@ai-agent-forge/plugin-subagent-delegate 0.87.0 → 0.88.1

package/dist/delegate.js

@@ -177,6 +177,157 @@ function validateRoleDefinition(id, value, origin) {
         ...(parentView === true ? { parentView: true } : {}),
     };
 }
+/** 角色菜单字符数（工具描述里每个角色占 `id — description`；装载期与注册期共用同一公式）。 */
+function roleMenuChars(roles) {
+    let total = 0;
+    for (const role of roles)
+        total += role.id.length + role.description.length + 3;
+    return total;
+}
+/** 未知角色 id 的拒绝文本（resolveRole 与角色工具共用，措辞保持稳定）。 */
+function unknownRoleMessage(id, roles) {
+    const available = [...roles.keys()].sort();
+    return (`unknown subagent role ${JSON.stringify(id)}; available roles: ` +
+        (available.length === 0 ? "(none configured)" : available.join(", ")));
+}
+/**
+ * 角色是否带**收窄档案**（profile 里除基线 version/roleId 外还有 model/thinkingLevel/
+ * tools/mode/systemPromptAppend）。`role.profile !== undefined` 不是这个意思：档案基线
+ * 恒含 roleId，因此任何角色都带 profile；"带收窄"看的是有没有收窄字段。
+ */
+function hasNarrowingProfile(role) {
+    const profile = role.profile;
+    return (profile !== undefined &&
+        (profile.model !== undefined ||
+            profile.thinkingLevel !== undefined ||
+            profile.tools !== undefined ||
+            profile.mode !== undefined ||
+            profile.systemPromptAppend !== undefined));
+}
+// ---------------------------------------------------------------------------
+// 会话级子代理角色（session-scoped roles，D-081，2026-10-03 用户裁决落地）
+//
+// 主代理可用角色 = 磁盘角色（方案 associations ∩ 目录文件）∪ 会话角色。会话角色由
+// 主代理在会话内用 `subagent_role_set` 注册，随会话文件持久化（下次打开仍在），
+// 不写 `<agentDir>/roles/`、不跨会话共享、子代理不继承。磁盘角色优先：撞名的注册
+// 被结构化拒绝，装载期合并时撞名的会话角色被忽略并 warn。
+// ---------------------------------------------------------------------------
+/**
+ * 会话角色快照条目的 customType（跨插件契约，workflow 软校验按此字面量读取）：
+ * data = `{ version: 1, roles: [...] }` **全量快照**、append-only；恢复时反向扫描
+ * 最近一条可解析快照（与 goal/plan/todo/workflow 的 loadState 同构）。压缩只影响
+ * LLM 上下文投影，`getBranchEntries` 始终返回完整分支，按分支重建因此压缩安全。
+ */
+export const SESSION_ROLE_STATE_ENTRY = "subagent.roles.state";
+/** 运行期角色 → 会话快照条目（平铺收窄字段，读-改-写与角色文件同构）。 */
+export function toSessionRoleRecord(role) {
+    const profile = role.profile;
+    return {
+        id: role.id,
+        description: role.description,
+        instructions: role.instructions,
+        ...(profile?.model === undefined ? {} : { model: profile.model }),
+        ...(profile?.thinkingLevel === undefined ? {} : { thinkingLevel: profile.thinkingLevel }),
+        ...(profile?.tools === undefined ? {} : { tools: profile.tools }),
+        ...(profile?.mode === undefined ? {} : { mode: profile.mode }),
+        ...(profile?.systemPromptAppend === undefined ? {} : { systemPromptAppend: profile.systemPromptAppend }),
+        ...(role.parentView === true ? { parentView: true } : {}),
+    };
+}
+/**
+ * 恢复水合（D-081）：从 `getBranchEntries()` 反向扫描最近一条**可解析**的会话角色
+ * 快照。快照级损坏（非对象/版本不符/roles 非数组）→ warn 后继续向前找；快照合法但
+ * 个别角色非法（id 形状、字段/档案校验不过）→ 丢弃该角色并 warn、保留其余；全部
+ * 不可解析 → 空数组。损坏不阻断会话启动。
+ */
+export function readSessionRoles(session, logger) {
+    const entries = session?.getBranchEntries() ?? [];
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.customType !== SESSION_ROLE_STATE_ENTRY)
+            continue;
+        const snapshot = entry.data;
+        if (!isPlainRecord(snapshot) || snapshot.version !== 1 || !Array.isArray(snapshot.roles)) {
+            logger?.warn?.(`session role state entry ${entry.id} is not a readable snapshot (want { version: 1, roles: [...] }); ` +
+                "reading the previous snapshot");
+            continue;
+        }
+        const roles = [];
+        for (const [roleIndex, raw] of snapshot.roles.entries()) {
+            const origin = `${SESSION_ROLE_STATE_ENTRY}[${roleIndex}]`;
+            if (!isPlainRecord(raw) || typeof raw.id !== "string" || !ROLE_ID_PATTERN.test(raw.id)) {
+                logger?.warn?.(`${origin} has no valid role id; entry dropped`);
+                continue;
+            }
+            // id 来自条目本身；其余键原样交给与角色文件同一套校验（未知键照样拒绝）。
+            const definition = {};
+            for (const [key, value] of Object.entries(raw)) {
+                if (key !== "id")
+                    definition[key] = value;
+            }
+            try {
+                const role = validateRoleDefinition(raw.id, definition, origin);
+                if (role !== undefined)
+                    roles.push(role);
+            }
+            catch (error) {
+                logger?.warn?.(`${origin} (role ${JSON.stringify(raw.id)}) is invalid and was dropped: ${errorText(error)}`);
+            }
+        }
+        return Object.freeze(roles);
+    }
+    return Object.freeze([]);
+}
+/**
+ * 合并磁盘角色与会话角色（D-081）：**磁盘优先**——撞名的会话角色不暴露并 warn（磁盘
+ * 角色是用户资产），但其数据仍留在会话文件里；水合按快照顺序把会话角色收进暴露预算
+ * （≤16 个、菜单 ≤2000 字符，磁盘+会话合并计算），超出部分不暴露并 warn——历史快照
+ * 可能因上限收紧或磁盘角色增加而超限，但不阻断会话启动，也不删除数据。
+ */
+export function mergeSubagentRoles(diskRoles, sessionRoles, logger) {
+    // 数据层：快照里的合法会话角色全量保留（同 id 后者覆盖前者，与快照顺序一致）。
+    const data = new Map();
+    // 视图层：磁盘角色优先，会话角色按快照顺序通过暴露预算。
+    const roles = new Map(diskRoles);
+    const shadowedByDisk = [];
+    const droppedForQuota = [];
+    for (const role of sessionRoles) {
+        data.set(role.id, role);
+        if (diskRoles.has(role.id)) {
+            shadowedByDisk.push(role.id);
+            logger?.warn?.(`session role "${role.id}" is shadowed by a visible disk role: kept in the session file but not exposed ` +
+                "(the disk role wins)");
+            continue;
+        }
+        const prospectiveChars = roleMenuChars([...roles.values(), role]);
+        if (roles.size + 1 > ROLE_COUNT_LIMIT || prospectiveChars > ROLE_MENU_CHARS) {
+            droppedForQuota.push(role.id);
+            logger?.warn?.(`session role "${role.id}" exceeds the ${ROLE_COUNT_LIMIT}-role / ${ROLE_MENU_CHARS}-char exposure budget: ` +
+                "kept in the session file but not exposed");
+            continue;
+        }
+        roles.set(role.id, role);
+    }
+    return {
+        sessionRoles: data,
+        roles,
+        shadowedByDisk: Object.freeze(shadowedByDisk),
+        droppedForQuota: Object.freeze(droppedForQuota),
+    };
+}
+/** 注册点的预算错误文本（undefined = 在预算内）：与装载期上限同一常量，附精简建议。 */
+function roleQuotaViolation(roles) {
+    if (roles.size > ROLE_COUNT_LIMIT) {
+        return (`registering this session role would expose ${roles.size} roles; at most ${ROLE_COUNT_LIMIT} are allowed ` +
+            "(the menu rides in the parent's tool description on every request) — remove unused session roles first");
+    }
+    const chars = roleMenuChars(roles.values());
+    if (chars > ROLE_MENU_CHARS) {
+        return (`registering this session role would grow the role menu to ${chars} chars; at most ${ROLE_MENU_CHARS} are ` +
+            "allowed — shorten descriptions or remove session roles first");
+    }
+    return undefined;
+}
 /**
  * 解析当前方案的角色目录（**全部来自磁盘**，无编译内定义）。装载期一次性完成，
  * 任何会让"配置了但没生效"的情况都显式失败：
@@ -243,7 +394,7 @@ export function resolveSubagentRoleCatalog(options) {
         throw new Error(`suite associations.roles exposes ${roles.size} roles; at most ${ROLE_COUNT_LIMIT} are allowed — the role menu ` +
             "rides in the parent's tool description on every request, and an unbounded menu degrades the main agent's own context");
     }
-    const menuChars = [...roles.values()].reduce((total, role) => total + role.id.length + role.description.length + 3, 0);
+    const menuChars = roleMenuChars(roles.values());
     if (menuChars > ROLE_MENU_CHARS) {
         throw new Error(`suite associations.roles menu is ${menuChars} chars; at most ${ROLE_MENU_CHARS} are allowed — shorten role ` +
             "descriptions or associate fewer roles (the menu is part of the parent's tool description)");
@@ -475,9 +626,7 @@ function resolveRole(value, roles) {
     }
     const role = roles.get(value);
     if (role === undefined) {
-        const available = [...roles.keys()].sort();
-        throw new SubagentDelegateError("subagent_unknown_role", `unknown subagent role ${JSON.stringify(value)}; available roles: ` +
-            (available.length === 0 ? "(none configured)" : available.join(", ")));
+        throw new SubagentDelegateError("subagent_unknown_role", unknownRoleMessage(value, roles));
     }
     return role;
 }
@@ -526,10 +675,10 @@ function resolveInt(explicit, configured, fallback, min, label) {
  * 因此"第二参非 undefined 即输入"的判定会把 context 误当输入（prompts 读成 undefined）。
  * 改按形状判定：第一参是普通对象即取第一参，否则看第二参。
  */
