mocode-ai 0.7.0 → 0.7.1

package/README.md

@@ -14,7 +14,7 @@ MoCode isn't a chat box with a coat of paint — it's an agent that actually get
 
 - **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. They can explore multiple code areas or directions in parallel and report back only a summary, which the main thread uses to decide what's next.
+- **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.
 - **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.
@@ -105,6 +105,7 @@ Common backend `base_url` values:
 | `COMPACT_THRESHOLD`         | Auto-compaction trigger threshold (fraction of window)                | `0.85`                      |
 | `LLM_STREAM_USAGE`          | Include `stream_options.include_usage` on streaming requests for real usage | `true`                |
 | `AUTO_COMPACT`               | Auto-compaction master switch                                          | `true`                       |
+| `MOCODE_AUTO_VALIDATE`       | Auto-run the lowest-cost discovered validation command after code changes; feed failures back to the agent | `true` |
 | `AUTO_REFLECT`               | Background reflection pass master switch (periodically mines memories from conversations) | `true`   |
 | `REFLECT_EVERY_N`            | Trigger a background reflection every N turns (runs alongside the agent, non-blocking) | `5`      |
 | `ANYSEARCH_API_KEY`         | Web search API key (falls back to anonymous free quota if unset)      | none                         |
@@ -148,7 +149,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); consecutive calls run in parallel automatically, returning only a summary |
+| `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 |
 
 | `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) |
@@ -239,4 +240,4 @@ npm run typecheck   # tsc --noEmit
 
 ## Future extensions
 
-MCP tool integration, a permission confirmation UI, and a real worktree-isolated sub-agent mode. The current version is a streaming, reasoning-visible, rollback-capable terminal coding agent with 20 tools, working-notepad planning, cross-session memory, parallel sub-agents, and an optional desktop pet.
+MCP tool integration, finer-grained capability locks, and a real worktree-isolated sub-agent mode. The current version is a streaming, reasoning-visible, rollback-capable terminal coding agent with 20 tools, working-notepad planning, cross-session memory, capability-aware tool scheduling, serial workspace-sharing sub-agents, and an optional desktop pet.

package/README.zh-CN.md

@@ -14,7 +14,7 @@ mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 
 - **自主多步推进** — 一次对话里连续多步:读代码、改代码、跑测试、根据报错再改……agent 自己决定下一步,中途不用你反复催。遇到卡点会调 `ask_human` 弹面板问你(阻塞到回应)。
 - **只读工具并行执行** — 一轮里连续的只读操作(读文件、grep、glob、codegraph、联网搜索/抓取)自动并发跑,总耗时 ≈ 最慢一个,而不是逐个排队。写文件 / 改文件这类有副作用的操作仍串行,保快照顺序与数据安全。
-- **子 agent 分而治之** — 复杂任务可派生独立子 agent:各自有自己的对话历史(不污染主线),可限定只读工具集和步数上限,并行探查多片代码 / 多个方向,最后只把摘要回灌主线。主线据此决定下一步。
+- **子 agent 分而治之** — 复杂任务可派生独立子 agent:各自有自己的对话历史(不污染主线),可限定工具集和步数上限。共享主工作区期间多个 task 串行执行,避免并发写冲突;每个子任务最后只把摘要回灌主线。
 - **计划 / 执行双模式** — `plan` 模式下只读探查(读代码、查索引、搜索,绝不写盘、不跑命令、不派生子 agent),产出计划;`auto` 模式全量工具放开。agent 还能在两者间自切换——先把陌生代码库摸清,再动手改。
 - **上下文自动压缩** — 接近窗口上限时三层压缩(单条结果裁剪 → 旧工具结果原地微压缩 → 旧对话摘要),长会话也不爆窗口;`/context` 实时显示 token 用量,`/compact` 可手动压缩(能带焦点指令聚焦保留)。
 - **跨会话长期记忆** — agent 能把项目架构、约定、踩过的坑存成长期记忆,下次会话自动加载;后台还会定期从对话里反思挖掘值得记住的事。记忆可增删改、带召回衰减。
