第 1 章：Claude Code 概述

1.1 Claude Code 解决什么问题

Claude Code 不是一个简单的"CLI 调用大模型"工具。它是 Anthropic 官方推出的 受控工具循环 Agent（Controlled Tool-Loop Agent），专为真实软件工程任务设计。

从工具到 Agent：三级范式

要理解 Claude Code 的定位，我们需要先理解 AI 辅助编程的三级范式：

第一级：代码补全（如 Copilot）。模型的工作是"预测下一行代码"。它看到你的光标位置和上下文，生成一个补全建议。这本质上是一个单次预测问题——模型不需要理解整个项目，不需要执行任何操作，只需要根据局部上下文生成合理的代码片段。用户始终是驾驶员，模型只是副驾。

第二级：IDE 聊天助手（如 Cursor Chat、Copilot Chat）。用户可以用自然语言描述需求，模型生成代码片段或修改建议。这比补全强大——模型可以看到更多上下文，可以生成多个文件的修改。但关键限制是：模型不能执行操作。它生成一个 diff，由用户决定是否 apply。如果 diff 有问题（比如依赖了一个不存在的函数），用户需要手动发现并反馈，模型无法自行验证。

第三级：自主 Agent（Claude Code）。模型不仅生成代码，还能自主执行多步操作。考虑一个真实场景：你想给项目添加一个新的 REST endpoint。Copilot 会给你一个函数体。IDE 聊天可能会建议一个修改方案。而 Claude Code 的做法是：先用 Grep 搜索现有路由定义理解项目的路由模式，用 FileRead 读取中间件配置，然后创建 handler 文件、注册路由、编写测试，接着运行 npm test 发现测试失败，读取错误信息，修复代码，再次运行测试直到通过，最后提交 git commit。整个过程是一个自主决策循环——模型决定下一步做什么，执行后观察结果，再决定下一步。

这种范式跃迁带来了根本性的架构差异。一个 Agent 需要：

• 循环（Loop）：不是单次调用，而是反复 "思考→执行→观察" 直到任务完成
• 工具（Tools）：不是只生成文本，而是能读文件、写文件、执行命令
• 记忆（Memory）：不是每次从零开始，而是记住用户偏好和项目上下文
• 安全控制（Safety）：因为它在用户机器上执行真实操作，所以需要严格的权限管理

Claude Code 的每一个架构决策都围绕这四个需求展开。

与其他 Agent 的区别

市面上不乏其他编程 Agent（如 AutoGPT、OpenDevin、Aider 等），但 Claude Code 有一个独特优势：它由构建 Claude 模型的同一个团队开发。这意味着系统提示词、工具描述、错误处理策略都与模型的行为特性共同设计和调优。例如，Claude Code 的 system prompt 不是一个通用的 "你是一个编程助手"——它包含了针对 Claude 模型特性优化的详细行为指令，工具的 description 字段也经过反复调优以匹配模型的理解模式。

此外，Claude Code 在生产级工程质量上远超大多数开源 Agent 项目：5 层纵深防御的安全系统、4 级渐进式上下文压缩、7 种错误恢复策略、流式工具预执行——这些不是学术 demo，而是服务真实用户的工业级实现。

"Agent-first" 的架构含义

"Agent-first" 不是营销口号——它有具体的架构含义：模型是循环中的决策者，而非人类。人类设定目标（"给这个项目添加用户认证"）并审批危险操作（"确认执行 npm install？"），但在两次人类交互之间，模型自主决定读什么文件、改什么代码、执行什么命令。

这体现在源码中最核心的一行——src/query.ts:307 的 while (true)：

// src/query.ts:307
while (true) {
    // ... 压缩 → API 调用 → 工具执行 → 继续/退出
}

这个循环只有当模型的响应不包含任何工具调用时才会退出。换句话说，是模型——而不是代码逻辑——决定任务是否完成。代码只是提供了执行环境，真正的"大脑"是模型本身。

1.2 技术栈

技术选型本身不是本文重点，但有两个选择值得一提，因为它们深刻影响了架构设计：

• Bun 的 feature() 宏：Claude Code 内部有大量功能（协调器模式、Swarm 团队等）在外部发布版本中需要完全移除。Bun 提供的编译时 Feature Flag 让这些代码在构建时被物理删除，而非运行时隐藏。这在后续"编译时 Feature Gate"设计原则中会详细展开。
• 自研 React 终端渲染器：Claude Code 的终端 UI 复杂度远超普通 CLI——权限确认对话框、流式代码高亮、嵌套工具进度指示器都需要组件化的状态管理。团队维护了一个 251KB 的定制 Ink 渲染器（而非使用上游库），详见 第 11 章：用户体验设计。

1.3 核心设计原则

Claude Code 的架构遵循 6 条核心设计原则：

1. Generator-based 流式架构

从 API 调用到 UI 渲染，全链路使用 async function* 异步生成器。这不是简单的 callback 或 Promise 链——而是真正的流式处理管道，每个 Token、每个工具结果都能实时流向用户界面。

核心查询循环的签名是：

// src/query.ts
export async function* query(
  params: QueryParams,
): AsyncGenerator<StreamEvent | Message | ToolUseSummaryMessage, Terminal>

这是一个异步生成器——它不是一次性返回结果，而是边执行边 yield 事件。调用方（QueryEngine）通过 for await (const msg of query(params)) 实时消费每一个事件：模型输出的每个 Token、每个工具调用的结果、压缩事件、错误恢复——所有这些都通过同一个 generator 管道流向 UI 层。

这种设计的好处是零缓冲延迟：用户在模型开始生成的瞬间就能看到输出，而不需要等待整个响应完成。

为什么是 Generator 而不是 Callback 或 Promise？ 这个选择不是随意的——三种异步模式各有根本性的局限：

• Callback 模式：经典 Node.js 风格，容易陷入 "callback hell"，更重要的是无法优雅地传递 backpressure（当 UI 渲染跟不上数据产生速度时，没有自然的暂停机制）。当用户按 Ctrl+C 中断时，需要手动在每一层 callback 中接线取消逻辑。
• Promise/async-await 模式：解决了 callback hell，但 await 是阻塞式的——一个 await apiCall() 必须等到整个响应完成才能返回。要实现流式，你需要手动缓冲部分结果并轮询，这本质上是在 Promise 之上重新发明 generator。
• Generator 模式：yield 天然就是流式语义——生产者（API 层）产出一个 token 就 yield 一次，消费者（UI 层）按自己的节奏拉取。更关键的是，generator.return() 可以级联清理整个调用链：用户按 Ctrl+C → REPL 调用 generator.return() → QueryEngine 的 generator 终止 → query() 的 generator 终止 → API 请求被 abort。不需要手动接线，cleanup 沿着 generator 链自动传播。

注意 query() 的返回类型 AsyncGenerator<..., Terminal>——Terminal 是 generator 的 return type，代表查询的最终状态，与 yield 出的中间事件流是分离的。这种"双通道"（yield 流式事件 + return 最终结果）只有 generator 能干净地表达。

整个数据流形成了一个嵌套的 generator 管道：REPL.tsx → QueryEngine.submitMessage() → query() → queryModelWithStreaming()（services/api/claude.ts）。每一层 generator 在管道上叠加自己的处理逻辑（压缩、错误恢复、权限检查），但对上层来说，它只是一个统一的 AsyncGenerator 事件流。

2. 防御性分层安全

权限系统采用多层防御：

权限规则匹配 (src/hooks/toolPermission/)
    ↓ 通过
Bash AST 分析 (src/utils/bash/, tree-sitter 解析)
    ↓ 通过
23 项静态安全验证器
    ↓ 通过
ML 分类器 (yoloClassifier)
    ↓ 通过
用户确认对话框

为什么需要这么多层？ 理解威胁模型是关键：Claude Code 在用户的真实机器上执行任意代码。模型不是完美的——它可能因为上下文混淆而生成错误命令，可能被恶意 README 中的 prompt injection 误导，或者只是单纯犯了一个逻辑错误。一条 rm -rf ~ 就足以造成不可挽回的损失。

这是经典的纵深防御：即使某一层有 bug 或被绕过，其他层仍然可以阻止危险操作。每一层使用不同的技术手段，覆盖不同类别的风险：

1. 权限规则匹配（src/hooks/toolPermission/）：这是策略层——用户通过 CLAUDE.md 的 allowedTools 或 --allowedTools 标志声明哪些操作是被允许的。这一层表达的是用户意图："在这个项目中，运行 npm test 总是安全的"。
2. Bash AST 分析（src/utils/bash/, tree-sitter）：不是用正则匹配命令字符串，而是用 tree-sitter 将 Bash 命令解析为抽象语法树。为什么不用正则？因为 Bash 语法极其灵活——r"m" -rf /、$(echo rm) -rf /、eval "rm -rf /" 这些变形都能绕过简单的字符串匹配，但 AST 分析能识别出实际执行的命令。
3. 23 项静态安全验证器：硬编码的已知危险模式检查。这是"白名单/黑名单"层——某些操作（如写入 /etc/passwd、修改 SSH 配置）无论上下文如何都应该被拦截。
4. ML 分类器（yoloClassifier）：一个经过训练的分类模型，能根据命令的语义上下文判断安全性。它捕获的是静态规则覆盖不到的"新型"危险模式——比如一条看起来无害但在当前上下文中可能造成问题的命令。
5. 用户确认对话框：最终的人类审核。即使所有自动化层都放行了，用户仍然可以看到即将执行的操作并选择拒绝。

关键设计洞察：各层使用完全不同的技术（规则匹配、语法解析、机器学习、人类判断），这意味着单一类别的 bug 无法同时绕过所有层。即使权限规则配置错误地放行了一条命令，tree-sitter AST 分析仍然会检测到 rm -rf / 这样的结构性危险模式。

3. 编译时 Feature Gate

通过 Bun bundler 的 feature() 宏实现编译时死代码消除。内部功能（如协调器模式）在外部构建中完全移除——不是运行时隐藏，而是编译时物理删除。

这个模式在整个代码库中反复出现：

// src/query.ts 开头 — 4 个 Feature Gate
const reactiveCompact = feature('REACTIVE_COMPACT')
  ? (require('./services/compact/reactiveCompact.js') as typeof import('./services/compact/reactiveCompact.js'))
  : null
const contextCollapse = feature('CONTEXT_COLLAPSE')
  ? (require('./services/contextCollapse/index.js') as typeof import('./services/contextCollapse/index.js'))
  : null
const snipModule = feature('HISTORY_SNIP')
  ? (require('./services/compact/snipCompact.js') as typeof import('./services/compact/snipCompact.js'))
  : null
const skillPrefetch = feature('EXPERIMENTAL_SKILL_SEARCH')
  ? (require('./services/skillSearch/prefetch.js') as typeof import('./services/skillSearch/prefetch.js'))
  : null

as typeof import(...) 类型断言让 TypeScript 在编译期获得正确的类型信息，而 feature() 在 Bun bundler 构建时被求值——如果结果为 false，整个 require() 分支和相关代码都被 tree-shaken 移除。使用这些模块的代码总是先检查 if (contextCollapse) { ... }，这个条件判断本身也在编译时被消除。

4. 状态集中 + 不可变更新

全局状态集中于 bootstrap/state.ts（1,758 行，150+ 访问器）。为什么不直接用全局变量？

在一个拥有 66+ 工具、多个子 Agent、压缩管道和 React UI 的系统中，共享状态是不可避免的——当前使用的模型名、会话 ID、Feature Flag 缓存、累计成本、文件修改状态等，这些信息需要被多个子系统同时访问和修改。朴素的全局变量方案会带来三个实际问题：

1. import 循环：模块 A 导入 B 的状态，B 导入 C 的工具，C 又导入 A 的状态——在一个 1,900 文件的项目中，这种循环几乎不可避免
2. 不可追踪的修改：当某个 bug 导致模型名被意外改变，你无法设断点查看"是谁在什么时候改了这个值"
3. React 渲染问题：直接修改全局对象的属性不会触发 React 组件的重新渲染

bootstrap/state.ts 的解决方案是通过显式的 getter/setter 函数暴露状态（如 getSessionId()、getTotalCost()、setCurrentModel()），而不是导出可变对象。每个模块只导入自己需要的 getter/setter 函数，从而打破 import 循环；每次修改都经过函数调用，可以轻松添加日志或断点追踪。

UI 状态使用 Zustand 模式的不可变更新——setAppState(prev => ({ ...prev, newField: value }))——保证 React 组件能正确感知状态变化。

值得注意的是，这不是一个"理想"的架构——团队自己也在控制全局状态的增长。但在 Claude Code 这样的复杂系统中，集中管理的 getter/setter 是一个务实的平衡：比全局变量安全，比完整的状态管理框架（如 Redux）轻量。

5. 渐进式压缩

Snip → Microcompact → Context Collapse → Autocompact 四级压缩流水线，确保对话永不因上下文溢出而中断。四级压缩按成本从低到高排列，每级解决不同粒度的问题：

1. Snip（零 API 成本）：移除对话历史中已经不再被引用的旧工具结果。例如，10 轮前的一次 grep 搜索结果可能有 50KB，但模型早已不再关注它。Snip 用一个占位符替换这些内容，纯本地操作，不需要调用 API。（query.ts:401-410）
2. Microcompact（近零成本）：压缩单个工具结果的体积。比如一个 Grep 工具返回了 200 行匹配结果，Microcompact 可以将其截断为最相关的前 20 行。同样是本地启发式操作。（query.ts:414-426）
3. Context Collapse（中等成本）：将相关的消息序列分组折叠为摘要。关键设计：这是一个读时投影——原始完整历史保留在内存中，发送给 API 的是折叠后的视图。这意味着折叠是可逆的，不会丢失原始信息。（query.ts:440-447）
4. Autocompact（全量成本）：fork 一个子 Agent 生成整个对话的摘要，用摘要替换原始历史。这是"核选项"——释放最多空间，但不可逆地丢失对话细节。（query.ts:454-467）

为什么四级而非只用 Autocompact？ 如果只有 Autocompact，每次上下文接近满就必须调用 API 生成摘要——既有延迟成本（用户等待），又有质量成本（细节丢失）。通过先执行零成本的 Snip 和 Microcompact，系统往往能释放足够的空间避免触发昂贵的 Autocompact。实践中，很多对话自始至终都不需要走到 Autocompact 这一步。

详见 第 3 章：上下文工程。

6. 工具即扩展点

所有能力——文件操作、搜索、Agent 派生、MCP 桥接——统一为 Tool 接口（src/Tool.ts）。无论是内置的 BashTool、通过 MCP 协议接入的外部工具，还是插件系统注册的第三方工具，它们共享完全相同的执行管道：权限检查 → 输入校验 → 执行 → 结果格式化 → UI 渲染。

Tool 接口（src/Tool.ts）拥有约 20 个字段和方法，每一个都在统一管道中扮演角色：

• isReadOnly()：告诉权限系统这个工具是否只读——只读工具（如 Grep、Glob）可以跳过用户确认
• isConcurrencySafe()：告诉 StreamingToolExecutor 这个工具能否与其他工具并行执行——Grep 可以，但 FileEdit 不行（可能产生写冲突）
• shouldDefer：告诉 API 层是否延迟发送完整 schema——66+ 个工具的 schema 加起来占用大量 token，不常用的工具可以按需加载
• inputSchema（Zod）：模型生成的参数在执行前必须通过 Schema 验证，防止畸形输入触达工具执行层
• interruptBehavior()：定义用户中断时工具的行为——有些工具可以立即中断，有些需要清理

findToolByName() 函数不区分工具来源——对 query 循环来说，所有工具都是平等的 Tool 对象。这意味着一个通过 MCP 协议接入的外部 Kubernetes 工具，和内置的 BashTool 经历完全相同的权限检查、输入验证、结果格式化流程。扩展 Claude Code 的能力就是实现一个符合 Tool 接口的对象，而不需要修改核心循环——这是经典的开闭原则（Open-Closed Principle）在 Agent 架构中的体现。

1.4 源码目录结构

Claude Code 源码约 1,900 文件、512K+ 行 TypeScript，目录结构如下：

src/
├── main.tsx                 # CLI 主入口（4,683 行）
│                            # Commander.js 解析参数，分发到 REPL/headless/SDK 模式
├── QueryEngine.ts           # 会话引擎（1,155 行）
│                            # 管理对话全生命周期：消息持久化、预算追踪、结果组装
├── query.ts                 # 核心查询循环（1,728 行）
│                            # 单次查询的状态机：压缩→API调用→工具执行→恢复/继续
├── Tool.ts                  # 工具接口定义
│                            # 所有工具（内置/MCP/插件）的统一类型约束
├── tools.ts                 # 工具注册与组装
├── context.ts               # 上下文构建（190 行）
│                            # getSystemContext/getUserContext：Git状态、CLAUDE.md、日期
│
├── bootstrap/               # 全局状态管理
│   └── state.ts             # 集中式状态存储（1,758 行，150+ getter/setter）
│                            # 所有子系统通过访问器读写共享状态，避免 import 循环
│
├── entrypoints/             # 入口点
│   ├── init.ts              # 核心初始化（341 行）：14 步幂等初始化
│   ├── cli.tsx              # 快速路径（--version, MCP server, bridge）
│   └── sdk/                 # SDK 入口与类型
│
├── screens/                 # 主要界面
│   ├── REPL.tsx             # 主对话 UI（895KB）：消息渲染、输入处理、状态管理
│   ├── Doctor.tsx           # 诊断界面
│   └── ResumeConversation.tsx
│
├── tools/                   # 66+ 内置工具
│   ├── BashTool/            # Shell 命令执行（含 AST 安全分析）
│   ├── AgentTool/           # 子 Agent 派生（支持 worktree 隔离）
│   ├── FileReadTool/        # 文件读取（支持图片、PDF、Notebook）
│   ├── FileEditTool/        # 文件编辑（search-and-replace 策略）
│   ├── GrepTool/            # 内容搜索（基于 ripgrep）
│   ├── GlobTool/            # 文件匹配
│   ├── WebFetchTool/        # 网页获取
│   ├── SkillTool/           # 技能调用
│   └── ...                  # 更多工具
│
├── services/
│   ├── api/                 # API 客户端层
│   │   ├── claude.ts        # 核心查询逻辑（3,419 行）
│   │   │                    # HTTP→Claude API 的桥梁：prompt 构建、缓存控制、
│   │   │                    # thinking 配置、task budget 注入、流式响应解析
│   │   ├── withRetry.ts     # 重试策略（指数退避 + 模型降级）
│   │   └── promptCacheBreakDetection.ts  # 缓存断裂检测与自动归因
│   ├── compact/             # 压缩系统
│   │   ├── autoCompact.ts   # 自动压缩触发（阈值计算、条件判断）
│   │   └── compact.ts       # 摘要生成引擎（1,705 行）
│   │                        # fork 子 Agent 生成对话摘要，压缩后恢复最近文件和技能
│   ├── mcp/                 # MCP 协议集成（7 种传输）
│   ├── oauth/               # OAuth 2.0 + PKCE
│   ├── plugins/             # 插件系统
│   └── lsp/                 # 语言服务器协议
│
├── hooks/                   # 权限与 Hook 处理
│   └── toolPermission/      # 工具权限判定
│       └── handlers/        # 3 种权限处理器：规则匹配、Hook、用户确认
│
├── coordinator/             # 多 Agent 协调器（内部功能，Feature-gated）
├── memdir/                  # 记忆系统（~/.claude/memory/ 管理）
├── skills/                  # 技能系统（18+ 内置技能）
├── ink/                     # 自定义终端渲染器（251KB 核心，React→终端输出）
├── vim/                     # Vim 模式
├── schemas/                 # Zod Schema 定义
└── utils/                   # 通用工具库
    ├── hooks.ts             # Hook 执行引擎
    ├── bash/                # Bash AST 解析（tree-sitter）
    ├── messages.ts          # 消息处理（5,512 行）：规范化、压缩边界、格式转换
    └── tokens.ts            # Token 估算与追踪

1.5 数据流全景

理解 Claude Code 的关键是理解数据如何在各层之间流动。下面是一次完整的用户交互的数据流：

让我们沿着数据流逐步展开，理解每个阶段发生了什么：

Step 1：用户输入进入 REPL。React 组件 REPL.tsx 捕获用户的文本输入。如果是斜杠命令（如 /clear、/compact），在本地直接处理，永远不会发送到 API。普通消息则传递给 QueryEngine.submitMessage()。

Step 2：QueryEngine 准备查询。processUserInput() 处理消息中的附件（图片缩放、文件引用解析），构建包含消息历史、系统提示词、工具列表和权限上下文的 QueryParams 对象，然后调用 query() 启动核心循环。

Step 3：4 级压缩管道运行。注意——压缩不是只在对话开始时运行一次，而是在每次 API 调用之前都会运行。循环的每一轮迭代都会依次检查 Snip → Microcompact → Context Collapse → Autocompact，按需触发。大多数迭代中没有任何压缩触发（上下文还没满），但当历史消息累积到接近上下文窗口上限时，压缩管道会自动介入。

Step 4：API 调用。系统提示词、压缩后的消息历史和工具 schema 被发送到 Claude API（通过 services/api/claude.ts 的 queryModelWithStreaming()）。响应以 token-by-token 的方式流式返回，每个 token 被 yield 为 StreamEvent 沿着 generator 链向上传递到 UI，用户立即看到文字出现。

Step 5：工具在流式过程中即开始执行。这是 Claude Code 的一个重要性能优化：StreamingToolExecutor 不等待模型的完整响应。当流式解析器检测到一个 tool_use JSON block 已经完整，工具执行立即开始——此时模型可能还在继续生成后面的文字或其他工具调用。只读且并发安全的工具（如 Grep、Glob）甚至可以并行执行，进一步缩短多工具调用的总耗时。

Step 6：结果注入，循环继续。工具的执行结果被封装为 tool_result 消息追加到对话历史中。循环回到 Step 3——再次检查是否需要压缩，再次调用 API。模型看到工具结果后决定下一步：继续调用更多工具，或者生成最终的文字回复。

Step 7：循环退出，结果组装。当模型的响应中不包含任何 tool_use block 时，query() 返回一个 Terminal 值。QueryEngine 组装最终结果，持久化对话历史，更新 usage/cost 追踪。

关于性能：流式工具预执行

Step 5 中的"流式工具预执行"值得单独强调。在朴素的实现中，流程是串行的：等待模型完整响应 → 解析工具调用 → 顺序执行工具 → 发送结果。Claude Code 的流程是重叠的：模型还在生成文字的同时，已解析完成的工具调用已经在执行。对于一次包含 3-4 个工具调用的响应，这种重叠可以显著减少端到端延迟。

关于错误恢复

数据流中隐藏着多层错误恢复机制：

• API 错误（429 限速、529 服务过载）：withRetry 层自动进行指数退避重试，严重情况下可以降级到备选模型
• 上下文过长（prompt_too_long）：触发 reactive compact——紧急执行一轮压缩然后重试 API 调用
• 工具执行失败：错误信息被包装为 tool_result（标记 is_error: true）返回给模型，模型可以自行决定是重试还是换一种方法。yieldMissingToolResultBlocks()（query.ts:123）确保每个 tool_use 都有对应的 tool_result，即使在中断场景下也不会出现消息配对缺失

关键洞察：数据通过嵌套的 async generator 流动。每一层都在 generator 管道上添加自己的处理逻辑（权限检查、压缩、错误恢复），但对上层来说，它只是一个统一的事件流。这使得关注点完全分离——QueryEngine 不需要知道压缩细节，REPL 不需要知道错误恢复逻辑。

1.6 启动流程

Claude Code 的启动经过精心优化，将大量工作并行化和延迟化。整个流程分为 9 个阶段，关键路径仅约 235ms：

为什么分 9 个阶段？

这个设计的核心目标是最小化用户感知的启动时间。用户关心的是"输入 claude 后多快看到输入提示符"，而不是所有初始化都完成了。所以：

• Phase 1-2 并行预取：MDM（移动设备管理）策略读取和 Keychain 凭证预取在模块加载的同时就并行启动，而不是等加载完成后串行执行
• Phase 6 幂等初始化：init() 函数是 memoized 的，重复调用无副作用。这让多个代码路径都可以安全地调用 await init() 而不用担心重复初始化
• Phase 8 延迟非关键任务：用户信息查询、文件计数统计、模型能力检测——这些对首次交互不重要的操作被推迟到首帧渲染之后
• Phase 9 懒加载重依赖：OpenTelemetry（~400KB+）在用户完成 Trust Dialog 之后才加载，避免拖慢启动速度

1.7 架构总览

这张图看起来像一个普通的分层架构，但每一层的设计决策都值得理解：

入口层（main.tsx）：CLI 入口处理三种截然不同的运行模式——REPL（交互式终端）、Print 模式（-p 标志，单次查询后退出）和 SDK/Bridge 模式（供第三方程序调用）。关键设计是：三种模式全部汇聚到同一个 QueryEngine。这意味着核心 Agent 循环是模式无关的——无论 Claude Code 是被人类交互使用、被 CI 脚本以 -p 调用、还是被 IDE 插件通过 SDK 集成，底层执行的都是同一个 query() 函数。这对测试也很有价值：Print 模式本质上就是一个无头测试工具。

会话层（QueryEngine）：管理一次对话的完整生命周期——消息持久化（每次交互自动保存）、成本追踪（累计 token 和美元开销）、预算执行（task budget 限额）、结构化输出重试。它是"用户交互"和"Agent 执行"之间的边界。当一条新消息到达时，QueryEngine 判断它是斜杠命令、文件附件还是普通 prompt，做相应的预处理后才转交给核心循环。

核心循环（query）：这是 Claude Code 的心脏。一个 while(true) 循环反复执行：压缩上下文 → 调用 API → 执行工具 → 判断是否继续。循环携带可变的 State 对象（query.ts:204），包括消息历史、压缩追踪状态、输出 token 恢复计数、turn 计数等。循环有 7 个不同的"继续点"（Continue Sites），分别处理正常工具循环、上下文过长恢复、压缩触发重试等场景。

服务层（API + 工具 + 上下文）：三个独立的子系统，由核心循环编排协调。API 服务处理模型通信（流式传输、重试策略、提示词缓存）。工具系统提供 66+ 种能力（文件操作、搜索、Agent 派生、MCP 桥接）。上下文系统负责构建系统提示词、注入 CLAUDE.md 内容、管理 git 状态信息。三者之间互不依赖。

基础设施层（OAuth、History、Telemetry、Plugins）：横切关注点，支撑所有其他层但不参与主循环。OAuth 处理认证，History 提供对话持久化和恢复（claude --resume），Telemetry（懒加载，~400KB+）追踪使用数据，Plugins 扩展工具和 Hook。

模块依赖规则

这个分层有一条关键的依赖规则：核心循环（query.ts）依赖服务层，但永远不依赖 UI 层；UI 层（REPL.tsx）依赖 QueryEngine，但永远不直接依赖 query.ts。这意味着你可以把整个终端 UI 替换为 Web UI，只需要重写 REPL 层——QueryEngine 及其以下的所有模块完全不用改动。SDK 模式就是这个设计的直接体现：它绕过了整个 UI 层，直接与 QueryEngine 交互。

1.8 代码规模参考

下一章：系统主循环

第 2 章：系统主循环

这是整个 Claude Code 最核心的章节。理解了主循环，就理解了 Claude Code 的灵魂。

2.1 全景：一次完整的交互

当用户输入一条消息时，Claude Code 执行以下流程：

用户输入 → 上下文组装 → 模型决策 → 工具执行 → 结果注入 → 继续/停止

这个循环不断重复，直到模型决定不再调用工具——返回纯文本响应为止。这就是 Agent Loop（代理循环）的本质。

2.2 双层生成器架构

Claude Code 的查询系统采用双层生成器架构，清晰分离会话管理与查询执行：

为什么要分两层？因为会话管理和查询执行的关注点完全不同。QueryEngine 关心的是"用户说了什么、花了多少钱、这轮结果是否成功"；query() 关心的是"消息是否需要压缩、API 返回了什么、工具执行是否成功、是否需要恢复"。双层分离使得每层的代码都更聚焦、更容易测试。

2.3 QueryEngine：会话生命周期管理

src/QueryEngine.ts（1,155 行）是对话的外壳。它的核心方法 submitMessage() 驱动一次完整的用户交互。

完整配置参数

QueryEngine 通过 QueryEngineConfig 接收所有配置：

// src/QueryEngine.ts
export type QueryEngineConfig = {
  cwd: string                          // 工具执行的工作目录
  tools: Tools                         // 可用工具集（66+ 内置工具）
  commands: Command[]                  // 斜杠命令（/compact, /memory, /clear 等）
  mcpClients: MCPServerConnection[]    // 活跃的 MCP 服务端连接
  agents: AgentDefinition[]            // 自定义 Agent 定义（来自 .claude/agents/）
  canUseTool: CanUseToolFn             // 权限判定函数（多层防御）
  getAppState: () => AppState          // 读取 UI 状态
  setAppState: (f: (prev: AppState) => AppState) => void  // Zustand 式不可变更新

  // 可选配置
  initialMessages?: Message[]          // 会话恢复时的初始消息
  readFileCache: FileStateCache        // 文件状态缓存（去重读取）
  customSystemPrompt?: string          // 完全覆盖系统提示词
  appendSystemPrompt?: string          // 追加到系统提示词末尾
  userSpecifiedModel?: string          // 模型覆盖（如 claude-sonnet）
  fallbackModel?: string               // 错误时降级模型
  thinkingConfig?: ThinkingConfig      // 扩展思考配置
  maxTurns?: number                    // 最大工具调用轮次（安全限制）
  maxBudgetUsd?: number                // USD 成本上限
  taskBudget?: { total: number }       // API 侧 Token 预算
  jsonSchema?: Record<string, unknown> // 结构化输出 JSON Schema
  verbose?: boolean                    // 详细调试日志
  abortController?: AbortController    // 取消控制器
  orphanedPermission?: OrphanedPermission  // 孤儿权限处理
}

几个值得注意的设计细节：

• canUseTool 包装：submitMessage() 内部会包装这个函数，在原有权限检查基础上追踪所有权限拒绝事件。这些拒绝记录最终会在结果消息中返回给 SDK 消费者（如桌面应用），让它们知道用户拒绝了哪些操作
• readFileCache：防止模型重复读取同一个文件。如果模型在第 3 轮调用 FileReadTool 读了 src/query.ts，第 5 轮再次请求时，缓存会返回已有内容而不是重新读取磁盘
• orphanedPermission：处理一种边缘情况——上一次会话在用户授权"始终允许 BashTool"后崩溃，权限没有持久化。下次启动时，这个"孤儿权限"会被重放一次

submitMessage() 八阶段生命周期

submitMessage() 驱动一次完整的用户交互，分为 8 个阶段：

各阶段详解：

阶段 1 — 设置：为什么每轮都要清除技能发现（clearSkillDiscovery()）？因为技能是在工具执行过程中动态发现的（通过 SkillSearchTool），上一轮发现的技能可能引用了已经不存在的工具或配置。每轮重新发现确保技能始终是最新的。

阶段 2 — 孤儿权限：只在会话的第一次 submitMessage() 调用时触发，且只触发一次（orphanedPermission 使用后被清空）。这处理的是上一个会话崩溃后遗留的权限授权。

阶段 3 — 用户输入处理：processUserInput() 是一个复杂的函数，它需要：

• 解析斜杠命令（/compact 触发手动压缩、/memory 管理记忆等）
• 处理附件（图片、PDF、文件引用）
• 将处理后的消息推入 mutableMessages 并持久化到磁盘

阶段 5 — 本地命令检查：像 /clear 这样的命令不需要调用 API——它们只是清理本地状态。如果 processUserInput() 设置了 shouldQuery = false，直接 yield 命令输出并提前返回，跳过整个查询循环。

阶段 6 — 主查询循环：这是最复杂的阶段。for await (const msg of query(params)) 迭代查询生成器，处理 7 种不同的消息类型：

• message_start / message_delta：更新 Token 使用统计
• assistant 消息：推入消息列表并 yield 给上层
• progress 消息：行内进度记录
• user 消息：工具结果注入
• compact_boundary：触发 snip/splice/GC 清理
• api_error：yield 重试信号
• tool_use_summary：工具使用摘要

阶段 7 — 预算检查：两种预算限制——USD 成本（getTotalCost() > maxBudgetUsd）和结构化输出重试次数（最多 5 次）。

阶段 8 — 结果提取：isResultSuccessful() 检查最后一条 assistant 消息是否有效。最终 yield 的结果消息包含丰富的元数据：usage（Token 使用量）、cost（USD 成本）、turns（工具调用轮次）、stop_reason、permission_denials（被拒绝的权限列表）等。

2.4 query()：核心循环的实现

src/query.ts（1,728 行）是 Claude Code 最复杂的单个模块，实现了一个基于状态机的异步生成器循环。

核心签名

export async function* query(
  params: QueryParams,
): AsyncGenerator<StreamEvent | Message | ToolUseSummaryMessage, Terminal>

关键点：这是一个 async function*——异步生成器。它不是一次性返回结果，而是边执行边 yield 事件，使调用方可以实时渲染流式输出。

循环状态

每次循环迭代共享一个可变的 State 对象：

type State = {
  messages: Message[]           // 当前消息列表
  toolUseContext: ToolUseContext // 工具执行上下文
  autoCompactTracking: AutoCompactTrackingState | undefined
  maxOutputTokensRecoveryCount: number   // 输出Token恢复计数
  hasAttemptedReactiveCompact: boolean   // 是否已尝试反应式压缩
  maxOutputTokensOverride: number | undefined
  pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined
  stopHookActive: boolean | undefined
  turnCount: number             // 当前轮次
  transition: Continue | undefined  // 上一次循环继续的原因
}

不可变参数 vs 可变状态

query() 内部有一个重要的设计区分：

async function* queryLoop(params: QueryParams, consumedCommandUuids: string[]) {
  // 不可变参数 — 循环期间永不重新赋值
  const { systemPrompt, userContext, systemContext, canUseTool,
          fallbackModel, querySource, maxTurns, skipCacheWrite } = params

  // 可变跨迭代状态 — 7 个 continue site 通过 state = { ... } 更新
  let state: State = {
    messages: params.messages,
    toolUseContext: params.toolUseContext,
    maxOutputTokensOverride: params.maxOutputTokensOverride,
    autoCompactTracking: undefined,
    // ...
  }
}

params 中的字段在循环期间是常量；state 在每个 continue site 通过整体赋值更新（而不是逐字段修改），这让状态变更更加明确和可追踪。

单次循环迭代流程

循环体代码走读

让我们跟着代码走一遍循环体的关键步骤：

第一步：4 级压缩流水线（详见第 3 章）

每次循环迭代的入口处，消息列表依次经过 Tool Result Budget → Snip → Microcompact → Context Collapse → Autocompact。这是防御性设计——即使上一轮工具返回了 100K Token 的输出，压缩流水线会在 API 调用前将其控制在预算内。

// 1. Tool Result 预算裁剪
messagesForQuery = await applyToolResultBudget(messagesForQuery, ...)

// 2. History Snip（Feature-gated）
if (feature('HISTORY_SNIP')) {
  const snipResult = snipModule!.snipCompactIfNeeded(messagesForQuery)
  messagesForQuery = snipResult.messages
  snipTokensFreed = snipResult.tokensFreed
}

// 3. Microcompact
const microcompactResult = await deps.microcompact(messagesForQuery, ...)
messagesForQuery = microcompactResult.messages

// 4. Context Collapse（Feature-gated）
if (feature('CONTEXT_COLLAPSE') && contextCollapse) {
  const collapseResult = await contextCollapse.applyCollapsesIfNeeded(
    messagesForQuery, toolUseContext, querySource
  )
  messagesForQuery = collapseResult.messages
}

第二步：构建 API 请求

const fullSystemPrompt = asSystemPrompt(
  appendSystemContext(systemPrompt, systemContext)  // 系统上下文后置
)
// userContext 通过 prependUserContext() 前置于消息

上下文的注入顺序对提示词缓存有影响：系统提示词（较稳定）后置追加系统上下文（Git 状态等），用户上下文（CLAUDE.md、日期）前置于消息。这种安排让系统提示词部分能更高效地被缓存。

第三步：流式调用 + 工具并行执行

callModel() 返回一个 async generator，StreamingToolExecutor 在流式接收响应的同时就开始执行已完成的工具调用（详见 2.5 节）。

第四步：记忆预取消费

// 在循环入口创建，使用 `using` 关键字确保在所有退出路径上 dispose
using pendingMemoryPrefetch = startRelevantMemoryPrefetch(
  state.messages, state.toolUseContext,
)

using 是 TypeScript 的 Explicit Resource Management 语法——当 generator 退出时（无论正常返回还是异常），pendingMemoryPrefetch 的 [Symbol.dispose]() 会自动调用，用于发送遥测和清理资源。记忆预取在模型流式生成期间并行运行，通过 settledAt 守卫确保每轮只消费一次。

2.5 流式处理与并行工具执行

Claude Code 的流式处理不是简单的"等 API 返回再显示"。它利用 StreamingToolExecutor 实现了流式工具并行执行：

                    API 流式输出
                    ▼▼▼▼▼▼▼▼▼▼
    ┌──────────────────────────────────┐
    │ StreamingToolExecutor            │
    │                                  │
    │ tool_use_1 完成 → 立即执行 ────→ │ 结果就绪
    │ ...模型继续生成...                │
    │ tool_use_2 完成 → 立即执行 ────→ │ 结果就绪
    │ ...模型继续生成...                │
    │ tool_use_3 完成 → 立即执行 ────→ │ 结果就绪
    └──────────────────────────────────┘

    时间线对比：
    串行执行：  [===API===][tool1][tool2][tool3]
    流式并行：  [===API===]
                   [tool1]     ← 利用流式窗口 (5-30s)
                      [tool2]  ← 覆盖 ~1s 工具延迟
                         [tool3]
                [==结果即时可用==]

StreamingToolExecutor 实现原理

StreamingToolExecutor（src/services/tools/StreamingToolExecutor.ts）的核心逻辑：

1. addToolUseBlock(block)：API 流式响应在解析到完整的 tool_use JSON block 时调用此方法。注意是"完整的 block"——不需要等整个 API 响应结束，一个 tool_use block 的 JSON 完成解析就可以分发执行
2. 内部执行：每个 block 被立即提交给 runTools() 执行。权限检查、输入校验、工具调用都在此时发生
3. getCompletedResults()：在 API 流式响应结束后调用，收集所有已完成的工具执行结果。由于工具在流式期间就已经开始执行，大部分结果此时已经就绪

