Support PreToolUse matchers for EnterPlanMode and other built-in tools

Resolved 💬 2 comments Opened Feb 22, 2026 by evelynmitchell Closed Mar 22, 2026

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:

  1. Support built-in tool names as PreToolUse matchersEnterPlanMode, 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.
  1. 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.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