概要: Claude Code のフックは、AI コーディングセッションの特定のライフサイクルポイントで実行される自動化スクリプトであり、開発者はカスタムコマンドの実行、アクションの検証、コードのフォーマット、通知の送信、プロジェクトルールの適用を行うことができます。これらのフックは、SessionStart、PreToolUse、PostToolUse などのイベントを通じて Claude のワークフローと統合され、設定可能なタイムアウトと終了コードの動作を持つ、コマンドベース、HTTPベース、プロンプトベースの実行パターンをサポートします。
Claude Code のフックシステムは、AI コーディングアシスタントを便利なツールから完全に自動化された開発環境へと変貌させます。ほとんどの開発者は、フックを通じて利用可能な制御の範囲を認識していません。
ただし、フックは単にファイル編集後にスクリプトを実行するだけではありません。Claude の意思決定プロセス全体にわたる傍受ポイントを提供します。コマンドを実行する前。ツールの呼び出しが失敗した後。許可が必要な場合。ユーザープロンプトを処理する前でさえ。
このガイドでは、公式ドキュメントで提供されているすべての内容に加え、コミュニティの議論で実稼働環境で実際に機能することが明らかにされている実践的なパターンを網羅しています。
Claude Code フックの実際の機能
公式の Claude Code ドキュメントによると、フックは、Claude Code のライフサイクルの特定のポイントで実行される、ユーザー定義のシェルコマンド、HTTP エンドポイント、またはプロンプトインジェクションです。標準入力経由で構造化された JSON 入力を受け取り、終了コードまたは HTTP 応答を通じてワークフローを制御します。
自動化は、ほとんどのガイドが示唆するよりも深いレベルで行われます。フックはツールの実行を完全にブロックしたり、Claude の推論に追加のコンテキストを注入したり、外部サービスをトリガーしたり、Claude が尊重しなければならない検証ルールを強制したりできます。
3 つのコアフックタイプが存在します。
- コマンドフック: stdout、stderr、および終了コードを通じて通信するシェルスクリプト
- HTTP フック: POST リクエストを受け取り JSON 応答を返すリモートエンドポイント
- プロンプトフック: 特定のイベントで Claude のコンテキストに注入される動的な指示
各タイプは異なる自動化パターンに対応します。コマンドフックはローカルの検証とフォーマットを処理します。HTTP フックは外部サービスやデータベースと統合します。プロンプトフックは外部プロセスなしで Claude の動作を変更します。
フックのライフサイクルとイベントシステム
公式ドキュメントでは、Claude Code の実行フロー中に発生する複数のフックイベント (SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Notification など) を定義しています。各イベントが発生するタイミングを理解することが、どのような自動化が可能になるかを決定します。
| イベント | 発生時期 | ブロック可能 |
|---|---|---|
| SessionStart | セッションが開始または再開されるとき | いいえ |
| UserPromptSubmit | Claude が処理する前にプロンプトを送信するとき | はい |
| PreToolUse | ツールの呼び出しが実行される前 | はい |
| PermissionRequest | 権限ダイアログが表示されるとき | はい |
| PostToolUse | ツールの呼び出しが成功した後 | いいえ |
| PostToolUseFailure | ツールの呼び出しが失敗した後 | いいえ |
| Notification | Claude Code が通知を送信するとき | いいえ |
| SubmitMessage | Claude がユーザーにメッセージを送信するとき | いいえ |
| ContextCompaction | コンテキストウィンドウが制限に近づいたとき | いいえ |
ブロック機能が最も重要です。PreToolUse フックは、危険な操作が実行される前にそれを防止できます。終了コード 1 はアクションをブロックします。終了コード 0 はそれを許可します。終了コード 2 は Claude に再考を促します。
しかし、待ってください。PostToolUse フックは、ツールが既に実行されているため、アクションを取り消すことはできません。この制限は、検証ロジックがどのように構造化されるかを形成します。重要なチェックは PreToolUse に属します。クリーンアップとフォーマットは PostToolUse に属します。
Claude Code セットアップ中に AI ツール特典を閲覧する
Claude Code のフックを扱っている場合、ワークフローの周りで他の AI ツールも選択している可能性があります。Get AI Perks は、AI およびクラウドツールのスタートアップクレジットとソフトウェア割引を 1 か所に集めています。このプラットフォームには 200 以上のオファーが含まれており、各オファーには特典条件と請求ガイドが含まれています。
Claude またはその他の AI ツールの特典をお探しですか？
Get AI Perks をチェックして以下を行います。
- Claude およびその他の AI ツールのオファーを閲覧する
- 適用前に特典条件を比較する
- ツールスタック全体でスタートアップ割引を見つける
👉 Get AI Perks にアクセスして、現在の AI ソフトウェア特典を探索してください。
設定とファイル構造
フックは、プロジェクト内の .claude/settings.json ファイルで定義されます。設定スキーマは、グローバルフックと、フックがいつ実行されるかをフィルタリングするツール固有のマッチャーをサポートします。
基本的なコマンドフック構造:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
${file} 変数は、ツールの入力からの実際のファイルパスに展開されます。公式ドキュメントによると、フックはコマンドフィールドと args フィールドでこれらの変数展開をサポートしています。
フックの場所の階層
Claude Code は、明確な優先順位で、フック定義のために複数の場所をチェックします。
- プロジェクトレベル: 現在のワークスペースにある .claude/settings.json
- ユーザーレベル: すべてのセッション用の ~/.claude/settings.json
- プラグイン提供: インストールされたプラグインにバンドルされたフック
プロジェクトフックは、同じイベントに対してユーザーフックをオーバーライドします。これにより、プロジェクト固有のフォーマットルールを維持しながら、グローバル通知ハンドラーを維持できます。
選択的実行のためのマッチャーパターン
マッチャーシステムは、フックを特定のツールまたは条件にフィルタリングします。マッチャーがない場合、フックはイベントが発生するたびにトリガーされます。
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
pathPattern フィールドは glob 構文を受け入れます。toolName フィールドは、edit_file、execute_command、read_file、create_directory などの Claude の組み込みツールと照合されます。
コミュニティの議論によると、マッチャーの組み合わせは AND ロジックで機能します。フックが実行されるためには、指定されたすべてのマッチャーが一致する必要があります。
コマンドフック: シェルスクリプト統合
コマンドフックは、構造化された JSON 入力でシェルコマンドまたはスクリプトを実行します。ローカル自動化の最も一般的なフックタイプを表します。
公式ドキュメントでは、コマンドフックは標準入力経由で JSON を次の構造で受け取ると指定しています。
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }スクリプトはこの入力を解析して意思決定を行います。Python の検証フックは次のようになります:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
終了コード 0 は操作を許可します。終了コード 1 はそれをブロックし、stderr メッセージを Claude に表示します。終了コード 2 はイベントに応じて特別な動作をトリガーします。
終了コード 2 の動作
公式のフック参照ドキュメントによると、終了コード 2 にはイベント固有の意味があります (PreToolUse: ブロックして再考を促します; UserPromptSubmit: ブロックせずにコンテキストを提供します; PermissionRequest: 権限をブロックします):
- PreToolUse: ツールをブロックし、stderr メッセージをコンテキストとして Claude に再考を促します
- UserPromptSubmit: stderr 出力をブロックせずに、追加のコンテキストとして提供します
- PermissionRequest: 権限の付与をブロックします
これにより、ハードブロックと許可の間の妥協点が生まれます。Claude は、操作が問題となる可能性のある理由についてのフィードバックを受け取り、アプローチを調整できます。
非同期コマンドフック
async: true フラグは、Claude のワークフローをブロックせずにフックをバックグラウンドで実行します。これは、デプロイ通知やメトリック収集などの遅い操作にとって重要です。
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
非同期フックが発生すると、Claude Code はプロセスを開始し、すぐに続行します。timeout フィールドは、実行時間の最大値を秒単位で設定します。指定しない場合、非同期フックは 10 分のデフォルトタイムアウトを使用します。
現実的な話ですが、非同期フックは Claude が続行した後に実行されるため、操作をブロックすることはできません。ログ記録、通知、クリーンアップには機能しますが、検証には機能しません。
HTTP フック: 外部サービス統合
HTTP フックは、リモートエンドポイントに JSON ペイロードを POST し、応答を解析して意思決定を制御します。これにより、検証サービス、データベース、サードパーティツールとの統合が可能になります。
基本的な HTTP フック設定:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
ペイロード構造はコマンドフックの入力と一致しますが、HTTP POST 本体として配信されます。応答が Claude の次のアクションを決定します。
HTTP 応答処理
公式ドキュメントによると、HTTP フックはステータスコードと本文の内容に基づいて応答を解釈します。
| ステータスコード | 効果 | メッセージソース |
|---|---|---|
| 200 | 操作を許可する | 応答本文 (オプション) |
| 400 | 操作をブロックする | Claude に表示される応答本文 |
| 500 | フックエラー、操作を許可する | ログに記録されるが、Claude には表示されない |
| その他 | 操作を許可する | フックの失敗はワークフローをブロックしない |
応答本文には、Claude がコンテキストとして表示する message フィールドを含めることができます。これにより、検証サービスが操作がブロックされた理由を説明できるようになります。
環境変数補間
HTTP フックは、url、headers、その他の文字列フィールドで ${VAR} 構文をサポートします。変数は、Claude Code が実行される環境から展開されます。
公式 MCP ドキュメントによると、環境変数展開はデフォルトのフォールバック構文をサポートします: ${VAR:-default} は、VAR が設定されていれば VAR に展開され、それ以外の場合はデフォルト値を使用します。
セキュリティ上の制約: GitHub の issue #28044 によると、HTTP フックは、allowedEnvVars 設定フィールドに明示的にリストされている環境変数のみにアクセスできます。これにより、意図しない資格情報の漏洩が防止されます。
プロンプトフック: コンテキスト注入
プロンプトフックは、特定のイベントで Claude のコンテキストに動的な指示を注入します。外部プロセスや API 呼び出しなしで動作を変更します。
| { “event”: “SessionStart”, “prompt”: “You are working on a TypeScript project. Always use strict null checks and prefer async/await over promises.” } |
注入されたテキストは、そのセッションの Claude のシステム指示の一部になります。プロンプトフックは、イベントデータに基づいて展開されるテンプレート変数を使用することもできます。
動的なプロンプト生成
公式ドキュメントによると、プロンプトフックは動的なプロンプトを生成するコマンドフィールドをサポートしています。
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
コマンドは標準入力経由で標準 JSON 入力を受け取り、stdout にプロンプトテキストを出力します。これにより、プロジェクトの状態に基づいたコンテキスト認識型指示生成が可能になります。
エージェントベースのフック
エージェントフックは、直接のプロンプト注入の代わりにイベントを処理するサブエージェントを指定します。サブエージェントはイベントに関するコンテキストを受け取り、多段階の推論を実行できます。
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “A tool call failed. Analyze the error and suggest fixes.” } |
指定されたサブエージェントは、プロジェクト設定で定義されている必要があります。エージェントフックは、単純なプロンプト注入では提供できない複雑な意思決定ロジックを可能にします。
実践的なフックパターン
コミュニティの議論と公式の例は、実稼働環境で確実に機能する特定の自動化パターンを明らかにしています。
編集後のコードの自動フォーマット
最も一般的なパターンは、Claude がファイルを編集した後にコードを自動的にフォーマットすることです。
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
${toolInput.path} 変数は、編集されたファイルパスに展開されます。PostToolUse は、正常な編集後にフォーマットが行われることを保証しますが、Claude のワークフローをブロックしません。
保護されたファイル変更のブロック
PreToolUse フックは、ファイル保護ルールを強制します。
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
スクリプトは、ターゲットパスを保護されたパターンと照合し、コード 1 で終了して禁止された編集をブロックします。
Claude が入力を必要とするときに通知を受ける
公式ワークフローガイドによると、Notification フックはデスクトップアラートをトリガーしたり、外部サービスにメッセージを送信したりできます。
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
これは、Claude Code が通知を送信するたびに発生します。これには、ユーザー入力を待っている場合や、タスク完了後などが含まれます。
コンパクション後のコンテキストの再注入
ContextCompaction フックは、会話ウィンドウがいっぱいになったときに重要なコンテキストを復元します。
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
コマンドの出力は、コンパクションが古いメッセージを削除した後に Claude のコンテキストに再注入されます。これにより、重要なプロジェクト固有の指示の損失を防ぎます。
設定変更の監査
Claude が設定ファイルを変更したときに追跡します。
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
非同期実行は、git 操作が完了するのを待たずに Claude をブロックしないようにします。これにより、手動ステージングなしで設定変更の監査証跡が作成されます。
JSON 出力と意思決定制御
コマンドフックは、単純な終了コードを超えた詳細なフィードバックを提供するために、構造化された JSON を出力できます。公式リファレンスによると、JSON 出力は Claude が意思決定のために解釈する複数フィールドの応答を可能にします。
| { “allowed”: false, “message”: “This file is protected by team policy”, “suggestion”: “Create a new file in src/features/ instead” } |
allowed フィールドは、操作が続行されるかどうかを制御します。message は Claude にコンテキストとして表示されます。suggestion フィールドは代替アプローチを提供します。
フックが JSON を出力するには、次のことを行う必要があります:
- 標準出力に有効な JSON を書き込む
- コード 0 (許可) または 1 (ブロック) で終了する
- 少なくとも allowed ブールフィールドを含める
Claude Code は JSON を解析し、フィードバックループを強化するために使用します。終了コードは依然として主要な決定を決定しますが、JSON はより豊かなコンテキストを提供します。
フック入力フィールド参照
すべてのフックは、共通フィールドとイベント固有のデータを含む JSON オブジェクトを標準入力経由で受け取ります。完全なスキーマを理解することで、より高度なフックロジックが可能になります。
共通入力フィールド
すべてのフックは、これらの基本フィールドを受け取ります。
- event: フックイベント名 (例: “PreToolUse”)
- sessionId: 現在の Claude セッションの一意の識別子
- turnId: 現在の会話ターンの識別子
- timestamp: イベントが発生した ISO 8601 タイムスタンプ
ツールイベントフィールド
PreToolUse、PostToolUse、PostToolUseFailure イベントには以下が含まれます。
- toolName: 呼び出されているツールの名前 (edit_file、execute_command など)
- toolInput: ツールの入力パラメータを含むオブジェクト
- toolResponse: ツールの出力データ (PostToolUse のみ)
- error: メッセージとコードを含むエラー詳細 (PostToolUseFailure のみ)
toolInput の構造はツールによって異なります。edit_file の場合は path と content を含みます。execute_command の場合は command と args を含みます。
権限イベントフィールド
PermissionRequest イベントには以下が含まれます。
- permissionType: 要求されている権限のタイプ (file_write、command_execute など)
- requestedAction: 権限を必要とする特定の操作
- resourcePath: 影響を受けるファイルパスまたはリソース識別子
MCP ツールフック
公式のフックリファレンスによると、フックは mcpTool マッチャーフィールドを使用して Model Context Protocol (MCP) ツールと照合できます。これにより、Claude が MCP サーバーによって提供される外部ツールを使用するときにフックが実行されます。
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
mcpTool 値は、形式 server-name/tool-name のツール名と照合されます。これにより、データベースクエリ、API 呼び出し、またはその他の外部操作の検証ロジックが可能になります。
GitHub の機能リクエストは、MCP サーバー通知を検査し、外部イベントに応答できるフックを含む、MCP 統合の深化に対する関心の高まりを示しています。
セキュリティに関する考慮事項
フックは、Claude Code 自体と同じ権限で実行されます。これは、マルチユーザー環境および共有構成にセキュリティ上の影響を与えます。
コマンド実行サンドボックス
GitHub issue #28044 によると、HTTP フックはネットワークアクセスを制限し、環境変数をフィルタリングするサンドボックスプロキシを経由します。コマンドフックにはそのような制限はありません。シェルアクセスでフルに実行されます。
ドキュメントでは、これらのプラクティスを推奨しています:
- フックコマンドに資格情報を保存しないでください
- 機密データには環境変数を使用してください
- ${...} 展開からのすべての入力を検証してください
- 外部サービスにタイムアウト制限を実装してください
- 失敗時にブロックされるのを防ぐために、非クリティカルな操作には非同期フックを使用してください
フック実行の分離
~/.claude/settings.json のユーザーレベルフックは、すべてのプロジェクトに適用されます。これは、異なる信頼境界を越えて作業するときにリスクを生じます。プロジェクトレベルのフックはユーザーレベルのフックをオーバーライドしますが、それらを完全に無効にすることはできません。
Claude Code の /hooks メニューには、現在のセッションでアクティブなすべてのフックが表示されます。機密性の高いプロジェクトで作業する前にこのリストを確認することは、潜在的なセキュリティ上の懸念を特定するのに役立ちます。
デバッグとトラブルシューティング
フックの失敗は、Claude の会話で常に明確に表示されるとは限りません。公式ドキュメントでは、いくつかのデバッグアプローチを提供しています。
フック実行ログ
Claude Code は、セッションデバッグ出力にフック実行を記録します。トラブルシューティングガイドによると、デバッグログを有効にすると、次のことが明らかになります。
- 各イベントに一致したフック
- 各フックに送信された JSON 入力
- フックプロセスの stdout および stderr 出力
- 終了コードと実行時間
- HTTP フックの HTTP 応答コードと本文
Claude Code を起動する前に環境で CLAUDE_DEBUG=1 を設定して、デバッグログを有効にします。
フックの独立したテスト
コマンドフックは、JSON 入力を手動で構築することで、Claude Code の外部でテストできます。
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
これにより、実際の Claude 操作をトリガーせずにフックロジックを検証できます。終了コードと stdout/stderr 出力は、期待される動作と一致する必要があります。
一般的なフックの失敗
コミュニティの議論では、これらの頻繁な問題が特定されています。
- タイムアウトエラー: デフォルトの 10 分のタイムアウトが遅い操作には短すぎます—timeout フィールドで増やしてください
- パス展開の失敗: ${file} などの変数が、ファイルコンテキストを含まないイベントでは未定義です
- 権限エラー: フックスクリプトに実行権限がありません—chmod +x script.sh を実行してください
- JSON 解析エラー: フックからの無効な JSON 出力—返す前に jq で検証してください
- 環境変数の利用不可: フックプロセスに伝播されていない変数—Claude Code の環境を確認してください
フックのパフォーマンスへの影響
同期フックは、完了またはタイムアウトまで Claude のワークフローをブロックします。デフォルトの 10 分のタイムアウトは無限のハングを防ぎますが、短い遅延でさえ複数の操作にわたって蓄積されます。
実務家によると、単純な検証フックはパフォーマンスへの影響がほとんどありません。ファイルフォーマットフックは、目立つが許容できるパフォーマンスへの影響をもたらします。外部 API 呼び出しはワークフローの摩擦を生み出す可能性があります。重い計算操作は非同期実行の恩恵を受けます。
フックのバッチ処理
複数のフックが同じイベントに一致できます。リファレンスドキュメントによると、フックは定義順にシーケンシャルに実行されます。いずれかのフックが操作をブロックした場合、残りのフックは実行されません。
これはパフォーマンスにとって重要です。200ms の 5 つの同期フックは、イベントごとに 1 秒追加されます。関連する検証を 1 つのフックにまとめることで、オーバーヘッドが削減されます。
高度なパターン
基本的な自動化を超えて、フックは高度なワークフローカスタマイズを可能にします。
ステートフルなフックチェーン
フックは、ファイルやデータベースを使用して、実行間で状態を維持できます。PostToolUse フックは、正常な操作を記録する可能性があり、PreToolUse フックは後でそれに対して検証します。
| #!/bin/bash # Record successful edits echo “${toolInput.path}” >> .claude/edit-history.txt |
補完的な PreToolUse フックは、この履歴をチェックして、重複する操作を防いだり、順序制約を強制したりできます。
条件付きフックのアクティブ化
環境変数は、実行時にフックの動作を制御します。CLAUDE_SKIP_HOOKS=1 を設定すると、緊急時にはフックが無効になります。
フック自体は環境フラグをチェックできます。
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Apply strict validation exit 1 fi exit 0 |
これにより、設定変更なしで開発モードと本番モードの動作が可能になります。
複数ステージ検証
PreToolUse フックは、終了コード 2 が Claude に警告付きで続行できるようにする複数ティア検証を実装できます。
- ハード障害 (終了コード 1): 危険な操作をブロックする
- ソフト警告 (終了コード 2): Claude に再考を促す
- コンテキスト付きパス (終了コード 0 + JSON): 追加情報を提供する
これは、バイナリの許可/拒否よりもニュアンスのある検証スペクトルを作成します。
CI/CD との統合
公式プラットフォーム統合ドキュメントによると、Claude Code は CI/CD 環境で実行され、コードレビューと問題トリアージを自動化します。フックはこの自動化を拡張します。
GitHub Actions ワークフローは、自動化されたセッション中にチームポリシーを強制するフックを定義できます。
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
STRICT_MODE フラグは、フックスクリプトの条件付き検証ロジックをアクティブにします。これにより、自動化されたセッションが、対話型開発よりも厳格なルールに従うようになります。
監査証跡生成
CI 環境の PostToolUse フックは、Claude のすべての操作の詳細な監査ログを作成します。
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
バックグラウンドロギングはパフォーマンスに影響しませんが、コンプライアンスとデバッグのために完全な操作履歴を提供します。
/hooks メニュー
Claude Code は /hooks コマンドを提供し、現在のセッションでアクティブなすべてのフックを表示します。公式ドキュメントによると、このメニューは以下を表示します。
- フックイベントタイプ
- マッチャーパターン
- コマンドまたは URL エンドポイント
- フックが非同期で実行されるかどうか
- 構成ソース (プロジェクト、ユーザー、またはプラグイン)
フックを選択すると、その完全な構成が表示され、現在のセッションで一時的に無効にすることができます。
フックの無効化または削除
フックは、フック定義に "enabled": false を追加することで、構成を削除せずに無効にできます。これにより、構成は保持されますが、実行は防止されます。
フックを完全に削除するには、対応する settings.json ファイルからエントリを削除します。変更は、セッションの再起動時、または /reload を実行したときに有効になります。
スキルとエージェントでのフック
公式ドキュメントによると、スキルまたはサブエージェント構成内で定義されたフックは、そのスキルまたはエージェントが実行された場合にのみ適用されます。これにより、特定のワークフローの特殊な自動化が可能になります。
デバッグサブエージェントには、すべてのツールの呼び出しをログに記録するフックが含まれる場合があります。
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
これらのフックは、通常の Claude Code 操作中ではなく、デバッガーエージェントセッション中にのみ発生します。
スクリプトのパスによる参照
フックコマンドは、相対パスと絶対パスの両方をサポートします。相対パスは、Claude Code が実行されるプロジェクトルートから解決されます。
コミュニティの議論からのベストプラクティス:
- フックスクリプトを .claude/hooks/ ディレクトリに保存する
- わかりやすい名前を使用する: hook1.sh ではなく validate-typescript.sh
- スクリプトを実行可能にする: chmod +x .claude/hooks/*.sh
- shebang 行を含める: #!/usr/bin/env bash または #!/usr/bin/env python3
- bash スクリプトで set -e を使用してエラー処理を追加する
将来のフック機能
GitHub の機能リクエストは、計画中および要求されているフックの拡張機能を明らかにしています。
- インラインスクリプトフック: 外部ファイルなしで settings.json に直接フックロジックを定義する
- MCP ツール統合: シェルコマンドの代わりにフックから MCP サーバーツールを呼び出す
- マルチエージェントコラボレーション: 異なるマシン上の Claude インスタンス間で調整するフック
- 強化された型付け: フックの入力/出力スキーマの TypeScript 型定義
GitHub issue #4274 によると、統合フックタイプ (MCP ツール、インラインスクリプト、API 呼び出し) の要求は、構成を簡素化し、開発者エクスペリエンスを向上させることを目的としています。
よくある質問
フックは Claude が危険なコマンドを実行するのを防ぐことができますか？
はい。PreToolUse フックは、コード 1 で終了することで、すべてのツールの実行をブロックできます。これには、ファイル編集、コマンド実行、MCP ツールの呼び出しが含まれます。フックは完全なツールの入力を受け取り、操作を許可する前に任意の基準に対して検証できます。
機能しないフックをデバッグするにはどうすればよいですか？
Claude Code を起動する前に CLAUDE_DEBUG=1 でデバッグログを有効にします。セッションログで、どのフックが一致したか、送信された JSON 入力、stdout/stderr 出力、終了コードなど、フック実行の詳細を確認します。サンプル JSON をフックスクリプトにパイプして、フックを個別にテストします。
フックはすべての Claude Code プラットフォームで機能しますか？
フックは CLI、デスクトップアプリ、および VS Code 拡張機能で機能します。公式ドキュメントによると、フックはファイルシステムへのアクセスがある Claude Code が実行される場所ならどこでも実行されます。ブラウザベースの Claude とモバイルアプリは、サンドボックス制約のためフックをサポートしていません。
フックは Claude の応答または動作を変更できますか？
プロンプトフックは Claude の動作に影響を与える指示を注入します。エージェントフックは、イベント処理を特殊なサブエージェントに委譲します。ただし、フックは Claude の生成されたテキストや推論プロセスを直接変更することはできません。コンテキストの提供と操作のブロックによって機能します。
async と sync フックの違いは何ですか？
同期フックは、完了またはタイムアウトまで Claude のワークフローをブロックします。非同期フックは、ブロックせずにバックグラウンドで実行されます。同期フックは終了コードを通じて操作を防止できます。非同期フックは Claude がフック完了前に続行するため、ブロックできません。ログ記録と通知には非同期、検証には同期を使用してください。
チーム間でフックを共有するにはどうすればよいですか？
.claude/settings.json ファイルをバージョン管理にコミットします。プロジェクトレベルのフックは、リポジトリをクローンするすべてのチームメンバーに適用されます。組織全体のポリシーについては、チームはメンバーが ~/.claude/settings.json にコピーする共有ユーザーレベル設定ファイルを維持できます。
HTTP フックはファイアウォールの内側にある内部 API を呼び出すことができますか？
はい、Claude Code がそれらの API へのネットワークアクセスを持つ環境で実行されている場合です。HTTP フックは、Claude Code を実行しているマシンから標準の POST リクエストを行います。企業ファイアウォールと VPN は通常どおり適用されます。ドキュメントで言及されているサンドボックスプロキシは、ネットワークルーティングではなく、環境変数の公開を制御します。
フックは Claude Code のトークン使用量を増やしますか？
プロンプトフックは Claude のコンテキストにテキストを注入するため、トークンを消費します。コマンドフックと HTTP フックはトークン使用量に直接影響しませんが、それらの出力 (エラーメッセージ、提案) は会話コンテキストの一部になります。説明メッセージを含む終了コード 2 は、単純なブロックを含む終了コード 1 よりも多くのコンテキストを追加します。
結論
Claude Code のフックは、AI アシスタントを強力なツールから完全に自動化された開発プラットフォームへと変革します。イベントシステムは、セッションの初期化からコンテキストコンパクションまで、Claude のワークフロー全体にわたる傍受ポイントを提供します。
コマンドフックはローカルの検証とフォーマットを処理します。HTTP フックは外部サービスとデータベースを統合します。プロンプトフックはコンテキスト注入を通じて動作を変更します。これらを組み合わせることで、チームポリシーを強制し、コード品質を維持し、既存の開発インフラストラクチャと統合する自動化パターンが可能になります。
マッチャーシステムは、フックを特定のツールとファイルパターンにフィルタリングします。終了コードと JSON 出力は意思決定フローを制御します。非同期実行は、遅い操作でのブロックを防ぎます。完全な設定スキーマは、単純な自動フォーマットから複雑な複数ステージ検証まで、すべてをサポートします。
コードフォーマットのための基本的な PostToolUse フックから始めます。ポリシーが登場するにつれて PreToolUse 検証を追加します。動作変更のためにプロンプトフックを試します。チーム全体の強制のために HTTP 統合を構築します。
新しい機能が出荷されるにつれて、完全なフックリファレンスと更新された設定スキーマについては、公式の Claude Code ドキュメントを確認してください。
