minimal-agent 0.11.0 → 0.13.0

package/src/memory/turnJournal.js

@@ -0,0 +1,95 @@
+/**
+ * ============================================================
+ *  src/memory/turnJournal.ts —— 「一个用户回合」的会话原文记账
+ * ------------------------------------------------------------
+ *  把 user 输入与本回合最终 assistant 回答写进 `episodes/*.jsonl`，
+ *  给 `SearchConversations` 提供可检索的历史原文。
+ *
+ *  ★ 为什么是独立模块、而不是塞进 loop.ts：
+ *    `runQuery` 不等于「一个用户回合」——子 Agent（tools/agent/agent.ts 直接调
+ *    runQuery，且**携带同一份 workspaceId/sessionId**）和 workflow 的每个 llm/agent 步
+ *    都会各调一次 runQuery。记在那里会把子任务提示词当成「用户说的话」灌进历史检索，
+ *    污染的正是这个功能要保护的东西。
+ *
+ *    也不能只留在 `session/runTurn.ts`：TUI 走的是 `ui/hooks/useChat.ts` → runWithPlugins，
+ *    **根本不经过 runTurn**。此前的后果是 TUI 对话永远不入库，而一次性的
+ *    `.backfill-<ws>.json` 标记又让 SearchConversations 在首次搜索后永久停更 ——
+ *    工具宣称"搜索本机历史会话原文"，实际对 TUI 用户静默失效。
+ *
+ *    所以：实现只有这一份，调用点恰好落在两个真正的「用户回合」边界上
+ *    （runTurn 与 useChat.submit），子 Agent 与 workflow 步一概不记。
+ * ============================================================
+ */
+import { applyEpisodeRetention, episodicMemoryService, finishRetentionSweep, shouldSweepRetention, } from './episodicMemory.js';
+import { memoryService } from './memoryService.js';
+function messageText(message) {
+    if (typeof message.content === 'string')
+        return message.content;
+    if (!Array.isArray(message.content))
+        return '';
+    return message.content
+        .filter((part) => part.type === 'text')
+        .map((part) => part.text)
+        .join('\n');
+}
+function lastAssistantMessage(messages, start) {
+    for (let index = messages.length - 1; index >= start; index -= 1) {
+        if (messages[index]?.role === 'assistant')
+            return messages[index];
+    }
+    return undefined;
+}
+/**
+ * 会话原文的保留清理：节流后台执行，绝不阻塞本回合。
+ * 与 `clipboardImage::pruneOldTempImages` 同款 fire-and-forget，不需要常驻定时器。
+ */
+function sweepRetentionInBackground(workspaceId) {
+    if (!shouldSweepRetention(workspaceId))
+        return;
+    void (async () => {
+        try {
+            const settings = await memoryService.settings();
+            if (!settings.retention)
+                return;
+            await applyEpisodeRetention(workspaceId, settings.retention);
+        }
+        finally {
+            finishRetentionSweep(workspaceId);
+        }
+    })().catch(() => undefined);
+}
+/**
+ * 开一次回合记账。缺权限 / 缺 workspaceId / 缺 sessionId 都返回 null（不记，也不报错）——
+ * 记账是附加能力，绝不能反过来阻断对话。
+ */
+export async function startTurnJournal(input) {
+    const context = input.memoryContext;
+    // 判据是 `!== 'denied'`：只要宿主没有明确拒绝记忆访问就记账，`read-only` 也照记。
+    // 这是**有意放松**的（2026-08-13 明确决定：优先保证检索效果与性能）——收紧成"只有可写
+    // 权限才记"会让 `-p`（默认 read-only）和部分 Desktop 场景的历史检索大面积失效。
+    // 真正的隐私边界由 `denied` 与保留窗口（MemorySettings.retention）负责，不靠这里收窄。
+    if (!context || context.access === 'denied' || !context.workspaceId || !context.sessionId) {
+        return null;
+    }
+    const target = { workspaceId: context.workspaceId, sessionId: context.sessionId };
+    await episodicMemoryService.append({
+        ...target,
+        role: 'user',
+        content: input.userInput,
+        ...(input.userMessageId ? { messageId: input.userMessageId } : {}),
+    }).catch(() => undefined);
+    sweepRetentionInBackground(target.workspaceId);
+    return {
+        async finish(history, startIndex) {
+            const assistant = lastAssistantMessage(history, startIndex);
+            const content = assistant ? messageText(assistant) : '';
+            if (!content)
+                return;
+            await episodicMemoryService.append({
+                ...target,
+                role: 'assistant',
+                content,
+            }).catch(() => undefined);
+        },
+    };
+}

package/src/memory/turnJournal.ts