这种设计的效果是：在一个典型的 API 响应（5-30 秒的流式窗口）中，多个工具可以被分发和完成。到流式结束时，工具结果已经可用——消除了串行执行的瓶颈。

2.6 Feature Flag 条件加载

query.ts 开头使用了 4 个 Feature Flag 条件加载模块：

import { feature } from 'bun:bundle'

const reactiveCompact = feature('REACTIVE_COMPACT')
  ? (require('./services/compact/reactiveCompact.js') as typeof import('./services/compact/reactiveCompact.js'))
  : null
const contextCollapse = feature('CONTEXT_COLLAPSE')
  ? (require('./services/contextCollapse/index.js') as typeof import('./services/contextCollapse/index.js'))
  : null
const snipModule = feature('HISTORY_SNIP')
  ? (require('./services/compact/snipCompact.js') as typeof import('./services/compact/snipCompact.js'))
  : null
const skillPrefetch = feature('EXPERIMENTAL_SKILL_SEARCH')
  ? (require('./services/skillSearch/prefetch.js') as typeof import('./services/skillSearch/prefetch.js'))
  : null

这个模式有三个层次：

1. 编译时消除：feature() 在 Bun bundler 构建时被求值。外部构建中 feature('REACTIVE_COMPACT') 返回 false，整个 require() 分支被 tree-shaking
2. 类型安全：as typeof import(...) 让 TypeScript 知道模块的完整类型，IDE 补全和类型检查不受影响
3. 运行时守卫：代码中使用 if (contextCollapse) { contextCollapse.applyCollapsesIfNeeded(...) }，这个 null 检查在编译时也被消除

2.7 七个继续点（Continue Sites）

query() 循环有 7 个导致循环继续的位置，每个对应一种恢复策略：

PTL（Prompt-Too-Long）恢复流程

Max-Output-Tokens 恢复

2.8 错误扣留策略（Withholding）

这是 Claude Code 最巧妙的设计之一：可恢复的错误不立即 yield 给上层。

工作原理

当出现 prompt_too_long 或 max_output_tokens 错误时，query() 不会立即通知调用方。它将错误推入 assistantMessages 但保留引用，然后运行恢复检查。如果恢复成功，错误永远不会暴露给调用者（包括 SDK 消费者和桌面应用），用户完全感知不到中间的错误。

// src/query.ts — 错误扣留检测函数
function isWithheldMaxOutputTokens(
  msg: Message | StreamEvent | undefined,
): msg is AssistantMessage {
  return msg?.type === 'assistant' && msg.apiError === 'max_output_tokens'
}

一个实际场景

假设模型正在编辑一个大文件，生成了 16,000 Token 的输出后被 max_output_tokens 截断：

1. 错误发生：API 返回 stop_reason: 'max_output_tokens'
2. 扣留而非暴露：错误被包装为 AssistantMessage（带 apiError: 'max_output_tokens'），推入消息列表但不 yield 给调用方
3. 恢复策略 1 — 升级：检查是否可以升级到 ESCALATED_MAX_TOKENS（64K）。如果可以，直接用更大的 Token 限制重试，不注入任何用户消息
4. 恢复策略 2 — 续写：如果升级不可用或已经用过，注入一条 meta 用户消息 "Output token limit hit. Resume directly from where you left off..." 让模型从断点继续，最多重试 3 次
5. 成功恢复：如果恢复成功，那条被扣留的错误消息永远不会 yield——SDK 消费者（如桌面应用）看不到任何错误，用户感知到的是一次流畅的响应

只有当所有恢复尝试都失败时（升级不可用 + 3 次续写都失败），错误才会被 yield 给上层。

为什么这么设计？

如果不做扣留，SDK 消费者（桌面应用、Bridge 模式）收到 error 类型的消息后会终止会话——即使后端的恢复循环还在运行，前端已经不再监听了。扣留机制确保前端只看到"干净"的结果流。

2.9 Token 使用追踪

QueryEngine 维护完整的 Token 使用统计：

totalUsage: {
  input_tokens: 0,
  output_tokens: 0,
  cache_read_input_tokens: 0,
  cache_creation_input_tokens: 0,
  server_tool_use_input_tokens: 0,
}

追踪机制：

• 每条 API 响应的 message_delta 事件中，currentMessageUsage 被更新
• message_stop 时，currentMessageUsage 通过 accumulateUsage() 累加到 totalUsage
• getTotalCost() 基于 totalUsage 和模型定价计算 USD 总成本
• 一旦 getTotalCost() > maxBudgetUsd，整个查询终止——这是防止意外高成本的安全机制

cache_read_input_tokens 和 cache_creation_input_tokens 的追踪对提示词缓存策略至关重要——它们告诉系统缓存是否在有效工作。缓存断裂检测（promptCacheBreakDetection.ts）就依赖这些数据来判断是否发生了缓存失效。

2.10 停止条件

循环在以下条件下终止：

1. 模型未调用工具：返回纯文本响应，正常结束
2. 达到最大轮次：maxTurns 限制
3. USD 预算超限：getTotalCost() > maxBudgetUsd
4. 用户中断：abortController.signal 被触发
5. 不可恢复的错误：PTL/MOT 恢复全部失败
6. 连续压缩失败：3 次 autocompact 连续失败（熔断器）

设计决策：为什么熔断阈值是 3 次？ MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3（src/services/compact/autoCompact.ts）。源码注释引用了生产数据："BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures (up to 3,272) in a single session, wasting ~250K API calls/day globally." 没有这个熔断器之前，压缩一旦进入失败循环，会无限重试——每次消耗一个完整的 API 调用（约 20K output tokens）。3 次阈值在"给压缩服务恢复机会"和"避免资源浪费"之间取得平衡。

设计决策：为什么用异步生成器而不是回调/事件？ query() 是一个 async function*，通过 yield 逐步输出事件。相比回调模式（如 EventEmitter），生成器有两个关键优势：（1）背压控制——消费端不处理完上一个事件，生产端不会继续执行，天然防止事件堆积；（2）线性控制流——循环的 7 个 continue site 可以用普通的 state = { ... }; continue 表达，不需要状态机的显式转换表。代价是调用方必须用 for await...of 消费，但在 Claude Code 中只有 QueryEngine 是消费者，这个约束完全可接受。

2.11 设计亮点总结

1. 双层生成器分离关注点：QueryEngine 管会话生命周期，query() 管单次循环
2. 流式工具并行执行：利用 API 流式窗口覆盖工具延迟
3. 错误扣留保证用户无感知恢复：可恢复错误不暴露给上层
4. 7 个精确的继续点：每种恢复策略都有明确的 transition 标记，可测试、可追踪
5. 编译时 Feature Gate：内部功能在外部构建中被物理移除
6. Task Budget 跨压缩结转：压缩前后的 Token 预算无缝衔接

动手实践：在 claude-code-from-scratch 的 src/agent.ts 中，你可以看到一个 ~574 行的 Agent 主循环实现。对比本章描述的双层生成器架构，思考：为什么最小实现不需要分两层？什么规模下才值得引入 QueryEngine 这样的会话管理层？参见教程 第 1 章：Agent Loop。

第 3 章：上下文工程

上下文工程是 Claude Code 能力的隐形支柱。模型的决策质量完全取决于它看到了什么上下文。

为什么上下文工程如此重要？

LLM 有一个固定大小的上下文窗口（Claude 当前最大 200K token）。而一次真实的编码会话，可能涉及几十次文件读取、数百次工具调用，产生的原始文本量轻松超过百万 token——远远超出上下文窗口的容量。

这意味着系统必须做出艰难的取舍：哪些信息留在上下文中，哪些被压缩或丢弃。如果取舍不当，模型会忘记刚才编辑了哪个文件、重复读取已经看过的内容、或者产生与之前决策矛盾的输出。

可以把上下文窗口想象成一张办公桌：桌面有限，你必须把最重要的文档放在手边，其他的归档到抽屉里。上下文工程就是这套"文档管理系统"——决定桌上放什么（上下文构建）、什么时候把旧文档收进抽屉（压缩）、以及如何让归档的文档在需要时快速取回（持久化与恢复）。

Claude Code 在这方面的工程量远超大多数人的预期。本章将深入分析它的完整上下文管理体系。

关键文件：src/context.ts（190 行）、src/utils/api.ts、src/services/compact/

3.1 上下文构建全景

每次调用 Claude API，模型都是从零开始的——它没有跨请求的持久记忆，只能看到当前请求中携带的内容。因此，Claude Code 必须在每次 API 调用前，将模型需要的所有信息组装成一个完整的请求。

这个组装过程涉及三大支柱：

1. 系统提示词（System Prompt）：定义模型的身份、能力边界和行为规则。这是最稳定的部分，跨请求基本不变。
2. 系统/用户上下文（System & User Context）：环境信息（git 状态、平台）和项目知识（CLAUDE.md 指令文件）。每会话计算一次。
3. 消息历史（Message History）：用户的提问、模型的回答、工具调用和结果——记录了对话中发生的一切。这是变化最快、占用空间最大的部分。

3.2 系统提示词的构建

系统提示词是上下文中最稳定的部分——它定义了模型"是谁"以及"该怎么做"。正因为稳定，它也是提示词缓存的最佳候选。Claude Code 的系统提示词构建在稳定性和灵活性之间做了精心平衡。

归属头（Attribution Header）

基于指纹的身份标识，用于追踪请求来源。

CLI 系统提示词前缀

根据运行模式变化：交互式模式（REPL）和 -p 单次查询模式有不同的前缀指令。

系统提示词优先级

系统提示词的构建有严格的优先级，由 buildEffectiveSystemPrompt()（src/utils/systemPrompt.ts）实现：

// 优先级从高到低：
// 0. overrideSystemPrompt — 完全覆盖（如 loop 模式）
// 1. coordinatorSystemPrompt — 协调器模式（Feature-gated）
// 2. agentSystemPrompt — Agent 定义的提示词
//    - Proactive 模式：追加到默认提示词后面
//    - 普通模式：替换默认提示词
// 3. customSystemPrompt — --system-prompt 参数指定
// 4. defaultSystemPrompt — 标准 Claude Code 提示词
// + appendSystemPrompt 始终追加到末尾（除 override 模式）

这个优先级链确保了不同运行模式（交互、Agent、协调器、SDK）都能获得正确的系统提示词，同时保留用户自定义的能力。

静态/动态边界标记

系统提示词中有一个关键的设计元素——SYSTEM_PROMPT_DYNAMIC_BOUNDARY（src/constants/prompts.ts:114）。这是一个哨兵字符串 __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__，它将系统提示词数组分成两半：

• 边界之前：核心指令、工具描述、安全规则等——对所有用户的所有会话都完全相同的内容
• 边界之后：MCP 工具指令、输出风格、语言偏好等——因用户/会话而异的内容

为什么需要这个边界？因为它直接影响提示词缓存的效率。边界之前的静态部分可以使用 scope: 'global' 缓存，跨所有用户共享——这意味着全球数百万 Claude Code 用户可以共享同一份缓存的核心系统提示词。边界之后的动态部分则只能用 scope: 'org' 或不缓存。没有这个边界，整个系统提示词都只能做 org 级别缓存，浪费大量缓存存储在完全相同的内容上。

Section-Level 缓存

系统提示词的各个组成部分通过 systemPromptSections.ts 实现了 section 级别的缓存。这里有两种类型：

// 计算一次，缓存到 /clear 或 /compact
systemPromptSection('toolInstructions', () => buildToolPrompt(...))

// 每轮重新计算，会破坏提示词缓存
DANGEROUS_uncachedSystemPromptSection(
  'modelOverride',
  () => getModelOverrideConfig(),
  'Live feature flags may change mid-session'  // 必须提供理由
)

DANGEROUS_ 前缀是刻意为之的代码级警示——它提醒开发者：这个 section 每轮都会重新计算，如果值发生变化会破坏提示词缓存。开发者必须提供一个 _reason 参数解释为什么缓存破坏是必要的。大多数 section 都是稳定的（工具描述、安全规则），只有少数依赖实时 feature flag 的 section 需要使用 DANGEROUS_ 变体。

clearSystemPromptSections() 在 /clear 和 /compact 时调用，同时重置 beta header 锁存（详见 3.6.3），让下一次对话获得完全新鲜的状态。

系统上下文（getSystemContext）

来自 src/context.ts 的 getSystemContext() 函数，被 memoize 缓存（每会话只计算一次）。

完整的实现展示了一个精心设计的上下文收集过程：

// src/context.ts — getGitStatus()
export const getGitStatus = memoize(async (): Promise<string | null> => {
  const isGit = await getIsGit()
  if (!isGit) return null

  try {
    // 5 个 git 命令并行执行
    const [branch, mainBranch, status, log, userName] = await Promise.all([
      getBranch(),
      getDefaultBranch(),
      execFileNoThrow(gitExe(), ['--no-optional-locks', 'status', '--short'], ...)
        .then(({ stdout }) => stdout.trim()),
      execFileNoThrow(gitExe(), ['--no-optional-locks', 'log', '--oneline', '-n', '5'], ...)
        .then(({ stdout }) => stdout.trim()),
      execFileNoThrow(gitExe(), ['config', 'user.name'], ...)
        .then(({ stdout }) => stdout.trim()),
    ])

    // 状态截断至 2000 字符，防止大量未提交文件撑爆上下文
    const truncatedStatus = status.length > MAX_STATUS_CHARS
      ? status.substring(0, MAX_STATUS_CHARS) +
        '\n... (truncated because it exceeds 2k characters...)'
      : status

    return [
      // 这条 disclaimer 至关重要——它告诉模型 git 状态是会话开始时的快照，
      // 防止模型在后续轮次中"幻觉"出实时的 git 状态更新
      `This is the git status at the start of the conversation. Note that this status is a snapshot in time, and will not update during the conversation.`,
      `Current branch: ${branch}`,
      `Main branch (you will usually use this for PRs): ${mainBranch}`,
      ...(userName ? [`Git user: ${userName}`] : []),
      `Status:\n${truncatedStatus || '(clean)'}`,
      `Recent commits:\n${log}`,
    ].join('\n\n')
  } catch (error) {
    logError(error)
    return null
  }
})

值得注意的设计细节：

• Promise.all 并行：5 个 git 命令同时执行，而不是串行等待——这在大型仓库中可以节省数百毫秒
• --no-optional-locks：避免 git 命令获取锁导致与其他 git 操作冲突
• MAX_STATUS_CHARS = 2000：限制状态输出长度。想象一个有 500 个未提交文件的 monorepo——不截断的话，git status 本身就会消耗大量上下文预算
• Disclaimer 文本：明确告诉模型这是快照，不会实时更新——这是防止模型幻觉的重要手段

getSystemContext() 本身还有条件跳过逻辑：

export const getSystemContext = memoize(async () => {
  // CCR（Cloud Code Remote）模式或禁用 git-instructions 时跳过
  const gitStatus =
    isEnvTruthy(process.env.CLAUDE_CODE_REMOTE) ||
    !shouldIncludeGitInstructions()
      ? null
      : await getGitStatus()

  // 缓存断裂注入（内部调试功能，Feature-gated）
  const injection = feature('BREAK_CACHE_COMMAND')
    ? getSystemPromptInjection()
    : null

  return {
    ...(gitStatus && { gitStatus }),
    ...(injection ? { cacheBreaker: `[CACHE_BREAKER: ${injection}]` } : {}),
  }
})

用户上下文（getUserContext）

export const getUserContext = memoize(async () => {
  // --bare 模式的微妙语义：
  // - CLAUDE_CODE_DISABLE_CLAUDE_MDS: 硬关闭，始终生效
  // - --bare: 跳过自动发现（CWD 遍历），但尊重显式 --add-dir
  // 注释原文："bare means skip what I didn't ask for, not ignore what I asked for"
  const shouldDisableClaudeMd =
    isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS) ||
    (isBareMode() && getAdditionalDirectoriesForClaudeMd().length === 0)

  const claudeMd = shouldDisableClaudeMd
    ? null
    : getClaudeMds(filterInjectedMemoryFiles(await getMemoryFiles()))

  // 缓存给 yoloClassifier 使用，避免创建 import 循环
  setCachedClaudeMdContent(claudeMd || null)

  return {
    ...(claudeMd && { claudeMd }),
    currentDate: `Today's date is ${getLocalISODate()}.`,
  }
})

CLAUDE.md 发现机制

CLAUDE.md 是 Claude Code 的 项目级指令文件，类似于 .editorconfig 或 .eslintrc，但面向 AI Agent。它的发现过程比看起来要复杂得多。

发现顺序（getMemoryFiles()）：

1. 管理策略文件：从 MDM（移动设备管理）策略中读取的指令（如 /etc/claude-code/CLAUDE.md）
2. 用户主目录：~/.claude/CLAUDE.md 下的全局配置
3. 项目文件：从 CWD 向上遍历目录树，查找每一层的指令文件
4. 本地文件：CLAUDE.local.md（不提交到 git 的个人指令）
5. 显式附加目录：--add-dir 参数指定的额外目录

文件名模式：每个目录下检查 CLAUDE.md、.claude/CLAUDE.md，以及 .claude/rules/ 目录下的所有 .md 文件。这意味着你可以将不同领域的指令拆分成独立文件（如 .claude/rules/testing.md、.claude/rules/style.md），系统会自动加载它们。

优先级排序：文件按从远到近的顺序加载——靠近 CWD 的文件后加载，因此优先级更高。这符合"就近原则"：项目根目录的全局规则可以被子目录的局部规则覆盖。由于 LLM 对上下文末尾的内容关注度更高（近因效应），后加载的指令在模型的"注意力"中权重更大。

@include 指令（src/utils/claudemd.ts）：

CLAUDE.md 文件可以通过 @ 语法引用其他文件：

# 项目指令
@./docs/coding-standards.md
@~/global-rules.md
@/etc/company-policy.md

• @path（无前缀）等同于 @./path，按相对路径解析
• @~/path 从用户主目录解析
• @/path 按绝对路径解析
• 只在叶子文本节点中生效（代码块内的 @ 不会被解析）
• 被引用的文件作为独立条目插入到引用文件之前
• 通过跟踪已处理文件防止循环引用
• 只允许文本文件扩展名（.md、.txt 等），防止加载二进制文件

过滤：filterInjectedMemoryFiles() 排除匹配 .claude-injected-* 模式的文件——这些是由 Hook 或系统程序化注入的，不是用户手动编写的

缓存失效：clearMemoryFileCaches() 在工作目录变更时清除缓存；resetGetMemoryFilesCache() 在 InstructionsLoaded Hook 触发时完全重新加载

上下文注入顺序

// src/utils/api.ts
const fullSystemPrompt = asSystemPrompt(
  appendSystemContext(systemPrompt, systemContext)  // 系统上下文后置
)
// userContext 在消息前置（prependUserContext）

系统上下文后置于系统提示词，用户上下文前置于消息——这个顺序影响提示词缓存的效率。系统提示词是最稳定的部分（跨请求不变），放在最前面有利于缓存命中；而用户上下文（CLAUDE.md、日期）可能随会话变化，放在消息前面不会破坏系统提示词的缓存。

3.3 消息历史管理

Claude Code 不是简单地将所有历史消息发送给 API。它通过一系列机制管理消息列表，确保发送给 API 的消息格式合法、内容精简。

压缩边界（Compact Boundary）

当 autocompact 发生后，消息列表中会插入一个 compact_boundary 标记。之后的 API 调用只发送边界之后的消息：

let messagesForQuery = [...getMessagesAfterCompactBoundary(messages)]

当 HISTORY_SNIP Feature 启用时，还会在此基础上投影一个"剪裁视图"——将被标记为 snipped 的消息从 API 请求中隐藏。

消息规范化（normalizeMessagesForAPI）

normalizeMessagesForAPI()（src/utils/messages.ts，约 200 行）是消息发送前的关键处理步骤。它解决了一个核心问题：Claude Code 内部的消息格式和 API 要求的消息格式不完全一致。

下面是每个处理步骤及其解决的问题：

1. 附件重排序（reorderAttachmentsForAPI）：附件消息在内部可能出现在任意位置，但 API 要求它们在语义上关联的消息之前。此步骤将附件消息向上冒泡，直到遇到 tool_result 或 assistant 消息为止。如果不做这一步，API 可能看到一个孤立的图片块，却不知道它与哪条消息相关。

2. 过滤虚拟消息：标记为 isVirtual 的消息（如 REPL 内部工具调用的临时消息）被移除。这些消息的存在仅为了 UI 展示——例如自动触发的内部操作在界面上需要显示进度，但它们不应进入 API 请求。

3. 构建错误→块类型映射：某些 API 错误（如"PDF 太大"、"图片太大"）需要从后续消息中剥离对应的媒体块。系统构建一个映射表 errorToBlockTypes，将错误文本映射到需要剥离的块类型（document、image）。如果不做这一步，同一个过大的 PDF 会在每次请求中被发送，每次都触发同样的错误。

4. 剥离内部元素：从消息中移除 tool_reference（工具引用标记）、advisor blocks（顾问指令）、因 API 错误而需要剥离的媒体项。tool_reference 是延迟工具加载系统（Tool Search）的内部跟踪标记，API 对此毫无概念——它们的存在会导致 API 返回格式错误。

5. thinking/signature 块处理：根据模型要求处理思考块。某些模型不支持 thinking 或 redacted_thinking 块——发送它们会直接导致 API 返回 400 错误。Signature 块用于验证思考块的完整性，也需要在不支持的模型上剥离。

6. 合并分裂消息：流式解析器可能将一个 API 响应拆分为多条具有相同 message.id 的 AssistantMessage（当并行工具调用产生多个 content block 时）。API 期望一个响应对应一条消息，多条同 ID 消息会违反消息交替规则。

7. 验证和修复配对：API 要求每个 tool_use block 都有对应的 tool_result，反之亦然。会话崩溃、压缩、中途中断都可能破坏这种配对关系。此步骤检测并修复孤儿 block——为缺失结果的 tool_use 生成错误类型的 tool_result，为缺失请求的 tool_result 注入合成的 tool_use。没有这一步，恢复一个崩溃的会话几乎必然会因为配对不完整而报错。

为什么这么复杂？ 因为 Claude API 对消息格式有严格要求：用户/助手消息必须交替出现、tool_use/tool_result 必须配对、thinking 块不能出现在不支持的位置。而 Claude Code 的内部消息列表可能因为会话崩溃恢复、压缩操作、用户中断等原因违反这些约束。normalizeMessagesForAPI 是防御层——确保无论内部状态多混乱，API 始终收到合法的消息序列。

3.4 五级压缩流水线

这是 Claude Code 上下文管理的核心机制。当对话越来越长，Token 使用量不断增长，五级压缩流水线逐级启动。设计哲学是渐进式压缩——先用成本最低的手段尝试释放空间，只在必要时才动用更重的武器。

为什么按此顺序执行？

每一级都比前一级"更重"——消耗更多计算资源，或丢失更多上下文细节：

1. Tool Result Budget 最先：纯本地操作，不调用 API。大结果写入磁盘，上下文只保留预览。零延迟、零成本。
2. Snip 释放最多：直接从消息列表中移除冗余部分，释放大量 Token，可能使后续压缩不必要。
3. Microcompact 成本极低：清理旧工具结果，不调用 API，适合频繁执行。
4. Context Collapse 在 Autocompact 之前：折叠可能使 Token 使用量降到 Autocompact 阈值以下，从而阻止不必要的全量压缩——保留了更细粒度的上下文。
5. Autocompact 作为最后手段：需要 fork 一个子 Agent 调用 API 生成摘要，成本最高，且不可逆（原始消息被摘要替换）。

各级压缩详解

Level 1: Tool Result 预算裁剪

applyToolResultBudget() 是最轻量的处理——纯本地操作，不调用 API。它解决的核心问题是：单次工具调用可能返回巨大的结果。例如，用 FileReadTool 读取一个万行文件，或用 BashTool 执行 find 命令获取数千个文件路径。

处理机制（src/utils/toolResultStorage.ts）：

1. 每个工具声明一个 maxResultSizeChars，默认值为 DEFAULT_MAX_RESULT_SIZE_CHARS = 50,000 字符
2. 可通过 GrowthBook Feature Flag（tengu_satin_quoll）按工具名覆盖阈值
3. 当工具结果超过阈值时，不是简单截断，而是持久化到磁盘

持久化路径: {projectDir}/{sessionId}/tool-results/{tool_use_id}.{txt|json}

上下文中只保留一个紧凑的引用消息：

<persisted-output>
Output too large (2.3 MB). Full output saved to: /tmp/.claude/session-xxx/tool-results/toolu_abc123.txt

Preview (first 2.0 KB):
[前 2000 字节的内容预览]
...
</persisted-output>

为什么选择持久化而非截断？ 截断意味着数据永久丢失——如果模型后来需要查看完整输出（比如在第 500 行发现了 bug），它无法恢复。持久化则保留了完整数据，模型可以随时使用 Read 工具读取磁盘文件来获取完整内容。2KB 的预览给了模型足够的信息来判断是否需要查看完整结果。

此外，applyToolResultBudget 还会追踪已替换的工具结果（ContentReplacementState），确保会话恢复（resume）时做出与原始会话完全相同的替换决策，维持提示词缓存的稳定性。

Level 2: History Snip

snipCompactIfNeeded() 是 Feature-gated 功能（HISTORY_SNIP），通过剪裁历史消息中的冗余部分释放 Token。释放量通过 snipTokensFreed 传递给后续的 autocompact 阈值检查——这很重要，因为 snip 移除了消息但最后一条 assistant 消息的 usage 仍然反映 snip 前的上下文大小，不做修正会导致 autocompact 过早触发。

Level 3: Microcompact

Microcompact 是 Claude Code 压缩体系中最精巧的机制之一。它的目标是清理历史中不再需要的旧工具结果——如果你 30 分钟前读取了一个文件，那个工具结果大概率已经不再有用，但它可能还占着数千 Token。

关键设计：Microcompact 有两条完全不同的路径，根据缓存状态选择：

路径 A：基于时间的 Microcompact（缓存已冷）

当用户离开一段时间后回来（距上次 assistant 消息超过配置的分钟数），服务端的提示词缓存已经过期（默认 5 分钟 TTL）。此时缓存已经"冷了"，无论怎么做都需要重新上传完整前缀。

在这种情况下，Microcompact 直接修改消息内容：

// 将旧工具结果替换为占位符
return { ...block, content: '[Old tool result content cleared]' }

只保留最近 N 个可压缩工具的结果（keepRecent，最少保留 1 个），其他全部替换为占位符。因为缓存已经冷了，修改消息内容不会造成额外的缓存失效——缓存本来就需要重建。

可压缩的工具类型：FileRead、Shell/Bash、Grep、Glob、WebSearch、WebFetch、FileEdit、FileWrite。

路径 B：缓存编辑 Microcompact（缓存仍热）

当缓存还没过期时（用户一直在活跃对话），情况完全不同。如果直接修改消息内容，会导致缓存键（cache key）变化，使 100K+ token 的缓存前缀全部失效，需要重新上传和计费。

因此，缓存编辑路径完全不修改本地消息。它使用一种巧妙的 API 级机制：

1. 在工具结果块上添加 cache_reference 字段（等于 tool_use_id），让服务端能够定位缓存中的具体位置
2. 构造 cache_edits 块，告诉服务端"删除这些 cache_reference 指向的内容"
3. 服务端在缓存中就地删除，不需要客户端重新上传前缀

// 消息本身不变，编辑在 API 层发生
// cache_edits 块通过 consumePendingCacheEdits() 传递给 API 层
return { messages } // 原样返回！

已发出的 cache_edits 通过 pinCacheEdits() 保存，在后续请求中按原始位置重新发送（服务端需要看到它们才能维持缓存一致性）。

两条路径互斥：时间触发优先级更高，如果时间触发生效，会跳过缓存编辑路径（因为缓存已冷，使用 cache_edits 没有意义）。

Level 4: Context Collapse

投影式上下文折叠——关键特性是它不修改原始消息。它创建消息的折叠视图，将不重要的早期消息替换为摘要。这使得折叠可以跨轮次持久化，且可以在需要时回退。

// src/query.ts — Context Collapse 是读时投影，不写原始消息
if (feature('CONTEXT_COLLAPSE') && contextCollapse) {
  const collapseResult = await contextCollapse.applyCollapsesIfNeeded(
    messagesForQuery, toolUseContext, querySource
  )
  messagesForQuery = collapseResult.messages
}

可以用数据库的 View 来类比：底层表（消息数组）的数据不变，但查询时（发送 API 请求时）看到的是一个过滤/转换后的视图。摘要存储在独立的 collapse store 中，projectView() 在每次循环入口将折叠视图叠加到原始消息之上。

Context Collapse 在约 90% 上下文利用率时提交折叠，而 Autocompact 在约 87% 触发（因为需要预留压缩输出空间）。两者同时运行会竞争——Autocompact 可能销毁 Collapse 正要保存的细粒度上下文。因此，当 Context Collapse 启用且活跃时，Autocompact 被抑制。

Level 5: Autocompact

这是最后的手段——当所有轻量级压缩都无法将 Token 使用量控制在安全范围内时，系统 fork 一个子 Agent 来生成整个对话的摘要。

触发条件（shouldAutoCompact()）——必须同时满足 5 个条件：

// 1. 递归守卫：防止压缩 Agent 自己触发压缩（死循环）
querySource !== 'session_memory' && querySource !== 'compact'

// 2. 三重开关检查：任一禁用则不触发
isAutoCompactEnabled()
  // 检查 DISABLE_COMPACT 环境变量
  // 检查 DISABLE_AUTO_COMPACT 环境变量
  // 检查 userConfig.autoCompactEnabled 设置

// 3. 非 Reactive-only 模式
// 当 REACTIVE_COMPACT 启用且特定标志活跃时，
// 让 API 自己的 PTL 错误触发反应式压缩，而非主动压缩

// 4. 非 Context-collapse 模式
// 当 CONTEXT_COLLAPSE 启用且活跃时，autocompact 被抑制
// 原因：collapse 在 ~90% 提交，autocompact 在 ~87% 触发——
// 两者同时运行会竞争，autocompact 可能销毁 collapse 正要保存的细粒度上下文

// 5. Token 阈值（含 snipTokensFreed 修正）
tokenCountWithEstimation(messages) - snipTokensFreed >= getAutoCompactThreshold(model)

阈值计算：

contextWindow = getContextWindowForModel(model)        // 如 200,000
effectiveWindow = contextWindow - maxOutputTokens      // 如 200,000 - 16,000 = 184,000
autoCompactThreshold = effectiveWindow - 13,000        // 如 184,000 - 13,000 = 171,000

对于 200K 上下文窗口 + 16K 最大输出的模型，阈值约在 171,000 Token（约 85.5% 利用率）。可通过 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 环境变量按百分比覆盖。

压缩提示词的设计（src/services/compact/prompt.ts）：

压缩的质量取决于给子 Agent 的提示词。Claude Code 在这里使用了一个精巧的"分析-摘要"两阶段模式：

首先，一个激进的 NO_TOOLS_PREAMBLE 确保摘要模型不会尝试调用工具（在 Sonnet 4.6+ 的自适应思考模型上，模型有时会无视较弱的限制而尝试工具调用，导致无文本输出）：

CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.

然后，模型被要求生成两个部分：

1. 块——思考草稿，按时间顺序分析对话中的每条消息：用户的意图、采取的方法、关键决策、文件名、代码片段、错误及修复、用户反馈
2. 块——正式摘要，包含 9 个标准化部分：

关键的设计巧思：formatCompactSummary() 会剥离 块，只保留

export function tokenCountWithEstimation(messages: readonly Message[]): number {
  // 1. 从消息末尾向前查找，找到最近一条有 API usage 数据的消息
  let i = messages.length - 1
  while (i >= 0) {
    const usage = getTokenUsage(messages[i])
    if (usage) {
      // 2. 向前跳过同一 API 响应的分裂记录（相同 message.id）
      //    并行工具调用可能将一个响应拆成多条消息
      const responseId = getAssistantMessageId(messages[i])
      if (responseId) {
        let j = i - 1
        while (j >= 0) {
          if (getAssistantMessageId(messages[j]) === responseId) {
            i = j  // 锚定到同一响应的最早记录
          } else if (getAssistantMessageId(messages[j]) !== undefined) {
            break   // 遇到不同的 API 响应，停止
          }
          j--
        }
      }
      // 3. 用 server 报告的 token 数作为锚点，加上后续消息的粗略估算
      return getTokenCountFromUsage(usage) +
             roughTokenCountEstimationForMessages(messages.slice(i + 1))
    }
    i--
  }
  // 4. 如果没有任何 usage 数据（如会话刚开始），完全靠字符串长度估算
  return roughTokenCountEstimationForMessages(messages)
}

// query.ts — 循环级别的 remaining 追踪
let taskBudgetRemaining: number | undefined = undefined
// 每次 compact 时：
//   taskBudgetRemaining -= finalContextTokensFromLastResponse(messages)

一旦某个 beta header 被首次发送，它就会持续出现在该会话的所有后续请求中

createUserMessage({
  content: `<system-reminder>
As you answer the user's questions, you can use the following context:
# claudeMd
${claudeMdContent}
# currentDate
Today's date is 2026-04-01.

IMPORTANT: this context may or may not be relevant to your tasks.
</system-reminder>`,
  isMeta: true,
})

// src/query.ts — 使用 using 关键字确保 dispose
using pendingMemoryPrefetch = startRelevantMemoryPrefetch(
  state.messages, state.toolUseContext,
)

// src/query.ts — PTL 恢复的第二阶段
tryReactiveCompact() {
  // 调用 compactConversation() 时设置 urgent=true
  // urgent 模式下：
  //   - 使用更激进的压缩策略
  //   - 可能使用更快（更小）的模型生成摘要
  //   - 不执行会话记忆压缩（太慢）
  compactConversation({ urgent: true })

  // 构建压缩后消息
  buildPostCompactMessages(...)

  // 继续循环
  state.transition = 'reactive_compact_retry'
}

第 4 章：工具系统

工具系统是 Claude Code 能力的载体。66+ 内置工具 + MCP 扩展 = 无限可能。

4.1 Tool 接口定义

Claude Code 的所有能力——文件操作、命令执行、Agent 派生、MCP 调用——都统一抽象为 Tool 接口（src/Tool.ts）。这是整个系统最核心的类型之一：

export type Tool<Input, Output, P extends ToolProgressData> = {
  // ===== 元数据 =====
  name: string                    // 工具唯一标识
  aliases?: string[]              // 别名（兼容旧名称）
  maxResultSizeChars: number      // 结果最大字符数
  shouldDefer?: boolean           // 是否延迟加载（ToolSearch 动态发现）

  // ===== 核心执行 =====
  call(args, context, canUseTool, parentMessage, onProgress?): Promise<ToolResult<Output>>

  // ===== 提示词与描述 =====
  description(input, options): Promise<string>
  prompt(options): Promise<string>

  // ===== Schema 定义 =====
  inputSchema: Input              // Zod 输入 Schema
  inputJSONSchema?: ToolInputJSONSchema  // JSON Schema（API 兼容）

  // ===== 安全与权限 =====
  isConcurrencySafe(input): boolean   // 是否可并发执行
  isReadOnly(input): boolean          // 是否只读操作
  isDestructive?(input): boolean      // 是否破坏性操作
  validateInput?(input, context): Promise<ValidationResult>
  checkPermissions(input, context): Promise<PermissionResult>

  // ===== UI 渲染（React 组件）=====
  renderToolUseMessage(input, options): React.ReactNode
  renderToolResultMessage?(content, progress, options): React.ReactNode
}

每个工具返回的 ToolResult 不仅包含数据，还可以注入额外消息或修改上下文：

export type ToolResult<T> = {
  data: T                    // 工具输出数据
  newMessages?: Message[]    // 额外注入的消息
  contextModifier?: (ctx) => ToolUseContext  // 上下文修改器
}

buildTool 工厂模式

所有工具的创建都通过 buildTool() 工厂函数完成。这个函数将 TOOL_DEFAULTS 与工具的自定义定义合并，确保每个工具都有完整的方法集：

const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: () => false,    // 默认假定不安全，防止并发问题
  isReadOnly: () => false,           // 默认假定有写入，需要权限检查
  isDestructive: () => false,
  checkPermissions: () => ({ behavior: 'allow', updatedInput }),  // 默认允许
  toAutoClassifierInput: () => '',   // 默认跳过分类器
}

function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return {
    ...TOOL_DEFAULTS,
    userFacingName: () => def.name,
    ...def,
  } as BuiltTool<D>
}

这是一个经典的 fail-closed（默认关闭）安全设计：

• isConcurrencySafe: () => false：新工具默认不可并发执行。只有经过验证确实安全的工具（如纯读取操作）才显式 opt-in 为 true。这避免了新增工具因遗漏并发安全标记而导致竞态条件。
• isReadOnly: () => false：默认假设工具有写入副作用，因此必须经过权限检查。只读工具（如 GrepTool、GlobTool）显式声明自己为只读以跳过权限弹窗。
• toAutoClassifierInput: () => ''：默认跳过 ML 分类器的自动审批。这意味着安全相关的工具不会被意外自动批准——必须由工具作者显式提供分类器输入格式。

这种设计确保了：任何新工具在缺少显式配置的情况下，都会走最保守的路径——需要权限、不可并发、不自动批准。

工具目录结构

每个工具独立存放在 src/tools/ 下的同名目录中，遵循统一的文件组织约定：

src/tools/FileEditTool/
├── FileEditTool.ts    // 主实现：call(), validateInput(), checkPermissions()
├── UI.tsx             // React 渲染：renderToolUseMessage, renderToolResultMessage
├── types.ts           // Zod inputSchema + TypeScript 类型
├── prompt.ts          // 工具特定的 system prompt 注入内容
├── constants.ts       // 常量定义
└── utils.ts           // 辅助函数（如 diff 生成、引号标准化）

这种分离的好处是：

• 关注点分离：执行逻辑（.ts）和渲染逻辑（UI.tsx）完全解耦，修改 UI 不影响工具行为
• Schema 可复用：types.ts 中定义的 Zod Schema 既用于运行时验证，也自动转换为 JSON Schema 发送给 API
• Prompt 注入：每个工具可以通过 prompt.ts 向系统提示词注入工具特定的使用指南，例如 FileEditTool 注入关于精确匹配的规则

4.2 工具注册与组装

src/tools.ts 定义了工具从定义到可用的三层组装流水线。这不是一个简单的"注册 + 使用"模式，而是一个带有编译时裁剪、运行时过滤和缓存感知排序的精密管道：

Layer 1：getAllBaseTools() — 编译时工具裁剪

