Claude Codeには「フック(Hooks)」という、AIエージェントの動きにルールベースの制約や自動処理を差し込める仕組みがある。ツール実行の前後やセッションの開始・終了といった決まったタイミングで、シェルコマンドやHTTPリクエスト、さらには別のAIモデルによる判定まで挟み込める。プロンプトで「危険な操作はしないで」と頼むのではなく、確定的に止める・記録する・通知するための仕組みとして押さえておきたい機能だ。
フックとは何か
Claude Codeのフックは、エージェントのライフサイクル上の特定イベントで発火する処理だ。プロンプトで「〜しないでください」と指示するのとは違い、外部のスクリプトや別モデルの判定結果に基づいて機械的に許可・拒否を決められるため、再現性のある安全策やワークフローの自動化に向いている。設定は次のいずれかのJSONファイルに書く。
| 設定ファイル | スコープ | 共有 |
|---|---|---|
~/.claude/settings.json |
全プロジェクト共通 | 個人のみ |
.claude/settings.json |
そのプロジェクト | Gitにコミットして共有可 |
.claude/settings.local.json |
そのプロジェクト（自分専用） | 非共有・gitignore対象 |
プラグインのhooks/hooks.json |
プラグイン有効時 | プラグインとして配布 |
主なフックイベント
代表的なイベントは次の通り。ツール呼び出しの前後、セッションの開始・終了、応答完了時など、エージェントの一挙手一投足に対応するタイミングが用意されている。
| イベント | 発火タイミング |
|---|---|
SessionStart / SessionEnd |
セッション開始時・終了時（resume/forkでも再発火） |
UserPromptSubmit |
ユーザーの入力をClaudeが処理する前 |
PreToolUse |
ツール実行の直前（ブロック可能） |
PostToolUse |
ツール実行の直後 |
Stop |
Claudeが応答を終えたとき |
Notification |
権限確認や認証プロンプトの表示時 |
PreCompact / PostCompact |
コンテキスト圧縮の前後 |
ほかにもSubagentStart/SubagentStop、PermissionRequest、WorktreeCreateなど、Agent SDK的な用途に対応した細かいイベントが増え続けている。
ハンドラーの種類——シェルだけじゃない
フック本体（ハンドラー）は5種類ある。もともとはシェルコマンドだけだったが、2026年に入って選択肢が広がった。
- command — シェルスクリプトや実行ファイル。標準入力でイベントのJSONを受け取る、最も基本的な形。
- http — 指定URLへPOSTするタイプ。2026年2月に追加され、Slack通知や社内APIとの連携がシェルスクリプト無しで書けるようになった。
- mcp_tool — 接続済みのMCPサーバーのツールを直接呼び出す。
- prompt — 入力内容をClaude（デフォルトはHaiku系の軽量モデル）に渡し、1ターンで許可/拒否を判定させる（タイムアウト30秒）。
- agent — ファイル読み取りやコマンド実行など複数ツールを使えるサブエージェントに判定を委ねる（最大50ターン、実験的機能）。
「rmコマンドかどうかを正規表現で見るだけ」ならcommand、「この差分は本当に安全か」といった曖昧な判断が必要ならpromptやagentタイプが向いている、という使い分けになる。
終了コードとJSON出力で挙動を決める
commandタイプのフックは、終了コードによって挙動が変わる。
| 終了コード | 意味 | 効果 |
|---|---|---|
| 0 | 正常終了 | 標準出力のJSONを読み、そこに書かれた判定（allow/deny等）が反映される |
| 2 | ブロック | PreToolUseやUserPromptSubmitなどの対象イベントを強制的に止める |
| 1・3以上 | 非ブロッキングエラー | 処理は続行されるが、エラー内容が通知される |
終了コード2は問答無用でブロックするための簡易な手段、終了コード0＋JSON出力は「許可はするが理由を記録する」「入力を書き換えて渡す」といった細かい制御に向く。
実践例
1. 危険なコマンドを止める
PreToolUseでBashをマッチさせ、rm -rfのようなパターンを検知したら拒否のJSONを返す。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
]
}
]
}
}スクリプト側ではjqでtool_input.commandを取り出し、危険な文字列を含むときだけpermissionDecision: "deny"を返す。
2. 編集後に自動でLintを走らせる
PostToolUseでEdit/Writeをマッチさせ、保存直後にLintやフォーマッタを走らせる。書式のズレをレビュー前に潰せる。
3. HTTPフックでSlackに通知する
httpタイプを使えば、長時間タスクの完了（Stopイベント）をSlackや社内Webhookに直接POSTできる。シェルスクリプトでcurlを書く手間が省ける分、設定ファイルだけで完結する。
使い始める際の注意点
フックはClaude自身の権限で、サンドボックスなしに実行される。設定を誤ると意図せずファイルを消したり、秘密情報を外部に送ってしまったりするリスクがある。まずは.claude/settings.local.jsonのような個人スコープで試し、チームに配る前に挙動を十分確認してから.claude/settings.jsonにコミットするのが安全だ。既存の設定を素早く整えたい場合は/hooksコマンドで対話的に追加することもできる。
主な情報源
- Hooks reference – Claude Code Docs
- Claude Code Hooks (2026): Block Claude Reading .env + 30 Hook Events, JSON Input, Exit Codes
- Claude Code Hooks: Complete Guide to All 30 Lifecycle Events
各ツールは提供元の規約に従ってご利用ください。情報は各情報源の公開時点のものです。収集・要約はAI、公開判断は人。