@ai-agent-forge/plugin-subagent-delegate 0.86.7 → 0.88.0

package/dist/delegate.js

@@ -67,34 +67,9 @@ export const capabilityManifest = {
 };
 // 通信面的宿主接线 `SubagentCommunicationWiringV1`（含信箱消息形状）是 plugin-sdk
 // 公共契约（D-075 S4 第三批迁入 SDK），本包经上方 import 消费并在 index 再导出。
-const COMMUNICATION_FLAG_KEYS = ["resume", "escalate", "sibling"];
-/**
- * 配置通道解析（`api.config.communication`）：缺省对象 = 全关；字段只接受 `true` 或省略，
- * 未知键与错误类型装载期 fail fast，不让"配置了但没生效"的假象存在。
- */
-function readCommunicationConfig(raw) {
-    if (raw === undefined)
-        return {};
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-        throw new Error("subagent-delegate config communication must be an object");
-    }
-    const record = raw;
-    const known = COMMUNICATION_FLAG_KEYS;
-    const unknown = Object.keys(record).filter((key) => !known.includes(key));
-    if (unknown.length > 0) {
-        throw new Error(`subagent-delegate config communication has unknown key(s): ${unknown.join(", ")}`);
-    }
-    const config = {};
-    for (const key of COMMUNICATION_FLAG_KEYS) {
-        const value = record[key];
-        if (value === undefined)
-            continue;
-        if (value !== true)
-            throw new Error(`subagent-delegate config communication.${key} must be true or omitted`);
-        config[key] = true;
-    }
-    return config;
-}
+// 通信面配置键已移除（D-060 裁决 15，2026-10-03）：resume/escalate/sibling 曾是
+// 出厂默认全开的显式开关（裁决 13/14 翻转后仅剩"显式 false 关闭"形态），随开关
+// 形态一并退役——功能基本面只有"有"与"没有"，配置键出现即装载期失败。
 /** 把宿主/调度器/信箱的结构化错误映射为工具面的同码委托错误（保留原始 message）。 */
 function mapCommunicationError(error) {
     if (error instanceof SubagentMailboxErrorV1) {
@@ -202,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;
+}
 /**
  * 解析当前方案的角色目录（**全部来自磁盘**，无编译内定义）。装载期一次性完成，
  * 任何会让"配置了但没生效"的情况都显式失败：
@@ -268,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)");
@@ -500,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;
 }
@@ -513,6 +637,11 @@ const RESULT_READ_DEFAULT_MESSAGES = 20;
 const RESULT_READ_MAX_MESSAGES = 50;
 /** `subagent_result` 的有界等待上限（后台结算收割），默认 0 = 只查一次。 */
 const RESULT_READ_MAX_WAIT_MS = 120_000;
+/**
+ * 每任务随结算投影/信封返回的兄弟流量摘录条数（D-060 裁决 14 父可见性）：有界——
+ * 这是审计摘录不是消息回灌，全量以信箱审计日志为准。
+ */
+const SIBLING_TRAFFIC_EXCERPTS = 8;
 /** UTF-8 字节数（回读信封如实报告体积）。 */
 function utf8ByteLength(text) {
     return Buffer.byteLength(text, "utf8");
@@ -546,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;
 }
@@ -668,14 +797,16 @@ export function createCapability(api, options) {
     const agents = api.agents;
     if (!session)
         throw new Error("subagent-delegate requires the session capability");
-    // 通信面配置在装载期 fail fast（两个上下文都读同一份 agent-dir 配置文件）。
-    const communication = readCommunicationConfig(api.config.communication);
+    // 通信面配置键已移除（D-060 裁决 15）：出现即装载期失败，不留"配置了但没生效"的假象。
+    if (api.config.communication !== undefined) {
+        throw new Error("subagent-delegate config communication was removed (D-060 ruling 15): communication tools register unconditionally; remove the key");
+    }
     const wiring = options?.communicationWiring;
-    // 子侧通信面（子→父 / 子↔子）：只要宿主接线了 post 通道且配置开启就注册——
+    // 子侧通信面（子→父 / 子↔子）：只要宿主接线了 post 通道就注册——
     // 叶子会话（无 agents）只拿这一面；获准自建会话（D-060 S5，agents 在场）两面都要：
     // 它既能向下委派（parent face），也仍能向自己的父上抛/收兄弟消息（child face）。
     const childTools = [];
-    if (wiring?.postEscalate !== undefined && communication.escalate === true) {
+    if (wiring?.postEscalate !== undefined) {
         childTools.push(api.registerTool({
             name: "subagent_escalate",
             label: "Escalate to parent",
@@ -703,12 +834,14 @@ export function createCapability(api, options) {
             },
         }));
     }
-    if (wiring?.sendSibling !== undefined && communication.sibling === true) {
+    if (wiring?.sendSibling !== undefined) {
         childTools.push(api.registerTool({
             name: "subagent_send",
             label: "Message a sibling",
             description: "Send one bounded message to a sibling subagent (a child of the same parent), addressed by its sessionId. " +
-                "Cross-family addressing is rejected.",
+                "Cross-family addressing is rejected. This channel is for data and intermediate artifacts only: task " +
+                "assignment and result acceptance stay with the parent agent. Sibling messages are visible to the parent " +
+                "(audited as excerpts with task results).",
             parameters: Type.Object({
                 to: Type.String({ description: "Recipient child session id" }),
                 text: Type.String({
@@ -735,7 +868,8 @@ export function createCapability(api, options) {
             name: "subagent_inbox",
             label: "Read sibling inbox",
             description: "Read and clear the earliest bounded messages your siblings sent you (subagent_send). Messages are " +
-                "consumed by this call; poll it when coordination is expected.",
+                "consumed by this call; poll it when coordination is expected. The sibling channel carries data and " +
+                "intermediate artifacts only — assignment and acceptance stay with the parent, which can audit this traffic.",
             parameters: Type.Object({
                 limit: Type.Optional(Type.Number({ description: "Max messages to take (1..20, default 10)", minimum: 1, maximum: 20 })),
             }),
@@ -875,27 +1009,47 @@ export function createCapability(api, options) {
     // 100）：对**非 resume** 的每次 submit 计数，超限按 `subagent_child_quota` 拒绝。
     const maxTotalPerParent = resolveInt(undefined, configInt(api, "maxTotalPerParent", 0), 100, 0, "maxTotalPerParent");
     let createdSubagentCount = 0;
-    // 后台委派开关（D-060 S6）：默认关；显式 `true` 才给 `subagent_run` 加 `background`
-    // 参数（提交即返回票据，不阻塞父回合；结算摘要经宿主 sink 进父的下一次模型轮次）。
-    if (api.config.background !== undefined && api.config.background !== true) {
-        throw new Error("subagent-delegate config background must be true or omitted");
+    // background 配置键已移除（D-060 裁决 15，2026-10-03）：后台委派是功能基本面，
+    // 无条件注册（`subagent_run` 的 background 参数与 subagent_cancel / subagent_steer
+    // 随之常在）；键出现即装载期失败，不留"配置了但没生效"的假象。
+    if (api.config.background !== undefined) {
+        throw new Error("subagent-delegate config background was removed (D-060 ruling 15): background delegation registers unconditionally; remove the key");
     }
-    const backgroundEnabled = api.config.background === true;
     // 角色目录 + 方案关联在装载期解析：非法文件/非法关联直接失败，不留"配置了但没生效"的假象。
     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（只回计数与摘要，不回正文）。
@@ -935,50 +1089,14 @@ export function createCapability(api, options) {
         parentSessionId: session.getSessionId(),
         ...(sessionAbortSignal === undefined ? {} : { parentSignal: sessionAbortSignal }),
         ...(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.",
-                })),
-            }),
-    });
-    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. ` +
@@ -986,161 +1104,509 @@ export function createCapability(api, options) {
             "final-assistant summary come back; ask a child for more detail in its prompt if you need it." +
             " Optionally pass `context` — file:line anchors and commands already tried and failed are rendered as a " +
             "header block at the top of each child prompt (pointers only)." +
+            // fork-join 推荐模式（D-060 裁决 14）：大任务拆并行块 + 最终组合任务，中间产物
+            // 留子层、主上下文不膨胀；通知粒度——结算必然回注但只有组合任务的报告需验收。
+            " For large splittable work prefer fork-join: launch the parallel chunk tasks with background:true, then submit " +
+            "one final assembly task (a separate background call) that gathers the chunks with subagent_result({taskId, waitMs}) " +
+            "— intermediate results stay in the child layer and only the assembled final report enters your context. Every " +
+            "task's settlement is announced to you (agent-task-settled), but notifications are not per-task acceptances: " +
+            "accept and act on (todos/goals/next steps) only the final assembly task's report; other settled lines are " +
+            "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: {
-            ...parameters,
-            ...(backgroundEnabled
-                ? {
-                    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).",
+                : ` 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 过线，宿主写进子会话文件头。
+                        // 角色存在时 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,
+                };
+            }
+        }
+        // 后台委派（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(() => {
+                            // 摘要观察失败不影响任务本身（终态已在调度器落库可查）。
+                        });
+                    }
                 }
-                : {}),
-        },
-        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 = backgroundEnabled && 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`);
+                catch {
+                    // submit 同步抛错已在上面捕获为条目级 rejected——后台票据只收成功提交。
                 }
             }
-            // 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,
-                    };
+            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");
                 }
-                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,
-                    };
-                }
+                throw new SubagentDelegateError("subagent_unknown_role", unknownRoleMessage(id, roles));
             }
-            // 后台委派（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——后台票据只收成功提交。
-                    }
+            // 同样的写入顺序：先全量快照落盘，成功后才提交内存与刷新工具面。
+            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
+                    ? ""
+                    : `, 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 { 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) ?? [];
-                    tasks[item.index] = {
-                        ...projectRecord(record),
-                        ...(escalations.length === 0 ? {} : { escalations }),
-                    };
+        }
+        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() };
                 }
