minimal-agent 0.12.0 → 0.14.0

package/src/tools/advisor/advisor.ts

@@ -27,10 +27,17 @@ import { z } from 'zod';
 
 import { configService } from '../../config/configService.js';
 import { CONFIG_LIMITS, normalizeLimited } from '../../config/numericLimits.js';
+import { DEFAULT_ADVISOR_CONFIG } from '../../config/configDefaults.js';
 import { countMessagesTokens } from '../../context/tokenCounter.js';
 import { chat } from '../../llm/client.js';
 import { derivePromptCacheContext } from '../../llm/promptCache.js';
-import type { Message, Tool, ToolCallContext, ToolResult } from '../../types.js';
+import type {
+  AdvisorContextPacket,
+  Message,
+  Tool,
+  ToolCallContext,
+  ToolResult,
+} from '../../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 
@@ -38,10 +45,14 @@ import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 const inputSchema = z.object({
   note: z
     .string()
-    .max(2000, 'note 太长（>2000 字）')
+    // 上限只做护栏，不做实用约束：note 是顾问唯一能看到的「模型主动强调的证据」，
+    // 卡太低（曾经 2000 字符）会让完整方案+关键代码原文根本塞不进去。真正的预算
+    // 闸门在 buildAdvisorMessages -> fitAdvisorBudget（inputTokenBudget 配置 +
+    // 顾问 contextWindow 推导），note 超预算只会挤掉历史消息，不会炸请求。
+    .max(100_000, 'note 太长（>100000 字符）')
     .optional()
     .describe(
-      '可选。大多数情况下不需要填——你此前说过的方案/诊断已经在会话历史里，顾问会自动看到。' +
+      '可选。大多数情况下不需要填--你此前说过的方案/诊断已经在会话历史里，顾问会自动看到。' +
         '只有需要额外强调、历史里没体现的点时才填一句话。',
     ),
 });
@@ -50,12 +61,10 @@ type AdvisorInput = z.infer<typeof inputSchema>;
 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.
