フックのリファレンス

フック（hook）は、Claude Code のライフサイクルの決まった時点で自動実行される、ユーザー定義のシェルコマンド・HTTP エンドポイント・MCP ツール呼び出し・LLM プロンプト・サブエージェントです。ターミナル・IDE 拡張・デスクトップアプリ・クラウドセッションのどこで動かしても、同じフックイベントが発火します。このページは、イベントのスキーマ・設定のオプション・JSON の入出力・非同期や HTTP などの応用機能の引き先です。クイックスタートと実例はフックの使い方にあります。

プラグインは、フックを、Claude Code が自分のプロセスの中で呼ぶ JavaScript の関数としても登録でき、イベントに反応するだけでなく画面にも描けます。そうしたプラグインが Mod（モッド）で、関数のフックはこのページではなく Mod のリファレンスで扱います。このページのフックは、Mod と並んで引き続き動きます。

要点#

• 設定は「イベント → matcher グループ → ハンドラー」の3段の入れ子
• ハンドラーは command・http・mcp_tool・prompt・agent の5種類
• 一致したハンドラーは並行して動く。同じハンドラーを複数の設定ファイルに書いても1回だけ動く
• 終了コード 2 でブロックでき、終了コード 0 と JSON で細かく制御できる
• 決定の書き方はイベントごとに違う（このページの「決定の制御」の表）

ライフサイクルとイベントの一覧#

イベントが発火して matcher が一致すると、Claude Code はそのイベントの JSON の文脈をハンドラーに渡します。コマンドフックでは stdin、HTTP フックでは POST のリクエストボディです。ハンドラーは入力を調べ、処理をして、必要なら判定を返します。

イベントの発火の頻度は3種類です。

• セッションごと：SessionStart と SessionEnd
• ターンごと：UserPromptSubmit・Stop・StopFailure
• エージェントのループ内のツール呼び出しごと：PreToolUse と PostToolUse（EndConversation の呼び出しはどちらも飛ばす）

フックが解決される流れ#

破壊的なシェルコマンドをブロックする PreToolUse フックの例です。

matcher で Bash のツール呼び出しに絞り、if でさらに rm * に一致する Bash のサブコマンドに絞るので、block-rm.sh は両方に一致したときだけ起動します（macOS・Linux）。

{
  "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" にして返します。プロジェクトの .claude/hooks/block-rm.sh に保存し、chmod +x で実行権限を付けます。

#!/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  # no decision; normal permission flow applies
fi

Windows（PowerShell）では、matcher を Bash|PowerShell にして、PowerShell ツールも対象にします。1つの if ルールは1つのツールの呼び出しにしか一致しないので、ツールごとにハンドラーを分けます（Bash 用は Bash(rm *)、PowerShell 用は PowerShell(Remove-Item *)）。どちらも同じスクリプトを powershell.exe で動かします。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          },
          {
            "type": "command",
            "if": "PowerShell(Remove-Item *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          }
        ]
      }
    ]
  }
}

-NoProfile は PowerShell のプロファイルを読み込まずフックを速く起動し、-ExecutionPolicy Bypass はローカルのスクリプトファイルを実行できるようにします。

# .claude/hooks/block-rm.ps1
$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
$command = $callInput.tool_input.command

if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
  @{
    hookSpecificOutput = @{
      hookEventName = "PreToolUse"
      permissionDecision = "deny"
      permissionDecisionReason = "Destructive command blocked by hook"
    }
  } | ConvertTo-Json
} else {
  exit 0  # no decision; normal permission flow applies
}

macOS・Linux の設定で、Claude Code が Bash "rm -rf /tmp/build" を実行しようとしたときの流れは次のとおりです。

1. イベントの発火：PreToolUse が発火し、ツールの入力が JSON で stdin に渡る（{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }）
2. matcher の判定："Bash" がツール名に一致し、このフックグループが有効になる。matcher を省くか "*" にすると、グループはそのイベントの発生のたびに有効になる
3. if の判定："Bash(rm *)" は、rm -rf /tmp/build が rm * に一致するサブコマンドなので一致し、このハンドラーが起動する。npm test だったら if が一致せず、block-rm.sh は起動せず、プロセス起動のコストも避けられる。if は任意で、無ければ一致したグループのハンドラーはすべて動く
4. ハンドラーの実行：スクリプトが全コマンドを調べて rm -rf を見つけ、判定を stdout に出す。rm file.txt のように安全な rm なら exit 0 に当たる。終了コード 0 で出力が無いときは、フックは報告する判定が無いということで、ツール呼び出しは通常の権限の流れを進む。フックは呼び出しを拒否できるが、黙っているのは承認ではない
5. 結果の反映：Claude Code が JSON の判定を読み、ツール呼び出しをブロックして、理由を Claude に見せる

設定#

フックは JSON の設定ファイルで定義します。設定は3段の入れ子です。

1. 応答するフックイベントを選ぶ（PreToolUse・Stop など）
2. 発火の条件を絞る matcher グループを足す（「Bash ツールのときだけ」など）
3. 一致したときに動くフックハンドラーを1つ以上定義する

フックの置き場所#

• クラウドセッションは、手元の ~/.claude/settings.json を読みません。セルフホスト環境では、運用者がランナーホストの ~/.claude/ から入れたフックと、ランナーイメージの管理設定ファイルのフックも動きます（管理設定のその層が適用される場合）。クラウドセッションにどの設定とプラグインが届くかは、クラウド（Web）を参照してください
• 設定ファイル・管理ポリシー設定・プラグインのフックは、サブエージェントの中でも動きます。サブエージェントがツールを呼ぶと、PreToolUse や PostToolUse などのツールイベントが、メインの会話と同じ設定のフックを発火し、入力にはサブエージェントを識別する agent_id と agent_type が入ります
• 管理者は、管理設定の allowManagedHooksOnly で、動かせるフックを制限できます
  • user・project・local・プラグインのフックがブロックされる（管理設定の enabledPlugins で強制有効にしたプラグインのフックは除く）
  • statusLine・fileSuggestion・subagentStatusLine の設定も管理設定に限られる
  • command ソースのプラグインも、disableCommandPluginSources を明示的に false にしない限り無効になる（管理設定の enabledPlugins で強制有効にしたものを含む）。command ソースは v2.1.229 以降
  • マーケットプレイスの headersHelper コマンドも、disableCommandPluginSources を明示的に false にしない限りブロックされる（管理設定自身が宣言したマーケットプレイスは除く）
• フックのエントリは、設定の階層をまたいで置き換えられず統合されます。user・project・local の設定は管理設定のフックを消さずに自分のフックを足し、disableAllHooks は管理設定の外から管理フックを無効にできません
• HTTP フックの許可リストは、管理ポリシー設定を含むすべての元のフックに適用されます
  • allowedHttpHookUrls：どの設定の階層でも定義されていると、統合した許可リストに URL が一致する HTTP ハンドラーだけが動く
  • httpHookAllowedEnvVars：定義されていると、そのリストの環境変数だけがフックのヘッダーに展開される

matcher のパターン#

matcher フィールドで、フックが発火する条件を絞ります。評価のしかたは、含まれる文字で決まります。

• 正規表現の経路の matcher は、JavaScript の RegExp.prototype.test で評価され、値のどこかに一致すれば成功します。Edit.* は Edit と NotebookEdit の両方に一致します。全体一致が要るときは、^Edit$ のように ^ と $ で囲みます
• FileChanged と StopFailure は、英字・数字・_・| だけの、より狭い完全一致の集合を使います。この2つのイベントで、ハイフン・空白・カンマを matcher に入れると、正規表現の経路になり、選択肢を区切れるのは | だけです。以下の表にある、matcher に対応するほかのイベントは、| か , を受け付けます
• FileChanged は、監視リストを作るときにはこれらの規則に従いません（FileChanged の節を参照）
• matcher を、matcher に対応しないイベントに足しても、黙って無視されます

イベントごとに、matcher が見るフィールドは違います。

• StopFailure を cloud_credential_error で一致させるには、v2.1.267 以降が必要です。認証情報の読み込みの失敗を、server_error や unknown ではなくこの値で報告する最初の版です
• ほとんどのイベントでは、Claude Code は stdin で送る JSON 入力のフィールドに対して matcher を評価します。ツールのイベントでは tool_name です。PreModelSwitch と PostModelSwitch では、to_model から導いた正規名に対して評価します

Claude が書き込みや編集をしたときだけ、lint のスクリプトを動かす例：

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

ツールのイベントでは、個々のハンドラーの if フィールドでさらに絞れます。if は権限ルールの構文で、ツール名と引数をあわせて照合します。"Bash(git *)" は Bash の入力のどれかのサブコマンドが git * に一致したときに動き、"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 サーバーの検索ツール

サーバーの全ツールに一致させるには、サーバーの接頭辞に .* を付けます。.* は必須です。mcp__memory や mcp__brave-search のような matcher は完全一致の文字だけで、文字列として完全一致で比べられ、どのツールにも一致しません。

• mcp__memory__.* は memory サーバーの全ツールに一致する
• mcp__brave-search__.* は、名前にハイフンを含むサーバーの全ツールに一致する
• mcp__.*__write.* は、どのサーバーでも、名前が write で始まるツールに一致する

プラグインに同梱された MCP サーバーのツールは、プラグイン名を含むスコープ付きのサーバー部分を使い、mcp__plugin_<plugin-name>_<server-name>__<tool> の形です。素のサーバーキーで書いた matcher は、これらのツールでは発火しません。my-plugin が db というキーでサーバーを同梱していれば、query ツールは mcp__plugin_my-plugin_db__query で、そのサーバーの全ツールの matcher は mcp__plugin_my-plugin_db__.* です。ハンドラーの if フィールドにも同じスコープ付きのツール名を使います。

memory サーバーの全操作を記録し、どの 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 配列の各オブジェクトが、matcher が一致したときに動くフックハンドラーです。5種類あります。

• 一致したフックはすべて並行して動きます。同じハンドラーを複数の設定ファイルに定義しても1回だけ動きます。プラグインやスキルの同じハンドラーは別扱いです
• ハンドラーは、現在のディレクトリで Claude Code の環境のまま動きます。現在のディレクトリが存在しなくなっている場合（別のシェルが削除した worktree や一時ディレクトリなど）、Claude Code は、まだ存在する次のうち最初のものからコマンドフックを動かします：セッションを始めたディレクトリ・プロジェクトルート・ホームディレクトリ・システムの一時ディレクトリ。代替のディレクトリを名指しする警告をデバッグログに記録します
• 環境変数 $CLAUDE_CODE_REMOTE は、リモートの Web 環境では "true" で、ローカルの CLI では設定されません。v2.1.199 以降は、ローカルのセッションに有効なリモートコントロール接続がある間、$CLAUDE_CODE_BRIDGE_SESSION_ID にリモートコントロールのセッション ID を設定します

共通のフィールド#

全種類のハンドラーに共通です。

• if フィールドには、権限ルールをちょうど1つだけ書けます。&&・||・リストで組み合わせる構文は無く、複数の条件を使うには、条件ごとに別のハンドラーを定義します
• ファイルツールの if では、"Edit(src/**)" のような1階層のディレクトリのパターンは、作業ディレクトリ内の src ディレクトリとその下のファイルだけに一致します。どの深さにある src ディレクトリにも一致させるには、"Edit(**/src/**)" と書きます。v2.1.214 より前は、"Edit(src/**)" が作業ディレクトリ以下のどの深さの src にも一致していました

