938| `PostCompact` | いいえ | ユーザーのみに stderr を表示 |938| `PostCompact` | いいえ | ユーザーのみに stderr を表示 |
939| `PreModelSwitch` | はい | モデルの切り替えをブロックし、ユーザーに stderr を表示 |939| `PreModelSwitch` | はい | モデルの切り替えをブロックし、ユーザーに stderr を表示 |
940| `PostModelSwitch` | いいえ | ユーザーのみに stderr を表示(モデルはすでに切り替え済み) |940| `PostModelSwitch` | いいえ | ユーザーのみに stderr を表示(モデルはすでに切り替え済み) |
941| `Elicitation` | はい | elicitation を拒否 |941| `Elicitation` | はい | リクエストを拒否し、ダイアログは表示されない |
942| `ElicitationResult` | はい | レスポンスをブロック(アクションが decline になる) |942| `ElicitationResult` | はい | レスポンスをブロック(アクションが decline になる) |
943| `WorktreeCreate` | はい | 0 以外の終了コードで worktree 作成が失敗 |943| `WorktreeCreate` | はい | 0 以外の終了コードで worktree 作成が失敗 |
944| `WorktreeRemove` | はい | 0 以外の終了コードは、その後もディレクトリが存在する場合に worktree の削除を失敗させる。ディレクトリがどうなるかについては [WorktreeRemove](#worktreeremove) を参照 |944| `WorktreeRemove` | はい | 0 以外の終了コードは、その後もディレクトリが存在する場合に worktree の削除を失敗させる。ディレクトリがどうなるかについては [WorktreeRemove](#worktreeremove) を参照 |
1095| PermissionDenied | `hookSpecificOutput` | `retry: true` はモデルが拒否されたツール呼び出しを再試行できることを伝えます。Claude Code は[判定のない拒否](#permissiondenied-decision-control)ではこれを無視します |1095| PermissionDenied | `hookSpecificOutput` | `retry: true` はモデルが拒否されたツール呼び出しを再試行できることを伝えます。Claude Code は[判定のない拒否](#permissiondenied-decision-control)ではこれを無視します |
1096| WorktreeCreate | パス戻り値 | コマンド フックは stdout にパスを出力します。HTTP フックは `hookSpecificOutput.worktreePath` を返します。フック失敗またはパス欠落で作成が失敗 |1096| WorktreeCreate | パス戻り値 | コマンド フックは stdout にパスを出力します。HTTP フックは `hookSpecificOutput.worktreePath` を返します。フック失敗またはパス欠落で作成が失敗 |
1097| WorktreeRemove | 終了コード | 0 以外の終了コードは、その後もディレクトリが存在する場合に削除を失敗させます。JSON 出力は破棄されます |1097| WorktreeRemove | 終了コード | 0 以外の終了コードは、その後もディレクトリが存在する場合に削除を失敗させます。JSON 出力は破棄されます |
1098| Elicitation | `hookSpecificOutput` | `action`(accept/decline/cancel)、`content`(accept の場合のフォーム フィールド値) |1098| Elicitation、ElicitationResult | `hookSpecificOutput` またはトップレベル `decision` | `action`(accept/decline/cancel)、`content`(フォーム フィールド値)。`decision: "block"` も[拒否](#other-ways-to-decline-an-elicitation)します |
1099| ElicitationResult | `hookSpecificOutput` | `action`(accept/decline/cancel)、`content`(フォーム フィールド値を上書き) |
1100| MessageDisplay | `hookSpecificOutput` | `displayContent` は画面に表示されるテキストを置き換えます。表示のみ: トランスクリプトと Claude が見るものは元のままです |1099| MessageDisplay | `hookSpecificOutput` | `displayContent` は画面に表示されるテキストを置き換えます。表示のみ: トランスクリプトと Claude が見るものは元のままです |
1101| SessionStart、SubagentStart、PostModelSwitch | コンテキストのみ | `hookSpecificOutput.additionalContext` は Claude 用にコンテキストを追加します。SessionStart は [`initialUserMessage`、`watchPaths`、`sessionTitle`、および `reloadSkills`](#sessionstart-decision-control) も受け入れます。ブロッキングまたは決定制御なし |1100| SessionStart、SubagentStart、PostModelSwitch | コンテキストのみ | `hookSpecificOutput.additionalContext` は Claude 用にコンテキストを追加します。SessionStart は [`initialUserMessage`、`watchPaths`、`sessionTitle`、および `reloadSkills`](#sessionstart-decision-control) も受け入れます。ブロッキングまたは決定制御なし |
1102| Setup、Notification、SessionEnd、PostCompact、InstructionsLoaded、StopFailure、CwdChanged、DirectoryAdded、FileChanged | なし | 決定制御なし。ログやクリーンアップなどの副作用に使用 |1101| Setup、Notification、SessionEnd、PostCompact、InstructionsLoaded、StopFailure、CwdChanged、DirectoryAdded、FileChanged | なし | 決定制御なし。ログやクリーンアップなどの副作用に使用 |
1163 フックイベント1162 フックイベント
1164</h2>1163</h2>
1165 1164
1166各イベントは、フックを実行できる Claude Code のライフサイクル上のポイントに対応しています。以下のセクションはライフサイクルに沿った順序で並んでおり、セッションのセットアップからエージェント型ループを経てセッション終了までを扱います。各セクションでは、イベントが発火するタイミング、サポートする matcher、受け取る JSON 入力、出力を通じて動作を制御する方法を説明します。1165各イベントは、Claude Code のライフサイクルにおいてフックを実行できるポイントに対応しています。以下のセクションはライフサイクルの順序に沿って並んでおり、セッションのセットアップからエージェント型ループを経てセッション終了までを扱います。各セクションでは、イベントが発火するタイミング、サポートされる matcher、受け取る JSON 入力、出力による動作の制御方法を説明します。
1167 1166
1168<h3 id="sessionstart">1167<h3 id="sessionstart">
1169 SessionStart1168 SessionStart
1170</h3>1169</h3>
1171 1170
1172Claude Code が新しいセッションを開始するとき、または既存のセッションを再開するときに実行されます。既存の issue やコードベースへの最近の変更といった開発コンテキストの読み込みや、環境変数の設定に便利です。スクリプトを必要としない静的なコンテキストには、代わりに [CLAUDE.md](/docs/ja/memory) を使用してください。1171Claude Code が新しいセッションを開始したとき、または既存のセッションを再開したときに実行されます。既存の issue やコードベースへの最近の変更などの開発コンテキストを読み込んだり、環境変数を設定したりするのに便利です。スクリプトを必要としない静的なコンテキストには、代わりに [CLAUDE.md](/docs/ja/memory) を使用してください。
1173 1172
1174SessionStart はすべてのセッションで実行されるため、これらのフックは高速に保ってください。サポートされるのは `type: "command"` と `type: "mcp_tool"` のフックのみです。`mcp_tool` フックが実行されるタイミングについては、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)を参照してください。1173SessionStart はすべてのセッションで実行されるため、これらのフックは高速に保ってください。サポートされるのは `type: "command"` と `type: "mcp_tool"` のフックのみです。`mcp_tool` フックが実行されるタイミングについては、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)を参照してください。
1175 1174
1181| `resume` | `--resume`、`--continue`、または `/resume` |1180| `resume` | `--resume`、`--continue`、または `/resume` |
1182| `clear` | `/clear` |1181| `clear` | `/clear` |
1183| `compact` | 自動または手動のコンテキスト圧縮 |1182| `compact` | 自動または手動のコンテキスト圧縮 |
1184| `fork` | 既存のセッションからフォークされた新しいセッション。`--resume` または `--continue` と組み合わせた `--fork-session`、`/fork` によるバックグラウンドコピー、`/branch`、または[バックグラウンドに移動](/docs/ja/agent-view#from-inside-a-session)した会話が該当します |1183| `fork` | 既存のセッションからフォークされた新しいセッション:`--resume` または `--continue` と組み合わせた `--fork-session`、`/fork` によるバックグラウンドコピー、`/branch`、または[バックグラウンドに移動](/docs/ja/agent-view#from-inside-a-session)した会話 |
1185 1184
1186v2.1.214 より前は、フォークされたセッションはソースとして `"resume"` を報告していました。1185v2.1.214 より前は、フォークされたセッションはソースとして `"resume"` を報告していました。
1187 1186
1188対話セッションを開始したとき、起動時に `--continue` または `--resume` で会話を再開したとき、または `/clear` を実行したときは、SessionStart フックがバックグラウンドで実行されます。すぐに入力を始めることができ、再開した会話はフックを待たずに表示されます。ただし、フックのコンテキストが Claude に届くように、Claude の最初の応答はフックの完了を待ちます。1187対話セッションを開始したとき、起動時に `--continue` や `--resume` で会話を再開したとき、または `/clear` を実行したとき、SessionStart フックはバックグラウンドで実行されます。すぐに入力を始めることができ、再開した会話はフックを待たずに表示されます。ただし、Claude の最初の応答はフックの完了を待つため、フックのコンテキストは Claude に届きます。
1189 1188
1190セッション内で `/resume` を使って会話を切り替えた場合は、切り替え自体がフックの完了を待ちます。バックグラウンドのフックがまだ実行中に `/clear` を実行したり別の会話に切り替えたりすると、フックが返す内容はセッションに一切適用されません。1189セッション内で `/resume` を使って会話を切り替える場合は、代わりに切り替えがフックの完了を待ちます。バックグラウンドのフックがまだ実行中に `/clear` を実行するか別の会話に切り替えた場合、フックが返す内容はセッションに一切適用されません。
1191 1190
1192起動時にも同じ待機が適用され、再開したセッションも含まれます。SessionStart フックの実行中に送信したプロンプトは、フックが完了するまで Claude に届きません。1191再開したセッションを含め、起動時にも同じ待機が適用されます。SessionStart フックがまだ実行中に送信したプロンプトは、フックが完了するまで Claude に届きません。
1193 1192
1194いずれの待機中も、`Esc` を押すとプロンプトを送信せずに入力欄に戻すことができます。フックは実行を続けます。1193いずれの待機中も、`Esc` を押すとプロンプトを送信せずに入力欄に戻すことができます。フックは実行を続けます。
1195 1194
1201 1200
1202| フィールド | 説明 |1201| フィールド | 説明 |
1203| :- | :- |1202| :- | :- |
1204| `source` | セッションの開始方法。新しいセッションでは `"startup"`、再開されたセッションでは `"resume"`、`/clear` の後では `"clear"`、コンテキスト圧縮の後では `"compact"`、既存のセッションからフォークされた新しいセッションでは `"fork"` |1203| `source` | セッションの開始方法:新しいセッションの場合は `"startup"`、再開したセッションの場合は `"resume"`、`/clear` の後は `"clear"`、コンテキスト圧縮の後は `"compact"`、既存のセッションからフォークされた新しいセッションの場合は `"fork"` |
1205| `model` | アクティブなモデルの識別子。たとえば `/clear` の後や、会話の復旧によってセッションが復元された場合など、省略されることがあるため、読み取る前にフィールドの有無を確認してください |1204| `model` | アクティブなモデルの識別子。`/clear` の後や、会話の復旧によってセッションが復元された場合などに省略されることがあるため、読み取る前にフィールドの有無を確認してください |
1206| `agent_type` | エージェント名。`claude --agent <name>` で Claude Code を起動した場合に含まれます |1205| `agent_type` | エージェント名。`claude --agent <name>` で Claude Code を起動した場合に存在します |
1207| `session_title` | セッションのカスタムタイトル。`--name`、`/rename`、フックの `sessionTitle` 出力、Agent SDK の `renameSession()` などで設定されている場合に含まれます。`sessionTitle` を出力するフックは、既存のカスタムタイトルを上書きしないように、まずこのフィールドを確認できます |1206| `session_title` | セッションのカスタムタイトル。`--name`、`/rename`、フックの `sessionTitle` 出力、Agent SDK の `renameSession()` などで設定されている場合に存在します。`sessionTitle` を出力するフックは、まずこのフィールドを確認することで既存のカスタムタイトルの上書きを回避できます |
1208 1207
1209名前を付けていないセッションにも[生成されたタイトル](/docs/ja/sessions#name-your-sessions)が付いている場合があります。このタイトルはカスタムタイトルではないため、`session_title` には含まれません。1208名前を付けていないセッションにも[生成されたタイトル](/docs/ja/sessions#name-your-sessions)が付いている場合があります。このタイトルはカスタムタイトルではないため、`session_title` には表示されません。
1210 1209
1211`source` が `"resume"` または `"fork"` で、トランスクリプトに Claude の応答が少なくとも 1 つ含まれている場合、SessionStart フックは以下の 4 つのフィールドも受け取ります。フックはこれらを使用して、古い会話を再開するコストを最初のリクエストの前に報告できます。たとえば [`systemMessage`](#json-output) で報告します。これらのフィールドには Claude Code v2.1.251 以降が必要です。1210`source` が `"resume"` または `"fork"` で、トランスクリプトに Claude からの応答が少なくとも 1 つ含まれている場合、SessionStart フックは以下の 4 つのフィールドも受け取ります。フックはこれらを使って、古い会話を再開するコストを最初のリクエストの前に報告できます。たとえば [`systemMessage`](#json-output) で報告できます。これらのフィールドには Claude Code v2.1.251 以降が必要です。
1212 1211
1213| フィールド | 説明 |1212| フィールド | 説明 |
1214| :- | :- |1213| :- | :- |
1215| `seconds_since_last_response` | 再開されたトランスクリプト内の最後の応答からの経過時間(実時間の秒数) |1214| `seconds_since_last_response` | 再開したトランスクリプト内の最後の応答からの経過時間(実時間の秒数) |
1216| `context_tokens` | 再開されたセッションの最初のリクエストがプロンプトとして再送信するトークン数 |1215| `context_tokens` | 再開したセッションの最初のリクエストがプロンプトとして再送信するトークン数 |
1217| `prompt_cache_likely_expired` | 最後の応答がセッションの[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime)より古い場合、またはその後のコンテキスト圧縮によってキャッシュされた会話が置き換えられた場合に `true` |1216| `prompt_cache_likely_expired` | 最後の応答がセッションの[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime)より古い場合、またはその後のコンテキスト圧縮によってキャッシュされた会話が置き換えられた場合に `true` |
1218| `estimated_cache_write_usd` | セッションのモデルで `context_tokens` をプロンプトキャッシュに書き込む推定コスト(米ドル)。応答は含みません |1217| `estimated_cache_write_usd` | セッションのモデルで `context_tokens` をプロンプトキャッシュに書き込む推定コスト(米ドル、応答を除く) |
1219 1218
1220次の例は、最後の応答から 90 分後に再開されたセッションの入力を示しています。1219次の例は、最後の応答から 90 分後に再開したセッションの入力を示しています。
1221 1220
1222```json theme={null}1221```json theme={null}
1223{1222{
1238 SessionStart の判定制御1237 SessionStart の判定制御
1239</h4>1238</h4>
1240 1239
1241Claude Code は、[プレーンテキストとして扱う](#exit-code-0) stdout を Claude のコンテキストに追加します。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、以下のイベント固有のフィールドを返すことができます。1240Claude Code は、[プレーンテキストとして扱う](#exit-code-0)標準出力を Claude のコンテキストに追加します。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、以下のイベント固有のフィールドを返すことができます。
1242 1241
1243| フィールド | 説明 |1242| フィールド | 説明 |
1244| :- | :- |1243| :- | :- |
1245| `additionalContext` | 会話の開始時、最初のプロンプトの前に Claude のコンテキストに追加される文字列。テキストの届け方と記述すべき内容については、[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |1244| `additionalContext` | 会話の開始時、最初のプロンプトの前に Claude のコンテキストに追加される文字列。テキストがどのように渡されるか、何を含めるべきかについては [Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1246| `initialUserMessage` | セッションの最初のユーザーメッセージとして使用される文字列。`-p` フラグを使った[非対話モード](/docs/ja/headless)で適用され、プロンプトが指定されていなくても最初のターンになります。プロンプトが指定されている場合、それは次のターンとして続きます。既存のターンに付加される `additionalContext` とは異なり、これはターンそのものを作成します |1245| `initialUserMessage` | セッションの最初のユーザーメッセージとして使用される文字列。`-p` フラグを使用した[非対話モード](/docs/ja/headless)で適用され、プロンプトが指定されていなくても最初のターンになります。プロンプトが指定されている場合は、その次のターンとして続きます。既存のターンに付加される `additionalContext` とは異なり、これはターンを作成します |
1247| `sessionTitle` | セッションのタイトルを設定します。効果は `/rename` と同じです。起動フォルダ、git ブランチ、worktree 名からセッションに自動的に名前を付けるのに使用します。`source` が `"startup"`、`"resume"`、`"fork"` の場合に適用され、`"clear"` と `"compact"` では無視されます |1246| `sessionTitle` | セッションタイトルを設定します。`/rename` と同じ効果があります。起動フォルダ、git ブランチ、worktree 名からセッションに自動で名前を付ける場合に使用します。`source` が `"startup"`、`"resume"`、`"fork"` の場合に適用され、`"clear"` と `"compact"` では無視されます |
1248| `watchPaths` | このセッション中に [FileChanged](#filechanged) イベントを監視する絶対パスの配列 |1247| `watchPaths` | このセッション中に [FileChanged](#filechanged) イベントを監視する絶対パスの配列 |
1249| `reloadSkills` | ブール値。`true` の場合、Claude Code は SessionStart フックの完了後に[スキル](/docs/ja/skills)とコマンドのディレクトリを再スキャンするため、フックがインストールしたスキルを同じセッションの最初のプロンプトから利用できます |1248| `reloadSkills` | ブール値。`true` の場合、Claude Code は SessionStart フックの完了後に[スキル](/docs/ja/skills)とコマンドのディレクトリを再スキャンするため、フックがインストールしたスキルは同じセッションの最初のプロンプトから利用できます |
1250 1249
1251```json theme={null}1250```json theme={null}
1252{1251{
1258}1257}
1259```1258```
1260 1259
1261このイベントではプレーンな stdout がすでに Claude に届くため、コンテキストを読み込むだけのフックは JSON を組み立てずに stdout へ直接出力できます。コンテキストを `sessionTitle` などの他のフィールドと組み合わせる必要がある場合は、JSON 形式を使用してください。1260このイベントでは通常の標準出力がすでに Claude に届くため、コンテキストを読み込むだけのフックは JSON を組み立てずに直接標準出力に出力できます。コンテキストを `sessionTitle` などの他のフィールドと組み合わせる必要がある場合は JSON 形式を使用してください。
1262 1261
1263SessionStart フックがスキルをインストールまたは更新する場合は `reloadSkills` を使用します。スキルの検出は通常 SessionStart フックの完了前に実行されるため、フックが `~/.claude/skills/` や `.claude/skills/` に書き込んだファイルは、これを使わないと次のセッションでしか表示されません。次の例では、共有スキルのリポジトリを同期し、再スキャンを要求します。1262SessionStart フックがスキルをインストールまたは更新する場合は `reloadSkills` を使用してください。スキルの検出は通常 SessionStart フックの完了前に実行されるため、フックが `~/.claude/skills/` や `.claude/skills/` に書き込んだファイルは、そうしないと次のセッションでしか表示されません。次の例では、共有スキルリポジトリを同期し、再スキャンを要求します。
1264 1263
1265```bash theme={null}1264```bash theme={null}
1266#!/bin/bash1265#!/bin/bash
1271echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1272```1271```
1273 1272
1274リポジトリの URL はプレースホルダーです。自分のスキルリポジトリに置き換えてください。プレースホルダーのままでは clone が失敗し、stderr に `fatal:` メッセージが出力されます。終了コード 0 で終了した SessionStart フックの stderr は情報提供のみを目的としているため、`reloadSkills` の要求は引き続き適用されます。1273リポジトリの URL はプレースホルダーです。独自のスキルリポジトリに置き換えてください。プレースホルダーのままではクローンが失敗し、標準エラー出力に `fatal:` メッセージが出力されます。終了コード 0 で終了した SessionStart フックの標準エラー出力は情報提供のみを目的としているため、`reloadSkills` の要求は引き続き適用されます。
1275 1274
1276<h4 id="persist-environment-variables">1275<h4 id="persist-environment-variables">
1277 環境変数を永続化する1276 環境変数を永続化する
1278</h4>1277</h4>
1279 1278
1280SessionStart フックは `CLAUDE_ENV_FILE` 環境変数にアクセスできます。この変数は、後続の Bash コマンド用に環境変数を永続化できるファイルパスを提供します。1279SessionStart フックは `CLAUDE_ENV_FILE` 環境変数にアクセスできます。この変数は、後続の Bash コマンドのために環境変数を永続化できるファイルパスを提供します。
1281 1280
1282個々の環境変数を設定するには、`CLAUDE_ENV_FILE` に `export` 文を書き込みます。他のフックが設定した変数を保持するために、追記(`>>`)を使用してください。1281個別の環境変数を設定するには、`export` 文を `CLAUDE_ENV_FILE` に書き込みます。他のフックが設定した変数を保持するには、追記(`>>`)を使用してください。
1283 1282
1284```bash theme={null}1283```bash theme={null}
1285#!/bin/bash1284#!/bin/bash
1293exit 01292exit 0
1294```1293```
1295 1294
1296セットアップコマンドによるすべての環境の変更を取り込むには、エクスポートされた変数を前後で比較します。1295セットアップコマンドによるすべての環境の変更を取り込むには、エクスポートされた変数を実行前後で比較します。
1297 1296
1298```bash theme={null}1297```bash theme={null}
1299#!/bin/bash1298#!/bin/bash
1313```1312```
1314 1313
1315<Note>1314<Note>
1316 `CLAUDE_ENV_FILE` は SessionStart、[Setup](#setup)、[CwdChanged](#cwdchanged)、[FileChanged](#filechanged) フックで利用できます。その他のフックタイプはこの変数にアクセスできません。1315 `CLAUDE_ENV_FILE` は、SessionStart、[Setup](#setup)、[CwdChanged](#cwdchanged)、[FileChanged](#filechanged) の各フックで利用できます。その他の種類のフックはこの変数にアクセスできません。
1317</Note>1316</Note>
1318 1317
1319<h3 id="setup">1318<h3 id="setup">
1320 Setup1319 Setup
1321</h3>1320</h3>
1322 1321
1323`--init-only` で Claude Code を起動した場合、または `-p` フラグを使った[非対話モード](/docs/ja/headless)で `--init` か `--maintenance` を付けて起動した場合にのみ発火します。通常の起動時には発火しません。通常のセッション開始とは別に、CI やスクリプトから明示的にトリガーする一度きりの依存関係のインストールや定期的なクリーンアップに使用します。セッションごとの初期化には、代わりに [SessionStart](#sessionstart) を使用してください。1322Claude Code を `--init-only` で起動した場合、または `-p` フラグを使用した[非対話モード](/docs/ja/headless)で `--init` か `--maintenance` を指定して起動した場合にのみ発火します。通常の起動時には発火しません。通常のセッション起動とは別に、CI やスクリプトから明示的にトリガーする 1 回限りの依存関係のインストールや定期的なクリーンアップに使用してください。セッションごとの初期化には、代わりに [SessionStart](#sessionstart) を使用してください。
1324 1323
1325matcher の値は、フックをトリガーした CLI フラグに対応します。1324matcher の値は、フックをトリガーした CLI フラグに対応します。
1326 1325
1329| `init` | `claude --init-only` または `claude -p --init` |1328| `init` | `claude --init-only` または `claude -p --init` |
1330| `maintenance` | `claude -p --maintenance` |1329| `maintenance` | `claude -p --maintenance` |
1331 1330
1332`claude --init-only` を実行すると、Claude Code は Setup フックと `startup` matcher の `SessionStart` フックを実行し、会話を開始せずに終了します。1331`claude --init-only` を実行すると、Claude Code は Setup フックと `startup` matcher の `SessionStart` フックを実行した後、会話を開始せずに終了します。
1333 1332
1334`-p` で会話を開始または継続する場合は、引数として、または stdin へのパイプでプロンプトも指定する必要があります。`SessionStart` フックが [`initialUserMessage`](#sessionstart-decision-control) を提供する場合や、[延期されたツール呼び出し](#defer-a-tool-call-for-later)を含むセッションを再開する場合は、プロンプトを省略できます。1333`-p` で会話を開始または続行する場合は、引数として、または標準入力へのパイプでプロンプトも指定する必要があります。`SessionStart` フックが [`initialUserMessage`](#sessionstart-decision-control) を提供する場合や、[遅延されたツール呼び出し](#defer-a-tool-call-for-later)を含むセッションを再開する場合は、プロンプトを省略できます。
1335 1334
1336成功した場合、`--init-only` はターミナルに何も出力しません。フックが実行されたことを確認するには、`claude --debug-file <path> --init-only` で起動し(`<path>` はログファイルの場所に置き換えます)、ログで Setup と SessionStart のフックのエントリを確認してください。1335成功した場合、`--init-only` はターミナルに何も出力しません。フックが実行されたことを確認するには、`<path>` をログファイルの場所に置き換えて `claude --debug-file <path> --init-only` で起動し、ログに Setup と SessionStart のフックのエントリがあるか確認してください。
1337 1336
1338Setup はすべての起動時に発火するわけではないため、依存関係のインストールを必要とするプラグインは Setup だけに頼ることはできません。実用的なパターンは、初回使用時に依存関係を確認し、見つからなければインストールすることです。たとえば、`${CLAUDE_PLUGIN_DATA}/node_modules` の有無をテストし、なければ `npm install` を実行するフックやスキルです。インストールした依存関係の保存場所については、[永続データディレクトリ](/docs/ja/plugins/components#path-variables-and-persistent-data)を参照してください。マーケットプレイスを通じてプラグインを配布する場合は、このパターンが不要なこともあります。Claude Code はプラグインをキャッシュする際に、[対象となる Node.js パッケージの依存関係を自動的にインストールします](/docs/ja/plugins/loading#node-js-package-dependencies)。1337Setup はすべての起動時に発火するわけではないため、依存関係のインストールを必要とするプラグインは Setup だけに頼ることはできません。実用的なパターンは、初回使用時に依存関係を確認し、存在しなければインストールすることです。たとえば、`${CLAUDE_PLUGIN_DATA}/node_modules` の有無をテストし、存在しなければ `npm install` を実行するフックやスキルです。インストールした依存関係の保存場所については、[永続データディレクトリ](/docs/ja/plugins/components#path-variables-and-persistent-data)を参照してください。マーケットプレイスを通じてプラグインを配布する場合、このパターンは不要な場合があります。Claude Code はプラグインをキャッシュする際に、[対象となる Node.js パッケージの依存関係を自動的にインストール](/docs/ja/plugins/loading#node-js-package-dependencies)します。
1339 1338
1340<h4 id="setup-input">1339<h4 id="setup-input">
1341 Setup の入力1340 Setup の入力
1357 Setup の判定制御1356 Setup の判定制御
1358</h4>1357</h4>
1359 1358
1360Setup フックはブロックできず、どの終了コードでも実行は継続されます。どの終了コードであっても、Claude Code は Setup フックの [JSON 出力フィールド](#json-output)(`systemMessage`、`continue`、`hookSpecificOutput.additionalContext` など)を破棄します。`-p` を使用する場合、Setup フックの stdout、stderr、終了コードは、`--output-format stream-json --verbose` で起動したときに限り、[`hook_response` イベント](/docs/ja/headless#read-session-metadata)として実行の出力に表示されます。1359Setup フックはブロックできません。どの終了コードでも実行は続行されます。どの終了コードでも、Claude Code は Setup フックの [JSON 出力フィールド](#json-output)(`systemMessage`、`continue`、`hookSpecificOutput.additionalContext` など)を破棄します。`-p` を使用する場合、Setup フックの標準出力、標準エラー出力、終了コードは、`--output-format stream-json --verbose` で起動したときにのみ、[`hook_response` イベント](/docs/ja/headless#read-session-metadata)として実行の出力に表示されます。
1361 1360
1362Setup フックは `CLAUDE_ENV_FILE` にアクセスできます。このファイルに書き込まれた変数は、[SessionStart フック](#persist-environment-variables)と同様に、セッションの後続の Bash コマンドに引き継がれます。`Setup` では `type: "command"` フックのみが実行されます。`Setup` の `type: "mcp_tool"` フックは、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)で説明されているとおり、常にスキップされます。1361Setup フックは `CLAUDE_ENV_FILE` にアクセスできます。このファイルに書き込まれた変数は、[SessionStart フック](#persist-environment-variables)と同様に、セッションの後続の Bash コマンドに引き継がれます。`Setup` で実行されるのは `type: "command"` フックのみです。`Setup` の `type: "mcp_tool"` フックは、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)で説明されているとおり、常にスキップされます。
1363 1362
1364<h3 id="instructionsloaded">1363<h3 id="instructionsloaded">
1365 InstructionsLoaded1364 InstructionsLoaded
1366</h3>1365</h3>
1367 1366
1368`CLAUDE.md` または `.claude/rules/*.md` ファイルがコンテキストに読み込まれたときに発火します。このイベントは、即時に読み込まれるファイルについてはセッション開始時に発火し、その後ファイルが遅延読み込みされたときにも再び発火します。たとえば、Claude がネストされた `CLAUDE.md` を含むサブディレクトリにアクセスしたときや、`paths:` フロントマターを持つ条件付きルールが一致したときです。このフックはブロックや判定制御をサポートしません。可観測性の目的で非同期に実行されます。1367`CLAUDE.md` または `.claude/rules/*.md` ファイルがコンテキストに読み込まれたときに発火します。このイベントは、即時に読み込まれるファイルに対してはセッション開始時に発火し、ファイルが遅延読み込みされるときにも再度発火します。たとえば、Claude がネストされた `CLAUDE.md` を含むサブディレクトリにアクセスしたときや、`paths:` フロントマターを持つ条件付きルールが一致したときです。このフックはブロックや判定制御をサポートしていません。可観測性を目的として非同期に実行されます。
1369 1368
1370Claude が **Project instructions** 設定を通じて [`AGENTS.md` を直接読み込む](/docs/ja/memory#agents-md)場合、このイベントは発火しません。`CLAUDE.md` が `AGENTS.md` をインポートする場合は、他のインポートされたファイルと同様に `load_reason` が `include` に設定されて発火し、`CLAUDE.md` が `AGENTS.md` へのシンボリックリンクである場合は、通常の `CLAUDE.md` の読み込みとして発火します。1369Claude が **Project instructions** 設定を通じて [`AGENTS.md` を直接読み込む](/docs/ja/memory#agents-md)場合、このイベントは発火しません。`CLAUDE.md` が `AGENTS.md` をインポートする場合は、他のインポートされたファイルと同様に `load_reason` が `include` に設定されて発火し、`CLAUDE.md` が `AGENTS.md` へのシンボリックリンクである場合は、通常の `CLAUDE.md` の読み込みとして発火します。
1371 1370
1372matcher は `load_reason` に対して照合されます。たとえば、セッション開始時に読み込まれたファイルに対してのみ発火させるには `"matcher": "session_start"` を、遅延読み込みに対してのみ発火させるには `"matcher": "path_glob_match|nested_traversal"` を使用します。1371matcher は `load_reason` に対して実行されます。たとえば、セッション開始時に読み込まれたファイルに対してのみ発火させるには `"matcher": "session_start"` を、遅延読み込みに対してのみ発火させるには `"matcher": "path_glob_match|nested_traversal"` を使用します。
1373 1372
1374<h4 id="instructionsloaded-input">1373<h4 id="instructionsloaded-input">
1375 InstructionsLoaded の入力1374 InstructionsLoaded の入力
1382| `file_path` | 読み込まれた指示ファイルの絶対パス |1381| `file_path` | 読み込まれた指示ファイルの絶対パス |
1383| `memory_type` | ファイルのスコープ:`"User"`、`"Project"`、`"Local"`、または `"Managed"` |1382| `memory_type` | ファイルのスコープ:`"User"`、`"Project"`、`"Local"`、または `"Managed"` |
1384| `load_reason` | ファイルが読み込まれた理由:`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"`、または `"compact"`。`"compact"` の値は、コンテキスト圧縮イベントの後に指示ファイルが再読み込みされたときに発火します |1383| `load_reason` | ファイルが読み込まれた理由:`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"`、または `"compact"`。`"compact"` の値は、コンテキスト圧縮イベントの後に指示ファイルが再読み込みされたときに発火します |
1385| `globs` | ファイルの `paths:` フロントマターにあるパスの glob パターン(存在する場合)。`path_glob_match` の読み込みの場合にのみ含まれます |1384| `globs` | ファイルの `paths:` フロントマターにあるパスの glob パターン(存在する場合)。`path_glob_match` の読み込みの場合にのみ存在します |
1386| `trigger_file_path` | 遅延読み込みの場合に、この読み込みをトリガーしたアクセス先のファイルのパス |1385| `trigger_file_path` | 遅延読み込みの場合、この読み込みをトリガーしたアクセス先のファイルのパス |
1387| `parent_file_path` | `include` の読み込みの場合に、このファイルをインクルードした親の指示ファイルのパス |1386| `parent_file_path` | `include` の読み込みの場合、このファイルをインクルードした親の指示ファイルのパス |
1388 1387
1389```json theme={null}1388```json theme={null}
1390{1389{
1402 InstructionsLoaded の判定制御1401 InstructionsLoaded の判定制御
1403</h4>1402</h4>
1404 1403
1405InstructionsLoaded フックには判定制御がありません。指示の読み込みをブロックしたり変更したりすることはできません。Claude Code は、`systemMessage` や `continue` などの [JSON 出力フィールド](#json-output)を破棄します。このイベントは、監査ログ、コンプライアンスの追跡、可観測性に使用してください。1404InstructionsLoaded フックには判定制御がありません。指示の読み込みをブロックしたり変更したりすることはできません。Claude Code はこれらのフックの [JSON 出力フィールド](#json-output)(`systemMessage` や `continue` など)を破棄します。このイベントは、監査ログ、コンプライアンスの追跡、可観測性のために使用してください。
1406 1405
1407<h3 id="userpromptsubmit">1406<h3 id="userpromptsubmit">
1408 UserPromptSubmit1407 UserPromptSubmit
1412プロンプトや会話に基づいて追加のコンテキストを加えたり、プロンプトを検証したり、1411プロンプトや会話に基づいて追加のコンテキストを加えたり、プロンプトを検証したり、
1413特定の種類のプロンプトをブロックしたりできます。1412特定の種類のプロンプトをブロックしたりできます。
1414 1413
1415`UserPromptSubmit` フックは、ユーザーが入力したプロンプトだけで発火するわけではありません。Claude Code は以下の場合にもこれらのフックを実行します。1414`UserPromptSubmit` フックは、ユーザーが入力したプロンプトに対してだけ発火するわけではありません。Claude Code は以下の場合にも実行します。
1416 1415
1417* [スケジュールタスク](/docs/ja/scheduled-tasks)の発火(`/loop` の反復を含む)1416* [スケジュールタスク](/docs/ja/scheduled-tasks)の発火(`/loop` の反復を含む)
1418* [バックグラウンドのサブエージェント](/docs/ja/sub-agents#run-subagents-in-foreground-or-background)が、それを開始したセッションに結果を報告したとき1417* [バックグラウンドのサブエージェント](/docs/ja/sub-agents#run-subagents-in-foreground-or-background)が、それを開始したセッションに結果を報告するとき
1419* [別のセッションが送信したメッセージ](/docs/ja/cross-session-messaging)がメインの会話に届いたとき1418* [別のセッションが送信したメッセージ](/docs/ja/cross-session-messaging)がメインの会話に届いたとき
1420 1419
1421`UserPromptSubmit` フックのデフォルトのタイムアウトは、`command`、`http`、`mcp_tool` タイプで 30 秒です。これは、他のほとんどのイベントでのこれらのタイプのデフォルトである 600 秒より短くなっています。このフックはすべてのプロンプトの前に実行され、完了するまでモデルの処理をブロックするため、フックが停止するとセッションも停止します。フックにより長い時間が必要な場合は、フックエントリの `timeout` フィールドを設定してください。1420`UserPromptSubmit` フックのデフォルトのタイムアウトは、`command`、`http`、`mcp_tool` の各タイプで 30 秒です。これは、他のほとんどのイベントでのこれらのタイプのデフォルトである 600 秒より短くなっています。このフックはすべてのプロンプトの前に実行され、完了するまでモデルの処理をブロックするため、フックが停止するとセッションも停止します。フックにさらに時間が必要な場合は、フックエントリの `timeout` フィールドを設定してください。
1422 1421
1423[`async: true`](#run-hooks-in-the-background) で実行するコマンドフックを除き、タイムアウトに達した `UserPromptSubmit` のコマンド、HTTP、または MCP ツールのフックはキャンセルされ、その出力は `additionalContext` も含めて破棄されます。プロンプトはそのコンテキストなしで Claude に届きます。トランスクリプトには、フック名、発生したタイムアウト、出力が破棄されたことを示す通知が表示されます。1422[`async: true`](#run-hooks-in-the-background) で実行するコマンドフックを除き、タイムアウトに達した `UserPromptSubmit` のコマンド、HTTP、または MCP ツールフックはキャンセルされ、その出力(`additionalContext` を含む)は破棄されます。プロンプトはそのコンテキストなしで Claude に届きます。トランスクリプトには、フック名、発生したタイムアウト、出力が破棄されたことを示す通知が表示されます。
1424 1423
1425`UserPromptSubmit` 上の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)がタイムアウトに達すると、フック名とタイムアウトを示すメッセージとともにプロンプトがブロックされます。このイベントのコールバックは、フェイルオープンしてはならないポリシーゲートとして機能している可能性があるためです。セッションは継続します。v2.1.208 より前は、このイベントでコールバックがタイムアウトすると、実行エラーでターンが終了していました。1424`UserPromptSubmit` の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)がタイムアウトに達すると、フック名とタイムアウトを示すメッセージとともにプロンプトがブロックされます。これは、そこでのコールバックが、フェイルオープンしてはならないポリシーゲートとして機能している可能性があるためです。セッションは続行されます。v2.1.208 より前は、このイベントでのコールバックのタイムアウトは実行エラーでターンを終了していました。
1426 1425
1427<h4 id="userpromptsubmit-input">1426<h4 id="userpromptsubmit-input">
1428 UserPromptSubmit の入力1427 UserPromptSubmit の入力
1430 1429
1431[共通の入力フィールド](#common-input-fields)に加えて、UserPromptSubmit フックは送信されたテキストを含む `prompt` フィールドを受け取ります。`[Pasted text #N]` プレースホルダーに折りたたまれた貼り付けコンテンツは、その場で展開された状態で届きます。Claude Code が[貼り付けたテキストを Claude 向けにマークする](/docs/ja/terminal-config#how-claude-treats-pasted-text)セッションでは、展開されたコンテンツは `<pasted_content id="…">` の行と `</pasted_content id="…">` の行の間に置かれるため、フックがプロンプトを解析する場合はこれらの行を考慮してください。1430[共通の入力フィールド](#common-input-fields)に加えて、UserPromptSubmit フックは送信されたテキストを含む `prompt` フィールドを受け取ります。`[Pasted text #N]` プレースホルダーに折りたたまれた貼り付けコンテンツは、その場で展開された状態で届きます。Claude Code が[貼り付けたテキストを Claude 向けにマークする](/docs/ja/terminal-config#how-claude-treats-pasted-text)セッションでは、展開されたコンテンツは `<pasted_content id="…">` の行と `</pasted_content id="…">` の行の間に置かれるため、フックがプロンプトを解析する場合はこれらの行を考慮してください。
1432 1431
1433UserPromptSubmit フックは、セッションにカスタムタイトルがある場合に `session_title` も受け取ります。意味は [SessionStart の `session_title` フィールド](#sessionstart-input)と同じです。1432UserPromptSubmit フックは、セッションにカスタムタイトルがある場合に `session_title` も受け取ります。その意味は [SessionStart の `session_title` フィールド](#sessionstart-input)と同じです。
1434 1433
1435```json theme={null}1434```json theme={null}
1436{1435{
1447 UserPromptSubmit の判定制御1446 UserPromptSubmit の判定制御
1448</h4>1447</h4>
1449 1448
1450`UserPromptSubmit` フックは、送信されたプロンプトを処理するかどうかを制御し、コンテキストを追加できます。すべての [JSON 出力フィールド](#json-output)を使用できます。1449`UserPromptSubmit` フックは、送信されたプロンプトを処理するかどうかを制御し、コンテキストを追加できます。すべての [JSON 出力フィールド](#json-output)が利用できます。
1451 1450
1452終了コード 0 で会話にコンテキストを追加する方法は 2 つあります。1451終了コード 0 の場合、会話にコンテキストを追加する方法は 2 つあります。
1453 1452
1454* **プレーンテキストの stdout**:Claude Code は、[プレーンテキストとして扱う](#exit-code-0) stdout を Claude のコンテキストに追加します1453* **プレーンテキストの標準出力**:Claude Code は、[プレーンテキストとして扱う](#exit-code-0)標準出力を Claude のコンテキストに追加します
1455* **`additionalContext` を含む JSON**:より細かく制御するには、以下の JSON 形式を使用します。`additionalContext` フィールドがコンテキストとして追加されます1454* **`additionalContext` を含む JSON**:より細かく制御するには、以下の JSON 形式を使用します。`additionalContext` フィールドがコンテキストとして追加されます
1456 1455
1457どちらの経路でも、トランスクリプトに表示されるエントリは作成されません。プレーンな stdout と `additionalContext` の値は、それぞれフック名で始まるシステムリマインダーとして挿入され、Claude は両方を読みます。配信を確認するには、[デバッグログ](#debug-hooks)を確認してください。1456どちらのチャネルも、トランスクリプトに表示されるエントリは作成しません。通常の標準出力と `additionalContext` の値は、それぞれフック名で始まるシステムリマインダーとして挿入され、Claude は両方を読み取ります。配信を確認するには、[デバッグログ](#debug-hooks)を確認してください。
1458 1457
1459プロンプトをブロックするには、`decision` を `"block"` に設定した JSON オブジェクトを返します。1458プロンプトをブロックするには、`decision` を `"block"` に設定した JSON オブジェクトを返します。
1460 1459
1461| フィールド | 説明 |1460| フィールド | 説明 |
1462| :- | :- |1461| :- | :- |
1463| `decision` | `"block"` は、プロンプトが Claude に届く前に停止します。プロンプトの続行を許可するには省略します |1462| `decision` | `"block"` は、プロンプトが Claude に届く前に停止します。プロンプトの処理を続行させる場合は省略します |
1464| `reason` | `decision` が `"block"` の場合にユーザーに表示されます。コンテキストには追加されません |1463| `reason` | `decision` が `"block"` の場合にユーザーに表示されます。コンテキストには追加されません |
1465| `additionalContext` | 送信されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |1464| `additionalContext` | 送信されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1466| `sessionTitle` | セッションのタイトルを設定します。プロンプトの内容に基づいてセッションに自動的に名前を付けるのに使用します |1465| `sessionTitle` | セッションタイトルを設定します。プロンプトの内容に基づいてセッションに自動で名前を付ける場合に使用します |
1467| `suppressOriginalPrompt` | フックがプロンプトをブロックするときに `true` の場合、ブロックメッセージからプロンプトのテキストを除外します。[ブロックされたプロンプトが残すもの](#what-a-blocked-prompt-leaves-behind)を参照してください |1466| `suppressOriginalPrompt` | フックがプロンプトをブロックする際に `true` の場合、ブロックメッセージからプロンプトのテキストを除外します。[ブロックされたプロンプトが残すもの](#what-a-blocked-prompt-leaves-behind)を参照してください |
1468 1467
1469終了コード 2 で終了してブロックするフックは、`reason` と同じ経路をたどります。ブロックメッセージは stderr のテキストをユーザーに表示し、それはコンテキストには追加されません。1468終了コード 2 で終了してブロックするフックは、`reason` と同じ方法で処理されます。ブロックメッセージには標準エラー出力のテキストがユーザーに表示され、コンテキストには追加されません。
1470 1469
1471```json theme={null}1470```json theme={null}
1472{1471{
1485 ブロックされたプロンプトが残すもの1484 ブロックされたプロンプトが残すもの
1486</h4>1485</h4>
1487 1486
1488ブロックされたプロンプトは Claude には届きませんが、そのテキストがすべての場所から削除されるわけではありません。デフォルトでは、ユーザーに表示されるブロックメッセージの末尾に `Original prompt:` と送信されたテキストが続き、Claude Code はそのメッセージをディスク上のセッションのトランスクリプトファイルに書き込みます。メッセージからテキストを除外するには、`hookSpecificOutput` 内に `"suppressOriginalPrompt": true` を含む JSON を出力します。これは、フックが `decision: "block"` でブロックする場合でも、終了コード 2 でブロックする場合でも機能します。1487ブロックされたプロンプトは Claude に届きませんが、そのテキストがあらゆる場所から削除されるわけではありません。デフォルトでは、ユーザーに表示されるブロックメッセージの末尾に `Original prompt:` と送信されたテキストが続き、Claude Code はそのメッセージをディスク上のセッションのトランスクリプトファイルに書き込みます。メッセージからテキストを除外するには、`hookSpecificOutput` 内に `"suppressOriginalPrompt": true` を含む JSON を出力してください。これは、フックが `decision: "block"` でブロックする場合でも、終了コード 2 で終了してブロックする場合でも機能します。
1489 1488
1490`suppressOriginalPrompt` が変更するのはブロックメッセージのみです。送信されたテキストは、セッションのトランスクリプトやプロンプト履歴などのローカルファイルに引き続き現れる可能性があるため、ブロックするフックは機密情報をディスクに残さないための手段にはなりません。これらのファイルを制限または削除するには、[プレーンテキストでの保存](/docs/ja/claude-directory#plaintext-storage)と[ローカルデータの消去](/docs/ja/claude-directory#clear-local-data)を参照してください。1489`suppressOriginalPrompt` が変更するのはブロックメッセージだけです。送信されたテキストは、セッションのトランスクリプトやプロンプト履歴などのローカルファイルに引き続き表示される可能性があるため、ブロックするフックは秘密情報をディスクに残さないための手段にはなりません。これらのファイルを制限または削除するには、[プレーンテキストの保存](/docs/ja/claude-directory#plaintext-storage)と[ローカルデータを消去する](/docs/ja/claude-directory#clear-local-data)を参照してください。
1491 1490
1492<h3 id="userpromptexpansion">1491<h3 id="userpromptexpansion">
1493 UserPromptExpansion1492 UserPromptExpansion
1494</h3>1493</h3>
1495 1494
1496ユーザーが入力したコマンドが、Claude に届く前にプロンプトへ展開されるときに実行されます。特定のコマンドの直接呼び出しをブロックしたり、特定のスキルにコンテキストを挿入したり、ユーザーが呼び出したコマンドをログに記録したりするのに使用します。たとえば、`deploy` に一致するフックは承認ファイルが存在しない限り `/deploy` をブロックでき、レビュースキルに一致するフックはチームのレビューチェックリストを `additionalContext` として追加できます。1495ユーザーが入力したコマンドが、Claude に届く前にプロンプトに展開されるときに実行されます。特定のコマンドの直接呼び出しをブロックしたり、特定のスキルにコンテキストを挿入したり、ユーザーがどのコマンドを呼び出したかをログに記録したりするのに使用します。たとえば、`deploy` に一致するフックは承認ファイルが存在しない限り `/deploy` をブロックでき、レビュースキルに一致するフックはチームのレビューチェックリストを `additionalContext` として追加できます。
1497 1496
1498このイベントは、`PreToolUse` がカバーしない経路を扱います。`Skill` ツールに一致する `PreToolUse` フックは Claude がツールを呼び出したときにのみ発火しますが、`/skillname` を直接入力すると `PreToolUse` を経由しません。`UserPromptExpansion` はその直接の経路で発火します。1497このイベントは、`PreToolUse` がカバーしない経路をカバーします。`Skill` ツールに一致する `PreToolUse` フックは Claude がツールを呼び出したときにのみ発火しますが、`/skillname` を直接入力すると `PreToolUse` はバイパスされます。`UserPromptExpansion` はその直接の経路で発火します。
1499 1498
1500`command_name` に対して照合します。すべてのプロンプト型コマンドで発火させるには、matcher を空のままにします。1499`command_name` に対してマッチします。すべてのプロンプト型コマンドで発火させるには、matcher を空のままにしてください。
1501 1500
1502<h4 id="userpromptexpansion-input">1501<h4 id="userpromptexpansion-input">
1503 UserPromptExpansion の入力1502 UserPromptExpansion の入力
1504</h4>1503</h4>
1505 1504
1506[共通の入力フィールド](#common-input-fields)に加えて、UserPromptExpansion フックは `expansion_type`、`command_name`、`command_args`、`command_source`、および元の `prompt` 文字列を受け取ります。`expansion_type` フィールドは、スキルとカスタムコマンドでは `slash_command`、MCP サーバーのプロンプトでは `mcp_prompt` になります。1505[共通の入力フィールド](#common-input-fields)に加えて、UserPromptExpansion フックは `expansion_type`、`command_name`、`command_args`、`command_source`、および元の `prompt` 文字列を受け取ります。`expansion_type` フィールドは、スキルとカスタムコマンドの場合は `slash_command`、MCP サーバーのプロンプトの場合は `mcp_prompt` です。
1507 1506
1508```json theme={null}1507```json theme={null}
1509{1508{
1524 UserPromptExpansion の判定制御1523 UserPromptExpansion の判定制御
1525</h4>1524</h4>
1526 1525
1527`UserPromptExpansion` フックは、展開をブロックしたり、コンテキストを追加したりできます。すべての [JSON 出力フィールド](#json-output)を利用できます。1526`UserPromptExpansion` フックは、展開をブロックしたりコンテキストを追加したりできます。すべての [JSON 出力フィールド](#json-output)が利用できます。
1528 1527
1529| フィールド | 説明 |1528| フィールド | 説明 |
1530| :- | :- |1529| :- | :- |
1531| `decision` | `"block"` は、コマンドの展開を防ぎます。続行を許可するには省略します |1530| `decision` | `"block"` はコマンドの展開を防ぎます。続行させる場合は省略します |
1532| `reason` | `decision` が `"block"` の場合にユーザーに表示されます |1531| `reason` | `decision` が `"block"` の場合にユーザーに表示されます |
1533| `additionalContext` | 展開されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |1532| `additionalContext` | 展開されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1534 1533
1535終了コード 2 で終了してブロックするフックは、`reason` と同じ経路をたどります。ブロックメッセージは stderr のテキストをユーザーに表示します。1534終了コード 2 で終了してブロックするフックは、`reason` と同じ方法で処理されます。ブロックメッセージには標準エラー出力のテキストがユーザーに表示されます。
1536 1535
1537```json theme={null}1536```json theme={null}
1538{1537{
1549 MessageDisplay1548 MessageDisplay
1550</h3>1549</h3>
1551 1550
1552アシスタントのメッセージが画面にストリーミングされている間に実行されます。Claude Code はメッセージを段階的に表示します。新たに完成した行のバッチがレンダリングできる状態になるたびに、フックがそれらの行を使って 1 回実行され、Claude Code はその位置にフックの置換テキストをレンダリングします。長いメッセージでは複数回呼び出され、短いメッセージでは 1 回だけのこともあります。1551アシスタントのメッセージが画面にストリーミングされている間に実行されます。Claude Code はメッセージを段階的に表示します。新たに完成した行のバッチが描画できる状態になるたびに、フックはそれらの行を受け取って 1 回実行され、Claude Code はフックの置換テキストをその位置に描画します。長いメッセージでは複数回呼び出され、短いメッセージでは 1 回だけの場合もあります。
1553 1552
1554MessageDisplay は次の用途に使用します。1553MessageDisplay は次の用途に使用します。
1555 1554
1556* 最小限の表示のために markdown を取り除く1555* 最小限の表示のために markdown を除去する
1557* Agent SDK アプリケーションがユーザーに表示するテキストを変換する1556* Agent SDK アプリケーションがユーザーに表示するテキストを変換する
1558* Claude の応答から API キーや内部ホスト名を伏せる1557* Claude の応答から API キーや内部ホスト名を秘匿する
1559 1558
1560Claude Code はフックが返るまで各バッチを保留するため、フックは高速に保ってください。フックが失敗するかタイムアウトした場合、Claude Code は元のテキストを表示します。このイベントのデフォルトのタイムアウトは 10 秒です。フックにより長い時間が必要な場合は、フックエントリの `timeout` フィールドを設定してください。1559Claude Code はフックが戻るまで各バッチを保持するため、フックは高速に保ってください。フックが失敗するかタイムアウトした場合、Claude Code は元のテキストを表示します。このイベントのデフォルトのタイムアウトは 10 秒です。フックにさらに時間が必要な場合は、フックエントリの `timeout` フィールドを設定してください。
1561 1560
1562MessageDisplay は表示専用です。置換テキストは画面にレンダリングされる内容のみを変更します。トランスクリプトと Claude が参照する内容は元のテキストのままなので、Claude が置換テキストを目にすることはなく、詳細モードでは元のテキストが表示されます。フックが受け取るのはアシスタントのメッセージテキストのみなので、ツールの結果やユーザーが入力したテキストは変更されずにレンダリングされます。1561MessageDisplay は表示専用です。置換テキストは画面に描画される内容だけを変更します。トランスクリプトと Claude が参照する内容は元のテキストのままであるため、Claude が置換テキストを見ることはなく、詳細モードでは元のテキストが表示されます。フックが受け取るのはアシスタントのメッセージのテキストのみであるため、ツールの結果やユーザーが入力したテキストは変更されずに描画されます。
1563 1562
1564MessageDisplay は matcher をサポートしておらず、テキストをストリーミングするすべてのアシスタントメッセージで発火します。ツール呼び出しのみの応答など、テキストを含まないメッセージではトリガーされません。1563MessageDisplay は matcher をサポートしておらず、テキストをストリーミングするすべてのアシスタントメッセージで発火します。ツール呼び出しのみの応答など、テキストを含まないメッセージでは発火しません。
1565 1564
1566Agent SDK のクエリや `claude -p` を含む非対話の実行では、MessageDisplay は行のバッチごとではなく、アシスタントメッセージごとに 1 回実行されます。この 1 回の呼び出しはメッセージの完了後に届き、メッセージのテキスト全体を含みます。`index` は `0`、`final` は `true` で、`delta` にメッセージ全体が入ります。各メッセージの `delta` テキストを収集するフックは、どちらのモードでも同じ合計テキストを受け取ります。1565Agent SDK のクエリや `claude -p` を含む非対話の実行では、MessageDisplay は行のバッチごとではなく、アシスタントメッセージごとに 1 回実行されます。その 1 回の呼び出しはメッセージの完了後に届き、メッセージの全文を含みます。`index` は `0`、`final` は `true`、`delta` はメッセージ全体を保持します。各メッセージの `delta` テキストを収集するフックは、どちらのモードでも同じテキスト全体を受け取ります。
1567 1566
1568<h4 id="messagedisplay-input">1567<h4 id="messagedisplay-input">
1569 MessageDisplay の入力1568 MessageDisplay の入力
1570</h4>1569</h4>
1571 1570
1572[共通の入力フィールド](#common-input-fields)に加えて、MessageDisplay フックはターンとメッセージの識別子、メッセージ内でのこの呼び出しの位置、および `delta` 内の新しいテキストを受け取ります。バッチの境界はテキストのストリーミング方法に依存するため、行が特定の方法でグループ化されることを期待するのではなく、`index` と `final` を使ってメッセージの進行状況を追跡してください。1571[共通の入力フィールド](#common-input-fields)に加えて、MessageDisplay フックは、ターンとメッセージの識別子、メッセージ内でのこの呼び出しの位置、および `delta` 内の新しいテキストを受け取ります。バッチの境界はテキストのストリーミング方法によって異なるため、行が特定の方法でグループ化されることを期待するのではなく、`index` と `final` を使用してメッセージ内の進行状況を追跡してください。
1573 1572
1574| フィールド | 説明 |1573| フィールド | 説明 |
1575| :- | :- |1574| :- | :- |
1576| `turn_id` | 現在のターンの UUID |1575| `turn_id` | 現在のターンの UUID |
1577| `message_id` | 表示中のアシスタントメッセージの UUID。同じメッセージのすべてのバッチで一定です。これは API の `msg_…` ID ではないため、トランスクリプトのメッセージ ID と対応付けることはできません |1576| `message_id` | 表示中のアシスタントメッセージの UUID。同じメッセージのすべてのバッチで一定です。これは API の `msg_…` ID ではないため、トランスクリプトのメッセージ ID と関連付けることはできません |
1578| `index` | メッセージ内でのこのバッチの 0 始まりのインデックス |1577| `index` | メッセージ内でのこのバッチの 0 から始まるインデックス |
1579| `final` | メッセージの最後のバッチで `true`。各メッセージにはちょうど 1 つの最終バッチがあります |1578| `final` | メッセージの最後のバッチで `true`。各メッセージには最終バッチがちょうど 1 つあります |
1580| `delta` | 前のバッチ以降に新たに完成した行(末尾の改行を含む)。常に行全体ですが、最終バッチは行の途中で終わる場合があります。対話的な実行では、メッセージが改行で終わる場合は最終バッチの delta が空になるため、空でない delta ではなく `final` をメッセージ終了のシグナルとして扱ってください。Agent SDK と `claude -p` の実行では、1 回の呼び出しにメッセージ全体が含まれます |1579| `delta` | 前回のバッチ以降に新たに完成した行(終端の改行を含む)。常に行単位ですが、最終バッチは行の途中で終わる場合があります。対話の実行では、メッセージが改行で終わる場合に最終バッチの delta は空になるため、空でない delta ではなく `final` をメッセージ終了のシグナルとして扱ってください。Agent SDK と `claude -p` の実行では、1 回の呼び出しがメッセージ全体を含みます |
1581 1580
1582```json theme={null}1581```json theme={null}
1583{1582{
1597 MessageDisplay の出力1596 MessageDisplay の出力
1598</h4>1597</h4>
1599 1598
1600すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、MessageDisplay フックは `displayContent` を返して、画面上の delta を置き換えることができます。1599すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、MessageDisplay フックは画面上の delta を置き換えるために `displayContent` を返すことができます。
1601 1600
1602| フィールド | 説明 |1601| フィールド | 説明 |
1603| :- | :- |1602| :- | :- |
1604| `displayContent` | delta の代わりに表示されるテキスト。元のテキストを表示するには省略します |1603| `displayContent` | delta の代わりに表示されるテキスト。元のテキストを表示する場合は省略します |
1605 1604
1606MessageDisplay フックには判定制御がありません。メッセージをブロックしたり、トランスクリプトに保存される内容や Claude に送信される内容を変更したりすることはできません。Claude Code は JSON 出力の `displayContent` に従って動作し、`systemMessage` と `continue` は破棄します。1605MessageDisplay フックには判定制御がありません。メッセージをブロックしたり、トランスクリプトに保存される内容や Claude に送信される内容を変更したりすることはできません。Claude Code は JSON 出力の `displayContent` に従って動作し、`systemMessage` と `continue` は破棄します。
1607 1606
1608次の例では、プレーンテキストで表示するために Claude の応答から markdown の書式を取り除きます。スクリプトは stdin から各バッチを読み取り、`delta` から太字のマーカーとインラインコードのバッククォートを削除し、結果を `displayContent` として返します。1607次の例では、プレーンテキストで表示するために Claude の応答から markdown の書式を除去します。スクリプトは各バッチを標準入力から読み取り、`delta` から太字のマーカーとインラインコードのバッククォートを取り除き、結果を `displayContent` として返します。
1609 1608
1610<Tabs>1609<Tabs>
1611 <Tab title="macOS/Linux">1610 <Tab title="macOS/Linux">
1612 設定ファイルで、このイベントのコマンドフックを登録します。1611 設定ファイルで、このイベント用のコマンドフックを登録します。
1613 1612
1614 ```json theme={null}1613 ```json theme={null}
1615 {1614 {
1638 </Tab>1637 </Tab>
1639 1638
1640 <Tab title="Windows (PowerShell)">1639 <Tab title="Windows (PowerShell)">
1641 PowerShell 経由でスクリプトを実行するコマンドフックを登録します。1640 PowerShell を通じてスクリプトを実行するコマンドフックを登録します。
1642 1641
1643 ```json theme={null}1642 ```json theme={null}
1644 {1643 {
1664 }1663 }
1665 ```1664 ```
1666 1665
1667 `-NoProfile` フラグは PowerShell プロファイルの読み込みをスキップしてフックを高速に起動させ、`-ExecutionPolicy Bypass` は PowerShell がローカルのスクリプトファイルを実行できるようにします。1666 `-NoProfile` フラグは PowerShell プロファイルの読み込みをスキップしてフックを高速に起動し、`-ExecutionPolicy Bypass` は PowerShell がローカルのスクリプトファイルを実行できるようにします。
1668 1667
1669 このスクリプトをプロジェクトの `.claude/hooks/plain-display.ps1` に保存します。1668 このスクリプトをプロジェクトの `.claude/hooks/plain-display.ps1` に保存します。
1670 1669
1681 </Tab>1680 </Tab>
1682</Tabs>1681</Tabs>
1683 1682
1684markdown を含まないバッチは変更されずにそのまま通過します。たとえば `jq` がないためにスクリプトが失敗した場合、Claude Code は元のテキストを表示し、その失敗はセッション内ではなく[デバッグ出力](#debug-hooks)にのみ記録されます。1683markdown を含まないバッチは変更されずにそのまま通過します。`jq` がないなどの理由でスクリプトが失敗した場合、Claude Code は元のテキストを表示し、失敗はセッション内ではなく[デバッグ出力](#debug-hooks)にのみ記録されます。
1685 1684
1686<h3 id="pretooluse">1685<h3 id="pretooluse">
1687 PreToolUse1686 PreToolUse
1688</h3>1687</h3>
1689 1688
1690Claude がツールのパラメーターを作成した後、ツール呼び出しを処理する前に実行されます。`EndConversation` を除く任意のツール名に一致します。対象は、`Bash`、`PowerShell`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`Workflow`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` などの組み込みツールと、任意の [MCP ツール名](#match-mcp-tools)です。1689Claude がツールのパラメーターを作成した後、ツール呼び出しを処理する前に実行されます。`EndConversation` を除く任意のツール名にマッチします。`Bash`、`PowerShell`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`Workflow`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` などの組み込みツールと、任意の [MCP ツール名](#match-mcp-tools)が対象です。
1691 1690
1692書き込んだものが何であれ、特定のファイルがディスク上で変更されたときにフックを実行するには、ファイル編集ツールを名前で照合する代わりに [FileChanged](#filechanged) を使用してください。PreToolUse とは異なり、Claude Code は FileChanged フックを変更の後に実行し、判定制御もないため、書き込みをブロックすることはできません。1691書き込んだのが何であれ、特定のファイルがディスク上で変更されたときにフックを実行するには、ファイル編集ツールを名前でマッチさせるのではなく [FileChanged](#filechanged) を使用してください。PreToolUse とは異なり、Claude Code は FileChanged フックを変更後に実行し、これには判定制御がないため、書き込みをブロックすることはできません。
1693 1692
1694<Warning>1693<Warning>
1695 PreToolUse は、Claude がツールを呼び出したときにのみ実行されます。[プロンプト内で `@` を使って参照した](/docs/ja/common-workflows#reference-files-and-directories)ファイルは、ツール呼び出しなしで追加されます。Claude Code はプロンプトを組み立てる際にその内容を挿入するため、`Read` に一致するフックを含め、PreToolUse フックは発火しません。特定のパスを `@` 参照からブロックするには、代わりに [`Read` の拒否ルール](/docs/ja/permissions#read-and-edit)を使用してください。1694 PreToolUse は、Claude がツールを呼び出した場合にのみ実行されます。[プロンプト内で `@` を使って参照した](/docs/ja/common-workflows#reference-files-and-directories)ファイルは、ツール呼び出しなしで追加されます。Claude Code はプロンプトの構築中にその内容を挿入するため、`Read` にマッチするフックを含め、PreToolUse フックはそれらのファイルに対して発火しません。`@` 参照から特定のパスをブロックするには、代わりに [`Read` の拒否ルール](/docs/ja/permissions#read-and-edit)を使用してください。
1696 1695
1697 PreToolUse は [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) でも発火しません。1696 PreToolUse は [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) に対しても発火しません。
1698</Warning>1697</Warning>
1699 1698
1700[PreToolUse の判定制御](#pretooluse-decision-control)を使用して、ツール呼び出しを許可、拒否、確認、または延期します。1699ツール呼び出しを許可、拒否、確認、または遅延させるには、[PreToolUse の判定制御](#pretooluse-decision-control)を使用します。
1701 1700
1702`PreToolUse` 上の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)がタイムアウトを超えると、ツール呼び出しがブロックされ、Claude はタイムアウトを示すエラー結果を受け取ります。他のフックが返した明示的な拒否は引き続き優先されます。1701タイムアウトを超えた `PreToolUse` の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)はツール呼び出しをブロックし、Claude はタイムアウトを示すエラー結果を受け取ります。別のフックが返した明示的な拒否は引き続き優先されます。
1703 1702
1704<h4 id="pretooluse-input">1703<h4 id="pretooluse-input">
1705 PreToolUse の入力1704 PreToolUse の入力
1707 1706
1708[共通の入力フィールド](#common-input-fields)に加えて、PreToolUse フックは `tool_name`、`tool_input`、`tool_use_id` を受け取ります。1707[共通の入力フィールド](#common-input-fields)に加えて、PreToolUse フックは `tool_name`、`tool_input`、`tool_use_id` を受け取ります。
1709 1708
1710[MCP ツール](#match-mcp-tools)の場合、入力には `mcp_server` も含まれます。これは、サーバーの `name` と、サーバーの定義がどこから来たかを示す `source` を持つオブジェクトです。`source` の値には、`plugin`、`sdk`、および `user` や `project` などの設定スコープが含まれます。Agent SDK リファレンスの [`McpServerProvenance`](/docs/ja/agent-sdk/typescript#mcpserverprovenance) にすべての値が記載されており、認識できない値の扱い方も説明されています。信頼の判断は、`name` や `mcp__<server>__` というツール名のプレフィックスではなく、`source` に基づいて行ってください。`mcp_server` フィールドには Claude Code v2.1.274 以降が必要です。1709[MCP ツール](#match-mcp-tools)の場合、入力には `mcp_server` も含まれます。これは、サーバーの `name` と、サーバーの定義がどこから来たかを示す `source` を持つオブジェクトです。`source` の値には、`plugin`、`sdk`、および `user` や `project` などの設定スコープがあります。Agent SDK リファレンスの [`McpServerProvenance`](/docs/ja/agent-sdk/typescript#mcpserverprovenance) にすべての値の一覧と、認識できない値の扱い方が記載されています。信頼の判断は、`name` や `mcp__<server>__` というツール名のプレフィックスではなく、`source` に基づいて行ってください。`mcp_server` フィールドには Claude Code v2.1.274 以降が必要です。
1711 1710
1712ファイルツールの `Write`、`Edit`、`Read` では、`tool_input.file_path` は常に絶対パスです。1711ファイルツールの `Write`、`Edit`、`Read` では、`tool_input.file_path` は常に絶対パスです。
1713 1712
1714* Claude Code はフックの実行前に `~` と相対パスを展開するため、パスに対して照合するフックを、`~` や同じパスの相対表記で回避することはできません1713* Claude Code はフックの実行前に `~` と相対パスを展開するため、パスでマッチするフックを `~` や同じパスの相対表記でバイパスすることはできません
1715* Windows では、フックが `$PWD` が `/c/project` のように見える Git Bash で実行される場合でも、パスはバックスラッシュ区切りで届きます1714* Windows では、`$PWD` が `/c/project` のように見える Git Bash でフックを実行している場合でも、パスはバックスラッシュ区切りで届きます
1716* `/src/` のチェックのようにスラッシュで記述した比較はバックスラッシュのパスに決して一致せず、ツール呼び出しはフックがブロックするものがなかったかのように続行されます1715* `/src/` のチェックなど、スラッシュで書かれた比較はバックスラッシュのパスには決してマッチせず、フックがブロックするものがなかったかのようにツール呼び出しが続行されます
1717* 比較の前に区切り文字を正規化してください。Bash では `FILE_PATH="${FILE_PATH//\\//}"`、Python では `file_path.replace("\\", "/")` を使用します。その後、パスは絶対パスなので、`^` で固定するのではなく `/src/` のようなパスセグメントで照合してください1716* 比較の前に区切り文字を正規化してください。Bash では `FILE_PATH="${FILE_PATH//\\//}"`、Python では `file_path.replace("\\", "/")` を使用し、パスは絶対パスであるため、`^` で先頭に固定するのではなく `/src/` などのパスセグメントでマッチさせてください
1718 1717
1719Windows での `Write` 呼び出しでは、次のように届きます。1718Windows での `Write` 呼び出しでは次のように渡されます。
1720 1719
1721```json theme={null}1720```json theme={null}
1722{1721{
1743| フィールド | 型 | 例 | 説明 |1742| フィールド | 型 | 例 | 説明 |
1744| :- | :- | :- | :- |1743| :- | :- | :- | :- |
1745| `command` | string | `"npm test"` | 実行するシェルコマンド |1744| `command` | string | `"npm test"` | 実行するシェルコマンド |
1746| `description` | string | `"Run test suite"` | コマンドの動作についての説明(省略可) |1745| `description` | string | `"Run test suite"` | コマンドの動作についての説明(オプション) |
1747| `timeout` | number | `120000` | タイムアウト(ミリ秒、省略可)。[最大値](/docs/ja/tools-reference#bash-tool-behavior)を超える値は拒否されず、最大値に切り下げられます |1746| `timeout` | number | `120000` | ミリ秒単位のタイムアウト(オプション)。[最大値](/docs/ja/tools-reference#bash-tool-behavior)を超える値は拒否されず、最大値に切り下げられます |
1748| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |1747| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |
1749 1748
1750Bash コマンドが Git リポジトリ内のファイルを変更すると、Claude Code は変更内容を記録できます。[`bashEditDiffEnabled`](/docs/ja/settings-reference#basheditdiffenabled) 設定で記録がオンになっている場合は、すべての権限モードで変更を記録します。どのファイルでこの設定を行えるかは、その設定の項目に記載されています。それ以外の場合は、auto モードと `bypassPermissions` モードで、かつ Claude Code が Claude に Bash 経由でファイルを編集するよう指示した場合にのみ記録します。記録をオフにするには、`bashEditDiffEnabled` を `false` に設定します。バックグラウンドのコマンドと読み取り専用のコマンドには差分は付きません。1749Bash コマンドが Git リポジトリ内のファイルを変更した場合、Claude Code は変更内容を記録できます。[`bashEditDiffEnabled`](/docs/ja/settings-reference#basheditdiffenabled) 設定で記録がオンになっている場合は、すべての権限モードで変更を記録します。どのファイルでこの設定を指定できるかは、その設定のエントリに記載されています。それ以外の場合は、auto モードと `bypassPermissions` モードでのみ、かつ Claude Code が Claude に Bash を通じてファイルを編集するよう指示した場合にのみ記録します。記録をオフにするには、`bashEditDiffEnabled` を `false` に設定してください。バックグラウンドのコマンドと読み取り専用のコマンドには差分は含まれません。
1751 1750
1752その後、[PostToolUse フック](#posttooluse)は `tool_response.bashEditDiff` で変更されたファイルを受け取ります。この一覧は、コマンドの実行中にリポジトリ配下で変更されたものを対象とします。Git が無視するファイルとサブモジュール内のファイルは含まれません。Claude Code v2.1.269 以降が必要です。1751その後、[PostToolUse フック](#posttooluse)は `tool_response.bashEditDiff` で変更されたファイルを受け取ります。このリストは、コマンドの実行中にリポジトリ配下で変更された内容をカバーします。Git が無視するファイルやサブモジュール内のファイルは含まれません。Claude Code v2.1.269 以降が必要です。
1753 1752
1754<Note>1753<Note>
1755 この一覧はベストエフォートであり、パブリックベータ版です。Claude Code は変更を見落としたり、同時に別のプロセスが変更したファイルを含めたり、サイズの上限で打ち切ったりすることがあります。フィールドの形式は変更される可能性があります。この一覧はレビュー対象を見つけるために使用し、ポリシーの強制には使用しないでください。1754 このリストはベストエフォートであり、パブリックベータです。Claude Code は変更を見逃したり、別のプロセスが同時に変更したファイルを含めたり、サイズ制限で打ち切ったりする場合があります。フィールドの形式は変更される可能性があります。このリストはレビュー対象を見つけるために使用し、ポリシーの強制には使用しないでください。
1756</Note>1755</Note>
1757 1756
1758`changedFiles` と `files` はコマンドが変更したものを一覧にし、残りのフィールドはその一覧がどれだけ完全で信頼できるかを示します。1757`changedFiles` と `files` はコマンドが変更した内容を列挙し、残りのフィールドはそのリストがどの程度完全で信頼できるかを示します。
1759 1758
1760| フィールド | 型 | 例 | 説明 |1759| フィールド | 型 | 例 | 説明 |
1761| :- | :- | :- | :- |1760| :- | :- | :- | :- |
1762| `changedFiles` | array | `["/path/to/src/app.ts"]` | コマンドが変更したファイルの絶対パス(最大 200 件)。`files` に差分がある場合、または `moreFiles` が 0 より大きい場合に常に含まれます |1761| `changedFiles` | array | `["/path/to/src/app.ts"]` | コマンドが変更したファイルの絶対パス(最大 200 件)。`files` に差分が含まれている場合、または `moreFiles` が 0 より大きい場合に常に存在します |
1763| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 表示用の、最大 5 つの変更ファイルの差分。コマンドが追加または削除したファイルでは `created` または `deleted` が `true` になります |1762| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 表示用の、最大 5 件の変更されたファイルの差分。コマンドが追加または削除したファイルでは、`created` または `deleted` が `true` になります |
1764| `moreFiles` | number | `2` | `files` に差分が含まれていない変更ファイルの数 |1763| `moreFiles` | number | `2` | `files` に差分が含まれていない変更されたファイルの数 |
1765| `unavailable` | boolean | `true` | 差分が不完全な場合、または取得できなかった場合に設定されます |1764| `unavailable` | boolean | `true` | 差分が不完全な場合、または取得できなかった場合に設定されます |
1766| `skipped` | boolean | `true` | `git checkout` や `git stash` など、作業ツリーを移動させる Git コマンドの場合に設定され、Claude Code は差分を取得しません |1765| `skipped` | boolean | `true` | `git checkout` や `git stash` など、作業ツリーを移動する Git コマンドの場合に設定され、Claude Code は差分を取得しません |
1767| `shared` | boolean | `true` | サブエージェントのものなど、別の Bash ツール呼び出しが同じリポジトリで同時に実行された場合に設定されます。一覧の変更の一部はそのコマンドによるものである可能性があります |1766| `shared` | boolean | `true` | サブエージェントのものなど、別の Bash ツール呼び出しが同時に同じリポジトリで実行された場合に設定されます。そのため、列挙された変更の一部はそのコマンドによるものである可能性があります |
1768 1767
1769<a id="powershell" />1768<a id="powershell" />
1770 1769
1774 1773
1775PowerShell コマンドを実行します。プラットフォームごとの利用可否については、[PowerShell ツール](/docs/ja/tools-reference#powershell-tool)を参照してください。1774PowerShell コマンドを実行します。プラットフォームごとの利用可否については、[PowerShell ツール](/docs/ja/tools-reference#powershell-tool)を参照してください。
1776 1775
1777フィールドは Bash ツールと同じで、コマンド文字列は `command` に入ります。1776フィールドは Bash ツールと同じで、コマンド文字列は `command` に含まれます。
1778 1777
1779| フィールド | 型 | 例 | 説明 |1778| フィールド | 型 | 例 | 説明 |
1780| :- | :- | :- | :- |1779| :- | :- | :- | :- |
1781| `command` | string | `"Get-ChildItem -Recurse"` | 実行する PowerShell コマンド |1780| `command` | string | `"Get-ChildItem -Recurse"` | 実行する PowerShell コマンド |
1782| `description` | string | `"List files recursively"` | コマンドの動作についての説明(省略可) |1781| `description` | string | `"List files recursively"` | コマンドの動作についての説明(オプション) |
1783| `timeout` | number | `120000` | タイムアウト(ミリ秒、省略可) |1782| `timeout` | number | `120000` | ミリ秒単位のタイムアウト(オプション) |
1784| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |1783| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |
1785 1784
1786シェルコマンドを検査するフックでは、両方のツールをカバーするように `Bash|PowerShell` で照合してください。1785シェルコマンドを検査するフックでは、両方のツールをカバーするように `Bash|PowerShell` にマッチさせてください。
1787 1786
1788* Windows では、PowerShell ツールが有効になっている環境であればどこでも、Claude は PowerShell をプライマリシェルとして扱い、シェルコマンドをそれ経由で実行します。1787* Windows では、PowerShell ツールが有効になっている環境であればどこでも、Claude は PowerShell をプライマリシェルとして扱い、シェルコマンドをそこに経由させます。
1789* Git Bash のない Windows では、このツールが自動的に有効になり、Claude Code は Bash ツールをまったく登録しません。1788* Git Bash がない Windows では、このツールは自動的に有効になり、Claude Code は Bash ツールをまったく登録しません。
1790* `Bash` のみに一致するフックは、その環境では決して発火しません。1789* `Bash` のみにマッチするフックは、そこでは決して発火しません。
1791 1790
1792<h5 id="write">1791<h5 id="write">
1793 Write1792 Write
1822| フィールド | 型 | 例 | 説明 |1821| フィールド | 型 | 例 | 説明 |
1823| :- | :- | :- | :- |1822| :- | :- | :- | :- |
1824| `file_path` | string | `"/path/to/file.txt"` | 読み取るファイルの絶対パス |1823| `file_path` | string | `"/path/to/file.txt"` | 読み取るファイルの絶対パス |
1825| `offset` | number | `10` | 読み取りを開始する行番号(省略可) |1824| `offset` | number | `10` | 読み取りを開始する行番号(オプション) |
1826| `limit` | number | `50` | 読み取る行数(省略可) |1825| `limit` | number | `50` | 読み取る行数(オプション) |
1827 1826
1828<h5 id="glob">1827<h5 id="glob">
1829 Glob1828 Glob
1834| フィールド | 型 | 例 | 説明 |1833| フィールド | 型 | 例 | 説明 |
1835| :- | :- | :- | :- |1834| :- | :- | :- | :- |
1836| `pattern` | string | `"**/*.ts"` | ファイルを照合する glob パターン |1835| `pattern` | string | `"**/*.ts"` | ファイルを照合する glob パターン |
1837| `path` | string | `"/path/to/dir"` | 検索するディレクトリ(省略可)。デフォルトは現在の作業ディレクトリです |1836| `path` | string | `"/path/to/dir"` | 検索するディレクトリ(オプション)。デフォルトは現在の作業ディレクトリです |
1838 1837
1839<h5 id="grep">1838<h5 id="grep">
1840 Grep1839 Grep
1845| フィールド | 型 | 例 | 説明 |1844| フィールド | 型 | 例 | 説明 |
1846| :- | :- | :- | :- |1845| :- | :- | :- | :- |
1847| `pattern` | string | `"TODO.*fix"` | 検索する正規表現パターン |1846| `pattern` | string | `"TODO.*fix"` | 検索する正規表現パターン |
1848| `path` | string | `"/path/to/dir"` | 検索するファイルまたはディレクトリ(省略可) |1847| `path` | string | `"/path/to/dir"` | 検索するファイルまたはディレクトリ(オプション) |
1849| `glob` | string | `"*.ts"` | ファイルを絞り込む glob パターン(省略可) |1848| `glob` | string | `"*.ts"` | ファイルを絞り込む glob パターン(オプション) |
1850| `output_mode` | string | `"content"` | `"content"`、`"files_with_matches"`、または `"count"`。デフォルトは `"files_with_matches"` です |1849| `output_mode` | string | `"content"` | `"content"`、`"files_with_matches"`、または `"count"`。デフォルトは `"files_with_matches"` です |
1851| `-i` | boolean | `true` | 大文字と小文字を区別しない検索 |1850| `-i` | boolean | `true` | 大文字と小文字を区別しない検索 |
1852| `multiline` | boolean | `false` | 複数行のマッチングを有効にする |1851| `multiline` | boolean | `false` | 複数行マッチングを有効にする |
1853 1852
1854<h5 id="webfetch">1853<h5 id="webfetch">
1855 WebFetch1854 WebFetch
1871| フィールド | 型 | 例 | 説明 |1870| フィールド | 型 | 例 | 説明 |
1872| :- | :- | :- | :- |1871| :- | :- | :- | :- |
1873| `query` | string | `"react hooks best practices"` | 検索クエリ |1872| `query` | string | `"react hooks best practices"` | 検索クエリ |
1874| `allowed_domains` | array | `["docs.example.com"]` | 省略可:これらのドメインの結果のみを含める |1873| `allowed_domains` | array | `["docs.example.com"]` | オプション:これらのドメインの結果のみを含める |
1875| `blocked_domains` | array | `["spam.example.com"]` | 省略可:これらのドメインの結果を除外する |1874| `blocked_domains` | array | `["spam.example.com"]` | オプション:これらのドメインの結果を除外する |
1876 1875
1877<h5 id="agent">1876<h5 id="agent">
1878 Agent1877 Agent
1884| :- | :- | :- | :- |1883| :- | :- | :- | :- |
1885| `prompt` | string | `"Find all API endpoints"` | エージェントが実行するタスク |1884| `prompt` | string | `"Find all API endpoints"` | エージェントが実行するタスク |
1886| `description` | string | `"Find API endpoints"` | タスクの短い説明 |1885| `description` | string | `"Find API endpoints"` | タスクの短い説明 |
1887| `subagent_type` | string | `"Explore"` | 使用する特化型エージェントの種類 |1886| `subagent_type` | string | `"Explore"` | 使用する専門エージェントの種類 |
1888| `model` | string | `"sonnet"` | デフォルトを上書きするモデルエイリアス(省略可) |1887| `model` | string | `"sonnet"` | デフォルトを上書きするモデルエイリアス(オプション) |
1889 1888
1890フォアグラウンドの Agent 呼び出しが完了すると、[PostToolUse フック](#posttooluse)は `tool_response` でサブエージェントの結果と実行のテレメトリを受け取ります。実行を調べるにはこれらのフィールドを読んでください。`totalTokens` と `usage` は最後のリクエストのみを対象とするため、サブエージェント全体のトークンとコストの集計には、`query_source` が `"subagent"` で絞り込んだ[トークンとコストのカウンター](/docs/ja/monitoring-usage#token-counter)を使用してください。1889フォアグラウンドの Agent 呼び出しが完了すると、[PostToolUse フック](#posttooluse)は `tool_response` でサブエージェントの結果と実行のテレメトリを受け取ります。これらのフィールドを読み取って実行内容を検査してください。`totalTokens` と `usage` は最後のリクエストのみを対象としているため、サブエージェント全体のトークンとコストの集計には、`query_source` を `"subagent"` で絞り込んだ[トークンとコストのカウンター](/docs/ja/monitoring-usage#token-counter)を使用してください。
1891 1890
1892| フィールド | 型 | 例 | 説明 |1891| フィールド | 型 | 例 | 説明 |
1893| :- | :- | :- | :- |1892| :- | :- | :- | :- |
1894| `status` | string | `"completed"` | フォアグラウンドのサブエージェントでは `"completed"`、バックグラウンドのサブエージェントでは `"async_launched"`。サブエージェントはデフォルトでバックグラウンドで実行されるため、`run_in_background` を省略した Agent 呼び出しも `"async_launched"` になります |1893| `status` | string | `"completed"` | フォアグラウンドのサブエージェントでは `"completed"`、バックグラウンドのサブエージェントでは `"async_launched"`。サブエージェントはデフォルトでバックグラウンドで実行されるため、`run_in_background` を省略した Agent 呼び出しでも `"async_launched"` になります |
1895| `agentId` | string | `"a4d2c8f1e0b3a297"` | サブエージェントの実行の識別子 |1894| `agentId` | string | `"a4d2c8f1e0b3a297"` | サブエージェントの実行の識別子 |
1896| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | サブエージェントの最終的なテキストブロック。レポートが `SubagentHandback` を経由するサブエージェントの場合は、代わりにその引き渡しについての短い注記 |1895| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | サブエージェントの最終テキストブロック。レポートが `SubagentHandback` を経由するサブエージェントの場合は、その代わりにその引き渡しについての短い注記 |
1897| `resolvedModel` | string | `"claude-sonnet-4-5"` | サブエージェントが開始時に使用したモデル。要求されたモデルと異なる場合があります |1896| `resolvedModel` | string | `"claude-sonnet-4-5"` | サブエージェントが開始時に使用したモデル。要求されたモデルと異なる場合があります |
1898| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | 使用されたモデルの順序(連続する重複はまとめられます)。実行中にモデルが切り替えられた場合にのみ設定されます。Claude Code v2.1.212 以降が必要です |1897| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | 使用されたモデルを順番に並べたもの(連続する重複はまとめられます)。実行中にモデルが切り替えられた場合にのみ設定されます。Claude Code v2.1.212 以降が必要です |
1899| `totalTokens` | number | `12450` | サブエージェントの最後の API リクエストのトークン数(入力、出力、キャッシュのトークンの合計)。実行全体の合計ではありません |1898| `totalTokens` | number | `12450` | サブエージェントの最後の API リクエストのトークン数(入力、出力、キャッシュのトークンの合計)。実行全体の合計ではありません |
1900| `totalDurationMs` | number | `48211` | サブエージェントの実行にかかった実時間 |1899| `totalDurationMs` | number | `48211` | サブエージェントの実行の実時間 |
1901| `totalToolUseCount` | number | `7` | サブエージェントが行ったツール呼び出しの数 |1900| `totalToolUseCount` | number | `7` | サブエージェントが行ったツール呼び出しの数 |
1902| `usage` | object | `{"input_tokens": 8320, ...}` | 最後の API リクエストの種類別トークン内訳:`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |1901| `usage` | object | `{"input_tokens": 8320, ...}` | 最後の API リクエストの種類別のトークン内訳:`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |
1903 1902
1904Claude Code v2.1.271 以降では、[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)で Claude Code が提供する [`SubagentHandback`](/docs/ja/tools-reference) ツールを使って実行されるサブエージェントは、レポートをテキストとして返すのではなく、そのツールを通じて届けます。その場合、`completed` 結果の `content` フィールドには、レポート自体ではなく、その引き渡しについての短い注記が含まれます。レポートを読むには、`SubagentHandback` に一致する `PreToolUse` または `PostToolUse` フックを設定し、`tool_input.message` を読み取ってください。1903Claude Code v2.1.271 以降では、Claude Code が [auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)で提供する [`SubagentHandback`](/docs/ja/tools-reference) ツールを使って実行されるサブエージェントは、レポートをテキストとして返すのではなく、そのツールを通じて渡します。その場合、`completed` の結果の `content` フィールドには、レポート自体ではなく、その引き渡しについての短い注記が含まれます。レポートを読み取るには、`SubagentHandback` にマッチする `PreToolUse` または `PostToolUse` フックで `tool_input.message` を読み取ってください。
1905 1904
1906バックグラウンドのサブエージェントの場合、ツールはタスクがバックグラウンドに移った時点で返るため、`tool_response` には使用量のフィールドが含まれません。バックグラウンドでの起動はすぐに返り、Claude Code が実行中にバックグラウンドへ移したフォアグラウンドのタスクはその移行の時点で返ります。`status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile`、`resolvedModel` を持ちます。1905バックグラウンドのサブエージェントの場合、ツールはタスクがバックグラウンドに移動した時点で戻るため、`tool_response` には使用量のフィールドは含まれません。バックグラウンドでの起動はすぐに戻り、Claude Code が実行中にバックグラウンドに移したフォアグラウンドのタスクはその移行時点で戻ります。このレスポンスには、`status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile`、`resolvedModel` が含まれます。
1907 1906
1908`completed` の応答では、`resolvedModel` はサブエージェントが開始時に使用したモデルを示します。これは、`availableModels` や他の上書きが適用される場合など、`tool_input` の `model` の値と異なることがあります。`async_launched` の応答では、`resolvedModel` はエージェントがバックグラウンドに移った時点で使用していたモデルを示すため、バックグラウンドに移る前に行われた切り替えがそこに反映されます。`modelsUsed` と、バックグラウンド移行時の `resolvedModel` の動作には Claude Code v2.1.212 以降が必要です。1907`completed` のレスポンスでは、`resolvedModel` はサブエージェントが開始時に使用したモデルを示します。これは、`availableModels` やその他の上書きが適用される場合など、`tool_input` の `model` の値と異なることがあります。`async_launched` のレスポンスでは、`resolvedModel` はエージェントがバックグラウンドに移動した時点で使用されていたモデルを示すため、バックグラウンドへの移行前に行われた切り替えはそこに反映されます。`modelsUsed` と、バックグラウンド移行時点の `resolvedModel` の動作には Claude Code v2.1.212 以降が必要です。
1909 1908
1910<a id="askuserquestion" />1909<a id="askuserquestion" />
1911 1910
1917 1916
1918| フィールド | 型 | 例 | 説明 |1917| フィールド | 型 | 例 | 説明 |
1919| :- | :- | :- | :- |1918| :- | :- | :- | :- |
1920| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | 提示する質問。それぞれ `question` 文字列、短い `header`、`options` 配列、オプションの `multiSelect` フラグを持ちます |1919| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | 提示する質問。それぞれに `question` 文字列、短い `header`、`options` 配列、オプションの `multiSelect` フラグがあります |
1921| `answers` | object | `{"Which framework?": "React"}` | 省略可。質問のテキストを選択されたオプションのラベルに対応付けます。複数選択の回答は、ラベルをカンマで連結します。Claude はこのフィールドを設定しません。プログラムで回答するには `updatedInput` 経由で指定してください |1920| `answers` | object | `{"Which framework?": "React"}` | オプション。質問のテキストを選択されたオプションのラベルに対応付けます。複数選択の回答は、ラベルをカンマで連結します。Claude はこのフィールドを設定しません。プログラムで回答するには、`updatedInput` を通じて指定してください |
1922 1921
1923<h5 id="exitplanmode">1922<h5 id="exitplanmode">
1924 ExitPlanMode1923 ExitPlanMode
1925</h5>1924</h5>
1926 1925
1927Claude が [plan モード](/docs/ja/permission-modes#analyze-before-you-edit-with-plan-mode)を終了する前に、計画を提示してユーザーに承認を求めます。Claude はツールを呼び出す前に計画をディスク上のファイルに書き込むため、モデルからの `tool_input` そのものは通常空です。Claude Code は、入力をフックに渡す前に計画の内容とファイルパスを挿入します。1926Claude が [plan モード](/docs/ja/permission-modes#analyze-before-you-edit-with-plan-mode)を終了する前に、計画を提示してユーザーに承認を求めます。Claude はツールを呼び出す前に計画をディスク上のファイルに書き込むため、モデルからの実際の `tool_input` は通常空です。Claude Code は、入力をフックに渡す前に計画の内容とファイルパスを挿入します。
1928 1927
1929| フィールド | 型 | 例 | 説明 |1928| フィールド | 型 | 例 | 説明 |
1930| :- | :- | :- | :- |1929| :- | :- | :- | :- |
1931| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 形式の計画の内容。ディスク上の計画ファイルから挿入されます |1930| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 形式の計画の内容。ディスク上の計画ファイルから挿入されます |
1932| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 計画ファイルのパス。挿入されます |1931| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 計画ファイルのパス。挿入されます |
1933| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 非推奨。Claude Code はこのフィールドを受け付けますが、無視します。v2.1.205 より前は、計画を実行するために Claude が要求したプロンプトベースの権限を保持していました |1932| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 非推奨。Claude Code はこのフィールドを受け付けますが無視します。v2.1.205 より前は、Claude が計画を実装するために要求したプロンプトベースの権限を保持していました |
1934 1933
1935`PostToolUse` では、`tool_response` は承認された計画を保持する `plan` と `filePath` のフィールドに加えて、内部のステータスフラグを持つオブジェクトです。計画の内容は、ディスクからファイルを読み直すのではなく、`tool_response.plan` から読み取ってください。1934`PostToolUse` では、`tool_response` は承認された計画を保持する `plan` と `filePath` フィールド、および内部のステータスフラグを持つオブジェクトです。計画の内容は、ディスクからファイルを再度読み取るのではなく、`tool_response.plan` から読み取ってください。
1936 1935
1937<h4 id="pretooluse-decision-control">1936<h4 id="pretooluse-decision-control">
1938 PreToolUse の判定制御1937 PreToolUse の判定制御
1939</h4>1938</h4>
1940 1939
1941`PreToolUse` フックは、ツール呼び出しを続行するかどうかを制御できます。トップレベルの `decision` フィールドを使用する他のフックとは異なり、PreToolUse は `hookSpecificOutput` オブジェクト内で判定を返します。これにより、より細かな制御が可能になります。4 つの結果(許可、拒否、確認、延期)に加えて、実行前にツールの入力を変更できます。1940`PreToolUse` フックは、ツール呼び出しを続行するかどうかを制御できます。トップレベルの `decision` フィールドを使用する他のフックとは異なり、PreToolUse は `hookSpecificOutput` オブジェクト内で判定を返します。これにより、4 つの結果(allow、deny、ask、defer)に加えて、実行前にツールの入力を変更する機能という、より豊富な制御が可能になります。
1942 1941
1943| フィールド | 説明 |1942| フィールド | 説明 |
1944| :- | :- |1943| :- | :- |
1945| `permissionDecision` | `"allow"` は権限プロンプトをスキップします。ただし、[どのモードでも自動承認されないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves)と、[`updatedInput` との組み合わせ](#allow-with-updatedinput)が必要な `AskUserQuestion` と `ExitPlanMode` は除きます。`"deny"` はツール呼び出しを防ぎます。`"ask"` はユーザーに確認を求めます。`"defer"` は、ツールを後で再開できるように正常に終了します。フックが何を返しても、[拒否ルールと確認ルール](/docs/ja/permissions#manage-permissions)は引き続き評価されます |1944| `permissionDecision` | `"allow"` は権限プロンプトをスキップします。ただし、[どのモードでも自動承認されないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves)と、[`updatedInput` との組み合わせ](#allow-with-updatedinput)が必要な `AskUserQuestion` および `ExitPlanMode` は除きます。`"deny"` はツール呼び出しを防ぎます。`"ask"` はユーザーに確認を求めます。`"defer"` は、後でツールを再開できるように正常に終了します。フックが何を返しても、[拒否ルールと確認ルール](/docs/ja/permissions#manage-permissions)は引き続き評価されます |
1946| `permissionDecisionReason` | `"ask"` の場合、権限プロンプトでユーザーに表示されます。誰もそのプロンプトに応答できない `-p` の実行で Claude Code が[呼び出しを拒否する](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)場合は、代わりに Claude がツール結果でその理由を読みます。`"deny"` の場合、Claude に表示されます。`"allow"` と `"defer"` の場合、[デバッグログ](#debug-hooks)にのみ書き込まれます |1945| `permissionDecisionReason` | `"ask"` の場合、権限プロンプトでユーザーに表示されます。誰もそのプロンプトに回答できない `-p` の実行で Claude Code が[呼び出しを拒否する](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)場合は、代わりに Claude がツールの結果でその理由を読み取ります。`"deny"` の場合は Claude に表示されます。`"allow"` と `"defer"` の場合は、[デバッグログ](#debug-hooks)にのみ書き込まれます |
1947| `updatedInput` | 実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。Claude Code は、権限ルールと Bash コマンドの[自動バックグラウンド化の対象かどうか](/docs/ja/tools-reference#foreground-commands-that-move-to-the-background)を、Claude が送信した入力ではなく、フックが返した入力に対して評価します。自動承認するには `"allow"` と、変更した入力をユーザーに表示するには `"ask"` と組み合わせます。`"defer"` の場合は無視されます |1946| `updatedInput` | 実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。Claude Code は、権限ルールと Bash コマンドの[自動バックグラウンド化の適格性](/docs/ja/tools-reference#foreground-commands-that-move-to-the-background)を、Claude が送信した入力ではなく、フックが返した入力に対して評価します。自動承認するには `"allow"` と、変更された入力をユーザーに表示するには `"ask"` と組み合わせます。`"defer"` の場合は無視されます |
1948| `additionalContext` | ツールの結果とともに Claude のコンテキストに追加される文字列。`permissionDecision` が `"defer"` の場合は無視されます。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |1947| `additionalContext` | ツールの結果とともに Claude のコンテキストに追加される文字列。`permissionDecision` が `"defer"` の場合は無視されます。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1949 1948
1950複数の PreToolUse フックが異なる判定を返した場合、優先順位は `deny` > `defer` > `ask` > `allow` です。1949複数の PreToolUse フックが異なる判定を返した場合、優先順位は `deny` > `defer` > `ask` > `allow` です。
1951 1950
1952終了コード 2 で終了してブロックするフックは、`"deny"` と同じ経路をたどります。Claude は stderr のメッセージを拒否の理由として受け取ります。1951終了コード 2 で終了してブロックするフックは、`"deny"` と同じ方法で処理されます。Claude は標準エラー出力のメッセージを拒否理由として受け取ります。
1953 1952
1954フックが `"ask"` を返すと、ユーザーに表示される権限プロンプトには、フックの出どころを示すラベルが含まれます。任意の設定ファイルまたはエージェントのフロントマターからのフックでは `[settings]`、プラグインのフックでは `[plugin:<name>]`、スキルのフロントマターからのフックでは `[skill]` です。これにより、どの設定ソースが確認を求めているかをユーザーが理解しやすくなります。1953フックが `"ask"` を返すと、ユーザーに表示される権限プロンプトには、フックの出所を示すラベルが含まれます。任意の設定ファイルまたはエージェントのフロントマターからのフックには `[settings]`、プラグインのフックには `[plugin:<name>]`、スキルのフロントマターからのフックには `[skill]` が表示されます。これにより、ユーザーはどの設定ソースが確認を求めているかを把握できます。
1955 1954
1956フックの `"ask"` は、[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)でも権限プロンプトを強制します。分類器は引き続きツール呼び出しを拒否できますが、呼び出しを黙って承認することはできません。v2.1.211 より前は、分類器は[サンドボックス](/docs/ja/sandboxing)外で実行される Bash コマンドを、フックが要求したプロンプトを表示せずに承認できました。その場合も分類器はそのコマンドに独自の安全ルールを適用しており、フックの `"deny"` は常に尊重されていました。1955フックの `"ask"` は、[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)でも権限プロンプトを強制します。分類器はツール呼び出しを拒否することはできますが、暗黙的に承認することはできません。v2.1.211 より前は、分類器は[サンドボックス](/docs/ja/sandboxing)の外で実行される Bash コマンドを、フックが要求したプロンプトを表示せずに承認できました。その場合でも分類器はそのコマンドに独自の安全ルールを適用しており、フックの `"deny"` は常に尊重されていました。
1957 1956
1958```json theme={null}1957```json theme={null}
1959{1958{
1970```1969```
1971 1970
1972<Note>1971<Note>
1973 PreToolUse では以前はトップレベルの `decision` と `reason` フィールドを使用していましたが、これらはこのイベントでは非推奨です。代わりに `hookSpecificOutput.permissionDecision` と `hookSpecificOutput.permissionDecisionReason` を使用してください。非推奨の値 `"approve"` と `"block"` は、それぞれ `"allow"` と `"deny"` に対応します。PostToolUse や Stop などの他のイベントでは、引き続きトップレベルの `decision` と `reason` が現在の形式として使用されます。1972 PreToolUse では以前トップレベルの `decision` と `reason` フィールドを使用していましたが、このイベントではこれらは非推奨です。代わりに `hookSpecificOutput.permissionDecision` と `hookSpecificOutput.permissionDecisionReason` を使用してください。非推奨の値 `"approve"` と `"block"` は、それぞれ `"allow"` と `"deny"` に対応します。PostToolUse や Stop などの他のイベントでは、引き続きトップレベルの `decision` と `reason` が現在の形式として使用されます。
1974</Note>1973</Note>
1975 1974
1976<h4 id="allow-with-updatedinput">1975<h4 id="allow-with-updatedinput">
1977 ユーザーの操作を必要とするツール1976 ユーザーの操作を必要とするツール
1978</h4>1977</h4>
1979 1978
1980`AskUserQuestion` と `ExitPlanMode` はユーザーの操作を必要とします。`-p` フラグを使用した[非対話モード](/docs/ja/headless)では、Agent SDK の `canUseTool` コールバックなど、プロンプトを受け取る[権限ホスト](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)が実行にある場合にのみ、Claude Code はこれらのツールを提供します。1979`AskUserQuestion` と `ExitPlanMode` はユーザーの操作を必要とします。`-p` フラグを使用した[非対話モード](/docs/ja/headless)では、Claude Code は、Agent SDK の `canUseTool` コールバックなど、プロンプトを受け取る[権限ホスト](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)が実行にある場合にのみ、これらのツールを提供します。
1981 1980
1982`PreToolUse` フックは、次のことを行う場合にその要件を満たします。1981`PreToolUse` フックは、次のことを行う場合にその要件を満たします。
1983 1982
19841. stdin からツールの入力を読み取る19831. 標準入力からツールの入力を読み取る
19852. 独自の UI を通じて回答を収集する19842. 独自の UI を通じて回答を収集する
19863. 回答を保持する `updatedInput` とともに `permissionDecision: "allow"` を返し、プロンプトを表示せずにツールが実行されるようにする19853. 回答を保持する `updatedInput` とともに `permissionDecision: "allow"` を返し、ツールがプロンプトなしで実行されるようにする
1987 1986
1988これらのツールでは、`"allow"` を返すだけでは不十分です。1987これらのツールでは、`"allow"` を返すだけでは不十分です。
1989 1988
1990`AskUserQuestion` の場合は、元の `questions` 配列をそのまま返し、各質問のテキストを選択された回答に対応付ける [`answers`](#askuserquestion) オブジェクトを追加します。次の出力は、1 つの質問に `React` と回答します。1989`AskUserQuestion` の場合は、元の `questions` 配列をそのまま返し、各質問のテキストを選択された回答に対応付ける [`answers`](#askuserquestion) オブジェクトを追加します。次の出力は、1 つの質問に `React` と回答しています。
1991 1990
1992```json theme={null}1991```json theme={null}
1993{1992{
2009}2008}
2010```2009```
2011 2010
2012サーバーが [`_meta["anthropic/requiresUserInteraction"]`](/docs/ja/mcp#require-approval-for-a-specific-tool) でマークした MCP ツールはさらに厳格です。フックは `updatedInput` の有無にかかわらず、`"allow"` でその承認プロンプトをスキップすることはできません。ツールが必要とする操作をフックが収集したことを Claude Code が確認できないためです。2011サーバーが [`_meta["anthropic/requiresUserInteraction"]`](/docs/ja/mcp#require-approval-for-a-specific-tool) でマークした MCP ツールはより厳格です。Claude Code はフックがツールに必要な操作を収集したことを確認できないため、`updatedInput` の有無にかかわらず、フックは `"allow"` でその承認プロンプトをスキップできません。
2013 2012
2014<h4 id="defer-a-tool-call-for-later">2013<h4 id="defer-a-tool-call-for-later">
2015 ツール呼び出しを後で実行するために延期する2014 ツール呼び出しを後で処理するために遅延させる
2016</h4>2015</h4>
2017 2016
2018`"defer"` は、Agent SDK アプリや Claude Code 上に構築したカスタム UI など、`claude -p` をサブプロセスとして実行し、その JSON 出力を読み取るインテグレーション向けです。これにより、呼び出し元のプロセスは Claude をツール呼び出しの時点で一時停止し、独自のインターフェースで入力を収集して、中断した場所から再開できます。Claude Code がこの値を尊重するのは、`-p` フラグを使った[非対話モード](/docs/ja/headless)のみです。対話セッションでは警告をログに記録し、フックの結果を無視します。2017`"defer"` は、Agent SDK アプリや Claude Code 上に構築したカスタム UI など、`claude -p` をサブプロセスとして実行し、その JSON 出力を読み取るインテグレーション向けです。これにより、呼び出し元のプロセスはツール呼び出しの時点で Claude を一時停止し、独自のインターフェースを通じて入力を収集し、中断したところから再開できます。Claude Code がこの値を尊重するのは、`-p` フラグを使用した[非対話モード](/docs/ja/headless)の場合のみです。対話セッションでは警告をログに記録し、フックの結果を無視します。
2019 2018
2020典型的なケースは `AskUserQuestion` ツールです。Claude はユーザーに何かを尋ねたいのに、回答するためのターミナルがありません。`-p` の実行では、`--permission-prompt-tool` で渡す MCP ツールなどの[権限ホスト](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)がある場合にのみ `AskUserQuestion` が提供されるため、権限ホストを指定して実行を開始してください。往復の流れは次のとおりです。2019典型的なケースは `AskUserQuestion` ツールです。Claude はユーザーに何かを尋ねたいものの、回答するためのターミナルがありません。`-p` の実行では、`--permission-prompt-tool` で渡す MCP ツールなどの[権限ホスト](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)がある場合にのみ `AskUserQuestion` が提供されるため、権限ホストを指定して実行を開始してください。往復の流れは次のとおりです。
2021 2020
20221. Claude が `AskUserQuestion` を呼び出します。`PreToolUse` フックが発火します。20211. Claude が `AskUserQuestion` を呼び出します。`PreToolUse` フックが発火します。
20232. フックが `permissionDecision: "defer"` を返します。ツールは実行されません。プロセスは `stop_reason: "tool_deferred"` で終了し、保留中のツール呼び出しはトランスクリプトに保存されます。20222. フックが `permissionDecision: "defer"` を返します。ツールは実行されません。プロセスは `stop_reason: "tool_deferred"` で終了し、保留中のツール呼び出しはトランスクリプトに保存されます。
20243. 呼び出し元のプロセスは SDK の結果から `deferred_tool_use` を読み取り、独自の UI で質問を表示して回答を待ちます。20233. 呼び出し元のプロセスが SDK の結果から `deferred_tool_use` を読み取り、独自の UI に質問を表示して回答を待ちます。
20254. 呼び出し元のプロセスは、同じ権限ホストを指定して `claude -p --resume <session-id>` を実行します。同じツール呼び出しで再び `PreToolUse` が発火します。20244. 呼び出し元のプロセスが同じ権限ホストを指定して `claude -p --resume <session-id>` を実行します。同じツール呼び出しが再び `PreToolUse` を発火させます。
20265. フックは `updatedInput` に回答を入れて `permissionDecision: "allow"` を返します。ツールが実行され、Claude は処理を続けます。20255. フックが `updatedInput` に回答を含めて `permissionDecision: "allow"` を返します。ツールが実行され、Claude が処理を続行します。
2027 2026
2028`deferred_tool_use` フィールドには、ツールの `id`、`name`、`input` が含まれます。`input` は、Claude がツール呼び出しのために生成したパラメーターで、実行前に取得されたものです。2027`deferred_tool_use` フィールドには、ツールの `id`、`name`、`input` が含まれます。`input` は、Claude がツール呼び出しのために生成したパラメーターで、実行前に取得されたものです。
2029 2028
2041}2040}
2042```2041```
2043 2042
2044タイムアウトや再試行の上限はありません。セッションは再開するまでディスク上に残りますが、[`cleanupPeriodDays`](/docs/ja/settings-reference#cleanupperioddays) の保持期間による削除の対象となります。この削除は、[保持期間の削除ルール](/docs/ja/claude-directory#cleaned-up-automatically)に従い、デフォルトでは 30 日後にセッションファイルを削除します。再開時に回答の準備ができていない場合、フックは再び `"defer"` を返すことができ、プロセスは同じ方法で終了します。呼び出し元のプロセスは、最終的にフックから `"allow"` または `"deny"` を返すことで、いつループを抜けるかを制御します。2043タイムアウトや再試行の上限はありません。セッションは再開するまでディスク上に残りますが、[`cleanupPeriodDays`](/docs/ja/settings-reference#cleanupperioddays) の保持期間によるクリーンアップの対象となります。このクリーンアップは、[保持期間によるクリーンアップのルール](/docs/ja/claude-directory#cleaned-up-automatically)に従い、デフォルトで 30 日後にセッションファイルを削除します。再開時に回答の準備ができていない場合、フックは再び `"defer"` を返すことができ、プロセスは同じ方法で終了します。呼び出し元のプロセスは、最終的にフックから `"allow"` または `"deny"` を返すことで、ループを抜けるタイミングを制御します。
2045 2044
2046`"defer"` は、Claude がそのターンで単一のツール呼び出しを行う場合にのみ機能します。Claude が複数のツール呼び出しを一度に行う場合、`"defer"` は警告とともに無視され、ツールは通常の権限フローで処理されます。この制約は、再開時に再実行できるツールが 1 つだけだからです。バッチ内の 1 つの呼び出しだけを延期すると、他の呼び出しが未解決のまま残ってしまいます。2045`"defer"` は、Claude がターン内で単一のツール呼び出しを行う場合にのみ機能します。Claude が一度に複数のツール呼び出しを行う場合、`"defer"` は警告とともに無視され、ツールは通常の権限フローで処理されます。この制約は、再開時には 1 つのツールしか再実行できないために存在します。他の呼び出しを未解決のままにせずに、バッチの中から 1 つの呼び出しだけを遅延させる方法はありません。
2047 2046
2048再開時に延期されたツールが利用できなくなっている場合、プロセスはフックが発火する前に `stop_reason: "tool_deferred_unavailable"` と `is_error: true` で終了します。これは、ツールを提供していた MCP サーバーが再開されたセッションで接続されていない場合に発生します。`deferred_tool_use` ペイロードは引き続き含まれるため、どのツールが失われたかを特定できます。2047再開時に遅延されたツールが利用できなくなっている場合、プロセスはフックが発火する前に `stop_reason: "tool_deferred_unavailable"` と `is_error: true` で終了します。これは、ツールを提供していた MCP サーバーが再開されたセッションで接続されていない場合に発生します。どのツールが見つからなくなったかを特定できるように、`deferred_tool_use` ペイロードは引き続き含まれます。
2049 2048
2050<Note>2049<Note>
2051 延期されたセッションを plan モードで再開するには、Claude Code が承認のために計画を提示できるよう、`--resume` とともに [`--permission-prompt-tool`](/docs/ja/cli-reference#cli-flags) を渡してください。特定の他の起動フラグを渡すと、再開された実行は plan モードに戻りません。[`-p` で plan モードで再開する](/docs/ja/sessions#resume-in-plan-mode-with-p)を参照してください。Claude Code v2.1.246 以降が必要です。2050 遅延されたセッションを plan モードで再開するには、Claude Code が承認のために計画を提示できるよう、`--resume` とともに [`--permission-prompt-tool`](/docs/ja/cli-reference#cli-flags) を渡してください。特定の他の起動フラグを渡すと、再開された実行は plan モードに戻りません。[`-p` で plan モードで再開する](/docs/ja/sessions#resume-in-plan-mode-with-p)を参照してください。Claude Code v2.1.246 以降が必要です。
2052 2051
2053 `-p` で再開する場合、Claude Code は他の保存された権限モードを復元しません。新しい `claude -p` の実行が開始する権限モードで実行を開始するため、延期されたセッションで `--permission-mode` や `--dangerously-skip-permissions` を使用していた場合は、再度渡してください。`-p` なしで `claude --resume <session-id>` を使って再開する場合、Claude Code は保存された権限モードを復元します。例外は[再開時の権限モード](/docs/ja/sessions#permission-mode-on-resume)に記載されています。2052 `-p` で再開する場合、Claude Code はそれ以外の保存された権限モードを復元しません。新しい `claude -p` の実行が開始する権限モードで実行を開始するため、遅延されたセッションで `--permission-mode` または `--dangerously-skip-permissions` を使用していた場合は、再度渡してください。`-p` なしで `claude --resume <session-id>` を使って再開する場合、Claude Code は保存された権限モードを復元します。例外については[再開時の権限モード](/docs/ja/sessions#permission-mode-on-resume)に記載されています。
2054</Note>2053</Note>
2055 2054
2056<h3 id="permissionrequest">2055<h3 id="permissionrequest">
2057 PermissionRequest2056 PermissionRequest
2058</h3>2057</h3>
2059 2058
2060Claude Code がツールを使用するための権限をユーザーに求めようとしているときに実行されます。[非対話モード](/docs/ja/headless)のバックグラウンドのサブエージェントなど、プロンプトを表示できないセッションでも、Claude Code はこれらのフックを実行し、どのフックも判定を返さない場合はツール呼び出しを拒否します。`--permission-prompt-tool` または Agent SDK の [`canUseTool` コールバック](/docs/ja/agent-sdk/permissions)に到達する呼び出しの場合、フックはホストと並行して実行され、先に判定したほうが適用されます。2059Claude Code がツールの使用について権限を求めようとするときに実行されます。[非対話モード](/docs/ja/headless)のバックグラウンドのサブエージェントなど、プロンプトを表示できないセッションでも、Claude Code はこれらのフックを実行し、どのフックも判定を返さない場合はツール呼び出しを拒否します。`--permission-prompt-tool` または Agent SDK の [`canUseTool` コールバック](/docs/ja/agent-sdk/permissions)に到達する呼び出しでは、フックはホストと並行して実行され、先に判定したほうが適用されます。
2061[PermissionRequest の判定制御](#permissionrequest-decision-control)を使用して、ユーザーに代わって許可または拒否します。2060ユーザーに代わって許可または拒否するには、[PermissionRequest の判定制御](#permissionrequest-decision-control)を使用します。
2062 2061
2063Claude がツールを使用するための権限を求めた瞬間にシグナルが必要な場合に、このイベントを使用します。Claude Code が `permission_prompt` タイプの [Notification](#notification) フックを実行するのは、プロンプトが約 6 秒間待機した後です。2062Claude がツールの使用について権限を求めた瞬間にシグナルが必要な場合は、このイベントを使用してください。Claude Code が `permission_prompt` タイプの [Notification](#notification) フックを実行するのは、プロンプトが約 6 秒待機した後です。
2064 2063
2065Claude Code は、サンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)に対しては PermissionRequest フックを実行しません。そのプロンプトのシグナルを得るには、`permission_prompt` 通知タイプを使用してください。2064Claude Code は、サンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)に対しては PermissionRequest フックを実行しません。そのプロンプトのシグナルを受け取るには、`permission_prompt` 通知タイプを使用してください。
2066 2065
2067ツール名に対して照合し、値は PreToolUse と同じです。2066PreToolUse と同じ値で、ツール名に対してマッチします。
2068 2067
2069<h4 id="permissionrequest-input">2068<h4 id="permissionrequest-input">
2070 PermissionRequest の入力2069 PermissionRequest の入力
2071</h4>2070</h4>
2072 2071
2073PermissionRequest フックは、PreToolUse フックと同様に `tool_name` と `tool_input` フィールドを受け取りますが、`tool_use_id` は含まれません。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。省略可能な `permission_suggestions` 配列には、許可ルールの追加や権限モードの変更など、このリクエストに対して Claude Code が提案する[権限の更新](#permission-update-entries)が含まれます。2072PermissionRequest フックは、PreToolUse フックと同様に `tool_name` と `tool_input` フィールドを受け取りますが、`tool_use_id` は受け取りません。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。オプションの `permission_suggestions` 配列には、許可ルールの追加や権限モードの変更など、Claude Code がこのリクエストに対して提案する[権限の更新](#permission-update-entries)が含まれます。
2074 2073
2075各権限ダイアログは独自のオプションを構築するため、`permission_suggestions` 配列は表示されるオプションの正確な一覧ではありません。ファイル編集用のダイアログなど、一部のダイアログはこの配列をまったく読み取らず、リクエスト自体からオプションを導き出します。配列を読み取るダイアログでも、提案が配列に残っているオプションを表示しないことがあります。たとえば、[`allowManagedPermissionRulesOnly`](/docs/ja/settings-reference#allowmanagedpermissionrulesonly) がルールを保存するオプションを非表示にする場合です。また、[**Yes, and switch to auto mode**](/docs/ja/permission-modes#switch-permission-modes) のように、提案エントリを持たないオプションを提示することもあります。このオプションは、権限の更新を介さずに権限モードを直接変更します。2074`permission_suggestions` 配列は、表示されるオプションの正確なリストではありません。各権限ダイアログは独自のオプションを構築するためです。ファイル編集用のダイアログなど、一部のダイアログはこの配列をまったく読み取らず、リクエスト自体からオプションを導き出します。配列を読み取るダイアログでも、提案が配列に残っているオプションを表示しないことがあります。たとえば、[`allowManagedPermissionRulesOnly`](/docs/ja/settings-reference#allowmanagedpermissionrulesonly) によってルールを保存するオプションが非表示になる場合です。また、[**Yes, and switch to auto mode**](/docs/ja/permission-modes#switch-permission-modes) のように、提案エントリを持たないオプションを提供することもあります。このオプションは、権限の更新を経由せずに権限モードを直接変更します。
2076 2075
2077PreToolUse フックは、権限が必要かどうかにかかわらず、すべてのツール呼び出しの前に実行されます。PermissionRequest フックは、Claude Code が権限をユーザーに求めようとしているとき、またはプロンプトを表示できない呼び出しを本来なら自動拒否するときにのみ実行されます。どちらのイベントも [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) では発火しません。2076PreToolUse フックは、権限が必要かどうかにかかわらず、すべてのツール呼び出しの前に実行されます。PermissionRequest フックは、Claude Code が権限を求めようとするとき、またはプロンプトを表示できない呼び出しを自動的に拒否しようとするときにのみ実行されます。どちらのイベントも [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) に対しては発火しません。
2078 2077
2079```json theme={null}2078```json theme={null}
2080{2079{
2109| :- | :- |2108| :- | :- |
2110| `behavior` | `"allow"` は権限を付与し、`"deny"` は拒否します。[拒否ルールと確認ルール](/docs/ja/permissions#manage-permissions)は引き続き評価されるため、`"allow"` を返すフックが一致する拒否ルールを上書きすることはありません |2109| `behavior` | `"allow"` は権限を付与し、`"deny"` は拒否します。[拒否ルールと確認ルール](/docs/ja/permissions#manage-permissions)は引き続き評価されるため、`"allow"` を返すフックが一致する拒否ルールを上書きすることはありません |
2111| `updatedInput` | `"allow"` の場合のみ:実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。変更された入力は、拒否ルールと確認ルールに対して再評価されます |2110| `updatedInput` | `"allow"` の場合のみ:実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。変更された入力は、拒否ルールと確認ルールに対して再評価されます |
2112| `updatedPermissions` | `"allow"` の場合のみ:適用する[権限の更新エントリ](#permission-update-entries)の配列。許可ルールの追加やセッションの権限モードの変更などです |2111| `updatedPermissions` | `"allow"` の場合のみ:適用する[権限の更新エントリ](#permission-update-entries)の配列。許可ルールの追加やセッションの権限モードの変更などがあります |
2113| `message` | `"deny"` の場合のみ:権限が拒否された理由を Claude に伝えます |2112| `message` | `"deny"` の場合のみ:権限が拒否された理由を Claude に伝えます |
2114| `interrupt` | `"deny"` の場合のみ:`true` の場合、Claude を停止します |2113| `interrupt` | `"deny"` の場合のみ:`true` の場合、Claude を停止します |
2115 2114
2116`decision` オブジェクトなしで終了コード 2 で終了するフックは権限フローを変更せず、その stderr は破棄されます。リクエストを許可または拒否できるのは `decision` オブジェクトのみです。2115`decision` オブジェクトなしで終了コード 2 で終了するフックは権限フローを変更せず、その標準エラー出力は破棄されます。リクエストを許可または拒否できるのは `decision` オブジェクトだけです。
2117 2116
2118```json theme={null}2117```json theme={null}
2119{2118{
2130```2129```
2131 2130
2132<h4 id="permission-update-entries">2131<h4 id="permission-update-entries">
2133 権限の更新エントリ2132 権限更新エントリ
2134</h4>2133</h4>
2135 2134
2136`updatedPermissions` 出力フィールドと [`permission_suggestions` 入力フィールド](#permissionrequest-input)は、どちらも同じエントリオブジェクトの配列を使用します。各エントリには、他のフィールドを決定する `type` と、変更の書き込み先を制御する `destination` があります。2135`updatedPermissions` 出力フィールドと [`permission_suggestions` 入力フィールド](#permissionrequest-input)は、どちらも同じエントリオブジェクトの配列を使用します。各エントリには、他のフィールドを決定する `type` と、変更の書き込み先を制御する `destination` があります。
2137 2136
2138| `type` | フィールド | 効果 |2137| `type` | フィールド | 効果 |
2139| :- | :- | :- |2138| :- | :- | :- |
2140| `addRules` | `rules`、`behavior`、`destination` | 権限ルールを追加します。`rules` は `{toolName, ruleContent?}` オブジェクトの配列です。ツール全体に一致させるには `ruleContent` を省略します。`behavior` は `"allow"`、`"deny"`、または `"ask"` です |2139| `addRules` | `rules`、`behavior`、`destination` | 権限ルールを追加します。`rules` は `{toolName, ruleContent?}` オブジェクトの配列です。ツール全体にマッチさせるには `ruleContent` を省略します。`behavior` は `"allow"`、`"deny"`、`"ask"` のいずれかです |
2141| `replaceRules` | `rules`、`behavior`、`destination` | `destination` にある指定の `behavior` のすべてのルールを、指定した `rules` で置き換えます |2140| `replaceRules` | `rules`、`behavior`、`destination` | `destination` にある指定された `behavior` のルールをすべて、提供された `rules` で置き換えます |
2142| `removeRules` | `rules`、`behavior`、`destination` | 指定の `behavior` の一致するルールを削除します |2141| `removeRules` | `rules`、`behavior`、`destination` | 指定された `behavior` のうち、マッチするルールを削除します |
2143| `setMode` | `mode`、`destination` | 権限モードを変更します。有効なモードは `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan`、および `default` のエイリアスである `manual` です |2142| `setMode` | `mode`、`destination` | 権限モードを変更します。有効なモードは `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan`、および `default` のエイリアスである `manual` です |
2144| `addDirectories` | `directories`、`destination` | 作業ディレクトリを追加します。`directories` はパス文字列の配列です |2143| `addDirectories` | `directories`、`destination` | 作業ディレクトリを追加します。`directories` はパス文字列の配列です |
2145| `removeDirectories` | `directories`、`destination` | 作業ディレクトリを削除します |2144| `removeDirectories` | `directories`、`destination` | 作業ディレクトリを削除します |
2146 2145
2147<Note>2146<Note>
2148 `bypassPermissions` を指定した `setMode` は、バイパスモードがすでに利用可能な状態でセッションを起動した場合にのみ有効になります。バイパスモードを利用可能にするには、`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` のいずれかを使用するか、[ユーザー設定、`--settings`、または管理設定](/docs/ja/settings-reference#permissions-defaultmode)で `permissions.defaultMode: "bypassPermissions"` を指定します。それ以外の場合、この更新は何も行いません。また、[`permissions.disableBypassPermissionsMode`](/docs/ja/permissions#managed-settings) によってこのモードが無効化されている場合や、セッションが [restricted モード](/docs/ja/cli-reference#cli-flags)で開始された場合も、この更新は何も行いません。2147 `bypassPermissions` を指定した `setMode` が有効になるのは、bypass モードがすでに利用可能な状態でセッションを起動した場合のみです。つまり、`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions`、または [ユーザー設定、`--settings`、管理設定](/docs/ja/settings-reference#permissions-defaultmode)での `permissions.defaultMode: "bypassPermissions"` のいずれかを使用した場合です。それ以外の場合、この更新は何も行いません。また、[`permissions.disableBypassPermissionsMode`](/docs/ja/permissions#managed-settings) がこのモードを無効にしている場合や、セッションが[制限モード](/docs/ja/cli-reference#cli-flags)で開始された場合も、この更新は何も行いません。
2149 2148
2150 `bypassPermissions` は、`destination` に関係なく `defaultMode` として永続化されることはありません。2149 `destination` に関係なく、`bypassPermissions` が `defaultMode` として永続化されることはありません。
2151</Note>2150</Note>
2152 2151
2153各エントリの `destination` フィールドは、変更をメモリ内にとどめるか、設定ファイルに永続化するかを決定します。2152すべてのエントリの `destination` フィールドによって、変更がメモリ内にとどまるか、設定ファイルに永続化されるかが決まります。
2154 2153
2155| `destination` | 書き込み先 |2154| `destination` | 書き込み先 |
2156| :- | :- |2155| :- | :- |
2159| `projectSettings` | `.claude/settings.json` |2158| `projectSettings` | `.claude/settings.json` |
2160| `userSettings` | `~/.claude/settings.json` |2159| `userSettings` | `~/.claude/settings.json` |
2161 2160
2162フックは、受け取った `permission_suggestions` のいずれかを、そのまま自身の `updatedPermissions` 出力として返すことができます。2161フックは、受け取った `permission_suggestions` のいずれかを、自身の `updatedPermissions` 出力としてそのまま返すことができます。
2163 2162
2164<h3 id="posttooluse">2163<h3 id="posttooluse">
2165 PostToolUse2164 PostToolUse
2169 2168
2170ツール名でマッチします。値は PreToolUse と同じです。2169ツール名でマッチします。値は PreToolUse と同じです。
2171 2170
2172ツール名が適切なフィルターにならない場合は、より広くマッチさせます。2171ツール名が適切なフィルターでない場合は、より広くマッチさせます。
2173 2172
2174* いずれかのツールが正常に完了した後にフックを実行するには、`matcher` を省略するか `"*"` に設定します。フック側で何が変更されたかを自ら調べることができます。たとえば `git status --porcelain` を実行すると、`git diff` では見落とされる未追跡ファイルも一覧表示されます。失敗したツール呼び出しについては、同じフックを [PostToolUseFailure](#posttoolusefailure) の下に追加します。2173* ツールが正常に完了した後に毎回フックを実行するには、`matcher` を省略するか `"*"` に設定します。その後、フック自身が何が変更されたかを調べられます。たとえば `git status --porcelain` を実行すると、`git diff` では見落とされる未追跡ファイルも一覧表示されます。失敗したツール呼び出しについては、同じフックを [PostToolUseFailure](#posttoolusefailure) にも追加してください。
2175* 書き込んだのが何であれ、特定のファイルがディスク上で変更されたときにフックを実行するには、[FileChanged](#filechanged) を使用します。`Bash` コマンドや Claude Code 外部のプロセスが同じファイルを書き換えた場合、Claude Code は `Edit|Write` にマッチする `PostToolUse` フックを実行しません。2174* 書き込んだのが何であれ、特定のファイルがディスク上で変更されたときにフックを実行するには、[FileChanged](#filechanged) を使用します。`Bash` コマンドや Claude Code 外部のプロセスが同じファイルを書き換えた場合、Claude Code は `Edit|Write` にマッチする `PostToolUse` フックを実行しません。
2176 2175
2177<h4 id="posttooluse-input">2176<h4 id="posttooluse-input">
2178 PostToolUse の入力2177 PostToolUse の入力
2179</h4>2178</h4>
2180 2179
2181`PostToolUse` フックは、ツールがすでに正常に実行された後に発火します。入力には、ツールに送られた引数である `tool_input` と、ツールが返した結果である `tool_response` の両方が含まれます。両者の正確なスキーマはツールによって異なります。ファイルツールの `tool_input` のパスは [PreToolUse](#pretooluse-input) と同じ形式で渡されます。つまり、常に絶対パスで、プラットフォーム固有の区切り文字が使われるため、Windows ではバックスラッシュになります。MCP ツールの場合、入力には [`mcp_server`](#pretooluse-input) オブジェクトも含まれます。2180`PostToolUse` フックは、ツールがすでに正常に実行された後に発火します。入力には、ツールに送信された引数である `tool_input` と、ツールが返した結果である `tool_response` の両方が含まれます。どちらの正確なスキーマもツールによって異なります。ファイルツールの `tool_input` のパスは [PreToolUse](#pretooluse-input) と同じ形式で届きます。つまり常に絶対パスで、プラットフォームネイティブの区切り文字が使われるため、Windows ではバックスラッシュになります。MCP ツールの場合、入力には [`mcp_server`](#pretooluse-input) オブジェクトも含まれます。
2182 2181
2183```json theme={null}2182```json theme={null}
2184{2183{
2203 2202
2204| フィールド | 説明 |2203| フィールド | 説明 |
2205| :- | :- |2204| :- | :- |
2206| `duration_ms` | 省略可能。ツールの実行時間(ミリ秒)。権限プロンプトと PreToolUse フックに費やされた時間は含みません |2205| `duration_ms` | 省略可能。ツールの実行時間(ミリ秒)。権限プロンプトと PreToolUse フックに費やされた時間は含まれません |
2207 2206
2208<h4 id="posttooluse-decision-control">2207<h4 id="posttooluse-decision-control">
2209 PostToolUse の判定制御2208 PostToolUse の決定制御
2210</h4>2209</h4>
2211 2210
2212`PostToolUse` フックは、ツール実行後に Claude へフィードバックを提供できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有フィールドを返すことができます。2211`PostToolUse` フックは、ツール実行後に Claude にフィードバックを提供できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有のフィールドを返すことができます。
2213 2212
2214| フィールド | 説明 |2213| フィールド | 説明 |
2215| :- | :- |2214| :- | :- |
2216| `decision` | `"block"` を指定すると、ツール結果の横に `reason` が追加されます。Claude には元の出力も引き続き表示されます。出力を置き換えるには `updatedToolOutput` を使用します |2215| `decision` | `"block"` は、ツールの結果の横に `reason` を追加します。Claude には元の出力も引き続き表示されます。出力を置き換えるには `updatedToolOutput` を使用します |
2217| `reason` | `decision` が `"block"` のときに Claude に示される説明 |2216| `reason` | `decision` が `"block"` の場合に Claude に表示される説明 |
2218| `additionalContext` | ツール結果とともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |2217| `additionalContext` | ツールの結果と一緒に Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
2219| `classifierContext` | この呼び出しの結果について、Claude ではなく [auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)の分類器に向けた短い注記。[auto モードの分類器向けに結果に注記を付ける](#annotate-a-result-for-the-auto-mode-classifier)を参照してください。Claude Code v2.1.236 以降が必要です |2218| `classifierContext` | Claude ではなく [auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)の分類器に向けた、この呼び出しの結果に関する短いメモ。[auto モードの分類器向けに結果に注釈を付ける](#annotate-a-result-for-the-auto-mode-classifier)を参照してください。Claude Code v2.1.236 以降が必要です |
2220| `updatedToolOutput` | Claude に送られる前に、ツールの出力を指定した値で置き換えます。値はツールの出力の形式と一致している必要があります |2219| `updatedToolOutput` | Claude に送信される前に、ツールの出力を指定した値で置き換えます。値はツールの出力の形式と一致する必要があります |
2221| `updatedMCPToolOutput` | [MCP ツール](#match-mcp-tools)に限り出力を置き換えます。すべてのツールで機能する `updatedToolOutput` の使用を推奨します |2220| `updatedMCPToolOutput` | [MCP ツール](#match-mcp-tools)の出力のみを置き換えます。すべてのツールで機能する `updatedToolOutput` の使用を推奨します |
2222 2221
2223次の例は、`Bash` 呼び出しの出力を置き換えます。置き換える値は `Bash` ツールの出力の形式に一致しています。2222以下の例では、`Bash` 呼び出しの出力を置き換えます。置き換える値は `Bash` ツールの出力の形式と一致しています。
2224 2223
2225```json theme={null}2224```json theme={null}
2226{2225{
2238```2237```
2239 2238
2240<Warning>2239<Warning>
2241 `updatedToolOutput` が変更するのは Claude に見える内容だけです。フックが発火する時点でツールはすでに実行されているため、書き込まれたファイル、実行されたコマンド、送信されたネットワークリクエストはすでに反映されています。OpenTelemetry のツールスパンや分析イベントなどのテレメトリも、フックが実行される前の元の出力を記録します。ツール呼び出しを実行前に阻止または変更するには、代わりに [PreToolUse](#pretooluse) フックを使用してください。2240 `updatedToolOutput` が変更するのは Claude に見える内容だけです。フックが発火した時点でツールはすでに実行されているため、書き込まれたファイル、実行されたコマンド、送信されたネットワークリクエストはすでに影響を及ぼしています。OpenTelemetry のツールスパンや分析イベントなどのテレメトリも、フックが実行される前の元の出力を記録します。ツール呼び出しを実行前に阻止または変更するには、代わりに [PreToolUse](#pretooluse) フックを使用してください。
2242 2241
2243 置き換える値はツールの出力の形式と一致している必要があります。組み込みツールはプレーンな文字列ではなく構造化されたオブジェクトを返します。たとえば `Bash` は、`stdout`、`stderr`、`interrupted`、`isImage` フィールドを持つオブジェクトを返します。組み込みツールの場合、ツールの出力スキーマに一致しない値は無視され、元の出力が使用されます。MCP ツールの出力はスキーマ検証なしでそのまま渡されます。Claude が必要とするエラーの詳細を取り除くと、Claude が誤った前提のまま作業を進める可能性があります。2242 置き換える値はツールの出力の形式と一致する必要があります。組み込みツールはプレーンな文字列ではなく構造化オブジェクトを返します。たとえば、`Bash` は `stdout`、`stderr`、`interrupted`、`isImage` フィールドを持つオブジェクトを返します。組み込みツールの場合、ツールの出力スキーマと一致しない値は無視され、元の出力が使用されます。MCP ツールの出力はスキーマ検証なしでそのまま渡されます。Claude が必要とするエラーの詳細を取り除くと、Claude が誤った前提に基づいて作業を進める可能性があります。
2244</Warning>2243</Warning>
2245 2244
2246<h4 id="annotate-a-result-for-the-auto-mode-classifier">2245<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2247 auto モードの分類器向けに結果に注記を付ける2246 auto モードの分類器向けに結果に注釈を付ける
2248</h4>2247</h4>
2249 2248
2250`classifierContext` を返すと、ツール呼び出しの結果に関する短い注記を、Claude ではなく [auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)の分類器に送ることができます。分類器は[ツール結果そのものを受け取ることはない](/docs/ja/permission-modes#how-the-classifier-evaluates-actions)ため、後続のアクションを審査する前に、呼び出しが何を返したかについて分類器に伝えるには、このフィールドを使うのがサポートされた方法です。このフィールドには Claude Code v2.1.236 以降が必要です。2249`classifierContext` を返すと、ツール呼び出しの結果に関する短いメモを、Claude ではなく [auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)の分類器に送信できます。分類器は[ツールの結果そのものを受け取ることはない](/docs/ja/permission-modes#how-the-classifier-evaluates-actions)ため、このフィールドは、分類器が後続のアクションを審査する前に、呼び出しが返した内容について何かを伝えるためのサポートされた方法です。このフィールドには Claude Code v2.1.236 以降が必要です。
2251 2250
2252次の例は、クエリの出力がどこから得られたかを分類器に伝えます。2251以下の例では、クエリの出力がどこから来たかを分類器に伝えます。
2253 2252
2254```json theme={null}2253```json theme={null}
2255{2254{
2260}2259}
2261```2260```
2262 2261
2263分類器が注記をどの程度重視するかは、フックをどこで設定したかによって異なります。2262分類器がメモをどの程度重視するかは、フックを設定した場所によって異なります。
2264 2263
2265* **Claude Code で設定されたフック**: 設定ファイル、プラグイン、スキル、エージェントのフロントマターから読み込まれたフックの場合、分類器は注記を未検証の、アプリケーションから提供されたコンテキストとして扱います。注記がユーザーの意図を確立することはなく、ユーザーが何かを承認または要求したと注記が主張する場合、分類器はその主張を会話内のユーザー自身のメッセージと照合します2264* **Claude Code で設定されたフック**: 設定ファイル、プラグイン、スキル、エージェントのフロントマターからのフックの場合、分類器はメモを検証されていない、アプリケーション提供のコンテキストとして扱います。メモがユーザーの意図を確定させることはなく、ユーザーが何かを承認した、または要求したとメモが主張する場合、分類器はその主張を会話内のユーザー自身のメッセージと照合します
2266* **インプロセスの Agent SDK コールバック**: Claude Code を組み込んだアプリケーションがフックを [TypeScript SDK コールバック](/docs/ja/agent-sdk/hooks)として登録し、ライブセッション中に注記を返す場合、分類器は注記で伝えられたユーザーの発言をユーザーの意図として考慮することがあります。そのような発言は、ユーザーが送信したメッセージであれば分類器が受け入れる同意要件を満たすことはありますが、ユーザー自身のメッセージでも解除できないブロックを解除することはありません。セッションが再開された後は、Claude Code は復元された注記を未検証のコンテキストとして扱います。両方のグループのフックが同じ呼び出しに注記を付けた場合、分類器は結合された注記を未検証として扱います2265* **インプロセスの Agent SDK コールバック**: Claude Code を組み込んだアプリケーションがフックを [TypeScript SDK コールバック](/docs/ja/agent-sdk/hooks)として登録し、ライブセッション中にメモを返す場合、分類器はメモで伝えられたユーザーの発言をユーザーの意図として重視することがあります。そのような発言は、ユーザーが送信したメッセージであれば分類器が受け入れる同意要件を満たすことができますが、ユーザー自身のメッセージでも解除できないブロックを解除することはありません。セッションが再開された後、Claude Code は復元されたメモを検証されていないコンテキストとして扱います。両方のグループのフックが同じ呼び出しに注釈を付けた場合、分類器は結合されたメモを検証されていないものとして扱います
2267 2266
2268Claude Code は注記を渡す際に次の制限を適用します。2267Claude Code はメモを配信する際に次の制限を適用します。
2269 2268
2270* **長さ**: Claude Code は 1 回のツール呼び出しに対する注記を 2,000 文字までに制限し、残りを切り捨てます。この上限は、その呼び出しに応答するすべてのフックで共有されます2269* **長さ**: Claude Code は 1 回のツール呼び出しに対するメモを 2,000 文字に制限し、残りを切り捨てます。この上限は、その呼び出しに応答するすべてのフックで共有されます
2271* **同期的な応答のみ**: [バックグラウンドで実行される](#run-hooks-in-the-background)フックの応答では、Claude Code はこのフィールドを無視します。その応答は Claude Code がツール結果を記録した後に届くためです2270* **同期応答のみ**: Claude Code は、[バックグラウンドで実行される](#run-hooks-in-the-background)フックの応答に含まれるこのフィールドを無視します。その応答は Claude Code がツールの結果を記録した後に届くためです
2272* **分類器が記録しない呼び出し**: 分類器のトランスクリプトには、ファイルの読み取りや検索などの読み取り専用の参照は含まれません。Claude Code は、そのような呼び出しに付けられた注記を破棄します2271* **分類器が記録しない呼び出し**: 分類器のトランスクリプトでは、ファイルの読み取りや検索などの読み取り専用の参照が省略されます。Claude Code は、そのような呼び出しに付けられたメモを破棄します
2273* **書き換えとの相互作用**: `updatedToolOutput` で置き換える出力について注記が説明している場合は、同じフックの応答で両方のフィールドを返してください。その書き換えが拒否された場合や、別のフックの書き換えで置き換えられた場合、Claude Code は注記を破棄します。書き換えなしで返した注記は、別のフックが出力を書き換えた場合でも Claude Code によって渡されます2272* **書き換えとの相互作用**: `updatedToolOutput` で置き換えている出力についてメモを記述する場合は、同じフックの応答で両方のフィールドを返してください。その書き換えが拒否された場合、または別のフックの書き換えがそれを置き換えた場合、Claude Code はメモを破棄します。書き換えなしで返したメモは、別のフックが出力を書き換えた場合でも Claude Code によって配信されます
2274 2273
2275<Warning>2274<Warning>
2276 分類器は `classifierContext` に入れた内容を、セッションをホストしているアプリケーションからの情報として読み取ります。そのため、信頼できないツール出力やサードパーティのテキストをコピーして入れないでください。注記は、その出所に関する事実やそれについてのユーザーの発言など、この 1 回の呼び出しについての短い主張にとどめてください。無関係なメッセージやイベントのストリームを渡すためにこのフィールドを使用しないでください。2275 分類器は `classifierContext` に配置した内容を、セッションをホストしているアプリケーションからの情報として読み取ります。そのため、信頼できないツール出力やサードパーティのテキストをコピーしないでください。メモは、その 1 回の呼び出しに関する短い主張(出所に関する事実や、それに関するユーザーの発言など)にとどめてください。このフィールドを、無関係なメッセージやイベントのストリームを配信するために使用しないでください。
2277</Warning>2276</Warning>
2278 2277
2279<h3 id="posttoolusefailure">2278<h3 id="posttoolusefailure">
2285ツール名でマッチします。値は PreToolUse と同じです。2284ツール名でマッチします。値は PreToolUse と同じです。
2286 2285
2287<Note>2286<Note>
2288 このイベントは、実行前に拒否されたツール呼び出しでは発火しません。該当するのは、不明なツール名、スキーマ検証やツール固有の検証に失敗した入力、権限の拒否です。検証による拒否は `tool_use_error` 結果として返され、フックが実行される前に発生するため、`PreToolUse` も `PostToolUseFailure` も発火しません。権限の拒否では `PreToolUse` は発火しますが、このイベントは発火しません。[PermissionDenied](#permissiondenied) を参照してください。2287 このイベントは、実行前に拒否されたツール呼び出し(不明なツール名、スキーマまたはツール固有の検証に失敗した入力、権限の拒否)では発火しません。検証による拒否は `tool_use_error` の結果として返され、フックの実行前に発生するため、`PreToolUse` も `PostToolUseFailure` も発火しません。権限の拒否では `PreToolUse` は発火しますが、このイベントは発火しません。[PermissionDenied](#permissiondenied) を参照してください。
2289</Note>2288</Note>
2290 2289
2291<h4 id="posttoolusefailure-input">2290<h4 id="posttoolusefailure-input">
2292 PostToolUseFailure の入力2291 PostToolUseFailure の入力
2293</h4>2292</h4>
2294 2293
2295PostToolUseFailure フックは、PostToolUse と同じ `tool_name` と `tool_input` フィールドに加えて、エラー情報をトップレベルのフィールドとして受け取ります。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。たとえば、失敗した `npm test` コマンドでは次のような入力が渡されます。2294PostToolUseFailure フックは、PostToolUse と同じ `tool_name` および `tool_input` フィールドに加えて、トップレベルのフィールドとしてエラー情報を受け取ります。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。たとえば、失敗した `npm test` コマンドでは次のような内容が渡されます。
2296 2295
2297```json theme={null}2296```json theme={null}
2298{2297{
2316| フィールド | 説明 |2315| フィールド | 説明 |
2317| :- | :- |2316| :- | :- |
2318| `error` | 何が問題だったかを説明する文字列。形式は失敗したツールによって異なります |2317| `error` | 何が問題だったかを説明する文字列。形式は失敗したツールによって異なります |
2319| `is_interrupt` | 省略可能なブール値。ツールが報告したエラーとしてではなく、中断として Claude Code に失敗が伝わった場合に true になります。実行中のツールをキャンセルしてもこのフックは発火せず、代わりにツール結果に中断メッセージが含まれます |2318| `is_interrupt` | 省略可能なブール値。ツールが報告したエラーとしてではなく、中止として Claude Code に失敗が届いた場合に true になります。実行中のツールをキャンセルしてもこのフックは発火しません。その場合は、ツールの結果に中断メッセージが含まれます |
2320| `duration_ms` | 省略可能。ツールの実行時間(ミリ秒)。権限プロンプトと PreToolUse フックに費やされた時間は含みません |2319| `duration_ms` | 省略可能。ツールの実行時間(ミリ秒)。権限プロンプトと PreToolUse フックに費やされた時間は含まれません |
2321 2320
2322`error` 文字列は通常、失敗したツールの結果として Claude が受け取るテキストと同じです。形式はツールと失敗の種類によって異なります。フックの判定には `tool_name`、`is_interrupt`、および先頭行の `Exit code N` を使用し、文字列の残りの部分は安定した形式ではなく表示用テキストとして扱ってください。2321`error` 文字列は通常、失敗したツールの結果として Claude が受け取るテキストと同じです。その形式はツールと失敗の種類によって異なります。フックは `tool_name`、`is_interrupt`、および先頭行の `Exit code N` をキーにしてください。文字列の残りの部分は表示用のテキストとして扱い、安定した形式とみなさないでください。
2323 2322
2324* Bash と PowerShell の場合、実行されて終了したコマンドでは、先頭行が `Exit code N` となり、その後にコマンドが生成した出力が stdout と stderr の混在した 1 つのブロックとして続きます2323* Bash と PowerShell の場合、実行されて終了したコマンドは先頭行に `Exit code N` を出力し、その後にコマンドが生成した出力を、stdout と stderr が混在した 1 つのブロックとして出力します
2325* Claude Code がシェルプロセス自体を起動できなかった場合、ペイロードには終了コードの行がない失敗メッセージだけが含まれることもあります2324* Claude Code がシェルプロセス自体を起動できなかった場合、ペイロードには終了コードの行がない、失敗メッセージだけが含まれることもあります
2326* Claude Code は長い文字列を `... [N characters truncated] ...` マーカーを挟んで中間部分を切り詰めることがあり、`Command timed out after 2m 0s` のような独自の行を挿入することもあります2325* Claude Code は長い文字列を `... [N characters truncated] ...` マーカーを挟んで中間部分を切り詰めます。また、`Command timed out after 2m 0s` のような独自の行を挿入することもあります
2327 2326
2328<h4 id="posttoolusefailure-decision-control">2327<h4 id="posttoolusefailure-decision-control">
2329 PostToolUseFailure の判定制御2328 PostToolUseFailure の決定制御
2330</h4>2329</h4>
2331 2330
2332`PostToolUseFailure` フックは、ツールの失敗後に Claude へコンテキストを提供できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有フィールドを返すことができます。2331`PostToolUseFailure` フックは、ツールの失敗後に Claude にコンテキストを提供できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有のフィールドを返すことができます。
2333 2332
2334| フィールド | 説明 |2333| フィールド | 説明 |
2335| :- | :- |2334| :- | :- |
2336| `additionalContext` | エラーとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |2335| `additionalContext` | エラーと一緒に Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
2337 2336
2338```json theme={null}2337```json theme={null}
2339{2338{
2348 PostToolBatch2347 PostToolBatch
2349</h3>2348</h3>
2350 2349
2351バッチ内のすべてのツール呼び出しが解決された後、Claude Code が次のリクエストをモデルに送信する前に 1 回実行されます。`PostToolUse` はツールごとに 1 回発火するため、Claude が並列でツールを呼び出すと同時に発火します。`PostToolBatch` はバッチ全体に対して正確に 1 回だけ発火するため、単一のツールではなく実行されたツールの組み合わせに依存するコンテキストを注入するのに適しています。このイベントには matcher はありません。2350バッチ内のすべてのツール呼び出しが解決された後、Claude Code がモデルに次のリクエストを送信する前に 1 回実行されます。`PostToolUse` はツールごとに 1 回発火するため、Claude が並列にツールを呼び出すと同時に発火します。`PostToolBatch` はバッチ全体に対して正確に 1 回だけ発火するため、単一のツールではなく、実行されたツールの集合に依存するコンテキストを注入するのに適した場所です。このイベントには matcher がありません。
2352 2351
2353<h4 id="posttoolbatch-input">2352<h4 id="posttoolbatch-input">
2354 PostToolBatch の入力2353 PostToolBatch の入力
2380}2379}
2381```2380```
2382 2381
2383`tool_response` には、対応する `tool_result` ブロックでモデルが受け取るのと同じ内容が含まれます。値は、ツールが出力したとおりのシリアライズされた文字列またはコンテンツブロックの配列です。`Read` の場合、これは生のファイル内容ではなく、行番号が先頭に付いたテキストを意味します。応答は大きくなる場合があるため、必要なフィールドだけを解析してください。2382`tool_response` には、モデルが対応する `tool_result` ブロックで受け取るのと同じ内容が含まれます。値は、ツールが出力したとおりのシリアライズされた文字列またはコンテンツブロックの配列です。`Read` の場合、生のファイル内容ではなく、行番号が先頭に付いたテキストになります。レスポンスは大きくなる可能性があるため、必要なフィールドだけを解析してください。
2384 2383
2385<Note>2384<Note>
2386 `tool_response` の形式は `PostToolUse` のものとは異なります。`PostToolUse` はツールの構造化された `Output` オブジェクト(`Write` の場合は `{filePath: "...", type: "create"}` など)を渡しますが、`PostToolBatch` はモデルに見えるシリアライズされた `tool_result` の内容を渡します。2385 `tool_response` の形式は `PostToolUse` のものとは異なります。`PostToolUse` はツールの構造化された `Output` オブジェクト(`Write` の場合は `{filePath: "...", type: "create"}` など)を渡しますが、`PostToolBatch` はモデルに表示されるシリアライズされた `tool_result` の内容を渡します。
2387</Note>2386</Note>
2388 2387
2389<h4 id="posttoolbatch-decision-control">2388<h4 id="posttoolbatch-decision-control">
2390 PostToolBatch の判定制御2389 PostToolBatch の決定制御
2391</h4>2390</h4>
2392 2391
2393`PostToolBatch` フックは、Claude 向けのコンテキストを注入できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有フィールドを返すことができます。2392`PostToolBatch` フックは、Claude 向けにコンテキストを注入できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有のフィールドを返すことができます。
2394 2393
2395| フィールド | 説明 |2394| フィールド | 説明 |
2396| :- | :- |2395| :- | :- |
2397| `additionalContext` | 次のモデル呼び出しの前に 1 回注入されるコンテキスト文字列。渡され方の詳細、入れるべき内容、再開されたセッションで過去の値がどう扱われるかについては、[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |2396| `additionalContext` | 次のモデル呼び出しの前に 1 回注入されるコンテキスト文字列。配信の詳細、含めるべき内容、再開されたセッションが過去の値をどのように扱うかについては、[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
2398 2397
2399```json theme={null}2398```json theme={null}
2400{2399{
2405}2404}
2406```2405```
2407 2406
2408`decision: "block"` または `continue: false` を返すと、次のモデル呼び出しの前にエージェント型ループが停止します。ブロックメッセージは、JSON の `reason` または `stopReason`、あるいは終了コード 2 の場合は stderr から取得されます。このメッセージはトランスクリプトに警告として表示され、会話にも残るため、会話が続行されると Claude はそれを確認できます。2407`decision: "block"` または `continue: false` を返すと、次のモデル呼び出しの前にエージェント型ループが停止します。ブロックメッセージは、JSON の `reason` または `stopReason`、あるいは終了コード 2 の場合は stderr から取得されます。このメッセージはトランスクリプトに警告として表示され、会話に残るため、会話が続行されると Claude にも表示されます。
2409 2408
2410<h3 id="permissiondenied">2409<h3 id="permissiondenied">
2411 PermissionDenied2410 PermissionDenied
2412</h3>2411</h3>
2413 2412
2414[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)がツール呼び出しを拒否したときに実行されます。これには、[auto モードとは別の安全性チェックが分類器自身のリクエストを拒否した](/docs/ja/errors#auto-mode-cannot-determine-the-safety-of-an-action)場合や、分類器の応答を解析できなかった場合など、分類器の判定なしで拒否された場合も含まれます。このフックは auto モードでのみ発火します。ユーザーが権限ダイアログを手動で拒否した場合、`PreToolUse` フックが呼び出しをブロックした場合、`deny` ルールがマッチした場合には実行されません。拒否のログ記録、設定の調整、またはツール呼び出しを再試行してよいことをモデルに伝えるために使用します。2413[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)がツール呼び出しを拒否したときに実行されます。これには、[auto モードとは別の安全性チェックが分類器自身のリクエストを拒否した](/docs/ja/errors#auto-mode-cannot-determine-the-safety-of-an-action)場合や、分類器の応答を解析できなかった場合など、分類器の判定なしに拒否された場合も含まれます。このフックは auto モードでのみ発火します。権限ダイアログを手動で拒否した場合、`PreToolUse` フックが呼び出しをブロックした場合、`deny` ルールがマッチした場合には実行されません。拒否のログ記録、設定の調整、またはモデルにツール呼び出しを再試行してよいことを伝えるために使用します。
2415 2414
2416ツール名でマッチします。値は PreToolUse と同じです。2415ツール名でマッチします。値は PreToolUse と同じです。
2417 2416
2440 2439
2441| フィールド | 説明 |2440| フィールド | 説明 |
2442| :- | :- |2441| :- | :- |
2443| `reason` | 拒否の理由。分類器の判定による場合、ほとんどのセッションでは、`[Data Exfiltration]` のように角括弧でマッチしたルールの名前が示されます。その他の形式については [拒否を確認する](/docs/ja/auto-mode-config#review-denials)を参照してください。[判定なしの拒否](#permissiondenied-decision-control)の場合は、`Auto mode could not evaluate this action and is blocking it for safety` で始まります。分類器モデルが利用できなかったことによる拒否の場合は、固定テキスト `Classifier unavailable` になります |2442| `reason` | 拒否の理由。分類器の判定の場合、ほとんどのセッションでは `[Data Exfiltration]` のように、マッチしたルールが角括弧で示されます。その他の形式については[拒否を確認する](/docs/ja/auto-mode-config#review-denials)を参照してください。[判定なしの拒否](#permissiondenied-decision-control)の場合は、`Auto mode could not evaluate this action and is blocking it for safety` で始まります。分類器モデルが利用できなかったことによる拒否の場合は、固定のテキスト `Classifier unavailable` になります |
2444 2443
2445<h4 id="permissiondenied-decision-control">2444<h4 id="permissiondenied-decision-control">
2446 PermissionDenied の判定制御2445 PermissionDenied の決定制御
2447</h4>2446</h4>
2448 2447
2449PermissionDenied フックは、拒否されたツール呼び出しを再試行してよいことをモデルに伝えることができます。`hookSpecificOutput.retry` を `true` に設定した JSON オブジェクトを返します。2448PermissionDenied フックは、拒否されたツール呼び出しを再試行してよいことをモデルに伝えることができます。`hookSpecificOutput.retry` を `true` に設定した JSON オブジェクトを返します。
2457}2456}
2458```2457```
2459 2458
2460`retry` が `true` の場合、Claude Code は、ツール呼び出しを再試行してよいことをモデルに伝えるメッセージを会話に追加します。Claude Code 自体が拒否を取り消すことはありません。フックが JSON を返さない場合、または `retry: false` を返した場合、拒否はそのまま維持され、モデルは元の拒否メッセージを受け取ります。2459`retry` が `true` の場合、Claude Code は、ツール呼び出しを再試行してよいことをモデルに伝えるメッセージを会話に追加します。Claude Code が拒否そのものを取り消すことはありません。フックが JSON を返さない場合、または `retry: false` を返した場合、拒否はそのまま維持され、モデルは元の拒否メッセージを受け取ります。
2461 2460
2462分類器が[アクションについて判定を出さなかった](/docs/ja/errors#auto-mode-cannot-determine-the-safety-of-an-action)場合、つまり分類器の応答を解析できなかった場合や、auto モードとは別の安全性チェックが分類器自身のリクエストを拒否した場合、Claude Code は `retry: true` を無視します。そのような拒否については、後で再試行するか先に進むかを、Claude Code がすでに拒否メッセージでモデルに伝えています。2461分類器が[アクションに対する判定を下さなかった](/docs/ja/errors#auto-mode-cannot-determine-the-safety-of-an-action)場合、つまり応答を解析できなかった場合や、auto モードとは別の安全性チェックが分類器自身のリクエストを拒否した場合、Claude Code は `retry: true` を無視します。これらの拒否については、Claude Code はすでに拒否メッセージの中で、後で再試行するか先に進むかをモデルに伝えています。
2463 2462
2464<h3 id="notification">2463<h3 id="notification">
2465 Notification2464 Notification
2466</h3>2465</h3>
2467 2466
2468Claude Code が通知を送信するときに実行されます。通知の種類でマッチします。すべての通知の種類でフックを実行するには、matcher を省略します。2467Claude Code が通知を送信するときに実行されます。通知の種類でマッチします。すべての種類の通知でフックを実行するには、matcher を省略します。
2469 2468
2470デスクトップ通知をオフにしていても、これらのフックイベントは受け取ります。`preferredNotifChannel` 設定(`notifications_disabled` を含む)が変更するのはユーザーへの通知方法だけで、フックが実行されるかどうかは変わりません。2469デスクトップ通知をオフにしていても、これらのフックイベントは受け取ります。`notifications_disabled` を含む `preferredNotifChannel` 設定が変更するのは通知の受け取り方だけであり、フックが実行されるかどうかは変わりません。
2471 2470
2472| Matcher | 発火するタイミング |2471| Matcher | 発火するタイミング |
2473| :- | :- |2472| :- | :- |
2474| `permission_prompt` | Claude がツールの使用またはサンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)について承認を必要としており、プロンプトが約 6 秒間待機している |2473| `permission_prompt` | Claude がツールの使用、またはサンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)について承認を必要としており、プロンプトが約 6 秒間待機している場合 |
2475| `idle_prompt` | Claude が約 60 秒前に応答を終え、それ以降ユーザーが入力していない |2474| `idle_prompt` | Claude が約 60 秒前に応答を終え、それ以降ユーザーが入力していない場合 |
2476| `auth_success` | 認証が完了した |2475| `auth_success` | 認証が完了した場合 |
2477| `elicitation_dialog` | MCP サーバーが elicitation フォームを開き、ユーザーが約 6 秒間入力していない |2476| `elicitation_dialog` | MCP サーバーが elicitation フォームを開き、ユーザーが約 6 秒間入力していない場合 |
2478| `elicitation_url_dialog` | MCP サーバーがブラウザーの URL を開くようユーザーに求め、ユーザーが約 6 秒間入力していない |2477| `elicitation_url_dialog` | MCP サーバーがブラウザの URL を開くよう求め、ユーザーが約 6 秒間入力していない場合 |
2479| `elicitation_complete` | MCP サーバーが [URL モードの elicitation](#elicitation-input) の完了を報告した |2478| `elicitation_complete` | MCP サーバーが [URL モードの elicitation](#elicitation-input) の完了を報告した場合 |
2480| `elicitation_response` | MCP の elicitation 応答がサーバーに返送された |2479| `elicitation_response` | MCP の elicitation の応答がサーバーに送り返された場合 |
2481| `agent_needs_input` | ターミナルで[エージェントビュー](/docs/ja/agent-view)が開いている間に、バックグラウンドセッションがユーザーの入力を待ち始めた。また、ターミナルセッションが[エージェントチームのチームメイトのターミナル設定に関する質問](/docs/ja/agent-teams#choose-a-display-mode)や、[分類器リクエストの料金](/docs/ja/auto-mode-classifier-billing)に関する auto モードの通知を表示し、ユーザーが約 6 秒間入力していない場合にも発火します |2480| `agent_needs_input` | ターミナルで[エージェントビュー](/docs/ja/agent-view)が開いている間に、バックグラウンドセッションがユーザーの入力待ちを開始した場合。また、ターミナルセッションで[エージェントチームのチームメイトのターミナル設定に関する質問](/docs/ja/agent-teams#choose-a-display-mode)や、auto モードの[分類器リクエストの料金](/docs/ja/auto-mode-classifier-billing)に関する通知が表示され、ユーザーが約 6 秒間入力していない場合にも発火します |
2482| `agent_completed` | バックグラウンドセッションが終了または失敗した。ターミナルで[エージェントビュー](/docs/ja/agent-view)が開いている間のみ発火します |2481| `agent_completed` | バックグラウンドセッションが終了または失敗した場合。ターミナルで[エージェントビュー](/docs/ja/agent-view)が開いている間のみ発火します |
2483| `quota_auto_resume_fired` | claude.ai の使用制限によって一時停止したタスクを Claude Code が続行した。続行はリセット時点、または待機中に Claude Code で行った操作(使用クレジットの追加、プランのアップグレード、モデルの切り替えなど)によって使用量が再び利用可能になった場合はそれより早く行われます。ただし[モデル設定の例外](/docs/ja/interactive-mode#wait-for-a-usage-limit-to-reset)があります |2482| `quota_auto_resume_fired` | claude.ai の使用制限によって一時停止されたタスクを Claude Code が続行した場合。リセット時、または待機中に Claude Code で使用クレジットの追加、プランのアップグレード、モデルの切り替えなどを行って再び使用可能になった場合はそれより早く続行されます。ただし、[モデル設定に関する例外](/docs/ja/interactive-mode#wait-for-a-usage-limit-to-reset)があります |
2484| `quota_auto_resume_stale` | コンピューターが約 30 分を超えてスリープしている間に claude.ai の使用制限がリセットされた。Claude Code は続行せず、ユーザーが `Enter` を押すのを待ちます。スリープがそれより短い場合は続行し、代わりに `quota_auto_resume_fired` を発火します |2483| `quota_auto_resume_stale` | コンピューターが約 30 分以上スリープしている間に claude.ai の使用制限がリセットされた場合。Claude Code は続行せず、ユーザーが `Enter` を押すのを待ちます。スリープがそれより短い場合は続行し、代わりに `quota_auto_resume_fired` を発火します |
2485| `quota_auto_resume_disabled` | Claude Code がタスクを続行せずに claude.ai の使用制限の待機を終了した。原因は、[`autoContinueAtUsageLimit`](/docs/ja/settings-reference#autocontinueatusagelimit) がオフにされた、Claude Code が自ら開始した待機中にリセットが 24 時間以上先に移動した、続行したタスクが繰り返し制限に達した、または続行がモデルに届く前にブロックされた、のいずれかです。ユーザーが `Esc` または `Ctrl+C` を押した場合や、**Don't continue automatically** を選択した場合は発火しません |2484| `quota_auto_resume_disabled` | Claude Code が claude.ai の使用制限の待機を、タスクを続行せずに終了した場合。原因は、[`autoContinueAtUsageLimit`](/docs/ja/settings-reference#autocontinueatusagelimit) がオフになった、Claude Code が自ら開始した待機中にリセットが 24 時間以上先に移動した、続行したタスクが繰り返し制限に達した、または続行がモデルに届く前にブロックされた、のいずれかです。ユーザーが `Esc` や `Ctrl+C` を押した場合、または **Don't continue automatically** を選択した場合は発火しません |
2486 2485
2487`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled` の種類には Claude Code v2.1.234 以降が必要です。2486`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled` の種類には Claude Code v2.1.234 以降が必要です。
2488 2487
2489ターミナルセッションでは、サンドボックス化されたコマンドのネットワークリクエストに対する `permission_prompt` には Claude Code v2.1.246 以降が必要です。2488ターミナルセッションでは、サンドボックス化されたコマンドのネットワークリクエストに対する `permission_prompt` に Claude Code v2.1.246 以降が必要です。
2490 2489
2491チームメイトのターミナル設定に関する質問に対する `agent_needs_input` には Claude Code v2.1.248 以降が必要です。2490チームメイトのターミナル設定に関する質問に対する `agent_needs_input` には Claude Code v2.1.248 以降が必要です。
2492 2491
2493<Note>2492<Note>
2494 `permission_prompt`、`idle_prompt`、`elicitation_dialog`、`elicitation_url_dialog` の種類はデスクトップ通知とタイミングを共有しているため、ターミナルセッションでは、ユーザーがターミナルから離れているとみなされる場合にのみ発生します。2493 `permission_prompt`、`idle_prompt`、`elicitation_dialog`、`elicitation_url_dialog` の種類はデスクトップ通知とタイミングを共有しているため、ターミナルセッションでは、ユーザーがターミナルから離れているように見える場合にのみ表示されます。
2495 2494
2496 * `permission_prompt` は、ユーザーが約 6 秒間入力していない時点で発生します。タイマーは権限プロンプトが表示されたときに開始し、キー入力のたびに延期されます。Claude がツールの使用権限を求めたときにすぐにフックを実行するには、代わりに [PermissionRequest](#permissionrequest) を使用してください。2495 * `permission_prompt` は、ユーザーが約 6 秒間入力していないときに発火します。タイマーは権限プロンプトが表示された時点で開始され、キー入力のたびに延期されます。Claude がツールの使用権限を求めたときに即座にフックを実行するには、代わりに [PermissionRequest](#permissionrequest) を使用してください。
2497 * `idle_prompt` は、Claude が応答を終えてから約 60 秒後に発生します。ただし、それ以降ユーザーが入力しておらず、バックグラウンドの[サブエージェント](/docs/ja/sub-agents)などのバックグラウンドエージェントが実行中でない場合に限ります。claude.ai の使用制限のリセットを待っている間、Claude Code は `idle_prompt` を送信しません。待機が自然に終了すると、代わりに `quota_auto_resume_*` の種類のいずれかが発火します。2496 * `idle_prompt` は、Claude が応答を終えてから約 60 秒後に発火します。ただし、それ以降ユーザーが入力しておらず、バックグラウンドの[サブエージェント](/docs/ja/sub-agents)などのバックグラウンドエージェントが実行中でない場合に限ります。Claude Code は、claude.ai の使用制限のリセットを待っている間は `idle_prompt` を送信しません。待機が自動的に終了した場合は、代わりに `quota_auto_resume_*` のいずれかの種類が発火します。
2498 * `elicitation_dialog`(elicitation フォームの場合)または `elicitation_url_dialog`(ブラウザー URL のリクエストの場合)は、ユーザーが約 6 秒間入力していない時点で発生します。どちらも `permission_prompt` と同じ 6 秒の待機条件を共有しており、タイマーはダイアログが表示されたときに開始し、キー入力のたびに延期されます。2497 * elicitation フォームに対する `elicitation_dialog`、またはブラウザ URL のリクエストに対する `elicitation_url_dialog` は、ユーザーが約 6 秒間入力していないときに発火します。どちらも `permission_prompt` と同じ 6 秒のゲートを共有しており、タイマーはダイアログが表示された時点で開始され、キー入力のたびに延期されます。
2499 2498
2500 別のダイアログが画面に表示されている間に届いた権限リクエストや elicitation にも、同じ 6 秒の待機条件が適用され、リクエストが届いた時点から計測されます。そのため、リクエストが開いているダイアログの後ろでまだ待機している間に通知が届くことがあります。2499 別のダイアログが画面に表示されている間に届いた権限リクエストや elicitation にも、リクエストが届いた時点から計測される同じ 6 秒のゲートが適用されます。その通知は、リクエストが開いているダイアログの後ろでまだ待機している間に届く場合があります。
2501</Note>2500</Note>
2502 2501
2503Claude Code が権限リクエストを Agent SDK の [`canUseTool` コールバック](/docs/ja/agent-sdk/user-input)に送信するセッションでは、`permission_prompt` のタイミングが異なります。Claude Desktop と VS Code 拡張機能は、この方法で Claude Code をホストしています。2502Claude Code が権限リクエストを Agent SDK の [`canUseTool` コールバック](/docs/ja/agent-sdk/user-input)に送信するセッション(Claude Desktop と VS Code 拡張機能が Claude Code をホストする方法)では、Claude Code は `permission_prompt` のタイミングを異なる方法で計測します。
2504 2503
2505* `permission_prompt` は、Claude が権限を求めてから約 6 秒後に発生します。入力中でも Claude Code は延期しません。2504* `permission_prompt` は、Claude が権限を求めてから約 6 秒後に発火します。Claude Code は入力中でも延期しません。
2506* それより早くユーザーまたは [PermissionRequest](#permissionrequest) フックが応答した場合、Claude Code は `permission_prompt` を実行しません。2505* ユーザーまたは [PermissionRequest](#permissionrequest) フックがそれより早く応答した場合、Claude Code は `permission_prompt` を実行しません。
2507* これらのセッションで `permission_prompt` をオフにするには、[`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/ja/env-vars) を `1` に設定します。2506* これらのセッションで `permission_prompt` をオフにするには、[`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/ja/env-vars) を `1` に設定します。
2508 2507
2509v2.1.233 より前は、これらのセッションで `permission_prompt` は発火しませんでした。2508v2.1.233 より前は、これらのセッションで `permission_prompt` は発火しませんでした。
2510 2509
2511通知の種類に応じて異なるハンドラーを実行するには、個別の matcher を使用します。次の設定では、Claude が権限の承認を必要とするときに権限専用のアラートスクリプトを、Claude がアイドル状態になったときに別の通知を実行します。2510通知の種類に応じて異なるハンドラーを実行するには、個別の matcher を使用します。この設定では、Claude が権限の承認を必要とするときに権限専用のアラートスクリプトを起動し、Claude がアイドル状態になったときに別の通知を起動します。
2512 2511
2513```json theme={null}2512```json theme={null}
2514{2513{
2555}2554}
2556```2555```
2557 2556
2558Notification フックは通知をブロックしたり変更したりすることはできません。Claude Code はその `systemMessage` と `continue` フィールドを破棄しますが、[`terminalSequence`](#emit-terminal-notifications) は引き続き出力します。デスクトップ通知の例はこれを利用しています。Notification フックは、通知を外部サービスに転送するといった副作用を目的としています。2557Notification フックは通知をブロックしたり変更したりすることはできません。Claude Code はそれらの `systemMessage` と `continue` フィールドを破棄しますが、[`terminalSequence`](#emit-terminal-notifications) は引き続き出力します。デスクトップ通知の例はこれに依存しています。Notification フックは、通知を外部サービスに転送するなどの副作用を目的としています。
2559 2558
2560<h3 id="subagentstart">2559<h3 id="subagentstart">
2561 SubagentStart2560 SubagentStart
2562</h3>2561</h3>
2563 2562
2564Claude が Agent ツールでサブエージェントを生成したとき、Claude が[サブエージェントを再開](/docs/ja/sub-agents#resume-subagents)したとき、およびインプロセスの[エージェントチーム](/docs/ja/agent-teams)のチームメイトが新しいメッセージを処理するたびに実行されます。エージェントタイプ名でフィルタリングする matcher をサポートしています。組み込みエージェントの場合、これは `general-purpose`、`Explore`、`Plan` のようなエージェント名です。[カスタムサブエージェント](/docs/ja/sub-agents)の場合、これはファイル名ではなく、エージェントのフロントマターの `name` フィールドです。2563Claude が Agent ツールでサブエージェントを生成したとき、Claude が[サブエージェントを再開](/docs/ja/sub-agents#resume-subagents)したとき、およびインプロセスの[エージェントチーム](/docs/ja/agent-teams)のチームメイトが新しいメッセージを処理するたびに実行されます。エージェントの種類名でフィルタリングする matcher をサポートしています。組み込みエージェントの場合、これは `general-purpose`、`Explore`、`Plan` などのエージェント名です。[カスタムサブエージェント](/docs/ja/sub-agents)の場合、これはファイル名ではなく、エージェントのフロントマターの `name` フィールドです。
2565 2564
2566[プラグイン](/docs/ja/plugins/overview)で提供されるサブエージェントの場合、エージェントタイプは、フロントマターの名前そのものではなく、`my-plugin:reviewer` のようなプラグインスコープの識別子になります。コロンが含まれるとプラグインスコープの名前は正規表現として扱われるため、完全一致させるには matcher を `^` と `$` で固定します: `^my-plugin:reviewer$`。2565[プラグイン](/docs/ja/plugins/overview)に同梱されたサブエージェントの場合、エージェントの種類は素のフロントマターの名前ではなく、`my-plugin:reviewer` のようなプラグインスコープの識別子になります。コロンが含まれるとプラグインスコープの名前は正規表現として扱われるため、完全一致させるには matcher を `^` と `$` で固定してください: `^my-plugin:reviewer$`。
2567 2566
2568<h4 id="subagentstart-input">2567<h4 id="subagentstart-input">
2569 SubagentStart の入力2568 SubagentStart の入力
2570</h4>2569</h4>
2571 2570
2572[共通入力フィールド](#common-input-fields)に加えて、SubagentStart フックは、サブエージェントの一意の識別子を含む `agent_id` と、matcher がフィルタリングに使うエージェント名を含む `agent_type` を受け取ります。2571[共通入力フィールド](#common-input-fields)に加えて、SubagentStart フックは、サブエージェントの一意の識別子を含む `agent_id` と、matcher がフィルタリングに使用するエージェント名を含む `agent_type` を受け取ります。
2573 2572
2574```json theme={null}2573```json theme={null}
2575{2574{
2582}2581}
2583```2582```
2584 2583
2585SubagentStart フックはサブエージェントの作成をブロックすることはできませんが、サブエージェントにコンテキストを注入することはできます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、次のフィールドを返すことができます。2584SubagentStart フックはサブエージェントの作成をブロックできませんが、サブエージェントにコンテキストを注入できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、次のフィールドを返すことができます。
2586 2585
2587| フィールド | 説明 |2586| フィールド | 説明 |
2588| :- | :- |2587| :- | :- |
2589| `additionalContext` | 会話の開始時、最初のプロンプトの前にサブエージェントのコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |2588| `additionalContext` | サブエージェントの会話の開始時、最初のプロンプトの前に、サブエージェントのコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
2590 2589
2591```json theme={null}2590```json theme={null}
2592{2591{
2597}2596}
2598```2597```
2599 2598
2600同じサブエージェントに対してフックが再度実行された場合、Claude Code は、サブエージェントのコンテキストに以前の実行で注入したコピーがまだ残っていない場合にのみ、返されたコンテキストを注入します。起動時に注入されたコピーはそのまま残るため、サブエージェントの[プロンプトキャッシュ](/docs/ja/prompt-caching#subagents-and-the-cache)は損なわれません。[自動圧縮](/docs/ja/sub-agents#auto-compaction)によってそのコピーが破棄された後は、Claude Code は次の実行のコンテキストを再び注入します。2599同じサブエージェントに対してフックが再度実行された場合、Claude Code は、サブエージェントのコンテキストに以前の実行で得たコピーがまだ含まれていない場合にのみ、返されたコンテキストを注入します。起動時に注入されたコピーはそのまま残るため、サブエージェントの[プロンプトキャッシュ](/docs/ja/prompt-caching#subagents-and-the-cache)は損なわれません。[自動圧縮](/docs/ja/sub-agents#auto-compaction)によってそのコピーが破棄された後は、Claude Code は次の実行のコンテキストを再び注入します。
2601 2600
2602<h3 id="subagentstop">2601<h3 id="subagentstop">
2603 SubagentStop2602 SubagentStop
2604</h3>2603</h3>
2605 2604
2606Claude Code のサブエージェントが応答を終えたときに実行されます。エージェントタイプでマッチします。値は SubagentStart と同じです。2605Claude Code のサブエージェントが応答を終えたときに実行されます。エージェントの種類でマッチします。値は SubagentStart と同じです。
2607 2606
2608<h4 id="subagentstop-input">2607<h4 id="subagentstop-input">
2609 SubagentStop の入力2608 SubagentStop の入力
2610</h4>2609</h4>
2611 2610
2612[共通入力フィールド](#common-input-fields)に加えて、SubagentStop フックは `stop_hook_active`、`agent_id`、`agent_type`、`agent_transcript_path`、`last_assistant_message` を受け取ります。`agent_type` フィールドは matcher のフィルタリングに使用される値です。`transcript_path` はメインセッションのトランスクリプトで、`agent_transcript_path` はネストされた `subagents/` フォルダーに保存されるサブエージェント自身のトランスクリプトです。`last_assistant_message` フィールドにはサブエージェントの最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにそれを参照できます。2611[共通入力フィールド](#common-input-fields)に加えて、SubagentStop フックは `stop_hook_active`、`agent_id`、`agent_type`、`agent_transcript_path`、`last_assistant_message` を受け取ります。`agent_type` フィールドは matcher のフィルタリングに使用される値です。`transcript_path` はメインセッションのトランスクリプトであり、`agent_transcript_path` はネストされた `subagents/` フォルダーに保存されたサブエージェント自身のトランスクリプトです。`last_assistant_message` フィールドにはサブエージェントの最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにそれにアクセスできます。
2613 2612
2614すべての SubagentStop イベントが、Claude が生成したサブエージェントから来るわけではありません。Claude Code は、[プロンプトの提案](/docs/ja/interactive-mode#prompt-suggestions)や [`/btw` のサイドクエスチョン](/docs/ja/interactive-mode#side-questions-with-%2Fbtw)など、自身の一部の機能のために内部エージェントも実行しており、それらが終了したときにも SubagentStop が発火します。これらのイベントでは、`agent_type` は、[`--agent`](/docs/ja/cli-reference#cli-flags) や [`agent` 設定](/docs/ja/settings-reference#agent)で設定されたものなど、セッション自体が実行されているエージェント名になり、セッションがエージェントなしで実行されている場合は空文字列になります。2613すべての SubagentStop イベントが、Claude が生成したサブエージェントから来るわけではありません。Claude Code は、[プロンプトの提案](/docs/ja/interactive-mode#prompt-suggestions)や [`/btw` による脇道の質問](/docs/ja/interactive-mode#side-questions-with-%2Fbtw)など、一部の独自機能のために内部エージェントも実行しており、それらが終了したときにも SubagentStop が発火します。これらのイベントでは、`agent_type` はセッション自体が実行されているエージェント名([`--agent`](/docs/ja/cli-reference#cli-flags) や [`agent` 設定](/docs/ja/settings-reference#agent)で設定されたものなど)になり、セッションがエージェントなしで実行されている場合は空文字列になります。
2615 2614
2616エージェントタイプを指定する `matcher` は、空の `agent_type` にはマッチしません。matcher が省略されているか、`""` または `"*"` であるか、空文字列にマッチする正規表現であるフックは、空の `agent_type` のイベントでも実行されます。2615エージェントの種類を指定する `matcher` は、空の `agent_type` にはマッチしません。matcher が省略されている、`""` または `"*"` である、あるいは空文字列にマッチする正規表現であるフックは、空の `agent_type` のイベントでも実行されます。
2617 2616
2618Claude Code v2.1.271 以降では、[`SubagentHandback`](/docs/ja/tools-reference) ツールを使って実行されるサブエージェントは、停止する前にそのツールを通じてレポートを渡します。その場合、`last_assistant_message` フィールドにはサブエージェントの締めくくりのテキスト(ある場合)が入り、渡されたレポートは含まれません。レポートはその呼び出しの `message` 入力であり、`SubagentHandback` にマッチする `PreToolUse` または `PostToolUse` フックは、それを `tool_input.message` として受け取ります。2617Claude Code v2.1.271 以降では、[`SubagentHandback`](/docs/ja/tools-reference) ツールを使用して実行されるサブエージェントは、停止する前にそのツールを通じてレポートを配信します。その場合、`last_assistant_message` フィールドにはサブエージェントの締めくくりのテキスト(存在する場合)が含まれ、これは配信されたレポートではありません。レポートはその呼び出しの `message` 入力であり、`SubagentHandback` にマッチした `PreToolUse` または `PostToolUse` フックは、それを `tool_input.message` として受け取ります。
2619 2618
2620SubagentStop フックは、[Stop の入力](#stop-input)で説明している `background_tasks` と `session_crons` の配列も受け取ります。どちらの配列も、サブエージェントではなく親セッションを対象としています。2619SubagentStop フックは、[Stop の入力](#stop-input)で説明されている `background_tasks` と `session_crons` の配列も受け取ります。どちらの配列も、サブエージェントではなく親セッションをスコープとしています。
2621 2620
2622```json theme={null}2621```json theme={null}
2623{2622{
2636}2635}
2637```2636```
2638 2637
2639SubagentStop フックは [Stop フック](#stop-decision-control)と同じ判定制御形式を使用します。これには、サブエージェントを実行し続けるエラー以外のフィードバックのために、`hookEventName` を `"SubagentStop"` に設定した `hookSpecificOutput.additionalContext` も含まれます。`reason` とともに `decision: "block"` を返すと、サブエージェントは実行を続け、`reason` が次の指示としてサブエージェントに渡されます。終了コード 2 でブロックするフックも、同じ方法で stderr のメッセージを渡します。サブエージェントが戻った後に親セッションにコンテキストを注入するには、代わりに `Agent` ツールに対する [`PostToolUse`](#posttooluse) フックを使用してください。2638SubagentStop フックは、[Stop フック](#stop-decision-control)と同じ決定制御の形式を使用します。これには、サブエージェントの実行を継続させるエラー以外のフィードバック用の、`hookEventName` を `"SubagentStop"` に設定した `hookSpecificOutput.additionalContext` も含まれます。`reason` とともに `decision: "block"` を返すと、サブエージェントの実行が継続され、`reason` が次の指示としてサブエージェントに配信されます。終了コード 2 でブロックするフックも、同じ方法で stderr メッセージを配信します。サブエージェントが戻った後に親セッションにコンテキストを注入するには、代わりに `Agent` ツールに対する [`PostToolUse`](#posttooluse) フックを使用してください。
2640 2639
2641<h3 id="taskcreated">2640<h3 id="taskcreated">
2642 TaskCreated2641 TaskCreated
2643</h3>2642</h3>
2644 2643
2645`TaskCreate` ツールでタスクが作成されるときに実行されます。命名規則を強制したり、タスクの説明を必須にしたり、特定のタスクの作成を阻止したりするために使用します。[Task ツールがないセッション](/docs/ja/tools-reference#task-tool-availability)では、このイベントは発火しません。2644`TaskCreate` ツールを介してタスクが作成されるときに実行されます。命名規則の強制、タスクの説明の必須化、特定のタスクの作成の防止に使用します。[Task ツールのないセッション](/docs/ja/tools-reference#task-tool-availability)では、このイベントは発火しません。
2646 2645
2647TaskCreated フックは matcher をサポートしておらず、発生するたびに発火します。2646TaskCreated フックは matcher をサポートしておらず、発生するたびに発火します。
2648 2647
2672| `task_subject` | タスクのタイトル |2671| `task_subject` | タスクのタイトル |
2673| `task_description` | タスクの詳細な説明。存在しない場合があります |2672| `task_description` | タスクの詳細な説明。存在しない場合があります |
2674| `teammate_name` | タスクを作成するチームメイトの名前。存在しない場合があります |2673| `teammate_name` | タスクを作成するチームメイトの名前。存在しない場合があります |
2675| `team_name` | 非推奨。セッションから導出されたチーム名。今後のリリースで削除されます |2674| `team_name` | 非推奨。セッションから派生したチーム名。将来のリリースで削除されます |
2675| `agent_id` | このイベントでは、この[共通入力フィールド](#common-input-fields)はタスクを作成するサブエージェントまたは[インプロセスのチームメイト](/docs/ja/agent-teams#choose-a-display-mode)を識別します。存在しない場合があります。Claude Code v2.1.290 以降が必要です |
2676 2676
2677<h4 id="taskcreated-decision-control">2677<h4 id="taskcreated-decision-control">
2678 TaskCreated の判定制御2678 TaskCreated の決定制御
2679</h4>2679</h4>
2680 2680
2681TaskCreated フックは、2 つの方法で作成をブロックできます。いずれの場合も、Claude Code はタスクを削除し、メッセージをツールのエラーとして Claude に返します。このイベントからの `continue: false` は Claude Code によって無視され、Claude は作業を続けます。2681TaskCreated フックは 2 つの方法で作成をブロックできます。いずれの場合も、Claude Code はタスクを削除し、メッセージをツールのエラーとして Claude に返します。Claude Code はこのイベントからの `continue: false` を無視し、Claude は作業を続けます。
2682 2682
2683* **終了コード 2**: Claude Code は stderr のテキストをメッセージとして返します。2683* **終了コード 2**: Claude Code は stderr のテキストをメッセージとして返します。
2684* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code は `reason` をメッセージとして返します。2684* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code は `reason` をメッセージとして返します。
2685 2685
2686次の例は、件名が必要な形式に従っていないタスクをブロックします。2686この例では、件名が必須の形式に従っていないタスクをブロックします。
2687 2687
2688```bash theme={null}2688```bash theme={null}
2689#!/bin/bash2689#!/bin/bash
2702 TaskCompleted2702 TaskCompleted
2703</h3>2703</h3>
2704 2704
2705タスクが完了としてマークされるときに実行されます。これは 2 つの状況で発火します。いずれかのエージェントが TaskUpdate ツールを通じてタスクを明示的に完了としてマークした場合と、[エージェントチーム](/docs/ja/agent-teams)のチームメイトが進行中のタスクを抱えたままターンを終えた場合です。タスクを閉じる前に、テストや lint チェックの合格などの完了基準を強制するために使用します。2705タスクが完了としてマークされるときに実行されます。これは 2 つの状況で発火します。いずれかのエージェントが TaskUpdate ツールを通じて明示的にタスクを完了としてマークしたとき、または[エージェントチーム](/docs/ja/agent-teams)のチームメイトが進行中のタスクを抱えたままターンを終えたときです。タスクを閉じる前に、テストや lint チェックの合格などの完了基準を強制するために使用します。
2706 2706
2707TaskCompleted フックは matcher をサポートしておらず、発生するたびに発火します。2707TaskCompleted フックは matcher をサポートしておらず、発生するたびに発火します。
2708 2708
2733| `task_subject` | タスクのタイトル |2733| `task_subject` | タスクのタイトル |
2734| `task_description` | タスクの詳細な説明。存在しない場合があります |2734| `task_description` | タスクの詳細な説明。存在しない場合があります |
2735| `teammate_name` | タスクを完了するチームメイトの名前。存在しない場合があります |2735| `teammate_name` | タスクを完了するチームメイトの名前。存在しない場合があります |
2736| `team_name` | 非推奨。セッションから導出されたチーム名。今後のリリースで削除されます |2736| `team_name` | 非推奨。セッションから派生したチーム名。将来のリリースで削除されます |
2737| `agent_id` | このイベントでは、この[共通入力フィールド](#common-input-fields)はタスクを完了するサブエージェントまたは[インプロセスのチームメイト](/docs/ja/agent-teams#choose-a-display-mode)を識別します。存在しない場合があります。Claude Code v2.1.290 以降が必要です |
2737 2738
2738<h4 id="taskcompleted-decision-control">2739<h4 id="taskcompleted-decision-control">
2739 TaskCompleted の判定制御2740 TaskCompleted の決定制御
2740</h4>2741</h4>
2741 2742
2742TaskCompleted フックは、タスクの完了を制御する 2 つの方法をサポートしています。2743TaskCompleted フックは、タスクの完了を制御する 2 つの方法をサポートしています。
2743 2744
2744* **終了コード 2**: タスクは完了としてマークされず、stderr のメッセージがフィードバックとしてモデルに返されます。2745* **終了コード 2**: タスクは完了としてマークされず、stderr メッセージがフィードバックとしてモデルに返されます。
2745* **JSON `{"continue": false, "stopReason": "..."}`**: チームメイトがターンを終えたことでイベントがトリガーされた場合、`Stop` フックの動作と同様にチームメイトを完全に停止します。`stopReason` はユーザーに表示されます。`TaskUpdate` ツールによってイベントがトリガーされた場合、Claude Code は `continue: false` を無視します。その場合でも終了コード 2 は完了をブロックします。2746* **JSON `{"continue": false, "stopReason": "..."}`**: チームメイトがターンを終えたことでイベントがトリガーされた場合、`Stop` フックの動作と同様に、チームメイトを完全に停止します。`stopReason` はユーザーに表示されます。`TaskUpdate` ツールがイベントをトリガーした場合、Claude Code は `continue: false` を無視します。終了コード 2 では引き続き完了がブロックされます。
2746 2747
2747次の例はテストを実行し、失敗した場合はタスクの完了をブロックします。2748この例では、テストを実行し、失敗した場合にタスクの完了をブロックします。
2748 2749
2749```bash theme={null}2750```bash theme={null}
2750#!/bin/bash2751#!/bin/bash
2764 Stop2765 Stop
2765</h3>2766</h3>
2766 2767
2767メインの Claude Code エージェントが応答を終えたときに実行されます。ユーザーによる中断で停止した場合は実行されません。API エラーの場合は、代わりに [StopFailure](#stopfailure) が発火します。2768メインの Claude Code エージェントが応答を終えたときに実行されます。
2769停止がユーザーによる中断によって発生した場合は実行されません。API エラーの場合は、
2770代わりに [StopFailure](#stopfailure) が発火します。
2768 2771
2769<Tip>2772<Tip>
2770 [`/goal`](/docs/ja/goal) コマンドは、セッションスコープのプロンプトベースの Stop フックの組み込みショートカットです。フック設定を書かずに、ある条件に向けて Claude に作業を続けさせたい場合に使用します。2773 [`/goal`](/docs/ja/goal) コマンドは、セッションスコープのプロンプトベースの Stop フックの組み込みショートカットです。フックの設定を書かずに、ある条件に向けて Claude に作業を続けさせたい場合に使用します。
2771</Tip>2774</Tip>
2772 2775
2773<h4 id="stop-input">2776<h4 id="stop-input">
2774 Stop の入力2777 Stop の入力
2775</h4>2778</h4>
2776 2779
2777[共通の入力フィールド](#common-input-fields)に加えて、Stop フックは `stop_hook_active`、`last_assistant_message`、`background_tasks`、`session_crons` を受け取ります。`stop_hook_active` フィールドは、Claude Code が Stop フックの結果としてすでに継続している場合に `true` になります。解決しない条件でブロックし続けることを避けるため、この値を確認するか、トランスクリプトを処理してください。2780[共通入力フィールド](#common-input-fields)に加えて、Stop フックは `stop_hook_active`、`last_assistant_message`、`background_tasks`、`session_crons` を受け取ります。`stop_hook_active` フィールドは、Claude Code がすでに stop フックの結果として続行している場合に `true` になります。決して解決しない条件でブロックし続けることを避けるため、この値を確認するか、トランスクリプトを処理してください。
2778 2781
2779Claude Code は連続 8 回の継続上限を適用します。Stop フックがターンを 8 回連続で継続させた後、Claude Code は次のブロックを上書きしてターンを終了します。連続継続の回数は、Claude がツールを呼び出すたびにリセットされます。上限を引き上げるには、[`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/ja/env-vars) を設定します。2782Claude Code は 8 回連続の続行上限を適用します。stop フックがターンを 8 回連続で続行させた後、Claude Code は次のブロックを上書きしてターンを終了します。連続続行の回数は、Claude がツールを呼び出すたびにリセットされます。上限を引き上げるには、[`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/ja/env-vars) を設定します。
2780 2783
2781`last_assistant_message` フィールドには Claude の最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにそれを参照できます。読み上げや通知のフックなど、完了したばかりのターンに対して動作するフックでは、`transcript_path` を読み取るのではなくこのフィールドを使用してください。すべてのバージョンで、Stop の時点でトランスクリプトファイルに最終メッセージが含まれているとは限りません。2784`last_assistant_message` フィールドには Claude の最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにそれにアクセスできます。読み上げフックや通知フックなど、完了したばかりのターンに対して動作するフックでは、`transcript_path` を読み取るのではなく、このフィールドを使用してください。すべてのバージョンで、Stop の時点でトランスクリプトファイルに最終メッセージが含まれていることは保証されていません。
2782 2785
2783`background_tasks` と `session_crons` の配列により、フックは「セッションが完了した」状態と「セッションが一時停止し、バックグラウンドの作業によって再び起こされるのを待っている」状態を区別できます。どちらの配列も、タスクレジストリにアクセスできる場合に存在し、進行中またはスケジュール済みのものがない場合は空になります。2786`background_tasks` と `session_crons` の配列により、フックは「セッションが完了した」状態と「セッションがバックグラウンドの作業によって再開されるのを待って一時停止している」状態を区別できます。どちらの配列も、タスクレジストリにアクセスできる場合に存在し、実行中またはスケジュール済みのものがない場合は空になります。
2784 2787
2785`background_tasks` の各エントリは進行中のタスク 1 つを表し、次のフィールドを使用します。2788`background_tasks` の各エントリは実行中の 1 つのタスクを記述し、次のフィールドを使用します。
2786 2789
2787| フィールド | 説明 |2790| フィールド | 説明 |
2788| :- | :- |2791| :- | :- |
2789| `id` | タスクの識別子 |2792| `id` | タスクの識別子 |
2790| `type` | `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session`、`MCP task` など、わかりやすいタスクタイプのラベル。各ラベルは、タスクを作成した Claude Code の機能を示します。認識されないタイプの場合は、生の判別値が使われます |2793| `type` | `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session`、`MCP task` などの、わかりやすいタスクの種類のラベル。各ラベルは、どの Claude Code 機能がタスクを作成したかを示します。認識されない種類の場合は、生の判別値にフォールバックします |
2791| `status` | 現在のタスクの状態 |2794| `status` | 現在のタスクのステータス |
2792| `description` | 自由形式の説明。上限は 1000 文字で、切り詰められた場合は文字列内に `… [+N chars]` マーカーが付きます |2795| `description` | 自由記述の説明。1000 文字が上限で、切り詰められた場合は文字列内に `… [+N chars]` マーカーが付きます |
2793| `command` | シェルのコマンドライン。上限は 1000 文字です。`shell` タスクにのみ存在します |2796| `command` | シェルのコマンドライン。1000 文字が上限です。`shell` タスクの場合のみ存在します |
2794| `agent_type` | サブエージェントのタイプ名。`subagent` タスクにのみ存在します |2797| `agent_type` | サブエージェントの種類名。`subagent` タスクの場合のみ存在します |
2795| `server` | MCP サーバー名。`monitor` と `MCP task` タスクにのみ存在します |2798| `server` | MCP サーバー名。`monitor` および `MCP task` タスクの場合のみ存在します |
2796| `tool` | MCP ツール名。`monitor` と `MCP task` タスクにのみ存在します |2799| `tool` | MCP ツール名。`monitor` および `MCP task` タスクの場合のみ存在します |
2797| `name` | ワークフロー名。`workflow` タスクにのみ存在します |2800| `name` | ワークフロー名。`workflow` タスクの場合のみ存在します |
2798 2801
2799`session_crons` の各エントリは、`CronCreate`、`ScheduleWakeup`、`/loop` から作成された、セッションスコープのスケジュール済みウェイクアップ 1 つを表します。2802`session_crons` の各エントリは、`CronCreate`、`ScheduleWakeup`、`/loop` から取得された、セッションスコープのスケジュール済みウェイクアップを 1 つ記述します。
2800 2803
2801| フィールド | 説明 |2804| フィールド | 説明 |
2802| :- | :- |2805| :- | :- |
2803| `id` | cron タスクの識別子 |2806| `id` | cron タスクの識別子 |
2804| `schedule` | cron 式。例: `0 9 * * 1-5` |2807| `schedule` | cron 式。例: `0 9 * * 1-5` |
2805| `recurring` | スケジュールが単一の発火時刻を表す 1 回限りのウェイクアップの場合は `false`、マッチするたびに再発火するタスクの場合は `true` |2808| `recurring` | スケジュールが単一の発火時刻を表す 1 回限りのウェイクアップの場合は `false`、マッチするたびに再発火するタスクの場合は `true` |
2806| `prompt` | cron の発火時に送信されるプロンプト。上限は 1000 文字で、同じ `… [+N chars]` マーカーが付きます |2809| `prompt` | cron の発火時に送信されるプロンプト。1000 文字が上限で、同じ `… [+N chars]` マーカーが付きます |
2807 2810
2808次の例は、進行中の shell タスク 1 つと繰り返しの cron 1 つを含む Stop の入力を示しています。2811この例は、実行中のシェルタスクが 1 つと、繰り返しの cron が 1 つある Stop の入力を示しています。
2809 2812
2810```json theme={null}2813```json theme={null}
2811{2814{
2837```2840```
2838 2841
2839<h4 id="stop-decision-control">2842<h4 id="stop-decision-control">
2840 Stop の判定制御2843 Stop の決定制御
2841</h4>2844</h4>
2842 2845
2843`Stop` と `SubagentStop` フックは、Claude が続行するかどうかを制御できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有フィールドを返すことができます。2846`Stop` および `SubagentStop` フックは、Claude が続行するかどうかを制御できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有のフィールドを返すことができます。
2844 2847
2845| フィールド | 説明 |2848| フィールド | 説明 |
2846| :- | :- |2849| :- | :- |
2847| `decision` | `"block"` を指定すると Claude の停止を阻止します。Claude の停止を許可するには省略します |2850| `decision` | `"block"` は Claude の停止を防ぎます。Claude の停止を許可するには省略します |
2848| `reason` | `decision` が `"block"` の場合は必須です。Claude に続行すべき理由を伝えます |2851| `reason` | `decision` が `"block"` の場合は必須です。Claude に続行すべき理由を伝えます |
2849| `hookSpecificOutput.additionalContext` | Claude へのエラー以外のフィードバック。Claude がそれに基づいて行動できるよう会話は続行しますが、`decision: "block"` とは異なり、トランスクリプトにはフックエラーではなくフックのフィードバックとして表示されます |2852| `hookSpecificOutput.additionalContext` | Claude へのエラー以外のフィードバック。Claude がそれに対応できるよう会話は続行されますが、`decision: "block"` とは異なり、トランスクリプトにはフックエラーではなくフックのフィードバックとして表示されます |
2850 2853
2851終了コード 2 でブロックするフックは、`reason` と同じように扱われます。Claude は続行すべき理由の説明として stderr のメッセージを受け取ります。2854終了コード 2 でブロックするフックは、`reason` と同じ方法で処理されます。Claude は、続行すべき理由の説明として stderr メッセージを受け取ります。
2852 2855
2853```json theme={null}2856```json theme={null}
2854{2857{
2857}2860}
2858```2861```
2859 2862
2860フックが設計どおりに動作しており、「終了する前にテストスイートを実行してください」のようなガイダンスを Claude に与えている場合は、`additionalContext` を使用します。これは `decision: "block"` と同じループ保護、つまり `stop_hook_active` 入力と連続 8 回の続行上限を通じて会話を続行させますが、トランスクリプトでは `Stop hook feedback` というラベルが付き、フックエラーの通知は表示されません。2863フックが設計どおりに動作し、「終了する前にテストスイートを実行する」などのガイダンスを Claude に与えている場合は、`additionalContext` を使用します。これは `decision: "block"` と同じループ保護(`stop_hook_active` 入力と 8 回連続の続行上限)を通じて会話を継続させますが、トランスクリプトでは `Stop hook feedback` とラベル付けされ、フックエラーの通知は表示されません。
2861 2864
2862```json theme={null}2865```json theme={null}
2863{2866{
2872 StopFailure2875 StopFailure
2873</h3>2876</h3>
2874 2877
2875API エラーによってターンが終了した場合に、[Stop](#stop) の代わりに実行されます。Claude Code は、[`terminalSequence`](#emit-terminal-notifications) を除き、フックの出力と終了コードを無視します。レート制限、認証の問題、その他の API エラーのために Claude が応答を完了できない場合に、失敗のログ記録、アラートの送信、または回復アクションの実行に使用します。2878API エラーによってターンが終了したときに、[Stop](#stop) の代わりに実行されます。Claude Code は、[`terminalSequence`](#emit-terminal-notifications) を除き、フックの出力と終了コードを無視します。レート制限、認証の問題、その他の API エラーによって Claude が応答を完了できない場合に、失敗のログ記録、アラートの送信、または復旧アクションの実行に使用します。
2876 2879
2877<h4 id="stopfailure-input">2880<h4 id="stopfailure-input">
2878 StopFailure の入力2881 StopFailure の入力
2884| :- | :- |2887| :- | :- |
2885| `error` | エラーの種類: `rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error`、または `unknown` |2888| `error` | エラーの種類: `rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error`、または `unknown` |
2886| `error_details` | エラーに関する追加の詳細(利用可能な場合) |2889| `error_details` | エラーに関する追加の詳細(利用可能な場合) |
2887| `last_assistant_message` | 会話に表示されるレンダリング済みのエラーテキスト。このフィールドに Claude の会話出力が入る `Stop` や `SubagentStop` とは異なり、`StopFailure` では `"API Error: Rate limit reached"` のような API エラー文字列そのものが入ります |2890| `last_assistant_message` | 会話に表示されるレンダリングされたエラーテキスト。このフィールドに Claude の会話出力が含まれる `Stop` や `SubagentStop` とは異なり、`StopFailure` では `"API Error: Rate limit reached"` のような API エラー文字列そのものが含まれます |
2888 2891
2889```json theme={null}2892```json theme={null}
2890{2893{
2898}2901}
2899```2902```
2900 2903
2901StopFailure フックには判定制御がありません。通知とログ記録の目的でのみ実行されます。2904StopFailure フックには決定制御がありません。通知とログ記録の目的でのみ実行されます。
2902 2905
2903<h3 id="teammateidle">2906<h3 id="teammateidle">
2904 TeammateIdle2907 TeammateIdle
2929| フィールド | 説明 |2932| フィールド | 説明 |
2930| :- | :- |2933| :- | :- |
2931| `teammate_name` | アイドル状態になろうとしているチームメイトの名前 |2934| `teammate_name` | アイドル状態になろうとしているチームメイトの名前 |
2932| `team_name` | 非推奨。セッションから導出されたチーム名。今後のリリースで削除されます |2935| `team_name` | 非推奨。セッションから派生したチーム名。将来のリリースで削除されます |
2936| `agent_id` | このイベントでは、この[共通入力フィールド](#common-input-fields)はアイドル状態になろうとしている[インプロセスのチームメイト](/docs/ja/agent-teams#choose-a-display-mode)を識別します。存在しない場合があります。Claude Code v2.1.290 以降が必要です |
2933 2937
2934<h4 id="teammateidle-decision-control">2938<h4 id="teammateidle-decision-control">
2935 TeammateIdle の判定制御2939 TeammateIdle の決定制御
2936</h4>2940</h4>
2937 2941
2938TeammateIdle フックは、チームメイトの動作を制御する 2 つの方法をサポートしています。2942TeammateIdle フックは、チームメイトの動作を制御する 2 つの方法をサポートしています。
2939 2943
2940* **終了コード 2**: チームメイトは stderr のメッセージをフィードバックとして受け取り、アイドル状態にならずに作業を続けます。2944* **終了コード 2**: チームメイトは stderr メッセージをフィードバックとして受け取り、アイドル状態にならずに作業を続けます。
2941* **JSON `{"continue": false, "stopReason": "..."}`**: `Stop` フックの動作と同様に、チームメイトを完全に停止します。`stopReason` はユーザーに表示されます。2945* **JSON `{"continue": false, "stopReason": "..."}`**: `Stop` フックの動作と同様に、チームメイトを完全に停止します。`stopReason` はユーザーに表示されます。
2942 2946
2943次の例は、チームメイトがアイドル状態になるのを許可する前に、ビルドアーティファクトが存在することを確認します。2947この例では、チームメイトがアイドル状態になるのを許可する前に、ビルドアーティファクトが存在することを確認します。
2944 2948
2945```bash theme={null}2949```bash theme={null}
2946#!/bin/bash2950#!/bin/bash
2957 ConfigChange2961 ConfigChange
2958</h3>2962</h3>
2959 2963
2960セッション中に設定ファイルが変更されたときに実行されます。設定変更の監査、セキュリティポリシーの強制、または設定ファイルへの不正な変更のブロックに使用します。2964セッション中に設定ファイルが変更されたときに実行されます。設定変更の監査、セキュリティポリシーの強制、設定ファイルへの不正な変更のブロックに使用します。
2961 2965
2962Claude Code は、設定ファイル、管理ポリシーファイル、またはスキルファイルが変更されたときに ConfigChange フックを実行します。管理ポリシーについては、`managed-settings.json` または `managed-settings.d/` 内のファイルが変更された場合にのみ実行します。[サーバー管理設定](/docs/ja/server-managed-settings)や、macOS の管理された環境設定、Windows レジストリのポリシーへの変更は、フックを実行せずに適用します。[`wslInheritsWindowsSettings`](/docs/ja/settings-reference#wslinheritswindowssettings) を使用している WSL では、Windows 側の管理設定ファイルの変更も、ポリシーのポーリング時にフックを実行せずに適用します。2966Claude Code は、設定ファイル、管理ポリシーファイル、またはスキルファイルが変更されたときに ConfigChange フックを実行します。管理ポリシーについては、`managed-settings.json` または `managed-settings.d/` 内のファイルが変更された場合にのみ実行します。[サーバー管理設定](/docs/ja/server-managed-settings)や、macOS の管理された環境設定または Windows レジストリポリシーへの変更は、フックを実行せずに適用します。[`wslInheritsWindowsSettings`](/docs/ja/settings-reference#wslinheritswindowssettings) を使用した WSL では、変更された Windows 側の管理設定ファイルも、ポリシーのポーリング時にフックを実行せずに適用します。
2963 2967
2964matcher は設定のソースでフィルタリングします。2968matcher は設定のソースでフィルタリングします。
2965 2969
2966| Matcher | 発火するタイミング |2970| Matcher | 発火するタイミング |
2967| :- | :- |2971| :- | :- |
2968| `user_settings` | `~/.claude/settings.json` が変更された |2972| `user_settings` | `~/.claude/settings.json` が変更された場合 |
2969| `project_settings` | `.claude/settings.json` が変更された |2973| `project_settings` | `.claude/settings.json` が変更された場合 |
2970| `local_settings` | `.claude/settings.local.json` が変更された |2974| `local_settings` | `.claude/settings.local.json` が変更された場合 |
2971| `policy_settings` | `managed-settings.json` または `managed-settings.d/` 内のファイルが変更された |2975| `policy_settings` | `managed-settings.json` または `managed-settings.d/` 内のファイルが変更された場合 |
2972| `skills` | `.claude/skills/` 内のスキルファイルが変更された |2976| `skills` | `.claude/skills/` 内のスキルファイルが変更された場合 |
2973 2977
2974次の例は、セキュリティ監査のためにすべての設定変更をログに記録します。2978この例では、セキュリティ監査のためにすべての設定変更をログに記録します。
2975 2979
2976```json theme={null}2980```json theme={null}
2977{2981{
2995 ConfigChange の入力2999 ConfigChange の入力
2996</h4>3000</h4>
2997 3001
2998[共通入力フィールド](#common-input-fields)に加えて、ConfigChange フックは `source` と、省略可能な `file_path` を受け取ります。`source` フィールドはどの種類の設定が変更されたかを示し、`file_path` は変更された特定のファイルのパスを示します。3002[共通入力フィールド](#common-input-fields)に加えて、ConfigChange フックは `source` と、省略可能な `file_path` を受け取ります。`source` フィールドはどの種類の設定が変更されたかを示し、`file_path` は変更された特定のファイルへのパスを提供します。
2999 3003
3000```json theme={null}3004```json theme={null}
3001{3005{
3009```3013```
3010 3014
3011<h4 id="configchange-decision-control">3015<h4 id="configchange-decision-control">
3012 ConfigChange の判定制御3016 ConfigChange の決定制御
3013</h4>3017</h4>
3014 3018
3015ConfigChange フックは、設定変更が反映されるのをブロックできます。変更を阻止するには、終了コード 2 または JSON の `decision` を使用します。ブロックされた場合、新しい設定は実行中のセッションに適用されません。3019ConfigChange フックは、設定変更が有効になるのをブロックできます。変更を防ぐには、終了コード 2 または JSON の `decision` を使用します。ブロックされた場合、新しい設定は実行中のセッションに適用されません。
3016 3020
3017| フィールド | 説明 |3021| フィールド | 説明 |
3018| :- | :- |3022| :- | :- |
3019| `decision` | `"block"` を指定すると、設定変更が適用されるのを阻止します。変更を許可するには省略します |3023| `decision` | `"block"` は設定変更が適用されるのを防ぎます。変更を許可するには省略します |
3020| `reason` | 受け付けられますが、表示されることはありません |3024| `reason` | 受け付けられますが、表示されることはありません |
3021 3025
3022```json theme={null}3026```json theme={null}
3026}3030}
3027```3031```
3028 3032
3029`policy_settings` の変更はブロックできません。マシン上の管理設定ファイルが変更されたときには `policy_settings` ソースに対してもフックが発火するため、それらの編集をログに記録するのには使用できますが、ブロックの判定はすべて無視されます。これにより、エンタープライズで管理される設定が常に反映されることが保証されます。[サーバー管理設定](/docs/ja/server-managed-settings)が届いたときや更新されたときには、Claude Code は `ConfigChange` フックを実行しません。3033`policy_settings` の変更はブロックできません。マシン上の管理設定ファイルが変更されたとき、`policy_settings` ソースに対してもフックは発火するため、それらの編集をログに記録するために使用できますが、ブロックの決定は無視されます。これにより、エンタープライズで管理された設定が常に有効になることが保証されます。[サーバー管理設定](/docs/ja/server-managed-settings)が届いたり更新されたりしたときには、Claude Code は `ConfigChange` フックを実行しません。
3030 3034
3031Claude Code は ConfigChange フックの JSON 出力のうちブロックの判定に従い、`systemMessage` と `continue` は破棄します。ブロックされた変更については、`reason` でブロックした場合も終了コード 2 の stderr でブロックした場合も、ユーザーにも Claude にもメッセージは表示されません。Claude Code はデバッグログに 1 行書き込むだけです。3035Claude Code は ConfigChange フックの JSON 出力からブロックの決定に従って動作し、`systemMessage` と `continue` を破棄します。`reason` でブロックした場合も、終了コード 2 の stderr でブロックした場合も、ブロックされた変更についてユーザーにも Claude にもメッセージは表示されません。Claude Code はデバッグログに 1 行書き込むだけです。
3032 3036
3033<h3 id="cwdchanged">3037<h3 id="cwdchanged">
3034 CwdChanged3038 CwdChanged
3035</h3>3039</h3>
3036 3040
3037メインの会話内のシェルコマンドが作業ディレクトリを変更したとき、たとえば Claude が `cd` コマンドを実行したときに実行されます。ディレクトリの変更に反応して、環境変数の再読み込み、プロジェクト固有のツールチェーンの有効化、セットアップスクリプトの自動実行などを行うために使用します。ディレクトリごとの環境を管理する [direnv](https://direnv.net/) のようなツールでは、[FileChanged](#filechanged) と組み合わせて使用します。3041メインの会話内のシェルコマンドが作業ディレクトリを変更したとき、たとえば Claude が `cd` コマンドを実行したときに実行されます。ディレクトリの変更に反応するために使用します。環境変数の再読み込み、プロジェクト固有のツールチェーンの有効化、セットアップスクリプトの自動実行などが可能です。ディレクトリごとの環境を管理する [direnv](https://direnv.net/) などのツールには、[FileChanged](#filechanged) と組み合わせて使用します。
3038 3042
3039CwdChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の CwdChanged イベントで Claude Code によってクリアされるまで、後続の Bash コマンドに引き継がれます。3043CwdChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の CwdChanged イベントで Claude Code がクリアするまで、後続の Bash コマンドに引き継がれます。
3040 3044
3041CwdChanged は matcher をサポートしておらず、発生するたびに発火します。3045CwdChanged は matcher をサポートしておらず、発生するたびに発火します。
3042 3046
3065 3069
3066| フィールド | 説明 |3070| フィールド | 説明 |
3067| :- | :- |3071| :- | :- |
3068| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` 設定のパスは常に監視されます。空の配列を返すと動的リストがクリアされます。これは新しいディレクトリに入るときの典型的な使い方です |3072| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` の設定に含まれるパスは常に監視されます。空の配列を返すと動的なリストがクリアされます。これは新しいディレクトリに入るときの典型的な使い方です |
3069 3073
3070CwdChanged フックには判定制御がありません。ディレクトリの変更をブロックすることはできません。3074CwdChanged フックには決定制御がありません。ディレクトリの変更をブロックすることはできません。
3071 3075
3072Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` を破棄します。対話型セッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。3076Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` を破棄します。対話型セッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。
3073 3077
3075 DirectoryAdded3079 DirectoryAdded
3076</h3>3080</h3>
3077 3081
3078セッションの途中で `/add-dir` コマンドを使って作業ディレクトリを追加した後、または SDK クライアントが `register_repo_root` 制御リクエストで作業ディレクトリを追加した後に実行されます。新たに追加されたリポジトリの準備、たとえば依存関係のインストールに使用します。3082`/add-dir` コマンドでセッションの途中に作業ディレクトリを追加した後、または SDK クライアントが `register_repo_root` 制御リクエストで作業ディレクトリを追加した後に実行されます。新しく追加されたリポジトリの準備(依存関係のインストールなど)に使用します。
3079 3083
3080Claude Code は次の場合にはこのイベントを発火しません。3084Claude Code は次の場合にはこのイベントを発火しません。
3081 3085
3082* `--add-dir` 起動フラグでディレクトリを渡した場合。これらのディレクトリは [SessionStart](#sessionstart) でカバーされます3086* `--add-dir` 起動フラグでディレクトリを渡した場合。これらのディレクトリは [SessionStart](#sessionstart) が対象とします
3083* `/permissions` の Workspace タブでディレクトリを追加した場合3087* `/permissions` の Workspace タブでディレクトリを追加した場合
3084* すでに作業ディレクトリであるディレクトリ、またはその内部にあるディレクトリを追加した場合3088* すでに作業ディレクトリであるか、作業ディレクトリ内にあるディレクトリを追加した場合
3085 3089
3086Claude Code はサンドボックスと権限の状態を更新した後に DirectoryAdded を発火するため、フックが実行される時点で、サンドボックス化されたツールにはすでに新しいディレクトリが見えています。フックコマンド自体はサンドボックス化されずに実行されます。3090Claude Code はサンドボックスと権限の状態を更新した後に DirectoryAdded を発火するため、フックが実行される時点で、サンドボックス化されたツールにはすでに新しいディレクトリが見えています。フックのコマンド自体はサンドボックス外で実行されます。
3087 3091
3088Claude Code はフックを待ちません。追加はすぐに完了し、フックはデフォルトの 600 秒のタイムアウトでバックグラウンドで実行されます。3092Claude Code はフックを待ちません。追加はすぐに完了し、フックは 600 秒のデフォルトのタイムアウトでバックグラウンドで実行されます。
3089 3093
3090matcher は、ディレクトリがどのように追加されたかでフィルタリングします。3094matcher は、ディレクトリがどのように追加されたかでフィルタリングします。
3091 3095
3092| Matcher | 発火するタイミング |3096| Matcher | 発火するタイミング |
3093| :- | :- |3097| :- | :- |
3094| `slash_command` | `/add-dir` でディレクトリを追加した |3098| `slash_command` | `/add-dir` でディレクトリを追加した場合 |
3095| `register_repo_root` | SDK クライアントが `register_repo_root` 制御リクエストでディレクトリを追加した |3099| `register_repo_root` | SDK クライアントが `register_repo_root` 制御リクエストでディレクトリを追加した場合 |
3096 3100
3097<h4 id="directoryadded-input">3101<h4 id="directoryadded-input">
3098 DirectoryAdded の入力3102 DirectoryAdded の入力
3103| フィールド | 説明 |3107| フィールド | 説明 |
3104| :- | :- |3108| :- | :- |
3105| `directory` | 追加されたディレクトリの絶対パス |3109| `directory` | 追加されたディレクトリの絶対パス |
3106| `source` | ディレクトリの追加方法。`/add-dir` の場合は `"slash_command"`、SDK 制御リクエストの場合は `"register_repo_root"` |3110| `source` | ディレクトリがどのように追加されたか。`/add-dir` の場合は `"slash_command"`、SDK の制御リクエストの場合は `"register_repo_root"` |
3107 3111
3108```json theme={null}3112```json theme={null}
3109{3113{
3116}3120}
3117```3121```
3118 3122
3119DirectoryAdded フックには判定制御がありません。フックが実行される時点で追加はすでに完了しているため、追加をブロックすることはできません。Claude Code は JSON 出力から `continue` フィールドを破棄し、残りをソースごとに異なる方法で表示します。3123DirectoryAdded フックには決定制御がありません。フックが実行される時点で追加はすでに完了しているため、追加をブロックすることはできません。Claude Code は JSON 出力から `continue` フィールドを破棄し、残りをソースごとに異なる方法で扱います。
3120 3124
3121* `slash_command`: Claude Code はフックの `systemMessage` をユーザーに表示するのではなく、次の会話ターンでコンテキストとして Claude に渡します。失敗したフックの数がトランスクリプトに表示されます。失敗時の出力全体はデバッグログに記録されます3125* `slash_command`: Claude Code はフックの `systemMessage` を、ユーザーに表示するのではなく、次の会話ターンでコンテキストとして Claude に配信します。失敗したフックの数がトランスクリプトに表示されます。失敗の完全な出力はデバッグログに記録されます
3122* `register_repo_root`: Claude Code は `systemMessage` の出力と失敗時の出力をデバッグログにのみ書き込みます3126* `register_repo_root`: Claude Code は `systemMessage` の出力と失敗の出力をデバッグログにのみ書き込みます
3123 3127
3124<h3 id="filechanged">3128<h3 id="filechanged">
3125 FileChanged3129 FileChanged
3126</h3>3130</h3>
3127 3131
3128監視対象のファイルがディスク上で変更されたときに実行されます。Claude Code はツール呼び出しを調べるのではなく、ファイルシステムウォッチャーで変更を検出するため、何がファイルを変更したかに関係なくフックを実行します。対象となるのは、`Edit` や `Write` のツール呼び出し、Claude が `Bash` で実行するスクリプト、あるいは Claude Code の完全に外部のプロセスです。一般的な用途は、プロジェクトの設定ファイルが変更されたときに環境変数を再読み込みすることです。3132監視対象のファイルがディスク上で変更されたときに実行されます。Claude Code はツール呼び出しを調べるのではなく、ファイルシステムウォッチャーで変更を検出するため、何がファイルを変更したかに関係なくフックを実行します。`Edit` や `Write` のツール呼び出し、Claude が `Bash` で実行したスクリプト、あるいは Claude Code 外部のプロセスのいずれであっても実行されます。一般的な用途は、プロジェクトの設定ファイルが変更されたときに環境変数を再読み込みすることです。
3129 3133
3130このイベントの `matcher` には 2 つの役割があります。3134このイベントの `matcher` は 2 つの役割を果たします。
3131 3135
3132* **監視リストを構築する**: 値は `|` で分割され、各セグメントが作業ディレクトリ内のリテラルなファイル名として登録されます。そのため、`".envrc|.env"` はちょうどその 2 つのファイルを監視します。ここでは正規表現パターンは役に立ちません。`^\.env` のような値は、文字どおり `^\.env` という名前のファイルを監視することになります。3136* **監視リストの構築**: 値は `|` で分割され、各セグメントが作業ディレクトリ内のリテラルなファイル名として登録されます。そのため、`".envrc|.env"` はちょうどその 2 つのファイルを監視します。ここでは正規表現パターンは役に立ちません。`^\.env` のような値は、文字どおり `^\.env` という名前のファイルを監視します。
3133* **実行するフックをフィルタリングする**: 監視対象のファイルが変更されると、同じ値が、変更されたファイルのベース名に対して標準の [matcher ルール](#matcher-patterns)を使い、どのフックグループを実行するかをフィルタリングします。3137* **実行するフックのフィルタリング**: 監視対象のファイルが変更されると、同じ値が、変更されたファイルのベース名に対する標準の [matcher ルール](#matcher-patterns)を使用して、どのフックグループを実行するかをフィルタリングします。
3134 3138
3135次の例は、`Bash` コマンドや外部スクリプトによるファイルの書き換えを含め、あらゆる変更の後に `data.csv` の改行コードを正規化します。3139この例では、`Bash` コマンドや外部スクリプトによるファイルの書き換えを含め、変更があるたびに `data.csv` の改行コードを正規化します。
3136 3140
3137```json theme={null}3141```json theme={null}
3138{3142{
3152}3156}
3153```3157```
3154 3158
3155このフックは、stdin の [JSON 入力](#filechanged-input)の `file_path` フィールドから、変更されたファイルの絶対パスを読み取ります。`grep` によるガードは、`perl` が削除するのと同じもの、つまり行末の CR を検査するため、正規化後の実行ではファイルに触れずに終了します。これより緩いガードだと無限ループになります。`perl -i` は何も置換しなくてもファイルを書き換え、Claude Code は書き換えのたびにフックを再実行するためです。このスクリプトを `/path/to/normalize-line-endings.sh` に保存し、実行可能にしてください。3159フックは、stdin の [JSON 入力](#filechanged-input)の `file_path` フィールドから、変更されたファイルの絶対パスを読み取ります。その `grep` によるガードは、`perl` が削除するのと同じもの、つまり行末の CR をテストするため、正規化後の実行ではファイルに触れずに終了します。より緩いガードにすると無限ループになります。`perl -i` は何も置換しない場合でもファイルを書き換え、Claude Code は書き換えのたびに再びフックを実行するためです。このスクリプトを `/path/to/normalize-line-endings.sh` に保存し、実行可能にしてください。
3156 3160
3157```bash theme={null}3161```bash theme={null}
3158#!/bin/bash3162#!/bin/bash
3164 3168
3165フックが機能することを確認するには、`Bash` コマンドで `data.csv` に CRLF の行を追加するよう Claude に依頼します。Claude Code がフックを実行し、ファイルの改行コードは LF になります。3169フックが機能することを確認するには、`Bash` コマンドで `data.csv` に CRLF の行を追加するよう Claude に依頼します。Claude Code がフックを実行し、ファイルの改行コードは LF になります。
3166 3170
3167事前に名前を指定できないファイルを監視するには、フックから [`watchPaths`](#filechanged-output) を返して監視リストを動的に更新します。Claude Code は、何かが監視するファイルを指定した場合にのみウォッチャーを起動するため、少なくとも 1 つのファイルを指定する matcher を持つ FileChanged グループか、`watchPaths` を返す [SessionStart](#sessionstart-decision-control) または [CwdChanged](#cwdchanged) フックでリストの初期値を設定してください。監視対象のファイルが変更されたとき、matcher は引き続きどのフックグループを実行するかをフィルタリングするため、動的なパスを処理するグループでは matcher を省略してください。省略した matcher はすべての監視対象ファイルにマッチし、監視リストには何も追加しません。`"*"` の matcher もすべてのファイルにマッチしますが、Claude Code はそれを他の値と同様に、`*` という名前のリテラルなファイルとして監視リストに登録します。3171事前に名前を指定できないファイルを監視するには、フックから [`watchPaths`](#filechanged-output) を返して、監視リストを動的に更新します。Claude Code は何かが監視するファイルを指定した場合にのみウォッチャーを開始するため、少なくとも 1 つのファイルを matcher で指定した FileChanged グループ、または `watchPaths` を返す [SessionStart](#sessionstart-decision-control) フックや [CwdChanged](#cwdchanged) フックで、リストに初期値を設定してください。監視対象のファイルが変更されたときにどのフックグループを実行するかは引き続き matcher でフィルタリングされるため、動的なパスを処理するグループでは matcher を省略してください。省略した matcher はすべての監視対象ファイルにマッチし、監視リストには何も追加しません。`"*"` の matcher もすべてのファイルにマッチしますが、Claude Code は他の値と同様に、それを `*` という名前のリテラルなファイルとして監視リストに登録します。
3168 3172
3169FileChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の [CwdChanged](#cwdchanged) イベントで Claude Code によってクリアされるまで、後続の Bash コマンドに引き継がれます。3173FileChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の [CwdChanged](#cwdchanged) イベントで Claude Code がクリアするまで、後続の Bash コマンドに引き継がれます。
3170 3174
3171<h4 id="filechanged-input">3175<h4 id="filechanged-input">
3172 FileChanged の入力3176 FileChanged の入力
3177| フィールド | 説明 |3181| フィールド | 説明 |
3178| :- | :- |3182| :- | :- |
3179| `file_path` | 変更されたファイルの絶対パス |3183| `file_path` | 変更されたファイルの絶対パス |
3180| `event` | 発生した内容: 変更されたファイルの場合は `"change"`、作成されたファイルの場合は `"add"`、削除されたファイルの場合は `"unlink"` |3184| `event` | 何が起きたか。変更されたファイルの場合は `"change"`、作成されたファイルの場合は `"add"`、削除されたファイルの場合は `"unlink"` |
3181 3185
3182```json theme={null}3186```json theme={null}
3183{3187{
3198 3202
3199| フィールド | 説明 |3203| フィールド | 説明 |
3200| :- | :- |3204| :- | :- |
3201| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` 設定のパスは常に監視されます。変更されたファイルに基づいて、フックスクリプトが監視すべき追加のファイルを見つけた場合に使用します |3205| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` の設定に含まれるパスは常に監視されます。フックスクリプトが、変更されたファイルに基づいて監視すべき追加のファイルを見つけた場合に使用します |
3202 3206
3203FileChanged フックには判定制御がありません。ファイルの変更が発生するのをブロックすることはできません。3207FileChanged フックには決定制御がありません。ファイルの変更が発生するのをブロックすることはできません。
3204 3208
3205Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` を破棄します。対話型セッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。3209Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` を破棄します。対話型セッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。
3206 3210
3208 WorktreeCreate3212 WorktreeCreate
3209</h3>3213</h3>
3210 3214
3211worktree が作成されるときに実行されます。対象は、`claude --worktree` から作成される場合、[`isolation: "worktree"` を使用するサブエージェント](/docs/ja/sub-agents#choose-the-subagent-scope)から作成される場合、Claude Code が独自の worktree に分離する[バックグラウンドセッション](/docs/ja/agent-view#how-file-edits-are-isolated)のために作成される場合です。デフォルトでは、Claude Code は `git worktree` を使って分離された作業コピーを作成します。WorktreeCreate フックを設定するとこのデフォルトの Git の動作が置き換えられ、SVN、Perforce、Mercurial などの別のバージョン管理システムを使用できるようになります。3215worktree の作成時に実行されます。`claude --worktree` から作成される場合、[`isolation: "worktree"` を使用するサブエージェント](/docs/ja/sub-agents#choose-the-subagent-scope)から作成される場合、または Claude Code が独自の worktree に分離する[バックグラウンドセッション](/docs/ja/agent-view#how-file-edits-are-isolated)のために作成される場合のいずれでも実行されます。デフォルトでは、Claude Code は `git worktree` を使用して分離された作業コピーを作成します。WorktreeCreate フックを設定すると、このデフォルトの git の動作が置き換えられ、SVN、Perforce、Mercurial などの別のバージョン管理システムを使用できるようになります。
3212 3216
3213フックはデフォルトの動作を完全に置き換えるため、[`.worktreeinclude`](/docs/ja/worktrees#copy-gitignored-files-into-worktrees) は処理されません。`.env` のようなローカルの設定ファイルを新しい worktree にコピーする必要がある場合は、フックスクリプト内で行ってください。3217フックはデフォルトの動作を完全に置き換えるため、[`.worktreeinclude`](/docs/ja/worktrees#copy-gitignored-files-into-worktrees) は処理されません。`.env` などのローカル設定ファイルを新しい worktree にコピーする必要がある場合は、フックスクリプト内でコピーしてください。
3214 3218
3215フックは、作成された worktree ディレクトリのパスを返す必要があります。Claude Code はこのパスを、分離されたセッションの作業ディレクトリとして使用します。各フックタイプがパスを返す方法については、[WorktreeCreate の出力](#worktreecreate-output)を参照してください。3219フックは、作成された worktree ディレクトリのパスを返す必要があります。Claude Code はこのパスを分離されたセッションの作業ディレクトリとして使用します。各フックタイプがパスを返す方法については、[WorktreeCreate の出力](#worktreecreate-output)を参照してください。
3216 3220
3217Claude Code はフックの成否と返されたパスに従い、`systemMessage` と `continue` を破棄します。3221Claude Code はフックの成功と返されたパスに基づいて動作し、`systemMessage` と `continue` は破棄します。
3218 3222
3219次の例は、SVN の作業コピーを作成し、Claude Code が使用するパスを出力します。リポジトリの URL は独自のものに置き換えてください。3223この例では、SVN の作業コピーを作成し、Claude Code が使用するパスを出力します。リポジトリの URL は独自のものに置き換えてください。
3220 3224
3221```json theme={null}3225```json theme={null}
3222{3226{
3235}3239}
3236```3240```
3237 3241
3238このフックは、stdin の JSON 入力から worktree の `name` を読み取り、新しいディレクトリに新規コピーをチェックアウトし、そのディレクトリのパスを出力します。最後の行の `echo` が、Claude Code が worktree のパスとして読み取るものです。パスに干渉しないよう、その他の出力はすべて stderr にリダイレクトしてください。3242このフックは、stdin の JSON 入力から worktree の `name` を読み取り、新しいディレクトリに新規コピーをチェックアウトして、そのディレクトリパスを出力します。最終行の `echo` が、Claude Code が worktree のパスとして読み取るものです。パスの妨げにならないよう、その他の出力はすべて stderr にリダイレクトしてください。
3239 3243
3240<h4 id="worktreecreate-input">3244<h4 id="worktreecreate-input">
3241 WorktreeCreate の入力3245 WorktreeCreate の入力
3242</h4>3246</h4>
3243 3247
3244[共通入力フィールド](#common-input-fields)に加えて、WorktreeCreate フックは `name` フィールドを受け取ります。これは新しい worktree のスラッグ識別子で、ユーザーが指定したものか自動生成されたもの(例: `bold-oak-a3f2`)です。3248[共通の入力フィールド](#common-input-fields)に加えて、WorktreeCreate フックは `name` フィールドを受け取ります。これは新しい worktree のスラッグ識別子で、ユーザーが指定するか自動生成されます(例: `bold-oak-a3f2`)。
3245 3249
3246```json theme={null}3250```json theme={null}
3247{3251{
3257 WorktreeCreate の出力3261 WorktreeCreate の出力
3258</h4>3262</h4>
3259 3263
3260WorktreeCreate フックは、標準の許可/ブロックの判定モデルを使用しません。代わりに、フックの成功または失敗によって結果が決まります。フックは作成した worktree ディレクトリのパスを返す必要があります。3264WorktreeCreate フックは、標準の許可/ブロックの決定モデルを使用しません。代わりに、フックの成功または失敗によって結果が決まります。フックは、作成された worktree ディレクトリのパスを返す必要があります。
3261 3265
3262* **コマンドフック**(`type: "command"`): パスを stdout の最後の空でない行として出力します。Claude Code はその行を読み取る前に ANSI エスケープコードを除去するため、`echo` より前に出力されたシェルの起動バナーは無視されます。それ以外のフックの出力はすべて stderr にリダイレクトしてください。3266* **コマンドフック**(`type: "command"`): stdout の最後の空でない行としてパスを出力します。Claude Code はその行を読み取る前に ANSI エスケープコードを除去するため、`echo` の前に出力されたシェルの起動バナーは無視されます。フックのその他の出力は stderr にリダイレクトしてください。
3263* **HTTP フック**(`type: "http"`): レスポンス本文で `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` を返します。3267* **HTTP フック**(`type: "http"`): レスポンスボディで `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` を返します。
3264 3268
3265フックが失敗した場合やパスを出力しなかった場合、worktree の作成はエラーで失敗します。3269フックが失敗した場合、またはパスを生成しなかった場合、worktree の作成はエラーで失敗します。
3266 3270
3267Claude Code は相対パスをフックが実行されたディレクトリを基準に解決し、その中の `.` や `..` セグメントを畳み込みます。結果のパスが Claude Code の移動できるディレクトリでない場合、セッションはそのパスを示すエラーを出力し、終了コード 1 で終了します。3271Claude Code は相対パスをフックが実行されたディレクトリを基準に解決し、その中の `.` や `..` のセグメントを正規化します。結果のパスが Claude Code が移動できるディレクトリでない場合、セッションはそのパスを示すエラーを出力し、終了コード 1 で終了します。
3268 3272
3269Claude Code は、`.` や `..` セグメントを含む絶対パスと、リポジトリルート以下のシンボリックリンクを経由するパスを拒否します。リポジトリにコミットされたシンボリックリンクによって worktree がリポジトリ外へリダイレクトされる可能性があるためです。エラーには拒否されたコンポーネントが示されます。正規化され、リポジトリ内のシンボリックリンクを経由しないパスを返してください。v2.1.216 より前は、worktree の作成はこのチェックを行わずにフックのパスに従っていました。3273Claude Code は、`.` や `..` のセグメントを含む絶対パス、およびリポジトリルート以下のシンボリックリンクを経由するパスを拒否します。リポジトリにコミットされたシンボリックリンクによって、worktree がリポジトリの外部にリダイレクトされる可能性があるためです。エラーには拒否された構成要素が示されます。リポジトリ内のシンボリックリンクを経由しない、正規化されたパスを返してください。v2.1.216 より前は、worktree の作成時にこのチェックを行わずにフックのパスに従っていました。
3270 3274
3271<h3 id="worktreeremove">3275<h3 id="worktreeremove">
3272 WorktreeRemove3276 WorktreeRemove
3273</h3>3277</h3>
3274 3278
3275Claude Code が、[`WorktreeCreate`](#worktreecreate) フックで作成された worktree をクリーンアップするときに実行されます。このイベントは次の場合に発生します。3279[`WorktreeCreate`](#worktreecreate) フックが作成した worktree を Claude Code がクリーンアップするときに実行されます。このイベントは次の場合に発生します。
3276 3280
3277* 対話型の [worktree セッション](/docs/ja/worktrees#start-claude-in-a-worktree)を終了し、Claude Code に確認されたときに worktree の削除を選択した場合3281* 対話型の [worktree セッション](/docs/ja/worktrees#start-claude-in-a-worktree)を終了し、Claude Code の確認に対して worktree の削除を選択した場合
3278* [名前を付けて](/docs/ja/sessions#name-your-sessions)いない対話型の worktree セッションを終了し、Claude Code が変更済みまたは未追跡のファイルを検出せず、確認なしで worktree を削除する場合3282* [名前を付けていない](/docs/ja/sessions#name-your-sessions)対話型の worktree セッションを終了し、Claude Code が変更されたファイルや追跡されていないファイルを検出せず、確認なしで worktree を削除した場合
3279* その worktree で実行されている[バックグラウンドセッション](/docs/ja/agent-view#what-deleting-a-session-removes)を削除した場合3283* worktree 内で実行されている[バックグラウンドセッション](/docs/ja/agent-view#what-deleting-a-session-removes)を削除した場合
3280 3284
3281Claude Code は git を使って変更済みまたは未追跡のファイルを探すため、git チェックアウトではない、またはその内部にない worktree では、ディレクトリに未コミットの作業があっても何も検出しません。何かを削除する前に、WorktreeRemove フック内でそのような作業がないか確認してください。3285Claude Code は git を使用して変更されたファイルや追跡されていないファイルを探すため、git のチェックアウトではない worktree や git のチェックアウト内にない worktree では、ディレクトリにコミットされていない作業があっても何も検出されません。WorktreeRemove フックで何かを削除する前に、そのような作業がないかを確認してください。
3282 3286
3283Git ベースの worktree の場合、Claude Code は `git worktree remove` で自動的にクリーンアップを行います。WorktreeCreate フックを設定した場合は、WorktreeRemove フックと組み合わせて、作成した worktree のクリーンアップを制御してください。3287git ベースの worktree の場合、Claude Code は `git worktree remove` でクリーンアップを自動的に処理します。WorktreeCreate フックを設定した場合は、WorktreeRemove フックと組み合わせて、作成される worktree のクリーンアップを制御してください。
3284 3288
3285* **WorktreeRemove フックがない場合**: worktree セッションの終了時に Claude Code が worktree を削除する際、WorktreeCreate フックが返したパスに対して `git worktree remove --force` にフォールバックするため、git が認識している worktree は削除されます。git が認識しない worktree(例えば、フックが git 以外のバージョン管理システムで作成したもの)はディスク上に残ります。[バックグラウンドセッション](/docs/ja/agent-view#what-deleting-a-session-removes)の削除がフックで作成された worktree をどう扱うかについては、エージェントビューの削除ルールを参照してください。3289* **WorktreeRemove フックがない場合**: worktree セッションの終了時に Claude Code が worktree を削除する際、WorktreeCreate フックが返したパスに対して `git worktree remove --force` にフォールバックするため、git が認識している worktree は削除されます。git が認識していない worktree(例えば、フックが git 以外のバージョン管理システムで作成したもの)はディスク上に残ります。[バックグラウンドセッション](/docs/ja/agent-view#what-deleting-a-session-removes)の削除がフックで作成された worktree をどう扱うかについては、エージェントビューの削除ルールを参照してください。
3286* **フックが 0 で終了した場合**: worktree は削除済みとして扱われます。Claude Code はフックからそれ以外に何も読み取らないため、フックがディレクトリを確実に削除するようにしてください。3290* **フックが 0 で終了した場合**: worktree は削除されたものとみなされます。Claude Code はフックからそれ以外の情報を読み取らないため、フックがディレクトリを削除したことを確認してください。
3287* **フックが 0 以外で終了した場合**: その後も `worktree_path` のディレクトリが存在していれば削除は失敗し、Git へのフォールバックなしで worktree はディスクに残ります。0 以外で終了する前にディレクトリを削除したフックは、削除済みとして扱われます。失敗の報告方法については、[WorktreeRemove の入力](#worktreeremove-input)を参照してください。3291* **フックが 0 以外で終了した場合**: その後も `worktree_path` のディレクトリが存在していれば削除は失敗し、git へのフォールバックなしで worktree はディスク上に残ります。0 以外で終了する前にディレクトリを削除したフックは、削除済みとみなされます。失敗の報告方法については、[WorktreeRemove の入力](#worktreeremove-input)を参照してください。
3288 3292
3289Claude Code は WorktreeCreate フックが返したパスしか把握していないため、フックで作成された worktree に属するブランチを削除することはありません。WorktreeCreate フックでブランチを作成する場合は、WorktreeRemove フックでそのブランチを削除してください。3293Claude Code は WorktreeCreate フックが返したパスしか把握していないため、フックで作成された worktree に属するブランチを削除することはありません。WorktreeCreate フックがブランチを作成する場合は、WorktreeRemove フックでそのブランチを削除してください。
3290 3294
3291Claude Code は、`systemMessage` や `continue` など、WorktreeRemove フックの [JSON 出力フィールド](#json-output)を破棄します。3295Claude Code は、`systemMessage` や `continue` などの WorktreeRemove フックの [JSON 出力フィールド](#json-output)を破棄します。
3292 3296
3293バックグラウンドセッションの削除では、Claude Code はフックを実行する前に保存されている worktree パスを検証し、シンボリックリンクであるパス、またはリポジトリルート以下でシンボリックリンクを経由するパスを拒否します。まだファイルを含む worktree に対しては、[エージェントビュー](/docs/ja/agent-view#what-deleting-a-session-removes)で削除を確認した場合にのみフックが実行されます。そのような worktree の場合、[`claude rm`](/docs/ja/agent-view#manage-sessions-from-the-shell) はセッションと worktree を残します。v2.1.216 より前は、フックはこれらのチェックなしで保存されたパスに対して実行されていました。3297バックグラウンドセッションの削除では、Claude Code はフックを実行する前に保存されている worktree のパスを検証し、シンボリックリンクであるパスや、リポジトリルート以下のシンボリックリンクを経由するパスを拒否します。まだファイルを含む worktree に対してフックが実行されるのは、[エージェントビュー](/docs/ja/agent-view#what-deleting-a-session-removes)で削除を確認した場合のみです。そのような worktree に対しては、[`claude rm`](/docs/ja/agent-view#manage-sessions-from-the-shell) は代わりにセッションと worktree を保持します。v2.1.216 より前は、これらのチェックなしで保存されたパスに対してフックが実行されていました。
3294 3298
3295Claude Code は、WorktreeCreate が返したパスをフック入力の `worktree_path` として渡します。次の例では、そのパスを読み取ってディレクトリを削除します。3299Claude Code は、WorktreeCreate が返したパスをフック入力の `worktree_path` として渡します。この例では、そのパスを読み取ってディレクトリを削除します。
3296 3300
3297```json theme={null}3301```json theme={null}
3298{3302{
3327}3331}
3328```3332```
3329 3333
3330WorktreeRemove フックの終了コードによって結果が決まります。フックが 0 以外で終了し、その後も `worktree_path` のディレクトリが存在している場合、削除は失敗します。3334WorktreeRemove フックの終了コードによって結果が決まります。フックが 0 以外で終了し、その後も `worktree_path` のディレクトリが存在する場合、削除は失敗します。
3331 3335
3332* worktree はディスクに残り、フックのコマンドと stderr は[デバッグログ](#debug-hooks)に記録されます。3336* worktree はディスク上に残り、フックのコマンドと stderr は[デバッグログ](#debug-hooks)に出力されます。
3333* バックグラウンドセッションを削除していた場合、セッションも残ります。[エージェントビュー](/docs/ja/agent-view#what-deleting-a-session-removes)の拒否メッセージには、`exited 1` のようなフックの終了状況、stderr の冒頭部分、およびセッションを再度削除した場合にディレクトリがそれでも削除されるかどうかが表示されます。3337* バックグラウンドセッションを削除しようとしていた場合、セッションも残ります。[エージェントビュー](/docs/ja/agent-view#what-deleting-a-session-removes)の拒否メッセージには、`exited 1` のようなフックの終了状況、stderr の冒頭部分の引用、およびセッションを再度削除した場合にディレクトリがそれでも削除されるかどうかが表示されます。
3334 3338
3335<h3 id="precompact">3339<h3 id="precompact">
3336 PreCompact3340 PreCompact
3337</h3>3341</h3>
3338 3342
3339Claude Code がコンテキスト圧縮を実行する直前に実行されます。3343Claude Code がコンテキスト圧縮処理を実行する直前に実行されます。
3340 3344
3341matcher の値は、圧縮が手動でトリガーされたか自動でトリガーされたかを示します。3345matcher の値は、コンテキスト圧縮が手動でトリガーされたか自動でトリガーされたかを示します。
3342 3346
3343| Matcher | 発生するタイミング |3347| Matcher | 発生するタイミング |
3344| :- | :- |3348| :- | :- |
3345| `manual` | `/compact` |3349| `manual` | `/compact` |
3346| `auto` | 会話が[自動圧縮ウィンドウ](/docs/ja/model-config#set-the-auto-compact-window)に達したときの自動圧縮 |3350| `auto` | 会話が[自動圧縮ウィンドウ](/docs/ja/model-config#set-the-auto-compact-window)に達したときの自動圧縮 |
3347 3351
3348圧縮をブロックするには、終了コード 2 で終了します。手動の `/compact` の場合、stderr のメッセージがユーザーに表示されます。`"decision": "block"` を含む JSON を返してブロックすることもできます。3352圧縮をブロックするには、終了コード 2 で終了します。手動の `/compact` の場合、stderr のメッセージがユーザーに表示されます。`"decision": "block"` を含む JSON を返すことでもブロックできます。
3349 3353
3350自動圧縮をブロックした場合の影響は、発生したタイミングによって異なります。コンテキスト上限に達する前に予防的に圧縮がトリガーされた場合、Claude Code は圧縮をスキップし、会話は圧縮されないまま続行されます。API がすでに返したコンテキスト上限エラーから回復するために圧縮がトリガーされた場合は、元のエラーが表面化し、現在のリクエストは失敗します。3354自動圧縮のブロックは、発生するタイミングによって影響が異なります。コンテキストの上限に達する前に先行して圧縮がトリガーされた場合、Claude Code は圧縮をスキップし、会話は圧縮されずに続行されます。API がすでに返したコンテキスト上限エラーから回復するために圧縮がトリガーされた場合は、元のエラーが表面化し、現在のリクエストは失敗します。
3351 3355
3352Claude Code は PreCompact フックの `systemMessage` と `continue` フィールドを破棄します。3356Claude Code は、PreCompact フックの `systemMessage` と `continue` フィールドを破棄します。
3353 3357
3354<h4 id="precompact-input">3358<h4 id="precompact-input">
3355 PreCompact の入力3359 PreCompact の入力
3372 PostCompact3376 PostCompact
3373</h3>3377</h3>
3374 3378
3375Claude Code がコンテキスト圧縮を完了した後に実行されます。このイベントを使用すると、圧縮後の新しい状態に対応できます。たとえば、生成された要約をログに記録したり、外部の状態を更新したりできます。Claude Code は PostCompact フックの `systemMessage` と `continue` フィールドを破棄します。3379Claude Code がコンテキスト圧縮処理を完了した後に実行されます。このイベントを使用すると、圧縮後の新しい状態に対応できます。例えば、生成された要約をログに記録したり、外部の状態を更新したりできます。Claude Code は、PostCompact フックの `systemMessage` と `continue` フィールドを破棄します。
3376 3380
3377`PreCompact` と同じ matcher の値が適用されます。3381`PreCompact` と同じ matcher の値が適用されます。
3378 3382
3379| Matcher | 発生するタイミング |3383| Matcher | 発生するタイミング |
3380| :- | :- |3384| :- | :- |
3381| `manual` | `/compact` の後 |3385| `manual` | `/compact` の後 |
3382| `auto` | 会話が[自動圧縮ウィンドウ](/docs/ja/model-config#set-the-auto-compact-window)に達したときの自動圧縮の後 |3386| `auto` | 会話が[自動圧縮ウィンドウ](/docs/ja/model-config#set-the-auto-compact-window)に達して自動圧縮された後 |
3383 3387
3384<h4 id="postcompact-input">3388<h4 id="postcompact-input">
3385 PostCompact の入力3389 PostCompact の入力
3386</h4>3390</h4>
3387 3391
3388[共通の入力フィールド](#common-input-fields)に加えて、PostCompact フックは `trigger` と `compact_summary` を受け取ります。`compact_summary` フィールドには、圧縮によって生成された会話の要約が含まれます。3392[共通の入力フィールド](#common-input-fields)に加えて、PostCompact フックは `trigger` と `compact_summary` を受け取ります。`compact_summary` フィールドには、圧縮処理によって生成された会話の要約が含まれます。
3389 3393
3390```json theme={null}3394```json theme={null}
3391{3395{
3398}3402}
3399```3403```
3400 3404
3401PostCompact フックには判定の制御はありません。圧縮の結果に影響を与えることはできませんが、後続のタスクを実行できます。3405PostCompact フックには決定制御がありません。圧縮の結果に影響を与えることはできませんが、後続のタスクを実行できます。
3402 3406
3403<h3 id="premodelswitch">3407<h3 id="premodelswitch">
3404 PreModelSwitch3408 PreModelSwitch
3405</h3>3409</h3>
3406 3410
3407ユーザーまたはクライアントが要求したモデルの切り替えを Claude Code が適用する前に実行されます。切り替えをブロックしたり、確認を求めたり、切り替えにかかるコストを事前に表示したりするために使用します。3411ユーザーまたはクライアントが要求したモデルの切り替えを Claude Code が適用する前に実行されます。切り替えをブロックしたり、確認を求めたり、切り替えが行われる前にそのコストを表示したりするために使用します。
3408 3412
3409PreModelSwitch には Claude Code v2.1.251 以降が必要です。Claude Code は次のリクエストに対してこのフックを実行します。3413PreModelSwitch には Claude Code v2.1.251 以降が必要です。Claude Code は次のリクエストに対してこのフックを実行します。
3410 3414
3411* `/model <name>` と `/model` ピッカー3415* `/model <name>` および `/model` ピッカー
3412* `Option+P` または `Alt+P` のモデルピッカー3416* `Option+P` または `Alt+P` のモデルピッカー
3413* `/config` の Model 設定3417* `/config` の Model 設定
3414* セッションのモデルが変わる場合の [fast mode](/docs/ja/fast-mode) のオン3418* セッションのモデルが変わる場合の [fast mode](/docs/ja/fast-mode) のオン
3415* [Agent SDK](/docs/ja/agent-sdk/typescript#query-object) ホストまたは [Remote Control](/docs/ja/remote-control) からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更3419* [Agent SDK](/docs/ja/agent-sdk/typescript#query-object) ホストまたは [Remote Control](/docs/ja/remote-control) からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更
3416 3420
3417Claude Code は、[自動モデルフォールバック](/docs/ja/model-config#automatic-model-fallback)やセッション再開時のモデルの復元など、Claude Code 自身が行う切り替えに対しては PreModelSwitch フックを実行しません。これらの変更は [PostModelSwitch](#postmodelswitch) にのみ届きます。3421Claude Code は、[自動モデルフォールバック](/docs/ja/model-config#automatic-model-fallback)やセッション再開時のモデル復元など、Claude Code が自ら行う切り替えに対しては PreModelSwitch フックを実行しません。これらの変更は [PostModelSwitch](#postmodelswitch) にのみ届きます。
3418 3422
3419Claude Code は、`[1m]` サフィックスを無視して、切り替え先モデルの正規名と matcher を比較します。`opus` のようなエイリアス、日付付きのモデル ID、Amazon Bedrock のモデル ID のようなプロバイダー固有の ID は、いずれも解決先の 1 つの正規名にマッチするため、`claude-opus-5` は Opus 5 のあらゆる表記をカバーします。3423Claude Code は、`[1m]` サフィックスを無視して、セッションの切り替え先モデルの正規名と matcher を比較します。`opus` のようなエイリアス、日付付きのモデル ID、Amazon Bedrock のモデル ID のようなプロバイダー固有の ID は、いずれも解決先の 1 つの正規名に一致するため、`claude-opus-5` は Opus 5 のあらゆる表記をカバーします。
3420 3424
3421切り替え先の正規名を特定できない場合(たとえば [LLM ゲートウェイ](/docs/ja/llm-gateway)だけが認識するカスタムモデル ID の場合)、Claude Code は matcher に関係なくすべての PreModelSwitch フックを実行します。そのため、ブロックするフックは matcher だけに頼らず、入力の `to_model` を確認する必要があります。3425切り替え先の正規名を Claude Code が判定できない場合(例えば、[LLM ゲートウェイ](/docs/ja/llm-gateway)だけが認識するカスタムモデル ID の場合)、Claude Code は matcher に関係なくすべての PreModelSwitch フックを実行します。そのため、ブロックを行うフックは matcher だけに頼るのではなく、入力の `to_model` を確認する必要があります。
3422 3426
3423matcher は、完全な名前、`claude-opus-4-6|claude-opus-5` のような `|` 区切りのリスト、または `.*opus.*` のような正規表現で記述します。次の例では、完全名の matcher を使用し、さらにフック入力の `to_model` も確認することで、Opus 4.6 への切り替えを終了コード 2 で拒否し、それ以外の切り替え先は許可します。3427matcher は、完全な名前、`claude-opus-4-6|claude-opus-5` のような `|` 区切りのリスト、または `.*opus.*` のような正規表現として記述します。この例では完全な名前の matcher を使用し、さらにフック入力の `to_model` も確認することで、Opus 4.6 への切り替えを終了コード 2 で拒否し、それ以外の切り替え先は通過させます。
3424 3428
3425<Tabs>3429<Tabs>
3426 <Tab title="macOS/Linux">3430 <Tab title="macOS/Linux">
3473 }3477 }
3474 ```3478 ```
3475 3479
3476 次のスクリプトをプロジェクトの `.claude/hooks/block-opus-46.ps1` に保存します。3480 このスクリプトをプロジェクトの `.claude/hooks/block-opus-46.ps1` に保存します。
3477 3481
3478 ```powershell theme={null}3482 ```powershell theme={null}
3479 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json3483 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3486 </Tab>3490 </Tab>
3487</Tabs>3491</Tabs>
3488 3492
3489フックが動作することを確認するには、別のモデルを実行しているセッションから `/model claude-opus-4-6` を実行します。Claude Code は現在のモデルを維持し、PreModelSwitch フックが切り替えをブロックしたことを、指定したメッセージを理由として報告します。3493フックが機能することを確認するには、別のモデルで実行中のセッションから `/model claude-opus-4-6` を実行します。Claude Code は現在のモデルを維持し、PreModelSwitch フックが切り替えをブロックしたことを、設定したメッセージを理由として報告します。
3490 3494
3491<h4 id="premodelswitch-input">3495<h4 id="premodelswitch-input">
3492 PreModelSwitch の入力3496 PreModelSwitch の入力
3493</h4>3497</h4>
3494 3498
3495[共通の入力フィールド](#common-input-fields)に加えて、PreModelSwitch フックは次の表のフィールドを受け取ります。最後の 5 つは会話を新しいモデルに再送信するコストを表すため、フックは切り替えの前にその金額を表示できます。3499[共通の入力フィールド](#common-input-fields)に加えて、PreModelSwitch フックはこの表のフィールドを受け取ります。最後の 5 つは、会話を新しいモデルに再送信する際のコストを示すため、フックは切り替えが行われる前にその数値を表示できます。
3496 3500
3497| フィールド | 型 | 説明 |3501| フィールド | 型 | 説明 |
3498| :- | :- | :- |3502| :- | :- | :- |
3499| `from_model` | string | 切り替え元のモデル ID |3503| `from_model` | string | 切り替え元のモデル ID |
3500| `to_model` | string | 切り替え先のモデル ID。matcher はこのモデルの正規名と比較されます |3504| `to_model` | string | 切り替え先のモデル ID。matcher はこのモデルの正規名と比較されます |
3501| `requested_model` | string または `null` | リクエストで指定されたモデル: `opus` のようなエイリアス、完全なモデル ID、またはデフォルトモデルが要求された場合は `null` |3505| `requested_model` | string または `null` | リクエストで指定されたモデル。`opus` のようなエイリアス、完全なモデル ID、またはデフォルトモデルのリクエストの場合は `null` |
3502| `source` | string | リクエストの送信元: `/model <name>`、`/config` の Model 設定、または fast mode のオンの場合は `"command"`、モデルピッカーの場合は `"picker"`、Agent SDK ホストまたは Remote Control からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更の場合は `"sdk"` |3506| `source` | string | リクエストの送信元。`/model <name>`、`/config` の Model 設定、または fast mode のオンの場合は `"command"`、モデルピッカーの場合は `"picker"`、Agent SDK ホストまたは Remote Control からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更の場合は `"sdk"` |
3503| `context_tokens` | number | 次のリクエストがプロンプトとして再送信するトークン数: メイン会話の最後の応答の入力、キャッシュ読み取り、キャッシュ作成、出力トークンの合計。最初の応答の前は `0` |3507| `context_tokens` | number | 次のリクエストがプロンプトとして再送信するトークン数。メイン会話の最後の応答における入力、キャッシュ読み取り、キャッシュ作成、出力のトークンの合計です。最初の応答の前は `0` |
3504| `prompt_cache_warm` | boolean | 現在のモデルのプロンプトキャッシュがまだウォームである可能性が高いかどうか。つまり、切り替えによってそれが失われるかどうか |3508| `prompt_cache_warm` | boolean | 現在のモデルのプロンプトキャッシュがまだウォームである可能性が高いかどうか。つまり、切り替えによってキャッシュが失われるかどうか |
3505| `cache_ttl` | string | Claude Code がこのセッションで要求する[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime): `"5m"` または `"1h"` |3509| `cache_ttl` | string | Claude Code がこのセッションで要求する[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime)。`"5m"` または `"1h"` |
3506| `estimated_cache_write_usd` | number | `to_model` 上で `cache_ttl` の料金で `context_tokens` をプロンプトキャッシュに書き込む推定コスト(米ドル)。次の応答は含みません。サーバーがコンテキスト全体を再キャッシュする必要がない場合もあるため、推定値として扱ってください |3510| `estimated_cache_write_usd` | number | `to_model` で `context_tokens` を `cache_ttl` の料金でプロンプトキャッシュに書き込む推定コスト(米ドル)。次の応答は含みません。サーバーがコンテキスト全体を再キャッシュする必要がない場合もあるため、推定値として扱ってください |
3507| `pricing` | string | Claude Code が `estimated_cache_write_usd` の料金をどのように算出したか: 組織独自の料金が設定されている場合はその料金による `"configured"`、定価による `"catalog"`、または `to_model` の価格が不明で Claude Code がデフォルトの料金を想定した場合は `"default"` |3511| `pricing` | string | Claude Code が `estimated_cache_write_usd` を算出した方法。組織が独自の料金を設定している場合はその料金による `"configured"`、定価による `"catalog"`、または `to_model` の価格が不明で Claude Code がデフォルトの料金を想定した場合は `"default"` |
3508 3512
3509次の例は、Sonnet 5 を実行しているセッションでの `/model opus` の入力を示しています。3513この例は、Sonnet 5 で実行中のセッションで `/model opus` を実行した場合の入力を示しています。
3510 3514
3511```json theme={null}3515```json theme={null}
3512{3516{
3527```3531```
3528 3532
3529<h4 id="premodelswitch-decision-control">3533<h4 id="premodelswitch-decision-control">
3530 PreModelSwitch の判定の制御3534 PreModelSwitch の決定制御
3531</h4>3535</h4>
3532 3536
3533`PreModelSwitch` フックは、切り替えをキャンセルしたり、ユーザーに確認を求めたり、続行させたりできます。終了コード 2 またはトップレベルの `decision: "block"` で切り替えがキャンセルされます。3537`PreModelSwitch` フックは、切り替えをキャンセルしたり、ユーザーに確認を求めたり、そのまま続行させたりできます。終了コード 2 またはトップレベルの `decision: "block"` で切り替えがキャンセルされます。
3534 3538
3535より細かく制御するには、[PreToolUse](#pretooluse-decision-control) と同様に、`hookSpecificOutput` オブジェクト内で `permissionDecision` と `permissionDecisionReason` を返します。`PreModelSwitch` は `"allow"`、`"deny"`、`"ask"` を受け付けます。`"defer"`、`updatedInput`、`additionalContext` は受け付けません。次の表で両方のフィールドを説明します。3539より細かく制御するには、[PreToolUse](#pretooluse-decision-control) と同様に、`hookSpecificOutput` オブジェクト内で `permissionDecision` と `permissionDecisionReason` を返します。`PreModelSwitch` は `"allow"`、`"deny"`、`"ask"` を受け付けます。`"defer"`、`updatedInput`、`additionalContext` は受け付けません。以下の表で両フィールドを説明します。
3536 3540
3537| フィールド | 説明 |3541| フィールド | 説明 |
3538| :- | :- |3542| :- | :- |
3539| `permissionDecision` | `"allow"` は続行し、[プロンプトキャッシュがウォームな間に Claude Code が表示する確認](/docs/ja/prompt-caching#switching-models)をスキップします。`"deny"` は切り替えをキャンセルします。`"ask"` はユーザーに確認を求めます |3543| `permissionDecision` | `"allow"` は続行し、[プロンプトキャッシュがウォームな間に Claude Code が表示する確認](/docs/ja/prompt-caching#switching-models)をスキップします。`"deny"` は切り替えをキャンセルします。`"ask"` はユーザーに確認を求めます |
3540| `permissionDecisionReason` | `"deny"` の場合、切り替えがブロックされた理由としてユーザーに表示されるか、`set_model` リクエストに対するエラーとして返されます。`"ask"` の場合、確認プロンプトに表示されます。`"allow"` の場合は無視されます |3544| `permissionDecisionReason` | `"deny"` の場合、切り替えがブロックされた理由としてユーザーに表示されるか、`set_model` リクエストに対するエラーとして返されます。`"ask"` の場合、確認プロンプトに表示されます。`"allow"` の場合は無視されます |
3541 3545
3542`"ask"` のプロンプトを表示できるのは、対話セッションでの `/model` だけです。`-p` フラグを使用した非対話モード、`/config`、`set_model` リクエストなど、その他のすべてのサーフェスでは、Claude Code は `"ask"` を拒否として扱います。3546`"ask"` のプロンプトを表示できるのは、対話セッションでの `/model` のみです。`-p` フラグを使用する非対話モード、`/config`、`set_model` リクエストなど、その他のすべてのサーフェスでは、Claude Code は `"ask"` を拒否として扱います。
3543 3547
3544次の例では、`context_tokens` のトークン数を示してユーザーに確認を求めます。3548この例では、ユーザーに確認を求め、`context_tokens` のトークン数を引用しています。
3545 3549
3546```json theme={null}3550```json theme={null}
3547{3551{
3553}3557}
3554```3558```
3555 3559
3556複数の PreModelSwitch フックが異なる判定を返した場合、優先順位は `deny` > `ask` > `allow` です。3560複数の PreModelSwitch フックが異なる決定を返した場合、優先順位は `deny` > `ask` > `allow` です。
3557 3561
3558Claude Code は判定に関係なく、フックが返した `systemMessage` をユーザーに表示します。そのため、コストを報告するフックは `{"systemMessage": "..."}` を返して 0 で終了できます。3562Claude Code は、決定に関係なく、フックが返した `systemMessage` をユーザーに表示します。そのため、コストを報告するフックは `{"systemMessage": "..."}` を返して 0 で終了できます。
3559 3563
3560タイムアウトまでに応答しない PreModelSwitch フックは、切り替えをブロックします。これに対して [PreToolUse](#timeouts) では、タイムアウトしたコマンドフックはツール呼び出しを続行させます。このイベントのデフォルトのタイムアウトは 30 秒です。`PreModelSwitch` は `command`、`http`、`mcp_tool` フックのみを実行するため、`prompt` と `agent` のデフォルトは適用されません。3564タイムアウトまでに応答しない PreModelSwitch フックは、切り替えをブロックします。これに対して [PreToolUse](#timeouts) では、タイムアウトしたコマンドフックはツール呼び出しを続行させます。このイベントのデフォルトのタイムアウトは 30 秒です。`PreModelSwitch` は `command`、`http`、`mcp_tool` フックのみを実行するため、`prompt` と `agent` のデフォルトは適用されません。
3561 3565
35620 と 2 以外のコードで終了し、JSON の判定を出力しないフックはブロックしません。[その他の終了コード](#other-exit-codes)で説明されているように、Claude Code はその stderr を表示して切り替えを適用します。35660 または 2 以外のコードで終了し、JSON の決定を出力しないフックはブロックしません。[その他の終了コード](#other-exit-codes)で説明しているとおり、Claude Code はその stderr を表示して切り替えを適用します。
3563 3567
3564<h3 id="postmodelswitch">3568<h3 id="postmodelswitch">
3565 PostModelSwitch3569 PostModelSwitch
3566</h3>3570</h3>
3567 3571
3568セッションのモデルが変更された後に実行されます。すべての CLAUDE.md を編集することなく、Claude にモデル固有のガイダンスを与えるために使用します。たとえば、特定のモデルに適用される組織全体の指示などです。3572セッションのモデルが変更された後に実行されます。すべての CLAUDE.md を編集することなく、Claude にモデル固有のガイダンスを与えるために使用します。例えば、特定のモデルに適用される組織全体の指示などです。
3569 3573
3570PostModelSwitch には Claude Code v2.1.251 以降が必要です。モデルはすでに変更されているため、ブロックすることはできません。Claude Code は次のいずれかの変更の後に PostModelSwitch フックを実行します。3574PostModelSwitch には Claude Code v2.1.251 以降が必要です。モデルはすでに変更されているため、ブロックすることはできません。Claude Code は、次のいずれかの変更の後に PostModelSwitch フックを実行します。
3571 3575
3572* ユーザーまたはクライアントが要求した切り替え3576* ユーザーまたはクライアントが要求した切り替え
3573* セッションのモデルを変更する[自動モデルフォールバック](/docs/ja/model-config#automatic-model-fallback)3577* セッションのモデルを変更する[自動モデルフォールバック](/docs/ja/model-config#automatic-model-fallback)
3574* [`opusplan`](/docs/ja/model-config#opusplan-model-setting) のような設定による plan モードへの移行または plan モードからの離脱3578* [`opusplan`](/docs/ja/model-config#opusplan-model-setting) などの設定による plan モードへの移行または plan モードからの離脱
3575* セッション再開時に Claude Code がモデルを復元したとき3579* セッション再開時の Claude Code によるモデルの復元
3576 3580
3577[フォールバックモデルチェーン](/docs/ja/model-config#fallback-model-chains)のモデルがターンを処理する場合、その置き換えは 1 ターンだけでセッションのモデルは変わらないため、Claude Code は PostModelSwitch フックを実行しません。3581[フォールバックモデルチェーン](/docs/ja/model-config#fallback-model-chains)のモデルがターンを処理する場合、Claude Code は PostModelSwitch フックを実行しません。この代替は 1 ターンのみ続き、セッションのモデルは変更されないためです。
3578 3582
3579matcher は [PreModelSwitch](#premodelswitch) と同じルールに従います。Claude Code は、セッションの切り替え先モデルの正規名と matcher を比較します。3583matcher は [PreModelSwitch](#premodelswitch) と同じルールに従います。Claude Code は、セッションの切り替え先モデルの正規名と matcher を比較します。
3580 3584
3581次の例では、セッションのモデルがいずれかの Opus モデルに変わるたびにガイダンスを追加します。3585この例では、セッションのモデルがいずれかの Opus モデルに変わるたびにガイダンスを追加します。
3582 3586
3583```json theme={null}3587```json theme={null}
3584{3588{
3598}3602}
3599```3603```
3600 3604
3601フックが動作することを確認するには、別のモデルを実行しているセッションから Opus モデルに切り替え(たとえば Sonnet のセッションから `/model opus` を実行し)、現在のモデルについてどのようなガイダンスがあるかを Claude に尋ねます。3605フックが機能することを確認するには、別のモデルで実行中のセッションから Opus モデルに切り替え(例えば Sonnet のセッションから `/model opus` を実行し)、現在のモデルについてどのようなガイダンスがあるかを Claude に尋ねます。
3602 3606
3603<h4 id="postmodelswitch-input">3607<h4 id="postmodelswitch-input">
3604 PostModelSwitch の入力3608 PostModelSwitch の入力
3605</h4>3609</h4>
3606 3610
3607PostModelSwitch フックは [PreModelSwitch](#premodelswitch-input) と同じフィールドを受け取ります。ただし、`hook_event_name` は `"PostModelSwitch"` に設定され、`source` には 2 つの値が追加されます。自動フォールバックなど Claude Code 自身が行った変更を表す `"auto"` と、セッション再開時に復元されたモデルを表す `"resume"` です。3611PostModelSwitch フックは [PreModelSwitch](#premodelswitch-input) と同じフィールドを受け取ります。ただし、`hook_event_name` は `"PostModelSwitch"` に設定され、`source` の値が 2 つ追加されます。自動フォールバックまたは Claude Code が自ら行ったその他の変更の場合は `"auto"`、セッション再開時に復元されたモデルの場合は `"resume"` です。
3608 3612
3609`source` が `"auto"` の場合、`requested_model` は `null` です。`source` が `"resume"` の場合は、Claude Code が復元した保存済みのモデル設定です。3613`source` が `"auto"` の場合、`requested_model` は `null` です。`source` が `"resume"` の場合は、Claude Code が復元した保存済みのモデル設定になります。
3610 3614
3611<h4 id="postmodelswitch-decision-control">3615<h4 id="postmodelswitch-decision-control">
3612 PostModelSwitch の判定の制御3616 PostModelSwitch の決定制御
3613</h4>3617</h4>
3614 3618
3615Claude Code は、終了コード 0 の場合のフックの[プレーンテキストの stdout](#exit-code-0)、または JSON 出力の `additionalContext` を受け取り、切り替え後の次のリクエストで Claude に渡します。すべてのフックで使用できる [JSON 出力フィールド](#json-output)に加えて、次のフィールドを返すことができます。3619Claude Code は、終了コード 0 のときのフックの[プレーンテキストの stdout](#exit-code-0)、または JSON 出力の `additionalContext` を受け取り、切り替え後の次のリクエストとともに Claude に渡します。すべてのフックで使用できる [JSON 出力フィールド](#json-output)に加えて、次のフィールドを返すことができます。
3616 3620
3617| フィールド | 説明 |3621| フィールド | 説明 |
3618| :- | :- |3622| :- | :- |
3619| `additionalContext` | 次のリクエストで Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |3623| `additionalContext` | 次のリクエストとともに Claude のコンテキストに追加される文字列。[Claude のコンテキストを追加する](#add-context-for-claude)を参照してください |
3620 3624
3621次のプロンプトを送信してから 5 秒以内にフックが完了しない場合、Claude Code はその出力なしでリクエストを送信し、代わりにその次のリクエストに出力を添付します。次のリクエストまでにモデルが複数回変更された場合、Claude Code は最後の切り替え先モデルの出力のみを渡します。3625次のプロンプトを送信してから 5 秒以内にフックが完了しない場合、Claude Code はその出力なしでリクエストを送信し、代わりにその次のリクエストに出力を添付します。次のリクエストの前にモデルが複数回変更された場合、Claude Code は最後の切り替え先モデルに対する出力のみを渡します。
3622 3626
3623<h3 id="sessionend">3627<h3 id="sessionend">
3624 SessionEnd3628 SessionEnd
3625</h3>3629</h3>
3626 3630
3627Claude Code セッションが終了するときに実行されます。クリーンアップタスク、セッション統計のログ記録、セッション状態の保存に便利です。終了理由でフィルタリングするための matcher をサポートしています。3631Claude Code のセッションが終了するときに実行されます。クリーンアップタスク、セッション統計のログ記録、セッション状態の保存に役立ちます。終了理由でフィルタリングするための matcher をサポートしています。
3628 3632
3629フック入力の `reason` フィールドは、セッションが終了した理由を示します。3633フック入力の `reason` フィールドは、セッションが終了した理由を示します。
3630 3634
3631| 理由 | 説明 |3635| 理由 | 説明 |
3632| :- | :- |3636| :- | :- |
3633| `clear` | `/clear` コマンドでセッションがクリアされた |3637| `clear` | `/clear` コマンドでセッションがクリアされた |
3634| `resume` | 対話的な `/resume` でセッションが切り替えられた |3638| `resume` | 対話型の `/resume` でセッションが切り替えられた |
3635| `logout` | ユーザーがログアウトした |3639| `logout` | ユーザーがログアウトした |
3636| `prompt_input_exit` | プロンプト入力が表示されている間にユーザーが終了した |3640| `prompt_input_exit` | プロンプト入力が表示されている間にユーザーが終了した |
3637| `other` | その他の終了理由 |3641| `other` | その他の終了理由 |
3653}3657}
3654```3658```
3655 3659
3656SessionEnd フックには判定の制御はありません。セッションの終了をブロックすることはできませんが、クリーンアップタスクを実行できます。Claude Code は、`systemMessage` などの [JSON 出力フィールド](#json-output)を破棄します。3660SessionEnd フックには決定制御がありません。セッションの終了をブロックすることはできませんが、クリーンアップタスクを実行できます。Claude Code は、`systemMessage` などのフックの [JSON 出力フィールド](#json-output)を破棄します。
3657 3661
3658SessionEnd フックのデフォルトのタイムアウトは 1.5 秒です。これは、終了するとき、`/clear` を実行するとき、または対話的な `/resume` でセッションを切り替えるときに適用されます。フックにより多くの時間を与えるには、次の 2 つの方法があります。3662SessionEnd フックのデフォルトのタイムアウトは 1.5 秒です。これは、終了時、`/clear` の実行時、または対話型の `/resume` でセッションを切り替えたときに適用されます。フックにより多くの時間を与えるには、次の 2 つの方法があります。
3659 3663
3660* **フックごとの `timeout`**: そのフックの設定で `timeout` を指定します。全体の制限時間は、設定ファイル内で最も大きいフックごとの `timeout` に合わせて、最大 60 秒まで自動的に引き上げられます。この方法で制限時間を引き上げても、独自の `timeout` を持たないフックはデフォルトのままです。プラグインが提供するフックに設定されたタイムアウトは、制限時間を引き上げません。3664* **フックごとの `timeout`**: そのフックの設定で `timeout` を設定します。全体の制限時間は、設定ファイル内のフックごとの `timeout` の最大値に合わせて、最大 60 秒まで自動的に引き上げられます。この方法で制限時間を引き上げた場合でも、独自の `timeout` を持たないフックはデフォルトのままです。プラグインが提供するフックに設定されたタイムアウトでは、制限時間は引き上げられません。
3661* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: この環境変数をミリ秒単位で設定すると、制限時間を明示的に上書きできます。設定した値は、独自の `timeout` を持たない各フックのタイムアウトにもなります。3665* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: この環境変数をミリ秒単位で設定して、制限時間を明示的に上書きします。設定した値は、独自の `timeout` を持たない各フックのタイムアウトにもなります。
3662 3666
3663次の例では、制限時間を 5 秒に設定します。3667この例では、制限時間を 5 秒に設定します。
3664 3668
3665```bash theme={null}3669```bash theme={null}
3666CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3670CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
3667```3671```
3668 3672
3669v2.1.268 より前は、`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` は全体の制限時間のみを引き上げ、独自の `timeout` を持たないフックは引き続き 1.5 秒後にキャンセルされていました。3673v2.1.268 より前は、`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` は全体の制限時間のみを引き上げ、独自の `timeout` を持たないフックは 1.5 秒後にキャンセルされていました。
3670 3674
3671<h3 id="elicitation">3675<h3 id="elicitation">
3672 Elicitation3676 Elicitation
3674 3678
3675MCP サーバーがタスクの途中でユーザー入力を要求したときに実行されます。デフォルトでは、Claude Code はユーザーが応答するための対話ダイアログを表示します。フックはこのリクエストをインターセプトしてプログラムで応答し、ダイアログを完全にスキップできます。3679MCP サーバーがタスクの途中でユーザー入力を要求したときに実行されます。デフォルトでは、Claude Code はユーザーが応答するための対話ダイアログを表示します。フックはこのリクエストをインターセプトしてプログラムで応答し、ダイアログを完全にスキップできます。
3676 3680
3681設定エントリとスクリプトを含む完全なフックについては、[スクリプトからフォームリクエストに回答する](#answer-a-form-request-from-a-script)を参照してください。
3682
3677matcher フィールドは MCP サーバー名と照合されます。3683matcher フィールドは MCP サーバー名と照合されます。
3678 3684
3679<h4 id="elicitation-input">3685<h4 id="elicitation-input">
3721 Elicitation の出力3727 Elicitation の出力
3722</h4>3728</h4>
3723 3729
3724ダイアログを表示せずにプログラムで応答するには、`hookSpecificOutput` を含む JSON オブジェクトを返します。3730Elicitation フックは、ユーザーの代わりにリクエストに回答したり、辞退またはキャンセルしたり、ダイアログに任せたりできます。回答、辞退、またはキャンセルするには、0 で終了し、`action` を含む `hookSpecificOutput` オブジェクトを出力します。サーバーは回答を受け取り、ダイアログは表示されません。この表の各行は、1 つの結果に対して返す内容と、MCP サーバーが受け取る内容を示しています。
3731
3732| 目的 | 返す内容 | サーバーが受け取る内容 |
3733| :- | :- | :- |
3734| ユーザーの代わりに回答する | `"action": "accept"` と、`content` 内のフォームフィールドの値 | `accept` と指定した `content` |
3735| リクエストを辞退する | `"action": "decline"` | `decline` |
3736| リクエストをキャンセルする | `"action": "cancel"` | `cancel` |
3737| リクエストをユーザーに任せる | 出力なし、終了コード 0 | [ダイアログ](/docs/ja/mcp#respond-to-mcp-elicitation-requests)でのユーザーの回答 |
3738
3739この出力は、[Elicitation の入力](#elicitation-input)で示したフォームモードのリクエストに回答します。`content` のキーは、そのリクエストの `requested_schema` のプロパティ名です。
3725 3740
3726```json theme={null}3741```json theme={null}
3727{3742{
3735}3750}
3736```3751```
3737 3752
3738| フィールド | 値 | 説明 |3753この出力はリクエストを辞退します。
3739| :- | :- | :- |3754
3740| `action` | `accept`、`decline`、`cancel` | リクエストを承諾、拒否、またはキャンセルするかどうか |3755```json theme={null}
3741| `content` | object | 送信するフォームフィールドの値。`action` が `accept` の場合にのみ使用されます |3756{
3757 "hookSpecificOutput": {
3758 "hookEventName": "Elicitation",
3759 "action": "decline"
3760 }
3761}
3762```
3763
3764ダイアログでは、**Decline** を選択すると `decline` が送信され、`Esc` を押すと `cancel` が送信されます。サーバーに見せたいほうを返してください。
3765
3766URL モードのリクエストの場合、`accept` を返すフックはダイアログをスキップするため、URL は開かれません。
3767
3768Claude Code は、どの `action` を返した場合でも、Elicitation フックの JSON 出力から `reason`、`systemMessage`、`continue` を破棄します。
3742 3769
3743終了コード 2 は elicitation を拒否します。Claude Code は stderr のメッセージをどこにも表示しません。3770<h4 id="other-ways-to-decline-an-elicitation">
3771 elicitation を辞退するその他の方法
3772</h4>
3773
3774フックは次の方法でも辞退できます。サーバーは `"action": "decline"` の場合と同じ `decline` を受け取ります。
3775
3776* **終了コード 2 で終了する**: Claude Code は同じフックが出力した `hookSpecificOutput` を無視します
3777* **トップレベルの `"decision": "block"` を出力する**: ブロックは同じ出力内の `action` を上書きします
3778
3779複数のフックが同じリクエストに一致する場合、いずれかのフックによる辞退は、他のフックによる `accept` や `cancel` を上書きします。
3780
3781このスクリプトは、URL モードのリクエストを辞退し、フォームリクエストはダイアログに任せます。
3782
3783```bash theme={null}
3784#!/bin/bash
3785if [ "$(jq -r '.mode')" = "url" ]; then
3786 exit 2
3787fi
3788```
3789
3790Claude Code は stderr や `reason` を表示しないため、ユーザーもサーバーもフックが辞退した理由を知ることはできません。
3791
3792v2.1.105 から v2.1.284 で修正されるまで、Claude Code は `Elicitation` および `ElicitationResult` フックのトップレベルの `decision` を無視していました。
3793
3794<h4 id="answer-a-form-request-from-a-script">
3795 スクリプトからフォームリクエストに回答する
3796</h4>
3744 3797
3745Claude Code は Elicitation フックの JSON 出力の `hookSpecificOutput` に基づいて動作し、`systemMessage` と `continue` は破棄します。3798この例では、繰り返し尋ねられる 1 つの質問にユーザーの代わりに回答します。`issue-tracker` という名前の MCP サーバーがフォームでプロジェクトキーを尋ね、フックが `DOCS` を入力します。スクリプトは、`project_key` がフォームの唯一のフィールドである場合に受け入れます。それ以外のリクエストでは何も出力しないため、ダイアログが表示されます。
3799
3800<Tabs>
3801 <Tab title="macOS/Linux">
3802 設定ファイルで、サーバー名を matcher としてこのイベントのコマンドフックを登録します。
3803
3804 ```json theme={null}
3805 {
3806 "hooks": {
3807 "Elicitation": [
3808 {
3809 "matcher": "issue-tracker",
3810 "hooks": [
3811 {
3812 "type": "command",
3813 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",
3814 "args": []
3815 }
3816 ]
3817 }
3818 ]
3819 }
3820 }
3821 ```
3822
3823 このスクリプトをプロジェクトの `.claude/hooks/answer-project-key.sh` に保存し、`chmod +x` で実行可能にします。
3824
3825 ```bash theme={null}
3826 #!/bin/bash
3827 input=$(cat)
3828 fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")
3829
3830 if [ "$fields" = '["project_key"]' ]; then
3831 jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'
3832 fi
3833 ```
3834 </Tab>
3835
3836 <Tab title="Windows (PowerShell)">
3837 サーバー名を matcher として、PowerShell でスクリプトを実行するコマンドフックを登録します。
3838
3839 ```json theme={null}
3840 {
3841 "hooks": {
3842 "Elicitation": [
3843 {
3844 "matcher": "issue-tracker",
3845 "hooks": [
3846 {
3847 "type": "command",
3848 "command": "powershell.exe",
3849 "args": [
3850 "-NoProfile",
3851 "-ExecutionPolicy",
3852 "Bypass",
3853 "-File",
3854 "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"
3855 ]
3856 }
3857 ]
3858 }
3859 ]
3860 }
3861 }
3862 ```
3863
3864 このスクリプトをプロジェクトの `.claude/hooks/answer-project-key.ps1` に保存します。
3865
3866 ```powershell theme={null}
3867 $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
3868 $fields = @($request.requested_schema.properties.PSObject.Properties.Name)
3869
3870 if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {
3871 @{
3872 hookSpecificOutput = @{
3873 hookEventName = "Elicitation"
3874 action = "accept"
3875 content = @{ project_key = "DOCS" }
3876 }
3877 } | ConvertTo-Json -Depth 3
3878 }
3879 ```
3880 </Tab>
3881</Tabs>
3882
3883フックが機能することを確認するには、`claude --debug` で Claude Code を起動し、サーバーがプロジェクトキーを尋ねるようなタスクを Claude に与えます。ダイアログは表示されず、[デバッグログ](#debug-hooks)に `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}` で終わる行が記録されます。
3746 3884
3747<h3 id="elicitationresult">3885<h3 id="elicitationresult">
3748 ElicitationResult3886 ElicitationResult
3749</h3>3887</h3>
3750 3888
3751ユーザーが MCP の elicitation に応答した後に実行されます。フックは、応答が MCP サーバーに返送される前に、その応答を監視、変更、またはブロックできます。3889ユーザーが MCP の elicitation に応答した後に実行されます。フックは、応答が MCP サーバーに返される前に、その応答を監視、変更、またはブロックできます。
3890
3891[Elicitation](#elicitation) フックがリクエストに回答した場合、Claude Code は ElicitationResult フックを実行せずにその回答をサーバーに送信します。
3752 3892
3753matcher フィールドは MCP サーバー名と照合されます。3893matcher フィールドは MCP サーバー名と照合されます。
3754 3894
3767 "mcp_server_name": "my-mcp-server",3907 "mcp_server_name": "my-mcp-server",
3768 "action": "accept",3908 "action": "accept",
3769 "content": { "username": "alice" },3909 "content": { "username": "alice" },
3770 "mode": "form",3910 "mode": "form"
3771 "elicitation_id": "elicit-123"
3772}3911}
3773```3912```
3774 3913
3776 ElicitationResult の出力3915 ElicitationResult の出力
3777</h4>3916</h4>
3778 3917
3779ユーザーの応答を上書きするには、`hookSpecificOutput` を含む JSON オブジェクトを返します。3918ElicitationResult フックは、ユーザーの応答をそのまま通過させたり、その値を変更したり、ブロックしたりできます。応答を変更またはブロックするには、0 で終了し、`action` を含む `hookSpecificOutput` オブジェクトを出力します。この表の各行は、1 つの結果に対して返す内容と、MCP サーバーが受け取る内容を示しています。
3919
3920| 目的 | 返す内容 | サーバーが受け取る内容 |
3921| :- | :- | :- |
3922| 応答を通過させる | 出力なし、終了コード 0 | 変更されていないユーザーの応答 |
3923| 送信された値を変更する | `"action": "accept"` と、`content` 内の新しい値 | `accept` と、ユーザーの値の代わりに指定した `content` |
3924| 応答をブロックする | `"action": "decline"` | ユーザーの値を含まない `decline` |
3925| リクエストをキャンセルする | `"action": "cancel"` | `cancel` と、ユーザーが送信した値。値を送らないようにするには `"decline"` を返します |
3926
3927この出力は、[ElicitationResult の入力](#elicitationresult-input)で示した応答を変更し、ユーザーが `alice` を送信したところでサーバーが `alice@example.com` を受け取るようにします。
3780 3928
3781```json theme={null}3929```json theme={null}
3782{3930{
3783 "hookSpecificOutput": {3931 "hookSpecificOutput": {
3784 "hookEventName": "ElicitationResult",3932 "hookEventName": "ElicitationResult",
3785 "action": "decline",3933 "action": "accept",
3786 "content": {}3934 "content": {
3935 "username": "alice@example.com"
3936 }
3787 }3937 }
3788}3938}
3789```3939```
3790 3940
3791| フィールド | 値 | 説明 |3941指定した `content` はユーザーの `content` オブジェクト全体を置き換えるため、変更しないフィールドも含めてください。Claude Code は `action` のない `hookSpecificOutput` を無視するため、`action` も一緒に返してください。
3792| :- | :- | :- |3942
3793| `action` | `accept`、`decline`、`cancel` | ユーザーのアクションを上書きします |3943ElicitationResult フックはユーザーが辞退またはキャンセルした場合にも実行され、フックの `action` がユーザーの action を置き換えます。`accept` を返す前に入力の `action` が `accept` であることを確認してください。確認しないと、フックが辞退されたリクエストを受け入れられたリクエストに変えてしまいます。このスクリプトは、ユーザーが受け入れた場合に同じ変更を行い、他のフィールドは保持し、それ以外の場合は何も出力しません。
3794| `content` | object | フォームフィールドの値を上書きします。`action` が `accept` の場合にのみ意味を持ちます |3944
3945```bash theme={null}
3946#!/bin/bash
3947input=$(cat)
3795 3948
3796終了コード 2 は応答をブロックし、実際のアクションを `decline` に変更します。Claude Code は stderr のメッセージをどこにも表示しません。3949if [ "$(jq -r '.action' <<<"$input")" = "accept" ]; then
3950 jq '{hookSpecificOutput: {hookEventName: "ElicitationResult", action: "accept", content: (.content + {username: (.content.username + "@example.com")})}}' <<<"$input"
3951fi
3952```
3797 3953
3798Claude Code は ElicitationResult フックの JSON 出力の `hookSpecificOutput` に基づいて動作し、`systemMessage` と `continue` は破棄します。3954この出力は応答をブロックします。
3955
3956```json theme={null}
3957{
3958 "hookSpecificOutput": {
3959 "hookEventName": "ElicitationResult",
3960 "action": "decline"
3961 }
3962}
3963```
3964
3965終了コード 2 とトップレベルの `"decision": "block"` でも応答をブロックできます。フックがこれらを組み合わせた場合にどれが有効になるか、ユーザーに何が表示されるか、どのバージョンが `decision` を無視していたかについては、[elicitation を辞退するその他の方法](#other-ways-to-decline-an-elicitation)で説明しています。
3966
3967Claude Code は、どの `action` を返した場合でも、ElicitationResult フックの JSON 出力から `reason`、`systemMessage`、`continue` を破棄します。
3799 3968
3800<h2 id="prompt-based-hooks">3969<h2 id="prompt-based-hooks">
3801 プロンプト ベースのフック3970 プロンプト ベースのフック
3859 4028
3860`type` を `"prompt"` に設定し、`command` の代わりに `prompt` 文字列を提供します。`$ARGUMENTS` プレースホルダーを使用して、フックの JSON 入力データをプロンプト テキストに注入します。4029`type` を `"prompt"` に設定し、`command` の代わりに `prompt` 文字列を提供します。`$ARGUMENTS` プレースホルダーを使用して、フックの JSON 入力データをプロンプト テキストに注入します。
3861 4030
4031プロンプト フックまたは[エージェント フック](#agent-based-hooks)では、`prompt` を「`.env` ファイルを読み取る Bash コマンドをすべてブロックする」のようにブロックまたは許可する対象に関するルールとして記述することも、「すべてのユニット テストが成功する」のように満たされるべき条件として記述することもできます。
4032
3862この `Stop` フックは、Claude が終了する前にすべてのタスクが完了しているかどうかを評価するよう LLM に求めます:4033この `Stop` フックは、Claude が終了する前にすべてのタスクが完了しているかどうかを評価するよう LLM に求めます:
3863 4034
3864```json theme={null}4035```json theme={null}