Claude Codeのhooks一覧｜どのイベントに何を仕込むか

Claude Codeのhooksは、種類を把握しないまま書くと「効かせたつもりが効いていない」事故につながります。hooksは自動化4層の1つで、全体像は『AIエージェントの自動化｜hooks・定期実行・常駐の役割分担』で扱いました。本記事は公式ドキュメントの全30種類を発火タイミングで整理し、逆引きする判断基準を示します。個別実装は別記事へ送り、一覧と選び方に絞ります。

検証環境：claude-opus-5 / Claude Code v2.1.x / macOS 15 / 2026-07-29検証。

01結論：Claude Codeのhooksは30種類｜まず「発火条件」で絞り込む

結論は3点です。

1. hooksは常駐しません。対応するイベントが起きるまで、スクリプトは1行も動きません。
2. 本記事では30種類を5グループへ整理します（グループ名は次章の一覧表で示します。この分類は本記事の独自編集です。公式ドキュメントはイベントを「セッションに1回」「ターンに1回」「ツール呼び出しごと」という3つの発火頻度でしか説明していません）。
3. 選ぶ基準は「いつ発火するか」と「実行や継続をブロックできるか」の2軸です。外すと発火しない・止められないhooksを作ります。

危険コマンドの遮断は『Claude CodeのPreToolUseフック｜危険コマンド遮断のコード例』にコードつきでまとめています。

02Claude Code hooksの全イベント一覧｜30種を5グループで見る

Claude Code公式ドキュメントの「Hook lifecycle」表を数えると、hooksイベントは30種類です（2026-07-29に公式ドキュメントを取得して実数を確認）。

30種類のうち、ブロック可否が「可」なのは17種類、「不可」は13種類です（2026-07-29実測）。「不可」の多くはヒント注入かログ・副作用専用の設計です。

30種類を全部使う必要はありません。取り消せない操作に近いイベント（PreToolUse・SessionStart等）から優先登録し、観測用途は後回しにする優先順位づけが実務で機能します。

03hooksでツール実行を制御する｜PreToolUse・PermissionRequest・PostToolUseの境界

ツール実行グループの6種類は名前が似て混同しやすい領域です。判断軸は「呼び出しの前か後か」と「誰の判断を経由するか」です。

PreToolUseはツール実行の直前に発火しpermissionDecisionをallow・deny・ask・deferで返します。deferは「判断しない」の意味で通常の権限フロー（permissions設定やユーザー確認）に処理を戻すだけで、自律度を下げる値ではありません。

PermissionRequestはPreToolUseとは別の入り口です。許可判定が要る局面で発火し、hookSpecificOutput.decision.behaviorにallowかdenyを返します。

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "updatedInput": {}
    }
  }
}

PermissionDeniedは自動モードの分類器が拒否した直後に発火します。exit codeとstderrは無視され、retryフィールドだけが意味を持ちます（出典: Claude Code公式ドキュメント）。

PostToolUse・PostToolUseFailure・PostToolBatchは実行後の3種です。成功時はPostToolUse、失敗時はPostToolUseFailure、並列ツール群の全解決後・次呼び出し直前はPostToolBatchが発火します。PostToolUseはupdatedToolOutputで結果を書き換えられ、機密マスキングや要約に向きます。

04hooksでセッションと環境を制御する｜SessionStart・ConfigChange・FileChangedの境界

セッションの生死・環境グループの11種類は「開始・終了」と「セッション中の環境変化の検知」の2層に分かれます。

SessionStartはsourceフィールド（startup・resume・clear・compact・forkの5パターン）で発火元を区別できます。返せるフィールドは5つです。

• additionalContext：文脈を注入
• initialUserMessage：最初のプロンプトを設定
• watchPaths：監視対象ファイルを指定
• sessionTitle：セッション名を設定
• reloadSkills：スキルを再読み込み

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "必読ルールの要約テキスト",
    "reloadSkills": true
  }
}

起動のたびに必読ルールを自動で読み込ませる実装は、専用の手順記事で扱う予定です。本記事ではSessionStartが「ブロックできない・文脈注入専用」という一点を押さえてください。

