Claude Code の hook イベント一覧 — matcher と if が効く場所
公式ドキュメントは、イベントの一覧・matcher の対象・if の適用範囲を別々の節に書いています。設定を書くときに必要なのは、それを1行で見比べた表なので、ここに作りました。
イベントと matcher
| イベント | matcher が当たる対象 | 値の例 |
|---|---|---|
PreToolUse | tool name | Edit|Write, Bash, mcp__server__.* |
PostToolUse | tool name | Edit|Write, Bash |
PostToolUseFailure | tool name | Bash |
PermissionRequest | tool name | Bash |
PermissionDenied | tool name | Bash |
SessionStart | how the session started | startup, resume, clear, compact, fork |
Setup | which CLI flag triggered setup | init, maintenance |
SessionEnd | why the session ended | clear, resume, logout, prompt_input_exit, other |
Notification | notification type | permission_prompt, idle_prompt, auth_success, agent_completed |
SubagentStart | agent type | general-purpose, Explore, Plan, custom names |
SubagentStop | agent type | same as SubagentStart |
PreCompact | what triggered compaction | manual, auto |
PostCompact | what triggered compaction | manual, auto |
PreModelSwitch | canonical name of the target model | claude-opus-5, .*opus.* |
PostModelSwitch | canonical name of the target model | claude-opus-5 |
ConfigChange | configuration source | user_settings, project_settings, local_settings, policy_settings, skills |
DirectoryAdded | how the directory was added | slash_command, register_repo_root |
FileChanged | literal filenames to watch | .envrc|.env |
StopFailure | error type | rate_limit, overloaded, authentication_failed, server_error |
InstructionsLoaded | load reason | session_start, nested_traversal, path_glob_match, include, compact |
UserPromptExpansion | command name | your skill or command names |
Elicitation | MCP server name | your configured MCP server names |
ElicitationResult | MCP server name | same as Elicitation |
matcher を書いても無視されるイベント
公式にこう書かれています。“If you add a matcher field to an event without matcher support, it is silently ignored.”
エラーは出ません。絞ったつもりのハンドラが毎回走ります。
CwdChanged, UserPromptSubmit, PostToolBatch, Stop, TeammateIdle, TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove, MessageDisplay
if が評価されるイベント
if はツール名と引数をまとめて見る絞り込みで、ツール系の5イベントでしか評価されません。それ以外で書くと、そのハンドラは一度も走りません。
PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied
ハンドラの必須フィールド
type ごとに要るものが違います。type を変えたときに前のフィールドが残るのがよくある形です。
| type | 必須 |
|---|---|
command | command |
http | url |
mcp_tool | server, tool |
prompt | prompt |
agent | prompt |
出典は Hooks（2026-09-04 時点）。この表は公式の記述から起こしたもので、公式そのものではありません。食い違いがあれば公式が正です。
この一覧をそのまま検査するツールを MIT で公開しています。.claude/ を読んで、無視される設定と非推奨の書き方を、根拠になっている公式ドキュメントへのリンク付きで指摘します。