-- 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.`;
+const description = `Consult an independently configured, read-only advisor model for a second opinion.
+The advisor receives a bounded view of the current session. Usually omit note; use it only for decisive evidence or visual facts that are absent or easy to miss in history.
+The result includes a full consultationId. After a successful automatic consultation, record the main Agent's evidence-based accept/partial/reject judgment with AdvisorDecision.
+The advisor is neither a fact source nor an authority. If it is unavailable or fails, follow the returned degradation guidance and do not retry in a loop.`;
 
 // ---------------- 3. 顾问 persona system prompt ----------------
 const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技术顾问，为正在独立执行任务的另一个 AI 助手提供第二意见评审。
@@ -64,6 +73,14 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
 你会看到该助手当前会话中受预算约束的相关记录——包括首要需求、近期交流、它的思考过程、当前方案
 和关键工具结果与执行结果，以及它现在想让你重点关注的内容（如果有）。
 
+重要：你**没有工具访问权，无法自行验证任何事实**。你只是提供一个不同视角的怀疑和推理，
+不能把自己的推测当成确定结论。每条指出的问题都要明确标注：
+  - 【有证据】：基于记录里明确出现的代码/测试结果/事实
+  - 【推断】：基于已有信息的合理推断，但未被证实
+  - 【存疑】：信息不足，需要执行助手回去核实
+不要过度自信，不要给出确定性语气的未验证判断——执行助手会对你的意见逐条做验证，
+夸大其词会被判定为误报。
+
 审视时请做到：
 - 像资深工程师做方案评审/代码评审一样直接、具体——发现问题就明说，不要无条件附和或说套话。
 - 优先检查：方案是否遗漏了风险或边界情况、诊断是否真的找到了根因还是只是让症状消失、
@@ -76,7 +93,16 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
   或换个方式绕开，都要点出来。
 - 结论必须基于你在历史记录里看到的实际证据，不要脱离上下文给泛泛的通用建议；
   被省略的记录（尤其工具结果原文）所涉及的判断，明说你无法核实。
-- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。`;
+- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。
+
+关于「带着反证回来」的那一次咨询（助手被要求这样做，不是在质疑你）：
+当它说「我实测是 X，你上次建议 Y」时，它手里的是一手证据，你手里的是推理——
+默认它的观测为真，然后只回答一个问题：**哪个约束更硬**。
+  - 你上次漏看了它给出的证据 → 直接认，并说清结论怎么变。
+  - 它的观测其实没测到你担心的那一层（测了被改的函数，而真实调用路径根本走不到）
+    → 指出这个错位，并说要测什么才算数。
+  - 两者都成立、只是适用范围不同 → 说清各自的边界，别硬选一个。
+不要为了显得一致而坚持原判，也不要因为被反驳就整个收回——两种都会让它失去判断依据。`;
 
 // ---------------- 4. 消息构造（纯函数，单独导出可测） ----------------
 
@@ -88,8 +114,20 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
  */
 const MAX_TOOL_RESULT_CHARS = 12_000;
 
+/**
+ * 工具调用参数与思维链的截断上限——与 `fitAdvisorBudget` 的预算裁剪是两回事：
+ * 那个只在总量超预算时才生效、按消息整条丢弃；这两个是每条消息内部无条件应用的
+ * 字段级上限，不看当前预算是否宽裕。思维链截得比正文更狠：重思考模型的
+ * reasoning 常比 content 长几倍，不设限会把预算吃光、挤掉更该保留的工具结果原文。
+ * 未发现过当前取值导致顾问漏判的实例，因此只命名、不改值——真出现具体案例
+ * 再调，不做没有证据支撑的预防性放宽。
+ */
+const ADVISOR_TOOL_ARGS_TRUNCATE_CHARS = 2_000;
+const ADVISOR_REASONING_TRUNCATE_CHARS = 2_000;
+
 /** 归一化后的工具结果前缀；裁剪统计要靠它反查，两处必须共用同一常量。 */
 const TOOL_RESULT_PREFIX = '[工具结果 ';
+const CONTEXT_PACKET_PREFIX = '[Advisor 结构化上下文包]';
 
 function truncateMiddle(value: string, limit = MAX_TOOL_RESULT_CHARS): string {
   if (value.length <= limit) return value;
@@ -192,19 +230,17 @@ function normalizeAdvisorMessage(
   }
   if (message.role === 'assistant') {
     const calls = message.tool_calls?.map((call) =>
-      `[调用工具 ${call.function.name}] ${truncateMiddle(call.function.arguments, 2000)}`,
+      `[调用工具 ${call.function.name}] ${truncateMiddle(call.function.arguments, ADVISOR_TOOL_ARGS_TRUNCATE_CHARS)}`,
     ).join('\n');
     // 思维链一并送给顾问：评审「方案对不对」很大程度上要看**它是怎么想到这个方案的**——
     // 推理里的跳跃（把推断当已验证、跳过一个没排除的可能）在最终结论文本里往往看不出来。
-    // 截断比正文更狠（2000）：重思考模型的 reasoning 常比 content 长几倍，不设限会把
-    // 预算吃光、反而挤掉更该保留的工具结果原文。
     // reasoning_details（结构化数组）不传：结构因 provider 而异，既无法可靠脱敏也无法
     // 稳定转成文本，传过去只会变成噪声。
     const thinking = typeof message.reasoning_content === 'string' && message.reasoning_content.length > 0
       ? message.reasoning_content
       : (typeof message.reasoning === 'string' ? message.reasoning : '');
     const thinkingLine = thinking.length > 0
-      ? `[思考过程]\n${truncateMiddle(thinking, 2000)}`
+      ? `[思考过程]\n${truncateMiddle(thinking, ADVISOR_REASONING_TRUNCATE_CHARS)}`
       : '';
     return {
       role: 'assistant',
@@ -226,20 +262,33 @@ function fitAdvisorBudget(messages: Message[], inputBudget: number): Message[] {
   const system = messages[0]!;
   const closing = messages[messages.length - 1]!;
   const body = messages.slice(1, -1);
-  const firstUserIndex = body.findIndex((message) => message.role === 'user');
+  const packetIndex = body.findIndex((message) =>
+    message.role === 'user'
+    && typeof message.content === 'string'
+    && message.content.startsWith(CONTEXT_PACKET_PREFIX));
+  const firstUserIndex = body.findIndex((message, index) =>
+    index !== packetIndex && message.role === 'user');
   const selected: Message[] = [];
   let used = countMessagesTokens([system, closing]);
-  if (firstUserIndex >= 0) {
-    const first = body[firstUserIndex]!;
-    selected.push(first);
-    used += countMessagesTokens([first]);
+  for (const index of [packetIndex, firstUserIndex]) {
+    if (index < 0) continue;
+    const pinned = body[index]!;
+    selected.push(pinned);
+    used += countMessagesTokens([pinned]);
   }
+  // 从最近往前收，**装不下就停**（break，不是 continue）。
+  //
+  // ⚠️ 曾经是 continue：一条大消息放不下就跳过它、继续往前捡更小的旧消息。
+  // 结果是给顾问一段**中间有洞**的对话 —— 而洞恰好开在信息量最大的地方（长工具
+  // 结果、完整方案文本），偏偏下面那句省略提示还写着「保留最初需求和最近相关记录」，
+  // 顾问于是把两条本不相邻的消息读成前后相接，在残缺的因果链上给出自信结论。
+  // 宁可少给，不可给错：连续的尾部 + 如实说明从哪里开始省略。
   const recent: Message[] = [];
   for (let index = body.length - 1; index >= 0; index--) {
-    if (index === firstUserIndex) continue;
+    if (index === firstUserIndex || index === packetIndex) continue;
     const message = body[index]!;
     const cost = countMessagesTokens([message]);
-    if (used + cost > inputBudget) continue;
+    if (used + cost > inputBudget) break;
     recent.unshift(message);
     used += cost;
   }
@@ -274,6 +323,7 @@ export function buildAdvisorMessages(
     contextWindow?: number;
     maxTokens?: number;
     inputTokenBudget?: number;
+    contextPacket?: AdvisorContextPacket;
   } = {},
 ): Message[] {
   const imageBudget: AdvisorImageBudget = { count: 0, encodedBytes: 0 };
@@ -296,13 +346,19 @@ export function buildAdvisorMessages(
 
   const messages: Message[] = [
     { role: 'system', content: ADVISOR_SYSTEM_PROMPT },
+    ...(options.contextPacket
+      ? [{
+          role: 'user' as const,
+          content: `${CONTEXT_PACKET_PREFIX}\n${JSON.stringify(options.contextPacket, null, 2)}`,
+        }]
+      : []),
     ...nonSystem,
     { role: 'user', content: closing },
   ];
   const contextWindow = options.contextWindow ?? 128_000;
   const maxTokens = options.maxTokens ?? 4096;
   const configuredBudget = normalizeLimited(
-    options.inputTokenBudget, CONFIG_LIMITS.advisorInputTokenBudget, 128_000);
+    options.inputTokenBudget, CONFIG_LIMITS.advisorInputTokenBudget, DEFAULT_ADVISOR_CONFIG.inputTokenBudget);
   const providerBudget = Math.max(CONFIG_LIMITS.advisorInputTokenBudget.min, contextWindow - maxTokens - 4096);
   const inputBudget = Math.min(configuredBudget, providerBudget);
   return fitAdvisorBudget(messages, inputBudget);
@@ -342,39 +398,73 @@ export async function runAdvisor(
   chatFn: typeof chat = chat,
   runtime: { timeoutMs?: number } = {},
 ): Promise<ToolResult> {
+  const consultation = ctx?.advisorInvocation === 'agent'
+    ? ctx.advisorRuntime?.beginConsultation()
+    : undefined;
+  const finish = (result: ToolResult): ToolResult => {
+    if (!consultation || !ctx?.advisorRuntime) return result;
+    const metadata = ctx.advisorRuntime.finishConsultation(consultation, result.ok);
+    return {
+      ...result,
+      ...(result.ok
+        ? {
+            content: `consultationId: ${metadata.consultationId}\n调用 AdvisorDecision 时必须原样使用上面的完整 consultationId。\n\n${result.content}`,
+          }
+        : {}),
+      metadata,
+    };
+  };
   const advisor = await configService.advisor();
   if (!advisor) {
-    return {
+    return finish({
       ok: false,
       error:
         '顾问模型未配置。请在设置 → 模型中完成专家顾问配置。' +
-        '可继续凭自己判断推进，不必等待顾问。',
-    };
+        '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
+    });
   }
 
   if (!advisor.enabled) {
-    return {
+    return finish({
       ok: false,
-      error: '顾问模型当前已关闭（/advisor on 开启）。可继续凭自己判断推进，不必等待顾问。',
-    };
+      error:
+        '顾问模型当前已关闭（/advisor on 开启）。' +
+        '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
+    });
   }
 
   if (advisor.mode === 'manual' && ctx?.advisorInvocation !== 'manual') {
-    return { ok: false, error: '顾问模型当前为“仅手动”模式；请使用 /advisor ask 发起咨询。' };
+    return finish({
+      ok: false,
+      error:
+        '顾问模型当前为"仅手动"模式；请使用 /advisor ask 发起咨询。' +
+        '本回合后续不要再次尝试自动调用 Advisor。',
+    });
   }
 
-  if (ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
+  // 复核豁免：有一个已成功、还没被 AdvisorDecision 结清的咨询时，这次调用是对它
+  // 的复核而不是一次新检查点的咨询——工具说明书要求"顾问意见与证据冲突时再问一次"，
+  // 若复核也照常计费/受配额拦截，短任务（配额恒为 1）会在第二次调用直接撞墙，
+  // 而配额耗尽的处理是把这次咨询标记失败并**顺带结清 #pending 指向的检查点**——
+  // 模型想认真复核，反而因为差一点配额把本该把关的高风险检查点悄悄放行了。
+  // 豁免只覆盖第一次复核：协调器按 checkpoint 记录成功咨询次数，完成一次复核后
+  // canReconcileConsultation 会变为 false，后续调用重新受正常配额约束。
+  const isReconcile = ctx?.advisorInvocation === 'agent'
+    && Boolean(ctx.advisorRuntime?.pendingConsultationId)
+    && ctx.advisorRuntime?.canReconcileConsultation === true;
+
+  if (!isReconcile && ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
     // ⚠️ 必须说明「配额会增长」：配额随本回合工作量上调（loop.ts::advisorQuotaFor），
     // 若这里只说「已达上限」，模型会当成本回合的硬上限而不再尝试 —— 那样长回合里
     // 「批次做完再复核一次」的配额永远不会被用到，增长机制等于没做。
-    return {
+    return finish({
       ok: false,
       error:
         `本回合顾问咨询配额暂时用完（当前 ${ctx.advisorCalls.max} 次）。` +
         '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。',
-    };
+    });
   }
-  if (ctx?.advisorCalls) ctx.advisorCalls.used++;
+  if (!isReconcile && ctx?.advisorCalls) ctx.advisorCalls.used++;
 
   const provider = advisor.provider;
   const snapshot = await configService.getSnapshot();
@@ -394,6 +484,9 @@ export async function runAdvisor(
     contextWindow: provider.contextWindow,
     maxTokens: provider.maxTokens,
     inputTokenBudget: advisor.inputTokenBudget,
+    ...(ctx?.advisorRuntime
+      ? { contextPacket: ctx.advisorRuntime.contextPacket(input.note) }
+      : {}),
   });
 
   // Advisor 是可降级的第二意见：使用独立、可配置的总时限，不影响主模型的流式时限。
@@ -457,23 +550,26 @@ export async function runAdvisor(
           contextWindow: provider.contextWindow,
           maxTokens: provider.maxTokens,
           inputTokenBudget: advisor.inputTokenBudget,
+          ...(ctx?.advisorRuntime
+            ? { contextPacket: ctx.advisorRuntime.contextPacket(input.note) }
+            : {}),
         }),
       );
       degradedWithoutImages = true;
     }
   } catch (e) {
     if (timeoutController.signal.aborted && !signal?.aborted) {
-      return {
+      return finish({
         ok: false,
         error:
           `顾问模型响应超过 ${Math.round(timeoutMs / 1000)}s 未完成，已跳过。` +
           '可继续凭自己判断推进，不必等待顾问。',
-      };
+      });
     }
-    return {
+    return finish({
       ok: false,
       error: `${classifyAdvisorError(e as Error)} 可继续凭自己判断推进，不必等待顾问。`,
-    };
+    });
   } finally {
     clearTimeout(timer);
   }
@@ -489,7 +585,7 @@ export async function runAdvisor(
       `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
   }
 
