minimal-agent 0.18.13 → 0.18.14

package/src/loop.ts

@@ -5,10 +5,10 @@ import {
   injectVisionFollowups,
   mergeToolCallDelta,
   pushManualInterruptMarker,
+  pushAdvisorFollowUpMarker,
   pushQueuedInputMarker,
 } from './loop/messages.js';
 import type { RunQueryOptions } from './loop/options.js';
-import { publishFinalAnswer } from './loop/publication.js';
 import { prepareModelRequest } from './loop/requestPreparation.js';
 import { executeToolBatch } from './loop/toolBatch.js';
 import { createToolExecutor, type WorkerOutcome } from './loop/toolExecutor.js';
@@ -25,15 +25,17 @@ export { friendlyToolDescription } from './loop/toolPresentation.js';
 export { advisorSemanticsFor } from './loop/toolSemantics.js';
 /**
  * Agent turn orchestrator. Owns conversation state and continuation decisions.
- * Request preparation, tool execution/scheduling and final publication live in
- * ./loop/. Host options and LoopEvent remain the public compatibility boundary.
+ * Request preparation and tool execution/scheduling live in ./loop/; the
+ * final answer is published here, verbatim, once every delivery gate passes.
+ * Host options and LoopEvent remain the public compatibility boundary.
  * See ./loop/README.md for phase ownership and invariants.
  */
 
 import crypto from 'node:crypto';
 import { resolve } from 'node:path';
-import { AdvisorCoordinator } from './advisor/advisorCoordinator.js';
-import { collectReviewContext } from './advisor/reviewContext.js';
+import { AdvisorNudge } from './advisor/advisorNudge.js';
+import { collectAdvisorBackground } from './advisor/reviewContext.js';
+import { previousUserRequest } from './memory/recallQuery.js';
 import { configService } from './config/configService.js';
 import { buildContextBudgetPlan } from './context/budgetPlan.js';
 import { getCompactThreshold } from './context/compact.js';
@@ -58,12 +60,13 @@ import { buildUserContent } from './multimodal.js';
 import { delegationRuntimeGuidance } from './prompts/delegation.js';
 import { capabilitiesForTools, enabledPolicyIds } from './prompts/policyRegistry.js';
 import { loadProjectPromptInstructions } from './prompts/projectInstructions.js';
-import { needsDiagramPreparation, visualPresentation } from './prompts/visualPresentation.js';
+import { needsDiagramPreparation, requestKeepsTextDiagrams, visualPresentation } from './prompts/visualPresentation.js';
+import { LiveDiagramGate } from './loop/liveDiagramGate.js';
 import { createAgentRuntimeContext } from './runtime/agentRuntimeContext.js';
 import { answerPreparationNotice } from './runtime/answerPreparation.js';
 import { invocationInstructions, invocationToolAllowed } from './runtime/invocationPolicy.js';
 import { createLifecycleTrace } from './runtime/lifecycleTrace.js';
-import { resolveOutputContract, toolsForResponsePhase } from './runtime/outputContract.js';
+import { resolveOutputContract } from './runtime/outputContract.js';
 import { filterToolsForProvider } from './team/toolPolicy.js';
 import { agentCoordinationContext, takeAgentNotifications } from './tools/agent/agentTaskService.js';
 import { needsInteractiveQuestion } from './tools/ask/routing.js';
@@ -80,6 +83,25 @@ import { stripThinkBlocks } from './utils/stripThink.js';
 /** 主工具循环的默认轮数上限。 */
 export const DEFAULT_MAX_TURNS = 200;
 