getAllBaseTools()（src/tools.ts:193-251）是所有工具的单一事实来源。它返回当前构建环境下所有可能可用的工具。

核心工具（约 20 个）通过标准 import 直接导入，始终存在：

import { BashTool } from './tools/BashTool/BashTool.js'
import { FileReadTool } from './tools/FileReadTool/FileReadTool.js'
import { FileEditTool } from './tools/FileEditTool/FileEditTool.js'
// ... 其他核心工具

Feature-gated 工具（约 46 个）通过条件 require() 加载：

const SleepTool = feature('PROACTIVE') || feature('KAIROS')
  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null

const SnipTool = feature('HISTORY_SNIP')
  ? require('./tools/SnipTool/SnipTool.js').SnipTool
  : null

这里的 feature() 不是运行时函数——它是 Bun 打包器的编译时宏。当构建面向外部用户的版本时，feature('PROACTIVE') 在编译阶段被求值为 false，整个三元表达式被简化为 const SleepTool = null，而 require() 调用被死代码消除（Dead Code Elimination）物理删除。这意味着内部工具不只是"隐藏"——它们在外部构建的二进制文件中根本不存在，从根本上杜绝了通过运行时手段绕过 Feature Gate 的可能。

还有一个有趣的优化：当 hasEmbeddedSearchTools() 返回 true 时（Anthropic 内部构建将 bfs/ugrep 编译进了 Bun 二进制文件），GlobTool 和 GrepTool 会被排除——因为 shell 别名已经指向了更快的嵌入式实现，专用工具就没有必要了。

Layer 2：getTools() — 运行时上下文过滤

getTools()（src/tools.ts:271-327）在运行时根据当前环境和权限上下文过滤工具。它包含四层递进过滤：

1. SIMPLE 模式（CLAUDE_CODE_SIMPLE 环境变量 / --bare 标志）：将工具集削减到最小核心——仅保留 BashTool、FileReadTool、FileEditTool。这是最轻量的工具配置，适用于资源受限或嵌入式场景。当 REPL 模式同时启用时，这三个工具会被替换为 REPLTool（因为 REPL 的 VM 内部已经封装了它们）。

2. REPL 模式过滤：当 isReplModeEnabled() 为 true 且 REPLTool 可用时，REPL_ONLY_TOOLS 集合中的工具（Bash、FileRead、FileEdit 等）从直接工具列表中隐藏。这些工具仍然存在于 REPL VM 的执行上下文中，但模型不能直接调用它们——必须通过 REPL 工具间接使用。

3. Deny 规则过滤：filterToolsByDenyRules() 检查每个工具是否匹配全局 deny 规则。一个没有 ruleContent 的 deny 规则（blanket deny）会完全移除对应工具，使模型在 system prompt 中根本看不到它。对于 MCP 工具，前缀匹配规则如 mcp__server 会一次性移除该服务器的所有工具——这是在模型看到工具列表之前就完成的，而不是在调用时才检查。

4. isEnabled() 运行时检查：每个工具的 isEnabled() 方法被调用，返回 false 的工具被过滤掉。这允许工具根据运行时条件（如依赖是否可用）自行决定是否启用。

Layer 3：assembleToolPool() — 合并与缓存感知排序

assembleToolPool()（src/tools.ts:345-367）是最终的组装点，将内置工具和 MCP 工具合并为统一的工具池：

export function assembleToolPool(
  permissionContext: ToolPermissionContext,
  mcpTools: Tools,
): Tools {
  const builtInTools = getTools(permissionContext)
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)

  // 分区排序：内置工具作为连续前缀，MCP 工具作为后缀
  const byName = (a: Tool, b: Tool) => a.name.localeCompare(b.name)
  return uniqBy(
    [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),
    'name',
  )
}

这段代码有两个关键设计决策：

分区排序而非全局排序：内置工具按字母排序形成一个连续的前缀块，MCP 工具按字母排序后追加为后缀块。为什么不直接对所有工具做一次全局排序？因为 API 服务器的缓存策略（claude_code_system_cache_policy）在最后一个内置工具之后设置了缓存断点。如果做全局排序，一个名为 mcp__github__create_issue 的 MCP 工具会插入到 GlobTool 和 GrepTool 之间，导致所有下游缓存键失效。分区排序确保添加/移除 MCP 工具只影响后缀部分，内置工具的（更大的）前缀块的缓存始终命中。

uniqBy('name') 内置优先：当内置工具和 MCP 工具同名时，uniqBy 保留首次出现的（即内置工具），因为内置工具在拼接数组中排在前面。这确保了内置工具不会被 MCP 工具意外覆盖。

4.3 内置工具清单

Claude Code 包含 66+ 内置工具，按功能分类如下：

4.4 工具执行生命周期

各阶段详解

Stage 1 - 工具查找

系统按 name 和 aliases 匹配工具定义。如果工具是通过已废弃的别名调用的，系统会在 tool_result 中附加一条废弃警告，引导模型在后续调用中使用新名称。如果未找到匹配工具，直接返回错误消息——这在模型幻觉出不存在的工具时会发生。

Stage 2 - 输入验证

输入验证分为两个阶段：

// Phase 1: Zod Schema 强制转换
// Zod 的 safeParse 不仅验证，还会做类型强制（如字符串数字 → 数字）
const parsed = tool.inputSchema.safeParse(rawInput)
// 如果 Schema 验证失败，格式化错误信息返回给模型

// Phase 2: 业务逻辑验证
// 仅在 Schema 验证通过后执行
const validation = await tool.validateInput(parsed.data, context)
// 返回类型：
// { result: true }                              — 验证通过
// { result: false, message, errorCode }         — 直接拒绝
// { result: false, message, behavior: 'ask' }   — 显示 UI 提示让用户决定

两阶段分离的设计确保了：Schema 层做结构验证（字段存在性、类型），业务层做语义验证（如 FileEditTool 检查文件是否存在、FileWriteTool 检查是否已读过文件再写入）。behavior: 'ask' 模式允许工具在不确定的情况下把决策权交给用户，而非直接拒绝。

Stage 3 - 并行启动

Pre-Tool Hook 和 Bash 分类器同时启动，而不是串行等待。这两个操作可能各需要数十到数百毫秒，并行化可以显著降低权限检查的总延迟。

• Pre-Tool Hook：执行用户在 hooks.preToolUse 中配置的外部脚本，可以返回 allow、deny 或不干预
• Bash 分类器：对 BashTool 调用进行投机性安全分类（判断命令是否只读），结果缓存以供权限检查使用

Stage 4 - 权限检查

权限检查是整个流水线中最复杂的阶段，实现在 checkPermissionsAndCallTool()（src/services/tools/toolExecution.ts）。它涉及多个决策源，按优先级链式求值——一旦某个环节做出明确决定，后续检查即被跳过：

4a. Hook 权限覆盖（最高优先级）

如果 Stage 3 的 Pre-Tool Hook 返回了权限决定（hookPermissionResult），它直接覆盖所有后续检查。Hook 可以返回三种结果：

• allow：跳过所有权限检查，直接执行（例如，企业内部 Hook 自动批准特定命令）
• deny：立即拒绝，附带拒绝原因
• 无决策：穿透到下一层检查

4b. 工具自身的 checkPermissions()

每个工具可以实现自己的权限逻辑。大部分工具使用默认实现（直接返回 allow），但 BashTool 的 bashToolHasPermission() 是一个 200+ 行的复杂实现（详见 4.6 节）。文件工具会检查路径是否在允许的工作目录范围内。

4c. 规则匹配

系统从 7 个来源收集权限规则，按优先级排列：

每条规则有三种行为：allow（自动批准）、deny（自动拒绝）、ask（要求交互确认）。规则的 ruleContent 支持三种匹配模式：

• 精确匹配：Bash(npm install) 仅匹配完全相同的命令
• 前缀匹配：Bash(git commit:*) 匹配所有以 git commit 开头的命令
• 通配符匹配：Bash(git *) 匹配所有以 git 开头的命令

4d. 投机分类器结果（Bash 专用）

在 Stage 3 中并行启动的 Bash 分类器此时返回结果。分类器是一个基于语义描述的 LLM 侧查询，用于判断命令是否匹配用户定义的 allow/deny 描述。如果分类器以高置信度判定命令安全（匹配 allow 描述），权限弹窗可以被自动跳过。分类器的结果通过 pendingClassifierCheck Promise 异步传递，UI 层可以在展示弹窗前等待它。

4e. 交互式确认弹窗

如果以上所有检查都没有做出明确决定（既不是自动允许也不是自动拒绝），用户会看到一个权限确认弹窗。弹窗包含：

• 工具名称和完整输入（如 Bash 命令文本）
• 破坏性命令警告（如果适用，来自 getDestructiveCommandWarning()）
• 建议的权限规则（如 Bash(git commit:*)），用户可以选择保存以避免未来重复确认
• 三个操作选项：允许一次（仅本次）、始终允许（保存为规则）、拒绝

4f. 拒绝追踪

DenialTrackingState 跟踪连续权限拒绝。当同一工具或命令模式被多次拒绝后，系统会向对话中注入引导提示，帮助模型理解它应该尝试不同的方法，而不是反复请求被拒绝的操作。这防止了模型陷入"请求权限 → 被拒绝 → 再次请求"的死循环。

Stage 5 - 工具执行

tool.call() 执行实际操作。关键机制是 onProgress 回调——它允许工具在执行过程中实时发射进度消息。例如，BashTool 通过此回调流式传输 stdout/stderr 输出，用户可以实时看到命令的输出而不必等待命令完成。后台任务（run_in_background: true）在超时阈值后自动转为异步执行。

Stage 6 - 结果处理

mapToolResultToToolResultBlockParam() 将工具的内部 ToolResult 转换为 API 兼容的 ToolResultBlockParam 格式。核心逻辑之一是大结果处理：如果结果超过 maxResultSizeChars，完整内容保存到磁盘，模型接收到的是文件路径 + 截断指示符（详见 4.8 节）。这避免了一次 grep 搜索结果炸掉整个上下文窗口。

Stage 7 - Post-Tool Hook

Post-Tool Hook 分为两个独立事件：

• postToolUse：工具执行成功时触发，Hook 脚本接收工具名称、输入和输出
• postToolFail：工具执行失败时触发，Hook 脚本接收工具名称、输入和错误详情

两者是独立的 Hook 事件，用户可以分别配置不同的处理逻辑。例如，可以在 postToolUse 中对 BashTool 的 git push 命令发送通知，在 postToolFail 中记录失败日志。

错误处理与传播

工具执行流水线的错误处理遵循一个核心哲学：错误是数据，不是异常。在任何阶段发生的错误都不会导致进程崩溃或对话中断——它们被转换为 tool_result 消息（带有 is_error: true 标记）返回给模型，让模型可以自我纠正。

各阶段的错误形式：

classifyToolError()（src/services/tools/toolExecution.ts）的设计值得关注。在 minified 构建中，JavaScript 的 error.constructor.name 会被混淆为 "nJT" 之类的短标识符，无法用于遥测分析。因此该函数采用了一个鲁棒的分类优先级链：

1. TelemetrySafeError 实例 → 使用其 telemetryMessage（开发者显式标记为遥测安全的消息）
2. 标准 Error + errno 码 → 返回 "Error:ENOENT"、"Error:EACCES" 等（Node.js 文件系统错误的稳定标识）
3. Error 实例且 .name 长度 > 3（未被 minify） → 使用原始错误名
4. 其他 Error → 返回 "Error"
5. 非 Error 值 → 返回 "UnknownError"

这种设计确保了遥测数据在任何构建模式下都是可分析的，同时避免泄漏文件路径或代码片段到遥测系统中。

4.5 并发控制

工具的并发执行遵循严格的规则：

• 只读工具可并行：isReadOnly(input) === true 的工具（如 FileReadTool、GrepTool、GlobTool）可以同时执行
• 写入工具串行：isReadOnly(input) === false 的工具（如 FileEditTool、BashTool 写命令）必须串行执行
• 并发安全标记：isConcurrencySafe(input) 提供更细粒度的控制

工具编排由 src/services/tools/toolOrchestration.ts 的 runTools() 函数管理：

// 简化的并发逻辑
const readOnlyTools = toolUses.filter(t => findTool(t).isReadOnly(t.input))
const statefulTools = toolUses.filter(t => !findTool(t).isReadOnly(t.input))

// 只读工具并行执行
await Promise.all(readOnlyTools.map(t => executeTool(t)))

// 有状态工具串行执行
for (const tool of statefulTools) {
  await executeTool(tool)
}

StreamingToolExecutor：流式并行执行

上述静态编排策略有一个局限：它必须等待模型完整输出所有 tool_use blocks 后才开始执行。而实际上，模型的流式输出需要 5-30 秒，一个 tool_use block 可能在流式输出的前几秒就已完整——何必等到最后？

StreamingToolExecutor（src/services/tools/StreamingToolExecutor.ts，约 530 行）正是为此设计。它在模型流式输出的同时，一旦检测到完整的 tool_use block，就立即启动执行：

// 工具在 StreamingToolExecutor 中经历 4 种状态
type ToolStatus = 'queued' | 'executing' | 'completed' | 'yielded'

// 每个工具的跟踪信息
type TrackedTool = {
  id: string
  block: ToolUseBlock
  assistantMessage: AssistantMessage
  isConcurrencySafe: boolean
  results?: Message[]
  pendingProgress: Message[]    // 进度消息即时发射，不等待最终结果
}

并发控制规则直接嵌入执行器内部：

// 能否执行一个工具？
private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executingTools = this.tools.filter(t => t.status === 'executing')
  return (
    executingTools.length === 0 ||
    (isConcurrencySafe && executingTools.every(t => t.isConcurrencySafe))
  )
}

规则很简单：如果当前没有工具在执行，任何工具都可以启动；如果有工具在执行，新工具只能在自身和所有正在执行的工具都标记为并发安全时才能启动。非并发安全的工具必须独占执行。

时间线对比展示了这种优化的效果：

串行执行（等待所有 tool_use 完成后）：
[==========API 流式输出==========][tool1][tool2][tool3]

流式并行执行（StreamingToolExecutor）：
[==========API 流式输出==========]
   [tool1]              ← tool_use_1 完成后立即启动
      [tool2]           ← 利用流式窗口（5-30s）覆盖工具延迟
         [tool3]
[======结果在 API 输出完成时已就绪======]

典型场景下，工具执行延迟约 1 秒，而模型流式输出持续 5-30 秒。这意味着大部分工具执行可以完全隐藏在流式窗口内，用户感知的总延迟接近于纯 API 调用时间。

另一个关键设计是 progressAvailableResolve 唤醒信号。结果消费者（getRemainingResults()）以事件驱动方式工作——当新结果或进度就绪时，执行器通过 resolve Promise 唤醒消费者，避免轮询开销。pendingProgress 消息（如 BashTool 的 stdout 流）会被立即发射给 UI，不必等待工具最终完成。

分区算法与并发上限

在 StreamingToolExecutor 内部，工具被分为两类执行：

1. 并发安全工具（isConcurrencySafe: true）：可以与其他并发安全工具同时执行。典型例子是 FileReadTool、GrepTool、GlobTool——它们只读取数据，不会互相干扰。
2. 非并发安全工具：必须独占执行，在它运行期间不能有其他工具同时执行。FileEditTool、BashTool 的写操作属于此类。

执行器的调度逻辑基于一个简单规则：当前没有工具在执行时，任何工具都可以启动；当有工具在执行时，新工具只能在"自身和所有正在执行的工具都是并发安全"的条件下启动。一旦遇到非并发安全工具，队列处理暂停，等待当前所有执行中的工具完成后，非并发安全工具独占运行。

即使在并行执行场景下，并发数也有硬性上限：MAX_TOOL_USE_CONCURRENCY = 10（可通过 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 环境变量配置）。这防止了模型一次发出 20 个 FileReadTool 调用时导致的文件句柄耗尽或 I/O 竞争。

此外，StreamingToolExecutor 还实现了兄弟取消机制（siblingAbortController）：当一个 Bash 工具执行出错时，它会取消同批次中其他正在执行的工具。这避免了"第一个命令失败但后续命令继续执行"的问题。非 Bash 工具（如 FileReadTool、WebFetchTool）的错误则不会级联——它们的失败通常是独立的，不影响兄弟工具。

结果的发射顺序始终与工具在模型输出中的出现顺序一致（FIFO），即使后面的工具先完成。这确保了消息流的确定性和可预测性。

4.6 BashTool 深度解析

BashTool 是整个工具系统中最复杂的工具——它的实现分布在 18 个源文件中（src/tools/BashTool/ 目录），涵盖安全验证、权限管理、沙箱隔离、命令语义解析等多个子系统。这种复杂性源于一个根本矛盾：Shell 是最强大的工具（几乎可以做任何事），但也是最危险的工具（一条恶意命令可以删除整个文件系统）。

BashTool 的输入 Schema：

{
  command: string              // Shell 命令
  timeout?: number             // 超时（毫秒）
  description?: string         // 活动描述（UI 展示）
  run_in_background?: boolean  // 异步执行
  dangerouslyDisableSandbox?: boolean  // 禁用沙箱
}

4.6.1 安全验证（bashSecurity.ts）

安全验证是 BashTool 的第一道防线，在权限检查之前执行。bashSecurity.ts 约 800 行代码，实现了 23 个命名安全检查（通过 BASH_SECURITY_CHECK_IDS 常量映射为数字 ID，避免在遥测日志中记录可变字符串）：

const BASH_SECURITY_CHECK_IDS = {
  INCOMPLETE_COMMANDS: 1,        // 不完整的命令片段
  JQ_SYSTEM_FUNCTION: 2,        // jq 的 system() 函数调用
  JQ_FILE_ARGUMENTS: 3,         // jq 文件参数限制
  OBFUSCATED_FLAGS: 4,          // 混淆的命令标志
  SHELL_METACHARACTERS: 5,      // Shell 元字符
  DANGEROUS_VARIABLES: 6,       // 管道/重定向中的危险变量
  NEWLINES: 7,                  // 未引用内容中的换行符
  DANGEROUS_PATTERNS_COMMAND_SUBSTITUTION: 8,  // 命令替换
  DANGEROUS_PATTERNS_INPUT_REDIRECTION: 9,     // 输入重定向
  DANGEROUS_PATTERNS_OUTPUT_REDIRECTION: 10,   // 输出重定向
  IFS_INJECTION: 11,            // IFS 变量注入
  GIT_COMMIT_SUBSTITUTION: 12,  // git commit 中的替换
  PROC_ENVIRON_ACCESS: 13,      // /proc/self/environ 访问
  MALFORMED_TOKEN_INJECTION: 14, // 畸形 token 注入
  BACKSLASH_ESCAPED_WHITESPACE: 15, // 反斜杠转义空白
  BRACE_EXPANSION: 16,          // 花括号展开
  CONTROL_CHARACTERS: 17,       // 控制字符
  UNICODE_WHITESPACE: 18,       // Unicode 空白同形字
  MID_WORD_HASH: 19,            // 词中 # 注释攻击
  ZSH_DANGEROUS_COMMANDS: 20,   // Zsh 危险命令
  BACKSLASH_ESCAPED_OPERATORS: 21, // 反斜杠转义运算符
  COMMENT_QUOTE_DESYNC: 22,     // 注释-引号脱同步攻击
  QUOTED_NEWLINE: 23,           // 引号内换行符
}

命令替换阻断是最关键的防御。COMMAND_SUBSTITUTION_PATTERNS 数组包含 11 种模式，覆盖了所有已知的命令替换形式：

