Agent SDK Hook — 工具呼叫攔截與資料正規化

Agent SDK Hooks 正是 CCA-F 考試用來區分「把 Claude 當成一個有智慧的提示模型」與「把 Claude 當成生產系統中一個元件」的關鍵主題。任務說明 1.5——「運用 Agent SDK Hooks 實作 tool call 攔截與資料正規化」——只測一個架構觀念：當你需要某項保證時，不是在 system prompt 裡客氣地拜託模型，而是在程式碼裡攔截 tool call 並以確定性方式強制執行。這個轉變——從機率性的提示合規，到確定性的程式強制執行——是 Domain 1（Agentic Architecture & Orchestration，佔考試 27%）中最高頻的核心心智模型。

這份學習筆記涵蓋 CCA-F 考生在這份 60 題、120 分鐘、情境式考試中需要認識的 Agent SDK Hooks 完整面向：agentic loop 內部的 hook 生命週期、PreToolUse 與 PostToolUse 的差異、標準使用情境（正規化異質工具結果、清除 PII、強制退款上限、轉接人工升級、稽核日誌）、考生常誤判執行點的陷阱，以及源自任務 1.5 題目最密集的客服解決方案 Agent 情境群的情境錨點模式。

什麼是 Agent SDK 中的 Hook？

hook 在 Claude Agent SDK 中，是一個由使用者註冊的 callback，會在 agent 執行生命週期的特定時刻觸發，讓應用程式有機會檢查、修改、攔截或記錄即將發生——或剛剛發生——的事情。Hook 是確定性的：它們是 SDK 在 agentic loop 期間同步呼叫的普通程式碼，不是模型可能選擇遵循或忽略的提示。這種確定性，正是讓 hook 成為系統具有不可妥協商業規則時的正確工具的原因。

在 CCA-F 任務 1.5 題目中，主導地位的兩種 hook 類型是 PreToolUse（在 tool call 離開應用程式前往執行之前觸發）與 PostToolUse（在 tool result 回傳後、被附加到對話並由模型處理之前觸發）。Agent Teams 和 Claude Code 還暴露了額外的生命週期 hook（TeammateIdle、TaskCreated、TaskCompleted、SessionStart、UserPromptSubmit、Stop），但就任務 1.5 而言，考試集中在這兩個 tool call hook 上。

Hook 在 Agentic Loop 中的位置 — 執行生命週期

要在考試中對 hook 做出準確推理，你需要對 agentic loop 及每個 hook 確切觸發時機有清晰的心智模型。

七步驟迴圈

每次 agentic loop 的迭代：

1. 應用程式將訊息歷史加上工具定義傳送給模型。
2. 模型產生一條 assistant 訊息，其中可能包含零個或多個 tool_use 區塊。
3. 針對每個 tool_use 區塊，SDK 即將呼叫工具——PreToolUse 在此觸發。
4. SDK 將 tool call 派發至工具處理器（一個函式、一個 MCP 伺服器，或 Read/Write/Bash 等內建工具）。
5. 工具完成並回傳結果（或錯誤）——PostToolUse 在此觸發。
6. SDK 將一條 tool_result 訊息注入對話。
7. 迴圈從步驟 1 以新的歷史記錄重複，直到模型發出 stop_reason: end_turn。

Hook 是步驟 3 和步驟 5 的確定性攔截點。理解這個生命週期後，其餘內容就迎刃而解了。

為什麼 Hook 觸發點很重要

步驟 3（PreToolUse）是在行動對現實世界產生任何影響之前，改變或阻擋行動的最後機會。步驟 5（PostToolUse）是塑造模型在下一輪將看到什麼內容的第一個機會。任務 1.5 的每道情境題，都恰好對應這兩個點中的一個——而錯誤答案選項通常是 hook 類型的混淆（需要 PreToolUse 時用了 PostToolUse，或反之）。

PreToolUse Hook — 在執行前檢查並修改 Tool 輸入

PreToolUse hook 接收工具名稱和提議的輸入參數。它可以執行以下任一操作：

