Claude Code のフックを理解する：エージェントを取り囲む確定的なレイヤー

Claude Code のフックとは？ フックとは、ユーザーが定義するシェルコマンド（さらに HTTP エンドポイント、MCP ツール、モデルへのプロンプトも含みます）であり、Claude Code がライフサイクルの決まった地点で自動的に実行するものです。ツール呼び出しの前、編集の後、セッション開始時、Claude が応答を終えたとき、といったタイミングです。¹ CLAUDE.md がモデルにおそらく従うであろう指示を与えるのに対し、フックはモデルが協力するかどうかにかかわらず実行されます。セッション内で /hooks と入力すれば、すべてのライフサイクルイベントと、それぞれに何が結び付けられているかを確認できます。 {.answer-block}

多くの開発者は、2つの制御レイヤーで Claude Code を運用しています。エージェントに何を許すかを制御する権限と、エージェントが何をすべきかを記述する CLAUDE.md です。フックは3つ目のレイヤーであり、何かを保証できる唯一のレイヤーです。以下では、考え方の枠組み、現行ドキュメントに載っているすべてのライフサイクルイベント、正確な入出力の取り決め、設定方法、動作する5つのパターン、そして判断の枠組みを扱います。API に関する詳細はすべて、2026年7月1日時点の公式フックリファレンスおよびガイドと照合して検証しています。このシステムは変化が速いため、本記事とリファレンスが食い違う場合はリファレンスが正です。（Claude Code は初めてですか？　まずは5分でできるセットアップ、またはClaude Code 入門ガイドからどうぞ。）

要点： フックは stdin から JSON を受け取り、終了コードまたは stdout に出力する JSON で応答します。終了コード0は許可、終了コード2はブロック（ブロック可能なイベントの場合）を意味し、Unix で慣習的に失敗を表す終了コード1は何もブロックしません。これがフックで最も陥りやすい落とし穴です。² 設定は settings.json の中で、PreToolUse や Stop といったイベント名の下に記述し、マッチャーで絞り込みます。必ず起きなければならないことにはフックを使い、モデルが単に知っておけばよいことには CLAUDE.md を使いましょう。

考え方の枠組み：非決定的な中核を取り囲む保証

コーディングエージェントは確率的なシステムです。編集のたびに Prettier を実行するよう頼めば、たいていは実行してくれます。しかし、変更が些細に見えるとき、コンテキストが長くなったとき、あるいは指示の言い回しが違って受け取られたときには、その手順を飛ばすかもしれません。CLAUDE.md、スキル、プロンプトはいずれも提案にすぎません。質は高く、たいてい従われますが、決して保証はされないのです。

フックは、その中核を取り囲む確定的な殻です。公式の定義はこうです。「Claude Code のライフサイクルの特定の地点で自動的に実行される、ユーザー定義のシェルコマンド、HTTP エンドポイント、またはLLMへのプロンプト」であり、「Claude Code の挙動を確定的に制御し、LLMが実行を選ぶことに頼るのではなく、特定の動作が必ず起きるようにする」ものです。³ フォーマッターは編集のたびに発火します。コマンドガードはすべての Bash 呼び出しを評価します。完了ゲートはすべての終了時に検査します。

この強制は見せかけではなく本物です。PreToolUse フックはあらゆる権限モードの検査より前に発火するため、permissionDecision: "deny" を返すフックは、bypassPermissions モードや --dangerously-skip-permissions の下であってもツールをブロックします。ただし逆は成り立ちません。"allow" を返すフックでも、設定ファイルの拒否ルールを緩めることはできません。フックは権限が許す範囲を超えてポリシーを厳しくすることはできても、緩めることは決してできないのです。⁴

ライフサイクル：すべてのフックイベント

2026年7月1日時点で、リファレンスには30個のフックイベントが記載されています。¹ これらは3つの周期に分けられます。セッションにつき1回のもの（SessionStart、SessionEnd）、ターンにつき1回のもの（UserPromptSubmit、Stop、StopFailure）、そしてエージェントループ内のツール呼び出しのたびに発火するもの（PreToolUse、PostToolUse）です。残りは特定の条件で発火します。設定変更、コンテキストの圧縮、サブエージェント、MCP とのやり取りなどです。

