DeadBolt Deep Dive: Building Execution Boundaries for AI Agent Tool Calls

When AI Agents can write files, call services, and send messages, a single wrong decision can turn into a real-world change. DeadBolt, launched by Next.11, is a free, open-source execution gate with a clear goal: a trusted dispatcher makes a deterministic ruling before the Agent's next protected action lands.

This article is based on the official walkthrough video and covers integration methods, policy controls, approval mechanisms, and real-world verification.

Why Execution Boundaries Are Needed

OpenAI's current Agent documentation recommends: place validation logic next to the tools that produce side effects. OWASP's excessive agency guidance proposes three engineering principles—least privilege, approval for high-impact actions, and authorization for every downstream request.

These are engineering reasons for establishing execution boundaries, but they are not a unified legal requirement. Specific obligations depend on your use case, contract terms, and jurisdiction.

DeadBolt provides only one link of deterministic control within this larger design. The official recommendation is explicit: combine it with other measures—narrowed tool sets, real service permissions, schema validation, and OS isolation that matches the runtime environment.

Excessive Agency is one of OWASP's core risk categories for LLM applications, referring to AI systems executing destructive actions beyond expectations due to excessive permissions, vague goals, or lack of constraints. Typical scenarios include an Agent autonomously calling payment APIs, deleting production data, or sending sensitive information externally. OWASP's mitigation directions include: limiting the tool set to the minimum necessary to complete the task, mandating human approval for high-impact operations, and performing independent authorization checks at every downstream service call point. Understanding this concept helps clarify DeadBolt's positioning—it is not a complete solution to excessive agency, but an engineering practice that peels the "authorization check" link away from the model side to the trusted dispatcher side.

Core Workflow: Model Proposes, Application Verifies

DeadBolt's execution model can be summarized as a chain:

• Model proposes work: The model can only propose invocation intent and does not hold execution authority.
• Trusted application verifies: The application validates parameters, assigns runtime identity and routed tool names.
• DeadBolt checks lease and policy: It makes a ruling against the current lease and policy.
• Dispatcher launches the function body only after an explicit allow: Any other result blocks the protected action.

Operators manage policies, approvals, and revocations through a separate control path. The official documentation repeatedly emphasizes one point: these control mechanisms must never be exposed as model tools. The dispatcher, database, operator credentials, and routes must all remain trusted—any caller that can bypass the gate or tamper with its storage is already outside the boundary.

It is important to clarify DeadBolt's capability boundaries: it is not an OS sandbox and cannot shut down frontier models. What it does is deny subsequent protected admissions, and it cannot cancel a tool function body that is already running.

Version Selection Determines the Integration Path

The official guidance is to determine the version first, then choose the integration example. The released version 1.0.3 supports the mature lease gate, native CLI, sidecar, and MCP proxy. The candidate examples add callback helpers, an installable pipeline, a Python client, optional SDK adapters, scoped credentials, and exact action approval—these have not yet entered the released archive package.

There are two installation paths:

• Native download: No Rust compiler required. Select the OS and processor architecture, verify the checksum, extract the archive, then run the version and drill commands.
• Source installation: Requires Rust and a platform C compiler or build tools, and the candidate version should be pinned to a fully reviewed commit.

As of this review, there are no available package releases on crates.io or PyPI; refer to the installation guide rather than assuming registry commands are available.

Quick Evaluation: Sidecar + Temporary File Dispatcher

The fastest evaluation path is a local sidecar with a temporary file dispatcher, requiring only the Python standard library and a native executable—no model account needed.

The evaluation script automatically performs: isolated state provisioning, policy configuration, attempting actions, and checking whether files actually exist. The script demonstrates several key behaviors:

• Writes that comply with policy execute successfully
• Tools outside the policy are rejected
• Irreversible actions require approval, and replay after one use is denied
• Parent revocation blocks registered children while unrelated runs continue
• Stopping the sidecar blocks the next action, and revocation state persists after restart

These 11 checks pass on both the released archive and the candidate binary. The official documentation explicitly states: they verify this dispatcher and do not constitute proof of isolation capability for any arbitrary Agent.

