minimal-agent 0.13.0 → 0.15.0

package/src/tools/advisor/advisor.ts

@@ -4,7 +4,7 @@
  * ------------------------------------------------------------
  *  独立配置的第二个 LLM，供主循环的模型在关键判断点（方案/诊断成型后动手写改之前、
  *  受阻或要改方向时、收尾汇报之前）主动调用，拿到一个不同模型的第二意见。
- *  时机规则的真身在 `prompts/promptAssembly.ts` 的 Advisor 工具规则 + 本文件的
+ *  时机规则的真身在 `prompts/policyRegistry.ts` 的 `capability.advisor` 能力块 + 本文件的
  *  `description`；配额曲线在 `loop.ts::advisorQuotaFor`。
  *
  *  设计要点（吸收自 Claude Code 官方 /advisor 的架构，但按 minimal-agent
@@ -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,24 +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). 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, but **explicitly note "not cross-verified by advisor" in your final output**. 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 助手提供第二意见评审。
@@ -117,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;
@@ -221,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',
@@ -255,13 +262,19 @@ 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）。
   //
@@ -272,7 +285,7 @@ function fitAdvisorBudget(messages: Message[], inputBudget: number): Message[] {
   // 宁可少给，不可给错：连续的尾部 + 如实说明从哪里开始省略。
   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) break;
@@ -310,6 +323,7 @@ export function buildAdvisorMessages(
     contextWindow?: number;
     maxTokens?: number;
     inputTokenBudget?: number;
+    contextPacket?: AdvisorContextPacket;
   } = {},
 ): Message[] {
   const imageBudget: AdvisorImageBudget = { count: 0, encodedBytes: 0 };
@@ -332,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);
@@ -378,46 +398,93 @@ 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 开启）。' +
         '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
-    };
+    });
   }
 
   if (advisor.mode === 'manual' && ctx?.advisorInvocation !== 'manual') {
-    return {
+    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;
+
+  // 检查点强制咨询 vs 自愿咨询分池计费：宿主主动拦下模型、强制它咨询的这一次
+  // 调用（hasActiveGate === true）走独立的 mandatoryUsed/mandatoryMax 池，
+  // 永远不会被自愿/复核性质的咨询挤占配额。旧版只有一个共享池，配额起点为 1
+  // 时一个回合里第二个检查点几乎必然撞墙——这不是顾问后端配置问题，是结构性的。
+  const isMandated = ctx?.advisorInvocation === 'agent'
+    && ctx.advisorRuntime?.hasActiveGate === true;
+  const quota = ctx?.advisorCalls;
+  const usesMandatoryPool = isMandated && quota?.mandatoryMax !== undefined;
+  const quotaUsed = usesMandatoryPool ? (quota!.mandatoryUsed ?? 0) : quota?.used;
+  const quotaMax = usesMandatoryPool ? quota!.mandatoryMax! : quota?.max;
+
+  if (!isReconcile && quota && quotaUsed !== undefined && quotaMax !== undefined && quotaUsed >= quotaMax) {
     // ⚠️ 必须说明「配额会增长」：配额随本回合工作量上调（loop.ts::advisorQuotaFor），
     // 若这里只说「已达上限」，模型会当成本回合的硬上限而不再尝试 —— 那样长回合里
     // 「批次做完再复核一次」的配额永远不会被用到，增长机制等于没做。
-    return {
+    // ⚠️ 只有确实存在一个待结清的咨询（pendingConsultationId）时才能说"按已有
+    // 意见继续"——否则这一步可能压根没有产生过任何意见，那句话就是误导。
+    const hasPendingAdvice = ctx?.advisorRuntime?.pendingConsultationId !== undefined;
+    const poolLabel = usesMandatoryPool ? '检查点强制咨询配额' : '顾问咨询配额';
+    const guidance = hasPendingAdvice
+      ? '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。'
+      : '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；这一步目前没有可参考的顾问意见，' +
+        '请基于代码、测试等一手证据自行判断，并在汇报时如实说明这一步未获得第二意见背书。';
+    return finish({
       ok: false,
-      error:
-        `本回合顾问咨询配额暂时用完（当前 ${ctx.advisorCalls.max} 次）。` +
-        '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。',
-    };
+      error: `本回合${poolLabel}暂时用完（当前 ${quotaMax} 次）。${guidance}`,
+    });
+  }
+  if (!isReconcile && quota) {
+    if (usesMandatoryPool) quota.mandatoryUsed = (quota.mandatoryUsed ?? 0) + 1;
+    else quota.used++;
   }
-  if (ctx?.advisorCalls) ctx.advisorCalls.used++;
 
   const provider = advisor.provider;
   const snapshot = await configService.getSnapshot();
@@ -437,6 +504,9 @@ export async function runAdvisor(
     contextWindow: provider.contextWindow,
     maxTokens: provider.maxTokens,
     inputTokenBudget: advisor.inputTokenBudget,
+    ...(ctx?.advisorRuntime
+      ? { contextPacket: ctx.advisorRuntime.contextPacket(input.note) }
+      : {}),
   });
 
   // Advisor 是可降级的第二意见：使用独立、可配置的总时限，不影响主模型的流式时限。
@@ -500,23 +570,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);
   }
