-p フラグを使用した非対話モードでは、Claude Code は、Agent SDK の canUseTool コールバックなど、プロンプトを受け取る権限ホストが実行にある場合にのみ、AskUserQuestion と ExitPlanMode を提供します。これらのツールにはユーザーの操作が必要です。permissionDecision: "allow" を updatedInput とともに返すと、その要件を満たせます。フックは stdin からツールの入力を読み取り、独自の UI を通じて回答を収集し、それを updatedInput で返すことで、ツールはプロンプトを表示せずに実行されます。これらのツールでは "allow" だけを返しても十分ではありません。AskUserQuestion の場合は、元の questions 配列をそのまま返し、各質問のテキストを選択された回答に対応付ける answers オブジェクトを追加します。

v2.1.199 以降、サーバーが _meta["anthropic/requiresUserInteraction"] でマークした MCP ツールはより厳格です。Claude Code はツールが必要とする操作をフックが収集したことを確認できないため、updatedInput の有無にかかわらず、フックは "allow" でその承認プロンプトをスキップできません。

ツール呼び出しを後で実行するために延期する

"defer" は、Agent SDK アプリや Claude Code 上に構築したカスタム UI など、claude -p をサブプロセスとして実行してその JSON 出力を読み取る統合向けです。呼び出し元のプロセスは、ツール呼び出しの時点で Claude を一時停止し、独自のインターフェースで入力を収集して、中断したところから再開できます。Claude Code がこの値を尊重するのは、-p フラグを使用した非対話モードの場合のみです。対話セッションでは警告をログに記録し、フックの結果を無視します。

AskUserQuestion ツールが典型的なケースです。Claude はユーザーに何かを質問したいものの、回答するためのターミナルがありません。-p の実行で AskUserQuestion が提供されるのは、--permission-prompt-tool で渡す MCP ツールなどの権限ホストがある場合のみなので、権限ホストを指定して実行を開始してください。往復の流れは次のとおりです：

1. Claude が AskUserQuestion を呼び出します。PreToolUse フックが発火します。
2. フックが permissionDecision: "defer" を返します。ツールは実行されません。プロセスは stop_reason: "tool_deferred" で終了し、保留中のツール呼び出しはトランスクリプトに保存されます。
3. 呼び出し元のプロセスは SDK の結果から deferred_tool_use を読み取り、独自の UI に質問を表示して回答を待ちます。
4. 呼び出し元のプロセスは、同じ権限ホストを指定して claude -p --resume <session-id> を実行します。同じツール呼び出しによって再び PreToolUse が発火します。
5. フックは updatedInput に回答を含めて permissionDecision: "allow" を返します。ツールが実行され、Claude は処理を続行します。

deferred_tool_use フィールドには、ツールの id、name、input が含まれます。input は Claude がツール呼び出しのために生成したパラメーターで、実行前に取得されたものです：

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

タイムアウトや再試行の制限はありません。セッションは再開するまでディスク上に残りますが、cleanupPeriodDays による保持期間のクリーンアップの対象となります。このクリーンアップは、保持期間のクリーンアップのルールに従い、デフォルトで 30 日後にセッションファイルを削除します。再開時に回答の準備ができていない場合、フックは再び "defer" を返すことができ、プロセスは同じように終了します。呼び出し元のプロセスは、最終的にフックから "allow" または "deny" を返すことで、ループを抜けるタイミングを制御します。

"defer" は、Claude がそのターンで単一のツール呼び出しを行う場合にのみ機能します。Claude が複数のツール呼び出しを一度に行う場合、"defer" は警告とともに無視され、ツールは通常の権限フローで処理されます。この制約があるのは、再開時には 1 つのツールしか再実行できないためです。バッチの中の 1 つの呼び出しだけを、他の呼び出しを未解決のまま残さずに延期する方法はありません。

再開時に延期されたツールが利用できなくなっている場合、プロセスはフックが発火する前に stop_reason: "tool_deferred_unavailable" と is_error: true で終了します。これは、ツールを提供していた MCP サーバーが再開したセッションで接続されていない場合に発生します。deferred_tool_use ペイロードは引き続き含まれるため、どのツールが見つからなくなったかを特定できます。

PermissionRequest

Claude Code がツールの使用についてユーザーに権限を求めようとするときに実行されます。非対話モードのバックグラウンドのサブエージェントなど、プロンプトを表示できないセッションでも、Claude Code はこれらのフックを実行し、どのフックも決定を返さなければツール呼び出しを拒否します。 ユーザーに代わって許可または拒否するには、PermissionRequest の決定制御を使用します。

Claude がツールの使用について権限を求めた瞬間にシグナルが必要な場合は、このイベントを使用してください。Claude Code は、permission_prompt タイプの Notification フックを、プロンプトが約 6 秒待機した後にのみ実行します。

Claude Code は、サンドボックス化されたコマンドのネットワークリクエストについては PermissionRequest フックを実行しません。そのプロンプトのシグナルを得るには、permission_prompt 通知タイプを使用してください。

PreToolUse と同じ値で、ツール名で照合します。

PermissionRequest の入力

PermissionRequest フックは、PreToolUse フックと同様に tool_name と tool_input フィールドを受け取りますが、tool_use_id は含まれません。MCP ツールの場合は、mcp_server オブジェクトも受け取ります。任意の permission_suggestions 配列には、許可ルールの追加や権限モードの変更など、Claude Code がこのリクエストに対して提案する権限の更新が含まれます。

permission_suggestions 配列は、表示されるオプションの正確なリストではありません。各権限ダイアログが独自にオプションを構築するためです。ファイル編集のダイアログなど、一部のダイアログはこの配列をまったく読み取らず、リクエスト自体からオプションを導き出します。配列を読み取るダイアログでも、提案が配列に残っているオプションを表示しないことがあります。たとえば、allowManagedPermissionRulesOnly がルールを保存するオプションを非表示にする場合です。また、Yes, and switch to auto mode のように、提案エントリのないオプションを提供することもあります。このオプションは、権限の更新を通じてではなく、権限モードを直接変更します。

PreToolUse フックは、権限が必要かどうかにかかわらず、すべてのツール呼び出しの前に実行されます。PermissionRequest フックは、Claude Code がユーザーに権限を求めようとするとき、またはプロンプトを表示できない呼び出しを本来なら自動的に拒否するときにのみ実行されます。どちらのイベントも EndConversation では発火しません。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

PermissionRequest の決定制御

PermissionRequest フックは権限リクエストを許可または拒否できます。すべてのフックで利用できる JSON 出力フィールドに加えて、フックスクリプトは次のイベント固有のフィールドを持つ decision オブジェクトを返すことができます：

decision オブジェクトなしで終了コード 2 で終了するフックは権限フローを変更せず、その stderr は破棄されます。リクエストを許可または拒否できるのは decision オブジェクトのみです。

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

権限更新エントリ

updatedPermissions 出力フィールドと permission_suggestions 入力フィールドは、どちらも同じエントリオブジェクトの配列を使用します。各エントリには、他のフィールドを決定する type と、変更の書き込み先を制御する destination があります。

各エントリの destination フィールドによって、変更をメモリ内にとどめるか設定ファイルに永続化するかが決まります。

フックは、受け取った permission_suggestions のいずれかを、自身の updatedPermissions 出力としてそのまま返すことができます。

PostToolUse

ツールが正常に完了した直後に実行されます。

ツール名でマッチします。値は PreToolUse と同じです。

ツール名が適切なフィルターにならない場合は、より広くマッチさせます。

• 任意のツールが正常に完了した後にフックを実行するには、matcher を省略するか "*" に設定します。その後、フック自身で何が変更されたかを調べることができます。たとえば git status --porcelain を実行すると、git diff では見落とされる未追跡ファイルも一覧表示されます。失敗したツール呼び出しについては、同じフックを PostToolUseFailure にも追加してください。
• 何が書き込んだかにかかわらず、特定のファイルがディスク上で変更されたときにフックを実行するには、FileChanged を使用します。Bash コマンドや Claude Code 外部のプロセスが同じファイルを書き換えた場合、Claude Code は Edit|Write にマッチする PostToolUse フックを実行しません。

PostToolUse の入力

PostToolUse フックは、ツールがすでに正常に実行された後に発火します。入力には、ツールに送信された引数である tool_input と、ツールが返した結果である tool_response の両方が含まれます。どちらも正確なスキーマはツールによって異なります。ファイル系ツールの tool_input のパスは、PreToolUse と同じ形式で渡されます。つまり、常に絶対パスで、プラットフォームネイティブの区切り文字が使われるため、Windows ではバックスラッシュになります。MCP ツールの場合、入力には mcp_server オブジェクトも含まれます。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

PostToolUse の決定制御

PostToolUse フックは、ツール実行後に Claude にフィードバックを提供できます。すべてのフックで利用可能な JSON 出力フィールドに加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。

以下の例は、Bash 呼び出しの出力を置き換えます。置き換える値は Bash ツールの出力の形状と一致しています。

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

auto モードの分類器向けに結果に注釈を付ける

