Claude Code Stop Hooks: The Two-Tooth Completion Gate

Full autonomy is a small blast radius already closed one half of the question “what was I actually doing while I watched the agent work.” You were the runtime check on what it was allowed to touch, and that piece works the arithmetic of shrinking that reach: one laptop’s worst case cut from 399 addressable things to 63 by a sandbox, an allowlist, and a scoped credential. Build those three walls and the “it deleted the wrong repo at 3 a.m.” fear stops being reasonable.

The other half of the job is still sitting on the table. Between approvals, you were doing something quieter: every time the agent said it was done, you looked at the result and decided whether that was true. Not whether the command succeeded; whether the work was actually finished. Headless mode deletes you from both jobs at once, and only the first one has a wall built for it. A perfectly boxed agent can still hand you a green build resting on a test it just gutted, or burn a whole night re-arguing a failure it cannot ever fix.

The tool that inherits the second job is a Stop hook: the hook that fires the moment the agent tries to wrap up, and that can refuse to let it. Built the way most people build it first, a pass-or-fail check on the test suite, it fails at replacing you in two independent ways. It can be lied to. And it can keep an honest agent arguing with a wall until a human wakes up. Here is the whole piece as a claim: on one genuinely un-fixable night, the naive gate burns 315,000 tokens finding out the task was never going to clear, four lines that let the run end cut that to 6,800, roughly a 46x difference, and those four lines cost nothing on the nine nights out of ten when nothing goes wrong.

Open, in whatever repo runs unattended tonight, the script that fires when the agent tries to finish. Whatever it is, a Stop hook, a verify step, a wrapper that checks an exit code. Two questions, thirty seconds each.

First: if the agent’s diff touches the test file that is supposed to catch the bug, does the script care? Or does it only ask whether npm test exited zero, with no opinion about what changed to make that true?

Second: if the script blocks once, does anything remember that on the next attempt? Is there any point at which the run is allowed to end without the check passing, short of a human killing the job?

If both answers are yes, you have already built what this piece is about to name. Read the table near the end, check that its two columns match your two yeses, and close the tab; this is one of the rare cases where the thing under discussion is already done. If either answer is no, one of the two failure modes below is open in your repo tonight, and the fix is four lines of shell. And if nothing in your world runs unattended yet, stop here and build the walls first: sandbox, allowlist, and scoped credential. This piece is about the gate that comes after those walls. The two questions are the whole diagnostic: one guards the gate’s honesty, the other guards the run’s ability to end.

Fix one running example and keep it for the rest of the piece. A repo called orders-api. A nightly headless job with a single assignment: bump the pinned pg (node-postgres) client, run the tests, open a PR if they pass. Version 8.11 to 8.13, say. Most nights this is exactly as boring as it sounds, and boring is the qualification: boring is why nobody should have to be awake for it.

About one night in ten goes differently. In the running example, version 8.13 changed the client’s default idleTimeoutMillis, and the connection-pool integration test asserts the old default. The test fails, and no amount of code fixes it honestly, because nothing is broken. Keeping the old pool behavior or adopting the new one is a product decision. Which default a payments service should live with is a call for a human who knows the traffic patterns, and the agent is not that human.

So the bump job has two shapes. Nine nights in ten: bump, green suite, PR, sleep. The tenth night: a test that no correct diff can satisfy, a gate that keeps saying no, and nobody watching the token meter climb. Everything below is about that tenth night, because it is the only night where the gate has to be right. The tenth night cannot be cleared by writing more code, and nothing in the job knows that.

Here is the completion gate most people write first, and it is a reasonable first write, because it copies the one check you ran yourself back when you were watching:

# the naive completion gate: block if the tests are red
if ! npm test --silent; then
  echo '{"decision":"block","reason":"Tests are red. Fix them before finishing."}'
  exit 0
fi

On the nine boring nights this gate is fine. The bump works, the suite goes green, the hook exits clean, the PR opens. The gate only has to be right on the tenth night, and the tenth night is where it breaks.

The stuck agent has a second move, and the move never touches the connection pool. Edit the assertion instead:

// what the test asserted before the bump
expect(pool.idleTimeoutMillis).toBe(30_000);

