mocode-ai 1.3.9 → 1.4.0

package/dist/agent/core.js

@@ -4,154 +4,32 @@
 //
 // 与 index.ts 的关系:index.ts 的 runAgent = runAgentCore + TUI hooks 薄封装(行为不变)。
 // spawn.ts 的 spawnAgent = runAgentCore + 静默 hooks(子 agent)。
-import { readFileSync } from 'node:fs';
-import { getNotesMtime } from '../session/notes.js';
 import { chat, estimatePromptTokens, estimateTokens, isContextLengthError, planChatTools, chatTools, } from '../llm/index.js';
-import { executeToolOutcome, findTool, getToolCapabilities, isFileMutationTool, } from '../tools/registry.js';
+import { executeToolOutcome, findTool, isFileMutationTool } from '../tools/registry.js';
 import { checkPermission } from '../permissions/index.js';
 import { validateToolArguments } from '../tools/validation.js';
-import { getPlanDisabledTools, getRuntimeDisabledTools } from '../tools/constants.js';
-import { getAgentMode, setAgentMode } from './mode.js';
-import { maybeCompact, contextState, createTraceEvent, summarizeToolArguments, safeProviderId, } from '../session/index.js';
-import { capToolResultForHistory } from '../session/compact.js';
+import { getPlanDisabledTools, getRuntimeDisabledTools, getSkillRuntimeDisabledTools } from '../tools/constants.js';
+import { ADD_TOOL_GROUPS_TOOL_NAME } from '../config/profiles.js';
+import { defaultAgentRuntimeContext } from './runtime-context.js';
+import { parseArgs, argumentErrorHint, isToolResultsNoise, isParallelTool, isResourceLockedCall, deniedOutcome, readDiffContext, pushToolResult, } from './tool-helpers.js';
+import { maybeCompact, contextState, summarizeToolArguments } from '../session/index.js';
+import { TurnTraceState } from './trace-state.js';
 import { createBudgetScheduler } from '../session/scheduler.js';
-import { recordArtifact, invalidateArtifacts, rehydrateArtifacts, knownEditTargets, } from '../context/index.js';
+import { invalidateArtifacts, rehydrateArtifacts } from '../context/index.js';
 import { createRelevancePruner } from '../context/relevance.js';
-import { isToolResultSuccess } from '../context/utils.js';
-import { config, getActiveModel, extractActivePlanSection, buildSessionStateReminder } 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 { getCurrentSessionId } from '../session/state.js';
 /** nag 提醒阈值:连续 N 个"执行了工具但没更新 notes.md"的步后提醒一次(对齐 Claude Code TodoWrite 的 3 轮)。 */
 const PLAN_NAG_THRESHOLD = 3;
 /** nag 提醒文本:注入到当前步第一条 tool_result 内容前(与最新工具输出同批被模型看到,而非单独一条易被冲淡)。 */
 const PLAN_NAG_TEXT = '[mocode] Reminder: you have an active plan in notes.md but have not updated it recently. ' +
     'If you finished a step, call plan_update to check it off (keep at most one in_progress); ' +
     'if the whole plan is done, let plan_update settle it to ## Done:. If the plan changed scope, update it to match reality.';
-/** 解析工具 arguments JSON;非法或空返 null(调用方据此降级到普通 preview)。 */
-function parseArgs(raw) {
-    try {
-        return raw.trim() ? JSON.parse(raw) : {};
-    }
-    catch {
-        return null;
-    }
-}
-/** 需要「已知编辑目标」恢复提示的文件编辑工具;其余工具的参数报错不注入该提示。 */
-const EDIT_HINT_TOOLS = new Set(['edit_file', 'write_file']);
-/** 文件编辑工具参数校验失败时的恢复提示:把系统已知仍新鲜的「最近 read_file 的
- *  path + hash」直接递给模型照抄,替代其在长上下文里凭记忆复述。
- *  只展示事实、不替模型填值;没有候选(从未 read_file / 全部已失效)返 undefined。 */
-function argumentErrorHint(name, state) {
-    if (!EDIT_HINT_TOOLS.has(name))
-        return undefined;
-    const targets = knownEditTargets(state);
-    if (targets.length === 0)
-        return undefined;
-    const lines = targets.map((target) => `  path=${target.path}  expected_hash=${target.hash}`).join('\n');
-    return ('系统已知最近 read_file 且尚未被修改的文件(直接复制下面的 path / expected_hash,勿凭记忆复述):\n' +
-        `${lines}\n如目标文件不在其中,先 read_file 该文件再发起编辑。`);
-}
-/** 判定 assistant content 是否只是 "Tool results:" 这类工具结果前缀噪声。
- *  部分模型(如 Claude)会在 tool_calls 前输出此种无意义过渡文本，写入 history
- *  会污染后续轮次上下文并在 TUI 上泄露为孤立行。 */
-function isToolResultsNoise(content) {
-    return /^(?:\s*Tool results:\s*)+$/i.test(content.trim());
-}
-/** 只有显式声明 parallel 且无需权限确认的工具才进入普通并发组。 */
-function isParallelTool(name) {
-    const tool = findTool(name);
-    return !!tool && (tool.risk ?? 'safe') === 'safe' &&
-        getToolCapabilities(tool).concurrency === 'parallel';
-}
-/** resource-locked 工具先顺序完成权限预检，再依赖 canonical resource lock 并发执行。 */
-function isResourceLockedTool(name) {
-    const tool = findTool(name);
-    return !!tool && getToolCapabilities(tool).concurrency === 'resource-locked';
-}
-function isResourceLockedCall(call) {
-    if (!isResourceLockedTool(call.name))
-        return false;
-    if (call.name !== 'sub-agent')
-        return true;
-    const args = parseArgs(call.arguments);
-    // Unknown write sets stay on the serial path. Read tasks and known disjoint write sets may batch.
-    return args?.mode !== 'write' || (Array.isArray(args.writeSet) && args.writeSet.length > 0);
-}
+// 工具辅助纯函数(parseArgs / argumentErrorHint / isToolResultsNoise / isParallelTool /
+// isResourceLockedTool / isResourceLockedCall / deniedOutcome / readDiffContext / pushToolResult)
+// 已提取至 ./tool-helpers.ts——它们不依赖本循环的局部状态,只接受显式参数,故可安全模块化。
 /** 文件 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 }。失败不阻断。 */