Sidecar is a deployment pattern: without modifying the main application process, auxiliary functionality runs as a separate process alongside the main process, communicating via local sockets or loopback network. In DeadBolt's context, the sidecar hosts the admission service, and the Agent host process requests rulings via Unix socket or authenticated loopback TCP, thereby decoupling the execution gate from Agent logic. The benefit of this design is that the gate's credentials, policies, and evidence storage are independent of the potentially untrusted workload process; even if the Agent is compromised, it cannot directly rewrite admission logic. The cost is additional process lifecycle management—when the sidecar is unavailable, it must fail closed, meaning deny rather than allow.

Rust Integration: Fail Closed Is the Bottom Line

In Rust, pull in the deadbolt crate from a release tag or a reviewed full revision. The package name is n11-deadbolt, and the library name is deadbolt.

When creating the gate, enable enforcement and set fail closed, using a private state directory. During trusted initialization, create the run lease and configure the actual tool policy.

The candidate version's dispatch helpers accept real callbacks, check immediately before invocation, preserve return values, and never call the callback on denial. Asynchronous dispatch checks when the future is pulled, not when it is constructed. The released API can also use the "manual admit followed by immediate function body execution" approach.

The official documentation gives two hard constraints:

• Protect every path that produces side effects; do not cache an allow for an entire session
• Do not consume one-shots on separate pre-checks

Sidecar and MCP Integration

The local sidecar exposes the admission interface via Unix socket or authenticated loopback TCP. The Python client uses only the standard library, and the Node client uses only built-in modules. The server and operator need matching database and evidence paths, as well as the dispatcher endpoint.

For STDIO-MCP integration, launch the server through DeadBolt's MCP proxy, and let the executor assign the agent identity. The proxy checks every routed tool invocation before forwarding, and operator controls always remain outside the server.

One notable detail: child processes do not inherit any DeadBolt bearer token. The candidate version limits frame and response sizes and handles child process termination and client disconnection. However, these checks do not cover arbitrary server startup, other MCP methods, or background work inside the server—the server implementation itself still needs protection and validation.

For existing hosts, the official recommendation is to start with a single narrowed tool route, first prove both allow and deny effects, then gradually expand coverage.

Optional SDK Adapter and Lease Semantics

The optional Python adapter protects real function tools in the tested OpenAI agent SDK: replace the function tool decorator on each side-effect function with a protected tool decorator. The SDK will still build schemas, validate parameters, and generate new function tool decorators.

The adapter does not create leases, grant operator approvals, or automatically protect hosted tools. It reports denials as typed causes through the SDK runner, so applications can display decisions without parsing prose. Acceptance for the installed wheel covers 19 cases, using the real runner and sidecar, without making provider requests.

There are several key points in lease semantics:

• A lease belongs to the agent identity, not to the vendor API key
• The default lease lifetime is 60 seconds, and a live admission (including ordinary denial) refreshes the sliding lease
• Silence lets the lease expire, and after expiration it does not slide
• Protected tool wrappers must not silently renew an expired identity

Action deadlines and admission credential deadlines are fixed and do not slide. These three lifetimes need to be tracked separately so that a specific workflow can be stopped without revoking the shared model key or interrupting unrelated actions.

Operator Controls: Pause / Clip / Kill

DeadBolt provides three control mechanisms:

• Pause: Temporarily block all protected admissions for a given agent
• Clip: Block a specific tool for that agent
• Kill: Revoke that agent and its registered descendants

Resume clears pause and clip and preserves the configured policy, but it cannot revive a kill. The selection logic is: use pause when investigation is needed, clip when a single capability needs to stop, and kill when a run must remain revoked.

There is an important limitation: controls issued after an action has already been admitted cannot revoke that action. Operators still need to prepare cancellation and recovery mechanisms in the application.

Policies: Tool Names, Targets, and Spend

Policies restrict three aspects: the tool names available to the agent, the reachable declared target tokens, and reported spend.

Unset lists remain open, so proactively configure narrowed policies. Tools outside the list are denied with purpose exceeded; external hosts are likewise denied. With a target list, network-type tools with missing hosts are denied, while local tools without targets are handled differently.

