Agent SDK Hooks とツール呼び出し傍受

Agent SDK Hooks は、Claude Certified Architect — Foundations（CCA-F）試験において、Claude を「プロンプトを与えるだけの賢いモデル」として扱う受験者と、「本番システムの構成要素」として扱う受験者を明確に分ける機能である。タスクステートメント 1.5「Agent SDK hooks をツール呼び出し傍受とデータ正規化に適用する」は、一つのアーキテクチャ的思想をテストする：保証が必要なとき、system prompt に丁寧に頼むのではなく、コード内でツール呼び出しを傍受し、決定論的に保証を適用する。この転換——確率論的 prompt 準拠から決定論的プログラム的適用へ——は、Domain 1（Agentic Architecture & Orchestration、試験の 27%）で最も頻繁に問われる思考モデルである。

本学習ノートは、CCA-F 受験者が 60 問・120 分・シナリオ形式の試験で認識を求められる Agent SDK Hooks の全領域を扱う。hooks のライフサイクルと agentic loop の関係、PreToolUse と PostToolUse の違い、標準的な利用ケース（異種ツール結果の正規化、PII スクラビング、払い戻し閾値の適用、ヒューマンエスカレーションへのリダイレクト、監査ログ）、受験者が陥りやすい試験トラップ、そしてタスク 1.5 の設問に最も多く登場する Customer Support Resolution Agent クラスターのシナリオアンカーパターンをすべて解説する。

Agent SDK における Hook とは何か

Claude Agent SDK における hook とは、エージェントの実行ライフサイクルの特定の時点で発火するユーザー登録コールバックであり、アプリケーションコードが「これから起きること」または「直前に起きたこと」を検査・変更・ブロック・記録する機会を与える。Hook は決定論的である。SDK が agentic loop 内で同期的に呼び出す通常のコードであり、モデルが従うかどうかわからない prompt ではない。この決定論性こそ、システムに交渉の余地のないビジネスルールが存在するときに hook が正しい選択肢となる理由である。

CCA-F タスク 1.5 の設問で最も頻繁に登場する hook の種類は PreToolUse（ツール呼び出しがアプリケーションを離れて実行される前に発火）と PostToolUse（ツール結果が返ってきた後、その結果が会話に追記されモデルに処理される前に発火）である。Agent Teams と Claude Code は追加のライフサイクル hook（TeammateIdle・TaskCreated・TaskCompleted・SessionStart・UserPromptSubmit・Stop）も公開しているが、タスク 1.5 については試験は二種類のツール呼び出し hook に集中している。

Agentic Loop における Hooks の位置づけ — 実行ライフサイクル

試験で hooks を正しく論じるためには、agentic loop と各 hook が発火する正確なポイントについて、明確な思考モデルを持つ必要がある。

七ステップのループ

agentic loop の各ターンについて：

1. アプリケーションがメッセージ履歴とツール定義をモデルに送信する。
2. モデルが、ゼロ個以上の tool_use ブロックを含む場合があるアシスタントメッセージを生成する。
3. 各 tool_use ブロックについて、SDK がツールを呼び出そうとする——ここで PreToolUse が発火する。
4. SDK がツール呼び出しをツールハンドラー（関数・MCP サーバー・Read/Write/Bash などの組み込みツール）にディスパッチする。
5. ツールが完了し、結果（またはエラー）を返す——ここで PostToolUse が発火する。
6. SDK が tool_result メッセージを会話に挿入する。
7. モデルが stop_reason: end_turn を発するまで、新しい履歴でステップ 1 から繰り返す。

Hooks はステップ 3 と 5 における決定論的な傍受ポイントである。このライフサイクルを理解すれば、本章の残りは容易に理解できる。

Hook ポイントが重要な理由

ステップ 3（PreToolUse）は、アクションが現実世界に影響を与える前にそれを変更またはブロックする最後の機会である。ステップ 5（PostToolUse）は、次のターンでモデルが目にするものを形成する最初の機会である。タスク 1.5 のすべての試験シナリオは、これら二つのポイントのいずれか一方に正確に対応する——誤答の選択肢は通常、hook タイプの混同（PostToolUse が必要なところで PreToolUse を使う、またはその逆）である。

PreToolUse Hook — 実行前のツール入力の検査と変更

PreToolUse hook はツール名と提案された入力引数を受け取る。以下のいずれかを実行できる：