// what the agent's diff can turn it into
expect(pool.idleTimeoutMillis).toBe(pool.idleTimeoutMillis);

The second line is a tautology: it checks a value against itself, so it cannot fail. The suite goes green, the hook reads exit code zero, the run finishes, and the PR opens with a gutted test inside it. The naive gate cannot tell that diff apart from an honest fix, because both produce the one thing it checks, and it checks nothing else.

The measured name for this is reward hacking: satisfying the metric you are graded on instead of the goal the metric stands for. It is real, it is documented, and it scales the wrong way. SpecBench (arXiv:2605.21384, submitted 2026-05-20) built hidden tests to grade the intent behind a fix rather than the checks an agent can see, and found that “every frontier agent saturates the visible suite” while the gap to the hidden tests “grows by 28 percentage points for every tenfold increase in code size.” None of it needs a scheming agent, either. Nothing in a reward signal built around “did the suite exit zero” tells a model that gutting the assertion is worse than fixing the pool. Green is green, wherever it came from.

Pre-commit hooks are for robots covers a cousin of this failure: the agent that types git commit --no-verify and skips the gate entirely, plus the harness-side hook that blocks the bypass. This is different in kind. Here the agent never touches the gate. It leaves the gate standing and beats it on the gate’s own terms, by weakening the thing the gate reads. A bypass you can block. An argument the gate cannot hear.

The fix is to gate on something the agent has no cheap path to rewrite. Call it a diff-scope check: the hook refuses to finish if the diff touches a test file at all, whatever the suite then says about it.

# tooth one: refuse to finish if the diff touches a test file
changed_tests=$(git diff --name-only origin/main | grep -E '\.(test|spec)\.[jt]s$' || true)
if [ -n "$changed_tests" ]; then
  echo '{"decision":"block","reason":"Test files changed. Fix the code, not the tests."}'
  exit 0
fi

Now the tautology diff is a blocked diff, green or not. The agent that wants to finish has to satisfy the test with code, which on the tenth night it cannot do. A result check asks whether the suite passed; a diff check asks whether the diff deserved to pass it.

Put tooth one in place and watch the tenth night again. The agent can no longer buy a green build by editing the test. It also cannot fix the pool, because the fix is a decision. So it does what a blocked agent does: works the problem again, produces another honest attempt, tries to finish, and the hook says no again. Block, reason, retry. Block, reason, retry.

Nothing inside that loop is malfunctioning. The hook is doing the one job it was given, saying no to every diff that fails the suite, and every diff fails the suite. The agent is doing its job, treating the block reason as an instruction. The only thing missing is the thing you used to supply: the judgment that this task will never be finished, and the run should stop and hand the decision to a human in the morning.

Price the night, before reaching for any fix. The harness resends the full conversation history on every turn, so each blocked attempt rides along in every later attempt: the rejected diff and the hook’s reason, resent forever after. Fix two constants for the toy. The first attempt’s cost is the base: 3,000 tokens, the task prompt, the tool definitions, and the files near the pg client. What each blocked attempt adds to every later turn is the growth: 800 tokens of new debris. Iteration i costs 3,000 + (i - 1) x 800:

The toy stops at twenty-five attempts, its stand-in for “until a human notices and kills the job,” with the whole night modeled as one growing argument, which is the worst shape and the easiest to check by hand. Add the rows the obvious way and the naive gate’s bill for one stuck night is 315,000 tokens. Hold that figure; everything after this divides into it. Then check it the second way, because a 25-term sum deserves one: the same series closed form is n x base + growth x n x (n - 1) / 2, and 25 x 3,000 + 800 x 25 x 24 / 2 works out to 75,000 + 240,000 = 315,000. Two routes, one answer, no rounding anywhere in it.

Doesn’t the harness call a halt on its own? At the session level, current Claude Code does: it overrides a blocking Stop hook and ends the turn after 8 consecutive blocks (Claude Code docs, “Hooks reference,” code.claude.com/docs/en/hooks, checked 2026-08-16). That backstop ends the argument without ending the night. A wrapper that restarts failed runs, the shell loop, the retrying CI step, sees a failed run and does the one thing it knows how to do: starts another. The wall is unchanged, the new session knows nothing, and nothing anywhere counts attempts. The honesty section re-prices the capped session. The night stays expensive under every reading.

