作者：wanlanglin（文章底部有claude code源码交流群，可以和作者直接交流）https://wanlanglin.github.io/-awesome-cc-harness/

A Comprehensive Textbook on AI Agent Infrastructure Design

“The model is the agent. The code is the harness. Build great harnesses. The agent will do the rest.”

本教程基于 Claude Code 源码（~512,664 行 TypeScript）的逆向工程与系统性分析，以教科书的体例深入剖析 AI Agent Harness 的每一个设计决策、工程取舍与实现细节。

全文遵循学术写作规范，在代码分析之上构建理论框架，将零散的实现细节提炼为可复用的设计原则。

读者对象：AI 工程师、Agent 系统架构师、对 LLM 应用基础设施感兴趣的研究者。

前置知识：TypeScript 基础、LLM API 调用经验、基本的系统设计概念。

图 0-1: Harness Engineering 架构全景 — LLM 被六层 Harness 基础设施环绕：工具系统（43+）、权限模型（5 种模式）、Hooks 系统（26 事件 x 4 类型）、沙盒（文件+网络+进程隔离）、上下文工程（CLAUDE.md + 记忆 + 四级压缩）、设置与配置（7 级层级）。

目录

• • 第一章：什么是 Harness Engineering？
• • 第二章：Claude Code 架构全景
• • 第三章：Agent Loop — Harness 的心脏
• • 第四章：Tool System — Agent 的双手
• • 第五章：Permission Model — 约束架构
• • 第六章：Hooks System — 生命周期可扩展性
• • 第七章：Sandbox & Security — 安全网
• • 第八章：Context Engineering — 信息管理的艺术
• • 第九章：Settings & Configuration — Harness 的可调性
• • 第十章：MCP Integration — 扩展 Harness 的边界
• • 第十一章：Sub-Agent System — 多智能体编排
• • 第十二章：Skills & Plugins — 扩展生态
• • 第十三章：构建你自己的 Harness — 实战指南
• • 第十四章：高级模式与设计哲学
• • 第十五章：从零构建 Mini Harness（Hands-on 实战）
• • 第十六章：竞品对比分析
• • 结语：从读者到构建者
• • 参考文献
• • 附录 A：Claude Code 源码文件索引
• • 附录 B：参考资源
• • 附录 C：ToolUseContext 完整类型定义
• • 附录 D：13 条防护规则参考模型

第一章：什么是 Harness Engineering？

想象你要训练一匹野马。你不会直接骑上去——你会先搭建围栏、准备缰绳、铺好跑道。这些”基础设施”不是马本身，但没有它们，再好的马也只是一匹野马。

AI Agent 也是如此。模型（LLM）是那匹马——强大但未被驯化。Harness Engineering 就是搭围栏、做缰绳、铺跑道的工程学科。

1.1 定义

Harness Engineering（线束工程）是设计环境、约束、反馈循环和基础设施以使 AI Agent 在规模化场景下可靠运行的工程学科。

这个术语在 2026 年初由 OpenAI 工程团队正式提出。他们描述了内部系统”用超过一百万行代码，没有一行是人类写的”——工程师不再直接写代码，而是”设计让 AI Agent 可靠编写代码的系统”。

一个简单的类比帮助你理解：

┌─────────────────────────────────────────────────┐│                                                 ││   Agent = Model (LLM)                          ││   Harness = Everything Else                     ││                                                 ││   ┌──────────┐     ┌────────────────────────┐  ││   │  Claude   │ ←── │  Tools, Permissions,   │  ││   │  Opus/    │ ──→ │  Hooks, Sandbox,       │  ││   │  Sonnet   │     │  Memory, Settings,     │  ││   │          │     │  MCP, Skills, Agents   │  ││   └──────────┘     └────────────────────────┘  ││      Model              Harness                 ││                                                 │└─────────────────────────────────────────────────┘

1.2 三大支柱

要理解 Harness Engineering，把它拆成三根柱子来看最清晰。你可以把它想象成盖房子：Context Engineering 是打地基（确保信息到位），Architectural Constraints 是承重墙（确保结构不塌），Entropy Management 是物业维护（确保房子不老化）。

图 1-2: 三大支柱的工程时间分配 — Context Engineering 占据最大比例（45%），因为”Agent 看不到的信息等于不存在”；Architectural Constraints 次之（35%）；Entropy Management 占 20% 但对长期稳定性至关重要。

支柱一：Context Engineering（上下文工程）

管理信息的可访问性、结构和时机。关键技术包括：

• • 静态上下文：仓库文档、CLAUDE.md/AGENTS.md 文件、设计文档
• • 动态上下文：日志、指标、目录映射、CI/CD 状态
• • 核心原则：”Agent 无法在上下文中访问的信息不存在”

支柱二：Architectural Constraints（架构约束）

通过机械执行而非建议来建立边界：

• • 依赖层级（Types → Config → Repo → Service → Runtime → UI）
• • 确定性 Linter 执行自定义规则
• • 基于 LLM 的审计员审查 Agent 合规性
• • 结构性测试和 pre-commit hooks

反直觉的收益：约束解空间让 Agent 更高效，而非更低效——通过阻止无用探索。

支柱三：Entropy Management（熵管理）

定期清理 Agent 解决代码退化：

• • 文档一致性验证
• • 约束违规扫描
• • 模式强制执行
• • 依赖审计

1.3 Harness Engineering vs 相关学科

1.4 停下来想一想

在继续之前，试着回答这个问题：

如果你今天要构建一个 AI 编码助手，你会把 80% 的工程时间花在哪里——改进模型，还是改进模型周围的系统？

如果你的回答是”模型”，那么 Harness Engineering 会挑战你的直觉。LangChain 的案例证明，仅改变 Harness 就能在基准测试上提升 14 个百分点。模型是”给定的”，Harness 才是你能控制的。

1.5 定量证据：Harness 的投资回报率

在深入”为什么现在”之前，让我们用数据说话：

图 1-1: Harness 优化 vs 模型优化的投资回报率对比 — 在 Terminal Bench 得分和开发周期缩短上，Harness 优化的收益远超模型优化，且所需工程时间仅为后者的十分之一。

关键洞察：Harness 优化的投资回报率（ROI）远高于模型优化。一个精心设计的 CLAUDE.md 文件只需 30 分钟，但可以将 Agent 在特定项目上的表现提升 20-40%。相比之下，模型微调需要数周时间和大量计算资源，且只对特定任务有效。

1.6 为什么现在？

三个趋同因素催生了需求：

1. 1. 模型商品化 — 竞争优势从模型转向系统
2. 2. 生产部署 — Agent 从演示走向面向客户的可靠性要求
3. 3. 基准局限 — 标准指标无法衡量多小时、多步骤的 Agent 稳定性

实际影响：LangChain 仅修改 Harness 架构（不换模型），在 Terminal Bench 2.0 上从 52.8% 提升到 66.5%，从 Top 30 跃升至 Top 5。

1.5 实施层级

第二章：Claude Code 架构全景

在上一章我们建立了理论框架。从这一章开始，我们将用一个真实的、正在生产环境运行的系统来验证这些理论。这个系统就是 Claude Code——Anthropic 的官方 AI 编码助手 CLI，拥有超过 50 万行 TypeScript 代码，是目前最完整的生产级 Agent Harness 参考实现。

为什么选择 Claude Code？因为它不是一个教学项目——它是每天被数以万计的开发者使用的真实产品。它的每一个设计决策背后，都有真实的用户痛点和工程取舍。通过逆向工程它的架构，我们能学到”课本上不会写”的实战智慧。

2.1 技术栈

图 2-1: Claude Code 各目录代码行数分布 — tools/ 和 utils/ 是最大的两个目录，合计占约 32% 的代码量，反映出工具系统和基础设施工具是 Harness 的核心。

图 2-2: 各类别模块数量 — components（144）和 commands（101）数量最多，体现了 Claude Code 作为终端 UI 应用的特征。

2.2 规模

• • ~1,884 TypeScript/TSX 文件
• • 512,664 行代码
• • 43+ 工具
• • 100+ Slash 命令
• • 80+ React Hooks
• • 144+ UI 组件
• • 22+ 服务模块
• • 26+ Hook 事件

2.3 目录结构

src/├── main.tsx                    # 入口点，CLI 引导（803 KB）├── query.ts                    # 核心 Agent 循环（68 KB）├── QueryEngine.ts              # LLM 查询引擎（46 KB）├── Tool.ts                     # Tool 基础接口（29 KB）├── tools.ts                    # Tool 注册表（25 KB）├── Task.ts                     # 任务类型定义├── commands.ts                 # 命令注册│├── tools/                      # 43 个工具目录│   ├── BashTool/              # Shell 命令执行│   ├── FileReadTool/          # 文件读取│   ├── FileWriteTool/         # 文件创建│   ├── FileEditTool/          # 部分文件修改│   ├── GlobTool/              # 文件模式匹配│   ├── GrepTool/              # ripgrep 内容搜索│   ├── AgentTool/             # 子 Agent 生成│   ├── SkillTool/             # Skill 执行│   ├── MCPTool/               # MCP 服务器调用│   ├── WebFetchTool/          # URL 内容抓取│   ├── WebSearchTool/         # 网页搜索│   └── ...                    # 更多工具│├── commands/                   # ~101 个命令目录│   ├── commit/                # Git 提交│   ├── review/                # 代码审查│   ├── mcp/                   # MCP 管理│   ├── skills/                # Skill 管理│   └── ...│├── components/                 # 144+ React/Ink 终端组件├── hooks/                      # 80+ 自定义 React Hooks├── services/                   # 22 个服务子目录│   ├── api/                   # Anthropic API 客户端│   ├── mcp/                   # MCP 协议连接│   ├── oauth/                 # OAuth 认证│   ├── lsp/                   # 语言服务器协议│   ├── compact/               # 对话压缩│   ├── plugins/               # 插件加载│   └── ...│├── utils/                      # 33+ 子目录，100+ 文件│   ├── permissions/           # 权限逻辑│   ├── hooks.ts               # Hook 执行引擎│   ├── hooks/                 # Hook 配置管理│   ├── sandbox/               # 沙盒适配器│   ├── settings/              # 设置管理│   ├── bash/                  # Shell 工具│   ├── memdir/                # 持久记忆目录│   └── ...│├── state/                      # 应用状态管理├── entrypoints/                # CLI/MCP/SDK 入口├── bridge/                     # IDE 双向通信├── coordinator/                # 多 Agent 编排├── skills/                     # Skill 系统├── plugins/                    # 插件系统├── memdir/                     # 记忆目录系统├── schemas/                    # Zod 验证 Schema├── types/                      # 类型定义└── constants/                  # 应用常量

