mocode-ai 1.2.5 → 1.2.7

package/README.md

@@ -79,7 +79,7 @@ MoCode isn't a chat box with a coat of paint — it's an agent that actually get
 - **Plan / Auto dual mode** — In `plan` mode the agent is read-only (reads code, queries indexes, searches — never writes to disk, runs commands, or spawns sub-agents) and produces a plan; `auto` mode unlocks the full toolset. The agent can switch between the two on its own — scope out an unfamiliar codebase first, then start making changes.
 - **Pressure-driven context compression** — Normal history keeps full tool evidence. At 80% occupancy, one scheduler event runs all enabled cleanup and always follows with a history summary. `/context` shows live usage and `/compact` remains an explicit manual override.
 - **Cross-session long-term memory** — The agent can save project architecture, conventions, and lessons learned as long-term memory, auto-loaded in future sessions. A background process periodically reflects on conversations to mine things worth remembering. Memories can be created, searched, updated, and forgotten, with recall-based decay.
-- **Project context (`MOCODE.md`)** — A single project-level memory file at `MOCODE.md` captures both static facts (project description, commands, module list, directory tree) and human/AI-written insights (conventions, architectural decisions, pitfalls). Generate it once with `/init`, then keep it up to date by hand or by asking the agent to refresh it. Loaded automatically into the system prompt on every turn.
+- **Project context (`AGENTS.md`)** — A single project-level memory file at `AGENTS.md` captures both static facts (project description, commands, module list, directory tree) and human/AI-written insights (conventions, architectural decisions, pitfalls). Generate it once with `/init`, then keep it up to date by hand or by asking the agent to refresh it. Loaded automatically into the system prompt on every turn.
 - **Session notepad (notes.md)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent maintains a working notepad at `.mocode/sessions/<sessionId>/notes.md` (file-based, survives context compression). It records the execution plan with the dedicated `plan_update` tool — a three-state step machine (`pending`/`in_progress`/`completed`, at most one `in_progress`) that auto-settles to `## Done:` when finished. The active plan is re-injected into the system prompt after compaction and re-synced into context whenever notes.md changes, and a gentle reminder nudges the agent if it goes several tool-steps without updating the plan. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]`.
 - **Interruptible and reversible** — Ctrl+C interrupts the current turn at any time (kills child processes recursively, rolls history back to before the turn started, leaves no half-finished tool calls). `/rollback` restores file changes from per-turn snapshots, with a per-file keep/undo choice — no git dependency required.
 - **Sandbox protection** — File reads/writes go through a sandbox that blocks out-of-bounds paths (`../../`, absolute paths outside the root, symlink escapes, etc.), so the agent never touches files outside your working directory.
@@ -96,7 +96,7 @@ MoCode isn't a chat box with a coat of paint — it's an agent that actually get
 ## Documentation
 
 - [中文使用指南](./docs/usage.md) — 菜单式快速上手、命令速查、模式、会话、项目上下文与排障。
-- [Project context](./docs/usage.md#项目上下文) — `MOCODE.md` and Skills.
+- [Project context](./docs/usage.md#项目上下文) — `AGENTS.md` and Skills.
 
 ## Installation
 
@@ -218,7 +218,7 @@ The agent operates in **the working directory it was launched from** — to have
 | `memory_update`     | Edit a memory in place (id unchanged; correct stale facts / update summary / toggle pin) |
 | `memory_forget`     | Forget a memory: archived by default (recoverable), `mode=delete` for a hard delete (pinned memories can't be deleted) |
 
-The five `memory_*` tools are gated on `MEMORY_ENABLED=true` at startup; toggle at runtime with `/memory_switch` (REPL restart required, by design — see Skills section for the difference between Tier-1 `MOCODE.md` and Tier-2 memory).
+The five `memory_*` tools are gated on `MEMORY_ENABLED=true` at startup; toggle at runtime with `/memory_switch` (REPL restart required, by design — see Skills section for the difference between Tier-1 `AGENTS.md` and Tier-2 memory).
 
 The four frontend tools — `browser`, `dev_server`, `screenshot`, `view_image` — are **off by default** (they depend on the Playwright binary, spawn long-lived processes, or capture the desktop). Enable the whole cluster at runtime with `/fe on`; the model only sees them once enabled. Toggle with `/fe on|off|status`.
 
@@ -254,7 +254,7 @@ dev_server stop   id=srv-xxxx
 | `/memory_switch`   | Toggle Tier-2 memory on/off (REPL restart required — by design)       |
 | `/reflect`          | Manually trigger a background memory reflection pass                  |
 | `/model`            | Configure the LLM (baseURL / apiKey / model / context window), applied immediately + persisted |
-| `/init`             | Scan the project and generate `MOCODE.md` project memory (dispatched to the agent) |
+| `/init`             | Scan the project and generate `AGENTS.md` project memory (dispatched to the agent) |
 | `/theme`            | Switch color theme (↑↓ · Enter, or `/theme <name>` directly)         |
 | `/plan`             | Switch to plan mode (read-only exploration + plan output, approve to switch to auto) |
 | `/auto`             | Switch back to auto mode (full toolset execution)                     |
@@ -293,11 +293,11 @@ A skill's `description` is injected into the system prompt (progressive disclosu
 
 The system prompt provides lightweight guidance rather than a framework gate: inspect only what matters, make focused changes, avoid repeated stale reads, and report uncertainty honestly. The agent decides whether validation is useful for the task and chooses the scope itself. Broad test/build suites are not run by default, and lack of validation never blocks completion or triggers an extra model turn.
 
-## Project memory (MOCODE.md)
+## Project memory (AGENTS.md)
 
 MoCode has a **two-tier memory** model distinct from skills:
 
-- **Tier-1 — `MOCODE.md` (auto-loaded every session):** Markdown project memory that gets concatenated into the system prompt on every turn. Discovery walks `~/.mocode/MOCODE.md` → every `MOCODE.md` from the cwd up to the filesystem root (far→near, near wins). On overflow the body is truncated with a marker pointing back at the files. Generate or refresh one with `/init`, or write it by hand — it's plain Markdown, no schema. `MOCODE.md` is also where the agent itself persists "next-session facts" it deduces (architecture, conventions, pitfalls).
+- **Tier-1 — `AGENTS.md` (auto-loaded every session):** Markdown project memory that gets concatenated into the system prompt on every turn. Discovery walks `~/.mocode/AGENTS.md` → every `AGENTS.md` from the cwd up to the filesystem root (far→near, near wins). On overflow the body is truncated with a marker pointing back at the files. Generate or refresh one with `/init`, or write it by hand — it's plain Markdown, no schema. `AGENTS.md` is also where the agent itself persists "next-session facts" it deduces (architecture, conventions, pitfalls).
 - **Tier-2 — `memory_*` tool library (agent-driven, opt-in):** Discrete tagged records (`decision` / `fact` / `pitfall` / `reference` / `feedback`) with recall-count-based decay (30-day → archived; 90-day → GC). The agent saves / searches / updates / forgets via tools; titles go in the system-prompt index (≤50), bodies fetched on demand via `memory_search`. Off by default; toggle with `MEMORY_ENABLED=true` at startup or `/memory_switch` (REPL restart required).
 
 ## Type checking

package/README.zh-CN.md

@@ -95,7 +95,7 @@ mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 ## 使用文档
 
 - [菜单式使用指南](./docs/usage.md) — 快速上手、命令速查、模式、会话、项目上下文与排障。
-- [项目上下文：`MOCODE.md` 与 Skills](./docs/usage.md#项目上下文)
+- [项目上下文：`AGENTS.md` 与 Skills](./docs/usage.md#项目上下文)
 
 ## 安装
 
@@ -257,7 +257,7 @@ dev_server stop   id=srv-xxxx
 | `/memory_switch` | 切换 Tier-2 记忆开关(需重启 REPL,刻意为之)                  |
 | `/reflect`      | 手动触发一次后台记忆反思 pass                                   |
 | `/model`        | 配置大模型(baseURL / apiKey / model / 上下文窗口),即时生效 + 持久化 |
-| `/init`         | 扫描项目生成 `MOCODE.md` 项目记忆(发给 agent 执行)               |
+| `/init`         | 扫描项目生成 `AGENTS.md` 项目记忆(发给 agent 执行)               |
 | `/theme`        | 切换颜色主题(↑↓ · Enter,或 `/theme <name>` 直切)            |
 | `/plan`         | 切到 plan 模式(只读探查 + 产出计划,审批后切 auto 执行)              |
 | `/auto`         | 切回 auto 模式(全量工具执行)                                  |
@@ -296,11 +296,11 @@ skill 的 `description` 注入系统提示(渐进式披露第①层),模型只
 
 system prompt 提供轻量建议而不是框架硬门：只检查支持下一步决策的内容，做最小完整改动，避免重复读取，并诚实说明不确定性。agent 自主决定是否需要验证以及验证范围；框架不会因为未验证阻止完成或追加模型轮次。
 
-## 项目记忆(MOCODE.md)
+## 项目记忆(AGENTS.md)
 
 mocode 的**双层记忆**模型,跟 Skills 是两件事:
 
-- **Tier-1 — `MOCODE.md`(每轮自动加载):** Markdown 项目记忆,每轮拼进 system prompt。发现路径:`~/.mocode/MOCODE.md` → 从 cwd 往上逐级 `MOCODE.md`(远→近拼接,近的覆盖更突出);超长截断并标注原始文件。运行 `/init` 生成或刷新,纯 Markdown,可手写,无 schema。agent 自己推得的「下次要记住的事实」(架构/约定/坑位)也写在这里。
+- **Tier-1 — `AGENTS.md`(每轮自动加载):** Markdown 项目记忆,每轮拼进 system prompt。发现路径:`~/.mocode/AGENTS.md` → 从 cwd 往上逐级 `AGENTS.md`(远→近拼接,近的覆盖更突出);超长截断并标注原始文件。运行 `/init` 生成或刷新,纯 Markdown,可手写,无 schema。agent 自己推得的「下次要记住的事实」(架构/约定/坑位)也写在这里。
 - **Tier-2 — `memory_*` 工具库(agent 主导,需启用):** 离散带标签条目(`decision` / `fact` / `pitfall` / `reference` / `feedback`),按召回计数衰减(30 天 → archived,90 天 → 硬删 GC)。agent 用工具存 / 搜 / 改 / 删;索引(标题)进系统提示(≤50 条),正文按需 `memory_search` 取。默认关,启动 `MEMORY_ENABLED=true` 或 REPL 内 `/memory_switch`(需重启 REPL,刻意为之)。
 
 ## 类型检查

package/dist/agent/core.js

@@ -6,8 +6,8 @@
 // spawn.ts 的 spawnAgent = runAgentCore + 静默 hooks(子 agent)。
 import { readFileSync } from 'node:fs';
 import { getNotesMtime } from '../session/notes.js';
-import { chat, estimatePromptTokens, planChatTools, chatTools, } from '../llm/index.js';
-import { executeToolOutcome, getToolCapabilities, isFileMutationTool, tools, } from '../tools/registry.js';
+import { chat, estimatePromptTokens, estimateTokens, planChatTools, chatTools, } from '../llm/index.js';
+import { executeToolOutcome, findTool, getToolCapabilities, isFileMutationTool, } from '../tools/registry.js';
 import { checkPermission } from '../permissions/index.js';
 import { validateToolArguments } from '../tools/validation.js';
 import { getPlanDisabledTools, getRuntimeDisabledTools } from '../tools/constants.js';
@@ -15,10 +15,10 @@ import { getAgentMode, setAgentMode } from './mode.js';
 import { maybeCompact, contextState, createTraceEvent, summarizeToolArguments, safeProviderId, } from '../session/index.js';
 import { capToolResultForHistory } from '../session/compact.js';
 import { createBudgetScheduler } from '../session/scheduler.js';
-import { recordArtifact, invalidateArtifacts, rehydrateArtifacts, } from '../context/index.js';
+import { recordArtifact, invalidateArtifacts, rehydrateArtifacts, knownEditTargets, } from '../context/index.js';
 import { createRelevancePruner } from '../context/relevance.js';
 import { isToolResultSuccess } from '../context/utils.js';
-import { config, extractActivePlanSection, reinjectActivePlanIntoSystem } from '../config/index.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';
@@ -40,15 +40,36 @@ function parseArgs(raw) {
         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 = tools.find((candidate) => candidate.name === 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 = tools.find((candidate) => candidate.name === name);
+    const tool = findTool(name);
     return !!tool && getToolCapabilities(tool).concurrency === 'resource-locked';
 }
 function isResourceLockedCall(call) {
@@ -203,6 +224,7 @@ export async function runAgentCore(opts) {
                 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;
@@ -283,10 +305,16 @@ export async function runAgentCore(opts) {
                 const activeTools = opts.toolsOverride
                     ?? (getAgentMode() === 'plan' ? planChatTools : chatTools);
                 const requestBaseURL = config.baseURL;
-                const requestModel = config.model;
+                const requestModel = getActiveModel();
                 const storedCalibration = getTokenCalibration(requestBaseURL, requestModel, activeTools);
                 runtimeContextState.correction = storedCalibration.correction;
                 runtimeContextState.calibrationSamples = storedCalibration.samples;
+                // 会话状态(活跃 plan + 笔记正文)在调度器**之前**取一次:
+                //  ① 它会被追加到本次请求末尾(见下方 ephemeralReminder),属于本步固定开销,
+                //     必须计入压力线——它不在 history 里,调度器只能由此入参看见(否则最多 5k
+                //     的笔记 + plan 段对 80% 触发线完全不可见,小窗口模型会压不住);
+                //  ② 同一份字符串复用到下方 reminder,避免每步重复读 notes.md。
+                const sessionStateText = opts.suppressSessionState ? '' : buildSessionStateReminder();
                 // The scheduler is the only automatic path that may compress old evidence.
                 // Normal tool pushes and lifecycle tracking remain metadata-only.
                 // 步前:五区 Budget Scheduler 在当前完整 history 上决策；开关关闭时退化回 maybeCompact 路径。
@@ -294,7 +322,7 @@ export async function runAgentCore(opts) {
                 let historyRebuilt = false;
                 const compactStartedAt = Date.now();
                 if (scheduler) {
-                    historyRebuilt = await scheduler.runStep(history, step, activeTools);
+                    historyRebuilt = await scheduler.runStep(history, step, activeTools, sessionStateText ? estimateTokens(sessionStateText) : 0);
                     if (scheduler.lastRunLog?.compactHistoryCalled) {
                         emitTrace('compact', {
                             source: 'automatic',
@@ -326,8 +354,8 @@ export async function runAgentCore(opts) {
                         runtimeContextState.lifecycleStats = lifecycle.stats();
                     }
                     rehydrateArtifacts(runtimeContextState, history);
-                    // ② compact 后把活跃 plan 重注入系统提示，避免 agent 因上下文压缩丢失执行计划。
-                    reinjectActivePlanIntoSystem(history);
+                    // 会话状态(活跃 plan + 笔记段)不再回写 history[0]:每步都会在 requestHistory
+                    // 末尾注入最新副本(见下方 ephemeralReminder),compact 后自然恢复。
                 }
                 hooks.onStepStart?.(); // 主 agent:spinner.start('思考中')
                 mode = 'idle';
@@ -337,31 +365,29 @@ export async function runAgentCore(opts) {
                 const modelStartedAt = Date.now();
                 const provider = safeProviderId(requestBaseURL);
                 emitTrace('model_start', { model: requestModel, provider });
-                // 动态注入(仅追加到 system 末尾,不触碰 staticBody 前缀 → 不破坏 prompt 缓存):
-                //  - 开场分析:仅主线(step===0 且 !suppressOpeningAnalysis)注入——即"用户发一个任务后,
-                //    agent 第一次模型调用"。子代理经 spawn.ts 传 suppressOpeningAnalysis:true 排除。
-                //  - historyRebuilt:compact 恢复步;要求重新锚定目标。两者可叠加但互不串扰。
-                //  .filter(Boolean) 保证空段不产生多余空行;后续 step 均为空串 → system 前缀稳定命中缓存。
-                //  安全保证:此段只拼进 requestHistory(新建对象),绝不回写 history[0],故不会跨 step/跨 turn 残留。
-                const dynamicSystemSuffix = [
+                // 动态注入(prompt 缓存关键):所有随步/随文件变化的提示统一拼成**历史末尾**一条
+                // ephemeral system 消息,不再改写 history[0]。这样系统提示 + 已有对话逐字节稳定,
+                // 支持自动前缀缓存的后端(OpenAI / DeepSeek / GLM / Qwen)可从头命中,只有尾部这
+                // 一小条随内容变化;若改写 history[0],单次 plan_update 就会让 6-8k 的系统提示
+                // 在本轮后续每步全价重算。
+                //  - 开场分析:仅主线(step===0 且 !suppressOpeningAnalysis)——用户发任务后 agent
+                //    的第一次模型调用。子代理经 spawn.ts 传 suppressOpeningAnalysis:true 排除。
+                //    放在尾部还有额外好处:step 0 与 step 1 的前缀不再因这段的出现/消失而错位。
+                //  - historyRebuilt:compact 恢复步,要求重新锚定目标。
+                //  - 会话状态:notes.md 的活跃 plan + 笔记正文(纯读,每步重取,始终最新)。
+                //  .filter(Boolean) 保证空段不产生多余空行;三段全空时不追加任何消息(requestHistory === history)。
+                //  安全保证:只拼进 requestHistory(新建数组),绝不写回 history,故不会跨 step/跨 turn 残留。
+                const ephemeralReminder = [
                     (!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
                         ? '## Post-compaction recovery\nContext was compacted before this request. Re-establish the current objective and unresolved work from retained evidence or the session note, avoid repeating completed investigation, and re-read exact file context before any dependent edit.'
                         : '',
+                    sessionStateText, // 调度器之前已取(并计入压力线),此处复用同一份,不重复读文件
                 ].filter(Boolean).join('\n\n');
-                const systemMessage = history[0];
-                const requestHistory = dynamicSystemSuffix
-                    && systemMessage?.role === 'system'
-                    && typeof systemMessage.content === 'string'
-                    ? [
-                        {
-                            ...systemMessage,
-                            content: `${systemMessage.content}\n\n${dynamicSystemSuffix}`,
-                        },
-                        ...history.slice(1),
-                    ]
+                const requestHistory = ephemeralReminder
+                    ? [...history, { role: 'system', content: ephemeralReminder }]
                     : history;
                 // 实时用量:当前步 prompt 估算(含校准系数)+ 流式累计 completion 估算,
                 // 叠上已完成步的实测 turnUsage,经 onLiveUsage 推给底栏实时 chip。
@@ -461,6 +487,14 @@ export async function runAgentCore(opts) {
                 onContextUpdate?.();
                 if (result.toolCalls.length > 0) {
                     toolCallCount += result.toolCalls.length;
+                    // 若 content 只是 Claude 式 "Tool results:" 噪声，清空它：不补换行、不写入 history，
+                    // 避免污染后续轮次上下文并在 TUI 泄露为孤立行。
+                    if (result.content && isToolResultsNoise(result.content)) {
+                        result.content = null;
+                        mode = 'idle';
+                        gotText = false;
+                        lastChar = '';
+                    }
                     // 流式正文末尾补换行(若 onToolCall 已补则 lastChar='\n',此处 no-op);防 ● 行黏在正文行尾
                     if (mode !== 'idle' && lastChar !== '\n')
                         hooks.onTextEnd?.();
@@ -602,7 +636,7 @@ export async function runAgentCore(opts) {
                             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);
+                                const tool = findTool(tc.name);
                                 const argumentsValid = tool && parsed !== null
                                     ? validateToolArguments(tool, parsed).valid
                                     : false;
@@ -635,14 +669,18 @@ export async function runAgentCore(opts) {
                             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, {
+                            const started = entries.map((entry) => {
+                                if (entry.denied)
+                                    return Promise.resolve(entry.denied);
+                                const hint = argumentErrorHint(entry.tc.name, runtimeContextState);
+                                return executeToolOutcome(entry.tc.name, entry.tc.arguments, signal, {
                                     callId: entry.tc.id,
+                                    ...(hint ? { argumentErrorHint: hint } : {}),
                                     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];
@@ -693,7 +731,7 @@ export async function runAgentCore(opts) {
                             // 权限预检查:在渲染 ● 头之前弹确认面板(体验:先问再执行,而非执行完再问)。
                             // 拒绝时只渲染拒绝结果,不渲染执行头;放行则继续走 header → start → executeTool 流程。
                             const parsed = parseArgs(tc.arguments);
-                            const tool = tools.find((t) => t.name === tc.name);
+                            const tool = findTool(tc.name);
                             const argumentsValid = tool && parsed !== null
                                 ? validateToolArguments(tool, parsed).valid
                                 : false;
@@ -726,8 +764,10 @@ export async function runAgentCore(opts) {
                                 : 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,
+                                ...(serialHint ? { argumentErrorHint: serialHint } : {}),
                                 onLockAcquired: (lockedArgs) => {
                                     if (mutationParsed)
                                         diff = readDiffContext(tc, lockedArgs);
@@ -763,12 +803,12 @@ export async function runAgentCore(opts) {
                             i++;
                         }
                     }
-                    // A(事件驱动重同步):本步若改动了 notes.md,把最新 plan 块刷回 history[0],
-                    // 让模型上下文镜像当前勾选态(不再停留在轮首的旧副本)。只在 mtime 变化时触发,零额外 churn。
+                    // A(计划触碰计数):本步若改动了 notes.md 则清零计数。会话状态本身无需在此重注入——
+                    // 每步都会由 buildSessionStateReminder() 在 requestHistory 末尾重建最新副本(见上方注入点),
+                    // 所以模型下一步看到的必然是当前勾选态。只保留计数,避免多余的 history 改写(prompt 缓存)。
                     // B(nag 提醒):连续 N 步有工具活动但没更新 plan,在当前步第一条 tool_result 前注入提醒。
                     const notesMtimeAfter = getNotesMtime();
                     if (notesMtimeAfter !== notesMtimeBefore) {
-                        reinjectActivePlanIntoSystem(history);
                         stepsSincePlanTouch = 0;
                     }
                     else {

package/dist/agent/index.js

@@ -7,7 +7,6 @@ import { Spinner } from '../ui/spinner.js';
 import { summarizeToolCall, summarizeToolResult, truncateDisplay, fmtElapsed, } from '../ui/render.js';
 import { renderFileChange } from '../ui/diff.js';
 import * as layout from '../ui/layout.js';
-import * as content from '../ui/content.js';
 import * as batch from '../ui/batch.js';
 import { beginTurn } from '../rollback/index.js';
 import { config } from '../config/index.js';
@@ -27,17 +26,10 @@ let subAgentGroupPendingSeparator = false;
 /** 派生子 agent 的工具名。它的调用要独占一批:子 agent 的实时工具明细会挂到这一行下面,
  *  并行派发多个子 agent 时,每个子 agent 才有自己可归属的摘要行。 */
 const SUB_AGENT_TOOL = 'sub-agent';
-/** 缓冲尾部是否已经是空白行(去掉 ANSI 后无可见字符)。用于避免 sub-agent 分隔空行叠成两行。 */
+/** 缓冲尾部是否已经是空白行(去掉 ANSI 后无可见字符)。用于避免 sub-agent 分隔空行叠成两行。
+ *  实现委托 layout.isLastContentRowBlank(compact 等模块共用同一判断)。 */
 function isLastContentRowBlank() {
-    // 用 committedRows 而不是 totalRows：hasCurrent 那行是未提交的光标等待位，
-    // 永远空白，不能把它当作“已经有一条空行分隔”。
-    const committed = content.committedRows();
-    if (committed === 0)
-        return false;
-    const line = content.lineAt(committed - 1);
-    if (line === null)
-        return false;
-    return line.replace(/\x1b\[[0-9;]*m/g, '').trim().length === 0;
+    return layout.isLastContentRowBlank();
 }
 let turnFileChanges = [];
 function lineDelta(oldText, newText) {
@@ -274,33 +266,73 @@ onContextUpdate) {
     let textBoundaryNewlines = 0;
     let hasPendingTextBoundary = false;
     let toolBatchFollowsText = false;
+    // Claude 等模型在 tool_calls 前常输出 "Tool results:" 这类无意义叙述。
+    // 它违反 silent execution，会在正文区泄露成孤立行。这里先缓冲，若累积内容
+    // 只是该噪声则抑制；一旦后面跟了实质正文，再丢弃噪声前缀并 flush。
+    let pendingNarration = '';
+    let narrationIsNoise = false;
+    const TOOL_RESULTS_NOISE_RE = /^(?:\s*Tool results:\s*)+$/i;
+    function writeAssistantText(s) {
+        const inToolBlock = currentBatchId !== null || subAgentGroupId !== null || subAgentGroupPendingSeparator;
+        if (inToolBlock && s.trim().length === 0)
+            return;
+        const followsToolBatch = inToolBlock;
+        // batch 收尾已经统一留了一条空白行。部分后端会把下一段正文以 \n / \n\n
+        // 开头发来；去掉这些“边界换行”，避免与 UI 分隔叠成两条空白行。
+        const visible = followsToolBatch ? s.replace(/^(?:[ \t]*\r?\n)+/, '') : s;
+        // 正文是工具批次边界：只有“连续且中间没有正文”的工具调用才合并。
+        // 一旦模型开始解释阶段结果，立即收尾当前摘要；后续工具重新建立批次。
+        if (visible)
+            flushToolBatch();
+        spinner.stop(); // 任何正文 token 都停 spinner(首 token 停「思考中」;onToolCall 重启后若又来文本则停「生成中」)。未旋转时 stop 为 no-op。
+        layout.contentWriteMd(visible); // 正文走 markdown 渲染(代码块高亮 / 标题 / 列表 / 行内 …),见 ui/markdown.ts
+        if (visible) {
+            lastChar = visible[visible.length - 1];
+            if (visible.trim().length > 0) {
+                hasPendingTextBoundary = true;
+                textBoundaryNewlines = 0;
+            }
+        }
+    }
+    function trySuppressNoise(s) {
+        pendingNarration += s;
+        const stripped = pendingNarration.replace(/\s+/g, ' ').trim();
+        if (TOOL_RESULTS_NOISE_RE.test(stripped)) {
+            narrationIsNoise = true;
+            return null;
+        }
+        let visible = pendingNarration;
+        if (narrationIsNoise) {
+            visible = pendingNarration.replace(/^(?:\s*Tool results:\s*)+/i, '');
+            narrationIsNoise = false;
+        }
+        pendingNarration = '';
+        return visible;
+    }
+    function flushPendingNarrationIfAny() {
+        if (!pendingNarration)
+            return;
+        const stripped = pendingNarration.replace(/\s+/g, ' ').trim();
+        if (TOOL_RESULTS_NOISE_RE.test(stripped)) {
+            pendingNarration = '';
+            narrationIsNoise = false;
+            return;
+        }
+        const visible = pendingNarration;
+        pendingNarration = '';
+        narrationIsNoise = false;
+        writeAssistantText(visible);
+    }
     const hooks = {
         onText: (s) => {
-            // 纯空白 chunk 在视觉上不是正文：既不切 batch，也不写入 markdown 缓冲。
-            // 部分兼容后端会在连续工具轮次间流出 " " / "\n"，若据此切批会漏掉首个工具。
-            // sub-agent 独占批不占 currentBatchId，但同样处在“工具块刚结束”的边界上。
-            const inToolBlock = currentBatchId !== null || subAgentGroupId !== null || subAgentGroupPendingSeparator;
-            if (inToolBlock && s.trim().length === 0)
-                return;
-            const followsToolBatch = inToolBlock;
-            // batch 收尾已经统一留了一条空白行。部分后端会把下一段正文以 \n / \n\n
-            // 开头发来；去掉这些“边界换行”，避免与 UI 分隔叠成两条空白行。
-            const visible = followsToolBatch ? s.replace(/^(?:[ \t]*\r?\n)+/, '') : s;
-            // 正文是工具批次边界：只有“连续且中间没有正文”的工具调用才合并。
-            // 一旦模型开始解释阶段结果，立即收尾当前摘要；后续工具重新建立批次。
-            if (s)
-                flushToolBatch();
-            spinner.stop(); // 任何正文 token 都停 spinner(首 token 停「思考中」;onToolCall 重启后若又来文本则停「生成中」)。未旋转时 stop 为 no-op。
-            layout.contentWriteMd(visible); // 正文走 markdown 渲染(代码块高亮 / 标题 / 列表 / 行内 …),见 ui/markdown.ts
-            if (visible) {
-                lastChar = visible[visible.length - 1];
-                if (visible.trim().length > 0) {
-                    hasPendingTextBoundary = true;
-                    textBoundaryNewlines = 0;
-                }
-            }
+            const visible = trySuppressNoise(s);
+            if (visible === null)
+                return; // 纯噪声，抑制
+            writeAssistantText(visible);
         },
         onToolCall: (name) => {
+            // 工具调用开始前，先 flush 被抑制的叙述缓冲（若是纯噪声则丢弃）。
+            flushPendingNarrationIfAny();
             // 文本/思考已流完,模型转而生成 tool_call 参数(可能很长,如 write_file 整篇内容):
             // 补换行(让随后的 ● 行与 diff 不黏在正文末尾)+ 启「生成中」内联 spinner,内容区不再干等。
             if (hasPendingTextBoundary) {
@@ -358,6 +390,7 @@ onContextUpdate) {
             layout.contentWrite(`${ui.dim}${t('agent.aborted')}${ui.reset}\n`);
         },
         onDone: (elapsedMs, usage) => {
+            flushPendingNarrationIfAny();
             flushToolBatch();
             writeChangeOverview();
             const tok = formatTurnTokens(usage);
@@ -427,9 +460,12 @@ function formatTurnTokens(usage) {
         return '';
     const fmt = (n) => (n < 1000 ? `${n}` : `${(n / 1000).toFixed(total >= 10000 ? 0 : 1)}k`);
     const cached = usage.cachedTokens;
+    const cacheCreated = usage.cacheCreationTokens ?? 0;
     const reasoning = usage.reasoningTokens;
     const billablePrompt = usage.promptTokens - cached;
     const extras = [];
+    if (cacheCreated > 0)
+        extras.push(`cache created ${fmt(cacheCreated)}`);
     if (cached > 0)
         extras.push(`${Math.round((cached / Math.max(1, usage.promptTokens)) * 100)}% cached`);
     if (reasoning > 0)

package/dist/agent/spawn.js

@@ -250,6 +250,10 @@ export async function spawnAgent(opts) {
         toolsOverride,
         contextState: localContextState,
         suppressOpeningAnalysis: true, // 子代理不注入「开场分析」:仅主线面对用户的首次响应用
+        // 子代理不注入主会话「会话状态」(plan + 笔记):systemPrompt 已用
+        // buildMocodeCorePrompt() 切掉会话私有尾段,工具表也排除了 plan_update——
+        // 灌主计划只会干扰窄 worker 并白付 token。
+        suppressSessionState: true,
         onToolOutcome: (tool, args) => {
             if (tool === 'read_file' && typeof args.path === 'string')
                 readSet.add(args.path);