classifierContext を返すと、ツール呼び出しの結果に関する短いメモを Claude ではなく auto モードの分類器に送信できます。分類器はツールの結果そのものを受け取ることはないため、分類器が後続のアクションを審査する前に、呼び出しが何を返したかについて伝えるには、このフィールドを使用するのが公式にサポートされた方法です。このフィールドには Claude Code v2.1.236 以降が必要です。

以下の例は、クエリの出力がどこから来たかを分類器に伝えます。

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

分類器がメモをどの程度重視するかは、フックをどこで設定したかによって異なります。

• Claude Code で設定されたフック: 設定ファイル、プラグイン、スキル、エージェントのフロントマターからのフックの場合、分類器はメモを未検証のアプリケーション提供コンテキストとして扱います。メモがユーザーの意図を確定させることはなく、ユーザーが何かを承認または要求したとメモが主張している場合、分類器はその主張を会話内のユーザー自身のメッセージと照合します
• インプロセスの Agent SDK コールバック: Claude Code を組み込んだアプリケーションがフックを TypeScript SDK コールバックとして登録し、ライブセッション中にメモを返す場合、分類器はメモで中継されたユーザーの発言をユーザーの意図として考慮することがあります。そのような発言は、ユーザーが送信したメッセージであれば分類器が受け入れる同意要件を満たすことができますが、ユーザー自身のメッセージでも解除できないブロックを解除することはありません。セッションが再開された後は、Claude Code は復元されたメモを未検証のコンテキストとして扱います。両方のグループのフックが同じ呼び出しに注釈を付けた場合、分類器は結合されたメモを未検証として扱います

Claude Code はメモを配信する際に以下の制限を適用します。

• 長さ: Claude Code は 1 回のツール呼び出しに対するメモを 2,000 文字に制限し、残りを切り捨てます。この上限は、その呼び出しに応答するすべてのフックで共有されます
• 同期応答のみ: バックグラウンドで実行されるフックの応答内のこのフィールドは無視されます。その応答は Claude Code がツールの結果を記録した後に届くためです
• 分類器が記録しない呼び出し: 分類器のトランスクリプトには、ファイルの読み取りや検索などの読み取り専用の参照は含まれません。Claude Code はそれらの呼び出しに付けられたメモを破棄します
• 書き換えとの相互作用: updatedToolOutput で置き換える出力についてメモで説明する場合は、同じフックの応答で両方のフィールドを返してください。その書き換えが拒否された場合や、別のフックの書き換えで置き換えられた場合、Claude Code はメモを破棄します。書き換えなしで返したメモは、別のフックが出力を書き換えた場合でも Claude Code が配信します

PostToolUseFailure

実行を開始したツールが失敗したとき、つまりツールがエラーをスローしたとき、または MCP ツールがエラー結果を返したときに実行されます。失敗をログに記録したり、アラートを送信したり、Claude に修正のためのフィードバックを提供したりするために使用します。

ツール名でマッチします。値は PreToolUse と同じです。

PostToolUseFailure の入力

PostToolUseFailure フックは、PostToolUse と同じ tool_name および tool_input フィールドに加えて、エラー情報をトップレベルのフィールドとして受け取ります。MCP ツールの場合は、mcp_server オブジェクトも受け取ります。たとえば、npm test コマンドが失敗した場合は次のように渡されます。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

error 文字列は通常、失敗したツールの結果として Claude が受け取るテキストと同じです。その形式はツールや失敗の種類によって異なります。フックの判定には tool_name、is_interrupt、および先頭行の Exit code N を使用し、文字列の残りの部分は安定した形式ではなく表示用テキストとして扱ってください。

• Bash と PowerShell では、実行されて終了したコマンドは、先頭行が Exit code N となり、その後にコマンドが出力した内容が stdout と stderr の混在した 1 つのブロックとして続きます
• Claude Code がシェルプロセス自体を起動できなかった場合、ペイロードには終了コードの行がない、失敗メッセージのみが含まれることもあります
• Claude Code は長い文字列の中間部分を ... [N characters truncated] ... マーカーで切り詰めるほか、Command timed out after 2m 0s などの独自の行を挿入することがあります

PostToolUseFailure の決定制御

PostToolUseFailure フックは、ツールの失敗後に Claude にコンテキストを提供できます。すべてのフックで利用可能な JSON 出力フィールドに加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

PostToolBatch

バッチ内のすべてのツール呼び出しが解決された後、Claude Code がモデルに次のリクエストを送信する前に 1 回実行されます。PostToolUse はツールごとに 1 回発火するため、Claude が並列のツール呼び出しを行うと同時に発火します。PostToolBatch はバッチ全体に対して正確に 1 回だけ発火するため、単一のツールではなく実行されたツールの組み合わせに依存するコンテキストを注入するのに適しています。このイベントには matcher はありません。

PostToolBatch の入力

共通の入力フィールドに加えて、PostToolBatch フックは、バッチ内のすべてのツール呼び出しを記述する配列である tool_calls を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/accounts.py"},
      "tool_use_id": "toolu_01...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    }
  ]
}

tool_response には、モデルが対応する tool_result ブロックで受け取るのと同じ内容が含まれます。値は、ツールが出力したとおりのシリアライズされた文字列またはコンテンツブロックの配列です。Read の場合、これは生のファイル内容ではなく、行番号が先頭に付いたテキストを意味します。応答は大きくなる可能性があるため、必要なフィールドのみを解析してください。

PostToolBatch の決定制御

PostToolBatch フックは、Claude にコンテキストを注入できます。すべてのフックで利用可能な JSON 出力フィールドに加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
  }
}

decision: "block" または continue: false を返すと、次のモデル呼び出しの前にエージェント型ループが停止します。ブロックメッセージは、JSON の reason または stopReason、あるいは終了コード 2 の場合は stderr から取得されます。このメッセージはトランスクリプトに警告として表示され、会話内に残るため、会話が続行されると Claude にも表示されます。

PermissionDenied

auto モードがツール呼び出しを拒否したときに実行されます。これには、auto モードとは別の安全性チェックが分類器自身のリクエストを拒否したため、または分類器の応答を解析できなかったために、分類器の判定なしで拒否された場合も含まれます。このフックは auto モードでのみ発火します。権限ダイアログを手動で拒否した場合、PreToolUse フックが呼び出しをブロックした場合、deny ルールがマッチした場合には実行されません。拒否をログに記録したり、設定を調整したり、ツール呼び出しを再試行してよいことをモデルに伝えたりするために使用します。

ツール名でマッチします。値は PreToolUse と同じです。

PermissionDenied の入力

共通の入力フィールドに加えて、PermissionDenied フックは tool_name、tool_input、tool_use_id、reason を受け取ります。MCP ツールの場合は、mcp_server オブジェクトも受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build",
    "description": "Clean build directory"
  },
  "tool_use_id": "toolu_01ABC123...",
  "reason": "[Irreversible Local Destruction]"
}

PermissionDenied の決定制御

PermissionDenied フックは、拒否されたツール呼び出しを再試行してよいことをモデルに伝えることができます。hookSpecificOutput.retry を true に設定した JSON オブジェクトを返します。

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

retry が true の場合、Claude Code はツール呼び出しを再試行してよいことをモデルに伝えるメッセージを会話に追加します。Claude Code が拒否自体を取り消すことはありません。フックが JSON を返さない場合、または retry: false を返した場合は、拒否がそのまま維持され、モデルは元の拒否メッセージを受け取ります。

分類器がアクションに対して判定を下さなかった場合、つまり分類器の応答を解析できなかった場合や、auto モードとは別の安全性チェックが分類器自身のリクエストを拒否した場合、Claude Code は retry: true を無視します。そのような拒否については、後で再試行するか次に進むかを、Claude Code がすでに拒否メッセージでモデルに伝えています。

Notification

Claude Code が通知を送信するときに実行されます。通知タイプでマッチします。すべての通知タイプでフックを実行するには、matcher を省略します。

デスクトップ通知をオフにしていても、これらのフックイベントは受け取ります。notifications_disabled を含む preferredNotifChannel 設定が変更するのは通知方法のみであり、フックが実行されるかどうかには影響しません。

quota_auto_resume_fired、quota_auto_resume_stale、quota_auto_resume_disabled タイプには Claude Code v2.1.234 以降が必要です。

ターミナルセッションで、サンドボックス化されたコマンドのネットワークリクエストに対する permission_prompt には Claude Code v2.1.246 以降が必要です。

チームメイトのターミナル設定に関する質問に対する agent_needs_input には Claude Code v2.1.248 以降が必要です。

Claude Code が権限リクエストを Agent SDK の canUseTool コールバックに送信するセッションでは、permission_prompt のタイミングが異なります。Claude Desktop や VS Code 拡張機能はこの方法で Claude Code をホストしています。

• permission_prompt は、Claude が権限を求めてから約 6 秒後に発火します。ユーザーが入力していても延期されません。
• ユーザーまたは PermissionRequest フックがそれより早く応答した場合、Claude Code は permission_prompt を実行しません。
• これらのセッションで permission_prompt をオフにするには、CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS を 1 に設定します。

v2.1.233 より前は、これらのセッションで permission_prompt は発火しませんでした。