const COMMAND_SUBSTITUTION_PATTERNS = [
  { pattern: /<\(/, message: 'process substitution <()' },
  { pattern: />\(/, message: 'process substitution >()' },
  { pattern: /=\(/, message: 'Zsh process substitution =()' },
  // Zsh EQUALS 展开：=curl evil.com → /usr/bin/curl evil.com
  // 绕过 Bash(curl:*) deny 规则，因为解析器看到的基命令是 =curl 而非 curl
  { pattern: /(?:^|[\s;&|])=[a-zA-Z_]/, message: 'Zsh equals expansion (=cmd)' },
  { pattern: /\$\(/, message: '$() command substitution' },
  { pattern: /\$\{/, message: '${} parameter substitution' },
  { pattern: /\$\[/, message: '$[] legacy arithmetic expansion' },
  { pattern: /~\[/, message: 'Zsh-style parameter expansion' },
  { pattern: /\(e:/, message: 'Zsh-style glob qualifiers' },
  { pattern: /\(\+/, message: 'Zsh glob qualifier with command execution' },
  { pattern: /\}\s*always\s*\{/, message: 'Zsh always block (try/always construct)' },
  { pattern: /<#/, message: 'PowerShell comment syntax' },  // 纵深防御
]

这些模式中有几个特别值得注意：

• Zsh equals 展开（=curl）：在 Zsh 中，=cmd 会展开为 cmd 的完整路径（等同于 $(which cmd)）。攻击者可以用 =curl evil.com 绕过 Bash(curl:*) 的 deny 规则，因为权限系统解析到的基命令是 =curl 而不是 curl。
• Zsh glob qualifiers（(e: 和 (+）：Zsh 的 glob 限定符可以在文件名匹配过程中执行任意代码——这是一个常被忽略的代码执行向量。
• PowerShell 注释语法（<#）：虽然 Claude Code 不在 PowerShell 中执行命令，但作为纵深防御，以防未来引入 PowerShell 执行路径。

为了避免误报（例如在字符串字面量 echo '$(...)' 中错误地检测到命令替换），安全验证器使用 extractQuotedContent() 函数先剥离引号内的内容。这个函数逐字符迭代，跟踪单引号/双引号状态，产出三种变体：withDoubleQuotes（仅剥离单引号内容）、fullyUnquoted（剥离所有引号内容）、unquotedKeepQuoteChars（内容剥离但保留引号字符本身，用于检测引号邻接）。

Zsh 危险命令同样有专门的防御。ZSH_DANGEROUS_COMMANDS 集合包含 18 个命令：

• zmodload：Zsh 模块加载器，是多种攻击的入口——zsh/mapfile（通过数组赋值进行不可见的文件 I/O）、zsh/zpty（伪终端命令执行）、zsh/net/tcp（ztcp 网络数据外泄）、zsh/files（内置 rm/mv/ln/chmod 绕过二进制检查）
• emulate -c：一个等效于 eval 的结构，可以执行任意代码
• sysopen/sysread/syswrite/sysseek：细粒度文件描述符操作（来自 zsh/system 模块）
• **zf_* 内置命令**（zf_rm、zf_mv、zf_ln、zf_chmod 等）：zsh/files 模块提供的内置文件操作，绕过了对外部二进制的权限检查

Tree-sitter AST 解析提供了结构化的命令分析能力。当 tree-sitter-bash 可用时，parseCommandRaw() 将命令解析为 AST，parseForSecurityFromAst() 从中提取 SimpleCommand[]（已解析引号的简单命令列表）。如果 AST 分析发现命令结构过于复杂（包含命令替换、展开、复杂控制流），它返回 'too-complex'，触发 ask 行为——即要求用户确认。当 tree-sitter 不可用时（如某些平台），系统回退到基于正则的遗留解析路径。checkSemantics() 函数在 AST 级别进行语义验证，检查即使语法合法但语义危险的命令。

4.6.2 多层权限系统（bashPermissions.ts）

bashToolHasPermission()（src/tools/BashTool/bashPermissions.ts）是整个代码库中最复杂的权限函数，实现了以下分层处理：

第 1 步：AST 解析与复杂度判断

首先尝试使用 tree-sitter 解析命令。解析结果分为三种：

• 'simple'：命令结构简单，可以按子命令逐一检查
• 'too-complex'：包含复杂结构（嵌套替换、管道链等），无法保证安全——跳过详细分析，直接进入 ask 路径
• 'parse-unavailable'：tree-sitter 不可用，回退到遗留的 splitCommand_DEPRECATED() 正则拆分

第 2 步：子命令拆分与上限保护

export const MAX_SUBCOMMANDS_FOR_SECURITY_CHECK = 50

超过 50 个子命令时，系统放弃逐一分析，直接返回 ask——这是一个安全的回退：无法证明安全的就让用户决定。

第 3 步：安全环境变量剥离

在匹配权限规则之前，命令前面的安全环境变量赋值会被剥离。例如 NODE_ENV=prod npm run build 中的 NODE_ENV=prod 被移除，剩下 npm run build 用于规则匹配。SAFE_ENV_VARS 集合包含 26 个已知安全的变量（Go 系列如 GOEXPERIMENT/GOOS/GOARCH，Rust 系列如 RUST_BACKTRACE/RUST_LOG，Node 的 NODE_ENV，locale 变量如 LANG/LC_ALL 等）。

为什么要区分安全和不安全的环境变量？因为 MY_VAR=val command 中的 MY_VAR 可能影响命令行为（如 LD_PRELOAD=evil.so curl），不能无条件剥离。但 NODE_ENV=prod 是无害的，如果不剥离，用户设置的 Bash(npm run:*) 规则就无法匹配到 NODE_ENV=prod npm run build。

第 4 步：前缀提取与规则建议

getSimpleCommandPrefix() 从命令中提取稳定的 2 词前缀用于可复用的权限规则。例如：

注意最后一行：bash、sh、sudo、env 等裸 shell 前缀被显式阻止生成前缀规则，因为 Bash(bash:) 等同于 Bash()——这会意外允许所有命令。

第 5 步：复合命令权限聚合

对于复合命令，所有子命令必须独立通过权限检查。任一子命令被 deny 则整体 deny，任一子命令需要 ask 则整体 ask。建议规则的数量有上限：

export const MAX_SUGGESTED_RULES_FOR_COMPOUND = 5

超过 5 条时，权限弹窗退化为"similar commands"描述，而非列出每一条。这避免了用户在一条 && 链中保存 10+ 条规则的混乱体验。

4.6.3 沙箱模式（shouldUseSandbox.ts）

BashTool 支持在沙箱中执行命令，限制文件系统访问、网络和进程能力。沙箱决策逻辑（shouldUseSandbox()）在以下条件下返回 false（不使用沙箱）：

1. SandboxManager.isSandboxingEnabled() 返回 false（全局禁用）
2. 命令设置了 dangerouslyDisableSandbox: true 且策略允许绕过
3. 命令匹配用户配置的 excludedCommands 排除列表

平台支持：macOS 使用 sandbox-exec 配置文件，Linux 使用 bubblewrap（bwrap）提供类 landlock 的限制。排除命令的处理涉及复合命令拆分、环境变量剥离和通配符匹配——与权限系统共享相同的命令解析基础设施。

4.6.4 sed 验证（sedValidation.ts）

sed 命令有专门的验证层，防止它被用作绕过 FileEditTool 权限的后门。验证采用白名单策略——只有已知安全的模式被自动批准：

安全模式 1：纯行打印（必须有 -n 标志）

• sed -n '5p'（打印第 5 行）
• sed -n '1,10p'（打印 1-10 行）
• sed -n '1p;5p;10p'（打印多个指定行）

安全模式 2：替换表达式

• sed 's/foo/bar/g'（替换操作，但 flags 仅允许 g/p/i/I/m/M/1-9）

被阻断的危险操作：

• w/W 标志（文件写入）
• e/E 标志（命令执行——sed 可以通过 e 标志执行 shell 命令！）
• !（地址取反）
• {} 块（sed 脚本块）
• 非 ASCII 字符（Unicode 同形字检测）
• 反斜杠分隔符 s\（潜在的解析混淆）

当 sed 命令包含文件参数（如 sed -i 's/foo/bar/' file.txt）时，-i（in-place 编辑）标志必须明确存在，且需要文件写入权限。纯读模式下的 sed 不允许操作文件参数。

4.6.5 路径验证与破坏性命令警告

路径验证（pathValidation.ts）对涉及文件路径的命令（cd、rm、mv、cp、cat、grep 等约 24 类命令）提取路径参数并验证其是否在允许的工作目录范围内。不同命令有不同的路径提取规则——cd 将所有参数拼接为一个路径，find 收集第一个非全局标志之前的路径，grep/rg 在解析完 pattern 参数后收集文件路径。所有命令都尊重 POSIX 的 -- 分隔符（之后的所有参数都是位置参数而非标志）。

对于危险的删除路径（rm -rf /、rm -rf ~），无论用户有什么已保存的规则，都始终需要显式批准——这是一个不可覆盖的安全硬限制。

破坏性命令警告（destructiveCommandWarning.ts）是一个纯信息层——它不影响权限决策，只在权限弹窗中显示额外警告。检测的模式包括：

4.6.6 后台任务管理

BashTool 支持两种后台执行模式：

显式后台化：模型在参数中设置 run_in_background: true，命令从一开始就作为 LocalShellTask 异步执行。输出流式写入任务输出文件，模型可通过 TaskGetTool 轮询结果。

自动后台化：在助手模式（长时间运行的对话）下，阻塞命令在 15 秒（ASSISTANT_BLOCKING_BUDGET_MS = 15_000）后自动转为后台执行。系统调用 backgroundExistingForegroundTask() 将前台任务移至后台，释放主循环继续处理。这防止了一个长时间运行的 npm install 或 make build 阻塞整个对话。

4.6.7 命令语义（commandSemantics.ts）

BashTool 不只是机械地检查退出码——它理解不同命令的语义约定。标准 Unix 约定中，退出码 0 = 成功，非 0 = 失败，但这并不普适：

interpretCommandResult() 根据命令名查表解读退出码，避免模型将 grep 的"无匹配"误判为执行失败而发起不必要的重试。

4.6.8 命令分类（UI 展示）

BashTool 还维护了一个命令分类系统，用于 UI 中的折叠显示。isSearchOrReadBashCommand() 函数分析管道中的每个部分，只有当所有部分都是搜索/读取命令时才标记为可折叠：

语义中性命令在管道分类中被跳过——例如 ls dir && echo "---" && ls dir2 仍然被视为读取操作（而非因为 echo 而变成不可折叠）。

4.7 AgentTool 深度解析

AgentTool 负责派生子 Agent，是多 Agent 架构的核心：

{
  description: string          // 3-5 词任务描述
  prompt: string               // 子 Agent 任务指令
  subagent_type?: string       // 专用 Agent 类型
  model?: 'sonnet' | 'opus' | 'haiku'
  run_in_background?: boolean  // 异步执行
  name?: string                // 可寻址的队友名称
  isolation?: 'worktree' | 'remote'  // 隔离模式
}

子 Agent 生命周期

子 Agent 从创建到执行经历 6 个阶段，每个阶段都有精确的决策逻辑：

Stage 1 - Agent 定义查找：如果提供了 subagent_type，系统按类型名匹配预定义的 Agent 定义（如 coder、researcher）。匹配时还会检查 Agent 定义所需的 MCP 服务是否可用、当前权限模式是否允许。未匹配到定义时使用通用默认配置。

Stage 2 - 模型解析：模型选择遵循三级优先级链。调用参数中的 model 字段优先级最高；其次是 Agent 定义中的默认模型；最后继承父 Agent 当前使用的模型。这种设计允许开销敏感的任务使用 haiku，复杂任务升级到 opus。

Stage 3 - 隔离环境搭建：worktree 模式通过 git worktree add 创建独立工作树，子 Agent 在隔离的文件系统视图中工作，避免与父 Agent 的文件编辑冲突。remote 模式检查 CCR（Claude Code Remote）环境可用性，准备远程部署。

Stage 4 - 工具池组装：子 Agent 的工具池不一定与父 Agent 相同。Agent 定义可以指定工具白名单/黑名单，例如 researcher 类型可能只获得只读工具。MCP 工具根据 Agent 定义的需求进行过滤。

Stage 5 - 系统提示词渲染：将 Agent 定义中的提示词模板与环境信息合并。注入内容包括：当前工作目录、操作系统类型、Shell 类型、Git 仓库状态等。这确保子 Agent 对执行环境有准确的认知。

Stage 6 - 执行与返回：根据调用方式分为四种模式：

• 同步：子 Agent 在当前进程内直接执行，结果嵌入父对话的 tool_result 中
• 异步：创建 LocalAgentTask，子 Agent 将结果写入临时文件，父 Agent 通过 TaskGetTool 轮询获取
• 队友：通过 Tmux 或 iTerm2 创建新的终端会话，子 Agent 作为独立进程并行工作，可通过 SendMessageTool 通信
• 远程：通过 CCR 创建远程执行环境，返回 WebSocket URL，结果异步回传

4.8 大结果处理机制

当工具输出超过 maxResultSizeChars，Claude Code 不会将全部内容注入对话上下文：

1. 将完整结果保存到 ~/claude-code/tool-results/ 目录
2. 模型接收：文件路径预览 + 截断指示符
3. 模型可通过 FileReadTool 按需读取完整内容

这避免了上下文膨胀，同时保持完整数据的可达性。

各工具的典型阈值

不同工具的 maxResultSizeChars 根据其输出特征设定：

MCP 工具的大结果处理

MCP 工具的输出有额外处理：二进制 blob（如图片、PDF）超过 25KB 时，自动保存到 .claude/mcp-outputs/ 目录。模型接收到文件路径引用而非内联的 base64 编码数据。这对于处理 MCP 服务端返回的截图、文档等二进制内容尤为重要。

整体设计遵循"按需读取"模式（on-demand read pattern）：模型先看到结果的摘要和位置信息，只在需要详细数据时才通过 FileReadTool 主动拉取。这将一次性的上下文爆炸转化为可控的增量读取。

设计决策：工具结果的三级大小限制 源码中定义了三个递进的限制层（src/constants/toolLimits.ts）： - DEFAULT_MAX_RESULT_SIZE_CHARS = 50,000：单个工具结果的默认上限，超过则持久化到磁盘 - MAX_TOOL_RESULT_TOKENS = 100,000（约 400KB）：绝对上限，任何工具都不能超过 - MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200,000：单条消息中所有工具结果的聚合上限 为什么需要三级？因为并发工具执行时，5 个工具各返回 50K 字符的结果就是 250K——超过单消息限制。聚合上限确保即使多个工具并发返回大结果，注入到对话中的总数据量也不会让上下文窗口失控。

4.9 MCP 工具集成

MCP（Model Context Protocol）工具通过桥接层无缝集成到 Claude Code 的工具系统中。

桥接工具

7 种传输机制

type McpTransport =
  | 'stdio'          // 标准输入/输出（子进程 MCP 服务端）
  | 'sse'            // Server-Sent Events（HTTP 流式）
  | 'sse-ide'        // SSE 变体（IDE 扩展）
  | 'http'           // HTTP 传输（StreamableHTTPClientTransport）
  | 'ws'             // WebSocket（双向实时）
  | 'sdk'            // SDK 原生传输（进程内，SdkControlTransport）
  | 'claudeai-proxy' // Claude.ai 代理服务端

连接状态机

客户端实例被 memoized，避免重复初始化。HTTP 404 + JSON-RPC -32001 检测会话过期。

OAuth 支持

MCP 集成支持三阶段 OAuth：

1. 标准 OAuth 2.0 + PKCE：自动 Token 轮换，30 秒超时
2. 跨应用访问（XAA）via OIDC：企业 IdP 集成，一次登录多个 MCP 服务端
3. Token 验证：主动刷新接近过期的 Token，macOS Keychain 缓存

配置与作用域

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["my-mcp-server.js"]
    },
    "remote-server": {
      "url": "https://api.example.com/mcp"
    }
  }
}

MCP 服务端配置支持 7 种作用域：local / user / project / dynamic / enterprise / claudeai / managed。

MCP 工具在 assembleToolPool() 阶段与内置工具合并，经过去重处理后统一注册。大输出（二进制 blob > 25KB）自动保存到 .claude/mcp-outputs/。

设计决策：为什么 MCP 适合 Agent 生态？ MCP 的核心设计思想是协议而非 SDK——任何语言、任何进程都可以实现 MCP 服务端，只要遵循 JSON-RPC 协议。这与 Claude Code 的工具系统形成了天然互补：内置工具是"深度集成"（直接访问进程内状态），MCP 工具是"广度扩展"（连接外部能力）。7 种传输机制的存在反映了现实世界的多样性——本地工具用 stdio（零网络开销），远程服务用 HTTP/WebSocket（支持认证和断线重连），IDE 插件用 SSE-IDE（适配 VS Code 的进程模型）。配置的 7 层作用域（从本地到企业）则确保了不同组织规模下的管理需求都能被满足。

4.10 工具搜索与延迟加载

并非所有 66+ 工具都会在每次 API 调用时发送给模型。ToolSearchTool 支持延迟加载：

• shouldDefer: true 的工具不会在初始工具列表中出现
• 模型可以调用 ToolSearch 搜索并动态加载需要的工具
• 工具的 searchHint 字段提供搜索提示

这减少了系统提示词的大小，提高了提示词缓存命中率。

searchHint 字段

每个可延迟加载的工具都可以定义 searchHint 字符串，用于提高工具被发现的概率。例如，一个 Jupyter Notebook 编辑工具可能设置 searchHint: "notebook jupyter ipynb cell"。当模型调用 ToolSearch 时，搜索算法同时匹配工具名称、描述和 searchHint。

ToolSearchTool 查询语法

ToolSearchTool 支持三种查询模式：

select: 模式最常用，当模型已经知道需要哪个工具时直接按名称加载，零搜索开销。关键词模式适用于探索性场景，如"我需要一个处理数据库的工具"。

对提示词缓存的影响

延迟加载的核心价值不仅是减小提示词体积，更重要的是稳定缓存键（cache key）。API 请求中的 tools 数组是缓存键的一部分——如果每次请求发送的工具集不同，缓存就会失效。通过将不常用的工具延迟加载，初始工具列表在大部分对话轮次中保持不变，从而获得更高的 prompt cache 命中率，节省 Token 开销并降低延迟。

4.11 设计洞察

1. 统一接口的力量

所有工具——无论是直接访问进程内状态的内置工具、通过 JSON-RPC 连接的 MCP 工具、还是运行在独立 VM 中的 REPL 工具——都共享同一个 Tool 泛型接口。这意味着执行流水线（输入验证 → 权限检查 → Hook → 执行 → 结果处理）对所有工具完全相同。新增一个 MCP 服务端不需要修改任何执行逻辑，只需要实现 call() 并提供 inputSchema。这种统一性是 Claude Code 能够在不增加系统复杂度的前提下从 20 个工具扩展到 66+ 个工具的关键。

2. 安全语义编码为类型

isReadOnly、isDestructive、isConcurrencySafe 不只是布尔标记——它们是参与运行时决策的活跃方法。isReadOnly(input) 接收工具输入作为参数，这意味着同一工具对不同输入可以有不同的安全语义。例如，BashTool 对 ls 返回 isReadOnly: true，对 rm 返回 false。这种细粒度的输入感知安全标记让并发调度器和权限系统能做出更精确的决策，而非对整个工具一刀切。

3. 渲染即工具

每个工具自带 React 渲染方法（renderToolUseMessage、renderToolResultMessage 等），而非由统一的渲染器根据工具类型分发。这种"自描述渲染"设计意味着工具最了解自己的输入输出应该如何展示——FileEditTool 渲染带颜色的 diff，BashTool 渲染带退出码的终端输出，GrepTool 渲染带行号的搜索结果。新增工具时只需实现自己的 UI.tsx，不需要修改任何全局渲染逻辑。

4. Feature Gate 的编译时裁剪

通过 Bun 的 feature() 编译时宏和死代码消除，外部构建从物理上不包含内部工具的代码。这不是运行时的 if (isInternal) 检查（可以被绕过），而是编译产物中完全不存在相关代码——逆向工程也无法恢复。

5. Fail-closed 安全默认值

TOOL_DEFAULTS 中 isConcurrencySafe: () => false 和 isReadOnly: () => false 的选择源于失败模式的不对称性。如果一个工具实际上是只读的但被标记为非只读（忘记 opt-in），后果是用户收到不必要的权限弹窗——烦人但安全。反过来，如果一个有写入副作用的工具被错误标记为只读（忘记 opt-out），后果是它可能在没有权限检查的情况下与其他写入工具并发执行，导致数据损坏——危险且隐蔽。这种不对称性决定了默认值必须选择"安全但可能过度限制"的方向。

6. 纵深防御的分层验证

BashTool 的安全不依赖任何单一防线。它有 7+ 层重叠的安全机制：Tree-sitter AST 解析、正则模式匹配、引用内容提取、路径约束验证、sed 白名单验证、沙箱隔离、权限规则系统。每一层都有已知的局限性（正则可以被精心构造的输入绕过、tree-sitter 可能不可用、沙箱可能不被平台支持），但设计哲学是：任何单层都可以失败，但攻击者需要同时绕过所有层才能成功。这使得利用难度呈指数级增长。

7. Prompt Cache 稳定性作为架构约束

多个看似无关的设计决策实际上都被同一个"隐形"约束驱动——prompt cache 命中率：

• assembleToolPool() 的分区排序（防止 MCP 工具变动污染内置工具的缓存键）
• backfillObservableInput() 只修改 UI 层的浅拷贝而非 API 输入（防止修改消息内容导致缓存失效）
• ToolSearch 延迟加载（稳定初始工具列表，避免每次请求发送不同的工具集）

缓存未命中意味着 API 需要重新处理数千个 token 的系统提示词，增加延迟和成本。这个经济学约束深刻地塑造了架构，但不阅读多个组件很难察觉到。

4.12 工具 UI 渲染模式

每个工具不仅定义执行逻辑，还自带完整的 UI 渲染能力。这是"渲染即工具"设计理念的体现——工具最了解自己的输入输出应该如何展示。

渲染方法一览

每个工具可以定义 4-6 个 React 渲染方法：

renderGroupedToolUse：批量合并渲染

当模型连续调用多个相同类型的工具（如连续 5 个 FileReadTool），逐个渲染会占据大量终端空间。renderGroupedToolUse() 方法将这些调用合并为一个紧凑的视图：

📖 Read 5 files: src/agent.ts, src/tools.ts, src/cli.ts, ...

而非：

📖 Read src/agent.ts
📖 Read src/tools.ts
📖 Read src/cli.ts
📖 Read src/prompt.ts
📖 Read src/session.ts

这不仅节省屏幕空间，也让用户更容易理解模型的意图——"它在批量阅读文件"而非"它在一个一个读文件"。

backfillObservableInput：输入回填

工具输入在到达 UI 之前会经过 backfillObservableInput() 处理。这个方法在不修改发送给 API 的实际输入的前提下，为 UI 观察者扩展输入信息。

典型例子：模型调用 FileEditTool 时只传入相对路径 src/agent.ts，但 UI 展示时需要完整路径 /home/user/project/src/agent.ts。backfillObservableInput() 将 CWD 补全到路径中供 UI 使用，但 API 侧的 tool_use block 保持原样。

为什么不直接修改 API 输入？因为 prompt cache 稳定性。API 请求中的消息内容是缓存键的一部分，任何修改都会导致缓存失效。backfillObservableInput() 只影响 UI 展示层，API 层的消息原封不动。

具体示例：FileEditTool 的 UI 渲染

FileEditTool 的 UI.tsx 根据操作类型渲染不同的视觉效果：

• 创建文件：标题显示"Create"，渲染完整文件内容并附带语法高亮
• 编辑文件：标题显示"Update"，渲染结构化的 diff 补丁，用颜色区分新增行（绿色）和删除行（红色）
• 错误状态：显示匹配失败的上下文，帮助用户理解为什么 old_string 未能在文件中找到匹配

每个工具的 UI.tsx 都遵循同样的模式：导入工具的类型定义，实现相应的 render* 方法，返回 React 节点。这种规范化的结构让新工具的 UI 开发有清晰的模板可循。

动手实践：在 claude-code-from-scratch 的 src/tools.ts 中，~325 行代码实现了 7 个核心工具。对比本章的 66+ 工具体系，这是理解"最小可用工具集"的最佳起点。参见教程 第 2 章：工具系统。

第 5 章：代码编辑策略

好用的 coding agent 不只是会写代码，而是会用低破坏性的方式改代码。

5.1 两种编辑工具

Claude Code 提供两种文件编辑工具，各有其适用场景：

系统提示词明确指引模型：优先使用 FileEditTool。只有在创建全新文件或需要完整重写时，才使用 FileWriteTool。

5.2 FileEditTool：Search-and-Replace 方法

FileEditTool 是 Claude Code 代码编辑的核心工具，采用精确字符串替换策略。

输入 Schema

{
  file_path: string    // 要编辑的文件绝对路径
  old_string: string   // 要替换的精确字符串
  new_string: string   // 替换后的新字符串
  replace_all?: boolean // 是否替换所有出现位置（默认 false）
}

工作原理

FileEditTool 不需要行号、不需要正则表达式。它的工作方式极其简单：

1. 在文件中精确查找 old_string
2. 确保 old_string 在文件中唯一出现（除非 replace_all=true）
3. 将其替换为 new_string
4. 如果 old_string 不唯一，返回错误，要求提供更多上下文

为什么 Search-and-Replace 优于其他方案

这个设计选择背后有深刻的工程考量：

1. 低破坏性

Search-and-replace 只修改目标文本，文件的其余部分完全不变。相比之下，全文件写入可能：

• 意外丢失未预期的内容
• 引入格式变化（缩进、空行）
• 在大文件上因 Token 限制截断内容

2. 可验证性

每次编辑都有明确的"before"和"after"。用户可以精确看到什么被改了——这比看一个完整的新文件要容易得多。

3. 抗幻觉

模型需要提供文件中实际存在的精确字符串。如果模型"幻觉"了不存在的代码，编辑会直接失败并返回错误，而不是静默地写入错误内容。

4. Token 效率

对大文件的小修改，search-and-replace 只需要发送修改点附近的上下文，而不是整个文件内容。

5. Git 友好

Search-and-replace 产生的 diff 最小化、最精确。自动化 PR 创建时，reviewer 看到的是干净的、有针对性的变更。

与备选方案的对比

在确定 search-and-replace 方案之前，有必要理解为什么其他看似合理的方案被排除了：

基于行号的编辑（如 edit line 42-45）：这是最直觉的方案，但也是最脆弱的。问题在于行号是位置相关的——当模型在一个对话 turn 中需要对同一文件做多处修改时，第一个编辑（比如在第 10 行插入 3 行代码）会导致后续所有行号偏移。模型要么需要一个复杂的行号重算逻辑，要么只能保证每次只编辑一处。而 search-and-replace 是位置无关的：不管文件上方插入了多少行，目标字符串的内容不会变，匹配始终有效。

基于 AST 的编辑（如 rename function foo to bar）：这个方案在理论上很优雅，但实际不可行。Claude Code 需要支持几十种编程语言，为每种语言维护一个完整的 AST 解析器成本极高。更关键的问题是：语法错误的文件恰恰是最需要编辑的文件，但 AST 解析器在遇到语法错误时会直接报错拒绝解析。这意味着在最需要编辑工具的场景下（修 bug、修语法错误），工具反而不可用。

Unified diff/patch 格式（如让模型直接输出 @@ -1,3 +1,4 @@ 格式的 diff）：LLM 在生成这种严格格式时表现很差。Unified diff 要求精确的 hunk header（起始行号和行数），要求每一行都正确使用 +/-/空格 前缀，上下文行数必须与 header 声明一致。任何一个字符的偏差都会导致整个 patch 无法应用。相比之下，search-and-replace 只需要模型提供两段自然语言级别的字符串——这正是 LLM 最擅长的任务形式。

全文件重写（即 FileWriteTool 的方式）：对于小文件可行，但对于大文件问题严重。一个 500 行的文件，哪怕只改一行，模型也需要输出完整的 500 行内容。这不仅浪费 Token，更危险的是模型可能在输出过程中遗漏未修改的代码——特别是文件中间重复性较强的部分（如一系列相似的 case 语句）。而且用户无法快速 review 变更：面对一个 500 行的新文件，找到实际修改的那一行如同大海捞针。

幻觉安全是 search-and-replace 最被低估的优势。考虑这个场景：模型"记得"文件中有一个 handleError() 函数，但实际上这个函数在上一次重构中已经被重命名为 processError()。如果使用 search-and-replace，模型提供 old_string: "function handleError()" 会直接失败（error code 8: "String to replace not found in file"），模型看到错误后会重新读取文件，发现正确的函数名。如果使用全文件重写，模型可能会写出包含 handleError() 的完整文件，覆盖掉正确的 processError()——而且这个错误完全是静默的，不会有任何报错。

输入预处理管线

在进入核心的验证和执行流程之前，模型的输入会先经过一个预处理阶段。normalizeFileEditInput() 在 validateInput 之前被调用，负责清洗模型输出中常见的瑕疵：

1. 尾部空白裁剪

模型生成代码时经常在行尾添加多余的空格或 tab。stripTrailingWhitespace() 会对 new_string 的每一行去除尾部空白字符。但这个规则有一个重要的例外：.md 和 .mdx 文件不做尾部空白裁剪。这是因为在 Markdown 语法中，行尾的两个空格表示硬换行（
），裁剪掉会改变文档的语义。

// Markdown 使用两个尾部空格作为硬换行——裁剪会改变语义
const isMarkdown = /\.(md|mdx)$/i.test(file_path)
const normalizedNewString = isMarkdown
  ? new_string
  : stripTrailingWhitespace(new_string)

2. API 反消毒（Desanitization）

Claude API 出于安全考虑，会将某些 XML 标签"消毒"（sanitize）为短形式，防止模型输出被误解析为 API 控制标签。例如：

当模型输出的 old_string 无法精确匹配文件内容时，desanitizeMatchString() 会尝试将这些消毒后的短形式还原为原始标签。如果还原后能匹配成功，同样的替换也会应用到 new_string，确保编辑的一致性。

这个预处理阶段对用户完全透明——大多数情况下用户不会意识到它的存在。但对于编辑包含 XML 标签或 Human:/Assistant: 等特殊字符串的文件（例如 prompt 模板文件），它是编辑能否成功的关键。

完整验证管线

FileEditTool 的 validateInput() 方法实现了一个多层验证管线，在真正执行编辑之前拦截各种问题。验证的顺序是刻意设计的：低成本的检查在前，需要文件 I/O 的检查在中，依赖文件内容的检查在后。这样在早期阶段就能拦截的问题不会浪费后续的磁盘读取开销。

完整的验证步骤和对应的错误码：

几个值得展开讨论的步骤：

步骤 7-8：文件创建的双重门控。old_string 为空有特殊语义——它表示"创建新文件"。当 old_string 为空且文件不存在时，验证直接通过；当 old_string 为空但文件已存在且有内容时（error code 3），会阻止操作，防止模型误用创建语义覆盖已有文件。但如果文件存在且内容为空（fileContent.trim() === ''），则允许通过——这处理了"空文件等同于不存在"的边界情况。

步骤 12：字符串查找。这一步调用前面介绍的 findActualString()，先尝试精确匹配，再尝试引号标准化后匹配。如果两种方式都找不到，返回 error code 8 并附上 old_string 的内容，帮助模型理解匹配失败的原因。同时，错误返回中还会附带 isFilePathAbsolute 元信息——因为一个常见的失败原因是模型使用了相对路径，导致在错误的目录下查找文件。

步骤 14：配置文件保护。对 .claude/settings.json 等配置文件，验证不仅检查 old_string 是否存在，还会模拟执行编辑并验证结果是否符合 JSON Schema。这防止了一个危险场景：一次看似合理的编辑可能导致配置文件格式损坏，使 Claude Code 无法正常启动。

唯一性约束

在上面的验证管线中，步骤 13 的唯一性约束值得单独讨论。FileEditTool 要求 old_string 在文件中唯一出现。如果不唯一，编辑失败并提示：

Found N matches of the string to replace, but replace_all is false.
To replace all occurrences, set replace_all to true.
To replace only one occurrence, please provide more context to uniquely identify the instance.

这个约束的设计哲学是"宁可失败也不猜测"：

• 防止歧义：如果 old_string 是 return null，文件中可能有 5 处 return null。没有唯一性约束，工具只会替换第一个匹配——但模型想替换的可能是第三个。失败并要求模型提供更多上下文（比如包含周围的函数签名），远比猜测性地替换第一个更安全
• 要求理解上下文：这迫使模型在编辑前真正理解代码结构。模型不能偷懒只提供一个关键词，而是需要提供足够的上下文片段来唯一标识修改点
• replace_all 作为显式逃逸阀：当需要重命名变量等批量操作时，模型必须显式设置 replace_all: true。这个设计让批量替换成为一个"明确的选择"而非"意外的后果"

实现细节：从匹配到写入

引号标准化

文件中可能包含弯引号（curly quotes），这种情况在从 Word、Google Docs 或网页复制过来的代码中很常见。但模型输出的始终是直引号（straight quotes）。如果不做处理，old_string 会因为引号不匹配而查找失败。

Claude Code 在 utils.ts 中实现了一套引号标准化机制：

// normalizeQuotes() 将所有弯引号转为直引号进行匹配
function normalizeQuotes(str: string): string {
  return str
    .replaceAll('\u201C', '"')   // "left double curly → straight
    .replaceAll('\u201D', '"')   // "right double curly → straight
    .replaceAll('\u2018', "'")   // 'left single curly → straight
    .replaceAll('\u2019', "'")   // 'right single curly → straight
}

findActualString() 实现了两阶段匹配策略：

function findActualString(fileContent: string, searchString: string): string | null {
  // 第一阶段：精确匹配
  if (fileContent.includes(searchString)) {
    return searchString
  }

  // 第二阶段：标准化引号后重试
  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
}

需要注意的是，当通过引号标准化匹配成功后，Claude Code 还会通过 preserveQuoteStyle() 将 new_string 中的直引号转换回弯引号，以保持文件的排版一致性。这个函数使用启发式规则判断引号的开闭位置——前面是空白或开括号的是左引号，否则是右引号——并且正确处理缩略语中的撇号（如 don't）。

除了引号标准化，还有一套反消毒（desanitization）机制：Claude API 会将某些 XML 标签（如 、 等）消毒为短形式（、），模型输出编辑时用的是消毒后的形式。desanitizeMatchString() 在匹配失败时自动还原这些标签。

Diff 生成

getPatchForEdit() 负责将编辑操作转化为结构化的 diff patch：

function getPatchForEdits({ filePath, fileContents, edits }): {
  patch: StructuredPatchHunk[]
  updatedFile: string
} {
  let updatedFile = fileContents

  for (const edit of edits) {
    const previousContent = updatedFile
    updatedFile = applyEditToFile(updatedFile, edit.old_string, edit.new_string, edit.replace_all)

    // 如果编辑没有改变任何内容，抛出错误
    if (updatedFile === previousContent) {
      throw new Error('String not found in file. Failed to apply edit.')
    }
  }

  // 使用 diff 库的 structuredPatch 生成 hunk
  // 注意：先将 tab 转为空格用于显示目的
  const patch = getPatchFromContents({
    filePath,
    oldContent: convertLeadingTabsToSpaces(fileContents),
    newContent: convertLeadingTabsToSpaces(updatedFile),
  })

  return { patch, updatedFile }
}

在调用 structuredPatch 之前，会对内容中的 & 和 $ 字符进行转义（替换为特殊 token），因为 diff 库在处理这些字符时存在 bug。diff 计算后再反转义回来。

删除操作的特殊处理

当 new_string 为空时（即删除操作），applyEditToFile() 有一个贴心的细节：它会检查文件中是否存在 old_string + '\n'——如果存在，会连同尾部的换行符一起删除。这防止了删除一行代码后留下一个空行的常见问题。

if (newString !== '') {
  return f(originalContent, oldString, newString)  // 正常替换，精确执行
}

// 删除场景：如果 old_string 后面紧跟换行符，连同换行一起删除
const stripTrailingNewline =
  !oldString.endsWith('\n') && originalContent.includes(oldString + '\n')

return stripTrailingNewline
  ? f(originalContent, oldString + '\n', newString)  // 删除 old_string + 换行
  : f(originalContent, oldString, newString)          // 仅删除 old_string

举个例子：假设文件内容是 line1\nline2\nline3\n，模型想删除 line2。如果直接替换 "line2" 为 ""，结果是 line1\n\nline3\n——多出一个空行。有了这个处理，实际删除的是 "line2\n"，结果是 line1\nline3\n，符合用户预期。

注意这个行为只在 new_string 为空时触发，正常的替换操作不受影响。这是一个很好的"做正确的事"设计——用户不需要知道这个机制的存在，但它让删除操作的结果始终符合直觉。

编辑去重

在实际使用中，模型偶尔会因为重试逻辑等原因发送重复的编辑请求。Claude Code 通过 areFileEditsInputsEquivalent() 进行语义去重——它不只是比较两组编辑的字面值是否相同，而是将两组编辑分别应用到当前文件内容，比较最终结果是否一致：

function areFileEditsEquivalent(edits1, edits2, originalContent): boolean {
  // 快速路径：字面值完全相同
  if (edits1.length === edits2.length &&
      edits1.every((e1, i) => e1.old_string === edits2[i].old_string && ...)) {
    return true
  }

  // 慢速路径：分别应用两组编辑，比较结果
  const result1 = getPatchForEdits({ fileContents: originalContent, edits: edits1 })
  const result2 = getPatchForEdits({ fileContents: originalContent, edits: edits2 })
  return result1.updatedFile === result2.updatedFile
}

这种语义比较能识别出"输入不同但效果相同"的编辑。例如，两组编辑可能使用了不同长度的 old_string 上下文，但最终修改的内容完全一致——它们会被正确判定为等价，避免重复执行。

5.3 FileWriteTool：全文件写入

FileWriteTool 的定位是创建新文件或完整重写：

{
  file_path: string    // 文件绝对路径
  content: string      // 完整文件内容
}

系统提示词中的使用指引：

• 对已有文件，必须先用 Read 工具读取内容，然后编辑
• 优先使用 Edit 工具修改现有文件——它只发送 diff
• 只在创建新文件或完整重写时使用 Write
• 永远不要创建文档文件（.md/README），除非用户明确要求
• 避免使用 emoji，除非用户要求

换行符策略：为什么 Write 始终使用 LF

FileWriteTool 在写入磁盘时始终使用 LF 换行符，不保留原文件的换行风格：

// Write 是全内容替换——模型发送的显式换行符就是它的意图。不要改写它们。
writeTextContent(fullFilePath, content, enc, 'LF')

这个决策来自一个真实的 bug 教训。源码注释记录了历史：

Previously we preserved the old file's line endings (or sampled the repo via ripgrep for new files), which silently corrupted e.g. bash scripts with \r on Linux when overwriting a CRLF file or when binaries in cwd poisoned the repo sample.

旧版本会保留原文件的换行风格（如果是新文件，会通过 ripgrep 采样仓库中其他文件的换行风格来决定）。但这导致了两个问题：

1. 在 Linux 上覆盖一个 CRLF 文件时，Write 会给新内容也加上 \r，导致 bash 脚本因为行尾的 \r 无法执行
2. 当工作目录中有二进制文件时，ripgrep 采样可能将二进制内容误判为 CRLF，污染新文件的换行符

这与 FileEditTool 形成了刻意的不对称：

为什么两者不同？FileEditTool 只修改文件的一小部分，保留换行风格是"最小变更"原则的自然延伸。FileWriteTool 替换整个文件，模型发送的内容（包括换行符）代表了完整的意图，不应被工具层面覆写。

编码检测

FileEditTool 的验证管线中包含一个 BOM（Byte Order Mark）检测步骤，用于正确读取非 UTF-8 编码的文件：

const fileBuffer = await fs.readFileBytes(fullFilePath)
const encoding: BufferEncoding =
  fileBuffer.length >= 2 &&
  fileBuffer[0] === 0xff &&
  fileBuffer[1] === 0xfe
    ? 'utf16le'
    : 'utf8'

如果文件前两个字节是 0xFF 0xFE（UTF-16LE 的 BOM），使用 UTF-16LE 解码；否则默认 UTF-8。完整的 detectEncodingForResolvedPath() 还能识别 UTF-8 BOM（0xEF 0xBB 0xBF），空文件默认 UTF-8（而非 ASCII），避免在后续写入 emoji 或中文时出现编码损坏。

安全验证

FileWriteTool 在执行写入前会进行多层安全检查，与 FileEditTool 共享核心验证逻辑：

// 1. 团队记忆密钥检查
const secretError = checkTeamMemSecrets(fullFilePath, content)

// 2. 权限 deny 规则匹配
const denyRule = matchingRuleForInput(fullFilePath, ..., 'edit', 'deny')

// 3. Windows UNC 路径检查：防止 NTLM 凭据泄露
if (fullFilePath.startsWith('\\\\') || fullFilePath.startsWith('//')) {
  return { result: true }  // 跳过文件系统操作，交由权限系统处理
}

// 4. 文件存在性检查 + mtime 验证
const fileStat = await fs.stat(fullFilePath)
const lastWriteTime = Math.floor(fileStat.mtimeMs)

// 5. 读取前置检查
const readTimestamp = toolUseContext.readFileState.get(fullFilePath)
if (!readTimestamp || readTimestamp.isPartialView) {
  return { result: false, message: 'File has not been read yet.' }
}

// 6. 外部修改检测
if (lastWriteTime > readTimestamp.timestamp) {
  return { result: false, message: 'File has been modified since read.' }
}

FileWriteTool 与 FileEditTool 共享同一套 readFileState 缓存机制——对已有文件，必须先读取才能写入。这个约束在代码层面强制执行，而不仅仅是提示词层面的建议。值得注意的是，如果文件不存在（ENOENT），验证直接通过——因为这是"创建新文件"的正常场景。

FileEditTool 还额外检查文件大小（1 GiB 上限），防止 V8/Bun 字符串长度限制（约 2^30 字符）导致的 OOM：

const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024 // 1 GiB
const { size } = await fs.stat(fullFilePath)
if (size > MAX_EDIT_FILE_SIZE) {
  return { result: false, message: `File is too large to edit (${formatFileSize(size)}).` }
}

5.4 多文件编辑协调

当需要跨多个文件进行协调修改时（如重命名一个被广泛引用的函数），Claude Code 的策略是：

串行编辑

由于 FileEditTool 的 isReadOnly() 返回 false，多个文件编辑操作会串行执行。这确保：

• 不会出现竞争条件
• 每个编辑基于文件的最新状态
• 如果中间某个编辑失败，后续编辑不会在错误基础上继续

原子性考量

单个 FileEditTool 调用是原子的——要么成功替换，要么完全不修改。但跨多个文件的编辑序列不是原子的。如果中间失败，已完成的编辑不会回滚。

这是一个有意的设计权衡：

• 回滚机制会增加极大的复杂度
• Git 提供了天然的回滚能力（git checkout）
• 模型可以在失败后自主修复

级联编辑保护

当多个编辑操作在同一文件上依次执行时，有一个微妙的风险：前一个编辑插入的文本可能被后一个编辑意外匹配到。getPatchForEdits() 通过子串检查来防止这种级联错误：

const appliedNewStrings: string[] = []

for (const edit of edits) {
  const oldStringToCheck = edit.old_string.replace(/\n+$/, '')

  // 检查当前 old_string 是否是之前任何 new_string 的子串
  for (const previousNewString of appliedNewStrings) {
    if (oldStringToCheck !== '' && previousNewString.includes(oldStringToCheck)) {
      throw new Error(
        'Cannot edit file: old_string is a substring of a new_string from a previous edit.'
      )
    }
  }

  // ... 执行编辑 ...
  appliedNewStrings.push(edit.new_string)
}

举个例子：假设编辑 A 将 foo() 替换为 foo() // calls bar()，编辑 B 想将 bar() 替换为 baz()。如果没有级联保护，编辑 B 的 old_string: "bar()" 会匹配到编辑 A 刚插入的注释中的 bar()，导致注释变成 // calls baz()——这不是模型的意图。有了子串检查，系统会检测到 "bar()" 是前一个 new_string 的子串，直接报错让模型重新思考编辑策略。

注意检查前会对 old_string 去除尾部换行（replace(/\n+$/, '')），避免因为换行符差异导致的误判。

Worktree 隔离

对于大规模重构，AgentTool 支持 Git Worktree 隔离模式。子 Agent 在独立的 Worktree 中工作，完成后由用户决定是否合并：

{
  prompt: "重构所有 API 处理函数...",
  isolation: 'worktree'  // 在独立 Worktree 中工作
}

5.5 编辑前的读取要求

系统提示词强制要求：编辑文件前必须先读取。

You MUST use your Read tool at least once in the conversation
before editing. This tool will error if you attempt an edit
without reading the file.

这不仅是提示词层面的约束——FileEditTool 的实现中实际检查 readFileState 缓存，如果文件未被读取过，会返回错误（error code 6）。

这个设计确保模型：

1. 了解文件的当前状态
2. 不会基于过时的记忆进行编辑
3. 能提供正确的 old_string

没有这个约束会怎样？

考虑一个真实的使用场景来理解读取前置的必要性：

场景 1：过期记忆。用户在对话的第 3 轮让 Claude 修改 utils.ts 中的 formatDate() 函数。Claude 在第 1 轮读取过这个文件，知道函数签名是 function formatDate(date: Date)。但在第 2 轮中，用户在 IDE 中手动将签名改为 function formatDate(date: Date, locale?: string)。如果没有读取前置约束，Claude 会基于对话历史中的旧版本生成 old_string: "function formatDate(date: Date)"——这个字符串在当前文件中已经不存在了（因为多了 locale 参数），编辑会失败。更糟糕的情况是，如果 Claude 使用 FileWriteTool 全文件重写，旧版本的内容会直接覆盖用户刚做的手动修改。

场景 2：isPartialView 的陷阱。某些文件在 Read 时会被注入额外内容（如 HTML 文件的注释会被剥离，MEMORY.md 会被截断）。这些文件的 readFileState 会被标记为 isPartialView: true。如果允许基于部分视图进行编辑，模型看到的内容与文件真实内容不一致，old_string 极有可能匹配失败或匹配到错误的位置。

读取前置约束的实现也很值得注意——它区分了"完全没读"和"读了但是部分视图"两种情况，对两者都拒绝编辑：

const readTimestamp = toolUseContext.readFileState.get(fullFilePath)
if (!readTimestamp || readTimestamp.isPartialView) {
  return {
    result: false,
    message: 'File has not been read yet. Read it first before writing to it.',
    errorCode: 6,
  }
}

并发安全：文件状态缓存

readFileState 是工具上下文中的一个缓存，记录每个文件的读取状态：

// readFileState 中每个文件的缓存条目
interface FileStateEntry {
  content: string       // 文件内容（用于匹配验证和内容比较）
  timestamp: number     // 读取时的 mtime（用于外部修改检测）
  offset?: number       // 读取起始行（部分读取时记录）
  limit?: number        // 读取行数（部分读取时记录）
  isPartialView?: boolean // 是否为部分视图
}

编辑前的并发检测流程：

1. 读取文件当前 mtime（通过 fs.stat 或 getFileModificationTime）
2. 对比 readFileState 中缓存的 timestamp
3. 如果 mtime > timestamp → 文件被外部修改 → 返回警告
4. Windows 回退：mtime 不可靠时（云同步、杀毒软件等可能触发 mtime 变化），
   使用内容哈希/全文比较作为二次确认

这解决了一个常见的竞争条件：用户在 IDE 中编辑文件的同时，Claude Code 也在编辑同一个文件。mtime 检查能捕获这种并发修改，避免覆盖用户的手动改动。

具体实现中，Windows 平台的 mtime 检查有特殊处理。因为 Windows 上的云同步（OneDrive）、杀毒软件等可能在不修改文件内容的情况下更新 mtime，所以当检测到 mtime 变化时，如果是完整读取（非 offset/limit 的部分读取），会额外比较文件内容——内容相同则认为安全，可以继续编辑：

const isFullRead = lastRead.offset === undefined && lastRead.limit === undefined
const contentUnchanged = isFullRead && currentContent === lastRead.content
if (!contentUnchanged) {
  throw new Error('File unexpectedly modified')
}

编辑成功后，readFileState 会立即更新为新的内容和时间戳，防止后续编辑触发误报。这个更新至关重要——如果不更新，模型在同一个 turn 中对同一文件做第二次编辑时，新的 mtime（刚才写入导致的）会大于旧的 readTimestamp，触发"文件被外部修改"的误报。更新后，后续编辑可以正常进行而不需要重新读取文件。

5.6 缩进保持

系统提示词中有关于缩进的明确指引：

When editing text from Read tool output, ensure you preserve
the exact indentation (tabs/spaces) as it appears AFTER the
line number prefix.

这特别重要，因为 Read 工具的输出带有行号前缀（cat -n 格式），模型需要正确区分行号前缀和实际文件内容中的缩进。

5.7 NotebookEditTool：Jupyter 编辑

对于 Jupyter Notebook（.ipynb 文件），Claude Code 提供专门的 NotebookEditTool，它理解 Notebook 的 cell 结构，在 cell 级别进行精确编辑。

输入 Schema

{
  notebook_path: string     // .ipynb 文件的绝对路径
  cell_id?: string          // 目标 cell 的 ID（或 cell-N 格式的索引）
  new_source: string        // 新的 cell 内容
  cell_type?: 'code' | 'markdown'  // cell 类型（insert 时必须指定）
  edit_mode?: 'replace' | 'insert' | 'delete'  // 编辑模式（默认 replace）
}

工作原理

Jupyter Notebook 本质上是一个 JSON 文件，核心结构是 cells 数组。每个 cell 包含 cell_type、source、metadata，以及 code cell 特有的 outputs 和 execution_count。

NotebookEditTool 的三种编辑模式：

• replace：替换指定 cell 的 source 内容。对 code cell，会同时重置 execution_count 为 null 并清空 outputs——因为源代码已变，旧的输出不再有效
• insert：在指定 cell 之后插入新 cell。如果不指定 cell_id，则在开头插入。对于 nbformat >= 4.5 的 notebook，会自动生成随机 cell ID
• delete：删除指定 cell，通过 cells.splice(cellIndex, 1) 实现

Cell 定位

Cell 的定位支持两种方式：

1. 原生 cell ID：直接使用 notebook 中每个 cell 的 id 字段
2. 索引格式：cell-N 格式（如 cell-0、cell-3），由 parseCellId() 解析为数字索引

权限与安全

NotebookEditTool 共享与 FileEditTool 相同的安全机制：

• 读取前置检查：必须先读取 notebook 文件才能编辑（与 FileEditTool/FileWriteTool 一致）
• 外部修改检测：通过 mtime 对比检测文件是否被外部修改
• UNC 路径防护：同样拦截 Windows UNC 路径
• 权限分组：在 acceptEdits 权限模式下，NotebookEditTool 与 FileEditTool 一样自动批准，无需用户确认

写入后同样更新 readFileState 缓存，保持与其他编辑工具的一致性。

5.8 原子写入与 LSP 集成

FileEditTool 的 call() 方法实现了一个完整的编辑执行管线，从文件读取到写入后的各种副作用：

async call(input, context) {
  // === 写入前准备（可异步）===

  // 1. 发现技能目录（fire-and-forget）
  const newSkillDirs = await discoverSkillDirsForPaths([absoluteFilePath], cwd)
  addSkillDirectories(newSkillDirs).catch(() => {})  // 不等待

  // 2. 确保父目录存在
  await fs.mkdir(dirname(absoluteFilePath))

  // 3. 文件历史备份（按内容哈希去重，v1 备份格式）
  await fileHistoryTrackEdit(updateFileHistoryState, absoluteFilePath, messageId)

  // === 临界区：避免异步操作以保持原子性 ===

  // 4. 同步读取文件（带编码和换行符元数据）
  const { content, encoding, lineEndings } = readFileSyncWithMetadata(filePath)

  // 5. 过时检测（mtime + 内容比较）
  const lastWriteTime = getFileModificationTime(absoluteFilePath)
  if (lastWriteTime > lastRead.timestamp) { /* ... 抛出错误 */ }

  // 6. 引号标准化 + 查找匹配
  const actualOldString = findActualString(content, old_string)
  const actualNewString = preserveQuoteStyle(old_string, actualOldString, new_string)

  // 7. 生成 patch
  const { patch, updatedFile } = getPatchForEdit(/* ... */)

  // 8. 写入磁盘（保持原始编码和换行符）
  writeTextContent(absoluteFilePath, updatedFile, encoding, lineEndings)

  // === 写入后副作用 ===

  // 9. 通知 LSP 服务器
  lspManager.changeFile(absoluteFilePath, updatedFile)  // didChange
  lspManager.saveFile(absoluteFilePath)                  // didSave

  // 10. 通知 VSCode（用于 diff 视图）
  notifyVscodeFileUpdated(absoluteFilePath, originalContent, updatedFile)

  // 11. 更新 readFileState 缓存
  readFileState.set(absoluteFilePath, {
    content: updatedFile,
    timestamp: getFileModificationTime(absoluteFilePath),
  })

  // 12. 统计与遥测
  countLinesChanged(patch)
  logFileOperation({ operation: 'edit', tool: 'FileEditTool', filePath })
}

几个关键设计点：

临界区最小化：步骤 4-8 之间刻意避免任何 await 异步操作。注释中明确写道 "Please avoid async operations between here and writing to disk to preserve atomicity"。为什么这么重要？JavaScript/TypeScript 是单线程但基于事件循环的——每个 await 都是一个让出控制权的点。如果在过时检测（步骤 5）和写入磁盘（步骤 8）之间有 await，另一个异步操作（如 linter 自动修复、IDE 保存）可能在这个间隙修改文件，导致写入覆盖外部修改。将文件历史备份和目录创建等可异步的操作提前到临界区之外，确保检测和写入之间没有断点。

编码与换行符的完整往返管线。FileEditTool 对文件编码和换行符的处理遵循"读什么写什么"原则，整个管线分为三个阶段：

1. 读取阶段（readFileSyncWithMetadata()）：

• 检测编码：通过 BOM 判断（0xFF 0xFE → UTF-16LE，0xEF 0xBB 0xBF → UTF-8 with BOM，默认 UTF-8）
• 检测换行符：扫描原始内容前 4096 码元，统计 CRLF 和独立 LF 的数量，多数投票决定换行风格
• 规范化内容：将所有 \r\n 统一为 \n，使内部处理全程基于 LF

1. 处理阶段：所有字符串匹配、替换、diff 生成都基于 LF 规范化后的内容。这简化了 old_string 的匹配逻辑——模型不需要关心目标文件是 LF 还是 CRLF

1. 写入阶段（writeTextContent()）：

• 如果检测到的原始换行符是 CRLF：先将内容中的 \n 全部替换为 \r\n
• 使用检测到的原始编码写入磁盘

这意味着编辑一个 UTF-16LE + CRLF 的文件（Windows 上的旧式文本文件），内部全程用 UTF-8 + LF 处理，写入时恢复为 UTF-16LE + CRLF——文件的编码和换行风格完全不变。

LSP 通知：编辑完成后立即通知 LSP 服务器，分为两步——changeFile()（对应 textDocument/didChange）告知内容已修改，saveFile()（对应 textDocument/didSave）触发 TypeScript server 等语言服务器的诊断更新。这些通知都是 fire-and-forget（.catch() 只做日志），不阻塞编辑返回。同时会清除该文件之前已交付的诊断信息（clearDeliveredDiagnosticsForFile），确保新诊断不会被去重过滤。

文件历史备份：fileHistoryTrackEdit() 在写入前捕获文件原始内容，使用内容哈希去重——如果连续多次编辑没有改变内容，不会产生重复备份。备份格式为 v1（基于硬链接或复制），存储在 ~/.claude/fileHistory/ 目录下。由于是幂等操作，即使后续的过时检测失败导致编辑中止，多出的备份也不会影响状态一致性。

技能目录发现：当编辑的文件位于某个技能目录中时，discoverSkillDirsForPaths() 会识别出该目录，并触发动态技能加载。此外 activateConditionalSkillsForPaths() 会激活路径匹配的条件技能。这使得编辑技能文件时，新技能可以立即被发现和使用。

5.9 Diff 渲染

编辑完成后，Claude Code 需要在终端中向用户展示变更内容。这由 StructuredDiff 组件（src/components/StructuredDiff.tsx）负责。

数据结构

Diff 渲染的核心数据来自 diff 库的 StructuredPatchHunk：

// 来自 diff 库的 StructuredPatchHunk
interface StructuredPatchHunk {
  oldStart: number      // 原文件起始行号
  newStart: number      // 新文件起始行号
  oldLines: number      // 原文件涉及的行数
  newLines: number      // 新文件涉及的行数
  lines: string[]       // diff 行（前缀 +/-/空格 表示增/删/不变）
}

关键常量：

const CONTEXT_LINES = 3          // diff 上下文行数（diff 库参数）
const DIFF_TIMEOUT_MS = 5_000    // diff 计算超时（5 秒）

行号调整

当 getPatchForDisplay 接收的是文件的一个片段（如 readEditContext 提供的局部内容）而非完整文件时，hunk 的行号是相对于片段起始位置的。adjustHunkLineNumbers() 将其转换为文件级别的绝对行号：

function adjustHunkLineNumbers(hunks: StructuredPatchHunk[], offset: number) {
  return hunks.map(h => ({
    ...h,
    oldStart: h.oldStart + offset,
    newStart: h.newStart + offset,
  }))
}

语法高亮

StructuredDiff 组件使用 color-diff 原生模块（Rust NAPI）进行语法高亮渲染。整个渲染流程有多层缓存优化：

1. WeakMap 缓存：以 StructuredPatchHunk 对象引用为 key，缓存渲染结果。当 hunk 对象被 GC 回收时，缓存自动释放
2. 参数化缓存键：缓存键包含 theme、width、dim、gutterWidth、firstLine（shebang 检测）和 filePath（语言检测），确保相同参数命中缓存
3. 缓存上限：每个 hunk 最多保留 4 个缓存条目（覆盖正常使用场景中的宽度变化），超出后清空重建

const RENDER_CACHE = new WeakMap<StructuredPatchHunk, Map<string, CachedRender>>()

// 缓存键编码所有影响渲染的参数
const key = `${theme}|${width}|${dim ? 1 : 0}|${gutterWidth}|${firstLine ?? ''}|${filePath}`

终端渲染布局

在全屏模式下，diff 使用双列布局——gutter 列（行号和 +/- 标记）与 content 列分离：

// Gutter 宽度由最大行号的位数决定
function computeGutterWidth(patch: StructuredPatchHunk): number {
  const maxLineNumber = Math.max(
    patch.oldStart + patch.oldLines - 1,
    patch.newStart + patch.newLines - 1,
    1
  )
  return maxLineNumber.toString().length + 3  // 标记符(1) + 两个间隔空格
}

Gutter 列使用 包裹，这样用户在终端中选择复制 diff 内容时，不会包含行号——这是一个细节但重要的用户体验优化。sliceAnsi 函数在切割 ANSI 彩色文本时保持转义序列的完整性，确保颜色不会因为列分割而错乱。

当 gutter 宽度超过终端总宽度时（极窄终端场景），会自动回退到单列渲染，由 Rust 模块处理自动换行。如果原生模块不可用或语法高亮被禁用，则回退到 StructuredDiffFallback 组件进行纯文本渲染。

5.10 与工具系统的整合

编辑工具在工具系统中的位置：

在 acceptEdits 权限模式下，编辑类工具自动批准，无需用户确认——这对信任度高的项目是极大的效率提升。

5.11 关键设计洞察

1. 低破坏性是核心原则：search-and-replace 不是因为简单才被选择，而是因为它对代码库的影响最小
2. 失败比静默错误更好：唯一性约束确保模型不会在歧义场景下做出错误编辑
3. 读取前置是安全网：强制读取确保模型基于最新状态做编辑
4. replace_all 的克制使用：默认 false，只在明确的批量操作场景下启用
5. Git 是终极回滚机制：不需要在编辑工具层面实现复杂的事务或回滚
6. 引号标准化是现实主义：处理真实世界中从各种来源复制粘贴的代码，而不是假设所有文件都完美规范
7. LSP 集成让 IDE 实时响应：编辑后立即通知语言服务器，用户无需等待就能看到最新的诊断信息
8. 文件历史提供额外安全网：基于内容哈希的幂等备份，在 Git 之外多一层保护
9. 输入预处理无声但关键：尾部空白裁剪和 API 反消毒在验证前静默修正模型输出的常见瑕疵，用户和模型都不需要感知这个过程
10. Edit 与 Write 的换行符不对称是刻意的：Edit 保留原始换行风格（最小变更原则），Write 始终使用 LF（模型意图原则），两者在各自的场景下都是正确的选择
11. 级联保护防止自引用编辑：多步编辑中的子串检查确保后续编辑不会意外修改前一步刚插入的文本，将一类难以调试的 bug 拦截在源头

这个编辑策略的精髓可以用一句话概括：宁可编辑失败让模型重试，也不要静默地写入错误内容。

动手实践：在 claude-code-from-scratch 的 src/tools.ts 中，edit_file 工具实现了简化版的 search-and-replace 策略。尝试运行 npm start 让 Agent 编辑一个文件，观察唯一性约束在实际中如何工作。

第 6 章：Hooks 与可扩展性

Hooks 是 Claude Code 的事件驱动扩展机制——在不修改源码的前提下，注入自定义逻辑到关键生命周期节点。

想象一下这些场景：每次 Claude 执行 git push 之前自动运行 lint 检查；每次编辑文件后在后台跑测试，只在测试失败时中断 Claude；或者把所有工具调用发送到公司审计系统。这些都是 Hooks 的典型用法。

Hooks 的核心设计理念是：Agent Loop 的每个关键节点都暴露一个事件，外部代码可以监听这些事件并注入行为。这和 Git Hooks（pre-commit、post-merge）、Webpack Plugins 的设计理念一脉相承，但 Claude Code 面对的问题更复杂——它需要处理权限控制、异步长任务、多 Agent 协调等场景，因此 Hook 系统的设计远比传统的"前后拦截器"复杂得多。

6.1 Hook 事件全景

为什么是这 25 种事件？

Claude Code 的 Hook 事件设计遵循一个原则：覆盖 Agent Loop 完整生命周期的所有关键决策点。回顾第 2 章的 Agent Loop，一次完整的交互涉及：用户输入 → 模型推理 → 工具调用（权限检查 → 执行 → 结果） → 模型决定是否继续 → 最终输出。每个环节都可能需要外部干预，因此每个环节都需要对应的 Hook 事件。

源码中定义了完整的事件列表（src/entrypoints/agentSdkTypes.ts）：

export const HOOK_EVENTS = [
  'PreToolUse', 'PostToolUse', 'PostToolUseFailure',
  'Notification', 'UserPromptSubmit', 'SessionStart', 'SessionEnd',
  'Stop', 'StopFailure', 'SubagentStart', 'SubagentStop',
  'PreCompact', 'PostCompact', 'PermissionRequest', 'PermissionDenied',
  'Setup', 'TeammateIdle', 'TaskCreated', 'TaskCompleted',
  'Elicitation', 'ElicitationResult', 'ConfigChange',
  'WorktreeCreate', 'WorktreeRemove', 'InstructionsLoaded',
  'CwdChanged', 'FileChanged'
] as const

按功能分类：

表格第四列"Matcher 匹配值"很重要——它告诉你，当你在配置中写 matcher: "Write" 时，系统实际拿什么值来比较。对于工具相关事件，matcher 匹配的是工具名；对于 SessionStart，匹配的是触发源；对于 Notification，匹配的是通知类型。这个映射关系在 getMatchingHooks() 的一个 switch 语句中定义。

为什么需要这么多事件？

初看 25 种事件可能觉得过多，但每个事件都有明确的使用场景：

• 工具前后事件（PreToolUse/PostToolUse）：最核心的扩展点。前置 Hook 可以阻止执行、修改输入；后置 Hook 可以执行检查、注入上下文。
• 会话事件（SessionStart/SessionEnd）：初始化环境、清理资源、上报审计日志。
• 环境变化事件（FileChanged/CwdChanged/ConfigChange）：响应外部变化，实现"文件保存后自动 lint"等工作流。
• Agent 协调事件（SubagentStart/SubagentStop/TeammateIdle）：在多 Agent 场景中注入协调逻辑。

6.2 Hook 类型

Claude Code 支持四种可配置的 Hook 类型和两种编程式 Hook 类型。前四种可以写在 settings.json 中，后两种仅在 SDK/插件内部使用。

1. 命令 Hook（Command）

最常用的类型。执行一条 Shell 命令，通过 stdin 接收 JSON 输入，通过 stdout 返回 JSON 结果，通过退出码表达成功/失败/阻塞。

{
  type: 'command',
  command: string,           // Shell 命令
  if?: string,               // 权限规则语法的二次过滤
  shell?: 'bash' | 'powershell',  // Shell 类型，默认 bash
  timeout?: number,          // 超时（秒）
  statusMessage?: string,    // 执行时的 spinner 提示
  once?: boolean,            // 执行一次后自动移除
  async?: boolean,           // 异步执行，不阻塞
  asyncRewake?: boolean      // 异步执行 + 退出码 2 时唤醒模型
}

工作原理（execCommandHook）：

1. 进程创建：调用 spawn() 创建子进程。Shell 的选择逻辑是：如果指定了 shell: 'powershell'，使用 pwsh；否则使用用户的 $SHELL（bash/zsh/sh）。
2. 输入传递：将 Hook 的结构化输入（包含 session_id、tool_name、tool_input 等）序列化为 JSON，通过 stdin 传入子进程。这意味着 Hook 脚本可以通过读取 stdin 获取完整的上下文信息。
3. 环境变量：子进程继承当前环境变量。如果是插件 Hook，额外注入 CLAUDE_PLUGIN_ROOT（插件根目录）和 CLAUDE_PLUGIN_DATA（插件数据目录），命令中的 ${CLAUDE_PLUGIN_ROOT} 占位符也会被替换。
4. 输出收集：等待进程退出，收集 stdout 和 stderr。
5. 结果解析：根据退出码和 stdout 内容决定 Hook 结果（详见 6.4 节）。

适用场景：日志记录、文件同步、CI/CD 触发、shell 脚本集成、自定义 linter。

2. 提示词 Hook（Prompt）

调用 LLM 进行语义评估。适用于需要"理解"而非简单模式匹配的判断场景。

{
  type: 'prompt',
  prompt: string,            // 提示词（$ARGUMENTS 占位符会被替换为 JSON 输入）
  if?: string,               // 权限规则语法过滤
  model?: string,            // 指定模型（默认使用小快模型，如 Haiku）
  timeout?: number,          // 超时（秒，默认 30）
  statusMessage?: string,
  once?: boolean
}

工作原理（execPromptHook）：

1. 将 $ARGUMENTS 占位符替换为 Hook 输入的 JSON 字符串
2. 构建消息数组（可选地包含对话历史），调用 queryModelWithoutStreaming（单轮、无流式）
3. 系统提示词要求模型返回 {"ok": true} 或 {"ok": false, "reason": "..."}
4. 解析模型返回，ok: false 映射为阻塞错误

关键设计细节：Prompt Hook 直接调用 createUserMessage 而不经过 processUserInput——因为后者会触发 UserPromptSubmit Hook，导致无限递归。

适用场景：语义安全检查（"这个 SQL 查询是否可能删除数据？"）、代码审查（"这个修改是否符合项目规范？"）。

3. Agent Hook

与 Prompt Hook 类似，但以 多轮 Agent 模式运行——它可以调用工具来验证条件，不仅仅是"想一想"。

{
  type: 'agent',
  prompt: string,            // 验证指令（$ARGUMENTS 占位符）
  if?: string,
  model?: string,            // 默认使用 Haiku
  timeout?: number,          // 超时（秒，默认 60）
  statusMessage?: string,
  once?: boolean
}

与 Prompt Hook 的关键区别：

Agent Hook 使用 registerStructuredOutputEnforcement 注册一个函数 Hook，确保 Agent 在结束时必须调用结构化输出工具返回结果。这是一个"Hook 嵌套 Hook"的设计——Agent Hook 本身在执行过程中注册临时的 Function Hook 来约束 Agent 行为。

适用场景：复杂验证流程——例如"运行测试并确认全部通过"、"检查编辑的文件是否能通过类型检查"。

4. HTTP Hook

向外部服务发送 POST 请求，适合与企业基础设施集成。

{
  type: 'http',
  url: string,               // POST 端点
  if?: string,
  timeout?: number,          // 超时（秒，默认 10 分钟）
  headers?: Record<string, string>,  // 支持 $VAR 环境变量插值
  allowedEnvVars?: string[], // 允许插值的环境变量白名单
  statusMessage?: string,
  once?: boolean
}

工作原理（execHttpHook）：

1. URL 白名单检查：如果配置了 allowedHttpHookUrls 策略，先检查 URL 是否匹配允许的模式。不匹配直接拒绝，不发任何请求。
2. Header 环境变量插值：遍历 headers，匹配 $VAR_NAME 或 ${VAR_NAME} 模式。只有在 allowedEnvVars 中列出的变量才会被替换，其他变量替换为空字符串。这防止了项目级 .claude/settings.json 中的恶意 Hook 窃取 $HOME、$AWS_SECRET_ACCESS_KEY 等敏感变量。
3. CRLF 注入防护：插值后的 header 值会被去除 \r、\n、\x00 字符，防止恶意环境变量注入额外的 HTTP 头。
4. 代理支持：自动检测 sandbox 代理和环境变量代理（HTTP_PROXY/HTTPS_PROXY），通过代理发送请求。
5. SSRF 防护：不通过代理时，使用 ssrfGuardedLookup 防止请求发往内网地址。
6. 响应解析：HTTP Hook 必须返回 JSON（与 Command Hook 不同，Command Hook 可以返回纯文本）。空 body 被视为 {}（成功且无特殊指令）。

重要限制：HTTP Hook 不支持 SessionStart 和 Setup 事件。原因是在 headless 模式下，这两个事件触发时 sandbox 的 structuredInput 消费者尚未启动，HTTP 请求会死锁。

适用场景：Webhook 通知、审计日志上报、第三方审批系统、合规检查。

5. 回调 Hook（Callback）— 仅限 SDK/插件

编程式函数，在进程内直接执行，不经过 spawn/HTTP 等 I/O 操作。

{
  type: 'callback',
  callback: async (input, toolUseID, signal, index, context) => HookJSONOutput,
  timeout?: number,
  internal?: boolean  // 标记为内部 Hook（启用快速路径优化）
}

为什么 Callback Hook 极快？ Claude Code 在 executeHooks 中有一个重要的快速路径优化：

// src/utils/hooks.ts
// 如果所有匹配的 Hook 都是 callback/function 类型（无需 spawn 外部进程）
if (matchedHooks.every(m => m.hook.type === 'callback' || m.hook.type === 'function')) {
  // 快速路径：跳过 JSON 序列化、AbortSignal 创建、进度事件、结果处理
  for (const [i, { hook }] of matchingHooks.entries()) {
    if (hook.type === 'callback') {
      await hook.callback(hookInput, toolUseID, signal, i, context)
    }
  }
  return  // 不经过常规 processHookJSONOutput 流程
}

这个优化将内部 Hook 的开销从 ~6µs 降低到 ~1.8µs（-70%）。内部 Hook（如文件访问跟踪、commit 归因）在每次工具调用时都触发，累积起来差距很大。

6. 函数 Hook（Function）— 仅限会话内

类似 Callback，但作用域限定在特定会话内，防止跨 Agent 泄漏。

{
  type: 'function',
  id?: string,
  callback: (messages: Message[], signal?: AbortSignal) => boolean | Promise<boolean>,
  errorMessage: string,      // callback 返回 false 时显示的错误
  timeout?: number,
  statusMessage?: string
}

主要用途：Agent Hook 的结构化输出强制（确保 Agent 必须通过特定工具返回结果）。通过 addFunctionHook() 注册，removeFunctionHook() 移除，按 sessionId 隔离——这确保验证 Agent 的函数 Hook 不会泄漏到主 Agent。

通用字段说明

有几个字段在多种 Hook 类型中出现，值得单独解释：

if 条件：这是一个比 matcher 更精细的过滤器。Matcher 匹配工具名（如 "Bash"），而 if 使用权限规则语法匹配工具的具体输入（如 "Bash(git *)"——只在 Bash 工具执行 git 命令时触发）。if 条件在 prepareIfConditionMatcher 中解析：它调用工具的 preparePermissionMatcher 来对工具输入进行模式匹配，复用了权限系统的匹配引擎。if 只适用于工具相关事件（PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest），对其他事件无效。

once 字段：如果为 true，Hook 执行一次后自动从配置中移除。适用于一次性的初始化或验证。

statusMessage 字段：Hook 执行时在 spinner 中显示的自定义消息。默认显示命令内容，但对于复杂命令或包含敏感信息的命令，自定义消息更友好。

6.3 Matcher 匹配器

Matcher 是 Hook 系统的路由机制——决定一个 Hook 是否应该响应某个事件。

配置格式

type HookMatcher = {
  matcher?: string,          // 匹配模式，不设置则匹配所有
  hooks: HookCommand[]       // 匹配时执行的 Hook 列表
}

配置示例：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "echo 'Bash tool used'" }]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "echo 'File modified'" }]
      }
    ]
  }
}

三种匹配模式

matchesPattern() 函数实现了三级匹配，按顺序尝试：

// src/utils/hooks.ts
function matchesPattern(matchQuery: string, matcher: string): boolean {
  if (!matcher || matcher === '*') return true

  // 1. 精确匹配或管道分隔（只含字母数字和 | 的视为简单模式）
  if (/^[a-zA-Z0-9_|]+$/.test(matcher)) {
    if (matcher.includes('|')) {
      // "Write|Edit|Read" → 分割后逐个精确匹配
      return patterns.includes(matchQuery)
    }
    // "Write" → 直接精确匹配
    return matchQuery === matcher
  }

  // 2. 正则表达式（包含任何特殊字符时）
  const regex = new RegExp(matcher)
  return regex.test(matchQuery)
}

三种模式的设计体现了渐进复杂度：

Matcher 与 if 条件的配合

Matcher 和 if 构成了两层过滤：

事件触发
  │
  ▼
Matcher 过滤：匹配工具名/事件类型（粗粒度）
  │ 不匹配 → 跳过，不 spawn 进程
  ▼
if 条件过滤：匹配工具的具体输入参数（细粒度）
  │ 不匹配 → 跳过，不 spawn 进程
  ▼
执行 Hook

举例：

{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    "command": "echo 'git command detected'",
    "if": "Bash(git push*)"
  }]
}

