@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/runtime/subagents/dispatch.js

@@ -1,11 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { sql } from "kysely";
-import { normalizeStoredDefinition } from "../../agents/definition.js";
 import { audit } from "../../identity/audit.js";
 import { forkAgentUnknownText } from "../../skills/invoke.js";
-import { AGENT_REFUSALS } from "../../tools/builtins/agent.js";
-import { ACTIVE_RUN_STATUSES, runJobId } from "../run-queue.js";
-import { effectiveDefinition, narrowFollowUp, SubagentTypeGoneError, } from "./definition.js";
+import { SEND_MESSAGE } from "../../tools/builtin-names.js";
+import { AGENT_REFUSALS, AGENT_TOOL, agentStartedText, } from "../../tools/builtins/agent.js";
+import { ACTIVE_RUN_STATUSES, runJobId } from "../run-jobs.js";
+import { childResult, finishedEvent } from "./child.js";
+import { effectiveDefinition, SubagentTypeGoneError, } from "./definition.js";
 import { subagentLimits } from "./limits.js";
 import { auditRefusal, checkOrgAgent, currentAgentDefinition } from "./org-agents.js";
 import { SUBAGENT_PREAMBLE } from "./preamble.js";
@@ -17,38 +18,40 @@ const GENERAL_ENTRY = {
     source: "general",
     description: GENERAL_PURPOSE_DESCRIPTION,
 };
+/**
+ * The depth of the run behind `ctx` below the root (agent map spec §6): 0 for a root
+ * conversation's run, its parent's depth plus one for a sub-agent's.
+ */
+export const runDepth = (ctx) => ctx.parent === undefined ? 0 : ctx.parent.depth + 1;
 /** Idempotency key of the parent's `subagent_dispatched` event. */
 export const dispatchedIdemKey = (runId, callId) => `subagent_dispatched:${runId}:${callId}`;
 /**
- * Dispatches the sub-agent of one `agent` call (spec §7.1), after the pipeline's validation,
- * policy, approval and `tool.preExecute` stages. A new sub-agent: resolves its type and effective
- * definition, then in one transaction (holding the parent run's row lock, so the dispatches of one
- * run serialize) inserts the child conversation, appends `subagent_started` and the task message,
- * inserts the child run (`queued`) and the `subagent_dispatches` row, appends `subagent_dispatched`
- * to the parent and audits `subagent.dispatched`. A `resume` appends the follow-up message and
- * starts the child's next run the same way. After commit the child run is enqueued; a failed
- * enqueue only logs (the dispatch is durable, the wait sweep re-enqueues it).
+ * Dispatches the sub-agent of one `Agent` call (spec §7.1, agent map spec §4.1), after the
+ * pipeline's validation, policy, approval and `tool.preExecute` stages: resolves its type and
+ * effective definition, then in one transaction (holding the parent run's row lock, so the
+ * dispatches of one run serialize) inserts the child conversation, appends `subagent_started` and
+ * the task message, inserts the child run (`queued`) and the `subagent_dispatches` row, appends
+ * `subagent_dispatched` and the call's `tool_result` ({@link agentStartedText}: the sub-agent runs
+ * in the background) to the parent and audits `subagent.dispatched` and `tool.called`. After
+ * commit the child run is enqueued; a failed enqueue only logs (the dispatch is durable, the wait
+ * sweep re-enqueues it). A fork invocation (`forSkill`) writes no `tool_result`: its run waits on
+ * the child (`advanceSkillForks`).
  *
- * Refusals (§4.5) start nothing: a call from a sub-agent, an unknown type, an org agent that fails
- * one of its gates ({@link orgAgentGates}, at every dispatch and follow-up; audited
- * `subagent.refused`), `resume` with `subagent_type` / `model`, a `resume` id that is not a
- * sub-agent of this conversation (whatever it is otherwise: no detail about other conversations),
- * or one whose run is still active.
+ * Refusals (§4.5) start nothing: a call from a run at `subagents.maxDepth` (agent map spec §4.1:
+ * its definition has no `Agent`, so only a forged call or a lowered limit gets here), an unknown
+ * type, or an org agent that fails one of its gates ({@link orgAgentGates}, checked at every
+ * level; audited `subagent.refused`).
  */
 export async function dispatchSubagent(d, a) {
     const { ctx, input } = a;
-    if (ctx.parent !== undefined)
-        return refused(AGENT_REFUSALS.notAvailableHere);
-    if (input.resume !== undefined) {
-        if (input.subagent_type !== undefined || input.model !== undefined) {
-            return refused(AGENT_REFUSALS.resumeWithType);
-        }
-        return resume(d, { ...a, id: input.resume });
-    }
+    const { maxDepth } = await subagentLimits(d.db, d.config, ctx.orgId);
+    const childDepth = runDepth(ctx) + 1;
+    if (childDepth > maxDepth)
+        return refused(AGENT_REFUSALS.depthLimit(maxDepth));
     const requested = input.subagent_type ?? "general-purpose";
     const unknown = (types) => refused(AGENT_REFUSALS.unknownType(requested, types.map((e) => e.type)));
     const fork = a.forSkill;
-    const listed = await resolveRoster(d.db, ctx.orgId, ctx.agent);
+    const listed = await resolveRoster(d.db, ctx.orgId, ctx.agent, d.log);
     const roster = fork !== undefined && !listed.some((e) => e.type === GENERAL_ENTRY.type)
         ? [GENERAL_ENTRY, ...listed]
         : listed;
@@ -75,6 +78,8 @@ export async function dispatchSubagent(d, a) {
             parent: ctx.agent,
             parentAgentId: ctx.agentId,
             entry,
+            childDepth,
+            maxDepth,
             ...(input.model !== undefined && { tier: input.model }),
             ...(orgAgent !== undefined && { orgAgent }),
         });