2.4 入口点流程

main.tsx → 并行预取（MDM设置 + Keychain + API预连接）    ↓Commander.js CLI 解析器初始化    ↓preAction Hook: init() → 遥测 → 插件 → 迁移 → 远程设置    ↓React/Ink 渲染器启动    ↓交互式 REPL/对话循环

设计哲学：Claude Code 的入口点 main.tsx（803 KB）采用延迟加载策略。重型模块（OpenTelemetry, gRPC, analytics）在需要时才加载，而关键路径（MDM 设置、Keychain）则并行预取，确保启动速度。

2.5 核心数据流全景图

┌─────────────────────────────────────────────────────────────────────┐│                    Claude Code 数据流全景                             ││                                                                      ││  用户输入 ──→ UserPromptSubmit Hook ──→ Slash Command 解析           ││     │                                                                ││     v                                                                ││  QueryEngine.submitMessage()                                         ││     │                                                                ││     ├─→ 系统提示构建: base + tools + CLAUDE.md + MCP + memory       ││     ├─→ 消息规范化: normalizeMessagesForAPI()                        ││     │   ├─ 重排序 attachment 消息                                    ││     │   ├─ 合并连续 user/assistant 消息                              ││     │   ├─ 剥离 PDF/图片错误的重复内容                                ││     │   ├─ 规范化工具名称（别名→正式名）                              ││     │   └─ 工具搜索引用块处理                                        ││     │                                                                ││     v                                                                ││  queryLoop() [while(true)]                                           ││     │                                                                ││     ├─→ 压缩管道: snip → micro → collapse → auto                    ││     ├─→ API 调用: deps.sample() [流式]                               ││     │                                                                ││     ├─→ 工具执行: StreamingToolExecutor (并发) / runTools (顺序)     ││     │   │                                                            ││     │   ├─→ 工具分区: partitionToolCalls()                           ││     │   │   ├─ isConcurrencySafe=true → 并发执行                     ││     │   │   └─ isConcurrencySafe=false → 串行执行                    ││     │   │                                                            ││     │   └─→ 每个工具:                                                ││     │       ├─ Zod schema 验证                                       ││     │       ├─ tool.validateInput()                                  ││     │       ├─ PreToolUse Hook                                       ││     │       ├─ 权限检查 (rules → mode → classifier)                 ││     │       ├─ Sandbox 包装 (BashTool)                               ││     │       ├─ tool.call() [实际执行]                                ││     │       └─ PostToolUse Hook                                      ││     │                                                                ││     ├─→ 错误恢复: 7 个 continue 站点                                ││     └─→ Stop Hook → 终止或继续                                      ││                                                                      ││  终止 → SessionEnd Hook → 转录保存 → 退出                           │└─────────────────────────────────────────────────────────────────────┘

2.6 消息类型系统

Claude Code 定义了丰富的消息类型系统，每种类型在 Agent Loop 中有不同的处理路径：

// src/types/message.ts — 消息类型层次type Message =  | UserMessage           // 人类输入（或工具结果）  | AssistantMessage      // 模型响应（文本 + 工具调用）  | AttachmentMessage     // 记忆/资源附件  | SystemMessage         // 系统消息  | SystemLocalCommandMessage  // 本地工具结果（bash, read 等）  | ToolUseSummaryMessage // 压缩后的工具历史  | TombstoneMessage      // 已删除消息标记  | ProgressMessage       // 流式进度更新

消息规范化（normalizeMessagesForAPI）是一个复杂的管道，处理包括：

• • 连续用户消息合并：Bedrock 不支持多个连续 user 消息，API 层面将它们合并
• • PDF/图片错误内容剥离：如果上传的 PDF 太大触发错误，后续轮次中自动剥离该内容，防止重复发送
• • 工具名称规范化：别名（如旧名称）映射到当前正式名称
• • Tool Reference 处理：当 Tool Search 启用时保留引用块，禁用时剥离
• • 虚拟消息过滤：REPL 内部工具调用的显示消息不发送给 API

第三章：Agent Loop — Harness 的心脏

如果 Harness 是一辆汽车，Agent Loop 就是它的发动机。不管你的座椅多豪华、安全气囊多先进，没有发动机车就不能跑。

本章是全书最重要的一章。我们将逐行拆解 Claude Code 的核心循环——queryLoop()——看它如何用一个 while(true) 驱动整个 AI 编码助手。读完本章，你会对”Agent 是如何工作的”有一个从底层到顶层的完整理解。

Agent Loop 是整个 Harness 最核心的组件。Claude Code 的实现位于 src/query.ts 的 queryLoop() 函数。

3.1 基本架构：无限循环 + Async Generator

以下是 Claude Code 真实源码中 queryLoop 的签名和初始化（src/query.ts）：

// src/query.ts — 真实的函数签名async function* queryLoop(  params: QueryParams,  consumedCommandUuids: string[],): AsyncGenerator<  | StreamEvent  | RequestStartEvent  | Message  | TombstoneMessage  | ToolUseSummaryMessage,  Terminal> {  // ===== 不可变参数 — 循环期间永不重新赋值 =====  const {    systemPrompt, userContext, systemContext,    canUseTool, fallbackModel, querySource,    maxTurns, skipCacheWrite,  } = params  const deps = params.deps ?? productionDeps()  // ===== 可变跨迭代状态 =====  // 循环体在每次迭代开始时解构此对象以保持裸名读取。  // Continue 站点写入 `state = { ... }` 而不是 9 个独立赋值。  let state: State = {    messages: params.messages,    toolUseContext: params.toolUseContext,    maxOutputTokensOverride: params.maxOutputTokensOverride,    autoCompactTracking: undefined,    stopHookActive: undefined,    maxOutputTokensRecoveryCount: 0,    hasAttemptedReactiveCompact: false,    turnCount: 1,    pendingToolUseSummary: undefined,    transition: undefined,  // 为什么上次迭代 continue 了  }  // 预算跟踪跨压缩边界（循环局部，不在 State 上）  let taskBudgetRemaining: number | undefined = undefined  // 查询配置快照（一次性捕获环境/statsig/会话状态）  const config = buildQueryConfig()  // 记忆预取（使用 `using` 确保在生成器退出时清理）  using pendingMemoryPrefetch = startRelevantMemoryPrefetch(    state.messages, state.toolUseContext,  )  while (true) {    // ... 循环体（下文详解）  }}

State 类型定义（这是循环的”骨架”）：

