@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/runtime/stream.js

@@ -15,6 +15,7 @@ import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
 import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { isUiBusMessage, uiFrame } from "../ui/registry.js";
+import { RunDrafts } from "./run-drafts.js";
 /** 补读事件的分页大小。 */
 const PAGE = 500;
 /** 慢客户端的积压上限：超过即关闭流，客户端带 Last-Event-ID 重连补读。 */
@@ -55,6 +56,7 @@ function isBusMessage(m) {
     return k === "delta" && typeof m.runId === "string";
 }
 const eventFrame = (e) => `id: ${e.seq}\nevent: event\ndata: ${JSON.stringify(e)}\n\n`;
+const draftFrame = (d) => `event: draft\ndata: ${JSON.stringify({ runId: d.runId, step: d.step, text: d.text, thinking: d.thinking })}\n\n`;
 /**
  * 会话事件流（SSE）：本进程持有的连接集合，停机时一并关闭。
  * 跨副本的数据只经 PG（事件日志）与内核 bus（`conv.<id>`）流动，进程内只保存连接本身的资源
@@ -71,13 +73,14 @@ let ConversationStreams = class ConversationStreams {
      * an event stream. Without `GracefulShutdown` (a standalone HTTP application, tests only) the
      * streams end with their connections.
      */
