@ai-agent-forge/plugin-subagent-delegate 0.85.0

package/dist/delegate.js

@@ -0,0 +1,1376 @@
+/**
+ * First-party builtin subagent-delegate capability: the first production
+ * orchestrator over the plugin-level `SubagentRuntime` (D-044).
+ *
+ * The capability consumes only the public face — `session`, `agents`,
+ * `sessionAbortSignal` and `tools` — and owns exactly one scheduler instance
+ * per plugin load. It adds no scheduling policy of its own: queue, admission,
+ * budgets, terminal states and the parent cancel fence all stay in the
+ * scheduler; this module is the model-facing `subagent_run` tool plus a bounded
+ * result projection (status / reason codes / message counts / short summary).
+ * Raw child messages never enter the tool result (context budget spec).
+ *
+ * The scheduler's deadline fence is tick-driven by design (no hidden timers),
+ * and this consumer has no tick driver of its own, so the tool exposes no
+ * `deadlineMs` parameter: a bound that nothing enforces would be a false
+ * affordance. Wait bounds are `taskTimeoutMs` (drain) and the host's
+ * `limits.drainTimeoutMs` inside the scheduler.
+ *
+ * 迁自宿主 `src/capabilities/subagent-delegate.ts`（D-075 S4 第三批拆包）。除 import
+ * 来源外保持宿主行为：公共契约（agent-task 键/档案、通信接线、血缘读取、快照）改自
+ * plugin-sdk；信箱类型/错误改自 @agent-forge/protocol；调度器与 runner 模块改包内
+ * 相对路径。三处语义收敛见 `SubagentDelegateCapabilityOptions` 与 createCapability
+ * 内的迁移注记（agentDir 单源、runnerEntryAuto 驱动自动池化、lineage 深度经 SDK 读取）。
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_TASK_CHILD_PROFILE_KEY, AGENT_TASK_PARENT_SESSION_KEY, AGENT_TASK_PARENT_TRACE_KEY, AGENT_TASK_RESUME_SESSION_KEY, createDisposableRegistration, detachedSessionSnapshot, EXPERIMENTAL_PUBLIC_API_VERSION, parseAgentTaskChildProfileV1, } from "@agent-forge/plugin-sdk";
+import { readAgentSessionLineage } from "@agent-forge/plugin-sdk/session-lineage";
+import { SUBAGENT_MAILBOX_MAX_MESSAGE_BYTES, SubagentMailboxErrorV1, subscribeTaskProgressV1, } from "@agent-forge/protocol/subagent";
+import { Type } from "typebox";
+import { createPooledAgentTaskAdapterV1, } from "./runner-pool.js";
+import { createNodeSubagentRunnerSpawnerV1 } from "./runner-spawn.js";
+import { resolveSelfInvocationV1 } from "./self-invocation.js";
+import { createAgentTaskApiAdapterV1 } from "./shared-adapter.js";
+import { createSubagentRuntime, SubagentRuntimeError, } from "./subagent-runtime.js";
+export const capabilityManifest = {
+    id: "agent-forge.builtin.subagent-delegate",
+    version: "0.1.0",
+    apiVersion: EXPERIMENTAL_PUBLIC_API_VERSION,
+    // `agents` 是可选能力：runner 的叶子会话刻意关闭 agent tasks（enableAgentTasks: false），
+    // 此时本能力"不适用"而非"加载失败"，缺失时静默不注册工具，避免每个叶子会话刷拒绝警告。
+    requiredCapabilities: ["session", "tools"],
+    optionalCapabilities: ["agents"],
+    /**
+     * 用户可配置默认值（D-044 §6 四层归属的 Profile/capability 配置层）：
+     * 经 agent-dir 配置通道 `<agentDir>/capabilities/builtin.subagent-delegate.json`
+     * 浅合并覆盖；宿主显式 options 优先级最高；非法值在装载时 fail fast。
+     */
+    config: {
+        maxConcurrentSubagents: 8,
+        maxQueueDepth: 200,
+        maxPromptBytes: 65536,
+        maxMetadataBytes: 16384,
+        maxResultBytes: 524288,
+        maxMessages: 2000,
+        drainTimeoutMs: 30000,
+        maxRetainedRecords: 256,
+        maxTasksPerCall: 4,
+        taskTimeoutMs: 300000,
+        // pooled 模式（D-045）：0 = 关闭（默认，shared 形态，零额外进程）。
+        runnerMaxProcesses: 0,
+        runnerMaxSessionsPerRunner: 8,
+        runnerIdleTimeoutMs: 300000,
+        runnerSweepIntervalMs: 60000,
+        runnerEntryAuto: false,
+    },
+};
+// 通信面的宿主接线 `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;
+}
+/** 把宿主/调度器/信箱的结构化错误映射为工具面的同码委托错误（保留原始 message）。 */
+function mapCommunicationError(error) {
+    if (error instanceof SubagentMailboxErrorV1) {
+        throw new SubagentDelegateError(error.code, error.message);
+    }
+    if (error instanceof SubagentRuntimeError &&
+        (error.code === "subagent_unknown_task" ||
+            error.code === "subagent_not_running" ||
+            error.code === "subagent_steer_unsupported")) {
+        throw new SubagentDelegateError(error.code, error.message);
+    }
+    throw error;
+}
+export class SubagentDelegateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SubagentDelegateError";
+        this.code = code;
+    }
+}
+/**
+ * 出厂种子（仅用于首次落盘，不是运行期定义）：默认方案关联 explore / reviewer，
+ * 因此新装环境开箱即用；用户改文件即生效，删文件则该关联成为 dangling 诊断。
+ */
+const FACTORY_ROLE_SEEDS = Object.freeze([
+    Object.freeze({
+        id: "explore",
+        description: "Read-only explorer: locates code and reports file:line evidence",
+        instructions: "You are an exploration subagent. Find the relevant code, configuration or documentation and report concrete " +
+            "evidence as file:line references with a one-line note per hit. Do not modify any file and do not run commands " +
+            "with side effects. Answer with findings first, then the smallest set of next steps.",
+    }),
+    Object.freeze({
+        id: "reviewer",
+        description: "Code reviewer: reads a diff or change set and reports findings and risks",
+        instructions: "You are a code-review subagent. Read the change set you are given (diff, files or description) and report " +
+            "findings ordered by severity: correctness first, then contract/regression risk, then clarity. For each finding " +
+            "give the location, why it is wrong or risky, and the smallest fix. Do not modify files. State explicitly when " +
+            "you found nothing in a category instead of inventing issues.",
+    }),
+]);
+const ROLE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+const ROLE_DESCRIPTION_CHARS = 200;
+const ROLE_INSTRUCTIONS_CHARS = 8000;
+/** 角色数量与"菜单"总长上限：菜单是主代理工具描述的一部分，必须有界。 */
+const ROLE_COUNT_LIMIT = 16;
+const ROLE_MENU_CHARS = 2000;
+const ROLE_KNOWN_KEYS = [
+    "description",
+    "instructions",
+    "model",
+    "thinkingLevel",
+    "tools",
+    "mode",
+    "systemPromptAppend",
+    "parentView",
+];
+/** 用户角色目录（agentDir 下），与 `<agentDir>/capabilities/` 并列。 */
+const ROLE_CATALOG_DIR = "roles";
+function validateRoleDefinition(id, value, origin) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${origin} must be an object with description and instructions`);
+    }
+    const fields = value;
+    for (const key of Object.keys(fields)) {
+        if (!ROLE_KNOWN_KEYS.includes(key)) {
+            throw new Error(`${origin}.${key} is not a recognized role field (known: ${ROLE_KNOWN_KEYS.join(", ")})`);
+        }
+    }
+    const description = fields.description;
+    if (typeof description !== "string" || description.trim() === "" || description.length > ROLE_DESCRIPTION_CHARS) {
+        throw new Error(`${origin}.description must be a non-empty string of at most ${ROLE_DESCRIPTION_CHARS} chars, got ` +
+            JSON.stringify(description));
+    }
+    const instructions = fields.instructions;
+    if (typeof instructions !== "string" ||
+        instructions.trim() === "" ||
+        instructions.length > ROLE_INSTRUCTIONS_CHARS) {
+        throw new Error(`${origin}.instructions must be a non-empty string of at most ${ROLE_INSTRUCTIONS_CHARS} chars`);
+    }
+    // 档案字段交给公共解析器校验（类型/范围/未知键都在那里拦），错误文本带上文件来源。
+    const profileInput = { version: 1, roleId: id };
+    for (const key of ["model", "thinkingLevel", "tools", "mode", "systemPromptAppend"]) {
+        if (fields[key] !== undefined)
+            profileInput[key] = fields[key];
+    }
+    const hasProfile = Object.keys(profileInput).length > 1;
+    let profile;
+    if (hasProfile) {
+        const parsed = parseAgentTaskChildProfileV1(profileInput);
+        if (!parsed.ok)
+            throw new Error(`${origin}: ${parsed.message}`);
+        profile = parsed.profile;
+    }
+    const parentView = fields.parentView;
+    if (parentView !== undefined && typeof parentView !== "boolean") {
+        throw new Error(`${origin}.parentView must be a boolean`);
+    }
+    return {
+        id,
+        description,
+        instructions,
+        ...(profile === undefined ? {} : { profile }),
+        ...(parentView === true ? { parentView: true } : {}),
+    };
+}
+/**
+ * 解析当前方案的角色目录（**全部来自磁盘**，无编译内定义）。装载期一次性完成，
+ * 任何会让"配置了但没生效"的情况都显式失败：
+ * - 被关联 + 文件存在但非法 → 抛错（指名文件）；
+ * - 被关联但目录里没有该 id → dangling（诊断，角色不可见），调用该名走 `subagent_unknown_role`；
+ * - 未被关联的坏文件只进诊断：别的方案不该被一个用不到的文件拖垮；
+ * - 暴露集受 16 个 / 2000 字符上限约束（菜单是主代理工具描述的一部分）。
+ */
+export function resolveSubagentRoleCatalog(options) {
+    const associated = [...new Set(options.associations)];
+    const roles = new Map();
+    const dangling = [];
+    const brokenUnassociated = [];
+    const catalogDir = join(options.agentDir, ROLE_CATALOG_DIR);
+    let entries = [];
+    try {
+        entries = readdirSync(catalogDir).filter((name) => name.endsWith(".json"));
+    }
+    catch {
+        // 目录不存在（未种子化/未配置）是正常状态。
+        entries = [];
+    }
+    for (const entry of entries) {
+        const id = entry.slice(0, -".json".length);
+        if (!ROLE_ID_PATTERN.test(id))
+            continue;
+        const origin = `${catalogDir}/${entry}`;
+        const isAssociated = associated.includes(id);
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(catalogDir, entry), "utf8"));
+        }
+        catch (error) {
+            if (isAssociated) {
+                throw new Error(`subagent role "${id}" is associated by this suite but ${origin} is unreadable`, {
+                    cause: error,
+                });
+            }
+            brokenUnassociated.push(id);
+            continue;
+        }
+        let role;
+        try {
+            role = validateRoleDefinition(id, parsed, origin);
+        }
+        catch (error) {
+            if (isAssociated)
+                throw error;
+            brokenUnassociated.push(id);
+            continue;
+        }
+        if (isAssociated && role !== undefined)
+            roles.set(id, role);
+    }
+    for (const id of associated) {
+        if (!ROLE_ID_PATTERN.test(id)) {
+            throw new Error(`suite associations.roles entry ${JSON.stringify(id)} is not a valid role id (expect lowercase [a-z0-9_-], ` +
+                "max 32 chars)");
+        }
+        if (!roles.has(id))
+            dangling.push(id);
+    }
+    if (roles.size > ROLE_COUNT_LIMIT) {
+        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);
+    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)");
+    }
+    return { roles, dangling: Object.freeze(dangling), brokenUnassociated: Object.freeze(brokenUnassociated) };
+}
+/** 角色文件名（`<agentDir>/roles/<id>.json`），供种子与目录与文档共用一处。 */
+export function subagentRoleCatalogPath(agentDir, id) {
+    return join(agentDir, ROLE_CATALOG_DIR, `${id}.json`);
+}
+/**
+ * 出厂种子落盘（仅补缺，绝不覆盖既有文件）：默认方案关联 explore/reviewer，
+ * 因此新环境开箱即用；这两个文件与用户自己写的角色完全同权——改文件即生效，
+ * 删文件使关联成为 dangling 诊断。引擎运行期从不回退到编译内的角色定义。
+ */
+export function seedFactoryRoleCatalog(agentDir) {
+    const dir = join(agentDir, ROLE_CATALOG_DIR);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        return; // 不可写（只读 agentDir）：角色可选，不阻断启动。
+    }
+    for (const role of FACTORY_ROLE_SEEDS) {
+        const path = subagentRoleCatalogPath(agentDir, role.id);
+        if (existsSync(path))
+            continue;
+        try {
+            writeFileSync(path, `${JSON.stringify({ description: role.description, instructions: role.instructions }, null, 2)}\n`, {
+                encoding: "utf8",
+                flag: "wx",
+            });
+        }
+        catch {
+            // 并发种子化或只读目录：已在磁盘上或不需要，保持现状。
+        }
+    }
+}
+/** 父投影上限：目标文本与工具面名单都取小值（这是"背景"，不是父上下文回灌）。 */
+const PARENT_VIEW_GOAL_CHARS = 2000;
+const PARENT_VIEW_TOOL_LIMIT = 40;
+/** 从父会话消息里取最后一条用户文本（有界），作为"父当前目标"。 */
+function lastUserText(messages, limit) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (typeof message !== "object" || message === null)
+            continue;
+        const record = message;
+        if (record.role !== "user")
+            continue;
+        const raw = typeof record.content === "string"
+            ? record.content
+            : Array.isArray(record.content)
+                ? record.content.map((part) => part.text ?? "").join("")
+                : "";
+        const trimmed = raw.trim();
+        if (trimmed === "")
+            continue;
+        return trimmed.length <= limit ? trimmed : `${trimmed.slice(0, limit)}…`;
+    }
+    return undefined;
+}
+/**
+ * 子读父（D-060 §4）：父会话的**有界投影**——sessionId、当前目标（最后一条用户文本，截断）、
+ * 工具面名单。默认关闭；开启后拼在角色指令与任务之间。父历史全文永不进入子会话。
+ */
+function composeParentView(session, parentSessionId) {
+    const goal = session === undefined ? undefined : lastUserText(session.getMessages(), PARENT_VIEW_GOAL_CHARS);
+    const tools = session?.getActiveTools?.() ?? [];
+    const toolList = tools.slice(0, PARENT_VIEW_TOOL_LIMIT).join(", ");
+    return [
+        "Parent context (bounded projection; the parent's full history is not available to you):",
+        `- parent session: ${parentSessionId}`,
+        ...(goal === undefined ? [] : [`- current goal: ${goal}`]),
+        ...(toolList === "" ? [] : [`- parent tools: ${toolList}`]),
+    ].join("\n");
+}
+/**
+ * 角色框定：角色指令在上、任务在下，任务原文原样保留（子会话看不到父会话历史，
+ * 因此这段文本是它唯一的"我是谁 + 做什么"来源）。组装后的字节数仍走 submit 侧
+ * maxPromptBytes 预算，超限按预算拒绝而不是静默截断。
+ */
+function composeRolePrompt(role, prompt) {
+    return `${role.instructions}\n\nTask:\n${prompt}`;
+}
+/** context 硬边界（设计 §2.3）：两个列表 ≤10 项、note ≤200 字符、path/command ≤500 字符。 */
+const CONTEXT_LIST_MAX_ITEMS = 10;
+const CONTEXT_NOTE_MAX_CHARS = 200;
+const CONTEXT_PATH_MAX_CHARS = 500;
+const CONTEXT_COMMAND_MAX_CHARS = 500;
+function parseContextNote(value, origin) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length > CONTEXT_NOTE_MAX_CHARS) {
+        throw new SubagentDelegateError("subagent_invalid_input", `${origin} must be a string of at most ${CONTEXT_NOTE_MAX_CHARS} chars`);
+    }
+    return value === "" ? undefined : value;
+}
+function parseContextList(value, label, parseEntry) {
+    if (!Array.isArray(value)) {
+        throw new SubagentDelegateError("subagent_invalid_input", `subagent_run context.${label} must be an array`);
+    }
+    if (value.length > CONTEXT_LIST_MAX_ITEMS) {
+        throw new SubagentDelegateError("subagent_invalid_input", `subagent_run context.${label} accepts at most ${CONTEXT_LIST_MAX_ITEMS} entries; received ${value.length}`);
+    }
+    return value.map((entry, index) => {
+        const origin = `subagent_run context.${label}[${index}]`;
+        if (!isPlainRecord(entry)) {
+            throw new SubagentDelegateError("subagent_invalid_input", `${origin} must be an object`);
+        }
+        return parseEntry(entry, origin);
+    });
+}
+/**
+ * 解析工具入参里的 `context`（形状/边界违规都以 `subagent_invalid_input` 整体拒绝）；
+ * 两个列表皆空时归一化为 undefined——与 context 缺省同一路径，整块不渲染。
+ */
+function parseDelegateContext(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainRecord(value)) {
+        throw new SubagentDelegateError("subagent_invalid_input", "subagent_run context must be an object");
+    }
+    const anchors = value.anchors === undefined
+        ? undefined
+        : parseContextList(value.anchors, "anchors", (entry, origin) => {
+            const path = entry.path;
+            if (typeof path !== "string" || path === "" || path.length > CONTEXT_PATH_MAX_CHARS) {
+                throw new SubagentDelegateError("subagent_invalid_input", `${origin}.path must be a non-empty string of at most ${CONTEXT_PATH_MAX_CHARS} chars`);
+            }
+            const rawLine = entry.line;
+            const line = rawLine === undefined
+                ? undefined
+                : (() => {
+                    if (typeof rawLine !== "number" || !Number.isInteger(rawLine) || rawLine < 1) {
+                        throw new SubagentDelegateError("subagent_invalid_input", `${origin}.line must be a positive integer`);
+                    }
+                    return rawLine;
+                })();
+            const note = parseContextNote(entry.note, `${origin}.note`);
+            return {
+                path,
+                ...(line === undefined ? {} : { line }),
+                ...(note === undefined ? {} : { note }),
+            };
+        });
+    const failedAttempts = value.failedAttempts === undefined
+        ? undefined
+        : parseContextList(value.failedAttempts, "failedAttempts", (entry, origin) => {
+            const command = entry.command;
+            if (typeof command !== "string" || command === "" || command.length > CONTEXT_COMMAND_MAX_CHARS) {
+                throw new SubagentDelegateError("subagent_invalid_input", `${origin}.command must be a non-empty string of at most ${CONTEXT_COMMAND_MAX_CHARS} chars`);
+            }
+            const note = parseContextNote(entry.note, `${origin}.note`);
+            return { command, ...(note === undefined ? {} : { note }) };
+        });
+    if ((anchors?.length ?? 0) === 0 && (failedAttempts?.length ?? 0) === 0)
+        return undefined;
+    return {
+        ...(anchors === undefined ? {} : { anchors }),
+        ...(failedAttempts === undefined ? {} : { failedAttempts }),
+    };
+}
+/**
+ * 把 context 确定性渲染为子会话首条 prompt 的头部块（模板逐字，设计 §2.3）：line
+ * 缺省只输出 path、note 缺省省略 " — <note>"、某列表为空不渲染对应小节、两个列表
+ * 皆空（context 已在解析侧归一化）返回 undefined——子会话 prompt 与现状逐字节一致。
+ */
+function renderDelegateContext(context) {
+    if (context === undefined)
+        return undefined;
+    const lines = ["[parent context anchors — may be stale; verify against current files]"];
+    const anchors = context.anchors ?? [];
+    if (anchors.length > 0) {
+        lines.push("Key locations:");
+        for (const anchor of anchors) {
+            const location = anchor.line === undefined ? anchor.path : `${anchor.path}:${anchor.line}`;
+            lines.push(`- ${location}${anchor.note === undefined ? "" : ` — ${anchor.note}`}`);
+        }
+    }
+    const failedAttempts = context.failedAttempts ?? [];
+    if (failedAttempts.length > 0) {
+        lines.push("Tried and failed:");
+        for (const attempt of failedAttempts) {
+            lines.push(`- \`${attempt.command}\`${attempt.note === undefined ? "" : ` — ${attempt.note}`}`);
+        }
+    }
+    return lines.length === 1 ? undefined : lines.join("\n");
+}
+/**
+ * 核验档案是否真的落到了子会话上：工具面必须是请求白名单的子集，模型必须等于请求值，
+ * 模式请求 `readonly` 时必须已是只读。宿主不暴露可核验事实（getActiveTools/getModel）
+ * 也算未落地——"要求了但无法证明"与"没要求"对上层是同一种风险。
+ */
+function verifyChildProfileApplied(host, requested) {
+    const parsed = parseAgentTaskChildProfileV1(requested);
+    if (!parsed.ok)
+        return `child task profile is invalid: ${parsed.message}`;
+    const profile = parsed.profile;
+    const session = host.session;
+    if (profile.tools !== undefined || profile.mode === "readonly") {
+        const active = session.getActiveTools?.();
+        if (active === undefined) {
+            return "host does not expose getActiveTools(); the requested tool narrowing cannot be verified";
+        }
+        if (profile.tools !== undefined) {
+            const extra = active.filter((name) => !profile.tools?.includes(name));
+            if (extra.length > 0) {
+                return `child session kept tools outside the requested allowlist: ${extra.join(", ")}`;
+            }
+        }
+    }
+    if (profile.model !== undefined) {
+        const model = session.getModel?.();
+        if (model === undefined) {
+            return "host does not expose getModel(); the requested model cannot be verified";
+        }
+        if (model.id !== profile.model) {
+            return `child session is on model ${JSON.stringify(model.id)} instead of the requested ${JSON.stringify(profile.model)}`;
+        }
+    }
+    return undefined;
+}
+function resolveRole(value, roles) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new SubagentDelegateError("subagent_invalid_input", "subagent_run role must be a non-empty string");
+    }
+    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(", ")));
+    }
+    return role;
+}
+/** 单条 summary 的字符上限（上下文预算：只回摘要，不回 messages 原文）。 */
+const SUMMARY_CHARS = 200;
+/** `subagent_result` 默认/上限返回条数（有界回读，绝不默认回灌全文）。 */
+const RESULT_READ_DEFAULT_MESSAGES = 20;
+const RESULT_READ_MAX_MESSAGES = 50;
+/** `subagent_result` 的有界等待上限（后台结算收割），默认 0 = 只查一次。 */
+const RESULT_READ_MAX_WAIT_MS = 120_000;
+/** UTF-8 字节数（回读信封如实报告体积）。 */
+function utf8ByteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+const DEFAULT_MAX_TASKS_PER_CALL = 4;
+const DEFAULT_TASK_TIMEOUT_MS = 300_000;
+/**
+ * 配置通道读取（manifest 默认 + agent-dir 文件合并后的 `api.config`）：
+ * 非整数/低于下限即 fail fast 并指名键，不让错误配置静默生效。
+ */
+function configInt(api, key, min) {
+    const value = api.config[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min) {
+        throw new Error(`subagent-delegate config ${key} must be an integer >= ${min}, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/** options > config > 默认，最终值仍需通过同一套下限校验。 */
+function resolveInt(explicit, configured, fallback, min, label) {
+    const value = explicit ?? configured ?? fallback;
+    if (!Number.isInteger(value) || value < min) {
+        throw new Error(`subagent-delegate ${label} must be an integer >= ${min}, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/**
+ * 宽松调用兼容（对齐 goal/plan/todo-set）：标准签名的第二参为 params，直接调用时第一参即 params。
+ * 生产装配向 runtime invoke 面注入 toolExecutionContext 作为 execute 的第二参（公共契约），
+ * 因此"第二参非 undefined 即输入"的判定会把 context 误当输入（prompts 读成 undefined）。
+ * 改按形状判定：第一参是普通对象即取第一参，否则看第二参。
+ */
+function objectInput(first, second) {
+    const primary = isPlainRecord(first) ? first : second;
+    if (!isPlainRecord(primary)) {
+        throw new SubagentDelegateError("subagent_invalid_input", "subagent_run input must be an object");
+    }
+    return primary;
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readPrompts(value, maxTasksPerCall) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new SubagentDelegateError("subagent_invalid_input", "subagent_run requires a non-empty prompts array");
+    }
+    const prompts = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || entry.trim() === "") {
+            throw new SubagentDelegateError("subagent_invalid_input", "subagent_run prompts must be non-empty strings");
+        }
+        prompts.push(entry);
+    }
+    if (prompts.length > maxTasksPerCall) {
+        throw new SubagentDelegateError("subagent_batch_too_large", `subagent_run accepts at most ${maxTasksPerCall} prompts per call; received ${prompts.length}`);
+    }
+    return prompts;
+}
+function errorText(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    try {
+        const serialized = JSON.stringify(error);
+        return serialized === undefined ? String(error) : serialized;
+    }
+    catch {
+        return String(error);
+    }
+}
+/** 结构化原因码：优先取错误自带的 code（调度器/适配器的结构化错误），否则表达为 submit 拒绝。 */
+function reasonCodeOf(error) {
+    if (error && typeof error === "object" && typeof error.code === "string") {
+        return error.code;
+    }
+    return "subagent_submit_rejected";
+}
+/** 文本块抽取：content 为字符串或 text 块数组；无文本返回 undefined。 */
+function messageText(content) {
+    if (typeof content === "string")
+        return content === "" ? undefined : content;
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const item of content) {
+        if (!item || typeof item !== "object")
+            continue;
+        const block = item;
+        if (block.type !== "text" || typeof block.text !== "string")
+            continue;
+        parts.push(block.text);
+    }
+    const text = parts.join("");
+    return text === "" ? undefined : text;
+}
+/** 最后一条带文本的 assistant 消息 → 有界 summary；找不到（或全无文本）省略。 */
+function assistantSummary(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (!message || typeof message !== "object")
+            continue;
+        const record = message;
+        if (record.role !== "assistant" && record.type !== "assistant")
+            continue;
+        const text = messageText(record.content);
+        if (text === undefined)
+            continue;
+        return text.length <= SUMMARY_CHARS ? text : text.slice(0, SUMMARY_CHARS);
+    }
+    return undefined;
+}
+function projectRecord(record) {
+    const summary = assistantSummary(record.messages);
+    return {
+        taskId: record.taskId,
+        status: record.status,
+        ...(record.reasonCode === undefined ? {} : { reasonCode: record.reasonCode }),
+        ...(record.reason === undefined ? {} : { reason: record.reason }),
+        ...(record.truncated ? { truncated: true } : {}),
+        messageCount: record.messages.length,
+        ...(record.sessionId === undefined || record.sessionId === "" ? {} : { sessionId: record.sessionId }),
+        ...(summary === undefined ? {} : { summary }),
+    };
+}
+/**
+ * 血缘深度（承载退役切片 2，Option A）：沿 S2 落盘头行的 `parentAgentSession` 上行，
+ * 返回本会话的祖先层数。root（无头行/非落盘会话）返回 undefined——不设限。
+ * 最多上行走 `maxWalk` 步（有界，防环按步数截断）。
+ *
+ * 迁移注记（D-075 S4 第三批）：宿主实现的逐头回读（`readAgentSession` 循环）改为
+ * plugin-sdk 的 `readAgentSessionLineage`——同一落盘契约的只读首行实现。语义对齐点：
+ * `ancestors` 只含**可解析**的祖先，而宿主 depth 对"父指针存在但父会话未落盘"的
+ * 最后一条边也计数（root 在内存里、文件不可达是常态），因此 dangling 边补 +1；
+ * `truncated`（走满 maxWalk 步仍有可解析父）时 ancestors.length 与宿主的 maxWalk
+ * 返回值一致。
+ */
+function lineageDepth(sessionId, agentDir, maxWalk) {
+    const lineage = readAgentSessionLineage(agentDir, sessionId, maxWalk);
+    if (lineage.self === undefined)
+        return undefined;
+    const last = lineage.ancestors.at(-1) ?? lineage.self;
+    const danglingParent = last.parentAgentSession !== undefined && last.parentAgentSession !== last.sessionId;
+    return lineage.ancestors.length + (danglingParent && !lineage.truncated ? 1 : 0);
+}
+/**
+ * 第一方编排 capability：一个调度器实例 + `subagent_run` 工具 + 释放登记。
+ * 只消费公共 API（session/agents/sessionAbortSignal/tools），不 import core 内部私有模块。
+ */
+export function createCapability(api, options) {
+    const session = api.session;
+    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);
+    const wiring = options?.communicationWiring;
+    // 子侧通信面（子→父 / 子↔子）：只要宿主接线了 post 通道且配置开启就注册——
+    // 叶子会话（无 agents）只拿这一面；获准自建会话（D-060 S5，agents 在场）两面都要：
+    // 它既能向下委派（parent face），也仍能向自己的父上抛/收兄弟消息（child face）。
+    const childTools = [];
+    if (wiring?.postEscalate !== undefined && communication.escalate === true) {
+        childTools.push(api.registerTool({
+            name: "subagent_escalate",
+            label: "Escalate to parent",
+            description: "Send one bounded message up to your parent agent. It does NOT interrupt the parent; it is delivered " +
+                "with the parent's next task result. Use it for a blocker or a key finding the task result alone would lose.",
+            parameters: Type.Object({
+                text: Type.String({
+                    minLength: 1,
+                    description: `Message to the parent (at most ${SUBAGENT_MAILBOX_MAX_MESSAGE_BYTES} utf-8 bytes)`,
+                }),
+            }),
+            execute: async (first, second) => {
+                const input = objectInput(first, second);
+                const text = typeof input.text === "string" ? input.text : "";
+                if (text.trim() === "") {
+                    throw new SubagentDelegateError("subagent_invalid_input", "subagent_escalate requires non-empty text");
+                }
+                try {
+                    wiring.postEscalate?.(text);
+                }
+                catch (error) {
+                    mapCommunicationError(error);
+                }
+                return { delivered: true, note: "the parent reads this with its next task result" };
+            },
+        }));
+    }
+    if (wiring?.sendSibling !== undefined && communication.sibling === true) {
+        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.",
+            parameters: Type.Object({
+                to: Type.String({ description: "Recipient child session id" }),
+                text: Type.String({
+                    minLength: 1,
+                    description: `Message (at most ${SUBAGENT_MAILBOX_MAX_MESSAGE_BYTES} utf-8 bytes)`,
+                }),
+            }),
+            execute: async (first, second) => {
+                const input = objectInput(first, second);
+                const to = typeof input.to === "string" ? input.to : "";
+                const text = typeof input.text === "string" ? input.text : "";
+                if (to === "" || text.trim() === "") {
+                    throw new SubagentDelegateError("subagent_invalid_input", "subagent_send requires to and non-empty text");
+                }
+                try {
+                    wiring.sendSibling?.(to, text);
+                }
+                catch (error) {
+                    mapCommunicationError(error);
+                }
+                return { delivered: true };
+            },
+        }), api.registerTool({
+            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.",
+            parameters: Type.Object({
+                limit: Type.Optional(Type.Number({ description: "Max messages to take (1..20, default 10)", minimum: 1, maximum: 20 })),
+            }),
+            execute: async (first, second) => {
+                const input = objectInput(first, second);
+                const requested = input.limit === undefined ? 10 : Number(input.limit);
+                if (!Number.isInteger(requested) || requested < 1 || requested > 20) {
+                    throw new SubagentDelegateError("subagent_invalid_input", "subagent_inbox limit must be an integer in 1..20");
+                }
+                const messages = wiring.drainInbox?.(requested) ?? [];
+                return { messages };
+            },
+        }));
+    }
+    // 调度器限额：options.limits 显式覆盖优先；否则由配置通道逐键取值，缺省回落到调度器默认。
+    const configuredLimits = {
+        maxConcurrentSubagents: configInt(api, "maxConcurrentSubagents", 1),
+        maxQueueDepth: configInt(api, "maxQueueDepth", 1),
+        maxPromptBytes: configInt(api, "maxPromptBytes", 1),
+        maxMetadataBytes: configInt(api, "maxMetadataBytes", 1),
+        maxResultBytes: configInt(api, "maxResultBytes", 1),
+        maxMessages: configInt(api, "maxMessages", 1),
+        drainTimeoutMs: configInt(api, "drainTimeoutMs", 1),
+        maxRetainedRecords: configInt(api, "maxRetainedRecords", 1),
+    };
+    const limits = options?.limits ??
+        (Object.values(configuredLimits).every((value) => value === undefined)
+            ? undefined
+            : configuredLimits);
+    const sessionAbortSignal = api.sessionAbortSignal;
+    /**
+     * adapter 选择（优先级）：宿主显式 adapter > 配置驱动的 pooled runner 池 > 共享模式（裸 primitive）。
+     * pooled 关闭时零额外进程；启用时 entryPath 必须显式给出（不猜安装形态），缺失即装载失败。
+     * 退役切片 1（生产默认 pooled，D-075 S4 第三批收敛）：自动池化旗标不再由宿主 options
+     * 注入，改由既有配置键 `runnerEntryAuto: true` 驱动——未显式配置 `runnerMaxProcesses`/
+     * `runnerEntryPath` 且未注入 spawner 时，若 self-invocation 可解析则自动以池化装配
+     * （默认 2 个 runner、每池 8 会话）；不可解析则保持共享模式。
+     */
+    const pool = (() => {
+        const configuredMaxProcesses = configInt(api, "runnerMaxProcesses", 0);
+        let runnerMaxProcesses = resolveInt(undefined, configuredMaxProcesses, 0, 0, "runnerMaxProcesses");
+        const selfInvocation = resolveSelfInvocationV1();
+        const autoPool = runnerMaxProcesses === 0 &&
+            api.config.runnerEntryAuto === true &&
+            options?.runnerSpawner === undefined &&
+            typeof api.config.runnerEntryPath !== "string";
+        if (autoPool && selfInvocation !== undefined)
+            runnerMaxProcesses = 2;
+        if (runnerMaxProcesses === 0)
+            return undefined;
+        // runner 配置存在即做一致性校验（即使宿主注入了 adapter，错误配置也不得静默）：
+        // 非法值/缺失入口/容量不覆盖并发都在装载期暴露。
+        const maxSessionsPerRunner = resolveInt(undefined, configInt(api, "runnerMaxSessionsPerRunner", 1), 8, 1, "runnerMaxSessionsPerRunner");
+        const idleRunnerTimeoutMs = resolveInt(undefined, configInt(api, "runnerIdleTimeoutMs", 1), 300_000, 1, "runnerIdleTimeoutMs");
+        const idleCheckIntervalMs = resolveInt(undefined, configInt(api, "runnerSweepIntervalMs", 1), 60_000, 1, "runnerSweepIntervalMs");
+        // 有效并发取"已配并发"或调度器默认值：容量校验必须在未显式配置并发时也生效，
+        // 否则池化容量小于默认并发（8）会被静默容忍，直到运行期才以 capacity 错误暴露。
+        const effectiveMaxConcurrent = options?.limits?.maxConcurrentSubagents ?? limits?.maxConcurrentSubagents ?? 8;
+        // spawn 工厂优先用注入；否则要求配置显式给出 runner 入口（装载期校验，不推迟到首次 spawn）。
+        let spawnRunner = options?.runnerSpawner;
+        if (spawnRunner === undefined) {
+            const entryPath = api.config.runnerEntryPath;
+            if (typeof entryPath === "string" && entryPath.trim() !== "") {
+                const nodeArgs = Array.isArray(api.config.runnerNodeArgs)
+                    ? api.config.runnerNodeArgs.filter((value) => typeof value === "string")
+                    : entryPath.endsWith(".ts")
+                        ? ["--experimental-strip-types"]
+                        : [];
+                const spawner = createNodeSubagentRunnerSpawnerV1({ entryPath, nodeArgs });
+                spawnRunner = () => spawner();
+            }
+            else if (autoPool) {
+                // 退役切片 1：CLI 宿主的自动池化——self-invocation 已在上方预检可解析。
+                const self = selfInvocation;
+                const nodeArgs = Array.isArray(api.config.runnerNodeArgs)
+                    ? api.config.runnerNodeArgs.filter((value) => typeof value === "string")
+                    : [...self.nodeArgs];
+                const spawner = createNodeSubagentRunnerSpawnerV1({ entryPath: self.entryPath, nodeArgs });
+                spawnRunner = () => spawner();
+            }
+            else if (api.config.runnerEntryAuto === true) {
+                // 显式开启的零配置路径：把当前进程的启动方式当作 runner 入口（见 self-invocation）。
+                const self = resolveSelfInvocationV1();
+                if (self === undefined) {
+                    throw new Error("subagent-delegate config runnerEntryAuto is enabled but the current process has no script entry " +
+                        "(compiled binaries must set runnerEntryPath explicitly)");
+                }
+                const nodeArgs = Array.isArray(api.config.runnerNodeArgs)
+                    ? api.config.runnerNodeArgs.filter((value) => typeof value === "string")
+                    : [...self.nodeArgs];
+                const spawner = createNodeSubagentRunnerSpawnerV1({ entryPath: self.entryPath, nodeArgs });
+                spawnRunner = () => spawner();
+            }
+            else {
+                throw new Error("subagent-delegate config runnerEntryPath is required when runnerMaxProcesses >= 1 " +
+                    "(or enable runnerEntryAuto to reuse this process's own entry)");
+            }
+        }
+        if (options?.adapter !== undefined)
+            return undefined;
+        // 开发态 runner（TS 引导的 CLI）冷启动可能超过默认 5s 握手预算，宿主可配置放宽。
+        const handshakeTimeoutMs = configInt(api, "runnerHandshakeTimeoutMs", 1);
+        return createPooledAgentTaskAdapterV1({
+            spawnRunner,
+            maxRunnerProcesses: runnerMaxProcesses,
+            maxSessionsPerRunner,
+            idleRunnerTimeoutMs,
+            idleCheckIntervalMs,
+            maxConcurrentSubagents: effectiveMaxConcurrent,
+            ...(handshakeTimeoutMs === undefined ? {} : { handshakeTimeoutMs }),
+            onDiagnostic: (message) => {
+                api.logger?.debug?.(`subagent-delegate runner: ${message}`);
+            },
+        });
+    })();
+    // 桥转换只在 agents 暴露任务面（create）时成立（承载退役切片 2：reader-only 宿主的
+    // agents 只承载回读，不承载委派）。父面 = 宿主 adapter > 配置/自动池 > 桥。
+    const baseAdapter = options?.adapter ?? pool ?? (agents?.create === undefined ? undefined : createAgentTaskApiAdapterV1(agents));
+    // 门控（承载退役）：父面 = 池或宿主 adapter 任一在即可，不再依赖 agents 能力——
+    // runner 叶子带自动池化（退役切片 1）因此同样获得委派父面（嵌套委派，深度硬限兜底）。
+    // 无任何 adapter 时委派不适用：只保留子侧通信面（fail-closed）。
+    if (baseAdapter === undefined) {
+        if (childTools.length === 0) {
+            api.logger?.debug?.("subagent-delegate: no runner pool and no host adapter; delegation tool stays unregistered");
+            return [];
+        }
+        return childTools;
+    }
+    // 配置错误在装载时 fail fast，不让 0/负数静默地拒绝每一次调用或永不超时。
+    const maxTasksPerCall = resolveInt(options?.maxTasksPerCall, configInt(api, "maxTasksPerCall", 1), DEFAULT_MAX_TASKS_PER_CALL, 1, "maxTasksPerCall");
+    const taskTimeoutMs = resolveInt(options?.taskTimeoutMs, configInt(api, "taskTimeoutMs", 1), DEFAULT_TASK_TIMEOUT_MS, 1, "taskTimeoutMs");
+    // 嵌套深度硬限（承载退役切片 2，Option A）：runner 叶子带自动池化后同样获得委派
+    // 父面，递归边界由血缘深度兜底——本会话已是第 maxNestedDepth 层时再委派按
+    // `subagent_depth_exceeded` 结构化拒绝。与 S5 shared 侧的深度上限同一默认（2 层）。
+    const maxNestedDepth = resolveInt(undefined, configInt(api, "maxNestedDepth", 1), 2, 1, "maxNestedDepth");
+    // 每父级累计可创建的子代理总量（承载退役切片 2，Option A；与 S5 shared 侧同一默认
+    // 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");
+    }
+    const backgroundEnabled = api.config.background === true;
+    // 角色目录 + 方案关联在装载期解析：非法文件/非法关联直接失败，不留"配置了但没生效"的假象。
+    const roleCatalog = options?.roles === undefined
+        ? { roles: new Map(), dangling: [], brokenUnassociated: [] }
+        : resolveSubagentRoleCatalog(options.roles);
+    const roles = 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()]
+        .sort((left, right) => (left.id < right.id ? -1 : 1))
+        .map((role) => `${role.id} — ${role.description}`)
+        .join("; ");
+    /**
+     * D-044 §5.6：把支持进度面的 adapter 装饰一层，累计"运行中 step"与最近一条
+     * 摘要，供工具 onUpdate 节流上报父 UI（只回计数与摘要，不回正文）。
+     */
+    const progressState = { steps: 0, last: undefined };
+    const progressUnsubscribes = new Set();
+    const adapter = {
+        create: async (request) => {
+            const requestedProfile = request.metadata?.[AGENT_TASK_CHILD_PROFILE_KEY];
+            const host = await baseAdapter.create(request);
+            // 档案核验：宿主必须把收窄落到了子会话上，且要能自证（getActiveTools/getModel）。
+            // 核验失败 = 上层以为的"只读评审者"没有生效，因此这里就地失败并回收该子会话，
+            // 而不是让它带着比预期更大的权限去跑。
+            if (requestedProfile !== undefined) {
+                const violation = verifyChildProfileApplied(host, requestedProfile);
+                if (violation !== undefined) {
+                    await host.dispose().catch(() => { });
+                    throw new SubagentDelegateError("subagent_profile_not_applied", violation);
+                }
+            }
+            const taskId = host.session.getSessionId();
+            const unsubscribe = subscribeTaskProgressV1(baseAdapter, taskId, (message) => {
+                progressState.steps += 1;
+                if (message !== undefined)
+                    progressState.last = message;
+            });
+            progressUnsubscribes.add(unsubscribe);
+            return host;
+        },
+        ...(baseAdapter.dispose === undefined
+            ? {}
+            : { dispose: async () => void (await baseAdapter.dispose?.()) }),
+    };
+    const runtime = createSubagentRuntime({
+        adapter,
+        owner: capabilityManifest.id,
+        parentSessionId: session.getSessionId(),
+        ...(sessionAbortSignal === undefined ? {} : { parentSignal: sessionAbortSignal }),
+        ...(limits === undefined ? {} : { limits }),
+    });
+    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({
+        name: "subagent_run",
+        label: "Run subagents",
+        description: `Delegate 1..${maxTasksPerCall} independent subagent tasks in one call and return their bounded terminal results. ` +
+            "Each prompt runs in its own isolated child session. Only status, reason codes, message counts and a shortened " +
+            "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)." +
+            (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).",
+                    })),
+                }
+                : {}),
+        },
+        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`);
+                }
+            }
+            // 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,
+                    };
+                }
+            }
+            // 后台委派（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 };
+            }
+            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 }),
+                    };
+                }
+                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) };
+        },
+    });
+    /**
+     * 只读回读工具（D-060 S3）：按 `taskId` 或 `sessionId` 取回**有界**的子会话片段。
+     * - `taskId` → 调度记录（内存/durable，owner+parent 作用域）；
+     * - `sessionId` → 持久化 transcript（宿主注入的会话回读器；未注入时结构化报错）。
+     * 返回默认只给最后 N 条（可调），并如实报告条数/字节/截断——绝不默认回灌全文。
+     */
+    const resultTool = api.registerTool({
+        name: "subagent_result",
+        label: "Read subagent result",
+        description: "Read back a bounded slice of a subagent's session: pass the taskId from subagent_run, or the child's sessionId " +
+            "to read its persisted transcript. Returns at most `maxMessages` trailing entries (default 20) plus counts, " +
+            "byte size and a truncated flag; it never returns the whole transcript by default.",
+        parameters: Type.Object({
+            taskId: Type.Optional(Type.String({ description: "Task id from subagent_run (scheduler record read)" })),
+            sessionId: Type.Optional(Type.String({
+                description: "Child session id (persisted transcript read; requires a host session reader)",
+            })),
+            maxMessages: Type.Optional(Type.Number({ description: "Trailing entries to return (1..50, default 20)", minimum: 1, maximum: 50 })),
+            waitMs: Type.Optional(Type.Number({
+                description: "Bounded wait for a background task to settle, in ms (0..120000, default 0 = check once; " +
+                    "unsettled tasks come back with knownTask/taskStatus instead of the transcript)",
+                minimum: 0,
+                maximum: 120000,
+            })),
+        }),
+        execute: async (first, second) => {
+            const input = objectInput(first, second);
+            const taskId = typeof input.taskId === "string" && input.taskId.trim() !== "" ? input.taskId : undefined;
+            const sessionId = typeof input.sessionId === "string" && input.sessionId.trim() !== "" ? input.sessionId : undefined;
+            const requested = input.maxMessages === undefined ? RESULT_READ_DEFAULT_MESSAGES : Number(input.maxMessages);
+            if (!Number.isInteger(requested) || requested < 1 || requested > RESULT_READ_MAX_MESSAGES) {
+                throw new SubagentDelegateError("subagent_invalid_input", `subagent_result maxMessages must be an integer in 1..${RESULT_READ_MAX_MESSAGES}`);
+            }
+            const waitMs = input.waitMs === undefined ? 0 : Number(input.waitMs);
+            if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > RESULT_READ_MAX_WAIT_MS) {
+                throw new SubagentDelegateError("subagent_invalid_input", `subagent_result waitMs must be an integer in 0..${RESULT_READ_MAX_WAIT_MS}`);
+            }
+            if (taskId === undefined && sessionId === undefined) {
+                throw new SubagentDelegateError("subagent_invalid_input", "subagent_result requires taskId (scheduler record) or sessionId (persisted transcript)");
+            }
+            if (taskId !== undefined) {
+                const requester = {
+                    owner: capabilityManifest.id,
+                    parentSessionId: session.getSessionId(),
+                };
+                // 后台委派（D-060 S6）：waitMs > 0 时有界等待结算；否则查一次。
+                const record = waitMs > 0 ? await runtime.wait(taskId, waitMs, requester) : await runtime.result(taskId, requester);
+                if (record === undefined) {
+                    // 未结算与不存在分开表达：已知任务回当前状态，模型可稍后再取。
+                    const known = runtime.peek(taskId, requester);
+                    return known === undefined
+                        ? { found: false, source: "record", taskId }
+                        : { found: false, source: "record", taskId, knownTask: true, taskStatus: known.status };
+                }
+                const messages = record.messages.slice(-requested);
+                // escalate 上抛（D-060 S4）：按子会话 id 取走并随信封返回（取后即清）。
+                const escalations = wiring?.drainEscalations?.(record.sessionId) ?? [];
+                return {
+                    found: true,
+                    source: "record",
+                    taskId: record.taskId,
+                    sessionId: record.sessionId,
+                    status: record.status,
+                    ...(record.reasonCode === undefined ? {} : { reasonCode: record.reasonCode }),
+                    ...(record.reason === undefined ? {} : { reason: record.reason }),
+                    messageCount: record.messages.length,
+                    returnedMessages: messages.length,
+                    bytes: utf8ByteLength(JSON.stringify(record.messages)),
+                    truncated: record.truncated || messages.length < record.messages.length,
+                    messages: messages.map((message) => detachedSessionSnapshot(message)),
+                    ...(escalations.length === 0 ? {} : { escalations }),
+                };
+            }
+            const reader = agents?.session;
+            if (reader === undefined) {
+                throw new SubagentDelegateError("subagent_profile_not_applied", "this host exposes no session reader; pass taskId instead (or run on a host that injects one)");
+            }
+            const view = await reader(sessionId);
+            if (view === undefined)
+                return { found: false, source: "session", sessionId };
+            const entries = view.entries.slice(-requested);
+            const escalations = wiring?.drainEscalations?.(view.sessionId) ?? [];
+            return {
+                found: true,
+                source: "session",
+                sessionId: view.sessionId,
+                ...(view.agentRole === undefined ? {} : { roleId: view.agentRole }),
+                entryCount: view.entryCount,
+                returnedMessages: entries.length,
+                bytes: view.bytes,
+                truncated: view.truncated || entries.length < view.entryCount,
+                messages: entries.map((entry) => detachedSessionSnapshot(entry)),
+                ...(escalations.length === 0 ? {} : { escalations }),
+            };
+        },
+    });
+    // steer 不设模型面工具（D-060 S4）：`subagent_run` 是阻塞式 drain-to-terminal，
+    // 父模型在工具调用期间不存在"运行中的子任务"窗口——暴露即死 affordance（与
+    // `deadlineMs` 同一纪律）。父→子 steer 走程序面：agents 桥的 `steer`（运行中
+    // 的后台任务）与本调度器的 `steer`/`findBySession` 原语，供编排插件组合。
+    /**
+     * 父→子续跑（D-060 S4，默认关）：对**已终态且已落盘**的子会话按 sessionId 继续
+     * 提交一轮任务（同一份 JSONL 续写，多轮子任务）。血缘作用域由宿主会话回读器判定，
+     * 活跃任务占用以 `subagent_session_busy` 拒绝。shared 与 pooled 都支持——pooled 下
+     * resume 键随 metadata 过线，runner 打开既有会话文件续写。
+     */
+    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;
+    /**
+     * 子会话盘点（D-060 模型面）：列出**本会话自己的**子代理会话（最近活动倒序、
+     * 有界），并用调度器记录富化活跃/终态信息。宿主注入 `agents.list` 才注册；
+     * 读的是落盘目录，父会话跨进程重启后仍能找回自己的子代理。返回的 sessionId
+     * 可直接用于 `subagent_result` / `subagent_resume`。
+     */
+    const listTool = agents?.list === undefined
+        ? undefined
+        : api.registerTool({
+            name: "subagent_list",
+            label: "List subagent sessions",
+            description: "List this session's own subagent sessions (newest activity first) with role, timestamps and transcript " +
+                "size; tasks still in flight are marked active, settled ones carry their terminal status. Read-only. " +
+                "Use a listed sessionId with subagent_result or subagent_resume.",
+            parameters: Type.Object({
+                limit: Type.Optional(Type.Number({ description: "Max entries to return (1..50, default 20)", minimum: 1, maximum: 50 })),
+            }),
+            execute: async (first, second) => {
+                const input = objectInput(first, second);
+                const requested = input.limit === undefined ? 20 : Number(input.limit);
+                if (!Number.isInteger(requested) || requested < 1 || requested > 50) {
+                    throw new SubagentDelegateError("subagent_invalid_input", "subagent_list limit must be an integer in 1..50");
+                }
+                const summaries = (await agents.list?.()) ?? [];
+                const requester = { owner: capabilityManifest.id, parentSessionId: session.getSessionId() };
+                const sessions = [];
+                for (const summary of summaries.slice(0, requested)) {
+                    const live = runtime.findBySession(summary.sessionId, requester);
+                    if (live !== undefined && !live.settled) {
+                        sessions.push({ ...summary, active: true });
+                        continue;
+                    }
+                    if (live !== undefined) {
+                        const record = await runtime.result(live.taskId, requester);
+                        if (record !== undefined) {
+                            sessions.push({
+                                ...summary,
+                                status: record.status,
+                                ...(record.reasonCode === undefined ? {} : { reasonCode: record.reasonCode }),
+                                ...(record.reason === undefined ? {} : { reason: record.reason }),
+                            });
+                            continue;
+                        }
+                    }
+                    // 无内存记录（父重启前的旧子会话）：只回摘要，transcript 仍在盘上。
+                    sessions.push(summary);
+                }
+                return { count: sessions.length, sessions };
+            },
+        });
+    return [
+        tool,
+        resultTool,
+        ...(resumeTool === undefined ? [] : [resumeTool]),
+        ...(listTool === undefined ? [] : [listTool]),
+        // 子侧通信面（D-060 S4/S5）：获准自建会话两面并存（向下委派 + 向父上抛/兄弟消息）。
+        ...childTools,
+        createDisposableRegistration("subagent-delegate.runtime", 
+        // 调度器释放是有界的 async 过程（cancel fence + 有界 drain），但 embedded
+        // builtin 走同步 loader（loadCapabilityPluginSync -> disposePluginSync 拒绝
+        // 异步 cleanup），因此登记处同步发起、观察 promise，不返回 Promise。
+        () => {
+            for (const unsubscribe of progressUnsubscribes)
+                unsubscribe();
+            progressUnsubscribes.clear();
+            // 先释放调度器（任务终态落定），再回收 runner 池（先释放任务再杀进程）。
+            void runtime
+                .dispose()
+                .then(() => pool?.shutdown())
+                .catch(() => {
+                // 释放失败的收尾错误已由 runtime 内部按任务暴露；同步 cleanup 路径
+                // 无法再抛，这里只保证不产生未处理的 rejection。
+            });
+        }, `registration:${capabilityManifest.id}:runtime`),
+    ];
+}
+//# sourceMappingURL=delegate.js.map