mocode-ai 0.7.3 → 1.0.2

package/dist/session/compact.js

@@ -7,6 +7,7 @@ import * as layout from '../ui/layout.js';
 import { pruneAfterCompaction } from '../rollback/index.js';
 import { toText } from '../context/utils.js';
 import { DEFAULT_BUDGET_POLICY } from '../context/budget.js';
+import { collectArtifactRefs } from '../context/artifacts.js';
 export function createContextState() {
     return { lastEstimate: 0, correction: 1, calibrationSamples: 0 };
 }
@@ -210,7 +211,7 @@ async function defaultSummarize(older, focus) {
     }
     const sysMsg = {
         role: 'system',
-        content: 'You are a session summarizer. Output only the summary body, max 300 words, preserving: the user\'s core request; files read/written/modified and key changes; key commands run and their result highlights; decisions made; current task progress and next step; open questions. Do not recap every detail.',
+        content: 'You are a session summarizer. Output only the summary body, max 300 words, preserving: the user\'s core request; files read/written/modified and key changes; source artifact IDs/hashes; key commands run and their result highlights; decisions made; current task progress and next step; open questions. Do not recap every detail.',
     };
     const userMsg = {
         role: 'user',
@@ -302,10 +303,11 @@ export async function compactHistory(history, opts) {
                     }
                 }
             }
+            const refs = collectArtifactRefs(older);
             const summaryMsg = {
                 role: 'system',
                 content: older.length > 0
-                    ? `# 会话摘要(force)\n被跳过的早期对话 ${older.length} 条已微压缩(token 数减少)。`
+                    ? `# 会话摘要(force)\n被跳过的早期对话 ${older.length} 条已微压缩(token 数减少)。${refs.length > 0 ? `\n[artifact refs: ${refs.join(', ')}]` : ''}`
                     : `# 会话摘要(force)\n无内容。`,
             };
             const rebuilt = [history[0], summaryMsg, ...keptAfter];
