mocode-ai 0.7.2 → 1.0.1

package/dist/rollback/index.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { config } from '../config/index.js';
@@ -52,6 +53,11 @@ function readState(full) {
 function sameState(a, b) {
     return a.kind === b.kind && a.data === b.data && a.mode === b.mode;
 }
+function stateFingerprint(state) {
+    return createHash('sha256')
+        .update(JSON.stringify([state.kind, state.data ?? null, state.mode ?? null]))
+        .digest('hex');
+}
 function stateFromSnapshot(snapshot) {
     if (snapshot.kind) {
         return { kind: snapshot.kind, data: snapshot.before ?? undefined, mode: snapshot.mode };
@@ -64,7 +70,7 @@ function stateFromSnapshot(snapshot) {
         data: Buffer.from(snapshot.before, 'utf8').toString('base64'),
     };
 }
-function snapshotFromState(rel, state, sequence, op, createdParents = []) {
+function snapshotFromState(rel, state, sequence, op, createdParents = [], after) {
     return {
         turnId: currentTurnId,
         path: rel,
@@ -75,6 +81,7 @@ function snapshotFromState(rel, state, sequence, op, createdParents = []) {
         sequence,
         ops: [op],
         createdParents: createdParents.length > 0 ? createdParents : undefined,
+        afterFingerprint: after ? stateFingerprint(after) : undefined,
     };
 }
 /** 同轮同路径只保留最早的 before；后续实际改动仅合并工具名。 */
@@ -90,11 +97,15 @@ function addSnapshot(next) {
     const existingSequence = existing.sequence ?? Number.MAX_SAFE_INTEGER;
     const nextSequence = next.sequence ?? Number.MAX_SAFE_INTEGER;
     const ops = new Set([...(existing.ops ?? []), ...(next.ops ?? [])]);
+    const latestAfterFingerprint = nextSequence >= existingSequence
+        ? next.afterFingerprint
+        : existing.afterFingerprint;
     if (nextSequence < existingSequence) {
-        snapshots[existingIndex] = { ...next, ops: [...ops] };
+        snapshots[existingIndex] = { ...next, ops: [...ops], afterFingerprint: latestAfterFingerprint };
     }
     else {
         existing.ops = [...ops];
+        existing.afterFingerprint = latestAfterFingerprint;
     }
 }
 function missingParents(full) {
@@ -139,14 +150,14 @@ export function endPathMutation(capture, op) {
     const after = readState(full);
     if (!sameState(capture.before, after)) {
         changed = true;
-        addSnapshot(snapshotFromState(capture.path, capture.before, capture.sequence, op, capture.createdParents));
+        addSnapshot(snapshotFromState(capture.path, capture.before, capture.sequence, op, capture.createdParents, after));
     }
     // write_file 会递归创建父目录；即使最终写文件失败，这些目录也是本轮真实副作用。
     for (const parentRel of capture.createdParents) {
         const parent = safeFullPath(parentRel);
         if (parent && readState(parent).kind !== 'missing') {
             changed = true;
-            addSnapshot(snapshotFromState(parentRel, { kind: 'missing' }, capture.sequence, op));
+            addSnapshot(snapshotFromState(parentRel, { kind: 'missing' }, capture.sequence, op, [], readState(parent)));
         }
     }
     if (changed)
@@ -202,7 +213,7 @@ export function endWorkspaceMutation(capture, op) {
         if (sameState(beforeState, afterState))
             continue;
         changed = true;
-        addSnapshot(snapshotFromState(rel, beforeState, capture.sequence, op));
+        addSnapshot(snapshotFromState(rel, beforeState, capture.sequence, op, [], afterState));
     }
     if (changed)
         mutationVersion += 1;
@@ -285,7 +296,11 @@ function restoreSnapshot(snapshot) {
     const state = stateFromSnapshot(snapshot);
     try {
         if (state.kind === 'missing') {
-            rmSync(full, { recursive: true, force: true });
+            const current = readState(full);
+            if (current.kind === 'directory')
+                rmdirSync(full);
+            else
+                rmSync(full, { recursive: false, force: true });
             for (const parentRel of snapshot.createdParents ?? []) {
                 const parent = safeFullPath(parentRel);
                 if (!parent)
@@ -329,9 +344,16 @@ export function applyRollback(plan, history, revertPaths) {
     const deletedMsgs = history.length - plan.cutoffIndex;
     history.length = plan.cutoffIndex;
     const picks = new Map();
+    const latest = new Map();
     for (const snapshot of snapshots) {
         if (snapshot.turnId <= plan.cutoffTurnId || !revertPaths.has(snapshot.path))
             continue;
+        const latestSnapshot = latest.get(snapshot.path);
+        if (!latestSnapshot || snapshot.turnId > latestSnapshot.turnId ||
+            (snapshot.turnId === latestSnapshot.turnId &&
+                (snapshot.sequence ?? -1) > (latestSnapshot.sequence ?? -1))) {
+            latest.set(snapshot.path, snapshot);
+        }
         const existing = picks.get(snapshot.path);
         if (!existing ||
             snapshot.turnId < existing.turnId ||
@@ -341,7 +363,18 @@ export function applyRollback(plan, history, revertPaths) {
             picks.set(snapshot.path, snapshot);
         }
     }
-    const selected = [...picks.values()];
+    const selected = [];
+    const conflictedFiles = [];
+    for (const snapshot of picks.values()) {
+        const expected = latest.get(snapshot.path)?.afterFingerprint;
+        const full = safeFullPath(snapshot.path);
+        if (expected && (!full || stateFingerprint(readState(full)) !== expected)) {
+            conflictedFiles.push(snapshot.path);
+        }
+        else {
+            selected.push(snapshot);
+        }
+    }
     // 先深到浅删除本轮新建项，再浅到深恢复原目录/文件。
     const removals = selected
         .filter((item) => stateFromSnapshot(item).kind === 'missing')
@@ -353,11 +386,13 @@ export function applyRollback(plan, history, revertPaths) {
     for (const snapshot of [...removals, ...restores]) {
         if (restoreSnapshot(snapshot))
             revertedFiles.push(snapshot.path);
+        else if (!conflictedFiles.includes(snapshot.path))
+            conflictedFiles.push(snapshot.path);
     }
     turns = turns.filter((turn) => turn.turnId <= plan.cutoffTurnId);
     snapshots = snapshots.filter((snapshot) => snapshot.turnId <= plan.cutoffTurnId);
     currentTurnId = turns.at(-1)?.turnId ?? 0;
-    return { deletedMsgs, revertedFiles };
+    return { deletedMsgs, revertedFiles, conflictedFiles };
 }
 export function pruneAfterCompaction(history) {
     const count = history.filter((message) => message.role === 'user').length;

package/dist/sandbox/index.js

@@ -1,5 +1,5 @@
 // 沙箱子系统 barrel。叶子:仅 node:path / node:fs,不反向依赖业务。
-export { getSandboxRoot, setSandboxRoot } from './root.js';
+export { getSandboxRoot, setSandboxRoot, withSandboxRoot } from './root.js';
 export { jailResolve, jailGlobPattern, isInsideRoot } from './jail.js';
 export { filterEnv, isCommandDenied } from './command.js';
 export { SANDBOX_EXEMPT_TOOLS, SANDBOX_PATH_TOOLS, enforceSandbox, } from './policy.js';

package/dist/sandbox/policy.js

@@ -8,7 +8,7 @@ import { jailResolve, jailGlobPattern } from './jail.js';
  *  - web_*:跨网络,非文件路径
  *  - ask_human / switch_mode:无文件路径
  *  - codegraph:只读 cwd 下 .codegraph/ 索引(只读、不写盘)
- *  - task:派生子 agent,继承全局 root(子 agent 同进程天然共享 getSandboxRoot)
+ *  - sub-agent:派生子 agent，通过 scoped sandbox root 使用隔离 overlay
  */
 export const SANDBOX_EXEMPT_TOOLS = new Set([
     'memory_save', 'memory_update', 'memory_forget', 'memory_search', 'memory_list',
@@ -16,7 +16,7 @@ export const SANDBOX_EXEMPT_TOOLS = new Set([
     'web_search', 'web_fetch',
     'ask_human', 'switch_mode',
     'codegraph',
-    'task',
+    'sub-agent',
 ]);
 /**
  * 路径类工具:enforceSandbox 集中把 args.path 重写为牢内绝对路径(默认安全;工具内

package/dist/sandbox/root.js

@@ -3,12 +3,18 @@
 // —— 全是「业务 → 叶子」,同 src/agent/mode.ts。
 //
 // 设计:sandboxRoot 是纯边界记录(默认 = process.cwd(),不 chdir),避免与 config.sessionDir 等
-// 模块加载期计算的值产生错位(若 chdir 会令那些值变陈旧)。子 agent 同进程天然继承全局 root
-// (未来 agents/ 做 worktree 隔离时再改为沿 opts 透传,照 signal 同形链路,7 处改动)。
+// 模块加载期计算的值产生错位(若 chdir 会令那些值变陈旧)。主 Agent 使用全局 root，
+// 并发子 Agent 通过 AsyncLocalStorage 获得互不干扰的 overlay root。
+import { AsyncLocalStorage } from 'node:async_hooks';
 let currentRoot = null;
+const scopedRoots = new AsyncLocalStorage();
 /** 当前沙箱根(绝对路径)。未初始化返 null,调用方 ?? process.cwd() 兜底(防御)。 */
 export function getSandboxRoot() {
-    return currentRoot;
+    return scopedRoots.getStore() ?? currentRoot;
+}
+/** Run one asynchronous agent against an isolated sandbox without changing sibling roots. */
+export function withSandboxRoot(root, run) {
+    return scopedRoots.run(root, run);
 }
 /** 设置沙箱根。repl startRepl 启动时调一次(默认 process.cwd();--sandbox-root / SANDBOX_ROOT 可覆盖)。
  *  返回之前的值,供未来 save/restore(子 agent worktree 隔离)用。 */

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,56 +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 `错误:在 ${path} 中未找到 old_string。不要重试相同参数；请先 read_file 读取目标区域，再从返回内容逐字复制新的 old_string 后重试。`;
+            return conflict(file, 'old_string 未找到；请重新 read_file 并复制最新内容。');
         }
         if (count > 1) {
-            return `错误:old_string 在 ${path} 中出现 ${count} 次,不唯一。请加入更多上下文使其唯一。`;
+            return conflict(file, `old_string 出现 ${count} 次；请增加上下文使其唯一。`);
         }
-        // 用函数形式替换,避免 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') {
+        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'}。请重新读取后再编辑。`);
+        }
+        if (result.status === 'failed') {
             return {
                 status: 'error',
-                code: 'POSTCONDITION_FAILED',
-                retryable: true,
-                output: postcondition.diagnostics
-                    .map((item) => `[${item.code ?? 'V0_FAILED'}] ${item.file ?? path}: ${item.message}`)
-                    .join('\n'),
+                code: 'EXECUTION_ERROR',
+                retryable: false,
+                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) => ({