-                catch (error) {
-                    // drain 抛错（如持久化失败）：保留原始 message，不静默吞掉。
-                    tasks[item.index] = { taskId, status: "failed", reason: errorText(error), messageCount: 0 };
+                const role = roles.get(requested);
+                if (role === undefined) {
+                    return { status: "error", message: unknownRoleMessage(requested, roles) };
                 }
-                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 { 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) };
         },
     });
     /**
@@ -1200,6 +1666,7 @@ export function createCapability(api, options) {
                 const messages = record.messages.slice(-requested);
                 // escalate 上抛（D-060 S4）：按子会话 id 取走并随信封返回（取后即清）。
                 const escalations = wiring?.drainEscalations?.(record.sessionId) ?? [];
+                const siblingTraffic = wiring?.readSiblingTraffic?.(record.sessionId, SIBLING_TRAFFIC_EXCERPTS) ?? [];
                 return {
                     found: true,
                     source: "record",
@@ -1214,6 +1681,7 @@ export function createCapability(api, options) {
                     truncated: record.truncated || messages.length < record.messages.length,
                     messages: messages.map((message) => detachedSessionSnapshot(message)),
                     ...(escalations.length === 0 ? {} : { escalations }),
+                    ...(siblingTraffic.length === 0 ? {} : { siblingTraffic }),
                 };
             }
             const reader = agents?.session;
@@ -1225,6 +1693,7 @@ export function createCapability(api, options) {
                 return { found: false, source: "session", sessionId };
             const entries = view.entries.slice(-requested);
             const escalations = wiring?.drainEscalations?.(view.sessionId) ?? [];
+            const siblingTraffic = wiring?.readSiblingTraffic?.(view.sessionId, SIBLING_TRAFFIC_EXCERPTS) ?? [];
             return {
                 found: true,
                 source: "session",
@@ -1236,96 +1705,137 @@ export function createCapability(api, options) {
                 truncated: view.truncated || entries.length < view.entryCount,
                 messages: entries.map((entry) => detachedSessionSnapshot(entry)),
                 ...(escalations.length === 0 ? {} : { escalations }),
+                ...(siblingTraffic.length === 0 ? {} : { siblingTraffic }),
             };
         },
     });
-    // steer 不设模型面工具（D-060 S4）：`subagent_run` 是阻塞式 drain-to-terminal，
-    // 父模型在工具调用期间不存在"运行中的子任务"窗口——暴露即死 affordance（与
-    // `deadlineMs` 同一纪律）。父→子 steer 走程序面：agents 桥的 `steer`（运行中
-    // 的后台任务）与本调度器的 `steer`/`findBySession` 原语，供编排插件组合。
-    // subagent_cancel（S4 补充裁决，2026-10-01）：仅 background 委派启用时注册——
-    // 前台 drain 下父模型在 subagent_run 阻塞中不存在运行中窗口（与 steer 的 S4
-    // 裁决同前提），cancel 只在 background 委派返回票据后才有可达窗口。
-    const cancelTool = backgroundEnabled
-        ? api.registerTool({
-            name: "subagent_cancel",
-            label: "Cancel a background subagent",
-            description: "Cancel a running background subagent task by its taskId (the ticket returned by subagent_run with " +
-                "background: true). Only background delegation tickets are cancellable: a foreground subagent_run call " +
-                "blocks until its tasks finish, so it never leaves a running task behind. Terminal statuses (including a " +
-                "task cancelled by something else) come back as already_terminal; unknown taskIds as not_found.",
-            parameters: Type.Object({
-                taskId: Type.String({ description: "Task id from a background subagent_run ticket" }),
-                reason: Type.Optional(Type.String({ description: "Short reason recorded on the cancellation fence" })),
+    // steer 的模型面（D-060 裁决 13，2026-10-02 用户裁决）：`subagent_steer` 随
+    // background 面注册。原 S4 裁决"steer 不设模型面工具"的前提——前台阻塞 drain 下
+    // 父模型无"运行中窗口"——在 background 默认开后失效（提交即返回票据，运行中窗口
+    // 存在），该论证保留为背景说明。语义对齐主流取证（codex v2 send_message /
+    // ZCode SendMessage 均为模型面排队投递）：不打断子代理当前回合，在其下一个模型
+    // 请求前生效。程序面（agents 桥的 steer 与本调度器的 steer/findBySession 原语）
+    // 保持不变，供编排插件组合。
+    // subagent_cancel（S4 补充裁决，2026-10-01）：原"仅 background 委派启用时注册"
+    // 的前提（前台 drain 下父模型在 subagent_run 阻塞中不存在运行中窗口）保留为
+    // 背景说明——cancel 只在 background 委派返回票据后才有可达窗口。
+    // 两个工具自 D-060 裁决 15（2026-10-03）起无条件注册（开关形态退役）。
+    const cancelTool = api.registerTool({
+        name: "subagent_cancel",
+        label: "Cancel a background subagent",
+        description: "Cancel a running background subagent task by its taskId (the ticket returned by subagent_run with " +
+            "background: true). Only background delegation tickets are cancellable: a foreground subagent_run call " +
+            "blocks until its tasks finish, so it never leaves a running task behind. Terminal statuses (including a " +
+            "task cancelled by something else) come back as already_terminal; unknown taskIds as not_found.",
+        parameters: Type.Object({
+            taskId: Type.String({ description: "Task id from a background subagent_run ticket" }),
+            reason: Type.Optional(Type.String({ description: "Short reason recorded on the cancellation fence" })),
+        }),
+        execute: async (first, second) => {
+            const input = objectInput(first, second);
+            const taskId = typeof input.taskId === "string" ? input.taskId : "";
+            if (taskId.trim() === "") {
+                throw new SubagentDelegateError("subagent_invalid_input", "subagent_cancel requires a taskId");
+            }
+            const reason = typeof input.reason === "string" && input.reason.trim() !== "" ? input.reason : undefined;
+            const result = await runtime.cancelById(taskId, { owner: capabilityManifest.id, parentSessionId: session.getSessionId() }, reason);
+            return result.outcome === "not_found"
+                ? { outcome: "not_found", taskId }
+                : { outcome: result.outcome, taskId, status: result.status };
+        },
+    });
+    // subagent_steer（D-060 裁决 13）：与 cancelTool 同属 background 面——有界引导消息
+    // 投递给运行中的后台子任务（排队语义），需要硬终止时模型仍走 subagent_cancel。
+    // D-060 裁决 15（2026-10-03）起无条件注册（开关形态退役）。
+    const steerTool = api.registerTool({
+        name: "subagent_steer",
+        label: "Steer a background subagent",
+        description: "Deliver one bounded steering message to a running background subagent task by its taskId (the ticket " +
+            "returned by subagent_run with background: true). Queued delivery: it does NOT interrupt the subagent's " +
+            "current turn — it takes effect before the task's next model request. Use it when user feedback or new " +
+            "information should change the subtask's direction. Use subagent_cancel when the task must stop instead.",
+        parameters: Type.Object({
+            taskId: Type.String({ description: "Task id from a background subagent_run ticket" }),
+            text: Type.String({
+                minLength: 1,
+                description: `Bounded steering message (at most ${SUBAGENT_MAILBOX_MAX_MESSAGE_BYTES} utf-8 bytes), delivered before the task's next model request`,
             }),
-            execute: async (first, second) => {
-                const input = objectInput(first, second);
-                const taskId = typeof input.taskId === "string" ? input.taskId : "";
-                if (taskId.trim() === "") {
-                    throw new SubagentDelegateError("subagent_invalid_input", "subagent_cancel requires a taskId");
-                }
-                const reason = typeof input.reason === "string" && input.reason.trim() !== "" ? input.reason : undefined;
-                const result = await runtime.cancelById(taskId, { owner: capabilityManifest.id, parentSessionId: session.getSessionId() }, reason);
-                return result.outcome === "not_found"
-                    ? { outcome: "not_found", taskId }
-                    : { outcome: result.outcome, taskId, status: result.status };
-            },
-        })
-        : undefined;
+        }),
+        execute: async (first, second) => {
+            const input = objectInput(first, second);
+            const taskId = typeof input.taskId === "string" ? input.taskId : "";
+            const text = typeof input.text === "string" ? input.text : "";
+            if (taskId.trim() === "" || text.trim() === "") {
+                throw new SubagentDelegateError("subagent_invalid_input", "subagent_steer requires a taskId and non-empty text");
+            }
+            if (Buffer.byteLength(text, "utf8") > SUBAGENT_MAILBOX_MAX_MESSAGE_BYTES) {
+                throw new SubagentDelegateError("subagent_message_too_large", `subagent_steer text exceeds ${SUBAGENT_MAILBOX_MAX_MESSAGE_BYTES} utf-8 bytes`);
+            }
+            try {
+                await runtime.steer(taskId, text, {
+                    owner: capabilityManifest.id,
+                    parentSessionId: session.getSessionId(),
+                });
+            }
+            catch (error) {
+                mapCommunicationError(error);
+            }
+            return { delivered: true, taskId };
+        },
+    });
     /**
-     * 父→子续跑（D-060 S4，默认关）：对**已终态且已落盘**的子会话按 sessionId 继续
-     * 提交一轮任务（同一份 JSONL 续写，多轮子任务）。血缘作用域由宿主会话回读器判定，
-     * 活跃任务占用以 `subagent_session_busy` 拒绝。shared 与 pooled 都支持——pooled 下
+     * 父→子续跑（D-060 S4）：对**已终态且已落盘**的子会话按 sessionId 继续提交一轮
+     * 任务（同一份 JSONL 续写，多轮子任务）。血缘作用域由宿主会话回读器判定，活跃
+     * 任务占用以 `subagent_session_busy` 拒绝。shared 与 pooled 都支持——pooled 下
      * resume 键随 metadata 过线，runner 打开既有会话文件续写。
+     * D-060 裁决 15（2026-10-03）起无条件注册（开关形态退役）。
      */