これらの大半は使うことはないでしょう。実運用の構成のほぼすべては、次の5つから組み立てられます。PreToolUse、PostToolUse、UserPromptSubmit、SessionStart、Stop です。残りは、必要になる日のために用意されています。

取り決め：JSON を入力し、終了コードまたは JSON を出力する

コマンド型のフックは stdin から JSON を受け取り、終了コード、stdout、stderr を通じて応答します。（HTTP 型のフックは同じ JSON を POST のボディとして受け取り、レスポンスボディを通じて応答します。）²

どのイベントも共通の外枠を届けます。session_id、transcript_path、cwd、hook_event_name（大半のイベントでは permission_mode も）に加えて、イベント固有のフィールドが付きます。Bash コマンドに対する PreToolUse フックは、次のような内容を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

ほかのイベントでは末尾が入れ替わります。UserPromptSubmit は prompt を、SessionStart は source（startup/resume/clear/compact）を、Stop は stop_hook_active と last_assistant_message を運びます。サブエージェント内で発火したフックは、加えて agent_id と agent_type を受け取ります。²

終了コード

結果は3通りです。²

• 終了コード0 — 成功。Claude Code は stdout を解析して JSON の出力フィールドを読み取ります。大半のイベントでは stdout はデバッグログに送られるだけですが、UserPromptSubmit、UserPromptExpansion、SessionStart では、素の stdout が Claude の見えるコンテキストとして追加されます。
• 終了コード2 — ブロックを伴うエラー。stdout（JSON を含めて）は無視され、stderr がエラーメッセージとして Claude に返されます。「ブロック」が何を意味するかはイベントによって異なります。
• それ以外の終了コード — ブロックを伴わないエラー。記録には <hook name> hook error という通知が表示され、実行はそのまま続きます。

この最後の点は強調に値します。終了コード1は何もブロックしません。 ドキュメントもこの点を直接注意喚起しています。1は Unix で慣習的に失敗を表す終了コードであるにもかかわらず、Claude Code は終了コード1をブロックを伴わないエラーとして扱い、処理を続けてしまうのです。ポリシーを課すフックは必ず exit 2 としなければなりません。²

終了コード2がイベントごとに何をするか、以下にまとめます。²

それ以外はブロックできません。PostToolUse と PostToolUseFailure は stderr を Claude に見せます（ツールはすでに実行済みです）。SessionStart、Notification、SessionEnd、CwdChanged、FileChanged、PostCompact、SubagentStart、Setup は stderr をユーザーにだけ見せます。StopFailure、InstructionsLoaded、MessageDisplay、PermissionDenied は終了コードを無視します。PermissionDenied で使える唯一の手立ては JSON の retry: true です。²

JSON による出力

ブロックか黙認かよりも細やかに制御したい場合は、終了コード0で終え、JSON オブジェクトを stdout に出力します。最初に一つ原則を。終了コードか JSON か、どちらか一方であって両方ではありません。 JSON は終了コード0のときにしか処理されず、終了コード2はそれを破棄します。⁵

共通フィールドはどのイベントでも機能します。continue: false は Claude を完全に停止させ（stopReason がユーザーに表示されます）、suppressOutput は stdout を記録から隠し、systemMessage はユーザーに警告を表示し、terminalSequence は許可リストに載ったターミナルのエスケープシーケンス（デスクトップ通知、ウィンドウタイトル、ベル）を送出します。判断用のフィールドはイベントごとに異なります。⁵

人がよくつまずく点が2つあります。1つ目。PreToolUse はトップレベルの decision パターンの例外です。かつてはトップレベルの decision/reason を使っていましたが、このイベントでは非推奨となりました（"approve"/"block" は "allow"/"deny" に対応します）。hookSpecificOutput.permissionDecision を使ってください。⁵ 2つ目。複数の PreToolUse フックの判断が食い違った場合、優先順位は deny > defer > ask > allow です。⁵

設定：settings.json、マッチャー、スコープ

フックの設定は3段階の入れ子になっています。イベントを選び、発火のタイミングを絞り込むマッチャーグループを加え、実行するフックハンドラーを1つ以上定義します。⁶

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "/path/to/lint-check.sh" }
        ]
      }
    ]
  }
}

