minimal-agent 0.10.0 → 0.12.0

package/src/tools/agent/agent.ts

@@ -0,0 +1,837 @@
+/**
+ * ============================================================
+ *  src/tools/agent/agent.ts —— Agent 工具（fork 子 agent / 多 agent 并行）
+ * ------------------------------------------------------------
+ *  借鉴 Claude Code 官方 AgentTool/ForkAgent 的核心思想，按 minimal-agent
+ *  内核架构做可恢复的前台/后台等效实现：
+ *    - 官方 fork = 「隔离 context 嵌套跑同一主循环 + 摘要回传（完整历史不进
+ *      父上下文）」。本工具在隔离 history 中嵌套运行同一主循环，并将私有历史、
+ *      进度和结果写入会话运行存储；前台、后台和重启后续接共用同一执行内核。
+ *    - 同轮多个 Agent 调用仍由 loop.ts 的并行 worker 执行；write scopes 与可选
+ *      worktree 负责隔离真正可并行的写任务。
+ *
+ *  已知限制（如实声明）：
+ *    - 子 agent 的 LoopEvent 不外泄：-p / stream-json 宿主只看到本工具的一对
+ *      tool_start/tool_end；步内进度通过 ToolCallContext.reportProgress 回到宿主。
+ *    - llm/client.ts 的网络退避档位是进程级共享：N 个并行分身同时失败会交错
+ *      抬档、任一成功清零（同 provider 拥塞场景下方向正确，本轮不隔离）。
+ *
+ *  ⚠️ 循环依赖纪律：本文件与 loop.ts / tools/index.ts 构成模块环
+ *  （tools/index → agent → loop → tools/index）。环内模块的**值**一律走下面的
+ *  loadCore() 动态 import 懒加载——静态 import 防不住「agent.ts 自身作为环入口」
+ *  的方向（测试/消费者直接 import 本文件时，tools/index 的 ALL_TOOLS 数组求值
+ *  早于本文件完成初始化，撞 TDZ ReferenceError，已真实发生）。type-only import
+ *  编译期擦除，不受此限。loop.ts 侧的 TOOLS_SCHEMA_TOKENS 懒化是同一纪律的配合。
+ * ============================================================
+ */
+
+import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { access } from 'node:fs/promises';
+import { withAskSource } from '../../askBridge.js';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+
+import { getWorkingDir, withWorkingDir } from '../../bootstrap/workingDir.js';
+import { derivePromptCacheContext } from '../../llm/promptCache.js';
+import type { RunQueryOptions } from '../../loop.js';
+import { createSessionState } from '../../session/sessionState.js';
+import {
+  assembleStablePrompt,
+  buildTransientPromptBundle,
+} from '../../prompts/promptAssembly.js';
+import {
+  createAgentRuntimeContext,
+  filterToolsForRuntime,
+} from '../../runtime/agentRuntimeContext.js';
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { stripThinkBlocks } from '../../utils/stripThink.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { type AgentTypeDef, SUBAGENT_EXCLUDED_TOOLS, resolveAgentType } from './agentTypes.js';
+import { acquireSubagentLease, normalizeWriteScopes } from './coordinator.js';
+import {
+  type AgentWorktree,
+  commitWorktreeChanges,
+  createAgentWorktree,
+  hasWorktreeChanges,
+  removeAgentWorktree,
+  worktreeChangedFiles,
+  worktreeDiffStat,
+} from './worktree.js';
+import { appendAgentEvent, loadAgentRecord, saveAgentRecord, type AgentTaskRecord, type LiveAgentTask } from './agentTaskService.js';
+
+// ---------------- 0. 环内模块懒加载（见文件头「循环依赖纪律」） ----------------
+
+interface CoreModules {
+  runQuery: typeof import('../../loop.js')['runQuery'];
+  ALL_TOOLS: typeof import('../index.js')['ALL_TOOLS'];
+  executeTool: typeof import('../index.js')['executeTool'];
+}
+let corePromise: Promise<CoreModules> | null = null;
+
+/** 首次调用时才真正加载 loop/tools——此刻模块图早已初始化完毕，环安全。 */
+function loadCore(): Promise<CoreModules> {
+  if (!corePromise) {
+    corePromise = Promise.all([import('../../loop.js'), import('../index.js')]).then(
+      ([loop, tools]) => ({
+        runQuery: loop.runQuery,
+        ALL_TOOLS: tools.ALL_TOOLS,
+        executeTool: tools.executeTool,
+      }),
+    );
+  }
+  return corePromise;
+}
+
+// ---------------- 1. Zod 输入 schema ----------------
+
+const inputSchema = z.object({
+  description: z
+    .string()
+    .min(1)
+    .max(60, 'description 太长（>60 字符）——它是进度显示用的短标签')
+    .describe('子任务短标签（3-8 个词，进度显示用，如「检索路由实现」）'),
+  prompt: z
+    .string()
+    .min(1)
+    .describe(
+      '完整自包含的任务书。子 agent 是无状态的、看不到当前对话——' +
+        '所有背景、涉及的文件路径、期望的产出格式都必须写进来',
+    ),
+  agent_type: z
+    .enum(['explore', 'general'])
+    .optional()
+    .describe('explore=只读收集调研（默认，可并行放心用）；general=可读写执行'),
+  isolation: z
+    .enum(['none', 'worktree'])
+    .optional()
+    .describe(
+      'worktree=在独立 git worktree 分支中执行（仅 general 生效；并行写同一批文件时用，' +
+        '完成后主 agent 审阅并合并分支）',
+    ),
+  write_scopes: z
+    .array(z.string().min(1))
+    .max(32)
+    .optional()
+    .describe(
+      'general 预计修改的工作目录相对路径。范围互不重叠时可并行；缺省时按整个工作目录串行。explore 不需要。',
+    ),
+  run_in_background: z.boolean().optional().describe('立即返回 agent_id，子任务在后台运行；用 TaskOutput/TaskStop 管理'),
+  resume_agent_id: z.string().regex(/^agent_[0-9a-f-]{36}$/i).optional().describe('继续当前会话中此前完成、中断或失败的 Agent 历史'),
+});
+type AgentInput = z.infer<typeof inputSchema>;
+
+const parameters = toToolParameters(inputSchema);
+
+// ---------------- 2. Description（给 LLM 看的工具说明） ----------------
+// 借鉴官方 AgentTool prompt 文案（任务书自包含 / 同轮并行 / 何时不用）。
+
+const description = `- Launches an isolated sub-agent for one self-contained task. Every run returns an agent_id; run_in_background=true continues without blocking, and resume_agent_id continues its persisted private history across user turns or an app restart.
+- The sub-agent CANNOT see this conversation. The \`prompt\` must be fully self-contained: background, exact file paths, what to look for / do, and the expected output format.
+- **To parallelize, emit multiple Agent calls in ONE assistant message** — they run concurrently. This is the main value of this tool.
+- Background Agent progress/results are read with TaskOutput and stopped with TaskStop. Do not poll: TaskOutput(block=true) waits efficiently.
+- Use for: exploring/researching several independent areas of a codebase at once, parallel information gathering from multiple sources, independent analyses that will be synthesized afterwards, and (with agent_type:'general') genuinely parallelizable write/execute work.
+- Do NOT use for: single targeted lookups that one or two direct tool calls would answer (a fork starts cold and re-derives context — slower and costlier), or strictly sequential work. Only general execution agents may ask the user, and only when genuinely blocked.
+- agent_type: 'explore' (default) = strictly read-only research; 'general' = read-write execution. For direct writes, declare relative write_scopes; disjoint scopes may run concurrently, overlapping or omitted scopes are serialized.
+- isolation:'worktree' (general only): the sub-agent sees the repo's last COMMITTED state. Never commit the user's work merely to expose uncommitted changes; instead keep the task in the current workspace or make the task self-contained. On completion its changes are committed only to a temporary branch; review before applying it to the user's workspace.
+- After sub-agents return you MUST synthesize: cross-check contradictions between reports, integrate into one conclusion — never just forward raw reports. A failed/timed-out fork is not a blocker: proceed with what you have and state the gap.
+- Each sub-task result carries coveredFiles: the actual files/URLs the sub-agent read, extracted from its tool-call history (not self-reported). Before trusting a conclusion, audit its coveredFiles for gaps/overlaps — if coverage looks too thin for what it claims, treat that conclusion as low-confidence.`;
+
+// ---------------- 3. 子 agent 系统提示词（memoize，提示词缓存友好） ----------------
+
+/** 任务回传契约。能力与权限已经由 assembleBasePrompt profile 精确注入。 */
+const SUBAGENT_COMMON_APPENDIX = `# 你是子 agent（fork 分身）
+你是主 agent 派生出的子 agent，正在执行一个自包含的子任务：
+- 你看不到主对话；任务书（用户消息）就是你的全部输入。
+- 你的**最后一条回复就是唯一回传主 agent 的报告**，必须自包含：结论 + 关键证据（文件路径/行号）+ 未尽事项。
+  不要输出「我完成了」这类无信息量收尾，也不要在报告里向主 agent 提问——它不会回复你。`;
+
+/**
+ * 提示词缓存友好：同回合 N 个同类型并行分身必须拿到**逐字节相同**的 system
+ * 消息，OpenAI 兼容 provider 的自动前缀缓存才吃得到（Layer 1 含日期、Layer 3
+ * 技能目录实时扫描——不 memoize 的话并行的多次求值可能产生字节差异，打散前缀）。
+ * 任务差异只落在末尾的 user 消息（任务书）——这是官方 fork「占位符字节一致」
+ * 技巧在自动前缀缓存下的原则等价物。
+ */
+const PROMPT_CACHE_TTL_MS = 60_000;
+const promptCache = new Map<string, { value: string; at: number }>();
+
+async function buildSubSystemPrompt(
+  cwd: string,
+  def: AgentTypeDef,
+  allTools: Tool[],
+): Promise<string> {
+  // Effective capabilities are part of prompt identity; a child must never
+  // reuse a cached parent-capability prompt (notably Desktop WebBrowser).
+  const key = `${cwd}::${def.type}::${allTools.map((tool) => tool.name).join(',')}`;
+  const hit = promptCache.get(key);
+  if (hit && Date.now() - hit.at < PROMPT_CACHE_TTL_MS) return hit.value;
+
+  const allowedNames = def.resolveAllowedTools(allTools.map((t) => t.name));
+  const subTools = allTools.filter((t) => allowedNames.includes(t.name));
+  const base = await assembleStablePrompt({
+    cwd,
+    tools: subTools,
+    profile: def.type === 'general' ? 'subagent-general' : 'subagent-explore',
+    includeProjectInstructions: true, // 子 agent 在同一仓库干活，项目约定必须继承
+    includePlugins: false, // 插件是宿主命令面，子 agent 不该被引去激活插件
+  });
+  const value = [base, SUBAGENT_COMMON_APPENDIX, def.promptAppendix].join('\n\n');
+  promptCache.set(key, { value, at: Date.now() });
+  return value;
+}
+
+// ---------------- 3.5 覆盖度提取（客观，从工具调用历史推导） ----------------
+
+/**
+ * 从子任务 history 中提取「实际读取/调研过的文件/目标」清单，
+ * 用于父 agent / 宿主做覆盖度自检，避免「以为覆盖了其实没覆盖」的幻觉。
+ */
+export function extractCoveredFiles(
+  history: readonly import('../../types.js').Message[],
+  startIdx: number,
+): string[] {
+  const seen = new Set<string>();
+  for (let i = startIdx; i < history.length; i++) {
+    const msg = history[i]!;
+    if (msg.role !== 'assistant' || !msg.tool_calls) continue;
+    for (const tc of msg.tool_calls) {
+      const name = tc.function.name;
+      let args: Record<string, unknown> | undefined;
+      try { args = JSON.parse(tc.function.arguments); } catch { continue; }
+      if (!args) continue;
+      if (name === 'Read' && typeof args.file_path === 'string') {
+        seen.add(args.file_path);
+      } else if (name === 'Glob' && typeof args.pattern === 'string') {
+        seen.add(`glob:${args.pattern}`);
+      } else if (name === 'Grep') {
+        const parts = ['grep:' + (typeof args.pattern === 'string' ? args.pattern : '?')];
+        if (typeof args.path === 'string') parts.push(`path=${args.path}`);
+        if (typeof args.glob === 'string') parts.push(`glob=${args.glob}`);
+        seen.add(parts.join(' '));
+      } else if (name === 'WebFetch' && typeof args.url === 'string') {
+        seen.add(args.url);
+      } else if (name === 'WebBrowser' && typeof args.url === 'string') {
+        seen.add(`browser:${args.url}`);
+      }
+    }
+  }
+  return [...seen].sort();
+}
+
+// ---------------- 4. 执行逻辑（导出供测试 DI） ----------------
+
+/** 测试注入缝（镜像 runAdvisor 的 chatFn 模式）：生产不传，走真实模块。 */
+export interface AgentTaskDeps {
+  chat?: RunQueryOptions['chat'];
+  executeTool?: RunQueryOptions['executeTool'];
+  initialHistory?: RunQueryOptions['history'];
+  captureHistory?: (history:RunQueryOptions['history'])=>void|Promise<void>;
+  existingWorktree?: AgentWorktree;
+  onWorktreeCreated?: (worktree: AgentWorktree) => void | Promise<void>;
+}
+
+function positiveInt(value: string | undefined): number | undefined {
+  const n = Number.parseInt(value ?? '', 10);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/** worktree 收尾：无改动清理；有改动代提交 + 生成给主 agent 的收口指引尾巴。 */
+async function finalizeWorktree(wt: AgentWorktree, label: string): Promise<string> {
+  const changed = await hasWorktreeChanges(wt.path, wt.baseSha);
+  if (!changed) {
+    await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+    return '';
+  }
+  const commit = await commitWorktreeChanges(wt.path, `agent fork: ${label}`);
+  const stat = await worktreeDiffStat(wt.path, wt.baseSha);
+  return [
+    '',
+    '———',
+    '⚠️ 子任务在独立 worktree 分支产生了改动（尚未合并回主工作区）：',
+    `- 分支：${wt.branch}`,
+    `- 隔离任务：${wt.branch.replace(/^agent\//, '')}`,
+    commit.ok ? '' : `- ⚠️ 自动提交失败（${commit.error}），改动仍留在 worktree 工作区未入分支`,
+    stat ? `- 改动摘要：\n${stat}` : '',
+    '主 agent 收口步骤：',
+    `1. 审阅改动：\`git diff ${wt.baseSha.slice(0, 12)} ${wt.branch}\`；`,
+    `2. 确认后在主工作区合并：\`git merge --squash ${wt.branch}\` 后提交（或按需 cherry-pick）；`,
+    '3. 在 KakadeAI 子任务卡中应用或放弃该隔离变更。',
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+/**
+ * 真正的执行逻辑：在隔离的 history + 独立 sessionState 上嵌套跑一个完整
+ * runQuery 子循环，把最终报告文本作为 ToolResult 回传。
+ *
+ * 刻意**不走 runTurn/runAgentTurn**：它们会 acquireContextLock（非重入锁，
+ * 主 turn 全程持锁 → 同 sessionFile 必死锁）并 saveContext 落盘——子 agent
+ * 应该零磁盘足迹、用完即弃。
+ */
+export async function runAgentTask(
+  input: AgentInput,
+  signal: AbortSignal | undefined,
+  ctx: ToolCallContext,
+  deps: AgentTaskDeps = {},
+): Promise<ToolResult> {
+  const startedAt = Date.now();
+  // ---- 前置检查 ----
+  if (!ctx.provider) {
+    return {
+      ok: false,
+      error: '子任务功能不可用（内核未透传 provider），请自己直接执行该任务。',
+    };
+  }
+  if (ctx.agentCalls && ctx.agentCalls.used >= ctx.agentCalls.max) {
+    return {
+      ok: false,
+      error: `本回合子任务派生已达上限（${ctx.agentCalls.max} 次），剩余工作请自己直接完成。`,
+    };
+  }
+  if (ctx.agentCalls) ctx.agentCalls.used++;
+
+  const { runQuery, ALL_TOOLS, executeTool } = await loadCore();
+
+  const def = resolveAgentType(input.agent_type);
+  // 轮数上限：AGENT_TOOL_MAX_TURNS 可统一覆盖两种类型（默认 explore 50 / general 100）。
+  const maxTurns = positiveInt(process.env.AGENT_TOOL_MAX_TURNS)
+    ?? (def.type === 'explore' ? ctx.subagentConfig?.exploreMaxTurns : ctx.subagentConfig?.generalMaxTurns)
+    ?? def.maxTurns;
+  // allowedTools 只裁「下发给模型的清单」；guardedExecute 是真正的硬防线（见下）。
+  const allowedTools = def.resolveAllowedTools(ALL_TOOLS.map((t) => t.name));
+
+  // ---- worktree 隔离（仅 general 显式要求时） ----
+  let wt: AgentWorktree | null = deps.existingWorktree ?? null;
+  const isolation = input.isolation ?? ctx.subagentConfig?.defaultWriteIsolation ?? 'none';
+  if (def.type === 'general' && isolation === 'worktree' && !wt) {
+    const created = await createAgentWorktree(`fork-${randomUUID().slice(0, 8)}`, ctx.cwd);
+    if (!created.ok) {
+      return {
+        ok: false,
+        error: `worktree 隔离创建失败：${created.error}。可改用 isolation:'none'（确保各子任务写不相交的文件）或自己串行执行。`,
+      };
+    }
+    wt = created;
+    await deps.onWorktreeCreated?.(created);
+  }
+  const cwd = wt?.path ?? ctx.cwd ?? getWorkingDir();
+  let writeScopes: string[];
+  try {
+    writeScopes = def.type === 'general'
+      ? await normalizeWriteScopes(cwd, wt ? ['.'] : input.write_scopes)
+      : [];
+  } catch (error) {
+    if (wt) await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+    return { ok: false, error: (error as Error).message };
+  }
+  const rootScope = await normalizeWriteScopes(cwd, undefined);
+  const childMemoryAccess = ctx.memoryAccess === 'denied' || !ctx.memoryAccess
+    ? 'denied'
+    : 'read-only';
+  const childRuntime = createAgentRuntimeContext({
+    surface: 'subagent',
+    profile: def.type === 'general' ? 'subagent-general' : 'subagent-explore',
+    cwd,
+    workspaceId: ctx.workspaceId,
+    sessionId: ctx.sessionId,
+    owner: childMemoryAccess === 'denied' ? 'untrusted' : 'local-owner',
+    memoryAccess: childMemoryAccess,
+    interactiveAsk: def.type === 'general',
+    toolGate: ctx.toolGate,
+  });
+  const subTools = filterToolsForRuntime(
+    ALL_TOOLS.filter((tool) => allowedTools.includes(tool.name)),
+    childRuntime,
+  );
+  const subToolNames = subTools.map((tool) => tool.name);
+  const childTransientBundle = await buildTransientPromptBundle({
+    cwd,
+    tools: subTools,
+    profile: childRuntime.profile,
+    includeProjectInstructions: true,
+    includePlugins: false,
+    runtime: {
+      surface: 'subagent',
+      cwd,
+      workspaceId: ctx.workspaceId,
+      sessionId: ctx.sessionId,
+      interactiveAsk: childRuntime.interactiveAsk,
+      memoryAccess: childMemoryAccess,
+      currentUserInput: input.prompt,
+    },
+  }).catch(() => undefined);
+
+  let lastPublishAt = 0;
+  const label = input.description;
+  const publish = (line: string, detail?: import('../../types.js').ToolProgressDetail, force = false): void => {
+    const now = Date.now();
+    if (!force && now - lastPublishAt < 200) return;
+    lastPublishAt = now;
+    ctx.reportProgress?.(line, detail);
+  };
+
+  // ---- 子 history：一条 system（压缩按 role 定位，必须存在）+ runQuery 自己 push 任务书 ----
+  const history: RunQueryOptions['history'] = deps.initialHistory?.length ? [...deps.initialHistory] : [
+    { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools) },
+  ];
+  const historyLenBefore = history.length;
+  const maxConcurrent = positiveInt(process.env.AGENT_TOOL_MAX_CONCURRENT) ?? ctx.subagentConfig?.maxConcurrent ?? 3;
+  let releaseLease: (() => void) | null = null;
+  try {
+    releaseLease = await acquireSubagentLease(
+      cwd,
+      def.type === 'general' ? writeScopes : [`__read__/${randomUUID()}`],
+      maxConcurrent,
+      {
+        signal,
+        onStatus: (status) => {
+          if (status.phase === 'queued') {
+            publish(`排队中${status.queuePosition ? ` · 第 ${status.queuePosition} 位` : ''}`, {
+              kind: 'subagent',
+              phase: 'queued',
+              queuePosition: status.queuePosition,
+              activeCount: status.activeCount,
+              maxConcurrent: status.maxConcurrent,
+            }, true);
+          } else {
+            publish('准备上下文', {
+              kind: 'subagent', phase: 'preparing', activeCount: status.activeCount, maxConcurrent: status.maxConcurrent,
+            }, true);
+          }
+        },
+      },
+    );
+  } catch (error) {
+    if ((error as Error).name === 'AbortError') return { ok: false, error: 'aborted' };
+    return { ok: false, error: `子任务「${label}」进入执行队列失败：${(error as Error).message}` };
+  }
+
+  // ---- 超时兜底（仿 Advisor 模式；默认 30 分钟——50/100 轮的真实审计/执行型
+  //      子任务 10 分钟跑不完，超时是兜底不是预期时长，env 可调低） ----
+  const timeoutMs = positiveInt(process.env.AGENT_TOOL_TIMEOUT_MS) ?? ctx.subagentConfig?.timeoutMs ?? 1_800_000;
+  const timeoutController = new AbortController();
+  const ownerCancelController = new AbortController();
+  let remainingTimeoutMs = timeoutMs;
+  let timerStartedAt = 0;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const armTimeout = (): void => {
+    if (timer || timeoutController.signal.aborted) return;
+    if (remainingTimeoutMs <= 0) {
+      timeoutController.abort(new Error('agent-task-timeout'));
+      return;
+    }
+    timerStartedAt = Date.now();
+    timer = setTimeout(() => {
+      timer = null;
+      remainingTimeoutMs = 0;
+      timeoutController.abort(new Error('agent-task-timeout'));
+    }, remainingTimeoutMs);
+  };
+  const pauseTimeout = (): void => {
+    if (!timer) return;
+    clearTimeout(timer);
+    timer = null;
+    remainingTimeoutMs = Math.max(0, remainingTimeoutMs - (Date.now() - timerStartedAt));
+  };
+  const resumeTimeout = (): void => {
+    if (!ownerCancelController.signal.aborted) armTimeout();
+  };
+  const stopTimeout = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+  armTimeout();
+  const combinedSignal = signal
+    ? AbortSignal.any([signal, timeoutController.signal, ownerCancelController.signal])
+    : AbortSignal.any([timeoutController.signal, ownerCancelController.signal]);
+
+  // ---- 递归硬防线：allowedTools 只影响模型可见清单，不拦 executeTool 的
+  //      全局调度口（loop.ts 注释明示）；这里把排除工具在执行层直接拒绝。 ----
+  const baseExecute = deps.executeTool ?? executeTool;
+  const changedFiles = new Set<string>();
+  let askCalls = 0;
+  const guardedExecute: NonNullable<RunQueryOptions['executeTool']> = async (name, args, s, c) => {
+    if (!allowedTools.includes(name) || SUBAGENT_EXCLUDED_TOOLS.includes(name)) {
+      return { ok: false as const, error: `子 agent 类型 ${def.type} 不允许调用 ${name}。` };
+    }
+    if (name === 'AskUserQuestion') {
+      askCalls++;
+      if (def.type !== 'general') {
+        return { ok: false as const, error: 'explore 子 agent 不能向用户提问，请在报告中记录假设和信息缺口。' };
+      }
+      if (askCalls > 2) {
+        return { ok: false as const, error: '当前子任务最多向用户提问两次，请基于已有回答完成任务或在报告中说明剩余缺口。' };
+      }
+    }
+    let parsed: Record<string, unknown> = {};
+    try { parsed = JSON.parse(args) as Record<string, unknown>; } catch { /* executeTool will report malformed input */ }
+    const rawPath = typeof parsed.file_path === 'string' ? parsed.file_path : typeof parsed.path === 'string' ? parsed.path : undefined;
+    if (def.type === 'general' && !wt && name === 'Bash' && writeScopes[0] !== rootScope[0]) {
+      return { ok: false as const, error: '声明了局部 write_scopes 时禁止 Bash：无法可靠证明命令只写入批准范围。请改用文件工具或使用整个工作目录范围。' };
+    }
+    if (def.type === 'general' && rawPath) {
+      if (isAbsolute(rawPath)) return { ok: false as const, error: `${name} 必须使用工作目录相对路径：${rawPath}` };
+      let physical: string;
+      try { physical = (await normalizeWriteScopes(cwd, [rawPath]))[0]!; }
+      catch { return { ok: false as const, error: `${name} 路径越过工作目录或符号链接边界：${rawPath}` }; }
+      const inside = writeScopes.some((scope) => physical === scope || physical.startsWith(`${scope}${sep}`));
+      if (!inside) return { ok: false as const, error: `${name} 路径超出 write_scopes：${rawPath}` };
+      if (['Edit', 'MultiEdit', 'Write', 'Download'].includes(name)) {
+        changedFiles.add(relative(cwd, resolve(cwd, rawPath)).split(sep).join('/'));
+      }
+    }
+    return baseExecute(name, args, s, c);
+  };
+
+  // ---- 事件消费：子 LoopEvent 一律不外泄，折算成统计 + 步内进度 ----
+  let turns = 0;
+  let toolOk = 0;
+  let toolFail = 0;
+  let textChars = 0;
+  let sawLlmError = false;
+  let llmErrorDetail = '';
+  let sawMaxTurns = false;
+
+  const consumeRun = async (): Promise<void> => {
+    publish('正在分析任务', { kind: 'subagent', phase: 'analyzing' }, true);
+    const events = runQuery(input.prompt, {
+      provider: ctx.provider!,
+      runtimeContext: childRuntime,
+      history,
+      maxTurns,
+      allowedTools: subToolNames,
+      signal: combinedSignal,
+      sessionState: createSessionState(), // 独立会话态，不与主循环/其他分身串扰
+      toolGate: ctx.toolGate, // 继承主循环审批策略（不给可写子 agent 开审批后门）
+      chat: deps.chat,
+      executeTool: guardedExecute,
+      memoryContext: {
+        access: childMemoryAccess,
+        workspaceId: ctx.workspaceId,
+        sessionId: ctx.sessionId,
+      },
+      transientBundle: childTransientBundle,
+      promptCache: derivePromptCacheContext(
+        ctx.promptCache,
+        `subagent:${ctx.toolCallId ?? input.description}`,
+      ),
+      // 不传 transientContext：任务书必须自包含，父回合的瞬时上下文不该隐式泄入
+    });
+    for await (const ev of events) {
+      switch (ev.type) {
+        case 'assistant_message':
+          turns++;
+          break;
+        case 'tool_start':
+          publish(`正在执行 · ${ev.argsFriendly ?? ev.toolName}`, {
+            kind: 'subagent',
+            phase: 'using_tool',
+            turn: Math.max(turns, 1),
+            toolName: ev.toolName,
+            toolDescription: ev.argsFriendly,
+          }, true);
+          break;
+        case 'tool_end':
+          if (ev.ok) toolOk++;
+          else toolFail++;
+          break;
+        case 'text':
+          textChars += ev.delta.length;
+          publish(`正在整理结论 · ${textChars} 字`, {
+            kind: 'subagent', phase: 'drafting', turn: Math.max(turns, 1), outputChars: textChars,
+          });
+          break;
+        case 'error':
+          // 中断（code:'aborted'）不在这里判——结局映射直接查 signal 状态更可靠
+          // （中断在 loop 里有三种浮出形态：入口 error / AbortError catch / interrupted 事件）。
+          if (ev.code === 'llm_error') {
+            sawLlmError = true;
+            llmErrorDetail = ev.error;
+          } else if (ev.code === 'max_turns') sawMaxTurns = true;
+          // compact_failed 非致命：loop 自己会硬上，这里无需处理
+          break;
+        default:
+          break; // 其余事件（text 流/压缩/context_usage…）对父层不可见
+      }
+    }
+  };
+
+  try {
+    // worktree 模式下整个子执行在 ALS 作用域内以 worktree 为 cwd（相对路径
+    // 工具全部落进隔离目录）；并行的多个分身各自的 ALS 作用域互不干扰。
+    const execute = () => withAskSource(
+      { kind: 'subagent', parentToolCallId: ctx.toolCallId, description: label },
+      {
+        onWaitStart: () => {
+          pauseTimeout();
+          publish('等待你的回答', { kind: 'subagent', phase: 'waiting_owner' }, true);
+        },
+        onWaitEnd: () => {
+          resumeTimeout();
+          publish('已回答，继续分析', { kind: 'subagent', phase: 'analyzing' }, true);
+        },
+        onCancel: () => ownerCancelController.abort(new Error('owner-cancelled-subagent')),
+      },
+      consumeRun,
+    );
+    if (wt) await withWorkingDir(wt.path, execute);
+    else await execute();
+  } catch (e) {
+    stopTimeout();
+    if (wt) await finalizeWorktree(wt, label); // fail-closed：有改动会保留分支
+    if (ownerCancelController.signal.aborted) {
+      return { ok: false, error: `子任务「${label}」已由 Agent 所有者取消。` };
+    }
+    if ((e as Error).name === 'AbortError' || signal?.aborted) {
+      return { ok: false, error: 'aborted' };
+    }
+    return { ok: false, error: `子任务「${label}」执行异常：${(e as Error).message}` };
+  } finally {
+    stopTimeout();
+    releaseLease?.();
+    await deps.captureHistory?.(history);
+  }
+
+  // ---- 结局映射（直接查 signal 状态，不依赖事件旗标） ----
+  if (ownerCancelController.signal.aborted) {
+    if (wt) await finalizeWorktree(wt, label);
+    return { ok: false, error: `子任务「${label}」已由 Agent 所有者取消。` };
+  }
+  // 用户中断：回传 loop 认识的字面量 'aborted'（它据此把整轮判为 interrupted）。
+  if (signal?.aborted) {
+    if (wt) await finalizeWorktree(wt, label);
+    return { ok: false, error: 'aborted' };
+  }
+  // 超时（timeoutController 触发而非用户中断）
+  if (timeoutController.signal.aborted) {
+    const wtTail = wt ? await finalizeWorktree(wt, label) : '';
+    return {
+      ok: false,
+      error:
+        `子任务「${label}」超过 ${Math.round(timeoutMs / 1000)}s 未完成，已终止。` +
+        `可缩小任务范围重试，或自己直接执行。${wtTail}`,
+    };
+  }
+
+  // ---- 产出提取：history 尾部倒扫最后一条非空 assistant 文本（剥 <think>） ----
+  let report = '';
+  for (let i = history.length - 1; i >= historyLenBefore; i--) {
+    const msg = history[i]!;
+    if (msg.role !== 'assistant' || !msg.content) continue;
+    const cleaned = stripThinkBlocks(msg.content);
+    if (cleaned) {
+      report = cleaned;
+      break;
+    }
+  }
+
+  if (!report && sawLlmError) {
+    const wtTail = wt ? await finalizeWorktree(wt, label) : '';
+    return { ok: false, error: `子任务「${label}」LLM 调用失败：${llmErrorDetail}${wtTail}` };
+  }
+  if (!report && sawMaxTurns) {
+    const wtTail = wt ? await finalizeWorktree(wt, label) : '';
+    return {
+      ok: false,
+      error: `子任务「${label}」达到轮数上限（${maxTurns} 轮）被截断且没有产出。可把任务拆得更小重试。${wtTail}`,
+    };
+  }
+  if (!report) {
+    const wtTail = wt ? await finalizeWorktree(wt, label) : '';
+    return { ok: false, error: `子任务「${label}」没有产出任何文本。${wtTail}` };
+  }
+
+  if (sawMaxTurns) {
+    report = `⚠️ 子任务达到轮数上限（${maxTurns} 轮）被截断，以下是截断时的最后输出（可能不完整）：\n\n${report}`;
+  }
+
+  // ---- 统计尾巴：主 agent 收口时评估报告可信度用 ----
+  const toolTotal = toolOk + toolFail;
+  report += `\n\n———\n（子任务「${label}」[${def.type}]：${turns} 轮 · ${toolTotal} 次工具调用${toolFail > 0 ? `，${toolFail} 次失败` : ''}）`;
+
+  if (wt) {
+    for (const path of await worktreeChangedFiles(wt.path, wt.baseSha)) changedFiles.add(path);
+    report += await finalizeWorktree(wt, label);
+  }
+
+  // 覆盖度提取（客观，从 tool call 历史推导）——在截断之前，不受报告长度影响。
+  const coveredFiles = extractCoveredFiles(history, historyLenBefore);
+  if (report.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+    report =
+      report.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
+      `\n\n... (报告超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
+  }
+  return {
+    ok: true,
+    content: report,
+    metadata: {
+      kind: 'agent',
+      agentType: def.type,
+      description: label,
+      isolation: wt ? 'worktree' : 'none',
+      turns,
+      toolCalls: toolTotal,
+      failedToolCalls: toolFail,
+      durationMs: Date.now() - startedAt,
+      changedFiles: [...changedFiles].sort(),
+      coveredFiles,
+      ...(wt && changedFiles.size > 0 ? {
+        worktree: {
+          id: wt.branch.replace(/^agent\//, ''),
+          branch: wt.branch,
+          baseSha: wt.baseSha,
+          status: 'ready' as const,
+        },
+      } : {}),
+    },
+  };
+}
+
+// 无宿主上下文的裸 call：拿不到 provider，走统一的缺失错误路径。
+async function call(input: AgentInput, signal?: AbortSignal): Promise<ToolResult> {
+  return runAgentTask(input, signal, {});
+}
+
+export async function runManagedAgentTask(
+  input: AgentInput,
+  signal: AbortSignal | undefined,
+  ctx: ToolCallContext,
+  deps: AgentTaskDeps = {},
+): Promise<ToolResult> {
+  if (!ctx.sessionState) return runAgentTask(input, signal, ctx);
+  const id = input.resume_agent_id ?? `agent_${randomUUID()}`;
+  let initialHistory: RunQueryOptions['history'] | undefined;
+  let resumedWorktree: AgentWorktree | undefined;
+  let coreInput = { ...input, run_in_background: undefined, resume_agent_id: undefined };
+  if (input.resume_agent_id) {
+    const live = ctx.sessionState.agentTasks.tasks.get(id);
+    if (live?.status === 'running') return { ok: false, error: `Agent ${id} 正在运行，不能并发恢复` };
+    const saved = await loadAgentRecord(ctx, id);
+    if (!saved) return { ok: false, error: `找不到可恢复 Agent：${id}` };
+    initialHistory = saved.history;
+    resumedWorktree = saved.worktree && await access(saved.worktree.path)
+      .then(() => saved.worktree)
+      .catch(() => undefined);
+    coreInput = {
+      ...(saved.input as AgentInput),
+      prompt: input.prompt,
+      description: input.description || saved.description,
+      run_in_background: undefined,
+      resume_agent_id: undefined,
+    };
+  }
+  const abort = new AbortController();
+  const combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+  let settle!: () => void;
+  const completion = new Promise<void>((resolvePromise) => { settle = resolvePromise; });
+  const task: LiveAgentTask = {
+    id,
+    status: 'running',
+    description: coreInput.description,
+    input: coreInput as unknown as Record<string, unknown>,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    abort,
+    completion,
+    events: new EventEmitter(),
+  };
+  ctx.sessionState.agentTasks.tasks.set(id, task);
+  await saveAgentRecord(ctx, task);
+  await appendAgentEvent(ctx, id, { phase: 'started', resumed: Boolean(input.resume_agent_id) });
+
+  const run = async (): Promise<ToolResult> => {
+    let captured = initialHistory;
+    let lastPersistedProgressAt = 0;
+    const managedContext: ToolCallContext = {
+      ...ctx,
+      reportProgress: (line, detail) => {
+        ctx.reportProgress?.(line, detail);
+        task.progress = line;
+        task.events.emit('change');
+        if (Date.now() - lastPersistedProgressAt >= 1_000) {
+          lastPersistedProgressAt = Date.now();
+          void saveAgentRecord(ctx, task).catch(() => undefined);
+          void appendAgentEvent(ctx, id, { phase: 'progress', message: line })
+            .catch(() => undefined);
+        }
+      },
+    };
+    try {
+      const result = await runAgentTask(coreInput, combined, managedContext, {
+        ...deps,
+        initialHistory,
+        existingWorktree: resumedWorktree,
+        onWorktreeCreated: async (worktree) => {
+          task.worktree = worktree;
+          await saveAgentRecord(ctx, task);
+        },
+        captureHistory: (history) => { captured = [...history]; },
+      });
+      task.result = result;
+      task.history = captured;
+      task.status = abort.signal.aborted ? 'stopped' : result.ok ? 'completed' : 'failed';
+      if (task.worktree && !await access(task.worktree.path).then(() => true).catch(() => false)) {
+        task.worktree = undefined;
+      }
+      task.updatedAt = Date.now();
+      await saveAgentRecord(ctx, task);
+      await appendAgentEvent(ctx, id, { phase: task.status, ok: result.ok });
+      return result;
+    } catch (error) {
+      task.status = abort.signal.aborted ? 'stopped' : 'failed';
+      task.result = { ok: false, error: (error as Error).message };
+      task.history = captured;
+      task.updatedAt = Date.now();
+      await saveAgentRecord(ctx, task).catch(() => undefined);
+      await appendAgentEvent(ctx, id, { phase: task.status, error: (error as Error).message })
+        .catch(() => undefined);
+      return task.result;
+    } finally {
+      task.events.emit('change');
+      settle();
+    }
+  };
+
+  if (input.run_in_background) {
+    void run();
+    return {
+      ok: true,
+      content: `后台 Agent 已启动。agent_id=${id}\n使用 TaskOutput 获取进度/结果，TaskStop 停止。`,
+      metadata: {
+        kind: 'agent', agentId: id, status: 'running',
+        agentType: input.agent_type ?? 'explore', description: input.description,
+        isolation: input.isolation ?? 'none', turns: 0, toolCalls: 0,
+        failedToolCalls: 0, durationMs: 0, changedFiles: [],
+      },
+    };
+  }
+  const result = await run();
+  if (result.ok && result.metadata?.kind === 'agent') {
+    result.metadata.agentId = id;
+    result.metadata.status = 'completed';
+    result.content = `agent_id=${id}\n${result.content}`;
+  } else if (!result.ok) {
+    result.error = `agent_id=${id}\n${result.error}`;
+  }
+  return result;
+}
+
+// ---------------- 5. 导出 ----------------
+
+export const agentTool: Tool<AgentInput> = {
+  name: 'Agent',
+  description,
+  inputSchema,
+  parameters,
+  // isReadOnly=false：general 分身可写盘。isConcurrencySafe=true 是并行的全部
+  // 来源——同轮多个 Agent 调用走 loop.ts 的并行 worker 队列。
+  isReadOnly: false,
+  isConcurrencySafe: true,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  interruptBehavior: () => 'block',
+  call,
+  callWithContext: runManagedAgentTask,
+};