Stop hook with exit code 2 displays as 'Stop hook error' instead of feedback
Resolved 💬 7 comments Opened Mar 15, 2026 by ValeryP Closed Jun 1, 2026
Description
Stop hooks that intentionally block with exit 2 and provide feedback via stderr are displayed as "Stop hook error" in the UI. This is misleading — exit code 2 is the documented way to block an action and provide instructions, not an error condition.
Current behavior
When a Stop hook exits with code 2 and writes instructions to stderr, the UI shows:
● Ran 4 stop hooks (ctrl+o to expand)
└ Stop hook error: [~/.claude/hooks/session-insights.sh]: BEFORE STOPPING: Save session insights...
The word "error" implies something went wrong, when in fact the hook is functioning exactly as designed.
Expected behavior
The message should indicate the hook blocked the action, not that it errored. For example:
● Ran 4 stop hooks (ctrl+o to expand)
└ Stop hook blocked: [~/.claude/hooks/session-insights.sh]: BEFORE STOPPING: Save session insights...
Or simply show the feedback text without an "error" label.
Steps to reproduce
- Create a Stop hook that exits with code 2 and writes to stderr:
#!/bin/bash
echo "Please save insights before stopping." >&2
exit 2
- Work in a session long enough for the hook to trigger
- Let Claude try to stop → observe "Stop hook error" label
Environment
- Claude Code version: 2.1.x (latest native macOS)
- OS: macOS (Darwin 25.3.0)
🤖 Generated with Claude Code
This issue has 7 comments on GitHub. Read the full discussion on GitHub ↗