これをどこに置くかでスコープが決まります。~/.claude/settings.json はあなたのすべてのプロジェクトに適用され、.claude/settings.json はプロジェクト単位でコミット可能、.claude/settings.local.json はプロジェクト単位で gitignore の対象です。そして設定の標準的な優先順位が適用されます。管理ポリシーがローカルより、ローカルがプロジェクトより、プロジェクトがユーザーより優先されます。⁹ フックはプラグイン（hooks/hooks.json）や、スキル・エージェントのフロントマターに同梱することもできます。また、企業の管理者はユーザーが上書きできない管理フックを強制できます。⁶

マッチャーはその文字列によって評価されます。"*"、""、またはマッチャーの省略はすべてに一致します。英字・数字・_・-・空白・カンマ・| だけを含む値は、完全一致の文字列またはリストです（Bash、Edit|Write）。それ以外はアンカーなしの JavaScript 正規表現になるため、Edit.* は Edit と NotebookEdit の両方に一致します。ちょうど1つのツールだけを指したいときは ^Edit$ のようにアンカーを付けてください。マッチャーは大文字・小文字を区別し、各イベントはそれぞれ固有のフィールドで照合します。ツール系イベントはツール名、SessionStart は source、SubagentStart はエージェントの種類、Notification は通知の種類です。⁶ ツール系イベントをより鋭く絞り込みたい場合、ハンドラーごとの if フィールドは "Bash(git *)" のような権限ルールを1つ受け付けます。ただしこれはベストエフォートで（解析できないコマンドに対しては通してしまいます）、確実な保証が必要なら if ではなく権限ルールを使ってください。⁶

ハンドラーには5種類あります。command（シェル）、http（POST エンドポイント）、mcp_tool、prompt（単一ターンのモデル評価）、そして agent（Read/Grep/Glob にアクセスできるサブエージェント。実験的）です。既定のタイムアウトは、command/http/mcp_tool が600秒（UserPromptSubmit では30秒、MessageDisplay では10秒に下がります）、prompt が30秒、agent が60秒です。フックごとに timeout で上書きできます。⁶ 一致したフックはすべて並列で実行され、同一のハンドラーは重複が除かれます。また $CLAUDE_PROJECT_DIR はスクリプトからプロジェクトのルートを指し示します。

確認には /hooks を使います。これは読み取り専用のビューアで、すべてのイベント、設定されたフック、そしてそれぞれがどの設定ファイル由来かを表示します。何かを変更するには JSON を編集します（あるいは Claude に頼みましょう）。すべてを一時的に無効化するには "disableAllHooks": true を設定します。⁶

5つのパターン

一般化した、最小限の形です。フックのチュートリアルでは、このうちいくつかをより充実した実運用版として組み立てています。またApple 開発のためのフックでは、これらを iOS のツールチェーンに応用しています。

1. 編集後に自動整形する（PostToolUse）

公式ガイドそのままです。Claude が触れたファイルは、例外なくすべて整形されます。³

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

コマンドは、使用しているスタックに応じて ruff format、gofmt、swiftformat などに置き換えてください。

2. 危険なコマンドをブロックする（PreToolUse、終了コード2）

#!/bin/bash
# .claude/hooks/guard-bash.sh — register on PreToolUse, matcher "Bash"
command=$(jq -r '.tool_input.command // empty')
case "$command" in
  *"rm -rf"* | *"git push --force"* | *"DROP TABLE"*)
    echo "Blocked: matches a destructive pattern. Propose a safer alternative." >&2
    exit 2 ;;
esac
exit 0

終了コード2は呼び出しをブロックし、stderr を Claude に返します。Claude はやみくもに再試行するのではなく、方針を修正します。これに相当する JSON 版、すなわち理由を添えた permissionDecision: "deny" も同じことをしますが、"ask"（人間に判断を委ねる）や updatedInput（コマンドを書き換える）へ発展させる余地があります。⁵

3. セッション開始時にコンテキストを注入する（SessionStart）

SessionStart フックからの素の stdout は、Claude が見られるコンテキストになります。JSON は不要です。¹

#!/bin/bash
# .claude/hooks/session-context.sh — register on SessionStart
echo "Current branch: $(git branch --show-current)"
echo "Recent commits:"
git log --oneline -5
echo "Uncommitted files: $(git status --porcelain | wc -l | tr -d ' ')"
exit 0

