Claude Code hooksの種類一覧と使い分け

結論​（即答）​: Claude Code hooksとは

Claude Code hooks​（フック）は、​Claude Code が​セッション中の​決まった​場面で​自動的に​実行する​処理です。​設定ファイルに​「どの​場面で​（イベント）」​「何を​（ハンドラー）」​動かすかを​書いておくと、​Claude の​判断を​待たずに​プログラムが​動きます。

場面を​表すイベントは、​2026年10月20日時点の​公式リファレンスで​33種類あります。​全部を​覚える​必要は​ありません。​業務で​最初に​使うのは、​起動時の​ SessionStart、​ツール実行前の​ PreToolUse、​ツール実行後の​ PostToolUse、​応答終了時の​ Stop の​4つです。

できる​ことは​3つに​分かれます。

• 止める​: 危険な​コマンドの​実行を​拒否する。​テストが​通るまで​ Claude を​終わらせない
• 足す: 起動時に​前回の​作業メモを​読み込ませる。​ツールの​結果に​注意書きを​添える
• 記録する​: 会話の​要約を​ノートに​残す。​ファイルの​変更を​通知する

当社は​ Obsidian へ​作業記録を​自動で​貯める​目的で​導入し、​2026年10月20日時点で​33イベントの​うち14イベントを​常用しています。​形式は​すべて​シェルコマンド型​（command）で、​本体は​ Node.js の​短い​スクリプトです。

出典: Claude Code 公式ドキュメント​「フック リファレンス」​（2026年10月20日確認。​当社の​確認環境は​ Claude Code v2.1.304）

CLAUDE.md や​ permissions との​違い

CLAUDE.md に​書いた​指示は、​Claude が​読んで​従う​「お願い」です。​長い​会話では​読み落とされる​ことがあります。​hooks は​プログラムが​実行するので、​場面が​来る​たびに​動きます。

permissions​（権限ルール）は、​ツールごとに​「許可する、​拒否する、​確認する」を​決める​仕組みです。​hooks は​その前後に​任意の​処理を​挟む仕組みで、​PreToolUse から​許可や​拒否を​返すこともできます。​公式リファレンスも、​許可と​拒否​そのものは​権限システムで​決め、​hooks は​その​補助と​して​使う​よう​書いています。

hooksの​種類は​「いつ​動くか」と​「何が​動くか」の​2軸で​分かれる

hooks を​分類する​軸は​2つあります。​1つ目は​イベントで、​どの​場面で​動くかを​表します​（33種類）。​2つ目は​ハンドラーの​形式で、​何が​処理を​行うかを​表します​（5種類）。​設定は​「イベント → matcher​（絞り込み）​→ ハンドラー」の​3階層で​書きます。

公式リファレンスは、​イベントの​頻度を​3段階に​分けています。

残りの​イベントは、​サブエージェントの​起動、​コンテキストの​圧縮、​モデルの​切り​替えなど、​その​出来事が​起きたときだけ​発火します。

全3​3イベントの​一覧表​（発火タイミング、​matcherの​対象、​ブロック可否）

表の​「ブロック」は、​終了コード2または​ JSON で​処理を​止められるかを​表します。​「matcher の​対象」は、​その​イベントの​中で​さらに​絞り込める​条件です。

セッションの​開始と​終了

ユーザー入力と​応答

ツール呼び出しと​権限

サブエージェントと​タスク

環境、​設定、​ファイル

圧縮、​モデル、​MCP、​通知

出典: 公式リファレンスの​「フック ライフサイクル」​「Matcher パターン」​「イベントごとの​終了コード 2 動作」の​各表​（2026年10月20日確認）

止められるのは​「まだ​起きていない​こと」だけ

33イベントの​うち、​終了コード2で​処理を​止められるのは​16イベントです。​PermissionRequest は​終了コード2では​止まらず、​JSON の​ decision でだけ拒否できます。​合わせて​17イベントで、​hooks から​結果を​変えられます。

分かれ目は、​イベントが​「まだ​起きていない​こと」を​表すか​「すでに​起きた​こと」を​表すかです。​PreToolUse は​ツール呼び出しの​前なので​止められます。​PostToolUse は​ツールが​動いた​後なので​止められません。​SessionStart や​ PostModelSwitch も​同じ​理由で​止められません。

止められない​イベントにも​使い道は​あります。​PostToolUse は​ Claude に​見せる​結果を​ updatedToolOutput で​置き換えられ、​PermissionDenied は​ retry: true で​再試行を​促せ、​SessionStart は​ additionalContext で​文脈を​足せます。​「止める」以外の​出力は、​後の​「終了コードと​JSON出力の​読み方」で​扱います。

