mocode-ai 0.7.0 → 0.7.2

package/dist/agent/core.js

@@ -6,20 +6,24 @@
 // spawn.ts 的 spawnAgent = runAgentCore + 静默 hooks(子 agent)。
 import { readFileSync } from 'node:fs';
 import { chat, estimatePromptTokens, planChatTools, chatTools, } from '../llm/index.js';
-import { executeTool, tools } from '../tools/registry.js';
+import { executeToolOutcome, getToolCapabilities, isFileMutationTool, tools, } from '../tools/registry.js';
 import { checkPermission } from '../permissions/index.js';
-import { getPlanDisabledTools } from '../tools/constants.js';
+import { getPlanDisabledTools, getRuntimeDisabledTools } from '../tools/constants.js';
 import { getAgentMode, setAgentMode } from './mode.js';
-import { maybeCompact, contextState, dropContextFromHistory } from '../session/index.js';
+import { maybeCompact, contextState, dropContextFromHistory, createTraceEvent, summarizeToolArguments, safeProviderId, } from '../session/index.js';
 import { createBudgetScheduler } from '../session/scheduler.js';
 import { optimizeToolResult, HOT_TURN_WINDOW, userTurnBoundary } from '../context/index.js';
 import { createAgeAwareEncodingState, } from '../context/age-aware.js';
 import { createRelevancePruner } from '../context/relevance.js';
 import { isToolResultSuccess } from '../context/utils.js';
 import { config } from '../config/index.js';
+import { t } from '../i18n/index.js';
 import { jailResolve } from '../sandbox/index.js';
 import { createLifecycleEngine } from '../context/lifecycle.js';
 import { getTokenCalibration, updateTokenCalibration, } from '../context/token-calibration.js';
+import { getCurrentTurnId, getCurrentTurnMutationState } from '../rollback/index.js';
+import { createAutomaticValidator, } from '../verification/index.js';
+import { getCurrentSessionId } from '../session/state.js';
 /** Stable per-history age state survives user turns; WeakMap avoids retaining closed sessions. */
 const ageAwareStateByHistory = new WeakMap();
 function ageAwareStateFor(history) {
@@ -57,17 +61,27 @@ function thrashHint(name, args, count) {
         '- edit_file → old_string mismatch; re-read the file to find the exact text\n' +
         '- otherwise → re-read the tool description; the argument shape may be wrong');
 }
-/** 只读工具集:一轮多个时,连续的只读工具成组 Promise.all 并行(无副作用、互不依赖)。 */
-const READ_TOOL_NAMES = new Set([
-    'read_file',
-    'glob',
-    'grep',
-    'codegraph',
-    'web_search',
-    'web_fetch',
-]);
-/** mutation 工具:写盘 + 在 executeTool 内记回滚 before 快照,必须串行保快照序。 */
-const isMutationTool = (name) => name === 'edit_file' || name === 'write_file';
+/** 只有显式声明 parallel 且无需权限确认的工具才进入普通并发组。 */
+function isParallelTool(name) {
+    const tool = tools.find((candidate) => candidate.name === name);
+    return !!tool && (tool.risk ?? 'safe') === 'safe' &&
+        getToolCapabilities(tool).concurrency === 'parallel';
+}
+/** resource-locked 工具先顺序完成权限预检，再依赖 canonical resource lock 并发执行。 */
+function isResourceLockedTool(name) {
+    const tool = tools.find((candidate) => candidate.name === name);
+    return !!tool && getToolCapabilities(tool).concurrency === 'resource-locked';
+}
+/** 文件 mutation 由 capability metadata 判定，供 diff、回滚与上下文失效共用。 */
+const isMutationTool = (name) => isFileMutationTool(name);
+function deniedOutcome(name) {
+    return {
+        status: 'denied',
+        code: 'PERMISSION_DENIED',
+        retryable: false,
+        output: `错误:用户拒绝了工具 ${name} 的执行。`,
+    };
+}
 /** mutation 执行前读旧内容供 diff:write_file 取整文件旧内容(不存在→null=新建),
  * edit_file 取 old_string 起始行号(供 diff 显示真实文件行号)。读不到则 diff 退化为相对行号。
  * 非 mutation 或参数非法返 { preWriteOld: null, editStartLine: 1 }。失败不阻断。 */
