Agent SDK の hooks は、エージェントの実行中に発生するイベントへコールバックを差し込み、ツール呼び出しの監視・ブロック・修正やログ記録を行うための仕組みです。本稿は公式ドキュメント（https://code.claude.com/docs/en/agent-sdk/hooks）の記述のうち、逐語照合を通過した事項だけをまとめた仕様解説です（2026-09-06 検証）。
hooks の定義とイベントモデル
hooks はエージェントイベントに応じて任意のコードを実行するコールバック関数です。対象イベントにはツール呼び出し、セッション開始、実行停止などが含まれます [1]。
Hooks are callback functions that run your code in response to agent events, like a tool being called, a session starting, or execution stopping.
同一イベントに複数のフックが登録されている場合、それらは並列に実行されます [1]。全てのフックコールバックは共通の 3 引数を受け取ります [1]。
PreToolUse によるブロックと修正
PreToolUse はツール呼び出しリクエストに対する事前フックで、リクエストをブロックまたは修正できます。危険なシェルコマンドのブロックが典型的な用途です [1]。
入力を書き換える場合、updatedInput は hookSpecificOutput の内部に置く必要があります。トップレベルに置いても適用されません [1]。
複数のフックが permissionDecision を返すとき、優先順位は deny が最上位です。1 つでも deny を返せば、他のフックの結果に関わらずその操作はブロックされます [1]。
PostToolUse と classifierContext
PostToolUse コールバックは classifierContext を返せます。これは auto モードのパーミッションクラシファイアへ向けた、ツール呼び出し結果に関する短い注釈です [1]。このフィールドは TypeScript Agent SDK v0.3.236 以降が必要です [1]。
旧フィールドの updatedMCPToolOutput は MCP ツール出力の置換のみに対応し、現在は非推奨です [1]。
タイムアウトの仕様
デフォルトタイムアウトは、多くのイベントで 600 秒、UserPromptSubmit・PreModelSwitch・PostModelSwitch で 30 秒、MessageDisplay で 10 秒です [1]。SessionEnd コールバックはシャットダウン中に実行されるため、デフォルト 1.5 秒という短い予算が適用されます [1]。
PreToolUse がタイムアウトした場合、ツール呼び出しは実行されず、Claude はフックがタイムアウト前に応答しなかった旨のツール結果を受け取り、ターンは継続します [1]。UserPromptSubmit および UserPromptExpansion でタイムアウトした場合、Claude Code はフック名とタイムアウトを示すメッセージでプロンプトをブロックし、未スクリーニングのプロンプトは通しません [1]。
SDK・バージョン依存の注意点
SessionStart と SessionEnd は TypeScript では SDK コールバックフックとして登録できますが、Python SDK では HookEvent 型がこれらを含まないため利用できません [1]。
MCP ツールの matcher は mcp____ の形式で、 は mcpServers 設定で使うキー名です [1]。
Notification フックの permission_prompt タイプは TypeScript Agent SDK v0.3.233 以降、または Python Agent SDK v0.2.139 以降が必要です [1]。permission_prompt は、canUseTool コールバックがパーミッションリクエストを約 6 秒待機した後に発火します [1]。
非同期出力モード（async: true）を返すと、エージェントはフックの完了を待たずに直ちに処理を続行します [1]。