Hooks リファレンス

Claude Code のフック イベント、設定スキーマ、JSON 入出力形式、終了コード、非同期フック、HTTP フック、プロンプト フック、MCP ツール フックのリファレンス。

フックは、Claude Code のライフサイクル内の特定のポイントで自動的に実行されるユーザー定義のシェル コマンド、HTTP エンドポイント、または LLM プロンプトです。このリファレンスを使用して、イベント スキーマ、設定オプション、JSON 入出力形式、非同期フック、HTTP フック、MCP ツール フックなどの高度な機能を検索してください。初めてフックを設定する場合は、代わりにガイドから始めてください。

フック ライフサイクル

フックは Claude Code セッション中の特定のポイントで発火します。イベントが発火してマッチャーがマッチすると、Claude Code はイベントに関する JSON コンテキストをフック ハンドラーに渡します。コマンド フックの場合、入力は stdin に到着します。HTTP フックの場合、POST リクエスト本体として到着します。ハンドラーは入力を検査し、アクションを実行し、オプションで決定を返すことができます。イベントは 3 つのケイデンスに分類されます。セッションごとに 1 回（SessionStart、SessionEnd）、ターンごとに 1 回（UserPromptSubmit、Stop、StopFailure）、agentic ループ内のすべてのツール呼び出しで（PreToolUse、PostToolUse）です。

以下の表は、各イベントがいつ発火するかをまとめています。フック イベントセクションでは、各イベントの完全な入力スキーマと決定制御オプションについて説明しています。

フックがどのように解決されるか

これらの部分がどのように組み合わさるかを理解するために、破壊的なシェル コマンドをブロックする PreToolUse フックを考えてみましょう。matcher は Bash ツール呼び出しに絞り込み、if 条件は rm * にマッチするコマンドにさらに絞り込むため、block-rm.sh は両方のフィルターがマッチするときのみ生成されます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

スクリプトは stdin から JSON 入力を読み取り、コマンドを抽出し、rm -rf が含まれている場合は permissionDecision として "deny" を返します。

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # allow the command
fi

ここで Claude Code が Bash "rm -rf /tmp/build" を実行することにしたとします。以下が起こります。

{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }

{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Destructive command blocked by hook"
}
}

以下の設定セクションでは完全なスキーマについて説明し、各フック イベントセクションでは、コマンドが受け取る入力と返すことができる出力について説明しています。

設定

フックは JSON 設定ファイルで定義されます。設定には 3 つのネストレベルがあります。

1. 応答するフック イベントを選択します（PreToolUse や Stop など）
2. 発火するタイミングをフィルタリングするマッチャー グループを追加します（'Bash ツールのみ'など）
3. マッチしたときに実行する 1 つ以上のフック ハンドラーを定義します

完全なウォークスルーと注釈付きの例については、上記のフックがどのように解決されるかを参照してください。

フック位置

フックを定義する場所によって、そのスコープが決まります。

設定ファイル解決の詳細については、設定を参照してください。エンタープライズ管理者は allowManagedHooksOnly を使用して、ユーザー、プロジェクト、プラグイン フックをブロックできます。管理設定で force-enabled されたプラグインからのフックは除外されるため、管理者は組織マーケットプレイスを通じて検証済みのフックを配布できます。フック設定を参照してください。

マッチャー パターン

matcher フィールドは、フックが発火するタイミングをフィルタリングします。マッチャーの評価方法は、含まれている文字に依存します。

FileChanged イベントは監視リストを構築するときにこれらのルールに従いません。FileChangedを参照してください。

各イベント タイプは異なるフィールドでマッチします。

マッチャーは、Claude Code がフックに stdin で送信するJSON 入力からのフィールドに対して実行されます。ツール イベントの場合、そのフィールドは tool_name です。各フック イベントセクションでは、マッチャー値の完全なセットとそのイベントの入力スキーマをリストしています。

この例は、Claude がファイルを書き込むまたは編集するときにのみ linting スクリプトを実行します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

UserPromptSubmit、PostToolBatch、Stop、TeammateIdle、TaskCreated、TaskCompleted、WorktreeCreate、WorktreeRemove、CwdChanged はマッチャーをサポートせず、すべての出現で常に発火します。これらのイベントに matcher フィールドを追加すると、サイレントに無視されます。

ツール イベントの場合、個別のフック ハンドラーで if フィールドを設定することで、より狭くフィルタリングできます。if は権限ルール構文を使用してツール名と引数を一緒にマッチするため、"Bash(git *)" は git * に一致する Bash 入力のサブコマンドのいずれかに対して実行され、"Edit(*.ts)" は TypeScript ファイルのみに対して実行されます。

MCP ツールをマッチ

MCP サーバー ツールはツール イベント（PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、PermissionDenied）で通常のツールとして表示されるため、他のツール名と同じ方法でマッチできます。

MCP ツールは mcp__<server>__<tool> という命名パターンに従います。例えば、

• mcp__memory__create_entities: Memory サーバーの create entities ツール
• mcp__filesystem__read_file: Filesystem サーバーの read file ツール
• mcp__github__search_repositories: GitHub サーバーの search ツール

すべてのツールをサーバーからマッチするには、サーバー プレフィックスに .* を追加します。.* は必須です。mcp__memory のようなマッチャーは文字とアンダースコアのみを含むため、完全一致として比較され、ツールにマッチしません。

• mcp__memory__.* は memory サーバーのすべてのツールにマッチ
• mcp__.*__write.* は任意のサーバーから「write」で始まるツールにマッチ

この例は、すべてのメモリ サーバー操作をログし、任意の MCP サーバーからの書き込み操作を検証します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

フック ハンドラー フィールド

内側の hooks 配列の各オブジェクトはフック ハンドラーです。マッチャーがマッチしたときに実行されるシェル コマンド、HTTP エンドポイント、MCP ツール、LLM プロンプト、またはエージェントです。5 つのタイプがあります。

• コマンド フック （type: "command"）: シェル コマンドを実行します。スクリプトはイベントのJSON 入力を stdin で受け取り、終了コードと stdout を通じて結果を通信します。
• HTTP フック （type: "http"）: イベントの JSON 入力を HTTP POST リクエストとして URL に送信します。エンドポイントは、コマンド フックと同じJSON 出力形式を使用して、レスポンス本体を通じて結果を通信します。
• MCP ツール フック （type: "mcp_tool"）: 既に接続されているMCP サーバー上のツールを呼び出します。ツールのテキスト出力はコマンド フック stdout のように扱われます。
• プロンプト フック （type: "prompt"）: Claude モデルにプロンプトを送信して、単一ターンの評価を行います。モデルは yes/no 決定を JSON として返します。プロンプト ベースのフックを参照してください。
• エージェント フック （type: "agent"）: Read、Grep、Glob などのツールを使用して条件を検証してから決定を返すことができるサブエージェントを生成します。エージェント フックは実験的であり、変更される可能性があります。エージェント ベースのフックを参照してください。

共通フィールド

これらのフィールドはすべてのフック タイプに適用されます。

if フィールドは正確に 1 つの権限ルールを保持します。ルールを組み合わせるための &&、||、またはリスト構文はありません。複数の条件を適用するには、各条件に対して個別のフック ハンドラーを定義します。Bash の場合、ルールは先頭の VAR=value 割り当てが削除された後のツール入力の各サブコマンドに対してマッチされるため、if: "Bash(git push *)" は FOO=bar git push と npm test && git push の両方にマッチします。コマンドが解析するには複雑すぎる場合、いずれかのサブコマンドがマッチすると、またはいつでもフックが実行されます。

コマンド フック フィールド