これは動的な状態のために使いましょう。静的な取り決めは CLAUDE.md に置くべきです。ドキュメント自身も、スクリプトを要しないコンテキストには CLAUDE.md を推奨しています。¹

4. Stop に完了ゲートを設ける

Stop は Claude が応答を終えたときに発火します。これをブロックすれば、条件が満たされるまでエージェントに作業を続けさせられます。

#!/bin/bash
# .claude/hooks/stop-gate.sh — register on Stop
input=$(cat)
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # already continuing because of this hook; don't loop forever
fi
if ! npm test --silent > /tmp/stop-gate.log 2>&1; then
  jq -n '{decision: "block", reason: "Tests are failing. Fix them before finishing. Log: /tmp/stop-gate.log"}'
fi
exit 0

stop_hook_active の確認は重要です。Claude Code は Stop フックを連続8回のブロックで打ち切る上限を設けており、自分がすでに継続を引き起こしたかどうかを確認しないゲートは、その上限をあっという間に使い果たしてしまいます。⁷ より柔らかく誘導したい場合は、decision: "block" の代わりに hookSpecificOutput.additionalContext を返します。継続する点は同じですが、フックエラーではなく、ラベル付きのフィードバックとして扱われます。そして一度きりの条件には、組み込みの /goal コマンドが使えます。これは設定不要で、セッション単位・プロンプトベースの Stop フックとして働きます。¹

5. ディスパッチャー：入り口は1つ、フックは小さくたくさん

10個のフックを登録するということは、settings.json に10個のエントリを書くということであり、それらはマシンやプロジェクトの間でばらついていきます。代わりの方法は、イベントごとにディスパッチャーを1つ登録し、規約によって振り分けることです。