-  return { ok: true, content };
+  return finish({ ok: true, content });
 }
 
 // 无宿主上下文的调用视为用户手动咨询；生产主循环使用 callWithContext。
@@ -507,6 +603,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/advisor/advisorDecision.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { configService } from '../../config/configService.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+const inputSchema = z
+    .object({
+    consultationId: z
+        .string()
+        .min(1)
+        .describe('Advisor 结果元数据中的 consultationId'),
+    decision: z.enum(['accept', 'partial', 'reject']),
+    rationale: z
+        .string()
+        .min(8)
+        .max(20_000)
+        .describe('主 Agent 基于代码、测试和用户约束作出的判断依据'),
+    acceptedPoints: z.array(z.string().min(1).max(4_000)).max(20).optional(),
+    rejectedPoints: z.array(z.string().min(1).max(4_000)).max(20).optional(),
+    verificationPlan: z.array(z.string().min(1).max(4_000)).max(20).optional(),
+})
+    .superRefine((value, ctx) => {
+    if (value.decision === 'partial' &&
+        (!value.acceptedPoints?.length || !value.rejectedPoints?.length)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['decision'],
+            message: 'partial 必须同时列出 acceptedPoints 和 rejectedPoints',
+        });
+    }
+    if (value.decision === 'reject' && !value.rejectedPoints?.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['rejectedPoints'],
+            message: 'reject 必须列出被拒绝的顾问意见',
+        });
+    }
+});
+async function callWithContext(input, _signal, context) {
+    if (!context.advisorRuntime) {
+        return { ok: false, error: '当前运行没有待处理的 Advisor 协调器状态。' };
+    }
+    return context.advisorRuntime.recordDecision(input);
+}
+export const advisorDecisionTool = {
+    name: 'AdvisorDecision',
+    description: "Records the main Agent's evidence-based decision after a successful Advisor consultation. " +
+        'Call it before resuming a deferred write, irreversible action, or final delivery. ' +
+        'The Advisor is a second opinion, not an authority: choose accept, partial, or reject based on primary evidence. ' +
+        'For partial/reject, explicitly identify rejected points and explain the code/test/user-constraint evidence.',
+    inputSchema,
+    parameters: toToolParameters(inputSchema),
+    isReadOnly: true,
+    isConcurrencySafe: false,
+    interruptBehavior: () => 'cancel',
+    resolveAvailability() {
+        const avail = configService.advisorAvailabilitySync();
+        if (avail.configured && (!avail.enabled || avail.mode === 'manual')) {
+            return {
+                available: false,
+                signature: avail.enabled ? 'manual-only' : 'disabled',
+            };
+        }
+        return { available: true, signature: avail.modelId ?? 'initializing' };
+    },
+    async call() {
+        return {
+            ok: false,
+            error: 'AdvisorDecision 只能在主 Agent 会话的 Advisor 咨询后调用。',
+        };
+    },
+    callWithContext,
+};