注意点が​2つあります。​1つは、​タイムアウトした​フックは​止める​役目を​果たさない​ことです。​PreToolUse の​フックが​時間切れに​なると、​ツール呼び出しは​通常の​権限フローで​続きます。​時間切れでも​止めたいときは​ onFailure: "block" を​付けます​（PreModelSwitch だけは​時間切れで​切り​替えが​止まります）。

もう​1つは​ Stop の​安全弁です。​Stop の​フックが​続行の​指示​（終了コード2か​ decision: "block"）を​8回連続で​返すと、​Claude Code は​それを​無視して​停止します。​Claude が​ツールを​呼ぶと​回数は​0に​戻り、​上限は​環境変数 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP で​変えられます。

出典: 公式リファレンス​「イベントごとの​終了コード 2 動作」​「タイムアウト」​「Stop」​（2026年10月20日確認）

ハンドラーの​形式は​5種類​（command、​http、​mcp_tool、​prompt、​agent）

イベントが​決まったら、​何に​処理を​させるかを​ type で​選びます。

当社は​ command だけを​使っています。​prompt と​ agent は​モデルの​呼び出しが​増える​ため、​その​分だけ​遅くなり、​利用枠も​消費します。​判断が​要る​検査でも、​まずは​シェルスクリプトで​書けないかを​考えます。

command には​書き方が​2つあります。args​ を​付けると​ exec 形式に​なり、​シェルを​介さずに​引数が​そのまま​渡ります。args​ を​付けないと​シェル形式に​なり、sh -c​ を​通ります​（Windows では​ Git Bash か​ PowerShell）。​パスを​含むコマンドは​ exec 形式の​ほうが​安全です。

長い​処理は​ "async": true で​バックグラウンドで​走らせられます。​Claude は​結果を​待たずに​進み、​処理が​終わると​ additionalContext や​ systemMessage が​次の​ターンで​届きます。​ただし非同期の​フックは​処理を​止められません。​止めたい​対象が​すでに​終わっている​ためです。

出典: 公式リファレンス​「フック ハンドラー フィールド」​「プロンプト ベースの​フック」​「エージェント ベースの​フック」​「バックグラウンドで​フックを​実行」​（2026年10月20日確認）

settings.jsonの​書き方と​置き場所

置き場所で​効く​範囲が​決まる

複数の​場所に​ある​ hooks は​置き換えではなく​合算されます。​プロジェクトの​設定が​ユーザーの​設定を​消すことは​ありません。​チームで​共有したい​規則は​ .claude/settings.json に、​自分だけで​使う​記録用の​フックは​ ~/.claude/settings.json に​置く​分け方が​基本です。

構造は​3階層

設定は​「イベント → matcher で​絞った​グループ → ハンドラーの​配列」の​3階層です。​次は​公式リファレンスに​ある​例で、rm -rf​ を​含む Bash コマンドを​拒否する​ PreToolUse の​設定です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

呼ばれる​スクリプトは、​標準入力の​ JSON から​コマンドを​取り出し、rm -rf​ を​含むときだけ拒否を​返します。

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0
fi

matcher の​書き方

正規表現は​値の​どこかに​一致すれば​通ります。Edit.*​ は​ NotebookEdit にも​一致するので、​完全に​一致させたいときは​ ^Edit$ と​書きます。​matcher を​持たない​イベント​（Stop、​UserPromptSubmit など）に​ matcher を​書いても​無視されます。

ハンドラーの​共通フィールド

設定した​ hooks は、​Claude Code の​中で​ /hooks と​打つと​一覧できます。​全部を​一時的に​無効に​するには​設定の​ disableAllHooks を​ true にします​（管理ポリシーの​フックは​無効に​なりません）。

出典: 公式リファレンス​「設定」の​各節​（2026年10月20日確認）

終了コードと​JSON出力の​読み方

フックは​2つの​経路で​ Claude Code に​結果を​伝えます。​終了コードと、​標準出力に​書く​ JSON です。

終了コードは​0、​2、​それ以外の​3通り

JSON で​返せる​共通フィールド

イベント固有の​出力は​ hookSpecificOutput に​まとめます。​よく​使うのは​次の​3つです。

• permissionDecision（PreToolUse）​: allow、​deny、​ask、​defer の​いずれか。​複数の​フックが​違う​答えを​返したら​ deny、​defer、​ask、​allow の​順で​強い​ほうが​勝つ
• updatedInput（PreToolUse、​PermissionRequest）​: ツールへの​入力を​丸ごと​差し替える
• additionalContext（多くの​イベント）​: Claude の​文脈に​文章を​足す。​上限は​10,000文字。​超えると​全文が​ファイルに​保存され、​Claude には​その​パスと​先頭2,000文字だけが​渡る

入力で​受け取る​共通フィールド

