The Gate Between Agent Decision and Commit

Most agent setups give the model a tool named write_file or access to a shell session, then instruct it in the system prompt to obey architectural boundaries, avoid breaking changes, and check licenses. When the model drifts—hallucinating an internal API contract or silently modifying a root build configuration—the write executes immediately. The file on disk changes.

Governing the model at the prompt level is attempting to enforce runtime security in user space. The model is an unconstrained probabilistic engine. The correct posture treats every agent action as untrusted input. The control point is not the model's reasoning loop; it is the write path itself.

The Write Path as the Only Verifiable Boundary

When an agent decides to change code, that decision is purely speculative until it reaches storage. Placing governance inside the context window relies on prompt compliance. Placing governance at the storage interface relies on concrete invariants resolved in code.

Instead of exposing raw filesystem writes, place an intent gate between speculative output and disk. In this architecture, an agent does not call write primitives directly. It registers a Build Intent. A Build Intent is a structured proposal containing the target path, the proposed diff, declared dependency changes, and the interface contract.

Once registered, the gate resolves invariants in code before any byte touches disk:

• Path boundaries: Does this edit touch protected configurations, lockfiles, or files outside the agent's assigned scope?
• Licensing and supply chain: Are newly introduced packages permitted under licensing policy?
• Interface contracts: Does the proposed change break existing public type signatures or exported module contracts?

The gate evaluates the proposal against these checks and returns a terminal state. If the intent fails validation, the write aborts cleanly without leaving dirty state in your working tree. The agent receives machine-readable failure details, allowing it to re-plan against clear constraints.

Intercepting the Write at the Tool Layer

The same control point applies regardless of how the agent connects—whether through an MCP server, a plain HTTP API, or @shpbl/sdk. Unchecked write primitives like raw shell execution or direct file modification are replaced by the Build Intent gate.

A minimal intent payload isolates the mutation from execution:

{
  "intent_type": "file_mutation",
  "target": "src/auth/session.ts",
  "patch": "@@ -12,4 +12,6 @@ ...",
  "dependencies": { "jose": "^5.2.0" }
}

The gate inspects this payload against policy:

1. Target file src/auth/session.ts matches a protected path pattern, requiring verification against authentication boundary invariants.
2. Added dependency jose is checked against allowed license constraints before acceptance.
3. The abstract syntax tree is parsed to verify that exported type signatures remain intact across the patch boundary.

Previewing the proposed mutation costs nothing; materialising the resolved artifact requires entitlement. By moving verification out of the prompt and into the write path, the agent operates within hard boundaries enforced entirely outside the model.