通知タイプに応じて異なるハンドラーを実行するには、個別の matcher を使用します。以下の設定では、Claude が権限の承認を必要とするときに権限専用のアラートスクリプトを起動し、Claude がアイドル状態になったときには別の通知を起動します。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Notification の入力

共通の入力フィールドに加えて、Notification フックは、通知テキストを含む message、省略可能な title、どのタイプが発火したかを示す notification_type を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Notification フックは通知をブロックしたり変更したりすることはできません。Claude Code はフックの systemMessage および continue フィールドを破棄しますが、terminalSequence は引き続き出力します。デスクトップ通知の例はこれを利用しています。Notification フックは、通知を外部サービスに転送するなどの副作用を目的としています。

SubagentStart

Claude が Agent ツールでサブエージェントを起動したとき、Claude がサブエージェントを再開したとき、およびインプロセスのエージェントチームのチームメイトが新しいメッセージを処理するたびに実行されます。エージェントタイプ名でフィルタリングするための matcher をサポートしています。組み込みエージェントの場合、これは general-purpose、Explore、Plan などのエージェント名です。カスタムサブエージェントの場合は、ファイル名ではなく、エージェントのフロントマターの name フィールドです。

プラグインで提供されるサブエージェントの場合、エージェントタイプは単なるフロントマターの名前ではなく、my-plugin:reviewer のようなプラグインスコープの識別子になります。コロンが含まれるため、プラグインスコープの名前は正規表現として処理されます。完全一致させるには、^my-plugin:reviewer$ のように matcher を ^ と $ で固定してください。

SubagentStart の入力

共通の入力フィールドに加えて、SubagentStart フックは、サブエージェントの一意の識別子を含む agent_id と、matcher のフィルタリング対象となるエージェント名を含む agent_type を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

SubagentStart フックはサブエージェントの作成をブロックできませんが、サブエージェントにコンテキストを注入することはできます。すべてのフックで利用可能な JSON 出力フィールドに加えて、以下を返すことができます。

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

同じサブエージェントに対してフックが再度実行された場合、Claude Code は、サブエージェントのコンテキストに以前の実行時のコピーがまだ含まれていない場合にのみ、返されたコンテキストを注入します。起動時に注入されたコピーはそのまま残るため、サブエージェントのプロンプトキャッシュは維持されます。自動圧縮によってそのコピーが破棄された後は、Claude Code は次の実行時のコンテキストを再度注入します。

SubagentStop

Claude Code のサブエージェントが応答を終えたときに実行されます。エージェントタイプでマッチします。値は SubagentStart と同じです。

SubagentStop の入力

共通の入力フィールドに加えて、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 フィールドにはサブエージェントの最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにアクセスできます。

すべての SubagentStop イベントが、Claude が起動したサブエージェントから発生するわけではありません。Claude Code は、プロンプトの提案や /btw のサイドクエスチョンなど、独自の機能の一部で内部エージェントも実行しており、それらが終了したときにも SubagentStop が発火します。それらのイベントの場合、agent_type はセッション自体が実行されているエージェント名（--agent や agent 設定で設定されたものなど）になり、セッションがエージェントなしで実行されている場合は空文字列になります。

エージェントタイプを指定した matcher は、空の agent_type にはマッチしません。matcher が省略されている、"" または "*" である、あるいは空文字列にマッチする正規表現であるフックは、agent_type が空のイベントでも実行されます。

Claude Code v2.1.271 以降では、SubagentHandback ツールを使用して実行されるサブエージェントは、停止する前にそのツールを通じてレポートを配信します。その場合、last_assistant_message フィールドにはサブエージェントの締めくくりのテキスト（存在する場合）が含まれますが、これは配信されたレポートではありません。レポートはその呼び出しの message 入力であり、SubagentHandback にマッチする PreToolUse または PostToolUse フックは、これを tool_input.message として受け取ります。

SubagentStop フックは、Stop の入力で説明されている background_tasks および session_crons 配列も受け取ります。どちらの配列も、サブエージェントではなく親セッションを対象としています。

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

SubagentStop フックは Stop フックと同じ決定制御形式を使用します。これには、サブエージェントの実行を継続させるエラーではないフィードバックとして、hookEventName を "SubagentStop" に設定した hookSpecificOutput.additionalContext も含まれます。reason とともに decision: "block" を返すと、サブエージェントの実行が継続され、reason が次の指示としてサブエージェントに配信されます。終了コード 2 で終了してブロックするフックも、同様に stderr メッセージを配信します。サブエージェントが戻った後に親セッションにコンテキストを注入するには、代わりに Agent ツールに対する PostToolUse フックを使用してください。

TaskCreated

TaskCreate ツールによってタスクが作成されるときに実行されます。命名規則を適用したり、タスクの説明を必須にしたり、特定のタスクの作成を阻止したりするために使用します。Task ツールがないセッションでは、このイベントは発火しません。

TaskCreated フックは matcher をサポートしておらず、すべての発生時に発火します。

TaskCreated の入力

共通の入力フィールドに加えて、TaskCreated フックは task_id、task_subject、および省略可能な task_description、teammate_name、team_name を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCreated の決定制御

TaskCreated フックは、2 つの方法で作成をブロックできます。いずれの場合も、Claude Code はタスクを削除し、メッセージをツールのエラーとして Claude に返します。このイベントからの continue: false は Claude Code によって無視され、Claude は作業を続けます。

• 終了コード 2: Claude Code は stderr のテキストをメッセージとして返します。
• JSON {"decision": "block", "reason": "..."}: Claude Code は reason をメッセージとして返します。

以下の例は、件名が必要な形式に従っていないタスクをブロックします。

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
  exit 2
fi

exit 0

TaskCompleted

タスクが完了としてマークされるときに実行されます。これは 2 つの状況で発火します。任意のエージェントが TaskUpdate ツールを通じてタスクを明示的に完了としてマークしたとき、またはエージェントチームのチームメイトが進行中のタスクを抱えたままターンを終了したときです。タスクをクローズする前に、テストやリントチェックの合格などの完了基準を適用するために使用します。

TaskCompleted フックは matcher をサポートしておらず、すべての発生時に発火します。

TaskCompleted の入力

共通の入力フィールドに加えて、TaskCompleted フックは task_id、task_subject、および省略可能な task_description、teammate_name、team_name を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCompleted の決定制御

TaskCompleted フックは、タスクの完了を制御する 2 つの方法をサポートしています。

• 終了コード 2: タスクは完了としてマークされず、stderr メッセージがフィードバックとしてモデルに返されます。
• JSON {"continue": false, "stopReason": "..."}: チームメイトがターンを終了したことでイベントが発生した場合、Stop フックの動作と同様に、チームメイトを完全に停止します。stopReason はユーザーに表示されます。TaskUpdate ツールによってイベントが発生した場合、Claude Code は continue: false を無視しますが、終了コード 2 は引き続き完了をブロックします。

以下の例は、テストを実行し、失敗した場合はタスクの完了をブロックします。

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# Run the test suite
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi

exit 0

Stop

メインの Claude Code エージェントが応答を終えたときに実行されます。ユーザーの中断によって停止した場合は実行されません。API エラーの場合は、代わりに StopFailure が発火します。

Stop の入力

共通の入力フィールドに加えて、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 を設定します。

last_assistant_message フィールドには Claude の最終応答のテキスト内容が含まれるため、フックはトランスクリプトファイルを解析せずにアクセスできます。読み上げや通知のフックなど、完了したばかりのターンに基づいて動作するフックでは、transcript_path を読み取るのではなくこのフィールドを使用してください。すべてのバージョンで、Stop の時点でトランスクリプトファイルに最終メッセージが含まれているとは限らないためです。

background_tasks および session_crons 配列により、フックは「セッションが完了した」状態と「セッションがバックグラウンド作業による再開を待って一時停止している」状態を区別できます。どちらの配列も、タスクレジストリにアクセスできる場合に存在し、実行中またはスケジュール済みのものがない場合は空になります。

background_tasks の各エントリは実行中のタスク 1 つを表し、以下のフィールドを使用します。

session_crons の各エントリは、CronCreate、ScheduleWakeup、/loop から取得された、セッションスコープのスケジュールされたウェイクアップ 1 つを表します。

以下の例は、実行中のシェルタスク 1 つと繰り返し実行される cron 1 つを含む Stop の入力を示しています。

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

Stop の決定制御

Stop および SubagentStop フックは、Claude が続行するかどうかを制御できます。すべてのフックで利用可能な JSON 出力フィールドに加えて、フックスクリプトは以下のイベント固有のフィールドを返すことができます。

終了コード 2 で終了してブロックするフックは、reason と同じように処理されます。Claude は、続行すべき理由の説明として stderr メッセージを受け取ります。

{
  "decision": "block",
  "reason": "Must be provided when Claude is blocked from stopping"
}

「完了前にテストスイートを実行する」など、フックが設計どおりに動作して Claude にガイダンスを与えている場合は、additionalContext を使用してください。これは decision: "block" と同じループ保護（stop_hook_active 入力と、連続継続 8 回の上限）を通じて会話を継続させますが、トランスクリプトには Stop hook feedback というラベルが付き、フックエラーの通知は表示されません。

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Please run the test suite before finishing"
  }
}