@@ -532,7 +605,7 @@ export async function runAdvisor(
       `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
   }
 
-  return { ok: true, content };
+  return finish({ ok: true, content });
 }
 
 // 无宿主上下文的调用视为用户手动咨询；生产主循环使用 callWithContext。

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;

package/src/tools/agent/agent.ts

@@ -59,7 +59,7 @@ import {
   worktreeChangedFiles,
   worktreeDiffStat,
 } from './worktree.js';
-import { appendAgentEvent, loadAgentRecord, saveAgentRecord, type AgentTaskRecord, type LiveAgentTask } from './agentTaskService.js';
+import { appendAgentEvent, attachAgentHistory, loadAgentRecord, saveAgentRecord, type AgentTaskRecord, type LiveAgentTask } from './agentTaskService.js';
 
 // ---------------- 0. 环内模块懒加载（见文件头「循环依赖纪律」） ----------------
 
@@ -120,7 +120,7 @@ const inputSchema = z.object({
   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>;
+export type AgentInput = z.infer<typeof inputSchema>;
 
 const parameters = toToolParameters(inputSchema);
 
@@ -227,7 +227,8 @@ export interface AgentTaskDeps {
   chat?: RunQueryOptions['chat'];
   executeTool?: RunQueryOptions['executeTool'];
   initialHistory?: RunQueryOptions['history'];
-  captureHistory?: (history:RunQueryOptions['history'])=>void|Promise<void>;
+  captureHistory?: (history: RunQueryOptions['history']) => void | Promise<void>;
+  onHistoryReady?: (history: RunQueryOptions['history']) => void;
   existingWorktree?: AgentWorktree;
   onWorktreeCreated?: (worktree: AgentWorktree) => void | Promise<void>;
 }
@@ -296,7 +297,10 @@ export async function runAgentTask(
   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;
@@ -377,6 +381,7 @@ export async function runAgentTask(
   const history: RunQueryOptions['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: (() => void) | null = null;
@@ -469,8 +474,8 @@ export async function runAgentTask(
     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' && !wt && ['Bash', 'ApplyPatch'].includes(name) && writeScopes[0] !== rootScope[0]) {
+      return { ok: false as const, error: `声明了局部 write_scopes 时禁止 ${name}：无法可靠证明一次调用只写入批准范围。请改用单文件工具或使用整个工作目录范围。` };
     }
     if (def.type === 'general' && rawPath) {
       if (isAbsolute(rawPath)) return { ok: false as const, error: `${name} 必须使用工作目录相对路径：${rawPath}` };
@@ -483,7 +488,14 @@ export async function runAgentTask(
         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 一律不外泄，折算成统计 + 步内进度 ----
@@ -737,6 +749,7 @@ export async function runManagedAgentTask(
     abort,
     completion,
     events: new EventEmitter(),
+    inbox: [],
   };
   ctx.sessionState.agentTasks.tasks.set(id, task);
   await saveAgentRecord(ctx, task);
@@ -769,6 +782,7 @@ export async function runManagedAgentTask(
           await saveAgentRecord(ctx, task);
         },
         captureHistory: (history) => { captured = [...history]; },
+        onHistoryReady: (history) => attachAgentHistory(task, history),
       });
       task.result = result;
       task.history = captured;