-function objectInput(first, second) {
+function objectInput(first, second, tool = "subagent_run") {
     const primary = isPlainRecord(first) ? first : second;
     if (!isPlainRecord(primary)) {
-        throw new SubagentDelegateError("subagent_invalid_input", "subagent_run input must be an object");
+        throw new SubagentDelegateError("subagent_invalid_input", `${tool} input must be an object`);
     }
     return primary;
 }
@@ -870,17 +1019,37 @@ export function createCapability(api, options) {
     const roleCatalog = options?.roles === undefined
         ? { roles: new Map(), dangling: [], brokenUnassociated: [] }
         : resolveSubagentRoleCatalog(options.roles);
-    const roles = roleCatalog.roles;
+    const diskRoles = roleCatalog.roles;
     for (const id of roleCatalog.dangling) {
         api.logger?.warn?.(`suite associations.roles lists "${id}" but no role file exists: ${subagentRoleCatalogPath(options?.roles?.agentDir ?? "", id)} (role stays unavailable for this session)`);
     }
     for (const id of roleCatalog.brokenUnassociated) {
         api.logger?.warn?.(`role file for "${id}" is invalid and is not associated by this suite; ignored (fix it or remove the file)`);
     }
-    const roleSummary = [...roles.values()]
+    // 会话角色水合（D-081）：磁盘目录解析之后从分支快照重建（最近一条可解析快照，
+    // 损坏向前回退并 warn，全部不可解析则为空）；磁盘优先、16 个 / 2000 字符菜单
+    // （磁盘+会话合并计算）都是**暴露**预算——未暴露的项保留在数据表里，不删除。
+    const hydratedRoles = mergeSubagentRoles(diskRoles, readSessionRoles(session, api.logger), api.logger);
+    /**
+     * 会话角色数据表 = 快照里的**全部**合法会话角色（含被磁盘遮蔽/未暴露项）：
+     * 先 appendEntry 成功再提交，写失败即注册失败（内存与文件不背离）。持久化写它——
+     * 视图收窄（遮蔽/超预算）不抹掉数据。
+     */
+    const sessionRoles = new Map(hydratedRoles.sessionRoles);
+    /** 可用集 = 磁盘 ∪ 通过暴露预算的会话角色（磁盘优先）：resolveRole/菜单/role 枚举只看它。 */
+    const roles = new Map(hydratedRoles.roles);
+    const renderRoleMenu = () => [...roles.values()]
         .sort((left, right) => (left.id < right.id ? -1 : 1))
         .map((role) => `${role.id} — ${role.description}`)
         .join("; ");
+    /** 全量快照落盘（append-only）：只存会话角色，绝不把磁盘角色写进条目。 */
+    const persistSessionRoles = (next) => {
+        const snapshot = {
+            version: 1,
+            roles: Object.freeze([...next].map(toSessionRoleRecord)),
+        };
+        session.appendEntry(SESSION_ROLE_STATE_ENTRY, snapshot);
+    };
     /**
      * D-044 §5.6：把支持进度面的 adapter 装饰一层，累计"运行中 step"与最近一条
      * 摘要，供工具 onUpdate 节流上报父 UI（只回计数与摘要，不回正文）。
@@ -922,57 +1091,12 @@ export function createCapability(api, options) {
         ...(limits === undefined ? {} : { limits }),
         ...(api.logger === undefined ? {} : { logger: api.logger }),
     });
-    const parameters = Type.Object({
-        prompts: Type.Array(Type.String({
-            minLength: 1,
-            description: "Self-contained prompt for one subagent task; the child session sees no parent history",
-        }), {
-            minItems: 1,
-            description: `1..${maxTasksPerCall} independent prompts run as separate subagent tasks`,
-        }),
-        context: Type.Optional(Type.Object({
-            anchors: Type.Optional(Type.Array(Type.Object({
-                path: Type.String({
-                    minLength: 1,
-                    maxLength: CONTEXT_PATH_MAX_CHARS,
-                    description: "File path the child should start from",
-                }),
-                line: Type.Optional(Type.Integer({ minimum: 1, description: "Line number in path (positive integer)" })),
-                note: Type.Optional(Type.String({
-                    maxLength: CONTEXT_NOTE_MAX_CHARS,
-                    description: "One-line why-it-matters note",
-                })),
-            }), { maxItems: CONTEXT_LIST_MAX_ITEMS })),
-            failedAttempts: Type.Optional(Type.Array(Type.Object({
-                command: Type.String({
-                    minLength: 1,
-                    maxLength: CONTEXT_COMMAND_MAX_CHARS,
-                    description: "Command that was already tried and failed",
-                }),
-                note: Type.Optional(Type.String({ maxLength: CONTEXT_NOTE_MAX_CHARS, description: "One-line failure note" })),
-            }), { maxItems: CONTEXT_LIST_MAX_ITEMS })),
-        }, {
-            description: "Parent pointers rendered as a header block into each child prompt: file:line anchors and commands " +
-                "already tried and failed. Pointers only — children still read the real files.",
-        })),
-        ...(roles.size === 0
-            ? {}
-            : {
-                role: Type.Optional(Type.String({
-                    description: `Named subagent role applied to every prompt in this call; one of: ${[...roles.keys()].sort().join(", ")}. ` +
-                        "Omit for a generic task. Roles frame the task; they do not change the child's model or tools.",
-                })),
-            }),
-        // background（D-060 S6）在 properties 内组合：此前的 `{...parameters, background}`
-        // 顶层展开把键放在 properties 之外，模型面 schema（anthropic 只取 schema.properties、
-        // openai 原样透传）从未真正声明该参数——D-060 裁决 13 翻转后随默认注册修正，
-        // 裁决 15 起开关形态退役、参数无条件声明。
-        background: Type.Optional(Type.Boolean({
-            description: "Submit without waiting: return task tickets immediately and keep working; settled results are " +
-                "announced at your next model round and can be read with subagent_result (optionally waiting).",
-        })),
-    });
-    const tool = api.registerTool({
+    /**
+     * `subagent_run` 的定义按**当前角色表**现场构建（D-081 即时生效）：set/remove 之后
+     * 以同 owner 同名重注册（runtime 语义 = 更新）让新菜单与 `role` 参数枚举在父会话的
+     * 下一次模型请求即可见，不需要重启或新建会话。
+     */
+    const buildRunToolDefinition = () => ({
         name: "subagent_run",
         label: "Run subagents",
         description: `Delegate 1..${maxTasksPerCall} independent subagent tasks in one call and return their bounded terminal results. ` +
@@ -990,152 +1114,499 @@ export function createCapability(api, options) {
             "status only." +
             (roles.size === 0
                 ? ""
-                : ` Configured subagent roles (pass \`role\`): ${roleSummary}. A role's instructions frame every task in the call; ` +
-                    "child model and tools stay inherited from this session."),
-        parameters,
-        execute: async (first, second, _signal, onUpdate) => {
-            const input = objectInput(first, second);
-            const prompts = readPrompts(input.prompts, maxTasksPerCall);
-            const role = resolveRole(input.role, roles);
-            // context 注入（设计 §2.3）：形状/边界违规在此整体拒绝；两个列表皆空归一化为
-            // undefined，后续路径与 context 缺省完全一致。
-            const contextBlock = renderDelegateContext(parseDelegateContext(input.context));
-            const background = input.background === true;
-            // 嵌套深度硬限（退役切片 2，Option A）：沿 S2 血缘头回溯本会话层级，已达
-            // maxNestedDepth 层时整次调用结构化拒绝——递归的兜底边界（不依赖模型自觉）。
-            // resume 不涉深度（S5 裁定：续写既有会话不计新层级，走 subagent_resume）。
-            // agentDir 单源（D-075 S4 第三批）：显式 options 优先，缺省回落 api.host.agentDir。
-            const agentDir = options?.agentDir ?? api.host.agentDir ?? "";
-            if (agentDir !== "") {
-                const depth = lineageDepth(session.getSessionId(), agentDir, maxNestedDepth + 2);
-                if (depth !== undefined && depth + 1 > maxNestedDepth) {
-                    throw new SubagentDelegateError("subagent_depth_exceeded", `this session already sits at nested depth ${depth}; delegation beyond maxNestedDepth ${maxNestedDepth} is refused`);
-                }
+                : ` Configured subagent roles (pass \`role\`): ${renderRoleMenu()}. A role's instructions frame every task in the call; ` +
+                    "a role with a narrowing profile also applies its tools/mode/model/thinkingLevel to the child, verified after creation."),
+        parameters: Type.Object({
+            prompts: Type.Array(Type.String({
+                minLength: 1,
+                description: "Self-contained prompt for one subagent task; the child session sees no parent history",
+            }), {
+                minItems: 1,
+                description: `1..${maxTasksPerCall} independent prompts run as separate subagent tasks`,
+            }),
+            context: Type.Optional(Type.Object({
+                anchors: Type.Optional(Type.Array(Type.Object({
+                    path: Type.String({
+                        minLength: 1,
+                        maxLength: CONTEXT_PATH_MAX_CHARS,
+                        description: "File path the child should start from",
+                    }),
+                    line: Type.Optional(Type.Integer({ minimum: 1, description: "Line number in path (positive integer)" })),
+                    note: Type.Optional(Type.String({
+                        maxLength: CONTEXT_NOTE_MAX_CHARS,
+                        description: "One-line why-it-matters note",
+                    })),
+                }), { maxItems: CONTEXT_LIST_MAX_ITEMS })),
+                failedAttempts: Type.Optional(Type.Array(Type.Object({
+                    command: Type.String({
+                        minLength: 1,
+                        maxLength: CONTEXT_COMMAND_MAX_CHARS,
+                        description: "Command that was already tried and failed",
+                    }),
+                    note: Type.Optional(Type.String({ maxLength: CONTEXT_NOTE_MAX_CHARS, description: "One-line failure note" })),
+                }), { maxItems: CONTEXT_LIST_MAX_ITEMS })),
+            }, {
+                description: "Parent pointers rendered as a header block into each child prompt: file:line anchors and commands " +
+                    "already tried and failed. Pointers only — children still read the real files.",
+            })),
+            ...(roles.size === 0
+                ? {}
+                : {
+                    role: Type.Optional(Type.String({
+                        description: `Named subagent role applied to every prompt in this call; one of: ${[...roles.keys()].sort().join(", ")}. ` +
+                            "Omit for a generic task. Roles frame the task; a role may also narrow the child's " +
+                            "tools/mode/model (verified after creation).",
+                    })),
+                }),
+            // background（D-060 S6）在 properties 内组合：此前的 `{...parameters, background}`
+            // 顶层展开把键放在 properties 之外，模型面 schema（anthropic 只取 schema.properties、
+            // openai 原样透传）从未真正声明该参数——D-060 裁决 13 翻转后随默认注册修正，
+            // 裁决 15 起开关形态退役、参数无条件声明。
+            background: Type.Optional(Type.Boolean({
+                description: "Submit without waiting: return task tickets immediately and keep working; settled results are " +
+                    "announced at your next model round and can be read with subagent_result (optionally waiting).",
+            })),
+        }),
+        execute: executeSubagentRun,
+    });
+    const executeSubagentRun = async (first, second, _signal, onUpdate) => {
+        const input = objectInput(first, second);
+        const prompts = readPrompts(input.prompts, maxTasksPerCall);
+        const role = resolveRole(input.role, roles);
+        // context 注入（设计 §2.3）：形状/边界违规在此整体拒绝；两个列表皆空归一化为
+        // undefined，后续路径与 context 缺省完全一致。
+        const contextBlock = renderDelegateContext(parseDelegateContext(input.context));
+        const background = input.background === true;
+        // 嵌套深度硬限（退役切片 2，Option A）：沿 S2 血缘头回溯本会话层级，已达
+        // maxNestedDepth 层时整次调用结构化拒绝——递归的兜底边界（不依赖模型自觉）。
+        // resume 不涉深度（S5 裁定：续写既有会话不计新层级，走 subagent_resume）。
+        // agentDir 单源（D-075 S4 第三批）：显式 options 优先，缺省回落 api.host.agentDir。
+        const agentDir = options?.agentDir ?? api.host.agentDir ?? "";
+        if (agentDir !== "") {
+            const depth = lineageDepth(session.getSessionId(), agentDir, maxNestedDepth + 2);
+            if (depth !== undefined && depth + 1 > maxNestedDepth) {
+                throw new SubagentDelegateError("subagent_depth_exceeded", `this session already sits at nested depth ${depth}; delegation beyond maxNestedDepth ${maxNestedDepth} is refused`);
             }
-            // submit 是同步抛出契约（预算/队列/已释放），逐条捕获为条目级 rejected；
-            // 全部提交完成后再逐条 drain，任务因此并行执行。
-            const pending = [];
-            const tasks = new Array(prompts.length).fill(undefined);
-            // 回合级血缘（第 3 期第二批）：提交动作发生在父回合工具阶段，此时 correlationId
-            // 有值；getter 缺席或返回 undefined 时不写键（行为回退）。仅 subagent_run 新建
-            // 路径携带——resume 打开既有会话、头定格，写键即"要求了但不生效"。
-            const turnCorrelationId = options?.getTurnCorrelationId?.();
-            for (let index = 0; index < prompts.length; index += 1) {
-                const prompt = prompts[index];
-                // 总量硬限（承载退役切片 2，Option A）：本会话累计创建数达上限时按结构化
-                // 码拒绝该条目（同批其余条目继续）。深度硬限在 execute 开头沿 S2 血缘头
-                // 整调用拒绝（见上），不在此重复。
-                if (createdSubagentCount >= maxTotalPerParent) {
-                    tasks[index] = {
-                        taskId: "",
-                        status: "rejected",
-                        reasonCode: "subagent_child_quota",
-                        reason: `this session already created ${createdSubagentCount} child sessions (cap ${maxTotalPerParent})`,
-                        messageCount: 0,
-                    };
-                    continue;
-                }
-                createdSubagentCount += 1;
-                // 首条 prompt 组装（角色框定 + 可选父投影）；context 头部块（有则）在最上、
-                // 与后续内容空一行，无块时与现状逐字节一致。字节数仍走 submit 侧 maxPromptBytes
-                // 预算，超限按预算拒绝而不是静默截断。
-                const composed = role === undefined
-                    ? prompt
-                    : role.parentView === true
-                        ? `${composeRolePrompt(role, prompt)}\n\n${composeParentView(session, session.getSessionId()) ?? ""}`.trim()
-                        : composeRolePrompt(role, prompt);
-                try {
-                    pending.push({
-                        index,
-                        handle: runtime.submit({
-                            prompt: contextBlock === undefined ? composed : `${contextBlock}\n\n${composed}`,
-                            // 血缘（D-060 S1）：父会话 id 随 metadata 过线，宿主写进子会话文件头；
-                            // 角色档案（若角色定义带收窄）一并带上。
-                            metadata: {
-                                [AGENT_TASK_PARENT_SESSION_KEY]: session.getSessionId(),
-                                ...(turnCorrelationId === undefined
-                                    ? {}
-                                    : { [AGENT_TASK_PARENT_TRACE_KEY]: turnCorrelationId }),
-                                ...(role?.profile === undefined ? {} : { [AGENT_TASK_CHILD_PROFILE_KEY]: role.profile }),
-                            },
-                        }),
-                    });
-                }
-                catch (error) {
-                    tasks[index] = {
-                        taskId: "",
-                        status: "rejected",
-                        reasonCode: reasonCodeOf(error),
-                        reason: errorText(error),
-                        messageCount: 0,
-                    };
-                }
+        }
+        // submit 是同步抛出契约（预算/队列/已释放），逐条捕获为条目级 rejected；
+        // 全部提交完成后再逐条 drain，任务因此并行执行。
+        const pending = [];
+        const tasks = new Array(prompts.length).fill(undefined);
+        // 回合级血缘（第 3 期第二批）：提交动作发生在父回合工具阶段，此时 correlationId
+        // 有值；getter 缺席或返回 undefined 时不写键（行为回退）。仅 subagent_run 新建
+        // 路径携带——resume 打开既有会话、头定格，写键即"要求了但不生效"。
+        const turnCorrelationId = options?.getTurnCorrelationId?.();
+        for (let index = 0; index < prompts.length; index += 1) {
+            const prompt = prompts[index];
+            // 总量硬限（承载退役切片 2，Option A）：本会话累计创建数达上限时按结构化
+            // 码拒绝该条目（同批其余条目继续）。深度硬限在 execute 开头沿 S2 血缘头
+            // 整调用拒绝（见上），不在此重复。
+            if (createdSubagentCount >= maxTotalPerParent) {
+                tasks[index] = {
+                    taskId: "",
+                    status: "rejected",
+                    reasonCode: "subagent_child_quota",
+                    reason: `this session already created ${createdSubagentCount} child sessions (cap ${maxTotalPerParent})`,
+                    messageCount: 0,
+                };
+                continue;
             }
-            // 后台委派（D-060 S6，配置门默认关）：提交即返回票据，不 drain——任务挂在
-            // 调度器上继续跑（会话级生命周期，父栅栏/会话销毁统一回收）。每个后台任务
-            // 挂一个结算观察器：结算一行有界 JSON 进宿主 sink，随父的下一次模型轮次注入。
-            if (background === true) {
-                const tickets = [];
-                for (const item of pending) {
-                    try {
-                        const handle = await item.handle;
-                        tickets.push({ taskId: handle.id });
-                        const sink = options?.backgroundDigestSink;
-                        if (sink !== undefined) {
-                            void handle
-                                .result()
-                                .then((record) => {
-                                sink(JSON.stringify({
-                                    taskId: record.taskId,
-                                    sessionId: record.sessionId,
-                                    status: record.status,
-                                    ...(record.reasonCode === undefined ? {} : { reasonCode: record.reasonCode }),
-                                }));
-                            })
-                                .catch(() => {
-                                // 摘要观察失败不影响任务本身（终态已在调度器落库可查）。
-                            });
-                        }
-                    }
-                    catch {
-                        // submit 同步抛错已在上面捕获为条目级 rejected——后台票据只收成功提交。
-                    }
-                }
-                return { background: true, tasks: tickets };
+            createdSubagentCount += 1;
+            // 首条 prompt 组装（角色框定 + 可选父投影）；context 头部块（有则）在最上、
+            // 与后续内容空一行，无块时与现状逐字节一致。字节数仍走 submit 侧 maxPromptBytes
+            // 预算，超限按预算拒绝而不是静默截断。
+            const composed = role === undefined
+                ? prompt
+                : role.parentView === true
+                    ? `${composeRolePrompt(role, prompt)}\n\n${composeParentView(session, session.getSessionId()) ?? ""}`.trim()
+                    : composeRolePrompt(role, prompt);
+            try {
+                pending.push({
+                    index,
+                    handle: runtime.submit({
+                        prompt: contextBlock === undefined ? composed : `${contextBlock}\n\n${composed}`,
+                        // 血缘（D-060 S1）：父会话 id 随 metadata 过线，宿主写进子会话文件头。
+                        // 角色存在时 child profile 恒定携带（档案基线含 roleId，无收窄字段的角色
+                        // 同样有血缘——/agents 与 subagent_list/subagent_result 的角色血缘对全部
+                        // 角色生效）；`role.profile ?? { version: 1, roleId }` 是防御兜底——对
+                        // validateRoleDefinition 产出的角色不可达；回归测试钉住该行为。
+                        metadata: {
+                            [AGENT_TASK_PARENT_SESSION_KEY]: session.getSessionId(),
+                            ...(turnCorrelationId === undefined ? {} : { [AGENT_TASK_PARENT_TRACE_KEY]: turnCorrelationId }),
+                            ...(role === undefined
+                                ? {}
+                                : {
+                                    [AGENT_TASK_CHILD_PROFILE_KEY]: role.profile ?? { version: 1, roleId: role.id },
+                                }),
+                        },
+                    }),
+                });
+            }
+            catch (error) {
+                tasks[index] = {
+                    taskId: "",
+                    status: "rejected",
+                    reasonCode: reasonCodeOf(error),
+                    reason: errorText(error),
+                    messageCount: 0,
+                };
             }
-            let completed = tasks.filter((task) => task !== undefined).length;
+        }
+        // 后台委派（D-060 S6，配置门默认关）：提交即返回票据，不 drain——任务挂在
+        // 调度器上继续跑（会话级生命周期，父栅栏/会话销毁统一回收）。每个后台任务
+        // 挂一个结算观察器：结算一行有界 JSON 进宿主 sink，随父的下一次模型轮次注入。
+        if (background === true) {
+            const tickets = [];
             for (const item of pending) {
-                let taskId = "";
                 try {
                     const handle = await item.handle;
-                    taskId = handle.id;
-                    const record = await handle.drain({ timeoutMs: taskTimeoutMs });
-                    // escalate 上抛（D-060 S4）：随任务投影一起交回父模型（取后即清）。
-                    const escalations = wiring?.drainEscalations?.(record.sessionId) ?? [];
-                    // 兄弟流量摘录（D-060 裁决 14）：只读审计面，随同一信封对父可见。
-                    const siblingTraffic = wiring?.readSiblingTraffic?.(record.sessionId, SIBLING_TRAFFIC_EXCERPTS) ?? [];
-                    tasks[item.index] = {
-                        ...projectRecord(record),
-                        ...(escalations.length === 0 ? {} : { escalations }),
-                        ...(siblingTraffic.length === 0 ? {} : { siblingTraffic }),
-                    };
+                    tickets.push({ taskId: handle.id });
+                    const sink = options?.backgroundDigestSink;
+                    if (sink !== undefined) {
+                        void handle
+                            .result()
+                            .then((record) => {
+                            sink(JSON.stringify({
+                                taskId: record.taskId,
+                                sessionId: record.sessionId,
+                                status: record.status,
+                                ...(record.reasonCode === undefined ? {} : { reasonCode: record.reasonCode }),
+                            }));
+                        })
+                            .catch(() => {
+                            // 摘要观察失败不影响任务本身（终态已在调度器落库可查）。
+                        });
+                    }
                 }
-                catch (error) {
-                    // drain 抛错（如持久化失败）：保留原始 message，不静默吞掉。
-                    tasks[item.index] = { taskId, status: "failed", reason: errorText(error), messageCount: 0 };
+                catch {
+                    // submit 同步抛错已在上面捕获为条目级 rejected——后台票据只收成功提交。
+                }
+            }
+            return { background: true, tasks: tickets };
+        }
+        let completed = tasks.filter((task) => task !== undefined).length;
+        for (const item of pending) {
+            let taskId = "";
+            try {
+                const handle = await item.handle;
+                taskId = handle.id;
+                const record = await handle.drain({ timeoutMs: taskTimeoutMs });
+                // escalate 上抛（D-060 S4）：随任务投影一起交回父模型（取后即清）。
+                const escalations = wiring?.drainEscalations?.(record.sessionId) ?? [];
+                // 兄弟流量摘录（D-060 裁决 14）：只读审计面，随同一信封对父可见。
+                const siblingTraffic = wiring?.readSiblingTraffic?.(record.sessionId, SIBLING_TRAFFIC_EXCERPTS) ?? [];
+                tasks[item.index] = {
+                    ...projectRecord(record),
+                    ...(escalations.length === 0 ? {} : { escalations }),
+                    ...(siblingTraffic.length === 0 ? {} : { siblingTraffic }),
+                };
+            }
+            catch (error) {
+                // drain 抛错（如持久化失败）：保留原始 message，不静默吞掉。
+                tasks[item.index] = { taskId, status: "failed", reason: errorText(error), messageCount: 0 };
+            }
+            completed += 1;
+            // D-044 §5.6：进度随任务完成节流上报（累计 step 数 + 最近一条回合摘要）；
+            // 只回摘要，不回模型正文。
+            const progressSuffix = progressState.steps === 0
+                ? ""
+                : ` · steps ${progressState.steps}${progressState.last === undefined ? "" : ` · ${progressState.last}`}`;
+            onUpdate?.({
+                content: [{ type: "text", text: `subagent ${completed}/${prompts.length}${progressSuffix}` }],
+                details: {},
+            });
+        }
+        return { tasks: tasks.filter((task) => task !== undefined) };
+    };
+    /** `subagent_run` 的注册句柄：set/remove 后刷新替换，释放时以最新句柄为准。 */
+    const runTool = { current: api.registerTool(buildRunToolDefinition()) };
+    /** 同 owner 同名重注册 = 更新（旧句柄 dispose 因表项已被接手而失效）。 */
+    const refreshRunTool = () => {
+        runTool.current = api.registerTool(buildRunToolDefinition());
+    };
+    /**
+     * 会话角色三工具（D-081）：注册/列出/删除。注册是"先落盘再提交内存"——持久化条目
+     * 写在会话文件里（customType `subagent.roles.state`），下次打开同一会话仍在；会话
+     * 角色不写 `<agentDir>/roles/`、不跨会话共享、子代理不继承。三工具未声明 readonlySafe，
+     * readonly 会话沿用既有"未声明即不激活"语义，不做特殊分支。
+     */
+    const roleSetTool = api.registerTool({
+        name: "subagent_role_set",
+        label: "Register a session subagent role",
+        description: "Register or update a session-scoped subagent role and use it by name in subagent_run. The role is persisted " +
+            "in this session file, so it is still available when this session is opened again; it is not written to the " +
+            "shared roles directory, not shared with other sessions, and not inherited by child subagents. Use it when the " +
+            "built-in roles are too coarse for the task at hand. id, description and instructions are required; the optional " +
+            "fields narrow the child the same way a role file does (tools/mode/model/thinkingLevel/systemPromptAppend) and " +
+            "parentView adds a bounded parent projection. Same id updates that session role; the change is visible to the " +
+            "next subagent_run call without restarting anything.",
+        parameters: Type.Object({
+            id: Type.String({
+                pattern: "^[a-z0-9][a-z0-9_-]{0,31}$",
+                description: "Lowercase role id (letters, digits, - and _, at most 32 chars)",
+            }),
+            description: Type.String({
+                minLength: 1,
+                maxLength: ROLE_DESCRIPTION_CHARS,
+                description: `One-line role description shown in the subagent_run role menu (at most ${ROLE_DESCRIPTION_CHARS} chars)`,
+            }),
+            instructions: Type.String({
+                minLength: 1,
+                maxLength: ROLE_INSTRUCTIONS_CHARS,
+                description: `Role instructions framing every task in a call (at most ${ROLE_INSTRUCTIONS_CHARS} chars)`,
+            }),
+            model: Type.Optional(Type.String({
+                description: "Narrow the child to this model id (must resolve within this session's scoped models)",
+            })),
+            thinkingLevel: Type.Optional(Type.String({
+                description: "Narrow the child thinking level: minimal | low | medium | high | xhigh | max",
+            })),
+            tools: Type.Optional(Type.Array(Type.String(), {
+                description: "Tool allowlist intersected with the inherited tool set ([] gives the child no tools)",
+            })),
+            mode: Type.Optional(Type.Union([Type.Literal("readonly"), Type.Literal("full-control")], {
+                description: "Narrow-only session mode: readonly never widens a readonly parent",
+            })),
+            systemPromptAppend: Type.Optional(Type.String({ description: "Text appended to the child system prompt (never replaces inherited content)" })),
+            parentView: Type.Optional(Type.Boolean({
+                description: "Give the child a bounded projection of the parent goal/tools (parent history stays hidden)",
+            })),
+        }),
+        execute: async (first, second) => {
+            const input = objectInput(first, second, "subagent_role_set");
+            const id = input.id;
+            if (typeof id !== "string" || !ROLE_ID_PATTERN.test(id)) {
+                throw new SubagentDelegateError("subagent_invalid_input", `subagent_role_set id must match ${String(ROLE_ID_PATTERN)} (lowercase letters, digits, "-" and "_", ` +
+                    `at most 32 chars), got ${JSON.stringify(id)}`);
+            }
+            for (const key of Object.keys(input)) {
+                if (key === "id" || ROLE_KNOWN_KEYS.includes(key))
+                    continue;
+                throw new SubagentDelegateError("subagent_invalid_input", `subagent_role_set has unknown parameter ${JSON.stringify(key)} (known: id, ${ROLE_KNOWN_KEYS.join(", ")})`);
+            }
+            const definition = {};
+            for (const key of ROLE_KNOWN_KEYS) {
+                if (input[key] !== undefined)
+                    definition[key] = input[key];
+            }
+            let role;
+            try {
+                role = validateRoleDefinition(id, definition, `subagent_role_set "${id}"`);
+            }
+            catch (error) {
+                throw new SubagentDelegateError("subagent_invalid_input", errorText(error));
+            }
+            if (role === undefined) {
+                throw new SubagentDelegateError("subagent_invalid_input", `subagent_role_set could not build role ${JSON.stringify(id)}`);
+            }
+            // 磁盘角色是用户资产：与**当前可见**磁盘角色撞名的新注册结构化拒绝，不隐式改写
+            // 其含义。已有会话数据条目（装载期被磁盘遮蔽的影子角色）走正常 upsert 路径：
+            // 更新的是会话文件里的数据，视图仍由磁盘角色当值。
+            if (diskRoles.has(id) && !sessionRoles.has(id)) {
+                throw new SubagentDelegateError("subagent_role_conflict", `subagent role ${JSON.stringify(id)} is a disk role declared by this suite; a session role cannot shadow it — ` +
+                    "pick another id or edit the role file");
+            }
+            // 预算检查（暴露预算：可用集 + 新角色，磁盘+会话合并计算）：超限结构化拒绝并提示精简。
+            const prospective = new Map(roles);
+            prospective.set(id, role);
+            const quota = roleQuotaViolation(prospective);
+            if (quota !== undefined)
+                throw new SubagentDelegateError("subagent_role_quota", quota);
+            // 写入顺序：先 appendEntry（失败原样抛出，注册即失败），成功后才提交内存——
+            // 内存与文件不背离。快照是 append-only 全量形态，写的是**数据表**（含未暴露项，
+            // 视图收窄不抹掉数据）。
+            const status = sessionRoles.has(id) ? "updated" : "created";
+            const nextSessionRoles = new Map(sessionRoles);
+            nextSessionRoles.set(id, role);
+            persistSessionRoles(nextSessionRoles.values());
+            sessionRoles.set(id, role);
+            // 视图提交：磁盘角色优先——影子 id 只更新数据，不改变可用集。
+            if (!diskRoles.has(id))
+                roles.set(id, role);
+            refreshRunTool();
+            return { id, status, roles: [...roles.keys()].sort() };
+        },
+    });
+    const roleListTool = api.registerTool({
+        name: "subagent_role_list",
+        label: "List subagent roles",
+        description: "List the subagent roles available in this session: id, origin (disk = shared role file, session = registered " +
+            "here with subagent_role_set), description, and whether the role narrows the child (hasProfile) or enables the " +
+            "bounded parent projection (hasParentView). Pass an id to get one role's full definition, including its " +
+            "instructions and narrowing fields, to read, modify and re-register with subagent_role_set.",
+        parameters: Type.Object({
+            id: Type.Optional(Type.String({ description: "Role id; omit to list every available role" })),
+        }),
+        execute: async (first, second) => {
+            const input = objectInput(first, second, "subagent_role_list");
+            const requested = input.id;
+            if (requested !== undefined && (typeof requested !== "string" || requested.trim() === "")) {
+                throw new SubagentDelegateError("subagent_invalid_input", "subagent_role_list id must be a non-empty string when present");
+            }
+            const originOf = (roleId) => (diskRoles.has(roleId) ? "disk" : "session");
+            if (requested === undefined) {
+                const entries = [...roles.values()]
+                    .sort((left, right) => (left.id < right.id ? -1 : 1))
+                    .map((role) => ({
+                    id: role.id,
+                    origin: originOf(role.id),
+                    description: role.description,
+                    hasProfile: hasNarrowingProfile(role),
+                    hasParentView: role.parentView === true,
+                }));
+                return { roles: entries };
+            }
+            const role = roles.get(requested);
+            if (role === undefined) {
+                throw new SubagentDelegateError("subagent_unknown_role", unknownRoleMessage(requested, roles));
+            }
+            return { role: { ...toSessionRoleRecord(role), origin: originOf(role.id) } };
+        },
+    });
+    const roleRemoveTool = api.registerTool({
+        name: "subagent_role_remove",
+        label: "Remove a session subagent role",
+        description: "Remove one session-scoped subagent role (one registered with subagent_role_set) from this session. The removal " +
+            "is persisted in the session file and takes effect for the next subagent_run call. Disk roles cannot be removed " +
+            "here — they live in the shared roles directory and are changed by editing their file; such a call is rejected " +
+            "with a structured error.",
+        parameters: Type.Object({
+            id: Type.String({ description: "Session role id to remove" }),
+        }),
+        execute: async (first, second) => {
+            const input = objectInput(first, second, "subagent_role_remove");
+            const id = input.id;
+            if (typeof id !== "string" || id.trim() === "") {
+                throw new SubagentDelegateError("subagent_invalid_input", "subagent_role_remove requires a role id");
+            }
+            // 会话数据条目优先：被磁盘遮蔽的影子角色也能删（删的是会话文件里的数据，
+            // 磁盘角色本身不受影响）；没有会话数据时才按"纯磁盘角色"结构化拒绝。
+            if (!sessionRoles.has(id)) {
+                if (diskRoles.has(id)) {
+                    throw new SubagentDelegateError("subagent_role_conflict", `subagent role ${JSON.stringify(id)} is a disk role; disk roles are changed by editing their file, ` +
+                        "not removed from a session");
                 }
-                completed += 1;
-                // D-044 §5.6：进度随任务完成节流上报（累计 step 数 + 最近一条回合摘要）；
-                // 只回摘要，不回模型正文。
-                const progressSuffix = progressState.steps === 0
+                throw new SubagentDelegateError("subagent_unknown_role", unknownRoleMessage(id, roles));
+            }
+            // 同样的写入顺序：先全量快照落盘，成功后才提交内存与刷新工具面。
+            const nextSessionRoles = new Map(sessionRoles);
+            nextSessionRoles.delete(id);
+            persistSessionRoles(nextSessionRoles.values());
+            sessionRoles.delete(id);
+            // 视图提交：磁盘角色优先——删掉影子数据后磁盘角色仍是可用集的当值项。
+            if (!diskRoles.has(id))
+                roles.delete(id);
+            refreshRunTool();
+            return { id, status: "removed", roles: [...roles.keys()].sort() };
+        },
+    });
+    /**
+     * `/roles` 视图（D-081 用户面）：数据源只有上面的三个闭包表（实时值）——可用集
+     * `roles`（按来源分区，磁盘 `diskRoles` 优先）、数据表 `sessionRoles`（诊断里
+     * "数据仍在会话文件里"的判据）、水合诊断 `hydratedRoles` 与目录解析诊断
+     * `roleCatalog.dangling`。分区/诊断行仅在非空时出现，列表按 id 排序。
+     */
+    const renderRolesOverview = () => {
+        // roles.agentDir 是角色目录（<agentDir>/roles/）的来源；没有它就没有磁盘角色面，
+        // 路径提示也就无从谈起（未见关联的会话不引导用户去丢文件）。
+        const roleAgentDir = options?.roles?.agentDir;
+        const sorted = [...roles.values()].sort((left, right) => (left.id < right.id ? -1 : 1));
+        const disk = sorted.filter((role) => diskRoles.has(role.id));
+        const session = sorted.filter((role) => !diskRoles.has(role.id));
+        const lines = [];
+        if (sorted.length === 0) {
+            lines.push("No subagent roles are available in this session. Register one with subagent_role_set" +
+                (roleAgentDir === undefined
                     ? ""
-                    : ` · steps ${progressState.steps}${progressState.last === undefined ? "" : ` · ${progressState.last}`}`;
-                onUpdate?.({
-                    content: [{ type: "text", text: `subagent ${completed}/${prompts.length}${progressSuffix}` }],
-                    details: {},
-                });
+                    : `, or drop a role file into ${join(roleAgentDir, ROLE_CATALOG_DIR)}/ and associate its id in the suite.`));
+        }
+        else {
+            lines.push(`Subagent roles available in this session: ${sorted.length}`);
+            if (disk.length > 0 || session.length > 0)
+                lines.push("");
+            if (disk.length > 0) {
+                lines.push("disk:");
+                for (const role of disk)
+                    lines.push(`  ${role.id} — ${role.description}`);
+            }
+            if (session.length > 0) {
+                lines.push("session:");
+                for (const role of session)
+                    lines.push(`  ${role.id} — ${role.description}`);
+            }
+        }
+        // 诊断区（仅非空时显示）：影子/超预算条目按数据表过滤——已被 remove 的旧诊断
+        // 不再声称"数据仍保留"；悬空关联只列 id，有角色目录时附逐 id 修复提示。
+        const shadowed = [...hydratedRoles.shadowedByDisk].filter((id) => sessionRoles.has(id)).sort();
+        const overBudget = [...hydratedRoles.droppedForQuota].filter((id) => sessionRoles.has(id)).sort();
+        const dangling = [...roleCatalog.dangling].sort();
+        if (shadowed.length > 0 || overBudget.length > 0) {
+            lines.push("", "Not exposed (data kept in this session file):");
+            if (shadowed.length > 0)
+                lines.push(`  shadowed by a visible disk role: ${shadowed.join(", ")}`);
+            if (overBudget.length > 0) {
+                lines.push(`  over the menu budget (${ROLE_COUNT_LIMIT} roles / ${ROLE_MENU_CHARS} chars): ${overBudget.join(", ")}`);
+            }
+        }
+        if (dangling.length > 0) {
+            lines.push("", `Suite associations without a role file (unavailable): ${dangling.join(", ")}`);
+            if (roleAgentDir !== undefined) {
+                for (const id of dangling) {
+                    lines.push(`  create ${subagentRoleCatalogPath(roleAgentDir, id)} or drop the association`);
+                }
+            }
+        }
+        return lines.join("\n");
+    };
+    /** `/roles <id>` 视图：单角色完整定义（收窄字段存在才显示，parentView 仅 true 显示）。 */
+    const renderRoleDefinitionView = (role) => {
+        const lines = [
+            `id: ${role.id}`,
+            `origin: ${diskRoles.has(role.id) ? "disk" : "session"}`,
+            `description: ${role.description}`,
+            "instructions:",
+            role.instructions,
+        ];
+        const profile = role.profile;
+        if (profile?.model !== undefined)
+            lines.push(`model: ${profile.model}`);
+        if (profile?.thinkingLevel !== undefined)
+            lines.push(`thinkingLevel: ${profile.thinkingLevel}`);
+        if (profile?.tools !== undefined)
+            lines.push(`tools: ${profile.tools.join(", ")}`);
+        if (profile?.mode !== undefined)
+            lines.push(`mode: ${profile.mode}`);
+        if (profile?.systemPromptAppend !== undefined)
+            lines.push("systemPromptAppend:", profile.systemPromptAppend);
+        if (role.parentView === true)
+            lines.push("parentView: true");
+        return lines.join("\n");
+    };
+    /**
+     * `/roles` 斜杠命令（D-081 用户面）：与角色三工具同一注册分支（委派面存在才注册），
+     * 句柄随插件 dispose。只读视图——不改状态、不引入新配置键；未知 id 是正常结果
+     * （error + 可用 id 列表），任何异常都收敛为 `{ status: "error" }`，命令不崩宿主。
+     */
+    const rolesCommand = api.registerCommand({
+        name: "roles",
+        description: "List the subagent roles available in this session (disk + session), or show one role's full definition",
+        argumentHint: "[id]",
+        execute: async (args) => {
+            try {
+                const requested = args.trim();
+                if (requested === "") {
+                    return { status: "success", message: renderRolesOverview() };
+                }
+                const role = roles.get(requested);
+                if (role === undefined) {
+                    return { status: "error", message: unknownRoleMessage(requested, roles) };
+                }
+                return { status: "success", message: renderRoleDefinitionView(role) };
+            }
+            catch (error) {
+                // A slash command must not crash the host (memory /promote precedent).
+                return { status: "error", message: errorText(error) };
             }
-            return { tasks: tasks.filter((task) => task !== undefined) };
         },
     });
     /**
@@ -1416,11 +1887,16 @@ export function createCapability(api, options) {
             },
         });
     return [
-        tool,
+        // 刷新句柄：释放时以最新一次 subagent_run 注册为准（旧句柄 dispose 因表项被接手而失效）。
+        createDisposableRegistration("subagent-delegate.tool.subagent_run", () => void runTool.current.dispose(), `registration:${capabilityManifest.id}:refreshable:tool:subagent_run`),
         resultTool,
         cancelTool,
         steerTool,
         resumeTool,
+        roleSetTool,
+        roleListTool,
+        roleRemoveTool,
+        rolesCommand,
         ...(listTool === undefined ? [] : [listTool]),
         // 子侧通信面（D-060 S4/S5）：获准自建会话两面并存（向下委派 + 向父上抛/兄弟消息）。
         ...childTools,