共通フィールドに加えて、コマンド フックはこれらのフィールドを受け入れます。

コマンド フックは args が設定されている場合は exec フォームで実行され、args が省略されている場合はシェル フォームで実行されます。フックがパス プレースホルダーを参照する場合は常に args を設定してください。各要素は引用符なしで 1 つの引数として渡されるためです。パイプや && などのシェル機能が必要な場合、または両方の懸念が適用されない場合は args を省略してください。

Exec フォームは args が存在する場合に実行されます。Claude Code は command を PATH 上の実行可能ファイルとして解決し、args を引数ベクトルとして直接生成します。シェルがないため、各 args 要素は記述されたとおりに正確に 1 つの引数であり、${CLAUDE_PLUGIN_ROOT} などのパス プレースホルダーは command と各 args 要素にプレーン文字列として置換されます。アポストロフィ、$、バッククォートなどの特殊文字は、シェルが解釈しないため、そのまま渡されます。プラットフォーム上でシェル トークン化は発生しません。

シェル フォームは args が存在しない場合に実行されます。command 文字列はシェルに渡されます。macOS と Linux では sh -c、Windows では Git Bash、または Git Bash がインストールされていない場合は PowerShell。shell フィールドを設定して明示的に選択します。シェルは文字列をトークン化し、変数を展開し、パイプ、&&、リダイレクト、グロブを解釈します。

この例は、プラグインにバンドルされた Node スクリプトを実行します。Exec フォームは解決されたスクリプト パスを引用符なしで 1 つの引数として渡します。

{
  "type": "command",
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]
}

同等のシェル フォームは、スペースまたは特殊文字を含むパスを処理するために引用符が必要です。

{
  "type": "command",
  "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"
}

両方のフォームは同じパス プレースホルダーをサポートし、両方とも生成されたプロセスで環境変数 CLAUDE_PROJECT_DIR、CLAUDE_PLUGIN_ROOT、CLAUDE_PLUGIN_DATA としてエクスポートするため、スクリプトは起動方法に関係なく process.env.CLAUDE_PLUGIN_ROOT を読み取ることができます。プラグイン フックは追加で ${user_config.*} 値を置換します。ユーザー設定を参照してください。

HTTP フック フィールド

共通フィールドに加えて、HTTP フックはこれらのフィールドを受け入れます。

Claude Code はフックのJSON 入力を Content-Type: application/json の POST リクエスト本体として送信します。レスポンス本体はコマンド フックと同じJSON 出力形式を使用します。

エラー処理はコマンド フックと異なります。2xx 以外のレスポンス、接続失敗、タイムアウトはすべて、実行を続行できる非ブロッキング エラーを生成します。ツール呼び出しをブロックまたは権限を拒否するには、decision: "block" または hookSpecificOutput を含む permissionDecision: "deny" を含む JSON 本体を持つ 2xx レスポンスを返します。

この例は PreToolUse イベントをローカル検証サービスに送信し、MY_TOKEN 環境変数からのトークンで認証します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

MCP ツール フック フィールド

共通フィールドに加えて、MCP ツール フックはこれらのフィールドを受け入れます。

ツールのテキスト コンテンツはコマンド フック stdout のように扱われます。有効なJSON 出力として解析される場合、決定として処理されます。そうでない場合は、プレーン テキストとして表示されます。指定されたサーバーが接続されていない場合、またはツールが isError: true を返す場合、フックは非ブロッキング エラーを生成し、実行は続行されます。

MCP ツール フックは、Claude Code が MCP サーバーに接続した後、すべてのフック イベントで利用可能です。SessionStart と Setup は通常、サーバーが接続を完了する前に発火するため、これらのイベント上のフックは最初の実行時に「接続されていない」エラーを予期する必要があります。

この例は、各 Write または Edit の後、my_server MCP サーバー上の security_scan ツールを呼び出し、編集されたファイルのパスを渡します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "my_server",
            "tool": "security_scan",
            "input": { "file_path": "${tool_input.file_path}" }
          }
        ]
      }
    ]
  }
}

プロンプト フックとエージェント フック フィールド

共通フィールドに加えて、プロンプト フックとエージェント フックはこれらのフィールドを受け入れます。

すべてのマッチング フックは並列で実行され、同一のハンドラーは自動的に重複排除されます。コマンド フックはコマンド文字列と args で重複排除され、HTTP フックは URL で重複排除されます。ハンドラーは Claude Code の環境を持つ現在のディレクトリで実行されます。$CLAUDE_CODE_REMOTE 環境変数はリモート Web 環境で "true" に設定され、ローカル CLI では設定されません。

パスでフック スクリプトを参照

フックが実行されるときの作業ディレクトリに関係なく、プロジェクトまたはプラグイン ルートを基準にしてフック スクリプトを参照するには、これらのプレースホルダーを使用します。

• ${CLAUDE_PROJECT_DIR}: プロジェクト ルート。
• ${CLAUDE_PLUGIN_ROOT}: プラグインの インストール ディレクトリ、プラグインにバンドルされたスクリプト用。プラグイン更新時に変更されます。
• ${CLAUDE_PLUGIN_DATA}: プラグインの永続データ ディレクトリ、プラグイン更新を通じて存続すべき依存関係と状態用。

パス プレースホルダーを参照するフックにはexec フォームを優先してください。Exec フォームは各 args 要素を引用符なしで 1 つの引数として渡すため、スペースまたは特殊文字を含むパスは引用符が不要です。シェル フォームでは、各プレースホルダーをダブル クォートで囲みます。

{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",
"args": []
}
]
}
]
}
}

{
"description": "Automatic code formatting",
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
"args": [],
"timeout": 30
}
]
}
]
}
}

スキルとエージェントのフック

設定ファイルとプラグインに加えて、フックはスキルとサブエージェントでフロントマターを使用して直接定義できます。これらのフックはコンポーネントのライフサイクルにスコープされ、そのコンポーネントがアクティブな場合にのみ実行されます。

すべてのフック イベントがサポートされています。サブエージェントの場合、Stop フックは自動的に SubagentStop に変換されます。これはサブエージェントが完了したときに発火するイベントです。

フックは設定ベースのフックと同じ設定形式を使用しますが、コンポーネントのライフタイムにスコープされ、完了時にクリーンアップされます。

このスキルは、各 Bash コマンドの前にセキュリティ検証スクリプトを実行する PreToolUse フックを定義します。

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

エージェントは YAML フロントマターで同じ形式を使用します。

/hooks メニュー

Claude Code で /hooks と入力して、設定されたフックの読み取り専用ブラウザーを開きます。メニューはすべてのフック イベントを表示し、設定されたフックの数を示し、マッチャーにドリルダウンでき、各フック ハンドラーの完全な詳細を表示します。これを使用して設定を検証し、フックがどの設定ファイルから定義されたかを確認するか、フックのコマンド、プロンプト、または URL を検査します。

メニューは 5 つのフック タイプをすべて表示します。command、prompt、agent、http、mcp_tool。各フックには、そのソースを示す [type] プレフィックスとソース ラベルが付けられています。

• User: ~/.claude/settings.json から
• Project: .claude/settings.json から
• Local: .claude/settings.local.json から
• Plugin: プラグインの hooks/hooks.json から
• Session: 現在のセッション用にメモリに登録
• Built-in: Claude Code によって内部的に登録

フックを選択すると、詳細ビューが開き、そのイベント、マッチャー、タイプ、ソース ファイル、および完全なコマンド、プロンプト、または URL が表示されます。メニューは読み取り専用です。フックを追加、変更、または削除するには、設定 JSON を直接編集するか、Claude にその変更を依頼してください。