-    constructor(eventLog, bus, access, config, log, shutdown) {
+    constructor(eventLog, bus, access, config, log, drafts, shutdown) {
         this.d = {
             eventLog,
             bus,
             access: (orgId, conversationId, viewer) => access.isAccessible(orgId, conversationId, viewer),
             config,
             log,
+            drafts: (conversationId) => drafts.live(conversationId),
         };
         if (shutdown?.signal.aborted)
             this.closeAll();
@@ -131,8 +134,9 @@ ConversationStreams = __decorate([
     __param(2, Inject(ConversationAccess)),
     __param(3, Inject(KernelConfigService)),
     __param(4, Inject(KERNEL_LOGGER)),
-    __param(5, Optional()),
-    __param(5, Inject(GracefulShutdown))
+    __param(5, Inject(RunDrafts)),
+    __param(6, Optional()),
+    __param(6, Inject(GracefulShutdown))
 ], ConversationStreams);
 export { ConversationStreams };
 /**
@@ -176,6 +180,9 @@ class Connection {
             this.openGate = resolve;
         });
         this.enqueue(() => this.catchUp());
+        // live drafts (spec 2026-11-07 §3.2): after the catch-up, before any delta (deltas are queued
+        // behind this); a delta also in the draft is dropped by the client by its offset
+        this.enqueue(() => this.sendDrafts());
     }
     async subscribe() {
         const un = await this.d.bus.subscribe(conversationTopic(this.p.conversationId), (m) => this.onMessage(m));
@@ -282,6 +289,23 @@ class Connection {
                 return;
         }
     }
+    /** One `event: draft` per step of the running run whose `assistant_message` is not logged. */
+    async sendDrafts() {
+        let drafts;
+        try {
+            drafts = await this.d.drafts(this.p.conversationId);
+        }
+        catch (err) {
+            // a convenience: without it the client resumes from the next delta (and asks for the draft)
+            this.d.log.warn("conversation stream cannot read live drafts", {
+                conversationId: this.p.conversationId,
+                err,
+            });
+            return;
+        }
+        for (const d of drafts)
+            this.write(draftFrame(d));
+    }
     /** 发最后一帧错误并关闭（未发完的排队输出随关闭丢弃）。 */
     fail(code) {
         if (this.closed)

package/dist/runtime/subagents/child.d.ts

@@ -1,6 +1,7 @@
 import type { AppendEvent, EventLog } from "../../conversations/event-log.js";
 import type { EventPayload } from "../../conversations/events.js";
 import type { KernelSchemaDb } from "../../db/kernel-schema.js";
+import type { SubagentAbortedBy } from "./status.js";
 /** Idempotency key of the parent's `subagent_finished` event. */
 export declare const finishedIdemKey: (childRunId: string) => string;
 /** A dispatch row, by its child run. */
@@ -10,29 +11,76 @@ export interface DispatchRow {
     parentConversationId: string;
     childConversationId: string;
     childRunId: string;
+    /** The budget run the dispatch counts against (agent map spec §6); set when read from the row. */
+    budgetRunId?: string;
+    /**
+     * A person's fork invocation (phase D, `subagent_dispatches.for_skill`): the parent run waits on
+     * it (`subagents` wait); every other dispatch runs in the background (agent map spec §5.4).
+     */
+    forSkill?: boolean;
 }
 /** The dispatch that started `childRunId`, or null (not a sub-agent run). */
 export declare function dispatchOfChildRun(db: KernelSchemaDb, childRunId: string): Promise<DispatchRow | null>;
+/**
+ * The dispatch row a finished child run reports through (agent map spec §5.2: every run of a child
+ * conversation that ends appends one `finished` delivery to its parent): the run's own dispatch
+ * (`Agent`, `SendMessage`), else, for a run nobody dispatched (a wake run, §5.3), the newest dispatch
+ * of its conversation with `childRunId` set to this run, `forSkill` false (a wake run of a fork's
+ * child is delivered like any background run; no parent run waits on it) and the run's own budget
+ * run. Null when the run is unknown or its conversation was never dispatched.
+ */
+export declare function deliveryRowOfChildRun(db: KernelSchemaDb, childRunId: string): Promise<DispatchRow | null>;
 /** The dispatch of the parent call `(runId, callId)`, or null (not dispatched yet). */
 export declare function dispatchOfCall(db: KernelSchemaDb, runId: string, callId: string): Promise<DispatchRow | null>;
 /**
- * The tool result of a finished child run (spec §4.4) and its `subagent_finished` payload, from
- * the child's log only: the status from its terminal event, the reply from its last
+ * The root conversation of `conversationId`'s tree (agent map spec §6): the first ancestor without
+ * a parent, or `conversationId` itself for a root (or an unknown id).
+ */
+export declare function rootConversationOf(db: KernelSchemaDb, conversationId: string): Promise<string>;
+/** Where a sub-agent's request for a person is shown: see {@link rootSurfaceOf}. */
+export interface RootSurface {
+    /** The root conversation of the sub-agent's tree. */
+    conversationId: string;
+    /** The root run the event is logged under: the one that last dispatched the branch. */
+    runId: string;
+    /** Child conversation ids from the root's child down to the sub-agent itself. */
+    path: string[];
+}
+/**
+ * Where the sub-agent conversation `conversationId`, in its run `runId`, shows a request for a
+ * person (`subagent_waiting`: an approval, a question or a connect card; agent map spec §7): the
+ * **root** conversation of its tree, the only one a person looks at, with the path from the root's
+ * child down to it, under the root run that last dispatched (or messaged) the root's child on that
+ * path (for a child of the root, the run's own dispatch first). `parent`, when the caller knows the
+ * run's dispatch and it was made by the root (`depth` 0), answers without a read. Null for a root
+ * conversation, or a branch the root never dispatched.
+ */
+export declare function rootSurfaceOf(db: KernelSchemaDb, conversationId: string, runId: string, parent?: {
+    conversationId: string;
+    runId: string;
+    depth: number;
+}): Promise<RootSurface | null>;
+/**
+ * The result of a finished child run (spec §4.4) and its `subagent_finished` payload, from the
+ * child's log only: the status from its terminal event, the reply from its last
  * `assistant_message` (text blocks), the tool call count from its `tool_result` events, the usage
  * from its `usage` events (compaction included) and the duration from `run_started` to the
- * terminal event. Null while the run has no terminal event.
+ * terminal event. Null while the run has no terminal event. `content` is the fork report's text
+ * (`agentResultText`); `reply`, `errorMessage` and `abortedBy` are what a background child's
+ * finished `subagent_delivery` carries.
  *
  * `modelGiven`: the parent's call named a `model`; for an org agent, which runs on its own model
  * (§5.4, §5.5), the status line then says `model: the agent's own`.
  */
-export declare function childResult(eventLog: EventLog, row: DispatchRow, 
-/** `forSkill`: a fork invocation's report (no resume hint, see `agentResultText`). */
-opts?: {
+export declare function childResult(eventLog: EventLog, row: DispatchRow, opts?: {
     modelGiven?: boolean;
-    forSkill?: boolean;
 }): Promise<{
     content: string;
     isError: boolean;
+    /** The text of the child's last `assistant_message`. */
+    reply: string;
+    errorMessage?: string;
+    abortedBy?: SubagentAbortedBy;
     finished: EventPayload<"subagent_finished">;
 } | null>;
 /** The parent's `subagent_finished` event for a finished child (idempotent by its key). */

package/dist/runtime/subagents/child.js

@@ -8,6 +8,8 @@ const DISPATCH_COLUMNS = [
     "parent_conversation_id",
     "child_conversation_id",
     "child_run_id",
+    "budget_run_id",
+    "for_skill",
 ];
 const toRow = (r) => ({
     parentRunId: r.parent_run_id,
@@ -15,6 +17,8 @@ const toRow = (r) => ({
     parentConversationId: r.parent_conversation_id,
     childConversationId: r.child_conversation_id,
     childRunId: r.child_run_id,
+    budgetRunId: r.budget_run_id,
+    forSkill: r.for_skill,
 });
 /** The dispatch that started `childRunId`, or null (not a sub-agent run). */
 export async function dispatchOfChildRun(db, childRunId) {
@@ -25,6 +29,41 @@ export async function dispatchOfChildRun(db, childRunId) {
         .executeTakeFirst();
     return r ? toRow(r) : null;
 }
+/**
+ * The dispatch row a finished child run reports through (agent map spec §5.2: every run of a child
+ * conversation that ends appends one `finished` delivery to its parent): the run's own dispatch
+ * (`Agent`, `SendMessage`), else, for a run nobody dispatched (a wake run, §5.3), the newest dispatch
+ * of its conversation with `childRunId` set to this run, `forSkill` false (a wake run of a fork's
+ * child is delivered like any background run; no parent run waits on it) and the run's own budget
+ * run. Null when the run is unknown or its conversation was never dispatched.
+ */
+export async function deliveryRowOfChildRun(db, childRunId) {
+    const own = await dispatchOfChildRun(db, childRunId);
+    if (own)
+        return own;
+    const run = await db
+        .selectFrom("runs")
+        .select(["conversation_id", "budget_run_id"])
+        .where("id", "=", childRunId)
+        .executeTakeFirst();
+    if (!run)
+        return null;
+    const latest = await db
+        .selectFrom("subagent_dispatches")
+        .select(DISPATCH_COLUMNS)
+        .where("child_conversation_id", "=", run.conversation_id)
+        .orderBy("created_at", "desc")
+        .limit(1)
+        .executeTakeFirst();
+    if (!latest)
+        return null;
+    return {
+        ...toRow(latest),
+        childRunId,
+        forSkill: false,
+        ...(run.budget_run_id !== null && { budgetRunId: run.budget_run_id }),
+    };
+}
 /** The dispatch of the parent call `(runId, callId)`, or null (not dispatched yet). */
 export async function dispatchOfCall(db, runId, callId) {
     const r = await db
@@ -35,6 +74,63 @@ export async function dispatchOfCall(db, runId, callId) {
         .executeTakeFirst();
     return r ? toRow(r) : null;
 }
+/**
+ * `conversationId` and its ancestors, nearest first, ending at the root of its tree (the first
+ * conversation without a parent); just `[conversationId]` for a root or an unknown id. Walks at
+ * most 16 levels, far above `subagents.maxDepth`'s bound of 5.
+ */
+async function ancestryOf(db, conversationId) {
+    const chain = [conversationId];
+    for (let i = 0; i < 16; i++) {
+        const row = await db
+            .selectFrom("conversations")
+            .select("parent_conversation_id")
+            .where("id", "=", chain[chain.length - 1])
+            .executeTakeFirst();
+        if (!row?.parent_conversation_id)
+            return chain;
+        chain.push(row.parent_conversation_id);
+    }
+    return chain;
+}
+/**
+ * The root conversation of `conversationId`'s tree (agent map spec §6): the first ancestor without
+ * a parent, or `conversationId` itself for a root (or an unknown id).
+ */
+export async function rootConversationOf(db, conversationId) {
+    return (await ancestryOf(db, conversationId)).at(-1);
+}
+/**
+ * Where the sub-agent conversation `conversationId`, in its run `runId`, shows a request for a
+ * person (`subagent_waiting`: an approval, a question or a connect card; agent map spec §7): the
+ * **root** conversation of its tree, the only one a person looks at, with the path from the root's
+ * child down to it, under the root run that last dispatched (or messaged) the root's child on that
+ * path (for a child of the root, the run's own dispatch first). `parent`, when the caller knows the
+ * run's dispatch and it was made by the root (`depth` 0), answers without a read. Null for a root
+ * conversation, or a branch the root never dispatched.
+ */
+export async function rootSurfaceOf(db, conversationId, runId, parent) {
+    if (parent?.depth === 0) {
+        return { conversationId: parent.conversationId, runId: parent.runId, path: [conversationId] };
+    }
+    const chain = await ancestryOf(db, conversationId);
+    if (chain.length < 2)
+        return null;
+    const root = chain.at(-1);
+    const path = chain.slice(0, -1).reverse();
+    const top = path[0];
+    const own = path.length === 1 ? await dispatchOfChildRun(db, runId) : null;
+    const dispatch = own ??
+        (await db
+            .selectFrom("subagent_dispatches")
+            .select(["parent_run_id as parentRunId"])
+            .where("child_conversation_id", "=", top)
+            .where("parent_conversation_id", "=", root)
+            .orderBy("created_at", "desc")
+            .limit(1)
+            .executeTakeFirst());
+    return dispatch ? { conversationId: root, runId: dispatch.parentRunId, path } : null;
+}
 /** All events of one run of a conversation, by seq. */
 async function runEvents(eventLog, conversationId, runId) {
     const out = [];
@@ -49,18 +145,18 @@ async function runEvents(eventLog, conversationId, runId) {
     }
 }
 /**
- * The tool result of a finished child run (spec §4.4) and its `subagent_finished` payload, from
- * the child's log only: the status from its terminal event, the reply from its last
+ * The result of a finished child run (spec §4.4) and its `subagent_finished` payload, from the
+ * child's log only: the status from its terminal event, the reply from its last
  * `assistant_message` (text blocks), the tool call count from its `tool_result` events, the usage
  * from its `usage` events (compaction included) and the duration from `run_started` to the
- * terminal event. Null while the run has no terminal event.
+ * terminal event. Null while the run has no terminal event. `content` is the fork report's text
+ * (`agentResultText`); `reply`, `errorMessage` and `abortedBy` are what a background child's
+ * finished `subagent_delivery` carries.
  *
  * `modelGiven`: the parent's call named a `model`; for an org agent, which runs on its own model
  * (§5.4, §5.5), the status line then says `model: the agent's own`.
  */
-export async function childResult(eventLog, row, 
-/** `forSkill`: a fork invocation's report (no resume hint, see `agentResultText`). */
-opts = {}) {
+export async function childResult(eventLog, row, opts = {}) {
     const events = await runEvents(eventLog, row.childConversationId, row.childRunId);
     const terminal = events.find((e) => e.type === "run_finished" || e.type === "run_failed" || e.type === "run_aborted");
     if (!terminal)
@@ -121,10 +217,12 @@ opts = {}) {
         tokens: usageTokens(usage),
         ...(abortedBy !== undefined && { abortedBy }),
         ...(ownModel && { ownModel }),
-        ...(opts.forSkill === true && { noResumeHint: true }),
     });
     return {
         ...text,
+        reply,
+        ...(errorMessage !== undefined && { errorMessage }),
+        ...(abortedBy !== undefined && { abortedBy }),
         finished: {
             subagentId: row.childConversationId,
             childRunId: row.childRunId,

package/dist/runtime/subagents/definition.d.ts

@@ -42,6 +42,13 @@ export interface CheckedOrgAgent {
     version: number;
     definition: AgentDefinition;
 }
+/** Where a new child sits (agent map spec §6): its depth below the root and the tree's limit. */
+export interface ChildDepth {
+    /** The child's depth: 1 for a child of a root conversation. */
+    childDepth: number;
+    /** `subagents.maxDepth` for the organization; a child at it never gets `Agent`. */
+    maxDepth: number;
+}
 /**
  * The effective definition of a sub-agent at its first dispatch (spec §5.3–§5.5):
  * - `general` / `inline` / `plugin`: the parent's definition narrowed by the template (tools by
@@ -52,10 +59,12 @@ export interface CheckedOrgAgent {
  *   (`tierFallback`); a template `effort` is set when the resolved model declares it;
  * - `agent`: the org agent's version that passed the gates (`orgAgent`, from {@link checkOrgAgent}),
  *   its own tools minus the child-removed ones, its policies with the parent's on top (stricter
- *   wins), its skills and model; `tier` ignored.
- * The `subagents` block is never part of a child's definition (depth 1).
+ *   wins), its skills, model and `subagents` block; `tier` ignored.
+ * Nesting (agent map spec §4.1): `Agent` stays unless the child is at `maxDepth`; the frozen
+ * definition keeps a `subagents` block, the roster the child dispatches from: an org agent's own,
+ * otherwise the parent definition's (a general-purpose, inline or plugin child inherits it).
  */
-export declare function effectiveDefinition(d: EffectiveDefinitionDeps, a: {
+export declare function effectiveDefinition(d: EffectiveDefinitionDeps, a: ChildDepth & {
     orgId: string;
     parent: AgentDefinition;
     parentAgentId: string;

package/dist/runtime/subagents/definition.js

@@ -2,7 +2,8 @@ import { connectorToolKey, extensionToolKey, parseToolKey, SKILL_ENTRY_FILE, san
 import { loadTemplates } from "../../agents/templates.js";
 import { ApiError } from "../../errors.js";
 import { PINNED_SKILLS_LIMITS } from "../../skills/catalog.js";
-import { CHILD_REMOVED_TOOLS } from "../../tools/builtin-names.js";
+import { selectedSkills } from "../../skills/usable.js";
+import { AGENT_TOOL, CHILD_REMOVED_TOOLS } from "../../tools/builtin-names.js";
 export { CHILD_REMOVED_TOOLS } from "../../tools/builtin-names.js";
 /**
  * The roster entry's template is gone (an inline template edited away, a plugin template
@@ -67,13 +68,15 @@ async function loadConnectors(db, orgId, refs) {
 }
 /**
  * Narrows tool refs by resolved key (spec §5.3): keeps a key when `allow` (if given) lists it and
- * neither `deny` nor {@link CHILD_REMOVED_TOOLS} does. A connector ref with `tools: "all"` stays
+ * neither `deny` nor {@link CHILD_REMOVED_TOOLS} does (nor, with `removeAgent`, it is `Agent`). A connector ref with `tools: "all"` stays
  * live only when nothing can narrow it (no allowlist and no deny key under `mcp__<slug>__`), so a tool
  * the connector gains later never slips past the template; otherwise it becomes the kept names, or
  * is dropped. A connector that no longer exists keeps its ref only without an allowlist.
  */
-function narrowTools(refs, connectors, allow, deny) {
+function narrowTools(refs, connectors, allow, deny, removeAgent) {
     const removed = new Set(CHILD_REMOVED_TOOLS);
+    if (removeAgent)
+        removed.add(AGENT_TOOL);
     const keep = (key) => !removed.has(key) && !deny.has(key) && (allow === null || allow.has(key));
     const out = [];
     for (const ref of refs) {
@@ -115,25 +118,17 @@ function narrowTools(refs, connectors, allow, deny) {
  * this order, the skill from the template's own plugin, the agent's own skill, the org skill (ties
  * by id), with a warning. Dropped ones get a warning.
  */
-async function pinnedFor(db, a, refs, byName) {
-    if (refs.length === 0)
+async function pinnedFor(db, a, refs, byName, 
+/** Further names the template lists (`selectedSkills`): resolved the same way, never pinned. */
+selected = []) {
+    if (refs.length === 0 && selected.length === 0)
         return { pinned: [], warnings: [] };
-    const orgSkills = a.parent.skills?.orgSkills ?? [];
-    const rows = (await db
-        .selectFrom("skills as s")
-        .innerJoin("skill_versions as v", (j) => j.onRef("v.skill_id", "=", "s.id").onRef("v.version", "=", "s.current_version"))
-        .leftJoin("catalog_items as c", "c.id", "s.catalog_item_id")
-        .select(["s.id", "s.name", "s.scope", "v.manifest", "c.name as plugin"])
-        .where("s.org_id", "=", a.orgId)
-        .where("s.deleted_at", "is", null)
-        .where((eb) => {
-        const own = eb.and([eb("s.scope", "=", "agent"), eb("s.agent_id", "=", a.parentAgentId)]);
-        return orgSkills.length === 0
-            ? own
-            : eb.or([own, eb.and([eb("s.scope", "=", "org"), eb("s.id", "in", orgSkills)])]);
-    })
-        .orderBy("s.id")
-        .execute()).map((r) => ({
+    // org and agent skills, linked org copies and platform skills on in the org (phase 2), by id
+    const rows = (await selectedSkills(db, {
+        orgId: a.orgId,
+        agentId: a.parentAgentId,
+        orgSkills: a.parent.skills?.orgSkills ?? [],
+    })).map((r) => ({
         id: r.id,
         name: r.name,
         scope: r.scope,
@@ -179,6 +174,13 @@ async function pinnedFor(db, a, refs, byName) {
         total += r.bytes;
         pinned.push(r.id);
     }
+    for (const ref of selected) {
+        if (refs.includes(ref))
+            continue;
+        if (!match(ref)) {
+            warnings.push(`The skill "${ref}" is not available: the agent does not select it.`);
+        }
+    }
     return { pinned, warnings };
 }
 /** The `effort` declaration of `model`, or null (or when the model cannot be resolved). */
@@ -220,6 +222,7 @@ async function resolveTier(d, orgId, parent, tier) {
 }
 /** `"{parent name} › {agent type}"`, within the 80-character name limit. */
 const childName = (parent, type) => `${parent} › ${type}`.slice(0, 80);
+const atMaxDepth = (a) => a.childDepth >= a.maxDepth;
 function orgAgentDefinition(d, a) {
     // the version the gates checked (checkOrgAgent), never read again here: a version saved in
     // between could be one the gates never saw (batch 3 review M1)
@@ -228,11 +231,15 @@ function orgAgentDefinition(d, a) {
     }
     const agentId = a.entry.agentId ?? "";
     const own = a.orgAgent.definition;
-    const { subagents: _subagents, skills, ...rest } = own;
+    // prompt files are authoring data: the child's model sees only `instructions` (their join), and
+    // `subagent_started.definition` keeps its shape (spec 2026-11-04 §3.3); its own `subagents`
+    // block stays: it is the roster the child dispatches from (agent map spec §4.1); pending
+    // connectors are authoring data too (ruling P4-6)
+    const { skills, instructionFiles: _files, pendingConnectors: _pending, ...rest } = own;
     const definition = {
         ...rest,
         // its own tools, not intersected with the parent's; only the child-removed ones go
-        tools: narrowTools(own.tools, new Map(), null, new Set()),
+        tools: narrowTools(own.tools, new Map(), null, new Set(), atMaxDepth(a)),
         // its policies, then the parent's on top, stricter wins (keys outside its tools are inert)
         toolPolicies: stricterPolicies(own.toolPolicies ?? {}, a.parent.toolPolicies ?? {}),
         ...(skills !== undefined && {
@@ -261,8 +268,10 @@ function orgAgentDefinition(d, a) {
  *   (`tierFallback`); a template `effort` is set when the resolved model declares it;
  * - `agent`: the org agent's version that passed the gates (`orgAgent`, from {@link checkOrgAgent}),
  *   its own tools minus the child-removed ones, its policies with the parent's on top (stricter
- *   wins), its skills and model; `tier` ignored.
- * The `subagents` block is never part of a child's definition (depth 1).
+ *   wins), its skills, model and `subagents` block; `tier` ignored.
+ * Nesting (agent map spec §4.1): `Agent` stays unless the child is at `maxDepth`; the frozen
+ * definition keeps a `subagents` block, the roster the child dispatches from: an org agent's own,
+ * otherwise the parent definition's (a general-purpose, inline or plugin child inherits it).
  */
 export async function effectiveDefinition(d, a) {
     if (a.entry.source === "agent")
@@ -281,12 +290,18 @@ export async function effectiveDefinition(d, a) {
         if (!row)
             throw new SubagentTypeGoneError(entry.type);
         template = row.template;
-        ref = { source: "plugin", id: row.id, version: row.version, plugin: row.plugin };
+        ref = {
+            source: "plugin",
+            id: row.id,
+            version: row.version,
+            ...(row.plugin ? { plugin: row.plugin } : {}),
+            ...(row.platformTemplateId !== undefined && { platformTemplateId: row.platformTemplateId }),
+        };
     }
     const connectors = await loadConnectors(d.db, a.orgId, parent.tools);
-    const tools = narrowTools(parent.tools, connectors, template?.tools !== undefined ? new Set(template.tools) : null, new Set(template?.disallowedTools ?? []));
+    const tools = narrowTools(parent.tools, connectors, template?.tools !== undefined ? new Set(template.tools) : null, new Set(template?.disallowedTools ?? []), atMaxDepth(a));
     const toolPolicies = stricterPolicies(parent.toolPolicies ?? {}, template?.toolPolicies ?? {});
-    const { pinned, warnings } = await pinnedFor(d.db, a, template?.skills ?? [], entry.source === "plugin" ? { plugin: entry.plugin } : null);
+    const { pinned, warnings } = await pinnedFor(d.db, a, template?.skills ?? [], entry.source === "plugin" ? { plugin: entry.plugin } : null, template?.selectedSkills ?? []);
     const tier = a.tier ?? template?.model ?? "inherit";
     const m = await resolveTier(d, a.orgId, parent, tier);
     let modelParams = m.modelParams;
@@ -315,6 +330,7 @@ export async function effectiveDefinition(d, a) {
                 ...(pinned.length > 0 && { pinned }),
             },
         }),
+        ...(parent.subagents !== undefined && { subagents: parent.subagents }),
     };
     return {
         definition,

package/dist/runtime/subagents/deliveries.d.ts

@@ -0,0 +1,71 @@
+import { EventLog } from "../../conversations/event-log.js";
+import type { EventPayload } from "../../conversations/events.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { TransactionHost } from "../../infra/database/transaction-host.js";
+import { KernelEvents } from "../../infra/events/kernel-events.js";
+import type { KernelLogger } from "../../log.js";
+import { type DispatchRow } from "./child.js";
+/** What a caller of {@link SubagentDeliveries.deliverIn} gives; the rest comes from the dispatch. */
+export type DeliveryInput = Omit<EventPayload<"subagent_delivery">, "subagentId" | "childRunId" | "description" | "triggerAccountId">;
+/** Idempotency key of a child run's finished delivery (one per child run). */
+export declare const finishedDeliveryIdemKey: (childRunId: string) => string;
+/**
+ * Deliveries from a sub-agent to its parent conversation (agent map spec §4.5, §5.2): each is one
+ * model-visible, absorbable `subagent_delivery` event in the parent's log. A parent run that is
+ * active absorbs it at its next model call; an idle parent is woken from the `subagent.delivered`
+ * domain event (emitted after the commit, with the log's notify).
+ *
+ * A background child's run reaching a terminal state ({@link childFinished}) writes the
+ * display-only `subagent_finished` and a `finished` delivery in one transaction, both idempotent by
+ * the child run, so of two finishers (the worker and a stop, the orphan sweep) exactly one writes
+ * them. A run that handed back a report and then completed writes no delivery (acceptance
+ * 2026-11-07): the report already told the parent everything, and a content-free "completed" line
+ * only woke an idle parent for nothing and pushed the report away from the end of its request. Fork invocations (phase D, `for_skill`) do not deliver: their parent run waits on the child
+ * and writes the report itself (`advanceSkillForks`).
+ */
+export declare class SubagentDeliveries {
+    private readonly kdb;
+    private readonly eventLog;
+    private readonly events;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, eventLog: EventLog, events: KernelEvents, log: Pick<KernelLogger, "warn">, txHost: TransactionHost);
+    /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
+    private get db();
+    /**
+     * Appends one delivery of the dispatch `row` to the parent log, in the caller's transaction or
+     * one of its own: the description is the dispatch's (`subagent_dispatched`), the trigger account
+     * the child run's (a wake runs as that person, §7). Idempotent by `opts.idemKey` (a finish's
+     * default is {@link finishedDeliveryIdemKey}; a report or a note must name its own): under the
+     * parent conversation's row lock, an existing delivery returns null and writes nothing. After
+     * the commit: the log's notify and `subagent.delivered`. Returns the new event's seq.
+     */
+    deliverIn(row: DispatchRow, d: DeliveryInput, opts?: {
+        idemKey?: string;
+    }): Promise<number | null>;
+    /**
+     * A background child run reached a terminal state (agent map spec §4.5, §5.2): appends the
+     * parent's `subagent_finished` (display only) and a `finished` delivery in one transaction, for
+     * every run of a child conversation (dispatched, sent a message or woken;
+     * {@link deliveryRowOfChildRun}), each once by its run. The delivery
+     * carries the final reply when the run handed back no report, else no text and `handedBack`; a
+     * failed run's error message and code, an aborted run who stopped it. A run that handed back and
+     * then `completed` gets only `subagent_finished` (not model-visible, wakes nothing); the log's
+     * notify still announces it to viewers. A run of a conversation never dispatched, a fork
+     * invocation's child, or not terminal yet is left alone. True when this call wrote the finish.
+     */
+    childFinished(childRunId: string): Promise<boolean>;
+    /** {@link childFinished}'s transaction. */
+    private finishIn;
+    /**
+     * {@link finishIn} for a run that handed back and completed: only `subagent_finished`, written
+     * once under the parent conversation's row lock (idempotent by the child run), then the log's
+     * notify after the commit. No `subagent.delivered`: nothing model-visible arrived, so no wake.
+     * True when this call wrote it.
+     */
+    private finishSilentlyIn;
+    /** Whether the child run handed back a report (`SubagentHandback`) before it finished. */
+    private handedBack;
+    /** The dispatch's task label (`subagent_dispatched.description`), else the child's title. */
+    private descriptionOf;
+}