• 放行（Pass through） — 回傳「照原樣繼續呼叫」的訊號。這是沒有策略違規時的預設行為。
• 修改輸入（Mutate input） — 在派發前改寫輸入。例如，加入模型遺漏的 store_id 篩選條件，或將模型提供的超出範圍數值夾緊（clamp）。
• 阻擋並替換（Block and substitute） — 阻止呼叫執行，並回傳說明拒絕原因的合成 tool result。模型讀取該合成結果後，在下一輪調整行動。
• 重新導向（Redirect） — 不是直接阻擋，而是將請求轉交給替代流程（例如人工升級佇列），並回傳指示模型向使用者說明升級結果的 tool result。

CCA-F 的 PreToolUse 標準使用情境

• 金額上限的策略閘道 — 客服解決方案 Agent 有一個 process_refund(amount, order_id) 工具。策略規定超過 USD 500 的退款需要人工核准。PreToolUse hook 檢查 amount，若超過上限，就阻擋呼叫並回傳 tool_result: "Refund above $500 requires manager approval. Escalation ticket CSR-4412 created."。模型隨後告知客戶將由人工客服跟進。
• 輸入清理（Input sanitization） — 阻擋缺少確認 token 的 delete_user 呼叫，或清除搜尋查詢中不允許的字元。
• 速率與配額強制執行 — 統計每個 session 的呼叫次數，並在達到配額後阻擋進一步的工具使用。
• 租戶範圍注入（Tenant-scoping injection） — 在每個資料庫查詢中加入目前使用者的 tenant_id 篩選條件，使跨租戶資料存取在結構上不可能發生。

PostToolUse Hook — 在注入前攔截並轉換 Tool 輸出

PostToolUse hook 接收原始 tool result——工具產生的任何字串、JSON 或結構化酬載——以及原始工具輸入和呼叫的中繼資料。它可以：

• 放行（Pass through） 結果不做修改。
• 正規化（Normalize） 異質欄位為模型更容易推理的標準形式。
• 清除（Redact） 不應進入模型 context window 的欄位（PII、機密、內部識別碼）。
• 豐富（Enrich） 結果，加入衍生值（在原始訂單記錄上加入計算好的 days_since_order 欄位）。
• 記錄（Log） 原始值與轉換後的值供稽核使用，且不改變模型所看到的內容。

正規化模式 — 讓異質資料變為標準形式

CCA-F 的常見情境：一個 agent 呼叫三個不同的上游系統（支付 API 回傳 Unix epoch 秒數、訂單 API 回傳 ISO 8601 字串、物流 API 回傳數字狀態碼如 1、2、3）。模型原則上可以自行搞清楚每種格式，但每一輪這樣做都會消耗 token、增加出錯風險，並讓對話充斥著樣板式的推理過程。PostToolUse hook 將三者正規化為標準形式——時間戳轉為 ISO 8601 UTC、狀態碼轉為具名列舉值（pending、shipped、delivered）——讓模型在每次 tool result 中看到統一、乾淨的記錄。

這個正規化使用情境是 PostToolUse 被引用最多的考題模式。若 CCA-F 題目描述不一致的上游資料格式並詢問在哪裡套用標準化，答案就是 PostToolUse hook。

清除模式 — 在注入上下文前處理 PII

客服解決方案 Agent 的工作流程經常碰觸到包含完整 PAN（卡號）、完整社會安全碼或健康資訊的原始資料庫列。PostToolUse hook 是在資料進入對話前清除這些欄位的架構最佳位置：工具仍然回傳完整記錄（讓工具處理器可以記錄或轉發給下游系統），但模型看到的版本只剩後四碼和遮罩後的識別碼。這降低了爆炸半徑：模型無法洩露它從未收到過的資料。

豐富模式 — 加入衍生欄位

有時模型能從預先計算的中繼資料中受益。PostToolUse hook 可以在原始訂單記錄上加入 days_since_order、eligible_for_refund、within_return_window 或 region_code，省去模型重新計算這些值的功夫，並降低對話中出現算術錯誤的機率。

Hook 註冊 — 附加至特定工具名稱 vs 所有工具

Hook 的註冊是考試測試的第二個決策軸（在「PreToolUse vs PostToolUse」之後）。

全域 Hook vs 特定工具 Hook

全域 hook 無論工具名稱為何，都會在每次 tool call 時觸發。將全域 hook 用於橫切關注點（cross-cutting concerns）：稽核日誌、任何工具輸出的 PII 清除、每個 session 的配額強制執行。

