Claude Code Hooks完全ガイド（2026年3月版）¶

対象 / ポイント

対象: Claude Codeを使う開発者で、繰り返し作業の自動化やルールの強制をプロンプト指示に頼らず実現したい方。

ポイント:

Hooksは21種のライフサイクルイベントで確実に実行される -- 保存時の自動フォーマット、危険コマンドのブロック、テスト強制など
4種のハンドラ：シェルcommand、HTTP http、LLM判定のprompt、コードベース検証のagent
/hooks CLIメニュー（読み取り専用）、JSON設定、スキル/エージェントfrontmatterで設定可能

Claude Codeがファイルを書くたびにPrettierを走らせたい。rm -rf /を実行しようとしたらブロックしたい。プロンプトで「お願い」することもできるが、お願いは保証ではない。Hooksなら確定的に実行される。

実際に動くフックの例を見てみよう。Claudeがファイルを編集するたびにPrettierを自動実行する設定だ：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

.claude/settings.jsonに置くだけで、ファイル書き込みのたびにPrettierが走る。プロンプト不要、権限ダイアログなし、例外なし。

この記事では全21イベント、4種のハンドラ、非同期実行、JSONによる高度な制御を網羅する。目次から必要なセクションに直接ジャンプできる。

前回バージョンからの主な変更点（2026年3月更新）

イベント数が14→21に増加（InstructionsLoaded, ConfigChange, WorktreeCreate/Remove, PostCompact, Elicitation/ElicitationResult追加）、HTTPフックタイプが新設、/hooksメニューが読み取り専用に変更、disableAllHooksで一括無効化が可能に。

Claude Code Hooksとは？¶

Hooksは、Claude Codeのライフサイクルに確定的な処理を割り込ませる仕組みだ。プロンプトでの指示がClaudeの解釈に委ねられる「お願い」であるのに対し、Hooksは毎回同じように実行される。

Claude Code実行 → 特定イベント発火 → matcher判定 → フック実行（command / http / prompt / agent）

Hookイベント一覧（全21種）¶

公式ドキュメントで定義されている全21種のライフサイクルイベント。