+/** Live streaming starts once real answer text exists. A leading inline
+ * <think> block (MiniMax and similar), even a tag still arriving in pieces,
+ * is not the answer and must not be shown as if it were. */
+/** 显式选项优先；否则读配置 `advisor.enforcement`（只在需要补问时才读一次盘，读失败当作关闭）。 */
+async function advisorFollowUpEnabled(options: RunQueryOptions): Promise<boolean> {
+  if (options.advisorFollowUp !== undefined) return options.advisorFollowUp;
+  try {
+    return (await configService.advisor())?.enforcement === 'followup';
+  } catch {
+    return false;
+  }
+}
+
+function answerTextStarted(text: string): boolean {
+  const lead = text.trimStart();
+  if (lead.length < '<think>'.length && '<think>'.startsWith(lead.toLowerCase())) return false;
+  return stripThinkBlocks(text).length > 0;
+}
+
 /**
  * 执行一次"用户输入 → 模型回答完成"的完整流程。
  *
@@ -158,7 +180,13 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
   let emptyResponseRecoveryAttempted = false;
   let emptyResponseRecoveryReason = '';
   let askCorrectionAttempted = false;
-  let diagramPreparationAttempted = false;
+  let diagramCorrectionAttempted = false;
+  // The retired draft rides along with the next request only, as private
+  // revision material: never shown to the user, never stored in history.
+  let diagramCorrectionDraft = '';
+  // Part of that draft already streamed live (the text before the box): the
+  // model continues from there instead of rewriting what the user has read.
+  let diagramContinuation = false;
   const output = resolveOutputContract(runtimeContext.surface, runtimeContext.output);
   const subagents = await configService.subagents();
   await hydrateSessionWorktree({
@@ -178,35 +206,12 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
     },
     history,
     sessionState,
-    advisorReviewContext: () => ({
-      ...collectReviewContext(advisorContextBundle),
-      constraints: [
-        ...collectReviewContext(advisorContextBundle).constraints,
-        {
-          id: 'execution.boundary',
-          authority: 'host',
-          content: JSON.stringify({
-            cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
-            conversationMode: toolCallContext.conversationMode,
-            profile: runtimeContext.profile,
-            availableTools: [...currentEffectiveToolSet.names],
-            invocation: invocationInstructions(options.invocationPolicy),
-          }),
-        },
-      ],
-      omittedIds: [
-        ...new Set([
-          ...(currentTransientBundle?.diagnostics.omittedIds ?? []),
-          ...(advisorContextBundle?.diagnostics.omittedIds ?? []),
-        ]),
-        ...(options.transientContext ? ['legacy.transient-context:not-forwarded'] : []),
-      ],
-      clippedIds: [
-        ...new Set([
-          ...(currentTransientBundle?.diagnostics.clippedIds ?? []),
-          ...(advisorContextBundle?.diagnostics.clippedIds ?? []),
-        ]),
-      ],
+    // Project constraints and memory are not in the conversation history, so the
+    // advisor gets them as one background block (see tools/advisor/advisor.ts).
+    advisorBackground: () => collectAdvisorBackground(advisorContextBundle, {
+      cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
+      availableTools: [...currentEffectiveToolSet.names],
+      invocation: invocationInstructions(options.invocationPolicy),
     }),
     // Statistics only; consultations have no per-turn quota.
     advisorCalls: { used: 0 },
@@ -257,20 +262,20 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
     options.invocationPolicy?.delivery !== 'caller' &&
     effectiveToolSet.names.has('PresentResult');
   let currentEffectiveToolSet = effectiveToolSet;
-  const advisorCoordinator = new AdvisorCoordinator({
-    history,
+  // The host only reminds; whether to consult the advisor is the model's call
+  // (see advisor/advisorNudge.ts). Nothing here blocks a tool or holds an answer.
+  const advisorNudge = new AdvisorNudge({
     currentRequest: userInput,
-    currentRequestMessageId: currentUserMessageId,
-    advisorAvailable: effectiveToolSet.names.has('Advisor'),
+    previousRequest: previousUserRequest(history),
+    advisorAvailable: effectiveToolSet.names.has('Advisor') && options.advisorReminders !== false,
   });
-  toolCallContext.advisorRuntime = advisorCoordinator;
   let coordinationText = '';
   let delegationCorrectionAttempted = false;
   // 组装每轮请求的易变上下文。三个构建点（首轮 / autoCompact 后 / snip 后）共用，
   // 避免 Advisor 相关提醒在复制粘贴中三处漂移。提醒均为 transient：只进当轮请求副本，
   // 不进会话历史（与 DELIVERY_CORRECTION_REMINDER 同构，见 buildModelMessages）。
   const buildRequestTransientContext = (): string => {
-    const advisorAvailable = currentEffectiveToolSet.names.has('Advisor');
+    const advisorAvailable = currentEffectiveToolSet.names.has('Advisor') && options.advisorReminders !== false;
     const parts = [
       transientFor(activeTools),
       coordinationText,
@@ -280,7 +285,13 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         callsUsed: toolCallContext.agentCalls?.used ?? 0,
         maxCalls: toolCallContext.agentCalls?.max ?? 0,
       }),
-      diagramPreparationAttempted ? visualPresentation(output) : '',
+      diagramCorrectionDraft
+        ? `${visualPresentation(output)}\n${
+            diagramContinuation
+              ? `你这版回答已向用户显示到字符框图之前（已保存为上一条消息，不能修改或撤回），框图及其后内容用户尚未看到。请紧接着已显示的内容继续写：先用 ${output.diagrams.join('/')} 重画那张框图，再按下方草稿写完其余部分，保留结论、数字、限定条件和链接；不要重复已显示的内容。`
+              : `你上一版回答（下方内部草稿，用户尚未看到）用字符画了框图，而当前载体可渲染 ${output.diagrams.join('/')}。请在这版草稿的基础上修订：只把字符框图改成这些格式，保留其余结论、数字、限定条件和链接。`
+          }技能目录里有图形技能时可先加载。\n<internal-draft>\n${diagramCorrectionDraft}\n</internal-draft>`
+        : '',
       delegationCorrectionAttempted
         ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。'
         : '',
@@ -291,8 +302,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         ? `上一次模型响应没有可交付正文（${emptyResponseRecoveryReason}）。请基于已有历史和工具结果继续完成任务：信息充分则给出实质结论，不充分则继续必要操作或明确缺口。不要重复已经完成的调查或有副作用的操作；不要把未完成的任务说成完成。已有顾问意见继续有效，无需仅因恢复而再次咨询。`
         : '',
       deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
-      advisorAvailable ? advisorCoordinator.transientReminder() : '',
-      advisorAvailable ? advisorCoordinator.usageLine(toolCallContext.advisorCalls!.used) : '',
+      advisorAvailable ? advisorNudge.reminder() : '',
     ];
     return parts.filter(Boolean).join('\n\n');
   };
@@ -577,7 +587,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
       replaceHistory,
       buildRequestTransientContext: (tools) => {
         currentEffectiveToolSet = tools;
-        advisorCoordinator.setAvailable(tools.names.has('Advisor'));
+        advisorNudge.setAvailable(tools.names.has('Advisor') && options.advisorReminders !== false);
         lastRequestTransientContext = buildRequestTransientContext();
         return lastRequestTransientContext;
       },
@@ -599,7 +609,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
     let assistantText = '';
     // Candidate text is private until the delivery gates allow publication.
     // Keep the compatibility event as a phase notice, never as a text retraction.
-    function* retireDraft(
+    function* preparationNotice(
       reason: Extract<LoopEvent, { type: 'assistant_draft_discarded' }>['reason'] | 'interrupted',
     ): Generator<LoopEvent> {
       const message: Message = {
@@ -612,6 +622,11 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
       };
       history.push(message);
       yield { type: 'injected_message', message };
+    }
+    function* retireDraft(
+      reason: Extract<LoopEvent, { type: 'assistant_draft_discarded' }>['reason'] | 'interrupted',
+    ): Generator<LoopEvent> {
+      yield* preparationNotice(reason);
       if (reason !== 'interrupted') yield { type: 'assistant_draft_discarded', reason, textLength: 0 };
     }
     /** 按 index 累积 tool_calls（OpenAI 协议下 tool_calls 是分片返回的） */