这个配置的匹配过程：

1. PreToolUse 事件触发，tool_name 是 "Bash" → matcher 匹配通过
2. 检查 if 条件："Bash(git push)" → 解析权限规则，检查工具输入的命令是否匹配 git push 模式
3. 如果用户执行的是 git push origin main → 匹配通过，执行 Hook
4. 如果用户执行的是 git status → 匹配失败，跳过

性能关键：两层过滤都在 spawn 子进程之前完成。如果一个 PreToolUse 事件触发了 10 个 Hook 配置，但只有 2 个通过了 matcher + if 的双重过滤，系统只会 spawn 2 个进程。这是"零成本抽象"——不触发的 Hook 完全没有运行时开销。

6.4 Hook 执行引擎

关键文件：src/utils/hooks.ts（核心调度）

Hook 执行经过 6 个阶段。下面逐一展开每个阶段的实现细节。

Stage 0：快速存在性检查

在进入完整的 Hook 流程之前，hasHookForEvent() 提供了一个轻量级的短路判断：

// src/utils/hooks.ts
function hasHookForEvent(hookEvent, appState, sessionId): boolean {
  const snap = getHooksConfigFromSnapshot()?.[hookEvent]
  if (snap && snap.length > 0) return true
  const reg = getRegisteredHooks()?.[hookEvent]
  if (reg && reg.length > 0) return true
  if (appState?.sessionHooks.get(sessionId)?.hooks[hookEvent]) return true
  return false
}

这个检查故意过度近似（over-approximates）：它不检查 matcher 是否匹配，不检查 managedOnly 策略——只要有任何配置存在就返回 true。假阳性只是多走一步完整匹配路径；假阴性则会跳过应执行的 Hook，所以宁可多查不可漏查。

这个优化的价值在于：绝大多数事件没有配置任何 Hook。一个没有配置 FileChanged Hook 的项目，每次文件变化事件都能在几微秒内短路返回，避免了 createBaseHookInput（需要路径拼接）和 getMatchingHooks（需要遍历配置）的开销。

Stage 1：信任检查

shouldSkipHookDueToTrust() 是安全底线——所有 Hook 都需要工作区信任：

// src/utils/hooks.ts
export function shouldSkipHookDueToTrust(): boolean {
  const isInteractive = !getIsNonInteractiveSession()
  if (!isInteractive) return false  // SDK 模式下信任隐式成立
  const hasTrust = checkHasTrustDialogAccepted()
  return !hasTrust  // true = 跳过 Hook
}

为什么如此严格？ Hooks 从 .claude/settings.json 读取配置并执行任意命令。如果不检查信任，恶意仓库可以通过在 .claude/settings.json 中注入 Hook 来执行代码——用户只要 clone 并打开仓库，Hook 就会自动运行。

历史漏洞驱动了这个设计：

1. SessionEnd Hook 泄露：用户 clone 恶意仓库 → 打开 Claude Code → 看到信任对话框 → 点击拒绝 → 退出。但 SessionEnd Hook 在退出时执行，不检查信任——恶意 Hook 仍然运行。
2. SubagentStop Hook 提前执行：子 Agent 在信任对话框弹出前就完成了 → SubagentStop 事件触发 → Hook 在未经信任的工作区中执行。

修复方案很简单但有效：在 executeHooks 的最开头统一检查信任，所有 Hook（无一例外）都必须在工作区信任建立后才能执行。源码注释说得很直白：

"This centralized check prevents RCE vulnerabilities for all current and future hooks"

Stage 2：Matcher 匹配与 Hook 收集

getMatchingHooks() 是整个引擎中逻辑最复杂的函数。它需要：

1. 收集所有来源的 Hook 配置：快照配置 + 注册的 SDK/插件 Hook + 会话 Hook + 函数 Hook
2. 根据事件类型确定 matchQuery：通过 switch 语句从 hookInput 中提取匹配值
3. Matcher 匹配过滤：对每个 HookMatcher，检查 matcher 是否匹配 matchQuery
4. if 条件过滤：使用 prepareIfConditionMatcher 生成匹配闭包，逐个检查
5. 特殊限制：HTTP Hook 在 SessionStart/Setup 事件中被过滤掉

matchQuery 的提取逻辑（源码 getMatchingHooks 中的 switch）：

switch (hookInput.hook_event_name) {
  case 'PreToolUse':
  case 'PostToolUse':
  case 'PostToolUseFailure':
  case 'PermissionRequest':
  case 'PermissionDenied':
    matchQuery = hookInput.tool_name        // 工具名
    break
  case 'SessionStart':
    matchQuery = hookInput.source           // "startup" | "resume" | "clear" | "compact"
    break
  case 'Setup':
    matchQuery = hookInput.trigger          // "init" | "maintenance"
    break
  case 'Notification':
    matchQuery = hookInput.notification_type // 通知类型
    break
  case 'SubagentStart':
  case 'SubagentStop':
    matchQuery = hookInput.agent_type       // Agent 类型
    break
  case 'FileChanged':
    matchQuery = basename(hookInput.file_path) // 文件名（不含路径）
    break
  // ...
}

注意 FileChanged 用的是 basename——只匹配文件名，不匹配路径。这意味着 matcher: ".env" 会匹配任何目录下的 .env 文件。

Stage 3：Hook 去重

当 Hook 配置在多个来源中重复出现时（比如用户设置和项目设置都定义了同一条 Hook），去重机制确保不会重复执行。

// src/utils/hooks.ts
function hookDedupKey(m: MatchedHook, payload: string): string {
  return `${m.pluginRoot ?? m.skillRoot ?? ''}\0${payload}`
}

去重的核心设计：

• 同源 Hook 去重：来自 settings 的 Hook（无 pluginRoot/skillRoot）共享空字符串前缀，相同命令只保留最后合并的那个
• 跨源 Hook 不去重：插件 A 和插件 B 可能都有 ${CLAUDE_PLUGIN_ROOT}/hook.sh，展开后指向不同文件。去重 key 包含 pluginRoot，确保它们不会被错误地合并
• 不同 if 条件不去重：即使命令相同，if 条件不同也是不同的 Hook

Last-wins 语义：new Map(entries) 在 key 冲突时保留最后一个 entry。对于 settings Hook，这意味着后合并的配置（如项目设置）覆盖先合并的（如用户设置）。

Callback 和 Function Hook 跳过去重——每个回调函数都是唯一的，去重没有意义。

Stage 4：输入构建与并行执行

输入构建：createBaseHookInput() 构建所有 Hook 共用的基础输入：

{
  session_id: string,       // 会话 ID
  transcript_path: string,  // 对话记录文件路径
  cwd: string,              // 当前工作目录
  permission_mode?: string, // 权限模式
  agent_id?: string,        // 子 Agent ID
  agent_type?: string       // Agent 类型
}

agent_type 有一个值得注意的优先级逻辑：子 Agent 的类型（来自 toolUseContext）优先于主线程的 --agent 标志。这样 Hook 可以通过 agent_id 是否存在来区分"主 Agent 的工具调用"和"子 Agent 的工具调用"。

JSON 输入的惰性序列化：Hook 输入只序列化一次，通过闭包共享给同一批次的所有 Hook：

let jsonInputResult: { ok: true; value: string } | { ok: false; error: unknown } | undefined
function getJsonInput() {
  if (jsonInputResult !== undefined) return jsonInputResult
  try {
    return (jsonInputResult = { ok: true, value: jsonStringify(hookInput) })
  } catch (error) {
    return (jsonInputResult = { ok: false, error })
  }
}

如果一个事件触发了 5 个 Command Hook，hookInput 只被 jsonStringify 一次。

并行执行：所有匹配的 Hook 通过 hookPromises.map(async function* ...) 并行启动，用 all() 等待所有结果。这意味着 5 个 Hook 的执行时间取决于最慢的那个，而不是 5 个的总和。每个 Hook 有独立的超时控制（createCombinedAbortSignal 合并了父级 signal 和 Hook 自己的超时）。

三种执行模式：

同步模式（默认）：等待进程退出，收集 stdout/stderr，解析输出。虽然多个 Hook 之间是并行的，但每个 Hook 自身是同步等待结果的。

异步模式（async: true）：Hook 进程在后台运行，通过 registerPendingAsyncHook() 注册到全局的 AsyncHookRegistry，立即返回 success。Agent Loop 在每轮循环中调用 checkForAsyncHookResponses() 轮询已完成的异步 Hook，将结果注入对话。默认超时 15 秒（可通过 asyncTimeout 覆盖）。

异步唤醒模式（asyncRewake: true）：最特殊的模式，专为"后台检查 + 按需中断"场景设计：

// src/utils/hooks.ts - executeInBackground()
if (asyncRewake) {
  // asyncRewake hooks 绕过 AsyncHookRegistry
  void shellCommand.result.then(async result => {
    if (result.code === 2) {
      // 退出码 2 = 阻塞错误 → 通过 notification 唤醒模型
      enqueuePendingNotification({
        value: wrapInSystemReminder(
          `Stop hook blocking error from command "${hookName}": ${stderr || stdout}`
        ),
        mode: 'task-notification',
      })
    }
  })
}

工作流程：

1. Hook 进程在后台运行，不阻塞当前操作
2. 退出码 0 → 静默成功，不打扰模型
3. 退出码 2 → 阻塞性错误，通过 enqueuePendingNotification 注入 唤醒模型
4. 模型在下一轮看到这个错误后可以做出响应（如修复失败的测试）

为什么退出码 2 而不是 1？ 这是一个精心设计的约定：0 = 成功，1 = 一般错误（用户可见但不打扰模型），2 = 需要模型关注的阻塞性错误。这让长时间运行的检查（如 CI 构建、集成测试）只在真正发现问题时才中断模型的工作流。

一个重要的实现细节：asyncRewake Hook 故意不调用 shellCommand.background()——因为 background() 会触发 taskOutput.spillToDisk()，将输出写入磁盘文件。但后续需要通过 getStdout() 和 getStderr() 读取内存中的输出来构建通知消息，spillToDisk() 会导致 stderr 从内存中清除（返回空字符串）。

Stage 5：输出解析与退出码语义

Hook 的输出协议由两部分组成：退出码和 stdout 内容。

退出码语义

对于非 JSON 输出的 Command Hook，退出码是唯一的通信渠道：

退出码 1 和 2 的关键区别值得强调：退出码 1 只是"告诉用户出了点问题"（non-blocking），模型不知道也不关心；退出码 2 是"告诉模型这里有问题，必须处理"（blocking），会阻止当前工具的执行或模型的停止。

这个区分非常实用：

• Linter 警告用退出码 1 → 用户看到但不打断工作流
• 安全检查失败用退出码 2 → 模型必须知道并处理

stdout 解析

parseHookOutput() 对 stdout 进行智能解析：

function parseHookOutput(stdout: string) {
  const trimmed = stdout.trim()
  // 不以 '{' 开头 → 纯文本，不尝试 JSON 解析
  if (!trimmed.startsWith('{')) {
    return { plainText: stdout }
  }
  // 以 '{' 开头 → 尝试 JSON 解析 + Zod schema 验证
  try {
    const result = validateHookJson(trimmed)
    if ('json' in result) return result
    // 验证失败 → 返回 plainText + validationError（包含期望的 schema）
    return { plainText: stdout, validationError: result.validationError }
  } catch {
    return { plainText: stdout }
  }
}

设计要点：

1. 以 { 开头才尝试 JSON 解析——简单的 echo "done" 不会被误解析
2. JSON 解析后还要经过 Zod schema 验证——确保字段名和类型都正确
3. 验证失败时的 schema 提示：当 JSON 格式不对时，错误信息中直接展示期望的完整 schema。这是很好的 DX（开发者体验）——Hook 作者不需要查文档就能看到正确的格式应该是什么样的

HTTP Hook 的解析（parseHttpHookOutput）略有不同：空 body 被视为空对象 {}（成功），非空内容必须是有效 JSON。

Stage 6：结果聚合与事件发射

多个并行 Hook 的结果通过 AggregatedHookResult 合并：

type AggregatedHookResult = {
  blockingError?: HookBlockingError      // 阻塞错误
  preventContinuation?: boolean          // 是否阻止继续
  stopReason?: string                    // 停止原因
  permissionBehavior?: 'allow' | 'deny' | 'ask' | 'passthrough'
  additionalContexts?: string[]          // 额外上下文（可来自多个 Hook）
  updatedInput?: Record<string, unknown> // 修改后的工具输入
  updatedMCPToolOutput?: unknown         // 修改后的 MCP 输出
  // ...
}

聚合是通过 for await ... of all(hookPromises) 流式进行的——每个 Hook 完成就立即 yield 结果，不等所有 Hook 完成。这意味着一个 Hook 的阻塞错误可以立即传播，而不必等待其他更慢的 Hook。

事件发射用于 UI 更新和可观测性：

• emitHookStarted()：Hook 开始执行时（用于 spinner 显示）
• emitHookResponse()：Hook 完成时（包含 stdout/stderr/exitCode/outcome）
• startHookProgressInterval()：长时间运行的 Hook 定期发射进度更新（用于在远程模式下推送实时输出）

超时配置

SessionEnd 超时极短（1.5 秒），因为用户正在退出，不应被 Hook 阻塞。可通过环境变量 CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 覆盖。

6.5 Hook JSON Output Schema

Hook 通过 stdout 输出 JSON 来控制 Claude Code 的行为。完整 schema 定义在 src/types/hooks.ts 中，使用 Zod 验证。

通用字段

{
  // === 流程控制 ===
  continue?: boolean,          // false → 阻止 Claude 继续（preventContinuation）
  suppressOutput?: boolean,    // 隐藏 stdout 输出（不记入 transcript）
  stopReason?: string,         // continue=false 时的停止原因消息

  // === 决策字段（向后兼容） ===
  decision?: 'approve' | 'block',  // approve → 允许, block → 阻止 + 错误
  reason?: string,                  // 决策原因

  // === 反馈 ===
  systemMessage?: string,      // 警告消息（显示给用户）
}

事件特定输出（hookSpecificOutput）

hookSpecificOutput 是一个 discriminated union，通过 hookEventName 字段区分不同事件的输出格式：

PreToolUse——最丰富的输出，可以控制权限、修改输入、注入上下文：

{
  hookEventName: 'PreToolUse',
  permissionDecision?: 'allow' | 'deny' | 'ask',  // 权限决策
  permissionDecisionReason?: string,               // 决策原因
  updatedInput?: Record<string, unknown>,           // 修改工具输入
  additionalContext?: string                        // 附加上下文
}

PermissionRequest——结构与 PreToolUse 不同，使用嵌套的 decision 对象：

{
  hookEventName: 'PermissionRequest',
  decision: {
    behavior: 'allow',
    updatedInput?: Record<string, unknown>,          // 修改输入
    updatedPermissions?: PermissionUpdate[]          // 注入新权限规则
  } | {
    behavior: 'deny',
    message?: string,                                // 拒绝原因
    interrupt?: boolean                              // 中断操作
  }
}

PostToolUse——可以注入上下文或替换 MCP 工具输出：

{
  hookEventName: 'PostToolUse',
  additionalContext?: string,
  updatedMCPToolOutput?: unknown   // 替换 MCP 工具的原始输出
}

SessionStart——可以设置初始消息和文件监听：

{
  hookEventName: 'SessionStart',
  additionalContext?: string,
  initialUserMessage?: string,     // 自动注入的初始用户消息
  watchPaths?: string[]            // 注册 FileChanged 监听路径
}

UserPromptSubmit / Setup / SubagentStart / PostToolUseFailure / Notification——只有 additionalContext：

{ hookEventName: '...', additionalContext?: string }

PermissionDenied——可以触发重试：

{ hookEventName: 'PermissionDenied', retry?: boolean }

Elicitation / ElicitationResult——MCP 交互响应：

{
  hookEventName: 'Elicitation',
  action?: 'accept' | 'decline' | 'cancel',
  content?: Record<string, unknown>
}

异步响应——Hook 也可以返回异步声明，表示结果稍后到达：

{ async: true, asyncTimeout?: number }

常用字段组合速查

数据流跟踪示例

以一个 PreToolUse Hook 拒绝 rm -rf 命令为例，跟踪完整的数据流：

1. 模型调用 Bash 工具，command = "rm -rf /tmp/data"
   │
2. Agent Loop 触发 PreToolUse 事件
   │
3. executePreToolHooks() 构建 hookInput：
   {
     hook_event_name: "PreToolUse",
     tool_name: "Bash",
     tool_input: { command: "rm -rf /tmp/data" },
     session_id: "abc-123",
     cwd: "/home/user/project",
     ...
   }
   │
4. getMatchingHooks() 查找匹配的 Hook
   ├── matcher: "Bash" → 匹配 tool_name "Bash" ✓
   └── if: "Bash(rm *)" → preparePermissionMatcher("rm -rf /tmp/data") → 匹配 "rm *" ✓
   │
5. execCommandHook() 执行 Hook 命令
   ├── spawn("bash", ["-c", "echo '{...}'"])
   ├── stdin 写入 JSON 输入
   └── 等待退出
   │
6. Hook 脚本 stdout 返回：
   {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny",
    "permissionDecisionReason": "rm -rf 命令被安全策略禁止"}}
   │
7. parseHookOutput() → 以 '{' 开头 → JSON 解析 → Zod 验证通过
   │
8. processHookJSONOutput() 处理 JSON：
   ├── hookSpecificOutput.hookEventName === "PreToolUse" ✓
   ├── permissionDecision === "deny"
   ├── result.permissionBehavior = 'deny'
   └── result.blockingError = { blockingError: "rm -rf 命令被安全策略禁止", command: "..." }
   │
9. 工具执行被阻止，模型收到错误消息：
   "PreToolUse:Bash hook error: rm -rf 命令被安全策略禁止"

6.6 信任模型与安全

Hook 配置快照

captureHooksConfigSnapshot() 在启动时冻结 Hook 配置。这意味着：

1. Hook 定义在整个会话期间不变
2. 即使 .claude/settings.json 在会话中被修改（比如被恶意代码修改），Hook 不会动态更新
3. 配置变更时 updateHooksConfigSnapshot() 会重新捕获，但只在受控的场景中触发

三层来源与策略控制

getHooksFromAllowedSources() 从三个来源合并 Hook 配置：

三种策略模式的设计对应不同的企业安全需求：

allowManagedHooksOnly 的影响范围很广——它不仅阻止用户设置和项目设置的 Hook，还阻止插件 Hook（pluginRoot 存在时跳过）和会话 Hook（包括 Agent/Skill frontmatter 中的 Hook）。但它不阻止 SDK 注册的 callback Hook（这些是运行时内部机制，不是用户配置）。

6.7 PermissionRequest Hook 深度解析

这是最强大的 Hook 类型——可以程序化地控制工具权限，在权限系统章节中参与竞速机制。

输入

{
  hook_event_name: 'PermissionRequest',
  tool_name: string,                    // 工具名称
  tool_input: Record<string, unknown>,  // 工具输入参数
  session_id: string,
  cwd: string,
  permission_mode: string
}

输出

PermissionRequest 的 hookSpecificOutput 使用嵌套的 decision 对象，与 PreToolUse 的 permissionDecision 字段不同：

{
  hookSpecificOutput: {
    hookEventName: 'PermissionRequest',
    decision: {
      // 允许 → 可以同时修改输入和注入权限规则
      behavior: 'allow',
      updatedInput?: Record<string, unknown>,
      updatedPermissions?: PermissionUpdate[]
    } | {
      // 拒绝 → 可以附带消息和中断标志
      behavior: 'deny',
      message?: string,
      interrupt?: boolean
    }
  }
}

四种能力

PermissionRequest Hook 远不止简单的 allow/deny：

1. 审批决策：behavior: 'allow' 或 'deny'
2. 输入修改：通过 updatedInput 修改工具的输入参数（如强制添加 --dry-run 标志）
3. 规则注入：通过 updatedPermissions 动态持久化新的权限规则——不只是本次生效，而是在整个会话中持续生效
4. 操作中断：interrupt: true 立即中断当前操作

与权限系统的竞速

PermissionRequest Hook 参与权限系统的竞速机制——与 UI 确认对话框和 ML 分类器同时运行，先完成的获胜。

6.8 Stop Hook：采样后验证

Stop Hook 在模型决定停止循环时触发（即模型返回纯文本而非工具调用时），可以阻止终止并强制继续：

模型返回纯文本（无工具调用）
    │
    ▼
Stop Hook 触发
    │
    ├── 返回 allow / 无阻塞错误 → 正常终止
    └── 返回 deny / 退出码 2 →
        注入 blockingError.blockingError 到对话
        transition = stop_hook_blocking
        继续 Agent Loop

这使得自动化工作流可以实现"做完了才能停"的语义。例如：

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "if ! npm test --silent 2>/dev/null; then echo 'Tests failed' >&2; exit 2; fi"
      }]
    }]
  }
}

每次模型准备停止时，自动运行测试。测试通过 → 允许停止；测试失败 → 退出码 2 → 模型收到"Tests failed"消息 → 被迫继续修复。

6.9 实战模式

模式 1：CI 构建检查（asyncRewake）

场景：每次编辑文件后自动运行测试，但不阻塞编辑工作流，只在测试失败时提醒模型。