StopFailure

API エラーによってターンが終了したときに、Stop の代わりに実行されます。Claude Code は、terminalSequence を除き、フックの出力と終了コードを無視します。レート制限、認証の問題、その他の API エラーによって Claude が応答を完了できない場合に、失敗をログに記録したり、アラートを送信したり、復旧アクションを実行したりするために使用します。

StopFailure の入力

共通の入力フィールドに加えて、StopFailure フックは error、省略可能な error_details、省略可能な last_assistant_message を受け取ります。error フィールドはエラーの種類を示し、matcher のフィルタリングに使用されます。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

StopFailure フックには決定制御がありません。通知とログ記録の目的でのみ実行されます。

TeammateIdle

エージェントチームのチームメイトがターンを終えてアイドル状態になろうとしているときに実行されます。リントチェックの合格を必須にしたり、出力ファイルの存在を確認したりするなど、チームメイトが作業を停止する前に品質ゲートを適用するために使用します。

TeammateIdle フックは matcher をサポートしておらず、すべての発生時に発火します。

TeammateIdle の入力

共通の入力フィールドに加えて、TeammateIdle フックは teammate_name と team_name を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

TeammateIdle の決定制御

TeammateIdle フックは、チームメイトの動作を制御する 2 つの方法をサポートしています。

• 終了コード 2: チームメイトは stderr メッセージをフィードバックとして受け取り、アイドル状態にならずに作業を続けます。
• JSON {"continue": false, "stopReason": "..."}: Stop フックの動作と同様に、チームメイトを完全に停止します。stopReason はユーザーに表示されます。

以下の例は、チームメイトがアイドル状態になるのを許可する前に、ビルドアーティファクトが存在することを確認します。

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0

ConfigChange

セッション中に設定ファイルが変更されたときに実行されます。設定の変更を監査したり、セキュリティポリシーを適用したり、設定ファイルへの不正な変更をブロックしたりするために使用します。

Claude Code は、設定ファイル、管理ポリシーファイル、またはスキルファイルが変更されたときに ConfigChange フックを実行します。管理ポリシーの場合は、managed-settings.json または managed-settings.d/ 内のファイルが変更された場合にのみ実行します。サーバー管理設定、および macOS の管理された環境設定や Windows のレジストリポリシーへの変更は、フックを実行せずに適用します。wslInheritsWindowsSettings を使用した WSL でも、Windows 側の管理設定ファイルの変更をポリシーのポーリング時にフックを実行せずに適用します。

matcher は設定のソースでフィルタリングします。

以下の例は、セキュリティ監査のためにすべての設定変更をログに記録します。

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

ConfigChange の入力

共通の入力フィールドに加えて、ConfigChange フックは source と、省略可能な file_path を受け取ります。source フィールドはどの種類の設定が変更されたかを示し、file_path は変更された特定のファイルへのパスを提供します。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/Users/.../my-project/.claude/settings.json"
}

ConfigChange の決定制御

ConfigChange フックは、設定の変更が反映されるのをブロックできます。変更を阻止するには、終了コード 2 または JSON の decision を使用します。ブロックされた場合、新しい設定は実行中のセッションに適用されません。

{
  "decision": "block",
  "reason": "Configuration changes to project settings require admin approval"
}

policy_settings の変更はブロックできません。マシン上の管理設定ファイルが変更されると、policy_settings ソースに対してもフックは発火するため、それらの編集をログに記録するために使用できますが、ブロックの決定はすべて無視されます。これにより、エンタープライズで管理される設定が常に反映されることが保証されます。サーバー管理設定が届いたり更新されたりしたときには、Claude Code は ConfigChange フックを実行しません。

Claude Code は ConfigChange フックの JSON 出力からブロックの決定に基づいて動作し、systemMessage と continue は破棄します。ブロックされた変更については、reason でブロックした場合も終了コード 2 の stderr でブロックした場合も、ユーザーにも Claude にもメッセージは表示されません。Claude Code はデバッグログに 1 行書き込むだけです。

CwdChanged

メイン会話内のシェルコマンドが作業ディレクトリを変更したとき、たとえば Claude が cd コマンドを実行したときに実行されます。環境変数の再読み込み、プロジェクト固有のツールチェーンの有効化、セットアップスクリプトの自動実行など、ディレクトリの変更に対応するために使用します。ディレクトリごとの環境を管理する direnv のようなツールでは、FileChanged と組み合わせて使用します。

CwdChanged フックは CLAUDE_ENV_FILE にアクセスできます。そのファイルに書き込まれた変数は、次の CwdChanged イベントで Claude Code がクリアするまで、後続の Bash コマンドに引き継がれます。

CwdChanged は matcher をサポートしておらず、すべての発生時に発火します。

CwdChanged の入力

共通の入力フィールドに加えて、CwdChanged フックは old_cwd と new_cwd を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project/src",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/Users/my-project",
  "new_cwd": "/Users/my-project/src"
}

CwdChanged の出力

すべてのフックで利用可能な JSON 出力フィールドに加えて、CwdChanged フックは watchPaths を返して、FileChanged が監視するファイルパスを動的に設定できます。

CwdChanged フックには決定制御がありません。ディレクトリの変更をブロックすることはできません。

Claude Code は JSON 出力から watchPaths と systemMessage を読み取り、continue は破棄します。インタラクティブセッションでは、systemMessage を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。

DirectoryAdded

セッション中に /add-dir コマンドで作業ディレクトリを追加した後、または SDK クライアントが register_repo_root 制御リクエストで作業ディレクトリを追加した後に実行されます。新しく追加されたリポジトリを準備するため、たとえば依存関係をインストールするために使用します。

Claude Code は以下の場合にこのイベントを発火しません。

• --add-dir 起動フラグでディレクトリを渡した場合。これらのディレクトリは SessionStart で対応します
• /permissions の Workspace タブでディレクトリを追加した場合
• すでに作業ディレクトリであるディレクトリ、または作業ディレクトリ内のディレクトリを追加した場合

Claude Code はサンドボックスと権限の状態を更新した後に DirectoryAdded を発火するため、フックの実行時には、サンドボックス化されたツールからすでに新しいディレクトリが見えています。フックコマンド自体はサンドボックスの外で実行されます。

Claude Code はフックを待ちません。追加は即座に完了し、フックはデフォルトの 600 秒のタイムアウトでバックグラウンドで実行されます。

matcher はディレクトリの追加方法でフィルタリングします。

DirectoryAdded の入力

共通の入力フィールドに加えて、DirectoryAdded フックは directory と source を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "DirectoryAdded",
  "directory": "/Users/my-other-repo",
  "source": "slash_command"
}

DirectoryAdded フックには決定制御がありません。フックの実行時には追加がすでに完了しているため、追加をブロックすることはできません。Claude Code は JSON 出力から continue フィールドを破棄し、残りはソースごとに異なる方法で扱います。

• slash_command: Claude Code はフックの systemMessage をユーザーに表示するのではなく、次の会話ターンでコンテキストとして Claude に配信します。失敗したフックの数がトランスクリプトに表示されます。失敗の完全な出力はデバッグログに記録されます
• register_repo_root: Claude Code は systemMessage の出力と失敗の出力をデバッグログにのみ書き込みます

FileChanged

監視対象のファイルがディスク上で変更されたときに実行されます。Claude Code はツール呼び出しを調べるのではなくファイルシステムウォッチャーで変更を検出するため、Edit や Write のツール呼び出し、Claude が Bash で実行したスクリプト、あるいは Claude Code 外部のプロセスなど、何がファイルを変更したかにかかわらずフックを実行します。一般的な用途は、プロジェクトの設定ファイルが変更されたときに環境変数を再読み込みすることです。

このイベントの matcher には 2 つの役割があります。

• 監視リストの構築: 値は | で分割され、各セグメントが作業ディレクトリ内のリテラルなファイル名として登録されます。そのため、".envrc|.env" はちょうどその 2 つのファイルを監視します。ここでは正規表現パターンは役に立ちません。^\.env のような値は、文字どおり ^\.env という名前のファイルを監視します。
• 実行するフックのフィルタリング: 監視対象のファイルが変更されると、同じ値を使用して、変更されたファイルのベース名に対して標準の matcher ルールを適用し、実行するフックグループをフィルタリングします。

以下の例は、Bash コマンドや外部スクリプトによるファイルの書き換えを含め、変更があるたびに data.csv の改行コードを正規化します。

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "data.csv",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/normalize-line-endings.sh"
          }
        ]
      }
    ]
  }
}

フックは、stdin 上の JSON 入力の file_path フィールドから、変更されたファイルの絶対パスを読み取ります。grep によるガードは perl が削除するもの、つまり行末の CR と同じものを検査するため、正規化後の実行ではファイルに触れずに終了します。ガードがより緩いと無限ループになります。perl -i は何も置換しない場合でもファイルを書き換え、Claude Code は書き換えのたびにフックを再度実行するためです。このスクリプトを /path/to/normalize-line-endings.sh に保存し、実行可能にしてください。

