[FEATURE]

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

Currently, PreToolUse hooks intercept ALL tool calls, including operations that would be auto-approved by Claude Code's built-in logic. This makes it impossible to create a "notification-only-when-actually-needed" workflow.

Use Case:
I want to receive push notifications on my mobile device only when Claude Code genuinely needs my permission for an operation - not for auto-approved operations like reading files, running safe commands, etc.

When away from my computer, I want to:

1. Claude encounters an operation requiring approval
2. I receive a push notification on my phone
3. I tap Approve/Deny
4. Claude continues immediately (no waiting at terminal)

Current Limitation:
PreToolUse hooks run before auto-approval logic, so they intercept everything:

• Read operations (would be auto-approved)
• Write operations (would be auto-approved)
• Safe bash commands (would be auto-approved)
• Operations that genuinely need approval

This creates notification spam and defeats the purpose. There's no way to hook only into "real" permission requests that would otherwise prompt the user in the terminal.

Proposed Solution

Add a new hook type: OnPermissionRequest or PostAutoApproval

This hook would only trigger when:

• An operation is NOT in the auto-approval list
• Claude Code would normally prompt the user in the terminal
• User intervention is genuinely required

Example configuration:

{
  "hooks": {
    "OnPermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/send-push-notification.sh",
            "timeout": 300000
          }
        ]
      }
    ]
  }
}

Hook Input (JSON stdin):

{
  "tool_name": "BashTool",
  "tool_input": {"command": "rm -rf /important/data"},
  "session_id": "abc123",
  "reason": "Operation not in auto-approval list"
}

Hook Output (JSON stdout):

{
  "hookSpecificOutput": {
    "hookEventName": "OnPermissionRequest",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "Approved via mobile notification"
  }
}

Benefits:

• Enables remote approval workflows for unattended operation
• Reduces notification spam (only real permission requests)
• Allows integration with mobile push notification systems
• Enables true "away from computer" Claude Code usage
• Useful for distributed/headless deployments

---

Alternative Solutions

Option 1: Permission Handler Config
Add a config option to specify a "permission handler" that replaces terminal prompts entirely:

{
  "permissionHandler": {
    "command": "/path/to/approval-handler.sh",
    "timeout": 300000,
    "fallbackToTerminal": true
  }
}

This handler would receive the same info as a PreToolUse hook but only be called when terminal approval would normally be required. If the handler fails or times out, fall back to terminal prompt.

---

Option 2: PostAutoApproval Hook
Similar to OnPermissionRequest but runs after auto-approval decision is made:

{
  "hooks": {
    "PostAutoApproval": [
      {
        "matcher": {
          "approvalRequired": true
        },
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/handler.sh"
          }
        ]
      }
    ]
  }
}

Only triggers when approvalRequired: true in the auto-approval decision.

---

Option 3: Hook Filtering by Approval Status
Enhance PreToolUse hooks to receive the auto-approval decision first:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": {
          "tools": ["BashTool"],
          "whenAutoApprovalIs": "denied"  // NEW
        },
        "hooks": [...]
      }
    ]
  }
}

This way PreToolUse hooks could filter to only run when auto-approval would deny the operation.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Environment:

• Use case: Distributed agent system running across 22 headless Proxmox servers
• Current workaround: None viable (PreToolUse too broad, terminal prompts require physical presence)
• Integration: Have existing push notification system using ntfy.sh, just need the hook point

Real-world scenario:
I'm running long-running Claude Code tasks on remote servers. When Claude needs permission for something (e.g., installing a package, modifying system files), I want my phone to buzz so I can approve it immediately from anywhere. Currently, Claude just sits there waiting at a terminal I'm not watching.

This would be incredibly valuable for:

• CI/CD workflows with Claude Code
• Overnight/weekend autonomous operations
• Multi-server deployments
• Remote development workflows

Additional Context

_No response_