@@ -84,7 +89,7 @@ export async function dispatchSubagent(d, a) {
         // the template went away since the roster was read (spec §13: refuse, never fail the run);
         // the list offered instead is read again, without it
         if (e instanceof SubagentTypeGoneError) {
-            return unknown(await resolveRoster(d.db, ctx.orgId, ctx.agent));
+            return unknown(await resolveRoster(d.db, ctx.orgId, ctx.agent, d.log));
         }
         throw e;
     }
@@ -116,9 +121,10 @@ export async function dispatchSubagent(d, a) {
             kind: "subagent",
             parent_conversation_id: ctx.conversationId,
             subagent_type: entry.type,
+            subagent_depth: childDepth,
         })
             .execute();
-        const [, task] = await d.eventLog.append(childId, [
+        const [, task] = await d.eventLog.appendIn(childId, [
             {
                 type: "subagent_started",
                 idemKey: "subagent_started",
@@ -149,95 +155,12 @@ export async function dispatchSubagent(d, a) {
                 },
             },
             taskMessage(ctx, a.callId, fork === undefined ? input.prompt : fork.task(eff.definition), undefined, fork?.skill),
-        ], t);
+        ]);
         return task;
     });
     // a new sub-agent's writer never refuses
     return out ?? refused(AGENT_REFUSALS.notAvailableHere);
 }