@@ -147,7 +147,7 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `ask_human`     | 决策点弹终端问答面板,用户选预设项或自由输入(阻塞至回应)                            |
 | `switch_mode`   | 在 `plan`(只读规划)与 `auto`(全量执行)间切换;agent 可自行调用,先探查再动手       |
 | `drop_context`  | 把历史里无关的旧工具结果替换为存根释放上下文(保 tool_call_id 配对,不动 system 与当前轮;幂等) |
-| `task`          | 派生子 agent 执行独立子任务(独立历史、可受限工具集、可设步数上限);连续多个自动并行,只回摘要      |
+| `task`          | 派生子 agent 执行独立子任务(独立历史、可受限工具集、可设步数上限);共享工作区期间串行执行,只回摘要 |
 
 | `memory_save`   | 存一条跨会话长期记忆(标题进索引,正文按需取)                                  |
 | `memory_search` | 按关键词搜记忆正文,命中即提升召回计数(影响遗忘衰减)                              |
@@ -221,4 +221,4 @@ npm run typecheck   # tsc --noEmit
 
 ## 可后续扩展
 
-MCP 工具集成、权限确认 UI、真·worktree 隔离的子 agent 模式。当前版本已是流式、思考可见、可回滚的终端编码 agent:20 个工具、工作记事本规划、跨会话记忆、并行子 agent、可选桌宠。
+MCP 工具集成、更细粒度的 capability 资源锁、真·worktree 隔离的子 agent 模式。当前版本已是流式、思考可见、可回滚的终端编码 agent:20 个工具、工作记事本规划、跨会话记忆、能力感知工具调度、共享工作区串行子 agent、可选桌宠。

package/dist/agent/core.js

@@ -6,9 +6,9 @@
 // spawn.ts 的 spawnAgent = runAgentCore + 静默 hooks(子 agent)。
 import { readFileSync } from 'node:fs';
 import { chat, estimatePromptTokens, planChatTools, chatTools, } from '../llm/index.js';
-import { executeTool, tools } from '../tools/registry.js';
+import { executeToolOutcome, getToolCapabilities, isFileMutationTool, tools, } from '../tools/registry.js';
 import { checkPermission } from '../permissions/index.js';
-import { getPlanDisabledTools } from '../tools/constants.js';
+import { getPlanDisabledTools, getRuntimeDisabledTools } from '../tools/constants.js';
 import { getAgentMode, setAgentMode } from './mode.js';
 import { maybeCompact, contextState, dropContextFromHistory } from '../session/index.js';
 import { createBudgetScheduler } from '../session/scheduler.js';
@@ -17,9 +17,12 @@ import { createAgeAwareEncodingState, } from '../context/age-aware.js';
 import { createRelevancePruner } from '../context/relevance.js';
 import { isToolResultSuccess } from '../context/utils.js';
 import { config } from '../config/index.js';
+import { t } from '../i18n/index.js';
 import { jailResolve } from '../sandbox/index.js';
 import { createLifecycleEngine } from '../context/lifecycle.js';
 import { getTokenCalibration, updateTokenCalibration, } from '../context/token-calibration.js';
+import { getCurrentTurnMutationState } from '../rollback/index.js';
+import { runAutomaticValidation, } from '../verification/index.js';
 /** Stable per-history age state survives user turns; WeakMap avoids retaining closed sessions. */
 const ageAwareStateByHistory = new WeakMap();
 function ageAwareStateFor(history) {
@@ -57,17 +60,22 @@ function thrashHint(name, args, count) {
         '- edit_file → old_string mismatch; re-read the file to find the exact text\n' +
         '- otherwise → re-read the tool description; the argument shape may be wrong');
 }
