mocode-ai 1.2.0 → 1.2.1

package/dist/agent/core.js

@@ -554,7 +554,7 @@ 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));
+                            const started = batch.map((tc) => executeToolOutcome(tc.name, tc.arguments, signal, { callId: tc.id }));
                             for (let k = 0; k < batch.length; k++) {
                                 const tc = batch[k];
                                 const outcome = await started[k];
@@ -627,6 +627,7 @@ export async function runAgentCore(opts) {
                             const started = entries.map((entry) => entry.denied
                                 ? Promise.resolve(entry.denied)
                                 : executeToolOutcome(entry.tc.name, entry.tc.arguments, signal, {
+                                    callId: entry.tc.id,
                                     onLockAcquired: (lockedArgs) => {
                                         entry.diff = readDiffContext(entry.tc, lockedArgs);
                                     },
@@ -715,6 +716,7 @@ export async function runAgentCore(opts) {
                             let diff = readDiffContext(tc, mutationParsed);
                             hooks.onToolStart?.(tc.name);
                             const outcome = await executeToolOutcome(tc.name, tc.arguments, signal, {
+                                callId: tc.id,
                                 onLockAcquired: (lockedArgs) => {
                                     if (mutationParsed)
                                         diff = readDiffContext(tc, lockedArgs);

package/dist/agent/index.js

@@ -7,6 +7,7 @@ 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';
@@ -17,6 +18,27 @@ import { isToolErrorOutput } from '../tools/result.js';
 import { appendCurrentSessionTraceEvent } from '../session/index.js';
 /** 当前 turn 的 batch id(runAgent 内闭包变量;一条 turn 一轮 tool batch 结束即清空)。 */
 let currentBatchId = null;
+/** 当前活跃的 sub-agent 组容器批 id(同一轮并行派发的多个 sub-agent 合并到这一个顶层摘要行下)。
+ *  null 表示当前没有进行中的子 agent 组。 */
+let subAgentGroupId = null;
+/** sub-agent 组收口后,与后续内容(普通工具/正文)之间欠一条分隔空行。
+ *  由 flushToolBatch / onText 在合适位置补,尾部已空则不再叠。 */
+let subAgentGroupPendingSeparator = false;
+/** 派生子 agent 的工具名。它的调用要独占一批:子 agent 的实时工具明细会挂到这一行下面,
+ *  并行派发多个子 agent 时,每个子 agent 才有自己可归属的摘要行。 */
+const SUB_AGENT_TOOL = 'sub-agent';
+/** 缓冲尾部是否已经是空白行(去掉 ANSI 后无可见字符)。用于避免 sub-agent 分隔空行叠成两行。 */
+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;
+}
 let turnFileChanges = [];
 function lineDelta(oldText, newText) {
     const before = oldText ? oldText.split('\n') : [];
@@ -68,20 +90,82 @@ function firstLineOf(ui) {
  *  重构后改为累积到 BatchRenderer,onToolBatchEnd 时统一打摘要行;
  *  展开/折叠由 BatchRenderer + 鼠标 release 决定,本函数不再直接写屏。 */
 function writeToolHeader(tc) {
-    // 改文件工具是 batch 屏障：先收尾之前的普通工具，确保 mutation 永远独占一批。
-    if (isMutationTool(tc.name))
+    if (tc.name === SUB_AGENT_TOOL) {
+        // sub-agent：同一轮并行派发的多个 sub-agent 合并进同一个「组容器批」——
+        // 顶层只有一个 ● 探索 N ... sub-agent N 摘要行,下面按 └─ sub-agent {...} 逐条
+        // 列出每个子 agent 调用,各自子批(实时工具)更深一层缩进。
+        // 注意：sub-agent header 到来时**不要** flushToolBatch,否则会把正在进行的组容器批收口。
+        if (subAgentGroupId == null) {
+            // 首个 sub-agent 调用前：若前面已经有一个普通工具批在跑，先收口它并补分隔空行，
+            // 避免普通批摘要行与 sub-agent 组摘要行粘在一起。
+            if (currentBatchId)
+                flushToolBatch();
+            // 首个 sub-agent 调用：建组容器批(顶层)。label 缺省=「探索」,entries 累计各 sub-agent 调用。
+            subAgentGroupId = batch.beginBatch(undefined, { groupParent: true });
+            batch.recordCall(subAgentGroupId, tc.name, summarizeToolCall(tc.name, tc.arguments), tc.id);
+            batch.bindCall(tc.id, subAgentGroupId);
+            batch.showLiveBatch(subAgentGroupId, layout);
+            // 立即展开第一组 └─ sub-agent 行(运行态不锚定视口),让子 agent 调用马上可见。
+            batch.expandBatch(subAgentGroupId, layout, true);
+        }
+        else {
+            // 同一轮并行派发的后续 sub-agent：向组追加 entry,实时刷新进度。
+            batch.recordCall(subAgentGroupId, tc.name, summarizeToolCall(tc.name, tc.arguments), tc.id);
+            batch.bindCall(tc.id, subAgentGroupId);
+            // 组已展开:追加新的 └─ sub-agent 行(插到已渲染 entry 之后),并刷新顶层摘要行计数。
+            batch.refreshBatchExpanded(subAgentGroupId, layout);
+            batch.showLiveBatch(subAgentGroupId, layout);
+        }
+        return;
+    }
+    // sub-agent 组还在跑但普通/mutation 工具先来了：收口 sub-agent 组，并补一条分隔空行。
+    if (subAgentGroupId) {
         flushToolBatch();
-    if (!currentBatchId)
-        currentBatchId = batch.beginBatch();
-    batch.recordCall(currentBatchId, tc.name, summarizeToolCall(tc.name, tc.arguments));
-    // 第一条工具开始时立即落摘要；后续调用加入同一 batch，并原地刷新计数。
-    batch.showLiveBatch(currentBatchId, layout);
+    }
+    if (isMutationTool(tc.name)) {
+        // mutation 永远独占一批（diff 要紧跟调用行）。先收口当前普通批。
+        if (currentBatchId)
+            flushToolBatch();
+        const id = batch.beginBatch();
+        currentBatchId = id;
+        batch.bindCall(tc.id, id);
+        batch.recordCall(id, tc.name, summarizeToolCall(tc.name, tc.arguments));
+        batch.showLiveBatch(id, layout);
+    }
+    else {
+        // 普通工具合并到 currentBatchId；同轮并行或连续无正文的工具轮次共享一个摘要行。
+        const id = currentBatchId ??= batch.beginBatch();
+        // 结果按 tool_call id 归位：并行执行时 currentBatchId 会漂移，只按“当前批”回填会漏填，
+        // 摘要行就永远停在 ◇（用户实测：子 agent 跑完主侧菱形没变成实心圆）。
+        batch.bindCall(tc.id, id);
+        batch.recordCall(id, tc.name, summarizeToolCall(tc.name, tc.arguments));
+        // 第一条工具开始时立即落摘要；后续调用加入同一 batch，并原地刷新计数。
+        batch.showLiveBatch(id, layout);
+    }
 }
 /** 渲染工具结果:mutation 成功走 diff 块(行号 + 语法高亮);其余走一行 preview。
  *  同 writeToolHeader,改为累积到 BatchRenderer(只缓存字符串,不写屏)。 */
 function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
-    if (!currentBatchId)
+    // 优先按 tool_call id 反查所属批（并行 / sub-agent 组时 currentBatchId 已不是它）。
+    const batchId = batch.batchIdForCall(tc.id) ?? currentBatchId;
+    if (!batchId)
         return;
+    if (tc.name === SUB_AGENT_TOOL) {
+        // sub-agent 调用只是组容器批的一个 entry：结果回填到对应 entry 即可,
+        // 无需独立批。全部 entry 完成后收口组容器批(落完成态 + 开放点击展开),
+        // 并与后续内容约定一条分隔空行。
+        const preview = summarizeToolResult(tc.name, output);
+        batch.recordResult(batchId, tc.name, preview, null, output, isToolErrorOutput(output), tc.id);
+        if (batch.isBatchComplete(batchId)) {
+            batch.endBatch(batchId, layout);
+            subAgentGroupId = null;
+            subAgentGroupPendingSeparator = true;
+        }
+        else {
+            batch.showLiveBatch(batchId, layout);
+        }
+        return;
+    }
     let diff = null;
     if ((tc.name === 'edit_file' || tc.name === 'write_file') && parsed && !isToolErrorOutput(output)) {
         const oldText = tc.name === 'edit_file' ? String(parsed.old_string ?? '') : preWriteOld;
@@ -102,16 +186,42 @@ function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
         });
     }
     const preview = diff ? '' : summarizeToolResult(tc.name, output);
-    batch.recordResult(currentBatchId, tc.name, preview, diff, output, isToolErrorOutput(output));
-    batch.showLiveBatch(currentBatchId, layout);
+    batch.recordResult(batchId, tc.name, preview, diff, output, isToolErrorOutput(output));
+    batch.showLiveBatch(batchId, layout);
     // mutation 结果（成功 diff 或错误输出）立即可见，并阻止后续普通工具并入这一批。
     if (isMutationTool(tc.name))
-        flushToolBatch(true);
+        finishStandaloneBatch(batchId, true);
+}
+/** 收尾一个独占批（mutation / sub-agent）。按 id 收尾而不是按 currentBatchId：
+ *  同一轮里 mutation 与 sub-agent 混排时，后者的 header 已经把前者切走，
+ *  只认 currentBatchId 会漏掉 diff 展开、把摘要永久留在未完成态。endBatch 幂等。 */
+function finishStandaloneBatch(id, expandSingleEntry) {
+    if (currentBatchId === id)
+        currentBatchId = null;
+    batch.endBatch(id, layout);
+    if (expandSingleEntry)
+        batch.expandSingleEntryFully(id, layout);
+    // mutation 独占批收尾:分隔空行由 flushToolBatch 负责(见 subAgentGroupPendingSeparator);
+    // 不再有 sub-agent 独占批——sub-agent 已合并进组容器批。
 }
 /** 将跨 LLM 工具轮次累计的调用写入内容区；正文开始或整个 turn 收尾时才切批。 */
 function flushToolBatch(expandSingleEntry = false) {
-    if (!currentBatchId)
+    if (!currentBatchId) {
+        // 异常路径:组容器批尚未收口(理论上最后一个 sub-agent 结果时已收口),这里补收口。
+        if (subAgentGroupId) {
+            const id = subAgentGroupId;
+            subAgentGroupId = null;
+            batch.endBatch(id, layout);
+            subAgentGroupPendingSeparator = true;
+        }
+        // 组 / 工具块与后续内容之间补一条分隔空行(尾部已空则不叠,避免空两行)。
+        if (subAgentGroupPendingSeparator) {
+            if (!isLastContentRowBlank())
+                layout.contentWrite('\n');
+            subAgentGroupPendingSeparator = false;
+        }
         return;
+    }
     const id = currentBatchId;
     currentBatchId = null;
     batch.endBatch(id, layout);
@@ -120,6 +230,7 @@ function flushToolBatch(expandSingleEntry = false) {
     // 普通批：endBatch 留了 1 个 hasCurrent 空行，break 一次把它提交为分隔空行。
     // mutation 自动展开：expandSingleEntryFully 自己补 separator (\n)，这里不能再补 \n，
     // 不然 diff 后面就会出现两条空白行。
+    subAgentGroupPendingSeparator = false;
     if (!expandSingleEntry)
         layout.contentWrite('\n');
 }
@@ -144,6 +255,8 @@ onContextUpdate) {
     beginTurn(truncateDisplay(firstLineOf(userInput), 40));
     layout.contentMode(); // 防御性:运行态光标归输入框光标位供 IME 锚定(enterRunningMode 已置,这里兜底)
     currentBatchId = null; // 新 turn 清旧 batch id(防上 turn 残留)
+    subAgentGroupId = null;
+    subAgentGroupPendingSeparator = false;
     turnFileChanges = [];
     // spinner:状态行最前面转圈(思考中 / 生成 / 执行 工具时,状态栏 lead 位显帧 + 文字)。
     // 经 setStatus 注入状态行(spinnerFrame + statusText),composeStatus 把帧 + 文字放 lead 位;
@@ -164,9 +277,11 @@ onContextUpdate) {
         onText: (s) => {
             // 纯空白 chunk 在视觉上不是正文：既不切 batch，也不写入 markdown 缓冲。
             // 部分兼容后端会在连续工具轮次间流出 " " / "\n"，若据此切批会漏掉首个工具。
-            if (currentBatchId && s.trim().length === 0)
+            // sub-agent 独占批不占 currentBatchId，但同样处在“工具块刚结束”的边界上。
+            const inToolBlock = currentBatchId !== null || subAgentGroupId !== null || subAgentGroupPendingSeparator;
+            if (inToolBlock && s.trim().length === 0)
                 return;
-            const followsToolBatch = currentBatchId !== null;
+            const followsToolBatch = inToolBlock;
             // batch 收尾已经统一留了一条空白行。部分后端会把下一段正文以 \n / \n\n
             // 开头发来；去掉这些“边界换行”，避免与 UI 分隔叠成两条空白行。
             const visible = followsToolBatch ? s.replace(/^(?:[ \t]*\r?\n)+/, '') : s;

package/dist/agent/spawn.js

@@ -1,9 +1,10 @@
-// 子 agent 封装:runAgentCore + 静默 hooks。独立 history / 可受限工具子集 / 低步数上限。
+// 子 agent 封装:runAgentCore + (TUI 激活时)实时渲染 hooks。独立 history / 可受限工具子集 / 低步数上限。
 // 供 task 工具(主 agent 派生子任务)调用——子 agent 的最终摘要回灌主 history。
 //
 // 与主 agent 的区别:
-//  - 不写主屏(layout.contentWrite):中间过程(流式正文 / 工具头 / diff)缓冲到内部字符串,
-//    结束返回给 task 工具(task 把它当 tool 结果回灌主 history,主 agent 据此继续)。
+//  - 主屏渲染可选:全屏 TUI 激活时(layout.isTuiActive()),把子 agent 内部工具调用实时写入
+//    主内容区并复用 batch 折叠机制(运行态逐条展开,执行完自动折叠回单行摘要,鼠标可点开查看);
+//    TUI 未激活(host 嵌入 / 非 TTY)时保持纯静默——中间过程只缓冲进 transcript,不写主屏。
 //  - 独立 history:不共享主对话,避免子任务的工具噪声污染主上下文。
 //  - 紧凑系统提示:不复制主 agent 的 memory/skills/项目快照；由 context 传入已知事实。
 //  - 工具子集:写任务默认继承主 Agent 工具（仅禁止递归 task）；只读模式按安全语义移除写工具。
@@ -15,8 +16,13 @@ import { chatTools } from '../llm/index.js';
 import { buildMocodeCorePrompt, config, isSubAgentEnabled } from '../config/index.js';
 import { effectiveSystemPrompt } from '../skills/index.js';
 import { ui } from '../ui/theme.js';
+import * as layout from '../ui/layout.js';
+import { isTuiActive } from '../ui/layout.js';
+import * as batch from '../ui/batch.js';
+import { isToolErrorOutput } from '../tools/result.js';
 import { runAgentCore } from './core.js';
 import { summarizeToolCall, summarizeToolResult, truncateDisplay } from '../ui/render.js';
+import { t } from '../i18n/index.js';
 import { createContextState } from '../session/compact.js';
 import { inOverlay, mergeSubAgentChangeSet } from '../agents/coordinator.js';
 /** 子 agent 系统提示后缀:角色与约束。 */
@@ -84,6 +90,61 @@ export async function spawnAgent(opts) {
         buf.push(s);
         transcript += s;
     };
+    // 主屏实时渲染(子 agent 透明化):TUI 激活时把子 agent 内部步骤实时写入主内容区,
+    // 复用 batch 折叠机制(mouse 点击摘要行可展开/收起)。TUI 未激活(host/非 TTY)时
+    // 保持纯静默——只缓冲 transcript,不写屏,兼容嵌入宿主。
+    const live = isTuiActive();
+    let liveBatchId = null;
+    const liveLayout = () => ({
+        contentWrite: (s) => layout.contentWrite(s),
+        contentReplaceLine: (absIdx, line) => layout.contentReplaceLine(absIdx, line),
+        contentInsertAfter: (after, lines, keepViewport) => layout.contentInsertAfter(after, lines, keepViewport),
+        contentDeleteFrom: (startIdx, n) => layout.contentDeleteFrom(startIdx, n),
+        totalRows: () => layout.totalRows(),
+        repaintViewport: () => layout.repaintViewport(),
+        isScrolled: () => layout.isScrolled(),
+    });
+    /** 本批是否挂在主侧调用行下(挂上了就由主侧负责分隔空行,自己不能往 buffer 末尾追加)。 */
+    let nested = false;
+    const ensureLiveBatch = () => {
+        if (!live || liveBatchId)
+            return;
+        // 主侧 sub-agent 组容器批 = 父批;本子 agent 的工具批挂在其下并更深一层缩进,
+        // 与同组其它子 agent 各归各的 └─ sub-agent 行(通过 groupChildIndex 定锚点)。
+        const parentId = batch.batchIdForCall(opts.callId) ?? undefined;
+        nested = parentId != null;
+        const childIndex = parentId ? batch.getGroupChildIndex(opts.callId) : undefined;
+        liveBatchId = batch.beginBatch(t('subagent.running'), {
+            parentId,
+            indent: parentId ? '        ' : undefined,
+            groupChildIndex: childIndex,
+            running: true,
+        });
+        batch.showLiveBatch(liveBatchId, liveLayout());
+        // 默认折叠:只显示一行「子 Agent 运行中 · glob X  read_file Y」,不展开明细;
+        // 用户点击摘要行后才展开看具体工具调用。
+    };
+    const finishLiveBatch = (status) => {
+        if (!live || !liveBatchId)
+            return;
+        const id = liveBatchId;
+        liveBatchId = null;
+        if (status)
+            batch.setBatchLabel(id, status === 'complete'
+                ? t('subagent.complete')
+                : status === 'failed' ? t('subagent.failed') : t('subagent.running'));
+        // 收尾:清除运行态标志,摘要行图标从「运行中 ◐」切回完成态 ●。
+        batch.setBatchRunning(id, false);
+        batch.endBatch(id, liveLayout());
+        // 子 agent 完成后自动折叠:endBatch 登记了点击,但默认保持展开态;
+        // 这里显式折叠回单行摘要,让执行完的批自动收起(用户可再点开)。
+        if (status === 'complete' && batch.isExpanded(id))
+            batch.toggleBatch(id, liveLayout());
+        // 嵌套批的分隔空行由主侧 flushToolBatch 统一补;这里再写会往 buffer 末尾插孤儿空行
+        // (并行子 agent 各写一条,块尾堆出空白)。
+        if (!nested)
+            layout.contentWrite('\n');
+    };
     let lastChar = '';
     const hooks = {
         onText: (s) => {
@@ -101,11 +162,24 @@ export async function spawnAgent(opts) {
         onToolHeader: (tc) => {
             const summary = summarizeToolCall(tc.name, tc.arguments);
             writeBuf(`  ● ${tc.name}  ${summary}\n`);
+            // 实时写入主内容区:子 agent 的每次工具调用累计到摘要行计数。
+            ensureLiveBatch();
+            if (liveBatchId) {
+                batch.recordCall(liveBatchId, tc.name, summary);
+                // 默认折叠,只刷新摘要行计数(glob/read_file 数量),不展开明细列表。
+                batch.showLiveBatch(liveBatchId, liveLayout());
+            }
         },
         onToolResult: (tc, output) => {
             const preview = summarizeToolResult(tc.name, output);
             if (preview)
                 writeBuf(`  ↳ ${preview}\n`);
+            if (liveBatchId) {
+                // 子 agent 批无 diff(写任务走 overlay,最终由主 agent 合并);空 preview 用占位
+                // 标记 entry 已完成,避免折叠后摘要仍显示"运行中"。
+                batch.recordResult(liveBatchId, tc.name, preview || t('toolSummary.noOutput'), null, output, isToolErrorOutput(output));
+                batch.showLiveBatch(liveBatchId, liveLayout());
+            }
         },
         onTextEnd: () => {
             if (lastChar && lastChar !== '\n') {
@@ -113,16 +187,30 @@ export async function spawnAgent(opts) {
                 lastChar = '\n';
             }
         },
-        onToolBatchEnd: () => writeBuf('\n'),
+        onToolBatchEnd: () => {
+            writeBuf('\n');
+            // 子 agent 一轮工具调用结束:仍在运行(可能还有后续轮次),仅推进实时摘要,
+            // 不折叠——等 onDone 整体完成才自动收起。
+            if (liveBatchId)
+                batch.showLiveBatch(liveBatchId, liveLayout());
+        },
         onNoReply: () => writeBuf(`${ui.dim}(无回复)${ui.reset}\n`),
-        onMaxSteps: () => writeBuf(`  ● 达到最大步数(${maxSteps}),子 agent 停止。\n`),
+        onMaxSteps: () => {
+            writeBuf(`  ● 达到最大步数(${maxSteps}),子 agent 停止。\n`);
+            finishLiveBatch('failed');
+        },
         onDone: (elapsedMs, usage) => {
             const tok = usage && usage.totalTokens
                 ? `  · ${usage.totalTokens} tokens${usage.cachedTokens ? ` ↻${usage.cachedTokens} cached` : ''}`
                 : '';
             writeBuf(`  ✻ 子 agent 耗时 ${(elapsedMs / 1000).toFixed(1)}s${tok}\n`);
+            finishLiveBatch('complete');
+        },
+        onAbort: () => {
+            // 中断:子 agent 未完成,收尾批(不折叠——用户可能想看中断前做了什么)。
+            finishLiveBatch('aborted');
         },
-        // onStepStart / onChatDone / onToolStart / onToolDone / onAbort:子 agent 静默,无需 spinner / 中断渲染。
+        // onStepStart / onChatDone / onToolStart / onToolDone:子 agent 静默,无需 spinner 渲染。
         // abort 还原(history 还原 + 模式还原)由 core 的 abortRestore 处理,hooks 只管展示。
     };
     // 每个子 agent 独享统计/预算状态。不能保存再恢复模块级单例：多个 task 并发时

package/dist/config/index.js

@@ -84,7 +84,7 @@ const DEFAULT_VOICE = `## Voice
 - Give technical recommendations with brief trade-off reasoning when choices exist.
 - Focus on useful information. Avoid unnecessary greetings, apologies, repetition, or filler.
 - Match the user's style and language while staying task-focused.
-- For long operations, briefly state the plan and expected result. Avoid step-by-step narration.
+- Work quietly: jump straight into tool calls without announcing them; reserve visible text for the final answer and truly important mid-task findings. No step-by-step narration.
 - State assumptions and ask when uncertain. Do not guess.`;
 /** 解析用户自定义声音:persona.md 文件优先(项目级 > 全局),其次 env MOCODE_PERSONA。无则返回 ''。 */
 function readPersonaFile() {
@@ -287,7 +287,7 @@ ${buildCodegraphSection()}
 ${buildWorkDisciplineSection(inferModelFamily(config.model))}
 
 ## Tool policy
-- During tool-calling turns, stay silent unless something important enough must reach the user — otherwise just call the tool and let it run.
+- Silent Execution: invoke tools directly without preamble. Output visible text ONLY for the final answer and critical mid-task findings. Strictly no step-by-step narration (no "let me…", "让我先…", "now checking…" between calls).
 - Go directly to a known path or symbol; use discovery tools only when the location is unknown.
 - Edit against a FRESH read: before any edit_file/write_file, call read_file on the exact path and copy both its latest hash and the exact target text. Never reconstruct old_string from a grep/summary/diff — those lose whitespace and indentation and cause edit failures.
 - A read_file hash from before a compaction, session resume, edit conflict, or external change is STALE and will be rejected — re-read rather than reuse an old hash.

package/dist/i18n/index.js

@@ -209,6 +209,9 @@ const zhCN = {
     'task.interrupted': '子 agent 被中断，未完成。',
     'task.noSummary': '子 agent 完成但未返回文本摘要（可能只调了工具或达到步数上限）。',
     'task.summaryTruncated': '…（子 agent 摘要已截断 {count} 字符）',
+    'subagent.running': '子 Agent 运行中',
+    'subagent.complete': '子 Agent 完成',
+    'subagent.failed': '子 Agent 失败',
     'subagent.status': '子 Agent：{state}',
     'subagent.stateOn': '开启',
     'subagent.stateOff': '关闭',
@@ -461,6 +464,9 @@ const en = {
     'task.interrupted': 'The sub-agent was interrupted before completion.',
     'task.noSummary': 'The sub-agent completed without a text summary (it may only have used tools or reached its step limit).',
     'task.summaryTruncated': '…(sub-agent summary truncated by {count} characters)',
+    'subagent.running': 'Sub-agent running',
+    'subagent.complete': 'Sub-agent complete',
+    'subagent.failed': 'Sub-agent failed',
     'subagent.status': 'Sub-agent: {state}',
     'subagent.stateOn': 'enabled',
     'subagent.stateOff': 'disabled',

package/dist/repl/index.js

@@ -276,9 +276,12 @@ function readPlanStatusFromNotes() {
         if (!title)
             return null;
         const total = (section.match(/^\s*-\s*\[[ xX]\]\s*\d+\./gm) || []).length;
-        const done = (section.match(/^\s*-\s*\[[xX]\]\s*\d+\./gm) || []).length;
-        const current = section.match(/^\s*-\s*\[ \]\s*\d+\.\s*(.+)$/m)?.[1].trim();
-        const summary = `plan: ${title} (${done}/${total})`;
+        const currentMatch = section.match(/^\s*-\s*\[ \]\s*(\d+)\.\s*(.+)$/m);
+        const current = currentMatch?.[2].trim();
+        // 括号进度 = 「当前执行到的步骤序号/总数」(执行第 1 步显示 1/3),与 `▸ 当前步` 后缀自洽;
+        // 旧语义 done/total 会永远慢一拍(执行第 2 步显示 1/3)。全勾选时显示 total/total(通常已自动结算为 Done,chip 消失)。
+        const activeNo = currentMatch ? Number(currentMatch[1]) : total;
+        const summary = `plan: ${title} (${activeNo}/${total})`;
         // mtime 让“相同内容被重写为一项新计划”也能重新出现，而不被旧轮次误抑制。
         const fingerprint = `${sessionId}\0${fs.statSync(p).mtimeMs}\0${section}`;
         return { fingerprint, summary: current ? `${summary} ▸ ${current}` : summary };

package/dist/tools/builtins/edit-file.js

@@ -41,7 +41,12 @@ expected_hash is required (sha256 from read_file artifact header) and must match
             line_end: { type: 'integer', description: 'Line-range mode: end line (1-based, inclusive). Mutually exclusive with old_string.' },
             expected_hash: { type: 'string', description: 'sha256 hash from the latest read_file artifact header (sha256:<64 hex>).' },
         },
-        required: ['path', 'new_string', 'expected_hash'],
+        // 注意:expected_hash 故意不放进 schema 的 required。
+        // 原因:缺失时若被 AJV 在 schema 层拦下,只会得到泛化的
+        // "缺少必填字段 expected_hash",模型据此只补该字段、反而丢掉 path,形成乒乓失败。
+        // 改为只在 execute 内校验(见下方 normalizeContentHash 检查),缺失时返回富指导信息,
+        // 明确要求先 read_file 并复制最新 hash——与 write_file 的设计保持一致。
+        required: ['path', 'new_string'],
     },
     async execute(args, ctx) {
         const file = String(args.path);

package/dist/tools/builtins/task.js

@@ -63,7 +63,8 @@ export const subAgentTool = {
         const writeSet = Array.isArray(args.writeSet) ? args.writeSet.map(String) : undefined;
         const context = typeof args.context === 'string' ? args.context.slice(0, 4000) : undefined;
         // 透传主 agent 的 abort signal:主 Ctrl+C 树杀子 agent(chat abort + 工具 abort)。
-        const result = await spawnAgent({ prompt, tools, maxSteps, signal: ctx?.signal, mode, writeSet, context });
+        // callId 透传:子 agent 实时渲染据此挂靠主侧对应批次(并行派发时各行归位)。
+        const result = await spawnAgent({ prompt, tools, maxSteps, signal: ctx?.signal, mode, writeSet, context, callId: ctx?.callId });
         let output;
         if (!result.completed) {
             output = `[SubAgentResult status=${result.status} tokens=${result.usage.totalTokens} readSet=${JSON.stringify(result.readSet)} changeSet=${result.changeSet?.id ?? 'none'} verification=not-run]\n${result.summary ?? t('task.interrupted')}`;

package/dist/tools/registry.js

@@ -153,7 +153,7 @@ async function executeToolOnce(tool, args, signal, opts) {
                 : null;
             let raw;
             try {
-                raw = await tool.execute(args, { signal });
+                raw = await tool.execute(args, { signal, callId: opts?.callId });
             }
             finally {
                 if (pathCapture)

package/dist/tools/validation.js

@@ -37,10 +37,15 @@ function compile(schema) {
     cache.set(schema, result);
     return result;
 }
-function formatErrors(errors) {
+function formatErrors(errors, schema) {
     if (!errors?.length)
         return '参数不符合 JSON Schema';
-    return errors.slice(0, 5).map((error) => {
+    // 收集所有「缺少必填字段」涉及的属性名,用于在文末一次性列出完整必填签名,
+    // 避免模型只补齐报错点名的一个字段、下一次又把别的字段弄丢(乒乓失败)。
+    const missing = errors
+        .filter((e) => e.keyword === 'required')
+        .map((e) => String(e.params.missingProperty ?? '?'));
+    const body = errors.slice(0, 5).map((error) => {
         const location = error.instancePath || '/';
         if (error.keyword === 'required') {
             const property = String(error.params.missingProperty ?? '?');
@@ -52,6 +57,16 @@ function formatErrors(errors) {
         }
         return `${location} ${error.message ?? error.keyword}`;
     }).join('; ');
+    let hint = '';
+    const required = schema?.required ?? [];
+    const properties = schema?.properties ?? {};
+    if (missing.length > 0 && required.length > 0) {
+        const lines = required
+            .map((k) => `- ${k}: ${properties[k]?.description ?? '(无描述)'}`)
+            .join('\n');
+        hint = `。请一次性补齐全部必填参数,不要在重试时只补其中一部分:\n${lines}`;
+    }
+    return body + hint;
 }
 /** Validate after tool-local normalization; AJV itself never coerces or mutates arguments. */
 export function validateToolArguments(tool, args) {
@@ -85,6 +100,6 @@ export function validateToolArguments(tool, args) {
     return {
         valid: false,
         code: 'INVALID_ARGUMENTS',
-        message: formatErrors(compiled.validate.errors),
+        message: formatErrors(compiled.validate.errors, tool.parameters),
     };
 }

package/dist/ui/batch.js

@@ -14,6 +14,12 @@
 import { ui } from './theme.js';
 import { t } from '../i18n/index.js';
 import { truncateAnsi } from './render.js';
+/** entry 是否已拿到结果。历史回放构造的 entry 无 done 字段,退化按内容判定。 */
+function isEntryDone(e) {
+    return e.done === true || !!e.resultSummary || !!e.diffBlock || !!e.failed;
+}
+/** 子 agent 运行中的专属图标:与完成态的实心 ● 区分,也区别于父层「探索」运行态的 ◇。 */
+const RUNNING_GLYPH = '◐';
 const batches = new Map();
 /** 绝对行索引 → 所属 batch id(仅记录 summary 行;用于鼠标点击反查)。
  *  buffer 行数变化时本表可能漂移——但只在 insertAfter/deleteFrom 后由本模块同步更新,
@@ -23,6 +29,13 @@ const absLineToBatchId = new Map();
 const absLineToEntry = new Map();
 /** 已展开第一层工具列表的 batch id。 */
 const expandedBatches = new Set();
+/** tool_call id → 所属 batch(主侧每次 onToolHeader 都登记)。
+ *  结果按 id 归位(并行时 currentBatchId 会漂移,按 id 查才不串批);
+ *  子 agent 建批时据此反查父批,把子批摘要行插到父批正下方。reset() 统一清理。 */
+const callToBatch = new Map();
+/** sub-agent 组:tool_call id → 在组容器批 entries 中的序号。
+ *  spawn.ts 建子批时据此把子批摘要行插到正确的 └─ sub-agent 行下方。reset() 统一清理。 */
+const groupChildIndexByCall = new Map();
 /** 展开时完整输出的最大行数;超出截断,避免巨型输出撑爆 viewport。 */
 const MAX_EXPAND_LINES = 200;
 /** 自洽行允许的最大显示宽(= 终端 cols)。buffer 行超 cols 会被终端 auto-wrap,
@@ -59,57 +72,125 @@ export function reset() {
     absLineToBatchId.clear();
     absLineToEntry.clear();
     expandedBatches.clear();
+    callToBatch.clear();
+    groupChildIndexByCall.clear();
 }
-/** 新建一个 batch(在 agent 拿到第一条 onToolHeader 时调)。返回 id。 */
-export function beginBatch() {
+/** 新建一个 batch(在 agent 拿到第一条 onToolHeader 时调)。返回 id。
+ *  label 可选:自定义摘要行标签(子 agent 批用),缺省按完成态取 agent.tools*。
+ *  opts.indent/parentId:子批嵌套渲染(摘要行缩进 + 插到父批下方)。
+ *  opts.groupParent:组容器批(并行 sub-agent 共享顶层摘要行)。
+ *  opts.groupChildIndex:本批作为组子批时在父 entries 中的序号(插入锚点用)。 */
+export function beginBatch(label, opts) {
     const id = `b${++_idCounter}`;
-    batches.set(id, { id, summaryAbsIdx: -1, entries: [], expandedEntries: new Set(), startedAt: Date.now() });
+    batches.set(id, {
+        id,
+        summaryAbsIdx: -1,
+        entries: [],
+        expandedEntries: new Set(),
+        renderedCount: 0,
+        startedAt: Date.now(),
+        label,
+        indent: opts?.indent,
+        parentId: opts?.parentId && batches.has(opts.parentId) ? opts.parentId : undefined,
+        groupParent: opts?.groupParent ?? false,
+        groupChildIndex: opts?.groupChildIndex,
+        running: opts?.running ?? false,
+    });
     return id;
 }
-/** 记一条工具调用(在 onToolHeader 时调,与 setEntryResult 配对;entries 顺序 = agent 调用顺序)。 */
-export function recordCall(id, name, callSummary) {
+/** 登记 tool_call id → 所属 batch。结果回填按 id 归位(并行时 currentBatchId 会漂移),
+ *  子 agent 也据此反查父批。 */
+export function bindCall(callId, batchId) {
+    if (callId)
+        callToBatch.set(callId, batchId);
+}
+/** tool_call id → 所属 batch id;未登记返 null。 */
+export function batchIdForCall(callId) {
+    if (!callId)
+        return null;
+    const id = callToBatch.get(callId);
+    return id && batches.has(id) ? id : null;
+}
+/** 记一条工具调用(在 onToolHeader 时调,与 setEntryResult 配对;entries 顺序 = agent 调用顺序)。
+ *  callId 可选:组容器批据此把 sub-agent 调用归到 entries 的固定序号(供子批插入锚点反查)。 */
+export function recordCall(id, name, callSummary, callId) {
     const b = batches.get(id);
     if (!b)
         return;
     // 已完成的累计探索后又追加工具：恢复进行中，待新结果返回再完成。
     b.finishedAt = undefined;
     b.entries.push({ name, callSummary, resultSummary: '', diffBlock: null });
+    if (callId && b.groupParent)
+        groupChildIndexByCall.set(callId, b.entries.length - 1);
+}
+/** 查询某 sub-agent 调用在所属组容器批 entries 中的序号(供 spawn.ts 建子批时定锚点)。 */
+export function getGroupChildIndex(callId) {
+    if (!callId)
+        return 0;
+    const v = groupChildIndexByCall.get(callId);
+    return v == null ? 0 : v;
+}
+/** 批是否所有 entry 都已拿到结果(空批视为完成)。 */
+export function isBatchComplete(id) {
+    const b = batches.get(id);
+    if (!b)
+        return false;
+    return b.entries.length > 0 && b.entries.every(isEntryDone);
 }
 /** 记一条工具结果(diff 块或单行 preview);agent 在 onToolResult 时调,匹配最后一条未填的 entry。
- *  fullOutput:工具原始完整输出(纯文本),展开时显示;mutation 工具的 diff 块已自含无需传。 */
-export function recordResult(id, name, resultSummary, diffBlock, fullOutput, failed = false) {
+ *  fullOutput:工具原始完整输出(纯文本),展开时显示;mutation 工具的 diff 块已自含无需传。
+ *  callId:组容器批用,直接把结果填到对应 entry(避免多个 sub-agent 同名时反向匹配错位)。 */
+export function recordResult(id, name, resultSummary, diffBlock, fullOutput, failed = false, callId) {
     const b = batches.get(id);
     if (!b || b.entries.length === 0)
         return;
+    // 组容器批:优先按 callId 定位 entry,防止多个同名 sub-agent 结果互相填错位置。
+    if (callId && b.groupParent) {
+        const idx = groupChildIndexByCall.get(callId);
+        if (idx != null && idx < b.entries.length && !isEntryDone(b.entries[idx])) {
+            const e = b.entries[idx];
+            e.resultSummary = resultSummary;
+            e.diffBlock = diffBlock;
+            e.fullOutput = fullOutput;
+            e.failed = failed;
+            e.done = true;
+            if (b.entries.every(isEntryDone))
+                b.finishedAt = Date.now();
+            return;
+        }
+    }
     // 反向找最后一条同名的 entry 填结果;同名工具一批多次调用时正向遍历更安全——用 lastIndexOf 同名回退
     for (let i = b.entries.length - 1; i >= 0; i--) {
-        if (b.entries[i].name === name && !b.entries[i].resultSummary) {
+        if (b.entries[i].name === name && !isEntryDone(b.entries[i])) {
             b.entries[i].resultSummary = resultSummary;
             b.entries[i].diffBlock = diffBlock;
             b.entries[i].fullOutput = fullOutput;
             b.entries[i].failed = failed;
-            if (b.entries.every((e) => e.resultSummary || e.diffBlock || e.failed))
+            b.entries[i].done = true;
+            if (b.entries.every(isEntryDone))
                 b.finishedAt = Date.now();
             return;
         }
     }
     // 兜底:无匹配则填最后一条
     const last = b.entries[b.entries.length - 1];
-    if (!last.resultSummary) {
+    if (!isEntryDone(last)) {
         last.resultSummary = resultSummary;
         last.diffBlock = diffBlock;
         last.fullOutput = fullOutput;
         last.failed = failed;
-        if (b.entries.every((e) => e.resultSummary || e.diffBlock || e.failed))
+        last.done = true;
+        if (b.entries.every(isEntryDone))
             b.finishedAt = Date.now();
     }
 }
 // ── 摘要行文本生成 ──
 /** 把 entry 列表压缩成一行摘要。 */
 function buildSummaryLine(record, live = false) {
+    const prefix = record.indent ?? '';
     const entries = record.entries;
     if (entries.length === 0) {
-        return `  ${ui.dim}│${ui.reset} ${ui.bold}${ui.accent}◇${ui.reset} ${ui.dim}No tools${ui.reset}`;
+        return `${prefix}  ${ui.dim}│${ui.reset} ${ui.bold}${ui.accent}◇${ui.reset} ${ui.dim}No tools${ui.reset}`;
     }
     // N>1:同类合并 "read_file 3, glob 1, grep 1"
     const counts = new Map();
@@ -118,15 +199,31 @@ function buildSummaryLine(record, live = false) {
     const parts = [];
     for (const [n, c] of counts)
         parts.push(`${n} ${c}`);
-    const completed = entries.filter((e) => e.resultSummary || e.diffBlock || e.failed).length;
+    const completed = entries.filter(isEntryDone).length;
     const failedCount = entries.filter((e) => e.failed).length;
     // 工具本身完成就立即显示完成态，不等待整轮正文流完/onDone。
     // 单项失败不代表整批失败：执行中优先展示进度；完成后区分部分失败与全部失败。
     const finished = completed >= entries.length;
     const allFailed = finished && failedCount === entries.length;
     const partiallyFailed = finished && failedCount > 0 && !allFailed;
-    const symbol = !finished ? '◇' : allFailed ? '×' : partiallyFailed ? '!' : '●';
-    const color = !finished ? ui.accent : allFailed ? ui.red : partiallyFailed ? ui.yellow : ui.green;
+    const symbol = record.running
+        ? RUNNING_GLYPH
+        : !finished
+            ? '◇'
+            : allFailed
+                ? '×'
+                : partiallyFailed
+                    ? '!'
+                    : '●';
+    const color = record.running
+        ? ui.accent
+        : !finished
+            ? ui.accent
+            : allFailed
+                ? ui.red
+                : partiallyFailed
+                    ? ui.yellow
+                    : ui.green;
     const label = !finished
         ? t('agent.toolsRunning')
         : allFailed
@@ -137,7 +234,8 @@ function buildSummaryLine(record, live = false) {
     const elapsed = record.finishedAt
         ? `  ${elapsedMs < 100 ? '<0.1s' : `${(elapsedMs / 1000).toFixed(1)}s`}`
         : '';
-    return `  ${ui.bold}${color}${symbol}${ui.reset} ${label}${progress}${elapsed}  ${ui.dim}${parts.join('  ')}${ui.reset}`;
+    const displayLabel = record.label ?? label;
+    return `${prefix}  ${ui.bold}${color}${symbol}${ui.reset} ${displayLabel}${progress}${elapsed}  ${ui.dim}${parts.join('  ')}${ui.reset}`;
 }
 // ── 展开/折叠 ──
 /** 把 batch 的详情行展开成自洽行数组(供 layout.contentInsertAfter 走 mid-buffer 插入)。
@@ -177,13 +275,13 @@ function buildEntryDetailLines(e, indent = '      ') {
     }
     return lines;
 }
-/** 第一层只展示有哪些调用及其简短结果，不展开完整输出。 */
-function buildExpandedLines(entries) {
+/** 第一层只展示有哪些调用及其简短结果，不展开完整输出。extraIndent 供子批嵌套加深缩进。 */
+function buildExpandedLines(entries, extraIndent = '') {
     return entries.map((e, index) => {
         const result = e.resultSummary ? `  ${ui.gray}↳ ${e.resultSummary}${ui.reset}` : '';
         const branch = index === entries.length - 1 ? '└─' : '├─';
         const failure = e.failed ? `${ui.red}×${ui.reset} ` : '';
-        return sanitizeRow(`    ${ui.dim}${branch}${ui.reset} ${failure}${ui.accent}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}${result}`);
+        return sanitizeRow(`${extraIndent}    ${ui.dim}${branch}${ui.reset} ${failure}${ui.accent}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}${result}`);
     });
 }
 function entryDetailIndent(entries, index) {
@@ -201,6 +299,22 @@ export function endBatch(id, layout) {
         absLineToBatchId.set(b.summaryAbsIdx, b.id);
         return;
     }
+    // 子批尚未落盘(组容器折叠期间被隐藏 / 折叠后才新建)。绝不能 contentWrite 到 buffer 末尾:
+    // 那会在正文区留下一条游离的子 agent 摘要行,父批再展开时就变成「多出来的第三条」。
+    if (b.parentId) {
+        const parent = batches.get(b.parentId);
+        if (parent?.groupParent) {
+            // 父批折叠中:不渲染,等 expand() 统一恢复(那时会用最新状态重建摘要行)。
+            if (!expandedBatches.has(parent.id) || parent.summaryAbsIdx < 0)
+                return;
+            // 父批已展开:插到自己的 └─ sub-agent 行下方。
+            const anchor = findParentEntryAbsLine(parent.id, b.groupChildIndex ?? 0) ?? parent.summaryAbsIdx;
+            layout.contentInsertAfter(anchor, [sanitizeRow(buildSummaryLine(b))]);
+            b.summaryAbsIdx = anchor + 1;
+            absLineToBatchId.set(b.summaryAbsIdx, b.id);
+            return;
+        }
+    }
     const summary = buildSummaryLine(b);
     // 写摘要行(以 \n 收尾;contentWrite 会 breakRow 让其成为完整物理行)
     layout.contentWrite(summary + '\n');
@@ -217,6 +331,37 @@ export function showLiveBatch(id, layout) {
         return;
     const summary = buildSummaryLine(b, true);
     if (b.summaryAbsIdx < 0) {
+        // 子批:摘要行插到父批已渲染块的正下方(而非 buffer 末尾),
+        // 让「子 agent 的工具明细」始终跟在自己的父调用行下——并行派发时才不串行。
+        const parent = b.parentId ? batches.get(b.parentId) : undefined;
+        if (parent && parent.summaryAbsIdx >= 0 && layout.contentInsertAfter) {
+            // 组容器父批处于折叠态时,子批摘要行先不渲染;等父批展开时由 expand 统一恢复,
+            // 避免子批摘要残留在父批明细区、再次展开后出现重复行。
+            if (parent.groupParent && !expandedBatches.has(parent.id)) {
+                b.summaryAbsIdx = -1;
+                return;
+            }
+            let anchor;
+            if (parent.groupParent && b.groupChildIndex != null && expandedBatches.has(parent.id)) {
+                // 组容器已展开:子 agent 工具批插到第 groupChildIndex 个 └─ sub-agent 行下方。
+                // 不能用固定偏移 summaryAbsIdx+1+childIndex——前面兄弟子批的内容会把它后面的
+                // entry 行整体下移,固定偏移会错位;用 absLineToEntry 登记的真实绝对索引。
+                let entryAbs = parent.summaryAbsIdx + 1 + b.groupChildIndex;
+                for (const [idx, target] of absLineToEntry) {
+                    if (target.batchId === parent.id && target.entryIndex === b.groupChildIndex) {
+                        entryAbs = idx;
+                        break;
+                    }
+                }
+                anchor = entryAbs;
+            }
+            else {
+                anchor = parent.summaryAbsIdx + (expandedBatches.has(parent.id) ? parent.renderedCount : 0);
+            }
+            layout.contentInsertAfter(anchor, [sanitizeRow(summary)], false);
+            b.summaryAbsIdx = anchor + 1;
+            return;
+        }
         layout.contentWrite(summary + '\n');
         b.summaryAbsIdx = Math.max(0, layout.totalRows() - 2);
         // 首条摘要通过增量 contentWrite 落屏时，markdown→普通内容的边界可能只更新了
@@ -241,6 +386,61 @@ export function findBatchByAbsLine(absLine) {
 export function isExpanded(id) {
     return expandedBatches.has(id);
 }
+/** 展开 batch 第一层(逐条工具调用)。供子 agent 实时运行态:执行中逐条展示。
+ *  live=true 时不锚定视口(实时输出跟随底部),区别于鼠标点击展开(保持视口不跳)。 */
+export function expandBatch(id, layout, live = false) {
+    const b = batches.get(id);
+    if (b && !expandedBatches.has(id))
+        expand(b, layout, live);
+}
+/**
+ * 展开态下**追加渲染**新增的明细行(子 agent 逐条追加工具时用)。
+ * 只插入 entries[renderedCount, ...) 中尚未渲染的条目,绝不重建——运行态下
+ * 并行多个批时,重建会按 entries.length 删除,误删其它子 agent 的批行。
+ * 未展开则 no-op。
+ */
+export function refreshBatchExpanded(id, layout) {
+    const b = batches.get(id);
+    if (!b || !expandedBatches.has(id))
+        return;
+    if (b.summaryAbsIdx < 0)
+        return; // 摘要行未落盘(父组容器折叠中):无处可挂,等展开时统一渲染
+    if (b.entries.length <= b.renderedCount)
+        return;
+    const newEntries = b.entries.slice(b.renderedCount);
+    const lines = buildExpandedLines(newEntries, b.indent ?? '');
+    // 实时追加:不锚定视口,让新明细行自然出现在屏底。
+    // 组容器批的 entry 与子批摘要行交错,新 entry 必须插在当前块末尾,
+    // 不能简单用 summaryAbsIdx+renderedCount(否则 entry 会插到前一个子批摘要行之前)。
+    let anchor = b.summaryAbsIdx + b.renderedCount;
+    if (b.groupParent) {
+        let maxIdx = b.summaryAbsIdx;
+        for (const [idx, target] of absLineToEntry) {
+            if (target.batchId === b.id && idx > maxIdx)
+                maxIdx = idx;
+        }
+        for (const child of batches.values()) {
+            if (child.parentId === b.id && child.summaryAbsIdx >= 0) {
+                let childEnd = child.summaryAbsIdx;
+                if (expandedBatches.has(child.id)) {
+                    childEnd += child.renderedCount;
+                    for (const j of child.expandedEntries) {
+                        childEnd += buildEntryDetailLines(child.entries[j], entryDetailIndent(child.entries, j)).length;
+                    }
+                }
+                if (childEnd > maxIdx)
+                    maxIdx = childEnd;
+            }
+        }
+        anchor = maxIdx;
+    }
+    layout.contentInsertAfter(anchor, lines, false);
+    // 登记新增明细行的点击命中(按实际插入位置)
+    for (let i = 0; i < newEntries.length; i++) {
+        absLineToEntry.set(anchor + 1 + i, { batchId: b.id, entryIndex: b.renderedCount + i });
+    }
+    b.renderedCount = b.entries.length;
+}
 /**
  * 切换 batch 展开/折叠;无变化时 no-op。
  * 折叠:从 buffer 删详情行(mid-buffer delete);
@@ -259,13 +459,38 @@ export function toggleBatch(id, layout) {
         expand(b, layout);
     }
 }
-function expand(b, layout) {
-    const lines = buildExpandedLines(b.entries);
-    layout.contentInsertAfter(b.summaryAbsIdx, lines);
+function expand(b, layout, live = false) {
+    if (b.summaryAbsIdx < 0)
+        return; // 摘要行未落盘时展开会把明细插到 buffer 头部
+    const lines = buildExpandedLines(b.entries, b.indent ?? '');
+    layout.contentInsertAfter(b.summaryAbsIdx, lines, !live);
     expandedBatches.add(b.id);
+    b.renderedCount = b.entries.length;
     for (let i = 0; i < b.entries.length; i++) {
         absLineToEntry.set(b.summaryAbsIdx + 1 + i, { batchId: b.id, entryIndex: i });
     }
+    // 组容器批展开时:把之前被折叠隐藏的子批摘要行重新插回对应 entry 下方,
+    // 否则子批摘要行会留在父批摘要行之后、造成明细重复/错位。
+    if (b.groupParent) {
+        const children = [...batches.values()]
+            .filter((x) => x.parentId === b.id)
+            .sort((a, b) => (a.groupChildIndex ?? 0) - (b.groupChildIndex ?? 0));
+        for (const child of children) {
+            const entryAbs = findParentEntryAbsLine(b.id, child.groupChildIndex ?? 0);
+            const anchor = entryAbs ?? b.summaryAbsIdx + b.renderedCount;
+            const summary = buildSummaryLine(child, true);
+            layout.contentInsertAfter(anchor, [sanitizeRow(summary)], !live);
+            child.summaryAbsIdx = anchor + 1;
+            absLineToBatchId.set(child.summaryAbsIdx, child.id);
+        }
+    }
+}
+function findParentEntryAbsLine(parentId, entryIndex) {
+    for (const [idx, target] of absLineToEntry) {
+        if (target.batchId === parentId && target.entryIndex === entryIndex)
+            return idx;
+    }
+    return null;
 }
 /** mutation 独占 batch 收尾后立即展示其调用概要和 diff。 */
 export function expandSingleEntryFully(id, layout) {
@@ -285,12 +510,47 @@ export function expandSingleEntryFully(id, layout) {
     absLineToEntry.set(b.summaryAbsIdx + 1, { batchId: id, entryIndex: 0 });
 }
 function collapse(b, layout) {
-    let lineCount = b.entries.length;
+    // 只删除实际渲染的明细行(renderedCount),而非 entries.length——运行态下
+    // entries 可能多于已渲染行,按 entries.length 会多删并行批量子 agent 的行。
+    let lineCount = b.renderedCount;
     for (const i of b.expandedEntries) {
         lineCount += buildEntryDetailLines(b.entries[i], entryDetailIndent(b.entries, i)).length;
     }
+    // 组容器批折叠时:一并移除嵌套子批的摘要行(及其已展开详情),
+    // 否则父批再次展开后子批摘要仍残留在明细区,出现重复行。
+    if (b.groupParent) {
+        const children = [...batches.values()].filter((x) => x.parentId === b.id);
+        for (const child of children) {
+            // 未落盘的子批(父批折叠期间新建)在 buffer 里没有对应行,计进 lineCount 会多删相邻正文。
+            if (child.summaryAbsIdx < 0) {
+                child.renderedCount = 0;
+                child.expandedEntries.clear();
+                expandedBatches.delete(child.id);
+                continue;
+            }
+            lineCount += 1; // 子批摘要行本身
+            if (expandedBatches.has(child.id)) {
+                // 子批自身展开时,它的第一层明细行(renderedCount)也在父批块内,必须一并计入,
+                // 否则删少了会留下孤儿明细行。
+                lineCount += child.renderedCount;
+                for (const j of child.expandedEntries) {
+                    lineCount += buildEntryDetailLines(child.entries[j], entryDetailIndent(child.entries, j)).length;
+                }
+                child.expandedEntries.clear();
+                expandedBatches.delete(child.id);
+            }
+            child.renderedCount = 0;
+            absLineToBatchId.delete(child.summaryAbsIdx);
+            child.summaryAbsIdx = -1;
+            for (const [idx, target] of absLineToEntry) {
+                if (target.batchId === child.id)
+                    absLineToEntry.delete(idx);
+            }
+        }
+    }
     layout.contentDeleteFrom(b.summaryAbsIdx + 1, lineCount);
     expandedBatches.delete(b.id);
+    b.renderedCount = 0;
     b.expandedEntries.clear();
     for (const [idx, target] of absLineToEntry) {
         if (target.batchId === b.id)
@@ -301,11 +561,27 @@ function collapse(b, layout) {
 export function findEntryByAbsLine(absLine) {
     return absLineToEntry.get(absLine) ?? null;
 }
-/** 第二层：只展开/折叠某一个工具的完整输出。 */
+/** 第二层：只展开/折叠某一个工具的完整输出。
+ *  特殊地，组容器批(groupParent)下的 sub-agent entry 行点击时，
+ *  切换的是对应子 Agent 批(child batch)的展开/折叠，而不是 entry 自身详情。 */
 export function toggleEntry(batchId, entryIndex, layout) {
     const b = batches.get(batchId);
     if (!b || !expandedBatches.has(batchId))
         return;
+    // 组容器批的 entry 对应一个子 Agent 批；点击 entry 行应展开/折叠该 entry
+    // 自身的详情（即子 agent 返回的完整文本输出）。子 agent 的工具调用列表由点击
+    // 子批自己的摘要行（● 子 Agent 完成 ...）来控制。
+    if (b.groupParent) {
+        // 如果该 sub-agent entry 没有可展开的详情，fallback 到 toggle 子批工具列表。
+        const details = buildEntryDetailLines(b.entries[entryIndex], entryDetailIndent(b.entries, entryIndex));
+        if (details.length === 0) {
+            const child = [...batches.values()].find((x) => x.parentId === batchId && x.groupChildIndex === entryIndex);
+            if (child) {
+                toggleBatch(child.id, layout);
+            }
+            return;
+        }
+    }
     let headerIdx = -1;
     for (const [idx, target] of absLineToEntry) {
         if (target.batchId === batchId && target.entryIndex === entryIndex)
@@ -369,7 +645,19 @@ export function shiftBatchesAfter(absIdx, delta) {
             b.summaryAbsIdx = Math.max(0, b.summaryAbsIdx + delta);
     }
 }
-// ── history 回放支持 ──
+/** 更新 batch 摘要行标签(子 agent 批:运行中→完成/失败)。 */
+export function setBatchLabel(id, label) {
+    const b = batches.get(id);
+    if (b)
+        b.label = label;
+}
+/** 设置/清除运行态标志:running=true 时摘要行用「运行中」专属图标,收尾时置 false。 */
+export function setBatchRunning(id, running) {
+    const b = batches.get(id);
+    if (b)
+        b.running = running;
+}
+/** history 回放支持 ── */
 /** 把已构造好的 BatchEntry[] 落成可切换摘要行(用于 renderHistory 回放)。
  *  含 mutation(write_file/edit_file)时整批展开；普通批次保留与实时 flushToolBatch 相同的空行边界。 */
 export function writeSummaryOnly(entries, layout) {

package/dist/ui/layout.js

@@ -10,6 +10,11 @@ import { renderMarkdown } from './markdown.js';
 import { t } from '../i18n/index.js';
 // ── 内部状态 ──
 let active = false;
+/** 是否处于全屏 TUI(alt screen)激活态。非 TTY / 嵌入宿主(host)下为 false。
+ *  子 agent 等异步路径据此判断能否把中间过程实时写入主内容区。 */
+export function isTuiActive() {
+    return active;
+}
 // ── 裸 console 防御:第三方库(如 openai SDK)可能用 console.log 直写 stdout,
 // 在 RUNNING 态会落到光标所在的底栏输入框,污染输入。进入 TUI 后把 console.*
 // 劫持到 contentWrite,统一进内容区(运行态下 contentWrite 末尾会把真光标归位输入框),
@@ -587,8 +592,12 @@ export function rewindContent(rowsToRewind) {
  *
  * 续写位(contentRow):若原写头在插入点之后,前移 lines.length,保持相对位置;
  * 若原写头 ≤ after,不变(新行在写头之后)。非 TTY 直接调 content.insertAfter。
+ *
+ * keepViewport:鼠标点击展开时 true(视口锚定原位,详情在下方展开,屏幕不跳);
+ * 子 agent 实时嵌套渲染时传 false —— 那是"新内容"而非"回看展开",必须跟随屏底,
+ * 否则每插一行就把视口冻住 1 行,子 agent 跑起来后主内容区看着像卡住不动。
  */
-export function contentInsertAfter(after, lines) {
+export function contentInsertAfter(after, lines, keepViewport = true) {
     if (!active || lines.length === 0)
         return;
     const g = getGeo();
@@ -616,7 +625,7 @@ export function contentInsertAfter(after, lines) {
     // 而不是自动跳到展开内容底部(用户体验:点击摘要行,视口不动,详情在下方展开)。
     // 关键:插入点绝对行 = after;插入前视口尾行绝对行 = totalBefore - 1;
     // 插入后要让原视口尾行仍在屏底 → scrollOffset = 插入后新增的、在原视口尾行之后的行数。
-    if (!scrolled && after < totalBefore) {
+    if (keepViewport && !scrolled && after < totalBefore) {
         // 插入点在原缓冲内(非追加到末尾),计算需要滚动的偏移量
         const insertedAfterViewport = after >= (totalBefore - g.contentBottom);
         if (insertedAfterViewport) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 16 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {