claude-code [FEATURE] User Interrupt Hook

Preflight Checklist

[x] I have searched existing requests and this feature hasn't been requested yet
[x] 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 (Stop hook)
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 Stop hook explicitly excludes interrupts

Oct 14 '25 09:10 arhgap11b

Would be great if we could have hook on context limit (when auto-compact turned off)!

Oct 14 '25 11:10 arhgap11b

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.