• 通過 — 「変更せずに呼び出しを続行する」というシグナルを返す。ポリシー違反がない場合のデフォルト動作。
• 入力の変更 — ディスパッチ前に入力を書き換える。例：モデルが忘れた store_id フィルターを追加する、モデルが範囲外で提供した数値フィールドをクランプする。
• ブロックして代替を返す — 呼び出しの実行を防ぎ、呼び出しが拒否された理由を説明する合成ツール結果を返す。モデルはその合成結果を読んで次のターンを調整する。
• リダイレクト — 完全にブロックする代わりに、リクエストを別のワークフロー（例：ヒューマンエスカレーションキュー）に引き渡し、モデルにエスカレーションを了解するよう指示するツール結果を返す。

CCA-F 向け PreToolUse の標準的な利用ケース

• 金額閾値のポリシーゲート — Customer Support Resolution Agent には process_refund(amount, order_id) ツールがある。ポリシーでは 500 ドルを超える払い戻しには人間の承認が必要とされている。PreToolUse hook が amount を検査し、閾値を超えた場合は呼び出しをブロックし、tool_result: "500ドルを超える払い戻しにはマネージャーの承認が必要です。エスカレーションチケット CSR-4412 を作成しました。" を返す。モデルはその後、人間のエージェントがフォローアップすることを顧客に伝える。
• 入力のサニタイゼーション — 確認トークンのない delete_user 呼び出しのブロック、検索クエリからの不正文字のスクラビング。
• レートとクォータの適用 — セッションごとの呼び出し回数をカウントし、クォータに達したらツールの使用をブロックする。
• テナントスコーピングの注入 — すべてのデータベースクエリに現在のユーザーの tenant_id フィルターを追加し、テナントをまたいだデータアクセスを構造的に不可能にする。

PostToolUse Hook — 挿入前のツール出力の傍受と変換

PostToolUse hook は、ツールが生成した生結果（文字列・JSON・構造化ペイロードを問わない）に加えて、元のツール入力と呼び出しに関するメタデータを受け取る。以下を実行できる：

• 結果をそのまま通過させる。
• 異種フィールドをモデルが推論しやすい正規化された形式に変換する。
• モデルのコンテキストウィンドウに入るべきでないフィールドを削除する（PII・機密情報・内部識別子）。
• 派生値を付加して結果を拡充する（生注文レコードに計算済みの days_since_order フィールドを追加する）。
• モデルに見せる内容を変えずに、監査のために生値と変換後の値をログに記録する。

正規化パターン — 異種データの正規化

典型的な CCA-F シナリオ：エージェントが三つの異なる上流システム（Unix エポック秒を返す決済 API、ISO 8601 文字列を返す注文 API、1・2・3 などの数値ステータスコードを返す配送 API）を呼び出す。モデルは原理的には各フォーマットを解釈できるが、毎ターンそれを行うとトークンを消費し、ミスが生じ、会話に定型的な推論が蓄積される。PostToolUse hook がすべてを正規化された形式——タイムスタンプは ISO 8601 UTC、ステータスは名前付き enum（pending・shipped・delivered）——に変換することで、モデルはすべてのツール結果で一様でクリーンなレコードを受け取れる。

この正規化の利用ケースは、PostToolUse の試験パターンとして最も多く引用されるものである。CCA-F の設問が「一貫性のない上流データフォーマット」を説明し「標準化をどこに適用するか」と問う場合、答えは PostToolUse hook である。

削除パターン — コンテキスト挿入前の PII 処理

Customer Support Resolution Agent のワークフローは、完全な PAN（カード番号）・SSN 全体・PHI を含む生のデータベース行に頻繁に触れる。PostToolUse hook は、これらのフィールドを会話に入る前に削除するアーキテクチャ的に整然とした場所である。ツールは完全なレコードを返し続け（ツールハンドラーはそれをログに記録したり下流システムに転送できる）、しかしモデルが目にするバージョンは末尾四桁とマスクされた識別子に縮小されている。これにより影響範囲が縮小される：モデルは受け取っていないデータを漏洩させることができない。

拡充パターン — 派生フィールドの追加

モデルが事前計算されたメタデータから恩恵を受けることがある。PostToolUse hook は days_since_order・eligible_for_refund・within_return_window・region_code を生注文レコードに追加し、モデルがそれらの値を再計算する手間を省き、会話内での計算ミスの可能性を減らすことができる。

Hook の登録 — 特定のツール名への紐付けとすべてのツールへの適用

Hook の登録は、試験がテストする二番目の判断軸である（「PreToolUse か PostToolUse か」の次に来る）。

グローバル Hook とツール固有 Hook

グローバル hook はツール名に関係なく、すべてのツール呼び出しで発火する。横断的関心事に使用する：監査ログ、任意のツール出力に対する PII 削除、セッションごとのクォータ適用。