#!/bin/bash
FILE=$(jq -r .file_path)
if grep -q $'\r$' "$FILE"; then
  perl -pi -e 's/\r$//' "$FILE"
fi

フックが機能することを確認するには、Bash コマンドで data.csv に CRLF の行を追記するよう Claude に依頼します。Claude Code がフックを実行し、ファイルの改行コードは LF になります。

事前に名前を指定できないファイルを監視するには、フックから watchPaths を返して監視リストを動的に更新します。Claude Code は監視対象のファイルが何らかの形で指定された場合にのみウォッチャーを開始するため、少なくとも 1 つのファイルを matcher で指定した FileChanged グループ、または watchPaths を返す SessionStart や CwdChanged フックでリストを初期化してください。監視対象のファイルが変更されたときにどのフックグループを実行するかは引き続き matcher でフィルタリングされるため、動的なパスを処理するグループでは matcher を省略してください。省略した matcher はすべての監視対象ファイルにマッチし、監視リストには何も追加しません。"*" matcher もすべてのファイルにマッチしますが、Claude Code はこれを他の値と同様に、* という名前のリテラルなファイルとして監視リストに登録します。

FileChanged フックは CLAUDE_ENV_FILE にアクセスできます。そのファイルに書き込まれた変数は、次の CwdChanged イベントで Claude Code がクリアするまで、後続の Bash コマンドに引き継がれます。

FileChanged の入力

共通の入力フィールドに加えて、FileChanged フックは file_path と event を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "FileChanged",
  "file_path": "/Users/my-project/.envrc",
  "event": "change"
}

FileChanged の出力

すべてのフックで利用可能な JSON 出力フィールドに加えて、FileChanged フックは watchPaths を返して、監視するファイルパスを動的に更新できます。

FileChanged フックには決定制御がありません。ファイルの変更が発生するのをブロックすることはできません。

Claude Code は JSON 出力から watchPaths と systemMessage を読み取り、continue は破棄します。インタラクティブセッションでは、systemMessage を短いターミナル通知として表示します。このメッセージは SDK のメッセージストリームには届きません。

WorktreeCreate

claude --worktree、isolation: "worktree" を使用するサブエージェント、または Claude Code が独自の worktree に分離するバックグラウンドセッションのいずれかによって worktree が作成されるときに実行されます。デフォルトでは、Claude Code は git worktree を使用して分離された作業コピーを作成します。WorktreeCreate フックを設定すると、このデフォルトの git の動作が置き換えられ、SVN、Perforce、Mercurial などの別のバージョン管理システムを使用できるようになります。

フックはデフォルトの動作を完全に置き換えるため、.worktreeinclude は処理されません。.env などのローカル設定ファイルを新しい worktree にコピーする必要がある場合は、フックスクリプト内でコピーしてください。

フックは、作成された worktree ディレクトリへのパスを返す必要があります。Claude Code はこのパスを分離されたセッションの作業ディレクトリとして使用します。各フックタイプがパスを返す方法については、WorktreeCreate の出力を参照してください。

Claude Code はフックの成功と返されたパスに基づいて動作し、systemMessage と continue は破棄します。

以下の例は、SVN の作業コピーを作成し、Claude Code が使用するパスを出力します。リポジトリの URL は自分のものに置き換えてください。

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

フックは stdin 上の JSON 入力から worktree の name を読み取り、新しいディレクトリに新しいコピーをチェックアウトして、そのディレクトリパスを出力します。最後の行の echo が、Claude Code が worktree のパスとして読み取るものです。パスの妨げにならないよう、その他の出力はすべて stderr にリダイレクトしてください。

WorktreeCreate の入力

共通の入力フィールドに加えて、WorktreeCreate フックは name フィールドを受け取ります。これは新しい worktree のスラッグ識別子で、ユーザーが指定するか自動生成されます（例: bold-oak-a3f2）。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

WorktreeCreate の出力

WorktreeCreate フックは、標準の許可/ブロックの判定モデルを使用しません。代わりに、フックの成功または失敗によって結果が決まります。フックは作成された worktree ディレクトリのパスを返す必要があります。

• コマンドフック（type: "command"）：パスを stdout の最後の空でない行として出力します。Claude Code はその行を読み取る前に ANSI エスケープコードを取り除くため、echo の前に出力されたシェルの起動バナーは無視されます。フックのその他の出力はすべて stderr にリダイレクトしてください。
• HTTP フック（type: "http"）：レスポンスボディで { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } を返します。

フックが失敗した場合、またはパスを生成しなかった場合、worktree の作成はエラーで失敗します。

Claude Code は相対パスをフックが実行されたディレクトリを基準に解決し、パス内の . や .. セグメントを畳み込みます。解決後のパスが Claude Code が移動できるディレクトリでない場合、セッションはそのパスを示すエラーを出力し、終了コード 1 で終了します。

Claude Code は、. や .. セグメントを含む絶対パス、およびリポジトリルート配下のシンボリックリンクを経由するパスを拒否します。リポジトリにコミットされたシンボリックリンクによって、worktree がリポジトリの外にリダイレクトされる可能性があるためです。エラーには拒否されたコンポーネントが示されます。リポジトリ内のシンボリックリンクを経由しない正規化されたパスを返してください。v2.1.216 より前は、worktree の作成はこのチェックを行わずにフックのパスに従っていました。

WorktreeRemove

worktree が削除されるときに実行されます。これは WorktreeCreate に対応するクリーンアップ用のイベントです。このイベントは次の場合に発生します。

• --worktree セッションを終了し、削除を選択したとき
• isolation: "worktree" を持つサブエージェントが完了したとき
• フックが worktree を作成したバックグラウンドセッションを削除したとき

Git ベースの worktree の場合、Claude Code は git worktree remove でクリーンアップを自動的に処理します。WorktreeCreate フックを設定した場合は、WorktreeRemove フックと組み合わせて、作成した worktree のクリーンアップを制御してください。

• WorktreeRemove フックがない場合：--worktree セッションを終了して削除を選択すると、Claude Code は WorktreeCreate フックが返したパスに対して git worktree remove --force にフォールバックするため、Git が認識している worktree は削除されます。Git が認識していない worktree（たとえば、Git 以外のバージョン管理システムでフックが作成したもの）はディスク上に残ります。フックが作成した worktree に対してバックグラウンドセッションの削除が何を行うかについては、agent view の削除ルールを参照してください。
• フックが 0 で終了した場合：worktree は削除済みとして扱われます。Claude Code はフックからそれ以外の情報を読み取らないため、フックがディレクトリを確実に削除するようにしてください。
• フックが 0 以外で終了した場合：その後も worktree_path のディレクトリが存在していれば削除は失敗し、Git へのフォールバックは行われずに worktree はディスク上に残ります。0 以外で終了する前にディレクトリを削除したフックは、削除済みとして扱われます。失敗がどのように報告されるかについては、WorktreeRemove の入力を参照してください。

Claude Code は WorktreeCreate フックが返したパスしか把握していないため、フックが作成した worktree に属するブランチを削除することはありません。WorktreeCreate フックがブランチを作成する場合は、WorktreeRemove フックでそのブランチを削除してください。

Claude Code は、systemMessage や continue などの WorktreeRemove フックの JSON 出力フィールドを破棄します。

バックグラウンドセッションの削除では、Claude Code はフックを実行する前に保存された worktree パスを検証し、シンボリックリンクであるパスや、リポジトリルート配下のシンボリックリンクを経由するパスを拒否します。まだファイルが含まれている worktree に対してフックが実行されるのは、agent view で削除を確認した場合のみです。そのような worktree の場合、claude rm はセッションと worktree を保持します。v2.1.216 より前は、フックはこれらのチェックなしに保存されたパスに対して実行されていました。

Claude Code は、WorktreeCreate が返したパスをフック入力の worktree_path として渡します。次の例では、そのパスを読み取ってディレクトリを削除します。

{
  "hooks": {
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

WorktreeRemove の入力

共通の入力フィールドに加えて、WorktreeRemove フックは worktree_path フィールドを受け取ります。これは削除される worktree の絶対パスです。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
}

WorktreeRemove フックの終了コードによって結果が決まります。フックが 0 以外で終了し、その後も worktree_path のディレクトリが存在する場合、削除は失敗します。

• worktree はディスク上に残り、フックのコマンドと stderr はデバッグログに送られます。
• バックグラウンドセッションを削除しようとしていた場合は、セッションも残ります。agent view の拒否メッセージには、exited 1 などフックがどのように終了したか、stderr の冒頭部分、そしてセッションを再度削除した場合にディレクトリが強制的に削除されるかどうかが表示されます。

PreCompact

Claude Code がコンテキスト圧縮を実行する直前に実行されます。

matcher の値は、圧縮が手動でトリガーされたか自動でトリガーされたかを示します。

圧縮をブロックするには、終了コード 2 で終了します。手動の /compact の場合、stderr のメッセージがユーザーに表示されます。"decision": "block" を含む JSON を返してブロックすることもできます。

自動圧縮をブロックした場合の効果は、発生するタイミングによって異なります。コンテキスト制限に達する前に予防的に圧縮がトリガーされた場合、Claude Code は圧縮をスキップし、会話は圧縮されないまま続行されます。API からすでに返されたコンテキスト制限エラーから回復するために圧縮がトリガーされた場合、元のエラーが表面化し、現在のリクエストは失敗します。

Claude Code は PreCompact フックの systemMessage および continue フィールドを破棄します。

PreCompact の入力

共通の入力フィールドに加えて、PreCompact フックは trigger と custom_instructions を受け取ります。manual の場合、custom_instructions にはユーザーが /compact に渡した内容が含まれ、何も渡さなかった場合は null になります。auto の場合、custom_instructions は null です。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": null
}

