Claude Code: agent hook（type: "agent"）でファイルやテスト結果を見てから止める・通す

prompt hook は渡された JSON だけを見て1回で判定するが、agent hook はサブエージェントを起動し、Read・Grep・Glob などで実際のファイルを調べてから {"ok": true/false} を返す。「本当にテストが通ったか」のように、確認に中身を見る必要がある条件に使う。

設定例（Stop: テストが通るまで終わらせない）

json

{
  "hooks": {
    "Stop": [
      { "hooks": [ {
        "type": "agent",
        "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
        "timeout": 120
      } ] }
    ]
  }
}

$ARGUMENTS に hook の入力 JSON が入る
サブエージェントは最大50ターン調べてから判定する
ok: false のときは、prompt hook の continueOnBlock: true と同じ扱いになる（理由が Claude に返り作業が続く）

prompt hook との違い

| | prompt | agent |
| - | - | - |
| 判定 | 1回の LLM 呼び出し | ツールを使うサブエージェント（最大50ターン） |
| 既定タイムアウト | 30秒 | 60秒 |
| continueOnBlock・impossible | あり | なし |
| 使えるイベント | PreToolUse・PostToolUse・Stop・SubagentStop・UserPromptSubmit・TaskCompleted など | 同じ。ただし PermissionRequest は不可（設定しても飛ばされる） |

注意点

実験的機能。設定や挙動は変わりうる。本番の品質ゲートは command hook を優先するよう公式も書いている
毎回サブエージェントが走るので、Stop や PostToolUse に付けると時間と利用枠をかなり使う。対象を matcher で絞り、timeout も決めておく
SessionStart・PreCompact・Notification などでは prompt／agent hook は使えない

出典

@gota_bara · 2026-02-03
公式ドキュメント（Agent-based hooks）: code.claude.com
関連: Claude Code: prompt hook は「指示文」で書ける（Stop で早期終了を防ぐ）