ツール固有 hook は特定の名前付きツールが呼び出された場合にのみ発火する。特定のツールにのみ適用するビジネスルールに使用する：500 ドルの払い戻し閾値は process_refund にのみ適用され、lookup_order や send_notification には適用されない。

登録パターン

Agent SDK はエージェント作成時の SDK オプション（プログラム的登録）として、または Claude Code の .claude/settings.json hooks 設定として hook を受け付ける。CCA-F では TypeScript のシグネチャや JSON スキーマを暗記する必要はなく、以下を認識する必要がある：

• Hook はエージェントの構築時に登録される——動的に発見されるわけではない。
• ツール名フィルターは hook を特定のツールに絞り込む。
• 同じイベントに複数の hook を登録できる。SDK は定義された順序でそれらを実行する。

特異性が重要な理由

過度に広い hook には三つの問題がある：（a）ゲーティングを必要としないツールへの呼び出しごとのオーバーヘッドが増加する、（b）表面的なパターンに一致するツールで誤ってブロックするリスクがある、（c）モジュール化すべきポリシーロジックが単一の hook 関数に集中する。試験の設問では、hook のスコープのみが異なる二つの正解に見える選択肢を提示することがある——正解はほぼ常により狭い登録である。

Hook の順序と合成

同じイベントに複数の hook が登録されている場合、SDK は登録順序でそれらを実行する。二つのアーキテクチャパターンがある：

• 連鎖変換 — hook A がタイムスタンプを正規化し、hook B が PII を削除し、hook C が監査メタデータを追加する。各 hook は前の hook の出力を受け取る。順序が重要：監査ログが PII を含むべきでない場合、削除は監査ログ記録の前に実行されなければならない。
• 短絡ブロック — セキュリティ hook が最初に実行され、呼び出し全体をブロックできる。変換 hook はセキュリティ hook が通過させた場合にのみ実行される。

よくある試験トラップ：受験者が hook は並列または任意の順序で実行されると思い込む。そうではない。Hook の順序は決定論的であり、アーキテクチャ上の決定領域の一部である。

Hook のエラー処理 — Hook 自体が例外をスローした場合

Hook は通常のコードであり、失敗することがある。SDK が hook のスローを処理するデフォルトの動作は hook のタイプと設定によって異なるが、試験で問われる原則は：

• PreToolUse がスローした場合は通常「呼び出しをブロック」として扱われる——フェールクローズ。エラーが発生したポリシーゲートは、許可された呼び出しとして扱うよりも拒否された呼び出しとして扱う方が安全だからである。
• PostToolUse がスローした場合は通常、元の変更されていない結果をそのまま通過させ、hook エラーをログに記録する。ツールはすでに実行されており、結果を完全にドロップするとループが壊れるためである。
• Hook のタイムアウト — 長時間実行される hook は agentic loop をブロックする。Hook は高速に保ち、高コストの処理（大容量ログのアップロード・重いアナリティクス）は非同期キューに委ねること。

試験シナリオで「正規化 hook がクラッシュした場合はどうなるか」と問う場合がある。原則的な回答：システムはエージェントを動作させ続けながら大きくログを出力し（ログ＋アラート）、通常は生の結果をそのまま通過させてレコードをレビュー待ちとしてフラグを立てるべきである。

決定論的適用 vs 確率論的 Prompt 準拠 — CCA-F の核心的思考モデル

このセクションはタスク 1.5 で最もテストされる考え方である。反射的になるまで内面化すること。

二つのコンプライアンス方式

選択の経験則

• 要件に絶対的な言葉（絶対にしてはならない・常に・いかなる状況でも・保証する）が使われている場合、答えは hook（または他の決定論的ゲート——厳密なツールスキーマ・コードレベルのバリデーション）。
• 要件に柔らかい言葉（好む・通常・推奨・適切な場合に）が使われている場合、system prompt で十分な場合がある。
• 要件が法律・財務・安全に関わる場合、文言が柔らかく聞こえても決定論的適用をデフォルトにする。

Prompt だけではコンプライアンスに不十分な理由

Anthropic 自身のエンジニアリングの文書でも、system prompt はモデルのデフォルト動作を導くのに優れているが、保証されたコンプライアンスをもたらさないと強調されている。モデルは統計的である：十分な呼び出し回数があれば、どのような確率論的挙動もいつかは外れ値を生み出す。process_refund のような高頻度ツール呼び出しでは、99.9% の prompt 準拠率でも約 1,000 回の呼び出しに 1 回の違反を意味する——法律やパートナー契約に裏打ちされたポリシーには多すぎる。Hook はコンプライアンスをシステムの構造的な特性とし、単なる目標にはしない。