@@ -116,8 +130,8 @@ function readDiffContext(tc, parsed) {
  *  - lifecycle 也在每个 runAgentCore 实例化一次,登记 grep/glob/codegraph 等 producer
  *    与 read/edit/write 的 consumer 关系;孤立+老化自动 STUB(观察类工具永不到 STUB)。
  *  - 开关关闭时 lifecycle=null 完全跳过。 */
-function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runtimeContextState = contextState) {
-    const succeeded = isToolResultSuccess(output);
+function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runtimeContextState = contextState, succeededOverride) {
+    const succeeded = succeededOverride ?? isToolResultSuccess(output);
     const ageAware = config.contextOptimize ? ageAwareStateFor(history) : null;
     const encodingContext = ageAware?.preparePush(tc, succeeded);
     const msg = {
@@ -157,7 +171,37 @@ export async function runAgentCore(opts) {
     const savedMode = getAgentMode();
     // 本轮计时:从入口到完毕(正常 return / 达上限),供 finally 打 ✻ Worked for 摘要行。
     const t0 = Date.now();
+    const traceSessionId = opts.traceContext?.sessionId ?? getCurrentSessionId() ?? `ephemeral-${process.pid}`;
+    const traceTurnId = opts.traceContext?.turnId ?? getCurrentTurnId();
+    let currentTraceStep;
+    let abortTraced = false;
+    const emitTrace = (type, data = {}, ids = {}) => {
+        try {
+            opts.onTraceEvent?.(createTraceEvent({
+                sessionId: traceSessionId,
+                turnId: traceTurnId,
+                type,
+                ...(currentTraceStep === undefined ? {} : {
+                    step: currentTraceStep,
+                    stepId: `${traceTurnId}:step:${currentTraceStep}`,
+                }),
+                ...ids,
+                data,
+            }));
+        }
+        catch {
+            // Trace is best-effort and must never alter execution.
+        }
+    };
+    emitTrace('turn_start', { mode: getAgentMode() });
     let done = false; // 正常完毕 / 达上限 true;中断 false(不显摘要)
+    let traceStatus = 'error';
+    let toolCallCount = 0;
+    let latestValidation;
+    const initialMutationVersion = getCurrentTurnMutationState().version;
+    let validatedMutationVersion = initialMutationVersion;
+    let fullyValidatedMutationVersion = initialMutationVersion;
+    const validator = opts.validator ?? createAutomaticValidator();
     // 本轮 token 累计:每步 chat() 返回后把 result.usage 累加,供 onDone 摘要行 + AgentRunResult.usage
     // 透传给 repl(显示在底栏模式 chip 右边)。未开启 include_usage 或全失败时为 undefined。
     let turnUsage;
@@ -217,8 +261,8 @@ export async function runAgentCore(opts) {
     let mode = 'idle';
     let gotText = false;
     let lastChar = '';
-    // 早退重探:本 turn 已执行过工具但模型突然返回无工具调用 + 极短/空文本 → 推一条提示让模型继续,
-    // 而非直接退出。每 turn 最多触发 1 次,防死循环。弱模型在探索中途偶尔"说完"即此兜底。
+    // 早退重探:本 turn 已执行过工具但模型突然返回无工具调用 + 空文本 → 推一条提示让模型继续。
+    // 短回复也可能是合法完成结果，不再按字符数误判；每 turn 最多触发 1 次以防死循环。
     let nudgeCount = 0;
     let hadToolsThisTurn = false;
     const onText = (s) => {
@@ -240,6 +284,10 @@ export async function runAgentCore(opts) {
     // 中断还原:停 spinner + 补换行 + (已中断)提示 + history 还原到本 turn 前 + 模式还原。
     // 两处共用:① await chat() 抛 AbortError 的 catch;② 工具被 abort 杀后循环顶检查。
     const abortRestore = () => {
+        if (!abortTraced) {
+            emitTrace('abort', { phase: 'observed', reason: 'signal' });
+            abortTraced = true;
+        }
         hooks.onAbort?.();
         history.length = 0;
         history.push(...savedHistory);
@@ -248,279 +296,592 @@ export async function runAgentCore(opts) {
     };
     try {
         for (let step = 0; step < maxSteps; step++) {
-            // 上一步工具被 abort 杀(run_command/web_fetch 等)→ signal.aborted,直接还原退出,不等 maybeCompact + chat()
-            if (signal?.aborted) {
-                abortRestore();
-                return { completed: false, finalText: null };
-            }
-            // 本步只计算一次实际工具集合，调度、请求和 usage 校准必须使用完全相同的 schema。
-            const activeTools = opts.toolsOverride
-                ?? (getAgentMode() === 'plan' ? planChatTools : chatTools);
-            const requestBaseURL = config.baseURL;
-            const requestModel = config.model;
-            const storedCalibration = getTokenCalibration(requestBaseURL, requestModel, activeTools);
-            runtimeContextState.correction = storedCalibration.correction;
-            runtimeContextState.calibrationSamples = storedCalibration.samples;
-            // 初次 tool push 只做保守编码；预算评估前先对 Cold 且 age 达阈值的旧结果降级，
-            // 避免 scheduler 根据马上会被 sweep 的陈旧占用误触发 history compact。
-            ageAware?.sweep(history, userTurnBoundary(history, HOT_TURN_WINDOW));
-            // 步前:五区 Budget Scheduler 在优化后的 history 上决策；开关关闭时退化回原 maybeCompact 路径。
-            // 此时 spinner 已停,通知行干净。
-            let historyRebuilt = false;
-            if (scheduler) {
-                historyRebuilt = await scheduler.runStep(history, step, activeTools);
-            }
-            else {
-                const compactResult = await maybeCompact(history, undefined, undefined, runtimeContextState, activeTools);
-                historyRebuilt = compactResult?.historyRebuilt === true;
-            }
-            // compact 用新消息数组原地重建 history 后，所有按消息位置恢复的状态都需重建。
-            if (historyRebuilt) {
-                if (lifecycle) {
-                    lifecycle = createLifecycleEngine(history);
-                    runtimeContextState.lifecycleStats = lifecycle.stats();
-                }
-                ageAware?.rehydrate(history);
-            }
-            hooks.onStepStart?.(); // 主 agent:spinner.start('思考中')
-            mode = 'idle';
-            gotText = false;
-            lastChar = '';
-            let result;
+            currentTraceStep = step;
+            const stepStartedAt = Date.now();
+            emitTrace('step_start', { ordinal: step });
             try {
-                result = await chat(history, { onText, onToolCall }, signal, activeTools);
-            }
-            catch (e) {
-                // 中断(用户运行中 Ctrl+C):chat() 抛 AbortError(signal.aborted)→ 还原 history + 模式 + return(不抛)。
-                // 工具执行现已串 signal:run_command/web_fetch 被 abort 即时杀,循环顶检查兜底(不会留未配对 tool_call_id)。
-                if (signal?.aborted ||
-                    (e instanceof Error &&
-                        (e.name === 'AbortError' || e.name === 'APIUserAbortError'))) {
+                // 上一步工具被 abort 杀(run_command/web_fetch 等)→ signal.aborted,直接还原退出,不等 maybeCompact + chat()
+                if (signal?.aborted) {
                     abortRestore();
-                    return { completed: false, finalText: null };
+                    traceStatus = 'aborted';
+                    const mutation = getCurrentTurnMutationState();
+                    return {
+                        completed: false,
+                        terminationReason: 'aborted',
+                        finalText: null,
+                        validation: latestValidation,
+                        changedFiles: mutation.changedFiles.map((item) => item.path),
+                    };
                 }
-                throw e;
-            }
-            runtimeContextState.lastUsage = result.usage; // 供 /context 与状态行显示实测 token
-            addUsage(result.usage); // 本轮累计:onDone 摘要行 + AgentRunResult.usage 透传
-            // 用本次实际发送的 tools 计算分母，再以 EWMA 更新 provider/model/tool-set 校准。
-            // 只持久化比例与样本数；无 usage 或短 prompt 时保持既有值。
-            if (result.usage?.promptTokens && result.usage.promptTokens > 100) {
-                const estimated = estimatePromptTokens(history, activeTools);
-                const updated = updateTokenCalibration(requestBaseURL, requestModel, activeTools, estimated, result.usage.promptTokens);
-                runtimeContextState.correction = updated.correction;
-                runtimeContextState.calibrationSamples = updated.samples;
-            }
-            hooks.onChatDone?.(); // 主 agent:spinner.stop()
-            // lastUsage 已更新:触发状态行 context 用量条重算+重画,运行中不再冻结在轮首。
-            onContextUpdate?.();
-            if (result.toolCalls.length > 0) {
-                hadToolsThisTurn = true;
-                // 流式正文末尾补换行(若 onToolCall 已补则 lastChar='\n',此处 no-op);防 ● 行黏在正文行尾
-                if (mode !== 'idle' && lastChar !== '\n')
-                    hooks.onTextEnd?.();
-                // 带工具调用的 assistant 消息原样回灌(OpenAI 格式要求)
-                history.push({
-                    role: 'assistant',
-                    content: result.content,
-                    tool_calls: result.toolCalls.map((tc) => ({
-                        id: tc.id,
-                        type: 'function',
-                        function: { name: tc.name, arguments: tc.arguments },
-                    })),
+                // 本步只计算一次实际工具集合，调度、请求和 usage 校准必须使用完全相同的 schema。
+                const activeTools = opts.toolsOverride
+                    ?? (getAgentMode() === 'plan' ? planChatTools : chatTools);
+                const requestBaseURL = config.baseURL;
+                const requestModel = config.model;
+                const storedCalibration = getTokenCalibration(requestBaseURL, requestModel, activeTools);
+                runtimeContextState.correction = storedCalibration.correction;
+                runtimeContextState.calibrationSamples = storedCalibration.samples;
+                // 初次 tool push 只做保守编码；预算评估前先对 Cold 且 age 达阈值的旧结果降级，
+                // 避免 scheduler 根据马上会被 sweep 的陈旧占用误触发 history compact。
+                ageAware?.sweep(history, userTurnBoundary(history, HOT_TURN_WINDOW));
+                // 步前:五区 Budget Scheduler 在优化后的 history 上决策；开关关闭时退化回原 maybeCompact 路径。
+                // 此时 spinner 已停,通知行干净。
+                let historyRebuilt = false;
+                const compactStartedAt = Date.now();
+                if (scheduler) {
+                    historyRebuilt = await scheduler.runStep(history, step, activeTools);
+                    if (scheduler.lastRunLog?.compactHistoryCalled) {
+                        emitTrace('compact', {
+                            source: 'automatic',
+                            reason: 'scheduled',
+                            historyRebuilt,
+                            durationMs: Date.now() - compactStartedAt,
+                        });
+                    }
+                }
+                else {
+                    const compactResult = await maybeCompact(history, undefined, undefined, runtimeContextState, activeTools);
+                    historyRebuilt = compactResult?.historyRebuilt === true;
+                    if (compactResult) {
+                        emitTrace('compact', {
+                            source: 'automatic_fallback',
+                            reason: compactResult.reason,
+                            compacted: compactResult.compacted,
+                            historyRebuilt,
+                            estimateBefore: compactResult.estimateBefore,
+                            estimateAfter: compactResult.estimateAfter,
+                            durationMs: Date.now() - compactStartedAt,
+                        });
+                    }
+                }
+                // compact 用新消息数组原地重建 history 后，所有按消息位置恢复的状态都需重建。
+                if (historyRebuilt) {
+                    if (lifecycle) {
+                        lifecycle = createLifecycleEngine(history);
+                        runtimeContextState.lifecycleStats = lifecycle.stats();
+                    }
+                    ageAware?.rehydrate(history);
+                }
+                hooks.onStepStart?.(); // 主 agent:spinner.start('思考中')
+                mode = 'idle';
+                gotText = false;
+                lastChar = '';
+                let result;
+                const modelStartedAt = Date.now();
+                const provider = safeProviderId(requestBaseURL);
+                emitTrace('model_start', { model: requestModel, provider });
+                try {
+                    result = await chat(history, {
+                        onText,
+                        onToolCall,
+                        onRetry: (retry) => emitTrace('model_retry', {
+                            model: requestModel,
+                            provider,
+                            attempt: retry.attempt,
+                            nextAttempt: retry.nextAttempt,
+                            waitMs: retry.waitMs,
+                            code: retry.code,
+                        }),
+                    }, signal, activeTools);
+                }
+                catch (e) {
+                    const errorValue = e && typeof e === 'object'
+                        ? e
+                        : undefined;
+                    emitTrace('model_end', {
+                        model: requestModel,
+                        provider,
+                        status: signal?.aborted ? 'aborted' : 'error',
+                        code: typeof errorValue?.status === 'number'
+                            ? `HTTP_${errorValue.status}`
+                            : errorValue?.code ?? errorValue?.name ?? 'MODEL_ERROR',
+                        durationMs: Date.now() - modelStartedAt,
+                    });
+                    // 中断(用户运行中 Ctrl+C):chat() 抛 AbortError(signal.aborted)→ 还原 history + 模式 + return(不抛)。
+                    // 工具执行现已串 signal:run_command/web_fetch 被 abort 即时杀,循环顶检查兜底(不会留未配对 tool_call_id)。
+                    if (signal?.aborted ||
+                        (e instanceof Error &&
+                            (e.name === 'AbortError' || e.name === 'APIUserAbortError'))) {
+                        abortRestore();
+                        traceStatus = 'aborted';
+                        const mutation = getCurrentTurnMutationState();
+                        return {
+                            completed: false,
+                            terminationReason: 'aborted',
+                            finalText: null,
+                            validation: latestValidation,
+                            changedFiles: mutation.changedFiles.map((item) => item.path),
+                        };
+                    }
+                    throw e;
+                }
+                emitTrace('model_end', {
+                    model: requestModel,
+                    provider,
+                    status: 'success',
+                    durationMs: Date.now() - modelStartedAt,
+                    promptTokens: result.usage?.promptTokens,
+                    completionTokens: result.usage?.completionTokens,
+                    totalTokens: result.usage?.totalTokens,
+                    cachedTokens: result.usage?.cachedTokens,
+                    reasoningTokens: result.usage?.reasoningTokens,
                 });
-                // 工具分组执行(保 tool_calls 原顺序):连续的只读工具(READ_TOOL_NAMES)成组并发——先一次性
-                // 渲染全部 header，让摘要在任何同步工具真正执行前立即可见；随后启动全部 executeTool，
-                // 再按原顺序逐个 await + 回灌结果。
-                // mutation(write_file/edit_file)及 run_command/use_skill 各为单步串行屏障——mutation 串行保
-                // recordMutation 调用序 = 回滚快照序(executeTool 内写前记 before 快照,同文件多次写需按序)。
-                // 渲染与 history 回灌一律按原顺序;并发只影响执行时序,tool_call_id 仍按序配对。
-                // executeTool 永不抛错(调度器 try/catch 返字符串),故 await 单个 promise 不会抛(永远 resolve 为字符串)。
-                const calls = result.toolCalls;
-                let i = 0;
-                while (i < calls.length) {
-                    if (READ_TOOL_NAMES.has(calls[i].name)) {
-                        // 收集连续只读组(≥1),并发执行:先渲染所有 header，再一次性启动所有
-                        // (executeTool 调用即开始 I/O)，最后按原顺序逐个 await + 回灌。
-                        // 必须先 header 后 execute：grep 等同步快速工具会在 executeTool 返回 Promise 前
-                        // 已经完成；若先 started.map，用户只能在工具完成后才看到摘要与其前面的换行。
-                        // 异步工具(web_fetch 等)并发跑、总耗时 ≈ 最慢一个;同步工具(glob/grep)map 时已顺序跑完,await 即返。
-                        let j = i;
-                        while (j < calls.length && READ_TOOL_NAMES.has(calls[j].name))
-                            j++;
-                        const batch = calls.slice(i, j);
-                        for (const tc of batch)
-                            hooks.onToolHeader?.(tc);
-                        hooks.onToolStart?.(batch[0].name);
-                        const started = batch.map((tc) => executeTool(tc.name, tc.arguments, signal, { dropContext }));
-                        for (let k = 0; k < batch.length; k++) {
-                            const tc = batch[k];
-                            const output = await started[k];
-                            hooks.onToolResult?.(tc, output, null, null, 1); // 只读工具无 diff
-                            // Thrashing:history 里附 hint(UI 已用干净 output 渲染,避免屏幕噪声)
-                            const hint = recordAndHint(tc.name, tc.arguments);
-                            pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
-                        }
-                        hooks.onToolDone?.();
-                        i = j;
+                runtimeContextState.lastUsage = result.usage; // 供 /context 与状态行显示实测 token
+                addUsage(result.usage); // 本轮累计:onDone 摘要行 + AgentRunResult.usage 透传
+                // 用本次实际发送的 tools 计算分母，再以 EWMA 更新 provider/model/tool-set 校准。
+                // 只持久化比例与样本数；无 usage 或短 prompt 时保持既有值。
+                if (result.usage?.promptTokens && result.usage.promptTokens > 100) {
+                    const estimated = estimatePromptTokens(history, activeTools);
+                    const updated = updateTokenCalibration(requestBaseURL, requestModel, activeTools, estimated, result.usage.promptTokens);
+                    runtimeContextState.correction = updated.correction;
+                    runtimeContextState.calibrationSamples = updated.samples;
+                }
+                hooks.onChatDone?.(); // 主 agent:spinner.stop()
+                // lastUsage 已更新:触发状态行 context 用量条重算+重画,运行中不再冻结在轮首。
+                onContextUpdate?.();
+                if (result.toolCalls.length > 0) {
+                    toolCallCount += result.toolCalls.length;
+                    hadToolsThisTurn = true;
+                    // 流式正文末尾补换行(若 onToolCall 已补则 lastChar='\n',此处 no-op);防 ● 行黏在正文行尾
+                    if (mode !== 'idle' && lastChar !== '\n')
+                        hooks.onTextEnd?.();
+                    // 带工具调用的 assistant 消息原样回灌(OpenAI 格式要求)
+                    history.push({
+                        role: 'assistant',
+                        content: result.content,
+                        tool_calls: result.toolCalls.map((tc) => ({
+                            id: tc.id,
+                            type: 'function',
+                            function: { name: tc.name, arguments: tc.arguments },
+                        })),
+                    });
+                    // 工具分组执行(保 tool_calls 原顺序)：safe parallel 工具照常并发；连续
+                    // resource-locked mutation 先按序完成权限预检，再按 canonical resource lock 启动。
+                    // registry 对所有真实资源访问统一持锁，所以不同 Agent 间的 read/write/process 也不会竞态。
+                    // 串行工具仍是本调用列表内的屏障；渲染/history 回灌始终按原 tool_calls 顺序。
+                    // executeToolOutcome 永不抛错，失败通过结构化 status/code 返回。
+                    const calls = result.toolCalls;
+                    const tracedCalls = calls.map((tc, index) => ({
+                        toolCallId: `${traceTurnId}:step:${step}:tool:${index}`,
+                        args: summarizeToolArguments(tc.arguments),
+                    }));
+                    for (let index = 0; index < calls.length; index++) {
+                        const tc = calls[index];
+                        const traceCall = tracedCalls[index];
+                        emitTrace('tool_call_start', {
+                            tool: tc.name,
+                            argumentHash: traceCall.args.sha256,
+                            arguments: traceCall.args,
+                            attempt: 1,
+                            retry: 0,
+                        }, {
+                            toolCallId: traceCall.toolCallId,
+                            ...(tc.id ? { providerToolCallId: tc.id } : {}),
+                        });
                     }
-                    else if (calls[i].name === 'task') {
-                        // task 并发组:连续的 task 调用成组并发(子 agent 并行跑,各自独立 history)。
-                        // 一次性启动全部(executeTool 即 spawnAgent,子 agent 开始跑),再并发 await + 渲染。
-                        // task 是长任务,并发 fan-out 总耗时 ≈ 最慢一个子 agent。
-                        // task 与 mutation/run_command 之间串行屏障(task 子 agent 可能有文件改动,不能和 write_file 乱序)。
-                        // 渲染:先批量打印所有 ● 头 + 启 spinner(让用户看到多个 task 同时在跑),再逐个 await 出结果。
-                        // (若像只读组那样「header → await → result」串行,长 task 的第二个 header 要等第一个跑完才出现,
-                        //  视觉上只有一个在跑——与并发事实不符。)
-                        //
-                        // plan 模式防御 backstop(与单步串行分支同语义):schema 已剔除 task,正常不会进这里;
-                        // 防后端幻觉调用——不执行(绝不派生子 agent,子 agent 可能有 mutation,违反只读),直接返错回灌。
-                        if (getAgentMode() === 'plan') {
-                            const tc = calls[i];
-                            hooks.onToolHeader?.(tc);
-                            const err = `错误:计划模式下禁用工具 ${tc.name}(仅读探查,不改动文件 / 不跑命令)`;
-                            hooks.onToolResult?.(tc, err, null, null, 1);
-                            // Thrashing:同上
-                            const hint = recordAndHint(tc.name, tc.arguments);
-                            pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
+                    const traceToolEnd = (tc, index, outcome) => {
+                        const traceCall = tracedCalls[index];
+                        emitTrace('tool_call_end', {
+                            tool: tc.name,
+                            argumentHash: traceCall.args.sha256,
+                            status: outcome.status,
+                            code: outcome.code,
+                            retryable: outcome.retryable,
+                            durationMs: outcome.durationMs ?? 0,
+                            retry: 0,
+                            changedFiles: outcome.changedFiles ?? [],
+                        }, {
+                            toolCallId: traceCall.toolCallId,
+                            ...(tc.id ? { providerToolCallId: tc.id } : {}),
+                        });
+                    };
+                    let i = 0;
+                    while (i < calls.length) {
+                        const currentCall = calls[i];
+                        if (getRuntimeDisabledTools().has(currentCall.name)) {
+                            hooks.onToolHeader?.(currentCall);
+                            const error = t('task.disabled');
+                            const outcome = {
+                                status: 'denied',
+                                code: 'TOOL_DISABLED',
+                                retryable: false,
+                                output: error,
+                                changedFiles: [],
+                                durationMs: 0,
+                            };
+                            hooks.onToolResult?.(currentCall, error, null, null, 1);
+                            const hint = recordAndHint(currentCall.name, currentCall.arguments);
+                            pushToolResult(history, currentCall, hint ? `${error}${hint}` : error, relprune, lifecycle, scheduler, runtimeContextState, false);
+                            traceToolEnd(currentCall, i, outcome);
                             i++;
                             continue;
                         }
-                        let j = i;
-                        while (j < calls.length && calls[j].name === 'task')
-                            j++;
-                        const batch = calls.slice(i, j);
-                        // 权限预检查:逐个 task 弹确认面板(在启动子 agent 之前,体验:先问再执行)。
-                        // 拒绝的 task 直接跳过,不启动子 agent;放行的收集到 allowedBatch。
-                        const allowedBatch = [];
-                        for (const tc of batch) {
+                        if (isParallelTool(currentCall.name)) {
+                            // 收集连续只读组(≥1),并发执行:先渲染所有 header，再一次性启动所有
+                            // (executeTool 调用即开始 I/O)，最后按原顺序逐个 await + 回灌。
+                            // 必须先 header 后 execute：grep 等同步快速工具会在 executeTool 返回 Promise 前
+                            // 已经完成；若先 started.map，用户只能在工具完成后才看到摘要与其前面的换行。
+                            // 异步工具(web_fetch 等)并发跑、总耗时 ≈ 最慢一个;同步工具(glob/grep)map 时已顺序跑完,await 即返。
+                            let j = i;
+                            while (j < calls.length && isParallelTool(calls[j].name))
+                                j++;
+                            const batch = calls.slice(i, j);
+                            for (const tc of batch)
+                                hooks.onToolHeader?.(tc);
+                            hooks.onToolStart?.(batch[0].name);
+                            const started = batch.map((tc) => executeToolOutcome(tc.name, tc.arguments, signal, { dropContext }));
+                            for (let k = 0; k < batch.length; k++) {
+                                const tc = batch[k];
+                                const outcome = await started[k];
+                                traceToolEnd(tc, i + k, outcome);
+                                const output = outcome.output;
+                                hooks.onToolResult?.(tc, output, null, null, 1); // 并行工具无 diff
+                                // Thrashing:history 里附 hint(UI 已用干净 output 渲染,避免屏幕噪声)
+                                const hint = recordAndHint(tc.name, tc.arguments);
+                                pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
+                            }
+                            hooks.onToolDone?.();
+                            i = j;
+                        }
+                        else if (isResourceLockedTool(currentCall.name) &&
+                            !(getAgentMode() === 'plan' && getPlanDisabledTools().has(currentCall.name))) {
+                            // 连续文件 mutation：权限确认仍严格按原序进行；全部 preflight 完成后再启动。
+                            // 每个执行在 registry 内按 canonical path 获取锁，不同文件可并发，同文件别名会排队。
+                            let j = i;
+                            while (j < calls.length &&
+                                isResourceLockedTool(calls[j].name) &&
+                                !getRuntimeDisabledTools().has(calls[j].name) &&
+                                !(getAgentMode() === 'plan' && getPlanDisabledTools().has(calls[j].name)))
+                                j++;
+                            const batch = calls.slice(i, j);
+                            const entries = [];
+                            for (let k = 0; k < batch.length; k++) {
+                                const tc = batch[k];
+                                const parsed = parseArgs(tc.arguments);
+                                const tool = tools.find((candidate) => candidate.name === tc.name);
+                                let denied;
+                                if (tool) {
+                                    const perm = await checkPermission(tool, parsed ?? {}, signal);
+                                    emitTrace('permission', {
+                                        source: 'agent_tool',
+                                        tool: tc.name,
+                                        decision: perm,
+                                        argumentHash: tracedCalls[i + k].args.sha256,
+                                    }, {
+                                        toolCallId: tracedCalls[i + k].toolCallId,
+                                        ...(tc.id ? { providerToolCallId: tc.id } : {}),
+                                    });
+                                    if (perm === 'deny')
+                                        denied = deniedOutcome(tc.name);
+                                }
+                                entries.push({
+                                    tc,
+                                    parsed,
+                                    diff: { preWriteOld: null, editStartLine: 1 },
+                                    ...(denied ? { denied } : {}),
+                                });
+                            }
+                            for (const entry of entries)
+                                hooks.onToolHeader?.(entry.tc);
+                            const firstAllowed = entries.find((entry) => !entry.denied);
+                            if (firstAllowed)
+                                hooks.onToolStart?.(firstAllowed.tc.name);
+                            const started = entries.map((entry) => entry.denied
+                                ? Promise.resolve(entry.denied)
+                                : executeToolOutcome(entry.tc.name, entry.tc.arguments, signal, {
+                                    dropContext,
+                                    onLockAcquired: (lockedArgs) => {
+                                        entry.diff = readDiffContext(entry.tc, lockedArgs);
+                                    },
+                                }));
+                            for (let k = 0; k < entries.length; k++) {
+                                const entry = entries[k];
+                                const outcome = await started[k];
+                                traceToolEnd(entry.tc, i + k, outcome);
+                                hooks.onToolResult?.(entry.tc, outcome.output, entry.denied ? null : entry.parsed, entry.diff.preWriteOld, entry.diff.editStartLine);
+                                const hint = recordAndHint(entry.tc.name, entry.tc.arguments);
+                                pushToolResult(history, entry.tc, hint ? `${outcome.output}${hint}` : outcome.output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
+                                if (isMutationTool(entry.tc.name) && outcome.status === 'success') {
+                                    const mutationPath = entry.parsed?.path;
+                                    if (typeof mutationPath === 'string' && mutationPath) {
+                                        relprune?.observeMutation(history, mutationPath);
+                                        lifecycle?.pushMutation(history, history.length - 1, mutationPath);
+                                        runtimeContextState.lifecycleStats = lifecycle?.stats();
+                                    }
+                                }
+                            }
+                            if (firstAllowed)
+                                hooks.onToolDone?.();
+                            i = j;
+                        }
+                        else {
+                            // 单步串行(mutation / run_command / use_skill)——逐个执行,保快照序
+                            const tc = calls[i];
+                            // plan 模式防御 backstop:schema 已剔除这些工具,正常不会进这里;防后端幻觉调用——
+                            // 不执行,直接返错回灌(让模型看到「plan 模式禁用」并停止),绝不写盘 / 跑命令。
+                            if (getAgentMode() === 'plan' && getPlanDisabledTools().has(tc.name)) {
+                                hooks.onToolHeader?.(tc);
+                                const err = `错误:计划模式下禁用工具 ${tc.name}(仅读探查,不改动文件 / 不跑命令)`;
+                                const outcome = {
+                                    status: 'denied',
+                                    code: 'MODE_DENIED',
+                                    retryable: false,
+                                    output: err,
+                                    changedFiles: [],
+                                    durationMs: 0,
+                                };
+                                hooks.onToolResult?.(tc, err, null, null, 1);
+                                // Thrashing:同上
+                                const hint = recordAndHint(tc.name, tc.arguments);
+                                pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
+                                traceToolEnd(tc, i, outcome);
+                                i++;
+                                continue;
+                            }
+                            // 权限预检查:在渲染 ● 头之前弹确认面板(体验:先问再执行,而非执行完再问)。
+                            // 拒绝时只渲染拒绝结果,不渲染执行头;放行则继续走 header → start → executeTool 流程。
                             const parsed = parseArgs(tc.arguments);
                             const tool = tools.find((t) => t.name === tc.name);
                             if (tool) {
                                 const perm = await checkPermission(tool, parsed ?? {}, signal);
+                                emitTrace('permission', {
+                                    source: 'agent_tool',
+                                    tool: tc.name,
+                                    decision: perm,
+                                    argumentHash: tracedCalls[i].args.sha256,
+                                }, {
+                                    toolCallId: tracedCalls[i].toolCallId,
+                                    ...(tc.id ? { providerToolCallId: tc.id } : {}),
+                                });
                                 if (perm === 'deny') {
                                     hooks.onToolHeader?.(tc);
-                                    const err = `错误:用户拒绝了工具 ${tc.name} 的执行。`;
-                                    hooks.onToolResult?.(tc, err, null, null, 1);
+                                    const outcome = deniedOutcome(tc.name);
+                                    hooks.onToolResult?.(tc, outcome.output, null, null, 1);
                                     const hint = recordAndHint(tc.name, tc.arguments);
-                                    pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
+                                    pushToolResult(history, tc, hint ? `${outcome.output}${hint}` : outcome.output, relprune, lifecycle, scheduler, runtimeContextState, false);
+                                    traceToolEnd(tc, i, outcome);
+                                    i++;
                                     continue;
                                 }
                             }
-                            allowedBatch.push(tc);
-                        }
-                        if (allowedBatch.length === 0) {
-                            i = j;
-                            continue; // 全部被拒绝,跳过执行
-                        }
-                        const started = allowedBatch.map((tc) => executeTool(tc.name, tc.arguments, signal, { dropContext }));
-                        // 先批量打印所有头 + 启 spinner(多 task 并发,spinner 只显一个,但 ● 头都打出来)
-                        for (const tc of allowedBatch) {
                             hooks.onToolHeader?.(tc);
-                        }
-                        hooks.onToolStart?.(allowedBatch[0].name); // spinner:多 task 共用一个「执行 task…」
-                        // 逐个 await 出结果(按 tool_calls 原序,保 tool_call_id 配对);结果到即渲染 ↳
-                        for (let k = 0; k < allowedBatch.length; k++) {
-                            const tc = allowedBatch[k];
-                            const output = await started[k];
-                            hooks.onToolResult?.(tc, output, null, null, 1); // task 结果是摘要,无 diff
-                            // Thrashing:同上
+                            const mutationParsed = isMutationTool(tc.name)
+                                ? parsed
+                                : null;
+                            let diff = readDiffContext(tc, mutationParsed);
+                            hooks.onToolStart?.(tc.name);
+                            const outcome = await executeToolOutcome(tc.name, tc.arguments, signal, {
+                                dropContext,
+                                onLockAcquired: (lockedArgs) => {
+                                    if (mutationParsed)
+                                        diff = readDiffContext(tc, lockedArgs);
+                                },
+                            });
+                            traceToolEnd(tc, i, outcome);
+                            const output = outcome.output;
+                            hooks.onToolDone?.();
+                            hooks.onToolResult?.(tc, output, mutationParsed, diff.preWriteOld, diff.editStartLine);
+                            // Thrashing:同上(history 附 hint,UI 干净)
                             const hint = recordAndHint(tc.name, tc.arguments);
-                            pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
-                        }
-                        hooks.onToolDone?.();
-                        i = j;
-                    }
-                    else {
-                        // 单步串行(mutation / run_command / use_skill)——逐个执行,保快照序
-                        const tc = calls[i];
-                        // plan 模式防御 backstop:schema 已剔除这些工具,正常不会进这里;防后端幻觉调用——
-                        // 不执行,直接返错回灌(让模型看到「plan 模式禁用」并停止),绝不写盘 / 跑命令。
-                        if (getAgentMode() === 'plan' && getPlanDisabledTools().has(tc.name)) {
-                            hooks.onToolHeader?.(tc);
-                            const err = `错误:计划模式下禁用工具 ${tc.name}(仅读探查,不改动文件 / 不跑命令)`;
-                            hooks.onToolResult?.(tc, err, null, null, 1);
-                            // Thrashing:同上
-                            const hint = recordAndHint(tc.name, tc.arguments);
-                            pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
-                            i++;
-                            continue;
-                        }
-                        // 权限预检查:在渲染 ● 头之前弹确认面板(体验:先问再执行,而非执行完再问)。
-                        // 拒绝时只渲染拒绝结果,不渲染执行头;放行则继续走 header → start → executeTool 流程。
-                        const parsed = parseArgs(tc.arguments);
-                        const tool = tools.find((t) => t.name === tc.name);
-                        if (tool) {
-                            const perm = await checkPermission(tool, parsed ?? {}, signal);
-                            if (perm === 'deny') {
-                                hooks.onToolHeader?.(tc);
-                                const err = `错误:用户拒绝了工具 ${tc.name} 的执行。`;
-                                hooks.onToolResult?.(tc, err, null, null, 1);
-                                const hint = recordAndHint(tc.name, tc.arguments);
-                                pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
-                                i++;
-                                continue;
-                            }
-                        }
-                        hooks.onToolHeader?.(tc);
-                        const mutationParsed = isMutationTool(tc.name)
-                            ? parsed
-                            : null;
-                        const { preWriteOld, editStartLine } = readDiffContext(tc, mutationParsed);
-                        hooks.onToolStart?.(tc.name);
-                        const output = await executeTool(tc.name, tc.arguments, signal, { dropContext });
-                        hooks.onToolDone?.();
-                        hooks.onToolResult?.(tc, output, mutationParsed, preWriteOld, editStartLine);
-                        // Thrashing:同上(history 附 hint,UI 干净)
-                        const hint = recordAndHint(tc.name, tc.arguments);
-                        pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
-                        // 只有成功 mutation 才会使旧 read 失效；pruner 与 lifecycle 独立启停。
-                        if (isMutationTool(tc.name) && isToolResultSuccess(output)) {
-                            const mp = mutationParsed?.path;
-                            if (typeof mp === 'string' && mp) {
-                                relprune?.observeMutation(history, mp);
-                                lifecycle?.pushMutation(history, history.length - 1, mp);
-                                runtimeContextState.lifecycleStats = lifecycle?.stats();
+                            pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
+                            // 只有成功 mutation 才会使旧 read 失效；pruner 与 lifecycle 独立启停。
+                            if (isMutationTool(tc.name) && outcome.status === 'success') {
+                                const mp = mutationParsed?.path;
+                                if (typeof mp === 'string' && mp) {
+                                    relprune?.observeMutation(history, mp);
+                                    lifecycle?.pushMutation(history, history.length - 1, mp);
+                                    runtimeContextState.lifecycleStats = lifecycle?.stats();
+                                }
                             }
+                            i++;
                         }
-                        i++;
+                    }
+                    // 工具步末尾补一空行:与下一轮的思考 / 正文分隔(否则 ↳ 后紧接 ▎ 思考,无空行不好看;
+                    // 与正文→● 的 1 空行对称)。工具结果已以 \n 收尾,此处再补 \n 恰好 1 空行。
+                    hooks.onToolBatchEnd?.();
+                    // 刷新中断快照:工具全部执行完毕后,history 处于一致状态(assistant+tool_calls+tool 结果完整),
+                    // 此时中断可安全保留这些已完成的消息,只丢弃下一轮未完成的 chat() 响应。
+                    savedHistory = history.slice();
+                    continue; // 带着工具结果再调一次 LLM
+                }
+                if (mode !== 'idle' && lastChar !== '\n')
+                    hooks.onTextEnd?.(); // 流式末尾补换行
+                // 早退保护:本 turn 已执行过工具调用,但模型突然返回无工具 + 极短/空文本 → 很可能是在探索中途
+                // 提前"说完了"。此时推一条 user 提示消息让模型继续探索,而非直接退出。每 turn 最多 1 次,防死循环。
+                // 早退重探只处理真正的空回复。短回复可能是合法完成结果（例如精确状态标记）；
+                // 仅凭字符数继续调用会重复输出，并产生一次完整的额外模型请求。
+                const replyIsEmpty = (result.content?.trim().length ?? 0) === 0;
+                if (hadToolsThisTurn && nudgeCount < 1 && replyIsEmpty) {
+                    nudgeCount++;
+                    history.push({ role: 'assistant', content: result.content });
+                    history.push({
+                        role: 'user',
+                        content: 'You stopped before completing the task. Please continue investigating — call more tools if needed, or provide a complete answer based on what you have gathered so far.',
+                    });
+                    continue; // 带着提示再调一次 LLM
+                }
+                // 没有工具调用:候选正文已流式打印。若本轮有新的代码变更，先通过框架验证门；
+                // failed 作为 system observation 风格的 user 消息回灌，不能伪造无配对的 tool 消息。
+                if (!gotText)
+                    hooks.onNoReply?.();
+                const candidate = { role: 'assistant', content: result.content };
+                const mutationBeforeValidation = getCurrentTurnMutationState();
+                const shouldValidate = opts.autoValidate === true &&
+                    getAgentMode() !== 'plan' &&
+                    (mutationBeforeValidation.version > validatedMutationVersion || latestValidation?.status === 'failed');
+                if (shouldValidate) {
+                    history.push(candidate);
+                    emitTrace('validation_start', {
+                        mutationVersion: mutationBeforeValidation.version,
+                        changedFiles: mutationBeforeValidation.changedFiles.map((item) => item.path),
+                    });
+                    try {
+                        latestValidation = await validator(signal, {
+                            onCommandStart: (command) => hooks.onValidationStart?.(command),
+                            onPermissionDecision: (permission) => {
+                                const summary = summarizeToolArguments(JSON.stringify(permission.arguments));
+                                emitTrace('permission', {
+                                    source: 'automatic_validation',
+                                    tool: permission.tool,
+                                    decision: permission.decision,
+                                    argumentHash: summary.sha256,
+                                });
+                            },
+                        });
+                    }
+                    catch (error) {
+                        const mutation = getCurrentTurnMutationState();
+                        const message = `Automatic validation failed to run: ${error instanceof Error ? error.message : String(error)}`;
+                        const status = signal?.aborted ? 'aborted' : 'failed';
+                        latestValidation = {
+                            status,
+                            level: 'V0',
+                            output: message,
+                            durationMs: 0,
+                            diagnostics: [{
+                                    level: 'V0', source: 'verifier', severity: 'error', code: 'VERIFIER_ERROR', message,
+                                }],
+                            stages: [],
+                            verificationComplete: false,
+                            fingerprint: `verifier-error-${mutation.version}`,
+                            inputFingerprint: `mutation-${mutation.version}`,
+                            inputMutationVersion: mutation.version,
+                            affectedPackages: [],
+                            changedFiles: mutation.changedFiles.map((item) => item.path),
+                            mutationVersion: mutation.version,
+                        };
+                    }
+                    emitTrace('validation_end', {
+                        status: latestValidation.status,
+                        level: latestValidation.level,
+                        durationMs: latestValidation.durationMs,
+                        verificationComplete: latestValidation.verificationComplete,
+                        skipReason: latestValidation.skipReason,
+                        fingerprint: latestValidation.fingerprint,
+                        mutationVersion: latestValidation.mutationVersion,
+                        stages: latestValidation.stages.map((stage) => ({
+                            level: stage.level,
+                            status: stage.status,
+                            adapter: stage.adapter,
+                            code: stage.diagnostics[0]?.code,
+                            durationMs: stage.durationMs,
+                            cached: stage.cached === true,
+                        })),
+                    });
+                    hooks.onValidationResult?.(latestValidation);
+                    validatedMutationVersion = latestValidation.mutationVersion;
+                    if (latestValidation.status === 'passed' && latestValidation.verificationComplete) {
+                        fullyValidatedMutationVersion = latestValidation.mutationVersion;
+                    }
+                    if (signal?.aborted || latestValidation.status === 'aborted') {
+                        abortRestore();
+                        traceStatus = 'aborted';
+                        const mutation = getCurrentTurnMutationState();
+                        return {
+                            completed: false,
+                            terminationReason: 'aborted',
+                            finalText: null,
+                            validation: latestValidation,
+                            changedFiles: mutation.changedFiles.map((item) => item.path),
+                        };
+                    }
+                    if (latestValidation.status === 'failed') {
+                        history.push({
+                            role: 'user',
+                            content: '[System observation: automatic validation failed]\n' +
+                                `Command: ${latestValidation.command ?? '(internal verifier)'}\n` +
+                                `${latestValidation.output}\n\n` +
+                                'Fix the reported problem, then finish the task. Do not claim success until validation passes.',
+                        });
+                        // 验证及其失败观察均已完整落入 history；下一步中断时可安全保留。
+                        savedHistory = history.slice();
+                        continue;
                     }
                 }
-                // 工具步末尾补一空行:与下一轮的思考 / 正文分隔(否则 ↳ 后紧接 ▎ 思考,无空行不好看;
-                // 与正文→● 的 1 空行对称)。工具结果已以 \n 收尾,此处再补 \n 恰好 1 空行。
-                hooks.onToolBatchEnd?.();
-                // 刷新中断快照:工具全部执行完毕后,history 处于一致状态(assistant+tool_calls+tool 结果完整),
-                // 此时中断可安全保留这些已完成的消息,只丢弃下一轮未完成的 chat() 响应。
-                savedHistory = history.slice();
-                continue; // 带着工具结果再调一次 LLM
+                else {
+                    history.push(candidate);
+                }
+                const finalMutation = getCurrentTurnMutationState();
+                done = true;
+                traceStatus = 'completed';
+                const verified = finalMutation.version <= fullyValidatedMutationVersion;
+                return {
+                    completed: true,
+                    terminationReason: verified ? 'completed' : 'completed_unverified',
+                    finalText: result.content,
+                    usage: turnUsage,
+                    validation: latestValidation,
+                    changedFiles: finalMutation.changedFiles.map((item) => item.path),
+                };
             }
-            if (mode !== 'idle' && lastChar !== '\n')
-                hooks.onTextEnd?.(); // 流式末尾补换行
-            // 早退保护:本 turn 已执行过工具调用,但模型突然返回无工具 + 极短/空文本 → 很可能是在探索中途
-            // 提前"说完了"。此时推一条 user 提示消息让模型继续探索,而非直接退出。每 turn 最多 1 次,防死循环。
-            // 判定标准:无 gotText(完全没输出)或正文极短(< 80 字符,通常是一句"我需要更多信息"级别的截断)。
-            const textLen = result.content?.trim().length ?? 0;
-            if (hadToolsThisTurn && nudgeCount < 1 && (!gotText || textLen < 80)) {
-                nudgeCount++;
-                history.push({ role: 'assistant', content: result.content });
-                history.push({
-                    role: 'user',
-                    content: 'You stopped before completing the task. Please continue investigating — call more tools if needed, or provide a complete answer based on what you have gathered so far.',
+            finally {
+                emitTrace('step_end', {
+                    durationMs: Date.now() - stepStartedAt,
+                    aborted: signal?.aborted === true,
                 });
-                continue; // 带着提示再调一次 LLM
             }
-            // 没有工具调用:流式正文即最终回复(已实时打印)
-            if (!gotText)
-                hooks.onNoReply?.();
-            history.push({ role: 'assistant', content: result.content });
-            done = true;
-            return { completed: true, finalText: result.content, usage: turnUsage };
         }
         hooks.onMaxSteps?.();
         done = true;
-        return { completed: true, finalText: null, usage: turnUsage };
+        traceStatus = 'max_steps';
+        const finalMutation = getCurrentTurnMutationState();
+        const hasUnverifiedChanges = finalMutation.version > fullyValidatedMutationVersion;
+        return {
+            completed: false,
+            terminationReason: hasUnverifiedChanges ? 'unverified_changes' : 'max_steps',
+            finalText: null,
+            usage: turnUsage,
+            validation: latestValidation,
+            changedFiles: finalMutation.changedFiles.map((item) => item.path),
+        };
     }
     finally {
+        const finalMutation = getCurrentTurnMutationState();
+        currentTraceStep = undefined;
+        emitTrace('turn_end', {
+            status: traceStatus,
+            durationMs: Date.now() - t0,
+            toolCalls: toolCallCount,
+            changedFiles: finalMutation.changedFiles.map((item) => item.path),
+            totalTokens: turnUsage?.totalTokens,
+            validationStatus: latestValidation?.status,
+        });
+        try {
+            opts.onTrace?.({
+                ts: new Date().toISOString(),
+                sessionId: traceSessionId,
+                turnId: traceTurnId,
+                status: traceStatus,
+                durationMs: Date.now() - t0,
+                toolCalls: toolCallCount,
+                changedFiles: finalMutation.changedFiles.map((item) => item.path),
+                usage: turnUsage,
+                validation: latestValidation,
+            });
+        }
+        catch {
+            // Trace is best-effort and must not change the turn result.
+        }
         // 跑完(正常 / 达上限)在回复末尾打耗时摘要行;中断 done=false 不打。
         if (done) {
             hooks.onDone?.(Date.now() - t0, turnUsage);
@@ -528,4 +889,4 @@ export async function runAgentCore(opts) {
     }
 }
 // ── 导出共享辅助(主 agent 的 TUI hooks 实现要用)──────────────────────────
-export { parseArgs, readDiffContext, isMutationTool, READ_TOOL_NAMES };
+export { parseArgs, readDiffContext, isMutationTool, isParallelTool };