-/**
- * A follow-up to an existing sub-agent of this conversation (§4.2 `resume`). It keeps the frozen
- * definition's instructions and model (replay), but is checked against what the parent may use
- * now (final review I1): a `general` / inline / plugin child's type must still be in the roster
- * of the dispatching run's version (a plugin template by its template id), else the call is
- * refused as an unknown type; an org agent child passes its gates. Its tools and org skills are
- * intersected with the current version ({@link narrowFollowUp}: the dispatching run's version,
- * or the org agent's current version as the gates read it under the lock), and the result is
- * recorded on the follow-up's task message for the run and for replay.
- */
-async function resume(d, a) {
-    const { ctx } = a;
-    const child = await d.db
-        .selectFrom("conversations")
-        .select(["id", "subagent_type"])
-        .where("id", "=", a.id)
-        .where("org_id", "=", ctx.orgId)
-        .where("kind", "=", "subagent")
-        .where("parent_conversation_id", "=", ctx.conversationId)
-        .executeTakeFirst();
-    if (!child)
-        return refused(AGENT_REFUSALS.noSuchAgent(a.id));
-    const started = await d.eventLog.findByIdem(child.id, "subagent_started");
-    if (started?.type !== "subagent_started")
-        return refused(AGENT_REFUSALS.noSuchAgent(a.id));
-    const { template } = started.payload;
-    const agentType = child.subagent_type ?? started.payload.agentType;
-    // an org agent's gates hold for every follow-up too (§5.5); it keeps its frozen version
-    if (template.source === "agent") {
-        const gates = await orgAgentGates(d.db, a, template.id ?? "", agentType, true);
-        if ("refused" in gates)
-            return gates.refused;
-    }
-    else {
-        const roster = await resolveRoster(d.db, ctx.orgId, ctx.agent);
-        const entry = template.source === "plugin"
-            ? roster.find((e) => e.source === "plugin" && e.templateId === template.id)
-            : findType(roster, agentType);
-        if (entry?.source !== template.source) {
-            return refused(AGENT_REFUSALS.unknownType(agentType, roster.map((e) => e.type)));
-        }
-    }
-    const frozen = normalizeStoredDefinition(started.payload.definition);
-    const plan = {
-        childConversationId: child.id,
-        agentType,
-        source: template.source,
-        agentId: template.source === "agent" ? (template.id ?? "") : ctx.agentId,
-        agentVersion: template.source === "agent" ? (template.version ?? ctx.agentVersion) : ctx.agentVersion,
-        resumed: true,
-        model: started.payload.definition.model,
-        tierFallback: false,
-    };
-    return commit(d, a, plan, async (t, checked) => {
-        const current = template.source === "agent" ? checked?.definition : ctx.agent;
-        if (current === undefined)
-            throw new Error("org agent follow-up without its checked version");
-        const activeRun = () => t
-            .selectFrom("runs")
-            .select("id")
-            .where("conversation_id", "=", child.id)
-            .where("status", "in", ACTIVE_RUN_STATUSES)
-            .executeTakeFirst();
-        // An active child is refused before its row is locked: a running child's token append locks
-        // its conversation row and then this parent run's row, which `commit` already holds, so
-        // waiting for the child's row here would be a lock-order cycle (review I1). The parent row
-        // lock serializes this parent's dispatches, so an earlier follow-up's run is visible here.
-        if (await activeRun())
-            return null;
-        // the child's row lock serializes follow-ups to one sub-agent; no run holds it now, so it is
-        // never held by an append waiting for the parent row
-        await t
-            .selectFrom("conversations")
-            .select("id")
-            .where("id", "=", child.id)
-            .forUpdate()
-            .executeTakeFirst();
-        if (await activeRun())
-            return null;
-        const [task] = await d.eventLog.append(child.id, [taskMessage(ctx, a.callId, a.input.prompt, narrowFollowUp(frozen, current))], t);
-        return task;
-    }).then((r) => r ?? refused(AGENT_REFUSALS.stillRunning(a.id)));
-}
 /**
  * The gates of an org agent sub-agent (§5.5) for this call: the allowlist of the parent agent's
  * **current** version (R5), the agent's `dispatchable`, its visibility to the person who started
@@ -246,7 +169,7 @@ async function resume(d, a) {
  * sub-agent freezes the definition read here) and again inside it under the parent run's row lock
  * ({@link commit}), so a gate revoked in between refuses (batch 9 review M1).
  */
