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

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

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

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.

Download on the App Store