-function readDiffContext(tc, parsed) {
-    if (!parsed)
-        return { preWriteOld: null, editStartLine: 1 };
-    const p = String(parsed.path ?? '');
-    if (!p)
-        return { preWriteOld: null, editStartLine: 1 };
-    if (tc.name === 'write_file') {
-        try {
-            // jailResolve:沙箱越界(../../、绝对外圈、软链出圈)抛错 → catch 兜底返 null,不泄露牢外内容(TOCTOU)
-            return { preWriteOld: readFileSync(jailResolve(p), 'utf8'), editStartLine: 1 };
-        }
-        catch {
-            return { preWriteOld: null, editStartLine: 1 }; // 文件不存在(新建)、不可读 或 沙箱越界(不泄露)
-        }
-    }
-    if (tc.name === 'edit_file') {
-        // 行尾归一化:LLM 生成的 old_string 用 LF(\n),但 Windows 文件可能是 CRLF(\r\n),
-        // 不统一则 indexOf 必败、editStartLine 恒为 1。与 edit-file.ts 保持一致归一化为 LF。
-        const oldStr = String(parsed.old_string ?? '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-        try {
-            // jailResolve:同上,沙箱越界抛错 → catch 兜底,不泄露牢外内容
-            const raw = readFileSync(jailResolve(p), 'utf8');
-            const data = raw.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-            const idx = oldStr ? data.indexOf(oldStr) : -1;
-            return {
-                preWriteOld: null,
-                editStartLine: idx >= 0 ? data.slice(0, idx).split('\n').length : 1,
-            };
-        }
-        catch {
-            return { preWriteOld: null, editStartLine: 1 }; // 读不到:diff 退化为相对行号(含沙箱越界)
-        }
-    }
-    return { preWriteOld: null, editStartLine: 1 };
-}
-/** 回灌 tool 结果到 history。
- *  正常路径只做单条 hard cap；原始 output 同时供 TUI 展示，因此用户与模型
- *  看到同一事实。Artifact/Relevance/Lifecycle 仅登记 metadata/provenance，
- *  不在这里改写旧正文；所有自动清理与压缩统一由 80% pressure scheduler 决定。 */
-function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runtimeContextState = contextState, succeededOverride) {
-    const succeeded = succeededOverride ?? isToolResultSuccess(output);
-    const msg = {
-        role: 'tool',
-        tool_call_id: tc.id,
-        // Preserve evidence verbatim in normal operation; the hard per-result cap
-        // remains solely as a request-size safety rail.
-        content: capToolResultForHistory(tc.name, output),
-    };
-    history.push(msg);
-    const messageIndex = history.length - 1;
-    recordArtifact(runtimeContextState, history, messageIndex, output, succeeded);
-    // 失败 read 不得淘汰旧 read；失败 consumer 也不能改变 lifecycle 上游状态。
-    if (pruner)
-        pruner.observePush(history, msg, succeeded);
-    if (lifecycle)
-        lifecycle.pushTool(history, messageIndex, succeeded);
-    runtimeContextState.lifecycleStats = lifecycle?.stats();
-}
 /**
  * agent 核心循环(纯逻辑):
  *  流式调 LLM(经 hooks.onText 实时渲染)→ 有 tool_calls 就分组执行并回灌
@@ -169,67 +47,41 @@ function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runt
  */
 export async function runAgentCore(opts) {
     const { history, userInput, signal, onContextUpdate, hooks } = opts;
+    const ctx = opts.runtimeContext ?? defaultAgentRuntimeContext;
     const runtimeContextState = opts.contextState ?? contextState;
     /** 本轮 ask_human 成功调用次数，仅用于 trace 观测，不影响工具执行或模型上下文。 */
     let askHumanCountThisTurn = 0;
-    const maxSteps = opts.maxSteps ?? config.maxSteps;
+    const maxSteps = opts.maxSteps ?? ctx.config.maxSteps;
     // 中断还原:repl 的 /plan / /auto / Shift+Tab 等用户面触发 setAgentMode 中途切了模式,
     // abort 时连同模式一起还原回轮首。模型不再持有 switch_mode 工具,无法自切。
-    const savedMode = getAgentMode();
+    const savedMode = ctx.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() });
+    // trace / token-usage 状态聚合(2.0 步骤2 深拆第一刀):emit/addUsage/turnUsage 收敛进
+    // TurnTraceState,事件 payload 与 hooks 序列保持字节级不变。
+    const traceState = new TurnTraceState({
+        sessionId: opts.traceContext?.sessionId ?? ctx.getCurrentSessionId() ?? `ephemeral-${process.pid}`,
+        turnId: opts.traceContext?.turnId ?? ctx.getCurrentTurnId(),
+        onTraceEvent: opts.onTraceEvent,
+    });
+    const traceSessionId = traceState.sessionId;
+    const traceTurnId = traceState.turnId;
+    const emitTrace = (type, data = {}, ids = {}) => traceState.emit(type, data, ids);
+    emitTrace('turn_start', { mode: ctx.getAgentMode() });
+    if (opts.initialToolRoute)
+        emitTrace('tool_route', opts.initialToolRoute);
     let done = false; // 正常完毕 / 达上限 true;中断 false(不显摘要)
     let traceStatus = 'error';
-    let toolCallCount = 0;
     // A+B(plan 可靠性):跨步计数"执行了工具但没改动 notes.md"的连续步数。
     // 本步写了 notes.md(plan_update 或直接 write/edit)→ 清零并重同步 history[0];
     // 否则累计,达阈值则在当前步 tool_result 前注入 nag 提醒。
     let stepsSincePlanTouch = 0;
