mocode-ai 0.7.1 → 0.7.2

package/dist/agent/index.js

@@ -14,7 +14,7 @@ import { runAgentCore, isMutationTool, } from './core.js';
 import { createPetHooks } from '../pet/state.js';
 import { t } from '../i18n/index.js';
 import { isToolErrorOutput } from '../tools/result.js';
-import { appendCurrentSessionTrace } from '../session/index.js';
+import { appendCurrentSessionTraceEvent } from '../session/index.js';
 /** 当前 turn 的 batch id(runAgent 内闭包变量;一条 turn 一轮 tool batch 结束即清空)。 */
 let currentBatchId = null;
 /** 取 userInput 的首行:字符串直接 split;多模态 parts 找首个 text part 再 split。 */
@@ -229,7 +229,7 @@ onContextUpdate) {
             onContextUpdate,
             hooks: combinedHooks,
             autoValidate: config.autoValidate,
-            onTrace: appendCurrentSessionTrace,
+            onTraceEvent: appendCurrentSessionTraceEvent,
         });
     }
     finally {

package/dist/llm/index.js

@@ -229,6 +229,14 @@ function firstNumber(arr) {
     }
     return undefined;
 }
+function retryErrorCode(error) {
+    if (!error || typeof error !== 'object')
+        return 'RETRYABLE_ERROR';
+    const value = error;
+    if (typeof value.status === 'number')
+        return `HTTP_${value.status}`;
+    return value.code ?? value.name ?? 'RETRYABLE_ERROR';
+}
 /**
  * 流式调一次 LLM:增量回调文本,内部累加 tool_calls 片段。
  * tool_calls 跨 chunk 按 index 累加(id / name / arguments 拼接)。
@@ -254,6 +262,12 @@ toolsOverride) {
                 throw err;
             }
             const wait = computeBackoff(attempt, getRetryAfterMs(err));
+            handlers.onRetry?.({
+                attempt,
+                nextAttempt: attempt + 1,
+                waitMs: wait,
+                code: retryErrorCode(err),
+            });
             logRetry(attempt, err, wait);
             // sleep 自己会在 signal abort 时抛 AbortError——透传,让 runAgentCore 的 catch 按中断处理。
             await sleep(wait, signal);

package/dist/permissions/index.js

@@ -7,7 +7,9 @@ import { config } from '../config/index.js';
 import { getSandboxRoot } from '../sandbox/index.js';
 import { t } from '../i18n/index.js';
 const PERMISSIONS_PATH = path.join(os.homedir(), '.mocode', 'permissions.json');
+const PERMISSIONS_VERSION = 3;
 let permanentGrants = [];
+let permanentToolAllows = new Set();
 let permanentLoaded = false;
 const sessionGrants = [];
 function stable(value) {
@@ -58,16 +60,27 @@ function loadPermanent() {
         permanentGrants = Array.isArray(parsed.grants)
             ? parsed.grants.filter(validGrant).filter((grant) => grant.scope === 'project')
             : [];
+        // Only the explicit v3 field enables broad grants. The retired legacy allowForever
+        // field remains ignored so upgrades cannot silently restore old authorization.
+        permanentToolAllows = parsed.version === PERMISSIONS_VERSION && Array.isArray(parsed.alwaysAllowTools)
+            ? new Set(parsed.alwaysAllowTools.filter((tool) => typeof tool === 'string' && tool.length > 0))
+            : new Set();
     }
     catch {
         permanentGrants = [];
+        permanentToolAllows = new Set();
     }
     return permanentGrants;
 }
 function savePermanent() {
     try {
         fs.mkdirSync(path.dirname(PERMISSIONS_PATH), { recursive: true });
-        fs.writeFileSync(PERMISSIONS_PATH, `${JSON.stringify({ version: 2, grants: permanentGrants }, null, 2)}\n`, 'utf8');
+        const data = {
+            version: PERMISSIONS_VERSION,
+            grants: permanentGrants,
+            alwaysAllowTools: [...permanentToolAllows].sort(),
+        };
+        fs.writeFileSync(PERMISSIONS_PATH, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
     }
     catch {
         // A failed persistence write must never turn into broader authorization.
@@ -98,11 +111,14 @@ export async function checkPermission(tool, args, signal, options = {}) {
         return 'allow';
     if (signal?.aborted)
         return 'deny';
+    loadPermanent();
+    if (permanentToolAllows.has(tool.name))
+        return 'allow';
     const fingerprint = permissionFingerprint(tool, args);
     const projectRoot = canonicalProjectRoot(options.projectRoot ?? getSandboxRoot() ?? process.cwd());
     if (sessionGrants.some((grant) => matches(grant, tool.name, fingerprint, projectRoot)))
         return 'allow';
-    if (loadPermanent().some((grant) => matches(grant, tool.name, fingerprint, projectRoot)))
+    if (permanentGrants.some((grant) => matches(grant, tool.name, fingerprint, projectRoot)))
         return 'allow';
     // CI/pipes must fail closed. Operators can deliberately restore unattended behavior.
     if (!process.stdin.isTTY && !config.permissionNonInteractiveAllow && !options.prompt)
@@ -112,9 +128,10 @@ export async function checkPermission(tool, args, signal, options = {}) {
     const onceOption = t('permission.allow');
     const sessionOption = t('permission.allowSessionResource');
     const projectOption = t('permission.allowProjectResource');
+    const alwaysOption = t('permission.allowForever');
     const denyOption = t('permission.deny');
     const dangerous = getToolRisk(tool) === 'dangerous';
-    const choices = [onceOption, sessionOption, projectOption, denyOption];
+    const choices = [onceOption, sessionOption, projectOption, alwaysOption, denyOption];
     const result = await (options.prompt ?? promptIntervention)({
         type: 'choice',
         title: dangerous
@@ -131,23 +148,44 @@ export async function checkPermission(tool, args, signal, options = {}) {
     }
     else if (result.value === projectOption) {
         const grant = { tool: tool.name, fingerprint, scope: 'project', projectRoot };
-        permanentGrants = loadPermanent().filter((item) => !matches(item, tool.name, fingerprint, projectRoot));
+        permanentGrants = permanentGrants.filter((item) => !matches(item, tool.name, fingerprint, projectRoot));
         permanentGrants.push(grant);
         if (options.persistProjectGrant !== false)
             savePermanent();
     }
+    else if (result.value === alwaysOption) {
+        permanentToolAllows.add(tool.name);
+        if (options.persistProjectGrant !== false)
+            savePermanent();
+    }
     return 'allow';
 }
 export function revokePermanentAllow(toolName, fingerprint) {
-    permanentGrants = loadPermanent().filter((grant) => grant.tool !== toolName || (fingerprint !== undefined && grant.fingerprint !== fingerprint));
+    loadPermanent();
+    permanentGrants = permanentGrants.filter((grant) => grant.tool !== toolName || (fingerprint !== undefined && grant.fingerprint !== fingerprint));
+    if (fingerprint === undefined)
+        permanentToolAllows.delete(toolName);
+    savePermanent();
+}
+export function revokePermanentToolAllow(toolName) {
+    loadPermanent();
+    permanentToolAllows.delete(toolName);
     savePermanent();
 }
 export function listPermanentGrants() {
     return loadPermanent().map((grant) => ({ ...grant }));
 }
-/** Compatibility API: returns tools having at least one project-scoped grant. */
+export function listPermanentToolAllows() {
+    loadPermanent();
+    return [...permanentToolAllows].sort();
+}
+/** Compatibility API: returns tools having any persistent resource or tool-wide grant. */
 export function listPermanentAllow() {
-    return [...new Set(loadPermanent().map((grant) => grant.tool))];
+    loadPermanent();
+    return [...new Set([
+            ...permanentGrants.map((grant) => grant.tool),
+            ...permanentToolAllows,
+        ])].sort();
 }
 export function clearSessionPermissionGrants() {
     sessionGrants.length = 0;
@@ -155,5 +193,6 @@ export function clearSessionPermissionGrants() {
 export function resetPermissionGrantsForTests() {
     sessionGrants.length = 0;
     permanentGrants = [];
+    permanentToolAllows = new Set();
     permanentLoaded = true;
 }

package/dist/repl/index.js

@@ -22,8 +22,8 @@ import { estimateMessagesTokens, reconfigureClient, refreshChatTools, chatTools,
 import { loadImageAttachment, renderChip, MAX_INLINE_BYTES_DEFAULT, } from '../attachments/image.js';
 import { modelSupportsVision } from '../llm/capabilities.js';
 import { computePruneStats } from '../context/relevance.js';
-import { manualCompact, contextState, newSessionId, saveSession, loadSession, listSessions, } from '../session/index.js';
-import { listTurns, planRollback, applyRollback, persistSnapshots, loadSnapshots, rebuildFromHistory, resetState, } from '../rollback/index.js';
+import { manualCompact, contextState, newSessionId, saveSession, loadSession, listSessions, appendCurrentSessionRuntimeEvent, hashTraceValue, } from '../session/index.js';
+import { listTurns, planRollback, applyRollback, persistSnapshots, loadSnapshots, rebuildFromHistory, resetState, getCurrentTurnId, } from '../rollback/index.js';
 import { listSkills, effectiveSystemPrompt, } from '../skills/index.js';
 import { buildMemorySection, buildMemoryIndexSection, kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, loadAll, } from '../memory/index.js';
 import { buildSnapshot, clearSnapshotCache } from '../project-snapshot/index.js';
@@ -396,8 +396,9 @@ function onRunningKey(_str, key) {
             runningInput = '';
             layout.paintRunningInputEcho(runningInput, runningPlaceholder);
         }
-        else {
-            currentAbort?.abort();
+        else if (currentAbort && !currentAbort.signal.aborted) {
+            appendCurrentSessionRuntimeEvent('abort', { phase: 'requested', source: 'keyboard' });
+            currentAbort.abort();
         }
         return;
     }
@@ -876,10 +877,22 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             for (const c of revertable)
                 revertPaths.add(c.path);
         }
-        applyRollback(plan, history, revertPaths);
+        const rolledBackFromTurnId = getCurrentTurnId();
+        const turnCountBeforeRollback = listTurns().length;
+        const rollbackResult = applyRollback(plan, history, revertPaths);
         if (!currentSessionId)
             currentSessionId = newSessionId();
         setCurrentSessionId(currentSessionId, process.cwd()); // 同步到 session/state,确保 notes.md 存在
+        appendCurrentSessionRuntimeEvent('rollback', {
+            status: 'applied',
+            rolledBackFromTurnId,
+            cutoffTurnId: plan.cutoffTurnId,
+            retainedTurns: plan.n,
+            rolledBackTurns: Math.max(0, turnCountBeforeRollback - plan.n),
+            deletedMessages: rollbackResult.deletedMsgs,
+            revertedFiles: rollbackResult.revertedFiles,
+            requestedFileCount: revertPaths.size,
+        }, plan.cutoffTurnId);
         try {
             saveSession(history, currentSessionId, queryHistory);
         }
@@ -1321,6 +1334,15 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             // 返回 SchedulerRunLog 给 UI 显示决策;退化路径(开关关时)在 manualCompact 内部走 compactHistory。
             const log = await manualCompact(history, focus, { force });
             const d = log.compactDetail;
+            appendCurrentSessionRuntimeEvent('compact', {
+                source: 'manual',
+                force,
+                called: log.compactHistoryCalled,
+                reason: d?.reason ?? 'unknown',
+                estimateBefore: d?.estimateBefore,
+                estimateAfter: d?.estimateAfter,
+                focusHash: focus ? hashTraceValue(focus) : undefined,
+            });
             if (!d) {
                 // 兜底(旧调用):只显示 old 文案
                 if (!log.compactHistoryCalled) {

package/dist/rollback/index.js

@@ -114,6 +114,11 @@ export function beginTurn(firstLine) {
     turnIdCounter += 1;
     currentTurnId = turnIdCounter;
     turns.push({ turnId: currentTurnId, firstLine });
+    return currentTurnId;
+}
+/** Stable identity shared by tracing, validation, and rollback for the active main turn. */
+export function getCurrentTurnId() {
+    return currentTurnId;
 }
 /** 单路径工具执行前捕获，不立即记账；失败/no-op 不应出现在 rollback 中。 */
 export function beginPathMutation(p) {

package/dist/session/index.js

@@ -12,4 +12,6 @@ export { compactHistory, maybeCompact, capToolResultForHistory, truncateMid, con
 export { runScheduler, manualCompact, createBudgetScheduler, } from './scheduler.js';
 export { dropContextFromHistory, formatDropResult, } from './drop.js';
 export { newSessionId, saveSession, loadSession, listSessions, sessionDir, } from './persist.js';
-export { appendCurrentSessionTrace } from './trace.js';
+export { appendCurrentSessionTrace, appendCurrentSessionTraceEvent, appendCurrentSessionRuntimeEvent, createTraceEvent, } from './trace.js';
+export { reduceTraceMetrics, readTraceEvents, readTraceMetrics } from './trace-metrics.js';
+export { summarizeToolArguments, hashTraceValue, safeProviderId } from './trace-sanitize.js';

package/dist/session/trace-metrics.js

@@ -0,0 +1,70 @@
+import { readFileSync } from 'node:fs';
+export function reduceTraceMetrics(events) {
+    const ends = events.filter((event) => event.type === 'tool_call_end');
+    let recovered = false;
+    let hadFailure = false;
+    let successes = 0;
+    let toolRetries = 0;
+    let tokens = 0;
+    let hasTokens = false;
+    for (const event of ends) {
+        const status = String(event.data.status ?? 'error');
+        const retry = Number(event.data.retry ?? 0);
+        toolRetries += Number.isFinite(retry) ? retry : 0;
+        if (status === 'success') {
+            successes++;
+            if (hadFailure)
+                recovered = true;
+        }
+        else {
+            hadFailure = true;
+        }
+    }
+    for (const event of events) {
+        if (event.type !== 'model_end')
+            continue;
+        const value = event.data.totalTokens;
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            tokens += value;
+            hasTokens = true;
+        }
+    }
+    const modelRetries = events.filter((event) => event.type === 'model_retry').length;
+    const firstValidation = events.find((event) => event.type === 'validation_end');
+    const turnEnd = [...events].reverse().find((event) => event.type === 'turn_end');
+    return {
+        toolCalls: events.filter((event) => event.type === 'tool_call_start').length,
+        toolFailures: ends.length - successes,
+        toolRecovery: recovered,
+        firstSuccessRate: ends.length ? successes / ends.length : 1,
+        modelRetries,
+        toolRetries,
+        retries: modelRetries + toolRetries,
+        tokens: hasTokens ? tokens : null,
+        durationMs: Number(turnEnd?.data.durationMs ?? 0),
+        firstValidationPassed: firstValidation?.data.status === 'passed',
+    };
+}
+/** Reads event JSONL; malformed/legacy summary lines are ignored. */
+export function readTraceEvents(file) {
+    const events = [];
+    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const value = JSON.parse(line);
+            if (value.schemaVersion === 1 && typeof value.type === 'string' &&
+                typeof value.sessionId === 'string' && typeof value.turnId === 'number' &&
+                value.data && typeof value.data === 'object') {
+                events.push(value);
+            }
+        }
+        catch {
+            // One corrupt best-effort trace line must not hide the remaining run.
+        }
+    }
+    return events;
+}
+export function readTraceMetrics(file) {
+    return reduceTraceMetrics(readTraceEvents(file));
+}

package/dist/session/trace-sanitize.js

@@ -0,0 +1,34 @@
+import { createHash } from 'node:crypto';
+export function hashTraceValue(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+/** Never persists argument values: only shape, size, and a one-way fingerprint. */
+export function summarizeToolArguments(raw) {
+    let keys = [];
+    let parseable = false;
+    try {
+        const parsed = raw.trim() ? JSON.parse(raw) : {};
+        parseable = true;
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            keys = Object.keys(parsed).sort();
+        }
+    }
+    catch {
+        // Invalid arguments are still fingerprinted without retaining their contents.
+    }
+    return {
+        sha256: hashTraceValue(raw),
+        byteLength: Buffer.byteLength(raw, 'utf8'),
+        keys,
+        parseable,
+    };
+}
+/** Provider identity is deliberately reduced to a hostname; credentials/path/query are discarded. */
+export function safeProviderId(baseURL) {
+    try {
+        return new URL(baseURL).hostname.toLowerCase() || 'custom';
+    }
+    catch {
+        return 'custom';
+    }
+}

package/dist/session/trace.js

@@ -1,26 +1,54 @@
+import { randomUUID } from 'node:crypto';
 import { appendFileSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { config } from '../config/index.js';
+import { getCurrentTurnId } from '../rollback/index.js';
 import { getCurrentSessionId } from './state.js';
-function boundedValidation(result) {
-    if (!result)
-        return undefined;
-    const max = 4000;
-    return result.output.length <= max
-        ? result
-        : { ...result, output: `${result.output.slice(0, 2000)}\n…[trace output truncated]…\n${result.output.slice(-1900)}` };
+export function createTraceEvent(input) {
+    return {
+        schemaVersion: 1,
+        eventId: randomUUID(),
+        ts: new Date().toISOString(),
+        ...input,
+    };
 }
-/** Best-effort JSONL trace. Failure must never affect the agent turn. */
-export function appendCurrentSessionTrace(trace) {
-    const sessionId = getCurrentSessionId();
-    if (!sessionId)
-        return;
+function appendTraceLine(sessionId, value) {
     try {
         const dir = path.join(config.sessionDir, sessionId);
         mkdirSync(dir, { recursive: true });
-        appendFileSync(path.join(dir, 'trace.jsonl'), `${JSON.stringify({ ...trace, validation: boundedValidation(trace.validation) })}\n`, 'utf8');
+        appendFileSync(path.join(dir, 'trace.jsonl'), `${JSON.stringify(value)}\n`, 'utf8');
     }
     catch {
         // Observability is best-effort and cannot block coding work.
     }
 }
+/** Persists a typed event in the current session's append-only black-box log. */
+export function appendCurrentSessionTraceEvent(event) {
+    const sessionId = getCurrentSessionId();
+    if (!sessionId)
+        return;
+    appendTraceLine(sessionId, { ...event, sessionId });
+}
+/** Records events initiated outside runAgentCore, such as Ctrl+C, /compact, and /rollback. */
+export function appendCurrentSessionRuntimeEvent(type, data, turnId = getCurrentTurnId()) {
+    const sessionId = getCurrentSessionId();
+    if (!sessionId)
+        return;
+    appendTraceLine(sessionId, createTraceEvent({ sessionId, turnId, type, data }));
+}
+/** Legacy turn-summary sink retained for API compatibility. New production code writes events. */
+export function appendCurrentSessionTrace(trace) {
+    const sessionId = getCurrentSessionId();
+    if (!sessionId)
+        return;
+    const validation = trace.validation
+        ? {
+            status: trace.validation.status,
+            level: trace.validation.level,
+            durationMs: trace.validation.durationMs,
+            verificationComplete: trace.validation.verificationComplete,
+            fingerprint: trace.validation.fingerprint,
+        }
+        : undefined;
+    appendTraceLine(sessionId, { ...trace, sessionId, validation });
+}

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

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { verifyWrittenFile } from '../../verification/postconditions.js';
 // ---------- edit_file ----------
 export const editFileTool = {
     name: 'edit_file',
@@ -39,6 +40,17 @@ export const editFileTool = {
         // 检测原始行尾风格,写回时还原(存在 \r\n 即视为 CRLF 文件;纯 LF 文件保持 LF)
         const out = data.includes('\r\n') ? updated.replace(/\n/g, '\r\n') : updated;
         await writeFile(full, out, 'utf8');
-        return `已在 ${path} 中完成 1 处替换。`;
+        const postcondition = await verifyWrittenFile(full, out);
+        if (postcondition.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'),
+            };
+        }
+        return `已在 ${path} 中完成 1 处替换 (sha256=${postcondition.actualHash})。`;
     },
 };

package/dist/tools/builtins/index.js

@@ -69,8 +69,15 @@ 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 },
-    // 子 Agent 共享主工作区；在隔离 workspace / write-set 锁实现前必须串行。
-    task: { effect: 'write', concurrency: 'serial', retry: 'never', resources: workspaceResource, supportsAbort: true },
+    // task 只编排子 Agent；真实读写由子调用自行持锁，父调用不得包 workspace 锁。
+    task: {
+        effect: 'write',
+        concurrency: 'serial',
+        retry: 'never',
+        resources: workspaceResource,
+        delegatesResourceLocks: true,
+        supportsAbort: true,
+    },
 };
 const rawBuiltinTools = [
     readFileTool,

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

@@ -1,5 +1,6 @@
 import { writeFile, mkdir } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
+import { verifyWrittenFile } from '../../verification/postconditions.js';
 // ---------- write_file ----------
 export const writeFileTool = {
     name: 'write_file',
@@ -19,6 +20,17 @@ export const writeFileTool = {
         const full = resolve(path);
         await mkdir(dirname(full), { recursive: true });
         await writeFile(full, content, 'utf8');
-        return `已写入 ${path} (${content.length} 字符)`;
+        const postcondition = await verifyWrittenFile(full, content);
+        if (postcondition.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'),
+            };
+        }
+        return `已写入 ${path} (${content.length} 字符, sha256=${postcondition.actualHash})`;
     },
 };

package/dist/tools/registry.js

@@ -1,6 +1,7 @@
 import { builtinTools } from './builtins/index.js';
 import { beginPathMutation, beginWorkspaceMutation, endPathMutation, endWorkspaceMutation, getCurrentTurnMutationState, } from '../rollback/index.js';
 import { enforceSandbox } from '../sandbox/index.js';
+import { resolveResourceLockRequests, toolResourceLockManager } from './resource-lock.js';
 import { t } from '../i18n/index.js';
 import { isToolErrorOutput } from './result.js';
 /**
@@ -115,45 +116,63 @@ export async function executeToolOutcome(name, argsRaw, signal, opts) {
         return terminalOutcome('error', 'INVALID_JSON', t('toolError.invalidJson', { name, arguments: argsRaw }), startedAt);
     }
     const capabilities = getToolCapabilities(tool);
-    const mutationBefore = getCurrentTurnMutationState();
+    let mutationVersionBefore;
+    let capturedPath;
     try {
         const sandboxError = enforceSandbox(name, args);
         if (sandboxError) {
             return terminalOutcome('denied', 'SANDBOX_DENIED', sandboxError, startedAt);
         }
-        const pathCapture = isFileMutationTool(name) && typeof args.path === 'string' && args.path
-            ? beginPathMutation(args.path)
-            : null;
-        // 进程和未知扩展可能间接改动任意文件；已声明 write 的非文件工具自行管理其状态。
-        const workspaceCapture = capabilities.effect === 'process' || capabilities.effect === 'unknown'
-            ? beginWorkspaceMutation()
-            : null;
-        let raw;
-        try {
-            raw = await tool.execute(args, {
-                signal,
-                dropContext: opts?.dropContext,
-            });
-        }
-        finally {
-            if (pathCapture)
-                endPathMutation(pathCapture, name);
-            if (workspaceCapture)
-                endWorkspaceMutation(workspaceCapture, name);
-        }
-        const mutationAfter = getCurrentTurnMutationState();
-        const changedFiles = mutationAfter.version !== mutationBefore.version
-            ? mutationAfter.changedFiles.map((item) => item.path)
-            : [];
-        if (signal?.aborted) {
-            return terminalOutcome('aborted', 'ABORTED', String(isStructuredOutcome(raw) ? raw.output : raw), startedAt, changedFiles);
-        }
-        return normalizeOutcome(raw, capabilities, Date.now() - startedAt, changedFiles);
+        const requests = resolveResourceLockRequests(capabilities, args);
+        return await toolResourceLockManager.withLocks(requests, signal, async () => {
+            // Diff 等执行前观察必须发生在真正持锁之后；同路径排队调用才能看到前序写入结果。
+            opts?.onLockAcquired?.(args);
+            const mutationBefore = getCurrentTurnMutationState();
+            mutationVersionBefore = mutationBefore.version;
+            const pathCapture = isFileMutationTool(name) && typeof args.path === 'string' && args.path
+                ? beginPathMutation(args.path)
+                : null;
+            capturedPath = pathCapture?.path;
+            // 进程和未知扩展可能间接改动任意文件；其 workspace lock 同时隔离全盘捕获。
+            const workspaceCapture = capabilities.effect === 'process' || capabilities.effect === 'unknown'
+                ? beginWorkspaceMutation()
+                : null;
+            let raw;
+            try {
+                raw = await tool.execute(args, {
+                    signal,
+                    dropContext: opts?.dropContext,
+                });
+            }
+            finally {
+                if (pathCapture)
+                    endPathMutation(pathCapture, name);
+                if (workspaceCapture)
+                    endWorkspaceMutation(workspaceCapture, name);
+            }
+            const mutationAfter = getCurrentTurnMutationState();
+            const changedFiles = mutationAfter.version !== mutationBefore.version
+                ? pathCapture
+                    ? mutationAfter.changedFiles
+                        .filter((item) => item.path === pathCapture.path)
+                        .map((item) => item.path)
+                    : mutationAfter.changedFiles.map((item) => item.path)
+                : [];
+            if (signal?.aborted) {
+                return terminalOutcome('aborted', 'ABORTED', String(isStructuredOutcome(raw) ? raw.output : raw), startedAt, changedFiles);
+            }
+            return normalizeOutcome(raw, capabilities, Date.now() - startedAt, changedFiles);
+        });
     }
     catch (error) {
         const mutationAfter = getCurrentTurnMutationState();
-        const changedFiles = mutationAfter.version !== mutationBefore.version
-            ? mutationAfter.changedFiles.map((item) => item.path)
+        const changedFiles = mutationVersionBefore !== undefined &&
+            mutationAfter.version !== mutationVersionBefore
+            ? capturedPath
+                ? mutationAfter.changedFiles
+                    .filter((item) => item.path === capturedPath)
+                    .map((item) => item.path)
+                : mutationAfter.changedFiles.map((item) => item.path)
             : [];
         if (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {
             return terminalOutcome('aborted', 'ABORTED', t('command.interrupted'), startedAt, changedFiles);