第12章：Agent 调度 —— fork 与 fresh 两条路

AgentTool.call()      调度总控：选 agent、分流模式、前置校验     1397 行
      ↓
runAgent()            子 agent 的上下文构造与生命周期管理        973 行
      ↓
query()               真正的模型循环（第 3 章）                 1729 行

const baseInputSchema = z.object({
  description: z.string().describe('A short (3-5 word) description of the task'),
  prompt: z.string().describe('The task for the agent to perform'),
  subagent_type: z.string().optional().describe('The type of specialized agent to use for this task'),
  model: z.enum(['sonnet', 'opus', 'haiku']).optional().describe(
    "Optional model override for this agent. Takes precedence over the agent definition's model frontmatter. If omitted, uses the agent definition's model, or inherits from the parent."),
  run_in_background: z.boolean().optional(),
})

// 多 agent + 隔离参数
const multiAgentInputSchema = z.object({
  name: …, team_name: …, mode: …,
  isolation: z.enum(['worktree'])   // 内部版还有 'remote'
    .optional().describe('Isolation mode. "worktree" creates a temporary git worktree so the agent works on an isolated copy of the repo.'),
  cwd: z.string().optional().describe('Absolute path to run the agent in. … Mutually exclusive with isolation: "worktree".'),
})

// 1. 没有 Agent Teams 权限却传了 team_name
if (team_name && !isAgentSwarmsEnabled()) throw new Error('Agent Teams is not yet available on your plan.')

// 2. teammate 不能再生 teammate
if (isTeammate() && teamName && name) throw new Error(
  'Teammates cannot spawn other teammates — the team roster is flat. To spawn a subagent instead, omit the `name` parameter.')

// 3. 进程内 teammate 不能开后台 agent
if (isInProcessTeammate() && teamName && run_in_background === true) throw new Error(
  'In-process teammates cannot spawn background agents. Use run_in_background=false for synchronous subagents.')

teamName && name        → spawnTeammate()      多 agent 团队成员
isolation === 'remote'  → teleportToRemote()   远程 CCR 环境 [内部]
isolation === 'worktree'→ 建 git worktree 再跑
默认                     → runAgent()

// 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

// Recursive fork guard: fork children keep the Agent tool in their
// pool for cache-identical tool defs, so reject fork attempts at call
// time. Primary check is querySource (compaction-resistant — set on
// context.options at spawn time, survives autocompact's message
// rewrite). Message-scan fallback catches any path where querySource
// wasn't threaded.
if (toolUseContext.options.querySource === `agent:builtin:${FORK_AGENT.agentType}`
    || isInForkChild(toolUseContext.messages)) {
  throw new Error('Fork is not available inside a forked worker. Complete your task directly using your tools.')
}

export function isInForkChild(messages: MessageType[]): boolean {
  return messages.some(m =>
    m.type === 'user' && Array.isArray(m.message.content) &&
    m.message.content.some(b => b.type === 'text' && b.text.includes(`<${FORK_BOILERPLATE_TAG}>`)))
}

if (hasPendingRequiredServers) {
  const MAX_WAIT_MS = 30_000
  const POLL_INTERVAL_MS = 500
  const deadline = Date.now() + MAX_WAIT_MS
  while (Date.now() < deadline) {
    await sleep(POLL_INTERVAL_MS)
    currentAppState = toolUseContext.getAppState()
    // Early exit: if any required server has already failed, no point
    // waiting for other pending servers
    if (hasFailedRequiredServer) break
    if (!stillPending) break
  }
}

// Get servers that actually have tools (meaning they're connected AND authenticated)

Agent 'X' requires MCP servers matching: A, B.
MCP servers with tools: C, D.
Use /mcp to configure and authenticate the required MCP servers.

/**
 * 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.
 *
 * 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.
 */