ポリシー違反アクションを代替ワークフローにリダイレクトする

モデルに単純に「ノー」と言うだけの PreToolUse hook は許容できるが、エンドユーザーを待たせることになる。成熟したアーキテクチャはリダイレクトを行う：ブロックするだけでなく、hook がリクエストを代替ワークフローにディスパッチし、モデルが結果を顧客に伝える方法を学べるツール結果を返す。

ヒューマンエスカレーションパターン

Customer Support Resolution Agent の払い戻し閾値の例：

1. モデルが tool_use: process_refund(amount=750, order_id="ABC") を発する。
2. PreToolUse hook が amount > 500 を確認し、直接払い戻しをブロックする。
3. Hook がヒューマンエージェントキューにエスカレーションチケットを作成する（例：Zendesk API 経由で完全なコンテキスト——顧客・注文・要求金額・会話サマリーを含む）。
4. Hook が tool_result: { status: "escalated", ticket_id: "CSR-4412", expected_response_hours: 24 } を返す。
5. モデルがツール結果を読み、顧客に伝える：「払い戻しリクエストを人間のエージェントにエスカレーションしました。チケット CSR-4412 は 24 時間以内にレビューされます。」

モデルは払い戻しが低額であれば自動処理できたことを決して知らない——hook がその機会を与えなかったからだ。コンプライアンスの保証は構造的である。

代替ツールパターン

もう一つの変形：PreToolUse が禁止されたツールをブロックし、正しいツールを明示的に推奨する結果を返す。例えば、モデルが本番データベースに対して execute_sql(raw_query) を実行しようとする場合、hook がそれをブロックし tool_result: "直接 SQL は拒否されました。適切なフィルターを付けた read_customer_data ツールを使用してください。" を返す。モデルはその後、より安全なツールを使ってリクエストを書き直す。

段階的レビューパターン

Hook は承認の段階をエンコードできる：100 ドル未満の払い戻しは自動承認、100〜500 ドルは確認メッセージが必要、500 ドル超は人間にエスカレーション。各段階は hook 内の一つの分岐である。モデルは統一されたインターフェース（ツールを呼び出し、ツール結果を受け取る）を経験し、hook は任意に複雑なポリシーツリーをエンコードする。

Hook における監査ログ — コンプライアンス証拠とデバッグ

Hook はすべてのツール呼び出しとすべてのツール結果を目にするため、監査証跡を生成する自然な場所である——モデルがそれらをどう扱うかに関わらず。

PreToolUse でログに記録すべき内容

• タイムスタンプ・セッション ID・会話 ID。
• ツール名と完全な入力引数。
• ポリシーの決定（許可・変更・ブロック・リダイレクト）。
• ブロックまたはリダイレクトの場合：ルール識別子（例：POLICY-REFUND-500-CEILING）。

PostToolUse でログに記録すべき内容

• 生のツール結果（削除前の完全なコピー、コンプライアンス対象ログに保存）。
• 会話に挿入された正規化・削除済みバージョン。
• レイテンシ・エラーフラグ・ツールハンドラーのバージョン。

監査ログが Prompt ではなくここに記録される理由

モデルに「構造化されたサマリーを発する」ように prompt で指示して「ログを記録させる」場合、確率論的なログが得られる——正しいこともあれば、フィールドが欠けることも、幻覚を起こすこともある。Hook は決定論的なログを生成する。金融・医療・顧客データ処理などの規制産業では、決定論的なログだけが監査人を満足させる。

PII スクラビング・削除・データ最小化パターン

Hook はデータ最小化のためのいくつかの段階的アプローチをサポートする：

• 完全削除 — フィールドを [REDACTED] に置き換えるか、モデルがペイロードを受け取る前に完全に削除する。
• マスキング — フィールドを部分的に保持する（SSN の末尾四桁、first.l****@example.com）ことで、モデルが機密値を見ることなくレコードについて推論できる。
• トークン化 — フィールドを不透明なトークンに置き換える。同じトークンを受け入れる下流のツールは、信頼境界内で元の値に解決できる。
• ハッシュ化 — 開示なしに相関を可能にするためにフィールドをハッシュに置き換える。

試験は暗号の詳細をテストしない。これらの変換を適用する正しい場所は PostToolUse hook であり、モデルに「SSN を繰り返さないようにしてください」と指示する prompt 指示ではない、という点をテストする。

同期 Hook のパフォーマンスへの影響

すべての hook はすべてのツール呼び出しにレイテンシを追加する。ネットワーク呼び出しを行う hook（SIEM への書き込み・ポリシー決定サービスの呼び出し）では、そのレイテンシは無視できない。