@@ -389,9 +391,13 @@ export async function compactHistory(history, opts) {
         summary = null; // 摘要失败 → 回退仅微压缩,不崩
     }
     if (summary) {
+        const artifactRefs = collectArtifactRefs(older);
+        const provenance = artifactRefs.length > 0
+            ? `\n\n[artifact refs: ${artifactRefs.join(', ')}]`
+            : '';
         const summaryMsg = {
             role: 'system',
-            content: `# 会话摘要\n${summary}`,
+            content: `# 会话摘要\n${summary}${provenance}`,
         };
         // 原地重建:[systemPrompt, summaryMsg, ...kept]
         const systemMsg = history[0];

package/dist/session/scheduler.js

@@ -23,11 +23,15 @@ import { config } from '../config/index.js';
 import { maybeCompact, contextState } from './compact.js';
 import * as layout from '../ui/layout.js';
 import { ui } from '../ui/theme.js';
+import { pruneStaleArtifacts, refreshArtifactFreshness } from '../context/artifacts.js';
 /** 创建 runAgentCore 闭包持有的 scheduler(每次 agent 启动一个新实例)。 */
 export function createBudgetScheduler(state = contextState) {
     const obs = {
         lastRunLog: null,
         async runStep(history, step, activeTools = chatTools) {
+            // Re-check file-backed hashes first, then discard stale/rebuildable facts before budgeting.
+            refreshArtifactFreshness(state, history);
+            pruneStaleArtifacts(state, history);
             const report = evaluateBudget(history, config.contextWindowTokens, step, state.correction, activeTools);
             const actions = scheduleActions(report);
             let compactHistoryCalled = false;

package/dist/session/state.js

@@ -1,33 +1,17 @@
 // session/state.ts - 会话状态跟踪模块
 // 提供当前活跃会话 ID 的全局访问点，供 config/buildNotepadSection 等读取会话级 notes.md。
 // 避免 repl/index.ts ↔ config/index.ts 循环依赖。
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
 let currentSessionId;
 /** 获取当前活跃会话 ID(供 buildNotepadSection 等使用)。 */
 export function getCurrentSessionId() {
     return currentSessionId;
 }
 /**
- * 设置当前活跃会话 ID，并确保该会话的 notes.md 文件存在（不存在则创建空文件）。
+ * 设置当前活跃会话 ID。notes.md 由 agent 按需创建；这里不能预建空文件，
+ * 否则 write_file(expected_hash=null) 的首次创建会必然冲突。
  * 由 repl/index.ts 在会话启动 / /resume 切换时调用。
  */
 export function setCurrentSessionId(id, cwd) {
     currentSessionId = id;
-    if (id)
-        ensureSessionNotes(id, cwd);
-}
-/** 确保 .mocode/sessions/<id>/notes.md 存在，不存在则创建空文件。 */
-function ensureSessionNotes(id, cwd) {
-    const dir = path.join(cwd, '.mocode', 'sessions', id);
-    const file = path.join(dir, 'notes.md');
-    if (existsSync(file))
-        return;
-    try {
-        mkdirSync(dir, { recursive: true });
-        writeFileSync(file, '', 'utf8');
-    }
-    catch {
-        // 创建失败不影响 REPL 主流程
-    }
+    void cwd;
 }

package/dist/tools/builtins/apply-patch.js

@@ -0,0 +1,174 @@
+import { readFile } from 'node:fs/promises';
+import { jailResolve } from '../../sandbox/index.js';
+import { commitChangeSet, contentHash, createChangeSet, summarizeChangeSet, } from '../../changeset/index.js';
+function invalid(message) {
+    const error = new Error(message);
+    error.name = 'PatchError';
+    return error;
+}
+function parsePatch(input) {
+    const lines = input.replace(/\r\n/g, '\n').split('\n');
+    if (lines[0] !== '*** Begin Patch')
+        throw invalid('patch 必须以 *** Begin Patch 开始。');
+    const operations = [];
+    let i = 1;
+    while (i < lines.length && lines[i] !== '*** End Patch') {
+        const header = lines[i++];
+        let match = /^\*\*\* Add File: (.+)$/.exec(header);
+        if (match) {
+            const body = [];
+            while (i < lines.length && !lines[i].startsWith('*** ')) {
+                const line = lines[i++];
+                if (!line.startsWith('+'))
+                    throw invalid(`Add File ${match[1]} 的内容行必须以 + 开头。`);
+                body.push(line.slice(1));
+            }
+            operations.push({ kind: 'add', path: match[1], lines: body });
+            continue;
+        }
+        match = /^\*\*\* Delete File: (.+)$/.exec(header);
+        if (match) {
+            operations.push({ kind: 'delete', path: match[1] });
+            continue;
+        }
+        match = /^\*\*\* Update File: (.+)$/.exec(header);
+        if (!match)
+            throw invalid(`未知 patch 指令: ${header}`);
+        const hunks = [];
+        while (i < lines.length && !lines[i].startsWith('*** ')) {
+            if (!lines[i].startsWith('@@'))
+                throw invalid(`Update File ${match[1]} 缺少 @@ hunk。`);
+            i++;
+            const hunk = [];
+            while (i < lines.length && !lines[i].startsWith('@@') && !lines[i].startsWith('*** ')) {
+                hunk.push(lines[i++]);
+            }
+            hunks.push(hunk);
+        }
+        operations.push({ kind: 'update', path: match[1], hunks });
+    }
+    if (lines[i] !== '*** End Patch')
+        throw invalid('patch 缺少 *** End Patch。');
+    if (operations.length === 0)
+        throw invalid('patch 不包含文件操作。');
+    return operations;
+}
+function applyHunks(source, hunks, file) {
+    let current = source.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    for (const hunk of hunks) {
+        const before = [];
+        const after = [];
+        for (const line of hunk) {
+            if (line.startsWith(' ')) {
+                before.push(line.slice(1));
+                after.push(line.slice(1));
+            }
+            else if (line.startsWith('-')) {
+                before.push(line.slice(1));
+            }
+            else if (line.startsWith('+')) {
+                after.push(line.slice(1));
+            }
+            else if (line === '\') {
+                continue;
+            }
+            else {
+                throw invalid(`Update File ${file} 的 hunk 行必须以空格、+ 或 - 开头。`);
+            }
+        }
+        const oldText = before.join('\n');
+        const newText = after.join('\n');
+        if (!oldText)
+            throw invalid(`Update File ${file} 的 hunk 缺少上下文或删除行。`);
+        const first = current.indexOf(oldText);
+        if (first < 0)
+            throw invalid(`Update File ${file} 的 hunk 与当前文件不匹配。`);
+        if (current.indexOf(oldText, first + 1) >= 0) {
+            throw invalid(`Update File ${file} 的 hunk 上下文不唯一，请增加上下文。`);
+        }
+        current = current.slice(0, first) + newText + current.slice(first + oldText.length);
+    }
+    return source.includes('\r\n') ? current.replace(/\n/g, '\r\n') : current;
+}
+async function buildChanges(operations) {
+    const changes = [];
+    for (const operation of operations) {
+        if (operation.kind === 'add') {
+            changes.push({
+                path: operation.path,
+                operation: 'create',
+                expectedHash: null,
+                replacement: operation.lines.join('\n'),
+            });
+            continue;
+        }
+        const raw = await readFile(jailResolve(operation.path));
+        const expectedHash = contentHash(raw);
+        if (operation.kind === 'delete') {
+            changes.push({ path: operation.path, operation: 'delete', expectedHash });
+            continue;
+        }
+        const source = raw.toString('utf8');
+        changes.push({
+            path: operation.path,
+            operation: 'update',
+            expectedHash,
+            replacement: applyHunks(source, operation.hunks, operation.path),
+        });
+    }
+    return changes;
+}
+function conflictOutcome(result) {
+    return {
+        status: 'error',
+        code: 'CHANGE_CONFLICT',
+        retryable: false,
+        changedFiles: [],
+        staleFiles: result.conflicts.map((item) => item.path),
+        output: [
+            '错误:apply_patch 检测到内容冲突，磁盘未发生变化。',
+            ...result.conflicts.map((item) => `- ${item.path}: expected=${item.expectedHash ?? 'missing'}, actual=${item.actualHash ?? 'missing'} (${item.reason})`),
+        ].join('\n'),
+    };
+}
+export const applyPatchTool = {
+    name: 'apply_patch',
+    description: 'Apply a multi-file patch transactionally. Format: *** Begin Patch, then *** Add/Update/Delete File sections, then *** End Patch. All files are dry-run and hash-checked before any file is committed; failure leaves disk unchanged.',
+    risk: 'confirm',
+    parameters: {
+        type: 'object',
+        properties: {
+            patch: { type: 'string', description: 'The complete *** Begin Patch ... *** End Patch document.' },
+        },
+        required: ['patch'],
+    },
+    async execute(args, ctx) {
+        try {
+            const changes = await buildChanges(parsePatch(String(args.patch)));
+            const result = await commitChangeSet(createChangeSet(changes), ctx?.signal);
+            if (result.status === 'conflict')
+                return conflictOutcome(result);
+            if (result.status === 'failed') {
+                return { status: 'error', code: 'PATCH_INVALID', retryable: false, changedFiles: [], output: `错误:apply_patch 提交失败，已恢复磁盘: ${result.error}` };
+            }
+            const summary = summarizeChangeSet(result.changeSet);
+            return {
+                status: 'success',
+                code: 'OK',
+                retryable: false,
+                changedFiles: result.changedFiles,
+                changeSet: summary,
+                output: `已事务化应用 ChangeSet ${summary.id}:\n${summary.changes.map((item) => `- ${item.operation} ${item.path} (${item.beforeHash ?? 'missing'} -> ${item.afterHash ?? 'missing'})`).join('\n')}`,
+            };
+        }
+        catch (error) {
+            return {
+                status: 'error',
+                code: 'PATCH_INVALID',
+                retryable: false,
+                changedFiles: [],
+                output: `错误:apply_patch 无效，磁盘未发生变化: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};

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

@@ -1,66 +1,79 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { verifyWrittenFile } from '../../verification/postconditions.js';
-// ---------- edit_file ----------
+import { readFile } from 'node:fs/promises';
+import { jailResolve } from '../../sandbox/index.js';
+import { commitChangeSet, createChangeSet, normalizeContentHash, summarizeChangeSet, } from '../../changeset/index.js';
+function conflict(path, details) {
+    return {
+        status: 'error',
+        code: 'CHANGE_CONFLICT',
+        retryable: false,
+        changedFiles: [],
+        staleFiles: [path],
+        output: `CHANGE_CONFLICT: ${path} was not changed. ${details} Do not retry these arguments. Call read_file on this exact path and copy both its latest hash and exact target text before editing again.`,
+    };
+}
 export const editFileTool = {
     name: 'edit_file',
-    description: 'Replace a string in a file. old_string must occur exactly once and match exactly (including indentation/newlines). Copy old_string verbatim from a fresh read_file result for this path; do not reconstruct it from memory or summaries. Use write_file for new files.',
+    description: 'Replace one exact string in a file transactionally. expected_hash is required and must be copied from a fresh read_file artifact header. If the file changes after that read, the edit is rejected without writing.',
     risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {
             path: { type: 'string' },
-            old_string: { type: 'string', description: 'The original text to be replaced; must match exactly' },
-            new_string: { type: 'string', description: 'The new text to replace it with' },
+            old_string: { type: 'string', description: 'The original text; must occur exactly once.' },
+            new_string: { type: 'string', description: 'Replacement text.' },
+            expected_hash: { type: 'string', description: 'sha256 hash from the latest read_file artifact header.' },
         },
-        required: ['path', 'old_string', 'new_string'],
+        required: ['path', 'old_string', 'new_string', 'expected_hash'],
     },
-    async execute(args) {
-        const path = String(args.path);
-        const oldStr = String(args.old_string);
-        const newStr = String(args.new_string);
-        const full = resolve(path);
-        const data = await readFile(full, 'utf8');
-        // 行尾归一化:read_file 用 split(/\r?\n/) 输出纯 LF,LLM 据此构造的 old_string/new_string
-        // 也是 LF;但本工具原样读文件(CRLF 保留),直接精确匹配会在 CRLF 文件上必败(文件 \r\n 对不上
-        // old_string 的 \n)。故匹配/计数在归一化(LF)文本上做,写回时按文件原始行尾风格还原,
-        // 不把 CRLF 文件悄悄换成 LF(只含 LF 的纯 LF 文件 norm===data,行为完全不变)。
-        const norm = data.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-        const normOld = oldStr.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-        const normNew = newStr.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-        const count = norm.split(normOld).length - 1;
+    async execute(args, ctx) {
+        const file = String(args.path);
+        const oldString = String(args.old_string);
+        const newString = String(args.new_string);
+        const expectedHash = normalizeContentHash(String(args.expected_hash));
+        if (!expectedHash)
+            return conflict(file, 'expected_hash 必须是 sha256:<64 hex>。');
+        const data = await readFile(jailResolve(file), 'utf8');
+        const normalized = data.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        const oldNormalized = oldString.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        const newNormalized = newString.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        const count = normalized.split(oldNormalized).length - 1;
         if (count === 0) {
-            return {
-                status: 'error',
-                code: 'EDIT_CONFLICT',
-                retryable: false,
-                output: `错误:在 ${path} 中未找到 old_string。不要重试相同参数；请先 read_file 读取目标区域，再从返回内容逐字复制新的 old_string 后重试。`,
-            };
+            return conflict(file, 'old_string 未找到；请重新 read_file 并复制最新内容。');
         }
         if (count > 1) {
-            return {
-                status: 'error',
-                code: 'EDIT_CONFLICT',
-                retryable: false,
-                output: `错误:old_string 在 ${path} 中出现 ${count} 次,不唯一。请加入更多上下文使其唯一。`,
-            };
+            return conflict(file, `old_string 出现 ${count} 次；请增加上下文使其唯一。`);
+        }
+        const updated = normalized.replace(oldNormalized, () => newNormalized);
+        const replacement = data.includes('\r\n') ? updated.replace(/\n/g, '\r\n') : updated;
+        const result = await commitChangeSet(createChangeSet([{
+                path: file,
+                operation: 'update',
+                expectedHash,
+                replacement,
+            }]), ctx?.signal);
+        if (result.status === 'conflict') {
+            const item = result.conflicts[0];
+            return conflict(file, `expected=${item?.expectedHash ?? 'missing'}, actual=${item?.actualHash ?? 'missing'}。请重新读取后再编辑。`);
         }
-        // 用函数形式替换,避免 new_string 里的 $ 被当特殊模式
-        const updated = norm.replace(normOld, () => normNew);
-        // 检测原始行尾风格,写回时还原(存在 \r\n 即视为 CRLF 文件;纯 LF 文件保持 LF)
-        const out = data.includes('\r\n') ? updated.replace(/\n/g, '\r\n') : updated;
-        await writeFile(full, out, 'utf8');
-        const postcondition = await verifyWrittenFile(full, out);
-        if (postcondition.status === 'failed') {
+        if (result.status === 'failed') {
             return {
                 status: 'error',
-                code: 'POSTCONDITION_FAILED',
+                code: 'EXECUTION_ERROR',
                 retryable: false,
-                output: postcondition.diagnostics
-                    .map((item) => `[${item.code ?? 'V0_FAILED'}] ${item.file ?? path}: ${item.message}`)
-                    .join('\n'),
+                changedFiles: [],
+                output: `错误:ChangeSet 提交失败并已执行恢复: ${result.error}`,
             };
         }
-        return `已在 ${path} 中完成 1 处替换 (sha256=${postcondition.actualHash})。`;
+        const summary = summarizeChangeSet(result.changeSet);
+        return {
+            status: 'success',
+            code: 'OK',
+            retryable: false,
+            changedFiles: result.changedFiles,
+            changeSet: summary,
+            output: result.changedFiles.length === 0
+                ? `文件 ${file} 内容未变化 (ChangeSet ${summary.id})。`
+                : `已事务化编辑 ${file} (ChangeSet ${summary.id}, sha256=${summary.changes[0]?.afterHash})。`,
+        };
     },
 };

package/dist/tools/builtins/index.js

@@ -16,7 +16,7 @@ import { memorySearchTool } from './memory-search.js';
 import { memoryListTool } from './memory-list.js';
 import { memoryUpdateTool } from './memory-update.js';
 import { memoryForgetTool } from './memory-forget.js';
-import { taskTool } from './task.js';
+import { subAgentTool } from './task.js';
 import { projectSkillUpdateTool } from './project-skill-update.js';
 /**
  * 所有内置工具,按注册顺序排列。
@@ -51,8 +51,8 @@ const workspaceResource = () => ['workspace'];
 const memoryResource = () => ['memory-store'];
 const CAPABILITIES = {
     read_file: { effect: 'read', concurrency: 'parallel', retry: 'safe', resources: pathResource },
-    write_file: { effect: 'write', concurrency: 'resource-locked', retry: 'never', resources: pathResource },
-    edit_file: { effect: 'write', concurrency: 'resource-locked', retry: 'never', resources: pathResource },
+    write_file: { effect: 'write', concurrency: 'resource-locked', retry: 'never', resources: pathResource, delegatesResourceLocks: true },
+    edit_file: { effect: 'write', concurrency: 'resource-locked', retry: 'never', resources: pathResource, delegatesResourceLocks: true },
     run_command: { effect: 'process', concurrency: 'serial', retry: 'never', resources: workspaceResource, supportsAbort: true },
     glob: { effect: 'read', concurrency: 'parallel', retry: 'safe', resources: workspaceResource },
     grep: { effect: 'read', concurrency: 'parallel', retry: 'safe', resources: workspaceResource },
@@ -69,12 +69,14 @@ const CAPABILITIES = {
     memory_update: { effect: 'write', concurrency: 'serial', retry: 'never', resources: memoryResource },
     memory_forget: { effect: 'write', concurrency: 'serial', retry: 'never', resources: memoryResource },
     project_skill_update: { effect: 'write', concurrency: 'serial', retry: 'never', resources: workspaceResource },
-    // task 只编排子 Agent；真实读写由子调用自行持锁，父调用不得包 workspace 锁。
-    task: {
+    // sub-agent 动态协调：只读任务无锁并行；写任务在 overlay 中执行，merge 时由 ChangeSet 持 canonical lock。
+    'sub-agent': {
         effect: 'write',
-        concurrency: 'serial',
+        concurrency: 'resource-locked',
         retry: 'never',
-        resources: workspaceResource,
+        resources: (args) => args.mode === 'write' && Array.isArray(args.writeSet) && args.writeSet.length
+            ? args.writeSet.map((item) => `file:${String(item)}`)
+            : args.mode === 'write' ? ['workspace'] : [],
         delegatesResourceLocks: true,
         supportsAbort: true,
     },
@@ -95,7 +97,7 @@ const rawBuiltinTools = [
     dropContextTool,
     ..._memoryTools,
     ..._projectSkillTools,
-    taskTool,
+    subAgentTool,
 ];
 /** 所有内置工具均携带显式能力；新增工具遗漏声明时 registry 会保守串行。 */
 export const builtinTools = rawBuiltinTools.map((tool) => ({

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { contentHash } from '../../changeset/index.js';
 import { MAX_FILE_LINES } from '../constants.js';
 /** 默认单次 read_file 拉取的行数。刻意压低,逼 LLM 分块读大文件,
  * 配合 description 中的 PAGINATION IS MANDATORY 引导。
@@ -30,6 +31,7 @@ export const readFileTool = {
         // 无论 LLM 传多大,单次硬钳到 MAX_FILE_LINES,杜绝「绕过分页引导一把全拿」。
         const limit = Math.min(Number(args.limit ?? DEFAULT_READ_LIMIT), MAX_FILE_LINES);
         const data = await readFile(resolve(path), 'utf8');
+        const artifactHeader = `[artifact source=read_file path=${path} hash=${contentHash(data)}]`;
         const lines = data.split(/\r?\n/);
         const start = Math.max(0, offset - 1);
         const end = Math.min(lines.length, start + limit);
@@ -38,8 +40,8 @@ export const readFileTool = {
             .map((l, i) => `${String(start + i + 1).padStart(6, ' ')}\t${l}`)
             .join('\n');
         if (end < lines.length) {
-            return body + `\n\n... (${lines.length - end} 行未显示,共 ${lines.length} 行)`;
+            return artifactHeader + '\n' + body + `\n\n... (${lines.length - end} 行未显示,共 ${lines.length} 行)`;
         }
-        return body || '(空文件)';
+        return artifactHeader + '\n' + (body || '(空文件)');
     },
 };

package/dist/tools/builtins/task.js

@@ -8,12 +8,12 @@ import { isSubAgentEnabled } from '../../config/index.js';
 //
 // 适用:分而治之的复杂任务 / 隔离上下文避免子任务工具噪声撑爆主窗口。
 // 多个 task 在共享工作区期间由 capability scheduler 串行执行；隔离 workspace 落地后再开放并行写。
-export const taskTool = {
-    name: 'task',
+export const subAgentTool = {
+    name: 'sub-agent',
     risk: 'dangerous',
     description: [
-        'Spawn a sub-agent for an isolated sub-task (independent history; only its final summary returns to you).',
-        'Use when a task splits into independent parts or its many tool calls would bloat your context.',
+        'Spawn a capable worker for an isolated sub-task; only its structured result returns.',
+        'Pass context with facts the main agent already knows to prevent duplicate exploration and token waste.',
         'Cannot recursively spawn sub-agents.',
     ].join(''),
     parameters: {
@@ -26,11 +26,23 @@ export const taskTool = {
             tools: {
                 type: 'array',
                 items: { type: 'string' },
-                description: 'Optional whitelist of tool names the sub-agent is allowed to use (e.g. ["read_file","glob","grep","codegraph"] for read-only investigation). Omit to allow all tools. If the sub-task needs verification/build/test (running scripts, typecheck, etc.), remember to include "run_command".',
+                description: 'Optional whitelist for deliberate specialization. Omit it to preserve the worker full capability for its mode.',
             },
             maxSteps: {
                 type: 'number',
-                description: 'Optional step limit for the sub-agent (default 50). Lower if the sub-task should be quick.',
+                description: 'Optional loop-safety override. By default the worker uses the same step ceiling as the main agent; this is not a token budget.',
+            },
+            mode: {
+                type: 'string', enum: ['read', 'write'],
+                description: 'read tasks may run in parallel; write tasks use an isolated overlay and are merged by the coordinator.',
+            },
+            writeSet: {
+                type: 'array', items: { type: 'string' },
+                description: 'Known workspace-relative paths this task may write. Unknown write sets conservatively use the workspace lock.',
+            },
+            context: {
+                type: 'string',
+                description: 'Concise facts already learned by the main agent. Passing this avoids duplicate repository exploration.',
             },
         },
         required: ['prompt'],
@@ -47,20 +59,39 @@ export const taskTool = {
         const maxSteps = typeof args.maxSteps === 'number' && args.maxSteps > 0
             ? Math.floor(args.maxSteps)
             : undefined;
+        const mode = args.mode === 'write' ? 'write' : 'read';
+        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 });
+        const result = await spawnAgent({ prompt, tools, maxSteps, signal: ctx?.signal, mode, writeSet, context });
+        let output;
         if (!result.completed) {
-            return t('task.interrupted');
+            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')}`;
         }
-        if (!result.summary) {
-            return t('task.noSummary');
+        else if (!result.summary) {
+            output = t('task.noSummary');
         }
-        // 摘要可能很长,截到 MAX_OUTPUT 保主 history 不爆。
-        const summary = result.summary;
-        if (summary.length > MAX_OUTPUT) {
-            return (summary.slice(0, MAX_OUTPUT) +
-                `\n\n${t('task.summaryTruncated', { count: summary.length - MAX_OUTPUT })}`);
+        else {
+            // 摘要可能很长,截到 MAX_OUTPUT 保主 history 不爆。
+            const summary = [
+                result.summary,
+                `\n[SubAgentResult status=${result.status} tokens=${result.usage.totalTokens} prompt=${result.usage.promptTokens} completion=${result.usage.completionTokens} cached=${result.usage.cachedTokens} readSet=${JSON.stringify(result.readSet)} changeSet=${result.changeSet?.id ?? 'none'} verification=deferred-to-coordinator]`,
+            ].filter(Boolean).join('\n');
+            output = summary.length > MAX_OUTPUT ? (summary.slice(0, MAX_OUTPUT) +
+                `\n\n${t('task.summaryTruncated', { count: summary.length - MAX_OUTPUT })}`) : summary;
         }
-        return summary;
+        const code = result.status === 'aborted'
+            ? 'ABORTED'
+            : result.status === 'conflict'
+                ? 'CHANGE_CONFLICT'
+                : result.completed ? 'OK' : 'EXECUTION_ERROR';
+        const outcome = {
+            status: result.status === 'aborted' ? 'aborted' : result.completed ? 'success' : 'error',
+            code,
+            retryable: false,
+            output,
+            usage: result.usage,
+        };
+        return outcome;
     },
 };