-    // 本轮 token 累计:每步 chat() 返回后把 result.usage 累加,供 onDone 摘要行 + AgentRunResult.usage
+    // 本轮 token 累计在 traceState.turnUsage(每步 chat() 返回后 addUsage),供 onDone 摘要行 + AgentRunResult.usage
     // 透传给 repl(显示在底栏模式 chip 右边)。未开启 include_usage 或全失败时为 undefined。
-    let turnUsage;
     // 实时 chip ↻ 估算用:上一步 chat 实测 prompt(前缀缓存下当前步命中 ≈ 它)+ 后端是否报过 cache 命中
     // (从不报 cache 的后端不估算,避免虚显 ↻)。
     let lastStepPromptTokens = 0;
     let providerCacheSeen = false;
-    const addUsage = (u) => {
-        if (!u)
-            return;
-        turnUsage = turnUsage
-            ? {
-                promptTokens: turnUsage.promptTokens + u.promptTokens,
-                completionTokens: turnUsage.completionTokens + u.completionTokens,
-                totalTokens: turnUsage.totalTokens + u.totalTokens,
-                cachedTokens: turnUsage.cachedTokens + u.cachedTokens,
-                cacheCreationTokens: (turnUsage.cacheCreationTokens ?? 0) + (u.cacheCreationTokens ?? 0),
-                reasoningTokens: turnUsage.reasoningTokens + u.reasoningTokens,
-            }
-            : u;
-    };
-    const addToolUsage = (outcome) => addUsage(outcome.usage);
     history.push({ role: 'user', content: userInput });
     // 中断回滚快照:push 用户消息后整段浅拷贝。abort 时 length=0;push(...saved) 还原。
     // 这样中断时至少保留用户消息(及之前的历史);每步工具全部执行完毕后刷新快照,