フックを無効化または削除

フックを削除するには、設定 JSON ファイルからそのエントリを削除します。

すべてのフックを削除せずに一時的に無効化するには、設定ファイルで "disableAllHooks": true を設定します。個別のフックを設定に保持したまま無効化する方法はありません。

disableAllHooks 設定は管理設定階層を尊重します。管理者が管理ポリシー設定を通じてフックを設定している場合、ユーザー、プロジェクト、またはローカル設定で設定された disableAllHooks は、それらの管理フックを無効化できません。管理設定レベルで設定された disableAllHooks のみが管理フックを無効化できます。

設定ファイルのフックへの直接編集は通常、ファイル ウォッチャーによって自動的に取得されます。

フック入出力

コマンド フックは stdin 経由で JSON データを受け取り、終了コード、stdout、stderr を通じて結果を通信します。HTTP フックは同じ JSON をリクエスト本体として受け取り、HTTP レスポンス本体を通じて結果を通信します。このセクションでは、すべてのイベントに共通するフィールドと動作について説明します。フック イベントの各セクションには、その特定の入力スキーマと決定制御オプションが含まれています。

macOS と Linux では、コマンド フックは v2.1.139 以降、制御端末のない独自のセッションで実行されます。フック プロセスと子プロセスは /dev/tty を開くことも、エスケープ シーケンスを Claude Code インターフェイスに直接送信することもできません。Windows には /dev/tty がありません。任意のプラットフォームでユーザーにメッセージを表示するには、JSON 出力でsystemMessageを返します。デスクトップ通知をトリガーしたり、ウィンドウ タイトルを設定したり、ベルを鳴らしたりするには、代わりにterminalSequenceを返します。

共通入力フィールド

フック イベントは、各フック イベントセクションで説明されているイベント固有のフィールドに加えて、これらのフィールドを JSON として受け取ります。コマンド フックの場合、この JSON は stdin 経由で到着します。HTTP フックの場合、POST リクエスト本体として到着します。

--agent で実行するか、サブエージェント内で実行する場合、2 つの追加フィールドが含まれます。

SessionStart フックのみが model フィールドを受け取ります。$CLAUDE_MODEL 環境変数はありません。フック プロセスは親環境を継承するため、シェルで $ANTHROPIC_MODEL を設定した場合はそれを読み取ることができますが、セッション中に /model でモデルを切り替えるときにその値は変わりません。

例えば、Bash コマンドの PreToolUse フックは stdin で以下を受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

tool_name と tool_input フィールドはイベント固有です。各フック イベントセクションでは、そのイベントの追加フィールドについて説明しています。

終了コード出力

フック コマンドからの終了コードは、Claude Code にアクションが進行すべきか、ブロックされるべきか、無視されるべきかを伝えます。

終了 0 は成功を意味します。Claude Code は stdout をJSON 出力フィールドで解析します。JSON 出力は終了 0 でのみ処理されます。ほとんどのイベントでは、stdout はデバッグ ログに書き込まれますが、トランスクリプトには表示されません。例外は UserPromptSubmit、UserPromptExpansion、および SessionStart で、stdout は Claude が見て行動できるコンテキストとして追加されます。

終了 2 はブロッキング エラーを意味します。Claude Code は stdout とそれ内の JSON を無視します。代わりに、stderr テキストがエラー メッセージとして Claude にフィードバックされます。効果はイベントに依存します。PreToolUse はツール呼び出しをブロックし、UserPromptSubmit はプロンプトを拒否します。完全なリストについては、終了コード 2 動作を参照してください。

その他の終了コード はほとんどのフック イベントの非ブロッキング エラーです。トランスクリプトは <hook name> hook error 通知を表示し、その後に stderr の最初の行が続くため、--debug なしで原因を特定できます。実行は続行され、完全な stderr はデバッグ ログに書き込まれます。

例えば、危険な Bash コマンドをブロックするフック コマンド スクリプト。

#!/bin/bash
# stdin から JSON 入力を読み取り、コマンドをチェック
command=$(jq -r '.tool_input.command' < /dev/stdin)

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # ブロッキング エラー: ツール呼び出しが防止される
fi

exit 0  # 成功: ツール呼び出しが進行

イベントごとの終了コード 2 動作

終了コード 2 は、フックが「停止、これをしないでください」と通知する方法です。効果はイベントに依存します。一部のイベントはブロック可能なアクション（まだ発生していないツール呼び出しなど）を表し、他のイベントはすでに発生したか防止できないことを表すためです。

HTTP レスポンス処理

HTTP フックは終了コードと stdout の代わりに HTTP ステータス コードとレスポンス本体を使用します。

• 2xx で空の本体: 成功、終了コード 0 で出力なしと同等
• 2xx でプレーン テキスト本体: 成功、テキストがコンテキストとして追加
• 2xx で JSON 本体: 成功、コマンド フックと同じJSON 出力スキーマを使用して解析
• 2xx 以外のステータス: 非ブロッキング エラー、実行は続行
• 接続失敗またはタイムアウト: 非ブロッキング エラー、実行は続行

コマンド フックとは異なり、HTTP フックはステータス コードのみでブロッキング エラーを通知できません。ツール呼び出しをブロックまたは権限を拒否するには、適切な決定フィールドを含む JSON 本体を持つ 2xx レスポンスを返します。

JSON 出力

終了コードで許可またはブロックできますが、JSON 出力はより細かい制御を提供します。終了コード 2 でブロックする代わりに、終了 0 して stdout に JSON オブジェクトを出力します。Claude Code はその JSON から特定のフィールドを読み取り、ブロック、許可、またはユーザーへのエスカレーションを含む決定制御を通じた動作を制御します。

フックの stdout には JSON オブジェクトのみが含まれている必要があります。シェル プロファイルがスタートアップ時にテキストを出力する場合、JSON 解析に干渉する可能性があります。トラブルシューティング ガイドのJSON 検証に失敗を参照してください。

フック出力文字列（additionalContext、systemMessage、およびプレーン stdout を含む）は 10,000 文字でキャップされます。この制限を超える出力はファイルに保存され、プレビューとファイル パスに置き換えられます。大きなツール結果と同じ方法で処理されます。

JSON オブジェクトは 3 種類のフィールドをサポートしています。

• continue などのユニバーサル フィールドはすべてのイベント全体で機能します。これらは以下の表にリストされています。
• トップレベルの decision と reason は一部のイベントで使用され、ブロックまたはフィードバックを提供します。
• hookSpecificOutput はより豊かな制御が必要なイベント用のネストされたオブジェクトです。イベント名に設定された hookEventName フィールドが必要です。

Claude を完全に停止するには、イベント タイプに関係なく。

