mocode-ai 0.7.2 → 1.0.1

package/README.md

@@ -8,13 +8,67 @@ A terminal coding agent: give it a goal, and it **completes it autonomously**
 
 MoCode explores your code, reads/writes/edits files, runs shell commands, and searches the web on its own, driving the task forward through a loop of "think → call a tool → observe the result → think again." It works with any OpenAI-compatible endpoint (GLM, DeepSeek, Qwen, local Ollama / vLLM, etc.), runs as a full-screen TUI with streaming output and visible reasoning.
 
+## Architecture
+
+MoCode is organized as a layered runtime: the terminal experience drives an autonomous core, the core reaches capabilities through a guarded execution plane, and a persistent intelligence layer keeps long-running work coherent.
+
+<p align="center"><img src="./assets/architecture/system-overview.svg" alt="MoCode layered system architecture" width="100%"></p>
+
+### Autonomous execution loop
+
+Each model response is one step in a closed loop. Tool calls are classified by declared capabilities, safe reads can run in parallel, writes acquire canonical resource locks, observations are encoded before returning to context, and code changes pass through automatic validation.
+
+<p align="center"><img src="./assets/architecture/agent-loop.svg" alt="MoCode autonomous agent execution loop" width="100%"></p>
+
+### Context that ages instead of exploding
+
+Tool output does not accumulate as an undifferentiated transcript. Typed encoders, relevance pruning, an observation lifecycle, age-aware compression, and a five-zone budget scheduler continuously reshape the active working set while sessions, snapshots, skills, notes, and memory retain durable knowledge.
+
+<p align="center"><img src="./assets/architecture/context-engine.svg" alt="MoCode context engineering and durable memory architecture" width="100%"></p>
+
+### Multi-agent work without unsafe shared writes
+
+Read-only sub-agents fan out concurrently. Writer agents work inside private filesystem overlays and return structured ChangeSets; the coordinator checks expected hashes, acquires canonical locks, performs conflict-safe merges, and runs one unified verification gate in the main workspace.
+
+<p align="center"><img src="./assets/architecture/multi-agent.svg" alt="MoCode multi-agent overlay and ChangeSet coordination" width="100%"></p>
+
+### Controlled execution: permission gates and capability scheduling
+
+Every mutating tool calls into a permission layer before it runs. Tools are classified `safe` / `confirm` / `dangerous`, scopes can be `once` / `session` / `project` / global-tool, fingerprints are stable hashes (command, path, or args), and the persistent record lives in `~/.mocode/permissions.json` (v3 schema, with v2 resource grants still loaded). Piped or CI environments default to deny until you opt in.
+
+<p align="center"><img src="./assets/architecture/permission-model.svg" alt="MoCode permission model: tool classes, four-tier grants, fingerprinting, durable storage" width="100%"></p>
+
+### Verification cascade: cheap checks first, expensive checks only on demand
+
+Code changes go through V0 (file post-conditions) → V1 (scoped tsc/eslint markers) → V2 (targeted unit tests) → V3 (affected package scripts). The first actionable failure stops the cascade and is fed back to the agent as a fresh observation; a SHA-256 content cache skips repeated work on unchanged files.
+
+<p align="center"><img src="./assets/architecture/verification-cascade.svg" alt="MoCode verification cascade V0 to V3 with content fingerprint cache" width="100%"></p>
+
+### Rollback timeline: per-mutation snapshots, restore by turn
+
+A clean undo point is saved before every mutating tool. `/rollback <turnId>` restores file buffers in reverse-chronological order under canonical resource locks, then reruns V0+V1 to confirm a clean state — never re-runs the model. Read tools, network effects, and binary changes are explicitly out of scope, kept honest in the contract.
+
+<p align="center"><img src="./assets/architecture/rollback-flow.svg" alt="MoCode rollback timeline and per-turn snapshot flow" width="100%"></p>
+
+### Context controls: five independent dials, not one big toggle
+
+`autoCompact` / `contextOptimize` / `contextRelprune` / `contextLifecycle` / `contextBudget` each gate a different knob (push-time compression, encoders, superseded-read pruning, observation lifecycle, five-zone scheduler). Each is independently killable via a `MOCODE_*=false` env var; the observation lifecycle runs even with all toggles off, so context still ages instead of exploding. An EWMA self-calibrates the token estimator against real provider usage.
+
+<p align="center"><img src="./assets/architecture/context-controls.svg" alt="MoCode context controls: five independent toggles, observation lifecycle, token self-calibration" width="100%"></p>
+
+### Desktop pet: a passive mirror over WebSocket
+
+The optional Electron sub-package (`packages/pet-app`) shows a stateful floating character that mirrors agent activity via a one-way WebSocket stream. Quit with `/pet quit`. The renderer owns no business logic; the agent loop is unchanged regardless of whether the pet is running.
+
+<p align="center"><img src="./assets/architecture/pet-bridge.svg" alt="MoCode desktop pet bridge: hooks, frames, Electron client" width="100%"></p>
+
 ## Why MoCode
 
 MoCode isn't a chat box with a coat of paint — it's an agent that actually gets things done:
 
 - **Autonomous multi-step execution** — In a single conversation, the agent chains multiple steps on its own: read code, edit code, run tests, fix based on errors, and so on. It decides the next step without you nagging it. When it hits a decision point, it calls `ask_human` to pop up a panel and ask you (blocking until you respond).
 - **Parallel read-only tools** — Consecutive read-only operations in a turn (reading files, grep, glob, codegraph, web search/fetch) run concurrently, so total time is roughly the slowest single call instead of the sum of all of them. Operations with side effects (writing/editing files) stay sequential to preserve snapshot ordering and data safety.