为什么选择 asyncRewake？ 测试可能需要几十秒。如果用同步 Hook，模型每编辑一个文件就要等几十秒。asyncRewake 让测试在后台运行，模型继续编辑其他文件，只在测试失败时才被中断。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "npm test 2>&1; if [ $? -ne 0 ]; then exit 2; else exit 0; fi",
        "asyncRewake": true
      }]
    }]
  }
}

工作流程：每次文件编辑后，后台自动运行测试。测试通过（退出码 0）→ 静默。测试失败（退出码 2）→ 唤醒模型并注入错误信息，模型自动修复。

模式 2：上下文注入（additionalContext）

场景：每次用户提交输入时，自动运行 linter 并将结果注入为额外上下文。

为什么选择 UserPromptSubmit + additionalContext？ 这让模型在开始工作前就知道现有的 lint 问题，可以在修改时顺手修复。

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "result=$(npx eslint --format=compact src/ 2>&1); if [ -n \"$result\" ]; then echo \"{\\\"hookSpecificOutput\\\": {\\\"hookEventName\\\": \\\"UserPromptSubmit\\\", \\\"additionalContext\\\": \\\"Current lint warnings:\\n$result\\\"}}\"; fi"
      }]
    }]
  }
}

模式 3：团队审计日志（HTTP Hook）

场景：将所有工具使用记录发送到公司审计系统。

为什么选择 HTTP Hook？ 审计系统通常是 REST API。Command Hook 需要额外安装 curl 并处理认证，HTTP Hook 原生支持 header 和环境变量插值。

{
  "hooks": {
    "PreToolUse": [{
      "hooks": [{
        "type": "http",
        "url": "https://audit.company.com/claude-code/tool-use",
        "headers": { "Authorization": "Bearer ${AUDIT_TOKEN}" },
        "allowedEnvVars": ["AUDIT_TOKEN"]
      }]
    }]
  }
}

安全提示：allowedEnvVars 明确声明允许插值的环境变量。未列出的变量引用（如 $HOME）会被替换为空字符串，防止意外暴露敏感信息。

模式 4：LLM 安全评估（Prompt Hook）

场景：在执行 Bash 命令前，用 LLM 评估命令是否安全。

为什么选择 Prompt Hook？ 简单的模式匹配（如 rm *）无法覆盖所有危险命令。LLM 可以理解命令的语义，识别 find / -delete、dd if=/dev/zero of=/dev/sda 等非典型但危险的命令。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Evaluate whether the following bash command is safe to execute in a development environment. The command details are: $ARGUMENTS. Consider: Does it modify system files? Does it delete data irreversibly? Does it access network resources unexpectedly?",
        "timeout": 15
      }]
    }]
  }
}

模式 5：PermissionRequest 自动审批

场景：自动批准已知安全的命令模式，减少用户确认弹窗。

{
  "hooks": {
    "PermissionRequest": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'",
        "if": "Bash(npm test*)"
      }]
    }]
  }
}

模式 6：输入改写（updatedInput）

场景：强制危险命令使用安全模式。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "input=$(cat); cmd=$(echo $input | jq -r '.tool_input.command'); echo \"{\\\"hookSpecificOutput\\\": {\\\"hookEventName\\\": \\\"PreToolUse\\\", \\\"permissionDecision\\\": \\\"allow\\\", \\\"updatedInput\\\": {\\\"command\\\": \\\"$cmd --dry-run\\\"}}}\"",
        "if": "Bash(rm *)"
      }]
    }]
  }
}

6.10 Hook 与技能/插件的协作

技能级 Hook

技能可以在 frontmatter 中定义自己的 Hook，在技能执行期间生效。这创建了层级扩展：

全局 Hook（settings.json）── 始终生效
  └── 技能级 Hook（技能 frontmatter）── 仅在该技能执行时生效
        └── 插件级 Hook（plugins/*/hooks/hooks.json）── 插件启用时生效

例如，一个部署技能可以定义 PreToolUse Hook 来限制可执行的命令：

# .claude/skills/deploy.md
---
name: deploy
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"deny\", \"permissionDecisionReason\": \"rm 命令在部署过程中被禁止\"}}'"
          if: "Bash(rm *)"
---

技能级 Hook 通过 parseHooksFromFrontmatter() 解析，使用与全局 Hook 完全相同的 HooksSchema 验证。会话 Hook 按 sessionId 隔离，确保一个 Agent 的 Hook 不会泄漏到另一个 Agent。

插件 Hook 的变量替换

插件 Hook 的命令中可以使用特殊占位符：

• ${CLAUDE_PLUGIN_ROOT} → 插件安装目录
• ${CLAUDE_PLUGIN_DATA} → 插件数据目录
• ${user_config.keyName} → 用户在插件配置中设置的选项值

执行时，这些变量会被替换为实际路径，并作为环境变量注入子进程。

Hook 去重机制

当同一个 Hook 命令出现在多个配置源中时（例如用户设置和项目设置都定义了 echo 'hello'），去重机制确保只执行一次。

去重的命名空间设计值得关注：

function hookDedupKey(m: MatchedHook, payload: string): string {
  return `${m.pluginRoot ?? m.skillRoot ?? ''}\0${payload}`
}

• Settings Hook（无 pluginRoot/skillRoot）→ 前缀是空字符串 → 用户/项目/本地设置中的相同命令会合并
• 插件 Hook → 前缀是 pluginRoot → 不同插件的相同模板命令（如 ${CLAUDE_PLUGIN_ROOT}/hook.sh）不会合并（因为展开后是不同文件）
• 技能 Hook → 前缀是 skillRoot → 同理

new Map(entries) 对于重复 key 保留最后一个 entry（last-wins），对于 settings Hook 这意味着后合并的配置覆盖先合并的。

6.11 设计洞察

1. 事件驱动 + 双层匹配 = 精确控制

25 种事件 × matcher（粗粒度） × if 条件（细粒度），覆盖几乎所有扩展需求。不匹配的 Hook 在 spawn 进程之前就被过滤——这是真正的零成本抽象。

2. 退出码是最核心的通信协议

0/1/2 三个退出码的区分看似简单，实则精妙。它将信息传递划分为三个级别：静默成功（0）、告知用户（1）、要求模型处理（2）。这让 Hook 作者不需要学习复杂的 JSON 协议就能控制基本行为——exit 2 比构建 JSON 对象简单得多。

3. 异步唤醒是创新设计

传统的 Hook 系统要么同步阻塞（慢），要么异步 fire-and-forget（无反馈）。asyncRewake 是第三种模式——后台运行 + 按需中断，退出码 2 的约定让长时间运行的检查只在失败时中断模型，完美平衡了性能和反馈。

4. 多层性能优化

Hook 系统在热路径上有三层优化：

• hasHookForEvent：大多数事件无 Hook 配置，快速短路返回
• matcher/if 前置过滤：不匹配的 Hook 不 spawn 进程
• Callback 快速路径：全 callback 时跳过 JSON 序列化和进度事件（-70% 开销），因为内部 Hook（文件访问跟踪、commit 归因）在每次工具调用时都触发

5. 安全设计遵循"全或无"原则

历史漏洞证明"大部分 Hook 需要信任"不够，必须是"所有 Hook 都需要信任"。配置快照、信任检查、环境变量白名单、CRLF 注入防护——每一层都假设攻击者可以控制前一层的输入。

6. Hook 是 Agent Loop 的横切关注点

Hook 系统本质上是 Agent Loop 的 AOP（面向切面编程）层。它不修改核心循环的任何逻辑，而是在关键节点注入横切逻辑。这使得核心循环保持简洁，扩展能力通过 Hook 系统实现。从架构上看，Hook 系统是连接 Claude Code 内部机制和外部生态（企业基础设施、CI/CD、安全策略）的桥梁。

第 7 章：多 Agent 架构

从单个 Agent 到 Agent 团队——Claude Code 如何协调多个 Agent 并行完成复杂任务。

7.1 三种多 Agent 模式

Claude Code 支持三种多 Agent 协作模式，适用于不同复杂度的场景：

这三种模式的复杂度递增，但共享同一套底层基础设施——AgentTool 工具、ToolUseContext 上下文隔离和 结果通知。理解子 Agent 模式是理解后两种模式的基础。

7.2 子 Agent 模式（AgentTool）

这是最基础的多 Agent 模式。父 Agent 通过 AgentTool 派生子 Agent 执行独立任务。

关键文件：src/tools/AgentTool/AgentTool.tsx

完整参数解析

{
  description: string,           // 3-5 词任务描述（必填）
  prompt: string,                // 完整任务指令（必填）— Worker 从零开始，无对话上下文
  subagent_type?: string,        // 专用 Agent 类型
  model?: 'sonnet' | 'opus' | 'haiku',  // 模型覆盖
  run_in_background?: boolean,   // 异步执行，结果通过 <task-notification> 通知
  name?: string,                 // 可寻址名称（用于 SendMessage）
  isolation?: 'worktree' | 'remote'  // 隔离模式
}

关键设计：prompt 必须是自包含的——Worker 无法看到父 Agent 的对话历史。这意味着每个 prompt 都需要包含完成任务所需的全部信息：文件路径、行号、具体的修改内容。

为什么采用这种"无上下文"设计而非共享对话历史？原因有三：

1. 隔离性：子 Agent 不会被父 Agent 对话中无关的信息干扰，上下文更加聚焦
2. 成本控制：共享完整对话历史会大幅增加每次 API 调用的 token 消耗
3. 并行安全：多个子 Agent 并行运行时，如果共享可变的对话历史会引发竞态条件

唯一的例外是 Fork 子 Agent（后文详述），它通过精巧的缓存机制在继承完整上下文的同时保持了经济性。

子 Agent 类型系统

subagent_type 决定了 Worker 的工具集、系统提示词和行为约束。Claude Code 源码中定义了三层 Agent 类型：

第一层：内建类型（src/tools/AgentTool/built-in/）

这些类型由 Claude Code 核心代码定义，经过精心优化：

第二层：自定义类型（.claude/agents/*.md）

用户通过 Markdown frontmatter 定义，支持所有 BaseAgentDefinition 字段。例如：

---
description: "Database migration specialist"
tools: ["Bash", "Read", "Edit"]
model: "sonnet"
permissionMode: "plan"
---
You are a database migration expert...

第三层：插件类型

通过插件系统注入，具有 source: 'plugin' 标识。

Explore Agent 深度分析

Explore Agent 的设计体现了多个精细的工程取舍（src/tools/AgentTool/built-in/exploreAgent.ts）：

系统提示词的"READ-ONLY"硬约束：提示词开头就用 === CRITICAL: READ-ONLY MODE === 显式声明禁止列表（不能创建/修改/删除文件、不能用重定向写文件、不能运行改变系统状态的命令）。虽然 disallowedTools 已经在工具层面阻止了写入工具，但系统提示词的重复声明是为了在模型层面增加一道安全屏障——模型不会尝试通过 Bash 工具间接写文件。

Haiku 模型选择：外部用户使用 Haiku（速度优先），内部用户继承父级模型。这个选择基于 Explore 的任务特性——搜索和读取文件不需要强推理能力，速度更重要。源码中的注释解释了这一点：

// Ants get inherit to use the main agent's model; external users get haiku for speed
model: process.env.USER_TYPE === 'ant' ? 'inherit' : 'haiku',

omitClaudeMd: true 的成本优化：Explore Agent 不需要知道项目的 commit 规范、PR 模板等 CLAUDE.md 中的规则——它只读代码，由父 Agent 解读结果。源码注释揭示了这个优化的规模：

// Explore is a fast read-only search agent — it doesn't need commit/PR/lint
// rules from CLAUDE.md. The main agent has full context and interprets results.
omitClaudeMd: true,

在 34M+ 次 Explore 调用/周的规模下，省略 CLAUDE.md 可节省约 5-15 Gtok/周。

并行工具调用的速度提示：系统提示词末尾特别强调"尽可能并行调用多个工具进行搜索和文件读取"——这是利用 API 的并行工具调用能力来加速搜索。

Plan Agent 深度分析

Plan Agent（src/tools/AgentTool/built-in/planAgent.ts）与 Explore 共享只读工具限制，但有不同的设计目标：

结构化输出要求：系统提示词要求 Plan Agent 在输出末尾必须包含"Critical Files for Implementation"列表（3-5 个文件）。这不是可选建议——它确保规划结果是可操作的，父 Agent 能根据这些关键文件路径开始执行。

继承父级模型：与 Explore 使用 Haiku 不同，Plan 使用 model: 'inherit'，因为架构设计和方案规划需要更强的推理能力。

工具列表复用：tools: EXPLORE_AGENT.tools——Plan 直接引用 Explore 的工具定义，确保两者保持一致。

General-purpose Agent 设计哲学

General-purpose Agent（src/tools/AgentTool/built-in/generalPurposeAgent.ts）的设计哲学是"最小约束"：

const SHARED_PREFIX = `You are an agent for Claude Code... Complete the task
  fully—don't gold-plate, but don't leave it half-done.`

• tools: ['*'] 赋予全部工具能力
• 不设置 omitClaudeMd——因为通用 Agent 可能需要遵守项目的 commit 规范等规则
• 不指定 model——使用 getDefaultSubagentModel() 获取默认子 Agent 模型
• 系统提示词简洁：只要求"完成任务，简洁汇报"

为什么限制工具集？ 不同任务有不同的安全需求。Explore Agent 只需要读取代码，赋予它写入能力是不必要的风险。类型系统实现了最小权限原则。

AgentTool 调用完整流程

当模型发出一次 Agent 工具调用时，系统经历以下 5 个阶段。理解这个流程有助于理解为什么子 Agent 能做到既隔离又高效。

阶段 1：类型解析

类型解析的核心逻辑在 AgentTool.tsx:318-356：

// Fork subagent experiment routing:
// - subagent_type set: use it (explicit wins)
// - subagent_type omitted, gate on: fork path (undefined)
// - subagent_type omitted, gate off: default general-purpose
const effectiveType = subagent_type
  ?? (isForkSubagentEnabled() ? undefined : GENERAL_PURPOSE_AGENT.agentType);
const isForkPath = effectiveType === undefined;

这段代码的决策逻辑很巧妙：

• 显式指定类型：直接使用，不猜测——"explicit wins"
• 省略类型 + fork 实验开启：走 fork 路径（继承完整上下文）
• 省略类型 + fork 实验关闭：回退到 general-purpose

如果指定了类型，系统从 agentDefinitions.activeAgents 列表中查找匹配的 AgentDefinition。找不到时，会区分"不存在"和"被权限拒绝"两种情况，给出不同的错误提示——这对用户调试很有帮助。

阶段 2：工具池组装

子 Agent 的工具池独立于父级构建，这是一个关键的隔离设计（AgentTool.tsx:568-577）：

// Assemble the worker's tool pool independently of the parent's.
// Workers always get their tools from assembleToolPool with their own
// permission mode, so they aren't affected by the parent's tool restrictions.
const workerPermissionContext = {
  ...appState.toolPermissionContext,
  mode: selectedAgent.permissionMode ?? 'acceptEdits'
};
const workerTools = assembleToolPool(workerPermissionContext, appState.mcp.tools);

注意 permissionMode 默认是 'acceptEdits'——这意味着子 Agent 默认情况下可以自动执行编辑操作，无需逐个确认。这是合理的，因为子 Agent 已经由父 Agent 委托了明确的任务。

工具池组装后，还要经过 filterToolsForAgent() 的多层过滤（详见下文"工具过滤流水线"）。

阶段 3：系统提示词构建

普通子 Agent 和 Fork 子 Agent 的提示词构建路径完全不同（AgentTool.tsx:483-541）：

普通路径：

1. 调用 agent 定义的 getSystemPrompt() 函数获取基础提示词
2. 用 enhanceSystemPromptWithEnvDetails() 追加环境信息（绝对路径格式、平台信息等）
3. 用户的 prompt 作为一条独立的 user 消息发送

Fork 路径：

1. 直接使用父级已渲染的系统提示词字节（toolUseContext.renderedSystemPrompt），不重新计算
2. 用 buildForkedMessages() 构建消息序列（克隆父级 assistant 消息 + 占位 tool_result + 子级指令）

Fork 路径为什么不重新计算系统提示词？因为 GrowthBook（A/B 测试系统）的状态可能在父级 turn 开始和 fork 生成之间发生变化，重新计算会产生不同的字节序列，导致 Prompt Cache 失效。

阶段 4：上下文创建

createSubagentContext()（src/utils/forkedAgent.ts:345-462）是整个多 Agent 架构的安全基石。详见下文"上下文隔离深度解析"。

阶段 5：执行分支

执行模式的选择逻辑在 AgentTool.tsx:555-567：

const shouldRunAsync = (
  run_in_background === true ||
  selectedAgent.background === true ||
  isCoordinator ||      // 协调器模式下所有 Agent 都异步
  forceAsync ||         // fork 实验开启时所有 Agent 都异步
  assistantForceAsync   // 助手模式下强制异步
) && !isBackgroundTasksDisabled;

几个值得注意的设计：

• 协调器模式强制异步：因为协调器需要同时管理多个 Worker，同步执行会阻塞编排
• Fork 实验强制异步：统一使用 交互模型
• 进程内队友不能运行后台 Agent：生命周期绑定到父级，强制后台会导致孤儿进程

工具过滤流水线

子 Agent 的工具不是简单地"给什么用什么"——而是经过一条精心设计的四层过滤流水线。这条流水线实现了纵深防御：即使某一层有漏洞，其他层仍能拦截危险工具访问。

关键函数：filterToolsForAgent()（src/tools/AgentTool/agentToolUtils.ts:70-116）

第一层 ALL_AGENT_DISALLOWED_TOOLS：移除"元工具"——TaskOutput、EnterPlanMode、ExitPlanMode、AskUserQuestion、TaskStop 等。这些工具用于控制 Agent 的执行流程本身，子 Agent 不应该能进入 Plan 模式或向用户提问。

第二层 CUSTOM_AGENT_DISALLOWED_TOOLS：对用户自定义的 Agent（来自 .claude/agents/）施加额外限制。这是一个安全边界——用户定义的 Agent 类型不应该获得与内建类型相同的权限。

第三层 ASYNC_AGENT_ALLOWED_TOOLS（白名单模式）：异步 Agent 只能使用白名单中的工具（Read、Grep、Glob、Edit、Write、Bash、Skill、NotebookEdit 等）。为什么异步 Agent 需要更严格的限制？因为异步 Agent 在后台运行，无法展示交互式 UI（如权限确认弹窗），某些需要用户交互的工具必须被排除。

第三层的例外：

• MCP 工具（名称以 mcp__ 开头）始终放行——它们由用户配置的外部服务提供，用户对其安全性负责
• ExitPlanMode：当 permissionMode === 'plan' 时允许——进程内队友需要退出 Plan 模式的能力
• 进程内队友：获得额外的 Agent 工具（可以派生同步子 Agent）和任务协调工具（TaskCreate/TaskGet/TaskList/TaskUpdate/SendMessage）——这些工具使队友能够协调共享任务列表和互相通信

第四层：Agent 自身定义的 disallowedTools。例如 Explore Agent 显式排除 [Agent, ExitPlanMode, FileEdit, FileWrite, NotebookEdit]。

设计洞察：前三层是全局策略（所有 Agent 都受约束），第四层是类型级策略（特定类型的约束）。这种分层确保了即使有人编写了一个 disallowedTools: []（空禁止列表）的自定义 Agent，它仍然受前三层的保护。

上下文隔离深度解析

createSubagentContext()（src/utils/forkedAgent.ts:345-462）是多 Agent 架构的安全基石。它为每个子 Agent 创建一个隔离的 ToolUseContext，确保子 Agent 的行为不会影响父级。

核心设计原则是"默认隔离，显式共享"（deny by default）：所有可变状态默认是隔离的，如果需要共享必须通过 shareSetAppState、shareAbortController 等参数显式 opt-in。

逐项解析每个字段的隔离方式和设计原因：

readFileState：克隆

readFileState: cloneFileStateCache(
  overrides?.readFileState ?? parentContext.readFileState,
),

文件状态缓存记录了每个文件的最后读取时间和内容哈希。如果子 Agent 与父级共享同一个缓存，子 Agent 的文件读取会改变缓存状态，导致父级对文件新鲜度的判断出错。克隆确保子 Agent 的读取操作不会"污染"父级的缓存。

abortController：新建子控制器

const abortController = overrides?.abortController ??
  (overrides?.shareAbortController
    ? parentContext.abortController
    : createChildAbortController(parentContext.abortController))

createChildAbortController() 使用 WeakRef 创建一个链接到父级的子控制器。关键行为：

• 父级中断 → 子级也中断：通过事件监听器传播 abort 信号
• 子级中断 ≠ 父级中断：子级的 abort 只清理自己的监听器，不影响父级

这个单向传播是故障隔离的基础：一个子 Agent 的失败（被 abort）不会连锁影响父级或其他子 Agent。

getAppState：包装

getAppState: overrides?.shareAbortController
  ? parentContext.getAppState  // 交互式子 Agent 直接共享
  : () => {
      const state = parentContext.getAppState()
      return {
        ...state,
        toolPermissionContext: {
          ...state.toolPermissionContext,
          shouldAvoidPermissionPrompts: true,  // 关键！
        },
      }
    }

非交互式子 Agent（后台运行）的 getAppState 被包装为始终返回 shouldAvoidPermissionPrompts: true。这防止后台子 Agent 弹出权限确认对话框阻塞父级的终端——后台 Agent 没有地方显示 UI。

setAppState：默认 no-op

setAppState: overrides?.shareSetAppState
  ? parentContext.setAppState
  : () => {},  // 隔离：子 Agent 的状态变更不传播

子 Agent 的状态变更（如工具进度、响应长度）默认不会传播到父级 UI。这避免了多个并行子 Agent 同时更新 UI 导致的混乱。

setAppStateForTasks：始终共享

// Task registration/kill must always reach the root store, even when
// setAppState is a no-op — otherwise async agents' background bash tasks
// are never registered and never killed (PPID=1 zombie).
setAppStateForTasks:
  parentContext.setAppStateForTasks ?? parentContext.setAppState,

这是唯一一个即使 setAppState 是 no-op 也必须共享的回调。为什么？因为子 Agent 可能通过 Bash 工具启动后台进程。如果这些进程的注册信息到不了根 store，当子 Agent 结束时这些进程就成了僵尸进程——PPID=1，无人回收。

queryTracking：新 chainId + depth + 1

queryTracking: {
  chainId: randomUUID(),           // 每个子 Agent 一个新的链路 ID
  depth: (parentContext.queryTracking?.depth ?? -1) + 1,
}

这个字段有两个作用：

1. 防止无限递归：depth 递增使系统能够检测和限制 Agent 嵌套深度
2. 链路追踪：chainId 允许分析系统追踪 Agent 的家族谱系，用于性能分析和调试

contentReplacementState：克隆（非新建）

// Clone by default (not fresh): cache-sharing forks process parent
// messages containing parent tool_use_ids. A fresh state would see
// them as unseen and make divergent replacement decisions → wire
// prefix differs → cache miss.
contentReplacementState:
  overrides?.contentReplacementState ??
  (parentContext.contentReplacementState
    ? cloneContentReplacementState(parentContext.contentReplacementState)
    : undefined),

这个字段的处理方式特别精妙。它管理工具结果中的内容替换（如截断超长输出）。为什么用克隆而不是新建？因为 Fork 子 Agent 会处理包含父级 tool_use_id 的消息。如果用一个全新的状态，对同一个 tool_use_id 会做出不同的替换决策，导致 API 请求的字节序列不同——Prompt Cache 就失效了。克隆确保对已知 ID 做出相同的决策，维持缓存命中。

四种执行模式

同步模式是最简单的：父 Agent 阻塞等待子 Agent 完成，结果直接作为 tool_result 嵌入父级对话。适合快速的探索或搜索任务。

异步模式适合长时间运行的任务。registerAsyncAgent() 在 AppState.tasks 中注册任务状态，父 Agent 立即收到一个包含 agentId 和 outputFile 的响应，可以继续处理其他工作。任务完成时，enqueueAgentNotification() 将 XML 作为 user 角色消息投递到父级的下一轮对话中。

自动后台化：当同步 Agent 运行超过 120 秒（getAutoBackgroundMs()），系统自动将其转为后台任务，避免长时间阻塞父级：

function getAutoBackgroundMs(): number {
  if (isEnvTruthy(process.env.CLAUDE_AUTO_BACKGROUND_TASKS) ||
      getFeatureValue_CACHED_MAY_BE_STALE('tengu_auto_background_agents', false)) {
    return 120_000;
  }
  return 0;
}

隔离模式

Git Worktree 隔离：子 Agent 在独立的 Git Worktree 中工作，防止多个 Agent 同时修改同一文件：

主仓库 (main branch)
├── Agent A 在此工作
│
├── .git/worktrees/
│   ├── worktree-abc/     ← Agent B 的隔离副本
│   └── worktree-def/     ← Agent C 的隔离副本

Worktree 创建过程（src/utils/worktree.ts）：

1. Slug 验证：最长 64 字符，只允许字母数字和 ./-/_，禁止路径穿越（..、绝对路径）——这是安全边界，防止子 Agent 通过 slug 注入访问仓库外的文件
2. 创建：在 .claude/worktrees// 下创建，对大目录（如 node_modules）使用符号链接避免磁盘占用
3. 清理：任务完成后，如果 worktree 无任何文件变更（通过 git diff 检测），自动删除；有变更时返回路径和分支名，由用户决定是否合并

远程隔离：在远程 CCR（Cross-Continent Runtime）环境中执行，通过 WebSocket 流式传输消息，适用于需要完全隔离的沙盒环境。远程隔离始终以异步模式运行。

Fork 子 Agent

当 subagent_type 未指定且 FORK_SUBAGENT feature gate 启用时，系统创建 fork 子 Agent——一种特殊模式，继承父级完整对话上下文。

为什么需要 Fork？Prompt Cache 的经济学

Fork 机制的核心动机是 Prompt Cache 共享。理解这一点需要先理解 Anthropic API 的缓存机制：

API 按请求前缀（system prompt + tools + messages prefix）缓存。如果两个请求的前缀字节完全相同，第二个请求可以复用第一个的缓存，cache read token 比 input token 便宜 90%。

普通子 Agent 有自己的系统提示词和空的消息历史——它与父级的请求前缀完全不同，无法共享缓存。每次调用都是"冷启动"。

Fork 子 Agent 则不同：它继承父级的完整请求前缀（相同的系统提示词、相同的工具定义、相同的消息历史），只在末尾追加一条不同的指令。这意味着所有从同一个父级 fork 出来的子 Agent 都共享同一个缓存前缀——第一个 fork 是冷启动，后续的都是缓存命中。

源码中 CacheSafeParams 类型（forkedAgent.ts:57-68）明确了这个"字节级相同"的要求：

export type CacheSafeParams = {
  /** System prompt - must match parent for cache hits */
  systemPrompt: SystemPrompt
  /** User context - prepended to messages, affects cache */
  userContext: { [k: string]: string }
  /** System context - appended to system prompt, affects cache */
  systemContext: { [k: string]: string }
  /** Tool use context containing tools, model, and other options */
  toolUseContext: ToolUseContext
  /** Parent context messages for prompt cache sharing */
  forkContextMessages: Message[]
}

Fork 消息构建

buildForkedMessages()（forkSubagent.ts:107-169）是 fork 机制的核心——它构建一组消息，确保所有 fork 子级的请求前缀字节相同：

关键实现细节：

1. 克隆父级 assistant 消息：保留所有内容块（thinking、text、每个 tool_use），不修改——确保字节相同
2. 占位 tool_result：为每个 tool_use 生成一个 tool_result，文本统一为 "Fork started — processing in background"。为什么不用实际结果？因为实际结果各不相同，会破坏缓存前缀的一致性
3. Per-child directive：只有最后一个文本块是每个 fork 独有的——包含该 fork 需要执行的具体指令

递归 Fork 防护

Fork 子级的工具池中保留了 Agent 工具（为了缓存一致性——如果移除会改变工具定义的字节），但在运行时通过两道防线阻止递归 fork：

// 第一道：通过 querySource 检测（抗消息压缩）
if (toolUseContext.options.querySource === `agent:builtin:${FORK_AGENT.agentType}`)

// 第二道：扫描消息历史中的 FORK_BOILERPLATE_TAG（后备方案）
|| isInForkChild(toolUseContext.messages)

为什么需要两道？querySource 是在 context 的 options 中设置的，不受消息自动压缩（autocompact）的影响——这是首选方案。消息扫描是后备方案，覆盖 querySource 没有被正确传递的边缘情况。

Fork Agent 定义

export const FORK_AGENT = {
  agentType: 'fork',
  tools: ['*'],              // 全部工具，保持与父级缓存一致
  maxTurns: 200,
  model: 'inherit',          // 继承父级模型（上下文长度对等）
  permissionMode: 'bubble',  // 权限请求冒泡到父级终端
  getSystemPrompt: () => '', // 未使用——fork 直接使用父级已渲染的系统提示词
}

permissionMode: 'bubble' 是一个独特的权限模式——当 fork 子级需要权限确认时，请求会"冒泡"到父级的终端显示，而不是被静默拒绝。这是因为 fork 子级被设计为"父级的延伸"，它的操作在概念上仍然由用户控制。

getSystemPrompt: () => '' 看起来像一个 bug，但实际上是刻意设计——fork 路径从不调用这个函数，而是直接传入父级的 renderedSystemPrompt 字节。如果不小心调用了它（比如代码路径错误），空字符串会导致明显的异常，而不是一个微妙的缓存失效。

与协调器模式互斥：Fork 和协调器不能同时启用——协调器有自己的 Worker 委托机制，fork 的"继承完整上下文"设计与协调器的"Worker 从零开始"哲学相矛盾。

7.3 协调器模式（Coordinator）

协调器模式（Feature-gated: COORDINATOR_MODE）将主 Agent 转变为纯编排者——只负责分析任务、分配 Worker、综合结果，永远不直接操作文件。

关键文件：src/coordinator/coordinatorMode.ts

协调器角色定义

协调器的系统提示词由 getCoordinatorSystemPrompt() 生成，包含 6 个精心设计的部分：

协调器可用工具

协调器的工具集被严格限制——这是核心设计约束：

协调器不能使用 Bash、Edit、Read 等工具——这确保它只做编排，不做执行。内部工具（TeamCreate, TeamDelete, SendMessage, SyntheticOutput）从主线程中排除。

为什么协调器不能执行？ 这不仅仅是分工问题——如果协调器既做决策又做执行，它会倾向于"自己动手比委托更快"，从而退化为一个普通的单 Agent。工具集的硬限制强制它必须通过 Worker 完成所有实际操作，这保证了任务分配的客观性和并行化。

Worker 工具集

Worker 根据模式获得不同的工具：

// src/coordinator/coordinatorMode.ts
const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)
  ? [BASH_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_EDIT_TOOL_NAME]  // 简单模式
  : Array.from(ASYNC_AGENT_ALLOWED_TOOLS)                        // 完整模式
      .filter(name => !INTERNAL_WORKER_TOOLS.has(name))

• 简单模式（CLAUDE_CODE_SIMPLE）：Bash, Read, Edit
• 完整模式：ASYNC_AGENT_ALLOWED_TOOLS 中的所有工具（排除内部工具）
• MCP 工具自动可用
• 技能通过 SkillTool 委托

Worker 工具上下文注入

getCoordinatorUserContext() 做了一件看似简单但至关重要的事：它构建一个 workerToolsContext 字符串，注入到协调器的用户上下文中。这个字符串告诉协调器：

1. Worker 有哪些工具——协调器需要知道 Worker 的能力边界才能写出可行的 prompt（不会要求 Worker 使用它没有的工具）
2. 有哪些 MCP 服务器可用——如果连接了 Slack MCP，协调器就知道可以派 Worker 发消息
3. Scratchpad 目录路径——如果启用了 Scratchpad，协调器可以指导 Worker 在共享目录中写入发现

这是上下文工程在编排层面的体现——协调器不是在盲目委托，而是根据 Worker 的实际能力来制定可行的任务计划。

标准工作流

四个阶段的并发管理规则：

协调器提示词设计精要

getCoordinatorSystemPrompt() 中蕴含了多条经过实践验证的设计原则：

1. "Never write 'based on your findings'"

协调器必须自己理解研究结果，然后写出包含具体文件路径、行号和修改内容的实施指令。"Based on your findings" 是将理解能力委托给 Worker，违背了协调器的核心职责。

// 反模式 — 懒惰委托
Agent({ prompt: "Based on your findings, fix the auth bug" })