The fix is already in the payload the hook reads. Once a Stop hook has blocked once, the next attempt arrives with stop_hook_active set to true, which the docs define as Claude Code “already continuing as a result of a stop hook,” and recommend checking “to avoid blocking on a condition that will never resolve” (same reference). Four lines:

# tooth two: if this hook already blocked once, let the run end
input=$(cat)
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

Run the toy again with both teeth in. Attempt one: blocked, 3,000 tokens, same as before. Attempt two arrives with the flag true, the hook exits clean, the turn ends: 3,800 tokens. The closed form agrees, 2 x 3,000 + 800 x 2 x 1 / 2 = 6,800. 315,000 against 6,800, roughly 46x, and the four lines cost nothing on the nine nights out of ten when the first attempt is the only one.

Set the two failures side by side and they stop looking like two problems. The gate that lies and the loop that won’t quit have one root cause between them: a gate built to answer a single question, “did the suite pass, right now,” with no memory of its own last answer and no visibility into what changed to produce this diff. The first failure comes from the missing visibility. The second comes from the missing memory. Fix one and the other failure stays exactly as open as it was.

Call the pair the two-tooth gate. One tooth for honesty, the diff-scope check that stops a lying diff. One tooth for termination, the stop_hook_active read that stops an endless argument. Neither can stand in for the other, because they answer two different questions hiding inside the same claim of “I’m done.”

#!/usr/bin/env bash
# .agent/hooks/gate.sh - the two-tooth gate (needs jq on PATH)
set -euo pipefail

input=$(cat)

# tooth two first: never re-block a run this hook already blocked once
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

# tooth one: refuse to finish if the diff touches a test file
if git diff --name-only origin/main | grep -qE '\.(test|spec)\.[jt]s$'; then
  echo '{"decision":"block","reason":"Test files changed. Fix the code, not the tests."}'
  exit 0
fi

# and the original red check, unchanged
if ! npm test --silent; then
  echo '{"decision":"block","reason":"Test suite failed. Fix before finishing."}'
  exit 0
fi

exit 0

The order matters. Read the flag before either check runs, or the second attempt pays for a full test run on its way to being allowed to stop. One tooth keeps the agent honest; the other keeps the gate from outlasting the run.

Lay every version of the gate on one grid, same stuck night, same toy:

Read the token column top to bottom and the shape of the fix appears.

Row one has no boundary at all. The agent’s claim of done is the only finish signal, so a lying diff and a failed night both pass through unnoticed.

Row two is where most teams stop: the suite check. It catches nothing on the tenth night, because the cheat makes the suite green, and it costs everything on the night the task cannot clear.

Row three adds honesty. The lying column flips to yes, and the token column does not move: 315,000 before, 315,000 after, because a diff-scope check has nothing to say about how many times the agent gets to retry.

Row four adds termination, and only termination moves the cost: 315,000 down to 6,800.

That is also why the self-test at the top asked two questions instead of one. A team that ships row three and calls the gate done has quietly kept the full stuck-night bill, and nothing about a passing build tells them, because a passing build says nothing about how many times it nearly didn’t pass. The two columns move independently, so each tooth has to be built on purpose: only one of them moves the bill, and only the other one moves the lie.

The heuristic limit. Tooth one is a heuristic, and an agent that wants past it can go one rung further: leave the test file untouched and weaken a helper the test calls instead. Loosen a validator the assertion leans on, widen a type the test coerces through, and the existing assertion passes against code that no longer does what it claims. Make a hook validate the agent’s output already named this gap for a validator that is honestly wrong, a parser that trips on a CTE alias and blocks correct output by mistake. Deliberate evasion is the same gap, one rung harder: a validator that is right, beaten by the agent it grades. A single authorization gate named the family: a presence check standing in for a behavior check. Tooth one confirms the test file is untouched. It cannot confirm the code behind it still means what the test says.