特定工具 hook 只在特定名稱的工具被呼叫時觸發。將特定工具 hook 用於只適用於某個工具的商業規則：USD 500 退款上限只適用於 process_refund，不適用於 lookup_order 或 send_notification。

註冊模式

Agent SDK 接受 hook 透過以下兩種方式之一：建立 agent 時的 SDK 選項（程式化註冊），或 Claude Code 中的 .claude/settings.json hook 設定。對 CCA-F 而言，你不需要背 TypeScript 函式簽章或 JSON schema；你需要認識：

• Hook 在 agent 建構時註冊，不是動態發現的。
• 工具名稱篩選條件可將 hook 限縮到特定工具。
• 同一事件上可以註冊多個 hook；SDK 按照定義好的順序執行它們。

為什麼精確性很重要

過於寬泛的 hook 會產生三個問題：（a）對不需要閘道的工具增加每次呼叫的額外開銷；（b）可能因工具輸入碰巧符合某個表面模式而誤擋；（c）將本應模組化的策略邏輯集中在單一 hook 函式中。考試題目有時會呈現兩個看起來都正確但只在 hook 範圍上有差異的選項——正確答案幾乎總是範圍更窄的那個。

Hook 排序與組合

當同一事件上有多個 hook 被註冊時，SDK 按照註冊順序執行它們。由此衍生兩種架構模式：

• 鏈式轉換（Chained transformation） — hook A 正規化時間戳、hook B 清除 PII、hook C 附加稽核中繼資料。每個 hook 消費前一個 hook 的輸出。順序很重要：若稽核日誌不應包含 PII，則清除必須在稽核日誌記錄之前執行。
• 短路阻擋（Short-circuit blocking） — 安全 hook 最先執行，可以完全阻擋呼叫；轉換 hook 只有在安全 hook 放行後才執行。

一個常見的考試陷阱：考生假設 hook 是並行或以任意順序執行的。它們不是。Hook 排序是確定性的，是架構決策面的一部分。

Hook 錯誤處理 — Hook 本身拋出例外時會發生什麼

Hook 是普通程式碼，可能會失敗。SDK 在 hook 拋出例外時的預設行為取決於 hook 類型和設定，但考試值得記住的原則是：

• PreToolUse 拋出例外，通常被視為「阻擋呼叫」——失敗關閉（fail-closed），因為出錯的策略閘道，比起視為放行的呼叫，將其視為拒絕的呼叫更安全。
• PostToolUse 拋出例外，通常回退至將原始未修改的結果傳遞過去並記錄 hook 錯誤，因為工具已經執行完畢，完全捨棄結果會破壞 agentic loop。
• Hook 超時 — 長時間執行的 hook 會阻塞 agentic loop。保持 hook 輕量，並將耗時的工作（大型日誌上傳、重量級分析）推送到 hook 同步放入佇列的 async 佇列中。

考試情境有時會問「如果正規化 hook 崩潰會怎樣？」原則性的答案是：系統應大聲失敗（記錄並發出告警），同時保持 agent 可運作——通常的做法是傳遞原始結果，並將該記錄標記為待審核。

確定性執行 vs 機率性提示合規 — CCA-F 核心心智模型

這個章節是任務 1.5 中最值得考試的觀念。內化它，直到成為反射。

兩種合規機制

選擇啟發式規則

• 若需求使用絕對詞彙（絕不、必須、在任何情況下都不得、保證），答案是 hook（或另一個確定性閘道——strict tool schema、程式碼層級驗證）。
• 若需求使用軟性詞彙（偏好、通常、鼓勵、適當時），system prompt 或許就夠了。
• 若需求涉及法律、財務或安全，即使措辭聽起來較軟，也預設使用確定性執行。

為什麼提示對合規來說不夠

Anthropic 自己的工程文章強調，system prompt 非常適合引導模型的預設行為，但無法提供有保證的合規性。模型是統計系統：在足夠多的呼叫次數下，任何機率性行為最終都會產生離群值。對於像 process_refund 這樣高頻的 tool call，即使是 99.9% 的提示合規率，大約每 1,000 次呼叫就有一次違規——對於受法律或合作夥伴合約約束的策略來說，這遠遠太多了。Hook 讓合規成為系統的結構性屬性，而非一種期望。

將違反策略的動作重新導向至替代流程