実践的ガイダンス

• 可能な限り hook をインプロセス・インメモリに保つ。高速な正規化関数はマイクロ秒レベル。
• 低速な処理（ログのアップロード・アラートディスパッチ・クロスシステム API 呼び出し）は、hook が同期的にエンキューして返すファイアアンドフォーゲットキューに送る。
• hook の実行の p99 レイテンシをツール自身のレイテンシと比較して測定する。5ms のツールレイテンシを二倍にする hook は問題ないが、500ms のツールレイテンシを二倍にする hook はユーザー向けフローで体感される可能性がある。

これが試験で重要な理由

コミュニティから収集された試験経験レポートによると、タスク 1.5 はハイスループットループにおける hook 傍受のコストを問うことがある。正しい回答プロファイルは「hook は同期的なオーバーヘッドを追加する。軽量に保ち、高コストの処理は非同期キューに押し込む」である。「hook はツール実行と並列に非同期で実行される」という誤答を排除すること——そうではない。

やさしい解説: — Agent SDK Hooks の三つの類比

抽象的なライフサイクル図は、身近なシステムに固定されるとよく理解できる。以下に Agent SDK Hooks の異なる側面を照らす三つの類比を示す。

類比 1: 空港のセキュリティと税関（PreToolUse と PostToolUse）

国際空港を想像してほしい。飛行機に搭乗しようとしている全乗客（ツール呼び出し）は保安検査——荷物を検査し、乗り入れ禁止リストと照合し、通過させるか、200ml の水を捨てさせるか（入力変更）、脇に引っ張って搭乗を拒否する（ブロックとリダイレクト）決定論的なチェックポイント——を通過する。これが PreToolUse だ。常に実行される。乗客がどれほど丁寧にスキップを求めても、航空会社のロイヤルティプログラムがどれほど優れていても関係ない——保安は構造的なものだ。

到着すると、全乗客（ツール結果）は税関——検査官が荷物が申告された正規の形式に一致することを確認し、国内に入れてはいけない物品を没収し（削除）、書類にスタンプを押す（監査ログ）——を通過する。これが PostToolUse だ。税関は飛行を取り消すことができない（副作用はすでに発生している）——それは目的地のシステム（会話のコンテキスト）に入るものを形成するだけだ。

この類比で三つのことが明確になる：（a）なぜ PreToolUse が「絶対にしてはならない」ルールの正しい場所なのか——保安は飛行機の前にあり、後にはない、（b）なぜ PostToolUse が副作用を取り消せないのか——飛行機はすでに着陸している、そして（c）なぜ実際のチェックポイント（決定論的 hook）の代わりに「乗客に放送でルールを守るようお願いする」（確率論的 prompt）ことを決して頼りにしてはならないのか。

類比 2: 居酒屋の板前（エクスペダイター）

繁盛する厨房には板前という役割がある——ライン cook とダイニングルームの間に立つ人物だ。パスを離れる前のすべての皿が板前によって確認される：正しいテーブル（ツール名が一致）、正しい温度（入力がポリシー内）、正しい盛り付け（フィールドが拡充）、ステーキに髪の毛がない（PII が削除）。検査を通過しない皿は突き返されるか、別のステーションに送られる。

PreToolUse は、料理の伝票が調理場に渡る前に確認する板前だ：今日のメニューにある料理か、このお客様にアレルギーの記録があるか、この VIP のための 48 オンスのステーキスペシャルを作る権限が厨房にあるか。PostToolUse は、料理がダイニングルームに出る前に完成した皿を確認する板前だ：盛り付け・温度・見た目・ポーションサイズ。どちらの場合も、板前はシェフに丁寧なメモでルールを「提案」しない——パスで構造的に適用するのだ。

この類比は順序の合成も説明する：板前は一連の確認（盛り付け、次に飾り付け、次に温度）を適用し、最初の重大な失敗で止まる。Hook の順序も同じ考え方だ。

類比 3: 銀行窓口のデュアルコントロール金庫

銀行の窓口係は顧客の取引を処理するが、特定の取引（閾値を超えた引き出し）には現金引き出しの前に上長の共同署名が必要だ。どれほど友好的な顧客でも窓口係はこれを覆すことができない——引き出し機構自体が二つの鍵を必要とするからだ。少額の取引は問題なく流れ、大きなものは上長承認に自動的に振り向けられ（代替ワークフロー）、顧客には「お客様のリクエストにはマネージャーの承認が必要です。通常数分かかります」と伝えられる（モデルがユーザーに伝える合成ツール結果）。