The official documentation specifically warns: target tokens must be derived from the route actually used by the function body. DeadBolt does not enforce DNS, redirects, or access hosts; it does not perform network socket or filesystem path jails.

Spend is reported by trusted infrastructure. This is not a billing meter or atomic purchase reservation; it simply stops subsequent protected admissions after a configured limit is crossed. Each child needs its own policy, configured during trusted initialization before dispatch.

Approval Mechanisms: One-Shot vs Exact Action

Existing irreversible tool policies require an operator one-shot: an unapproved attempt returns needs human, the operator approves a specific agent-tool pair, the next admitted call consumes that approval, and further attempts require a new review.

This mechanism is suitable when a trusted application controls side effects, but its scope is limited to the agent-tool pair; it is not bound to recipient, message text, amount, or other parameters. Do not describe it as "approval for an exact message."

When parameters determine sensitive outcomes, use the candidate version's exact action path. It binds together the executor's run, routed tool, target, validated JSON parameters, a unique nonce, and a fixed deadline. The review request must be prepared in trusted code, the review file must be protected, and the operator approves the reviewed fingerprint.

Version 1 fingerprints use SHA-256 (written in the original as HA-256) over a domain-separated RFC 8785 canonicalized JSON envelope, with explicit rules for objects, numbers, Unicode, and request size. Duplicate keys, unknown fields, illegal numbers, and oversized envelopes are all rejected. When amounts are involved, use safe integer minor units or decimal strings to avoid precision ambiguity.

One gap to watch for: the grant is automatically consumed with the primary SQLite evidence, but this does not equal exactly-once execution of the external effect. A crash or tool error may leave "completion status unknown" after consumption, requiring reconciliation of application results and downstream idempotency before seeking a new approval. Grant revocation also cannot cancel work already in progress.

RFC 8785 (JSON Canonicalization Scheme, JCS) defines a set of deterministic JSON serialization rules so that the same logical object produces byte-identical output across implementations. Its key conventions include: object keys sorted by UTF-16 code units, numbers using the ECMAScript shortest representation, strings escaped canonically, and NaN and Infinity forbidden. DeadBolt's exact action fingerprint is precisely SHA-256 over the domain-separated JCS-canonicalized JSON envelope, so what the reviewer approves is "the exact byte sequence of this set of parameters." Any parameter change alters the fingerprint and prevents reuse of the approval. This also explains why duplicate keys, unknown fields, illegal numbers, and oversized envelopes must be rejected—they would undermine the uniqueness premise of canonicalization.

Scoped Credentials and Lineage Revocation

The candidate version separates workload admission credentials from operator tokens: trusted initialization configures the lease and policy, then issues a private credential file with a fixed expiration for a given agent. The workload can request legacy or exact admission for that identity but cannot create agents, modify policies, view other agents, grant approvals, or report spend.

The practical recommendation is straightforward: remove operator tokens from the workload environment. SQLite stores credential hashes, and the bearer itself remains private; after the first credential issuance, socket access alone no longer grants anonymous permissions.

Regarding lineage, children must register under a parent before starting protective work, then explicitly configure their own policies. Registration only creates lineage; it does not copy the parent's tool or target restrictions. Killing a parent revokes registered descendants but does not revoke independent identities in the same store. The file evaluation demonstrates this behavior: a killed parent callback is blocked, child callbacks are blocked, and an unrelated agent continues writing normally.

Lineage in DeadBolt describes the parent-child derivation relationship between agent identities: a child agent must register with its parent before beginning protected work, forming a traceable genealogy tree. The registration action itself only establishes the relationship; it does not copy the parent's tool allowlist or target restrictions, and the child must explicitly configure its own policy. This design makes revocation transitive—Kill on a parent cascades to all registered descendants, while independent identities in the same store that are not registered under this tree remain unaffected. The value of lineage is that when a particular workflow is judged anomalous, the operator can cut off the entire derivation chain at once without having to locate each derived identity individually.

Evidence Chain: What It Proves and What It Does Not

