@xrkseek/harness 0.5.9 → 0.5.11

package/node_modules/@xrkseek/server-face/dist/subagent-tools.js

@@ -1,18 +1,21 @@
 import { SUBAGENT_ROUTING_PROMPT_TEXT } from "@xrkseek/core-tools";
 import { listPendingAdmits, readSessionEvents, } from "@xrkseek/core-session";
 import { dispatchFaceMethod } from "./dispatch.js";
-import { lastAssistantBodyText } from "./adapt/subagent-notice.js";
+import { formatChildOutcome, lastAssistantBodyText, lastModelRetryNotice, } from "./adapt/subagent-notice.js";
 import { boundChildAnswer, SUBAGENT_ANSWER_INLINE_BYTES, } from "./adapt/subagent-answer-bound.js";
 export { boundChildAnswer, SUBAGENT_ANSWER_INLINE_BYTES };
+import { subagentOwnedEvents } from "./subagent-registry.js";
 import { DEFAULT_MAX_ACTIVE_CHILDREN, DEFAULT_MAX_DEPTH, resolveAgentPresetProfile, } from "./presets-catalog.js";
 import { effectiveSessionAgentPreset } from "./session-agent-preset.js";
 import { resolveSessionCwd } from "./session-cwd.js";
+import { canvasWorkspaceIdForSession } from "./canvas-tools.js";
+import { formatRosterCatalog } from "./agent-roster-store.js";
 import { ExternalAgentError, parseExternalAgentKind, parseExternalAgentProduct, runExternalAgentTurn, supportsExternalContinuable, startExternalContinuable, isChildSessionActive, } from "./external-agent-runtime.js";
 import { createSubagentWorktree, finalizeSubagentWorktree, formatWorktreeResult, worktreeContextNote, worktreeSkippedForRemote, } from "./subagent-worktree.js";
-import { resolveSessionModelSelection } from "./model-catalog.js";
+import { resolveSessionModelSelection, resolveSubagentModelSetting, } from "./model-catalog.js";
 import { selectSessionModel } from "./select-session-model.js";
 import { appendOutputContract, buildOutputSchemaRetryMessage, coerceOutputSchema, validateOutputAgainstSchema, } from "./agent-team-output.js";
-import { applySpawnRoleReminder, parseAgentTeamSpawnRole, } from "./agent-team-roles.js";
+import { applySubagentSpawnPreamble, parseAgentTeamSpawnRole, rootUserAuthorizationBlock, } from "./agent-team-roles.js";
 import { isAgentTeamRole, } from "./agent-team-graph.js";
 import { bindRalphTool } from "./ralph-tool.js";
 const FOREGROUND_WAIT_MS = 10 * 60 * 1000;
@@ -106,19 +109,45 @@ async function waitDrainIdle(runtime, sessionId, signal, timeoutMs = FOREGROUND_
         // for its child would otherwise hang the tool batch forever. The join
         // stays attached in the background — the caller cancels the child right
         // after this rejects, which is what actually drains it.
-        await abortable(run(sessionId), signal);
+        //
+        // The race must also carry the timeout: latch.run() joins until the
+        // child's chain *actually* settles, so a child stuck on a tool that
+        // ignores abort pins the parent's turn for as long as it hangs. The
+        // timeout used to apply only to the polling fallback below — i.e. never
+        // on the Host path, which always has run().
+        await raceDeadline(abortable(run(sessionId), signal), timeoutMs, sessionId);
         return;
     }