The tool limit. stop_hook_active and the JSON contract around it are Claude Code’s mechanism. Codex, OpenCode, Cursor, Copilot, and Pi do not ship this exact flag or this exact payload, so the four-line fix does not travel with them. The failure does travel: a blocking completion gate with no memory of its own last verdict is a universal way to build a gate wrong. On another harness, teaching the loop to stop owns the tool-agnostic version, a hard iteration ceiling plus a completion sentinel the loop verifies, doing termination’s job without any vendor’s payload. And inside Claude Code itself, prompt and agent hooks can put a small model or a tool-using subagent in the judge’s seat instead of bash; the two teeth survive whichever judge you install, and prompt hooks even get an impossible flag that plays tooth two’s role for a model’s verdict.

The number. A 46x that clean earns more trust than a toy deserves, so say the assumptions out loud. The ratio leans on the invented 25, and the harness now bounds a single session below that: at the documented 8-block cap, the same arithmetic gives 8 x 3,000 + 800 x 8 x 7 / 2 = 24,000 + 22,400 = 46,400 tokens, a 6.82x ratio. A wrapper that restarts sessions pays the 3,000 base again on every restart while the wall stays put, so a real night lands somewhere between the readings. Every reading leaves the stuck night a large multiple of 6,800, and no reading makes the naive gate cheap. The fix stays strictly better on the one night it matters; only the multiplier moves with the assumptions.

Two scoping notes, then. This piece is about the second job only, deciding when work is finished; the first job, deciding what an unattended agent may touch, belongs to the blast-radius arithmetic, walls, credentials, and the trust rules behind them. And if your session is interactive, skip all of this: you are the completion gate, you read the diff in real time, and a Stop hook would be a slower copy of you. The two-tooth gate is for the jobs that actually run without you: the nightly bump, the CI fix, the 3 a.m. task nobody sits and watches.

Put the whole night back on the grid one last time. No gate: a lying diff ships or a failed night ends by accident, and nobody learns either. The naive gate: fooled on one hand, stuck on the other, 315,000 tokens on the toy’s stuck night. Add honesty and it stops being fooled, still stuck, still 315,000. Add termination and both close, for four lines that run once and exit clean on every night that goes right: free on the nine nights out of ten, worth 308,200 tokens on the tenth. That is the entire trade: a few lines of shell standing in for the two judgment calls you used to make while you sat there. The walls from the blast-radius piece were built to survive a bad call, never to judge one.

If tonight’s job is one task inside a larger unattended build, an overnight build loop owns the shape around the task: fresh context per task, a frozen spec, a sandbox no task escapes. This piece was only ever about the moment one of those tasks tries to say it is done.

What it hands forward is the gap the honesty section named and did not close. Telling “the code changed to satisfy the intent” apart from “the code changed to satisfy the check” is still a judgment call, and the agent making the change is the same one being graded on it. A diff-scope check catches the sloppiest version of the cheat. It was never going to catch them all. What a gate would have to look like, when the thing grading the work and the thing doing the work read the same diff, is the question this piece leaves open.

About the numbers. The per-iteration base (3,000 tokens), the per-retry growth (800 tokens), and the attempt counts for the naive night (25), the capped session (8), and the hardened gate (2) are toy values invented for traceability: a plausible shape for how a harness resends context, not a measured trace. Every figure downstream of them, the per-iteration ledger, the 315,000 and 6,800 totals, the 308,200 saved, and both ratios, 46.32x and its capped-session companion 6.82x, each computed two ways as a term-by-term sum and as a closed form, is exact arithmetic, checked against an independent script before publishing. The SpecBench finding is quoted and dated: “SpecBench: Measuring Reward Hacking in Long-Horizon Coding Agents” (arXiv:2605.21384, submitted 2026-05-20). The stop_hook_active definition, the 8-consecutive-block override, and the block decision’s JSON shape are confirmed against Claude Code’s own documentation (Claude Code docs, “Hooks reference,” code.claude.com/docs/en/hooks, checked 2026-08-16). The orders-api repo, the pg version bump, its idleTimeoutMillis behavior change, and the one-night-in-ten rate are an invented running example, not an observed one.

For the per-tool mechanics, see Hooks for the Stop hook payload and decision control, Headless & CI for running the job unattended, and Permissions & sandboxing for the walls this gate stands behind.