package/src/tools/advisor/advisorDecision.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+
+import { configService } from '../../config/configService.js';
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+
+const inputSchema = z
+  .object({
+    consultationId: z
+      .string()
+      .min(1)
+      .describe('Advisor 结果元数据中的 consultationId'),
+    decision: z.enum(['accept', 'partial', 'reject']),
+    rationale: z
+      .string()
+      .min(8)
+      .max(20_000)
+      .describe('主 Agent 基于代码、测试和用户约束作出的判断依据'),
+    acceptedPoints: z.array(z.string().min(1).max(4_000)).max(20).optional(),
+    rejectedPoints: z.array(z.string().min(1).max(4_000)).max(20).optional(),
+    verificationPlan: z.array(z.string().min(1).max(4_000)).max(20).optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (
+      value.decision === 'partial' &&
+      (!value.acceptedPoints?.length || !value.rejectedPoints?.length)
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['decision'],
+        message: 'partial 必须同时列出 acceptedPoints 和 rejectedPoints',
+      });
+    }
+    if (value.decision === 'reject' && !value.rejectedPoints?.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['rejectedPoints'],
+        message: 'reject 必须列出被拒绝的顾问意见',
+      });
+    }
+  });
+
+type AdvisorDecisionInput = z.infer<typeof inputSchema>;
+
+async function callWithContext(
+  input: AdvisorDecisionInput,
+  _signal: AbortSignal | undefined,
+  context: ToolCallContext,
+): Promise<ToolResult> {
+  if (!context.advisorRuntime) {
+    return { ok: false, error: '当前运行没有待处理的 Advisor 协调器状态。' };
+  }
+  return context.advisorRuntime.recordDecision(input);
+}
+
+export const advisorDecisionTool: Tool<AdvisorDecisionInput> = {
+  name: 'AdvisorDecision',
+  description:
+    "Records the main Agent's evidence-based decision after a successful Advisor consultation. " +
+    'Call it before resuming a deferred write, irreversible action, or final delivery. ' +
+    'The Advisor is a second opinion, not an authority: choose accept, partial, or reject based on primary evidence. ' +
+    'For partial/reject, explicitly identify rejected points and explain the code/test/user-constraint evidence.',
+  inputSchema,
+  parameters: toToolParameters(inputSchema),
+  isReadOnly: true,
+  isConcurrencySafe: false,
+  interruptBehavior: () => 'cancel',
+  resolveAvailability() {
+    const avail = configService.advisorAvailabilitySync();
+    if (avail.configured && (!avail.enabled || avail.mode === 'manual')) {
+      return {
+        available: false,
+        signature: avail.enabled ? 'manual-only' : 'disabled',
+      };
+    }
+    return { available: true, signature: avail.modelId ?? 'initializing' };
+  },
+  async call(): Promise<ToolResult> {
+    return {
+      ok: false,
+      error: 'AdvisorDecision 只能在主 Agent 会话的 Advisor 咨询后调用。',
+    };
+  },
+  callWithContext,
+};

