dsh-plugin-tool-management 0.9.1 → 0.10.0

package/lib/index.js

@@ -10,18 +10,19 @@
 //
 // Build: `tsc -p tsconfig.json` compiles this to lib/index.js (the shipped
 // artifact — same convention as DSH's own packages, which ship compiled JS).
-import { defineTool } from '@deepseek-ai/dsh-tools';
+import { defineTool as hostDefineTool } from '@deepseek-ai/dsh-tools';
 import { createRequire } from 'node:module';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { ArchiveWorkspaceRegistry as HistoryService, workspaceBaseName, workspacePathKey } from './history/workspace.js';
 import { createSkillsService, pluginLog } from './skills/service.js';
+import { renameWithRetry } from './skills/core.js';
 import { createAgentsMdService } from './agents-md/service.js';
 import { createRulesService, planMemoryExport } from './rules/service.js';
 import { createArchiveEngine } from './rules/archive-engine.js';
 import { createSubagentService, decideToolFilter, defaultPersonasDir } from './subagents/service.js';
 import { createSubagentCatalog } from './subagents/catalog.js';
 import { createSkillCatalog } from './skills/catalog.js';
-import { DEFAULT_INJECT_SETTINGS, createContextInjector, normalizeInjectSettings, } from './context-inject.js';
+import { DEFAULT_INJECT_SETTINGS, createContextInjector, normalizeInjectSettings, subagentDepthOf, } from './context-inject.js';
 import { isApprovalNever } from './approval-policy.js';
 import { EXPECTED_MIN_HOST_VERSION, EXPECTED_PEER_RANGE, VERIFIED_HOST_VERSION, summarize } from './compat/probe.js';
 import { assessPresetReach, injectionFactsOf, presetRosterOf, readCompositionFacts, reachNoticeForAgent } from './compat/preset-reach.js';
@@ -34,7 +35,7 @@ import { defineSubagentManagerListTool, defineSubagentManagerRunTool } from './s
 import { detectFormat, extractText, parseGenericText, parseJsonlTranscript, parseMarkdownTranscript } from './imports/parsers.js';
 import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
