[DOCS] Hooks docs mention auto-approval scripts but provide no end-to-end PermissionRequest or PreToolUse auto-approve example

Documentation Type

Missing code examples

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

• hooks reference: decision control examples and cross-reference to guide
• hooks-guide: "What you can automate" examples
• hooks-guide: non-interactive limitation note for PermissionRequest

Current Documentation

The hooks reference currently says:

For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see What you can automate in the guide...

But the hooks guide's "What you can automate" section only lists four common patterns:

• Get notified when Claude needs input
• Auto-format code after edits
• Block edits to protected files
• Re-inject context after compaction

And later in the guide:

PermissionRequest hooks do not fire in non-interactive mode (-p). Use PreToolUse hooks for automated permission decisions.

What's Wrong or Missing?

A. Reference points to auto-approval scripts that are not present in the guide

The hooks reference explicitly points readers to the guide for "auto-approval scripts," but the guide does not include an end-to-end auto-approval script for either:

• interactive mode (PermissionRequest), or
• non-interactive mode (PreToolUse, which the guide itself recommends for automation in -p mode).

B. High-friction workflow has no copy-paste example

Plan-approval automation is a common workflow (for example, matching PermissionRequest on ExitPlanMode), but users only get conceptual text and have to piece JSON structure together from multiple sections/pages.

C. The docs provide building blocks but not a minimal safe pattern

The reference documents fields and schemas, but there is no practical "safe default" example that shows:

• exact event and matcher,
• minimal decision payload,
• when to use allow vs ask,
• and caveats for unattended approval.

Suggested Improvement

Add a dedicated subsection in hooks-guide under "What you can automate," such as:

Auto-approve specific permission prompts

Provide two complete examples:

1. Interactive mode (PermissionRequest)

• matcher: ExitPlanMode (or another narrow tool matcher)
• output: hookSpecificOutput.decision.behavior: "allow"
• optional: updatedPermissions
• caution: keep matcher narrow to avoid over-broad approvals

1. Non-interactive mode (PreToolUse)

• equivalent automation using permissionDecision: "allow" / "ask"
• explain this is the supported path for -p mode

Also update the hooks reference cross-link sentence so it only claims examples that actually exist on the guide page.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Section | Issue |
|------|---------|-------|
| https://code.claude.com/docs/en/hooks | Decision control examples (cross-reference sentence) | Says guide includes auto-approval scripts |
| https://code.claude.com/docs/en/hooks-guide | What you can automate | No auto-approval example despite reference |
| https://code.claude.com/docs/en/hooks-guide | Limitations | Says to use PreToolUse for automated permission decisions in -p, but no concrete example |

Total scope: 2 pages affected

Community evidence: https://github.com/yigitkonur/hooks-claude-approve exists specifically to auto-approve PermissionRequest for ExitPlanMode, which suggests a real demand for a first-party example in docs.