Hooks reference

一行要約

hooks-guide が「何ができるか」を説明するのに対し、こちらは exit code 2 がイベントごとにどう振る舞うか、イベントごとの決定制御の形、ハンドラ種別ごとのフィールドという、書くときに毎回引く3つの表。

解説と例は hooks-guide を参照。この文書はそこに載っていないリファレンス部分だけを収録している。

要点

全 hook が受け取る共通フィールド

command hook は stdin、HTTP hook は POST ボディで受け取る。

フィールド	内容
`session_id`	現在のセッション識別子
`prompt_id`	ユーザープロンプトを識別する UUID
`transcript_path`	会話 JSON へのパス（現在のターンより遅れることがある）
`cwd`	現在の作業ディレクトリ
`permission_mode`	`"default"` / `"plan"` / `"acceptEdits"` / `"auto"` / `"dontAsk"` / `"bypassPermissions"`
`effort`	`level` を持つオブジェクト
`hook_event_name`	発火したイベント名
`agent_id`	subagent の識別子（subagent 文脈のみ）
`agent_type`	エージェント名（`"Explore"` など）

exit code 2 の挙動（イベント別）

exit code 2 は「止めろ、これをするな」の合図。 ただし効果はイベントで違う。

ブロックできるもの:

イベント	exit 2 の効果
`PreToolUse`	ツール呼び出しをブロック
`PermissionRequest`	権限を拒否
`UserPromptSubmit`	プロンプト処理をブロックし、プロンプトを消去する
`UserPromptExpansion`	展開をブロック
`Stop`	Claude が止まるのを防ぎ、会話を続けさせる
`SubagentStop`	subagent が止まるのを防ぐ
`TeammateIdle`	teammate が idle になるのを防ぐ
`TaskCreated`	タスク作成をロールバックする
`TaskCompleted`	完了マークを防ぐ
`ConfigChange`	設定変更をブロック（`policy_settings` を除く）
`PreCompact`	compaction をブロック
`Elicitation`	elicitation を拒否
`ElicitationResult`	応答をブロック（action が decline になる）
`WorktreeCreate`	非ゼロの exit code はすべて作成を失敗させる
`PostToolBatch`	次のモデル呼び出しの前に agentic ループを止める

ブロックできないもの:

イベント	exit 2 の効果
`PostToolUse` / `PostToolUseFailure`	stderr を Claude に見せる（ツールは既に走っている）
`PermissionDenied`	exit code と stderr は無視される。 JSON の `retry: true` を使う
`Notification` / `SubagentStart` / `SessionStart` / `Setup` / `SessionEnd` / `CwdChanged` / `FileChanged` / `PostCompact`	stderr をユーザーにだけ見せる
`DirectoryAdded`	stderr は debug ログへ
`WorktreeRemove`	失敗は debug モードでのみ記録
`InstructionsLoaded`	exit code は無視
`StopFailure`	出力も exit code も無視
`MessageDisplay`	元のテキストが表示される

決定制御の形（イベント別）

イベント	決定の形	主なフィールド
`UserPromptSubmit`, `UserPromptExpansion`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `Stop`, `SubagentStop`, `ConfigChange`, `PreCompact`	トップレベルの `decision`	`decision: "block"`, `reason`
`TeammateIdle`, `TaskCreated`, `TaskCompleted`	exit code または `continue: false`	`{"continue": false, "stopReason": "..."}`
`PreToolUse`	`hookSpecificOutput`	`permissionDecision`（allow/deny/ask/defer）, `permissionDecisionReason`
`PermissionRequest`	`hookSpecificOutput`	`decision.behavior`（allow/deny）
`PermissionDenied`	`hookSpecificOutput`	`retry: true`
`WorktreeCreate`	パスを返す	command hook は stdout にパスを出す。HTTP hook は `hookSpecificOutput.worktreePath`
`Elicitation` / `ElicitationResult`	`hookSpecificOutput`	`action`（accept/decline/cancel）, `content`
`MessageDisplay`	`hookSpecificOutput`	`displayContent`（表示のみ置き換え。transcript は変わらない）
`SessionStart`, `Setup`, `SubagentStart`	context のみ	`additionalContext`。SessionStart は加えて `initialUserMessage`, `watchPaths`, `sessionTitle`, `reloadSkills`
`WorktreeRemove`, `Notification`, `SessionEnd`, `PostCompact`, `InstructionsLoaded`, `StopFailure`, `CwdChanged`, `DirectoryAdded`, `FileChanged`	なし	副作用のみ

内容の書き換え:

イベント	書き換えフィールド
`PreToolUse`	`hookSpecificOutput` 直下の `updatedInput` がツール引数を置き換える
`PermissionRequest`	`decision` オブジェクトの中の `updatedInput`
`PostToolUse`	`updatedToolOutput` がツール結果を置き換える
`UserPromptSubmit`	プロンプトは置き換えられない。 `additionalContext` の注入のみ

全 JSON 出力に共通のフィールド

