dsh-plugin-tool-management 0.9.1 → 0.11.0

package/lib/subagents/tools.js

@@ -1,3 +1,6 @@
+// 深度探针（`subagentDepthOf`）与目录判据（`catalogInjectedAt`）都不再需要：
+// 2026-09-17 方案 A 之后，这两个工具都不再看会话深度 —— 委派由官方决定（默认能嵌套到 3 层），
+// `catalogDepth` 只管常驻目录注入到哪些会话。
 export function text(v) {
     return [{ type: 'text', text: v }];
 }
@@ -19,7 +22,7 @@ export async function filterBySceneBinding(docs, enabledSceneLists) {
 export function defineSubagentManagerListTool(subagents) {
     return {
         name: 'subagent_manager_list',
-        description: 'List available personas (pre-configured subagent profiles) with their descriptions. Call before subagent_manager_run.',
+        description: 'List available personas (pre-configured subagent profiles) with their descriptions. The same catalog is injected into your context each turn (the「可委派的子智能体」system-reminder); call this tool before subagent_manager_run for the full, always-current list.',
         parameters: {},
         output: {
             schema: { type: 'string' },
@@ -27,6 +30,10 @@ export function defineSubagentManagerListTool(subagents) {
         },
         async execute(_args, exec) {
             const { allowed, reason } = await filterBySceneBinding(await subagents.list(), await subagents.sceneLists());
+            // 这里**不再按深度过滤**（2026-09-17 用户裁定，方案 A）：`catalogDepth` 只决定常驻目录
+            // 注入到哪些会话，与"能不能委派"无关 —— 委派由官方决定（`dsh-tool-subagent` 默认能嵌套
+            // 到 3 层）。此前按深度过滤等于把可用人设藏起来：目录不注入时模型只能靠这个工具查，
+            // 而工具又不列全，结果是"明明能委派却查不到人设"。
             const lines = allowed.map((p) => '- ' + p.name + ' — ' + (p.description || '(无描述)'));
             let notice = '';
             try {
@@ -42,10 +49,21 @@ export function defineSubagentManagerListTool(subagents) {
 export function defineSubagentManagerRunTool(subagents) {
     return {
         name: 'subagent_manager_run',
-        description: 'Run a named persona as a one-shot subagent: it gets the persona as its own system prompt, works on `task` in a fresh context, and returns only its final output. Stateless — it does not see this conversation. Expensive: starts a fresh model session, so use it only for self-contained work.',
+        // 描述按「是什么 → 两种模式 → 何时用（含与官方两个委派工具的分界）→ 何时改用别的」组织。
+        // 2026-09-17 补了**分界规则**与 `inherit`：此前上下文里虽然注入了人设目录与「用
+        // subagent_manager_run 执行」，但没有任何一句话说明它和官方 `subagent` / `subagent_fork`
+        // 何时该用谁 —— 本机实测（session-ee722e23）模型读完 README 后选了官方 `subagent_fork`
+        // （fork 能继承已读内容、不必复述）。现在人设通道也有 fork（`inherit`），分界只剩
+        // 「要不要后台跑」一件事，所以规则能写成"贴合人设的一律走这里"。
+        //
+        // 「何时不用」那一段保留（2026-09-17，用户采纳的四条里的第 6 条）：参照 Claude Code 的
+        // Agent 工具（`AgentTool/prompt.ts:232-240`），把"不该用"写成**带替代工具**的具体清单
+        // （具体路径→Read；找定义→Grep/Glob），比笼统说"这个很贵"有用得多。
+        description: 'Run a named persona as a subagent: it gets the persona as its own system prompt, works on `task`, and returns only its final output.\n\nTwo modes: by default the child starts fresh — it cannot see this conversation, so `task` must be self-contained. With `inherit: true` the child is seeded with this conversation\'s finished turns (the same mechanism as the host\'s `subagent_fork`), so `task` only states what is new — use it for follow-ups on work already completed. Only **finished** turns are inherited: a delegation made during the current turn inherits nothing from that turn, so a mid-turn hand-off still needs a self-contained `task`.\n\nWrite `task` as the goal plus the context it needs — do not prescribe method or output format: those belong to the persona.\n\nWhen to use: work that matches one of the personas in the「可委派的子智能体」system-reminder injected into your context (or from subagent_manager_list) — a review, a focused investigation, a piece of writing — where the detail does not belong in your own context. Work that matches a persona belongs here, not in the host\'s `subagent` / `subagent_fork`: those take no persona. Use them only when no persona fits, or when you need a background run (this tool waits for the result).\n\nWhen NOT to use: reading a specific file (use Read), finding a definition (use Grep/Glob), or touching two or three files (use Read directly).',
         parameters: {
             agent: { type: 'string', required: true, description: 'Persona name from subagent_manager_list.' },
-            task: { type: 'string', required: true, description: 'Self-contained task, with all context the subagent needs.' },
+            task: { type: 'string', required: true, description: 'The task for the subagent: the goal plus the context it needs. Self-contained by default; with inherit: true it only needs to state what is new. Leave method and output format to the persona.' },
+            inherit: { type: 'boolean', description: 'Let the subagent inherit this conversation\'s finished turns, like the host\'s subagent_fork (default false = a fresh child that cannot see this conversation). Only finished turns are inherited — a delegation made mid-turn cannot pass the current turn\'s content, so write `task` as if it were self-contained.' },
         },
         output: {
             schema: { type: 'string' },
@@ -54,6 +72,7 @@ export function defineSubagentManagerRunTool(subagents) {
         async execute(args, exec) {
             const name = String((args && args.agent) || '').trim();
             const task = String((args && args.task) || '').trim();
+            const inherit = args && args.inherit === true;
             if (!task)
                 throw new Error('task 不能为空');
             // 官方 SubagentStartRequest.parent 必填：调用方 agent 缺失时给结构化错误，不把 undefined 透传下去。
@@ -66,12 +85,18 @@ export function defineSubagentManagerRunTool(subagents) {
                 const available = allowed.map((p) => p.name).join('、') || '(无)';
                 throw new Error('人设不可用: ' + name + (reason ? '（' + reason + '）' : '（可用: ' + available + '）'));
             }
+            // 这里**刻意没有**"深度不够就拒绝"的检查（2026-09-17 用户裁定，方案 A）。
+            // 它此前基于一个错误假设：以为传 `maxDepth: 1` 会让子会话再委派必然失败。实际上官方
+            // `dsh-tool-subagent` 的默认是 **3**、provider 只在**传了值**时才校验，所以子代理本来
+            // 就能继续嵌套。那个检查的唯一净效果是让**我们的**工具比官方严 —— 同一个子会话里官方
+            // 工具能委派、我们的被自己拦下 —— 而用户真想禁止嵌套也禁止不了（官方工具照样能）。
+            // `catalogDepth` 现在只管"目录注入到哪些会话"，不参与委派可行性判断。
             // 按当前会话的 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 r = await subagents.runSerial(exec.agent, persona, task, exec.signal, decision === undefined ? undefined : decision.filter, inherit);
             const prefix = r.stopReason && r.stopReason !== 'completed' ? `[stopReason: ${r.stopReason}]\n` : '';
             const note = decision && decision.note ? `⚠ ${decision.note}\n\n` : '';
             return note + prefix + r.text;

package/lib/tools/deps.js

@@ -0,0 +1,8 @@
+// model 工具（ctx.tools.register + defineTool）各域共用的依赖与 helper。
+//
+// 为什么单独一个文件：五个域的工具都要同一批依赖（defineTool 包装、注册出口、场景锁定
+// 守卫、注入边界提示），各写一份会漂移。
+/** 每个工具 output.render 的统一出口：把字符串包成宿主要的 content 数组。 */
+export function text(value) {
+    return [{ type: 'text', text: value }];
+}

package/lib/tools/mcp.js

@@ -0,0 +1,110 @@
+// MCP 域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
+// mcp_manager_list / mcp_manager_set_enabled / mcp_manager_restart / mcp_manager_add。
+import { DEFAULT_MCP_NOTE_MAX_LENGTH, normalizeMcpNote } from '../mcp/state-section.js';
+import { text } from './deps.js';
+export function buildMcpTools(deps) {
+    const { defineTool, register } = deps;
+    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. 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).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args, exec) {
+            const showAll = Boolean(args && args.all === true);
+            // 必须走 mcpmListView()（= mcpmRowsWithNotes(false)）：备注在这里合入，且未打码的
+            // url/headers/env 已被打码。备注是本插件 MCP 这一项的真正价值（用户写给未来模型的
+            // 决策提示，如「A 挂了改用 B」），而它只走注入通道 —— 压制型预设下不注入时，
+            // 这里就是唯一的读取路径。
+            const r = await deps.mcpmListView();
+            if (!r.ok)
+                throw new Error(r.error);
+            const all = r.rows || [];
+            // 默认只列「已启用」的（用户裁定 2026-09-16，与技能 / 记忆列表同口径）：停用的服务器
+            // 模型调不到，列出来只是噪音。表头给出全量口径，所以不会变成盲区。
+            const shown = showAll ? all : all.filter((x) => !x.disabled);
+            const summary = shown.map((x) => {
+                const note = normalizeMcpNote(x.notes, DEFAULT_MCP_NOTE_MAX_LENGTH);
+                // 工具数 = 可用数（停用表扣减后）：段里给模型的是同一个口径，模型据此与
+                // 自己 schema 里的 `mcp__*` 工具对得上；被场景收窄 / 手动关掉的工具不算。
+                const usableTools = typeof x.enabledToolCount === 'number' ? x.enabledToolCount : x.toolCount;
+                return x.id + ' | ' + x.serverName + ' | ' + x.level + ' | ' + (x.disabled ? 'disabled' : 'enabled') +
+                    (x.live ? ' | loader:' + (x.live.enabled ? 'on' : 'off') + (x.live.phase ? ':' + x.live.phase : '') : '') +
+                    (typeof usableTools === 'number' ? ' | tools:' + usableTools : '') +
+                    (note ? ' | user-hint:' + note : '');
+            });
+            const header = 'MCP servers: ' + (showAll
+                ? all.length + ' configured'
+                : shown.length + ' enabled of ' + all.length + ' configured' +
+                    (shown.length === all.length ? '' : ' (pass all=true for every configured server)')) + '\n';
+            // 注入边界：压制型预设（persona complete / 关闭运行时上下文，如极简）下本插件
+            // 默认不注入 —— 模型只有 mcp__* 的工具名与参数，没有服务级信息。不说明的话，
+            // 模型会把「能调用这些工具」当成「已经知道有哪些 server、用户给它们写了什么备注」。
+            // 提示本身不点名任何工具，所以挂在哪个发现型工具上都不会出现循环指引。
+            const notice = await deps.reachNoticeForAgent(deps.presetRoster(), exec && exec.agent && exec.agent.ctx, deps.injectNoticeOptions());
+            return header + (summary.join('\n') || '(none)') + notice;
+        },
+    }));
+    register(defineTool({
+        name: 'mcp_manager_set_enabled',
+        description: 'Enable or disable one configured MCP server (writes the patch file; takes effect via HMR).',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Entry id of the MCP server, e.g. mcp-stepfun-web-search.' },
+            level: { type: 'string', required: true, description: 'project or global.' },
+            enabled: { type: 'boolean', required: true, description: 'true to enable, false to disable.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            const r = await deps.mcpmSetEnabled({ id: args.id, level: args.level, enabled: args.enabled });
+            if (!r.ok)
+                throw new Error(r.error);
+            // 场景未锁定时，页面 / 模型改的开关都要落进当前场景的档案（与 handlers 层同一套同步）。
+            const syncErr = await deps.syncSwitchToScene('mcpm-set-enabled', args);
+            return 'OK: ' + args.id + ' now ' + (args.enabled ? 'enabled' : 'disabled') +
+                (syncErr ? '\nWARN: 当前场景档案未同步（' + syncErr + '）' : '');
+        },
+    }));
+    register(defineTool({
+        name: 'mcp_manager_restart',
+        description: 'Restart one configured MCP server (disable + re-enable; reconnect and re-sync tools).',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Entry id of the MCP server, e.g. mcp-stepfun-web-search.' },
+            level: { type: 'string', required: true, description: 'project or global.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const r = await deps.mcpmRestart({ id: args.id, level: args.level });
+            if (!r.ok)
+                throw new Error(r.error);
+            return 'OK: ' + args.id + ' restarted';
+        },
+    }));
+    register(defineTool({
+        name: 'mcp_manager_add',
+        description: 'Add a new MCP server (streamable-http or stdio) at project or global level.',
+        parameters: {
+            serverName: { type: 'string', required: true, description: 'Unique server name (1-32 chars, [A-Za-z0-9_-]).' },
+            transport: { type: 'string', required: true, description: 'streamable-http or stdio.' },
+            url: { type: 'string', description: 'Server URL (required for streamable-http).' },
+            command: { type: 'string', description: 'Executable (required for stdio).' },
+            args: { type: 'string', description: 'Arguments, space separated (stdio).' },
+            headers: { type: 'string', description: 'Extra headers as key=value lines (streamable-http).' },
+            env: { type: 'string', description: 'Extra env vars as key=value lines (stdio).' },
+            level: { type: 'string', description: 'project or global (default project).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            const r = await deps.mcpmAdd(args);
+            if (!r.ok)
+                throw new Error(r.error);
+            return 'OK: added ' + r.row.id + ' at ' + r.row.level;
+        },
+    }));
+}

package/lib/tools/memory.js

@@ -0,0 +1,87 @@
+// 记忆（rules）域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
+// memory_manager_list / memory_manager_read / memory_manager_write。
+//
+// 活动场景的记忆正文会自动注入上下文（无需调用工具读取）；这里的工具用于查询/编辑规则
+// 本身。memory_manager_write 受 tools/pre-execute 审批门禁（D2）。
+// 路径锚点：$DSH_HOME/tool-management/memories/<场景>/…（场景 `global` = 界面「全局」）。
+import { text } from './deps.js';
+export function buildMemoryTools(deps) {
+    const { defineTool, register } = deps;
+    register(defineTool({
+        name: 'memory_manager_list',
+        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).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args, exec) {
+            const showAll = Boolean(args && args.all === true);
+            const r = await deps.rulesOps['rules-list'](args);
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '读取规则失败');
+            // 「会注入」的判定与记忆段同源（renderSceneMemory）：global 场景恒常注入，其余场景要
+            // 在 index.active 里，再叠加单条 enabled 与同名 bundle 的 shadowed。默认只列这些，
+            // 全列一次会把没启用的条目也算进上下文（用户裁定 2026-09-16，与技能列表同口径）。
+            const sceneOn = (group) => group === 'global' ||
+                (group !== '' && (r.activeMode === 'all' || String(r.activeScene || '') === group));
+            const stateOf = (x) => {
+                if (x.shadowed === true)
+                    return { injects: false, label: '被同名覆盖' };
+                if (x.enabled === false)
+                    return { injects: false, label: '已停用' };
+                if (!sceneOn(String(x.group || '')))
+                    return { injects: false, label: '场景未启用' };
+                return { injects: true, label: '已启用' };
+            };
+            const rows = (r.rules || []).map((x) => ({ x, ...stateOf(x) }));
+            const shown = showAll ? rows : rows.filter((row) => row.injects);
+            const lines = shown.map(({ x, label }) => ('- ' + x.id + ' [' + (x.group || '未归属场景') + '] ' + label +
+                (x.description ? ' — ' + x.description : '')));
+            const scenes = (r.scenes || []).map((s) => (s.label || s.name) + (s.active ? '(启用)' : '(未启用)')).join('、');
+            const header = '记忆：' + (showAll
+                ? rows.length + ' 条'
+                : shown.length + ' 条会注入 / 共 ' + rows.length + ' 条' +
+                    (shown.length === rows.length ? '' : '（传 all=true 看全部）')) + '\n';
+            // 注入边界：压制型预设（persona complete / 关闭运行时上下文）下本插件默认不注入，
+            // 此时列出的记忆**不在**模型上下文里。必须说出来，否则模型会假设自己已经看到正文。
+            const notice = await deps.reachNoticeForAgent(deps.presetRoster(), exec && exec.agent && exec.agent.ctx, deps.injectNoticeOptions());
+            return header + (lines.join('\n') || '(无记忆)') +
+                '\n场景：' + (scenes || '(无)') + (r.activeMode === 'all' ? '（默认全部启用）' : '（已收窄）') + notice;
+        },
+    }));
+    register(defineTool({
+        name: 'memory_manager_read',
+        description: 'Read the full body of one memory under ~/.dsh/tool-management/memories. Call it only for memories that are not already in your context (disabled, unassigned to a scene, or dropped by the injection budget).',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Memory id like <scene>/<name>.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const r = await deps.rulesOps['rules-read'](args);
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '读取规则失败');
+            return '# ' + r.rule.id + '\n\n' + (r.rule.body || '');
+        },
+    }));
+    register(defineTool({
+        name: 'memory_manager_write',
+        description: 'Create a new memory as ~/.dsh/tool-management/memories/<scene>/<name>.md. The scene must already exist (use global for the always-on scene).',
+        parameters: {
+            group: { type: 'string', required: true, description: 'Scene name (no path separators or < > : " | ? *); `global` = the always-on scene.' },
+            name: { type: 'string', required: true, description: 'Memory name = .md file name without extension; <=64 chars, no path separators or < > : " | ? *, must not start with a dot.' },
+            description: { type: 'string', required: true, description: 'One-sentence description (<=500 chars).' },
+            body: { type: 'string', required: true, description: 'Markdown body (<=256 KiB).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            const r = await deps.rulesOps['rules-create'](args);
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '创建规则失败');
+            return 'OK: memory ' + r.rule.id + '（场景「' + (r.rule.group || '未归属') + '」启用后自动生效）';
+        },
+    }));
+}

package/lib/tools/prompt.js

@@ -0,0 +1,70 @@
+// AGENTS.md 预设域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
+// prompt_manager_list / prompt_manager_apply。
+//
+// 模型可查、可切，**不能造 / 不能删** —— 避免模型乱删用户预设。
+import { join } from 'node:path';
+import { text } from './deps.js';
+export function buildPromptTools(deps) {
+    const { defineTool, register } = deps;
+    register(defineTool({
+        name: 'prompt_manager_list',
+        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).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args, exec) {
+            const showAll = Boolean(args && args.all === true);
+            const r = await deps.promptsService.list();
+            if (!r.ok)
+                throw new Error(r.error);
+            const all = r.presets || [];
+            // 默认只列「当前这份 ~/.dsh/AGENTS.md 是从哪个预设来的」（用户裁定 2026-09-16）。
+            // 判定分两级：内容逐字节相同 = 生效；否则看服务层记下的「最近一次应用」——
+            // 用户手改过全局文件时，第二级仍能给出答案，不必退化成全列（那会白烧上下文）。
+            const active = all.filter((p) => p.active === true);
+            const fallback = active.length ? active : all.filter((p) => p.lastApplied === true);
+            const shown = showAll ? all : fallback;
+            // 路径这一列是「名单 → 全文」的闭环：预设正文既不进提示词、也没有读取工具，
+            // 给出文件路径让模型用宿主的文件工具读，比再造一个 read 工具省一条常驻 schema。
+            const summary = shown.map((p) => {
+                const mark = p.active ? ' [active]'
+                    : p.lastApplied ? ' [last applied — ~/.dsh/AGENTS.md has changed since]'
+                        : '';
+                return p.id + mark + ' | ' + join(deps.promptsDir, p.id, 'AGENTS.md');
+            });
+            const header = 'AGENTS.md presets: ' + (showAll
+                ? all.length + ' in the library'
+                : fallback.length
+                    ? fallback.length + (active.length ? ' active' : ' last applied') + ' of ' + all.length +
+                        (fallback.length === all.length ? '' : ' (pass all=true for the whole library)')
+                    : '0 active of ' + all.length + ' (pass all=true for the whole library)') + '\n';
+            // 同上：AGENTS.md 由官方 dsh-agent-instructions 行承载（极简没挂这一行），
+            // 这一行不在时文件内容不会进上下文。
+            const notice = await deps.reachNoticeForAgent(deps.presetRoster(), exec && exec.agent && exec.agent.ctx, deps.injectNoticeOptions());
+            return header + (summary.join('\n') || '(none)') + '\n(DSH re-reads ~/.dsh/AGENTS.md every turn, so applying takes effect on the next turn.)' + notice;
+        },
+    }));
+    register(defineTool({
+        name: 'prompt_manager_apply',
+        description: 'Apply one AGENTS.md preset by id; effective on the next turn. If a scene currently drives the baseline, this does NOT refuse: it rebinds that scene\'s prompt binding to the preset and re-syncs the scene, so ~/.dsh/AGENTS.md ends up holding the scene\'s (new) binding — tell the user which scene was rebound. Otherwise the preset is written to ~/.dsh/AGENTS.md directly. A locked scene blocks the call.',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Preset id (lowercase letters, digits, hyphens).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            const r = await deps.applyPresetGuarded(args.id);
+            if (!r.ok)
+                throw new Error(r.error);
+            // 场景驱动时写的是「场景绑定」，回执必须说清改的是哪个场景 —— 只说「已应用到
+            // AGENTS.md」会让模型对用户谎报（用户不知道自己的场景绑定被换掉了）。
+            if (r.viaScene) {
+                return 'OK: preset ' + args.id + ' is now the prompt binding of scene 「' + (r.scene || '') + '」 and the scene was re-synced (effective next turn; ~/.dsh/AGENTS.md now carries that scene\'s binding).';
+            }
+            return 'OK: preset ' + args.id + ' applied to ~/.dsh/AGENTS.md (next session; current session unchanged' + (r.backedUp ? '; previous backed up to __last-applied__' : '') + ')';
+        },
+    }));
+}