package/src/tools/agent/agent.js

@@ -41,7 +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';
+import { appendAgentEvent, attachAgentHistory, loadAgentRecord, saveAgentRecord } from './agentTaskService.js';
 let corePromise = null;
 /** 首次调用时才真正加载 loop/tools——此刻模块图早已初始化完毕，环安全。 */
 function loadCore() {
@@ -234,7 +234,10 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
         ctx.agentCalls.used++;
     const { runQuery, ALL_TOOLS, executeTool } = await loadCore();
     const def = resolveAgentType(input.agent_type);
-    // 轮数上限：AGENT_TOOL_MAX_TURNS 可统一覆盖两种类型（默认 explore 50 / general 100）。
+    // 轮数上限：AGENT_TOOL_MAX_TURNS 可统一覆盖两种类型。默认值的唯一真值在
+    // config/configDefaults.ts::DEFAULT_SUBAGENTS_CONFIG（现为 explore 200 / general 100，
+    // 那里写了「只读的给宽、能写的给窄」的理由）。这条注释以前写着「explore 50」，
+    // 而代码早已是 200 —— 注释里复述数字必然漂移，所以现在只留指针。
     const maxTurns = positiveInt(process.env.AGENT_TOOL_MAX_TURNS)
         ?? (def.type === 'explore' ? ctx.subagentConfig?.exploreMaxTurns : ctx.subagentConfig?.generalMaxTurns)
         ?? def.maxTurns;
@@ -312,6 +315,7 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
     const history = deps.initialHistory?.length ? [...deps.initialHistory] : [
         { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools) },
     ];
