minimal-agent 0.18.7 → 0.18.9

package/src/runtime/agentRuntimeContext.ts

@@ -1,5 +1,7 @@
 import type { Tool, ToolAvailability, ToolCallContext } from '../types.js';
 import type { ToolGate } from '../toolGate.js';
+import { resolveOutputContract, type OutputContract } from './outputContract.js';
+export { WEB_OUTPUT, resolveOutputContract, type OutputContract } from './outputContract.js';
 import { isMemoryToolName } from '../tools/capabilities.js';
 import type { ComputerAutomationIntent } from '../tools/computeruse/computerIntent.js';
 
@@ -26,6 +28,7 @@ export type MemoryAccessInput = MemoryAccess | 'local-owner';
  */
 export interface AgentRuntimeContext {
   readonly surface: AgentSurface;
+  readonly output?: OutputContract;
   /** Concrete frontend identity; surface remains the execution capability class. */
   readonly host?: 'desktop' | 'tui' | 'cli' | 'stream-json' | 'workflow';
   readonly profile: AgentProfile;
@@ -75,6 +78,7 @@ export function createAgentRuntimeContext(
   const { browser: rawBrowser, ...rest } = input;
   return Object.freeze({
     ...rest,
+    output: resolveOutputContract(input.surface, input.output),
     ...(rawBrowser
       ? {
           browser: normalizeBrowserRuntime(rawBrowser),

package/src/runtime/fileLock.js

@@ -0,0 +1,75 @@
+import { mkdir, stat } from 'node:fs/promises';
+import * as fs from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import lockfile from 'proper-lockfile';
+/** Shared heartbeat protocol for local file-backed stores, not a database lock.
+ * Never reclaim legacy regular-file locks: old hosts do not speak this protocol.
+ * proper-lockfile fails closed on compromised ownership (its default handler).
+ */
+export async function acquireStateFileLock(path, options = {}) {
+    const { signal, waitMs = 15_000, label = 'STATE' } = options;
+    signal?.throwIfAborted();
+    const target = resolve(path);
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + waitMs;
+    while (true) {
+        signal?.throwIfAborted();
+        const legacy = await stat(`${target}.lock`).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (legacy?.isFile()) {
+            throw new Error(`${label}_LEGACY_LOCK：请停止旧版本宿主并检查遗留锁：${target}.lock`);
+        }
+        try {
+            let owned = false;
+            let identity;
+            const guardedFs = {
+                ...fs,
+                rmdir(lockPath, callback) {
+                    if (!owned)
+                        return fs.rmdir(lockPath, callback);
+                    // Also guard immediate release, before the next heartbeat could detect
+                    // replacement. Never recursively remove a lock directory.
+                    fs.stat(lockPath, (error, current) => {
+                        if (error || !identity || current.dev !== identity.dev ||
+                            current.ino !== identity.ino || current.birthtimeMs !== identity.birthtimeMs) {
+                            callback(Object.assign(new Error(`锁所有权已丢失：${target}`), { code: 'ECOMPROMISED' }));
+                            return;
+                        }
+                        fs.rmdir(lockPath, callback);
+                    });
+                },
+            };
+            const release = await lockfile.lock(target, {
+                fs: guardedFs,
+                realpath: false,
+                retries: 0,
+                stale: 120_000,
+                update: 10_000,
+            });
+            owned = true;
+            try {
+                identity = await stat(`${target}.lock`);
+            }
+            catch (error) {
+                await release().catch(() => undefined);
+                throw error;
+            }
+            if (signal?.aborted) {
+                await release();
+                signal.throwIfAborted();
+            }
+            return release;
+        }
+        catch (error) {
+            if (error.code !== 'ELOCKED')
+                throw error;
+            if (Date.now() >= deadline)
+                throw new Error(`${label}_LOCK_TIMEOUT：等待文件锁超时：${target}`);
+            await delay(40, undefined, { signal });
+        }
+    }
+}

package/src/runtime/fileLock.ts

@@ -0,0 +1,73 @@
+import { mkdir, stat } from 'node:fs/promises';
+import * as fs from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import lockfile from 'proper-lockfile';
+
+/** Shared heartbeat protocol for local file-backed stores, not a database lock.
+ * Never reclaim legacy regular-file locks: old hosts do not speak this protocol.
+ * proper-lockfile fails closed on compromised ownership (its default handler).
+ */
+export async function acquireStateFileLock(
+  path: string,
+  options: { signal?: AbortSignal; waitMs?: number; label?: string } = {},
+): Promise<() => Promise<void>> {
+  const { signal, waitMs = 15_000, label = 'STATE' } = options;
+  signal?.throwIfAborted();
+  const target = resolve(path);
+  await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + waitMs;
+  while (true) {
+    signal?.throwIfAborted();
+    const legacy = await stat(`${target}.lock`).catch((error) => {
+      if (error.code === 'ENOENT') return null;
+      throw error;
+    });
+    if (legacy?.isFile()) {
+      throw new Error(`${label}_LEGACY_LOCK：请停止旧版本宿主并检查遗留锁：${target}.lock`);
+    }
+    try {
+      let owned = false;
+      let identity: fs.Stats | undefined;
+      const guardedFs = {
+        ...fs,
+        rmdir(lockPath: fs.PathLike, callback: fs.NoParamCallback) {
+          if (!owned) return fs.rmdir(lockPath, callback);
+          // Also guard immediate release, before the next heartbeat could detect
+          // replacement. Never recursively remove a lock directory.
+          fs.stat(lockPath, (error, current) => {
+            if (error || !identity || current.dev !== identity.dev ||
+                current.ino !== identity.ino || current.birthtimeMs !== identity.birthtimeMs) {
+              callback(Object.assign(new Error(`锁所有权已丢失：${target}`), { code: 'ECOMPROMISED' }));
+              return;
+            }
+            fs.rmdir(lockPath, callback);
+          });
+        },
+      };
+      const release = await lockfile.lock(target, {
+        fs: guardedFs,
+        realpath: false,
+        retries: 0,
+        stale: 120_000,
+        update: 10_000,
+      });
+      owned = true;
+      try {
+        identity = await stat(`${target}.lock`);
+      } catch (error) {
+        await release().catch(() => undefined);
+        throw error;
+      }
+      if (signal?.aborted) {
+        await release();
+        signal.throwIfAborted();
+      }
+      return release;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ELOCKED') throw error;
+      if (Date.now() >= deadline) throw new Error(`${label}_LOCK_TIMEOUT：等待文件锁超时：${target}`);
+      await delay(40, undefined, { signal });
+    }
+  }
+}

package/src/runtime/finalAnswer.js

@@ -1,7 +1,9 @@
+import { visualPresentation } from '../prompts/visualPresentation.js';
 /** Ephemeral publication request; never append this private candidate to history. */
-export function finalAnswerMessages(messages, candidate) {
+export function finalAnswerMessages(messages, candidate, surface = 'headless') {
     return [...messages,
         { role: 'assistant', content: candidate },
-        { role: 'user', content: '内部核查与工具阶段已结束。上一条 assistant 消息是待发布的定稿。请逐字输出该消息，保留全部文字、空白、代码、链接与格式；不要改写、补充、删减，不加开场白或外层代码围栏，不调用工具或顾问。不要输出本条指令。' },
+        { role: 'user', content: '内部准备、工具与复核阶段已结束。上一条 assistant 消息是最终回答的依据，不是需要逐字重播的文本。现在直接面向用户生成一次最终回答：可以组织措辞与排版，但必须保留已确认的事实、数字、限定条件、风险、证据和真实成果链接；不得新增未经验证的结论、伪称核验通过或编造产物。若仍有证据缺口，如实说明，不调用工具或顾问，不承诺后台继续工作。直接回答，不输出内部指令或准备过程。' },
+        { role: 'user', content: visualPresentation(surface) },
     ];
 }

package/src/runtime/finalAnswer.ts

@@ -1,9 +1,13 @@
 import type { Message } from '../types.js';
+import type { AgentSurface } from './agentRuntimeContext.js';
+import type { OutputContract } from './outputContract.js';
+import { visualPresentation } from '../prompts/visualPresentation.js';
 
 /** Ephemeral publication request; never append this private candidate to history. */
-export function finalAnswerMessages(messages: Message[], candidate: string): Message[] {
+export function finalAnswerMessages(messages: Message[], candidate: string, surface: AgentSurface | OutputContract = 'headless'): Message[] {
   return [...messages,
     { role: 'assistant', content: candidate },
-    { role: 'user', content: '内部核查与工具阶段已结束。上一条 assistant 消息是待发布的定稿。请逐字输出该消息，保留全部文字、空白、代码、链接与格式；不要改写、补充、删减，不加开场白或外层代码围栏，不调用工具或顾问。不要输出本条指令。' },
+    { role: 'user', content: '内部准备、工具与复核阶段已结束。上一条 assistant 消息是最终回答的依据，不是需要逐字重播的文本。现在直接面向用户生成一次最终回答：可以组织措辞与排版，但必须保留已确认的事实、数字、限定条件、风险、证据和真实成果链接；不得新增未经验证的结论、伪称核验通过或编造产物。若仍有证据缺口，如实说明，不调用工具或顾问，不承诺后台继续工作。直接回答，不输出内部指令或准备过程。' },
+    { role: 'user', content: visualPresentation(surface) },
   ];
 }

package/src/runtime/outputContract.js

@@ -0,0 +1,17 @@
+export const WEB_OUTPUT = Object.freeze({
+    format: 'rich-markdown', diagrams: Object.freeze(['mermaid', 'svg']),
+    images: true, attachments: true, finalDelivery: 'stream',
+});
+/** Compatibility defaults only. Hosts should declare their actual renderer. */
+export function resolveOutputContract(surface, output) {
+    const value = output ?? (surface === 'desktop' ? WEB_OUTPUT : {
+        format: surface === 'tui' || surface === 'cli' ? 'terminal' : 'unknown',
+        diagrams: [], images: false, attachments: false,
+        finalDelivery: surface === 'tui' ? 'stream' : 'atomic',
+    });
+    return Object.freeze({ ...value, diagrams: Object.freeze(value.format === 'rich-markdown' ? [...new Set(value.diagrams)] : []) });
+}
+/** Publication changes tool access, not the renderer or local execution rights. */
+export function toolsForResponsePhase(tools, phase) {
+    return phase === 'publication' ? [] : [...tools];
+}

package/src/runtime/outputContract.ts

@@ -0,0 +1,34 @@
+import type { AgentSurface } from './agentRuntimeContext.js';
+
+/** Trusted host presentation declaration, never an execution permission. */
+export interface OutputContract {
+  readonly format: 'rich-markdown' | 'terminal' | 'structured' | 'unknown';
+  readonly diagrams: readonly ('mermaid' | 'svg')[];
+  readonly images: boolean;
+  readonly attachments: boolean;
+  readonly finalDelivery: 'stream' | 'atomic';
+}
+
+export const WEB_OUTPUT: OutputContract = Object.freeze({
+  format: 'rich-markdown', diagrams: Object.freeze(['mermaid', 'svg'] as const),
+  images: true, attachments: true, finalDelivery: 'stream',
+});
+
+/** Compatibility defaults only. Hosts should declare their actual renderer. */
+export function resolveOutputContract(surface: AgentSurface, output?: OutputContract): OutputContract {
+  const value: OutputContract = output ?? (surface === 'desktop' ? WEB_OUTPUT : {
+    format: surface === 'tui' || surface === 'cli' ? 'terminal' : 'unknown',
+    diagrams: [], images: false, attachments: false,
+    finalDelivery: surface === 'tui' ? 'stream' : 'atomic',
+  });
+  return Object.freeze({ ...value, diagrams: Object.freeze(
+    value.format === 'rich-markdown' ? [...new Set(value.diagrams)] : [],
+  ) });
+}
+
+export type ResponsePhase = 'preparation' | 'publication';
+
+/** Publication changes tool access, not the renderer or local execution rights. */
+export function toolsForResponsePhase<T>(tools: readonly T[], phase: ResponsePhase): T[] {
+  return phase === 'publication' ? [] : [...tools];
+}

package/src/session/runAgentTurn.js

@@ -5,7 +5,8 @@ import { listSessionSummaries, updateSessionMetadata, } from '../context/session
 import { workspaceIndexService } from '../context/workspaceIndex.js';
 import { createPromptCacheContext } from '../llm/promptCache.js';
 import { modelRefFromLegacy } from '../modelRef.js';
-import { buildBaseSystemPrompt, browserPromptRuntime, buildTransientPromptBundle, } from '../prompts/system.js';
+import { browserPromptRuntime, buildTransientPromptBundle, } from '../prompts/system.js';
+import { assembleStablePrompt } from '../prompts/promptAssembly.js';
 import { createAgentRuntimeContext, filterToolsForRuntime, memoryContextFromRuntime, } from '../runtime/agentRuntimeContext.js';
 import { filterToolsForCategories } from '../team/toolPolicy.js';
 import { ALL_TOOLS } from '../tools/index.js';
@@ -119,6 +120,7 @@ deps = {}) {
             // 稳定层进 history[0]（runTurn 每轮重写它，必须逐字节可复现，见 runTurn.ts 的缓存不变量）；
             // 易变层每轮单独计算，仅附加到当前用户消息的模型副本。
             const runtimeContext = createAgentRuntimeContext({
+                output: opts.output,
                 surface: 'headless',
                 profile: 'main',
                 cwd: effectiveCwd,
@@ -146,11 +148,14 @@ deps = {}) {
             const turnTools = provider.source === 'gateway'
                 ? filterToolsForCategories(runtimeTools, effectiveGatewayCategories)
                 : runtimeTools;
-            const systemPrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
+            const systemPrompt = await assembleStablePrompt({ cwd: effectiveCwd, tools: turnTools, runtime: {
+                    surface: runtimeContext.surface, output: runtimeContext.output,
+                } });
             const transientBundle = await buildTransientPromptBundle({
                 cwd: effectiveCwd,
                 tools: turnTools,
                 runtime: {
+                    output: runtimeContext.output,
                     surface: 'headless',
                     cwd: effectiveCwd,
                     workspaceId: workspace?.id,

package/src/session/runAgentTurn.ts

@@ -9,10 +9,10 @@ import { workspaceIndexService } from '../context/workspaceIndex.js';
 import { createPromptCacheContext } from '../llm/promptCache.js';
 import { type ModelRef, modelRefFromLegacy } from '../modelRef.js';
 import {
-  buildBaseSystemPrompt,
   browserPromptRuntime,
   buildTransientPromptBundle,
 } from '../prompts/system.js';
+import { assembleStablePrompt } from '../prompts/promptAssembly.js';
 import {
   createAgentRuntimeContext,
   filterToolsForRuntime,
@@ -31,6 +31,7 @@ import {
 } from './sessionState.js';
 
 export interface RunAgentTurnOptions {
+  output?: import('../runtime/outputContract.js').OutputContract;
   /** Host execution identity: distinct triggers must not reuse completed plugin work. */
   executionId?: string;
   input: string;
@@ -178,6 +179,7 @@ export async function runAgentTurn(
     // 稳定层进 history[0]（runTurn 每轮重写它，必须逐字节可复现，见 runTurn.ts 的缓存不变量）；
     // 易变层每轮单独计算，仅附加到当前用户消息的模型副本。
     const runtimeContext = createAgentRuntimeContext({
+      output: opts.output,
       surface: 'headless',
       profile: 'main',
       cwd: effectiveCwd,
@@ -216,11 +218,14 @@ export async function runAgentTurn(
       provider.source === 'gateway'
         ? filterToolsForCategories(runtimeTools, effectiveGatewayCategories)
         : runtimeTools;
-    const systemPrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
+    const systemPrompt = await assembleStablePrompt({ cwd: effectiveCwd, tools: turnTools, runtime: {
+      surface: runtimeContext.surface, output: runtimeContext.output,
+    } });
     const transientBundle = await buildTransientPromptBundle({
       cwd: effectiveCwd,
       tools: turnTools,
       runtime: {
+        output: runtimeContext.output,
         surface: 'headless',
         cwd: effectiveCwd,
         workspaceId: workspace?.id,

package/src/session/runtimeStore.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { mkdir, open, readFile, readdir, rename, rm, stat, } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { agentStateDir } from '../context/agentHome.js';
+import { acquireStateFileLock } from '../runtime/fileLock.js';
 function segment(value, fallback) {
     return ((value ?? fallback).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120) ||
         fallback);
@@ -20,38 +21,20 @@ export async function withRuntimeFileLock(path, work) {
     const tail = previous.then(() => current);
     queues.set(key, tail);
     await previous.catch(() => undefined);
-    let lockHandle;
-    const lockPath = `${path}.lock`;
+    let unlock;
     try {
-        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-        const deadline = Date.now() + 10_000;
-        while (!lockHandle) {
-            try {
-                lockHandle = await open(lockPath, 'wx', 0o600);
-                await lockHandle.writeFile(`${process.pid}\n${Date.now()}\n`);
-            }
-            catch (error) {
-                if (error.code !== 'EEXIST')
-                    throw error;
-                const age = Date.now() -
-                    (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
-                if (age > 30_000)
-                    await rm(lockPath, { force: true });
-                else if (Date.now() >= deadline)
-                    throw new Error(`runtime lock timeout: ${path}`);
-                else
-                    await new Promise((r) => setTimeout(r, 25));
-            }
-        }
+        unlock = await acquireStateFileLock(key, { label: 'RUNTIME' });
         return await work();
     }
     finally {
-        await lockHandle?.close().catch(() => undefined);
-        if (lockHandle)
-            await rm(lockPath, { force: true }).catch(() => undefined);
-        release();
-        if (queues.get(key) === tail)
-            queues.delete(key);
+        try {
+            await unlock?.();
+        }
+        finally {
+            release();
+            if (queues.get(key) === tail)
+                queues.delete(key);
+        }
     }
 }
 export async function readRuntimeJson(path, fallback) {

package/src/session/runtimeStore.ts

@@ -11,6 +11,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 
 import { agentStateDir } from '../context/agentHome.js';
+import { acquireStateFileLock } from '../runtime/fileLock.js';
 
 export interface RuntimeIdentity {
   workspaceId?: string;
@@ -47,32 +48,17 @@ export async function withRuntimeFileLock<T>(
   const tail = previous.then(() => current);
   queues.set(key, tail);
   await previous.catch(() => undefined);
-  let lockHandle: Awaited<ReturnType<typeof open>> | undefined;
-  const lockPath = `${path}.lock`;
+  let unlock: (() => Promise<void>) | undefined;
   try {
-    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    const deadline = Date.now() + 10_000;
-    while (!lockHandle) {
-      try {
-        lockHandle = await open(lockPath, 'wx', 0o600);
-        await lockHandle.writeFile(`${process.pid}\n${Date.now()}\n`);
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
-        const age =
-          Date.now() -
-          (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
-        if (age > 30_000) await rm(lockPath, { force: true });
-        else if (Date.now() >= deadline)
-          throw new Error(`runtime lock timeout: ${path}`);
-        else await new Promise((r) => setTimeout(r, 25));
-      }
-    }
+    unlock = await acquireStateFileLock(key, { label: 'RUNTIME' });
     return await work();
   } finally {
-    await lockHandle?.close().catch(() => undefined);
-    if (lockHandle) await rm(lockPath, { force: true }).catch(() => undefined);
-    release();
-    if (queues.get(key) === tail) queues.delete(key);
+    try {
+      await unlock?.();
+    } finally {
+      release();
+      if (queues.get(key) === tail) queues.delete(key);
+    }
   }
 }
 

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 分身）
@@ -128,10 +129,10 @@ const SUBAGENT_COMMON_APPENDIX = `# 你是子 agent（fork 分身）
  */
 const PROMPT_CACHE_TTL_MS = 60_000;
 const promptCache = new Map();
-async function buildSubSystemPrompt(cwd, def, allTools, conversationMode = 'private') {
+async function buildSubSystemPrompt(cwd, def, allTools, conversationMode = 'private', output) {
     // Effective capabilities are part of prompt identity; a child must never
     // reuse a cached parent-capability prompt (notably Desktop WebBrowser).
-    const key = `${cwd}::${def.type}::${conversationMode}::${allTools.map((tool) => tool.name).join(',')}`;
+    const key = `${cwd}::${def.type}::${conversationMode}::${JSON.stringify(output ?? null)}::${allTools.map((tool) => tool.name).join(',')}`;
     const hit = promptCache.get(key);
     if (hit && Date.now() - hit.at < PROMPT_CACHE_TTL_MS)
         return hit.value;
@@ -143,7 +144,7 @@ async function buildSubSystemPrompt(cwd, def, allTools, conversationMode = 'priv
         profile: def.type === 'general' ? 'subagent-general' : 'subagent-explore',
         includeProjectInstructions: true, // 子 agent 在同一仓库干活，项目约定必须继承
         includePlugins: false, // 插件是宿主命令面，子 agent 不该被引去激活插件
-        runtime: { conversationMode },
+        runtime: { conversationMode, output },
     });
     const value = [base, SUBAGENT_COMMON_APPENDIX, def.promptAppendix].join('\n\n');
     promptCache.set(key, { value, at: Date.now() });
@@ -298,6 +299,7 @@ async function runAgentTaskImpl(input, signal, ctx, deps = {}) {
         ? 'denied'
         : 'read-only';
     const childRuntime = createAgentRuntimeContext({
+        output: ctx.output,
         surface: 'subagent',
         profile: def.type === 'general' ? 'subagent-general' : 'subagent-explore',
         conversationMode: ctx.conversationMode,
@@ -318,6 +320,7 @@ async function runAgentTaskImpl(input, signal, ctx, deps = {}) {
         includeProjectInstructions: true,
         includePlugins: false,
         runtime: {
+            output: childRuntime.output,
             surface: 'subagent',
             conversationMode: ctx.conversationMode,
             cwd,
@@ -341,10 +344,10 @@ async function runAgentTaskImpl(input, signal, ctx, deps = {}) {
     };
     // ---- 子 history：一条 system（压缩按 role 定位，必须存在）+ runQuery 自己 push 任务书 ----
     const history = deps.initialHistory?.length ? [...deps.initialHistory] : [
-        { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools, ctx.conversationMode) },
+        { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools, ctx.conversationMode, childRuntime.output) },
     ];
     if (deps.initialHistory?.length) {
-        const system = await buildSubSystemPrompt(cwd, def, subTools, ctx.conversationMode);
+        const system = await buildSubSystemPrompt(cwd, def, subTools, ctx.conversationMode, childRuntime.output);
         const index = history.findIndex((message) => message.role === 'system');
         if (index >= 0)
             history[index] = { role: 'system', content: system };

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，提示词缓存友好） ----------------
 
@@ -183,10 +184,11 @@ async function buildSubSystemPrompt(
   def: AgentTypeDef,
   allTools: Tool[],
   conversationMode: ToolCallContext['conversationMode'] = 'private',
+  output?: ToolCallContext['output'],
 ): Promise<string> {
   // Effective capabilities are part of prompt identity; a child must never
   // reuse a cached parent-capability prompt (notably Desktop WebBrowser).
-  const key = `${cwd}::${def.type}::${conversationMode}::${allTools.map((tool) => tool.name).join(',')}`;
+  const key = `${cwd}::${def.type}::${conversationMode}::${JSON.stringify(output ?? null)}::${allTools.map((tool) => tool.name).join(',')}`;
   const hit = promptCache.get(key);
   if (hit && Date.now() - hit.at < PROMPT_CACHE_TTL_MS) return hit.value;
 
@@ -198,7 +200,7 @@ async function buildSubSystemPrompt(
     profile: def.type === 'general' ? 'subagent-general' : 'subagent-explore',
     includeProjectInstructions: true, // 子 agent 在同一仓库干活，项目约定必须继承
     includePlugins: false, // 插件是宿主命令面，子 agent 不该被引去激活插件
-    runtime: { conversationMode },
+    runtime: { conversationMode, output },
   });
   const value = [base, SUBAGENT_COMMON_APPENDIX, def.promptAppendix].join('\n\n');
   promptCache.set(key, { value, at: Date.now() });
@@ -374,6 +376,7 @@ async function runAgentTaskImpl(
     ? 'denied'
     : 'read-only';
   const childRuntime = createAgentRuntimeContext({
+    output: ctx.output,
     surface: 'subagent',
     profile: def.type === 'general' ? 'subagent-general' : 'subagent-explore',
     conversationMode: ctx.conversationMode,
@@ -397,6 +400,7 @@ async function runAgentTaskImpl(
     includeProjectInstructions: true,
     includePlugins: false,
     runtime: {
+      output: childRuntime.output,
       surface: 'subagent',
       conversationMode: ctx.conversationMode,
       cwd,
@@ -421,10 +425,10 @@ async function runAgentTaskImpl(
 
   // ---- 子 history：一条 system（压缩按 role 定位，必须存在）+ runQuery 自己 push 任务书 ----
   const history: RunQueryOptions['history'] = deps.initialHistory?.length ? [...deps.initialHistory] : [
-    { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools, ctx.conversationMode) },
+    { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools, ctx.conversationMode, childRuntime.output) },
   ];
   if (deps.initialHistory?.length) {
-    const system = await buildSubSystemPrompt(cwd, def, subTools, ctx.conversationMode);
+    const system = await buildSubSystemPrompt(cwd, def, subTools, ctx.conversationMode, childRuntime.output);
     const index = history.findIndex((message) => message.role === 'system');
     if (index >= 0) history[index] = { role: 'system', content: system };
     else history.unshift({ role: 'system', content: system });

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,