package/lib/tools/skills.js

@@ -0,0 +1,139 @@
+// 技能域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
+// skill_manager_list / skill_manager_set_enabled / skill_manager_create。
+import { text } from './deps.js';
+export function buildSkillTools(deps) {
+    const { defineTool, register } = deps;
+    // Skill-facing tools: list, toggle, create. create is gated by the
+    // tools/pre-execute hook below (the model must ask before writing files).
+    register(defineTool({
+        name: 'skill_manager_list',
+        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).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args, exec) {
+            const showAll = Boolean(args && args.all === true);
+            const r = await deps.skillsOps['skill-state']({});
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || 'skill-state failed');
+            const data = r.data || {};
+            // 同名（canonical = declaredName || name）跨根重复时只有**一份**生效，排序规则是
+            // 「同名首选 > 来源优先级 rank」，**与启用状态无关**（core 的 groupLoadableSkillsByName）。
+            // 于是「启用被覆盖的那份」是静默无效的：工具会回 OK，技能却依然不可用 —— 用户实测
+            // 踩到的正是这个坑（同一技能在 dsh/agents/claude/custom 各有一份，启错根等于没启）。
+            // 这里把生效/被覆盖如实标出来，让模型（和人）不必猜。
+            //
+            // 默认只列启用的（2026-09-16 用户裁定）：本机 36 条里只有 1 条启用，全列一次约 4.3k
+            // 字符且永久留在 transcript。表头始终给出全量口径（多少条 / 多少同名组），所以
+            // 「还有没列出来的」不会变成盲区 —— 要看就传 all=true。
+            const rows = [];
+            const counts = new Map();
+            for (const root of data.roots || []) {
+                for (const skill of root.skills || []) {
+                    const key = String(skill.declaredName || skill.name || '');
+                    counts.set(key, (counts.get(key) || 0) + 1);
+                    // `enabled` 只写在「胜出者」上（core 的 markWinners）；影子副本与不可加载的技能
+                    // 没有这个字段。原先直接读 skill.enabled，这些技能一律被报成 disabled ——
+                    // 这里改用与界面同口径的兜底推导（client 的 isSkillEnabled）。
+                    const enabled = skill.enabled !== undefined
+                        ? skill.enabled === true
+                        : (skill.invocationPolicyValid && skill.modelInvocable && skill.userInvocable && skill.managerEnabled !== false);
+                    const marks = [];
+                    if (skill.shadowedBy && skill.shadowedBy.root)
+                        marks.push('shadowed by ' + skill.shadowedBy.root);
+                    if (skill.preferred === true)
+                        marks.push('preferred');
+                    rows.push({
+                        root: String(root.key || ''),
+                        enabled,
+                        text: (skill.name || skill.declaredName || '') + ' | ' + (root.key || '') + ' | ' + (enabled ? 'enabled' : 'disabled') +
+                            (marks.length ? ' | ' + marks.join(' ') : '') +
+                            (skill.path ? ' | ' + skill.path : ''),
+                    });
+                }
+            }
+            const dupGroups = [...counts.values()].filter((n) => n > 1).length;
+            const shown = showAll ? rows : rows.filter((row) => row.enabled);
+            const header = 'Skills: ' + (showAll
+                ? rows.length + ' entries'
+                : shown.length + ' enabled of ' + rows.length + ' entries') +
+                (dupGroups ? ' · ' + dupGroups + ' duplicated names' : '') +
+                (showAll || shown.length === rows.length ? '' : ' (pass all=true to include disabled and shadowed entries)') + '\n';
+            // 注入边界：预设没挂 dsh-tool-skill（如极简）时官方技能目录不在，本插件的
+            // 「技能目录」注入域会在开关打开时兜底（见上面的注入通道）；两者都没有时模型看到的
+            // 只是这份名单 —— 说清边界，别让它以为上下文里已经有技能正文（正文用路径读）。
+            const notice = await deps.reachNoticeForAgent(deps.presetRoster(), exec && exec.agent && exec.agent.ctx, deps.injectNoticeOptions());
+            return header + (shown.map((row) => row.text).join('\n') || '(none)') + notice;
+        },
+    }));
+    register(defineTool({
+        name: 'skill_manager_set_enabled',
+        description: 'Enable or disable one DSH skill (manager policy only; source files are never modified). Enabling a shadowed copy has no effect.',
+        parameters: {
+            name: { type: 'string', required: true, description: 'Skill name (kebab-case).' },
+            enabled: { type: 'boolean', required: true, description: 'true to enable, false to disable.' },
+            root: { type: 'string', description: 'Source root key (dsh/agents/codex/claude or a project key); default dsh.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            const root = String(args.root || 'dsh');
+            const op = args.enabled ? 'skill-enable' : 'skill-disable';
+            const r = await deps.skillsOps[op]({ name: args.name, root });
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || 'skill toggle failed');
+            // 场景未锁定时同步进当前场景档案（与 handlers 层同一套同步）。
+            const syncErr = await deps.syncSwitchToScene(op, { name: args.name, root, enabled: args.enabled === true });
+            // 静默无效是这个工具最容易骗人的地方：同名胜负只由「首选 > 来源优先级」决定，
+            // 与启用状态无关。对影子副本操作会返回 OK，但技能依然不可用。如实说一句。
+            let shadowedBy = '';
+            try {
+                const state = await deps.skillsOps['skill-state']({});
+                for (const rt of (state && state.data && state.data.roots) || []) {
+                    for (const skill of rt.skills || []) {
+                        if (String(skill.declaredName || skill.name || '') !== String(args.name))
+                            continue;
+                        if (String(rt.key || '') !== root)
+                            continue;
+                        if (skill.shadowedBy && skill.shadowedBy.root)
+                            shadowedBy = String(skill.shadowedBy.root);
+                    }
+                }
+            }
+            catch {
+                shadowedBy = '';
+            }
+            const warn = shadowedBy
+                ? ' — BUT this copy is shadowed by the same-name skill in "' + shadowedBy + '", so it stays inactive: enable that copy instead, or make this root the preferred copy in the panel'
+                : '';
+            const sceneWarn = syncErr ? '\nWARN: 当前场景档案未同步（' + syncErr + '）' : '';
+            return 'OK: ' + args.name + ' now ' + (args.enabled ? 'enabled' : 'disabled') + warn + sceneWarn;
+        },
+    }));
+    register(defineTool({
+        name: 'skill_manager_create',
+        // 落点必须和 UI「创建技能」一致：两者都走 core 的默认落点（hub 的
+        // tool-management/skills/，hub 缺失时退回 DSH_HOME/skills）。以前这里硬编码
+        // root:'dsh'，于是同一个「新建技能」动作，人点界面和模型调用会落到两个不同的根。
+        description: 'Create a new DSH skill under DSH_HOME/tool-management/skills. Use only when the user explicitly asks to create or save a reusable skill.',
+        parameters: {
+            name: { type: 'string', required: true, description: 'Skill name; normalized to kebab-case.' },
+            description: { type: 'string', required: true, description: 'A concise routing description for when to use the skill.' },
+            body: { type: 'string', required: true, description: 'Markdown instructions that form the skill body.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            const r = await deps.skillsOps['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');
+            const data = r.data || {};
+            return 'Created DSH skill ' + (data.name || args.name) + ' at ' + (data.path || '(unknown)');
+        },
+    }));
+}