+    deps.onHistoryReady?.(history);
     const historyLenBefore = history.length;
     const maxConcurrent = positiveInt(process.env.AGENT_TOOL_MAX_CONCURRENT) ?? ctx.subagentConfig?.maxConcurrent ?? 3;
     let releaseLease = null;
@@ -407,8 +411,8 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
         }
         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' && !wt && ['Bash', 'ApplyPatch'].includes(name) && writeScopes[0] !== rootScope[0]) {
+            return { ok: false, error: `声明了局部 write_scopes 时禁止 ${name}：无法可靠证明一次调用只写入批准范围。请改用单文件工具或使用整个工作目录范围。` };
         }
         if (def.type === 'general' && rawPath) {
             if (isAbsolute(rawPath))
@@ -427,7 +431,14 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
                 changedFiles.add(relative(cwd, resolve(cwd, rawPath)).split(sep).join('/'));
             }
         }
-        return baseExecute(name, args, s, c);
+        const result = await baseExecute(name, args, s, c);
+        if (result.metadata?.kind === 'file_activity') {
+            for (const file of result.metadata.files) {
+                if (['created', 'modified', 'generated', 'deleted'].includes(file.activity))
+                    changedFiles.add(file.relativePath);
+            }
+        }
+        return result;
     };
     // ---- 事件消费：子 LoopEvent 一律不外泄，折算成统计 + 步内进度 ----
     let turns = 0;
@@ -672,6 +683,7 @@ export async function runManagedAgentTask(input, signal, ctx, deps = {}) {
         abort,
         completion,
         events: new EventEmitter(),
+        inbox: [],
     };
     ctx.sessionState.agentTasks.tasks.set(id, task);
     await saveAgentRecord(ctx, task);
@@ -703,6 +715,7 @@ export async function runManagedAgentTask(input, signal, ctx, deps = {}) {
                     await saveAgentRecord(ctx, task);
                 },
                 captureHistory: (history) => { captured = [...history]; },
+                onHistoryReady: (history) => attachAgentHistory(task, history),
             });
             task.result = result;
             task.history = captured;