Skip to content

Guard rails for AI coding agents

I assume agents will run the wrong command eventually and design for that, the way a machine builder assumes an operator will eventually reach into the cell.

Status: in daily use · checked Oct 26, 2026

In plain terms

An agent needs a written reason to run a destructive command, can't rewrite git history, and can't push without a two-step check. A separate check confirms each guard still works.

An agent that can run shell commands will eventually run the wrong one. So I make the wrong thing mechanically hard to do and check that each guard is doing something. Interlocks and error-proofing (poka-yoke) work the same way on a machine: they don't depend on the operator remembering. Recorded failures drive new guards, from blocked destructive commands to a two-step push confirmation, and separate checks catch any guard that goes missing or any commit that weakens one.

What an agent cannot do

Before building the remote dispatch and deploy paths I recorded what an agent must be unable to do, as design locks. Stated as limits on the agent, not as advice to it:

An agent can't Because
approve its own change the review result can be posted by one dedicated identity only, and the posting step refuses to run inside a worker
push without a checkpoint pushes require the scoped approval and checklist path: a two-step handshake that a human confirms for interactive pushes, and an authorized courier may auto-confirm within its declared scope
apply a change to the network surface agents draft and run a dry-run diff; a person approves it in the session
deploy to live systems unattended a deploy is two calls, and an unattended agent is allowed the first only
sign its own dispatches signing happens in one place and workers can only verify
widen its own tool access each host has a ceiling on what a worker may run, a task can only narrow it, and a request outside the list is rejected
run agentic work on a host that was not granted it the grant is per host, declared explicitly and denied by default
act without leaving a record every dispatch writes an audit entry, and setup fails closed if the audit location is missing
work in a project that has no guard policy a missing policy is a failure of the health check, and the default is to enforce

These are the locks I recorded; how agent output is trusted says which parts are running. One of them was tested against the code and amended (selected design decisions).

Levels of enforcement

Rules are recorded at the level that actually backs them, and pages say which:

Level Backed by What it means
Comment a code comment the author knew; nothing else did
Document a document or task item a human has to remember
Rule an always-loaded rule the agent reads every session an agent probably follows it
Guard a mechanical guard: hook, gate, test the action is intercepted, whoever forgot

The failure this exists to prevent is a silent document level: a runbook confidently prescribes a manual step, the reader assumes something would catch a mistake, and nothing does. So runbooks carry a one-line enforcement stamp, and a claim of "guard" must name the guard, which makes the claim checkable with a search.

The guards

The guards have a few documented exceptions.

flowchart LR T[Tool call] --> H[Hooks] --> B[Commit backstops] --> PU[Push gate] --> PR[PR checks] --> MC[Independent review]:::guard
flowchart TD T[Tool call] --> H[Hooks] --> B[Commit backstops] --> PU[Push gate] --> PR[PR checks] --> MC[Independent review]:::guard
Guard Stops Type
Subagent redirect expensive model fan-out for read-only work tool-call hook, fails closed
Risky-command guard destructive commands with no written reason tool-call hook; a written justification is required
Destructive-command guard recursive deletes, remote-exec heredocs tool-call hook
Git-clobber guard history-destroying operations tool-call hook
Managed-file guard hand edits to generated or rendered files (which the next render would silently revert) tool-call hook
Primary-checkout backstop commits in the shared checkout git pre-commit hook; refuses even if the tool-call hook was bypassed
Secret scan secrets entering history pre-commit; a hit means stop and rotate, not delete-and-retry
Doc-freshness ratchet stale or unstamped documentation pre-commit and CI (see Documentation that stays true)
Push gate code leaving the machine without a checkpoint mint token, then checklist, then confirm
Independent review merging without the independent reviewer required status check in the main repositories, posted only by a dedicated reviewer identity (see How agent output is trusted)

These properties matter more than any single guard:

  • Defense in depth. The pre-commit backstop exists because a tool-call hook can be bypassed; the primary-checkout rule is enforced at both layers.
  • Fail closed where the cost of a miss is high. When a guard can't evaluate a call, it denies.

Fail closed, because of a guard that allowed everything

One of the git guards once silently allowed every call: a helper module failed to import, the guard crashed, and a crash read as "no objection". Guards now fail closed: if a guard script is missing or can't run, the call is blocked. The full case is in Incidents and the fixes they produced.

Guards are checked to be alive

A guard that reports "OK" while inspecting nothing is worse than no guard. These keep that from happening.

  • A liveness probe checks that every registered guard script exists, parses and imports, so a guard that has gone missing or broken shows up.
  • A refusal journal records real blocks, so there is evidence that guards refuse things in practice, outside the tests as well.
  • Non-vacuity proofs. A guard ships with test cases that plant a violation and require a refusal (missing stamp, fail; a guard claim without a named guard, fail; a correct claim, pass), so a guard that stops looking fails its own test. The case that taught this is in Incidents and the fixes they produced. The general rule: a guard isn't done until you have watched it refuse something.

Guards for the guards close the loop. Separate checks fail a commit that adds a guard without registering it, or that removes or weakens a hook without a written reason. That is the ratchet: additions are free, and removals have to be explained.

Reversibility for hard-to-undo changes

A deadman timer is required before a hard-to-reverse change: a self-canceling rollback. If the change completes and the system is healthy, it is disarmed; if the change fails half-way, or the session dies, the rollback fires by itself. It turns "hope I can get back in" into a bounded, automatic recovery.