The Claude Code Stop hook
Updated
Quick answer
The Stop hook runs each time Claude Code finishes responding. It receives the session’s details, including Claude’s last message, and can either let the turn end or send Claude back to work with a reason. It does not run when you interrupt Claude, and an API error fires StopFailure instead.
When it fires, and when it doesn’t
- It fires when the main agent finishes a response, at the end of every turn, not only at the end of a whole task. It takes no matcher.
- It doesn’t fire when you interrupt Claude with Esc.
- On an API error, such as a rate limit, a billing problem or an overloaded server, Claude Code runs
StopFailureinstead. That event’s matcher filters on the error type, and its output is ignored. - Subagents have their own event,
SubagentStop.
A turn can end while work goes on: a subagent, a shell command or a monitor running in the background. Stop fires anyway, and fires again when that work wakes Claude up. The input tells you which case you are in.
If what you want is “keep going until this condition is true”, the built-in /goal command sets up a prompt-based Stop hook for the session without any configuration.
What it receives
Standard input
{
"session_id": "abc123",
"cwd": "/Users/you/dev/harbor",
"permission_mode": "default",
"hook_event_name": "Stop",
"stop_hook_active": false,
"last_assistant_message": "Done: the login form now validates emails. All 212 tests pass.",
"background_tasks": [],
"session_crons": []
}
last_assistant_message is the text of Claude’s final reply: use it rather than the transcript file, which may not include the last message yet. background_tasks lists work still in flight, each entry with a type such as shell or subagent. session_crons lists scheduled wake-ups. stop_hook_active is true when Claude is already continuing because of a stop hook.
Run a command when Claude finishes
~/.claude/settings.json
{
"hooks": {
"Stop": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/done.sh" }] }],
"StopFailure": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/done.sh" }] }]
}
}
~/.claude/hooks/done.sh (Linux desktop; on macOS use osascript)
#!/bin/sh
# Stop and StopFailure: one alert per real end of work, with what Claude said.
input=$(cat)
# A subagent still running: its end will bring another Stop. Other background tasks don't count.
[ "$(printf '%s' "$input" | jq '[.background_tasks[]? | select(.type=="subagent")] | length')" -gt 0 ] && exit 0
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")
msg=$(printf '%s' "$input" | jq -r '.last_assistant_message // "Finished"' | head -c 180)
notify-send "Claude Code · $project" "$msg"
exit 0
For StopFailure, last_assistant_message holds the error text, such as “API Error: Rate limit reached”, so the same script tells you why the turn stopped. Keep the command quick, or set "async": true so it runs in the background.
Make Claude continue without a loop
A Stop hook can refuse the end of the turn. Print {"decision": "block", "reason": "..."}, or exit 2 with the reason on standard error, and Claude reads the reason and keeps working. To give Claude a note without it being shown as an error, return hookSpecificOutput.additionalContext instead: the transcript labels it Stop hook feedback.
Send Claude back once if the tests fail
#!/bin/sh
input=$(cat)
# Already continuing because of this hook: let the turn end.
[ "$(printf '%s' "$input" | jq -r '.stop_hook_active')" = true ] && exit 0
cd "$(printf '%s' "$input" | jq -r '.cwd')" || exit 0
if ! out=$(npm test 2>&1); then
last=$(printf '%s' "$out" | tail -n 15)
jq -nc --arg r "The tests fail. Fix them before you finish. Last lines: $last" \
'{decision: "block", reason: $r}'
fi
exit 0
Two safeguards stop runaway loops. Check stop_hook_active, as above, so you don’t block on a condition that will never clear. And Claude Code caps it: after stop hooks have continued the turn eight times in a row, it ends the turn whatever the hook says. The count resets each time Claude calls a tool, and CLAUDE_CODE_STOP_HOOK_BLOCK_CAP changes the cap. To end everything, return "continue": false.
Reading a Stop hook error
- Stop hook error with your reason: your hook returned
decision: block, which the terminal shows as an error even when it works as designed. UseadditionalContextfor a calmer label. - Failed with non-blocking status code: your script exited with a code other than 0 or 2. The turn ended normally; the notice carries the first line of your standard error.
- No such file or directory: the path in
commandis wrong or the script isn’t executable, so the hook never ran. - Your JSON is ignored: something else reached standard output, often a line your shell profile prints. Print nothing but the JSON object.
Run claude --debug and read the log in ~/.claude/debug/ to see each run with its exit status and duration. onFailure has no effect on Stop hooks.
How Monish uses it
Monish’s Stop hook turns the end of a turn into a push: Done · harbor with the start of Claude’s last message. It waits until no subagent is still running, so the push doesn’t come too early. Reply from the notification, and your message becomes Claude’s next instruction. The hook runs in the background with asyncRewake, so the terminal stays free while a reply is possible, and it stops waiting as soon as you type a new prompt at the keyboard. Pair a computer with curl -fsSL https://monish.cc/install.sh | sh -s and the code the app shows.
Questions
- Why does my Stop hook run before Claude has really finished?
- Stop fires at the end of every turn, including a turn that ends while a subagent or a shell keeps running in the background. Check background_tasks and skip while it lists a task of type subagent; ignore the other types, or a dev server left running would silence every alert.
- My Stop hook makes Claude loop. How do I stop it?
- Exit early when stop_hook_active is true. Claude Code also ends the turn after eight continuations in a row without a tool call.
- Does the Stop hook run in claude -p?
- Yes, at the end of each turn. Async hooks still running when a -p run ends are cancelled, so keep the work synchronous or start a detached process.
- What is the difference between Stop and SubagentStop?
- Stop fires when the main agent finishes responding. SubagentStop fires when a subagent finishes, and its matcher filters on the agent type.
More guides
- Get notified when Claude Code finishesThe Stop hook on macOS, Windows and Linux, then on your phone.
- The Claude Code Notification hookWhen it fires, what notification_type means, and why it waits six seconds.
- Claude Code hooks explained, with examplesThe events, where they live, and which ones matter for notifications.
- The Claude Code PermissionRequest hookAnswer a permission prompt from a script: input, output, limits.
New to Monish? The home page shows what lands on your iPhone, and all guides are listed here.
Get Monish on your iPhone
Free, no account. Your 6-digit code is waiting in the app.