@@ -623,6 +638,25 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
     let reasoningContent = '';
     let reasoningString = '';
     const reasoningDetails: unknown[] = [];
+    /** Visible text is never retracted: whatever already streamed live is
+     * committed before the turn moves on (interruption, error, new messages). */
+    function* commitLiveAnswer(presentation: 'final' | 'progress'): Generator<LoopEvent> {
+      const message: Extract<Message, { role: 'assistant' }> = {
+        role: 'assistant',
+        // Only what the user actually saw: a box held back by the diagram gate
+        // must not slip into history through an interruption.
+        content: assistantText.slice(0, shownLength),
+        ...(reasoningContent ? { reasoning_content: reasoningContent } : {}),
+        ...(reasoningString ? { reasoning: reasoningString } : {}),
+        ...(reasoningDetails.length > 0 ? { reasoning_details: reasoningDetails } : {}),
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+        presentation,
+        ...(options.messageProvenance ? { provenance: options.messageProvenance } : {}),
+      };
+      history.push(message);
+      yield { type: 'assistant_message', message };
+    }
 
     /**
      * R2：本轮 LLM 流的终止原因（来自 client 的 done.stopReason）。
@@ -631,17 +665,63 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
      */
     let lastFinishReason: 'stop' | 'tool_calls' | 'length' | 'unknown' | 'aborted' = 'unknown';
 
