From 46c8c3a26caa6b9d82208af60ef40163427e8ce9 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Mon, 8 Dec 2025 18:56:20 -0500
Subject: [PATCH] docs(hook-development): add PermissionRequest hook event
 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation for the PermissionRequest hook event which was missing
from the skill despite being in the official Claude Code documentation.
PermissionRequest runs when a permission dialog is shown and allows hooks
to automatically allow or deny permission requests.

Changes:
- Add PermissionRequest to skill description event list
- Add PermissionRequest section in Hook Events with example and output format
- Add PermissionRequest to Quick Reference table
- Add PermissionRequest to event-specific fields documentation
- Add PermissionRequest to validate-hook-schema.sh VALID_EVENTS array

Fixes #67

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../skills/hook-development/SKILL.md          | 53 ++++++++++++++++++-
 .../scripts/validate-hook-schema.sh           |  2 +-
 2 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md
index bcc696e..d9973d9 100644
--- a/plugins/plugin-dev/skills/hook-development/SKILL.md
+++ b/plugins/plugin-dev/skills/hook-development/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: hook-development
-description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
+description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
 ---
 
 # Hook Development for Claude Code Plugins
@@ -159,6 +159,54 @@ Execute before any tool runs. Use to approve, deny, or modify tool calls.
 }
 ```
 
+### PermissionRequest
+
+Execute when user is shown a permission dialog. Use to automatically allow or deny permissions.
+
+**Example:**
+
+```json
+{
+  "PermissionRequest": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-permission.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Output for PermissionRequest:**
+
+```json
+{
+  "hookSpecificOutput": {
+    "decision": {
+      "behavior": "allow|deny",
+      "updatedInput": {"command": "modified command"},
+      "message": "Reason for denial",
+      "interrupt": false
+    }
+  }
+}
+```
+
+- `behavior`: "allow" to approve, "deny" to reject
+- `updatedInput`: Optional modified tool parameters (only with "allow")
+- `message`: Explanation shown to user (only with "deny")
+- `interrupt`: If true with "deny", stops the current operation
+
+**Use cases:**
+
+- Auto-approve safe commands matching patterns
+- Block dangerous operations with explanations
+- Modify tool inputs before execution
+
 ### PostToolUse
 
 Execute after tool completes. Use to react to results, provide feedback, or log.
@@ -327,7 +375,7 @@ All hooks receive JSON via stdin with common fields:
 
 **Event-specific fields:**
 
-- **PreToolUse/PostToolUse:** `tool_name`, `tool_input`, `tool_result`
+- **PreToolUse/PermissionRequest/PostToolUse:** `tool_name`, `tool_input`, `tool_result`
 - **UserPromptSubmit:** `user_prompt`
 - **Stop/SubagentStop:** `reason`
 
@@ -596,6 +644,7 @@ echo "$output" | jq .
 | Event | When | Use For |
 |-------|------|---------|
 | PreToolUse | Before tool | Validation, modification |
+| PermissionRequest | Permission dialog | Auto-allow/deny |
 | PostToolUse | After tool | Feedback, logging |
 | UserPromptSubmit | User input | Context, validation |
 | Stop | Agent stopping | Completeness check |
diff --git a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh
index fed0a1f..11af5bc 100755
--- a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh
+++ b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh
@@ -38,7 +38,7 @@ echo "✅ Valid JSON"
 # Check 2: Root structure
 echo ""
 echo "Checking root structure..."
-VALID_EVENTS=("PreToolUse" "PostToolUse" "UserPromptSubmit" "Stop" "SubagentStop" "SessionStart" "SessionEnd" "PreCompact" "Notification")
+VALID_EVENTS=("PreToolUse" "PermissionRequest" "PostToolUse" "UserPromptSubmit" "Stop" "SubagentStop" "SessionStart" "SessionEnd" "PreCompact" "Notification")
 
 for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
   found=false