フックは​標準入力​（http ならリクエスト本体）で​ JSON を​受け取ります。​どの​イベントにも​ session_id、transcript_path​（会話ログの​パス）、cwd、hook_event_name​ が​入り、​ツール系なら​ tool_name と​ tool_input、​Stop なら​ last_assistant_message のように​イベント固有の​項目が​足されます。​サブエージェントの​中で​動いたときは​ agent_id と​ agent_type も​入ります。

標準出力には​ JSON 以外を​出さないようにします。​シェルの​起動時メッセージが​混ざるだけで​ JSON の​解釈に​失敗し、​終了コード0でも​「止めない​失敗」と​して​扱われます。

出典: 公式リファレンス​「フック入出力」​（2026年10月20日確認）

まず​入れる​なら、​この​4つ​（当社の​運用例）

導入の​経緯は​冒頭のとおりです。​当社の​設定は​ ~/.claude/settings.json に​14イベントを​登録したもので、​組み立て方は​ AIデータ基盤の​作り方​（2/3）​再現手順 に​載せています。

その​経験から、​最初に​入れる​価値が​高い順に​4つを​挙げます。

1. PreToolUse で​危険な​コマンドを​止める

対象は​ Bash、​条件は​ rm -rf や​ git push --force のような​取り返しの​つかない​操作です。rm -rf​ に​ついては​「settings.jsonの​書き方と​置き場所」の​ block-rm.sh が​そのまま​使え、git push --force​ は​同じ​スクリプトに​条件を​1行足すだけです。​拒否の​理由は​ Claude に​渡るので、​Claude は​別の​方法を​探します。

2. Stop で​作業記録を​自動保存する

Stop は​応答の​たびに​発火し、​入力の​ last_assistant_message に​最後の​応答が​入ります。​当社は​これを​デイリーノートの​決まった​位置に​追記しています。​失敗しても​会話を​止めないよう、​例外は​ログに​落として​終了コード0で​返します。

3. SessionStart で​前回の​文脈を​読み込ませる

additionalContext に​文章を​返すと、​起動直後の​ Claude が​それを​読んだ​状態で​始まります。​当社は​並行する​複数の​会話の​直近の​発言を​注入し、​「さっきの​あれ」が​別の​会話でも​通じるように​しています。​プラグインが​同じ​仕組みを​使うことも​あり、​当社の​環境では​ Vercel の​プラグインが​ SessionStart で​自身の​使い方の​案内を​毎回注入しています。

4. PostToolUse で​フォーマッターや​テストを​回す

matcher を​ Edit|Write にし、​ファイルが​書かれる​たびに​整形や​テストを​走らせます。​時間の​かかる​テストは​ "async": true に​して​ Claude を​待た​せず、​結果は​次の​ターンで​受け取ります。

書くときの​約束

• 記録用の​フックは、​失敗しても​会話を​止めない​（例外は​捕捉して​ログに​残し、​終了コード0で​返す）
• ノートや​ログへの​書き込みは​追記だけにし、​既存の​行を​書き換えない
• スクリプトは​絶対パスで​指し、​シェル変数は​ "$VAR" のように​引用符で​囲む
• .env や​鍵の​ファイルには​触らない

出典: 当社の​設定​（2026年10月20日確認）、​AIデータ基盤の​作り方​（2/3）​再現手順、​公式リファレンス​「セキュリティ ベストプラクティス」

つまずきやすい点と​制限

信頼していない​フォルダの​フックも​動く​ことがある

対話セッションでは、​フォルダを​信頼するかの​確認に​応じるまで​設定ファイルの​フックは​動きません。​一方、-p​ で​動かす非対話モードや​ SDK からの​実行では​ダイアログが​出ず、​リポジトリに​コミットされた​ .claude/settings.json の​フックが​そのまま​動きます。​他人の​リポジトリを​ claude -p で​動かす前には、.claude/​ の​中身を​確認するか、--bare​ で​起動するか、--settings '{"disableAllHooks": true}'​ で​無効にします。

タイムアウトの​既定値は​イベントで​違う

command、​http、​mcp_tool は​600秒、​prompt は​30秒、​agent は​60秒です。​ただし UserPromptSubmit、​PreModelSwitch、​PostModelSwitch では​ command、​http、​mcp_tool も​30秒、​MessageDisplay は​10秒に​下がります。​SessionEnd は​全フックで​1.5秒の​予算を​共有し、​個別に​ timeout を​書くと​最大60秒まで​延びます。

PreToolUse は​ @ 指定の​ファイル読み込みでは​発火しない

プロンプトに​ @ファイル名 と​書いた​読み込みは、​ツール呼び出しではないので​ PreToolUse を​通りません。​ファイルの​読み取りを​ hooks で​守る​つもりなら、​この​抜け道を​前提に​設計します。​公式リファレンスは​回避策と​して​環境変数 CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 を​挙げています。