+    // Decided before the model writes anything: can a check still hold this
+    // answer back? If not, it is irrevocable by construction and streams live
+    // (visible text is never retracted). If one can — a required formal delivery
+    // or an unresolved delegation — the candidate stays private until it passes
+    // and is then published verbatim. Streaming everything and retracting on a
+    // later check showed users drafts that vanished; buffering everything made
+    // every answer appear as one block. The advisor is deliberately not a holder
+    // any more: it is a reminder, so an answer never waits for it.
+    const liveEligible =
+      !options.responseFormat &&
+      runtimeContext.profile === 'main' &&
+      output.finalDelivery === 'stream' &&
+      !(formalDeliveryRequired && !resultPresented && !deliveryCorrectionAttempted);
+    // Only decides how the answer is shown: unreadable delegation state means
+    // "hold it back", never a failed turn (the final gate re-reads it anyway).
+    const delegationMayHold =
+      liveEligible &&
+      !delegationCorrectionAttempted &&
+      currentEffectiveToolSet.names.has('Agent') &&
+      (await agentCoordinationContext(toolCallContext).then(
+        (coordination) =>
+          coordination.unresolved.some((record) => record.parentMessageId === currentUserMessageId),
+        () => true,
+      ));
+    const liveFinal = liveEligible && !delegationMayHold;
+    let liveStarted = false;
+    let shownLength = 0;
+    // Live answers on a diagram-rendering surface hold back a fence that could
+    // be a text drawing until it closes, so a box can be corrected without
+    // retracting anything (see loop/liveDiagramGate.ts).
+    const diagramGate =
+      liveFinal && output.diagrams.length > 0 && !diagramCorrectionAttempted && !requestKeepsTextDiagrams(userInput)
+        ? new LiveDiagramGate()
+        : undefined;
+    function* releaseLive(final = false): Generator<LoopEvent> {
+      const end = diagramGate ? diagramGate.releasable(assistantText, final) : assistantText.length;
+      if (!liveStarted) {
+        if (!answerTextStarted(assistantText.slice(0, end))) return;
+        liveStarted = true;
+        yield { type: 'stage_change', stage: 'streaming' };
+      }
+      if (end > shownLength) {
+        yield { type: 'text', delta: assistantText.slice(shownLength, end) };
+        shownLength = end;
+      }
+    }
+
     // 进入 LLM 流前：等首 token / reasoning，本质是 thinking
     yield { type: 'stage_change', stage: 'thinking' };
     workStarted = true;
 
     try {
       const modelMessages = buildModelMessages(history, requestTransientContext, userMessage.id);
-      advisorCoordinator.markTransientDelivered();
       for await (const ev of chatFn({
         provider,
         messages: modelMessages,
-        tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'preparation'),
+        tools: currentEffectiveToolSet.tools,
         signal,
         conversationMode: runtimeContext.conversationMode ?? 'private',
         promptCache: options.promptCache,
@@ -652,6 +732,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
       })) {
         if (ev.type === 'text_delta') {
           assistantText += ev.delta;
+          if (liveFinal) yield* releaseLive();
         } else if (ev.type === 'tool_call_delta') {
           mergeToolCallDelta(toolCallsByIndex, ev);
         } else if (ev.type === 'reasoning_delta') {
@@ -694,15 +775,18 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
     } catch (e) {
       trace('model_error');
       if ((e as Error).name === 'AbortError') {
-        yield* retireDraft('interrupted');
+        if (liveStarted) {
+          yield* commitLiveAnswer('final');
+          yield { type: 'warning', message: '回答未完整生成，已保留已显示的内容；未撤回或重新生成。' };
+        } else yield* retireDraft('interrupted');
         yield interruption();
         return;
       }
 
       // prompt_too_long 反应式自救：压缩历史 → 同 turn 重发 LLM
       // LLM 看到压缩后的 9 段摘要 + 近期 verbatim 消息，能接着干活，
-      // 不会丢失中途的工具调用上下文。
-      if (isPromptTooLongError(e) && reactiveCount < MAX_REACTIVE_PER_QUERY) {
+      // 不会丢失中途的工具调用上下文。已实时显示过文字时不重发（会重复输出）。
+      if (!liveStarted && isPromptTooLongError(e) && reactiveCount < MAX_REACTIVE_PER_QUERY) {
         reactiveCount++;
         yield { type: 'compact_start' };
         yield { type: 'stage_change', stage: 'compacting' };
@@ -750,7 +834,10 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
       }
 
       // code='llm_error'：终结性错误，stop_reason='error'
-      yield* retireDraft('interrupted');
+      if (liveStarted) {
+        yield* commitLiveAnswer('final');
+        yield { type: 'warning', message: '回答未完整生成，已保留已显示的内容；未撤回或重新生成。' };
+      } else yield* retireDraft('interrupted');
       yield {
         type: 'error',
         error: `LLM 调用失败：${(e as Error).message}`,
@@ -760,8 +847,18 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
     }
 
     trace('model_end');
+    // A tool round (e.g. loading a graphics skill) is part of the revision;
+    // the draft is dropped only once the revised answer itself has arrived.
+    if (toolCallsByIndex.length === 0) {
+      diagramCorrectionDraft = '';
+      diagramContinuation = false;
+    }
     if (lastFinishReason === 'aborted' || signal?.aborted || options.hasQueuedInput?.()) {
-      yield* retireDraft('interrupted');
+      if (liveStarted) {
+        yield* commitLiveAnswer('final');
+        if (lastFinishReason !== 'stop')
+          yield { type: 'warning', message: '回答未完整生成，已保留已显示的内容；未撤回或重新生成。' };
+      } else yield* retireDraft('interrupted');
       if (options.hasQueuedInput?.() && !signal?.aborted) {
         pushQueuedInputMarker(history);
         yield { type: 'interrupted', reason: 'queued_input' };
@@ -782,43 +879,12 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
       }
     }
 
-    // A pending review must run before another solving/publishing attempt.
-    // Read-only diagnosis and human questions remain available while stalled.
-    const pendingReview = options.advisorCheckpoints === false ? undefined : advisorCoordinator.pendingReview();
-    if (
-      pendingReview &&
-      turn < maxTurns &&
-      toolCallsByIndex.length > 0 &&
-      !toolCallsByIndex.some((tc) => ['Advisor', 'AskUserQuestion'].includes(tc.function.name)) &&
-      toolCallsByIndex.some(
-        (tc) =>
-          tc.function.name === 'PresentResult' ||
-          advisorSemanticsFor(
-            tc,
-            toolCallContext,
-            currentEffectiveToolSet.tools.find((t) => t.name === tc.function.name),
-            { treatVerificationAsReadOnly: true },
-          ).mutatesWorkspace ||
-          stallGuard.shouldReject(tc),
-      )
-    ) {
-      yield* retireDraft('advisor_checkpoint');
-      toolCallsByIndex.splice(0, toolCallsByIndex.length, {
-        id: crypto.randomUUID(),
-        type: 'function',
-        function: { name: 'Advisor', arguments: JSON.stringify(pendingReview) },
-      });
-      assistantText = '';
-    }
-    // Count the calls that survived review scheduling, including failed loads.
-    for (const call of toolCallsByIndex) {
-      if (call.function.name !== 'Skill') continue;
-      try {
-        if (JSON.parse(call.function.arguments).name === 'dynamic-ui') diagramPreparationAttempted = true;
-      } catch {
-        /* Ordinary tool validation reports malformed arguments. */
-      }
+    if (liveFinal) {
+      // Narration before a tool round, or no turn left to revise: show it all.
+      if (diagramGate?.hit !== undefined && (toolCallsByIndex.length > 0 || turn >= maxTurns)) diagramGate.release();
+      yield* releaseLive(true);
     }
+
     const assistantMsg: Message = {
       role: 'assistant',
       content: assistantText.length > 0 ? assistantText : null,
@@ -832,31 +898,41 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
     };
     // 4. 没有工具调用 → 整轮交互结束
     finalResponse: if (toolCallsByIndex.length === 0) {
-      // Repair only private preparation, through the ordinary tool pipeline.
-      // One attempt per turn, including missing/failed skills; never rewind a reply.
+      if (diagramGate?.hit !== undefined) {
+        diagramCorrectionAttempted = true;
+        diagramCorrectionDraft = assistantText;
+        if (liveStarted) {
+          // The text before the box stays exactly as shown, as its own message.
+          diagramContinuation = true;
+          yield* commitLiveAnswer('progress');
+          yield* preparationNotice('diagram_preparation');
+        } else yield* retireDraft('diagram_preparation');
+        continue;
+      }
+      // A boxed ASCII diagram on a surface that renders real diagrams: retire the
+      // private draft once and let the model revise it, with the draft passed
+      // back as internal material (asking it to "keep the rest" without showing
+      // the rest made it answer from scratch). The kernel names no skill and
+      // never writes a tool call the model did not make — it used to inject
+      // Skill("dynamic-ui") into history under the model's name. Content checks
+      // like this one and the ask correction apply only to private drafts; an
+      // answer that already streamed live is never retracted.
       if (
-        !diagramPreparationAttempted &&
+        !liveStarted &&
+        !diagramCorrectionAttempted &&
         !options.responseFormat &&
         runtimeContext.profile === 'main' &&
         output.diagrams.length > 0 &&
-        currentEffectiveToolSet.names.has('Skill') &&
         turn < maxTurns &&
         needsDiagramPreparation(assistantText, userInput)
       ) {
-        diagramPreparationAttempted = true;
-        toolCallsByIndex.push({
-          id: crypto.randomUUID(),
-          type: 'function',
-          function: {
-            name: 'Skill',
-            arguments: JSON.stringify({ name: 'dynamic-ui' }),
-          },
-        });
-        assistantMsg.content = null;
-        assistantMsg.tool_calls = toolCallsByIndex;
-        break finalResponse;
+        diagramCorrectionAttempted = true;
+        diagramCorrectionDraft = assistantText;
+        yield* retireDraft('diagram_preparation');
+        continue;
       }
       if (
+        !liveStarted &&
         !askCorrectionAttempted &&
         runtimeContext.interactiveAsk &&
         currentEffectiveToolSet.names.has('AskUserQuestion') &&
@@ -872,7 +948,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         runtimeContext.profile === 'main' ? await agentCoordinationContext(toolCallContext) : undefined;
       const pendingDelegations =
         coordination?.unresolved.filter((record) => record.parentMessageId === currentUserMessageId) ?? [];
-      if (pendingDelegations.length && !delegationCorrectionAttempted && turn < maxTurns) {
+      if (!liveStarted && pendingDelegations.length && !delegationCorrectionAttempted && turn < maxTurns) {
         delegationCorrectionAttempted = true;
         coordinationText = coordination!.text;
         yield* retireDraft('formal_delivery');
@@ -883,6 +959,9 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         ...(await takeAgentNotifications(toolCallContext)),
       ];
       if (pendingMessages.length) {
+        // A private draft is simply superseded; a live one was already read,
+        // so it stays in the conversation as this step's progress.
+        if (liveStarted) yield* commitLiveAnswer('progress');
         history.push(...pendingMessages);
         continue;
       }
@@ -890,6 +969,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
       // presenting it. Give it one model-only corrective pass; the reminder is
       // transient and therefore never pollutes persisted conversation history.
       if (
+        !liveStarted &&
         !emptyResponse &&
         formalDeliveryRequired &&
         !resultPresented &&
@@ -900,38 +980,19 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         yield* retireDraft('formal_delivery');
         continue;
       }
-      const deliveryCheckpoint =
-        emptyResponse || options.advisorCheckpoints === false
-          ? { allow: true as const }
-          : advisorCoordinator.beforeDelivery(assistantText);
-      const fallbackReview =
-        !emptyResponse && options.advisorCheckpoints !== false
-          ? advisorCoordinator.pendingReview(assistantText)
-          : undefined;
-      if (fallbackReview && turn < maxTurns) {
-        yield* retireDraft('advisor_checkpoint');
-        // Reuse the effective tool boundary, permissions, cancellation, events and
-        // persistence. Never call a provider behind the host's tool pipeline.
-        toolCallsByIndex.push({
-          id: crypto.randomUUID(),
-          type: 'function',
-          function: {
-            name: 'Advisor',
-            arguments: JSON.stringify(fallbackReview),
-          },
-        });
-        assistantMsg.content = null;
-        assistantMsg.tool_calls = toolCallsByIndex;
-        break finalResponse;
-      }
-      if (!deliveryCheckpoint.allow && turn < maxTurns) {
-        yield* retireDraft('advisor_checkpoint');
-        continue;
-      }
+      let advisorFollowUp = false;
       if (!emptyResponse) {
-        for (const message of advisorCoordinator.deliveryWarnings()) yield { type: 'warning', message };
-        if (!deliveryCheckpoint.allow)
-          yield { type: 'warning', message: '已达到本轮执行上限，顾问交付检查尚未完成；不能把此次输出视为已复核。' };
+        // A reminder, never a gate: the answer is already on its way to the user.
+        // With enforcement 'followup' (weak models that never ask on their own) an
+        // unreviewed substantive answer earns one more request in which the model is
+        // asked to call Advisor itself; the warning is then left for that pass.
+        if (turn < maxTurns && advisorNudge.followUpDue(assistantText) && (await advisorFollowUpEnabled(options))) {
+          advisorNudge.markFollowedUp();
+          advisorFollowUp = true;
+        } else {
+          const unreviewed = advisorNudge.unreviewedWarning(assistantText);
+          if (unreviewed) yield { type: 'warning', message: unreviewed };
+        }
       }
       if (emptyResponse) {
         // Recover once within the existing turn budget, retaining tool receipts and
@@ -958,85 +1019,25 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         }
         yield* retireDraft('empty_response');
       } else {
-        // Publication is a separate tool-free request. Nothing from preparation
-        // has been streamed, and no gate may retract text after this boundary.
-        let publicationError: unknown;
-        let publicationInterrupted = false;
-        let streamed = false;
-        if (!options.responseFormat && runtimeContext.profile === 'main' && output.finalDelivery === 'stream') {
-          const publication = yield* publishFinalAnswer({
-            provider,
-            messages: buildModelMessages(history, requestTransientContext, userMessage.id),
-            candidate: assistantText,
-            candidateFinishReason: lastFinishReason,
-            output,
-            chatFn,
-            options,
-            signal,
-            conversationMode: runtimeContext.conversationMode ?? 'private',
-            turnUsage,
-          });
-          const publishedText = publication.text;
-          ({ publicationError, publicationInterrupted, streamed, lastFinishReason } = publication);
-          assistantText = publishedText;
-          assistantMsg.content = publishedText || null;
-          if (!publishedText) {
-            if (publicationInterrupted)
-              yield {
-                ...interruption(),
-                usage: {
-                  ...turnUsage,
-                  trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
-                },
-              };
-            else
-              yield {
-                type: 'error',
-                code: 'llm_error',
-                error: `最终答案生成失败：${String(publicationError)}`,
-                usage: {
-                  ...turnUsage,
-                  trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
-                },
-              };
-            return;
-          }
-        }
+        // Publication is a one-way boundary: the text that passed every gate is
+        // exactly what the user sees and what history keeps — streamed live
+        // when nothing could hold it back, otherwise published verbatim now.
+        // It used to be regenerated by a second tool-free request: a third
+        // text no gate had seen, at the cost of a full-context call.
+        if (!liveStarted && !options.responseFormat && runtimeContext.profile === 'main' && output.finalDelivery === 'stream')
+          yield { type: 'stage_change', stage: 'streaming' };
         assistantMsg.presentation = 'final';
         trace('final_published');
-        if (assistantMsg.role === 'assistant')
-          assistantMsg.advisorTaskVersion = advisorCoordinator.versions.taskVersion;
-        assistantMsg.advisorCheckpoints = advisorCoordinator.drainDegradations();
         history.push(assistantMsg);
-        // Non-interactive consumers retain atomic output. Interactive hosts
-        // already received real deltas; commit the identical text only once.
-        if (!streamed) yield { type: 'text', delta: assistantText };
+        if (!liveStarted) yield { type: 'text', delta: assistantText };
         yield {
           type: 'assistant_message',
           message: assistantMsg as Extract<Message, { role: 'assistant' }>,
         };
-        if (publicationInterrupted || publicationError) {
-          yield { type: 'warning', message: '最终答案未完整生成，已保留已输出内容；未撤回或重新生成。' };
-          if (publicationInterrupted)
-            yield {
-              ...interruption(),
-              usage: {
-                ...turnUsage,
-                trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
-              },
-            };
-          else
-            yield {
-              type: 'error',
-              code: 'llm_error',
-              error: `最终答案流中断：${String(publicationError)}`,
-              usage: {
-                ...turnUsage,
-                trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
-              },
-            };
-          return;
-        }
+      }
+      if (advisorFollowUp) {
+        pushAdvisorFollowUpMarker(history);
+        continue;
       }
       // R2：最终回答被 provider 因 max_tokens 截断（finish_reason='length'）时，
       // 不能静默当正常 end_turn 收尾 —— 否则 -p 宿主会拿到半截答案却以为成功。
@@ -1146,7 +1147,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
       runtimeContext,
       toolCallContext,
       currentEffectiveToolSet,
-      advisorCoordinator,
+      advisorNudge,
       stallGuard,
       modelEnvironmentCwd,
       observedRuleScopes,
@@ -1160,18 +1161,16 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
     // latest evidence and versions. Parallel batches commit in call order once
     // settled. Both paths use this single writer, avoiding duplicate observation.
     const commitOutcome = async function* ({ tc, result }: WorkerOutcome): AsyncGenerator<LoopEvent> {
-      if (tc.function.name !== 'Advisor' && tc.function.name !== 'AdvisorDecision') {
-        advisorCoordinator.observeToolResult(
+      advisorNudge.observeToolResult(
+        tc,
+        result,
+        advisorSemanticsFor(
           tc,
-          result,
-          advisorSemanticsFor(
-            tc,
-            toolCallContext,
-            currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name),
-            { treatVerificationAsReadOnly: true },
-          ),
-        );
-      }
+          toolCallContext,
+          currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name),
+          { treatVerificationAsReadOnly: true },
+        ),
+      );
       if (result.ok || result.disposition !== 'deferred') {
         evidenceLedger.record(tc.function.name, tc.function.arguments, result);
       }
@@ -1189,6 +1188,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         const manifest = result.metadata?.kind === 'result_manifest' ? result.metadata.manifest : browserArtifact;
         presentedResultUnverified ||= manifest?.files.some((file) => file.verification === 'failed') ?? false;
       }
+      const actionHint = advisorNudge.takeActionHint();
       const rawContent = result.ok ? result.content : `Error: ${result.error}`;
       const basePolicy = result.policy ?? getToolResultPolicy(tc.function.name);
       // 超大结果先归档再压缩：归档失败时保留原文，绝不因为磁盘问题破坏上下文。
@@ -1212,9 +1212,10 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         ? { ...basePolicy, archiveRef: archived.archiveRef, originalChars: archived.originalChars }
         : basePolicy;
       // 微压缩仅对成功结果走；policy 会保护高价值结果，避免不可逆中段丢失。
-      const content = result.ok
+      const compacted = result.ok
         ? microCompact(tc.function.name, archived.content, sessionState?.microCompact, policy)
         : rawContent;
+      const content = actionHint ? `${compacted}\n\n${actionHint}` : compacted;
       history.push({
         role: 'tool',
         display_ok: result.ok,
@@ -1222,13 +1223,6 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         tool_call_id: tc.id,
         tool_result_policy: policy,
         ...(!result.ok && result.disposition === 'deferred' ? { toolResultDisposition: 'deferred' as const } : {}),
-        ...(tc === toolCallsByIndex.at(-1) ? { advisorCheckpoints: advisorCoordinator.drainDegradations() } : {}),
-        advisorMutatesWorkspace: advisorSemanticsFor(
-          tc,
-          toolCallContext,
-          currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name),
-          { treatVerificationAsReadOnly: true },
-        ).mutatesWorkspace,
         ...(result.metadata ? { display_metadata: result.metadata } : {}),
         timestamp: Date.now(),
         id: crypto.randomUUID(),
@@ -1277,7 +1271,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
         stall.reason === 'repeated_failure'
           ? '同一问题两次尝试失败，请停止原样重试；顾问可用时，继续解决或交付前先咨询，由主 Agent 自行核验和决策。只读诊断仍可继续。'
           : '检测到连续工具轮次没有产生新文本或新结果；请切换路径或咨询 Advisor。';
-      if (stall.reason !== 'repeated_failure') advisorCoordinator.notifyStalled(stall.signature ?? stall.reason);
+      if (stall.reason !== 'repeated_failure') advisorNudge.notifyStalled(stall.signature ?? stall.reason ?? 'no_progress');
       yield { type: 'warning', message };
     }