フィールド	既定	内容
`continue`	`true`	`false` で Claude が完全に停止する。イベント固有の決定より優先される
`stopReason`	—	`continue: false` のときユーザーに見せるメッセージ。Claude には見せない
`suppressOutput`	`false`	`true` で hook の stdout を transcript から隠す（debug ログには残る）
`systemMessage`	—	ユーザーに見せる警告
`terminalSequence`	—	端末エスケープシーケンス（OSC `0`/`1`/`2`/`9`/`99`/`777` または BEL）。カーソル移動や色変更を防ぐため制限された allowlist
`additionalContext`	—	system reminder として Claude の context に注入される文字列。上限 10,000 文字

ハンドラ種別ごとのフィールド

command hook:

フィールド	必須	内容
`type`	○	`"command"`
`command`	○	実行するシェルコマンド。`args` があると実行可能ファイルとして解決し直接 spawn する
`args`	—	引数リスト。あると exec 形式（シェルを介さない）
`async`	—	`true` でブロックせずバックグラウンド実行
`asyncRewake`	—	`true` でバックグラウンド実行し、exit code 2 で Claude を起こす。 `async` を含意する
`shell`	—	`"bash"`（既定）または `"powershell"`
`if`	—	permission rule 構文のフィルタ。ツールイベントのみ
`timeout`	—	秒。既定 600（`UserPromptSubmit` は 30、`MessageDisplay` は 10）
`statusMessage`	—	実行中に出すスピナーのメッセージ
`once`	—	`true` でセッション中1回だけ走って削除される（skill / agent frontmatter 専用）

exec 形式 vs シェル形式: args があるとシェルを介さず、各要素が書いたとおりに1つの引数になる（特殊文字はそのまま渡る）。args を省くとシェルに渡され、パイプ・&&・リダイレクト・glob が使える。

HTTP hook — url（必須）、headers（$VAR_NAME / ${VAR_NAME} 展開）、allowedEnvVars（展開を許す変数名のリスト）。

応答の扱い:

応答	扱い
2xx + 空ボディ	成功（exit 0 相当）
2xx + プレーンテキスト	成功。context として追加される
2xx + JSON	JSON 出力スキーマとしてパース
非 2xx または接続失敗	ブロックしないエラー。実行は続く

To block, return 2xx JSON with appropriate decision fields. HTTP のステータスコードだけではブロックできない。

MCP tool hook — server（plugin 同梱なら plugin:<plugin-name>:<server-name>）、tool、input（文字列は hook 入力からの ${path} 置換をサポート、例: "${tool_input.file_path}"）。

サーバは既に接続済みでなければならない。 hook が OAuth や接続フローを起こすことはない。未接続、またはツールが isError: true を返すと、ブロックしないエラーになり実行は続く。

prompt hook — prompt（$ARGUMENTS が hook 入力 JSON に置換される）、model（既定は fast model）、timeout の既定は 30 秒。

agent hook — 同上だが timeout の既定は 60 秒。

非同期 hook

フィールド	内容
`async`	バックグラウンドで走り、Claude Code をブロックしない
`asyncRewake`	バックグラウンドで走り、exit code 2 で Claude を起こす。stderr（空なら stdout）が system reminder として Claude に見える

用途: CI やデプロイのような長時間の処理。Claude は待つ間も作業を続けられ、失敗したら起こされる。

skill / agent の frontmatter に書く hook

全イベントがサポートされる。 subagent では Stop hook が自動的に SubagentStop に変換される。

設定ファイルと同じ形式だが、そのコンポーネントの寿命にスコープされ、終了時に片付けられる。

Trust requirement (v2.1.218+): project subagent の frontmatter hook は、そのエージェントファイルが由来するフォルダの workspace trust ダイアログを承認した後にのみ走る。

そのまま使える具体例

skill の frontmatter に hook を書く:

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

長時間の CI を待たずに走らせ、失敗したら Claude を起こす:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/run-ci.sh",
            "asyncRewake": true,
            "statusMessage": "CI running in background"
          }
        ]
      }
    ]
  }
}

exec 形式で特殊文字をそのまま渡す:

{
  "type": "command",
  "command": "/usr/local/bin/my-hook",
  "args": ["--pattern", "a && b || c"]
}

MCP ツールを hook として呼ぶ（${path} で hook 入力を差し込む）:

{
  "type": "mcp_tool",
  "server": "audit-service",
  "tool": "log_edit",
  "input": {
    "path": "${tool_input.file_path}",
    "session": "${session_id}"
  }
}

PostToolUse でツール結果を書き換える:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "updatedToolOutput": "..."
  }
}

Claude を完全に止める（イベント固有の決定より優先される）:

{
  "continue": false,
  "stopReason": "Deployment window is closed until Friday."
}

原典で言及されている関連文書

hooks-guide — 解説と使用例（この文書の対になる文書）
permissions — exit code 2 が allow ルールより優先されること
skills — skill frontmatter の hooks
sub-agents — subagent frontmatter の hooks、Stop → SubagentStop 変換
agent-teams — TeammateIdle / TaskCreated / TaskCompleted

未取得の派生リンク

https://code.claude.com/docs/en/tools-reference — ツールの正規名（permission rule と hook matcher が使うのはこちら）

ai-docs

エクスプローラー