DeadBolt records admission attempts and operator changes using SQLite and JSON lines. Observed facts and inferred conclusions are explicitly distinguished: content identifiers hash the recorded payload, and inferred rows reference their premises.

Incident Command can export an agent's decision history, current policy, revocation time, and registered children. But the official documentation explicitly draws the line: these records cannot identify who holds the token, cannot prove external operations completed, and cannot prove legal compliance. Generated narratives are not evidence rows.

The candidate version's action records contain metadata and fingerprints rather than raw parameters, but private review files still contain actual content, and export and retention policies need corresponding protection. The optional witness integration is an independent sink with its own failure boundary. These records are for investigation, after which they should be reconciled with application and provider evidence.

Fail Closed: Failure Must Not Become Permission

The dispatcher should run the function body only after a fresh, explicit allow. Sidecar unavailability, malformed responses, timeouts, or authentication failures must not become permission. Enforcement must be enabled and fail closed.

In testing, stopping the sidecar prevented file effects; after restart, killed identities remained preserved while unrelated leases remained valid. Database and evidence paths must remain consistent, using private state directories and local binding. The repository provides container and systemd guidance, but the target deployment still needs its own acceptance testing. SQLite backups need to be consistent, and recovery should be tested with dispatch stopped.

Candidate migrations add new tables. Older binaries will not enforce the new credential or exact action boundaries, so rollback requires a reviewed recovery plan. Primary SQLite transactions do not make JSON lines, witness, and external effects a global transaction.

Harness in Practice and a Real Integration Bug

The demo used an optimized Harness executable, copied outside the source checkout, with deadbolt and fail closed enabled and isolated state. A synthetic loopback provider proposed a normal file write, the Harness ran the protected tool, and the file appeared; before the next write, the operator killed the file, the Harness reported a killed denial, and the second file did not exist; another Harness agent successfully wrote its own file.

The output shown on screen came from real commands and tool results, with paths shortened for readability. This is a deterministic integration test and does not constitute an assertion about the behavior of any particular model. The Harness currently uses legacy admission and correctly rejects exact-only tools until a dedicated exact action adapter is connected.

This review found a meaningful integration bug: the Harness performed tool admission before waiting for human review and only checked stored kill or pause state after review. This means changed policies or expired leases could be missed, and a denied review could prematurely consume a one-shot. Four new regression cases failed against this behavior. After the fix, admission runs only once after review and before the registered function body or review content is written, and seven new regression cases cover these paths, including operator kill, clip write, approval preservation, and exact-only denial. 25 tests, 200 optimized suite cases, and all 15 remote checks passed.

Landing Recommendations

The official starting path is: first connect a single narrowed tool route in your application → choose either the released or reviewed candidate API → configure a private store, assign stable identities, and set useful policies → wrap real side-effect functions and test their allowed behavior → verify policy denial, operator revocation, expiration, approval replay, and gate failure (do not accept any hidden fallback) → add exact content review when parameters determine sensitive outcomes → add scoped credentials when the workload should not hold operator permissions → document which routes have been covered, and only expand scope after their effects have been checked.

DeadBolt is free and open under the Apache 2.0 license, and the gate itself does not require a model subscription. The guide, reproducible fixtures, source revision, subtitles, and evidence are provided with the walkthrough. The next step is a small, independently verified integration in your own system.

One-line Summary

DeadBolt is an open-source execution gate that makes deterministic admission rulings through a trusted dispatcher before Agent side effects land.

Paragraph Summary

DeadBolt is a free, open-source execution gate launched by Next.11 that peels admission rulings for Agent tool calls away from the model side to a trusted dispatcher, following the chain of "model proposes, application verifies, gate checks, execute only after explicit allow." It offers integration methods such as a native CLI, sidecar, and MCP proxy, and constrains side effects through three independent operator controls—Pause/Clip/Kill—plus leases, policies, one-shot approval, and the candidate version's exact action approval. The article emphasizes that DeadBolt is not an OS sandbox and cannot cancel a running tool function body, and that its evidence records cannot prove external operation completion or legal compliance. The official review also found and fixed a real integration bug in the Harness, moving admission to run after human review.