{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

ターミナル通知を発行

terminalSequence フィールドには Claude Code v2.1.141 以降が必要です。

フックは制御端末なしで実行されるため、エスケープ シーケンスを /dev/tty に直接書き込むことは失敗します。代わりに、エスケープ シーケンスを terminalSequence フィールドで返し、Claude Code は独自のターミナル書き込みパスを通じてそれを発行します。これはレース フリーで、tmux と GNU screen 内で機能し、/dev/tty がない Windows で機能します。

フィールドは 1 つ以上の許可リストに登録されたエスケープ シーケンスの文字列を受け入れます。

• OSC 0、1、2: ウィンドウとアイコン タイトル
• OSC 9: iTerm2、ConEmu、Windows Terminal、WezTerm 通知（9;4 タスクバー進捗を含む）
• OSC 99: Kitty 通知
• OSC 777: urxvt、Ghostty、Warp 通知
• 裸の BEL

シーケンスは BEL または ST で終了する場合があります。許可リスト外のもの（CSI カーソルと色シーケンス、OSC パレット シーケンス、OSC 8 ハイパーリンク、OSC 52 クリップボード書き込み、OSC 1337 を含む）は拒否され、フィールドは無視されます。

以下の例は Notification フックからデスクトップ通知を発火します。エスケープ シーケンスは printf 8 進数エスケープで構築されるため、制御バイトはシェル コマンド ラインに表示されず、jq -n --arg は JSON 出力を構築するため、通知メッセージの引用符、バックスラッシュ、改行は正しくエスケープされます。

#!/bin/bash
# Notification フック: Claude Code が注意を必要とするときにデスクトップに ping を送信します。
input=$(cat)
title="Claude Code'
body=$(jq -r '.message // 'Needs your attention'' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

{ "terminalSequence": "..." } の形状は、任意のシェルまたは言語から同じです。Windows では、PowerShell またはスクリプトでエスケープ文字列を構築し、同じ JSON オブジェクトを発行します。

Claude 用にコンテキストを追加

additionalContext フィールドは、フックから Claude のコンテキスト ウィンドウに文字列を渡します。Claude Code は文字列をシステム リマインダーでラップし、フックが発火した時点で会話に挿入します。Claude は次のモデル リクエストでリマインダーを読み取りますが、インターフェイスではチャット メッセージとして表示されません。

hookSpecificOutput 内でイベント名と一緒に additionalContext を返します。

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead."
  }
}

リマインダーが表示される場所はイベントに依存します。

• SessionStart、Setup、および SubagentStart: 会話の開始時、最初のプロンプトの前
• UserPromptSubmit および UserPromptExpansion: 送信されたプロンプトの横
• PreToolUse、PostToolUse、PostToolUseFailure、および PostToolBatch: ツール結果の横

複数のフックが同じイベントに対して additionalContext を返す場合、Claude はすべての値を受け取ります。値が 10,000 文字を超える場合、Claude Code はセッション ディレクトリ内のファイルに完全なテキストを書き込み、短いプレビューとファイル パスを Claude に渡します。

Claude が現在の環境の状態または実行されたばかりの操作について知っておくべき情報に additionalContext を使用します。

• 環境状態: 現在のブランチ、デプロイ ターゲット、またはアクティブな機能フラグ
• 条件付きプロジェクト ルール: 編集されたばかりのファイルに適用されるテスト コマンド、このワークツリーで読み取り専用のディレクトリ
• 外部データ: 割り当てられたオープン イシュー、最近の CI 結果、内部サービスから取得されたコンテンツ

変わらない指示については、CLAUDE.mdを優先します。スクリプトを実行せずに読み込まれ、静的なプロジェクト規約の標準的な場所です。

テキストを命令型システム指示ではなく、事実的なステートメントとして記述します。「デプロイ ターゲットは本番環境です」または「このリポジトリは bun test を使用します」などのフレーズはプロジェクト情報として読み取られます。帯域外システム コマンドとしてフレーム化されたテキストは Claude のプロンプト インジェクション防御をトリガーする可能性があり、Claude がテキストをコンテキストとして扱う代わりに表示します。

注入されたテキストはセッション トランスクリプトに保存されます。PostToolUse または UserPromptSubmit などの中盤イベントの場合、--continue または --resume で再開すると、フックを再実行する代わりに保存されたテキストが再生されるため、タイムスタンプやコミット SHA などの値は再開時に古くなります。SessionStart フックは source を "resume" に設定して再開時に再度実行されるため、コンテキストをリフレッシュできます。

決定制御

すべてのイベントが JSON を通じたブロッキングまたは動作制御をサポートしているわけではありません。サポートするイベントは、その決定を表現するために異なるフィールド セットを使用します。フックを書く前に、このテーブルをクイック リファレンスとして使用してください。

各パターンの実行例を以下に示します。

{
"decision": "block",
"reason": "Test suite must pass before proceeding"
}

{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database writes are not allowed"
}
}

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

Bash コマンド検証、プロンプト フィルタリング、自動承認スクリプトを含む拡張例については、ガイドの自動化できることとBash コマンド バリデーター リファレンス実装を参照してください。

フック イベント

各イベントは Claude Code のライフサイクル内のポイントに対応し、フックが実行できます。以下のセクションはライフサイクルに一致する順序で配置されています。セッション セットアップから agentic ループを経由してセッション終了まで。各セクションでは、イベントがいつ発火するか、サポートするマッチャー、受け取る JSON 入力、出力を通じた動作制御方法について説明しています。

SessionStart

Claude Code が新しいセッションを開始するか、既存のセッションを再開するときに実行されます。既存の問題や最近のコードベース変更など、開発コンテキストをロードしたり、環境変数をセットアップしたりするのに便利です。静的コンテキストでスクリプトが不要な場合は、代わりにCLAUDE.mdを使用してください。

SessionStart はすべてのセッションで実行されるため、これらのフックを高速に保ちます。type: "command" と type: "mcp_tool" フックのみがサポートされています。

マッチャー値はセッションがどのように開始されたかに対応しています。

SessionStart 入力

共通入力フィールドに加えて、SessionStart フックは source、model、およびオプションで agent_type を受け取ります。source フィールドはセッションがどのように開始されたかを示します。新しいセッションの場合は "startup"、再開されたセッションの場合は "resume"、/clear の後は "clear"、コンパクション後は "compact"。model フィールドはモデル識別子を含みます。claude --agent <name> で Claude Code を開始する場合、agent_type フィールドはエージェント名を含みます。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionStart",
  "source": "startup",
  "model": "claude-sonnet-4-6"
}

SessionStart 決定制御

フック スクリプトが stdout に出力するテキストは Claude のコンテキストとして追加されます。すべてのフックで利用可能なJSON 出力フィールドに加えて、これらのイベント固有のフィールドを返すことができます。

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2"
  }
}

このイベントではプレーン stdout が既に Claude に到達するため、コンテキストのみをロードするフックは JSON を構築せずに stdout に直接出力できます。suppressOutput などの他のフィールドとコンテキストを組み合わせる必要がある場合は JSON 形式を使用します。

環境変数を永続化

SessionStart フックは CLAUDE_ENV_FILE 環境変数にアクセスでき、後続の Bash コマンド用に環境変数を永続化できるファイル パスを提供します。

個別の環境変数を設定するには、export ステートメントを CLAUDE_ENV_FILE に書き込みます。他のフックで設定された変数を保持するには、追加（>>）を使用します。

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

環境からのすべての変更をキャプチャするには、セットアップ コマンドの前後でエクスポートされた変数を比較します。

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# 環境を変更するセットアップ コマンドを実行
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

このファイルに書き込まれた変数は、セッション中に Claude Code が実行するすべての後続の Bash コマンドで利用可能になります。

Setup

--init-only で Claude Code を起動するか、プリント モード（-p）で --init または --maintenance で起動するときのみ発火します。通常のスタートアップでは発火しません。CI またはスクリプトから明示的にトリガーする 1 回限りの依存関係インストールまたはスケジュール済みクリーンアップに使用します。通常のセッション スタートアップとは別です。セッションごとの初期化の場合は、代わりにSessionStartを使用してください。

マッチャー値はフックをトリガーした CLI フラグに対応しています。

--init-only は Setup フックと startup マッチャーを持つ SessionStart フックを実行してから、会話を開始せずに終了します。--init と --maintenance は -p（プリント モード）と組み合わせた場合のみ Setup フックを発火させます。対話型セッションでは、これら 2 つのフラグは現在 Setup フックを発火させません。