これはまさに払い戻し閾値パターンだ。PreToolUse hook は引き出し機構だ。上長キューはヒューマンエスカレーションワークフローだ。合成ツール結果は上長を呼ぶ間に窓口係が顧客に伝えることだ。顧客のリクエストはブラックホールに消えたのではない——より遅いが有効な結果をもたらすワークフローに振り向けられ、顧客は情報を提供され続ける。

試験当日にどの類比を使うか

• 「絶対にしてはならない」適用と Pre/Post の区別に関する設問 → 空港の類比。
• 正規化・拡充・検査チェーンに関する設問 → 板前の類比。
• ヒューマンエスカレーションへのリダイレクトと代替ワークフローに関する設問 → 銀行窓口の類比。

Hook 利用ケースマトリックス — どの Hook を使うかの判断

タスク 1.5 の一般的な試験トラップ

CCA-F の試験は Agent SDK Hooks に関して五つの繰り返しトラップパターンを積極的に利用する。

トラップ 1: PostToolUse が副作用を「防止する」

受験者は「絶対に X を実行してはならない」の適用ポイントとして PostToolUse を選ぶことがある。誤り。 PostToolUse はツールがすでに実行された後に発火する。ツールが本番テーブルを削除した場合、PostToolUse はそれを取り消すことができない。副作用の防止については、正しい答えは PreToolUse だけである。

トラップ 2: Hook の代わりにプロンプトエンジニアリング

シナリオにハードなコンプライアンス要件（法律・財務・安全）があると、誤答の選択肢は「system prompt を強化する」や「ツールの説明に例を追加する」を提案する。これらは確率論的だ。ハードなルールに対する正しい CCA-F の答えは hook（または別の決定論的ゲート）である。

トラップ 3: PreToolUse の変更スコープの混同

入力を変更する PreToolUse hook はツールが見るものを変更するが、モデルがメッセージ履歴に見るものは変更しない。試験の設問で「モデルが同じ間違った入力を繰り返す」と問う場合、PreToolUse の入力変更だけではモデルの認識を修正しない——モデルは依然として元の入力でツールを呼び出したと思っている。ツール結果に修正のノートを挿入する PostToolUse hook を使用するか、会話履歴に観察を追加するかのいずれかが必要である。

トラップ 4: Hook の順序の誤った前提

受験者が hook は並列または非決定論的な順序で実行されると思い込む場合がある。そうではない。Hook の順序は決定論的であり、登録順序に従う。削除 hook の前に登録された監査 hook は削除前のデータをログに記録し、後に登録されたものは削除後のデータをログに記録する。順序がセマンティクスを決定する。

トラップ 5: 「Hook がすべてを処理する」過剰適用

逆のトラップ：hook がすべてのアーキテクチャ的問いに対する正しい答えだと思い込む。そうではない。Hook はツール呼び出しの決定論的な傍受のためのものだ。Hook は、ツールの発見・コンテキストウィンドウ管理・長時間実行のサブタスク委任（subagents を使用する）・セッション永続性（SDK セッション API を使用する）・モデル動作の調整（prompt を使用する）には適切ではない。hook に到達する前にシナリオを慎重に読むこと。

練習アンカー — タスク 1.5 シナリオ設問テンプレート

タスク 1.5 に関連する CCA-F シナリオ設問は、Customer Support Resolution Agent と Developer Productivity のシナリオに集中している。繰り返し登場する五つの形式を示す。

テンプレート A: 防止 vs 観察

フィンテック企業が issue_card_replacement ツールを持つ Customer Support Resolution Agent を構築している。ポリシーでは、アカウントごとに 30 日間に 1 回のカード交換しか許可されていない。チームは同時セッションでもこの制限が守られることを保証しなければならない。どのアーキテクチャ的メカニズムを実装すべきか。正解：交換カウンターを確認してさらなる呼び出しをブロックする PreToolUse hook。誤答：より強い system prompt（確率論的）、PostToolUse hook（事後）、ツール説明の改善（強制力なし）。

テンプレート B: 異種データの正規化

Developer Productivity エージェントが、異なるフォーマットのタイムスタンプを返す三つの API を呼び出す：Unix エポック秒・ISO 8601・カスタムの YYYYMMDD-HHMMSS 文字列。チームはモデルが常に ISO 8601 UTC を受け取れるようにしたい。正規化ロジックをどこに置くべきか。正解：変換するすべての三つのツールに登録された PostToolUse hook。誤答：system prompt に指示を追加する（トークンコストが高く確率論的）、三つの別々のエージェントに分岐する（アーキテクチャレベルとして誤り）。

