Hooks リファレンス

​

フック ライフサイクル

• セッションごとに 1 回：SessionStart と SessionEnd
• ターンごとに 1 回：UserPromptSubmit、Stop、StopFailure
• エージェント型ループ内のすべてのツール呼び出しで：PreToolUse と PostToolUse。ただし、EndConversation の呼び出しは両方をスキップします

​

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

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

#!/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

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

# .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
}

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

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

​

設定

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

​

フック位置

• ユーザー、プロジェクト、ローカル、プラグインのフックはブロックされます。管理設定の enabledPlugins で強制的に有効化されたプラグインのフックは除外されます
• Claude Code は、statusLine、fileSuggestion、subagentStatusLine の設定も管理設定のものに限定します
• Claude Code は、command ソースを持つプラグインも無効化します。これには管理設定の enabledPlugins で強制的に有効化されたプラグインも含まれます。ただし、disableCommandPluginSources が明示的に false に設定されている場合は除きます。command ソースには Claude Code v2.1.229 以降が必要です
• Claude Code は、マーケットプレイスの headersHelper コマンドもブロックします。ただし、disableCommandPluginSources が明示的に false に設定されている場合は除きます。また、管理設定自体が宣言しているマーケットプレイスは対象外です

• allowedHttpHookUrls: いずれかの設定レベルで定義されている場合、Claude Code は URL がマージされた許可リストに一致する HTTP フックハンドラーのみを実行します
• httpHookAllowedEnvVars: 定義されている場合、Claude Code はそのリストにある環境変数のみをフックヘッダーに補間します

​

Matcher パターン

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

​

MCP ツールをマッチ

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

• mcp__memory__.* は memory サーバーのすべてのツールにマッチ
• mcp__brave-search__.* は名前にハイフンを含むサーバーのすべてのツールにマッチ
• mcp__.*__write.* は任意のサーバーの、名前が write で始まるツールにマッチ

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

​

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

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

​

共通フィールド

​

if パターンが Bash コマンドにマッチする仕組み

​

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

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

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

​

HTTP フック フィールド

