minimal-agent 0.18.13 → 0.18.14

package/src/loop.js

@@ -1,6 +1,5 @@
 import { DELIVERY_CORRECTION_REMINDER, expectsFormalDelivery } from './loop/deliveryIntent.js';
-import { buildModelMessages, evictPriorVisionShots, injectVisionFollowups, mergeToolCallDelta, pushManualInterruptMarker, pushQueuedInputMarker, } from './loop/messages.js';
-import { publishFinalAnswer } from './loop/publication.js';
+import { buildModelMessages, evictPriorVisionShots, injectVisionFollowups, mergeToolCallDelta, pushManualInterruptMarker, pushAdvisorFollowUpMarker, pushQueuedInputMarker, } from './loop/messages.js';
 import { prepareModelRequest } from './loop/requestPreparation.js';
 import { executeToolBatch } from './loop/toolBatch.js';
 import { createToolExecutor } from './loop/toolExecutor.js';
@@ -11,14 +10,16 @@ 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';
@@ -36,12 +37,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';
@@ -55,6 +57,26 @@ import { hydrateSessionWorktree } from './tools/worktree/sessionWorktree.js';
 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) {
+    if (options.advisorFollowUp !== undefined)
+        return options.advisorFollowUp;
+    try {
+        return (await configService.advisor())?.enforcement === 'followup';
+    }
+    catch {
+        return false;
+    }
+}
+function answerTextStarted(text) {
+    const lead = text.trimStart();
+    if (lead.length < '<think>'.length && '<think>'.startsWith(lead.toLowerCase()))
+        return false;
+    return stripThinkBlocks(text).length > 0;
+}
 /**
  * 执行一次"用户输入 → 模型回答完成"的完整流程。
  *
@@ -128,7 +150,13 @@ export async function* runQuery(userInput, options) {
     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({
@@ -148,35 +176,12 @@ export async function* runQuery(userInput, options) {
         },
         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 },
@@ -222,20 +227,20 @@ export async function* runQuery(userInput, options) {
         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 = () => {
-        const advisorAvailable = currentEffectiveToolSet.names.has('Advisor');
+        const advisorAvailable = currentEffectiveToolSet.names.has('Advisor') && options.advisorReminders !== false;
         const parts = [
             transientFor(activeTools),
             coordinationText,
@@ -245,7 +250,11 @@ export async function* runQuery(userInput, options) {
                 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 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。'
                 : '',
@@ -256,8 +265,7 @@ export async function* runQuery(userInput, options) {
                 ? `上一次模型响应没有可交付正文（${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');
     };
@@ -524,7 +532,7 @@ export async function* runQuery(userInput, options) {
             replaceHistory,
             buildRequestTransientContext: (tools) => {
                 currentEffectiveToolSet = tools;
-                advisorCoordinator.setAvailable(tools.names.has('Advisor'));
+                advisorNudge.setAvailable(tools.names.has('Advisor') && options.advisorReminders !== false);
                 lastRequestTransientContext = buildRequestTransientContext();
                 return lastRequestTransientContext;
             },
@@ -545,7 +553,7 @@ export async function* runQuery(userInput, options) {
         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(reason) {
+        function* preparationNotice(reason) {
             const message = {
                 role: 'system',
                 content: answerPreparationNotice(reason),
@@ -556,6 +564,9 @@ export async function* runQuery(userInput, options) {
             };
             history.push(message);
             yield { type: 'injected_message', message };
+        }
+        function* retireDraft(reason) {
+            yield* preparationNotice(reason);
             if (reason !== 'interrupted')
                 yield { type: 'assistant_draft_discarded', reason, textLength: 0 };
         }
@@ -568,22 +579,80 @@ export async function* runQuery(userInput, options) {
         let reasoningContent = '';
         let reasoningString = '';
         const reasoningDetails = [];
+        /** Visible text is never retracted: whatever already streamed live is
+         * committed before the turn moves on (interruption, error, new messages). */
+        function* commitLiveAnswer(presentation) {
+            const message = {
+                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）。
          * 'length' = 被 provider 因 max_tokens 截断 —— 收尾时据此给 warning，
          * 避免「半截答案」被静默当成正常 end_turn。
          */
         let lastFinishReason = '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) {
+            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,
@@ -594,6 +663,8 @@ export async function* runQuery(userInput, options) {
             })) {
                 if (ev.type === 'text_delta') {
                     assistantText += ev.delta;
+                    if (liveFinal)
+                        yield* releaseLive();
                 }
                 else if (ev.type === 'tool_call_delta') {
                     mergeToolCallDelta(toolCallsByIndex, ev);
@@ -648,14 +719,19 @@ export async function* runQuery(userInput, options) {
         catch (e) {
             trace('model_error');
             if (e.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' };
@@ -695,7 +771,12 @@ export async function* runQuery(userInput, options) {
                 // reactive 没压动或未恢复 → 退回正常错误路径
             }
             // 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.message}`,
@@ -704,8 +785,20 @@ export async function* runQuery(userInput, options) {
             return;
         }
         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' };
@@ -725,35 +818,11 @@ export async function* runQuery(userInput, options) {
                 toolCallsByIndex.push(...dense);
             }
         }
-        // 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 = {
             role: 'assistant',
@@ -768,29 +837,41 @@ export async function* runQuery(userInput, options) {
         };
         // 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 (!diagramPreparationAttempted &&
+            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 (!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 (!askCorrectionAttempted &&
+            if (!liveStarted &&
+                !askCorrectionAttempted &&
                 runtimeContext.interactiveAsk &&
                 currentEffectiveToolSet.names.has('AskUserQuestion') &&
                 needsInteractiveQuestion(stripThinkBlocks(assistantText)) &&
@@ -802,7 +883,7 @@ export async function* runQuery(userInput, options) {
             const emptyResponse = stripThinkBlocks(assistantText).length === 0;
             const coordination = 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');
@@ -813,13 +894,18 @@ export async function* runQuery(userInput, options) {
                 ...(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;
             }
             // A model occasionally writes a path/link in prose and stops without formally
             // presenting it. Give it one model-only corrective pass; the reminder is
             // transient and therefore never pollutes persisted conversation history.
-            if (!emptyResponse &&
+            if (!liveStarted &&
+                !emptyResponse &&
                 formalDeliveryRequired &&
                 !resultPresented &&
                 !deliveryCorrectionAttempted &&
@@ -828,37 +914,21 @@ export async function* runQuery(userInput, options) {
                 yield* retireDraft('formal_delivery');
                 continue;
             }
-            const deliveryCheckpoint = emptyResponse || options.advisorCheckpoints === false
-                ? { allow: true }
-                : 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
@@ -886,86 +956,26 @@ export async function* runQuery(userInput, options) {
                 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;
-                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)
+                if (!liveStarted)
                     yield { type: 'text', delta: assistantText };
                 yield {
                     type: 'assistant_message',
                     message: assistantMsg,
                 };
-                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 宿主会拿到半截答案却以为成功。
@@ -1077,7 +1087,7 @@ export async function* runQuery(userInput, options) {
             runtimeContext,
             toolCallContext,
             currentEffectiveToolSet,
-            advisorCoordinator,
+            advisorNudge,
             stallGuard,
             modelEnvironmentCwd,
             observedRuleScopes,
@@ -1090,9 +1100,7 @@ export async function* runQuery(userInput, options) {
         // 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 }) {
-            if (tc.function.name !== 'Advisor' && tc.function.name !== 'AdvisorDecision') {
-                advisorCoordinator.observeToolResult(tc, result, advisorSemanticsFor(tc, toolCallContext, currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name), { treatVerificationAsReadOnly: true }));
-            }
+            advisorNudge.observeToolResult(tc, result, advisorSemanticsFor(tc, 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);
             }
@@ -1108,6 +1116,7 @@ export async function* runQuery(userInput, options) {
                 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);
             // 超大结果先归档再压缩：归档失败时保留原文，绝不因为磁盘问题破坏上下文。
@@ -1129,9 +1138,10 @@ export async function* runQuery(userInput, options) {
                 ? { ...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,
@@ -1139,8 +1149,6 @@ export async function* runQuery(userInput, options) {
                 tool_call_id: tc.id,
                 tool_result_policy: policy,
                 ...(!result.ok && result.disposition === 'deferred' ? { toolResultDisposition: 'deferred' } : {}),
-                ...(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(),
@@ -1182,7 +1190,7 @@ export async function* runQuery(userInput, options) {
                 ? '同一问题两次尝试失败，请停止原样重试；顾问可用时，继续解决或交付前先咨询，由主 Agent 自行核验和决策。只读诊断仍可继续。'
                 : '检测到连续工具轮次没有产生新文本或新结果；请切换路径或咨询 Advisor。';
             if (stall.reason !== 'repeated_failure')
-                advisorCoordinator.notifyStalled(stall.signature ?? stall.reason);
+                advisorNudge.notifyStalled(stall.signature ?? stall.reason ?? 'no_progress');
             yield { type: 'warning', message };
         }
         // 关键节点截图回填：把工具附带的实况截图作为一条带图 user 消息喂给（视觉）模型自我核验，