minimal-agent 0.8.2 → 0.10.0

package/src/tools/agent/agent.js

@@ -0,0 +1,555 @@
+/**
+ * ============================================================
+ *  src/tools/agent/agent.ts —— Agent 工具（fork 子 agent / 多 agent 并行）
+ * ------------------------------------------------------------
+ *  借鉴 Claude Code 官方 AgentTool/ForkAgent 的核心思想，按 minimal-agent
+ *  内核架构做同步等效实现：
+ *    - 官方 fork = 「隔离 context 嵌套跑同一主循环 + 摘要回传（完整历史不进
+ *      父上下文）」。我们不需要它的后台任务队列/AsyncLocalStorage 身份追踪
+ *      （那是为 Ink UI 后台任务服务的）——本工具同步 await 一个嵌套 runQuery，
+ *      声明 isConcurrencySafe:true 后，模型在同一轮发出 N 个 Agent 调用时，
+ *      loop.ts 现成的并行 worker 队列自动把它们并发执行。这就是并行的全部来源。
+ *    - 同轮混入任一非并发安全工具（如 Edit）会整轮退化串行——这是想要的安全
+ *      语义（写操作与并行 fork 不该交错）。
+ *
+ *  已知限制（如实声明）：
+ *    - 子 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 { withAskSource } from '../../askBridge.js';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { getWorkingDir, withWorkingDir } from '../../bootstrap/workingDir.js';
+import { createSessionState } from '../../session/sessionState.js';
+import { assembleBasePrompt } from '../../prompts/promptAssembly.js';
+import { stripThinkBlocks } from '../../utils/stripThink.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { SUBAGENT_EXCLUDED_TOOLS, resolveAgentType } from './agentTypes.js';
+import { acquireSubagentLease, normalizeWriteScopes } from './coordinator.js';
+import { commitWorktreeChanges, createAgentWorktree, hasWorktreeChanges, removeAgentWorktree, worktreeChangedFiles, worktreeDiffStat, } from './worktree.js';
+let corePromise = null;
+/** 首次调用时才真正加载 loop/tools——此刻模块图早已初始化完毕，环安全。 */
+function loadCore() {
+    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 不需要。'),
+});
+const parameters = toToolParameters(inputSchema);
+// ---------------- 2. Description（给 LLM 看的工具说明） ----------------
+// 借鉴官方 AgentTool prompt 文案（任务书自包含 / 同轮并行 / 何时不用）。
+const description = `- Launches a stateless sub-agent with a fresh, isolated context to execute one self-contained subtask; returns only its final report text (its full working history never enters this conversation).
+- 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.
+- 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 (uncommitted changes are invisible — commit first if it needs them). On completion its changes are auto-committed to a temp branch and the report tail tells you the branch name; review the diff, merge (e.g. \`git merge --squash <branch>\`), then clean up.
+- 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.`;
+// ---------------- 3. 子 agent 系统提示词（memoize，提示词缓存友好） ----------------
+/** 通用附加段：所有 agent_type 共享（拼在 assembleBasePrompt 之后）。 */
+const SUBAGENT_COMMON_APPENDIX = `# 你是子 agent（fork 分身）
+你是主 agent 派生出的子 agent，正在执行一个自包含的子任务：
+- 你看不到主对话；任务书（用户消息）就是你的全部输入。
+- explore 子任务不能向用户提问；general 仅在缺少关键输入或高风险取舍时使用 AskUserQuestion，最多两次。
+- 你的**最后一条回复就是唯一回传主 agent 的报告**，必须自包含：结论 + 关键证据（文件路径/行号）+ 未尽事项。
+  不要输出「我完成了」这类无信息量收尾，也不要在报告里向主 agent 提问——它不会回复你。`;
+/**
+ * 提示词缓存友好：同回合 N 个同类型并行分身必须拿到**逐字节相同**的 system
+ * 消息，OpenAI 兼容 provider 的自动前缀缓存才吃得到（Layer 1 含日期、Layer 3
+ * 技能目录实时扫描——不 memoize 的话并行的多次求值可能产生字节差异，打散前缀）。
+ * 任务差异只落在末尾的 user 消息（任务书）——这是官方 fork「占位符字节一致」
+ * 技巧在自动前缀缓存下的原则等价物。
+ */
+const PROMPT_CACHE_TTL_MS = 60_000;
+const promptCache = new Map();
+async function buildSubSystemPrompt(cwd, def, allTools) {
+    const key = `${cwd}::${def.type}`;
+    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 assembleBasePrompt({
+        cwd,
+        tools: subTools,
+        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;
+}
+function positiveInt(value) {
+    const n = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/** worktree 收尾：无改动清理；有改动代提交 + 生成给主 agent 的收口指引尾巴。 */
+async function finalizeWorktree(wt, label) {
+    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, signal, ctx, deps = {}) {
+    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 = null;
+    const isolation = input.isolation ?? ctx.subagentConfig?.defaultWriteIsolation ?? 'none';
+    if (def.type === 'general' && isolation === 'worktree') {
+        const created = await createAgentWorktree(`fork-${randomUUID().slice(0, 8)}`);
+        if (!created.ok) {
+            return {
+                ok: false,
+                error: `worktree 隔离创建失败：${created.error}。可改用 isolation:'none'（确保各子任务写不相交的文件）或自己串行执行。`,
+            };
+        }
+        wt = created;
+    }
+    const cwd = wt?.path ?? getWorkingDir();
+    let writeScopes;
+    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.message };
+    }
+    const rootScope = await normalizeWriteScopes(cwd, undefined);
+    let lastPublishAt = 0;
+    const label = input.description;
+    const publish = (line, detail, force = false) => {
+        const now = Date.now();
+        if (!force && now - lastPublishAt < 200)
+            return;
+        lastPublishAt = now;
+        ctx.reportProgress?.(line, detail);
+    };
+    // ---- 子 history：一条 system（压缩按 role 定位，必须存在）+ runQuery 自己 push 任务书 ----
+    const history = [
+        { role: 'system', content: await buildSubSystemPrompt(cwd, def, ALL_TOOLS) },
+    ];
+    const historyLenBefore = history.length;
+    const maxConcurrent = positiveInt(process.env.AGENT_TOOL_MAX_CONCURRENT) ?? ctx.subagentConfig?.maxConcurrent ?? 3;
+    let releaseLease = 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.name === 'AbortError')
+            return { ok: false, error: 'aborted' };
+        return { ok: false, error: `子任务「${label}」进入执行队列失败：${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 = null;
+    const armTimeout = () => {
+        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 = () => {
+        if (!timer)
+            return;
+        clearTimeout(timer);
+        timer = null;
+        remainingTimeoutMs = Math.max(0, remainingTimeoutMs - (Date.now() - timerStartedAt));
+    };
+    const resumeTimeout = () => {
+        if (!ownerCancelController.signal.aborted)
+            armTimeout();
+    };
+    const stopTimeout = () => {
+        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();
+    let askCalls = 0;
+    const guardedExecute = async (name, args, s, c) => {
+        if (!allowedTools.includes(name) || SUBAGENT_EXCLUDED_TOOLS.includes(name)) {
+            return { ok: false, error: `子 agent 类型 ${def.type} 不允许调用 ${name}。` };
+        }
+        if (name === 'AskUserQuestion') {
+            askCalls++;
+            if (def.type !== 'general') {
+                return { ok: false, error: 'explore 子 agent 不能向用户提问，请在报告中记录假设和信息缺口。' };
+            }
+            if (askCalls > 2) {
+                return { ok: false, error: '当前子任务最多向用户提问两次，请基于已有回答完成任务或在报告中说明剩余缺口。' };
+            }
+        }
+        let parsed = {};
+        try {
+            parsed = JSON.parse(args);
+        }
+        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, error: '声明了局部 write_scopes 时禁止 Bash：无法可靠证明命令只写入批准范围。请改用文件工具或使用整个工作目录范围。' };
+        }
+        if (def.type === 'general' && rawPath) {
+            if (isAbsolute(rawPath))
+                return { ok: false, error: `${name} 必须使用工作目录相对路径：${rawPath}` };
+            let physical;
+            try {
+                physical = (await normalizeWriteScopes(cwd, [rawPath]))[0];
+            }
+            catch {
+                return { ok: false, error: `${name} 路径越过工作目录或符号链接边界：${rawPath}` };
+            }
+            const inside = writeScopes.some((scope) => physical === scope || physical.startsWith(`${scope}${sep}`));
+            if (!inside)
+                return { ok: false, 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 () => {
+        publish('正在分析任务', { kind: 'subagent', phase: 'analyzing' }, true);
+        const events = runQuery(input.prompt, {
+            provider: ctx.provider,
+            history,
+            maxTurns,
+            allowedTools,
+            signal: combinedSignal,
+            sessionState: createSessionState(), // 独立会话态，不与主循环/其他分身串扰
+            toolGate: ctx.toolGate, // 继承主循环审批策略（不给可写子 agent 开审批后门）
+            chat: deps.chat,
+            executeTool: guardedExecute,
+            // 受监督宿主（Desktop）下把「监督位」透传给子 agent：子 agent 的浏览器 challenge（验证码/登录）
+            // 仍可由用户在可见浏览器里处理，与主 agent 行为一致；非监督（CLI/-p/TUI）不传 → 子 agent 同样
+            // 非阻塞、绝不挂起。conversationKey 留空以维持子 agent「不认领独立标签页」的既有行为。
+            ...(ctx.browserRun?.supervised
+                ? { browserRun: { conversationKey: '', runId: randomUUID(), supervised: true } }
+                : {}),
+            // 不传 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.name === 'AbortError' || signal?.aborted) {
+            return { ok: false, error: 'aborted' };
+        }
+        return { ok: false, error: `子任务「${label}」执行异常：${e.message}` };
+    }
+    finally {
+        stopTimeout();
+        releaseLease?.();
+    }
+    // ---- 结局映射（直接查 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);
+    }
+    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(),
+            ...(wt && changedFiles.size > 0 ? {
+                worktree: {
+                    id: wt.branch.replace(/^agent\//, ''),
+                    branch: wt.branch,
+                    baseSha: wt.baseSha,
+                    status: 'ready',
+                },
+            } : {}),
+        },
+    };
+}
+// 无宿主上下文的裸 call：拿不到 provider，走统一的缺失错误路径。
+async function call(input, signal) {
+    return runAgentTask(input, signal, {});
+}
+// ---------------- 5. 导出 ----------------
+export const agentTool = {
+    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: runAgentTask,
+};

package/src/tools/agent/agentTypes.js

@@ -0,0 +1,59 @@
+/**
+ * ============================================================
+ *  src/tools/agent/agentTypes.ts —— 内置子 agent 类型（类型即数据）
+ * ------------------------------------------------------------
+ *  借鉴 Claude Code 官方 builtInAgents.ts 的「agent 定义 = 一段提示词附加段
+ *  + 工具白名单 + 轮数上限」模式，按 minimal-agent 减法原则只保留两种：
+ *
+ *    - explore（默认）：严格只读收集调研，不包含任何会写盘的工具。
+ *    - general：可读写执行（松权限裁决：写工具全放开）。并行时各子任务
+ *      必须写互不相交的文件，或经 isolation:'worktree' 走独立分支。
+ *
+ *  不做 plan 类型：explore + 任务书里一句「最后列出关键文件清单」即可表达
+ *  （两次规则：真实需要出现两次再议）。
+ * ============================================================
+ */
+/**
+ * 任何 agent_type 都排除的工具：
+ *   - Agent：防递归 fork（子 agent 再 fork 子 agent，深度失控）。
+ *   - Advisor：每个子 runQuery 有独立的 advisorCalls 预算（{used:0,max:2}），
+ *     N 个并行分身 = 最多 2N 次顾问调用，成本失控；两次规则后再议。
+ */
+export const SUBAGENT_EXCLUDED_TOOLS = [
+    'Agent',
+    'Advisor',
+];
+/** explore 白名单（显式列名，可预期）：严格只读。 */
+export const EXPLORE_ALLOWED_TOOLS = [
+    'Read',
+    'Glob',
+    'Grep',
+    'WebSearch',
+    'WebFetch',
+    'WebBrowser',
+];
+/** 借鉴官方 EXPLORE_AGENT「READ-ONLY MODE」文案中文化。 */
+const EXPLORE_APPENDIX = `# 本次子任务类型：只读调研（explore）
+这是一次只读探索任务：你没有 Edit/Write/Bash/Download 等写工具，严禁尝试创建、修改或删除项目文件。
+你的产出就是调研报告文本本身——
+把结论、关键证据（文件路径 + 行号）、以及没查到的缺口写清楚。`;
+const GENERAL_APPENDIX = `# 本次子任务类型：读写执行（general）
+你可以读写文件、执行命令。写盘前照常先 Read（内核有覆盖保护）。
+只有在关键输入缺失、高风险取舍或无法安全继续时才使用 AskUserQuestion；能从代码、上下文或合理默认值判断时不要打断用户。每个子任务最多提问两次。
+只做任务书里交代的事，不要顺手扩大改动范围；改完在报告里列出动过的每个文件。`;
+const EXPLORE_DEF = {
+    type: 'explore',
+    resolveAllowedTools: (all) => all.filter((n) => EXPLORE_ALLOWED_TOOLS.includes(n)),
+    maxTurns: 50,
+    promptAppendix: EXPLORE_APPENDIX,
+};
+const GENERAL_DEF = {
+    type: 'general',
+    resolveAllowedTools: (all) => all.filter((n) => !SUBAGENT_EXCLUDED_TOOLS.includes(n)),
+    maxTurns: 100,
+    promptAppendix: GENERAL_APPENDIX,
+};
+/** 未知/缺省一律回落 explore（最安全的默认：只读）。 */
+export function resolveAgentType(name) {
+    return name === 'general' ? GENERAL_DEF : EXPLORE_DEF;
+}