一個只對模型說「不」的 PreToolUse hook 是可接受的，但會讓使用者陷入困境。成熟的架構選擇重新導向：不只是阻擋，而是將請求派發至替代流程，並回傳一個 tool result 教導模型如何溝通結果。

人工升級模式

以客服解決方案 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. 模型讀取 tool result，向客戶說明：「您的退款申請已升級給人工客服；工單 CSR-4412 將在 24 小時內審核。」

模型永遠不會知道較低金額的退款可以自動處理——因為 hook 從未給它這個機會。合規保證是結構性的。

替代工具模式

另一種變體：PreToolUse 阻擋被禁止的工具，並回傳明確建議正確工具的結果。例如，模型嘗試對生產資料庫執行 execute_sql(raw_query)；hook 阻擋它並回傳 tool_result: "Direct SQL denied. Use the read_customer_data tool with the appropriate filter."。模型隨後用更安全的工具改寫請求。

分級審核模式

Hook 可以編碼核准分級：$100 以下的退款自動核准、$100–500 需要確認訊息、超過 $500 升級給人工。每個分級是 hook 內的一個分支。模型體驗到統一的介面（呼叫工具、接收 tool result），而 hook 則編碼了一棵任意複雜的策略樹。

Hook 中的稽核日誌 — 合規依據與除錯

Hook 是產生稽核軌跡的天然位置，因為它們能看到每次 tool call 和每次 tool result，無論模型用它們做了什麼。

PreToolUse 中應記錄的內容

• 時間戳、session ID、conversation ID。
• 工具名稱和完整輸入參數。
• 策略決定（放行 / 修改 / 阻擋 / 重新導向）。
• 若被阻擋或重新導向：規則識別碼（例如 POLICY-REFUND-500-CEILING）。

PostToolUse 中應記錄的內容

• 原始 tool result（完整的清除前複本，儲存在合規範圍的日誌中）。
• 注入對話的正規化 / 清除後版本。
• 延遲、錯誤旗標、工具處理器版本。

為什麼稽核日誌要在這裡而不在提示中

若你「請求模型記錄」——透過告訴它發出一個結構化摘要——你得到的是機率性日誌：有時正確，有時缺少欄位，有時是幻覺。Hook 產生確定性日誌。在受監管的行業（金融、醫療、客戶資料處理），確定性日誌是唯一能讓稽核人員滿意的類型。

PII 清除、遮罩與資料最小化模式

Hook 支援幾種分層的資料最小化方式：

• 完整清除（Full redaction） — 欄位在模型看到酬載之前，以 [REDACTED] 替換或完全移除。
• 遮罩（Masking） — 欄位部分保留（社會安全碼後四碼、first.l****@example.com），讓模型仍能對記錄進行推理，但看不到敏感值。
• 代符化（Tokenization） — 欄位以不透明的代符替換；在信任邊界內接受相同代符的下游工具可以解析回原始值。
• 雜湊化（Hashing） — 欄位以雜湊值替換，在不揭露原值的情況下實現關聯。

考試不測試密碼學細節；它測試的是這些轉換的正確位置是 PostToolUse hook，而不是在提示中指令模型「請不要重複說出社會安全碼」。

同步 Hook 的效能影響

每個 hook 都會對每次 tool call 增加延遲。對於發出網路呼叫的 hook（寫入 SIEM、呼叫策略決策服務），這個延遲不可忽視。

實務指引

• 盡可能讓 hook 在記憶體內執行；一個快速的正規化函式約需數微秒。
• 將慢速工作（日誌上傳、告警派發、跨系統 API 呼叫）送入 hook 同步放入佇列的 fire-and-forget 佇列後回傳。
• 以工具本身的延遲為基準衡量 hook 執行的 p99 延遲；將 5ms 工具延遲加倍的 hook 是可以接受的，但將 500ms 工具延遲加倍的 hook 在面向使用者的流程中可能會被察覺。

這對考試的意義

社群來源的考試經驗報告指出，任務 1.5 有時會詢問高吞吐量迴圈中 hook 攔截的成本。正確的答案輪廓是「hook 增加同步開銷；保持輕量，並將昂貴的工作推送到 async 佇列」。請避免「hook 與工具執行並行非同步執行」的干擾選項——它們不是。

白話文解釋 — Agent SDK Hooks 的三個類比

抽象的生命週期圖表，一旦錨定在熟悉的系統上，就會變得具體好記。以下三個類比各自照亮了 Agent SDK Hooks 的不同面向。

