Claude Code Hooks 完全ガイド：settings.json、5 つのイベントと exit code によるブロック
Hooks は Claude Code の決定論的レイヤーです：プロンプトに頼らず、設定すれば必ず実行されます。この図解ウォークスルーは Anthropic 公式の hooks 動画を映像に使用 —— 5 つのイベント、PreToolUse のブロックスクリプト、構造化された deny JSON、そして完全な PostToolUse フォーマット設定まで。
TL;DR —— Claude Code hooks とは
- Hooks は決定論的です：Claude Code のライフサイクルの固定ポイントで毎回必ず実行されます。「毎回編集後に Prettier を実行して」という CLAUDE.md の指示はたいていの場合機能します —— hook は常に機能します。
- イベントは 5 つ：UserPromptSubmit（プロンプトが処理される前）、PreToolUse（ツール呼び出しの前）、PostToolUse（ツール完了後）、Notification、そして Stop（Claude が応答を終えたとき）。
- exit code 2 で終了する PreToolUse hook はそのツール呼び出しをブロックし、stderr のメッセージが Claude に返されるので理由が分かります。exit code 0 なら呼び出しは続行されます。
- Hooks は settings.json に書きます —— イベント、任意のツール matcher、コマンド。プロジェクトの .claude/settings.json に置いてコミットすれば、チーム全員が同じ保証を引き継ぎます。
Hooks in Claude Code
チャンネル:Claude (official Anthropic channel)3:22
Claude Code Hooks, Explained Simply
チャンネル:Agentic Lab8:32
Claude Code - Getting Started with Hooks
チャンネル:Greg Baugues11:53
Hooks reference — Claude Code documentation
ドキュメント:code.claude.com
このガイドのフレームは Anthropic 公式の hooks 解説動画から。ウォークスルーの文章は独立して執筆され、公式 hooks リファレンスと突き合わせて検証しています。
スクリーンショットの著作権は作成者に帰属し、視覚的ドキュメントとしてクレジット付きで使用しています。各ステップから元動画の該当瞬間へ深リンクできます。
Claude Code hooks を段階的にセットアップ
1 · 実戦で hook が動く姿
- 1
回答の最後に hook が発火するのを見る
ステータスラインには「Running stop hook · 39s · 484 tokens」と表示されています —— Claude Code が Stop hook を実行してからターンを返しているのです。1 枚のスクリーンショットに思想のすべてが詰まっています：登録したコマンドがライフサイクルの固定ポイントで、一致するたびに、モデルが「忘れずにやってくれる」ことに一切頼らず実行される、と。
Claude の回答後に実行される Stop hook —— 39 秒経過、484 tokens 消費。0:10 に視聴 - 2
5 つの hook イベントを覚える
UserPromptSubmit はプロンプト送信の瞬間、Claude が処理する前に実行されます。PreToolUse は各ツール呼び出しの前。PostToolUse はツール呼び出しの完了後。Notification は Claude が通知を送るときに発火し、Stop は Claude が応答を終えたときに実行されます。書く hook はすべて、この 5 つのポイントのいずれかに 1 対 1 で紐づきます。
Anthropic 公式 hooks 動画による 5 つのイベント —— 他のすべてはこのリストにぶら下がります。1:04 に視聴
2 · 最初の hook を書く
- 3
settings.json に hooks ブロックを追加する
hook は settings.json における 3 つの要素です：イベント名、適用対象のツールを絞る任意の matcher、実行するコマンド。スクリーンショットでは PreToolUse の matcher に Edit が補完されつつあります —— この hook はファイル編集系のツール呼び出しでのみ発火します。JSON を手書きしたくなければ、/hooks メニューで同じ設定を対話的に編集できます。
matcher が Edit を自動補完。PreToolUse hook をファイル編集限定にしています。0:14 に視聴 - 4
exit code 2 で危険なコマンドをブロックする
PreToolUse hook はツール名と入力を JSON として stdin で受け取ります。このスクリプトは jq で .tool_input.command を取り出し、rm -rf や git push --force といった破壊的パターンを grep で照合し、一致すれば理由を stderr に出して exit code 2 で終了します。exit code 2 は呼び出しをブロックし、stderr のテキストはフィードバックとして Claude に返されるため、モデルは拒否理由を知って調整できます。
jq が stdin からコマンドを読み取り、rm -rf か --force に一致すると stderr に出力して exit 2。2:02 に視聴 - 5
exit code の代わりに構造化された拒否を返す
より細かい制御には、exit code に頼らず JSON の決定を出力できます。ここでは PreToolUse hook が DROP TABLE を捕捉し、hookSpecificOutput が permissionDecision「deny」と理由 ——「migration を使って」—— を運び、モデルのコンテキストに届けます。同じ強固な保証でありながら、実行可能な指示が添えられます。
permissionDecision が deny だと SQL コマンドがブロックされ、モデルに代替案が伝わります。2:16 に視聴 - 6
hooks をリポジトリに置いてチームで共有する
プロジェクトの .claude/settings.json に設定された hooks はプロジェクトレベルで、コミットできます。リポジトリをクローンした人は全員、ブロック系を含む同じ hooks を自動的に実行します。ヘルパースクリプトは .claude/hooks/ に置き、CLAUDE_PROJECT_DIR 環境変数で参照すれば、Claude の現在の作業ディレクトリがどこであってもパスが解決されます。
プロジェクトの .claude フォルダには settings.json と共有スクリプトの hooks/ ディレクトリ。0:17 に視聴 - 7
完全で実戦的な hooks 設定をコピーする
この設定は一度に 2 つの仕事をします。PostToolUse ブロックは Edit|Write|MultiEdit に一致し、30 秒のタイムアウトで .claude/hooks/auto-format.sh を実行 —— Claude が触れたファイルはすべてフォーマットされます。その下の 2 つ目の hook は Bash に一致し、実行された全コマンドを記録 —— コンプライアンス定番のパターンです。timeout と async フィールドのおかげで、遅いフォーマッタがセッションを止めることはありません。
30 秒タイムアウトの PostToolUse 自動フォーマットと、全コマンドを記録する Bash hook。2:46 に視聴
3 · チームとして運用する
- 8
exit code の契約を暗記する
exit code 0 は続行。exit code 2 はブロック —— stderr は Claude が行動に移せるフィードバックとして渡されます。それ以外の exit code は stderr をあなた（ユーザー）に見せるだけでツール呼び出しは続行します。エージェントを硬直的に止めず、見ておきたい警告に使いましょう。
- 9
/hooks メニューで登録を確認し、レシピを選ぶ
/hooks コマンドは同じ設定を対話的に開きます —— どのスコープにどの hook が登録されているかの確認に便利です。ここからは 4 つの主力レシピ：編集後の自動フォーマット（PostToolUse）、実行コマンドの全記録（Bash 上の PostToolUse）、危険操作のブロック（exit 2 付き PreToolUse）、Claude 完了時の通知（Stop）。毎回確実に起きるべきことはプロンプトに書かず、hook にしましょう。
exit code の契約、1 枚の表で
すべての hook コマンドは exit code で通信します。3 つのケースですべてをカバーできます：
- exit 0続行。ツール呼び出しは通常どおり実行されます。hook の stdout はトランスクリプトモード（Ctrl-R）で確認できます。
- exit 2ブロック。ツール呼び出しは拒否され、hook の stderr がフィードバックとして Claude に返されるため、モデルは軌道修正できます —— exit-2 hook が単なる致命傷ではなく「教訓」になるのはこのためです。
- exit 1その他のコード：ブロックせず警告。stderr はあなたに表示されますが呼び出しは続行します。「このファイルは通常生成物ですが、本当に編集しますか？」といった注意喚起系 hook 向け。
もう 1 つの上級ルート：exit code の代わりに、hook は JSON の決定（permissionDecision 付き hookSpecificOutput）を出力して、構造化された理由付きで拒否できます（ステップ 5 参照）。exit code はシンプルな契約、JSON 決定は型付きの契約です。
今すぐコミットすべき 4 つのレシピ
公式動画が挙げる 4 つのユースケースを、コピーして使える意図として整理しました：
- 1編集後の自動フォーマット —— Edit|MultiEdit に一致する PostToolUse hook が拡張子を判定し、適切なフォーマッタを実行：TypeScript は Prettier、Go は gofmt、Python は Ruff。
- 2実行コマンドの全記録 —— Bash 上の PostToolUse hook が各コマンドをファイルに追記。コンプライアンス担当は大喜び、先週の火曜に何が走ったか調べる未来のあなたも喜びます。
- 3危険操作のブロック —— exit 2 付き PreToolUse hook で本番設定ディレクトリ、rm -rf パターン、main へのコミットを防衛。これらは「提案」ではなく「保証」になります。
- 4タスク完了の通知 —— Stop または Notification hook でデスクトップ通知やサウンドを発火。長時間のエージェント実行も張り付く必要がありません。
4 つとも 1 つの .claude/settings.json に収まります。まずはフォーマッタから —— 毎回の保存で実感できる hook です。