-- **Sub-agents divide and conquer** — Complex tasks can spawn independent sub-agents, each with its own conversation history (isolated from the main thread), an optional restricted toolset, and a step cap. Sub-agent calls execute serially while they share the main workspace, preventing concurrent writes from racing; each returns only a summary to the main thread.
+- **Sub-agents divide and conquer** — Complex tasks can spawn independent sub-agents with isolated histories and scoped toolsets. Read-only workers can fan out concurrently; writer workers run in private filesystem overlays and return ChangeSets that are merged under expected-hash checks and canonical resource locks. Only structured findings return to the main thread.
 - **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.
 - **Automatic context compression** — As the context window fills up, a three-tier compression kicks in (trim individual results → compact older tool results in place → summarize older turns), so long sessions never overflow. `/context` shows live token usage; `/compact` triggers manual compression (optionally with a focus hint to preserve what matters).
 - **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.
@@ -112,8 +166,8 @@ Common backend `base_url` values:
 | `ANYSEARCH_BASE_URL`        | Search API endpoint                                                    | `https://api.anysearch.com` |
 | `SKILLS_DIRS`               | Override the default skill scan directories (platform path separator) | three default directories   |
 | `MOCODE_CONTEXT_OPTIMIZE`   | Typed encoding of tool results before they reach the LLM (tree/search/log…); disable for raw passthrough (length trimming only) | `true` |
-| `MAX_STEPS`                 | Max agent loop steps per turn (prevents infinite loops)               | `200`                        |
-| `SUB_AGENT_MAX_STEPS`       | Default step cap for sub-agents (spawned via the `task` tool)         | `50`                         |
+| `MAX_STEPS`                 | Max agent loop steps per turn (infinite-loop safety only)             | `1000`                       |
+| `SUB_AGENT_MAX_STEPS`       | Sub-agent loop safety ceiling; defaults to the main-agent value       | `1000`                       |
 | `SANDBOX_ROOT`               | Sandbox root directory (file operation boundary; falls back to cwd if unset) | none                  |
 | `MOCODE_THEME`               | Color theme (default/dark/light…; shell env takes precedence over file) | `default`                   |
 
@@ -149,7 +203,7 @@ The agent operates in **the working directory it was launched from** — to have
 | `ask_human`        | Pop up a Q&A panel at decision points; user picks a preset or types freely (blocks until answered) |
 | `switch_mode`      | Switch between `plan` (read-only planning) and `auto` (full execution); the agent can call this itself to explore before acting |
 | `drop_context`     | Replace irrelevant old tool results in history with stubs to free up context (preserves tool_call_id pairing, leaves system prompt and current turn untouched, idempotent) |
