dsh-plugin-tool-management 0.9.1 → 0.11.0

package/lib/subagents/service.js

@@ -1,12 +1,13 @@
 // src/subagents/service.ts —— 轻量子智能体：人设发现（TTL 扫描）+ 官方 ctx.subagents.start 薄封装。
 // 设计 §3：人设 = $DSH_HOME/tool-management/agents/<name>.md（frontmatter 可选，缺省派生）；v1 串行运行；
-// spawn provider 缺失时经 createRequire 挂载官方 dsh-subagent-spawn-in-process（宿主侧包）。
+// provider 缺失时经 createRequire 挂载宿主侧包：`spawn`（新会话，默认）与 `fork`（继承本次会话）。
 //
 // v0.4 目录变更：人设由 `$DSH_HOME/subagents/` 搬到 `$DSH_HOME/tool-management/agents/`
 // （插件产生的文件统一收在 tool-management/ 下）。旧目录在首次扫描时搬入，见 relocateLegacyPersonas。
 import { createRequire } from 'node:module';
-import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { isValidSegment } from '../paths.js';
 import { resolveDshHome } from '../skills/core.js';
 import { listTrashEntries, moveOutOfTrash, moveToTrash, purgeTrashEntry, readTrashEntry } from '../hub.js';
 import { expandUploads, planPersonaImport } from '../imports/upload.js';
@@ -97,17 +98,27 @@ export function parsePresetToolRules(frontmatter) {
     }
     return Object.keys(rules).length ? rules : undefined;
 }