止めた​プロンプトは​消えない

UserPromptSubmit で​プロンプトを​止めても、​原文は、​止めたときに​表示される​メッセージと、​ディスク上の​会話ログに​残ります。suppressOriginalPrompt​ は、​表示される​メッセージから​原文を​外すだけです。​機密情報の​流出防止を​ hooks で​止める​ことに​頼るわけには​いきません。

非同期フックは​ -p では​終了時に​打ち切られる

"async": true の​フックの​結果が​届くのは、​セッションが​動いている​間だけです。​非対話モードでは、​セッション終了時に​まだ​走っている​非同期フックは​強制終了されます。​セッションより​長く​続けたい​処理は、​フックから​切り離した​別プロセスと​して​起動します。

Windows の​ PowerShell では​変数の​書き方に​注意

PowerShell の​フックで​ $CLAUDE_PROJECT_DIR と​裸で​書くと、​未定義の​変数と​して​ $null に​なります。${CLAUDE_PROJECT_DIR}​ か​ $env:CLAUDE_PROJECT_DIR を​使います。

動かないときの​調べ方

まず​ /hooks で​読み込まれているかを​見ます。​次に​ claude --debug で​起動すると、​ログが​ ~/.claude/debug/<session-id>.txt に​出ます。​v2.1.296 以降は、​フックごとに​ Hooks: PostToolUse:Write [...] finished with status 0 (31ms) のような​1行が​残り、​遅いフックも​見つけられます。

出典: 公式リファレンス​「セキュリティに​関する​考慮事項」​「タイムアウト」​「フックを​デバッグ」​（2026年10月20日確認）

よく​ある​質問

hooks を​使うと​料金は​かかりますか？

command、​http、​mcp_tool の​フックは​ Claude の​モデルを​呼ばないので、​フック自体は​ Claude の​利用枠を​使いません。​ただし additionalContext で​足した​文章は​次の​呼び出しの​入力に​含まれます。​prompt と​ agent は​モデルを​呼びます。​agent は​最大50ターン動くので、​頻繁に​発火する​イベントには​向きません。

CLAUDE.md に​書くのと​何が​違いますか？

CLAUDE.md は​ Claude が​読む指示で、​従うか​どうかは​ Claude の​判断です。​hooks は​プログラムが​実行するので、​Claude の​判断を​介さずに​動きます。​「毎回起こしたい​こと」は​ hooks、​「状況に​応じて​判断して​ほしい​こと」は​ CLAUDE.md に​書きます。

チームで​共有するには​どこに​書きますか？

プロジェクトの​ .claude/settings.json に​書いて​コミットします。​個人の​ PC だけで​動かしたいものは​ ~/.claude/settings.json か​ .claude/settings.local.json です。

サブエージェントの​中でも​動きますか？

動きます。​設定ファイル、​管理ポリシー、​プラグインの​フックは​サブエージェントの​中でも​発火し、​入力に​ agent_id と​ agent_type が​入るので、​本体の​会話と​区別できます。

プラグインや​スキルにも​ hooks を​持たせられますか？

持たせられます。​プラグインは​ hooks/hooks.json、​スキルと​サブエージェントは​フロントマターに​書きます。​スキルの​フックは​ once: true で​初回だけ動かせます。

設定したのに​動かないときは​どこを​見ますか？

まず​ /hooks に​出ているかを​確かめます。​出ていなければ、​フォルダの​信頼、​JSON の​構文、​置き場所を​疑います。​出ているのに​動かないなら​ claude --debug の​ログで​ matcher の​一致を​見ます。​終了コード0で​ JSON を​返しているのに​効かないときは、​標準出力に​ JSON 以外の​文字が​混ざっていないかを​確かめます。

MCP と​ hooks は​どう​違いますか？

MCP は​ Claude に​新しい​ツール​（外部​サービスの​操作など）を​与える​仕組みで、​使うか​どうかは​ Claude が​決めます。​hooks は​ Claude の​動作の​前後に​処理を​挟む仕組みで、​Claude の​判断を​待ちません。​両者は​組み合わせられ、mcp_tool​ 形式を​使えば、​フックから​ MCP の​ツールを​呼べます。

関連リンク

• AIデータ基盤の​作り方​（2/3）​再現手順: 当社の​ Stop、​PreCompact、​SessionStart の​ hooks と​ Obsidian の​組み合わせ
• AI事業​（AIコーチング、​週次AIリサーチ）​: 当社の​ AI 導入支援
• お問い​合わせ: hooks や​作業記録の​自動化の​ご相談
• 公式ドキュメント: フック リファレンス、​フック ガイド（2026年10月20日確認）

Obsidian 連携や​ Claude Fable 5.1 の​記事など、​関連する​他の​リサーチは​この​下の​一覧に​あります。