Permission Prompt 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 type that fires when Claude Code is waiting for user approval on permission prompts.

Motivation

Currently, Claude Code has hooks for:

• PreToolUse - Before tool execution
• PostToolUse - After tool completion
• Stop - When Claude finishes responding

However, there's no hook that fires when Claude Code is blocked waiting for user permission approval.

Use Case

When a tool requires permission (configured in settings.json under "ask"), Claude Code shows:

Do you want to proceed?
❯ 1. Yes
  2. Yes, and don't ask again...
  3. Type here...

At this moment, users may want to:

• Play a notification sound
• Show a desktop alert
• Log the permission request
• Track tool usage patterns
• Send notifications to monitoring systems

Currently, the Stop hook fires when Claude finishes ALL work, but permission prompts happen mid-execution - a different state that needs its own hook.

Proposed Solution

Proposed Solution

Add a new hook type: PermissionPrompt (or WaitingForApproval)

Example Configuration

{
  "hooks": {
    "PermissionPrompt": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/on-permission-prompt.sh"
          }
        ]
      }
    ]
  }
}

Hook Context

The hook should receive context about:

• tool_name - Which tool requires permission
• tool_input - Parameters of the tool call
• reason - Why permission is required (e.g., "matches ask pattern: Bash(rm:*)")

Example Hook Script

#!/bin/bash
# Notify user that approval is needed

echo "$(date) - Permission required for tool execution" >> ~/.claude/permission-log.txt

# Play notification sound
afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &

# Show desktop notification
osascript -e 'display notification "Claude needs your approval" with title "Claude Code"'

Benefits

1. User Awareness - Alerts users when their input is needed for blocked operations
2. Monitoring - Track which tools frequently require permission
3. Audit Trail - Log permission requests for security/compliance
4. Workflow Integration - Integrate with notification systems (Slack, Teams, etc.)
5. Consistency - Completes the hook lifecycle coverage (before, during-blocked, after, stop)

Alternative Solutions

Alternatives Considered

1. Use PreToolUse Hook

Problem: Fires before permission prompt appears, not when waiting for approval

2. Use Stop Hook

Problem: Fires after ALL work completes, not during mid-execution blocks

3. External Monitoring

Problem: Requires polling/watching external state, unreliable and inefficient

Additional Context

Current Permission System:

{
  "permissions": {
    "allow": [],
    "deny": ["WebSearch", "WebFetch"],
    "ask": [
      "Bash(rm:*)",
      "Bash(git push:*)"
    ]
  }
}

When tools match "ask" patterns, they trigger permission prompts - this is the state we want to hook into.

Related Features

This complements existing hooks to provide full lifecycle coverage:

| Hook | When It Fires |
|------|---------------|
| PreToolUse | Before tool execution (approved or not) |
| PermissionPrompt | When waiting for user approval ← NEW |
| PostToolUse | After tool execution completes |
| Stop | When Claude finishes responding |

Implementation Notes

• Should respect matcher patterns (tool-specific or wildcard)
• Should include tool context in environment/stdin
• Should be non-blocking (async) to avoid interfering with prompt
• Consider adding decision support (like Stop hook can block/approve)

Priority

Low - Nice to have

Feature Category

Interactive mode (TUI)

Use Case Example

Use Case

When a tool requires permission (configured in settings.json under "ask"), Claude Code shows:

Do you want to proceed?
❯ 1. Yes
  2. Yes, and don't ask again...
  3. Type here...

At this moment, users may want to:

• Play a notification sound
• Show a desktop alert
• Log the permission request
• Track tool usage patterns
• Send notifications to monitoring systems

Currently, the Stop hook fires when Claude finishes ALL work, but permission prompts happen mid-execution - a different state that needs its own hook.

Additional Context

_No response_