[FEATURE] User Interrupt Hook #9516
Description
Preflight Checklist
- I have searched existing requests and this feature hasn't been requested yet
- This is a single feature request (not multiple features)
Problem Statement
Summary
Add a new hook event that fires when the user manually interrupts Claude Code's response (e.g., by clicking Stop or pressing Ctrl+C).
Problem
Currently, Claude Code provides a Stop hook that fires when the agent finishes responding normally. However, according to the documentation:
"Does not run if the stoppage occurred due to a user interrupt."
This creates a gap: there is no way to detect when the user manually interrupts the agent. This prevents implementing features that need to differentiate between:
- Normal completion (agent finished its work)
- User interrupt (user manually stopped the agent)
Proposed Solution
Add a new hook event: UserInterrupt (or AgentInterrupted, Stop:Interrupted, etc.)
This hook should fire when:
- User clicks the Stop button during agent response
- User presses keyboard interrupt (Ctrl+C or equivalent)
- User manually cancels agent operation through any UI mechanism
Example Configuration
{
"hooks": {
"Stop": [{
"hooks": [{
"type": "command",
"command": "my-script.py --event normal_completion"
}]
}],
"UserInterrupt": [{
"hooks": [{
"type": "command",
"command": "my-script.py --event user_interrupted"
}]
}]
}
}Alternative Solutions
No response
Priority
Medium - Would be very helpful
Feature Category
CLI commands and flags
Use Case Example
We're implementing an audio notification system that plays background noise while Claude works and plays a completion sound when finished. We need to:
- Play a "work complete" sound when the agent finishes normally (
Stophook) - Play a different "interrupted" sound when the user manually stops the agent
- Currently impossible because there's no hook for user interrupts
Additional Context
Benefits
- Feature parity: Completes the lifecycle coverage (start → working → end/interrupt)
- Better UX: Enables context-aware notifications and state management
- Debugging: Helps track user interaction patterns and interruption frequency
- Resource cleanup: Allows proper cleanup of resources when operations are interrupted vs. completed
Workarounds (and why they don't work)
- Timeout-based detection: Unreliable, creates false positives for long-running tasks
- Heartbeat with PreToolUse: Fires on every tool call, creates noise and complexity
- Process monitoring: External to Claude Code, fragile and platform-specific
Related Documentation
- Hooks Reference
- Current
Stophook explicitly excludes interrupts
Activity
arhgap11b commentedon Oct 14, 2025
Would be great if we could have hook on context limit (when auto-compact turned off)!
github-actions commentedon Dec 8, 2025
This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.
mpercy commentedon Dec 24, 2025
Would be nice to see this fixed for edge-triggered status / notification purposes
CharlonTank commentedon Dec 29, 2025
I need that too!
jeffc-dev commentedon Jan 14, 2026
Consider me another vote for this.
I'm working on a utility that watches Claude activity and is effectively 'stuck' if it can't detect manual interuption.
bernarduh commentedon Jan 21, 2026
I could use the Interrupted hook too 🙏
maxisme commentedon Jan 24, 2026
Very keen for this feature it is leaving my Claude code wrapper in very strange states.
alvarolb commentedon Jan 24, 2026
I need this one too ;)
johnrobinsn commentedon Jan 24, 2026
Pretty please 🙏 Thanks!
mwurm293 commentedon Feb 8, 2026
please
XciD commentedon Feb 10, 2026
Would love to see this one too
14 remaining items
ro0mquy commentedon Jul 8, 2026
+1
zhenghan3852 commentedon Jul 8, 2026
+1
3Spiders commentedon Aug 3, 2026
+1
fix(sessions): an interrupted turn stops reading "working" (v0.325.0) (…
fix(sessions): an interrupted turn stops reading "working" (v0.325.0) (…
fix(tmux,claude): clear the agent dot after an ESC interrupt
No interrupt hook exists; we were registered on 11 of 31 events
fix(tmux,claude): clear the agent dot after an ESC interrupt
ZhenyaUsenko commentedon Sep 28, 2026
+1
pleahmacaka commentedon Oct 1, 2026
+1, use case: a plugin that sends "continue" when you press Enter twice on an empty prompt after interrupting.
turn-marker: Count each prompt when it is submitted
A Claude Code turn stopped with Esc ends the pane's working status: t…
MaxShymko commentedon Oct 28, 2026
I need this as well!
CTSDM commentedon Nov 8, 2026
We run several Claude Code sessions in tmux and show each one's state (working/idle) from hooks: UserPromptSubmit --> working, Stop --> idle. When a turn is interrupted by the user with escape or control c, no hook fires, so the session shows "working" indefinitely while it sits idle. It's worst when the interrupt comes before any output: the prompt goes back to the input box and there's nothing on screen we could detect the interrupt from.