8 · 子智能体

tools/AgentTool/ 目录，主文件 228 KB。这是所有工具里最复杂的一个 —— 因为它的作用是递归地启动另一个完整的智能体。

8.1 首要动机是上下文隔离，不是并行

8.2 三种形态

8.3 分叉：把提示词缓存用到极致

分叉的典型用法是「同时派 5 个子智能体，从不同角度探索同一个问题」。这 5 个的上下文几乎完全一样 —— 唯一区别是最后那句「你负责方向 A / B / C / D / E」。

提示词缓存是前缀匹配的。所以：

为此做的四件事

① 系统提示词传「已渲染好的字节」

/**
 * The getSystemPrompt here is unused: the fork path passes
 * `override.systemPrompt` with the parent's already-rendered system prompt
 * bytes, threaded via `toolUseContext.renderedSystemPrompt`. Reconstructing
 * by re-calling getSystemPrompt() can diverge (GrowthBook cold→warm)
 * and bust the prompt cache; threading the rendered bytes is byte-exact.
 */

claude-code/src/tools/AgentTool/forkSubagent.ts

译：这里的 getSystemPrompt 是没用到的：分叉路径传递的是父已经渲染好的系统提示词字节，通过 renderedSystemPrompt 字段串下来。重新调用生成函数可能产生分歧（因为特性开关配置可能从冷缓存变成热缓存），从而毁掉提示词缓存；传递已渲染的字节是字节级精确的。

展开解释这个坑：系统提示词的内容并不完全固定，它可能包含 A/B 实验的变体。而实验配置本身有缓存 —— 父智能体生成提示词的那一刻，某个实验配置可能还是「冷缓存」状态（用默认值）；几秒后子智能体重新生成时，配置已经变成「热缓存」（用真实值）。两次生成的字节不同，缓存全废。

对应的字段在 Tool.ts 里有定义：

/**
 * Parent's rendered system prompt bytes, frozen at turn start.
 * Used by fork subagents to share the parent's prompt cache — re-calling
 * getSystemPrompt() at fork-spawn time can diverge (GrowthBook cold→warm)
 * and bust the cache. See forkSubagent.ts.
 */
renderedSystemPrompt?: SystemPrompt

「frozen at turn start」（在轮次开始时冻结） —— 这是关键。

② 工具清单原样继承

/**
 * Synthetic agent definition for the fork path.
 *
 * Not registered in builtInAgents — used only when `!subagent_type` and the
 * experiment is active. `tools: ['*']` with `useExactTools` means the fork
 * child receives the parent's exact tool pool (for cache-identical API
 * prefixes). `permissionMode: 'bubble'` surfaces permission prompts to the
 * parent terminal. `model: 'inherit'` keeps the parent's model for context
 * length parity.
 */
export const FORK_AGENT = {
  tools: ['*'],
  permissionMode: 'bubble',
  model: 'inherit',
  ...
}

三个字段各有理由：

• tools: ['*'] 配合 useExactTools —— 子智能体拿到父的精确工具池。它用不到那么多工具，但工具定义是请求前缀的一部分，改了就没缓存。
• permissionMode: 'bubble' —— 权限确认冒泡到父智能体所在的终端。子智能体自己没有界面。
• model: 'inherit' —— 继承父的模型，保证上下文窗口大小一致。如果子用了窗口更小的模型，继承来的历史可能直接放不下。

③ 消息构造：只让最后一个文本块不同

/**
 * Build the forked conversation messages for the child agent.
 *
 * For prompt cache sharing, all fork children must produce byte-identical
 * API request prefixes. This function:
 * 1. Keeps the full parent assistant message (all tool_use blocks, thinking, text)
 * 2. Builds a single user message with tool_results for every tool_use block
 *    using an identical placeholder, then appends a per-child directive text block
 *
 * Result: [...history, assistant(all_tool_uses), user(placeholder_results..., directive)]
 * Only the final text block differs per child, maximizing cache hits.
 */
export function buildForkedMessages(...)

那个「占位工具结果」的巧妙之处：父那条消息里有 5 个工具调用（每个对应一个分叉）。按接口规则，每个工具调用必须有配对的结果。但这 5 个分叉还没跑完，真实结果不存在。于是给每一个都填完全相同的占位内容 —— 既满足配对要求，又保证 5 个子智能体看到的这段一模一样。

源码里还有一个专门的常量：

/** Must be identical across all fork children for prompt cache sharing. */

④ 递归分叉守卫：从接口层下移到调用层

/**
 * Guard against recursive forking. Fork children keep the Agent tool in their
 * tool pool for cache-identical tool definitions, so we reject fork attempts
 * at call time by detecting the fork boilerplate tag in conversation history.
 */
export function isInForkChild(messages: MessageType[]): boolean { ... }