-    const resumeTool = communication.resume === true
-        ? api.registerTool({
-            name: "subagent_resume",
-            label: "Resume a subagent",
-            description: "Continue a finished subagent session by its sessionId: submit one more prompt into the same persisted " +
-                "transcript (multi-turn subtask) and get the bounded terminal projection, like subagent_run for one task.",
-            parameters: Type.Object({
-                sessionId: Type.String({ description: "Child session id of a finished subagent task" }),
-                prompt: Type.String({ minLength: 1, description: "Follow-up prompt for the continued session" }),
-            }),
-            execute: async (first, second) => {
-                const input = objectInput(first, second);
-                const sessionId = typeof input.sessionId === "string" ? input.sessionId : "";
-                const prompt = typeof input.prompt === "string" ? input.prompt : "";
-                if (sessionId === "" || prompt.trim() === "") {
-                    throw new SubagentDelegateError("subagent_invalid_input", "subagent_resume requires sessionId and prompt");
-                }
-                const reader = agents?.session;
-                if (reader === undefined) {
-                    throw new SubagentDelegateError("subagent_profile_not_applied", "this host exposes no session reader; resume cannot verify the session scope");
-                }
-                const view = await reader(sessionId);
-                if (view === undefined) {
-                    throw new SubagentDelegateError("subagent_unknown_session", `no child session ${sessionId} under this parent`);
-                }
-                const requester = { owner: capabilityManifest.id, parentSessionId: session.getSessionId() };
-                const active = runtime.findBySession(sessionId, requester);
-                if (active !== undefined && !active.settled) {
-                    throw new SubagentDelegateError("subagent_session_busy", `session ${sessionId} still has an unsettled task (${active.taskId}); steer or wait instead`);
-                }
-                let handle;
-                try {
-                    handle = await runtime.submit({
-                        prompt,
-                        metadata: {
-                            [AGENT_TASK_PARENT_SESSION_KEY]: session.getSessionId(),
-                            [AGENT_TASK_RESUME_SESSION_KEY]: sessionId,
-                        },
-                    });
-                }
-                catch (error) {
-                    throw new SubagentDelegateError("subagent_submit_rejected", errorText(error));
-                }
-                const record = await handle.drain({ timeoutMs: taskTimeoutMs });
-                return { tasks: [projectRecord(record)] };
-            },
-        })
-        : undefined;
+    const resumeTool = api.registerTool({
+        name: "subagent_resume",
+        label: "Resume a subagent",
+        description: "Continue a finished subagent session by its sessionId: submit one more prompt into the same persisted " +
+            "transcript (multi-turn subtask) and get the bounded terminal projection, like subagent_run for one task.",
+        parameters: Type.Object({
+            sessionId: Type.String({ description: "Child session id of a finished subagent task" }),
+            prompt: Type.String({ minLength: 1, description: "Follow-up prompt for the continued session" }),
+        }),
+        execute: async (first, second) => {
+            const input = objectInput(first, second);
+            const sessionId = typeof input.sessionId === "string" ? input.sessionId : "";
+            const prompt = typeof input.prompt === "string" ? input.prompt : "";
+            if (sessionId === "" || prompt.trim() === "") {
+                throw new SubagentDelegateError("subagent_invalid_input", "subagent_resume requires sessionId and prompt");
+            }
+            const reader = agents?.session;
+            if (reader === undefined) {
+                throw new SubagentDelegateError("subagent_profile_not_applied", "this host exposes no session reader; resume cannot verify the session scope");
+            }
+            const view = await reader(sessionId);
+            if (view === undefined) {
+                throw new SubagentDelegateError("subagent_unknown_session", `no child session ${sessionId} under this parent`);
+            }
+            const requester = { owner: capabilityManifest.id, parentSessionId: session.getSessionId() };
+            const active = runtime.findBySession(sessionId, requester);
+            if (active !== undefined && !active.settled) {
+                throw new SubagentDelegateError("subagent_session_busy", `session ${sessionId} still has an unsettled task (${active.taskId}); steer or wait instead`);
+            }
+            let handle;
+            try {
+                handle = await runtime.submit({
+                    prompt,
+                    metadata: {
+                        [AGENT_TASK_PARENT_SESSION_KEY]: session.getSessionId(),
+                        [AGENT_TASK_RESUME_SESSION_KEY]: sessionId,
+                    },
+                });
+            }
+            catch (error) {
+                throw new SubagentDelegateError("subagent_submit_rejected", errorText(error));
+            }
+            const record = await handle.drain({ timeoutMs: taskTimeoutMs });
+            return { tasks: [projectRecord(record)] };
+        },
+    });
     /**
      * 子会话盘点（D-060 模型面）：列出**本会话自己的**子代理会话（最近活动倒序、
      * 有界），并用调度器记录富化活跃/终态信息。宿主注入 `agents.list` 才注册；
@@ -1377,10 +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 === undefined ? [] : [cancelTool]),
-        ...(resumeTool === undefined ? [] : [resumeTool]),
+        cancelTool,
+        steerTool,
+        resumeTool,
+        roleSetTool,
+        roleListTool,
+        roleRemoveTool,
+        rolesCommand,
         ...(listTool === undefined ? [] : [listTool]),
         // 子侧通信面（D-060 S4/S5）：获准自建会话两面并存（向下委派 + 向父上抛/兄弟消息）。
         ...childTools,