フックリファレンス
このページでは、Claude Codeでフックを実装するためのリファレンスドキュメントを提供します。
例を含むクイックスタートガイドについては、Claude Codeフックの開始を参照してください。
設定
Claude Codeフックは設定ファイルで設定されます:
~/.claude/settings.json
- ユーザー設定.claude/settings.json
- プロジェクト設定.claude/settings.local.json
- ローカルプロジェクト設定(コミットされない)- エンタープライズ管理ポリシー設定
構造
フックはマッチャーによって整理され、各マッチャーは複数のフックを持つことができます:
- matcher: ツール名にマッチするパターン、大文字小文字を区別(
PreToolUse
とPostToolUse
にのみ適用)- 単純な文字列は完全一致:
Write
はWriteツールのみにマッチ - 正規表現をサポート:
Edit|Write
またはNotebook.*
- すべてのツールにマッチするには
*
を使用。空文字列(""
)を使用するか、matcher
を空白のままにすることもできます。
- 単純な文字列は完全一致:
- hooks: パターンがマッチしたときに実行するコマンドの配列
type
: 現在は"command"
のみサポートcommand
: 実行するbashコマンド($CLAUDE_PROJECT_DIR
環境変数を使用可能)timeout
: (オプション)特定のコマンドをキャンセルするまでの実行時間(秒)
UserPromptSubmit
、Notification
、Stop
、SubagentStop
などのマッチャーを使用しないイベントの場合、matcherフィールドを省略できます:
プロジェクト固有のフックスクリプト
環境変数CLAUDE_PROJECT_DIR
(Claude Codeがフックコマンドを起動するときのみ利用可能)を使用して、プロジェクトに保存されたスクリプトを参照でき、Claudeの現在のディレクトリに関係なく動作することを保証できます:
フックイベント
PreToolUse
Claudeがツールパラメータを作成した後、ツール呼び出しを処理する前に実行されます。
一般的なマッチャー:
Task
- サブエージェントタスク(サブエージェントドキュメントを参照)Bash
- シェルコマンドGlob
- ファイルパターンマッチングGrep
- コンテンツ検索Read
- ファイル読み取りEdit
、MultiEdit
- ファイル編集Write
- ファイル書き込みWebFetch
、WebSearch
- Web操作
PostToolUse
ツールが正常に完了した直後に実行されます。
PreToolUseと同じマッチャー値を認識します。
Notification
Claude Codeが通知を送信するときに実行されます。通知は以下の場合に送信されます:
- Claudeがツールを使用する許可が必要な場合。例:「ClaudeはBashを使用する許可が必要です」
- プロンプト入力が少なくとも60秒間アイドル状態の場合。「Claudeはあなたの入力を待っています」
UserPromptSubmit
ユーザーがプロンプトを送信したとき、Claudeが処理する前に実行されます。これにより、プロンプト/会話に基づいて追加のコンテキストを追加したり、プロンプトを検証したり、特定のタイプのプロンプトをブロックしたりできます。
Stop
メインのClaude Codeエージェントが応答を完了したときに実行されます。ユーザーの中断による停止の場合は実行されません。
SubagentStop
Claude Codeサブエージェント(Taskツール呼び出し)が応答を完了したときに実行されます。
SessionEnd
Claude Codeセッションが終了するときに実行されます。クリーンアップタスク、セッション統計のログ記録、またはセッション状態の保存に便利です。
フック入力のreason
フィールドは以下のいずれかになります:
clear
- /clearコマンドでセッションがクリアされたlogout
- ユーザーがログアウトしたprompt_input_exit
- プロンプト入力が表示されている間にユーザーが終了したother
- その他の終了理由
PreCompact
Claude Codeがコンパクト操作を実行しようとする前に実行されます。
マッチャー:
manual
-/compact
から呼び出されたauto
- 自動コンパクト(コンテキストウィンドウが満杯のため)から呼び出された
SessionStart
Claude Codeが新しいセッションを開始するか、既存のセッションを再開するとき(現在は内部的に新しいセッションを開始)に実行されます。既存の問題やコードベースへの最近の変更などの開発コンテキストを読み込むのに便利です。
マッチャー:
startup
- 起動から呼び出されたresume
---resume
、--continue
、または/resume
から呼び出されたclear
-/clear
から呼び出された
フック入力
フックはセッション情報とイベント固有のデータを含むJSONデータをstdinを介して受信します:
PreToolUse入力
tool_input
の正確なスキーマはツールによって異なります。
PostToolUse入力
tool_input
とtool_response
の正確なスキーマはツールによって異なります。
Notification入力
UserPromptSubmit入力
StopとSubagentStop入力
stop_hook_active
は、Claude Codeがすでにストップフックの結果として継続している場合にtrueになります。Claude Codeが無限に実行されることを防ぐために、この値をチェックするか、トランスクリプトを処理してください。
PreCompact入力
manual
の場合、custom_instructions
はユーザーが/compact
に渡すものから来ます。auto
の場合、custom_instructions
は空です。
SessionStart入力
SessionEnd入力
フック出力
フックがClaude Codeに出力を返す方法は2つあります。出力は、ブロックするかどうかと、Claudeとユーザーに表示すべきフィードバックを伝達します。
シンプル:終了コード
フックは終了コード、stdout、stderrを通じてステータスを伝達します:
- 終了コード0: 成功。
stdout
はトランスクリプトモード(CTRL-R)でユーザーに表示されますが、UserPromptSubmit
とSessionStart
では、stdoutがコンテキストに追加されます。 - 終了コード2: ブロッキングエラー。
stderr
がClaudeに自動的にフィードバックされ処理されます。以下のフックイベント別の動作を参照してください。 - その他の終了コード: 非ブロッキングエラー。
stderr
がユーザーに表示され、実行が継続されます。
注意:終了コードが0の場合、Claude Codeはstdoutを見ません。ただし、UserPromptSubmit
フックでは、stdoutがコンテキストとして注入されます。
終了コード2の動作
フックイベント | 動作 |
---|---|
PreToolUse | ツール呼び出しをブロックし、stderrをClaudeに表示 |
PostToolUse | stderrをClaudeに表示(ツールは既に実行済み) |
Notification | N/A、stderrをユーザーにのみ表示 |
UserPromptSubmit | プロンプト処理をブロックし、プロンプトを消去し、stderrをユーザーにのみ表示 |
Stop | 停止をブロックし、stderrをClaudeに表示 |
SubagentStop | 停止をブロックし、stderrをClaudeサブエージェントに表示 |
PreCompact | N/A、stderrをユーザーにのみ表示 |
SessionStart | N/A、stderrをユーザーにのみ表示 |
SessionEnd | N/A、stderrをユーザーにのみ表示 |
高度:JSON出力
フックはより洗練された制御のために、stdout
で構造化されたJSONを返すことができます:
共通JSONフィールド
すべてのフックタイプは、これらのオプションフィールドを含めることができます:
continue
がfalseの場合、フック実行後にClaudeは処理を停止します。
PreToolUse
の場合、これは"permissionDecision": "deny"
とは異なり、特定のツール呼び出しのみをブロックし、Claudeに自動フィードバックを提供します。PostToolUse
の場合、これは"decision": "block"
とは異なり、Claudeに自動フィードバックを提供します。UserPromptSubmit
の場合、これはプロンプトが処理されることを防ぎます。Stop
とSubagentStop
の場合、これは任意の"decision": "block"
出力よりも優先されます。- すべての場合において、
"continue" = false
は任意の"decision": "block"
出力よりも優先されます。
stopReason
はcontinue
に伴い、ユーザーに表示される理由を提供しますが、Claudeには表示されません。
PreToolUse
決定制御
PreToolUse
フックはツール呼び出しが進行するかどうかを制御できます。
"allow"
は許可システムをバイパスします。permissionDecisionReason
はユーザーに表示されますが、Claudeには表示されません。"deny"
はツール呼び出しの実行を防ぎます。permissionDecisionReason
はClaudeに表示されます。"ask"
はUIでツール呼び出しを確認するようユーザーに求めます。permissionDecisionReason
はユーザーに表示されますが、Claudeには表示されません。
PreToolUseフックのdecision
とreason
フィールドは非推奨です。
代わりにhookSpecificOutput.permissionDecision
と
hookSpecificOutput.permissionDecisionReason
を使用してください。非推奨フィールド
"approve"
と"block"
はそれぞれ"allow"
と"deny"
にマップされます。
PostToolUse
決定制御
PostToolUse
フックはツール実行後にClaudeにフィードバックを提供できます。
"block"
は自動的にClaudeにreason
でプロンプトします。undefined
は何もしません。reason
は無視されます。"hookSpecificOutput.additionalContext"
はClaudeが考慮するコンテキストを追加します。
UserPromptSubmit
決定制御
UserPromptSubmit
フックはユーザープロンプトが処理されるかどうかを制御できます。
"block"
はプロンプトが処理されることを防ぎます。送信されたプロンプトはコンテキストから消去されます。"reason"
はユーザーに表示されますが、コンテキストには追加されません。undefined
はプロンプトが正常に進行することを許可します。"reason"
は無視されます。"hookSpecificOutput.additionalContext"
はブロックされていない場合、文字列をコンテキストに追加します。
Stop
/SubagentStop
決定制御
Stop
とSubagentStop
フックはClaudeが継続しなければならないかどうかを制御できます。
"block"
はClaudeが停止することを防ぎます。Claudeがどのように進行すべきかを知るために、reason
を設定する必要があります。undefined
はClaudeが停止することを許可します。reason
は無視されます。
SessionStart
決定制御
SessionStart
フックはセッションの開始時にコンテキストを読み込むことができます。
"hookSpecificOutput.additionalContext"
は文字列をコンテキストに追加します。- 複数のフックの
additionalContext
値は連結されます。
SessionEnd
決定制御
SessionEnd
フックはセッション終了時に実行されます。セッション終了をブロックすることはできませんが、クリーンアップタスクを実行できます。
終了コード例:Bashコマンド検証
JSON出力例:コンテキスト追加と検証のためのUserPromptSubmit
UserPromptSubmit
フックの場合、どちらの方法でもコンテキストを注入できます:
- 終了コード0とstdout:Claudeがコンテキストを見る(
UserPromptSubmit
の特別なケース) - JSON出力:動作をより詳細に制御
JSON出力例:承認付きPreToolUse
MCPツールとの連携
Claude CodeフックはModel Context Protocol(MCP)ツールとシームレスに連携します。MCPサーバーがツールを提供する場合、フックでマッチできる特別な命名パターンで表示されます。
MCPツールの命名
MCPツールはmcp__<server>__<tool>
のパターンに従います。例:
mcp__memory__create_entities
- Memoryサーバーのエンティティ作成ツールmcp__filesystem__read_file
- Filesystemサーバーのファイル読み取りツールmcp__github__search_repositories
- GitHubサーバーの検索ツール
MCPツール用のフック設定
特定のMCPツールまたはMCPサーバー全体をターゲットにできます:
例
コードフォーマット、通知、ファイル保護を含む実用的な例については、開始ガイドのその他の例を参照してください。
セキュリティに関する考慮事項
免責事項
自己責任で使用してください:Claude Codeフックはシステム上で任意のシェルコマンドを自動的に実行します。フックを使用することで、以下を認めることになります:
- 設定するコマンドについて単独で責任を負う
- フックはユーザーアカウントがアクセスできる任意のファイルを変更、削除、またはアクセスできる
- 悪意のあるまたは不適切に書かれたフックはデータ損失やシステム損傷を引き起こす可能性がある
- Anthropicは保証を提供せず、フック使用による損害について一切の責任を負わない
- 本番環境で使用する前に、安全な環境でフックを十分にテストすべきである
設定に追加する前に、常にフックコマンドを確認し理解してください。
セキュリティのベストプラクティス
より安全なフックを書くための主要な実践方法:
- 入力を検証・サニタイズ - 入力データを盲目的に信頼しない
- 常にシェル変数を引用符で囲む -
$VAR
ではなく"$VAR"
を使用 - パストラバーサルをブロック - ファイルパスの
..
をチェック - 絶対パスを使用 - スクリプトの完全パスを指定(プロジェクトパスには
$CLAUDE_PROJECT_DIR
を使用) - 機密ファイルをスキップ -
.env
、.git/
、キーなどを避ける
設定の安全性
設定ファイルでのフックの直接編集は即座に有効になりません。Claude Codeは:
- 起動時にフックのスナップショットを取得
- セッション全体でこのスナップショットを使用
- フックが外部で変更された場合に警告
- 変更を適用するために
/hooks
メニューでの確認が必要
これにより、悪意のあるフック変更が現在のセッションに影響することを防ぎます。
フック実行の詳細
- タイムアウト:デフォルトで60秒の実行制限、コマンドごとに設定可能。
- 個別のコマンドのタイムアウトは他のコマンドに影響しません。
- 並列化:マッチするすべてのフックが並列実行
- 重複排除:同一のフックコマンドは自動的に重複排除
- 環境:Claude Codeの環境で現在のディレクトリで実行
CLAUDE_PROJECT_DIR
環境変数が利用可能で、プロジェクトルートディレクトリ(Claude Codeが開始された場所)の絶対パスが含まれます
- 入力:stdinを介したJSON
- 出力:
- PreToolUse/PostToolUse/Stop/SubagentStop:トランスクリプト(Ctrl-R)に進行状況表示
- Notification/SessionEnd:デバッグのみにログ記録(
--debug
) - UserPromptSubmit/SessionStart:stdoutがClaudeのコンテキストとして追加
デバッグ
基本的なトラブルシューティング
フックが動作しない場合:
- 設定を確認 -
/hooks
を実行してフックが登録されているか確認 - 構文を検証 - JSON設定が有効であることを確認
- コマンドをテスト - まずフックコマンドを手動で実行
- 権限を確認 - スクリプトが実行可能であることを確認
- ログを確認 -
claude --debug
を使用してフック実行の詳細を確認
一般的な問題:
- 引用符がエスケープされていない - JSON文字列内で
\"
を使用 - 間違ったマッチャー - ツール名が正確にマッチしているか確認(大文字小文字を区別)
- コマンドが見つからない - スクリプトの完全パスを使用
高度なデバッグ
複雑なフックの問題の場合:
- フック実行を検査 -
claude --debug
を使用して詳細なフック実行を確認 - JSONスキーマを検証 - 外部ツールでフック入力/出力をテスト
- 環境変数を確認 - Claude Codeの環境が正しいことを確認
- エッジケースをテスト - 異常なファイルパスや入力でフックを試す
- システムリソースを監視 - フック実行中のリソース枯渇をチェック
- 構造化ログを使用 - フックスクリプトでログを実装
デバッグ出力例
claude --debug
を使用してフック実行の詳細を確認:
進行状況メッセージはトランスクリプトモード(Ctrl-R)に表示され、以下を示します:
- 実行中のフック
- 実行されるコマンド
- 成功/失敗ステータス
- 出力またはエラーメッセージ