{
  "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 ツール フック フィールド

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

​

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

​

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

• ${CLAUDE_PROJECT_DIR}: セッションを開始したプロジェクトルート。Claude Code はこの変数を stdio MCP サーバーとプラグイン LSP サーバーの環境にも設定します。
• ${CLAUDE_PLUGIN_ROOT}: プラグインのインストールディレクトリ。プラグインにバンドルされたスクリプト用です。更新時にこのパスがどう扱われるかについては、プラグインの環境変数を参照してください。
• ${CLAUDE_PLUGIN_DATA}: プラグインの永続データディレクトリ。プラグインの更新後も保持すべき依存関係と状態用です。

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

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

​

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

• サブエージェントのフック: Claude Code は、そのサブエージェントの実行中にのみこれらを実行し、サブエージェントが終了すると削除します。ここでの Stop フックは、Claude Code によって SubagentStop に変換されます。これはサブエージェントが完了したときに発火するイベントです。
• スキルのフック: Claude Code は、ユーザーまたは Claude がスキルを呼び出したときにこれらを登録し、スキル自体のターンの後のターンも含めて、セッションの残りの期間ずっと実行し続けます。代わりに最初の実行が成功した後で Claude Code にフックを削除させるには、そのフックに once: true を設定します。

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

​

スキルのフックの制限

• プラグイン専用ロック: 組織の管理者は、strictPluginOnlyCustomization 管理設定を使用して、フックをプラグインと管理設定に限定できます。このロックの下でスキルがフロントマターのフックを保持できるのは、プラグインスキル、バンドルスキル、または管理設定ディレクトリ内のスキルである場合のみです。ユーザー自身の設定ファイルのフックも実行されません。
  • 確認: Claude Code セッションで /status と入力します。Setting sources 行に Enterprise managed settings が含まれている場合は、strictPluginOnlyCustomization がフックをロックしているかどうかを管理者に確認してください。
  • 対処: プラグインスキルはフロントマターのフックを保持するため、スキルをプラグインに移動します。そのプラグインをマーケットプレイスに掲載し、そこからインストールします。Claude Code が is blocked by enterprise policy でマーケットプレイスを拒否する場合は、そのマーケットプレイスを許可するよう管理者に依頼してください。
• フックの上限: Claude Code v2.1.304 以降では、スキルのソースごとにセッション単位の上限があります。プロジェクト、個人のスキルフォルダー、各プラグインは、それぞれ別のソースとして数えられます。1 つのソースのスキルが登録できるフックは最大 1,024 個です。それらのフックの matcher の合計は最大 16,384 文字です。配下に複数のフックを持つ matcher は、フックごとに 1 回ずつ数えられます。
  • 確認: デバッグログを有効にして、フックが発火しなかったセッションを再現します。
    1. シェルから claude --debug で新しいセッションを開始します。シェルからセッションを開始しない場合は、代わりに新しいセッションで最初に /debug と入力します。
    2. Claude が呼び出したものも含め、同じスキルを同じ順序で呼び出します。両方の合計はスキルごとに積み上がるためです。コマンドとして入力できないスキルは、呼び出すよう Claude に依頼してください。
    3. デバッグログで registers none of its hooks を検索します。このテキストを含む行に、上限を超えたスキルの名前が示されます。
  • 対処: そのスキル、または同じソースの他のスキルで宣言するフックを減らすか matcher を短くしてから、新しいセッションを開始します。それらのスキルを自分で編集できない場合は、作成者に変更を依頼してください。それまでは、新しいセッションを開始し、必要なスキルを同じソースの他のスキルより先に呼び出してください。

​

/hooks メニュー

​

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

​

フック入出力

​

共通入力フィールド

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

​

終了コード出力

• 成功: フックが 0 で終了します。Claude Code はフックが出力した JSON 出力フィールドを適用し、それらのフィールドがアクションをブロックまたは拒否しない限り、アクションは進行します。例外についてはバックグラウンド プロセスを開始するフックを参照してください。
• ブロッキング エラー: フックが 2 で終了します。ブロック可能なイベントでは、Claude Code はアクションを停止します。
• 非ブロッキング エラー: フックがその他のコードで終了するか、起動しない、無効な JSON を出力するなど、その他の方法で失敗します。アクションは進行します。ただし、onFailure を "block" に設定したフックなど、失敗時にアクションをブロックするフックは例外です。PreToolUse などのイベントでは、トランスクリプトに <hook name> hook error 通知が表示されます。

• WorktreeCreate: JSON の内容にかかわらず、0 以外の終了コードで worktree の作成が失敗します。
• WorktreeRemove: 0 以外の終了コードは、その後もディレクトリが存在する場合に worktree の削除を失敗させます。
• Stop、SubagentStop、TaskCompleted、およびプラグインの UserPromptSubmit フック: フックが stdout に何も出力せずに 2 で終了し、stderr に No such file or directory のようにファイルが見つからないことが示されている場合、Claude Code はその実行を非ブロッキング エラーとして扱います。
• Elicitation と ElicitationResult: Claude Code はフックが 0 で終了した場合に hookSpecificOutput を適用し、その他の終了コードでは無視します。
• StopFailure などフック出力を破棄するイベント: Claude Code はすべての終了コードで JSON を無視します。ただし、terminalSequence のような副作用フィールドは引き続き発火します。

​

終了コード 0

• { で始まらない出力、または { で始まり } で終わらない出力: プレーン テキストとして扱われます。このルールにより、JSON 配列や引用符で囲まれた JSON 文字列はプレーン テキストになります。
• それぞれが単独で JSON として解析できる 2 行以上の出力で、最初の行が { で始まり最後の行が } で終わるもの: フィールドを設定する JSON 出力オブジェクトである行がない場合はプレーン テキストになります。そのような行がある場合、出力は解析失敗になるため、そのオブジェクトだけを stdout に出力してください。
• { で始まり } で終わるが有効な JSON ではないその他の出力: 解析失敗になります。

​

終了コード 2

• スキーマ検証に合格する JSON: Claude Code は JSON 出力フィールドを引き続き読み取りますが、それらでブロックを上書きすることはできません。permissionDecision が "allow" であっても、アクションは通過しません。Elicitation と ElicitationResult では、終了 2 のフックの hookSpecificOutput は無視されます。
• スキーマ検証に失敗する JSON: フックは引き続きブロックします。Claude Code は stderr をブロッキング理由として使用し、検証の失敗をデバッグ ログに記録します。

#!/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

PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed

​

その他の終了コード

Failed with non-blocking status code: something broke

Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory

​

タイムアウト

​

バックグラウンド プロセスを開始するフック

#!/bin/bash
"$CLAUDE_PROJECT_DIR"/.claude/hooks/policy-check.sh || exit $?
"$CLAUDE_PROJECT_DIR"/.claude/hooks/upload-metrics.sh >/dev/null 2>&1 &

• || exit $?: チェックの終了コードをフック自身の終了コードにします。これにより、拒否のために 2 で終了するチェックは引き続きブロックします。これがない場合、フックは最後の行の終了コード（0）で終了します。
• >/dev/null 2>&1 &: 出力をリダイレクトした状態で upload-metrics.sh をバックグラウンドで実行するため、フックの出力が開いたままになりません。

​

フックが失敗したときにアクションをブロックする

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'

• 起動できない: コマンド フックが起動に失敗する（例えば、スクリプトや実行可能ファイルが存在しないため）
• 0 または 2 以外の終了コード: permissionDecision: "allow" のようにアクションを許可する JSON を出力した場合でも、コマンド フックでは失敗としてカウントされます。JSON の決定を返すには、0 で終了してください
• HTTP エラー: HTTP フックの接続が失敗するか、レスポンスのステータスが 2xx ではない
• タイムアウト: フックが timeout に達する
• 無効な出力: JSON 出力が解析できないか、スキーマ検証に失敗する。HTTP フックの場合、空でも JSON オブジェクトでもない 2xx 本体も該当します。コマンド フックからのプレーン テキストの stdout は失敗ではありません

• Stop、SubagentStop、TaskCompleted、TeammateIdle フック: これらのイベントでの終了コード 2 は Claude を作業に戻しますが、Claude は実行されないフックを修復できません
• バックグラウンド コマンド フック: async または asyncRewake を設定したコマンド フック

​

Git Bash のない Windows で失敗したフック

blocking because Git Bash wasn't found, so only exit code 0 or 2 counts as this hook's verdict.

• フックが失敗したときにアクションを進行させたい: フックに "onFailure": "continue" を追加します
• フックが Bash 向けに書かれている: shell が設定されていないシェル形式のフックは、Git Bash がインストールされていない場合は PowerShell で実行され、Bash 向けに書かれたスクリプトはそのままでは実行できないことがあります。Git for Windows をインストールするか、Claude Code が見つけられない場所に Git Bash がインストールされている場合は CLAUDE_CODE_GIT_BASH_PATH を設定してから、新しいセッションを開始します
• フックが .cmd や .bat ファイルではなく 1 つの .exe を実行する: プログラムを command に、その引数を args に指定して exec 形式を使用し、"onFailure": "block" を追加します。これにより Claude Code はシェルを介さずにプログラムを起動します。"onFailure": "block" がない場合、プログラムが失敗した、存在しない、またはタイムアウトしたときに呼び出しが進行することがあります
• フックは警告のために 1 で終了するが、クラッシュしたときはブロックする必要がある: "onFailure": "continue" では、警告であってもクラッシュであっても、終了コード 1 で呼び出しが進行します。代わりに "onFailure": "block" を追加し、警告する箇所ではスクリプトを終了コード 0 で終了させて、それらの呼び出しが進行するようにします。終了コード 0 の後に PreToolUse で警告を表示するには、1 つの JSON オブジェクトの systemMessage フィールドに入れて stdout に出力します
• 失敗時にブロックする必要がある PowerShell のガード フック: onFailure が未設定の場合、Git for Windows がインストールされて Claude Code が Git Bash を見つけると、ブロックしなくなります。Git Bash の有無にかかわらず失敗やタイムアウトで呼び出しがブロックされるよう、"onFailure": "block" を追加します。また、それ以降も Git Bash ではなく PowerShell でフックが実行され続けるよう、"shell": "powershell" も設定します

​

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

​

HTTP レスポンス処理

• 2xx で空の本体: 成功、終了コード 0 で出力なしと同等
• 2xx で JSON オブジェクト本体: コマンド フックと同じ JSON 出力スキーマを使用して解析。スキーマ検証に失敗した本体は非ブロッキング エラー
• 2xx でその他の本体（プレーン テキストなど）: 非ブロッキング エラー。2xx 以外のステータスと同じように処理されます。Claude Code はテキストを Claude のコンテキストに追加しません
• 2xx 以外のステータス: 非ブロッキング エラー
• 接続失敗: 非ブロッキング エラー
• タイムアウト: タイムアウトで説明されているとおり、フックはキャンセルされます

​

JSON 出力

• スコープ: 同じイベントに対して複数のフックが実行される場合でも、Claude Code は各文字列を個別に計測します。JSON 出力の場合、各フィールドは個別に計測されます。プレーン stdout は全体として計測されます。
• 制限を超えた場合: Claude Code は出力をセッション ディレクトリ内のファイルに保存し、ファイル パスと最初の最大 2,000 文字のプレビューに置き換えます。大きな有効な Bash 結果も同じ方法で処理されます（出力制限で説明）。その Bash の上限とは異なり、この上限を引き上げる設定や環境変数はありません。
• ファイルの読み取り: Claude Code は Claude にファイルを読むよう求めないため、Claude が常に確認する必要があるものは上限内に収めてください。

• continue などのユニバーサル フィールドは以下の表にリストされています。すべてのイベントがこれらを受け入れますが、一部のイベントはこれらを破棄するか、systemMessage をトランスクリプト以外の場所に配信します。各イベントのセクションにその旨が記載されています。terminalSequence もそれらのイベントで機能しますが、ターミナル通知を発行に記載されている例外があります。
• トップレベルの decision と reason は一部のイベントで使用され、ブロックまたはフィードバックを提供します。
• hookSpecificOutput はより豊かな制御が必要なイベント用のネストされたオブジェクトです。イベント名に設定された hookEventName フィールドが必要です。

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

​

ターミナル通知を発行

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

• Claude Code は対話セッションでのみ、かつそのインターフェイスが画面に表示されている間のみシーケンスを書き込みます。-p フラグを使用した非対話モードおよび Agent SDK では、このフィールドは無視されます。
• WorktreeCreate コマンド フックは JSON を返せません。Claude Code はその stdout を worktree パスとして読み取るためです。HTTP WorktreeCreate フックは 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}'

​

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

{
  "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 はフィードバックに対応できます。Stop 決定制御を参照してください
• PostModelSwitch: 切り替え後の次のリクエストとともに。タイミングについては PostModelSwitch 決定制御を参照してください

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

​

決定制御

• PreToolUse: hookSpecificOutput の直下の updatedInput は、ツールが実行される前にそのツールの引数を置き換えます。PreToolUse 決定制御を参照してください
• PermissionRequest: decision オブジェクト内の updatedInput。PermissionRequest 決定制御を参照してください
• PostToolUse: updatedToolOutput はツールの結果を置き換えます。PostToolUse 決定制御を参照してください
• UserPromptSubmit: プロンプトを置き換えることはできません。additionalContext をそれと一緒に注入するだけです

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

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

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

​

フックイベント

​

SessionStart

​

SessionStart の入力

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

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

​

フックがインストールしたスキルを再読み込みする

#!/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}}'

​

環境変数を永続化する

#!/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

• 空行または # コメント
• 行頭にある 1 つの代入で、export NAME=value、declare -x NAME=value、または NAME=value の形式で記述され、Bash が記述どおりにそのまま使用する値であるもの。値は次の部分を任意に組み合わせたものです：英字、数字、_ @ % + = : , . / - の文字のみを使用するクォートなしのテキスト、シングルクォートで囲まれたテキスト、内部の $、バッククォート、" がすべてバックスラッシュでエスケープされたダブルクォートで囲まれたテキスト

​

Setup

​

Setup の入力

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

​

Setup の決定制御

​

InstructionsLoaded

​

InstructionsLoaded の入力

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

​

InstructionsLoaded の決定制御

​

UserPromptSubmit

• /loop の反復を含む、セッションスコープのスケジュールタスクが発火したとき
• バックグラウンドのサブエージェントが、それを開始したセッションに報告を返すとき
• 別のセッションが送信したメッセージがメインの会話に届くとき

​

UserPromptSubmit の入力

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

• プレーンテキストの stdout：Claude Code は、プレーンテキストとして扱う stdout を Claude のコンテキストに追加します
• additionalContext を含む JSON：より細かく制御するには、以下の JSON 形式を使用します。additionalContext フィールドがコンテキストとして追加されます

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

​

ブロックされたプロンプトが残すもの

​

UserPromptExpansion

​

UserPromptExpansion の入力

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

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

​

MessageDisplay

• 最小限の表示のために markdown を除去する
• Agent SDK アプリケーションがユーザーに表示するテキストを変換する
• Claude の応答から API キーや内部ホスト名を秘匿する

​

MessageDisplay の入力

{
  "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 の出力

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

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

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "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

​

PreToolUse

​

PreToolUse の入力

• Claude Code はフックの実行前に ~ と相対パスを展開するため、パスでマッチするフックが ~ や同じパスの相対表記によって回避されることはありません
• Windows では、フックが $PWD が /c/project のように見える Git Bash で実行される場合でも、パスはバックスラッシュ区切りで届きます
• /src/ のチェックなど、スラッシュで書かれた比較はバックスラッシュのパスには決してマッチせず、ツール呼び出しはフックがブロックするものがなかったかのように続行されます
• 比較の前に区切り文字を正規化してください。Bash では FILE_PATH="${FILE_PATH//\\//}"、Python では file_path.replace("\\", "/") を使用します。その後、パスは絶対パスなので、^ で先頭を固定するのではなく、/src/ などのパスセグメントでマッチさせます

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

• Windows では、PowerShell ツールが有効になっている場合は常に、Claude は PowerShell をプライマリシェルとして扱い、シェルコマンドをそれ経由で実行します。
• Git Bash のない Windows では、このツールが自動的に有効になり、Claude Code は Bash ツールをまったく登録しません。
• Bash のみにマッチするフックは、そこでは決して発火しません。

​

PreToolUse の決定制御

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

​

ユーザーの操作を必要とするツール

1. stdin からツールの入力を読み取る
2. 独自の UI で回答を収集する
3. 回答を保持する updatedInput とともに permissionDecision: "allow" を返し、プロンプトなしでツールが実行されるようにする

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

​

ツール呼び出しを後回しにする

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 が続行します。

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

• 再開時またはその後にプロンプトを送信しなかった場合、呼び出しはまだ保留中です。ツールが利用できる状態で再度再開すると、最初にそれが実行されます。
• 再開時またはその後にプロンプトを送信した場合、Claude Code はツールの結果なしでプロンプトに応答し、保留された呼び出しを破棄します。引き続きツールを呼び出す必要がある場合は、ツールが利用可能になった時点で新しいプロンプトを送信してください。

​

PermissionRequest

​

PermissionRequest の入力

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

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

​

権限更新エントリ

​

PostToolUse

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

​

PostToolUse の入力

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