Claude Stop Hook: Why exit 2 Makes the Model Retry

A Claude Stop hook can return the model to a task after a failed check, but it must exit with code 2 and send errors to stderr.
Claude Stop Hook: Why exit 2 Makes the Model Retry
A Stop hook can make Claude retry when a check fails. However, the hook must exit with code 2.
Differences between exit codes:
exit 2returns Claude to task execution and passes the hook'sstderrcontents to it, allowing the model to fix the error.exit 1does not block completion, so Claude simply finishes even if the check failed.
Additionally, exit 1 may indicate an error in the hook itself, such as a missing dependency or a bug in its script.
So, if you want Claude to retry, use exit 2 and send error output to stderr.
Example:
[your command] >&2 || { echo failed; exit 2; }
Why it matters
AnalysisCorrect exit codes turn Stop hooks into an actionable self-correction mechanism for AI coding agents, rather than a silent failure signal.
Discuss in community
Share your questions and insights with developers
Related in Ecosystem
Practical guides, core terminology, and agent skills
Claude Sonnet 4.6 vs GPT-5.5 vs Gemini 3.1 Pro: 2026 model comparison
Every few weeks, a new model comes out, and every time the same questions arise: should I switch? what changed what to pay for?
Claude Fable 5: When to Use the Powerful Model and Which Effort Level to Choose
A comprehensive breakdown of Claude Fable 5 and the effort parameter: behavioral reasoning signals, level availability matrix (low to xhigh), per-turn cost calculations, and practical API/Claude Code setups.
ClaudeMom on GitHub: project described as hypnotizing the official Claude client
A GitHub project called ClaudeMom is described as a local gateway that can make the official Claude client treat a user as authenticated.
Anthropic adds prompt-based interface customization to Claude desktop
Claude desktop now lets users change the app's interface design using a prompt.