package/lib/tools/subagent.js

@@ -0,0 +1,40 @@
+// 子智能体域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
+// subagent_manager_list / subagent_manager_run。
+//
+// exec.agent / exec.signal 由工具运行时提供（parent 与取消信号的官方通道）。
+//
+// 两个工具**各自** try/catch：一个注册失败不该把另一个也带走，而且失败必须说得出
+// 「是哪一个没注册上」——只打一行日志时，模型侧只会「查无此工具」、界面毫无痕迹。
+import { defineSubagentManagerListTool, defineSubagentManagerRunTool } from '../subagents/tools.js';
+export function buildSubagentTools(deps) {
+    const { defineTool, register } = deps;
+    const recordFailure = (name, e) => {
+        deps.failures.list.push({ name, reason: deps.message(e) });
+        if (deps.failures.logged)
+            return;
+        deps.failures.logged = true;
+        console.error('[dsh-plugin-tool-management] subagent tool registration failed:', name, deps.message(e));
+    };
+    try {
+        // 与其余 12 个工具同一条注册通道：defineTool 负责编译 parameters（object root + required），
+        // 裸 register 会把未编译的参数声明直接发给模型 API。
+        register(defineTool(defineSubagentManagerListTool({
+            list: () => deps.subagentService.list(),
+            sceneLists: deps.sceneLists,
+            // 与其余发现型工具同口径：压制型预设下不注入时，人设目录不在模型上下文里，
+            // 只有工具可用。挂上边界提示，模型才不会把「看不到人设」当成「没有人设」。
+            noticeFor: (exec) => deps.reachNoticeForAgent(deps.presetRoster(), exec && exec.agent && exec.agent.ctx, deps.injectNoticeOptions()),
+        })));
+    }
+    catch (e) {
+        recordFailure('subagent_manager_list', e);
+    }
+    try {
+        // 工具限制按**当前会话的 Agent 预设**下发：父会话跑在哪个预设，就用那个预设那一行的
+        // 白/黑名单（`decideToolFilter`），名单里已消失的工具名会被丢掉并在结果里如实说明。
+        register(defineTool(defineSubagentManagerRunTool({ ...deps.subagentService, sceneLists: deps.sceneLists, toolFilterFor: deps.toolFilterFor })));
+    }
+    catch (e) {
+        recordFailure('subagent_manager_run', e);
+    }
+}