-import { mkdir, readdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, stat, unlink, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { zipSync } from 'fflate';
 /**
@@ -154,6 +155,10 @@ export default {
         // is not an injected service and throws "cannot get property without
         // inject" at boot.
         const TOKEN = String(config?.token || process.env.DSH_PLUGIN_TOOL_MANAGEMENT_TOKEN || '').trim();
+        // 令牌比较走「双侧 sha256 → timingSafeEqual」：摘要定长 32 字节，无需长度分支
+        // （直接比较不等长 Buffer 会抛），逐字节的耗时不随匹配前缀长度变化 —— JS 的 ===
+        // 逐字符短路，理论上可被计时侧信道逐位猜测。
+        const tokenMatches = (presented) => timingSafeEqual(createHash('sha256').update(presented).digest(), createHash('sha256').update(TOKEN).digest());
         const wait = (ms) => ctx.timeout(ms);
         const message = (e) => String((e && e.message) || e);
         let writeChain = Promise.resolve();
@@ -572,7 +577,7 @@ export default {
                     await subagentService.enabledStore.setEnabled(on, true);
                 void subagentCatalog.refresh();
             },
-            // 记忆 id 全集（保存 memories 段时校验并报 stale）。
+            // 记忆 id 全集。引擎已不消费（memories 段 P5 起废弃），实现保留以维持接口形状。
             knownMemoryIds: async () => {
                 const r = await rulesService.ops['rules-list']({});
                 return new Set(((r && r.rules) || []).filter((x) => !x.shadowed).map((x) => String(x.id)));
@@ -700,6 +705,9 @@ export default {
         // 注入实况（只读诊断）：注入器的 live() 读回"最近活跃会话"可见表面上的五域文本。
         // 挂在 apply 作用域：`injection-live` op 与注入器不在同一层（effect 内部）。
         let contextInjectorLive = null;
+        // 采纳遥测的入口（同样是 apply 作用域的中转）：工具注册在 effect 之外，
+        // 拿不到 effect 内部的 `injector`；经这个 `let` 中转，热更新重建注入器也能跟上。
+        let contextInjectorNote = null;
         try {
             ctx.effect(() => {
                 const injector = createContextInjector({
@@ -707,18 +715,43 @@ export default {
                     // 顺序即界面勾选与消息顺序（用户裁定 2026-09-16）：场景和记忆 → MCP → 技能 →
                     // 子智能体 → 提示词。form 是宿主语义轴：记忆是「当前状态」（snapshot，后发取代先发），
                     // 三个目录是 catalog，提示词是 instructions（与官方 AGENTS.md 那条行同一形态）。
+                    //
+                    // `applicableTo`（2026-09-17 方案 A）：子智能体域按"**目录该不该注入到这么深的
+                    // 会话**"（人设的 `catalogDepth`，默认 1 = 只在顶层注入）判断，**不是**"能不能
+                    // 委派"。委派可行性由官方决定：`dsh-tool-subagent` 默认 `maxDepth: 3`，provider
+                    // 只在传了该值时才校验，所以子代理本来就能继续嵌套（用户实测确认）。此前判据叫
+                    // "还有没有委派预算"、语义是"还能不能委派"，那是错的 —— 详见 service.ts 里
+                    // `catalogDepth` 字段的注释。目录正文也按同一个判据过滤（`text(agent)`），两处同源
+                    // 所以不会分叉。
+                    //
+                    // 记忆域（2026-09-17 用户裁定）：**只在顶层注入**。记忆是"父会话的现场"，不是子代理
+                    // 完成任务所需的事实 —— 而且它带着「一律照办，覆盖你的默认做法」这种强主张，塞进
+                    // 一次性子会话只会与角色定义争注意力（实测：子代理跑审查时，上下文里同时躺着人设与
+                    // 整份场景记忆）。子代理手里有 `memory_manager_list/read`，需要什么自己取；父代理
+                    // 上下文里也有记忆，相关事实应当由它写进 `task`（子代理的上下文 = 角色 + 任务）。
+                    // 其余三域对任何深度都成立：提示词是用户规则（本插件的立身之本就是"覆盖到子代理"）、
+                    // 技能目录与 MCP 状态是"操作这台机器所需的事实"（子代理手里就有 `skill` / `mcp__*`
+                    // 工具，不知道清单就只能瞎调）。
                     domains: () => [
-                        { key: 'memory', name: 'tool-management:scene-memory', label: '场景和记忆', form: 'snapshot', text: () => rulesService.memoryText() },
+                        { key: 'memory', name: 'tool-management:scene-memory', label: '场景和记忆', form: 'snapshot', text: () => rulesService.memoryText(), applicableTo: (agent) => subagentDepthOf(agent) === 0 },
                         { key: 'mcp', name: 'tool-management:mcp-state', label: 'MCP 服务器', form: 'catalog', text: () => mcpStateCatalog.text() },
                         { key: 'skills', name: 'tool-management:skill-catalog', label: '技能目录', form: 'catalog', text: () => skillCatalog.text() },
-                        { key: 'subagents', name: 'tool-management:subagents', label: '子智能体', form: 'catalog', text: () => subagentCatalog.text() },
-                        { key: 'prompt', name: 'tool-management:prompt', label: '提示词', form: 'instructions', text: () => rulesService.promptText() },
+                        {
+                            key: 'subagents',
+                            name: 'tool-management:subagents',
+                            label: '子智能体',
+                            form: 'catalog',
+                            text: (agent) => subagentCatalog.text(agent),
+                            applicableTo: (agent) => subagentCatalog.catalogVisibleAt(subagentDepthOf(agent)),
+                        },
+                        { key: 'prompt', name: 'tool-management:prompt', label: '提示词', form: 'instructions', text: () => rulesService.promptText(), files: () => rulesService.promptFiles() },
                     ],
                     settings: () => injectSettingsSync(),
                     factsFor: (agent) => presetFactsForAgent(agent),
                 });
                 contextInjectorLive = () => injector.live();
-                return () => { contextInjectorLive = null; injector.dispose(); };
+                contextInjectorNote = (toolName, agent) => injector.noteToolUse(toolName, agent);
+                return () => { contextInjectorLive = null; contextInjectorNote = null; injector.dispose(); };
             }, 'dsh-plugin-tool-management: context injection');
         }
         catch (e) {
@@ -783,12 +816,51 @@ export default {
                 return 0;
             }
         }
+        /**
+         * 人设改名后同步运行时快照（F-025）：退出还原按 `subagentsAll` 逐名走，快照里
+         * 还留着旧名的话，退出会「旧名静默跳过、新名不还原」—— 被改名的人设停留在
+         * 场景期间状态。快照在进入场景时拍、改名发生在进入后，只能在改名时跟着改。
+         */
+        async function renameSubagentInSnapshot(from, to) {
+            try {
+                const slice = await rulesService.readArchiveSlice();
+                const mode = slice && slice.mode;
+                const snapshot = mode && mode.snapshot;
+                if (!snapshot)
+                    return;
+                let changed = false;
+                const next = { ...snapshot };
+                if (snapshot.subagentsAll && Object.prototype.hasOwnProperty.call(snapshot.subagentsAll, from)) {
+                    const all = {};
+                    for (const [k, v] of Object.entries(snapshot.subagentsAll)) {
+                        all[k === from ? to : k] = v;
+                        if (k === from)
+                            changed = true;
+                    }
+                    next.subagentsAll = all;
+                }
+                for (const field of ['subagents', 'subagentsOn']) {
+                    const list = snapshot[field];
+                    if (Array.isArray(list) && list.includes(from)) {
+                        next[field] = list.map((n) => (n === from ? to : n));
+                        changed = true;
+                    }
+                }
+                if (changed)
+                    await rulesService.patchIndex({ mode: { ...mode, snapshot: next } });
+            }
+            catch { /* 快照同步失败不阻断改名本身；残留与修复前一致 */ }
+        }
         const baseSubagentUpdate = subagentService.ops['subagent-update'];
         if (typeof baseSubagentUpdate === 'function') {
             subagentService.ops['subagent-update'] = async (args) => {
                 const res = await baseSubagentUpdate(args);
-                if (res && res.ok !== false && res.renamedFrom)
-                    void rebindSubagentInArchives(String(res.renamedFrom), String(res.name));
+                if (res && res.ok !== false && res.renamedFrom) {
+                    const from = String(res.renamedFrom);
+                    const to = String(res.name);
+                    void rebindSubagentInArchives(from, to);
+                    void renameSubagentInSnapshot(from, to);
+                }
                 return res;
             };
         }
@@ -883,6 +955,10 @@ export default {
             'mcpm-add', 'mcpm-edit', 'mcpm-remove', 'mcpm-set-enabled', 'mcpm-set-all', 'mcpm-restart',
             'mcpm-compact',
             'mcpm-export', 'mcpm-import', 'mcpm-note', 'mcpm-settings', 'mcpm-tool-enabled',
+            // mcpm-tools-refresh 为了拿实时工具表会临时启用目标服务器、结束后恢复原状（两次
+            // writePatch），恢复失败还会停留在启用态 —— 是写不是读，按写门禁（与 mcpm-restart
+            // 已在清单同理；0.6.0/0.7.0 已有两次写 op 漏列前科）。
+            'mcpm-tools-refresh',
             // mcpm-reveal returns UNMASKED secrets; even though it is a read, it is
             // token-gated like a write — on a LAN-exposed port the token must be the
             // last line of defense for plaintext credentials too, not just writes.
@@ -983,7 +1059,8 @@ export default {
          *   - 应用**别的份** = 换掉这个场景的绑定（用户裁定 2026-09-17：未锁定时切换要可用，
          *     并且同步写进场景档案）。绑定改完再走一次场景同步，于是「场景页显示什么 / 实际注入
          *     什么 / 谁是引用方」三处立刻重新对齐（此前的做法是直接拒绝，用户得先退出场景）。
-         * 锁定仍由 `guardLockedOps` 挡住（agentsmd-apply 在冻结清单里）。
+         * 锁定由 `guardLockedOps` 挡住（agentsmd-apply 在冻结清单里）；模型工具
+         * `prompt_manager_apply` 不经过 handlers，execute 里自带 `lockedSceneGuard`（F-001）。
          */
         async function applyPresetGuarded(id) {
             const driver = await scenePromptSync.driver();
@@ -996,6 +1073,7 @@ export default {
                             ok: false,
                             code: 'error.agentsMd.sceneRebindFailed',
                             error: `无法把场景「${driver.label}」的提示词绑定改成「${target}」：${(rebound && rebound.error) || '未知原因'}`,
+                            params: { scene: driver.label, target, reason: String((rebound && rebound.error) || '未知原因') },
                         };
                     }
                 }
@@ -1213,7 +1291,6 @@ export default {
             catch (e) { /* pruning is best-effort */ }
         }
         async function writePatch(abs, content) {
-            const t = await fs.resolve(abs);
             const policy = await sandboxPolicy.resolve({ mode: 'danger-full-access' });
             try {
                 const previous = await readPatch(abs);
@@ -1221,7 +1298,20 @@ export default {
                     await backupPatchFile(abs, previous);
             }
             catch (e) { /* a failed backup must never block the write */ }
-            await fs.writeText(t, content, undefined, undefined, policy);
+            // 同目录临时文件 + rename 原子替换：进程中断/磁盘满最坏留下一个 .tmp 兄弟，
+            // 不会截断补丁本体。官方 app-boot 写这两个补丁文件用的是同一套模式
+            // （`filename + '.tmp'` → rename + 瞬时错误重试，lib/index.js `_writeFile`），
+            // 所以 HMR 对 rename 的容忍不需要额外验证。内容写仍走宿主 fs 服务
+            // （沙箱策略与审批语义不变），rename 只是元数据动作。
+            const temp = abs + '.' + randomUUID().slice(0, 8) + '.dsh-tmp';
+            try {
+                await fs.writeText(await fs.resolve(temp), content, undefined, undefined, policy);
+                await renameWithRetry(temp, abs);
+            }
+            catch (e) {
+                await rm(temp, { force: true }).catch(() => undefined);
+                throw e;
+            }
         }
         // ---------- duplicate loader-id guard ----------
         // Two rows with the same loader id make the plugin composition fail to
@@ -1401,7 +1491,6 @@ export default {
                     managedIds.add(m[1].trim());
             }
             const rows = [];
-            const overrides = [];
             const blocks = [];
             let current = null;
             for (const line of lines) {
@@ -1440,16 +1529,18 @@ export default {
                     }
                 }
                 else {
+                    // 覆盖块按**文件顺序**生效，不是"收集后统一回填"：官方
+                    // `@deepseek-ai/dsh-app-boot` 的 applyEntryPatches 只给此刻已入索引的 id 打补丁
+                    // （insert 是插入时立即入索引），命中不到就 warn + skip。所以写在 insert 之前的
+                    // 覆盖块在宿主侧是 no-op —— 这里同样丢弃，界面才和生效值一致。
                     const entry = parseEntry(block.text.split('\n'));
-                    if (entry && entry.name === '@deepseek-ai/dsh-mcp-client')
-                        overrides.push({ id: entry.id, disabled: entry.disabled });
+                    if (entry && entry.name === '@deepseek-ai/dsh-mcp-client' && entry.disabled !== undefined) {
+                        const row = rows.find((r) => r.id === entry.id);
+                        if (row)
+                            row.disabled = entry.disabled;
+                    }
                 }
             }
-            for (const o of overrides) {
-                const row = rows.find((r) => r.id === o.id);
-                if (row && o.disabled !== undefined)
-                    row.disabled = o.disabled;
-            }
             return { rows };
         }
         // ---------- line-based block editing ----------
@@ -2109,7 +2200,9 @@ export default {
                 toolsList.push({
                     name: known.name,
                     description: known.description || '（服务器未运行；这个名字来自上次运行记录）',
-                    enabled: !disabledHere.has(known.name),
+                    // 与上方 live 行同一口径：整台停用（`*`）时 stale 行同样报停用，
+                    // 否则同页「live 行停用、stale 行启用」自相矛盾。
+                    enabled: wildcardHere ? false : !disabledHere.has(known.name),
                     parameters: [],
                     stale: true,
                 });
@@ -2204,6 +2297,24 @@ export default {
             }
             const toolCounts = {};
             const enabledToolCounts = {};
+            // 只来自**真实 schema** 的两个数，以及只来自**「已知工具」缓存**的一个数。
+            //
+            // 为什么必须与上面那两个分开（2026-09-17 用户实测发现）：`toolCounts` 是三处并集
+            // （live ∪ 停用表 ∪ 缓存），把"这台 server 曾经有什么工具"与"它现在有什么工具"混成了
+            // 一个数。界面状态胶囊与注入段此前读的就是它，于是**一台已经连不上的 server 会被报成
+            // 「已运行」并注入上下文**，模型照着去调 `mcp__X__*`，而那个工具根本没注册 —— 白烧一轮。
+            //
+            // 分开之后三个数各有明确含义：
+            //   liveToolCounts        当前真实注册的工具数（0 = 一个都没注册）
+            //   liveEnabledToolCounts 上面这个数里未被停用表扣减的（真正能调到的）
+            //   knownToolCounts       缓存里的工具数 —— 它是**曾经真的连上过**的证据（缓存只在真实
+            //                         schema 里见到工具时才写入），0 = 从未连上过
+            //
+            // 前两个给状态胶囊与注入段用；`toolCounts` / `enabledToolCounts` 语义不变，继续给场景
+            // 档案挑工具、详情页清单用（那里"上次见过哪些工具"正是需要的，且已标 `stale`）。
+            const liveToolCounts = {};
+            const liveEnabledToolCounts = {};
+            const knownToolCounts = {};
             try {
                 const schemas = await tools.schemas();
                 const knownCache = await readKnownMcpTools();
@@ -2254,6 +2365,17 @@ export default {
                     // 否则收窄后模型看到的数字比它能调的工具多，页面与详情页也会互相矛盾。
                     enabledToolCounts[server] = countEnabledTools(set, disabledMap[server] || []);
                 }
+                // 真实来源的两个数：只数 `liveNames`（schema 里真正注册了的），再按停用表扣减。
+                for (const [server, list] of Object.entries(liveNames)) {
+                    const set = new Set(list);
+                    liveToolCounts[server] = set.size;
+                    liveEnabledToolCounts[server] = countEnabledTools(set, disabledMap[server] || []);
+                }
+                // 「曾经连上过」的证据：缓存里这台 server 见过几个工具。注意读的是**回写之前**的
+                // `knownCache` —— 回写会把这次 live 见到的并进去，而这次 live 见到的本来就已经算在
+                // liveToolCounts 里了，不需要它来充当"曾经"。
+                for (const [server, list] of Object.entries(knownCache))
+                    knownToolCounts[server] = list.length;
                 // 回写「已知工具」：live 见到的名字与描述并入缓存（有变化才写盘，读路径上的 best-effort）。
                 // 名字集合变化，或某个已知工具这次拿到了描述而缓存里没有 → 都算变化。
                 let cacheChanged = false;
@@ -2309,7 +2431,21 @@ export default {
                     row.toolCount = toolCounts[row.serverName] || 0;
                 if (row.enabledToolCount === undefined)
                     row.enabledToolCount = enabledToolCounts[row.serverName] || 0;
-            }
+                // 这三个**总是**覆盖：它们描述的是"此刻的真实状态"，而缓存合并出来的那两个数
+                // 描述的是"这台 server 有过哪些工具"。两者混淆过一次，代价是注入段谎报可用。
+                row.liveToolCount = liveToolCounts[row.serverName] || 0;
+                row.liveEnabledToolCount = liveEnabledToolCounts[row.serverName] || 0;
+                row.knownToolCount = knownToolCounts[row.serverName] || 0;
+            }
+            // 列表顺序（用户要求 2026-09-17）：**全局在前、应用级在后**，各级按服务器名排，
+            // 当前在跑的 loader 行垫底。放在服务端而不是页面里：同一个顺序也是场景档案勾选器
+            // （`scene-inventory`）与模型侧 `mcp_manager_list` 的顺序 —— 三处说同一件事。
+            // 名字比较与技能页同一套（localeCompare），大小写混排时不会把大写全顶到前面。
+            const levelRank = { global: 0, project: 1, loader: 2 };
+            const serverNameOf = (row) => String(row.serverName || row.id || '');
+            rows.sort((a, b) => (levelRank[a.level] ?? 3) - (levelRank[b.level] ?? 3) ||
+                serverNameOf(a).localeCompare(serverNameOf(b)) ||
+                String(a.id).localeCompare(String(b.id)));
             // A loader id that appears twice (same id in both patch files, or twice in
             // one) makes the composition fail to boot. Surface it instead of hiding it.
             const idCounts = new Map();
@@ -2424,6 +2560,17 @@ export default {
             }
             const oldAbs = cur.level === 'global' ? p.globalPatch : p.projectPatch;
             const newAbs = level === 'global' ? p.globalPatch : p.projectPatch;
+            // 编辑表单不建模 config 里的全部键：手写补丁可能带 toolCallTimeoutMs 这类字段，
+            // 重建前从旧条目原样带回，否则一次「编辑」就把它静默删掉。只透传 buildInsertBlock
+            // 已有发射路径的键 —— 其余未知键的保真需要值保持式序列化（裸布尔/数字经
+            // unquote/yq 往返会漂成字符串），不在此处理，宁可如实丢弃也不写错类型。
+            try {
+                const curRaw = parseRows(await readPatch(oldAbs)).rows.find((r) => r.id === id);
+                if (curRaw && curRaw.config && curRaw.config.toolCallTimeoutMs != null) {
+                    row.toolCallTimeoutMs = curRaw.config.toolCallTimeoutMs;
+                }
+            }
+            catch { /* 旧文件读不了时按建模字段重建，与原行为一致 */ }
             const block = buildInsertBlock(row);
             return withWriteLock(async () => {
                 // Per-tool disable state is keyed by the serverName namespace: migrate
@@ -2439,6 +2586,20 @@ export default {
                         catch (e) { /* non-fatal */ }
                         disabledToolsCache = { at: Date.now(), value: toolMap };
                     }
+                    // F-025：运行时快照的 mcp 停用表同样按 serverName 键 —— 改名不跟着改，
+                    // 退出场景整体回写时旧键成死键、新名工具的停用状态丢失（回到全启用）。
+                    try {
+                        const slice = await rulesService.readArchiveSlice();
+                        const mode = slice && slice.mode;
+                        const mcpMap = mode && mode.snapshot && mode.snapshot.mcp;
+                        if (mcpMap && Object.prototype.hasOwnProperty.call(mcpMap, cur.serverName)) {
+                            const next = {};
+                            for (const [k, v] of Object.entries(mcpMap))
+                                next[k === cur.serverName ? serverName : k] = v;
+                            await rulesService.patchIndex({ mode: { ...mode, snapshot: { ...mode.snapshot, mcp: next } } });
+                        }
+                    }
+                    catch { /* 快照同步失败不阻断改名本身；残留与修复前一致 */ }
                 }
                 if (oldAbs !== newAbs) {
                     // Level migration: remove from the old file, insert into the new one.
@@ -2621,6 +2782,16 @@ export default {
             // waits deliberately run OUTSIDE the write lock — holding the global
             // write lock for up to ~11s stalled every other write op.
             await withWriteLock(async () => {
+                // 并发护栏：阶段 1 的强制写自身必然把 effective 状态置为停用，所以走到这里时
+                // 若读到「已启用」，只可能是等待窗口内别的写操作重新启用了它 —— 以现状为准并
+                // 警告，绝不按重启前快照把用户的显式选择改回去。其余情形按 wasDisabled 原样恢复。
+                // （已知残留：窗口内被「停用」与阶段 1 的写不可区分，仍按快照恢复 —— 重启语义
+                // 本就是「状态与重启前一致」，方向性无害。）
+                const currentDisabled = await isRowDisabled(id, level);
+                if (!currentDisabled && wasDisabled) {
+                    warnings.push('重启等待窗口内该服务被重新启用：已保留启用状态，未按重启前状态恢复');
+                    return;
+                }
                 let c = await readPatch(abs);
                 c = removeMarked(c, id, 'disable');
                 if (wasDisabled)
@@ -2764,9 +2935,13 @@ export default {
                         return { skipped: true, reason: 'serverName 已存在' };
                     if (idTaken && !overwrite)
                         return { skipped: true, reason: 'id 已存在' };
+                    // Overwrite: purge every trace of the id from BOTH patch files first,
+                    // then insert the imported row at its own level. The purge is not
+                    // atomic with the insert, so keep the pre-purge content of both files
+                    // and restore it when the insert fails — same trade-off as mcpmEdit's
+                    // level migration: losing the old entries is worse than a transient dup.
+                    const origs = [];
                     if (idTaken && overwrite) {
-                        // Purge every trace of the id from BOTH patch files first, then
-                        // insert the imported row at its own level.
                         for (const lvl of ['project', 'global']) {
                             const lAbs = lvl === 'global' ? p.globalPatch : p.projectPatch;
                             let lContent = '';
@@ -2776,24 +2951,50 @@ export default {
                             catch (e) {
                                 continue;
                             }
-                            lContent = removeEntryAll(lContent, row.id);
+                            origs.push({ abs: lAbs, content: lContent });
                             try {
-                                await writePatch(lAbs, lContent);
+                                await writePatch(lAbs, removeEntryAll(lContent, row.id));
                             }
                             catch (e) {
-                                return { skipped: true, reason: '覆盖旧条目失败: ' + message(e) };
+                                // 前面已清掉的文件也要恢复：purge 中途失败同样不能留下「旧条目没了」的状态。
+                                for (const o of origs) {
+                                    try {
+                                        await writePatch(o.abs, o.content);
+                                    }
+                                    catch { /* best effort */ }
+                                }
+                                return { skipped: true, reason: '覆盖旧条目失败（已回滚）: ' + message(e) };
                             }
                         }
                     }
                     const abs = row.level === 'global' ? p.globalPatch : p.projectPatch;
-                    let c = await readPatch(abs);
-                    const before = c;
-                    c = appendBlock(c, buildInsertBlock(row));
-                    if (row.disabled)
-                        c = appendBlock(c, buildDisableBlock(row.id, true));
-                    if (duplicateGuard(before, c))
-                        return { skipped: true, reason: '会产生重复的 loader id' };
-                    await writePatch(abs, c);
+                    try {
+                        let c = await readPatch(abs);
+                        const before = c;
+                        c = appendBlock(c, buildInsertBlock(row));
+                        if (row.disabled)
+                            c = appendBlock(c, buildDisableBlock(row.id, true));
+                        const guard = duplicateGuard(before, c);
+                        if (guard) {
+                            for (const o of origs) {
+                                try {
+                                    await writePatch(o.abs, o.content);
+                                }
+                                catch { /* best effort */ }
+                            }
+                            return { skipped: true, reason: guard.error };
+                        }
+                        await writePatch(abs, c);
+                    }
+                    catch (e) {
+                        for (const o of origs) {
+                            try {
+                                await writePatch(o.abs, o.content);
+                            }
+                            catch { /* best effort */ }
+                        }
+                        return { skipped: true, reason: '写入失败（已回滚）: ' + message(e) };
+                    }
                     return { added: true, wasOverwrite: idTaken && overwrite };
                 });
                 if (res.added) {
@@ -3425,10 +3626,12 @@ export default {
                     ctx.logger?.warn?.('agents-md: reference probe failed; remove allowed');
                 const why = refs ? refs.get(id) || [] : [];
                 if (why.length) {
+                    const refsText = why.map(promptRefReason).join('；');
                     return {
                         ok: false,
                         code: 'error.agentsMd.referenced',
-                        error: `「${id}」仍被引用，不能删除：${why.map(promptRefReason).join('；')}。先改掉引用（换绑提示词 / 退出场景 / 应用别的预设）再删除。`,
+                        error: `「${id}」仍被引用，不能删除：${refsText}。先改掉引用（换绑提示词 / 退出场景 / 应用别的预设）再删除。`,
+                        params: { id, refs: refsText },
                     };
                 }
                 return agentsMdService.remove(id);
@@ -4483,9 +4686,50 @@ export default {
         }
         // ---------- agent-facing tools (standard ctx.tools.register + defineTool) ----------
         const text = (value) => [{ type: 'text', text: value }];
+        /**
+         * 采纳遥测：把每个工具包一层，模型一调就记一笔"哪个域被伸手了"（见 context-inject 的
+         * `noteToolUse`）。计数在宿主工具对象之外，所以**参数校验失败也算**——我们要测的是
+         * "模型知不知道有这个域、会不会去用"，不是"调用写得对不对"。
+         *
+         * 只统计本插件自己的工具，不走 `tools/result` 这类宿主事件：事件的作用域语义一旦变化，
+         * 遥测会静默变成 0，而 0 恰好会被读成"模型从来不用"——一个假结论比没有结论更糟。
+         * 包自己的工具是确定性的：工具在，观测就在。
+         */
+        const trackAdoption = (def) => {
+            const name = String(def.name ?? '');
+            const run = def.execute;
+            if (name === '' || typeof run !== 'function')
+                return def;
+            return {
+                ...def,
+                async execute(args, exec) {
+                    try {
+                        if (contextInjectorNote !== null)
+                            contextInjectorNote(name, exec && exec.agent);
+                    }
+                    catch { /* 遥测绝不能影响工具 */ }
+                    return run(args, exec);
+                },
+            };
+        };
+        /**
+         * 与宿主 `defineTool` **同签名的**本地包装。
+         *
+         * 为什么用同名遮蔽而不是逐个改 14 个注册点：采纳遥测必须覆盖**每一个**域工具，
+         * 漏一个就得到"这个域从来没用过"的假结论。遮蔽 import 让"新加工具自动被统计"成为
+         * 默认，而不是靠后来者记得手动加。
+         *
+         * 类型上刻意**不重写签名**，而是把箭头函数断言成 `typeof hostDefineTool`：宿主签名带
+         * `const S/O` 类型参数，照着写一遍会让 TS 在每个调用点上多展开一层 `InferObject<S, ?>`，
+         * 直接撞 "Excessive stack depth comparing types"（实测）。断言成宿主自己的类型之后，
+         * 14 个调用点的参数表推断与改造前**完全一致** —— 宿主改签名时该报错的地方照旧报错；
+         * 包装体本身只是转发（参数收 `unknown`、原样交给宿主），不参与推断，也就没有可失效的类型。
+         */
+        const hostDefineToolAny = hostDefineTool;
+        const defineTool = ((options) => trackAdoption(hostDefineToolAny(options)));
         tools.register(defineTool({
             name: 'mcp_manager_list',
-            description: 'List configured MCP servers (level, enabled state, live loader status, tool count excluding switched-off tools, note). Read a server\'s note before choosing it. Defaults to enabled servers; pass all=true for every configured server.',
+            description: 'List configured MCP servers (level, enabled state, live loader status, tool count excluding switched-off tools, note). Read a server\'s note before choosing it. The same list is injected into your context each turn (the「本机 MCP 服务器的当前状态」system-reminder); this tool is the raw view — all=true includes disabled servers. Defaults to enabled servers; pass all=true for every configured server.',
             parameters: {
                 all: { type: 'boolean', description: 'Include disabled servers (default false).' },
             },
@@ -4577,6 +4821,9 @@ export default {
             },
             output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
             async execute(args) {
+                const blocked = await lockedSceneGuard();
+                if (blocked)
+                    throw new Error(blocked);
                 const r = await mcpmAdd(args);
                 if (!r.ok)
                     throw new Error(r.error);
@@ -4587,7 +4834,7 @@ export default {
         // tools/pre-execute hook below (the model must ask before writing files).
         tools.register(defineTool({
             name: 'skill_manager_list',
-            description: 'List DSH skills with enabled state, effective/shadowed status and source file path. Defaults to enabled skills only; pass all=true for every entry. A copy marked "shadowed by <root>" stays inactive even if enabled.',
+            description: 'List DSH skills with enabled state, effective/shadowed status and source file path. The injected「本机技能目录」system-reminder carries callable skills and summaries only; use this tool to get a source file path (read the file for the full body) and to see entries that are off. Defaults to enabled skills only; pass all=true for every entry. A copy marked "shadowed by <root>" stays inactive even if enabled.',
             parameters: {
                 all: { type: 'boolean', description: 'Include disabled and shadowed entries (default false).' },
             },
@@ -4706,6 +4953,9 @@ export default {
             },
             output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
             async execute(args) {
+                const blocked = await lockedSceneGuard();
+                if (blocked)
+                    throw new Error(blocked);
                 const r = await skillsService.ops['skill-create']({ name: args.name, description: args.description, body: args.body });
                 if (!r || r.ok === false)
                     throw new Error((r && r.error) || 'skill create failed');
@@ -4716,7 +4966,7 @@ export default {
         // AGENTS.md 预设库：模型可查/切，不能造/删（避免模型乱删用户预设）。
         tools.register(defineTool({
             name: 'prompt_manager_list',
-            description: 'List AGENTS.md presets (id, active state, file path). Read that file to see a preset body. Defaults to the preset currently in effect; pass all=true for the whole library.',
+            description: 'List AGENTS.md presets (id, active state, file path). Read that file to see a preset body. The preset in effect right now is injected into your context each turn (the「本机提示词」system-reminder, whose「来源：」line names the file). Defaults to the preset currently in effect; pass all=true for the whole library.',
             parameters: {
                 all: { type: 'boolean', description: 'Include inactive presets (default false).' },
             },
@@ -4761,6 +5011,9 @@ export default {
             },
             output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
             async execute(args) {
+                const blocked = await lockedSceneGuard();
+                if (blocked)
+                    throw new Error(blocked);
                 const r = await applyPresetGuarded(args.id);
                 if (!r.ok)
                     throw new Error(r.error);
@@ -4773,7 +5026,7 @@ export default {
         // 路径锚点：$DSH_HOME/tool-management/memories/<场景>/…（场景 `global` = 界面「全局」）。
         tools.register(defineTool({
             name: 'memory_manager_list',
-            description: 'List memories under ~/.dsh/tool-management/memories (id, scene, enabled, description). Defaults to the memories that will actually be injected; pass all=true for every entry.',
+            description: 'List memories under ~/.dsh/tool-management/memories (id, scene, enabled, description). The ones actually injected are carried in your context each turn (the「本机当前的场景和记忆」system-reminder); use this tool to find ids/paths or to see entries that are off. Defaults to the memories that will actually be injected; pass all=true for every entry.',
             parameters: {
                 group: { type: 'string', description: 'Optional scene filter.' },
                 all: { type: 'boolean', description: 'Include memories that are off, in an inactive scene, or shadowed (default false).' },
@@ -4839,6 +5092,9 @@ export default {
             },
             output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
             async execute(args) {
+                const blocked = await lockedSceneGuard();
+                if (blocked)
+                    throw new Error(blocked);
                 const r = await rulesService.ops['rules-create'](args);
                 if (!r || r.ok === false)
                     throw new Error((r && r.error) || '创建规则失败');
@@ -4919,11 +5175,13 @@ export default {
                         .catch(() => ({ kind: 'ask', reason: 'Write a memory under ~/.dsh/tool-management/memories' }));
                 }
                 // subagent_manager_run：子代理运行花真 token：默认确认（requireConfirmForModelSubagentRun !== false），可关。
+                // `inherit: true` 时子代理会读到本次会话已完成的对话 —— 卡里如实说明（用户批准的是
+                // "把这段对话交给它"，不只是"跑个子代理"）。文案只在与 fork 有关的部分分叉。
+                const inherits = !!(exec && exec.arguments && exec.arguments.inherit);
+                const ask = { kind: 'ask', reason: inherits ? 'Run a subagent on this conversation (it inherits the conversation; consumes tokens)' : 'Run a subagent (consumes tokens)' };
                 return readPluginSettings()
-                    .then((s) => (s.requireConfirmForModelSubagentRun !== false
-                    ? { kind: 'ask', reason: 'Run a subagent (consumes tokens)' }
-                    : next()))
-                    .catch(() => ({ kind: 'ask', reason: 'Run a subagent (consumes tokens)' }));
+                    .then((s) => (s.requireConfirmForModelSubagentRun !== false ? ask : next()))
+                    .catch(() => ask);
             });
         }
         // ---------- per-tool MCP switches: execution guard + visibility ----------
@@ -5040,7 +5298,7 @@ export default {
                             res.end(JSON.stringify({ ok: false, error: 'missing plugin gate header' }));
                             return;
                         }
-                        const tokenAccepted = TOKEN !== '' && hdr('x-dsh-token') === TOKEN;
+                        const tokenAccepted = TOKEN !== '' && tokenMatches(hdr('x-dsh-token'));
                         if (!tokenAccepted) {
                             const fence = fenceRejection(req, connection);
                             if (fence) {
@@ -5074,7 +5332,7 @@ export default {
                                     return;
                                 }
                             }
-                            if (TOKEN && WRITE_OPS.has(op) && hdr('x-dsh-token') !== TOKEN) {
+                            if (TOKEN && WRITE_OPS.has(op) && !tokenMatches(hdr('x-dsh-token'))) {
                                 res.end(JSON.stringify({ ok: false, error: '缺少或错误的访问令牌（x-dsh-token）' }));
                                 return;
                             }