if のパターンが Bash コマンドに一致するしくみ#

if フィールドの Bash のパターンで、フックのコマンドが動くかは、パターンの形と Claude が呼ぶ Bash コマンドで決まります。先頭の VAR=value の代入は、照合の前に取り除かれます。

Bash の入力がどのコマンドを実行するか Claude Code が判定できないときは、パターンに関係なくフックを動かします。if の絞り込みは最善努力なので、許可や拒否を確実に強制するにはフックでなく権限を使います。

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

共通のフィールドに加えて、次のフィールドがあります。

exec 形式とシェル形式

コマンドフックは、args があれば exec 形式、無ければシェル形式で動きます。フックがパスのプレースホルダーを参照するときは、各要素が引用符なしで1つの引数として渡されるので、args を設定します。パイプや && などのシェルの機能が要るとき、またはどちらの心配も無いときは、args を省きます。

• exec 形式（args あり）：Claude Code は command を PATH 上の実行ファイルとして解決し、args を引数のベクトルとして直接起動します。シェルは無いので、args の各要素は書いたとおり1つの引数になり、${CLAUDE_PLUGIN_ROOT} のようなパスのプレースホルダーは、command と各 args 要素に、単なる文字列として置換されます。アポストロフィ・$・バッククォートなどの特殊文字は、解釈するシェルが無いので、そのまま渡ります。どのプラットフォームでも、シェルによるトークン分割は起きません
• シェル形式（args なし）：command の文字列がシェルに渡されます。macOS と Linux は sh -c、Windows は Git Bash（無ければ PowerShell）です。shell フィールドで明示的にも選べます。シェルが文字列を分割し、変数を展開し、パイプ・&&・リダイレクト・glob を解釈します

プラグインに同梱した 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 を読めます
• プラグインのフックは、exec 形式に限り、${user_config.*} の値も置換します（command と各 args 要素に単なる文字列として置換されるので、シェルが再解析しない）
• ${user_config.*} を command に書いたシェル形式のプラグインフックは、実行されずエラーになります。シェル形式のフックでオプションの値を使うには、環境変数 $CLAUDE_PLUGIN_OPTION_<KEY>（webhook_url オプションなら $CLAUDE_PLUGIN_OPTION_WEBHOOK_URL）を読むか、args を設定して exec 形式に切り替えます。v2.1.207 より前は、シェル形式のプラグインフックのコマンドも ${user_config.*} を置換していました

HTTP フックのフィールド#

共通のフィールドに加えて、次のフィールドがあります。

Claude Code は、フックの JSON 入力を Content-Type: application/json の POST リクエストボディとして送ります。レスポンスボディは、コマンドフックと同じ JSON 出力形式です。エラーの扱いはコマンドフックと違います（後述「HTTP のレスポンスの扱い」）。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 ツールフックのフィールド#

共通のフィールドに加えて、次のフィールドがあります。

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

• ツールの結果の読まれ方：Claude Code は、ツールのテキスト内容を、コマンドフックの stdout と同じ（終了コード 0 の解析規則）に読みます。ツールが isError: true を返すと、フックはブロックしないエラーを出し、実行は続きます
• サーバーがまだ接続中のとき：PreToolUse や Stop のように、フックがブロックしたり結果を変えたりできるイベントでは、Claude Code は、接続中のサーバーがつながるまで、最大 MCP_TIMEOUT かつフック自身の timeout の範囲で待ってから、ツールを呼びます。Notification や SessionEnd のような観察のイベントでは待ちません。cached の状態のサーバーは、フックがそのツールを呼ぶときに接続されます。その時点でサーバーがつながっていなければ、フックはブロックしないエラーを出し、実行は続きます。フックが OAuth の流れを始めることは無いので、先に /mcp でサーバーを認証します
• MCP サーバーが使える前に発火するイベント：起動時の SessionStart（--continue や --resume の場合も）と、すべての Setup イベントは、セッションの MCP サーバーがフックから使える前に発火します。Claude Code は、その mcp_tool フックを、ツールを呼ばずに飛ばし、デバッグログに mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)（Setup なら、その名前を挙げた同じメッセージ）を記録します。/clear やコンパクションの後など、SessionStart がセッションの後のほうで再び発火するときは、その mcp_tool フックが動きます。起動時にセッションが必要とするものには、SessionStart の type: "command" フックを使います

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

共通のフィールドに加えて、次のフィールドがあります。

スクリプトをパスで参照する#

フックが動くときの作業ディレクトリにかかわらず、プロジェクトやプラグインのルートからの相対でフックのスクリプトを参照するプレースホルダーです。

• ${CLAUDE_PROJECT_DIR}：セッションが始まったプロジェクトルート。Claude Code は、stdio の MCP サーバーとプラグインの LSP サーバーの環境にも、この変数を設定します
• ${CLAUDE_PLUGIN_ROOT}：プラグインに同梱したスクリプト用の、プラグインのインストール先のディレクトリ。更新をまたいだパスの挙動は、プラグインのリファレンスにあります
• ${CLAUDE_PLUGIN_DATA}：更新後も残すべき依存関係と状態のための、プラグインの永続データディレクトリ

パスのプレースホルダーを参照するフックには、exec 形式を勧めます。シェル形式では、各プレースホルダーを二重引用符で囲みます。

プロジェクトのスクリプト：Write か Edit のツール呼び出しの後に、プロジェクトの .claude/hooks/ からスタイルチェッカーを動かす例です。

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

プラグインのスクリプト：プラグインのフックは、任意の最上位の description フィールドを持つ hooks/hooks.json に定義します。プラグインが有効になると、そのフックは、あなたのユーザーとプロジェクトのフックと統合されます。プラグインに同梱した整形スクリプトを動かす例です（作り方はプラグインを作って配る参照）。

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

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

設定ファイルとプラグインのほかに、スキルとサブエージェントの frontmatter に、設定ベースのフックと同じ形式で、フックを直接定義できます。Claude Code がそれを登録しておく期間は、コンポーネントで違います。

• サブエージェントのフック：そのサブエージェントが動いている間だけ動き、終わると取り除かれる。ここの Stop フックは、サブエージェントの完了時に発火する SubagentStop に変換される
• スキルのフック：あなたか Claude がスキルを呼んだときに登録され、セッションの残りの間、スキル自身のターンより後のターンでも動き続ける。最初に成功した実行の後に取り除かれるようにするには、フックに once: true を付ける

各 Bash コマンドの前にセキュリティ検証スクリプトを動かす PreToolUse フックを定義するスキルの例：

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

サブエージェントも、YAML の frontmatter で同じ形式を使います。

• プロジェクトのスキルの frontmatter のフックは、設定ファイルのフックと同じワークスペースの信頼の規則に従います。Claude Code は、あなたか Claude がスキルを呼んだときに、信頼していないフォルダでの -p の実行を含めて、それらを登録します
• プロジェクトのサブエージェントの frontmatter のフックは、エージェントのファイルがあるフォルダの、ワークスペースの信頼ダイアログを承認した後にだけ動きます。-p のセッションは、承認したことになりません。詳しくはサブエージェントを参照してください。v2.1.218 より前は、これらのフックは信頼していないフォルダからも動くことがありました

/hooks メニュー#

Claude Code で /hooks を入力すると、設定済みのフックの読み取り専用のブラウザが開きます。一覧は、各フックに、ユーザー設定・プロジェクト設定・ローカル設定・プラグイン・現在のセッションなど、出どころを示すラベルを付けます。

フックを選ぶと、それが動かすものの全文と、定義された場所（設定ファイルのパスやプラグインの名前など）が見られます。

設定されたフックが無いイベントも含めて、すべてのフックイベントを見るには、一覧の末尾の All events を選びます。

フックを無効にする・取り除く#

• 設定ファイルで定義したフックを取り除くには、そのファイルからエントリを削除します
• すべてのフックを、取り除かずに一時的に無効にするには、設定ファイルに "disableAllHooks": true を書きます。Claude Code は、設定の優先順位を適用した後に残る値を読むので、プロジェクトの .claude/settings.json の "disableAllHooks": false は、ユーザー設定の true を上書きします。プロジェクトの設定に関係なく、1回の実行だけフックを切るには、--settings '{"disableAllHooks": true}' を渡します（プロジェクトとローカルの設定より優先されます）。個々のフックを、設定に残したまま無効にする方法はありません
• disableAllHooks は、管理設定の階層を尊重します。管理者が管理ポリシー設定でフックを設定している場合、user・project・local の設定の disableAllHooks では、それらの管理フックを無効にできません。管理フックを無効にできるのは、管理設定のレベルで設定した disableAllHooks だけです
• 設定ファイルのフックの直接の編集は、通常、ファイルの監視が自動で拾います

フックの入力と出力#

コマンドフックは、JSON のデータを stdin で受け取り、終了コード・stdout・stderr で結果を返します。HTTP フックは、同じ JSON を POST のリクエストボディで受け取り、HTTP のレスポンスボディで結果を返します。この節は、全イベントに共通のフィールドと挙動を扱います。各イベントの入力スキーマと決定の制御は、イベントごとの節にあります。

• macOS と Linux では、コマンドフックは、制御端末の無い自分のセッションで動きます。フックのプロセスと子プロセスは、/dev/tty を開けず、エスケープシーケンスを Claude Code の画面へ直接送れません。Windows には /dev/tty がありません
• どのプラットフォームでも、ユーザーにメッセージを出すには、JSON 出力で systemMessage を返します（イベントによっては、これを捨てるか、別の場所へ届けます。各イベントの節に書いてあります）。デスクトップ通知・ウィンドウタイトルの設定・ベルには、代わりに terminalSequence を返します

共通の入力フィールド#

イベントは、各イベントの節に書かれたイベント固有のフィールドのほかに、次のフィールドを JSON で受け取ります。

--agent で実行しているとき、またはサブエージェントの中では、さらに2つのフィールドが入ります。

• model フィールドを受け取れるのは SessionStart のフックだけで、Claude Code が必ず入れるとは限りません。PreModelSwitch と PostModelSwitch のフックは、代わりに from_model と to_model を受け取るので、セッション中のモデルの変化を追うには PostModelSwitch のフックを使います
• $CLAUDE_MODEL という環境変数はありません。シェルで設定していれば、フックは $ANTHROPIC_MODEL を読めますが、セッション中に /model でモデルを切り替えても、その値は変わりません
• フックのプロセスは、親の環境を引き継ぎます。ただし、Claude Code が起動するすべてのサブプロセスから取り除く OTEL_* のエクスポーター変数と、CLAUDE_CODE_SUBPROCESS_ENV_SCRUB を 1 にしたときに取り除かれる変数は除きます

Bash コマンドの PreToolUse フックが stdin で受け取る例：

{
  "session_id": "abc123",
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite",
    "timeout": 120000,
    "run_in_background": false
  },
  "tool_use_id": "toolu_01ABC123..."
}

tool_name・tool_input・tool_use_id はイベント固有のフィールドです。

