minimal-agent 0.11.0 → 0.13.0

package/src/session/sessionState.js

@@ -12,12 +12,14 @@ import { createMicroCompactState, } from '../context/microCompactLite.js';
 import { createReactiveCompactState, } from '../context/reactiveCompact.js';
 import { createFileReadState } from '../tools/shared/fileState.js';
 import { createBackgroundTaskState, disposeBackgroundTaskState, } from '../tools/tasks/backgroundTaskService.js';
+import { createAgentTaskState, stopAllAgentTasks } from '../tools/agent/agentTaskService.js';
 export function createSessionState() {
     return {
         reactive: createReactiveCompactState(),
         microCompact: createMicroCompactState(),
         fileReads: createFileReadState(),
         backgroundTasks: createBackgroundTaskState(),
+        agentTasks: createAgentTaskState(),
     };
 }
 const persistentStates = new Map();
@@ -56,6 +58,7 @@ export async function disposeSessionState(key) {
         return;
     persistentStates.delete(key);
     await disposeBackgroundTaskState(entry.state.backgroundTasks);
+    await stopAllAgentTasks(entry.state.agentTasks);
     entry.state.fileReads.entries.clear();
 }
 export async function disposeAllSessionStates() {
@@ -63,11 +66,13 @@ export async function disposeAllSessionStates() {
     persistentStates.clear();
     await Promise.all(entries.map(async ({ state }) => {
         await disposeBackgroundTaskState(state.backgroundTasks);
+        await stopAllAgentTasks(state.agentTasks);
         state.fileReads.entries.clear();
     }));
 }
 export async function disposeDetachedSessionState(state) {
     await disposeBackgroundTaskState(state.backgroundTasks);
+    await stopAllAgentTasks(state.agentTasks);
     state.fileReads.entries.clear();
 }
 function prunePersistentStates(now, keepKey) {

package/src/session/sessionState.ts

@@ -23,12 +23,22 @@ import {
   disposeBackgroundTaskState,
   type BackgroundTaskState,
 } from '../tools/tasks/backgroundTaskService.js';
+import { createAgentTaskState, stopAllAgentTasks, type AgentTaskState } from '../tools/agent/agentTaskService.js';
 
 export interface SessionState {
   reactive: ReactiveCompactState;
   microCompact: MicroCompactState;
   fileReads: FileReadState;
   backgroundTasks: BackgroundTaskState;
+  agentTasks: AgentTaskState;
+  /** Main-agent worktree changes the effective cwd without changing workspace identity. */
+  activeWorktree?: {
+    id: string;
+    path: string;
+    branch: string;
+    baseSha: string;
+    gitRoot: string;
+  };
 }
 
 export function createSessionState(): SessionState {
@@ -37,6 +47,7 @@ export function createSessionState(): SessionState {
     microCompact: createMicroCompactState(),
     fileReads: createFileReadState(),
     backgroundTasks: createBackgroundTaskState(),
+    agentTasks: createAgentTaskState(),
   };
 }
 
@@ -84,6 +95,7 @@ export async function disposeSessionState(key: string): Promise<void> {
   if (!entry) return;
   persistentStates.delete(key);
   await disposeBackgroundTaskState(entry.state.backgroundTasks);
+  await stopAllAgentTasks(entry.state.agentTasks);
   entry.state.fileReads.entries.clear();
 }
 
@@ -92,12 +104,14 @@ export async function disposeAllSessionStates(): Promise<void> {
   persistentStates.clear();
   await Promise.all(entries.map(async ({ state }) => {
     await disposeBackgroundTaskState(state.backgroundTasks);
+    await stopAllAgentTasks(state.agentTasks);
     state.fileReads.entries.clear();
   }));
 }
 
 export async function disposeDetachedSessionState(state: SessionState): Promise<void> {
   await disposeBackgroundTaskState(state.backgroundTasks);
+  await stopAllAgentTasks(state.agentTasks);
   state.fileReads.entries.clear();
 }
 

package/src/tools/advisor/advisor.js

@@ -42,11 +42,23 @@ const inputSchema = z.object({
 const parameters = toToolParameters(inputSchema);
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
 const description = `- Consults an independent, separately-configured second LLM ("顾问模型" / advisor) for a second opinion on your current plan, diagnosis, or progress.
-- Call with no arguments in most cases — the advisor receives a bounded, relevant view of the current session (the original request, recent discussion, current plan/diagnosis, and key tool results). Only pass \`note\` if something important is not otherwise clear.
-- Exception: if your current plan/diagnosis relies on things you saw in images (screenshots, photos, diagrams), summarize the key visual facts in \`note\` in 1-2 sentences (what each image shows and what you concluded from it) — the advisor may not be able to see the images themselves, and any visual judgment you never wrote down as text does not exist for it.
-- Call this: (1) after a plan/diagnosis has taken shape but before you commit to it (write code, declare a conclusion); (2) when you're stuck — the same error keeps recurring, your fixes aren't converging, or the user has pushed back and you're reconsidering direction; (3) before declaring a multi-step task complete and reporting back to the user.
+- Call with no arguments in most cases — the advisor receives a bounded, relevant view of the current session (the original request, recent discussion, current plan/diagnosis, and key tool results). Always pass key evidence (original code snippets, raw data, full plan text) in \`note\`, not just your summary — the advisor cannot verify things you never wrote down.
+- Exception: if your current plan/diagnosis relies on things you saw in images (screenshots, photos, diagrams), summarize the key visual facts in \`note\` in 1-2 sentences (what each image shows and what you concluded from it) — the advisor may not be able to see the images themselves.
+- **Call it BEFORE substantive work, not after things go wrong.** The advisor is worth the most before an approach hardens — once you have written the code, the plan is expensive to abandon.
+  - Orientation is NOT substantive work: finding files, reading code, running a command to see the current state. Do that first, then consult.
+  - Substantive work IS: writing or editing files, committing to an interpretation, building on an assumption, declaring an answer.
+- **MUST call Advisor in all 5 of these situations — do not wait for errors or user prompts:**
+  1. After a plan / development plan is finalized, **before** executing it (get critique first, avoid discovering wrong direction halfway)
+  2. **Before** submitting final results to the user (before PresentResult): code reviews, assessment reports, technical selections, refactoring plans — any time you "deliver a conclusion"
+  3. The same error occurs 2+ times in a row, or fixes are not converging (early sign of infinite loop — switch approach immediately)
+  4. The user gives unsatisfied feedback a **second time** in the same turn (stop spinning in place, get a fresh perspective first)
+  5. Decisions involving security, data loss, or irreversible operations (advisor double-check)
+- **Make your work durable BEFORE calling in situation 2.** Write the file, save the result. This call takes time; if the turn ends during it, a written file survives and an unwritten answer does not.
+- On a long task, consult at least twice: once before the approach is locked in, once before you declare it done. On a short reactive task whose next step is dictated by output you just read, one call is enough — the advisor adds most of its value early.
+- **Take the advice seriously, but do not obey it blindly.** Adapt if you follow a step and it empirically fails, or you hold primary-source evidence contradicting a specific claim (the file says X, the test output says Y). A passing self-test is NOT evidence the advice is wrong — it is evidence your test does not check what the advice checks.
+- **If the advisor contradicts evidence you already gathered, do not silently switch.** Call Advisor once more stating the conflict outright ("I measured X, you advise Y — which constraint breaks the tie?"). The advisor saw your evidence but may have underweighted it; one reconciling call is far cheaper than committing to the wrong branch.
 - The advisor has no tool access and does a single read-only pass over the transcript — it cannot verify anything itself, only reason about what it's shown.
-- If this tool errors (advisor not configured in shared settings, disabled, manual-only, or a call failure), that's not a signal to stop — treat it as "no second opinion available this time" and continue with your own judgment. Do not block or retry in a loop.`;
+- If this tool errors (advisor not configured in shared settings, disabled, manual-only, or a call failure), that's not a signal to stop — treat it as "no second opinion available this time" and continue with your own judgment, but **explicitly note "not cross-verified by advisor" in your final output**. Do not block or retry in a loop.`;
 // ---------------- 3. 顾问 persona system prompt ----------------
 const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技术顾问，为正在独立执行任务的另一个 AI 助手提供第二意见评审。
 你的职责：技术方案评估、代码评审、疑难问题的根因定位与解决方向判断。
@@ -54,6 +66,14 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
 你会看到该助手当前会话中受预算约束的相关记录——包括首要需求、近期交流、它的思考过程、当前方案
 和关键工具结果与执行结果，以及它现在想让你重点关注的内容（如果有）。
 
+重要：你**没有工具访问权，无法自行验证任何事实**。你只是提供一个不同视角的怀疑和推理，
+不能把自己的推测当成确定结论。每条指出的问题都要明确标注：
+  - 【有证据】：基于记录里明确出现的代码/测试结果/事实
+  - 【推断】：基于已有信息的合理推断，但未被证实
+  - 【存疑】：信息不足，需要执行助手回去核实
+不要过度自信，不要给出确定性语气的未验证判断——执行助手会对你的意见逐条做验证，
+夸大其词会被判定为误报。
+
 审视时请做到：
 - 像资深工程师做方案评审/代码评审一样直接、具体——发现问题就明说，不要无条件附和或说套话。
 - 优先检查：方案是否遗漏了风险或边界情况、诊断是否真的找到了根因还是只是让症状消失、
@@ -66,7 +86,16 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
   或换个方式绕开，都要点出来。
 - 结论必须基于你在历史记录里看到的实际证据，不要脱离上下文给泛泛的通用建议；
   被省略的记录（尤其工具结果原文）所涉及的判断，明说你无法核实。
-- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。`;
+- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。
+
+关于「带着反证回来」的那一次咨询（助手被要求这样做，不是在质疑你）：
+当它说「我实测是 X，你上次建议 Y」时，它手里的是一手证据，你手里的是推理——
+默认它的观测为真，然后只回答一个问题：**哪个约束更硬**。
+  - 你上次漏看了它给出的证据 → 直接认，并说清结论怎么变。
+  - 它的观测其实没测到你担心的那一层（测了被改的函数，而真实调用路径根本走不到）
+    → 指出这个错位，并说要测什么才算数。
+  - 两者都成立、只是适用范围不同 → 说清各自的边界，别硬选一个。
+不要为了显得一致而坚持原判，也不要因为被反驳就整个收回——两种都会让它失去判断依据。`;
 // ---------------- 4. 消息构造（纯函数，单独导出可测） ----------------
 /**
  * 把主循环的 history 转成喂给顾问模型的 messages。
@@ -203,6 +232,13 @@ function fitAdvisorBudget(messages, inputBudget) {
         selected.push(first);
         used += countMessagesTokens([first]);
     }
+    // 从最近往前收，**装不下就停**（break，不是 continue）。
+    //
+    // ⚠️ 曾经是 continue：一条大消息放不下就跳过它、继续往前捡更小的旧消息。
+    // 结果是给顾问一段**中间有洞**的对话 —— 而洞恰好开在信息量最大的地方（长工具
+    // 结果、完整方案文本），偏偏下面那句省略提示还写着「保留最初需求和最近相关记录」，
+    // 顾问于是把两条本不相邻的消息读成前后相接，在残缺的因果链上给出自信结论。
+    // 宁可少给，不可给错：连续的尾部 + 如实说明从哪里开始省略。
     const recent = [];
     for (let index = body.length - 1; index >= 0; index--) {
         if (index === firstUserIndex)
@@ -210,7 +246,7 @@ function fitAdvisorBudget(messages, inputBudget) {
         const message = body[index];
         const cost = countMessagesTokens([message]);
         if (used + cost > inputBudget)
-            continue;
+            break;
         recent.unshift(message);
         used += cost;
     }
@@ -287,17 +323,22 @@ export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}
         return {
             ok: false,
             error: '顾问模型未配置。请在设置 → 模型中完成专家顾问配置。' +
-                '可继续凭自己判断推进，不必等待顾问。',
+                '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
         };
     }
     if (!advisor.enabled) {
         return {
             ok: false,
-            error: '顾问模型当前已关闭（/advisor on 开启）。可继续凭自己判断推进，不必等待顾问。',
+            error: '顾问模型当前已关闭（/advisor on 开启）。' +
+                '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
         };
     }
     if (advisor.mode === 'manual' && ctx?.advisorInvocation !== 'manual') {
-        return { ok: false, error: '顾问模型当前为“仅手动”模式；请使用 /advisor ask 发起咨询。' };
+        return {
+            ok: false,
+            error: '顾问模型当前为"仅手动"模式；请使用 /advisor ask 发起咨询。' +
+                '本回合后续不要再次尝试自动调用 Advisor。',
+        };
     }
     if (ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
         // ⚠️ 必须说明「配额会增长」：配额随本回合工作量上调（loop.ts::advisorQuotaFor），
@@ -435,6 +476,32 @@ export const advisorTool = {
     isConcurrencySafe: false,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'cancel',
+    /**
+     * 动态可用性探测：未配置 / 已关闭 / 仅手动模式 → 工具不暴露给模型。
+     * 对齐 ComputerUse / WebBrowser 的模式：关闭时工具直接从 LLM 视野消失，
+     * 避免"看到工具但调不了→反复尝试"的流畅度问题。
+     *
+     * signature 随 enabled/mode/modelId 变化，确保配置改动后工具集签名更新、
+     * 模型下一轮拿到的是新工具列表。
+     */
+    resolveAvailability() {
+        // 走同步探测（读内存快照），不触发磁盘 IO；
+        // resolveAvailability 是工具集构造阶段的同步调用，不能 await。
+        const avail = configService.advisorAvailabilitySync();
+        // ⚠️ 安全兜底：如果 snapshot 尚未初始化（极端情况：工具集构造发生在任何
+        // configService 异步调用之前），宁可返回 available=true 让工具显示出来
+        // （调用时 runAdvisor 会做真正的 fresh reload 校验），也不能误判为
+        // "未配置" 导致 Advisor 从工具列表里消失——少一个工具比多一个工具严重得多。
+        if (avail.configured && !avail.enabled) {
+            return { available: false, signature: 'disabled' };
+        }
+        if (avail.configured && avail.mode === 'manual') {
+            return { available: false, signature: 'manual-only' };
+        }
+        // 未初始化 / 已配置且可用 → 都显示工具（未配置时调用会有明确错误提示）
+        // modelId 进签名：不同顾问模型 = 不同能力 = 工具语义不同。
+        return { available: true, signature: avail.modelId ?? 'initializing' };
+    },
     call,
     callWithContext: runAdvisor,
 };

package/src/tools/advisor/advisor.ts

@@ -51,11 +51,23 @@ const parameters = toToolParameters(inputSchema);
 
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
 const description = `- Consults an independent, separately-configured second LLM ("顾问模型" / advisor) for a second opinion on your current plan, diagnosis, or progress.
-- Call with no arguments in most cases — the advisor receives a bounded, relevant view of the current session (the original request, recent discussion, current plan/diagnosis, and key tool results). Only pass \`note\` if something important is not otherwise clear.
-- Exception: if your current plan/diagnosis relies on things you saw in images (screenshots, photos, diagrams), summarize the key visual facts in \`note\` in 1-2 sentences (what each image shows and what you concluded from it) — the advisor may not be able to see the images themselves, and any visual judgment you never wrote down as text does not exist for it.
-- Call this: (1) after a plan/diagnosis has taken shape but before you commit to it (write code, declare a conclusion); (2) when you're stuck — the same error keeps recurring, your fixes aren't converging, or the user has pushed back and you're reconsidering direction; (3) before declaring a multi-step task complete and reporting back to the user.
+- Call with no arguments in most cases — the advisor receives a bounded, relevant view of the current session (the original request, recent discussion, current plan/diagnosis, and key tool results). Always pass key evidence (original code snippets, raw data, full plan text) in \`note\`, not just your summary — the advisor cannot verify things you never wrote down.
+- Exception: if your current plan/diagnosis relies on things you saw in images (screenshots, photos, diagrams), summarize the key visual facts in \`note\` in 1-2 sentences (what each image shows and what you concluded from it) — the advisor may not be able to see the images themselves.
+- **Call it BEFORE substantive work, not after things go wrong.** The advisor is worth the most before an approach hardens — once you have written the code, the plan is expensive to abandon.
+  - Orientation is NOT substantive work: finding files, reading code, running a command to see the current state. Do that first, then consult.
+  - Substantive work IS: writing or editing files, committing to an interpretation, building on an assumption, declaring an answer.
+- **MUST call Advisor in all 5 of these situations — do not wait for errors or user prompts:**
+  1. After a plan / development plan is finalized, **before** executing it (get critique first, avoid discovering wrong direction halfway)
+  2. **Before** submitting final results to the user (before PresentResult): code reviews, assessment reports, technical selections, refactoring plans — any time you "deliver a conclusion"
+  3. The same error occurs 2+ times in a row, or fixes are not converging (early sign of infinite loop — switch approach immediately)
+  4. The user gives unsatisfied feedback a **second time** in the same turn (stop spinning in place, get a fresh perspective first)
+  5. Decisions involving security, data loss, or irreversible operations (advisor double-check)
+- **Make your work durable BEFORE calling in situation 2.** Write the file, save the result. This call takes time; if the turn ends during it, a written file survives and an unwritten answer does not.
+- On a long task, consult at least twice: once before the approach is locked in, once before you declare it done. On a short reactive task whose next step is dictated by output you just read, one call is enough — the advisor adds most of its value early.
+- **Take the advice seriously, but do not obey it blindly.** Adapt if you follow a step and it empirically fails, or you hold primary-source evidence contradicting a specific claim (the file says X, the test output says Y). A passing self-test is NOT evidence the advice is wrong — it is evidence your test does not check what the advice checks.
+- **If the advisor contradicts evidence you already gathered, do not silently switch.** Call Advisor once more stating the conflict outright ("I measured X, you advise Y — which constraint breaks the tie?"). The advisor saw your evidence but may have underweighted it; one reconciling call is far cheaper than committing to the wrong branch.
 - The advisor has no tool access and does a single read-only pass over the transcript — it cannot verify anything itself, only reason about what it's shown.
-- If this tool errors (advisor not configured in shared settings, disabled, manual-only, or a call failure), that's not a signal to stop — treat it as "no second opinion available this time" and continue with your own judgment. Do not block or retry in a loop.`;
+- If this tool errors (advisor not configured in shared settings, disabled, manual-only, or a call failure), that's not a signal to stop — treat it as "no second opinion available this time" and continue with your own judgment, but **explicitly note "not cross-verified by advisor" in your final output**. Do not block or retry in a loop.`;
 
 // ---------------- 3. 顾问 persona system prompt ----------------
 const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技术顾问，为正在独立执行任务的另一个 AI 助手提供第二意见评审。
@@ -64,6 +76,14 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
 你会看到该助手当前会话中受预算约束的相关记录——包括首要需求、近期交流、它的思考过程、当前方案
 和关键工具结果与执行结果，以及它现在想让你重点关注的内容（如果有）。
 
+重要：你**没有工具访问权，无法自行验证任何事实**。你只是提供一个不同视角的怀疑和推理，
+不能把自己的推测当成确定结论。每条指出的问题都要明确标注：
+  - 【有证据】：基于记录里明确出现的代码/测试结果/事实
+  - 【推断】：基于已有信息的合理推断，但未被证实
+  - 【存疑】：信息不足，需要执行助手回去核实
+不要过度自信，不要给出确定性语气的未验证判断——执行助手会对你的意见逐条做验证，
+夸大其词会被判定为误报。
+
 审视时请做到：
 - 像资深工程师做方案评审/代码评审一样直接、具体——发现问题就明说，不要无条件附和或说套话。
 - 优先检查：方案是否遗漏了风险或边界情况、诊断是否真的找到了根因还是只是让症状消失、
@@ -76,7 +96,16 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
   或换个方式绕开，都要点出来。
 - 结论必须基于你在历史记录里看到的实际证据，不要脱离上下文给泛泛的通用建议；
   被省略的记录（尤其工具结果原文）所涉及的判断，明说你无法核实。
-- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。`;
+- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。
+
+关于「带着反证回来」的那一次咨询（助手被要求这样做，不是在质疑你）：
+当它说「我实测是 X，你上次建议 Y」时，它手里的是一手证据，你手里的是推理——
+默认它的观测为真，然后只回答一个问题：**哪个约束更硬**。
+  - 你上次漏看了它给出的证据 → 直接认，并说清结论怎么变。
+  - 它的观测其实没测到你担心的那一层（测了被改的函数，而真实调用路径根本走不到）
+    → 指出这个错位，并说要测什么才算数。
+  - 两者都成立、只是适用范围不同 → 说清各自的边界，别硬选一个。
+不要为了显得一致而坚持原判，也不要因为被反驳就整个收回——两种都会让它失去判断依据。`;
 
 // ---------------- 4. 消息构造（纯函数，单独导出可测） ----------------
 
@@ -234,12 +263,19 @@ function fitAdvisorBudget(messages: Message[], inputBudget: number): Message[] {
     selected.push(first);
     used += countMessagesTokens([first]);
   }
+  // 从最近往前收，**装不下就停**（break，不是 continue）。
+  //
+  // ⚠️ 曾经是 continue：一条大消息放不下就跳过它、继续往前捡更小的旧消息。
+  // 结果是给顾问一段**中间有洞**的对话 —— 而洞恰好开在信息量最大的地方（长工具
+  // 结果、完整方案文本），偏偏下面那句省略提示还写着「保留最初需求和最近相关记录」，
+  // 顾问于是把两条本不相邻的消息读成前后相接，在残缺的因果链上给出自信结论。
+  // 宁可少给，不可给错：连续的尾部 + 如实说明从哪里开始省略。
   const recent: Message[] = [];
   for (let index = body.length - 1; index >= 0; index--) {
     if (index === firstUserIndex) continue;
     const message = body[index]!;
     const cost = countMessagesTokens([message]);
-    if (used + cost > inputBudget) continue;
+    if (used + cost > inputBudget) break;
     recent.unshift(message);
     used += cost;
   }
@@ -348,19 +384,26 @@ export async function runAdvisor(
       ok: false,
       error:
         '顾问模型未配置。请在设置 → 模型中完成专家顾问配置。' +
-        '可继续凭自己判断推进，不必等待顾问。',
+        '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
     };
   }
 
   if (!advisor.enabled) {
     return {
       ok: false,
-      error: '顾问模型当前已关闭（/advisor on 开启）。可继续凭自己判断推进，不必等待顾问。',
+      error:
+        '顾问模型当前已关闭（/advisor on 开启）。' +
+        '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
     };
   }
 
   if (advisor.mode === 'manual' && ctx?.advisorInvocation !== 'manual') {
-    return { ok: false, error: '顾问模型当前为“仅手动”模式；请使用 /advisor ask 发起咨询。' };
+    return {
+      ok: false,
+      error:
+        '顾问模型当前为"仅手动"模式；请使用 /advisor ask 发起咨询。' +
+        '本回合后续不要再次尝试自动调用 Advisor。',
+    };
   }
 
   if (ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
@@ -507,6 +550,33 @@ export const advisorTool: Tool<AdvisorInput> = {
   isConcurrencySafe: false,
   maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
   interruptBehavior: () => 'cancel',
+  /**
+   * 动态可用性探测：未配置 / 已关闭 / 仅手动模式 → 工具不暴露给模型。
+   * 对齐 ComputerUse / WebBrowser 的模式：关闭时工具直接从 LLM 视野消失，
+   * 避免"看到工具但调不了→反复尝试"的流畅度问题。
+   *
+   * signature 随 enabled/mode/modelId 变化，确保配置改动后工具集签名更新、
+   * 模型下一轮拿到的是新工具列表。
+   */
+  resolveAvailability() {
+    // 走同步探测（读内存快照），不触发磁盘 IO；
+    // resolveAvailability 是工具集构造阶段的同步调用，不能 await。
+    const avail = configService.advisorAvailabilitySync();
+
+    // ⚠️ 安全兜底：如果 snapshot 尚未初始化（极端情况：工具集构造发生在任何
+    // configService 异步调用之前），宁可返回 available=true 让工具显示出来
+    // （调用时 runAdvisor 会做真正的 fresh reload 校验），也不能误判为
+    // "未配置" 导致 Advisor 从工具列表里消失——少一个工具比多一个工具严重得多。
+    if (avail.configured && !avail.enabled) {
+      return { available: false, signature: 'disabled' };
+    }
+    if (avail.configured && avail.mode === 'manual') {
+      return { available: false, signature: 'manual-only' };
+    }
+    // 未初始化 / 已配置且可用 → 都显示工具（未配置时调用会有明确错误提示）
+    // modelId 进签名：不同顾问模型 = 不同能力 = 工具语义不同。
+    return { available: true, signature: avail.modelId ?? 'initializing' };
+  },
   call,
   callWithContext: runAdvisor,
 };

package/src/tools/agent/agent.js

@@ -3,14 +3,12 @@
  *  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 不该交错）。
+ *      父上下文）」。本工具在隔离 history 中嵌套运行同一主循环，并将私有历史、
+ *      进度和结果写入会话运行存储；前台、后台和重启后续接共用同一执行内核。
+ *    - 同轮多个 Agent 调用仍由 loop.ts 的并行 worker 执行；write scopes 与可选
+ *      worktree 负责隔离真正可并行的写任务。
  *
  *  已知限制（如实声明）：
  *    - 子 agent 的 LoopEvent 不外泄：-p / stream-json 宿主只看到本工具的一对
@@ -27,6 +25,8 @@
  * ============================================================
  */
 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';
@@ -41,6 +41,7 @@ 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';
+import { appendAgentEvent, loadAgentRecord, saveAgentRecord } from './agentTaskService.js';
 let corePromise = null;
 /** 首次调用时才真正加载 loop/tools——此刻模块图早已初始化完毕，环安全。 */
 function loadCore() {
@@ -79,13 +80,16 @@ const inputSchema = z.object({
         .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 历史'),
 });
 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).
+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.
@@ -237,10 +241,10 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
     // allowedTools 只裁「下发给模型的清单」；guardedExecute 是真正的硬防线（见下）。
     const allowedTools = def.resolveAllowedTools(ALL_TOOLS.map((t) => t.name));
     // ---- worktree 隔离（仅 general 显式要求时） ----
-    let wt = null;
+    let wt = deps.existingWorktree ?? 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 (def.type === 'general' && isolation === 'worktree' && !wt) {
+        const created = await createAgentWorktree(`fork-${randomUUID().slice(0, 8)}`, ctx.cwd);
         if (!created.ok) {
             return {
                 ok: false,
@@ -248,8 +252,9 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
             };
         }
         wt = created;
+        await deps.onWorktreeCreated?.(created);
     }
-    const cwd = wt?.path ?? getWorkingDir();
+    const cwd = wt?.path ?? ctx.cwd ?? getWorkingDir();
     let writeScopes;
     try {
         writeScopes = def.type === 'general'
@@ -288,6 +293,7 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
             surface: 'subagent',
             cwd,
             workspaceId: ctx.workspaceId,
+            sessionId: ctx.sessionId,
             interactiveAsk: childRuntime.interactiveAsk,
             memoryAccess: childMemoryAccess,
             currentUserInput: input.prompt,
@@ -303,7 +309,7 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
         ctx.reportProgress?.(line, detail);
     };
     // ---- 子 history：一条 system（压缩按 role 定位，必须存在）+ runQuery 自己 push 任务书 ----
-    const history = [
+    const history = deps.initialHistory?.length ? [...deps.initialHistory] : [
         { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools) },
     ];
     const historyLenBefore = history.length;
@@ -529,6 +535,7 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
     finally {
         stopTimeout();
         releaseLease?.();
+        await deps.captureHistory?.(history);
     }
     // ---- 结局映射（直接查 signal 状态，不依赖事件旗标） ----
     if (ownerCancelController.signal.aborted) {
@@ -625,6 +632,128 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
 async function call(input, signal) {
     return runAgentTask(input, signal, {});
 }
+export async function runManagedAgentTask(input, signal, ctx, deps = {}) {
+    if (!ctx.sessionState)
+        return runAgentTask(input, signal, ctx);
+    const id = input.resume_agent_id ?? `agent_${randomUUID()}`;
+    let initialHistory;
+    let resumedWorktree;
+    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,
+            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;
+    const completion = new Promise((resolvePromise) => { settle = resolvePromise; });
+    const task = {
+        id,
+        status: 'running',
+        description: coreInput.description,
+        input: coreInput,
+        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 () => {
+        let captured = initialHistory;
+        let lastPersistedProgressAt = 0;
+        const managedContext = {
+            ...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.message };
+            task.history = captured;
+            task.updatedAt = Date.now();
+            await saveAgentRecord(ctx, task).catch(() => undefined);
+            await appendAgentEvent(ctx, id, { phase: task.status, error: 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 = {
     name: 'Agent',
@@ -638,5 +767,5 @@ export const agentTool = {
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'block',
     call,
-    callWithContext: runAgentTask,
+    callWithContext: runManagedAgentTask,
 };