minimal-agent 0.18.9 → 0.18.11

package/src/loop.js

@@ -1,174 +1,60 @@
+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 { prepareModelRequest } from './loop/requestPreparation.js';
+import { executeToolBatch } from './loop/toolBatch.js';
+import { createToolExecutor } from './loop/toolExecutor.js';
+import { advisorSemanticsFor } from './loop/toolSemantics.js';
+export { expectsFormalDelivery } from './loop/deliveryIntent.js';
+export { buildModelMessages, SYSTEM_REMINDER_CLOSE, SYSTEM_REMINDER_OPEN, VISION_SHOT_MARKER, } from './loop/messages.js';
+export { friendlyToolDescription } from './loop/toolPresentation.js';
+export { advisorSemanticsFor } from './loop/toolSemantics.js';
 /**
- * ============================================================
- *  src/loop.ts —— Agent 主循环（query loop）
- * ------------------------------------------------------------
- *  这是整个 agent 的"心脏"。一句话描述：
- *
- *    用户说话 → 调 LLM → LLM 想调工具就执行工具 → 把结果喂回去 → 继续调 LLM →
- *    直到 LLM 不再调工具，输出最终回答。
- *
- *  和 kakadeai 主仓库 query.ts 用同样的 AsyncGenerator 模式：
- *    - 函数是 async function*，可以 yield 各种事件给 UI
- *    - UI 通过 for await 拿到事件，把它们映射到 React state
- *
- *  循环每轮（turn）做的事：
- *    a. 自动压缩检查（防止 context 撑爆）
- *    b. 调 LLM，把流式响应组装成完整的 assistant message
- *    c. 如果 assistant 不调工具 → 结束，return
- *    d. 否则并行执行所有工具调用（OpenAI 协议要求 tool 消息按 tool_calls 顺序回填）
- *    e. 进入下一轮（让模型看到 tool_result 后继续推理）
- *
- *  失控保护：maxTurns（默认 200）。
- *  中断支持：AbortSignal 透传到 chat() 和 tool.call()。
- *
- *  "工作过程显示"事件：
- *    - stage_change：thinking / streaming / tool_executing / compacting
- *    - reasoning：思维链流式增量（仅字符串型 field）
- * ============================================================
+ * 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.
+ * See ./loop/README.md for phase ownership and invariants.
  */
 import crypto from 'node:crypto';
-import { answerPreparationNotice } from './runtime/answerPreparation.js';
-import { finalAnswerMessages } from './runtime/finalAnswer.js';
-import { resolveOutputContract, toolsForResponsePhase } from './runtime/outputContract.js';
-import { needsDiagramPreparation, visualPresentation } from './prompts/visualPresentation.js';
-import { createLifecycleTrace } from './runtime/lifecycleTrace.js';
-import { conciseToolPath } from './runtime/toolDisplay.js';
-import { dirname, resolve } from 'node:path';
-import { loadProjectPromptInstructions } from './prompts/projectInstructions.js';
-import { resolveToolPath } from './tools/shared/fileUtils.js';
-import { invocationInstructions, invocationToolAllowed } from './runtime/invocationPolicy.js';
-import { needsInteractiveQuestion } from './tools/ask/routing.js';
-import { autoCompactIfNeeded, getCompactThreshold, shouldAutoCompact } from './context/compact.js';
+import { resolve } from 'node:path';
+import { AdvisorCoordinator } from './advisor/advisorCoordinator.js';
+import { collectReviewContext } from './advisor/reviewContext.js';
+import { configService } from './config/configService.js';
+import { buildContextBudgetPlan } from './context/budgetPlan.js';
+import { getCompactThreshold } from './context/compact.js';
+import { assembleContextBundle, contextFragment, resizeContextBundle } from './context/contextBundle.js';
+import { expireOldEntries, getToolResultPolicy, incrementTurn, microCompact, reclaimOldToolResults, resetCacheEdits, } from './context/microCompactLite.js';
 import { createConversationOptimizer } from './context/optimizeConversation.js';
-import { microCompact, incrementTurn, expireOldEntries, reclaimOldToolResults, resetCacheEdits, getToolResultPolicy, } from './context/microCompactLite.js';
-import { isPromptTooLongError, reactiveCompactIfApplicable, } from './context/reactiveCompact.js';
-import { snipCompactIfNeeded } from './context/snipCompact.js';
+import { isPromptTooLongError, reactiveCompactIfApplicable } from './context/reactiveCompact.js';
+import { countMessagesTokens, estimateToolsTokens } from './context/tokenCounter.js';
 import { archiveToolResult } from './context/toolResultArchive.js';
-import { countMessagesTokens, countTextTokens, estimateToolsTokens, } from './context/tokenCounter.js';
-import { buildContextBudgetPlan, fitToolsForEmergency } from './context/budgetPlan.js';
-import { assembleContextBundle, contextFragment, resizeContextBundle } from './context/contextBundle.js';
+import { validateFinalClaims } from './harness/claimValidation.js';
+import { EvidenceLedger } from './harness/evidenceLedger.js';
+import { StallGuard } from './harness/stallGuard.js';
 import { chat as defaultChat } from './llm/client.js';
 import { buildUserContent } from './multimodal.js';
-import { ALL_TOOLS, executeTool as defaultExecuteTool, getToolByName, getToolGateDetails, } from './tools/index.js';
-import { configService } from './config/configService.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 { 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 { filterToolsForProvider } from './team/toolPolicy.js';
+import { agentCoordinationContext, takeAgentNotifications } from './tools/agent/agentTaskService.js';
+import { needsInteractiveQuestion } from './tools/ask/routing.js';
 import { capabilityForToolName } from './tools/capabilities.js';
-import { createEffectiveToolSet } from './tools/effectiveToolSet.js';
 import { classifyComputerAutomationIntent } from './tools/computeruse/computerIntent.js';
 import { recordComputerUseExposure } from './tools/computeruse/telemetryLog.js';
-import { filterToolsForProvider } from './team/toolPolicy.js';
+import { createEffectiveToolSet } from './tools/effectiveToolSet.js';
+import { ALL_TOOLS, executeTool as defaultExecuteTool } from './tools/index.js';
+import { createReadBudget } from './tools/shared/readBudget.js';
 import { hydrateSessionWorktree } from './tools/worktree/sessionWorktree.js';
-import { capabilitiesForTools, enabledPolicyIds, } from './prompts/policyRegistry.js';
-import { EvidenceLedger } from './harness/evidenceLedger.js';
-import { StallGuard } from './harness/stallGuard.js';
-import { validateFinalClaims } from './harness/claimValidation.js';
-import { AdvisorCoordinator, } from './advisor/advisorCoordinator.js';
-import { toolEffectFor } from './tools/capabilities.js';
-import { isReadOnlyShellCommand, isVerificationShellCommand } from './tools/bash/semantics.js';
-import { collectReviewContext } from './advisor/reviewContext.js';
-import { createAgentRuntimeContext, } from './runtime/agentRuntimeContext.js';
 import { stripThinkBlocks } from './utils/stripThink.js';