// 正确 — 综合后的具体指令
Agent({ prompt: "Fix the null pointer in src/auth/validate.ts:42.
  The user field on Session is undefined when sessions expire but
  the token remains cached. Add a null check before user.id access." })

为什么这条规则如此重要？因为它定义了协调器的不可委托职责——综合理解。如果协调器只是转发消息（"Worker A 发现了一些东西，Worker B 你去处理"），它就退化成了一个消息路由器，没有任何智能编排的价值。强制协调器在综合阶段"理解并具体化"，是保持编排质量的关键。

2. "Every message you send is to the user"

这条规则防止协调器在长时间运行时保持沉默。Worker 的 是内部信号，不是对话伙伴——协调器不应该回复通知，而应该向用户报告进展。

3. "Don't set the model parameter"

协调器提示词中明确要求不要为 Worker 设置 model 参数。原因是 Worker 默认使用与协调器相同的模型来处理实质性任务。如果协调器为了"节省成本"设置了更便宜的模型，Worker 在复杂实施任务中可能表现不佳——这是一个容易犯的错误。

4. "Add a purpose statement"

协调器被要求在 Worker prompt 中包含"目的声明"——例如"This research will inform a PR description"。这是微妙但重要的提示工程：Worker 知道产出的用途后，会调整输出的深度和格式。为 PR 描述做的研究会更注重用户可见的变化，为 bug 修复做的研究会更注重根因分析。

5. Continue vs Spawn 决策表

最后一条特别有深意：当一个 Worker 的方法完全错误时，它的对话历史中充满了错误的假设和失败的尝试。如果继续使用这个 Worker，模型倾向于基于已有上下文做小修小补（"锚定效应"），而不是从根本上换一种方法。Spawn 一个全新的 Worker 可以避免这种认知锚定。

6. "验证 = 证明代码有效，不是确认代码存在"

验证 Worker 必须：运行测试（启用功能）、调查类型检查错误（不轻易判定"无关"）、保持怀疑态度、独立测试。

7. Worker 看不到你的对话

每个 Worker 提示词必须是自包含的。协调器提示词中反复强调这一点："Workers can't see your conversation. Every prompt must be self-contained."

这是初学者最容易犯的错误——写出类似"请继续刚才的工作"的 prompt，但 Worker 根本不知道"刚才"是什么。

7.4 Swarm 执行后端

Swarm 系统支持创建命名 Agent 团队，Agent 之间通过信箱对等通信。

关键文件：src/utils/swarm/backends/

三种后端

后端选择优先级的设计考量

后端检测的优先级不是随意排列的，每一步都有明确的理由：

1. 已在 tmux 内 → 直接用 Tmux：用户已经有了 tmux 分屏基础设施，在 tmux 内再创建新的 tmux session 会造成嵌套混乱。直接利用现有环境最自然。

1. 在 iTerm2 内 + it2 CLI 可用 → 用 iTerm2：提供 macOS 原生的面板体验（创建/分割窗格而非 tmux 面板），但如果 it2 CLI 不可用则回退到 tmux——因为 iTerm2 环境中 tmux 通常也可用。

1. 非交互式环境 → InProcess：CI/CD、SDK 调用等没有终端的场景，无法创建可视化面板。InProcess 后端在同一进程内运行 Worker，是唯一可行的选择。

1. 其他交互式环境 → 尝试 tmux：如果都不满足，尝试 tmux 作为最后方案。tmux 几乎在所有 Linux/macOS 系统上可用。

统一接口

所有后端实现统一的 TeammateExecutor 接口：

interface TeammateExecutor {
  spawn(config): Promise<void>              // 创建队友
  sendMessage(agentId, message): Promise<void>  // 发送消息
  terminate(agentId, reason): Promise<void> // 优雅关闭
  kill(agentId): Promise<void>              // 立即终止
  isActive(agentId): boolean                // 检查存活
}

terminate 和 kill 的区别很重要：terminate 发送优雅关闭请求（Agent 可以完成当前工作再退出），kill 通过 AbortController 立即中断。协调器在 Worker 方向错误时使用 TaskStop（映射到 kill），在正常结束时使用 terminate。

InProcess 执行详解

InProcess 后端是最轻量的执行方式，适用于非交互式环境（如 CI/CD）。核心文件：src/utils/swarm/inProcessRunner.ts。

AsyncLocalStorage 上下文隔离：

每个 Worker 通过 runWithTeammateContext() 在独立的 AsyncLocalStorage 上下文中运行。Node.js 的 AsyncLocalStorage 提供了一种在异步调用链中传递上下文的机制——每个 Worker 的异步调用栈（Promise 链、回调等）都能访问自己的 TeammateIdentity，即使它们在同一个 Node.js 事件循环中交错执行。

为什么 API 客户端和 MCP 连接可以共享？因为它们本质上是无状态的连接复用——HTTP 客户端和 WebSocket 连接是线程安全的，多个 Worker 可以并发使用同一个连接而不会干扰。这避免了为每个 Worker 建立独立连接的开销（TCP 握手、TLS 协商、MCP 初始化等）。

权限同步机制：

Worker 执行工具时需要权限审批。InProcess 后端使用两种权限桥接方式：

1. Leader 桥接（优先）：Worker 直接调用 Leader 的 ToolUseConfirm 对话框，UI 上显示 Worker 标记（badge）让用户知道是哪个 Worker 在请求。这是快速路径——权限确认直接在终端弹出，用户立即看到并做出决策。

1. 信箱通信（后备）：Worker 将权限请求写入信箱（writeToMailbox），Leader 通过 readMailbox 读取并响应。通过 registerPermissionCallback() / processMailboxPermissionResponse() 实现。这是当 Leader 桥接不可用时的后备方案——例如 Leader 正忙于处理其他请求。

AbortController 独立性：

每个 Worker 有独立的 AbortController。这意味着：

• 一个 Worker 的失败不影响其他 Worker
• 协调器中断不级联到 Worker（Worker 可以被显式 TaskStop）
• killInProcessTeammate() 通过 abort controller 立即终止特定 Worker

Scratchpad：跨 Worker 知识共享

当 tengu_scratch feature gate 启用时，系统提供一个共享的 Scratchpad 目录：

// src/coordinator/coordinatorMode.ts
if (scratchpadDir && isScratchpadGateEnabled()) {
  content += `\nScratchpad directory: ${scratchpadDir}\n` +
    `Workers can read and write here without permission prompts. ` +
    `Use this for durable cross-worker knowledge.`
}

Workers 可以在这个目录中自由读写文件（无需权限确认），用于持久化跨 Worker 的知识——例如研究发现、中间结果、共享配置。

为什么需要 Scratchpad？ 没有它，Worker 之间只能通过协调器中转信息。这有两个问题：

1. 延迟：Worker A 的发现必须先回传给协调器，协调器综合后再传给 Worker B——多了一个来回
2. 信息丢失：协调器综合时可能丢失细节（比如具体的行号），Worker B 拿到的是协调器的理解而非原始发现

Scratchpad 提供了一个直接的旁路通道：Worker A 将详细发现写入文件，Worker B 直接读取——无需经过协调器的"理解和转述"。

7.5 Worker 结果传递

同步 vs 异步：两条返回路径

Worker 的结果传递分为同步和异步两条路径，它们的机制完全不同：

同步路径（finalizeAgentTool() in agentToolUtils.ts）：

当子 Agent 同步执行时，父 Agent 阻塞等待。完成后，系统提取子 Agent 最后一条 assistant 消息的文本内容（不包含中间的工具调用过程），包装为 AgentToolResult，直接作为 tool_result 嵌入父级对话。

// 同步结果结构
{
  status: 'completed',
  agentId: string,
  content: [{ type: 'text', text: '最终结果文本' }],
  totalToolUseCount: number,
  totalDurationMs: number,
  totalTokens: number,
}

异步路径（enqueueAgentNotification() in LocalAgentTask.tsx）：

异步 Agent 在后台运行，父 Agent 立即收到一个"已启动"的响应。当任务完成（成功/失败/被终止）时，结果以 XML 格式作为 user 角色消息投递到父级的下一轮对话中：

<task-notification>
  <task-id>ae9a65ee22594487c</task-id>
  <status>completed</status>
  <summary>Agent "research query engine" completed</summary>
  <result>
    ... 详细结果内容 ...
  </result>
  <usage>
    <total_tokens>71330</total_tokens>
    <tool_uses>21</tool_uses>
    <duration_ms>81748</duration_ms>
  </usage>
</task-notification>

关键字段：

• task-id：Agent ID，可用于 SendMessage 继续该 Worker
• status：completed / failed / killed
• summary：人类可读的结果摘要（"completed" / "failed: {error}" / "was stopped"）
• result：Worker 的文本输出（可选），协调器据此做综合决策
• usage：Token 使用量、工具调用次数、耗时——用于成本追踪

task-notification 以 user 角色消息到达。协调器通过 开头标签区分它们和真正的用户消息。这个设计选择是因为 Claude API 的消息格式要求——只有 user 角色的消息能由系统注入，而 本质上是一个"系统事件"而非真正的用户输入。

通知去重与安全检查

去重机制：enqueueAgentNotification() 使用一个原子 notified 标志（LocalAgentTask.tsx）防止重复通知。如果 TaskStop 已经标记了任务为已通知，后续的完成通知会被静默丢弃。这防止了一个 Worker 被 stop 后又恰好自然完成时向协调器发送两条通知。

安全分类器：当 TRANSCRIPT_CLASSIFIER feature gate 启用时，classifyHandoffIfNeeded()（agentToolUtils.ts）在返回子 Agent 结果给父级之前，对子 Agent 的完整对话记录运行安全分类。这是一种纵深防御机制——防止攻击者通过精心构造的文件内容（如 README 中嵌入的 prompt injection）利用子 Agent 作为"跳板"，将恶意指令注入父级对话。如果分类器标记了结果，安全警告会被前置到结果文本中。

Worker 生命周期

错误处理与恢复

Worker 失败时，协调器有多种恢复策略：

协调器提示词中明确指出处理策略：

When a worker reports failure:
- Continue the same worker with SendMessage — it has the full error context
- If a correction attempt fails, try a different approach or report to the user

7.6 Plan 模式：两阶段执行

Plan 模式在 Agent 的工具调用循环中插入了一个审批关卡——进入 Plan 模式后，系统级剥离写入权限，Agent 只能读取代码和撰写计划文件；用户审批计划后，权限恢复，Agent 按计划执行修改。

关键文件：src/tools/EnterPlanModeTool/、src/tools/ExitPlanModeTool/、src/utils/planModeV2.ts、src/utils/plans.ts

两阶段设计

权限剥离与恢复

进入 Plan 模式时，系统执行精细的权限管理：

// src/utils/permissions/permissionSetup.ts
function prepareContextForPlanMode(context: ToolPermissionContext) {
  // 1. 记住进入 Plan 前的权限模式（如 default/auto）
  //    退出时恢复到这个模式
  context.prePlanMode = context.mode

  // 2. 如果从 auto 模式进入，剥离危险权限
  //    防止自动分类器在探索阶段批准写入操作
  if (context.mode === 'auto') {
    stripDangerousPermissionsForAutoMode(context)
  }

  // 3. 切换到 plan 模式
  context.mode = 'plan'
}

被剥离的"危险权限"包括：Bash 工具级别的 allow 规则、脚本解释器前缀（python:、node: 等）、Agent 通配符（agent(*)）。这些权限在用户审批计划后自动恢复。

设计决策：为什么不直接禁用所有写入工具？ Plan 模式保留了一个可写表面——计划文件（存储在 ~/.claude/plans/{slug}.md）。Agent 需要将探索发现和设计方案持久化到这个文件中，供用户审阅。这个"只允许写计划文件"的设计，在安全性（不修改代码）和实用性（能产出可审阅的方案）之间取得了平衡。

Plan 模式的五阶段工作流

系统提示词（src/utils/messages.ts）为 Plan 模式定义了一个结构化的工作流：

1. 初步理解 — 使用 Explore 子 Agent 调查代码库
2. 方案设计 — 使用 Plan 子 Agent 设计实现方案
3. 方案审查 — 读取关键文件，确保方案可行
4. 编写计划 — 将最终方案写入计划文件（唯一可编辑的文件）
5. 退出 Plan — 调用 ExitPlanMode，触发用户审批

审批与状态转换

审批通过后，计划内容作为 tool_result 注入对话，确保模型在实施阶段能引用具体方案。

为什么需要两阶段设计？

传统的 Agent 执行模式是"边想边做"——模型一边分析问题一边修改代码。这在简单任务中效率很高，但在复杂任务中会导致：

• 方向性返工：Agent 在只看了局部代码后就动手修改，后续发现整体方向不对，已有修改全部作废
• 无计划的局部修改：缺少全局视角的逐文件修改可能引入不一致，尤其在大型重构中
• 审批粒度过细：用户被迫逐个工具调用地审批，无法看到全貌就要做决定

两阶段设计通过一个审批关卡强制 Agent "先想清楚再动手"。源码中的关键约束是系统提示词中的这句话：

"The user indicated that they do not want you to execute yet — you MUST NOT make any edits, run any non-readonly tools, or otherwise make any changes to the system."

这不是建议，是硬约束——Plan 模式下写入工具的权限被系统级剥离，即使模型尝试调用也会被拒绝。

7.7 设计洞察

1. 协调器不执行是核心约束：防止协调器既做决策又做执行，保证任务分配的客观性。这也是为什么协调器的工具集被严格限制为 Agent + SendMessage + TaskStop。
2. "Never write based on your findings" 是最重要的提示词设计：强制协调器综合理解研究结果，而非将理解委托给 Worker。这个约束将协调器从消息转发器提升为真正的智能编排者。
3. Continue vs Spawn 不是默认选择：取决于上下文重叠度。高重叠→继续，低重叠→新建。这个决策框架避免了无脑复用或无脑新建。
4. AbortController 独立性保证故障隔离：一个 Worker 的崩溃不会连锁影响其他 Worker。这是并行系统的基本可靠性要求。
5. 后端检测优先级考虑用户环境：tmux > iTerm2 > InProcess，最大化利用已有终端能力。
6. Scratchpad 解决跨 Worker 知识共享：没有它，Worker 之间只能通过协调器中转信息，增加延迟和信息丢失风险。
7. Plan 模式的审批关卡是信任的物化：两阶段设计不只是 UX 改进——它将"用户信任"从隐性（每次工具调用时的权限弹窗）变为显性（一次性审批整体方案）。这在团队协作中尤为重要：协调器 Worker 的计划需要经过团队领导审批，而不是每个文件修改都需要确认。
8. Fork 是伪装成架构模式的缓存优化：Fork 子 Agent 的核心动机不是"继承上下文"——而是让多个子级共享父级的 Prompt Cache。CacheSafeParams 类型明确要求"字节级相同"就是最好的证据。继承上下文是缓存共享的副产品，不是设计目标。
9. 上下文隔离默认最大安全：createSubagentContext() 将所有可变状态默认设为隔离（no-op / clone），开发者必须通过 shareSetAppState、shareAbortController 等参数显式 opt-in 共享。这种"deny by default"设计意味着新增的子 Agent 功能天生是安全的——除非开发者有意识地打开共享。
10. 工具过滤实现纵深防御：四层独立的过滤（全局禁止 → 自定义限制 → 异步白名单 → 类型级禁止）确保即使某一层有 bug，其他层仍能拦截危险工具访问。MCP 工具的"始终放行"看似是例外，实际上是信任边界的正确划分——用户配置的外部工具由用户自己负责安全性。

动手实践：在 claude-code-from-scratch 中，Agent 主循环（src/agent.ts）实现了基础的工具调用循环。尝试在此基础上增加一个简单的"plan 模式"——在执行工具前先收集所有计划的操作，让用户一次性审批。

第 8 章：记忆系统

没有记忆的 Agent 每次对话都是初见——记忆让 Claude Code 从"无状态工具"进化为"跨会话学习的编程伙伴"。

8.1 为什么 Agent 需要记忆？

想象这样的场景：你连续三天和 Claude Code 在同一个项目上协作。第一天你告诉它"不要在响应末尾总结"，第二天你又说了一遍，第三天你开始烦躁——为什么它记不住？

这就是没有记忆的 Agent 的根本问题：每次会话都从零开始。用户偏好丢失、项目上下文重置、之前的纠正被遗忘。

Claude Code 的记忆系统解决这个问题，但它不是一个简单的"把所有信息存下来"的系统。它有一个核心约束：

只记忆不可从当前项目状态推导的信息。

这个约束不是为了省存储空间，而是为了防止记忆与现实漂移。如果记忆记录了"认证模块在 src/auth/"，一次代码重构就会让这条记忆变成误导。代码模式、架构、git 历史等信息是自描述的——从代码本身读取永远比从记忆中回忆更准确。

记忆 vs CLAUDE.md：互补而非竞争

两者互补：CLAUDE.md 存"项目是什么"，记忆存"和这个人协作时要注意什么"。

关键文件：src/memdir/

8.2 四种记忆类型：封闭分类法

记忆系统使用封闭的四类型分类法（closed taxonomy），每种类型有明确的职责边界和结构要求：

为什么是四种类型而非自由标签？ 封闭分类法强制 Agent 做出明确的语义分类，避免标签膨胀导致召回时的模糊匹配。每种类型有不同的保存结构和使用方式——这让模型在写入和读取时都有明确的行为指引。

feedback 类型深度分析：不只记录失败

源码 memoryTypes.ts 中 feedback 类型的定义揭示了一个微妙的设计决策——feedback 不仅记录用户的纠正，还记录用户的肯定：

Guidance or correction the user has given you. These are a very important
type of memory to read and write as they allow you to remain coherent and
responsive to the way you should approach work in the project.

为什么同时记录成功和失败？源码注释中有一段关键解释（意译）：

如果你只保存纠正，你会避免过去的错误，但会偏离用户已经验证过的好方法，并可能变得过于谨慎。

这是一个深刻的观察。假设用户说"这次的代码风格很好，以后就这样写"，如果不记录这个正面反馈，Agent 可能在下次会话中"改进"代码风格——结果反而偏离了用户满意的方向。

feedback 和 project 的结构化要求

这两种类型要求特定的正文结构：

规则或事实本身。

**Why:** 用户给出这个反馈的原因——通常是一个过去的事故或强烈偏好。
**How to apply:** 什么时候/在哪里应用这条指导。

为什么需要 Why？ 源码提示词中明确说明："Knowing why lets you judge edge cases instead of blindly following the rule."

举个例子：如果记忆只记录"不要 mock 数据库"，Agent 会在所有测试中避免 mock。但如果记忆还包含"Why: 上季度 mock 测试通过但生产环境迁移失败"，Agent 就能判断——这条规则适用于集成测试，单元测试中的轻量级 mock 可能没问题。

project 类型：相对日期 → 绝对日期

project 类型有一个特殊要求：必须将相对日期转换为绝对日期。

当用户说"周四之后合并冻结"，记忆必须存为"2026-03-05 后合并冻结"。原因很简单：记忆可能在几周后被另一次会话读取，此时"周四"已经毫无意义。

什么不该保存

记忆系统有一个明确的排除列表，来自源码中的 WHAT_NOT_TO_SAVE_SECTION：

- 代码模式、约定、架构、文件路径、项目结构——读当前代码即可获得
- Git 历史、最近的改动、谁改了什么——git log / git blame 是权威来源
- 调试方案或修复步骤——修复在代码里，上下文在 commit 消息中
- 已经记录在 CLAUDE.md 中的内容
- 临时任务细节：进行中的工作、临时状态、当前对话上下文

关键设计点：这些排除规则即使用户明确要求保存也生效。如果用户说"记住这个 PR 列表"，Agent 应该引导用户思考"这个列表中有什么是不可推导的？是关于它的某个决策、某个意外发现，还是某个截止日期？"

记忆决策流程

8.3 存储架构

存储格式

每条记忆是独立的 Markdown 文件，带 YAML frontmatter：

---
name: 简洁回复偏好
description: 用户不希望在响应末尾看到总结
type: feedback
---

不要在每次响应末尾总结已完成的操作。

**Why:** 用户明确表示可以自己阅读 diff。
**How to apply:** 所有响应保持简洁，省略尾部总结。

关键设计：description 字段不仅是元数据，它是召回系统的核心依据。当 Sonnet 模型在选择相关记忆时，主要依赖 description 判断相关性，因此 description 必须足够具体——"用户偏好"太泛，"用户不希望在响应末尾看到总结"才够精确。

目录结构

记忆文件存储在项目特定目录中：

~/.claude/projects/{project-hash}/memory/
├── MEMORY.md              ← 索引文件（每次会话自动加载）
├── user_role.md            ← 用户记忆
├── feedback_terse.md       ← 反馈记忆
├── project_freeze.md       ← 项目记忆
└── reference_linear.md     ← 引用记忆

路径解析：三级优先

记忆目录的位置通过三级优先级链确定（src/memdir/paths.ts）：

安全决策：为什么 projectSettings 被排除？

getAutoMemPathSetting() 只从 user/managed settings 读取，不从 projectSettings 读取。原因是安全：projectSettings 来自项目的 .claude/settings.json 文件，它是被签入代码仓库的。一个恶意的仓库可以设置 autoMemoryDirectory: "~/.ssh"，让 Claude Code 的记忆写入操作（Edit/Write 工具）获得对用户 SSH 密钥目录的写访问权限。这与权限系统中"不信任项目级设置用于安全敏感路径"的原则一致。

Git Worktree 共享

findCanonicalGitRoot() 确保同一仓库的所有 Git worktree 共享同一个记忆目录。如果不这样做，git worktree add 创建的新工作目录会生成一个独立的记忆空间，导致记忆"孤岛化"——在主工作目录中保存的偏好在 worktree 中消失。

目录预创建：避免浪费模型回合

系统通过 ensureMemoryDirExists() 在会话开始时保证目录存在。这一步是幂等的——底层的 fs.mkdir 自动处理 EEXIST，整个路径链在一次调用中创建。

为什么要保证目录预创建？ 实践中发现，Claude 会浪费回合执行 ls / mkdir -p 来检查目录是否存在。系统提示词中会注入 DIR_EXISTS_GUIDANCE，明确告诉模型：

"This directory already exists — write to it directly with the Write tool (do not run mkdir or check for its existence)."

这是一个典型的"用系统设计消除模型低效行为"的例子——与其期望模型学会不检查目录，不如直接预创建并明确告知。

是否启用记忆：五级优先

isAutoMemoryEnabled() 的判断链：

CLAUDE_CODE_DISABLE_AUTO_MEMORY 环境变量  →  禁用
--bare 启动标志                           →  禁用
远程模式（无持久化存储）                    →  禁用
settings.json 中 autoMemoryEnabled       →  按配置
以上都不满足                              →  默认启用

8.4 MEMORY.md：索引而非容器

MEMORY.md 是记忆系统的索引文件，不是记忆容器。每个条目应为一行链接：

- [用户角色](user_role.md) — 数据科学家，专注可观测性
- [简洁回复偏好](feedback_terse.md) — 不要尾部总结
- [合并冻结](project_freeze.md) — 2026-03-05 移动端发布冻结
- [Bug 追踪](reference_linear.md) — 管道 Bug 在 Linear INGEST 项目

为什么是索引而非容器？ 类比数据库：MEMORY.md 是索引，记忆文件是数据行。索引必须紧凑——因为 MEMORY.md 每次会话都完整加载到系统提示词中，它的大小直接挤占有效上下文空间。实际的记忆内容只有被 Sonnet 选中时才按需读取。

双层截断机制

MEMORY.md 有严格的大小限制，由 truncateEntrypointContent() 实现：

// src/memdir/memdir.ts
export const MAX_ENTRYPOINT_LINES = 200
export const MAX_ENTRYPOINT_BYTES = 25_000  // ~125 chars/line at 200 lines

export function truncateEntrypointContent(raw: string): EntrypointTruncation {
  const contentLines = trimmed.split('\n')
  const wasLineTruncated = lineCount > MAX_ENTRYPOINT_LINES
  const wasByteTruncated = byteCount > MAX_ENTRYPOINT_BYTES

  // 第一步：按行截断（自然边界）
  let truncated = wasLineTruncated
    ? contentLines.slice(0, MAX_ENTRYPOINT_LINES).join('\n')
    : trimmed

  // 第二步：如果仍超过字节上限，在最后一个换行处截断（不切断行中间）
  if (truncated.length > MAX_ENTRYPOINT_BYTES) {
    const cutAt = truncated.lastIndexOf('\n', MAX_ENTRYPOINT_BYTES)
    truncated = truncated.slice(0, cutAt > 0 ? cutAt : MAX_ENTRYPOINT_BYTES)
  }

  // 追加警告信息
  return {
    content: truncated + `\n\n> WARNING: MEMORY.md is ${reason}. Only part of it was loaded.`,
    lineCount, byteCount, wasLineTruncated, wasByteTruncated,
  }
}

为什么有两层截断？

• 行截断（200 行）：正常情况——索引条目太多，按行截断保持完整条目。
• 字节截断（25KB）：防御措施——捕捉行数在 200 以内但单行极长的异常索引。实际观察到 p100 场景：197KB 在 200 行内（有人把整篇文档作为单行条目）。

返回的元数据（wasLineTruncated / wasByteTruncated）用于遥测追踪，帮助团队了解用户的索引增长模式。

警告消息的设计：截断时追加的警告不只是报告问题，还教模型如何修复——提示模型"keep index entries to one line under ~200 chars; move detail into topic files"。这体现了一个设计原则：错误消息应该包含修复指引。

skipIndex 模式

一个实验性的 feature gate（tengu_moth_copse）正在测试移除 MEMORY.md 索引要求。启用后，记忆提取 Agent 直接写记忆文件而不更新 MEMORY.md。

为什么测试这个？两步保存流程（写文件 + 更新索引）是记忆系统中最容易出错的部分——模型可能写了文件但忘了更新索引，或者索引格式错误。如果 skipIndex 模式的召回质量不下降（因为 scanMemoryFiles() 直接扫描目录而非依赖索引），就可以简化整个保存流程。

8.5 记忆召回：语义检索

当用户提交查询时，系统自动寻找相关记忆。这个过程分为扫描、评估、过滤三个阶段：

scanMemoryFiles()：单次遍历优化

src/memdir/memoryScan.ts 中的扫描实现采用了一个巧妙的性能优化——单次遍历（read-then-sort）而非传统的两步法（stat-sort-read）：

export async function scanMemoryFiles(memoryDir: string, signal: AbortSignal) {
  const entries = await readdir(memoryDir, { recursive: true })
  const mdFiles = entries.filter(f => f.endsWith('.md') && basename(f) !== 'MEMORY.md')

  // 并行读取所有文件的 frontmatter（只读前 30 行）
  const headerResults = await Promise.allSettled(
    mdFiles.map(async (relativePath) => {
      const { content, mtimeMs } = await readFileInRange(filePath, 0, FRONTMATTER_MAX_LINES)
      const { frontmatter } = parseFrontmatter(content, filePath)
      return { filename: relativePath, filePath, mtimeMs, description, type }
    })
  )

  // 单次遍历：读取后排序，而非 stat-排序-读取
  return headerResults
    .filter(r => r.status === 'fulfilled')
    .map(r => r.value)
    .sort((a, b) => b.mtimeMs - a.mtimeMs)
    .slice(0, MAX_MEMORY_FILES)  // MAX_MEMORY_FILES = 200
}

为什么这样更快？

传统方法是：

1. stat() 所有文件获取 mtime → N 次 syscall
2. 按 mtime 排序，取前 200
3. read() 前 200 个文件的 frontmatter → 200 次 syscall
4. 总计：N + 200 次 syscall

单次遍历方法是：

1. read() 所有文件的前 30 行（readFileInRange 同时返回 mtime）→ N 次 syscall
2. 排序并截取前 200
3. 总计：N 次 syscall

对常见场景（N ≤ 200），syscall 数量减半。代价是多读了一些最终被丢弃的文件的 frontmatter，但每个文件只读 30 行，开销极小。

FRONTMATTER_MAX_LINES = 30：只读前 30 行是因为 frontmatter 始终在文件顶部。读取完整文件对召回来说是浪费——选择阶段只需要 description 字段。

formatMemoryManifest()：清单格式

扫描结果被格式化为清单，提供给 Sonnet 评估：

- [feedback] feedback_terse.md (2026-03-28T10:30:00Z): 用户不希望在响应末尾看到总结
- [project] project_freeze.md (2026-03-01T09:00:00Z): 2026-03-05 合并冻结，移动端发布

格式中的 ISO 时间戳至关重要——它让 Sonnet 能判断记忆的新鲜度。一个月前的"合并冻结"记忆很可能已过时，Sonnet 可以据此降低其优先级。

selectRelevantMemories()：Sonnet 语义评估

const SELECT_MEMORIES_SYSTEM_PROMPT = `You are selecting memories that will be useful
to Claude Code as it processes a user's query. Return a list of filenames for the
memories that will clearly be useful (up to 5).
- Be selective and discerning.
- If recently-used tools are provided, do not select usage reference docs for those
  tools. DO still select warnings, gotchas, or known issues about those tools.`

const result = await sideQuery({
  model: getDefaultSonnetModel(),
  system: SELECT_MEMORIES_SYSTEM_PROMPT,
  messages: [{ role: 'user', content: `Query: ${query}\n\nAvailable memories:\n${manifest}${toolsSection}` }],
  max_tokens: 256,
  output_format: { type: 'json_schema', schema: { /* selected_memories: string[] */ } },
})

为什么用 Sonnet 而非关键词匹配？ 语义相关性评估比关键词匹配更准确。例如，用户问"部署流程"时，关键词匹配可能错过标题为"CI/CD 注意事项"的记忆，但 Sonnet 能理解语义关联。

为什么限制 5 个？ 上下文空间有限。记忆内容作为 user message 注入对话，过多的记忆会挤占工作空间。5 个是召回价值和上下文成本的平衡点。

recentTools 参数：精确的噪声过滤

recentTools 参数是一个巧妙的设计。当 Claude Code 正在使用某个工具（如 mcp__X__spawn）时：

• 该工具的参考文档型记忆是噪声——对话中已经包含了使用方法
• 但关于该工具的警告和已知问题仍然有价值

提示词中明确区分这两种情况："do not select usage reference docs for those tools. DO still select warnings, gotchas, or known issues about those tools." 这让选择器在工具使用的上下文中做出更精确的判断。

alreadySurfaced 预过滤

findRelevantMemories() 在调用 Sonnet 之前就过滤掉已展示的记忆路径。这不是为了避免重复展示（虽然也有这个效果），而是为了不浪费 5 个召回槽位——如果不预过滤，Sonnet 可能选中 3 个已展示的记忆，只留下 2 个新记忆的空间。

异步预取：不阻塞主循环

记忆召回通过 pendingMemoryPrefetch 实现异步预取——在模型开始生成响应的同时，后台通过 sideQuery() 查询 Sonnet。当模型实际需要记忆时，结果通常已经就绪。

这个设计确保记忆召回的 ~250ms 延迟不叠加到用户感知的响应时间上。对用户来说，记忆召回是"免费"的。

8.6 记忆新鲜度与漂移防御

记忆记录的是写入时的事实，但时间会让记忆过时。记忆系统通过多层防御机制来处理这个问题。

人类可读的时间距离

memoryAge.ts 将 mtime 转为人类可读的字符串：

0 天 → "today"
1 天 → "yesterday"
47 天 → "47 days ago"

为什么不用 ISO 时间戳？ 模型不擅长日期算术。给模型 2026-02-12T10:30:00Z 并告诉它今天是 2026-04-01，它可能算不清楚过了多少天。但 "47 days ago" 直接触发模型的"这可能过时了"推理。

新鲜度警告

对于超过 1 天的记忆，系统注入新鲜度警告文本（memoryFreshnessText）：

"Memories are point-in-time observations, not live state — claims about code behavior or file:line citations may be outdated."

这个警告的出发点是：用户报告过 Agent 将过时的记忆（如"X 函数在 line 42"）作为事实断言，导致错误的代码修改。

记忆访问三规则

源码中的 WHEN_TO_ACCESS_SECTION 定义了三条访问规则：

1. 当已知记忆与任务相关时：主动查阅
2. 当用户明确要求时：必须访问记忆（用 MUST 强调）
3. 当用户说"忽略记忆"时：视为记忆不存在

第三条规则背后有一个 eval 失败案例：用户说"忽略关于 X 的记忆"，但 Claude 回复"不是 Y（如记忆中所述），而是..."——它承认了记忆的存在并试图"修正"，违背了用户的意图。

信任召回：验证而非盲信

TRUSTING_RECALL_SECTION 是记忆系统中最关键的安全网之一：

"记忆说 X 存在" ≠ "X 现在存在"

规则要求：如果记忆提到一个文件路径，用 Glob/Read 验证它是否存在。如果记忆提到一个函数，用 Grep 确认它是否还在。

这个节的效果在 eval 中得到了验证：没有这个节，通过率 0/2；加入后，通过率 3/3。 这说明模型默认会信任记忆中的具体引用，但记忆中的代码位置信息衰减很快——一次重构就可能全部失效。

8.7 后台记忆提取

除了模型主动写入和用户通过 /remember 保存外，Claude Code 还有一个后台记忆提取 Agent（src/services/extractMemories/extractMemories.ts），在每次对话回合结束后自动运行。

整体架构

触发与互斥

提取 Agent 在 handleStopHooks 中被触发——即主 Agent 完成响应（没有更多工具调用）时。但它不是每次都运行：

互斥机制：hasMemoryWritesSince() 检查主 Agent 是否在最近的消息范围内已经写入了记忆文件。如果主 Agent 已经主动保存了记忆（比如用户说"记住这个"，主 Agent 直接调用 Write 写入），提取 Agent 就跳过——避免对同一段对话产生重复记忆。

回合节流：turnsSinceLastExtraction 计数器控制提取频率。不是每个回合都需要提取——很多回合（如简单的问答）没有值得记忆的信息。

重叠防护

如果上一次提取还在运行时新的回合结束了，系统不会启动并发提取：

inProgress = true → 将新请求暂存为 pendingContext
当前提取完成    → 检查 pendingContext，如果有则启动 trailing run
trailing run    → 只处理自游标推进后的新消息

这个设计确保：(1) 不会有两个提取 Agent 同时写入记忆目录（避免冲突）；(2) 不会遗漏任何对话内容。

工具权限：严格的写入白名单

提取 Agent 的工具权限由 createAutoMemCanUseTool() 定义：

这是最小权限原则的体现——提取 Agent 只需要读取对话上下文和已有记忆，然后写入新记忆。它不需要执行代码、修改项目文件或调用外部服务。

提取提示词设计

提取 Agent 的提示词（src/services/extractMemories/prompts.ts）有几个关键设计：

高效的回合预算：提示词明确指导 Agent 的执行策略——"Turn 1: 并行发起所有读取；Turn 2: 并行发起所有写入"。这最大化了工具调用的并行度，通常 2 个回合就能完成工作（硬上限是 5 个回合）。

防止重复：提示词注入已有记忆的清单（manifest），并指导 Agent "先检查是否已有类似记忆，再决定创建新的"。

范围限制：MUST only use content from last ~${newMessageCount} messages——只从最新的消息中提取，不重新处理已处理过的历史。

共享 Prompt Cache

提取 Agent 通过 runForkedAgent() 创建，这与技能系统的 fork 模式使用相同的底层机制。关键优势是共享父级的 prompt cache——系统提示词不需要重新计算和传输，大幅降低提取的 token 消耗。

8.8 记忆提示词构建层级

记忆系统的提示词构建分为三个层级，每层叠加不同的内容：

buildMemoryLines()：行为指令的八个子节

buildMemoryLines() 构建的指令包含八个子节：

1. 持久化记忆介绍：告知模型记忆目录路径，DIR_EXISTS_GUIDANCE 说明目录已存在
2. 显式保存/遗忘：用户说"记住"→ 立即保存，说"忘记"→ 查找并删除
3. 四类型分类法：user / feedback / project / reference 的完整定义、示例、保存时机
4. 什么不该保存：代码模式、git 历史、CLAUDE.md 已有内容等排除列表
5. 如何保存：两步流程（写文件 + 更新 MEMORY.md）或单步（skipIndex 模式）
6. 何时访问：三条规则 + "用户说忽略则忽略"
7. 信任召回：验证记忆中的引用，不盲信
8. 记忆 vs 其他持久化：Plan 用于对齐实施方案，Task 用于追踪当前会话进度，记忆用于跨会话信息

第 8 点的区分特别重要——模型容易混淆何时用记忆、何时用 Plan、何时用 Task。记忆系统的提示词明确划定了边界：

- Plan：非平凡实现任务的方案对齐，变更应更新 Plan 而非保存记忆 - Task：当前会话中的步骤分解和进度追踪 - 记忆：跨会话有价值的信息

KAIROS 模式

KAIROS 是一个实验性的"助手模式"，为长期运行的会话设计。与普通模式维护 MEMORY.md 实时索引不同，KAIROS 模式将信息追加到日期命名的日志文件中：

~/.claude/projects/{hash}/logs/
└── 2026/
    └── 04/
        └── 2026-04-01.md    ← 今天的日志

每天的日志是追加式的，避免了频繁更新 MEMORY.md 索引的开销。定期通过 /dream 技能将日志蒸馏为结构化的主题记忆文件。这种"先追加、后整理"的模式适合高频交互场景。

8.9 团队记忆

当启用团队记忆（TEAMMEM feature gate）时，系统管理两个记忆目录：

~/.claude/projects/{hash}/memory/          ← 私有记忆（仅自己可见）
~/.claude/projects/{hash}/memory/team/     ← 团队记忆（项目成员共享）

作用域指导

在团队模式下，类型分类法增加了 标签来指导记忆的存储位置：

敏感数据防护：团队记忆的提示词中明确要求"MUST NOT save sensitive data (API keys, credentials) in team memories"。私有记忆也不建议存储敏感信息，但团队记忆中这是强制要求——因为团队记忆会被其他成员的 Agent 读取。

架构细节：isTeamMemoryEnabled() 要求先启用自动记忆。团队目录是自动记忆目录的子目录——mkdir(teamDir) 会通过递归创建自动创建父目录。两个目录各有独立的 MEMORY.md 索引，都加载到系统提示词中。

8.10 Agent 记忆

除了主 Agent 的记忆系统，Claude Code 还为子 Agent（通过 Agent 工具创建的）提供了独立的记忆系统（src/tools/AgentTool/agentMemory.ts）。

三个作用域

user 作用域:    ~/.claude/agent-memory/{agentType}/
project 作用域: .claude/agent-memory/{agentType}/
local 作用域:   .claude/agent-memory-local/{agentType}/

• user：跨所有项目的 Agent 级知识（如"这种类型的探索 Agent 应该如何工作"）
• project：项目特定的 Agent 知识（如"这个项目的测试 Agent 应该使用哪个测试框架"）
• local：本地机器特定，不会签入版本控制

为什么与主记忆分离？

子 Agent 的知识类型与主 Agent 不同。一个 "explorer" Agent 学到的代码导航技巧、一个 "test-runner" Agent 学到的测试模式——这些是 Agent 类型特有的操作知识，与用户偏好和项目决策没有关系。分离存储避免了主记忆被 Agent 操作细节污染。

agentType 在路径中的作用是隔离不同类型 Agent 的知识空间。路径中的冒号被替换为破折号（sanitizeAgentTypeForPath()）以兼容文件系统。

记忆注入方式

Agent 记忆通过与主记忆相同的 buildMemoryPrompt() 函数构建，但带有 Agent 特有的行为指导。注入方式也相同——MEMORY.md 索引进系统提示词，具体记忆按需通过语义召回加载。

8.11 记忆注入对话的方式

理解记忆如何到达模型的上下文窗口：

MEMORY.md：系统提示词注入

MEMORY.md 内容通过 systemPromptSection('memory', () => loadMemoryPrompt()) 注入系统提示词。这意味着：

• 每次会话自动加载
• 经过 truncateEntrypointContent() 截断
• 位于系统提示词的动态部分

召回的记忆：用户消息注入

通过 Sonnet 选中的记忆作为 user message（带 isMeta: true）注入对话：

case 'relevant_memories': {
  return wrapMessagesInSystemReminder(
    attachment.memories.map(m => createUserMessage({
      content: `${memoryHeader(m.path, m.mtimeMs)}\n\n${m.content}`,
      isMeta: true
    }))
  )
}

memoryHeader() 包含文件路径、修改时间的人类可读距离（如 "3 days ago"）、和新鲜度警告。记忆被包裹在 标签中，与其他上下文信息（如 Read/Grep 结果）归为同一组。

isMeta: true 标记确保这些消息在 UI 中不作为用户消息显示，但模型能看到它们。

8.12 设计洞察

1. 只记忆不可推导的信息：代码模式从代码读，git 历史从 git 查，记忆只存"元信息"——这个约束是整个系统的根基，防止记忆成为过时的代码映射

1. 语义召回优于关键词匹配：用 Sonnet 评估相关性，能理解"部署"和"CI/CD"的语义关联。代价是 ~250ms 额外延迟，但通过异步预取完全隐藏

1. 两层截断防御长索引：行截断捕捉正常增长，字节截断捕捉异常长行（实际观察到 197KB 在 200 行内）——面向实际数据设计，而非理论场景

1. 后台提取 Agent 模式：将"从对话中提取记忆"封装为独立的 forked agent，共享 prompt cache 降低成本，互斥机制避免重复，最小权限限制写入范围。这个模式可推广到任何"后台智能"场景

1. eval 驱动的提示词工程：TRUSTING_RECALL_SECTION 的加入直接由 eval 数据驱动（0/2 → 3/3）。记忆系统的每个提示词节都经过测评验证，不是凭直觉添加的

1. 用系统设计消除模型低效行为：预创建目录 + DIR_EXISTS_GUIDANCE 比"教模型不要检查目录"更可靠。这是一个通用原则：如果模型反复犯某个错误，优先考虑改变环境而非改变提示词

1. frontmatter 作为统一接口：记忆和技能使用相同的 Markdown + YAML frontmatter 格式，降低了模型的认知负担——只需学习一种文件格式就能操作两个系统

动手实践：在 claude-code-from-scratch 的 src/session.ts 中，可以看到一个最小的会话持久化实现。尝试在此基础上增加记忆系统——将用户偏好写入 ~/.mini-claude/memory/ 目录，并在系统提示词中注入。

第 9 章：技能系统

技能是 Claude Code 的"AI Shell 脚本"——将验证有效的 prompt 模板化，让 Agent 不必每次从头编写相同的流程。

9.1 什么是技能？

Shell 脚本自动化终端任务，技能自动化 AI 任务。一个技能本质上是：提示词模板 + 元数据 + 执行上下文。

与传统的聊天机器人"命令"不同，Claude Code 的技能有一个关键特性——双重调用模型：

用户手动调用时，CLI 直接解析 /command args 语法。模型自动调用时，通过 SkillTool 工具（一个专门的工具定义）来执行。两条路径最终汇合到同一个提示词加载和执行逻辑。

PromptCommand 核心类型

技能在代码中表示为 PromptCommand 类型（src/types/command.ts）：

type PromptCommand = {
  type: 'prompt'
  name: string                    // 技能名称
  description: string             // 显示描述
  whenToUse?: string              // 模型据此判断何时自动触发
  allowedTools?: string[]         // 允许的工具白名单
  model?: string                  // 模型覆盖
  effort?: EffortValue            // 工作量级别
  context?: 'inline' | 'fork'    // 执行模式
  agent?: string                  // fork 时的 Agent 类型
  source: 'bundled' | 'plugin' | 'skills' | 'mcp'  // 来源
  hooks?: HooksSettings           // 技能级 Hook
  skillRoot?: string              // 技能资源基础目录
  paths?: string[]                // 可见性路径模式
  getPromptForCommand(args, context): Promise<ContentBlockParam[]>  // 内容加载器
}

关键文件：src/skills/loadSkillsDir.ts、src/tools/SkillTool/SkillTool.ts

9.2 技能来源与优先级

技能从 6 个来源加载，优先级从高到低：

高优先级来源的技能在命名冲突时覆盖低优先级。

加载流程

文件系统技能通过 loadSkillsFromSkillsDir() 加载：

技能文件格式要求：只支持 skill-name/SKILL.md 的目录格式——每个技能是一个目录，包含一个 SKILL.md 文件。这不是随意的限制：目录格式允许技能附带资源文件（如模板、配置），并通过 ${CLAUDE_SKILL_DIR} 引用。

去重：为什么用 realpath 而非 inode

去重通过 realpath() 解析符号链接实现——相同规范路径的文件视为同一技能。源码注释解释了为什么不用 inode 号：

虚拟文件系统、容器文件系统、NFS 可能报告不可靠的 inode 值（如 inode 0），ExFAT 可能丢失精度。realpath() 在所有平台上行为一致。

这是一个实际环境驱动的决策——Claude Code 运行在各种环境中，包括容器和远程文件系统。

MCP 技能构建器：打破依赖循环

MCP 服务端提供的技能通过 mcpSkillBuilders.ts 中的 write-once 注册表模式加载。这个间接层存在是为了打破循环依赖：

client.ts → mcpSkills.ts → loadSkillsDir.ts → ... → client.ts  ← 循环！

注册表模式将 MCP 技能的构建函数注册为回调，解耦了模块间的直接依赖。

9.3 技能结构与 Frontmatter

技能文件是 Markdown + YAML frontmatter。以下是所有支持的 frontmatter 字段及详细说明：

---
name: my-skill                    # 显示名称（可选，默认使用目录名）
description: 描述                  # 技能描述（Sonnet 据此判断是否自动触发）
aliases: [ms]                     # 命令别名列表
when_to_use: 自动触发条件描述       # 模型据此判断何时主动调用（影响 SkillTool 触发）
argument-hint: "文件路径"          # 参数提示（显示在帮助和 Tab 补全中）
arguments: [file, mode]           # 命名参数列表（映射到 $file, $mode）
allowed-tools: [Bash, Edit, Read] # 允许的工具白名单（限制技能可使用的工具）
model: claude-sonnet              # 模型覆盖（"inherit" = 继承父级，不覆盖）
effort: quick                     # 工作量：quick / standard / 整数分钟
context: fork                     # 执行上下文：inline（默认）或 fork
agent: explorer                   # fork 时使用的 Agent 类型
version: "1.0"                    # 语义版本号
shell: bash                       # 内联 Shell 块使用的 Shell 类型
user-invocable: true              # false 则隐藏，用户不可通过 /name 直接调用
disable-model-invocation: false   # true 则只允许用户手动 /skill 调用，模型不可自动触发
paths:                            # 可见性路径模式（gitignore 风格）
  - "src/components/**"           # 仅在匹配路径下工作时显示此技能
hooks:                            # 技能级 Hook 定义
  PreToolUse:
    - matcher: "Bash(*)"
      hooks:
        - type: command
          command: "echo checking"
---

技能提示词内容...
可以引用 $ARGUMENTS 占位符

字段解析细节

parseSkillFrontmatterFields() 统一处理所有字段解析（src/skills/loadSkillsDir.ts）：

model 字段："inherit" 被解析为 undefined，意味着使用当前会话的模型。其他值（如 "claude-sonnet"）作为模型覆盖。

effort 字段：接受三种格式——"quick"（快速任务）、"standard"（标准任务）、整数（自定义分钟数）。这影响模型的思考深度。

paths 字段：gitignore 风格的路径模式。parseSkillPaths() 会去除 /** 后缀并过滤掉匹配所有文件的模式（如 *）。这允许技能仅在特定代码区域激活——例如一个 React 组件技能只在 src/components/ 下可见。

hooks 解析：通过 Zod schema（HooksSchema().safeParse）校验。无效的 hooks 定义仅记录警告但不致命——一个格式错误的 hook 不应该阻止整个技能加载。

arguments 字段：命名参数通过 parseArgumentNames() 提取。在提示词替换时，$file 和 ${file} 都映射到 arguments[0] 的值。

9.4 懒加载与 Token 预算

懒加载：只加载需要的

技能内容不在启动时加载——只有 frontmatter（name, description, whenToUse）被预加载。完整的 Markdown 内容在用户实际调用或模型触发时才读取。

export function estimateSkillFrontmatterTokens(skill: Command): number {
  const frontmatterText = [skill.name, skill.description, skill.whenToUse]
    .filter(Boolean)
    .join(' ')
  return roughTokenCountEstimation(frontmatterText)
}

为什么懒加载？ 系统可能注册几十个技能。如果全部加载到系统提示词中：

• 挤占上下文空间（一个技能可能有几百行提示词）
• 大部分技能在当前会话中不会被使用
• 加载时间增加，影响首次响应速度

通过只加载 frontmatter 来展示可用技能列表，将内容加载推迟到调用时，实现了"展示成本低、执行成本按需"。

Token 预算分配算法

技能列表在系统提示词中需要占据空间，但空间有限。formatCommandsWithinBudget()（src/tools/SkillTool/prompt.ts）实现了一个三阶段预算分配算法：

Phase 1：尝试所有技能使用完整描述。如果总量在预算内，直接完成。

Phase 2：将技能分为 bundled（内置）和 rest（非内置）两组。Bundled 技能始终保留完整描述——它们是核心功能，截断会隐藏基本能力。计算 bundled 占用后的剩余预算，在非 bundled 技能间均分。

Phase 3（极端情况）：如果均分后每个技能不足 20 个字符（MIN_DESC_LENGTH），非 bundled 技能降级为仅显示名称。此时用户仍然可以看到技能存在，只是没有描述。

为什么保护 bundled 技能？ Bundled 技能代表 Claude Code 的核心能力（如 /commit、/review、/debug）。用户期望始终能看到这些技能及其功能说明。即使安装了大量自定义技能导致预算压力，核心功能的可发现性也不能牺牲。

每个技能描述还有一个硬上限：MAX_LISTING_DESC_CHARS = 250 字符，即使在预算充裕时也不允许单个技能占据过多空间。

9.5 提示词替换管道

技能内容在执行时经过多层替换，由 getPromptForCommand() 驱动：

Step 1：基础目录前缀

如果技能有关联目录（skillRoot），在提示词开头插入 "Base directory for this skill: {baseDir}"。这让技能的提示词可以引用相对路径资源。

Step 2：参数替换

substituteArguments() 处理两种参数格式：

• $ARGUMENTS：替换为用户输入的全部参数字符串
• $file / ${file}：替换为对应的命名参数（从 frontmatter 的 arguments 字段映射）

例如，技能定义 arguments: [file, format]，用户输入 /skill main.ts json，则 $file → main.ts，$format → json。

Step 3：环境变量替换

• ${CLAUDE_SKILL_DIR}：替换为技能文件所在的目录路径。在 Windows 上，反斜杠自动转为正斜杠以保持路径一致性。
• ${CLAUDE_SESSION_ID}：替换为当前会话 ID，允许技能按会话隔离状态。

Step 4：内联 Shell 执行

技能 Markdown 中可以嵌入 ` !command ` 格式的 Shell 命令。执行时命令被运行，输出替换回原位。这允许技能动态获取环境信息：

当前分支：!`git branch --show-current`
最近提交：!`git log --oneline -5`

Shell 类型可通过 frontmatter 的 shell 字段指定（bash/zsh/fish）。

MCP 安全隔离

MCP 技能来自远程不受信任的服务端，因此有两项安全限制：

// Security: MCP skills are remote and untrusted — never execute inline
// shell commands (!`…` / ```! … ```) from their markdown body.
if (loadedFrom !== 'mcp') {
  finalContent = await executeShellCommandsInPrompt(finalContent, ...)
}

1. 禁用内联 Shell 执行：远程提示词中的 ` !rm -rf / ` 不会被执行
2. 不替换 ${CLAUDE_SKILL_DIR}：对远程技能无意义，且暴露本地路径是信息泄露

这个检查在源码中是显式实现的，而非依赖某个抽象层——安全关键路径上的显式检查比隐式依赖更可靠。

9.6 技能执行：Inline vs Fork

技能有两种执行上下文，由 frontmatter 的 context 字段决定：

Inline 模式（默认）

提示词作为消息注入当前对话。模型在原有上下文中继续执行——可以看到之前的对话历史、使用所有可用工具。

优势：共享对话上下文，可以引用之前的讨论；无额外开销。

劣势：技能提示词占据主对话上下文空间；工具调用污染主对话历史。

适用场景：快速行为修改（如 simplify——审查刚写的代码）、需要引用对话上下文的任务。

Fork 模式

创建独立的子 Agent，有自己的消息历史和工具池。完成后结果返回父对话。

优势：不污染主对话上下文；可限制工具集（安全隔离）；可使用不同的模型。

劣势：不能引用主对话历史中的内容；有创建子 Agent 的额外开销。

适用场景：需要大量工具调用的复杂任务（如 verify——运行完整测试套件）、需要工具限制的安全敏感任务。

对比总结

何时选择 Fork？

• 任务需要大量工具调用（会污染主对话上下文）
• 需要限制可用工具（安全隔离——如 review 技能不应该能写文件）
• 需要使用不同的模型（如用 Sonnet 做快速检查，用 Opus 做深度分析）
• 需要独立的失败隔离（fork 失败不影响主对话流）

模型覆盖解析

当技能指定 model 字段时，resolveSkillModelOverride() 处理解析：

• "inherit" → undefined（使用父级模型，不覆盖）
• 具体模型别名（如 "claude-sonnet"）→ 解析为实际模型 ID
• 如果主会话有模型后缀（如 [1m]），覆盖时会保留该后缀

AllowedTools 在 Fork 模式下的安全意义

当技能指定 allowed-tools: [Bash, Read, Grep, Glob] 时，fork 出的子 Agent 只能使用这些工具。这是安全隔离的关键：

• 一个代码审查技能不需要写文件的能力——限制为只读工具
• 一个测试运行技能不需要网络访问——限制为 Bash + Read

工具限制通过 contextModifier 在返回结果时应用，修改上下文中的 alwaysAllowRules。

9.7 技能的权限模型

SAFE_SKILL_PROPERTIES 白名单

SkillTool 在执行技能前需要检查权限。一个关键优化是：只包含"安全属性"的技能自动允许，无需用户确认。

"安全属性"由 SAFE_SKILL_PROPERTIES 白名单定义（src/tools/SkillTool/SkillTool.ts）：

const SAFE_SKILL_PROPERTIES = new Set([
  // PromptCommand 属性
  'type', 'progressMessage', 'contentLength', 'argNames', 'model', 'effort',
  'source', 'pluginInfo', 'disableNonInteractive', 'skillRoot', 'context',
  'agent', 'getPromptForCommand', 'frontmatterKeys',
  // CommandBase 属性
  'name', 'description', 'hasUserSpecifiedDescription', 'isEnabled',
  'isHidden', 'aliases', 'isMcp', 'argumentHint', 'whenToUse', 'paths',
  'version', 'disableModelInvocation', 'userInvocable', 'loadedFrom',
  'immediate'
])

skillHasOnlySafeProperties() 遍历技能对象的所有键，检查每个键是否在白名单中。undefined/null/空值视为安全。

为什么是白名单而非黑名单？ 前向兼容安全。如果未来 PromptCommand 类型增加了新属性（如 networkAccess），白名单模式下它默认需要权限审批，直到被显式加入白名单。黑名单模式则相反——新属性默认被允许，必须被显式加入黑名单才会触发审批。在安全敏感的上下文中，"默认拒绝"比"默认允许"更安全。

不同来源的信任级别

9.8 压缩后的技能保留

问题

当对话过长触发 autocompact（上下文压缩）时，之前注入的技能提示词会被压缩摘要覆盖。模型失去对技能指令的访问，导致行为在压缩前后不一致——压缩前按技能指令行事，压缩后"忘记"了技能。

解决方案

addInvokedSkill() 在每次技能调用时记录完整信息到全局状态：

addInvokedSkill(name, path, content, agentId)
// 记录：名称、路径、完整内容、时间戳、所属 Agent ID

压缩后，createSkillAttachmentIfNeeded() 从全局状态重建技能内容作为 attachment 重新注入。

预算管理

POST_COMPACT_SKILLS_TOKEN_BUDGET = 25,000  总预算
POST_COMPACT_MAX_TOKENS_PER_SKILL = 5,000  单技能上限

• 按最近调用优先排序——最近使用的技能最可能仍然相关
• 超出单技能上限时，保留头部截断尾部——因为技能的设置指令和使用说明通常在开头
• 超出总预算时，最不活跃的技能被丢弃

Agent 作用域隔离

记录的技能按 agentId 隔离——子 Agent 调用的技能不会泄漏到父 Agent 的压缩恢复中，反之亦然。clearInvokedSkillsForAgent(agentId) 在 fork Agent 完成时清理其技能记录。

为什么这个机制重要？ 没有它，一个长时间的编码会话（跨越多次压缩）会逐渐"忘记"技能上下文。用户在第 50 轮使用 /commit 时的行为应该与第 5 轮一致——技能保留机制确保了这种一致性。

9.9 内置技能详解

注册机制

内置技能通过 registerBundledSkill() 在启动时注册（src/skills/bundledSkills.ts）：

registerBundledSkill({
  name: 'remember',
  description: 'Review auto-memory entries...',
  whenToUse: 'Use when...',
  userInvocable: true,
  isEnabled: () => isAutoMemoryEnabled(),
  async getPromptForCommand(args) {
    return [{ type: 'text', text: SKILL_PROMPT }]
  }
})

与文件系统技能不同，bundled 技能的内容编译在二进制中，不需要运行时文件读取。

始终注册的技能

Feature-gated 技能

安全的文件提取

部分 bundled 技能需要在运行时提取资源文件（如提示词模板）到磁盘。这通过 safeWriteFile() 实现，使用了多重安全措施：

• 每进程 nonce 目录：使用随机命名的临时目录，防止路径预测
• owner-only 权限（0o700/0o600）：只有当前用户可以读写

懒提取：extractionPromise 被 memoize 化，多个并发调用等待同一个提取完成，而不是各自竞争。

9.10 MCP 技能集成

MCP（Model Context Protocol）服务端可以向 Claude Code 暴露技能，与本地技能无缝融合。

加载路径

MCP 技能通过 mcpSkillBuilders 注册表构建。当 SkillTool 获取所有命令时，同时加载本地和 MCP 技能，按名称去重。

安全模型

MCP 技能被视为不受信任的远程代码，施加了最严格的安全限制：

尽管受限，MCP 技能仍然可以使用参数替换（$ARGUMENTS）和所有非 Shell 的功能，且在 UI 和模型视角中与本地技能无差别。

9.11 技能级 Hook

技能可以在 frontmatter 中定义自己的 Hook，在技能执行期间生效：

hooks:
  PreToolUse:
    - matcher: "Bash(*)"
      hooks:
        - type: command
          command: "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"updatedInput\": {\"command\": \"$ORIGINAL_CMD --dry-run\"}}}'"

层级叠加

全局 Hook（settings.json）── 始终生效
  └── 技能级 Hook（技能 frontmatter）── 仅在该技能执行时生效

技能级 Hook 不覆盖全局 Hook，而是叠加。两者同时生效，全局 Hook 先执行。

Hook 注册时机

技能的 Hook 通过 registerSkillHooks() 在技能被调用时注册——不是启动时。这与懒加载原则一致：只在需要时激活。

校验与容错

Hook 定义通过 Zod schema 校验。如果定义格式错误：

• 记录警告日志
• 不阻止技能加载——一个无效的 Hook 不应该让整个技能无法使用
• 无效的 Hook 被忽略，有效部分正常生效

实际应用示例

部署技能的安全网：

hooks:
  PreToolUse:
    - matcher: "Bash(*)"
      hooks:
        - type: command
          command: "validate-deploy-command.sh"

日志收集技能：

hooks:
  PostToolUse:
    - matcher: "*"
      hooks:
        - type: command
          command: "log-tool-usage.sh $TOOL_NAME"

9.12 自定义技能实战

示例 1：代码审查技能（Fork 模式）

---
name: review
description: 审查当前分支的所有改动，检查代码质量和潜在问题
when_to_use: 当用户要求审查代码、检查改动、或在提交前做 review 时
argument-hint: 可选的关注点（如"安全性"、"性能"）
allowed-tools: [Bash, Read, Grep, Glob]
context: fork
---

审查当前分支相对于 main 的所有改动。

关注点：$ARGUMENTS

步骤：
1. 运行 `git diff main...HEAD` 查看所有改动
2. 逐文件分析代码质量
3. 检查：安全漏洞、错误处理、边界情况、命名规范
4. 输出结构化的审查报告，包括问题严重级别

选择 fork 的原因：审查需要大量 git diff、Read、Grep 调用，这些会污染主对话上下文。fork 模式让审查在隔离环境中完成，只返回最终报告。allowed-tools 限制为只读工具——审查不应该修改代码。

示例 2：代码风格检查（Inline 模式）

---
name: lint-check
description: 检查最近修改的文件是否符合项目代码风格
when_to_use: 当用户修改了代码后想快速检查风格一致性时
---

检查我最近修改的文件是否符合项目的代码风格约定。

步骤：
1. 运行 `git diff --name-only` 获取改动文件列表
2. 对每个文件运行项目配置的 linter
3. 汇总结果，如果有问题直接修复

选择 inline 的原因：这个技能可能需要修复代码（Edit 工具），需要完整的工具访问权限。它的工具调用量不大，不会严重污染上下文。

示例 3：快速检查（Fork + 不同模型）

---
name: quick-check
description: 用 Sonnet 快速检查代码的明显问题
context: fork
model: claude-sonnet
effort: quick
allowed-tools: [Read, Grep, Glob]
---

快速扫描以下文件的明显问题：$ARGUMENTS

重点关注：
- 未处理的异常
- 硬编码的密钥或密码
- 明显的逻辑错误

选择 fork + sonnet 的原因：这是一个快速检查，不需要深度思考。使用 Sonnet 更快且更便宜。fork 模式确保隔离。effort: quick 进一步降低思考深度。

whenToUse 写作技巧

whenToUse 字段决定了模型何时自动触发技能。好的 whenToUse 应该：

• 描述用户意图，而非用户的措辞："当用户需要审查代码质量时" 好于 "当用户说 review 时"
• 包含否定条件："当用户要求审查代码时，但不用于 PR 描述生成" 帮助模型区分相似场景
• 具体而非笼统："当用户修改了多个文件并想在提交前检查" 好于 "当用户需要帮助时"

9.13 SkillTool 的完整执行流程

当模型决定调用一个技能时，SkillTool 的 call() 方法执行以下步骤：

contextModifier 是返回值中的关键部分——它是一个函数，在后续回合中修改执行上下文：

• 如果技能指定了 allowedTools，追加到 alwaysAllowRules
• 如果技能指定了 model，覆盖 mainLoopModel
• 如果技能指定了 effort，覆盖 effortValue

9.14 设计洞察

1. 发现与执行分离：Frontmatter 用于浏览和发现（低成本），完整内容用于执行（按需加载）。这是管理大型工具集的通用模式——展示目录不需要加载全部内容

1. 白名单权限是前向兼容安全：新增属性默认需要权限审批。这比黑名单更安全——遗漏的黑名单条目是安全漏洞，遗漏的白名单条目只是多一次用户确认

1. Markdown + Frontmatter 是正确的格式选择：人类可读、版本控制友好、Git diff 清晰、不需要特殊工具。比 JSON/YAML 配置文件更适合包含大量提示词文本的场景

1. 双重调用模型扩展了技能的适用范围：纯手动触发（传统 slash command）限制了使用场景。模型自动触发让技能成为 Agent 行为的一部分——用户不需要记住命令名，只需要表达意图

1. 压缩后恢复确保长会话一致性：这是一个容易被忽略的细节——没有它，长对话中技能会"衰减"。按时间优先的预算分配是合理的启发式：最近使用的技能最可能仍然相关

1. fork 模式是隔离和安全的关键：它不只是"在另一个线程运行"——它是完整的权限隔离（限制工具）、上下文隔离（不污染主对话）、和模型隔离（可用不同模型）

1. MCP 技能的信任边界清晰：远程代码默认不受信任，安全限制是显式的。这比"默认信任、出了问题再修"的模式更健壮

动手实践：尝试在 .claude/skills/ 目录下创建一个自定义技能。从最简单的 inline 技能开始——只需要一个 SKILL.md 文件。观察它如何出现在 / 补全列表中，以及模型如何根据 when_to_use 自动触发它。

第 10 章：权限与安全

Claude Code 在用户的真实环境中执行代码——安全不是可选的附加功能，而是架构的基石。

10.1 纵深防御架构

Claude Code 采用纵深防御（Defense in Depth）策略。多个独立的安全层共同保护用户环境——即使某一层被绕过，其他层仍然有效。

Layer 1 — 工作区信任确认（Trust Dialog）：当你首次在一个目录中启动 Claude Code 时，系统会弹出信任确认对话框。这是第一道防线：如果用户选择不信任当前工作区，系统将禁用所有项目级 Hook 和自定义设置。这防止了一种常见攻击场景——恶意仓库在 .claude/ 目录下预埋 Hook 脚本，用户一 clone 就自动执行。只有在用户明确信任后，项目级配置才会生效。

Layer 2 — 权限模式：全局策略开关，决定系统的默认行为是"询问"、"自动允许"还是"自动拒绝"。详见 10.2 权限模式。

Layer 3 — 权限规则匹配：用户和管理员可以预定义 allow/deny/ask 规则列表，对特定工具或特定命令进行精确控制。例如 Bash(npm test:*) 允许所有 npm test 相关命令自动通过。详见 10.3 权限规则系统。

Layer 4 — Bash 多层安全：Bash 是攻击面最大的工具，因此有独立的多层安全验证体系，包括 tree-sitter AST 解析、23 项静态安全检查、路径约束验证等。详见 10.6 Bash 命令的多层安全验证。

Layer 5 — 工具级安全：每个工具声明自己的安全属性并实现专属的验证逻辑。validateInput 方法在权限检查之前验证输入合法性（如检查文件路径格式）；checkPermissions 方法执行工具特有的安全逻辑（如文件编辑工具检查目标是否为危险文件）。只读工具（如 Read、Glob、Grep）在大多数模式下可自动通过。

Layer 6 — 沙箱与隔离：这一层提供两种隔离机制。Sandbox 通过操作系统级进程隔离（macOS 用 Seatbelt，Linux 用命名空间）限制 Bash 命令的文件系统、网络和进程权限。Git Worktree 提供文件级隔离——子 Agent 在独立的 worktree 中工作，完成后如果没有实质修改则自动清理，防止子 Agent 的实验性操作污染主工作目录。详见 10.9 沙箱设计。

Layer 7 — 用户确认：当前面所有自动化层都无法做出决策时，最终由人类决定。交互式对话框同时启动 Hook 检查和 ML 分类器，三者竞速——但一旦用户亲自操作对话框，自动化结果一律丢弃，人类意图永远优先。详见 10.5 三种权限处理器。

为什么不用一个统一的权限检查代替 7 层？因为纵深防御的核心假设是"每一层都可能被绕过"。如果只有工具级检查，一个巧妙的命令注入就可能绕过全部安全机制。7 层架构中，即使 AST 语义分析被绕过，路径约束和用户确认仍然可以拦截。

10.2 权限模式

Claude Code 定义了 5 种外部权限模式和 2 种内部模式：

下面逐一解释每种模式的行为和设计动机：

default 模式

这是最常用的模式。工具调用的决策链路如下：先检查 deny 规则，命中则直接拒绝；再检查 allow 规则，命中则自动通过；两者都不命中时，弹出交互式确认对话框让用户决定。用户在对话框中可以选择"一次性允许"或"始终允许"（后者会将规则持久化到配置文件）。

这个模式体现了"默认安全"原则：未知的操作一律询问用户，而不是静默允许或静默拒绝。

acceptEdits 模式

自动批准文件编辑类工具（Edit、Write、NotebookEdit），以及 Bash 中的文件操作命令（mkdir、touch、rm、rmdir、mv、cp、sed）。其他 Bash 命令仍需确认。

但危险文件和目录的安全检查是 bypass-immune 的——即使在 acceptEdits 模式下，编辑 .git/、.bashrc、.claude/settings.json 等敏感路径仍然需要用户确认。这个设计确保了即使用户选择了宽松模式，安全底线也不会被突破（详见 10.7 危险文件与目录保护）。

plan 模式

模型生成操作计划但暂停执行，每个工具调用都需要用户明确批准。适合审查敏感操作或不熟悉的代码库。plan 模式还可以与 auto 模式结合：如果用户原本使用 bypassPermissions，进入 plan 模式后系统会记住 prePlanMode，plan 审查通过后按原模式执行。

bypassPermissions 模式

全部工具调用自动批准——但这并不意味着毫无限制。deny 规则和 bypass-immune 安全检查仍然生效。源码中的检查顺序是关键：

1. 先检查 deny 规则          → 命中直接拒绝，不管什么模式
2. 先检查安全路径检查         → .git/、.claude/ 等 bypass-immune 路径仍需确认
3. 然后才检查 bypassPermissions → 只有通过了上面两关，才会自动允许

这意味着管理员可以通过 deny 规则对 bypassPermissions 模式施加约束，例如 deny Bash(rm -rf:*) 即使在 bypass 模式下也会生效。

源码：src/utils/permissions/permissions.ts:1262-1281

dontAsk 模式

与 bypassPermissions 相反：将所有需要"询问用户"的决策转为"拒绝"。为 CI/CD 和无人值守环境设计——没有人可以回答确认对话框，所以不确定的操作宁可拒绝也不能挂起等待。allow 和 deny 规则仍然生效，只是 ask 被替换为 deny。

内部模式

auto 模式：使用 ML 分类器（transcript classifier）自动做出权限决策，无需用户交互。分类器分析当前对话上下文和工具调用意图来判断操作是否安全。这是一个 feature-gated 的内部功能（TRANSCRIPT_CLASSIFIER）。当分类器无法判断或累积拒绝超过阈值时，回退到交互模式。

bubble 模式：多 Agent 协调器（Coordinator）专用。Worker Agent 使用此模式将无法决策的权限请求"冒泡"到协调器层面处理，避免 Worker 之间的权限决策冲突。

10.3 权限规则系统

权限规则是整个权限系统的基础数据结构。理解规则的格式、匹配方式和优先级，是理解后续所有安全机制的前提。

规则格式

每条规则由两部分组成：工具名 和可选的 内容匹配模式。

ToolName              → 匹配该工具的所有调用
ToolName(content)     → 匹配该工具中特定内容的调用

对于 Bash 工具，content 就是命令字符串。例如：

对于 MCP 工具，规则支持服务器级别匹配：mcp__server1 匹配该服务器的所有工具，mcp__server1__tool1 匹配特定工具。

源码：src/utils/permissions/permissionRuleParser.ts，src/utils/permissions/shellRuleMatching.ts

三种匹配类型

规则解析器（parsePermissionRule）将规则内容解析为三种类型之一：

精确匹配：规则内容不含 : 后缀也不含未转义的 。命令必须与规则内容完全相同才能匹配。例如 npm install 只匹配 npm install，不匹配 npm install lodash。

前缀匹配（legacy : 语法）：规则以 : 结尾。剥离 : 后，命令以该前缀开头即匹配。例如 npm: 匹配 npm、npm install、npm run build。注意 npm:* 也匹配裸 npm（无参数），这是刻意设计——允许前缀意味着信任该命令的所有用法。

通配符匹配：规则包含未转义的 。 被转为正则的 .，匹配任意字符序列。例如 git --no-verify 匹配 git commit --no-verify、git push --no-verify。

一个精巧的细节：当模式以 （空格+通配符）结尾，且整个模式只有这一个通配符时，尾部会变为可选的——git 既匹配 git commit 也匹配裸 git。这让通配符语法与前缀语法的行为保持一致。

// 源码简化示意
if (regexPattern.endsWith(' .*') && unescapedStarCount === 1) {
  regexPattern = regexPattern.slice(0, -3) + '( .*)?'
}

如果需要匹配字面量 （比如命令中真的有星号），用 \ 转义。

源码：src/utils/permissions/shellRuleMatching.ts

三种规则行为

每条规则关联一种行为：

• allow：匹配的操作自动批准，无需用户确认
• deny：匹配的操作直接拒绝，用户无法覆盖（除非删除规则）
• ask：匹配的操作强制弹出确认对话框，即使在 bypassPermissions 模式下也要确认

ask 规则的存在是一个重要的安全设计：即使你对大多数操作使用 bypass 模式，也可以对特定高危操作（如 npm publish、git push --force）设置 ask 规则作为安全阀。

规则来源与优先级

规则可以来自多个来源，按以下优先级排列（高优先级在前）：

这个优先级设计满足了企业场景的需求：企业策略（policySettings）优先级最高，管理员可以通过 MDM 下发强制规则，用户无法覆盖。同时，allowManagedPermissionRulesOnly 选项可以限制用户只能使用管理策略定义的规则，进一步收紧控制。

源码：src/utils/permissions/permissions.ts，src/utils/permissions/permissionsLoader.ts

实际配置示例

// ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",           // 允许所有 npm test 命令
      "Bash(git status)",           // 允许 git status
      "Bash(git diff:*)",           // 允许所有 git diff 命令
      "Read",                       // 允许所有文件读取
      "Glob",                       // 允许所有文件搜索
      "mcp__filesystem"             // 允许 filesystem MCP 服务器所有工具
    ],
    "deny": [
      "Bash(rm -rf:*)",            // 禁止所有 rm -rf 命令
      "Bash(git push --force:*)"   // 禁止 force push
    ],
    "ask": [
      "Bash(npm publish:*)",       // 发布包时必须确认
      "Bash(git push:*)"           // push 时必须确认
    ]
  }
}

当模型调用 Bash(npm test --coverage) 时，系统匹配到 allow 规则 Bash(npm test:*) 并自动通过；调用 Bash(npm publish) 时，匹配到 ask 规则，即使在 bypassPermissions 模式下也会弹出确认对话框。

10.4 权限决策完整流程

理解了规则系统后，我们来看完整的权限决策流程。每次工具调用都经过 hasPermissionsToUseToolInner 函数，这是整个权限系统的核心调度器。

让我们逐步解读这个流程：

Step 1a — 工具级 deny 规则：首先检查是否有规则直接拒绝整个工具（如 deny 规则 Bash 会禁止所有 Bash 命令）。如果命中，直接拒绝，不进入后续任何检查。

Step 1b — 工具级 ask 规则：检查是否有规则要求整个工具必须确认。这里有一个例外：如果沙箱已启用且配置了 autoAllowBashIfSandboxed，沙箱化的命令可以跳过 ask 规则自动通过——因为沙箱本身已经限制了命令的能力。

Step 1c — 工具自身的权限检查：调用 tool.checkPermissions(parsedInput, context)。每个工具实现自己的逻辑：

• BashTool：执行完整的多层安全验证（AST 解析、静态检查、路径约束等），详见 10.6
• FileEditTool / FileWriteTool：检查目标文件是否在危险列表中，是否在允许的工作目录内
• 只读工具（Read、Glob、Grep）：通常返回 allow

Step 1d-1g — 处理工具返回结果：这里有几个关键的 bypass-immune 场景：

• 1f：如果工具返回的 ask 携带了用户配置的 ask 规则作为原因（如 Bash(npm publish:*) ask 规则），即使在 bypassPermissions 模式下也必须确认。这确保了用户对特定操作设置的安全阀不会被 bypass 绕过。
• 1g：安全路径检查（.git/、.claude/、.bashrc 等）返回的 ask 是 bypass-immune 的——这些路径太敏感，任何模式下都不应该自动通过。

Step 2a — 检查 bypass 模式：注意这一步在 deny 规则和 safety check 之后。deny 规则和安全检查的优先级高于 bypassPermissions 模式——这是整个流程中最关键的设计决策。

Step 2b — 检查 allow 规则：如果存在匹配的 allow 规则，自动通过。

Step 3 — 兜底为 ask：如果前面所有检查都没有得出明确结论（工具返回了 passthrough），则转为 ask，弹出确认对话框。

源码：src/utils/permissions/permissions.ts:1158-1319，函数 hasPermissionsToUseToolInner

10.5 三种权限处理器

当权限决策流程得出 ask 结论后，如何向用户展示确认对话框？不同的执行上下文使用不同的权限处理器：

InteractiveHandler 的竞速机制

这是最精巧的设计——用户确认和自动化检查同时进行：

关键细节：

• createResolveOnce 守卫确保只有第一个决定生效
• userInteracted 标志：一旦用户触碰对话框，分类器结果被丢弃
• 200ms 防误触宽限期：避免用户意外按键导致错误决策

竞速机制的代码实现

// createResolveOnce：确保只有第一个决定生效
function createResolveOnce<T>() {
  let resolved = false
  let resolve: (value: T) => void
  const promise = new Promise<T>(r => { resolve = r })

  return {
    promise,
    resolve: (value: T) => {
      if (resolved) return    // 后续决定被丢弃
      resolved = true
      resolve(value)
    }
  }
}

// InteractiveHandler 的并行决策流程
async function handlePermission(request: PermissionRequest) {
  const { promise, resolve } = createResolveOnce<Decision>()
  let userInteracted = false

  // 同时启动三个决策源
  showUIDialog(request, (decision) => {
    userInteracted = true
    resolve(decision)
  })

  runHook('PermissionRequest', request).then(hookResult => {
    if (!userInteracted) resolve(hookResult)
  })

  runClassifier(request).then(classifierResult => {
    if (!userInteracted) resolve(classifierResult)
  })

  // 200ms 防误触：对话框显示后 200ms 内的按键被忽略
  await sleep(200)
  enableDialogInput()

  return promise
}

设计考量：200ms 宽限期的目的是防止用户在对话框刚弹出时意外按下回车键，从而误批准危险操作。一旦用户与对话框产生交互（任何按键或点击），userInteracted 标志被设置，之后 Hook 和分类器的自动化结果都会被丢弃——人类意图永远优先。

权限解释器（Permission Explainer）

在确认对话框中，用户不仅看到命令本身，还会看到一个 AI 生成的风险解释。这个解释由 Haiku 模型（轻量快速）通过 sideQuery 并行生成，与对话框同时启动，不阻塞用户操作。

解释包含四个维度：

type PermissionExplanation = {
  explanation: string   // 这条命令做什么（1-2 句话）
  reasoning: string     // 为什么要执行它（以 "I" 开头，如 "I need to check..."）
  risk: string          // 可能出什么问题（15 词以内）
  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH'
    // LOW: 安全的开发工作流（读取文件、运行测试）
    // MEDIUM: 可恢复的变更（编辑文件、安装依赖）
    // HIGH: 危险/不可逆操作（删除文件、修改系统配置）
}

这个设计让用户在做决策时拥有充分的上下文信息，而不是面对一个裸命令凭直觉判断。特别是对于不熟悉的命令（如复杂的 sed 或 awk 表达式），解释器可以大幅降低用户误判的概率。

源码：src/utils/permissions/permissionExplainer.ts

CoordinatorHandler

CoordinatorHandler 用于协调器（Coordinator）模式下的 Worker Agent。与 InteractiveHandler 的并行竞速不同，它采用顺序执行策略：

1. 先执行 Hook — 如果 PermissionRequest Hook 返回了明确决策（allow/deny），直接使用
2. 再执行分类器 — Hook 未决时，运行 ML 分类器尝试自动判断
3. 最后显示对话框 — 如果前两者都无法决定，才向用户展示交互式确认

这种顺序设计避免了多个 Worker 同时弹出对话框的混乱场景。

SwarmWorkerHandler

SwarmWorkerHandler 用于子 Agent（Swarm Worker）场景。它的权限处理最为保守：

• 继承父 Agent 的权限决策：子 Agent 不会独立发起权限请求，而是复用父 Agent 已批准的权限
• 受限的工具集：子 Agent 只能使用父 Agent 明确授权的工具子集
• 无直接用户交互：子 Agent 不能弹出确认对话框，未授权的操作直接拒绝

10.6 Bash 命令的多层安全验证

BashTool 是攻击面最大的工具——它可以执行任意 Shell 命令，因此有最严格的安全验证体系。

bashToolHasPermission 入口流程

bashToolHasPermission 是 Bash 权限检查的总入口（src/tools/BashTool/bashPermissions.ts:1663）。每条命令经过以下检查链：

Tree-sitter AST 安全解析

这是 Bash 安全体系中最重要的创新。传统方法（正则表达式 + 手工字符遍历）在面对 Shell 的复杂语法时容易出现解析器差异（parser differential）——安全检查器理解的命令含义与 Bash 实际执行的含义不同，攻击者可以利用这种差异绕过检查。

tree-sitter 方案用一个真正的 Bash 语法解析器替代了手工解析，核心设计原则是 FAIL-CLOSED：不理解的结构一律不信任。

// ast.ts 的核心设计
// 源码注释原文：
// "The key design property is FAIL-CLOSED: we never interpret structure we
//  don't understand. If tree-sitter produces a node we haven't explicitly
//  allowlisted, we refuse to extract argv and the caller must ask the user."

解析结果是三选一的枚举：

什么会触发 too-complex？ 任何不在白名单中的 AST 节点类型。白名单非常保守：

// 只有这 4 种结构节点会被递归遍历
const STRUCTURAL_TYPES = new Set([
  'program',              // 根节点
  'list',                 // a && b || c
  'pipeline',             // a | b
  'redirected_statement',  // 带重定向的命令
])

// 只有这些分隔符被允许
const SEPARATOR_TYPES = new Set(['&&', '||', '|', ';', '&', '|&', '\n'])

这意味着以下结构都会被标记为 too-complex，需要用户确认：

• 命令替换 $(cmd) 或 ` cmd `
• 变量展开 ${var}
• 算术展开 $((expr))
• 控制流 if/for/while/case
• 函数定义
• 进程替换 <(cmd) / >(cmd)

checkSemantics — 语义级安全检查

即使命令通过了 AST 解析（结果为 simple），还需要检查语义层面的危险。有些命令在语法上完全合法，但在语义上是危险的：

• eval "rm -rf /" — eval 可以执行任意字符串
• zmodload zsh/net/tcp — 加载 zsh 网络模块
• emulate sh -c 'dangerous_code' — 改变 shell 行为并执行代码

checkSemantics 检查 argv[0] 是否是已知的危险命令（eval、zsh 内建等），如果是则标记为需要确认。

Shadow 测试策略

tree-sitter 是新引入的解析方案，为了保证稳定性，Claude Code 采用了渐进式迁移策略：

1. Shadow 模式（TREE_SITTER_BASH_SHADOW feature gate）：tree-sitter 与 legacy splitCommand_DEPRECATED 并行运行
2. 两者的解析结果被比较，分歧记录到遥测事件 tengu_tree_sitter_shadow
3. 但最终决策仍然使用 legacy 路径——shadow 模式纯粹是观察性的
4. 当遥测数据证明 tree-sitter 足够可靠后，才会切换为权威路径

这种"先观察、再切换"的策略在安全关键系统中非常常见——它允许团队在生产环境中收集真实数据，而不是在测试环境中猜测。

源码：src/utils/bash/ast.ts，src/tools/BashTool/bashPermissions.ts:1670-1806

23 项静态安全验证器

src/tools/BashTool/bashSecurity.ts 包含 23 项独立的检查，每一项针对特定的攻击向量：