minimal-agent 0.18.8 → 0.18.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.18.8",
+  "version": "0.18.9",
   "description": "Bun-first 的本地 Agent 内核，支持工具、插件、工作流、上下文压缩、长期记忆与 OpenAI 兼容接口；Tauri 桌面宿主和 Node.js npm 发布可复用同一内核",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/src/loop.js

@@ -69,6 +69,7 @@ import { createAgentRuntimeContext, } from './runtime/agentRuntimeContext.js';
 import { stripThinkBlocks } from './utils/stripThink.js';
 import { orderedPool } from './runtime/orderedPool.js';
 import { takeAgentNotifications, agentCoordinationContext } from './tools/agent/agentTaskService.js';
+import { delegationRuntimeGuidance } from './prompts/delegation.js';
 import { executionSegments } from './tools/executionSegments.js';
 import { acquireSubagentLease, normalizeWriteScopes } from './tools/agent/coordinator.js';
 const DELIVERY_ARTIFACT = '(?:文件|合同|协议|方案|文档|表格|报告|图片|图像|海报|幻灯片|PPT|PDF|代码|脚本|压缩包|网页|页面|HTML|DOCX|XLSX|CSV|ZIP)';
@@ -239,6 +240,8 @@ export async function* runQuery(userInput, options) {
     let resultPresented = false;
     let presentedResultUnverified = false;
     let deliveryCorrectionAttempted = false;
+    let emptyResponseRecoveryAttempted = false;
+    let emptyResponseRecoveryReason = '';
     let askCorrectionAttempted = false;
     let diagramPreparationAttempted = false;
     const output = resolveOutputContract(runtimeContext.surface, runtimeContext.output);
@@ -326,9 +329,13 @@ export async function* runQuery(userInput, options) {
         const parts = [
             transientFor(activeTools),
             coordinationText,
+            delegationRuntimeGuidance({ available: runtimeContext.profile === 'main' && currentEffectiveToolSet.names.has('Agent'),
+                maxConcurrent: subagents.maxConcurrent, callsUsed: toolCallContext.agentCalls?.used ?? 0,
+                maxCalls: toolCallContext.agentCalls?.max ?? 0 }),
             diagramPreparationAttempted ? visualPresentation(output) : '',
             delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
             askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
+            emptyResponseRecoveryAttempted ? `上一次模型响应没有可交付正文（${emptyResponseRecoveryReason}）。请基于已有历史和工具结果继续完成任务：信息充分则给出实质结论，不充分则继续必要操作或明确缺口。不要重复已经完成的调查或有副作用的操作；不要把未完成的任务说成完成。已有顾问意见继续有效，无需仅因恢复而再次咨询。` : '',
             deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
             advisorAvailable ? advisorCoordinator.transientReminder() : '',
             advisorAvailable
@@ -692,16 +699,24 @@ export async function* runQuery(userInput, options) {
                 requiredNames: [...effectiveToolSet.requiredNames],
             });
         advisorCoordinator.setAvailable(currentEffectiveToolSet.names.has('Advisor'));
+        // Tool availability may change during emergency fitting. Rebuild dynamic
+        // guidance against the actual request boundary, then account for its size.
+        requestTransientContext = buildRequestTransientContext();
+        lastRequestTransientContext = requestTransientContext;
+        const finalRequestBudget = buildContextBudgetPlan({
+            provider, history, tools: currentEffectiveToolSet.tools,
+            transientContext: requestTransientContext,
+        });
         if (emergencyFit.removedNames.length > 0) {
             yield {
                 type: 'warning',
                 message: `当前模型窗口压力过高，本次请求临时省略工具 Schema：${emergencyFit.removedNames.join(', ')}；下一轮会重新评估并恢复。`,
             };
         }
-        if (emergencyFit.plan.overBudget) {
+        if (finalRequestBudget.overBudget) {
             yield {
                 type: 'error',
-                error: `当前请求即使经过上下文降级仍需要约 ${emergencyFit.plan.totalInputTokens} tokens，超过模型输入上限 ${emergencyFit.plan.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
+                error: `当前请求即使经过上下文降级仍需要约 ${finalRequestBudget.totalInputTokens} tokens，超过模型输入上限 ${finalRequestBudget.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
                 code: 'context_overflow',
             };
             yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('error') };
@@ -999,8 +1014,19 @@ export async function* runQuery(userInput, options) {
                     yield { type: 'warning', message: '已达到本轮执行上限，顾问交付检查尚未完成；不能把此次输出视为已复核。' };
             }
             if (emptyResponse) {
-                // A no-tool response is already the model's terminal signal. Do not turn it
-                // into another model round, and do not persist/broadcast an empty bubble.
+                // Recover once within the existing turn budget, retaining tool receipts and
+                // advisor state. Never replay tools or expose an empty candidate as an answer.
+                if (!resultPresented && !emptyResponseRecoveryAttempted && turn < maxTurns) {
+                    emptyResponseRecoveryAttempted = true;
+                    emptyResponseRecoveryReason = lastFinishReason === 'length'
+                        ? '输出额度耗尽' : lastFinishReason === 'unknown'
+                        ? '响应流缺少正常结束状态' : '响应为空或仅含思考内容';
+                    const message = { role: 'system', content: '正在恢复回答，已保留调查结果与工作进展。',
+                        id: crypto.randomUUID(), timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+                    history.push(message);
+                    yield { type: 'injected_message', message };
+                    continue;
+                }
                 yield* retireDraft('empty_response');
             }
             else {
@@ -1162,7 +1188,9 @@ export async function* runQuery(userInput, options) {
                 trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
             };
             if (emptyResponse && !resultPresented) {
-                const warning = '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
+                const warning = emptyResponseRecoveryAttempted
+                    ? '自动恢复后仍未生成最终答复，已有进展已保留。可以继续本轮或检查模型服务。'
+                    : '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
                 yield { type: 'warning', message: warning };
                 yield { type: 'turn_done', completionStatus: 'no_answer', warning, usage };
             }

package/src/loop.ts

@@ -113,6 +113,7 @@ import {
 import { stripThinkBlocks } from './utils/stripThink.js';
 import { orderedPool } from './runtime/orderedPool.js';
 import { takeAgentNotifications, agentCoordinationContext } from './tools/agent/agentTaskService.js';
+import { delegationRuntimeGuidance } from './prompts/delegation.js';
 import { executionSegments } from './tools/executionSegments.js';
 import { acquireSubagentLease, normalizeWriteScopes } from './tools/agent/coordinator.js';
 
@@ -449,6 +450,8 @@ export async function* runQuery(
   let resultPresented = false;
   let presentedResultUnverified = false;
   let deliveryCorrectionAttempted = false;
+  let emptyResponseRecoveryAttempted = false;
+  let emptyResponseRecoveryReason = '';
   let askCorrectionAttempted = false;
   let diagramPreparationAttempted = false;
   const output = resolveOutputContract(runtimeContext.surface, runtimeContext.output);
@@ -539,9 +542,13 @@ export async function* runQuery(
     const parts = [
       transientFor(activeTools),
       coordinationText,
+      delegationRuntimeGuidance({ available: runtimeContext.profile === 'main' && currentEffectiveToolSet.names.has('Agent'),
+        maxConcurrent: subagents.maxConcurrent, callsUsed: toolCallContext.agentCalls?.used ?? 0,
+        maxCalls: toolCallContext.agentCalls?.max ?? 0 }),
       diagramPreparationAttempted ? visualPresentation(output) : '',
       delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
       askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
+      emptyResponseRecoveryAttempted ? `上一次模型响应没有可交付正文（${emptyResponseRecoveryReason}）。请基于已有历史和工具结果继续完成任务：信息充分则给出实质结论，不充分则继续必要操作或明确缺口。不要重复已经完成的调查或有副作用的操作；不要把未完成的任务说成完成。已有顾问意见继续有效，无需仅因恢复而再次咨询。` : '',
       deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
       advisorAvailable ? advisorCoordinator.transientReminder() : '',
       advisorAvailable
@@ -917,16 +924,24 @@ export async function* runQuery(
     advisorCoordinator.setAvailable(
       currentEffectiveToolSet.names.has('Advisor'),
     );
+    // Tool availability may change during emergency fitting. Rebuild dynamic
+    // guidance against the actual request boundary, then account for its size.
+    requestTransientContext = buildRequestTransientContext();
+    lastRequestTransientContext = requestTransientContext;
+    const finalRequestBudget = buildContextBudgetPlan({
+      provider, history, tools: currentEffectiveToolSet.tools,
+      transientContext: requestTransientContext,
+    });
     if (emergencyFit.removedNames.length > 0) {
       yield {
         type: 'warning',
         message: `当前模型窗口压力过高，本次请求临时省略工具 Schema：${emergencyFit.removedNames.join(', ')}；下一轮会重新评估并恢复。`,
       };
     }
-    if (emergencyFit.plan.overBudget) {
+    if (finalRequestBudget.overBudget) {
       yield {
         type: 'error',
-        error: `当前请求即使经过上下文降级仍需要约 ${emergencyFit.plan.totalInputTokens} tokens，超过模型输入上限 ${emergencyFit.plan.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
+        error: `当前请求即使经过上下文降级仍需要约 ${finalRequestBudget.totalInputTokens} tokens，超过模型输入上限 ${finalRequestBudget.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
         code: 'context_overflow',
       };
       yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('error') };
@@ -1224,8 +1239,19 @@ export async function* runQuery(
         if (!deliveryCheckpoint.allow) yield { type: 'warning', message: '已达到本轮执行上限，顾问交付检查尚未完成；不能把此次输出视为已复核。' };
       }
       if (emptyResponse) {
-        // A no-tool response is already the model's terminal signal. Do not turn it
-        // into another model round, and do not persist/broadcast an empty bubble.
+        // Recover once within the existing turn budget, retaining tool receipts and
+        // advisor state. Never replay tools or expose an empty candidate as an answer.
+        if (!resultPresented && !emptyResponseRecoveryAttempted && turn < maxTurns) {
+          emptyResponseRecoveryAttempted = true;
+          emptyResponseRecoveryReason = lastFinishReason === 'length'
+            ? '输出额度耗尽' : lastFinishReason === 'unknown'
+              ? '响应流缺少正常结束状态' : '响应为空或仅含思考内容';
+          const message: Message = { role: 'system', content: '正在恢复回答，已保留调查结果与工作进展。',
+            id: crypto.randomUUID(), timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+          history.push(message);
+          yield { type: 'injected_message', message };
+          continue;
+        }
         yield* retireDraft('empty_response');
       } else {
         // Publication is a separate tool-free request. Nothing from preparation
@@ -1375,7 +1401,9 @@ export async function* runQuery(
         trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
       };
       if (emptyResponse && !resultPresented) {
-        const warning = '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
+        const warning = emptyResponseRecoveryAttempted
+          ? '自动恢复后仍未生成最终答复，已有进展已保留。可以继续本轮或检查模型服务。'
+          : '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
         yield { type: 'warning', message: warning };
         yield { type: 'turn_done', completionStatus: 'no_answer', warning, usage };
       } else if (pendingDelegations.length) {

package/src/memory/factLearning.js

@@ -2,7 +2,7 @@
  * its source material. A durable receipt makes retries idempotent. */
 import { readFile } from 'node:fs/promises';
 import { parseMemoryProposal } from './proposal.js';
-import { failureSchema, jobEligible, recordJobFailure, reportLearningFailure } from './jobPolicy.js';
+import { failureSchema, jobEligible, recordJobFailure, recordBackgroundLearningFailure } from './jobPolicy.js';
 import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { z } from 'zod';
@@ -437,7 +437,7 @@ export function scheduleFactLearning(options) {
     void runFactLearning(options)
         .catch((error) => {
         if (!options.signal?.aborted)
-            reportLearningFailure(directory(options.workspaceId));
+            recordBackgroundLearningFailure(options.workspaceId, 'facts', 'learning');
     })
         .finally(async () => {
         const settings = await memoryService.settings();
@@ -453,7 +453,7 @@ export function scheduleFactLearning(options) {
         if (pending.length)
             wakeAt(directory(options.workspaceId), Math.max(Date.now() + 1000, Math.min(...pending.map((turn) => turn.nextAttemptAt ?? Date.now()))), () => scheduleFactLearning({ ...options, force: false }), options.signal);
     })
-        .catch((error) => process.stderr.write(`[minimal-agent memory] 恢复调度失败：${error.message}\n`));
+        .catch(() => recordBackgroundLearningFailure(options.workspaceId, 'facts', 'scheduling'));
 }
 export async function drainFactLearning() {
     await Promise.allSettled([...running.values()].map((task) => task.promise));

package/src/memory/factLearning.ts

@@ -2,7 +2,7 @@
  * its source material. A durable receipt makes retries idempotent. */
 import { readFile } from 'node:fs/promises';
 import { parseMemoryProposal } from './proposal.js';
-import { failureSchema, jobEligible, recordJobFailure, reportLearningFailure } from './jobPolicy.js';
+import { failureSchema, jobEligible, recordJobFailure, recordBackgroundLearningFailure } from './jobPolicy.js';
 import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { z } from 'zod';
@@ -574,7 +574,7 @@ export function scheduleFactLearning(
   void runFactLearning(options)
     .catch((error) => {
       if (!options.signal?.aborted)
-        reportLearningFailure(directory(options.workspaceId));
+        recordBackgroundLearningFailure(options.workspaceId, 'facts', 'learning');
     })
     .finally(async () => {
       const settings = await memoryService.settings();
@@ -604,11 +604,7 @@ export function scheduleFactLearning(
           options.signal,
         );
     })
-    .catch((error) =>
-      process.stderr.write(
-        `[minimal-agent memory] 恢复调度失败：${error.message}\n`,
-      ),
-    );
+    .catch(() => recordBackgroundLearningFailure(options.workspaceId, 'facts', 'scheduling'));
 }
 export async function drainFactLearning() {
   await Promise.allSettled([...running.values()].map((task) => task.promise));

package/src/memory/jobPolicy.js

@@ -13,23 +13,31 @@ export function recordJobFailure(job, error) {
         : /VERSION_CONFLICT|SOURCE_CHANGED/.test(message) ? 'conflict'
             : /timeout|超时|429|503|fetch|network|ECONN|连接/i.test(message) ? 'transient'
                 : 'unknown';
-    const consecutive = job.failure?.kind === kind ? job.failure.consecutive + 1 : 1;
+    // Changing failure categories is not recovery. Otherwise alternating provider
+    // and proposal failures can keep a source retrying forever.
+    const consecutive = (job.failure?.consecutive ?? 0) + 1;
     job.attempts = (job.attempts ?? 0) + 1;
-    job.failure = { kind, consecutive, paused: consecutive >= (kind === 'proposal' ? 3 : 6) };
+    job.failure = { kind, consecutive, paused: Boolean(job.failure?.paused) || consecutive >= (kind === 'proposal' ? 3 : 6) };
     job.nextAttemptAt = retryAt(consecutive);
 }
 export function jobEligible(job, force = false, now = Date.now()) {
     return force || (!job.failure?.paused && (job.nextAttemptAt ?? 0) <= now);
 }
-const notices = new Map();
-/** No raw provider response, quotes, or repeated terminal floods. Durable job
- * state retains the failure category and can be resumed with a forced run. */
-export function reportLearningFailure(key) {
-    const now = Date.now();
-    if (now - (notices.get(key) ?? 0) < 300_000)
-        return;
-    notices.set(key, now);
-    if (notices.size > 128)
-        notices.delete(notices.keys().next().value);
-    process.stderr.write('[minimal-agent memory] 后台学习未完成，资料已保留；可通过 MemoryMaintenance status 查看、run 重试。重复失败将暂停自动重试。\n');
+const health = new Map();
+/** Background services never write over a host's TUI. Durable queues retain
+ * source failures; this bounded process snapshot also exposes scheduler/IO errors
+ * that could not be persisted. No source text, paths or provider secrets. */
+export function recordBackgroundLearningFailure(workspaceId, partition, phase) {
+    const key = `${workspaceId}:${partition}`;
+    const previous = health.get(key);
+    health.delete(key);
+    health.set(key, { partition, phase, failures: (previous?.failures ?? 0) + 1, at: Date.now() });
+    if (health.size > 128)
+        health.delete(health.keys().next().value);
+}
+export function backgroundLearningHealth(workspaceId) {
+    return ['facts', 'experience'].flatMap(partition => {
+        const value = health.get(`${workspaceId}:${partition}`);
+        return value ? [{ ...value }] : [];
+    });
 }

package/src/memory/jobPolicy.ts

@@ -16,9 +16,11 @@ export function recordJobFailure(job: Job, error: unknown): void {
     : /VERSION_CONFLICT|SOURCE_CHANGED/.test(message) ? 'conflict'
     : /timeout|超时|429|503|fetch|network|ECONN|连接/i.test(message) ? 'transient'
     : 'unknown';
-  const consecutive = job.failure?.kind === kind ? job.failure.consecutive + 1 : 1;
+  // Changing failure categories is not recovery. Otherwise alternating provider
+  // and proposal failures can keep a source retrying forever.
+  const consecutive = (job.failure?.consecutive ?? 0) + 1;
   job.attempts = (job.attempts ?? 0) + 1;
-  job.failure = { kind, consecutive, paused: consecutive >= (kind === 'proposal' ? 3 : 6) };
+  job.failure = { kind, consecutive, paused: Boolean(job.failure?.paused) || consecutive >= (kind === 'proposal' ? 3 : 6) };
   job.nextAttemptAt = retryAt(consecutive);
 }
 
@@ -26,13 +28,22 @@ export function jobEligible(job: Job, force = false, now = Date.now()): boolean
   return force || (!job.failure?.paused && (job.nextAttemptAt ?? 0) <= now);
 }
 
-const notices = new Map<string, number>();
-/** No raw provider response, quotes, or repeated terminal floods. Durable job
- * state retains the failure category and can be resumed with a forced run. */
-export function reportLearningFailure(key: string): void {
-  const now = Date.now();
-  if (now - (notices.get(key) ?? 0) < 300_000) return;
-  notices.set(key, now);
-  if (notices.size > 128) notices.delete(notices.keys().next().value!);
-  process.stderr.write('[minimal-agent memory] 后台学习未完成，资料已保留；可通过 MemoryMaintenance status 查看、run 重试。重复失败将暂停自动重试。\n');
+type Partition = 'facts' | 'experience';
+type Health = { partition: Partition; phase: 'learning' | 'scheduling'; failures: number; at: number };
+const health = new Map<string, Health>();
+/** Background services never write over a host's TUI. Durable queues retain
+ * source failures; this bounded process snapshot also exposes scheduler/IO errors
+ * that could not be persisted. No source text, paths or provider secrets. */
+export function recordBackgroundLearningFailure(workspaceId: string, partition: Partition, phase: Health['phase']): void {
+  const key = `${workspaceId}:${partition}`;
+  const previous = health.get(key);
+  health.delete(key);
+  health.set(key, { partition, phase, failures: (previous?.failures ?? 0) + 1, at: Date.now() });
+  if (health.size > 128) health.delete(health.keys().next().value!);
+}
+export function backgroundLearningHealth(workspaceId: string): Health[] {
+  return (['facts', 'experience'] as const).flatMap(partition => {
+    const value = health.get(`${workspaceId}:${partition}`);
+    return value ? [{ ...value }] : [];
+  });
 }

package/src/memory/learning.js

@@ -5,7 +5,7 @@
 import { randomUUID } from 'node:crypto';
 import { parseMemoryProposal } from './proposal.js';
 import { acquireModelSlot, MAX_MODEL_DURATION_MS } from './modelBudget.js';
-import { jobEligible, recordJobFailure, reportLearningFailure } from './jobPolicy.js';
+import { jobEligible, recordJobFailure, recordBackgroundLearningFailure } from './jobPolicy.js';
 import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { ensurePrivateDir } from './fileStore.js';
@@ -343,7 +343,7 @@ export function scheduleMemoryMaintenance(options) {
     void runMemoryMaintenance(options).catch((error) => {
         if (options.signal?.aborted)
             return;
-        reportLearningFailure(experienceDirectory(options.workspaceId));
+        recordBackgroundLearningFailure(options.workspaceId, 'experience', 'learning');
     }).finally(async () => {
         const settings = await memoryService.settings();
         if (cancelled.has(experienceDirectory(options.workspaceId)) || options.signal?.aborted || !settings.autoRemember || !settings.learning?.enabled)
@@ -358,7 +358,7 @@ export function scheduleMemoryMaintenance(options) {
         if (cancelled.has(experienceDirectory(options.workspaceId)) || active.has(experienceDirectory(options.workspaceId)))
             return;
         wakeAt(experienceDirectory(options.workspaceId), Math.max(next, Date.now() + 1000), () => scheduleMemoryMaintenance({ ...options, force: false }), options.signal);
-    }).catch(error => process.stderr.write(`[minimal-agent memory] 恢复调度失败：${error.message}\n`));
+    }).catch(() => recordBackgroundLearningFailure(options.workspaceId, 'experience', 'scheduling'));
 }
 /** Tests and orderly hosts may drain without polling or busy waiting. */
 export async function drainMemoryMaintenance() {

package/src/memory/learning.ts

@@ -5,7 +5,7 @@
 import { randomUUID } from 'node:crypto';
 import { parseMemoryProposal } from './proposal.js';
 import { acquireModelSlot, MAX_MODEL_DURATION_MS } from './modelBudget.js';
-import { jobEligible, recordJobFailure, reportLearningFailure } from './jobPolicy.js';
+import { jobEligible, recordJobFailure, recordBackgroundLearningFailure } from './jobPolicy.js';
 import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { ensurePrivateDir } from './fileStore.js';
@@ -423,7 +423,7 @@ export function scheduleMemoryMaintenance(
   if (active.has(experienceDirectory(options.workspaceId))) return;
   void runMemoryMaintenance(options).catch((error) => {
     if (options.signal?.aborted) return;
-    reportLearningFailure(experienceDirectory(options.workspaceId));
+    recordBackgroundLearningFailure(options.workspaceId, 'experience', 'learning');
   }).finally(async () => {
     const settings = await memoryService.settings();
     if (cancelled.has(experienceDirectory(options.workspaceId)) || options.signal?.aborted || !settings.autoRemember || !settings.learning?.enabled) return;
@@ -436,7 +436,7 @@ export function scheduleMemoryMaintenance(
     // Cancellation can happen during the preceding disk reads.
     if (cancelled.has(experienceDirectory(options.workspaceId)) || active.has(experienceDirectory(options.workspaceId))) return;
     wakeAt(experienceDirectory(options.workspaceId), Math.max(next, Date.now() + 1000), () => scheduleMemoryMaintenance({ ...options, force: false }), options.signal);
-  }).catch(error => process.stderr.write(`[minimal-agent memory] 恢复调度失败：${error.message}\n`));
+  }).catch(() => recordBackgroundLearningFailure(options.workspaceId, 'experience', 'scheduling'));
 }
 
 /** Tests and orderly hosts may drain without polling or busy waiting. */

package/src/memory/learningModel.js

@@ -43,8 +43,10 @@ export function createLearningModel(provider, execute = chat) {
             }
         }
         signal.throwIfAborted();
-        if (!finished || !text.trim())
-            throw new Error('记忆整理模型未正常完成，保留待处理资料');
+        if (!finished)
+            throw new MemoryProposalError('format', '记忆整理模型未正常完成（截断或缺少正常结束标记），保留待处理资料');
+        if (!text.trim())
+            throw new MemoryProposalError('format', '记忆整理模型未正常完成（空正文），保留待处理资料');
         return { text, usage };
     };
 }

package/src/memory/learningModel.ts

@@ -49,8 +49,10 @@ export function createLearningModel(
       }
     }
     signal.throwIfAborted();
-    if (!finished || !text.trim())
-      throw new Error('记忆整理模型未正常完成，保留待处理资料');
+    if (!finished)
+      throw new MemoryProposalError('format', '记忆整理模型未正常完成（截断或缺少正常结束标记），保留待处理资料');
+    if (!text.trim())
+      throw new MemoryProposalError('format', '记忆整理模型未正常完成（空正文），保留待处理资料');
     return { text, usage };
   };
 }

package/src/prompts/delegation.js

@@ -0,0 +1,15 @@
+/** One delegation contract shared by the main prompt, tool discovery and runtime. */
+export const RESEARCH_DELEGATION_POLICY = `# 大范围阅读与并行调研
+- 先读项目说明、目录、入口与基线，建立问题地图，不先串行读完整仓库。批量阅读涉及多个独立模块、各需多轮探索时，优先同轮派发多个 Agent(agent_type="explore")；数量取决于独立工作量和宿主额度，不按文件数量机械切块。
+- 少量已知文件同轮批量读；强依赖调用链自行跟进。只读委派无需写入铺路或 worktree，不为获得 shell 升级 general。
+- 自包含任务书优先用 context.researchQuestions 写清问题、范围、停止条件，附基线、已知证据与排除项，不复制主历史。
+- 有独立工作时后台派发，否则同轮前台派发；不立即轮询或重复调查。整合证据、冲突与缺口；摘要不代表全文覆盖，并发不保证降低总 Token。`;
+export const AGENT_TOOL_DESCRIPTION = '启动隔离子任务（fork）并返回 agent_id。大型多模块批量阅读先定位入口，再优先同轮派发独立 explore 调查；少量已知文件直接批量读。explore 默认只读，general 使用 write_scopes 或 worktree。任务书自包含，context.researchQuestions 定义问题、范围、停止条件；AgentReport.findings 返回证据结论。run_in_background 立即返回供主 Agent 推进独立工作；resume_agent_id 续接子任务私有历史。reportMaxChars 限制预览，完整交接由 TaskOutput 获取。';
+export function delegationRuntimeGuidance(input) {
+    if (!input.available)
+        return '';
+    const remaining = Math.max(0, input.maxCalls - input.callsUsed);
+    if (!remaining)
+        return '本轮子任务派发次数已用完：收口已有子任务，其余调查由主 Agent 使用当前工具完成，不重复尝试派发。';
+    return `本轮可使用 Agent 进行隔离委派，剩余派发次数 ${remaining}，配置并发上限 ${Math.max(1, Math.min(8, input.maxConcurrent))}（实际槽位由调度器协调）。大型批量阅读先建立问题地图，再优先并行派发独立 explore 调查；不要把所有模块留在主上下文串行阅读。少量已知文件仍直接批量读。`;
+}

package/src/prompts/delegation.ts

@@ -0,0 +1,20 @@
+/** One delegation contract shared by the main prompt, tool discovery and runtime. */
+export const RESEARCH_DELEGATION_POLICY = `# 大范围阅读与并行调研
+- 先读项目说明、目录、入口与基线，建立问题地图，不先串行读完整仓库。批量阅读涉及多个独立模块、各需多轮探索时，优先同轮派发多个 Agent(agent_type="explore")；数量取决于独立工作量和宿主额度，不按文件数量机械切块。
+- 少量已知文件同轮批量读；强依赖调用链自行跟进。只读委派无需写入铺路或 worktree，不为获得 shell 升级 general。
+- 自包含任务书优先用 context.researchQuestions 写清问题、范围、停止条件，附基线、已知证据与排除项，不复制主历史。
+- 有独立工作时后台派发，否则同轮前台派发；不立即轮询或重复调查。整合证据、冲突与缺口；摘要不代表全文覆盖，并发不保证降低总 Token。`;
+
+export const AGENT_TOOL_DESCRIPTION = '启动隔离子任务（fork）并返回 agent_id。大型多模块批量阅读先定位入口，再优先同轮派发独立 explore 调查；少量已知文件直接批量读。explore 默认只读，general 使用 write_scopes 或 worktree。任务书自包含，context.researchQuestions 定义问题、范围、停止条件；AgentReport.findings 返回证据结论。run_in_background 立即返回供主 Agent 推进独立工作；resume_agent_id 续接子任务私有历史。reportMaxChars 限制预览，完整交接由 TaskOutput 获取。';
+
+export function delegationRuntimeGuidance(input: {
+  available: boolean;
+  maxConcurrent: number;
+  callsUsed: number;
+  maxCalls: number;
+}): string {
+  if (!input.available) return '';
+  const remaining = Math.max(0, input.maxCalls - input.callsUsed);
+  if (!remaining) return '本轮子任务派发次数已用完：收口已有子任务，其余调查由主 Agent 使用当前工具完成，不重复尝试派发。';
+  return `本轮可使用 Agent 进行隔离委派，剩余派发次数 ${remaining}，配置并发上限 ${Math.max(1, Math.min(8, input.maxConcurrent))}（实际槽位由调度器协调）。大型批量阅读先建立问题地图，再优先并行派发独立 explore 调查；不要把所有模块留在主上下文串行阅读。少量已知文件仍直接批量读。`;
+}

package/src/prompts/policyRegistry.js

@@ -1,4 +1,5 @@
 import { CODE_REVIEW_RUBRIC } from './codeReview.js';
+import { RESEARCH_DELEGATION_POLICY } from './delegation.js';
 import { capabilityForToolName, } from '../tools/capabilities.js';
 import { skillInvokeInstruction } from './skillList.js';
 import { visualPresentation } from './visualPresentation.js';
@@ -260,7 +261,7 @@ const CAPABILITY_POLICIES = [
     {
         id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
         requiresTools: ['Agent'],
-        render: () => '- 大范围调查先定位入口、模块边界与基线，不穷尽读取。独立且需多轮探索的问题可同轮派发 explore Agent，数量取决于独立工作量和宿主额度，不为并行而拆分；少量已知文件/网址直接批量读，强顺序或协调开销大于收益时自行完成。主 Agent 保留跨模块判断，有独立工作时后台派发并推进，不重复调查或立即轮询。任务书写清问题、范围、停止条件、排除项和已知证据，不复制私有历史。按问题整合结论与阅读证据，区分观察、推断、建议；冲突核验不投票，只补读关键结论、版本变化与修改位置。文件清单不代表全文覆盖。子任务用实际可用的搜索/正文工具，动态浏览器归主 Agent；不得为只读命令升级为 general。',
+        render: () => RESEARCH_DELEGATION_POLICY,
     },
     {
         id: 'capability.agent-handoff', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
@@ -295,7 +296,7 @@ const CAPABILITY_POLICIES = [
             if (toolNames.has('RecallMemory'))
                 rules.push('自包含任务无需检索记忆。依赖跨会话用户信息、偏好、决定或项目背景时，先检查已注入证据；缺少相关信息再用 RecallMemory，避免重复检索或直接反问用户。查询无关命中时停止扩大检索；旧结论与现场冲突时重新查证，未在本轮核验的历史结论标明来源及可能过时。');
             if (toolNames.has('RecallMemory') && toolNames.has('UpdateMemory'))
-                rules.push('纠正：RecallMemory 定位 → UpdateMemory(expectedVersion)；冲突回执充分则合并重试，否则重读。语义未变不重写。');
+                rules.push('RecallMemory 读版本 → UpdateMemory：update 原话/review 待复核/confirm 确认；冲突重读，拒绝不重试。');
             if (toolNames.has('ForgetMemory'))
                 rules.push('ForgetMemory 仅响应当前明确遗忘要求。');
             if (toolNames.has('ConfirmMemory'))

package/src/prompts/policyRegistry.ts

@@ -1,5 +1,6 @@
 import type { Tool } from '../types.js';
 import { CODE_REVIEW_RUBRIC } from './codeReview.js';
+import { RESEARCH_DELEGATION_POLICY } from './delegation.js';
 import type { AgentProfile, AgentSurface } from '../runtime/agentRuntimeContext.js';
 import {
   capabilityForToolName,
@@ -309,7 +310,7 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
   {
     id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
     requiresTools: ['Agent'],
-    render: () => '- 大范围调查先定位入口、模块边界与基线，不穷尽读取。独立且需多轮探索的问题可同轮派发 explore Agent，数量取决于独立工作量和宿主额度，不为并行而拆分；少量已知文件/网址直接批量读，强顺序或协调开销大于收益时自行完成。主 Agent 保留跨模块判断，有独立工作时后台派发并推进，不重复调查或立即轮询。任务书写清问题、范围、停止条件、排除项和已知证据，不复制私有历史。按问题整合结论与阅读证据，区分观察、推断、建议；冲突核验不投票，只补读关键结论、版本变化与修改位置。文件清单不代表全文覆盖。子任务用实际可用的搜索/正文工具，动态浏览器归主 Agent；不得为只读命令升级为 general。',
+    render: () => RESEARCH_DELEGATION_POLICY,
   },
   {
     id: 'capability.agent-handoff', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
@@ -341,7 +342,7 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
       ];
       if (toolNames.has('RememberMemory')) rules.push('RememberMemory 保存明确要求记住的新事实；后台提炼启用时普通陈述交后台处理，不重复写入。自动记忆关闭时仅响应明确保存要求；失败如实说明，不阻断任务。');
       if (toolNames.has('RecallMemory')) rules.push('自包含任务无需检索记忆。依赖跨会话用户信息、偏好、决定或项目背景时，先检查已注入证据；缺少相关信息再用 RecallMemory，避免重复检索或直接反问用户。查询无关命中时停止扩大检索；旧结论与现场冲突时重新查证，未在本轮核验的历史结论标明来源及可能过时。');
-      if (toolNames.has('RecallMemory') && toolNames.has('UpdateMemory')) rules.push('纠正：RecallMemory 定位 → UpdateMemory(expectedVersion)；冲突回执充分则合并重试，否则重读。语义未变不重写。');
+      if (toolNames.has('RecallMemory') && toolNames.has('UpdateMemory')) rules.push('RecallMemory 读版本 → UpdateMemory：update 原话/review 待复核/confirm 确认；冲突重读，拒绝不重试。');
       if (toolNames.has('ForgetMemory')) rules.push('ForgetMemory 仅响应当前明确遗忘要求。');
       if (toolNames.has('ConfirmMemory')) rules.push('用户重新确认相同事实时使用 ConfirmMemory 更新确认时间，不创建副本。');
       if (toolNames.has('ReviewMemories')) rules.push('已过复核周期的记录只降低优先级并提示复核，不自动删除。');

package/src/tools/agent/agent.js

@@ -25,6 +25,7 @@
  * ============================================================
  */
 import { randomUUID } from 'node:crypto';
+import { AGENT_TOOL_DESCRIPTION } from '../../prompts/delegation.js';
 import { researchQuestionSchema, researchPreview } from './research.js';
 import { EventEmitter } from 'node:events';
 import { access } from 'node:fs/promises';
@@ -106,7 +107,7 @@ const inputSchema = z.object({
 const parameters = toToolParameters(inputSchema);
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
 // 借鉴官方 AgentTool prompt 文案（任务书自包含 / 同轮并行 / 何时不用）。
-const description = 'Launch an isolated sub-agent with a self-contained prompt. Returns agent_id; run_in_background returns immediately, resume_agent_id resumes private history. explore is read-only; general uses write_scopes or an explicit worktree. context.researchQuestions defines question IDs, scope and stopping conditions; structured findings link conclusions to tool evidence. Full handoff and paged findings remain available through TaskOutput.';
+const description = AGENT_TOOL_DESCRIPTION;
 // ---------------- 3. 子 agent 系统提示词（memoize，提示词缓存友好） ----------------
 /** 任务回传契约。能力与权限已经由 assembleBasePrompt profile 精确注入。 */
 const SUBAGENT_COMMON_APPENDIX = `# 你是子 agent（fork 分身）

package/src/tools/agent/agent.ts

@@ -26,6 +26,7 @@
  */
 
 import { randomUUID } from 'node:crypto';
+import { AGENT_TOOL_DESCRIPTION } from '../../prompts/delegation.js';
 import { researchQuestionSchema, researchPreview } from './research.js';
 import { EventEmitter } from 'node:events';
 import { access } from 'node:fs/promises';
@@ -152,7 +153,7 @@ const parameters = toToolParameters(inputSchema);
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
 // 借鉴官方 AgentTool prompt 文案（任务书自包含 / 同轮并行 / 何时不用）。
 
-const description = 'Launch an isolated sub-agent with a self-contained prompt. Returns agent_id; run_in_background returns immediately, resume_agent_id resumes private history. explore is read-only; general uses write_scopes or an explicit worktree. context.researchQuestions defines question IDs, scope and stopping conditions; structured findings link conclusions to tool evidence. Full handoff and paged findings remain available through TaskOutput.';
+const description = AGENT_TOOL_DESCRIPTION;
 
 // ---------------- 3. 子 agent 系统提示词（memoize，提示词缓存友好） ----------------
 

package/src/tools/memory/maintenance.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { backgroundLearningHealth } from '../../memory/jobPolicy.js';
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
 import { sha256 } from '../../memory/codec.js';
 import { captureDependencies } from '../../memory/dependencies.js';
@@ -289,6 +290,7 @@ export const memoryMaintenanceTool = {
                 ok: true,
                 content: JSON.stringify({
                     ...(await persistedLearningStatus(ctx.workspaceId)),
+                    recentBackgroundFailures: backgroundLearningHealth(ctx.workspaceId),
                     revision: store.revision,
                     taskSummaries: {
                         count: store.taskSummaries?.length ?? 0,

package/src/tools/memory/maintenance.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { backgroundLearningHealth } from '../../memory/jobPolicy.js';
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
 import { sha256 } from '../../memory/codec.js';
 import { captureDependencies } from '../../memory/dependencies.js';
@@ -388,6 +389,7 @@ export const memoryMaintenanceTool: Tool<z.infer<typeof schema>> = {
         content: JSON.stringify(
           {
             ...(await persistedLearningStatus(ctx.workspaceId)),
+            recentBackgroundFailures: backgroundLearningHealth(ctx.workspaceId),
             revision: store.revision,
             taskSummaries: {
               count: store.taskSummaries?.length ?? 0,

package/src/tools/memory/memory.js

@@ -6,7 +6,7 @@ import { memoryRecordPath } from '../../memory/fileStore.js';
 import { memoryService, } from '../../memory/memoryService.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
-import { EXPLICIT_CROSS_WORKSPACE_INTENT, EXPLICIT_FORGET_INTENT, EXPLICIT_MEMORY_INTENT, EXPLICIT_PERSONA_INTENT, confirmSensitiveMemory, denyUnlessLocalOwner, requireCurrentEvidence, } from './policy.js';
+import { EXPLICIT_CROSS_WORKSPACE_INTENT, EXPLICIT_FORGET_INTENT, EXPLICIT_MEMORY_INTENT, EXPLICIT_PERSONA_INTENT, confirmSensitiveMemory, confirmMemoryCorrection, denyUnlessLocalOwner, requireCurrentEvidence, } from './policy.js';
 const scopeSchema = z.enum(['personal', 'workspace']);
 const categorySchema = z.enum([
     'profile',
@@ -21,7 +21,7 @@ function formatRecord(record, version) {
         ? ` workspace=${record.workspaceId}`
         : '';
     const lifecycle = ` status=${record.status ?? 'active'} revision=${record.revision ?? 1}`;
-    return `- [${record.id}] scope=${record.scope} ${record.category}/${record.subject}${workspace}${lifecycle}${version ? ` version=${version}` : ''}: ${record.statement}（${record.evidence}，${new Date(record.updatedAt).toISOString()}）`;
+    return `- [${record.id}] scope=${record.scope} ${record.category}/${record.subject}${workspace}${lifecycle}${version ? ` version=${version}` : ''}: ${record.statement}（${record.evidence}，${new Date(record.updatedAt).toISOString()}）${record.status === 'needs_review' && record.confirmationContext ? `\n复核线索（非事实）：${record.confirmationContext}` : ''}`;
 }
 function diagnosticSuffix(diagnostics) {
     if (!diagnostics.length)
@@ -159,15 +159,18 @@ export const rememberMemoryTool = {
     },
 };
 const updateSchema = z.object({
+    action: z.enum(['update', 'review', 'confirm']).optional().describe('默认 update：当前用户原话纠正；review：仅标记待复核，不改事实；confirm：通过宿主向用户确认拟更新内容后保存'),
+    reason: z.string().min(1).max(1000).optional().describe('review/confirm 必填：冲突或纠正依据，注明来源；不得伪造用户陈述'),
     id: z.string().uuid(),
     scope: scopeSchema,
     category: categorySchema.optional(),
     subject: z.string().min(1).max(120).optional(),
-    statement: z.string().min(1).max(1000),
+    statement: z.string().min(1).max(1000).optional(),
     evidenceQuote: z
         .string()
         .min(1)
         .max(1000)
+        .optional()
         .describe('当前用户消息中的逐字证据片段'),
     sensitivity: z.enum(['normal', 'sensitive']).optional(),
     aliases: z.array(z.string().min(1).max(120)).max(20).optional(),
@@ -184,7 +187,7 @@ const updateSchema = z.object({
 });
 export const updateMemoryTool = {
     name: 'UpdateMemory',
-    description: '在用户当前陈述纠正或替换旧事实时，按 RecallMemory 返回的 ID 整条更新。必须先读取旧记录，evidenceQuote 必须逐字来自当前用户消息；不得用推断补写历史。',
+    description: '纠正用户事实记忆：先 RecallMemory 读取 ID/version。默认 update 需要 statement 与当前用户原话 evidenceQuote；review 需要 reason，仅标记待复核、保留原事实与证据；confirm 需要 statement/reason，通过宿主展示新旧内容并取得用户确认再更新。拒绝或无法交互不写入。项目知识和经验走 MemoryMaintenance，不伪造用户证据。',
     inputSchema: updateSchema,
     parameters: toToolParameters(updateSchema),
     isReadOnly: false,
@@ -196,9 +199,23 @@ export const updateMemoryTool = {
         if (denied)
             return denied;
         const current = ctx.currentUserInput ?? '';
-        const invalidEvidence = requireCurrentEvidence(ctx, input.evidenceQuote);
-        if (invalidEvidence)
-            return invalidEvidence;
+        const action = input.action ?? 'update';
+        if (action === 'review' && (input.statement !== undefined || input.evidenceQuote !== undefined)) {
+            return { ok: false, error: 'review 仅提交 reason，不提交 statement/evidenceQuote；标记疑点不代表确认新事实' };
+        }
+        if (action !== 'update' && (input.category !== undefined || input.subject !== undefined || input.aliases !== undefined || input.supersedesIds !== undefined || input.sensitivity !== undefined)) {
+            return { ok: false, error: 'review/confirm 只处理当前记录的复核状态或正文，不同时修改分类、敏感级别、别名或替代其他记录' };
+        }
+        if (action === 'update') {
+            if (!input.statement || !input.evidenceQuote)
+                return { ok: false, error: 'update 需要 statement 和当前用户原话 evidenceQuote' };
+            const invalidEvidence = requireCurrentEvidence(ctx, input.evidenceQuote);
+            if (invalidEvidence)
+                return invalidEvidence;
+        }
+        else if (!input.reason || (action === 'confirm' && !input.statement)) {
+            return { ok: false, error: 'review 需要 reason；confirm 需要 reason 和 statement' };
+        }
         if (input.scope === 'workspace' && !ctx.workspaceId) {
             return {
                 ok: false,
@@ -206,7 +223,7 @@ export const updateMemoryTool = {
             };
         }
         if (!(await memoryService.settings()).autoRemember &&
-            !EXPLICIT_MEMORY_INTENT.test(current)) {
+            !EXPLICIT_MEMORY_INTENT.test(current) && action !== 'confirm') {
             return {
                 ok: false,
                 error: '用户已关闭自动记忆；当前消息没有明确要求更新记忆',
@@ -215,18 +232,43 @@ export const updateMemoryTool = {
         const currentRecord = await memoryService.readWithVersion(input.id, input.scope, input.scope === 'workspace' ? ctx.workspaceId : undefined);
         if (!currentRecord)
             return { ok: false, error: '未找到该记忆，未做修改' };
-        const sensitivity = input.sensitivity ?? currentRecord.record.sensitivity ?? 'normal';
+        const expectedVersion = input.expectedVersion ?? currentRecord.version;
+        if (expectedVersion !== currentRecord.version) {
+            return {
+                ok: false,
+                error: '记忆已被手工或并发修改。未应用本次更新；保留以下当前记录的并发修改后可直接重试，不存在时重新定位。\n'
+                    + JSON.stringify({ current: currentRecord }),
+            };
+        }
+        if (action === 'review') {
+            signal?.throwIfAborted();
+            try {
+                const reviewed = await memoryService.updateWithVersion(input.id, input.scope, expectedVersion, { status: 'needs_review', confirmationContext: `待复核原因（非确认事实）：${input.reason}` }, input.scope === 'workspace' ? ctx.workspaceId : undefined);
+                return reviewed ? { ok: true, content: `已标记待复核，原事实和证据未改写。id=${input.id}\nversion=${reviewed.version}` }
+                    : { ok: false, error: '记录已不存在，未做修改' };
+            }
+            catch (error) {
+                if (error.message === 'MEMORY_VERSION_CONFLICT')
+                    return { ok: false, error: '记忆并发变更，请重新读取；未标记待复核' };
+                throw error;
+            }
+        }
+        const statement = input.statement;
+        const confirmed = action === 'confirm' && await confirmMemoryCorrection(currentRecord.record.subject, currentRecord.record.statement, statement, input.reason, signal);
+        if (action === 'confirm' && !confirmed)
+            return { ok: false, error: '未获得用户确认（拒绝或宿主无法交互），原记忆未改写；可标记待复核，不要重复请求确认' };
+        const evidenceQuote = confirmed ? `用户通过纠正记忆确认：${statement}` : input.evidenceQuote;
+        const sensitivity = currentRecord.record.sensitivity === 'sensitive' ? 'sensitive' : input.sensitivity ?? 'normal';
         if (sensitivity === 'sensitive' &&
-            input.statement.trim() === input.evidenceQuote.trim()) {
+            !confirmed && statement.trim() === evidenceQuote.trim()) {
             return {
                 ok: false,
                 error: '敏感内容不得逐字更新；请先概括、去除不必要细节后再请求确认',
             };
         }
-        const evidence = await confirmSensitiveMemory(input.statement, sensitivity, signal);
+        const evidence = confirmed ? 'user_confirmed' : await confirmSensitiveMemory(statement, sensitivity, signal);
         if (!evidence)
             return { ok: false, error: '敏感记忆更新未获确认' };
-        const expectedVersion = input.expectedVersion ?? currentRecord.version;
         let updated;
         try {
             updated = await memoryService.updateWithVersion(input.id, input.scope, expectedVersion, {
@@ -234,9 +276,11 @@ export const updateMemoryTool = {
                     ? { category: input.category }
                     : {}),
                 ...(input.subject ? { subject: input.subject } : {}),
-                statement: input.statement,
+                statement,
+                status: 'active',
                 evidence,
-                evidenceQuote: input.evidenceQuote,
+                evidenceQuote,
+                confirmationContext: confirmed ? `宿主确认纠正：${input.reason}` : '',
                 sourceSessionId: ctx.sessionId ?? 'unknown',
                 sourceMessageId: ctx.userMessageId ?? 'unknown',
                 sensitivity,

package/src/tools/memory/memory.ts

@@ -18,6 +18,7 @@ import {
   EXPLICIT_MEMORY_INTENT,
   EXPLICIT_PERSONA_INTENT,
   confirmSensitiveMemory,
+  confirmMemoryCorrection,
   denyUnlessLocalOwner,
   requireCurrentEvidence,
 } from './policy.js';
@@ -39,7 +40,7 @@ function formatRecord(
     ? ` workspace=${record.workspaceId}`
     : '';
   const lifecycle = ` status=${record.status ?? 'active'} revision=${record.revision ?? 1}`;
-  return `- [${record.id}] scope=${record.scope} ${record.category}/${record.subject}${workspace}${lifecycle}${version ? ` version=${version}` : ''}: ${record.statement}（${record.evidence}，${new Date(record.updatedAt).toISOString()}）`;
+  return `- [${record.id}] scope=${record.scope} ${record.category}/${record.subject}${workspace}${lifecycle}${version ? ` version=${version}` : ''}: ${record.statement}（${record.evidence}，${new Date(record.updatedAt).toISOString()}）${record.status === 'needs_review' && record.confirmationContext ? `\n复核线索（非事实）：${record.confirmationContext}` : ''}`;
 }
 
 function diagnosticSuffix(
@@ -188,15 +189,18 @@ export const rememberMemoryTool: Tool<z.infer<typeof rememberSchema>> = {
 };
 
 const updateSchema = z.object({
+  action: z.enum(['update', 'review', 'confirm']).optional().describe('默认 update：当前用户原话纠正；review：仅标记待复核，不改事实；confirm：通过宿主向用户确认拟更新内容后保存'),
+  reason: z.string().min(1).max(1000).optional().describe('review/confirm 必填：冲突或纠正依据，注明来源；不得伪造用户陈述'),
   id: z.string().uuid(),
   scope: scopeSchema,
   category: categorySchema.optional(),
   subject: z.string().min(1).max(120).optional(),
-  statement: z.string().min(1).max(1000),
+  statement: z.string().min(1).max(1000).optional(),
   evidenceQuote: z
     .string()
     .min(1)
     .max(1000)
+    .optional()
     .describe('当前用户消息中的逐字证据片段'),
   sensitivity: z.enum(['normal', 'sensitive']).optional(),
   aliases: z.array(z.string().min(1).max(120)).max(20).optional(),
@@ -217,7 +221,7 @@ const updateSchema = z.object({
 export const updateMemoryTool: Tool<z.infer<typeof updateSchema>> = {
   name: 'UpdateMemory',
   description:
-    '在用户当前陈述纠正或替换旧事实时，按 RecallMemory 返回的 ID 整条更新。必须先读取旧记录，evidenceQuote 必须逐字来自当前用户消息；不得用推断补写历史。',
+    '纠正用户事实记忆：先 RecallMemory 读取 ID/version。默认 update 需要 statement 与当前用户原话 evidenceQuote；review 需要 reason，仅标记待复核、保留原事实与证据；confirm 需要 statement/reason，通过宿主展示新旧内容并取得用户确认再更新。拒绝或无法交互不写入。项目知识和经验走 MemoryMaintenance，不伪造用户证据。',
   inputSchema: updateSchema,
   parameters: toToolParameters(updateSchema),
   isReadOnly: false,
@@ -228,8 +232,20 @@ export const updateMemoryTool: Tool<z.infer<typeof updateSchema>> = {
     const denied = denyUnlessLocalOwner(ctx);
     if (denied) return denied;
     const current = ctx.currentUserInput ?? '';
-    const invalidEvidence = requireCurrentEvidence(ctx, input.evidenceQuote);
-    if (invalidEvidence) return invalidEvidence;
+    const action = input.action ?? 'update';
+    if (action === 'review' && (input.statement !== undefined || input.evidenceQuote !== undefined)) {
+      return { ok: false, error: 'review 仅提交 reason，不提交 statement/evidenceQuote；标记疑点不代表确认新事实' };
+    }
+    if (action !== 'update' && (input.category !== undefined || input.subject !== undefined || input.aliases !== undefined || input.supersedesIds !== undefined || input.sensitivity !== undefined)) {
+      return { ok: false, error: 'review/confirm 只处理当前记录的复核状态或正文，不同时修改分类、敏感级别、别名或替代其他记录' };
+    }
+    if (action === 'update') {
+      if (!input.statement || !input.evidenceQuote) return { ok: false, error: 'update 需要 statement 和当前用户原话 evidenceQuote' };
+      const invalidEvidence = requireCurrentEvidence(ctx, input.evidenceQuote);
+      if (invalidEvidence) return invalidEvidence;
+    } else if (!input.reason || (action === 'confirm' && !input.statement)) {
+      return { ok: false, error: 'review 需要 reason；confirm 需要 reason 和 statement' };
+    }
     if (input.scope === 'workspace' && !ctx.workspaceId) {
       return {
         ok: false,
@@ -238,7 +254,7 @@ export const updateMemoryTool: Tool<z.infer<typeof updateSchema>> = {
     }
     if (
       !(await memoryService.settings()).autoRemember &&
-      !EXPLICIT_MEMORY_INTENT.test(current)
+      !EXPLICIT_MEMORY_INTENT.test(current) && action !== 'confirm'
     ) {
       return {
         ok: false,
@@ -251,23 +267,49 @@ export const updateMemoryTool: Tool<z.infer<typeof updateSchema>> = {
       input.scope === 'workspace' ? ctx.workspaceId : undefined,
     );
     if (!currentRecord) return { ok: false, error: '未找到该记忆，未做修改' };
-    const sensitivity = input.sensitivity ?? currentRecord.record.sensitivity ?? 'normal';
+    const expectedVersion = input.expectedVersion ?? currentRecord.version;
+    if (expectedVersion !== currentRecord.version) {
+      return {
+        ok: false,
+        error:
+          '记忆已被手工或并发修改。未应用本次更新；保留以下当前记录的并发修改后可直接重试，不存在时重新定位。\n'
+          + JSON.stringify({ current: currentRecord }),
+      };
+    }
+    if (action === 'review') {
+      signal?.throwIfAborted();
+      try {
+        const reviewed = await memoryService.updateWithVersion(input.id, input.scope, expectedVersion,
+          { status: 'needs_review', confirmationContext: `待复核原因（非确认事实）：${input.reason}` },
+          input.scope === 'workspace' ? ctx.workspaceId : undefined);
+        return reviewed ? { ok: true, content: `已标记待复核，原事实和证据未改写。id=${input.id}\nversion=${reviewed.version}` }
+          : { ok: false, error: '记录已不存在，未做修改' };
+      } catch (error) {
+        if ((error as Error).message === 'MEMORY_VERSION_CONFLICT') return { ok: false, error: '记忆并发变更，请重新读取；未标记待复核' };
+        throw error;
+      }
+    }
+    const statement = input.statement!;
+    const confirmed = action === 'confirm' && await confirmMemoryCorrection(currentRecord.record.subject,
+      currentRecord.record.statement, statement, input.reason!, signal);
+    if (action === 'confirm' && !confirmed) return { ok: false, error: '未获得用户确认（拒绝或宿主无法交互），原记忆未改写；可标记待复核，不要重复请求确认' };
+    const evidenceQuote = confirmed ? `用户通过纠正记忆确认：${statement}` : input.evidenceQuote!;
+    const sensitivity = currentRecord.record.sensitivity === 'sensitive' ? 'sensitive' : input.sensitivity ?? 'normal';
     if (
       sensitivity === 'sensitive' &&
-      input.statement.trim() === input.evidenceQuote.trim()
+      !confirmed && statement.trim() === evidenceQuote.trim()
     ) {
       return {
         ok: false,
         error: '敏感内容不得逐字更新；请先概括、去除不必要细节后再请求确认',
       };
     }
-    const evidence = await confirmSensitiveMemory(
-      input.statement,
+    const evidence = confirmed ? 'user_confirmed' : await confirmSensitiveMemory(
+      statement,
       sensitivity,
       signal,
     );
     if (!evidence) return { ok: false, error: '敏感记忆更新未获确认' };
-    const expectedVersion = input.expectedVersion ?? currentRecord.version;
     let updated: Awaited<ReturnType<typeof memoryService.updateWithVersion>>;
     try {
       updated = await memoryService.updateWithVersion(
@@ -279,9 +321,11 @@ export const updateMemoryTool: Tool<z.infer<typeof updateSchema>> = {
             ? { category: input.category as MemoryCategory }
             : {}),
           ...(input.subject ? { subject: input.subject } : {}),
-          statement: input.statement,
+          statement,
+          status: 'active',
           evidence,
-          evidenceQuote: input.evidenceQuote,
+          evidenceQuote,
+          confirmationContext: confirmed ? `宿主确认纠正：${input.reason}` : '',
           sourceSessionId: ctx.sessionId ?? 'unknown',
           sourceMessageId: ctx.userMessageId ?? 'unknown',
           sensitivity,

package/src/tools/memory/policy.js

@@ -25,9 +25,24 @@ export function requireCurrentEvidence(ctx, evidenceQuote) {
         ? null
         : {
             ok: false,
-            error: 'evidenceQuote 不是当前用户消息的逐字片段，拒绝写入推断性记忆',
+            error: 'evidenceQuote 不是当前用户消息的逐字片段，未写入。不要改写或伪造引用重试：用户事实可用 UpdateMemory(action=confirm) 请求确认，或 action=review 标记待复核；项目知识/经验使用 MemoryMaintenance，不把工具证据当用户原话。',
         };
 }
+export async function confirmMemoryCorrection(subject, previous, proposed, reason, signal) {
+    if (!hasAskHandler())
+        return false;
+    signal?.throwIfAborted();
+    const [answer] = await requestUserChoice([{
+            header: '纠正记忆',
+            question: `是否更新“${subject}”？\n原记录：${previous}\n拟更新为：${proposed}\n纠正依据：${reason}`,
+            options: [
+                { label: '暂不更新', description: '保留原记录，不把建议视为事实。' },
+                { label: '确认更新', description: '确认拟更新内容准确，并保存为本机长期记忆。' },
+            ],
+        }], signal);
+    signal?.throwIfAborted();
+    return answer?.selected.length === 1 && answer.selected[0] === '确认更新';
+}
 export async function confirmSensitiveMemory(statement, sensitivity, signal) {
     if (sensitivity === 'normal')
         return 'user_stated';

package/src/tools/memory/policy.ts

@@ -38,10 +38,25 @@ export function requireCurrentEvidence(
     ? null
     : {
         ok: false,
-        error: 'evidenceQuote 不是当前用户消息的逐字片段，拒绝写入推断性记忆',
+        error: 'evidenceQuote 不是当前用户消息的逐字片段，未写入。不要改写或伪造引用重试：用户事实可用 UpdateMemory(action=confirm) 请求确认，或 action=review 标记待复核；项目知识/经验使用 MemoryMaintenance，不把工具证据当用户原话。',
       };
 }
 
+export async function confirmMemoryCorrection(subject: string, previous: string, proposed: string, reason: string, signal?: AbortSignal): Promise<boolean> {
+  if (!hasAskHandler()) return false;
+  signal?.throwIfAborted();
+  const [answer] = await requestUserChoice([{
+    header: '纠正记忆',
+    question: `是否更新“${subject}”？\n原记录：${previous}\n拟更新为：${proposed}\n纠正依据：${reason}`,
+    options: [
+      { label: '暂不更新', description: '保留原记录，不把建议视为事实。' },
+      { label: '确认更新', description: '确认拟更新内容准确，并保存为本机长期记忆。' },
+    ],
+  }], signal);
+  signal?.throwIfAborted();
+  return answer?.selected.length === 1 && answer.selected[0] === '确认更新';
+}
+
 export async function confirmSensitiveMemory(
   statement: string,
   sensitivity: 'normal' | 'sensitive',

package/src/tools/toolPromptGuides.js

@@ -1,3 +1,4 @@
+import { AGENT_TOOL_DESCRIPTION } from '../prompts/delegation.js';
 import { bashShellNotice } from './bash/bash.js';
 import { COMPUTER_USE_TOOL_ACTIONS } from './computeruse/protocol.js';
 export const TOOL_CATEGORY_LABELS = {
@@ -42,7 +43,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES = {
     BrowserCDP: g('web', '需要现有浏览器工具未覆盖的原始 CDP 能力', '发送精确方法并按事件序列读取结果', '常规网页自动化优先 WebBrowser/BrowserBatch', 'last-resort'),
     Download: g('web', '把已知 URL 的原始资源保存到本机', '给出目标路径并校验下载结果', '只阅读正文时用 WebFetch'),
     ComputerUse: g('desktop', '用户明确要求观察或操作原生应用、系统窗口或桌面界面', '观察当前界面，执行一个动作，再验证结果', '文件、静态图片、Shell 和网页任务优先专用工具', 'last-resort'),
-    Agent: g('agents', '派生独立且边界清晰的子任务', '给出自包含任务书并在返回后核验整合', '不要拆分琐碎或强顺序工作'),
+    Agent: g('agents', '大型多模块调查优先委派独立只读问题', '先定位入口，再同轮派发 explore，核验整合证据', '少量已知文件或强顺序工作直接处理'),
     AgentMessage: g('agents', '向运行中的子 Agent 补充非触发消息', '按稳定 agent id 发送必要上下文', '需要追加新工作使用 AgentFollowup'),
     AgentList: g('agents', '查看子 Agent 状态和稳定 ID', '按任务路径列出后选择目标', '已知目标 ID 时无需调用'),
     AgentWait: g('agents', '等待指定子 Agent 进展或结果', '优先长等待，收到更新后再整合', '忙轮询'),
@@ -58,7 +59,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES = {
     RecallMemory: g('memory', '当前回答依赖跨会话稳定偏好、决定或背景', '按主题召回并核对证据', '当前消息已足够时不要装饰性召回'),
     MemoryMaintenance: g('memory', '处理学习队列、项目事实冲突及经验反馈', 'status 定位；summaries 按 query 找近期任务线索、按 turnId 查证据；resolve/resolveKnowledge 结清候选；明确跨项目适用条件后 promoteExperience/promoteKnowledge；adopt 后 feedback', '召回不算使用；失败摘要不是已确认事实；不每轮调用'),
     RememberMemory: g('memory', '用户明确要求记住长期有效事实、偏好或决定', '保存原话证据和适用范围', '普通陈述交由已启用的后台提炼，不重复保存'),
-    UpdateMemory: g('memory', '当前用户陈述纠正一条已有记忆', '先 Recall 定位版本，再完整替换', '不要创建冲突副本'),
+    UpdateMemory: g('memory', '纠正用户事实', '读版本后 update/review/confirm', '项目知识/经验走 MemoryMaintenance'),
     ListMemories: g('memory', '用户要查看已保存记忆或需要管理总览', '按范围列出后再决定操作', '正常任务无需全量列出'),
     ForgetMemory: g('memory', '用户明确要求忘记某条记忆', '定位准确 ID 后删除', '不得主动清理'),
     SetPersona: g('memory', '用户明确要求改变长期角色或协作风格', '写入清晰、稳定的人格要求', '一次性语气请求不要持久化'),
@@ -117,7 +118,7 @@ export const CONTRACT_DESCRIPTION_OVERRIDES = {
     WebSearch: 'Tavily 搜索返回标题、URL、片段及可选综合答案，不是完整原文或浏览器。重要结论读取来源正文；按子问题查询，重试改变关键词或来源。recency 控制时效，历史范围用 start_date/end_date，none 关闭自动时效；advanced 更慢，news 偏新闻。需配置 Tavily。',
     PowerShell: '运行宿主 PowerShell 独立进程并检查结果；长任务用 TaskOutput/TaskStop。永久删除用 Trash；不可逆操作先确认，非交互时取消。',
     Download: '下载 HTTP(S) 原始字节到指定路径；相对路径基于工作目录，会覆盖已有文件；失败或中断不保留部分下载。',
-    Agent: '启动隔离上下文子任务并返回 agent_id。explore 只读，general 按 write_scopes 或 worktree 执行。run_in_background 立即返回；resume_agent_id 续接私有历史。context.researchQuestions 定义问题契约，AgentReport.findings 按 ID 回传证据结论；reportMaxChars 限制返回预览，完整交接可由 TaskOutput 获取。',
+    Agent: AGENT_TOOL_DESCRIPTION,
     EnterWorktree: '从已提交 HEAD 创建并进入隔离工作树，不自动复制原工作区未提交修改；后续文件工具使用隔离目录，项目记忆仍属于原工作区。',
     ExitWorktree: '退出隔离工作树：apply 检查并应用补丁到原工作区但不自动提交；keep 保留；discard 有改动则归档保留。实际应用成功后的清理告警不表示应重新应用。',
 };

package/src/tools/toolPromptGuides.ts

@@ -1,4 +1,5 @@
 import type { Tool, ToolCategory, ToolPromptGuide } from '../types.js';
+import { AGENT_TOOL_DESCRIPTION } from '../prompts/delegation.js';
 import { bashShellNotice } from './bash/bash.js';
 import { COMPUTER_USE_TOOL_ACTIONS } from './computeruse/protocol.js';
 
@@ -56,7 +57,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES: Readonly<Record<string, ToolPromptGuide
 
   ComputerUse: g('desktop', '用户明确要求观察或操作原生应用、系统窗口或桌面界面', '观察当前界面，执行一个动作，再验证结果', '文件、静态图片、Shell 和网页任务优先专用工具', 'last-resort'),
 
-  Agent: g('agents', '派生独立且边界清晰的子任务', '给出自包含任务书并在返回后核验整合', '不要拆分琐碎或强顺序工作'),
+  Agent: g('agents', '大型多模块调查优先委派独立只读问题', '先定位入口，再同轮派发 explore，核验整合证据', '少量已知文件或强顺序工作直接处理'),
   AgentMessage: g('agents', '向运行中的子 Agent 补充非触发消息', '按稳定 agent id 发送必要上下文', '需要追加新工作使用 AgentFollowup'),
   AgentList: g('agents', '查看子 Agent 状态和稳定 ID', '按任务路径列出后选择目标', '已知目标 ID 时无需调用'),
   AgentWait: g('agents', '等待指定子 Agent 进展或结果', '优先长等待，收到更新后再整合', '忙轮询'),
@@ -73,7 +74,7 @@ export const BUILTIN_TOOL_PROMPT_GUIDES: Readonly<Record<string, ToolPromptGuide
   RecallMemory: g('memory', '当前回答依赖跨会话稳定偏好、决定或背景', '按主题召回并核对证据', '当前消息已足够时不要装饰性召回'),
   MemoryMaintenance: g('memory', '处理学习队列、项目事实冲突及经验反馈', 'status 定位；summaries 按 query 找近期任务线索、按 turnId 查证据；resolve/resolveKnowledge 结清候选；明确跨项目适用条件后 promoteExperience/promoteKnowledge；adopt 后 feedback', '召回不算使用；失败摘要不是已确认事实；不每轮调用'),
   RememberMemory: g('memory', '用户明确要求记住长期有效事实、偏好或决定', '保存原话证据和适用范围', '普通陈述交由已启用的后台提炼，不重复保存'),
-  UpdateMemory: g('memory', '当前用户陈述纠正一条已有记忆', '先 Recall 定位版本，再完整替换', '不要创建冲突副本'),
+  UpdateMemory: g('memory', '纠正用户事实', '读版本后 update/review/confirm', '项目知识/经验走 MemoryMaintenance'),
   ListMemories: g('memory', '用户要查看已保存记忆或需要管理总览', '按范围列出后再决定操作', '正常任务无需全量列出'),
   ForgetMemory: g('memory', '用户明确要求忘记某条记忆', '定位准确 ID 后删除', '不得主动清理'),
   SetPersona: g('memory', '用户明确要求改变长期角色或协作风格', '写入清晰、稳定的人格要求', '一次性语气请求不要持久化'),
@@ -135,7 +136,7 @@ export const CONTRACT_DESCRIPTION_OVERRIDES: Readonly<Record<string, string | ((
   WebSearch: 'Tavily 搜索返回标题、URL、片段及可选综合答案，不是完整原文或浏览器。重要结论读取来源正文；按子问题查询，重试改变关键词或来源。recency 控制时效，历史范围用 start_date/end_date，none 关闭自动时效；advanced 更慢，news 偏新闻。需配置 Tavily。',
   PowerShell: '运行宿主 PowerShell 独立进程并检查结果；长任务用 TaskOutput/TaskStop。永久删除用 Trash；不可逆操作先确认，非交互时取消。',
   Download: '下载 HTTP(S) 原始字节到指定路径；相对路径基于工作目录，会覆盖已有文件；失败或中断不保留部分下载。',
-  Agent: '启动隔离上下文子任务并返回 agent_id。explore 只读，general 按 write_scopes 或 worktree 执行。run_in_background 立即返回；resume_agent_id 续接私有历史。context.researchQuestions 定义问题契约，AgentReport.findings 按 ID 回传证据结论；reportMaxChars 限制返回预览，完整交接可由 TaskOutput 获取。',
+  Agent: AGENT_TOOL_DESCRIPTION,
   EnterWorktree: '从已提交 HEAD 创建并进入隔离工作树，不自动复制原工作区未提交修改；后续文件工具使用隔离目录，项目记忆仍属于原工作区。',
   ExitWorktree: '退出隔离工作树：apply 检查并应用补丁到原工作区但不自动提交；keep 保留；discard 有改动则归档保留。实际应用成功后的清理告警不表示应重新应用。',
 };