SessionStart
セッション開始時に発動（startup / resume / clear / compact）例：開発コンテキスト注入、環境変数の永続化
SessionEnd
セッション終了時に発動例：クリーンアップ、セッション統計ログ記録
UserPromptSubmit
ユーザーがプロンプト送信時に発動例：プロンプトのバリデーション、コンテキスト追加
PreToolUse
ツール実行前に発動例：危険コマンドのブロック、ツール入力の書き換え
PermissionRequest
権限ダイアログ表示時に発動例：安全なコマンドの自動承認
PostToolUse
ツール実行成功後に発動例：ファイル保存後の自動lint/format
PostToolUseFailure
ツール実行失敗後に発動例：失敗ログ記録、リトライ判定
Notification
通知発生時に発動（permissionprompt / idleprompt / authsuccess / elicitationdialog）例：デスクトップ通知、Slack通知
Stop
Claudeが応答完了時に発動例：自動git commit、タスク完了ログ
SubagentStart
サブエージェント開始時に発動例：DB接続セットアップ、特定エージェント用の環境準備
SubagentStop
サブエージェント終了時に発動例：タスク完了の強制、結果ログ記録
PreCompact
コンテキスト圧縮前に発動例：会話トランスクリプトのバックアップ
PostCompact
コンテキスト圧縮後に発動例：圧縮サマリーの記録、コンテキスト再注入
TeammateIdle
Agent Teamsのチームメイトがアイドル状態になる直前に発動例：アイドルエージェントへのタスク再割り当て
TaskCompleted
タスクが完了マークされた時に発動例：完了通知、次タスクのトリガー
InstructionsLoaded
CLAUDE.mdや.claude/rules/*.mdがコンテキストに読み込まれた時に発動例：設定ファイルの監視（制御不可、監視のみ）
ConfigChange
セッション中に設定ファイルが変更された時に発動例：設定変更の監査ログ、不正な変更のブロック
WorktreeCreate
--worktreeやisolation: "worktree"でワークツリー作成時に発動例：カスタムワークツリー作成ロジック
WorktreeRemove
ワークツリー削除時に発動例：クリーンアップ処理
Elicitation
MCPサーバーがユーザー入力を要求した時に発動例：入力の自動応答、入力要求の拒否
ElicitationResult
MCP入力要求にユーザーが応答した後に発動例：応答内容の検証、ログ記録

フックハンドラの種類（4タイプ）¶

4種のハンドラタイプが利用可能。

タイプ	説明	用途	対応イベント
`command`	シェルコマンドを実行	lint、git操作、通知、バックアップ	全イベント
`http`	HTTPエンドポイントにPOST	外部サービス連携、チーム共有の監査ログ	全イベント
`prompt`	LLMに判断を委ねる（単一ターン）	コンテキスト依存の許可/拒否判定	PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted等
`agent`	エージェントがコードベースを検証（マルチターン）	実際のファイル状態に基づく複雑な判断	prompt対応イベントと同じ

// command型（確定的ルール向き）
{
  "type": "command",
  "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
}

// http型（外部サービス連携）
{
  "type": "http",
  "url": "http://localhost:8080/hooks/pre-tool-use",
  "headers": { "Authorization": "Bearer $MY_TOKEN" },
  "allowedEnvVars": ["MY_TOKEN"]
}

// prompt型（LLM判断が必要な場合）
{
  "type": "prompt",
  "prompt": "このBashコマンドが本番環境に影響を与える可能性があるか評価してください: $ARGUMENTS"
}

// agent型（コードベースの状態確認が必要な場合）
{
  "type": "agent",
  "prompt": "変更されたファイルに対応するテストが存在するか確認してください"
}

使い分けの指針

command: シンプルで確定的なルール（formatやlint、git操作）→ 常にcommandを優先
http: 外部サービスとの連携、チーム共有の監査・バリデーション → commandと同等の制御が可能
prompt: フック入力データだけで判断できる場合（コマンドの危険性評価など）
agent: 実際のコードベースの状態を確認する必要がある場合（テストの存在確認など）

非同期フック（async）— 2026年1月追加¶

ブロッキングせずにバックグラウンドで実行する非同期フックが追加されました。

{
  "type": "command",
  "command": "node backup-script.js",
  "async": true,
  "timeout": 30
}

	同期フック（デフォルト）	非同期フック（`async: true`）
Claudeの動作	フック完了まで待機	待機せず即座に続行
ブロック制御	exit code 2 でブロック可能	ブロック不可
適した用途	セキュリティチェック、権限判定	ログ記録、バックアップ、通知送信
不適な用途	時間のかかる処理	Claudeが結果を必要とする処理

Exit Codeの制御体系¶

フックのexit codeでClaudeの挙動を制御できます。

Exit 0  → 成功。stdoutのJSON出力を解析
Exit 2  → ブロッキングエラー。stderrがClaudeにフィードバック
その他  → 非ブロッキングエラー。verboseモードでstderr表示、実行は継続

Exit 2の挙動はイベントごとに異なります：

イベント	Exit 2の効果
PreToolUse	ツール呼び出しをブロック
UserPromptSubmit	プロンプトを拒否
PermissionRequest	権限を拒否
Stop / SubagentStop	停止をブロック（作業継続を強制）
TeammateIdle	チームメンバーの待機を防止
TaskCompleted	タスク完了マークを防止
ConfigChange	設定変更をブロック
Elicitation	MCP入力要求を拒否
ElicitationResult	応答をブロック（declineに変更）
SessionStart / PreCompact	stderrをユーザーに表示のみ（ブロック不可）
PostToolUse / Notification	stderrを表示のみ（実行済みのためブロック不可）

JSON構造化出力による高度な制御¶

Exit 0時にstdoutへJSON出力することで、きめ細かい制御が可能です。

PreToolUseの権限判定¶

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Safe read operation",
    "updatedInput": {
      "command": "modified-command"
    },
    "additionalContext": "Claudeへの追加コンテキスト"
  }
}

"allow": 権限システムをバイパスして許可
"deny": ツールをブロックし、理由をClaudeにフィードバック

PermissionRequestの自動応答¶

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

Stop/SubagentStopの完了強制¶

{
  "decision": "block",
  "reason": "テストが失敗しています。修正してから完了してください。"
}

設定ファイルの配置場所¶

場所	スコープ	共有可能
`~/.claude/settings.json`	全プロジェクト共通	いいえ（ローカルのみ）
`.claude/settings.json`	プロジェクト固有	はい（Git管理可能）
`.claude/settings.local.json`	プロジェクト固有	いいえ（gitignored）
組織管理ポリシー	エンタープライズ全体	はい（管理者制御）
プラグイン `hooks/hooks.json`	プラグイン有効時	はい（バンドル配布）
スキル/エージェントfrontmatter	コンポーネント活動中	はい（ファイル内定義）

全フックの一括無効化

設定ファイルに "disableAllHooks": true を追加すると、全フックを一括で無効化できます。

設定例¶

1. /hooks CLIメニューで確認¶

# Claude Code CLI内で
/hooks
# → イベント一覧とフック数が表示される
# → イベント選択 → 設定済みフックの詳細を確認

/hooksメニューは読み取り専用

フックの追加・変更・削除は設定JSONファイルを直接編集するか、Claudeに変更を依頼してください。

2. 基本的なJSON設定¶

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '作業完了！' >> ~/work.log"
          }
        ]
      }
    ]
  }
}

3. SessionStartでコンテキスト注入¶

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"additionalContext\": \"現在のブランチ: '$(git branch --show-current)'\"}'"
          }
        ]
      }
    ]
  }
}

SessionStartとUserPromptSubmitのstdout出力はClaudeのコンテキストとして追加されます。

4. 環境変数の永続化（SessionStart限定）¶

SessionStartフックではCLAUDE_ENV_FILEを使って環境変数をセッション全体に永続化できます。

#!/bin/bash
# setup-env.sh - SessionStartフックから呼び出す
echo "PROJECT_ROOT=$(git rev-parse --show-toplevel)" >> "$CLAUDE_ENV_FILE"
echo "NODE_ENV=development" >> "$CLAUDE_ENV_FILE"

5. スキル/エージェントのfrontmatterにフック定義¶

---
name: code-reviewer
description: コード変更を自動lintでレビュー
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---
あなたはコードレビューの専門エージェントです。

frontmatter内のStopフック

スキル/エージェントのfrontmatterで定義したStopフックは自動的にSubagentStopイベントに変換されます。

活用例¶

自動Format/Lint
PostToolUseでファイル変更後に自動整形。matcherでWrite|Edit|MultiEditを指定
セキュリティブロック
PreToolUseで危険なBashコマンド（rm -rf等）をexit code 2でブロック
デスクトップ通知
Notificationでアイドル時・権限要求時にOS通知を送信
安全コマンド自動承認
PermissionRequestでnpm run lint等を自動allow
テスト強制
Stopのexit code 2で「テストが通るまで完了させない」を実現
自動Git管理
PostToolUseでGitButler等と連携し、セッションごとにブランチ自動分離
圧縮前バックアップ
PreCompactでコンテキスト圧縮前にトランスクリプトを自動保存
Agent Teams連携
SubagentStart/Stop, TeammateIdleでサブエージェントのライフサイクル管理
セッション初期化
SessionStartで開発環境セットアップ、依存関係インストール、DB初期化を自動実行
LLM判定フック
prompt/agent型でコンテキスト依存の判断（本番影響の評価等）をLLMに委ねる

実践パターン：GitButler連携¶

複数のClaude Codeセッションを同時実行する場合、GitButlerのフックでセッションごとにブランチを自動分離できます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          { "type": "command", "command": "but claude pre-tool" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          { "type": "command", "command": "but claude post-tool" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "but claude stop" }
        ]
      }
    ]
  }
}

デバッグとトラブルシューティング¶

フックのテスト¶

# stdinにサンプルJSONをパイプしてテスト
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?  # exit codeを確認

Stopフックの無限ループ防止¶

Stopフックでexit 2を返すとClaudeは作業を継続するが、これが無限ループを引き起こす場合がある。stop_hook_activeフィールドを確認して防止する：

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # 2回目以降は停止を許可
fi
# ... フックのロジック

よくある問題¶

症状	原因	対処
フックが実行されない	/hooksで表示されない	セッション再起動、設定ファイルの構文確認
"command not found"	相対パスの問題	`$CLAUDE_PROJECT_DIR`で絶対パス指定
"jq: command not found"	jq未インストール	jqインストール、またはPython/Node.jsで代替
PermissionRequestが発火しない	非インタラクティブモード	`-p`フラグ使用時はPreToolUseを使う
非同期フックでブロックできない	async: trueの制限	セキュリティチェックは同期フックで
JSON解析エラー	シェルプロファイルの`echo`がJSON出力を汚染	`~/.zshrc`等で`if [[ $- == i ]]`ガード追加
Stopフックが無限ループ	`stop_hook_active`未チェック	上記の無限ループ防止パターンを実装
設定変更が反映されない	セッション中のファイル編集	`/hooks`で確認するかセッション再起動

verboseモードの活用¶

# Ctrl+O でverboseモード切替
# → PreToolUse/PostToolUse等のstdout/stderrが表示される

バージョン別変更点まとめ¶

項目	旧版（2025年）	2026年2月版	現在（2026年3月版）
イベント数	7種	14種	21種
フックタイプ	commandのみ	command / prompt / agent	command / http / prompt / agent
非同期実行	なし	`async: true` 対応	同左
JSON出力制御	なし	permissionDecision等	同左
設定方法	JSON手動編集のみ	`/hooks` CLIメニュー + JSON	`/hooks`（読み取り専用）+ JSON + frontmatter
環境変数永続化	なし	`CLAUDE_ENV_FILE`	同左
プラグイン対応	なし	`hooks/hooks.json`	同左
Agent Teams	なし	TeammateIdle / TaskCompleted	同左
MCP連携	なし	なし	Elicitation / ElicitationResult
ワークツリー	なし	なし	WorktreeCreate / WorktreeRemove
設定監視	なし	なし	ConfigChange / InstructionsLoaded
一括無効化	なし	なし	`disableAllHooks: true`

📚 さらに学ぶには¶

公式ドキュメント：Hooks Guide — 入門・セットアップ
公式ドキュメント：Hooks Reference — 全イベントスキーマ・JSON仕様・詳細リファレンス

まとめ¶

Claude Code Hooksは2026年3月現在、21種のライフサイクルイベント、4種のハンドラタイプ、非同期実行、JSON構造化出力を備えた本格的なオートメーション基盤に成長しています。

✅ 確定的な制御：プロンプトの「お願い」ではなく「必ず実行」を保証
✅ 21イベント対応：セッション開始から終了、Agent Teams、MCP連携、ワークツリーまでカバー
✅ 4種のハンドラ：command、http、prompt、agentを用途に応じて選択
✅ 非同期フック：ログ・通知・バックアップをノンブロッキングで実行
✅ JSON制御：権限の自動判定、ツール入力の書き換え、停止のブロック
✅ 配布可能：プラグインやfrontmatterでチーム/プロジェクト単位で共有

権限管理概要 →

Hooksで自動化を組んだら、次は権限を正しく設計する

🔗 関連記事¶

権限管理概要
安全なClaude Code運用のための権限設計
コマンドリファレンス
全コマンド・設定・ショートカットを活用度別に整理
Hooks実践 - AIエージェント自動化
自動記事投稿システムの構築
Hooks応用 - プロダクション実装
エラーハンドリングとチーム開発での活用
GitHub Copilot Hooks完全ガイド
Copilot Coding Agent・CLIのHooksとの機能比較・使い分け

Claude Code Hooks完全ガイド（2026年3月版）¶

Claude Code Hooksとは？¶

Hookイベント一覧（全21種）¶

フックハンドラの種類（4タイプ）¶

非同期フック（async）— 2026年1月追加¶

Exit Codeの制御体系¶

JSON構造化出力による高度な制御¶

PreToolUseの権限判定¶

PermissionRequestの自動応答¶

Stop/SubagentStopの完了強制¶

設定ファイルの配置場所¶

設定例¶

1. /hooks CLIメニューで確認¶

2. 基本的なJSON設定¶

3. SessionStartでコンテキスト注入¶

4. 環境変数の永続化（SessionStart限定）¶

5. スキル/エージェントのfrontmatterにフック定義¶

活用例¶

実践パターン：GitButler連携¶

デバッグとトラブルシューティング¶

フックのテスト¶

Stopフックの無限ループ防止¶

よくある問題¶

verboseモードの活用¶

バージョン別変更点まとめ¶

関連記事で詳しく学ぶ¶

🎯 AIエージェント自動化編 ¶

🛠️ プロダクション実装編 ¶

🔧 高度な条件付き実行編 ¶

📚 さらに学ぶには¶

まとめ¶

🔗 関連記事¶

Claude Code Hooks完全ガイド（2026年3月版）¶

Claude Code Hooksとは？¶

Hookイベント一覧（全21種）¶

フックハンドラの種類（4タイプ）¶

非同期フック（async）— 2026年1月追加¶

Exit Codeの制御体系¶

JSON構造化出力による高度な制御¶

PreToolUseの権限判定¶

PermissionRequestの自動応答¶

Stop/SubagentStopの完了強制¶

設定ファイルの配置場所¶

設定例¶

1. /hooks CLIメニューで確認¶

2. 基本的なJSON設定¶

3. SessionStartでコンテキスト注入¶

4. 環境変数の永続化（SessionStart限定）¶

5. スキル/エージェントのfrontmatterにフック定義¶

活用例¶

実践パターン：GitButler連携¶

デバッグとトラブルシューティング¶

フックのテスト¶

Stopフックの無限ループ防止¶

よくある問題¶

verboseモードの活用¶

バージョン別変更点まとめ¶

関連記事で詳しく学ぶ¶

🎯 AIエージェント自動化編¶

🛠️ プロダクション実装編¶

🔧 高度な条件付き実行編¶

📚 さらに学ぶには¶

まとめ¶

🔗 関連記事¶

🎯 AIエージェント自動化編 ¶

🛠️ プロダクション実装編 ¶

🔧 高度な条件付き実行編 ¶