@@ -238,18 +90,14 @@ export async function runAgentCore(opts) {
     let savedHistory = history.slice();
     // Relevance and lifecycle collect provenance during normal work. Neither path
     // rewrites history; exact supersession is applied only by the pressure scheduler.
-    const relprune = config.contextRelprune ? createRelevancePruner() : null;
-    let lifecycle = config.contextLifecycle
-        ? createLifecycleEngine(history)
-        : null;
+    const relprune = ctx.config.contextRelprune ? createRelevancePruner() : null;
+    let lifecycle = ctx.config.contextLifecycle ? createLifecycleEngine(history) : null;
     runtimeContextState.lifecycleStats = lifecycle?.stats();
     rehydrateArtifacts(runtimeContextState, history);
     // The scheduler is the sole automatic history-rewrite entry point. It runs
     // superseded → stale artifact → old logs/search → compact at real pressure.
     // contextBudget=false keeps only the infrastructure compact fallback.
-    const scheduler = config.contextBudget !== false
-        ? createBudgetScheduler(runtimeContextState)
-        : null;
+    const scheduler = ctx.config.contextBudget !== false ? createBudgetScheduler(runtimeContextState) : null;
     // 本轮流式状态:首个正文 token 到达即停 spinner(思考期间 spinner 持续转「思考中…」,不写思考内容)。
     let mode = 'idle';
     let gotText = false;
@@ -272,19 +120,11 @@ 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);
-        setAgentMode(savedMode);
-    };
+    // 实现已收敛进 TurnTraceState.abortRestore;savedHistory/savedMode 是函数级 let,此处闭包现读。
+    const abortRestore = () => traceState.abortRestore({ hooks, history, savedHistory, ctx, savedMode });
     try {
         for (let step = 0; step < maxSteps; step++) {
-            currentTraceStep = step;
+            traceState.currentTraceStep = step;
             const stepStartedAt = Date.now();
             emitTrace('step_start', { ordinal: step });
             try {
@@ -292,21 +132,45 @@ export async function runAgentCore(opts) {
                 if (signal?.aborted) {
                     abortRestore();
                     traceStatus = 'aborted';
-                    const mutation = getCurrentTurnMutationState();
-                    return {
-                        completed: false,
-                        terminationReason: 'aborted',
-                        finalText: null,
-                        usage: turnUsage,
-                        changedFiles: mutation.changedFiles.map((item) => item.path),
-                    };
+                    return traceState.buildAbortedResult(ctx.getCurrentTurnMutationState());
                 }
-                // 本步只计算一次实际工具集合，调度、请求和 usage 校准必须使用完全相同的 schema。
-                const activeTools = opts.toolsOverride
-                    ?? (getAgentMode() === 'plan' ? planChatTools : chatTools);
-                const requestBaseURL = config.baseURL;
-                const requestModel = getActiveModel();
-                const storedCalibration = getTokenCalibration(requestBaseURL, requestModel, activeTools);
+                // 本步只捕获一次不可变 policy snapshot。即便 add_tool_groups 在执行阶段扩容，
+                // 本次模型响应仍必须按旧 snapshot 校验；新工具只在下一 step 的 schema 中出现。
+                const planMode = ctx.getAgentMode() === 'plan';
+                const policySnapshot = opts.toolPolicy?.snapshot(planMode);
+                const configuredTools = opts.toolsOverride ?? policySnapshot?.tools ?? (planMode ? planChatTools : chatTools);
+                const policyAllowedTools = opts.runtimeAllowedToolNames
+                    ? configuredTools.filter((tool) => opts.runtimeAllowedToolNames?.has(tool.function.name))
+                    : configuredTools;
+                const skillDisabledTools = getSkillRuntimeDisabledTools();
+                const legacyDisabledTools = opts.toolPolicy || opts.runtimeAllowedToolNames ? new Set() : getRuntimeDisabledTools();
+                // schema、runtime backstop 与后代权限都从同一 effective allow-list 派生。
+                // policy snapshot 是本 step 的不可扩张上限；skill deny 可在同批 use_skill 后继续动态收窄。
+                const activeTools = policyAllowedTools.filter((tool) => !skillDisabledTools.has(tool.function.name) && !legacyDisabledTools.has(tool.function.name));
+                const stepAllowedNames = new Set(activeTools.map((tool) => tool.function.name));
+                const currentAllowedToolNames = () => {
+                    const currentSkillDisabledTools = getSkillRuntimeDisabledTools();
+                    return [...stepAllowedNames].filter((name) => !currentSkillDisabledTools.has(name));
+                };
+                const isToolDeniedForStep = (name) => !stepAllowedNames.has(name) || getSkillRuntimeDisabledTools().has(name);
+                // 委派给编排工具(sub-agent/run_skill)的父前缀快照:去掉历史末尾「产生本次调用的
+                // assistant tool_call 消息」(协议上它必须紧跟 tool_result,不能出现在子 history),
+                // 只保留其前的主前缀。子 agent 以它为前缀、尾部追加委派消息 → 与主 agent 已发送
+                // 前缀逐字节一致,命中前缀缓存。tools 直接用本步 activeTools:子 agent 与主 agent
+                // 同权同 schema,不做任何裁剪,也没有额外的执行层禁用集合。
+                const delegationForOrchestrator = () => {
+                    let k = history.length - 1;
+                    while (k > 0) {
+                        const m = history[k];
+                        if (m.role === 'assistant' && Array.isArray(m.tool_calls))
+                            break;
+                        k--;
+                    }
+                    return { history: history.slice(0, k > 0 ? k : history.length), tools: activeTools };
+                };
+                const requestBaseURL = ctx.config.baseURL;
+                const requestModel = ctx.getActiveModel();
+                const storedCalibration = ctx.getTokenCalibration(requestBaseURL, requestModel, activeTools);
                 runtimeContextState.correction = storedCalibration.correction;
                 runtimeContextState.calibrationSamples = storedCalibration.samples;
                 // 会话状态(活跃 plan + 笔记正文)在调度器**之前**取一次:
@@ -314,7 +178,7 @@ export async function runAgentCore(opts) {
                 //     必须计入压力线——它不在 history 里,调度器只能由此入参看见(否则最多 5k
                 //     的笔记 + plan 段对 80% 触发线完全不可见,小窗口模型会压不住);
                 //  ② 压缩步在压缩成功后重取(P2 固结的 Compaction Snapshot 当步即可见)。
-                let sessionStateText = opts.suppressSessionState ? '' : buildSessionStateReminder();
+                let sessionStateText = opts.suppressSessionState ? '' : ctx.buildSessionStateReminder();
                 // The scheduler is the only automatic path that may compress old evidence.
                 // Normal tool pushes and lifecycle tracking remain metadata-only.
                 // 压缩**之前**先刷一次状态栏:bar 要显示「本步真实 prompt 撞线」那一刻。
@@ -368,7 +232,7 @@ export async function runAgentCore(opts) {
                     // 末尾就带上最新 Compaction Snapshot,不必等下一步。bar 口径对应的
                     // ephemeralText 仍用触发时旧值(见 buildRequestHistory 注释),仅差这一段。
                     if (!opts.suppressSessionState)
-                        sessionStateText = buildSessionStateReminder();
+                        sessionStateText = ctx.buildSessionStateReminder();
                     // 会话状态(活跃 plan + 笔记段)不再回写 history[0]:每步都会在 requestHistory
                     // 末尾注入最新副本(见下方 ephemeralReminder),compact 后自然恢复。
                 }
@@ -378,7 +242,7 @@ export async function runAgentCore(opts) {
                 lastChar = '';
                 let result;
                 const modelStartedAt = Date.now();
-                const provider = safeProviderId(requestBaseURL);
+                const provider = ctx.safeProviderId(requestBaseURL);
                 emitTrace('model_start', { model: requestModel, provider });
                 // 动态注入(prompt 缓存关键):所有随步/随文件变化的提示统一拼成**历史末尾**一条
                 // ephemeral system 消息,不再改写 history[0]。这样系统提示 + 已有对话逐字节稳定,
@@ -398,7 +262,8 @@ export async function runAgentCore(opts) {
                 // 不计,让 bar 用会让两条线再错开几百 token。
                 const buildRequestHistory = () => {
                     const ephemeralReminder = [
-                        (!opts.suppressOpeningAnalysis && step === 0)
+                        opts.toolPolicy?.reminder(planMode) ?? '',
+                        !opts.suppressOpeningAnalysis && step === 0
                             ? '## Opening analysis\nBegin your FIRST response of this turn with a brief analysis of the request and your planned approach (1-3 sentences, no filler), THEN start tool calls. This opening is the only place where pre-tool prose is expected; after it, work quietly with no narration between tool calls.'
                             : '',
                         historyRebuilt
@@ -413,7 +278,9 @@ export async function runAgentCore(opts) {
                                 '4. Before re-running a search/read you think you already did, check the summary and notes first: only repeat it if the result is genuinely missing or the target has changed.'
                             : '',
                         sessionStateText, // 调度器之前已取(并计入压力线),此处复用同一份,不重复读文件
-                    ].filter(Boolean).join('\n\n');
+                    ]
+                        .filter(Boolean)
+                        .join('\n\n');
                     return ephemeralReminder
                         ? [...history, { role: 'system', content: ephemeralReminder }]
                         : history;
@@ -424,25 +291,9 @@ export async function runAgentCore(opts) {
                 // 那一次才是解释「为什么要压」的。
                 onContextUpdate?.();
                 // 实时用量:当前步 prompt 估算(含校准系数)+ 流式累计 completion 估算,
-                // 叠上已完成步的实测 turnUsage,经 onLiveUsage 推给底栏实时 chip。
-                // turnUsage 在闭包里被 addUsage 原地更新,reportLive 每次调用读最新值。
+                // 叠上已完成步的实测 turnUsage(traceState 内累加,每次调用读最新值),经 onLiveUsage 推给底栏实时 chip。
                 let stepPromptEst = estimatePromptTokens(requestHistory, activeTools, runtimeContextState.correction);
-                const reportLive = (p) => {
-                    // 当前步 prompt:末尾 usage chunk 到达后用实测,流式期间用估算(含校准)。
-                    // 当前步 cache 命中同理:上报即用实测;流式期间按前缀缓存估算 ≈ 上一步实测 prompt
-                    // (当前 prompt 总含其为前缀),不超过当前步 prompt;后端从不报 cache 时不估算。
-                    // 口径与轮末摘要一致:chip ↑ 显计费 prompt(裸 - cached),↓/↻ 同。
-                    const curPrompt = p.promptTokens ?? stepPromptEst;
-                    const curCached = p.cachedTokens ?? (providerCacheSeen
-                        ? Math.min(lastStepPromptTokens, curPrompt)
-                        : 0);
-                    hooks.onLiveUsage?.({
-                        promptTokens: (turnUsage?.promptTokens ?? 0) + curPrompt,
-                        completionTokens: (turnUsage?.completionTokens ?? 0) + p.completionTokens,
-                        totalTokens: (turnUsage?.totalTokens ?? 0) + curPrompt + p.completionTokens,
-                        cachedTokens: (turnUsage?.cachedTokens ?? 0) + curCached,
-                    });
-                };
+                const reportLive = (p) => traceState.reportLive(hooks, stepPromptEst, lastStepPromptTokens, providerCacheSeen, p);
                 reportLive({ completionTokens: 0 }); // 思考阶段先显 ↑ prompt 估算,首 token 到达后 ↓ 开始涨
                 // 单一 chat 入口:错误侧的 model_end 埋点只写一处(重试也会记,不丢失败轨迹)。
                 const chatHandlers = {
@@ -463,16 +314,14 @@ export async function runAgentCore(opts) {
                         return await chat(requestHistory, chatHandlers, signal, activeTools);
                     }
                     catch (err) {
-                        const errorValue = err && typeof err === 'object'
-                            ? err
-                            : undefined;
+                        const errorValue = err && typeof err === 'object' ? err : 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',
+                                : (errorValue?.code ?? errorValue?.name ?? 'MODEL_ERROR'),
                             durationMs: Date.now() - modelStartedAt,
                         });
                         throw err;
@@ -484,19 +333,10 @@ export async function runAgentCore(opts) {
                 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'))) {
+                    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,
-                            usage: turnUsage,
-                            changedFiles: mutation.changedFiles.map((item) => item.path),
-                        };
+                        return traceState.buildAbortedResult(ctx.getCurrentTurnMutationState());
                     }
                     // 后端实测拒绝了 prompt(上下文超长):本地估算对该 provider 系统性偏低时,
                     // 压力线压不住,这是唯一可信的触发。强压一轮后重试一次;仍失败才抛(限一次,防循环)。
@@ -508,7 +348,7 @@ export async function runAgentCore(opts) {
                         // 偶发误判会被后续真实 usage 样本拉回。
                         const rawEstimate = estimatePromptTokens(requestHistory, activeTools);
                         if (rawEstimate > 1_000) {
-                            const cal = updateTokenCalibration(requestBaseURL, requestModel, activeTools, rawEstimate, config.contextWindowTokens);
+                            const cal = ctx.updateTokenCalibration(requestBaseURL, requestModel, activeTools, rawEstimate, ctx.config.contextWindowTokens);
                             runtimeContextState.correction = cal.correction;
                             runtimeContextState.calibrationSamples = cal.samples;
                         }
@@ -551,7 +391,7 @@ export async function runAgentCore(opts) {
                     reasoningTokens: result.usage?.reasoningTokens,
                 });
                 runtimeContextState.lastUsage = result.usage; // 供 /context 与状态行显示实测 token
-                addUsage(result.usage); // 本轮累计:onDone 摘要行 + AgentRunResult.usage 透传
+                traceState.addUsage(result.usage); // 本轮累计:onDone 摘要行 + AgentRunResult.usage 透传
                 if (result.usage) {
                     lastStepPromptTokens = result.usage.promptTokens; // 下一步流式期 ↻ 估算的前缀基准
                     if (result.usage.cachedTokens > 0)
@@ -561,7 +401,7 @@ export async function runAgentCore(opts) {
                 // 只持久化比例与样本数；无 usage 或短 prompt 时保持既有值。
                 if (result.usage?.promptTokens && result.usage.promptTokens > 100) {
                     const estimated = estimatePromptTokens(requestHistory, activeTools);
-                    const updated = updateTokenCalibration(requestBaseURL, requestModel, activeTools, estimated, result.usage.promptTokens);
+                    const updated = ctx.updateTokenCalibration(requestBaseURL, requestModel, activeTools, estimated, result.usage.promptTokens);
                     runtimeContextState.correction = updated.correction;
                     runtimeContextState.calibrationSamples = updated.samples;
                 }
@@ -569,7 +409,7 @@ export async function runAgentCore(opts) {
                 // lastUsage 已更新:触发状态行 context 用量条重算+重画,运行中不再冻结在轮首。
                 onContextUpdate?.();
                 if (result.toolCalls.length > 0) {
-                    toolCallCount += result.toolCalls.length;
+                    traceState.toolCallCount += result.toolCalls.length;
                     // 若 content 只是 Claude 式 "Tool results:" 噪声，清空它：不补换行、不写入 history，
                     // 避免污染后续轮次上下文并在 TUI 泄露为孤立行。
                     if (result.content && isToolResultsNoise(result.content)) {
@@ -594,7 +434,7 @@ export async function runAgentCore(opts) {
                     // A+B:记录本步第一条 tool_result 的下标 + 执行前 notes.md 的 mtime,
                     // 工具全部执行完后据此判断"本步是否改动了 notes.md"(重同步 / nag)。
                     const toolResultStartIdx = history.length;
-                    const notesMtimeBefore = getNotesMtime();
+                    const notesMtimeBefore = ctx.getNotesMtime();
                     // Record interstitial narration for observability only. It never changes tool output
                     // or injects instructions back into the model context.
                     const narration = result.content?.trim() ?? '';
@@ -649,10 +489,104 @@ export async function runAgentCore(opts) {
                             ...(tc.id ? { providerToolCallId: tc.id } : {}),
                         });
                     };
-                    let i = 0;
+                    const hasToolRouteBarrier = calls.some((tc) => tc.name === ADD_TOOL_GROUPS_TOOL_NAME);
+                    if (hasToolRouteBarrier) {
+                        const mixedCall = calls.length !== 1;
+                        for (let index = 0; index < calls.length; index++) {
+                            const tc = calls[index];
+                            hooks.onToolHeader?.(tc);
+                            const parsed = parseArgs(tc.arguments);
+                            let outcome;
+                            if (mixedCall) {
+                                const isControl = tc.name === ADD_TOOL_GROUPS_TOOL_NAME;
+                                outcome = {
+                                    status: 'denied',
+                                    code: isControl ? 'INVALID_ARGUMENTS' : 'TOOL_DISABLED',
+                                    retryable: false,
+                                    output: isControl
+                                        ? '错误:add_tool_groups 必须在一个独立的 model step 中单独调用；本次没有扩容。'
+                                        : `错误:同一响应包含 add_tool_groups，工具 ${tc.name} 未执行。请等待扩容结果后在下一 step 重试。`,
+                                    changedFiles: [],
+                                    durationMs: 0,
+                                };
+                            }
+                            else if (isToolDeniedForStep(tc.name)) {
+                                outcome = {
+                                    status: 'denied',
+                                    code: 'TOOL_DISABLED',
+                                    retryable: false,
+                                    output: `错误:当前 tool policy snapshot 不允许调用 ${tc.name}。`,
+                                    changedFiles: [],
+                                    durationMs: 0,
+                                };
+                            }
+                            else if (!opts.toolPolicy) {
+                                outcome = {
+                                    status: 'denied',
+                                    code: 'TOOL_DISABLED',
+                                    retryable: false,
+                                    output: '错误:当前 Agent 未启用动态工具策略，无法调用 add_tool_groups。',
+                                    changedFiles: [],
+                                    durationMs: 0,
+                                };
+                            }
+                            else if (!parsed ||
+                                !Array.isArray(parsed.groups) ||
+                                parsed.groups.length === 0 ||
+                                typeof parsed.reason !== 'string' ||
+                                !parsed.reason.trim()) {
+                                outcome = {
+                                    status: 'error',
+                                    code: 'INVALID_ARGUMENTS',
+                                    retryable: false,
+                                    output: '错误:add_tool_groups 需要非空 groups 数组和非空 reason。',
+                                    changedFiles: [],
+                                    durationMs: 0,
+                                };
+                            }
+                            else {
+                                const expansion = opts.toolPolicy.expand(parsed.groups, parsed.reason);
+                                const succeeded = expansion.added.length > 0;
+                                const details = [
+                                    succeeded
+                                        ? `Tool policy expanded to v${expansion.snapshot.version}; added groups: ${expansion.added.join(', ')}.`
+                                        : `Tool policy was not expanded (still v${expansion.snapshot.version}).`,
+                                    expansion.rejected.length > 0 ? `Rejected: ${expansion.rejected.join('; ')}.` : '',
+                                    succeeded ? 'The added tool schemas become available on the next model step.' : '',
+                                ]
+                                    .filter(Boolean)
+                                    .join('\n');
+                                outcome = {
+                                    status: succeeded ? 'success' : 'error',
+                                    code: succeeded ? 'OK' : 'INVALID_ARGUMENTS',
+                                    retryable: false,
+                                    output: details,
+                                    changedFiles: [],
+                                    durationMs: 0,
+                                };
+                                emitTrace('tool_route_expand', {
+                                    policyId: expansion.snapshot.id,
+                                    fromVersion: policySnapshot?.version,
+                                    toVersion: expansion.snapshot.version,
+                                    requestedGroups: parsed.groups.map(String),
+                                    addedGroups: expansion.added,
+                                    rejected: expansion.rejected,
+                                    reason: parsed.reason,
+                                    status: outcome.status,
+                                });
+                            }
+                            opts.onToolOutcome?.(tc.name, parsed ?? {}, outcome);
+                            hooks.onToolResult?.(tc, outcome.output, null, null, 1);
+                            pushToolResult(history, tc, outcome.output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
+                            traceToolEnd(tc, index, outcome);
+                        }
+                    }
+                    // add_tool_groups 是 step 屏障：只要本响应出现该控制调用，本批所有普通工具都不执行。
+                    // 但上面仍为每个 provider tool_call 写入了配对 tool_result，保持 OpenAI 协议完整。
+                    let i = hasToolRouteBarrier ? calls.length : 0;
                     while (i < calls.length) {
                         const currentCall = calls[i];
-                        if (getRuntimeDisabledTools().has(currentCall.name)) {
+                        if (isToolDeniedForStep(currentCall.name)) {
                             hooks.onToolHeader?.(currentCall);
                             const error = t('task.disabled');
                             const outcome = {
@@ -676,17 +610,21 @@ export async function runAgentCore(opts) {
                             // 已经完成；若先 started.map，用户只能在工具完成后才看到摘要与其前面的换行。
                             // 异步工具(web_fetch 等)并发跑、总耗时 ≈ 最慢一个;同步工具(glob/grep)map 时已顺序跑完,await 即返。
                             let j = i;
-                            while (j < calls.length && isParallelTool(calls[j].name))
+                            while (j < calls.length && isParallelTool(calls[j].name) && !isToolDeniedForStep(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, { callId: tc.id }));
+                            const started = batch.map((tc) => executeToolOutcome(tc.name, tc.arguments, signal, {
+                                callId: tc.id,
+                                allowedToolNames: currentAllowedToolNames(),
+                                delegation: delegationForOrchestrator(),
+                            }));
                             for (let k = 0; k < batch.length; k++) {
                                 const tc = batch[k];
                                 const outcome = await started[k];
-                                addToolUsage(outcome);
+                                traceState.addUsage(outcome.usage);
                                 opts.onToolOutcome?.(tc.name, parseArgs(tc.arguments) ?? {}, outcome);
                                 traceToolEnd(tc, i + k, outcome);
                                 const output = outcome.output;
@@ -705,14 +643,14 @@ export async function runAgentCore(opts) {
                             i = j;
                         }
                         else if (isResourceLockedCall(currentCall) &&
-                            !(getAgentMode() === 'plan' && getPlanDisabledTools().has(currentCall.name))) {
+                            !(ctx.getAgentMode() === 'plan' && getPlanDisabledTools().has(currentCall.name))) {
                             // 连续文件 mutation：权限确认仍严格按原序进行；全部 preflight 完成后再启动。
                             // 每个执行在 registry 内按 canonical path 获取锁，不同文件可并发，同文件别名会排队。
                             let j = i;
                             while (j < calls.length &&
                                 isResourceLockedCall(calls[j]) &&
-                                !getRuntimeDisabledTools().has(calls[j].name) &&
-                                !(getAgentMode() === 'plan' && getPlanDisabledTools().has(calls[j].name)))
+                                !isToolDeniedForStep(calls[j].name) &&
+                                !(ctx.getAgentMode() === 'plan' && getPlanDisabledTools().has(calls[j].name)))
                                 j++;
                             const batch = calls.slice(i, j);
                             const entries = [];
@@ -720,9 +658,7 @@ export async function runAgentCore(opts) {
                                 const tc = batch[k];
                                 const parsed = parseArgs(tc.arguments);
                                 const tool = findTool(tc.name);
-                                const argumentsValid = tool && parsed !== null
-                                    ? validateToolArguments(tool, parsed).valid
-                                    : false;
+                                const argumentsValid = tool && parsed !== null ? validateToolArguments(tool, parsed).valid : false;
                                 let denied;
                                 if (tool && argumentsValid) {
                                     const perm = await checkPermission(tool, parsed ?? {}, signal, {
@@ -758,6 +694,8 @@ export async function runAgentCore(opts) {
                                 const hint = argumentErrorHint(entry.tc.name, runtimeContextState);
                                 return executeToolOutcome(entry.tc.name, entry.tc.arguments, signal, {
                                     callId: entry.tc.id,
+                                    allowedToolNames: currentAllowedToolNames(),
+                                    delegation: delegationForOrchestrator(),
                                     ...(hint ? { argumentErrorHint: hint } : {}),
                                     onLockAcquired: (lockedArgs) => {
                                         entry.diff = readDiffContext(entry.tc, lockedArgs);
@@ -767,15 +705,12 @@ export async function runAgentCore(opts) {
                             for (let k = 0; k < entries.length; k++) {
                                 const entry = entries[k];
                                 const outcome = await started[k];
-                                addToolUsage(outcome);
+                                traceState.addUsage(outcome.usage);
                                 opts.onToolOutcome?.(entry.tc.name, entry.parsed ?? {}, outcome);
                                 traceToolEnd(entry.tc, i + k, outcome);
                                 hooks.onToolResult?.(entry.tc, outcome.output, entry.denied ? null : entry.parsed, entry.diff.preWriteOld, entry.diff.editStartLine);
                                 pushToolResult(history, entry.tc, outcome.output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
-                                const invalidatedFiles = [...new Set([
-                                        ...(outcome.changedFiles ?? []),
-                                        ...(outcome.staleFiles ?? []),
-                                    ])];
+                                const invalidatedFiles = [...new Set([...(outcome.changedFiles ?? []), ...(outcome.staleFiles ?? [])])];
                                 if (invalidatedFiles.length > 0) {
                                     for (const changedFile of invalidatedFiles) {
                                         relprune?.observeMutation(history, changedFile);
@@ -794,7 +729,7 @@ export async function runAgentCore(opts) {
                             const tc = calls[i];
                             // plan 模式防御 backstop:schema 已剔除这些工具,正常不会进这里;防后端幻觉调用——
                             // 不执行,直接返错回灌(让模型看到「plan 模式禁用」并停止),绝不写盘 / 跑命令。
-                            if (getAgentMode() === 'plan' && getPlanDisabledTools().has(tc.name)) {
+                            if (ctx.getAgentMode() === 'plan' && getPlanDisabledTools().has(tc.name)) {
                                 hooks.onToolHeader?.(tc);
                                 const err = `错误:计划模式下禁用工具 ${tc.name}(仅读探查,不改动文件 / 不跑命令)`;
                                 const outcome = {
@@ -815,9 +750,7 @@ export async function runAgentCore(opts) {
                             // 拒绝时只渲染拒绝结果,不渲染执行头;放行则继续走 header → start → executeTool 流程。
                             const parsed = parseArgs(tc.arguments);
                             const tool = findTool(tc.name);
-                            const argumentsValid = tool && parsed !== null
-                                ? validateToolArguments(tool, parsed).valid
-                                : false;
+                            const argumentsValid = tool && parsed !== null ? validateToolArguments(tool, parsed).valid : false;
                             if (tool && argumentsValid) {
                                 const perm = await checkPermission(tool, parsed ?? {}, signal, {
                                     prompt: opts.permissionPrompt,
@@ -842,21 +775,21 @@ export async function runAgentCore(opts) {
                                 }
                             }
                             hooks.onToolHeader?.(tc);
-                            const mutationParsed = isMutationTool(tc.name)
-                                ? parsed
-                                : null;
+                            const mutationParsed = isMutationTool(tc.name) ? parsed : null;
                             let diff = readDiffContext(tc, mutationParsed);
                             hooks.onToolStart?.(tc.name);
                             const serialHint = argumentErrorHint(tc.name, runtimeContextState);
                             const outcome = await executeToolOutcome(tc.name, tc.arguments, signal, {
                                 callId: tc.id,
+                                allowedToolNames: currentAllowedToolNames(),
+                                delegation: delegationForOrchestrator(),
                                 ...(serialHint ? { argumentErrorHint: serialHint } : {}),
                                 onLockAcquired: (lockedArgs) => {
                                     if (mutationParsed)
                                         diff = readDiffContext(tc, lockedArgs);
                                 },
                             });
-                            addToolUsage(outcome);
+                            traceState.addUsage(outcome.usage);
                             opts.onToolOutcome?.(tc.name, parsed ?? {}, outcome);
                             traceToolEnd(tc, i, outcome);
                             const output = outcome.output;
@@ -871,10 +804,7 @@ export async function runAgentCore(opts) {
                                 }, tc.id ? { providerToolCallId: tc.id } : {});
                             }
                             pushToolResult(history, tc, output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
-                            const invalidatedFiles = [...new Set([
-                                    ...(outcome.changedFiles ?? []),
-                                    ...(outcome.staleFiles ?? []),
-                                ])];
+                            const invalidatedFiles = [...new Set([...(outcome.changedFiles ?? []), ...(outcome.staleFiles ?? [])])];
                             if (invalidatedFiles.length > 0) {
                                 for (const changedFile of invalidatedFiles) {
                                     relprune?.observeMutation(history, changedFile);
@@ -890,16 +820,19 @@ export async function runAgentCore(opts) {
                     // 每步都会由 buildSessionStateReminder() 在 requestHistory 末尾重建最新副本(见上方注入点),
                     // 所以模型下一步看到的必然是当前勾选态。只保留计数,避免多余的 history 改写(prompt 缓存)。
                     // B(nag 提醒):连续 N 步有工具活动但没更新 plan,在当前步第一条 tool_result 前注入提醒。
-                    const notesMtimeAfter = getNotesMtime();
+                    const notesMtimeAfter = ctx.getNotesMtime();
                     if (notesMtimeAfter !== notesMtimeBefore) {
                         stepsSincePlanTouch = 0;
                     }
                     else {
                         stepsSincePlanTouch += 1;
                         if (stepsSincePlanTouch >= PLAN_NAG_THRESHOLD) {
-                            const activePlan = extractActivePlanSection();
+                            const activePlan = ctx.extractActivePlanSection();
                             const firstToolMsg = history[toolResultStartIdx];
-                            if (activePlan && firstToolMsg && firstToolMsg.role === 'tool' && typeof firstToolMsg.content === 'string') {
+                            if (activePlan &&
+                                firstToolMsg &&
+                                firstToolMsg.role === 'tool' &&
+                                typeof firstToolMsg.content === 'string') {
                                 firstToolMsg.content = `${PLAN_NAG_TEXT}\n\n${firstToolMsg.content}`;
                             }
                             stepsSincePlanTouch = 0;
@@ -943,14 +876,14 @@ export async function runAgentCore(opts) {
                 if (!gotText)
                     hooks.onNoReply?.();
                 history.push({ role: 'assistant', content: result.content });
-                const finalMutation = getCurrentTurnMutationState();
+                const finalMutation = ctx.getCurrentTurnMutationState();
                 done = true;
                 traceStatus = 'completed';
                 return {
                     completed: true,
                     terminationReason: 'completed',
                     finalText: result.content,
-                    usage: turnUsage,
+                    usage: traceState.turnUsage,
                     changedFiles: finalMutation.changedFiles.map((item) => item.path),
                 };
             }
@@ -964,24 +897,24 @@ export async function runAgentCore(opts) {
         hooks.onMaxSteps?.();
         done = true;
         traceStatus = 'max_steps';
-        const finalMutation = getCurrentTurnMutationState();
+        const finalMutation = ctx.getCurrentTurnMutationState();
         return {
             completed: false,
             terminationReason: 'max_steps',
             finalText: null,
-            usage: turnUsage,
+            usage: traceState.turnUsage,
             changedFiles: finalMutation.changedFiles.map((item) => item.path),
         };
     }
     finally {
-        const finalMutation = getCurrentTurnMutationState();
-        currentTraceStep = undefined;
+        const finalMutation = ctx.getCurrentTurnMutationState();
+        traceState.currentTraceStep = undefined;
         emitTrace('turn_end', {
             status: traceStatus,
             durationMs: Date.now() - t0,
-            toolCalls: toolCallCount,
+            toolCalls: traceState.toolCallCount,
             changedFiles: finalMutation.changedFiles.map((item) => item.path),
-            totalTokens: turnUsage?.totalTokens,
+            totalTokens: traceState.turnUsage?.totalTokens,
         });
         try {
             opts.onTrace?.({
@@ -990,9 +923,9 @@ export async function runAgentCore(opts) {
                 turnId: traceTurnId,
                 status: traceStatus,
                 durationMs: Date.now() - t0,
-                toolCalls: toolCallCount,
+                toolCalls: traceState.toolCallCount,
                 changedFiles: finalMutation.changedFiles.map((item) => item.path),
-                usage: turnUsage,
+                usage: traceState.turnUsage,
             });
         }
         catch {
@@ -1000,7 +933,7 @@ export async function runAgentCore(opts) {
         }
         // 跑完(正常 / 达上限)在回复末尾打耗时摘要行;中断 done=false 不打。
         if (done) {
-            hooks.onDone?.(Date.now() - t0, turnUsage);
+            hooks.onDone?.(Date.now() - t0, traceState.turnUsage);
         }
     }
 }