[DOCS] Hooks reference lists incomplete set of matchable tool names for PreToolUse and PermissionRequest

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

• "PreToolUse" section (tool name list and tool_input schemas)
• "PermissionRequest" section (matchable tool names)
• "Matcher patterns" table

Current Documentation

The PreToolUse section states:

Matches on tool name: Bash, Edit, Write, Read, Glob, Grep, Task, WebFetch, WebSearch, and any MCP tool names.

The PreToolUse section then documents tool_input schemas for only these tools: Bash, Write, Edit, Read, Glob, Grep, WebFetch, WebSearch, Task.

The PermissionRequest section states:

Matches on tool name, same values as PreToolUse.

What's Wrong or Missing?

A. Three permission-requiring tools are missing from the tool name list

The Settings > Tools page lists these tools as requiring permission (column: "Requires permission: Yes"):

| Tool | Documented in hooks reference? |
|------|-------------------------------|
| Bash | Yes |
| Edit | Yes |
| ExitPlanMode | No |
| NotebookEdit | No |
| Skill | No |
| WebFetch | Yes |
| WebSearch | Yes |
| Write | Yes |

ExitPlanMode, NotebookEdit, and Skill all require permission per the settings page, meaning they fire PermissionRequest events and can be matched in PreToolUse hooks. But the hooks reference doesn't list them as valid tool names and doesn't document their tool_input schemas.

B. "Same values as PreToolUse" is misleading for PermissionRequest

The PermissionRequest section says it matches "same values as PreToolUse." But PermissionRequest specifically fires when a permission dialog appears — so it fires for every tool with "Requires permission: Yes" in the settings page. This includes ExitPlanMode, which is arguably the most common PermissionRequest use case (auto-approving plan mode), yet isn't listed as a PreToolUse matcher value either.

C. No tool_input schemas for the missing tools

The PreToolUse section documents detailed tool_input schemas (field names, types, examples) for each listed tool. ExitPlanMode, NotebookEdit, and Skill have no documented tool_input schema. Hook authors targeting these tools must guess what fields are available on stdin.

For example, community implementations of ExitPlanMode hooks access tool_input.plan (the plan content), but this field is entirely undocumented. See: https://github.com/yigitkonur/hooks-claude-approve

Suggested Improvement

A. Add missing tools to the PreToolUse tool name list

Update the PreToolUse introduction to:

Matches on tool name: Bash, Edit, ExitPlanMode, Glob, Grep, NotebookEdit, Read, Skill, Task, WebFetch, WebSearch, and any MCP tool names.

B. Add tool_input schemas for the missing tools

Add documentation blocks for ExitPlanMode, NotebookEdit, and Skill in the PreToolUse input section, following the same format as the existing tool schemas. For example:

ExitPlanMode — Prompts the user to exit plan mode and start coding.

| Field | Type | Description |
|:------|:-----|:------------|
| plan | string | The plan content (may be absent if plan was written to a file) |

NotebookEdit — Modifies Jupyter notebook cells.

| Field | Type | Description |
|:------|:-----|:------------|
| notebook_path | string | Absolute path to the notebook |
| new_source | string | New cell content |
| cell_type | string | "code" or "markdown" |
| edit_mode | string | "replace", "insert", or "delete" |

Skill — Executes a skill within the conversation.

| Field | Type | Description |
|:------|:-----|:------------|
| skill | string | The skill name |
| args | string | Optional arguments for the skill |

(Exact field names should be verified against the implementation.)

C. Clarify PermissionRequest scope

Update the PermissionRequest matcher description from:

Matches on tool name, same values as PreToolUse.

To something like:

Matches on tool name. Any tool that requires permission (listed in the Tools table) can trigger this event: Bash, Edit, ExitPlanMode, NotebookEdit, Skill, WebFetch, WebSearch, Write, and MCP tools.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Section | Issue |
|------|---------|-------|
| https://code.claude.com/docs/en/hooks | PreToolUse | Tool name list missing ExitPlanMode, NotebookEdit, Skill |
| https://code.claude.com/docs/en/hooks | PreToolUse input | No tool_input schemas for ExitPlanMode, NotebookEdit, Skill |
| https://code.claude.com/docs/en/hooks | PermissionRequest | "same values as PreToolUse" understates its scope |
| https://code.claude.com/docs/en/hooks | Matcher patterns table | Tool events row doesn't mention ExitPlanMode, NotebookEdit, Skill |
| https://code.claude.com/docs/en/hooks-guide | Filter hooks with matchers | Only shows Bash/Edit/Write examples |

Total scope: 2 pages affected (hooks reference, hooks guide)

Cross-reference: The Settings > Tools table correctly lists all tools with their permission requirements. The hooks docs should be consistent with this authoritative list.

Community evidence: The hooks-claude-approve project uses "matcher": "ExitPlanMode" on PermissionRequest hooks and accesses tool_input.plan — both undocumented in the official docs. The repo's README includes a note that "Many implementations try hooking Stop and grepping the transcript" because users can't discover ExitPlanMode as the correct approach from the documentation.