#!/bin/bash
# .claude/hooks/dispatch.sh — register once per event you care about
input=$(cat)
event=$(echo "$input" | jq -r '.hook_event_name')
dir="$CLAUDE_PROJECT_DIR/.claude/hooks/$event"
[ -d "$dir" ] || exit 0
for hook in "$dir"/*.sh; do
  [ -x "$hook" ] || continue
  echo "$input" | "$hook" || exit $?
done
exit 0

ガードを追加する作業は、.claude/hooks/PreToolUse/ に新しいファイルを置いて chmod +x するだけになります。settings.json は一切変わらず、各スクリプトは単体でテストできるほど小さいまま保たれ、最初の終了コード2がそのまま伝わります。一つ注意点があります。ディスパッチャーは Claude Code が本来並列で実行するものを直列化してしまうため、終了コードで応答するフックに最も向いています。JSON を出力するフックは単独で使うべきです。stdout にはちょうど1つの JSON オブジェクトだけが含まれていなければならないからです。⁵

フック、CLAUDE.md、スキル、メモリの使い分け

4つの仕組みには、それぞれ4つの役割があります。

失敗は両方向に起こり得ます。取り決めをフックとして書き込めば、一文の案内で十分こと足りることを、壊れやすいスクリプトで強制する羽目になります。ポリシーを CLAUDE.md の文章として書けば、よりによって肝心な日に main へ強制プッシュするエージェントを抱えることになります。判断基準はこうです。モデルがこれを一度無視したら、その代償はどれほどか？　苛立ち程度なら CLAUDE.md、重大な事故ならフックです。

フックにできないこと

包み隠さぬ制約です。いずれも公式ドキュメントによります。⁷

• フックはツールやスラッシュコマンドを呼び出せません。 コマンド型のフックが扱えるのは stdout、stderr、終了コードだけで、それ以上はありません。additionalContext を通じて返されるコンテキストは、プレーンテキストとして注入されます。
• PostToolUse は取り消しができません。 ツールはすでに実行済みです。防止策は PreToolUse にあります。
• Stop はすべての応答終了時に発火します。 「タスク完了」時だけではなく、またユーザーによる中断では発火しません（API エラーの場合は代わりに StopFailure が発火します）。ゲートのロジックは、タスク途中での停止にも耐えられるようにしなければなりません。
• PermissionRequest はヘッドレス（-p）モードでは発火しません。 自動的な権限判断には PreToolUse を使ってください。
• PreToolUse は @ で参照されたファイルを見られません。 プロンプト内で @ を使って取り込まれたファイルはツール呼び出しを伴わないため、その経路からパスを守るには Read の拒否ルールを使ってください。¹
• 並列の updatedInput は非決定的です。 複数の PreToolUse フックが同じツールの引数を書き換える場合、最後に終わったものが勝ちます。書き換えは1つのフックに担当させましょう。
• タイムアウトはフックを打ち切ります。 コマンド型フックの既定は600秒です（UserPromptSubmit は30秒、MessageDisplay は10秒）。タイムアウトする遅いゲートは、実行されなかったゲートと同じです。
• 出力は10,000文字が上限です。 あふれた分はファイルに書き出され、プレビューに置き換えられます。
• フックはあなたのユーザー権限をすべて持って実行されます。 リファレンス自身がこう警告しています。フックは「あなたのユーザーアカウントがアクセスできるあらゆるファイルを変更・削除・アクセスできます。設定に追加する前に、すべてのフックコマンドを見直し、テストしてください」。⁸ 変数はクォートで囲み、絶対パスを使い、機密性の高いファイルは避けましょう。
• 壊れたフックは、直すまですべてのセッションを損ないます。 デバッグには記録ビュー（Ctrl+O）、claude --debug-file /tmp/claude.log、あるいはセッション途中の /debug を使います。よくある落とし穴は、起動時に文字を出力するシェルプロファイルが、フックの JSON 出力を壊してしまうことです。⁷

よくある質問

Claude Code のフックとは何ですか？

フックとは、ユーザーが定義するコマンド（シェルスクリプト、HTTP エンドポイント、MCP ツール、またはモデルへのプロンプト）であり、Claude Code がライフサイクルの特定の地点で自動的に実行するものです。³ フックは stdin からイベントの JSON を受け取り、終了コードまたは JSON で応答します。ツール呼び出しをブロックする、コンテキストを注入する、引数を書き換える、エージェントに作業を続けさせる、といった具合です。CLAUDE.md の指示とは違い、フックはモデルの振る舞いにかかわらず毎回実行されます。

PreToolUse フックと権限の違いは何ですか？

権限ルールは宣言的です。Claude Code 自身が評価する、静的な許可・拒否・確認のパターンです。PreToolUse フックはプログラム可能です。あなたのコードがツール入力の全体を調べて判断します。フックは権限モードの検査より前に発火するため、フックの "deny" は bypassPermissions モードでも有効です。ただしフックの "allow" は、設定ファイルの拒否ルールを覆せません。⁴ パターンで表現できることには権限ルールを使い、判断にロジックや外部の状態、入力の書き換えが必要なときにフックを持ち出しましょう。

フックはヘッドレス（-p）モードでも動きますか？

動きます。ただしドキュメントに記された例外が1つあります。PermissionRequest フックは非対話モードでは発火しないため、自動的な権限判断は PreToolUse に置くべきです。⁷ さらにヘッドレスモードでは、対話セッションでは無視される選択肢が一つ使えるようになります。permissionDecision: "defer" です。これはツール呼び出しを一時停止し、外側で包むプロセス（Agent SDK アプリ、独自の UI など）が入力を集めて、後からセッションを再開できるようにします。⁵

フックは動くのに、何もブロックしないのはなぜですか？

ほとんどの場合、取り決めに違反しています。終了コード1はブロックしません。ブロックするのは終了コード2だけで、しかもブロックに対応したイベントに限られます。² JSON による判断は終了コード0のときにしか解析されません。{"decision": "block"} を出力してから終了コード2で終えるスクリプトは、その JSON が破棄されてしまいます。そしてマッチャーは大文字・小文字を区別します。bash は Bash に決して一致しません。まず /hooks で登録を確認し、次にサンプルの JSON をスクリプトにパイプで渡して echo $? を調べてテストしましょう。⁷

出典

2026年7月1日に公式ドキュメントと照合して検証しました。フックの API は Claude Code v2.1.x のリリースを通じて大きく変わっています（新しいイベント、新しいフィールド、マッチャーの意味づけ）。そのため、バージョンに左右される詳細は「この日付時点のもの」として扱ってください。

このサイトの関連記事： プロンプトフックやエージェントフックまで含めたシステム全体像はClaude Code ガイドのフックの節を、完全な設定を伴う5つの実運用ビルドはフックのチュートリアルを、iOS への応用パターンはApple 開発のためのフックを、そして Claude Code をまだインストールしていない方はクイックスタートをご覧ください。