Rules That Run is a ten-part series on the rules that keep an AI agent setup honest. This is part 3.
Parts 1 and 2 each ended with a hook or a wrapper doing the work a sentence in an instruction file used to do. This part is about the general method, because I now use it for almost every rule that matters: write the rule in plain words first, then wire it into the harness so it runs whether the model remembers it or not, then keep a count of every time someone walks around it.
Why a sentence is not enough
An instruction file is read at the start of a session and then competes with everything else in context. Early in a session the agent follows it well. Late in a long session, after a compaction, or in a subagent that never loaded it, the same rule gets weaker. A line like "run the type checker and tests before committing" is exactly the kind of rule that fades this way.
A hook does not have that problem. Claude Code runs it on a named event, such as before a tool call or when the agent tries to stop, and the hook's answer is binding. If a PreToolUse hook denies a commit, the commit does not happen, and the model gets the reason as feedback.
So the method has four parts: the rule in words, the hook that enforces it, an override for the cases the rule did not foresee, and a log of every decision.
The gate with a logged override
The first gate I built was the commit gate. Before any git commit, it runs the typecheck and the test suite. If either fails, it denies the commit with the failing output as the reason.
Every gate needs a way out. Sometimes the test suite is broken for a reason unrelated to the change, or the commit is a docs-only fix in a repo whose tests take minutes. If there is no override, people learn to work around the gate in worse ways, such as committing from a different shell. So each gate has an override: an environment variable set for a single command. Every use writes a log row.
// ~/.claude/hooks/commit-gate.mjs (PreToolUse, matcher: "Bash")
import fs from 'node:fs';
const input = JSON.parse(fs.readFileSync(0, 'utf8'));
const cmd = input.tool_input?.command ?? '';
if (!/\bgit\s+commit\b/.test(cmd)) process.exit(0);
if (/\bGATE_OVERRIDE=1\b/.test(cmd)) {
logDecision({ gate: 'commit', decision: 'override', cmd });
process.exit(0);
}
const result = runChecks(input.cwd); // typecheck + test suite
if (result.ok) {
logDecision({ gate: 'commit', decision: 'pass' });
process.exit(0);
}
logDecision({ gate: 'commit', decision: 'block', why: result.summary });
process.stdout.write(JSON.stringify({
hookSpecificOutput: {
hookEventName: 'PreToolUse',
permissionDecision: 'deny',
permissionDecisionReason: `Checks failed:\n${result.summary}`,
},
}));
The override lives in the command itself, so it is visible in the transcript, and the log row records the full command.
What the log says
All of my gates write to one log. As of November 18, 2026, it held about 20,300 rows, going back to June 2026.
The commit gate has been logging since July 16, 2026. Over that time it recorded 3,352 passes, 198 blocks and 127 overrides.
The honest reading of those numbers is uncomfortable. 127 overrides against 198 blocks means the way out gets used a lot. An override can be the right call, for a known-broken test or a commit with no code in it. It can also be the agent, or me, deciding the gate was in the way. The log cannot tell those apart by itself. What it can do is make the rate visible, and that is why overrides are counted at all.
The second gate shows a different pattern. The file-authoring gate blocks writing files through shell heredocs, because the shell tool in my setup silently strips one level of backslashes, so a heredoc can write a file whose contents differ from what the agent typed, with exit code zero. The gate denies the heredoc and tells the agent to use the file-writing tool instead. As of November 18, 2026 it had logged 2,619 denials and 68 overrides. Here the override is rare and the rule mostly just redirects the agent to the right tool, which is what a gate should do.
Counting bypasses
A gate with an override can decay quietly. Each override looks reasonable in the moment. Under deadline pressure, the reasons get thinner and the overrides get more frequent, and nobody notices because each one was logged and the log was never read.
I took that concern from research on safety gates, which found that bypasses rise silently under pressure unless somebody counts them. So the log is read on a schedule. A weekly job computes, for each gate, overrides as a share of all its decisions that week. It flags any gate where overrides exceed 20% of decisions in a week, or where the rate rises week over week.
// weekly bypass report (sketch)
for (const [gate, rows] of byGate(lastWeek)) {
const overrides = rows.filter(r => r.decision === 'override').length;
const rate = overrides / rows.length;
if (rate > 0.20 || rate > previousRate(gate)) flag(gate, rate);
}
A flag means one of two things. Either the rule is wrong for some common case and should change, or people are walking past a rule that is right. Both need a person to look, and the report is what puts the gate in front of a person.
One process, many hooks
As the gates multiplied, the hooks themselves became a cost. Claude Code runs each configured command hook as its own process. With my set of Node hooks, a single tool call was spawning around nine processes before anything happened. That is slow, and on a busy machine it is noticeable on every step.
The fix is a dispatcher. Settings register one command per event, the dispatcher, and pass it the list of hooks to run. The dispatcher loads each hook in a worker thread inside one process, feeds each the same input, and merges the answers.
The merge rule is strict: deny beats ask, and ask beats allow. If any hook denies, the call is denied, and the reasons are joined so the model sees all of them.
The failure rule is the opposite of strict. A hook that crashes, or does not answer within its timeout (10 seconds by default), counts as having no opinion. The dispatcher fails open and logs the failure. I chose this on purpose. A bug in one hook should not freeze every tool call in every session, and the log makes a crashing hook visible the same day.
{
"hooks": {
"PreToolUse": [
{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "node ~/.claude/hooks/dispatch.mjs commit-gate.mjs@Bash heredoc-gate.mjs@Bash agent-budget.mjs@Agent"
}]
}
]
}
}
Failing open has a cost. For the short time a gate is broken, its rule is back to being a sentence in a file. I accept that because the alternative, a crashed gate that blocks everything, gets turned off entirely, and then the rule is gone for good.
Writing the rule first
The order in the title matters. I still write every rule in words before I wire it, and the words stay in the instruction file next to the name of the hook that enforces them. The words are what the agent reads to understand why it was denied. The hook is what makes the words hold. A hook with no written rule produces denials nobody can explain, and a written rule with no hook produces the drift I started this series with.
Build it yourself
- Pick one rule the agent breaks often enough that you have noticed. Write it in one sentence.
- Write a PreToolUse hook that detects the action and denies it with a reason that says what to do instead.
- Add an override as a per-command environment variable, and log every use.
- Send every gate's decisions to one append-only log with the gate name, decision and command.
- Run a weekly job that computes overrides as a share of decisions per gate and flags high or rising rates.
- When you have more than a few hooks per event, run them through one dispatcher with deny over ask over allow.
- Give each hook a timeout and fail open on crash or timeout, with a log row each time.