[DOCS] Missing PermissionRequest hook details in Hooks Guide and Input Reference schema

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

docs/en/hooks-guide.md docs/en/hooks.md

Section/Topic

• hooks-guide.md: "Hook Events Overview" - hooks.md: "Hook Input" section

Current Documentation

In docs/en/hooks-guide.md under Hook Events Overview, the list currently reads:

• PreToolUse: Runs before tool calls (can block them)
• PostToolUse: Runs after tool calls complete
• UserPromptSubmit: Runs when the user submits a prompt...
• Notification: Runs when Claude Code sends notifications
• Stop: Runs when Claude Code finishes responding
• SubagentStop: Runs when subagent tasks complete
• PreCompact: Runs before Claude Code is about to run a compact operation
• SessionStart: Runs when Claude Code starts a new session...
• SessionEnd: Runs when Claude Code session ends

In docs/en/hooks.md, while PermissionRequest is mentioned in the Configuration and Output sections, it is completely missing from the Hook Input section, which lists inputs for all other hooks (PreToolUse Input, PostToolUse Input, Notification Input, etc.).

What's Wrong or Missing?

The PermissionRequest hook was introduced in v2.0.45 (according to the Changelog), but the documentation is incomplete:

1. It is missing from the high-level list in the Hooks Guide, making it difficult for new users to know the feature exists.
2. Critically, the Reference documentation is missing the PermissionRequest Input JSON schema. Developers cannot implement this hook without knowing what fields are passed to stdin (e.g., does it receive tool_input? tool_name? cwd?).

Suggested Improvement

In docs/en/hooks-guide.md:* Add PermissionRequest to the overview list:

• PermissionRequest: Runs when the permission system requires user confirmation (can auto-approve or deny)

In docs/en/hooks.md: Add a new section under Hook Input detailing the JSON schema. Based on the tool's behavior, it should likely look similar to this:

PermissionRequest Input

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm install"
  }
}

Impact

High - Prevents users from using a feature

Additional Context

• This feature was highlighted in Changelog 2.0.45: "Added PermissionRequest hook to automatically approve or deny tool permission requests with custom logic"
• The "Decision Control" output format is documented, but the Input format is missing.

[edsonbrusque]

Also, why this hook doesn't fire a command?

The "Stop" hook works on my environment (WSL) but "PermissionRequest" doesn't.

"Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"(New-Object Media.SoundPlayer 'C:\\Media\\chord.wav').PlaySync()\""
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"(New-Object Media.SoundPlayer 'C:\\Media\\chimes.wav').PlaySync()\""
          }
        ]
      }
    ],

[McBenac]

I can confirm this issue. PermissionRequest hook does not trigger in VSCode extension on Windows 11 either.

Tested with:

• matcher: "*"
• Simple PowerShell command to play a sound

PreToolUse hook works fine with identical config, but triggers on ALL tool calls (including auto-approved), making it unsuitable for notifications when human input is required.

Use case: Running multiple Claude Code sessions and needing audio alert when permission dialog appears.