類比一：高鐵安檢（PreToolUse）與海關（PostToolUse）

想像台灣高鐵的車站。每位旅客（tool call）在登車（執行工具）之前，都必須通過安檢閘口——一個確定性的查驗點，工作人員核對身分、掃描行李，然後要嘛放行，要嘛要求你把超規的液體拿出來丟掉（輸入修改），要嘛直接拒絕你登車（阻擋並重新導向）。那個閘口就是 PreToolUse。每次都執行，不管旅客多禮貌、多急著趕車——安檢是結構性的。

抵達後，每位旅客（tool result）通過海關申報台——檢查員確保申報內容符合標準格式，沒收不得攜入境內的物品（清除），並蓋章記錄（稽核日誌），然後旅客才能進入國內通道（對話上下文）。那就是 PostToolUse。海關不能讓你的班機起飛——副作用已經發生了——它只能塑造進入目的地系統的內容。

這個類比讓三件事豁然開朗：（a）為什麼 PreToolUse 是「絕不」規則的正確位置——安檢在登車之前，不是下車之後；（b）為什麼 PostToolUse 無法復原副作用——班機已經降落；（c）為什麼你不會依賴「廣播中友善地請旅客自行遵守規定」（機率性提示）來取代實際的安檢閘口（確定性 hook）。

類比二：婚宴外燴的總舖師

繁忙的外燴現場有一個關鍵角色——總舖師，站在廚房出菜口與宴客桌之間。每道即將出菜的料理都要經過總舖師把關：是否送到正確的桌次（工具名稱是否匹配）、溫度是否合適（輸入是否在策略範圍內）、裝飾是否到位（欄位是否已豐富）、有沒有異物（PII 是否已清除）。不合格的菜要麼退回廚房，要麼轉到另一個工作站。

PreToolUse 是總舖師在點菜單送到廚房前把關：這道菜今天有在菜單上嗎？這位客人有飲食禁忌嗎？廚房有授權幫這位貴賓做那道特製料理嗎？PostToolUse 是總舖師在成品料理出菜前把關：擺盤、溫度、份量、點綴。總舖師從不是「透過便條紙建議廚師注意規定」——他在出菜口結構性地把關。

這個類比也說明了排序組合的道理：總舖師按順序逐一檢查（先確認擺盤、再確認點綴、再確認溫度），遇到嚴重問題就立刻停止後續檢查。Hook 排序的概念完全相同。

類比三：銀行出納的雙重控制金庫

銀行出納處理客戶交易，但某些交易（超過一定金額的提款）在現金抽屜開啟之前需要主管共簽。出納就算遇到再友善的客戶也無法繞過這個機制——抽屜本身的機械構造需要兩把鑰匙。小額交易暢行無阻；大額交易自動導向主管核准（替代流程），而客戶被告知「您的請求需要主管審核，通常需要幾分鐘」（模型向使用者傳達的合成 tool result）。

這正是退款上限模式。PreToolUse hook 是抽屜的機械構造。主管佇列是人工升級流程。合成 tool result 是出納在等候主管時告訴客戶的話。客戶的請求不是被無聲地丟棄——它被重新導向至一個能產生較慢但有效結果的流程，而客戶全程被告知狀況。

考試當天選用哪個類比

• 關於**「絕不」強制執行**與 Pre/Post 區別的題目 → 高鐵安檢類比。
• 關於正規化、豐富與檢查鏈的題目 → 總舖師類比。
• 關於重新導向至人工模式與替代流程的題目 → 銀行出納類比。

Hook 使用情境矩陣 — 何時使用哪個 Hook

任務 1.5 的常見考試陷阱

CCA-F 考試積極利用 Agent SDK Hooks 的五種反覆出現的陷阱模式。

陷阱一：PostToolUse「防止」副作用

考生有時會選擇 PostToolUse 作為「絕不執行 X」的執行點。錯誤。 PostToolUse 在工具已經執行完畢之後才觸發。如果工具刪除了生產資料表，PostToolUse 無法復原這個操作。要防止副作用，唯一正確的答案是 PreToolUse。

陷阱二：用提示工程取代 Hook

當情境陳述了硬性合規需求（法律、財務、安全），干擾選項會建議「強化 system prompt」或「在工具說明中加入範例」。這些都是機率性的。CCA-F 對硬性規則的正確答案是 hook（或另一個確定性閘道）。

