AIToday
Large Language ModelsAI Coding AssistantsZenn AI/MLPublished: Nov 21, 2026, 16:00 JST

Claude Code 2.1.325: ten stalls in a Stop-hook reviewer setup

Send on LINE
Claude Code 2.1.325: ten stalls in a Stop-hook reviewer setup

3 Key Points

  1. What happened

    A developer installed a reviewer subagent that writes a sha256-tagged PASS/FAIL verdict to .review/verdict.json and a Stop hook that checks it, then logged ten places the setup stalled on Claude Code 2.1.325 — including a blocking exit-2 hook that let a turn end.

  2. Why it matters

    The stalls show a verification setup can silently fail to hold the AI to its review gate, so anyone relying on such a hook may think changes were checked when the turn simply ended.

Not sure about something? Ask the AI

Questions and answers are published on this page.

Summaries like this, every morning.

Context & Analysis

The setup under test has two moving parts: a reviewer subagent that writes a verdict with the current diff's sha256 into .review/verdict.json, and a Stop hook that only checks whether a verdict exists, matches the current diff, and says PASS. The author's runs on Claude Code 2.1.325 (with one run on 2.1.326) show that several of the failure points sit in how Claude Code treats hooks and subagents rather than in the verdict logic itself.

The documented exceptions mattered more than the headline behavior. A Stop hook that exits 2 is treated as non-blocking when stdout is empty and stderr names a missing file, and onFailure: "block" has no effect on Stop hooks — both documented in the hooks reference, and both observed in runs D and E. Separately, subagents start in the background by default, so in the author's runs the AI often closed its turn before a verdict existed, and the hook blocked again; in R6 the AI called the reviewer in the background three times even after receiving a reason asking it to wait.

The author's fixes were partial. Moving the verdict to .review/verdict.json avoided Claude Code's protection on .claude/, and adding an explicit instruction not to use the caller's supplementary notes stopped the reviewer from passing out-of-scope README changes. But the author notes each run was done once, with personal global hooks and CLAUDE.md active, and a clean environment was not tested — so how much of the AI's waiting and reverting behavior generalizes is left open.

FAQ
Why did the Stop hook fail to block the AI?
The official hooks documentation says a Stop hook that exits 2 with empty stdout and stderr mentioning a missing file, such as No such file or directory, is treated as a non-blocking error. In the author's run D, the turn ended in one turn. The fix was to print JSON with decision: block to stdout and exit 0; run F then blocked nine times.
Does onFailure: "block" work on a Stop hook?
No. The hooks documentation lists Stop among the hooks where the field has no effect. In run E, a script with a syntax error exited 1 and the conversation ended in one turn without stopping.
What is the 8-consecutive-continuation cap?
Claude Code overrides the next block and ends the turn after stop hooks have continued the turn eight times in a row, and the count resets each time Claude calls a tool. Run C and R4 ended on the ninth block; run B exceeded eight blocks in a stretch where the AI called tools while waiting for a verdict.
Send on LINE

AI news that matters for your work, delivered every morning.

Pick your industry and the AI tools you use, and get news related to your work every day.

Free · 30 seconds with Google · unsubscribe anytimeWhat is AIToday? →

Ask AI

Ask AI anything about this article. The AI reads this article, earlier AIToday articles, and Wikipedia, and cites its sources. Q&As are published on this page for other readers too.

Questions and answers are published on this page.

Related Articles

Next articleContra Pace: Ben Pace's one-graph case for LessWrong's writer decline