docs(hook-development): add PermissionRequest hook event documentation (#69)

## Summary
- Added documentation for the PermissionRequest hook event
- Updated validate-hook-schema.sh to recognize PermissionRequest as a
valid event
- PermissionRequest allows automatic allow/deny of permission dialogs

## Problem
Fixes #67

The hook-development skill was missing documentation for
PermissionRequest, which is a valid hook event in the official Claude
Code documentation. This caused:
1. Users not knowing about this capability
2. The validation script incorrectly warning about PermissionRequest
being unknown

## Solution
Added comprehensive documentation for PermissionRequest:
- New section in Hook Events with example configuration and output
format
- Added to skill description trigger list
- Added to Quick Reference table
- Added to event-specific input fields
- Added to VALID_EVENTS in validate-hook-schema.sh

### Alternatives Considered
- **Document as "not supported for plugins"**: Rejected because official
docs show it's available
- **Minimal one-line addition**: Rejected because consistent
documentation requires the same treatment as other events

## Changes
- `plugins/plugin-dev/skills/hook-development/SKILL.md`: Added
PermissionRequest documentation (+50 lines)
-
`plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh`:
Added PermissionRequest to VALID_EVENTS

## Testing
- [x] Markdownlint passes
- [x] Shellcheck shows only pre-existing warnings (not related to this
change)
- [x] Documentation follows existing patterns

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

Co-authored-by: Claude <noreply@anthropic.com>

Author: sjnims

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 |

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