陷阱三：混淆 PreToolUse 修改的範圍

PreToolUse hook 修改工具輸入，改變的是工具看到的內容，而不是模型在訊息歷史中看到的內容。若考試題目問「模型一直重複相同的錯誤輸入」，PreToolUse 輸入修改本身無法糾正模型的信念——模型仍然認為它是用原始輸入呼叫了工具。你需要使用 PostToolUse hook 在 tool result 中注入修正性說明，或在對話歷史中附加一條觀察訊息。

陷阱四：誤以為 Hook 排序是不確定的

考生有時假設 hook 是並行或以非確定性順序執行的。它們不是。Hook 排序是確定性的，遵循註冊順序。在清除 hook 之前註冊的稽核 hook，會記錄清除前的資料；在清除 hook 之後註冊的，則記錄清除後的資料。順序決定語義。

陷阱五：「Hook 處理一切」的過度延伸

反向陷阱：假設 hook 是每個架構問題的正確答案。它們不是。Hook 用於對 tool call 的確定性攔截。Hook 不是進行工具發現、context window 管理、長時間執行的子任務委派（使用 subagent）、session 持久化（使用 SDK session API）或模型行為調整（使用提示）的正確位置。在拿出 hook 之前，請仔細閱讀情境。

練習錨點 — 任務 1.5 情境題模板

CCA-F 與任務 1.5 相關的情境題，集中在客服解決方案 Agent 和開發者生產力情境上。以下是五種反覆出現的題型。

模板 A：防止 vs 觀察

一家金融科技公司建立了一個帶有 issue_card_replacement 工具的客服解決方案 Agent。策略規定每個帳戶每 30 天只允許一次換卡。團隊必須保證這個限制在並發 session 下仍然成立。他們應該實作哪種架構機制？正確：PreToolUse hook，檢查換卡計數器並阻擋後續呼叫。干擾選項：更強的 system prompt（機率性）、PostToolUse hook（事後）、工具說明改良（無法強制執行）。

模板 B：異質資料正規化

一個開發者生產力 Agent 呼叫三個以不同格式回傳時間戳的 API：Unix epoch 秒數、ISO 8601，以及自訂的 YYYYMMDD-HHMMSS 字串。團隊希望模型始終看到 ISO 8601 UTC。正規化邏輯應該放在哪裡？正確：在三個工具上都註冊 PostToolUse hook，在注入前將每種格式轉換為 ISO 8601。干擾選項：在 system prompt 中加入指令（消耗 token、機率性）、分拆成三個獨立 agent（架構層級錯誤）。

模板 C：合規性 PII 清除

一個支援 agent 擷取包含完整社會安全碼的客戶記錄。團隊必須保證社會安全碼永遠不會進入模型的 context window。應該使用哪個 hook，為什麼？正確：PostToolUse — 工具處理器有存取完整記錄的合理需求（供下游 API 使用），因此清除是在進入對話的途中執行，而不是在工具輸出的途中。干擾選項：PreToolUse（幫不上忙——問題在於回傳的資料，不在於請求）。

模板 D：重新導向至人工升級

客服情境：超過 $500 的退款必須轉給人工。哪種機制組合是正確的？正確：PreToolUse hook 阻擋直接退款、建立升級工單，並回傳描述升級情況的合成 tool result，讓模型能向使用者傳達結果。干擾選項：只阻擋不重新導向（使用者體驗差）、透過提示告訴模型在 $500 以上時偏好人工升級（機率性）。

模板 E：Hook 錯誤處理

一個正規化 hook 在遇到格式不正確的上游回應時拋出例外。最安全的預設行為是什麼？正確：傳遞原始的原始 tool result、記錄 hook 錯誤，並通知操作人員。干擾選項：完全捨棄 tool result（破壞 agentic loop）、無限重試 hook（增加延遲並有無限迴圈的風險）。

與其他 Domain 1 主題的關係

Hook 與其他 Domain 1 主題的互動方式，正是考試喜歡交叉測試的地方。

Hook vs Subagent 工具白名單

