dsh-plugin-tool-management 0.6.0 → 0.8.0

package/lib/subagents/service.js

@@ -5,9 +5,10 @@
 // v0.4 目录变更：人设由 `$DSH_HOME/subagents/` 搬到 `$DSH_HOME/tool-management/agents/`
 // （插件产生的文件统一收在 tool-management/ 下）。旧目录在首次扫描时搬入，见 relocateLegacyPersonas。
 import { createRequire } from 'node:module';
-import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { resolveDshHome } from '../skills/core.js';
+import { listTrashEntries, moveOutOfTrash, moveToTrash, purgeTrashEntry, readTrashEntry } from '../hub.js';
 import { expandUploads, planPersonaImport } from '../imports/upload.js';
 const message = (e) => String((e && e.message) || e);
 /** 人设默认目录：`$DSH_HOME/tool-management/agents/`。 */
@@ -50,25 +51,66 @@ async function relocateLegacyPersonas(dir) {
         }
     }
 }
-/** 行式 frontmatter 解析：只认 description / provider / model / tools / toolsDeny 五个键。 */
+/** 逗号/顿号分隔的名字清单（空串 → undefined）。 */
+function listOf(value) {
+    const text = String(value ?? '').trim();
+    if (!text)
+        return undefined;
+    const list = text.split(/[,，]/).map((s) => s.trim()).filter(Boolean);
+    return list.length ? list : undefined;
+}
+/**
+ * 解析 `toolsByPreset:` 块 —— 每个 Agent 预设一行：
+ *
+ * ```yaml
+ * toolsByPreset:
+ *   standard: allow: read, write
+ *   ptc: deny: workflow
+ * ```
+ *
+ * 缩进即"在块内"，回到顶格即块结束（frontmatter 只有这一处嵌套，所以不需要完整
+ * YAML 解析器）。模式 id 只做形状校验，认不认得由运行时按当前预设名单判断。
+ */
+export function parsePresetToolRules(frontmatter) {
+    const rules = {};
+    let inBlock = false;
+    for (const raw of frontmatter.split(/\r?\n/)) {
+        const line = raw.replace(/\s+#.*$/, '');
+        if (!inBlock) {
+            if (/^toolsbypreset\s*:\s*$/i.test(line.trim()))
+                inBlock = true;
+            continue;
+        }
+        if (line.trim() === '')
+            continue;
+        if (!/^\s/.test(line))
+            break;
+        const m = /^\s*([A-Za-z0-9._-]+)\s*:\s*(allow|deny)\s*:\s*(.*)$/i.exec(line);
+        if (!m)
+            continue;
+        const names = listOf(m[3]);
+        // 空名单 = 不限制 = 不落盘，读到时也直接忽略，免得把"没开"读成"开了但空"。
+        if (!names)
+            continue;
+        rules[m[1]] = { mode: m[2].toLowerCase() === 'deny' ? 'deny' : 'allow', names };
+    }
+    return Object.keys(rules).length ? rules : undefined;
+}
+/** 行式 frontmatter 解析：只认 description / provider / model / tools / toolsDeny / toolsByPreset。 */
 export function parsePersona(raw, fallbackName) {
     const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
     const data = {};
     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();
         }
+        toolsByPreset = parsePresetToolRules(m[1]);
         body = raw.slice(m[0].length);
     }
-    const listOf = (value) => {
-        if (!value)
-            return undefined;
-        const list = value.split(/[,，]/).map((s) => s.trim()).filter(Boolean);
-        return list.length ? list : undefined;
-    };
     const tools = listOf(data.tools);
     // 兼容两种写法：`toolsdeny: a, b`（线上格式）与 `toolsDeny: a, b`（键名统一小写后同形）。
     const toolsDeny = listOf(data.toolsdeny);
@@ -80,6 +122,7 @@ export function parsePersona(raw, fallbackName) {
         model: data.model || undefined,
         tools,
         toolsDeny,
+        ...(toolsByPreset === undefined ? {} : { toolsByPreset }),
         body: body.trim(),
         path: '',
     };