-| `task`             | Spawn a sub-agent for an independent subtask (isolated history, optional restricted toolset, optional step cap); calls run serially while sharing the workspace and return only a summary |
+| `sub-agent`        | Spawn a capable isolated worker; read tasks can run concurrently and writes use overlay + ChangeSet safe merge |
 
 | `memory_save`      | Save a piece of cross-session long-term memory (title indexed, body fetched on demand) |
 | `memory_search`    | Search memory bodies by keyword; hits boost the recall count (affects forgetting decay) |

package/README.zh-CN.md

@@ -8,13 +8,67 @@
 
 mocode 自己探索代码、读写改文件、执行命令、联网查资料,以「思考 → 调用工具 → 观察结果 → 再思考」的循环一步步把任务推进到完成。接任意 OpenAI 兼容接口(GLM、DeepSeek、Qwen、本地 Ollama / vLLM 等),全屏 TUI 交互,流式输出、思考过程可见。
 
+## 架构
+
+MoCode 是一个分层的自治运行时：终端交互层驱动 Agent 内核，内核通过受控能力平面执行真实操作，持久化认知层则让长任务和跨会话工作保持连贯。
+
+<p align="center"><img src="./assets/architecture/system-overview-zh-CN.svg" alt="MoCode 分层系统架构" width="100%"></p>
+
+### 自治执行循环
+
+每次模型响应都是闭环中的一步。工具调用按能力声明分类，安全读取可以并行，写操作获取规范化资源锁，观察结果编码后才回到上下文，代码改动最终经过自动验证门。
+
+<p align="center"><img src="./assets/architecture/agent-loop-zh-CN.svg" alt="MoCode 自治 Agent 执行循环" width="100%"></p>
+
+### 会衰减、不会膨胀的上下文
+
+工具输出不会作为无差别日志无限堆积。类型化编码、相关性裁剪、观察生命周期、年龄感知压缩和五区预算调度持续重塑活跃工作集；会话、Snapshot、Skill、notes.md 与长期记忆负责保留耐久知识。
+
+<p align="center"><img src="./assets/architecture/context-engine-zh-CN.svg" alt="MoCode 上下文工程与持久化记忆架构" width="100%"></p>
+
+### 多 Agent 并行，但不冒险共享写入
+
+只读子 Agent 可以并行扇出；写任务在私有文件系统 overlay 中完成并返回结构化 ChangeSet。协调器校验 expected hash、获取规范化资源锁、安全合并冲突，最后由主工作区统一执行验证。
+
+<p align="center"><img src="./assets/architecture/multi-agent-zh-CN.svg" alt="MoCode 多 Agent overlay 与 ChangeSet 协调" width="100%"></p>
+
+### 受控执行:权限门 + 能力调度
+
+每个写入工具在执行前都会经过权限层。工具分为 `safe` / `confirm` / `dangerous` 三档,授权粒度支持 `once` / `session` / `project` / 全局工具四档,指纹使用稳定哈希(命令、路径或参数),持久化记录落在 `~/.mocode/permissions.json`(v3 格式,会自动加载 v2 资源授权)。管道/CI 环境默认拒绝所有需确认的操作,除非显式开启。
+
+<p align="center"><img src="./assets/architecture/permission-model-zh-CN.svg" alt="MoCode 权限模型:工具分级、四档授权、指纹、持久化" width="100%"></p>
+
+### 验证瀑布:便宜检查先做,贵检查按需上场
+
+代码改动按 V0(文件级后置条件)→ V1(限范围的 tsc/eslint)→ V2(定向单元测试)→ V3(受影响 package 的脚本)由低到高执行。首个可操作失败立即停止,作为新的观察反馈给 Agent;SHA-256 文件指纹缓存避免对未改动文件重复劳动。
+
+<p align="center"><img src="./assets/architecture/verification-cascade-zh-CN.svg" alt="MoCode 自动验证瀑布 V0 到 V3,带文件指纹缓存" width="100%"></p>
+
+### 回滚时间线:每次写入都留干净撤销点
+
+每次写入工具执行前先存一份 undo 快照。`/rollback <turnId>` 按时间逆序在 canonical 资源锁下恢复文件缓冲,然后重跑 V0+V1 验证状态干净——完全不重跑模型。读取类工具、网络副作用、二进制改动明确不在截图范围,契约里写死。
+
+<p align="center"><img src="./assets/architecture/rollback-flow-zh-CN.svg" alt="MoCode 回滚时间线和每轮快照流" width="100%"></p>
+
+### 上下文控制:五个独立开关,不是一锅端
+
+`autoCompact` / `contextOptimize` / `contextRelprune` / `contextLifecycle` / `contextBudget` 各自把控一个旋钮(push 压缩、编码器、被取代读取的剪裁、观察生命周期、五区调度器)。每个都能用 `MOCODE_*=false` 单独关;即使五个全关,观察结果仍按生命周期老化。token 估算带 EWMA 自动校准真实 provider 用量。
+
+<p align="center"><img src="./assets/architecture/context-controls-zh-CN.svg" alt="MoCode 上下文控制:五个独立开关、观察生命周期、token 自校准" width="100%"></p>
+
+### 桌宠:WebSocket 上的被动镜像
+
+可选 Electron 子包(`packages/pet-app`)用一个悬浮小角色镜像 agent 状态:单向 WebSocket 推送事件帧,`/pet quit` 完全关闭。渲染层零业务逻辑,无论桌宠是否在跑,主 agent 循环一字不改。
+
+<p align="center"><img src="./assets/architecture/pet-bridge-zh-CN.svg" alt="MoCode 桌宠桥:hooks、事件帧、Electron 客户端" width="100%"></p>
+
 ## 为什么用 mocode
 
 mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 
 - **自主多步推进** — 一次对话里连续多步:读代码、改代码、跑测试、根据报错再改……agent 自己决定下一步,中途不用你反复催。遇到卡点会调 `ask_human` 弹面板问你(阻塞到回应)。
 - **只读工具并行执行** — 一轮里连续的只读操作(读文件、grep、glob、codegraph、联网搜索/抓取)自动并发跑,总耗时 ≈ 最慢一个,而不是逐个排队。写文件 / 改文件这类有副作用的操作仍串行,保快照顺序与数据安全。