任務 1.3 介紹了 allowedTools——一個限制 subagent 可以呼叫哪些工具的 subagent 設定。allowedTools 是粗粒度、靜態、工具層級的閘道：subagent 要嘛有這個工具，要嘛沒有。Hook 是細粒度、動態、每次呼叫的閘道：subagent 有這個工具，但 hook 檢查每次呼叫的參數。使用 allowedTools 進行能力範圍限定，使用 hook 進行行為閘道。考試有時會問應該使用哪個；答案取決於限制是類別性的（使用 allowedTools）還是參數相依的（使用 hook）。

Hook vs Strict Tool Schema

任務 4.3 介紹了工具 schema 上的 strict: true——對輸出形狀的 schema 驗證確定性閘道。Hook 是對行為的程式碼層級確定性閘道。兩者都在確定性執行的一側。對於「擷取的 JSON 必須始終有 confidence 欄位」這種需求，strict schema 更簡潔；對於「退款金額不得超過 $500」這種需求，hook 是答案。

Hook 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 提供機率性合規：模型通常遵循，但在任何一次呼叫中都可能偏離。考試反覆透過呈現兩個看似正確的答案來測試這個選擇，一個強化提示，一個加入 hook。對於硬性規則，選 hook。

如何使用 Agent SDK Hooks 正規化異質 tool result 格式？

在受影響的工具上註冊 PostToolUse hook。在 hook 內部，偵測傳入格式並在 SDK 將結果注入對話之前，將其轉換為標準形式。典型情況：一個 API 回傳 Unix epoch 時間戳，另一個回傳 ISO 8601，第三個回傳數字狀態碼如 1、2、3。Hook 將三者正規化為 ISO 8601 UTC 時間戳和具名狀態列舉值（pending、shipped、delivered），讓模型始終看到統一的 schema。這消除了每輪格式推理的開銷，並降低模型在不一致資料上出錯的機率。

退款上限模式在客服解決方案 Agent 情境中如何運作？

Agent 有一個 process_refund(amount, order_id) 工具。策略規定超過 USD 500 的退款需要人工核准。實作方式：process_refund 上的 PreToolUse hook 檢查 amount。若 amount <= 500，hook 放行，工具正常執行。若 amount > 500，hook 阻擋直接退款，在人工客服佇列中建立升級工單（包含完整上下文），並回傳合成 tool result，如 {status: "escalated", ticket_id: "CSR-4412"}。模型讀取該結果，告訴客戶人工將在 24 小時內審核。退款保證是結構性的——即使提示被削弱，模型也無法繞過它。

如果 PreToolUse 或 PostToolUse hook 本身拋出例外，會發生什麼？

SDK 的原則性預設是 PreToolUse 失敗關閉（將出錯的 hook 視為阻擋——比起允許可能不合規的呼叫，將其視為拒絕更安全），以及 PostToolUse 記錄後失敗開放（傳遞原始結果並記錄 hook 失敗——完全捨棄結果會破壞 agentic loop）。兩種情況下，系統都應記錄並發出告警，讓操作人員能修復 hook。CCA-F 情境有時會問哪種失敗模式是合適的；答案取決於 hook 是安全閘道（失敗關閉）還是可觀測性轉換（失敗開放）。

Agent SDK hooks 與 Claude Code 的 slash command 或 Skills 相同嗎？

不相同。Hook 是 SDK 層級的生命週期 callback，在 tool call 事件上觸發，作為普通程式碼在你的應用程式 process 中執行。Slash command 和 Skills 是 Claude Code 的設定功能，影響 agent 的提示方式以及使用者可以互動式執行的指令。兩者處於不同的層次：hook 以確定性方式塑造 agent 的執行期 tool call 行為；slash command 和 Skills 則塑造提示組成與使用者工作流程。它們可以共存——一個 Claude Code 專案可以定義啟動工具使用 agent 的 Skills，而那些 agent 可以為策略執行註冊 PreToolUse hook。

延伸閱讀

• Claude Agent SDK 概覽: https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview
• Agent SDK 中的 Subagent: https://docs.anthropic.com/en/docs/claude-code/sdk/subagents
• 處理 Tool Call — Tool Result 格式: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/handle-tool-calls
• 為 Agent 撰寫工具 — 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 Session 團隊: 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

Related ExamHub topics: 自主任務執行的 Agentic Loop, Subagent 呼叫、上下文傳遞與生成, Tool 介面設計 — 說明與邊界, MCP 工具的結構化錯誤回應.