Hook Matchers

Control which tools trigger your hook. Regex-based matching on tool names.

Matcher Values

Matcher	Matches	Use for
`"Bash"`	Shell commands	Block rm -rf, approve safe commands
`"Edit"`	File edits (string replace)	Validate edits, protect files
`"Write"`	File creation/overwrite	Protect files, check content
`"Read"`	File reads	Block reading sensitive files
`"Glob"`	File pattern search	Rarely used in hooks
`"Grep"`	Content search	Rarely used in hooks
`"Agent"`	Subagent spawning	Limit concurrent agents
`"Skill"`	Skill invocation	Block opaque built-in skills
`"Edit\|Write"`	Any file modification	Syntax check, scope guard
`"Bash\|Edit\|Write"`	Commands + file changes	Broad protection
`""`	ALL tools	Logging, monitoring

Warning: Matcher "" applies to every tool call. If a hook with "" breaks (returns exit 2), ALL tools are blocked and the session becomes unrecoverable. Use "Bash" during development.

How Matching Works

Matchers are regex patterns tested against the tool name. "Edit|Write" means "matches Edit OR Write".

// settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",        // Only Bash commands
        "hooks": [{"type": "command", "command": "bash ~/.claude/hooks/guard.sh"}]
      },
      {
        "matcher": "Edit|Write",  // File modifications
        "hooks": [{"type": "command", "command": "bash ~/.claude/hooks/scope.sh"}]
      }
    ]
  }
}

Common Patterns

I want to...	Matcher
Block dangerous shell commands	`"Bash"`
Auto-approve safe commands	`"Bash"`
Check syntax after edits	`"Edit\|Write"`
Protect a specific file	`"Edit\|Write"`
Limit subagent count	`"Agent"`
Block opaque skills	`"Skill"`
Log everything	`""`
Monitor context usage	`""`

Best practice: Use the narrowest matcher possible. "Bash" is safer than "" because a broken hook only affects shell commands, not file reads or searches.