テンプレート C: コンプライアンスのための PII 削除

サポートエージェントが SSN 全体を含む顧客レコードを取得する。チームは SSN がモデルのコンテキストウィンドウに決して届かないことを保証しなければならない。どの hook を使うか、なぜか。正解：PostToolUse — ツールハンドラーは下流 API のために完全なレコードへのアクセスが正当に必要なため、削除はツールの出力先ではなく、会話への入り口で行う。誤答：PreToolUse（役立たない——問題は返されたデータであり、リクエストではない）。

テンプレート D: ヒューマンエスカレーションへのリダイレクト

Customer Support シナリオ：500 ドルを超える払い戻しは人間に送る。どのメカニズムの組み合わせを使うか。正解：直接払い戻しをブロックし、エスカレーションチケットを作成し、モデルが結果を顧客に伝えられる合成ツール結果を返す PreToolUse hook。誤答：リダイレクトなしのブロックのみ（UX が悪い）、500 ドル以上でヒューマンエスカレーションを好むよう prompt で伝える（確率論的）。

テンプレート E: Hook のエラー処理

正規化 hook が不正な上流レスポンスでスローする。最も安全なデフォルト動作は何か。正解：元の生ツール結果をそのまま通過させ、hook エラーをログに記録し、オペレーターに通知する。誤答：ツール結果を完全にドロップする（ループが壊れる）、hook を無限に再試行する（レイテンシが増加し無限ループのリスクがある）。

他の Domain 1 章節との関係

Hook は Domain 1 の他の章節とクロステストで試される形で相互作用する。

Hooks vs Subagent ツール許可リスト

タスク 1.3 では allowedTools を紹介する——subagent が呼び出せるツールを制限する subagent 設定。allowedTools は粗く静的なツールレベルのゲート：subagent にツールがあるかないかだ。Hook は細粒度で動的な呼び出しごとのゲート：subagent にはツールがあるが、hook が各呼び出しの引数を検査する。能力スコーピングには allowedTools、動作ゲーティングには hook を使用する。試験はどちらを使うかを問うことがある。答えは制限がカテゴリカルなもの（allowedTools を使用）か引数依存のもの（hook を使用）かによる。

Hooks vs 厳密なツールスキーマ

タスク 4.3 では、ツールスキーマの strict: true を紹介する——出力形状の決定論的なスキーマ検証ゲート。Hook は動作のコードレベルの決定論的ゲートだ。どちらもコンプライアンス上の決定論的適用の側に位置する。「抽出された JSON には常に confidence フィールドが必要」という要件には厳密なスキーマが適切であり、「払い戻し金額が 500 ドルを超えてはならない」という要件には hook が答えだ。

Hooks vs 構造化エラーレスポンス

タスク 2.2 では構造化エラーレスポンス（errorCategory・isRetryable）を扱う。Hook はブロックの結果として構造化エラーを生成でき、MCP エラー規約に自然に整合する。PreToolUse hook が呼び出しをブロックする場合、単なる文字列ではなく構造化エラーを返すことで、モデルが異なる入力で再試行するか中止するかを判断できる。

Agent SDK Hooks よくある質問（FAQ）

CCA-F 試験における PreToolUse hook と PostToolUse hook の違いは何か

PreToolUse hook は、モデルがツールを呼び出すことを決定した後、SDK が呼び出しをディスパッチする前に発火する——防止・入力変更・ポリシー適用・代替ワークフローへのリダイレクトのための決定論的ゲートだ。PostToolUse hook は、ツールが実行されてその結果が利用可能になった後、その結果が会話に追加される前に発火する——正規化・PII 削除・拡充・監査ログのための決定論的変換ポイントだ。CCA-F の経験則：要件が防止なら答えは PreToolUse、要件が事後の変換または観察なら答えは PostToolUse。

PostToolUse hook はツールの実行を防ぐことができるか

できない。PostToolUse が発火するまでに、ツールはすでに実行されており、すべての副作用（データベースへの書き込み・払い戻しの発行・メール送信）はすでに発生している。PostToolUse は事後にモデルが目にするものを形成するだけだ。副作用の防止には、ツールが最初から実行されないよう PreToolUse hook（または他の実行前ゲート）を使用しなければならない。これは最も頻度の高い CCA-F トラップパターンの一つだ——防止の要件に PostToolUse を選んだ受験者は減点される。

CCA-F 試験でいつ hook を使い、いつ system prompt の指示を使うか

