dsh-plugin-tool-management 0.20.2 → 0.21.0

package/lib/subagents/child-preset.js

@@ -0,0 +1,120 @@
+// Agent Preset helpers for persona-scoped child composition.
+//
+// DSH 0.2.1 removed persona/toolFilter from SubagentStartRequest. A spawn child
+// can still select an independent preset, so this module clones the parent's
+// declared preset, replaces its persona row, and registers a short-lived preset
+// id for that child. The clone is mounted by the official registry; nothing in
+// the official package is patched.
+import { createHash } from 'node:crypto';
+import { JSON_SCHEMA, Type, load } from 'js-yaml';
+import { renderPersonaPrompt } from './persona-parse.js';
+const CHILD_PRESET_PREFIX = 'tool-management-child-';
+const JS_EXPR_TAG = 'tag:yaml.org,2002:js';
+const jsExprType = new Type(JS_EXPR_TAG, {
+    kind: 'scalar',
+    resolve: (data) => typeof data === 'string',
+    construct: (data) => ({ __jsExpr: data }),
+    represent: (data) => data.__jsExpr,
+});
+const entryListSchema = JSON_SCHEMA.extend(jsExprType);
+/** `!!js` 标量（官方 `entryListSchema` 的 `JsExpr`）：克隆时只带 `__jsExpr` 一个键。 */
+function isJsExpr(value) {
+    return typeof value === 'object' && value !== null && '__jsExpr' in value;
+}
+function presetRosterOf(ctx) {
+    try {
+        return ctx?.get?.('agentPresets');
+    }
+    catch {
+        return undefined;
+    }
+}
+function cloneEntry(value) {
+    if (isJsExpr(value))
+        return { __jsExpr: value.__jsExpr };
+    if (!value || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(cloneEntry);
+    const copy = {};
+    for (const [key, item] of Object.entries(value))
+        copy[key] = cloneEntry(item);
+    return copy;
+}
+function isPersonaOrPresetSwitch(row) {
+    if (row.name === '@deepseek-ai/dsh-persona')
+        return true;
+    // A custom preset row would replace the whole composition; cloning it would
+    // silently change the parent instead of merely overriding its persona.
+    return row.name === '@deepseek-ai/dsh-agent-preset';
+}
+function removePersonaRows(rows) {
+    const kept = [];
+    for (const value of rows) {
+        // 不是对象的行：官方 entry list 不接受它，说明这份组合已不是本插件读懂的形状。
+        // 静默原样保留会把"人设"语义悄悄换掉（克隆出来的预设带着看不懂的行），所以明确报错。
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new Error('the parent agent preset composition contains a non-object plugin row; cannot clone it safely');
+        }
+        const row = value;
+        if (isPersonaOrPresetSwitch(row))
+            continue;
+        if (row.group === true) {
+            const config = Array.isArray(row.config) ? removePersonaRows(row.config) : row.config;
+            kept.push(cloneEntry({ ...row, config }));
+        }
+        else {
+            kept.push(cloneEntry(row));
+        }
+    }
+    return kept;
+}
+/** Read the parent preset's declared rows and return a child definition. */
+export async function childPresetDefinition(parentAgent, persona) {
+    const parentCtx = parentAgent?.ctx;
+    const roster = presetRosterOf(parentCtx);
+    if (!roster || typeof roster.composedPreset !== 'function' || typeof roster.readDocument !== 'function' || typeof roster.register !== 'function') {
+        throw new Error('this host lacks the agent-preset read/register API, so no standalone persona can be created for the subagent; upgrade to DSH >= 0.2.1 and enable the agentPresets service');
+    }
+    const parentPresetId = String(roster.composedPreset(parentCtx) ?? '');
+    if (!parentPresetId)
+        throw new Error('this parent session has no agent preset bound; cannot safely create a subagent with a persona');
+    const document = await roster.readDocument(parentPresetId);
+    if (!document || typeof document.content !== 'string') {
+        throw new Error(`failed to read the parent agent preset "${parentPresetId}": readDocument returned no composition YAML`);
+    }
+    let parsed;
+    try {
+        parsed = load(document.content, { schema: entryListSchema });
+    }
+    catch (error) {
+        throw new Error(`failed to parse the parent agent preset "${parentPresetId}": ${String(error?.message ?? error)}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`the composition of the parent agent preset "${parentPresetId}" is not a list of plugin rows; cannot clone it`);
+    }
+    const plugins = removePersonaRows(parsed);
+    plugins.unshift({
+        id: 'tool-management-child-persona',
+        name: '@deepseek-ai/dsh-persona',
+        config: { prefix: renderPersonaPrompt(persona) },
+    });
+    // hash 必须覆盖**父预设的组合正文**：同一个 id 的内容可以被 profile 补丁改写，只按
+    // id + 人设定哈希会让改过的内容继续复用旧定义（冷恢复/追问时加载的是上一版插件树）。
+    const hash = createHash('sha256')
+        .update(parentPresetId)
+        .update('\0')
+        .update(document.content)
+        .update('\0')
+        .update(persona.name)
+        .update('\0')
+        .update(renderPersonaPrompt(persona))
+        .digest('hex')
+        .slice(0, 16);
+    return {
+        id: CHILD_PRESET_PREFIX + hash,
+        name: `persona:${persona.name}`,
+        description: `Ephemeral child preset cloned from ${parentPresetId}`,
+        plugins: plugins,
+    };
+}

package/lib/subagents/persona-parse.js

@@ -238,12 +238,12 @@ export const DEFAULT_PERSONA_CATALOG_DEPTH = 1;
  * 放在本模块（叶子）而不是 `catalog.ts`：`tools.ts` 也要用它，而 `catalog.ts` 反向依赖
  * `tools.ts` 的 `filterBySceneBinding` —— 放那边会形成 tools ↔ catalog 的循环。
  */
-export const CONTINUABLE_MARK = '（允许追问）';
+export const CONTINUABLE_MARK = ' (continuable)';
 /**
  * 「不限制嵌套」的目录注入深度（界面下拉的第四档，前端同值见 client.js 的
  * `CATALOG_DEPTH_UNLIMITED`）。
  *
- * 取值远大于宿主能嵌套到的深度（官方 `dsh-tool-subagent` 默认 `maxDepth: 3`），所以判据
+ * 取值远大于宿主能嵌套到的深度（0.2.1 的 `dsh-subagent` 默认 `maxDepth: 1`），所以判据
  * `深度 < catalogDepth` 在任何可达的会话里都成立 —— 判据本身不必为它加特例分支。
  */
 export const UNLIMITED_PERSONA_CATALOG_DEPTH = 99;
@@ -330,18 +330,18 @@ export function textOfBlocks(blocks, type) {
 export function emptyResultNote(output, stopReason) {
     // 连思考都没有 → 子代理确实什么都没产出，这时说「没干活」是对的。
     if (textOfBlocks(output, 'reasoning') === '')
-        return '(子代理无输出)';
-    const head = '子代理没有返回正文 —— 它产出了思考';
+        return '(the subagent produced no output)';
+    const head = 'the subagent returned no text — only reasoning';
     switch (stopReason) {
         case 'max-tokens':
-            return `(${head}，但写出结论前就用完了 token 上限；需要结果请把任务拆小些再委派。)`;
+            return `(${head}, but it hit the token limit before writing a conclusion; split the task smaller and delegate again if you need a result.)`;
         case 'error':
-            return `(${head}，但中途出错了；诊断信息见后。)`;
+            return `(${head}, but it errored; diagnostics follow.)`;
         case 'aborted':
-            return `(${head}，但写出结论前被中止了。)`;
+            return `(${head}, but it was aborted before writing a conclusion.)`;
         case 'refusal':
-            return `(${head}，但它拒绝了这项任务。)`;
+            return `(${head}, but it refused this task.)`;
         default:
-            return `(${head}，但没有写出结论；可以拆小任务重新委派，或你自己接着做。)`;
+            return `(${head}, and wrote no conclusion; split the task and delegate again, or carry on yourself.)`;
     }
 }

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('; ') } : {}) };
 }