@@ -0,0 +1,120 @@
+/**
+ * ============================================================
+ *  src/memory/turnJournal.ts —— 「一个用户回合」的会话原文记账
+ * ------------------------------------------------------------
+ *  把 user 输入与本回合最终 assistant 回答写进 `episodes/*.jsonl`，
+ *  给 `SearchConversations` 提供可检索的历史原文。
+ *
+ *  ★ 为什么是独立模块、而不是塞进 loop.ts：
+ *    `runQuery` 不等于「一个用户回合」——子 Agent（tools/agent/agent.ts 直接调
+ *    runQuery，且**携带同一份 workspaceId/sessionId**）和 workflow 的每个 llm/agent 步
+ *    都会各调一次 runQuery。记在那里会把子任务提示词当成「用户说的话」灌进历史检索，
+ *    污染的正是这个功能要保护的东西。
+ *
+ *    也不能只留在 `session/runTurn.ts`：TUI 走的是 `ui/hooks/useChat.ts` → runWithPlugins，
+ *    **根本不经过 runTurn**。此前的后果是 TUI 对话永远不入库，而一次性的
+ *    `.backfill-<ws>.json` 标记又让 SearchConversations 在首次搜索后永久停更 ——
+ *    工具宣称"搜索本机历史会话原文"，实际对 TUI 用户静默失效。
+ *
+ *    所以：实现只有这一份，调用点恰好落在两个真正的「用户回合」边界上
+ *    （runTurn 与 useChat.submit），子 Agent 与 workflow 步一概不记。
+ * ============================================================
+ */
+
+import {
+  applyEpisodeRetention,
+  episodicMemoryService,
+  finishRetentionSweep,
+  shouldSweepRetention,
+} from './episodicMemory.js';
+import { memoryService } from './memoryService.js';
+import type { Message } from '../types.js';
+
+export interface TurnJournalInput {
+  memoryContext?: {
+    access?: string;
+    workspaceId?: string;
+    sessionId?: string;
+  };
+  userInput: string;
+  userMessageId?: string;
+}
+
+export interface TurnJournal {
+  /** 回合收尾时调用：从 history 里取本回合最后一条 assistant 消息入库。 */
+  finish(history: readonly Message[], startIndex: number): Promise<void>;
+}
+
+function messageText(message: Message): string {
+  if (typeof message.content === 'string') return message.content;
+  if (!Array.isArray(message.content)) return '';
+  return message.content
+    .filter((part): part is Extract<typeof part, { type: 'text' }> => part.type === 'text')
+    .map((part) => part.text)
+    .join('\n');
+}
+
+function lastAssistantMessage(
+  messages: readonly Message[],
+  start: number,
+): Message | undefined {
+  for (let index = messages.length - 1; index >= start; index -= 1) {
+    if (messages[index]?.role === 'assistant') return messages[index];
+  }
+  return undefined;
+}
+
+/**
+ * 会话原文的保留清理：节流后台执行，绝不阻塞本回合。
+ * 与 `clipboardImage::pruneOldTempImages` 同款 fire-and-forget，不需要常驻定时器。
+ */
+function sweepRetentionInBackground(workspaceId: string): void {
+  if (!shouldSweepRetention(workspaceId)) return;
+  void (async () => {
+    try {
+      const settings = await memoryService.settings();
+      if (!settings.retention) return;
+      await applyEpisodeRetention(workspaceId, settings.retention);
+    } finally {
+      finishRetentionSweep(workspaceId);
+    }
+  })().catch(() => undefined);
+}
+
+/**
+ * 开一次回合记账。缺权限 / 缺 workspaceId / 缺 sessionId 都返回 null（不记，也不报错）——
+ * 记账是附加能力，绝不能反过来阻断对话。
+ */
+export async function startTurnJournal(
+  input: TurnJournalInput,
+): Promise<TurnJournal | null> {
+  const context = input.memoryContext;
+  // 判据是 `!== 'denied'`：只要宿主没有明确拒绝记忆访问就记账，`read-only` 也照记。
+  // 这是**有意放松**的（2026-08-13 明确决定：优先保证检索效果与性能）——收紧成"只有可写
+  // 权限才记"会让 `-p`（默认 read-only）和部分 Desktop 场景的历史检索大面积失效。
+  // 真正的隐私边界由 `denied` 与保留窗口（MemorySettings.retention）负责，不靠这里收窄。
+  if (!context || context.access === 'denied' || !context.workspaceId || !context.sessionId) {
+    return null;
+  }
+  const target = { workspaceId: context.workspaceId, sessionId: context.sessionId };
+  await episodicMemoryService.append({
+    ...target,
+    role: 'user',
+    content: input.userInput,
+    ...(input.userMessageId ? { messageId: input.userMessageId } : {}),
+  }).catch(() => undefined);
+  sweepRetentionInBackground(target.workspaceId);
+
+  return {
+    async finish(history, startIndex) {
+      const assistant = lastAssistantMessage(history, startIndex);
+      const content = assistant ? messageText(assistant) : '';
+      if (!content) return;
+      await episodicMemoryService.append({
+        ...target,
+        role: 'assistant',
+        content,
+      }).catch(() => undefined);
+    },
+  };
+}