-- **子 agent 分而治之** — 复杂任务可派生独立子 agent:各自有自己的对话历史(不污染主线),可限定工具集和步数上限。共享主工作区期间多个 task 串行执行,避免并发写冲突;每个子任务最后只把摘要回灌主线。
+- **子 agent 分而治之** — 复杂任务可派生拥有独立历史与受限工具集的子 agent。只读 worker 可并行扇出；写 worker 在私有文件系统 overlay 中运行，返回的 ChangeSet 经过 expected hash 校验与规范化资源锁后才合并。主线只接收结构化发现，不接收过程噪声。
 - **计划 / 执行双模式** — `plan` 模式下只读探查(读代码、查索引、搜索,绝不写盘、不跑命令、不派生子 agent),产出计划;`auto` 模式全量工具放开。agent 还能在两者间自切换——先把陌生代码库摸清,再动手改。
 - **上下文自动压缩** — 接近窗口上限时三层压缩(单条结果裁剪 → 旧工具结果原地微压缩 → 旧对话摘要),长会话也不爆窗口;`/context` 实时显示 token 用量,`/compact` 可手动压缩(能带焦点指令聚焦保留)。
 - **跨会话长期记忆** — agent 能把项目架构、约定、踩过的坑存成长期记忆,下次会话自动加载;后台还会定期从对话里反思挖掘值得记住的事。记忆可增删改、带召回衰减。
@@ -110,8 +164,8 @@ LLM_MODEL=glm-4.6                              # 换成你的模型名
 | `ANYSEARCH_BASE_URL`    | 搜索 API 端点                                  | `https://api.anysearch.com` |
 | `SKILLS_DIRS`           | 覆盖默认 skill 扫描目录(平台分隔符)                     | 三目录自动扫描                     |
 | `MOCODE_CONTEXT_OPTIMIZE` | 工具结果进 LLM 前的类型化编码(树/搜索/日志…),关掉则原样进(仅长度裁剪) | `true`                      |
