476| `async` | いいえ | `true` の場合、ブロックせずにバックグラウンドで実行されます。[バックグラウンドでフックを実行](#run-hooks-in-the-background)を参照してください |476| `async` | いいえ | `true` の場合、ブロックせずにバックグラウンドで実行されます。[バックグラウンドでフックを実行](#run-hooks-in-the-background)を参照してください |
477| `asyncRewake` | いいえ | `true` の場合、バックグラウンドで実行され、終了コード 2 で Claude を起動します。フックの stderr、または stderr が空の場合は stdout が [システムリマインダー](/docs/ja/glossary#system-reminder)として Claude に表示されるため、Claude は長時間実行されるバックグラウンドの失敗に対応できます |477| `asyncRewake` | いいえ | `true` の場合、バックグラウンドで実行され、終了コード 2 で Claude を起動します。フックの stderr、または stderr が空の場合は stdout が [システムリマインダー](/docs/ja/glossary#system-reminder)として Claude に表示されるため、Claude は長時間実行されるバックグラウンドの失敗に対応できます |
478| `shell` | いいえ | このフックに使用するシェル。`"bash"` または `"powershell"` を受け入れます。デフォルトは `"bash"`、または Git Bash がインストールされていない場合は Windows で `"powershell"`。`"powershell"` を設定すると、Windows 上で PowerShell 経由でコマンドが実行されます。フックは PowerShell を直接生成するため、`CLAUDE_CODE_USE_POWERSHELL_TOOL` は不要です。`args` が設定されている場合は無視されます |478| `shell` | いいえ | このフックに使用するシェル。`"bash"` または `"powershell"` を受け入れます。デフォルトは `"bash"`、または Git Bash がインストールされていない場合は Windows で `"powershell"`。`"powershell"` を設定すると、Windows 上で PowerShell 経由でコマンドが実行されます。フックは PowerShell を直接生成するため、`CLAUDE_CODE_USE_POWERSHELL_TOOL` は不要です。`args` が設定されている場合は無視されます |
479| `onFailure` | いいえ | フックが失敗したときにアクションがどうなるか。`"continue"`（デフォルト）または `"block"`。[フックが失敗したときにアクションをブロックする](#block-the-action-when-a-hook-fails)を参照してください。Claude Code v2.1.295 以降が必要です |
479 480
480<a id="exec-form-and-shell-form" />481<a id="exec-form-and-shell-form" />
481 482
533| `url` | はい | POST リクエストを送信する URL |534| `url` | はい | POST リクエストを送信する URL |
534| `headers` | いいえ | キー値ペアとしての追加 HTTP ヘッダー。値は `$VAR_NAME` または `${VAR_NAME}` 構文を使用した環境変数補間をサポートします。`allowedEnvVars` にリストされている変数のみが解決されます |535| `headers` | いいえ | キー値ペアとしての追加 HTTP ヘッダー。値は `$VAR_NAME` または `${VAR_NAME}` 構文を使用した環境変数補間をサポートします。`allowedEnvVars` にリストされている変数のみが解決されます |
535| `allowedEnvVars` | いいえ | ヘッダー値に補間される可能性のある環境変数名のリスト。リストされていない変数への参照は空の文字列に置き換えられます。環境変数補間が機能するために必須 |536| `allowedEnvVars` | いいえ | ヘッダー値に補間される可能性のある環境変数名のリスト。リストされていない変数への参照は空の文字列に置き換えられます。環境変数補間が機能するために必須 |
537| `onFailure` | いいえ | フックが失敗したときにアクションがどうなるか。`"continue"`（デフォルト）または `"block"`。[フックが失敗したときにアクションをブロックする](#block-the-action-when-a-hook-fails)を参照してください。Claude Code v2.1.295 以降が必要です |
536 538
537Claude Code はフックの [JSON 入力](#hook-input-and-output)を `Content-Type: application/json` の POST リクエスト本体として送信します。レスポンス本体はコマンド フックと同じ [JSON 出力形式](#json-output)を使用します。539Claude Code はフックの [JSON 入力](#hook-input-and-output)を `Content-Type: application/json` の POST リクエスト本体として送信します。レスポンス本体はコマンド フックと同じ [JSON 出力形式](#json-output)を使用します。
538 540
821 終了コード出力823 終了コード出力
822</h3>824</h3>
823 825
824フック コマンドからの終了コードは、Claude Code にアクションが進行すべきか、ブロックされるべきか、無視されるべきかを伝えます。終了コードは単独で作用するわけではありません。Claude Code は 0 だけでなくすべての終了コードで stdout から [JSON 出力フィールド](#json-output)を読み取ります。標準の決定モデルを使用するイベントでは、解析されたオブジェクトがスキーマ検証に合格すると、終了コードとともに効果を持ちます。終了 2 によるブロックは、JSON で上書きできない唯一の結果です。826フックの終了コードは、ツール呼び出しやプロンプトなど、フックをトリガーしたアクションを続行するかどうかを Claude Code に伝えます。完了した実行の結果は次の 3 つのいずれかです。
825 827
826イベントごとの例外は 2 つの表にまとめられています。[イベントごとの終了コード 2 動作](#exit-code-2-behavior-per-event)は各イベントで終了コードが何をするかを示し、[決定制御](#decision-control)は各イベントがどの決定フィールドを尊重するかを示します。`systemMessage` などのユニバーサル フィールドはほとんどのイベントで機能し、[JSON 出力](#json-output)の表にリストされています。828* **成功**: フックが 0 で終了します。Claude Code はフックが出力した [JSON 出力](#json-output)フィールドを適用し、それらのフィールドがアクションをブロックまたは拒否しない限り、アクションは進行します。
829* **ブロッキング エラー**: フックが 2 で終了します。[ブロック可能なイベント](#exit-code-2-behavior-per-event)では、Claude Code はアクションを停止します。
830* **非ブロッキング エラー**: フックがその他のコードで終了するか、起動しない、無効な JSON を出力するなど、その他の方法で失敗します。アクションは進行し、`PreToolUse` などのイベントではトランスクリプトに `<hook name> hook error` 通知が表示されます。失敗したフックでアクションをブロックしたい場合は、[`onFailure: "block"`](#block-the-action-when-a-hook-fails) を設定してください。
831
832フックが stdout に出力する内容によって結果が変わることがあります。例えば、`PreToolUse` フックが 1 で終了しても、検証に合格する JSON を出力した場合、実行は成功となり、JSON フィールドが何が起こるかを決定します。`PreToolUse` などのイベントでフックの結果を確認するには、stdout に出力した内容を最初の列で、終了コードを上部の行で照合してください。
833
834| stdout | 終了 0 | 終了 2 | その他の終了コード |
835| :- | :- | :- | :- |
836| [スキーマ検証](#json-output)に合格する JSON オブジェクト | 成功。フィールドが適用されます | ブロッキング エラー。Claude Code はフィールドを引き続き読み取りますが、それらでブロックを上書きすることはできません | 成功。Claude Code は終了コードを無視し、フィールドのみが結果を決定します。[`onFailure: "block"`](#block-the-action-when-a-hook-fails) を設定している場合、これは失敗としてカウントされます |
837| [解析できない](#exit-code-0)、またはスキーマ検証に失敗する JSON | 非ブロッキング エラー。通知には解析または検証のメッセージが含まれます | ブロッキング エラー。stderr が理由になります | 非ブロッキング エラー。通知には解析または検証のメッセージが含まれます |
838| [プレーン テキスト](#exit-code-0)、または何もなし | 成功 | ブロッキング エラー。stderr が理由になります | 非ブロッキング エラー。通知には stderr の最初の行が含まれます |
839
840一部のイベントには独自のルールがあります。
841
842* **`WorktreeCreate`**: JSON の内容にかかわらず、0 以外の終了コードで worktree の作成が失敗します。
843* **`WorktreeRemove`**: 0 以外の終了コードは、その後もディレクトリが存在する場合に worktree の削除を失敗させます。
844* **`Stop`、`SubagentStop`、`TaskCompleted`、およびプラグインの `UserPromptSubmit` フック**: フックが stdout に何も出力せずに 2 で終了し、stderr に `No such file or directory` のようにファイルが見つからないことが示されている場合、Claude Code はその実行を非ブロッキング エラーとして扱います。
845* **`Elicitation` と `ElicitationResult`**: Claude Code はフックが 0 で終了した場合に `hookSpecificOutput` を適用し、その他の終了コードでは無視します。
846* **`StopFailure` などフック出力を破棄するイベント**: Claude Code はすべての終了コードで JSON を無視します。ただし、`terminalSequence` のような副作用フィールドは引き続き発火します。
847
848イベントで終了コード 2 が何をするかは[イベントごとの終了コード 2 動作](#exit-code-2-behavior-per-event)を、どの決定フィールドが尊重されるかは[決定制御](#decision-control)を参照してください。
827 849
828<h4 id="exit-code-0">850<h4 id="exit-code-0">
829 終了コード 0851 終了コード 0
835 857
836Claude Code が stdout を [JSON 出力](#json-output)として読み取るかプレーン テキストとして読み取るかは、前後の空白を無視したうえで、その開始と終了の文字によって決まります。858Claude Code が stdout を [JSON 出力](#json-output)として読み取るかプレーン テキストとして読み取るかは、前後の空白を無視したうえで、その開始と終了の文字によって決まります。
837 859
838* **`{` で始まり `}` で終わる**: Claude Code は JSON として解析します。出力が 2 行以上で、各行が単独で JSON として解析でき、どの行もフィールドを設定する [JSON 出力](#json-output)オブジェクトでない場合、Claude Code は出力全体をプレーン テキストとして扱います。それらの行のいずれかがフィールドを設定している場合、出力全体は解析失敗となります（後述）。860* **`{` で始まり `}` で終わる**: Claude Code は JSON として解析します。出力が 2 行以上で、各行が単独で JSON として解析でき、どの行もフィールドを設定する [JSON 出力](#json-output)オブジェクトでない場合、Claude Code は出力全体をプレーン テキストとして扱います。それらの行のいずれかがフィールドを設定している場合、出力全体は解析失敗となります。
839* **`{` で始まるが `}` で終わらない**: Claude Code はプレーン テキストとして扱います。861* **`{` で始まるが `}` で終わらない**: Claude Code はプレーン テキストとして扱います。
840* **その他の文字で始まる**: JSON 配列や引用符で囲まれた JSON 文字列を含め、Claude Code はプレーン テキストとして扱います。862* **その他の文字で始まる**: JSON 配列や引用符で囲まれた JSON 文字列を含め、Claude Code はプレーン テキストとして扱います。
841 863
842標準の決定モデルを使用するイベントでは、終了 0 で解析されたオブジェクトがスキーマ検証に失敗した場合は非ブロッキング エラーとなります。アクションは進行し、トランスクリプトには検証メッセージとともに `<hook name> hook error` 通知が表示されます。2 以外のすべての終了コードでも同じことが起こりますが、[終了 2 は引き続きブロックします](#exit-code-2)。864Claude Code が stdout を JSON として解析しようとして失敗した場合、または解析されたオブジェクトが[スキーマ検証](#json-output)に失敗した場合、実行は[非ブロッキング エラー](#exit-code-output)になります。`<hook name> hook error` 通知には解析または検証のメッセージが含まれます。プレーン テキストの stdout をコンテキストとして追加するイベントでは、Claude Code は解析に失敗した stdout を追加しません。
843
844標準の決定モデルを使用するイベントでは、Claude Code が stdout を JSON として解析しようとして失敗した場合、2 以外のすべての終了コードで非ブロッキング エラーを報告します。トランスクリプトには解析メッセージとともに `<hook name> hook error` 通知が表示されます。プレーン テキストの stdout をコンテキストとして追加するイベントでは、Claude Code はそのテキストを追加しません。v2.1.248 より前は、Claude Code はその stdout をプレーン テキストとして扱っていました。
845 865
846終了 0 のフックからの stderr はデバッグ ログにのみ送られ、トランスクリプトには表示されず、Claude がそれを見ることはありません。自分で読むには、[デバッグ ログ](#debug-hooks)を有効にしてください。`PostToolUse` または `PostToolUseFailure` フックから Claude に警告を表示するには、代わりに終了 2 を使用してください。そうすれば、ツールがすでに実行されていても [Claude は stderr を確認できます](#exit-code-2-behavior-per-event)。866終了 0 のフックからの stderr を Claude が見ることはありません。`PreToolUse` などのイベントで自分で読むには、[デバッグ ログ](#debug-hooks)を有効にしてください。`PostToolUse` または `PostToolUseFailure` フックから Claude に警告を表示するには、代わりに終了 2 を使用してください。そうすれば、ツールがすでに実行されていても [Claude は stderr を確認できます](#exit-code-2-behavior-per-event)。
847 867
848<h4 id="exit-code-2">868<h4 id="exit-code-2">
849 終了コード 2869 終了コード 2
850</h4>870</h4>
851 871
852終了 2 はブロッキング エラーを意味します。[ブロック可能なイベント](#exit-code-2-behavior-per-event)では、JSON を出力するかどうかにかかわらず終了 2 はブロックします。JSON の `permissionDecision` が `"allow"` であっても上書きできません。Claude Code は stdout 上の有効な [JSON 出力](#json-output)を引き続き読み取ります。`Elicitation` と `ElicitationResult` では、終了 2 のフックの `hookSpecificOutput` は無視されます。872アクションをブロックするには、コード 2 で終了します。[ブロック可能なイベント](#exit-code-2-behavior-per-event)では、Claude Code はアクションを停止します。例えば、`PreToolUse` フックはツール呼び出しをブロックし、`UserPromptSubmit` フックはプロンプトを拒否します。
853 873
854ブロッキング メッセージは、JSON がブロッキング決定を行う場合はその理由、それ以外の場合は stderr テキストです。ブロックの効果はイベントによって異なります。`PreToolUse` はツール呼び出しをブロックし、`UserPromptSubmit` はプロンプトを拒否する、などです。[イベントごとの終了コード 2 動作](#exit-code-2-behavior-per-event)にはすべてのイベントの効果がリストされており、各イベントのセクションにはメッセージの送信先が記載されています。874ブロックに伴うメッセージはフックの stderr です。フックがブロッキング決定を行う JSON も出力した場合、Claude Code は代わりにその決定の理由を使用します。
855 875
856[JSON 出力](#json-output)のスキーマ検証に失敗する JSON を出力しながら終了 2 するフックは、引き続きブロックします。Claude Code は stderr をブロッキング理由として使用し、検証の失敗をデバッグ ログに記録します。v2.1.214 より前は、Claude Code はその組み合わせを非ブロッキング エラーとして扱い、アクションは進行していました。876終了 2 は、フックが JSON を出力した場合でもブロックします。
877
878* **スキーマ検証に合格する JSON**: Claude Code は [JSON 出力](#json-output)フィールドを引き続き読み取りますが、それらでブロックを上書きすることはできません。`permissionDecision` が `"allow"` であっても、アクションは通過しません。`Elicitation` と `ElicitationResult` では、終了 2 のフックの `hookSpecificOutput` は無視されます。
879* **スキーマ検証に失敗する JSON**: フックは引き続きブロックします。Claude Code は stderr をブロッキング理由として使用し、検証の失敗をデバッグ ログに記録します。
857 880
858このスクリプトは終了 2 によって `rm` コマンドをブロックし、それ以外のすべてのコマンドは通常の権限フローに任せます。881このスクリプトは終了 2 によって `rm` コマンドをブロックし、それ以外のすべてのコマンドは通常の権限フローに任せます。
859 882
871exit 0 # No decision: the normal permission flow applies894exit 0 # No decision: the normal permission flow applies
872```895```
873 896
897このスクリプトを `Bash` の `PreToolUse` フックとして登録すると、`rm` で始まるコマンドはブロックされ、Claude はイベント名、ツール名、フックのコマンドがプレフィックスとして付いたフックの stderr を、ツールのエラーとして受け取ります。
898
899```text theme={null}
900PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed
901```
902
874<h4 id="other-exit-codes">903<h4 id="other-exit-codes">
875 その他の終了コード904 その他の終了コード
876</h4>905</h4>
877 906
878その他の終了コードは、ほとんどのフック イベントでそれ自体ではブロックしません。何が起こるかは stdout によって異なります。907フックが 0 または 2 以外のコードで終了し、stdout にプレーン テキストを出力するか何も出力しない場合、実行は[非ブロッキング エラー](#exit-code-output)になります。トランスクリプトには、`Failed with non-blocking status code:` とフックの stderr の最初の行を含む `<hook name> hook error` 通知が表示されます。例えば、`Bash` の `PreToolUse` フックが stderr に `something broke` を出力して 1 で終了した場合、`PreToolUse:Bash hook error` 通知には次の行が含まれます。
879 908
880* 標準の決定モデルを使用するイベントで、解析されたオブジェクトがスキーマ検証に合格した場合、Claude Code は終了コードを無視し、JSON のみが結果を決定します。909```text theme={null}
881 * イベントがサポートする各フィールド（`permissionDecision`、`additionalContext`、`updatedInput`、`systemMessage` を含む）が尊重され、フックはエラーとして報告されません。910Failed with non-blocking status code: something broke
882 * [決定制御](#decision-control)にはイベントごとの決定フィールドがリストされています。`systemMessage` などのユニバーサル フィールドは [JSON 出力](#json-output)の表に従います。911```
883* 標準の決定モデルを使用するイベントで、解析されたオブジェクトがスキーマ検証に失敗した場合、[終了 0 の場合](#exit-code-0)と同じ非ブロッキング エラーになります。アクションは進行し、`<hook name> hook error` 通知に検証メッセージが含まれます。
884* Claude Code が [JSON として解析しようとして](#exit-code-0)失敗した stdout の場合、標準の決定モデルを使用するイベントでは、Claude Code は終了 0 の場合と同じ非ブロッキング エラーを報告します。アクションは進行し、通知に解析メッセージが含まれます。
885* Claude Code が[プレーン テキストとして扱う](#exit-code-0) stdout、または空の stdout の場合、ほとんどのフック イベントで非ブロッキング エラーとなります。アクションは進行し、トランスクリプトには `<hook name> hook error` 通知と、その後に `Failed with non-blocking status code:` というプレフィックスが付いた stderr の最初の行が表示されます。完全な stderr を取得するには、[デバッグ ログ](#debug-hooks)を有効にしてください。
886 912
887標準の決定モデルに含まれないイベントは、[イベントごとの表](#exit-code-2-behavior-per-event)の独自の行に従います。`WorktreeCreate` は JSON の内容にかかわらず 0 以外の終了で作成に失敗し、`StopFailure` のようにフック出力を完全に破棄するイベントは、すべての終了コードで JSON を無視します。ただし、`terminalSequence` のような副作用フィールドは引き続き発火します。913最初の行だけでなく完全な stderr を取得するには、[デバッグ ログ](#debug-hooks)を有効にしてください。
888 914
889起動できないフックも同じ非ブロッキングの扱いになります。スクリプト パスが存在しないか実行可能でない場合、シェルは 127 などのコードで終了し、インタープリターのメッセージとともに同じ通知が表示されます（例: `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`）。ほとんどのフック イベントでは、アクションは進行します。ポリシー フックを設定するときは、最初の実行時にこの通知に注意してください。`settings.json` でパスを入力ミスすると、ゲートが気付かないうちに無効になります。915起動できないフックも非ブロッキング エラーになります。シェル形式では、スクリプト パスが存在しないか実行可能でない場合、シェルは 127 などのコードで終了し、通知にはインタープリターのメッセージが含まれます（例: `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`）。ポリシー フックを設定するときは、最初の実行時にこの通知に注意してください。`settings.json` でパスを入力ミスすると、フックは一度も実行されません。代わりにアクションをブロックするには、[`onFailure: "block"`](#block-the-action-when-a-hook-fails) を設定してください。
890 916
891<Warning>917<Warning>
892 ほとんどのフック イベントでは、終了コード 2 がコードのみでブロックする唯一の終了コードです。stdout に有効な JSON がない場合、1 が従来の Unix 失敗コードであっても、Claude Code は終了コード 1 を非ブロッキング エラーとして扱い、アクションを進行させます。フックがポリシーを実施することを目的としている場合は、`exit 2` を使用してください。worktree イベントは異なります。`WorktreeCreate` からの 0 以外の終了コードは worktree の作成を中止し、`WorktreeRemove` からの 0 以外の終了コードは、その後もディレクトリが存在する場合に worktree の削除を失敗させます。918 stdout に有効な JSON がない場合、1 が従来の Unix 失敗コードであっても、Claude Code は終了コード 1 を非ブロッキング エラーとして扱います。フックがポリシーを実施することを目的としている場合は、`exit 2` を使用してください。
893</Warning>919</Warning>
894 920
895<h4 id="timeouts">921<h4 id="timeouts">
900 926
901[`PreModelSwitch`](#premodelswitch) では、タイムアウトでキャンセルされたフックはモデルの切り替えをブロックします。`PreToolUse` では、2 つのフック ファミリーで動作が異なります。927[`PreModelSwitch`](#premodelswitch) では、タイムアウトでキャンセルされたフックはモデルの切り替えをブロックします。`PreToolUse` では、2 つのフック ファミリーで動作が異なります。
902 928
903* タイムアウトした `command`、`http`、または `mcp_tool` フックはツール呼び出しをブロックしません。呼び出しは通常の[権限フロー](/docs/ja/permissions)を通じて続行されるため、停止したフックがゲートとして機能することを当てにしないでください。929* タイムアウトした `command`、`http`、または `mcp_tool` フックはツール呼び出しをブロックしません。呼び出しは通常の[権限フロー](/docs/ja/permissions)を通じて続行されるため、停止したフックがゲートとして機能することを当てにしないでください。`command` または `http` フックがタイムアウトしたときに呼び出しをブロックするには、[`onFailure: "block"`](#block-the-action-when-a-hook-fails) を設定してください。
904* タイムアウトを超えた [Agent SDK コールバック フック](/docs/ja/agent-sdk/hooks)は[ツール呼び出しをブロックします](#pretooluse)。930* タイムアウトを超えた [Agent SDK コールバック フック](/docs/ja/agent-sdk/hooks)は[ツール呼び出しをブロックします](#pretooluse)。
905 931
932<h4 id="block-the-action-when-a-hook-fails">
933 フックが失敗したときにアクションをブロックする
934</h4>
935
936ほとんどのイベントでは、フックが失敗またはタイムアウトしても Claude Code はアクションを実行するため、パスが間違っていたりスクリプトがクラッシュしたりするポリシー フックはすべてを通過させてしまいます。代わりにアクションをブロックするには、`command` または `http` フックに `"onFailure": "block"` を設定します。デフォルト値は `"continue"` です。Claude Code v2.1.295 以降が必要です。
937
938`.claude/settings.json` 内のこの `PreToolUse` フックは、各 Bash コマンドの前にプロジェクト スクリプトを実行し、スクリプトが失敗した場合はコマンドをブロックします。
939
940```json theme={null}
941{
942 "hooks": {
943 "PreToolUse": [
944 {
945 "matcher": "Bash",
946 "hooks": [
947 {
948 "type": "command",
949 "command": "node",
950 "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
951 "onFailure": "block"
952 }
953 ]
954 }
955 ]
956 }
957}
958```
959
960試すには、`check-command.js` を存在しない状態のままにして、Claude に `ls` などの Bash コマンドの実行を依頼します。Claude Code は呼び出しをブロックし、エラーには `failed; blocking because onFailure is "block"` と、それに続く node 自身のエラー出力が含まれます（ここでは 1 行に切り詰めています）。
961
962```text theme={null}
963PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
964Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'
965```
966
967タイムアウト後は、メッセージに `failed` ではなく `timed out` と表示されます。`onFailure` が設定されていない場合、同じスクリプトの欠落は非ブロッキング エラーとなり、`ls` は実行されます。
968
969次のそれぞれが失敗としてカウントされます。
970
971* **起動できない**: コマンド フックが起動に失敗する（例えば、スクリプトや実行可能ファイルが存在しないため）
972* **0 または 2 以外の終了コード**: `permissionDecision: "allow"` のようにアクションを許可する JSON を出力した場合でも、コマンド フックでは失敗としてカウントされます。JSON の決定を返すには、0 で終了してください
973* **HTTP エラー**: HTTP フックの接続が失敗するか、レスポンスのステータスが 2xx ではない
974* **タイムアウト**: フックが [`timeout`](#common-fields) に達する
975* **無効な出力**: JSON 出力が[解析できない](#exit-code-0)か、[スキーマ検証](#json-output)に失敗する。HTTP フックの場合、空でも JSON オブジェクトでもない 2xx 本体も該当します。コマンド フックからのプレーン テキストの stdout は失敗ではありません
976
977`"block"` を設定すると、失敗は[そのイベントでの終了コード 2](#exit-code-2-behavior-per-event) と同じ動作をします。ただし `PermissionRequest` は例外で、リクエストを拒否します。例えば、`PreToolUse` の失敗はツール呼び出しをブロックし、`UserPromptSubmit` の失敗はプロンプトをブロックします。
978
979このフィールドは次のフックには効果がありません。
980
981* **`Stop`、`SubagentStop`、`TaskCompleted`、`TeammateIdle` フック**: これらのイベントでの終了コード 2 は Claude を作業に戻しますが、Claude は実行されないフックを修復できません
982* **バックグラウンド コマンド フック**: [`async` または `asyncRewake`](#run-hooks-in-the-background) を設定したコマンド フック
983
906<h4 id="exit-code-2-behavior-per-event">984<h4 id="exit-code-2-behavior-per-event">
907 イベントごとの終了コード 2 動作985 イベントごとの終了コード 2 動作
908</h4>986</h4>
960* **接続失敗**: 非ブロッキング エラー、実行は続行1038* **接続失敗**: 非ブロッキング エラー、実行は続行
961* **タイムアウト**: [タイムアウト](#timeouts)で説明されているとおり、フックはキャンセルされます1039* **タイムアウト**: [タイムアウト](#timeouts)で説明されているとおり、フックはキャンセルされます
962 1040
963コマンド フックとは異なり、HTTP フックはステータス コードのみでブロッキング エラーを通知できません。ツール呼び出しをブロックまたは権限を拒否するには、適切な決定フィールドを含む JSON 本体を持つ 2xx レスポンスを返します。1041HTTP フックはステータス コードのみでブロッキング エラーを通知できません。2xx 以外のステータスや接続の失敗は[非ブロッキング エラー](#exit-code-output)です。ツール呼び出しをブロックまたは権限を拒否するには、適切な決定フィールドを含む JSON 本体を持つ 2xx レスポンスを返します。リクエストが失敗した場合や 2xx 以外のステータスを返した場合にアクションをブロックするには、[`onFailure: "block"`](#block-the-action-when-a-hook-fails) を設定してください。
964 1042
965<h3 id="json-output">1043<h3 id="json-output">
966 JSON 出力1044 JSON 出力
1237 SessionStart の判定制御1315 SessionStart の判定制御
1238</h4>1316</h4>
1239 1317
1240Claude Code は、[プレーンテキストとして扱う](#exit-code-0)標準出力を Claude のコンテキストに追加します。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、以下のイベント固有のフィールドを返すことができます。1318SessionStart フックは、Claude へのコンテキストの追加、最初のユーザーメッセージの指定、セッションタイトルの設定、ファイルの監視、スキルの再読み込みを行えます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、それぞれに対応するフィールドを返してください。
1241 1319
1242| フィールド | 説明 |1320| フィールド | 説明 |
1243| :- | :- |1321| :- | :- |
1244| `additionalContext` | 会話の開始時、最初のプロンプトの前に Claude のコンテキストに追加される文字列。テキストがどのように渡されるか、何を含めるべきかについては [Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |1322| `additionalContext` | 会話の開始時、最初のプロンプトの前に Claude のコンテキストに追加される文字列。テキストがどのように渡されるか、何を含めるべきかについては [Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1245| `initialUserMessage` | セッションの最初のユーザーメッセージとして使用される文字列。`-p` フラグを使用した[非対話モード](/docs/ja/headless)で適用され、プロンプトが指定されていなくても最初のターンになります。プロンプトが指定されている場合は、その次のターンとして続きます。既存のターンに付加される `additionalContext` とは異なり、これはターンを作成します |1323| `initialUserMessage` | `-p` フラグを使用した[非対話モード](/docs/ja/headless)で、セッションの最初のユーザーメッセージとして使用される文字列。プロンプトを渡さなくても最初のターンになります。プロンプトを渡した場合は、次のターンとして続きます |
1246| `sessionTitle` | セッションタイトルを設定します。`/rename` と同じ効果があります。起動フォルダ、git ブランチ、worktree 名からセッションに自動で名前を付ける場合に使用します。`source` が `"startup"`、`"resume"`、`"fork"` の場合に適用され、`"clear"` と `"compact"` では無視されます |1324| `sessionTitle` | セッションタイトルを設定します。`/rename` と同じ効果があります。`source` が `"startup"`、`"resume"`、または `"fork"` の場合に適用されます |
1247| `watchPaths` | このセッション中に [FileChanged](#filechanged) イベントを監視する絶対パスの配列 |1325| `watchPaths` | このセッション中に [FileChanged](#filechanged) イベントを監視する絶対パスの配列 |
1248| `reloadSkills` | ブール値。`true` の場合、Claude Code は SessionStart フックの完了後に[スキル](/docs/ja/skills)とコマンドのディレクトリを再スキャンするため、フックがインストールしたスキルは同じセッションの最初のプロンプトから利用できます |1326| `reloadSkills` | ブール値。`true` の場合、Claude Code は SessionStart フックの完了後に[スキル](/docs/ja/skills)とコマンドのディレクトリを再スキャンします。[フックがインストールしたスキルを再読み込みする](#reload-skills-that-a-hook-installs)を参照してください |
1327
1328次の出力はコンテキストを追加し、セッションに名前を付けます。
1249 1329
1250```json theme={null}1330```json theme={null}
1251{1331{
1257}1337}
1258```1338```
1259 1339
1260このイベントでは通常の標準出力がすでに Claude に届くため、コンテキストを読み込むだけのフックは JSON を組み立てずに直接標準出力に出力できます。コンテキストを `sessionTitle` などの他のフィールドと組み合わせる必要がある場合は JSON 形式を使用してください。1340Claude Code は SessionStart フックの[プレーンテキストの stdout](#exit-code-0) を Claude のコンテキストに追加するため、コンテキストを追加するだけのフックは JSON を組み立てずにそのまま出力できます。
1341
1342プラグインの SessionStart フックが `initialUserMessage` または `sessionTitle` を指定する場合は、セッションの開始前にプラグインをインストールしてください。SessionStart フックの実行後にインストールが完了したプラグインからのこれら 2 つのフィールドは、Claude Code によって無視されます。
1343
1344<h4 id="reload-skills-that-a-hook-installs">
1345 フックがインストールしたスキルを再読み込みする
1346</h4>
1347
1348SessionStart フックがインストールしたスキルを同じセッションで利用できるようにするには、`reloadSkills` を返します。スキルの検出は通常 SessionStart フックの完了前に実行されるため、これがないと、フックが `~/.claude/skills/` や `.claude/skills/` に書き込んだファイルが最初のプロンプトの実行時に見つからない場合があります。
1261 1349
1262SessionStart フックがスキルをインストールまたは更新する場合は `reloadSkills` を使用してください。スキルの検出は通常 SessionStart フックの完了前に実行されるため、フックが `~/.claude/skills/` や `.claude/skills/` に書き込んだファイルは、そうしないと次のセッションでしか表示されません。次の例では、共有スキルリポジトリを同期し、再スキャンを要求します。1350次の例は、共有スキルのリポジトリを同期し、再スキャンを要求します。
1263 1351
1264```bash theme={null}1352```bash theme={null}
1265#!/bin/bash1353#!/bin/bash
1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1358echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1271```1359```
1272 1360
1273リポジトリの URL はプレースホルダーです。独自のスキルリポジトリに置き換えてください。プレースホルダーのままではクローンが失敗し、標準エラー出力に `fatal:` メッセージが出力されます。終了コード 0 で終了した SessionStart フックの標準エラー出力は情報提供のみを目的としているため、`reloadSkills` の要求は引き続き適用されます。1361リポジトリの URL はプレースホルダーです。独自のスキルリポジトリに置き換えてください。
1274 1362
1275<h4 id="persist-environment-variables">1363<h4 id="persist-environment-variables">
1276 環境変数を永続化する1364 環境変数を永続化する
1419 1507
1420`UserPromptSubmit` フックのデフォルトのタイムアウトは、`command`、`http`、`mcp_tool` の各タイプで 30 秒です。これは、他のほとんどのイベントでのこれらのタイプのデフォルトである 600 秒より短くなっています。このフックはすべてのプロンプトの前に実行され、完了するまでモデルの処理をブロックするため、フックが停止するとセッションも停止します。フックにさらに時間が必要な場合は、フックエントリの `timeout` フィールドを設定してください。1508`UserPromptSubmit` フックのデフォルトのタイムアウトは、`command`、`http`、`mcp_tool` の各タイプで 30 秒です。これは、他のほとんどのイベントでのこれらのタイプのデフォルトである 600 秒より短くなっています。このフックはすべてのプロンプトの前に実行され、完了するまでモデルの処理をブロックするため、フックが停止するとセッションも停止します。フックにさらに時間が必要な場合は、フックエントリの `timeout` フィールドを設定してください。
1421 1509
1422[`async: true`](#run-hooks-in-the-background) で実行するコマンドフックを除き、タイムアウトに達した `UserPromptSubmit` のコマンド、HTTP、または MCP ツールフックはキャンセルされ、その出力（`additionalContext` を含む）は破棄されます。プロンプトはそのコンテキストなしで Claude に届きます。トランスクリプトには、フック名、発生したタイムアウト、出力が破棄されたことを示す通知が表示されます。1510[`async: true`](#run-hooks-in-the-background) で実行するコマンドフックを除き、タイムアウトに達した `UserPromptSubmit` のコマンド、HTTP、または MCP ツールフックはキャンセルされ、その出力は `additionalContext` を含めて破棄されます。プロンプトはそのコンテキストなしで Claude に届きます。代わりにプロンプトをブロックするには、コマンドフックまたは HTTP フックに [`onFailure: "block"`](#block-the-action-when-a-hook-fails) を設定してください。トランスクリプトには、フックの名前、発生したタイムアウト、出力が破棄されたことを示す通知が表示されます。
1423 1511
1424`UserPromptSubmit` の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)がタイムアウトに達すると、フック名とタイムアウトを示すメッセージとともにプロンプトがブロックされます。これは、そこでのコールバックが、フェイルオープンしてはならないポリシーゲートとして機能している可能性があるためです。セッションは続行されます。v2.1.208 より前は、このイベントでのコールバックのタイムアウトは実行エラーでターンを終了していました。1512`UserPromptSubmit` の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)がタイムアウトに達すると、フック名とタイムアウトを示すメッセージとともにプロンプトがブロックされます。これは、そこでのコールバックが、フェイルオープンしてはならないポリシーゲートとして機能している可能性があるためです。セッションは続行されます。v2.1.208 より前は、このイベントでのコールバックのタイムアウトは実行エラーでターンを終了していました。
1425 1513
1860| :- | :- | :- | :- |1948| :- | :- | :- | :- |
1861| `url` | string | `"https://example.com/api"` | コンテンツを取得する URL |1949| `url` | string | `"https://example.com/api"` | コンテンツを取得する URL |
1862| `prompt` | string | `"Extract the API endpoints"` | 取得したコンテンツに対して実行するプロンプト |1950| `prompt` | string | `"Extract the API endpoints"` | 取得したコンテンツに対して実行するプロンプト |
1951| `offset` | number | `100000` | ページの先頭からスキップする文字数（オプション）。Claude は長いページの続きを読むためにこれを設定します。Claude Code v2.1.290 以降が必要です |
1863 1952
1864<h5 id="websearch">1953<h5 id="websearch">
1865 WebSearch1954 WebSearch
2112| `message` | `"deny"` の場合のみ：権限が拒否された理由を Claude に伝えます |2201| `message` | `"deny"` の場合のみ：権限が拒否された理由を Claude に伝えます |
2113| `interrupt` | `"deny"` の場合のみ：`true` の場合、Claude を停止します |2202| `interrupt` | `"deny"` の場合のみ：`true` の場合、Claude を停止します |
2114 2203
2115`decision` オブジェクトなしで終了コード 2 で終了するフックは権限フローを変更せず、その標準エラー出力は破棄されます。リクエストを許可または拒否できるのは `decision` オブジェクトだけです。2204`decision` オブジェクトなしで終了コード 2 で終了するフックは、権限フローを変更せず、その stderr は破棄されます。リクエストを許可または拒否するには、`decision` オブジェクトを返してください。
2116 2205
2117```json theme={null}2206```json theme={null}
2118{2207{
2678 TaskCreated の決定制御2767 TaskCreated の決定制御
2679</h4>2768</h4>
2680 2769
2681TaskCreated フックは 2 つの方法で作成をブロックできます。いずれの場合も、Claude Code はタスクを削除し、メッセージをツールのエラーとして Claude に返します。Claude Code はこのイベントからの `continue: false` を無視し、Claude は作業を続けます。2770TaskCreated フックは、終了コード 2 または JSON の判定によって作成をブロックできます。いずれの場合も、Claude Code はタスクを削除し、メッセージをツールのエラーとして Claude に返します。Claude Code はこのイベントからの `continue: false` を無視し、Claude は作業を続けます。
2682 2771
2683* **終了コード 2**: Claude Code は stderr のテキストをメッセージとして返します。2772* **終了コード 2**: Claude Code は stderr のテキストをメッセージとして返します。
2684* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code は `reason` をメッセージとして返します。2773* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code は `reason` をメッセージとして返します。
3561 3650
3562Claude Code は、決定に関係なく、フックが返した `systemMessage` をユーザーに表示します。そのため、コストを報告するフックは `{"systemMessage": "..."}` を返して 0 で終了できます。3651Claude Code は、決定に関係なく、フックが返した `systemMessage` をユーザーに表示します。そのため、コストを報告するフックは `{"systemMessage": "..."}` を返して 0 で終了できます。
3563 3652
3564タイムアウトまでに応答しない PreModelSwitch フックは、切り替えをブロックします。これに対して [PreToolUse](#timeouts) では、タイムアウトしたコマンドフックはツール呼び出しを続行させます。このイベントのデフォルトのタイムアウトは 30 秒です。`PreModelSwitch` は `command`、`http`、`mcp_tool` フックのみを実行するため、`prompt` と `agent` のデフォルトは適用されません。3653タイムアウトまでに応答しない PreModelSwitch フックは、切り替えをブロックします。他のイベントでのタイムアウトの動作については、[タイムアウト](#timeouts)を参照してください。このイベントのデフォルトのタイムアウトは 30 秒です。`PreModelSwitch` は `command`、`http`、`mcp_tool` フックのみを実行するため、`prompt` と `agent` のデフォルトは適用されません。
3565 3654
35660 または 2 以外のコードで終了し、JSON の決定を出力しないフックはブロックしません。[その他の終了コード](#other-exit-codes)で説明しているとおり、Claude Code はその stderr を表示して切り替えを適用します。36550 または 2 以外のコードで終了し、JSON の決定を出力しないフックは、[その他の終了コード](#other-exit-codes)で説明されているように、非ブロッキングエラーになります。
3567 3656
3568<h3 id="postmodelswitch">3657<h3 id="postmodelswitch">
3569 PostModelSwitch3658 PostModelSwitch
4278非同期フックは同期フックと比べていくつかの制約があります。4367非同期フックは同期フックと比べていくつかの制約があります。
4279 4368
4280* フック出力は次の会話ターンで配信されます。セッションがアイドル状態の場合、レスポンスは次のユーザー操作まで待機します。例外: `asyncRewake` フックが終了コード 2 で終了すると、セッションがアイドル状態でも Claude を直ちに起動します。4369* フック出力は次の会話ターンで配信されます。セッションがアイドル状態の場合、レスポンスは次のユーザー操作まで待機します。例外: `asyncRewake` フックが終了コード 2 で終了すると、セッションがアイドル状態でも Claude を直ちに起動します。
4281* 各実行は個別のバックグラウンド プロセスを作成します。同じ非同期フックの複数の発火全体で重複排除はありません。4370* 各実行は個別のバックグラウンド プロセスを作成します。
4282 4371
4283<h2 id="security-considerations">4372<h2 id="security-considerations">
4284 セキュリティに関する考慮事項4373 セキュリティに関する考慮事項