ConfigChange・CwdChanged・InstructionsLoaded・FileChangedはセッション外側の変化検知層です。唯一ブロック可能なConfigChangeはdecision: blockで止まり（policy_settings除く）、残り3種は環境同期・ログ用途です。

05どのhooksイベントを使うか｜やりたいことから逆引きする判断基準

「何をしたいか」から使うイベントを引く表です。

判断に迷う場合は、上から順に「取り消せない操作か」「ブロックしたいか」「観測だけでよいか」の3問を自分に投げてください。

06hooksの設定方法と入出力の共通スキーマ｜settings.jsonへの登録

hooksを書ける場所は6箇所あります（出典: Claude Code公式ドキュメント）。

チーム共有hooksは.claude/settings.jsonに書いてGitで共有し、個人の一時的な上書きはLocalへ置きます。permissionsのallow・ask・denyとhooksの配分は『Claude Codeの権限設定｜allow・ask・denyの配分と設定例』で扱っています。

matcherの書き方は3パターンです（出典: Claude Code公式ドキュメント）。*・空文字・省略は全件一致、英数字・_・-・空白・,・|だけの文字列は完全一致かリスト指定です。ハイフンが完全一致に含まれるのはv2.1.195以降のみで、それ以前はcode-reviewerも正規表現扱いとなりsenior-code-reviewerに誤爆します。それ以外を含むと正規表現評価です（例：Bash=完全一致／Edit|Write=リスト／mcp__memory__.*=正規表現）。

FileChangedとStopFailureは例外です。英数字・_・|のみが完全一致となり、ハイフン・空白・カンマを含めると他のイベントより先に正規表現として評価されます。

hookの実行方式（type）は5種類です（出典: Claude Code公式ドキュメント）。シェルコマンドcommand・URLへPOSTするhttp・MCPツールを呼ぶmcp_toolが基本です。モデルにYes/No判定させるprompt・検証用サブエージェントのagentが加わります。デフォルトタイムアウトはcommand・http・mcp_toolが600秒、promptが30秒、agentが60秒です。

全イベントの入力フィールドはsession_id・transcript_path・cwd・hook_event_name・permission_modeです。サブエージェント内ではagent_id・agent_typeも加わります。

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse"
}

出力側の共通フィールドはcontinue・stopReason・suppressOutput・systemMessageです。固有判定はhookSpecificOutput内に書きます。

07hooksでつまずきやすい点｜設定と実装がずれる3つの落とし穴

落とし穴1：matcherに*を書いて、意図せず正規表現になる。 *は完全一致の文字集合に含まれず、Bash*は「直前の文字の0回以上の繰り返し」を意味する正規表現になり、想定と違う一致を生みます。

落とし穴2：SessionEndの合計予算1.5秒を知らずに重い処理を書く。 SessionEndは複数登録しても合計1.5秒の共有予算しかありません（出典: Claude Code公式ドキュメント）。timeout指定で最大60秒まで延びますが、既定値のままログ送信やAPI呼び出しを書くと打ち切られます。

落とし穴3：PermissionDeniedをPreToolUseと同じ感覚で実装する。 exit code 2はPreToolUseで効きますが、PermissionDeniedでは無視され、読むのはretryフィールドだけです。

matcherとtypeの挙動はイベントをまたいで統一されていません。公式ドキュメントを都度確認し、類推で実装しないことが要です。

08hooksを整えるチェックリスト

• 実行前に止めたい操作をPreToolUseのdeny対象として洗い出したか
• 使うイベントを「発火タイミング」と「ブロックできるか」の2軸で選んだか
• matcherに*など正規表現化する文字を意図せず混ぜていないか
• settings.jsonのどの置き場所（User/Project/Local/Managed等）に書くか決めたか
• 短いデフォルトタイムアウト（UserPromptSubmit 30秒・MessageDisplay 10秒・SessionEnd 1.5秒）を把握したか
• /hooksコマンドで登録内容を確認したか
• PreToolUseの詳しい実装は専用記事へ委ね、判断基準だけを使ったか

09FAQ