終了コードの出力#

フックのコマンドの終了コードは、操作を進めるか、ブロックするか、無視するかを Claude Code に伝えます。終了コードだけで決まるのではありません。Claude Code は、終了コード 0 だけでなくどの終了コードでも stdout から JSON の出力フィールドを読み、標準の決定モデルを使うイベントでは、スキーマ検証を通る解析済みのオブジェクトが、終了コードと並んで有効になります。終了コード 2 のブロックは、JSON が上書きできない唯一の結果です。

イベントごとの例外は、2つの表が持ちます。「イベントごとの終了コード 2 の挙動」は、各イベントで終了コードが何をするかを、「決定の制御」は、各イベントがどの決定フィールドを受け付けるかを示します。systemMessage のようなユニバーサルなフィールドは、ほとんどのイベントで働き、「JSON 出力」の表にあります。

終了コード 0#

終了コード 0 は成功で、構造化された制御のために JSON を出力するときに意図する終了コードです。

• ほとんどのイベントでは、Claude Code は stdout をデバッグログに書き、記録には出しません。例外は UserPromptSubmit・UserPromptExpansion・SessionStart・PostModelSwitch で、プレーンテキストの stdout が、Claude が見て反応できる文脈として加わります
• stdout を JSON 出力として読むかプレーンテキストとして読むかは、前後の空白を無視した始まりと終わりで決まります
  • { で始まり } で終わる：JSON として解析される。出力が2行以上で、各行がそれだけで JSON として解析でき、どの行も、フィールドを設定する JSON 出力のオブジェクトでないときは、出力全体がプレーンテキストとして扱われる。それらの行の1つでもフィールドを設定していると、出力全体が解析の失敗になる（後述）
  • { で始まるが } で終わらない：プレーンテキストとして扱われる
  • それ以外で始まる：JSON の配列や引用符で囲んだ JSON の文字列を含め、プレーンテキストとして扱われる
• 標準の決定モデルを使うイベントでは、終了コード 0 で、スキーマ検証に失敗した解析済みのオブジェクトは、ブロックしないエラーです。操作は進み、記録に、検証のメッセージつきの <hook name> hook error の通知が出ます。2 以外のどの終了コードでも同じで、終了コード 2 はそれでもブロックします
• 標準の決定モデルを使うイベントで、Claude Code が stdout を JSON として解析しようとして失敗すると、2 以外のどの終了コードでも、ブロックしないエラーを報告します。記録に、解析のメッセージつきの <hook name> hook error の通知が出ます。プレーンテキストの stdout を文脈として加えるイベントでは、Claude Code はそのテキストを加えません。v2.1.248 より前は、その stdout をプレーンテキストとして扱っていました
• 終了コード 0 で終わるフックの stderr は、デバッグログにだけ行き、記録には決して出ず、Claude も見ません。自分で読むには、デバッグログを有効にします。PostToolUse や PostToolUseFailure のフックから Claude に警告を出すには、ツールがすでに動いていても Claude が stderr を見られる終了コード 2 を使います

終了コード 2#

終了コード 2 は、ブロックするエラーです。ブロックできるイベントでは、JSON を出力してもしなくても、終了コード 2 でブロックされます。JSON の permissionDecision: "allow" でも上書きできません。Claude Code は、stdout の有効な JSON の出力を、それでも読みます。Elicitation と ElicitationResult では、終了コード 2 のフックの hookSpecificOutput は無視されます。

• ブロックのメッセージは、JSON がブロックの判定をしていればその理由、そうでなければ stderr のテキストです。ブロックが何をするかはイベントで変わります：PreToolUse はツール呼び出しをブロックし、UserPromptSubmit はプロンプトを拒否する、など
• JSON 出力のスキーマ検証に失敗する JSON を出力しながら終了コード 2 で終わるフックも、ブロックします。Claude Code は stderr をブロックの理由に使い、検証の失敗をデバッグログに記録します。v2.1.214 より前は、この組み合わせはブロックしないエラーとして扱われ、操作は進みました

rm コマンドを終了コード 2 でブロックし、ほかのコマンドは通常の権限の流れに任せるスクリプトの例：

#!/bin/bash
# Reads JSON input from stdin, checks the command
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # No decision: the normal permission flow applies

それ以外の終了コード#

ほとんどのフックイベントでは、それ以外の終了コードはそれだけではブロックしません。何が起きるかは stdout で決まります。

• スキーマ検証を通る解析済みのオブジェクトがあり、標準の決定モデルを使うイベント：Claude Code は終了コードを無視し、JSON だけが結果を決めます。イベントが対応する各フィールド（permissionDecision・additionalContext・updatedInput・systemMessage を含む）が有効になり、フックはエラーとして報告されません
• スキーマ検証に失敗する解析済みのオブジェクトがあり、標準の決定モデルを使うイベント：終了コード 0 のときと同じ、ブロックしないエラーです。操作は進み、<hook name> hook error の通知が検証のメッセージを伝えます
• Claude Code が JSON として解析しようとして失敗する stdout がある、標準の決定モデルを使うイベント：終了コード 0 のときと同じ、ブロックしないエラーを報告します。操作は進み、通知が解析のメッセージを伝えます
• プレーンテキストとして扱われる stdout、または空の stdout：ほとんどのフックイベントで、ブロックしないエラーです。操作は進み、記録に、<hook name> hook error の通知と、Failed with non-blocking status code: を前に付けた stderr の最初の1行が出ます。stderr の全文を得るには、デバッグログを有効にします
• 標準の決定モデルの外のイベントは、「イベントごとの表」に自分の行を持ちます。WorktreeCreate は、JSON が何を言っていても、どの非 0 でも作成が失敗します。StopFailure のように、フックの出力を完全に捨てるイベントは、どの終了コードでも JSON を無視します（terminalSequence のような副作用のフィールドは、それでも働きます）
• 起動できないフックも、同じブロックしないエラーに入ります。スクリプトのパスが存在しない・実行できないときは、シェルが 127 のような終了コードで終わり、インタプリタのメッセージつきの同じ通知が出ます（例：Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory）。ほとんどのフックイベントで、操作は進みます。方針のフックを設定するときは、最初の実行でこの通知を見張ってください。settings.json のパスの打ち間違いは、ゲートを黙って無効にします

タイムアウト#

async: true で動かすコマンドフックを除き、Claude Code は、timeout に達した command・http・mcp_tool のフックを取り消し、その出力を捨てるので、ほとんどのイベントで、タイムアウトしたフックは判定を出しません。

• PreModelSwitch：タイムアウトで取り消されたフックは、モデルの切り替えをブロックします
• PreToolUse：2種類のフックで違います
  • タイムアウトした command・http・mcp_tool のフックは、ツール呼び出しをブロックしません。呼び出しは通常の権限の流れを進むので、止まったフックがゲートとして働くことを当てにしないでください
  • タイムアウトを超えた Agent SDK のコールバックフックは、ツール呼び出しをブロックします

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

終了コード 2 は、フックが「止めて、これをしないで」と伝える方法です。効果はイベントで変わります。まだ起きていないツール呼び出しのようにブロックできる動作を表すイベントと、すでに起きたことや防げないことを表すイベントがあるためです。

SessionStart・SubagentStart・PostModelSwitch では、Claude Code は、終了コード 2 の stderr を、ブロックしないエラーと同じ <hook name> hook error の通知として記録に出します。Claude には見えず、セッションやサブエージェントは進みます。SubagentStart では、通知は親の会話ではなくサブエージェント自身の記録に出ます。

HTTP のレスポンスの扱い#

HTTP フックは、終了コードと stdout の代わりに、HTTP のステータスコードとレスポンスボディを使います。次の結果は、ほとんどのイベントに当てはまります。WorktreeCreate のように、「イベントごとの表」に自分の失敗の取り決めを持つイベントは、失敗した HTTP フックにもその取り決めを適用します。

• 2xx で本文が空：成功。出力なしの終了コード 0 と同じ
• 2xx で JSON オブジェクトの本文：コマンドフックと同じ JSON 出力のスキーマで解析される。スキーマ検証に失敗する本文は、ブロックしないエラー
• 2xx でそれ以外の本文（プレーンテキストなど）：ブロックしないエラー。2xx 以外のステータスと同じ扱いで、Claude Code はそのテキストを Claude の文脈に加えない
• 2xx 以外のステータス：ブロックしないエラー。実行は続く
• 接続の失敗：ブロックしないエラー。実行は続く
• タイムアウト：フックは取り消される（前述「タイムアウト」）

コマンドフックと違い、HTTP フックは、ステータスコードだけでブロックするエラーを知らせられません。ツール呼び出しをブロックしたり権限を拒否したりするには、適切な決定のフィールドを持つ JSON の本文つきの 2xx のレスポンスを返します。

JSON 出力#

終了コードでできるのはブロックするか黙るかだけですが、JSON 出力ならより細かく制御できます。終了コード 2 でブロックする代わりに、終了コード 0 で JSON オブジェクトを stdout に出します。Claude Code は、その JSON の特定のフィールドを読んで動作を制御します。ブロック・許可・ユーザーへの引き上げのための決定の制御を含みます。

• フックの stdout は、JSON オブジェクトだけにします。シェルのプロファイルが起動時にテキストを出すと、JSON の解析を妨げます（フックの使い方のトラブルシューティングを参照）
• フックの additionalContext・systemMessage・initialUserMessage の文字列と、プレーンな stdout は、10,000 文字が上限です
  • 範囲：同じイベントで複数のフックが動いても、Claude Code は文字列ごとに別々に測る。JSON 出力ではフィールドごと、プレーンな stdout は全体で測る
  • 上限を超えたとき：Claude Code は、出力をセッションディレクトリのファイルに保存し、ファイルのパスと先頭 2,000 文字までのプレビューに置き換える。大きな有効な Bash の結果も、同じように扱われる（ツールの出力制限を参照）。その Bash の上限と違い、この上限には、上げる設定も環境変数もない
  • ファイルの読み取り：Claude Code は、Claude にそのファイルを読むよう求めないので、Claude が必ず見るべきものは、上限の中に収める

JSON オブジェクトは3種類のフィールドに対応します。

• ユニバーサルなフィールド：下の表の continue など。どのイベントも受け付けるが、イベントによっては捨てたり、systemMessage を記録以外の場所へ届けたりする。各イベントの節に書いてある。terminalSequence も、「ターミナル通知を出す」に挙げた例外を除き、これらのイベントで働く
• 最上位の decision と reason：一部のイベントが、ブロックやフィードバックのために使う
• hookSpecificOutput：より豊かな制御が要るイベントのための入れ子のオブジェクト。イベント名を設定した hookEventName フィールドが必須

Claude を完全に止めるには：

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

PreToolUse と PostToolUse のフックでは、ツール呼び出しが失敗したときや、Claude がまだ応答をストリームしている間に完了したときにも、停止が適用されます。

ターミナル通知を出す#

フックは制御端末なしで動くので、エスケープシーケンスを /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 を含む、許可リストの外のものは拒否され、フィールドが無視されます。

