In Claude Code, how do the Stop, SubagentStop, StopFailure and SessionEnd hook events differ, and which of them can keep Claude working?
answer
- end of a turn versus end of a session
- every response, not task completion
- API errors take another path
- subagent frontmatter renames one
- a tight budget at exit
basics
~20 sStop fires each time the main agent finishes responding and can block, keeping Claude working; SubagentStop does so for a subagent. StopFailure replaces Stop on API errors, observe-only. SessionEnd fires at session close and cannot block.
solid answer
~40 s`Stop` fires whenever the main agent finishes a response, not only when a task is done, and not on a user interrupt. It can block: a block keeps Claude working, which is how Stop gates work, with `stop_hook_active` and a cap of eight consecutive continuations as loop protection. `SubagentStop` is the same for a subagent, matched on agent type; a `Stop` hook in subagent frontmatter is converted to it. `StopFailure` fires instead of `Stop` when the turn ends on an API error; its output and exit code are ignored apart from a terminal sequence. `SessionEnd` fires as the session terminates, matched on reasons such as `clear` or `logout`; it cannot block and has a 1.5-second default budget, so it suits fast cleanup only.
go deeper
Recall that Stop is per response and can keep Claude going, while SessionEnd runs once at exit and can only clean up.
Explain the matchers: SessionEnd reasons, SubagentStop agent types, StopFailure error types, and that Stop has no matcher.
Show the operational traps: Stop firing on clarifying questions, the 1.5-second SessionEnd budget, API errors bypassing Stop, and frontmatter Stop becoming SubagentStop.
Weigh a Stop gate's quality benefit against extra turns and cost, and decide which completion checks a team enforces at turn end versus in CI.
## Four events around "finishing" Claude Code has several events that sound like "the end", and they differ in **cadence** (per turn or per session) and in **whether a hook can change the outcome**. | Event | Fires when | Matcher filters | Can block? | |---|---|---|---| | `Stop` | The main agent finishes responding | no matcher support | Yes: Claude continues | | `SubagentStop` | A subagent finishes | agent type | Yes: the subagent continues | | `StopFailure` | The turn ends on an API error, instead of `Stop` | error type, such as `rate_limit` | No: output and exit code ignored | | `SessionEnd` | The session terminates | reason: `clear`, `resume`, `logout`, `prompt_input_exit`, `other` | No | ## `Stop`: the end of every turn `Stop` runs each time Claude finishes a response. That is **per turn**, not "when the task is finished", so a hook that assumes completion will run after every answer, including a clarifying question. It does not run when you interrupt Claude, and when the turn ends because of an API error, `StopFailure` fires instead. `Stop` is one of the events that **can block**. A block prevents Claude from stopping and hands it a reason to keep going; that is the basis of every "run the tests before you finish" gate. Because a gate can loop, the input carries `stop_hook_active`, true when Claude is already continuing because of a stop hook, and Claude Code caps consecutive continuations at eight before it overrides the next block. The exact blocking fields and the loop guard belong to the hook input and output contract, and building the gate belongs to the handler patterns; for choosing the event, what matters is that `Stop` is the one that can keep the main agent working. ## `SubagentStop`: the same for subagents `SubagentStop` fires when a subagent finishes and accepts the same blocking decisions, which keep the **subagent** running with the reason as its next instruction. Its matcher filters on the agent type (`Explore`, `Plan`, a custom agent's `name`). Two details matter: - A `Stop` hook declared in a **subagent's frontmatter** is converted to `SubagentStop`, because that is the event fired when the subagent completes. - It also fires for internal agents Claude Code runs for its own features, where the agent type can be empty; an omitted or `*` matcher catches those too, a named matcher does not. ## `StopFailure`: observe API failures `StopFailure` replaces `Stop` when a rate limit, overload, authentication or similar API error ends the turn. Claude Code ignores its output and exit code apart from a `terminalSequence`, so it is for logging, alerting and recovery scripts, not for decisions. Its matcher takes the error type. ## `SessionEnd`: cleanup at exit `SessionEnd` fires when the session itself terminates: on exit, after `/clear`, on an interactive `/resume` switch, or on logout. It **cannot block** termination; exit 2 only shows stderr to the user. Its default budget is **1.5 seconds** for all SessionEnd hooks together. A per-hook `timeout` in your settings files raises the budget to match, up to 60 seconds, and `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` sets it explicitly. Keep it to quick cleanup: deleting scratch files, flushing a log line. ## Choosing between them 1. **Need Claude to keep working until a condition holds?** `Stop` (or `SubagentStop` for a subagent). 2. **Need to react when the turn died on an API error?** `StopFailure`. 3. **Need to tidy up when the session closes?** `SessionEnd`, matched on the reason when only some exits matter, such as `clear`. 4. **Need context after `/clear`?** That is `SessionStart` with the `clear` source on the new session, not `SessionEnd` on the old one. ## Common mistakes - **Treating `Stop` as "task complete".** A clarifying question ends a turn too, so a completion notice or a deploy step on `Stop` fires far more often than intended. - **Expecting `Stop` on API failures.** A rate-limited turn fires `StopFailure`, so a logging hook registered only on `Stop` misses exactly the turns worth logging. - **Putting a gate on `SessionEnd`.** It cannot block, so a check there can only report after the fact, and the 1.5-second default budget may cut it short. - **Naming agent types on `SubagentStop` and missing internal agents.** A named matcher skips events whose agent type is empty; omit the matcher if every subagent stop matters.
- A SessionEnd hook that uploads a large log keeps getting cut off. Why, and what are the options?SessionEnd hooks share a 1.5-second default budget. Setting a longer `timeout` on that hook raises the budget to match, up to 60 seconds, and `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` sets it explicitly. Often the better fix is to hand the upload to a background process and return at once.
- Why does a Stop hook that posts 'task done' to chat fire after Claude merely asks you a question?Stop fires whenever the main agent finishes a response, not when a task completes. A clarifying question ends a turn just like a final answer. The hook has to judge completion itself, for example from `last_assistant_message`, or the team should accept a message per turn.
- Stop fires only when Claude has finished the whole task.
- A SessionEnd hook can keep the session open by exiting 2.
- Stop also fires when a turn ends on a rate-limit error.
- StopFailure hooks can retry the failed request by blocking.
- A Stop hook in subagent frontmatter runs when the main turn ends.