-/** 行式 frontmatter 解析：只认 description / provider / model / tools / toolsDeny / toolsByPreset。 */
+/** 行式 frontmatter 解析：只认 description / provider / model / tools / toolsDeny / toolsByPreset / catalogDepth / output。 */
 export function parsePersona(raw, fallbackName) {
     const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
     const data = {};
+    const outputLines = [];
     let body = raw;
     let toolsByPreset;
     if (m) {
         for (const line of m[1].split(/\r?\n/)) {
             const kv = /^([A-Za-z_-]+)\s*:\s*(.*)$/.exec(line.trim());
-            if (kv)
-                data[kv[1].toLowerCase()] = kv[2].trim();
+            if (!kv)
+                continue;
+            const key = kv[1].toLowerCase();
+            // `output:` 是**可重复**的键（一条要求一行，按顺序收集）。frontmatter 是逐行解析的，
+            // 多行契约塞不进一个值里；写成重复键比引入块标量语法简单，也一眼看得懂。
+            if (key === 'output') {
+                if (kv[2].trim() !== '')
+                    outputLines.push(kv[2].trim());
+                continue;
+            }
+            data[key] = kv[2].trim();
         }
         toolsByPreset = parsePresetToolRules(m[1]);
         body = raw.slice(m[0].length);
@@ -116,6 +127,7 @@ export function parsePersona(raw, fallbackName) {
     // 兼容两种写法：`toolsdeny: a, b`（线上格式）与 `toolsDeny: a, b`（键名统一小写后同形）。
     const toolsDeny = listOf(data.toolsdeny);
     const firstLine = body.split(/\r?\n/).find((l) => l.trim())?.trim() ?? '';
+    const catalogDepth = parseCatalogDepth(data);
     return {
         name: fallbackName,
         description: data.description || firstLine,
@@ -124,43 +136,307 @@ export function parsePersona(raw, fallbackName) {
         tools,
         toolsDeny,
         ...(toolsByPreset === undefined ? {} : { toolsByPreset }),
+        ...(catalogDepth === undefined ? {} : { catalogDepth }),
+        ...(outputLines.length ? { output: outputLines.join('\n') } : {}),
         body: body.trim(),
         path: '',
     };
 }
+/** 零宽空格：用来拆开 `{{`，视觉上不留痕。 */
+const ZERO_WIDTH = '\u200b';
+/**
+ * 拆开正文里的 `{{`，让它不再被宿主当作提示词变量引用。
+ *
+ * 宿主对 section 文本做**严格**变量插值（dsh-system-prompt 的 `interpolate`）：
+ * 命中 `{{name}}` 而该变量没注册就抛错，整个子代理启动失败。人设是用户自由文本，
+ * 作者写 `{{foo}}` 几乎一定是字面量，却会让委派直接崩掉。这里在两个花括号之间插一个
+ * 零宽空格：模型看到的仍是 `{{foo}}`，宿主再也找不到 `{{`。**只拆开，不删除**——
+ * 用户写下的每一个可见字符都保留。
+ */
+export function neutralizePromptVariables(text) {
+    // 在"后面还是左花括号"的 `{` 之后插入零宽空格，把 `{{` 拆成 `{<ZWSP>{`。
+    // 用前瞻断言而不是 `replace(/\{\{/g, …)`：后者的替换串**尾字符也是 `{`**，
+    // 遇到 `{{{` 会与被替换掉的首括号后面的原字符重新拼出 `{{`（实测踩到）。
+    // 前瞻写法一次扫描就够，连续多少个左括号都处理干净。
+    return text.replace(/\{(?=\{)/g, `{${ZERO_WIDTH}`);
+}
+/**
+ * 这个人设主要用中文写的？启发式，判错的代价只是框的语言不搭。
+ *
+ * 判定范围是**人设整体**（名字 + 描述 + 正文），不只是正文：正文可能是占位符、
+ * 代码片段或纯英文标识（实测有人的正文是 `123`），只看正文会把一个中文人设
+ * 判成英文、配上英文框。名字与描述是作者写的，同样能说明语言。
+ */
+function isChinesePersona(name, description, body) {
+    const sample = `${name}\n${description}\n${body}`;
+    const cjk = (sample.match(/[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/g) || []).length;
+    if (cjk === 0)
+        return false;
+    const latin = (sample.match(/[A-Za-z]/g) || []).length;
+    // 汉字信息密度高于字母，1 个汉字按 2 个字母折算，避免"中文正文夹少量英文术语"被判成英文。
+    return cjk * 2 >= latin;
+}
+/**
+ * 人设 → 子代理系统提示词里那一段的**成品文本**（2026-09-17）。
+ *
+ * 为什么需要这层框：宿主给子代理的 persona 只占一个槽位 —— `deployment:persona-prefix`，
+ * section order 0，位置紧贴 `harness:identity`（order -1000，那句 "You are an AI agent
+ * powered by DeepSeek Harness."）。而宿主自己的 `personaPrefix` 配置是**部署级短前缀**，
+ * 它默认由部署方承担框架。我们把整篇人设正文直接填进这个槽，等于交出一段无标题、无归属、
+ * 无授权的裸文本：模型读到的是"身份句后面又跟了两句话"，而不是"我被指定为一个角色"。
+ * 用户写的 `必须…` 因此只是背景信息，没有上位效力。
+ *
+ * 两份参考实现都靠**框**解决同一件事：Claude Code 把代理提示词放在系统提示词**首位**，
+ * 追加内容一律带 `#`/`##` 标题与指令段（`AgentTool/agentMemory.ts`、`memdir/memdir.ts`）；
+ * Codex 在指令文件交界处插入来源标记 `--- project-doc ---`，让模型知道权威边界从哪开始
+ * （`core/src/agents_md.rs`）。两者都没有"把用户正文裸拼进系统提示词"这种做法。
+ *
+ * 框里四样东西各有分工，缺一样就退化成原来的裸文本：
+ *   - `# 角色：名` —— 结构信号（markdown 标题是模型最强的分段线索）+ 可引用的名字；
+ *   - 归属 + 授权一行 —— "由调用方指定、与默认倾向冲突时以它为准"，给正文上位效力；
+ *     2026-09-17 补了半句"任务说要什么，怎么做以它为准"：不写这句，模型会把 `task`
+ *     （父代理按自己的框架写的具体指令）读成人设的上级，人设只剩风格提示的分量；
+ *   - 边界一句 —— 角色决定**怎么做**，不改变**能做什么**。这不是装饰：官方
+ *     `subagent:delegation` 运行时上下文已经声明"权限在启动时固定"，两处不呼应的话，
+ *     写着"你可以随意写文件"的人设会读起来像与工具限制矛盾；
+ *   - `## 角色定义` 标题 + 正文 —— 明确起止，把用户文本围起来。
+ *
+ * 语言跟随人设整体（名字 + 描述 + 正文）：中文人设配中文框，英文配英文。
+ *
+ * 框里**不列 `description`**（2026-09-17 用户裁定，此前列）：那个字段的用途是**给调用方
+ * 选用**（本机那份写的是"当用户提到审查或使用审查子智能体时使用"），对已经在执行的人设
+ * 子代理是错位信息 —— 可能被读成"满足某个条件才按这个角色"的前置条件。要给人设子代理
+ * 看的简介属于正文（`description` 仍照常参与语言判定与目录展示）。
+ *
+ * 正文为空时退化成只给一个名字 —— 空框比没有框更糟。
+ */
+export function renderPersonaPrompt(persona) {
+    // 名字与正文/输出过同一道中和：名字原样进框时，宿主对 section 文本的严格插值会把
+    // `{{…}}` 当未注册变量抛错，委派直接硬失败 —— 0.9.5 的中和只盖了正文与输出，漏了名字
+    // （validPersonaName 不挡花括号，手写 frontmatter 造得出这种名字）。
+    const name = neutralizePromptVariables(String(persona.name || '').trim()) || '(unnamed)';
+    const raw = String(persona.body ?? '');
+    const body = neutralizePromptVariables(raw.trim());
+    if (body === '')
+        return name;
+    const rawDescription = String(persona.description ?? '').trim();
+    const output = neutralizePromptVariables(String(persona.output ?? '').trim());
+    const lines = isChinesePersona(name, rawDescription, raw)
+        ? [
+            `# 角色：${name}`,
+            '',
+            `你正在以「${name}」的身份执行本次委派任务。以下角色定义由调用方指定，是你本次运行的固定行为准则：与你的默认倾向冲突时，以它为准；任务说要什么，怎么做以它为准。它决定你如何工作，不改变你的权限范围。`,
+            '',
+            '## 角色定义',
+            '',
+            body,
+            ...(output === '' ? [] : ['', '## 输出要求（硬性）', '', output]),
+        ]
+        : [
+            `# Persona: ${name}`,
+            '',
+            `You are running this delegated task as "${name}". The persona below was specified by the caller and is your fixed operating guideline for this run: where it conflicts with your default inclinations, it wins; the task states what to achieve, and this persona governs how. It governs how you work, not what you are permitted to do.`,
+            '',
+            '## Persona',
+            '',
+            body,
+            ...(output === '' ? [] : ['', '## Output requirements (hard)', '', output]),
+        ];
+    return lines.join('\n');
+}
+/** 一个人设没写 `catalogDepth` 时的目录注入深度：1 —— 只在顶层注入目录。 */
+export const DEFAULT_PERSONA_CATALOG_DEPTH = 1;
+/**
+ * 「不限制嵌套」的目录注入深度（界面下拉的第四档，前端同值见 client.js 的
+ * `CATALOG_DEPTH_UNLIMITED`）。
+ *
+ * 取值远大于宿主能嵌套到的深度（官方 `dsh-tool-subagent` 默认 `maxDepth: 3`），所以判据
+ * `深度 < catalogDepth` 在任何可达的会话里都成立 —— 判据本身不必为它加特例分支。
+ */
+export const UNLIMITED_PERSONA_CATALOG_DEPTH = 99;
+/**
+ * 这个人设的目录注入深度（非法值一律退回默认，**默认从不放宽**）。
+ *
+ * 为什么非法值退回默认而不是报错：`catalogDepth` 是 frontmatter 里手写的字段，写错一个
+ * 数字不该让整个人设不可用；而"退回默认"是安全方向 —— 默认只注入到顶层，噪声最小。
+ */
+export function catalogDepthOf(persona) {
+    const value = persona?.catalogDepth;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        return DEFAULT_PERSONA_CATALOG_DEPTH;
+    return value;
+}
+/**
+ * 深度为 `depth` 的会话里，该不该注入这个人设所在的目录？
+ *
+ * 判据是 `depth < 目录注入深度`。**这个函数是三处口径的唯一来源** —— 目录要不要列出、
+ * 域该不该注入、实况报什么状态，全都问它。各写一份必然分叉。
+ *
+ * ⚠️ 它回答的**不是**"能不能委派"（那由官方决定，且默认能嵌套到 3 层）。这个区分是
+ * 2026-09-17 用户实测后纠正的：此前函数名是 `canDelegateTo`，把"目录可见性"当成了
+ * "委派可行性"，于是同一个子会话里官方工具能委派、我们的工具被自己的守卫拦下。
+ */
+export function catalogInjectedAt(persona, depth) {
+    const from = Number.isSafeInteger(depth) && depth >= 0 ? depth : 0;
+    return from < catalogDepthOf(persona);
+}
+/** frontmatter 里目录注入深度的几种写法都认（含旧的 `maxDepth`，见下）。 */
+function parseCatalogDepth(data) {
+    // 旧键 `maxDepth` 也读：0.9.5 定稿前这个字段叫过那个名字，且当时语义是"递归上限"。
+    // 读它只是为了不让手写过旧键的文件静默失效；**写回时一律写新键**（见 serializePersona）。
+    const raw = data.catalogdepth ?? data['catalog-depth'] ?? data.catalog_depth ?? data.maxdepth ?? data['max-depth'] ?? data.max_depth;
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    const value = Number(raw.trim());
+    if (!Number.isSafeInteger(value) || value < 0)
+        return undefined;
+    return value;
+}
 const RESULT_MAX = 16 * 1024;
+/**
+ * 从内容块数组里按 `type` 取文本并拼接 —— 官方 `finalText` 的口径
+ * （`dsh-subagent/lib/index.js:2658`：`blocks.filter(block => block.type === "text")`；
+ * `dsh-tool-subagent` 的 `outputValueText`、`withDiagnosticAndPartialText` 同样如此）。
+ *
+ * **必须按 `type` 过滤，不能只判有没有 `text` 字段**：`ContentBlock` 里 `TextBlock` 与
+ * `ReasoningBlock` 的结构完全相同（都是 `{ type, text: string }`，见 dsh-llm 的
+ * `types.d.ts:39/44`），只判字段会把**思考**当成正文拼进去。本机 298 条子代理终局消息里
+ * 294 条受影响：211 条思考与正文并存（返回结果的开头变成「我做了 1、2、3」这类自我校验，
+ * 正文被顶到后面），83 条压根没有正文。
+ *
+ * `typeof b.text === 'string'` 这层是防 provider 给出畸形块（官方工具也这么防）。
+ */
+export function textOfBlocks(blocks, type) {
+    if (!Array.isArray(blocks))
+        return '';
+    return blocks
+        .filter((b) => b !== null && typeof b === 'object' && b.type === type && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('')
+        .trim();
+}
+/**
+ * 没有正文时给调用方的一句话。
+ *
+ * 要解决的是**误读**：原来一律回 `(子代理无输出)`，而「子代理没干活」和「干了活但没写出
+ * 正文」是两件事，报成同一句会让调用方把它当成一次空跑。所以这一句里必须同时说清两件事：
+ *   ① 它**干了活**（产出了思考）—— 否则会被读成空跑；
+ *   ② 这次委派**没有拿到可用结果** —— 否则会被当成一份内容读下去。
+ *
+ * 按收尾原因分档，而不是给一句通用话：实测数据推翻了「它忘了写结论」这个想当然的解释 ——
+ * 本机 83 条「没有正文」的终局里**没有一条是 `completed`**（max-tokens 36、error 20、
+ * 无收尾记录 22、aborted 5），而有正文那批 215 条里 195 条是 `completed`。官方自己也是
+ * 这么分的：`dsh-tool-subagent/lib/index.js:316` 对任何非 `completed` 的收尾**直接抛错**
+ * （`stopReasonError` → `withDiagnosticAndPartialText`），只有 `completed` 才当结果返回。
+ * 所以这个兜底出现的场合，对策基本都是「拆小任务 / 查诊断 / 换人设」，不是原样再发一次。
+ *
+ * 分档用的是官方 `stopReasonError` 认的那几个值，出现新值时落回最后那句通用说明。
+ *
+ * 刻意**不把思考正文塞回来**：那正是这次要修的泄漏，换个标签塞回去等于没修。
+ */
+export function emptyResultNote(output, stopReason) {
+    // 连思考都没有 → 子代理确实什么都没产出，这时说「没干活」是对的。
+    if (textOfBlocks(output, 'reasoning') === '')
+        return '(子代理无输出)';
+    const head = '子代理没有返回正文 —— 它产出了思考';
+    switch (stopReason) {
+        case 'max-tokens':
+            return `(${head}，但写出结论前就用完了 token 上限；需要结果请把任务拆小些再委派。)`;
+        case 'error':
+            return `(${head}，但中途出错了；诊断信息见后。)`;
+        case 'aborted':
+            return `(${head}，但写出结论前被中止了。)`;
+        case 'refusal':
+            return `(${head}，但它拒绝了这项任务。)`;
+        default:
+            return `(${head}，但没有写出结论；可以拆小任务重新委派，或你自己接着做。)`;
+    }
+}
 export function createSubagentService(ctx, opts) {
     const dir = opts?.subagentsDir || defaultPersonasDir();
     const stateDir = opts?.stateDir && opts.stateDir.trim() !== '' ? opts.stateDir : join(resolveDshHome(), 'tool-management');
     const stateFile = join(stateDir, 'subagents-index.json');
     const req = createRequire(import.meta.url);
     let cache = null;
+    // ── 写操作串行队列 ──────────────────────────────────────────────────────
+    // 状态文件的「读-改-写」必须整体串行：两个并发开关各自读到同一份快照、各自写回，
+    // 后写的会把先写的改动抹掉（用户关掉的人设会自己回来）。人设文件的建/改/删也走这里，
+    // 否则「查重 → 写入」之间的空窗会让两次同名导入互相覆盖。
+    // 与 rules / skills 两域同一实现（`then(task, task)` 让前一个失败后队列照样继续）。
+    let mutationQueue = Promise.resolve();
+    const enqueueMutation = (task) => {
+        const queued = mutationQueue.then(task, task);
+        mutationQueue = queued.catch(() => undefined);
+        return queued;
+    };
     // ── 人设启用集合（子智能体开关）────────────────────────────────────────
     // subagents-index.json：{ version: 1, enabled: string[] }（与 memories-index.json 同目录约定）。
-    //   - 文件缺失/损坏 = **全部启用**（老用户升级零感知，行为与开关上线前一致）；
+    //   - 文件**缺失** = **全部启用**（老用户升级零感知，行为与开关上线前一致）；
+    //   - 文件**存在但解析失败** = **全部停用** + 告警一次（fail-closed：损坏不该把用户停用的
+    //     人设一次性重新暴露给模型，且用户看不到任何提示；与 rules 域索引隔离同口径）；
     //   - 文件一旦写出即为权威：之后新建/导入/回收站恢复的人设**自动启用**（刚建就想用是常理）；
     //   - 停用只影响注入与 subagent_* 工具的可见性，人设文件一个字节不动。
     // 缓存约定：undefined = 还没读过盘；null = 文件缺失（全部启用）；数组 = 权威集合。
     let enabledCache = undefined;
+    // 与缓存配对的文件指纹（mtimeMs；文件不存在时 null）。**必须比对指纹**：这个文件可能被
+    // 另一个 DSH 实例（多 profile 共享 state 目录）或手工编辑改动，只在自身写入时失效缓存
+    // 会让插件一直返回旧集合 —— 用户停用的人设悄悄回来。一次 stat 比重新读 + 解析便宜，
+    // 而且立刻跟上外部改动，不引入新的 TTL 窗口。
+    let enabledStamp = null;
+    // 解析失败只告警一次：readEnabled 每次读都会走到那段，不设标志会刷屏。
+    let warnedBrokenState = false;
+    /** 文件 mtimeMs；不存在或读不到时 null（与「文件缺失」同一判定）。 */
+    const fileStamp = async (path) => {
+        try {
+            return (await stat(path)).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+    };
     async function readEnabled() {
-        if (enabledCache !== undefined)
+        const stamp = await fileStamp(stateFile);
+        if (enabledCache !== undefined && stamp === enabledStamp)
             return enabledCache;
         // 用局部变量过渡：await 之后 TS 对闭包级缓存变量的收窄会失效，直接返回会报 undefined。
         let next;
+        let text;
         try {
-            const raw = JSON.parse(await readFile(stateFile, 'utf8'));
-            next = Array.isArray(raw && raw.enabled) ? raw.enabled.map((x) => String(x)) : [];
+            text = await readFile(stateFile, 'utf8');
         }
         catch {
+            text = null;
+        }
+        if (text === null) {
+            // 文件不存在 → 全部启用（升级零感知，见上方约定）。
             next = null;
         }
+        else {
+            try {
+                const raw = JSON.parse(text);
+                next = Array.isArray(raw && raw.enabled) ? raw.enabled.map((x) => String(x)) : [];
+            }
+            catch (e) {
+                // 文件**存在**却解析失败 → fail-closed 成「谁都不启用」。沿用「全部启用」会把用户
+                // 停用的人设一次性全部重新暴露给模型，而用户看不到任何提示；空集合至少可见、可恢复
+                // （重新开启即可）。文件本身一个字节不动，修好后重启即恢复。
+                if (!warnedBrokenState) {
+                    warnedBrokenState = true;
+                    ctx.logger?.warn?.(`[dsh-plugin-tool-management] 人设索引解析失败（${message(e)}）；已按「全部停用」处理，请检查 ${stateFile}`);
+                }
+                next = [];
+            }
+        }
         enabledCache = next;
+        enabledStamp = stamp;
         return next;
     }
     async function writeEnabled(list) {
         await mkdir(stateDir, { recursive: true });
         await writeFile(stateFile, JSON.stringify({ version: 1, enabled: list }, null, 2), 'utf8');
         enabledCache = list;
+        // 写入后重取指纹，让下一次 readEnabled 直接命中缓存（否则会白读一次）。
+        enabledStamp = await fileStamp(stateFile);
     }
     /** 新建/导入/恢复的人设默认停用（v0.8.5 用户裁定，与技能 / MCP 同口径）：
      *  文件缺失（含旧数据）时先把「全部启用」物化成显式全集**并排除新名**——
@@ -192,6 +468,25 @@ export function createSubagentService(ctx, opts) {
             return;
         await writeEnabled(set.filter((n) => n !== name));
     }
+    /**
+     * 启用集合的「跟随写」失败**不能吞**。原先这五处一律 `.catch(() => undefined)`，
+     * 而写盘失败时后果是静默改变开关状态：新建/导入/恢复的人设会停在**启用**态（下一轮就进
+     * 模型上下文），改名的人设会停在**停用**态 —— 用户看到的却都是成功。
+     *
+     * 沿用 `sceneSyncError` 的形状：只给**原因原文**，句子由界面按当前语言拼。
+     */
+    async function withEnabledNote(res, task) {
+        try {
+            await task();
+            return res;
+        }
+        catch (e) {
+            const reason = message(e);
+            return res && res.ok === false
+                ? { ...res, error: `${res.error}；另外，启停状态没能同步（${reason}）` }
+                : { ...res, stateSyncError: reason };
+        }
+    }
     /** list() 输出统一附上 enabled：文件缺失 → 全 true；否则按集合。 */
     function withEnabled(docs, set) {
         if (set === null)
@@ -222,55 +517,79 @@ export function createSubagentService(ctx, opts) {
         }
         return withEnabled(docs, await readEnabled());
     }
-    // spawn provider 在场性（设计 §3.2，落地方式见 cordis.patch.yml 的取舍注释）：
+    // provider 在场性（设计 §3.2，落地方式见 cordis.patch.yml 的取舍注释）：
     // 官方通道探测（ctx.subagents.list()）→ 缺失才挂载 → 失败把原因原样带出（不吞、不谎报）。
     // 不是一次性静默标记：每次调用都先探测，宿主后来注册了 provider 也能立刻跟上。
-    let spawnMount = null;
-    function hasSpawnProvider(runtime) {
+    //
+    // 两个 provider（2026-09-17 加 fork，理由见 runOnce 的通道说明）：
+    //   spawn = 新起的独立会话（默认）；fork = **继承本次会话已完成的对话**（官方 subagent_fork 用的是它）。
+    const PROVIDER_PACKAGES = {
+        spawn: { pkg: '@deepseek-ai/dsh-subagent-spawn-in-process', label: 'spawn（新会话）' },
+        fork: { pkg: '@deepseek-ai/dsh-subagent-fork-in-process', label: 'fork（继承本次会话）' },
+    };
+    const providerMounts = {};
+    function hasProvider(runtime, kind) {
         if (typeof runtime.list !== 'function')
             return false;
         try {
             const names = runtime.list();
-            return Array.isArray(names) && names.indexOf('spawn') >= 0;
+            return Array.isArray(names) && names.indexOf(kind) >= 0;
         }
         catch {
             return false;
         }
     }
-    async function ensureSpawnProvider() {
+    async function ensureProvider(kind) {
         const runtime = ctx.get?.('subagents');
         if (!runtime || typeof runtime.start !== 'function') {
             throw new Error('子代理服务未挂载（ctx.subagents 缺失；请确认 DSH 版本 ≥0.1.5-rc.2）');
         }
-        if (hasSpawnProvider(runtime))
+        if (hasProvider(runtime, kind))
             return runtime;
         // 宿主没有 list() 就探测不了：不重复挂载（避免同名 provider 二次注册），交给 start 报官方错误兜底。
         if (typeof runtime.list !== 'function')
             return runtime;
-        if (!spawnMount) {
+        if (!providerMounts[kind]) {
+            const { pkg, label } = PROVIDER_PACKAGES[kind];
             try {
-                const mod = req('@deepseek-ai/dsh-subagent-spawn-in-process');
+                const mod = req(pkg);
                 if (!mod || typeof mod.apply !== 'function')
                     throw new Error('模块未导出 apply(ctx, config)（版本不匹配？）');
-                mod.apply(ctx, { providerName: 'spawn' });
-                spawnMount = { ok: true };
+                mod.apply(ctx, { providerName: kind });
+                providerMounts[kind] = { ok: true };
             }
             catch (e) {
-                spawnMount = {
+                providerMounts[kind] = {
                     ok: false,
-                    error: 'spawn provider 不可用：宿主没有注册它，本插件挂载 @deepseek-ai/dsh-subagent-spawn-in-process 也失败（'
+                    error: `${label} provider 不可用：宿主没有注册它，本插件挂载 ${pkg} 也失败（`
                         + message(e) + '）。请在宿主 profile 挂载该包（本插件已声明为可选 peerDependency），或安装后重启 DSH。',
                 };
             }
         }
-        if (!spawnMount.ok)
-            throw new Error(spawnMount.error);
-        if (!hasSpawnProvider(runtime))
-            throw new Error('spawn provider 挂载后仍未出现在 ctx.subagents.list()（宿主版本不匹配？）');
+        const mount = providerMounts[kind];
+        if (!mount || !mount.ok)
+            throw new Error(mount ? mount.error : 'provider 挂载失败（未知原因）');
+        if (!hasProvider(runtime, kind))
+            throw new Error(`${kind} provider 挂载后仍未出现在 ctx.subagents.list()（宿主版本不匹配？）`);
         return runtime;
     }
-    async function runOnce(parentAgent, p, task, signal, toolFilter) {
-        const runtime = await ensureSpawnProvider();
+    async function runOnce(parentAgent, p, task, signal, toolFilter, inherit) {
+        // 这里**刻意没有**"预算用尽就拒绝"的前置检查（2026-09-17 用户实测后拆掉）。
+        // 它此前基于一个错误假设：以为传 `maxDepth: 1` 会让子会话再委派必然失败。实际上官方
+        // `dsh-tool-subagent` 的默认是 **3**、provider 只在**传了值**时才校验（`resolveChildDepth`），
+        // 所以子代理本来就能继续嵌套。那个检查唯一的净效果是让**我们的**工具比官方严 ——
+        // 同一个子会话里官方工具能委派、我们的被自己拦下 —— 而用户真想禁止嵌套也禁止不了。
+        //
+        // 通道选择（方案 C，2026-09-17）：`inherit` → 官方 fork provider（子会话被**本次会话已完成的
+        // 对话**播种，`task` 只需写新增部分）；默认 → spawn（全新会话，任务必须自包含）。
+        // 为什么必须有这一档：官方的 `subagent_fork` 靠"继承上下文"赢走过模型的选择 —— 本机实测
+        // （session-ee722e23）上下文里明明有「先在这里选人设…用 subagent_manager_run 执行」与
+        // `code-review` 人设，模型在**读进 README 之后**仍选了 `subagent_fork`：那能把已读内容带过去、
+        // 不必复述。人设通道缺这一档时，"贴合人设的任务"会持续被官方工具抢走 —— 补齐能力比改文案
+        // 更根本（模型选的是省力，不是没看见）。fork provider 的能力位（persona / toolFilter /
+        // agentOptions）与 spawn 相同，所以请求体不用分叉。
+        const kind = inherit === true ? 'fork' : 'spawn';
+        const runtime = await ensureProvider(kind);
         // 工具限制三态：对象 = 调用方已按当前预设决定；null = 调用方明确决定不加限制；
         // undefined = 调用方没决定（如别的入口直接调 runSerial）→ 回落人设里的旧格式全局名单。
         const legacyFilter = (p.tools?.length || p.toolsDeny?.length)
@@ -278,17 +597,24 @@ export function createSubagentService(ctx, opts) {
             : null;
         const resolved = toolFilter === undefined ? legacyFilter : toolFilter;
         // 官方签名：start(name, request) —— name = ctx.subagents 上的 provider 注册名。
-        const run = await runtime.start('spawn', {
+        const run = await runtime.start(kind, {
             label: p.name,
             parent: parentAgent,
             // 官方 SubagentStartRequest.signal 为必填：调用方缺省时给一个永不中止的信号，不传 undefined。
             signal: signal ?? new AbortController().signal,
             prompt: [{ type: 'text', text: task }],
-            persona: p.body,
+            // 人设不是裸正文：宿主的 persona 槽位（section order 0）原本是部署级短前缀，
+            // 框架该由填槽方承担。见 renderPersonaPrompt 的说明 —— 裸拼的后果是模型把它
+            // 读成身份句的续写，而不是一个被指定的角色。
+            persona: renderPersonaPrompt(p),
             // 工具白/黑名单 → 官方 ToolRestriction（`deny` 优先级高于 `allow`；未知名官方会直接拒绝启动，
             // 所以名单由 index.ts 按当前预设 + 当前真实存在的工具名算好再传进来，见 decideToolFilter）。
             ...(resolved === null ? {} : { toolFilter: resolved }),
-            maxDepth: 1,
+            // **刻意不传 `maxDepth`**（2026-09-17 用户裁定，方案 A）：它是官方的**真·递归上限**
+            // （`resolveChildDepth` 会抛 `SubagentDepthError`），而我们的 `catalogDepth` 只想决定
+            // "目录出现在哪"。传了它会让我们的工具比官方严（1 vs 3），且会要求 provider 具备
+            // `depthLimit` capability（不传就没这个依赖）。让 provider 用它自己的默认，与官方
+            // 工具的能力保持一致。
             // provider 与 model 是模型路由的两半：DSH 的 resolveModel(provider, model) 不做
             // `provider/model` 字符串拆分，只改 model 会落在**主会话的 provider** 上——跨来源
             // 指定模型（如 sensenova 的 sensenova-6.8-flash-lite）必须两个键一起给。
@@ -298,15 +624,17 @@ export function createSubagentService(ctx, opts) {
         });
         try {
             const result = await run.result; // 官方契约：child 级失败不 reject（stopReason 体现）
-            const text = (result.output ?? [])
-                .map((b) => (b && typeof b === 'object' && typeof b.text === 'string' ? b.text : ''))
-                .join('').trim();
+            // 只取 `text` 块（见 textOfBlocks）。此前这里只判了 `typeof b.text === 'string'`，
+            // 于是 `reasoning` 块被当成正文 —— 子代理返回的正文里混着它的思考（计数、自我校验），
+            // 只有思考时整段返回思考。本机 298 条终局消息里 98.7% 命中。
+            const text = textOfBlocks(result.output, 'text');
             // 官方 SubagentResult 的诊断字段是 `diagnostic`（旧代码读 .detail 恒空 → 失败时模型只见空输出）。
             const diagnostic = result.diagnostic ? `\n\n[provider] ${String(result.diagnostic)}` : '';
+            const stopReason = String(result.stopReason ?? 'completed');
             return {
-                text: ((text || '(子代理无输出)') + diagnostic).slice(0, RESULT_MAX),
+                text: ((text || emptyResultNote(result.output, stopReason)) + diagnostic).slice(0, RESULT_MAX),
                 runId: String(run.id ?? ''),
-                stopReason: String(result.stopReason ?? 'completed'),
+                stopReason,
             };
         }
         finally {
@@ -315,17 +643,24 @@ export function createSubagentService(ctx, opts) {
     }
     // v1 串行：同一时刻至多一个子代理运行（设计 §3.2）。
     let chain = Promise.resolve();
-    const runSerial = (parentAgent, p, task, signal, toolFilter) => {
-        const queued = chain.then(() => runOnce(parentAgent, p, task, signal, toolFilter), () => runOnce(parentAgent, p, task, signal, toolFilter));
+    const runSerial = (parentAgent, p, task, signal, toolFilter, inherit) => {
+        const start = () => runOnce(parentAgent, p, task, signal, toolFilter, inherit);
+        const queued = chain.then(start, start);
         chain = queued.catch(() => undefined);
         return queued;
     };
+    /** 写操作 op 名集合（HTTP 端 WRITE_OPS 由它派生）。 */
+    const writeOps = new Set([
+        'subagent-create', 'subagent-update', 'subagent-delete', 'subagent-import',
+        'subagent-toggle', 'subagent-trash-restore', 'subagent-trash-delete',
+    ]);
     const ops = {
         'subagent-list': async () => {
             const docs = await list();
             return {
                 ok: true,
-                subagents: docs.map((p) => ({ name: p.name, enabled: p.enabled !== false, description: p.description, provider: p.provider ?? null, model: p.model ?? null, tools: p.tools ?? null, toolsDeny: p.toolsDeny ?? null, toolsByPreset: p.toolsByPreset ?? null })),
+                // catalogDepth 报**生效值**（没写就是默认 1），界面与模型都不必各自知道默认是多少。
+                subagents: docs.map((p) => ({ name: p.name, enabled: p.enabled !== false, description: p.description, provider: p.provider ?? null, model: p.model ?? null, tools: p.tools ?? null, toolsDeny: p.toolsDeny ?? null, toolsByPreset: p.toolsByPreset ?? null, catalogDepth: catalogDepthOf(p), output: p.output ?? null })),
             };
         },
         'subagent-get': async (args) => {
@@ -334,7 +669,7 @@ export function createSubagentService(ctx, opts) {
             const p = docs.find((d) => d.name === name);
             if (!p)
                 return { ok: false, error: `人设不存在: ${name}` };
-            return { ok: true, persona: { name: p.name, description: p.description, provider: p.provider ?? '', model: p.model ?? '', tools: p.tools ?? [], toolsDeny: p.toolsDeny ?? [], toolsByPreset: p.toolsByPreset ?? {}, body: p.body } };
+            return { ok: true, persona: { name: p.name, description: p.description, provider: p.provider ?? '', model: p.model ?? '', tools: p.tools ?? [], toolsDeny: p.toolsDeny ?? [], toolsByPreset: p.toolsByPreset ?? {}, catalogDepth: catalogDepthOf(p), output: p.output ?? '', body: p.body } };
         },
         'subagent-create': async (args) => {
             const name = String((args && args.name) || '').trim();
@@ -354,9 +689,8 @@ export function createSubagentService(ctx, opts) {
             }
             await writeFile(target, serializePersona(args), 'utf8');
             // v0.8.5：新建默认不启动——显式集合下新名天然停用；文件缺失时先物化全集并排除新名。
-            await materializeEnabledExcluding([name]).catch(() => undefined);
             cache = null;
-            return { ok: true, name };
+            return withEnabledNote({ ok: true, name }, () => materializeEnabledExcluding([name]));
         },
         /**
          * 保存人设，**可选改名**（nextName）。
@@ -383,20 +717,28 @@ export function createSubagentService(ctx, opts) {
                 const taken = await readFile(nextTarget, 'utf8').then(() => true).catch(() => false);
                 if (taken)
                     return { ok: false, error: `人设已存在: ${nextRaw}` };
-                try {
-                    await rename(target, nextTarget);
-                }
-                catch (e) {
-                    return { ok: false, error: `人设改名失败: ${message(e)}` };
-                }
                 finalName = nextRaw;
                 renamedFrom = name;
             }
-            await writeFile(join(dir, finalName + '.md'), serializePersona({ ...args, name: finalName }), 'utf8');
+            // 先把新内容写进临时文件、再一次性改名到位。原先的顺序是「先 rename 旧文件 → 再
+            // writeFile 新文件」，writeFile 一旦失败就留下「新名字 + 旧内容」的半态 —— 用户看到
+            // 改名成功、内容却还是旧的。临时名以 `.` 开头且不以 `.md` 结尾，扫描时天然被忽略。
+            const finalTarget = join(dir, finalName + '.md');
+            const tmp = join(dir, `.${finalName}.tmp-${process.pid}-${Date.now()}`);
+            try {
+                await writeFile(tmp, serializePersona({ ...args, name: finalName }), 'utf8');
+                await rename(tmp, finalTarget);
+            }
+            catch (e) {
+                await rm(tmp, { force: true }).catch(() => undefined);
+                return { ok: false, error: `保存人设失败: ${message(e)}` };
+            }
+            // 改名时旧文件等新文件就位后再清：清失败只多一份副本，不丢数据。
             if (renamedFrom)
-                await renamePersonaInEnabled(renamedFrom, finalName).catch(() => undefined);
+                await rm(join(dir, renamedFrom + '.md'), { force: true }).catch(() => undefined);
             cache = null;
-            return { ok: true, name: finalName, ...(renamedFrom ? { renamedFrom } : {}) };
+            return withEnabledNote({ ok: true, name: finalName, ...(renamedFrom ? { renamedFrom } : {}) }, async () => { if (renamedFrom)
+                await renamePersonaInEnabled(renamedFrom, finalName); });
         },
         /**
          * 删除人设 = **移入回收站**（`hub/trash/agents-trash/<id>/persona.md`）。
@@ -414,9 +756,8 @@ export function createSubagentService(ctx, opts) {
             const moved = await moveToTrash('subagents', name, [{ from: target, dest: 'persona.md' }]);
             if (moved.ok === false)
                 return { ok: false, error: `移入回收站失败: ${moved.error}` };
-            await removePersonaFromEnabled(name).catch(() => undefined);
             cache = null;
-            return { ok: true, name, trashId: moved.id };
+            return withEnabledNote({ ok: true, name, trashId: moved.id }, () => removePersonaFromEnabled(name));
         },
         'subagent-trash-list': async () => ({ ok: true, trash: await listTrashEntries('subagents') }),
         'subagent-trash-restore': async (args) => {
@@ -440,9 +781,8 @@ export function createSubagentService(ctx, opts) {
             }
             await purgeTrashEntry('subagents', id);
             // v0.8.5：回收站恢复默认不启动（与新建/导入同口径）。
-            await materializeEnabledExcluding([entry.name]).catch(() => undefined);
             cache = null;
-            return { ok: true, name: entry.name };
+            return withEnabledNote({ ok: true, name: entry.name }, () => materializeEnabledExcluding([entry.name]));
         },
         'subagent-trash-delete': async (args) => {
             const id = String((args && args.id) || '').trim();
@@ -490,11 +830,10 @@ export function createSubagentService(ctx, opts) {
                 }
                 imported.push(target.name);
             }
-            if (imported.length) {
-                await materializeEnabledExcluding(imported).catch(() => undefined);
+            if (imported.length)
                 cache = null;
-            }
-            return { ok: true, imported, skipped };
+            return withEnabledNote({ ok: true, imported, skipped }, async () => { if (imported.length)
+                await materializeEnabledExcluding(imported); });
         },
         /**
          * 子智能体开关（v0.8）：停用 = 不注入目录段、subagent_manager_list/run 不可见；文件本体不动。
@@ -527,6 +866,13 @@ export function createSubagentService(ctx, opts) {
             return { ok: true, name, enabled: args.enabled === true };
         },
     };
+    // 写 op 统一进串行队列（理由见上方 mutationQueue 的说明）。放在这里统一包、而不是逐个手写：
+    // 以后新增写 op 只改 writeOps 一处，不会漏掉。
+    for (const name of writeOps) {
+        const fn = ops[name];
+        if (typeof fn === 'function')
+            ops[name] = (args) => enqueueMutation(() => fn(args));
+    }
     const enabledStore = {
         /** 指定名单里当前被停用的（进入模式拍快照用：只记将被启用的行，退出时精确停回）。 */
         async disabledAmong(names) {
@@ -546,35 +892,64 @@ export function createSubagentService(ctx, opts) {
             const state = new Map(docs.map((d) => [d.name, d.enabled !== false]));
             return docs.map((d) => d.name).filter((n) => state.get(n) === true);
         },
-        /** 批量启停；只碰给出的名字，人设已不存在的跳过（别把悬空名写进集合）。 */
+        /** 批量启停；只碰给出的名字，人设已不存在的跳过（别把悬空名写进集合）。
+         *  同样走写队列：它由场景档案引擎直接调用（不经 op 表），不排队就会与开关 op 互相覆盖。 */
         async setEnabled(names, enabled) {
-            const docs = await list();
-            const set = await readEnabled();
-            const base = (set === null ? docs.map((d) => d.name) : set.slice()).filter((n) => docs.some((d) => d.name === n));
-            let dirty = false;
-            for (const n of names) {
-                if (!docs.some((d) => d.name === n))
-                    continue;
-                const i = base.indexOf(n);
-                if (enabled && i < 0) {
-                    base.push(n);
-                    dirty = true;
+            await enqueueMutation(async () => {
+                const docs = await list();
+                const set = await readEnabled();
+                const base = (set === null ? docs.map((d) => d.name) : set.slice()).filter((n) => docs.some((d) => d.name === n));
+                let dirty = false;
+                for (const n of names) {
+                    if (!docs.some((d) => d.name === n))
+                        continue;
+                    const i = base.indexOf(n);
+                    if (enabled && i < 0) {
+                        base.push(n);
+                        dirty = true;
+                    }
+                    if (!enabled && i >= 0) {
+                        base.splice(i, 1);
+                        dirty = true;
+                    }
                 }
-                if (!enabled && i >= 0) {
-                    base.splice(i, 1);
-                    dirty = true;
+                if (dirty) {
+                    await writeEnabled(base);
+                    cache = null;
                 }
-            }
-            if (dirty) {
-                await writeEnabled(base);
-                cache = null;
-            }
+            });
         },
     };
-    return { list, runSerial, ops, enabledStore, writeOps: new Set(['subagent-create', 'subagent-update', 'subagent-delete', 'subagent-import', 'subagent-toggle', 'subagent-trash-restore', 'subagent-trash-delete']) };
+    return { list, runSerial, ops, enabledStore, writeOps };
+}
+/** 人设名长度上限（字符）。 */
+const PERSONA_NAME_MAX = 64;
+/**
+ * 官方 `tools.restrict()` 的**保留名**：名单里出现它时，官方不是"当它不存在"，而是**直接抛错**
+ * （`dsh-tools/lib/index.js:2800`：cannot name reserved PTC mode presentation transport），
+ * 子代理当场起不来。
+ *
+ * 为什么必须在这里显式剔除：`run_code` 在宿主面上是**合法可见**的工具名（非 native 模式下
+ * 由官方补进可见集合），所以"按当前存在的工具名过滤未知项"剔不掉它 —— 过滤留下的正好是
+ * 会让官方抛错的那个。用户的直观预期是"写了就生效（或至少被忽略）"，实际却是整个委派失败。
+ */
+const RESERVED_TOOL_NAMES = new Set(['run_code']);
+/** 把保留名从名单里剔掉，并说明剔了什么（不静默）。 */
+function stripReserved(names) {
+    const kept = [];
+    const dropped = [];
+    for (const name of names)
+        (RESERVED_TOOL_NAMES.has(name) ? dropped : kept).push(name);
+    return { kept, dropped };
 }
-function validPersonaName(name) {
-    return name.length > 0 && name.length <= 64 && !name.startsWith('.') && !/[\\/<>:"|?*]/.test(name);
+/**
+ * 人设名合法性：谓词收敛到 `../paths.ts`（此前这里与 rules / imports / skills 各写一套，
+ * 缺了 Windows 保留设备名与控制字符检查 —— 设备名在 Windows 上创建即失败）。
+ * 注意：**不挡花括号**，手写 frontmatter 仍造得出 `{{…}}` 名字，渲染侧照旧做中和
+ * （见 renderPersonaPrompt）。
+ */
+export function validPersonaName(name) {
+    return isValidSegment(name, PERSONA_NAME_MAX);
 }
 /** 字符串数组规范化（非数组/空项都丢掉）。 */
 function toStringList(value) {
@@ -611,7 +986,19 @@ export function serializePersona(args) {
     // 黑名单字段兼容两种入参名：toolsDeny（UI/camel）与 tools_deny（snake）。
     const toolsDeny = toStringList(args?.toolsDeny ?? args?.tools_deny);
     const byPreset = presetRulesOf(args?.toolsByPreset);
+    // 目录注入深度：只在显式给了合法值时写入。默认（1）**不落盘** —— 免得每个新建的人设都
+    // 多一行说明"它和默认一样"，也保证老的人设文件回写后逐字节不变。
+    // 入参名兼容三种：catalogDepth（新）、maxDepth / max_depth（0.9.5 定稿前的旧名）。
+    const catalogDepthRaw = args?.catalogDepth ?? args?.catalog_depth ?? args?.maxDepth ?? args?.max_depth;
+    const catalogDepth = catalogDepthRaw === undefined || catalogDepthRaw === null || String(catalogDepthRaw).trim() === ''
+        ? undefined
+        : Number(String(catalogDepthRaw).trim());
+    const hasCatalogDepth = catalogDepth !== undefined && Number.isSafeInteger(catalogDepth) && catalogDepth >= 0 && catalogDepth !== DEFAULT_PERSONA_CATALOG_DEPTH;
     const body = String((args && args.body) ?? '').trim();
+    // `output` 可传字符串（按行拆）或数组（界面直接给数组）：一条要求写成一行重复键。
+    const outputLines = (Array.isArray(args?.output) ? args.output.map((v) => String(v)) : String(args?.output ?? '').split(/\r?\n/))
+        .map((line) => line.trim())
+        .filter((line) => line !== '');
     const lines = ['---'];
     if (description)
         lines.push('description: ' + description);
@@ -619,6 +1006,10 @@ export function serializePersona(args) {
         lines.push('provider: ' + provider);
     if (model)
         lines.push('model: ' + model);
+    if (hasCatalogDepth)
+        lines.push('catalogDepth: ' + String(catalogDepth));
+    for (const line of outputLines)
+        lines.push('output: ' + line);
     if (tools.length)
         lines.push('tools: ' + tools.join(', '));
     if (toolsDeny.length)
@@ -635,34 +1026,57 @@ export function serializePersona(args) {
  * 按**当前会话的 Agent 预设**决定这次委派下发什么工具限制。
  *
  * 为什么必须按预设分：子代理跑在父会话的预设里（官方 `composeFrom(childCtx, parent.ctx)`），
- * 而各预设的工具集合差别极大（极简模式只有持久 shell），官方 `tools.restrict()` 遇到
- * 名单里不存在的工具名会直接抛错、子代理根本起不来。所以：
+ * 而各预设的工具集合差别极大（极简模式只有持久 shell）。官方 `tools.restrict()` 实有
+ * **四个**抛错点（`dsh-tools/lib/index.js:2790-2803`），抛了子代理就起不来：
+ *
+ *   ① 非 scoped context 调用（宿主 `childCtx` 已满足，无风险）；
+ *   ② `allow` 与 `deny` 同时缺省 ⇒ `restrict({})` 抛 —— 本函数用 `filter: null`（不下发）
+ *      表达"不加限制"，**从不**调用 `restrict({})`；
+ *   ③ **名单含保留名 `run_code` 即抛** —— 而它在宿主面上是合法可见名，"按现有工具名过滤"
+ *      剔不掉它，所以这里**显式剔除**并写进 note（见 `stripReserved`）；
+ *   ④ 未知名 ⇒ 抛（唯一此前被记录的那条）。
  *
+ * 所以：
  *   - 当前预设配了名单（且名单非空）→ 用它；白名单额外并入**当时真实在跑的 MCP 工具**
  *     （官方 allow 是"清单之外全砍"，不并进来会把 MCP 一起砍掉；用户裁定：子代理要能
  *     用当前启动的 MCP）；
  *   - 当前预设没配 → 回落旧的全局 `tools` / `toolsDeny`（老文件行为不变）；
- *   - 名单里有已经消失的工具名 → **丢掉并在 note 里如实说明**（不接受静默失效）；
+ *   - 名单里有已经消失的工具名、或写了保留名 → **丢掉并在 note 里如实说明**（不接受静默失效）；
  *   - 判断不了当前预设（老宿主 / 异常）→ 不按模式施加，并在 note 里说明。
  *
+ * ⚠ 两种失败方向都要记账（它们互斥，且都不是"没生效"这么简单）：名单全落空时本函数返回
+ * `filter: null` = **放宽到不限制**（fail-open）；保留名没剔干净时官方抛错 = **收紧到起不来**。
+ *
  * 三态返回：`filter: null` = 明确不加限制；`filter: {...}` = 下发该限制。
  */
 export function decideToolFilter(persona, presetId, known) {
     const rule = presetId === null ? undefined : persona.toolsByPreset?.[presetId];
     if (rule && rule.names.length) {
-        const usable = rule.names.filter((name) => known.names.has(name));
+        const knownNames = rule.names.filter((name) => known.names.has(name));
+        const reserved = stripReserved(knownNames);
+        const usable = reserved.kept;
         const dropped = rule.names.filter((name) => !known.names.has(name));
-        const droppedNote = dropped.length ? `名单里这些工具当前不存在，已忽略：${dropped.join('、')}` : undefined;
+        const notes = [];
+        if (dropped.length)
+            notes.push(`名单里这些工具当前不存在，已忽略：${dropped.join('、')}`);
+        if (reserved.dropped.length) {
+            notes.push(`名单里的 ${reserved.dropped.join('、')} 是官方保留名（写进工具限制会让子代理直接起不来），已忽略`);
+        }
         if (!usable.length) {
-            return { filter: null, note: `「${presetId}」的${rule.mode === 'allow' ? '白' : '黑'}名单里没有当前存在的工具，本次不施加工具限制` };
+            const note = notes.length ? notes.join('；') : undefined;
+            return { filter: null, note: note ?? `「${presetId}」的${rule.mode === 'allow' ? '白' : '黑'}名单里没有当前存在的工具，本次不施加工具限制` };
         }
+        const droppedNote = notes.length ? notes.join('；') : undefined;
         if (rule.mode === 'allow')
             return { filter: { allow: [...new Set([...usable, ...known.mcp])] }, ...(droppedNote === undefined ? {} : { note: droppedNote }) };
         return { filter: { deny: usable }, ...(droppedNote === undefined ? {} : { note: droppedNote }) };
     }
     // 旧格式（全局名单）：保持老行为，白名单同样并入 MCP。
-    const legacyAllow = (persona.tools || []).filter((name) => known.names.has(name));
-    const legacyDeny = (persona.toolsDeny || []).filter((name) => known.names.has(name));
+    const legacyKnown = [...(persona.tools || []), ...(persona.toolsDeny || [])].filter((name) => known.names.has(name));
+    const legacyReserved = stripReserved(legacyKnown);
+    const legacyKept = new Set(legacyReserved.kept);
+    const legacyAllow = (persona.tools || []).filter((name) => legacyKept.has(name));
+    const legacyDeny = (persona.toolsDeny || []).filter((name) => legacyKept.has(name));
     const legacyDropped = [...(persona.tools || []), ...(persona.toolsDeny || [])].filter((name) => !known.names.has(name));
     const filter = {
         ...(legacyAllow.length ? { allow: [...new Set([...legacyAllow, ...known.mcp])] } : {}),
@@ -678,6 +1092,9 @@ export function decideToolFilter(persona, presetId, known) {
     }
     if (legacyDropped.length)
         notes.push(`名单里这些工具当前不存在，已忽略：${legacyDropped.join('、')}`);
+    if (legacyReserved.dropped.length) {
+        notes.push(`名单里的 ${legacyReserved.dropped.join('、')} 是官方保留名（写进工具限制会让子代理直接起不来），已忽略`);
+    }
     if (!Object.keys(filter).length) {
         if (presetId === null && !notes.length)
             notes.push('没能判断当前会话的 Agent 预设，本次不施加工具限制');