-async function orgAgentGates(db, a, agentId, agentType, resumed) {
+export async function orgAgentGates(db, a, agentId, agentType, resumed) {
     const { ctx } = a;
     const parentDefinition = (await currentAgentDefinition(db, ctx.agentId)) ?? {};
     const check = await checkOrgAgent(db, {
@@ -270,13 +193,19 @@ async function orgAgentGates(db, a, agentId, agentType, resumed) {
     });
     return { refused: refused(AGENT_REFUSALS.agentNotAvailable(agentType)) };
 }
-const taskMessage = (ctx, callId, prompt, narrowed, 
 /**
- * A fork invocation's record: the child's log then holds the invocation, so its `skill_load`
+ * A sub-agent's task message, or (`message`) a `SendMessage` from its parent (agent map spec
+ * §5.1: `dispatch.kind: "message"`, idempotent by the sending call, with the follow-up narrowing
+ * the run it triggers uses).
+ */
+export const taskMessage = (ctx, callId, prompt, narrowed, 
+/**
+ * A fork invocation's record: the child's log then holds the invocation, so its `Skill`
  * is offered and resolves the invoked version (phase D).
  */
-skill) => ({
+skill, message = false) => ({
     type: "user_message",
+    ...(message && { idemKey: sentMessageIdemKey(ctx.runId, callId) }),
     payload: {
         content: [{ type: "text", text: prompt }],
         ...(skill !== undefined && { skill }),
@@ -285,158 +214,263 @@ skill) => ({
             parentConversationId: ctx.conversationId,
             parentRunId: ctx.runId,
             callId,
+            ...(message && { kind: "message" }),
             ...(narrowed !== undefined && { narrowed }),
         },
     },
 });
+/** Idempotency key of a `SendMessage`'s `user_message` in the sub-agent's log. */
+export const sentMessageIdemKey = (runId, callId) => `send_message:${runId}:${callId}`;
+const isActiveStatus = (status) => ACTIVE_RUN_STATUSES.includes(status);
 /**
- * The dispatch transaction shared by new sub-agents and follow-ups: locks the parent conversation
- * row, then the parent run row (the order every terminal path uses),
- * runs `child` (writes the child conversation's first events and returns the task message, or
- * null to refuse), then inserts the child run and the dispatch row, appends `subagent_dispatched`
- * and the audit row. After commit: notifies both conversations and enqueues the child run.
- * Returns null when `child` refused.
- *
- * Under the parent run's row lock it first re-checks what the pipeline checked without it: a call
- * already dispatched (a second holder of the same step, e.g. after a stalled-job takeover) gets
- * the existing child run back and writes nothing, and a parent run that is no longer `running`
- * (stopped, orphaned) dispatches nothing. Then the run's limits (§8.2, {@link subagentLimits}),
- * read fresh: its children's token counter at or over the cap, its dispatches (follow-ups
- * included) at the cap, or as many active children as may run at once each refuse with the §4.5
- * text. The lock serializes the dispatches of one run, so the counts cannot race.
+ * The result text of a child run that ended before its parent's call got a result and was never
+ * delivered (agent map spec, rc upgrade: a foreground-era dispatch whose rc finisher wrote
+ * `subagent_finished` and resumed the parent): the child's report (`childResult`), with the
+ * parent's `subagent_finished` appended in this transaction when it is missing (idempotent by its
+ * key), so the undelivered sweep never delivers it a second time. Null when the parent already
+ * has a delivery for the run (it carries the result) or the run has no terminal event yet.
  */
-async function commit(d, a, plan, 
-/** Writes the child's events; `checked` is the org agent version the in-lock gates passed. */
-child) {
+async function rcFinishedResult(d, row) {
+    const delivered = await d.db
+        .selectFrom("conversation_events")
+        .select("seq")
+        .where("conversation_id", "=", row.parentConversationId)
+        .where("type", "=", "subagent_delivery")
+        .where(sql `payload ->> 'childRunId'`, "=", row.childRunId)
+        .limit(1)
+        .executeTakeFirst();
+    if (delivered)
+        return null;
+    const r = await childResult(d.eventLog, row);
+    if (!r)
+        return null;
+    await d.eventLog.appendIn(row.parentConversationId, [finishedEvent(row, r.finished)]);
+    return r.content;
+}
+/**
+ * {@link commit}'s transaction (run by `SubagentsService.commitDispatch`, `d.db` its handle).
+ * Null when `child` refused.
+ */
+export async function commitDispatchIn(d, a, plan, child) {
     const { ctx, callId, input } = a;
     const childRunId = randomUUID();
-    const out = await d.db.transaction().execute(async (t) => {
-        // the documented order, conversation row then run row (run-finish.ts, abortWaiting): the
-        // append to the parent below takes the conversation row, so it is taken first here, or a stop
-        // racing this commit could deadlock (final review m2); the child's row comes last
-        await t
-            .selectFrom("conversations")
-            .select("id")
-            .where("id", "=", ctx.conversationId)
-            .forUpdate()
-            .executeTakeFirst();
-        const parent = await t
+    const t = d.db;
+    // the documented order, conversation row then run row (run-finish.ts, abortWaiting): the
+    // append to the parent below takes the conversation row, so it is taken first here, or a stop
+    // racing this commit could deadlock (final review m2); the child's row comes last
+    await t
+        .selectFrom("conversations")
+        .select("id")
+        .where("id", "=", ctx.conversationId)
+        .forUpdate()
+        .executeTakeFirst();
+    const parent = await t
+        .selectFrom("runs")
+        .select(["status", "subagent_tokens_used", "budget_run_id"])
+        .where("id", "=", ctx.runId)
+        .forUpdate()
+        .executeTakeFirst();
+    const existing = await t
+        .selectFrom("subagent_dispatches as sd")
+        .leftJoin("runs as cr", "cr.id", "sd.child_run_id")
+        .select(["sd.child_run_id", "sd.child_conversation_id", "cr.status", "cr.trigger_seq"])
+        .where("sd.parent_run_id", "=", ctx.runId)
+        .where("sd.parent_call_id", "=", callId)
+        .executeTakeFirst();
+    if (existing) {
+        // An `Agent` call's result was written with its first dispatch (this returns it). A call
+        // dispatched before `Agent` ran in the background (a foreground wait in flight across the
+        // upgrade) gets the immediate result now, so the log never keeps it unpaired; such a call
+        // reaches here again through the pipeline's policy stages, so it may ask for approval again.
+        let result = null;
+        if (a.forSkill === undefined) {
+            // an rc child that already ended under the foreground wait, whose rc finisher wrote
+            // `subagent_finished` and resumed this run (no delivery; the sweep never delivers a run with
+            // `subagent_finished`): its report is this call's result, as the rc gave it, or it is lost.
+            // Only while the call has no result: a call that has one (a background dispatch's second
+            // holder) keeps it, and its child's finish stays to its delivery or the undelivered sweep.
+            const resultKey = resultEvent(ctx, callId, AGENT_TOOL, "").idemKey;
+            const finished = a.sent === undefined &&
+                existing.status !== null &&
+                !isActiveStatus(existing.status) &&
+                (await d.eventLog.findByIdem(ctx.conversationId, resultKey)) === undefined
+                ? await rcFinishedResult(d, {
+                    parentRunId: ctx.runId,
+                    parentCallId: callId,
+                    parentConversationId: ctx.conversationId,
+                    childConversationId: existing.child_conversation_id,
+                    childRunId: existing.child_run_id,
+                })
+                : null;
+            const [ev] = await d.eventLog.appendIn(ctx.conversationId, [
+                resultEvent(ctx, callId, a.call?.toolKey ?? AGENT_TOOL, finished ?? a.sent?.content ?? agentStartedText(existing.child_conversation_id)),
+            ]);
+            if (ev?.type === "tool_result")
+                result = { content: ev.payload.content, seq: ev.seq };
+        }
+        return {
+            kind: "existing",
+            childRunId: existing.child_run_id,
+            childConversationId: existing.child_conversation_id,
+            result,
+            // still queued: the first holder may have died before its enqueue (review M4)
+            requeue: existing.status === "queued" && existing.trigger_seq !== null
+                ? {
+                    conversationId: existing.child_conversation_id,
+                    seq: Number(existing.trigger_seq),
+                }
+                : null,
+        };
+    }
+    if (parent?.status !== "running")
+        return { kind: "stopped" };
+    // the tree's budget run (agent map spec §6), locked after the parent run so the dispatches of
+    // every run of one tree serialize on it; the parent run itself when it opened the window
+    const budgetRunId = parent.budget_run_id ?? ctx.runId;
+    const tokensUsed = budgetRunId === ctx.runId
+        ? parent.subagent_tokens_used
+        : ((await t
             .selectFrom("runs")
-            .select(["status", "subagent_tokens_used"])
-            .where("id", "=", ctx.runId)
+            .select("subagent_tokens_used")
+            .where("id", "=", budgetRunId)
             .forUpdate()
-            .executeTakeFirst();
-        const existing = await t
-            .selectFrom("subagent_dispatches as sd")
-            .leftJoin("runs as cr", "cr.id", "sd.child_run_id")
-            .select(["sd.child_run_id", "sd.child_conversation_id", "cr.status", "cr.trigger_seq"])
-            .where("sd.parent_run_id", "=", ctx.runId)
-            .where("sd.parent_call_id", "=", callId)
-            .executeTakeFirst();
-        if (existing) {
-            return {
-                kind: "existing",
-                childRunId: existing.child_run_id,
-                // still queued: the first holder may have died before its enqueue (review M4)
-                requeue: existing.status === "queued" && existing.trigger_seq !== null
-                    ? {
-                        conversationId: existing.child_conversation_id,
-                        seq: Number(existing.trigger_seq),
-                    }
-                    : null,
-            };
-        }
-        if (parent?.status !== "running")
-            return { kind: "stopped" };
-        const limit = await limitRefusal(t, d, ctx, parent.subagent_tokens_used);
-        if (limit !== null)
-            return { kind: "limit", content: limit };
-        let checked;
-        if (plan.source === "agent") {
-            // the org agent's gates again, under the parent run's lock, with both agents' rows held
-            // FOR SHARE (in id order) so a concurrent save of either serializes with this dispatch
-            await t
-                .selectFrom("agents")
-                .select("id")
-                .where("id", "in", [ctx.agentId, plan.agentId])
-                .orderBy("id")
-                .forShare()
-                .execute();
-            const gates = await orgAgentGates(t, a, plan.agentId, plan.agentType, plan.resumed);
-            if ("refused" in gates)
-                return { kind: "gate", outcome: gates.refused };
-            checked = gates.checked;
-        }
-        const task = await child(t, checked);
-        if (task === null)
-            return null;
+            .executeTakeFirst())?.subagent_tokens_used ?? 0);
+    const limit = await limitRefusal(t, d, ctx, budgetRunId, tokensUsed, a.sent?.refusals ?? AGENT_REFUSALS);
+    if (limit !== null)
+        return { kind: "limit", content: limit };
+    let checked;
+    if (plan.source === "agent") {
+        // the org agent's gates again, under the parent run's lock, with both agents' rows held
+        // FOR SHARE (in id order) so a concurrent save of either serializes with this dispatch
         await t
-            .insertInto("runs")
-            .values({
-            id: childRunId,
-            conversation_id: plan.childConversationId,
-            status: "queued",
-            agent_version: plan.agentVersion,
-            trigger_account_id: ctx.accountId,
-            trigger_seq: task.seq,
-        })
-            .execute();
-        await t
-            .insertInto("subagent_dispatches")
-            .values({
-            parent_run_id: ctx.runId,
-            parent_call_id: callId,
-            parent_conversation_id: ctx.conversationId,
-            step: ctx.step,
-            child_conversation_id: plan.childConversationId,
-            child_run_id: childRunId,
-            resumed: plan.resumed,
-        })
+            .selectFrom("agents")
+            .select("id")
+            .where("id", "in", [ctx.agentId, plan.agentId])
+            .orderBy("id")
+            .forShare()
             .execute();
-        const [dispatched] = await d.eventLog.append(ctx.conversationId, [
-            {
-                type: "subagent_dispatched",
-                runId: ctx.runId,
-                idemKey: dispatchedIdemKey(ctx.runId, callId),
-                payload: {
-                    step: ctx.step,
-                    callId,
-                    subagentId: plan.childConversationId,
-                    childRunId,
-                    agentType: plan.agentType,
-                    description: input.description,
-                    resumed: plan.resumed,
-                    model: { provider: plan.model.provider, model: plan.model.model },
-                    ...(plan.tierFallback && { tierFallback: true }),
-                    ...(a.forSkill !== undefined && { invokedSeq: a.forSkill.seq }),
-                },
+        const gates = await orgAgentGates(t, a, plan.agentId, plan.agentType, plan.resumed);
+        if ("refused" in gates)
+            return { kind: "gate", outcome: gates.refused };
+        checked = gates.checked;
+    }
+    const task = await child(t, checked);
+    if (task === null)
+        return null;
+    await t
+        .insertInto("runs")
+        .values({
+        id: childRunId,
+        conversation_id: plan.childConversationId,
+        status: "queued",
+        agent_version: plan.agentVersion,
+        trigger_account_id: ctx.accountId,
+        trigger_seq: task.seq,
+        budget_run_id: budgetRunId,
+    })
+        .execute();
+    await t
+        .insertInto("subagent_dispatches")
+        .values({
+        parent_run_id: ctx.runId,
+        parent_call_id: callId,
+        parent_conversation_id: ctx.conversationId,
+        step: ctx.step,
+        child_conversation_id: plan.childConversationId,
+        child_run_id: childRunId,
+        resumed: plan.resumed,
+        budget_run_id: budgetRunId,
+        for_skill: a.forSkill !== undefined,
+    })
+        .execute();
+    // an org agent runs on its own model (§5.4): a `model` on the call was ignored
+    const ownModel = plan.source === "agent" && input.model !== undefined;
+    const content = a.sent?.content ?? agentStartedText(plan.childConversationId, { ownModel });
+    const parentEvents = await d.eventLog.appendIn(ctx.conversationId, [
+        {
+            type: "subagent_dispatched",
+            runId: ctx.runId,
+            idemKey: dispatchedIdemKey(ctx.runId, callId),
+            payload: {
+                step: ctx.step,
+                callId,
+                subagentId: plan.childConversationId,
+                childRunId,
+                agentType: plan.agentType,
+                description: input.description,
+                resumed: plan.resumed,
+                model: { provider: plan.model.provider, model: plan.model.model },
+                ...(plan.tierFallback && { tierFallback: true }),
+                ...(a.forSkill !== undefined && { invokedSeq: a.forSkill.seq }),
             },
-        ], t);
+        },
+        // an `Agent` call's result is immediate (agent map spec §4.1): the sub-agent works in the
+        // background and reports through `subagent_delivery`; a fork invocation has no tool call
+        ...(a.forSkill === undefined
+            ? [resultEvent(ctx, callId, a.call?.toolKey ?? AGENT_TOOL, content)]
+            : []),
+    ]);
+    await audit(t, {
+        actorAccountId: ctx.accountId,
+        orgId: ctx.orgId,
+        action: "subagent.dispatched",
+        target: plan.childConversationId,
+        detail: {
+            parentConversationId: ctx.conversationId,
+            parentRunId: ctx.runId,
+            callId,
+            agentType: plan.agentType,
+            source: plan.source,
+            ...(plan.source === "agent" && {
+                agentId: plan.agentId,
+                agentVersion: plan.agentVersion,
+            }),
+            resumed: plan.resumed,
+            childRunId,
+        },
+    });
+    if (a.forSkill === undefined) {
         await audit(t, {
             actorAccountId: ctx.accountId,
             orgId: ctx.orgId,
-            action: "subagent.dispatched",
-            target: plan.childConversationId,
+            action: "tool.called",
+            target: ctx.conversationId,
             detail: {
-                parentConversationId: ctx.conversationId,
-                parentRunId: ctx.runId,
+                toolKey: a.sent !== undefined ? SEND_MESSAGE : AGENT_TOOL,
+                isError: false,
+                durationMs: a.call === undefined ? null : Math.max(0, Date.now() - a.call.startedAt),
+                agentId: ctx.agentId,
+                agentVersion: ctx.agentVersion,
+                conversationId: ctx.conversationId,
+                runId: ctx.runId,
                 callId,
-                agentType: plan.agentType,
-                source: plan.source,
-                ...(plan.source === "agent" && {
-                    agentId: plan.agentId,
-                    agentVersion: plan.agentVersion,
-                }),
-                resumed: plan.resumed,
-                childRunId,
+                ...a.call?.authorization,
             },
         });
-        return {
-            kind: "written",
-            childSeq: task.seq,
-            parentSeq: dispatched.seq,
-        };
-    });
+    }
+    return {
+        kind: "written",
+        childRunId,
+        childSeq: task.seq,
+        parentSeq: Math.max(...parentEvents.map((e) => e.seq)),
+        content,
+    };
+}
+/**
+ * The immediate `tool_result` of an `Agent` call ({@link agentStartedText}) or of a `SendMessage`
+ * that started an idle sub-agent, idempotent by the call.
+ */
+const resultEvent = (ctx, callId, toolKey, content) => ({
+    type: "tool_result",
+    runId: ctx.runId,
+    idemKey: `tool_result:${ctx.runId}:${callId}`,
+    payload: { step: ctx.step, callId, toolKey, content, isError: false },
+});
+export async function commit(d, a, plan, 
+/** Writes the child's events; `checked` is the org agent version the in-lock gates passed. */
+child) {
+    const { ctx } = a;
+    const out = await d.commitDispatch(a, plan, child);
     if (out === null)
         return null;
     if (out.kind === "existing") {
@@ -453,17 +487,26 @@ child) {
                 err,
             }));
         }
-        return { kind: "dispatched", childRunId: out.childRunId };
+        if (out.result !== null)
+            await d.eventLog.notify(ctx.conversationId, out.result.seq);
+        return {
+            kind: "dispatched",
+            childRunId: out.childRunId,
+            childConversationId: out.childConversationId,
+            content: out.result?.content ?? a.sent?.content ?? agentStartedText(out.childConversationId),
+        };
     }
     // the result is never read: the run is over
-    if (out.kind === "stopped")
-        return refused(AGENT_REFUSALS.notAvailableHere);
+    if (out.kind === "stopped") {
+        return refused((a.sent?.refusals ?? AGENT_REFUSALS).notAvailableHere);
+    }
     if (out.kind === "limit")
         return refused(out.content);
     if (out.kind === "gate")
         return out.outcome;
     await d.eventLog.notify(plan.childConversationId, out.childSeq);
     await d.eventLog.notify(ctx.conversationId, out.parentSeq);
+    const childRunId = out.childRunId;
     const jobId = runJobId(plan.childConversationId, out.childSeq);
     try {
         await d.enqueue({ runId: childRunId, conversationId: plan.childConversationId }, jobId, "subagent");
@@ -472,31 +515,54 @@ child) {
         // the dispatch is committed: the wait sweep re-enqueues the queued child run
         d.log.error("cannot enqueue sub-agent run; the sweep retries", { childRunId, jobId, err });
     }
-    return { kind: "dispatched", childRunId };
+    return {
+        kind: "dispatched",
+        childRunId,
+        childConversationId: plan.childConversationId,
+        content: out.content,
+    };
 }
 /**
- * The §4.5 refusal of a dispatch the parent run's limits forbid, or null. Runs under the parent
- * run's row lock; `tokensUsed` is the counter read with that lock.
+ * The §4.5 refusal of a dispatch the limits forbid, or null (agent map spec §6). Runs under the
+ * parent conversation's, the parent run's and the budget run's row locks; `tokensUsed` is the
+ * budget run's counter read with its lock. A dispatch from a run at `maxDepth` is refused (the
+ * limit may have been lowered since the call's definition was frozen); tokens and dispatches
+ * (follow-ups included) count the whole tree on its budget run; concurrency counts the child
+ * conversations of the parent conversation that have an active run, whatever started that run.
  */
-async function limitRefusal(t, d, ctx, tokensUsed) {
+async function limitRefusal(t, d, ctx, budgetRunId, tokensUsed, texts) {
     const limits = await subagentLimits(t, d.config, ctx.orgId);
-    if (Number(tokensUsed) >= limits.maxTokensPerRun) {
-        return AGENT_REFUSALS.budget(limits.maxTokensPerRun);
+    if (runDepth(ctx) >= limits.maxDepth)
+        return texts.depthLimit(limits.maxDepth);
+    // 0: no limit (the deployment config or the org's override)
+    if (limits.maxTokensPerRun > 0 && Number(tokensUsed) >= limits.maxTokensPerRun) {
+        return texts.budget(limits.maxTokensPerRun);
     }
-    const counts = await t
-        .selectFrom("subagent_dispatches as sd")
-        .innerJoin("runs as cr", "cr.id", "sd.child_run_id")
-        .select([
-        sql `count(*)`.as("total"),
-        sql `count(*) FILTER (WHERE cr.status IN (${sql.join(ACTIVE_RUN_STATUSES)}))`.as("active"),
-    ])
-        .where("sd.parent_run_id", "=", ctx.runId)
-        .executeTakeFirstOrThrow();
-    if (Number(counts.total) >= limits.maxDispatchesPerRun) {
-        return AGENT_REFUSALS.tooManyDispatches(limits.maxDispatchesPerRun);
+    if (limits.maxDispatchesPerRun > 0) {
+        const total = await t
+            .selectFrom("subagent_dispatches")
+            .select(sql `count(*)`.as("n"))
+            .where("budget_run_id", "=", budgetRunId)
+            .executeTakeFirstOrThrow();
+        if (Number(total.n) >= limits.maxDispatchesPerRun) {
+            return texts.tooManyDispatches(limits.maxDispatchesPerRun);
+        }
     }
-    if (Number(counts.active) >= limits.maxConcurrentPerRun) {
-        return AGENT_REFUSALS.tooManyConcurrent(limits.maxConcurrentPerRun);
+    // every child conversation with an active run of any origin: a dispatch, a message it never
+    // absorbed (a continuation run) or a wake run all hold its slot
+    const active = await t
+        .selectFrom("conversations as c")
+        .select(sql `count(*)`.as("n"))
+        .where("c.parent_conversation_id", "=", ctx.conversationId)
+        .where("c.kind", "=", "subagent")
+        .where("c.deleted_at", "is", null)
+        .where(({ exists, selectFrom }) => exists(selectFrom("runs as cr")
+        .select(sql `1`.as("one"))
+        .whereRef("cr.conversation_id", "=", "c.id")
+        .where("cr.status", "in", ACTIVE_RUN_STATUSES)))
+        .executeTakeFirstOrThrow();
+    if (Number(active.n) >= limits.maxConcurrentPerConversation) {
+        return texts.tooManyConcurrent(limits.maxConcurrentPerConversation);
     }
     return null;
 }