type State = {  messages: Message[]  toolUseContext: ToolUseContext  autoCompactTracking: AutoCompactTrackingState | undefined  maxOutputTokensRecoveryCount: number  hasAttemptedReactiveCompact: boolean  maxOutputTokensOverride: number | undefined  pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined  stopHookActive: boolean | undefined  turnCount: number  transition: Continue | undefined  // 上次迭代为何 continue}

下面用状态图展示 queryLoop 的完整生命周期——每个状态对应循环中的一个阶段，每条边对应一个 transition reason：

简化后的逻辑流（帮助理解）：

while (true) {    // 1. 解构状态    const { messages, toolUseContext, ... } = state;    // 2. 压缩管道    // 3. 构建系统提示 + 规范化消息    // 4. 调用 LLM API（流式）    // 5. 收集 tool_use 块    // 6. 错误恢复（7 个 continue 站点）    // 7. 工具执行    // 8. Stop Hook → 终止或继续    // 9. 更新状态 → continue}

设计哲学：

• • Async Generator：不是返回最终结果，而是 yield 每一个中间事件（流式事件、消息、墓碑消息）。这使客户端可以在 API 调用完成前就开始渲染。
• • 无限循环 + 显式退出：循环只在 return Terminal 时退出。这比有限循环更灵活，因为很多恢复路径需要重新迭代。
• • 单一 State 对象：每次迭代开始时解构 State，在 continue 站点整体重新赋值，维护伪不可变语义。

3.2 循环的七个 Continue 站点

Claude Code 的 queryLoop 有 7+ 个 continue 站点，每个对应不同的恢复场景：

┌─────────────────────────────────────────────────┐│                 queryLoop()                      ││                                                  ││  ┌──────────────────────────────────────────┐   ││  │ Continue Site 1: Proactive Compaction     │   ││  │ 触发: token 超过阈值                      │   ││  │ 动作: autocompact → 新消息 → continue     │   ││  └──────────────────────────────────────────┘   ││                                                  ││  ┌──────────────────────────────────────────┐   ││  │ Continue Site 2: Prompt Too Long          │   ││  │ 触发: API 返回 prompt-too-long 错误       │   ││  │ 动作: context-collapse → reactive compact │   ││  └──────────────────────────────────────────┘   ││                                                  ││  ┌──────────────────────────────────────────┐   ││  │ Continue Site 3: Max Output Tokens        │   ││  │ 触发: 模型输出截断                        │   ││  │ 动作: 升级 8k→64k → 多轮重试（最多3次）   │   ││  └──────────────────────────────────────────┘   ││                                                  ││  ┌──────────────────────────────────────────┐   ││  │ Continue Site 4: Fallback Model           │   ││  │ 触发: FallbackTriggeredError             │   ││  │ 动作: 切换模型 → 重试请求                 │   ││  └──────────────────────────────────────────┘   ││                                                  ││  ┌──────────────────────────────────────────┐   ││  │ Continue Site 5: Stop Hook Blocking       │   ││  │ 触发: 用户 Hook 要求额外轮次              │   ││  │ 动作: 注入 Hook 消息 → continue           │   ││  └──────────────────────────────────────────┘   ││                                                  ││  ┌──────────────────────────────────────────┐   ││  │ Continue Site 6: Image/Media Errors       │   ││  │ 触发: ImageSizeError / ImageResizeError   │   ││  │ 动作: 反应式压缩（移除图片）→ continue    │   ││  └──────────────────────────────────────────┘   ││                                                  ││  ┌──────────────────────────────────────────┐   ││  │ Continue Site 7: Tool Execution           │   ││  │ 触发: 正常工具执行完成                    │   ││  │ 动作: 收集结果 → 更新状态 → continue      │   ││  └──────────────────────────────────────────┘   ││                                                  ││  ┌──────────────────────────────────────────┐   ││  │ return Terminal — 唯一的退出点             │   ││  │ 条件: 无工具调用 + Stop Hook 不阻止        │   ││  └──────────────────────────────────────────┘   │└─────────────────────────────────────────────────┘

3.3 压缩管道（Compaction Pipeline）

上下文窗口是有限的——即使是 1M token 的窗口，在长对话中也会被填满。Claude Code 实现了一个四级压缩管道，这是它最精巧的子系统之一。

源码批注分析：关于 Microcompact 和 Snip 的执行顺序，源码注释道：“Apply snip before microcompact (both may run — they are not mutually exclusive)… snipTokensFreed is plumbed to autocompact: snip’s threshold check must reflect what snip removed.” 这揭示了一个微妙的数据流依赖：Snip 释放的 token 数必须传递给 Autocompact 的阈值检查，否则 Autocompact 会低估已释放的空间，导致不必要的全对话摘要。

关于 Context-Collapse，注释道：“Nothing is yielded — the collapsed view is a read-time projection… summary messages live in the collapse store, not the REPL array.” 这意味着 Level 3 不修改任何数据结构——它只是改变了”读取方式”。这种设计使得 collapse 可以跨轮次持久化，而且完全可逆。

每级独立运作，但有严格的执行顺序约束：

┌────────────────────────────────────────────────────────┐│                  Compaction Pipeline                     ││                                                         ││  Level 1: Snip Compact（每轮）                          ││  ├─ Feature-gated 历史截断                              ││  ├─ 追踪释放的 token 数                                  ││  └─ 最轻量，几乎无延迟                                   ││                                                         ││  Level 2: Microcompact（每轮）                           ││  ├─ 将 3 轮前的工具结果替换为 "[Previous: used {tool}]"  ││  ├─ 缓存压缩结果                                        ││  └─ 延迟边界消息直到 API 响应（知道 cache_deleted_input） ││                                                         ││  Level 3: Context-Collapse（读时投射）                   ││  ├─ 不修改消息数组，而是在读取时投射                      ││  ├─ 按粒度排空可折叠上下文                               ││  └─ 低成本，渐进式                                      ││                                                         ││  Level 4: Autocompact（>50k tokens 时触发）              ││  ├─ 保存完整转录到磁盘                                   ││  ├─ LLM 总结所有消息                                     ││  ├─ 用摘要替换所有消息                                   ││  └─ 最重量级，但释放最多空间                              ││                                                         ││  执行顺序: snip → micro → context-collapse → auto        ││  各级互不排斥，可组合运行                                 │└────────────────────────────────────────────────────────┘

设计哲学：

• • 渐进式：先尝试轻量操作，只在必要时升级到重量操作
• • 边界延迟：Microcompact 的边界消息延迟到 API 响应后，因为此时才知道缓存命中情况
• • 预算追踪跨压缩边界：taskBudgetRemaining 在压缩前捕获最终窗口，累计跨多次压缩

3.4 工具执行编排

Claude Code 有两种工具执行模式，实际生产中两者共存：

模式 1: StreamingToolExecutor（默认 — 边流式边执行）

// src/services/tools/toolOrchestration.ts — 真实代码export class StreamingToolExecutor {  private tools: TrackedTool[] = []  private toolUseContext: ToolUseContext  private hasErrored = false  // 子 AbortController：当一个 Bash 工具出错时，  // 兄弟子进程立即死亡，但不中止父级查询  private siblingAbortController: AbortController  private discarded = false  addTool(block: ToolUseBlock, assistantMessage: AssistantMessage): void {    const toolDefinition = findToolByName(this.toolDefinitions, block.name)    if (!toolDefinition) {      // 工具不存在 → 立即创建错误结果      this.tools.push({        id: block.id, block, assistantMessage,        status: 'completed',        isConcurrencySafe: true,        pendingProgress: [],        results: [createUserMessage({          content: [{            type: 'tool_result',            content: `<tool_use_error>Error: No such tool: ${block.name}</tool_use_error>`,            is_error: true,            tool_use_id: block.id,          }],        })],      })      return    }    // 解析输入并判断是否可并发    const parsedInput = toolDefinition.inputSchema.safeParse(block.input)    const isConcurrencySafe = parsedInput?.success      ? Boolean(toolDefinition.isConcurrencySafe(parsedInput.data))      : false    this.tools.push({      id: block.id, block, assistantMessage,      status: 'queued', isConcurrencySafe,      pendingProgress: [],    })    void this.processQueue()  // 立即开始处理  }  // 当流式回退发生时，丢弃所有待处理和进行中的工具  discard(): void { this.discarded = true }}

关键设计：addTool() 在模型流式生成过程中被调用。每当识别到一个完整的 tool_use JSON 块，该工具立即排队执行。模型还在生成第二个工具调用时，第一个已经在运行了。

模式 2: runTools()（回退 — 分区后执行）

// src/services/tools/toolOrchestration.ts — 真实代码export async function* runTools(  toolUseMessages: ToolUseBlock[],  assistantMessages: AssistantMessage[],  canUseTool: CanUseToolFn,  toolUseContext: ToolUseContext,): AsyncGenerator<MessageUpdate, void> {  let currentContext = toolUseContext  // 核心设计：工具分区  for (const { isConcurrencySafe, blocks } of partitionToolCalls(    toolUseMessages, currentContext,  )) {    if (isConcurrencySafe) {      // ===== 只读批次：并发执行 =====      const queuedContextModifiers: Record<string, ((ctx) => ctx)[]> = {}      for await (const update of runToolsConcurrently(blocks, ...)) {        if (update.contextModifier) {          // 收集上下文修改器，延迟应用          queuedContextModifiers[update.contextModifier.toolUseID]            ?.push(update.contextModifier.modifyContext)        }        yield { message: update.message, newContext: currentContext }      }      // 批次完成后，按顺序应用所有上下文修改      for (const block of blocks) {        for (const modifier of queuedContextModifiers[block.id] ?? []) {          currentContext = modifier(currentContext)        }      }    } else {      // ===== 写入批次：串行执行 =====      for await (const update of runToolsSerially(blocks, ...)) {        if (update.newContext) currentContext = update.newContext        yield { message: update.message, newContext: currentContext }      }    }  }}

工具分区算法 (partitionToolCalls)：

输入: [Read("a.ts"), Read("b.ts"), Write("c.ts"), Read("d.ts")]分区结果:  批次 1: { isConcurrencySafe: true,  blocks: [Read("a.ts"), Read("b.ts")] }  批次 2: { isConcurrencySafe: false, blocks: [Write("c.ts")] }  批次 3: { isConcurrencySafe: true,  blocks: [Read("d.ts")] }执行顺序: 批次 1 并发 → 批次 2 串行 → 批次 3 并发

设计哲学：只读工具（Read, Glob, Grep）天然可并发——它们不修改状态。写入工具（Write, Edit, Bash）必须串行，因为它们可能依赖前一个工具的副作用。分区算法将连续的同类工具分组，在安全性和性能之间取得最优平衡。上下文修改器（contextModifier）被收集并延迟应用，确保并发执行期间的上下文一致性。

为什么这很重要？ 假设 Agent 要读取 10 个文件来回答一个架构问题。如果没有工具分区，这 10 个 Read 会一个接一个串行执行——每个可能需要几十毫秒。有了分区，它们并发执行，总时间约等于最慢的那一个。在实际使用中，这让”读取代码库”这类操作从秒级降到毫秒级。这种优化对用户来说是”感觉上的流畅”——你不需要知道原理，但你会注意到它快。

3.5 错误恢复级联（含真实源码）

Claude Code 对可恢复错误实现了级联恢复策略。以下是 src/query.ts 中的真实代码：

Prompt Too Long (413) 恢复

// src/query.ts — 真实的 413 恢复代码if (isWithheld413) {  // 第 1 步: 排空 context-collapse 队列  // 只有在上次 transition 不是 collapse_drain_retry 时才尝试  // （如果已经排空过但仍然 413，跳过直接进入 reactive compact）  if (feature('CONTEXT_COLLAPSE') && contextCollapse      && state.transition?.reason !== 'collapse_drain_retry') {    const drained = contextCollapse.recoverFromOverflow(messagesForQuery, querySource)    if (drained.committed > 0) {      state = { ...state,        messages: drained.messages,        transition: { reason: 'collapse_drain_retry', committed: drained.committed },      }      continue  // ← Continue Site 1    }  }}// 第 2 步: Reactive Compact（完整摘要）if ((isWithheld413 || isWithheldMedia) && reactiveCompact) {  const compacted = await reactiveCompact.tryReactiveCompact({    hasAttempted: hasAttemptedReactiveCompact,  // 防止无限循环    querySource,    aborted: toolUseContext.abortController.signal.aborted,    messages: messagesForQuery,    cacheSafeParams: { systemPrompt, userContext, systemContext, ... },  })  if (compacted) {    // 预算跟踪：捕获压缩前的最终上下文窗口    if (params.taskBudget) {      const preCompactContext = finalContextTokensFromLastResponse(messagesForQuery)      taskBudgetRemaining = Math.max(0,        (taskBudgetRemaining ?? params.taskBudget.total) - preCompactContext)    }    const postCompactMessages = buildPostCompactMessages(compacted)    for (const msg of postCompactMessages) { yield msg }    state = { ...state,      messages: postCompactMessages,      hasAttemptedReactiveCompact: true,      transition: { reason: 'reactive_compact_retry' },    }    continue  // ← Continue Site 2  }  // 第 3 步: 所有恢复失败 → 向用户报告  // 关键：不要进入 Stop Hooks！模型从未产生有效响应，  // Stop Hooks 无法有意义地评估。运行 Stop Hooks 会造成死亡螺旋：  // error → hook blocking → retry → error → ...  yield lastMessage  void executeStopFailureHooks(lastMessage, toolUseContext)  return { reason: 'prompt_too_long' }}

Max Output Tokens 恢复

// src/query.ts — 真实的 max_output_tokens 恢复代码if (isWithheldMaxOutputTokens(lastMessage)) {  // 升级重试：如果使用了默认的 8k 上限，升级到 64k 重试 **同一请求**  // 无 meta 消息，无多轮交互  const capEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_otk_slot_v1', false)  if (capEnabled && maxOutputTokensOverride === undefined      && !process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS) {    logEvent('tengu_max_tokens_escalate', { escalatedTo: ESCALATED_MAX_TOKENS })    state = { ...state,      maxOutputTokensOverride: ESCALATED_MAX_TOKENS,  // 64k      transition: { reason: 'max_output_tokens_escalate' },    }    continue  // ← Continue Site 3  }  // 多轮恢复：注入恢复消息，要求模型从断点继续  if (maxOutputTokensRecoveryCount < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {  // 限制 3 次    const recoveryMessage = createUserMessage({      content: `Output token limit hit. Resume directly — no apology, no recap. ` +        `Pick up mid-thought if that is where the cut happened. ` +        `Break remaining work into smaller pieces.`,      isMeta: true,    })    state = { ...state,      messages: [...messagesForQuery, ...assistantMessages, recoveryMessage],      maxOutputTokensRecoveryCount: maxOutputTokensRecoveryCount + 1,      transition: {        reason: 'max_output_tokens_recovery',        attempt: maxOutputTokensRecoveryCount + 1,      },    }    continue  // ← Continue Site 4  }  // 恢复耗尽 → 展示被截断的错误  yield lastMessage}

Stop Hook 恢复

// src/query.ts — Stop Hook 阻止后的恢复const stopHookResult = yield* handleStopHooks(  messagesForQuery, assistantMessages, systemPrompt,  userContext, systemContext, toolUseContext, querySource, stopHookActive,)if (stopHookResult.preventContinuation) {  return { reason: 'stop_hook_prevented' }}if (stopHookResult.blockingErrors.length > 0) {  state = { ...state,    messages: [...messagesForQuery, ...assistantMessages, ...stopHookResult.blockingErrors],    maxOutputTokensRecoveryCount: 0,    // 关键：保留 hasAttemptedReactiveCompact 标志！    // 如果 compact 已经运行但无法恢复 prompt-too-long，    // 重置此标志会导致无限循环：    // compact → 仍然太长 → error → stop hook → compact → ...    hasAttemptedReactiveCompact,    stopHookActive: true,    transition: { reason: 'stop_hook_blocking' },  }  continue  // ← Continue Site 5}

所有终止原因

// query.ts 中的 10 种终止原因return { reason: 'completed' }           // 正常完成（无工具调用 + Stop Hook 不阻止）return { reason: 'blocking_limit' }      // 硬性 token 限制return { reason: 'stop_hook_prevented' } // Stop Hook 阻止继续return { reason: 'aborted_streaming' }   // 用户中断（模型响应中）return { reason: 'aborted_tools' }       // 用户中断（工具执行中）return { reason: 'hook_stopped' }        // Hook 附件停止继续return { reason: 'max_turns', turnCount }// 达到最大轮次限制return { reason: 'prompt_too_long' }     // 413 恢复耗尽return { reason: 'image_error' }         // 图片/PDF 太大return { reason: 'model_error', error }  // 意外异常

源码批注深度分析：

以下洞察来自 Claude Code 源码中的内部开发者注释，揭示了生产环境中的真实工程挑战：

1. 错误扣留（Error Withholding）策略

源码注释写道：“yielding early would leak intermediate errors to consumers like cowork/desktop that terminate on any error field, even though recovery is still running.”

这意味着 queryLoop 不是在发现错误时立即 yield，而是扣留错误（withheld），等恢复流程走完后才决定是否展示。这防止了下游消费者（IDE 扩展、桌面应用）看到中间态的错误就提前终止。

2. 压缩边界的预算跟踪

源码注释写道：“remaining is undefined until first compact fires — before compact the server sees full history and counts down from {total} itself (see api/api/sampling/prompt/renderer.py:292); after compact, server only sees summary and would under-count spend.”

这揭示了一个精妙的服务端-客户端协同设计：压缩前，服务端能看到完整历史并自己计算预算消耗；压缩后，服务端只能看到摘要，所以客户端必须告诉服务端”你看不到的那部分消耗了多少”。

3. hasAttemptedReactiveCompact 不重置的原因

注意 Stop Hook 恢复中 hasAttemptedReactiveCompact 标志被保留而非重置。源码注释解释：如果 compact 已经运行但无法恢复 prompt-too-long，重置此标志会导致无限循环：compact → 仍然太长 → error → stop hook → compact → …。这是一个真实的生产 bug 修复。

4. 记忆预取的 using 语义

using pendingMemoryPrefetch = startRelevantMemoryPrefetch(...) 使用了 TC39 的 Explicit Resource Management 提案（using 关键字）。源码注释道：“Fired once per user turn — the prompt is invariant across loop iterations, so per-iteration firing would ask sideQuery the same question N times.”using 确保在生成器退出（正常或异常）时自动清理预取资源。

教学要点：这些细节揭示了一个核心原则——生产级 Agent Loop 的复杂性不在于”循环本身”，而在于”循环失败时如何优雅恢复”。一个 30 行的 while(true) 就能实现基本的 Agent Loop，但处理好所有边界情况需要 1800+ 行。这中间的差距就是 Harness Engineering 的全部价值。

3.6 停下来想一想

读完 Agent Loop，试着回答：

1. 1. 为什么 queryLoop 用 while(true) 而不是递归？（提示：考虑内存和栈深度）
2. 2. 为什么压缩管道有 4 级而不是 1 级？（提示：考虑成本和延迟的权衡）
3. 3. 如果你要给循环添加一个新的恢复路径（比如”API 密钥过期”），你需要修改哪些地方？

这些问题没有标准答案，但思考它们会帮助你理解”为什么”而不仅仅是”怎么做”。

图 3-2: (左) 最小实现 vs 生产实现的复杂性对比（对数刻度）— 代码行数增长 60 倍，但每个维度的增长都对应真实的生产需求。(右) 四级压缩管道的 Token 释放效率 — 从 180K 逐级降至 45K。

图 3-3: 7 个 continue 站点的触发频率估计 — “Next Turn”（正常推进）占 95%，错误恢复站点合计约 5%，但正是这 5% 的代码（约 500 行）防止了会话中断和成本失控。

图 3-1: queryLoop() 状态机 — 展示 7 个 continue 站点、4 级压缩管道、StreamingToolExecutor 并行执行和 10 种终止原因的完整流转。

3.7 定量分析：Agent Loop 的复杂性度量

为了量化”最小 Agent Loop”和”生产 Agent Loop”之间的差距，我们对 src/query.ts 进行了代码度量分析：

复杂性增长分析：从 30 行到 1,800 行是 60 倍的增长。但这不是”过度工程”——每一行都对应一个真实的生产问题。例如：

• • hasAttemptedReactiveCompact 标志只有 1 行，但它防止了一个会消耗数千美元 API 费用的无限循环 bug。
• • taskBudgetRemaining 跟踪逻辑约 20 行，但它是唯一能在压缩边界后正确计算 Token 消耗的机制。
• • StreamingToolExecutor 约 200 行，但它将多工具执行延迟从 O(n) 降到 O(1)（最慢工具的时间）。

3.8 Agent Loop 的设计哲学总结

1. 1. 弹性优于刚性：7+ 个 continue 站点允许从几乎任何错误中恢复
2. 2. 渐进式降级：每种错误先尝试最轻量的恢复，逐步升级
3. 3. 流式优先：Async Generator 使每个中间状态都可观察
4. 4. 状态显式化：单一 State 对象，无隐式全局状态
5. 5. 可观测性内建：每个恢复点都有 analytics 和 profiling

第四章：Tool System — Agent 的双手

Agent Loop 是发动机，那工具系统就是方向盘和油门。发动机再强大，如果不能操控方向、调节速度，车也到不了目的地。

在 Claude Code 中，模型（LLM）本身不能读文件、不能运行命令、不能搜索代码。它唯一能做的就是生成文本。但通过工具系统，这些文本被翻译成真实的操作——读一个文件、编辑一行代码、运行一个测试。

本章我们来看 Claude Code 如何设计一个 43+ 工具的系统，每个工具既是独立的、又是统一管理的。这套设计模式你可以直接复用到自己的 Agent 项目中。

工具系统是 Harness 中 Agent 与外部世界交互的唯一通道。Claude Code 实现了一个 43+ 工具的系统，每个工具都是自包含模块。

4.1 Tool 接口定义

位于 src/Tool.ts，这是所有工具的基础类型：

type Tool<  Input extends AnyObject = AnyObject,  Output = unknown,  P extends ToolProgressData = ToolProgressData,> = {  // ===== 核心标识 =====  name: string;                    // 工具名称（主标识符）  aliases?: string[];              // 别名（向后兼容）  userFacingName(): string;        // 显示名称  // ===== Schema & 验证 =====  inputSchema: ZodType<Input>;     // Zod 输入验证  inputJSONSchema?: JSONSchema;    // 可选 JSON Schema（MCP 工具）  outputSchema?: ZodType<Output>;  // 可选输出类型  validateInput(input): Promise<ValidationResult>;  // ===== 执行 =====  call(    args: Input,    context: ToolUseContext,    canUseTool: CanUseTool,    parentMessage: AssistantMessage,    progressCallback?: ProgressCallback<P>,  ): Promise<ToolResult<Output>>;  // ===== 权限 & 安全 =====  checkPermissions(args, context): Promise<PermissionDecision>;  isConcurrencySafe(args): boolean;      // 能否并行执行  isDestructive(args): boolean;          // 不可逆操作？  isReadOnly(): boolean;                 // 只读操作？  preparePermissionMatcher(args): string; // Hook 模式匹配  // ===== 行为 =====  isEnabled(): boolean;                  // 特性门控检查  interruptBehavior(): 'cancel' | 'block';  requiresUserInteraction(): boolean;  // ===== 渲染 =====  renderToolUseMessage(args): ReactElement;  renderToolResultMessage(result): ReactElement;  renderToolUseProgressMessage(progress): ReactElement;  // ===== 搜索 & 折叠 =====  searchHint: string;                    // ToolSearch 的 3-10 词关键词  shouldDefer: boolean;                  // 延迟加载  alwaysLoad: boolean;                   // 永不延迟  // ===== 描述（动态生成）=====  description(isNonInteractive?: boolean): string;  prompt(context): string;               // 系统提示片段};

设计哲学：

• • 自描述：每个工具携带自己的 Schema、描述、权限逻辑和渲染函数
• • 双 Schema 支持：Zod（内部验证） + JSON Schema（MCP 互操作）
• • 动态描述：description() 接收交互模式参数，非交互模式下可省略UI相关说明
• • 延迟加载：shouldDefer 让不常用工具在第一轮不加载到模型上下文，节省 token

初学者常见误区：很多人设计工具系统时只关注 call() 方法——”工具能做什么”。但在生产环境中，权限检查、输入验证、进度渲染占了工具代码的 80%。一个好的工具接口不只是”执行”，而是”安全地、可观测地、可中断地执行”。

4.2 工具注册表

位于 src/tools.ts：

// 唯一的工具真实来源function getAllBaseTools(): Tool[] {  return [    // === 始终加载 ===    AgentTool,    TaskOutputTool,    BashTool,    FileReadTool,    FileEditTool,    FileWriteTool,    WebFetchTool,    WebSearchTool,    AskUserQuestionTool,    SkillTool,    // ...更多始终可用的工具    // === 特性门控 ===    ...(feature('PROACTIVE') ? [SleepTool] : []),    ...(feature('AGENT_TRIGGERS') ? [ScheduleCronTool] : []),    ...(feature('COORDINATOR_MODE') ? [TeamCreateTool, TeamDeleteTool] : []),    ...(isReplModeEnabled() ? [REPLTool] : []),    // ...更多条件工具  ];}

Dead Code Elimination（死代码消除）：

// Bun 的 bun:bundle 在编译时评估 feature() 调用// 如果 feature('PROACTIVE') 编译为 false:...(false ? [SleepTool] : [])// → SleepTool 的全部代码被 tree-shake 移除// 包括其引用的所有字符串和依赖

这是 Claude Code 的一个关键设计模式：编译时特性门控。外部发行版可以通过设置 feature flags 来移除整个子系统，而不需要手动删除代码。

4.3 工具池组装

function assembleToolPool(builtInTools: Tool[], mcpTools: Tool[]): Tool[] {  // 1. 过滤被 deny 规则禁止的 MCP 工具  const filteredMcp = mcpTools.filter(t => !getDenyRuleForTool(t));  // 2. 分别排序（保持 prompt cache 稳定性）  const sortedBuiltIn = sortBy(builtInTools,t => t.name);  const sortedMcp = sortBy(filteredMcp,t => t.name);  // 3. 连接：内置工具在前（作为缓存前缀）  const combined = [...sortedBuiltIn, ...sortedMcp];  // 4. 去重（内置优先）  return uniqBy(combined,t => t.name);}

Cache Stability（缓存稳定性）设计：

内置工具按名称排序后形成稳定的缓存前缀。当 MCP 工具增减时，前缀不变，Anthropic API 的 prompt cache 不会失效。这是一个微妙但重要的性能优化。

4.4 工具执行生命周期

图 4-1: 工具执行管道的 7 步流程 — 从 Zod Schema 验证到 PostToolUse Hook，每一步都可能改变工具的行为或阻止执行。

用下面的序列图理解一个工具从请求到执行的完整路径——注意 Hook 如何在关键节点介入：

下面用传统流程图展示同样的过程：

用户/模型请求工具调用    │    v┌─────────────────────────┐│ 1. validateInput()       │  结构验证（必填字段、范围）│    使用 Zod Schema       │└────────┬────────────────┘         │ 通过         v┌─────────────────────────┐│ 2. checkPermissions()    │  工具特定的权限逻辑│    返回 allow/ask/deny   │└────────┬────────────────┘         │ 未被拒绝         v┌─────────────────────────┐│ 3. Rule-Based Perms      │  设置中的 allow/deny/ask 规则│    checkRuleBasedPerms() │└────────┬────────────────┘         │ 未被拒绝         v┌─────────────────────────┐│ 4. PreToolUse Hooks      │  用户定义的 Hook│    可批准或阻止           │└────────┬────────────────┘         │ 未被阻止         v┌─────────────────────────┐│ 5. User Prompt/Classifier│  最终审批（或自动分类器）│    auto 模式：YOLO 分类器│└────────┬────────────────┘         │ 批准         v┌─────────────────────────┐│ 6. call()                │  实际执行工具│    返回 ToolResult       │└────────┬────────────────┘         │         v┌─────────────────────────┐│ 7. PostToolUse Hooks     │  执行后回调│    审计日志、通知等       │└─────────────────────────┘

4.5 工具执行管道（含 Hook 集成的真实代码）

工具执行不仅仅是调用 tool.call()——它是一个多步管道，每一步都可能改变行为：

// src/services/tools/toolExecution.ts — 真实的执行管道async function checkPermissionsAndCallTool(  tool: Tool,  toolUseID: string,  input: Record<string, unknown>,  toolUseContext: ToolUseContext,  canUseTool: CanUseToolFn,  assistantMessage: AssistantMessage,  onToolProgress: (progress: ToolProgress) => void,): Promise<MessageUpdate[]> {  // ===== 步骤 1: Zod Schema 验证 =====  const parsedInput = tool.inputSchema.safeParse(input)  if (!parsedInput.success) {    return [{ message: createUserMessage({      content: formatZodValidationError(tool.name, parsedInput.error),    }) }]  }  // ===== 步骤 2: 工具特定验证 =====  const isValidCall = await tool.validateInput?.(parsedInput.data, toolUseContext)  if (isValidCall?.result === false) {    return [{ message: createUserMessage({      content: isValidCall.message,    }) }]  }  // ===== 步骤 3: PreToolUse Hook =====  // Hook 可以：批准、阻止、修改输入、注入上下文  let processedInput = parsedInput.data  let hookPermissionResult: PermissionResult | undefined  for await (const result of runPreToolUseHooks(...)) {    switch (result.type) {      case 'hookPermissionResult':        hookPermissionResult = result.hookPermissionResult        break      case 'hookUpdatedInput':        processedInput = result.updatedInput  // Hook 修改了输入！        break    }  }  // ===== 步骤 4: 权限解析（Hook + Rules 交互）=====  // 关键设计：Hook 的 'allow' 不绕过 settings.json 的 deny/ask 规则  const { decision, input: callInput } = await resolveHookPermissionDecision(    hookPermissionResult, tool, processedInput,    toolUseContext, canUseTool, assistantMessage, toolUseID,  )  if (decision.behavior !== 'allow') {    return [/* 权限被拒绝的消息 */]  }  // ===== 步骤 5: 实际执行工具 =====  let toolResult = await tool.call(    callInput, toolUseContext, canUseTool,    assistantMessage, onToolProgress,  )  // ===== 步骤 6: PostToolUse Hook =====  // Hook 可以：修改 MCP 工具输出、注入额外上下文  for await (const result of runPostToolUseHooks(...)) {    if (result.updatedMCPToolOutput) {      toolResult = { ...toolResult, data: result.updatedMCPToolOutput }    }  }  // ===== 步骤 7: 转换为 API 格式并返回 =====  return resultingMessages}

Hook 权限决策解析（这是最微妙的部分）：

// src/services/tools/toolHooks.ts — 真实代码export async function resolveHookPermissionDecision(  hookPermissionResult, tool, input, toolUseContext,  canUseTool, assistantMessage, toolUseID,) {  if (hookPermissionResult?.behavior === 'allow') {    // Hook 说"允许"——但这不是最终判决！    // deny/ask 规则仍然适用（安全不可变量）    // 如果工具需要用户交互，且 Hook 提供了 updatedInput，    // 那么 Hook 就是"用户交互"（如 headless 包装器）    const interactionSatisfied =      tool.requiresUserInteraction?.() &&      hookPermissionResult.updatedInput !== undefined    // 即使 Hook 允许，仍检查规则    const ruleCheck = await checkRuleBasedPermissions(tool, input, toolUseContext)    if (ruleCheck?.behavior === 'deny') {      // Deny 规则覆盖 Hook 的 allow！      return { decision: ruleCheck, input }    }    if (ruleCheck?.behavior === 'ask') {      // Ask 规则仍需要对话框      return { decision: await canUseTool(...), input }    }    // 无规则阻止 → Hook 的 allow 生效    return { decision: hookPermissionResult, input }  }  // ... deny 和 ask 处理}

核心安全不变量：deny > settings rules > hook allow。即使 Hook 批准了操作，settings.json 中的 deny 规则仍然阻止它。这防止了恶意 Hook 绕过安全策略。

为什么 Hook allow 不能绕过 deny 规则？ 这是一个真实的安全考量。想象你安装了一个第三方 MCP 服务器，它提供了一个 PreToolUse Hook，对所有操作返回 allow。如果 Hook allow 能绕过 deny 规则，这个第三方代码就获得了超越你安全策略的权限——它可以让 Agent 执行你明确禁止的操作。Claude Code 的设计保证了：你在 settings.json 中写的 deny 规则是不可绕过的底线，无论有什么 Hook 介入。

4.6 FileEditTool 字符串替换算法

FileEditTool 的核心算法值得单独分析——它处理了智能引号匹配，这是一个真实的工程挑战：

// src/tools/FileEditTool/utils.ts — 真实代码// 问题：模型有时生成 "curly quotes"（智能引号）// 但文件中是 "straight quotes"（直引号），或反之const LEFT_DOUBLE_CURLY_QUOTE = '\u201C'   // "const RIGHT_DOUBLE_CURLY_QUOTE = '\u201D'  // "function normalizeQuotes(str: string): string {  return str    .replaceAll('\u2018', "'")   // ' → '    .replaceAll('\u2019', "'")   // ' → '    .replaceAll('\u201C', '"')   // " → "    .replaceAll('\u201D', '"')   // " → "}// 三阶段查找算法function findActualString(fileContent: string, searchString: string): string | null {  // 阶段 1: 精确匹配  if (fileContent.includes(searchString)) return searchString  // 阶段 2: 引号规范化匹配  const normalizedSearch = normalizeQuotes(searchString)  const normalizedFile = normalizeQuotes(fileContent)  const searchIndex = normalizedFile.indexOf(normalizedSearch)  if (searchIndex !== -1) {    // 返回文件中的 **原始** 字符串（保留原始引号风格）    return fileContent.substring(searchIndex, searchIndex + searchString.length)  }  return null}// 替换算法function applyEditToFile(  originalContent: string,  oldString: string,  newString: string,  replaceAll: boolean = false,): string {  const f = replaceAll    ? (content, search, replace) => content.replaceAll(search, () => replace)    : (content, search, replace) => content.replace(search, () => replace)  if (newString !== '') return f(originalContent, oldString, newString)  // 边界情况：删除操作  // 如果 oldString 不以换行结尾，但文件中 oldString 后面紧跟换行，  // 同时删除那个换行（防止留下空行）  const stripTrailingNewline =    !oldString.endsWith('\n') && originalContent.includes(oldString + '\n')  return stripTrailingNewline    ? f(originalContent, oldString + '\n', newString)    : f(originalContent, oldString, newString)}

设计智慧：使用 () => replace 而非直接传递 replace 字符串。这防止了替换字符串中的 $1, $& 等特殊模式被 JavaScript 的正则替换机制误解释。一个微妙但关键的防御。

4.7 定量分析：工具执行的性能特征

源码批注：关于内部 Hook 快速路径，源码注释道：“Fast-path: all hooks are internal callbacks (sessionFileAccessHooks, attributionHooks). These return {} and don’t use the abort signal… Measured: 6.01µs → ~1.8µs per PostToolUse hit (-70%).” 这个 70% 的性能提升来自跳过 span/progress/abortSignal/JSON 解析——对于每次工具调用都要触发的 PostToolUse Hook，这种微优化累积效果显著。

图 4-2: 43+ 工具的类别分布 — Core I/O（6 个）是使用频率最高的工具，Advanced（6 个）则通过 feature gate 按需加载。

图 4-3: 核心工具能力雷达图 — 展示并发安全性、只读性、破坏性等维度。FileReadTool 和 GrepTool 是”最安全”的工具（并发安全 + 只读），BashTool 是”最危险”的（可破坏 + 非只读 + 非并发安全）。

图 4-4: 工具执行延迟分布（对数刻度）— 从内部 Hook 的 2µs 到 Agent Explore 的 15 秒，延迟跨越 7 个数量级。这解释了为什么 StreamingToolExecutor 的并发优化如此重要——在多工具场景下，它将总延迟从所有工具之和降为最慢工具的时间。

4.8 工具分类

4.9 工具延迟加载（Tool Deferral）

// 并非所有工具都在第一轮加载// shouldDefer = true 的工具不发送给模型// 直到 ToolSearchTool 被调用发现它们// 例：NotebookEditTool{  name: 'NotebookEdit',  shouldDefer: true,        // 第一轮不加载  searchHint: 'jupyter notebook cell edit insert',  alwaysLoad: false,}// 例：BashTool{  name: 'Bash',  shouldDefer: false,       // 始终加载  alwaysLoad: true,         // 永不延迟}

设计哲学：

模型的工具定义占用 token 预算。43+ 个工具全部加载会消耗大量上下文空间。通过延迟加载，第一轮只加载核心工具（~15 个），其余通过 ToolSearch 按需发现。这是上下文工程的典型应用。

第五章：Permission Model — 约束架构

回想一下第一章的”驯马”比喻。到目前为止，我们的马（Agent）有了发动机（Loop）和操控系统（Tools）。但如果它能自由奔跑、随意踩踏庄稼呢？我们需要围栏——这就是权限模型。

这是 Harness Engineering 最核心的”约束”支柱。一个设计良好的权限模型不是给 Agent “加限制”——而是给 Agent “减少犯错的可能性”。Claude Code 的权限系统是业界最成熟的实现之一，它揭示了一个反直觉的真理：约束越精确，Agent 越自由。因为当你能精确控制风险时，你敢让 Agent 做更多事情。

权限模型是 Harness 的”安全阀”。它决定 Agent 能做什么、不能做什么、需要询问什么。

5.1 五种权限模式

type PermissionMode =  | 'default'            // 敏感操作始终询问  | 'acceptEdits'        // 自动批准文件编辑，其他询问  | 'bypassPermissions'  // 自动批准一切（危险）  | 'dontAsk'           // 自动拒绝需要询问的操作  | 'plan'              // 计划模式限制（只读 + 计划文件）  | 'auto'              // AI 分类器自动审批（实验性）  | 'bubble';           // 冒泡到父 Agent（子 Agent 用）

设计哲学：

模式不是二元的（允许/禁止），而是一个光谱。default 是最安全的，适合新用户；bypassPermissions 适合信任环境中的自动化；auto 是最有趣的——它使用一个两阶段 AI 分类器来判断操作是否安全。

类比：权限模式就像开车时的驾驶辅助系统。default 相当于新手模式——每次变道都要你确认。acceptEdits 相当于自适应巡航——直行自动，转弯手动。bypassPermissions 相当于完全自动驾驶——你完全信任系统。auto 最有趣——它是一个AI驾驶员在帮你开车，但它自己也有一个”安全员”（YOLO 分类器）在监督它。

5.2 三级规则系统

type PermissionRule = {  source: PermissionRuleSource;  // 规则来源  ruleBehavior: 'allow' | 'deny' | 'ask';  ruleValue: {    toolName: string;       // 例: "Bash", "Write", "mcp__server"    ruleContent?: string;   // 例: "git *", "*.ts", "prefix:npm *"  };};

规则语法示例：

# 允许所有 git 命令Bash(git *)# 允许写入 TypeScript 文件Write(*.ts)# 拒绝所有 MCP 服务器工具mcp__*# 允许读取任何文件Read# 拒绝 rm -rf 命令Bash(rm -rf *)# 允许特定 MCP 服务器的所有工具mcp__my-server(*)

5.3 纵深防御模型

图 5-1: 纵深防御六层安全模型 — 从软约束（CLAUDE.md，~95% 遵守率）到硬约束（硬编码拒绝，100% 不可绕过），层层叠加使整体绕过概率趋近于零。

在深入具体的权限规则之前，先从宏观视角理解 Claude Code 的六层安全架构。这是整个 Harness 最重要的设计模式之一：

分析：注意颜色渐变——从蓝色（软约束，可被忽略）到黄色（中等约束，可被配置覆盖）到红色（硬约束，不可绕过）。在工程实践中，第 1 层（CLAUDE.md）的遵守率约 95%——模型有时会”忘记”。但第 6 层的遵守率是 100%，因为它在代码中硬编码。这种渐变设计意味着：你不需要每一层都完美，只要层层叠加的概率足够低。如果每一层有 5% 的绕过率，6 层叠加后绕过概率是 0.05^6 ≈ 0.000000002%。

5.4 设置层级（7 级优先级）

规则来自多个来源，按优先级从高到低：

优先级最高    ↓1. CLI 参数 (cliArg)              — 命令行覆盖2. 会话命令 (command)              — /permissions 命令3. Flag 设置 (flagSettings)        — CLAUDE_CODE_FLAG_SETTINGS4. 策略设置 (policySettings)       — 组织策略5. 本地设置 (localSettings)        — .claude/settings.json.local6. 项目设置 (projectSettings)      — .claude/settings.json7. 用户设置 (userSettings)         — ~/.claude/settings.json    ↓优先级最低

加上企业管理设置：

Managed Settings（MDM/企业）:├── /managed/managed-settings.json        — 基础管理设置├── /managed/managed-settings.d/*.json    — Drop-in 覆盖└── macOS plutil / Windows Registry       — 操作系统级 MDM

设计哲学：

层级化设置允许在不修改用户设置的情况下在组织层面施加策略。企业管理员可以通过 MDM（移动设备管理）锁定某些权限，项目维护者可以在项目设置中定义合理默认值，而个人用户可以在此基础上微调。

分析：信任层级与覆盖方向

注意箭头方向是从下到上——低优先级在底部，高优先级在顶部。这不是偶然的：越接近”运行时”的设置，优先级越高。用户设置是”最远的”（编辑一次，长期使用），CLI 参数是”最近的”（每次运行都可以不同）。这种设计让你可以用 CLI 参数临时覆盖任何设置，而不用修改文件。

另一个关键设计：lockedByPolicy: true 可以让管理员锁定沙盒设置，使得用户无法禁用。源码注释提到这是*”Added to unblock NVIDIA enterprise rollout”*——一个真实的企业客户需求驱动了这个特性。

5.5 权限决策管道（真实源码）

以下是 src/utils/permissions/permissions.ts 中真实的权限管道，注释揭示了每个决策的原因：

// src/utils/permissions/permissions.ts — 真实代码async function hasPermissionsToUseToolInner(  tool: Tool, input: Record<string, unknown>, context: ToolUseContext,): Promise<PermissionDecision> {  if (context.abortController.signal.aborted) throw new AbortError()  let appState = context.getAppState()  // ===== 1a. 整个工具被 Deny =====  const denyRule = getDenyRuleForTool(appState.toolPermissionContext, tool)  if (denyRule) {    return { behavior: 'deny', decisionReason: { type: 'rule', rule: denyRule },      message: `Permission to use ${tool.name} has been denied.` }  }  // ===== 1b. 整个工具被 Ask =====  const askRule = getAskRuleForTool(appState.toolPermissionContext, tool)  if (askRule) {    // 特殊情况：沙盒自动允许    // 当 autoAllowBashIfSandboxed 开启时，沙盒化的命令跳过 ask 规则    // 不会沙盒化的命令（排除命令、dangerouslyDisableSandbox）仍遵守 ask    const canSandboxAutoAllow =      tool.name === BASH_TOOL_NAME &&      SandboxManager.isSandboxingEnabled() &&      SandboxManager.isAutoAllowBashIfSandboxedEnabled() &&      shouldUseSandbox(input)    if (!canSandboxAutoAllow) {      return { behavior: 'ask', decisionReason: { type: 'rule', rule: askRule } }    }    // 落入下方让 Bash 的 checkPermissions 处理命令级规则  }  // ===== 1c. 工具特定权限检查 =====  let toolPermissionResult: PermissionResult = { behavior: 'passthrough' }  try {    const parsedInput = tool.inputSchema.parse(input)    toolPermissionResult = await tool.checkPermissions(parsedInput, context)  } catch (e) {    if (e instanceof AbortError) throw e    logError(e)  }  // ===== 1d. 工具实现拒绝 =====  if (toolPermissionResult?.behavior === 'deny') return toolPermissionResult  // ===== 1e. 需要用户交互的工具 =====  if (tool.requiresUserInteraction?.() && toolPermissionResult?.behavior === 'ask') {    return toolPermissionResult  }  // ===== 1f. 内容级 ask 规则（重要！）=====  // 当用户配置了内容级 ask 规则如 Bash(npm publish:*)，  // tool.checkPermissions 返回 {behavior:'ask', decisionReason:{type:'rule', ruleBehavior:'ask'}}  // 这必须被尊重，即使在 bypassPermissions 模式下！  if (toolPermissionResult?.behavior === 'ask' &&      toolPermissionResult.decisionReason?.type === 'rule' &&      toolPermissionResult.decisionReason.rule.ruleBehavior === 'ask') {    return toolPermissionResult  }  // ===== 1g. 安全检查（不可绕过）=====  // .git/, .claude/, .vscode/, shell 配置等路径  // 即使 bypassPermissions 模式也必须提示  if (toolPermissionResult?.behavior === 'ask' &&      toolPermissionResult.decisionReason?.type === 'safetyCheck') {    return toolPermissionResult  }  // ===== 2a. 模式检查 =====  appState = context.getAppState()  // 重新获取最新状态  const shouldBypassPermissions =    appState.toolPermissionContext.mode === 'bypassPermissions' ||    (appState.toolPermissionContext.mode === 'plan' &&     appState.toolPermissionContext.isBypassPermissionsModeAvailable)  if (shouldBypassPermissions) {    return { behavior: 'allow', decisionReason: { type: 'mode', mode: '...' } }  }  // ===== 2b. 整个工具被 Allow =====  const allowRule = toolAlwaysAllowedRule(appState.toolPermissionContext, tool)  if (allowRule) {    return { behavior: 'allow', decisionReason: { type: 'rule', rule: allowRule } }  }  // ===== 3. passthrough → ask =====  return toolPermissionResult.behavior === 'passthrough'    ? { ...toolPermissionResult, behavior: 'ask' }    : toolPermissionResult}// ===== 外层包装：模式转换 =====export const hasPermissionsToUseTool: CanUseToolFn = async (...) => {  const result = await hasPermissionsToUseToolInner(...)  // 允许 → 重置连续拒绝计数器  if (result.behavior === 'allow') {    if (feature('TRANSCRIPT_CLASSIFIER') && context.mode === 'auto') {      persistDenialState(context, recordSuccess(currentDenialState))    }    return result  }  // ask → 模式转换  if (result.behavior === 'ask') {    if (appState.toolPermissionContext.mode === 'dontAsk') {      return { behavior: 'deny', decisionReason: { type: 'mode', mode: 'dontAsk' } }    }    // auto 模式 → AI 分类器（见 5.5 节）  }  return result}

权限决策顺序图：

                    工具调用请求                        │          ┌─────────────┼─────────────┐          │             │             │     Deny 规则?    Ask 规则?     Allow 规则?       │ 是            │ 是           │ 是       v              │             v     拒绝          沙盒可以        允许                  自动允许?                   │ 否                   v               tool.checkPermissions()                   │          ┌────────┼────────┐          │        │        │        deny     ask      allow/          │        │      passthrough          v        │        │        拒绝    内容级规则?   │                 │ 是       │                 v         │               拒绝/询问   │                           │                 安全检查?──┤                  │ 是     │                  v        │                 询问      │                           │              bypassPermissions?                  │ 是     │ 否                  v        v                允许    Allow 规则?                         │ 是  │ 否                         v     v                       允许   ask → 模式转换                              ├─ dontAsk → deny                              ├─ auto → AI 分类器                              └─ default → 用户提示

5.6 权限规则解析器（真实源码）

规则字符串的解析比看上去复杂——需要处理转义的括号：

// src/utils/permissions/permissionRuleParser.ts — 真实代码// 输入: "Bash(python -c \"print\\(1\\)\")"// 输出: { toolName: "Bash", ruleContent: "python -c \"print(1)\"" }export function permissionRuleValueFromString(ruleString: string): PermissionRuleValue {  // 找到第一个 **未转义** 的左括号  const openParenIndex = findFirstUnescapedChar(ruleString, '(')  if (openParenIndex === -1) {    return { toolName: normalizeLegacyToolName(ruleString) }  }  // 找到最后一个 **未转义** 的右括号  const closeParenIndex = findLastUnescapedChar(ruleString, ')')  if (closeParenIndex === -1 || closeParenIndex <= openParenIndex) {    return { toolName: normalizeLegacyToolName(ruleString) }  }  // 右括号必须在末尾  if (closeParenIndex !== ruleString.length - 1) {    return { toolName: normalizeLegacyToolName(ruleString) }  }  const toolName = ruleString.substring(0, openParenIndex)  const rawContent = ruleString.substring(openParenIndex + 1, closeParenIndex)  // 空内容 "Bash()" 或通配符 "Bash(*)" → 工具级规则  if (rawContent === '' || rawContent === '*') {    return { toolName: normalizeLegacyToolName(toolName) }  }  // 反转义: \\( → (, \\) → ), \\\\ → \\  const ruleContent = unescapeRuleContent(rawContent)  return { toolName: normalizeLegacyToolName(toolName), ruleContent }}// 判断字符是否被转义（前面有奇数个反斜杠）function findFirstUnescapedChar(str: string, char: string): number {  for (let i = 0; i < str.length; i++) {    if (str[i] === char) {      let backslashCount = 0      let j = i - 1      while (j >= 0 && str[j] === '\\') { backslashCount++; j-- }      if (backslashCount % 2 === 0) return i  // 偶数个反斜杠 = 未转义    }  }  return -1}

MCP 服务器级规则匹配：

// 规则 "mcp__server1" 匹配工具 "mcp__server1__tool1"// 规则 "mcp__server1__*" 匹配 server1 的所有工具function toolMatchesRule(tool, rule): boolean {  if (rule.ruleValue.ruleContent !== undefined) return false  // 内容规则不匹配整个工具  const nameForRuleMatch = getToolNameForPermissionCheck(tool)  if (rule.ruleValue.toolName === nameForRuleMatch) return true  // MCP 服务器级匹配  const ruleInfo = mcpInfoFromString(rule.ruleValue.toolName)  const toolInfo = mcpInfoFromString(nameForRuleMatch)  return ruleInfo !== null && toolInfo !== null &&    (ruleInfo.toolName === undefined || ruleInfo.toolName === '*') &&    ruleInfo.serverName === toolInfo.serverName}

图 5-2: 权限决策漏斗 — 100% 的工具调用经过逐层过滤，最终只有 ~11% 需要昂贵的分类器或用户确认。前 4 步过滤掉了 89% 的调用，全部是零成本的规则匹配。

图 5-3: 纵深防御逐层绕过概率（蓝色柱：单层概率，红色线：累积概率，对数刻度）— 6 层叠加后，累积绕过概率趋近于零。注意第 6 层（硬编码拒绝）的单层概率为 0，使累积概率归零。

图 5-4: 权限决策矩阵热力图 — 5 种权限模式 × 6 种工具类型的决策结果。绿色=ALLOW，橙色=ASK，红色=DENY。注意 auto 模式下 Bash(danger) 仍为 ASK——分类器对高风险操作采取保守策略。

5.7 定量分析：权限决策的分布

基于 Claude Code 源码中的 analytics 埋点和注释，我们可以推断权限决策的典型分布：

源码批注：关于分类器的优化，源码注释道：“Before running the auto mode classifier, check if acceptEdits mode would allow this action. This avoids expensive classifier API calls for safe operations like file edits.” 这个快速路径检查估计跳过了 ~35% 的分类器调用。另一段注释提到：“Allowlisted tools are safe and don’t need YOLO classification.” 这进一步跳过 ~15%。两者叠加意味着只有约 11% 的工具调用真正需要分类器 API 调用。

性能启示：权限检查的平均延迟约 5-10ms（加权平均），但方差极大。Rule-based 路径几乎无延迟，而分类器路径可能需要 2 秒。这就是为什么 Claude Code 在 toolExecution.ts 中实现了推测性预取——在 PreToolUse Hook 运行的同时，并行启动 Bash 分类器检查。源码注释道：“Speculatively start the bash allow classifier check early so it runs in parallel with pre-tool hooks.”

5.8 YOLO 分类器（Auto 模式）

auto 模式使用一个两阶段 AI 分类器来自动审批工具调用：

阶段 1: Fast 分类器├─ 使用较小/快速模型├─ 检查：这个操作安全吗？├─ 返回 confidence: high/medium/low├─ 如果 high confidence + shouldBlock=false → 直接批准└─ 如果不确定 → 进入阶段 2阶段 2: Thinking 分类器├─ 使用更大/更深思考的模型├─ 分析完整上下文（对话历史 + 工具输入）├─ 返回最终判断└─ 如果仍不确定 → 降级为用户询问安全工具快速路径:├─ Read, Glob, Grep 等只读工具├─ 跳过 API 调用（节省延迟和成本）└─ 直接返回 allow连续拒绝跟踪:├─ 如果分类器连续拒绝多次├─ 回退到用户提示└─ 防止分类器过度保守时卡住

设计哲学：

YOLO 分类器体现了 Harness 工程的核心理念——不信任模型自己判断操作是否安全。即使主模型认为操作是正确的，一个独立的”看门人”模型会进行二次审查。两阶段设计在速度和安全性之间取得平衡。

5.6 权限决策理由追踪

每个权限决策都附带详细的理由，用于审计和调试：

type PermissionDecisionReason =  | { type: 'rule'; rule: PermissionRule }  | { type: 'mode'; mode: PermissionMode }  | { type: 'classifier'; classifier: string; reason: string }  | { type: 'hook'; hookName: string; reason?: string }  | { type: 'safetyCheck'; reason: string; classifierApprovable: boolean }  // ... 更多变体

第六章：Hooks System — 生命周期可扩展性

权限模型告诉 Agent “能不能做”，而 Hooks 让你在 Agent “做之前”和”做之后”插入自己的逻辑。

你可以把 Hooks 想象成机场的安检通道。旅客（工具调用）要通过安检（PreToolUse Hook），通过后可能被贴上标签（PostToolUse Hook），如果行李有问题会被拦下（blocking error）。安检人员可以是人工的（command Hook），也可以是 AI 的（agent Hook），甚至可以是远程的（http Hook）。

Claude Code 定义了 26 种 Hook 事件和 4 种 Hook 类型——这是目前开源可见的最完整的 Agent 生命周期扩展系统。理解它，你就掌握了让 Harness “可定制”的关键。

Hooks 是 Harness 的扩展点。它们允许用户在 Agent 生命周期的关键时刻注入自定义逻辑。

6.1 26 个 Hook 事件

// src/types/hooks.ts — 完整的 Hook 事件列表type HookEvent =  // 工具相关  | 'PreToolUse'        // 工具执行前  | 'PostToolUse'       // 工具执行后  | 'PostToolUseFailure'// 工具执行失败后  // 权限  | 'PermissionRequest' // 权限请求  | 'PermissionDenied'  // 权限被拒绝  // 会话  | 'SessionStart'      // 会话开始  | 'SessionEnd'        // 会话结束  | 'Stop'              // 模型停止  | 'StopFailure'       // 停止失败  // 用户输入  | 'UserPromptSubmit'  // 用户提交提示  // Agent  | 'SubagentStart'     // 子 Agent 启动  | 'SubagentStop'      // 子 Agent 停止  | 'TeammateIdle'      // 队友空闲  // 任务  | 'TaskCreated'       // 任务创建  | 'TaskCompleted'     // 任务完成  // 压缩  | 'PreCompact'        // 压缩前  | 'PostCompact'       // 压缩后  // 其他  | 'Setup'             // 初始设置  | 'Notification'      // 通知  | 'Elicitation'       // 信息请求  | 'ElicitationResult' // 信息请求结果  | 'ConfigChange'      // 配置变更  | 'CwdChanged'        // 工作目录变更  | 'FileChanged'       // 文件变更  | 'WorktreeCreate'    // Worktree 创建  | 'WorktreeRemove'    // Worktree 移除  | 'InstructionsLoaded'; // 指令加载完成

图 6-1: 26 个 Hook 事件的触发频率估计 — PreToolUse 和 PostToolUse 是最频繁的事件（每次工具调用都触发），SessionStart/End 只在会话边界触发。这解释了为什么 PostToolUse 的内部 Hook 有专门的快速路径优化（-70% 延迟）。

图 6-2: Hook 类型的成本-智能度散点图 — Command Hook 在左下角（便宜但简单），Agent Hook 在右上角（昂贵但智能）。虚线分隔四个象限：左上是”理想区域”（智能且便宜），右下是”避免区域”（愚蠢且昂贵）。

6.2 Hook 生命周期与类型选择

选择正确的 Hook 类型是 Harness 定制的关键决策。下图帮助你根据场景选择：

解读：左下角是 Command Hook 的领地——简单、便宜、确定性强（如 lint、grep 检查）。右上角是 Agent Hook——最聪明但最贵（需要完整的 Claude 调用来理解代码语义）。HTTP Hook 在右下——成本中等（网络延迟），但智能低（只是 POST 数据）。Prompt Hook 在中间偏上——单次 LLM 判断，比 Agent 便宜但比脚本聪明。

四种 Hook 类型

类型 1: Command Hook（Shell 命令）

{  "type": "command",  "command": "npm test -- --bail",  "if": "Bash(npm *)",  "shell": "bash",  "timeout": 30,  "statusMessage": "Running tests...",  "once":false,  "async":false,  "asyncRewake":false}

执行流程：

1. 1. 路径转换（Windows: C:\Users\foo → /c/Users/foo）
2. 2. 变量替换（${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT}）
3. 3. Shell 选择（Bash 或 PowerShell）
4. 4. JSON 输入写入 stdin
5. 5. 逐行解析 stdout（检测异步信号和 prompt 请求）
6. 6. 退出码判断结果

退出码语义：

• • 0: 成功，stdout 内容可选展示
• • 2: 阻止性错误，stderr 展示给模型和用户
• • 其他: 非阻止性错误，stderr 仅展示给用户

类型 2: Prompt Hook（LLM 评估）

{  "type": "prompt",  "prompt": "Review this code change for security vulnerabilities: $ARGUMENTS",  "model": "claude-sonnet-4-6",  "timeout": 60}

使用一个独立的 LLM 调用来评估 Hook 输入。适合需要语义理解的检查（如代码安全审查）。

类型 3: HTTP Hook（外部服务）

{  "type": "http",  "url": "https://hooks.slack.com/triggers/...",  "headers": {    "Authorization": "Bearer $SLACK_TOKEN"  },  "allowedEnvVars": ["SLACK_TOKEN"],  "timeout": 10}

POST JSON 到外部 URL。headers 中的 $VAR_NAME 语法从白名单环境变量插值。allowedEnvVars 限制可访问的环境变量，防止意外泄露。

类型 4: Agent Hook（Agent 验证器）

{  "type": "agent",  "prompt": "Verify that the test suite passes and no regressions were introduced",  "model": "claude-sonnet-4-6",  "timeout": 120}

使用一个完整的 Claude Agent（带工具访问）来验证操作。成本最高但最强大——Agent 可以读取文件、运行测试、检查结果。

6.3 Hook 配置结构

// ~/.claude/settings.json{  "hooks": {    "PreToolUse": [      {        "matcher": "Write",        "hooks": [          {            "type": "command",            "command": "eslint --stdin --stdin-filename=$TOOL_INPUT_FILE_PATH",            "if": "Write(*.ts)"          }        ]      },      {        "matcher": "Bash",        "hooks": [          {            "type": "command",            "command": "echo '{\"decision\": \"block\", \"reason\": \"sudo is not allowed\"}' ",            "if": "Bash(sudo *)"          }        ]      }    ],    "PostToolUse": [      {        "hooks": [          {            "type": "http",            "url": "https://audit.company.com/log",            "headers": { "Authorization": "Bearer $AUDIT_TOKEN" },            "allowedEnvVars": ["AUDIT_TOKEN"]          }        ]      }    ],    "SessionEnd": [      {        "hooks": [          {            "type": "command",            "command": "git stash",            "timeout": 10          }        ]      }    ]  }}

6.4 Hook 输入/输出协议

输入（通过 stdin 传递的 JSON）：

// 所有 Hook 的基础字段{  session_id: string,  transcript_path: string,  cwd: string,  permission_mode?: string,  agent_id?: string,  agent_type?: string,}// PreToolUse 特有字段{  tool_name: "Write",  tool_input: { file_path: "/src/index.ts", content: "..." },  tool_use_id: "toolu_xxx",}// PostToolUse 特有字段{  tool_name: "Bash",  tool_input: { command: "npm test" },  tool_response: { stdout: "...", exit_code: 0 },  tool_use_id: "toolu_xxx",}// UserPromptSubmit{  prompt_text: "Fix the bug in login.ts",}// SessionStart{  source: "startup" | "resume" | "clear" | "compact",}

输出（stdout 返回的 JSON）：

type HookJSONOutput = {  // 全局控制  continue?: boolean;           // false = 停止对话  stopReason?: string;  decision?: 'approve' | 'block';  reason?: string;  systemMessage?: string;       // 注入系统消息  suppressOutput?: boolean;  // 权限相关  permissionDecision?: 'allow' | 'deny' | 'ask';  // 事件特定  hookSpecificOutput?: {    updatedInput?: object;           // 修改工具输入（PreToolUse）    additionalContext?: string;       // 注入额外上下文    watchPaths?: string[];           // 注册文件监视器    updatedMCPToolOutput?: unknown;  // 修改 MCP 工具输出    action?: 'accept' | 'decline' | 'cancel';  }};