フックリファレンス
このページでは、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ツール呼び出し)が応答を完了したときに実行されます。
PreCompact
Claude Codeがコンパクト操作を実行しようとする前に実行されます。
マッチャー:
manual
-/compact
から呼び出しauto
- 自動コンパクトから呼び出し(コンテキストウィンドウが満杯のため)
フック入力
フックは、セッション情報とイベント固有のデータを含む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
は空です。
フック出力
フックがClaude Codeに出力を返す方法は2つあります。出力は、ブロックするかどうかと、Claudeとユーザーに表示すべきフィードバックを伝達します。
シンプル:終了コード
フックは終了コード、stdout、stderrを通じてステータスを伝達します:
- 終了コード0: 成功。
stdout
はトランスクリプトモード(CTRL-R)でユーザーに表示されますが、UserPromptSubmit
の場合は例外で、stdoutがコンテキストに追加されます。 - 終了コード2: ブロッキングエラー。
stderr
がClaudeに自動的にフィードバックされ処理されます。以下のフックイベント別の動作を参照してください。 - その他の終了コード: 非ブロッキングエラー。
stderr
がユーザーに表示され、実行が継続されます。
注意:Claude Codeは終了コードが0の場合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をユーザーのみに表示 |
高度: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には表示されません。(非推奨の"approve"
値 +reason
も同じ動作をします。)"deny"
はツール呼び出しの実行を防ぎます。permissionDecisionReason
はClaudeに表示されます。("block"
値 +reason
も同じ動作をします。)"ask"
はユーザーにUIでツール呼び出しを確認するよう求めます。permissionDecisionReason
はユーザーに表示されますが、Claudeには表示されません。
PostToolUse
決定制御
PostToolUse
フックは、ツール呼び出しが進行するかどうかを制御できます。
"block"
は自動的にClaudeにreason
でプロンプトします。undefined
は何もしません。reason
は無視されます。
UserPromptSubmit
決定制御
UserPromptSubmit
フックは、ユーザープロンプトが処理されるかどうかを制御できます。
"block"
はプロンプトが処理されることを防ぎます。送信されたプロンプトはコンテキストから消去されます。"reason"
はユーザーに表示されますが、コンテキストには追加されません。undefined
はプロンプトが正常に進行することを許可します。"reason"
は無視されます。"hookSpecificOutput.additionalContext"
は、ブロックされていない場合に文字列をコンテキストに追加します。
Stop
/SubagentStop
決定制御
Stop
とSubagentStop
フックは、Claudeが継続しなければならないかどうかを制御できます。
"block"
はClaudeが停止することを防ぎます。Claudeがどのように進行すべきかを知るためにreason
を入力する必要があります。undefined
はClaudeが停止することを許可します。reason
は無視されます。
終了コード例: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サーバーのcreate entitiesツールmcp__filesystem__read_file
- Filesystemサーバーのread fileツール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
環境変数が利用可能で、プロジェクトルートディレクトリの絶対パスが含まれます
- 入力:stdinを介したJSON
- 出力:
- PreToolUse/PostToolUse/Stop:トランスクリプト(Ctrl-R)で進行状況表示
- Notification:デバッグのみにログ(
--debug
)
デバッグ
基本的なトラブルシューティング
フックが動作しない場合:
- 設定を確認 -
/hooks
を実行してフックが登録されているかを確認 - 構文を検証 - JSON設定が有効であることを確認
- コマンドをテスト - まずフックコマンドを手動で実行
- 権限を確認 - スクリプトが実行可能であることを確認
- ログを確認 -
claude --debug
を使用してフック実行の詳細を確認
一般的な問題:
- 引用符がエスケープされていない - JSON文字列内で
\"
を使用 - 間違ったマッチャー - ツール名が完全に一致することを確認(大文字小文字を区別)
- コマンドが見つからない - スクリプトの完全パスを使用
高度なデバッグ
複雑なフックの問題の場合:
- フック実行を検査 -
claude --debug
を使用して詳細なフック実行を確認 - JSONスキーマを検証 - 外部ツールでフック入力/出力をテスト
- 環境変数を確認 - Claude Codeの環境が正しいことを確認
- エッジケースをテスト - 異常なファイルパスや入力でフックを試す
- システムリソースを監視 - フック実行中のリソース枯渇をチェック
- 構造化ログを使用 - フックスクリプトでログを実装
デバッグ出力例
claude --debug
を使用してフック実行の詳細を確認:
進行状況メッセージはトランスクリプトモード(Ctrl-R)に表示され、以下を示します:
- 実行中のフック
- 実行されるコマンド
- 成功/失敗ステータス
- 出力またはエラーメッセージ