7> Claude Code のフック イベント、設定スキーマ、JSON 入出力形式、終了コード、非同期フック、HTTP フック、プロンプト フック、MCP ツール フックのリファレンス。7> Claude Code のフック イベント、設定スキーマ、JSON 入出力形式、終了コード、非同期フック、HTTP フック、プロンプト フック、MCP ツール フックのリファレンス。
8 8
9<Tip>9<Tip>
10 例を含むクイックスタート ガイドについては、[ワークフローをフックで自動化する](/docs/ja/hooks-guide)を参照してください。10 例を含むクイックスタート ガイドについては、[フックでアクションを自動化する](/docs/ja/hooks-guide)を参照してください。
11</Tip>11</Tip>
12 12
13フックは、Claude Code のライフサイクル内の特定のポイントで自動的に実行されるユーザー定義のシェル コマンド、HTTP エンドポイント、または LLM プロンプトです。このリファレンスを使用して、イベント スキーマ、設定オプション、JSON 入出力形式、非同期フック、HTTP フック、MCP ツール フックなどの高度な機能を検索してください。初めてフックを設定する場合は、代わりに[ガイド](/docs/ja/hooks-guide)から始めてください。13フックは、Claude Code のライフサイクル内の特定のポイントで自動的に実行されるユーザー定義のシェル コマンド、HTTP エンドポイント、MCP ツール呼び出し、LLM プロンプト、またはサブエージェントです。Claude Code は、ターミナルでのセッション、IDE 拡張機能、[デスクトップアプリ](/docs/ja/desktop-quickstart)、[クラウドセッション](/docs/ja/claude-code-on-the-web)など、どこで実行されていても同じフック イベントを発火します。このリファレンスを使用して、イベント スキーマ、設定オプション、JSON 入出力形式、非同期フック、HTTP フック、MCP ツール フックなどの高度な機能を検索してください。
14
15プラグインは、Claude Code が自身のプロセス内で呼び出す JavaScript 関数としてフックを登録することもでき、これによりイベントに応じて動作するだけでなく、インターフェースに描画することもできます。そうしたプラグインは [mod](/docs/ja/plugins/mods/overview) であり、それらの関数フックについてはここではなく[イベントに反応する](/docs/ja/plugins/mods/events)で説明しています。このページで説明するフックは、mod と併用しても引き続き動作します。
14 16
15<h2 id="hook-lifecycle">17<h2 id="hook-lifecycle">
16 フック ライフサイクル18 フック ライフサイクル
17</h2>19</h2>
18 20
19フックは Claude Code セッション中の特定のポイントで発火します。イベントが発火してマッチャーがマッチすると、Claude Code はイベントに関する JSON コンテキストをフック ハンドラーに渡します。コマンド フックの場合、入力は stdin に到着します。HTTP フックの場合、POST リクエスト本体として到着します。ハンドラーは入力を検査し、アクションを実行し、オプションで決定を返すことができます。21Claude Code は、セッション中の特定のポイントでフックを実行します。イベントが発火して matcher がマッチすると、Claude Code はイベントに関する JSON コンテキストをフック ハンドラーに渡します。コマンド フックの場合、入力は stdin に到着します。HTTP フックの場合、POST リクエスト本体として到着します。ハンドラーは入力を検査し、アクションを実行し、オプションで決定を返すことができます。
20 22
21イベントは 3 つのケイデンスに分類されます。23イベントは 3 つのケイデンスに分類されます。
22 24
23* セッションごとに 1 回：`SessionStart` と `SessionEnd`25* セッションごとに 1 回：`SessionStart` と `SessionEnd`
24* ターンごとに 1 回：`UserPromptSubmit`、`Stop`、`StopFailure`26* ターンごとに 1 回：`UserPromptSubmit`、`Stop`、`StopFailure`
25* agentic ループ内のすべてのツール呼び出しで：`PreToolUse` と `PostToolUse`27* エージェント型ループ内のすべてのツール呼び出しで：`PreToolUse` と `PostToolUse`。ただし、[`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) の呼び出しは両方をスキップします
26 28
27<div style={{maxWidth: "500px", margin: "0 auto"}}>29<div style={{maxWidth: "500px", margin: "0 auto"}}>
28 <Frame>30 <Frame>
29 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=81b9256c1bbe8832553485f5d9e9c746" alt="オプションの Setup から SessionStart に流れ込み、その後、UserPromptSubmit、スラッシュ コマンド用の UserPromptExpansion、ネストされた agentic ループ（PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、PostToolBatch、SubagentStart/Stop、TaskCreated、TaskCompleted）、Stop または StopFailure を含むターンごとのループ、その後 TeammateIdle、PreCompact、PostCompact、SessionEnd が続き、Elicitation と ElicitationResult は MCP ツール実行内にネストされ、PermissionDenied は PermissionRequest からの副分岐として自動モード拒否のため、WorktreeCreate、WorktreeRemove、Notification、ConfigChange、InstructionsLoaded、CwdChanged、FileChanged はスタンドアロン非同期イベントとして表示されるフック ライフサイクル図" width="520" height="1336" data-path="images/hooks-lifecycle.svg" />31 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=81b9256c1bbe8832553485f5d9e9c746" className="dark:hidden" alt="オプションの Setup から SessionStart に流れ込み、その後、UserPromptSubmit、スラッシュコマンド用の UserPromptExpansion、ネストされたエージェント型ループ（PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、PostToolBatch、SubagentStart/Stop、TaskCreated、TaskCompleted）、Stop または StopFailure を含むターンごとのループ、その後 TeammateIdle、PreCompact、PostCompact、SessionEnd が続くことを示すフック ライフサイクル図。Elicitation と ElicitationResult は MCP ツール実行内にネストされ、PermissionDenied は auto モードでの拒否のための PermissionRequest からの副分岐、WorktreeCreate、WorktreeRemove、Notification、ConfigChange、InstructionsLoaded、CwdChanged、FileChanged、DirectoryAdded はスタンドアロンの非同期イベント、PreModelSwitch は要求されたモデル切り替えの前に実行されるスタンドアロンの逐次イベント、PostModelSwitch はセッションのモデルが変更された後に実行されるスタンドアロンの非同期イベント、MessageDisplay はアシスタントのメッセージ テキストのストリーミング中に実行される表示専用イベントとして示されています" width="520" height="1336" data-path="images/hooks-lifecycle.svg" />
32
33 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle-dark.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=c9b3d88487335f58cce0b52e2f9e7531" className="hidden dark:block" alt="オプションの Setup から SessionStart に流れ込み、その後、UserPromptSubmit、スラッシュコマンド用の UserPromptExpansion、ネストされたエージェント型ループ（PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、PostToolBatch、SubagentStart/Stop、TaskCreated、TaskCompleted）、Stop または StopFailure を含むターンごとのループ、その後 TeammateIdle、PreCompact、PostCompact、SessionEnd が続くことを示すフック ライフサイクル図。Elicitation と ElicitationResult は MCP ツール実行内にネストされ、PermissionDenied は auto モードでの拒否のための PermissionRequest からの副分岐、WorktreeCreate、WorktreeRemove、Notification、ConfigChange、InstructionsLoaded、CwdChanged、FileChanged、DirectoryAdded はスタンドアロンの非同期イベント、PreModelSwitch は要求されたモデル切り替えの前に実行されるスタンドアロンの逐次イベント、PostModelSwitch はセッションのモデルが変更された後に実行されるスタンドアロンの非同期イベント、MessageDisplay はアシスタントのメッセージ テキストのストリーミング中に実行される表示専用イベントとして示されています" width="520" height="1336" data-path="images/hooks-lifecycle-dark.svg" />
30 </Frame>34 </Frame>
31</div>35</div>
32 36
33以下の表は、各イベントがいつ発火するかをまとめています。[フック イベント](#hook-events)セクションでは、各イベントの完全な入力スキーマと決定制御オプションについて説明しています。37以下の表は、各イベントがいつ発火するかをまとめています。[フック イベント](#hook-events)セクションでは、各イベントの完全な入力スキーマと決定制御オプションについて説明しています。
34 38
35| Event | When it fires |39| イベント | 発火するタイミング |
36| :- | :- |40| :- | :- |
37| `SessionStart` | When a session begins or resumes |41| `SessionStart` | セッションが開始または再開されたとき |
38| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |42| `Setup` | `--init-only` で Claude Code を起動するとき、または `-p` モードで `--init` または `--maintenance` を使用するとき。CI またはスクリプトでの 1 回限りの準備用 |
39| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |43| `UserPromptSubmit` | プロンプトを送信するとき、Claude が処理する前 |
40| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |44| `UserPromptExpansion` | ユーザーが入力したコマンドがプロンプトに展開されるとき、Claude に到達する前。展開をブロックできます |
41| `PreToolUse` | Before a tool call executes. Can block it |45| `PreToolUse` | ツール呼び出しが実行される前。ブロックできます |
42| `PermissionRequest` | When a tool call needs a permission decision |46| `PermissionRequest` | ツール呼び出しが権限決定を必要とするとき |
43| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict |47| `PermissionDenied` | オートモードがツール呼び出しを拒否するとき、分類器の判定がない拒否を含みます。JSON `hookSpecificOutput.retry: true` を使用して、モデルが拒否されたツール呼び出しを再試行できることを伝えます。Claude Code は分類器が判定を出さなかった場合、`retry` を無視します |
44| `PostToolUse` | After a tool call succeeds |48| `PostToolUse` | ツール呼び出しが成功した後 |
45| `PostToolUseFailure` | After a tool call fails |49| `PostToolUseFailure` | ツール呼び出しが失敗した後 |
46| `PostToolBatch` | After a full batch of parallel tool calls resolves, before the next model call |50| `PostToolBatch` | 並列ツール呼び出しの完全なバッチが解決した後、次のモデル呼び出しの前 |
47| `Notification` | When Claude Code sends a notification |51| `Notification` | Claude Code が通知を送信するとき |
48| `MessageDisplay` | While assistant message text is displayed |52| `MessageDisplay` | アシスタントメッセージテキストが表示されている間 |
49| `SubagentStart` | When a subagent is spawned |53| `SubagentStart` | サブエージェントがスポーンされるとき |
50| `SubagentStop` | When a subagent finishes |54| `SubagentStop` | サブエージェントが終了するとき |
51| `TaskCreated` | When a task is being created via `TaskCreate` |55| `TaskCreated` | `TaskCreate` 経由でタスクが作成されるとき |
52| `TaskCompleted` | When a task is being marked as completed |56| `TaskCompleted` | タスクが完了としてマークされるとき |
53| `Stop` | When Claude finishes responding |57| `Stop` | Claude が応答を終了するとき |
54| `StopFailure` | When the turn ends due to an API error |58| `StopFailure` | API エラーが原因でターンが終了するとき |
55| `TeammateIdle` | When an [agent team](/docs/en/agent-teams) teammate is about to go idle |59| `TeammateIdle` | [エージェントチーム](/docs/ja/agent-teams) のチームメイトがアイドル状態になろうとするとき |
56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |60| `InstructionsLoaded` | CLAUDE.md または `.claude/rules/*.md` ファイルがコンテキストに読み込まれるとき。セッション開始時およびセッション中にファイルが遅延読み込みされるときに発火します |
57| `ConfigChange` | When a configuration file changes during a session |61| `ConfigChange` | セッション中に設定ファイルが変更されるとき |
58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |62| `CwdChanged` | 作業ディレクトリが変更されるとき、例えば Claude が `cd` コマンドを実行するとき。direnv などのツールを使用したリアクティブな環境管理に便利です |
59| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request |63| `DirectoryAdded` | `/add-dir` または SDK `register_repo_root` コントロールリクエスト経由でセッション中盤に作業ディレクトリが追加されるとき |
60| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |64| `FileChanged` | 監視対象ファイルがディスク上で変更されるとき。`matcher` フィールドは監視するファイル名を指定します |
61| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |65| `WorktreeCreate` | `--worktree`、`isolation: "worktree"`、またはバックグラウンドセッション経由で worktree が作成されるとき。デフォルトの git 動作を置き換えます |
62| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |66| `WorktreeRemove` | セッション終了時、サブエージェント終了時、またはバックグラウンドセッションを削除するときに worktree が削除されるとき |
63| `PreCompact` | Before context compaction |67| `PreCompact` | コンテキスト圧縮の前 |
64| `PostCompact` | After context compaction completes |68| `PostCompact` | コンテキスト圧縮が完了した後 |
65| `PreModelSwitch` | Before Claude Code applies a model switch that you or a client requested. Can block the switch |69| `PreModelSwitch` | Claude Code があなたまたはクライアントがリクエストしたモデルスイッチを適用する前。スイッチをブロックできます |
66| `PostModelSwitch` | After the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a session |70| `PostModelSwitch` | セッションのモデルが変更された後、Claude Code が独自に行う変更（セッションを再開するときのモデル復元など）を含みます |
67| `Elicitation` | When an MCP server requests user input during a tool call |71| `Elicitation` | MCP サーバーがツール呼び出し中にユーザー入力をリクエストするとき |
68| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |72| `ElicitationResult` | ユーザーが MCP エリシテーションに応答した後、レスポンスがサーバーに送り返される前 |
69| `SessionEnd` | When a session terminates |73| `SessionEnd` | セッションが終了するとき |
70 74
71<h3 id="how-a-hook-resolves">75<h3 id="how-a-hook-resolves">
72 フックがどのように解決されるか76 フックがどのように解決されるか
73</h3>77</h3>
74 78
75これらの部分がどのように組み合わさるかを理解するために、破壊的なシェル コマンドをブロックする `PreToolUse` フックを考えてみましょう。`matcher` は Bash ツール呼び出しに絞り込み、`if` 条件は `rm *` にマッチするコマンドにさらに絞り込むため、`block-rm.sh` は両方のフィルターがマッチするときのみ生成されます。79イベント、matcher、ハンドラーがどのように組み合わさるかを理解するために、破壊的なシェル コマンドをブロックする次の `PreToolUse` フックを考えてみましょう。
76 80
77```json theme={null}81<Tabs>
78{82 <Tab title="macOS/Linux">
83 `matcher` は Bash ツール呼び出しに絞り込み、`if` 条件は `rm *` にマッチする Bash サブコマンドにさらに絞り込むため、`block-rm.sh` は両方のフィルターがマッチするときのみ生成されます。
84
85 ```json theme={null}
86 {
79 "hooks": {87 "hooks": {
80 "PreToolUse": [88 "PreToolUse": [
81 {89 {
91 }99 }
92 ]100 ]
93 }101 }
94}102 }
95```103 ```
96 104
97スクリプトは stdin から JSON 入力を読み取り、コマンドを抽出し、`rm -rf` が含まれている場合は `permissionDecision` として `"deny"` を返します。105 スクリプトは stdin から JSON 入力を読み取り、コマンドを抽出し、`rm -rf` が含まれている場合は `permissionDecision` として `"deny"` を返します。Claude Code が実行できるように、プロジェクト内の `.claude/hooks/block-rm.sh` に保存し、`chmod +x .claude/hooks/block-rm.sh` で実行可能にしてください。
98 106
99```bash theme={null}107 ```bash theme={null}
100#!/bin/bash108 #!/bin/bash
101# .claude/hooks/block-rm.sh109 # .claude/hooks/block-rm.sh
102COMMAND=$(jq -r '.tool_input.command')110 COMMAND=$(jq -r '.tool_input.command')
103 111
104if echo "$COMMAND" | grep -q 'rm -rf'; then112 if echo "$COMMAND" | grep -q 'rm -rf'; then
105 jq -n '{113 jq -n '{
106 hookSpecificOutput: {114 hookSpecificOutput: {
107 hookEventName: "PreToolUse",115 hookEventName: "PreToolUse",
109 permissionDecisionReason: "Destructive command blocked by hook"117 permissionDecisionReason: "Destructive command blocked by hook"
110 }118 }
111 }'119 }'
112else120 else
113 exit 0 # no decision; normal permission flow applies121 exit 0 # no decision; normal permission flow applies
114fi122 fi
115```123 ```
124
125 このスクリプトは、JSON 入力を解析するこのページの他の Bash の例と同様に `jq` を使用します。試す前に `jq` をインストールし、`PATH` 上にあることを確認してください。
126 </Tab>
127
128 <Tab title="Windows (PowerShell)">
129 matcher `Bash|PowerShell` は、Bash に加えて [PowerShell ツール](#powershell)も対象にします。1 つの `if` ルールは 1 つのツールの呼び出しにしかマッチしないため、ツールごとに個別のハンドラーを用意します。1 つ目は `rm *` にマッチする Bash サブコマンドに、2 つ目は `Remove-Item *` にマッチする PowerShell コマンドに絞り込みます。どちらも `powershell.exe` を通じて同じスクリプトを実行します。
130
131 ```json theme={null}
132 {
133 "hooks": {
134 "PreToolUse": [
135 {
136 "matcher": "Bash|PowerShell",
137 "hooks": [
138 {
139 "type": "command",
140 "if": "Bash(rm *)",
141 "command": "powershell.exe",
142 "args": [
143 "-NoProfile",
144 "-ExecutionPolicy",
145 "Bypass",
146 "-File",
147 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
148 ]
149 },
150 {
151 "type": "command",
152 "if": "PowerShell(Remove-Item *)",
153 "command": "powershell.exe",
154 "args": [
155 "-NoProfile",
156 "-ExecutionPolicy",
157 "Bypass",
158 "-File",
159 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
160 ]
161 }
162 ]
163 }
164 ]
165 }
166 }
167 ```
168
169 `-NoProfile` フラグは PowerShell プロファイルの読み込みをスキップしてフックをすばやく起動させ、`-ExecutionPolicy Bypass` は PowerShell がローカルのスクリプト ファイルを実行できるようにします。
170
171 スクリプトは stdin から JSON 入力を読み取り、コマンドを抽出し、`rm -rf` または `-Recurse` が後に続く `Remove-Item` が含まれている場合は `permissionDecision` として `"deny"` を返します。プロジェクト内の `.claude/hooks/block-rm.ps1` に保存してください。
116 172
117ここで Claude Code が `Bash "rm -rf /tmp/build"` を実行することにしたとします。以下が起こります。173 ```powershell theme={null}
174 # .claude/hooks/block-rm.ps1
175 $callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
176 $command = $callInput.tool_input.command
177
178 if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
179 @{
180 hookSpecificOutput = @{
181 hookEventName = "PreToolUse"
182 permissionDecision = "deny"
183 permissionDecisionReason = "Destructive command blocked by hook"
184 }
185 } | ConvertTo-Json
186 } else {
187 exit 0 # no decision; normal permission flow applies
188 }
189 ```
190 </Tab>
191</Tabs>
192
193ここで、macOS/Linux の設定に対して Claude Code が `Bash "rm -rf /tmp/build"` を実行することにしたとします。以下が起こります。
118 194
119<Frame>195<Frame>
120 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" alt="フック解決フロー：PreToolUse イベントが発火し、マッチャーが Bash マッチをチェックし、if 条件が Bash(rm *) マッチをチェックし、フック ハンドラーが実行され、結果が Claude Code に返される" width="930" height="270" data-path="images/hook-resolution.svg" />196 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" className="dark:hidden" alt="フック解決の図：PreToolUse が発火し、matcher が Bash へのマッチをチェックし、次に if 条件が Bash(rm *) へのマッチをチェックします。両方がマッチすると、フック コマンドが実行されて permissionDecision として deny を返すため、ツール呼び出しはブロックされ、Claude Code は処理を続行します。いずれかのチェックがマッチしない場合、フックはスキップされ、ツール呼び出しの続行が許可されます。" width="930" height="270" data-path="images/hook-resolution.svg" />
197
198 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/hook-resolution-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=e80af91f8507cee6bd51ac3c2dd92f63" className="hidden dark:block" alt="フック解決の図：PreToolUse が発火し、matcher が Bash へのマッチをチェックし、次に if 条件が Bash(rm *) へのマッチをチェックします。両方がマッチすると、フック コマンドが実行されて permissionDecision として deny を返すため、ツール呼び出しはブロックされ、Claude Code は処理を続行します。いずれかのチェックがマッチしない場合、フックはスキップされ、ツール呼び出しの続行が許可されます。" width="930" height="270" data-path="images/hook-resolution-dark.svg" />
121</Frame>199</Frame>
122 200
123<Steps>201<Steps>
129 ```207 ```
130 </Step>208 </Step>
131 209
132 <Step title="マッチャーがチェック">210 <Step title="matcher がチェック">
133 マッチャー `"Bash"` がツール名にマッチするため、このフック グループがアクティブになります。マッチャーを省略するか `"*"` を使用すると、グループはイベントのすべての出現でアクティブになります。211 matcher `"Bash"` がツール名にマッチするため、このフック グループがアクティブになります。matcher を省略するか `"*"` を使用すると、グループはイベントのすべての出現でアクティブになります。
134 </Step>212 </Step>
135 213
136 <Step title="If 条件がチェック">214 <Step title="If 条件がチェック">
137 `if` 条件 `"Bash(rm *)"` は `rm -rf /tmp/build` が `rm *` にマッチするサブコマンドであるためマッチするため、このハンドラーが生成されます。コマンドが `npm test` だった場合、`if` チェックは失敗し、`block-rm.sh` は実行されず、プロセス生成のオーバーヘッドを回避します。`if` フィールドはオプションです。なければ、マッチしたグループ内のすべてのハンドラーが実行されます。215 `if` 条件 `"Bash(rm *)"` は `rm -rf /tmp/build` が `rm *` にマッチするサブコマンドであるためマッチし、このハンドラーが生成されます。コマンドが `npm test` だった場合、`if` チェックは失敗し、`block-rm.sh` は実行されず、プロセス生成のオーバーヘッドを回避します。`if` フィールドはオプションです。なければ、マッチしたグループ内のすべてのハンドラーが実行されます。
138 </Step>216 </Step>
139 217
140 <Step title="フック ハンドラーが実行">218 <Step title="フック ハンドラーが実行">
167フックは JSON 設定ファイルで定義されます。設定には 3 つのネストレベルがあります。245フックは JSON 設定ファイルで定義されます。設定には 3 つのネストレベルがあります。
168 246
1691. 応答する[フック イベント](#hook-events)を選択します（`PreToolUse` や `Stop` など）2471. 応答する[フック イベント](#hook-events)を選択します（`PreToolUse` や `Stop` など）
1702. 発火するタイミングをフィルタリングする[マッチャー グループ](#matcher-patterns)を追加します（「Bash ツールのみ」など）2482. 発火するタイミングをフィルタリングする [matcher グループ](#matcher-patterns)を追加します（「Bash ツールのみ」など）
1713. マッチしたときに実行する 1 つ以上の[フック ハンドラー](#hook-handler-fields)を定義します2493. マッチしたときに実行する 1 つ以上の[フック ハンドラー](#hook-handler-fields)を定義します
172 250
173完全なウォークスルーと注釈付きの例については、上記の[フックがどのように解決されるか](#how-a-hook-resolves)を参照してください。251完全なウォークスルーと注釈付きの例については、上記の[フックがどのように解決されるか](#how-a-hook-resolves)を参照してください。
174 252
175<Note>253<Note>
176 このページでは各レベルに特定の用語を使用しています。**フック イベント**はライフサイクル ポイント、**マッチャー グループ**はフィルター、**フック ハンドラー**はシェル コマンド、HTTP エンドポイント、MCP ツール、プロンプト、または実行されるエージェントです。「フック」単独は一般的な機能を指します。254 このページでは各レベルに特定の用語を使用しています。**フック イベント**はライフサイクル ポイント、**matcher グループ**はフィルター、**フック ハンドラー**はシェル コマンド、HTTP エンドポイント、MCP ツール、プロンプト、または実行されるエージェントです。「フック」単独は一般的な機能を指します。
177</Note>255</Note>
178 256
179<h3 id="hook-locations">257<h3 id="hook-locations">
186| :- | :- | :- |264| :- | :- | :- |
187| `~/.claude/settings.json` | すべてのプロジェクト | いいえ、マシンにローカル |265| `~/.claude/settings.json` | すべてのプロジェクト | いいえ、マシンにローカル |
188| `.claude/settings.json` | 単一プロジェクト | はい、リポジトリにコミット可能 |266| `.claude/settings.json` | 単一プロジェクト | はい、リポジトリにコミット可能 |
189| `.claude/settings.local.json` | 単一プロジェクト | いいえ、Claude Code が作成するときに gitignored |267| `.claude/settings.local.json` | 単一プロジェクト | いいえ、Claude Code が設定を保存する際に gitignore 対象になります |
190| 管理ポリシー設定 | 組織全体 | はい、管理者が制御 |268| 管理ポリシー設定 | 組織全体 | はい、管理者が制御 |
191| [プラグイン](/docs/ja/plugins) `hooks/hooks.json` | プラグインが有効な場合 | はい、プラグインにバンドル |269| [プラグイン](/docs/ja/plugins/overview) `hooks/hooks.json` | プラグインが有効な場合 | はい、プラグインにバンドル |
192| [スキル](/docs/ja/skills)または[エージェント](/docs/ja/sub-agents)フロントマター | コンポーネントがアクティブな場合 | はい、コンポーネント ファイルで定義 |270| [スキル](/docs/ja/skills)のフロントマター | スキルが呼び出された後のセッションの残りの期間。[スキルとエージェントのフック](#hooks-in-skills-and-agents)を参照 | はい、スキルファイルで定義 |
271| [サブエージェント](/docs/ja/sub-agents)のフロントマター | そのサブエージェントの実行中 | はい、サブエージェントファイルで定義 |
272
273[クラウドセッション](/docs/ja/claude-code-on-the-web)は、ローカルの `~/.claude/settings.json` を読み取りません。[セルフホスト環境](/docs/ja/self-hosted-environments-configuration#permissions-and-tool-approval)では、Claude Code はオペレーターがランナーホストの `~/.claude/` に用意したフックも実行します。また、ランナーイメージの管理設定ファイルが [Claude Code が適用する管理ソース](/docs/ja/managed-settings#how-claude-code-combines-managed-sources)に含まれる場合は、そのファイル内のフックも実行します。デフォルトでは、これはサーバー管理設定も MDM で配布された Claude Code ポリシーも管理層を提供していない場合に限られます。どの設定ファイルとプラグイン、つまりどのフックがクラウドセッションに届くかについては、[セットアップから引き継がれるもの](/docs/ja/cloud-environments#what-carries-over-from-your-setup)を参照してください。
274
275設定ファイル解決の詳細については、[設定](/docs/ja/settings)を参照してください。
276
277設定ファイル、管理ポリシー設定、プラグインからのフックは、[サブエージェント](/docs/ja/sub-agents)内でも実行されます。サブエージェントがツールを呼び出すと、`PreToolUse` や `PostToolUse` などのツールイベントはメインの会話と同じ設定済みフックを発火させ、入力にはサブエージェントを識別する `agent_id` と `agent_type` の[共通入力フィールド](#common-input-fields)が含まれます。
193 278
194設定ファイル解決の詳細については、[設定](/docs/ja/settings)を参照してください。エンタープライズ管理者は `allowManagedHooksOnly` を使用して、ユーザー、プロジェクト、プラグイン フックをブロックできます。管理設定で force-enabled されたプラグインからのフックは除外されるため、管理者は組織マーケットプレイスを通じて検証済みのフックを配布できます。[フック設定](/docs/ja/settings#hook-configuration)を参照してください。279管理者は[管理設定](/docs/ja/managed-settings)で [`allowManagedHooksOnly`](/docs/ja/settings-reference#allowmanagedhooksonly) を使用して、実行されるフックを制限できます。
280
281* ユーザー、プロジェクト、ローカル、プラグインのフックはブロックされます。管理設定の `enabledPlugins` で強制的に有効化されたプラグインのフックは除外されます
282* Claude Code は、[`statusLine`](/docs/ja/statusline)、[`fileSuggestion`](/docs/ja/settings-reference#filesuggestion)、[`subagentStatusLine`](/docs/ja/statusline#subagent-status-lines) の設定も管理設定のものに限定します
283* Claude Code は、[`command` ソース](/docs/ja/plugins/marketplace-reference#command-plugin-source)を持つプラグインも無効化します。これには管理設定の `enabledPlugins` で強制的に有効化されたプラグインも含まれます。ただし、[`disableCommandPluginSources`](/docs/ja/settings-reference#disablecommandpluginsources) が明示的に `false` に設定されている場合は除きます。`command` ソースには Claude Code v2.1.229 以降が必要です
284* Claude Code は、マーケットプレイスの [`headersHelper` コマンド](/docs/ja/plugins/host-marketplace#authenticate-archive-downloads)もブロックします。ただし、[`disableCommandPluginSources`](/docs/ja/settings-reference#disablecommandpluginsources) が明示的に `false` に設定されている場合は除きます。また、管理設定自体が宣言しているマーケットプレイスは対象外です
285
286[`allowManagedHooksOnly` の下で実行されるもの](/docs/ja/settings-reference#what-runs-under-allowmanagedhooksonly)を参照してください。
287
288フックエントリは、設定レベル間で互いに置き換えられるのではなくマージされます。ユーザー、プロジェクト、ローカルの設定は管理フックを削除せずに独自のフックを追加します。また、[`disableAllHooks`](#disable-or-remove-hooks) 設定は、管理設定の外からは管理フックを無効化できません。
289
290[HTTP フックの許可リスト](/docs/ja/settings-reference#hook-and-skill-settings)は、管理ポリシー設定を含むすべてのソースからのフックに適用されます。
291
292* `allowedHttpHookUrls`: いずれかの設定レベルで定義されている場合、Claude Code は URL がマージされた許可リストに一致する HTTP フックハンドラーのみを実行します
293* `httpHookAllowedEnvVars`: 定義されている場合、Claude Code はそのリストにある環境変数のみをフックヘッダーに補間します
195 294
196<h3 id="matcher-patterns">295<h3 id="matcher-patterns">
197 マッチャー パターン296 Matcher パターン
198</h3>297</h3>
199 298
200`matcher` フィールドは、フックが発火するタイミングをフィルタリングします。マッチャーの評価方法は、含まれている文字に依存します。299`matcher` フィールドは、フックが発火するタイミングをフィルタリングします。matcher の評価方法は、含まれている文字に依存します。
201 300
202| マッチャー値 | 評価方法 | 例 |301| matcher 値 | 評価方法 | 例 |
203| :- | :- | :- |302| :- | :- | :- |
204| `"*"`、`""`、または省略 | すべてにマッチ | イベントのすべての出現で発火 |303| `"*"`、`""`、または省略 | すべてにマッチ | イベントのすべての出現で発火 |
205| 文字、数字、`_`、`-`、スペース、`,`、`\|` のみ | 完全一致、または `\|` または `,` で区切られた完全一致のリスト（オプションで周囲の空白を含む） | `Bash` は Bash ツールのみにマッチ。`Edit\|Write` と `Edit, Write` はいずれかのツールに完全にマッチ。`code-reviewer` はそのエージェント タイプのみにマッチ |304| 文字、数字、`_`、`-`、スペース、`,`、`\|` のみ | 完全一致、または `\|` または `,` で区切られた完全一致のリスト（オプションで周囲の空白を含む） | `Bash` は Bash ツールのみにマッチ。`Edit\|Write` と `Edit, Write` はいずれかのツールに完全にマッチ。`code-reviewer` はそのエージェント タイプのみにマッチ |
206| その他の文字を含む | JavaScript 正規表現、アンカーなし | `^Notebook` は Notebook で始まるツールにマッチ。`mcp__memory__.*` は `memory` サーバーのすべてのツールにマッチ |305| その他の文字を含む | JavaScript 正規表現、アンカーなし | `^Notebook` は名前が `Notebook` で始まるツールにマッチ。`mcp__memory__.*` は `memory` サーバーのすべてのツールにマッチ |
207
208正規表現パス上のマッチャーは JavaScript の `RegExp.prototype.test` でテストされます。これは値内のどこかでマッチすると成功します。`Edit.*` は `Edit` と `NotebookEdit` の両方にマッチします。完全文字列マッチが必要な場合は、`^Edit$` のようにパターンを `^` と `$` でラップしてください。
209 306
210カンマ区切り文字と周囲の空白許容度には Claude Code v2.1.191 以降が必要です。307正規表現パス上の matcher は JavaScript の `RegExp.prototype.test` でテストされます。これは値内のどこかでマッチすると成功します。`Edit.*` は `Edit` と `NotebookEdit` の両方にマッチします。完全文字列マッチが必要な場合は、`^Edit$` のようにパターンを `^` と `$` でラップしてください。
211 308
212完全一致セット内のハイフンには Claude Code v2.1.195 以降が必要です。以前のバージョンでは、`code-reviewer` のようなハイフン付き名前はアンカーなしの正規表現として評価されるため、`senior-code-reviewer` でも発火します。これらのバージョンではそのような名前のみにマッチするように `^code-reviewer$` としてアンカーしてください。309`FileChanged` と `StopFailure` は、文字、数字、`_`、`|` のみの狭い完全一致セットを使用します。これら 2 つのイベントの matcher にハイフン、スペース、またはカンマがあると、正規表現パスに留まり、`|` のみが代替を区切ります。後続の表で matcher サポートを持つ他のすべてのイベントは `|` または `,` を受け入れます。
213
214`FileChanged` と `StopFailure` は、文字、数字、`_`、`|` のみの狭い完全一致セットを使用します。これら 2 つのイベントのマッチャーにハイフン、スペース、またはカンマがあると、正規表現パスに留まり、`|` のみが代替を区切ります。後続の表でマッチャー サポートを持つ他のすべてのイベントは `|` または `,` を受け入れます。
215 310
216`FileChanged` イベントは監視リストを構築するときにこれらのルールに従いません。[FileChanged](#filechanged)を参照してください。311`FileChanged` イベントは監視リストを構築するときにこれらのルールに従いません。[FileChanged](#filechanged)を参照してください。
217 312
218各イベント タイプは異なるフィールドでマッチします。313各イベント タイプは異なるフィールドでマッチします。
219 314
220| イベント | マッチャーがフィルタリングするもの | マッチャー値の例 |315| イベント | matcher がフィルタリングするもの | matcher 値の例 |
221| :- | :- | :- |316| :- | :- | :- |
222| `PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied` | ツール名 | `Bash`、`Edit\|Write`、`mcp__.*` |317| `PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied` | ツール名 | `Bash`、`Edit\|Write`、`mcp__.*` |
223| `SessionStart` | セッションの開始方法 | `startup`、`resume`、`clear`、`compact` |318| `SessionStart` | セッションの開始方法 | `startup`、`resume`、`clear`、`compact`、`fork` |
224| `Setup` | セットアップをトリガーした CLI フラグ | `init`、`maintenance` |319| `Setup` | セットアップをトリガーした CLI フラグ | `init`、`maintenance` |
225| `SessionEnd` | セッションが終了した理由 | `clear`、`resume`、`logout`、`prompt_input_exit`、`bypass_permissions_disabled`、`other` |320| `SessionEnd` | セッションが終了した理由 | `clear`、`resume`、`logout`、`prompt_input_exit`、`other` |
226| `Notification` | 通知タイプ | `permission_prompt`、`idle_prompt`、`auth_success`、`elicitation_dialog`、`elicitation_complete`、`elicitation_response`、`agent_needs_input`、`agent_completed` |321| `Notification` | 通知タイプ | `permission_prompt`、`idle_prompt`、`auth_success`、`elicitation_dialog`、`elicitation_url_dialog`、`elicitation_complete`、`elicitation_response`、`agent_needs_input`、`agent_completed`、`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled` |
227| `SubagentStart` | エージェント タイプ | `general-purpose`、`Explore`、`Plan`、カスタム エージェント名、またはプラグイン スコープ付き名前（`^my-plugin:reviewer$` など） |322| `SubagentStart` | エージェント タイプ | `general-purpose`、`Explore`、`Plan`、カスタム エージェント名、またはプラグイン スコープ付き名前（`^my-plugin:reviewer$` など） |
228| `PreCompact`、`PostCompact` | コンパクションをトリガーしたもの | `manual`、`auto` |323| `PreCompact`、`PostCompact` | コンテキスト圧縮をトリガーしたもの | `manual`、`auto` |
324| `PreModelSwitch`、`PostModelSwitch` | セッションの切り替え先モデルの正規名（[PreModelSwitch](#premodelswitch) で説明） | `claude-opus-5`、`claude-opus-4-6\|claude-opus-5`、`.*opus.*` |
229| `SubagentStop` | エージェント タイプ | `SubagentStart` と同じ値 |325| `SubagentStop` | エージェント タイプ | `SubagentStart` と同じ値 |
230| `ConfigChange` | 設定ソース | `user_settings`、`project_settings`、`local_settings`、`policy_settings`、`skills` |326| `ConfigChange` | 設定ソース | `user_settings`、`project_settings`、`local_settings`、`policy_settings`、`skills` |
231| `CwdChanged` | マッチャー サポートなし | すべてのディレクトリ変更で常に発火 |327| `CwdChanged` | matcher サポートなし | すべての出現で常に発火 |
328| `DirectoryAdded` | ディレクトリが追加された方法 | `slash_command`、`register_repo_root` |
232| `FileChanged` | 監視するリテラル ファイル名（[FileChanged](#filechanged)を参照） | `.envrc\|.env` |329| `FileChanged` | 監視するリテラル ファイル名（[FileChanged](#filechanged)を参照） | `.envrc\|.env` |
233| `StopFailure` | エラー タイプ | `rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`unknown` |330| `StopFailure` | エラー タイプ | `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` |
234| `InstructionsLoaded` | ロード理由 | `session_start`、`nested_traversal`、`path_glob_match`、`include`、`compact` |331| `InstructionsLoaded` | ロード理由 | `session_start`、`nested_traversal`、`path_glob_match`、`include`、`compact` |
235| `UserPromptExpansion` | コマンド名 | スキルまたはコマンド名 |332| `UserPromptExpansion` | コマンド名 | スキルまたはコマンド名 |
236| `Elicitation` | MCP サーバー名 | 設定された MCP サーバー名 |333| `Elicitation` | MCP サーバー名 | 設定された MCP サーバー名 |
237| `ElicitationResult` | MCP サーバー名 | `Elicitation` と同じ値 |334| `ElicitationResult` | MCP サーバー名 | `Elicitation` と同じ値 |
238| `UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`MessageDisplay` | マッチャー サポートなし | すべての出現で常に発火 |335| `UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`MessageDisplay` | matcher サポートなし | すべての出現で常に発火 |
336
337`StopFailure` を `cloud_credential_error` でマッチさせるには Claude Code v2.1.267 以降が必要です。これは、認証情報の読み込み失敗を `server_error` や `unknown` ではなくこの値で報告する最初のバージョンです。
239 338
240マッチャーは、Claude Code がフックに stdin で送信する[JSON 入力](#hook-input-and-output)からのフィールドに対して実行されます。ツール イベントの場合、そのフィールドは `tool_name` です。各[フック イベント](#hook-events)セクションでは、マッチャー値の完全なセットとそのイベントの入力スキーマをリストしています。339ほとんどのイベントでは、Claude Code は、フックに stdin で送信する [JSON 入力](#hook-input-and-output)のフィールドに対して matcher を評価します。ツール イベントの場合、そのフィールドは `tool_name` です。`PreModelSwitch` と `PostModelSwitch` では、[PreModelSwitch](#premodelswitch) で説明しているとおり、Claude Code は `to_model` から導出した正規名に対して matcher を評価します。各[フック イベント](#hook-events)セクションでは、matcher 値の完全なセットとそのイベントの入力スキーマをリストしています。
241 340
242この例は、Claude がファイルを書き込むまたは編集するときにのみ linting スクリプトを実行します。341この例は、Claude がファイルを書き込むまたは編集するときにのみ linting スクリプトを実行します。
243 342
259}358}
260```359```
261 360
262`UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`MessageDisplay`、`CwdChanged` はマッチャーをサポートせず、すべての出現で常に発火します。これらのイベントに `matcher` フィールドを追加すると、サイレントに無視されます。361matcher をサポートしないイベントに `matcher` フィールドを追加すると、サイレントに無視されます。
263 362
264ツール イベントの場合、個別のフック ハンドラーで [`if` フィールド](#common-fields)を設定することで、より狭くフィルタリングできます。`if` は[権限ルール構文](/docs/ja/permissions)を使用してツール名と引数を一緒にマッチするため、`"Bash(git *)"` は `git *` に一致する Bash 入力のサブコマンドのいずれかに対して実行され、`"Edit(*.ts)"` は TypeScript ファイルのみに対して実行されます。363ツール イベントの場合、個別のフック ハンドラーで [`if` フィールド](#common-fields)を設定することで、より狭くフィルタリングできます。`if` は[権限ルール構文](/docs/ja/permissions)を使用してツール名と引数を一緒にマッチするため、`"Bash(git *)"` は `git *` に一致する Bash 入力のサブコマンドのいずれかに対して実行され、`"Edit(*.ts)"` は TypeScript ファイルのみに対して実行されます。
265 364
275* `mcp__filesystem__read_file`: Filesystem サーバーの read file ツール374* `mcp__filesystem__read_file`: Filesystem サーバーの read file ツール
276* `mcp__github__search_repositories`: GitHub サーバーの search ツール375* `mcp__github__search_repositories`: GitHub サーバーの search ツール
277 376
278すべてのツールをサーバーからマッチするには、サーバー プレフィックスに `.*` を追加します。`.*` は必須です。`mcp__memory` のようなマッチャーは完全一致文字のみを含むため、完全一致として比較され、ツールにマッチしません。377サーバーのすべてのツールをマッチするには、サーバー プレフィックスに `.*` を追加します。`.*` は必須です。`mcp__memory` や `mcp__brave-search` のような matcher は完全一致文字のみを含むため、完全一致として比較され、どのツールにもマッチしません。
279 378
280* `mcp__memory__.*` は `memory` サーバーのすべてのツールにマッチ379* `mcp__memory__.*` は `memory` サーバーのすべてのツールにマッチ
281* `mcp__brave-search__.*` は名前にハイフンを含むサーバーのすべてのツールにマッチ380* `mcp__brave-search__.*` は名前にハイフンを含むサーバーのすべてのツールにマッチ
282* `mcp__.*__write.*` は任意のサーバーから「write」で始まるツールにマッチ381* `mcp__.*__write.*` は任意のサーバーの、名前が `write` で始まるツールにマッチ
283 382
284完全一致セット内のハイフンには Claude Code v2.1.195 以降が必要です。以前のバージョンでは、`mcp__brave-search` のようなベアのハイフン付きプレフィックスはアンカーなしの正規表現として評価され、そのサーバーのすべてのツールにマッチします。`mcp__brave-search__.*` 形式はすべてのバージョンで機能します。383[プラグイン バンドル MCP サーバー](/docs/ja/mcp#plugin-provided-mcp-servers)からのツールは、プラグイン名を含むスコープ付きサーバー セグメントを使用します。`mcp__plugin_<plugin-name>_<server-name>__<tool>`。ベア サーバー キーに対して記述された matcher は、これらのツールに対して発火しません。`db` キーの下でサーバーをバンドルする `my-plugin` という名前のプラグインの場合、`query` ツールは `mcp__plugin_my-plugin_db__query` として表示されるため、そのサーバーのすべてのツールの matcher は `mcp__plugin_my-plugin_db__.*` です。ハンドラーの [`if` フィールド](#common-fields)で同じスコープ付きツール名を使用します。スコープ付き名がどのように構築されるかについては、[プラグイン提供 MCP サーバー](/docs/ja/mcp#plugin-provided-mcp-servers)を参照してください。
285 384
286[プラグイン バンドル MCP サーバー](/docs/ja/mcp#plugin-provided-mcp-servers)からのツールは、プラグイン名を含むスコープ付きサーバー セグメントを使用します。`mcp__plugin_<plugin-name>_<server-name>__<tool>`。ベア サーバー キーに対して記述されたマッチャーは、これらのツールに対して発火しません。`db` キーの下でサーバーをバンドルする `my-plugin` という名前のプラグインの場合、`query` ツールは `mcp__plugin_my-plugin_db__query` として表示されるため、そのサーバーのすべてのツールのマッチャーは `mcp__plugin_my-plugin_db__.*` です。ハンドラーの [`if` フィールド](#common-fields)で同じスコープ付きツール名を使用します。スコープ付き名がどのように構築されるかについては、[プラグイン提供 MCP サーバー](/docs/ja/mcp#plugin-provided-mcp-servers)を参照してください。385この例は、すべてのメモリ サーバー操作をログに記録し、任意の MCP サーバーからの書き込み操作を検証します。
287
288この例は、すべてのメモリ サーバー操作をログし、任意の MCP サーバーからの書き込み操作を検証します。
289 386
290```json theme={null}387```json theme={null}
291{388{
318 フック ハンドラー フィールド415 フック ハンドラー フィールド
319</h3>416</h3>
320 417
321内側の `hooks` 配列の各オブジェクトはフック ハンドラーです。マッチャーがマッチしたときに実行されるシェル コマンド、HTTP エンドポイント、MCP ツール、LLM プロンプト、またはエージェントです。5 つのタイプがあります。418内側の `hooks` 配列の各オブジェクトはフック ハンドラーです。matcher がマッチしたときに実行されるシェル コマンド、HTTP エンドポイント、MCP ツール、LLM プロンプト、またはエージェントです。5 つのタイプがあります。
322 419
323* **[コマンド フック](#command-hook-fields)** （`type: "command"`）: シェル コマンドを実行します。スクリプトはイベントの[JSON 入力](#hook-input-and-output)を stdin で受け取り、終了コードと stdout を通じて結果を通信します。420* **[コマンド フック](#command-hook-fields)** （`type: "command"`）: シェル コマンドを実行します。スクリプトはイベントの [JSON 入力](#hook-input-and-output)を stdin で受け取り、終了コードと stdout を通じて結果を通信します。
324* **[HTTP フック](#http-hook-fields)** （`type: "http"`）: イベントの JSON 入力を HTTP POST リクエストとして URL に送信します。エンドポイントは、コマンド フックと同じ[JSON 出力形式](#json-output)を使用して、レスポンス本体を通じて結果を通信します。421* **[HTTP フック](#http-hook-fields)** （`type: "http"`）: イベントの JSON 入力を HTTP POST リクエストとして URL に送信します。エンドポイントは、コマンド フックと同じ [JSON 出力形式](#json-output)を使用して、レスポンス本体を通じて結果を通信します。
325* **[MCP ツール フック](#mcp-tool-hook-fields)** （`type: "mcp_tool"`）: 既に接続されている[MCP サーバー](/docs/ja/mcp)上のツールを呼び出します。ツールのテキスト出力はコマンド フック stdout のように扱われます。422* **[MCP ツール フック](#mcp-tool-hook-fields)** （`type: "mcp_tool"`）: 設定済みの [MCP サーバー](/docs/ja/mcp)上のツールを呼び出します。ツールのテキスト出力はコマンド フック stdout のように扱われます。
326* **[プロンプト フック](#prompt-and-agent-hook-fields)** （`type: "prompt"`）: Claude モデルにプロンプトを送信して、単一ターンの評価を行います。モデルは yes/no 決定を JSON として返します。[プロンプト ベースのフック](#prompt-based-hooks)を参照してください。423* **[プロンプト フック](#prompt-and-agent-hook-fields)** （`type: "prompt"`）: Claude モデルにプロンプトを送信して、単一ターンの評価を行います。モデルは決定を JSON として返します。[プロンプト ベースのフック](#prompt-based-hooks)を参照してください。
327* **[エージェント フック](#prompt-and-agent-hook-fields)** （`type: "agent"`）: Read、Grep、Glob などのツールを使用して条件を検証してから決定を返すことができるサブエージェントを生成します。エージェント フックは実験的であり、変更される可能性があります。[エージェント ベースのフック](#agent-based-hooks)を参照してください。424* **[エージェント フック](#prompt-and-agent-hook-fields)** （`type: "agent"`）: Read、Grep、Glob などのツールを使用して条件を検証してから決定を返すことができるサブエージェントを生成します。エージェント フックは実験的であり、変更される可能性があります。[エージェント ベースのフック](#agent-based-hooks)を参照してください。
328 425
329すべてのマッチング フックは並列で実行され、同一のハンドラーは自動的に重複排除されます。コマンド フックはコマンド文字列と `args` で重複排除され、HTTP フックは URL で重複排除されます。426マッチしたすべてのフックは並列で実行されます。同じハンドラーを複数の設定ファイルで定義した場合、実行は 1 回だけです。プラグインまたはスキルが持つ同じハンドラーのコピーは別個のものとして扱われます。
427
428ハンドラーは Claude Code の環境を持つ現在のディレクトリで実行されます。現在のディレクトリが存在しなくなった場合（たとえば、別のシェルがセッション中に削除した worktree や一時ディレクトリなど）、Claude Code は次のうち最初に存在するディレクトリからコマンドフックを実行します。セッションを開始したディレクトリ、プロジェクトルート、ホームディレクトリ、またはシステムの一時ディレクトリです。Claude Code は、フォールバック先のディレクトリ名を含む警告を[デバッグログ](#debug-hooks)に記録します。
330 429
331ハンドラーは Claude Code の環境を持つ現在のディレクトリで実行されます。`$CLAUDE_CODE_REMOTE` 環境変数はリモート Web 環境で `"true"` に設定され、ローカル CLI では設定されません。v2.1.199 以降、[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/ja/env-vars)は、ローカル セッションがアクティブな Remote Control 接続を持つ間、[Remote Control](/docs/ja/remote-control)セッション ID に設定されます。430`$CLAUDE_CODE_REMOTE` 環境変数はリモート Web 環境で `"true"` に設定され、ローカル CLI では設定されません。Claude Code v2.1.199 以降では、ローカルセッションにアクティブな Remote Control 接続がある間、[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/ja/env-vars) が [Remote Control](/docs/ja/remote-control) のセッション ID に設定されます。
332 431
333<h4 id="common-fields">432<h4 id="common-fields">
334 共通フィールド433 共通フィールド
339| フィールド | 必須 | 説明 |438| フィールド | 必須 | 説明 |
340| :- | :- | :- |439| :- | :- | :- |
341| `type` | はい | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"`、または `"agent"` |440| `type` | はい | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"`、または `"agent"` |
342| `if` | いいえ | `"Bash(git *)"` または `"Edit(*.ts)"` などの権限ルール構文を使用してこのフックが実行されるタイミングをフィルタリングします。ツール呼び出しがパターンにマッチする場合のみ、フック コマンドが実行されます。[Bash マッチング テーブル](#bash-if-matching)を参照して、Bash パターンがサブコマンド、`$()`、バッククォートに対してどのように評価されるかを確認してください。ツール イベントでのみ評価されます。`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied`。他のイベントでは、`if` が設定されたフックは実行されません。[権限ルール](/docs/ja/permissions)と同じ構文を使用します |441| `if` | いいえ | `"Bash(git *)"` または `"Edit(*.ts)"` などの権限ルール構文を使用してこのフックが実行されるタイミングをフィルタリングします。ツール呼び出しがパターンにマッチする場合のみ、フック コマンドが実行されます。Bash パターンがサブコマンド、`$()`、バッククォートに対してどのように評価されるかについては、後述の [Bash マッチング テーブル](#bash-if-matching)を参照してください。ツール イベントでのみ評価されます。`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied`。他のイベントでは、`if` が設定されたフックは実行されません。[権限ルール](/docs/ja/permissions)と同じ構文を使用します |
343| `timeout` | いいえ | キャンセルまでの秒数。デフォルト: `command`、`http`、`mcp_tool` は 600、`prompt` は 30、`agent` は 60。[`UserPromptSubmit`](#userpromptsubmit) は `command`、`http`、`mcp_tool` のデフォルトを 30 に低下させ、[`MessageDisplay`](#messagedisplay) はそれを 10 に低下させます |442| `timeout` | いいえ | キャンセルまでの秒数。[`async: true`](#run-hooks-in-the-background) で実行するコマンドフックには、Claude Code はこれを適用しません。デフォルト: `command`、`http`、`mcp_tool` は 600、`prompt` は 30、`agent` は 60。Claude Code は、[`UserPromptSubmit`](#userpromptsubmit)、[`PreModelSwitch`](#premodelswitch)、[`PostModelSwitch`](#postmodelswitch) では `command`、`http`、`mcp_tool` のデフォルトを 30 に、[`MessageDisplay`](#messagedisplay) では 10 に下げます。[`SessionEnd`](#sessionend) フックは 1.5 秒の予算を共有します。設定でフックごとにより長い `timeout` を指定している場合、Claude Code は最大 60 秒までそれに合わせて予算を引き上げます |
344| `statusMessage` | いいえ | フックの実行中に表示されるカスタム スピナー メッセージ |443| `statusMessage` | いいえ | フックの実行中に表示されるカスタム スピナー メッセージ |
345| `once` | いいえ | `true` の場合、セッションごとに 1 回だけ実行してから削除されます。[スキル フロントマター](#hooks-in-skills-and-agents)でのみ尊重されます。設定ファイルとエージェント フロントマターでは無視されます |444| `once` | いいえ | `true` の場合、Claude Code は最初の実行が成功した後にフックを削除します。失敗した実行、終了コード 2 でブロックした実行、またはタイムアウトした実行ではフックがそのまま残るため、次にマッチするイベントで再び実行されます。[スキルのフロントマター](#hooks-in-skills-and-agents)で宣言されたフックでのみ有効です。設定ファイルとエージェントのフロントマターでは無視されます |
346 445
347`if` フィールドは正確に 1 つの権限ルールを保持します。ルールを組み合わせるための `&&`、`||`、またはリスト構文はありません。複数の条件を適用するには、各条件に対して個別のフック ハンドラーを定義します。446`if` フィールドは正確に 1 つの権限ルールを保持します。ルールを組み合わせるための `&&`、`||`、またはリスト構文はありません。複数の条件を適用するには、各条件に対して個別のフック ハンドラーを定義します。
348 447
448ファイルツールの `if` 条件では、`"Edit(src/**)"` のような単一セグメントのディレクトリパターンは、作業ディレクトリ内の `src` ディレクトリとその配下のファイルにのみマッチします。任意の深さにある `src` という名前のディレクトリにマッチさせるには、`"Edit(**/src/**)"` と記述します。v2.1.214 より前は、`"Edit(src/**)"` は作業ディレクトリ配下の任意の深さにある `src` という名前のディレクトリにマッチしていました。
449
349<span id="bash-if-matching" />Bash パターンの場合、フック コマンドが実行されるかどうかは、パターンの形状と Claude が呼び出している Bash コマンドに依存します。先頭の `VAR=value` 割り当ては、マッチング前に削除されます。450<span id="bash-if-matching" />Bash パターンの場合、フック コマンドが実行されるかどうかは、パターンの形状と Claude が呼び出している Bash コマンドに依存します。先頭の `VAR=value` 割り当ては、マッチング前に削除されます。
350 451
351| `if` パターン | Bash コマンド | フックが実行されるか | 理由 |452| `if` パターン | Bash コマンド | フックが実行されるか | 理由 |
356| `Bash(rm *)` | `echo $(date)` | いいえ | サブコマンドが `rm *` にマッチしません |457| `Bash(rm *)` | `echo $(date)` | いいえ | サブコマンドが `rm *` にマッチしません |
357| `Bash(git push *)` | `echo $(date)` | はい | コマンド名以上を指定するパターンは、`$()`、バッククォート、または `$VAR` でとにかくフックを実行します |458| `Bash(git push *)` | `echo $(date)` | はい | コマンド名以上を指定するパターンは、`$()`、バッククォート、または `$VAR` でとにかくフックを実行します |
358 459
359フィルターは、Bash コマンドを解析できない場合、パターンに関係なくフックを実行して、オープンに失敗します。`if` フィルターはベストエフォートであるため、ハードな許可または拒否を強制するには、フックではなく[権限システム](/docs/ja/permissions)を使用してください。460Bash 入力がどのコマンドを実行するかを Claude Code が判断できない場合、パターンに関係なくフックを実行します。`if` フィルターはベストエフォートであるため、ハードな許可または拒否を強制するには、フックではなく[権限システム](/docs/ja/permissions)を使用してください。
360 461
361<h4 id="command-hook-fields">462<h4 id="command-hook-fields">
362 コマンド フック フィールド463 コマンド フック フィールド
369| `command` | はい | 実行するシェル コマンド。`args` を使用する場合、直接生成する実行可能ファイル。[Exec フォームとシェル フォーム](#exec-form-and-shell-form)を参照してください |470| `command` | はい | 実行するシェル コマンド。`args` を使用する場合、直接生成する実行可能ファイル。[Exec フォームとシェル フォーム](#exec-form-and-shell-form)を参照してください |
370| `args` | いいえ | 引数リスト。存在する場合、`command` は実行可能ファイルとして解決され、`args` を引数ベクトルとして直接生成されます。シェルは関与しません。[Exec フォームとシェル フォーム](#exec-form-and-shell-form)を参照してください |471| `args` | いいえ | 引数リスト。存在する場合、`command` は実行可能ファイルとして解決され、`args` を引数ベクトルとして直接生成されます。シェルは関与しません。[Exec フォームとシェル フォーム](#exec-form-and-shell-form)を参照してください |
371| `async` | いいえ | `true` の場合、ブロックせずにバックグラウンドで実行されます。[バックグラウンドでフックを実行](#run-hooks-in-the-background)を参照してください |472| `async` | いいえ | `true` の場合、ブロックせずにバックグラウンドで実行されます。[バックグラウンドでフックを実行](#run-hooks-in-the-background)を参照してください |
372| `asyncRewake` | いいえ | `true` の場合、バックグラウンドで実行され、終了コード 2 で Claude を起動します。`async` を暗黙的に指定します。フックの stderr、または stderr が空の場合は stdout が、Claude がシステム リマインダーとして長時間実行されるバックグラウンド失敗に反応できるように表示されます |473| `asyncRewake` | いいえ | `true` の場合、バックグラウンドで実行され、終了コード 2 で Claude を起動します。フックの stderr、または stderr が空の場合は stdout が [システムリマインダー](/docs/ja/glossary#system-reminder)として Claude に表示されるため、Claude は長時間実行されるバックグラウンドの失敗に対応できます |
373| `shell` | いいえ | このフックに使用するシェル。`"bash"` または `"powershell"` を受け入れます。デフォルトは `"bash"`、または Git Bash がインストールされていない場合は Windows で `"powershell"`。`"powershell"` を設定すると、Windows 上で PowerShell 経由でコマンドが実行されます。`CLAUDE_CODE_USE_POWERSHELL_TOOL` は不要です。フックは PowerShell を直接生成するため。`args` が設定されている場合は無視されます |474| `shell` | いいえ | このフックに使用するシェル。`"bash"` または `"powershell"` を受け入れます。デフォルトは `"bash"`、または Git Bash がインストールされていない場合は Windows で `"powershell"`。`"powershell"` を設定すると、Windows 上で PowerShell 経由でコマンドが実行されます。フックは PowerShell を直接生成するため、`CLAUDE_CODE_USE_POWERSHELL_TOOL` は不要です。`args` が設定されている場合は無視されます |
374 475
375<a id="exec-form-and-shell-form" />476<a id="exec-form-and-shell-form" />
376 477
380 481
381コマンド フックは `args` が設定されている場合は exec フォームで実行され、`args` が省略されている場合はシェル フォームで実行されます。フックが[パス プレースホルダー](#reference-scripts-by-path)を参照する場合は常に `args` を設定してください。各要素は引用符なしで 1 つの引数として渡されるためです。パイプや `&&` などのシェル機能が必要な場合、または両方の懸念が適用されない場合は `args` を省略してください。482コマンド フックは `args` が設定されている場合は exec フォームで実行され、`args` が省略されている場合はシェル フォームで実行されます。フックが[パス プレースホルダー](#reference-scripts-by-path)を参照する場合は常に `args` を設定してください。各要素は引用符なしで 1 つの引数として渡されるためです。パイプや `&&` などのシェル機能が必要な場合、または両方の懸念が適用されない場合は `args` を省略してください。
382 483
383**Exec フォーム**は `args` が存在する場合に実行されます。Claude Code は `command` を `PATH` 上の実行可能ファイルとして解決し、`args` を引数ベクトルとして直接生成します。シェルがないため、各 `args` 要素は記述されたとおりに正確に 1 つの引数であり、`${CLAUDE_PLUGIN_ROOT}` などのパス プレースホルダーは `command` と各 `args` 要素にプレーン文字列として置換されます。アポストロフィ、`$`、バッククォートなどの特殊文字は、シェルが解釈しないため、そのまま渡されます。プラットフォーム上でシェル トークン化は発生しません。484**Exec フォーム**は `args` が存在する場合に実行されます。Claude Code は `command` を `PATH` 上の実行可能ファイルとして解決し、`args` を引数ベクトルとして直接生成します。シェルがないため、各 `args` 要素は記述されたとおりに正確に 1 つの引数であり、`${CLAUDE_PLUGIN_ROOT}` などのパス プレースホルダーは `command` と各 `args` 要素にプレーン文字列として置換されます。アポストロフィ、`$`、バッククォートなどの特殊文字は、シェルが解釈しないため、そのまま渡されます。どのプラットフォームでもシェル トークン化は発生しません。
384 485
385**シェル フォーム**は `args` が存在しない場合に実行されます。`command` 文字列はシェルに渡されます。macOS と Linux では `sh -c`、Windows では Git Bash、または Git Bash がインストールされていない場合は PowerShell。`shell` フィールドを設定して明示的に選択します。シェルは文字列をトークン化し、変数を展開し、パイプ、`&&`、リダイレクト、グロブを解釈します。486**シェル フォーム**は `args` が存在しない場合に実行されます。`command` 文字列はシェルに渡されます。macOS と Linux では `sh -c`、Windows では Git Bash、または Git Bash がインストールされていない場合は PowerShell。`shell` フィールドを設定して明示的に選択します。シェルは文字列をトークン化し、変数を展開し、パイプ、`&&`、リダイレクト、グロブを解釈します。
386 487
407}508}
408```509```
409 510
410両方のフォームは同じ[パス プレースホルダー](#reference-scripts-by-path)をサポートし、両方とも生成されたプロセスで環境変数 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`CLAUDE_PLUGIN_DATA` としてエクスポートするため、スクリプトは起動方法に関係なく `process.env.CLAUDE_PLUGIN_ROOT` を読み取ることができます。プラグイン フックは追加で [`${user_config.*}`](/docs/ja/plugins-reference#user-configuration) 値を置換します。exec フォームのみ: 値は `command` と各 `args` 要素にプレーン文字列として置換されるため、シェルは再解析しません。511両方のフォームは同じ[パス プレースホルダー](#reference-scripts-by-path)をサポートし、両方とも生成されたプロセスで環境変数 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`CLAUDE_PLUGIN_DATA` としてエクスポートするため、スクリプトは起動方法に関係なく `process.env.CLAUDE_PLUGIN_ROOT` を読み取ることができます。
512
513プラグイン フックは追加で [`${user_config.*}`](/docs/ja/plugins/manifest-reference#user-configuration) 値を置換します。exec フォームのみ: 値は `command` と各 `args` 要素にプレーン文字列として置換されるため、シェルは再解析しません。
411 514
412`${user_config.*}` を参照するシェル フォーム プラグイン フック コマンドは、実行する代わりに[エラー](/docs/ja/errors#plugin-command-references-user-config)で失敗します。シェル フォーム フックからオプション値を使用するには、`$CLAUDE_PLUGIN_OPTION_<KEY>` 環境変数（`webhook_url` オプションの場合は `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL` など）を読み取るか、`args` を設定してフックを exec フォームに切り替えます。v2.1.207 より前では、シェル フォーム プラグイン フック コマンドも `${user_config.*}` を置換していました。515`command` が `${user_config.*}` を参照するシェル フォームのプラグイン フックは、実行される代わりに[エラー](/docs/ja/errors#plugin-command-references-user-config)で失敗します。シェル フォーム フックからオプション値を使用するには、`$CLAUDE_PLUGIN_OPTION_<KEY>` 環境変数（`webhook_url` オプションの場合は `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL` など）を読み取るか、`args` を設定してフックを exec フォームに切り替えます。v2.1.207 より前では、シェル フォーム プラグイン フック コマンドも `${user_config.*}` を置換していました。
413 516
414<Note>517<Note>
415 Exec フォームでは、`command` は実行可能ファイル名またはパスのみです。`command` が空白を含むパス区切りなしの名前であり、`args` と一緒に空白を含む場合、Claude Code は警告をログします。生成が失敗するためです。`node script.js` という名前の実行可能ファイルはありません。余分なトークンを `args` に移動します。`C:\Program Files\nodejs\node.exe` などのスペースを含む絶対パスは、単一の有効な実行可能ファイルであり、警告をトリガーしません。518 Exec フォームでは、`command` は実行可能ファイル名またはパスのみです。`args` とともに使用される `command` がパス区切り文字を含まないベア名で、かつ空白を含む場合、生成が失敗するため Claude Code は警告をログに記録します。`node script.js` という名前の実行可能ファイルは存在しないためです。余分なトークンを `args` に移動してください。`C:\Program Files\nodejs\node.exe` などのスペースを含む絶対パスは、単一の有効な実行可能ファイルであり、警告をトリガーしません。
416</Note>519</Note>
417 520
418<h4 id="http-hook-fields">521<h4 id="http-hook-fields">
427| `headers` | いいえ | キー値ペアとしての追加 HTTP ヘッダー。値は `$VAR_NAME` または `${VAR_NAME}` 構文を使用した環境変数補間をサポートします。`allowedEnvVars` にリストされている変数のみが解決されます |530| `headers` | いいえ | キー値ペアとしての追加 HTTP ヘッダー。値は `$VAR_NAME` または `${VAR_NAME}` 構文を使用した環境変数補間をサポートします。`allowedEnvVars` にリストされている変数のみが解決されます |
428| `allowedEnvVars` | いいえ | ヘッダー値に補間される可能性のある環境変数名のリスト。リストされていない変数への参照は空の文字列に置き換えられます。環境変数補間が機能するために必須 |531| `allowedEnvVars` | いいえ | ヘッダー値に補間される可能性のある環境変数名のリスト。リストされていない変数への参照は空の文字列に置き換えられます。環境変数補間が機能するために必須 |
429 532
430Claude Code はフックの[JSON 入力](#hook-input-and-output)を `Content-Type: application/json` の POST リクエスト本体として送信します。レスポンス本体はコマンド フックと同じ[JSON 出力形式](#json-output)を使用します。533Claude Code はフックの [JSON 入力](#hook-input-and-output)を `Content-Type: application/json` の POST リクエスト本体として送信します。レスポンス本体はコマンド フックと同じ [JSON 出力形式](#json-output)を使用します。
431 534
432エラー処理はコマンド フックと異なります。2xx 以外のレスポンス、接続失敗、タイムアウトはすべて、実行を続行できる非ブロッキング エラーを生成します。ツール呼び出しをブロックまたは権限を拒否するには、`decision: "block"` または `hookSpecificOutput` を含む `permissionDecision: "deny"` を含む JSON 本体を持つ 2xx レスポンスを返します。535エラー処理はコマンド フックと異なります。[HTTP レスポンスの処理](#http-response-handling)を参照してください。
433 536
434この例は `PreToolUse` イベントをローカル検証サービスに送信し、`MY_TOKEN` 環境変数からのトークンで認証します。537この例は `PreToolUse` イベントをローカル検証サービスに送信し、`MY_TOKEN` 環境変数からのトークンで認証します。
435 538
464 567
465| フィールド | 必須 | 説明 |568| フィールド | 必須 | 説明 |
466| :- | :- | :- |569| :- | :- | :- |
467| `server` | はい | 設定された MCP サーバーの名前。[プラグイン バンドル サーバー](/docs/ja/mcp#plugin-provided-mcp-servers)の場合、これはスコープ付き名前 `plugin:<plugin-name>:<server-name>`（例：`plugin:my-plugin:db`）であり、ベア サーバー キーではありません。サーバーは既に接続されている必要があります。フックは OAuth または接続フローをトリガーしません |570| `server` | はい | 設定された MCP サーバーの名前。[プラグイン バンドル サーバー](/docs/ja/mcp#plugin-provided-mcp-servers)の場合、これはスコープ付き名前 `plugin:<plugin-name>:<server-name>`（例：`plugin:my-plugin:db`）であり、ベア サーバー キーではありません |
468| `tool` | はい | そのサーバー上で呼び出すツールの名前 |571| `tool` | はい | そのサーバー上で呼び出すツールの名前 |
469| `input` | いいえ | ツールに渡される引数。文字列値は、フックの[JSON 入力](#hook-input-and-output)から `${path}` 置換をサポートします（例：`"${tool_input.file_path}"`） |572| `input` | いいえ | ツールに渡される引数。文字列値は、フックの [JSON 入力](#hook-input-and-output)から `${path}` 置換をサポートします（例：`"${tool_input.file_path}"`） |
470
471ツールのテキスト コンテンツはコマンド フック stdout のように扱われます。有効な[JSON 出力](#json-output)として解析される場合、決定として処理されます。そうでない場合は、プレーン テキストとして表示されます。指定されたサーバーが接続されていない場合、またはツールが `isError: true` を返す場合、フックは非ブロッキング エラーを生成し、実行は続行されます。
472
473MCP ツール フックは、Claude Code が MCP サーバーに接続した後、すべてのフック イベントで利用可能です。`SessionStart` と `Setup` は通常、サーバーが接続を完了する前に発火するため、これらのイベント上のフックは最初の実行時に「接続されていない」エラーを予期する必要があります。
474 573
475この例は、各 `Write` または `Edit` の後、`my_server` MCP サーバー上の `security_scan` ツールを呼び出し、編集されたファイルのパスを渡します。574この例は、各 `Write` または `Edit` の後、`my_server` MCP サーバー上の `security_scan` ツールを呼び出し、編集されたファイルのパスを渡します。
476 575
494}593}
495```594```
496 595
596<h5 id="how-the-tool’s-result-is-read">
597 ツールの結果の読み取り方
598</h5>
599
600Claude Code は、[終了コード 0 の解析ルール](#exit-code-0)に従い、コマンドフックの stdout と同じ方法でツールのテキストコンテンツを読み取ります。ツールが `isError: true` を返した場合、フックは非ブロッキングエラーを生成し、実行は続行されます。
601
602<h5 id="when-the-server-is-still-connecting">
603 サーバーがまだ接続中の場合
604</h5>
605
606`PreToolUse` や `Stop` など、フックが結果をブロックまたは変更できるイベントでは、Claude Code は接続中のサーバーを待ってからツールを呼び出します。待機時間は最大で [`MCP_TIMEOUT`](/docs/ja/env-vars) までで、フック自体の [`timeout`](#common-fields) の範囲内です。`Notification` や `SessionEnd` などの観察用イベントでは待機しません。
607
608[`cached` ステータス](/docs/ja/mcp#server-status-detail)を表示しているサーバーは、フックがそのツールを呼び出したときに接続します。その時点でサーバーが接続されていない場合、フックは非ブロッキングエラーを生成し、実行は続行されます。フックが OAuth フローを開始することはないため、先に [`/mcp` からサーバーを認証](/docs/ja/mcp#authenticate-with-remote-mcp-servers)してください。
609
610<h5 id="events-that-fire-before-mcp-servers-are-available">
611 MCP サーバーが利用可能になる前に発火するイベント
612</h5>
613
614起動時の `SessionStart`（`--continue` や `--resume` の場合を含む）とすべての `Setup` イベントは、セッションの MCP サーバーがフックから利用可能になる前に発火します。Claude Code はツールを呼び出さずにこれらの `mcp_tool` フックをスキップし、[デバッグログ](#debug-hooks)には `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`、または `Setup` を示す同じメッセージが記録されます。`/clear` やコンテキスト圧縮の後など、セッションの後半で `SessionStart` が再び発火した場合は、その `mcp_tool` フックが実行されます。セッションが起動時に必要とするものについては、代わりに `SessionStart` で `type: "command"` フックを使用してください。
615
497<h4 id="prompt-and-agent-hook-fields">616<h4 id="prompt-and-agent-hook-fields">
498 プロンプト フックとエージェント フック フィールド617 プロンプト フックとエージェント フック フィールド
499</h4>618</h4>
503| フィールド | 必須 | 説明 |622| フィールド | 必須 | 説明 |
504| :- | :- | :- |623| :- | :- | :- |
505| `prompt` | はい | モデルに送信するプロンプト テキスト。フック入力 JSON のプレースホルダーとして `$ARGUMENTS` を使用します。バックスラッシュでエスケープしてリテラル テキストを含めます。`\$1.00` は `$1.00` としてレンダリングされます |624| `prompt` | はい | モデルに送信するプロンプト テキスト。フック入力 JSON のプレースホルダーとして `$ARGUMENTS` を使用します。バックスラッシュでエスケープしてリテラル テキストを含めます。`\$1.00` は `$1.00` としてレンダリングされます |
506| `model` | いいえ | 評価に使用するモデル。デフォルトは高速モデル |625| `model` | いいえ | 評価に使用するモデル。デフォルトは、Claude Code が[バックグラウンド機能](/docs/ja/costs#background-token-usage)に使用するモデル |
507 626
508<h3 id="reference-scripts-by-path">627<h3 id="reference-scripts-by-path">
509 パスでフック スクリプトを参照628 パスでフック スクリプトを参照
511 630
512フックが実行されるときの作業ディレクトリに関係なく、プロジェクトまたはプラグイン ルートを基準にしてフック スクリプトを参照するには、これらのプレースホルダーを使用します。631フックが実行されるときの作業ディレクトリに関係なく、プロジェクトまたはプラグイン ルートを基準にしてフック スクリプトを参照するには、これらのプレースホルダーを使用します。
513 632
514* `${CLAUDE_PROJECT_DIR}`: プロジェクト ルート。Claude Code はこの変数を[stdio MCP サーバー](/docs/ja/mcp#option-3-add-a-local-stdio-server)とプラグイン LSP サーバーの環境にも設定します。633* `${CLAUDE_PROJECT_DIR}`: セッションを開始したプロジェクトルート。Claude Code はこの変数を [stdio MCP サーバー](/docs/ja/mcp#option-3-add-a-local-stdio-server)とプラグイン LSP サーバーの環境にも設定します。
515* `${CLAUDE_PLUGIN_ROOT}`: プラグインのインストール ディレクトリ、[プラグイン](/docs/ja/plugins)にバンドルされたスクリプト用。プラグイン更新時に変更されます。634* `${CLAUDE_PLUGIN_ROOT}`: プラグインのインストールディレクトリ。[プラグイン](/docs/ja/plugins/overview)にバンドルされたスクリプト用です。更新時にこのパスがどう扱われるかについては、[プラグインの環境変数](/docs/ja/plugins/manifest-reference#environment-variables)を参照してください。
516* `${CLAUDE_PLUGIN_DATA}`: プラグインの[永続データ ディレクトリ](/docs/ja/plugins-reference#persistent-data-directory)、プラグイン更新を通じて存続すべき依存関係と状態用。635* `${CLAUDE_PLUGIN_DATA}`: プラグインの[永続データディレクトリ](/docs/ja/plugins/components#path-variables-and-persistent-data)。プラグインの更新後も保持すべき依存関係と状態用です。
636
637<Note>
638 **worktree の場合は異なります。** セッション中に Claude が [worktree](/docs/ja/worktrees) に入った場合、Claude Code は `${CLAUDE_PROJECT_DIR}` を元の場所のまま維持し、worktree のパスは別の方法でフックに渡します。
517 639
518パス プレースホルダーを参照するフックには[exec フォーム](#exec-form-and-shell-form)を優先してください。Exec フォームは各 `args` 要素を引用符なしで 1 つの引数として渡すため、スペースまたは特殊文字を含むパスは引用符が不要です。シェル フォームでは、各プレースホルダーをダブル クォートで囲みます。640 * **`${CLAUDE_PROJECT_DIR}` は変わらない**: セッションを開始したプロジェクトルートを引き続き指すため、`${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh` のようなコマンドは、引き続きメインのチェックアウト内のスクリプトを実行します。
641 * **`cwd` は Claude に追従する**: フックの[入力 JSON](#common-input-fields) の `cwd` フィールドは、Claude が worktree に入った後はその worktree のルートになり、Claude が `cd` を実行した後は新しいディレクトリになります。Claude がどのディレクトリで作業しているかをフックが知る必要がある場合は、このフィールドを読み取ってください。
642</Note>
643
644パス プレースホルダーを参照するフックには [exec フォーム](#exec-form-and-shell-form)を優先してください。シェル フォームでは、各プレースホルダーをダブル クォートで囲みます。
519 645
520<Tabs>646<Tabs>
521 <Tab title="プロジェクト スクリプト">647 <Tab title="プロジェクト スクリプト">
567 }693 }
568 ```694 ```
569 695
570 プラグイン フックの作成の詳細については、[プラグイン コンポーネント リファレンス](/docs/ja/plugins-reference#hooks)を参照してください。696 プラグイン フックの作成の詳細については、[プラグイン コンポーネント リファレンス](/docs/ja/plugins/components#hooks)を参照してください。
571 </Tab>697 </Tab>
572</Tabs>698</Tabs>
573 699
575 スキルとエージェントのフック701 スキルとエージェントのフック
576</h3>702</h3>
577 703
578設定ファイルとプラグインに加えて、フックは[スキル](/docs/ja/skills)と[サブエージェント](/docs/ja/sub-agents)でフロントマターを使用して直接定義できます。これらのフックはコンポーネントのライフサイクルにスコープされ、そのコンポーネントがアクティブな場合にのみ実行されます。704設定ファイルとプラグインに加えて、フックは[スキル](/docs/ja/skills)と[サブエージェント](/docs/ja/sub-agents)でフロントマターを使用して直接定義できます。設定形式は設定ベースのフックと同じです。Claude Code がこれらを登録しておく期間は、コンポーネントによって異なります。
579
580すべてのフック イベントがサポートされています。サブエージェントの場合、`Stop` フックは自動的に `SubagentStop` に変換されます。これはサブエージェントが完了したときに発火するイベントです。
581 705
582フックは設定ベースのフックと同じ設定形式を使用しますが、コンポーネントのライフタイムにスコープされ、完了時にクリーンアップされます。706* **サブエージェントのフック**: Claude Code は、そのサブエージェントの実行中にのみこれらを実行し、サブエージェントが終了すると削除します。ここでの `Stop` フックは、Claude Code によって `SubagentStop` に変換されます。これはサブエージェントが完了したときに発火するイベントです。
707* **スキルのフック**: Claude Code は、ユーザーまたは Claude がスキルを呼び出したときにこれらを登録し、スキル自体のターンの後のターンも含めて、セッションの残りの期間ずっと実行し続けます。代わりに最初の実行が成功した後で Claude Code にフックを削除させるには、そのフックに [`once: true`](#common-fields) を設定します。
583 708
584このスキルは、各 `Bash` コマンドの前にセキュリティ検証スクリプトを実行する `PreToolUse` フックを定義します。709このスキルは、各 `Bash` コマンドの前にセキュリティ検証スクリプトを実行する `PreToolUse` フックを定義します。
585 710
596---721---
597```722```
598 723
599エージェントは YAML フロントマターで同じ形式を使用します。724サブエージェントは YAML フロントマターで同じ形式を使用します。
725
726プロジェクトスキルのフロントマターのフックは、[設定ファイルのフックと同じワークスペース信頼ルール](#workspace-trust)に従います。Claude Code は、ユーザーまたは Claude がスキルを呼び出したときにこれらを登録します。これには、信頼していないフォルダーでの `-p` 実行も含まれます。
727
728プロジェクトサブエージェントのフロントマターのフックは、エージェントファイルの取得元フォルダーについて[ワークスペース信頼ダイアログ](/docs/ja/permissions#project-allow-rules-and-workspace-trust)を承認した後にのみ実行されます。`-p` セッションは承認したことになりません。[フォルダーを信頼する前に実行されるもの](/docs/ja/permissions#what-runs-before-you-trust-a-folder)ではこれを設定ファイルのルールと比較しており、サブエージェントのページには[どのスコープが対象外か](/docs/ja/sub-agents#hooks-in-subagent-frontmatter)が記載されています。v2.1.218 より前は、これらのフックは信頼していないフォルダーからも実行される可能性がありました。
600 729
601<h3 id="the-/hooks-menu">730<h3 id="the-/hooks-menu">
602 `/hooks` メニュー731 `/hooks` メニュー
603</h3>732</h3>
604 733
605Claude Code で `/hooks` と入力して、設定されたフックの読み取り専用ブラウザーを開きます。メニューはすべてのフック イベントを表示し、設定されたフックの数を示し、マッチャーにドリルダウンでき、各フック ハンドラーの完全な詳細を表示します。これを使用して設定を検証し、フックがどの設定ファイルから定義されたかを確認するか、フックのコマンド、プロンプト、または URL を検査します。734Claude Code で `/hooks` と入力して、設定されたフックの読み取り専用ブラウザーを開きます。リストでは、各フックにその取得元（ユーザー設定、プロジェクト設定、ローカル設定、プラグイン、現在のセッションなど）を示すラベルが付けられます。
606
607メニューは 5 つのフック タイプをすべて表示します。`command`、`prompt`、`agent`、`http`、`mcp_tool`。各フックには、そのソースを示す `[type]` プレフィックスとソース ラベルが付けられています。
608 735
609* `User`: `~/.claude/settings.json` から736フックを選択すると、そのフックが実行する内容の全文と、定義されている場所（設定ファイルのパスやプラグインの名前など）が表示されます。
610* `Project`: `.claude/settings.json` から
611* `Local`: `.claude/settings.local.json` から
612* `Plugin`: プラグインの `hooks/hooks.json` から
613* `Session`: 現在のセッション用にメモリに登録
614* `Built-in`: Claude Code によって内部的に登録
615 737
616フックを選択すると、詳細ビューが開き、そのイベント、マッチャー、タイプ、ソース ファイル、および完全なコマンド、プロンプト、または URL が表示されます。メニューは読み取り専用です。フックを追加、変更、または削除するには、設定 JSON を直接編集するか、Claude にその変更を依頼してください。738フックが設定されていないものも含めてすべてのフック イベントを参照するには、リストの末尾にある `All events` を選択します。
617 739
618<h3 id="disable-or-remove-hooks">740<h3 id="disable-or-remove-hooks">
619 フックを無効化または削除741 フックを無効化または削除
620</h3>742</h3>
621 743
622フックを削除するには、設定 JSON ファイルからそのエントリを削除します。744設定ファイルで定義されたフックを削除するには、そのファイルからエントリを削除します。
623 745
624すべてのフックを削除せずに一時的に無効化するには、設定ファイルで `"disableAllHooks": true` を設定します。個別のフックを設定に保持したまま無効化する方法はありません。746すべてのフックを削除せずに一時的に無効化するには、設定ファイルで `"disableAllHooks": true` を設定します。Claude Code は[設定の優先順位](/docs/ja/settings#settings-precedence)を適用した後に残る値を読み取るため、プロジェクトの `.claude/settings.json` にある `"disableAllHooks": false` は、ユーザー設定の `true` を上書きします。プロジェクトの設定内容にかかわらず 1 回の実行だけフックをオフにするには、`--settings '{"disableAllHooks": true}'` を渡します。これはプロジェクト設定とローカル設定よりも優先されます。個別のフックを設定に保持したまま無効化する方法はありません。
625 747
626`disableAllHooks` 設定は管理設定階層を尊重します。管理者が管理ポリシー設定を通じてフックを設定している場合、ユーザー、プロジェクト、またはローカル設定で設定された `disableAllHooks` は、それらの管理フックを無効化できません。管理設定レベルで設定された `disableAllHooks` のみが管理フックを無効化できます。748`disableAllHooks` 設定は管理設定階層を尊重します。管理者が管理ポリシー設定を通じてフックを設定している場合、ユーザー、プロジェクト、またはローカル設定で設定された `disableAllHooks` は、それらの管理フックを無効化できません。管理設定レベルで設定された `disableAllHooks` のみが管理フックを無効化できます。各レベルの影響範囲の詳細については、[`disableAllHooks`](/docs/ja/settings-reference#disableallhooks) を参照してください。
627 749
628設定ファイルのフックへの直接編集は通常、ファイル ウォッチャーによって自動的に取得されます。750設定ファイルのフックへの直接編集は通常、ファイル ウォッチャーによって自動的に取得されます。
629 751
631 フック入出力753 フック入出力
632</h2>754</h2>
633 755
634コマンド フックは stdin 経由で JSON データを受け取り、終了コード、stdout、stderr を通じて結果を通信します。HTTP フックは同じ JSON をリクエスト本体として受け取り、HTTP レスポンス本体を通じて結果を通信します。このセクションでは、すべてのイベントに共通するフィールドと動作について説明します。[フック イベント](#hook-events)の各セクションには、その特定の入力スキーマと決定制御オプションが含まれています。756コマンド フックは stdin 経由で JSON データを受け取り、終了コード、stdout、stderr を通じて結果を通信します。HTTP フックは同じ JSON を POST リクエスト本体として受け取り、HTTP レスポンス本体を通じて結果を通信します。このセクションでは、すべてのイベントに共通するフィールドと動作について説明します。[フック イベント](#hook-events)の各セクションには、その特定の入力スキーマと決定制御オプションが含まれています。
635 757
636macOS と Linux では、コマンド フックは v2.1.139 以降、制御端末のない独自のセッションで実行されます。フック プロセスと子プロセスは `/dev/tty` を開くことも、エスケープ シーケンスを Claude Code インターフェイスに直接送信することもできません。Windows には `/dev/tty` がありません。任意のプラットフォームでユーザーにメッセージを表示するには、JSON 出力で[`systemMessage`](#json-output)を返します。デスクトップ通知をトリガーしたり、ウィンドウ タイトルを設定したり、ベルを鳴らしたりするには、代わりに[`terminalSequence`](#emit-terminal-notifications)を返します。758macOS と Linux では、コマンド フックは制御ターミナルのない独自のセッションで実行されます。フック プロセスと子プロセスは `/dev/tty` を開くことも、エスケープ シーケンスを Claude Code インターフェイスに直接送信することもできません。Windows には `/dev/tty` がありません。
759
760任意のプラットフォームでユーザーにメッセージを表示するには、JSON 出力で [`systemMessage`](#json-output) を返します。一部のイベントはこれを破棄するか別の場所に配信します。その点は各[イベントのセクション](#hook-events)に記載されています。デスクトップ通知をトリガーしたり、ウィンドウ タイトルを設定したり、ベルを鳴らしたりするには、代わりに [`terminalSequence`](#emit-terminal-notifications) を返します。
637 761
638<h3 id="common-input-fields">762<h3 id="common-input-fields">
639 共通入力フィールド763 共通入力フィールド
645| :- | :- |769| :- | :- |
646| `session_id` | 現在のセッション識別子 |770| `session_id` | 現在のセッション識別子 |
647| `prompt_id` | 現在処理中のユーザー プロンプトを識別する UUID。[OpenTelemetry イベントの `prompt.id` 属性](/docs/ja/monitoring-usage#event-correlation-attributes)と一致するため、単一のプロンプトのテレメトリでフック出力を相関させることができます。最初のユーザー入力まで存在しません。Claude Code v2.1.196 以降が必要です |771| `prompt_id` | 現在処理中のユーザー プロンプトを識別する UUID。[OpenTelemetry イベントの `prompt.id` 属性](/docs/ja/monitoring-usage#event-correlation-attributes)と一致するため、単一のプロンプトのテレメトリでフック出力を相関させることができます。最初のユーザー入力まで存在しません。Claude Code v2.1.196 以降が必要です |
648| `transcript_path` | 会話 JSON へのパス。トランスクリプト ファイルは非同期に書き込まれ、メモリ内の会話に遅れる可能性があるため、フックが発火するときに現在のターンの最新メッセージがまだ含まれていない可能性があります。現在のターンの最終的なアシスタント テキストが必要なフックは、トランスクリプトを読む代わりに[Stop](#stop)と[SubagentStop](#subagentstop)の `last_assistant_message` を使用する必要があります |772| `transcript_path` | 会話 JSON へのパス。トランスクリプト ファイルは非同期に書き込まれ、メモリ内の会話に遅れる可能性があるため、フックが発火するときに現在のターンの最新メッセージがまだ含まれていない可能性があります。現在のターンの最終的なアシスタント テキストが必要なフックは、トランスクリプトを読む代わりに [Stop](#stop) と [SubagentStop](#subagentstop) の `last_assistant_message` を使用する必要があります |
649| `cwd` | フックが呼び出されるときの現在の作業ディレクトリ |773| `cwd` | フックが呼び出されるときの現在の作業ディレクトリ |
774| `scratchpad_dir` | セッションの[スクラッチパッド ディレクトリ](/docs/ja/claude-directory#session-scratchpad-directory)へのパス。Claude はここに一時的な作業ファイルを保持します。セッションにスクラッチパッドがない場合、または一時ディレクトリが利用できない場合は存在しません。Claude Code v2.1.257 以降が必要です |
650| `permission_mode` | 現在の[権限モード](/docs/ja/permissions#permission-modes): `"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"`、または `"bypassPermissions"`。**Manual** というラベルが付いたモードは `"default"` として到着し、`"manual"` として到着することはないため、`"default"` と一致するスクリプトは引き続き機能します。すべてのイベントがこのフィールドを受け取るわけではありません。各[フック イベント](#hook-events)セクションの JSON 例を確認してください |775| `permission_mode` | 現在の[権限モード](/docs/ja/permissions#permission-modes): `"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"`、または `"bypassPermissions"`。**Manual** というラベルが付いたモードは `"default"` として到着し、`"manual"` として到着することはないため、`"default"` と一致するスクリプトは引き続き機能します。すべてのイベントがこのフィールドを受け取るわけではありません。各[フック イベント](#hook-events)セクションの JSON 例を確認してください |
651| `effort` | アクティブな[努力レベル](/docs/ja/model-config#adjust-effort-level)を保持する `level` フィールドを持つオブジェクト。ターンの場合: `"low"`、`"medium"`、`"high"`、`"xhigh"`、または `"max"`。リクエストされたモデル努力が現在のモデルがサポートしているものを超える場合、これはモデルが実際に使用したダウングレードされたレベルです。Ultracode は異なるレベルではなく、`"xhigh"` として報告されます。オブジェクトは[ステータス ライン](/docs/ja/statusline#available-data)の `effort` フィールドと一致します。`PreToolUse`、`PostToolUse`、`Stop`、`SubagentStop` などのツール使用コンテキスト内で発火するイベント、および現在のモデルが努力パラメータをサポートする場合に存在します。レベルは、フック コマンドと Bash ツールに `$CLAUDE_EFFORT` 環境変数として利用可能です。 |776| `effort` | フックの実行時に有効な [effort レベル](/docs/ja/model-config#adjust-effort-level)を保持する `level` フィールドを持つオブジェクト: `"low"`、`"medium"`、`"high"`、`"xhigh"`、または `"max"`。アクティブなモデルがサポートしていないレベルを設定した場合、`level` は Claude Code が代わりに実行したレベルを報告します。そのレベルの選び方については [effort レベルを調整](/docs/ja/model-config#adjust-effort-level)を参照してください。オブジェクトは[ステータスライン](/docs/ja/statusline#available-data)の `effort` フィールドと一致します。現在のモデルが effort パラメータをサポートしている場合、`PreToolUse`、`PostToolUse`、`Stop`、`SubagentStop` などのツール使用コンテキスト内で発火するイベントに存在します。レベルは、フック コマンドと Bash ツールでも `$CLAUDE_EFFORT` 環境変数として利用可能です。 |
652| `hook_event_name` | 発火したイベントの名前 |777| `hook_event_name` | 発火したイベントの名前 |
653 778
654`--agent` で実行するか、サブエージェント内で実行する場合、2 つの追加フィールドが含まれます。779`--agent` で実行するか、サブエージェント内で実行する場合、2 つの追加フィールドが含まれます。
656| フィールド | 説明 |781| フィールド | 説明 |
657| :- | :- |782| :- | :- |
658| `agent_id` | サブエージェントの一意の識別子。フックがサブエージェント呼び出し内で発火する場合にのみ存在します。これを使用して、サブエージェント フック呼び出しをメイン スレッド呼び出しから区別します。 |783| `agent_id` | サブエージェントの一意の識別子。フックがサブエージェント呼び出し内で発火する場合にのみ存在します。これを使用して、サブエージェント フック呼び出しをメイン スレッド呼び出しから区別します。 |
659| `agent_type` | エージェント名（例えば、`"Explore"` または `"security-reviewer"`）。セッションが `--agent` を使用するか、フックがサブエージェント内で発火する場合に存在します。サブエージェントの場合、サブエージェントのタイプがセッションの `--agent` 値よりも優先されます。[カスタム サブエージェント](/docs/ja/sub-agents)の場合、これはエージェントのフロントマターの `name` フィールドであり、ファイル名ではありません。[プラグイン](/docs/ja/plugins)によって提供されるサブエージェントの場合、これは `my-plugin:reviewer` などのプラグイン スコープ識別子であり、フロントマター名ではありません。[SubagentStart](#subagentstart)を参照して、プラグイン スコープ名に対するマッチャーを記述する方法を確認してください。 |784| `agent_type` | エージェント名（例えば、`"Explore"` または `"security-reviewer"`）。セッションが `--agent` を使用するか、フックがサブエージェント内で発火する場合に存在します。サブエージェントの場合、サブエージェントのタイプがセッションの `--agent` 値よりも優先されます。カスタム サブエージェントとプラグイン サブエージェントが報告する値と、プラグイン スコープ名に対する matcher の記述方法については、[SubagentStart](#subagentstart) を参照してください。 |
785
786[`SessionStart`](#sessionstart) フックのみが `model` フィールドを受け取ることができ、Claude Code が常にそれを含めるとは限りません。[`PreModelSwitch`](#premodelswitch) と [`PostModelSwitch`](#postmodelswitch) フックは代わりに `from_model` と `to_model` を受け取るため、セッション中に変化するモデルを追跡するには PostModelSwitch フックを使用してください。
660 787
661[`SessionStart`](#sessionstart) フックのみが `model` フィールドを受け取ることができ、存在することは保証されません。`$CLAUDE_MODEL` 環境変数はありません。フック プロセスは親環境を継承するため、シェルで `$ANTHROPIC_MODEL` を設定した場合はそれを読み取ることができますが、セッション中に `/model` でモデルを切り替えるときにその値は変わりません。1 つのセット変数は継承されません。Claude Code は[すべてのサブプロセスから `OTEL_*` エクスポーター変数を削除](/docs/ja/monitoring-usage#administrator-configuration)します。これにはフックが含まれます。788`$CLAUDE_MODEL` 環境変数はありません。シェルで `$ANTHROPIC_MODEL` を設定した場合、フックはそれを読み取ることができますが、セッション中に `/model` でモデルを切り替えてもその値は変わりません。
789
790フック プロセスは親環境を継承します。ただし、Claude Code が[起動するすべてのサブプロセスから削除する](/docs/ja/monitoring-usage#administrator-configuration) `OTEL_*` エクスポーター変数と、[`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/ja/env-vars#variables) が `1` に設定されている場合に除去される変数は除きます。
662 791
663例えば、Bash コマンドの `PreToolUse` フックは stdin で以下を受け取ります。792例えば、Bash コマンドの `PreToolUse` フックは stdin で以下を受け取ります。
664 793
668 "prompt_id": "550e8400-e29b-41d4-a716-446655440000",797 "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
669 "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",798 "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
670 "cwd": "/home/user/my-project",799 "cwd": "/home/user/my-project",
800 "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
671 "permission_mode": "default",801 "permission_mode": "default",
672 "hook_event_name": "PreToolUse",802 "hook_event_name": "PreToolUse",
673 "tool_name": "Bash",803 "tool_name": "Bash",
674 "tool_input": {804 "tool_input": {
675 "command": "npm test"805 "command": "npm test",
676 }806 "description": "Run test suite",
807 "timeout": 120000,
808 "run_in_background": false
809 },
810 "tool_use_id": "toolu_01ABC123..."
677}811}
678```812```
679 813
680`tool_name` と `tool_input` フィールドはイベント固有です。各[フック イベント](#hook-events)セクションでは、そのイベントの追加フィールドについて説明しています。814`tool_name`、`tool_input`、`tool_use_id` フィールドはイベント固有です。各[フック イベント](#hook-events)セクションでは、そのイベントの追加フィールドについて説明しています。
681 815
682<h3 id="exit-code-output">816<h3 id="exit-code-output">
683 終了コード出力817 終了コード出力
684</h3>818</h3>
685 819
686フック コマンドからの終了コードは、Claude Code にアクションが進行すべきか、ブロックされるべきか、無視されるべきかを伝えます。820フック コマンドからの終了コードは、Claude Code にアクションが進行すべきか、ブロックされるべきか、無視されるべきかを伝えます。終了コードは単独で作用するわけではありません。Claude Code は 0 だけでなくすべての終了コードで stdout から [JSON 出力フィールド](#json-output)を読み取ります。標準の決定モデルを使用するイベントでは、解析されたオブジェクトがスキーマ検証に合格すると、終了コードとともに効果を持ちます。終了 2 によるブロックは、JSON で上書きできない唯一の結果です。
821
822イベントごとの例外は 2 つの表にまとめられています。[イベントごとの終了コード 2 動作](#exit-code-2-behavior-per-event)は各イベントで終了コードが何をするかを示し、[決定制御](#decision-control)は各イベントがどの決定フィールドを尊重するかを示します。`systemMessage` などのユニバーサル フィールドはほとんどのイベントで機能し、[JSON 出力](#json-output)の表にリストされています。
823
824<h4 id="exit-code-0">
825 終了コード 0
826</h4>
827
828終了 0 は成功を意味し、構造化制御のために JSON を出力する場合に想定される終了コードです。
829
830ほとんどのイベントでは、Claude Code は stdout をデバッグ ログに書き込み、トランスクリプトには表示しません。例外は `UserPromptSubmit`、`UserPromptExpansion`、`SessionStart`、`PostModelSwitch` で、Claude Code はプレーン テキストの stdout を Claude が見て行動できるコンテキストとして追加します。
831
832Claude Code が stdout を [JSON 出力](#json-output)として読み取るかプレーン テキストとして読み取るかは、前後の空白を無視したうえで、その開始と終了の文字によって決まります。
833
834* **`{` で始まり `}` で終わる**: Claude Code は JSON として解析します。出力が 2 行以上で、各行が単独で JSON として解析でき、どの行もフィールドを設定する [JSON 出力](#json-output)オブジェクトでない場合、Claude Code は出力全体をプレーン テキストとして扱います。それらの行のいずれかがフィールドを設定している場合、出力全体は解析失敗となります（後述）。
835* **`{` で始まるが `}` で終わらない**: Claude Code はプレーン テキストとして扱います。
836* **その他の文字で始まる**: JSON 配列や引用符で囲まれた JSON 文字列を含め、Claude Code はプレーン テキストとして扱います。
687 837
688**終了 0** は成功を意味します。Claude Code は stdout を[JSON 出力フィールド](#json-output)で解析します。JSON 出力は終了 0 でのみ処理されます。ほとんどのイベントでは、stdout はデバッグ ログに書き込まれますが、トランスクリプトには表示されません。例外は `UserPromptSubmit`、`UserPromptExpansion`、および `SessionStart` で、stdout は Claude が見て行動できるコンテキストとして追加されます。838標準の決定モデルを使用するイベントでは、終了 0 で解析されたオブジェクトがスキーマ検証に失敗した場合は非ブロッキング エラーとなります。アクションは進行し、トランスクリプトには検証メッセージとともに `<hook name> hook error` 通知が表示されます。2 以外のすべての終了コードでも同じことが起こりますが、[終了 2 は引き続きブロックします](#exit-code-2)。
689 839
690**終了 2** はブロッキング エラーを意味します。Claude Code は stdout とそれ内の JSON を無視します。代わりに、stderr テキストがエラー メッセージとして Claude にフィードバックされます。効果はイベントに依存します。`PreToolUse` はツール呼び出しをブロックし、`UserPromptSubmit` はプロンプトを拒否します。完全なリストについては、[終了コード 2 動作](#exit-code-2-behavior-per-event)を参照してください。840標準の決定モデルを使用するイベントでは、Claude Code が stdout を JSON として解析しようとして失敗した場合、2 以外のすべての終了コードで非ブロッキング エラーを報告します。トランスクリプトには解析メッセージとともに `<hook name> hook error` 通知が表示されます。プレーン テキストの stdout をコンテキストとして追加するイベントでは、Claude Code はそのテキストを追加しません。v2.1.248 より前は、Claude Code はその stdout をプレーン テキストとして扱っていました。
691 841
692**その他の終了コード** はほとんどのフック イベントの非ブロッキング エラーです。トランスクリプトは `<hook name> hook error` 通知を表示し、その後に stderr の最初の行が続くため、`--debug` なしで原因を特定できます。実行は続行され、完全な stderr はデバッグ ログに書き込まれます。842終了 0 のフックからの stderr はデバッグ ログにのみ送られ、トランスクリプトには表示されず、Claude がそれを見ることはありません。自分で読むには、[デバッグ ログ](#debug-hooks)を有効にしてください。`PostToolUse` または `PostToolUseFailure` フックから Claude に警告を表示するには、代わりに終了 2 を使用してください。そうすれば、ツールがすでに実行されていても [Claude は stderr を確認できます](#exit-code-2-behavior-per-event)。
693 843
694例えば、危険な Bash コマンドをブロックするフック コマンド スクリプト。844<h4 id="exit-code-2">
845 終了コード 2
846</h4>
847
848終了 2 はブロッキング エラーを意味します。[ブロック可能なイベント](#exit-code-2-behavior-per-event)では、JSON を出力するかどうかにかかわらず終了 2 はブロックします。JSON の `permissionDecision` が `"allow"` であっても上書きできません。Claude Code は stdout 上の有効な [JSON 出力](#json-output)を引き続き読み取ります。`Elicitation` と `ElicitationResult` では、終了 2 のフックの `hookSpecificOutput` は無視されます。
849
850ブロッキング メッセージは、JSON がブロッキング決定を行う場合はその理由、それ以外の場合は stderr テキストです。ブロックの効果はイベントによって異なります。`PreToolUse` はツール呼び出しをブロックし、`UserPromptSubmit` はプロンプトを拒否する、などです。[イベントごとの終了コード 2 動作](#exit-code-2-behavior-per-event)にはすべてのイベントの効果がリストされており、各イベントのセクションにはメッセージの送信先が記載されています。
851
852[JSON 出力](#json-output)のスキーマ検証に失敗する JSON を出力しながら終了 2 するフックは、引き続きブロックします。Claude Code は stderr をブロッキング理由として使用し、検証の失敗をデバッグ ログに記録します。v2.1.214 より前は、Claude Code はその組み合わせを非ブロッキング エラーとして扱い、アクションは進行していました。
853
854このスクリプトは終了 2 によって `rm` コマンドをブロックし、それ以外のすべてのコマンドは通常の権限フローに任せます。
695 855
696```bash theme={null}856```bash theme={null}
697#!/bin/bash857#!/bin/bash
698# stdin から JSON 入力を読み取り、コマンドをチェック858# Reads JSON input from stdin, checks the command
699command=$(jq -r '.tool_input.command' < /dev/stdin)859input=$(cat)
860command=$(jq -r '.tool_input.command' <<<"$input")
700 861
701if [[ "$command" == rm* ]]; then862if [[ "$command" == rm* ]]; then
702 echo "Blocked: rm commands are not allowed" >&2863 echo "Blocked: rm commands are not allowed" >&2
703 exit 2 # ブロッキング エラー: ツール呼び出しが防止される864 exit 2 # Blocking error: tool call is prevented
704fi865fi
705 866
706exit 0 # 決定なし: 通常の権限フローが適用される867exit 0 # No decision: the normal permission flow applies
707```868```
708 869
870<h4 id="other-exit-codes">
871 その他の終了コード
872</h4>
873
874その他の終了コードは、ほとんどのフック イベントでそれ自体ではブロックしません。何が起こるかは stdout によって異なります。
875
876* 標準の決定モデルを使用するイベントで、解析されたオブジェクトがスキーマ検証に合格した場合、Claude Code は終了コードを無視し、JSON のみが結果を決定します。
877 * イベントがサポートする各フィールド（`permissionDecision`、`additionalContext`、`updatedInput`、`systemMessage` を含む）が尊重され、フックはエラーとして報告されません。
878 * [決定制御](#decision-control)にはイベントごとの決定フィールドがリストされています。`systemMessage` などのユニバーサル フィールドは [JSON 出力](#json-output)の表に従います。
879* 標準の決定モデルを使用するイベントで、解析されたオブジェクトがスキーマ検証に失敗した場合、[終了 0 の場合](#exit-code-0)と同じ非ブロッキング エラーになります。アクションは進行し、`<hook name> hook error` 通知に検証メッセージが含まれます。
880* Claude Code が [JSON として解析しようとして](#exit-code-0)失敗した stdout の場合、標準の決定モデルを使用するイベントでは、Claude Code は終了 0 の場合と同じ非ブロッキング エラーを報告します。アクションは進行し、通知に解析メッセージが含まれます。
881* Claude Code が[プレーン テキストとして扱う](#exit-code-0) stdout、または空の stdout の場合、ほとんどのフック イベントで非ブロッキング エラーとなります。アクションは進行し、トランスクリプトには `<hook name> hook error` 通知と、その後に `Failed with non-blocking status code:` というプレフィックスが付いた stderr の最初の行が表示されます。完全な stderr を取得するには、[デバッグ ログ](#debug-hooks)を有効にしてください。
882
883標準の決定モデルに含まれないイベントは、[イベントごとの表](#exit-code-2-behavior-per-event)の独自の行に従います。`WorktreeCreate` は JSON の内容にかかわらず 0 以外の終了で作成に失敗し、`StopFailure` のようにフック出力を完全に破棄するイベントは、すべての終了コードで JSON を無視します。ただし、`terminalSequence` のような副作用フィールドは引き続き発火します。
884
885起動できないフックも同じ非ブロッキングの扱いになります。スクリプト パスが存在しないか実行可能でない場合、シェルは 127 などのコードで終了し、インタープリターのメッセージとともに同じ通知が表示されます（例: `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`）。ほとんどのフック イベントでは、アクションは進行します。ポリシー フックを設定するときは、最初の実行時にこの通知に注意してください。`settings.json` でパスを入力ミスすると、ゲートが気付かないうちに無効になります。
886
709<Warning>887<Warning>
710 ほとんどのフック イベントでは、終了コード 2 のみがアクションをブロックします。Claude Code は終了コード 1 を非ブロッキング エラーとして扱い、1 が従来の Unix 失敗コードであっても、アクションを進行させます。フックがポリシーを実施することを目的としている場合は、`exit 2` を使用してください。例外は `WorktreeCreate` で、0 以外の終了コードはワークツリー作成を中止します。888 ほとんどのフック イベントでは、終了コード 2 がコードのみでブロックする唯一の終了コードです。stdout に有効な JSON がない場合、1 が従来の Unix 失敗コードであっても、Claude Code は終了コード 1 を非ブロッキング エラーとして扱い、アクションを進行させます。フックがポリシーを実施することを目的としている場合は、`exit 2` を使用してください。worktree イベントは異なります。`WorktreeCreate` からの 0 以外の終了コードは worktree の作成を中止し、`WorktreeRemove` からの 0 以外の終了コードは、その後もディレクトリが存在する場合に worktree の削除を失敗させます。
711</Warning>889</Warning>
712 890
891<h4 id="timeouts">
892 タイムアウト
893</h4>
894
895[`async: true`](#run-hooks-in-the-background) で実行するコマンド フックを除き、Claude Code は [`timeout`](#common-fields) に達した `command`、`http`、または `mcp_tool` フックをキャンセルし、フックの出力を破棄します。そのため、ほとんどのイベントでは、タイムアウトしたフックは決定を下しません。
896
897[`PreModelSwitch`](#premodelswitch) では、タイムアウトでキャンセルされたフックはモデルの切り替えをブロックします。`PreToolUse` では、2 つのフック ファミリーで動作が異なります。
898
899* タイムアウトした `command`、`http`、または `mcp_tool` フックはツール呼び出しをブロックしません。呼び出しは通常の[権限フロー](/docs/ja/permissions)を通じて続行されるため、停止したフックがゲートとして機能することを当てにしないでください。
900* タイムアウトを超えた [Agent SDK コールバック フック](/docs/ja/agent-sdk/hooks)は[ツール呼び出しをブロックします](#pretooluse)。
901
713<h4 id="exit-code-2-behavior-per-event">902<h4 id="exit-code-2-behavior-per-event">
714 イベントごとの終了コード 2 動作903 イベントごとの終了コード 2 動作
715</h4>904</h4>
719| フック イベント | ブロック可能？ | 終了 2 で何が起こるか |908| フック イベント | ブロック可能？ | 終了 2 で何が起こるか |
720| :- | :- | :- |909| :- | :- | :- |
721| `PreToolUse` | はい | ツール呼び出しをブロック |910| `PreToolUse` | はい | ツール呼び出しをブロック |
722| `PermissionRequest` | はい | 権限を拒否 |911| `PermissionRequest` | いいえ | このイベントでは終了コード 2 は尊重されず、権限フローは変更されずに進行します。代わりに [`decision` オブジェクト](#permissionrequest-decision-control)を通じて拒否してください |
723| `UserPromptSubmit` | はい | プロンプト処理をブロックしてプロンプトを消去 |912| `UserPromptSubmit` | はい | プロンプトをブロックし、Claude に届かないようにします。[ブロックされたプロンプトが残すもの](#what-a-blocked-prompt-leaves-behind)を参照してください |
724| `UserPromptExpansion` | はい | 拡張をブロック |913| `UserPromptExpansion` | はい | 拡張をブロック |
725| `Stop` | はい | Claude が停止するのを防ぎ、会話を続行 |914| `Stop` | はい | Claude が停止するのを防ぎ、会話を続行 |
726| `SubagentStop` | はい | サブエージェントが停止するのを防止 |915| `SubagentStop` | はい | サブエージェントが停止するのを防止 |
727| `TeammateIdle` | はい | チームメイトがアイドル状態になるのを防止（チームメイトが作業を続行） |916| `TeammateIdle` | はい | チームメイトがアイドル状態になるのを防止し、作業を続行させる |
728| `TaskCreated` | はい | タスク作成をロールバック |917| `TaskCreated` | はい | タスク作成をロールバック |
729| `TaskCompleted` | はい | タスクが完了としてマークされるのを防止 |918| `TaskCompleted` | はい | タスクが完了としてマークされるのを防止 |
730| `ConfigChange` | はい | 設定変更が有効になるのをブロック（`policy_settings` を除く） |919| `ConfigChange` | はい | 設定変更が有効になるのをブロック（`policy_settings` を除く） |
731| `StopFailure` | いいえ | 出力と終了コードは無視 |920| `StopFailure` | いいえ | 出力と終了コードは無視（`terminalSequence` を除く） |
732| `PostToolUse` | いいえ | Claude に stderr を表示（ツールはすでに実行） |921| `PostToolUse` | いいえ | Claude に stderr を表示（ツールはすでに実行） |
733| `PostToolUseFailure` | いいえ | Claude に stderr を表示（ツールはすでに失敗） |922| `PostToolUseFailure` | いいえ | Claude に stderr を表示（ツールはすでに失敗） |
734| `PostToolBatch` | はい | 次のモデル呼び出しの前に agentic ループを停止 |923| `PostToolBatch` | はい | 次のモデル呼び出しの前にエージェント型ループを停止 |
735| `PermissionDenied` | いいえ | 終了コードと stderr は無視（拒否はすでに発生）。JSON `hookSpecificOutput.retry: true` を使用してモデルが再試行できることを伝える |924| `PermissionDenied` | いいえ | 終了コードと stderr は無視（拒否はすでに発生）。JSON `hookSpecificOutput.retry: true` を使用してモデルが再試行できることを伝える。Claude Code は[判定のない拒否](#permissiondenied-decision-control)では `retry: true` を無視します |
736| `Notification` | いいえ | ユーザーのみに stderr を表示 |925| `Notification` | いいえ | 終了コードと stderr は無視 |
737| `SubagentStart` | いいえ | ユーザーのみに stderr を表示 |926| `SubagentStart` | いいえ | ユーザーのみに stderr を表示 |
738| `SessionStart` | いいえ | ユーザーのみに stderr を表示 |927| `SessionStart` | いいえ | ユーザーのみに stderr を表示 |
739| `Setup` | いいえ | ユーザーのみに stderr を表示 |928| `Setup` | いいえ | 終了コードと stderr は無視 |
740| `SessionEnd` | いいえ | ユーザーのみに stderr を表示 |929| `SessionEnd` | いいえ | ユーザーのみに stderr を表示 |
741| `CwdChanged` | いいえ | ユーザーのみに stderr を表示 |930| `CwdChanged` | いいえ | ユーザーのみに stderr を表示 |
931| `DirectoryAdded` | いいえ | stderr はデバッグ ログに送られる（ディレクトリはすでに追加済み） |
742| `FileChanged` | いいえ | ユーザーのみに stderr を表示 |932| `FileChanged` | いいえ | ユーザーのみに stderr を表示 |
743| `PreCompact` | はい | コンパクションをブロック |933| `PreCompact` | はい | コンテキスト圧縮をブロック |
744| `PostCompact` | いいえ | ユーザーのみに stderr を表示 |934| `PostCompact` | いいえ | ユーザーのみに stderr を表示 |
935| `PreModelSwitch` | はい | モデルの切り替えをブロックし、ユーザーに stderr を表示 |
936| `PostModelSwitch` | いいえ | ユーザーのみに stderr を表示（モデルはすでに切り替え済み） |
745| `Elicitation` | はい | elicitation を拒否 |937| `Elicitation` | はい | elicitation を拒否 |
746| `ElicitationResult` | はい | レスポンスをブロック（アクションが decline になる） |938| `ElicitationResult` | はい | レスポンスをブロック（アクションが decline になる） |
747| `WorktreeCreate` | はい | 0 以外の終了コードでワークツリー作成が失敗 |939| `WorktreeCreate` | はい | 0 以外の終了コードで worktree 作成が失敗 |
748| `WorktreeRemove` | いいえ | 失敗はデバッグ モードでのみログ |940| `WorktreeRemove` | はい | 0 以外の終了コードは、その後もディレクトリが存在する場合に worktree の削除を失敗させる。ディレクトリがどうなるかについては [WorktreeRemove](#worktreeremove) を参照 |
749| `InstructionsLoaded` | いいえ | 終了コードは無視 |941| `InstructionsLoaded` | いいえ | 終了コードは無視 |
750| `MessageDisplay` | いいえ | 元のテキストが表示される |942| `MessageDisplay` | いいえ | 元のテキストが表示される |
751 943
752`SessionStart`、`Setup`、および `SubagentStart` の場合、終了コード 2 stderr は[非ブロッキング エラー](#exit-code-output)と同じ方法で、トランスクリプトに `<hook name> hook error` 通知としてレンダリングされます。Claude はそれを見ず、セッションまたはサブエージェントは進行します。`SubagentStart` の場合、通知は親会話ではなく、サブエージェント自身のトランスクリプトに表示されます。944`SessionStart`、`SubagentStart`、および `PostModelSwitch` の場合、Claude Code は終了コード 2 の stderr を[非ブロッキング エラー](#exit-code-output)と同じ方法で、トランスクリプトに `<hook name> hook error` 通知としてレンダリングします。Claude はそれを見ず、セッションまたはサブエージェントは進行します。`SubagentStart` の場合、通知は親会話ではなく、サブエージェント自身のトランスクリプトに表示されます。
753
754Claude Code v2.1.199 以降、`SessionStart`、`Setup`、および `SubagentStart` はトランスクリプトに終了コード 2 stderr を表示します。以前のバージョンはデバッグ ログにのみ書き込みました。
755 945
756<h3 id="http-response-handling">946<h3 id="http-response-handling">
757 HTTP レスポンス処理947 HTTP レスポンス処理
758</h3>948</h3>
759 949
760HTTP フックは終了コードと stdout の代わりに HTTP ステータス コードとレスポンス本体を使用します。950HTTP フックは終了コードと stdout の代わりに HTTP ステータス コードとレスポンス本体を使用します。以下の結果はほとんどのイベントに適用されます。`WorktreeCreate` のように[イベントごとの表](#exit-code-2-behavior-per-event)に独自の失敗時の規約を持つイベントは、失敗した HTTP フックにもその規約を適用します。
761 951
762* **2xx で空の本体**: 成功、終了コード 0 で出力なしと同等952* **2xx で空の本体**: 成功、終了コード 0 で出力なしと同等
763* **2xx でプレーン テキスト本体**: 成功、テキストがコンテキストとして追加953* **2xx で JSON オブジェクト本体**: コマンド フックと同じ [JSON 出力](#json-output)スキーマを使用して解析。スキーマ検証に失敗した本体は非ブロッキング エラー
764* **2xx で JSON 本体**: 成功、コマンド フックと同じ[JSON 出力](#json-output)スキーマを使用して解析954* **2xx でその他の本体（プレーン テキストなど）**: 非ブロッキング エラー。2xx 以外のステータスと同じように処理されます。Claude Code はテキストを Claude のコンテキストに追加しません
765* **2xx 以外のステータス**: 非ブロッキング エラー、実行は続行955* **2xx 以外のステータス**: 非ブロッキング エラー、実行は続行
766* **接続失敗またはタイムアウト**: 非ブロッキング エラー、実行は続行956* **接続失敗**: 非ブロッキング エラー、実行は続行
957* **タイムアウト**: [タイムアウト](#timeouts)で説明されているとおり、フックはキャンセルされます
767 958
768コマンド フックとは異なり、HTTP フックはステータス コードのみでブロッキング エラーを通知できません。ツール呼び出しをブロックまたは権限を拒否するには、適切な決定フィールドを含む JSON 本体を持つ 2xx レスポンスを返します。959コマンド フックとは異なり、HTTP フックはステータス コードのみでブロッキング エラーを通知できません。ツール呼び出しをブロックまたは権限を拒否するには、適切な決定フィールドを含む JSON 本体を持つ 2xx レスポンスを返します。
769 960
771 JSON 出力962 JSON 出力
772</h3>963</h3>
773 964
774終了コードで許可またはブロックできますが、JSON 出力はより細かい制御を提供します。終了コード 2 でブロックする代わりに、終了 0 して stdout に JSON オブジェクトを出力します。Claude Code はその JSON から特定のフィールドを読み取り、ブロック、許可、またはユーザーへのエスカレーションを含む[決定制御](#decision-control)を通じた動作を制御します。965終了コードではブロックするか何もしないかしか選べませんが、JSON 出力はより細かい制御を提供します。終了コード 2 でブロックする代わりに、終了 0 して stdout に JSON オブジェクトを出力します。Claude Code はその JSON から特定のフィールドを読み取り、ブロック、許可、またはユーザーへのエスカレーションのための[決定制御](#decision-control)を含む動作を制御します。
775 966
776<Note>967<Note>
777 フックごとに 1 つのアプローチを選択する必要があります。両方ではありません。終了コードのみでシグナリングするか、終了 0 して構造化制御のために JSON を出力するかのいずれかです。Claude Code は終了 0 でのみ JSON を処理します。終了 2 の場合、JSON は無視されます。968 フックごとに 1 つのアプローチを選択してください。終了コードのみでシグナリングするか、終了 0 して構造化制御のために JSON を出力するかのいずれかです。両方を混在させた場合、終了 2 は[ブロッキング効果](#exit-code-2-behavior-per-event)を維持し、Claude Code は引き続き JSON フィールドを読み取ります。ただし、[終了コード 2](#exit-code-2) で説明されている elicitation の例外が 1 つあります。
778</Note>969</Note>
779 970
780フックの stdout には JSON オブジェクトのみが含まれている必要があります。シェル プロファイルがスタートアップ時にテキストを出力する場合、JSON 解析に干渉する可能性があります。トラブルシューティング ガイドの[JSON 検証に失敗](/docs/ja/hooks-guide#json-validation-failed)を参照してください。971フックの stdout には JSON オブジェクトのみが含まれている必要があります。シェル プロファイルがスタートアップ時にテキストを出力する場合、JSON 解析に干渉する可能性があります。トラブルシューティング ガイドの[フックの JSON が効果を持たない](/docs/ja/hooks-guide#hook-json-has-no-effect)を参照してください。
781 972
782フック出力文字列（`additionalContext`、`systemMessage`、およびプレーン stdout を含む）は 10,000 文字でキャップされます。この制限を超える出力はファイルに保存され、プレビューとファイル パスに置き換えられます。大きなツール結果と同じ方法で処理されます。973フックの `additionalContext`、`systemMessage`、`initialUserMessage` の文字列、およびプレーン stdout は 10,000 文字に制限されています。
974
975* **スコープ**: 同じイベントに対して複数のフックが実行される場合でも、Claude Code は各文字列を個別に計測します。JSON 出力の場合、各フィールドは個別に計測されます。プレーン stdout は全体として計測されます。
976* **制限を超えた場合**: Claude Code は出力をセッション ディレクトリ内のファイルに保存し、ファイル パスと最初の最大 2,000 文字のプレビューに置き換えます。大きな有効な Bash 結果も同じ方法で処理されます（[出力制限](/docs/ja/tools-reference#output-limits)で説明）。その Bash の上限とは異なり、この上限を引き上げる設定や環境変数はありません。
977* **ファイルの読み取り**: Claude Code は Claude にファイルを読むよう求めないため、Claude が常に確認する必要があるものは上限内に収めてください。
783 978
784JSON オブジェクトは 3 種類のフィールドをサポートしています。979JSON オブジェクトは 3 種類のフィールドをサポートしています。
785 980
786* **`continue` などのユニバーサル フィールド**はすべてのイベント全体で機能します。これらは以下の表にリストされています。981* **`continue` などのユニバーサル フィールド**は以下の表にリストされています。すべてのイベントがこれらを受け入れますが、一部のイベントはこれらを破棄するか、`systemMessage` をトランスクリプト以外の場所に配信します。各イベントのセクションにその旨が記載されています。`terminalSequence` もそれらのイベントで機能しますが、[ターミナル通知を発行](#emit-terminal-notifications)に記載されている例外があります。
787* **トップレベルの `decision` と `reason`** は一部のイベントで使用され、ブロックまたはフィードバックを提供します。982* **トップレベルの `decision` と `reason`** は一部のイベントで使用され、ブロックまたはフィードバックを提供します。
788* **`hookSpecificOutput`** はより豊かな制御が必要なイベント用のネストされたオブジェクトです。イベント名に設定された `hookEventName` フィールドが必要です。983* **`hookSpecificOutput`** はより豊かな制御が必要なイベント用のネストされたオブジェクトです。イベント名に設定された `hookEventName` フィールドが必要です。
789 984
790| フィールド | デフォルト | 説明 |985| フィールド | デフォルト | 説明 |
791| :- | :- | :- |986| :- | :- | :- |
792| `continue` | `true` | `false` の場合、フックが実行された後、Claude は完全に処理を停止します。イベント固有の決定フィールドよりも優先されます |987| `continue` | `true` | `false` の場合、フックが実行された後、Claude は完全に処理を停止します。イベント固有の決定フィールドよりも優先されます |
793| `stopReason` | なし | `continue` が `false` のときにユーザーに表示されるメッセージ。Claude には表示されません |988| `stopReason` | なし | `continue` が `false` のときにユーザーに表示されるメッセージ。会話に残るため、会話が続行された場合は Claude にも表示されます |
794| `suppressOutput` | `false` | `true` の場合、デバッグ ログから stdout を非表示にします |989| `suppressOutput` | `false` | 効果はありません。Claude Code はこのフィールドを受け入れますが、それに基づいて動作しません。成功したフックの stdout はトランスクリプトに表示されることはなく、デバッグ ログに記録されます |
795| `systemMessage` | なし | ユーザーに表示される警告メッセージ |990| `systemMessage` | なし | ユーザーに表示される警告メッセージ。[Agent SDK](/docs/ja/agent-sdk/overview) および [`--output-format stream-json`](/docs/ja/headless) の出力では、[`SDKInformationalMessage`](/docs/ja/agent-sdk/typescript#sdkinformationalmessage) として届く場合があります |
796| `terminalSequence` | なし | Claude Code が代わりに発行するターミナル エスケープ シーケンス（デスクトップ通知、ウィンドウ タイトル、ベルなど）。OSC `0`/`1`/`2`/`9`/`99`/`777` と BEL に制限されます。値に許可リスト外のものが含まれている場合、フィールドは無視されます。`/dev/tty` が利用できないフックの代わりにこれを使用してください |991| `terminalSequence` | なし | Claude Code が代わりに発行するターミナル エスケープ シーケンス（デスクトップ通知、ウィンドウ タイトル、ベルなど）。OSC `0`/`1`/`2`/`9`/`99`/`777` と BEL に制限されます。値に許可リスト外のものが含まれている場合、フィールドは無視されます。フックでは利用できない `/dev/tty` への書き込みの代わりにこれを使用してください |
797 992
798Claude を完全に停止するには、イベント タイプに関係なく。993Claude を完全に停止するには、次のようにします。
799 994
800```json theme={null}995```json theme={null}
801{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }996{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
802```997```
803 998
999`PreToolUse` および `PostToolUse` フックの場合、Claude がまだ応答をストリーミングしている間にツール呼び出しが失敗または完了した場合でも、停止が適用されます。
1000
804<h4 id="emit-terminal-notifications">1001<h4 id="emit-terminal-notifications">
805 ターミナル通知を発行1002 ターミナル通知を発行
806</h4>1003</h4>
807 1004
808`terminalSequence` フィールドには Claude Code v2.1.141 以降が必要です。1005フックは制御ターミナルなしで実行されるため、エスケープ シーケンスを `/dev/tty` に直接書き込むことは失敗します。代わりに、エスケープ シーケンスを `terminalSequence` フィールドで返し、Claude Code は独自のターミナル書き込みパスを通じてそれを発行します。これはレース フリーで、tmux と GNU screen 内で機能し、`/dev/tty` がない Windows で機能します。
809
810フックは制御端末なしで実行されるため、エスケープ シーケンスを `/dev/tty` に直接書き込むことは失敗します。代わりに、エスケープ シーケンスを `terminalSequence` フィールドで返し、Claude Code は独自のターミナル書き込みパスを通じてそれを発行します。これはレース フリーで、tmux と GNU screen 内で機能し、`/dev/tty` がない Windows で機能します。
811 1006
812フィールドは 1 つ以上の許可リストに登録されたエスケープ シーケンスの文字列を受け入れます。1007フィールドは 1 つ以上の許可リストに登録されたエスケープ シーケンスの文字列を受け入れます。
813 1008
819 1014
820シーケンスは BEL または ST で終了する場合があります。許可リスト外のもの（CSI カーソルと色シーケンス、OSC パレット シーケンス、OSC 8 ハイパーリンク、OSC 52 クリップボード書き込み、OSC 1337 を含む）は拒否され、フィールドは無視されます。1015シーケンスは BEL または ST で終了する場合があります。許可リスト外のもの（CSI カーソルと色シーケンス、OSC パレット シーケンス、OSC 8 ハイパーリンク、OSC 52 クリップボード書き込み、OSC 1337 を含む）は拒否され、フィールドは無視されます。
821 1016
1017Claude Code はフックの出力を処理するときにシーケンス自体を書き込むため、このフィールドは `Notification` や `StopFailure` など、`systemMessage` と `continue` を破棄するイベントでも機能します。ただし、2 つの制限があります。
1018
1019* Claude Code は対話セッションでのみ、かつそのインターフェイスが画面に表示されている間のみシーケンスを書き込みます。`-p` フラグを使用した非対話モードおよび Agent SDK では、このフィールドは無視されます。
1020* `WorktreeCreate` コマンド フックは JSON を返せません。Claude Code はその stdout を worktree パスとして読み取るためです。HTTP `WorktreeCreate` フックは JSON を返すため、このフィールドを含めることができます。
1021
822以下の例は `Notification` フックからデスクトップ通知を発火します。エスケープ シーケンスは `printf` 8 進数エスケープで構築されるため、制御バイトはシェル コマンド ラインに表示されず、`jq -n --arg` は JSON 出力を構築するため、通知メッセージの引用符、バックスラッシュ、改行は正しくエスケープされます。1022以下の例は `Notification` フックからデスクトップ通知を発火します。エスケープ シーケンスは `printf` 8 進数エスケープで構築されるため、制御バイトはシェル コマンド ラインに表示されず、`jq -n --arg` は JSON 出力を構築するため、通知メッセージの引用符、バックスラッシュ、改行は正しくエスケープされます。
823 1023
824```bash theme={null}1024```bash theme={null}
825#!/bin/bash1025#!/bin/bash
826# Notification フック: Claude Code が注意を必要とするときにデスクトップに ping を送信します。1026# Notification hook: ping the desktop when Claude Code needs attention.
827input=$(cat)1027input=$(cat)
828title="Claude Code'1028title="Claude Code"
829body=$(jq -r '.message // 'Needs your attention"' <<<"$input")1029body=$(jq -r '.message // "Needs your attention"' <<<"$input")
830seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")1030seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
831jq -nc --arg seq "$seq" '{terminalSequence: $seq}'1031jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
832```1032```
833 1033
834`{ "terminalSequence": "..." }` の形状は、任意のシェルまたは言語から同じです。Windows では、PowerShell またはスクリプトでエスケープ文字列を構築し、同じ JSON オブジェクトを発行します。1034`{ "terminalSequence": "..." }` の形状は、任意のシェルまたは言語から同じです。
835
836<Note>
837 `terminalSequence` は、以前に `/dev/tty` にエスケープ シーケンスを直接書き込んでいたフックの対応する置き換えです。許可リストはカーソルを移動したり色を変更したりできないシーケンスに制限されているため、フックはオンスクリーン プロンプトを破損することはできません。
838</Note>
839 1035
840<h4 id="add-context-for-claude">1036<h4 id="add-context-for-claude">
841 Claude 用にコンテキストを追加1037 Claude 用にコンテキストを追加
842</h4>1038</h4>
843 1039
844`additionalContext` フィールドは、フックから Claude のコンテキスト ウィンドウに文字列を渡します。Claude Code は文字列をシステム リマインダーでラップし、フックが発火した時点で会話に挿入します。Claude は次のモデル リクエストでリマインダーを読み取りますが、インターフェイスではチャット メッセージとして表示されません。1040`additionalContext` フィールドは、フックから Claude のコンテキストウィンドウに文字列を渡します。Claude Code は文字列を[システムリマインダー](/docs/ja/glossary#system-reminder)でラップし、フックが発火した時点で会話に挿入します。Claude は次のモデル リクエストでリマインダーを読み取りますが、インターフェイスではチャット メッセージとして表示されません。
845 1041
846`hookSpecificOutput` 内でイベント名と一緒に `additionalContext` を返します。1042`hookSpecificOutput` 内でイベント名と一緒に `additionalContext` を返します。
847 1043
856 1052
857リマインダーが表示される場所はイベントに依存します。1053リマインダーが表示される場所はイベントに依存します。
858 1054
859* [SessionStart](#sessionstart)、[Setup](#setup)、および [SubagentStart](#subagentstart): 会話の開始時、最初のプロンプトの前1055* [SessionStart](#sessionstart) および [SubagentStart](#subagentstart): 会話の開始時、最初のプロンプトの前
860* [UserPromptSubmit](#userpromptsubmit) および [UserPromptExpansion](#userpromptexpansion): 送信されたプロンプトの横1056* [UserPromptSubmit](#userpromptsubmit) および [UserPromptExpansion](#userpromptexpansion): 送信されたプロンプトの横
861* [PreToolUse](#pretooluse)、[PostToolUse](#posttooluse)、[PostToolUseFailure](#posttoolusefailure)、および [PostToolBatch](#posttoolbatch): ツール結果の横1057* [PreToolUse](#pretooluse)、[PostToolUse](#posttooluse)、[PostToolUseFailure](#posttoolusefailure)、および [PostToolBatch](#posttoolbatch): ツール結果の横
862* [Stop](#stop) および [SubagentStop](#subagentstop): ターンの終了時。会話は続行されるため、Claude はフィードバックに対応できます。[Stop 決定制御](#stop-decision-control)を参照してください1058* [Stop](#stop) および [SubagentStop](#subagentstop): ターンの終了時。会話は続行されるため、Claude はフィードバックに対応できます。[Stop 決定制御](#stop-decision-control)を参照してください
1059* [PostModelSwitch](#postmodelswitch): 切り替え後の次のリクエストとともに。タイミングについては [PostModelSwitch 決定制御](#postmodelswitch-decision-control)を参照してください
863 1060
864複数のフックが同じイベントに対して `additionalContext` を返す場合、Claude はすべての値を受け取ります。値が 10,000 文字を超える場合、Claude Code はセッション ディレクトリ内のファイルに完全なテキストを書き込み、短いプレビューとファイル パスを Claude に渡します。1061複数のフックが同じイベントに対して `additionalContext` を返す場合、Claude はすべての値を受け取ります。
1062
1063値が 10,000 文字を超える場合、Claude Code はテキストをセッション ディレクトリ内のファイルに書き込み、代わりにファイル パスと最初の最大 2,000 文字のプレビューを Claude に渡します。Claude はファイルを読むことができますが、Claude Code はそれを読むよう求めません。
865 1064
866Claude が現在の環境の状態または実行されたばかりの操作について知っておくべき情報に `additionalContext` を使用します。1065Claude が現在の環境の状態または実行されたばかりの操作について知っておくべき情報に `additionalContext` を使用します。
867 1066
868* **環境状態**: 現在のブランチ、デプロイ ターゲット、またはアクティブな機能フラグ1067* **環境状態**: 現在のブランチ、デプロイ ターゲット、またはアクティブな機能フラグ
869* **条件付きプロジェクト ルール**: 編集されたばかりのファイルに適用されるテスト コマンド、このワークツリーで読み取り専用のディレクトリ1068* **条件付きプロジェクト ルール**: 編集されたばかりのファイルに適用されるテスト コマンド、この worktree で読み取り専用のディレクトリ
870* **外部データ**: 割り当てられたオープン イシュー、最近の CI 結果、内部サービスから取得されたコンテンツ1069* **外部データ**: 割り当てられたオープン イシュー、最近の CI 結果、内部サービスから取得されたコンテンツ
871 1070
872変わらない指示については、[CLAUDE.md](/docs/ja/memory)を優先します。スクリプトを実行せずに読み込まれ、静的なプロジェクト規約の標準的な場所です。1071変わらない指示については、[CLAUDE.md](/docs/ja/memory) を優先します。スクリプトを実行せずに読み込まれ、静的なプロジェクト規約の標準的な場所です。
873 1072
874テキストを命令型システム指示ではなく、事実的なステートメントとして記述します。「デプロイ ターゲットは本番環境です」または「このリポジトリは `bun test` を使用します」などのフレーズはプロジェクト情報として読み取られます。帯域外システム コマンドとしてフレーム化されたテキストは Claude のプロンプト インジェクション防御をトリガーする可能性があり、Claude がテキストをコンテキストとして扱う代わりに表示します。1073テキストを命令型システム指示ではなく、事実的なステートメントとして記述します。「デプロイ ターゲットは本番環境です」または「このリポジトリは `bun test` を使用します」などのフレーズはプロジェクト情報として読み取られます。帯域外システム コマンドとしてフレーム化されたテキストは Claude のプロンプトインジェクション防御をトリガーする可能性があり、その場合 Claude はテキストをコンテキストとして扱う代わりにユーザーに提示します。
875 1074
876注入されたテキストはセッション トランスクリプトに保存されます。`PostToolUse` または `UserPromptSubmit` などの中盤イベントの場合、`--continue` または `--resume` で再開すると、フックを再実行する代わりに保存されたテキストが再生されるため、タイムスタンプやコミット SHA などの値は再開時に古くなります。`SessionStart` フックは `source` を `"resume"` に設定して再開時に再度実行されるため、コンテキストをリフレッシュできます。1075Claude Code は注入されたテキストをセッション トランスクリプトに保存します。`PostToolUse` や `UserPromptSubmit` などのセッション途中のイベントの場合、`--continue` または `--resume` で再開すると、Claude Code は過去のターンについてフックを再実行するのではなく保存されたテキストを再生するため、タイムスタンプやコミット SHA などの値は古くなります。`SessionStart` フックは再開時に `source` を `"resume"`（`--fork-session` を追加した場合は `"fork"`）に設定して再度実行されるため、コンテキストをリフレッシュできます。
877 1076
878<h4 id="decision-control">1077<h4 id="decision-control">
879 決定制御1078 決定制御
884| イベント | 決定パターン | キー フィールド |1083| イベント | 決定パターン | キー フィールド |
885| :- | :- | :- |1084| :- | :- | :- |
886| UserPromptSubmit、UserPromptExpansion、PostToolUse、PostToolUseFailure、PostToolBatch、Stop、SubagentStop、ConfigChange、PreCompact | トップレベル `decision` | `decision: "block"`、`reason`。Stop と SubagentStop は[会話を続行する非エラー フィードバック](#stop-decision-control)のために `hookSpecificOutput.additionalContext` も受け入れます |1085| UserPromptSubmit、UserPromptExpansion、PostToolUse、PostToolUseFailure、PostToolBatch、Stop、SubagentStop、ConfigChange、PreCompact | トップレベル `decision` | `decision: "block"`、`reason`。Stop と SubagentStop は[会話を続行する非エラー フィードバック](#stop-decision-control)のために `hookSpecificOutput.additionalContext` も受け入れます |
887| TeammateIdle、TaskCreated、TaskCompleted | 終了コードまたは `continue: false` | 終了コード 2 はアクションをブロックし、stderr フィードバックを使用します。JSON `{"continue": false, "stopReason": "..."}` はチームメイト全体を停止し、`Stop` フック動作と一致します |1086| TeammateIdle、TaskCompleted | 終了コードまたは `continue: false` | 終了コード 2 は stderr フィードバックとともにアクションをブロックします。JSON `{"continue": false, "stopReason": "..."}` もチームメイトを完全に停止し、`Stop` フックの動作と一致します。[`TaskUpdate` ツールがイベントをトリガーした場合、TaskCompleted はこれを無視します](#taskcompleted-decision-control) |
1087| TaskCreated | 終了コードまたはトップレベル `decision` | 終了コード 2 または `decision: "block"` は[タスクをキャンセル](#taskcreated-decision-control)し、メッセージを Claude に返します。`continue: false` は無視されます |
888| PreToolUse | `hookSpecificOutput` | `permissionDecision`（allow/deny/ask/defer）、`permissionDecisionReason` |1088| PreToolUse | `hookSpecificOutput` | `permissionDecision`（allow/deny/ask/defer）、`permissionDecisionReason` |
1089| PreModelSwitch | `hookSpecificOutput` またはトップレベル `decision` | `permissionDecision`（allow/deny/ask）、`permissionDecisionReason`。`decision: "block"` も[切り替えをキャンセル](#premodelswitch-decision-control)します |
889| PermissionRequest | `hookSpecificOutput` | `decision.behavior`（allow/deny） |1090| PermissionRequest | `hookSpecificOutput` | `decision.behavior`（allow/deny） |
890| PermissionDenied | `hookSpecificOutput` | `retry: true` はモデルが拒否されたツール呼び出しを再試行できることを伝える |1091| PermissionDenied | `hookSpecificOutput` | `retry: true` はモデルが拒否されたツール呼び出しを再試行できることを伝えます。Claude Code は[判定のない拒否](#permissiondenied-decision-control)ではこれを無視します |
891| WorktreeCreate | パス戻り値 | コマンド フックは stdout にパスを出力します。HTTP フックは `hookSpecificOutput.worktreePath` 経由で返します。フック失敗またはパス欠落で作成が失敗 |1092| WorktreeCreate | パス戻り値 | コマンド フックは stdout にパスを出力します。HTTP フックは `hookSpecificOutput.worktreePath` を返します。フック失敗またはパス欠落で作成が失敗 |
1093| WorktreeRemove | 終了コード | 0 以外の終了コードは、その後もディレクトリが存在する場合に削除を失敗させます。JSON 出力は破棄されます |
892| Elicitation | `hookSpecificOutput` | `action`（accept/decline/cancel）、`content`（accept の場合のフォーム フィールド値） |1094| Elicitation | `hookSpecificOutput` | `action`（accept/decline/cancel）、`content`（accept の場合のフォーム フィールド値） |
893| ElicitationResult | `hookSpecificOutput` | `action`（accept/decline/cancel）、`content`（フォーム フィールド値をオーバーライド） |1095| ElicitationResult | `hookSpecificOutput` | `action`（accept/decline/cancel）、`content`（フォーム フィールド値を上書き） |
894| MessageDisplay | `hookSpecificOutput` | `displayContent` は画面に表示されるテキストを置き換えます。表示のみ: トランスクリプトと Claude が見るものは元のままです |1096| MessageDisplay | `hookSpecificOutput` | `displayContent` は画面に表示されるテキストを置き換えます。表示のみ: トランスクリプトと Claude が見るものは元のままです |
895| SessionStart、Setup、SubagentStart | コンテキストのみ | `hookSpecificOutput.additionalContext` は Claude 用にコンテキストを追加します。SessionStart は [`initialUserMessage`、`watchPaths`、`sessionTitle`、および `reloadSkills`](#sessionstart-decision-control)も受け入れます。ブロッキングまたは決定制御なし |1097| SessionStart、SubagentStart、PostModelSwitch | コンテキストのみ | `hookSpecificOutput.additionalContext` は Claude 用にコンテキストを追加します。SessionStart は [`initialUserMessage`、`watchPaths`、`sessionTitle`、および `reloadSkills`](#sessionstart-decision-control) も受け入れます。ブロッキングまたは決定制御なし |
896| WorktreeRemove、Notification、SessionEnd、PostCompact、InstructionsLoaded、StopFailure、CwdChanged、FileChanged | なし | 決定制御なし。ログやクリーンアップなどの副作用に使用 |1098| Setup、Notification、SessionEnd、PostCompact、InstructionsLoaded、StopFailure、CwdChanged、DirectoryAdded、FileChanged | なし | 決定制御なし。ログやクリーンアップなどの副作用に使用 |
897 1099
898いくつかのイベントは、許可またはブロックするだけでなく、コンテンツを書き直すこともできます。1100いくつかのイベントは、許可またはブロックするだけでなく、コンテンツを書き直すこともできます。
899 1101
902* `PostToolUse`: `updatedToolOutput` はツールの結果を置き換えます。[PostToolUse 決定制御](#posttooluse-decision-control)を参照してください1104* `PostToolUse`: `updatedToolOutput` はツールの結果を置き換えます。[PostToolUse 決定制御](#posttooluse-decision-control)を参照してください
903* `UserPromptSubmit`: プロンプトを置き換えることはできません。`additionalContext` をそれと一緒に注入するだけです1105* `UserPromptSubmit`: プロンプトを置き換えることはできません。`additionalContext` をそれと一緒に注入するだけです
904 1106
905編集またはトランスフォーメーション ユースケースの場合、アウトバウンド ツール入力の場合は `PreToolUse` で、インバウンド ツール結果の場合は `PostToolUse` で傍受します。1107秘匿化や変換のユースケースの場合、アウトバウンド ツール入力の場合は `PreToolUse` で、インバウンド ツール結果の場合は `PostToolUse` で傍受します。
906 1108
907各パターンの実行例を以下に示します。1109各パターンの実行例を以下に示します。
908 1110
909<Tabs>1111<Tabs>
910 <Tab title="トップレベル決定">1112 <Tab title="トップレベル決定">
911 `UserPromptSubmit`、`UserPromptExpansion`、`PostToolUse`、`PostToolUseFailure`、`PostToolBatch`、`Stop`、`SubagentStop`、`ConfigChange`、`PreCompact` で使用されます。唯一の値は `"block"` です。アクションを進行させるには、JSON から `decision` を省略するか、JSON なしで終了 0 で終了します。1113 `decision` の唯一の値は `"block"` です。アクションを進行させるには、JSON から `decision` を省略するか、JSON なしで終了 0 で終了します。
912 1114
913 ```json theme={null}1115 ```json theme={null}
914 {1116 {
951 </Tab>1153 </Tab>
952</Tabs>1154</Tabs>
953 1155
954Bash コマンド検証、プロンプト フィルタリング、自動承認スクリプトを含む拡張例については、ガイドの[自動化できること](/docs/ja/hooks-guide#what-you-can-automate)と[Bash コマンド バリデーター リファレンス実装](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)を参照してください。1156Bash コマンド検証、プロンプト フィルタリング、自動承認スクリプトを含む拡張例については、ガイドの[自動化できること](/docs/ja/hooks-guide#what-you-can-automate)と [Bash コマンド バリデーター リファレンス実装](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)を参照してください。
955 1157
956<h2 id="hook-events">1158<h2 id="hook-events">
957 フック イベント1159 フックイベント
958</h2>1160</h2>
959 1161
960各イベントは Claude Code のライフサイクル内のポイントに対応し、フックが実行できます。以下のセクションはライフサイクルに一致する順序で配置されています。セッション セットアップから agentic ループを経由してセッション終了まで。各セクションでは、イベントがいつ発火するか、サポートするマッチャー、受け取る JSON 入力、出力を通じた動作制御方法について説明しています。1162各イベントは、フックを実行できる Claude Code のライフサイクル上のポイントに対応しています。以下のセクションはライフサイクルに沿って、セッションのセットアップからエージェント型ループを経てセッション終了までの順に並んでいます。各セクションでは、イベントが発火するタイミング、サポートする matcher、受け取る JSON 入力、出力を通じて動作を制御する方法を説明します。
961 1163
962<h3 id="sessionstart">1164<h3 id="sessionstart">
963 SessionStart1165 SessionStart
964</h3>1166</h3>
965 1167
966Claude Code が新しいセッションを開始するか、既存のセッションを再開するときに実行されます。既存の問題や最近のコードベース変更など、開発コンテキストをロードしたり、環境変数をセットアップしたりするのに便利です。静的コンテキストでスクリプトが不要な場合は、代わりに[CLAUDE.md](/docs/ja/memory)を使用してください。1168Claude Code が新しいセッションを開始するとき、または既存のセッションを再開するときに実行されます。既存の issue やコードベースの最近の変更などの開発コンテキストの読み込みや、環境変数の設定に役立ちます。スクリプトを必要としない静的なコンテキストには、代わりに [CLAUDE.md](/docs/ja/memory) を使用してください。
967 1169
968SessionStart はすべてのセッションで実行されるため、これらのフックを高速に保ちます。`type: "command"` と `type: "mcp_tool"` フックのみがサポートされています。1170SessionStart はすべてのセッションで実行されるため、これらのフックは高速に保ってください。サポートされているのは `type: "command"` と `type: "mcp_tool"` のフックのみです。`mcp_tool` フックが実行されるタイミングについては、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)を参照してください。
969 1171
970マッチャー値はセッションがどのように開始されたかに対応しています。1172matcher の値は、セッションがどのように開始されたかに対応します：
971 1173
972| マッチャー | いつ発火するか |1174| Matcher | 発火するタイミング |
973| :- | :- |1175| :- | :- |
974| `startup` | 新しいセッション |1176| `startup` | 新しいセッション |
975| `resume` | `--resume`、`--continue`、または `/resume` |1177| `resume` | `--resume`、`--continue`、または `/resume` |
976| `clear` | `/clear` |1178| `clear` | `/clear` |
977| `compact` | 自動またはマニュアル コンパクション |1179| `compact` | 自動または手動のコンテキスト圧縮 |
1180| `fork` | 既存のセッションからフォークされた新しいセッション：`--resume` または `--continue` と併用した `--fork-session`、`/fork` のバックグラウンドコピー、`/branch`、または[バックグラウンドに移動](/docs/ja/agent-view#from-inside-a-session)した会話 |
1181
1182v2.1.214 より前は、フォークされたセッションはソースとして `"resume"` を報告していました。
1183
1184対話セッションを開始したとき、起動時に `--continue` または `--resume` で会話を再開したとき、または `/clear` を実行したとき、SessionStart フックはバックグラウンドで実行されます。すぐに入力を開始でき、再開した会話はフックを待たずに表示されます。ただし Claude の最初の応答はフックの完了を待つため、フックのコンテキストは Claude に届きます。
1185
1186セッション内で `/resume` を使って会話を切り替える場合は、代わりに切り替えがフックの完了を待ちます。バックグラウンドのフックがまだ実行中に `/clear` を実行したり別の会話に切り替えたりした場合、フックが返す内容はセッションに一切適用されません。
1187
1188起動時にも、再開したセッションを含めて同じ待機が適用されます。SessionStart フックの実行中に送信したプロンプトは、フックが完了するまで Claude に届きません。
1189
1190いずれの待機中も、`Esc` を押すとプロンプトを送信せずに入力欄に戻せます。フックは実行を続けます。
978 1191
979<h4 id="sessionstart-input">1192<h4 id="sessionstart-input">
980 SessionStart 入力1193 SessionStart の入力
981</h4>1194</h4>
982 1195
983[共通入力フィールド](#common-input-fields)に加えて、SessionStart フックは `source` と、オプションで `model`、`agent_type`、`session_title` を受け取ります。1196[共通の入力フィールド](#common-input-fields)に加えて、SessionStart フックは `source` と、オプションで `model`、`agent_type`、`session_title` を受け取ります：
1197
1198| フィールド | 説明 |
1199| :- | :- |
1200| `source` | セッションの開始方法：新しいセッションの場合は `"startup"`、再開したセッションの場合は `"resume"`、`/clear` の後は `"clear"`、コンテキスト圧縮の後は `"compact"`、既存のセッションからフォークされた新しいセッションの場合は `"fork"` |
1201| `model` | アクティブなモデルの識別子。たとえば `/clear` の後や、会話の復旧によってセッションが復元された場合などには省略されることがあるため、読み取る前にフィールドの有無を確認してください |
1202| `agent_type` | エージェント名。`claude --agent <name>` で Claude Code を起動した場合に存在します |
1203| `session_title` | セッションのカスタムタイトル。設定されている場合に存在します。たとえば `--name`、`/rename`、フックの `sessionTitle` 出力、または Agent SDK の `renameSession()` で設定されます。`sessionTitle` を出力するフックは、既存のカスタムタイトルの上書きを避けるために、まずこのフィールドを確認できます |
1204
1205名前を付けていないセッションでも、[生成されたタイトル](/docs/ja/sessions#name-your-sessions)を持つことがあります。そのタイトルはカスタムタイトルではなく、`session_title` には含まれません。
1206
1207`source` が `"resume"` または `"fork"` で、トランスクリプトに Claude からの応答が少なくとも 1 つ含まれる場合、SessionStart フックは以下の 4 つのフィールドも受け取ります。フックはこれらを使って、古い会話を再開する際のコストを最初のリクエストの前に報告できます。たとえば [`systemMessage`](#json-output) で報告します。これらのフィールドには Claude Code v2.1.251 以降が必要です。
984 1208
985| フィールド | 説明 |1209| フィールド | 説明 |
986| :- | :- |1210| :- | :- |
987| `source` | セッションがどのように開始されたか: 新しいセッションの場合は `"startup"`、再開されたセッションの場合は `"resume"`、`/clear` の後は `"clear"`、コンパクション後は `"compact"` |1211| `seconds_since_last_response` | 再開したトランスクリプト内の最後の応答からの経過秒数（実時間） |
988| `model` | アクティブなモデル識別子。例えば `/clear` の後、またはセッションが会話復旧を通じて復元されるときなど、フィールドが省略される可能性があるため、読み取る前にフィールドをチェックしてください |1212| `context_tokens` | 再開したセッションの最初のリクエストがプロンプトとして再送信するトークン数 |
989| `agent_type` | `claude --agent <name>` で Claude Code を開始する場合、エージェント名が存在 |1213| `prompt_cache_likely_expired` | 最後の応答がセッションの[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime)より古い場合、またはその後のコンテキスト圧縮によってキャッシュされた会話が置き換えられた場合に `true` |
990| `session_title` | 例えば `--name` または `/rename` 経由で既に設定されている場合、現在のセッション タイトル。`sessionTitle` を発行するフックは、ユーザーが明示的に設定したタイトルを上書きしないように、最初に `session_title` をチェックできます |1214| `estimated_cache_write_usd` | セッションのモデルで `context_tokens` をプロンプトキャッシュに書き込む推定コスト（米ドル）。応答は含みません |
1215
1216この例は、最後の応答から 90 分後に再開されたセッションの入力を示しています：
991 1217
992```json theme={null}1218```json theme={null}
993{1219{
995 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1221 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
996 "cwd": "/Users/...",1222 "cwd": "/Users/...",
997 "hook_event_name": "SessionStart",1223 "hook_event_name": "SessionStart",
998 "source": "startup",1224 "source": "resume",
999 "model": "claude-sonnet-5"1225 "model": "claude-opus-5",
1226 "seconds_since_last_response": 5400,
1227 "context_tokens": 182340,
1228 "prompt_cache_likely_expired": true,
1229 "estimated_cache_write_usd": 1.1396
1000}1230}
1001```1231```
1002 1232
1003<h4 id="sessionstart-decision-control">1233<h4 id="sessionstart-decision-control">
1004 SessionStart 決定制御1234 SessionStart の決定制御
1005</h4>1235</h4>
1006 1236
1007フック スクリプトが stdout に出力するテキストは Claude のコンテキストとして追加されます。すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、これらのイベント固有のフィールドを返すことができます。1237Claude Code は、[プレーンテキストとして扱う](#exit-code-0) stdout を Claude のコンテキストに追加します。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、次のイベント固有のフィールドを返すことができます：
1008 1238
1009| フィールド | 説明 |1239| フィールド | 説明 |
1010| :- | :- |1240| :- | :- |
1011| `additionalContext` | Claude のコンテキストの開始時に追加される文字列。最初のプロンプトの前。[Claude のコンテキストを追加](#add-context-for-claude)を参照して、テキストがどのように配信されるか、何を含めるかを確認してください |1241| `additionalContext` | 会話の開始時、最初のプロンプトの前に Claude のコンテキストに追加される文字列。テキストがどのように渡されるか、何を含めるべきかについては [Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1012| `initialUserMessage` | セッションの最初のユーザー メッセージとして使用される文字列。[非対話型モード](/docs/ja/headless)で `-p` フラグで適用され、プロンプトが提供されない場合でも最初のターンになります。プロンプトが提供される場合、次のターンとして続きます。`additionalContext` とは異なり、既存のターンに付加されるのではなく、このターンを作成します |1242| `initialUserMessage` | セッションの最初のユーザーメッセージとして使用される文字列。`-p` フラグを使用した[非対話モード](/docs/ja/headless)で適用され、プロンプトが指定されていなくても最初のターンになります。プロンプトが指定されている場合は、それが次のターンとして続きます。既存のターンに付加される `additionalContext` とは異なり、これはターンそのものを作成します |
1013| `sessionTitle` | セッション タイトルを設定します。`/rename` と同じ効果があります。起動フォルダ、git ブランチ、またはワークツリー名からセッションを自動的に名前付けするのに使用します。`source` が `"startup"` または `"resume"` の場合のみ適用されます。`"clear"` と `"compact"` では無視されます |1243| `sessionTitle` | セッションタイトルを設定します。`/rename` と同じ効果があります。起動フォルダ、git ブランチ、または worktree 名からセッションに自動的に名前を付けるために使用します。`source` が `"startup"`、`"resume"`、または `"fork"` の場合に適用され、`"clear"` と `"compact"` では無視されます |
1014| `watchPaths` | このセッション中に[FileChanged](#filechanged)イベントを監視する絶対パスの配列 |1244| `watchPaths` | このセッション中に [FileChanged](#filechanged) イベントを監視する絶対パスの配列 |
1015| `reloadSkills` | ブール値。`true` の場合、Claude Code は SessionStart フックが完了した後に[スキル](/docs/ja/skills)とコマンド ディレクトリを再スキャンするため、フックがインストールしたスキルは同じセッションで利用可能になり、最初のプロンプトから開始されます |1245| `reloadSkills` | ブール値。`true` の場合、Claude Code は SessionStart フックの完了後に[スキル](/docs/ja/skills)とコマンドのディレクトリを再スキャンするため、フックがインストールしたスキルは最初のプロンプトから同じセッションで利用できます |
1016 1246
1017```json theme={null}1247```json theme={null}
1018{1248{
1024}1254}
1025```1255```
1026 1256
1027このイベントではプレーン stdout が既に Claude に到達するため、コンテキストのみをロードするフックは JSON を構築せずに stdout に直接出力できます。`suppressOutput` や `sessionTitle` などの他のフィールドとコンテキストを組み合わせる必要がある場合は JSON 形式を使用します。1257このイベントではプレーンな stdout がすでに Claude に届くため、コンテキストを読み込むだけのフックは JSON を組み立てずに stdout に直接出力できます。コンテキストを `sessionTitle` などの他のフィールドと組み合わせる必要がある場合は、JSON 形式を使用してください。
1028 1258
1029SessionStart フックがスキルをインストールまたは更新する場合は `reloadSkills` を使用します。スキル検出は通常 SessionStart フックが完了する前に実行されるため、フックが `~/.claude/skills/` または `.claude/skills/` に書き込むファイルは、それ以外の場合は次のセッションにのみ表示されます。この例は共有スキル リポジトリを同期し、再スキャンをリクエストします。1259SessionStart フックがスキルをインストールまたは更新する場合は `reloadSkills` を使用します。スキルの検出は通常 SessionStart フックが完了する前に実行されるため、フックが `~/.claude/skills/` や `.claude/skills/` に書き込んだファイルは、そうしなければ次のセッションでしか利用できません。この例では、共有スキルリポジトリを同期し、再スキャンを要求します：
1030 1260
1031```bash theme={null}1261```bash theme={null}
1032#!/bin/bash1262#!/bin/bash
1037echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1267echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1038```1268```
1039 1269
1270リポジトリの URL はプレースホルダーです。独自のスキルリポジトリに置き換えてください。プレースホルダーのままではクローンが失敗し、stderr に `fatal:` メッセージが出力されます。終了コード 0 で終了する SessionStart フックの stderr は情報提供のみを目的としているため、`reloadSkills` の要求は引き続き適用されます。
1271
1040<h4 id="persist-environment-variables">1272<h4 id="persist-environment-variables">
1041 環境変数を永続化1273 環境変数を永続化する
1042</h4>1274</h4>
1043 1275
1044SessionStart フックは `CLAUDE_ENV_FILE` 環境変数にアクセスでき、後続の Bash コマンド用に環境変数を永続化できるファイル パスを提供します。1276SessionStart フックは `CLAUDE_ENV_FILE` 環境変数にアクセスできます。この変数は、後続の Bash コマンドのために環境変数を永続化できるファイルパスを提供します。
1045 1277
1046個別の環境変数を設定するには、`export` ステートメントを `CLAUDE_ENV_FILE` に書き込みます。他のフックで設定された変数を保持するには、追加（`>>`）を使用します。1278個々の環境変数を設定するには、`export` 文を `CLAUDE_ENV_FILE` に書き込みます。他のフックが設定した変数を保持するため、追記（`>>`）を使用してください：
1047 1279
1048```bash theme={null}1280```bash theme={null}
1049#!/bin/bash1281#!/bin/bash
1057exit 01289exit 0
1058```1290```
1059 1291
1060環境からのすべての変更をキャプチャするには、セットアップ コマンドの前後でエクスポートされた変数を比較します。1292セットアップコマンドによる環境の変更をすべて取得するには、エクスポートされた変数を実行前後で比較します：
1061 1293
1062```bash theme={null}1294```bash theme={null}
1063#!/bin/bash1295#!/bin/bash
1064 1296
1065ENV_BEFORE=$(export -p | sort)1297ENV_BEFORE=$(export -p | sort)
1066 1298
1067# 環境を変更するセットアップ コマンドを実行1299# Run your setup commands that modify the environment
1068source ~/.nvm/nvm.sh1300source ~/.nvm/nvm.sh
1069nvm use 201301nvm use 20
1070 1302
1076exit 01308exit 0
1077```1309```
1078 1310
1079このファイルに書き込まれた変数は、セッション中に Claude Code が実行するすべての後続の Bash コマンドで利用可能になります。
1080
1081<Note>1311<Note>
1082 `CLAUDE_ENV_FILE` は SessionStart、[Setup](#setup)、[CwdChanged](#cwdchanged)、[FileChanged](#filechanged)フックで利用可能です。他のフック タイプはこの変数にアクセスできません。1312 `CLAUDE_ENV_FILE` は SessionStart、[Setup](#setup)、[CwdChanged](#cwdchanged)、[FileChanged](#filechanged) フックで利用できます。その他のフックタイプはこの変数にアクセスできません。
1083</Note>1313</Note>
1084 1314
1085<h3 id="setup">1315<h3 id="setup">
1086 Setup1316 Setup
1087</h3>1317</h3>
1088 1318
1089`--init-only` で Claude Code を起動するか、[非対話型モード](/docs/ja/headless)で `-p` フラグを使用して `--init` または `--maintenance` で起動するときのみ発火します。通常のスタートアップでは発火しません。CI またはスクリプトから明示的にトリガーする 1 回限りの依存関係インストールまたはスケジュール済みクリーンアップに使用します。通常のセッション スタートアップとは別です。セッションごとの初期化の場合は、代わりに[SessionStart](#sessionstart)を使用してください。1319Claude Code を `--init-only` で起動した場合、または `-p` フラグを使用した[非対話モード](/docs/ja/headless)で `--init` か `--maintenance` を付けて起動した場合にのみ発火します。通常の起動時には発火しません。通常のセッション開始とは別に、CI やスクリプトから明示的にトリガーする一度限りの依存関係のインストールや定期的なクリーンアップに使用してください。セッションごとの初期化には、代わりに [SessionStart](#sessionstart) を使用してください。
1090 1320
1091マッチャー値はフックをトリガーした CLI フラグに対応しています。1321matcher の値は、フックをトリガーした CLI フラグに対応します：
1092 1322
1093| マッチャー | いつ発火するか |1323| Matcher | 発火するタイミング |
1094| :- | :- |1324| :- | :- |
1095| `init` | `claude --init-only` または `claude -p --init` |1325| `init` | `claude --init-only` または `claude -p --init` |
1096| `maintenance` | `claude -p --maintenance` |1326| `maintenance` | `claude -p --maintenance` |
1097 1327
1098`--init-only` は Setup フックと `startup` マッチャーを持つ SessionStart フックを実行してから、会話を開始せずに終了します。`--init` と `--maintenance` は `-p` と組み合わせた場合のみ Setup フックを発火させます。対話型セッションでは、これら 2 つのフラグは現在 Setup フックを発火させません。1328`claude --init-only` を実行すると、Claude Code は Setup フックと、`startup` matcher を持つ `SessionStart` フックを実行し、会話を開始せずに終了します。
1329
1330`-p` で会話を開始または続行する場合は、プロンプトも引数として、または stdin へのパイプで指定する必要があります。`SessionStart` フックが [`initialUserMessage`](#sessionstart-decision-control) を提供する場合や、[延期されたツール呼び出し](#defer-a-tool-call-for-later)のあるセッションを再開する場合は、プロンプトを省略できます。
1099 1331
1100Setup はすべての起動で発火しないため、依存関係がインストールされている必要があるプラグインは Setup のみに依存できません。実用的なパターンは、最初の使用時に依存関係をチェックし、欠落している場合はインストールすることです。例えば、`${CLAUDE_PLUGIN_DATA}/node_modules` をテストし、欠落している場合は `npm install` を実行するフックまたはスキル。永続データ ディレクトリについては、[永続データ ディレクトリ](/docs/ja/plugins-reference#persistent-data-directory)を参照して、インストールされた依存関係を保存する場所を確認してください。1332成功した場合、`--init-only` はターミナルに何も出力しません。フックが実行されたことを確認するには、`<path>` をログファイルの場所に置き換えて `claude --debug-file <path> --init-only` で起動し、ログで Setup と SessionStart のフックのエントリを確認してください。
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)します。
1101 1335
1102<h4 id="setup-input">1336<h4 id="setup-input">
1103 Setup 入力1337 Setup の入力
1104</h4>1338</h4>
1105 1339
1106[共通入力フィールド](#common-input-fields)に加えて、Setup フックは `trigger` フィールドを受け取ります。これは `"init"` または `"maintenance"` に設定されます。1340[共通の入力フィールド](#common-input-fields)に加えて、Setup フックは `"init"` または `"maintenance"` のいずれかに設定された `trigger` フィールドを受け取ります：
1107 1341
1108```json theme={null}1342```json theme={null}
1109{1343{
1116```1350```
1117 1351
1118<h4 id="setup-decision-control">1352<h4 id="setup-decision-control">
1119 Setup 決定制御1353 Setup の決定制御
1120</h4>1354</h4>
1121 1355
1122Setup フックはブロックできません。非ゼロ終了コード（2 を含む）は stderr をユーザーに `<hook name> hook error` 通知として表示し、実行は続行されます。[非対話型モード](/docs/ja/headless)では、フック出力は `--verbose` で起動した場合のみ表示されます。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)として実行の出力に表示されます。
1123
1124Claude のコンテキストに情報を渡すには、JSON 出力で `additionalContext` を返します。プレーン stdout はデバッグ ログにのみ書き込まれます。すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、これらのイベント固有のフィールドを返すことができます。
1125
1126| フィールド | 説明 |
1127| :- | :- |
1128| `additionalContext` | Claude のコンテキストに追加される文字列。複数のフックの値は連結されます |
1129
1130```json theme={null}
1131{
1132 "hookSpecificOutput": {
1133 "hookEventName": "Setup",
1134 "additionalContext": "Dependencies installed: node_modules, .venv"
1135 }
1136}
1137```
1138 1357
1139Setup フックは `CLAUDE_ENV_FILE` にアクセスできます。そのファイルに書き込まれた変数は、[SessionStart フック](#persist-environment-variables)と同じように、セッション中の後続の Bash コマンドに永続化されます。`type: "command"` と `type: "mcp_tool"` フックのみがサポートされています。1358Setup フックは `CLAUDE_ENV_FILE` にアクセスできます。このファイルに書き込まれた変数は、[SessionStart フック](#persist-environment-variables)と同様に、セッションの後続の Bash コマンドに引き継がれます。`Setup` で実行されるのは `type: "command"` フックのみです。`Setup` の `type: "mcp_tool"` フックは、[MCP ツールフックのフィールド](#mcp-tool-hook-fields)で説明しているとおり、常にスキップされます。
1140 1359
1141<h3 id="instructionsloaded">1360<h3 id="instructionsloaded">
1142 InstructionsLoaded1361 InstructionsLoaded
1143</h3>1362</h3>
1144 1363
1145`CLAUDE.md` または `.claude/rules/*.md` ファイルがコンテキストにロードされるときに発火します。このイベントはセッション開始時に熱心にロードされたファイルに対して発火し、後で Claude がネストされた `CLAUDE.md` を含むサブディレクトリにアクセスするときなど、遅延ロードされたファイルに対して再度発火します。または `paths:` フロントマターを持つ条件付きルールがマッチするとき。フックはブロッキングまたは決定制御をサポートしません。観測可能性の目的で非同期に実行されます。1364`CLAUDE.md` または `.claude/rules/*.md` ファイルがコンテキストに読み込まれたときに発火します。このイベントは、即時に読み込まれるファイルについてはセッション開始時に発火し、ファイルが遅延読み込みされるときにも後で再び発火します。たとえば、Claude がネストされた `CLAUDE.md` を含むサブディレクトリにアクセスしたときや、`paths:` フロントマターを持つ条件付きルールが一致したときです。このフックはブロックや決定制御をサポートしていません。可観測性のために非同期で実行されます。
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` の読み込みとして発火します。
1146 1367
1147マッチャーは `load_reason` に対して実行されます。例えば、`"matcher": "session_start"` を使用してセッション開始時にロードされたファイルのみに対して発火するか、`"matcher": "path_glob_match|nested_traversal"` を使用して遅延ロードのみに対して発火します。1368matcher は `load_reason` に対して照合されます。たとえば、セッション開始時に読み込まれたファイルに対してのみ発火させるには `"matcher": "session_start"` を、遅延読み込みに対してのみ発火させるには `"matcher": "path_glob_match|nested_traversal"` を使用します。
1148 1369
1149<h4 id="instructionsloaded-input">1370<h4 id="instructionsloaded-input">
1150 InstructionsLoaded 入力1371 InstructionsLoaded の入力
1151</h4>1372</h4>
1152 1373
1153[共通入力フィールド](#common-input-fields)に加えて、InstructionsLoaded フックはこれらのフィールドを受け取ります。1374[共通の入力フィールド](#common-input-fields)に加えて、InstructionsLoaded フックは次のフィールドを受け取ります：
1154 1375
1155| フィールド | 説明 |1376| フィールド | 説明 |
1156| :- | :- |1377| :- | :- |
1157| `file_path` | ロードされた命令ファイルへの絶対パス |1378| `file_path` | 読み込まれた指示ファイルの絶対パス |
1158| `memory_type` | ファイルのスコープ: `"User"`、`"Project"`、`"Local"`、または `"Managed"` |1379| `memory_type` | ファイルのスコープ：`"User"`、`"Project"`、`"Local"`、または `"Managed"` |
1159| `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"` の値は、コンテキスト圧縮イベントの後に指示ファイルが再読み込みされたときに発火します |
1160| `globs` | ファイルの `paths:` フロントマターからのパス グロブ パターン（存在する場合）。`path_glob_match` ロードの場合のみ存在 |1381| `globs` | ファイルの `paths:` フロントマターにあるパスの glob パターン（存在する場合）。`path_glob_match` の読み込みでのみ存在します |
1161| `trigger_file_path` | 遅延ロードの場合、このロードをトリガーしたファイルへのパス |1382| `trigger_file_path` | 遅延読み込みの場合、この読み込みのきっかけとなったアクセス先のファイルのパス |
1162| `parent_file_path` | `include` ロードの場合、このファイルを含む親命令ファイルへのパス |1383| `parent_file_path` | `include` の読み込みの場合、このファイルをインクルードした親の指示ファイルのパス |
1163 1384
1164```json theme={null}1385```json theme={null}
1165{1386{
1174```1395```
1175 1396
1176<h4 id="instructionsloaded-decision-control">1397<h4 id="instructionsloaded-decision-control">
1177 InstructionsLoaded 決定制御1398 InstructionsLoaded の決定制御
1178</h4>1399</h4>
1179 1400
1180InstructionsLoaded フックは決定制御がありません。命令ロードをブロックまたは変更できません。このイベントを監査ログ、コンプライアンス追跡、または観測可能性に使用します。1401InstructionsLoaded フックには決定制御がありません。指示の読み込みをブロックしたり変更したりすることはできません。Claude Code は `systemMessage` や `continue` などの [JSON 出力フィールド](#json-output)を破棄します。このイベントは、監査ログ、コンプライアンスの追跡、可観測性のために使用してください。
1181 1402
1182<h3 id="userpromptsubmit">1403<h3 id="userpromptsubmit">
1183 UserPromptSubmit1404 UserPromptSubmit
1184</h3>1405</h3>
1185 1406
1186ユーザーがプロンプトを送信するときに実行されます。Claude がそれを処理する前に。これにより、プロンプト/会話に基づいて追加コンテキストを追加したり、プロンプトを検証したり、特定のタイプのプロンプトをブロックしたりできます。1407ユーザーがプロンプトを送信したとき、Claude がそれを処理する前に実行されます。これにより、プロンプトや会話に基づいて追加のコンテキストを加えたり、プロンプトを検証したり、特定の種類のプロンプトをブロックしたりできます。
1187 1408
1188`UserPromptSubmit` フックは `command`、`http`、`mcp_tool` タイプのデフォルト タイムアウトが 30 秒で、他のイベントでのこれらのタイプの 600 秒のデフォルトより短くなっています。このフックはすべてのプロンプトの前に実行され、モデル処理がそれが完了するまでブロックされるため、スタックしたフックはセッションを停止させます。フックにより多くの時間が必要な場合は、フック エントリで `timeout` フィールドを設定します。1409`UserPromptSubmit` フックのデフォルトのタイムアウトは、`command`、`http`、`mcp_tool` タイプで 30 秒です。これは、他のほとんどのイベントにおけるこれらのタイプのデフォルトである 600 秒より短くなっています。このフックはすべてのプロンプトの前に実行され、完了するまでモデルの処理をブロックするため、フックが停止するとセッションが止まってしまいます。フックにより長い時間が必要な場合は、フックエントリで `timeout` フィールドを設定してください。
1189 1410
1190タイムアウトに達した `UserPromptSubmit` フックはキャンセルされ、`additionalContext` を含むその出力は破棄されます。プロンプトは引き続き Claude に到達しますが、そのコンテキストなしで。v2.1.196 以降では、トランスクリプトはフックの名前、発火したタイムアウト、出力が破棄されたことを示す通知を表示します。以前のバージョンはフックを通知なしでキャンセルします。1411[`async: true`](#run-hooks-in-the-background) で実行するコマンドフックを除き、タイムアウトに達した `UserPromptSubmit` のコマンド、HTTP、または MCP ツールのフックはキャンセルされ、`additionalContext` を含むその出力は破棄されます。プロンプトはそのコンテキストなしで Claude に届きます。トランスクリプトには、フック名、発生したタイムアウト、および出力が破棄されたことを示す通知が表示されます。
1191 1412
1192[Agent SDK コールバック フック](/docs/ja/agent-sdk/hooks)が `UserPromptSubmit` でタイムアウトに達した場合、プロンプトをブロックします。フックの名前とタイムアウトを示すメッセージが表示されます。コールバックはそこで失敗してはいけないポリシー ゲートとして機能する可能性があるためです。セッションは続行されます。v2.1.208 より前では、コールバック タイムアウトはそのイベントでターンを実行エラーで終了させました。1413タイムアウトに達した `UserPromptSubmit` の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)は、フック名とタイムアウトを示すメッセージとともにプロンプトをブロックします。これは、このイベントのコールバックが、フェイルオープンしてはならないポリシーゲートとして機能している可能性があるためです。セッションは継続します。v2.1.208 より前は、このイベントでのコールバックのタイムアウトは実行エラーとしてターンを終了させていました。
1193 1414
1194<h4 id="userpromptsubmit-input">1415<h4 id="userpromptsubmit-input">
1195 UserPromptSubmit 入力1416 UserPromptSubmit の入力
1196</h4>1417</h4>
1197 1418
1198[共通入力フィールド](#common-input-fields)に加えて、UserPromptSubmit フックはユーザーが送信したテキストを含む `prompt` フィールドを受け取ります。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
1421UserPromptSubmit フックは、セッションにカスタムタイトルがある場合、`session_title` も受け取ります。意味は [SessionStart の `session_title` フィールド](#sessionstart-input)と同じです。
1199 1422
1200```json theme={null}1423```json theme={null}
1201{1424{
1209```1432```
1210 1433
1211<h4 id="userpromptsubmit-decision-control">1434<h4 id="userpromptsubmit-decision-control">
1212 UserPromptSubmit 決定制御1435 UserPromptSubmit の決定制御
1213</h4>1436</h4>
1214 1437
1215`UserPromptSubmit` フックは、ユーザー プロンプトが処理されるかどうかを制御し、コンテキストを追加できます。すべての[JSON 出力フィールド](#json-output)が利用可能です。1438`UserPromptSubmit` フックは、ユーザーのプロンプトを処理するかどうかを制御し、コンテキストを追加できます。すべての [JSON 出力フィールド](#json-output)を利用できます。
1216 1439
1217終了コード 0 で会話にコンテキストを追加する 2 つの方法があります。1440終了コード 0 で会話にコンテキストを追加する方法は 2 つあります：
1218 1441
1219* **プレーン テキスト stdout**: stdout に書き込まれた JSON 以外のテキストはコンテキストとして追加されます1442* **プレーンテキストの stdout**：Claude Code は、[プレーンテキストとして扱う](#exit-code-0) stdout を Claude のコンテキストに追加します
1220* **`additionalContext` を含む JSON**: より多くの制御のために以下の JSON 形式を使用します。`additionalContext` フィールドはコンテキストとして追加されます1443* **`additionalContext` を含む JSON**：より細かく制御するには、以下の JSON 形式を使用します。`additionalContext` フィールドがコンテキストとして追加されます
1221 1444
1222プレーン stdout はトランスクリプトのフック出力として表示されます。`additionalContext` 値は Claude が見える通知なしで読むシステム リマインダーとして注入されます。1445どちらの方法でも、トランスクリプトに表示されるエントリは作成されません。プレーンな stdout と `additionalContext` の値は、それぞれフック名で始まるシステムリマインダーとして注入され、Claude は両方を読み取ります。配信を確認するには、[デバッグログ](#debug-hooks)を確認してください。
1223 1446
1224プロンプトをブロックするには、`decision` を `"block"` に設定した JSON オブジェクトを返します。1447プロンプトをブロックするには、`decision` を `"block"` に設定した JSON オブジェクトを返します：
1225 1448
1226| フィールド | 説明 |1449| フィールド | 説明 |
1227| :- | :- |1450| :- | :- |
1228| `decision` | `"block"` はプロンプトが処理されるのを防ぎ、コンテキストから消去します。許可するには省略 |1451| `decision` | `"block"` は、プロンプトが Claude に届く前に停止します。プロンプトを続行させるには省略します |
1229| `reason` | `decision` が `"block"` のときにユーザーに表示されます。コンテキストに追加されません |1452| `reason` | `decision` が `"block"` の場合にユーザーに表示されます。コンテキストには追加されません |
1230| `additionalContext` | Claude のコンテキストに追加される文字列。[Claude のコンテキストを追加](#add-context-for-claude)を参照してください |1453| `additionalContext` | 送信されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1231| `sessionTitle` | セッション タイトルを設定します。プロンプト コンテンツに基づいてセッションを自動的に名前付けするのに使用 |1454| `sessionTitle` | セッションタイトルを設定します。プロンプトの内容に基づいてセッションに自動的に名前を付けるために使用します |
1232| `suppressOriginalPrompt` | `decision` が `"block"` のときに `true` の場合、ユーザーに表示されるブロック メッセージから元のプロンプト テキストを省略 |1455| `suppressOriginalPrompt` | フックがプロンプトをブロックするときに `true` の場合、ブロックメッセージからプロンプトのテキストを除外します。[ブロックされたプロンプトが残すもの](#what-a-blocked-prompt-leaves-behind)を参照してください |
1456
1457終了コード 2 で終了してブロックするフックは、`reason` と同じように扱われます。ブロックメッセージは stderr のテキストをユーザーに表示し、コンテキストには追加されません。
1233 1458
1234```json theme={null}1459```json theme={null}
1235{1460{
1238 "hookSpecificOutput": {1463 "hookSpecificOutput": {
1239 "hookEventName": "UserPromptSubmit",1464 "hookEventName": "UserPromptSubmit",
1240 "additionalContext": "My additional context here",1465 "additionalContext": "My additional context here",
1241 "sessionTitle": "My session title"1466 "sessionTitle": "My session title",
1467 "suppressOriginalPrompt": true
1242 }1468 }
1243}1469}
1244```1470```
1245 1471
1472<h4 id="what-a-blocked-prompt-leaves-behind">
1473 ブロックされたプロンプトが残すもの
1474</h4>
1475
1476ブロックされたプロンプトが Claude に届くことはありませんが、そのテキストがすべての場所から削除されるわけではありません。デフォルトでは、ユーザーに表示されるブロックメッセージは `Original prompt:` と送信されたテキストで終わり、Claude Code はそのメッセージをディスク上のセッションのトランスクリプトファイルに書き込みます。メッセージからテキストを除外するには、`hookSpecificOutput` 内に `"suppressOriginalPrompt": true` を含む JSON を出力します。これは、フックが `decision: "block"` でブロックする場合でも、終了コード 2 で終了する場合でも機能します。JSON を出力しない終了コード 2 のフックでは、ブロックメッセージに常にプロンプトのテキストが含まれます。
1477
1478`suppressOriginalPrompt` が変更するのはブロックメッセージだけです。送信されたテキストは、セッションのトランスクリプトやプロンプト履歴などのローカルファイルに引き続き残る可能性があるため、ブロックするフックはシークレットをディスクに残さないための手段にはなりません。これらのファイルを制限または削除するには、[平文での保存](/docs/ja/claude-directory#plaintext-storage)と[ローカルデータの消去](/docs/ja/claude-directory#clear-local-data)を参照してください。
1479
1246<h3 id="userpromptexpansion">1480<h3 id="userpromptexpansion">
1247 UserPromptExpansion1481 UserPromptExpansion
1248</h3>1482</h3>
1249 1483
1250ユーザーが入力したコマンドが Claude に到達する前にプロンプトに展開されるときに実行されます。特定のコマンドを直接呼び出しからブロックしたり、特定のスキルのコンテキストを注入したり、ユーザーが呼び出すコマンドをログしたりするのに使用します。例えば、`deploy` にマッチするフックは、承認ファイルが存在しない限り `/deploy` をブロックできます。または、レビュー スキルにマッチするフックはチームのレビュー チェックリストを `additionalContext` として追加できます。1484ユーザーが入力したコマンドが、Claude に届く前にプロンプトに展開されるときに実行されます。特定のコマンドの直接呼び出しをブロックしたり、特定のスキルにコンテキストを注入したり、ユーザーが呼び出すコマンドをログに記録したりするために使用します。たとえば、`deploy` に一致するフックは承認ファイルが存在しない限り `/deploy` をブロックでき、レビュースキルに一致するフックはチームのレビューチェックリストを `additionalContext` として追加できます。
1251 1485
1252このイベントは `PreToolUse` がカバーしないパスをカバーします。`PreToolUse` フックが `Skill` ツールにマッチするのは Claude がツールを呼び出すときのみですが、`/skillname` を直接入力すると `PreToolUse` をバイパスします。`UserPromptExpansion` はその直接パスで発火します。1486このイベントは、`PreToolUse` がカバーしない経路をカバーします。`Skill` ツールに一致する `PreToolUse` フックは Claude がツールを呼び出したときにのみ発火しますが、`/skillname` を直接入力すると `PreToolUse` を経由しません。`UserPromptExpansion` はその直接の経路で発火します。
1253 1487
1254`command_name` でマッチします。マッチャーを空のままにして、すべてのプロンプト タイプのコマンドで発火します。1488`command_name` で照合します。すべてのプロンプトタイプのコマンドで発火させるには、matcher を空のままにします。
1255 1489
1256<h4 id="userpromptexpansion-input">1490<h4 id="userpromptexpansion-input">
1257 UserPromptExpansion 入力1491 UserPromptExpansion の入力
1258</h4>1492</h4>
1259 1493
1260[共通入力フィールド](#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` です。
1261 1495
1262```json theme={null}1496```json theme={null}
1263{1497{
1275```1509```
1276 1510
1277<h4 id="userpromptexpansion-decision-control">1511<h4 id="userpromptexpansion-decision-control">
1278 UserPromptExpansion 決定制御1512 UserPromptExpansion の決定制御
1279</h4>1513</h4>
1280 1514
1281`UserPromptExpansion` フックは展開をブロックするか、コンテキストを追加できます。すべての[JSON 出力フィールド](#json-output)が利用可能です。1515`UserPromptExpansion` フックは、展開をブロックしたりコンテキストを追加したりできます。すべての [JSON 出力フィールド](#json-output)を利用できます。
1282 1516
1283| フィールド | 説明 |1517| フィールド | 説明 |
1284| :- | :- |1518| :- | :- |
1285| `decision` | `"block"` はコマンドが展開されるのを防止。許可するには省略 |1519| `decision` | `"block"` はコマンドの展開を防ぎます。続行させるには省略します |
1286| `reason` | `decision` が `"block"` のときにユーザーに表示されます |1520| `reason` | `decision` が `"block"` の場合にユーザーに表示されます |
1287| `additionalContext` | 展開されたプロンプトと一緒に Claude のコンテキストに追加される文字列。[Claude のコンテキストを追加](#add-context-for-claude)を参照してください |1521| `additionalContext` | 展開されたプロンプトとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1522
1523終了コード 2 で終了してブロックするフックは、`reason` と同じように扱われます。ブロックメッセージは stderr のテキストをユーザーに表示します。
1288 1524
1289```json theme={null}1525```json theme={null}
1290{1526{
1301 MessageDisplay1537 MessageDisplay
1302</h3>1538</h3>
1303 1539
1304アシスタント メッセージが画面にストリーミングされている間に実行されます。Claude Code はメッセージを増分で表示します。新しく完了した行のバッチがレンダリング準備ができるたびに、フックはそれらの行で 1 回実行され、Claude Code はフックの置換テキストをその場所にレンダリングします。長いメッセージは複数の呼び出しを生成します。短いメッセージは 1 つだけ生成する可能性があります。1540アシスタントメッセージが画面にストリーミングされている間に実行されます。Claude Code はメッセージを段階的に表示します。新たに完成した行のバッチがレンダリングできる状態になるたびに、フックはその行を受け取って 1 回実行され、Claude Code はフックが返した置換テキストをその場所にレンダリングします。長いメッセージでは複数回の呼び出しが発生し、短いメッセージでは 1 回だけの場合もあります。
1305 1541
1306MessageDisplay を使用して以下を実行します。1542MessageDisplay は次の用途に使用できます：
1307 1543
1308* マークダウンを削除して最小限の表示にする1544* 最小限の表示にするために markdown を取り除く
1309* エージェント SDK アプリケーションがユーザーに表示するテキストを変換する1545* Agent SDK アプリケーションがユーザーに表示するテキストを変換する
1310* Claude の応答から API キーまたは内部ホスト名を編集する1546* Claude の応答から API キーや内部ホスト名を伏せる
1311 1547
1312Claude Code は各バッチをフックが返されるまで保持するため、フックを高速に保ちます。フックが失敗またはタイムアウトした場合、Claude Code は元のテキストを表示します。このイベントのデフォルト タイムアウトは 10 秒です。フックにより多くの時間が必要な場合は、フック エントリで `timeout` フィールドを設定します。1548Claude Code はフックが返るまで各バッチを保持するため、フックは高速に保ってください。フックが失敗またはタイムアウトした場合、Claude Code は元のテキストを表示します。このイベントのデフォルトのタイムアウトは 10 秒です。フックにより長い時間が必要な場合は、フックエントリで `timeout` フィールドを設定してください。
1313 1549
1314MessageDisplay は表示のみです。置換テキストは画面にレンダリングされるものだけを変更します。トランスクリプトと Claude が見るものは元のテキストを保持するため、Claude は置換を見ず、詳細モードは元のテキストを表示します。フックはアシスタント メッセージ テキストのみを受け取るため、ツール結果とユーザーが入力したテキストは変更されずにレンダリングされます。1550MessageDisplay は表示専用です。置換テキストは画面にレンダリングされる内容だけを変更します。トランスクリプトと Claude が参照する内容は元のテキストのままなので、Claude が置換テキストを目にすることはなく、verbose モードでは元のテキストが表示されます。フックが受け取るのはアシスタントメッセージのテキストのみなので、ツールの結果やユーザーが入力したテキストは変更されずにレンダリングされます。
1315 1551
1316MessageDisplay はマッチャーをサポートせず、テキストをストリーミングするすべてのアシスタント メッセージに対して発火します。テキストなしのメッセージ（ツール呼び出しのみの応答など）はそれをトリガーしません。1552MessageDisplay は matcher をサポートしておらず、テキストをストリーミングするすべてのアシスタントメッセージで発火します。ツール呼び出しのみの応答など、テキストを含まないメッセージではトリガーされません。
1317 1553
1318非対話型実行（Agent 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` テキストを収集するフックは、どちらのモードでも同じ合計テキストを受け取ります。
1319 1555
1320<h4 id="messagedisplay-input">1556<h4 id="messagedisplay-input">
1321 MessageDisplay 入力1557 MessageDisplay の入力
1322</h4>1558</h4>
1323 1559
1324[共通入力フィールド](#common-input-fields)に加えて、MessageDisplay フックはターンとメッセージの識別子、この呼び出しのメッセージ内での位置、および `delta` の新しいテキストを受け取ります。バッチ境界はテキストがどのようにストリーミングされるかに依存するため、行が特定の方法でグループ化されることを期待するのではなく、`index` と `final` を使用してメッセージを通じた進行状況を追跡します。1560[共通の入力フィールド](#common-input-fields)に加えて、MessageDisplay フックは、ターンとメッセージの識別子、メッセージ内でのこの呼び出しの位置、および `delta` 内の新しいテキストを受け取ります。バッチの境界はテキストのストリーミング方法によって異なるため、行が特定の方法でグループ化されることを前提とせず、`index` と `final` を使用してメッセージの進行状況を追跡してください。
1325 1561
1326| フィールド | 説明 |1562| フィールド | 説明 |
1327| :- | :- |1563| :- | :- |
1328| `turn_id` | 現在のターンの UUID |1564| `turn_id` | 現在のターンの UUID |
1329| `message_id` | 表示されるアシスタント メッセージの UUID。メッセージの同じバッチ全体で安定しています。これは API `msg_…` id ではないため、トランスクリプト メッセージ id と相関させることはできません |1565| `message_id` | 表示中のアシスタントメッセージの UUID。同じメッセージのすべてのバッチで一定です。これは API の `msg_…` ID ではないため、トランスクリプトのメッセージ ID と関連付けることはできません |
1330| `index` | メッセージ内のこのバッチのゼロベースのインデックス |1566| `index` | メッセージ内でのこのバッチの 0 から始まるインデックス |
1331| `final` | メッセージの最後のバッチで `true`。各メッセージは正確に 1 つの最終バッチを持ちます |1567| `final` | メッセージの最後のバッチで `true`。各メッセージには最終バッチが 1 つだけあります |
1332| `delta` | 前のバッチ以降の新しく完了した行。終了改行を含みます。常に完全な行です。ただし、最終バッチは行の途中で終わる可能性があります。対話型実行では、メッセージが改行で終わるときの最終バッチの delta は空なので、`final` ではなく、メッセージの終了信号として `final` を処理します。Agent SDK と `claude -p` 実行では、単一の呼び出しが全体メッセージを含みます |1568| `delta` | 前のバッチ以降に新たに完成した行（終端の改行を含む）。常に行全体ですが、最終バッチだけは行の途中で終わることがあります。対話的な実行では、メッセージが改行で終わる場合、最終バッチの delta は空になるため、空でない delta ではなく `final` をメッセージ終了のシグナルとして扱ってください。Agent SDK と `claude -p` の実行では、1 回の呼び出しでメッセージ全体が渡されます |
1333 1569
1334```json theme={null}1570```json theme={null}
1335{1571{
1346```1582```
1347 1583
1348<h4 id="messagedisplay-output">1584<h4 id="messagedisplay-output">
1349 MessageDisplay 出力1585 MessageDisplay の出力
1350</h4>1586</h4>
1351 1587
1352すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、MessageDisplay フックは `displayContent` を返して画面上の delta を置き換えることができます。1588すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、MessageDisplay フックは `displayContent` を返して画面上の delta を置き換えることができます：
1353 1589
1354| フィールド | 説明 |1590| フィールド | 説明 |
1355| :- | :- |1591| :- | :- |
1356| `displayContent` | delta の代わりに表示されるテキスト。元のテキストを表示するには省略 |1592| `displayContent` | delta の代わりに表示されるテキスト。元のテキストを表示するには省略します |
1357 1593
1358MessageDisplay フックは決定制御がありません。メッセージをブロックしたり、トランスクリプトに保存されたもの、または Claude に送信されたものを変更することはできません。1594MessageDisplay フックには決定制御がありません。メッセージをブロックしたり、トランスクリプトに保存される内容や Claude に送信される内容を変更したりすることはできません。Claude Code は JSON 出力のうち `displayContent` に基づいて動作し、`systemMessage` と `continue` は破棄します。
1359 1595
1360この例は Claude の応答からマークダウン フォーマットを削除して、プレーン テキスト表示を行います。スクリプトは stdin から各バッチを読み取り、`delta` から太字マーカーとインライン コード バッククォートを削除し、結果を `displayContent` として返します。1596この例では、プレーンテキストで表示するために Claude の応答から markdown の書式を取り除きます。スクリプトは stdin から各バッチを読み取り、`delta` から太字のマーカーとインラインコードのバッククォートを削除して、結果を `displayContent` として返します。
1361 1597
1362<Tabs>1598<Tabs>
1363 <Tab title="macOS/Linux">1599 <Tab title="macOS/Linux">
1364 設定ファイルでイベントのコマンド フックを登録します。1600 設定ファイルでこのイベントのコマンドフックを登録します：
1365 1601
1366 ```json theme={null}1602 ```json theme={null}
1367 {1603 {
1381 }1617 }
1382 ```1618 ```
1383 1619
1384 このスクリプトをプロジェクトの `.claude/hooks/plain-display.sh` に保存し、`chmod +x` で実行可能にします。1620 このスクリプトをプロジェクトの `.claude/hooks/plain-display.sh` に保存し、`chmod +x` で実行可能にします：
1385 1621
1386 ```bash theme={null}1622 ```bash theme={null}
1387 #!/bin/bash1623 #!/bin/bash
1388 jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'1624 jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'
1389 ```1625 ```
1390
1391 スクリプトは `PATH` に `jq` が必要です。
1392 </Tab>1626 </Tab>
1393 1627
1394 <Tab title="Windows (PowerShell)">1628 <Tab title="Windows (PowerShell)">
1395 PowerShell 経由でスクリプトを実行するコマンド フックを登録します。1629 PowerShell を通じてスクリプトを実行するコマンドフックを登録します：
1396 1630
1397 ```json theme={null}1631 ```json theme={null}
1398 {1632 {
1418 }1652 }
1419 ```1653 ```
1420 1654
1421 `-NoProfile` フラグは PowerShell プロファイルのロードをスキップしてフックを高速に開始し、`-ExecutionPolicy Bypass` は PowerShell がローカル スクリプト ファイルを実行できるようにします。1655 `-NoProfile` フラグは PowerShell プロファイルの読み込みをスキップしてフックを素早く起動させ、`-ExecutionPolicy Bypass` は PowerShell がローカルのスクリプトファイルを実行できるようにします。
1422 1656
1423 このスクリプトをプロジェクトの `.claude/hooks/plain-display.ps1` に保存します。1657 このスクリプトをプロジェクトの `.claude/hooks/plain-display.ps1` に保存します：
1424 1658
1425 ```powershell theme={null}1659 ```powershell theme={null}
1426 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json1660 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
1435 </Tab>1669 </Tab>
1436</Tabs>1670</Tabs>
1437 1671
1438マークダウンなしのバッチは変更されずに通過します。スクリプトが失敗した場合（例えば、`jq` が欠落している場合）、Claude Code は元のテキストを表示し、セッションではなく[デバッグ出力](#debug-hooks)でのみ失敗を記録します。1672markdown を含まないバッチは変更されずにそのまま渡されます。たとえば `jq` がないためにスクリプトが失敗した場合、Claude Code は元のテキストを表示し、失敗はセッション内ではなく[デバッグ出力](#debug-hooks)にのみ記録されます。
1439 1673
1440<h3 id="pretooluse">1674<h3 id="pretooluse">
1441 PreToolUse1675 PreToolUse
1442</h3>1676</h3>
1443 1677
1444Claude がツール パラメーターを作成した後、ツール呼び出しを処理する前に実行されます。ツール名でマッチします。`Bash`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`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
1680何が書き込んだかにかかわらず、特定のファイルがディスク上で変更されたときにフックを実行するには、ファイル編集ツールを名前で照合するのではなく [FileChanged](#filechanged) を使用してください。PreToolUse とは異なり、Claude Code は FileChanged フックを変更後に実行し、決定制御もないため、書き込みをブロックすることはできません。
1445 1681
1446<Warning>1682<Warning>
1447 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
1685 PreToolUse は [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) に対しても発火しません。
1448</Warning>1686</Warning>
1449 1687
1450[PreToolUse 決定制御](#pretooluse-decision-control)を使用して、ツール呼び出しを許可、拒否、質問、または遅延します。1688ツール呼び出しを許可、拒否、確認、または延期するには、[PreToolUse の決定制御](#pretooluse-decision-control)を使用します。
1689
1690タイムアウトを超えた `PreToolUse` の [Agent SDK コールバックフック](/docs/ja/agent-sdk/hooks)はツール呼び出しをブロックし、Claude はタイムアウトを示すエラー結果を受け取ります。他のフックが返した明示的な拒否は引き続き優先されます。
1451 1691
1452<h4 id="pretooluse-input">1692<h4 id="pretooluse-input">
1453 PreToolUse 入力1693 PreToolUse の入力
1454</h4>1694</h4>
1455 1695
1456[共通入力フィールド](#common-input-fields)に加えて、PreToolUse フックは `tool_name`、`tool_input`、`tool_use_id` を受け取ります。`tool_input` フィールドはツールに依存します。1696[共通の入力フィールド](#common-input-fields)に加えて、PreToolUse フックは `tool_name`、`tool_input`、`tool_use_id` を受け取ります。
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 以降が必要です。
1699
1700ファイルツール `Write`、`Edit`、`Read` では、`tool_input.file_path` は常に絶対パスです：
1701
1702* Claude Code はフックの実行前に `~` と相対パスを展開するため、パスで照合するフックが `~` や同じパスの相対表記によって回避されることはありません
1703* Windows では、`$PWD` が `/c/project` のように見える Git Bash でフックを実行する場合でも、パスはバックスラッシュ区切りで届きます
1704* `/src/` のチェックなど、スラッシュで記述された比較はバックスラッシュのパスには一致せず、ツール呼び出しはフックがブロックする対象がなかったかのように続行されます
1705* 比較する前に区切り文字を正規化してください。Bash では `FILE_PATH="${FILE_PATH//\\//}"`、Python では `file_path.replace("\\", "/")` を使用します。その後、パスは絶対パスなので、`^` で先頭に固定するのではなく `/src/` などのパスセグメントで照合します
1706
1707Windows での `Write` 呼び出しでは、次の内容が渡されます：
1708
1709```json theme={null}
1710{
1711 "hook_event_name": "PreToolUse",
1712 "tool_name": "Write",
1713 "tool_input": {
1714 "file_path": "C:\\project\\src\\index.ts",
1715 "content": "..."
1716 },
1717 ...
1718}
1719```
1720
1721`tool_input` のフィールドはツールによって異なります：
1722
1723<a id="bash" />
1457 1724
1458<h5 id="bash">1725<h5 id="bash">
1459 Bash1726 Bash
1460</h5>1727</h5>
1461 1728
1462シェル コマンドを実行します。1729シェルコマンドを実行します。
1463 1730
1464| フィールド | タイプ | 例 | 説明 |1731| フィールド | 型 | 例 | 説明 |
1465| :- | :- | :- | :- |1732| :- | :- | :- | :- |
1466| `command` | 文字列 | `"npm test"` | 実行するシェル コマンド |1733| `command` | string | `"npm test"` | 実行するシェルコマンド |
1467| `description` | 文字列 | `"Run test suite"` | コマンドが何をするかのオプション説明 |1734| `description` | string | `"Run test suite"` | コマンドの動作の説明（任意） |
1468| `timeout` | 数値 | `120000` | ミリ秒単位のオプション タイムアウト。[最大値](/docs/ja/tools-reference#bash-tool-behavior)を超える値は最大値に削減されます |1735| `timeout` | number | `120000` | タイムアウト（ミリ秒、任意）。[最大値](/docs/ja/tools-reference#bash-tool-behavior)を超える値は拒否されず、最大値に切り下げられます |
1469| `run_in_background` | ブール値 | `false` | コマンドをバックグラウンドで実行するかどうか |1736| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |
1737
1738Bash コマンドが Git リポジトリ内のファイルを変更した場合、Claude Code は変更内容を記録できます。[`bashEditDiffEnabled`](/docs/ja/settings-reference#basheditdiffenabled) 設定で記録がオンになっている場合は、すべての権限モードで変更を記録します。どのファイルでこの設定を指定できるかは、その設定の項目に記載されています。それ以外の場合は、auto モードと `bypassPermissions` モードでのみ、かつ Claude Code が Bash を通じてファイルを編集するよう Claude に指示した場合にのみ記録します。記録をオフにするには、`bashEditDiffEnabled` を `false` に設定します。バックグラウンドのコマンドと読み取り専用のコマンドには差分は含まれません。
1739
1740その後、[PostToolUse フック](#posttooluse)は変更されたファイルを `tool_response.bashEditDiff` で受け取ります。このリストは、コマンドの実行中にリポジトリ配下で変更されたものを対象とします。Git が無視するファイルやサブモジュール内のファイルは含まれません。Claude Code v2.1.269 以降が必要です。
1741
1742<Note>
1743 このリストはベストエフォートであり、パブリックベータ版です。Claude Code は変更を見逃したり、別のプロセスが同時に変更したファイルを含めたり、サイズ制限で打ち切ったりすることがあります。フィールドの形式は変更される可能性があります。このリストはポリシーの強制ではなく、レビュー対象を見つけるために使用してください。
1744</Note>
1745
1746`changedFiles` と `files` はコマンドが変更したものを列挙し、残りのフィールドはそのリストがどの程度完全で信頼できるかを示します。
1747
1748| フィールド | 型 | 例 | 説明 |
1749| :- | :- | :- | :- |
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` になります |
1752| `moreFiles` | number | `2` | `files` に差分が含まれていない変更ファイルの数 |
1753| `unavailable` | boolean | `true` | 差分が不完全な場合、または取得できなかった場合に設定されます |
1754| `skipped` | boolean | `true` | `git checkout` や `git stash` など、作業ツリーを移動する Git コマンドの場合に設定され、Claude Code は差分を取得しません |
1755| `shared` | boolean | `true` | サブエージェントのものなど、別の Bash ツール呼び出しが同時に同じリポジトリで実行された場合に設定されます。そのため、リストに含まれる変更の一部はそのコマンドによるものである可能性があります |
1756
1757<a id="powershell" />
1758
1759<h5 id="powershell">
1760 PowerShell
1761</h5>
1762
1763PowerShell コマンドを実行します。プラットフォームごとの利用可否については [PowerShell ツール](/docs/ja/tools-reference#powershell-tool)を参照してください。
1764
1765フィールドは Bash ツールと同じで、コマンド文字列は `command` に含まれます：
1766
1767| フィールド | 型 | 例 | 説明 |
1768| :- | :- | :- | :- |
1769| `command` | string | `"Get-ChildItem -Recurse"` | 実行する PowerShell コマンド |
1770| `description` | string | `"List files recursively"` | コマンドの動作の説明（任意） |
1771| `timeout` | number | `120000` | タイムアウト（ミリ秒、任意） |
1772| `run_in_background` | boolean | `false` | コマンドをバックグラウンドで実行するかどうか |
1773
1774シェルコマンドを検査するフックでは、両方のツールをカバーするように `Bash|PowerShell` で照合してください：
1775
1776* Windows では、PowerShell ツールが有効になっている場合、Claude は PowerShell をプライマリシェルとして扱い、シェルコマンドをそれを通じて実行します。
1777* Git Bash のない Windows では、このツールは自動的に有効になり、Claude Code は Bash ツールをまったく登録しません。
1778* `Bash` のみに一致するフックは、その環境では発火しません。
1470 1779
1471<h5 id="write">1780<h5 id="write">
1472 Write1781 Write
1474 1783
1475ファイルを作成または上書きします。1784ファイルを作成または上書きします。
1476 1785
1477| フィールド | タイプ | 例 | 説明 |1786| フィールド | 型 | 例 | 説明 |
1478| :- | :- | :- | :- |1787| :- | :- | :- | :- |
1479| `file_path` | 文字列 | `"/path/to/file.txt"` | 書き込むファイルへの絶対パス |1788| `file_path` | string | `"/path/to/file.txt"` | 書き込むファイルの絶対パス |
1480| `content` | 文字列 | `"file content"` | ファイルに書き込むコンテンツ |1789| `content` | string | `"file content"` | ファイルに書き込む内容 |
1481 1790
1482<h5 id="edit">1791<h5 id="edit">
1483 Edit1792 Edit
1484</h5>1793</h5>
1485 1794
1486既存ファイル内の文字列を置換します。1795既存のファイル内の文字列を置換します。
1487 1796
1488| フィールド | タイプ | 例 | 説明 |1797| フィールド | 型 | 例 | 説明 |
1489| :- | :- | :- | :- |1798| :- | :- | :- | :- |
1490| `file_path` | 文字列 | `"/path/to/file.txt"` | 編集するファイルへの絶対パス |1799| `file_path` | string | `"/path/to/file.txt"` | 編集するファイルの絶対パス |
1491| `old_string` | 文字列 | `"original text"` | 検索して置換するテキスト |1800| `old_string` | string | `"original text"` | 検索して置換するテキスト |
1492| `new_string` | 文字列 | `"replacement text"` | 置換テキスト |1801| `new_string` | string | `"replacement text"` | 置換後のテキスト |
1493| `replace_all` | ブール値 | `false` | すべての出現を置換するかどうか |1802| `replace_all` | boolean | `false` | すべての出現箇所を置換するかどうか |
1494 1803
1495<h5 id="read">1804<h5 id="read">
1496 Read1805 Read
1497</h5>1806</h5>
1498 1807
1499ファイル コンテンツを読み取ります。1808ファイルの内容を読み取ります。
1500 1809
1501| フィールド | タイプ | 例 | 説明 |1810| フィールド | 型 | 例 | 説明 |
1502| :- | :- | :- | :- |1811| :- | :- | :- | :- |
1503| `file_path` | 文字列 | `"/path/to/file.txt"` | 読み取るファイルへの絶対パス |1812| `file_path` | string | `"/path/to/file.txt"` | 読み取るファイルの絶対パス |
1504| `offset` | 数値 | `10` | 読み取りを開始する行番号のオプション |1813| `offset` | number | `10` | 読み取りを開始する行番号（任意） |
1505| `limit` | 数値 | `50` | 読み取る行数のオプション |1814| `limit` | number | `50` | 読み取る行数（任意） |
1506 1815
1507<h5 id="glob">1816<h5 id="glob">
1508 Glob1817 Glob
1509</h5>1818</h5>
1510 1819
1511グロブ パターンにマッチするファイルを検索します。1820glob パターンに一致するファイルを検索します。
1512 1821
1513| フィールド | タイプ | 例 | 説明 |1822| フィールド | 型 | 例 | 説明 |
1514| :- | :- | :- | :- |1823| :- | :- | :- | :- |
1515| `pattern` | 文字列 | `"**/*.ts"` | ファイルにマッチするグロブ パターン |1824| `pattern` | string | `"**/*.ts"` | ファイルと照合する glob パターン |
1516| `path` | 文字列 | `"/path/to/dir"` | 検索するオプション ディレクトリ。デフォルトは現在の作業ディレクトリ |1825| `path` | string | `"/path/to/dir"` | 検索するディレクトリ（任意）。デフォルトは現在の作業ディレクトリです |
1517 1826
1518<h5 id="grep">1827<h5 id="grep">
1519 Grep1828 Grep
1520</h5>1829</h5>
1521 1830
1522正規表現でファイル コンテンツを検索します。1831正規表現でファイルの内容を検索します。
1523 1832
1524| フィールド | タイプ | 例 | 説明 |1833| フィールド | 型 | 例 | 説明 |
1525| :- | :- | :- | :- |1834| :- | :- | :- | :- |
1526| `pattern` | 文字列 | `"TODO.*fix"` | 検索する正規表現パターン |1835| `pattern` | string | `"TODO.*fix"` | 検索する正規表現パターン |
1527| `path` | 文字列 | `"/path/to/dir"` | 検索するオプション ファイルまたはディレクトリ |1836| `path` | string | `"/path/to/dir"` | 検索するファイルまたはディレクトリ（任意） |
1528| `glob` | 文字列 | `"*.ts"` | ファイルをフィルタリングするオプション グロブ パターン |1837| `glob` | string | `"*.ts"` | ファイルを絞り込む glob パターン（任意） |
1529| `output_mode` | 文字列 | `"content"` | `"content"`、`"files_with_matches"`、または `"count"`。デフォルトは `"files_with_matches"` |1838| `output_mode` | string | `"content"` | `"content"`、`"files_with_matches"`、または `"count"`。デフォルトは `"files_with_matches"` です |
1530| `-i` | ブール値 | `true` | 大文字小文字を区別しない検索 |1839| `-i` | boolean | `true` | 大文字と小文字を区別しない検索 |
1531| `multiline` | ブール値 | `false` | 複数行マッチングを有効化 |1840| `multiline` | boolean | `false` | 複数行の照合を有効にする |
1532 1841
1533<h5 id="webfetch">1842<h5 id="webfetch">
1534 WebFetch1843 WebFetch
1536 1845
1537Web コンテンツを取得して処理します。1846Web コンテンツを取得して処理します。
1538 1847
1539| フィールド | タイプ | 例 | 説明 |1848| フィールド | 型 | 例 | 説明 |
1540| :- | :- | :- | :- |1849| :- | :- | :- | :- |
1541| `url` | 文字列 | `"https://example.com/api"` | コンテンツを取得する URL |1850| `url` | string | `"https://example.com/api"` | コンテンツを取得する URL |
1542| `prompt` | 文字列 | `"Extract the API endpoints"` | 取得したコンテンツで実行するプロンプト |1851| `prompt` | string | `"Extract the API endpoints"` | 取得したコンテンツに対して実行するプロンプト |
1543 1852
1544<h5 id="websearch">1853<h5 id="websearch">
1545 WebSearch1854 WebSearch
1547 1856
1548Web を検索します。1857Web を検索します。
1549 1858
1550| フィールド | タイプ | 例 | 説明 |1859| フィールド | 型 | 例 | 説明 |
1551| :- | :- | :- | :- |1860| :- | :- | :- | :- |
1552| `query` | 文字列 | `"react hooks best practices"` | 検索クエリ |1861| `query` | string | `"react hooks best practices"` | 検索クエリ |
1553| `allowed_domains` | 配列 | `["docs.example.com"]` | オプション: これらのドメインからのみ結果を含める |1862| `allowed_domains` | array | `["docs.example.com"]` | 任意：これらのドメインの結果のみを含める |
1554| `blocked_domains` | 配列 | `["spam.example.com"]` | オプション: これらのドメインからの結果を除外 |1863| `blocked_domains` | array | `["spam.example.com"]` | 任意：これらのドメインの結果を除外する |
1555 1864
1556<h5 id="agent">1865<h5 id="agent">
1557 Agent1866 Agent
1558</h5>1867</h5>
1559 1868
1560[サブエージェント](/docs/ja/sub-agents)を生成します。1869[サブエージェント](/docs/ja/sub-agents)を起動します。
1561 1870
1562| フィールド | タイプ | 例 | 説明 |1871| フィールド | 型 | 例 | 説明 |
1563| :- | :- | :- | :- |1872| :- | :- | :- | :- |
1564| `prompt` | 文字列 | `"Find all API endpoints"` | エージェントが実行するタスク |1873| `prompt` | string | `"Find all API endpoints"` | エージェントが実行するタスク |
1565| `description` | 文字列 | `"Find API endpoints"` | タスクの短い説明 |1874| `description` | string | `"Find API endpoints"` | タスクの短い説明 |
1566| `subagent_type` | 文字列 | `"Explore"` | 使用する特殊エージェントのタイプ |1875| `subagent_type` | string | `"Explore"` | 使用する専門エージェントの種類 |
1567| `model` | 文字列 | `"sonnet"` | デフォルトをオーバーライドするオプション モデル エイリアス |1876| `model` | string | `"sonnet"` | デフォルトを上書きするモデルエイリアス（任意） |
1568 1877
1569`PostToolUse` では、完了した Agent 呼び出しの `tool_response` はサブエージェントの最終テキストと使用テレメトリを含みます。フックからサブエージェント単位のコストを記録するためにこれらのフィールドを読み取ります。1878フォアグラウンドの Agent 呼び出しが完了すると、[PostToolUse フック](#posttooluse)は `tool_response` でサブエージェントの結果と実行のテレメトリを受け取ります。実行を調べるにはこれらのフィールドを読み取ってください。`totalTokens` と `usage` は最後のリクエストのみを対象とするため、サブエージェント全体のトークンとコストの集計には、`query_source` `"subagent"` で絞り込んだ[トークンとコストのカウンター](/docs/ja/monitoring-usage#token-counter)を使用してください：
1570 1879
1571| フィールド | タイプ | 例 | 説明 |1880| フィールド | 型 | 例 | 説明 |
1572| :- | :- | :- | :- |1881| :- | :- | :- | :- |
1573| `status` | 文字列 | `"completed"` | `"completed"` は同期呼び出しの場合、`"async_launched"` はバックグラウンド サブエージェントの場合。v2.1.198 以降では、サブエージェントはデフォルトでバックグラウンドで実行されるため、省略された `run_in_background` も `"async_launched"` を生成します |1882| `status` | string | `"completed"` | フォアグラウンドのサブエージェントの場合は `"completed"`、バックグラウンドのサブエージェントの場合は `"async_launched"`。v2.1.198 以降、サブエージェントはデフォルトでバックグラウンドで実行されるため、`run_in_background` を省略した場合も `"async_launched"` になります |
1574| `agentId` | 文字列 | `"a4d2c8f1e0b3a297"` | サブエージェント実行の識別子 |1883| `agentId` | string | `"a4d2c8f1e0b3a297"` | サブエージェントの実行の識別子 |
1575| `content` | 配列 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | サブエージェントの最終テキスト ブロック |1884| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | サブエージェントの最終的なテキストブロック。レポートが `SubagentHandback` を経由するサブエージェントの場合は、その代わりにハンドバックに関する短いメモ |
1576| `resolvedModel` | 文字列 | `"claude-sonnet-4-5"` | サブエージェントが実行されたモデル。要求されたモデルと異なる可能性があります。Claude Code v2.1.174 以降が必要 |1885| `resolvedModel` | string | `"claude-sonnet-4-5"` | サブエージェントが開始時に使用したモデル。要求されたモデルとは異なる場合があります |
1577| `totalTokens` | 数値 | `12450` | サブエージェントのターン全体で請求されたトークン合計 |1886| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | 使用されたモデルを順に並べたもの（連続する重複はまとめられます）。実行中にモデルが切り替えられた場合にのみ設定されます。Claude Code v2.1.212 以降が必要です |
1578| `totalDurationMs` | 数値 | `48211` | サブエージェント実行の実時間 |1887| `totalTokens` | number | `12450` | サブエージェントの最後の API リクエストのトークン数（入力、出力、キャッシュのトークンの合計）。実行全体の合計ではありません |
1579| `totalToolUseCount` | 数値 | `7` | サブエージェントが行ったツール呼び出しの数 |1888| `totalDurationMs` | number | `48211` | サブエージェントの実行の実時間 |
1580| `usage` | オブジェクト | `{"input_tokens": 8320, ...}` | タイプ別トークン分解: `input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |1889| `totalToolUseCount` | number | `7` | サブエージェントが行ったツール呼び出しの数 |
1890| `usage` | object | `{"input_tokens": 8320, ...}` | 最後の API リクエストの種類別トークン内訳：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |
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` を読み取ってください。
1581 1893
1582バックグラウンド サブエージェントの場合、ツールはサブエージェント起動後すぐに返されるため、`tool_response` は使用フィールドを含みません。`status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile`、`resolvedModel` を含みます。1894バックグラウンドのサブエージェントの場合、ツールはタスクがバックグラウンドに移動した時点で返るため、`tool_response` には使用量のフィールドが含まれません。バックグラウンドでの起動はすぐに返り、Claude Code が実行途中でバックグラウンドに移したフォアグラウンドのタスクはその移行時点で返ります。レスポンスには `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile`、`resolvedModel` が含まれます。
1583 1895
1584`resolvedModel` フィールドはサブエージェントが実行されたモデルを名前付けし、`tool_input` の `model` 値と異なる可能性があります。Claude Code v2.1.174 以降が必要です。1896`completed` レスポンスでは、`resolvedModel` はサブエージェントが開始時に使用したモデルを示し、`availableModels` やその他の上書きが適用される場合など、`tool_input` の `model` の値とは異なることがあります。`async_launched` レスポンスでは、`resolvedModel` はエージェントがバックグラウンドに移動した時点で使用中のモデルを示すため、バックグラウンドへの移行前に行われたモデルの切り替えはそこに反映されます。`modelsUsed` と、バックグラウンド移行時点の `resolvedModel` の動作には Claude Code v2.1.212 以降が必要です。
1585 1897
1586<a id="askuserquestion" />1898<a id="askuserquestion" />
1587 1899
1589 AskUserQuestion1901 AskUserQuestion
1590</h5>1902</h5>
1591 1903
1592ユーザーに 1 つから 4 つの複数選択肢の質問をします。1904ユーザーに 1～4 個の多肢選択式の質問をします。
1593 1905
1594| フィールド | タイプ | 例 | 説明 |1906| フィールド | 型 | 例 | 説明 |
1595| :- | :- | :- | :- |1907| :- | :- | :- | :- |
1596| `questions` | 配列 | `[{"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` フラグを持ちます |
1597| `answers` | オブジェクト | `{"Which framework?": "React"}` | オプション。質問テキストを選択されたオプション ラベルにマップします。複数選択の回答はラベルをコンマで結合します。Claude はこのフィールドを設定しません。`updatedInput` 経由で提供して、プログラムで回答します |1909| `answers` | object | `{"Which framework?": "React"}` | 任意。質問のテキストを選択されたオプションのラベルに対応付けます。複数選択の回答では、ラベルをカンマで結合します。Claude はこのフィールドを設定しません。プログラムで回答するには `updatedInput` を通じて指定します |
1598 1910
1599<h5 id="exitplanmode">1911<h5 id="exitplanmode">
1600 ExitPlanMode1912 ExitPlanMode
1601</h5>1913</h5>
1602 1914
1603Claude が[プラン モード](/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 は、入力をフックに渡す前に計画の内容とファイルパスを注入します。
1604 1916
1605| フィールド | タイプ | 例 | 説明 |1917| フィールド | 型 | 例 | 説明 |
1606| :- | :- | :- | :- |1918| :- | :- | :- | :- |
1607| `plan` | 文字列 | `"## Refactor auth\n1. Extract..."` | Markdown のプラン コンテンツ。ディスク上のプラン ファイルから注入 |1919| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 形式の計画の内容。ディスク上の計画ファイルから注入されます |
1608| `planFilePath` | 文字列 | `"/Users/.../plans/refactor-auth.md"` | プラン ファイルへのパス。注入 |1920| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 計画ファイルへのパス。注入されます |
1609| `allowedPrompts` | 配列 | `[{"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 が要求したプロンプトベースの権限を保持していました |
1610 1922
1611`PostToolUse` では、`tool_response` は `plan` と `filePath` フィールドを含むオブジェクトで、承認されたプランと内部ステータス フラグを保持します。ディスクからファイルを再度読み取るのではなく、`tool_response.plan` でプラン コンテンツを読み取ります。1923`PostToolUse` では、`tool_response` は承認された計画を保持する `plan` と `filePath` フィールド、および内部のステータスフラグを持つオブジェクトです。計画の内容は、ディスクからファイルを再度読み込むのではなく `tool_response.plan` から読み取ってください。
1612 1924
1613<h4 id="pretooluse-decision-control">1925<h4 id="pretooluse-decision-control">
1614 PreToolUse 決定制御1926 PreToolUse の決定制御
1615</h4>1927</h4>
1616 1928
1617`PreToolUse` フックはツール呼び出しが進行するかどうかを制御できます。トップレベル `decision` フィールドを使用する他のフックとは異なり、PreToolUse は `hookSpecificOutput` オブジェクト内に決定を返します。これにより、より豊かな制御が可能になります。4 つの結果（許可、拒否、質問、遅延）と、実行前にツール入力を変更する機能。1929`PreToolUse` フックは、ツール呼び出しを続行するかどうかを制御できます。トップレベルの `decision` フィールドを使用する他のフックとは異なり、PreToolUse は `hookSpecificOutput` オブジェクト内で決定を返します。これにより、4 つの結果（allow、deny、ask、defer）に加えて、実行前にツールの入力を変更する機能という、より豊富な制御が可能になります。
1618 1930
1619| フィールド | 説明 |1931| フィールド | 説明 |
1620| :- | :- |1932| :- | :- |
1621| `permissionDecision` | `"allow"` はツール呼び出しをスキップします。[ユーザー操作が必要なツール](#pretooluse-decision-control)と、組織が [`ask`](/docs/ja/mcp#organization-controls-on-connector-tools)に設定したコネクター ツールを除きます。`"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)は引き続き評価されます |
1622| `permissionDecisionReason` | `"allow"` と `"ask"` の場合、ユーザーに表示されますが Claude には表示されません。`"deny"` の場合、Claude に表示されます。`"defer"` の場合、無視されます |1934| `permissionDecisionReason` | `"ask"` の場合、ユーザーには表示されますが Claude には表示されません。`"deny"` の場合、Claude に表示されます。`"allow"` と `"defer"` の場合、[デバッグログ](#debug-hooks)にのみ書き込まれます |
1623| `updatedInput` | 実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更されていないフィールドを変更されたフィールドと一緒に含めます。`"allow"` と組み合わせて自動承認するか、`"ask"` と組み合わせて変更された入力をユーザーに表示します。`"defer"` の場合、無視されます |1935| `updatedInput` | 実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。Claude Code は、権限ルールと Bash コマンドの[自動バックグラウンド化の対象かどうか](/docs/ja/tools-reference#foreground-commands-that-move-to-the-background)を、Claude が送信した入力ではなくフックが返した入力に対して評価します。自動承認するには `"allow"` と、変更後の入力をユーザーに表示するには `"ask"` と組み合わせます。`"defer"` の場合は無視されます |
1624| `additionalContext` | ツール実行前に Claude のコンテキストに追加される文字列。`"defer"` の場合、無視されます。[Claude のコンテキストを追加](#add-context-for-claude)を参照してください |1936| `additionalContext` | ツールの結果とともに Claude のコンテキストに追加される文字列。`permissionDecision` が `"defer"` の場合は無視されます。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1937
1938複数の PreToolUse フックが異なる決定を返した場合、優先順位は `deny` > `defer` > `ask` > `allow` です。
1939
1940終了コード 2 で終了してブロックするフックは、`"deny"` と同じように扱われます。Claude は stderr のメッセージを拒否の理由として受け取ります。
1625 1941
1626複数の PreToolUse フックが異なる決定を返す場合、優先順位は `deny` > `defer` > `ask` > `allow` です。1942フックが `"ask"` を返した場合、ユーザーに表示される権限プロンプトには、フックの出どころを示すラベルが含まれます。任意の設定ファイルまたはエージェントのフロントマターからのフックには `[settings]`、プラグインのフックには `[plugin:<name>]`、スキルのフロントマターからのフックには `[skill]` が表示されます。これにより、どの設定ソースが確認を求めているかをユーザーが把握しやすくなります。
1627 1943
1628フックが `"ask"` を返すと、ユーザーに表示される権限プロンプトには、フックの出所を識別するラベルが含まれます。例えば、`[User]`、`[Project]`、`[Plugin]`、または `[Local]`。これにより、ユーザーはどの設定ソースが確認を要求しているかを理解できます。1944フックの `"ask"` は、[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)でも権限プロンプトを強制します。分類器はツール呼び出しを拒否することはできますが、プロンプトを表示せずに承認することはできません。v2.1.211 より前は、分類器は[サンドボックス](/docs/ja/sandboxing)の外で実行される Bash コマンドを、フックが要求したプロンプトを表示せずに承認できました。その場合でも分類器はそのコマンドに独自の安全ルールを適用し、フックの `"deny"` は常に尊重されていました。
1629 1945
1630```json theme={null}1946```json theme={null}
1631{1947{
1641}1957}
1642```1958```
1643 1959
1644`AskUserQuestion` と `ExitPlanMode` はユーザー操作が必要で、通常は[非対話型モード](/docs/ja/headless)で `-p` フラグでブロックします。`permissionDecision: "allow"` を `updatedInput` と一緒に返すことでその要件を満たします。フックは stdin からツールの入力を読み取り、独自の UI を通じて回答を収集し、ツールがプロンプトなしで実行されるように `updatedInput` で返します。`"allow"` のみを返すことはこれらのツールには十分ではありません。`AskUserQuestion` の場合、元の `questions` 配列をエコーバックし、各質問のテキストを選択された回答にマップする [`answers`](#askuserquestion) オブジェクトを追加します。1960<span id="allow-with-updatedinput" />
1645 1961
1646コネクター ツール[組織が `ask`](/docs/ja/mcp#organization-controls-on-connector-tools)に設定したツールはプロンプトを表示します。`"allow"` を返す場合でも。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) オブジェクトを追加します。
1647 1963
1648v2.1.199 以降では、サーバーが [`_meta["anthropic/requiresUserInteraction"]`](/docs/ja/mcp#require-approval-for-a-specific-tool) でマークした MCP ツールはより厳密です。フックは `"allow"` で承認プロンプトをスキップできません。`updatedInput` の有無にかかわらず、Claude Code はフックがツールが必要とする操作を収集したことを確認できないためです。1964v2.1.199 以降、サーバーが [`_meta["anthropic/requiresUserInteraction"]`](/docs/ja/mcp#require-approval-for-a-specific-tool) でマークした MCP ツールはより厳格です。Claude Code はツールが必要とする操作をフックが収集したことを確認できないため、`updatedInput` の有無にかかわらず、フックは `"allow"` でその承認プロンプトをスキップできません。
1649 1965
1650<Note>1966<Note>
1651 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` を使用します。
1652</Note>1968</Note>
1653 1969
1654<h4 id="defer-a-tool-call-for-later">1970<h4 id="defer-a-tool-call-for-later">
1655 ツール呼び出しを後で再開するために遅延1971 ツール呼び出しを後で実行するために延期する
1656</h4>1972</h4>
1657 1973
1658`"defer"` は `claude -p` をサブプロセスとして実行し、その JSON 出力を読み取る Agent SDK アプリまたはカスタム UI などの統合用です。これにより、その呼び出しプロセスは Claude をツール呼び出しで一時停止し、独自のインターフェースを通じて入力を収集し、中断したところから再開できます。Claude Code は[非対話型モード](/docs/ja/headless)で `-p` フラグでのみこの値を尊重します。対話型セッションではログ警告を記録し、フック結果を無視します。1974`"defer"` は、Agent SDK アプリや Claude Code 上に構築したカスタム UI など、`claude -p` をサブプロセスとして実行してその JSON 出力を読み取る統合向けです。呼び出し元のプロセスは、ツール呼び出しの時点で Claude を一時停止し、独自のインターフェースで入力を収集して、中断したところから再開できます。Claude Code がこの値を尊重するのは、`-p` フラグを使用した[非対話モード](/docs/ja/headless)の場合のみです。対話セッションでは警告をログに記録し、フックの結果を無視します。
1659 1975
1660`AskUserQuestion` ツールが典型的なケースです。Claude はユーザーに何かを尋ねたいのですが、応答するターミナルがありません。ラウンド トリップは次のように機能します。1976`AskUserQuestion` ツールが典型的なケースです。Claude はユーザーに何かを質問したいものの、回答するためのターミナルがありません。`-p` の実行で `AskUserQuestion` が提供されるのは、`--permission-prompt-tool` で渡す MCP ツールなどの[権限ホスト](/docs/ja/headless#turn-off-permission-prompts-in-unattended-runs)がある場合のみなので、権限ホストを指定して実行を開始してください。往復の流れは次のとおりです：
1661 1977
16621. Claude が `AskUserQuestion` を呼び出します。`PreToolUse` フックが発火します。19781. Claude が `AskUserQuestion` を呼び出します。`PreToolUse` フックが発火します。
16632. フックは `permissionDecision: "defer"` を返します。ツールは実行されません。プロセスは `stop_reason: "tool_deferred"` で終了し、トランスクリプトに保留中のツール呼び出しが保持されます。19792. フックが `permissionDecision: "defer"` を返します。ツールは実行されません。プロセスは `stop_reason: "tool_deferred"` で終了し、保留中のツール呼び出しはトランスクリプトに保存されます。
16643. 呼び出しプロセスは SDK 結果から `deferred_tool_use` を読み取り、独自の UI で質問を表示し、回答を待ちます。19803. 呼び出し元のプロセスは SDK の結果から `deferred_tool_use` を読み取り、独自の UI に質問を表示して回答を待ちます。
16654. 呼び出しプロセスは `claude -p --resume <session-id>` を実行します。同じツール呼び出しが `PreToolUse` を再度発火させます。19814. 呼び出し元のプロセスは、同じ権限ホストを指定して `claude -p --resume <session-id>` を実行します。同じツール呼び出しによって再び `PreToolUse` が発火します。
16665. フックは `permissionDecision: "allow"` を返し、`updatedInput` に回答を含めます。ツールが実行され、Claude が続行します。19825. フックは `updatedInput` に回答を含めて `permissionDecision: "allow"` を返します。ツールが実行され、Claude は処理を続行します。
1667 1983
1668`deferred_tool_use` フィールドはツールの `id`、`name`、`input` を含みます。`input` は実行前にキャプチャされたツール呼び出しのパラメーターです。1984`deferred_tool_use` フィールドには、ツールの `id`、`name`、`input` が含まれます。`input` は Claude がツール呼び出しのために生成したパラメーターで、実行前に取得されたものです：
1669 1985
1670```json theme={null}1986```json theme={null}
1671{1987{
1681}1997}
1682```1998```
1683 1999
1684タイムアウトまたは再試行制限はありません。セッションはディスク上に残ります。回答の準備ができていないときに再開する場合、フックは再度 `"defer"` を返すことができ、プロセスは同じ方法で終了します。呼び出しプロセスはループを破るタイミングを制御し、最終的に `"allow"` または `"deny"` を返します。2000タイムアウトや再試行の制限はありません。セッションは再開するまでディスク上に残りますが、[`cleanupPeriodDays`](/docs/ja/settings-reference#cleanupperioddays) による保持期間のクリーンアップの対象となります。このクリーンアップは、[保持期間のクリーンアップのルール](/docs/ja/claude-directory#cleaned-up-automatically)に従い、デフォルトで 30 日後にセッションファイルを削除します。再開時に回答の準備ができていない場合、フックは再び `"defer"` を返すことができ、プロセスは同じように終了します。呼び出し元のプロセスは、最終的にフックから `"allow"` または `"deny"` を返すことで、ループを抜けるタイミングを制御します。
1685 2001
1686`"defer"` は Claude が単一のツール呼び出しを行うときのみ機能します。Claude が一度に複数のツール呼び出しを行う場合、`"defer"` は警告で無視され、ツールは通常の権限フローを通じて進行します。制約が存在するのは、再開が 1 つのツールのみを再実行できるためです。バッチから 1 つの呼び出しを遅延させる方法はなく、他の呼び出しは未解決のままになります。2002`"defer"` は、Claude がそのターンで単一のツール呼び出しを行う場合にのみ機能します。Claude が複数のツール呼び出しを一度に行う場合、`"defer"` は警告とともに無視され、ツールは通常の権限フローで処理されます。この制約があるのは、再開時には 1 つのツールしか再実行できないためです。バッチの中の 1 つの呼び出しだけを、他の呼び出しを未解決のまま残さずに延期する方法はありません。
1687 2003
1688遅延されたツールが再開時に利用できなくなった場合、プロセスは `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` ペイロードは引き続き含まれるため、どのツールが見つからなくなったかを特定できます。
1689 2005
1690<Note>2006<Note>
1691 `--resume` は前のセッションから権限モードを復元します。遅延されたときにアクティブだった権限モードが復元されるため、再開時に `--permission-mode` を再度渡す必要はありません。例外は `plan` と `bypassPermissions` で、これらは決して引き継がれません。再開時に `--permission-mode` を明示的に渡すと、復元された値がオーバーライドされます。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
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)に記載されている例外があります。
1692</Note>2010</Note>
1693 2011
1694<h3 id="permissionrequest">2012<h3 id="permissionrequest">
1695 PermissionRequest2013 PermissionRequest
1696</h3>2014</h3>
1697 2015
1698ユーザーに権限ダイアログが表示されるときに実行されます。2016Claude Code がツールの使用についてユーザーに権限を求めようとするときに実行されます。[非対話モード](/docs/ja/headless)のバックグラウンドのサブエージェントなど、プロンプトを表示できないセッションでも、Claude Code はこれらのフックを実行し、どのフックも決定を返さなければツール呼び出しを拒否します。
1699[PermissionRequest 決定制御](#permissionrequest-decision-control)を使用して、ユーザーに代わって許可または拒否します。2017ユーザーに代わって許可または拒否するには、[PermissionRequest の決定制御](#permissionrequest-decision-control)を使用します。
2018
2019Claude がツールの使用について権限を求めた瞬間にシグナルが必要な場合は、このイベントを使用してください。Claude Code は、`permission_prompt` タイプの [Notification](#notification) フックを、プロンプトが約 6 秒待機した後にのみ実行します。
1700 2020
1701ツール名でマッチします。PreToolUse と同じ値。2021Claude Code は、サンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)については PermissionRequest フックを実行しません。そのプロンプトのシグナルを得るには、`permission_prompt` 通知タイプを使用してください。
2022
2023PreToolUse と同じ値で、ツール名で照合します。
1702 2024
1703<h4 id="permissionrequest-input">2025<h4 id="permissionrequest-input">
1704 PermissionRequest 入力2026 PermissionRequest の入力
1705</h4>2027</h4>
1706 2028
1707PermissionRequest フックは PreToolUse フックのような `tool_name` と `tool_input` フィールドを受け取りますが、`tool_use_id` はありません。オプションの `permission_suggestions` 配列には、ユーザーが通常権限ダイアログで見る「常に許可」オプションが含まれています。違いはフックが発火するタイミングです。PermissionRequest フックはユーザーに権限ダイアログが表示されようとしているときに実行され、PreToolUse フックは権限ステータスに関係なくツール実行前に実行されます。2029PermissionRequest フックは、PreToolUse フックと同様に `tool_name` と `tool_input` フィールドを受け取りますが、`tool_use_id` は含まれません。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。任意の `permission_suggestions` 配列には、許可ルールの追加や権限モードの変更など、Claude Code がこのリクエストに対して提案する[権限の更新](#permission-update-entries)が含まれます。
2030
2031`permission_suggestions` 配列は、表示されるオプションの正確なリストではありません。各権限ダイアログが独自にオプションを構築するためです。ファイル編集のダイアログなど、一部のダイアログはこの配列をまったく読み取らず、リクエスト自体からオプションを導き出します。配列を読み取るダイアログでも、提案が配列に残っているオプションを表示しないことがあります。たとえば、[`allowManagedPermissionRulesOnly`](/docs/ja/settings-reference#allowmanagedpermissionrulesonly) がルールを保存するオプションを非表示にする場合です。また、[**Yes, and switch to auto mode**](/docs/ja/permission-modes#switch-permission-modes) のように、提案エントリのないオプションを提供することもあります。このオプションは、権限の更新を通じてではなく、権限モードを直接変更します。
2032
2033PreToolUse フックは、権限が必要かどうかにかかわらず、すべてのツール呼び出しの前に実行されます。PermissionRequest フックは、Claude Code がユーザーに権限を求めようとするとき、またはプロンプトを表示できない呼び出しを本来なら自動的に拒否するときにのみ実行されます。どちらのイベントも [`EndConversation`](/docs/ja/tools-reference#endconversation-tool-behavior) では発火しません。
1708 2034
1709```json theme={null}2035```json theme={null}
1710{2036{
1730```2056```
1731 2057
1732<h4 id="permissionrequest-decision-control">2058<h4 id="permissionrequest-decision-control">
1733 PermissionRequest 決定制御2059 PermissionRequest の決定制御
1734</h4>2060</h4>
1735 2061
1736`PermissionRequest` フックは権限リクエストを許可または拒否できます。すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、フック スクリプトはこれらのイベント固有のフィールドを持つ `decision` オブジェクトを返すことができます。2062`PermissionRequest` フックは権限リクエストを許可または拒否できます。すべてのフックで利用できる [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは次のイベント固有のフィールドを持つ `decision` オブジェクトを返すことができます：
1737 2063
1738| フィールド | 説明 |2064| フィールド | 説明 |
1739| :- | :- |2065| :- | :- |
1740| `behavior` | `"allow"` は権限を付与、`"deny"` は拒否。[拒否と質問ルール](/docs/ja/permissions#manage-permissions)は引き続き評価されるため、`"allow"` を返すフックは一致する拒否ルールをオーバーライドしません |2066| `behavior` | `"allow"` は権限を付与し、`"deny"` は拒否します。[拒否ルールと確認ルール](/docs/ja/permissions#manage-permissions)は引き続き評価されるため、`"allow"` を返すフックが一致する拒否ルールを上書きすることはありません |
1741| `updatedInput` | `"allow"` のみ: 実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更されていないフィールドを変更されたフィールドと一緒に含めます。変更された入力は拒否と質問ルールに対して再評価されます |2067| `updatedInput` | `"allow"` の場合のみ：実行前にツールの入力パラメーターを変更します。入力オブジェクト全体を置き換えるため、変更したフィールドとともに変更していないフィールドも含めてください。変更された入力は、拒否ルールと確認ルールに対して再評価されます |
1742| `updatedPermissions` | `"allow"` のみ: 適用する[権限更新エントリ](#permission-update-entries)の配列。許可ルールを追加したり、セッション権限モードを変更したりするなど |2068| `updatedPermissions` | `"allow"` の場合のみ：適用する[権限更新エントリ](#permission-update-entries)の配列。許可ルールの追加やセッションの権限モードの変更などです |
1743| `message` | `"deny"` のみ: 権限が拒否された理由を Claude に伝える |2069| `message` | `"deny"` の場合のみ：権限が拒否された理由を Claude に伝えます |
1744| `interrupt` | `"deny"` のみ: `true` の場合、Claude を停止 |2070| `interrupt` | `"deny"` の場合のみ：`true` の場合、Claude を停止します |
2071
2072`decision` オブジェクトなしで終了コード 2 で終了するフックは権限フローを変更せず、その stderr は破棄されます。リクエストを許可または拒否できるのは `decision` オブジェクトのみです。
1745 2073
1746```json theme={null}2074```json theme={null}
1747{2075{
1761 権限更新エントリ2089 権限更新エントリ
1762</h4>2090</h4>
1763 2091
1764`updatedPermissions` 出力フィールドと[`permission_suggestions` 入力フィールド](#permissionrequest-input)の両方が同じエントリ オブジェクトの配列を使用します。各エントリには、その他のフィールドを決定する `type` と、変更が書き込まれる場所を制御する `destination` があります。2092`updatedPermissions` 出力フィールドと [`permission_suggestions` 入力フィールド](#permissionrequest-input)は、どちらも同じエントリオブジェクトの配列を使用します。各エントリには、他のフィールドを決定する `type` と、変更の書き込み先を制御する `destination` があります。
1765 2093
1766| `type` | フィールド | 効果 |2094| `type` | フィールド | 効果 |
1767| :- | :- | :- |2095| :- | :- | :- |
1768| `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"` です |
1769| `replaceRules` | `rules`、`behavior`、`destination` | `destination` で指定された `behavior` のすべてのルールを提供されたルールに置き換えます |2097| `replaceRules` | `rules`、`behavior`、`destination` | `destination` にある指定された `behavior` のすべてのルールを、指定された `rules` で置き換えます |
1770| `removeRules` | `rules`、`behavior`、`destination` | 指定された `behavior` の一致するルールを削除 |2098| `removeRules` | `rules`、`behavior`、`destination` | 指定された `behavior` の一致するルールを削除します |
1771| `setMode` | `mode`、`destination` | 権限モードを変更します。有効なモードは `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan`、`manual`（`default` のエイリアス）です。`manual` エイリアスには Claude Code v2.1.200 以降が必要です |2099| `setMode` | `mode`、`destination` | 権限モードを変更します。有効なモードは `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan`、および `default` のエイリアスとしての `manual` です。`manual` エイリアスには Claude Code v2.1.200 以降が必要です |
1772| `addDirectories` | `directories`、`destination` | 作業ディレクトリを追加します。`directories` はパス文字列の配列 |2100| `addDirectories` | `directories`、`destination` | 作業ディレクトリを追加します。`directories` はパス文字列の配列です |
1773| `removeDirectories` | `directories`、`destination` | 作業ディレクトリを削除 |2101| `removeDirectories` | `directories`、`destination` | 作業ディレクトリを削除します |
1774 2102
1775<Note>2103<Note>
1776 `setMode` で `bypassPermissions` を使用する場合、セッションが既にバイパス モードで起動されている場合のみ有効です。`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions`、または設定の `permissions.defaultMode: "bypassPermissions"` を使用し、モードが [`permissions.disableBypassPermissionsMode`](/docs/ja/permissions#managed-settings)で無効化されていない場合。それ以外の場合、更新は no-op です。`bypassPermissions` は `destination` に関係なく `defaultMode` として永続化されません。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
2106 `destination` に関係なく、`bypassPermissions` が `defaultMode` として永続化されることはありません。
1777</Note>2107</Note>
1778 2108
1779すべてのエントリの `destination` フィールドは、変更がメモリに留まるか設定ファイルに永続化されるかを決定します。2109各エントリの `destination` フィールドによって、変更をメモリ内にとどめるか設定ファイルに永続化するかが決まります。
1780 2110
1781| `destination` | 書き込み先 |2111| `destination` | 書き込み先 |
1782| :- | :- |2112| :- | :- |
1783| `session` | メモリのみ、セッション終了時に破棄 |2113| `session` | メモリ内のみ。セッション終了時に破棄されます |
1784| `localSettings` | `.claude/settings.local.json` |2114| `localSettings` | `.claude/settings.local.json` |
1785| `projectSettings` | `.claude/settings.json` |2115| `projectSettings` | `.claude/settings.json` |
1786| `userSettings` | `~/.claude/settings.json` |2116| `userSettings` | `~/.claude/settings.json` |
1787 2117
1788フックは受け取った `permission_suggestions` の 1 つを独自の `updatedPermissions` 出力として反映できます。これは、ユーザーがダイアログで「常に許可」オプションを選択するのと同等です。2118フックは、受け取った `permission_suggestions` のいずれかを、自身の `updatedPermissions` 出力としてそのまま返すことができます。
1789 2119
1790<h3 id="posttooluse">2120<h3 id="posttooluse">
1791 PostToolUse2121 PostToolUse
1793 2123
1794ツールが正常に完了した直後に実行されます。2124ツールが正常に完了した直後に実行されます。
1795 2125
1796ツール名でマッチします。PreToolUse と同じ値。2126ツール名でマッチします。値は PreToolUse と同じです。
2127
2128ツール名が適切なフィルターにならない場合は、より広くマッチさせます。
2129
2130* 任意のツールが正常に完了した後にフックを実行するには、`matcher` を省略するか `"*"` に設定します。その後、フック自身で何が変更されたかを調べることができます。たとえば `git status --porcelain` を実行すると、`git diff` では見落とされる未追跡ファイルも一覧表示されます。失敗したツール呼び出しについては、同じフックを [PostToolUseFailure](#posttoolusefailure) にも追加してください。
2131* 何が書き込んだかにかかわらず、特定のファイルがディスク上で変更されたときにフックを実行するには、[FileChanged](#filechanged) を使用します。`Bash` コマンドや Claude Code 外部のプロセスが同じファイルを書き換えた場合、Claude Code は `Edit|Write` にマッチする `PostToolUse` フックを実行しません。
1797 2132
1798<h4 id="posttooluse-input">2133<h4 id="posttooluse-input">
1799 PostToolUse 入力2134 PostToolUse の入力
1800</h4>2135</h4>
1801 2136
1802`PostToolUse` フックはツールがすでに正常に実行された後に発火します。入力には、ツールに送信された引数である `tool_input` と、返された結果である `tool_response` の両方が含まれます。両方の正確なスキーマはツールに依存します。2137`PostToolUse` フックは、ツールがすでに正常に実行された後に発火します。入力には、ツールに送信された引数である `tool_input` と、ツールが返した結果である `tool_response` の両方が含まれます。どちらも正確なスキーマはツールによって異なります。ファイル系ツールの `tool_input` のパスは、[PreToolUse](#pretooluse-input) と同じ形式で渡されます。つまり、常に絶対パスで、プラットフォームネイティブの区切り文字が使われるため、Windows ではバックスラッシュになります。MCP ツールの場合、入力には [`mcp_server`](#pretooluse-input) オブジェクトも含まれます。
1803 2138
1804```json theme={null}2139```json theme={null}
1805{2140{
1815 },2150 },
1816 "tool_response": {2151 "tool_response": {
1817 "filePath": "/path/to/file.txt",2152 "filePath": "/path/to/file.txt",
1818 "success": true2153 "type": "create"
1819 },2154 },
1820 "tool_use_id": "toolu_01ABC123...",2155 "tool_use_id": "toolu_01ABC123...",
1821 "duration_ms": 122156 "duration_ms": 12
1824 2159
1825| フィールド | 説明 |2160| フィールド | 説明 |
1826| :- | :- |2161| :- | :- |
1827| `duration_ms` | オプション。ツール実行時間（ミリ秒）。権限プロンプトと PreToolUse フックに費やされた時間は除外 |2162| `duration_ms` | 省略可能。ツールの実行時間（ミリ秒）。権限プロンプトと PreToolUse フックに費やされた時間は含まれません |
1828 2163
1829<h4 id="posttooluse-decision-control">2164<h4 id="posttooluse-decision-control">
1830 PostToolUse 決定制御2165 PostToolUse の決定制御
1831</h4>2166</h4>
1832 2167
1833`PostToolUse` フックはツール実行後に Claude にフィードバックを提供できます。すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、フック スクリプトはこれらのイベント固有のフィールドを返すことができます。2168`PostToolUse` フックは、ツール実行後に Claude にフィードバックを提供できます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。
1834 2169
1835| フィールド | 説明 |2170| フィールド | 説明 |
1836| :- | :- |2171| :- | :- |
1837| `decision` | `"block"` は Claude に `reason` でプロンプトを表示。許可するには省略 |2172| `decision` | `"block"` を指定すると、ツールの結果の隣に `reason` を追加します。Claude には元の出力も引き続き表示されます。出力を置き換えるには `updatedToolOutput` を使用します |
1838| `reason` | `decision` が `"block"` のときに Claude に表示される説明 |2173| `reason` | `decision` が `"block"` のときに Claude に表示される説明 |
1839| `additionalContext` | Claude のコンテキストに追加される文字列。[Claude のコンテキストを追加](#add-context-for-claude)を参照してください |2174| `additionalContext` | ツールの結果とともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1840| `updatedToolOutput` | ツールの出力を提供された値に置換してから 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 以降が必要です |
1841| `updatedMCPToolOutput` | [MCP ツール](#match-mcp-tools)のみ: ツールの出力を置換。すべてのツールで機能する `updatedToolOutput` を優先 |2176| `updatedToolOutput` | Claude に送信される前に、ツールの出力を指定した値で置き換えます。値はツールの出力の形状と一致している必要があります |
2177| `updatedMCPToolOutput` | [MCP ツール](#match-mcp-tools)の場合のみ出力を置き換えます。すべてのツールで機能する `updatedToolOutput` の使用を推奨します |
1842 2178
1843以下の例は `Bash` 呼び出しの出力を置換します。置換値は `Bash` ツールの出力形状と一致します。2179以下の例は、`Bash` 呼び出しの出力を置き換えます。置き換える値は `Bash` ツールの出力の形状と一致しています。
1844 2180
1845```json theme={null}2181```json theme={null}
1846{2182{
1858```2194```
1859 2195
1860<Warning>2196<Warning>
1861 `updatedToolOutput` は Claude が見るものだけを変更します。フックが発火するまでにツールはすでに実行されているため、書き込まれたファイル、実行されたコマンド、送信されたネットワーク リクエストはすでに有効になっています。OpenTelemetry ツール スパンやアナリティクス イベントなどのテレメトリも、フックが実行される前に元の出力をキャプチャします。ツール呼び出しを実行前に防止または変更するには、代わりに[PreToolUse](#pretooluse)フックを使用します。2197 `updatedToolOutput` が変更するのは Claude に見える内容だけです。フックが発火した時点でツールはすでに実行されているため、書き込まれたファイル、実行されたコマンド、送信されたネットワークリクエストはすでに反映されています。OpenTelemetry のツールスパンや分析イベントなどのテレメトリも、フックの実行前に元の出力を記録します。ツール呼び出しを実行前に阻止または変更するには、代わりに [PreToolUse](#pretooluse) フックを使用してください。
1862 2198
1863 置換値はツールの出力形状と一致する必要があります。組み込みツールは単純な文字列ではなく構造化オブジェクトを返します。例えば、`Bash` は `stdout`、`stderr`、`interrupted`、`isImage` フィールドを持つオブジェクトを返します。組み込みツールの場合、ツールの出力スキーマと一致しない値は無視され、元の出力が使用されます。MCP ツール出力はスキーマ検証なしで渡されます。Claude が必要とするエラー詳細を削除すると、Claude が誤った仮定で進行する可能性があります。2199 置き換える値はツールの出力の形状と一致している必要があります。組み込みツールはプレーンな文字列ではなく構造化されたオブジェクトを返します。たとえば、`Bash` は `stdout`、`stderr`、`interrupted`、`isImage` フィールドを持つオブジェクトを返します。組み込みツールの場合、ツールの出力スキーマと一致しない値は無視され、元の出力が使用されます。MCP ツールの出力はスキーマ検証なしでそのまま渡されます。Claude が必要とするエラーの詳細を取り除くと、Claude が誤った前提のまま処理を進める可能性があります。
2200</Warning>
2201
2202<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2203 auto モードの分類器向けに結果に注釈を付ける
2204</h4>
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 以降が必要です。
2207
2208以下の例は、クエリの出力がどこから来たかを分類器に伝えます。
2209
2210```json theme={null}
2211{
2212 "hookSpecificOutput": {
2213 "hookEventName": "PostToolUse",
2214 "classifierContext": "This query ran against the staging database, not production."
2215 }
2216}
2217```
2218
2219分類器がメモをどの程度重視するかは、フックをどこで設定したかによって異なります。
2220
2221* **Claude Code で設定されたフック**: 設定ファイル、プラグイン、スキル、エージェントのフロントマターからのフックの場合、分類器はメモを未検証のアプリケーション提供コンテキストとして扱います。メモがユーザーの意図を確定させることはなく、ユーザーが何かを承認または要求したとメモが主張している場合、分類器はその主張を会話内のユーザー自身のメッセージと照合します
2222* **インプロセスの Agent SDK コールバック**: Claude Code を組み込んだアプリケーションがフックを [TypeScript SDK コールバック](/docs/ja/agent-sdk/hooks)として登録し、ライブセッション中にメモを返す場合、分類器はメモで中継されたユーザーの発言をユーザーの意図として考慮することがあります。そのような発言は、ユーザーが送信したメッセージであれば分類器が受け入れる同意要件を満たすことができますが、ユーザー自身のメッセージでも解除できないブロックを解除することはありません。セッションが再開された後は、Claude Code は復元されたメモを未検証のコンテキストとして扱います。両方のグループのフックが同じ呼び出しに注釈を付けた場合、分類器は結合されたメモを未検証として扱います
2223
2224Claude Code はメモを配信する際に以下の制限を適用します。
2225
2226* **長さ**: Claude Code は 1 回のツール呼び出しに対するメモを 2,000 文字に制限し、残りを切り捨てます。この上限は、その呼び出しに応答するすべてのフックで共有されます
2227* **同期応答のみ**: [バックグラウンドで実行される](#run-hooks-in-the-background)フックの応答内のこのフィールドは無視されます。その応答は Claude Code がツールの結果を記録した後に届くためです
2228* **分類器が記録しない呼び出し**: 分類器のトランスクリプトには、ファイルの読み取りや検索などの読み取り専用の参照は含まれません。Claude Code はそれらの呼び出しに付けられたメモを破棄します
2229* **書き換えとの相互作用**: `updatedToolOutput` で置き換える出力についてメモで説明する場合は、同じフックの応答で両方のフィールドを返してください。その書き換えが拒否された場合や、別のフックの書き換えで置き換えられた場合、Claude Code はメモを破棄します。書き換えなしで返したメモは、別のフックが出力を書き換えた場合でも Claude Code が配信します
2230
2231<Warning>
2232 分類器は `classifierContext` に入れた内容を、セッションをホストしているアプリケーションからの情報として読み取ります。そのため、信頼できないツールの出力やサードパーティのテキストをこのフィールドにコピーしないでください。メモは、出所に関する事実やそれについてのユーザーの発言など、この 1 回の呼び出しに関する短い主張にとどめてください。無関係なメッセージやイベントのストリームを配信するためにこのフィールドを使用しないでください。
1864</Warning>2233</Warning>
1865 2234
1866<h3 id="posttoolusefailure">2235<h3 id="posttoolusefailure">
1867 PostToolUseFailure2236 PostToolUseFailure
1868</h3>2237</h3>
1869 2238
1870ツール実行が失敗するときに実行されます。このイベントはエラーをスロー、または失敗結果を返すツール呼び出しに対して発火します。これを使用して失敗をログ、アラートを送信、または Claude に是正フィードバックを提供します。2239実行を開始したツールが失敗したとき、つまりツールがエラーをスローしたとき、または MCP ツールがエラー結果を返したときに実行されます。失敗をログに記録したり、アラートを送信したり、Claude に修正のためのフィードバックを提供したりするために使用します。
1871 2240
1872ツール名でマッチします。PreToolUse と同じ値。2241ツール名でマッチします。値は PreToolUse と同じです。
1873 2242
1874<Note>2243<Note>
1875 このイベントはツール呼び出しが実行前に拒否された場合には発火しません。不明なツール名、スキーマまたはツール固有の検証に失敗した入力、または権限拒否。検証拒否は `tool_use_error` 結果として返され、フックが実行される前に発生するため、`PreToolUse` も `PostToolUseFailure` も発火しません。権限拒否は `PreToolUse` を発火させますが、このイベントは発火しません。[PermissionDenied](#permissiondenied)を参照してください。2244 このイベントは、実行前に拒否されたツール呼び出しでは発火しません。これには、不明なツール名、スキーマやツール固有の検証に失敗した入力、権限の拒否が含まれます。検証による拒否は `tool_use_error` 結果として返され、フックの実行前に発生するため、`PreToolUse` も `PostToolUseFailure` も発火しません。権限の拒否では `PreToolUse` は発火しますが、このイベントは発火しません。[PermissionDenied](#permissiondenied) を参照してください。
1876</Note>2245</Note>
1877 2246
1878<h4 id="posttoolusefailure-input">2247<h4 id="posttoolusefailure-input">
1879 PostToolUseFailure 入力2248 PostToolUseFailure の入力
1880</h4>2249</h4>
1881 2250
1882PostToolUseFailure フックは PostToolUse と同じ `tool_name` と `tool_input` フィールドを受け取り、エラー情報をトップレベル フィールドとして受け取ります。2251PostToolUseFailure フックは、PostToolUse と同じ `tool_name` および `tool_input` フィールドに加えて、エラー情報をトップレベルのフィールドとして受け取ります。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。たとえば、`npm test` コマンドが失敗した場合は次のように渡されます。
1883 2252
1884```json theme={null}2253```json theme={null}
1885{2254{
1894 "description": "Run test suite"2263 "description": "Run test suite"
1895 },2264 },
1896 "tool_use_id": "toolu_01ABC123...",2265 "tool_use_id": "toolu_01ABC123...",
1897 "error": "Command exited with non-zero status code 1",2266 "error": "Exit code 1\nError: Cannot find module 'express'",
1898 "is_interrupt": false,2267 "is_interrupt": false,
1899 "duration_ms": 41872268 "duration_ms": 4187
1900}2269}
1902 2271
1903| フィールド | 説明 |2272| フィールド | 説明 |
1904| :- | :- |2273| :- | :- |
1905| `error` | 何が悪かったかを説明する文字列 |2274| `error` | 何が問題だったかを説明する文字列。形式は失敗したツールによって異なります |
1906| `is_interrupt` | 失敗がユーザー割り込みによって引き起こされたかどうかを示すオプション ブール値 |2275| `is_interrupt` | 省略可能なブール値。ツールが報告したエラーとしてではなく、中断として Claude Code に失敗が伝わった場合に true になります。実行中のツールをキャンセルしてもこのフックは発火せず、代わりにツールの結果に中断メッセージが含まれます |
1907| `duration_ms` | オプション。ツール実行時間（ミリ秒）。権限プロンプトと PreToolUse フックに費やされた時間は除外 |2276| `duration_ms` | 省略可能。ツールの実行時間（ミリ秒）。権限プロンプトと PreToolUse フックに費やされた時間は含まれません |
2277
2278`error` 文字列は通常、失敗したツールの結果として Claude が受け取るテキストと同じです。その形式はツールや失敗の種類によって異なります。フックの判定には `tool_name`、`is_interrupt`、および先頭行の `Exit code N` を使用し、文字列の残りの部分は安定した形式ではなく表示用テキストとして扱ってください。
2279
2280* Bash と PowerShell では、実行されて終了したコマンドは、先頭行が `Exit code N` となり、その後にコマンドが出力した内容が stdout と stderr の混在した 1 つのブロックとして続きます
2281* Claude Code がシェルプロセス自体を起動できなかった場合、ペイロードには終了コードの行がない、失敗メッセージのみが含まれることもあります
2282* Claude Code は長い文字列の中間部分を `... [N characters truncated] ...` マーカーで切り詰めるほか、`Command timed out after 2m 0s` などの独自の行を挿入することがあります
1908 2283
1909<h4 id="posttoolusefailure-decision-control">2284<h4 id="posttoolusefailure-decision-control">
1910 PostToolUseFailure 決定制御2285 PostToolUseFailure の決定制御
1911</h4>2286</h4>
1912 2287
1913`PostToolUseFailure` フックはツール失敗後に Claude にコンテキストを提供できます。すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、フック スクリプトはこれらのイベント固有のフィールドを返すことができます。2288`PostToolUseFailure` フックは、ツールの失敗後に Claude にコンテキストを提供できます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。
1914 2289
1915| フィールド | 説明 |2290| フィールド | 説明 |
1916| :- | :- |2291| :- | :- |
1917| `additionalContext` | Claude のコンテキストに追加される文字列。[Claude のコンテキストを追加](#add-context-for-claude)を参照してください |2292| `additionalContext` | エラーとともに Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1918 2293
1919```json theme={null}2294```json theme={null}
1920{2295{
1929 PostToolBatch2304 PostToolBatch
1930</h3>2305</h3>
1931 2306
1932バッチ内のすべてのツール呼び出しが解決された後、Claude Code が次のモデル リクエストを送信する前に、1 回実行されます。`PostToolUse` はツールごとに 1 回発火します。つまり、Claude が並列ツール呼び出しを行うときに同時に発火します。`PostToolBatch` は完全なバッチで正確に 1 回発火するため、単一のツールではなく、実行されたツールのセットに依存するコンテキストを注入するのに適切な場所です。このイベントにはマッチャーがありません。2307バッチ内のすべてのツール呼び出しが解決された後、Claude Code がモデルに次のリクエストを送信する前に 1 回実行されます。`PostToolUse` はツールごとに 1 回発火するため、Claude が並列のツール呼び出しを行うと同時に発火します。`PostToolBatch` はバッチ全体に対して正確に 1 回だけ発火するため、単一のツールではなく実行されたツールの組み合わせに依存するコンテキストを注入するのに適しています。このイベントには matcher はありません。
1933 2308
1934<h4 id="posttoolbatch-input">2309<h4 id="posttoolbatch-input">
1935 PostToolBatch 入力2310 PostToolBatch の入力
1936</h4>2311</h4>
1937 2312
1938[共通入力フィールド](#common-input-fields)に加えて、PostToolBatch フックはバッチ内のすべてのツール呼び出しを説明する `tool_calls` 配列を受け取ります。2313[共通の入力フィールド](#common-input-fields)に加えて、PostToolBatch フックは、バッチ内のすべてのツール呼び出しを記述する配列である `tool_calls` を受け取ります。
1939 2314
1940```json theme={null}2315```json theme={null}
1941{2316{
1949 "tool_name": "Read",2324 "tool_name": "Read",
1950 "tool_input": {"file_path": "/.../ledger/accounts.py"},2325 "tool_input": {"file_path": "/.../ledger/accounts.py"},
1951 "tool_use_id": "toolu_01...",2326 "tool_use_id": "toolu_01...",
1952 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."2327 "tool_response": "1\tfrom __future__ import annotations\n2\t..."
1953 },2328 },
1954 {2329 {
1955 "tool_name": "Read",2330 "tool_name": "Read",
1956 "tool_input": {"file_path": "/.../ledger/transactions.py"},2331 "tool_input": {"file_path": "/.../ledger/transactions.py"},
1957 "tool_use_id": "toolu_02...",2332 "tool_use_id": "toolu_02...",
1958 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."2333 "tool_response": "1\tfrom __future__ import annotations\n2\t..."
1959 }2334 }
1960 ]2335 ]
1961}2336}
1962```2337```
1963 2338
1964`tool_response` はモデルが対応する `tool_result` ブロックで受け取るのと同じコンテンツを含みます。値はツールが発行したのと同じように、シリアル化された文字列またはコンテンツ ブロック配列です。`Read` の場合、これは生のファイル コンテンツではなく、行番号が付いたテキストを意味します。応答は大きくなる可能性があるため、必要なフィールドのみを解析してください。2339`tool_response` には、モデルが対応する `tool_result` ブロックで受け取るのと同じ内容が含まれます。値は、ツールが出力したとおりのシリアライズされた文字列またはコンテンツブロックの配列です。`Read` の場合、これは生のファイル内容ではなく、行番号が先頭に付いたテキストを意味します。応答は大きくなる可能性があるため、必要なフィールドのみを解析してください。
1965 2340
1966<Note>2341<Note>
1967 `tool_response` の形状は `PostToolUse` のものと異なります。`PostToolUse` はツールの構造化 `Output` オブジェクト（`Write` の場合は `{filePath: "...", success: true}` など）を渡します。`PostToolBatch` はモデルが見るシリアル化された `tool_result` コンテンツを渡します。2342 `tool_response` の形状は `PostToolUse` のものとは異なります。`PostToolUse` はツールの構造化された `Output` オブジェクト（`Write` の場合は `{filePath: "...", type: "create"}` など）を渡しますが、`PostToolBatch` はモデルが参照するシリアライズされた `tool_result` の内容を渡します。
1968</Note>2343</Note>
1969 2344
1970<h4 id="posttoolbatch-decision-control">2345<h4 id="posttoolbatch-decision-control">
1971 PostToolBatch 決定制御2346 PostToolBatch の決定制御
1972</h4>2347</h4>
1973 2348
1974`PostToolBatch` フックは Claude のコンテキストを注入できます。すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、フック スクリプトはこれらのイベント固有のフィールドを返すことができます。2349`PostToolBatch` フックは、Claude にコンテキストを注入できます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。
1975 2350
1976| フィールド | 説明 |2351| フィールド | 説明 |
1977| :- | :- |2352| :- | :- |
1978| `additionalContext` | 次のモデル呼び出しの前に 1 回注入されるコンテキスト文字列。[Claude のコンテキストを追加](#add-context-for-claude)を参照してください |2353| `additionalContext` | 次のモデル呼び出しの前に 1 回注入されるコンテキスト文字列。配信の詳細、含める内容、再開されたセッションが過去の値をどう扱うかについては、[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
1979 2354
1980```json theme={null}2355```json theme={null}
1981{2356{
1986}2361}
1987```2362```
1988 2363
1989`decision: "block"` または `continue: false` を返すと、次のモデル呼び出しの前に agentic ループが停止します。2364`decision: "block"` または `continue: false` を返すと、次のモデル呼び出しの前にエージェント型ループが停止します。ブロックメッセージは、JSON の `reason` または `stopReason`、あるいは終了コード 2 の場合は stderr から取得されます。このメッセージはトランスクリプトに警告として表示され、会話内に残るため、会話が続行されると Claude にも表示されます。
1990 2365
1991<h3 id="permissiondenied">2366<h3 id="permissiondenied">
1992 PermissionDenied2367 PermissionDenied
1993</h3>2368</h3>
1994 2369
1995[自動モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)分類器がツール呼び出しを拒否するときに実行されます。このフックは自動モードでのみ発火します。手動で権限ダイアログを拒否するとき、`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` ルールがマッチした場合には実行されません。拒否をログに記録したり、設定を調整したり、ツール呼び出しを再試行してよいことをモデルに伝えたりするために使用します。
1996 2371
1997ツール名でマッチします。PreToolUse と同じ値。2372ツール名でマッチします。値は PreToolUse と同じです。
1998 2373
1999<h4 id="permissiondenied-input">2374<h4 id="permissiondenied-input">
2000 PermissionDenied 入力2375 PermissionDenied の入力
2001</h4>2376</h4>
2002 2377
2003[共通入力フィールド](#common-input-fields)に加えて、PermissionDenied フックは `tool_name`、`tool_input`、`tool_use_id`、`reason` を受け取ります。2378[共通の入力フィールド](#common-input-fields)に加えて、PermissionDenied フックは `tool_name`、`tool_input`、`tool_use_id`、`reason` を受け取ります。MCP ツールの場合は、[`mcp_server`](#pretooluse-input) オブジェクトも受け取ります。
2004 2379
2005```json theme={null}2380```json theme={null}
2006{2381{
2015 "description": "Clean build directory"2390 "description": "Clean build directory"
2016 },2391 },
2017 "tool_use_id": "toolu_01ABC123...",2392 "tool_use_id": "toolu_01ABC123...",
2018 "reason": "Auto mode denied: command targets a path outside the project"2393 "reason": "[Irreversible Local Destruction]"
2019}2394}
2020```2395```
2021 2396
2022| フィールド | 説明 |2397| フィールド | 説明 |
2023| :- | :- |2398| :- | :- |
2024| `reason` | ツール呼び出しが拒否された理由の分類器の説明 |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` になります |
2025 2400
2026<h4 id="permissiondenied-decision-control">2401<h4 id="permissiondenied-decision-control">
2027 PermissionDenied 決定制御2402 PermissionDenied の決定制御
2028</h4>2403</h4>
2029 2404
2030PermissionDenied フックはモデルが拒否されたツール呼び出しを再試行できることを伝えることができます。`hookSpecificOutput.retry` を `true` に設定した JSON オブジェクトを返します。2405PermissionDenied フックは、拒否されたツール呼び出しを再試行してよいことをモデルに伝えることができます。`hookSpecificOutput.retry` を `true` に設定した JSON オブジェクトを返します。
2031 2406
2032```json theme={null}2407```json theme={null}
2033{2408{
2038}2413}
2039```2414```
2040 2415
2041`retry` が `true` の場合、Claude Code は会話にメッセージを追加し、モデルがツール呼び出しを再試行できることを伝えます。拒否自体は反転されません。フックが JSON を返さない場合、または `retry: false` を返す場合、拒否は立ったままで、モデルは元の拒否メッセージを受け取ります。2416`retry` が `true` の場合、Claude Code はツール呼び出しを再試行してよいことをモデルに伝えるメッセージを会話に追加します。Claude Code が拒否自体を取り消すことはありません。フックが JSON を返さない場合、または `retry: false` を返した場合は、拒否がそのまま維持され、モデルは元の拒否メッセージを受け取ります。
2417
2418分類器が[アクションに対して判定を下さなかった](/docs/ja/errors#auto-mode-cannot-determine-the-safety-of-an-action)場合、つまり分類器の応答を解析できなかった場合や、auto モードとは別の安全性チェックが分類器自身のリクエストを拒否した場合、Claude Code は `retry: true` を無視します。そのような拒否については、後で再試行するか次に進むかを、Claude Code がすでに拒否メッセージでモデルに伝えています。
2042 2419
2043<h3 id="notification">2420<h3 id="notification">
2044 Notification2421 Notification
2045</h3>2422</h3>
2046 2423
2047Claude Code が通知を送信するときに実行されます。通知タイプでマッチします。マッチャーを省略して、すべての通知タイプのフックを実行します。2424Claude Code が通知を送信するときに実行されます。通知タイプでマッチします。すべての通知タイプでフックを実行するには、matcher を省略します。
2425
2426デスクトップ通知をオフにしていても、これらのフックイベントは受け取ります。`notifications_disabled` を含む `preferredNotifChannel` 設定が変更するのは通知方法のみであり、フックが実行されるかどうかには影響しません。
2048 2427
2049| マッチャー | いつ発火するか |2428| Matcher | 発火するタイミング |
2050| :- | :- |2429| :- | :- |
2051| `permission_prompt` | Claude が権限承認を必要とする |2430| `permission_prompt` | Claude がツールの使用、またはサンドボックス化されたコマンドの[ネットワークリクエスト](/docs/ja/sandboxing#network-isolation)の承認を必要としており、プロンプトが約 6 秒間待機している |
2052| `idle_prompt` | Claude が完了して次のプロンプトを待機 |2431| `idle_prompt` | Claude が約 60 秒前に応答を終え、その後ユーザーが入力していない |
2053| `auth_success` | 認証が完了 |2432| `auth_success` | 認証が完了した |
2054| `elicitation_dialog` | MCP サーバーが elicitation フォームを開く |2433| `elicitation_dialog` | MCP サーバーが elicitation フォームを開き、ユーザーが約 6 秒間入力していない |
2055| `elicitation_complete` | MCP elicitation フォームが送信または却下 |2434| `elicitation_url_dialog` | MCP サーバーがブラウザの URL を開くよう求め、ユーザーが約 6 秒間入力していない |
2056| `elicitation_response` | MCP elicitation レスポンスがサーバーに送信 |2435| `elicitation_complete` | MCP サーバーが [URL モードの elicitation](#elicitation-input) の完了を報告した |
2057| `agent_needs_input` | バックグラウンド セッションが入力を待機開始。[エージェント ビュー](/docs/ja/agent-view)がターミナルで開いている場合のみ発火 |2436| `elicitation_response` | MCP elicitation の応答がサーバーに返送された |
2058| `agent_completed` | バックグラウンド セッションが完了または失敗。[エージェント ビュー](/docs/ja/agent-view)がターミナルで開いている場合のみ発火 |2437| `agent_needs_input` | [エージェントビュー](/docs/ja/agent-view)がターミナルで開いている間に、バックグラウンドセッションがユーザーの入力待ちを開始した。また、ターミナルセッションが[エージェントチームのチームメイトのターミナル設定に関する質問](/docs/ja/agent-teams#choose-a-display-mode)や、auto モードの[分類器リクエストの料金](/docs/ja/auto-mode-classifier-billing)に関するお知らせを表示し、ユーザーが約 6 秒間入力していない場合にも発火する |
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)がある |
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** を選択した場合は発火しない |
2442
2443`agent_needs_input` および `agent_completed` タイプには Claude Code v2.1.198 以降が必要です。
2444
2445`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled` タイプには Claude Code v2.1.234 以降が必要です。
2059 2446
2060`agent_needs_input` と `agent_completed` タイプには Claude Code v2.1.198 以降が必要です。2447ターミナルセッションで、サンドボックス化されたコマンドのネットワークリクエストに対する `permission_prompt` には Claude Code v2.1.246 以降が必要です。
2061 2448
2062異なるマッチャーを使用して、通知タイプに応じて異なるハンドラーを実行します。この設定は、Claude が権限承認を必要とするときに権限固有のアラート スクリプトをトリガーし、Claude がアイドル状態になったときに異なる通知をトリガーします。2449チームメイトのターミナル設定に関する質問に対する `agent_needs_input` には Claude Code v2.1.248 以降が必要です。
2450
2451<Note>
2452 `permission_prompt`、`idle_prompt`、`elicitation_dialog`、`elicitation_url_dialog` タイプはデスクトップ通知とタイミングを共有しているため、ターミナルセッションでは、ユーザーがターミナルから離れていると判断される場合にのみ表示されます。
2453
2454 * `permission_prompt` は、ユーザーが約 6 秒間入力しなかった時点で発火します。タイマーは権限プロンプトが表示されたときに開始し、キーを押すたびに延期されます。Claude がツールの使用権限を求めたときに即座にフックを実行するには、代わりに [PermissionRequest](#permissionrequest) を使用してください。
2455 * `idle_prompt` は、Claude が応答を終えてから約 60 秒後に、その間ユーザーが入力していない場合にのみ発火します。Claude Code が claude.ai の使用制限のリセットを待っている間は、`idle_prompt` は送信されません。待機が自動的に終了すると、代わりに `quota_auto_resume_*` タイプのいずれかが発火します。
2456 * `elicitation_dialog`（elicitation フォームの場合）または `elicitation_url_dialog`（ブラウザの URL リクエストの場合）は、ユーザーが約 6 秒間入力しなかった時点で発火します。どちらも `permission_prompt` と同じ 6 秒の待機条件を共有しており、タイマーはダイアログが表示されたときに開始し、キーを押すたびに延期されます。
2457
2458 別のダイアログが画面に表示されている間に届いた権限リクエストや elicitation にも、リクエストが届いた時点から計測される同じ 6 秒の待機条件が適用されます。そのため、リクエストが開いているダイアログの後ろでまだ待機している間に、その通知が届くことがあります。
2459</Note>
2460
2461Claude Code が権限リクエストを Agent SDK の [`canUseTool` コールバック](/docs/ja/agent-sdk/user-input)に送信するセッションでは、`permission_prompt` のタイミングが異なります。Claude Desktop や VS Code 拡張機能はこの方法で Claude Code をホストしています。
2462
2463* `permission_prompt` は、Claude が権限を求めてから約 6 秒後に発火します。ユーザーが入力していても延期されません。
2464* ユーザーまたは [PermissionRequest](#permissionrequest) フックがそれより早く応答した場合、Claude Code は `permission_prompt` を実行しません。
2465* これらのセッションで `permission_prompt` をオフにするには、[`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/ja/env-vars) を `1` に設定します。
2466
2467v2.1.233 より前は、これらのセッションで `permission_prompt` は発火しませんでした。
2468
2469通知タイプに応じて異なるハンドラーを実行するには、個別の matcher を使用します。以下の設定では、Claude が権限の承認を必要とするときに権限専用のアラートスクリプトを起動し、Claude がアイドル状態になったときには別の通知を起動します。
2063 2470
2064```json theme={null}2471```json theme={null}
2065{2472{
2089```2496```
2090 2497
2091<h4 id="notification-input">2498<h4 id="notification-input">
2092 Notification 入力2499 Notification の入力
2093</h4>2500</h4>
2094 2501
2095[共通入力フィールド](#common-input-fields)に加えて、Notification フックは通知テキストを含む `message`、オプションの `title`、発火したタイプを示す `notification_type` を受け取ります。2502[共通の入力フィールド](#common-input-fields)に加えて、Notification フックは、通知テキストを含む `message`、省略可能な `title`、どのタイプが発火したかを示す `notification_type` を受け取ります。
2096 2503
2097```json theme={null}2504```json theme={null}
2098{2505{
2106}2513}
2107```2514```
2108 2515
2109Notification フックは通知をブロックまたは変更できません。これらは副作用（外部サービスへの通知の転送など）を目的としています。すべてのフックで利用可能な[JSON 出力フィールド](#json-output)（`systemMessage` など）が適用されます。2516Notification フックは通知をブロックしたり変更したりすることはできません。Claude Code はフックの `systemMessage` および `continue` フィールドを破棄しますが、[`terminalSequence`](#emit-terminal-notifications) は引き続き出力します。デスクトップ通知の例はこれを利用しています。Notification フックは、通知を外部サービスに転送するなどの副作用を目的としています。
2110 2517
2111<h3 id="subagentstart">2518<h3 id="subagentstart">
2112 SubagentStart2519 SubagentStart
2113</h3>2520</h3>
2114 2521
2115Agent ツール経由でサブエージェントが生成されるときに実行されます。エージェント タイプ名でフィルタリングするマッチャーをサポート。組み込みエージェントの場合、これはエージェント名（`general-purpose`、`Explore`、`Plan` など）です。[カスタム サブエージェント](/docs/ja/sub-agents)の場合、これはファイル名ではなく、エージェントのフロントマターの `name` フィールドです。2522Claude が Agent ツールでサブエージェントを起動したとき、Claude が[サブエージェントを再開](/docs/ja/sub-agents#resume-subagents)したとき、およびインプロセスの[エージェントチーム](/docs/ja/agent-teams)のチームメイトが新しいメッセージを処理するたびに実行されます。エージェントタイプ名でフィルタリングするための matcher をサポートしています。組み込みエージェントの場合、これは `general-purpose`、`Explore`、`Plan` などのエージェント名です。[カスタムサブエージェント](/docs/ja/sub-agents)の場合は、ファイル名ではなく、エージェントのフロントマターの `name` フィールドです。
2116 2523
2117[プラグイン](/docs/ja/plugins)から出荷されたサブエージェントの場合、エージェント タイプはプラグイン スコープの識別子（`my-plugin:reviewer` など）で、ベアのフロントマター名ではありません。コロンはプラグイン スコープの名前を正規表現パスに配置するため、正確なマッチのためにマッチャーを `^` と `$` でアンカーします。`^my-plugin:reviewer$`。2524[プラグイン](/docs/ja/plugins/overview)で提供されるサブエージェントの場合、エージェントタイプは単なるフロントマターの名前ではなく、`my-plugin:reviewer` のようなプラグインスコープの識別子になります。コロンが含まれるため、プラグインスコープの名前は正規表現として処理されます。完全一致させるには、`^my-plugin:reviewer$` のように matcher を `^` と `$` で固定してください。
2118 2525
2119<h4 id="subagentstart-input">2526<h4 id="subagentstart-input">
2120 SubagentStart 入力2527 SubagentStart の入力
2121</h4>2528</h4>
2122 2529
2123[共通入力フィールド](#common-input-fields)に加えて、SubagentStart フックはサブエージェントの一意の識別子を含む `agent_id` とエージェント名を含む `agent_type` を受け取ります。2530[共通の入力フィールド](#common-input-fields)に加えて、SubagentStart フックは、サブエージェントの一意の識別子を含む `agent_id` と、matcher のフィルタリング対象となるエージェント名を含む `agent_type` を受け取ります。
2124 2531
2125```json theme={null}2532```json theme={null}
2126{2533{
2133}2540}
2134```2541```
2135 2542
2136SubagentStart フックはサブエージェント作成をブロックできませんが、サブエージェントにコンテキストを注入できます。すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、以下を返すことができます。2543SubagentStart フックはサブエージェントの作成をブロックできませんが、サブエージェントにコンテキストを注入することはできます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、以下を返すことができます。
2137 2544
2138| フィールド | 説明 |2545| フィールド | 説明 |
2139| :- | :- |2546| :- | :- |
2140| `additionalContext` | サブエージェントのコンテキストの開始時に追加される文字列。最初のプロンプトの前。[Claude のコンテキストを追加](#add-context-for-claude)を参照してください |2547| `additionalContext` | サブエージェントの会話の開始時、最初のプロンプトの前に、サブエージェントのコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
2141 2548
2142```json theme={null}2549```json theme={null}
2143{2550{
2148}2555}
2149```2556```
2150 2557
2558同じサブエージェントに対してフックが再度実行された場合、Claude Code は、サブエージェントのコンテキストに以前の実行時のコピーがまだ含まれていない場合にのみ、返されたコンテキストを注入します。起動時に注入されたコピーはそのまま残るため、サブエージェントの[プロンプトキャッシュ](/docs/ja/prompt-caching#subagents-and-the-cache)は維持されます。[自動圧縮](/docs/ja/sub-agents#auto-compaction)によってそのコピーが破棄された後は、Claude Code は次の実行時のコンテキストを再度注入します。
2559
2151<h3 id="subagentstop">2560<h3 id="subagentstop">
2152 SubagentStop2561 SubagentStop
2153</h3>2562</h3>
2154 2563
2155Claude Code サブエージェントが応答を終了したときに実行されます。エージェント タイプでマッチします。SubagentStart と同じ値。2564Claude Code のサブエージェントが応答を終えたときに実行されます。エージェントタイプでマッチします。値は SubagentStart と同じです。
2156 2565
2157<h4 id="subagentstop-input">2566<h4 id="subagentstop-input">
2158 SubagentStop 入力2567 SubagentStop の入力
2159</h4>2568</h4>
2160 2569
2161[共通入力フィールド](#common-input-fields)に加えて、SubagentStop フックは `stop_hook_active`、`agent_id`、`agent_type`、`agent_transcript_path`、`last_assistant_message` を受け取ります。`agent_type` フィールドはマッチャー フィルタリングに使用される値です。`transcript_path` はメイン セッションのトランスクリプト、`agent_transcript_path` はネストされた `subagents/` フォルダに保存されたサブエージェント独自のトランスクリプトです。`last_assistant_message` フィールドはサブエージェントの最終応答のテキスト コンテンツを含むため、フックはトランスクリプト ファイルを解析せずにアクセスできます。2570[共通の入力フィールド](#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` フィールドにはサブエージェントの最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにアクセスできます。
2571
2572すべての 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)で設定されたものなど）になり、セッションがエージェントなしで実行されている場合は空文字列になります。
2573
2574エージェントタイプを指定した `matcher` は、空の `agent_type` にはマッチしません。matcher が省略されている、`""` または `"*"` である、あるいは空文字列にマッチする正規表現であるフックは、`agent_type` が空のイベントでも実行されます。
2162 2575
2163SubagentStop フックは、Claude Code v2.1.145 以降で利用可能な、[Stop 入力](#stop-input)で説明されている `background_tasks` と `session_crons` 配列も受け取ります。両方の配列はサブエージェントではなく親セッションにスコープされています。2576Claude Code v2.1.271 以降では、[`SubagentHandback`](/docs/ja/tools-reference) ツールを使用して実行されるサブエージェントは、停止する前にそのツールを通じてレポートを配信します。その場合、`last_assistant_message` フィールドにはサブエージェントの締めくくりのテキスト（存在する場合）が含まれますが、これは配信されたレポートではありません。レポートはその呼び出しの `message` 入力であり、`SubagentHandback` にマッチする `PreToolUse` または `PostToolUse` フックは、これを `tool_input.message` として受け取ります。
2577
2578SubagentStop フックは、[Stop の入力](#stop-input)で説明されている `background_tasks` および `session_crons` 配列も受け取ります。どちらの配列も、サブエージェントではなく親セッションを対象としています。
2164 2579
2165```json theme={null}2580```json theme={null}
2166{2581{
2179}2594}
2180```2595```
2181 2596
2182SubagentStop フックは[Stop フック](#stop-decision-control)と同じ決定制御形式を使用します。`hookSpecificOutput.additionalContext` を含む `hookEventName` を `"SubagentStop"` に設定して、非エラー フィードバックをサポートします。会話は続行されるため、Claude が対応できます。ただし、`decision: "block"` とは異なり、トランスクリプトでは「Stop フック フィードバック」としてラベル付けされ、フック エラー通知は表示されません。`decision: "block"` を `reason` と一緒に返すとサブエージェントを実行し続け、`reason` をサブエージェントの次の命令として配信します。サブエージェントが戻った後に親セッションにコンテキストを注入するには、代わりに `Agent` ツール上の [`PostToolUse`](#posttooluse)フックを使用します。2597SubagentStop フックは [Stop フック](#stop-decision-control)と同じ決定制御形式を使用します。これには、サブエージェントの実行を継続させるエラーではないフィードバックとして、`hookEventName` を `"SubagentStop"` に設定した `hookSpecificOutput.additionalContext` も含まれます。`reason` とともに `decision: "block"` を返すと、サブエージェントの実行が継続され、`reason` が次の指示としてサブエージェントに配信されます。終了コード 2 で終了してブロックするフックも、同様に stderr メッセージを配信します。サブエージェントが戻った後に親セッションにコンテキストを注入するには、代わりに `Agent` ツールに対する [`PostToolUse`](#posttooluse) フックを使用してください。
2183 2598
2184<h3 id="taskcreated">2599<h3 id="taskcreated">
2185 TaskCreated2600 TaskCreated
2186</h3>2601</h3>
2187 2602
2188タスクが `TaskCreate` ツール経由で作成されるときに実行されます。命名規則を実施したり、タスク説明を要求したり、特定のタスクが作成されるのを防いだりするのに使用します。2603`TaskCreate` ツールによってタスクが作成されるときに実行されます。命名規則を適用したり、タスクの説明を必須にしたり、特定のタスクの作成を阻止したりするために使用します。[Task ツールがないセッション](/docs/ja/tools-reference#task-tool-availability)では、このイベントは発火しません。
2189 2604
2190`TaskCreated` フックが終了コード 2 で終了すると、タスクは作成されず、stderr メッセージはモデルへのフィードバックとしてフィードバックされます。チームメイト全体を停止する代わりに再実行するには、`{"continue": false, "stopReason": "..."}` を含む JSON を返します。TaskCreated フックはマッチャーをサポートせず、すべての出現で発火します。2605TaskCreated フックは matcher をサポートしておらず、すべての発生時に発火します。
2191 2606
2192<h4 id="taskcreated-input">2607<h4 id="taskcreated-input">
2193 TaskCreated 入力2608 TaskCreated の入力
2194</h4>2609</h4>
2195 2610
2196[共通入力フィールド](#common-input-fields)に加えて、TaskCreated フックは `task_id`、`task_subject`、およびオプションで `task_description`、`teammate_name`、`team_name` を受け取ります。2611[共通の入力フィールド](#common-input-fields)に加えて、TaskCreated フックは `task_id`、`task_subject`、および省略可能な `task_description`、`teammate_name`、`team_name` を受け取ります。
2197 2612
2198```json theme={null}2613```json theme={null}
2199{2614{
2200 "session_id": "abc123",2615 "session_id": "abc123",
2201 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",2616 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2202 "cwd": "/Users/...",2617 "cwd": "/Users/...",
2203 "permission_mode": "default",
2204 "hook_event_name": "TaskCreated",2618 "hook_event_name": "TaskCreated",
2205 "task_id": "task-001",2619 "task_id": "task-001",
2206 "task_subject": "Implement user authentication",2620 "task_subject": "Implement user authentication",
2214| :- | :- |2628| :- | :- |
2215| `task_id` | 作成されるタスクの識別子 |2629| `task_id` | 作成されるタスクの識別子 |
2216| `task_subject` | タスクのタイトル |2630| `task_subject` | タスクのタイトル |
2217| `task_description` | タスクの詳細説明。存在しない可能性があります |2631| `task_description` | タスクの詳細な説明。存在しない場合があります |
2218| `teammate_name` | タスクを作成しているチームメイトの名前。存在しない可能性があります |2632| `teammate_name` | タスクを作成するチームメイトの名前。存在しない場合があります |
2219| `team_name` | チームの名前。存在しない可能性があります |2633| `team_name` | 非推奨。セッションから派生したチーム名。将来のリリースで削除されます |
2220 2634
2221<h4 id="taskcreated-decision-control">2635<h4 id="taskcreated-decision-control">
2222 TaskCreated 決定制御2636 TaskCreated の決定制御
2223</h4>2637</h4>
2224 2638
2225TaskCreated フックはタスク作成を制御する 2 つの方法をサポートしています。2639TaskCreated フックは、2 つの方法で作成をブロックできます。いずれの場合も、Claude Code はタスクを削除し、メッセージをツールのエラーとして Claude に返します。このイベントからの `continue: false` は Claude Code によって無視され、Claude は作業を続けます。
2226 2640
2227* **終了コード 2**: タスクは作成されず、stderr メッセージはモデルへのフィードバックとしてフィードバックされます。2641* **終了コード 2**: Claude Code は stderr のテキストをメッセージとして返します。
2228* **JSON `{"continue": false, "stopReason": "..."}`**: チームメイト全体を停止し、`Stop` フック動作と一致します。`stopReason` はユーザーに表示されます。2642* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code は `reason` をメッセージとして返します。
2229 2643
2230この例は、タスク件名が必要な形式に従わない場合、タスク作成をブロックします。2644以下の例は、件名が必要な形式に従っていないタスクをブロックします。
2231 2645
2232```bash theme={null}2646```bash theme={null}
2233#!/bin/bash2647#!/bin/bash
2246 TaskCompleted2660 TaskCompleted
2247</h3>2661</h3>
2248 2662
2249タスクが完了としてマークされるときに実行されます。これは 2 つの状況で発火します。任意のエージェントが TaskUpdate ツール経由でタスクを明示的に完了としてマークするとき、または[エージェント チーム](/docs/ja/agent-teams)チームメイトが進行中のタスクでターンを終了するとき。これを使用してチームメイトが作業を停止する前に品質ゲートを実施します。例えば、lint チェックの合格を要求したり、出力ファイルが存在することを確認したりします。2663タスクが完了としてマークされるときに実行されます。これは 2 つの状況で発火します。任意のエージェントが TaskUpdate ツールを通じてタスクを明示的に完了としてマークしたとき、または[エージェントチーム](/docs/ja/agent-teams)のチームメイトが進行中のタスクを抱えたままターンを終了したときです。タスクをクローズする前に、テストやリントチェックの合格などの完了基準を適用するために使用します。
2250 2664
2251`TaskCompleted` フックが終了コード 2 で終了すると、タスクは完了としてマークされず、stderr メッセージはモデルへのフィードバックとしてフィードバックされます。チームメイト全体を停止する代わりに再実行するには、`{"continue": false, "stopReason": "..."}` を含む JSON を返します。TaskCompleted フックはマッチャーをサポートせず、すべての出現で発火します。2665TaskCompleted フックは matcher をサポートしておらず、すべての発生時に発火します。
2252 2666
2253<h4 id="taskcompleted-input">2667<h4 id="taskcompleted-input">
2254 TaskCompleted 入力2668 TaskCompleted の入力
2255</h4>2669</h4>
2256 2670
2257[共通入力フィールド](#common-input-fields)に加えて、TaskCompleted フックは `task_id`、`task_subject`、およびオプションで `task_description`、`teammate_name`、`team_name` を受け取ります。2671[共通の入力フィールド](#common-input-fields)に加えて、TaskCompleted フックは `task_id`、`task_subject`、および省略可能な `task_description`、`teammate_name`、`team_name` を受け取ります。
2258 2672
2259```json theme={null}2673```json theme={null}
2260{2674{
2273 2687
2274| フィールド | 説明 |2688| フィールド | 説明 |
2275| :- | :- |2689| :- | :- |
2276| `task_id` | 完了しているタスクの識別子 |2690| `task_id` | 完了されるタスクの識別子 |
2277| `task_subject` | タスクのタイトル |2691| `task_subject` | タスクのタイトル |
2278| `task_description` | タスクの詳細説明。存在しない可能性があります |2692| `task_description` | タスクの詳細な説明。存在しない場合があります |
2279| `teammate_name` | タスクを完了しているチームメイトの名前。存在しない可能性があります |2693| `teammate_name` | タスクを完了するチームメイトの名前。存在しない場合があります |
2280| `team_name` | チームの名前。存在しない可能性があります |2694| `team_name` | 非推奨。セッションから派生したチーム名。将来のリリースで削除されます |
2281 2695
2282<h4 id="taskcompleted-decision-control">2696<h4 id="taskcompleted-decision-control">
2283 TaskCompleted 決定制御2697 TaskCompleted の決定制御
2284</h4>2698</h4>
2285 2699
2286TaskCompleted フックはタスク完了を制御する 2 つの方法をサポートしています。2700TaskCompleted フックは、タスクの完了を制御する 2 つの方法をサポートしています。
2287 2701
2288* **終了コード 2**: タスクは完了としてマークされず、stderr メッセージはモデルへのフィードバックとしてフィードバックされます。2702* **終了コード 2**: タスクは完了としてマークされず、stderr メッセージがフィードバックとしてモデルに返されます。
2289* **JSON `{"continue": false, "stopReason": "..."}`**: チームメイト全体を停止し、`Stop` フック動作と一致します。`stopReason` はユーザーに表示されます。2703* **JSON `{"continue": false, "stopReason": "..."}`**: チームメイトがターンを終了したことでイベントが発生した場合、`Stop` フックの動作と同様に、チームメイトを完全に停止します。`stopReason` はユーザーに表示されます。`TaskUpdate` ツールによってイベントが発生した場合、Claude Code は `continue: false` を無視しますが、終了コード 2 は引き続き完了をブロックします。
2290 2704
2291この例はテストを実行し、失敗した場合はタスク完了をブロックします。2705以下の例は、テストを実行し、失敗した場合はタスクの完了をブロックします。
2292 2706
2293```bash theme={null}2707```bash theme={null}
2294#!/bin/bash2708#!/bin/bash
2295INPUT=$(cat)2709INPUT=$(cat)
2296TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')2710TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
2297 2711
2298# テスト スイートを実行2712# Run the test suite
2299if ! npm test 2>&1; then2713if ! npm test 2>&1; then
2300 echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&22714 echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
2301 exit 22715 exit 2
2308 Stop2722 Stop
2309</h3>2723</h3>
2310 2724
2311メイン Claude Code エージェントが応答を終了したときに実行されます。ユーザー割り込みが原因で停止が発生した場合は実行されません。API エラーは代わりに[StopFailure](#stopfailure)を発火させます。2725メインの Claude Code エージェントが応答を終えたときに実行されます。ユーザーの中断によって停止した場合は実行されません。API エラーの場合は、代わりに [StopFailure](#stopfailure) が発火します。
2312 2726
2313<Tip>2727<Tip>
2314 [`/goal`](/docs/ja/goal)コマンドは、セッション スコープのプロンプト ベースの Stop フックの組み込みショートカットです。Claude が条件が成立するまで作業を続けるようにしたいが、フック設定を書きたくない場合に使用します。2728 [`/goal`](/docs/ja/goal) コマンドは、セッションスコープのプロンプトベースの Stop フックの組み込みショートカットです。フックの設定を書かずに、ある条件に向けて Claude に作業を続けさせたい場合に使用します。
2315</Tip>2729</Tip>
2316 2730
2317<h4 id="stop-input">2731<h4 id="stop-input">
2318 Stop 入力2732 Stop の入力
2319</h4>2733</h4>
2320 2734
2321[共通入力フィールド](#common-input-fields)に加えて、Stop フックは `stop_hook_active`、`last_assistant_message`、`background_tasks`、`session_crons` を受け取ります。`stop_hook_active` フィールドは、Claude Code がすでに stop フックの結果として続行している場合は `true` です。この値をチェックするか、Claude Code が無限に実行されるのを防ぐためにトランスクリプトを処理します。`last_assistant_message` フィールドは Claude の最終応答のテキスト コンテンツを含むため、フックはトランスクリプト ファイルを解析せずにアクセスできます。2735[共通の入力フィールド](#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) を設定します。
2322 2736
2323`background_tasks` と `session_crons` 配列は、Claude Code v2.1.145 以降で利用可能で、フックが「セッションが完了」と「セッションが一時停止してバックグラウンド作業が再開されるのを待機」を区別できます。タスク レジストリに到達可能な場合は両方の配列が存在し、何も進行中または予定されていない場合は空です。2737`last_assistant_message` フィールドには Claude の最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにアクセスできます。読み上げや通知のフックなど、完了したばかりのターンに基づいて動作するフックでは、`transcript_path` を読み取るのではなくこのフィールドを使用してください。すべてのバージョンで、Stop の時点でトランスクリプトファイルに最終メッセージが含まれているとは限らないためです。
2324 2738
2325`background_tasks` の各エントリは 1 つの進行中のタスクを説明し、これらのフィールドを使用します。2739`background_tasks` および `session_crons` 配列により、フックは「セッションが完了した」状態と「セッションがバックグラウンド作業による再開を待って一時停止している」状態を区別できます。どちらの配列も、タスクレジストリにアクセスできる場合に存在し、実行中またはスケジュール済みのものがない場合は空になります。
2740
2741`background_tasks` の各エントリは実行中のタスク 1 つを表し、以下のフィールドを使用します。
2326 2742
2327| フィールド | 説明 |2743| フィールド | 説明 |
2328| :- | :- |2744| :- | :- |
2329| `id` | タスク識別子 |2745| `id` | タスクの識別子 |
2330| `type` | フレンドリーなタスク タイプ ラベル（`shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session`、`MCP task` など）。各ラベルは Claude Code のどの機能がタスクを作成したかを識別します。認識されないタイプの場合は生の判別式にフォールバック |2746| `type` | `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session`、`MCP task` などのわかりやすいタスクタイプのラベル。各ラベルは、どの Claude Code 機能がタスクを作成したかを示します。認識されないタイプの場合は、生の識別子にフォールバックします |
2331| `status` | 現在のタスク ステータス |2747| `status` | 現在のタスクのステータス |
2332| `description` | フリー テキスト説明。1000 文字でキャップされ、クリップされた場合は文字列内に `… [+N chars]` マーカー |2748| `description` | 自由形式の説明。1000 文字が上限で、切り詰められた場合は文字列内に `… [+N chars]` マーカーが付きます |
2333| `command` | シェル コマンド ライン。1000 文字でキャップ。`shell` タスクの場合のみ存在 |2749| `command` | シェルのコマンドライン。1000 文字が上限です。`shell` タスクの場合のみ存在します |
2334| `agent_type` | サブエージェント タイプ名。`subagent` タスクの場合のみ存在 |2750| `agent_type` | サブエージェントのタイプ名。`subagent` タスクの場合のみ存在します |
2335| `server` | MCP サーバー名。`monitor` と `MCP task` タスクの場合のみ存在 |2751| `server` | MCP サーバー名。`monitor` および `MCP task` タスクの場合のみ存在します |
2336| `tool` | MCP ツール名。`monitor` と `MCP task` タスクの場合のみ存在 |2752| `tool` | MCP ツール名。`monitor` および `MCP task` タスクの場合のみ存在します |
2337| `name` | ワークフロー名。`workflow` タスクの場合のみ存在 |2753| `name` | ワークフロー名。`workflow` タスクの場合のみ存在します |
2338 2754
2339`session_crons` の各エントリは 1 つのセッション スコープのスケジュール済みウェイクアップを説明し、`CronCreate`、`ScheduleWakeup`、`/loop` から取得されます。2755`session_crons` の各エントリは、`CronCreate`、`ScheduleWakeup`、`/loop` から取得された、セッションスコープのスケジュールされたウェイクアップ 1 つを表します。
2340 2756
2341| フィールド | 説明 |2757| フィールド | 説明 |
2342| :- | :- |2758| :- | :- |
2343| `id` | Cron タスク識別子 |2759| `id` | cron タスクの識別子 |
2344| `schedule` | Cron 式（例：`0 9 * * 1-5`） |2760| `schedule` | cron 式。例: `0 9 * * 1-5` |
2345| `recurring` | スケジュールが単一の発火時刻をエンコードする 1 回限りのウェイクアップの場合は `false`、すべてのマッチで再発火するタスクの場合は `true` |2761| `recurring` | スケジュールが単一の発火時刻を表す 1 回限りのウェイクアップの場合は `false`、マッチするたびに再発火するタスクの場合は `true` |
2346| `prompt` | Cron が発火するときに送信されるプロンプト。1000 文字でキャップされ、同じ `… [+N chars]` マーカー |2762| `prompt` | cron の発火時に送信されるプロンプト。1000 文字が上限で、同じ `… [+N chars]` マーカーが付きます |
2347 2763
2348この例は、1 つの進行中のシェル タスクと 1 つの定期的な cron を含む Stop 入力を示しています。2764以下の例は、実行中のシェルタスク 1 つと繰り返し実行される cron 1 つを含む Stop の入力を示しています。
2349 2765
2350```json theme={null}2766```json theme={null}
2351{2767{
2377```2793```
2378 2794
2379<h4 id="stop-decision-control">2795<h4 id="stop-decision-control">
2380 Stop 決定制御2796 Stop の決定制御
2381</h4>2797</h4>
2382 2798
2383`Stop` と `SubagentStop` フックは Claude が続行するかどうかを制御できます。すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、フック スクリプトはこれらのイベント固有のフィールドを返すことができます。2799`Stop` および `SubagentStop` フックは、Claude が続行するかどうかを制御できます。すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。
2384 2800
2385| フィールド | 説明 |2801| フィールド | 説明 |
2386| :- | :- |2802| :- | :- |
2387| `decision` | `"block"` は Claude が停止するのを防止。Claude を停止させるには省略 |2803| `decision` | `"block"` を指定すると Claude の停止を阻止します。Claude の停止を許可するには省略します |
2388| `reason` | `decision` が `"block"` のときに必須。Claude が続行すべき理由を伝える |2804| `reason` | `decision` が `"block"` の場合は必須です。Claude に続行すべき理由を伝えます |
2389| `hookSpecificOutput.additionalContext` | 非エラー フィードバック Claude 用。会話は続行されるため Claude が対応できますが、`decision: "block"` とは異なり、トランスクリプトでは「Stop フック フィードバック」としてラベル付けされ、フック エラー通知は表示されません |2805| `hookSpecificOutput.additionalContext` | Claude へのエラーではないフィードバック。Claude がそれに対応できるよう会話は続行されますが、`decision: "block"` とは異なり、トランスクリプトにはフックエラーではなくフックのフィードバックとして表示されます |
2806
2807終了コード 2 で終了してブロックするフックは、`reason` と同じように処理されます。Claude は、続行すべき理由の説明として stderr メッセージを受け取ります。
2390 2808
2391```json theme={null}2809```json theme={null}
2392{2810{
2395}2813}
2396```2814```
2397 2815
2398`additionalContext` を使用する場合、フックが設計通りに機能し、Claude にガイダンスを提供しています。例えば、「完了する前にテスト スイートを実行してください」。会話は `stop_hook_active` 入力と 8 回連続継続キャップと同じループ保護を通じて続行されます。2816「完了前にテストスイートを実行する」など、フックが設計どおりに動作して Claude にガイダンスを与えている場合は、`additionalContext` を使用してください。これは `decision: "block"` と同じループ保護（`stop_hook_active` 入力と、連続継続 8 回の上限）を通じて会話を継続させますが、トランスクリプトには `Stop hook feedback` というラベルが付き、フックエラーの通知は表示されません。
2399 2817
2400```json theme={null}2818```json theme={null}
2401{2819{
2410 StopFailure2828 StopFailure
2411</h3>2829</h3>
2412 2830
2413[Stop](#stop)の代わりに、ターンが API エラーのために終了するときに実行されます。出力と終了コードは無視されます。Claude が API エラーのため応答を完了できない場合、失敗をログ、アラートを送信、または回復アクションを実行するのに使用します。2831API エラーによってターンが終了したときに、[Stop](#stop) の代わりに実行されます。Claude Code は、[`terminalSequence`](#emit-terminal-notifications) を除き、フックの出力と終了コードを無視します。レート制限、認証の問題、その他の API エラーによって Claude が応答を完了できない場合に、失敗をログに記録したり、アラートを送信したり、復旧アクションを実行したりするために使用します。
2414 2832
2415<h4 id="stopfailure-input">2833<h4 id="stopfailure-input">
2416 StopFailure 入力2834 StopFailure の入力
2417</h4>2835</h4>
2418 2836
2419[共通入力フィールド](#common-input-fields)に加えて、StopFailure フックは `error`、オプションの `error_details`、およびオプションの `last_assistant_message` を受け取ります。`error` フィールドはエラー タイプを識別し、マッチャー フィルタリングに使用されます。2837[共通の入力フィールド](#common-input-fields)に加えて、StopFailure フックは `error`、省略可能な `error_details`、省略可能な `last_assistant_message` を受け取ります。`error` フィールドはエラーの種類を示し、matcher のフィルタリングに使用されます。
2420 2838
2421| フィールド | 説明 |2839| フィールド | 説明 |
2422| :- | :- |2840| :- | :- |
2423| `error` | エラー タイプ: `rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、または `unknown` |2841| `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` |
2424| `error_details` | 利用可能な場合、エラーに関する追加詳細 |2842| `error_details` | エラーに関する追加の詳細（利用可能な場合） |
2425| `last_assistant_message` | 会話に表示されるレンダリングされたエラー テキスト。`Stop` と `SubagentStop` とは異なり、このフィールドは Claude の会話出力ではなく、`"API Error: Rate limit reached"` などの API エラー文字列を含みます |2843| `last_assistant_message` | 会話に表示されたレンダリング済みのエラーテキスト。このフィールドに Claude の会話出力が含まれる `Stop` や `SubagentStop` とは異なり、`StopFailure` では `"API Error: Rate limit reached"` のような API エラー文字列そのものが含まれます |
2426 2844
2427```json theme={null}2845```json theme={null}
2428{2846{
2436}2854}
2437```2855```
2438 2856
2439StopFailure フックは決定制御がありません。通知とログの目的でのみ実行されます。2857StopFailure フックには決定制御がありません。通知とログ記録の目的でのみ実行されます。
2440 2858
2441<h3 id="teammateidle">2859<h3 id="teammateidle">
2442 TeammateIdle2860 TeammateIdle
2443</h3>2861</h3>
2444 2862
2445[エージェント チーム](/docs/ja/agent-teams)チームメイトがターンを終了した後、アイドル状態になろうとしているときに実行されます。これを使用してチームメイトが作業を停止する前に品質ゲートを実施します。例えば、lint チェックの合格を要求したり、出力ファイルが存在することを確認したりします。2863[エージェントチーム](/docs/ja/agent-teams)のチームメイトがターンを終えてアイドル状態になろうとしているときに実行されます。リントチェックの合格を必須にしたり、出力ファイルの存在を確認したりするなど、チームメイトが作業を停止する前に品質ゲートを適用するために使用します。
2446 2864
2447`TeammateIdle` フックが終了コード 2 で終了すると、チームメイトは stderr メッセージをフィードバックとして受け取り、アイドル状態になる代わりに作業を続行します。チームメイト全体を停止する代わりに再実行するには、`{"continue": false, "stopReason": "..."}` を含む JSON を返します。TeammateIdle フックはマッチャーをサポートせず、すべての出現で発火します。2865TeammateIdle フックは matcher をサポートしておらず、すべての発生時に発火します。
2448 2866
2449<h4 id="teammateidle-input">2867<h4 id="teammateidle-input">
2450 TeammateIdle 入力2868 TeammateIdle の入力
2451</h4>2869</h4>
2452 2870
2453[共通入力フィールド](#common-input-fields)に加えて、TeammateIdle フックは `teammate_name` と `team_name` を受け取ります。2871[共通の入力フィールド](#common-input-fields)に加えて、TeammateIdle フックは `teammate_name` と `team_name` を受け取ります。
2454 2872
2455```json theme={null}2873```json theme={null}
2456{2874{
2467| フィールド | 説明 |2885| フィールド | 説明 |
2468| :- | :- |2886| :- | :- |
2469| `teammate_name` | アイドル状態になろうとしているチームメイトの名前 |2887| `teammate_name` | アイドル状態になろうとしているチームメイトの名前 |
2470| `team_name` | チームの名前 |2888| `team_name` | 非推奨。セッションから派生したチーム名。将来のリリースで削除されます |
2471 2889
2472<h4 id="teammateidle-decision-control">2890<h4 id="teammateidle-decision-control">
2473 TeammateIdle 決定制御2891 TeammateIdle の決定制御
2474</h4>2892</h4>
2475 2893
2476TeammateIdle フックはチームメイト動作を制御する 2 つの方法をサポートしています。2894TeammateIdle フックは、チームメイトの動作を制御する 2 つの方法をサポートしています。
2477 2895
2478* **終了コード 2**: チームメイトは stderr メッセージをフィードバックとして受け取り、アイドル状態になる代わりに作業を続行します。2896* **終了コード 2**: チームメイトは stderr メッセージをフィードバックとして受け取り、アイドル状態にならずに作業を続けます。
2479* **JSON `{"continue": false, "stopReason": "..."}`**: チームメイト全体を停止し、`Stop` フック動作と一致します。`stopReason` はユーザーに表示されます。2897* **JSON `{"continue": false, "stopReason": "..."}`**: `Stop` フックの動作と同様に、チームメイトを完全に停止します。`stopReason` はユーザーに表示されます。
2480 2898
2481この例は、チームメイトがアイドル状態になることを許可する前に、ビルド アーティファクトが存在することをチェックします。2899以下の例は、チームメイトがアイドル状態になるのを許可する前に、ビルドアーティファクトが存在することを確認します。
2482 2900
2483```bash theme={null}2901```bash theme={null}
2484#!/bin/bash2902#!/bin/bash
2495 ConfigChange2913 ConfigChange
2496</h3>2914</h3>
2497 2915
2498セッション中に設定ファイルが変更されるときに実行されます。設定変更を監査したり、セキュリティ ポリシーを実施したり、設定ファイルへの不正な変更をブロックしたりするのに使用します。2916セッション中に設定ファイルが変更されたときに実行されます。設定の変更を監査したり、セキュリティポリシーを適用したり、設定ファイルへの不正な変更をブロックしたりするために使用します。
2499 2917
2500ConfigChange フックは設定ファイル、管理ポリシー設定、スキル ファイルの変更に対して発火します。入力の `source` フィールドは、どのタイプの設定が変更されたかを示し、オプションの `file_path` フィールドは変更されたファイルへのパスを提供します。2918Claude Code は、設定ファイル、管理ポリシーファイル、またはスキルファイルが変更されたときに ConfigChange フックを実行します。管理ポリシーの場合は、`managed-settings.json` または `managed-settings.d/` 内のファイルが変更された場合にのみ実行します。[サーバー管理設定](/docs/ja/server-managed-settings)、および macOS の管理された環境設定や Windows のレジストリポリシーへの変更は、フックを実行せずに適用します。[`wslInheritsWindowsSettings`](/docs/ja/settings-reference#wslinheritswindowssettings) を使用した WSL でも、Windows 側の管理設定ファイルの変更をポリシーのポーリング時にフックを実行せずに適用します。
2501 2919
2502マッチャーは設定ソースでフィルタリングします。2920matcher は設定のソースでフィルタリングします。
2503 2921
2504| マッチャー | いつ発火するか |2922| Matcher | 発火するタイミング |
2505| :- | :- |2923| :- | :- |
2506| `user_settings` | `~/.claude/settings.json` が変更 |2924| `user_settings` | `~/.claude/settings.json` が変更された |
2507| `project_settings` | `.claude/settings.json` が変更 |2925| `project_settings` | `.claude/settings.json` が変更された |
2508| `local_settings` | `.claude/settings.local.json` が変更 |2926| `local_settings` | `.claude/settings.local.json` が変更された |
2509| `policy_settings` | 管理ポリシー設定が変更 |2927| `policy_settings` | `managed-settings.json` または `managed-settings.d/` 内のファイルが変更された |
2510| `skills` | `.claude/skills/` のスキル ファイルが変更 |2928| `skills` | `.claude/skills/` 内のスキルファイルが変更された |
2511 2929
2512この例は、セキュリティ監査のためにすべての設定変更をログします。2930以下の例は、セキュリティ監査のためにすべての設定変更をログに記録します。
2513 2931
2514```json theme={null}2932```json theme={null}
2515{2933{
2530```2948```
2531 2949
2532<h4 id="configchange-input">2950<h4 id="configchange-input">
2533 ConfigChange 入力2951 ConfigChange の入力
2534</h4>2952</h4>
2535 2953
2536[共通入力フィールド](#common-input-fields)に加えて、ConfigChange フックは `source` とオプションで `file_path` を受け取ります。`source` フィールドは、どのタイプの設定が変更されたかを示し、`file_path` は変更されたファイルへのパスを提供します。2954[共通の入力フィールド](#common-input-fields)に加えて、ConfigChange フックは `source` と、省略可能な `file_path` を受け取ります。`source` フィールドはどの種類の設定が変更されたかを示し、`file_path` は変更された特定のファイルへのパスを提供します。
2537 2955
2538```json theme={null}2956```json theme={null}
2539{2957{
2547```2965```
2548 2966
2549<h4 id="configchange-decision-control">2967<h4 id="configchange-decision-control">
2550 ConfigChange 決定制御2968 ConfigChange の決定制御
2551</h4>2969</h4>
2552 2970
2553ConfigChange フックは設定変更が有効になるのをブロックできます。終了コード 2 または JSON `decision` を使用して変更を防止します。ブロックされた場合、新しい設定は実行中のセッションに適用されません。2971ConfigChange フックは、設定の変更が反映されるのをブロックできます。変更を阻止するには、終了コード 2 または JSON の `decision` を使用します。ブロックされた場合、新しい設定は実行中のセッションに適用されません。
2554 2972
2555| フィールド | 説明 |2973| フィールド | 説明 |
2556| :- | :- |2974| :- | :- |
2557| `decision` | `"block"` は設定変更が適用されるのを防止。変更を許可するには省略 |2975| `decision` | `"block"` を指定すると設定の変更が適用されるのを阻止します。変更を許可するには省略します |
2558| `reason` | `decision` が `"block"` のときにユーザーに表示される説明 |2976| `reason` | 受け付けられますが、表示されることはありません |
2559 2977
2560```json theme={null}2978```json theme={null}
2561{2979{
2564}2982}
2565```2983```
2566 2984
2567`policy_settings` の変更はブロックできません。フックは `policy_settings` ソースに対して引き続き発火するため、監査ログに使用できますが、ブロッキング決定は無視されます。これにより、エンタープライズ管理設定が常に有効になることが保証されます。2985`policy_settings` の変更はブロックできません。マシン上の管理設定ファイルが変更されると、`policy_settings` ソースに対してもフックは発火するため、それらの編集をログに記録するために使用できますが、ブロックの決定はすべて無視されます。これにより、エンタープライズで管理される設定が常に反映されることが保証されます。[サーバー管理設定](/docs/ja/server-managed-settings)が届いたり更新されたりしたときには、Claude Code は `ConfigChange` フックを実行しません。
2986
2987Claude Code は ConfigChange フックの JSON 出力からブロックの決定に基づいて動作し、`systemMessage` と `continue` は破棄します。ブロックされた変更については、`reason` でブロックした場合も終了コード 2 の stderr でブロックした場合も、ユーザーにも Claude にもメッセージは表示されません。Claude Code はデバッグログに 1 行書き込むだけです。
2568 2988
2569<h3 id="cwdchanged">2989<h3 id="cwdchanged">
2570 CwdChanged2990 CwdChanged
2571</h3>2991</h3>
2572 2992
2573セッション中に作業ディレクトリが変更されるときに実行されます。例えば、Claude が `cd` コマンドを実行するとき。これを使用してディレクトリ変更に反応します。環境変数をリロードしたり、プロジェクト固有のツールチェーンをアクティブにしたり、セットアップ スクリプトを自動的に実行したりします。[FileChanged](#filechanged)とペアになり、[direnv](https://direnv.net/)などのツール用に、ディレクトリごとの環境を管理します。2993メイン会話内のシェルコマンドが作業ディレクトリを変更したとき、たとえば Claude が `cd` コマンドを実行したときに実行されます。環境変数の再読み込み、プロジェクト固有のツールチェーンの有効化、セットアップスクリプトの自動実行など、ディレクトリの変更に対応するために使用します。ディレクトリごとの環境を管理する [direnv](https://direnv.net/) のようなツールでは、[FileChanged](#filechanged) と組み合わせて使用します。
2574 2994
2575CwdChanged フックは `CLAUDE_ENV_FILE` にアクセスできます。そのファイルに書き込まれた変数は、[SessionStart フック](#persist-environment-variables)と同じように、セッション中の後続の Bash コマンドに永続化されます。2995CwdChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の CwdChanged イベントで Claude Code がクリアするまで、後続の Bash コマンドに引き継がれます。
2576 2996
2577CwdChanged はマッチャーをサポートせず、すべてのディレクトリ変更で発火します。2997CwdChanged は matcher をサポートしておらず、すべての発生時に発火します。
2578 2998
2579<h4 id="cwdchanged-input">2999<h4 id="cwdchanged-input">
2580 CwdChanged 入力3000 CwdChanged の入力
2581</h4>3001</h4>
2582 3002
2583[共通入力フィールド](#common-input-fields)に加えて、CwdChanged フックは `old_cwd` と `new_cwd` を受け取ります。3003[共通の入力フィールド](#common-input-fields)に加えて、CwdChanged フックは `old_cwd` と `new_cwd` を受け取ります。
2584 3004
2585```json theme={null}3005```json theme={null}
2586{3006{
2594```3014```
2595 3015
2596<h4 id="cwdchanged-output">3016<h4 id="cwdchanged-output">
2597 CwdChanged 出力3017 CwdChanged の出力
2598</h4>3018</h4>
2599 3019
2600すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、CwdChanged フックは `watchPaths` を返して、[FileChanged](#filechanged)が監視するファイル パスを動的に設定できます。3020すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、CwdChanged フックは `watchPaths` を返して、[FileChanged](#filechanged) が監視するファイルパスを動的に設定できます。
2601 3021
2602| フィールド | 説明 |3022| フィールド | 説明 |
2603| :- | :- |3023| :- | :- |
2604| `watchPaths` | 絶対パスの配列。現在の動的監視リストを置き換えます（マッチャー設定からのパスは常に監視されます）。新しいディレクトリに入るときは、空の配列を返すのが一般的です |3024| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` 設定のパスは常に監視されます。空の配列を返すと動的なリストがクリアされます。これは新しいディレクトリに移動するときによく使われます |
3025
3026CwdChanged フックには決定制御がありません。ディレクトリの変更をブロックすることはできません。
2605 3027
2606CwdChanged フックは決定制御がありません。ディレクトリ変更をブロックできません。3028Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` は破棄します。インタラクティブセッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。
3029
3030<h3 id="directoryadded">
3031 DirectoryAdded
3032</h3>
3033
3034セッション中に `/add-dir` コマンドで作業ディレクトリを追加した後、または SDK クライアントが `register_repo_root` 制御リクエストで作業ディレクトリを追加した後に実行されます。新しく追加されたリポジトリを準備するため、たとえば依存関係をインストールするために使用します。
3035
3036Claude Code は以下の場合にこのイベントを発火しません。
3037
3038* `--add-dir` 起動フラグでディレクトリを渡した場合。これらのディレクトリは [SessionStart](#sessionstart) で対応します
3039* `/permissions` の Workspace タブでディレクトリを追加した場合
3040* すでに作業ディレクトリであるディレクトリ、または作業ディレクトリ内のディレクトリを追加した場合
3041
3042Claude Code はサンドボックスと権限の状態を更新した後に DirectoryAdded を発火するため、フックの実行時には、サンドボックス化されたツールからすでに新しいディレクトリが見えています。フックコマンド自体はサンドボックスの外で実行されます。
3043
3044Claude Code はフックを待ちません。追加は即座に完了し、フックはデフォルトの 600 秒のタイムアウトでバックグラウンドで実行されます。
3045
3046matcher はディレクトリの追加方法でフィルタリングします。
3047
3048| Matcher | 発火するタイミング |
3049| :- | :- |
3050| `slash_command` | `/add-dir` でディレクトリを追加した |
3051| `register_repo_root` | SDK クライアントが `register_repo_root` 制御リクエストでディレクトリを追加した |
3052
3053<h4 id="directoryadded-input">
3054 DirectoryAdded の入力
3055</h4>
3056
3057[共通の入力フィールド](#common-input-fields)に加えて、DirectoryAdded フックは `directory` と `source` を受け取ります。
3058
3059| フィールド | 説明 |
3060| :- | :- |
3061| `directory` | 追加されたディレクトリの絶対パス |
3062| `source` | ディレクトリの追加方法。`/add-dir` の場合は `"slash_command"`、SDK 制御リクエストの場合は `"register_repo_root"` |
3063
3064```json theme={null}
3065{
3066 "session_id": "abc123",
3067 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
3068 "cwd": "/Users/my-project",
3069 "hook_event_name": "DirectoryAdded",
3070 "directory": "/Users/my-other-repo",
3071 "source": "slash_command"
3072}
3073```
3074
3075DirectoryAdded フックには決定制御がありません。フックの実行時には追加がすでに完了しているため、追加をブロックすることはできません。Claude Code は JSON 出力から `continue` フィールドを破棄し、残りはソースごとに異なる方法で扱います。
3076
3077* `slash_command`: Claude Code はフックの `systemMessage` をユーザーに表示するのではなく、次の会話ターンでコンテキストとして Claude に配信します。失敗したフックの数がトランスクリプトに表示されます。失敗の完全な出力はデバッグログに記録されます
3078* `register_repo_root`: Claude Code は `systemMessage` の出力と失敗の出力をデバッグログにのみ書き込みます
2607 3079
2608<h3 id="filechanged">3080<h3 id="filechanged">
2609 FileChanged3081 FileChanged
2610</h3>3082</h3>
2611 3083
2612監視されたファイルがディスク上で変更されるときに実行されます。プロジェクト設定ファイルが変更されたときに環境変数をリロードするのに便利です。3084監視対象のファイルがディスク上で変更されたときに実行されます。Claude Code はツール呼び出しを調べるのではなくファイルシステムウォッチャーで変更を検出するため、`Edit` や `Write` のツール呼び出し、Claude が `Bash` で実行したスクリプト、あるいは Claude Code 外部のプロセスなど、何がファイルを変更したかにかかわらずフックを実行します。一般的な用途は、プロジェクトの設定ファイルが変更されたときに環境変数を再読み込みすることです。
3085
3086このイベントの `matcher` には 2 つの役割があります。
3087
3088* **監視リストの構築**: 値は `|` で分割され、各セグメントが作業ディレクトリ内のリテラルなファイル名として登録されます。そのため、`".envrc|.env"` はちょうどその 2 つのファイルを監視します。ここでは正規表現パターンは役に立ちません。`^\.env` のような値は、文字どおり `^\.env` という名前のファイルを監視します。
3089* **実行するフックのフィルタリング**: 監視対象のファイルが変更されると、同じ値を使用して、変更されたファイルのベース名に対して標準の [matcher ルール](#matcher-patterns)を適用し、実行するフックグループをフィルタリングします。
3090
3091以下の例は、`Bash` コマンドや外部スクリプトによるファイルの書き換えを含め、変更があるたびに `data.csv` の改行コードを正規化します。
3092
3093```json theme={null}
3094{
3095 "hooks": {
3096 "FileChanged": [
3097 {
3098 "matcher": "data.csv",
3099 "hooks": [
3100 {
3101 "type": "command",
3102 "command": "/path/to/normalize-line-endings.sh"
3103 }
3104 ]
3105 }
3106 ]
3107 }
3108}
3109```
3110
3111フックは、stdin 上の [JSON 入力](#filechanged-input)の `file_path` フィールドから、変更されたファイルの絶対パスを読み取ります。`grep` によるガードは `perl` が削除するもの、つまり行末の CR と同じものを検査するため、正規化後の実行ではファイルに触れずに終了します。ガードがより緩いと無限ループになります。`perl -i` は何も置換しない場合でもファイルを書き換え、Claude Code は書き換えのたびにフックを再度実行するためです。このスクリプトを `/path/to/normalize-line-endings.sh` に保存し、実行可能にしてください。
2613 3112
2614このイベントの `matcher` は 2 つの役割を果たします。3113```bash theme={null}
3114#!/bin/bash
3115FILE=$(jq -r .file_path)
3116if grep -q $'\r$' "$FILE"; then
3117 perl -pi -e 's/\r$//' "$FILE"
3118fi
3119```
2615 3120
2616* **監視リストを構築**: 値は `|` で分割され、各セグメントは作業ディレクトリのリテラル ファイル名として登録されるため、`.envrc|.env` はこれら 2 つのファイルを正確に監視します。正規表現パターンはここでは役に立ちません。`^\.env` のような値は `^\.env` という文字通りの名前のファイルを監視します。3121フックが機能することを確認するには、`Bash` コマンドで `data.csv` に CRLF の行を追記するよう Claude に依頼します。Claude Code がフックを実行し、ファイルの改行コードは LF になります。
2617* **どのフックが実行されるかをフィルタリング**: 監視されたファイルが変更されると、同じ値は標準[マッチャー ルール](#matcher-patterns)を使用して、変更されたファイルのベース名に対してどのフック グループが実行されるかをフィルタリングします。
2618 3122
2619FileChanged フックは `CLAUDE_ENV_FILE` にアクセスできます。そのファイルに書き込まれた変数は、[SessionStart フック](#persist-environment-variables)と同じように、セッション中の後続の Bash コマンドに永続化されます。3123事前に名前を指定できないファイルを監視するには、フックから [`watchPaths`](#filechanged-output) を返して監視リストを動的に更新します。Claude Code は監視対象のファイルが何らかの形で指定された場合にのみウォッチャーを開始するため、少なくとも 1 つのファイルを matcher で指定した FileChanged グループ、または `watchPaths` を返す [SessionStart](#sessionstart-decision-control) や [CwdChanged](#cwdchanged) フックでリストを初期化してください。監視対象のファイルが変更されたときにどのフックグループを実行するかは引き続き matcher でフィルタリングされるため、動的なパスを処理するグループでは matcher を省略してください。省略した matcher はすべての監視対象ファイルにマッチし、監視リストには何も追加しません。`"*"` matcher もすべてのファイルにマッチしますが、Claude Code はこれを他の値と同様に、`*` という名前のリテラルなファイルとして監視リストに登録します。
3124
3125FileChanged フックは [`CLAUDE_ENV_FILE`](#persist-environment-variables) にアクセスできます。そのファイルに書き込まれた変数は、次の [CwdChanged](#cwdchanged) イベントで Claude Code がクリアするまで、後続の Bash コマンドに引き継がれます。
2620 3126
2621<h4 id="filechanged-input">3127<h4 id="filechanged-input">
2622 FileChanged 入力3128 FileChanged の入力
2623</h4>3129</h4>
2624 3130
2625[共通入力フィールド](#common-input-fields)に加えて、FileChanged フックは `file_path` と `event` を受け取ります。3131[共通の入力フィールド](#common-input-fields)に加えて、FileChanged フックは `file_path` と `event` を受け取ります。
2626 3132
2627| フィールド | 説明 |3133| フィールド | 説明 |
2628| :- | :- |3134| :- | :- |
2629| `file_path` | 変更されたファイルへの絶対パス |3135| `file_path` | 変更されたファイルの絶対パス |
2630| `event` | 何が起こったか: `"change"`（ファイル変更）、`"add"`（ファイル作成）、または `"unlink"`（ファイル削除） |3136| `event` | 何が起きたか。変更されたファイルの場合は `"change"`、作成されたファイルの場合は `"add"`、削除されたファイルの場合は `"unlink"` |
2631 3137
2632```json theme={null}3138```json theme={null}
2633{3139{
2641```3147```
2642 3148
2643<h4 id="filechanged-output">3149<h4 id="filechanged-output">
2644 FileChanged 出力3150 FileChanged の出力
2645</h4>3151</h4>
2646 3152
2647すべてのフックで利用可能な[JSON 出力フィールド](#json-output)に加えて、FileChanged フックは `watchPaths` を返して、監視されるファイル パスを動的に更新できます。3153すべてのフックで利用可能な [JSON 出力フィールド](#json-output)に加えて、FileChanged フックは `watchPaths` を返して、監視するファイルパスを動的に更新できます。
2648 3154
2649| フィールド | 説明 |3155| フィールド | 説明 |
2650| :- | :- |3156| :- | :- |
2651| `watchPaths` | 絶対パスの配列。現在の動的監視リストを置き換えます（マッチャー設定からのパスは常に監視されます）。フック スクリプトが変更されたファイルに基づいて検出した追加ファイルを監視する場合に使用します |3157| `watchPaths` | 絶対パスの配列。現在の動的な監視リストを置き換えます。`matcher` 設定のパスは常に監視されます。フックスクリプトが、変更されたファイルに基づいて監視すべき追加のファイルを見つけた場合に使用します |
3158
3159FileChanged フックには決定制御がありません。ファイルの変更が発生するのをブロックすることはできません。
2652 3160
2653FileChanged フックは決定制御がありません。ファイル変更をブロックできません。3161Claude Code は JSON 出力から `watchPaths` と `systemMessage` を読み取り、`continue` は破棄します。インタラクティブセッションでは、`systemMessage` を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。
2654 3162
2655<h3 id="worktreecreate">3163<h3 id="worktreecreate">
2656 WorktreeCreate3164 WorktreeCreate
2657</h3>3165</h3>
2658 3166
2659`claude --worktree` を実行するか、[サブエージェントが `isolation: "worktree"` を使用](/docs/ja/sub-agents#choose-the-subagent-scope)する場合、Claude Code は `git worktree` を使用して分離された作業コピーを作成します。WorktreeCreate フックを設定する場合、デフォルトの git 動作を置き換え、SVN、Perforce、Mercurial などの別のバージョン管理システムを使用できます。3167`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 などの別のバージョン管理システムを使用できるようになります。
2660 3168
2661フックは作成されたワークツリー ディレクトリへの絶対パスを返す必要があります。Claude Code はこ のパスを分離されたセッションの作業ディレクトリとして使用します。コマンド フックは stdout にパスを出力します。HTTP フックは `hookSpecificOutput.worktreePath` 経由で返します。3169フックはデフォルトの動作を完全に置き換えるため、[`.worktreeinclude`](/docs/ja/worktrees#copy-gitignored-files-into-worktrees) は処理されません。`.env` などのローカル設定ファイルを新しい worktree にコピーする必要がある場合は、フックスクリプト内でコピーしてください。
2662 3170
2663フックはデフォルトの git 動作を完全に置き換えるため、[`.worktreeinclude`](/docs/ja/worktrees#copy-gitignored-files-into-worktrees)は処理されません。`.env` などのローカル設定ファイルを新しいワークツリーにコピーする必要がある場合は、フック スクリプト内で実行してください。3171フックは、作成された worktree ディレクトリへのパスを返す必要があります。Claude Code はこのパスを分離されたセッションの作業ディレクトリとして使用します。各フックタイプがパスを返す方法については、[WorktreeCreate の出力](#worktreecreate-output)を参照してください。
2664 3172
2665この例は SVN 作業コピーを作成し、Claude Code が使用するパスを出力します。リポジトリ URL を自分のものに置き換えます。3173Claude Code はフックの成功と返されたパスに基づいて動作し、`systemMessage` と `continue` は破棄します。
3174
3175以下の例は、SVN の作業コピーを作成し、Claude Code が使用するパスを出力します。リポジトリの URL は自分のものに置き換えてください。
2666 3176
2667```json theme={null}3177```json theme={null}
2668{3178{
2681}3191}
2682```3192```
2683 3193
2684フックは stdin から JSON 入力からワークツリー `name` を読み取り、新しいディレクトリに新しいコピーをチェックアウトし、ディレクトリ パスを出力します。最後の行の `echo` は Claude Code が読み取るワークツリー パスです。他の出力を stderr にリダイレクトして、パスに干渉しないようにします。3194フックは stdin 上の JSON 入力から worktree の `name` を読み取り、新しいディレクトリに新しいコピーをチェックアウトして、そのディレクトリパスを出力します。最後の行の `echo` が、Claude Code が worktree のパスとして読み取るものです。パスの妨げにならないよう、その他の出力はすべて stderr にリダイレクトしてください。
2685 3195
2686<h4 id="worktreecreate-input">3196<h4 id="worktreecreate-input">
2687 WorktreeCreate 入力3197 WorktreeCreate の入力
2688</h4>3198</h4>
2689 3199
2690[共通入力フィールド](#common-input-fields)に加えて、WorktreeCreate フックは `name` フィールドを受け取ります。これは新しいワークツリーのスラッグ識別子で、ユーザーが指定するか自動生成されます（例えば、`bold-oak-a3f2`）。3200[共通の入力フィールド](#common-input-fields)に加えて、WorktreeCreate フックは `name` フィールドを受け取ります。これは新しい worktree のスラッグ識別子で、ユーザーが指定するか自動生成されます（例: `bold-oak-a3f2`）。
2691 3201
2692```json theme={null}3202```json theme={null}
2693{3203{
2700```3210```
2701 3211
2702<h4 id="worktreecreate-output">3212<h4 id="worktreecreate-output">
2703 WorktreeCreate 出力3213 WorktreeCreate の出力
2704</h4>3214</h4>
2705 3215
2706WorktreeCreate フックは標準的な許可/ブロック決定モデルを使用しません。代わりに、フックの成功または失敗が結果を決定します。フックは作成されたワークツリー ディレクトリへの絶対パスを返す必要があります。3216WorktreeCreate フックは、標準の許可/ブロックの判定モデルを使用しません。代わりに、フックの成功または失敗によって結果が決まります。フックは作成された worktree ディレクトリのパスを返す必要があります。
3217
3218* **コマンドフック**（`type: "command"`）：パスを stdout の最後の空でない行として出力します。Claude Code はその行を読み取る前に ANSI エスケープコードを取り除くため、`echo` の前に出力されたシェルの起動バナーは無視されます。フックのその他の出力はすべて stderr にリダイレクトしてください。
3219* **HTTP フック**（`type: "http"`）：レスポンスボディで `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` を返します。
2707 3220
2708* **コマンド フック** (`type: "command"`): stdout にパスを出力します。3221フックが失敗した場合、またはパスを生成しなかった場合、worktree の作成はエラーで失敗します。
2709* **HTTP フック** (`type: "http"`): レスポンス本体で `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` を返します。
2710 3222
2711フックが失敗するか出力を生成しない場合、ワークツリー作成はエラーで失敗します。3223Claude Code は相対パスをフックが実行されたディレクトリを基準に解決し、パス内の `.` や `..` セグメントを畳み込みます。解決後のパスが Claude Code が移動できるディレクトリでない場合、セッションはそのパスを示すエラーを出力し、終了コード 1 で終了します。
2712 3224
2713Claude Code は相対パスを、フックが実行されたディレクトリに対して解決します。結果のパスが Claude Code が入力できるディレクトリでない場合、セッションはパスを名前付けするエラーを出力し、終了コード 1 で終了します。v2.1.205 より前では、相対パスまたはディスク上に存在しないパスはセッション スタートアップでクラッシュし、`-p` を使用すると約 30 秒停止してから終了コード 0 で終了しました。3225Claude Code は、`.` や `..` セグメントを含む絶対パス、およびリポジトリルート配下のシンボリックリンクを経由するパスを拒否します。リポジトリにコミットされたシンボリックリンクによって、worktree がリポジトリの外にリダイレクトされる可能性があるためです。エラーには拒否されたコンポーネントが示されます。リポジトリ内のシンボリックリンクを経由しない正規化されたパスを返してください。v2.1.216 より前は、worktree の作成はこのチェックを行わずにフックのパスに従っていました。
2714 3226
2715<h3 id="worktreeremove">3227<h3 id="worktreeremove">
2716 WorktreeRemove3228 WorktreeRemove
2717</h3>3229</h3>
2718 3230
2719[WorktreeCreate](#worktreecreate)のクリーンアップ対応。このフックはワークツリーが削除されるときに発火します。`--worktree` セッションを終了して削除を選択するか、`isolation: "worktree"` を持つサブエージェントが完了するとき。git ベースのワークツリーの場合、Claude は `git worktree remove` で自動的にクリーンアップを処理します。git 以外のバージョン管理システムの WorktreeCreate フックを設定した場合、クリーンアップを処理するために WorktreeRemove フックとペアにします。なければ、ワークツリー ディレクトリはディスク上に残ります。3231worktree が削除されるときに実行されます。これは [WorktreeCreate](#worktreecreate) に対応するクリーンアップ用のイベントです。このイベントは次の場合に発生します。
3232
3233* `--worktree` セッションを終了し、削除を選択したとき
3234* `isolation: "worktree"` を持つサブエージェントが完了したとき
3235* フックが worktree を作成した[バックグラウンドセッション](/docs/ja/agent-view#what-deleting-a-session-removes)を削除したとき
3236
3237Git ベースの worktree の場合、Claude Code は `git worktree remove` でクリーンアップを自動的に処理します。WorktreeCreate フックを設定した場合は、WorktreeRemove フックと組み合わせて、作成した worktree のクリーンアップを制御してください。
2720 3238
2721Claude Code は WorktreeCreate が返したパスを `worktree_path` としてフック入力に渡します。この例はそのパスを読み取り、ディレクトリを削除します。3239* **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 の削除ルールを参照してください。
3240* **フックが 0 で終了した場合**：worktree は削除済みとして扱われます。Claude Code はフックからそれ以外の情報を読み取らないため、フックがディレクトリを確実に削除するようにしてください。
3241* **フックが 0 以外で終了した場合**：その後も `worktree_path` のディレクトリが存在していれば削除は失敗し、Git へのフォールバックは行われずに worktree はディスク上に残ります。0 以外で終了する前にディレクトリを削除したフックは、削除済みとして扱われます。失敗がどのように報告されるかについては、[WorktreeRemove の入力](#worktreeremove-input)を参照してください。
3242
3243Claude Code は WorktreeCreate フックが返したパスしか把握していないため、フックが作成した worktree に属するブランチを削除することはありません。WorktreeCreate フックがブランチを作成する場合は、WorktreeRemove フックでそのブランチを削除してください。
3244
3245Claude Code は、`systemMessage` や `continue` などの WorktreeRemove フックの [JSON 出力フィールド](#json-output)を破棄します。
3246
3247バックグラウンドセッションの削除では、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 より前は、フックはこれらのチェックなしに保存されたパスに対して実行されていました。
3248
3249Claude Code は、WorktreeCreate が返したパスをフック入力の `worktree_path` として渡します。次の例では、そのパスを読み取ってディレクトリを削除します。
2722 3250
2723```json theme={null}3251```json theme={null}
2724{3252{
2738```3266```
2739 3267
2740<h4 id="worktreeremove-input">3268<h4 id="worktreeremove-input">
2741 WorktreeRemove 入力3269 WorktreeRemove の入力
2742</h4>3270</h4>
2743 3271
2744[共通入力フィールド](#common-input-fields)に加え、WorktreeRemove フックは削除されるワークツリーへの絶対パスである `worktree_path` フィールドを受け取ります。3272[共通の入力フィールド](#common-input-fields)に加えて、WorktreeRemove フックは `worktree_path` フィールドを受け取ります。これは削除される worktree の絶対パスです。
2745 3273
2746```json theme={null}3274```json theme={null}
2747{3275{
2753}3281}
2754```3282```
2755 3283
2756WorktreeRemove フックは決定制御がありません。ワークツリー削除をブロックできませんが、バージョン管理状態の削除やアーカイブ変更などのクリーンアップ タスクを実行できます。フック失敗はデバッグ モードでのみログされます。3284WorktreeRemove フックの終了コードによって結果が決まります。フックが 0 以外で終了し、その後も `worktree_path` のディレクトリが存在する場合、削除は失敗します。
3285
3286* worktree はディスク上に残り、フックのコマンドと stderr は[デバッグログ](#debug-hooks)に送られます。
3287* バックグラウンドセッションを削除しようとしていた場合は、セッションも残ります。[agent view](/docs/ja/agent-view#what-deleting-a-session-removes) の拒否メッセージには、`exited 1` などフックがどのように終了したか、stderr の冒頭部分、そしてセッションを再度削除した場合にディレクトリが強制的に削除されるかどうかが表示されます。
2757 3288
2758<h3 id="precompact">3289<h3 id="precompact">
2759 PreCompact3290 PreCompact
2760</h3>3291</h3>
2761 3292
2762Claude Code がコンパクション操作を実行しようとしている前に実行されます。3293Claude Code がコンテキスト圧縮を実行する直前に実行されます。
2763 3294
2764マッチャー値は、コンパクションが手動でトリガーされたか自動的にトリガーされたかを示します。3295matcher の値は、圧縮が手動でトリガーされたか自動でトリガーされたかを示します。
2765 3296
2766| マッチャー | いつ発火するか |3297| Matcher | 発生するタイミング |
2767| :- | :- |3298| :- | :- |
2768| `manual` | `/compact` |3299| `manual` | `/compact` |
2769| `auto` | コンテキスト ウィンドウが満杯のときの自動コンパクション |3300| `auto` | 会話が[自動圧縮ウィンドウ](/docs/ja/model-config#set-the-auto-compact-window)に達したときの自動圧縮 |
3301
3302圧縮をブロックするには、終了コード 2 で終了します。手動の `/compact` の場合、stderr のメッセージがユーザーに表示されます。`"decision": "block"` を含む JSON を返してブロックすることもできます。
2770 3303
2771終了コード 2 でコンパクションをブロック。手動の `/compact` の場合、stderr メッセージはユーザーに表示されます。JSON で `"decision": "block"` を返してブロックすることもできます。3304自動圧縮をブロックした場合の効果は、発生するタイミングによって異なります。コンテキスト制限に達する前に予防的に圧縮がトリガーされた場合、Claude Code は圧縮をスキップし、会話は圧縮されないまま続行されます。API からすでに返されたコンテキスト制限エラーから回復するために圧縮がトリガーされた場合、元のエラーが表面化し、現在のリクエストは失敗します。
2772 3305
2773自動コンパクションのブロックは、いつ発火するかに応じて異なる効果があります。コンテキスト制限の前にコンパクションがプロアクティブにトリガーされた場合、Claude Code はそれをスキップし、会話は非圧縮で続行されます。コンテキスト制限エラーから回復するためにコンパクションがトリガーされた場合、基礎となるエラーが表示され、現在のリクエストが失敗します。3306Claude Code は PreCompact フックの `systemMessage` および `continue` フィールドを破棄します。
2774 3307
2775<h4 id="precompact-input">3308<h4 id="precompact-input">
2776 PreCompact 入力3309 PreCompact の入力
2777</h4>3310</h4>
2778 3311
2779[共通入力フィールド](#common-input-fields)に加えて、PreCompact フックは `trigger` と `custom_instructions` を受け取ります。`manual` の場合、`custom_instructions` はユーザーが `/compact` に渡すものを含みます。`auto` の場合、`custom_instructions` は空です。3312[共通の入力フィールド](#common-input-fields)に加えて、PreCompact フックは `trigger` と `custom_instructions` を受け取ります。`manual` の場合、`custom_instructions` にはユーザーが `/compact` に渡した内容が含まれ、何も渡さなかった場合は `null` になります。`auto` の場合、`custom_instructions` は `null` です。
2780 3313
2781```json theme={null}3314```json theme={null}
2782{3315{
2785 "cwd": "/Users/...",3318 "cwd": "/Users/...",
2786 "hook_event_name": "PreCompact",3319 "hook_event_name": "PreCompact",
2787 "trigger": "manual",3320 "trigger": "manual",
2788 "custom_instructions": ""3321 "custom_instructions": null
2789}3322}
2790```3323```
2791 3324
2793 PostCompact3326 PostCompact
2794</h3>3327</h3>
2795 3328
2796Claude Code がコンパクション操作を完了した後に実行されます。このイベントを使用して、新しいコンパクト状態に反応します。例えば、生成されたサマリーをログしたり、外部状態を更新したりします。3329Claude Code がコンテキスト圧縮を完了した後に実行されます。このイベントを使用すると、生成された要約をログに記録したり外部の状態を更新したりするなど、圧縮後の新しい状態に対応できます。Claude Code は PostCompact フックの `systemMessage` および `continue` フィールドを破棄します。
2797 3330
2798`PreCompact` と同じマッチャー値が適用されます。3331`PreCompact` と同じ matcher の値が適用されます。
2799 3332
2800| マッチャー | いつ発火するか |3333| Matcher | 発生するタイミング |
2801| :- | :- |3334| :- | :- |
2802| `manual` | `/compact` の後 |3335| `manual` | `/compact` の後 |
2803| `auto` | コンテキスト ウィンドウが満杯のときの自動コンパクション後 |3336| `auto` | 会話が[自動圧縮ウィンドウ](/docs/ja/model-config#set-the-auto-compact-window)に達したときの自動圧縮の後 |
2804 3337
2805<h4 id="postcompact-input">3338<h4 id="postcompact-input">
2806 PostCompact 入力3339 PostCompact の入力
2807</h4>3340</h4>
2808 3341
2809[共通入力フィールド](#common-input-fields)に加えて、PostCompact フックは `trigger` と `compact_summary` を受け取ります。`compact_summary` フィールドはコンパクション操作によって生成された会話サマリーを含みます。3342[共通の入力フィールド](#common-input-fields)に加えて、PostCompact フックは `trigger` と `compact_summary` を受け取ります。`compact_summary` フィールドには、圧縮によって生成された会話の要約が含まれます。
2810 3343
2811```json theme={null}3344```json theme={null}
2812{3345{
2819}3352}
2820```3353```
2821 3354
2822PostCompact フックは決定制御がありません。コンパクション結果に影響を与えることはできませんが、フォローアップ タスクを実行できます。3355PostCompact フックには判定の制御がありません。圧縮の結果に影響を与えることはできませんが、後続のタスクを実行できます。
3356
3357<h3 id="premodelswitch">
3358 PreModelSwitch
3359</h3>
3360
3361ユーザーまたはクライアントが要求したモデルの切り替えを Claude Code が適用する前に実行されます。切り替えのブロック、確認の要求、または切り替え前にそのコストを表示するために使用します。
3362
3363PreModelSwitch には Claude Code v2.1.251 以降が必要です。Claude Code は次のリクエストに対してこのフックを実行します。
3364
3365* `/model <name>` および `/model` ピッカー
3366* `Option+P` または `Alt+P` のモデルピッカー
3367* `/config` の Model 設定
3368* セッションのモデルが変わる場合の [fast mode](/docs/ja/fast-mode) のオン
3369* [Agent SDK](/docs/ja/agent-sdk/typescript#query-object) ホストまたは [Remote Control](/docs/ja/remote-control) からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更
3370
3371[モデルの自動フォールバック](/docs/ja/model-config#automatic-model-fallback)やセッション再開時のモデルの復元など、Claude Code が独自に行う切り替えについては PreModelSwitch フックは実行されません。これらの変更は [PostModelSwitch](#postmodelswitch) にのみ届きます。
3372
3373Claude Code は、matcher をセッションの切り替え先モデルの正規名と比較します。このとき `[1m]` サフィックスは無視されます。`opus` などのエイリアス、日付付きのモデル ID、Amazon Bedrock のモデル ID などのプロバイダー固有の ID はすべて、解決先の 1 つの正規名に一致するため、`claude-opus-5` は Opus 5 のあらゆる表記をカバーします。
3374
3375Claude Code が切り替え先の正規名を特定できない場合（たとえば [LLM ゲートウェイ](/docs/ja/llm-gateway)だけが認識するカスタムモデル ID など）、matcher に関係なくすべての PreModelSwitch フックが実行されます。したがって、ブロックを行うフックは matcher だけに頼るのではなく、入力の `to_model` を確認する必要があります。
3376
3377matcher は、完全一致の名前、`claude-opus-4-6|claude-opus-5` のような `|` 区切りのリスト、または `.*opus.*` のような正規表現として記述します。次の例では、完全一致の matcher を使用しつつフック入力の `to_model` も確認し、終了コード 2 で終了することで Opus 4.6 への切り替えを拒否し、それ以外の切り替え先は通過させます。
3378
3379<Tabs>
3380 <Tab title="macOS/Linux">
3381 このコマンドは `jq` で `to_model` を確認します。
3382
3383 ```json theme={null}
3384 {
3385 "hooks": {
3386 "PreModelSwitch": [
3387 {
3388 "matcher": "claude-opus-4-6",
3389 "hooks": [
3390 {
3391 "type": "command",
3392 "command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
3393 }
3394 ]
3395 }
3396 ]
3397 }
3398 }
3399 ```
3400 </Tab>
3401
3402 <Tab title="Windows (PowerShell)">
3403 PowerShell でスクリプトを実行するコマンドフックを登録します。
3404
3405 ```json theme={null}
3406 {
3407 "hooks": {
3408 "PreModelSwitch": [
3409 {
3410 "matcher": "claude-opus-4-6",
3411 "hooks": [
3412 {
3413 "type": "command",
3414 "command": "powershell.exe",
3415 "args": [
3416 "-NoProfile",
3417 "-ExecutionPolicy",
3418 "Bypass",
3419 "-File",
3420 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
3421 ]
3422 }
3423 ]
3424 }
3425 ]
3426 }
3427 }
3428 ```
3429
3430 次のスクリプトをプロジェクトの `.claude/hooks/block-opus-46.ps1` に保存します。
3431
3432 ```powershell theme={null}
3433 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3434 if ($hookInput.to_model -match 'opus-4-6') {
3435 [Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
3436 exit 2
3437 }
3438 exit 0
3439 ```
3440 </Tab>
3441</Tabs>
3442
3443フックが機能することを確認するには、別のモデルで実行中のセッションから `/model claude-opus-4-6` を実行します。Claude Code は現在のモデルを維持し、PreModelSwitch フックが切り替えをブロックしたことを、指定したメッセージを理由として報告します。
3444
3445<h4 id="premodelswitch-input">
3446 PreModelSwitch の入力
3447</h4>
3448
3449[共通の入力フィールド](#common-input-fields)に加えて、PreModelSwitch フックは次の表のフィールドを受け取ります。最後の 5 つは、会話を新しいモデルに再送信する際のコストを表すため、フックは切り替えの前にその数値を表示できます。
3450
3451| フィールド | 型 | 説明 |
3452| :- | :- | :- |
3453| `from_model` | string | 切り替え元のモデル ID |
3454| `to_model` | string | 切り替え先のモデル ID。matcher はこのモデルの正規名と比較されます |
3455| `requested_model` | string または `null` | リクエストで指定されたモデル：`opus` などのエイリアス、完全なモデル ID、またはデフォルトモデルがリクエストされた場合は `null` |
3456| `source` | string | リクエストの送信元：`/model <name>`、`/config` の Model 設定、または fast mode のオンの場合は `"command"`、モデルピッカーの場合は `"picker"`、Agent SDK ホストまたは Remote Control からの `set_model` リクエスト、または `apply_flag_settings` リクエストでのモデル変更の場合は `"sdk"` |
3457| `context_tokens` | number | 次のリクエストがプロンプトとして再送信するトークン数：メイン会話における最後の応答の入力、キャッシュ読み取り、キャッシュ作成、出力トークンの合計。最初の応答の前は `0` |
3458| `prompt_cache_warm` | boolean | 現在のモデルのプロンプトキャッシュがまだウォーム状態である可能性が高いかどうか。ウォーム状態の場合、切り替えによってキャッシュが失われます |
3459| `cache_ttl` | string | このセッションで Claude Code が要求する[プロンプトキャッシュの有効期間](/docs/ja/prompt-caching#cache-lifetime)：`"5m"` または `"1h"` |
3460| `estimated_cache_write_usd` | number | `to_model` 上で `context_tokens` を `cache_ttl` の料金でプロンプトキャッシュに書き込む推定コスト（米ドル）。次の応答は含みません。サーバーがコンテキスト全体を再キャッシュする必要がない場合もあるため、推定値として扱ってください |
3461| `pricing` | string | Claude Code が `estimated_cache_write_usd` をどのように算出したか：組織が独自の料金を設定している場合はその料金による `"configured"`、定価による `"catalog"`、または `to_model` の料金が不明で Claude Code がデフォルト料金を仮定した場合は `"default"` |
3462
3463次の例は、Sonnet 5 で実行中のセッションで `/model opus` を実行した場合の入力を示しています。
3464
3465```json theme={null}
3466{
3467 "session_id": "abc123",
3468 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
3469 "cwd": "/Users/...",
3470 "hook_event_name": "PreModelSwitch",
3471 "from_model": "claude-sonnet-5",
3472 "to_model": "claude-opus-5",
3473 "requested_model": "opus",
3474 "source": "command",
3475 "context_tokens": 182340,
3476 "prompt_cache_warm": true,
3477 "cache_ttl": "5m",
3478 "estimated_cache_write_usd": 1.1396,
3479 "pricing": "catalog"
3480}
3481```
3482
3483<h4 id="premodelswitch-decision-control">
3484 PreModelSwitch の判定制御
3485</h4>
3486
3487`PreModelSwitch` フックは、切り替えをキャンセルしたり、ユーザーに確認を求めたり、そのまま続行させたりできます。終了コード 2 またはトップレベルの `decision: "block"` は切り替えをキャンセルします。
3488
3489より細かく制御するには、[PreToolUse](#pretooluse-decision-control) と同様に、`hookSpecificOutput` オブジェクト内で `permissionDecision` と `permissionDecisionReason` を返します。`PreModelSwitch` は `"allow"`、`"deny"`、`"ask"` を受け付けます。`"defer"`、`updatedInput`、`additionalContext` は受け付けません。次の表で両方のフィールドについて説明します。
3490
3491| フィールド | 説明 |
3492| :- | :- |
3493| `permissionDecision` | `"allow"` は切り替えを続行し、[プロンプトキャッシュがウォーム状態のときに Claude Code が表示する確認](/docs/ja/prompt-caching#switching-models)をスキップします。`"deny"` は切り替えをキャンセルします。`"ask"` はユーザーに確認を求めます |
3494| `permissionDecisionReason` | `"deny"` の場合、切り替えがブロックされた理由としてユーザーに表示されるか、`set_model` リクエストのエラーとして返されます。`"ask"` の場合、確認プロンプトに表示されます。`"allow"` の場合は無視されます |
3495
3496`"ask"` のプロンプトを表示できるのは、対話セッションでの `/model` のみです。`-p` フラグを使用した非対話モード、`/config`、`set_model` リクエストを含むその他すべてのサーフェスでは、Claude Code は `"ask"` を拒否として扱います。
3497
3498次の例では、ユーザーに確認を求め、`context_tokens` のトークン数を示しています。
3499
3500```json theme={null}
3501{
3502 "hookSpecificOutput": {
3503 "hookEventName": "PreModelSwitch",
3504 "permissionDecision": "ask",
3505 "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
3506 }
3507}
3508```
3509
3510複数の PreModelSwitch フックが異なる判定を返した場合、優先順位は `deny` > `ask` > `allow` です。
3511
3512Claude Code は判定にかかわらず、フックが返した `systemMessage` をユーザーに表示します。そのため、コストを報告するフックは `{"systemMessage": "..."}` を返して 0 で終了できます。
3513
3514タイムアウトまでに応答しない PreModelSwitch フックは、切り替えをブロックします。対照的に、[PreToolUse](#timeouts) では、タイムアウトしたコマンドフックはツール呼び出しを続行させます。このイベントのデフォルトのタイムアウトは 30 秒です。`PreModelSwitch` は `command`、`http`、`mcp_tool` フックのみを実行するため、`prompt` と `agent` のデフォルトは適用されません。
3515
35160 または 2 以外のコードで終了し、JSON の判定を出力しないフックはブロックしません。[その他の終了コード](#other-exit-codes)で説明されているとおり、Claude Code はその stderr を表示して切り替えを適用します。
3517
3518<h3 id="postmodelswitch">
3519 PostModelSwitch
3520</h3>
3521
3522セッションのモデルが変更された後に実行されます。特定のモデルに適用される組織全体の指示など、すべての CLAUDE.md を編集することなく、Claude にモデル固有のガイダンスを与えるために使用します。
3523
3524PostModelSwitch には Claude Code v2.1.251 以降が必要です。モデルはすでに変更されているため、ブロックすることはできません。Claude Code は、次のいずれかの変更の後に PostModelSwitch フックを実行します。
3525
3526* ユーザーまたはクライアントが要求した切り替え
3527* セッションのモデルを変更する[モデルの自動フォールバック](/docs/ja/model-config#automatic-model-fallback)
3528* [`opusplan`](/docs/ja/model-config#opusplan-model-setting) などの設定による plan モードへの移行または終了
3529* セッション再開時に Claude Code がモデルを復元したとき
3530
3531[フォールバックモデルチェーン](/docs/ja/model-config#fallback-model-chains)のモデルがターンを処理した場合、PostModelSwitch フックは実行されません。この置き換えは 1 ターンのみ有効で、セッションのモデルは変更されないためです。
3532
3533matcher は [PreModelSwitch](#premodelswitch) と同じルールに従います。Claude Code は、matcher をセッションの切り替え先モデルの正規名と比較します。
3534
3535次の例では、セッションのモデルがいずれかの Opus モデルに変更されるたびにガイダンスを追加します。
3536
3537```json theme={null}
3538{
3539 "hooks": {
3540 "PostModelSwitch": [
3541 {
3542 "matcher": ".*opus.*",
3543 "hooks": [
3544 {
3545 "type": "command",
3546 "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
3547 }
3548 ]
3549 }
3550 ]
3551 }
3552}
3553```
3554
3555フックが機能することを確認するには、別のモデルで実行中のセッションから Opus モデルに切り替え（たとえば Sonnet セッションから `/model opus` を実行）、現在のモデルについてどのようなガイダンスがあるかを Claude に尋ねます。
3556
3557<h4 id="postmodelswitch-input">
3558 PostModelSwitch の入力
3559</h4>
3560
3561PostModelSwitch フックは [PreModelSwitch](#premodelswitch-input) と同じフィールドを受け取ります。ただし、`hook_event_name` は `"PostModelSwitch"` に設定され、`source` には 2 つの値が追加されます。自動フォールバックや Claude Code が独自に行ったその他の変更の場合は `"auto"`、セッション再開時に復元されたモデルの場合は `"resume"` です。
3562
3563`source` が `"auto"` の場合、`requested_model` は `null` です。`source` が `"resume"` の場合は、Claude Code が復元した保存済みのモデル設定です。
3564
3565<h4 id="postmodelswitch-decision-control">
3566 PostModelSwitch の判定制御
3567</h4>
3568
3569Claude Code は、終了コード 0 の場合のフックの[プレーンテキストの stdout](#exit-code-0)、または JSON 出力の `additionalContext` を取得し、切り替え後の次のリクエストとともに Claude に渡します。すべてのフックで使用できる [JSON 出力フィールド](#json-output)に加えて、次のフィールドを返すことができます。
3570
3571| フィールド | 説明 |
3572| :- | :- |
3573| `additionalContext` | 次のリクエストで Claude のコンテキストに追加される文字列。[Claude にコンテキストを追加する](#add-context-for-claude)を参照してください |
3574
3575次のプロンプトを送信してから 5 秒以内にフックが完了しない場合、Claude Code は出力なしでそのリクエストを送信し、代わりにその次のリクエストに出力を添付します。次のリクエストまでにモデルが複数回変更された場合、Claude Code は最後の切り替え先モデルの出力のみを渡します。
2823 3576
2824<h3 id="sessionend">3577<h3 id="sessionend">
2825 SessionEnd3578 SessionEnd
2826</h3>3579</h3>
2827 3580
2828Claude Code セッションが終了するときに実行されます。クリーンアップ タスク、セッション統計のログ、またはセッション状態の保存に便利です。終了理由でフィルタリングするマッチャーをサポートします。3581Claude Code セッションが終了するときに実行されます。クリーンアップタスク、セッション統計のログ記録、セッション状態の保存に役立ちます。終了理由でフィルタリングするための matcher をサポートしています。
2829 3582
2830フック入力の `reason` フィールドはセッションが終了した理由を示します。3583フック入力の `reason` フィールドは、セッションが終了した理由を示します。
2831 3584
2832| 理由 | 説明 |3585| 理由 | 説明 |
2833| :- | :- |3586| :- | :- |
2834| `clear` | `/clear` コマンドでセッションをクリア |3587| `clear` | `/clear` コマンドでセッションがクリアされた |
2835| `resume` | インタラクティブ `/resume` 経由でセッションを切り替え |3588| `resume` | 対話的な `/resume` でセッションが切り替えられた |
2836| `logout` | ユーザーがログアウト |3589| `logout` | ユーザーがログアウトした |
2837| `prompt_input_exit` | プロンプト入力が表示されている間にユーザーが終了 |3590| `prompt_input_exit` | プロンプト入力が表示されている間にユーザーが終了した |
2838| `bypass_permissions_disabled` | バイパス権限モードが無効化 |
2839| `other` | その他の終了理由 |3591| `other` | その他の終了理由 |
3592| `bypass_permissions_disabled` | v2.1.234 で削除されました。Claude Code はこの値を送信しません。`SessionEnd` の matcher から削除してください |
2840 3593
2841<h4 id="sessionend-input">3594<h4 id="sessionend-input">
2842 SessionEnd 入力3595 SessionEnd の入力
2843</h4>3596</h4>
2844 3597
2845[共通入力フィールド](#common-input-fields)に加えて、SessionEnd フックはセッションが終了した理由を示す `reason` フィールドを受け取ります。上記の[理由テーブル](#sessionend)をすべての値について参照してください。3598[共通の入力フィールド](#common-input-fields)に加えて、SessionEnd フックはセッションが終了した理由を示す `reason` フィールドを受け取ります。すべての値については、上記の[理由の表](#sessionend)を参照してください。
2846 3599
2847```json theme={null}3600```json theme={null}
2848{3601{
2854}3607}
2855```3608```
2856 3609
2857SessionEnd フックは決定制御がありません。セッション終了をブロックできませんが、クリーンアップ タスクを実行できます。3610SessionEnd フックには判定の制御がありません。セッションの終了をブロックすることはできませんが、クリーンアップタスクを実行できます。Claude Code は、`systemMessage` などの [JSON 出力フィールド](#json-output)を破棄します。
2858 3611
2859SessionEnd フックのデフォルト タイムアウトは 1.5 秒です。これはセッション終了、`/clear`、およびインタラクティブ `/resume` 経由でのセッション切り替えに適用されます。フックにより多くの時間が必要な場合は、フック設定でフックごとの `timeout` を設定します。全体的な予算は、設定ファイルで設定されたフックごとのタイムアウトの最高値に自動的に引き上げられ、最大 60 秒です。プラグイン提供のフックに設定されたタイムアウトは予算を引き上げません。予算を明示的にオーバーライドするには、`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` 環境変数をミリ秒単位で設定します。3612SessionEnd フックのデフォルトのタイムアウトは 1.5 秒です。これは、終了したとき、`/clear` を実行したとき、または対話的な `/resume` でセッションを切り替えたときに適用されます。フックにより多くの時間を与えるには、次の 2 つの方法があります。
3613
3614* **フックごとの `timeout`**：そのフックの設定で `timeout` を設定します。全体の上限時間は、設定ファイル内のフックごとの `timeout` の最大値に合わせて、最大 60 秒まで自動的に引き上げられます。この方法で上限時間を引き上げても、独自の `timeout` を持たないフックはデフォルトのままです。プラグインが提供するフックに設定されたタイムアウトは、上限時間を引き上げません。
3615* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**：この環境変数をミリ秒単位で設定すると、上限時間を明示的に上書きできます。設定した値は、独自の `timeout` を持たない各フックのタイムアウトにもなります。
3616
3617次の例では、上限時間を 5 秒に設定します。
2860 3618
2861```bash theme={null}3619```bash theme={null}
2862CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3620CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
2863```3621```
2864 3622
3623v2.1.268 より前は、`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` は全体の上限時間のみを引き上げ、独自の `timeout` を持たないフックは引き続き 1.5 秒後にキャンセルされていました。
3624
2865<h3 id="elicitation">3625<h3 id="elicitation">
2866 Elicitation3626 Elicitation
2867</h3>3627</h3>
2868 3628
2869MCP サーバーがタスク中にユーザー入力をリクエストするときに実行されます。デフォルトでは、Claude Code はユーザーが応答するためのインタラクティブ ダイアログを表示します。フックはこのリクエストをインターセプトして、プログラムで応答し、ダイアログを完全にスキップできます。3629MCP サーバーがタスクの途中でユーザー入力を要求したときに実行されます。デフォルトでは、Claude Code はユーザーが応答するための対話ダイアログを表示します。フックはこのリクエストをインターセプトしてプログラムで応答し、ダイアログを完全にスキップできます。
2870 3630
2871マッチャー フィールドは MCP サーバー名に対してマッチします。3631matcher フィールドは MCP サーバー名と照合されます。
2872 3632
2873<h4 id="elicitation-input">3633<h4 id="elicitation-input">
2874 Elicitation 入力3634 Elicitation の入力
2875</h4>3635</h4>
2876 3636
2877[共通入力フィールド](#common-input-fields)に加えて、Elicitation フックは `mcp_server_name`、`message`、およびオプションで `mode`、`url`、`elicitation_id`、`requested_schema` フィールドを受け取ります。3637[共通の入力フィールド](#common-input-fields)に加えて、Elicitation フックは `mcp_server_name`、`message`、およびオプションの `mode`、`url`、`elicitation_id`、`requested_schema` フィールドを受け取ります。
2878 3638
2879フォーム モード elicitation（最も一般的なケース）の場合。3639最も一般的なケースであるフォームモードの elicitation の場合：
2880 3640
2881```json theme={null}3641```json theme={null}
2882{3642{
2883 "session_id": "abc123",3643 "session_id": "abc123",
2884 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3644 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2885 "cwd": "/Users/...",3645 "cwd": "/Users/...",
2886 "permission_mode": "default",
2887 "hook_event_name": "Elicitation",3646 "hook_event_name": "Elicitation",
2888 "mcp_server_name": "my-mcp-server",3647 "mcp_server_name": "my-mcp-server",
2889 "message": "Please provide your credentials",3648 "message": "Please provide your credentials",
2897}3656}
2898```3657```
2899 3658
2900URL モード elicitation（ブラウザベースの認証）の場合。3659ブラウザベースの認証に使用される URL モードの elicitation の場合：
2901 3660
2902```json theme={null}3661```json theme={null}
2903{3662{
2904 "session_id": "abc123",3663 "session_id": "abc123",
2905 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3664 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2906 "cwd": "/Users/...",3665 "cwd": "/Users/...",
2907 "permission_mode": "default",
2908 "hook_event_name": "Elicitation",3666 "hook_event_name": "Elicitation",
2909 "mcp_server_name": "my-mcp-server",3667 "mcp_server_name": "my-mcp-server",
2910 "message": "Please authenticate",3668 "message": "Please authenticate",
2914```3672```
2915 3673
2916<h4 id="elicitation-output">3674<h4 id="elicitation-output">
2917 Elicitation 出力3675 Elicitation の出力
2918</h4>3676</h4>
2919 3677
2920ダイアログを表示せずにプログラムで応答するには、`hookSpecificOutput` を含む JSON オブジェクトを返します。3678ダイアログを表示せずにプログラムで応答するには、`hookSpecificOutput` を含む JSON オブジェクトを返します。
2934| フィールド | 値 | 説明 |3692| フィールド | 値 | 説明 |
2935| :- | :- | :- |3693| :- | :- | :- |
2936| `action` | `accept`、`decline`、`cancel` | リクエストを受け入れるか、拒否するか、キャンセルするか |3694| `action` | `accept`、`decline`、`cancel` | リクエストを受け入れるか、拒否するか、キャンセルするか |
2937| `content` | オブジェクト | 送信するフォーム フィールド値。`action` が `accept` のときのみ使用 |3695| `content` | object | 送信するフォームフィールドの値。`action` が `accept` の場合にのみ使用されます |
3696
3697終了コード 2 は elicitation を拒否します。Claude Code は stderr のメッセージをどこにも表示しません。
2938 3698
2939終了コード 2 は elicitation を拒否し、stderr をユーザーに表示します。3699Claude Code は Elicitation フックの JSON 出力のうち `hookSpecificOutput` に従って動作し、`systemMessage` と `continue` は破棄します。
2940 3700
2941<h3 id="elicitationresult">3701<h3 id="elicitationresult">
2942 ElicitationResult3702 ElicitationResult
2943</h3>3703</h3>
2944 3704
2945ユーザーが MCP elicitation に応答した後に実行されます。フックは応答を観察、変更、またはブロックしてから、MCP サーバーに送り返すことができます。3705ユーザーが MCP の elicitation に応答した後に実行されます。フックは、応答が MCP サーバーに返送される前に、その応答を監視、変更、またはブロックできます。
2946 3706
2947マッチャー フィールドは MCP サーバー名に対してマッチします。3707matcher フィールドは MCP サーバー名と照合されます。
2948 3708
2949<h4 id="elicitationresult-input">3709<h4 id="elicitationresult-input">
2950 ElicitationResult 入力3710 ElicitationResult の入力
2951</h4>3711</h4>
2952 3712
2953[共通入力フィールド](#common-input-fields)に加えて、ElicitationResult フックは `mcp_server_name`、`action`、およびオプションで `mode`、`elicitation_id`、`content` フィールドを受け取ります。3713[共通の入力フィールド](#common-input-fields)に加えて、ElicitationResult フックは `mcp_server_name`、`action`、およびオプションの `mode`、`elicitation_id`、`content` フィールドを受け取ります。
2954 3714
2955```json theme={null}3715```json theme={null}
2956{3716{
2957 "session_id": "abc123",3717 "session_id": "abc123",
2958 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3718 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2959 "cwd": "/Users/...",3719 "cwd": "/Users/...",
2960 "permission_mode": "default",
2961 "hook_event_name": "ElicitationResult",3720 "hook_event_name": "ElicitationResult",
2962 "mcp_server_name": "my-mcp-server",3721 "mcp_server_name": "my-mcp-server",
2963 "action": "accept",3722 "action": "accept",
2968```3727```
2969 3728
2970<h4 id="elicitationresult-output">3729<h4 id="elicitationresult-output">
2971 ElicitationResult 出力3730 ElicitationResult の出力
2972</h4>3731</h4>
2973 3732
2974ユーザーの応答をオーバーライドするには、`hookSpecificOutput` を含む JSON オブジェクトを返します。3733ユーザーの応答を上書きするには、`hookSpecificOutput` を含む JSON オブジェクトを返します。
2975 3734
2976```json theme={null}3735```json theme={null}
2977{3736{
2985 3744
2986| フィールド | 値 | 説明 |3745| フィールド | 値 | 説明 |
2987| :- | :- | :- |3746| :- | :- | :- |
2988| `action` | `accept`、`decline`、`cancel` | ユーザーのアクションをオーバーライド |3747| `action` | `accept`、`decline`、`cancel` | ユーザーのアクションを上書きします |
2989| `content` | オブジェクト | フォーム フィールド値をオーバーライド。`action` が `accept` のときのみ意味がある |3748| `content` | object | フォームフィールドの値を上書きします。`action` が `accept` の場合にのみ意味を持ちます |
2990 3749
2991終了コード 2 はレスポンスをブロックし、有効なアクションを `decline` に変更します。3750終了コード 2 は応答をブロックし、実際のアクションを `decline` に変更します。Claude Code は stderr のメッセージをどこにも表示しません。
3751
3752Claude Code は ElicitationResult フックの JSON 出力のうち `hookSpecificOutput` に従って動作し、`systemMessage` と `continue` は破棄します。
2992 3753
2993<h2 id="prompt-based-hooks">3754<h2 id="prompt-based-hooks">
2994 プロンプト ベースのフック3755 プロンプト ベースのフック
29995 つのフック タイプ（`command`、`http`、`mcp_tool`、`prompt`、`agent`）すべてをサポートするイベント：37605 つのフック タイプ（`command`、`http`、`mcp_tool`、`prompt`、`agent`）すべてをサポートするイベント：
3000 3761
3001* `PermissionDenied`3762* `PermissionDenied`
3002* `PermissionRequest`
3003* `PostToolBatch`3763* `PostToolBatch`
3004* `PostToolUse`3764* `PostToolUse`
3005* `PostToolUseFailure`3765* `PostToolUseFailure`
3012* `UserPromptExpansion`3772* `UserPromptExpansion`
3013* `UserPromptSubmit`3773* `UserPromptSubmit`
3014 3774
3775`PermissionRequest` は `command`、`http`、`mcp_tool`、`prompt` フックをサポートしますが、`agent` フックはサポートしません。このイベントにエージェント フックを設定した場合、Claude Code はそれをスキップし、権限フローは変更されずに進行します。フックから許可または拒否するには、コマンド フックまたは HTTP フックから[決定オブジェクト](#permissionrequest-decision-control)を返します。
3776
3015`command`、`http`、`mcp_tool` フックをサポートするが、`prompt` または `agent` をサポートしないイベント：3777`command`、`http`、`mcp_tool` フックをサポートするが、`prompt` または `agent` をサポートしないイベント：
3016 3778
3017* `ConfigChange`3779* `ConfigChange`
3018* `CwdChanged`3780* `CwdChanged`
3781* `DirectoryAdded`
3019* `Elicitation`3782* `Elicitation`
3020* `ElicitationResult`3783* `ElicitationResult`
3021* `FileChanged`3784* `FileChanged`
3022* `InstructionsLoaded`3785* `InstructionsLoaded`
3786* `MessageDisplay`
3023* `Notification`3787* `Notification`
3024* `PostCompact`3788* `PostCompact`
3789* `PostModelSwitch`
3025* `PreCompact`3790* `PreCompact`
3791* `PreModelSwitch`
3026* `SessionEnd`3792* `SessionEnd`
3027* `StopFailure`3793* `StopFailure`
3028* `SubagentStart`3794* `SubagentStart`
3029* `WorktreeCreate`3795* `WorktreeCreate`
3030* `WorktreeRemove`3796* `WorktreeRemove`
3031 3797
3032`SessionStart` と `Setup` は `command` と `mcp_tool` フックをサポートしています。これらは `http`、`prompt`、`agent` フックをサポートしていません。3798`SessionStart` と `Setup` は `command` と `mcp_tool` フックをサポートしており、それらの `mcp_tool` フックがいつ実行されるかについては [MCP ツール フックのフィールド](#mcp-tool-hook-fields)で説明しています。これらは `http`、`prompt`、`agent` フックをサポートしていません。
3033 3799
3034<h3 id="how-prompt-based-hooks-work">3800<h3 id="how-prompt-based-hooks-work">
3035 プロンプト ベースのフックの仕組み3801 プロンプト ベースのフックの仕組み
3037 3803
3038プロンプト ベースのフックは Bash コマンドを実行する代わりに：3804プロンプト ベースのフックは Bash コマンドを実行する代わりに：
3039 3805
30401. フック入力とプロンプトを Claude モデル（デフォルトは Haiku）に送信38061. フック入力とプロンプトを Claude モデル（デフォルトでは Claude Code が[バックグラウンド機能](/docs/ja/costs#background-token-usage)に使用するモデル）に送信
30412. LLM は決定を含む構造化 JSON で応答38072. LLM は決定を含む構造化 JSON で応答
30423. Claude Code は決定を自動的に処理38083. Claude Code は決定を自動的に処理
3043 3809
3045 プロンプト フック設定3811 プロンプト フック設定
3046</h3>3812</h3>
3047 3813
3048`type` を `"prompt"` に設定し、`command` の代わりに `prompt` 文字列を提供します。`$ARGUMENTS` プレースホルダーを使用して、フックの JSON 入力データをプロンプト テキストに注入します。Claude Code は結合されたプロンプトと入力を高速 Claude モデルに送信し、JSON 決定を返します。3814`type` を `"prompt"` に設定し、`command` の代わりに `prompt` 文字列を提供します。`$ARGUMENTS` プレースホルダーを使用して、フックの JSON 入力データをプロンプト テキストに注入します。
3049 3815
3050この `Stop` フックは、Claude が終了する前にすべてのタスクが完了しているかどうかを評価するよう LLM に求めます：3816この `Stop` フックは、Claude が終了する前にすべてのタスクが完了しているかどうかを評価するよう LLM に求めます：
3051 3817
3070| :- | :- | :- |3836| :- | :- | :- |
3071| `type` | はい | `"prompt"` である必要があります |3837| `type` | はい | `"prompt"` である必要があります |
3072| `prompt` | はい | LLM に送信するプロンプト テキスト。フック入力 JSON のプレースホルダーとして `$ARGUMENTS` を使用します。`$ARGUMENTS` が存在しない場合、入力 JSON がプロンプトに追加されます |3838| `prompt` | はい | LLM に送信するプロンプト テキスト。フック入力 JSON のプレースホルダーとして `$ARGUMENTS` を使用します。`$ARGUMENTS` が存在しない場合、入力 JSON がプロンプトに追加されます |
3073| `model` | いいえ | 評価に使用するモデル。デフォルトは高速モデル |3839| `model` | いいえ | 評価に使用するモデル。デフォルトは Claude Code が[バックグラウンド機能](/docs/ja/costs#background-token-usage)に使用するモデル |
3074| `timeout` | いいえ | タイムアウト（秒単位）。デフォルト：30 |3840| `timeout` | いいえ | タイムアウト（秒単位）。デフォルト：30 |
3075| `continueOnBlock` | いいえ | プロンプトが `ok: false` を返すとき、理由を Claude にフィードバックして、停止する代わりにターンを続行します。デフォルト：`false`。結果の `decision: "block"` に `continue: true` として実装されます。イベント ごとの動作については、[レスポンス スキーマ](#response-schema)を参照してください |3841| `continueOnBlock` | いいえ | 適用されるイベントでは、`true` にすると `ok: false` の理由を Claude にフィードバックし、ターンを終了する代わりに続行します。デフォルト：`false`。イベント ごとの動作については、[レスポンス スキーマ](#response-schema)を参照してください |
3076 3842
3077<h3 id="response-schema">3843<h3 id="response-schema">
3078 レスポンス スキーマ3844 レスポンス スキーマ
3083```json theme={null}3849```json theme={null}
3084{3850{
3085 "ok": true | false,3851 "ok": true | false,
3086 "reason": "Explanation for the decision"3852 "reason": "Explanation for the decision",
3853 "impossible": true | false
3087}3854}
3088```3855```
3089 3856
3090| フィールド | 説明 |3857| フィールド | 説明 |
3091| :- | :- |3858| :- | :- |
3092| `ok` | `true` はアクションを許可、`false` は `decision: "block"` を生成します。以下のイベント ごとの動作を参照してください |3859| `ok` | `true` で許可します。`false` の場合は、以下のイベント ごとの動作を参照してください |
3093| `reason` | `ok` が `false` のときに必須。ブロック理由として使用されます |3860| `reason` | `ok` が `false` のときに必須 |
3861| `impossible` | 省略可能。条件が決して満たされないとモデルが判断した場合に、`ok: false` とともに返します。`Stop` と `SubagentStop` では、Claude Code は理由をフィードバックする代わりにターンを終了させます。エージェント フックとその他のイベントはこれを無視します |
3094 3862
3095`ok: false` で何が起こるかはイベントによって異なります：3863`ok: false` で何が起こるかはイベントによって異なります：
3096 3864
3097* `Stop` と `SubagentStop`：理由は Claude の次の指示としてフィードバックされ、ターンが続行されます3865* `Stop` と `SubagentStop`：理由は Claude の次の指示としてフィードバックされ、ターンが続行されます。ただし、応答で `impossible: true` も設定されている場合は、Claude Code が停止を許可し、ターンが終了します
3098* `PreToolUse`：ツール呼び出しが拒否され、理由は Claude にツール エラーとして返されます。これはコマンド フックの `permissionDecision: "deny"` と同等です3866* `PreToolUse`：ツール呼び出しが拒否されます。デフォルトではターンが終了し、拒否理由は警告行としてチャットに表示されます。代わりに理由をツール エラーとして Claude に返し、Claude が調整して続行できるようにするには、`continueOnBlock: true` を設定します。これはコマンド フックの `permissionDecision: "deny"` と同等です。v2.1.210 より前は、拒否理由はツール エラーとして Claude に返され、ターンは続行されていました
3099* `PostToolUse`：デフォルトではターンが終了し、理由は警告行としてチャットに表示されます。`continueOnBlock: true` を設定して、理由を Claude にフィードバックし、ターンを続行する代わりに使用します3867* `PostToolUse`：デフォルトではターンが終了し、理由は警告行としてチャットに表示されます。`continueOnBlock: true` を設定して、理由を Claude にフィードバックし、ターンを続行する代わりに使用します
3100* `PostToolBatch`、`UserPromptSubmit`、`UserPromptExpansion`：ターンが終了し、理由は警告行として表示されます。これらのイベントは `continue` に関係なく `decision: "block"` でターンを終了します3868* `PostToolBatch`、`UserPromptSubmit`、`UserPromptExpansion`：ターンが終了し、理由は警告行として表示されます。これらのイベントは `continue` に関係なく `decision: "block"` でターンを終了します
3101* `PostToolUseFailure`、`TaskCreated`、`TaskCompleted`：理由は Claude にツール エラーとして返されます。`PreToolUse` と同様です3869* `PostToolUseFailure`、`TaskCreated`：理由は `continueOnBlock` に関係なくツール エラーとして Claude に返され、ターンが続行されます
3870* `TaskCompleted`：ターン中にタスクが完了としてマークされたために発火した場合、理由は `continueOnBlock` に関係なくツール エラーとして Claude に返され、ターンが続行されます。チームメイトが停止したために発火した場合は、`TeammateIdle` と同様に動作し、デフォルトでチームメイトを停止します
3102* `TeammateIdle`：デフォルトではチームメイトが停止し、理由は警告行として表示されます。`continueOnBlock: true` を設定して、理由をチームメイトにフィードバックし、代わりに作業を続行させます3871* `TeammateIdle`：デフォルトではチームメイトが停止し、理由は警告行として表示されます。`continueOnBlock: true` を設定して、理由をチームメイトにフィードバックし、代わりに作業を続行させます
3103* `PermissionRequest`：`ok: false` は効果がありません。フックから承認を拒否するには、[コマンド フック](#command-hook-fields)を使用して `hookSpecificOutput.decision.behavior: "deny"` を返します3872* `PermissionRequest`：`ok: false` は効果がありません。フックから承認を拒否するには、[コマンド フック](#command-hook-fields)を使用して `hookSpecificOutput.decision.behavior: "deny"` を返します
3104* `PermissionDenied`：`ok: false` は効果がありません。拒否は既に発生しているためです。このイベントが読み取る唯一の出力は `hookSpecificOutput.retry` です。プロンプト フックとエージェント フックはこれを設定できません。これらはこのイベントで実行されますが、その出力は破棄されます。`retry` を返すには、[コマンド フック](#command-hook-fields)を使用してください3873* `PermissionDenied`：`ok: false` は効果がありません。拒否は既に発生しているためです。このイベントが読み取る唯一の出力は `hookSpecificOutput.retry` です。プロンプト フックとエージェント フックはこれを設定できません。これらはこのイベントで実行されますが、その出力は破棄されます。`retry` を返すには、[コマンド フック](#command-hook-fields)を使用してください
3109 停止する前に複数の条件をチェック3878 停止する前に複数の条件をチェック
3110</h3>3879</h3>
3111 3880
3112この `Stop` フックは詳細なプロンプトを使用して、Claude が停止することを許可する前に 3 つの条件をチェックします。`SubagentStop` フックは同じ形式を使用して、[サブエージェント](/docs/ja/sub-agents)が停止すべきかどうかを評価します。`"ok"` が `false` の場合、Claude は提供された理由を次の指示として受け取り、作業を続行します：3881この `Stop` フックは詳細なプロンプトを使用して、Claude が停止することを許可する前に 3 つの条件をチェックします。`SubagentStop` フックは同じ形式を使用して、[サブエージェント](/docs/ja/sub-agents)が停止すべきかどうかを評価します。条件がまだ満たされていないためにモデルが `"ok": false` を返した場合、Claude は提供された理由を次の指示として受け取り、作業を続行します：
3113 3882
3114```json theme={null}3883```json theme={null}
3115{3884{
3137 エージェント フックは実験的です。動作と設定は将来のリリースで変更される可能性があります。本番ワークフローの場合は、[コマンド フック](#command-hook-fields)を優先してください。3906 エージェント フックは実験的です。動作と設定は将来のリリースで変更される可能性があります。本番ワークフローの場合は、[コマンド フック](#command-hook-fields)を優先してください。
3138</Warning>3907</Warning>
3139 3908
3140エージェント ベースのフック（`type: "agent"`）はプロンプト ベースのフックのようですが、マルチターン ツール アクセスを備えています。単一の LLM 呼び出しの代わりに、エージェント フックはサブエージェントを生成し、ファイルを読み取り、コードを検索し、コードベースを検査して条件を検証できます。エージェント フックはプロンプト ベースのフックと同じイベントをサポートしています。3909エージェント ベースのフック（`type: "agent"`）はプロンプト ベースのフックのようですが、マルチターン ツール アクセスを備えています。単一の LLM 呼び出しの代わりに、エージェント フックはサブエージェントを生成し、ファイルを読み取り、コードを検索し、コードベースを検査して条件を検証できます。エージェント フックは、`PermissionRequest` を除き、[プロンプト ベースのフック](#prompt-based-hooks)と同じイベントをサポートしています。
3141 3910
3142<h3 id="how-agent-hooks-work">3911<h3 id="how-agent-hooks-work">
3143 エージェント フックの仕組み3912 エージェント フックの仕組み
31481. Claude Code はプロンプトとフックの JSON 入力を持つサブエージェントを生成します39171. Claude Code はプロンプトとフックの JSON 入力を持つサブエージェントを生成します
31492. サブエージェントは Read、Grep、Glob などのツールを使用して調査できます39182. サブエージェントは Read、Grep、Glob などのツールを使用して調査できます
31503. 最大 50 ターン後、サブエージェントは構造化 `{ "ok": true/false }` 決定を返します39193. 最大 50 ターン後、サブエージェントは構造化 `{ "ok": true/false }` 決定を返します
31514. Claude Code はプロンプト フックと同じ方法で決定を処理します39204. Claude Code は `ok` が `true` の場合にアクションを許可します。`ok` が `false` の場合、Claude Code は[レスポンス スキーマ](#response-schema)に記載されているとおり、そのイベントで `continueOnBlock: true` を指定したプロンプト フックと同じ方法でブロックを処理します
3152 3921
3153エージェント フックは、フック入力データのみを評価するのではなく、実際のファイルを検査したりテスト出力を検査したりする必要がある場合に便利です。3922エージェント フックは、フック入力データのみを評価するのではなく、実際のファイルを検査したりテスト出力を検査したりする必要がある場合に便利です。
3154 3923
3156 エージェント フック設定3925 エージェント フック設定
3157</h3>3926</h3>
3158 3927
3159`type` を `"agent"` に設定し、`prompt` 文字列を提供します。設定フィールドは[プロンプト フック](#prompt-hook-configuration)と同じですが、より長いデフォルト タイムアウトです：3928`type` を `"agent"` に設定し、`prompt` 文字列を提供します。フック入力 JSON のプレースホルダーとして `$ARGUMENTS` を使用します。設定フィールドは[プロンプト フック](#prompt-hook-configuration)と同じですが、エージェント フックはデフォルト タイムアウトが 60 秒と長く、`continueOnBlock` フィールドがありません。
3160
3161| フィールド | 必須 | 説明 |
3162| :- | :- | :- |
3163| `type` | はい | `"agent"` である必要があります |
3164| `prompt` | はい | 検証する内容を説明するプロンプト。フック入力 JSON のプレースホルダーとして `$ARGUMENTS` を使用します |
3165| `model` | いいえ | 使用するモデル。デフォルトは高速モデル |
3166| `timeout` | いいえ | タイムアウト（秒単位）。デフォルト：60 |
3167 3929
3168レスポンス スキーマはプロンプト フックと同じです：許可するには `{ "ok": true }` を、ブロックするには `{ "ok": false, "reason": "..." }` を返します。3930レスポンス スキーマは、許可する場合は `{ "ok": true }`、ブロックする場合は `{ "ok": false, "reason": "..." }` です。`ok: false` の場合、Claude Code はエージェント フックを、同じイベントにおける[`continueOnBlock: true` を指定したプロンプト フック](#response-schema)と同じ方法で処理します。エージェント フックには `continueOnBlock` フィールドがなく、プロンプト フックの `impossible` フィールドもサポートしていません。
3169 3931
3170この `Stop` フックは、Claude が終了することを許可する前にすべてのユニット テストが合格することを検証します：3932この `Stop` フックは、Claude が終了することを許可する前にすべてのユニット テストが合格することを検証します：
3171 3933
3191 バックグラウンドでフックを実行3953 バックグラウンドでフックを実行
3192</h2>3954</h2>
3193 3955
3194デフォルトでは、フックは完了するまで Claude の実行をブロックします。デプロイメント、テスト スイート、外部 API 呼び出しなどの長時間実行タスクの場合、`"async": true` を設定してフックをバックグラウンドで実行し、Claude が作業を続行できるようにします。非同期フックはブロックまたは Claude の動作を制御できません。`decision`、`permissionDecision`、`continue` などのレスポンス フィールドは、制御しようとしたアクションがすでに完了しているため、効果がありません。3956デフォルトでは、フックは完了するまで Claude の実行をブロックします。デプロイ、テスト スイート、外部 API 呼び出しなどの長時間実行タスクの場合、`"async": true` を設定してフックをバックグラウンドで実行し、Claude が作業を続行できるようにします。非同期フックはブロックまたは Claude の動作を制御できません。`decision`、`permissionDecision`、`continue` などのレスポンス フィールドは、制御しようとしたアクションがすでに完了しているため、効果がありません。
3195 3957
3196<h3 id="configure-an-async-hook">3958<h3 id="configure-an-async-hook">
3197 非同期フックを設定3959 非同期フックを設定
3199 3961
3200コマンド フックの設定に `"async": true` を追加して、Claude をブロックせずにバックグラウンドで実行します。このフィールドは `type: "command"` フックでのみ利用可能です。3962コマンド フックの設定に `"async": true` を追加して、Claude をブロックせずにバックグラウンドで実行します。このフィールドは `type: "command"` フックでのみ利用可能です。
3201 3963
3202このフックは、すべての `Write` ツール呼び出しの後にテスト スクリプトを実行します。Claude は `run-tests.sh` が最大 120 秒間実行されている間、すぐに作業を続行します。スクリプトが完了すると、その出力は次の会話ターンで配信されます。3964このフックは、すべての `Write` ツール呼び出しの後にテスト スクリプトを実行します。`run-tests.sh` の実行中も、Claude はすぐに作業を続行します。スクリプトが完了すると、その出力は次の会話ターンで配信されます。
3203 3965
3204```json theme={null}3966```json theme={null}
3205{3967{
3211 {3973 {
3212 "type": "command",3974 "type": "command",
3213 "command": "/path/to/run-tests.sh",3975 "command": "/path/to/run-tests.sh",
3214 "async": true,3976 "async": true
3215 "timeout": 120
3216 }3977 }
3217 ]3978 ]
3218 }3979 }
3221}3982}
3222```3983```
3223 3984
3224`timeout` フィールドはバックグラウンド プロセスの最大時間（秒単位）を設定します。指定されない場合、非同期フックは同期フックと同じ 10 分のデフォルトを使用します。3985非同期フックがバックグラウンドで実行され始めると、Claude Code はそのフックに `timeout` を適用しません。`asyncRewake` で実行するフックには、Claude Code は引き続き `timeout` を適用します。
3986
3987Claude Code が非同期フックの結果を配信するのは、セッションの実行中のみです。
3988
3989* `-p` フラグを使用した[非対話モード](/docs/ja/headless)では、Claude Code は終了処理時にまだ実行中の非同期フックをすべて強制終了し、結果 `cancelled` で確定します
3990* フックの処理を `claude -p` セッションより長く存続させる必要がある場合は、フックから完全にデタッチされたプロセスを起動します
3225 3991
3226<h3 id="how-async-hooks-execute">3992<h3 id="how-async-hooks-execute">
3227 非同期フックの実行方法3993 非同期フックの実行方法
3229 3995
3230非同期フックが発火すると、Claude Code はフック プロセスを開始し、完了を待たずにすぐに続行します。フックは同期フックと同じ JSON 入力を stdin 経由で受け取ります。3996非同期フックが発火すると、Claude Code はフック プロセスを開始し、完了を待たずにすぐに続行します。フックは同期フックと同じ JSON 入力を stdin 経由で受け取ります。
3231 3997
3232バックグラウンド プロセスが終了した後、フックが `additionalContext` フィールドを含む JSON レスポンスを生成した場合、そのコンテンツは次の会話ターンで Claude にコンテキストとして配信されます。`systemMessage` フィールドは Claude ではなく、あなたに表示されます。3998バックグラウンド プロセスが終了した後、Claude Code はフックの JSON レスポンスに含まれる `additionalContext` フィールドと `systemMessage` フィールドを次の会話ターンで Claude に配信します。同期フックの `systemMessage` とは異なり、どちらのフィールドもユーザーには表示されません。
3233 3999
3234Claude Code は JSON レスポンスを同期フックと同じ[出力スキーマ](#json-output)に対して検証し、`systemMessage` が文字列でないなど、値の型が間違っているフィールドをドロップします。これは配信する代わりに行われます。`--debug` で実行すると、ドロップされた各フィールドに名前を付けた警告が表示されます。v2.1.202 より前では、非同期フックからの不正な形式の JSON 出力はセッションをクラッシュさせる可能性があり、セッションが再開されるたびにクラッシュが再発生していました。4000Claude Code は JSON レスポンスを同期フックと同じ[出力スキーマ](#json-output)に対して検証し、`systemMessage` が文字列でないなど、値の型が間違っているフィールドをドロップします。これは配信する代わりに行われます。`--debug` で実行すると、ドロップされた各フィールドに名前を付けた警告が表示されます。v2.1.202 より前では、非同期フックからの不正な形式の JSON 出力はセッションをクラッシュさせる可能性があり、セッションが再開されるたびにクラッシュが再発生していました。
3235 4001
3279 "type": "command",4045 "type": "command",
3280 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",4046 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
3281 "args": [],4047 "args": [],
3282 "async": true,4048 "async": true
3283 "timeout": 300
3284 }4049 }
3285 ]4050 ]
3286 }4051 }
3295 4060
3296非同期フックは同期フックと比べていくつかの制約があります。4061非同期フックは同期フックと比べていくつかの制約があります。
3297 4062
3298* `async` をサポートするのは `type: "command"` フックのみです。プロンプト ベースのフックは非同期で実行できません。
3299* 非同期フックはツール呼び出しをブロックまたは決定を返すことができません。フックが完了するまでに、トリガーするアクションはすでに進行しています。
3300* フック出力は次の会話ターンで配信されます。セッションがアイドル状態の場合、レスポンスは次のユーザー操作まで待機します。例外: `asyncRewake` フックが終了コード 2 で終了すると、セッションがアイドル状態でも Claude を直ちに起動します。4063* フック出力は次の会話ターンで配信されます。セッションがアイドル状態の場合、レスポンスは次のユーザー操作まで待機します。例外: `asyncRewake` フックが終了コード 2 で終了すると、セッションがアイドル状態でも Claude を直ちに起動します。
3301* 各実行は個別のバックグラウンド プロセスを作成します。同じ非同期フックの複数の発火全体で重複排除はありません。4064* 各実行は個別のバックグラウンド プロセスを作成します。同じ非同期フックの複数の発火全体で重複排除はありません。
3302 4065
3308 免責事項4071 免責事項
3309</h3>4072</h3>
3310 4073
3311コマンド フックはシステム ユーザーの完全な権限で実行されます。
3312
3313<Warning>4074<Warning>
3314 コマンド フックはユーザー アカウントの完全な権限でシェル コマンドを実行します。ユーザー アカウントがアクセスできるファイルを変更、削除、またはアクセスできます。フック コマンドを設定に追加する前に、すべてのフック コマンドを確認してテストしてください。4075 コマンド フックはユーザー アカウントの完全な権限でシェル コマンドを実行します。ユーザー アカウントがアクセスできるファイルを変更、削除、またはアクセスできます。フック コマンドを設定に追加する前に、すべてのフック コマンドを確認してテストしてください。
3315</Warning>4076</Warning>
3316 4077
4078<h3 id="workspace-trust">
4079 ワークスペースの信頼
4080</h3>
4081
4082Claude Code は、設定ファイルのフックを実行する前にワークスペースの信頼を確認します。何が信頼済みとみなされるかは、セッションの種類によって異なります。
4083
4084* **インタラクティブ セッション**: ユーザーがそのフォルダー、またはそのフォルダーにまで信頼が及ぶ親ディレクトリについて[ワークスペースの信頼ダイアログ](/docs/ja/permissions#project-allow-rules-and-workspace-trust)を承認するまで、Claude Code はユーザー自身の `~/.claude/settings.json` を含むすべての設定ファイルのフックを保留します
4085* **`-p` または SDK セッション**: Claude Code はダイアログを表示せず、フォルダーを信頼済みとして扱います。そのため、リポジトリの `.claude/settings.json` にコミットされたフックは、一度も信頼したことのないフォルダーでも実行されます
4086
4087自分が作成していないリポジトリに対して `claude -p` をスクリプトで実行する前に、そのリポジトリの `.claude/` 設定ファイルを確認するか、[`--bare`](/docs/ja/headless#start-faster-with-bare-mode) で開始するか、`--settings '{"disableAllHooks": true}'` を使用して[その実行ではフックをオフにして](#disable-or-remove-hooks)ください。プロジェクト サブエージェントのフロントマター フックには、設定ファイルのフックよりも厳しいルールが適用されます。[フォルダーを信頼する前に実行されるもの](/docs/ja/permissions#what-runs-before-you-trust-a-folder)では、リポジトリのコンテンツの種類ごとにセッションの種類別の動作を示しています。
4088
3317<h3 id="security-best-practices">4089<h3 id="security-best-practices">
3318 セキュリティ ベストプラクティス4090 セキュリティ ベストプラクティス
3319</h3>4091</h3>
3330 Windows PowerShell ツール4102 Windows PowerShell ツール
3331</h2>4103</h2>
3332 4104
3333Windows では、コマンド フックで `"shell": "powershell"` を設定することで、個別のフックを PowerShell で実行できます。フックは PowerShell を直接生成するため、`CLAUDE_CODE_USE_POWERSHELL_TOOL` が設定されているかどうかに関係なく機能します。Claude Code は `pwsh.exe`（PowerShell 7 以降の実行可能ファイル）を自動検出し、Windows PowerShell 5.1 の `powershell.exe` にフォールバックします。4105Windows では、コマンド フックで `"shell": "powershell"` を設定することで、個別のフックを PowerShell で実行できます。Claude Code は `pwsh.exe`（PowerShell 7 以降の実行可能ファイル）を自動検出し、Windows PowerShell 5.1 の `powershell.exe` にフォールバックします。
3334 4106
3335```json theme={null}4107```json theme={null}
3336{4108{
3355 4127
3356v2.1.198 より前では、この書き換えはプラグイン フックにのみ適用されていました。以前のバージョンでは、`settings.json` フックは `$env:` 形式または [exec 形式](#exec-form-and-shell-form) が必要です。exec 形式では、フックが定義されている場所に関係なく、各 `args` 要素で `${CLAUDE_PROJECT_DIR}` が置換されます。4128v2.1.198 より前では、この書き換えはプラグイン フックにのみ適用されていました。以前のバージョンでは、`settings.json` フックは `$env:` 形式または [exec 形式](#exec-form-and-shell-form) が必要です。exec 形式では、フックが定義されている場所に関係なく、各 `args` 要素で `${CLAUDE_PROJECT_DIR}` が置換されます。
3357 4129
3358PowerShell フックで裸の `$CLAUDE_PROJECT_DIR` スペルを記述しないでください。PowerShell はそれを未定義のローカル変数として解析し、`$null` に解決します。これにより、スクリプト パスがプロジェクト ルート プレフィックスなしで残されます。Claude Code はその形式を書き換えません。代わりに、[デバッグ ログ](#debug-hooks) に警告をログします。4130PowerShell フックで裸の `$CLAUDE_PROJECT_DIR` スペルを記述しないでください。PowerShell はそれを未定義のローカル変数として解析し、`$null` に解決します。これにより、スクリプト パスがプロジェクト ルート プレフィックスなしで残されます。Claude Code はその形式を書き換えません。代わりに、[デバッグ ログ](#debug-hooks) に警告を記録します。
3359 4131
3360以下の例は、`$env:` 形式でプロジェクト スクリプトを実行する `settings.json` フックを示しています。これはすべてのバージョンで機能します。4132以下の例は、`$env:` 形式でプロジェクト スクリプトを実行する `settings.json` フックを示しています。これはすべてのバージョンで機能します。
3361 4133
3371 フックをデバッグ4143 フックをデバッグ
3372</h2>4144</h2>
3373 4145
3374フック実行の詳細、マッチしたフック、終了コード、完全な stdout と stderr はデバッグ ログ ファイルに書き込まれます。`claude --debug-file <path>` で既知の場所にログを書き込むか、`claude --debug` を実行してログを `~/.claude/debug/<session-id>.txt` で読み取ります。`--debug` フラグはターミナルに出力しません。4146フック実行の詳細はデバッグ ログ ファイルに書き込まれます。`claude --debug-file <path>` で既知の場所にログを書き込むか、`claude --debug` を実行してログを `~/.claude/debug/<session-id>.txt` で読み取ります。`--debug` フラグはターミナルに出力しません。
4147
4148たとえば、`Write` に対する `PostToolUse` フックで、コマンドが `hook-ran` を出力する場合、次のようなエントリが生成されます。
3375 4149
3376```text theme={null}4150```text theme={null}
3377[DEBUG] Executing hooks for PostToolUse:Write41512026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
3378[DEBUG] Found 1 hook commands to execute41522026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"
3379[DEBUG] Executing hook command: <Your command> with timeout 600000ms
3380[DEBUG] Hook command completed with status 0: <Your stdout>
3381```4153```
3382 4154
3383より詳細なフック マッチング詳細については、`CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` を設定して、フック マッチャー数とクエリ マッチングなどの追加ログ行を確認します。4155より詳細なフック マッチング詳細については、`CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` を設定して、フック matcher 数とクエリ マッチングなどの追加ログ行を確認します。
3384 4156
3385フックが発火しない、Stop フックが実行をブロックし続ける、または設定エラーなどの一般的な問題のトラブルシューティングについては、ガイドの[制限事項とトラブルシューティング](/docs/ja/hooks-guide#limitations-and-troubleshooting)を参照してください。`/context`、`/doctor`、および設定の優先順位をカバーするより広範な診断チュートリアルについては、[設定をデバッグ](/docs/ja/debug-your-config)を参照してください。4157フックが発火しない、Stop フックが実行をブロックし続ける、または設定エラーなどの一般的な問題のトラブルシューティングについては、ガイドの[制限事項とトラブルシューティング](/docs/ja/hooks-guide#limitations-and-troubleshooting)を参照してください。`/context`、`/doctor`、および設定の優先順位をカバーするより広範な診断チュートリアルについては、[設定をデバッグ](/docs/ja/debug-your-config)を参照してください。