• Claude Code は、フックの出力を処理するときにシーケンスを自分で書くので、このフィールドは、Notification や StopFailure のように systemMessage と continue を捨てるイベントでも働きます。2つの制限があります
  • Claude Code がシーケンスを書くのは、対話セッションで、画面が出ている間だけ。-p フラグの非対話モードと Agent SDK では、フィールドを無視する
  • WorktreeCreate のコマンドフックは、Claude Code が stdout を worktree のパスとして読むので、JSON を返せない。HTTP の WorktreeCreate フックは JSON を返せて、このフィールドを含められる

Notification フックからデスクトップ通知を出す例です。エスケープシーケンスは、制御用のバイトがシェルのコマンドラインに現れないよう printf の8進のエスケープで作り、jq -n --arg で JSON の出力を作って、通知メッセージ中の引用符・バックスラッシュ・改行が正しくエスケープされるようにしています。

#!/bin/bash
# Notification hook: ping the desktop when Claude Code needs attention.
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": "..." } の形は、どのシェルや言語からでも同じです。

Claude に文脈を渡す#

additionalContext フィールドは、フックの文字列を Claude のコンテキストウィンドウに渡します。Claude Code は、その文字列をシステムリマインダーで包み、フックが発火した時点の会話に挿入します。Claude は次のモデルリクエストでそのリマインダーを読みますが、画面にはチャットのメッセージとして出ません。additionalContext は、イベント名と並べて hookSpecificOutput の中に返します。

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

リマインダーが現れる場所は、イベントで違います。

• SessionStart と SubagentStart：会話の始まり、最初のプロンプトの前

• UserPromptSubmit と UserPromptExpansion：送信されたプロンプトと並んで

• PreToolUse・PostToolUse・PostToolUseFailure・PostToolBatch：ツールの結果の隣

• Stop と SubagentStop：ターンの終わり。Claude がフィードバックに反応できるよう、会話が続く

• PostModelSwitch：切り替え後の次のリクエストに付く

• 同じイベントで複数のフックが additionalContext を返すと、Claude はすべての値を受け取ります

• 値が 10,000 文字を超えると、Claude Code はテキストをセッションディレクトリのファイルに書き、ファイルのパスと先頭 2,000 文字までのプレビューを Claude に渡します。Claude はそのファイルを読めますが、Claude Code は読むよう求めません

• additionalContext は、Claude が、いまの環境の状態や、いま実行した操作について知っておくべき情報に使います：環境の状態（現在のブランチ・デプロイ先・有効な機能フラグ）／条件つきのプロジェクトのルール（いま編集したファイルにどのテストコマンドが当てはまるか・この worktree でどのディレクトリが読み取り専用か）／外部のデータ（自分に割り当てられた open の issue・最近の CI の結果・社内サービスから取った内容）

• 変わらない指示には、CLAUDE.md を使います。スクリプトを動かさずに読み込まれる、静的なプロジェクトの規約の標準の置き場所です

• テキストは、命令調のシステム指示でなく、事実の文として書きます。「The deployment target is production」や「This repo uses bun test」のような言い方は、プロジェクトの情報として読まれます。帯域外のシステムコマンドのように見える書き方は、Claude のプロンプトインジェクションへの防御を起こし、Claude が文脈として扱わず、そのテキストをあなたに見せてしまうことがあります

• Claude Code は、注入したテキストをセッションの記録に保存します。PostToolUse や UserPromptSubmit のようなセッション途中のイベントでは、--continue や --resume で再開したとき、過去のターンのフックを再実行せず保存したテキストを再生するので、タイムスタンプやコミット SHA のような値は古くなります。SessionStart のフックは、再開時に source を "resume"（--fork-session を付けたなら "fork"）にして再び動くので、文脈を更新できます

決定の制御#

JSON でブロックや動作の制御に対応するイベントは一部だけで、対応するイベントは、それぞれ違うフィールドで決定を表します。フックを書く前の早見表です。

一部のイベントは、許可やブロックだけでなく、内容を書き換えることもできます。

• PreToolUse：hookSpecificOutput 直下の updatedInput が、ツールの引数を実行前に置き換える
• PermissionRequest：decision オブジェクトの中の updatedInput
• PostToolUse：updatedToolOutput がツールの結果を置き換える
• UserPromptSubmit：プロンプトを置き換えられない。並べて additionalContext を注入できるだけ

伏せ字や変換の用途では、出ていく入力は PreToolUse で、入ってくるツールの結果は PostToolUse で捕まえます。

各パターンの例：

最上位の decision：decision の値は "block" だけです。操作を進めるには、JSON から decision を省くか、JSON なしで終了コード 0 で終えます。

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

PreToolUse：hookSpecificOutput で、許可・拒否・ユーザーへの引き上げができます。実行前にツールの入力を変えたり、Claude に追加の文脈を注入したりもできます。

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

PermissionRequest：hookSpecificOutput で、ユーザーに代わって権限リクエストを許可・拒否します。許可するときは、ツールの入力を変えたり、ユーザーに再度確認しないよう権限ルールを適用したりもできます。

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

Bash コマンドの検証・プロンプトのフィルタリング・自動承認のスクリプトを含む詳しい例は、フックの使い方にあります。

フックイベント#

各イベントは、フックが動ける Claude Code のライフサイクルの時点に対応します。以降の節は、セッションの準備から、エージェントのループを経て、セッションの終了まで、ライフサイクルの順に並んでいます。各節は、イベントがいつ発火するか・どの matcher に対応するか・受け取る JSON の入力・出力で動作を制御する方法を説明します。

SessionStart#

新しいセッションの開始時と、既存のセッションの再開時に動きます。既存の issue や最近の変更のような開発の文脈を読み込んだり、環境変数を設定したりするのに向きます。スクリプトが要らない静的な文脈なら、CLAUDE.md を使います。

• SessionStart はすべてのセッションで動くので、フックは速くしておきます。対応するのは type: "command" と type: "mcp_tool" のフックだけです（mcp_tool が動く条件は、前述の MCP ツールフックのフィールドの節）
• 対話セッションの開始時、--continue か --resume での起動時の再開、/clear では、SessionStart のフックはバックグラウンドで動きます。すぐに入力でき、再開した会話はフックを待たずに表示されます。ただし Claude の最初の応答は、フックの文脈が Claude に届くよう、フックが終わるのを待ちます
• セッション内で /resume で会話を切り替えるときは、代わりに切り替えがフックの終了を待ちます。バックグラウンドのフックが動いている間に /clear を実行したり別の会話に切り替えたりすると、そのフックが返したものは、セッションに適用されません
• 起動時（再開したセッションを含む）にも同じ待ちが適用され、SessionStart のフックが動いている間に送ったプロンプトは、フックが終わるまで Claude に届きません。どちらの待ちの間も、Esc でプロンプトを送らず入力欄に戻せます（フックは動き続けます）

matcher の値は、セッションの始まり方に対応します。

v2.1.214 より前は、フォークされたセッションの source は "resume" でした。

SessionStart の入力#

共通の入力フィールドに加えて、source と、任意の model・agent_type・session_title を受け取ります。

名前を付けていないセッションにも、生成されたタイトルがあることがありますが、それはカスタムタイトルではなく、session_title には出ません。

source が "resume" か "fork" で、記録に Claude の応答が1つ以上あるとき、SessionStart のフックは次の4つのフィールドも受け取ります。最初のリクエストの前に、古い会話の再開にかかるコストを（systemMessage などで）報告するのに使えます。v2.1.251 以降が必要です。

最後の応答から 90 分後に再開したセッションの入力の例：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionStart",
  "source": "resume",
  "model": "claude-opus-5",
  "seconds_since_last_response": 5400,
  "context_tokens": 182340,
  "prompt_cache_likely_expired": true,
  "estimated_cache_write_usd": 1.1396
}

SessionStart の決定の制御#

Claude Code は、プレーンテキストとして扱う 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",
    "sessionTitle": "auth-refactor"
  }
}

このイベントではプレーンな stdout がすでに Claude に届くので、文脈を読み込むだけのフックは、JSON を作らず stdout に直接出せます。sessionTitle など、ほかのフィールドと組み合わせるときに、JSON の形を使います。

SessionStart のフックがスキルをインストールまたは更新するときは、reloadSkills を使います。スキルの探索は通常、SessionStart のフックが終わる前に済むので、フックが ~/.claude/skills/ や .claude/skills/ に書いたファイルは、そのままでは次のセッションにしか現れません。共有のスキルのリポジトリを同期して、再走査を求める例です。

#!/bin/bash

git -C ~/.claude/skills/team-skills pull --quiet 2>/dev/null || \
  git clone --quiet https://git.example.com/your-org/team-skills.git ~/.claude/skills/team-skills

echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

リポジトリの URL はプレースホルダーなので、自分のスキルのリポジトリに置き換えます。プレースホルダーのままではクローンが失敗し、fatal: のメッセージを stderr に出します。終了コード 0 で終わる SessionStart のフックの stderr は情報用だけなので、reloadSkills の要求は、それでも適用されます。

環境変数を永続化する#

SessionStart のフックは、後続の Bash コマンドのために環境変数を永続化できるファイルパスを示す環境変数 CLAUDE_ENV_FILE を使えます。個別の環境変数を設定するには、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)

# Run your setup commands that modify the environment
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

Setup#

--init-only で起動したとき、または -p フラグの非対話モードで --init か --maintenance を付けて起動したときだけ発火します。通常の起動では発火しません。CI やスクリプトから、通常のセッション開始とは別に明示的に起こす、1回限りの依存関係のインストールや定期的な後始末に使います。セッションごとの初期化には、代わりに SessionStart を使います。

• claude --init-only を実行すると、Claude Code は Setup のフックと、startup の matcher の SessionStart のフックを動かし、会話を始めずに終了します
• -p で会話を始めるか続けるときは、引数か stdin のパイプでプロンプトを渡す必要もあります。SessionStart のフックが initialUserMessage を供給するときか、保留したツール呼び出しでセッションを再開するときは、プロンプトを省けます
• 成功すると、--init-only はターミナルに何も出しません。フックが動いたかを確かめるには、claude --debug-file <path> --init-only（<path> はログファイルの場所）で起動し、ログの Setup と SessionStart のフックの項目を見ます
• Setup は起動のたびには発火しないので、依存関係のインストールが要るプラグインは、Setup だけには頼れません。実用的な形は、初回の使用時に依存関係を確かめ、無ければインストールすることです（${CLAUDE_PLUGIN_DATA}/node_modules を調べ、無ければ npm install を動かすフックやスキルなど）。インストールした依存関係の置き場は、プラグインの永続データディレクトリを参照してください。マーケットプレイスでプラグインを配るなら、この形は要らないかもしれません：Claude Code は、プラグインをキャッシュするとき、対象の Node.js パッケージの依存関係を自動でインストールします

Setup の入力#

共通の入力フィールドに加えて、"init" か "maintenance" を設定した trigger フィールドを受け取ります。

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

Setup の決定の制御#

Setup のフックはブロックできず、どの終了コードでも実行は続きます。Claude Code は、どの終了コードでも、Setup のフックの JSON 出力のフィールド（systemMessage・continue・hookSpecificOutput.additionalContext など）を捨てます。-p では、--output-format stream-json --verbose で起動したときだけ、Setup のフックの stdout・stderr・終了コードが hook_response イベントとして実行の出力に現れます。