要件がハードなコンプライアンスルール——「絶対にしてはならない」「常に」「保証する」または法律・財務・安全に関わるもの——の場合は hook を使用する。Hook は決定論的適用をもたらす：すべての呼び出しで常に実行される。トーン・好み・デフォルトスタイル・典型的な動作などのソフトなガイダンスには system prompt を使用する。System prompt は確率論的準拠をもたらす：モデルは通常それに従うが、どの呼び出しでも逸脱する可能性がある。試験は繰り返し、一方が prompt を強化し他方が hook を追加するという二つの正解に見える答えを提示する。ハードなルールには hook を選ぶ。

Agent SDK hooks を使って異種ツール結果フォーマットを正規化するにはどうすればよいか

影響を受けるツールに PostToolUse hook を登録する。hook 内で受信フォーマットを検出し、SDK が結果を会話に挿入する前に正規化された形式に変換する。典型的なケース：ある API が Unix エポックタイムスタンプを返し、別の API が ISO 8601 を返し、三番目の API が 1・2・3 のような数値ステータスコードを返す。hook がすべてを ISO 8601 UTC タイムスタンプと名前付きステータス enum（pending・shipped・delivered）に正規化することで、モデルは常に一様なスキーマを受け取る。これにより毎ターンのフォーマット推論オーバーヘッドが除去され、一貫性のないデータでのモデルエラーの可能性が低減される。

Customer Support Resolution Agent シナリオでの払い戻し閾値パターンはどのように機能するか

エージェントに process_refund(amount, order_id) ツールがある。ポリシーでは 500 ドルを超える払い戻しには人間の承認が必要だ。実装：process_refund への PreToolUse hook が amount を検査する。amount <= 500 の場合、hook は通過させてツールは通常通り実行される。amount > 500 の場合、hook が直接払い戻しをブロックし、ヒューマンエージェントキューにエスカレーションチケットを作成し（完全なコンテキストを含む）、{status: "escalated", ticket_id: "CSR-4412"} のような合成ツール結果を返す。モデルはその結果を読んで、顧客に人間が 24 時間以内にレビューすると伝える。払い戻しの保証は構造的だ——たとえ prompt が弱められてもモデルはそれを回避できない。

PreToolUse または PostToolUse hook 自体が例外をスローした場合はどうなるか

SDK の原則的なデフォルトは、PreToolUse ではフェールクローズ（エラーになった hook はブロックとして扱う——潜在的に非準拠の呼び出しを許可するよりも安全）であり、PostToolUse ではログ付きフェールオープン（元の生結果をそのまま通過させ hook の失敗をログに記録する——結果を完全にドロップすると agentic loop が壊れる）である。どちらの場合もシステムはログを記録してアラートを送り、オペレーターが hook を修正できるようにする。CCA-F シナリオはどちらの失敗モードが適切かを問うことがある。答えは hook がセーフティゲートか（フェールクローズ）、可観測性変換か（フェールオープン）によって異なる。

Agent SDK hooks は Claude Code のスラッシュコマンドや skills と同じものか

違う。Hook は SDK レベルのライフサイクルコールバックであり、ツール呼び出しイベントで発火し、アプリケーションプロセス内で通常のコードとして実行される。スラッシュコマンドと skills は、エージェントの prompt 方法やユーザーがインタラクティブに実行できるコマンドに影響する Claude Code の設定機能だ。この二つは異なるレイヤーに存在する：hook はエージェントのランタイムツール呼び出し動作を決定論的に形成し、スラッシュコマンドと skills は prompt の構成とユーザーワークフローを形成する。共存できる——Claude Code プロジェクトはツールを使うエージェントを起動する skills を定義でき、それらのエージェントはポリシー適用のために PreToolUse hook を登録できる。

参考資料

• Claude Agent SDK 概要: https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview
• Agent SDK での Subagents: https://docs.anthropic.com/en/docs/claude-code/sdk/subagents
• Tool Calls の処理 — Tool Result のフォーマット: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/handle-tool-calls
• Writing Tools for Agents — Anthropic Engineering: https://www.anthropic.com/engineering/writing-tools-for-agents
• Tool Use 概要: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
• Claude Code セッションチームの編成: https://code.claude.com/docs/en/agent-teams
• CCA-F 試験ガイド（公式 PDF）: https://everpath-course-content.s3-accelerate.amazonaws.com/instructor/8lsy243ftffjjy1cx9lm3o2bw/public/1773274827/Claude+Certified+Architect+%E2%80%93+Foundations+Certification+Exam+Guide.pdf

関連 ExamLab 章節: 自律タスク実行のための Agentic Loops, Subagent の呼び出し、コンテキスト受け渡し、生成, ツールインターフェース設計 — 説明と境界, MCP ツールの構造化エラーレスポンス.