Setup はすべての起動で発火しないため、依存関係がインストールされている必要があるプラグインは Setup のみに依存できません。実用的なパターンは、最初の使用時に依存関係をチェックし、欠落している場合はインストールすることです。例えば、${CLAUDE_PLUGIN_DATA}/node_modules をテストし、欠落している場合は npm install を実行するフックまたはスキル。永続データ ディレクトリについては、永続データ ディレクトリを参照して、インストールされた依存関係を保存する場所を確認してください。

Setup 入力

共通入力フィールドに加えて、Setup フックは trigger フィールドを受け取ります。これは "init" または "maintenance" に設定されます。

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

Setup 決定制御

Setup フックはブロックできません。終了コード 2 では、stderr がユーザーに表示されます。その他の非ゼロ終了コードでは、stderr は --verbose で起動した場合のみ表示されます。どちらの場合も実行は続行されます。Claude のコンテキストに情報を渡すには、JSON 出力で additionalContext を返します。プレーン stdout はデバッグ ログにのみ書き込まれます。すべてのフックで利用可能なJSON 出力フィールドに加えて、これらのイベント固有のフィールドを返すことができます。

{
  "hookSpecificOutput": {
    "hookEventName": "Setup",
    "additionalContext": "Dependencies installed: node_modules, .venv"
  }
}

Setup フックは CLAUDE_ENV_FILE にアクセスできます。そのファイルに書き込まれた変数は、SessionStart フックと同じように、セッション中の後続の Bash コマンドに永続化されます。type: "command" と type: "mcp_tool" フックのみがサポートされています。

InstructionsLoaded

