1159 フックイベント1159 フックイベント
1160</h2>1160</h2>
1161 1161
1162各イベントは、フックを実行できる Claude Code のライフサイクル上のポイントに対応しています。以下のセクションはライフサイクルに沿って、セッションのセットアップからエージェント型ループを経てセッション終了までの順に並んでいます。各セクションでは、イベントが発火するタイミング、サポートする matcher、受け取る JSON 入力、出力を通じて動作を制御する方法を説明します。1162各イベントは、フックを実行できる Claude Code のライフサイクル上のポイントに対応しています。以下のセクションはライフサイクルに沿った順序で並んでおり、セッションのセットアップからエージェント型ループを経てセッション終了までを扱います。各セクションでは、イベントが発火するタイミング、サポートする matcher、受け取る JSON 入力、出力を通じて動作を制御する方法を説明します。
1163 1163
1164<h3 id="sessionstart">1164<h3 id="sessionstart">
1165 SessionStart1165 SessionStart
1166</h3>1166</h3>
1167 1167
1168Claude Code が新しいセッションを開始するとき、または既存のセッションを再開するときに実行されます。既存の issue やコードベースの最近の変更などの開発コンテキストの読み込みや、環境変数の設定に役立ちます。スクリプトを必要としない静的なコンテキストには、代わりに [CLAUDE.md](/docs/ja/memory) を使用してください。1168Claude Code が新しいセッションを開始するとき、または既存のセッションを再開するときに実行されます。既存の issue やコードベースへの最近の変更といった開発コンテキストの読み込みや、環境変数の設定に便利です。スクリプトを必要としない静的なコンテキストには、代わりに [CLAUDE.md](/docs/ja/memory) を使用してください。
1169 1169
1170SessionStart はすべてのセッションで実行されるため、これらのフックは高速に保ってください。サポートされているのは `type: "command"` と `type: "mcp_tool"` のフックのみです。`mcp_tool` フックが実行されるタイミングについては、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)を参照してください。1170SessionStart はすべてのセッションで実行されるため、これらのフックは高速に保ってください。サポートされるのは `type: "command"` と `type: "mcp_tool"` のフックのみです。`mcp_tool` フックが実行されるタイミングについては、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)を参照してください。
1171 1171
1172matcher の値は、セッションがどのように開始されたかに対応します：1172matcher の値は、セッションがどのように開始されたかに対応します。
1173 1173
1174| Matcher | 発火するタイミング |1174| Matcher | 発火するタイミング |
1175| :- | :- |1175| :- | :- |
1177| `resume` | `--resume`、`--continue`、または `/resume` |1177| `resume` | `--resume`、`--continue`、または `/resume` |
1178| `clear` | `/clear` |1178| `clear` | `/clear` |
1179| `compact` | 自動または手動のコンテキスト圧縮 |1179| `compact` | 自動または手動のコンテキスト圧縮 |
1180| `fork` | 既存のセッションからフォークされた新しいセッション：`--resume` または `--continue` と併用した `--fork-session`、`/fork` のバックグラウンドコピー、`/branch`、または[バックグラウンドに移動](/docs/ja/agent-view#from-inside-a-session)した会話 |1180| `fork` | 既存のセッションからフォークされた新しいセッション。`--resume` または `--continue` と組み合わせた `--fork-session`、`/fork` によるバックグラウンドコピー、`/branch`、または[バックグラウンドに移動](/docs/ja/agent-view#from-inside-a-session)した会話が該当します |
1181 1181
1182v2.1.214 より前は、フォークされたセッションはソースとして `"resume"` を報告していました。1182v2.1.214 より前は、フォークされたセッションはソースとして `"resume"` を報告していました。
1183 1183
1184対話セッションを開始したとき、起動時に `--continue` または `--resume` で会話を再開したとき、または `/clear` を実行したとき、SessionStart フックはバックグラウンドで実行されます。すぐに入力を開始でき、再開した会話はフックを待たずに表示されます。ただし Claude の最初の応答はフックの完了を待つため、フックのコンテキストは Claude に届きます。1184対話セッションを開始したとき、起動時に `--continue` または `--resume` で会話を再開したとき、または `/clear` を実行したときは、SessionStart フックがバックグラウンドで実行されます。すぐに入力を始めることができ、再開した会話はフックを待たずに表示されます。ただし、フックのコンテキストが Claude に届くように、Claude の最初の応答はフックの完了を待ちます。
1185 1185
1186セッション内で `/resume` を使って会話を切り替える場合は、代わりに切り替えがフックの完了を待ちます。バックグラウンドのフックがまだ実行中に `/clear` を実行したり別の会話に切り替えたりした場合、フックが返す内容はセッションに一切適用されません。1186セッション内で `/resume` を使って会話を切り替えた場合は、切り替え自体がフックの完了を待ちます。バックグラウンドのフックがまだ実行中に `/clear` を実行したり別の会話に切り替えたりすると、フックが返す内容はセッションに一切適用されません。
1187 1187
1188起動時にも、再開したセッションを含めて同じ待機が適用されます。SessionStart フックの実行中に送信したプロンプトは、フックが完了するまで Claude に届きません。1188起動時にも同じ待機が適用され、再開したセッションも含まれます。SessionStart フックの実行中に送信したプロンプトは、フックが完了するまで Claude に届きません。
1189 1189
1190いずれの待機中も、`Esc` を押すとプロンプトを送信せずに入力欄に戻せます。フックは実行を続けます。1190いずれの待機中も、`Esc` を押すとプロンプトを送信せずに入力欄に戻すことができます。フックは実行を続けます。
1191 1191
1192<h4 id="sessionstart-input">1192<h4 id="sessionstart-input">
1193 SessionStart の入力1193 SessionStart の入力
1194</h4>1194</h4>
1195 1195
1196[共通の入力フィールド](#common-input-fields)に加えて、SessionStart フックは `source` と、オプションで `model`、`agent_type`、`session_title` を受け取ります：1196[共通の入力フィールド](#common-input-fields)に加えて、SessionStart フックは `source` と、オプションで `model`、`agent_type`、`session_title` を受け取ります。
1197 1197
1198| フィールド | 説明 |1198| フィールド | 説明 |
1199| :- | :- |1199| :- | :- |
1200| `source` | セッションの開始方法：新しいセッションの場合は `"startup"`、再開したセッションの場合は `"resume"`、`/clear` の後は `"clear"`、コンテキスト圧縮の後は `"compact"`、既存のセッションからフォークされた新しいセッションの場合は `"fork"` |1200| `source` | セッションの開始方法。新しいセッションでは `"startup"`、再開されたセッションでは `"resume"`、`/clear` の後では `"clear"`、コンテキスト圧縮の後では `"compact"`、既存のセッションからフォークされた新しいセッションでは `"fork"` |
1201| `model` | アクティブなモデルの識別子。たとえば `/clear` の後や、会話の復旧によってセッションが復元された場合などには省略されることがあるため、読み取る前にフィールドの有無を確認してください |1201| `model` | アクティブなモデルの識別子。たとえば `/clear` の後や、会話の復旧によってセッションが復元された場合など、省略されることがあるため、読み取る前にフィールドの有無を確認してください |
1202| `agent_type` | エージェント名。`claude --agent <name>` で Claude Code を起動した場合に存在します |1202| `agent_type` | エージェント名。`claude --agent <name>` で Claude Code を起動した場合に含まれます |
1203| `session_title` | セッションのカスタムタイトル。設定されている場合に存在します。たとえば `--name`、`/rename`、フックの `sessionTitle` 出力、または Agent SDK の `renameSession()` で設定されます。`sessionTitle` を出力するフックは、既存のカスタムタイトルの上書きを避けるために、まずこのフィールドを確認できます |1203| `session_title` | セッションのカスタムタイトル。`--name`、`/rename`、フックの `sessionTitle` 出力、Agent SDK の `renameSession()` などで設定されている場合に含まれます。`sessionTitle` を出力するフックは、既存のカスタムタイトルを上書きしないように、まずこのフィールドを確認できます |
1204 1204
1205名前を付けていないセッションでも、[生成されたタイトル](/docs/ja/sessions#name-your-sessions)を持つことがあります。そのタイトルはカスタムタイトルではなく、`session_title` には含まれません。1205名前を付けていないセッションにも[生成されたタイトル](/docs/ja/sessions#name-your-sessions)が付いている場合があります。このタイトルはカスタムタイトルではないため、`session_title` には含まれません。
1206 1206
1207`source` が `"resume"` または `"fork"` で、トランスクリプトに Claude からの応答が少なくとも 1 つ含まれる場合、SessionStart フックは以下の 4 つのフィールドも受け取ります。フックはこれらを使って、古い会話を再開する際のコストを最初のリクエストの前に報告できます。たとえば [`systemMessage`](#json-output) で報告します。これらのフィールドには Claude Code v2.1.251 以降が必要です。1207`source` が `"resume"` または `"fork"` で、トランスクリプトに Claude の応答が少なくとも 1 つ含まれている場合、SessionStart フックは以下の 4 つのフィールドも受け取ります。フックはこれらを使用して、古い会話を再開するコストを最初のリクエストの前に報告できます。たとえば [`systemMessage`](#json-output) で報告します。これらのフィールドには Claude Code v2.1.251 以降が必要です。
1208 1208
1209| フィールド | 説明 |1209| フィールド | 説明 |
1210| :- | :- |1210| :- | :- |
1211| `seconds_since_last_response` | 再開したトランスクリプト内の最後の応答からの経過秒数（実時間） |1211| `seconds_since_last_response` | 再開されたトランスクリプト内の最後の応答からの経過時間（実時間の秒数） |
1212| `context_tokens` | 再開したセッションの最初のリクエストがプロンプトとして再送信するトークン数 |1212| `context_tokens` | 再開されたセッションの最初のリクエストがプロンプトとして再送信するトークン数 |
1213| `prompt_cache_likely_expired` | 最後の応答がセッションの[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime)より古い場合、またはその後のコンテキスト圧縮によってキャッシュされた会話が置き換えられた場合に `true` |1213| `prompt_cache_likely_expired` | 最後の応答がセッションの[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime)より古い場合、またはその後のコンテキスト圧縮によってキャッシュされた会話が置き換えられた場合に `true` |
1214| `estimated_cache_write_usd` | セッションのモデルで `context_tokens` をプロンプトキャッシュに書き込む推定コスト（米ドル）。応答は含みません |1214| `estimated_cache_write_usd` | セッションのモデルで `context_tokens` をプロンプトキャッシュに書き込む推定コスト（米ドル）。応答は含みません |
1215 1215
1216この例は、最後の応答から 90 分後に再開されたセッションの入力を示しています：1216次の例は、最後の応答から 90 分後に再開されたセッションの入力を示しています。
1217 1217
1218```json theme={null}1218```json theme={null}
1219{1219{
1231```1231```
1232 1232
1233<h4 id="sessionstart-decision-control">1233<h4 id="sessionstart-decision-control">
1234 SessionStart の決定制御1234 SessionStart の判定制御
1235</h4>1235</h4>
1236 1236
1237Claude Code は、[プレーンテキストとして扱う](#exit-code-0) stdout を Claude のコンテキストに追加します。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、次のイベント固有のフィールドを返すことができます：1237Claude Code は、[プレーンテキストとして扱う](#exit-code-0) stdout を Claude のコンテキストに追加します。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、以下のイベント固有のフィールドを返すことができます。
1238 1238
1239| フィールド | 説明 |1239| フィールド | 説明 |
1240| :- | :- |1240| :- | :- |
1241| `additionalContext` | 会話の開始時、最初のプロンプトの前に Claude のコンテキストに追加される文字列。テキストがどのように渡されるか、何を含めるべきかについては [Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |1241| `additionalContext` | 会話の開始時、最初のプロンプトの前に Claude のコンテキストに追加される文字列。テキストの届け方と記述すべき内容については、[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1242| `initialUserMessage` | セッションの最初のユーザーメッセージとして使用される文字列。`-p` フラグを使用した[非対話モード](/docs/ja/headless)で適用され、プロンプトが指定されていなくても最初のターンになります。プロンプトが指定されている場合は、それが次のターンとして続きます。既存のターンに付加される `additionalContext` とは異なり、これはターンそのものを作成します |1242| `initialUserMessage` | セッションの最初のユーザーメッセージとして使用される文字列。`-p` フラグを使った[非対話モード](/docs/ja/headless)で適用され、プロンプトが指定されていなくても最初のターンになります。プロンプトが指定されている場合、それは次のターンとして続きます。既存のターンに付加される `additionalContext` とは異なり、これはターンそのものを作成します |
1243| `sessionTitle` | セッションタイトルを設定します。`/rename` と同じ効果があります。起動フォルダ、git ブランチ、または worktree 名からセッションに自動的に名前を付けるために使用します。`source` が `"startup"`、`"resume"`、または `"fork"` の場合に適用され、`"clear"` と `"compact"` では無視されます |1243| `sessionTitle` | セッションのタイトルを設定します。効果は `/rename` と同じです。起動フォルダ、git ブランチ、worktree 名からセッションに自動的に名前を付けるのに使用します。`source` が `"startup"`、`"resume"`、`"fork"` の場合に適用され、`"clear"` と `"compact"` では無視されます |
1244| `watchPaths` | このセッション中に [FileChanged](#filechanged) イベントを監視する絶対パスの配列 |1244| `watchPaths` | このセッション中に [FileChanged](#filechanged) イベントを監視する絶対パスの配列 |
1245| `reloadSkills` | ブール値。`true` の場合、Claude Code は SessionStart フックの完了後に[スキル](/docs/ja/skills)とコマンドのディレクトリを再スキャンするため、フックがインストールしたスキルは最初のプロンプトから同じセッションで利用できます |1245| `reloadSkills` | ブール値。`true` の場合、Claude Code は SessionStart フックの完了後に[スキル](/docs/ja/skills)とコマンドのディレクトリを再スキャンするため、フックがインストールしたスキルを同じセッションの最初のプロンプトから利用できます |
1246 1246
1247```json theme={null}1247```json theme={null}
1248{1248{
1254}1254}
1255```1255```
1256 1256
1257このイベントではプレーンな stdout がすでに Claude に届くため、コンテキストを読み込むだけのフックは JSON を組み立てずに stdout に直接出力できます。コンテキストを `sessionTitle` などの他のフィールドと組み合わせる必要がある場合は、JSON 形式を使用してください。1257このイベントではプレーンな stdout がすでに Claude に届くため、コンテキストを読み込むだけのフックは JSON を組み立てずに stdout へ直接出力できます。コンテキストを `sessionTitle` などの他のフィールドと組み合わせる必要がある場合は、JSON 形式を使用してください。
1258 1258
1259SessionStart フックがスキルをインストールまたは更新する場合は `reloadSkills` を使用します。スキルの検出は通常 SessionStart フックが完了する前に実行されるため、フックが `~/.claude/skills/` や `.claude/skills/` に書き込んだファイルは、そうしなければ次のセッションでしか利用できません。この例では、共有スキルリポジトリを同期し、再スキャンを要求します：1259SessionStart フックがスキルをインストールまたは更新する場合は `reloadSkills` を使用します。スキルの検出は通常 SessionStart フックの完了前に実行されるため、フックが `~/.claude/skills/` や `.claude/skills/` に書き込んだファイルは、これを使わないと次のセッションでしか表示されません。次の例では、共有スキルのリポジトリを同期し、再スキャンを要求します。
1260 1260
1261```bash theme={null}1261```bash theme={null}
1262#!/bin/bash1262#!/bin/bash
1267echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1267echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1268```1268```
1269 1269
1270リポジトリの URL はプレースホルダーです。独自のスキルリポジトリに置き換えてください。プレースホルダーのままではクローンが失敗し、stderr に `fatal:` メッセージが出力されます。終了コード 0 で終了する SessionStart フックの stderr は情報提供のみを目的としているため、`reloadSkills` の要求は引き続き適用されます。1270リポジトリの URL はプレースホルダーです。自分のスキルリポジトリに置き換えてください。プレースホルダーのままでは clone が失敗し、stderr に `fatal:` メッセージが出力されます。終了コード 0 で終了した SessionStart フックの stderr は情報提供のみを目的としているため、`reloadSkills` の要求は引き続き適用されます。
1271 1271
1272<h4 id="persist-environment-variables">1272<h4 id="persist-environment-variables">
1273 環境変数を永続化する1273 環境変数を永続化する
1274</h4>1274</h4>
1275 1275
1276SessionStart フックは `CLAUDE_ENV_FILE` 環境変数にアクセスできます。この変数は、後続の Bash コマンドのために環境変数を永続化できるファイルパスを提供します。1276SessionStart フックは `CLAUDE_ENV_FILE` 環境変数にアクセスできます。この変数は、後続の Bash コマンド用に環境変数を永続化できるファイルパスを提供します。
1277 1277
1278個々の環境変数を設定するには、`export` 文を `CLAUDE_ENV_FILE` に書き込みます。他のフックが設定した変数を保持するため、追記（`>>`）を使用してください：1278個々の環境変数を設定するには、`CLAUDE_ENV_FILE` に `export` 文を書き込みます。他のフックが設定した変数を保持するために、追記（`>>`）を使用してください。
1279 1279
1280```bash theme={null}1280```bash theme={null}
1281#!/bin/bash1281#!/bin/bash
1289exit 01289exit 0
1290```1290```
1291 1291
1292セットアップコマンドによる環境の変更をすべて取得するには、エクスポートされた変数を実行前後で比較します：1292セットアップコマンドによるすべての環境の変更を取り込むには、エクスポートされた変数を前後で比較します。
1293 1293
1294```bash theme={null}1294```bash theme={null}
1295#!/bin/bash1295#!/bin/bash
1316 Setup1316 Setup
1317</h3>1317</h3>
1318 1318
1319Claude Code を `--init-only` で起動した場合、または `-p` フラグを使用した[非対話モード](/docs/ja/headless)で `--init` か `--maintenance` を付けて起動した場合にのみ発火します。通常の起動時には発火しません。通常のセッション開始とは別に、CI やスクリプトから明示的にトリガーする一度限りの依存関係のインストールや定期的なクリーンアップに使用してください。セッションごとの初期化には、代わりに [SessionStart](#sessionstart) を使用してください。1319`--init-only` で Claude Code を起動した場合、または `-p` フラグを使った[非対話モード](/docs/ja/headless)で `--init` か `--maintenance` を付けて起動した場合にのみ発火します。通常の起動時には発火しません。通常のセッション開始とは別に、CI やスクリプトから明示的にトリガーする一度きりの依存関係のインストールや定期的なクリーンアップに使用します。セッションごとの初期化には、代わりに [SessionStart](#sessionstart) を使用してください。
1320 1320
1321matcher の値は、フックをトリガーした CLI フラグに対応します：1321matcher の値は、フックをトリガーした CLI フラグに対応します。
1322 1322
1323| Matcher | 発火するタイミング |1323| Matcher | 発火するタイミング |
1324| :- | :- |1324| :- | :- |
1325| `init` | `claude --init-only` または `claude -p --init` |1325| `init` | `claude --init-only` または `claude -p --init` |
1326| `maintenance` | `claude -p --maintenance` |1326| `maintenance` | `claude -p --maintenance` |
1327 1327
1328`claude --init-only` を実行すると、Claude Code は Setup フックと、`startup` matcher を持つ `SessionStart` フックを実行し、会話を開始せずに終了します。1328`claude --init-only` を実行すると、Claude Code は Setup フックと `startup` matcher の `SessionStart` フックを実行し、会話を開始せずに終了します。
1329 1329
1330`-p` で会話を開始または続行する場合は、プロンプトも引数として、または stdin へのパイプで指定する必要があります。`SessionStart` フックが [`initialUserMessage`](#sessionstart-decision-control) を提供する場合や、[延期されたツール呼び出し](#defer-a-tool-call-for-later)のあるセッションを再開する場合は、プロンプトを省略できます。1330`-p` で会話を開始または継続する場合は、引数として、または stdin へのパイプでプロンプトも指定する必要があります。`SessionStart` フックが [`initialUserMessage`](#sessionstart-decision-control) を提供する場合や、[延期されたツール呼び出し](#defer-a-tool-call-for-later)を含むセッションを再開する場合は、プロンプトを省略できます。
1331 1331
1332成功した場合、`--init-only` はターミナルに何も出力しません。フックが実行されたことを確認するには、`<path>` をログファイルの場所に置き換えて `claude --debug-file <path> --init-only` で起動し、ログで Setup と SessionStart のフックのエントリを確認してください。1332成功した場合、`--init-only` はターミナルに何も出力しません。フックが実行されたことを確認するには、`claude --debug-file <path> --init-only` で起動し（`<path>` はログファイルの場所に置き換えます）、ログで Setup と SessionStart のフックのエントリを確認してください。
1333 1333
1334Setup はすべての起動時に発火するわけではないため、依存関係のインストールを必要とするプラグインは 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)します。1334Setup はすべての起動時に発火するわけではないため、依存関係のインストールを必要とするプラグインは 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)。
1335 1335
1336<h4 id="setup-input">1336<h4 id="setup-input">
1337 Setup の入力1337 Setup の入力
1338</h4>1338</h4>
1339 1339
1340[共通の入力フィールド](#common-input-fields)に加えて、Setup フックは `"init"` または `"maintenance"` のいずれかに設定された `trigger` フィールドを受け取ります：1340[共通の入力フィールド](#common-input-fields)に加えて、Setup フックは `"init"` または `"maintenance"` のいずれかが設定された `trigger` フィールドを受け取ります。
1341 1341
1342```json theme={null}1342```json theme={null}
1343{1343{
1350```1350```
1351 1351
1352<h4 id="setup-decision-control">1352<h4 id="setup-decision-control">
1353 Setup の決定制御1353 Setup の判定制御
1354</h4>1354</h4>
1355 1355
1356Setup フックはブロックできません。どの終了コードでも実行は続行されます。Claude Code はどの終了コードでも、`systemMessage`、`continue`、`hookSpecificOutput.additionalContext` などの Setup フックの [JSON 出力フィールド](#json-output)を破棄します。`-p` の場合、Setup フックの stdout、stderr、終了コードは、`--output-format stream-json --verbose` で起動したときにのみ、[`hook_response` イベント](/docs/ja/headless#read-session-metadata)として実行の出力に表示されます。1356Setup フックはブロックできず、どの終了コードでも実行は継続されます。どの終了コードであっても、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)として実行の出力に表示されます。
1357 1357
1358Setup フックは `CLAUDE_ENV_FILE` にアクセスできます。このファイルに書き込まれた変数は、[SessionStart フック](#persist-environment-variables)と同様に、セッションの後続の Bash コマンドに引き継がれます。`Setup` で実行されるのは `type: "command"` フックのみです。`Setup` の `type: "mcp_tool"` フックは、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)で説明しているとおり、常にスキップされます。1358Setup フックは `CLAUDE_ENV_FILE` にアクセスできます。このファイルに書き込まれた変数は、[SessionStart フック](#persist-environment-variables)と同様に、セッションの後続の Bash コマンドに引き継がれます。`Setup` で実行されるのは `type: "command"` フックのみです。`Setup` 上の `type: "mcp_tool"` フックは、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)で説明されているとおり、常にスキップされます。
1359 1359
1360<h3 id="instructionsloaded">1360<h3 id="instructionsloaded">
1361 InstructionsLoaded1361 InstructionsLoaded
1362</h3>1362</h3>
1363 1363
1364`CLAUDE.md` または `.claude/rules/*.md` ファイルがコンテキストに読み込まれたときに発火します。このイベントは、即時に読み込まれるファイルについてはセッション開始時に発火し、ファイルが遅延読み込みされるときにも後で再び発火します。たとえば、Claude がネストされた `CLAUDE.md` を含むサブディレクトリにアクセスしたときや、`paths:` フロントマターを持つ条件付きルールが一致したときです。このフックはブロックや決定制御をサポートしていません。可観測性のために非同期で実行されます。1364`CLAUDE.md` または `.claude/rules/*.md` ファイルがコンテキストに読み込まれたときに発火します。このイベントは、即時に読み込まれるファイルについてはセッション開始時に発火し、ファイルが遅延読み込みされたときにも再度発火します。遅延読み込みの例としては、ネストされた `CLAUDE.md` を含むサブディレクトリに Claude がアクセスしたときや、`paths:` フロントマターを持つ条件付きルールが一致したときがあります。このフックはブロックや判定制御をサポートしていません。可観測性を目的として非同期で実行されます。
1365 1365
1366このイベントは、Claude が **Project instructions** 設定を通じて [`AGENTS.md` を直接読み込む](/docs/ja/memory#agents-md)場合には発火しません。`CLAUDE.md` が `AGENTS.md` をインポートする場合は、他のインポートされたファイルと同様に `load_reason` が `include` に設定されて発火し、`CLAUDE.md` が `AGENTS.md` へのシンボリックリンクである場合は、通常の `CLAUDE.md` の読み込みとして発火します。1366Claude が **Project instructions** 設定を通じて [`AGENTS.md` を直接読み込む](/docs/ja/memory#agents-md)場合、このイベントは発火しません。`CLAUDE.md` が `AGENTS.md` をインポートする場合は、他のインポートされたファイルと同様に `load_reason` が `include` に設定されて発火し、`CLAUDE.md` が `AGENTS.md` へのシンボリックリンクである場合は、通常の `CLAUDE.md` の読み込みとして発火します。
1367 1367
1368matcher は `load_reason` に対して照合されます。たとえば、セッション開始時に読み込まれたファイルに対してのみ発火させるには `"matcher": "session_start"` を、遅延読み込みに対してのみ発火させるには `"matcher": "path_glob_match|nested_traversal"` を使用します。1368matcher は `load_reason` に対して照合されます。たとえば、セッション開始時に読み込まれたファイルに対してのみ発火させるには `"matcher": "session_start"` を、遅延読み込みに対してのみ発火させるには `"matcher": "path_glob_match|nested_traversal"` を使用します。
1369 1369
1371 InstructionsLoaded の入力1371 InstructionsLoaded の入力
1372</h4>1372</h4>
1373 1373
1374[共通の入力フィールド](#common-input-fields)に加えて、InstructionsLoaded フックは次のフィールドを受け取ります：1374[共通の入力フィールド](#common-input-fields)に加えて、InstructionsLoaded フックは以下のフィールドを受け取ります。
1375 1375
1376| フィールド | 説明 |1376| フィールド | 説明 |
1377| :- | :- |1377| :- | :- |
1378| `file_path` | 読み込まれた指示ファイルの絶対パス |1378| `file_path` | 読み込まれた指示ファイルの絶対パス |
1379| `memory_type` | ファイルのスコープ：`"User"`、`"Project"`、`"Local"`、または `"Managed"` |1379| `memory_type` | ファイルのスコープ：`"User"`、`"Project"`、`"Local"`、または `"Managed"` |
1380| `load_reason` | ファイルが読み込まれた理由：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"`、または `"compact"`。`"compact"` の値は、コンテキスト圧縮イベントの後に指示ファイルが再読み込みされたときに発火します |1380| `load_reason` | ファイルが読み込まれた理由：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"`、または `"compact"`。`"compact"` の値は、コンテキスト圧縮イベントの後に指示ファイルが再読み込みされたときに発火します |
1381| `globs` | ファイルの `paths:` フロントマターにあるパスの glob パターン（存在する場合）。`path_glob_match` の読み込みでのみ存在します |1381| `globs` | ファイルの `paths:` フロントマターにあるパスの glob パターン（存在する場合）。`path_glob_match` の読み込みの場合にのみ含まれます |
1382| `trigger_file_path` | 遅延読み込みの場合、この読み込みのきっかけとなったアクセス先のファイルのパス |1382| `trigger_file_path` | 遅延読み込みの場合に、この読み込みをトリガーしたアクセス先のファイルのパス |
1383| `parent_file_path` | `include` の読み込みの場合、このファイルをインクルードした親の指示ファイルのパス |1383| `parent_file_path` | `include` の読み込みの場合に、このファイルをインクルードした親の指示ファイルのパス |
1384 1384
1385```json theme={null}1385```json theme={null}
1386{1386{
1395```1395```
1396 1396
1397<h4 id="instructionsloaded-decision-control">1397<h4 id="instructionsloaded-decision-control">
1398 InstructionsLoaded の決定制御1398 InstructionsLoaded の判定制御
1399</h4>1399</h4>
1400 1400
1401InstructionsLoaded フックには決定制御がありません。指示の読み込みをブロックしたり変更したりすることはできません。Claude Code は `systemMessage` や `continue` などの [JSON 出力フィールド](#json-output)を破棄します。このイベントは、監査ログ、コンプライアンスの追跡、可観測性のために使用してください。1401InstructionsLoaded フックには判定制御がありません。指示の読み込みをブロックしたり変更したりすることはできません。Claude Code は、`systemMessage` や `continue` などの [JSON 出力フィールド](#json-output)を破棄します。このイベントは、監査ログ、コンプライアンスの追跡、可観測性に使用してください。
1402 1402
1403<h3 id="userpromptsubmit">1403<h3 id="userpromptsubmit">
1404 UserPromptSubmit1404 UserPromptSubmit
1406 1406
1407ユーザーがプロンプトを送信したとき、Claude がそれを処理する前に実行されます。これにより、プロンプトや会話に基づいて追加のコンテキストを加えたり、プロンプトを検証したり、特定の種類のプロンプトをブロックしたりできます。1407ユーザーがプロンプトを送信したとき、Claude がそれを処理する前に実行されます。これにより、プロンプトや会話に基づいて追加のコンテキストを加えたり、プロンプトを検証したり、特定の種類のプロンプトをブロックしたりできます。
1408 1408
1409`UserPromptSubmit` フックのデフォルトのタイムアウトは、`command`、`http`、`mcp_tool` タイプで 30 秒です。これは、他のほとんどのイベントにおけるこれらのタイプのデフォルトである 600 秒より短くなっています。このフックはすべてのプロンプトの前に実行され、完了するまでモデルの処理をブロックするため、フックが停止するとセッションが止まってしまいます。フックにより長い時間が必要な場合は、フックエントリで `timeout` フィールドを設定してください。1409`UserPromptSubmit` フックのデフォルトのタイムアウトは、`command`、`http`、`mcp_tool` タイプで 30 秒です。これは、他のほとんどのイベントでのこれらのタイプのデフォルトである 600 秒より短くなっています。このフックはすべてのプロンプトの前に実行され、完了するまでモデルの処理をブロックするため、フックが停止するとセッションも停止します。フックにより長い時間が必要な場合は、フックエントリの `timeout` フィールドを設定してください。
1410 1410
1411[`async: true`](#run-hooks-in-the-background) で実行するコマンドフックを除き、タイムアウトに達した `UserPromptSubmit` のコマンド、HTTP、または MCP ツールのフックはキャンセルされ、`additionalContext` を含むその出力は破棄されます。プロンプトはそのコンテキストなしで Claude に届きます。トランスクリプトには、フック名、発生したタイムアウト、および出力が破棄されたことを示す通知が表示されます。1411[`async: true`](#run-hooks-in-the-background) で実行するコマンドフックを除き、タイムアウトに達した `UserPromptSubmit` のコマンド、HTTP、または MCP ツールのフックはキャンセルされ、その出力は `additionalContext` も含めて破棄されます。プロンプトはそのコンテキストなしで Claude に届きます。トランスクリプトには、フック名、発生したタイムアウト、出力が破棄されたことを示す通知が表示されます。
1412 1412
1413タイムアウトに達した `UserPromptSubmit` の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)は、フック名とタイムアウトを示すメッセージとともにプロンプトをブロックします。これは、このイベントのコールバックが、フェイルオープンしてはならないポリシーゲートとして機能している可能性があるためです。セッションは継続します。v2.1.208 より前は、このイベントでのコールバックのタイムアウトは実行エラーとしてターンを終了させていました。1413`UserPromptSubmit` 上の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)がタイムアウトに達すると、フック名とタイムアウトを示すメッセージとともにプロンプトがブロックされます。このイベントのコールバックは、フェイルオープンしてはならないポリシーゲートとして機能している可能性があるためです。セッションは継続します。v2.1.208 より前は、このイベントでコールバックがタイムアウトすると、実行エラーでターンが終了していました。
1414 1414
1415<h4 id="userpromptsubmit-input">1415<h4 id="userpromptsubmit-input">
1416 UserPromptSubmit の入力1416 UserPromptSubmit の入力
1417</h4>1417</h4>
1418 1418
1419[共通の入力フィールド](#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="…">` の行の間に置かれるため、フックがプロンプトを解析する場合はこれらの行を考慮してください。1419[共通の入力フィールド](#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="…">` の行の間に置かれるため、フックがプロンプトを解析する場合はこれらの行を考慮してください。
1420 1420
1421UserPromptSubmit フックは、セッションにカスタムタイトルがある場合、`session_title` も受け取ります。意味は [SessionStart の `session_title` フィールド](#sessionstart-input)と同じです。1421UserPromptSubmit フックは、セッションにカスタムタイトルがある場合に `session_title` も受け取ります。意味は [SessionStart の `session_title` フィールド](#sessionstart-input)と同じです。
1422 1422
1423```json theme={null}1423```json theme={null}
1424{1424{
1432```1432```
1433 1433
1434<h4 id="userpromptsubmit-decision-control">1434<h4 id="userpromptsubmit-decision-control">
1435 UserPromptSubmit の決定制御1435 UserPromptSubmit の判定制御
1436</h4>1436</h4>
1437 1437
1438`UserPromptSubmit` フックは、ユーザーのプロンプトを処理するかどうかを制御し、コンテキストを追加できます。すべての [JSON 出力フィールド](#json-output)を利用できます。1438`UserPromptSubmit` フックは、ユーザーのプロンプトを処理するかどうかを制御し、コンテキストを追加できます。すべての [JSON 出力フィールド](#json-output)を利用できます。
1439 1439
1440終了コード 0 で会話にコンテキストを追加する方法は 2 つあります：1440終了コード 0 で会話にコンテキストを追加する方法は 2 つあります。
1441 1441
1442* **プレーンテキストの stdout**：Claude Code は、[プレーンテキストとして扱う](#exit-code-0) stdout を Claude のコンテキストに追加します1442* **プレーンテキストの stdout**：Claude Code は、[プレーンテキストとして扱う](#exit-code-0) stdout を Claude のコンテキストに追加します
1443* **`additionalContext` を含む JSON**：より細かく制御するには、以下の JSON 形式を使用します。`additionalContext` フィールドがコンテキストとして追加されます1443* **`additionalContext` を含む JSON**：より細かく制御するには、以下の JSON 形式を使用します。`additionalContext` フィールドがコンテキストとして追加されます
1444 1444
1445どちらの方法でも、トランスクリプトに表示されるエントリは作成されません。プレーンな stdout と `additionalContext` の値は、それぞれフック名で始まるシステムリマインダーとして注入され、Claude は両方を読み取ります。配信を確認するには、[デバッグログ](#debug-hooks)を確認してください。1445どちらの経路でも、トランスクリプトに表示されるエントリは作成されません。プレーンな stdout と `additionalContext` の値は、それぞれフック名で始まるシステムリマインダーとして挿入され、Claude は両方を読みます。配信を確認するには、[デバッグログ](#debug-hooks)を確認してください。
1446 1446
1447プロンプトをブロックするには、`decision` を `"block"` に設定した JSON オブジェクトを返します：1447プロンプトをブロックするには、`decision` を `"block"` に設定した JSON オブジェクトを返します。
1448 1448
1449| フィールド | 説明 |1449| フィールド | 説明 |
1450| :- | :- |1450| :- | :- |
1451| `decision` | `"block"` は、プロンプトが Claude に届く前に停止します。プロンプトを続行させるには省略します |1451| `decision` | `"block"` は、プロンプトが Claude に届く前に停止します。プロンプトの続行を許可するには省略します |
1452| `reason` | `decision` が `"block"` の場合にユーザーに表示されます。コンテキストには追加されません |1452| `reason` | `decision` が `"block"` の場合にユーザーに表示されます。コンテキストには追加されません |
1453| `additionalContext` | 送信されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |1453| `additionalContext` | 送信されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1454| `sessionTitle` | セッションタイトルを設定します。プロンプトの内容に基づいてセッションに自動的に名前を付けるために使用します |1454| `sessionTitle` | セッションのタイトルを設定します。プロンプトの内容に基づいてセッションに自動的に名前を付けるのに使用します |
1455| `suppressOriginalPrompt` | フックがプロンプトをブロックするときに `true` の場合、ブロックメッセージからプロンプトのテキストを除外します。[ブロックされたプロンプトが残すもの](#what-a-blocked-prompt-leaves-behind)を参照してください |1455| `suppressOriginalPrompt` | フックがプロンプトをブロックするときに `true` の場合、ブロックメッセージからプロンプトのテキストを除外します。[ブロックされたプロンプトが残すもの](#what-a-blocked-prompt-leaves-behind)を参照してください |
1456 1456
1457終了コード 2 で終了してブロックするフックは、`reason` と同じように扱われます。ブロックメッセージは stderr のテキストをユーザーに表示し、コンテキストには追加されません。1457終了コード 2 で終了してブロックするフックは、`reason` と同じ経路をたどります。ブロックメッセージは stderr のテキストをユーザーに表示し、それはコンテキストには追加されません。
1458 1458
1459```json theme={null}1459```json theme={null}
1460{1460{
1473 ブロックされたプロンプトが残すもの1473 ブロックされたプロンプトが残すもの
1474</h4>1474</h4>
1475 1475
1476ブロックされたプロンプトが Claude に届くことはありませんが、そのテキストがすべての場所から削除されるわけではありません。デフォルトでは、ユーザーに表示されるブロックメッセージは `Original prompt:` と送信されたテキストで終わり、Claude Code はそのメッセージをディスク上のセッションのトランスクリプトファイルに書き込みます。メッセージからテキストを除外するには、`hookSpecificOutput` 内に `"suppressOriginalPrompt": true` を含む JSON を出力します。これは、フックが `decision: "block"` でブロックする場合でも、終了コード 2 で終了する場合でも機能します。JSON を出力しない終了コード 2 のフックでは、ブロックメッセージに常にプロンプトのテキストが含まれます。1476ブロックされたプロンプトは Claude に届きませんが、そのテキストがすべての場所から削除されるわけではありません。デフォルトでは、ユーザーに表示されるブロックメッセージの末尾に `Original prompt:` と送信されたテキストが続き、Claude Code はそのメッセージをディスク上のセッションのトランスクリプトファイルに書き込みます。メッセージからテキストを除外するには、`hookSpecificOutput` 内に `"suppressOriginalPrompt": true` を含む JSON を出力します。これは、フックが `decision: "block"` でブロックする場合でも、終了コード 2 で終了してブロックする場合でも機能します。JSON を出力しない終了コード 2 のフックでは、ブロックメッセージに常にプロンプトのテキストが含まれます。
1477 1477
1478`suppressOriginalPrompt` が変更するのはブロックメッセージだけです。送信されたテキストは、セッションのトランスクリプトやプロンプト履歴などのローカルファイルに引き続き残る可能性があるため、ブロックするフックはシークレットをディスクに残さないための手段にはなりません。これらのファイルを制限または削除するには、[平文での保存](/docs/ja/claude-directory#plaintext-storage)と[ローカルデータの消去](/docs/ja/claude-directory#clear-local-data)を参照してください。1478`suppressOriginalPrompt` が変更するのはブロックメッセージのみです。送信されたテキストは、セッションのトランスクリプトやプロンプト履歴などのローカルファイルに引き続き現れる可能性があるため、ブロックするフックは機密情報をディスクに残さないための手段にはなりません。これらのファイルを制限または削除するには、[プレーンテキストでの保存](/docs/ja/claude-directory#plaintext-storage)と[ローカルデータの消去](/docs/ja/claude-directory#clear-local-data)を参照してください。
1479 1479
1480<h3 id="userpromptexpansion">1480<h3 id="userpromptexpansion">
1481 UserPromptExpansion1481 UserPromptExpansion
1482</h3>1482</h3>
1483 1483
1484ユーザーが入力したコマンドが、Claude に届く前にプロンプトに展開されるときに実行されます。特定のコマンドの直接呼び出しをブロックしたり、特定のスキルにコンテキストを注入したり、ユーザーが呼び出すコマンドをログに記録したりするために使用します。たとえば、`deploy` に一致するフックは承認ファイルが存在しない限り `/deploy` をブロックでき、レビュースキルに一致するフックはチームのレビューチェックリストを `additionalContext` として追加できます。1484ユーザーが入力したコマンドが、Claude に届く前にプロンプトへ展開されるときに実行されます。特定のコマンドの直接呼び出しをブロックしたり、特定のスキルにコンテキストを挿入したり、ユーザーが呼び出したコマンドをログに記録したりするのに使用します。たとえば、`deploy` に一致するフックは承認ファイルが存在しない限り `/deploy` をブロックでき、レビュースキルに一致するフックはチームのレビューチェックリストを `additionalContext` として追加できます。
1485 1485
1486このイベントは、`PreToolUse` がカバーしない経路をカバーします。`Skill` ツールに一致する `PreToolUse` フックは Claude がツールを呼び出したときにのみ発火しますが、`/skillname` を直接入力すると `PreToolUse` を経由しません。`UserPromptExpansion` はその直接の経路で発火します。1486このイベントは、`PreToolUse` がカバーしない経路を扱います。`Skill` ツールに一致する `PreToolUse` フックは Claude がツールを呼び出したときにのみ発火しますが、`/skillname` を直接入力すると `PreToolUse` を経由しません。`UserPromptExpansion` はその直接の経路で発火します。
1487 1487
1488`command_name` で照合します。すべてのプロンプトタイプのコマンドで発火させるには、matcher を空のままにします。1488`command_name` に対して照合します。すべてのプロンプト型コマンドで発火させるには、matcher を空のままにします。
1489 1489
1490<h4 id="userpromptexpansion-input">1490<h4 id="userpromptexpansion-input">
1491 UserPromptExpansion の入力1491 UserPromptExpansion の入力
1492</h4>1492</h4>
1493 1493
1494[共通の入力フィールド](#common-input-fields)に加えて、UserPromptExpansion フックは `expansion_type`、`command_name`、`command_args`、`command_source`、および元の `prompt` 文字列を受け取ります。`expansion_type` フィールドは、スキルとカスタムコマンドの場合は `slash_command`、MCP サーバーのプロンプトの場合は `mcp_prompt` です。1494[共通の入力フィールド](#common-input-fields)に加えて、UserPromptExpansion フックは `expansion_type`、`command_name`、`command_args`、`command_source`、および元の `prompt` 文字列を受け取ります。`expansion_type` フィールドは、スキルとカスタムコマンドでは `slash_command`、MCP サーバーのプロンプトでは `mcp_prompt` になります。
1495 1495
1496```json theme={null}1496```json theme={null}
1497{1497{
1509```1509```
1510 1510
1511<h4 id="userpromptexpansion-decision-control">1511<h4 id="userpromptexpansion-decision-control">
1512 UserPromptExpansion の決定制御1512 UserPromptExpansion の判定制御
1513</h4>1513</h4>
1514 1514
1515`UserPromptExpansion` フックは、展開をブロックしたりコンテキストを追加したりできます。すべての [JSON 出力フィールド](#json-output)を利用できます。1515`UserPromptExpansion` フックは、展開をブロックしたり、コンテキストを追加したりできます。すべての [JSON 出力フィールド](#json-output)を利用できます。
1516 1516
1517| フィールド | 説明 |1517| フィールド | 説明 |
1518| :- | :- |1518| :- | :- |
1519| `decision` | `"block"` はコマンドの展開を防ぎます。続行させるには省略します |1519| `decision` | `"block"` は、コマンドの展開を防ぎます。続行を許可するには省略します |
1520| `reason` | `decision` が `"block"` の場合にユーザーに表示されます |1520| `reason` | `decision` が `"block"` の場合にユーザーに表示されます |
1521| `additionalContext` | 展開されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |1521| `additionalContext` | 展開されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1522 1522
1523終了コード 2 で終了してブロックするフックは、`reason` と同じように扱われます。ブロックメッセージは stderr のテキストをユーザーに表示します。1523終了コード 2 で終了してブロックするフックは、`reason` と同じ経路をたどります。ブロックメッセージは stderr のテキストをユーザーに表示します。
1524 1524
1525```json theme={null}1525```json theme={null}
1526{1526{
1537 MessageDisplay1537 MessageDisplay
1538</h3>1538</h3>
1539 1539
1540アシスタントメッセージが画面にストリーミングされている間に実行されます。Claude Code はメッセージを段階的に表示します。新たに完成した行のバッチがレンダリングできる状態になるたびに、フックはその行を受け取って 1 回実行され、Claude Code はフックが返した置換テキストをその場所にレンダリングします。長いメッセージでは複数回の呼び出しが発生し、短いメッセージでは 1 回だけの場合もあります。1540アシスタントのメッセージが画面にストリーミングされている間に実行されます。Claude Code はメッセージを段階的に表示します。新たに完成した行のバッチがレンダリングできる状態になるたびに、フックがそれらの行を使って 1 回実行され、Claude Code はその位置にフックの置換テキストをレンダリングします。長いメッセージでは複数回呼び出され、短いメッセージでは 1 回だけのこともあります。
1541 1541
1542MessageDisplay は次の用途に使用できます：1542MessageDisplay は次の用途に使用します。
1543 1543
1544* 最小限の表示にするために markdown を取り除く1544* 最小限の表示のために markdown を取り除く
1545* Agent SDK アプリケーションがユーザーに表示するテキストを変換する1545* Agent SDK アプリケーションがユーザーに表示するテキストを変換する
1546* Claude の応答から API キーや内部ホスト名を伏せる1546* Claude の応答から API キーや内部ホスト名を伏せる
1547 1547
1548Claude Code はフックが返るまで各バッチを保持するため、フックは高速に保ってください。フックが失敗またはタイムアウトした場合、Claude Code は元のテキストを表示します。このイベントのデフォルトのタイムアウトは 10 秒です。フックにより長い時間が必要な場合は、フックエントリで `timeout` フィールドを設定してください。1548Claude Code はフックが返るまで各バッチを保留するため、フックは高速に保ってください。フックが失敗するかタイムアウトした場合、Claude Code は元のテキストを表示します。このイベントのデフォルトのタイムアウトは 10 秒です。フックにより長い時間が必要な場合は、フックエントリの `timeout` フィールドを設定してください。
1549 1549
1550MessageDisplay は表示専用です。置換テキストは画面にレンダリングされる内容だけを変更します。トランスクリプトと Claude が参照する内容は元のテキストのままなので、Claude が置換テキストを目にすることはなく、verbose モードでは元のテキストが表示されます。フックが受け取るのはアシスタントメッセージのテキストのみなので、ツールの結果やユーザーが入力したテキストは変更されずにレンダリングされます。1550MessageDisplay は表示専用です。置換テキストは画面にレンダリングされる内容のみを変更します。トランスクリプトと Claude が参照する内容は元のテキストのままなので、Claude が置換テキストを目にすることはなく、詳細モードでは元のテキストが表示されます。フックが受け取るのはアシスタントのメッセージテキストのみなので、ツールの結果やユーザーが入力したテキストは変更されずにレンダリングされます。
1551 1551
1552MessageDisplay は matcher をサポートしておらず、テキストをストリーミングするすべてのアシスタントメッセージで発火します。ツール呼び出しのみの応答など、テキストを含まないメッセージではトリガーされません。1552MessageDisplay は matcher をサポートしておらず、テキストをストリーミングするすべてのアシスタントメッセージで発火します。ツール呼び出しのみの応答など、テキストを含まないメッセージではトリガーされません。
1553 1553
1554Agent SDK のクエリや `claude -p` を含む非対話の実行では、MessageDisplay は行のバッチごとではなく、アシスタントメッセージごとに 1 回実行されます。この 1 回の呼び出しはメッセージの完了後に届き、メッセージの全文を含みます。`index` は `0`、`final` は `true` で、`delta` にはメッセージ全体が含まれます。各メッセージの `delta` テキストを収集するフックは、どちらのモードでも同じ合計テキストを受け取ります。1554Agent SDK のクエリや `claude -p` を含む非対話の実行では、MessageDisplay は行のバッチごとではなく、アシスタントメッセージごとに 1 回実行されます。この 1 回の呼び出しはメッセージの完了後に届き、メッセージのテキスト全体を含みます。`index` は `0`、`final` は `true` で、`delta` にメッセージ全体が入ります。各メッセージの `delta` テキストを収集するフックは、どちらのモードでも同じ合計テキストを受け取ります。
1555 1555
1556<h4 id="messagedisplay-input">1556<h4 id="messagedisplay-input">
1557 MessageDisplay の入力1557 MessageDisplay の入力
1558</h4>1558</h4>
1559 1559
1560[共通の入力フィールド](#common-input-fields)に加えて、MessageDisplay フックは、ターンとメッセージの識別子、メッセージ内でのこの呼び出しの位置、および `delta` 内の新しいテキストを受け取ります。バッチの境界はテキストのストリーミング方法によって異なるため、行が特定の方法でグループ化されることを前提とせず、`index` と `final` を使用してメッセージの進行状況を追跡してください。1560[共通の入力フィールド](#common-input-fields)に加えて、MessageDisplay フックはターンとメッセージの識別子、メッセージ内でのこの呼び出しの位置、および `delta` 内の新しいテキストを受け取ります。バッチの境界はテキストのストリーミング方法に依存するため、行が特定の方法でグループ化されることを期待するのではなく、`index` と `final` を使ってメッセージの進行状況を追跡してください。
1561 1561
1562| フィールド | 説明 |1562| フィールド | 説明 |
1563| :- | :- |1563| :- | :- |
1564| `turn_id` | 現在のターンの UUID |1564| `turn_id` | 現在のターンの UUID |
1565| `message_id` | 表示中のアシスタントメッセージの UUID。同じメッセージのすべてのバッチで一定です。これは API の `msg_…` ID ではないため、トランスクリプトのメッセージ ID と関連付けることはできません |1565| `message_id` | 表示中のアシスタントメッセージの UUID。同じメッセージのすべてのバッチで一定です。これは API の `msg_…` ID ではないため、トランスクリプトのメッセージ ID と対応付けることはできません |
1566| `index` | メッセージ内でのこのバッチの 0 から始まるインデックス |1566| `index` | メッセージ内でのこのバッチの 0 始まりのインデックス |
1567| `final` | メッセージの最後のバッチで `true`。各メッセージには最終バッチが 1 つだけあります |1567| `final` | メッセージの最後のバッチで `true`。各メッセージにはちょうど 1 つの最終バッチがあります |
1568| `delta` | 前のバッチ以降に新たに完成した行（終端の改行を含む）。常に行全体ですが、最終バッチだけは行の途中で終わることがあります。対話的な実行では、メッセージが改行で終わる場合、最終バッチの delta は空になるため、空でない delta ではなく `final` をメッセージ終了のシグナルとして扱ってください。Agent SDK と `claude -p` の実行では、1 回の呼び出しでメッセージ全体が渡されます |1568| `delta` | 前のバッチ以降に新たに完成した行（末尾の改行を含む）。常に行全体ですが、最終バッチは行の途中で終わる場合があります。対話的な実行では、メッセージが改行で終わる場合は最終バッチの delta が空になるため、空でない delta ではなく `final` をメッセージ終了のシグナルとして扱ってください。Agent SDK と `claude -p` の実行では、1 回の呼び出しにメッセージ全体が含まれます |
1569 1569
1570```json theme={null}1570```json theme={null}
1571{1571{
1585 MessageDisplay の出力1585 MessageDisplay の出力
1586</h4>1586</h4>
1587 1587
1588すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、MessageDisplay フックは `displayContent` を返して画面上の delta を置き換えることができます：1588すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、MessageDisplay フックは `displayContent` を返して、画面上の delta を置き換えることができます。
1589 1589
1590| フィールド | 説明 |1590| フィールド | 説明 |
1591| :- | :- |1591| :- | :- |
1592| `displayContent` | delta の代わりに表示されるテキスト。元のテキストを表示するには省略します |1592| `displayContent` | delta の代わりに表示されるテキスト。元のテキストを表示するには省略します |
1593 1593
1594MessageDisplay フックには決定制御がありません。メッセージをブロックしたり、トランスクリプトに保存される内容や Claude に送信される内容を変更したりすることはできません。Claude Code は JSON 出力のうち `displayContent` に基づいて動作し、`systemMessage` と `continue` は破棄します。1594MessageDisplay フックには判定制御がありません。メッセージをブロックしたり、トランスクリプトに保存される内容や Claude に送信される内容を変更したりすることはできません。Claude Code は JSON 出力の `displayContent` に従って動作し、`systemMessage` と `continue` は破棄します。
1595 1595
1596この例では、プレーンテキストで表示するために Claude の応答から markdown の書式を取り除きます。スクリプトは stdin から各バッチを読み取り、`delta` から太字のマーカーとインラインコードのバッククォートを削除して、結果を `displayContent` として返します。1596次の例では、プレーンテキストで表示するために Claude の応答から markdown の書式を取り除きます。スクリプトは stdin から各バッチを読み取り、`delta` から太字のマーカーとインラインコードのバッククォートを削除し、結果を `displayContent` として返します。
1597 1597
1598<Tabs>1598<Tabs>
1599 <Tab title="macOS/Linux">1599 <Tab title="macOS/Linux">
1600 設定ファイルでこのイベントのコマンドフックを登録します：1600 設定ファイルで、このイベントのコマンドフックを登録します。
1601 1601
1602 ```json theme={null}1602 ```json theme={null}
1603 {1603 {
1617 }1617 }
1618 ```1618 ```
1619 1619
1620 このスクリプトをプロジェクトの `.claude/hooks/plain-display.sh` に保存し、`chmod +x` で実行可能にします：1620 このスクリプトをプロジェクトの `.claude/hooks/plain-display.sh` に保存し、`chmod +x` で実行可能にします。
1621 1621
1622 ```bash theme={null}1622 ```bash theme={null}
1623 #!/bin/bash1623 #!/bin/bash
1626 </Tab>1626 </Tab>
1627 1627
1628 <Tab title="Windows (PowerShell)">1628 <Tab title="Windows (PowerShell)">
1629 PowerShell を通じてスクリプトを実行するコマンドフックを登録します：1629 PowerShell 経由でスクリプトを実行するコマンドフックを登録します。
1630 1630
1631 ```json theme={null}1631 ```json theme={null}
1632 {1632 {
1652 }1652 }
1653 ```1653 ```
1654 1654
1655 `-NoProfile` フラグは PowerShell プロファイルの読み込みをスキップしてフックを素早く起動させ、`-ExecutionPolicy Bypass` は PowerShell がローカルのスクリプトファイルを実行できるようにします。1655 `-NoProfile` フラグは PowerShell プロファイルの読み込みをスキップしてフックを高速に起動させ、`-ExecutionPolicy Bypass` は PowerShell がローカルのスクリプトファイルを実行できるようにします。
1656 1656
1657 このスクリプトをプロジェクトの `.claude/hooks/plain-display.ps1` に保存します：1657 このスクリプトをプロジェクトの `.claude/hooks/plain-display.ps1` に保存します。
1658 1658
1659 ```powershell theme={null}1659 ```powershell theme={null}
1660 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json1660 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
1669 </Tab>1669 </Tab>
1670</Tabs>1670</Tabs>
1671 1671
1672markdown を含まないバッチは変更されずにそのまま渡されます。たとえば `jq` がないためにスクリプトが失敗した場合、Claude Code は元のテキストを表示し、失敗はセッション内ではなく[デバッグ出力](#debug-hooks)にのみ記録されます。1672markdown を含まないバッチは変更されずにそのまま通過します。たとえば `jq` がないためにスクリプトが失敗した場合、Claude Code は元のテキストを表示し、その失敗はセッション内ではなく[デバッグ出力](#debug-hooks)にのみ記録されます。
1673 1673
1674<h3 id="pretooluse">1674<h3 id="pretooluse">
1675 PreToolUse1675 PreToolUse
1676</h3>1676</h3>
1677 1677
1678Claude がツールのパラメーターを作成した後、ツール呼び出しを処理する前に実行されます。`EndConversation` を除く任意のツール名に一致します。対象には、`Bash`、`PowerShell`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`Workflow`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` などの組み込みツールと、任意の [MCP ツール名](#match-mcp-tools)が含まれます。1678Claude がツールのパラメーターを作成した後、ツール呼び出しを処理する前に実行されます。`EndConversation` を除く任意のツール名に一致します。対象は、`Bash`、`PowerShell`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`Workflow`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` などの組み込みツールと、任意の [MCP ツール名](#match-mcp-tools)です。
1679 1679
1680何が書き込んだかにかかわらず、特定のファイルがディスク上で変更されたときにフックを実行するには、ファイル編集ツールを名前で照合するのではなく [FileChanged](#filechanged) を使用してください。PreToolUse とは異なり、Claude Code は FileChanged フックを変更後に実行し、決定制御もないため、書き込みをブロックすることはできません。1680書き込んだものが何であれ、特定のファイルがディスク上で変更されたときにフックを実行するには、ファイル編集ツールを名前で照合する代わりに [FileChanged](#filechanged) を使用してください。PreToolUse とは異なり、Claude Code は FileChanged フックを変更の後に実行し、判定制御もないため、書き込みをブロックすることはできません。
1681 1681
1682<Warning>1682<Warning>
1683 PreToolUse は Claude がツールを呼び出したときにのみ実行されます。[プロンプト内で `@` を使って参照した](/docs/ja/common-workflows#reference-files-and-directories)ファイルは、ツール呼び出しなしで追加されます。Claude Code はプロンプトの構築中にその内容を挿入するため、`Read` に一致するフックを含め、PreToolUse フックは一切発火しません。`@` 参照から特定のパスをブロックするには、代わりに [`Read` の拒否ルール](/docs/ja/permissions#read-and-edit)を使用してください。1683 PreToolUse は、Claude がツールを呼び出したときにのみ実行されます。[プロンプト内で `@` を使って参照した](/docs/ja/common-workflows#reference-files-and-directories)ファイルは、ツール呼び出しなしで追加されます。Claude Code はプロンプトを組み立てる際にその内容を挿入するため、`Read` に一致するフックを含め、PreToolUse フックは発火しません。特定のパスを `@` 参照からブロックするには、代わりに [`Read` の拒否ルール](/docs/ja/permissions#read-and-edit)を使用してください。
1684 1684
1685 PreToolUse は [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) に対しても発火しません。1685 PreToolUse は [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) でも発火しません。
1686</Warning>1686</Warning>
1687 1687
1688ツール呼び出しを許可、拒否、確認、または延期するには、[PreToolUse の決定制御](#pretooluse-decision-control)を使用します。1688[PreToolUse の判定制御](#pretooluse-decision-control)を使用して、ツール呼び出しを許可、拒否、確認、または延期します。
1689 1689
1690タイムアウトを超えた `PreToolUse` の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)はツール呼び出しをブロックし、Claude はタイムアウトを示すエラー結果を受け取ります。他のフックが返した明示的な拒否は引き続き優先されます。1690`PreToolUse` 上の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)がタイムアウトを超えると、ツール呼び出しがブロックされ、Claude はタイムアウトを示すエラー結果を受け取ります。他のフックが返した明示的な拒否は引き続き優先されます。
1691 1691
1692<h4 id="pretooluse-input">1692<h4 id="pretooluse-input">
1693 PreToolUse の入力1693 PreToolUse の入力
1695 1695
1696[共通の入力フィールド](#common-input-fields)に加えて、PreToolUse フックは `tool_name`、`tool_input`、`tool_use_id` を受け取ります。1696[共通の入力フィールド](#common-input-fields)に加えて、PreToolUse フックは `tool_name`、`tool_input`、`tool_use_id` を受け取ります。
1697 1697
1698[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 以降が必要です。1698[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 以降が必要です。
1699 1699
1700ファイルツール `Write`、`Edit`、`Read` では、`tool_input.file_path` は常に絶対パスです：1700ファイルツールの `Write`、`Edit`、`Read` では、`tool_input.file_path` は常に絶対パスです。
1701 1701
1702* Claude Code はフックの実行前に `~` と相対パスを展開するため、パスで照合するフックが `~` や同じパスの相対表記によって回避されることはありません1702* Claude Code はフックの実行前に `~` と相対パスを展開するため、パスに対して照合するフックを、`~` や同じパスの相対表記で回避することはできません
1703* Windows では、`$PWD` が `/c/project` のように見える Git Bash でフックを実行する場合でも、パスはバックスラッシュ区切りで届きます1703* Windows では、フックが `$PWD` が `/c/project` のように見える Git Bash で実行される場合でも、パスはバックスラッシュ区切りで届きます
1704* `/src/` のチェックなど、スラッシュで記述された比較はバックスラッシュのパスには一致せず、ツール呼び出しはフックがブロックする対象がなかったかのように続行されます1704* `/src/` のチェックのようにスラッシュで記述した比較はバックスラッシュのパスに決して一致せず、ツール呼び出しはフックがブロックするものがなかったかのように続行されます
1705* 比較する前に区切り文字を正規化してください。Bash では `FILE_PATH="${FILE_PATH//\\//}"`、Python では `file_path.replace("\\", "/")` を使用します。その後、パスは絶対パスなので、`^` で先頭に固定するのではなく `/src/` などのパスセグメントで照合します1705* 比較の前に区切り文字を正規化してください。Bash では `FILE_PATH="${FILE_PATH//\\//}"`、Python では `file_path.replace("\\", "/")` を使用します。その後、パスは絶対パスなので、`^` で固定するのではなく `/src/` のようなパスセグメントで照合してください
1706 1706
1707Windows での `Write` 呼び出しでは、次の内容が渡されます：1707Windows での `Write` 呼び出しでは、次のように届きます。
1708 1708
1709```json theme={null}1709```json theme={null}
1710{1710{
1718}1718}
1719```1719```
1720 1720
1721`tool_input` のフィールドはツールによって異なります：1721`tool_input` のフィールドはツールによって異なります。
1722 1722
1723<a id="bash" />1723<a id="bash" />
1724 1724
1731| フィールド | 型 | 例 | 説明 |1731| フィールド | 型 | 例 | 説明 |
1732| :- | :- | :- | :- |1732| :- | :- | :- | :- |
1733| `command` | string | `"npm test"` | 実行するシェルコマンド |1733| `command` | string | `"npm test"` | 実行するシェルコマンド |
1734| `description` | string | `"Run test suite"` | コマンドの動作の説明（任意） |1734| `description` | string | `"Run test suite"` | コマンドの動作についての説明（省略可） |
1735| `timeout` | number | `120000` | タイムアウト（ミリ秒、任意）。[最大値](/docs/ja/tools-reference#bash-tool-behavior)を超える値は拒否されず、最大値に切り下げられます |1735| `timeout` | number | `120000` | タイムアウト（ミリ秒、省略可）。[最大値](/docs/ja/tools-reference#bash-tool-behavior)を超える値は拒否されず、最大値に切り下げられます |
1736| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |1736| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |
1737 1737
1738Bash コマンドが Git リポジトリ内のファイルを変更した場合、Claude Code は変更内容を記録できます。[`bashEditDiffEnabled`](/docs/ja/settings-reference#basheditdiffenabled) 設定で記録がオンになっている場合は、すべての権限モードで変更を記録します。どのファイルでこの設定を指定できるかは、その設定の項目に記載されています。それ以外の場合は、auto モードと `bypassPermissions` モードでのみ、かつ Claude Code が Bash を通じてファイルを編集するよう Claude に指示した場合にのみ記録します。記録をオフにするには、`bashEditDiffEnabled` を `false` に設定します。バックグラウンドのコマンドと読み取り専用のコマンドには差分は含まれません。1738Bash コマンドが Git リポジトリ内のファイルを変更すると、Claude Code は変更内容を記録できます。[`bashEditDiffEnabled`](/docs/ja/settings-reference#basheditdiffenabled) 設定で記録がオンになっている場合は、すべての権限モードで変更を記録します。どのファイルでこの設定を行えるかは、その設定の項目に記載されています。それ以外の場合は、auto モードと `bypassPermissions` モードで、かつ Claude Code が Claude に Bash 経由でファイルを編集するよう指示した場合にのみ記録します。記録をオフにするには、`bashEditDiffEnabled` を `false` に設定します。バックグラウンドのコマンドと読み取り専用のコマンドには差分は付きません。
1739 1739
1740その後、[PostToolUse フック](#posttooluse)は変更されたファイルを `tool_response.bashEditDiff` で受け取ります。このリストは、コマンドの実行中にリポジトリ配下で変更されたものを対象とします。Git が無視するファイルやサブモジュール内のファイルは含まれません。Claude Code v2.1.269 以降が必要です。1740その後、[PostToolUse フック](#posttooluse)は `tool_response.bashEditDiff` で変更されたファイルを受け取ります。この一覧は、コマンドの実行中にリポジトリ配下で変更されたものを対象とします。Git が無視するファイルとサブモジュール内のファイルは含まれません。Claude Code v2.1.269 以降が必要です。
1741 1741
1742<Note>1742<Note>
1743 このリストはベストエフォートであり、パブリックベータ版です。Claude Code は変更を見逃したり、別のプロセスが同時に変更したファイルを含めたり、サイズ制限で打ち切ったりすることがあります。フィールドの形式は変更される可能性があります。このリストはポリシーの強制ではなく、レビュー対象を見つけるために使用してください。1743 この一覧はベストエフォートであり、パブリックベータ版です。Claude Code は変更を見落としたり、同時に別のプロセスが変更したファイルを含めたり、サイズの上限で打ち切ったりすることがあります。フィールドの形式は変更される可能性があります。この一覧はレビュー対象を見つけるために使用し、ポリシーの強制には使用しないでください。
1744</Note>1744</Note>
1745 1745
1746`changedFiles` と `files` はコマンドが変更したものを列挙し、残りのフィールドはそのリストがどの程度完全で信頼できるかを示します。1746`changedFiles` と `files` はコマンドが変更したものを一覧にし、残りのフィールドはその一覧がどれだけ完全で信頼できるかを示します。
1747 1747
1748| フィールド | 型 | 例 | 説明 |1748| フィールド | 型 | 例 | 説明 |
1749| :- | :- | :- | :- |1749| :- | :- | :- | :- |
1750| `changedFiles` | array | `["/path/to/src/app.ts"]` | コマンドが変更したファイルの絶対パス（最大 200 件）。`files` に差分が含まれる場合、または `moreFiles` が 0 より大きい場合は常に存在します |1750| `changedFiles` | array | `["/path/to/src/app.ts"]` | コマンドが変更したファイルの絶対パス（最大 200 件）。`files` に差分がある場合、または `moreFiles` が 0 より大きい場合に常に含まれます |
1751| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 表示用の、変更された最大 5 ファイルの差分。コマンドが追加または削除したファイルでは `created` または `deleted` が `true` になります |1751| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 表示用の、最大 5 つの変更ファイルの差分。コマンドが追加または削除したファイルでは `created` または `deleted` が `true` になります |
1752| `moreFiles` | number | `2` | `files` に差分が含まれていない変更ファイルの数 |1752| `moreFiles` | number | `2` | `files` に差分が含まれていない変更ファイルの数 |
1753| `unavailable` | boolean | `true` | 差分が不完全な場合、または取得できなかった場合に設定されます |1753| `unavailable` | boolean | `true` | 差分が不完全な場合、または取得できなかった場合に設定されます |
1754| `skipped` | boolean | `true` | `git checkout` や `git stash` など、作業ツリーを移動する Git コマンドの場合に設定され、Claude Code は差分を取得しません |1754| `skipped` | boolean | `true` | `git checkout` や `git stash` など、作業ツリーを移動させる Git コマンドの場合に設定され、Claude Code は差分を取得しません |
1755| `shared` | boolean | `true` | サブエージェントのものなど、別の Bash ツール呼び出しが同時に同じリポジトリで実行された場合に設定されます。そのため、リストに含まれる変更の一部はそのコマンドによるものである可能性があります |1755| `shared` | boolean | `true` | サブエージェントのものなど、別の Bash ツール呼び出しが同じリポジトリで同時に実行された場合に設定されます。一覧の変更の一部はそのコマンドによるものである可能性があります |
1756 1756
1757<a id="powershell" />1757<a id="powershell" />
1758 1758
1760 PowerShell1760 PowerShell
1761</h5>1761</h5>
1762 1762
1763PowerShell コマンドを実行します。プラットフォームごとの利用可否については [PowerShell ツール](/docs/ja/tools-reference#powershell-tool)を参照してください。1763PowerShell コマンドを実行します。プラットフォームごとの利用可否については、[PowerShell ツール](/docs/ja/tools-reference#powershell-tool)を参照してください。
1764 1764
1765フィールドは Bash ツールと同じで、コマンド文字列は `command` に含まれます：1765フィールドは Bash ツールと同じで、コマンド文字列は `command` に入ります。
1766 1766
1767| フィールド | 型 | 例 | 説明 |1767| フィールド | 型 | 例 | 説明 |
1768| :- | :- | :- | :- |1768| :- | :- | :- | :- |
1769| `command` | string | `"Get-ChildItem -Recurse"` | 実行する PowerShell コマンド |1769| `command` | string | `"Get-ChildItem -Recurse"` | 実行する PowerShell コマンド |
1770| `description` | string | `"List files recursively"` | コマンドの動作の説明（任意） |1770| `description` | string | `"List files recursively"` | コマンドの動作についての説明（省略可） |
1771| `timeout` | number | `120000` | タイムアウト（ミリ秒、任意） |1771| `timeout` | number | `120000` | タイムアウト（ミリ秒、省略可） |
1772| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |1772| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |
1773 1773
1774シェルコマンドを検査するフックでは、両方のツールをカバーするように `Bash|PowerShell` で照合してください：1774シェルコマンドを検査するフックでは、両方のツールをカバーするように `Bash|PowerShell` で照合してください。
1775 1775
1776* Windows では、PowerShell ツールが有効になっている場合、Claude は PowerShell をプライマリシェルとして扱い、シェルコマンドをそれを通じて実行します。1776* Windows では、PowerShell ツールが有効になっている環境であればどこでも、Claude は PowerShell をプライマリシェルとして扱い、シェルコマンドをそれ経由で実行します。
1777* Git Bash のない Windows では、このツールは自動的に有効になり、Claude Code は Bash ツールをまったく登録しません。1777* Git Bash のない Windows では、このツールが自動的に有効になり、Claude Code は Bash ツールをまったく登録しません。
1778* `Bash` のみに一致するフックは、その環境では発火しません。1778* `Bash` のみに一致するフックは、その環境では決して発火しません。
1779 1779
1780<h5 id="write">1780<h5 id="write">
1781 Write1781 Write
1810| フィールド | 型 | 例 | 説明 |1810| フィールド | 型 | 例 | 説明 |
1811| :- | :- | :- | :- |1811| :- | :- | :- | :- |
1812| `file_path` | string | `"/path/to/file.txt"` | 読み取るファイルの絶対パス |1812| `file_path` | string | `"/path/to/file.txt"` | 読み取るファイルの絶対パス |
1813| `offset` | number | `10` | 読み取りを開始する行番号（任意） |1813| `offset` | number | `10` | 読み取りを開始する行番号（省略可） |
1814| `limit` | number | `50` | 読み取る行数（任意） |1814| `limit` | number | `50` | 読み取る行数（省略可） |
1815 1815
1816<h5 id="glob">1816<h5 id="glob">
1817 Glob1817 Glob
1821 1821
1822| フィールド | 型 | 例 | 説明 |1822| フィールド | 型 | 例 | 説明 |
1823| :- | :- | :- | :- |1823| :- | :- | :- | :- |
1824| `pattern` | string | `"**/*.ts"` | ファイルと照合する glob パターン |1824| `pattern` | string | `"**/*.ts"` | ファイルを照合する glob パターン |
1825| `path` | string | `"/path/to/dir"` | 検索するディレクトリ（任意）。デフォルトは現在の作業ディレクトリです |1825| `path` | string | `"/path/to/dir"` | 検索するディレクトリ（省略可）。デフォルトは現在の作業ディレクトリです |
1826 1826
1827<h5 id="grep">1827<h5 id="grep">
1828 Grep1828 Grep
1833| フィールド | 型 | 例 | 説明 |1833| フィールド | 型 | 例 | 説明 |
1834| :- | :- | :- | :- |1834| :- | :- | :- | :- |
1835| `pattern` | string | `"TODO.*fix"` | 検索する正規表現パターン |1835| `pattern` | string | `"TODO.*fix"` | 検索する正規表現パターン |
1836| `path` | string | `"/path/to/dir"` | 検索するファイルまたはディレクトリ（任意） |1836| `path` | string | `"/path/to/dir"` | 検索するファイルまたはディレクトリ（省略可） |
1837| `glob` | string | `"*.ts"` | ファイルを絞り込む glob パターン（任意） |1837| `glob` | string | `"*.ts"` | ファイルを絞り込む glob パターン（省略可） |
1838| `output_mode` | string | `"content"` | `"content"`、`"files_with_matches"`、または `"count"`。デフォルトは `"files_with_matches"` です |1838| `output_mode` | string | `"content"` | `"content"`、`"files_with_matches"`、または `"count"`。デフォルトは `"files_with_matches"` です |
1839| `-i` | boolean | `true` | 大文字と小文字を区別しない検索 |1839| `-i` | boolean | `true` | 大文字と小文字を区別しない検索 |
1840| `multiline` | boolean | `false` | 複数行の照合を有効にする |1840| `multiline` | boolean | `false` | 複数行のマッチングを有効にする |
1841 1841
1842<h5 id="webfetch">1842<h5 id="webfetch">
1843 WebFetch1843 WebFetch
1859| フィールド | 型 | 例 | 説明 |1859| フィールド | 型 | 例 | 説明 |
1860| :- | :- | :- | :- |1860| :- | :- | :- | :- |
1861| `query` | string | `"react hooks best practices"` | 検索クエリ |1861| `query` | string | `"react hooks best practices"` | 検索クエリ |
1862| `allowed_domains` | array | `["docs.example.com"]` | 任意：これらのドメインの結果のみを含める |1862| `allowed_domains` | array | `["docs.example.com"]` | 省略可：これらのドメインの結果のみを含める |
1863| `blocked_domains` | array | `["spam.example.com"]` | 任意：これらのドメインの結果を除外する |1863| `blocked_domains` | array | `["spam.example.com"]` | 省略可：これらのドメインの結果を除外する |
1864 1864
1865<h5 id="agent">1865<h5 id="agent">
1866 Agent1866 Agent
1872| :- | :- | :- | :- |1872| :- | :- | :- | :- |
1873| `prompt` | string | `"Find all API endpoints"` | エージェントが実行するタスク |1873| `prompt` | string | `"Find all API endpoints"` | エージェントが実行するタスク |
1874| `description` | string | `"Find API endpoints"` | タスクの短い説明 |1874| `description` | string | `"Find API endpoints"` | タスクの短い説明 |
1875| `subagent_type` | string | `"Explore"` | 使用する専門エージェントの種類 |1875| `subagent_type` | string | `"Explore"` | 使用する特化型エージェントの種類 |
1876| `model` | string | `"sonnet"` | デフォルトを上書きするモデルエイリアス（任意） |1876| `model` | string | `"sonnet"` | デフォルトを上書きするモデルエイリアス（省略可） |
1877 1877
1878フォアグラウンドの Agent 呼び出しが完了すると、[PostToolUse フック](#posttooluse)は `tool_response` でサブエージェントの結果と実行のテレメトリを受け取ります。実行を調べるにはこれらのフィールドを読み取ってください。`totalTokens` と `usage` は最後のリクエストのみを対象とするため、サブエージェント全体のトークンとコストの集計には、`query_source` `"subagent"` で絞り込んだ[トークンとコストのカウンター](/docs/ja/monitoring-usage#token-counter)を使用してください：1878フォアグラウンドの Agent 呼び出しが完了すると、[PostToolUse フック](#posttooluse)は `tool_response` でサブエージェントの結果と実行のテレメトリを受け取ります。実行を調べるにはこれらのフィールドを読んでください。`totalTokens` と `usage` は最後のリクエストのみを対象とするため、サブエージェント全体のトークンとコストの集計には、`query_source` が `"subagent"` で絞り込んだ[トークンとコストのカウンター](/docs/ja/monitoring-usage#token-counter)を使用してください。
1879 1879
1880| フィールド | 型 | 例 | 説明 |1880| フィールド | 型 | 例 | 説明 |
1881| :- | :- | :- | :- |1881| :- | :- | :- | :- |
1882| `status` | string | `"completed"` | フォアグラウンドのサブエージェントでは `"completed"`、バックグラウンドのサブエージェントでは `"async_launched"`。サブエージェントはデフォルトでバックグラウンドで実行されるため、`run_in_background` を省略した Agent 呼び出しも `"async_launched"` になります |1882| `status` | string | `"completed"` | フォアグラウンドのサブエージェントでは `"completed"`、バックグラウンドのサブエージェントでは `"async_launched"`。サブエージェントはデフォルトでバックグラウンドで実行されるため、`run_in_background` を省略した Agent 呼び出しも `"async_launched"` になります |
1883| `agentId` | string | `"a4d2c8f1e0b3a297"` | サブエージェントの実行の識別子 |1883| `agentId` | string | `"a4d2c8f1e0b3a297"` | サブエージェントの実行の識別子 |
1884| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | サブエージェントの最終的なテキストブロック。レポートが `SubagentHandback` を経由するサブエージェントの場合は、その代わりにハンドバックに関する短いメモ |1884| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | サブエージェントの最終的なテキストブロック。レポートが `SubagentHandback` を経由するサブエージェントの場合は、代わりにその引き渡しについての短い注記 |
1885| `resolvedModel` | string | `"claude-sonnet-4-5"` | サブエージェントが開始時に使用したモデル。要求されたモデルとは異なる場合があります |1885| `resolvedModel` | string | `"claude-sonnet-4-5"` | サブエージェントが開始時に使用したモデル。要求されたモデルと異なる場合があります |
1886| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | 使用されたモデルを順に並べたもの（連続する重複はまとめられます）。実行中にモデルが切り替えられた場合にのみ設定されます。Claude Code v2.1.212 以降が必要です |1886| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | 使用されたモデルの順序（連続する重複はまとめられます）。実行中にモデルが切り替えられた場合にのみ設定されます。Claude Code v2.1.212 以降が必要です |
1887| `totalTokens` | number | `12450` | サブエージェントの最後の API リクエストのトークン数（入力、出力、キャッシュのトークンの合計）。実行全体の合計ではありません |1887| `totalTokens` | number | `12450` | サブエージェントの最後の API リクエストのトークン数（入力、出力、キャッシュのトークンの合計）。実行全体の合計ではありません |
1888| `totalDurationMs` | number | `48211` | サブエージェントの実行の実時間 |1888| `totalDurationMs` | number | `48211` | サブエージェントの実行にかかった実時間 |
1889| `totalToolUseCount` | number | `7` | サブエージェントが行ったツール呼び出しの数 |1889| `totalToolUseCount` | number | `7` | サブエージェントが行ったツール呼び出しの数 |
1890| `usage` | object | `{"input_tokens": 8320, ...}` | 最後の API リクエストの種類別トークン内訳：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |1890| `usage` | object | `{"input_tokens": 8320, ...}` | 最後の API リクエストの種類別トークン内訳：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |
1891 1891
1892Claude 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` を読み取ってください。1892Claude 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` を読み取ってください。
1893 1893
1894バックグラウンドのサブエージェントの場合、ツールはタスクがバックグラウンドに移動した時点で返るため、`tool_response` には使用量のフィールドが含まれません。バックグラウンドでの起動はすぐに返り、Claude Code が実行途中でバックグラウンドに移したフォアグラウンドのタスクはその移行時点で返ります。レスポンスには `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile`、`resolvedModel` が含まれます。1894バックグラウンドのサブエージェントの場合、ツールはタスクがバックグラウンドに移った時点で返るため、`tool_response` には使用量のフィールドが含まれません。バックグラウンドでの起動はすぐに返り、Claude Code が実行中にバックグラウンドへ移したフォアグラウンドのタスクはその移行の時点で返ります。`status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile`、`resolvedModel` を持ちます。
1895 1895
1896`completed` レスポンスでは、`resolvedModel` はサブエージェントが開始時に使用したモデルを示し、`availableModels` やその他の上書きが適用される場合など、`tool_input` の `model` の値とは異なることがあります。`async_launched` レスポンスでは、`resolvedModel` はエージェントがバックグラウンドに移動した時点で使用中のモデルを示すため、バックグラウンドへの移行前に行われたモデルの切り替えはそこに反映されます。`modelsUsed` と、バックグラウンド移行時点の `resolvedModel` の動作には Claude Code v2.1.212 以降が必要です。1896`completed` の応答では、`resolvedModel` はサブエージェントが開始時に使用したモデルを示します。これは、`availableModels` や他の上書きが適用される場合など、`tool_input` の `model` の値と異なることがあります。`async_launched` の応答では、`resolvedModel` はエージェントがバックグラウンドに移った時点で使用していたモデルを示すため、バックグラウンドに移る前に行われた切り替えがそこに反映されます。`modelsUsed` と、バックグラウンド移行時の `resolvedModel` の動作には Claude Code v2.1.212 以降が必要です。
1897 1897
1898<a id="askuserquestion" />1898<a id="askuserquestion" />
1899 1899
1901 AskUserQuestion1901 AskUserQuestion
1902</h5>1902</h5>
1903 1903
1904ユーザーに 1～4 個の多肢選択式の質問をします。1904ユーザーに 1〜4 個の多肢選択式の質問をします。
1905 1905
1906| フィールド | 型 | 例 | 説明 |1906| フィールド | 型 | 例 | 説明 |
1907| :- | :- | :- | :- |1907| :- | :- | :- | :- |
1908| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 提示する質問。それぞれ `question` 文字列、短い `header`、`options` 配列、および任意の `multiSelect` フラグを持ちます |1908| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 提示する質問。それぞれ `question` 文字列、短い `header`、`options` 配列、省略可能な `multiSelect` フラグを持ちます |
1909| `answers` | object | `{"Which framework?": "React"}` | 任意。質問のテキストを選択されたオプションのラベルに対応付けます。複数選択の回答では、ラベルをカンマで結合します。Claude はこのフィールドを設定しません。プログラムで回答するには `updatedInput` を通じて指定します |1909| `answers` | object | `{"Which framework?": "React"}` | 省略可。質問のテキストを選択されたオプションのラベルに対応付けます。複数選択の回答は、ラベルをカンマで連結します。Claude はこのフィールドを設定しません。プログラムで回答するには `updatedInput` 経由で指定してください |
1910 1910
1911<h5 id="exitplanmode">1911<h5 id="exitplanmode">
1912 ExitPlanMode1912 ExitPlanMode
1913</h5>1913</h5>
1914 1914
1915Claude が [plan モード](/docs/ja/permission-modes#analyze-before-you-edit-with-plan-mode)を終了する前に、計画を提示してユーザーに承認を求めます。Claude はツールを呼び出す前に計画をディスク上のファイルに書き込むため、モデルからの実際の `tool_input` は通常空です。Claude Code は、入力をフックに渡す前に計画の内容とファイルパスを注入します。1915Claude が [plan モード](/docs/ja/permission-modes#analyze-before-you-edit-with-plan-mode)を終了する前に、計画を提示してユーザーに承認を求めます。Claude はツールを呼び出す前に計画をディスク上のファイルに書き込むため、モデルからの `tool_input` そのものは通常空です。Claude Code は、入力をフックに渡す前に計画の内容とファイルパスを挿入します。
1916 1916
1917| フィールド | 型 | 例 | 説明 |1917| フィールド | 型 | 例 | 説明 |
1918| :- | :- | :- | :- |1918| :- | :- | :- | :- |
1919| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 形式の計画の内容。ディスク上の計画ファイルから注入されます |1919| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 形式の計画の内容。ディスク上の計画ファイルから挿入されます |
1920| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 計画ファイルへのパス。注入されます |1920| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 計画ファイルのパス。挿入されます |
1921| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 非推奨。Claude Code はこのフィールドを受け付けますが無視します。v2.1.205 より前は、計画を実装するために Claude が要求したプロンプトベースの権限を保持していました |1921| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 非推奨。Claude Code はこのフィールドを受け付けますが、無視します。v2.1.205 より前は、計画を実行するために Claude が要求したプロンプトベースの権限を保持していました |
1922 1922
1923`PostToolUse` では、`tool_response` は承認された計画を保持する `plan` と `filePath` フィールド、および内部のステータスフラグを持つオブジェクトです。計画の内容は、ディスクからファイルを再度読み込むのではなく `tool_response.plan` から読み取ってください。1923`PostToolUse` では、`tool_response` は承認された計画を保持する `plan` と `filePath` のフィールドに加えて、内部のステータスフラグを持つオブジェクトです。計画の内容は、ディスクからファイルを読み直すのではなく、`tool_response.plan` から読み取ってください。
1924 1924
1925<h4 id="pretooluse-decision-control">1925<h4 id="pretooluse-decision-control">
1926 PreToolUse の決定制御1926 PreToolUse の判定制御
1927</h4>1927</h4>
1928 1928
1929`PreToolUse` フックは、ツール呼び出しを続行するかどうかを制御できます。トップレベルの `decision` フィールドを使用する他のフックとは異なり、PreToolUse は `hookSpecificOutput` オブジェクト内で決定を返します。これにより、4 つの結果（allow、deny、ask、defer）に加えて、実行前にツールの入力を変更する機能という、より豊富な制御が可能になります。1929`PreToolUse` フックは、ツール呼び出しを続行するかどうかを制御できます。トップレベルの `decision` フィールドを使用する他のフックとは異なり、PreToolUse は `hookSpecificOutput` オブジェクト内で判定を返します。これにより、より細かな制御が可能になります。4 つの結果（許可、拒否、確認、延期）に加えて、実行前にツールの入力を変更できます。
1930 1930
1931| フィールド | 説明 |1931| フィールド | 説明 |
1932| :- | :- |1932| :- | :- |
1933| `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)は引き続き評価されます |1933| `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)は引き続き評価されます |
1934| `permissionDecisionReason` | `"ask"` の場合、ユーザーには表示されますが Claude には表示されません。`"deny"` の場合、Claude に表示されます。`"allow"` と `"defer"` の場合、[デバッグログ](#debug-hooks)にのみ書き込まれます |1934| `permissionDecisionReason` | `"ask"` の場合、権限プロンプトでユーザーに表示されます。誰もそのプロンプトに応答できない `-p` の実行で Claude Code が[呼び出しを拒否する](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)場合は、代わりに Claude がツール結果でその理由を読みます。`"deny"` の場合、Claude に表示されます。`"allow"` と `"defer"` の場合、[デバッグログ](#debug-hooks)にのみ書き込まれます |
1935| `updatedInput` | 実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。Claude Code は、権限ルールと Bash コマンドの[自動バックグラウンド化の対象かどうか](/docs/ja/tools-reference#foreground-commands-that-move-to-the-background)を、Claude が送信した入力ではなくフックが返した入力に対して評価します。自動承認するには `"allow"` と、変更後の入力をユーザーに表示するには `"ask"` と組み合わせます。`"defer"` の場合は無視されます |1935| `updatedInput` | 実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。Claude Code は、権限ルールと Bash コマンドの[自動バックグラウンド化の対象かどうか](/docs/ja/tools-reference#foreground-commands-that-move-to-the-background)を、Claude が送信した入力ではなく、フックが返した入力に対して評価します。自動承認するには `"allow"` と、変更した入力をユーザーに表示するには `"ask"` と組み合わせます。`"defer"` の場合は無視されます |
1936| `additionalContext` | ツールの結果とともに Claude のコンテキストに追加される文字列。`permissionDecision` が `"defer"` の場合は無視されます。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |1936| `additionalContext` | ツールの結果とともに Claude のコンテキストに追加される文字列。`permissionDecision` が `"defer"` の場合は無視されます。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1937 1937
1938複数の PreToolUse フックが異なる決定を返した場合、優先順位は `deny` > `defer` > `ask` > `allow` です。1938複数の PreToolUse フックが異なる判定を返した場合、優先順位は `deny` > `defer` > `ask` > `allow` です。
1939 1939
1940終了コード 2 で終了してブロックするフックは、`"deny"` と同じように扱われます。Claude は stderr のメッセージを拒否の理由として受け取ります。1940終了コード 2 で終了してブロックするフックは、`"deny"` と同じ経路をたどります。Claude は stderr のメッセージを拒否の理由として受け取ります。
1941 1941
1942フックが `"ask"` を返した場合、ユーザーに表示される権限プロンプトには、フックの出どころを示すラベルが含まれます。任意の設定ファイルまたはエージェントのフロントマターからのフックには `[settings]`、プラグインのフックには `[plugin:<name>]`、スキルのフロントマターからのフックには `[skill]` が表示されます。これにより、どの設定ソースが確認を求めているかをユーザーが把握しやすくなります。1942フックが `"ask"` を返すと、ユーザーに表示される権限プロンプトには、フックの出どころを示すラベルが含まれます。任意の設定ファイルまたはエージェントのフロントマターからのフックでは `[settings]`、プラグインのフックでは `[plugin:<name>]`、スキルのフロントマターからのフックでは `[skill]` です。これにより、どの設定ソースが確認を求めているかをユーザーが理解しやすくなります。
1943 1943
1944フックの `"ask"` は、[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)でも権限プロンプトを強制します。分類器はツール呼び出しを拒否することはできますが、プロンプトを表示せずに承認することはできません。v2.1.211 より前は、分類器は[サンドボックス](/docs/ja/sandboxing)の外で実行される Bash コマンドを、フックが要求したプロンプトを表示せずに承認できました。その場合でも分類器はそのコマンドに独自の安全ルールを適用し、フックの `"deny"` は常に尊重されていました。1944フックの `"ask"` は、[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)でも権限プロンプトを強制します。分類器は引き続きツール呼び出しを拒否できますが、呼び出しを黙って承認することはできません。v2.1.211 より前は、分類器は[サンドボックス](/docs/ja/sandboxing)外で実行される Bash コマンドを、フックが要求したプロンプトを表示せずに承認できました。その場合も分類器はそのコマンドに独自の安全ルールを適用しており、フックの `"deny"` は常に尊重されていました。
1945 1945
1946```json theme={null}1946```json theme={null}
1947{1947{
1959 1959
1960<span id="allow-with-updatedinput" />1960<span id="allow-with-updatedinput" />
1961 1961
1962`-p` フラグを使用した[非対話モード](/docs/ja/headless)では、Claude Code は、Agent SDK の `canUseTool` コールバックなど、プロンプトを受け取る[権限ホスト](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)が実行にある場合にのみ、`AskUserQuestion` と `ExitPlanMode` を提供します。これらのツールにはユーザーの操作が必要です。`permissionDecision: "allow"` を `updatedInput` とともに返すと、その要件を満たせます。フックは stdin からツールの入力を読み取り、独自の UI を通じて回答を収集し、それを `updatedInput` で返すことで、ツールはプロンプトを表示せずに実行されます。これらのツールでは `"allow"` だけを返しても十分ではありません。`AskUserQuestion` の場合は、元の `questions` 配列をそのまま返し、各質問のテキストを選択された回答に対応付ける [`answers`](#askuserquestion) オブジェクトを追加します。1962`-p` フラグを使った[非対話モード](/docs/ja/headless)では、Claude Code は、Agent SDK の `canUseTool` コールバックなど、プロンプトを受け取る[権限ホスト](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)が実行にある場合にのみ、`AskUserQuestion` と `ExitPlanMode` を提供します。これらのツールにはユーザーの操作が必要です。`permissionDecision: "allow"` を `updatedInput` とともに返すと、その要件を満たせます。フックは stdin からツールの入力を読み取り、独自の UI で回答を収集し、それを `updatedInput` で返すことで、ツールはプロンプトなしで実行されます。これらのツールでは、`"allow"` だけを返しても十分ではありません。`AskUserQuestion` の場合は、元の `questions` 配列をそのまま返し、各質問のテキストを選択された回答に対応付ける [`answers`](#askuserquestion) オブジェクトを追加してください。
1963 1963
1964v2.1.199 以降、サーバーが [`_meta["anthropic/requiresUserInteraction"]`](/docs/ja/mcp#require-approval-for-a-specific-tool) でマークした MCP ツールはより厳格です。Claude Code はツールが必要とする操作をフックが収集したことを確認できないため、`updatedInput` の有無にかかわらず、フックは `"allow"` でその承認プロンプトをスキップできません。1964サーバーが [`_meta["anthropic/requiresUserInteraction"]`](/docs/ja/mcp#require-approval-for-a-specific-tool) でマークした MCP ツールはさらに厳格です。フックは `updatedInput` の有無にかかわらず、`"allow"` でその承認プロンプトをスキップすることはできません。ツールが必要とする操作をフックが収集したことを Claude Code が確認できないためです。
1965 1965
1966<Note>1966<Note>
1967 PreToolUse では以前はトップレベルの `decision` と `reason` フィールドを使用していましたが、このイベントではこれらは非推奨です。代わりに `hookSpecificOutput.permissionDecision` と `hookSpecificOutput.permissionDecisionReason` を使用してください。非推奨の値 `"approve"` と `"block"` は、それぞれ `"allow"` と `"deny"` に対応します。PostToolUse や Stop などの他のイベントでは、現在の形式として引き続きトップレベルの `decision` と `reason` を使用します。1967 PreToolUse は以前はトップレベルの `decision` と `reason` フィールドを使用していましたが、このイベントではこれらは非推奨です。代わりに `hookSpecificOutput.permissionDecision` と `hookSpecificOutput.permissionDecisionReason` を使用してください。非推奨の値 `"approve"` と `"block"` は、それぞれ `"allow"` と `"deny"` に対応します。PostToolUse や Stop などの他のイベントでは、現在の形式としてトップレベルの `decision` と `reason` を引き続き使用します。
1968</Note>1968</Note>
1969 1969
1970<h4 id="defer-a-tool-call-for-later">1970<h4 id="defer-a-tool-call-for-later">
1971 ツール呼び出しを後で実行するために延期する1971 ツール呼び出しを後で実行するために延期する
1972</h4>1972</h4>
1973 1973
1974`"defer"` は、Agent SDK アプリや Claude Code 上に構築したカスタム UI など、`claude -p` をサブプロセスとして実行してその JSON 出力を読み取る統合向けです。呼び出し元のプロセスは、ツール呼び出しの時点で Claude を一時停止し、独自のインターフェースで入力を収集して、中断したところから再開できます。Claude Code がこの値を尊重するのは、`-p` フラグを使用した[非対話モード](/docs/ja/headless)の場合のみです。対話セッションでは警告をログに記録し、フックの結果を無視します。1974`"defer"` は、Agent SDK アプリや Claude Code 上に構築したカスタム UI など、`claude -p` をサブプロセスとして実行し、その JSON 出力を読み取るインテグレーション向けです。これにより、呼び出し元のプロセスは Claude をツール呼び出しの時点で一時停止し、独自のインターフェースで入力を収集して、中断した場所から再開できます。Claude Code がこの値を尊重するのは、`-p` フラグを使った[非対話モード](/docs/ja/headless)のみです。対話セッションでは警告をログに記録し、フックの結果を無視します。
1975 1975
1976`AskUserQuestion` ツールが典型的なケースです。Claude はユーザーに何かを質問したいものの、回答するためのターミナルがありません。`-p` の実行で `AskUserQuestion` が提供されるのは、`--permission-prompt-tool` で渡す MCP ツールなどの[権限ホスト](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)がある場合のみなので、権限ホストを指定して実行を開始してください。往復の流れは次のとおりです：1976典型的なケースは `AskUserQuestion` ツールです。Claude はユーザーに何かを尋ねたいのに、回答するためのターミナルがありません。`-p` の実行では、`--permission-prompt-tool` で渡す MCP ツールなどの[権限ホスト](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)がある場合にのみ `AskUserQuestion` が提供されるため、権限ホストを指定して実行を開始してください。往復の流れは次のとおりです。
1977 1977
19781. Claude が `AskUserQuestion` を呼び出します。`PreToolUse` フックが発火します。19781. Claude が `AskUserQuestion` を呼び出します。`PreToolUse` フックが発火します。
19792. フックが `permissionDecision: "defer"` を返します。ツールは実行されません。プロセスは `stop_reason: "tool_deferred"` で終了し、保留中のツール呼び出しはトランスクリプトに保存されます。19792. フックが `permissionDecision: "defer"` を返します。ツールは実行されません。プロセスは `stop_reason: "tool_deferred"` で終了し、保留中のツール呼び出しはトランスクリプトに保存されます。
19803. 呼び出し元のプロセスは SDK の結果から `deferred_tool_use` を読み取り、独自の UI に質問を表示して回答を待ちます。19803. 呼び出し元のプロセスは SDK の結果から `deferred_tool_use` を読み取り、独自の UI で質問を表示して回答を待ちます。
19814. 呼び出し元のプロセスは、同じ権限ホストを指定して `claude -p --resume <session-id>` を実行します。同じツール呼び出しによって再び `PreToolUse` が発火します。19814. 呼び出し元のプロセスは、同じ権限ホストを指定して `claude -p --resume <session-id>` を実行します。同じツール呼び出しで再び `PreToolUse` が発火します。
19825. フックは `updatedInput` に回答を含めて `permissionDecision: "allow"` を返します。ツールが実行され、Claude は処理を続行します。19825. フックは `updatedInput` に回答を入れて `permissionDecision: "allow"` を返します。ツールが実行され、Claude は処理を続けます。
1983 1983
1984`deferred_tool_use` フィールドには、ツールの `id`、`name`、`input` が含まれます。`input` は Claude がツール呼び出しのために生成したパラメーターで、実行前に取得されたものです：1984`deferred_tool_use` フィールドには、ツールの `id`、`name`、`input` が含まれます。`input` は、Claude がツール呼び出しのために生成したパラメーターで、実行前に取得されたものです。
1985 1985
1986```json theme={null}1986```json theme={null}
1987{1987{
1997}1997}
1998```1998```
1999 1999
2000タイムアウトや再試行の制限はありません。セッションは再開するまでディスク上に残りますが、[`cleanupPeriodDays`](/docs/ja/settings-reference#cleanupperioddays) による保持期間のクリーンアップの対象となります。このクリーンアップは、[保持期間のクリーンアップのルール](/docs/ja/claude-directory#cleaned-up-automatically)に従い、デフォルトで 30 日後にセッションファイルを削除します。再開時に回答の準備ができていない場合、フックは再び `"defer"` を返すことができ、プロセスは同じように終了します。呼び出し元のプロセスは、最終的にフックから `"allow"` または `"deny"` を返すことで、ループを抜けるタイミングを制御します。2000タイムアウトや再試行の上限はありません。セッションは再開するまでディスク上に残りますが、[`cleanupPeriodDays`](/docs/ja/settings-reference#cleanupperioddays) の保持期間による削除の対象となります。この削除は、[保持期間の削除ルール](/docs/ja/claude-directory#cleaned-up-automatically)に従い、デフォルトでは 30 日後にセッションファイルを削除します。再開時に回答の準備ができていない場合、フックは再び `"defer"` を返すことができ、プロセスは同じ方法で終了します。呼び出し元のプロセスは、最終的にフックから `"allow"` または `"deny"` を返すことで、いつループを抜けるかを制御します。
2001 2001
2002`"defer"` は、Claude がそのターンで単一のツール呼び出しを行う場合にのみ機能します。Claude が複数のツール呼び出しを一度に行う場合、`"defer"` は警告とともに無視され、ツールは通常の権限フローで処理されます。この制約があるのは、再開時には 1 つのツールしか再実行できないためです。バッチの中の 1 つの呼び出しだけを、他の呼び出しを未解決のまま残さずに延期する方法はありません。2002`"defer"` は、Claude がそのターンで単一のツール呼び出しを行う場合にのみ機能します。Claude が複数のツール呼び出しを一度に行う場合、`"defer"` は警告とともに無視され、ツールは通常の権限フローで処理されます。この制約は、再開時に再実行できるツールが 1 つだけだからです。バッチ内の 1 つの呼び出しだけを延期すると、他の呼び出しが未解決のまま残ってしまいます。
2003 2003
2004再開時に延期されたツールが利用できなくなっている場合、プロセスはフックが発火する前に `stop_reason: "tool_deferred_unavailable"` と `is_error: true` で終了します。これは、ツールを提供していた MCP サーバーが再開したセッションで接続されていない場合に発生します。`deferred_tool_use` ペイロードは引き続き含まれるため、どのツールが見つからなくなったかを特定できます。2004再開時に延期されたツールが利用できなくなっている場合、プロセスはフックが発火する前に `stop_reason: "tool_deferred_unavailable"` と `is_error: true` で終了します。これは、ツールを提供していた MCP サーバーが再開されたセッションで接続されていない場合に発生します。`deferred_tool_use` ペイロードは引き続き含まれるため、どのツールが失われたかを特定できます。
2005 2005
2006<Note>2006<Note>
2007 延期されたセッションを 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 以降が必要です。2007 延期されたセッションを 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 以降が必要です。
2008 2008
2009 `-p` で再開する場合、Claude Code はそれ以外の保存された権限モードを復元しません。新しい `claude -p` の実行が開始するときと同じ権限モードで実行を開始するため、延期されたセッションで `--permission-mode` または `--dangerously-skip-permissions` を使用していた場合は、再度渡してください。`-p` なしで `claude --resume <session-id>` を使用して再開する場合、Claude Code は保存された権限モードを復元します。ただし、[再開時の権限モード](/docs/ja/sessions#permission-mode-on-resume)に記載されている例外があります。2009 `-p` で再開する場合、Claude Code は他の保存された権限モードを復元しません。新しい `claude -p` の実行が開始する権限モードで実行を開始するため、延期されたセッションで `--permission-mode` や `--dangerously-skip-permissions` を使用していた場合は、再度渡してください。`-p` なしで `claude --resume <session-id>` を使って再開する場合、Claude Code は保存された権限モードを復元します。例外は[再開時の権限モード](/docs/ja/sessions#permission-mode-on-resume)に記載されています。
2010</Note>2010</Note>
2011 2011
2012<h3 id="permissionrequest">2012<h3 id="permissionrequest">
2013 PermissionRequest2013 PermissionRequest
2014</h3>2014</h3>
2015 2015
2016Claude Code がツールを使用する権限をユーザーに求めようとするときに実行されます。[非対話モード](/docs/ja/headless)のバックグラウンドのサブエージェントなど、プロンプトを表示できないセッションでも、Claude Code はこれらのフックを実行し、どのフックも決定を返さなかった場合はツール呼び出しを拒否します。`--permission-prompt-tool` または Agent SDK の [`canUseTool` コールバック](/docs/ja/agent-sdk/permissions)に届く呼び出しでは、フックはホストと並行して実行され、先に決定した方が適用されます。2016Claude Code がツールを使用するための権限をユーザーに求めようとしているときに実行されます。[非対話モード](/docs/ja/headless)のバックグラウンドのサブエージェントなど、プロンプトを表示できないセッションでも、Claude Code はこれらのフックを実行し、どのフックも判定を返さない場合はツール呼び出しを拒否します。`--permission-prompt-tool` または Agent SDK の [`canUseTool` コールバック](/docs/ja/agent-sdk/permissions)に到達する呼び出しの場合、フックはホストと並行して実行され、先に判定したほうが適用されます。
2017ユーザーに代わって許可または拒否するには、[PermissionRequest の決定制御](#permissionrequest-decision-control)を使用します。2017[PermissionRequest の判定制御](#permissionrequest-decision-control)を使用して、ユーザーに代わって許可または拒否します。
2018 2018
2019Claude がツールの使用について権限を求めた瞬間にシグナルが必要な場合は、このイベントを使用してください。Claude Code は、`permission_prompt` タイプの [Notification](#notification) フックを、プロンプトが約 6 秒待機した後にのみ実行します。2019Claude がツールを使用するための権限を求めた瞬間にシグナルが必要な場合に、このイベントを使用します。Claude Code が `permission_prompt` タイプの [Notification](#notification) フックを実行するのは、プロンプトが約 6 秒間待機した後です。
2020 2020
2021Claude Code は、サンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)については PermissionRequest フックを実行しません。そのプロンプトのシグナルを得るには、`permission_prompt` 通知タイプを使用してください。2021Claude Code は、サンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)に対しては PermissionRequest フックを実行しません。そのプロンプトのシグナルを得るには、`permission_prompt` 通知タイプを使用してください。
2022 2022
2023PreToolUse と同じ値で、ツール名で照合します。2023ツール名に対して照合し、値は PreToolUse と同じです。
2024 2024
2025<h4 id="permissionrequest-input">2025<h4 id="permissionrequest-input">
2026 PermissionRequest の入力2026 PermissionRequest の入力
2027</h4>2027</h4>
2028 2028
2029PermissionRequest フックは、PreToolUse フックと同様に `tool_name` と `tool_input` フィールドを受け取りますが、`tool_use_id` は含まれません。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。任意の `permission_suggestions` 配列には、許可ルールの追加や権限モードの変更など、Claude Code がこのリクエストに対して提案する[権限の更新](#permission-update-entries)が含まれます。2029PermissionRequest フックは、PreToolUse フックと同様に `tool_name` と `tool_input` フィールドを受け取りますが、`tool_use_id` は含まれません。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。省略可能な `permission_suggestions` 配列には、許可ルールの追加や権限モードの変更など、このリクエストに対して Claude Code が提案する[権限の更新](#permission-update-entries)が含まれます。
2030 2030
2031`permission_suggestions` 配列は、表示されるオプションの正確なリストではありません。各権限ダイアログが独自にオプションを構築するためです。ファイル編集のダイアログなど、一部のダイアログはこの配列をまったく読み取らず、リクエスト自体からオプションを導き出します。配列を読み取るダイアログでも、提案が配列に残っているオプションを表示しないことがあります。たとえば、[`allowManagedPermissionRulesOnly`](/docs/ja/settings-reference#allowmanagedpermissionrulesonly) がルールを保存するオプションを非表示にする場合です。また、[**Yes, and switch to auto mode**](/docs/ja/permission-modes#switch-permission-modes) のように、提案エントリのないオプションを提供することもあります。このオプションは、権限の更新を通じてではなく、権限モードを直接変更します。2031各権限ダイアログは独自のオプションを構築するため、`permission_suggestions` 配列は表示されるオプションの正確な一覧ではありません。ファイル編集用のダイアログなど、一部のダイアログはこの配列をまったく読み取らず、リクエスト自体からオプションを導き出します。配列を読み取るダイアログでも、提案が配列に残っているオプションを表示しないことがあります。たとえば、[`allowManagedPermissionRulesOnly`](/docs/ja/settings-reference#allowmanagedpermissionrulesonly) がルールを保存するオプションを非表示にする場合です。また、[**Yes, and switch to auto mode**](/docs/ja/permission-modes#switch-permission-modes) のように、提案エントリを持たないオプションを提示することもあります。このオプションは、権限の更新を介さずに権限モードを直接変更します。
2032 2032
2033PreToolUse フックは、権限が必要かどうかにかかわらず、すべてのツール呼び出しの前に実行されます。PermissionRequest フックは、Claude Code がユーザーに権限を求めようとするとき、またはプロンプトを表示できない呼び出しを本来なら自動的に拒否するときにのみ実行されます。どちらのイベントも [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) では発火しません。2033PreToolUse フックは、権限が必要かどうかにかかわらず、すべてのツール呼び出しの前に実行されます。PermissionRequest フックは、Claude Code が権限をユーザーに求めようとしているとき、またはプロンプトを表示できない呼び出しを本来なら自動拒否するときにのみ実行されます。どちらのイベントも [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) では発火しません。
2034 2034
2035```json theme={null}2035```json theme={null}
2036{2036{
2056```2056```
2057 2057
2058<h4 id="permissionrequest-decision-control">2058<h4 id="permissionrequest-decision-control">
2059 PermissionRequest の決定制御2059 PermissionRequest の判定制御
2060</h4>2060</h4>
2061 2061
2062`PermissionRequest` フックは権限リクエストを許可または拒否できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有のフィールドを持つ `decision` オブジェクトを返すことができます：2062`PermissionRequest` フックは、権限リクエストを許可または拒否できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは以下のイベント固有のフィールドを持つ `decision` オブジェクトを返すことができます。
2063 2063
2064| フィールド | 説明 |2064| フィールド | 説明 |
2065| :- | :- |2065| :- | :- |
2066| `behavior` | `"allow"` は権限を付与し、`"deny"` は拒否します。[拒否ルールと確認ルール](/docs/ja/permissions#manage-permissions)は引き続き評価されるため、`"allow"` を返すフックが一致する拒否ルールを上書きすることはありません |2066| `behavior` | `"allow"` は権限を付与し、`"deny"` は拒否します。[拒否ルールと確認ルール](/docs/ja/permissions#manage-permissions)は引き続き評価されるため、`"allow"` を返すフックが一致する拒否ルールを上書きすることはありません |
2067| `updatedInput` | `"allow"` の場合のみ：実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。変更された入力は、拒否ルールと確認ルールに対して再評価されます |2067| `updatedInput` | `"allow"` の場合のみ：実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。変更された入力は、拒否ルールと確認ルールに対して再評価されます |
2068| `updatedPermissions` | `"allow"` の場合のみ：適用する[権限更新エントリ](#permission-update-entries)の配列。許可ルールの追加やセッションの権限モードの変更などです |2068| `updatedPermissions` | `"allow"` の場合のみ：適用する[権限の更新エントリ](#permission-update-entries)の配列。許可ルールの追加やセッションの権限モードの変更などです |
2069| `message` | `"deny"` の場合のみ：権限が拒否された理由を Claude に伝えます |2069| `message` | `"deny"` の場合のみ：権限が拒否された理由を Claude に伝えます |
2070| `interrupt` | `"deny"` の場合のみ：`true` の場合、Claude を停止します |2070| `interrupt` | `"deny"` の場合のみ：`true` の場合、Claude を停止します |
2071 2071
2086```2086```
2087 2087
2088<h4 id="permission-update-entries">2088<h4 id="permission-update-entries">
2089 権限更新エントリ2089 権限の更新エントリ
2090</h4>2090</h4>
2091 2091
2092`updatedPermissions` 出力フィールドと [`permission_suggestions` 入力フィールド](#permissionrequest-input)は、どちらも同じエントリオブジェクトの配列を使用します。各エントリには、他のフィールドを決定する `type` と、変更の書き込み先を制御する `destination` があります。2092`updatedPermissions` 出力フィールドと [`permission_suggestions` 入力フィールド](#permissionrequest-input)は、どちらも同じエントリオブジェクトの配列を使用します。各エントリには、他のフィールドを決定する `type` と、変更の書き込み先を制御する `destination` があります。
2094| `type` | フィールド | 効果 |2094| `type` | フィールド | 効果 |
2095| :- | :- | :- |2095| :- | :- | :- |
2096| `addRules` | `rules`、`behavior`、`destination` | 権限ルールを追加します。`rules` は `{toolName, ruleContent?}` オブジェクトの配列です。ツール全体に一致させるには `ruleContent` を省略します。`behavior` は `"allow"`、`"deny"`、または `"ask"` です |2096| `addRules` | `rules`、`behavior`、`destination` | 権限ルールを追加します。`rules` は `{toolName, ruleContent?}` オブジェクトの配列です。ツール全体に一致させるには `ruleContent` を省略します。`behavior` は `"allow"`、`"deny"`、または `"ask"` です |
2097| `replaceRules` | `rules`、`behavior`、`destination` | `destination` にある指定された `behavior` のすべてのルールを、指定された `rules` で置き換えます |2097| `replaceRules` | `rules`、`behavior`、`destination` | `destination` にある指定の `behavior` のすべてのルールを、指定した `rules` で置き換えます |
2098| `removeRules` | `rules`、`behavior`、`destination` | 指定された `behavior` の一致するルールを削除します |2098| `removeRules` | `rules`、`behavior`、`destination` | 指定の `behavior` の一致するルールを削除します |
2099| `setMode` | `mode`、`destination` | 権限モードを変更します。有効なモードは `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan`、および `default` のエイリアスとしての `manual` です。`manual` エイリアスには Claude Code v2.1.200 以降が必要です |2099| `setMode` | `mode`、`destination` | 権限モードを変更します。有効なモードは `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan`、および `default` のエイリアスとしての `manual` です。`manual` エイリアスには Claude Code v2.1.200 以降が必要です |
2100| `addDirectories` | `directories`、`destination` | 作業ディレクトリを追加します。`directories` はパス文字列の配列です |2100| `addDirectories` | `directories`、`destination` | 作業ディレクトリを追加します。`directories` はパス文字列の配列です |
2101| `removeDirectories` | `directories`、`destination` | 作業ディレクトリを削除します |2101| `removeDirectories` | `directories`、`destination` | 作業ディレクトリを削除します |
2102 2102
2103<Note>2103<Note>
2104 `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)で開始された場合も、この更新は何も行いません。2104 `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)で開始された場合も、この更新は何も行いません。
2105 2105
2106 `destination` に関係なく、`bypassPermissions` が `defaultMode` として永続化されることはありません。2106 `bypassPermissions` は、`destination` に関係なく `defaultMode` として永続化されることはありません。
2107</Note>2107</Note>
2108 2108
2109各エントリの `destination` フィールドによって、変更をメモリ内にとどめるか設定ファイルに永続化するかが決まります。2109各エントリの `destination` フィールドは、変更をメモリ内にとどめるか、設定ファイルに永続化するかを決定します。
2110 2110
2111| `destination` | 書き込み先 |2111| `destination` | 書き込み先 |
2112| :- | :- |2112| :- | :- |
2115| `projectSettings` | `.claude/settings.json` |2115| `projectSettings` | `.claude/settings.json` |
2116| `userSettings` | `~/.claude/settings.json` |2116| `userSettings` | `~/.claude/settings.json` |
2117 2117
2118フックは、受け取った `permission_suggestions` のいずれかを、自身の `updatedPermissions` 出力としてそのまま返すことができます。2118フックは、受け取った `permission_suggestions` のいずれかを、そのまま自身の `updatedPermissions` 出力として返すことができます。
2119 2119
2120<h3 id="posttooluse">2120<h3 id="posttooluse">
2121 PostToolUse2121 PostToolUse
2127 2127
2128ツール名が適切なフィルターにならない場合は、より広くマッチさせます。2128ツール名が適切なフィルターにならない場合は、より広くマッチさせます。
2129 2129
2130* 任意のツールが正常に完了した後にフックを実行するには、`matcher` を省略するか `"*"` に設定します。その後、フック自身で何が変更されたかを調べることができます。たとえば `git status --porcelain` を実行すると、`git diff` では見落とされる未追跡ファイルも一覧表示されます。失敗したツール呼び出しについては、同じフックを [PostToolUseFailure](#posttoolusefailure) にも追加してください。2130* いずれかのツールが正常に完了した後にフックを実行するには、`matcher` を省略するか `"*"` に設定します。フック側で何が変更されたかを自ら調べることができます。たとえば `git status --porcelain` を実行すると、`git diff` では見落とされる未追跡ファイルも一覧表示されます。失敗したツール呼び出しについては、同じフックを [PostToolUseFailure](#posttoolusefailure) の下に追加します。
2131* 何が書き込んだかにかかわらず、特定のファイルがディスク上で変更されたときにフックを実行するには、[FileChanged](#filechanged) を使用します。`Bash` コマンドや Claude Code 外部のプロセスが同じファイルを書き換えた場合、Claude Code は `Edit|Write` にマッチする `PostToolUse` フックを実行しません。2131* 書き込んだのが何であれ、特定のファイルがディスク上で変更されたときにフックを実行するには、[FileChanged](#filechanged) を使用します。`Bash` コマンドや Claude Code 外部のプロセスが同じファイルを書き換えた場合、Claude Code は `Edit|Write` にマッチする `PostToolUse` フックを実行しません。
2132 2132
2133<h4 id="posttooluse-input">2133<h4 id="posttooluse-input">
2134 PostToolUse の入力2134 PostToolUse の入力
2135</h4>2135</h4>
2136 2136
2137`PostToolUse` フックは、ツールがすでに正常に実行された後に発火します。入力には、ツールに送信された引数である `tool_input` と、ツールが返した結果である `tool_response` の両方が含まれます。どちらも正確なスキーマはツールによって異なります。ファイル系ツールの `tool_input` のパスは、[PreToolUse](#pretooluse-input) と同じ形式で渡されます。つまり、常に絶対パスで、プラットフォームネイティブの区切り文字が使われるため、Windows ではバックスラッシュになります。MCP ツールの場合、入力には [`mcp_server`](#pretooluse-input) オブジェクトも含まれます。2137`PostToolUse` フックは、ツールがすでに正常に実行された後に発火します。入力には、ツールに送られた引数である `tool_input` と、ツールが返した結果である `tool_response` の両方が含まれます。両者の正確なスキーマはツールによって異なります。ファイルツールの `tool_input` のパスは [PreToolUse](#pretooluse-input) と同じ形式で渡されます。つまり、常に絶対パスで、プラットフォーム固有の区切り文字が使われるため、Windows ではバックスラッシュになります。MCP ツールの場合、入力には [`mcp_server`](#pretooluse-input) オブジェクトも含まれます。
2138 2138
2139```json theme={null}2139```json theme={null}
2140{2140{
2159 2159
2160| フィールド | 説明 |2160| フィールド | 説明 |
2161| :- | :- |2161| :- | :- |
2162| `duration_ms` | 省略可能。ツールの実行時間（ミリ秒）。権限プロンプトと PreToolUse フックに費やされた時間は含まれません |2162| `duration_ms` | 省略可能。ツールの実行時間（ミリ秒）。権限プロンプトと PreToolUse フックに費やされた時間は含みません |
2163 2163
2164<h4 id="posttooluse-decision-control">2164<h4 id="posttooluse-decision-control">
2165 PostToolUse の決定制御2165 PostToolUse の判定制御
2166</h4>2166</h4>
2167 2167
2168`PostToolUse` フックは、ツール実行後に Claude にフィードバックを提供できます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。2168`PostToolUse` フックは、ツール実行後に Claude へフィードバックを提供できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有フィールドを返すことができます。
2169 2169
2170| フィールド | 説明 |2170| フィールド | 説明 |
2171| :- | :- |2171| :- | :- |
2172| `decision` | `"block"` を指定すると、ツールの結果の隣に `reason` を追加します。Claude には元の出力も引き続き表示されます。出力を置き換えるには `updatedToolOutput` を使用します |2172| `decision` | `"block"` を指定すると、ツール結果の横に `reason` が追加されます。Claude には元の出力も引き続き表示されます。出力を置き換えるには `updatedToolOutput` を使用します |
2173| `reason` | `decision` が `"block"` のときに Claude に表示される説明 |2173| `reason` | `decision` が `"block"` のときに Claude に示される説明 |
2174| `additionalContext` | ツールの結果とともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |2174| `additionalContext` | ツール結果とともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
2175| `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 以降が必要です |2175| `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 以降が必要です |
2176| `updatedToolOutput` | Claude に送信される前に、ツールの出力を指定した値で置き換えます。値はツールの出力の形状と一致している必要があります |2176| `updatedToolOutput` | Claude に送られる前に、ツールの出力を指定した値で置き換えます。値はツールの出力の形式と一致している必要があります |
2177| `updatedMCPToolOutput` | [MCP ツール](#match-mcp-tools)の場合のみ出力を置き換えます。すべてのツールで機能する `updatedToolOutput` の使用を推奨します |2177| `updatedMCPToolOutput` | [MCP ツール](#match-mcp-tools)に限り出力を置き換えます。すべてのツールで機能する `updatedToolOutput` の使用を推奨します |
2178 2178
2179以下の例は、`Bash` 呼び出しの出力を置き換えます。置き換える値は `Bash` ツールの出力の形状と一致しています。2179次の例は、`Bash` 呼び出しの出力を置き換えます。置き換える値は `Bash` ツールの出力の形式に一致しています。
2180 2180
2181```json theme={null}2181```json theme={null}
2182{2182{
2194```2194```
2195 2195
2196<Warning>2196<Warning>
2197 `updatedToolOutput` が変更するのは Claude に見える内容だけです。フックが発火した時点でツールはすでに実行されているため、書き込まれたファイル、実行されたコマンド、送信されたネットワークリクエストはすでに反映されています。OpenTelemetry のツールスパンや分析イベントなどのテレメトリも、フックの実行前に元の出力を記録します。ツール呼び出しを実行前に阻止または変更するには、代わりに [PreToolUse](#pretooluse) フックを使用してください。2197 `updatedToolOutput` が変更するのは Claude に見える内容だけです。フックが発火する時点でツールはすでに実行されているため、書き込まれたファイル、実行されたコマンド、送信されたネットワークリクエストはすでに反映されています。OpenTelemetry のツールスパンや分析イベントなどのテレメトリも、フックが実行される前の元の出力を記録します。ツール呼び出しを実行前に阻止または変更するには、代わりに [PreToolUse](#pretooluse) フックを使用してください。
2198 2198
2199 置き換える値はツールの出力の形状と一致している必要があります。組み込みツールはプレーンな文字列ではなく構造化されたオブジェクトを返します。たとえば、`Bash` は `stdout`、`stderr`、`interrupted`、`isImage` フィールドを持つオブジェクトを返します。組み込みツールの場合、ツールの出力スキーマと一致しない値は無視され、元の出力が使用されます。MCP ツールの出力はスキーマ検証なしでそのまま渡されます。Claude が必要とするエラーの詳細を取り除くと、Claude が誤った前提のまま処理を進める可能性があります。2199 置き換える値はツールの出力の形式と一致している必要があります。組み込みツールはプレーンな文字列ではなく構造化されたオブジェクトを返します。たとえば `Bash` は、`stdout`、`stderr`、`interrupted`、`isImage` フィールドを持つオブジェクトを返します。組み込みツールの場合、ツールの出力スキーマに一致しない値は無視され、元の出力が使用されます。MCP ツールの出力はスキーマ検証なしでそのまま渡されます。Claude が必要とするエラーの詳細を取り除くと、Claude が誤った前提のまま作業を進める可能性があります。
2200</Warning>2200</Warning>
2201 2201
2202<h4 id="annotate-a-result-for-the-auto-mode-classifier">2202<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2203 auto モードの分類器向けに結果に注釈を付ける2203 auto モードの分類器向けに結果に注記を付ける
2204</h4>2204</h4>
2205 2205
2206`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 以降が必要です。2206`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 以降が必要です。
2207 2207
2208以下の例は、クエリの出力がどこから来たかを分類器に伝えます。2208次の例は、クエリの出力がどこから得られたかを分類器に伝えます。
2209 2209
2210```json theme={null}2210```json theme={null}
2211{2211{
2216}2216}
2217```2217```
2218 2218
2219分類器がメモをどの程度重視するかは、フックをどこで設定したかによって異なります。2219分類器が注記をどの程度重視するかは、フックをどこで設定したかによって異なります。
2220 2220
2221* **Claude Code で設定されたフック**: 設定ファイル、プラグイン、スキル、エージェントのフロントマターからのフックの場合、分類器はメモを未検証のアプリケーション提供コンテキストとして扱います。メモがユーザーの意図を確定させることはなく、ユーザーが何かを承認または要求したとメモが主張している場合、分類器はその主張を会話内のユーザー自身のメッセージと照合します2221* **Claude Code で設定されたフック**: 設定ファイル、プラグイン、スキル、エージェントのフロントマターから読み込まれたフックの場合、分類器は注記を未検証の、アプリケーションから提供されたコンテキストとして扱います。注記がユーザーの意図を確立することはなく、ユーザーが何かを承認または要求したと注記が主張する場合、分類器はその主張を会話内のユーザー自身のメッセージと照合します
2222* **インプロセスの Agent SDK コールバック**: Claude Code を組み込んだアプリケーションがフックを [TypeScript SDK コールバック](/docs/ja/agent-sdk/hooks)として登録し、ライブセッション中にメモを返す場合、分類器はメモで中継されたユーザーの発言をユーザーの意図として考慮することがあります。そのような発言は、ユーザーが送信したメッセージであれば分類器が受け入れる同意要件を満たすことができますが、ユーザー自身のメッセージでも解除できないブロックを解除することはありません。セッションが再開された後は、Claude Code は復元されたメモを未検証のコンテキストとして扱います。両方のグループのフックが同じ呼び出しに注釈を付けた場合、分類器は結合されたメモを未検証として扱います2222* **インプロセスの Agent SDK コールバック**: Claude Code を組み込んだアプリケーションがフックを [TypeScript SDK コールバック](/docs/ja/agent-sdk/hooks)として登録し、ライブセッション中に注記を返す場合、分類器は注記で伝えられたユーザーの発言をユーザーの意図として考慮することがあります。そのような発言は、ユーザーが送信したメッセージであれば分類器が受け入れる同意要件を満たすことはありますが、ユーザー自身のメッセージでも解除できないブロックを解除することはありません。セッションが再開された後は、Claude Code は復元された注記を未検証のコンテキストとして扱います。両方のグループのフックが同じ呼び出しに注記を付けた場合、分類器は結合された注記を未検証として扱います
2223 2223
2224Claude Code はメモを配信する際に以下の制限を適用します。2224Claude Code は注記を渡す際に次の制限を適用します。
2225 2225
2226* **長さ**: Claude Code は 1 回のツール呼び出しに対するメモを 2,000 文字に制限し、残りを切り捨てます。この上限は、その呼び出しに応答するすべてのフックで共有されます2226* **長さ**: Claude Code は 1 回のツール呼び出しに対する注記を 2,000 文字までに制限し、残りを切り捨てます。この上限は、その呼び出しに応答するすべてのフックで共有されます
2227* **同期応答のみ**: [バックグラウンドで実行される](#run-hooks-in-the-background)フックの応答内のこのフィールドは無視されます。その応答は Claude Code がツールの結果を記録した後に届くためです2227* **同期的な応答のみ**: [バックグラウンドで実行される](#run-hooks-in-the-background)フックの応答では、Claude Code はこのフィールドを無視します。その応答は Claude Code がツール結果を記録した後に届くためです
2228* **分類器が記録しない呼び出し**: 分類器のトランスクリプトには、ファイルの読み取りや検索などの読み取り専用の参照は含まれません。Claude Code はそれらの呼び出しに付けられたメモを破棄します2228* **分類器が記録しない呼び出し**: 分類器のトランスクリプトには、ファイルの読み取りや検索などの読み取り専用の参照は含まれません。Claude Code は、そのような呼び出しに付けられた注記を破棄します
2229* **書き換えとの相互作用**: `updatedToolOutput` で置き換える出力についてメモで説明する場合は、同じフックの応答で両方のフィールドを返してください。その書き換えが拒否された場合や、別のフックの書き換えで置き換えられた場合、Claude Code はメモを破棄します。書き換えなしで返したメモは、別のフックが出力を書き換えた場合でも Claude Code が配信します2229* **書き換えとの相互作用**: `updatedToolOutput` で置き換える出力について注記が説明している場合は、同じフックの応答で両方のフィールドを返してください。その書き換えが拒否された場合や、別のフックの書き換えで置き換えられた場合、Claude Code は注記を破棄します。書き換えなしで返した注記は、別のフックが出力を書き換えた場合でも Claude Code によって渡されます
2230 2230
2231<Warning>2231<Warning>
2232 分類器は `classifierContext` に入れた内容を、セッションをホストしているアプリケーションからの情報として読み取ります。そのため、信頼できないツールの出力やサードパーティのテキストをこのフィールドにコピーしないでください。メモは、出所に関する事実やそれについてのユーザーの発言など、この 1 回の呼び出しに関する短い主張にとどめてください。無関係なメッセージやイベントのストリームを配信するためにこのフィールドを使用しないでください。2232 分類器は `classifierContext` に入れた内容を、セッションをホストしているアプリケーションからの情報として読み取ります。そのため、信頼できないツール出力やサードパーティのテキストをコピーして入れないでください。注記は、その出所に関する事実やそれについてのユーザーの発言など、この 1 回の呼び出しについての短い主張にとどめてください。無関係なメッセージやイベントのストリームを渡すためにこのフィールドを使用しないでください。
2233</Warning>2233</Warning>
2234 2234
2235<h3 id="posttoolusefailure">2235<h3 id="posttoolusefailure">
2236 PostToolUseFailure2236 PostToolUseFailure
2237</h3>2237</h3>
2238 2238
2239実行を開始したツールが失敗したとき、つまりツールがエラーをスローしたとき、または MCP ツールがエラー結果を返したときに実行されます。失敗をログに記録したり、アラートを送信したり、Claude に修正のためのフィードバックを提供したりするために使用します。2239実行を開始したツールが失敗したとき、つまりツールがエラーをスローしたか、MCP ツールがエラー結果を返したときに実行されます。失敗のログ記録、アラートの送信、Claude への修正フィードバックの提供に使用します。
2240 2240
2241ツール名でマッチします。値は PreToolUse と同じです。2241ツール名でマッチします。値は PreToolUse と同じです。
2242 2242
2243<Note>2243<Note>
2244 このイベントは、実行前に拒否されたツール呼び出しでは発火しません。これには、不明なツール名、スキーマやツール固有の検証に失敗した入力、権限の拒否が含まれます。検証による拒否は `tool_use_error` 結果として返され、フックの実行前に発生するため、`PreToolUse` も `PostToolUseFailure` も発火しません。権限の拒否では `PreToolUse` は発火しますが、このイベントは発火しません。[PermissionDenied](#permissiondenied) を参照してください。2244 このイベントは、実行前に拒否されたツール呼び出しでは発火しません。該当するのは、不明なツール名、スキーマ検証やツール固有の検証に失敗した入力、権限の拒否です。検証による拒否は `tool_use_error` 結果として返され、フックが実行される前に発生するため、`PreToolUse` も `PostToolUseFailure` も発火しません。権限の拒否では `PreToolUse` は発火しますが、このイベントは発火しません。[PermissionDenied](#permissiondenied) を参照してください。
2245</Note>2245</Note>
2246 2246
2247<h4 id="posttoolusefailure-input">2247<h4 id="posttoolusefailure-input">
2248 PostToolUseFailure の入力2248 PostToolUseFailure の入力
2249</h4>2249</h4>
2250 2250
2251PostToolUseFailure フックは、PostToolUse と同じ `tool_name` および `tool_input` フィールドに加えて、エラー情報をトップレベルのフィールドとして受け取ります。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。たとえば、`npm test` コマンドが失敗した場合は次のように渡されます。2251PostToolUseFailure フックは、PostToolUse と同じ `tool_name` と `tool_input` フィールドに加えて、エラー情報をトップレベルのフィールドとして受け取ります。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。たとえば、失敗した `npm test` コマンドでは次のような入力が渡されます。
2252 2252
2253```json theme={null}2253```json theme={null}
2254{2254{
2272| フィールド | 説明 |2272| フィールド | 説明 |
2273| :- | :- |2273| :- | :- |
2274| `error` | 何が問題だったかを説明する文字列。形式は失敗したツールによって異なります |2274| `error` | 何が問題だったかを説明する文字列。形式は失敗したツールによって異なります |
2275| `is_interrupt` | 省略可能なブール値。ツールが報告したエラーとしてではなく、中断として Claude Code に失敗が伝わった場合に true になります。実行中のツールをキャンセルしてもこのフックは発火せず、代わりにツールの結果に中断メッセージが含まれます |2275| `is_interrupt` | 省略可能なブール値。ツールが報告したエラーとしてではなく、中断として Claude Code に失敗が伝わった場合に true になります。実行中のツールをキャンセルしてもこのフックは発火せず、代わりにツール結果に中断メッセージが含まれます |
2276| `duration_ms` | 省略可能。ツールの実行時間（ミリ秒）。権限プロンプトと PreToolUse フックに費やされた時間は含まれません |2276| `duration_ms` | 省略可能。ツールの実行時間（ミリ秒）。権限プロンプトと PreToolUse フックに費やされた時間は含みません |
2277 2277
2278`error` 文字列は通常、失敗したツールの結果として Claude が受け取るテキストと同じです。その形式はツールや失敗の種類によって異なります。フックの判定には `tool_name`、`is_interrupt`、および先頭行の `Exit code N` を使用し、文字列の残りの部分は安定した形式ではなく表示用テキストとして扱ってください。2278`error` 文字列は通常、失敗したツールの結果として Claude が受け取るテキストと同じです。形式はツールと失敗の種類によって異なります。フックの判定には `tool_name`、`is_interrupt`、および先頭行の `Exit code N` を使用し、文字列の残りの部分は安定した形式ではなく表示用テキストとして扱ってください。
2279 2279
2280* Bash と PowerShell では、実行されて終了したコマンドは、先頭行が `Exit code N` となり、その後にコマンドが出力した内容が stdout と stderr の混在した 1 つのブロックとして続きます2280* Bash と PowerShell の場合、実行されて終了したコマンドでは、先頭行が `Exit code N` となり、その後にコマンドが生成した出力が stdout と stderr の混在した 1 つのブロックとして続きます
2281* Claude Code がシェルプロセス自体を起動できなかった場合、ペイロードには終了コードの行がない、失敗メッセージのみが含まれることもあります2281* Claude Code がシェルプロセス自体を起動できなかった場合、ペイロードには終了コードの行がない失敗メッセージだけが含まれることもあります
2282* Claude Code は長い文字列の中間部分を `... [N characters truncated] ...` マーカーで切り詰めるほか、`Command timed out after 2m 0s` などの独自の行を挿入することがあります2282* Claude Code は長い文字列を `... [N characters truncated] ...` マーカーを挟んで中間部分を切り詰めることがあり、`Command timed out after 2m 0s` のような独自の行を挿入することもあります
2283 2283
2284<h4 id="posttoolusefailure-decision-control">2284<h4 id="posttoolusefailure-decision-control">
2285 PostToolUseFailure の決定制御2285 PostToolUseFailure の判定制御
2286</h4>2286</h4>
2287 2287
2288`PostToolUseFailure` フックは、ツールの失敗後に Claude にコンテキストを提供できます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。2288`PostToolUseFailure` フックは、ツールの失敗後に Claude へコンテキストを提供できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有フィールドを返すことができます。
2289 2289
2290| フィールド | 説明 |2290| フィールド | 説明 |
2291| :- | :- |2291| :- | :- |
2304 PostToolBatch2304 PostToolBatch
2305</h3>2305</h3>
2306 2306
2307バッチ内のすべてのツール呼び出しが解決された後、Claude Code がモデルに次のリクエストを送信する前に 1 回実行されます。`PostToolUse` はツールごとに 1 回発火するため、Claude が並列のツール呼び出しを行うと同時に発火します。`PostToolBatch` はバッチ全体に対して正確に 1 回だけ発火するため、単一のツールではなく実行されたツールの組み合わせに依存するコンテキストを注入するのに適しています。このイベントには matcher はありません。2307バッチ内のすべてのツール呼び出しが解決された後、Claude Code が次のリクエストをモデルに送信する前に 1 回実行されます。`PostToolUse` はツールごとに 1 回発火するため、Claude が並列でツールを呼び出すと同時に発火します。`PostToolBatch` はバッチ全体に対して正確に 1 回だけ発火するため、単一のツールではなく実行されたツールの組み合わせに依存するコンテキストを注入するのに適しています。このイベントには matcher はありません。
2308 2308
2309<h4 id="posttoolbatch-input">2309<h4 id="posttoolbatch-input">
2310 PostToolBatch の入力2310 PostToolBatch の入力
2311</h4>2311</h4>
2312 2312
2313[共通の入力フィールド](#common-input-fields)に加えて、PostToolBatch フックは、バッチ内のすべてのツール呼び出しを記述する配列である `tool_calls` を受け取ります。2313[共通入力フィールド](#common-input-fields)に加えて、PostToolBatch フックは、バッチ内のすべてのツール呼び出しを記述する配列 `tool_calls` を受け取ります。
2314 2314
2315```json theme={null}2315```json theme={null}
2316{2316{
2336}2336}
2337```2337```
2338 2338
2339`tool_response` には、モデルが対応する `tool_result` ブロックで受け取るのと同じ内容が含まれます。値は、ツールが出力したとおりのシリアライズされた文字列またはコンテンツブロックの配列です。`Read` の場合、これは生のファイル内容ではなく、行番号が先頭に付いたテキストを意味します。応答は大きくなる可能性があるため、必要なフィールドのみを解析してください。2339`tool_response` には、対応する `tool_result` ブロックでモデルが受け取るのと同じ内容が含まれます。値は、ツールが出力したとおりのシリアライズされた文字列またはコンテンツブロックの配列です。`Read` の場合、これは生のファイル内容ではなく、行番号が先頭に付いたテキストを意味します。応答は大きくなる場合があるため、必要なフィールドだけを解析してください。
2340 2340
2341<Note>2341<Note>
2342 `tool_response` の形状は `PostToolUse` のものとは異なります。`PostToolUse` はツールの構造化された `Output` オブジェクト（`Write` の場合は `{filePath: "...", type: "create"}` など）を渡しますが、`PostToolBatch` はモデルが参照するシリアライズされた `tool_result` の内容を渡します。2342 `tool_response` の形式は `PostToolUse` のものとは異なります。`PostToolUse` はツールの構造化された `Output` オブジェクト（`Write` の場合は `{filePath: "...", type: "create"}` など）を渡しますが、`PostToolBatch` はモデルに見えるシリアライズされた `tool_result` の内容を渡します。
2343</Note>2343</Note>
2344 2344
2345<h4 id="posttoolbatch-decision-control">2345<h4 id="posttoolbatch-decision-control">
2346 PostToolBatch の決定制御2346 PostToolBatch の判定制御
2347</h4>2347</h4>
2348 2348
2349`PostToolBatch` フックは、Claude にコンテキストを注入できます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。2349`PostToolBatch` フックは、Claude 向けのコンテキストを注入できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有フィールドを返すことができます。
2350 2350
2351| フィールド | 説明 |2351| フィールド | 説明 |
2352| :- | :- |2352| :- | :- |
2353| `additionalContext` | 次のモデル呼び出しの前に 1 回注入されるコンテキスト文字列。配信の詳細、含める内容、再開されたセッションが過去の値をどう扱うかについては、[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |2353| `additionalContext` | 次のモデル呼び出しの前に 1 回注入されるコンテキスト文字列。渡され方の詳細、入れるべき内容、再開されたセッションで過去の値がどう扱われるかについては、[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
2354 2354
2355```json theme={null}2355```json theme={null}
2356{2356{
2361}2361}
2362```2362```
2363 2363
2364`decision: "block"` または `continue: false` を返すと、次のモデル呼び出しの前にエージェント型ループが停止します。ブロックメッセージは、JSON の `reason` または `stopReason`、あるいは終了コード 2 の場合は stderr から取得されます。このメッセージはトランスクリプトに警告として表示され、会話内に残るため、会話が続行されると Claude にも表示されます。2364`decision: "block"` または `continue: false` を返すと、次のモデル呼び出しの前にエージェント型ループが停止します。ブロックメッセージは、JSON の `reason` または `stopReason`、あるいは終了コード 2 の場合は stderr から取得されます。このメッセージはトランスクリプトに警告として表示され、会話にも残るため、会話が続行されると Claude はそれを確認できます。
2365 2365
2366<h3 id="permissiondenied">2366<h3 id="permissiondenied">
2367 PermissionDenied2367 PermissionDenied
2368</h3>2368</h3>
2369 2369
2370[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` ルールがマッチした場合には実行されません。拒否をログに記録したり、設定を調整したり、ツール呼び出しを再試行してよいことをモデルに伝えたりするために使用します。2370[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` ルールがマッチした場合には実行されません。拒否のログ記録、設定の調整、またはツール呼び出しを再試行してよいことをモデルに伝えるために使用します。
2371 2371
2372ツール名でマッチします。値は PreToolUse と同じです。2372ツール名でマッチします。値は PreToolUse と同じです。
2373 2373
2375 PermissionDenied の入力2375 PermissionDenied の入力
2376</h4>2376</h4>
2377 2377
2378[共通の入力フィールド](#common-input-fields)に加えて、PermissionDenied フックは `tool_name`、`tool_input`、`tool_use_id`、`reason` を受け取ります。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。2378[共通入力フィールド](#common-input-fields)に加えて、PermissionDenied フックは `tool_name`、`tool_input`、`tool_use_id`、`reason` を受け取ります。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。
2379 2379
2380```json theme={null}2380```json theme={null}
2381{2381{
2396 2396
2397| フィールド | 説明 |2397| フィールド | 説明 |
2398| :- | :- |2398| :- | :- |
2399| `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` になります |2399| `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` になります |
2400 2400
2401<h4 id="permissiondenied-decision-control">2401<h4 id="permissiondenied-decision-control">
2402 PermissionDenied の決定制御2402 PermissionDenied の判定制御
2403</h4>2403</h4>
2404 2404
2405PermissionDenied フックは、拒否されたツール呼び出しを再試行してよいことをモデルに伝えることができます。`hookSpecificOutput.retry` を `true` に設定した JSON オブジェクトを返します。2405PermissionDenied フックは、拒否されたツール呼び出しを再試行してよいことをモデルに伝えることができます。`hookSpecificOutput.retry` を `true` に設定した JSON オブジェクトを返します。
2413}2413}
2414```2414```
2415 2415
2416`retry` が `true` の場合、Claude Code はツール呼び出しを再試行してよいことをモデルに伝えるメッセージを会話に追加します。Claude Code が拒否自体を取り消すことはありません。フックが JSON を返さない場合、または `retry: false` を返した場合は、拒否がそのまま維持され、モデルは元の拒否メッセージを受け取ります。2416`retry` が `true` の場合、Claude Code は、ツール呼び出しを再試行してよいことをモデルに伝えるメッセージを会話に追加します。Claude Code 自体が拒否を取り消すことはありません。フックが JSON を返さない場合、または `retry: false` を返した場合、拒否はそのまま維持され、モデルは元の拒否メッセージを受け取ります。
2417 2417
2418分類器が[アクションに対して判定を下さなかった](/docs/ja/errors#auto-mode-cannot-determine-the-safety-of-an-action)場合、つまり分類器の応答を解析できなかった場合や、auto モードとは別の安全性チェックが分類器自身のリクエストを拒否した場合、Claude Code は `retry: true` を無視します。そのような拒否については、後で再試行するか次に進むかを、Claude Code がすでに拒否メッセージでモデルに伝えています。2418分類器が[アクションについて判定を出さなかった](/docs/ja/errors#auto-mode-cannot-determine-the-safety-of-an-action)場合、つまり分類器の応答を解析できなかった場合や、auto モードとは別の安全性チェックが分類器自身のリクエストを拒否した場合、Claude Code は `retry: true` を無視します。そのような拒否については、後で再試行するか先に進むかを、Claude Code がすでに拒否メッセージでモデルに伝えています。
2419 2419
2420<h3 id="notification">2420<h3 id="notification">
2421 Notification2421 Notification
2422</h3>2422</h3>
2423 2423
2424Claude Code が通知を送信するときに実行されます。通知タイプでマッチします。すべての通知タイプでフックを実行するには、matcher を省略します。2424Claude Code が通知を送信するときに実行されます。通知の種類でマッチします。すべての通知の種類でフックを実行するには、matcher を省略します。
2425 2425
2426デスクトップ通知をオフにしていても、これらのフックイベントは受け取ります。`notifications_disabled` を含む `preferredNotifChannel` 設定が変更するのは通知方法のみであり、フックが実行されるかどうかには影響しません。2426デスクトップ通知をオフにしていても、これらのフックイベントは受け取ります。`preferredNotifChannel` 設定（`notifications_disabled` を含む）が変更するのはユーザーへの通知方法だけで、フックが実行されるかどうかは変わりません。
2427 2427
2428| Matcher | 発火するタイミング |2428| Matcher | 発火するタイミング |
2429| :- | :- |2429| :- | :- |
2430| `permission_prompt` | Claude がツールの使用、またはサンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)の承認を必要としており、プロンプトが約 6 秒間待機している |2430| `permission_prompt` | Claude がツールの使用またはサンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)について承認を必要としており、プロンプトが約 6 秒間待機している |
2431| `idle_prompt` | Claude が約 60 秒前に応答を終え、その後ユーザーが入力していない |2431| `idle_prompt` | Claude が約 60 秒前に応答を終え、それ以降ユーザーが入力していない |
2432| `auth_success` | 認証が完了した |2432| `auth_success` | 認証が完了した |
2433| `elicitation_dialog` | MCP サーバーが elicitation フォームを開き、ユーザーが約 6 秒間入力していない |2433| `elicitation_dialog` | MCP サーバーが elicitation フォームを開き、ユーザーが約 6 秒間入力していない |
2434| `elicitation_url_dialog` | MCP サーバーがブラウザの URL を開くよう求め、ユーザーが約 6 秒間入力していない |2434| `elicitation_url_dialog` | MCP サーバーがブラウザーの URL を開くようユーザーに求め、ユーザーが約 6 秒間入力していない |
2435| `elicitation_complete` | MCP サーバーが [URL モードの elicitation](#elicitation-input) の完了を報告した |2435| `elicitation_complete` | MCP サーバーが [URL モードの elicitation](#elicitation-input) の完了を報告した |
2436| `elicitation_response` | MCP elicitation の応答がサーバーに返送された |2436| `elicitation_response` | MCP の elicitation 応答がサーバーに返送された |
2437| `agent_needs_input` | [エージェントビュー](/docs/ja/agent-view)がターミナルで開いている間に、バックグラウンドセッションがユーザーの入力待ちを開始した。また、ターミナルセッションが[エージェントチームのチームメイトのターミナル設定に関する質問](/docs/ja/agent-teams#choose-a-display-mode)や、auto モードの[分類器リクエストの料金](/docs/ja/auto-mode-classifier-billing)に関するお知らせを表示し、ユーザーが約 6 秒間入力していない場合にも発火する |2437| `agent_needs_input` | ターミナルで[エージェントビュー](/docs/ja/agent-view)が開いている間に、バックグラウンドセッションがユーザーの入力を待ち始めた。また、ターミナルセッションが[エージェントチームのチームメイトのターミナル設定に関する質問](/docs/ja/agent-teams#choose-a-display-mode)や、[分類器リクエストの料金](/docs/ja/auto-mode-classifier-billing)に関する auto モードの通知を表示し、ユーザーが約 6 秒間入力していない場合にも発火します |
2438| `agent_completed` | バックグラウンドセッションが完了または失敗した。[エージェントビュー](/docs/ja/agent-view)がターミナルで開いている間のみ発火する |2438| `agent_completed` | バックグラウンドセッションが終了または失敗した。ターミナルで[エージェントビュー](/docs/ja/agent-view)が開いている間のみ発火します |
2439| `quota_auto_resume_fired` | claude.ai の使用制限によって一時停止されたタスクを Claude Code が続行した。リセット時、または待機中に使用クレジットの追加、プランのアップグレード、モデルの切り替えなど Claude Code 内で行った操作によって再び使用可能になった場合はそれより早く続行する。ただし [モデル設定の例外](/docs/ja/interactive-mode#wait-for-a-usage-limit-to-reset)がある |2439| `quota_auto_resume_fired` | claude.ai の使用制限によって一時停止したタスクを Claude Code が続行した。続行はリセット時点、または待機中に Claude Code で行った操作（使用クレジットの追加、プランのアップグレード、モデルの切り替えなど）によって使用量が再び利用可能になった場合はそれより早く行われます。ただし[モデル設定の例外](/docs/ja/interactive-mode#wait-for-a-usage-limit-to-reset)があります |
2440| `quota_auto_resume_stale` | コンピューターが約 30 分以上スリープしている間に claude.ai の使用制限がリセットされた。Claude Code は続行せず、ユーザーが `Enter` を押すのを待つ。スリープがより短い場合は続行し、代わりに `quota_auto_resume_fired` を発火する |2440| `quota_auto_resume_stale` | コンピューターが約 30 分を超えてスリープしている間に claude.ai の使用制限がリセットされた。Claude Code は続行せず、ユーザーが `Enter` を押すのを待ちます。スリープがそれより短い場合は続行し、代わりに `quota_auto_resume_fired` を発火します |
2441| `quota_auto_resume_disabled` | Claude Code がタスクを続行せずに claude.ai の使用制限の待機を終了した。原因は、Claude Code が自動的に開始した待機中に [`autoContinueAtUsageLimit`](/docs/ja/settings-reference#autocontinueatusagelimit) がオフになった、またはリセットが 24 時間以上先に移動した、続行したタスクが制限に達し続けた、あるいは続行がモデルに到達する前にブロックされた、のいずれか。`Esc` や `Ctrl+C` を押した場合、または **Don't continue automatically** を選択した場合は発火しない |2441| `quota_auto_resume_disabled` | Claude Code がタスクを続行せずに claude.ai の使用制限の待機を終了した。原因は、[`autoContinueAtUsageLimit`](/docs/ja/settings-reference#autocontinueatusagelimit) がオフにされた、Claude Code が自ら開始した待機中にリセットが 24 時間以上先に移動した、続行したタスクが繰り返し制限に達した、または続行がモデルに届く前にブロックされた、のいずれかです。ユーザーが `Esc` または `Ctrl+C` を押した場合や、**Don't continue automatically** を選択した場合は発火しません |
2442 2442
2443`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled` タイプには Claude Code v2.1.234 以降が必要です。2443`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled` の種類には Claude Code v2.1.234 以降が必要です。
2444 2444
2445ターミナルセッションで、サンドボックス化されたコマンドのネットワークリクエストに対する `permission_prompt` には Claude Code v2.1.246 以降が必要です。2445ターミナルセッションでは、サンドボックス化されたコマンドのネットワークリクエストに対する `permission_prompt` には Claude Code v2.1.246 以降が必要です。
2446 2446
2447チームメイトのターミナル設定に関する質問に対する `agent_needs_input` には Claude Code v2.1.248 以降が必要です。2447チームメイトのターミナル設定に関する質問に対する `agent_needs_input` には Claude Code v2.1.248 以降が必要です。
2448 2448
2449<Note>2449<Note>
2450 `permission_prompt`、`idle_prompt`、`elicitation_dialog`、`elicitation_url_dialog` タイプはデスクトップ通知とタイミングを共有しているため、ターミナルセッションでは、ユーザーがターミナルから離れていると判断される場合にのみ表示されます。2450 `permission_prompt`、`idle_prompt`、`elicitation_dialog`、`elicitation_url_dialog` の種類はデスクトップ通知とタイミングを共有しているため、ターミナルセッションでは、ユーザーがターミナルから離れているとみなされる場合にのみ発生します。
2451 2451
2452 * `permission_prompt` は、ユーザーが約 6 秒間入力しなかった時点で発火します。タイマーは権限プロンプトが表示されたときに開始し、キーを押すたびに延期されます。Claude がツールの使用権限を求めたときに即座にフックを実行するには、代わりに [PermissionRequest](#permissionrequest) を使用してください。2452 * `permission_prompt` は、ユーザーが約 6 秒間入力していない時点で発生します。タイマーは権限プロンプトが表示されたときに開始し、キー入力のたびに延期されます。Claude がツールの使用権限を求めたときにすぐにフックを実行するには、代わりに [PermissionRequest](#permissionrequest) を使用してください。
2453 * `idle_prompt` は、Claude が応答を終えてから約 60 秒後に、その間ユーザーが入力していない場合にのみ発火します。Claude Code が claude.ai の使用制限のリセットを待っている間は、`idle_prompt` は送信されません。待機が自動的に終了すると、代わりに `quota_auto_resume_*` タイプのいずれかが発火します。2453 * `idle_prompt` は、Claude が応答を終えてから約 60 秒後に発生します。ただし、それ以降ユーザーが入力しておらず、バックグラウンドの[サブエージェント](/docs/ja/sub-agents)などのバックグラウンドエージェントが実行中でない場合に限ります。claude.ai の使用制限のリセットを待っている間、Claude Code は `idle_prompt` を送信しません。待機が自然に終了すると、代わりに `quota_auto_resume_*` の種類のいずれかが発火します。
2454 * `elicitation_dialog`（elicitation フォームの場合）または `elicitation_url_dialog`（ブラウザの URL リクエストの場合）は、ユーザーが約 6 秒間入力しなかった時点で発火します。どちらも `permission_prompt` と同じ 6 秒の待機条件を共有しており、タイマーはダイアログが表示されたときに開始し、キーを押すたびに延期されます。2454 * `elicitation_dialog`（elicitation フォームの場合）または `elicitation_url_dialog`（ブラウザー URL のリクエストの場合）は、ユーザーが約 6 秒間入力していない時点で発生します。どちらも `permission_prompt` と同じ 6 秒の待機条件を共有しており、タイマーはダイアログが表示されたときに開始し、キー入力のたびに延期されます。
2455 2455
2456 別のダイアログが画面に表示されている間に届いた権限リクエストや elicitation にも、リクエストが届いた時点から計測される同じ 6 秒の待機条件が適用されます。そのため、リクエストが開いているダイアログの後ろでまだ待機している間に、その通知が届くことがあります。2456 別のダイアログが画面に表示されている間に届いた権限リクエストや elicitation にも、同じ 6 秒の待機条件が適用され、リクエストが届いた時点から計測されます。そのため、リクエストが開いているダイアログの後ろでまだ待機している間に通知が届くことがあります。
2457</Note>2457</Note>
2458 2458
2459Claude Code が権限リクエストを Agent SDK の [`canUseTool` コールバック](/docs/ja/agent-sdk/user-input)に送信するセッションでは、`permission_prompt` のタイミングが異なります。Claude Desktop や VS Code 拡張機能はこの方法で Claude Code をホストしています。2459Claude Code が権限リクエストを Agent SDK の [`canUseTool` コールバック](/docs/ja/agent-sdk/user-input)に送信するセッションでは、`permission_prompt` のタイミングが異なります。Claude Desktop と VS Code 拡張機能は、この方法で Claude Code をホストしています。
2460 2460
2461* `permission_prompt` は、Claude が権限を求めてから約 6 秒後に発火します。ユーザーが入力していても延期されません。2461* `permission_prompt` は、Claude が権限を求めてから約 6 秒後に発生します。入力中でも Claude Code は延期しません。
2462* ユーザーまたは [PermissionRequest](#permissionrequest) フックがそれより早く応答した場合、Claude Code は `permission_prompt` を実行しません。2462* それより早くユーザーまたは [PermissionRequest](#permissionrequest) フックが応答した場合、Claude Code は `permission_prompt` を実行しません。
2463* これらのセッションで `permission_prompt` をオフにするには、[`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/ja/env-vars) を `1` に設定します。2463* これらのセッションで `permission_prompt` をオフにするには、[`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/ja/env-vars) を `1` に設定します。
2464 2464
2465v2.1.233 より前は、これらのセッションで `permission_prompt` は発火しませんでした。2465v2.1.233 より前は、これらのセッションで `permission_prompt` は発火しませんでした。
2466 2466
2467通知タイプに応じて異なるハンドラーを実行するには、個別の matcher を使用します。以下の設定では、Claude が権限の承認を必要とするときに権限専用のアラートスクリプトを起動し、Claude がアイドル状態になったときには別の通知を起動します。2467通知の種類に応じて異なるハンドラーを実行するには、個別の matcher を使用します。次の設定では、Claude が権限の承認を必要とするときに権限専用のアラートスクリプトを、Claude がアイドル状態になったときに別の通知を実行します。
2468 2468
2469```json theme={null}2469```json theme={null}
2470{2470{
2497 Notification の入力2497 Notification の入力
2498</h4>2498</h4>
2499 2499
2500[共通の入力フィールド](#common-input-fields)に加えて、Notification フックは、通知テキストを含む `message`、省略可能な `title`、どのタイプが発火したかを示す `notification_type` を受け取ります。2500[共通入力フィールド](#common-input-fields)に加えて、Notification フックは、通知テキストを含む `message`、省略可能な `title`、どの種類が発火したかを示す `notification_type` を受け取ります。
2501 2501
2502```json theme={null}2502```json theme={null}
2503{2503{
2511}2511}
2512```2512```
2513 2513
2514Notification フックは通知をブロックしたり変更したりすることはできません。Claude Code はフックの `systemMessage` および `continue` フィールドを破棄しますが、[`terminalSequence`](#emit-terminal-notifications) は引き続き出力します。デスクトップ通知の例はこれを利用しています。Notification フックは、通知を外部サービスに転送するなどの副作用を目的としています。2514Notification フックは通知をブロックしたり変更したりすることはできません。Claude Code はその `systemMessage` と `continue` フィールドを破棄しますが、[`terminalSequence`](#emit-terminal-notifications) は引き続き出力します。デスクトップ通知の例はこれを利用しています。Notification フックは、通知を外部サービスに転送するといった副作用を目的としています。
2515 2515
2516<h3 id="subagentstart">2516<h3 id="subagentstart">
2517 SubagentStart2517 SubagentStart
2518</h3>2518</h3>
2519 2519
2520Claude が Agent ツールでサブエージェントを起動したとき、Claude が[サブエージェントを再開](/docs/ja/sub-agents#resume-subagents)したとき、およびインプロセスの[エージェントチーム](/docs/ja/agent-teams)のチームメイトが新しいメッセージを処理するたびに実行されます。エージェントタイプ名でフィルタリングするための matcher をサポートしています。組み込みエージェントの場合、これは `general-purpose`、`Explore`、`Plan` などのエージェント名です。[カスタムサブエージェント](/docs/ja/sub-agents)の場合は、ファイル名ではなく、エージェントのフロントマターの `name` フィールドです。2520Claude が Agent ツールでサブエージェントを生成したとき、Claude が[サブエージェントを再開](/docs/ja/sub-agents#resume-subagents)したとき、およびインプロセスの[エージェントチーム](/docs/ja/agent-teams)のチームメイトが新しいメッセージを処理するたびに実行されます。エージェントタイプ名でフィルタリングする matcher をサポートしています。組み込みエージェントの場合、これは `general-purpose`、`Explore`、`Plan` のようなエージェント名です。[カスタムサブエージェント](/docs/ja/sub-agents)の場合、これはファイル名ではなく、エージェントのフロントマターの `name` フィールドです。
2521 2521
2522[プラグイン](/docs/ja/plugins/overview)で提供されるサブエージェントの場合、エージェントタイプは単なるフロントマターの名前ではなく、`my-plugin:reviewer` のようなプラグインスコープの識別子になります。コロンが含まれるため、プラグインスコープの名前は正規表現として処理されます。完全一致させるには、`^my-plugin:reviewer$` のように matcher を `^` と `$` で固定してください。2522[プラグイン](/docs/ja/plugins/overview)で提供されるサブエージェントの場合、エージェントタイプは、フロントマターの名前そのものではなく、`my-plugin:reviewer` のようなプラグインスコープの識別子になります。コロンが含まれるとプラグインスコープの名前は正規表現として扱われるため、完全一致させるには matcher を `^` と `$` で固定します: `^my-plugin:reviewer$`。
2523 2523
2524<h4 id="subagentstart-input">2524<h4 id="subagentstart-input">
2525 SubagentStart の入力2525 SubagentStart の入力
2526</h4>2526</h4>
2527 2527
2528[共通の入力フィールド](#common-input-fields)に加えて、SubagentStart フックは、サブエージェントの一意の識別子を含む `agent_id` と、matcher のフィルタリング対象となるエージェント名を含む `agent_type` を受け取ります。2528[共通入力フィールド](#common-input-fields)に加えて、SubagentStart フックは、サブエージェントの一意の識別子を含む `agent_id` と、matcher がフィルタリングに使うエージェント名を含む `agent_type` を受け取ります。
2529 2529
2530```json theme={null}2530```json theme={null}
2531{2531{
2538}2538}
2539```2539```
2540 2540
2541SubagentStart フックはサブエージェントの作成をブロックできませんが、サブエージェントにコンテキストを注入することはできます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、以下を返すことができます。2541SubagentStart フックはサブエージェントの作成をブロックすることはできませんが、サブエージェントにコンテキストを注入することはできます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、次のフィールドを返すことができます。
2542 2542
2543| フィールド | 説明 |2543| フィールド | 説明 |
2544| :- | :- |2544| :- | :- |
2545| `additionalContext` | サブエージェントの会話の開始時、最初のプロンプトの前に、サブエージェントのコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |2545| `additionalContext` | 会話の開始時、最初のプロンプトの前にサブエージェントのコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
2546 2546
2547```json theme={null}2547```json theme={null}
2548{2548{
2553}2553}
2554```2554```
2555 2555
2556同じサブエージェントに対してフックが再度実行された場合、Claude Code は、サブエージェントのコンテキストに以前の実行時のコピーがまだ含まれていない場合にのみ、返されたコンテキストを注入します。起動時に注入されたコピーはそのまま残るため、サブエージェントの[プロンプトキャッシュ](/docs/ja/prompt-caching#subagents-and-the-cache)は維持されます。[自動圧縮](/docs/ja/sub-agents#auto-compaction)によってそのコピーが破棄された後は、Claude Code は次の実行時のコンテキストを再度注入します。2556同じサブエージェントに対してフックが再度実行された場合、Claude Code は、サブエージェントのコンテキストに以前の実行で注入したコピーがまだ残っていない場合にのみ、返されたコンテキストを注入します。起動時に注入されたコピーはそのまま残るため、サブエージェントの[プロンプトキャッシュ](/docs/ja/prompt-caching#subagents-and-the-cache)は損なわれません。[自動圧縮](/docs/ja/sub-agents#auto-compaction)によってそのコピーが破棄された後は、Claude Code は次の実行のコンテキストを再び注入します。
2557 2557
2558<h3 id="subagentstop">2558<h3 id="subagentstop">
2559 SubagentStop2559 SubagentStop
2565 SubagentStop の入力2565 SubagentStop の入力
2566</h4>2566</h4>
2567 2567
2568[共通の入力フィールド](#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` フィールドにはサブエージェントの最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにアクセスできます。2568[共通入力フィールド](#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` フィールドにはサブエージェントの最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにそれを参照できます。
2569 2569
2570すべての 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)で設定されたものなど）になり、セッションがエージェントなしで実行されている場合は空文字列になります。2570すべての 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)で設定されたものなど、セッション自体が実行されているエージェント名になり、セッションがエージェントなしで実行されている場合は空文字列になります。
2571 2571
2572エージェントタイプを指定した `matcher` は、空の `agent_type` にはマッチしません。matcher が省略されている、`""` または `"*"` である、あるいは空文字列にマッチする正規表現であるフックは、`agent_type` が空のイベントでも実行されます。2572エージェントタイプを指定する `matcher` は、空の `agent_type` にはマッチしません。matcher が省略されているか、`""` または `"*"` であるか、空文字列にマッチする正規表現であるフックは、空の `agent_type` のイベントでも実行されます。
2573 2573
2574Claude Code v2.1.271 以降では、[`SubagentHandback`](/docs/ja/tools-reference) ツールを使用して実行されるサブエージェントは、停止する前にそのツールを通じてレポートを配信します。その場合、`last_assistant_message` フィールドにはサブエージェントの締めくくりのテキスト（存在する場合）が含まれますが、これは配信されたレポートではありません。レポートはその呼び出しの `message` 入力であり、`SubagentHandback` にマッチする `PreToolUse` または `PostToolUse` フックは、これを `tool_input.message` として受け取ります。2574Claude Code v2.1.271 以降では、[`SubagentHandback`](/docs/ja/tools-reference) ツールを使って実行されるサブエージェントは、停止する前にそのツールを通じてレポートを渡します。その場合、`last_assistant_message` フィールドにはサブエージェントの締めくくりのテキスト（ある場合）が入り、渡されたレポートは含まれません。レポートはその呼び出しの `message` 入力であり、`SubagentHandback` にマッチする `PreToolUse` または `PostToolUse` フックは、それを `tool_input.message` として受け取ります。
2575 2575
2576SubagentStop フックは、[Stop の入力](#stop-input)で説明されている `background_tasks` および `session_crons` 配列も受け取ります。どちらの配列も、サブエージェントではなく親セッションを対象としています。2576SubagentStop フックは、[Stop の入力](#stop-input)で説明している `background_tasks` と `session_crons` の配列も受け取ります。どちらの配列も、サブエージェントではなく親セッションを対象としています。
2577 2577
2578```json theme={null}2578```json theme={null}
2579{2579{
2592}2592}
2593```2593```
2594 2594
2595SubagentStop フックは [Stop フック](#stop-decision-control)と同じ決定制御形式を使用します。これには、サブエージェントの実行を継続させるエラーではないフィードバックとして、`hookEventName` を `"SubagentStop"` に設定した `hookSpecificOutput.additionalContext` も含まれます。`reason` とともに `decision: "block"` を返すと、サブエージェントの実行が継続され、`reason` が次の指示としてサブエージェントに配信されます。終了コード 2 で終了してブロックするフックも、同様に stderr メッセージを配信します。サブエージェントが戻った後に親セッションにコンテキストを注入するには、代わりに `Agent` ツールに対する [`PostToolUse`](#posttooluse) フックを使用してください。2595SubagentStop フックは [Stop フック](#stop-decision-control)と同じ判定制御形式を使用します。これには、サブエージェントを実行し続けるエラー以外のフィードバックのために、`hookEventName` を `"SubagentStop"` に設定した `hookSpecificOutput.additionalContext` も含まれます。`reason` とともに `decision: "block"` を返すと、サブエージェントは実行を続け、`reason` が次の指示としてサブエージェントに渡されます。終了コード 2 でブロックするフックも、同じ方法で stderr のメッセージを渡します。サブエージェントが戻った後に親セッションにコンテキストを注入するには、代わりに `Agent` ツールに対する [`PostToolUse`](#posttooluse) フックを使用してください。
2596 2596
2597<h3 id="taskcreated">2597<h3 id="taskcreated">
2598 TaskCreated2598 TaskCreated
2599</h3>2599</h3>
2600 2600
2601`TaskCreate` ツールによってタスクが作成されるときに実行されます。命名規則を適用したり、タスクの説明を必須にしたり、特定のタスクの作成を阻止したりするために使用します。[Task ツールがないセッション](/docs/ja/tools-reference#task-tool-availability)では、このイベントは発火しません。2601`TaskCreate` ツールでタスクが作成されるときに実行されます。命名規則を強制したり、タスクの説明を必須にしたり、特定のタスクの作成を阻止したりするために使用します。[Task ツールがないセッション](/docs/ja/tools-reference#task-tool-availability)では、このイベントは発火しません。
2602 2602
2603TaskCreated フックは matcher をサポートしておらず、すべての発生時に発火します。2603TaskCreated フックは matcher をサポートしておらず、発生するたびに発火します。
2604 2604
2605<h4 id="taskcreated-input">2605<h4 id="taskcreated-input">
2606 TaskCreated の入力2606 TaskCreated の入力
2607</h4>2607</h4>
2608 2608
2609[共通の入力フィールド](#common-input-fields)に加えて、TaskCreated フックは `task_id`、`task_subject`、および省略可能な `task_description`、`teammate_name`、`team_name` を受け取ります。2609[共通入力フィールド](#common-input-fields)に加えて、TaskCreated フックは `task_id`、`task_subject`、および省略可能な `task_description`、`teammate_name`、`team_name` を受け取ります。
2610 2610
2611```json theme={null}2611```json theme={null}
2612{2612{
2628| `task_subject` | タスクのタイトル |2628| `task_subject` | タスクのタイトル |
2629| `task_description` | タスクの詳細な説明。存在しない場合があります |2629| `task_description` | タスクの詳細な説明。存在しない場合があります |
2630| `teammate_name` | タスクを作成するチームメイトの名前。存在しない場合があります |2630| `teammate_name` | タスクを作成するチームメイトの名前。存在しない場合があります |
2631| `team_name` | 非推奨。セッションから派生したチーム名。将来のリリースで削除されます |2631| `team_name` | 非推奨。セッションから導出されたチーム名。今後のリリースで削除されます |
2632 2632
2633<h4 id="taskcreated-decision-control">2633<h4 id="taskcreated-decision-control">
2634 TaskCreated の決定制御2634 TaskCreated の判定制御
2635</h4>2635</h4>
2636 2636
2637TaskCreated フックは、2 つの方法で作成をブロックできます。いずれの場合も、Claude Code はタスクを削除し、メッセージをツールのエラーとして Claude に返します。このイベントからの `continue: false` は Claude Code によって無視され、Claude は作業を続けます。2637TaskCreated フックは、2 つの方法で作成をブロックできます。いずれの場合も、Claude Code はタスクを削除し、メッセージをツールのエラーとして Claude に返します。このイベントからの `continue: false` は Claude Code によって無視され、Claude は作業を続けます。
2639* **終了コード 2**: Claude Code は stderr のテキストをメッセージとして返します。2639* **終了コード 2**: Claude Code は stderr のテキストをメッセージとして返します。
2640* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code は `reason` をメッセージとして返します。2640* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code は `reason` をメッセージとして返します。
2641 2641
2642以下の例は、件名が必要な形式に従っていないタスクをブロックします。2642次の例は、件名が必要な形式に従っていないタスクをブロックします。
2643 2643
2644```bash theme={null}2644```bash theme={null}
2645#!/bin/bash2645#!/bin/bash
2658 TaskCompleted2658 TaskCompleted
2659</h3>2659</h3>
2660 2660
2661タスクが完了としてマークされるときに実行されます。これは 2 つの状況で発火します。任意のエージェントが TaskUpdate ツールを通じてタスクを明示的に完了としてマークしたとき、または[エージェントチーム](/docs/ja/agent-teams)のチームメイトが進行中のタスクを抱えたままターンを終了したときです。タスクをクローズする前に、テストやリントチェックの合格などの完了基準を適用するために使用します。2661タスクが完了としてマークされるときに実行されます。これは 2 つの状況で発火します。いずれかのエージェントが TaskUpdate ツールを通じてタスクを明示的に完了としてマークした場合と、[エージェントチーム](/docs/ja/agent-teams)のチームメイトが進行中のタスクを抱えたままターンを終えた場合です。タスクを閉じる前に、テストや lint チェックの合格などの完了基準を強制するために使用します。
2662 2662
2663TaskCompleted フックは matcher をサポートしておらず、すべての発生時に発火します。2663TaskCompleted フックは matcher をサポートしておらず、発生するたびに発火します。
2664 2664
2665<h4 id="taskcompleted-input">2665<h4 id="taskcompleted-input">
2666 TaskCompleted の入力2666 TaskCompleted の入力
2667</h4>2667</h4>
2668 2668
2669[共通の入力フィールド](#common-input-fields)に加えて、TaskCompleted フックは `task_id`、`task_subject`、および省略可能な `task_description`、`teammate_name`、`team_name` を受け取ります。2669[共通入力フィールド](#common-input-fields)に加えて、TaskCompleted フックは `task_id`、`task_subject`、および省略可能な `task_description`、`teammate_name`、`team_name` を受け取ります。
2670 2670
2671```json theme={null}2671```json theme={null}
2672{2672{
2685 2685
2686| フィールド | 説明 |2686| フィールド | 説明 |
2687| :- | :- |2687| :- | :- |
2688| `task_id` | 完了されるタスクの識別子 |2688| `task_id` | 完了するタスクの識別子 |
2689| `task_subject` | タスクのタイトル |2689| `task_subject` | タスクのタイトル |
2690| `task_description` | タスクの詳細な説明。存在しない場合があります |2690| `task_description` | タスクの詳細な説明。存在しない場合があります |
2691| `teammate_name` | タスクを完了するチームメイトの名前。存在しない場合があります |2691| `teammate_name` | タスクを完了するチームメイトの名前。存在しない場合があります |
2692| `team_name` | 非推奨。セッションから派生したチーム名。将来のリリースで削除されます |2692| `team_name` | 非推奨。セッションから導出されたチーム名。今後のリリースで削除されます |
2693 2693
2694<h4 id="taskcompleted-decision-control">2694<h4 id="taskcompleted-decision-control">
2695 TaskCompleted の決定制御2695 TaskCompleted の判定制御
2696</h4>2696</h4>
2697 2697
2698TaskCompleted フックは、タスクの完了を制御する 2 つの方法をサポートしています。2698TaskCompleted フックは、タスクの完了を制御する 2 つの方法をサポートしています。
2699 2699
2700* **終了コード 2**: タスクは完了としてマークされず、stderr メッセージがフィードバックとしてモデルに返されます。2700* **終了コード 2**: タスクは完了としてマークされず、stderr のメッセージがフィードバックとしてモデルに返されます。
2701* **JSON `{"continue": false, "stopReason": "..."}`**: チームメイトがターンを終了したことでイベントが発生した場合、`Stop` フックの動作と同様に、チームメイトを完全に停止します。`stopReason` はユーザーに表示されます。`TaskUpdate` ツールによってイベントが発生した場合、Claude Code は `continue: false` を無視しますが、終了コード 2 は引き続き完了をブロックします。2701* **JSON `{"continue": false, "stopReason": "..."}`**: チームメイトがターンを終えたことでイベントがトリガーされた場合、`Stop` フックの動作と同様にチームメイトを完全に停止します。`stopReason` はユーザーに表示されます。`TaskUpdate` ツールによってイベントがトリガーされた場合、Claude Code は `continue: false` を無視します。その場合でも終了コード 2 は完了をブロックします。
2702 2702
2703以下の例は、テストを実行し、失敗した場合はタスクの完了をブロックします。2703次の例はテストを実行し、失敗した場合はタスクの完了をブロックします。
2704 2704
2705```bash theme={null}2705```bash theme={null}
2706#!/bin/bash2706#!/bin/bash
2720 Stop2720 Stop
2721</h3>2721</h3>
2722 2722
2723メインの Claude Code エージェントが応答を終えたときに実行されます。ユーザーの中断によって停止した場合は実行されません。API エラーの場合は、代わりに [StopFailure](#stopfailure) が発火します。2723メインの Claude Code エージェントが応答を終えたときに実行されます。ユーザーによる中断で停止した場合は実行されません。API エラーの場合は、代わりに [StopFailure](#stopfailure) が発火します。
2724 2724
2725<Tip>2725<Tip>
2726 [`/goal`](/docs/ja/goal) コマンドは、セッションスコープのプロンプトベースの Stop フックの組み込みショートカットです。フックの設定を書かずに、ある条件に向けて Claude に作業を続けさせたい場合に使用します。2726 [`/goal`](/docs/ja/goal) コマンドは、セッションスコープのプロンプトベースの Stop フックの組み込みショートカットです。フック設定を書かずに、ある条件に向けて Claude に作業を続けさせたい場合に使用します。
2727</Tip>2727</Tip>
2728 2728
2729<h4 id="stop-input">2729<h4 id="stop-input">
2730 Stop の入力2730 Stop の入力
2731</h4>2731</h4>
2732 2732
2733[共通の入力フィールド](#common-input-fields)に加えて、Stop フックは `stop_hook_active`、`last_assistant_message`、`background_tasks`、`session_crons` を受け取ります。`stop_hook_active` フィールドは、Claude Code が Stop フックの結果としてすでに続行している場合に `true` になります。決して解消されない条件でブロックし続けないよう、この値を確認するか、トランスクリプトを処理してください。Claude Code は連続継続を 8 回までとする上限を適用します。Stop フックがターンを 8 回連続で継続させた後、Claude Code は次のブロックを上書きしてターンを終了します。上限を引き上げるには、[`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/ja/env-vars) を設定します。2733[共通入力フィールド](#common-input-fields)に加えて、Stop フックは `stop_hook_active`、`last_assistant_message`、`background_tasks`、`session_crons` を受け取ります。`stop_hook_active` フィールドは、Claude Code が Stop フックの結果としてすでに続行している場合に `true` になります。解決しない条件でブロックし続けることがないよう、この値を確認するか、トランスクリプトを処理してください。Claude Code は連続 8 回の続行上限を適用します。Stop フックがターンを 8 回連続で続行させると、Claude Code は次のブロックを上書きしてターンを終了します。上限を引き上げるには、[`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/ja/env-vars) を設定します。
2734 2734
2735`last_assistant_message` フィールドには Claude の最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにアクセスできます。読み上げや通知のフックなど、完了したばかりのターンに基づいて動作するフックでは、`transcript_path` を読み取るのではなくこのフィールドを使用してください。すべてのバージョンで、Stop の時点でトランスクリプトファイルに最終メッセージが含まれているとは限らないためです。2735`last_assistant_message` フィールドには Claude の最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにそれを参照できます。読み上げや通知のフックなど、完了したばかりのターンに対して動作するフックでは、`transcript_path` を読み取るのではなくこのフィールドを使用してください。すべてのバージョンで、Stop の時点でトランスクリプトファイルに最終メッセージが含まれているとは限りません。
2736 2736
2737`background_tasks` および `session_crons` 配列により、フックは「セッションが完了した」状態と「セッションがバックグラウンド作業による再開を待って一時停止している」状態を区別できます。どちらの配列も、タスクレジストリにアクセスできる場合に存在し、実行中またはスケジュール済みのものがない場合は空になります。2737`background_tasks` と `session_crons` の配列により、フックは「セッションが完了した」状態と「セッションが一時停止し、バックグラウンドの作業によって再び起こされるのを待っている」状態を区別できます。どちらの配列も、タスクレジストリにアクセスできる場合に存在し、進行中またはスケジュール済みのものがない場合は空になります。
2738 2738
2739`background_tasks` の各エントリは実行中のタスク 1 つを表し、以下のフィールドを使用します。2739`background_tasks` の各エントリは進行中のタスク 1 つを表し、次のフィールドを使用します。
2740 2740
2741| フィールド | 説明 |2741| フィールド | 説明 |
2742| :- | :- |2742| :- | :- |
2743| `id` | タスクの識別子 |2743| `id` | タスクの識別子 |
2744| `type` | `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session`、`MCP task` などのわかりやすいタスクタイプのラベル。各ラベルは、どの Claude Code 機能がタスクを作成したかを示します。認識されないタイプの場合は、生の識別子にフォールバックします |2744| `type` | `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session`、`MCP task` など、わかりやすいタスクタイプのラベル。各ラベルは、タスクを作成した Claude Code の機能を示します。認識されないタイプの場合は、生の判別値が使われます |
2745| `status` | 現在のタスクのステータス |2745| `status` | 現在のタスクの状態 |
2746| `description` | 自由形式の説明。1000 文字が上限で、切り詰められた場合は文字列内に `… [+N chars]` マーカーが付きます |2746| `description` | 自由形式の説明。上限は 1000 文字で、切り詰められた場合は文字列内に `… [+N chars]` マーカーが付きます |
2747| `command` | シェルのコマンドライン。1000 文字が上限です。`shell` タスクの場合のみ存在します |2747| `command` | シェルのコマンドライン。上限は 1000 文字です。`shell` タスクにのみ存在します |
2748| `agent_type` | サブエージェントのタイプ名。`subagent` タスクの場合のみ存在します |2748| `agent_type` | サブエージェントのタイプ名。`subagent` タスクにのみ存在します |
2749| `server` | MCP サーバー名。`monitor` および `MCP task` タスクの場合のみ存在します |2749| `server` | MCP サーバー名。`monitor` と `MCP task` タスクにのみ存在します |
2750| `tool` | MCP ツール名。`monitor` および `MCP task` タスクの場合のみ存在します |2750| `tool` | MCP ツール名。`monitor` と `MCP task` タスクにのみ存在します |
2751| `name` | ワークフロー名。`workflow` タスクの場合のみ存在します |2751| `name` | ワークフロー名。`workflow` タスクにのみ存在します |
2752 2752
2753`session_crons` の各エントリは、`CronCreate`、`ScheduleWakeup`、`/loop` から取得された、セッションスコープのスケジュールされたウェイクアップ 1 つを表します。2753`session_crons` の各エントリは、`CronCreate`、`ScheduleWakeup`、`/loop` から作成された、セッションスコープのスケジュール済みウェイクアップ 1 つを表します。
2754 2754
2755| フィールド | 説明 |2755| フィールド | 説明 |
2756| :- | :- |2756| :- | :- |
2757| `id` | cron タスクの識別子 |2757| `id` | cron タスクの識別子 |
2758| `schedule` | cron 式。例: `0 9 * * 1-5` |2758| `schedule` | cron 式。例: `0 9 * * 1-5` |
2759| `recurring` | スケジュールが単一の発火時刻を表す 1 回限りのウェイクアップの場合は `false`、マッチするたびに再発火するタスクの場合は `true` |2759| `recurring` | スケジュールが単一の発火時刻を表す 1 回限りのウェイクアップの場合は `false`、マッチするたびに再発火するタスクの場合は `true` |
2760| `prompt` | cron の発火時に送信されるプロンプト。1000 文字が上限で、同じ `… [+N chars]` マーカーが付きます |2760| `prompt` | cron の発火時に送信されるプロンプト。上限は 1000 文字で、同じ `… [+N chars]` マーカーが付きます |
2761 2761
2762以下の例は、実行中のシェルタスク 1 つと繰り返し実行される cron 1 つを含む Stop の入力を示しています。2762次の例は、進行中の shell タスク 1 つと繰り返しの cron 1 つを含む Stop の入力を示しています。
2763 2763
2764```json theme={null}2764```json theme={null}
2765{2765{
2791```2791```
2792 2792
2793<h4 id="stop-decision-control">2793<h4 id="stop-decision-control">
2794 Stop の決定制御2794 Stop の判定制御
2795</h4>2795</h4>
2796 2796
2797`Stop` および `SubagentStop` フックは、Claude が続行するかどうかを制御できます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。2797`Stop` と `SubagentStop` フックは、Claude が続行するかどうかを制御できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有フィールドを返すことができます。
2798 2798
2799| フィールド | 説明 |2799| フィールド | 説明 |
2800| :- | :- |2800| :- | :- |
2801| `decision` | `"block"` を指定すると Claude の停止を阻止します。Claude の停止を許可するには省略します |2801| `decision` | `"block"` を指定すると Claude の停止を阻止します。Claude の停止を許可するには省略します |
2802| `reason` | `decision` が `"block"` の場合は必須です。Claude に続行すべき理由を伝えます |2802| `reason` | `decision` が `"block"` の場合は必須です。Claude に続行すべき理由を伝えます |
2803| `hookSpecificOutput.additionalContext` | Claude へのエラーではないフィードバック。Claude がそれに対応できるよう会話は続行されますが、`decision: "block"` とは異なり、トランスクリプトにはフックエラーではなくフックのフィードバックとして表示されます |2803| `hookSpecificOutput.additionalContext` | Claude へのエラー以外のフィードバック。Claude がそれに基づいて行動できるよう会話は続行しますが、`decision: "block"` とは異なり、トランスクリプトにはフックエラーではなくフックのフィードバックとして表示されます |
2804 2804
2805終了コード 2 で終了してブロックするフックは、`reason` と同じように処理されます。Claude は、続行すべき理由の説明として stderr メッセージを受け取ります。2805終了コード 2 でブロックするフックは、`reason` と同じように扱われます。Claude は続行すべき理由の説明として stderr のメッセージを受け取ります。
2806 2806
2807```json theme={null}2807```json theme={null}
2808{2808{
2811}2811}
2812```2812```
2813 2813
2814「完了前にテストスイートを実行する」など、フックが設計どおりに動作して Claude にガイダンスを与えている場合は、`additionalContext` を使用してください。これは `decision: "block"` と同じループ保護（`stop_hook_active` 入力と、連続継続 8 回の上限）を通じて会話を継続させますが、トランスクリプトには `Stop hook feedback` というラベルが付き、フックエラーの通知は表示されません。2814フックが設計どおりに動作しており、「終了する前にテストスイートを実行してください」のようなガイダンスを Claude に与えている場合は、`additionalContext` を使用します。これは `decision: "block"` と同じループ保護、つまり `stop_hook_active` 入力と連続 8 回の続行上限を通じて会話を続行させますが、トランスクリプトでは `Stop hook feedback` というラベルが付き、フックエラーの通知は表示されません。
2815 2815
2816```json theme={null}2816```json theme={null}
2817{2817{
2826 StopFailure2826 StopFailure
2827</h3>2827</h3>
2828 2828
2829API エラーによってターンが終了したときに、[Stop](#stop) の代わりに実行されます。Claude Code は、[`terminalSequence`](#emit-terminal-notifications) を除き、フックの出力と終了コードを無視します。レート制限、認証の問題、その他の API エラーによって Claude が応答を完了できない場合に、失敗をログに記録したり、アラートを送信したり、復旧アクションを実行したりするために使用します。2829API エラーによってターンが終了した場合に、[Stop](#stop) の代わりに実行されます。Claude Code は、[`terminalSequence`](#emit-terminal-notifications) を除き、フックの出力と終了コードを無視します。レート制限、認証の問題、その他の API エラーのために Claude が応答を完了できない場合に、失敗のログ記録、アラートの送信、または回復アクションの実行に使用します。
2830 2830
2831<h4 id="stopfailure-input">2831<h4 id="stopfailure-input">
2832 StopFailure の入力2832 StopFailure の入力
2833</h4>2833</h4>
2834 2834
2835[共通の入力フィールド](#common-input-fields)に加えて、StopFailure フックは `error`、省略可能な `error_details`、省略可能な `last_assistant_message` を受け取ります。`error` フィールドはエラーの種類を示し、matcher のフィルタリングに使用されます。2835[共通入力フィールド](#common-input-fields)に加えて、StopFailure フックは `error`、省略可能な `error_details`、省略可能な `last_assistant_message` を受け取ります。`error` フィールドはエラーの種類を示し、matcher のフィルタリングに使用されます。
2836 2836
2837| フィールド | 説明 |2837| フィールド | 説明 |
2838| :- | :- |2838| :- | :- |
2839| `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` |2839| `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` |
2840| `error_details` | エラーに関する追加の詳細（利用可能な場合） |2840| `error_details` | エラーに関する追加の詳細（利用可能な場合） |
2841| `last_assistant_message` | 会話に表示されたレンダリング済みのエラーテキスト。このフィールドに Claude の会話出力が含まれる `Stop` や `SubagentStop` とは異なり、`StopFailure` では `"API Error: Rate limit reached"` のような API エラー文字列そのものが含まれます |2841| `last_assistant_message` | 会話に表示されるレンダリング済みのエラーテキスト。このフィールドに Claude の会話出力が入る `Stop` や `SubagentStop` とは異なり、`StopFailure` では `"API Error: Rate limit reached"` のような API エラー文字列そのものが入ります |
2842 2842
2843```json theme={null}2843```json theme={null}
2844{2844{
2852}2852}
2853```2853```
2854 2854
2855StopFailure フックには決定制御がありません。通知とログ記録の目的でのみ実行されます。2855StopFailure フックには判定制御がありません。通知とログ記録の目的でのみ実行されます。
2856 2856
2857<h3 id="teammateidle">2857<h3 id="teammateidle">
2858 TeammateIdle2858 TeammateIdle
2859</h3>2859</h3>
2860 2860
2861[エージェントチーム](/docs/ja/agent-teams)のチームメイトがターンを終えてアイドル状態になろうとしているときに実行されます。リントチェックの合格を必須にしたり、出力ファイルの存在を確認したりするなど、チームメイトが作業を停止する前に品質ゲートを適用するために使用します。2861[エージェントチーム](/docs/ja/agent-teams)のチームメイトがターンを終えてアイドル状態になろうとしているときに実行されます。lint チェックの合格を必須にしたり、出力ファイルの存在を確認したりするなど、チームメイトが作業を停止する前に品質ゲートを強制するために使用します。
2862 2862
2863TeammateIdle フックは matcher をサポートしておらず、すべての発生時に発火します。2863TeammateIdle フックは matcher をサポートしておらず、発生するたびに発火します。
2864 2864
2865<h4 id="teammateidle-input">2865<h4 id="teammateidle-input">
2866 TeammateIdle の入力2866 TeammateIdle の入力
2867</h4>2867</h4>
2868 2868
2869[共通の入力フィールド](#common-input-fields)に加えて、TeammateIdle フックは `teammate_name` と `team_name` を受け取ります。2869[共通入力フィールド](#common-input-fields)に加えて、TeammateIdle フックは `teammate_name` と `team_name` を受け取ります。
2870 2870
2871```json theme={null}2871```json theme={null}
2872{2872{
2883| フィールド | 説明 |2883| フィールド | 説明 |
2884| :- | :- |2884| :- | :- |
2885| `teammate_name` | アイドル状態になろうとしているチームメイトの名前 |2885| `teammate_name` | アイドル状態になろうとしているチームメイトの名前 |
2886| `team_name` | 非推奨。セッションから派生したチーム名。将来のリリースで削除されます |2886| `team_name` | 非推奨。セッションから導出されたチーム名。今後のリリースで削除されます |
2887 2887
2888<h4 id="teammateidle-decision-control">2888<h4 id="teammateidle-decision-control">
2889 TeammateIdle の決定制御2889 TeammateIdle の判定制御
2890</h4>2890</h4>
2891 2891
2892TeammateIdle フックは、チームメイトの動作を制御する 2 つの方法をサポートしています。2892TeammateIdle フックは、チームメイトの動作を制御する 2 つの方法をサポートしています。
2893 2893
2894* **終了コード 2**: チームメイトは stderr メッセージをフィードバックとして受け取り、アイドル状態にならずに作業を続けます。2894* **終了コード 2**: チームメイトは stderr のメッセージをフィードバックとして受け取り、アイドル状態にならずに作業を続けます。
2895* **JSON `{"continue": false, "stopReason": "..."}`**: `Stop` フックの動作と同様に、チームメイトを完全に停止します。`stopReason` はユーザーに表示されます。2895* **JSON `{"continue": false, "stopReason": "..."}`**: `Stop` フックの動作と同様に、チームメイトを完全に停止します。`stopReason` はユーザーに表示されます。
2896 2896
2897以下の例は、チームメイトがアイドル状態になるのを許可する前に、ビルドアーティファクトが存在することを確認します。2897次の例は、チームメイトがアイドル状態になるのを許可する前に、ビルドアーティファクトが存在することを確認します。
2898 2898
2899```bash theme={null}2899```bash theme={null}
2900#!/bin/bash2900#!/bin/bash
2911 ConfigChange2911 ConfigChange
2912</h3>2912</h3>
2913 2913
2914セッション中に設定ファイルが変更されたときに実行されます。設定の変更を監査したり、セキュリティポリシーを適用したり、設定ファイルへの不正な変更をブロックしたりするために使用します。2914セッション中に設定ファイルが変更されたときに実行されます。設定変更の監査、セキュリティポリシーの強制、または設定ファイルへの不正な変更のブロックに使用します。
2915 2915
2916Claude Code は、設定ファイル、管理ポリシーファイル、またはスキルファイルが変更されたときに ConfigChange フックを実行します。管理ポリシーの場合は、`managed-settings.json` または `managed-settings.d/` 内のファイルが変更された場合にのみ実行します。[サーバー管理設定](/docs/ja/server-managed-settings)、および macOS の管理された環境設定や Windows のレジストリポリシーへの変更は、フックを実行せずに適用します。[`wslInheritsWindowsSettings`](/docs/ja/settings-reference#wslinheritswindowssettings) を使用した WSL でも、Windows 側の管理設定ファイルの変更をポリシーのポーリング時にフックを実行せずに適用します。2916Claude Code は、設定ファイル、管理ポリシーファイル、またはスキルファイルが変更されたときに ConfigChange フックを実行します。管理ポリシーについては、`managed-settings.json` または `managed-settings.d/` 内のファイルが変更された場合にのみ実行します。[サーバー管理設定](/docs/ja/server-managed-settings)や、macOS の管理された環境設定、Windows レジストリのポリシーへの変更は、フックを実行せずに適用します。[`wslInheritsWindowsSettings`](/docs/ja/settings-reference#wslinheritswindowssettings) を使用している WSL では、Windows 側の管理設定ファイルの変更も、ポリシーのポーリング時にフックを実行せずに適用します。
2917 2917
2918matcher は設定のソースでフィルタリングします。2918matcher は設定のソースでフィルタリングします。
2919 2919
2925| `policy_settings` | `managed-settings.json` または `managed-settings.d/` 内のファイルが変更された |2925| `policy_settings` | `managed-settings.json` または `managed-settings.d/` 内のファイルが変更された |
2926| `skills` | `.claude/skills/` 内のスキルファイルが変更された |2926| `skills` | `.claude/skills/` 内のスキルファイルが変更された |
2927 2927
2928以下の例は、セキュリティ監査のためにすべての設定変更をログに記録します。2928次の例は、セキュリティ監査のためにすべての設定変更をログに記録します。
2929 2929
2930```json theme={null}2930```json theme={null}
2931{2931{
2949 ConfigChange の入力2949 ConfigChange の入力
2950</h4>2950</h4>
2951 2951
2952[共通の入力フィールド](#common-input-fields)に加えて、ConfigChange フックは `source` と、省略可能な `file_path` を受け取ります。`source` フィールドはどの種類の設定が変更されたかを示し、`file_path` は変更された特定のファイルへのパスを提供します。2952[共通入力フィールド](#common-input-fields)に加えて、ConfigChange フックは `source` と、省略可能な `file_path` を受け取ります。`source` フィールドはどの種類の設定が変更されたかを示し、`file_path` は変更された特定のファイルのパスを示します。
2953 2953
2954```json theme={null}2954```json theme={null}
2955{2955{
2963```2963```
2964 2964
2965<h4 id="configchange-decision-control">2965<h4 id="configchange-decision-control">
2966 ConfigChange の決定制御2966 ConfigChange の判定制御
2967</h4>2967</h4>
2968 2968
2969ConfigChange フックは、設定の変更が反映されるのをブロックできます。変更を阻止するには、終了コード 2 または JSON の `decision` を使用します。ブロックされた場合、新しい設定は実行中のセッションに適用されません。2969ConfigChange フックは、設定変更が反映されるのをブロックできます。変更を阻止するには、終了コード 2 または JSON の `decision` を使用します。ブロックされた場合、新しい設定は実行中のセッションに適用されません。
2970 2970
2971| フィールド | 説明 |2971| フィールド | 説明 |
2972| :- | :- |2972| :- | :- |
2973| `decision` | `"block"` を指定すると設定の変更が適用されるのを阻止します。変更を許可するには省略します |2973| `decision` | `"block"` を指定すると、設定変更が適用されるのを阻止します。変更を許可するには省略します |
2974| `reason` | 受け付けられますが、表示されることはありません |2974| `reason` | 受け付けられますが、表示されることはありません |
2975 2975
2976```json theme={null}2976```json theme={null}
2980}2980}
2981```2981```
2982 2982
2983`policy_settings` の変更はブロックできません。マシン上の管理設定ファイルが変更されると、`policy_settings` ソースに対してもフックは発火するため、それらの編集をログに記録するために使用できますが、ブロックの決定はすべて無視されます。これにより、エンタープライズで管理される設定が常に反映されることが保証されます。[サーバー管理設定](/docs/ja/server-managed-settings)が届いたり更新されたりしたときには、Claude Code は `ConfigChange` フックを実行しません。2983`policy_settings` の変更はブロックできません。マシン上の管理設定ファイルが変更されたときには `policy_settings` ソースに対してもフックが発火するため、それらの編集をログに記録するのには使用できますが、ブロックの判定はすべて無視されます。これにより、エンタープライズで管理される設定が常に反映されることが保証されます。[サーバー管理設定](/docs/ja/server-managed-settings)が届いたときや更新されたときには、Claude Code は `ConfigChange` フックを実行しません。
2984 2984
2985Claude Code は ConfigChange フックの JSON 出力からブロックの決定に基づいて動作し、`systemMessage` と `continue` は破棄します。ブロックされた変更については、`reason` でブロックした場合も終了コード 2 の stderr でブロックした場合も、ユーザーにも Claude にもメッセージは表示されません。Claude Code はデバッグログに 1 行書き込むだけです。2985Claude Code は ConfigChange フックの JSON 出力のうちブロックの判定に従い、`systemMessage` と `continue` は破棄します。ブロックされた変更については、`reason` でブロックした場合も終了コード 2 の stderr でブロックした場合も、ユーザーにも Claude にもメッセージは表示されません。Claude Code はデバッグログに 1 行書き込むだけです。
2986 2986
2987<h3 id="cwdchanged">2987<h3 id="cwdchanged">
2988 CwdChanged2988 CwdChanged
2989</h3>2989</h3>
2990 2990
2991メイン会話内のシェルコマンドが作業ディレクトリを変更したとき、たとえば Claude が `cd` コマンドを実行したときに実行されます。環境変数の再読み込み、プロジェクト固有のツールチェーンの有効化、セットアップスクリプトの自動実行など、ディレクトリの変更に対応するために使用します。ディレクトリごとの環境を管理する [direnv](https://direnv.net/) のようなツールでは、[FileChanged](#filechanged) と組み合わせて使用します。2991メインの会話内のシェルコマンドが作業ディレクトリを変更したとき、たとえば Claude が `cd` コマンドを実行したときに実行されます。ディレクトリの変更に反応して、環境変数の再読み込み、プロジェクト固有のツールチェーンの有効化、セットアップスクリプトの自動実行などを行うために使用します。ディレクトリごとの環境を管理する [direnv](https://direnv.net/) のようなツールでは、[FileChanged](#filechanged) と組み合わせて使用します。
2992 2992
2993CwdChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の CwdChanged イベントで Claude Code がクリアするまで、後続の Bash コマンドに引き継がれます。2993CwdChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の CwdChanged イベントで Claude Code によってクリアされるまで、後続の Bash コマンドに引き継がれます。
2994 2994
2995CwdChanged は matcher をサポートしておらず、すべての発生時に発火します。2995CwdChanged は matcher をサポートしておらず、発生するたびに発火します。
2996 2996
2997<h4 id="cwdchanged-input">2997<h4 id="cwdchanged-input">
2998 CwdChanged の入力2998 CwdChanged の入力
2999</h4>2999</h4>
3000 3000
3001[共通の入力フィールド](#common-input-fields)に加えて、CwdChanged フックは `old_cwd` と `new_cwd` を受け取ります。3001[共通入力フィールド](#common-input-fields)に加えて、CwdChanged フックは `old_cwd` と `new_cwd` を受け取ります。
3002 3002
3003```json theme={null}3003```json theme={null}
3004{3004{
3015 CwdChanged の出力3015 CwdChanged の出力
3016</h4>3016</h4>
3017 3017
3018すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、CwdChanged フックは `watchPaths` を返して、[FileChanged](#filechanged) が監視するファイルパスを動的に設定できます。3018すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、CwdChanged フックは `watchPaths` を返して、[FileChanged](#filechanged) が監視するファイルパスを動的に設定できます。
3019 3019
3020| フィールド | 説明 |3020| フィールド | 説明 |
3021| :- | :- |3021| :- | :- |
3022| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` 設定のパスは常に監視されます。空の配列を返すと動的なリストがクリアされます。これは新しいディレクトリに移動するときによく使われます |3022| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` 設定のパスは常に監視されます。空の配列を返すと動的リストがクリアされます。これは新しいディレクトリに入るときの典型的な使い方です |
3023 3023
3024CwdChanged フックには決定制御がありません。ディレクトリの変更をブロックすることはできません。3024CwdChanged フックには判定制御がありません。ディレクトリの変更をブロックすることはできません。
3025 3025
3026Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` は破棄します。インタラクティブセッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。3026Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` を破棄します。対話型セッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。
3027 3027
3028<h3 id="directoryadded">3028<h3 id="directoryadded">
3029 DirectoryAdded3029 DirectoryAdded
3030</h3>3030</h3>
3031 3031
3032セッション中に `/add-dir` コマンドで作業ディレクトリを追加した後、または SDK クライアントが `register_repo_root` 制御リクエストで作業ディレクトリを追加した後に実行されます。新しく追加されたリポジトリを準備するため、たとえば依存関係をインストールするために使用します。3032セッションの途中で `/add-dir` コマンドを使って作業ディレクトリを追加した後、または SDK クライアントが `register_repo_root` 制御リクエストで作業ディレクトリを追加した後に実行されます。新たに追加されたリポジトリの準備、たとえば依存関係のインストールに使用します。
3033 3033
3034Claude Code は以下の場合にこのイベントを発火しません。3034Claude Code は次の場合にはこのイベントを発火しません。
3035 3035
3036* `--add-dir` 起動フラグでディレクトリを渡した場合。これらのディレクトリは [SessionStart](#sessionstart) で対応します3036* `--add-dir` 起動フラグでディレクトリを渡した場合。これらのディレクトリは [SessionStart](#sessionstart) でカバーされます
3037* `/permissions` の Workspace タブでディレクトリを追加した場合3037* `/permissions` の Workspace タブでディレクトリを追加した場合
3038* すでに作業ディレクトリであるディレクトリ、または作業ディレクトリ内のディレクトリを追加した場合3038* すでに作業ディレクトリであるディレクトリ、またはその内部にあるディレクトリを追加した場合
3039 3039
3040Claude Code はサンドボックスと権限の状態を更新した後に DirectoryAdded を発火するため、フックの実行時には、サンドボックス化されたツールからすでに新しいディレクトリが見えています。フックコマンド自体はサンドボックスの外で実行されます。3040Claude Code はサンドボックスと権限の状態を更新した後に DirectoryAdded を発火するため、フックが実行される時点で、サンドボックス化されたツールにはすでに新しいディレクトリが見えています。フックコマンド自体はサンドボックス化されずに実行されます。
3041 3041
3042Claude Code はフックを待ちません。追加は即座に完了し、フックはデフォルトの 600 秒のタイムアウトでバックグラウンドで実行されます。3042Claude Code はフックを待ちません。追加はすぐに完了し、フックはデフォルトの 600 秒のタイムアウトでバックグラウンドで実行されます。
3043 3043
3044matcher はディレクトリの追加方法でフィルタリングします。3044matcher は、ディレクトリがどのように追加されたかでフィルタリングします。
3045 3045
3046| Matcher | 発火するタイミング |3046| Matcher | 発火するタイミング |
3047| :- | :- |3047| :- | :- |
3052 DirectoryAdded の入力3052 DirectoryAdded の入力
3053</h4>3053</h4>
3054 3054
3055[共通の入力フィールド](#common-input-fields)に加えて、DirectoryAdded フックは `directory` と `source` を受け取ります。3055[共通入力フィールド](#common-input-fields)に加えて、DirectoryAdded フックは `directory` と `source` を受け取ります。
3056 3056
3057| フィールド | 説明 |3057| フィールド | 説明 |
3058| :- | :- |3058| :- | :- |
3070}3070}
3071```3071```
3072 3072
3073DirectoryAdded フックには決定制御がありません。フックの実行時には追加がすでに完了しているため、追加をブロックすることはできません。Claude Code は JSON 出力から `continue` フィールドを破棄し、残りはソースごとに異なる方法で扱います。3073DirectoryAdded フックには判定制御がありません。フックが実行される時点で追加はすでに完了しているため、追加をブロックすることはできません。Claude Code は JSON 出力から `continue` フィールドを破棄し、残りをソースごとに異なる方法で表示します。
3074 3074
3075* `slash_command`: Claude Code はフックの `systemMessage` をユーザーに表示するのではなく、次の会話ターンでコンテキストとして Claude に配信します。失敗したフックの数がトランスクリプトに表示されます。失敗の完全な出力はデバッグログに記録されます3075* `slash_command`: Claude Code はフックの `systemMessage` をユーザーに表示するのではなく、次の会話ターンでコンテキストとして Claude に渡します。失敗したフックの数がトランスクリプトに表示されます。失敗時の出力全体はデバッグログに記録されます
3076* `register_repo_root`: Claude Code は `systemMessage` の出力と失敗の出力をデバッグログにのみ書き込みます3076* `register_repo_root`: Claude Code は `systemMessage` の出力と失敗時の出力をデバッグログにのみ書き込みます
3077 3077
3078<h3 id="filechanged">3078<h3 id="filechanged">
3079 FileChanged3079 FileChanged
3080</h3>3080</h3>
3081 3081
3082監視対象のファイルがディスク上で変更されたときに実行されます。Claude Code はツール呼び出しを調べるのではなくファイルシステムウォッチャーで変更を検出するため、`Edit` や `Write` のツール呼び出し、Claude が `Bash` で実行したスクリプト、あるいは Claude Code 外部のプロセスなど、何がファイルを変更したかにかかわらずフックを実行します。一般的な用途は、プロジェクトの設定ファイルが変更されたときに環境変数を再読み込みすることです。3082監視対象のファイルがディスク上で変更されたときに実行されます。Claude Code はツール呼び出しを調べるのではなく、ファイルシステムウォッチャーで変更を検出するため、何がファイルを変更したかに関係なくフックを実行します。対象となるのは、`Edit` や `Write` のツール呼び出し、Claude が `Bash` で実行するスクリプト、あるいは Claude Code の完全に外部のプロセスです。一般的な用途は、プロジェクトの設定ファイルが変更されたときに環境変数を再読み込みすることです。
3083 3083
3084このイベントの `matcher` には 2 つの役割があります。3084このイベントの `matcher` には 2 つの役割があります。
3085 3085
3086* **監視リストの構築**: 値は `|` で分割され、各セグメントが作業ディレクトリ内のリテラルなファイル名として登録されます。そのため、`".envrc|.env"` はちょうどその 2 つのファイルを監視します。ここでは正規表現パターンは役に立ちません。`^\.env` のような値は、文字どおり `^\.env` という名前のファイルを監視します。3086* **監視リストを構築する**: 値は `|` で分割され、各セグメントが作業ディレクトリ内のリテラルなファイル名として登録されます。そのため、`".envrc|.env"` はちょうどその 2 つのファイルを監視します。ここでは正規表現パターンは役に立ちません。`^\.env` のような値は、文字どおり `^\.env` という名前のファイルを監視することになります。
3087* **実行するフックのフィルタリング**: 監視対象のファイルが変更されると、同じ値を使用して、変更されたファイルのベース名に対して標準の [matcher ルール](#matcher-patterns)を適用し、実行するフックグループをフィルタリングします。3087* **実行するフックをフィルタリングする**: 監視対象のファイルが変更されると、同じ値が、変更されたファイルのベース名に対して標準の [matcher ルール](#matcher-patterns)を使い、どのフックグループを実行するかをフィルタリングします。
3088 3088
3089以下の例は、`Bash` コマンドや外部スクリプトによるファイルの書き換えを含め、変更があるたびに `data.csv` の改行コードを正規化します。3089次の例は、`Bash` コマンドや外部スクリプトによるファイルの書き換えを含め、あらゆる変更の後に `data.csv` の改行コードを正規化します。
3090 3090
3091```json theme={null}3091```json theme={null}
3092{3092{
3106}3106}
3107```3107```
3108 3108
3109フックは、stdin 上の [JSON 入力](#filechanged-input)の `file_path` フィールドから、変更されたファイルの絶対パスを読み取ります。`grep` によるガードは `perl` が削除するもの、つまり行末の CR と同じものを検査するため、正規化後の実行ではファイルに触れずに終了します。ガードがより緩いと無限ループになります。`perl -i` は何も置換しない場合でもファイルを書き換え、Claude Code は書き換えのたびにフックを再度実行するためです。このスクリプトを `/path/to/normalize-line-endings.sh` に保存し、実行可能にしてください。3109このフックは、stdin の [JSON 入力](#filechanged-input)の `file_path` フィールドから、変更されたファイルの絶対パスを読み取ります。`grep` によるガードは、`perl` が削除するのと同じもの、つまり行末の CR を検査するため、正規化後の実行ではファイルに触れずに終了します。これより緩いガードだと無限ループになります。`perl -i` は何も置換しなくてもファイルを書き換え、Claude Code は書き換えのたびにフックを再実行するためです。このスクリプトを `/path/to/normalize-line-endings.sh` に保存し、実行可能にしてください。
3110 3110
3111```bash theme={null}3111```bash theme={null}
3112#!/bin/bash3112#!/bin/bash
3116fi3116fi
3117```3117```
3118 3118
3119フックが機能することを確認するには、`Bash` コマンドで `data.csv` に CRLF の行を追記するよう Claude に依頼します。Claude Code がフックを実行し、ファイルの改行コードは LF になります。3119フックが機能することを確認するには、`Bash` コマンドで `data.csv` に CRLF の行を追加するよう Claude に依頼します。Claude Code がフックを実行し、ファイルの改行コードは LF になります。
3120 3120
3121事前に名前を指定できないファイルを監視するには、フックから [`watchPaths`](#filechanged-output) を返して監視リストを動的に更新します。Claude Code は監視対象のファイルが何らかの形で指定された場合にのみウォッチャーを開始するため、少なくとも 1 つのファイルを matcher で指定した FileChanged グループ、または `watchPaths` を返す [SessionStart](#sessionstart-decision-control) や [CwdChanged](#cwdchanged) フックでリストを初期化してください。監視対象のファイルが変更されたときにどのフックグループを実行するかは引き続き matcher でフィルタリングされるため、動的なパスを処理するグループでは matcher を省略してください。省略した matcher はすべての監視対象ファイルにマッチし、監視リストには何も追加しません。`"*"` matcher もすべてのファイルにマッチしますが、Claude Code はこれを他の値と同様に、`*` という名前のリテラルなファイルとして監視リストに登録します。3121事前に名前を指定できないファイルを監視するには、フックから [`watchPaths`](#filechanged-output) を返して監視リストを動的に更新します。Claude Code は、何かが監視するファイルを指定した場合にのみウォッチャーを起動するため、少なくとも 1 つのファイルを指定する matcher を持つ FileChanged グループか、`watchPaths` を返す [SessionStart](#sessionstart-decision-control) または [CwdChanged](#cwdchanged) フックでリストの初期値を設定してください。監視対象のファイルが変更されたとき、matcher は引き続きどのフックグループを実行するかをフィルタリングするため、動的なパスを処理するグループでは matcher を省略してください。省略した matcher はすべての監視対象ファイルにマッチし、監視リストには何も追加しません。`"*"` の matcher もすべてのファイルにマッチしますが、Claude Code はそれを他の値と同様に、`*` という名前のリテラルなファイルとして監視リストに登録します。
3122 3122
3123FileChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の [CwdChanged](#cwdchanged) イベントで Claude Code がクリアするまで、後続の Bash コマンドに引き継がれます。3123FileChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の [CwdChanged](#cwdchanged) イベントで Claude Code によってクリアされるまで、後続の Bash コマンドに引き継がれます。
3124 3124
3125<h4 id="filechanged-input">3125<h4 id="filechanged-input">
3126 FileChanged の入力3126 FileChanged の入力
3127</h4>3127</h4>
3128 3128
3129[共通の入力フィールド](#common-input-fields)に加えて、FileChanged フックは `file_path` と `event` を受け取ります。3129[共通入力フィールド](#common-input-fields)に加えて、FileChanged フックは `file_path` と `event` を受け取ります。
3130 3130
3131| フィールド | 説明 |3131| フィールド | 説明 |
3132| :- | :- |3132| :- | :- |
3133| `file_path` | 変更されたファイルの絶対パス |3133| `file_path` | 変更されたファイルの絶対パス |
3134| `event` | 何が起きたか。変更されたファイルの場合は `"change"`、作成されたファイルの場合は `"add"`、削除されたファイルの場合は `"unlink"` |3134| `event` | 発生した内容: 変更されたファイルの場合は `"change"`、作成されたファイルの場合は `"add"`、削除されたファイルの場合は `"unlink"` |
3135 3135
3136```json theme={null}3136```json theme={null}
3137{3137{
3148 FileChanged の出力3148 FileChanged の出力
3149</h4>3149</h4>
3150 3150
3151すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、FileChanged フックは `watchPaths` を返して、監視するファイルパスを動的に更新できます。3151すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、FileChanged フックは `watchPaths` を返して、監視するファイルパスを動的に更新できます。
3152 3152
3153| フィールド | 説明 |3153| フィールド | 説明 |
3154| :- | :- |3154| :- | :- |
3155| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` 設定のパスは常に監視されます。フックスクリプトが、変更されたファイルに基づいて監視すべき追加のファイルを見つけた場合に使用します |3155| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` 設定のパスは常に監視されます。変更されたファイルに基づいて、フックスクリプトが監視すべき追加のファイルを見つけた場合に使用します |
3156 3156
3157FileChanged フックには決定制御がありません。ファイルの変更が発生するのをブロックすることはできません。3157FileChanged フックには判定制御がありません。ファイルの変更が発生するのをブロックすることはできません。
3158 3158
3159Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` は破棄します。インタラクティブセッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。3159Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` を破棄します。対話型セッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。
3160 3160
3161<h3 id="worktreecreate">3161<h3 id="worktreecreate">
3162 WorktreeCreate3162 WorktreeCreate
3163</h3>3163</h3>
3164 3164
3165`claude --worktree`、[`isolation: "worktree"` を使用するサブエージェント](/docs/ja/sub-agents#choose-the-subagent-scope)、または Claude Code が独自の worktree に分離する[バックグラウンドセッション](/docs/ja/agent-view#how-file-edits-are-isolated)のいずれかによって worktree が作成されるときに実行されます。デフォルトでは、Claude Code は `git worktree` を使用して分離された作業コピーを作成します。WorktreeCreate フックを設定すると、このデフォルトの git の動作が置き換えられ、SVN、Perforce、Mercurial などの別のバージョン管理システムを使用できるようになります。3165worktree が作成されるときに実行されます。対象は、`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 などの別のバージョン管理システムを使用できるようになります。
3166 3166
3167フックはデフォルトの動作を完全に置き換えるため、[`.worktreeinclude`](/docs/ja/worktrees#copy-gitignored-files-into-worktrees) は処理されません。`.env` などのローカル設定ファイルを新しい worktree にコピーする必要がある場合は、フックスクリプト内でコピーしてください。3167フックはデフォルトの動作を完全に置き換えるため、[`.worktreeinclude`](/docs/ja/worktrees#copy-gitignored-files-into-worktrees) は処理されません。`.env` のようなローカルの設定ファイルを新しい worktree にコピーする必要がある場合は、フックスクリプト内で行ってください。
3168 3168
3169フックは、作成された worktree ディレクトリへのパスを返す必要があります。Claude Code はこのパスを分離されたセッションの作業ディレクトリとして使用します。各フックタイプがパスを返す方法については、[WorktreeCreate の出力](#worktreecreate-output)を参照してください。3169フックは、作成された worktree ディレクトリのパスを返す必要があります。Claude Code はこのパスを、分離されたセッションの作業ディレクトリとして使用します。各フックタイプがパスを返す方法については、[WorktreeCreate の出力](#worktreecreate-output)を参照してください。
3170 3170
3171Claude Code はフックの成功と返されたパスに基づいて動作し、`systemMessage` と `continue` は破棄します。3171Claude Code はフックの成否と返されたパスに従い、`systemMessage` と `continue` を破棄します。
3172 3172
3173以下の例は、SVN の作業コピーを作成し、Claude Code が使用するパスを出力します。リポジトリの URL は自分のものに置き換えてください。3173次の例は、SVN の作業コピーを作成し、Claude Code が使用するパスを出力します。リポジトリの URL は独自のものに置き換えてください。
3174 3174
3175```json theme={null}3175```json theme={null}
3176{3176{
3189}3189}
3190```3190```
3191 3191
3192フックは stdin 上の JSON 入力から worktree の `name` を読み取り、新しいディレクトリに新しいコピーをチェックアウトして、そのディレクトリパスを出力します。最後の行の `echo` が、Claude Code が worktree のパスとして読み取るものです。パスの妨げにならないよう、その他の出力はすべて stderr にリダイレクトしてください。3192このフックは、stdin の JSON 入力から worktree の `name` を読み取り、新しいディレクトリに新規コピーをチェックアウトし、そのディレクトリのパスを出力します。最後の行の `echo` が、Claude Code が worktree のパスとして読み取るものです。パスに干渉しないよう、その他の出力はすべて stderr にリダイレクトしてください。
3193 3193
3194<h4 id="worktreecreate-input">3194<h4 id="worktreecreate-input">
3195 WorktreeCreate の入力3195 WorktreeCreate の入力
3196</h4>3196</h4>
3197 3197
3198[共通の入力フィールド](#common-input-fields)に加えて、WorktreeCreate フックは `name` フィールドを受け取ります。これは新しい worktree のスラッグ識別子で、ユーザーが指定するか自動生成されます（例: `bold-oak-a3f2`）。3198[共通入力フィールド](#common-input-fields)に加えて、WorktreeCreate フックは `name` フィールドを受け取ります。これは新しい worktree のスラッグ識別子で、ユーザーが指定したものか自動生成されたもの（例: `bold-oak-a3f2`）です。
3199 3199
3200```json theme={null}3200```json theme={null}
3201{3201{
3211 WorktreeCreate の出力3211 WorktreeCreate の出力
3212</h4>3212</h4>
3213 3213
3214WorktreeCreate フックは、標準の許可/ブロックの判定モデルを使用しません。代わりに、フックの成功または失敗によって結果が決まります。フックは作成された worktree ディレクトリのパスを返す必要があります。3214WorktreeCreate フックは、標準の許可/ブロックの判定モデルを使用しません。代わりに、フックの成功または失敗によって結果が決まります。フックは作成した worktree ディレクトリのパスを返す必要があります。
3215 3215
3216* **コマンドフック**（`type: "command"`）：パスを stdout の最後の空でない行として出力します。Claude Code はその行を読み取る前に ANSI エスケープコードを取り除くため、`echo` の前に出力されたシェルの起動バナーは無視されます。フックのその他の出力はすべて stderr にリダイレクトしてください。3216* **コマンドフック**（`type: "command"`）: パスを stdout の最後の空でない行として出力します。Claude Code はその行を読み取る前に ANSI エスケープコードを除去するため、`echo` より前に出力されたシェルの起動バナーは無視されます。それ以外のフックの出力はすべて stderr にリダイレクトしてください。
3217* **HTTP フック**（`type: "http"`）：レスポンスボディで `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` を返します。3217* **HTTP フック**（`type: "http"`）: レスポンス本文で `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` を返します。
3218 3218
3219フックが失敗した場合、またはパスを生成しなかった場合、worktree の作成はエラーで失敗します。3219フックが失敗した場合やパスを出力しなかった場合、worktree の作成はエラーで失敗します。
3220 3220
3221Claude Code は相対パスをフックが実行されたディレクトリを基準に解決し、パス内の `.` や `..` セグメントを畳み込みます。解決後のパスが Claude Code が移動できるディレクトリでない場合、セッションはそのパスを示すエラーを出力し、終了コード 1 で終了します。3221Claude Code は相対パスをフックが実行されたディレクトリを基準に解決し、その中の `.` や `..` セグメントを畳み込みます。結果のパスが Claude Code の移動できるディレクトリでない場合、セッションはそのパスを示すエラーを出力し、終了コード 1 で終了します。
3222 3222
3223Claude Code は、`.` や `..` セグメントを含む絶対パス、およびリポジトリルート配下のシンボリックリンクを経由するパスを拒否します。リポジトリにコミットされたシンボリックリンクによって、worktree がリポジトリの外にリダイレクトされる可能性があるためです。エラーには拒否されたコンポーネントが示されます。リポジトリ内のシンボリックリンクを経由しない正規化されたパスを返してください。v2.1.216 より前は、worktree の作成はこのチェックを行わずにフックのパスに従っていました。3223Claude Code は、`.` や `..` セグメントを含む絶対パスと、リポジトリルート以下のシンボリックリンクを経由するパスを拒否します。リポジトリにコミットされたシンボリックリンクによって worktree がリポジトリ外へリダイレクトされる可能性があるためです。エラーには拒否されたコンポーネントが示されます。正規化され、リポジトリ内のシンボリックリンクを経由しないパスを返してください。v2.1.216 より前は、worktree の作成はこのチェックを行わずにフックのパスに従っていました。
3224 3224
3225<h3 id="worktreeremove">3225<h3 id="worktreeremove">
3226 WorktreeRemove3226 WorktreeRemove
3229worktree が削除されるときに実行されます。これは [WorktreeCreate](#worktreecreate) に対応するクリーンアップ用のイベントです。このイベントは次の場合に発生します。3229worktree が削除されるときに実行されます。これは [WorktreeCreate](#worktreecreate) に対応するクリーンアップ用のイベントです。このイベントは次の場合に発生します。
3230 3230
3231* `--worktree` セッションを終了し、削除を選択したとき3231* `--worktree` セッションを終了し、削除を選択したとき
3232* `isolation: "worktree"` を持つサブエージェントが完了したとき3232* `isolation: "worktree"` を指定したサブエージェントが終了したとき
3233* フックが worktree を作成した[バックグラウンドセッション](/docs/ja/agent-view#what-deleting-a-session-removes)を削除したとき3233* フックが worktree を作成した[バックグラウンドセッション](/docs/ja/agent-view#what-deleting-a-session-removes)を削除したとき
3234 3234
3235Git ベースの worktree の場合、Claude Code は `git worktree remove` でクリーンアップを自動的に処理します。WorktreeCreate フックを設定した場合は、WorktreeRemove フックと組み合わせて、作成した worktree のクリーンアップを制御してください。3235Git ベースの worktree の場合、Claude Code は `git worktree remove` で自動的にクリーンアップを行います。WorktreeCreate フックを設定した場合は、WorktreeRemove フックと組み合わせて、作成した worktree のクリーンアップを制御してください。
3236 3236
3237* **WorktreeRemove フックがない場合**：`--worktree` セッションを終了して削除を選択すると、Claude Code は WorktreeCreate フックが返したパスに対して `git worktree remove --force` にフォールバックするため、Git が認識している worktree は削除されます。Git が認識していない worktree（たとえば、Git 以外のバージョン管理システムでフックが作成したもの）はディスク上に残ります。フックが作成した worktree に対して[バックグラウンドセッション](/docs/ja/agent-view#what-deleting-a-session-removes)の削除が何を行うかについては、agent view の削除ルールを参照してください。3237* **WorktreeRemove フックがない場合**: `--worktree` セッションを終了して削除を選択すると、Claude Code は WorktreeCreate フックが返したパスに対して `git worktree remove --force` にフォールバックするため、Git が認識している worktree は削除されます。Git が認識していない worktree（たとえば Git 以外のバージョン管理システムでフックが作成したもの）はディスクに残ります。[バックグラウンドセッション](/docs/ja/agent-view#what-deleting-a-session-removes)の削除がフックで作成された worktree をどう扱うかについては、エージェントビューの削除ルールを参照してください。
3238* **フックが 0 で終了した場合**：worktree は削除済みとして扱われます。Claude Code はフックからそれ以外の情報を読み取らないため、フックがディレクトリを確実に削除するようにしてください。3238* **フックが 0 で終了した場合**: worktree は削除済みとして扱われます。Claude Code はフックからそれ以外に何も読み取らないため、フックがディレクトリを確実に削除するようにしてください。
3239* **フックが 0 以外で終了した場合**：その後も `worktree_path` のディレクトリが存在していれば削除は失敗し、Git へのフォールバックは行われずに worktree はディスク上に残ります。0 以外で終了する前にディレクトリを削除したフックは、削除済みとして扱われます。失敗がどのように報告されるかについては、[WorktreeRemove の入力](#worktreeremove-input)を参照してください。3239* **フックが 0 以外で終了した場合**: その後も `worktree_path` のディレクトリが存在していれば削除は失敗し、Git へのフォールバックなしで worktree はディスクに残ります。0 以外で終了する前にディレクトリを削除したフックは、削除済みとして扱われます。失敗の報告方法については、[WorktreeRemove の入力](#worktreeremove-input)を参照してください。
3240 3240
3241Claude Code は WorktreeCreate フックが返したパスしか把握していないため、フックが作成した worktree に属するブランチを削除することはありません。WorktreeCreate フックがブランチを作成する場合は、WorktreeRemove フックでそのブランチを削除してください。3241Claude Code は WorktreeCreate フックが返したパスしか把握していないため、フックで作成された worktree に属するブランチを削除することはありません。WorktreeCreate フックでブランチを作成する場合は、WorktreeRemove フックでそのブランチを削除してください。
3242 3242
3243Claude Code は、`systemMessage` や `continue` などの WorktreeRemove フックの [JSON 出力フィールド](#json-output)を破棄します。3243Claude Code は、`systemMessage` や `continue` など、WorktreeRemove フックの [JSON 出力フィールド](#json-output)を破棄します。
3244 3244
3245バックグラウンドセッションの削除では、Claude Code はフックを実行する前に保存された worktree パスを検証し、シンボリックリンクであるパスや、リポジトリルート配下のシンボリックリンクを経由するパスを拒否します。まだファイルが含まれている worktree に対してフックが実行されるのは、[agent view](/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 より前は、フックはこれらのチェックなしに保存されたパスに対して実行されていました。3245バックグラウンドセッションの削除では、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 より前は、フックはこれらのチェックなしで保存されたパスに対して実行されていました。
3246 3246
3247Claude Code は、WorktreeCreate が返したパスをフック入力の `worktree_path` として渡します。次の例では、そのパスを読み取ってディレクトリを削除します。3247Claude Code は、WorktreeCreate が返したパスをフック入力の `worktree_path` として渡します。次の例では、そのパスを読み取ってディレクトリを削除します。
3248 3248
3279}3279}
3280```3280```
3281 3281
3282WorktreeRemove フックの終了コードによって結果が決まります。フックが 0 以外で終了し、その後も `worktree_path` のディレクトリが存在する場合、削除は失敗します。3282WorktreeRemove フックの終了コードによって結果が決まります。フックが 0 以外で終了し、その後も `worktree_path` のディレクトリが存在している場合、削除は失敗します。
3283 3283
3284* worktree はディスク上に残り、フックのコマンドと stderr は[デバッグログ](#debug-hooks)に送られます。3284* worktree はディスクに残り、フックのコマンドと stderr は[デバッグログ](#debug-hooks)に記録されます。
3285* バックグラウンドセッションを削除しようとしていた場合は、セッションも残ります。[agent view](/docs/ja/agent-view#what-deleting-a-session-removes) の拒否メッセージには、`exited 1` などフックがどのように終了したか、stderr の冒頭部分、そしてセッションを再度削除した場合にディレクトリが強制的に削除されるかどうかが表示されます。3285* バックグラウンドセッションを削除していた場合、セッションも残ります。[エージェントビュー](/docs/ja/agent-view#what-deleting-a-session-removes)の拒否メッセージには、`exited 1` のようなフックの終了状況、stderr の冒頭部分、およびセッションを再度削除した場合にディレクトリがそれでも削除されるかどうかが表示されます。
3286 3286
3287<h3 id="precompact">3287<h3 id="precompact">
3288 PreCompact3288 PreCompact
3299 3299
3300圧縮をブロックするには、終了コード 2 で終了します。手動の `/compact` の場合、stderr のメッセージがユーザーに表示されます。`"decision": "block"` を含む JSON を返してブロックすることもできます。3300圧縮をブロックするには、終了コード 2 で終了します。手動の `/compact` の場合、stderr のメッセージがユーザーに表示されます。`"decision": "block"` を含む JSON を返してブロックすることもできます。
3301 3301
3302自動圧縮をブロックした場合の効果は、発生するタイミングによって異なります。コンテキスト制限に達する前に予防的に圧縮がトリガーされた場合、Claude Code は圧縮をスキップし、会話は圧縮されないまま続行されます。API からすでに返されたコンテキスト制限エラーから回復するために圧縮がトリガーされた場合、元のエラーが表面化し、現在のリクエストは失敗します。3302自動圧縮をブロックした場合の影響は、発生したタイミングによって異なります。コンテキスト上限に達する前に予防的に圧縮がトリガーされた場合、Claude Code は圧縮をスキップし、会話は圧縮されないまま続行されます。API がすでに返したコンテキスト上限エラーから回復するために圧縮がトリガーされた場合は、元のエラーが表面化し、現在のリクエストは失敗します。
3303 3303
3304Claude Code は PreCompact フックの `systemMessage` および `continue` フィールドを破棄します。3304Claude Code は PreCompact フックの `systemMessage` と `continue` フィールドを破棄します。
3305 3305
3306<h4 id="precompact-input">3306<h4 id="precompact-input">
3307 PreCompact の入力3307 PreCompact の入力
3324 PostCompact3324 PostCompact
3325</h3>3325</h3>
3326 3326
3327Claude Code がコンテキスト圧縮を完了した後に実行されます。このイベントを使用すると、生成された要約をログに記録したり外部の状態を更新したりするなど、圧縮後の新しい状態に対応できます。Claude Code は PostCompact フックの `systemMessage` および `continue` フィールドを破棄します。3327Claude Code がコンテキスト圧縮を完了した後に実行されます。このイベントを使用すると、圧縮後の新しい状態に対応できます。たとえば、生成された要約をログに記録したり、外部の状態を更新したりできます。Claude Code は PostCompact フックの `systemMessage` と `continue` フィールドを破棄します。
3328 3328
3329`PreCompact` と同じ matcher の値が適用されます。3329`PreCompact` と同じ matcher の値が適用されます。
3330 3330
3350}3350}
3351```3351```
3352 3352
3353PostCompact フックには判定の制御がありません。圧縮の結果に影響を与えることはできませんが、後続のタスクを実行できます。3353PostCompact フックには判定の制御はありません。圧縮の結果に影響を与えることはできませんが、後続のタスクを実行できます。
3354 3354
3355<h3 id="premodelswitch">3355<h3 id="premodelswitch">
3356 PreModelSwitch3356 PreModelSwitch
3357</h3>3357</h3>
3358 3358
3359ユーザーまたはクライアントが要求したモデルの切り替えを Claude Code が適用する前に実行されます。切り替えのブロック、確認の要求、または切り替え前にそのコストを表示するために使用します。3359ユーザーまたはクライアントが要求したモデルの切り替えを Claude Code が適用する前に実行されます。切り替えをブロックしたり、確認を求めたり、切り替えにかかるコストを事前に表示したりするために使用します。
3360 3360
3361PreModelSwitch には Claude Code v2.1.251 以降が必要です。Claude Code は次のリクエストに対してこのフックを実行します。3361PreModelSwitch には Claude Code v2.1.251 以降が必要です。Claude Code は次のリクエストに対してこのフックを実行します。
3362 3362
3363* `/model <name>` および `/model` ピッカー3363* `/model <name>` と `/model` ピッカー
3364* `Option+P` または `Alt+P` のモデルピッカー3364* `Option+P` または `Alt+P` のモデルピッカー
3365* `/config` の Model 設定3365* `/config` の Model 設定
3366* セッションのモデルが変わる場合の [fast mode](/docs/ja/fast-mode) のオン3366* セッションのモデルが変わる場合の [fast mode](/docs/ja/fast-mode) のオン
3367* [Agent SDK](/docs/ja/agent-sdk/typescript#query-object) ホストまたは [Remote Control](/docs/ja/remote-control) からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更3367* [Agent SDK](/docs/ja/agent-sdk/typescript#query-object) ホストまたは [Remote Control](/docs/ja/remote-control) からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更
3368 3368
3369[モデルの自動フォールバック](/docs/ja/model-config#automatic-model-fallback)やセッション再開時のモデルの復元など、Claude Code が独自に行う切り替えについては PreModelSwitch フックは実行されません。これらの変更は [PostModelSwitch](#postmodelswitch) にのみ届きます。3369Claude Code は、[自動モデルフォールバック](/docs/ja/model-config#automatic-model-fallback)やセッション再開時のモデルの復元など、Claude Code 自身が行う切り替えに対しては PreModelSwitch フックを実行しません。これらの変更は [PostModelSwitch](#postmodelswitch) にのみ届きます。
3370 3370
3371Claude Code は、matcher をセッションの切り替え先モデルの正規名と比較します。このとき `[1m]` サフィックスは無視されます。`opus` などのエイリアス、日付付きのモデル ID、Amazon Bedrock のモデル ID などのプロバイダー固有の ID はすべて、解決先の 1 つの正規名に一致するため、`claude-opus-5` は Opus 5 のあらゆる表記をカバーします。3371Claude Code は、`[1m]` サフィックスを無視して、切り替え先モデルの正規名と matcher を比較します。`opus` のようなエイリアス、日付付きのモデル ID、Amazon Bedrock のモデル ID のようなプロバイダー固有の ID は、いずれも解決先の 1 つの正規名にマッチするため、`claude-opus-5` は Opus 5 のあらゆる表記をカバーします。
3372 3372
3373Claude Code が切り替え先の正規名を特定できない場合（たとえば [LLM ゲートウェイ](/docs/ja/llm-gateway)だけが認識するカスタムモデル ID など）、matcher に関係なくすべての PreModelSwitch フックが実行されます。したがって、ブロックを行うフックは matcher だけに頼るのではなく、入力の `to_model` を確認する必要があります。3373切り替え先の正規名を特定できない場合（たとえば [LLM ゲートウェイ](/docs/ja/llm-gateway)だけが認識するカスタムモデル ID の場合）、Claude Code は matcher に関係なくすべての PreModelSwitch フックを実行します。そのため、ブロックするフックは matcher だけに頼らず、入力の `to_model` を確認する必要があります。
3374 3374
3375matcher は、完全一致の名前、`claude-opus-4-6|claude-opus-5` のような `|` 区切りのリスト、または `.*opus.*` のような正規表現として記述します。次の例では、完全一致の matcher を使用しつつフック入力の `to_model` も確認し、終了コード 2 で終了することで Opus 4.6 への切り替えを拒否し、それ以外の切り替え先は通過させます。3375matcher は、完全な名前、`claude-opus-4-6|claude-opus-5` のような `|` 区切りのリスト、または `.*opus.*` のような正規表現で記述します。次の例では、完全名の matcher を使用し、さらにフック入力の `to_model` も確認することで、Opus 4.6 への切り替えを終了コード 2 で拒否し、それ以外の切り替え先は許可します。
3376 3376
3377<Tabs>3377<Tabs>
3378 <Tab title="macOS/Linux">3378 <Tab title="macOS/Linux">
3379 このコマンドは `jq` で `to_model` を確認します。3379 コマンドは `jq` で `to_model` を確認します。
3380 3380
3381 ```json theme={null}3381 ```json theme={null}
3382 {3382 {
3438 </Tab>3438 </Tab>
3439</Tabs>3439</Tabs>
3440 3440
3441フックが機能することを確認するには、別のモデルで実行中のセッションから `/model claude-opus-4-6` を実行します。Claude Code は現在のモデルを維持し、PreModelSwitch フックが切り替えをブロックしたことを、指定したメッセージを理由として報告します。3441フックが動作することを確認するには、別のモデルを実行しているセッションから `/model claude-opus-4-6` を実行します。Claude Code は現在のモデルを維持し、PreModelSwitch フックが切り替えをブロックしたことを、指定したメッセージを理由として報告します。
3442 3442
3443<h4 id="premodelswitch-input">3443<h4 id="premodelswitch-input">
3444 PreModelSwitch の入力3444 PreModelSwitch の入力
3445</h4>3445</h4>
3446 3446
3447[共通の入力フィールド](#common-input-fields)に加えて、PreModelSwitch フックは次の表のフィールドを受け取ります。最後の 5 つは、会話を新しいモデルに再送信する際のコストを表すため、フックは切り替えの前にその数値を表示できます。3447[共通の入力フィールド](#common-input-fields)に加えて、PreModelSwitch フックは次の表のフィールドを受け取ります。最後の 5 つは会話を新しいモデルに再送信するコストを表すため、フックは切り替えの前にその金額を表示できます。
3448 3448
3449| フィールド | 型 | 説明 |3449| フィールド | 型 | 説明 |
3450| :- | :- | :- |3450| :- | :- | :- |
3451| `from_model` | string | 切り替え元のモデル ID |3451| `from_model` | string | 切り替え元のモデル ID |
3452| `to_model` | string | 切り替え先のモデル ID。matcher はこのモデルの正規名と比較されます |3452| `to_model` | string | 切り替え先のモデル ID。matcher はこのモデルの正規名と比較されます |
3453| `requested_model` | string または `null` | リクエストで指定されたモデル：`opus` などのエイリアス、完全なモデル ID、またはデフォルトモデルがリクエストされた場合は `null` |3453| `requested_model` | string または `null` | リクエストで指定されたモデル: `opus` のようなエイリアス、完全なモデル ID、またはデフォルトモデルが要求された場合は `null` |
3454| `source` | string | リクエストの送信元：`/model <name>`、`/config` の Model 設定、または fast mode のオンの場合は `"command"`、モデルピッカーの場合は `"picker"`、Agent SDK ホストまたは Remote Control からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更の場合は `"sdk"` |3454| `source` | string | リクエストの送信元: `/model <name>`、`/config` の Model 設定、または fast mode のオンの場合は `"command"`、モデルピッカーの場合は `"picker"`、Agent SDK ホストまたは Remote Control からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更の場合は `"sdk"` |
3455| `context_tokens` | number | 次のリクエストがプロンプトとして再送信するトークン数：メイン会話における最後の応答の入力、キャッシュ読み取り、キャッシュ作成、出力トークンの合計。最初の応答の前は `0` |3455| `context_tokens` | number | 次のリクエストがプロンプトとして再送信するトークン数: メイン会話の最後の応答の入力、キャッシュ読み取り、キャッシュ作成、出力トークンの合計。最初の応答の前は `0` |
3456| `prompt_cache_warm` | boolean | 現在のモデルのプロンプトキャッシュがまだウォーム状態である可能性が高いかどうか。ウォーム状態の場合、切り替えによってキャッシュが失われます |3456| `prompt_cache_warm` | boolean | 現在のモデルのプロンプトキャッシュがまだウォームである可能性が高いかどうか。つまり、切り替えによってそれが失われるかどうか |
3457| `cache_ttl` | string | このセッションで Claude Code が要求する[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime)：`"5m"` または `"1h"` |3457| `cache_ttl` | string | Claude Code がこのセッションで要求する[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime): `"5m"` または `"1h"` |
3458| `estimated_cache_write_usd` | number | `to_model` 上で `context_tokens` を `cache_ttl` の料金でプロンプトキャッシュに書き込む推定コスト（米ドル）。次の応答は含みません。サーバーがコンテキスト全体を再キャッシュする必要がない場合もあるため、推定値として扱ってください |3458| `estimated_cache_write_usd` | number | `to_model` 上で `cache_ttl` の料金で `context_tokens` をプロンプトキャッシュに書き込む推定コスト（米ドル）。次の応答は含みません。サーバーがコンテキスト全体を再キャッシュする必要がない場合もあるため、推定値として扱ってください |
3459| `pricing` | string | Claude Code が `estimated_cache_write_usd` をどのように算出したか：組織が独自の料金を設定している場合はその料金による `"configured"`、定価による `"catalog"`、または `to_model` の料金が不明で Claude Code がデフォルト料金を仮定した場合は `"default"` |3459| `pricing` | string | Claude Code が `estimated_cache_write_usd` の料金をどのように算出したか: 組織独自の料金が設定されている場合はその料金による `"configured"`、定価による `"catalog"`、または `to_model` の価格が不明で Claude Code がデフォルトの料金を想定した場合は `"default"` |
3460 3460
3461次の例は、Sonnet 5 で実行中のセッションで `/model opus` を実行した場合の入力を示しています。3461次の例は、Sonnet 5 を実行しているセッションでの `/model opus` の入力を示しています。
3462 3462
3463```json theme={null}3463```json theme={null}
3464{3464{
3479```3479```
3480 3480
3481<h4 id="premodelswitch-decision-control">3481<h4 id="premodelswitch-decision-control">
3482 PreModelSwitch の判定制御3482 PreModelSwitch の判定の制御
3483</h4>3483</h4>
3484 3484
3485`PreModelSwitch` フックは、切り替えをキャンセルしたり、ユーザーに確認を求めたり、そのまま続行させたりできます。終了コード 2 またはトップレベルの `decision: "block"` は切り替えをキャンセルします。3485`PreModelSwitch` フックは、切り替えをキャンセルしたり、ユーザーに確認を求めたり、続行させたりできます。終了コード 2 またはトップレベルの `decision: "block"` で切り替えがキャンセルされます。
3486 3486
3487より細かく制御するには、[PreToolUse](#pretooluse-decision-control) と同様に、`hookSpecificOutput` オブジェクト内で `permissionDecision` と `permissionDecisionReason` を返します。`PreModelSwitch` は `"allow"`、`"deny"`、`"ask"` を受け付けます。`"defer"`、`updatedInput`、`additionalContext` は受け付けません。次の表で両方のフィールドについて説明します。3487より細かく制御するには、[PreToolUse](#pretooluse-decision-control) と同様に、`hookSpecificOutput` オブジェクト内で `permissionDecision` と `permissionDecisionReason` を返します。`PreModelSwitch` は `"allow"`、`"deny"`、`"ask"` を受け付けます。`"defer"`、`updatedInput`、`additionalContext` は受け付けません。次の表で両方のフィールドを説明します。
3488 3488
3489| フィールド | 説明 |3489| フィールド | 説明 |
3490| :- | :- |3490| :- | :- |
3491| `permissionDecision` | `"allow"` は切り替えを続行し、[プロンプトキャッシュがウォーム状態のときに Claude Code が表示する確認](/docs/ja/prompt-caching#switching-models)をスキップします。`"deny"` は切り替えをキャンセルします。`"ask"` はユーザーに確認を求めます |3491| `permissionDecision` | `"allow"` は続行し、[プロンプトキャッシュがウォームな間に Claude Code が表示する確認](/docs/ja/prompt-caching#switching-models)をスキップします。`"deny"` は切り替えをキャンセルします。`"ask"` はユーザーに確認を求めます |
3492| `permissionDecisionReason` | `"deny"` の場合、切り替えがブロックされた理由としてユーザーに表示されるか、`set_model` リクエストのエラーとして返されます。`"ask"` の場合、確認プロンプトに表示されます。`"allow"` の場合は無視されます |3492| `permissionDecisionReason` | `"deny"` の場合、切り替えがブロックされた理由としてユーザーに表示されるか、`set_model` リクエストに対するエラーとして返されます。`"ask"` の場合、確認プロンプトに表示されます。`"allow"` の場合は無視されます |
3493 3493
3494`"ask"` のプロンプトを表示できるのは、対話セッションでの `/model` のみです。`-p` フラグを使用した非対話モード、`/config`、`set_model` リクエストを含むその他すべてのサーフェスでは、Claude Code は `"ask"` を拒否として扱います。3494`"ask"` のプロンプトを表示できるのは、対話セッションでの `/model` だけです。`-p` フラグを使用した非対話モード、`/config`、`set_model` リクエストなど、その他のすべてのサーフェスでは、Claude Code は `"ask"` を拒否として扱います。
3495 3495
3496次の例では、ユーザーに確認を求め、`context_tokens` のトークン数を示しています。3496次の例では、`context_tokens` のトークン数を示してユーザーに確認を求めます。
3497 3497
3498```json theme={null}3498```json theme={null}
3499{3499{
3507 3507
3508複数の PreModelSwitch フックが異なる判定を返した場合、優先順位は `deny` > `ask` > `allow` です。3508複数の PreModelSwitch フックが異なる判定を返した場合、優先順位は `deny` > `ask` > `allow` です。
3509 3509
3510Claude Code は判定にかかわらず、フックが返した `systemMessage` をユーザーに表示します。そのため、コストを報告するフックは `{"systemMessage": "..."}` を返して 0 で終了できます。3510Claude Code は判定に関係なく、フックが返した `systemMessage` をユーザーに表示します。そのため、コストを報告するフックは `{"systemMessage": "..."}` を返して 0 で終了できます。
3511 3511
3512タイムアウトまでに応答しない PreModelSwitch フックは、切り替えをブロックします。対照的に、[PreToolUse](#timeouts) では、タイムアウトしたコマンドフックはツール呼び出しを続行させます。このイベントのデフォルトのタイムアウトは 30 秒です。`PreModelSwitch` は `command`、`http`、`mcp_tool` フックのみを実行するため、`prompt` と `agent` のデフォルトは適用されません。3512タイムアウトまでに応答しない PreModelSwitch フックは、切り替えをブロックします。これに対して [PreToolUse](#timeouts) では、タイムアウトしたコマンドフックはツール呼び出しを続行させます。このイベントのデフォルトのタイムアウトは 30 秒です。`PreModelSwitch` は `command`、`http`、`mcp_tool` フックのみを実行するため、`prompt` と `agent` のデフォルトは適用されません。
3513 3513
35140 または 2 以外のコードで終了し、JSON の判定を出力しないフックはブロックしません。[その他の終了コード](#other-exit-codes)で説明されているとおり、Claude Code はその stderr を表示して切り替えを適用します。35140 と 2 以外のコードで終了し、JSON の判定を出力しないフックはブロックしません。[その他の終了コード](#other-exit-codes)で説明されているように、Claude Code はその stderr を表示して切り替えを適用します。
3515 3515
3516<h3 id="postmodelswitch">3516<h3 id="postmodelswitch">
3517 PostModelSwitch3517 PostModelSwitch
3518</h3>3518</h3>
3519 3519
3520セッションのモデルが変更された後に実行されます。特定のモデルに適用される組織全体の指示など、すべての CLAUDE.md を編集することなく、Claude にモデル固有のガイダンスを与えるために使用します。3520セッションのモデルが変更された後に実行されます。すべての CLAUDE.md を編集することなく、Claude にモデル固有のガイダンスを与えるために使用します。たとえば、特定のモデルに適用される組織全体の指示などです。
3521 3521
3522PostModelSwitch には Claude Code v2.1.251 以降が必要です。モデルはすでに変更されているため、ブロックすることはできません。Claude Code は、次のいずれかの変更の後に PostModelSwitch フックを実行します。3522PostModelSwitch には Claude Code v2.1.251 以降が必要です。モデルはすでに変更されているため、ブロックすることはできません。Claude Code は次のいずれかの変更の後に PostModelSwitch フックを実行します。
3523 3523
3524* ユーザーまたはクライアントが要求した切り替え3524* ユーザーまたはクライアントが要求した切り替え
3525* セッションのモデルを変更する[モデルの自動フォールバック](/docs/ja/model-config#automatic-model-fallback)3525* セッションのモデルを変更する[自動モデルフォールバック](/docs/ja/model-config#automatic-model-fallback)
3526* [`opusplan`](/docs/ja/model-config#opusplan-model-setting) などの設定による plan モードへの移行または終了3526* [`opusplan`](/docs/ja/model-config#opusplan-model-setting) のような設定による plan モードへの移行または plan モードからの離脱
3527* セッション再開時に Claude Code がモデルを復元したとき3527* セッション再開時に Claude Code がモデルを復元したとき
3528 3528
3529[フォールバックモデルチェーン](/docs/ja/model-config#fallback-model-chains)のモデルがターンを処理した場合、PostModelSwitch フックは実行されません。この置き換えは 1 ターンのみ有効で、セッションのモデルは変更されないためです。3529[フォールバックモデルチェーン](/docs/ja/model-config#fallback-model-chains)のモデルがターンを処理する場合、その置き換えは 1 ターンだけでセッションのモデルは変わらないため、Claude Code は PostModelSwitch フックを実行しません。
3530 3530
3531matcher は [PreModelSwitch](#premodelswitch) と同じルールに従います。Claude Code は、matcher をセッションの切り替え先モデルの正規名と比較します。3531matcher は [PreModelSwitch](#premodelswitch) と同じルールに従います。Claude Code は、セッションの切り替え先モデルの正規名と matcher を比較します。
3532 3532
3533次の例では、セッションのモデルがいずれかの Opus モデルに変更されるたびにガイダンスを追加します。3533次の例では、セッションのモデルがいずれかの Opus モデルに変わるたびにガイダンスを追加します。
3534 3534
3535```json theme={null}3535```json theme={null}
3536{3536{
3550}3550}
3551```3551```
3552 3552
3553フックが機能することを確認するには、別のモデルで実行中のセッションから Opus モデルに切り替え（たとえば Sonnet セッションから `/model opus` を実行）、現在のモデルについてどのようなガイダンスがあるかを Claude に尋ねます。3553フックが動作することを確認するには、別のモデルを実行しているセッションから Opus モデルに切り替え（たとえば Sonnet のセッションから `/model opus` を実行し）、現在のモデルについてどのようなガイダンスがあるかを Claude に尋ねます。
3554 3554
3555<h4 id="postmodelswitch-input">3555<h4 id="postmodelswitch-input">
3556 PostModelSwitch の入力3556 PostModelSwitch の入力
3557</h4>3557</h4>
3558 3558
3559PostModelSwitch フックは [PreModelSwitch](#premodelswitch-input) と同じフィールドを受け取ります。ただし、`hook_event_name` は `"PostModelSwitch"` に設定され、`source` には 2 つの値が追加されます。自動フォールバックや Claude Code が独自に行ったその他の変更の場合は `"auto"`、セッション再開時に復元されたモデルの場合は `"resume"` です。3559PostModelSwitch フックは [PreModelSwitch](#premodelswitch-input) と同じフィールドを受け取ります。ただし、`hook_event_name` は `"PostModelSwitch"` に設定され、`source` には 2 つの値が追加されます。自動フォールバックなど Claude Code 自身が行った変更を表す `"auto"` と、セッション再開時に復元されたモデルを表す `"resume"` です。
3560 3560
3561`source` が `"auto"` の場合、`requested_model` は `null` です。`source` が `"resume"` の場合は、Claude Code が復元した保存済みのモデル設定です。3561`source` が `"auto"` の場合、`requested_model` は `null` です。`source` が `"resume"` の場合は、Claude Code が復元した保存済みのモデル設定です。
3562 3562
3563<h4 id="postmodelswitch-decision-control">3563<h4 id="postmodelswitch-decision-control">
3564 PostModelSwitch の判定制御3564 PostModelSwitch の判定の制御
3565</h4>3565</h4>
3566 3566
3567Claude Code は、終了コード 0 の場合のフックの[プレーンテキストの stdout](#exit-code-0)、または JSON 出力の `additionalContext` を取得し、切り替え後の次のリクエストとともに Claude に渡します。すべてのフックで使用できる [JSON 出力フィールド](#json-output)に加えて、次のフィールドを返すことができます。3567Claude Code は、終了コード 0 の場合のフックの[プレーンテキストの stdout](#exit-code-0)、または JSON 出力の `additionalContext` を受け取り、切り替え後の次のリクエストで Claude に渡します。すべてのフックで使用できる [JSON 出力フィールド](#json-output)に加えて、次のフィールドを返すことができます。
3568 3568
3569| フィールド | 説明 |3569| フィールド | 説明 |
3570| :- | :- |3570| :- | :- |
3571| `additionalContext` | 次のリクエストで Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |3571| `additionalContext` | 次のリクエストで Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
3572 3572
3573次のプロンプトを送信してから 5 秒以内にフックが完了しない場合、Claude Code は出力なしでそのリクエストを送信し、代わりにその次のリクエストに出力を添付します。次のリクエストまでにモデルが複数回変更された場合、Claude Code は最後の切り替え先モデルの出力のみを渡します。3573次のプロンプトを送信してから 5 秒以内にフックが完了しない場合、Claude Code はその出力なしでリクエストを送信し、代わりにその次のリクエストに出力を添付します。次のリクエストまでにモデルが複数回変更された場合、Claude Code は最後の切り替え先モデルの出力のみを渡します。
3574 3574
3575<h3 id="sessionend">3575<h3 id="sessionend">
3576 SessionEnd3576 SessionEnd
3577</h3>3577</h3>
3578 3578
3579Claude Code セッションが終了するときに実行されます。クリーンアップタスク、セッション統計のログ記録、セッション状態の保存に役立ちます。終了理由でフィルタリングするための matcher をサポートしています。3579Claude Code セッションが終了するときに実行されます。クリーンアップタスク、セッション統計のログ記録、セッション状態の保存に便利です。終了理由でフィルタリングするための matcher をサポートしています。
3580 3580
3581フック入力の `reason` フィールドは、セッションが終了した理由を示します。3581フック入力の `reason` フィールドは、セッションが終了した理由を示します。
3582 3582
3605}3605}
3606```3606```
3607 3607
3608SessionEnd フックには判定の制御がありません。セッションの終了をブロックすることはできませんが、クリーンアップタスクを実行できます。Claude Code は、`systemMessage` などの [JSON 出力フィールド](#json-output)を破棄します。3608SessionEnd フックには判定の制御はありません。セッションの終了をブロックすることはできませんが、クリーンアップタスクを実行できます。Claude Code は、`systemMessage` などの [JSON 出力フィールド](#json-output)を破棄します。
3609 3609
3610SessionEnd フックのデフォルトのタイムアウトは 1.5 秒です。これは、終了したとき、`/clear` を実行したとき、または対話的な `/resume` でセッションを切り替えたときに適用されます。フックにより多くの時間を与えるには、次の 2 つの方法があります。3610SessionEnd フックのデフォルトのタイムアウトは 1.5 秒です。これは、終了するとき、`/clear` を実行するとき、または対話的な `/resume` でセッションを切り替えるときに適用されます。フックにより多くの時間を与えるには、次の 2 つの方法があります。
3611 3611
3612* **フックごとの `timeout`**：そのフックの設定で `timeout` を設定します。全体の上限時間は、設定ファイル内のフックごとの `timeout` の最大値に合わせて、最大 60 秒まで自動的に引き上げられます。この方法で上限時間を引き上げても、独自の `timeout` を持たないフックはデフォルトのままです。プラグインが提供するフックに設定されたタイムアウトは、上限時間を引き上げません。3612* **フックごとの `timeout`**: そのフックの設定で `timeout` を指定します。全体の制限時間は、設定ファイル内で最も大きいフックごとの `timeout` に合わせて、最大 60 秒まで自動的に引き上げられます。この方法で制限時間を引き上げても、独自の `timeout` を持たないフックはデフォルトのままです。プラグインが提供するフックに設定されたタイムアウトは、制限時間を引き上げません。
3613* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**：この環境変数をミリ秒単位で設定すると、上限時間を明示的に上書きできます。設定した値は、独自の `timeout` を持たない各フックのタイムアウトにもなります。3613* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: この環境変数をミリ秒単位で設定すると、制限時間を明示的に上書きできます。設定した値は、独自の `timeout` を持たない各フックのタイムアウトにもなります。
3614 3614
3615次の例では、上限時間を 5 秒に設定します。3615次の例では、制限時間を 5 秒に設定します。
3616 3616
3617```bash theme={null}3617```bash theme={null}
3618CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3618CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
3619```3619```
3620 3620
3621v2.1.268 より前は、`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` は全体の上限時間のみを引き上げ、独自の `timeout` を持たないフックは引き続き 1.5 秒後にキャンセルされていました。3621v2.1.268 より前は、`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` は全体の制限時間のみを引き上げ、独自の `timeout` を持たないフックは引き続き 1.5 秒後にキャンセルされていました。
3622 3622
3623<h3 id="elicitation">3623<h3 id="elicitation">
3624 Elicitation3624 Elicitation
3634 3634
3635[共通の入力フィールド](#common-input-fields)に加えて、Elicitation フックは `mcp_server_name`、`message`、およびオプションの `mode`、`url`、`elicitation_id`、`requested_schema` フィールドを受け取ります。3635[共通の入力フィールド](#common-input-fields)に加えて、Elicitation フックは `mcp_server_name`、`message`、およびオプションの `mode`、`url`、`elicitation_id`、`requested_schema` フィールドを受け取ります。
3636 3636
3637最も一般的なケースであるフォームモードの elicitation の場合：3637最も一般的なケースであるフォームモードの elicitation の場合:
3638 3638
3639```json theme={null}3639```json theme={null}
3640{3640{
3654}3654}
3655```3655```
3656 3656
3657ブラウザベースの認証に使用される URL モードの elicitation の場合：3657ブラウザベースの認証に使用される URL モードの elicitation の場合:
3658 3658
3659```json theme={null}3659```json theme={null}
3660{3660{
3689 3689
3690| フィールド | 値 | 説明 |3690| フィールド | 値 | 説明 |
3691| :- | :- | :- |3691| :- | :- | :- |
3692| `action` | `accept`、`decline`、`cancel` | リクエストを受け入れるか、拒否するか、キャンセルするか |3692| `action` | `accept`、`decline`、`cancel` | リクエストを承諾、拒否、またはキャンセルするかどうか |
3693| `content` | object | 送信するフォームフィールドの値。`action` が `accept` の場合にのみ使用されます |3693| `content` | object | 送信するフォームフィールドの値。`action` が `accept` の場合にのみ使用されます |
3694 3694
3695終了コード 2 は elicitation を拒否します。Claude Code は stderr のメッセージをどこにも表示しません。3695終了コード 2 は elicitation を拒否します。Claude Code は stderr のメッセージをどこにも表示しません。
3696 3696
3697Claude Code は Elicitation フックの JSON 出力のうち `hookSpecificOutput` に従って動作し、`systemMessage` と `continue` は破棄します。3697Claude Code は Elicitation フックの JSON 出力の `hookSpecificOutput` に基づいて動作し、`systemMessage` と `continue` は破棄します。
3698 3698
3699<h3 id="elicitationresult">3699<h3 id="elicitationresult">
3700 ElicitationResult3700 ElicitationResult
3747 3747
3748終了コード 2 は応答をブロックし、実際のアクションを `decline` に変更します。Claude Code は stderr のメッセージをどこにも表示しません。3748終了コード 2 は応答をブロックし、実際のアクションを `decline` に変更します。Claude Code は stderr のメッセージをどこにも表示しません。
3749 3749
3750Claude Code は ElicitationResult フックの JSON 出力のうち `hookSpecificOutput` に従って動作し、`systemMessage` と `continue` は破棄します。3750Claude Code は ElicitationResult フックの JSON 出力の `hookSpecificOutput` に基づいて動作し、`systemMessage` と `continue` は破棄します。
3751 3751
3752<h2 id="prompt-based-hooks">3752<h2 id="prompt-based-hooks">
3753 プロンプト ベースのフック3753 プロンプト ベースのフック