-| `MAX_STEPS`             | 每轮 agent 循环最大步数(防无限循环)                    | `200`                       |
-| `SUB_AGENT_MAX_STEPS`   | 子 agent(task 工具派生)默认步数上限                  | `50`                        |
+| `MAX_STEPS`             | 每轮 Agent 循环最大步数（仅防无限循环）                 | `1000`                      |
+| `SUB_AGENT_MAX_STEPS`   | 子 Agent 循环安全上限，默认与主 Agent 一致             | `1000`                      |
 | `SANDBOX_ROOT`          | 沙箱根目录(文件操作边界;未配则用 cwd 兜底)                | 无                           |
 | `MOCODE_THEME`          | 颜色主题(default/dark/light…;shell 设置优先于文件)      | `default`                   |
 
@@ -147,7 +201,7 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `ask_human`     | 决策点弹终端问答面板,用户选预设项或自由输入(阻塞至回应)                            |
 | `switch_mode`   | 在 `plan`(只读规划)与 `auto`(全量执行)间切换;agent 可自行调用,先探查再动手       |
 | `drop_context`  | 把历史里无关的旧工具结果替换为存根释放上下文(保 tool_call_id 配对,不动 system 与当前轮;幂等) |
-| `task`          | 派生子 agent 执行独立子任务(独立历史、可受限工具集、可设步数上限);共享工作区期间串行执行,只回摘要 |
+| `sub-agent`     | 派生具备完整能力的隔离子 Agent；只读任务可并发，写任务通过 overlay + ChangeSet 安全合并 |
 
 | `memory_save`   | 存一条跨会话长期记忆(标题进索引,正文按需取)                                  |
 | `memory_search` | 按关键词搜记忆正文,命中即提升召回计数(影响遗忘衰减)                              |

package/dist/agent/core.js

@@ -8,11 +8,12 @@ import { readFileSync } from 'node:fs';
 import { chat, estimatePromptTokens, planChatTools, chatTools, } from '../llm/index.js';
 import { executeToolOutcome, getToolCapabilities, isFileMutationTool, tools, } 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, 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 { optimizeToolResult, HOT_TURN_WINDOW, userTurnBoundary, recordArtifact, invalidateArtifacts, rehydrateArtifacts, } from '../context/index.js';
 import { createAgeAwareEncodingState, } from '../context/age-aware.js';
 import { createRelevancePruner } from '../context/relevance.js';
 import { isToolResultSuccess } from '../context/utils.js';