PostCompact

Claude Code がコンテキスト圧縮を完了した後に実行されます。このイベントを使用すると、生成された要約をログに記録したり外部の状態を更新したりするなど、圧縮後の新しい状態に対応できます。Claude Code は PostCompact フックの systemMessage および continue フィールドを破棄します。

PreCompact と同じ matcher の値が適用されます。

PostCompact の入力

共通の入力フィールドに加えて、PostCompact フックは trigger と compact_summary を受け取ります。compact_summary フィールドには、圧縮によって生成された会話の要約が含まれます。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

PostCompact フックには判定の制御がありません。圧縮の結果に影響を与えることはできませんが、後続のタスクを実行できます。

PreModelSwitch

ユーザーまたはクライアントが要求したモデルの切り替えを Claude Code が適用する前に実行されます。切り替えのブロック、確認の要求、または切り替え前にそのコストを表示するために使用します。

PreModelSwitch には Claude Code v2.1.251 以降が必要です。Claude Code は次のリクエストに対してこのフックを実行します。

• /model <name> および /model ピッカー
• Option+P または Alt+P のモデルピッカー
• /config の Model 設定
• セッションのモデルが変わる場合の fast mode のオン
• Agent SDK ホストまたは Remote Control からの set_model リクエスト、または apply_flag_settings リクエストでのモデル変更

モデルの自動フォールバックやセッション再開時のモデルの復元など、Claude Code が独自に行う切り替えについては PreModelSwitch フックは実行されません。これらの変更は PostModelSwitch にのみ届きます。

Claude Code は、matcher をセッションの切り替え先モデルの正規名と比較します。このとき [1m] サフィックスは無視されます。opus などのエイリアス、日付付きのモデル ID、Amazon Bedrock のモデル ID などのプロバイダー固有の ID はすべて、解決先の 1 つの正規名に一致するため、claude-opus-5 は Opus 5 のあらゆる表記をカバーします。

Claude Code が切り替え先の正規名を特定できない場合（たとえば LLM ゲートウェイだけが認識するカスタムモデル ID など）、matcher に関係なくすべての PreModelSwitch フックが実行されます。したがって、ブロックを行うフックは matcher だけに頼るのではなく、入力の to_model を確認する必要があります。

matcher は、完全一致の名前、claude-opus-4-6|claude-opus-5 のような | 区切りのリスト、または .*opus.* のような正規表現として記述します。次の例では、完全一致の matcher を使用しつつフック入力の to_model も確認し、終了コード 2 で終了することで Opus 4.6 への切り替えを拒否し、それ以外の切り替え先は通過させます。

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"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"
}
]
}
]
}
}

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
]
}
]
}
]
}
}

$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($hookInput.to_model -match 'opus-4-6') {
[Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
exit 2
}
exit 0

フックが機能することを確認するには、別のモデルで実行中のセッションから /model claude-opus-4-6 を実行します。Claude Code は現在のモデルを維持し、PreModelSwitch フックが切り替えをブロックしたことを、指定したメッセージを理由として報告します。

PreModelSwitch の入力

共通の入力フィールドに加えて、PreModelSwitch フックは次の表のフィールドを受け取ります。最後の 5 つは、会話を新しいモデルに再送信する際のコストを表すため、フックは切り替えの前にその数値を表示できます。

次の例は、Sonnet 5 で実行中のセッションで /model opus を実行した場合の入力を示しています。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreModelSwitch",
  "from_model": "claude-sonnet-5",
  "to_model": "claude-opus-5",
  "requested_model": "opus",
  "source": "command",
  "context_tokens": 182340,
  "prompt_cache_warm": true,
  "cache_ttl": "5m",
  "estimated_cache_write_usd": 1.1396,
  "pricing": "catalog"
}

PreModelSwitch の判定制御

PreModelSwitch フックは、切り替えをキャンセルしたり、ユーザーに確認を求めたり、そのまま続行させたりできます。終了コード 2 またはトップレベルの decision: "block" は切り替えをキャンセルします。

より細かく制御するには、PreToolUse と同様に、hookSpecificOutput オブジェクト内で permissionDecision と permissionDecisionReason を返します。PreModelSwitch は "allow"、"deny"、"ask" を受け付けます。"defer"、updatedInput、additionalContext は受け付けません。次の表で両方のフィールドについて説明します。

"ask" のプロンプトを表示できるのは、対話セッションでの /model のみです。-p フラグを使用した非対話モード、/config、set_model リクエストを含むその他すべてのサーフェスでは、Claude Code は "ask" を拒否として扱います。

次の例では、ユーザーに確認を求め、context_tokens のトークン数を示しています。

{
  "hookSpecificOutput": {
    "hookEventName": "PreModelSwitch",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
  }
}

複数の PreModelSwitch フックが異なる判定を返した場合、優先順位は deny > ask > allow です。

Claude Code は判定にかかわらず、フックが返した systemMessage をユーザーに表示します。そのため、コストを報告するフックは {"systemMessage": "..."} を返して 0 で終了できます。

タイムアウトまでに応答しない PreModelSwitch フックは、切り替えをブロックします。対照的に、PreToolUse では、タイムアウトしたコマンドフックはツール呼び出しを続行させます。このイベントのデフォルトのタイムアウトは 30 秒です。PreModelSwitch は command、http、mcp_tool フックのみを実行するため、prompt と agent のデフォルトは適用されません。

0 または 2 以外のコードで終了し、JSON の判定を出力しないフックはブロックしません。その他の終了コードで説明されているとおり、Claude Code はその stderr を表示して切り替えを適用します。

PostModelSwitch

セッションのモデルが変更された後に実行されます。特定のモデルに適用される組織全体の指示など、すべての CLAUDE.md を編集することなく、Claude にモデル固有のガイダンスを与えるために使用します。

PostModelSwitch には Claude Code v2.1.251 以降が必要です。モデルはすでに変更されているため、ブロックすることはできません。Claude Code は、次のいずれかの変更の後に PostModelSwitch フックを実行します。

• ユーザーまたはクライアントが要求した切り替え
• セッションのモデルを変更するモデルの自動フォールバック
• opusplan などの設定による plan モードへの移行または終了
• セッション再開時に Claude Code がモデルを復元したとき

フォールバックモデルチェーンのモデルがターンを処理した場合、PostModelSwitch フックは実行されません。この置き換えは 1 ターンのみ有効で、セッションのモデルは変更されないためです。

matcher は PreModelSwitch と同じルールに従います。Claude Code は、matcher をセッションの切り替え先モデルの正規名と比較します。

次の例では、セッションのモデルがいずれかの Opus モデルに変更されるたびにガイダンスを追加します。

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": ".*opus.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
          }
        ]
      }
    ]
  }
}

フックが機能することを確認するには、別のモデルで実行中のセッションから Opus モデルに切り替え（たとえば Sonnet セッションから /model opus を実行）、現在のモデルについてどのようなガイダンスがあるかを Claude に尋ねます。

PostModelSwitch の入力

PostModelSwitch フックは PreModelSwitch と同じフィールドを受け取ります。ただし、hook_event_name は "PostModelSwitch" に設定され、source には 2 つの値が追加されます。自動フォールバックや Claude Code が独自に行ったその他の変更の場合は "auto"、セッション再開時に復元されたモデルの場合は "resume" です。

source が "auto" の場合、requested_model は null です。source が "resume" の場合は、Claude Code が復元した保存済みのモデル設定です。

PostModelSwitch の判定制御

Claude Code は、終了コード 0 の場合のフックのプレーンテキストの stdout、または JSON 出力の additionalContext を取得し、切り替え後の次のリクエストとともに Claude に渡します。すべてのフックで使用できる JSON 出力フィールドに加えて、次のフィールドを返すことができます。

次のプロンプトを送信してから 5 秒以内にフックが完了しない場合、Claude Code は出力なしでそのリクエストを送信し、代わりにその次のリクエストに出力を添付します。次のリクエストまでにモデルが複数回変更された場合、Claude Code は最後の切り替え先モデルの出力のみを渡します。

SessionEnd

Claude Code セッションが終了するときに実行されます。クリーンアップタスク、セッション統計のログ記録、セッション状態の保存に役立ちます。終了理由でフィルタリングするための matcher をサポートしています。

フック入力の reason フィールドは、セッションが終了した理由を示します。

SessionEnd の入力

共通の入力フィールドに加えて、SessionEnd フックはセッションが終了した理由を示す reason フィールドを受け取ります。すべての値については、上記の理由の表を参照してください。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

SessionEnd フックには判定の制御がありません。セッションの終了をブロックすることはできませんが、クリーンアップタスクを実行できます。Claude Code は、systemMessage などの JSON 出力フィールドを破棄します。