-import { orderedPool } from './runtime/orderedPool.js';
-import { takeAgentNotifications, agentCoordinationContext } from './tools/agent/agentTaskService.js';
-import { delegationRuntimeGuidance } from './prompts/delegation.js';
-import { executionSegments } from './tools/executionSegments.js';
-import { acquireSubagentLease, normalizeWriteScopes } from './tools/agent/coordinator.js';
-const DELIVERY_ARTIFACT = '(?:文件|合同|协议|方案|文档|表格|报告|图片|图像|海报|幻灯片|PPT|PDF|代码|脚本|压缩包|网页|页面|HTML|DOCX|XLSX|CSV|ZIP)';
-const DELIVERY_ACTION = '(?:发送|(?<![开研])发|交付|提交|(?<!宣)传(?!统)|制作|生成|创建|导出|输出|修改|更新|完成|写|起草|做|设计|整理)';
-const ENGLISH_DELIVERY_ARTIFACT = '(?:file|contract|document|report|spreadsheet|workbook|slides?|presentation|pdf|image|code|script|archive|zip|html|webpage|website)';
-const ENGLISH_DELIVERY_ACTION = '(?:send|deliver|submit|provide|create|generate|export|update|modify|finish|produce|draft|write|make|build)';
-/** Whether this turn explicitly asks for a concrete artifact that should be formally delivered. */
-export function expectsFormalDelivery(input) {
-    // Questions about producing artifacts are not instructions to produce them.
-    // Evaluate clauses independently so “解释原因，然后生成报告” still delivers.
-    const clauses = input.split(/[。！？!?；;\n]|然后|随后|并且/).filter(Boolean);
-    return clauses.some(expectsDeliveryClause);
-}
-function expectsDeliveryClause(input) {
-    if (/为什么|为何|如何|怎么|怎样|是否|能否|能不能|不要|不必|无需|只(?:需|要)?(?:解释|分析|评估|讨论)|\b(?:why|how|whether|explain|analy[sz]e|discuss|do not|don't)\b/i.test(input))
-        return false;
-    const compact = input.replace(/\s+/g, '');
-    const chinese = new RegExp(`${DELIVERY_ACTION}(?:给)?我?.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}${DELIVERY_ACTION}(?:给)?我?|给我.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}给我`, 'i');
-    const english = new RegExp(`\\b${ENGLISH_DELIVERY_ACTION}\\b.{0,80}\\b${ENGLISH_DELIVERY_ARTIFACT}\\b|\\b${ENGLISH_DELIVERY_ARTIFACT}\\b.{0,80}\\b${ENGLISH_DELIVERY_ACTION}\\b`, 'i');
-    return chinese.test(compact) || english.test(input);
-}
-const DELIVERY_CORRECTION_REMINDER = `The user requested a concrete final deliverable, but no successful PresentResult call has been made.
-Do not repeat the answer or mention a path only. Call PresentResult now with the actual final files and/or final http(s) links.
-Submit only final outputs, never temporary scripts, unpacked assets, caches, or reference sources. If no valid result exists, explain that honestly without inventing one.`;
-/**
- * 每轮 LLM 请求都会带上工具 schema，但 countMessagesTokens 只数历史消息、
- * 漏了这部分 → 系统性低估。autoCompact 判定阈值时加上它才准。
- *
- * ⚠️ 必须懒求值而非模块顶层求值：Agent 工具引入了 tools/index → agent → loop →
- * tools/index 的模块环，若从 tools/index 一侧先进入，顶层求值 ALL_TOOLS 时它还在
- * TDZ（临时死区），启动即 ReferenceError。函数体内访问时模块图早已初始化完毕。
- */
-/**
- * 本轮**真正发出去的**工具 schema 估算 token 数。
- *
- * 曾经这里数的是 `ALL_TOOLS`，那是错的：每回合发给模型的是 `activeTools`，
- * 会被 `allowedTools`（工作流步骤 / 子 agent 收窄）、`subagents.enabled`、
- * `computerRun` 是否注入等条件过滤掉一部分。ComputerUse 单个工具的 schema
- * 实测就有 ~5800 token（全量 ~18000 的三分之一），在没暴露它的会话里照样
- * 被计入压缩阈值 → **压缩提前触发**；被 `allowed_tools` 收窄到两三个工具的
- * 子 agent 偏差更大。
- *
- * 缓存必须按工具集**键控**：模块级单值缓存配上按回合变化的工具集，会让所有
- * 后续回合都拿到第一回合那个数字 —— 比不缓存更糟，因为它错得很稳定。
- */
-const toolsSchemaTokensCache = new Map();
-function getToolsSchemaTokens(tools, signature) {
-    const key = signature ?? tools.map((t) => t.name).join(',');
-    let cached = toolsSchemaTokensCache.get(key);
-    if (cached === undefined) {
-        cached = estimateToolsTokens(tools);
-        toolsSchemaTokensCache.set(key, cached);
-    }
-    return cached;
-}
 /** 主工具循环的默认轮数上限。 */
 export const DEFAULT_MAX_TURNS = 200;
-export function advisorSemanticsFor(call, context, tool, 
-// 默认 false：只有 advisor 检查点/记账（beforeTool、observeToolResult、
-// 持久化的 advisorMutatesWorkspace 标注）才传 true。工作区租约判定
-// （needsWorkspaceLease）必须保持严格定义不受影响——验证类命令仍可能写
-// 构建产物/缓存，并发场景下让它绕开租约会重新引入竞态。
-opts) {
-    const definition = tool ?? getToolByName(call.function.name);
-    const gate = context ? getToolGateDetails(call.function.name, call.function.arguments, context) : undefined;
-    // Reuse the tool's side-effect contract, including shell/scripts, Trash and
-    // generation tools. Shell tools refine their generic writable declaration
-    // using the actual command; the same result is also used by the host gate.
-    let isReadOnly = gate?.isReadOnly ?? definition?.isReadOnly ?? false;
-    if (call.function.name === 'Agent') {
-        try {
-            const args = JSON.parse(call.function.arguments || '{}');
-            isReadOnly = !args.resume_agent_id && (args.agent_type ?? 'explore') === 'explore';
-        }
-        catch {
-            isReadOnly = false;
-        }
-    }
-    if (call.function.name === 'Bash' || call.function.name === 'PowerShell') {
-        try {
-            const input = JSON.parse(call.function.arguments || '{}');
-            if (typeof input.command === 'string') {
-                // 跑测试/构建/lint 只是核对现状，不该被当成"开始实施改动"而白白烧掉
-                // pre-execution 检查点——即使它们可能写构建产物/缓存，不满足
-                // isReadOnlyShellCommand 的并发安全定义（见 opts 注释，那个场景仍要严格）。
-                isReadOnly =
-                    isReadOnlyShellCommand(input.command) ||
-                        (opts?.treatVerificationAsReadOnly === true &&
-                            isVerificationShellCommand(input.command));
-            }
-        }
-        catch {
-            // Malformed input is left writable; normal tool validation reports it.
-            isReadOnly = false;
-        }
-    }
-    const mutatesWorkspace = toolEffectFor(call.function.name, isReadOnly) === 'execution';
-    return { mutatesWorkspace };
-}
 /**
  * 执行一次"用户输入 → 模型回答完成"的完整流程。
  *
@@ -180,25 +66,24 @@ export async function* runQuery(userInput, options) {
     // Never carry a prior turn's base64 image into a new user request.
     evictPriorVisionShots(history);
     const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
-    const inferredDesktop = options.browserRun?.supervised === true ||
-        options.browserRun?.viewer === 'desktop';
-    const baseRuntimeContext = options.runtimeContext ?? createAgentRuntimeContext({
-        surface: inferredDesktop ? 'desktop' : 'headless',
-        ...(inferredDesktop ? { host: 'desktop' } : {}),
-        profile: 'main',
-        cwd: process.cwd(),
-        workspaceId: options.memoryContext?.workspaceId,
-        sessionId: options.memoryContext?.sessionId,
-        owner: options.memoryContext?.access !== 'denied' ? 'local-owner' : 'untrusted',
-        memoryAccess: options.memoryContext?.access ?? 'denied',
-        interactiveAsk: false,
-        browser: options.browserRun,
-        computer: options.computerRun,
-        computerIntervention: options.computerIntervention,
-        toolGate: options.toolGate,
-    });
-    const computerIntent = baseRuntimeContext.computerIntent
-        ?? classifyComputerAutomationIntent(userInput, sessionState?.computerAutomation);
+    const inferredDesktop = options.browserRun?.supervised === true || options.browserRun?.viewer === 'desktop';
+    const baseRuntimeContext = options.runtimeContext ??
+        createAgentRuntimeContext({
+            surface: inferredDesktop ? 'desktop' : 'headless',
+            ...(inferredDesktop ? { host: 'desktop' } : {}),
+            profile: 'main',
+            cwd: process.cwd(),
+            workspaceId: options.memoryContext?.workspaceId,
+            sessionId: options.memoryContext?.sessionId,
+            owner: options.memoryContext?.access !== 'denied' ? 'local-owner' : 'untrusted',
+            memoryAccess: options.memoryContext?.access ?? 'denied',
+            interactiveAsk: false,
+            browser: options.browserRun,
+            computer: options.computerRun,
+            computerIntervention: options.computerIntervention,
+            toolGate: options.toolGate,
+        });
+    const computerIntent = baseRuntimeContext.computerIntent ?? classifyComputerAutomationIntent(userInput, sessionState?.computerAutomation);
     const runtimeContext = createAgentRuntimeContext({
         ...baseRuntimeContext,
         computerIntent,
@@ -220,7 +105,9 @@ export async function* runQuery(userInput, options) {
     const observedRuleScopes = new Map();
     const pendingRuleScopes = new Set();
     const transientFor = (tools) => {
-        const opaque = [options.transientContext?.trim(), invocationInstructions(options.invocationPolicy)].filter(Boolean).join('\n\n');
+        const opaque = [options.transientContext?.trim(), invocationInstructions(options.invocationPolicy)]
+            .filter(Boolean)
+            .join('\n\n');
         const bundle = currentTransientBundle;
         if (!bundle)
             return opaque;
@@ -231,9 +118,7 @@ export async function* runQuery(userInput, options) {
             transientContext: opaque,
         });
         const availableForBundle = Math.max(0, basePlan.inputLimit - basePlan.historyTokens - basePlan.toolTokens - basePlan.transientTokens);
-        const selected = availableForBundle >= bundle.diagnostics.usedTokens
-            ? bundle
-            : resizeContextBundle(bundle, availableForBundle);
+        const selected = availableForBundle >= bundle.diagnostics.usedTokens ? bundle : resizeContextBundle(bundle, availableForBundle);
         advisorContextBundle = selected;
         return [selected.text, opaque].filter(Boolean).join('\n\n');
     };
@@ -255,18 +140,43 @@ export async function* runQuery(userInput, options) {
     const toolCallContext = {
         output,
         availableToolNames: () => currentEffectiveToolSet.names,
-        executionServices: { ...options.executionServices, executeTool: executeToolFn, chat: chatFn, invocationPolicy: options.invocationPolicy },
+        executionServices: {
+            ...options.executionServices,
+            executeTool: executeToolFn,
+            chat: chatFn,
+            invocationPolicy: options.invocationPolicy,
+        },
         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 ?? [])])],
+            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 ?? []),
+                ]),
+            ],
         }),
         // Statistics only; consultations have no per-turn quota.
         advisorCalls: { used: 0 },
@@ -296,10 +206,10 @@ export async function* runQuery(userInput, options) {
     // 传入数组时严格按数组过滤，[] 表示本轮不下发任何工具。
     // 同时约束模型可见工具和本循环实际执行的工具。
     const hostTools = filterToolsForProvider(options.availableTools ?? ALL_TOOLS, provider);
-    const availableTools = hostTools.filter((tool) => invocationToolAllowed(tool.name, options.invocationPolicy)
-        && (tool.name !== 'Agent' || subagents.enabled)
-        && (tool.name !== 'ComputerUse'
-            || (runtimeContext.computer !== undefined && runtimeContext.computerIntent?.needed === true)));
+    const availableTools = hostTools.filter((tool) => invocationToolAllowed(tool.name, options.invocationPolicy) &&
+        (tool.name !== 'Agent' || subagents.enabled) &&
+        (tool.name !== 'ComputerUse' ||
+            (runtimeContext.computer !== undefined && runtimeContext.computerIntent?.needed === true)));
     const effectiveToolSet = createEffectiveToolSet({
         availableTools,
         runtime: runtimeContext,
@@ -307,10 +217,10 @@ export async function* runQuery(userInput, options) {
         requiredNames: options.requiredTools,
     });
     const activeTools = effectiveToolSet.tools;
-    const formalDeliveryRequired = explicitFileDeliveryRequested
-        && runtimeContext.profile === 'main'
-        && options.invocationPolicy?.delivery !== 'caller'
-        && effectiveToolSet.names.has('PresentResult');
+    const formalDeliveryRequired = explicitFileDeliveryRequested &&
+        runtimeContext.profile === 'main' &&
+        options.invocationPolicy?.delivery !== 'caller' &&
+        effectiveToolSet.names.has('PresentResult');
     let currentEffectiveToolSet = effectiveToolSet;
     const advisorCoordinator = new AdvisorCoordinator({
         history,
@@ -329,28 +239,37 @@ export async function* runQuery(userInput, options) {
         const parts = [
             transientFor(activeTools),
             coordinationText,
-            delegationRuntimeGuidance({ available: runtimeContext.profile === 'main' && currentEffectiveToolSet.names.has('Agent'),
-                maxConcurrent: subagents.maxConcurrent, callsUsed: toolCallContext.agentCalls?.used ?? 0,
-                maxCalls: toolCallContext.agentCalls?.max ?? 0 }),
+            delegationRuntimeGuidance({
+                available: runtimeContext.profile === 'main' && currentEffectiveToolSet.names.has('Agent'),
+                maxConcurrent: subagents.maxConcurrent,
+                callsUsed: toolCallContext.agentCalls?.used ?? 0,
+                maxCalls: toolCallContext.agentCalls?.max ?? 0,
+            }),
             diagramPreparationAttempted ? visualPresentation(output) : '',
-            delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
-            askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
-            emptyResponseRecoveryAttempted ? `上一次模型响应没有可交付正文（${emptyResponseRecoveryReason}）。请基于已有历史和工具结果继续完成任务：信息充分则给出实质结论，不充分则继续必要操作或明确缺口。不要重复已经完成的调查或有副作用的操作；不要把未完成的任务说成完成。已有顾问意见继续有效，无需仅因恢复而再次咨询。` : '',
+            delegationCorrectionAttempted
+                ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。'
+                : '',
+            askCorrectionAttempted
+                ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。'
+                : '',
+            emptyResponseRecoveryAttempted
+                ? `上一次模型响应没有可交付正文（${emptyResponseRecoveryReason}）。请基于已有历史和工具结果继续完成任务：信息充分则给出实质结论，不充分则继续必要操作或明确缺口。不要重复已经完成的调查或有副作用的操作；不要把未完成的任务说成完成。已有顾问意见继续有效，无需仅因恢复而再次咨询。`
+                : '',
             deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
             advisorAvailable ? advisorCoordinator.transientReminder() : '',
-            advisorAvailable
-                ? advisorCoordinator.usageLine(toolCallContext.advisorCalls.used)
-                : '',
+            advisorAvailable ? advisorCoordinator.usageLine(toolCallContext.advisorCalls.used) : '',
         ];
         return parts.filter(Boolean).join('\n\n');
     };
     let lastRequestTransientContext = [options.transientBundle?.text, options.transientContext]
-        .filter(Boolean).join('\n\n');
+        .filter(Boolean)
+        .join('\n\n');
     const evidenceLedger = new EvidenceLedger();
     const stallGuard = new StallGuard();
     const harnessDiagnostics = (stopReason) => ({
         promptVersion: 'minimal-agent:prompt:v2',
-        basePromptHash: crypto.createHash('sha256')
+        basePromptHash: crypto
+            .createHash('sha256')
             .update(history[0]?.role === 'system' ? history[0].content : '')
             .digest('hex'),
         enabledPolicyIds: enabledPolicyIds({
@@ -360,9 +279,11 @@ export async function* runQuery(userInput, options) {
             capabilities: capabilitiesForTools(currentEffectiveToolSet.tools),
             toolNames: currentEffectiveToolSet.names,
         }),
-        enabledCapabilities: [...new Set(currentEffectiveToolSet.tools
+        enabledCapabilities: [
+            ...new Set(currentEffectiveToolSet.tools
                 .map((tool) => capabilityForToolName(tool.name))
-                .filter((capability) => Boolean(capability)))],
+                .filter((capability) => Boolean(capability))),
+        ],
         effectiveToolSetSignature: currentEffectiveToolSet.signature,
         tokenBudget: buildContextBudgetPlan({
             provider,
@@ -403,8 +324,7 @@ export async function* runQuery(userInput, options) {
             message: `未作为图片附加：${skipped.source}（${skipped.reason}），已按普通文本处理。`,
         };
     }
-    let visionRequiredThisTurn = Array.isArray(userContent)
-        && userContent.some((part) => part.type === 'image_url' || part.type === 'video_url');
+    let visionRequiredThisTurn = Array.isArray(userContent) && userContent.some((part) => part.type === 'image_url' || part.type === 'video_url');
     if (visionRequiredThisTurn && provider.supportsVision === false) {
         yield {
             type: 'error',
@@ -463,14 +383,15 @@ export async function* runQuery(userInput, options) {
     };
     const optimizationEvents = [];
     toolCallContext.optimizeConversation = createConversationOptimizer({
-        history, provider,
+        history,
+        provider,
         // This additional model call must contribute to the turn's resource ledger,
         // without replacing the main model's context/cache usage measurements.
         chat: async function* (args) {
             turnUsage.totalCalls += 1;
             for await (const event of chatFn(args)) {
-                if (event.type === 'done'
-                    && (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number')) {
+                if (event.type === 'done' &&
+                    (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number')) {
                     turnUsage.reportedCalls += 1;
                     turnUsage.inputTokens += event.promptTokens ?? 0;
                     turnUsage.outputTokens += event.outputTokens ?? 0;
@@ -479,8 +400,9 @@ export async function* runQuery(userInput, options) {
             }
         },
         promptCache: options.promptCache,
-        replaceHistory, hasQueuedInput: options.hasQueuedInput,
-        onCompacted: event => optimizationEvents.push(event),
+        replaceHistory,
+        hasQueuedInput: options.hasQueuedInput,
+        onCompacted: (event) => optimizationEvents.push(event),
     });
     const interruption = () => {
         if (options.hasQueuedInput?.()) {
@@ -501,19 +423,38 @@ export async function* runQuery(userInput, options) {
         }
         modelEnvironmentCwd = nextEnvironmentCwd;
         try {
-            const rules = await loadProjectPromptInstructions(modelEnvironmentCwd) ?? '';
+            const rules = (await loadProjectPromptInstructions(modelEnvironmentCwd)) ?? '';
             observedRuleScopes.set(resolve(modelEnvironmentCwd), rules);
             for (const scope of new Set([...observedRuleScopes.keys(), ...pendingRuleScopes])) {
                 if (scope !== resolve(modelEnvironmentCwd))
-                    observedRuleScopes.set(scope, await loadProjectPromptInstructions(scope) ?? '');
+                    observedRuleScopes.set(scope, (await loadProjectPromptInstructions(scope)) ?? '');
             }
             pendingRuleScopes.clear();
-            const mergedRules = await loadProjectPromptInstructions(modelEnvironmentCwd, [...observedRuleScopes.keys()]) ?? '';
+            const mergedRules = (await loadProjectPromptInstructions(modelEnvironmentCwd, [...observedRuleScopes.keys()])) ?? '';
             currentTransientBundle = assembleContextBundle([
-                ...(options.transientBundle?.fragments ?? []).filter(f => f.id !== 'project.instructions' && f.id !== 'runtime.execution-environment'),
-                contextFragment({ id: 'runtime.execution-environment', kind: 'runtime', authority: 'host', priority: 100, required: true, atomic: true,
-                    content: `当前有效执行目录：${modelEnvironmentCwd}。此宿主快照替换旧执行目录；项目规则以本次快照为准，旧历史中的版本不再生效。${rules ? '' : '当前目录及父目录没有适用的项目规则文件，旧规则不得恢复。'}工具权限仍以本次有效工具集和宿主闸门为准。` }),
-                ...(mergedRules ? [contextFragment({ id: 'project.instructions', kind: 'project', authority: 'constraint', priority: 90, required: true, atomic: true, content: mergedRules })] : []),
+                ...(options.transientBundle?.fragments ?? []).filter((f) => f.id !== 'project.instructions' && f.id !== 'runtime.execution-environment'),
+                contextFragment({
+                    id: 'runtime.execution-environment',
+                    kind: 'runtime',
+                    authority: 'host',
+                    priority: 100,
+                    required: true,
+                    atomic: true,
+                    content: `当前有效执行目录：${modelEnvironmentCwd}。此宿主快照替换旧执行目录；项目规则以本次快照为准，旧历史中的版本不再生效。${rules ? '' : '当前目录及父目录没有适用的项目规则文件，旧规则不得恢复。'}工具权限仍以本次有效工具集和宿主闸门为准。`,
+                }),
+                ...(mergedRules
+                    ? [
+                        contextFragment({
+                            id: 'project.instructions',
+                            kind: 'project',
+                            authority: 'constraint',
+                            priority: 90,
+                            required: true,
+                            atomic: true,
+                            content: mergedRules,
+                        }),
+                    ]
+                    : []),
             ], options.transientBundle?.diagnostics.budgetTokens);
         }
         catch (error) {
@@ -523,12 +464,18 @@ export async function* runQuery(userInput, options) {
         }
         const handoff = options.agentHandoff?.current();
         if (handoff && handoff.kind !== 'help') {
-            yield { type: 'turn_done', completionStatus: handoff.kind === 'result' ? 'completed' : 'delivery_incomplete',
+            yield {
+                type: 'turn_done',
+                completionStatus: handoff.kind === 'result' ? 'completed' : 'delivery_incomplete',
                 warning: handoff.kind === 'blocked' ? '子任务已交回主 Agent 接力' : undefined,
-                usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+                usage: {
+                    ...turnUsage,
+                    trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+                },
+            };
             return;
         }
-        history.push(...(options.takePendingMessages?.() ?? []), ...await takeAgentNotifications(toolCallContext));
+        history.push(...(options.takePendingMessages?.() ?? []), ...(await takeAgentNotifications(toolCallContext)));
         if (runtimeContext.profile === 'main')
             coordinationText = (await agentCoordinationContext(toolCallContext)).text;
         incrementTurn(sessionState?.microCompact);
@@ -562,174 +509,51 @@ export async function* runQuery(userInput, options) {
             }
             return;
         }
-        // 2. 自动压缩（判据 = max(上一轮真实 usage, 历史估算 + 工具 schema)，
-        //    阈值 provider 无关、按 contextWindow × compactRatio 比例触发）
-        let requestTransientContext = buildRequestTransientContext();
-        lastRequestTransientContext = requestTransientContext;
-        const preCompactBudget = buildContextBudgetPlan({
-            provider,
-            history,
-            tools: activeTools,
-            transientContext: requestTransientContext,
-        });
-        if (preCompactBudget.overBudget || lastPromptTokens !== undefined) {
-            try {
-                const compactOptions = {
-                    actualPromptTokens: lastPromptTokens,
-                    toolsTokens: getToolsSchemaTokens(activeTools, effectiveToolSet.signature),
-                    transientTokens: countTextTokens(requestTransientContext),
-                    // cacheEdits 判据校正：本地 history 未瘦身，扣掉服务端已删部分的估算，
-                    // 防止虚高估算劫持 Math.max 导致压缩过早触发（压缩会重建整个前缀缓存）。
-                    ...(cacheEditsMode && sessionState?.microCompact
-                        ? { serverDeletedTokens: sessionState.microCompact.cacheEdits.activeDeletedTokens }
-                        : {}),
-                    signal,
-                    promptCache: options.promptCache,
-                    chat: chatFn,
-                };
-                if (shouldAutoCompact(history, provider, compactOptions)) {
-                    yield { type: 'compact_start' };
-                    yield { type: 'stage_change', stage: 'compacting' };
-                }
-                const compact = await autoCompactIfNeeded(history, provider, compactOptions);
-                if (compact.compacted) {
-                    replaceHistory(compact.messages);
-                    yield {
-                        type: 'compact_done',
-                        before: compact.before,
-                        after: compact.after,
-                        trigger: 'threshold',
-                        mode: compact.mode,
-                        degraded: compact.degraded,
-                        ...(compact.fallbackReason ? { fallbackReason: compact.fallbackReason } : {}),
-                        ...(compact.messagesRemoved !== undefined ? { messagesRemoved: compact.messagesRemoved } : {}),
-                        ...(compact.tokensFreed !== undefined ? { tokensFreed: compact.tokensFreed } : {}),
-                    };
-                    yield { type: 'stage_change', stage: 'thinking' };
-                }
-            }
-            catch (e) {
-                if (signal?.aborted || e.name === 'AbortError') {
-                    yield interruption();
-                    return;
-                }
-                // 压缩失败不要让整个对话挂掉：先 snip 砍最老消息释放空间再继续。
-                let recovered = false;
-                try {
-                    const before = countMessagesTokens(history);
-                    const snipped = snipCompactIfNeeded(history, { force: true, snipPercent: 0.3 });
-                    if (snipped.messagesRemoved > 0) {
-                        replaceHistory(snipped.messages);
-                        recovered = true;
-                        yield {
-                            type: 'compact_done',
-                            before,
-                            after: countMessagesTokens(history),
-                            trigger: 'threshold',
-                            mode: 'snip-fallback',
-                            degraded: true,
-                            fallbackReason: 'llm-error',
-                            messagesRemoved: snipped.messagesRemoved,
-                            tokensFreed: snipped.tokensFreed,
-                        };
-                    }
-                }
-                catch {
-                    /* snip 也失败 → 真的只能硬上 */
-                }
-                if (!recovered) {
-                    // 事件是 provider 原始报错唯一该去的地方：只到 stderr / UI，不进 history、
-                    // 不落盘、不会在后续轮次重新发给模型（compact.ts 里那条降级消息因此保持无错误体）。
-                    yield {
-                        type: 'error',
-                        error: `自动压缩失败，规则式截断也未能释放空间；已继续尝试回答：${e.message}`,
-                        code: 'compact_failed',
-                    };
-                }
-            }
-        }
-        // Re-open transient capacity after compaction. If the compacted tail is still
-        // too large, trim old history before sacrificing any model-visible ability.
-        requestTransientContext = buildRequestTransientContext();
-        lastRequestTransientContext = requestTransientContext;
-        let postCompactBudget = buildContextBudgetPlan({
-            provider,
+        const prepared = yield* prepareModelRequest({
             history,
-            tools: activeTools,
-            transientContext: requestTransientContext,
-        });
-        if (postCompactBudget.overBudget) {
-            const before = countMessagesTokens(history);
-            const snipped = snipCompactIfNeeded(history, { force: true, snipPercent: 0.3 });
-            if (snipped.messagesRemoved > 0) {
-                replaceHistory(snipped.messages);
-                yield {
-                    type: 'compact_done',
-                    before,
-                    after: countMessagesTokens(history),
-                    trigger: 'post-budget',
-                    mode: 'snip-fallback',
-                    degraded: true,
-                    fallbackReason: 'still-over-budget',
-                    messagesRemoved: snipped.messagesRemoved,
-                    tokensFreed: snipped.tokensFreed,
-                };
-                requestTransientContext = buildRequestTransientContext();
-                lastRequestTransientContext = requestTransientContext;
-                postCompactBudget = buildContextBudgetPlan({
-                    provider,
-                    history,
-                    tools: activeTools,
-                    transientContext: requestTransientContext,
-                });
-            }
-        }
-        const emergencyFit = fitToolsForEmergency({
             provider,
-            history,
-            tools: activeTools,
-            transientContext: requestTransientContext,
-            requiredNames: effectiveToolSet.requiredNames,
+            activeTools,
+            effectiveToolSet,
+            runtimeContext,
+            sessionState,
+            signal,
+            lastPromptTokens,
+            cacheEditsMode,
+            options,
+            chatFn,
+            replaceHistory,
+            buildRequestTransientContext: (tools) => {
+                currentEffectiveToolSet = tools;
+                advisorCoordinator.setAvailable(tools.names.has('Advisor'));
+                lastRequestTransientContext = buildRequestTransientContext();
+                return lastRequestTransientContext;
+            },
         });
-        currentEffectiveToolSet = emergencyFit.removedNames.length === 0
-            ? effectiveToolSet
-            : createEffectiveToolSet({
-                availableTools: emergencyFit.tools,
-                runtime: runtimeContext,
-                requiredNames: [...effectiveToolSet.requiredNames],
-            });
-        advisorCoordinator.setAvailable(currentEffectiveToolSet.names.has('Advisor'));
-        // Tool availability may change during emergency fitting. Rebuild dynamic
-        // guidance against the actual request boundary, then account for its size.
-        requestTransientContext = buildRequestTransientContext();
-        lastRequestTransientContext = requestTransientContext;
-        const finalRequestBudget = buildContextBudgetPlan({
-            provider, history, tools: currentEffectiveToolSet.tools,
-            transientContext: requestTransientContext,
-        });
-        if (emergencyFit.removedNames.length > 0) {
-            yield {
-                type: 'warning',
-                message: `当前模型窗口压力过高，本次请求临时省略工具 Schema：${emergencyFit.removedNames.join(', ')}；下一轮会重新评估并恢复。`,
-            };
+        if (prepared.kind === 'interrupted') {
+            yield interruption();
+            return;
         }
-        if (finalRequestBudget.overBudget) {
-            yield {
-                type: 'error',
-                error: `当前请求即使经过上下文降级仍需要约 ${finalRequestBudget.totalInputTokens} tokens，超过模型输入上限 ${finalRequestBudget.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
-                code: 'context_overflow',
-            };
+        if (prepared.kind === 'overflow') {
             yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('error') };
             return;
         }
+        const requestTransientContext = prepared.requestTransientContext;
+        currentEffectiveToolSet = prepared.currentEffectiveToolSet;
+        toolCallContext.reserveReadChars = createReadBudget(prepared.remainingTokens);
         // 3. 调 LLM 并组装 assistant 消息
         trace('model_start');
         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) {
-            const message = { role: 'system', content: answerPreparationNotice(reason), id: crypto.randomUUID(),
-                timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+            const message = {
+                role: 'system',
+                content: answerPreparationNotice(reason),
+                id: crypto.randomUUID(),
+                timestamp: Date.now(),
+                _ephemeral: true,
+                _uiProgress: true,
+            };
             history.push(message);
             yield { type: 'injected_message', message };
             if (reason !== 'interrupted')
@@ -765,12 +589,8 @@ export async function* runQuery(userInput, options) {
                 promptCache: options.promptCache,
                 visionPolicy: visionRequiredThisTurn ? 'required' : 'optional-history',
                 // cacheEdits 回收状态（同一会话级对象跨轮复用；compact 后由 resetCacheEdits 清空）
-                ...(cacheEditsMode && sessionState?.microCompact
-                    ? { cacheEdits: sessionState.microCompact.cacheEdits }
-                    : {}),
-                ...(options.responseFormat
-                    ? { responseFormat: options.responseFormat }
-                    : {}),
+                ...(cacheEditsMode && sessionState?.microCompact ? { cacheEdits: sessionState.microCompact.cacheEdits } : {}),
+                ...(options.responseFormat ? { responseFormat: options.responseFormat } : {}),
             })) {
                 if (ev.type === 'text_delta') {
                     assistantText += ev.delta;
@@ -908,14 +728,19 @@ export async function* runQuery(userInput, options) {
         // 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))) {
+        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) } });
+            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.
@@ -926,7 +751,9 @@ export async function* runQuery(userInput, options) {
                 if (JSON.parse(call.function.arguments).name === 'dynamic-ui')
                     diagramPreparationAttempted = true;
             }
-            catch { /* Ordinary tool validation reports malformed arguments. */ }
+            catch {
+                /* Ordinary tool validation reports malformed arguments. */
+            }
         }
         const assistantMsg = {
             role: 'assistant',
@@ -943,21 +770,31 @@ export async function* runQuery(userInput, options) {
         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 && !options.responseFormat
-                && runtimeContext.profile === 'main' && output.diagrams.length > 0
-                && currentEffectiveToolSet.names.has('Skill') && turn < maxTurns
-                && needsDiagramPreparation(assistantText, userInput)) {
+            if (!diagramPreparationAttempted &&
+                !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' }),
-                    } });
+                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;
             }
-            if (!askCorrectionAttempted && runtimeContext.interactiveAsk
-                && currentEffectiveToolSet.names.has('AskUserQuestion')
-                && needsInteractiveQuestion(stripThinkBlocks(assistantText)) && turn < maxTurns) {
+            if (!askCorrectionAttempted &&
+                runtimeContext.interactiveAsk &&
+                currentEffectiveToolSet.names.has('AskUserQuestion') &&
+                needsInteractiveQuestion(stripThinkBlocks(assistantText)) &&
+                turn < maxTurns) {
                 askCorrectionAttempted = true;
                 yield* retireDraft('interactive_question');
                 continue;
@@ -971,7 +808,10 @@ export async function* runQuery(userInput, options) {
                 yield* retireDraft('formal_delivery');
                 continue;
             }
-            const pendingMessages = [...(options.takePendingMessages?.() ?? []), ...await takeAgentNotifications(toolCallContext)];
+            const pendingMessages = [
+                ...(options.takePendingMessages?.() ?? []),
+                ...(await takeAgentNotifications(toolCallContext)),
+            ];
             if (pendingMessages.length) {
                 history.push(...pendingMessages);
                 continue;
@@ -979,10 +819,11 @@ export async function* runQuery(userInput, options) {
             // 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 && formalDeliveryRequired
-                && !resultPresented
-                && !deliveryCorrectionAttempted
-                && turn < maxTurns) {
+            if (!emptyResponse &&
+                formalDeliveryRequired &&
+                !resultPresented &&
+                !deliveryCorrectionAttempted &&
+                turn < maxTurns) {
                 deliveryCorrectionAttempted = true;
                 yield* retireDraft('formal_delivery');
                 continue;
@@ -991,14 +832,20 @@ export async function* runQuery(userInput, options) {
                 ? { allow: true }
                 : advisorCoordinator.beforeDelivery(assistantText);
             const fallbackReview = !emptyResponse && options.advisorCheckpoints !== false
-                ? advisorCoordinator.pendingReview(assistantText) : undefined;
+                ? 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),
-                    } });
+                toolCallsByIndex.push({
+                    id: crypto.randomUUID(),
+                    type: 'function',
+                    function: {
+                        name: 'Advisor',
+                        arguments: JSON.stringify(fallbackReview),
+                    },
+                });
                 assistantMsg.content = null;
                 assistantMsg.tool_calls = toolCallsByIndex;
                 break finalResponse;
@@ -1018,11 +865,20 @@ export async function* runQuery(userInput, options) {
                 // advisor state. Never replay tools or expose an empty candidate as an answer.
                 if (!resultPresented && !emptyResponseRecoveryAttempted && turn < maxTurns) {
                     emptyResponseRecoveryAttempted = true;
-                    emptyResponseRecoveryReason = lastFinishReason === 'length'
-                        ? '输出额度耗尽' : lastFinishReason === 'unknown'
-                        ? '响应流缺少正常结束状态' : '响应为空或仅含思考内容';
-                    const message = { role: 'system', content: '正在恢复回答，已保留调查结果与工作进展。',
-                        id: crypto.randomUUID(), timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+                    emptyResponseRecoveryReason =
+                        lastFinishReason === 'length'
+                            ? '输出额度耗尽'
+                            : lastFinishReason === 'unknown'
+                                ? '响应流缺少正常结束状态'
+                                : '响应为空或仅含思考内容';
+                    const message = {
+                        role: 'system',
+                        content: '正在恢复回答，已保留调查结果与工作进展。',
+                        id: crypto.randomUUID(),
+                        timestamp: Date.now(),
+                        _ephemeral: true,
+                        _uiProgress: true,
+                    };
                     history.push(message);
                     yield { type: 'injected_message', message };
                     continue;
@@ -1035,85 +891,42 @@ export async function* runQuery(userInput, options) {
                 let publicationError;
                 let publicationInterrupted = false;
                 let streamed = false;
-                if (!options.responseFormat && runtimeContext.profile === 'main'
-                    && output.finalDelivery === 'stream') {
-                    const candidate = assistantText;
-                    const candidateFinishReason = lastFinishReason;
-                    let publishedText = '';
-                    let publicationDone = false;
-                    yield { type: 'stage_change', stage: 'streaming' };
-                    try {
-                        const publicationMessages = finalAnswerMessages(buildModelMessages(history, requestTransientContext, userMessage.id), assistantText, output);
-                        const publicationPlan = buildContextBudgetPlan({ provider, history: publicationMessages, tools: [] });
-                        if (publicationPlan.overBudget)
-                            throw new Error('最终表达上下文超过模型输入上限，未发送请求。');
-                        if (signal?.aborted || options.hasQueuedInput?.()) {
-                            publicationInterrupted = true;
-                            throw new Error('最终发布已取消。');
-                        }
-                        turnUsage.totalCalls += 1;
-                        for await (const event of chatFn({
-                            provider,
-                            messages: publicationMessages,
-                            tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'publication'), signal,
-                            conversationMode: runtimeContext.conversationMode ?? 'private',
-                            promptCache: options.promptCache,
-                        })) {
-                            if (event.type === 'done' && !publicationDone) {
-                                publicationDone = true;
-                                if (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number') {
-                                    turnUsage.reportedCalls += 1;
-                                    turnUsage.inputTokens += event.promptTokens ?? 0;
-                                    turnUsage.outputTokens += event.outputTokens ?? 0;
-                                }
-                            }
-                            if (signal?.aborted || options.hasQueuedInput?.()) {
-                                publicationInterrupted = true;
-                                break;
-                            }
-                            if (event.type === 'text_delta') {
-                                // Final expression is live generation, not an exact-copy replay.
-                                // Once visible, text is never replaced or joined with a different draft.
-                                publishedText += event.delta;
-                                streamed = true;
-                                yield { type: 'text', delta: event.delta };
-                            }
-                            else if (event.type === 'tool_call_delta') {
-                                throw new Error('最终表达阶段返回了非预期工具调用，未执行该工具。');
-                            }
-                            else if (event.type === 'done') {
-                                publicationDone = true;
-                                lastFinishReason = event.stopReason;
-                                if (event.stopReason === 'aborted')
-                                    publicationInterrupted = true;
-                            }
-                        }
-                        if (!publicationDone && !publicationInterrupted)
-                            throw new Error('最终答案流未正常结束。');
-                        if (!publicationInterrupted && lastFinishReason !== 'stop' && lastFinishReason !== 'length')
-                            throw new Error('最终答案流缺少有效的结束状态。');
-                        if (!publishedText.trim() && !publicationInterrupted)
-                            throw new Error('最终表达未返回正文。');
-                    }
-                    catch (error) {
-                        publicationInterrupted ||= signal?.aborted === true || options.hasQueuedInput?.() === true || error?.name === 'AbortError';
-                        publicationError = error;
-                    }
-                    if (publicationError && !publicationInterrupted && !publishedText) {
-                        yield { type: 'warning', message: '最终回答流未能开始，已一次性显示内部准备的答案；未进行新的事实核验。' };
-                        yield { type: 'text', delta: candidate };
-                        streamed = true;
-                        publishedText = candidate;
-                        lastFinishReason = candidateFinishReason;
-                        publicationError = undefined;
-                    }
+                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 } };
+                            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 } };
+                            yield {
+                                type: 'error',
+                                code: 'llm_error',
+                                error: `最终答案生成失败：${String(publicationError)}`,
+                                usage: {
+                                    ...turnUsage,
+                                    trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+                                },
+                            };
                         return;
                     }
                 }
@@ -1134,9 +947,23 @@ export async function* runQuery(userInput, options) {
                 if (publicationInterrupted || publicationError) {
                     yield { type: 'warning', message: '最终答案未完整生成，已保留已输出内容；未撤回或重新生成。' };
                     if (publicationInterrupted)
-                        yield { ...interruption(), usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+                        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 } };
+                        yield {
+                            type: 'error',
+                            code: 'llm_error',
+                            error: `最终答案流中断：${String(publicationError)}`,
+                            usage: {
+                                ...turnUsage,
+                                trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+                            },
+                        };
                     return;
                 }
             }
@@ -1153,7 +980,7 @@ export async function* runQuery(userInput, options) {
             // The final answer has already consumed the latest screenshot. Persist only a compact
             // marker so the next turn does not resend a large screen image.
             evictPriorVisionShots(history);
-            const estimatedTokens = countMessagesTokens(history) + getToolsSchemaTokens(activeTools);
+            const estimatedTokens = countMessagesTokens(history) + estimateToolsTokens(activeTools);
             const usedTokens = Math.min(provider.contextWindow, Math.max(lastPromptTokens ?? 0, estimatedTokens));
             yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('complete') };
             const claimValidation = validateFinalClaims(assistantText, evidenceLedger.snapshot());
@@ -1218,8 +1045,12 @@ export async function* runQuery(userInput, options) {
                 };
             }
             else {
-                yield { type: 'turn_done', completionStatus: 'completed', usage,
-                    ...(emptyResponse ? { warning: '成果已提交，未生成文字总结；请查看已提交的成果。' } : {}) };
+                yield {
+                    type: 'turn_done',
+                    completionStatus: 'completed',
+                    usage,
+                    ...(emptyResponse ? { warning: '成果已提交，未生成文字总结；请查看已提交的成果。' } : {}),
+                };
             }
             return;
         }
@@ -1241,256 +1072,18 @@ export async function* runQuery(userInput, options) {
         // 两种路径下，history 里的 tool 消息都严格按 toolCallsByIndex 索引顺序回填
         // （OpenAI 协议要求 tool 消息与上一条 assistant 的 tool_calls 一一对应）。
         yield { type: 'stage_change', stage: 'tool_executing' };
-        // 执行单个 tool call → WorkerOutcome（内部吞掉 abort/异常，永不 reject）。
-        const failureReviews = [];
-        const runOneImpl = async (tc, reportProgress) => {
-            try {
-                const handoff = options.agentHandoff?.current();
-                if (handoff && handoff.kind !== 'help')
-                    return { tc, result: { ok: false, disposition: 'deferred', error: '子任务已经提交交接，本批后续调用未执行' } };
-                if (signal?.aborted || options.hasQueuedInput?.()) {
-                    return { tc, result: { ok: false, disposition: 'deferred', error: 'aborted' } };
-                }
-                const advisorAvailable = currentEffectiveToolSet.names.has('Advisor');
-                if (!advisorAvailable && stallGuard.shouldReject(tc)) {
-                    return {
-                        tc,
-                        result: {
-                            ok: false,
-                            disposition: 'deferred',
-                            error: '检测到同一工具和参数已连续两次返回相同失败；第三次调用已在执行前拒绝，请改变输入或改用其他路径。',
-                            recovery: 'change-input',
-                            sensitivity: 'public',
-                        },
-                    };
-                }
-                // The model-visible catalog and the execution boundary are the same set.
-                // A provider may still emit a stale or fabricated tool call; return a
-                // recoverable result so the model can choose an available path.
-                if (!currentEffectiveToolSet.names.has(tc.function.name)) {
-                    const boundary = options.toolBoundaryLabel ?? '当前宿主授权';
-                    const visible = [...currentEffectiveToolSet.names];
-                    const availableHint = visible.length
-                        ? `（可用：${visible.slice(0, 12).join('、')}${visible.length > 12 ? '…' : ''}）`
-                        : '（本轮没有可用工具）';
-                    const deniedReason = tc.function.name === 'Agent'
-                        ? '当前上下文不允许调用 Agent；请直接完成子任务或改用已提供的工具'
-                        : `工具 ${tc.function.name} 不在${boundary}的有效工具集中${availableHint}，请改用已提供的工具继续任务`;
-                    return {
-                        tc,
-                        result: {
-                            ok: false,
-                            error: deniedReason,
-                            recovery: 'change-input',
-                            sensitivity: 'public',
-                        },
-                    };
-                }
-                const checkpoint = options.advisorCheckpoints === false
-                    ? { allow: true }
-                    : advisorCoordinator.beforeTool(tc, {
-                        ...advisorSemanticsFor(tc, toolCallContext, currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name), { treatVerificationAsReadOnly: true }),
-                        retriesFailure: stallGuard.shouldReject(tc),
-                    });
-                if (!checkpoint.allow) {
-                    return { tc, result: checkpoint.deferred };
-                }
-                // 工具执行闸门：宿主注入后覆盖所有工具，包括只读工具。deny → 把 reason 当
-                // tool_result 回填，模型据此改道/如实报告，不抛异常不中断整轮。宿主异常一律 deny。
-                // Keep the host gate's side-effect classification identical to the
-                // Advisor classification. Shell tools are generic in their schema but
-                // individual commands can be deterministic read-only diagnostics.
-                let isReadOnly = currentEffectiveToolSet.tools.find(tool => tool.name === tc.function.name)?.isReadOnly === true;
-                if (tc.function.name === 'Bash' || tc.function.name === 'PowerShell') {
-                    try {
-                        const input = JSON.parse(tc.function.arguments || '{}');
-                        if (typeof input.command === 'string')
-                            isReadOnly = isReadOnlyShellCommand(input.command);
-                    }
-                    catch {
-                        isReadOnly = false;
-                    }
-                }
-                const effectiveToolGate = runtimeContext.toolGate ?? options.toolGate;
-                if (effectiveToolGate) {
-                    let decision;
-                    try {
-                        const gateDetails = getToolGateDetails(tc.function.name, tc.function.arguments, { ...toolCallContext, cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd, toolCallId: tc.id, reportProgress });
-                        decision = await effectiveToolGate({
-                            name: tc.function.name,
-                            argsJson: tc.function.arguments,
-                            isReadOnly,
-                            toolCallId: tc.id,
-                            ...gateDetails,
-                        }, signal);
-                    }
-                    catch {
-                        decision = { allow: false, reason: '工具执行审批失败（宿主异常）' };
-                    }
-                    if (!decision.allow) {
-                        return { tc, result: { ok: false, error: decision.reason } };
-                    }
-                }
-                if (signal?.aborted || options.hasQueuedInput?.()) {
-                    return { tc, result: { ok: false, disposition: 'deferred', error: 'aborted' } };
-                }
-                options.onToolStart?.(tc.function.name, tc.id);
-                // 浅拷贝填入本次调用的 toolCallId：进度按调用实例路由（并行同名工具不串扰）。
-                // advisorCalls/agentCalls 是共享对象引用，计数仍全轮共享，不受拷贝影响。
-                const executionCwd = sessionState?.activeWorktree?.path ?? toolCallContext.cwd;
-                if (executionCwd !== modelEnvironmentCwd)
-                    return { tc, result: {
-                            ok: false, disposition: 'deferred',
-                            error: '执行环境已改变，本批调用依据旧目录生成，尚未执行。请等待刷新环境和项目规则后重新生成调用。',
-                        } };
-                // Load path-scoped rules before a direct file mutation. Returning a
-                // deferred result gives the model a boundary to reconsider its edit.
-                if (['Edit', 'MultiEdit', 'Write', 'Download', 'NotebookEdit', 'Trash'].includes(tc.function.name)) {
-                    try {
-                        const args = JSON.parse(tc.function.arguments);
-                        const targets = tc.function.name === 'Trash' ? args.paths : [args.file_path ?? args.path ?? args.notebook_path];
-                        for (const target of Array.isArray(targets) ? targets : []) {
-                            if (typeof target !== 'string')
-                                continue;
-                            // Download/Trash use literal path.resolve; editing tools expand ~.
-                            const resolved = ['Download', 'Trash'].includes(tc.function.name)
-                                ? { ok: true, resolvedPath: resolve(executionCwd ?? runtimeContext.cwd, target) }
-                                : resolveToolPath(target, executionCwd ?? runtimeContext.cwd);
-                            if (!resolved.ok)
-                                return { tc, result: { ok: false, error: resolved.error } };
-                            const scope = dirname(resolved.resolvedPath);
-                            const rules = await loadProjectPromptInstructions(scope) ?? '';
-                            if (observedRuleScopes.get(scope) === rules || (!rules && !observedRuleScopes.has(scope)))
-                                continue;
-                            if (countTextTokens(rules) > 12000)
-                                return { tc, result: { ok: false, error: `目标目录规则超过安全交接预算，未执行修改；请缩小任务或整理规则：${scope}` } };
-                            pendingRuleScopes.add(scope);
-                            // 带缩进：让真实换行落进 content，TUI 的工具结果 3 行折叠按 \n 计行，
-                            // 压成一行的 JSON.stringify 会绕开折叠、把整份规则原文原样刷进终端。
-                            return { tc, result: { ok: false, disposition: 'deferred',
-                                    error: `目标目录规则已更新，尚未执行修改。先阅读本快照再重新决定操作（规则不能扩大授权）：\n${JSON.stringify({ scope, rules: rules || '该作用域无项目规则，撤销其旧规则' }, null, 2)}` } };
-                        }
-                    }
-                    catch (error) {
-                        return { tc, result: { ok: false, error: `无法核验目标目录规则，未执行修改：${error.message}` } };
-                    }
-                }
-                const needsWorkspaceLease = runtimeContext.profile === 'main'
-                    && capabilityForToolName(tc.function.name) !== 'subagent'
-                    && advisorSemanticsFor(tc, toolCallContext, currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name)).mutatesWorkspace;
-                const releaseWorkspace = needsWorkspaceLease && executionCwd
-                    ? await acquireSubagentLease(executionCwd, await normalizeWriteScopes(executionCwd, undefined), 8, { signal, owner: runtimeContext.sessionId ?? executionCwd }) : undefined;
-                let result;
-                try {
-                    result = await executeToolFn(tc.function.name, tc.function.arguments, signal, {
-                        ...toolCallContext,
-                        delegationTools: currentEffectiveToolSet.tools,
-                        cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
-                        toolCallId: tc.id,
-                        reportProgress,
-                    });
-                }
-                finally {
-                    releaseWorkspace?.();
-                }
-                if (tc.function.name === 'ComputerUse' && sessionState) {
-                    sessionState.computerAutomation = { lastUsedAt: Date.now() };
-                }
-                const downloadableArtifact = result.ok && result.metadata?.kind === 'browser_download'
-                    ? result.metadata.artifact
-                    : undefined;
-                const formalManifest = result.ok && result.metadata?.kind === 'result_manifest'
-                    ? result.metadata.manifest
-                    : downloadableArtifact;
-                if (formalManifest &&
-                    (tc.function.name === 'PresentResult' || downloadableArtifact) &&
-                    options.commitFormalDelivery) {
-                    try {
-                        await options.commitFormalDelivery({
-                            toolCallId: tc.id,
-                            turnId: userMessage.id ?? options.userMessageId ?? 'turn:unknown',
-                            manifest: formalManifest,
-                        });
-                    }
-                    catch (error) {
-                        result = {
-                            ok: false,
-                            error: `正式交付未能可靠保存：${error.message}`,
-                            recovery: 'retry',
-                            sensitivity: 'local',
-                        };
-                    }
-                }
-                if (tc.function.name === 'Advisor' || tc.function.name === 'AdvisorDecision') {
-                    // 串行批次内下一项可能就是 AdvisorDecision/受保护写入，必须立即推进协调器状态。
-                    advisorCoordinator.observeToolResult(tc, result);
-                }
-                options.onToolEnd?.(tc.id, false);
-                return { tc, result };
-            }
-            catch (e) {
-                const wasAborted = e.name === 'AbortError';
-                options.onToolEnd?.(tc.id, wasAborted);
-                if (wasAborted) {
-                    return { tc, result: { ok: false, error: 'aborted' } };
-                }
-                return { tc, result: { ok: false, error: e.message } };
-            }
-        };
-        const runOne = async (tc, reportProgress) => {
-            // Also settle denied/invalid/unavailable calls that never reached the
-            // provider adapter. This records a real attempt, not an ignored reminder.
-            let consultation;
-            if (tc.function.name === 'Advisor') {
-                let reason;
-                try {
-                    reason = JSON.parse(tc.function.arguments).reason;
-                }
-                catch { /* validation handles malformed input */ }
-                consultation = advisorCoordinator.beginConsultation(reason);
-            }
-            const outcome = await runOneImpl(tc, reportProgress);
-            if (consultation && outcome.result.metadata?.kind !== 'advisor_consultation'
-                && !(!outcome.result.ok && outcome.result.error === 'aborted')) {
-                outcome.result = { ...outcome.result, metadata: advisorCoordinator.finishConsultation(consultation, outcome.result.ok) };
-            }
-            const metadata = outcome.result.metadata;
-            if (metadata?.kind === 'advisor_decision' && outcome.result.ok
-                || metadata?.kind === 'advisor_consultation') {
-                if (metadata.checkpoint === 'stalled')
-                    stallGuard.completeReview(metadata.checkpointKey.split(':').at(-1));
-            }
-            const failure = stallGuard.observeAttempt(tc, outcome.result);
-            if (failure.stalled && failure.signature) {
-                failureReviews.push(failure);
-                advisorCoordinator.requireFailureReview(failure.signature, failure.attempts ?? []);
-            }
-            return outcome;
-        };
-        const startEvent = (tc) => ({
-            type: 'tool_start',
-            toolCallId: tc.id,
-            toolName: tc.function.name,
-            argsPreview: previewArgs(tc.function.arguments),
-            argsFriendly: friendlyToolDescription(tc.function.name, tc.function.arguments),
-            argsConcise: friendlyToolDescription(tc.function.name, tc.function.arguments, conciseToolPath),
-        });
-        const endEvent = (o) => ({
-            type: 'tool_end',
-            toolCallId: o.tc.id,
-            toolName: o.tc.function.name,
-            ok: o.result.ok,
-            content: o.result.ok
-                ? o.result.content
-                : o.result.error === 'aborted'
-                    ? '(已中断)'
-                    : `Error: ${o.result.error}`,
-            metadata: o.result.metadata,
-        });
-        const segments = executionSegments(toolCallsByIndex, (tc) => {
-            const tool = currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name);
-            return !['AskUserQuestion', 'Advisor', 'AdvisorDecision', 'OptimizeConversation', 'AgentReport', 'AgentResolve'].includes(tc.function.name)
-                && (tool?.isConcurrencySafe ?? getToolByName(tc.function.name)?.isConcurrencySafe) === true;
+        const { runOne, failureReviews } = createToolExecutor({
+            options,
+            runtimeContext,
+            toolCallContext,
+            currentEffectiveToolSet,
+            advisorCoordinator,
+            stallGuard,
+            modelEnvironmentCwd,
+            observedRuleScopes,
+            pendingRuleScopes,
+            currentUserMessageId: userMessage.id,
+            executeToolFn,
         });
         let anyAborted = false;
         // Commit serial outcomes before the next tool starts: Advisor must see the
@@ -1505,23 +1098,15 @@ export async function* runQuery(userInput, options) {
             }
             if (!result.ok && result.error === 'aborted')
                 anyAborted = true;
-            const browserArtifact = result.ok && result.metadata?.kind === 'browser_download'
-                ? result.metadata.artifact
-                : undefined;
+            const browserArtifact = result.ok && result.metadata?.kind === 'browser_download' ? result.metadata.artifact : undefined;
             if (result.ok &&
-                ((tc.function.name === 'PresentResult' &&
-                    result.metadata?.kind === 'result_manifest') ||
-                    browserArtifact)) {
+                ((tc.function.name === 'PresentResult' && result.metadata?.kind === 'result_manifest') || browserArtifact)) {
                 resultPresented = true;
                 // `not_run` only says that no optional, format-specific validator was
                 // invoked. The PresentResult boundary has still checked the file and
                 // persisted its fingerprint, so it must not downgrade a normal delivery.
-                const manifest = result.metadata?.kind === 'result_manifest'
-                    ? result.metadata.manifest
-                    : browserArtifact;
-                presentedResultUnverified ||=
-                    manifest?.files.some((file) => file.verification === 'failed') ??
-                        false;
+                const manifest = result.metadata?.kind === 'result_manifest' ? result.metadata.manifest : browserArtifact;
+                presentedResultUnverified ||= manifest?.files.some((file) => file.verification === 'failed') ?? false;
             }
             const rawContent = result.ok ? result.content : `Error: ${result.error}`;
             const basePolicy = result.policy ?? getToolResultPolicy(tc.function.name);
@@ -1555,134 +1140,43 @@ export async function* runQuery(userInput, options) {
                 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,
+                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(),
                 ...(options.messageProvenance ? { provenance: options.messageProvenance } : {}),
             });
         };
-        const settled = [];
-        let questionEncountered = false;
-        let advisorEncountered = false;
-        for (const segment of segments) {
-            if (!questionEncountered && !advisorEncountered && segment.length > 1) {
-                // —— 并行：事件队列把各 worker 的 start/end 按真实完成顺序交错 yield 给 UI。
-                const queue = [];
-                let signalNew = null;
-                const enqueue = (ev) => {
-                    queue.push(ev);
-                    signalNew?.();
-                    signalNew = null;
-                };
-                // 默认并发 = 本轮工具调用数，即不设人为上限（orderedPool 内部本就会
-                // Math.min(concurrency, items.length)）——这批工具已经过 allConcurrencySafe
-                // 判定全部只读/并发安全，能同时跑多少纯是吞吐量问题，不是正确性问题；宿主仍可显式传
-                // options.toolConcurrency 收紧（"并发安全"不等于"内存/子进程/provider 配额无限"，
-                // 真有这类顾虑应由宿主按自己的资源预算显式传值，而不是内核替所有宿主悄悄封顶）。
-                // ⚠️ 这条默认值曾被 9ce9be61 那次子Agent/浏览器重构悄悄改回 8——那次改动是照着一份
-                // 更早的 loop.ts 打的 diff，没带上这里的注释，属于历史真空期的意外覆盖，不是刻意
-                // 重新评估后的决定；发现后原样恢复。
-                const allDone = orderedPool(segment, options.toolConcurrency ?? segment.length, async (tc) => {
-                    enqueue(startEvent(tc));
-                    const o = await runOne(tc, (message, detail) => enqueue({
-                        type: 'tool_progress',
-                        toolCallId: tc.id,
-                        toolName: tc.function.name,
-                        message,
-                        detail,
-                    }));
-                    enqueue(endEvent(o));
-                    return o;
-                });
-                let finished = false;
-                const wakeDone = () => {
-                    finished = true;
-                    signalNew?.();
-                    signalNew = null;
-                };
-                void allDone.then(wakeDone, wakeDone);
-                while (!finished || queue.length > 0) {
-                    while (queue.length > 0)
-                        yield queue.shift();
-                    if (finished)
-                        break;
-                    await new Promise((r) => {
-                        signalNew = r;
-                    });
-                }
-                const outcomes = await allDone;
-                settled.push(...outcomes);
-                for (const outcome of outcomes)
-                    yield* commitOutcome(outcome);
-            }
-            else {
-                // —— 串行：逐个执行（含写类工具，或只有一个工具）。事件直接顺序 yield，无需队列。
-                for (const tc of segment) {
-                    if (questionEncountered || advisorEncountered) {
-                        const outcome = { tc, result: { ok: false, disposition: 'deferred',
-                                error: questionEncountered
-                                    ? '此调用在用户回答前已生成，尚未执行。请先阅读提问结果并重新规划；仅在仍必要时重新调用。'
-                                    : '此调用在顾问返回前已生成，尚未执行。请先阅读顾问结果，自主决定采纳、部分采纳或拒绝，再重新生成必要的工具调用。咨询失败则自行判断继续，不必重复咨询。' } };
-                        yield startEvent(tc);
-                        yield endEvent(outcome);
-                        settled.push(outcome);
-                        yield* commitOutcome(outcome);
-                        continue;
-                    }
-                    questionEncountered = tc.function.name === 'AskUserQuestion';
-                    yield startEvent(tc);
-                    const queue = [];
-                    let wake = null;
-                    let finished = false;
-                    const worker = runOne(tc, (message, detail) => {
-                        queue.push({
-                            type: 'tool_progress',
-                            toolCallId: tc.id,
-                            toolName: tc.function.name,
-                            message,
-                            detail,
-                        });
-                        wake?.();
-                        wake = null;
-                    }).finally(() => {
-                        finished = true;
-                        wake?.();
-                        wake = null;
-                    });
-                    while (!finished || queue.length > 0) {
-                        while (queue.length > 0)
-                            yield queue.shift();
-                        if (finished)
-                            break;
-                        await new Promise((resolve) => { wake = resolve; });
-                    }
-                    const o = await worker;
-                    // Every later call was planned without this second opinion, including
-                    // decision records and further consultations. Return control to the LLM.
-                    advisorEncountered = tc.function.name === 'Advisor';
-                    yield endEvent(o);
-                    settled.push(o);
-                    yield* commitOutcome(o);
-                }
-            }
-        }
+        const settled = yield* executeToolBatch({
+            toolCallsByIndex,
+            currentEffectiveToolSet,
+            options,
+            runOne,
+            commitOutcome,
+        });
         // Publish after every pending tool result has been appended, so hosts see a
         // complete protocol chain when persisting the compacted history.
         while (optimizationEvents.length > 0)
             yield optimizationEvents.shift();
         const childHandoff = options.agentHandoff?.current();
         if (childHandoff && childHandoff.kind !== 'help') {
-            yield { type: 'turn_done', completionStatus: childHandoff.kind === 'result' ? 'completed' : 'delivery_incomplete',
+            yield {
+                type: 'turn_done',
+                completionStatus: childHandoff.kind === 'result' ? 'completed' : 'delivery_incomplete',
                 warning: childHandoff.kind === 'blocked' ? '子任务已交回主 Agent 接力' : undefined,
-                usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+                usage: {
+                    ...turnUsage,
+                    trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+                },
+            };
             return;
         }
         // Failures are recorded at execution time; batch observation now supplements
         // them with the existing no-progress signal without counting attempts twice.
-        const stall = failureReviews.at(-1) ?? (turn + 1 < maxTurns
-            ? stallGuard.observe(settled.map((item) => item.tc), settled.map((item) => item.result), assistantText)
-            : { stalled: false });
+        const stall = failureReviews.at(-1) ??
+            (turn + 1 < maxTurns
+                ? stallGuard.observe(settled.map((item) => item.tc), settled.map((item) => item.result), assistantText)
+                : { stalled: false });
         if (stall.stalled) {
             const message = stall.reason === 'repeated_failure'
                 ? '同一问题两次尝试失败，请停止原样重试；顾问可用时，继续解决或交付前先咨询，由主 Agent 自行核验和决策。只读诊断仍可继续。'
@@ -1698,7 +1192,9 @@ export async function* runQuery(userInput, options) {
         try {
             injectedShot = await injectVisionFollowups(history, settled, provider);
         }
-        catch { /* 截图回填失败不影响主流程 */ }
+        catch {
+            /* 截图回填失败不影响主流程 */
+        }
         // The history copy is intentionally downgraded after the turn. Emit a detached snapshot
         // so TUI/Desktop stores do not see their already-rendered image mutate underneath them.
         if (injectedShot) {
@@ -1731,242 +1227,3 @@ export async function* runQuery(userInput, options) {
         code: 'max_turns',
     };
 }
-// ---------------- 辅助函数 ----------------
-/**
- * 易变上下文只存在于 provider 请求副本中，不会进入会话历史。
- */
-export const SYSTEM_REMINDER_OPEN = '<system-reminder>';
-export const SYSTEM_REMINDER_CLOSE = '</system-reminder>';
-/**
- * Attach transient context to the current turn's user message in a model-only
- * clone. Later tool-loop requests reuse the same decorated message, making each
- * serialized request a strict prefix extension of the previous one.
- */
-export function buildModelMessages(history, transientContext, currentUserMessageId) {
-    history = history.filter(message => !(message.role === 'system' && message._ephemeral));
-    const transient = transientContext?.trim();
-    if (!transient)
-        return history;
-    let index = currentUserMessageId
-        ? history.findIndex((message) => message.role === 'user' && message.id === currentUserMessageId)
-        : -1;
-    if (index < 0) {
-        for (let cursor = history.length - 1; cursor >= 0; cursor--) {
-            if (history[cursor]?.role === 'user') {
-                index = cursor;
-                break;
-            }
-        }
-    }
-    if (index < 0)
-        return history;
-    const target = history[index];
-    if (target.role !== 'user')
-        return history;
-    const reminder = `${SYSTEM_REMINDER_OPEN}\n${transient}\n${SYSTEM_REMINDER_CLOSE}`;
-    const content = typeof target.content === 'string'
-        ? `${target.content}\n\n${reminder}`
-        : [...target.content, { type: 'text', text: reminder }];
-    const next = [...history];
-    next[index] = { ...target, content };
-    return next;
-}
-// 关键节点图像核验的合成消息标记：既是给模型的提示前缀，也是 evictPriorVisionShots 识别旧图消息的锚。
-export const VISION_SHOT_MARKER = '【实况图像】';
-/**
- * 历史标记。这套机制最初只有 WebBrowser 用得上，文案写死了「浏览器」；
- * 现在 Bash 的 ATTACH_IMAGE sentinel 也能产图（屏幕截图 / 生成的产物），文案必须中性。
- * 但**持久化会话里仍存着旧前缀的消息**，淘汰逻辑必须继续认它 ——
- * 否则老会话里的旧截图永远不会被降级，图片一路累积撑爆上下文。
- */
-const LEGACY_VISION_SHOT_MARKERS = ['【浏览器实况截图】'];
-const VISION_SHOT_PROMPT = `${VISION_SHOT_MARKER}上面是刚才工具执行后附带的真实图像（浏览器页面 / 屏幕截图 / 生成的产物）。请仔细看图核对：是否真的到达/呈现了你预期的状态？若与预期不符（空白/报错/弹窗遮挡/验证拦截/内容不对），不要假设成功，如实说明并调整下一步。`;
-/** 一条 user 消息的文本是否是「实况图像」合成消息（含历史前缀）。 */
-function isVisionShotText(text) {
-    return (text.startsWith(VISION_SHOT_MARKER) ||
-        LEGACY_VISION_SHOT_MARKERS.some((marker) => text.startsWith(marker)));
-}
-/**
- * 把本轮工具附带的实况截图（ToolResult.visionImages）组装成一条带图 user 消息喂给模型自我核验。
- * - 仅在模型明确支持识图时注入（provider.supportsVision === true）；否则丢弃（不假装核验、也不给非视觉端点发图触发 400）。
- * - 注入前先把历史里旧的截图消息降级为纯文字占位（evictPriorVisionShots），保证上下文里最多一张实况图，
- *   避免图片累积撑爆上下文（呼应浏览器 ADR「高频帧只存内存、只持久化最终结果」）。
- * - **失败的工具结果同样回填**：出错现场那张图往往比成功时更有信息量（权限弹窗、
- *   验证拦截、意外的前台窗口）。此前这里要求 `ok === true`，逼得想附图的工具只能
- *   把失败伪装成成功——见 types.ts 里 ToolResult 那段注释。
- */
-async function injectVisionFollowups(history, settled, provider) {
-    if (provider.supportsVision === false)
-        return null;
-    const images = settled.flatMap((s) => s.result.visionImages ?? []);
-    if (images.length === 0)
-        return null;
-    evictPriorVisionShots(history);
-    // 工具可以给自己这批图配一句说明（visionNote）。内核只负责把它拼在通用提示之后，
-    // 不解读内容——「这是一组 1Hz 连续帧」这类语义只有产图的工具知道。
-    const notes = settled
-        .flatMap((s) => (s.result.visionNote ? [s.result.visionNote] : []))
-        .filter((note, index, all) => all.indexOf(note) === index);
-    const text = notes.length > 0
-        ? `${VISION_SHOT_PROMPT}\n\n${notes.join('\n\n')}`
-        : VISION_SHOT_PROMPT;
-    const content = await buildUserContent({ text, images });
-    const msg = { role: 'user', content, timestamp: Date.now(), id: crypto.randomUUID() };
-    history.push(msg);
-    return msg;
-}
-/** 把历史里旧的实况图像 user 消息降级为纯文字占位、剔除其图片，释放上下文（只保留最近一张真图）。 */
-function evictPriorVisionShots(history) {
-    for (const msg of history) {
-        if (msg.role !== 'user' || !Array.isArray(msg.content))
-            continue;
-        const textPart = msg.content.find((p) => p.type === 'text');
-        if (textPart?.type === 'text' && isVisionShotText(textPart.text)) {
-            msg.content = `${VISION_SHOT_MARKER}（此前的实况图像已从上下文移除以节省空间。）`;
-        }
-    }
-}
-/**
- * 用户按ESC手动中断
- */
-function pushManualInterruptMarker(history) {
-    history.push({
-        role: 'user',
-        content: '(用户按下了 ESC/Ctrl+C 中断了任务。等待用户新指令。)',
-        timestamp: Date.now(),
-        id: crypto.randomUUID(),
-    });
-}
-/**
- * 有新的用户输入在队列中，当前安全停靠
- */
-function pushQueuedInputMarker(history) {
-    history.push({
-        role: 'user',
-        content: [
-            '(系统提示：用户在工作过程中发送了新的消息。',
-            '你现在看到的是上一轮工作在被打断前已完成的部分。',
-            '请阅读用户的新消息，判断：',
-            '1. 如果是不相关的新任务：简要确认已收到，转向新任务，可在新任务完成后询问是否回到之前工作',
-            '2. 如果是补充信息或前置依赖：把新信息纳入考虑，判断是否需要调整已做的工作，然后继续',
-            '3. 如果是改变方向或取消：评估已完成的部分，说明你对变更的理解，按新方向推进)',
-        ].join('\n'),
-        timestamp: Date.now(),
-        id: crypto.randomUUID(),
-    });
-}
-/** 把一条 tool_call_delta 合并到累积数组上 */
-function mergeToolCallDelta(acc, ev) {
-    let slot = acc[ev.index];
-    if (!slot) {
-        slot = {
-            id: '',
-            type: 'function',
-            function: { name: '', arguments: '' },
-        };
-        acc[ev.index] = slot;
-    }
-    if (ev.id)
-        slot.id = ev.id;
-    if (ev.name)
-        slot.function.name += ev.name;
-    if (ev.argumentsDelta)
-        slot.function.arguments += ev.argumentsDelta;
-}
-/** 给 UI 展示用的参数预览（只取前 60 字符） */
-function previewArgs(rawJson) {
-    const oneLine = rawJson.replace(/\s+/g, ' ').trim();
-    if (oneLine.length <= 60)
-        return oneLine;
-    return oneLine.slice(0, 60) + '...';
-}
-/**
- * 把工具名 + raw arguments JSON 转换成人话描述。
- * UI 优先用这个显示在 spinner 行（如 "Reading src/foo.ts"）。
- * 已知工具走 switch；未知工具或 JSON parse 失败 fallback 到 `${toolName}(...)`。
- */
-function friendlyToolDescription(toolName, rawArgsJson, fileLabel) {
-    let args = {};
-    try {
-        args = JSON.parse(rawArgsJson) ?? {};
-    }
-    catch {
-        return `${toolName}(...)`;
-    }
-    const truncate = (s, n) => {
-        if (typeof s !== 'string')
-            return '';
-        return s.length > n ? s.slice(0, n) + '…' : s;
-    };
-    const file = (value) => {
-        if (typeof value !== 'string')
-            return '';
-        if (fileLabel)
-            return fileLabel(value);
-        return value.length > 64 ? `…${value.slice(-63)}` : value;
-    };
-    switch (toolName) {
-        case 'Skill': return `技能 · ${truncate(args.name, 60)}`;
-        case 'SearchSkills': return `查找技能 · ${truncate(args.query, 60)}`;
-        case 'Advisor': {
-            const reasons = { plan_review: '执行前评审', delivery_review: '交付前核验', stalled: '分析重复失败', uncertainty: '核查不确定问题', user_dissatisfaction: '复核用户反馈', evidence_conflict: '核查证据冲突' };
-            return `咨询顾问 · ${reasons[String(args.reason)] ?? '独立第二意见'}`;
-        }
-        case 'AdvisorDecision': return `顾问建议 · ${truncate(args.decision ?? args.action, 40) || '记录核验与采纳结论'}`;
-        case 'AskUserQuestion': return '询问关键决策';
-        case 'PresentResult': return '提交成果与验证结果';
-        case 'PowerShell': return `运行 PowerShell · ${truncate(args.description ?? args.command, 60)}`;
-        case 'OptimizeConversation': return '优化对话';
-        case 'Read': return `Reading ${file(args.file_path)}`;
-        case 'Edit': return `Editing ${file(args.file_path)}`;
-        case 'MultiEdit': {
-            const n = Array.isArray(args.edits) ? args.edits.length : 0;
-            return `Editing ${file(args.file_path)}${n ? ` (${n} 处)` : ''}`;
-        }
-        case 'Write': return `Writing ${file(args.file_path)}`;
-        case 'Trash': return `Moving to Trash ${file(args.file_path ?? args.path)}`;
-        case 'ApplyPatch': {
-            const patch = typeof args.patch === 'string' ? args.patch : typeof args.input === 'string' ? args.input : '';
-            const files = [...patch.matchAll(/^\*\*\* (Add|Update|Delete) File: (.+)$/gm)].map(m => `${file(m[2])}（${{ Add: '新增', Update: '修改', Delete: '删除' }[m[1]]}）`);
-            if (!files.length)
-                files.push(...[...patch.matchAll(/^\+\+\+ [ab]\/([^\n]+)$/gm)].map(m => file(m[1])));
-            return files.length > 0 ? `Editing ${files.join(', ')}` : 'Editing patch';
-        }
-        case 'NotebookEdit': return `Editing ${file(args.notebook_path ?? args.file_path)}`;
-        case 'Bash': return typeof args.description === 'string' && args.description.trim()
-            ? `运行 ${truncate(args.description, 70)}` : `Running \`${truncate(args.command, 40)}\``;
-        case 'Grep': {
-            const p = truncate(args.pattern, 30);
-            const g = typeof args.glob === 'string' && args.glob.length > 0 ? ` in ${truncate(args.glob, 25)}` : '';
-            return `Searching \`${p}\`${g}`;
-        }
-        case 'Glob': return `Globbing \`${truncate(args.pattern, 50)}\``;
-        case 'WebBrowser': {
-            const actions = { start: '启动', navigate: '打开页面', screenshot: '截图', snapshot: '读取页面', click: '点击', fill: '填写', evaluate: '执行页面脚本', close: '关闭', stop: '停止', console: '查看控制台', network: '查看网络请求' };
-            let target = '';
-            try {
-                target = new URL(String(args.url)).host;
-            }
-            catch { /* no URL for local actions */ }
-            return `浏览器 · ${actions[String(args.action)] ?? (truncate(args.action, 32) || '操作页面')}${target ? ` · ${target}` : ''}`;
-        }
-        case 'WebFetch': {
-            try {
-                return `Fetching ${new URL(String(args.url)).host}`;
-            }
-            catch {
-                return `Fetching ...`;
-            }
-        }
-        case 'BrowserBatch': return `浏览器 · ${truncate(args.action, 30) || '批量操作'}（${Array.isArray(args.steps) ? args.steps.length : 0} 步）`;
-        case 'BrowserCDP': return `浏览器调试 · ${truncate(String(args.method ?? args.operation ?? ''), 45)}`;
-        case 'WebSearch': return `Searching \`${truncate(args.query, 50)}\``;
-        case 'Agent': {
-            const t = typeof args.agent_type === 'string' ? args.agent_type : 'explore';
-            return `子任务[${t}] ${truncate(args.description, 50)}`;
-        }
-        default: return `${toolName} · ${truncate(args.description ?? args.action ?? args.operation, 60) || '执行工具操作'}`;
-    }
-}
-// 导出供测试用（friendlyToolDescription 是 module-private 纯函数）
-export { friendlyToolDescription };