-/** 只读工具集:一轮多个时,连续的只读工具成组 Promise.all 并行(无副作用、互不依赖)。 */
-const READ_TOOL_NAMES = new Set([
-    'read_file',
-    'glob',
-    'grep',
-    'codegraph',
-    'web_search',
-    'web_fetch',
-]);
-/** mutation 工具:写盘 + 在 executeTool 内记回滚 before 快照,必须串行保快照序。 */
-const isMutationTool = (name) => name === 'edit_file' || name === 'write_file';
+/** 只有显式声明 parallel 且无需权限确认的工具才可并发；未知扩展保守串行。 */
+function isParallelTool(name) {
+    const tool = tools.find((candidate) => candidate.name === name);
+    return !!tool && (tool.risk ?? 'safe') === 'safe' &&
+        getToolCapabilities(tool).concurrency === 'parallel';
+}
+/** 文件 mutation 由 capability metadata 判定，供 diff、回滚与上下文失效共用。 */
+const isMutationTool = (name) => isFileMutationTool(name);
+function deniedOutcome(name) {
+    return {
+        status: 'denied',
+        code: 'PERMISSION_DENIED',
+        retryable: false,
+        output: `错误:用户拒绝了工具 ${name} 的执行。`,
+    };
+}
 /** mutation 执行前读旧内容供 diff:write_file 取整文件旧内容(不存在→null=新建),
  * edit_file 取 old_string 起始行号(供 diff 显示真实文件行号)。读不到则 diff 退化为相对行号。
  * 非 mutation 或参数非法返 { preWriteOld: null, editStartLine: 1 }。失败不阻断。 */
