Claude Code hooks リファレンス

hook は、Claude Code が「確認待ちになった」「応答が終わった」などの節目で自動実行するコマンドです。 hook を初めて触るなら、設定を手書きせず作れる hooks ビルダーから始めてください。 hook を書くときに必要な情報を 1 ページにまとめました。全イベントの一覧と各 matcher が受け付ける値、 すべての hook が標準入力で受け取る項目、settings.json と statusLine の形、終了コードの意味です。 最後の節では、AgentManager がこれらのイベントから導出するセッションごとの状態ファイルを、 自分のスクリプトから読みたい人向けに説明します。

• hook イベント一覧
• すべての hook が標準入力で受け取る項目
• settings.json のスキーマ
• statusLine のスキーマと標準入力
• 終了コード
• AgentManager のセッション状態ファイル

hook イベント一覧

Claude Code は現在 33 種の hook イベントを定義しています。3 列目は、そのイベントで matcher が何を対象に絞り込むかと、値の例です。 「—」のイベントは matcher を無視して常に発火します。| で区切った素の名前は完全一致、 正規表現の記号を含む場合は JavaScript の正規表現として扱われます。空の matcher は全件に一致します。

すべての hook が標準入力で受け取る項目

各 hook コマンドは標準入力から JSON オブジェクトを 1 つ受け取ります。次の項目は全イベント共通で、イベントごとに固有の項目が加わります （例: ツール系イベントの tool_name と tool_input、Notification の notification_type、 StopFailure の error_type、SessionEnd の reason）。

settings.json のスキーマ

hook はトップレベルの hooks キーの下に置きます。置き場所は ~/.claude/settings.json（ユーザー）、 .claude/settings.json（プロジェクト・コミット対象）、.claude/settings.local.json（プロジェクト・git 管理外）のいずれかです。 ファイルはマージされ、複数ファイルに定義した hook はそれぞれから実行されます。

{
  "hooks": {
    "<イベント名>": [
      {
        "matcher": "<任意の絞り込み>",
        "hooks": [
          { "type": "command", "command": "<シェルコマンド>", "timeout": 600 }
        ]
      }
    ]
  }
}

statusLine のスキーマと標準入力

ステータス行は別のトップレベルキーで、枠は 1 つだけです。そのコマンドはアシスタントの応答のたびに実行され、 hook には渡らないデータ（コンテキストウィンドウの使用量と利用上限の状態）を受け取ります。

{
  "statusLine": {
    "type": "command",
    "command": "<シェルコマンド>",
    "padding": 0,
    "refreshInterval": 5,
    "hideVimModeIndicator": false
  }
}

終了コード

AgentManager のセッション状態ファイル

AgentManager の hook は上のイベントをセッションごとに 1 つの JSON ファイルへ集約し、 ~/.claude/agent-manager/sessions/<session_id>.json に書きます。イベントのたびにその場で上書きされるため、 読み取り側でパースに失敗したら壊れたと判断せず読み直してください。導出ルールは hook で Claude Code のセッション状態を追跡するで説明しています。

もう 1 つのファイル ~/.claude/agent-manager/stats/<session_id>.json は statusLine の パススルーが書きます。ステータス行の標準入力にある context_window・rate_limits・model を そのまま持ち、PreCompact が発火したときはその印も持ちます。インストール前に設定していたステータス行のコマンドは ~/.claude/agent-manager/statusline-original.json に保存され、引き続き実行されます。