SessionEnd フックのデフォルトのタイムアウトは 1.5 秒です。これは、終了したとき、/clear を実行したとき、または対話的な /resume でセッションを切り替えたときに適用されます。フックにより多くの時間を与えるには、次の 2 つの方法があります。

• フックごとの timeout：そのフックの設定で timeout を設定します。全体の上限時間は、設定ファイル内のフックごとの timeout の最大値に合わせて、最大 60 秒まで自動的に引き上げられます。この方法で上限時間を引き上げても、独自の timeout を持たないフックはデフォルトのままです。プラグインが提供するフックに設定されたタイムアウトは、上限時間を引き上げません。
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS：この環境変数をミリ秒単位で設定すると、上限時間を明示的に上書きできます。設定した値は、独自の timeout を持たない各フックのタイムアウトにもなります。

次の例では、上限時間を 5 秒に設定します。

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

v2.1.268 より前は、CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS は全体の上限時間のみを引き上げ、独自の timeout を持たないフックは引き続き 1.5 秒後にキャンセルされていました。

Elicitation

MCP サーバーがタスクの途中でユーザー入力を要求したときに実行されます。デフォルトでは、Claude Code はユーザーが応答するための対話ダイアログを表示します。フックはこのリクエストをインターセプトしてプログラムで応答し、ダイアログを完全にスキップできます。

matcher フィールドは MCP サーバー名と照合されます。

Elicitation の入力

共通の入力フィールドに加えて、Elicitation フックは mcp_server_name、message、およびオプションの mode、url、elicitation_id、requested_schema フィールドを受け取ります。

最も一般的なケースであるフォームモードの elicitation の場合：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

ブラウザベースの認証に使用される URL モードの elicitation の場合：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Elicitation の出力

ダイアログを表示せずにプログラムで応答するには、hookSpecificOutput を含む JSON オブジェクトを返します。

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": {
      "username": "alice"
    }
  }
}

終了コード 2 は elicitation を拒否します。Claude Code は stderr のメッセージをどこにも表示しません。

Claude Code は Elicitation フックの JSON 出力のうち hookSpecificOutput に従って動作し、systemMessage と continue は破棄します。

ElicitationResult

ユーザーが MCP の elicitation に応答した後に実行されます。フックは、応答が MCP サーバーに返送される前に、その応答を監視、変更、またはブロックできます。

matcher フィールドは MCP サーバー名と照合されます。

ElicitationResult の入力

共通の入力フィールドに加えて、ElicitationResult フックは mcp_server_name、action、およびオプションの mode、elicitation_id、content フィールドを受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

ElicitationResult の出力

ユーザーの応答を上書きするには、hookSpecificOutput を含む JSON オブジェクトを返します。

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

終了コード 2 は応答をブロックし、実際のアクションを decline に変更します。Claude Code は stderr のメッセージをどこにも表示しません。

Claude Code は ElicitationResult フックの JSON 出力のうち hookSpecificOutput に従って動作し、systemMessage と continue は破棄します。

プロンプト ベースのフック

コマンド、HTTP、MCP ツール フックに加えて、Claude Code はプロンプト ベースのフック（type: "prompt"）をサポートしており、LLM を使用してアクションを許可またはブロックするかどうかを評価し、エージェント フック（type: "agent"）はツール アクセスを持つ agentic ベリファイアーを生成します。すべてのイベントがすべてのフック タイプをサポートしているわけではありません。

5 つのフック タイプ（command、http、mcp_tool、prompt、agent）すべてをサポートするイベント：

• PermissionDenied
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

PermissionRequest は command、http、mcp_tool、prompt フックをサポートしますが、agent フックはサポートしません。このイベントにエージェント フックを設定した場合、Claude Code はそれをスキップし、権限フローは変更されずに進行します。フックから許可または拒否するには、コマンド フックまたは HTTP フックから決定オブジェクトを返します。

command、http、mcp_tool フックをサポートするが、prompt または agent をサポートしないイベント：

• ConfigChange
• CwdChanged
• DirectoryAdded
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• MessageDisplay
• Notification
• PostCompact
• PostModelSwitch
• PreCompact
• PreModelSwitch
• SessionEnd
• StopFailure
• SubagentStart
• WorktreeCreate
• WorktreeRemove

SessionStart と Setup は command と mcp_tool フックをサポートしており、それらの mcp_tool フックがいつ実行されるかについては MCP ツール フックのフィールドで説明しています。これらは http、prompt、agent フックをサポートしていません。

プロンプト ベースのフックの仕組み

プロンプト ベースのフックは Bash コマンドを実行する代わりに：

1. フック入力とプロンプトを Claude モデル（デフォルトでは Claude Code がバックグラウンド機能に使用するモデル）に送信
2. LLM は決定を含む構造化 JSON で応答
3. Claude Code は決定を自動的に処理

プロンプト フック設定

type を "prompt" に設定し、command の代わりに prompt 文字列を提供します。$ARGUMENTS プレースホルダーを使用して、フックの JSON 入力データをプロンプト テキストに注入します。

この Stop フックは、Claude が終了する前にすべてのタスクが完了しているかどうかを評価するよう LLM に求めます：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

レスポンス スキーマ

LLM は以下を含む JSON で応答する必要があります：

{
  "ok": true | false,
  "reason": "Explanation for the decision",
  "impossible": true | false
}

ok: false で何が起こるかはイベントによって異なります：

• Stop と SubagentStop：理由は Claude の次の指示としてフィードバックされ、ターンが続行されます。ただし、応答で impossible: true も設定されている場合は、Claude Code が停止を許可し、ターンが終了します
• PreToolUse：ツール呼び出しが拒否されます。デフォルトではターンが終了し、拒否理由は警告行としてチャットに表示されます。代わりに理由をツール エラーとして Claude に返し、Claude が調整して続行できるようにするには、continueOnBlock: true を設定します。これはコマンド フックの permissionDecision: "deny" と同等です。v2.1.210 より前は、拒否理由はツール エラーとして Claude に返され、ターンは続行されていました
• PostToolUse：デフォルトではターンが終了し、理由は警告行としてチャットに表示されます。continueOnBlock: true を設定して、理由を Claude にフィードバックし、ターンを続行する代わりに使用します
• PostToolBatch、UserPromptSubmit、UserPromptExpansion：ターンが終了し、理由は警告行として表示されます。これらのイベントは continue に関係なく decision: "block" でターンを終了します
• PostToolUseFailure、TaskCreated：理由は continueOnBlock に関係なくツール エラーとして Claude に返され、ターンが続行されます
• TaskCompleted：ターン中にタスクが完了としてマークされたために発火した場合、理由は continueOnBlock に関係なくツール エラーとして Claude に返され、ターンが続行されます。チームメイトが停止したために発火した場合は、TeammateIdle と同様に動作し、デフォルトでチームメイトを停止します
• TeammateIdle：デフォルトではチームメイトが停止し、理由は警告行として表示されます。continueOnBlock: true を設定して、理由をチームメイトにフィードバックし、代わりに作業を続行させます
• PermissionRequest：ok: false は効果がありません。フックから承認を拒否するには、コマンド フックを使用して hookSpecificOutput.decision.behavior: "deny" を返します
• PermissionDenied：ok: false は効果がありません。拒否は既に発生しているためです。このイベントが読み取る唯一の出力は hookSpecificOutput.retry です。プロンプト フックとエージェント フックはこれを設定できません。これらはこのイベントで実行されますが、その出力は破棄されます。retry を返すには、コマンド フックを使用してください

任意のイベントでより細かい制御が必要な場合は、決定制御で説明されているイベント ごとのフィールドを使用して、コマンド フックを使用してください。

停止する前に複数の条件をチェック

この Stop フックは詳細なプロンプトを使用して、Claude が停止することを許可する前に 3 つの条件をチェックします。SubagentStop フックは同じ形式を使用して、サブエージェントが停止すべきかどうかを評価します。条件がまだ満たされていないためにモデルが "ok": false を返した場合、Claude は提供された理由を次の指示として受け取り、作業を続行します：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

エージェント ベースのフック

エージェント ベースのフック（type: "agent"）はプロンプト ベースのフックのようですが、マルチターン ツール アクセスを備えています。単一の LLM 呼び出しの代わりに、エージェント フックはサブエージェントを生成し、ファイルを読み取り、コードを検索し、コードベースを検査して条件を検証できます。エージェント フックは、PermissionRequest を除き、プロンプト ベースのフックと同じイベントをサポートしています。

エージェント フックの仕組み

エージェント フックが発火するとき：

1. Claude Code はプロンプトとフックの JSON 入力を持つサブエージェントを生成します
2. サブエージェントは Read、Grep、Glob などのツールを使用して調査できます
3. 最大 50 ターン後、サブエージェントは構造化 { "ok": true/false } 決定を返します
4. Claude Code は ok が true の場合にアクションを許可します。ok が false の場合、Claude Code はレスポンス スキーマに記載されているとおり、そのイベントで continueOnBlock: true を指定したプロンプト フックと同じ方法でブロックを処理します

