A Claude Code Stop hook blocks until a condition holds, and Claude keeps working long after it should stop. Why does it loop, and how do you guard it?
answer
- fires on every finish
- a field says you already blocked
- a cap of consecutive blocks
- feedback versus block
basics
~20 sEach decision: block or exit 2 sends Claude back to work, and the next finish fires the hook again. Check stop_hook_active in the stdin JSON and exit 0 when it is true; Claude Code also ends the turn after eight consecutive blocks.
solid answer
~40 sA `Stop` hook fires every time Claude finishes responding. Returning `{"decision": "block", "reason": "..."}`, or exiting 2 with stderr, prevents the stop and hands the reason to Claude, which continues. If the condition can't be met, each new finish fires the hook again and it blocks again. The stdin JSON carries **`stop_hook_active`**, which is `true` when Claude is already continuing because of a stop hook; check it and `exit 0` to let Claude stop. As a backstop, Claude Code overrides the next block after **eight consecutive continuations** and ends the turn with a warning; `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` changes that number, and `0` disables the cap. For guidance that isn't an error, return `hookSpecificOutput.additionalContext`, which continues the turn through the same loop protections but is labelled `Stop hook feedback` instead of a hook error.
code
bash · 11 lines#!/bin/bash
# Stop hook: one nudge to update the changelog, then let Claude stop
input=$(cat)
if [ "$(jq -r '.stop_hook_active' <<<"$input")" = "true" ]; then
exit 0 # already continuing because of a Stop hook
fi
cwd=$(jq -r '.cwd' <<<"$input")
if ! grep -q "Unreleased" "$cwd/CHANGELOG.md"; then
jq -n '{decision: "block", reason: "Add an Unreleased entry to CHANGELOG.md before finishing."}'
fi
exit 0go deeper
Recall that a Stop hook can keep Claude working by blocking, and that the stdin JSON has a stop_hook_active field to prevent endless loops.
Explain the two ways to block a stop (decision block with a reason, or exit 2 with stderr) and why every new finish fires the hook again.
Show you design a gate that converges: the stop_hook_active early exit, the eight-block cap and its variable, feedback versus block, and conditions Claude can actually satisfy.
Weigh forcing completion against cost: how many automatic continuations a team tolerates, which checks deserve a Stop gate at all, and how failures are reported when the gate gives up.
## Why a Stop hook can loop A **`Stop` hook** runs when the main Claude Code agent finishes responding. It doesn't run when you interrupt Claude, and a turn that ends on an API error fires `StopFailure` instead. A Stop hook can **block** the stop in two ways: - print `{"decision": "block", "reason": "..."}` on stdout (`reason` is required when blocking), or - write the reason to stderr and `exit 2`. Either way, Claude doesn't stop: it receives the reason as an explanation of why it should continue, and it works again. When it finishes that work, **the Stop event fires again**, and the hook runs again with fresh input. If the hook's condition is one Claude can't satisfy, such as a flaky check, an external service that is down or a goal outside its permissions, the hook blocks on every finish. That is the loop. ## The loop guard: `stop_hook_active` Stop hooks receive the common input fields plus `stop_hook_active`, `last_assistant_message`, `background_tasks` and `session_crons`. - **`stop_hook_active`** is `true` when Claude Code is already continuing as a result of a stop hook. A hook that sees `true` knows that it, or another stop hook, already sent Claude back once in this chain. - The documented pattern is to **exit 0 early when it is `true`**, which allows the stop. - The alternative is to inspect the transcript and block only while real progress is being made. The early-exit pattern gives **one nudge per chain**: Claude gets a single chance to fix the problem, and on the next finish it may stop even if the condition still fails. For a gate that must be satisfied, prefer a condition Claude can actually reach, and report the remaining failure rather than blocking forever. ## The backstop: a consecutive-block cap Claude Code limits runaway loops itself. After stop hooks have continued the turn **eight times in a row**, it overrides the next block and ends the turn with a warning that the Stop hook blocked too many consecutive times. | Setting | Effect | |---|---| | Default | Cap of 8 consecutive continuations | | `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=<n>` | Raises or lowers the cap | | `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=0` | Disables the cap, which is risky with a hook that never relents | The cap applies to `Stop` and `SubagentStop`. Raise it only when a hook legitimately needs more iterations to converge, and still check `stop_hook_active`, because eight wasted iterations cost time and tokens. ## Block, feedback or full stop | Output | Effect | How the transcript shows it | |---|---|---| | `decision: "block"` with `reason`, or exit 2 | Claude continues with the reason | As a hook error | | `hookSpecificOutput.additionalContext` | Claude continues with the guidance | As `Stop hook feedback`, no error notice | | `continue: false` with `stopReason` | Claude stops processing entirely | `stopReason` shown to the user | | Exit 0, no output | Claude stops normally | Nothing | `additionalContext` is for a hook that is working as designed and giving guidance. It goes through **the same loop protections** as a block (`stop_hook_active` and the cap), so it needs the same guard. `continue: false` is the opposite tool: it ends processing instead of extending it. ## A guarded Stop hook ```bash #!/bin/bash input=$(cat) if [ "$(jq -r '.stop_hook_active' <<<"$input")" = "true" ]; then exit 0 # already continuing because of a Stop hook: let Claude stop fi cwd=$(jq -r '.cwd' <<<"$input") if ! grep -q "Unreleased" "$cwd/CHANGELOG.md"; then jq -n '{decision: "block", reason: "Add an Unreleased entry to CHANGELOG.md before finishing."}' fi exit 0 ``` On the first finish without an entry, the hook blocks with a reason. On the next finish `stop_hook_active` is `true`, so it exits 0 and Claude stops whatever the file says. ## Other facts that keep Stop hooks sane 1. A Stop hook fires whenever Claude finishes responding, **not only at task completion**, so a check that expects a finished task must tolerate a plain answer to a question. 2. Read the reply from **`last_assistant_message`**, not by parsing `transcript_path`, which may not contain the final message yet. 3. `background_tasks` and `session_crons` tell the hook whether the session is done or only paused waiting for background work, which is another reason not to block. 4. `SubagentStop` follows the same decision control for subagents.
- When is `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=0` a bad idea?Setting it to `0` disables the consecutive-block cap, so a Stop hook whose condition never resolves keeps Claude working until someone interrupts it, spending time and tokens. Raise the cap instead when a hook legitimately needs more than eight iterations, and keep the `stop_hook_active` check.
- When should a Stop hook return `additionalContext` instead of `decision: "block"`?When the hook is working as designed and offering guidance, such as reminding Claude to update the changelog. The turn continues the same way, but the transcript labels it `Stop hook feedback` instead of a hook error. It goes through the same loop protections, so it still needs the `stop_hook_active` guard.
- Stop hooks fire only when the whole task is complete
- Claude Code will let a Stop hook block forever with no limit
- stop_hook_active means another Stop hook is still running
- Returning additionalContext from a Stop hook bypasses the loop protections
- continue: false keeps Claude working on the hook's feedback