CLAUDE.md または .claude/rules/*.md ファイルがコンテキストにロードされるときに発火します。このイベントはセッション開始時に熱心にロードされたファイルに対して発火し、後で Claude がネストされた CLAUDE.md を含むサブディレクトリにアクセスするときなど、遅延ロードされたファイルに対して再度発火します。または paths: フロントマターを持つ条件付きルールがマッチするとき。フックはブロッキングまたは決定制御をサポートしません。観測可能性の目的で非同期に実行されます。

マッチャーは load_reason に対して実行されます。例えば、"matcher": "session_start" を使用してセッション開始時にロードされたファイルのみに対して発火するか、"matcher": "path_glob_match|nested_traversal" を使用して遅延ロードのみに対して発火します。

InstructionsLoaded 入力

共通入力フィールドに加えて、InstructionsLoaded フックはこれらのフィールドを受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "InstructionsLoaded",
  "file_path": "/Users/my-project/CLAUDE.md",
  "memory_type": "Project",
  "load_reason": "session_start"
}

InstructionsLoaded 決定制御

InstructionsLoaded フックは決定制御がありません。命令ロードをブロックまたは変更できません。このイベントを監査ログ、コンプライアンス追跡、または観測可能性に使用します。

UserPromptSubmit

ユーザーがプロンプトを送信するときに実行されます。Claude がそれを処理する前に。これにより、プロンプト/会話に基づいて追加コンテキストを追加したり、プロンプトを検証したり、特定のタイプのプロンプトをブロックしたりできます。

UserPromptSubmit フックは command、http、mcp_tool タイプのデフォルト タイムアウトが 30 秒で、他のイベントでのこれらのタイプの 600 秒のデフォルトより短くなっています。このフックはすべてのプロンプトの前に実行され、モデル処理がそれが完了するまでブロックされるため、スタックしたフックはセッションを停止させます。フックにより多くの時間が必要な場合は、フック エントリで timeout フィールドを設定します。

UserPromptSubmit 入力

共通入力フィールドに加えて、UserPromptSubmit フックはユーザーが送信したテキストを含む prompt フィールドを受け取ります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

UserPromptSubmit 決定制御

UserPromptSubmit フックは、ユーザー プロンプトが処理されるかどうかを制御し、コンテキストを追加できます。すべてのJSON 出力フィールドが利用可能です。

終了コード 0 で会話にコンテキストを追加する 2 つの方法があります。

• プレーン テキスト stdout: stdout に書き込まれた JSON 以外のテキストはコンテキストとして追加されます
• additionalContext を含む JSON: より多くの制御のために以下の JSON 形式を使用します。additionalContext フィールドはコンテキストとして追加されます

プレーン stdout はトランスクリプトのフック出力として表示されます。additionalContext フィールドはより慎重に追加されます。

プロンプトをブロックするには、decision を "block" に設定した JSON オブジェクトを返します。

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here",
    "sessionTitle": "My session title"
  }
}

UserPromptExpansion

ユーザーが入力したスラッシュ コマンドが Claude に到達する前にプロンプトに展開されるときに実行されます。特定のコマンドを直接呼び出しからブロックしたり、特定のスキルのコンテキストを注入したり、ユーザーが呼び出すコマンドをログしたりするのに使用します。例えば、deploy にマッチするフックは、承認ファイルが存在しない限り /deploy をブロックできます。または、レビュー スキルにマッチするフックはチームのレビュー チェックリストを additionalContext として追加できます。

このイベントは PreToolUse がカバーしないパスをカバーします。PreToolUse フックが Skill ツールにマッチするのは Claude がツールを呼び出すときのみですが、/skillname を直接入力すると PreToolUse をバイパスします。UserPromptExpansion はその直接パスで発火します。

command_name でマッチします。マッチャーを空のままにして、すべてのプロンプト タイプのスラッシュ コマンドで発火します。

UserPromptExpansion 入力

共通入力フィールドに加えて、UserPromptExpansion フックは expansion_type、command_name、command_args、command_source、および元の prompt 文字列を受け取ります。expansion_type フィールドはスキルとカスタム コマンドの場合は slash_command、MCP サーバー プロンプトの場合は mcp_prompt です。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../00893aaf.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptExpansion",
  "expansion_type": "slash_command",
  "command_name": "example-skill",
  "command_args": "arg1 arg2",
  "command_source": "plugin",
  "prompt": "/example-skill arg1 arg2"
}

UserPromptExpansion 決定制御

UserPromptExpansion フックは展開をブロックするか、コンテキストを追加できます。すべてのJSON 出力フィールドが利用可能です。

{
  "decision": "block",
  "reason": "This slash command is not available",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptExpansion",
    "additionalContext": "Additional context for this expansion"
  }
}

PreToolUse

Claude がツール パラメーターを作成した後、ツール呼び出しを処理する前に実行されます。ツール名でマッチします。Bash、Edit、Write、Read、Glob、Grep、Agent、WebFetch、WebSearch、AskUserQuestion、ExitPlanMode、および任意のMCP ツール名。

PreToolUse 決定制御を使用して、ツールの使用を許可、拒否、質問、または遅延します。

PreToolUse 入力

共通入力フィールドに加えて、PreToolUse フックは tool_name、tool_input、tool_use_id を受け取ります。tool_input フィールドはツールに依存します。

Bash

シェル コマンドを実行します。

Write

ファイルを作成または上書きします。

Edit

既存ファイル内の文字列を置換します。

Read

ファイル コンテンツを読み取ります。

Glob

グロブ パターンにマッチするファイルを検索します。

Grep

正規表現でファイル コンテンツを検索します。

WebFetch

Web コンテンツを取得して処理します。

WebSearch

Web を検索します。

Agent

サブエージェントを生成します。

PostToolUse では、完了した Agent 呼び出しの tool_response はサブエージェントの最終テキストと使用テレメトリを含みます。フックからサブエージェント単位のコストを記録するためにこれらのフィールドを読み取ります。

run_in_background: true 呼び出しの場合、ツールはサブエージェント起動後すぐに返されるため、tool_response は使用フィールドを含みません。status: "async_launched"、agentId、description、prompt、outputFile を含みます。

AskUserQuestion

ユーザーに 1 つから 4 つの複数選択肢の質問をします。

ExitPlanMode

Claude がプラン モードを離れる前にプランを提示し、ユーザーに承認を求めます。Claude はツールを呼び出す前にプランをディスク上のファイルに書き込むため、モデルからのリテラル tool_input は allowedPrompts のみを含みます。Claude Code はプラン コンテンツとファイル パスをフックに渡す前に注入します。

PostToolUse では、tool_response は plan と filePath フィールドを含むオブジェクトで、承認されたプランと内部ステータス フラグを保持します。ディスクからファイルを再度読み取るのではなく、tool_response.plan でプラン コンテンツを読み取ります。

PreToolUse 決定制御

PreToolUse フックはツール呼び出しが進行するかどうかを制御できます。トップレベル decision フィールドを使用する他のフックとは異なり、PreToolUse は hookSpecificOutput オブジェクト内に決定を返します。これにより、より豊かな制御が可能になります。4 つの結果（許可、拒否、質問、遅延）と、実行前にツール入力を変更する機能。

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

フックが "ask" を返すと、ユーザーに表示される権限プロンプトには、フックの出所を識別するラベルが含まれます。例えば、[User]、[Project]、[Plugin]、または [Local]。これにより、ユーザーはどの設定ソースが確認を要求しているかを理解できます。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

AskUserQuestion と ExitPlanMode はユーザー操作が必要で、通常は非対話型モードで -p フラグでブロックします。permissionDecision: "allow" を updatedInput と一緒に返すことでその要件を満たします。フックは stdin からツールの入力を読み取り、独自の UI を通じて回答を収集し、ツールがプロンプトなしで実行されるように updatedInput で返します。"allow" のみを返すことはこれらのツールには十分ではありません。AskUserQuestion の場合、元の questions 配列をエコーバックし、各質問のテキストを選択された回答にマップする answers オブジェクトを追加します。

ツール呼び出しを後で再開するために遅延

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

AskUserQuestion ツールが典型的なケースです。Claude はユーザーに何かを尋ねたいのですが、応答するターミナルがありません。ラウンド トリップは次のように機能します。

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. フックは permissionDecision: "allow" を返し、updatedInput に回答を含めます。ツールが実行され、Claude が続行します。

deferred_tool_use フィールドはツールの id、name、input を含みます。input は実行前にキャプチャされたツール呼び出しのパラメーターです。

{
  "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 }] }
  }
}

タイムアウトまたは再試行制限はありません。セッションはディスク上に残ります。回答の準備ができていないときに再開する場合、フックは再度 "defer" を返すことができ、プロセスは同じ方法で終了します。呼び出しプロセスはループを破るタイミングを制御し、最終的に "allow" または "deny" を返します。

"defer" は Claude が単一のツール呼び出しを行うときのみ機能します。Claude が一度に複数のツール呼び出しを行う場合、"defer" は警告で無視され、ツールは通常の権限フローを通じて進行します。制約が存在するのは、再開が 1 つのツールのみを再実行できるためです。バッチから 1 つの呼び出しを遅延させる方法はなく、他の呼び出しは未解決のままになります。

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

PermissionRequest

ユーザーに権限ダイアログが表示されるときに実行されます。 PermissionRequest 決定制御を使用して、ユーザーに代わって許可または拒否します。

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

PermissionRequest 入力

PermissionRequest フックは PreToolUse フックのような tool_name と tool_input フィールドを受け取りますが、tool_use_id はありません。オプションの permission_suggestions 配列には、ユーザーが通常権限ダイアログで見る「常に許可」オプションが含まれています。違いはフックが発火するタイミングです。PermissionRequest フックはユーザーに権限ダイアログが表示されようとしているときに実行され、PreToolUse フックは権限ステータスに関係なくツール実行前に実行されます。

{
  "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 オブジェクトを返すことができます。

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

権限更新エントリ

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

すべてのエントリの destination フィールドは、変更がメモリに留まるか設定ファイルに永続化されるかを決定します。

フックは受け取った permission_suggestions の 1 つを独自の updatedPermissions 出力として反映できます。これは、ユーザーがダイアログで「常に許可」オプションを選択するのと同等です。

PostToolUse

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

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

PostToolUse 入力

PostToolUse フックはツールがすでに正常に実行された後に発火します。入力には、ツールに送信された引数である tool_input と、返された結果である tool_response の両方が含まれます。両方の正確なスキーマはツールに依存します。

{
  "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",
    "success": true
  },
  "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
    }
  }
}

PostToolUseFailure

ツール実行が失敗するときに実行されます。このイベントはエラーをスロー、または失敗結果を返すツール呼び出しに対して発火します。これを使用して失敗をログ、アラートを送信、または Claude に是正フィードバックを提供します。

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

PostToolUseFailure 入力

PostToolUseFailure フックは PostToolUse と同じ tool_name と tool_input フィールドを受け取り、エラー情報をトップレベル フィールドとして受け取ります。

{
  "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": "Command exited with non-zero status code 1",
  "is_interrupt": false,
  "duration_ms": 4187
}

PostToolUseFailure 決定制御

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

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

PostToolBatch

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

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\n     2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\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 を返すと、次のモデル呼び出しの前に agentic ループが停止します。

PermissionDenied

自動モード分類器がツール呼び出しを拒否するときに実行されます。このフックは自動モードでのみ発火します。手動で権限ダイアログを拒否するとき、PreToolUse フックがコールをブロックするとき、または deny ルールがマッチするときは実行されません。これを使用して分類器の拒否をログ、設定を調整、またはモデルがツール呼び出しを再試行できることを伝えます。

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

PermissionDenied 入力

共通入力フィールドに加えて、PermissionDenied フックは tool_name、tool_input、tool_use_id、reason を受け取ります。

{
  "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": "Auto mode denied: command targets a path outside the project"
}

PermissionDenied 決定制御

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

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

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

Notification

Claude Code が通知を送信するときに実行されます。通知タイプでマッチします。permission_prompt、idle_prompt、auth_success、elicitation_dialog、elicitation_complete、elicitation_response。マッチャーを省略して、すべての通知タイプのフックを実行します。

異なるマッチャーを使用して、通知タイプに応じて異なるハンドラーを実行します。この設定は、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 to use Bash",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Notification フックは通知をブロックまたは変更できません。これらは副作用（外部サービスへの通知の転送など）を目的としています。すべてのフックで利用可能なJSON 出力フィールド（systemMessage など）が適用されます。

SubagentStart

Agent ツール経由でサブエージェントが生成されるときに実行されます。エージェント タイプ名でフィルタリングするマッチャーをサポート（general-purpose、Explore、Plan などの組み込みエージェント、またはカスタム サブエージェントの場合はエージェントのフロントマターの name フィールド。ファイル名ではありません）。

SubagentStart 入力

共通入力フィールドに加えて、SubagentStart フックはサブエージェントの一意の識別子を含む agent_id とエージェント名を含む agent_type（"general-purpose"、"Explore"、"Plan" などの組み込みエージェント、またはカスタム エージェント名）を受け取ります。

{
  "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"
  }
}

SubagentStop

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

SubagentStop 入力

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

{
  "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..."
}

SubagentStop フックはStop フックと同じ決定制御形式を使用します。additionalContext をサポートしません。decision: "block" を reason と一緒に返すとサブエージェントを実行し続け、reason をサブエージェントの次の命令として配信します。サブエージェントが戻った後に親セッションにコンテキストを注入するには、代わりに Agent ツール上の PostToolUseフックを使用します。

TaskCreated

タスクが TaskCreate ツール経由で作成されるときに実行されます。命名規則を実施したり、タスク説明を要求したり、特定のタスクが作成されるのを防いだりするのに使用します。

TaskCreated フックが終了コード 2 で終了すると、タスクは作成されず、stderr メッセージはモデルへのフィードバックとしてフィードバックされます。チームメイト全体を停止する代わりに再実行するには、{"continue": false, "stopReason": "..."} を含む JSON を返します。TaskCreated フックはマッチャーをサポートせず、すべての出現で発火します。

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/...",
  "permission_mode": "default",
  "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": "my-project"
}

TaskCreated 決定制御

TaskCreated フックはタスク作成を制御する 2 つの方法をサポートしています。

• 終了コード 2: タスクは作成されず、stderr メッセージはモデルへのフィードバックとしてフィードバックされます。
• JSON {"continue": false, "stopReason": "..."}: チームメイト全体を停止し、Stop フック動作と一致します。stopReason はユーザーに表示されます。

この例は、タスク件名が必要な形式に従わない場合、タスク作成をブロックします。

#!/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 ツール経由でタスクを明示的に完了としてマークするとき、またはエージェント チームチームメイトが進行中のタスクでターンを終了するとき。これを使用してチームメイトが作業を停止する前に品質ゲートを実施します。例えば、lint チェックの合格を要求したり、出力ファイルが存在することを確認したりします。

TaskCompleted フックが終了コード 2 で終了すると、タスクは完了としてマークされず、stderr メッセージはモデルへのフィードバックとしてフィードバックされます。チームメイト全体を停止する代わりに再実行するには、{"continue": false, "stopReason": "..."} を含む JSON を返します。TaskCompleted フックはマッチャーをサポートせず、すべての出現で発火します。

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": "my-project"
}

TaskCompleted 決定制御

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

• 終了コード 2: タスクは完了としてマークされず、stderr メッセージはモデルへのフィードバックとしてフィードバックされます。
• JSON {"continue": false, "stopReason": "..."}: チームメイト全体を停止し、Stop フック動作と一致します。stopReason はユーザーに表示されます。

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

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

# テスト スイートを実行
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 を受け取ります。stop_hook_active フィールドは、Claude Code がすでに stop フックの結果として続行している場合は true です。この値をチェックするか、Claude Code が無限に実行されるのを防ぐためにトランスクリプトを処理します。last_assistant_message フィールドは Claude の最終応答のテキスト コンテンツを含むため、フックはトランスクリプト ファイルを解析せずにアクセスできます。

{
  "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..."
}

Stop 決定制御

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

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

StopFailure

Stopの代わりに、ターンが API エラーのために終了するときに実行されます。出力と終了コードは無視されます。Claude が API エラーのため応答を完了できない場合、失敗をログ、アラートを送信、または回復アクションを実行するのに使用します。

StopFailure 入力

共通入力フィールドに加えて、StopFailure フックは error、オプションの error_details、およびオプションの last_assistant_message を受け取ります。error フィールドはエラー タイプを識別し、マッチャー フィルタリングに使用されます。

{
  "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

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

TeammateIdle フックが終了コード 2 で終了すると、チームメイトは stderr メッセージをフィードバックとして受け取り、アイドル状態になる代わりに作業を続行します。チームメイト全体を停止する代わりに再実行するには、{"continue": false, "stopReason": "..."} を含む JSON を返します。TeammateIdle フックはマッチャーをサポートせず、すべての出現で発火します。

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": "my-project"
}

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

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

ConfigChange フックは設定ファイル、管理ポリシー設定、スキル ファイルの変更に対して発火します。入力の source フィールドは、どのタイプの設定が変更されたかを示し、オプションの file_path フィールドは変更されたファイルへのパスを提供します。

マッチャーは設定ソースでフィルタリングします。

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

{
  "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 ソースに対して引き続き発火するため、監査ログに使用できますが、ブロッキング決定は無視されます。これにより、エンタープライズ管理設定が常に有効になることが保証されます。

CwdChanged

セッション中に作業ディレクトリが変更されるときに実行されます。例えば、Claude が cd コマンドを実行するとき。これを使用してディレクトリ変更に反応します。環境変数をリロードしたり、プロジェクト固有のツールチェーンをアクティブにしたり、セットアップ スクリプトを自動的に実行したりします。FileChangedとペアになり、direnvなどのツール用に、ディレクトリごとの環境を管理します。

CwdChanged フックは CLAUDE_ENV_FILE にアクセスできます。そのファイルに書き込まれた変数は、SessionStart フックと同じように、セッション中の後続の Bash コマンドに永続化されます。

CwdChanged はマッチャーをサポートせず、すべてのディレクトリ変更で発火します。

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 フックは決定制御がありません。ディレクトリ変更をブロックできません。

FileChanged

監視されたファイルがディスク上で変更されるときに実行されます。プロジェクト設定ファイルが変更されたときに環境変数をリロードするのに便利です。

このイベントの matcher は 2 つの役割を果たします。

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

FileChanged フックは CLAUDE_ENV_FILE にアクセスできます。そのファイルに書き込まれた変数は、SessionStart フックと同じように、セッション中の後続の 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 フックは決定制御がありません。ファイル変更をブロックできません。

WorktreeCreate

claude --worktree を実行するか、サブエージェントが isolation: "worktree" を使用する場合、Claude Code は git worktree を使用して分離された作業コピーを作成します。WorktreeCreate フックを設定する場合、デフォルトの git 動作を置き換え、SVN、Perforce、Mercurial などの別のバージョン管理システムを使用できます。

フックは作成されたワークツリー ディレクトリへの絶対パスを返す必要があります。Claude Code はこのパスを分離されたセッションの作業ディレクトリとして使用します。コマンド フックは stdout にパスを出力します。HTTP フックは hookSpecificOutput.worktreePath 経由で返します。

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

この例は 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 入力からワークツリー name を読み取り、新しいディレクトリに新しいコピーをチェックアウトし、ディレクトリ パスを出力します。最後の行の echo は Claude Code が読み取るワークツリー パスです。他の出力を stderr にリダイレクトして、パスに干渉しないようにします。

WorktreeCreate 入力

共通入力フィールドに加えて、WorktreeCreate フックは name フィールドを受け取ります。これは新しいワークツリーのスラッグ識別子で、ユーザーが指定するか自動生成されます（例えば、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 フックは標準的な許可/ブロック決定モデルを使用しません。代わりに、フックの成功または失敗が結果を決定します。フックは作成されたワークツリー ディレクトリへの絶対パスを返す必要があります。

• コマンド フック (type: "command"): stdout にパスを出力します。
• HTTP フック (type: "http"): レスポンス本体で { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } を返します。

フックが失敗するか出力を生成しない場合、ワークツリー作成はエラーで失敗します。

WorktreeRemove

WorktreeCreateのクリーンアップ対応。このフックはワークツリーが削除されるときに発火します。--worktree セッションを終了して削除を選択するか、isolation: "worktree" を持つサブエージェントが完了するとき。git ベースのワークツリーの場合、Claude は git worktree remove で自動的にクリーンアップを処理します。git 以外のバージョン管理システムの WorktreeCreate フックを設定した場合、クリーンアップを処理するために WorktreeRemove フックとペアにします。なければ、ワークツリー ディレクトリはディスク上に残ります。

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

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

WorktreeRemove 入力

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

{
  "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 フックは決定制御がありません。ワークツリー削除をブロックできませんが、バージョン管理状態の削除やアーカイブ変更などのクリーンアップ タスクを実行できます。フック失敗はデバッグ モードでのみログされます。

PreCompact

Claude Code がコンパクション操作を実行しようとしている前に実行されます。

マッチャー値は、コンパクションが手動でトリガーされたか自動的にトリガーされたかを示します。

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

自動コンパクションのブロックは、いつ発火するかに応じて異なる効果があります。コンテキスト制限の前にコンパクションがプロアクティブにトリガーされた場合、Claude Code はそれをスキップし、会話は非圧縮で続行されます。コンテキスト制限エラーから回復するためにコンパクションがトリガーされた場合、基礎となるエラーが表示され、現在のリクエストが失敗します。

PreCompact 入力

共通入力フィールドに加えて、PreCompact フックは trigger と custom_instructions を受け取ります。manual の場合、custom_instructions はユーザーが /compact に渡すものを含みます。auto の場合、custom_instructions は空です。

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

PostCompact

Claude Code がコンパクション操作を完了した後に実行されます。このイベントを使用して、新しいコンパクト状態に反応します。例えば、生成されたサマリーをログしたり、外部状態を更新したりします。

PreCompact と同じマッチャー値が適用されます。

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 フックは決定制御がありません。コンパクション結果に影響を与えることはできませんが、フォローアップ タスクを実行できます。

SessionEnd

Claude Code セッションが終了するときに実行されます。クリーンアップ タスク、セッション統計のログ、またはセッション状態の保存に便利です。終了理由でフィルタリングするマッチャーをサポートします。

フック入力の 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 フックは決定制御がありません。セッション終了をブロックできませんが、クリーンアップ タスクを実行できます。

SessionEnd フックのデフォルト タイムアウトは 1.5 秒です。これはセッション終了、/clear、およびインタラクティブ /resume 経由でのセッション切り替えに適用されます。フックにより多くの時間が必要な場合は、フック設定でフックごとの timeout を設定します。全体的な予算は、設定ファイルで設定されたフックごとのタイムアウトの最高値に自動的に引き上げられ、最大 60 秒です。プラグイン提供のフックに設定されたタイムアウトは予算を引き上げません。予算を明示的にオーバーライドするには、CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 環境変数をミリ秒単位で設定します。

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Elicitation

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

マッチャー フィールドは 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/...",
  "permission_mode": "default",
  "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/...",
  "permission_mode": "default",
  "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 を拒否し、stderr をユーザーに表示します。

ElicitationResult

ユーザーが MCP elicitation に応答した後に実行されます。フックは応答を観察、変更、またはブロックしてから、MCP サーバーに送り返すことができます。

マッチャー フィールドは 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/...",
  "permission_mode": "default",
  "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 に変更します。

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

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

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

• PermissionRequest
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• UserPromptExpansion
• UserPromptSubmit

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

• ConfigChange
• CwdChanged
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• Notification
• PermissionDenied
• PostCompact
• PreCompact
• SessionEnd
• StopFailure
• SubagentStart
• TeammateIdle
• WorktreeCreate
• WorktreeRemove

SessionStart と Setup は command と mcp_tool フックをサポートしています。これらは http、prompt、agent フックをサポートしていません。

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

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

1. フック入力とプロンプトを Claude モデル（デフォルトは Haiku）に送信
2. LLM は決定を含む構造化 JSON で応答
3. Claude Code は決定を自動的に処理

プロンプト フック設定

type を "prompt" に設定し、command の代わりに prompt 文字列を提供します。$ARGUMENTS プレースホルダーを使用して、フックの JSON 入力データをプロンプト テキストに注入します。Claude Code は結合されたプロンプトと入力を高速 Claude モデルに送信し、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"
}

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

• Stop と SubagentStop：理由は Claude の次の指示としてフィードバックされ、ターンが続行されます
• PreToolUse：ツール呼び出しが拒否され、理由は Claude にツール エラーとして返されます。これはコマンド フックの permissionDecision: "deny" と同等です
• PostToolUse：デフォルトではターンが終了し、理由は警告行としてチャットに表示されます。continueOnBlock: true を設定して、理由を Claude にフィードバックし、ターンを続行する代わりに使用します
• PostToolBatch、UserPromptSubmit、UserPromptExpansion：ターンが終了し、理由は警告行として表示されます。これらのイベントは continue に関係なく decision: "block" でターンを終了します
• PostToolUseFailure、TaskCreated、TaskCompleted：理由は Claude にツール エラーとして返されます。PreToolUse と同様です
• PermissionRequest：ok: false は効果がありません。フックから承認を拒否するには、コマンド フックを使用して hookSpecificOutput.decision.behavior: "deny" を返します

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

例：マルチ基準 Stop フック

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

{
  "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 呼び出しの代わりに、エージェント フックはサブエージェントを生成し、ファイルを読み取り、コードを検索し、コードベースを検査して条件を検証できます。エージェント フックはプロンプト ベースのフックと同じイベントをサポートしています。

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

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

1. Claude Code はプロンプトとフックの JSON 入力を持つサブエージェントを生成します
2. サブエージェントは Read、Grep、Glob などのツールを使用して調査できます
3. 最大 50 ターン後、サブエージェントは構造化 { "ok": true/false } 決定を返します
4. Claude Code はプロンプト フックと同じ方法で決定を処理します

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

エージェント フック設定

type を "agent" に設定し、prompt 文字列を提供します。設定フィールドはプロンプト フックと同じですが、より長いデフォルト タイムアウトです：

レスポンス スキーマはプロンプト フックと同じです：許可するには { "ok": true } を、ブロックするには { "ok": false, "reason": "..." } を返します。

この 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 ツール呼び出しの後にテスト スクリプトを実行します。Claude は run-tests.sh が最大 120 秒間実行されている間、すぐに作業を続行します。スクリプトが完了すると、その出力は次の会話ターンで配信されます。

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

timeout フィールドはバックグラウンド プロセスの最大時間（秒単位）を設定します。指定されない場合、非同期フックは同期フックと同じ 10 分のデフォルトを使用します。

非同期フックの実行方法

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

バックグラウンド プロセスが終了した後、フックが additionalContext フィールドを含む JSON レスポンスを生成した場合、そのコンテンツは次の会話ターンで Claude にコンテキストとして配信されます。systemMessage フィールドは Claude ではなく、あなたに表示されます。

非同期フック完了通知はデフォルトで抑制されます。これらを表示するには、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,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

制限事項

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

• async をサポートするのは type: "command" フックのみです。プロンプト ベースのフックは非同期で実行できません。
• 非同期フックはツール呼び出しをブロックまたは決定を返すことができません。フックが完了するまでに、トリガーするアクションはすでに進行しています。
• フック出力は次の会話ターンで配信されます。セッションがアイドル状態の場合、レスポンスは次のユーザー操作まで待機します。例外: asyncRewake フックが終了コード 2 で終了すると、セッションがアイドル状態でも Claude を直ちに起動します。
• 各実行は個別のバックグラウンド プロセスを作成します。同じ非同期フックの複数の発火全体で重複排除はありません。

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

免責事項

コマンド フックはシステム ユーザーの完全な権限で実行されます。

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

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

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

Windows PowerShell ツール

Windows では、コマンド フックで "shell": "powershell" を設定することで、個別のフックを PowerShell で実行できます。フックは PowerShell を直接生成するため、CLAUDE_CODE_USE_POWERSHELL_TOOL が設定されているかどうかに関係なく機能します。Claude Code は pwsh.exe（PowerShell 7 以上）を自動検出し、powershell.exe（5.1）にフォールバックします。

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

フックをデバッグ

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

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 600000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

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

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