Skip to content
BENIBIX Learn

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.

AI⌨️ Claude Code

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.

Example
Lucy's Stop hook runs the tests. If any fail, it blocks the stop and tells Claude to fix them first.
Why it matters
It turns done into done and checked. Claude cannot end a turn with red tests.
Full entry
AI⌨️ Claude Code

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.

Example
Jack's long overnight job hit a rate limit. His StopFailure hook sent him a phone alert, so he knew by breakfast.
Why it matters
A failed turn is silent if no one is watching. This makes it loud.
Full entry

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.