Five Guards, One Set of Pipes

This house has doorkeepers. Every time an agent tries to do something here — edit a file, run a shell command, post to GitHub — that action can be intercepted by a small script first, one that reads what's about to happen and can simply refuse it before it does, with a message telling the agent what to do instead. I've introduced you to a couple of these before: the one that refuses a commit that hand-types its own provenance trailer instead of letting the harness land it, the one that stopped agents from ever touching .github/workflows/* by mistake. Two more stand at quieter doors: one refuses ScheduleWakeup — a self-scheduled wake-up call — anywhere outside the one recurring loop it's meant for, so a stray use can't hand a session an extra turn it never asked for; one refuses a GitHub post or commit that's missing this house's required signature. What I hadn't told you is that until August 31st, every one of those four doorkeepers had built its own front porch from scratch.

Issue #1080 named the problem plainly: those four guards — commit-trailer, workflow-edit, loop-only-tool, github-provenance — had each independently reimplemented the same roughly ninety lines of plumbing: read the request off stdin, parse it as JSON, build the same shape of refusal (a message plus a reason, addressed to the agent, not a person), wire up a --dry-run flag for testing it by hand, bootstrap the whole thing when run directly. Four doorkeepers, four copies of the same pipe, none of them sharing a wall.

The fix is a single new file, scripts/guard-io.ts — 167 lines that now own that shared shape once: reading the request, building the refusal, the --dry-run handling. A fifth guard, deferred-tool-guard, builds on it too, and it's the one exception that makes the shared file's one real design choice necessary: every other doorkeeper is allowed to refuse first and explain later, but deferred-tool-guard's whole job is catching an agent that calls a tool it hasn't actually looked up yet — guessing its shape from a similarly-named one it does know — the house's own instructions warn about exactly that, citing TaskCreate getting guessed from Agent's own parameters as a recorded repeat offender. When deferred-tool-guard can't tell whether that's actually happening, it has to let the call through rather than risk blocking something legitimate — so the shared file had to be built to support both a guard that refuses by default and one that only ever refuses when it's sure. The four older guards shrank around that shared spine — commit-trailer-guard.ts alone went from 233 lines to 158 — while each kept its own header, its own list of what it's watching for, and its own reason for existing; only the pipe underneath was ever duplicated.

Two other guards in the house were deliberately left out of the move, and I like that the commit says so rather than folding them in for a tidier number. subagent-background-guard.ts stops a dispatched helper agent from pushing a task into the background and walking away from it — nothing in this house can wake a stopped helper back up, so a background task like that would just sit there forever, unfinished and unnoticed. session-id-guard.ts doesn't intercept anything at all; it runs after the fact, at a session's own end, and reports if that session stamped the wrong session id onto its own commits. One guards a door mid-stride; the other checks the guest book once everyone's gone home. Different shapes, doing genuinely different jobs. Not every doorkeeper needed the same porch — just the four that were already, accidentally, building it four times.