[FEATURE] Add notification matcher for when Claude is actually waiting for user input

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

The idle_prompt notification hook fires after EVERY response, making it unusable for its intended purpose.

I want to be notified when Claude Code genuinely needs my attention (asking a question via AskUserQuestion, requiring approval, waiting for permission), but the current idle_prompt Notification matcher triggers immediately after every normal response, creating constant false positive notifications.

Current workflow problem:

1. I configure a Notification hook with idle_prompt matcher to get notified when Claude needs input
2. I ask Claude to perform a long-running task (install packages, run tests, etc.) and work on something else
3. I get notified immediately after Claude finishes responding - "Claude is waiting for your input" ❌ (false positive)
4. I check the terminal - Claude doesn't need anything, just finished normally
5. This happens after EVERY response - after each package install, each test run, each file read
6. I've learned to ignore the notifications due to alert fatigue
7. When Claude actually DOES need my input (choosing between fixes, answering a question), I miss it

Why I need this:

• Long-running operations: Work on other tasks while Claude runs tests, installs packages, debugging
• Multi-tasking: Get notified only when my attention is genuinely required
• Automation: Build reliable workflows that react to actual user input requests, not every completion
• Productivity: The Stop hook tells me when tasks complete, but I need to know when Claude is blocked waiting for MY decision

The name "idle_prompt" suggests waiting/idle state, but it fires on every prompt display instead.

Proposed Solution

Three-part solution (all related):

1. Implement notification_type field properly (fixes #11964)

Add the documented notification_type field to the JSON payload with distinct values:

{
  "session_id": "string",
  "cwd": "string",
  "message": "string",
  "notification_type": "waiting_for_user_action",
  "waiting_for_tool": "AskUserQuestion",
  "idle_duration_seconds": 0,
  "hook_event_name": "Notification"
}

Proposed notification_type values:

• "waiting_for_user_action" - AskUserQuestion, choices, confirmations
• "permission_required" - Tool approval needed
• "response_complete" - Normal response finished (current idle_prompt behavior)
• "user_interrupted" - User pressed ESC/Ctrl+C (from #11189)
• "idle_timeout" - Actually idle for 60+ seconds

2. Add new notification matcher (preferred approach)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "waiting_for_user_action",
        "hooks": [{"type": "command", "command": "/path/to/notify.sh"}]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [...]
      }
    ]
  }
}

3. Fix idle_prompt behavior

Make idle_prompt match its name:

• ✅ Fire when actually idle/waiting (60+ seconds, or waiting for user action)
• ❌ Don't fire on every normal response completion

This gives users control:

• Use waiting_for_user_action for immediate notifications when input needed
• Use idle_prompt for timeout-based notifications (60+ seconds)
• Filter by notification_type in scripts for custom logic

Alternative Solutions

What I've tried (all failed):

1. Keyword filtering on message content

if [[ "$message" =~ "waiting for" ]] || [[ "$message" =~ "choose" ]]; then
  notify
fi

Problem: Message field is often empty or generic ("", " ", or just project name)
Result: Still false positives

2. Checking notification_type field

Problem: Field is completely missing (see #11964)
Result: Can't differentiate anything

3. Smart filtering with multiple heuristics

• Analyzed message patterns
• Checked for specific keywords
• Added cooldown timers

Problem: No reliable signal in the payload to distinguish cases
Result: Either too many false positives or miss real notifications

Priority

Medium - Would be very helpful

Feature Category

Other

Use Case Example

_No response_

Additional Context

Related Issues (Building on existing work)

#11964 (Bug) - Notification events missing notification_type field

• Reports that the documented field is completely missing from the JSON payload
• My feature request proposes how to implement this field properly
• Relationship: #11964 reports the bug, this FR proposes the complete solution
• Together they solve the infrastructure problem + the behavioral problem

#11189 (Enhancement) - Add interrupt/reason context to Notification hook

• Requests reason field to distinguish user interrupts from natural pauses
• Focuses on interrupt detection (ESC/Ctrl+C)
• My request focuses on idle/waiting vs. normal completion detection
• Relationship: Both are needed for comprehensive notification control
• This FR can incorporate the interrupt detection as a notification_type value

#8320 (Bug) - 60-Second Idle Notifications not triggering at all

• Reports idle_prompt completely broken (doesn't fire even after 60+ seconds)
• My issue reports the opposite (fires when it shouldn't - false positives)
• Relationship: Shows idle_prompt is fundamentally broken and needs redesign
• This FR proposes fixing it comprehensively for all use cases

This feature request is unique because it:

1. Provides the missing implementation details for notification_type field (#11964)
2. Addresses both false positives (my issue) AND false negatives (#8320)
3. Incorporates the interrupt context concept from #11189
4. Proposes a complete, backward-compatible solution