-    const deadline = Date.now() + timeoutMs;
-    while (runtime.drain.isActive(sessionId)) {
-        if (signal?.aborted) {
-            throw new DOMException("aborted", "AbortError");
-        }
-        if (Date.now() > deadline) {
-            throw new Error(`subagent timed out waiting for session ${sessionId}`);
+    // Same deadline semantics as the hub.run branch above — one throw site, one
+    // message, so a caller (or a log grep) cannot tell the two paths apart.
+    await raceDeadline((async () => {
+        while (runtime.drain.isActive(sessionId)) {
+            if (signal?.aborted) {
+                throw new DOMException("aborted", "AbortError");
+            }
+            await new Promise((r) => setTimeout(r, POLL_MS));
         }
-        await new Promise((r) => setTimeout(r, POLL_MS));
-    }
+    })(), timeoutMs, sessionId);
+}
+/**
+ * Reject once `timeoutMs` elapses, naming the session so the failure reads
+ * like the polling branch's. The wrapped promise keeps running — the caller
+ * cancels the child right after, which is what actually drains it.
+ */
+function raceDeadline(promise, timeoutMs, sessionId) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return promise;
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`subagent timed out waiting for session ${sessionId}`)), timeoutMs);
+    });
+    return Promise.race([
+        promise.finally(() => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }),
+        timedOut,
+    ]);
 }
 /** Reject as soon as `signal` aborts; the wrapped promise keeps running. */
 function abortable(promise, signal) {
@@ -146,6 +175,27 @@ function abortError(reason) {
     err.name = "AbortError";
     return err;
 }
+/**
+ * How a parent gets work back out of a child that outlived the foreground
+ * wait. One place on purpose: background spawn, timeout salvage and failure
+ * replies must not drift apart, or a parent learns the recovery verbs only
+ * on the happy path.
+ */
+export function childResumeHint(childId) {
+    return (`Child session \`${childId}\` is not gone: \`wait_agent\` keeps waiting for it, ` +
+        `\`session_read\` replays its history, \`session_trace\` shows its lineage, ` +
+        `\`list_agents\` its state, and \`followup_task\` wakes a new turn on it. Read it ` +
+        `before spawning a replacement so the new task does not repeat work it already did.`);
+}
+/**
+ * The slice of a child's log the parent owns: seeded parent text never counts.
+ * One read, two projections (`lastAssistantBodyText` for the salvaged answer,
+ * `lastModelRetryNotice` for what its model request was doing).
+ */
+export function childOwnedEvents(runtime, childId) {
+    const link = runtime.subagents.getByChild(childId);
+    return subagentOwnedEvents(link, readSessionEvents(runtime.store, childId));
+}
 function formatSubagentAbortReason(reason) {
     if (reason === undefined || reason === null)
         return "aborted";
@@ -193,29 +243,88 @@ function countActiveChildren(runtime, parentSessionId) {
     }
     return n;
 }
+/**
+ * Undo a half-made spawn. `session.create` / `session.fork` already made the
+ * child durable and registered its link, so any failure between there and a
+ * successful `session.prompt` would otherwise leave an empty session in the
+ * sidebar and a permanent entry in the catalog / quota counts.
+ */
+async function discardUnstartedChild(runtime, childSessionId) {
+    runtime.subagents.detach(childSessionId);
+    runtime.agentTeams.removeNode(childSessionId);
+    runtime.agentTeamTasks.forgetByChild(childSessionId);
+    runtime.sessionCwds.delete(childSessionId);
+    try {
+        await dispatchFaceMethod(runtime, "session.cancel", `tool-sa-discard-${childSessionId}`, { sessionId: childSessionId, cascade: true });
+    }
+    catch {
+        /* best effort: the log is dropped either way */
+    }
+    try {
+        runtime.store.delete?.(childSessionId);
+    }
+    catch {
+        /* store without delete / already gone */
+    }
+    await Promise.resolve(runtime.invalidateAgent?.(childSessionId)).catch(() => undefined);
+}
+/**
+ * Reject a caller-supplied `task_id` another child already owns. Checked
+ * *before* the child exists: rebinding the card would misdirect that child's
+ * later idle notice (`completeByChild` keys on childSessionId).
+ */
+function taskIdConflict(runtime, taskIdHint) {
+    if (!taskIdHint)
+        return undefined;
+    const boundChild = runtime.agentTeamTasks.get(taskIdHint)?.childSessionId;
+    return boundChild
+        ? `subagent: task_id ${taskIdHint} is already bound to child ${boundChild}; use a different task_id`
+        : undefined;
+}
 /**
  * Optional LLM target for a freshly created child.
- * `model` alone inherits the parent's current provider; `provider` alone is rejected.
+ *
+ * Precedence: the call's own args → the fleet-wide `agent-loop.subagentModel`
+ * setting → the parent's own route. `model` alone inherits the parent's current
+ * provider; `provider` alone is rejected.
  */
 async function applySubagentModelOverride(runtime, args) {
     const providerRaw = args.provider?.trim() ?? "";
     const modelRaw = args.model?.trim() ?? "";
     const effortRaw = args.reasoningEffort?.trim() ?? "";
-    if (!providerRaw && !modelRaw && !effortRaw)
+    // Refuse loudly rather than silently: an explicit model on an external
+    // child would otherwise read as honored when the subprocess ignores it.
+    if (args.skipExternal && (providerRaw || modelRaw || effortRaw)) {
+        return {
+            ok: false,
+            message: "subagent: model / provider / reasoning_effort do not apply to an external runtime " +
+                "(acp / app-server / claude-code) — the child CLI picks its own model. " +
+                "Drop the argument, or use runtime=in-process.",
+        };
+    }
+    // No per-call pin: the setting owns the route, and an empty setting leaves
+    // the child on the parent's selection that `session.create` copied.
+    const fleet = providerRaw || modelRaw || effortRaw
+        ? undefined
+        : resolveSubagentModelSetting(runtime);
+    if (!providerRaw && !modelRaw && !effortRaw && !fleet)
         return { ok: true };
-    if (!modelRaw) {
+    const model = modelRaw || fleet?.model || "";
+    const effort = effortRaw || fleet?.reasoningEffort || "";
+    if (!model) {
         return {
             ok: false,
             message: "subagent: model is required when overriding provider or reasoning_effort",
         };
     }
     const provider = providerRaw
+        || fleet?.provider
         || resolveSessionModelSelection(runtime, args.parentSessionId).provider;
     const selected = await selectSessionModel(runtime, {
         sessionId: args.childSessionId,
         provider,
-        model: modelRaw,
-        ...(effortRaw ? { reasoningEffort: effortRaw } : {}),
+        model,
+        ...(effort ? { reasoningEffort: effort } : {}),
     });
     if (!selected.ok) {
         return {
@@ -226,27 +335,54 @@ async function applySubagentModelOverride(runtime, args) {
     return { ok: true };
 }
 function createSubagentTool(options) {
-    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
-    const maxActiveChildren = options.maxActiveChildren ?? DEFAULT_MAX_ACTIVE_CHILDREN;
+    /**
+     * Ceilings for one call. Resolved live (not frozen at bind time) so the
+     * numbers `analytics` / `list_agents` report are the numbers spawn
+     * enforces — a Settings change takes effect on the next call instead of
+     * at the next agent rebuild. The bind options are a test-only override.
+     */
+    const caps = () => {
+        const quota = resolveSubagentQuota(options.runtime, options.parentSessionId);
+        return {
+            maxDepth: options.maxDepth ?? quota.maxDepth,
+            maxActive: options.maxActiveChildren ?? quota.maxActive,
+            active: quota.active,
+        };
+    };
+    const foregroundWaitMs = options.foregroundWaitMs ?? FOREGROUND_WAIT_MS;
+    const description = "Delegate a self-contained task to a teammate subagent (separate session, same workspace as this session unless worktree:true). " +
+        "Use for focused independent work — research, a scoped implementation, analysis, or read-only review — " +
+        "so it does not consume this conversation's context. " +
+        "By default the child cannot see this chat — give a complete standalone prompt (paths, goals, constraints, persona). " +
+        "Do not tell the child to read AGENTS.md to discover who it is; Face prepends parent/child session ids, mode, role, and cwd. " +
+        "Set inherit_context true to seed the child with this session's completed turns only " +
+        "(the current in-flight turn is excluded). " +
+        "By default waits for the result (one-shot, no later human messages on that child). " +
+        "That foreground wait is bounded (10 min by default): on expiry the child is NOT discarded — " +
+        "whatever answer it already wrote is salvaged into this result and the child id stays readable " +
+        "(session_read / followup_task), so prefer run_in_background for genuinely long work instead of retrying blind. " +
+        "Set run_in_background true for a continuable child (chat companion / long task) and continue via followup_task / send_message. " +
+        "Prefer Agent Team member_id (catalog on this tool and team_list) over restating playbook or tools; " +
+        "optional role (worker|researcher|reviewer|lead) is only the fallback when no member fits; " +
+        "optional output_schema appends an OUTPUT CONTRACT and validates the final JSON; " +
+        "optional task_id / task_name register the work on the Agent Teams task board. " +
+        "Optional provider / model / reasoning_effort pin the child's LLM (model alone keeps the parent provider). " +
+        "Optional runtime: omit or in-process (default Face child); acp / app-server / claude-code spawn an external subprocess. " +
+        "acp / app-server support run_in_background + followup_task / send_message / wait_agent / interrupt_agent on the same list surface; claude-code remains one-shot print. " +
+        "The child's answer is returned inline in this tool result when short. " +
+        "Only when the UTF-8 body exceeds ~12KB does Face spill it under ~/.xrk/spill/tool-outputs/ " +
+        "and replace the body with a path + head/tail preview — then read_file that path. " +
+        "An empty or missing tool-outputs directory means nothing spilled; the full answer is already in this result (or the session event log), not on disk.";
     return {
         name: "subagent",
-        description: "Delegate a self-contained task to a teammate subagent (separate session/context). " +
-            "Use for focused independent work — research, a scoped implementation, analysis, or read-only review — " +
-            "so it does not consume this conversation's context. " +
-            "By default the child cannot see this chat — give a complete standalone prompt. " +
-            "Set inherit_context true to seed the child with this session's completed turns only " +
-            "(the current in-flight turn is excluded). " +
-            "By default waits for the result; set run_in_background true to get a durable child id and continue later via send_message. " +
-            "Optional role (worker|researcher|reviewer|lead) prefixes a role reminder; " +
-            "optional output_schema appends an OUTPUT CONTRACT and validates the final JSON; " +
-            "optional task_id / task_name register the work on the Agent Teams task board. " +
-            "Optional provider / model / reasoning_effort pin the child's LLM (model alone keeps the parent provider). " +
-            "Optional runtime: omit or in-process (default Face child); acp / app-server / claude-code spawn an external subprocess. " +
-            "acp / app-server support run_in_background + followup_task / send_message / wait_agent / interrupt_agent on the same list surface; claude-code remains one-shot print. " +
-            "The child's answer is returned inline in this tool result when short. " +
-            "Only when the UTF-8 body exceeds ~12KB does Face spill it under ~/.xrk/spill/tool-outputs/ " +
-            "and replace the body with a path + head/tail preview — then read_file that path. " +
-            "An empty or missing tool-outputs directory means nothing spilled; the full answer is already in this result (or the session event log), not on disk.",
+        description,
+        dynamicSchema: () => {
+            const ws = canvasWorkspaceIdForSession(options.runtime, options.parentSessionId);
+            const catalog = formatRosterCatalog(options.runtime.agentRoster.listVisible(ws));
+            return {
+                description: `${description}\n\nPrefer member_id from this Agent Team catalog:\n${catalog}`,
+            };
+        },
         parameters: {
             type: "object",
             properties: {
@@ -256,12 +392,19 @@ function createSubagentTool(options) {
                 },
                 prompt: {
                     type: "string",
-                    description: "Task for the subagent. When inherit_context is false (default), include paths, goals, and constraints — it does not see this conversation. When inherit_context is true, build on the seeded completed turns.",
+                    description: "Task for the subagent. Put the actual job here (paths, goals, constraints, any persona). " +
+                        "When inherit_context is false (default), the child does not see this conversation. " +
+                        "When inherit_context is true, build on the seeded completed turns. " +
+                        "Face already injects parent/child session ids — do not send the child to AGENTS.md to learn its role.",
                 },
                 inherit_context: {
                     type: "boolean",
                     description: "If true, seed the child with this session's completed-turn prefix (open turn excluded). Default false. Ignored for external runtimes.",
                 },
+                member_id: {
+                    type: "string",
+                    description: "Agent Team member id. Face applies that member's tools, inject, and playbook — the same three surfaces the parent already edits. Prefer this over restating those in prompt.",
+                },
                 run_in_background: {
                     type: "boolean",
                     description: "If true, return the child session id immediately (continuable). Default false (wait for the child's final answer). Supported for in-process and external acp / app-server (not claude-code).",
@@ -329,10 +472,11 @@ function createSubagentTool(options) {
                     isError: true,
                 };
             }
-            const prompt = String(a.prompt ?? "").trim();
-            if (!prompt) {
+            const promptBare = String(a.prompt ?? "").trim();
+            if (!promptBare) {
                 return { content: "subagent: empty prompt", isError: true };
             }
+            let prompt = promptBare;
             const roleRaw = a.role ?? a.agent_type;
             let spawnRole;
             if (roleRaw !== undefined && String(roleRaw).trim()) {
@@ -344,6 +488,23 @@ function createSubagentTool(options) {
                     };
                 }
             }
+            const memberId = String(a.member_id ?? "").trim();
+            let rosterMember;
+            if (memberId) {
+                const workspaceId = canvasWorkspaceIdForSession(options.runtime, options.parentSessionId);
+                rosterMember = options.runtime.agentRoster.get(workspaceId, memberId);
+                if (!rosterMember) {
+                    return {
+                        content: `subagent: unknown member_id "${memberId}" (team_list first)`,
+                        isError: true,
+                    };
+                }
+                prompt = `${rosterMember.playbook.trim()}\n\nTASK:\n${promptBare}`;
+                if (spawnRole === undefined && rosterMember.role !== "default") {
+                    spawnRole = rosterMember.role;
+                }
+            }
+            const memberSpawn = memberId ? { memberId } : {};
             const schemaCoerce = coerceOutputSchema(a.output_schema);
             if (schemaCoerce.error) {
                 return {
@@ -361,20 +522,35 @@ function createSubagentTool(options) {
             }
             if (runtimeKind !== "in-process") {
                 const background = a.run_in_background === true;
+                // One cwd for every external branch. `resolveSessionCwd` already
+                // falls back to the workspace root, so the child runs where the
+                // parent runs instead of always at the root (which silently broke
+                // any session that had moved into another workspace).
+                const externalCwd = resolveSessionCwd(options.runtime, options.parentSessionId);
                 if (background && !supportsExternalContinuable(runtimeKind)) {
                     return {
                         content: "subagent: run_in_background is not supported for claude-code (print); use acp or app-server",
                         isError: true,
                     };
                 }
+                if (a.worktree === true) {
+                    // Worktree handling lives in the in-process branch below; silently
+                    // dropping the flag would have the child edit the parent's own
+                    // checkout while the caller believed it was isolated.
+                    return {
+                        content: "subagent: worktree is only supported for runtime=in-process " +
+                            "(an external runtime owns its own working directory).",
+                        isError: true,
+                    };
+                }
                 const depth = subagentDepth(options.runtime, options.parentSessionId);
+                const { maxDepth, maxActive: maxActiveChildren, active } = caps();
                 if (depth >= maxDepth) {
                     return {
                         content: `subagent: max depth ${maxDepth} reached (current depth ${depth})`,
                         isError: true,
                     };
                 }
-                const active = countActiveChildren(options.runtime, options.parentSessionId);
                 if (active >= maxActiveChildren) {
                     return {
                         content: `subagent: max active children ${maxActiveChildren} reached (active ${active})`,
@@ -391,6 +567,10 @@ function createSubagentTool(options) {
                             parentSessionId: options.parentSessionId,
                             label,
                             mode: "continuable",
+                            ...memberSpawn,
+                            ...(spawnRole && spawnRole !== "default"
+                                ? { role: spawnRole }
+                                : {}),
                         });
                         if (!created.result.ok) {
                             return {
@@ -407,11 +587,22 @@ function createSubagentTool(options) {
                             ...(typeof a.reasoning_effort === "string"
                                 ? { reasoningEffort: a.reasoning_effort }
                                 : {}),
+                            // An ACP / app-server / claude-code child runs on ITS OWN CLI
+                            // config; a Face-side pin cannot reach it. Recording one anyway
+                            // made `/status` and `list_agents` report a route the subprocess
+                            // never used, so the record is skipped rather than faked.
+                            skipExternal: true,
                         });
                         if (!modelPin.ok) {
+                            await discardUnstartedChild(options.runtime, childId);
                             return { content: modelPin.message, isError: true };
                         }
                         const taskTitle = String(a.task_name ?? "").trim() || label;
+                        const taskIdConflictMsg = taskIdConflict(options.runtime, String(a.task_id ?? "").trim() || undefined);
+                        if (taskIdConflictMsg) {
+                            await discardUnstartedChild(options.runtime, childId);
+                            return { content: taskIdConflictMsg, isError: true };
+                        }
                         const task = options.runtime.agentTeamTasks.open({
                             parentSessionId: options.parentSessionId,
                             title: taskTitle,
@@ -430,7 +621,7 @@ function createSubagentTool(options) {
                             runtime: options.runtime,
                             faceSessionId: childId,
                             kind: runtimeKind,
-                            cwd: resolveSessionCwd(options.runtime, options.parentSessionId) ?? options.runtime.workspaceRoot,
+                            cwd: externalCwd,
                             prompt,
                             background: true,
                             ...(signal ? { signal } : {}),
@@ -454,7 +645,7 @@ function createSubagentTool(options) {
                     }
                     const result = await runExternalAgentTurn({
                         kind: runtimeKind,
-                        cwd: options.runtime.workspaceRoot,
+                        cwd: externalCwd,
                         prompt,
                         ...(signal ? { signal } : {}),
                         ...(options.externalEnv ? { env: options.externalEnv } : {}),
@@ -477,13 +668,13 @@ function createSubagentTool(options) {
                 }
             }
             const depth = subagentDepth(options.runtime, options.parentSessionId);
+            const { maxDepth, maxActive: maxActiveChildren, active } = caps();
             if (depth >= maxDepth) {
                 return {
                     content: `subagent: max depth ${maxDepth} reached (current depth ${depth})`,
                     isError: true,
                 };
             }
-            const active = countActiveChildren(options.runtime, options.parentSessionId);
             if (active >= maxActiveChildren) {
                 return {
                     content: `subagent: max active children ${maxActiveChildren} reached (active ${active})`,
@@ -497,6 +688,14 @@ function createSubagentTool(options) {
                 (background ? "subagent" : "subagent-task");
             const linkMode = background ? "continuable" : "one-shot";
             const parentCwd = resolveSessionCwd(options.runtime, options.parentSessionId);
+            const taskTitle = String(a.task_name ?? "").trim() || label;
+            const taskIdHint = String(a.task_id ?? "").trim() || undefined;
+            // Before anything is allocated: reusing a task_id another child owns
+            // must not leave a worktree or a session behind.
+            const taskIdError = taskIdConflict(options.runtime, taskIdHint);
+            if (taskIdError) {
+                return { content: taskIdError, isError: true };
+            }
             let isolated = null;
             let managedLease = null;
             let worktreeSkip = "";
@@ -528,15 +727,13 @@ function createSubagentTool(options) {
                     }
                 }
             }
-            let childPrompt = applySpawnRoleReminder(prompt, spawnRole);
+            let taskBody = prompt;
             if (outputSchema) {
-                childPrompt = appendOutputContract(childPrompt, outputSchema);
+                taskBody = appendOutputContract(taskBody, outputSchema);
             }
-            childPrompt = isolated
-                ? `${childPrompt}\n\n${worktreeContextNote(isolated)}`
-                : childPrompt;
-            const taskTitle = String(a.task_name ?? "").trim() || label;
-            const taskIdHint = String(a.task_id ?? "").trim() || undefined;
+            taskBody = isolated
+                ? `${taskBody}\n\n${worktreeContextNote(isolated)}`
+                : taskBody;
             const openTask = (childSessionId) => {
                 const task = options.runtime.agentTeamTasks.open({
                     parentSessionId: options.parentSessionId,
@@ -591,14 +788,44 @@ function createSubagentTool(options) {
                     finalizeSubagentWorktree(isolated);
                 }
             };
+            /**
+             * Codex `spawn_guard.rs` (RAII): a half-made spawn is torn down on
+             * EVERY exit path, including an unexpected throw. Explicit
+             * `discardUnstartedChild` calls cover the known failure branches; this
+             * flag + finally is the backstop for anything they miss.
+             */
+            let started = false;
+            const discardIfUnstarted = async () => {
+                if (started || !childId)
+                    return;
+                started = true;
+                dropIsolated();
+                await discardUnstartedChild(options.runtime, childId);
+            };
             let childId;
-            let seedEventCount = 0;
+            /** Fork seed size — bounds the root-evidence slice below. */
+            let seedCut = 0;
             if (inherit) {
-                const forked = await dispatchFaceMethod(options.runtime, "session.fork", `tool-sa-fork-${Date.now()}`, {
-                    sessionId: options.parentSessionId,
-                    linkMode,
-                    label,
-                });
+                // A transport reject (not an RpcResult error) here would strand the
+                // worktree lease allocated above; catch keeps the cleanup total.
+                let forked;
+                try {
+                    forked = await dispatchFaceMethod(options.runtime, "session.fork", `tool-sa-fork-${Date.now()}`, {
+                        sessionId: options.parentSessionId,
+                        linkMode,
+                        label,
+                        ...(spawnRole && spawnRole !== "default"
+                            ? { role: spawnRole }
+                            : {}),
+                    });
+                }
+                catch {
+                    dropIsolated();
+                    return {
+                        content: "subagent seed failed: fork request errored",
+                        isError: true,
+                    };
+                }
                 if (!forked.result.ok) {
                     // No completed turn yet — fall back to a fresh child (DSH fork omits seed).
                     if (forked.result.error.code === "fork-unavailable") {
@@ -606,6 +833,10 @@ function createSubagentTool(options) {
                             parentSessionId: options.parentSessionId,
                             label,
                             mode: linkMode,
+                            ...memberSpawn,
+                            ...(spawnRole && spawnRole !== "default"
+                                ? { role: spawnRole }
+                                : {}),
                         });
                         if (!created.result.ok) {
                             dropIsolated();
@@ -626,7 +857,10 @@ function createSubagentTool(options) {
                 }
                 else {
                     childId = String(forked.result.value.sessionId);
-                    seedEventCount = Number(forked.result.value.eventCount ?? 0);
+                    // Durable seed boundary: every answer read of this child must
+                    // slice from here, or the parent's last reply reads as its answer.
+                    seedCut = Number(forked.result.value.eventCount ?? 0);
+                    options.runtime.subagents.setSeedEventCount(childId, seedCut);
                 }
             }
             else {
@@ -634,6 +868,10 @@ function createSubagentTool(options) {
                     parentSessionId: options.parentSessionId,
                     label,
                     mode: linkMode,
+                    ...memberSpawn,
+                    ...(spawnRole && spawnRole !== "default"
+                        ? { role: spawnRole }
+                        : {}),
                 });
                 if (!created.result.ok) {
                     dropIsolated();
@@ -654,21 +892,65 @@ function createSubagentTool(options) {
                     : {}),
             });
             if (!modelPin.ok) {
-                dropIsolated();
+                await discardIfUnstarted();
                 return { content: modelPin.message, isError: true };
             }
             if (isolated) {
                 options.runtime.sessionCwds.set(childId, isolated.path);
-                await options.runtime.invalidateAgent?.(childId);
+                // Worktree bind failure must not leak the child: swallow and let the
+                // prompt below decide the spawn's fate (or the catch backstop).
+                await Promise.resolve(options.runtime.invalidateAgent?.(childId)).catch(() => undefined);
             }
+            const childPrompt = applySubagentSpawnPreamble({
+                prompt: taskBody,
+                parentSessionId: options.parentSessionId,
+                childSessionId: childId,
+                mode: linkMode,
+                label,
+                ...(spawnRole ? { role: spawnRole } : {}),
+                inheritContext: inherit,
+                cwd: isolated?.path ?? parentCwd,
+                isolatedWorktree: isolated !== null,
+                ...(rosterMember
+                    ? { memberId: rosterMember.id, inject: rosterMember.inject }
+                    : {}),
+                // The human's own asks: a child that only sees the parent's paraphrase
+                // drifts from what was actually authorized (Codex
+                // `control/user_authorization.rs`). A forked child already carries
+                // these in its seeded transcript, so only add them beyond the cut.
+                ...(() => {
+                    const block = rootUserAuthorizationBlock({
+                        parentEvents: readSessionEvents(options.runtime.store, options.parentSessionId),
+                        ...(seedCut > 0 ? { sinceEventCount: seedCut } : {}),
+                    });
+                    return block ? { userAuthorization: block } : {};
+                })(),
+            });
             const task = openTask(childId);
             const worktreeLine = reclaimIsolated;
-            const prompted = await dispatchFaceMethod(options.runtime, "session.prompt", `tool-sa-p-${childId}`, {
-                sessionId: childId,
-                mode: "queue",
-                content: [{ type: "text", text: childPrompt }],
-            });
+            // A transport-level reject (not an RpcResult error) must not leak the
+            // child: the catch backstop tears the half-made spawn down.
+            let prompted;
+            try {
+                prompted = await dispatchFaceMethod(options.runtime, "session.prompt", `tool-sa-p-${childId}`, {
+                    sessionId: childId,
+                    mode: "queue",
+                    content: [{ type: "text", text: childPrompt }],
+                });
+            }
+            catch (err) {
+                await discardIfUnstarted();
+                const extra = worktreeLine(false);
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [`subagent prompt failed: ${message}`, extra]
+                        .filter(Boolean)
+                        .join("\n"),
+                    isError: true,
+                };
+            }
             if (!prompted.result.ok) {
+                await discardIfUnstarted();
                 const extra = worktreeLine(false);
                 return {
                     content: [`subagent prompt failed: ${prompted.result.error.message}`, extra]
@@ -677,6 +959,8 @@ function createSubagentTool(options) {
                     isError: true,
                 };
             }
+            // Spawn accepted — the child is no longer a half-made shell.
+            started = true;
             if (background) {
                 return {
                     content: [
@@ -689,7 +973,8 @@ function createSubagentTool(options) {
                         outputSchema
                             ? "OUTPUT CONTRACT attached; result will be schema-checked on idle."
                             : undefined,
-                        "Use followup_task to wake a new task, send_message (delivery queue|steer) to continue, wait_agent for results, interrupt_agent (takeover true to pause for human) to stop, list_agents / analytics for quota.",
+                        childResumeHint(childId),
+                        "Use followup_task to wake a new task, send_message (delivery queue|steer) to continue, wait_agent for results, interrupt_agent (takeover true to pause for human) to stop, analytics for quota.",
                         "Keep working; do not busy-poll.",
                         worktreeLine(true) || undefined,
                     ]
@@ -698,29 +983,63 @@ function createSubagentTool(options) {
                 };
             }
             try {
-                await waitDrainIdle(options.runtime, childId, signal);
+                await waitDrainIdle(options.runtime, childId, signal, foregroundWaitMs);
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                await dispatchFaceMethod(options.runtime, "session.cancel", `tool-sa-c-${childId}`, { sessionId: childId }).catch(() => undefined);
+                const timedOut = /timed out waiting/i.test(message);
+                // Salvage before cancelling: `session.cancel` drops the chain, so a
+                // child that had already written its answer would bill the parent for
+                // nothing. A child that produced nothing is stuck, so it still gets
+                // cancelled instead of left dangling.
+                const owned = childOwnedEvents(options.runtime, childId);
+                const salvaged = lastAssistantBodyText(owned);
+                const retrying = timedOut
+                    ? lastModelRetryNotice(owned)
+                    : undefined;
+                if (!salvaged) {
+                    await dispatchFaceMethod(options.runtime, "session.cancel", `tool-sa-c-${childId}`, 
+                    // `parent`, not the default `user`: a parent that gave up waiting
+                    // is not a human hitting Stop. The old default stamped
+                    // turn/end `reason: user`, so every timed-out child read as "stopped
+                    // by the user" in the child log and in the completion notice.
+                    { sessionId: childId, cause: { kind: "parent" } }).catch(() => undefined);
+                }
                 options.runtime.agentTeamTasks.complete(task.id, {
                     ok: false,
                     preview: message,
                 });
                 const extra = worktreeLine(false);
                 return {
-                    content: [`subagent failed: ${message}`, extra].filter(Boolean).join("\n"),
+                    content: [
+                        salvaged
+                            ? `${message}, but the child finished work before the wait expired — its last answer is salvaged below.`
+                            : `subagent failed: ${message}`,
+                        salvaged || undefined,
+                        timedOut ? childResumeHint(childId) : undefined,
+                        retrying,
+                        extra,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
                     isError: true,
                 };
             }
             const all = readSessionEvents(options.runtime.store, childId);
             // Never return seeded parent assistant text as the child's result.
-            let owned = seedEventCount > 0 ? all.slice(seedEventCount) : all;
+            const link = options.runtime.subagents.getByChild(childId);
+            const readOwned = () => subagentOwnedEvents(link, readSessionEvents(options.runtime.store, childId));
+            let owned = subagentOwnedEvents(link, all);
             let text = lastAssistantBodyText(owned);
             let schemaValid;
             let schemaErrors;
-            if (outputSchema && text) {
-                let checked = validateOutputAgainstSchema(text, outputSchema);
+            if (outputSchema) {
+                // An empty body cannot satisfy the contract either: a silent skip
+                // would hand the parent `ok: true` with an unvalidated (missing)
+                // answer, so treat "no text" as one more schema failure.
+                let checked = text
+                    ? validateOutputAgainstSchema(text, outputSchema)
+                    : { valid: false, errors: ["child produced no assistant text"] };
                 if (!checked.valid) {
                     const retry = await dispatchFaceMethod(options.runtime, "session.prompt", `tool-sa-schema-${childId}`, {
                         sessionId: childId,
@@ -739,18 +1058,20 @@ function createSubagentTool(options) {
                         catch {
                             /* keep first answer */
                         }
-                        owned = seedEventCount > 0
-                            ? readSessionEvents(options.runtime.store, childId).slice(seedEventCount)
-                            : readSessionEvents(options.runtime.store, childId);
+                        owned = readOwned();
                         text = lastAssistantBodyText(owned) || text;
-                        checked = validateOutputAgainstSchema(text, outputSchema);
+                        checked = text
+                            ? validateOutputAgainstSchema(text, outputSchema)
+                            : { valid: false, errors: ["child produced no assistant text"] };
                     }
                 }
                 schemaValid = checked.valid;
                 schemaErrors = checked.errors;
             }
             options.runtime.agentTeamTasks.complete(task.id, {
-                ok: true,
+                // An unvalidated answer is not a successful delegation: the task
+                // board must not read `completed` when the contract was skipped.
+                ok: schemaValid !== false,
                 ...(text ? { preview: text } : {}),
                 ...(schemaValid !== undefined ? { schemaValid } : {}),
                 ...(schemaErrors && schemaErrors.length > 0
@@ -786,7 +1107,8 @@ function createSubagentTool(options) {
 function createListAgentsTool(options) {
     return {
         name: "list_agents",
-        description: "List direct child subagents of this session (id, label, mode, running, inbox queue/steer). " +
+        description: "List direct child subagents of this session (id, label, mode, running, model, inbox queue/steer, " +
+            "and how each child's last turn actually ended — finished vs aborted by parent/user vs error, with idle age). " +
             "Prefaces with depth/active quota. Prefer `analytics` for a fuller quota snapshot.",
         parameters: { type: "object", properties: {} },
         isConcurrencySafe: () => true,
@@ -819,7 +1141,14 @@ function createListAgentsTool(options) {
                 const inbox = id !== "?"
                     ? childInboxCounts(options.runtime, id)
                     : { queued: 0, steering: 0 };
-                return `${id}\t${label}\t${mode}\t${activity}\tq=${inbox.queued}\tsteer=${inbox.steering}`;
+                const route = e.model ? `\t${e.model}` : "";
+                // `idle` alone reads the same for a child that finished and one the
+                // parent's wait budget cut off; the outcome line is what separates
+                // "delivered" from "killed".
+                const outcome = id === "?" || e.kind === "diagnostic"
+                    ? ""
+                    : `\t${formatChildOutcome(readSessionEvents(options.runtime.store, id))}`;
+                return `${id}\t${label}\t${mode}\t${activity}${route}${outcome}\tq=${inbox.queued}\tsteer=${inbox.steering}`;
             });
             return { content: [header, ...lines].join("\n") };
         },
@@ -873,7 +1202,8 @@ function createSendMessageTool(options) {
                     isError: true,
                 };
             }
-            options.runtime.agentTeamTasks.markResumed(childId);
+            // Task-board resume is owned by `subagent.prompt` (the SoT for every
+            // delivery route); calling it again here double-bumped the revision.
             return { content: `sent to ${childId} (${delivery})` };
         },
     };
@@ -1032,7 +1362,6 @@ function createTeamGraphTool(options) {
                         results.push(`${peer.id}\tfail\t${prompted.result.error.message}`);
                         continue;
                     }
-                    options.runtime.agentTeamTasks.markResumed(peer.id);
                     results.push(`${peer.id}\tok\t${delivery}`);
                 }
                 return {
@@ -1110,7 +1439,6 @@ function createFollowupTaskTool(options) {
                     isError: true,
                 };
             }
-            options.runtime.agentTeamTasks.markResumed(childId);
             return { content: `followup_task sent to ${childId} (steer)` };
         },
     };
@@ -1217,10 +1545,11 @@ function createWaitAgentTool(options) {
                     : `wait_agent completed (${timeoutMs}ms budget)`,
             ];
             for (const childId of targets) {
+                const link = options.runtime.subagents.getByChild(childId);
                 const running = isChildSessionActive(options.runtime, childId);
                 const text = running
                     ? undefined
-                    : lastAssistantBodyText(readSessionEvents(options.runtime.store, childId));
+                    : lastAssistantBodyText(subagentOwnedEvents(link, readSessionEvents(options.runtime.store, childId)));
                 const inbox = childInboxCounts(options.runtime, childId);
                 lines.push([
                     childId,
@@ -1245,7 +1574,8 @@ function createAnalyticsTool(options) {
     return {
         name: "analytics",
         description: "Local subagent quota and queue snapshot for this session (not cloud telemetry). " +
-            "Shows depth/active caps, free slots, and each child's running state plus inbox queue/steer counts.",
+            "Shows depth/active caps, free slots, and each child's running state, model route, " +
+            "plus inbox queue/steer counts.",
         parameters: { type: "object", properties: {} },
         isConcurrencySafe: () => true,
         async execute() {
@@ -1278,7 +1608,14 @@ function createAnalyticsTool(options) {
                         ? "running"
                         : "idle";
                     const inbox = childInboxCounts(options.runtime, link.childSessionId);
-                    lines.push(`  ${link.childSessionId}\t${link.label ?? "subagent"}\t${link.mode}\t${activity}\tq=${inbox.queued}\tsteer=${inbox.steering}`);
+                    const externalKind = options.runtime.externalAgents.kind(link.childSessionId);
+                    const route = externalKind
+                        ? `external:${externalKind}`
+                        : (() => {
+                            const m = resolveSessionModelSelection(options.runtime, link.childSessionId);
+                            return `${m.provider}/${m.model}`;
+                        })();
+                    lines.push(`  ${link.childSessionId}\t${link.label ?? "subagent"}\t${link.mode}\t${activity}\t${route}\tq=${inbox.queued}\tsteer=${inbox.steering}`);
                 }
             }
             return { content: lines.join("\n") };