dsh-plugin-tool-management 0.20.3 → 0.21.0

package/lib/subagents/run-provider.js

@@ -8,7 +8,9 @@
 // 就等于换了解析基准。传引用才谈得上逐字不变。
 // 运行侧不碰人设清单的那份缓存（`cache` / `enabledCache` 都在 service.ts 那一层），
 // 所以它只需要 ctx / req / message 三件。
+import { randomUUID } from 'node:crypto';
 import { emptyResultNote, renderPersonaPrompt, RESULT_MAX, textOfBlocks, } from './persona-parse.js';
+import { childPresetDefinition } from './child-preset.js';
 // 拆出四层后 subagents/service.js 的公开面照旧（index.ts、ops/sessions.ts、scenes/candidates.ts、
 // subagents/tools.ts 与契约测试都按这个路径引）。
 export { catalogInjectedAt, catalogDepthOf, DEFAULT_PERSONA_CATALOG_DEPTH, emptyResultNote, neutralizePromptVariables, normalizeReasoningEffort, parsePersona, parsePresetToolRules, renderPersonaPrompt, REASONING_EFFORT_MAX_LENGTH, textOfBlocks, UNLIMITED_PERSONA_CATALOG_DEPTH, } from './persona-parse.js';
@@ -16,8 +18,8 @@ export { presetRulesOf, serializePersona, validPersonaName } from './persona-wri
 export { decideToolFilter } from './tool-filter.js';
 export function createRunProvider(deps) {
     const PROVIDER_PACKAGES = {
-        spawn: { pkg: '@deepseek-ai/dsh-subagent-spawn-in-process', label: 'spawn（新会话）' },
-        fork: { pkg: '@deepseek-ai/dsh-subagent-fork-in-process', label: 'fork（继承本次会话）' },
+        spawn: { pkg: '@deepseek-ai/dsh-subagent-spawn-in-process', label: 'spawn (fresh session)' },
+        fork: { pkg: '@deepseek-ai/dsh-subagent-fork-in-process', label: 'fork (inherits this session)' },
     };
     const providerMounts = {};
     function hasProvider(runtime, kind) {
@@ -33,8 +35,8 @@ export function createRunProvider(deps) {
     }
     async function ensureProvider(kind) {
         const runtime = deps.ctx.get?.('subagents');
-        if (!runtime || typeof runtime.start !== 'function') {
-            throw new Error('子代理服务未挂载（ctx.subagents 缺失；请确认 DSH 版本 ≥0.1.5-rc.2）');
+        if (!runtime || typeof runtime.startActivation !== 'function') {
+            throw new Error('the subagent service is not mounted or lacks startActivation (ctx.subagents is missing; check that DSH is >= 0.2.1-rc.2)');
         }
         if (hasProvider(runtime, kind))
             return runtime;
@@ -46,31 +48,132 @@ export function createRunProvider(deps) {
             try {
                 const mod = deps.req(pkg);
                 if (!mod || typeof mod.apply !== 'function')
-                    throw new Error('模块未导出 apply(ctx, config)（版本不匹配？）');
+                    throw new Error('the module does not export apply(ctx, config) (version mismatch?)');
                 mod.apply(deps.ctx, { providerName: kind });
                 providerMounts[kind] = { ok: true };
             }
             catch (e) {
                 providerMounts[kind] = {
                     ok: false,
-                    error: `${label} provider 不可用：宿主没有注册它，本插件挂载 ${pkg} 也失败（`
-                        + deps.message(e) + '）。请在宿主 profile 挂载该包（本插件已声明为可选 peerDependency），或安装后重启 DSH。',
+                    error: `the ${label} provider is unavailable: the host did not register it and mounting ${pkg} from this plugin failed too (`
+                        + deps.message(e) + '). Mount that package in the host profile (this plugin declares it as an optional peerDependency), or install it and restart DSH.',
                 };
             }
         }
         const mount = providerMounts[kind];
         if (!mount || !mount.ok)
-            throw new Error(mount ? mount.error : 'provider 挂载失败（未知原因）');
+            throw new Error(mount ? mount.error : 'provider mount failed (unknown reason)');
         if (!hasProvider(runtime, kind))
-            throw new Error(`${kind} provider 挂载后仍未出现在 ctx.subagents.list()（宿主版本不匹配？）`);
+            throw new Error(`the ${kind} provider still does not appear in ctx.subagents.list() after mounting (host version mismatch?)`);
         return runtime;
     }
+    /**
+     * Install the persona's optional tool mask on one exact child scope. The
+     * official request no longer accepts toolFilter, so this is the only place
+     * the mask can be applied without widening the child's inherited tools.
+     *
+     * Must run inside `agent/created` for that exact child (0.2.1)：the official
+     * factory awaits every serial `agent/created` listener **before** it releases
+     * the queued first prompt (`dsh-agent/lib/types/index.js:334` → `announce`),
+     * so a restriction installed here is already in force at the child's first
+     * tool call. Installing after `startActivation()` resolves would race: the
+     * first turn could already have run with the inherited tools.
+     */
+    function restrictChildTools(childAgent, filter) {
+        const tools = childAgent?.ctx?.get?.('tools');
+        if (!tools || typeof tools.restrict !== 'function') {
+            throw new Error('the subagent tool scope lacks tools.restrict(); cannot apply a tool restriction');
+        }
+        const dispose = tools.restrict(filter);
+        return typeof dispose === 'function' ? dispose : () => undefined;
+    }
+    /**
+     * 临时子预设的引用计数表：同一份定义（父预设 + 人设）只注册一次。
+     *
+     * 三件事逼着它存在（0.2.1）：
+     *   ① 复用 —— 同一个 (父预设, 人设) 反复委派时重复 `register()` 会因官方
+     *      `Duplicate agent preset` 直接失败；
+     *   ② 失败路径释放 —— 启动失败还留着定义，会在宿主 registry 里堆一份永久的插件树，
+     *      还会出现在 `agentPresets.list()` 的名单里；
+     *   ③ 追问子代理**不能**在启动后立刻注销 —— 冷恢复按 `agent-preset/selected` 投影找预设
+     *      （`dsh-subagent/lib/index.js` → `NOT_RESUMABLE`），提前注销会让后续追问失败。
+     * 引用归零才真正注销；插件卸载时统一释放（见 installChildPresetCleanup）。
+     */
+    const presetLeases = new Map();
+    /** 已注册的临时预设 → 官方返回的注销函数。 */
+    const presetUnregisters = new Map();
+    /**
+     * 取（必要时注册）一份临时子预设的引用；返回的 release 由调用方在 finally 里调。
+     */
+    async function acquireChildPreset(definition) {
+        const id = definition.id;
+        const existing = presetLeases.get(id);
+        if (existing !== undefined) {
+            existing.refs += 1;
+            return async () => {
+                const lease = presetLeases.get(id);
+                if (lease === undefined || lease !== existing)
+                    return;
+                lease.refs -= 1;
+                if (lease.refs > 0)
+                    return;
+                presetLeases.delete(id);
+                const unregister = presetUnregisters.get(id);
+                if (unregister === undefined)
+                    return;
+                presetUnregisters.delete(id);
+                await unregister().catch(() => undefined);
+            };
+        }
+        const roster = deps.ctx.get?.('agentPresets');
+        if (!roster || typeof roster.register !== 'function') {
+            throw new Error('the agentPresets service is unavailable: cannot register the subagent persona preset');
+        }
+        let unregister;
+        try {
+            unregister = await roster.register(definition);
+        }
+        catch (error) {
+            throw new Error(`failed to register the subagent persona preset: ${deps.message(error)}`);
+        }
+        presetLeases.set(id, { refs: 1 });
+        presetUnregisters.set(id, unregister);
+        return async () => {
+            const lease = presetLeases.get(id);
+            if (lease === undefined)
+                return;
+            lease.refs -= 1;
+            if (lease.refs > 0)
+                return;
+            presetLeases.delete(id);
+            presetUnregisters.delete(id);
+            // 释放失败只影响清理，绝不让它盖住主路径的错误（调用方一律 catch 掉）。
+            await unregister().catch(() => undefined);
+        };
+    }
+    /** 插件卸载（HMR / 停用 / 更新）时释放全部临时预设。 */
+    function installChildPresetCleanup() {
+        if (typeof deps.ctx?.effect !== 'function')
+            return;
+        try {
+            deps.ctx.effect(() => () => {
+                presetLeases.clear();
+                const unregisters = [...presetUnregisters.values()];
+                presetUnregisters.clear();
+                // 串行释放：官方 unregister 会 retire 一代并等它被收集，并发会互相踩代数。
+                let chain = Promise.resolve();
+                for (const unregister of unregisters) {
+                    chain = chain.then(() => Promise.resolve(unregister()).catch(() => undefined));
+                }
+                void chain;
+            }, 'dsh-plugin-tool-management: child preset cleanup');
+        }
+        catch { /* effect 不可用 → 只影响清理，不影响本次委派 */ }
+    }
+    installChildPresetCleanup();
     async function runOnce(parentAgent, p, task, signal, toolFilter, inherit) {
-        // 这里**刻意没有**"预算用尽就拒绝"的前置检查（2026-09-17 用户实测后拆掉）。
-        // 它此前基于一个错误假设：以为传 `maxDepth: 1` 会让子会话再委派必然失败。实际上官方
-        // `dsh-tool-subagent` 的默认是 **3**、provider 只在**传了值**时才校验（`resolveChildDepth`），
-        // 所以子代理本来就能继续嵌套。那个检查唯一的净效果是让**我们的**工具比官方严 ——
-        // 同一个子会话里官方工具能委派、我们的被自己拦下 —— 而用户真想禁止嵌套也禁止不了。
+        // 这里**刻意没有**"预算用尽就拒绝"的前置检查：宿主统一决定委派深度
+        // （当前默认 maxDepth=1），本工具不传 maxDepth，也不自行判断能否继续委派。
         //
         // 通道选择（方案 C，2026-09-17）：`inherit` → 官方 fork provider（子会话被**本次会话已完成的
         // 对话**播种，`task` 只需写新增部分）；默认 → spawn（全新会话，任务必须自包含）。
@@ -78,8 +181,7 @@ export function createRunProvider(deps) {
         // （session-ee722e23）上下文里明明有「先在这里选人设…用 subagent_manager_run 执行」与
         // `code-review` 人设，模型在**读进 README 之后**仍选了 `subagent_fork`：那能把已读内容带过去、
         // 不必复述。人设通道缺这一档时，"贴合人设的任务"会持续被官方工具抢走 —— 补齐能力比改文案
-        // 更根本（模型选的是省力，不是没看见）。fork provider 的能力位（persona / toolFilter /
-        // agentOptions）与 spawn 相同，所以请求体不用分叉。
+        // 更根本（模型选的是省力，不是没看见）。
         const kind = inherit === true ? 'fork' : 'spawn';
         const runtime = await ensureProvider(kind);
         // 工具限制三态：对象 = 调用方已按当前预设决定；null = 调用方明确决定不加限制；
@@ -109,58 +211,107 @@ export function createRunProvider(deps) {
                 },
             }
             : {};
-        // ── 允许追问通道（人设 `continuable: true`，0.19.0）────────────────────────────
-        // 与一次性走的是**两条官方通道**：`startContinuable` 建持久子会话，在**收件箱受理时**
-        // 即兑现（不是跑完），返回稳定 `childId`，子代理在后台继续跑。追问不需要本插件再出工具
-        // —— 宿主自带全局 `send_message` / `interrupt_agent`（`dsh-tool-subagent-control`），
-        // 它们对任何可继续子级都生效，与创建它的工具无关。这里只负责"把它建起来"。
+        // 0.2.1 起 persona/toolFilter 不再属于 SubagentStartRequest。fork 明确不支持独立
+        // Agent Preset，因此带工具限制的 fork 必须在启动前报错，不能静默放宽权限。
+        if (kind === 'fork' && resolved !== null) {
+            throw new Error('fork does not support its own tool restriction: remove the tools/toolsDeny/toolsByPreset restriction this persona carries in this preset, '
+                + 'then use inherit=true; if the tool restriction is required, switch back to the default spawn (inherit=false).');
+        }
+        let releasePreset;
+        let agentPreset;
+        if (kind === 'spawn') {
+            const definition = await childPresetDefinition(parentAgent, p);
+            releasePreset = await acquireChildPreset(definition);
+            agentPreset = definition.id;
+        }
+        const childFilter = kind === 'spawn' ? resolved : null;
+        // 带工具限制的 spawn：`childId` 由我们预留，并在父 scope 的 `agent/created` 上按
+        // **精确 id** 施加限制。
         //
-        // 两条官方语义（`dsh-subagent/lib/index.js:599-654`）决定了回执只能写成"已启动 + id"：
-        //   · 子代理启动时被追加一句返回指引，要求它**自己**用 send_message 把结果发给父代理
-        //     —— 父代理不会自动收到它的转录、工具输出或思考；
-        //   · 结算时父代理还会收到一条 `subagent-settled` 通知（含收尾正文）。
-        // 所以这条通道的产出是**异步**到达的，不是本函数的返回值。
-        if (p.continuable === true) {
-            const started = await runtime.startContinuable({
+        // 为什么必须这么做（0.2.1 的启动顺序）：官方本地激活的首条 prompt 在 `startLocal()`
+        // 里就入 inbox（`dsh-subagent/lib/index.js` 的 `submitMaterialized`），而 announce 是
+        // **串行 `agent/created` 监听全部完成后才放行收件箱**（`dsh-agent/lib/types/index.js`
+        // 的 `announce` → `await this.ctx.serial(entry.carrier, 'agent/created', …)`）。
+        // 所以在这里施加 = 首轮工具调用之前已生效；等 `startActivation()` 返回再
+        // `restrict()` 就慢了一步 —— 首轮看到的还是继承来的工具集，人设的工具限制形同虚设。
+        //
+        // 监听器里取不到 child 或没有 `restrict()` 时**明确抛错**：监听器抛出会让官方把这次
+        // 创建判失败并回滚（fail-closed），绝不静默放宽。
+        // `childFilter` 只在 !== null 时进入下面的分支，但 TS 的收窄在这里失效（闭包捕获 +
+        // 外层 `const childId` 的推导），所以显式把非空那份收窄出来。
+        const childFilterValue = childFilter;
+        const childId = childFilterValue === null ? undefined : 'tool-management-child-' + randomUUID();
+        let stopWatching;
+        let restrictionFailure;
+        if (childId !== undefined) {
+            const parentCtx = parentAgent?.ctx;
+            if (typeof parentCtx?.on !== 'function') {
+                await releasePreset?.().catch(() => undefined);
+                throw new Error('the parent agent scope is unavailable: cannot apply the tool restriction before the subagent is created');
+            }
+            const onCreated = (payload) => {
+                const agent = payload && payload.agent;
+                if (!agent || String(agent.id) !== String(childId))
+                    return;
+                try {
+                    restrictChildTools(agent, childFilterValue);
+                }
+                catch (error) {
+                    restrictionFailure = error instanceof Error ? error : new Error(String(error));
+                    throw restrictionFailure;
+                }
+            };
+            // `ctx.on` 没返回 disposer（老宿主 / 异常）→ 用恒空函数兜底：监听会随父 scope
+            // 生命周期结束，调用侧只需保证自己调 `stopWatching()` 时不再抛。
+            const stop = parentCtx.on('agent/created', onCreated);
+            stopWatching = typeof stop === 'function' ? stop : () => undefined;
+        }
+        const startSignal = signal ?? new AbortController().signal;
+        let activation;
+        try {
+            activation = await runtime.startActivation({
                 provider: kind,
                 label: p.name,
-                // `ContinuableStartSpec.request` 是 `Omit<SubagentStartRequest,'label'|'signal'|'outputSchema'>`：
-                // label 提到 spec 顶层、signal 由 spec 自己带（官方接管准备期的取消），两者都不进 request。
+                ...(childId === undefined ? {} : { childId }),
                 request: {
                     parent: parentAgent,
-                    prompt: [{ type: 'text', text: task }],
-                    persona: renderPersonaPrompt(p),
-                    ...(resolved === null ? {} : { toolFilter: resolved }),
+                    prompt: [{ type: 'text', text: kind === 'fork' ? renderPersonaPrompt(p) + '\n\n' + task : task }],
+                    ...(agentPreset === undefined ? {} : { agentPreset }),
                     ...routeOptions,
                 },
-                signal: signal ?? new AbortController().signal,
+                signal: startSignal,
+                delivery: p.continuable === true ? 'parent' : 'caller',
             });
-            return { text: '', runId: String(started?.childId ?? ''), stopReason: 'started', continuable: true };
-        }
-        // 官方签名：start(name, request) —— name = ctx.subagents 上的 provider 注册名。
-        const run = await runtime.start(kind, {
-            label: p.name,
-            parent: parentAgent,
-            // 官方 SubagentStartRequest.signal 为必填：调用方缺省时给一个永不中止的信号，不传 undefined。
-            signal: signal ?? new AbortController().signal,
-            prompt: [{ type: 'text', text: task }],
-            // 人设不是裸正文：宿主的 persona 槽位（section order 0）原本是部署级短前缀，
-            // 框架该由填槽方承担。见 renderPersonaPrompt 的说明 —— 裸拼的后果是模型把它
-            // 读成身份句的续写，而不是一个被指定的角色。
-            persona: renderPersonaPrompt(p),
-            // 工具白/黑名单 → 官方 ToolRestriction（`deny` 优先级高于 `allow`；未知名官方会直接拒绝启动，
-            // 所以名单由 index.ts 按当前预设 + 当前真实存在的工具名算好再传进来，见 decideToolFilter）。
-            ...(resolved === null ? {} : { toolFilter: resolved }),
-            // **刻意不传 `maxDepth`**（2026-09-17 用户裁定，方案 A）：它是官方的**真·递归上限**
-            // （`resolveChildDepth` 会抛 `SubagentDepthError`），而我们的 `catalogDepth` 只想决定
-            // "目录出现在哪"。传了它会让我们的工具比官方严（1 vs 3），且会要求 provider 具备
-            // `depthLimit` capability（不传就没这个依赖）。让 provider 用它自己的默认，与官方
-            // 工具的能力保持一致。
-            // provider / model / reasoningEffort 的合并语义见上方 `routeOptions` 的注释。
-            ...routeOptions,
-        });
+        }
+        catch (error) {
+            try {
+                stopWatching?.();
+            }
+            catch { /* ignore */ }
+            await releasePreset?.().catch(() => undefined);
+            // 失败可能就是我们自己的监听器抛的（fail-closed 那条）：那句话更接近根因，
+            // 别让官方的通用报错把它盖掉。
+            if (restrictionFailure === undefined)
+                throw error;
+            throw new Error(`failed to apply the subagent tool restriction: ${restrictionFailure.message}`, { cause: error });
+        }
+        // 创建窗口结束，监听器摘掉（它只服务这一个 child id）。
+        try {
+            stopWatching?.();
+        }
+        catch { /* ignore */ }
+        if (restrictionFailure !== undefined) {
+            // 监听器抛了但激活仍然建立（理论竞态）：撤掉这次激活，绝不让一个限制没生效的
+            // 子代理继续跑。
+            await activation.dispose().catch(() => undefined);
+            await releasePreset?.().catch(() => undefined);
+            throw new Error(`failed to apply the subagent tool restriction: ${restrictionFailure.message}`);
+        }
+        if (p.continuable === true) {
+            return { text: '', runId: String(activation.childId ?? ''), stopReason: 'started', continuable: true };
+        }
         try {
-            const result = await run.result; // 官方契约：child 级失败不 reject（stopReason 体现）
+            const result = await activation.result; // 官方契约：child 级失败不 reject（stopReason 体现）
             // 只取 `text` 块（见 textOfBlocks）。此前这里只判了 `typeof b.text === 'string'`，
             // 于是 `reasoning` 块被当成正文 —— 子代理返回的正文里混着它的思考（计数、自我校验），
             // 只有思考时整段返回思考。本机 298 条终局消息里 98.7% 命中。
@@ -170,18 +321,23 @@ export function createRunProvider(deps) {
             const stopReason = String(result.stopReason ?? 'completed');
             return {
                 text: ((text || emptyResultNote(result.output, stopReason)) + diagnostic).slice(0, RESULT_MAX),
-                runId: String(run.id ?? ''),
+                runId: String(activation.childId ?? ''),
                 stopReason,
             };
         }
         finally {
-            await run.dispose().catch(() => { }); // 官方前台语义：collection 后即弃
+            await activation.dispose().catch(() => { }); // 官方前台语义：collection 后即弃
+            // 一次性子代理走完即弃：这一轮没人再需要这份预设定义。释放失败只影响清理，
+            // 所以 catch 掉 —— 它绝不能盖住上面已经算出 / 抛出的结果。
+            await releasePreset?.().catch(() => undefined);
         }
     }
     // v1 串行：同一时刻至多一次**启动**在途（设计 §3.2）。
     // ⚠️ 0.19.0 起这条不再等于"至多一个子代理在跑"：允许追问（`continuable`）的子代理在
-    // `startContinuable` 返回后仍在后台运行，而这里只串行化"启动"这一步。这是官方通道的
+    // `startActivation()` 返回后仍在后台运行，而这里只串行化"启动"这一步。这是官方通道的
     // 固有语义（后台子级本来就允许并存），不是本插件放宽了限制。
+    // `continuable: true` 的返回值是 `{ text: '', stopReason: 'started' }` —— 产出不在这里，
+    // 而由官方的结算通知在子代理结束时送到父代理（见 persona-types.ts 的 continuable 注释）。
     let chain = Promise.resolve();
     const runSerial = (parentAgent, p, task, signal, toolFilter, inherit) => {
         const start = () => runOnce(parentAgent, p, task, signal, toolFilter, inherit);

package/lib/subagents/tool-filter.js

@@ -52,15 +52,15 @@ export function decideToolFilter(persona, presetId, known) {
         const dropped = rule.names.filter((name) => !known.names.has(name));
         const notes = [];
         if (dropped.length)
-            notes.push(`名单里这些工具当前不存在，已忽略：${dropped.join('、')}`);
+            notes.push(`these tools in the list do not exist right now and were ignored: ${dropped.join(', ')}`);
         if (reserved.dropped.length) {
-            notes.push(`名单里的 ${reserved.dropped.join('、')} 是官方保留名（写进工具限制会让子代理直接起不来），已忽略`);
+            notes.push(`${reserved.dropped.join(', ')} in the list are reserved official names (writing them into the tool restriction would stop the subagent from starting at all) and were ignored`);
         }
         if (!usable.length) {
-            const note = notes.length ? notes.join('；') : undefined;
-            return { filter: null, note: note ?? `「${presetId}」的${rule.mode === 'allow' ? '白' : '黑'}名单里没有当前存在的工具，本次不施加工具限制` };
+            const note = notes.length ? notes.join('; ') : undefined;
+            return { filter: null, note: note ?? `the ${rule.mode === 'allow' ? 'allow' : 'deny'} list of "${presetId}" contains no tool that exists right now, so no tool restriction is applied this time` };
         }
-        const droppedNote = notes.length ? notes.join('；') : undefined;
+        const droppedNote = notes.length ? notes.join('; ') : undefined;
         if (rule.mode === 'allow')
             return { filter: { allow: [...new Set([...usable, ...known.mcp])] }, ...(droppedNote === undefined ? {} : { note: droppedNote }) };
         return { filter: { deny: usable }, ...(droppedNote === undefined ? {} : { note: droppedNote }) };
@@ -81,18 +81,18 @@ export function decideToolFilter(persona, presetId, known) {
     if (presetId === null) {
         // 说清这一刻到底靠什么在跑：有旧格式就照旧格式，没有就明说"按模式配的限制这次不生效"。
         notes.push(hasLegacy
-            ? '没能判断当前会话的 Agent 预设，按旧格式的全局名单执行'
-            : '没能判断当前会话的 Agent 预设，按模式配的限制这次不生效');
+            ? 'could not determine the agent preset of this session; running the legacy global list instead'
+            : 'could not determine the agent preset of this session; the mode-scoped restriction does not apply this time');
     }
     if (legacyDropped.length)
-        notes.push(`名单里这些工具当前不存在，已忽略：${legacyDropped.join('、')}`);
+        notes.push(`these tools in the list do not exist right now and were ignored: ${legacyDropped.join(', ')}`);
     if (legacyReserved.dropped.length) {
-        notes.push(`名单里的 ${legacyReserved.dropped.join('、')} 是官方保留名（写进工具限制会让子代理直接起不来），已忽略`);
+        notes.push(`${legacyReserved.dropped.join(', ')} in the list are reserved official names (writing them into the tool restriction would stop the subagent from starting at all) and were ignored`);
     }
     if (!Object.keys(filter).length) {
         if (presetId === null && !notes.length)
-            notes.push('没能判断当前会话的 Agent 预设，本次不施加工具限制');
-        return { filter: null, ...(notes.length ? { note: notes.join('；') } : {}) };
+            notes.push('could not determine the agent preset of this session; no tool restriction is applied this time');
+        return { filter: null, ...(notes.length ? { note: notes.join('; ') } : {}) };
     }
-    return { filter, ...(notes.length ? { note: notes.join('；') } : {}) };
+    return { filter, ...(notes.length ? { note: notes.join('; ') } : {}) };
 }

package/lib/subagents/tools.js

@@ -29,14 +29,14 @@ export async function filterBySceneBinding(docs, enabledSceneLists, includeUnava
     if (includeUnavailable || !bound.size)
         return { allowed: live, reason: null };
     const allowed = live.filter((d) => bound.has(d.name));
-    return { allowed, reason: allowed.length ? null : `当前启用场景的子智能体绑定: ${[...bound].join('、')}` };
+    return { allowed, reason: allowed.length ? null : `the enabled scene's subagent bindings: ${[...bound].join(', ')}` };
 }
 export function defineSubagentManagerListTool(subagents) {
     return {
         name: 'subagent_manager_list',
         // `depth-filtered` 删掉（2026-10-15 注入文本审查）：注入深度是**注入侧**的实现细节，
         // 模型看到的是"目录里有哪些人设"，`catalogDepth` 那个词对它没有任何可操作性。
-        description: 'List personas (pre-configured subagent profiles) with their descriptions. The「当前子智能体」reminder carries a view of the same catalog; call this for the always-current full list, or pass all=true to include personas that are disabled or outside the active scene.',
+        description: 'List personas (pre-configured subagent profiles) with their descriptions. The "Current subagents" reminder carries a view of the same catalog; call this for the always-current full list, or pass all=true to include personas that are disabled or outside the active scene.',
         parameters: {
             all: { type: 'boolean', description: 'Include disabled personas and ones outside the active scene (default false). Listed ≠ delegable: `run` still refuses those.' },
         },
@@ -54,9 +54,9 @@ export function defineSubagentManagerListTool(subagents) {
             // 而工具又不列全，结果是"明明能委派却查不到人设"。
             // `all=true` 时**标出哪些不可用**：只列名字的话，模型照样分不清哪个能直接委派
             // （与技能列表标 `shadowed-by:` 同一条理由 —— 列出来不等于能用）。
-            const lines = allowed.map((p) => '- ' + p.name + ' — ' + (p.description || '(无描述)') +
+            const lines = allowed.map((p) => '- ' + p.name + ' — ' + (p.description || '(no description)') +
                 (p.continuable === true ? CONTINUABLE_MARK : '') +
-                (includeUnavailable ? (p.enabled === false ? '（已停用，需先启用）' : '') : ''));
+                (includeUnavailable ? (p.enabled === false ? ' (disabled — turn it on first)' : '') : ''));
             // 默认口径下有多少个没列出来（停用的 + 不在启用场景里的）：不报的话，模型看到一份短名单
             // 会当成"本机只有这些人设"。数量照报，与另外三个 list 的表头同一口径。
             const hiddenCount = includeUnavailable ? 0 : docs.length - allowed.length;
@@ -67,9 +67,9 @@ export function defineSubagentManagerListTool(subagents) {
             catch {
                 notice = '';
             }
-            const header = '人设子智能体（' + allowed.length + '）' +
-                (hiddenCount > 0 ? '（另有 ' + hiddenCount + ' 个停用或不在当前场景，传 all=true 查看）' : '') + '：\n';
-            return header + (lines.join('\n') || '(无)') + (reason ? '\n注意：' + reason : '') + notice;
+            const header = 'persona subagents (' + allowed.length + ')' +
+                (hiddenCount > 0 ? ' (' + hiddenCount + ' more are disabled or outside the current scene; pass all=true to see them)' : '') + ':\n';
+            return header + (lines.join('\n') || '(none)') + (reason ? '\nnote: ' + reason : '') + notice;
         },
     };
 }
@@ -105,9 +105,9 @@ export function defineSubagentManagerRunTool(subagents) {
         // 最贵的单个参数。收完两处重复后目标 ≈325 tok。判据是"删掉的那句在描述里已经有了吗"：
         // Modes 段留着（它是模型的入口），参数说明只留"这一段独有的信息"。
         // `inherit` 那句"轮中委派拿不到当前轮"必须留 —— 它是这条参数唯一会让人写错 task 的地方。
-        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. A persona marked「允许追问」instead returns an agent id and runs in the background — continue it with `send_message`.\n\nModes: by default a fresh child that cannot see this conversation, so `task` must be self-contained. With `inherit: true` it also gets this conversation\'s **finished** turns (like the host\'s `subagent_fork`) — the current turn is never included, so a mid-turn hand-off still needs a self-contained `task`.\n\n`task` = the goal plus the context it needs; leave method and output format to the persona.\n\nUse it when the work matches a persona in the「当前子智能体」reminder (a review, an investigation, a piece of writing) and the detail should not sit in your own context. Not for reading a file (Read), finding a definition (Grep/Glob), or touching two or three files.',
+        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. A persona marked `(continuable)` instead returns an agent id and runs in the background — continue it with `send_message`.\n\nModes: by default a fresh child that cannot see this conversation, so `task` must be self-contained. With `inherit: true` it also gets this conversation\'s **finished** turns (like the host\'s `subagent_fork`) — the current turn is never included, so a mid-turn hand-off still needs a self-contained `task`.\n\n`task` = the goal plus the context it needs; leave method and output format to the persona.\n\nUse it when the work matches a persona in the "Current subagents" reminder (a review, an investigation, a piece of writing) and the detail should not sit in your own context. Not for reading a file (Read), finding a definition (Grep/Glob), or touching two or three files.',
         parameters: {
-            agent: { type: 'string', required: true, description: 'Persona name — see the「当前子智能体」reminder, or list personas with subagent_manager_list.' },
+            agent: { type: 'string', required: true, description: 'Persona name — see the "Current subagents" reminder, or list personas with subagent_manager_list.' },
             // `task` 的说明只留"这是什么"（2026-10-15 注入文本审查）：上面描述里那句
             // "leave method and output format to the persona." 此前在这里**逐字重复**了一遍
             // （57 字符），而模型填这个参数时两处都在手上 —— 同一件事付两次 token。
@@ -123,22 +123,23 @@ export function defineSubagentManagerRunTool(subagents) {
             const task = String((args && args.task) || '').trim();
             const inherit = args && args.inherit === true;
             if (!task)
-                throw new Error('task 不能为空');
+                throw new Error('task must not be empty');
             // 官方 SubagentStartRequest.parent 必填：调用方 agent 缺失时给结构化错误，不把 undefined 透传下去。
             if (!exec || !exec.agent)
-                throw new Error('缺少调用方 agent（exec.agent 不可用）：无法创建子代理运行');
+                throw new Error('no caller agent (exec.agent is unavailable): cannot create a subagent run');
             const docs = await subagents.list();
             const { allowed, reason } = await filterBySceneBinding(docs, await subagents.sceneLists());
             const persona = allowed.find((p) => p.name === name);
             if (!persona) {
-                const available = allowed.map((p) => p.name).join('、') || '(无)';
-                throw new Error('人设不可用: ' + name + (reason ? '（' + reason + '）' : '（可用: ' + available + '）'));
+                const available = allowed.map((p) => p.name).join(', ') || '(none)';
+                throw new Error('persona unavailable: ' + name + (reason ? ' (' + reason + ')' : ' (available: ' + available + ')'));
             }
             // 这里**刻意没有**"深度不够就拒绝"的检查（2026-09-17 用户裁定，方案 A）。
             // 它此前基于一个错误假设：以为传 `maxDepth: 1` 会让子会话再委派必然失败。实际上官方
-            // `dsh-tool-subagent` 的默认是 **3**、provider 只在**传了值**时才校验，所以子代理本来
-            // 就能继续嵌套。那个检查的唯一净效果是让**我们的**工具比官方严 —— 同一个子会话里官方
-            // 工具能委派、我们的被自己拦下 —— 而用户真想禁止嵌套也禁止不了（官方工具照样能）。
+            // 的 `maxDepth` 只用**宿主配置**那一档（0.2.1 默认 1）、provider 只在**传了值**时才校验，
+            // 所以能不能继续委派问官方就行。那个检查的唯一净效果是让**我们的**工具比官方严 ——
+            // 同一个子会话里官方工具能委派、我们的被自己拦下 —— 而用户真想禁止嵌套也禁止不了
+            // （官方工具照样能）。
             // `catalogDepth` 现在只管"目录注入到哪些会话"，不参与委派可行性判断。
             // 按当前会话的 Agent 预设算工具限制：判断不了当前预设、或名单里的工具已经不存在时，
             // 结论里会带一句实话，跟着结果一起返回——不静默改变限制的强度。
@@ -149,14 +150,20 @@ export function defineSubagentManagerRunTool(subagents) {
             const prefix = r.stopReason && r.stopReason !== 'completed' ? `[stopReason: ${r.stopReason}]\n` : '';
             const note = decision && decision.note ? `⚠ ${decision.note}\n\n` : '';
             // 允许追问通道（人设 `continuable: true`）：产出是**异步**到达的，这里只拿到子会话 id。
-            // 回执必须把"id + 怎么追问 + 怎么中止"三件事写全 —— 少写一句，模型就会把"没拿到结果"
-            // 读成"委派失败"而重试一次（那会再起一个后台子代理，白白翻倍）。
+            // 回执必须把"id + 产出怎么回来 + 怎么追问 + 怎么中止"写全 —— 少写一句，模型就会把
+            // "没拿到结果"读成"委派失败"而重试一次（那会再起一个后台子代理，白白翻倍）。
+            // "产出怎么回来"说的是**宿主的结算通知**（0.2.1 核实 `dsh-subagent/lib/types/manager.js`
+            // 的 `notifySettlement` → `createSettlementMessage`）：子代理结束时父代理会收到一条
+            // `subagent-settled` 通知，含收尾一行说明 + 子代理最终的非空 text 块（+ 结构化结果与
+            // 诊断）。它自己发回来的 `send_message` 是**补充**（`withContinuableReturnGuidance`
+            // 要求它在收尾前把自包含结果发给父代理），不是产出的唯一来路 —— 回执不能只说前者，
+            // 否则子代理没主动发消息时父代理会把"还没收到结果"当成"还在跑"。
             if (r.continuable === true) {
-                return note + '已启动允许追问的子代理「' + name + '」（后台运行）\n'
+                return note + 'started the continuable subagent "' + name + '" (running in the background)\n'
                     + 'agent_id: ' + r.runId + '\n\n'
-                    + '它的产出稍后自己发到这里，届时你会收到一条通知。要追问就 '
-                    + 'send_message({ agent_id: "' + r.runId + '", message: "..." })，'
-                    + '要中止就 interrupt_agent({ agent_id: "' + r.runId + '" })。';
+                    + 'you will get a notification carrying its final output when it settles. To follow up: '
+                    + 'send_message({ agent_id: "' + r.runId + '", message: "..." }), '
+                    + 'To stop it: interrupt_agent({ agent_id: "' + r.runId + '" }).';
             }
             return note + prefix + r.text;
         },

package/lib/tools/deps.js

@@ -7,7 +7,7 @@ export function text(value) {
     return [{ type: 'text', text: value }];
 }
 /**
- * 名单渲染：超过 `TOOL_NAME_LIST_CAP` 项就截断，并把总数写在后面（"等 N 项"）。
+ * 名单渲染：超过 `TOOL_NAME_LIST_CAP` 项就截断，并把总数写在后面（"…(N total)"）。
  *
  * 为什么两个地方都要它：`scene_manager_list` 用它列档案，`scene_manager_save` 用它
  * 在回执里回显"这一次替换挤掉了什么"。两处都必须**点名、不能只给数量** —— 只给数量
@@ -17,9 +17,9 @@ export function text(value) {
 export const TOOL_NAME_LIST_CAP = 6;
 export function toolNameList(list) {
     if (!list.length)
-        return '空';
-    const head = list.slice(0, TOOL_NAME_LIST_CAP).join('、');
-    return list.length > TOOL_NAME_LIST_CAP ? head + ' 等 ' + list.length + ' 项' : head;
+        return 'none';
+    const head = list.slice(0, TOOL_NAME_LIST_CAP).join(', ');
+    return list.length > TOOL_NAME_LIST_CAP ? head + ' ...(' + list.length + ' total)' : head;
 }
 /**
  * 按名字找技能落在哪个来源（root）。