@@ -50,7 +51,7 @@ function parseArgs(raw) {
  * (直接拼,不哈希——避免热路径开销;args 长度本身有限,内存压力可忽略)。
  * null 表示未触发,不污染输出。
  */
-const THRASH_THRESHOLD = 3;
+const THRASH_THRESHOLD = 2;
 function thrashHint(name, args, count) {
     if (count < THRASH_THRESHOLD)
         return null;
@@ -58,9 +59,34 @@ function thrashHint(name, args, count) {
         'either failing or returning the same content. STOP retrying and switch strategy:\n' +
         '- read_file / glob → path likely wrong; call `glob` to discover paths, or `ask_human`\n' +
         '- run_command → Windows path-escaping issue; use `read_file` / `glob` with absolute paths instead\n' +
-        '- edit_file → old_string mismatch; re-read the file to find the exact text\n' +
+        '- write_file / edit_file CHANGE_CONFLICT → do not resend; read_file the same path and use its latest hash (use null only when read_file says the path is missing)\n' +
+        '- edit_file old_string mismatch → re-read the exact region and copy it verbatim\n' +
         '- otherwise → re-read the tool description; the argument shape may be wrong');
 }
+/**
+ * Detect only a strict streak of identical failures. Successful calls, or a
+ * different tool/argument pair, end the streak. This keeps intentional phased
+ * read_file/glob calls from being mislabeled after the underlying files change.
+ */
+export function createThrashTracker() {
+    let lastFailedFingerprint = null;
+    let consecutiveFailures = 0;
+    return (name, args, succeeded) => {
+        if (succeeded) {
+            lastFailedFingerprint = null;
+            consecutiveFailures = 0;
+            return null;
+        }
+        const fingerprint = `${name}\x00${args}`;
+        if (fingerprint === lastFailedFingerprint)
+            consecutiveFailures += 1;
+        else {
+            lastFailedFingerprint = fingerprint;
+            consecutiveFailures = 1;
+        }
+        return thrashHint(name, args, consecutiveFailures);
+    };
+}
 /** 只有显式声明 parallel 且无需权限确认的工具才进入普通并发组。 */
 function isParallelTool(name) {
     const tool = tools.find((candidate) => candidate.name === name);
@@ -72,6 +98,15 @@ function isResourceLockedTool(name) {
     const tool = tools.find((candidate) => candidate.name === 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);
+}
 /** 文件 mutation 由 capability metadata 判定，供 diff、回滚与上下文失效共用。 */
 const isMutationTool = (name) => isFileMutationTool(name);
 function deniedOutcome(name) {
@@ -141,11 +176,13 @@ function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runt
         content: optimizeToolResult(tc.name, output, tc.arguments, encodingContext),
     };
     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, history.length - 1, succeeded);
+        lifecycle.pushTool(history, messageIndex, succeeded);
     runtimeContextState.lifecycleStats = lifecycle?.stats();
 }
 /**
@@ -218,15 +255,10 @@ export async function runAgentCore(opts) {
             }
             : u;
     };
-    // Thrashing 检测:本轮内同 (name, args) 累计次数。≥3 在工具结果尾部追加 hint(见 thrashHint)。
-    // 只在 runAgentCore 内,turn 结束自然 GC;不跨 turn 持久(下一轮重新计数,避免误把历史判为 thrashing)。
-    const recentToolCalls = new Map();
-    const recordAndHint = (name, args) => {
-        const fp = `${name}\x00${args}`;
-        const c = (recentToolCalls.get(fp) ?? 0) + 1;
-        recentToolCalls.set(fp, c);
-        return thrashHint(name, args, c);
-    };
+    const addToolUsage = (outcome) => addUsage(outcome.usage);
+    // Only consecutive identical failures are thrashing. Any success (including
+    // a mutation between two reads) or different call resets the streak.
+    const recordAndHint = createThrashTracker();
     history.push({ role: 'user', content: userInput });
     // 中断回滚快照:push 用户消息后整段浅拷贝。abort 时 length=0;push(...saved) 还原。
     // 这样中断时至少保留用户消息(及之前的历史);每步工具全部执行完毕后刷新快照,
@@ -249,6 +281,7 @@ export async function runAgentCore(opts) {
         ? createLifecycleEngine(history)
         : null;
     runtimeContextState.lifecycleStats = lifecycle?.stats();
+    rehydrateArtifacts(runtimeContextState, history);
     // 预算调度器:每个 runAgentCore 实例一个，在 age-aware sweep 后评估并执行 warn / compact。
     // contextBudget 开关关闭时为 null。
     const scheduler = config.contextBudget !== false
@@ -309,6 +342,7 @@ export async function runAgentCore(opts) {
                         completed: false,
                         terminationReason: 'aborted',
                         finalText: null,
+                        usage: turnUsage,
                         validation: latestValidation,
                         changedFiles: mutation.changedFiles.map((item) => item.path),
                     };
@@ -361,6 +395,7 @@ export async function runAgentCore(opts) {
                         runtimeContextState.lifecycleStats = lifecycle.stats();
                     }
                     ageAware?.rehydrate(history);
+                    rehydrateArtifacts(runtimeContextState, history);
                 }
                 hooks.onStepStart?.(); // 主 agent:spinner.start('思考中')
                 mode = 'idle';
@@ -409,6 +444,7 @@ export async function runAgentCore(opts) {
                             completed: false,
                             terminationReason: 'aborted',
                             finalText: null,
+                            usage: turnUsage,
                             validation: latestValidation,
                             changedFiles: mutation.changedFiles.map((item) => item.path),
                         };
@@ -479,6 +515,20 @@ export async function runAgentCore(opts) {
                             ...(tc.id ? { providerToolCallId: tc.id } : {}),
                         });
                     }
+                    const traceToolRetry = (tc, index, retry) => {
+                        const traceCall = tracedCalls[index];
+                        emitTrace('tool_retry', {
+                            tool: tc.name,
+                            argumentHash: traceCall.args.sha256,
+                            attempt: retry.attempt,
+                            nextAttempt: retry.nextAttempt,
+                            waitMs: retry.waitMs,
+                            code: retry.code,
+                        }, {
+                            toolCallId: traceCall.toolCallId,
+                            ...(tc.id ? { providerToolCallId: tc.id } : {}),
+                        });
+                    };
                     const traceToolEnd = (tc, index, outcome) => {
                         const traceCall = tracedCalls[index];
                         emitTrace('tool_call_end', {
@@ -488,8 +538,13 @@ export async function runAgentCore(opts) {
                             code: outcome.code,
                             retryable: outcome.retryable,
                             durationMs: outcome.durationMs ?? 0,
-                            retry: 0,
+                            attempt: outcome.attempts ?? 1,
+                            retry: Math.max(0, (outcome.attempts ?? 1) - 1),
+                            retryDelayMs: outcome.retryDelayMs ?? 0,
                             changedFiles: outcome.changedFiles ?? [],
+                            staleFiles: outcome.staleFiles ?? [],
+                            ...(outcome.changeSet ? { changeSet: outcome.changeSet } : {}),
+                            ...(outcome.usage ? { nestedUsage: outcome.usage } : {}),
                         }, {
                             toolCallId: traceCall.toolCallId,
                             ...(tc.id ? { providerToolCallId: tc.id } : {}),
@@ -510,7 +565,7 @@ export async function runAgentCore(opts) {
                                 durationMs: 0,
                             };
                             hooks.onToolResult?.(currentCall, error, null, null, 1);
-                            const hint = recordAndHint(currentCall.name, currentCall.arguments);
+                            const hint = recordAndHint(currentCall.name, currentCall.arguments, false);
                             pushToolResult(history, currentCall, hint ? `${error}${hint}` : error, relprune, lifecycle, scheduler, runtimeContextState, false);
                             traceToolEnd(currentCall, i, outcome);
                             i++;
@@ -529,27 +584,32 @@ export async function runAgentCore(opts) {
                             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 }));
+                            const started = batch.map((tc, offset) => executeToolOutcome(tc.name, tc.arguments, signal, {
+                                dropContext,
+                                onRetry: (retry) => traceToolRetry(tc, i + offset, retry),
+                            }));
                             for (let k = 0; k < batch.length; k++) {
                                 const tc = batch[k];
                                 const outcome = await started[k];
+                                addToolUsage(outcome);
+                                opts.onToolOutcome?.(tc.name, parseArgs(tc.arguments) ?? {}, outcome);
                                 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);
+                                const hint = recordAndHint(tc.name, tc.arguments, outcome.status === 'success');
                                 pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
                             }
                             hooks.onToolDone?.();
                             i = j;
                         }
-                        else if (isResourceLockedTool(currentCall.name) &&
+                        else if (isResourceLockedCall(currentCall) &&
                             !(getAgentMode() === 'plan' && getPlanDisabledTools().has(currentCall.name))) {
                             // 连续文件 mutation：权限确认仍严格按原序进行；全部 preflight 完成后再启动。
                             // 每个执行在 registry 内按 canonical path 获取锁，不同文件可并发，同文件别名会排队。
                             let j = i;
                             while (j < calls.length &&
-                                isResourceLockedTool(calls[j].name) &&
+                                isResourceLockedCall(calls[j]) &&
                                 !getRuntimeDisabledTools().has(calls[j].name) &&
                                 !(getAgentMode() === 'plan' && getPlanDisabledTools().has(calls[j].name)))
                                 j++;
@@ -559,8 +619,11 @@ export async function runAgentCore(opts) {
                                 const tc = batch[k];
                                 const parsed = parseArgs(tc.arguments);
                                 const tool = tools.find((candidate) => candidate.name === tc.name);
+                                const argumentsValid = tool && parsed !== null
+                                    ? validateToolArguments(tool, parsed).valid
+                                    : false;
                                 let denied;
-                                if (tool) {
+                                if (tool && argumentsValid) {
                                     const perm = await checkPermission(tool, parsed ?? {}, signal);
                                     emitTrace('permission', {
                                         source: 'agent_tool',
@@ -586,28 +649,35 @@ 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
+                            const started = entries.map((entry, offset) => entry.denied
                                 ? Promise.resolve(entry.denied)
                                 : executeToolOutcome(entry.tc.name, entry.tc.arguments, signal, {
                                     dropContext,
                                     onLockAcquired: (lockedArgs) => {
                                         entry.diff = readDiffContext(entry.tc, lockedArgs);
                                     },
+                                    onRetry: (retry) => traceToolRetry(entry.tc, i + offset, retry),
                                 }));
                             for (let k = 0; k < entries.length; k++) {
                                 const entry = entries[k];
                                 const outcome = await started[k];
+                                addToolUsage(outcome);
+                                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);
-                                const hint = recordAndHint(entry.tc.name, entry.tc.arguments);
+                                const hint = recordAndHint(entry.tc.name, entry.tc.arguments, outcome.status === 'success');
                                 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();
+                                const invalidatedFiles = [...new Set([
+                                        ...(outcome.changedFiles ?? []),
+                                        ...(outcome.staleFiles ?? []),
+                                    ])];
+                                if (invalidatedFiles.length > 0) {
+                                    for (const changedFile of invalidatedFiles) {
+                                        relprune?.observeMutation(history, changedFile);
+                                        lifecycle?.pushMutation(history, history.length - 1, changedFile);
                                     }
+                                    invalidateArtifacts(runtimeContextState, history, invalidatedFiles);
+                                    runtimeContextState.lifecycleStats = lifecycle?.stats();
                                 }
                             }
                             if (firstAllowed)
@@ -632,7 +702,7 @@ export async function runAgentCore(opts) {
                                 };
                                 hooks.onToolResult?.(tc, err, null, null, 1);
                                 // Thrashing:同上
-                                const hint = recordAndHint(tc.name, tc.arguments);
+                                const hint = recordAndHint(tc.name, tc.arguments, false);
                                 pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
                                 traceToolEnd(tc, i, outcome);
                                 i++;
@@ -642,7 +712,10 @@ export async function runAgentCore(opts) {
                             // 拒绝时只渲染拒绝结果,不渲染执行头;放行则继续走 header → start → executeTool 流程。
                             const parsed = parseArgs(tc.arguments);
                             const tool = tools.find((t) => t.name === tc.name);
-                            if (tool) {
+                            const argumentsValid = tool && parsed !== null
+                                ? validateToolArguments(tool, parsed).valid
+                                : false;
+                            if (tool && argumentsValid) {
                                 const perm = await checkPermission(tool, parsed ?? {}, signal);
                                 emitTrace('permission', {
                                     source: 'agent_tool',
@@ -657,7 +730,7 @@ export async function runAgentCore(opts) {
                                     hooks.onToolHeader?.(tc);
                                     const outcome = deniedOutcome(tc.name);
                                     hooks.onToolResult?.(tc, outcome.output, null, null, 1);
-                                    const hint = recordAndHint(tc.name, tc.arguments);
+                                    const hint = recordAndHint(tc.name, tc.arguments, false);
                                     pushToolResult(history, tc, hint ? `${outcome.output}${hint}` : outcome.output, relprune, lifecycle, scheduler, runtimeContextState, false);
                                     traceToolEnd(tc, i, outcome);
                                     i++;
@@ -676,22 +749,28 @@ export async function runAgentCore(opts) {
                                     if (mutationParsed)
                                         diff = readDiffContext(tc, lockedArgs);
                                 },
+                                onRetry: (retry) => traceToolRetry(tc, i, retry),
                             });
+                            addToolUsage(outcome);
+                            opts.onToolOutcome?.(tc.name, parsed ?? {}, outcome);
                             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);
+                            const hint = recordAndHint(tc.name, tc.arguments, outcome.status === 'success');
                             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();
+                            const invalidatedFiles = [...new Set([
+                                    ...(outcome.changedFiles ?? []),
+                                    ...(outcome.staleFiles ?? []),
+                                ])];
+                            if (invalidatedFiles.length > 0) {
+                                for (const changedFile of invalidatedFiles) {
+                                    relprune?.observeMutation(history, changedFile);
+                                    lifecycle?.pushMutation(history, history.length - 1, changedFile);
                                 }
+                                invalidateArtifacts(runtimeContextState, history, invalidatedFiles);
+                                runtimeContextState.lifecycleStats = lifecycle?.stats();
                             }
                             i++;
                         }
@@ -801,6 +880,7 @@ export async function runAgentCore(opts) {
                             completed: false,
                             terminationReason: 'aborted',
                             finalText: null,
+                            usage: turnUsage,
                             validation: latestValidation,
                             changedFiles: mutation.changedFiles.map((item) => item.path),
                         };