Support PreToolUse matchers for EnterPlanMode and other built-in tools
Problem
When configuring PreToolUse hooks, only a subset of tools are documented as valid matchers (Bash, Edit, Write, Read, Glob, Grep, WebFetch, WebSearch, Task, Notebook.*). Built-in tools like EnterPlanMode, ExitPlanMode, and EnterWorktree are not mentioned.
I wanted to run a shell script when Claude enters plan mode (to check git branch hygiene before starting a new task). The natural configuration would be:
{
"hooks": {
"PreToolUse": [
{
"matcher": "EnterPlanMode",
"hooks": [{"type": "command", "command": ".claude/hooks/check-branch.sh"}]
}
]
}
}
This doesn't work. I also tried SubagentStart with matcher Plan (documented but didn't fire in testing). The workaround I landed on is PreToolUse(Task) with a JSON filter inside the script that reads tool_input.subagent_type from stdin — but this only catches plan mode when it's delegated to a subagent, not inline EnterPlanMode.
Iterations tried
| Config | Result |
|--------|--------|
| PreToolUse + EnterPlanMode | Never fires |
| SubagentStart + Plan | Never fires (despite being documented) |
| PreToolUse + Task + stdin filter | Works for subagent launches, but not inline plan mode |
Request
Either:
- Support built-in tool names as PreToolUse matchers —
EnterPlanMode,ExitPlanMode,EnterWorktree,TaskCreate,TaskUpdate, etc. These are real tool calls that show up in transcripts; letting hooks match on them would be straightforward and powerful.
- Or document an exhaustive list of valid matchers for each hook event, so users don't have to discover what works through trial and error.
Use case
Auto-creating a fresh git branch when entering plan mode, to prevent starting work on a stale/merged branch. This is a common workflow issue when using Claude Code for multi-PR development.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