Narrower than your grants
An agent with a boundary and a tool allowlist is constrained but not directed. It can stay perfectly inside its standing permissions while doing something entirely unrelated to the job it was approved for. Every individual call is legitimate; the run as a whole is not the run anybody authorised.
That gap is the difference between a boundary and a mission. The Scope Contract closes it with a per-task object, derived at approval, narrower than the agent's general grants, and consulted on every call.
interface ScopeContract {
taskId, proposer,
allowedTools, // D1 — a subset of the agent's tools
pathScope, // D2 — directory roots this task may touch
allowedCommands, // D3 — exact command strings
budget, // D4 — max in-scope calls
planHash, // binds the approved plan
hash, // the seal over everything above
frozen, used, inputs // runtime state, deliberately outside the seal
}
What the seal covers, and what it must not
Seven fields are sealed. Four are not, and the split is the most considered decision in the module.
function seal(c) {
const canon = JSON.stringify({
taskId: c.taskId, proposer: c.proposer,
allowedTools: [...c.allowedTools].sort(),
pathScope: [...c.pathScope].sort(),
allowedCommands: [...c.allowedCommands].sort(),
budget: c.budget ?? {}, planHash: c.planHash,
});
return sha256(canon);
}
Field order comes from the literal rather than the caller's object, and arrays are sorted on copies — so reordering a tool list does not break the seal, while adding to it does. The stored arrays keep their insertion order; only the hashed view is canonical.
The unsealed fields are used (the call meter) and inputs (file stamps taken at pick-time). Sealing them would be a category error. The seal's job is to make the authority grant immutable for the life of the task, and the grant is fixed at approval. The meter and the stamps are observations that legitimately change afterwards.
More sharply: if stamping an input had to re-seal the contract, then a method taking no actor at all would become a mutation path for a sealed object — and the proposer-is-not-approver guarantee would be routed around by the back door. Sealing observations would have destroyed the meaning of the seal.
Four deviation classes, checked in a deliberate order
The gate returns the first deviation, in the order D1 → D3 → D2 → D4 — not numeric order, because path canonicalisation is the expensive check and there is no reason to pay for it when a cheaper one already refuses.
Two preconditions run before any of them: no contract for a claimed task id is a fail-closed refusal, and a contract whose recomputed seal does not match its stored hash is scope-contract-tampered — the only refusal in the module that carries no deviation class, because tampering is not a deviation, it is a different kind of problem.
D1, tool. Exact string membership. No globs, no prefixes, no namespace matching. A task approved to read files cannot invoke a write tool even though the agent holds it.
D3, command. The gate extracts a command descriptor from the call's input — command, cmd, template, or the first element of argv — and requires exact membership in the task's list. Byte-exact: 'npm test' is not 'npm test'.
D2, path. Every declared path parameter must sit at or under a root in the task's scope, using the same case-folding, Unicode-normalising containment check the boundary engine uses.
D4, budget. Prospective: the call that would exceed the ceiling is refused, then an admitted call advances the meter. An absent budget means unlimited.
One structural consequence worth naming. Exec tools declare no path parameters — correctly, since their argument is a command rather than a path — so paths embedded in a shell string never reach D2. For exec, D3 is the only thing standing in front of the call. That is why D3 exists as its own class rather than being folded into D1.
The one place derivation tightens
Nobody hand-authors a contract. The issuer derives one from what governance already knows:
- D1 mirrors the agent's declared tools — or, if it declared none, every registered tool, because you cannot narrow what was never declared.
- D2 mirrors the union of the run's write and visibility roots.
- D4 mirrors a configured default, or unlimited.
- D3 mirrors nothing, because there is nothing to mirror.
There is no "allowed commands" field on an agent definition anywhere in the system. So derivation has only two options — all commands or none — and it chooses none:
The effect is that an auto-derived contract permits ordinary work and still withholds un-named commands. A task can read and write inside its boundary without anyone authoring anything; the moment it wants to run rm -rf ./build, that string has to have been named at approval.
Deriving rather than authoring is what makes the control adoptable. A contract nobody has to write is a contract that actually exists on every task.
Amendment is about who, not about direction
A contract is not immutable in the absolute sense — a task's scope legitimately changes. It is immutable to the agent. Amendment requires an actor in the approver set, and that actor must not be the contract's proposer. Both checks audit the refusal before throwing, so a rejected amendment is still evidence.
Because the proposer is a sealed field and is deliberately absent from the patch type, the separation-of-duties check cannot be moved by the patch it is guarding.
This is the repo's reference implementation of proposer-is-not-approver; the wiki's dual-control gate cites it by file and line. And note what the control is not: nothing requires an amendment to narrow. An approver may widen the tool list or raise the budget. The control is on who, not on which direction.
Why it shipped correct and unused for months
This is the part worth the whole article.
The module was written, sealed, metered, tested — seven green conformance tests — and wired to nothing. An external review found it, and the site had been describing non-deviation as a live control for months.
The reason it was never switched on is the interesting bit, and it is not negligence. The gate fails closed when a task has no contract, and nothing issued contracts. Turning it on would have denied every call in the system. The missing piece was an issuer, not a flag.
That is a specific and under-appreciated failure mode: a correct fail-closed control whose enabling precondition does not exist yet is unshippable, and the pressure is to leave it dark rather than build the boring half. The boring half was 147 lines.
The fix also had to solve an applicability problem. A naive rollout would require a contract for every call — which conflates non-deviation with "no task, no tool", a different control that already exists. So there are three modes, and the middle one is the design:
| off | the gate is not consulted at all — exact pre-enforcement behaviour |
| contracted | a call claiming a task id must have a contract; a call with no task id has no mission to deviate from and falls through to standing grants, boundary and floors |
| strict | additionally requires a task id on every call |
Conflating the middle row with task-binding would have made non-deviation impossible to enable without also mandating task ids everywhere, which is a much larger change to force on an adopter.
Two further details that turned out to be load-bearing. Issuance is idempotent — a replayed approval after a restart returns the existing contract rather than throwing, so recovery does not fail the task. And contracts persist and restore, because without that an in-flight task comes back contract-less and has every call denied: the gate would look broken rather than fail-safe. The state file shares the corrupt-versus-absent discipline used everywhere else — absent restores empty, unparseable enters safe mode.
Time-of-check to time-of-use
A file a task picks can change before the task uses it. A shared drive, a cloud sync, or an attacker swapping it. So inputs are stamped when picked — content hash plus size and mtime — and re-verified at use, with a changed hash treated as a deviation rather than as trusted input.
One implementation detail is worth stealing. The content hash reads the file as latin1, not utf8, because latin1 maps each byte to exactly one code unit. Hashing as UTF-8 would collapse every invalid byte sequence onto the replacement character and make distinct binary files hash identically. One word, and it is the difference between a binary-safe stamp and a broken one.
Honest limits
The gate meters on a clean scope verdict, and the scope check runs early — before boundary containment, before the secret gates, before risk and policy. So a call that clears scope and is then denied downstream has still consumed budget. The accurate description is "budget counts attempts that cleared scope", not "actions that happened". For a rate limit that is defensible; for anything described as a task's spend it would not be.
The path check resolves but does not follow symlinks — the outer boundary engine does that, so this is defence in depth rather than a hole, but the scope layer alone does not canonicalise links.
The command extractor reads the first matching parameter name and, for array forms, only the first element. A tool whose command parameter is named something else entirely would not be seen by D3 at all, though it would still have to pass D1.
And amendment records that a change happened, by whom, but not what changed. Reconstructing a contract's history from the audit chain tells you there were three amendments and who approved them; it does not tell you what any of them did.
None of that undermines the control. It does mean the honest claim is narrower than "the agent cannot deviate": the agent cannot use a tool, path or command outside what was approved for this task, and cannot widen that set itself. That is a real and unusual guarantee, and it is not the same as a guarantee about intent.