@@ -87,26 +130,98 @@ export function parsePersona(raw, fallbackName) {
 const RESULT_MAX = 16 * 1024;
 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, 'agents-index.json');
     const req = createRequire(import.meta.url);
     let cache = null;
-    async function list() {
-        if (cache && Date.now() - cache.at < 1000)
-            return cache.value;
-        // 旧目录搬家放在首次扫描前（幂等；失败不阻断，旧目录仍会被下面的读取兜底看到）。
-        await relocateLegacyPersonas(dir).catch(() => undefined);
-        const docs = [];
+    // ── 人设启用集合（子智能体开关）────────────────────────────────────────
+    // agents-index.json：{ version: 1, enabled: string[] }（与 rules-index.json 同目录约定）。
+    //   - 文件缺失/损坏 = **全部启用**（老用户升级零感知，行为与开关上线前一致）；
+    //   - 文件一旦写出即为权威：之后新建/导入/回收站恢复的人设**自动启用**（刚建就想用是常理）；
+    //   - 停用只影响注入与 subagent_* 工具的可见性，人设文件一个字节不动。
+    // 缓存约定：undefined = 还没读过盘；null = 文件缺失（全部启用）；数组 = 权威集合。
+    let enabledCache = undefined;
+    async function readEnabled() {
+        if (enabledCache !== undefined)
+            return enabledCache;
+        // 用局部变量过渡：await 之后 TS 对闭包级缓存变量的收窄会失效，直接返回会报 undefined。
+        let next;
         try {
-            const entries = await readdir(dir);
-            for (const fileName of entries.filter((e) => e.endsWith('.md')).sort()) {
-                const raw = await readFile(join(dir, fileName), 'utf8').catch(() => '');
-                if (!raw.trim())
-                    continue;
-                docs.push({ ...parsePersona(raw, fileName.slice(0, -3)), path: join(dir, fileName) });
+            const raw = JSON.parse(await readFile(stateFile, 'utf8'));
+            next = Array.isArray(raw && raw.enabled) ? raw.enabled.map((x) => String(x)) : [];
+        }
+        catch {
+            next = null;
+        }
+        enabledCache = next;
+        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;
+    }
+    /** 新建/导入/恢复的人设默认启用；文件缺失（本来就全启用）时无需写。 */
+    async function enablePersonaNames(names) {
+        const set = await readEnabled();
+        if (set === null)
+            return;
+        let dirty = false;
+        for (const n of names)
+            if (set.indexOf(n) < 0) {
+                set.push(n);
+                dirty = true;
+            }
+        if (dirty)
+            await writeEnabled(set);
+    }
+    /** 改名跟随：旧名在集合里就改新名；不在（停用中）保持停用。 */
+    async function renamePersonaInEnabled(from, to) {
+        const set = await readEnabled();
+        if (set === null)
+            return;
+        const i = set.indexOf(from);
+        if (i < 0)
+            return;
+        set[i] = to;
+        await writeEnabled(set);
+    }
+    /** 删除后从集合摘掉，别留悬空名（列表时无害，但会让集合越攒越脏）。 */
+    async function removePersonaFromEnabled(name) {
+        const set = await readEnabled();
+        if (set === null || set.indexOf(name) < 0)
+            return;
+        await writeEnabled(set.filter((n) => n !== name));
+    }
+    /** list() 输出统一附上 enabled：文件缺失 → 全 true；否则按集合。 */
+    function withEnabled(docs, set) {
+        if (set === null)
+            return docs.map((d) => ({ ...d, enabled: true }));
+        return docs.map((d) => ({ ...d, enabled: set.indexOf(d.name) >= 0 }));
+    }
+    async function list() {
+        let docs;
+        if (cache && Date.now() - cache.at < 1000) {
+            docs = cache.value;
+        }
+        else {
+            // 旧目录搬家放在首次扫描前（幂等；失败不阻断，旧目录仍会被下面的读取兜底看到）。
+            await relocateLegacyPersonas(dir).catch(() => undefined);
+            const fresh = [];
+            try {
+                const entries = await readdir(dir);
+                for (const fileName of entries.filter((e) => e.endsWith('.md')).sort()) {
+                    const raw = await readFile(join(dir, fileName), 'utf8').catch(() => '');
+                    if (!raw.trim())
+                        continue;
+                    fresh.push({ ...parsePersona(raw, fileName.slice(0, -3)), path: join(dir, fileName) });
+                }
             }
+            catch { /* 目录缺失 = 无人设 */ }
+            cache = { at: Date.now(), value: fresh };
+            docs = fresh;
         }
-        catch { /* 目录缺失 = 无人设 */ }
-        cache = { at: Date.now(), value: docs };
-        return docs;
+        return withEnabled(docs, await readEnabled());
     }
     // spawn provider 在场性（设计 §3.2，落地方式见 cordis.patch.yml 的取舍注释）：
     // 官方通道探测（ctx.subagents.list()）→ 缺失才挂载 → 失败把原因原样带出（不吞、不谎报）。
@@ -155,8 +270,14 @@ export function createSubagentService(ctx, opts) {
             throw new Error('spawn provider 挂载后仍未出现在 ctx.subagents.list()（宿主版本不匹配？）');
         return runtime;
     }
-    async function runOnce(parentAgent, p, task, signal) {
+    async function runOnce(parentAgent, p, task, signal, toolFilter) {
         const runtime = await ensureSpawnProvider();
+        // 工具限制三态：对象 = 调用方已按当前预设决定；null = 调用方明确决定不加限制；
+        // undefined = 调用方没决定（如别的入口直接调 runSerial）→ 回落人设里的旧格式全局名单。
+        const legacyFilter = (p.tools?.length || p.toolsDeny?.length)
+            ? { ...(p.tools?.length ? { allow: p.tools } : {}), ...(p.toolsDeny?.length ? { deny: p.toolsDeny } : {}) }
+            : null;
+        const resolved = toolFilter === undefined ? legacyFilter : toolFilter;
         // 官方签名：start(name, request) —— name = ctx.subagents 上的 provider 注册名。
         const run = await runtime.start('spawn', {
             label: p.name,
@@ -166,10 +287,8 @@ export function createSubagentService(ctx, opts) {
             prompt: [{ type: 'text', text: task }],
             persona: p.body,
             // 工具白/黑名单 → 官方 ToolRestriction（`deny` 优先级高于 `allow`；未知名官方会直接拒绝启动，
-            // 所以选择器给的是「全体预设工具并集」，见 index.ts presetToolCandidates）。
-            ...((p.tools?.length || p.toolsDeny?.length)
-                ? { toolFilter: { ...(p.tools?.length ? { allow: p.tools } : {}), ...(p.toolsDeny?.length ? { deny: p.toolsDeny } : {}) } }
-                : {}),
+            // 所以名单由 index.ts 按当前预设 + 当前真实存在的工具名算好再传进来，见 decideToolFilter）。
+            ...(resolved === null ? {} : { toolFilter: resolved }),
             maxDepth: 1,
             // provider 与 model 是模型路由的两半：DSH 的 resolveModel(provider, model) 不做
             // `provider/model` 字符串拆分，只改 model 会落在**主会话的 provider** 上——跨来源
@@ -197,8 +316,8 @@ export function createSubagentService(ctx, opts) {
     }
     // v1 串行：同一时刻至多一个子代理运行（设计 §3.2）。
     let chain = Promise.resolve();
-    const runSerial = (parentAgent, p, task, signal) => {
-        const queued = chain.then(() => runOnce(parentAgent, p, task, signal), () => runOnce(parentAgent, p, task, signal));
+    const runSerial = (parentAgent, p, task, signal, toolFilter) => {
+        const queued = chain.then(() => runOnce(parentAgent, p, task, signal, toolFilter), () => runOnce(parentAgent, p, task, signal, toolFilter));
         chain = queued.catch(() => undefined);
         return queued;
     };
@@ -207,7 +326,7 @@ export function createSubagentService(ctx, opts) {
             const docs = await list();
             return {
                 ok: true,
-                subagents: docs.map((p) => ({ name: p.name, description: p.description, provider: p.provider ?? null, model: p.model ?? null, tools: p.tools ?? null, toolsDeny: p.toolsDeny ?? null })),
+                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 })),
             };
         },
         'subagent-get': async (args) => {
@@ -216,7 +335,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 ?? [], 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 ?? {}, body: p.body } };
         },
         'subagent-create': async (args) => {
             const name = String((args && args.name) || '').trim();
@@ -235,9 +354,17 @@ export function createSubagentService(ctx, opts) {
                 return { ok: false, error: `创建人设目录失败: ${dir}（${message(e)}）` };
             }
             await writeFile(target, serializePersona(args), 'utf8');
+            // 新建即启用（文件缺失 = 本来全启用，无需写）；缓存失效让下次 list 带上新成员。
+            await enablePersonaNames([name]).catch(() => undefined);
             cache = null;
             return { ok: true, name };
         },
+        /**
+         * 保存人设，**可选改名**（nextName）。
+         * 人设名就是文件名（`agents/<名>.md`），所以改名 = 重命名文件；
+         * 目标名已存在直接拒绝，绝不覆盖别人的文件。
+         * 返回 `renamedFrom` 供调用方把场景档案里的绑定一起改掉（档案存的是人设名）。
+         */
         'subagent-update': async (args) => {
             const name = String((args && args.name) || '').trim();
             if (!validPersonaName(name))
@@ -246,17 +373,84 @@ export function createSubagentService(ctx, opts) {
             const exists = await readFile(target, 'utf8').then(() => true).catch(() => false);
             if (!exists)
                 return { ok: false, error: `人设不存在: ${name}` };
-            await writeFile(target, serializePersona(args), 'utf8');
+            let finalName = name;
+            let renamedFrom;
+            const nextRaw = args && args.nextName !== undefined ? String(args.nextName).trim() : '';
+            if (nextRaw !== '' && nextRaw !== name) {
+                if (!validPersonaName(nextRaw)) {
+                    return { ok: false, error: `新人设名不合法: ${nextRaw}（非空、≤64 字符、不含路径分隔符与 < > : " | ? *、不以 . 开头）` };
+                }
+                const nextTarget = join(dir, nextRaw + '.md');
+                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');
+            if (renamedFrom)
+                await renamePersonaInEnabled(renamedFrom, finalName).catch(() => undefined);
             cache = null;
-            return { ok: true, name };
+            return { ok: true, name: finalName, ...(renamedFrom ? { renamedFrom } : {}) };
         },
+        /**
+         * 删除人设 = **移入回收站**（`hub/trash/agents-trash/<id>/persona.md`）。
+         * 早先这里是 `rm`，而界面按钮写着「移入回收站」——文案与行为不一致；现在行为追上文案，
+         * 误删可以从子智能体页的回收站里恢复。
+         */
         'subagent-delete': async (args) => {
             const name = String((args && args.name) || '').trim();
             if (!validPersonaName(name))
                 return { ok: false, error: `人设名不合法: ${name || '(空)'}` };
-            await rm(join(dir, name + '.md')).catch(() => { });
+            const target = join(dir, name + '.md');
+            const exists = await readFile(target, 'utf8').then(() => true).catch(() => false);
+            if (!exists)
+                return { ok: false, error: `人设不存在: ${name}` };
+            const moved = await moveToTrash('agents', 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 };
+            return { ok: true, name, trashId: moved.id };
+        },
+        'subagent-trash-list': async () => ({ ok: true, trash: await listTrashEntries('agents') }),
+        'subagent-trash-restore': async (args) => {
+            const id = String((args && args.id) || '').trim();
+            const entry = await readTrashEntry('agents', id);
+            if (!entry)
+                return { ok: false, error: `回收站条目不存在: ${id}` };
+            if (!validPersonaName(entry.name))
+                return { ok: false, error: `回收站里的人设名不合法: ${entry.name}` };
+            const target = join(dir, entry.name + '.md');
+            const exists = await readFile(target, 'utf8').then(() => true).catch(() => false);
+            // 绝不覆盖：同名人设已经存在时如实拒绝，让人自己决定怎么办。
+            if (exists)
+                return { ok: false, error: `无法恢复，同名人设已存在: ${entry.name}` };
+            try {
+                await mkdir(dir, { recursive: true });
+                await moveOutOfTrash('agents', id, 'persona.md', target);
+            }
+            catch (e) {
+                return { ok: false, error: `恢复失败: ${message(e)}` };
+            }
+            await purgeTrashEntry('agents', id);
+            // 恢复 = 拿回来用：自动启用（文件缺失本来就全启用，无需写）。
+            await enablePersonaNames([entry.name]).catch(() => undefined);
+            cache = null;
+            return { ok: true, name: entry.name };
+        },
+        'subagent-trash-delete': async (args) => {
+            const id = String((args && args.id) || '').trim();
+            const gone = await purgeTrashEntry('agents', id);
+            if (!gone)
+                return { ok: false, error: `回收站条目不存在: ${id}` };
+            return { ok: true, id };
         },
         /**
          * 导入人设（.md / .zip）：一个 .md 一个人设，文件名（去扩展名）= 人设名；
@@ -297,25 +491,115 @@ export function createSubagentService(ctx, opts) {
                 }
                 imported.push(target.name);
             }
-            if (imported.length)
+            if (imported.length) {
+                await enablePersonaNames(imported).catch(() => undefined);
                 cache = null;
+            }
             return { ok: true, imported, skipped };
         },
+        /**
+         * 子智能体开关（v0.8）：停用 = 不注入目录段、subagent_list/run 不可见；文件本体不动。
+         * `enabled` 必须显式给布尔值 —— 与 rules-toggle 同一条口径：不按"翻转"推断，
+         * 免得参数丢了时界面以为改了、实际什么都没动。
+         */
+        'subagent-toggle': async (args) => {
+            const name = String((args && args.name) || '').trim();
+            if (!validPersonaName(name))
+                return { ok: false, error: `人设名不合法: ${name || '(空)'}` };
+            if (typeof (args && args.enabled) !== 'boolean') {
+                return { ok: false, error: '缺少参数：enabled 必须是布尔值（只按传入值写入，不做"翻转"推断）' };
+            }
+            const docs = await list();
+            if (!docs.some((d) => d.name === name))
+                return { ok: false, error: `人设不存在: ${name}` };
+            const set = await readEnabled();
+            // 文件缺失 = 当前全启用：首次开关时把现状物化成显式集合（否则"部分停用"无处落笔）。
+            const base = (set === null ? docs.map((d) => d.name) : set.slice()).filter((n) => docs.some((d) => d.name === n));
+            const i = base.indexOf(name);
+            if (args.enabled === true) {
+                if (i < 0)
+                    base.push(name);
+            }
+            else if (i >= 0) {
+                base.splice(i, 1);
+            }
+            await writeEnabled(base);
+            cache = null;
+            return { ok: true, name, enabled: args.enabled === true };
+        },
+    };
+    const enabledStore = {
+        /** 指定名单里当前被停用的（进入模式拍快照用：只记将被启用的行，退出时精确停回）。 */
+        async disabledAmong(names) {
+            const docs = await list();
+            const state = new Map(docs.map((d) => [d.name, d.enabled !== false]));
+            return names.filter((n) => state.get(n) === false);
+        },
+        /** 批量启停；只碰给出的名字，人设已不存在的跳过（别把悬空名写进集合）。 */
+        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;
+                }
+                if (!enabled && i >= 0) {
+                    base.splice(i, 1);
+                    dirty = true;
+                }
+            }
+            if (dirty) {
+                await writeEnabled(base);
+                cache = null;
+            }
+        },
     };
-    return { list, runSerial, ops, writeOps: new Set(['subagent-create', 'subagent-update', 'subagent-delete', 'subagent-import']) };
+    return { list, runSerial, ops, enabledStore, writeOps: new Set(['subagent-create', 'subagent-update', 'subagent-delete', 'subagent-import', 'subagent-toggle', 'subagent-trash-restore', 'subagent-trash-delete']) };
 }
 function validPersonaName(name) {
     return name.length > 0 && name.length <= 64 && !name.startsWith('.') && !/[\\/<>:"|?*]/.test(name);
 }
+/** 字符串数组规范化（非数组/空项都丢掉）。 */
+function toStringList(value) {
+    return Array.isArray(value) ? value.map((x) => String(x).trim()).filter(Boolean) : [];
+}
+/**
+ * 规范化前端传来的 `toolsByPreset`：丢掉空名单（空 = 不限制 = 不落盘），
+ * 模式 id 只收形状合法的（预设 id 允许字母数字点横线）。
+ */
+export function presetRulesOf(value) {
+    if (value === null || typeof value !== 'object')
+        return [];
+    const out = [];
+    for (const [rawId, rawRule] of Object.entries(value)) {
+        const id = String(rawId).trim();
+        if (!id || !/^[A-Za-z0-9._-]+$/.test(id))
+            continue;
+        if (rawRule === null || typeof rawRule !== 'object')
+            continue;
+        const rec = rawRule;
+        const names = toStringList(rec.names);
+        if (!names.length)
+            continue;
+        out.push([id, { mode: String(rec.mode) === 'deny' ? 'deny' : 'allow', names }]);
+    }
+    return out;
+}
 /** 人设文件序列化：frontmatter 只写用户填过的键；正文 = 人设提示词。 */
 export function serializePersona(args) {
     const description = String((args && args.description) || '').replace(/\r?\n/g, ' ').trim();
     const provider = String((args && args.provider) || '').trim();
     const model = String((args && args.model) || '').trim();
-    const toList = (v) => (Array.isArray(v) ? v.map((x) => String(x).trim()).filter(Boolean) : []);
-    const tools = toList(args?.tools);
+    const tools = toStringList(args?.tools);
     // 黑名单字段兼容两种入参名：toolsDeny（UI/camel）与 tools_deny（snake）。
-    const toolsDeny = toList(args?.toolsDeny ?? args?.tools_deny);
+    const toolsDeny = toStringList(args?.toolsDeny ?? args?.tools_deny);
+    const byPreset = presetRulesOf(args?.toolsByPreset);
     const body = String((args && args.body) ?? '').trim();
     const lines = ['---'];
     if (description)
@@ -328,6 +612,65 @@ export function serializePersona(args) {
         lines.push('tools: ' + tools.join(', '));
     if (toolsDeny.length)
         lines.push('toolsDeny: ' + toolsDeny.join(', '));
+    if (byPreset.length) {
+        lines.push('toolsByPreset:');
+        for (const [id, rule] of byPreset)
+            lines.push('  ' + id + ': ' + rule.mode + ': ' + rule.names.join(', '));
+    }
     lines.push('---', '', body, '');
     return lines.join('\n');
 }
+/**
+ * 按**当前会话的 Agent 预设**决定这次委派下发什么工具限制。
+ *
+ * 为什么必须按预设分：子代理跑在父会话的预设里（官方 `composeFrom(childCtx, parent.ctx)`），
+ * 而各预设的工具集合差别极大（极简模式只有持久 shell），官方 `tools.restrict()` 遇到
+ * 名单里不存在的工具名会直接抛错、子代理根本起不来。所以：
+ *
+ *   - 当前预设配了名单（且名单非空）→ 用它；白名单额外并入**当时真实在跑的 MCP 工具**
+ *     （官方 allow 是"清单之外全砍"，不并进来会把 MCP 一起砍掉；用户裁定：子代理要能
+ *     用当前启动的 MCP）；
+ *   - 当前预设没配 → 回落旧的全局 `tools` / `toolsDeny`（老文件行为不变）；
+ *   - 名单里有已经消失的工具名 → **丢掉并在 note 里如实说明**（不接受静默失效）；
+ *   - 判断不了当前预设（老宿主 / 异常）→ 不按模式施加，并在 note 里说明。
+ *
+ * 三态返回：`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 dropped = rule.names.filter((name) => !known.names.has(name));
+        const droppedNote = dropped.length ? `名单里这些工具当前不存在，已忽略：${dropped.join('、')}` : undefined;
+        if (!usable.length) {
+            return { filter: null, note: `「${presetId}」的${rule.mode === 'allow' ? '白' : '黑'}名单里没有当前存在的工具，本次不施加工具限制` };
+        }
+        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 legacyDropped = [...(persona.tools || []), ...(persona.toolsDeny || [])].filter((name) => !known.names.has(name));
+    const filter = {
+        ...(legacyAllow.length ? { allow: [...new Set([...legacyAllow, ...known.mcp])] } : {}),
+        ...(legacyDeny.length ? { deny: legacyDeny } : {}),
+    };
+    const notes = [];
+    const hasLegacy = Boolean((persona.tools || []).length || (persona.toolsDeny || []).length);
+    if (presetId === null) {
+        // 说清这一刻到底靠什么在跑：有旧格式就照旧格式，没有就明说"按模式配的限制这次不生效"。
+        notes.push(hasLegacy
+            ? '没能判断当前会话的 Agent 预设，按旧格式的全局名单执行'
+            : '没能判断当前会话的 Agent 预设，按模式配的限制这次不生效');
+    }
+    if (legacyDropped.length)
+        notes.push(`名单里这些工具当前不存在，已忽略：${legacyDropped.join('、')}`);
+    if (!Object.keys(filter).length) {
+        if (presetId === null && !notes.length)
+            notes.push('没能判断当前会话的 Agent 预设，本次不施加工具限制');
+        return { filter: null, ...(notes.length ? { note: notes.join('；') } : {}) };
+    }
+    return { filter, ...(notes.length ? { note: notes.join('；') } : {}) };
+}

package/lib/subagents/tools.js

@@ -1,12 +1,19 @@
 export function text(v) {
     return [{ type: 'text', text: v }];
 }
-/** 场景绑定校验（设计 §3.3）：启用场景的 subagents 并集；空并集 = 全部可用。 */
+/**
+ * 可见性过滤（两道闸，按序）：
+ *   ① 人设开关（全局）：停用的绝不进上下文 —— 即便它被场景绑定（场景启动时会自动把
+ *      绑定的人设启用，见 archive-engine 的 applySubagentSwitches）。
+ *   ② 场景绑定校验（设计 §3.3）：启用场景的 subagents 并集；空并集 = 全部可用。
+ * 之前只有②：全局默认所有子智能体都进上下文，没有开关可言。
+ */
 export async function filterBySceneBinding(docs, enabledSceneLists) {
+    const live = docs.filter((d) => d.enabled !== false);
     const bound = new Set(enabledSceneLists.flat());
     if (!bound.size)
-        return { allowed: docs, reason: null };
-    const allowed = docs.filter((d) => bound.has(d.name));
+        return { allowed: live, reason: null };
+    const allowed = live.filter((d) => bound.has(d.name));
     return { allowed, reason: allowed.length ? null : `当前启用场景的子智能体绑定: ${[...bound].join('、')}` };
 }
 export function defineSubagentListTool(subagents) {
@@ -54,9 +61,15 @@ export function defineSubagentRunTool(subagents) {
                 const available = allowed.map((p) => p.name).join('、') || '(无)';
                 throw new Error('人设不可用: ' + name + (reason ? '（' + reason + '）' : '（可用: ' + available + '）'));
             }
-            const r = await subagents.runSerial(exec.agent, persona, task, exec.signal);
+            // 按当前会话的 Agent 预设算工具限制：判断不了当前预设、或名单里的工具已经不存在时，
+            // 结论里会带一句实话，跟着结果一起返回——不静默改变限制的强度。
+            const decision = typeof subagents.toolFilterFor === 'function'
+                ? await subagents.toolFilterFor(persona, exec.agent && exec.agent.ctx)
+                : undefined;
+            const r = await subagents.runSerial(exec.agent, persona, task, exec.signal, decision === undefined ? undefined : decision.filter);
             const prefix = r.stopReason && r.stopReason !== 'completed' ? `[stopReason: ${r.stopReason}]\n` : '';
-            return prefix + r.text;
+            const note = decision && decision.note ? `⚠ ${decision.note}\n\n` : '';
+            return note + prefix + r.text;
         },
     };
 }