@@ -116,8 +124,8 @@ function readDiffContext(tc, parsed) {
  *  - lifecycle 也在每个 runAgentCore 实例化一次,登记 grep/glob/codegraph 等 producer
  *    与 read/edit/write 的 consumer 关系;孤立+老化自动 STUB(观察类工具永不到 STUB)。
  *  - 开关关闭时 lifecycle=null 完全跳过。 */
-function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runtimeContextState = contextState) {
-    const succeeded = isToolResultSuccess(output);
+function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runtimeContextState = contextState, succeededOverride) {
+    const succeeded = succeededOverride ?? isToolResultSuccess(output);
     const ageAware = config.contextOptimize ? ageAwareStateFor(history) : null;
     const encodingContext = ageAware?.preparePush(tc, succeeded);
     const msg = {
@@ -158,6 +166,11 @@ export async function runAgentCore(opts) {
     // 本轮计时:从入口到完毕(正常 return / 达上限),供 finally 打 ✻ Worked for 摘要行。
     const t0 = Date.now();
     let done = false; // 正常完毕 / 达上限 true;中断 false(不显摘要)
+    let traceStatus = 'error';
+    let toolCallCount = 0;
+    let latestValidation;
+    let validatedMutationVersion = getCurrentTurnMutationState().version;
+    const validator = opts.validator ?? runAutomaticValidation;
     // 本轮 token 累计:每步 chat() 返回后把 result.usage 累加,供 onDone 摘要行 + AgentRunResult.usage
     // 透传给 repl(显示在底栏模式 chip 右边)。未开启 include_usage 或全失败时为 undefined。
     let turnUsage;
@@ -251,7 +264,14 @@ export async function runAgentCore(opts) {
             // 上一步工具被 abort 杀(run_command/web_fetch 等)→ signal.aborted,直接还原退出,不等 maybeCompact + chat()
             if (signal?.aborted) {
                 abortRestore();
-                return { completed: false, finalText: null };
+                traceStatus = 'aborted';
+                const mutation = getCurrentTurnMutationState();
+                return {
+                    completed: false,
+                    finalText: null,
+                    validation: latestValidation,
+                    changedFiles: mutation.changedFiles.map((item) => item.path),
+                };
             }
             // 本步只计算一次实际工具集合，调度、请求和 usage 校准必须使用完全相同的 schema。
             const activeTools = opts.toolsOverride
@@ -297,7 +317,14 @@ export async function runAgentCore(opts) {
                     (e instanceof Error &&
                         (e.name === 'AbortError' || e.name === 'APIUserAbortError'))) {
                     abortRestore();
-                    return { completed: false, finalText: null };
+                    traceStatus = 'aborted';
+                    const mutation = getCurrentTurnMutationState();
+                    return {
+                        completed: false,
+                        finalText: null,
+                        validation: latestValidation,
+                        changedFiles: mutation.changedFiles.map((item) => item.path),
+                    };
                 }
                 throw e;
             }
@@ -315,6 +342,7 @@ export async function runAgentCore(opts) {
             // lastUsage 已更新:触发状态行 context 用量条重算+重画,运行中不再冻结在轮首。
             onContextUpdate?.();
             if (result.toolCalls.length > 0) {
+                toolCallCount += result.toolCalls.length;
                 hadToolsThisTurn = true;
                 // 流式正文末尾补换行(若 onToolCall 已补则 lastChar='\n',此处 no-op);防 ● 行黏在正文行尾
                 if (mode !== 'idle' && lastChar !== '\n')
@@ -329,104 +357,47 @@ export async function runAgentCore(opts) {
                         function: { name: tc.name, arguments: tc.arguments },
                     })),
                 });
-                // 工具分组执行(保 tool_calls 原顺序):连续的只读工具(READ_TOOL_NAMES)成组并发——先一次性
-                // 渲染全部 header，让摘要在任何同步工具真正执行前立即可见；随后启动全部 executeTool，
-                // 再按原顺序逐个 await + 回灌结果。
-                // mutation(write_file/edit_file)及 run_command/use_skill 各为单步串行屏障——mutation 串行保
-                // recordMutation 调用序 = 回滚快照序(executeTool 内写前记 before 快照,同文件多次写需按序)。
-                // 渲染与 history 回灌一律按原顺序;并发只影响执行时序,tool_call_id 仍按序配对。
-                // executeTool 永不抛错(调度器 try/catch 返字符串),故 await 单个 promise 不会抛(永远 resolve 为字符串)。
+                // 工具分组执行(保 tool_calls 原顺序):连续且显式声明 parallel 的 safe 工具成组并发——先一次性
+                // 渲染全部 header，让摘要在任何同步工具真正执行前立即可见；随后启动全部 executeToolOutcome，
+                // 再按原顺序逐个 await + 回灌结果。其余工具均为串行屏障；resource-locked write 保证
+                // rollback 快照顺序，未知扩展与共享工作区 task 也默认串行。
+                // 渲染与 history 回灌一律按原顺序；并发只影响执行时序，tool_call_id 仍按序配对。
+                // executeToolOutcome 永不抛错，失败通过结构化 status/code 返回。
                 const calls = result.toolCalls;
                 let i = 0;
                 while (i < calls.length) {
-                    if (READ_TOOL_NAMES.has(calls[i].name)) {
+                    const currentCall = calls[i];
+                    if (getRuntimeDisabledTools().has(currentCall.name)) {
+                        hooks.onToolHeader?.(currentCall);
+                        const error = t('task.disabled');
+                        hooks.onToolResult?.(currentCall, error, null, null, 1);
+                        const hint = recordAndHint(currentCall.name, currentCall.arguments);
+                        pushToolResult(history, currentCall, hint ? `${error}${hint}` : error, relprune, lifecycle, scheduler, runtimeContextState, false);
+                        i++;
+                        continue;
+                    }
+                    if (isParallelTool(currentCall.name)) {
                         // 收集连续只读组(≥1),并发执行:先渲染所有 header，再一次性启动所有
                         // (executeTool 调用即开始 I/O)，最后按原顺序逐个 await + 回灌。
                         // 必须先 header 后 execute：grep 等同步快速工具会在 executeTool 返回 Promise 前
                         // 已经完成；若先 started.map，用户只能在工具完成后才看到摘要与其前面的换行。
                         // 异步工具(web_fetch 等)并发跑、总耗时 ≈ 最慢一个;同步工具(glob/grep)map 时已顺序跑完,await 即返。
                         let j = i;
-                        while (j < calls.length && READ_TOOL_NAMES.has(calls[j].name))
+                        while (j < calls.length && isParallelTool(calls[j].name))
                             j++;
                         const batch = calls.slice(i, j);
                         for (const tc of batch)
                             hooks.onToolHeader?.(tc);
                         hooks.onToolStart?.(batch[0].name);
-                        const started = batch.map((tc) => executeTool(tc.name, tc.arguments, signal, { dropContext }));
+                        const started = batch.map((tc) => executeToolOutcome(tc.name, tc.arguments, signal, { dropContext }));
                         for (let k = 0; k < batch.length; k++) {
                             const tc = batch[k];
-                            const output = await started[k];
-                            hooks.onToolResult?.(tc, output, null, null, 1); // 只读工具无 diff
+                            const outcome = await started[k];
+                            const output = outcome.output;
+                            hooks.onToolResult?.(tc, output, null, null, 1); // 并行工具无 diff
                             // Thrashing:history 里附 hint(UI 已用干净 output 渲染,避免屏幕噪声)
                             const hint = recordAndHint(tc.name, tc.arguments);
-                            pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
-                        }
-                        hooks.onToolDone?.();
-                        i = j;
-                    }
-                    else if (calls[i].name === 'task') {
-                        // task 并发组:连续的 task 调用成组并发(子 agent 并行跑,各自独立 history)。
-                        // 一次性启动全部(executeTool 即 spawnAgent,子 agent 开始跑),再并发 await + 渲染。
-                        // task 是长任务,并发 fan-out 总耗时 ≈ 最慢一个子 agent。
-                        // task 与 mutation/run_command 之间串行屏障(task 子 agent 可能有文件改动,不能和 write_file 乱序)。
-                        // 渲染:先批量打印所有 ● 头 + 启 spinner(让用户看到多个 task 同时在跑),再逐个 await 出结果。
-                        // (若像只读组那样「header → await → result」串行,长 task 的第二个 header 要等第一个跑完才出现,
-                        //  视觉上只有一个在跑——与并发事实不符。)
-                        //
-                        // plan 模式防御 backstop(与单步串行分支同语义):schema 已剔除 task,正常不会进这里;
-                        // 防后端幻觉调用——不执行(绝不派生子 agent,子 agent 可能有 mutation,违反只读),直接返错回灌。
-                        if (getAgentMode() === 'plan') {
-                            const tc = calls[i];
-                            hooks.onToolHeader?.(tc);
-                            const err = `错误:计划模式下禁用工具 ${tc.name}(仅读探查,不改动文件 / 不跑命令)`;
-                            hooks.onToolResult?.(tc, err, null, null, 1);
-                            // Thrashing:同上
-                            const hint = recordAndHint(tc.name, tc.arguments);
-                            pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
-                            i++;
-                            continue;
-                        }
-                        let j = i;
-                        while (j < calls.length && calls[j].name === 'task')
-                            j++;
-                        const batch = calls.slice(i, j);
-                        // 权限预检查:逐个 task 弹确认面板(在启动子 agent 之前,体验:先问再执行)。
-                        // 拒绝的 task 直接跳过,不启动子 agent;放行的收集到 allowedBatch。
-                        const allowedBatch = [];
-                        for (const tc of batch) {
-                            const parsed = parseArgs(tc.arguments);
-                            const tool = tools.find((t) => t.name === tc.name);
-                            if (tool) {
-                                const perm = await checkPermission(tool, parsed ?? {}, signal);
-                                if (perm === 'deny') {
-                                    hooks.onToolHeader?.(tc);
-                                    const err = `错误:用户拒绝了工具 ${tc.name} 的执行。`;
-                                    hooks.onToolResult?.(tc, err, null, null, 1);
-                                    const hint = recordAndHint(tc.name, tc.arguments);
-                                    pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
-                                    continue;
-                                }
-                            }
-                            allowedBatch.push(tc);
-                        }
-                        if (allowedBatch.length === 0) {
-                            i = j;
-                            continue; // 全部被拒绝,跳过执行
-                        }
-                        const started = allowedBatch.map((tc) => executeTool(tc.name, tc.arguments, signal, { dropContext }));
-                        // 先批量打印所有头 + 启 spinner(多 task 并发,spinner 只显一个,但 ● 头都打出来)
-                        for (const tc of allowedBatch) {
-                            hooks.onToolHeader?.(tc);
-                        }
-                        hooks.onToolStart?.(allowedBatch[0].name); // spinner:多 task 共用一个「执行 task…」
-                        // 逐个 await 出结果(按 tool_calls 原序,保 tool_call_id 配对);结果到即渲染 ↳
-                        for (let k = 0; k < allowedBatch.length; k++) {
-                            const tc = allowedBatch[k];
-                            const output = await started[k];
-                            hooks.onToolResult?.(tc, output, null, null, 1); // task 结果是摘要,无 diff
-                            // Thrashing:同上
-                            const hint = recordAndHint(tc.name, tc.arguments);
-                            pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
+                            pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
                         }
                         hooks.onToolDone?.();
                         i = j;
@@ -454,10 +425,10 @@ export async function runAgentCore(opts) {
                             const perm = await checkPermission(tool, parsed ?? {}, signal);
                             if (perm === 'deny') {
                                 hooks.onToolHeader?.(tc);
-                                const err = `错误:用户拒绝了工具 ${tc.name} 的执行。`;
-                                hooks.onToolResult?.(tc, err, null, null, 1);
+                                const outcome = deniedOutcome(tc.name);
+                                hooks.onToolResult?.(tc, outcome.output, null, null, 1);
                                 const hint = recordAndHint(tc.name, tc.arguments);
-                                pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
+                                pushToolResult(history, tc, hint ? `${outcome.output}${hint}` : outcome.output, relprune, lifecycle, scheduler, runtimeContextState, false);
                                 i++;
                                 continue;
                             }
@@ -468,14 +439,15 @@ export async function runAgentCore(opts) {
                             : null;
                         const { preWriteOld, editStartLine } = readDiffContext(tc, mutationParsed);
                         hooks.onToolStart?.(tc.name);
-                        const output = await executeTool(tc.name, tc.arguments, signal, { dropContext });
+                        const outcome = await executeToolOutcome(tc.name, tc.arguments, signal, { dropContext });
+                        const output = outcome.output;
                         hooks.onToolDone?.();
                         hooks.onToolResult?.(tc, output, mutationParsed, preWriteOld, editStartLine);
                         // Thrashing:同上(history 附 hint,UI 干净)
                         const hint = recordAndHint(tc.name, tc.arguments);
-                        pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
+                        pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
                         // 只有成功 mutation 才会使旧 read 失效；pruner 与 lifecycle 独立启停。
-                        if (isMutationTool(tc.name) && isToolResultSuccess(output)) {
+                        if (isMutationTool(tc.name) && outcome.status === 'success') {
                             const mp = mutationParsed?.path;
                             if (typeof mp === 'string' && mp) {
                                 relprune?.observeMutation(history, mp);
@@ -509,18 +481,100 @@ export async function runAgentCore(opts) {
                 });
                 continue; // 带着提示再调一次 LLM
             }
-            // 没有工具调用:流式正文即最终回复(已实时打印)
+            // 没有工具调用:候选正文已流式打印。若本轮有新的代码变更，先通过框架验证门；
+            // failed 作为 system observation 风格的 user 消息回灌，不能伪造无配对的 tool 消息。
             if (!gotText)
                 hooks.onNoReply?.();
-            history.push({ role: 'assistant', content: result.content });
+            const candidate = { role: 'assistant', content: result.content };
+            const mutationBeforeValidation = getCurrentTurnMutationState();
+            const shouldValidate = opts.autoValidate === true &&
+                getAgentMode() !== 'plan' &&
+                mutationBeforeValidation.version > validatedMutationVersion;
+            if (shouldValidate) {
+                history.push(candidate);
+                try {
+                    latestValidation = await validator(signal, {
+                        onCommandStart: (command) => hooks.onValidationStart?.(command),
+                    });
+                }
+                catch (error) {
+                    const mutation = getCurrentTurnMutationState();
+                    latestValidation = {
+                        status: signal?.aborted ? 'aborted' : 'failed',
+                        output: `Automatic validation failed to run: ${error instanceof Error ? error.message : String(error)}`,
+                        durationMs: 0,
+                        changedFiles: mutation.changedFiles.map((item) => item.path),
+                        mutationVersion: mutation.version,
+                    };
+                }
+                hooks.onValidationResult?.(latestValidation);
+                validatedMutationVersion = latestValidation.mutationVersion;
+                if (signal?.aborted || latestValidation.status === 'aborted') {
+                    abortRestore();
+                    traceStatus = 'aborted';
+                    const mutation = getCurrentTurnMutationState();
+                    return {
+                        completed: false,
+                        finalText: null,
+                        validation: latestValidation,
+                        changedFiles: mutation.changedFiles.map((item) => item.path),
+                    };
+                }
+                if (latestValidation.status === 'failed') {
+                    history.push({
+                        role: 'user',
+                        content: '[System observation: automatic validation failed]\n' +
+                            `Command: ${latestValidation.command ?? '(internal verifier)'}\n` +
+                            `${latestValidation.output}\n\n` +
+                            'Fix the reported problem, then finish the task. Do not claim success until validation passes.',
+                    });
+                    // 验证及其失败观察均已完整落入 history；下一步中断时可安全保留。
+                    savedHistory = history.slice();
+                    continue;
+                }
+            }
+            else {
+                history.push(candidate);
+            }
+            const finalMutation = getCurrentTurnMutationState();
             done = true;
-            return { completed: true, finalText: result.content, usage: turnUsage };
+            traceStatus = 'completed';
+            return {
+                completed: true,
+                finalText: result.content,
+                usage: turnUsage,
+                validation: latestValidation,
+                changedFiles: finalMutation.changedFiles.map((item) => item.path),
+            };
         }
         hooks.onMaxSteps?.();
         done = true;
-        return { completed: true, finalText: null, usage: turnUsage };
+        traceStatus = 'max_steps';
+        const finalMutation = getCurrentTurnMutationState();
+        return {
+            completed: true,
+            finalText: null,
+            usage: turnUsage,
+            validation: latestValidation,
+            changedFiles: finalMutation.changedFiles.map((item) => item.path),
+        };
     }
     finally {
+        const finalMutation = getCurrentTurnMutationState();
+        try {
+            opts.onTrace?.({
+                ts: new Date().toISOString(),
+                status: traceStatus,
+                durationMs: Date.now() - t0,
+                toolCalls: toolCallCount,
+                changedFiles: finalMutation.changedFiles.map((item) => item.path),
+                usage: turnUsage,
+                validation: latestValidation,
+            });
+        }
+        catch {
+            // Trace is best-effort and must not change the turn result.
+        }
         // 跑完(正常 / 达上限)在回复末尾打耗时摘要行;中断 done=false 不打。
         if (done) {
             hooks.onDone?.(Date.now() - t0, turnUsage);
@@ -528,4 +582,4 @@ export async function runAgentCore(opts) {
     }
 }
 // ── 导出共享辅助(主 agent 的 TUI hooks 实现要用)──────────────────────────
-export { parseArgs, readDiffContext, isMutationTool, READ_TOOL_NAMES };
+export { parseArgs, readDiffContext, isMutationTool, isParallelTool };

package/dist/agent/index.js

@@ -14,6 +14,7 @@ import { runAgentCore, isMutationTool, } from './core.js';
 import { createPetHooks } from '../pet/state.js';
 import { t } from '../i18n/index.js';
 import { isToolErrorOutput } from '../tools/result.js';
+import { appendCurrentSessionTrace } from '../session/index.js';
 /** 当前 turn 的 batch id(runAgent 内闭包变量;一条 turn 一轮 tool batch 结束即清空)。 */
 let currentBatchId = null;
 /** 取 userInput 的首行:字符串直接 split;多模态 parts 找首个 text part 再 split。 */
@@ -187,6 +188,23 @@ onContextUpdate) {
             flushToolBatch();
             layout.contentWrite(`${ui.dim}${t('agent.aborted')}${ui.reset}\n`);
         },
+        onValidationStart: (command) => {
+            flushToolBatch();
+            spinner.start(t('agent.validating', { command }));
+        },
+        onValidationResult: (validation) => {
+            spinner.stop();
+            const color = validation.status === 'passed'
+                ? ui.green
+                : validation.status === 'failed'
+                    ? ui.red
+                    : ui.yellow;
+            const command = validation.command ?? t('agent.validationNoCommand');
+            const detail = validation.status === 'skipped' && validation.skipReason
+                ? `${validation.status}: ${validation.skipReason}`
+                : validation.status;
+            layout.contentWrite(`  ${color}●${ui.reset} ${t('agent.validationResult', { command, status: detail })}\n`);
+        },
         onDone: (elapsedMs, usage) => {
             flushToolBatch();
             const tok = formatTurnTokens(usage);
@@ -210,6 +228,8 @@ onContextUpdate) {
             signal,
             onContextUpdate,
             hooks: combinedHooks,
+            autoValidate: config.autoValidate,
+            onTrace: appendCurrentSessionTrace,
         });
     }
     finally {

package/dist/agent/spawn.js

@@ -12,7 +12,7 @@
 //  - 中断透传:opts.signal(主 agent 的 abort signal)透传给 runAgentCore → chat/executeTool,
 //    主 Ctrl+C 树杀子 agent(chat 流式 abort + run_command/web_fetch 即时取消)。
 import { chatTools } from '../llm/index.js';
-import { config, isMemoryEnabled } from '../config/index.js';
+import { config, isMemoryEnabled, isSubAgentEnabled } from '../config/index.js';
 import { effectiveSystemPrompt } from '../skills/index.js';
 import { buildMemorySection, buildMemoryIndexSection } from '../memory/index.js';
 import { ui } from '../ui/theme.js';
@@ -40,6 +40,13 @@ You are a sub-agent spawned by the main agent to handle an isolated sub-task. Yo
  * 子 agent 跑在主 signal 下,主 abort 即子 abort;子 agent 的 abortRestore 还原子 history + 模式。
  */
 export async function spawnAgent(opts) {
+    if (!isSubAgentEnabled()) {
+        return {
+            summary: null,
+            completed: false,
+            transcript: 'Sub-agent execution is disabled. Enable it with /subagent on.',
+        };
+    }
     const maxSteps = opts.maxSteps ?? config.subAgentMaxSteps ?? 50;
     // 构造子 agent 系统提示:复用主 agent 组装链 + 子 agent 角色后缀 + 自定义后缀。
     // config.systemPrompt 是 getter(每次访问现拼 buildBasePrompt,反映 isMemoryEnabled),
@@ -124,6 +131,7 @@ export async function spawnAgent(opts) {
         maxSteps,
         toolsOverride,
         contextState: localContextState,
+        autoValidate: false, // 子 Agent 共享主轮工作区，由主 Agent 收尾统一验证
     });
     return {
         summary: result.finalText,

package/dist/config/index.js

@@ -358,6 +358,7 @@ export const config = {
     compactThreshold: Number(process.env.COMPACT_THRESHOLD) || 0.85,
     includeUsage: process.env.LLM_STREAM_USAGE !== 'false',
     autoCompact: process.env.AUTO_COMPACT !== 'false',
+    autoValidate: process.env.MOCODE_AUTO_VALIDATE !== 'false',
     contextOptimize: process.env.MOCODE_CONTEXT_OPTIMIZE !== 'false',
     contextRelprune: process.env.MOCODE_CONTEXT_RELPRUNE !== 'false',
     contextLifecycle: process.env.MOCODE_LIFECYCLE !== 'false',
@@ -366,6 +367,7 @@ export const config = {
     memoryEnabled: process.env.MEMORY_ENABLED === 'true',
     reflectEveryN: Number(process.env.REFLECT_EVERY_N) || 5,
     maxSteps: Number(process.env.MAX_STEPS) || 200,
+    subAgentEnabled: process.env.MOCODE_SUBAGENT_ENABLED === 'true',
     subAgentMaxSteps: Number(process.env.SUB_AGENT_MAX_STEPS) || 50,
     sessionDir: path.join(process.cwd(), '.mocode', 'sessions'),
     searchApiKey: process.env.ANYSEARCH_API_KEY,
@@ -379,6 +381,7 @@ export const config = {
     llmKeysFromShell,
     projectSnapshotEnabled: process.env.MOCODE_PROJECT_SNAPSHOT !== 'false',
     permissionEnabled: process.env.MOCODE_PERMISSION !== 'false',
+    permissionNonInteractiveAllow: process.env.MOCODE_PERMISSION_NON_INTERACTIVE_ALLOW === 'true',
     projectSkillEnabled: process.env.MOCODE_PROJECT_SKILL === 'true',
 };
 /**
@@ -407,6 +410,15 @@ export function updateModelConfig(opts) {
         process.env.CONTEXT_WINDOW_TOKENS = String(opts.contextWindowTokens);
     }
 }
+/** 子 Agent 总开关；默认 false，关闭时 task 不进入模型工具表。 */
+export function isSubAgentEnabled() {
+    return config.subAgentEnabled;
+}
+/** 运行时切换子 Agent；工具 schema 刷新与持久化由 REPL 调用方完成。 */
+export function updateSubAgentConfig(enabled) {
+    config.subAgentEnabled = enabled;
+    process.env.MOCODE_SUBAGENT_ENABLED = enabled ? 'true' : 'false';
+}
 /**
  * 记忆子系统总开关:单一来源。/memory_switch、/memory_status、buildSystemPrompt、
  * tools/builtins/index.ts、tools/constants.ts 的 plan-mode 列表都从这里查。