package/src/memory/types.ts

@@ -71,10 +71,26 @@ export interface MemoryReviewWindows {
   decision: number;
 }
 
+/**
+ * 会话原文日志（`episodes/*.jsonl`）的保留窗口。
+ *
+ * 记忆条目（records）是用户明确授权保存的稳定事实，只有用户能删；会话原文日志是为了
+ * `SearchConversations` 而留的**全量对话副本**，性质完全不同——它必须有保留上限，否则
+ * 明文对话会无限累积（仓库里其它 append-only 存储都有清理，只有它没有）。
+ */
+export interface MemoryRetention {
+  /** 超过这个天数的会话原文自动清理。 */
+  episodeDays: number;
+  /** 单个工作区的会话原文总体积上限（MB），先到者先触发。 */
+  episodeMaxMegabytes: number;
+}
+
 export interface MemorySettings {
   autoRemember: boolean;
   /** Optional on the public wire type for pre-v2 desktop clients. */
   reviewAfterDays?: MemoryReviewWindows;
+  /** Optional on the wire so pre-retention clients keep deserializing. */
+  retention?: MemoryRetention;
 }
 
 export interface MemoryDiagnostic {

package/src/plugins/pluginApi.ts

@@ -21,9 +21,21 @@
  * ============================================================
  */
 
-import type { LoopEvent, Message, Provider, ToolCallContext } from '../types.js';
+import type { ContextBundle } from '../context/contextBundle.js';
+import type { AgentRuntimeContext } from '../runtime/agentRuntimeContext.js';
+import type {
+  RunAgentTurnOptions,
+  RunAgentTurnResult,
+} from '../session/runAgentTurn.js';
 import type { SessionState } from '../session/sessionState.js';
-import type { RunAgentTurnOptions, RunAgentTurnResult } from '../session/runAgentTurn.js';
+import type {
+  LoopEvent,
+  Message,
+  PromptCacheContext,
+  Provider,
+  ToolCallContext,
+  ToolResult,
+} from '../types.js';
 
 /** 框架传给插件的运行时上下文（仅暴露执行 LLM/工具 所需的最小集合）。 */
 export interface PluginContext {
@@ -38,12 +50,23 @@ export interface PluginContext {
   maxTurns?: number;
   /** 当前回合的瞬时外部上下文；插件不得把它持久化到 history。 */
   transientContext?: string;
-  transientBundle?: import('../context/contextBundle.js').ContextBundle;
-  promptCache?: import('../types.js').PromptCacheContext;
+  transientBundle?: ContextBundle;
+  promptCache?: PromptCacheContext;
   /** Canonical host-issued trust context; plugins may narrow it but never elevate it. */
-  runtimeContext?: import('../runtime/agentRuntimeContext.js').AgentRuntimeContext;
+  runtimeContext?: AgentRuntimeContext;
   /** Host tool names are an upper bound. Plugins may narrow, never expand. */
   allowedTools?: readonly string[];
+  /**
+   * Host tool dispatcher. Rich plugins must use the same injected executor as
+   * the parent run so tests, embedders and host-specific dispatch remain on one
+   * execution path.
+   */
+  executeTool?: (
+    name: string,
+    rawArgsJson: string,
+    signal?: AbortSignal,
+    context?: ToolCallContext,
+  ) => Promise<ToolResult>;
   /**
    * 宿主的**授权与可见性上下文**，原样转交给工具层（`executeTool` 第四参）。
    *
@@ -100,7 +123,8 @@ export interface PluginEvent {
 export interface PluginApi {
   activate?(
     ctx: PluginRuntimeContext,
-  ): Promise<void | (() => void)> | void | (() => void);
+  ): // biome-ignore lint/suspicious/noConfusingVoidType: lifecycle hooks intentionally accept synchronous void or an async disposer.
+  Promise<void | (() => void)> | void | (() => void);
   runCommand?(
     commandName: string,
     args: string,

package/src/plugins/pluginRunner.js

@@ -9,13 +9,13 @@
  *    2) / 输入 → discoverPlugins → resolveCommand
  *       a) 命中插件且其 plugin.ts 暴露 runCommand → 让 plugin.ts 接管
  *       b) 命中插件但只有声明式 commands/*.md → 把 prompt 拼好喂给 runQuery
- *       c) 未命中 → 静默透传 runQuery（/ 只是激活前缀，不是严格命令系统；
- *          未知的 /xxx 当普通用户输入处理，不报错）
+ *       c) 未命中 -> warning 提示未知命令后透传 runQuery（/ 只是激活前缀，
+ *          不是严格命令系统；未知的 /xxx 当普通用户输入处理，不报错）
  * ============================================================
  */
-import { discoverPlugins, resolveCommand, buildCommandInput, } from './commandRouter.js';
-import { loadPluginApi } from './pluginLoader.js';
 import { runQuery } from '../loop.js';
+import { buildCommandInput, discoverPlugins, listAvailableCommands, resolveCommand, } from './commandRouter.js';
+import { loadPluginApi } from './pluginLoader.js';
 export async function* runWithPlugins(userInput, options) {
     const { provider, history, signal } = options;
     const isSlashCommand = userInput.trimStart().startsWith('/');
@@ -30,6 +30,7 @@ export async function* runWithPlugins(userInput, options) {
             sessionState: options.sessionState,
             chat: options.chat,
             executeTool: options.executeTool,
+            commitFormalDelivery: options.commitFormalDelivery,
             toolGate: options.toolGate,
             transientContext: options.transientContext,
             transientBundle: options.transientBundle,
@@ -55,10 +56,21 @@ export async function* runWithPlugins(userInput, options) {
     await discoverPlugins();
     const matched = resolveCommand(userInput);
     if (!matched) {
-        // 未命中任何插件命令 → 静默透传 runQuery。
-        // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统。
-        // 用户可能输入 /init、/help、/任何东西 —— 不匹配就当普通对话处理，
-        // 让 LLM 自行理解意图。不报错、不提示、不打断用户体验。
+        // 未命中任何插件命令 -> 提示后透传 runQuery。
+        // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统：
+        // 不匹配仍当普通对话处理，让 LLM 自行理解意图。但 -p 等无人值守场景里
+        // 拼错的 /reseach 会被静默当文本烧一轮 LLM（实战：用户以为在跑工作流，
+        // 实际什么都没发生）--先 warning 列出已注册命令，零成本纠正拼写。
+        const trimmedUnknown = userInput.trimStart();
+        const spaceUnknown = trimmedUnknown.indexOf(' ', 1);
+        const unknownCmd = (spaceUnknown >= 0 ? trimmedUnknown.slice(1, spaceUnknown) : trimmedUnknown.slice(1)).trim();
+        if (unknownCmd) {
+            const available = listAvailableCommands().map((c) => c.command);
+            yield {
+                type: 'warning',
+                message: `未知命令 /${unknownCmd}（已注册：${available.length ? available.join('、') : '无'}），已按普通对话处理。`,
+            };
+        }
         yield* runQuery(userInput, {
             provider,
             history,
@@ -69,6 +81,7 @@ export async function* runWithPlugins(userInput, options) {
             sessionState: options.sessionState,
             chat: options.chat,
             executeTool: options.executeTool,
+            commitFormalDelivery: options.commitFormalDelivery,
             toolGate: options.toolGate,
             transientContext: options.transientContext,
             transientBundle: options.transientBundle,
@@ -104,6 +117,7 @@ export async function* runWithPlugins(userInput, options) {
             promptCache: options.promptCache,
             runtimeContext: options.runtimeContext,
             allowedTools: options.allowedTools,
+            executeTool: options.executeTool,
             // ⚠️ 宿主授权上下文**必须**跟着走。这一处曾经漏掉，而下面两条 runQuery 路径
             // 都带着它 —— 于是富插件成了三条路里唯一拿不到 browserRun/computerRun 的那条。
             // 后果不是"少个字段"：workflow 里调 ComputerUse 恒返回「当前宿主未启用
@@ -129,6 +143,7 @@ export async function* runWithPlugins(userInput, options) {
         sessionState: options.sessionState,
         chat: options.chat,
         executeTool: options.executeTool,
+        commitFormalDelivery: options.commitFormalDelivery,
         toolGate: options.toolGate,
         transientContext: options.transientContext,
         transientBundle: options.transientBundle,

package/src/plugins/pluginRunner.ts

@@ -9,20 +9,21 @@
  *    2) / 输入 → discoverPlugins → resolveCommand
  *       a) 命中插件且其 plugin.ts 暴露 runCommand → 让 plugin.ts 接管
  *       b) 命中插件但只有声明式 commands/*.md → 把 prompt 拼好喂给 runQuery
- *       c) 未命中 → 静默透传 runQuery（/ 只是激活前缀，不是严格命令系统；
- *          未知的 /xxx 当普通用户输入处理，不报错）
+ *       c) 未命中 -> warning 提示未知命令后透传 runQuery（/ 只是激活前缀，
+ *          不是严格命令系统；未知的 /xxx 当普通用户输入处理，不报错）
  * ============================================================
  */
 
+import { type RunQueryOptions, runQuery } from '../loop.js';
+import type { LoopEvent, Message, Provider } from '../types.js';
 import {
+  buildCommandInput,
   discoverPlugins,
+  listAvailableCommands,
   resolveCommand,
-  buildCommandInput,
 } from './commandRouter.js';
-import { loadPluginApi } from './pluginLoader.js';
-import { runQuery, type RunQueryOptions } from '../loop.js';
-import type { LoopEvent, Message, Provider } from '../types.js';
 import type { PluginEvent } from './pluginApi.js';
+import { loadPluginApi } from './pluginLoader.js';
 
 export interface PluginRunnerOptions {
   provider: Provider;
@@ -38,6 +39,7 @@ export interface PluginRunnerOptions {
    */
   chat?: RunQueryOptions['chat'];
   executeTool?: RunQueryOptions['executeTool'];
+  commitFormalDelivery?: RunQueryOptions['commitFormalDelivery'];
   /** 工具执行闸门（生产用）：透传给 runQuery。见 src/toolGate.ts。 */
   toolGate?: RunQueryOptions['toolGate'];
   transientContext?: RunQueryOptions['transientContext'];
@@ -77,6 +79,7 @@ export async function* runWithPlugins(
       sessionState: options.sessionState,
       chat: options.chat,
       executeTool: options.executeTool,
+      commitFormalDelivery: options.commitFormalDelivery,
       toolGate: options.toolGate,
       transientContext: options.transientContext,
       transientBundle: options.transientBundle,
@@ -104,10 +107,23 @@ export async function* runWithPlugins(
   const matched = resolveCommand(userInput);
 
   if (!matched) {
-    // 未命中任何插件命令 → 静默透传 runQuery。
-    // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统。
-    // 用户可能输入 /init、/help、/任何东西 —— 不匹配就当普通对话处理，
-    // 让 LLM 自行理解意图。不报错、不提示、不打断用户体验。
+    // 未命中任何插件命令 -> 提示后透传 runQuery。
+    // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统：
+    // 不匹配仍当普通对话处理，让 LLM 自行理解意图。但 -p 等无人值守场景里
+    // 拼错的 /reseach 会被静默当文本烧一轮 LLM（实战：用户以为在跑工作流，
+    // 实际什么都没发生）--先 warning 列出已注册命令，零成本纠正拼写。
+    const trimmedUnknown = userInput.trimStart();
+    const spaceUnknown = trimmedUnknown.indexOf(' ', 1);
+    const unknownCmd = (
+      spaceUnknown >= 0 ? trimmedUnknown.slice(1, spaceUnknown) : trimmedUnknown.slice(1)
+    ).trim();
+    if (unknownCmd) {
+      const available = listAvailableCommands().map((c) => c.command);
+      yield {
+        type: 'warning',
+        message: `未知命令 /${unknownCmd}（已注册：${available.length ? available.join('、') : '无'}），已按普通对话处理。`,
+      };
+    }
     yield* runQuery(userInput, {
       provider,
       history,
@@ -118,6 +134,7 @@ export async function* runWithPlugins(
       sessionState: options.sessionState,
       chat: options.chat,
       executeTool: options.executeTool,
+      commitFormalDelivery: options.commitFormalDelivery,
       toolGate: options.toolGate,
       transientContext: options.transientContext,
       transientBundle: options.transientBundle,
@@ -154,6 +171,7 @@ export async function* runWithPlugins(
       promptCache: options.promptCache,
       runtimeContext: options.runtimeContext,
       allowedTools: options.allowedTools,
+      executeTool: options.executeTool,
       // ⚠️ 宿主授权上下文**必须**跟着走。这一处曾经漏掉，而下面两条 runQuery 路径
       // 都带着它 —— 于是富插件成了三条路里唯一拿不到 browserRun/computerRun 的那条。
       // 后果不是"少个字段"：workflow 里调 ComputerUse 恒返回「当前宿主未启用
@@ -180,10 +198,11 @@ export async function* runWithPlugins(
     sessionState: options.sessionState,
     chat: options.chat,
     executeTool: options.executeTool,
+    commitFormalDelivery: options.commitFormalDelivery,
     toolGate: options.toolGate,
-      transientContext: options.transientContext,
-      transientBundle: options.transientBundle,
-      promptCache: options.promptCache,
+    transientContext: options.transientContext,
+    transientBundle: options.transientBundle,
+    promptCache: options.promptCache,
     userAttachments: options.userAttachments,
     userMessageId: options.userMessageId,
     userBrowserReferences: options.userBrowserReferences,

package/src/prompts/policyRegistry.js

@@ -84,6 +84,8 @@ const ROUTABLE_TOOLS = [
     'ComputerUse', 'WebBrowser', 'WebFetch', 'WebSearch',
     'Download', 'Read', 'Glob', 'Grep', 'Edit', 'MultiEdit', 'Write', 'Bash',
     'NotebookEdit', 'LSP', 'PowerShell', 'TaskOutput', 'TaskStop',
+    'Trash', 'TaskCreate', 'TaskGet', 'TaskUpdate', 'TaskList', 'Skill',
+    'EnterWorktree', 'ExitWorktree', 'TerminalCapture', 'Snip',
 ];
 const PARAMETERIZED_TOOLS = [
     ...ROUTABLE_TOOLS, ...MEMORY_TOOLS, 'AskUserQuestion', 'Advisor', 'Agent',
@@ -173,6 +175,31 @@ const CAPABILITY_POLICIES = [
         requires: ['background.process'],
         render: () => '- 后台任务按当前会话隔离。启动后保存 task_id；TaskOutput 可阻塞等待新输出，避免高频轮询；任务不再需要或需要中止时使用 TaskStop，不遗留服务进程。',
     },
+    {
+        id: 'capability.trash', layer: 'capability', profiles: ['main', 'subagent-general'], source: '06',
+        requiresTools: ['Trash'],
+        render: () => '- 删除项目文件或目录使用 Trash 移入系统回收站；清理 Git 未跟踪文件使用 Trash(action="git-clean")。Bash/PowerShell 不执行绕过回收站的永久删除命令。',
+    },
+    {
+        id: 'capability.task-management', layer: 'capability', profiles: ALL_PROFILES, source: '06',
+        requires: ['task.management'],
+        render: () => '- 多阶段、跨回合或存在依赖关系的工作用 TaskCreate/TaskUpdate 保持任务图；开始前检查 blockedBy，完成验证后才标记 completed。单步工作不必创建任务。',
+    },
+    {
+        id: 'capability.skill-invoke', layer: 'capability', profiles: ALL_PROFILES, source: '07',
+        requiresTools: ['Skill'],
+        render: () => '- 需求匹配已安装 Skill 或用户明确点名 Skill 时，用 Skill 按精确名称加载完整 SKILL.md；其中引用的资源再按需 Read，不预加载整个目录。',
+    },
+    {
+        id: 'capability.session-worktree', layer: 'capability', profiles: MAIN_PROFILE, source: '06',
+        requires: ['worktree.session'],
+        render: () => '- 主任务需要隔离试验时可 EnterWorktree；完成后用 ExitWorktree apply/keep/discard 收口。apply 必须通过补丁检查且不自动提交；discard 不永久丢弃已有成果。',
+    },
+    {
+        id: 'capability.terminal-capture', layer: 'capability', profiles: MAIN_PROFILE, source: '06',
+        requiresTools: ['TerminalCapture'],
+        render: () => '- 只有确需查看当前 TUI 屏幕状态时使用 TerminalCapture；项目命令输出仍通过 Bash/TaskOutput 获取。',
+    },
     {
         id: 'capability.web-research', layer: 'capability', profiles: ALL_PROFILES, source: '04',
         requiresAnyTools: ['WebSearch', 'WebFetch'],
@@ -205,7 +232,34 @@ const CAPABILITY_POLICIES = [
     {
         id: 'capability.advisor', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
         requiresTools: ['Advisor'],
-        render: () => '- Advisor 是可选的第二意见：复杂架构决策、高风险修改、反复受阻、证据冲突或用户明确要求时再调用。普通实现和收尾不固定咨询；顾问不可用不得阻塞主流程。咨询前先落盘成果，顾问意见与实测冲突时以实测为准并明确核对冲突。',
+        // 注意：文本内不得硬编码其他工具名（如 PresentResult），否则该工具缺席时这里
+        // 成为唯一残留的「幽灵引用」——capability 规则交叉引用必须在 toolNames 条件下拼接。
+        render: ({ toolNames }) => `- Advisor（顾问模型）使用规则：
+  **在动手之前问，不是出事之后问**：顾问的价值在方案定型前最大——代码一旦写下去，换方向的成本就变了。
+  「摸清现状」不算动手（找文件、读代码、跑命令看状态，这些先做完再问）；
+  「动手」指写文件、认定某个解释、在假设上继续搭、给出结论。
+  **当 Advisor 工具出现在当前可用工具列表中时**，以下 5 种场景必须主动调用，不要等到出错或用户问了才想起来：
+  1. 方案/开发计划成型后、动手执行前（先让顾问挑刺，避免做一半才发现方向错了）
+  2. 最终结果提交用户前${toolNames.has('PresentResult') ? '（PresentResult 之前）' : ''}：代码评审、评估报告、技术选型、重构方案等所有"给出结论"的场合
+  3. 连续 2 次遇到同类错误或修复不收敛（死循环前兆，立刻换思路）
+  4. 同一轮内用户第 2 次反馈不满意（不要在原地打转，先找顾问换角度）
+  5. 涉及安全性、数据丢失、不可逆操作的决策（顾问双保险）
+  调用时 note 里必须包含：你的完整结论/方案 + 关键代码原文或证据摘要，不要只写结论摘要。
+  场景 2 有个前置动作：**先把产出落盘再调用**（写文件、保存结果）。这一次调用要花时间，
+  回合若在此期间结束，写下的文件还在，没写的答案就没了。
+  长任务至少咨询两次：方案定型前一次、宣布完成前一次；短的、下一步由刚读到的输出直接决定的任务，一次即可。
+  **顾问返回后必须做验证，不能盲信：**
+  - 顾问的意见只是第二视角的候选诊断，不是事实。它没有工具访问权，无法自行验证。
+  - 对顾问提出的每一条严重问题/反例，都必须回到代码、测试、原始资料或工具输出核实。
+  - 核实后分类：真问题（有证据支撑）、误报（被事实推翻）、待澄清（暂时无法验证）。
+  - 未经核实的顾问意见，不得写成确定结论；与实测冲突时，以实测为准。
+  - ⚠️ 但「自测通过」不等于顾问说错了：那往往只说明你的测试没测到它指的那一层。
+  - 与你已掌握的证据冲突时**不要默默改方向**：再调一次顾问，把冲突摆出来
+    （「我实测是 X，你建议 Y，哪个约束更硬？」）。它看过你的证据但可能低估了，
+    一次对账远比顺着错误分支做下去便宜。
+  **如果 Advisor 不在工具列表中**（未配置、已关闭、仅手动模式或当前不可用）：视为用户明确选择跳过，不得尝试调用，也不阻塞流程，无需在输出中专门说明。
+  咨询前先落盘成果，顾问意见与实测冲突时以实测为准并明确核对冲突。
+  补充：任何评审/评估/结论输出前，先用 adversarial-review 的方法论自我审查（拆原子主张、反向提问、去现场核对），再决定是否需要顾问。`,
     },
     {
         id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',

package/src/prompts/policyRegistry.ts

@@ -133,6 +133,8 @@ const ROUTABLE_TOOLS = [
   'ComputerUse', 'WebBrowser', 'WebFetch', 'WebSearch',
   'Download', 'Read', 'Glob', 'Grep', 'Edit', 'MultiEdit', 'Write', 'Bash',
   'NotebookEdit', 'LSP', 'PowerShell', 'TaskOutput', 'TaskStop',
+  'Trash', 'TaskCreate', 'TaskGet', 'TaskUpdate', 'TaskList', 'Skill',
+  'EnterWorktree', 'ExitWorktree', 'TerminalCapture', 'Snip',
 ];
 
 const PARAMETERIZED_TOOLS = [
@@ -215,6 +217,31 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
     requires: ['background.process'],
     render: () => '- 后台任务按当前会话隔离。启动后保存 task_id；TaskOutput 可阻塞等待新输出，避免高频轮询；任务不再需要或需要中止时使用 TaskStop，不遗留服务进程。',
   },
+  {
+    id: 'capability.trash', layer: 'capability', profiles: ['main','subagent-general'], source: '06',
+    requiresTools: ['Trash'],
+    render: () => '- 删除项目文件或目录使用 Trash 移入系统回收站；清理 Git 未跟踪文件使用 Trash(action="git-clean")。Bash/PowerShell 不执行绕过回收站的永久删除命令。',
+  },
+  {
+    id: 'capability.task-management', layer: 'capability', profiles: ALL_PROFILES, source: '06',
+    requires: ['task.management'],
+    render: () => '- 多阶段、跨回合或存在依赖关系的工作用 TaskCreate/TaskUpdate 保持任务图；开始前检查 blockedBy，完成验证后才标记 completed。单步工作不必创建任务。',
+  },
+  {
+    id: 'capability.skill-invoke', layer: 'capability', profiles: ALL_PROFILES, source: '07',
+    requiresTools: ['Skill'],
+    render: () => '- 需求匹配已安装 Skill 或用户明确点名 Skill 时，用 Skill 按精确名称加载完整 SKILL.md；其中引用的资源再按需 Read，不预加载整个目录。',
+  },
+  {
+    id: 'capability.session-worktree', layer: 'capability', profiles: MAIN_PROFILE, source: '06',
+    requires: ['worktree.session'],
+    render: () => '- 主任务需要隔离试验时可 EnterWorktree；完成后用 ExitWorktree apply/keep/discard 收口。apply 必须通过补丁检查且不自动提交；discard 不永久丢弃已有成果。',
+  },
+  {
+    id: 'capability.terminal-capture', layer: 'capability', profiles: MAIN_PROFILE, source: '06',
+    requiresTools: ['TerminalCapture'],
+    render: () => '- 只有确需查看当前 TUI 屏幕状态时使用 TerminalCapture；项目命令输出仍通过 Bash/TaskOutput 获取。',
+  },
   {
     id: 'capability.web-research', layer: 'capability', profiles: ALL_PROFILES, source: '04',
     requiresAnyTools: ['WebSearch', 'WebFetch'],
@@ -247,7 +274,34 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
   {
     id: 'capability.advisor', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
     requiresTools: ['Advisor'],
-    render: () => '- Advisor 是可选的第二意见：复杂架构决策、高风险修改、反复受阻、证据冲突或用户明确要求时再调用。普通实现和收尾不固定咨询；顾问不可用不得阻塞主流程。咨询前先落盘成果，顾问意见与实测冲突时以实测为准并明确核对冲突。',
+    // 注意：文本内不得硬编码其他工具名（如 PresentResult），否则该工具缺席时这里
+    // 成为唯一残留的「幽灵引用」——capability 规则交叉引用必须在 toolNames 条件下拼接。
+    render: ({ toolNames }) => `- Advisor（顾问模型）使用规则：
+  **在动手之前问，不是出事之后问**：顾问的价值在方案定型前最大——代码一旦写下去，换方向的成本就变了。
+  「摸清现状」不算动手（找文件、读代码、跑命令看状态，这些先做完再问）；
+  「动手」指写文件、认定某个解释、在假设上继续搭、给出结论。
+  **当 Advisor 工具出现在当前可用工具列表中时**，以下 5 种场景必须主动调用，不要等到出错或用户问了才想起来：
+  1. 方案/开发计划成型后、动手执行前（先让顾问挑刺，避免做一半才发现方向错了）
+  2. 最终结果提交用户前${toolNames.has('PresentResult') ? '（PresentResult 之前）' : ''}：代码评审、评估报告、技术选型、重构方案等所有"给出结论"的场合
+  3. 连续 2 次遇到同类错误或修复不收敛（死循环前兆，立刻换思路）
+  4. 同一轮内用户第 2 次反馈不满意（不要在原地打转，先找顾问换角度）
+  5. 涉及安全性、数据丢失、不可逆操作的决策（顾问双保险）
+  调用时 note 里必须包含：你的完整结论/方案 + 关键代码原文或证据摘要，不要只写结论摘要。
+  场景 2 有个前置动作：**先把产出落盘再调用**（写文件、保存结果）。这一次调用要花时间，
+  回合若在此期间结束，写下的文件还在，没写的答案就没了。
+  长任务至少咨询两次：方案定型前一次、宣布完成前一次；短的、下一步由刚读到的输出直接决定的任务，一次即可。
+  **顾问返回后必须做验证，不能盲信：**
+  - 顾问的意见只是第二视角的候选诊断，不是事实。它没有工具访问权，无法自行验证。
+  - 对顾问提出的每一条严重问题/反例，都必须回到代码、测试、原始资料或工具输出核实。
+  - 核实后分类：真问题（有证据支撑）、误报（被事实推翻）、待澄清（暂时无法验证）。
+  - 未经核实的顾问意见，不得写成确定结论；与实测冲突时，以实测为准。
+  - ⚠️ 但「自测通过」不等于顾问说错了：那往往只说明你的测试没测到它指的那一层。
+  - 与你已掌握的证据冲突时**不要默默改方向**：再调一次顾问，把冲突摆出来
+    （「我实测是 X，你建议 Y，哪个约束更硬？」）。它看过你的证据但可能低估了，
+    一次对账远比顺着错误分支做下去便宜。
+  **如果 Advisor 不在工具列表中**（未配置、已关闭、仅手动模式或当前不可用）：视为用户明确选择跳过，不得尝试调用，也不阻塞流程，无需在输出中专门说明。
+  咨询前先落盘成果，顾问意见与实测冲突时以实测为准并明确核对冲突。
+  补充：任何评审/评估/结论输出前，先用 adversarial-review 的方法论自我审查（拆原子主张、反向提问、去现场核对），再决定是否需要顾问。`,
   },
   {
     id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',