工具系統：42 個工具和一條治理流水線

工具不只是函式

把工具系統理解成「LLM 能呼叫的函式集合」，這個理解只對了一半。

函式只有輸入和輸出。工具還有：誰能呼叫它、在什麼情況下需要確認、失敗了怎麼辦、結果有多大該怎麼截斷、是否允許並行執行。這些不是函式的屬性，是治理的屬性。Claude Code 把這兩件事放在同一個介面裡。

Tool.ts：核心介面

每個工具都實作 Tool 介面，關鍵欄位如下：

interface Tool {
  name: string
  description: string
  inputSchema: JSONSchema
  handler: (input: unknown, context: ToolContext) => Promise<ToolResult>
  isReadOnly: boolean
  requiresConfirmation: boolean
  resultBudget?: number
}

isReadOnly 不只是語義標記。Explore Agent 在嚴格唯讀模式下運行時，這個欄位決定工具是否可用。requiresConfirmation 控制執行前是否需要暫停等待使用者確認。resultBudget 設置這個工具的輸出上限，超出時自動截斷並附上提示。

buildTool()：fail-closed 的預設值

新增工具時用 buildTool() 工廠函式，而不是直接實作介面。原因是預設值策略：

function buildTool(config: ToolConfig): Tool {
  return {
    isReadOnly: false,          // 預設非唯讀
    requiresConfirmation: true, // 預設需要確認
    ...config,
  }
}

requiresConfirmation 預設為 true，isReadOnly 預設為 false。這是 fail-closed 設計——新工具在明確豁免之前，預設走最保守的路徑。開發者忘記設置 requiresConfirmation: false 的後果是多一次確認提示，而不是靜默執行危險操作。

42 個工具的分類

42 個內建工具按功能分成幾組。

檔案操作這組最多，Read/Write/Edit/MultiEdit/Glob/LS 都在這裡。Edit 和 MultiEdit 用 diff 格式接受輸入——模型只需要描述「把哪段改成什麼」，而不是重寫整個檔案，大幅降低意外覆蓋的風險。

執行類工具以 Bash 為核心，帶 timeout 和輸出截斷，是整個工具系統裡管控最嚴格的一個，每次呼叫都要走完整 Pipeline。Grep、WebSearch、WebFetch 負責搜尋和抓取，其中 WebFetch 有內建截斷邏輯，單頁內容超出預算時不會直接塞滿上下文。

剩下兩組比較特殊。Agent 控制——AgentTool 用來派發子 Agent，TodoWrite/TodoRead 做跨迴圈的任務狀態持久化。UI 互動則是 AskUser（暫停等人）和 ShowWidget（渲染視覺元素）。後者讓模型能在對話介面裡直接產生互動式 UI，不只是文字輸出。

14 步執行 Pipeline

每次工具呼叫不是直接進 handler，要先過 14 步 Pipeline：

1. 解析輸入 JSON
2. 對照 inputSchema 做 schema 驗證
3. 查詢權限設定（project / user / global 三層）
4. 執行 Pre-hook（PreToolUse）
5. 解析 Hook 的 permissionBehavior 回傳值
6. 若需要確認，暫停並等待使用者決定
7. 檢查 isReadOnly vs 當前 Agent 模式
8. 套用 updatedInput（Hook 可能修改輸入）
9. 執行工具 handler
10. 收集結果
11. 套用 resultBudget 截斷
12. 執行 Post-hook（PostToolUse）
13. 把結果序列化為模型可讀格式
14. 更新 Tool result Token 計數

每一步都是明確的關卡。工具作者只需要實作 handler，其餘 13 步由框架處理。

Speculative Classifier

Speculative Classifier 是 Pipeline 的提速機制。

正常流程是：等模型完整輸出工具呼叫請求 → 進入 Pipeline → 步驟 3 查權限。問題是「查權限」可能涉及磁碟讀取（載入 .claude/settings.json）或 Hook 執行，有延遲。

Speculative Classifier 在串流回應到來時就開始分析工具呼叫的模式，在模型輸出完成之前預測這次呼叫需要哪些權限，提前觸發步驟 3-5。等模型真正輸出完整請求時，權限決定已經快取好了。

這個優化對短 Prompt 的效果最明顯——模型輸出快，但後續的 I/O 延遲相對長，Speculative Classifier 的提前量能消化掉大部分等待時間。

---

參考來源： 本文內容參考 Xiao Tan（@tvytlx）的《Claude Code 源碼架構深度解析 V2.0》，基於原報告的分析框架和研究成果整理。