常规做法是「把 Agent 工具从子智能体的工具池里去掉」。但那样就改变了工具定义，破坏缓存。所以改为：工具留着，但在真正调用的那一刻检查对话历史里有没有分叉标记：

if (isInForkChild(toolUseContext.messages)) {
  throw new Error('Fork is not available inside a forked worker. '
                + 'Complete your task directly using your tools.')
}

工作树隔离的额外提示

/**
 * Notice injected into fork children running in an isolated worktree.
 * Tells the child to translate paths from the inherited context, re-read
 * potentially stale files, and that its changes are isolated.
 */
export function buildWorktreeNotice(...)

如果分叉子智能体跑在隔离的 git 工作树里，它继承的历史里那些文件路径指向的是父的目录。所以要显式告诉它：路径要翻译、文件可能已经不是你看到的那个版本、你的修改是隔离的。

8.4 子智能体的工具限制

export const ALL_AGENT_DISALLOWED_TOOLS = new Set([
  TASK_OUTPUT_TOOL_NAME,        // 不能查看其他任务的输出
  EXIT_PLAN_MODE_V2_TOOL_NAME,  // 不能退出计划模式（会话级全局状态）
  ENTER_PLAN_MODE_TOOL_NAME,    // 不能进入计划模式
  // 内部用户允许嵌套子智能体，外部用户不允许
  ...(process.env.USER_TYPE === 'ant' ? [] : [AGENT_TOOL_NAME]),
  ASK_USER_QUESTION_TOOL_NAME,  // ★ 不能向用户提问
  TASK_STOP_TOOL_NAME,          // 不能停止其他任务
  // 防止在子智能体内递归执行工作流
  ...(feature('WORKFLOW_SCRIPTS') ? [WORKFLOW_TOOL_NAME] : []),
])

export const CUSTOM_AGENT_DISALLOWED_TOOLS = new Set([...ALL_AGENT_DISALLOWED_TOOLS])

claude-code/src/constants/tools.ts

后台异步智能体的白名单更严格

/*
 * Async Agent Tool Availability Status (Source of Truth)
 */
export const ASYNC_AGENT_ALLOWED_TOOLS = new Set([
  FILE_READ_TOOL_NAME,      // 读文件
  WEB_SEARCH_TOOL_NAME,     // 网络搜索
  TODO_WRITE_TOOL_NAME,     // 待办清单
  GREP_TOOL_NAME,           // 内容搜索
  WEB_FETCH_TOOL_NAME,      // 抓网页
  GLOB_TOOL_NAME,           // 文件名搜索
  ...
])

注意这里从「黑名单」变成了「白名单」 —— 而且几乎全是只读工具。

8.5 子智能体的上下文构造

创建子智能体时会构造一个新的 ToolUseContext。有几个字段的处理很讲究：

/**
 * Always-shared setAppState for session-scoped infrastructure (background
 * tasks, session hooks). Unlike setAppState, which is no-op for async agents
 * (see createSubagentContext), this always reaches the root store so agents
 * at any nesting depth can register/clean up infrastructure that outlives
 * a single turn. Only set by createSubagentContext; main-thread contexts
 * fall back to setAppState.
 */
setAppStateForTasks?: (f: (prev: AppState) => AppState) => void

译：供会话级基础设施（后台任务、会话钩子）使用的「永远共享」的状态写入函数。不同于普通的 setAppState（对异步智能体是空操作），这个函数总能抵达根存储 —— 这样任意嵌套深度的智能体都能注册或清理那些生命周期超过单轮的基础设施。只有创建子智能体上下文时才设置它；主线程上下文回退到普通的 setAppState。

另外两个相关字段：

agentId?: AgentId      // 只有子智能体才设置；钩子用它来区分是不是子智能体调用
agentType?: string     // 子智能体的类型名

/** When true, preserve toolUseResult on messages even for subagents.
 *  Used by in-process teammates whose transcripts are viewable by the user. */
preserveToolUseResults?: boolean

最后那个字段说明：默认情况下子智能体的工具结果会被丢弃（省内存，反正用户看不到）。但「进程内队友」这种形态的子智能体，它的对话记录是用户可见的，所以要保留。

8.6 内建智能体类型

tools/AgentTool/builtInAgents.ts 定义了几个内建类型，其中最常用的是：

用户还可以自定义 —— 在 .claude/agents/*.md 里写一个 Markdown 文件，头部元数据声明名字、描述、可用工具、模型。loadAgentsDir.ts 负责加载。

8.7 后台任务的几种形态

tasks/ 目录下有多种任务形态，它们的差别在于「跑在哪里」和「怎么通信」：

任务的完成通过消息队列通知回主循环 —— 就是第 3.9 节讲的那个「进程级全局队列」，每个智能体只取走发给自己的通知。

8.8 中断的级联

中止控制器构成一棵树：