Stop Hook vs StopFailure Hook
People think a Stop hook runs at the end of every turn, whatever happens. It only runs when Claude finishes its answer on its own. A turn cut short by an API error, such as a rate limit, fires StopFailure instead. And only Stop can send Claude back to work. StopFailure ignores what the hook prints, so it is for alerts.
Stop Hook
The event when Claude finishes, where a hook can make it keep going.
Stop is the hook event that fires when Claude finishes its answer. It does not fire if you interrupt, and an API error fires StopFailure instead. A hook here can block the stop with a reason, and Claude keeps working. A stop_hook_active flag tells the hook it already did this once, so it can avoid a loop.
StopFailure Hook
The event when a turn ends on an error. It is for logs and alerts.
StopFailure is the hook event that fires instead of Stop when a turn ends because of an API error. Examples are a rate limit, an overloaded server or a login problem. The matcher can pick the kind of error. Claude Code ignores what the hook prints, so it is for logging and alerts only.
In one line
- Stop Hook
- The event when Claude finishes, where a hook can make it keep going.
- StopFailure Hook
- The event when a turn ends on an error. It is for logs and alerts.