@pencil-agent/nano-pencil 2.0.0 → 2.0.1

package/docs/cc-agent-design.md

@@ -0,0 +1,1297 @@
+# Claude Code 主子 Agent 架构拆解
+
+> 源码版本：@anthropic-ai/claude-code@2.1.92
+> 目标：让一个模型可以在 nanoPencil 中一比一复刻 CC 的 Agent（子代理）系统
+
+---
+
+## 一、一句话概括
+
+CC 的 Agent 工具是一个**进程内子代理生成器**：父 agent 通过 `Agent` tool call 创建一个全新的 `AgentSession`（独立 LLM 循环），子 agent 拥有独立的系统提示、工具集和消息历史，完成后将最后一条 assistant 消息作为结果返回给父 agent。
+
+**不是**子进程、不是 HTTP 调用、不是 IPC——是同一个进程内的异步函数调用，共享同一套 runtime 基础设施。
+
+---
+
+## 二、核心概念映射
+
+| CC 概念 | nanoPencil 对应 | 说明 |
+|---------|----------------|------|
+| `Agent` tool | `SubAgentSpec` + `SubAgentRuntime` | CC 是 LLM 可调用的 tool；nanoPencil 是内部 API |
+| `Task` (alias) | 无 | CC 中 Agent 的别名 |
+| `subagent_type` | `runRole` / agent definition | 决定工具集和系统提示 |
+| `run_in_background` | `run_in_background` | 异步执行，输出写文件 |
+| `isolation: "worktree"` | `WorktreeManager` | git worktree 隔离 |
+| `agentNameRegistry` | `activeAgents` Map | 按名称寻址子 agent |
+| Handoff classifier | 无 | CC 独有的安全审查 |
+
+---
+
+## 三、Agent 工具的 JSON Schema
+
+### 3.1 Input Schema（LLM 看到的）
+
+```typescript
+// CC 源码中的定义（cli.js 第 3947 行附近）
+const AgentInputSchema = 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()
+    .describe("Set to true to run this agent in the background. You will be notified when it completes."),
+
+  name: z.string().optional()
+    .describe("Name for the spawned agent. Makes it addressable via SendMessage({to: name}) while running."),
+
+  team_name: z.string().optional()
+    .describe("Team name for spawning. Uses current team context if omitted."),
+
+  mode: z.enum(["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"]).optional()
+    .describe('Permission mode for spawned teammate (e.g., "plan" to require plan approval).'),
+
+  isolation: z.enum(["worktree"]).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. Overrides the working directory for all filesystem and shell operations within this agent. Mutually exclusive with isolation: "worktree".'),
+});
+```
+
+**注意**：
+- `cwd` 在最终发送给 LLM 的 schema 中被 omit 掉了（`nzY().omit({cwd:!0})`），但内部处理时仍然接受。
+- `run_in_background` 在 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 环境变量启用时也会被 omit（`xs1` 函数：`DS6||hx()?q.omit({run_in_background:!0}):q`）。
+
+### 3.2 Output Schema
+
+```typescript
+// 同步完成时
+type AgentOutputCompleted = {
+  agentId: string;
+  agentType?: string;
+  content: { type: "text"; text: string }[];
+  totalToolUseCount: number;
+  totalDurationMs: number;
+  totalTokens: number;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens: number | null;
+    cache_read_input_tokens: number | null;
+    server_tool_use: {
+      web_search_requests: number;
+      web_fetch_requests: number;
+    } | null;
+    service_tier: ("standard" | "priority" | "batch") | null;
+    cache_creation: {
+      ephemeral_1h_input_tokens: number;
+      ephemeral_5m_input_tokens: number;
+    } | null;
+  };
+  status: "completed";
+  prompt: string;  // 原始 prompt 文本
+};
+
+// 异步启动时
+type AgentOutputAsync = {
+  status: "async_launched";
+  agentId: string;          // 异步 agent 的 ID
+  description: string;      // 任务描述
+  prompt: string;           // 原始 prompt
+  outputFile: string;       // 输出文件路径，可用于检查进度
+  canReadOutputFile?: boolean; // 父 agent 是否有 Read/Bash 工具
+};
+
+type AgentOutput = AgentOutputCompleted | AgentOutputAsync;
+```
+
+---
+
+## 四、AgentDefinition 完整接口
+
+从源码中提取的 `AgentDefinition` 所有字段：
+
+```typescript
+interface AgentDefinition {
+  // === 必填 ===
+  agentType: string;                    // 唯一标识，如 "general-purpose"
+  description: string;                  // 一行描述
+  whenToUse: string | (() => string);   // ⚠️ 可以是函数！Explore 就是函数引用
+  getSystemPrompt: (ctx: { toolUseContext: any }) => string;
+
+  // === 工具控制（二选一） ===
+  tools?: string[];                     // 白名单，["*"] = 全部
+  disallowedTools?: string[];           // 黑名单
+
+  // === 模型 ===
+  model?: string;                       // "sonnet" | "opus" | "haiku" | "inherit"
+  effort?: "low" | "medium" | "high" | number;  // 推理努力程度
+
+  // === 权限 ===
+  permissionMode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";
+
+  // === 隔离 ===
+  isolation?: "worktree";               // worktree 隔离模式
+
+  // === 后台 ===
+  background?: boolean;                 // ⚠️ agent 定义级的后台标志，不同于 run_in_background 参数
+
+  // === Fork 行为 ===
+  forksParentContext?: boolean | "turn"; // ⚠️ 文档未提及！控制 fork 时继承哪些父消息
+                                          // true = 继承全部父消息
+                                          // "turn" = 只继承当前 turn 的消息
+                                          // undefined = 不继承
+
+  // === MCP ===
+  requiredMcpServers?: string[];        // ⚠️ 文档未提及！需要的 MCP 服务器
+  mcpServers?: string[];                // 关联的 MCP 服务器
+
+  // === 其他 ===
+  source: "built-in" | "plugin" | "flagSettings" | "userSettings" | "projectSettings";
+  baseDir: string;                      // 基础目录
+  color?: string;                       // ⚠️ 文档未提及！UI 颜色标识
+  maxTurns?: number;                    // 最大轮次
+  skills?: string[];                    // 关联的 skills
+  initialPrompt?: string;               // 初始提示
+  memory?: "user" | "project" | "local"; // 记忆范围
+  omitClaudeMd?: boolean;               // 是否跳过 CLAUDE.md
+  appendSystemPrompt?: boolean;         // 是否追加系统提示
+  hooks?: any;                          // 钩子配置
+  filename?: string;                    // 文件名（自定义 agent）
+}
+```
+
+---
+
+## 五、内置 Agent 类型定义
+
+### 5.1 general-purpose
+
+```typescript
+{
+  agentType: "general-purpose",
+  whenToUse: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.",
+  tools: ["*"],           // 所有工具
+  source: "built-in",
+  baseDir: "built-in",
+  getSystemPrompt: hr_,   // 继承主 agent 的系统提示
+}
+```
+
+**关键**：`tools: ["*"]` 表示通配符——继承父 agent 的全部工具集。
+
+### 5.2 Explore
+
+```typescript
+{
+  agentType: "Explore",
+  whenToUse: Lr_,   // ⚠️ 是函数引用，不是字符串字面量！运行时动态生成
+  disallowedTools: ["Agent", "ExitPlanMode", "Edit", "Write", "NotebookEdit"],
+  source: "built-in",
+  baseDir: "built-in",
+  model: "haiku",         // 强制使用 haiku 模型
+  omitClaudeMd: true,     // 不加载 CLAUDE.md
+  getSystemPrompt: () => Er_(),  // 专用系统提示
+}
+```
+
+**关键**：
+- `disallowedTools` 而非 `tools`——用黑名单而非白名单
+- 禁止 `Agent`（不能递归 spawn）
+- 禁止 `Edit`/`Write`/`NotebookEdit`（只读）
+- 强制 `haiku` 模型（快速、便宜）
+
+### 5.3 Plan
+
+```typescript
+{
+  agentType: "Plan",
+  whenToUse: "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.",
+  disallowedTools: ["Agent", "ExitPlanMode", "Edit", "Write", "NotebookEdit"],
+  source: "built-in",
+  baseDir: "built-in",
+  model: "inherit",       // ⚠️ 继承父 agent 的模型，不强制指定
+  omitClaudeMd: true,     // ⚠️ 不加载 CLAUDE.md
+  getSystemPrompt: () => Rr_(),  // 专用系统提示
+}
+```
+
+### 5.4 statusline-setup
+
+```typescript
+{
+  agentType: "statusline-setup",
+  whenToUse: "Use this agent to configure the user's Claude Code status line setting.",
+  tools: ["Read", "Edit"],  // ⚠️ 只有读和编辑，没有 Bash/Write
+  source: "built-in",
+  baseDir: "built-in",
+  model: "sonnet",           // ⚠️ 指定 sonnet 模型
+  color: "orange",           // ⚠️ UI 颜色标识
+  getSystemPrompt: () => `You are a status line setup agent for Claude Code...`,
+}
+```
+
+### 5.5 claude-code-guide
+
+```typescript
+{
+  agentType: "claude-code-guide",
+  whenToUse: `Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. IMPORTANT: Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can continue via SendMessage.`,
+  tools: bj() ? [e7, pq, Bj, Kh] : [Z_, H9, pq, Bj, Kh],  // ⚠️ 条件工具集，取决于某个运行时标志
+  source: "built-in",
+  baseDir: "built-in",
+  model: "haiku",            // ⚠️ 使用 haiku 模型
+  permissionMode: "dontAsk", // ⚠️ 不询问权限
+  getSystemPrompt: ({ toolUseContext }) => /* 专用系统提示 */,
+}
+```
+
+---
+
+## 六、Agent Spawn 完整流程
+
+### 6.1 同步执行路径
+
+```
+[1] LLM 输出 tool_use: Agent({ prompt, subagent_type, description, ... })
+    ↓
+[2] Agent tool handler 被调用
+    async call({prompt, subagent_type, description, model, run_in_background, name, team_name, mode, isolation, cwd}, ...)
+    ↓
+[3] 参数预处理
+    - model: 如果 Ay6() 为 true（某些限制模式），忽略 model 参数
+    - team_name: 检查是否在 team context 中
+    ↓
+[4] Team 路径判断
+    if (team_name && name) → 走 team teammate spawn 路径（KZK 函数）
+    ↓
+[5] Agent 类型解析
+    if (subagent_type 未指定) {
+      if (在 fork worker 中) → 抛错 "Fork is not available inside a forked worker"
+      agentDef = PS6（默认 fork agent 定义）
+      isFork = true
+    } else {
+      从 agentDefinitions.activeAgents 中查找匹配的 agentType
+      if (找不到) → 抛错 "Agent type 'X' not found"
+      if (被 permission rule 拒绝) → 抛错 "Agent type 'X' has been denied"
+      agentDef = 找到的定义
+      isFork = false
+    }
+    ↓
+[6] MCP 服务器检查
+    if (agentDef.requiredMcpServers 有值) {
+      等待最多 30 秒让 pending MCP 连接完成
+      检查所需 MCP 服务器是否可用
+      if (不可用) → 抛错
+    }
+    ↓
+[7] 模型选择
+    resolvedModel = JE6(agentDef.model, mainLoopModel, userOverride, permissionMode)
+    // 优先级：agent 定义的 model > 用户指定的 model > 主循环的 model
+    ↓
+[8] 系统提示构建
+    if (isFork) {
+      // Fork 模式：继承父 agent 的系统提示
+      systemPrompt = parentSession.renderedSystemPrompt
+      // ⚠️ 如果 renderedSystemPrompt 不存在，走 Lx() 构建
+      messages = buildForkMessages(prompt, queryMetadata)
+    } else {
+      // 普通模式：使用 agent 定义的系统提示
+      // ⚠️ 注意：Z18() 会把 worktree path 和 cwd 作为 Notes 注入系统提示
+      systemPrompt = Z18([additionalWorkingDirs], model, additionalWorkingDirs)
+      // Z18 开头是 "Notes:" 然后列出所有工作目录
+      if (agentDef.memory) { /* 加载记忆 */ }
+      messages = [userMessage(prompt)]
+    }
+    ↓
+[9] 权限模式确定
+    permissionContext = { ...parentPermissionContext, mode: agentDef.permissionMode ?? "acceptEdits" }
+    ↓
+[10] 工具集确定
+     if (isFork) {
+       availableTools = parentTools  // 完全继承
+       useExactTools = true           // ⚠️ 精确使用父工具，不重新过滤
+     } else {
+       availableTools = td(permissionContext, mcpTools)  // 根据权限过滤
+     }
+    ↓
+[11] Worktree 创建（如果 isolation === "worktree"）
+     worktreeResult = await Xq8(`agent-${agentId.slice(0,8)}`)
+     // 详见第七节
+    ↓
+[12] 异步判断
+     // ⚠️ 三个独立的异步触发源：
+     // 1. run_in_background 参数（用户显式指定）
+     // 2. agentDef.background（agent 定义中的标志）
+     // 3. 自动后台化（运行时超时）
+     //
+     // ⚠️ 限制：In-process teammate 不能用 run_in_background=true 或 background=true
+     if (TD() && teamContext && agentDef.background === true) {
+       throw Error("In-process teammates cannot spawn background agents.")
+     }
+     //
+     isAsync = (run_in_background === true || agentDef.background === true)
+     autoBackgroundMs = czY()  // 默认 120000ms = 2 分钟（如果启用）
+     //
+     // ⚠️ DS6 = CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 环境变量
+     // 如果 DS6 为 true，所有异步能力被禁用
+    ↓
+[13] 同步执行
+     创建 AgentSession（详见第八节）
+     迭代 LLM 流：
+       while (true) {
+         result = await stream.next()
+         if (result.done) break
+         // 收集消息
+         messages.push(result.value)
+         // 检查是否应该转为后台
+         if (shouldBackground) {
+           // 转为异步路径
+           break
+         }
+       }
+    ↓
+[14] 结果提取
+     VS8(messages, agentId, metadata) → AgentOutputCompleted
+     - 从最后一条 assistant 消息提取文本
+     - 计算 totalTokens, totalToolUseCount, totalDurationMs
+     - 提取 usage 统计
+     - ⚠️ maxResultSizeChars = 100,000（1e5）字符，超出会被截断
+    ↓
+[15] 安全审查（auto mode 下）
+     // ⚠️ 同步路径直接调用 ES8
+     // ⚠️ 异步路径：ES8 在父 agent 读取 outputFile 时触发（延迟审查）
+     ES8({ agentMessages, tools, toolPermissionContext, abortSignal, subagentType })
+     - 调用 handoff classifier（TS8 函数）检查子 agent 输出
+     - classifier 使用一个小模型审查子 agent 的操作
+     - 如果 flagged → 返回 SECURITY WARNING 前缀
+     - ⚠️ 如果 classifier 不可用（unavailable），返回警告但不阻断
+    ↓
+[16] Worktree 清理
+     if (worktree 存在) {
+       if (无变更 && 无新提交) → git worktree remove
+       else → 保留（可手动检查）
+     }
+    ↓
+[17] 返回 AgentOutputCompleted 给 LLM
+```
+
+### 6.2 异步执行路径
+
+```
+[1-11] 同上
+    ↓
+[12] isAsync = true
+    ↓
+[13] 创建后台任务
+     taskId = dg8({ agentId, description, prompt, selectedAgent, setAppState, toolUseId })
+     // 在 AppState 中注册任务
+     ↓
+     if (name 参数存在) {
+       agentNameRegistry.set(name, agentId)  // 注册名称映射
+     }
+    ↓
+[14] 启动异步执行
+     OU(sessionMetadata, () =>
+       q6(() => LS8({
+         taskId, abortController, makeStream, metadata, description,
+         toolUseContext, rootSetAppState, agentIdForCleanup,
+         enableSummarization, getWorktreeResult
+       }))
+     )
+     // LS8 = 异步 agent runner（详见第八节 8.2）
+    ↓
+[15] 检查父 agent 是否有 Read/Bash 工具
+     canReadOutputFile = tools.some(t => isReadTool(t) || isBashTool(t))
+    ↓
+[16] 立即返回 AgentOutputAsync
+     {
+       status: "async_launched",
+       agentId,
+       description,
+       prompt,
+       outputFile: lY(agentId),  // <project>/.claude/tasks/<agentId>.output
+       canReadOutputFile
+     }
+```
+
+---
+
+## 七、Worktree 隔离机制
+
+### 7.1 创建（Xq8 函数）
+
+```typescript
+async function Xq8(agentId: string, options?: WorktreeOptions) {
+  // 1. 注册 worktree 元数据
+  zS6(agentId);
+
+  // 2. 检查是否有 hook-based worktree
+  if (hM6()) {
+    const hookResult = await P58(agentId);
+    // hook 可以自定义 worktree 创建逻辑
+    return { worktreePath: hookResult.worktreePath, hookBased: true };
+  }
+
+  // 3. 获取 worktree 配置
+  const config = getWorktreeConfig();
+  // symlinkDirectories: 需要 symlink 的目录（如 node_modules）
+  // sparsePaths: git sparse-checkout 路径
+
+  // 4. 创建 git worktree
+  const worktreePath = path.join(getTempDir(), `agent-${agentId}`);
+  const branchName = `agent-${agentId}`;
+
+  await exec(`git worktree add --detach ${worktreePath}`);
+
+  // 5. 处理 sparse checkout（如果配置了）
+  if (config.sparsePaths?.length) {
+    await exec(`git sparse-checkout set --cone ${config.sparsePaths.join(' ')}`, { cwd: worktreePath });
+  }
+
+  // 6. 创建 symlink（如果配置了）
+  if (config.symlinkDirectories?.length) {
+    for (const dir of config.symlinkDirectories) {
+      const src = path.join(projectRoot, dir);
+      const dst = path.join(worktreePath, dir);
+      if (fs.existsSync(src) && !fs.existsSync(dst)) {
+        await fs.symlink(src, dst);
+      }
+    }
+  }
+
+  // 7. 记录 head commit（用于后续变更检测）
+  const headCommit = await exec('git rev-parse HEAD', { cwd: worktreePath });
+
+  return {
+    worktreePath,
+    worktreeBranch: branchName,
+    headCommit: headCommit.stdout.trim(),
+    gitRoot: projectRoot,
+  };
+}
+```
+
+### 7.2 变更检测（E77 函数）
+
+```typescript
+async function E77(worktreePath: string, baselineCommit: string): Promise<boolean> {
+  const { dirty, commitsAhead } = await il8(worktreePath, baselineCommit);
+  // il8 内部：
+  //   dirty = git status --porcelain 输出非空
+  //   commitsAhead = git rev-list ${baselineCommit}..HEAD --count
+  return dirty || commitsAhead > 0;
+}
+```
+
+### 7.3 清理（jJ6 函数）
+
+```typescript
+async function jJ6(worktreePath: string, branchName: string, gitRoot: string, hookBased?: boolean) {
+  if (hookBased) {
+    // hook-based worktree 由 hook 负责清理
+    const cleanup = await dl8(worktreePath);
+    return;
+  }
+
+  // 1. 删除 worktree
+  await exec(`git worktree remove ${worktreePath} --force`, { cwd: gitRoot });
+
+  // 2. 删除分支（如果存在）
+  try {
+    await exec(`git branch -D ${branchName}`, { cwd: gitRoot });
+  } catch {
+    // 分支可能不存在，忽略
+  }
+}
+```
+
+### 7.4 生命周期决策
+
+```
+Agent 执行完成
+    ↓
+worktree 存在？
+    ├─ NO → 无操作
+    └─ YES → E77(worktreePath, headCommit)
+        ├─ 无变更 → jJ6() 清理 worktree
+        └─ 有变更 → 保留 worktree，返回 worktreePath 给父 agent
+            // 父 agent 可以检查变更，手动决定是否应用
+```
+
+---
+
+## 八、AgentSession 创建与执行
+
+### 8.1 同步执行（call 函数内部）
+
+```typescript
+// CC 源码中的同步执行路径（简化）
+const agentId = generateUUID();
+
+const sessionConfig = {
+  agentDefinition: agentDef,
+  promptMessages: messages,           // 用户消息
+  toolUseContext: parentContext,       // 继承父 agent 的 context
+  canUseTool: permissionChecker,      // 权限检查函数
+  isAsync: false,
+  querySource: `agent:${agentDef.agentType}`,
+  model: resolvedModel,
+  // ⚠️ override 逻辑比文档描述的更复杂：
+  override: isFork
+    ? { systemPrompt: parentSystemPrompt }      // Fork: 继承父系统提示
+    : agentSystemPrompt && !worktree && !cwd
+      ? { systemPrompt: I5(agentSystemPrompt) } // 普通（无 worktree/cwd）: 格式化 agent 系统提示
+      : undefined,                               // 有 worktree/cwd: 不 override，让 Z18 处理
+  availableTools: isFork ? parentTools : filteredTools,
+  // ⚠️ forkContextMessages 取决于 agentDef.forksParentContext：
+  forkContextMessages: isFork
+    ? agentDef.forksParentContext === "turn"
+      ? parentMessages.slice(turnStartIndex)  // "turn": 只继承当前 turn
+      : agentDef.forksParentContext === true
+        ? parentMessages                       // true: 继承全部
+        : undefined                            // undefined: 不继承
+    : undefined,
+  worktreePath: worktree?.worktreePath,
+  description: description,
+};
+
+// 创建 LLM 流
+const stream = Yx(sessionConfig);
+
+// 迭代执行
+const messages = [];
+let totalTokens = 0;
+let totalToolUseCount = 0;
+
+for await (const event of stream) {
+  messages.push(event);
+
+  // 更新进度 UI
+  if (elapsed > 2000 && !showedSpinner) {
+    setToolJSX(<AgentProgressUI />);
+    showedSpinner = true;
+  }
+
+  // 检查是否应该转为后台
+  if (shouldBackground && taskId) {
+    // 转为异步路径
+    break;
+  }
+}
+
+// 提取结果
+const result = VS8(messages, agentId, {
+  prompt, resolvedAgentModel, isBuiltInAgent, startTime, agentType, isAsync: false
+});
+```
+
+### 8.2 异步执行（LS8 函数）
+
+```typescript
+async function LS8({
+  taskId, abortController, makeStream, metadata, description,
+  toolUseContext, rootSetAppState, agentIdForCleanup,
+  enableSummarization, getWorktreeResult
+}) {
+  const messages = [];
+
+  try {
+    // 1. 创建 token 计数器
+    const tokenCounter = c26();
+    const toolCounter = l26(toolUseContext.options.tools);
+
+    // 2. 如果需要摘要，注册停止回调
+    let stopFn;
+    if (enableSummarization) {
+      const { stop } = qe6(taskId, agentId, tokenCounter, rootSetAppState);
+      stopFn = stop;
+    }
+
+    // 3. 创建流并迭代
+    const stream = makeStream(/* cacheSafeParams */);
+
+    for await (const event of stream) {
+      // 检查 abort
+      if (abortController.signal.aborted) break;
+
+      messages.push(event);
+      // 更新 token 和 tool 计数
+      KK6(tokenCounter, event, toolCounter, toolUseContext.options.tools);
+
+      // 更新任务状态
+      _e6(taskId, Pa(tokenCounter), rootSetAppState);
+
+      // 记录工具使用
+      const toolUse = NS8(event);
+      if (toolUse) {
+        yS8(tokenCounter, taskId, toolUseId, description, metadata, toolUse);
+      }
+    }
+
+    // 4. 提取结果
+    const result = VS8(messages, taskId, metadata);
+
+    // 5. 更新任务状态为完成
+    hS8(result, rootSetAppState);
+
+    // 6. 清理 worktree
+    const worktreeResult = await getWorktreeResult();
+
+    // 7. 清理 agent 注册
+    v18(agentId, { agentType: metadata.agentType, description })
+      .catch(err => log(`Failed to clear worktree metadata: ${err}`));
+
+    return result;
+
+  } catch (error) {
+    // 错误处理
+    throw error;
+  } finally {
+    // 清理
+    if (agentIdForCleanup) {
+      // 从 activeAgents 中移除
+    }
+  }
+}
+```
+
+---
+
+## 九、工具过滤机制
+
+### 9.1 过滤逻辑
+
+```typescript
+// 工具过滤的核心函数
+function filterToolsForAgent(agentDef, parentTools, permissionContext, mcpTools) {
+  // 1. 获取基础工具集
+  let tools = td(permissionContext, mcpTools);
+  // td = 根据权限模式过滤工具
+
+  // 2. 应用 agent 定义的工具限制
+  if (agentDef.tools) {
+    // 白名单模式：只保留指定的工具
+    if (agentDef.tools.includes("*")) {
+      // 通配符：保留所有工具
+    } else {
+      tools = tools.filter(t => agentDef.tools.includes(t.name));
+    }
+  }
+
+  if (agentDef.disallowedTools) {
+    // 黑名单模式：移除指定的工具
+    tools = tools.filter(t => !agentDef.disallowedTools.includes(t.name));
+  }
+
+  return tools;
+}
+```
+
+### 9.2 各类型的工具集
+
+| Agent 类型 | 工具策略 | 具体工具 | 模型 | 其他 |
+|-----------|---------|---------|------|------|
+| general-purpose | `tools: ["*"]` | 继承父 agent 全部工具 | 继承 | - |
+| Explore | `disallowedTools` | 全部 - Agent - ExitPlanMode - Edit - Write - NotebookEdit | haiku | omitClaudeMd |
+| Plan | `disallowedTools` | 同 Explore | inherit | omitClaudeMd |
+| statusline-setup | `tools` 白名单 | Read, Edit | sonnet | color: orange |
+| claude-code-guide | `tools` 条件 | 取决于 bj() 标志 | haiku | permissionMode: dontAsk |
+
+### 9.3 权限模式对工具的影响
+
+```typescript
+function td(permissionContext, mcpTools) {
+  // permissionContext.mode 可能的值：
+  // - "acceptEdits": 默认模式，编辑需要确认
+  // - "auto": 自动模式，大部分操作自动批准
+  // - "bypassPermissions": 跳过所有权限检查
+  // - "plan": 只读 + plan 模式
+  // - "dontAsk": 不询问，直接拒绝未授权操作
+
+  let tools = [...builtinTools];
+
+  // 根据模式过滤
+  if (permissionContext.mode === "plan") {
+    tools = tools.filter(t => isReadOnly(t));
+  }
+
+  // 添加 MCP 工具
+  tools.push(...mcpTools);
+
+  return tools;
+}
+```
+
+---
+
+## 十、系统提示构建
+
+### 10.1 普通子 Agent
+
+```typescript
+// 子 agent 的系统提示构建
+function buildSubAgentSystemPrompt(agentDef, toolUseContext) {
+  // 1. 获取 agent 定义的系统提示
+  const agentPrompt = agentDef.getSystemPrompt({ toolUseContext });
+
+  // 2. 如果 agent 有 memory 配置，加载记忆
+  if (agentDef.memory) {
+    const memory = loadMemory(agentDef.memory);
+    agentPrompt += `\n${memory}`;
+  }
+
+  // 3. 格式化
+  return I5(agentPrompt);
+  // I5 = 将系统提示格式化为 Anthropic API 消息格式
+}
+```
+
+### 10.2 Fork 模式
+
+```typescript
+// Fork 模式：继承父 agent 的系统提示
+function buildForkSystemPrompt(parentSession) {
+  // 直接使用父 agent 的 renderedSystemPrompt
+  return parentSession.renderedSystemPrompt;
+}
+```
+
+### 10.3 系统提示的差异
+
+| 场景 | 系统提示来源 | CLAUDE.md | 记忆 | 工作目录注入 |
+|------|------------|-----------|------|------------|
+| 普通子 agent（无 worktree/cwd） | agentDef.getSystemPrompt() → I5() 格式化 | 取决于 agent 定义 | 取决于 memory 配置 | 无 |
+| 普通子 agent（有 worktree/cwd） | Z18() 构建（含 "Notes:" + 工作目录列表） | 取决于 agent 定义 | 取决于 memory 配置 | ✅ 自动注入 |
+| Fork 模式 | 父 agent 的 renderedSystemPrompt | 继承父 agent | 继承父 agent | 无 |
+| Explore agent | Er_() 专用系统提示 | omitClaudeMd: true | 无 | 无 |
+
+---
+
+## 十一、消息传递协议
+
+### 11.1 父 → 子
+
+```typescript
+// 消息构建
+const messages = [];
+
+if (isFork) {
+  // Fork 模式：包含父 agent 的上下文消息
+  messages.push(...buildForkContextMessages(parentMessages, prompt, queryMetadata));
+  // buildForkContextMessages 会：
+  //   1. 取父 agent 的消息历史
+  //   2. 添加用户的新 prompt
+  //   3. 添加 query metadata（requestId 等）
+} else {
+  // 普通模式：只有用户消息
+  messages.push({ type: "user", content: [{ type: "text", text: prompt }] });
+}
+```
+
+### 11.2 子 → 父（同步）
+
+```typescript
+// 结果提取（VS8 函数）
+function VS8(messages, agentId, metadata) {
+  // 1. 获取最后一条 assistant 消息
+  const lastAssistant = findLastAssistantMessage(messages);
+  if (!lastAssistant) throw new Error("No assistant messages found");
+
+  // 2. 提取文本内容
+  let textContent = lastAssistant.message.content.filter(c => c.type === "text");
+
+  // 3. 如果最后一条没有文本，向前搜索
+  if (textContent.length === 0) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.type !== "assistant") continue;
+      const texts = msg.message.content.filter(c => c.type === "text");
+      if (texts.length > 0) {
+        textContent = texts;
+        break;
+      }
+    }
+  }
+
+  // 4. 统计
+  const totalTokens = $W(messages)?.usage?.total_tokens ?? 0;
+  const totalToolUseCount = wZz(messages);
+
+  // 5. 构建结果
+  return {
+    agentId,
+    agentType: metadata.agentType,
+    content: textContent,
+    totalDurationMs: Date.now() - metadata.startTime,
+    totalTokens,
+    totalToolUseCount,
+    usage: $W(messages)?.message?.usage,
+    status: "completed",
+    prompt: metadata.prompt,
+  };
+}
+```
+
+### 11.3 子 → 父（异步）
+
+异步 agent 的结果通过**文件系统**传递：
+
+```typescript
+// 输出文件路径
+function lY(agentId) {
+  return path.join(qR6(), `${agentId}.output`);
+  // qR6() = <project>/.claude/tasks/
+}
+
+// 输出文件内容 = 最后一条 assistant 消息的文本
+```
+
+父 agent 可以通过 Read 工具读取 `outputFile` 来检查子 agent 的进度。
+
+---
+
+## 十二、安全机制
+
+### 12.1 Handoff Classifier（auto mode）
+
+```typescript
+async function ES8({
+  agentMessages, tools, toolPermissionContext, abortSignal, subagentType, totalToolUseCount
+}) {
+  // 只在 auto mode 下运行
+  if (toolPermissionContext.mode !== "auto") return null;
+
+  // 构建审查 prompt
+  const reviewPrompt = {
+    role: "user",
+    content: [{
+      type: "text",
+      text: "Sub-agent has finished and is handing back control to the main agent. Review the sub-agent's work based on the block rules and let the main agent know if any file is dangerous (the main agent will see the reason)."
+    }]
+  };
+
+  // 调用 classifier
+  const result = await TS8(
+    [...agentMessages, reviewPrompt],
+    tools, toolPermissionContext, abortSignal
+  );
+
+  // 记录决策
+  d("tengu_auto_mode_decision", {
+    decision: result.shouldBlock ? "blocked" : "allowed",
+    toolName: "Agent",
+    subagentType,
+    toolUseCount: totalToolUseCount,
+    isHandoff: true,
+  });
+
+  if (result.shouldBlock) {
+    if (result.unavailable) {
+      return "Note: The safety classifier was unavailable when reviewing this sub-agent's work. Please carefully verify the sub-agent's actions and output before acting on them.";
+    }
+    return `SECURITY WARNING: Sub-agent performed actions that may violate security policy. Reason: ${result.reason}. Review the sub-agent's actions carefully before acting on its output.`;
+  }
+
+  return null;  // 安全，无警告
+}
+```
+
+### 12.2 权限继承
+
+```typescript
+// 子 agent 的权限模式
+const childPermissionContext = {
+  ...parentPermissionContext,
+  mode: agentDef.permissionMode ?? "acceptEdits",
+  // agent 定义可以覆盖权限模式
+  // 但不能比父 agent 更宽松
+};
+```
+
+### 12.3 递归限制
+
+```typescript
+// 在 Fork worker 中不能再次 fork
+if (querySource === `agent:builtin:${forkAgentType}` || isForkWorker(messages)) {
+  throw new Error("Fork is not available inside a forked worker. Complete your task directly using your tools.");
+}
+
+// Team 中 teammate 不能 spawn teammate
+if (isTeamContext && name) {
+  throw new Error("Teammates cannot spawn other teammates — the team roster is flat.");
+}
+
+// In-process teammate 不能 spawn background agent
+if (isInProcessTeam && run_in_background === true) {
+  throw new Error("In-process teammates cannot spawn background agents.");
+}
+```
+
+---
+
+## 十三、自动后台化机制
+
+### 13.1 触发条件
+
+```typescript
+function czY() {
+  // 如果启用了自动后台任务，返回阈值（2 分钟）
+  if (U6(process.env.CLAUDE_AUTO_BACKGROUND_TASKS) ||
+      S8("tengu_auto_background_agents", false)) {
+    return 120000;  // 2 分钟
+  }
+  return 0;  // 禁用
+}
+```
+
+### 13.2 转后台流程
+
+```
+同步执行中，elapsed > autoBackgroundMs
+    ↓
+检查条件：
+  - 子 agent 还在运行
+  - 父 agent 的 UI 可以设置 JSX
+    ↓
+创建后台任务对象
+  taskId = dg8({ agentId, description, prompt, ... })
+    ↓
+设置 agentNameRegistry（如果 name 存在）
+    ↓
+中断当前同步迭代
+  stream.return(undefined)
+    ↓
+启动异步继续
+  OU(metadata, () => LS8({ ... }))
+    ↓
+返回 AgentOutputAsync 给父 agent
+```
+
+---
+
+## 十四、Agent 注册表与命名
+
+### 14.1 agentNameRegistry
+
+```typescript
+// 在 AppState 中维护
+agentNameRegistry: Map<string, string>  // name → agentId
+
+// 注册
+if (name) {
+  setAppState(state => {
+    const registry = new Map(state.agentNameRegistry);
+    registry.set(name, agentId);
+    return { ...state, agentNameRegistry: registry };
+  });
+}
+
+// 查找（SendMessage 使用）
+function findAgentByName(name) {
+  return agentNameRegistry.get(name);
+}
+```
+
+### 14.2 Agent 定义缓存
+
+```typescript
+// agentDefinitions 在 AppState 中维护
+agentDefinitions: {
+  activeAgents: AgentDefinition[],   // 当前可用的 agent 列表
+  allAgents: AgentDefinition[],      // 所有 agent（包括不可用的）
+  failedFiles?: { path: string, error: string }[],
+}
+
+// 加载时机：
+// 1. 启动时
+// 2. 配置变更时
+// 3. 插件加载时
+
+// 来源：
+// 1. 内置 agent（fy8()）
+// 2. 插件定义的 agent（ao6()）
+// 3. 用户自定义 agent（.claude/agents/*.md）
+```
+
+---
+
+## 十五、自定义 Agent 定义格式
+
+### 15.1 Markdown 格式（.claude/agents/*.md）
+
+```markdown
+---
+name: my-agent
+description: "A specialized agent for X"
+tools: ["Read", "Glob", "Grep"]  # 可选，白名单
+disallowedTools: ["Write"]        # 可选，黑名单
+model: sonnet                     # 可选
+effort: high                      # 可选
+permissionMode: plan              # 可选
+maxTurns: 10                      # 可选
+background: false                 # 可选
+memory: project                   # 可选
+isolation: worktree               # 可选
+skills: ["skill-name"]            # 可选
+initialPrompt: "..."              # 可选
+appendSystemPrompt: true          # 可选
+mcpServers: ["server-name"]       # 可选
+---
+
+You are a specialized agent for X.
+
+Your responsibilities:
+1. ...
+2. ...
+```
+
+### 15.2 JSON 格式（插件定义）
+
+```json
+{
+  "agents": {
+    "my-agent": {
+      "description": "A specialized agent for X",
+      "tools": ["Read", "Glob", "Grep"],
+      "prompt": "You are a specialized agent for X...",
+      "model": "sonnet",
+      "permissionMode": "plan",
+      "maxTurns": 10,
+      "background": false,
+      "memory": "project",
+      "isolation": "worktree"
+    }
+  }
+}
+```
+
+---
+
+## 十六、Telemetry 事件
+
+```typescript
+// Agent 选择
+d("tengu_agent_tool_selected", {
+  agent_type: agentDef.agentType,
+  model: resolvedModel,
+  source: agentDef.source,       // "built-in" | "plugin" | "flagSettings"
+  color: agentDef.color,
+  is_built_in_agent: isBuiltIn(agentDef),
+  is_resume: false,
+  is_async: isAsync,
+  is_fork: isFork,
+});
+
+// Agent 完成
+d("tengu_agent_tool_completed", {
+  agent_type: metadata.agentType,
+  model: metadata.resolvedAgentModel,
+  prompt_char_count: metadata.prompt.length,
+  response_char_count: responseText.length,
+  assistant_message_count: messages.length,
+  total_tool_use_count: totalToolUseCount,
+  duration_ms: Date.now() - metadata.startTime,
+  total_tokens: totalTokens,
+  is_built_in_agent: metadata.isBuiltInAgent,
+  is_async: metadata.isAsync,
+});
+
+// Auto mode 决策
+d("tengu_auto_mode_decision", {
+  decision: "blocked" | "allowed",
+  toolName: "Agent",
+  subagentType,
+  toolUseCount,
+  isHandoff: true,
+});
+
+// Agent 记忆加载
+d("tengu_agent_memory_loaded", {
+  scope: agentDef.memory,
+  source: "subagent",
+});
+```
+
+---
+
+## 十七、完整状态机
+
+```
+                    ┌─────────────────────────────────────┐
+                    │         Agent Tool Called            │
+                    └──────────────┬──────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────────────┐
+                    │      Resolve Agent Definition        │
+                    │  (subagent_type → AgentDefinition)   │
+                    └──────────────┬──────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────────────┐
+                    │      Check Permissions & MCP         │
+                    └──────────────┬──────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────────────┐
+                    │      Build System Prompt             │
+                    │  (fork: inherit, normal: agentDef)   │
+                    └──────────────┬──────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────────────┐
+                    │      Create Worktree?                │
+                    │  (isolation === "worktree")          │
+                    └──────────────┬──────────────────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              │                    │                     │
+    ┌─────────▼─────────┐ ┌───────▼───────┐ ┌──────────▼──────────┐
+    │  Sync Execution   │ │  Background   │ │  Team Teammate      │
+    │  (default)        │ │  (async)      │ │  (team_name+name)   │
+    └─────────┬─────────┘ └───────┬───────┘ └──────────┬──────────┘
+              │                    │                     │
+    ┌─────────▼─────────┐ ┌───────▼───────┐ ┌──────────▼──────────┐
+    │  Create Session   │ │  Create Task  │ │  KZK()              │
+    │  Yx(config)       │ │  dg8()        │ │  Team Spawn         │
+    └─────────┬─────────┘ └───────┬───────┘ └─────────────────────┘
+              │                    │
+    ┌─────────▼─────────┐ ┌───────▼───────┐
+    │  Iterate Stream   │ │  LS8()        │
+    │  for await        │ │  Async Runner │
+    └─────────┬─────────┘ └───────┬───────┘
+              │                    │
+    ┌─────────▼─────────┐ ┌───────▼───────┐
+    │  Auto-background? │ │  Write Output │
+    │  elapsed > 2min   │ │  File         │
+    └─────────┬─────────┘ └───────┬───────┘
+              │                    │
+    ┌─────────▼─────────┐ ┌───────▼───────┐
+    │  VS8() Extract    │ │  Return       │
+    │  Result           │ │  async_launched│
+    └─────────┬─────────┘ └───────────────┘
+              │
+    ┌─────────▼─────────┐
+    │  Handoff Check    │
+    │  (auto mode)      │
+    └─────────┬─────────┘
+              │
+    ┌─────────▼─────────┐
+    │  Cleanup Worktree │
+    └─────────┬─────────┘
+              │
+    ┌─────────▼─────────┐
+    │  Return Completed │
+    └───────────────────┘
+```
+
+---
+
+## 十八、复刻清单
+
+### 18.1 数据结构
+
+- [ ] `AgentDefinition` 接口（详见第四节，25+ 字段）
+- [ ] `AgentInput` / `AgentOutput` 类型
+- [ ] `AgentSessionConfig` 接口
+- [ ] `agentNameRegistry` Map
+- [ ] `maxResultSizeChars` 常量（100,000）
+- [ ] `forksParentContext` 三态逻辑（true/"turn"/undefined）
+
+### 18.2 核心函数
+
+- [ ] `resolveAgentType(subagent_type)` → 查找 agent 定义
+- [ ] `filterToolsForAgent(agentDef, parentTools, permissionContext)` → 工具过滤
+- [ ] `Z18(additionalWorkingDirs, model)` → 系统提示构建（含工作目录 Notes）
+- [ ] `createWorktree(agentId)` → worktree 创建
+- [ ] `checkWorktreeDirty(worktreePath, baseline)` → 变更检测
+- [ ] `cleanupWorktree(worktreePath, branch, gitRoot)` → worktree 清理
+- [ ] `createAgentSession(config)` → 创建 LLM session
+- [ ] `extractAgentResult(messages, agentId, metadata)` → 结果提取
+- [ ] `checkHandoffSafety(messages, tools, permissionContext)` → 安全审查
+- [ ] `Lx()` → 主 session 系统提示构建（fork 模式回退）
+
+### 18.3 工具注册
+
+- [ ] Agent tool 的 JSON Schema 定义
+- [ ] Agent tool handler（call 函数）
+- [ ] 同步/异步执行路径
+- [ ] 自动后台化逻辑
+- [ ] `maxResultSizeChars: 1e5` 截断
+
+### 18.4 内置 Agent
+
+- [ ] general-purpose（tools: ["*"]，`whenToUse` 是字符串）
+- [ ] Explore（disallowedTools, model: haiku, omitClaudeMd，`whenToUse` 是函数引用）
+- [ ] Plan（disallowedTools）
+- [ ] statusline-setup
+- [ ] claude-code-guide
+
+### 18.5 安全
+
+- [ ] 递归限制（fork 中不能再 fork）
+- [ ] Team 限制（teammate 不能 spawn teammate）
+- [ ] In-process teammate 不能 spawn background agent
+- [ ] 权限继承（不能比父更宽松）
+- [ ] Handoff classifier（auto mode 安全审查）
+- [ ] Classifier 不可用时的降级处理
+
+### 18.6 持久化
+
+- [ ] 输出文件（`.claude/tasks/<agentId>.output`）
+- [ ] Agent 定义缓存（启动时/配置变更时/插件加载时）
+- [ ] agentNameRegistry 持久化
+- [ ] Worktree 元数据（head commit 用于变更检测）
+
+---
+
+## 十九、与 nanoPencil 现有实现的差异
+
+| 维度 | CC | nanoPencil |
+|------|-----|-----------|
+| **工具定义** | LLM 可调用的 tool | 内部 API（SubAgentSpec） |
+| **Agent 类型** | 5 个内置 + 自定义 | 2 种模式（research/implement）+ team modes |
+| **Worktree** | git worktree add --detach | 同 |
+| **异步执行** | 内置 run_in_background | 内置 |
+| **自动后台** | 2 分钟阈值 | 无 |
+| **安全审查** | Handoff classifier | 无 |
+| **Fork 模式** | 继承父 agent 系统提示和消息 | 无 |
+| **forksParentContext** | true/"turn"/undefined 三种模式 | 无 |
+| **命名注册** | agentNameRegistry | activeAgents Map |
+| **输出文件** | .claude/tasks/*.output | .nanopencil/subagent-runs/*.md |
+| **系统提示** | 按 agent type 构建 + Z18 注入工作目录 | 按 runRole 构建 |
+| **工具过滤** | tools/disallowedTools | createReadOnlyTools/createCodingTools |
+| **自定义 Agent** | .claude/agents/*.md | 无 |
+| **结果大小限制** | maxResultSizeChars = 100,000 | 无 |
+| **background 字段** | agent 定义级 + 参数级，两个独立控制 | 仅参数级 |
+
+---
+
+## 二十、关键源码位置
+
+| 组件 | CC 源码位置（cli.js 行号/函数名） |
+|------|-------------------------------|
+| 工具名常量 | `H4="Agent"`, `eI="Task"` |
+| Input Schema | `lzY`, `nzY`, `xs1`（第 3947 行附近） |
+| Output Schema | `izY` |
+| Agent handler | `ng8.call()`（第 3947 行附近） |
+| 内置 agent 定义 | `fy8()` |
+| Agent 类型过滤 | `Mq8()` |
+| 工具过滤 | `td()` |
+| Worktree 创建 | `Xq8()` |
+| 变更检测 | `E77()` → `il8()` |
+| Worktree 清理 | `jJ6()` |
+| 系统提示构建 | `Z18()`, `Lx()` |
+| 结果提取 | `VS8()` |
+| 异步 runner | `LS8()` |
+| 后台任务创建 | `dg8()` |
+| 输出文件路径 | `lY()` → `qR6()` |
+| 自动后台阈值 | `czY()` |
+| Handoff 审查 | `ES8()` |
+| Agent 定义解析 | `mM4()`（markdown）, `uM4()`（JSON） |
+| Agent 注册表 | `agentNameRegistry` in AppState |