Setup のフックは CLAUDE_ENV_FILE を使えます。そのファイルに書いた変数は、SessionStart のフックと同じく、セッションの後続の Bash コマンドに残ります。Setup で動くのは type: "command" のフックだけで、Setup の type: "mcp_tool" のフックは常に飛ばされます。

InstructionsLoaded#

CLAUDE.md や .claude/rules/*.md が文脈に読み込まれたときに発火します。セッション開始時に先に読み込まれたファイルについて発火し、後からファイルが遅延読み込みされたとき（Claude が入れ子の CLAUDE.md のあるサブディレクトリにアクセスしたとき、paths: frontmatter のある条件つきルールが一致したときなど）にも発火します。ブロックや決定の制御には対応せず、観測のために非同期で動きます。

• このイベントは、Project instructions 設定で Claude が AGENTS.md を直接読むときには発火しません。CLAUDE.md が AGENTS.md をインポートするときは、ほかのインポートファイルと同じく load_reason が include で発火し、CLAUDE.md が AGENTS.md へのシンボリックリンクのときは、通常の CLAUDE.md の読み込みとして発火します
• matcher は load_reason に対して評価されます。セッション開始時に読み込まれたファイルだけで発火するには "matcher": "session_start"、遅延読み込みだけなら "matcher": "path_glob_match|nested_traversal" を使います

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 の決定の制御#

決定の制御はありません。指示の読み込みをブロックしたり変更したりできず、systemMessage や continue などの JSON 出力のフィールドは捨てられます。監査ログ・コンプライアンスの追跡・観測に使います。

UserPromptSubmit#

プロンプトが送信されたとき、Claude が処理する前に動きます。プロンプトや会話に基づいて追加の文脈を足したり、プロンプトを検証したり、特定の種類のプロンプトをブロックしたりできます。

UserPromptSubmit のフックは、自分で打ったプロンプトのときだけ発火するのではありません。Claude Code は次のときにも動かします。

• 定期実行のタスクが発火したとき（/loop の1回の繰り返しを含む）

• バックグラウンドのサブエージェントが、自分を始めたセッションへ報告を返したとき

• 別のセッションがメッセージをメインの会話へ送ってきたとき

• command・http・mcp_tool の種類の既定のタイムアウトは 30 秒で、ほかのほとんどのイベントでのそれらの種類の既定の 600 秒より短いです。このフックはすべてのプロンプトの前に動き、完了するまでモデルの処理をブロックするので、止まったフックはセッションを止めます。もっと時間が要るなら、フックのエントリで timeout を設定します

• async: true で動かすコマンドフックを除き、タイムアウトに達した UserPromptSubmit のコマンド・HTTP・MCP ツールのフックは取り消され、additionalContext を含む出力は捨てられます。プロンプトは、その文脈なしで Claude に届きます。記録には、フック名・発火したタイムアウト・出力が捨てられたことを示す通知が出ます

• UserPromptSubmit の Agent SDK のコールバックフックがタイムアウトに達すると、フック名とタイムアウトを示すメッセージつきでプロンプトをブロックします（そこのコールバックは、失敗しても通してはいけない方針のゲートとして働いていることがあるため）。セッションは続きます。v2.1.208 より前は、そのイベントのコールバックのタイムアウトは、実行エラーでターンを終えていました

UserPromptSubmit の入力#

共通の入力フィールドに加えて、送信されたテキストを持つ prompt フィールドを受け取ります。[Pasted text #N] のプレースホルダーに畳まれた貼り付けの内容は、その場で展開されて届きます。Claude Code が貼り付けたテキストを Claude 向けに印を付けるセッションでは、展開された内容が <pasted_content id="…"> の行と </pasted_content id="…"> の行の間に入るので、フックがプロンプトを解析するときはその行を考慮します。セッションにカスタムタイトルがあるときは session_title も受け取ります（SessionStart の session_title と同じ意味）。

{
  "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 の決定の制御#

送信されたプロンプトを処理するかどうかを制御し、文脈を足せます。JSON 出力のフィールドはすべて使えます。終了コード 0 で会話に文脈を足す方法は2つあります。

• プレーンテキストの stdout：Claude Code が、プレーンテキストとして扱う stdout を Claude の文脈に加える
• additionalContext を持つ JSON：下の JSON 形式でより細かく制御する。additionalContext フィールドが文脈として加わる

どちらの経路も、記録に見える項目は作りません。プレーンな stdout と additionalContext の値は、それぞれフック名で始まるシステムリマインダーとして注入され、Claude は両方を読みます。届いたかを確かめるには、デバッグログを見ます。プロンプトをブロックするには、decision を "block" にした JSON オブジェクトを返します。

終了コード 2 でブロックするフックも reason と同じ経路をたどり、ブロックメッセージが stderr のテキストをユーザーに見せ、文脈には加わりません。

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

ブロックしたプロンプトが残すもの#

ブロックされたプロンプトは Claude に届きませんが、そのテキストはあらゆる場所から消えるわけではありません。既定では、ユーザーに出すブロックメッセージが Original prompt: と送信されたテキストで終わり、Claude Code はそのメッセージをディスク上のセッションの記録ファイルに書きます。テキストをメッセージから除くには、hookSpecificOutput の中に "suppressOriginalPrompt": true を入れた JSON を出力します。decision: "block" でブロックしても、終了コード 2 でブロックしても有効です。JSON を出力しない終了コード 2 のフックは、ブロックメッセージに必ずプロンプトのテキストが入ります。

suppressOriginalPrompt が変えるのはブロックメッセージだけです。送信されたテキストは、セッションの記録やプロンプトの履歴などのローカルファイルに残りうるので、ブロックするフックは、秘密をディスクに残さない方法にはなりません。

UserPromptExpansion#

ユーザーが入力したコマンドが、Claude に届く前にプロンプトへ展開されるときに動きます。特定のコマンドの直接の呼び出しをブロックする、特定のスキルに文脈を注入する、ユーザーがどのコマンドを呼んだかを記録する、といった用途に向きます。たとえば、deploy に一致するフックは、承認ファイルが無ければ /deploy をブロックでき、レビュー用のスキルに一致するフックは、チームのレビューのチェックリストを additionalContext として足せます。

• このイベントは、PreToolUse がカバーしない経路を扱います。Skill ツールに一致する PreToolUse のフックは Claude がツールを呼んだときだけ発火し、/skillname を直接入力すると PreToolUse を迂回します。UserPromptExpansion はその直接の経路で発火します
• command_name に一致します。すべてのプロンプト型コマンドで発火させるには、matcher を空にします

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 の決定の制御#

展開をブロックしたり文脈を足したりできます。JSON 出力のフィールドはすべて使えます。

終了コード 2 でブロックするフックも reason と同じ経路をたどり、ブロックメッセージが stderr のテキストをユーザーに見せます。

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

MessageDisplay#

アシスタントのメッセージが画面へストリームされている間に動きます。Claude Code はメッセージを少しずつ表示します。新しく完成した行のまとまりが描画できるたびに、フックがその行を渡されて1回動き、Claude Code はその場所にフックの置換テキストを描画します。長いメッセージでは複数回、短いメッセージでは1回だけ呼ばれることがあります。

• 用途：最小限の表示のために Markdown を取り除く／Agent SDK のアプリがユーザーに見せるテキストを変換する／Claude の応答から API キーや内部のホスト名を伏せ字にする
• Claude Code は、フックが返るまで各まとまりを保留するので、フックは速くします。フックが失敗するかタイムアウトすると、元のテキストが表示されます。このイベントの既定のタイムアウトは 10 秒で、もっと時間が要るなら timeout を設定します
• 表示専用です。置換テキストが変えるのは画面に描画されるものだけで、記録と Claude が見るものは元のテキストのままなので、Claude は置換を見ません。verbose モードも元のテキストを表示します。フックが受け取るのはアシスタントのメッセージのテキストだけで、ツールの結果と自分が入力したテキストは、そのまま描画されます
• matcher には対応せず、テキストをストリームするすべてのアシスタントのメッセージで発火します（ツール呼び出しだけの応答のように、テキストの無いメッセージでは発火しません）
• 非対話の実行（Agent SDK のクエリと claude -p を含む）では、MessageDisplay は、行のまとまりごとでなくアシスタントのメッセージごとに1回動きます。その1回の呼び出しは、メッセージの完了後に届き、全文を持ちます：index は 0、final は true、delta にメッセージ全体が入ります。メッセージごとの delta のテキストを集めるフックは、どちらのモードでも同じ合計のテキストを受け取ります

MessageDisplay の入力#

共通の入力フィールドに加えて、ターンとメッセージの識別子・メッセージ内でのこの呼び出しの位置・delta の新しいテキストを受け取ります。まとまりの境界はテキストのストリームのされ方で決まるので、行が特定のグループになることを当てにせず、index と final でメッセージ内の進み具合を追います。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "MessageDisplay",
  "turn_id": "0c9e6a2f-7d41-4f4e-9a15-3f4f7c2b8d10",
  "message_id": "5b2a9c8e-1f63-4d8a-b7c4-9e0d2a6f1c3b",
  "index": 0,
  "final": false,
  "delta": "Here is the plan:\n"
}

MessageDisplay の出力#

全フックが使える JSON 出力のフィールドに加えて、画面上の delta を置き換える displayContent を返せます。

決定の制御はなく、メッセージをブロックしたり、記録や Claude に送られるものを変えたりはできません。Claude Code は JSON 出力の displayContent に従い、systemMessage と continue は捨てます。

次の例は、プレーンテキストの表示のために、Claude の応答から Markdown の書式を取り除きます。スクリプトは各まとまりを stdin から読み、delta から太字の記号とインラインコードのバッククォートを除いて、結果を displayContent として返します。設定ファイルにコマンドフックを登録します（macOS・Linux）。

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

スクリプトをプロジェクトの .claude/hooks/plain-display.sh に保存し、chmod +x で実行権限を付けます。

#!/bin/bash
jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'

Windows では、command を powershell.exe、args を -NoProfile・-ExecutionPolicy・Bypass・-File・${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1 にして、次のスクリプトを動かします。

$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
$text = $batch.delta -replace '\*\*', '' -replace '`', ''
@{
  hookSpecificOutput = @{
    hookEventName = "MessageDisplay"
    displayContent = $text
  }
} | ConvertTo-Json

Markdown の無いまとまりは、そのまま通ります。スクリプトが失敗した場合（jq が無いなど）、Claude Code は元のテキストを表示し、失敗はデバッグ出力にだけ記録され、セッションには出ません。

PreToolUse#

Claude がツールのパラメーターを作った後、ツール呼び出しを処理する前に動きます。EndConversation を除くあらゆるツール名に一致します：Bash・PowerShell・Edit・Write・Read・Glob・Grep・Agent・Workflow・WebFetch・WebSearch・AskUserQuestion・ExitPlanMode などの組み込みツールと、すべての MCP ツール名です。

• 特定のファイルがディスク上で変わったとき、誰が書いたかにかかわらずフックを動かすには、ファイルを編集するツールを名前で一致させるのではなく FileChanged を使います。FileChanged のフックは変更の後に動き、決定の制御が無いので、書き込みをブロックできません
• 決定の制御（次の節）で、ツール呼び出しを許可・拒否・確認・保留できます
• PreToolUse の Agent SDK のコールバックフックがタイムアウトを超えると、ツール呼び出しをブロックし、Claude はタイムアウトを名指しするエラーの結果を受け取ります。別のフックが返した明示的な拒否は、それでも優先されます

PreToolUse の入力#

共通の入力フィールドに加えて、tool_name・tool_input・tool_use_id を受け取ります。

• MCP ツールでは、サーバーの name と、サーバー定義の出どころを示す source を持つオブジェクト mcp_server も入力に入ります。source の値には plugin・sdk・user や project などの設定の範囲があります。信頼の判断は、name や mcp__<server>__ のツール名の接頭辞でなく source に基づいて行います。mcp_server フィールドは v2.1.274 以降が必要です
• ファイルツール Write・Edit・Read では、tool_input.file_path は常に絶対パスです。
  • Claude Code は、フックが動く前に ~ と相対パスを展開するので、パスに一致させるフックを、~ や同じパスの相対の書き方で回避できない
  • Windows では、フックが $PWD が /c/project のように見える Git Bash で動いていても、パスはバックスラッシュ区切りで届く
  • /src/ の確認のようにスラッシュで書いた比較は、バックスラッシュのパスには決して一致せず、ツール呼び出しは、フックにブロックするものが無かったかのように進む
  • 比較の前に区切りを正規化する（Bash なら FILE_PATH="${FILE_PATH//\\//}"、Python なら file_path.replace("\\", "/")）。そのうえで、パスが絶対パスなので ^ で固定せず、/src/ のようなパスの一部に一致させる

Windows の Write 呼び出しは、次の形で届きます。

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "C:\\project\\src\\index.ts",
    "content": "..."
  },
  ...
}

tool_input のフィールドはツールで決まります。

Bash

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

Bash コマンドが Git リポジトリのファイルを変更したとき、Claude Code は変更内容を記録できます。

• bashEditDiffEnabled 設定が記録をオンにしているときは、すべての権限モードで記録します（どのファイルで設定できるかは、その設定の項目にあります）。そうでなければ、auto モードと bypassPermissions モードで、かつ Claude Code が Claude に Bash でのファイル編集を指示するときだけ記録します。記録をオフにするには bashEditDiffEnabled を false にします。バックグラウンドのコマンドと読み取り専用のコマンドには差分がありません
• その後 PostToolUse のフックは、変更されたファイルを tool_response.bashEditDiff で受け取ります。一覧は、コマンドの実行中にリポジトリの下で変わったものです。Git が無視するファイルとサブモジュールのファイルは載りません。v2.1.269 以降が必要です

changedFiles と files はコマンドが変えたものを挙げ、残りのフィールドはその一覧の完全さと信頼性を示します。

PowerShell

PowerShell コマンドを実行します（プラットフォームごとの利用可否はツール一覧を参照）。フィールドは Bash ツールと同じで、コマンドの文字列は command に入ります。

シェルコマンドを調べるフックでは、両方のツールを対象にするため Bash|PowerShell に一致させます。

• PowerShell ツールが有効な Windows では、Claude は PowerShell を主なシェルとして扱い、シェルコマンドをそれ経由で動かす
• Git Bash の無い Windows では、ツールは自動で有効になり、Claude Code は Bash ツールをまったく登録しない
• Bash だけに一致するフックは、そこでは発火しない

Write

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

Edit

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

Read

ファイルの内容を読みます。

Glob

glob パターンに一致するファイルを探します。

Grep

正規表現でファイルの内容を検索します。

WebFetch

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

WebSearch

Web を検索します。

Agent

サブエージェントを起動します。

フォアグラウンドの Agent 呼び出しが完了すると、PostToolUse のフックは、サブエージェントの結果と実行のテレメトリを tool_response で受け取ります。サブエージェント全体のトークンとコストの集計には、query_source が "subagent" のトークンとコストのカウンターを使います（totalTokens と usage は最後のリクエストだけが対象のため）。

• v2.1.271 以降では、Claude Code が auto モードで提供する SubagentHandback ツールで動くサブエージェントは、報告をテキストで返さず、そのツール経由で届けます。その completed の結果の content フィールドには、報告そのものでなく受け渡しの短い注記が入ります。報告を読むには、SubagentHandback に一致する PreToolUse か PostToolUse のフックを使い、tool_input.message を読みます
• バックグラウンドのサブエージェントでは、タスクがバックグラウンドに移った時点でツールが返るので、tool_response に使用量のフィールドはありません（バックグラウンドの起動は即座に返り、実行の途中で Claude Code がバックグラウンドに移したフォアグラウンドのタスクは、その移行時に返ります）。status: "async_launched"・agentId・description・prompt・outputFile・resolvedModel を持ちます
• completed のレスポンスでは、resolvedModel はサブエージェントが始まったモデルで、availableModels などの上書きが働くと、tool_input の model の値と違うことがあります。async_launched のレスポンスでは、エージェントがバックグラウンドに移った時点で使っていたモデルなので、バックグラウンド化の前に起きた入れ替わりが反映されます。modelsUsed とバックグラウンド化時点の resolvedModel の挙動は v2.1.212 以降が必要です

AskUserQuestion

ユーザーに、1〜4 個の選択式の質問をします。

ExitPlanMode

Claude がプランモードを抜ける前に、計画を示して、ユーザーに承認を求めます。Claude はツールを呼ぶ前に計画をディスク上のファイルに書くので、モデルからの tool_input そのものは通常空です。Claude Code が、フックに入力を渡す前に、計画の内容とファイルパスを注入します。

PostToolUse では、tool_response は、承認された計画を持つ plan と filePath のフィールドと、内部の状態フラグを持つオブジェクトです。計画の内容は、ディスクからファイルを読み直さず tool_response.plan を読みます。

PreToolUse の決定の制御#

ツール呼び出しを進めるかを制御できます。最上位の decision フィールドを使うほかのフックと違い、PreToolUse は決定を hookSpecificOutput オブジェクトの中に返します。これにより、4つの結果（allow・deny・ask・defer）と、実行前にツールの入力を変更する機能で、より豊かな制御ができます。

• 複数の PreToolUse のフックが異なる判定を返すときの優先順位は deny > defer > ask > allow です
• 終了コード 2 でブロックするフックも "deny" と同じ経路をたどり、Claude は stderr のメッセージを拒否の理由として見ます
• フックが "ask" を返すと、ユーザーに出る権限確認に、フックの出どころを示すラベルが付きます：設定ファイルかエージェントの frontmatter のフックは [settings]、プラグインのフックは [plugin:<name>]、スキルの frontmatter のフックは [skill]
• フックの "ask" は auto モードでも権限確認を強制します。分類器はツール呼び出しを拒否できますが、黙って承認はできません。v2.1.211 より前は、分類器が、サンドボックスの外で動く Bash コマンドを、フックが要求した確認を出さずに承認できました（分類器は、そのコマンドに自分の安全規則を適用し、フックの "deny" は常に守られました）

{
  "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 フラグの非対話モードで、Claude Code がこれらを出すのは、実行に、確認を受ける権限ホスト（Agent SDK の canUseTool コールバックなど）があるときだけです。

PreToolUse のフックは、次のことをすると、その要件を満たします。

1. ツールの入力を stdin から読む
2. 自前の UI で答えを集める
3. 答えを入れた updatedInput と一緒に permissionDecision: "allow" を返す。ツールは確認なしで動く

これらのツールでは、"allow" だけでは足りません。

AskUserQuestion では、元の questions 配列を返し、各質問のテキストから選ばれた答えへの対応を持つ answers オブジェクトを足します。次の出力は、1つの質問に React と答えます。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "questions": [
        {
          "question": "Which framework?",
          "header": "Framework",
          "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}],
          "multiSelect": false
        }
      ],
      "answers": {"Which framework?": "React"}
    }
  }
}

サーバーが _meta["anthropic/requiresUserInteraction"] で印を付けた MCP ツールは、より厳しい扱いです。Claude Code は、フックがツールの必要とする操作を集めたことを確認できないので、フックは、updatedInput の有無にかかわらず、"allow" でその承認確認を飛ばせません。

ツール呼び出しを後に保留する（defer）#

"defer" は、claude -p をサブプロセスとして動かして JSON 出力を読む統合（Agent SDK のアプリや、Claude Code の上に作ったカスタム UI など）向けです。呼び出し側のプロセスが、ツール呼び出しで 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", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false }] }
  }
}

• タイムアウトも再試行の上限もありません。セッションは、再開するまでディスクに残ります（既定でセッションファイルを 30 日後に削除する cleanupPeriodDays の保持の掃除の対象）。再開したとき答えがまだ用意できていなければ、フックは再び "defer" を返せて、プロセスは同じように終了します。ループをいつ抜けるかは、呼び出し側が、最終的にフックから "allow" か "deny" を返して決めます
• "defer" が働くのは、そのターンに Claude がツール呼び出しを1つだけ行うときです。Claude が複数のツール呼び出しを同時に行うと、"defer" は警告つきで無視され、ツールは通常の権限の流れで進みます。再開では1つのツールしか再実行できず、バッチの1つだけを保留して残りを未解決のままにする方法が無いためです
• 再開したときに保留したツールが使えなくなっていると、プロセスは、フックが発火する前に stop_reason: "tool_deferred_unavailable" と is_error: true で終了します。そのツールを提供していた MCP サーバーが、再開したセッションで接続されていないときに起きます。どのツールが無くなったか分かるよう、deferred_tool_use のペイロードは含まれます

PermissionRequest#

Claude Code がツールを使う許可をあなたに尋ねようとするときに動きます。バックグラウンドのサブエージェントの非対話モードなど、確認を出せないセッションでも、Claude Code はこれらのフックを動かし、どのフックも判定を返さなければ、ツール呼び出しを拒否します。決定の制御で、ユーザーに代わって許可や拒否ができます。--permission-prompt-tool や Agent SDK の canUseTool コールバックに届く呼び出しでは、フックはホストと並んで動き、先に判定したほうが適用されます。

• このイベントは、Claude がツールを使う許可を求めた瞬間の合図が要るときに使います。permission_prompt の Notification フックは、確認が約6秒待たれた後にだけ動きます
• Claude Code は、サンドボックス内のコマンドのネットワークリクエストでは PermissionRequest のフックを動かしません。その確認の合図には、permission_prompt の通知の種類を使います
• ツール名に一致します（値は PreToolUse と同じ）

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 の決定の制御#

権限リクエストを許可・拒否できます。全フックが使える 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 の1つを、自分の updatedPermissions の出力としてそのまま返せます。

PostToolUse#

ツールが成功して完了した直後に動きます。ツール名に一致します（値は PreToolUse と同じ）。ツール名が適切な絞り込みでないときは、より広く一致させます。

• 成功したあらゆるツールの後にフックを動かすには、matcher を省くか "*" にします。フックが何が変わったかを自分で見つけられます（git status --porcelain を動かすなど。git diff が見逃す未追跡ファイルも出ます）。失敗したツール呼び出しには、同じフックを PostToolUseFailure の下にも足します
• 特定のファイルがディスク上で変わったとき、誰が書いたかにかかわらずフックを動かすには、FileChanged を使います。Bash コマンドや Claude Code の外のプロセスが同じファイルを書き換えたとき、Claude Code は Edit|Write に一致する 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 の決定の制御#

ツールの実行後に Claude へフィードバックを出せます。全フックが使える JSON 出力のフィールドに加えて、次のイベント固有のフィールドを返せます。

Bash の呼び出しの出力を置き換える例です。置換する値は Bash ツールの出力の形に合っています。

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

auto モードの分類器へ結果を注釈する#

classifierContext を返すと、ツール呼び出しの結果についての短い注記を、Claude にでなく auto モードの分類器へ送ります。分類器はツールの結果そのものを受け取らないので、このフィールドは、分類器が後の操作を審査する前に、呼び出しが何を返したかを伝える、サポートされた方法です。v2.1.236 以降が必要です。クエリの出力がどこから来たかを分類器に伝える例：

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

分類器がその注記にどれだけ重みを置くかは、フックを設定した場所で決まります。

• Claude Code で設定したフック（設定ファイル・プラグイン・スキル・エージェントの frontmatter）：分類器は、注記を、アプリケーションが与えた、未検証の文脈として扱う。注記がユーザーの意図を確立することは無く、あなたが承認した・要求したと主張していれば、分類器はその主張を、会話の中のあなた自身のメッセージと照らして確かめる
• プロセス内の Agent SDK のコールバック：Claude Code を組み込んだアプリケーションが、フックを TypeScript SDK のコールバックとして登録し、実行中のセッションで注記を返すと、分類器は、注記で中継されたユーザーの発言をユーザーの意図として重く見ることがある。そうした発言は、あなたが送るメッセージなら分類器が受け入れる同意の要件を満たせるが、あなた自身のメッセージでも解けないブロックは、解けない。セッションの再開後、Claude Code は復元した注記を未検証の文脈として扱う。両方のグループのフックが同じ呼び出しに注釈を付けると、分類器は、結合した注記を未検証として扱う

注記を渡すとき、Claude Code は次の制限を適用します。

• 長さ：1つのツール呼び出しの注記を 2,000 文字に制限し、残りは切り詰める。この上限は、その呼び出しに応答するすべてのフックで共有される
• 同期のレスポンスだけ：バックグラウンドで動くフックのレスポンスのこのフィールドは無視される（そのレスポンスは、Claude Code がツールの結果を記録した後に届くため）
• 分類器が記録しない呼び出し：分類器の記録は、ファイルの読み取りや検索のような読み取り専用の参照を省く。そうした呼び出しに付けた注記は捨てられる
• 書き換えとの関係：updatedToolOutput で置き換える出力についての注記は、同じフックのレスポンスで両方のフィールドを返す。その書き換えが拒否されたり、別のフックの書き換えが置き換えたりすると、注記は捨てられる。書き換えなしで返した注記は、別のフックが出力を書き換えても渡される

PostToolUseFailure#

実行を始めたツールが失敗したとき（ツールがエラーを投げたとき、または MCP ツールがエラーの結果を返したとき）に動きます。失敗の記録・警告の送信・Claude への是正のフィードバックに使います。ツール名に一致します（値は PreToolUse と同じ）。

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 の決定の制御#

ツールの失敗の後に Claude へ文脈を渡せます。全フックが使える JSON 出力のフィールドに加えて、次のフィールドを返せます。

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

PostToolBatch#

バッチ内のすべてのツール呼び出しが解決した後、Claude Code が次のリクエストをモデルへ送る前に、1回だけ動きます。PostToolUse はツールごとに1回発火するので、Claude が並行してツール呼び出しをすると同時に発火します。PostToolBatch はバッチ全体を持って1回だけ発火するので、個々のツールでなく、動いたツールの組に依存する文脈を注入するのに向きます。このイベントに matcher はありません。

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 の決定の制御#

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 の入力#

共通の入力フィールドに加えて、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 の決定の制御#

拒否されたツール呼び出しをモデルが再試行してよいと伝えられます。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 を省くと、すべての通知の種類でフックが動きます。デスクトップ通知をオフにしていても、これらのフックイベントは受け取ります（preferredNotifChannel 設定は notifications_disabled を含め、あなたへの知らせ方だけを変え、フックが動くかは変えません）。

• quota_auto_resume_fired・quota_auto_resume_stale・quota_auto_resume_disabled の種類は v2.1.234 以降が必要です
• ターミナルセッションで、サンドボックス内のコマンドのネットワークリクエストの permission_prompt は v2.1.246 以降が必要です
• チームメイトの端末設定の質問の agent_needs_input は v2.1.248 以降が必要です

Agent SDK の canUseTool コールバック（Claude Desktop と VS Code 拡張が Claude 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 の入力#

共通の入力フィールドに加えて、通知のテキストの 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 は出します（フックの使い方のデスクトップ通知の例が頼っているのはこれです）。通知を外部のサービスへ転送するような、副作用のために使います。

SubagentStart#

Claude が Agent ツールでサブエージェントを起動したとき、Claude がサブエージェントを再開したとき、プロセス内のエージェントチームのチームメイトが新しいメッセージを処理するたびに動きます。エージェントの種類の名前で絞る matcher に対応します。組み込みのエージェントでは general-purpose・Explore・Plan などのエージェント名で、カスタムサブエージェントでは、ファイル名でなくエージェントの frontmatter の name フィールドです。

プラグインが提供するサブエージェントでは、エージェントの種類は、素の frontmatter の名前でなく、my-plugin:reviewer のようなプラグインのスコープ付きの識別子です。コロンがあるので、スコープ付きの名前は正規表現の経路に入り、完全一致させるには、^my-plugin:reviewer$ のように ^ と $ で固定します。

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 の入力#

共通の入力フィールドに加えて、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 が空のイベントでも動きます
• 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 の入力#

共通の入力フィールドに加えて、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 の決定の制御#

作成を、2通りでブロックできます。どちらでも、Claude Code はタスクを削除し、あなたのメッセージをツールのエラーとして Claude に返します。このイベントの continue: false は無視され、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 ツールでタスクを明示的に完了にしたとき、またはエージェントチームのチームメイトが、進行中のタスクを持ったままターンを終えたとき。タスクを閉じる前に、テストや lint の通過のような完了の基準を強制するのに使います。TaskCompleted のフックは matcher に対応せず、発生のたびに発火します。

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 の決定の制御#

タスクの完了を制御する方法は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_hook_active・last_assistant_message・background_tasks・session_crons を受け取ります。

• stop_hook_active は、Claude Code が、すでに Stop フックの結果として続行しているとき true です。解決しない条件でブロックし続けないよう、この値を確かめるか記録を処理します。

Claude Code は、連続8回の続行の上限を適用します：Stop フックがターンを8回続けて続行させると、Claude Code は次のブロックを上書きしてターンを終えます。続けて続行した回数は、Claude がツールを呼ぶたびにリセットされます。上限を上げるには 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 の入力#

共通の入力フィールドに加えて、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"
}

決定の制御はなく、通知と記録のためだけに動きます。

TeammateIdle#

エージェントチームのチームメイトが、ターンを終えた後にアイドルになろうとしているときに動きます。lint の通過を求める、出力ファイルが存在するか確かめるなど、チームメイトが作業をやめる前の品質ゲートの強制に使います。TeammateIdle のフックは matcher に対応せず、発生のたびに発火します。

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 の決定の制御#

チームメイトの挙動を制御する方法は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 の入力#

共通の入力フィールドに加えて、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 の決定の制御#

設定の変更が有効になるのをブロックできます。変更を防ぐには、終了コード 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 の入力#

共通の入力フィールドに加えて、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 出力のフィールドに加えて、FileChanged が監視するファイルパスを動的に設定する watchPaths を返せます。

決定の制御はなく、ディレクトリの変更をブロックできません。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 の入力#

共通の入力フィールドに加えて、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"
}

決定の制御はなく、追加はフックが動く時点ですでに完了しているのでブロックできません。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 の規則で、どのフックグループが動くかを絞ります

data.csv が（Bash コマンドや外部のスクリプトが書き換えた場合を含め）変わった後に、改行コードを正規化する例：

{
  "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 もすべてのファイルに一致しますが、Claude Code は、ほかの値と同じように、これを監視リストに、* という名前のリテラルのファイルとして登録します
• FileChanged のフックは CLAUDE_ENV_FILE を使えます。そのファイルに書いた変数は、次の CwdChanged イベントで Claude Code が消すまで、後続の Bash コマンドに残ります

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 出力のフィールドに加えて、監視するファイルパスを動的に更新する watchPaths を返せます。

決定の制御はなく、ファイルの変更が起きるのをブロックできません。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 の入力#

共通の入力フィールドに加えて、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 の出力#

標準の許可・ブロックの決定モデルは使いません。代わりに、フックの成功か失敗が結果を決めます。フックは、作成した 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 のフックを設定したなら、それが作った worktree の後始末を制御するため、WorktreeRemove のフックと組み合わせます。

• WorktreeRemove のフックが無い：--worktree のセッションを終了して削除を選んだとき、Claude Code は、WorktreeCreate のフックが返したパスに対する git worktree remove --force にフォールバックするので、git が認識する worktree は削除される。git が認識しない worktree（git 以外のバージョン管理システムでフックが作ったものなど）は、ディスクに残る。フックが作った worktree を持つバックグラウンドセッションを削除したときの扱いは、エージェントビューの削除の規則を参照

• フックが終了コード 0 で終わる：worktree は削除されたと数えられる。Claude Code はフックからほかに何も読まないので、フックがディレクトリを削除したことを確かめる

• フックが非 0 で終わる：その後も worktree_path のディレクトリが存在すれば、削除は失敗し、worktree は git へのフォールバックなしでディスクに残る。非 0 で終わる前にディレクトリを削除したフックは、削除されたと数えられる

• Claude Code は、フックが作った worktree のブランチを、決して削除しません。Claude Code が知っているのは、WorktreeCreate のフックが返したパスだけだからです。WorktreeCreate のフックがブランチを作るなら、WorktreeRemove のフックでそれを削除します

• Claude Code は、WorktreeRemove のフックの JSON 出力のフィールド（systemMessage と continue など）を捨てます

• バックグラウンドセッションの削除では、Claude Code は、フックを動かす前に、保存された worktree のパスを確かめ、シンボリックリンクであるパス、またはリポジトリルートより下でシンボリックリンクを通るパスを拒否します。まだファイルを含む worktree でフックが動くのは、エージェントビューで削除を確認したときだけです。そうした 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 の入力#

共通の入力フィールドに加えて、削除される worktree の絶対パスの 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 のフックの終了コードが結果を決めます。フックが非 0 で終わり、その後も worktree_path のディレクトリが存在すると、削除は失敗します。

• worktree はディスクに残り、フックのコマンドと stderr はデバッグログへ行く
• バックグラウンドセッションを削除していたなら、セッションも残る。エージェントビューの拒否メッセージが、フックがどう終わったか（exited 1 など）を報告し、stderr の最初の部分を引用して、もう一度セッションを削除すればディレクトリを削除できるかを述べる

PreCompact#

Claude Code がコンパクションを実行しようとする前に動きます。matcher の値は、コンパクションが手動か自動かを示します。

• コンパクションをブロックするには、終了コード 2 で終えます。手動の /compact では、stderr のメッセージがユーザーに出ます。"decision": "block" を持つ JSON を返してもブロックできます
• 自動コンパクションのブロックの効果は、発火した時点で違います。コンテキストの上限の前に先回りして起きたコンパクションなら、Claude Code はそれを飛ばし、会話はコンパクトされないまま続きます。API がすでに返したコンテキスト上限のエラーから復旧するために起きたコンパクションなら、元のエラーが表に出て、現在のリクエストは失敗します
• Claude Code は、PreCompact のフックの systemMessage と continue を捨てます

PreCompact の入力#

共通の入力フィールドに加えて、trigger と custom_instructions を受け取ります。manual では、custom_instructions はユーザーが /compact に渡した内容で、何も渡さなければ null です。auto では 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 の入力#

共通の入力フィールドに加えて、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..."
}

決定の制御はありません。コンパクションの結果には影響せず、後続の作業を行えます。

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 のあらゆる書き方をカバーします
• 切り替え先の正規名を判定できないとき（自分の LLM ゲートウェイだけが知るカスタムのモデル ID など）、Claude Code は matcher に関係なく、すべての PreModelSwitch のフックを動かします。そのため、ブロックするフックは、matcher だけに頼らず、入力の to_model を確かめます
• matcher は、完全な名前・claude-opus-4-6|claude-opus-5 のような | 区切りの一覧・.*opus.* のような正規表現で書きます

完全な名前の matcher を使い、フックの入力の to_model も確かめて、Opus 4.6 への切り替えを終了コード 2 で拒否し、ほかの切り替えは通す例（macOS・Linux）：

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

Windows では、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 の入力#

共通の入力フィールドに加えて、次の表のフィールドを受け取ります。最後の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 の決定の制御#

切り替えを取り消す・ユーザーに確認を求める・進めることができます。終了コード 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 に渡すのに使います（特定のモデルで適用される、組織全体の指示など）。v2.1.251 以降が必要です。モデルはすでに変わっているので、ブロックはできません。Claude Code は、次のどの変更の後でも PostModelSwitch のフックを動かします。

• あなたやクライアントが要求した切り替え
• セッションのモデルを変える、自動のモデルフォールバック
• opusplan のような設定がプランモードに入る・出るとき
• セッションを再開したときに Claude Code がモデルを復元するとき

フォールバックモデルのチェーンのモデルがターンを処理するときは、PostModelSwitch のフックを動かしません。その置き換えは1ターンだけで、セッションのモデルは変わらないためです。matcher は PreModelSwitch と同じ規則に従い、セッションが切り替わった先のモデルの正規名と比べます。セッションのモデルが 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 の入力#

PreModelSwitch と同じフィールドを受け取りますが、hook_event_name は "PostModelSwitch" で、source の値が2つ加わります：自動のフォールバックなど、Claude Code が自分で行った変更は "auto"、セッションを再開したときに復元したモデルは "resume" です。source が "auto" のとき requested_model は null で、"resume" のときは Claude Code が復元した、保存されたモデル設定です。

PostModelSwitch の決定の制御#

Claude Code は、終了コード 0 でのフックのプレーンテキストの stdout か、JSON 出力の additionalContext を受け取り、切り替え後の次のリクエストで Claude に届けます。全フックが使える JSON 出力のフィールドに加えて、次を返せます。

次のプロンプトを送った後、5秒たってもフックが終わっていなければ、Claude Code は出力なしでそのリクエストを送り、出力はその次のリクエストに付けます。次のリクエストまでにモデルが何度か変わったときは、Claude Code は、最後の切り替えの切り替え先のモデルの出力だけを届けます。

SessionEnd#

Claude Code のセッションが終わるときに動きます。後始末・セッションの統計の記録・セッションの状態の保存に向きます。終了の理由で絞る matcher に対応します。フックの入力の reason フィールドが、セッションが終わった理由を示します。

SessionEnd の入力#

共通の入力フィールドに加えて、セッションが終わった理由を示す reason フィールドを受け取ります。

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

決定の制御はなく、セッションの終了をブロックできませんが、後始末はできます。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 の入力#

共通の入力フィールドに加えて、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 の入力#

共通の入力フィールドに加えて、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 ツールのフックのほかに、LLM が操作を許可するかブロックするかを評価するプロンプト型フック（type: "prompt"）と、ツールを使える、エージェント的な検証者を起動するエージェント型フック（type: "agent"）があります。すべてのイベントがすべてのフックの種類に対応するわけではありません。

5種類（command・http・mcp_tool・prompt・agent）すべてに対応するイベント：

• PermissionRequest にエージェント型フックを設定しても、Claude Code はそれを飛ばし、権限の流れは変わらず進みます。フックから許可や拒否をするには、コマンドか HTTP のフックから決定オブジェクト（PermissionRequest の決定の制御）を返します
• SessionStart と Setup の mcp_tool フックがいつ動くかは、MCP ツールフックのフィールドの節に書いてあります

プロンプト型フック#

コマンドを実行する代わりに、プロンプト型フックは次のように動きます。

1. フックの入力とあなたのプロンプトを Claude のモデルに送る（既定は、Claude Code がバックグラウンドの機能に使うモデル）
2. LLM が、判定を含む構造化された JSON で応答する
3. Claude Code が判定を自動で処理する

プロンプト型フックの設定#

type を "prompt" にし、command の代わりに prompt の文字列を指定します。$ARGUMENTS のプレースホルダーで、フックの JSON 入力データをプロンプトのテキストに差し込みます。Claude が終える前に、すべての作業が完了したかを LLM に評価させる Stop フックの例：

{
  "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：ツール呼び出しは拒否される。既定ではターンが終わり、拒否の理由が警告行としてチャットに出る。continueOnBlock: true にすると、代わりに理由をツールエラーとして Claude に返し、Claude が調整して続けられる（コマンドフックの 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 を1回呼ぶ代わりに、ファイルを読み、コードを検索し、コードベースを調べて条件を確かめるサブエージェントを起動します。PermissionRequest を除き、プロンプト型フックと同じイベントに対応します。

エージェント型フックが発火したときの流れ：

1. Claude Code が、あなたのプロンプトとフックの JSON 入力を持つサブエージェントを起動する
2. サブエージェントが、Read・Grep・Glob などのツールで調べられる
3. 最大 50 ターンの後、サブエージェントが構造化された { "ok": true/false } の判定を返す
4. ok が true なら、Claude Code は操作を許す。ok が false なら、Claude Code は、応答のスキーマにあるように、そのイベントで continueOnBlock: true を付けたプロンプト型フックと同じようにブロックを扱う

検証が、フックの入力データの評価だけでなく、実際のファイルやテストの出力を調べる必要があるときに役立ちます。

エージェント型フックの設定#

type を "agent" にし、prompt の文字列を指定します（$ARGUMENTS はフックの入力 JSON のプレースホルダー）。設定のフィールドはプロンプト型フックと同じですが、エージェント型フックは既定のタイムアウトがより長い 60 秒で、continueOnBlock フィールドはありません。応答のスキーマは、許可なら { "ok": true }、ブロックなら { "ok": false, "reason": "..." } です。ok: false のとき、Claude Code は、同じイベントで continueOnBlock: true を付けたプロンプト型フックと同じように扱います。エージェント型フックには continueOnBlock フィールドも、プロンプト型の impossible フィールドへの対応もありません。

Claude が終える前に、すべてのユニットテストが通ることを確かめる Stop フックの例：

{
  "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 で動かすフックでは、timeout を引き続き強制します
• Claude Code が非同期のフックの結果を届けるのは、セッションが動いている間だけです。-p フラグの非対話モードでは、終了処理の時点でまだ動いている非同期のフックを Claude Code が kill し、結果を 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 モードをオンにするか、--verbose で Claude Code を起動します

例：ファイルの変更後にテストを動かす#

Claude がファイルを書くたびに、バックグラウンドでテストスイートを動かし、テストが終わったら結果を Claude に報告するフックです。次のスクリプトをプロジェクトの .claude/hooks/run-tests-async.sh に保存し、chmod +x で実行権限を付けます。

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

# Read hook input from stdin
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Only run tests for source files
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Run tests and report results to Claude via additionalContext
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
          }
        ]
      }
    ]
  }
}

非同期フックの制約#

同期のフックに比べて、非同期のフックにはさらに制約があります。

• フックの出力は次の会話のターンで届く。セッションがアイドルなら、次のユーザーの操作まで応答が待つ。例外：終了コード 2 で終わる asyncRewake のフックは、セッションがアイドルでも Claude をすぐ起こす
• 実行のたびに別のバックグラウンドのプロセスが作られる。同じ非同期フックが何度発火しても、重複は取り除かれない

セキュリティ#

ワークスペースの信頼#

Claude Code は、設定ファイルのフックを動かす前に、ワークスペースの信頼を確かめます。何が信頼済みとして数えられるかは、セッションの種類で決まります。

• 対話セッション：Claude Code は、そのフォルダ（またはその信頼が及ぶ親ディレクトリ）のワークスペースの信頼ダイアログを承認するまで、あなた自身の ~/.claude/settings.json を含むすべての設定ファイルのフックを動かさない
• -p または SDK セッション：Claude Code はダイアログを出さず、フォルダを信頼済みとして扱うので、リポジトリの .claude/settings.json にコミットされたフックは、一度も信頼していないフォルダで動く

自分が書いていないリポジトリに対して claude -p をスクリプトで動かす前に、その .claude/ の設定ファイルを確認するか、--bare で始めるか、--settings '{"disableAllHooks": true}' でその実行のフックをオフにします。プロジェクトのサブエージェントの frontmatter のフックは、設定ファイルのフックより厳しい規則に従います。

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

フックを書くときは、次を心に留めます。

• 入力を検証し無害化する：入力データを決して盲目的に信頼しない
• シェルの変数は必ず引用符で囲む：$VAR ではなく "$VAR"
• パストラバーサルを防ぐ：ファイルパスの .. を確かめる
• 絶対パスを使う：スクリプトにフルパスを指定する。exec 形式では ${CLAUDE_PROJECT_DIR} を使えば、パスに引用符は要らない。シェル形式では二重引用符で囲む
• 機密のファイルを避ける：.env・.git/・鍵などは対象にしない

Windows の PowerShell で動かす#

Windows では、コマンドフックに "shell": "powershell" を設定して、個々のフックを PowerShell で動かせます。Claude Code は、PowerShell 7 以降の実行ファイル pwsh.exe を自動で検出し、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 は、PowerShell のシェル形式のコマンドの ${CLAUDE_PROJECT_DIR}・${CLAUDE_PLUGIN_ROOT}・${CLAUDE_PLUGIN_DATA} のプレースホルダーを、settings.json・プラグイン・スキルのどこで定義されたフックでも、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 フラグは、ターミナルには出力しません。

• たとえば、hook-ran を出力するコマンドを持つ Write への PostToolUse のフックは、次のような項目を作ります

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・設定の優先順位を含む、より広い診断の手順は設定のデバッグにあります