export const FORK_AGENT = {
  agentType: 'fork',
  whenToUse: 'Implicit fork — inherits full conversation context. Not selectable via subagent_type…',
  tools: ['*'],
  maxTurns: 200,
  model: 'inherit',
  permissionMode: 'bubble',
  source: 'built-in',
  baseDir: 'built-in',
  getSystemPrompt: () => '',
}

/** Placeholder text used for all tool_result blocks in the fork prefix.
 * Must be identical across all fork children for prompt cache sharing. */
const FORK_PLACEHOLDER_RESULT = 'Fork started — processing in background'

/**
 * 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(directive: string, assistantMessage: AssistantMessage): MessageType[]

[……历史……]
[assistant: tool_use(fork1), tool_use(fork2), tool_use(fork3)]
[user: tool_result(fork1, "Fork started — processing in background"),
       tool_result(fork2, "Fork started — processing in background"),
       tool_result(fork3, "Fork started — processing in background"),
       text("<fork-boilerplate>…</fork-boilerplate>\n\n<你自己的指令>")]     ← 只有这一块不同

// TODO(smoosh): this text sibling creates a [tool_result, text] pattern on the wire
// (renders as </function_results>\n\nHuman:<text>). One-off per-child construction,
// not a repeated teacher, so low-priority. If we ever care, use smooshIntoToolResult
// from src/utils/messages.ts to fold the directive into the last tool_result.content.

export function buildChildMessage(directive: string): string {
  return `<${FORK_BOILERPLATE_TAG}>
STOP. READ THIS FIRST.

You are a forked worker process. You are NOT the main agent.

RULES (non-negotiable):
1. Your system prompt says "default to forking." IGNORE IT — that's for the parent. You ARE the fork. Do NOT spawn sub-agents; execute directly.
2. Do NOT converse, ask questions, or suggest next steps
3. Do NOT editorialize or add meta-commentary
4. USE your tools directly: Bash, Read, Write, etc.
5. If you modify files, commit your changes before reporting. Include the commit hash in your report.
6. Do NOT emit text between tool calls. Use tools silently, then report once at the end.
7. Stay strictly within your directive's scope. If you discover related systems outside your scope, mention them in one sentence at most — other workers cover those areas.
8. Keep your report under 500 words unless the directive specifies otherwise. Be factual and concise.
9. Your response MUST begin with "Scope:". No preamble, no thinking-out-loud.
10. REPORT structured facts, then stop

Output format (plain text labels, not markdown headers):
  Scope: <echo back your assigned scope in one sentence>
  Result: <the answer or key findings, limited to the scope above>
  Key files: <relevant file paths — include for research tasks>
  Files changed: <list with commit hash — include only if you modified files>
  Issues: <list — include only if there are issues to flag>
</${FORK_BOILERPLATE_TAG}>

${FORK_DIRECTIVE_PREFIX}${directive}`
}

export function buildWorktreeNotice(parentCwd: string, worktreeCwd: string): string {
  return `You've inherited the conversation context above from a parent agent working in ${parentCwd}. You are operating in an isolated git worktree at ${worktreeCwd} — same repository, same relative file structure, separate working copy. Paths in the inherited context refer to the parent's working directory; translate them to your worktree root. Re-read files before editing if the parent may have modified them since they appear in the context. Your changes stay in this worktree and will not affect the parent's files.`
}

① 解析模型、创建 agentId、注册 Perfetto 追踪
② 过滤父进程消息里未完成的工具调用（避免 API 报错）
③ 准备 userContext / systemContext
④ 只读 agent 瘦身：砍掉 claudeMd 和 gitStatus
⑤ 构造 agent 专属的权限上下文
⑥ 解析工具池（fork 用 useExactTools）
⑦ 拿系统提示词（fork 直接用父进程渲染好的字节）
⑧ 决定 abortController（异步 agent 用新的、同步 agent 共享父的）
⑨ 跑 SubagentStart 钩子，收集额外上下文
⑩ 注册 frontmatter 里声明的钩子
⑪ 预加载 frontmatter 里声明的技能
⑫ 初始化 agent 专属的 MCP 服务器
⑬ 合并 MCP 工具
⑭ 构造子 agent 的 ToolUseContext
⑮ 调 query()
⑯ 记录 sidechain transcript、写元数据
⑰ 清理：MCP、钩子、Perfetto、todo、bash 任务、文件状态缓存

// Read-only agents (Explore, Plan) don't act on commit/PR/lint rules from
// CLAUDE.md — the main agent has full context and interprets their output.
// Dropping claudeMd here saves ~5-15 Gtok/week across 34M+ Explore spawns.
// Explicit override.userContext from callers is preserved untouched.
// Kill-switch defaults true; flip tengu_slim_subagent_claudemd=false to revert.
const { claudeMd: _omittedClaudeMd, ...userContextNoClaudeMd } = baseUserContext

// Explore/Plan are read-only search agents — the parent-session-start
// gitStatus (up to 40KB, explicitly labeled stale) is dead weight. If they
// need git info they run `git status` themselves and get fresh data.
// Saves ~1-3 Gtok/week fleet-wide.
const { gitStatus: _omittedGitStatus, ...systemContextNoGit } = baseSystemContext

omitClaudeMd: true,

const agentGetAppState = () => {
  const state = toolUseContext.getAppState()
  // Override permission mode if agent defines one (unless parent is
  // bypassPermissions, acceptEdits, or auto)
  …
  // Set flag to auto-deny prompts for agents that can't show UI
  // Use explicit canShowPermissionPrompts if provided, otherwise:
  //   - bubble mode: always show prompts (bubbles to parent terminal)
  //   - default: !isAsync (sync agents show prompts, async agents don't)
  const shouldAvoidPrompts = …
  // For background agents that can show prompts, await automated checks
  // (classifier, permission hooks) before showing the permission dialog.
  // Since these are background agents, waiting is fine — the user should
  // only be interrupted when automated checks can't resolve the permission.
  …
  // Scope tool permissions: when allowedTools is provided, use them as session rules.
  // IMPORTANT: Preserve cliArg rules (from SDK's --allowedTools) since those are
  // explicit permissions from the SDK consumer that should apply to all agents.
  // Only clear session-level rules from the parent to prevent unintended leakage.
}

async function initializeAgentMcpServers(agentDefinition, …) {
  // If no agent-specific servers defined, return parent clients as-is
  …
  // When MCP is locked to plugin-only, skip frontmatter MCP servers for
  // USER-CONTROLLED agents only. Plugin, built-in, and policySettings agents
  // are admin-trusted — their frontmatter MCP is part of the admin-approved
  // surface. Blocking them (as the first cut did) breaks plugin agents that
  // legitimately need MCP, contradicting "plugin-provided always loads."
  const agentIsAdminTrusted = isSourceAdminTrusted(agentDefinition.source)
  …
  for (const spec of agentDefinition.mcpServers) {
    if (typeof spec === 'string') {
      // Reference by name - look up in existing MCP configs
      // This uses the memoized connectToServer, so we may get a shared client
    } else {
      // Inline definition as { [name]: config }
      // These are agent-specific servers that should be cleaned up
    }
  }
  // Only clean up newly created clients (inline definitions), not shared/referenced ones
}

const skillsToPreload = agentDefinition.skills ?? []
if (skillsToPreload.length > 0) {
  const allSkills = await getSkillToolCommands(getProjectRoot())
  for (const skillName of skillsToPreload) {
    // 三种解析策略：
    // 1. Exact match (hasCommand checks name, userFacingName, aliases)
    // 2. Fully-qualified with agent's plugin prefix (e.g., "my-skill" → "plugin:my-skill")
    // 3. Suffix match on ":skillName" for plugin-namespaced skills
  }
  // Load all skill contents concurrently and add to initial messages
  const loaded = await Promise.all(validSkills.map(async ({…}) => ({
    …, content: await skill.getPromptForCommand('', toolUseContext),
  })))
}

is_async: (run_in_background === true || selectedAgent.background === true) && !isBackgroundTasksDisabled

## Writing the prompt

When spawning a fresh agent (with a `subagent_type`), it starts with zero context.
Brief the agent like a smart colleague who just walked into the room — it hasn't seen
this conversation, doesn't know what you've tried, doesn't understand why this task matters.
- Explain what you're trying to accomplish and why.
- Describe what you've already learned or ruled out.
- Give enough context about the surrounding problem that the agent can make judgment calls
  rather than just following a narrow instruction.
- If you need a short response, say so ("report in under 200 words").
- Lookups: hand over the exact command. Investigations: hand over the question —
  prescribed steps become dead weight when the premise is wrong.

For fresh agents, terse command-style prompts produce shallow, generic work.

**Never delegate understanding.** Don't write "based on your findings, fix the bug" or
"based on the research, implement it." Those phrases push synthesis onto the agent instead
of doing it yourself. Write prompts that prove you understood: include file paths,
line numbers, what specifically to change.

## When to fork

Fork yourself (omit `subagent_type`) when the intermediate tool output isn't worth keeping
in your context. The criterion is qualitative — "will I need this output again" — not task size.
- **Research**: fork open-ended questions. If research can be broken into independent
  questions, launch parallel forks in one message. A fork beats a fresh subagent for this —
  it inherits context and shares your cache.
- **Implementation**: prefer to fork implementation work that requires more than a couple
  of edits. Do research before jumping to implementation.

Forks are cheap because they share your prompt cache. Don't set `model` on a fork — a
different model can't reuse the parent's cache. Pass a short `name` (one or two words,
lowercase) so the user can see the fork in the teams panel and steer it mid-run.

**Don't peek.** The tool result includes an `output_file` path — do not Read or tail it
unless the user explicitly asks for a progress check. You get a completion notification;
trust it. Reading the transcript mid-flight pulls the fork's tool noise into your context,
which defeats the point of forking.

**Don't race.** After launching, you know nothing about what the fork found. Never fabricate
or predict fork results in any format — not as prose, summary, or structured output. The
notification arrives as a user-role message in a later turn; it is never something you write
yourself. If the user asks a follow-up before the notification lands, tell them the fork is
still running — give status, not a guess.

**Writing a fork prompt.** Since the fork inherits your context, the prompt is a *directive* —
what to do, not what the situation is. Be specific about scope: what's in, what's out, what
another agent is handling. Don't re-explain background.

user: "so is the gate wired up or not"
<commentary>
User asks mid-wait. The audit fork was launched to answer exactly this, and it hasn't
returned. The coordinator does not have this answer. Give status, not a fabricated result.
</commentary>
assistant: Still waiting on the audit — that's one of the things it's checking. Should land shortly.

cd claude-code-deep-dive/extracted-source

# 1. 输入 schema 与那个 "external" === 'ant' 铁证
sed -n '82,140p' src/tools/AgentTool/AgentTool.tsx
grep -n '"external" === ' src/tools/AgentTool/AgentTool.tsx

# 2. 五道前置校验与四条分流
sed -n '250,470p' src/tools/AgentTool/AgentTool.tsx

# 3. fork 的全部实现（210 行，值得整读）
cat src/tools/AgentTool/forkSubagent.ts

# 4. runAgent 的十七步
grep -n '  // ' src/tools/AgentTool/runAgent.ts | head -60

# 5. 两处上下文瘦身与它们的省量数据
grep -n -B4 -A4 'Gtok/week' src/tools/AgentTool/runAgent.ts

# 6. agent 专属 MCP 的两种生命周期
sed -n '95,212p' src/tools/AgentTool/runAgent.ts

# 7. 委派协议的两段核心提示词
sed -n '80,155p' src/tools/AgentTool/prompt.ts

# 子 agent 的 sidechain transcript
ls ~/.claude/projects/*/*/ 2>/dev/null | head

# 看当前可用的 agent 列表（也能看到 system-reminder 里的 agent_listing_delta）
/agents