エージェント フックは、フック入力データのみを評価するのではなく、実際のファイルを検査したりテスト出力を検査したりする必要がある場合に便利です。

エージェント フック設定

type を "agent" に設定し、prompt 文字列を提供します。フック入力 JSON のプレースホルダーとして $ARGUMENTS を使用します。設定フィールドはプロンプト フックと同じですが、エージェント フックはデフォルト タイムアウトが 60 秒と長く、continueOnBlock フィールドがありません。

レスポンス スキーマは、許可する場合は { "ok": true }、ブロックする場合は { "ok": false, "reason": "..." } です。ok: false の場合、Claude Code はエージェント フックを、同じイベントにおけるcontinueOnBlock: true を指定したプロンプト フックと同じ方法で処理します。エージェント フックには continueOnBlock フィールドがなく、プロンプト フックの impossible フィールドもサポートしていません。

この Stop フックは、Claude が終了することを許可する前にすべてのユニット テストが合格することを検証します：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

バックグラウンドでフックを実行

デフォルトでは、フックは完了するまで Claude の実行をブロックします。デプロイ、テスト スイート、外部 API 呼び出しなどの長時間実行タスクの場合、"async": true を設定してフックをバックグラウンドで実行し、Claude が作業を続行できるようにします。非同期フックはブロックまたは Claude の動作を制御できません。decision、permissionDecision、continue などのレスポンス フィールドは、制御しようとしたアクションがすでに完了しているため、効果がありません。

非同期フックを設定

コマンド フックの設定に "async": true を追加して、Claude をブロックせずにバックグラウンドで実行します。このフィールドは type: "command" フックでのみ利用可能です。

このフックは、すべての Write ツール呼び出しの後にテスト スクリプトを実行します。run-tests.sh の実行中も、Claude はすぐに作業を続行します。スクリプトが完了すると、その出力は次の会話ターンで配信されます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

非同期フックがバックグラウンドで実行され始めると、Claude Code はそのフックに timeout を適用しません。asyncRewake で実行するフックには、Claude Code は引き続き timeout を適用します。

Claude Code が非同期フックの結果を配信するのは、セッションの実行中のみです。

• -p フラグを使用した非対話モードでは、Claude Code は終了処理時にまだ実行中の非同期フックをすべて強制終了し、結果 cancelled で確定します
• フックの処理を claude -p セッションより長く存続させる必要がある場合は、フックから完全にデタッチされたプロセスを起動します

非同期フックの実行方法

非同期フックが発火すると、Claude Code はフック プロセスを開始し、完了を待たずにすぐに続行します。フックは同期フックと同じ JSON 入力を stdin 経由で受け取ります。

バックグラウンド プロセスが終了した後、Claude Code はフックの JSON レスポンスに含まれる additionalContext フィールドと systemMessage フィールドを次の会話ターンで Claude に配信します。同期フックの systemMessage とは異なり、どちらのフィールドもユーザーには表示されません。

Claude Code は JSON レスポンスを同期フックと同じ出力スキーマに対して検証し、systemMessage が文字列でないなど、値の型が間違っているフィールドをドロップします。これは配信する代わりに行われます。--debug で実行すると、ドロップされた各フィールドに名前を付けた警告が表示されます。v2.1.202 より前では、非同期フックからの不正な形式の JSON 出力はセッションをクラッシュさせる可能性があり、セッションが再開されるたびにクラッシュが再発生していました。

非同期フック完了通知はデフォルトで抑制されます。これらを表示するには、Ctrl+O で詳細モードを有効にするか、--verbose で Claude Code を開始します。

ファイル変更後にテストを実行

このフックは Claude がファイルを書き込むたびにバックグラウンドでテスト スイートを開始し、テストが完了したら結果を Claude に報告します。このスクリプトをプロジェクトの .claude/hooks/run-tests-async.sh に保存し、chmod +x で実行可能にします。

#!/bin/bash
# run-tests-async.sh

# stdin からフック入力を読み取る
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# ソース ファイルのみテストを実行
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# テストを実行し、additionalContext 経由で結果を Claude に報告
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  MSG="Tests passed after editing $FILE_PATH"
else
  MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

次に、プロジェクト ルートの .claude/settings.json にこの設定を追加します。async: true フラグにより、Claude はテストの実行中に作業を続行できます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true
          }
        ]
      }
    ]
  }
}

制限事項

非同期フックは同期フックと比べていくつかの制約があります。

• フック出力は次の会話ターンで配信されます。セッションがアイドル状態の場合、レスポンスは次のユーザー操作まで待機します。例外: asyncRewake フックが終了コード 2 で終了すると、セッションがアイドル状態でも Claude を直ちに起動します。
• 各実行は個別のバックグラウンド プロセスを作成します。同じ非同期フックの複数の発火全体で重複排除はありません。

セキュリティに関する考慮事項

免責事項

ワークスペースの信頼

Claude Code は、設定ファイルのフックを実行する前にワークスペースの信頼を確認します。何が信頼済みとみなされるかは、セッションの種類によって異なります。

• インタラクティブ セッション: ユーザーがそのフォルダー、またはそのフォルダーにまで信頼が及ぶ親ディレクトリについてワークスペースの信頼ダイアログを承認するまで、Claude Code はユーザー自身の ~/.claude/settings.json を含むすべての設定ファイルのフックを保留します
• -p または SDK セッション: Claude Code はダイアログを表示せず、フォルダーを信頼済みとして扱います。そのため、リポジトリの .claude/settings.json にコミットされたフックは、一度も信頼したことのないフォルダーでも実行されます

自分が作成していないリポジトリに対して claude -p をスクリプトで実行する前に、そのリポジトリの .claude/ 設定ファイルを確認するか、--bare で開始するか、--settings '{"disableAllHooks": true}' を使用してその実行ではフックをオフにしてください。プロジェクト サブエージェントのフロントマター フックには、設定ファイルのフックよりも厳しいルールが適用されます。フォルダーを信頼する前に実行されるものでは、リポジトリのコンテンツの種類ごとにセッションの種類別の動作を示しています。

セキュリティ ベストプラクティス

フックを書くときは、これらのプラクティスに留意してください。

• 入力を検証およびサニタイズ: 入力データを盲目的に信頼しないでください
• 常にシェル変数を引用: $VAR ではなく "$VAR" を使用
• パス トラバーサルをブロック: ファイル パスで .. をチェック
• 絶対パスを使用: スクリプトの完全なパスを指定します。exec 形式では、${CLAUDE_PROJECT_DIR} を使用し、パスは引用符で囲む必要がありません。シェル形式では、ダブル クォートで囲みます
• 機密ファイルをスキップ: .env、.git/、キーなどを避ける

Windows PowerShell ツール

Windows では、コマンド フックで "shell": "powershell" を設定することで、個別のフックを PowerShell で実行できます。Claude Code は pwsh.exe（PowerShell 7 以降の実行可能ファイル）を自動検出し、Windows PowerShell 5.1 の powershell.exe にフォールバックします。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'File written'"
          }
        ]
      }
    ]
  }
}

PowerShell シェル形式のコマンドからプロジェクト ルートを参照するには、${CLAUDE_PROJECT_DIR} または $env:CLAUDE_PROJECT_DIR を記述します。Claude Code は settings.json、プラグイン、またはスキルで定義されているかどうかに関係なく、PowerShell シェル形式のコマンド内の ${CLAUDE_PROJECT_DIR}、${CLAUDE_PLUGIN_ROOT}、および ${CLAUDE_PLUGIN_DATA} プレースホルダーを PowerShell の ${env:NAME} 形式に書き換えます。PowerShell は解析後にエクスポートされた環境から値を解決するため、プレースホルダーはダブルクォート文字列内では機能しますが、PowerShell が変数を展開しないシングルクォート文字列内では機能しません。

PowerShell フックで裸の $CLAUDE_PROJECT_DIR スペルを記述しないでください。PowerShell はそれを未定義のローカル変数として解析し、$null に解決します。これにより、スクリプト パスがプロジェクト ルート プレフィックスなしで残されます。Claude Code はその形式を書き換えません。代わりに、デバッグ ログ に警告を記録します。

以下の例は、$env: 形式でプロジェクト スクリプトを実行する settings.json フックを示しています。

{
  "type": "command",
  "shell": "powershell",
  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}

フックをデバッグ

フック実行の詳細はデバッグ ログ ファイルに書き込まれます。claude --debug-file <path> で既知の場所にログを書き込むか、claude --debug を実行してログを ~/.claude/debug/<session-id>.txt で読み取ります。--debug フラグはターミナルに出力しません。

たとえば、Write に対する PostToolUse フックで、コマンドが hook-ran を出力する場合、次のようなエントリが生成されます。

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

より詳細なフック マッチング詳細については、CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose を設定して、フック matcher 数とクエリ マッチングなどの追加ログ行を確認します。

フックが発火しない、Stop フックが実行をブロックし続ける、または設定エラーなどの一般的な問題のトラブルシューティングについては、ガイドの制限事項とトラブルシューティングを参照してください。/context、/doctor、および設定の優先順位をカバーするより広範な診断チュートリアルについては、設定をデバッグを参照してください。