@xrkseek/harness 0.4.0-rc.4 → 0.4.1

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

@@ -1,15 +1,70 @@
 import { SUBAGENT_ROUTING_PROMPT_TEXT } from "@xrkseek/core-tools";
-import { readSessionEvents } from "@xrkseek/core-session";
+import { listPendingAdmits, readSessionEvents, } from "@xrkseek/core-session";
 import { dispatchFaceMethod } from "./dispatch.js";
 import { lastAssistantBodyText } from "./adapt/subagent-notice.js";
-import { DEFAULT_MAX_ACTIVE_CHILDREN, DEFAULT_MAX_DEPTH } from "./presets-catalog.js";
+import { DEFAULT_MAX_ACTIVE_CHILDREN, DEFAULT_MAX_DEPTH, resolveAgentPresetProfile, } from "./presets-catalog.js";
 import { resolveSessionCwd } from "./session-cwd.js";
-import { ExternalAgentError, parseExternalAgentKind, runExternalAgentTurn, } from "./external-agent-runtime.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 { appendOutputContract, buildOutputSchemaRetryMessage, coerceOutputSchema, validateOutputAgainstSchema, } from "./agent-team-output.js";
+import { applySpawnRoleReminder, parseAgentTeamSpawnRole, } from "./agent-team-roles.js";
+import { bindRalphTool } from "./ralph-tool.js";
 const FOREGROUND_WAIT_MS = 10 * 60 * 1000;
+const WAIT_AGENT_DEFAULT_MS = 5 * 60 * 1000;
+const WAIT_AGENT_MIN_MS = 1_000;
 const POLL_MS = 50;
 export { SUBAGENT_ROUTING_PROMPT_TEXT, DEFAULT_MAX_ACTIVE_CHILDREN, DEFAULT_MAX_DEPTH };
-export { parseExternalAgentKind, runExternalAgentTurn, resolveExternalAgentLaunch, ExternalAgentError, } from "./external-agent-runtime.js";
+/**
+ * Resolve live quota for Status / `analytics` (Face agent-loop ∩ badge ceiling).
+ */
+export function resolveSubagentQuota(runtime, sessionId) {
+    const loopValue = runtime.settingsNamespaces.view("agent-loop").value;
+    const faceDepth = typeof loopValue.maxSubagentDepth === "number" &&
+        Number.isFinite(loopValue.maxSubagentDepth) &&
+        loopValue.maxSubagentDepth >= 1
+        ? Math.min(3, Math.floor(loopValue.maxSubagentDepth))
+        : DEFAULT_MAX_DEPTH;
+    const faceActive = typeof loopValue.maxActiveSubagents === "number" &&
+        Number.isFinite(loopValue.maxActiveSubagents) &&
+        loopValue.maxActiveSubagents >= 1
+        ? Math.min(16, Math.floor(loopValue.maxActiveSubagents))
+        : DEFAULT_MAX_ACTIVE_CHILDREN;
+    const presetId = runtime.sessionAgentPresets.get(sessionId);
+    const profile = resolveAgentPresetProfile(presetId);
+    const maxDepth = profile.subagents.maxDepth !== undefined
+        ? Math.min(faceDepth, profile.subagents.maxDepth)
+        : faceDepth;
+    const maxActive = profile.subagents.maxActiveChildren !== undefined
+        ? Math.min(faceActive, profile.subagents.maxActiveChildren)
+        : faceActive;
+    const depth = subagentDepth(runtime, sessionId);
+    const active = countActiveChildren(runtime, sessionId);
+    const delegated = runtime.subagents.listDelegated(sessionId).length;
+    return {
+        depth,
+        maxDepth,
+        active,
+        maxActive,
+        delegated,
+        slotsFree: Math.max(0, maxActive - active),
+    };
+}
+function childInboxCounts(runtime, childSessionId) {
+    if (!runtime.store.has(childSessionId)) {
+        return { queued: 0, steering: 0 };
+    }
+    const pending = listPendingAdmits(readSessionEvents(runtime.store, childSessionId), childSessionId);
+    let queued = 0;
+    let steering = 0;
+    for (const admit of pending) {
+        if (admit.delivery === "steer")
+            steering += 1;
+        else
+            queued += 1;
+    }
+    return { queued, steering };
+}
+export { parseExternalAgentKind, parseExternalAgentProduct, runExternalAgentTurn, resolveExternalAgentLaunch, openExternalAgentLiveSession, supportsExternalContinuable, ExternalAgentError, ExternalAgentSessionRegistry, isChildSessionActive, startExternalContinuable, promptExternalContinuable, interruptExternalContinuable, } from "./external-agent-runtime.js";
 export function subagentDepth(runtime, sessionId) {
     let depth = 0;
     let cur = sessionId;
@@ -44,7 +99,7 @@ async function waitDrainIdle(runtime, sessionId, signal, timeoutMs = FOREGROUND_
 function countActiveChildren(runtime, parentSessionId) {
     let n = 0;
     for (const link of runtime.subagents.listDelegated(parentSessionId)) {
-        if (runtime.drain.isActive(link.childSessionId))
+        if (isChildSessionActive(runtime, link.childSessionId))
             n += 1;
     }
     return n;
@@ -54,14 +109,18 @@ function createSubagentTool(options) {
     const maxActiveChildren = options.maxActiveChildren ?? DEFAULT_MAX_ACTIVE_CHILDREN;
     return {
         name: "subagent",
-        description: "Delegate a self-contained task to a subagent (separate session/context). " +
+        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 runtime: omit or in-process (default Face child); acp / app-server / claude-code spawn an external one-shot subprocess (no Face child; background not supported).",
+            "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 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.",
         parameters: {
             type: "object",
             properties: {
@@ -79,11 +138,31 @@ function createSubagentTool(options) {
                 },
                 run_in_background: {
                     type: "boolean",
-                    description: "If true, return the child session id immediately (continuable). Default false (wait for the child's final answer). Not supported for external runtimes.",
+                    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).",
+                },
+                role: {
+                    type: "string",
+                    description: "Spawn role template: default | worker | researcher | reviewer | lead (alias: agent_type).",
+                },
+                agent_type: {
+                    type: "string",
+                    description: "Alias of role (Codex agent_type).",
+                },
+                task_id: {
+                    type: "string",
+                    description: "Optional stable task id on the Agent Teams board (auto-minted when omitted).",
+                },
+                task_name: {
+                    type: "string",
+                    description: "Task board title (defaults to description / task_id).",
+                },
+                output_schema: {
+                    type: "object",
+                    description: "Optional JSON Schema for the child's FINAL answer (Hermes OUTPUT CONTRACT). Validated after the turn; one correction turn on failure for foreground waits.",
                 },
                 runtime: {
                     type: "string",
-                    description: "Delegation runtime: in-process (default), acp (XRK_ACP_AGENT), app-server (XRK_CODEX_APP_SERVER / codex app-server), claude-code (XRK_CLAUDE_CODE / claude -p).",
+                    description: "Delegation runtime: in-process (default), acp (Settings external-agent.acpAgent / XRK_ACP_AGENT), app-server (Settings / XRK_CODEX_APP_SERVER), claude-code (Settings / XRK_CLAUDE_CODE).",
                 },
                 worktree: {
                     type: "boolean",
@@ -106,6 +185,25 @@ function createSubagentTool(options) {
             if (!prompt) {
                 return { content: "subagent: empty prompt", isError: true };
             }
+            const roleRaw = a.role ?? a.agent_type;
+            let spawnRole;
+            if (roleRaw !== undefined && String(roleRaw).trim()) {
+                spawnRole = parseAgentTeamSpawnRole(roleRaw);
+                if (!spawnRole) {
+                    return {
+                        content: "subagent: role/agent_type must be default | worker | researcher | reviewer | lead",
+                        isError: true,
+                    };
+                }
+            }
+            const schemaCoerce = coerceOutputSchema(a.output_schema);
+            if (schemaCoerce.error) {
+                return {
+                    content: `subagent: ${schemaCoerce.error}`,
+                    isError: true,
+                };
+            }
+            const outputSchema = schemaCoerce.schema;
             const runtimeKind = parseExternalAgentKind(a.runtime);
             if (runtimeKind === undefined) {
                 return {
@@ -114,19 +212,93 @@ function createSubagentTool(options) {
                 };
             }
             if (runtimeKind !== "in-process") {
-                if (a.run_in_background === true) {
+                const background = a.run_in_background === true;
+                if (background && !supportsExternalContinuable(runtimeKind)) {
                     return {
-                        content: "subagent: run_in_background is not supported for external runtimes",
+                        content: "subagent: run_in_background is not supported for claude-code (print); use acp or app-server",
+                        isError: true,
+                    };
+                }
+                const depth = subagentDepth(options.runtime, options.parentSessionId);
+                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})`,
                         isError: true,
                     };
                 }
                 try {
+                    const product = parseExternalAgentProduct(options.runtime.settingsNamespaces.view("external-agent").value);
+                    if (background && supportsExternalContinuable(runtimeKind)) {
+                        const label = String(a.description ?? "").trim() ||
+                            String(a.task_name ?? "").trim() ||
+                            `external-${runtimeKind}`;
+                        const created = await dispatchFaceMethod(options.runtime, "session.create", `tool-sa-ext-${Date.now()}`, {
+                            parentSessionId: options.parentSessionId,
+                            label,
+                            mode: "continuable",
+                        });
+                        if (!created.result.ok) {
+                            return {
+                                content: `subagent create failed: ${created.result.error.message}`,
+                                isError: true,
+                            };
+                        }
+                        const childId = String(created.result.value.sessionId);
+                        const taskTitle = String(a.task_name ?? "").trim() || label;
+                        const task = options.runtime.agentTeamTasks.open({
+                            parentSessionId: options.parentSessionId,
+                            title: taskTitle,
+                            childSessionId: childId,
+                            ...(spawnRole && spawnRole !== "default"
+                                ? { role: spawnRole }
+                                : {}),
+                            ...(String(a.task_id ?? "").trim()
+                                ? { taskId: String(a.task_id).trim() }
+                                : {}),
+                        });
+                        if (outputSchema) {
+                            options.runtime.agentTeamTasks.setOutputSchema(task.id, outputSchema);
+                        }
+                        await startExternalContinuable({
+                            runtime: options.runtime,
+                            faceSessionId: childId,
+                            kind: runtimeKind,
+                            cwd: resolveSessionCwd(options.runtime, options.parentSessionId) ?? options.runtime.workspaceRoot,
+                            prompt,
+                            background: true,
+                            ...(signal ? { signal } : {}),
+                            ...(options.externalEnv ? { env: options.externalEnv } : {}),
+                            ...(product ? { product } : {}),
+                            ...(options.externalSpawn
+                                ? { spawnImpl: options.externalSpawn }
+                                : {}),
+                        });
+                        return {
+                            content: [
+                                `Started background external subagent \`${childId}\` (${label} · ${runtimeKind}).`,
+                                `task ${task.id}` +
+                                    (spawnRole && spawnRole !== "default"
+                                        ? ` · role ${spawnRole}`
+                                        : ""),
+                                "Use followup_task / send_message / wait_agent / interrupt_agent / list_agents / analytics.",
+                                "Keep working; do not busy-poll.",
+                            ].join("\n"),
+                        };
+                    }
                     const result = await runExternalAgentTurn({
                         kind: runtimeKind,
                         cwd: options.runtime.workspaceRoot,
                         prompt,
                         ...(signal ? { signal } : {}),
                         ...(options.externalEnv ? { env: options.externalEnv } : {}),
+                        ...(product ? { product } : {}),
                         ...(options.externalSpawn
                             ? { spawnImpl: options.externalSpawn }
                             : {}),
@@ -161,26 +333,104 @@ function createSubagentTool(options) {
             const background = a.run_in_background === true;
             const inherit = a.inherit_context === true;
             const label = String(a.description ?? "").trim() ||
+                String(a.task_name ?? "").trim() ||
                 (background ? "subagent" : "subagent-task");
             const linkMode = background ? "continuable" : "one-shot";
             const parentCwd = resolveSessionCwd(options.runtime, options.parentSessionId);
             let isolated = null;
+            let managedLease = null;
             let worktreeSkip = "";
             if (a.worktree === true) {
                 if (worktreeSkippedForRemote(options.runtime.remoteExecution)) {
                     worktreeSkip = "worktree skipped: not a local terminal";
                 }
                 else {
-                    isolated = createSubagentWorktree(parentCwd);
-                    if (!isolated) {
-                        worktreeSkip =
-                            "worktree skipped: not a git repository or worktree add failed";
+                    managedLease =
+                        options.runtime.managedWorktrees.allocate({
+                            parentCwd,
+                            parentSessionId: options.parentSessionId,
+                        }) ?? null;
+                    if (managedLease) {
+                        isolated = {
+                            path: managedLease.path,
+                            branch: managedLease.branch,
+                            repoRoot: managedLease.repoRoot,
+                            baseCommit: managedLease.baseCommit,
+                        };
+                    }
+                    else {
+                        // Fall back to one-shot create when the registry path fails.
+                        isolated = createSubagentWorktree(parentCwd);
+                        if (!isolated) {
+                            worktreeSkip =
+                                "worktree skipped: not a git repository or worktree add failed";
+                        }
                     }
                 }
             }
-            const childPrompt = isolated
-                ? `${prompt}\n\n${worktreeContextNote(isolated)}`
-                : prompt;
+            let childPrompt = applySpawnRoleReminder(prompt, spawnRole);
+            if (outputSchema) {
+                childPrompt = appendOutputContract(childPrompt, 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;
+            const openTask = (childSessionId) => {
+                const task = options.runtime.agentTeamTasks.open({
+                    parentSessionId: options.parentSessionId,
+                    title: taskTitle,
+                    childSessionId,
+                    ...(spawnRole && spawnRole !== "default" ? { role: spawnRole } : {}),
+                    ...(taskIdHint ? { taskId: taskIdHint } : {}),
+                });
+                if (outputSchema) {
+                    options.runtime.agentTeamTasks.setOutputSchema(task.id, outputSchema);
+                }
+                if (managedLease) {
+                    options.runtime.managedWorktrees.bind(managedLease.id, {
+                        childSessionId,
+                        teamTaskId: task.id,
+                    });
+                    options.runtime.agentTeamTasks.bindWorktree(task.id, {
+                        path: managedLease.path,
+                        branch: managedLease.branch,
+                        id: managedLease.id,
+                    });
+                }
+                else if (isolated) {
+                    options.runtime.agentTeamTasks.bindWorktree(task.id, {
+                        path: isolated.path,
+                        branch: isolated.branch,
+                    });
+                }
+                return task;
+            };
+            const reclaimIsolated = (keep) => {
+                if (worktreeSkip)
+                    return worktreeSkip;
+                if (!isolated)
+                    return "";
+                if (keep) {
+                    return `[worktree] ${isolated.path}\nbranch ${isolated.branch}\nleft in place (child still running)`;
+                }
+                if (managedLease) {
+                    return formatWorktreeResult(options.runtime.managedWorktrees.reclaim(managedLease.id) ??
+                        finalizeSubagentWorktree(isolated));
+                }
+                return formatWorktreeResult(finalizeSubagentWorktree(isolated));
+            };
+            const dropIsolated = () => {
+                if (!isolated)
+                    return;
+                if (managedLease) {
+                    options.runtime.managedWorktrees.reclaim(managedLease.id);
+                }
+                else {
+                    finalizeSubagentWorktree(isolated);
+                }
+            };
             let childId;
             let seedEventCount = 0;
             if (inherit) {
@@ -198,8 +448,7 @@ function createSubagentTool(options) {
                             mode: linkMode,
                         });
                         if (!created.result.ok) {
-                            if (isolated)
-                                finalizeSubagentWorktree(isolated);
+                            dropIsolated();
                             return {
                                 content: `subagent create failed: ${created.result.error.message}`,
                                 isError: true,
@@ -208,8 +457,7 @@ function createSubagentTool(options) {
                         childId = String(created.result.value.sessionId);
                     }
                     else {
-                        if (isolated)
-                            finalizeSubagentWorktree(isolated);
+                        dropIsolated();
                         return {
                             content: `subagent seed failed: ${forked.result.error.message}`,
                             isError: true,
@@ -228,8 +476,7 @@ function createSubagentTool(options) {
                     mode: linkMode,
                 });
                 if (!created.result.ok) {
-                    if (isolated)
-                        finalizeSubagentWorktree(isolated);
+                    dropIsolated();
                     return {
                         content: `subagent create failed: ${created.result.error.message}`,
                         isError: true,
@@ -241,16 +488,8 @@ function createSubagentTool(options) {
                 options.runtime.sessionCwds.set(childId, isolated.path);
                 await options.runtime.invalidateAgent?.(childId);
             }
-            const worktreeLine = (keep) => {
-                if (worktreeSkip)
-                    return worktreeSkip;
-                if (!isolated)
-                    return "";
-                if (keep) {
-                    return `[worktree] ${isolated.path}\nbranch ${isolated.branch}\nleft in place (child still running)`;
-                }
-                return formatWorktreeResult(finalizeSubagentWorktree(isolated));
-            };
+            const task = openTask(childId);
+            const worktreeLine = reclaimIsolated;
             const prompted = await dispatchFaceMethod(options.runtime, "session.prompt", `tool-sa-p-${childId}`, {
                 sessionId: childId,
                 mode: "queue",
@@ -269,10 +508,15 @@ function createSubagentTool(options) {
                 return {
                     content: [
                         `Started background subagent \`${childId}\` (${label}).`,
+                        `task ${task.id}` +
+                            (spawnRole && spawnRole !== "default" ? ` · role ${spawnRole}` : ""),
                         inherit
                             ? "Seeded with this session's completed turns (open turn excluded)."
                             : undefined,
-                        "Use send_message to continue, interrupt_agent to stop, list_agents to inspect.",
+                        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.",
                         "Keep working; do not busy-poll.",
                         worktreeLine(true) || undefined,
                     ]
@@ -286,6 +530,10 @@ function createSubagentTool(options) {
             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);
+                options.runtime.agentTeamTasks.complete(task.id, {
+                    ok: false,
+                    preview: message,
+                });
                 const extra = worktreeLine(false);
                 return {
                     content: [`subagent failed: ${message}`, extra].filter(Boolean).join("\n"),
@@ -294,8 +542,48 @@ function createSubagentTool(options) {
             }
             const all = readSessionEvents(options.runtime.store, childId);
             // Never return seeded parent assistant text as the child's result.
-            const owned = seedEventCount > 0 ? all.slice(seedEventCount) : all;
-            const text = lastAssistantBodyText(owned);
+            let owned = seedEventCount > 0 ? all.slice(seedEventCount) : all;
+            let text = lastAssistantBodyText(owned);
+            let schemaValid;
+            let schemaErrors;
+            if (outputSchema && text) {
+                let checked = validateOutputAgainstSchema(text, outputSchema);
+                if (!checked.valid) {
+                    const retry = await dispatchFaceMethod(options.runtime, "session.prompt", `tool-sa-schema-${childId}`, {
+                        sessionId: childId,
+                        mode: "queue",
+                        content: [
+                            {
+                                type: "text",
+                                text: buildOutputSchemaRetryMessage(checked.errors),
+                            },
+                        ],
+                    });
+                    if (retry.result.ok) {
+                        try {
+                            await waitDrainIdle(options.runtime, childId, signal);
+                        }
+                        catch {
+                            /* keep first answer */
+                        }
+                        owned = seedEventCount > 0
+                            ? readSessionEvents(options.runtime.store, childId).slice(seedEventCount)
+                            : readSessionEvents(options.runtime.store, childId);
+                        text = lastAssistantBodyText(owned) || text;
+                        checked = validateOutputAgainstSchema(text, outputSchema);
+                    }
+                }
+                schemaValid = checked.valid;
+                schemaErrors = checked.errors;
+            }
+            options.runtime.agentTeamTasks.complete(task.id, {
+                ok: true,
+                ...(text ? { preview: text } : {}),
+                ...(schemaValid !== undefined ? { schemaValid } : {}),
+                ...(schemaErrors && schemaErrors.length > 0
+                    ? { schemaErrors }
+                    : {}),
+            });
             const extra = worktreeLine(false);
             if (!text) {
                 return {
@@ -304,14 +592,23 @@ function createSubagentTool(options) {
                         .join("\n"),
                 };
             }
-            return { content: [text, extra].filter(Boolean).join("\n") };
+            const schemaLine = schemaValid === undefined
+                ? undefined
+                : schemaValid
+                    ? "schema_valid=true"
+                    : `schema_valid=false\n${(schemaErrors ?? []).map((e) => `- ${e}`).join("\n")}`;
+            return {
+                content: [text, schemaLine, extra].filter(Boolean).join("\n"),
+                ...(schemaValid === false ? { isError: true } : {}),
+            };
         },
     };
 }
 function createListAgentsTool(options) {
     return {
         name: "list_agents",
-        description: "List direct child subagents of this session (id, label, mode, running).",
+        description: "List direct child subagents of this session (id, label, mode, running, inbox queue/steer). " +
+            "Prefaces with depth/active quota. Prefer `analytics` for a fuller quota snapshot.",
         parameters: { type: "object", properties: {} },
         isConcurrencySafe: () => true,
         async execute() {
@@ -324,31 +621,40 @@ function createListAgentsTool(options) {
             }
             const value = listed.result.value;
             const entries = value.entries ?? [];
-            if (!entries.length)
-                return { content: "(no subagents)" };
-            return {
-                content: entries
-                    .map((e) => {
-                    if (e.kind === "diagnostic") {
-                        return `${e.id ?? "?"}\tdiagnostic\t${e.reason ?? "unavailable"}`;
-                    }
-                    const id = e.id ?? "?";
-                    const label = e.label ?? "subagent";
-                    const mode = e.mode ?? "?";
-                    const activity = e.activity ?? "idle";
-                    return `${id}\t${label}\t${mode}\t${activity}`;
-                })
-                    .join("\n"),
-            };
+            const quota = resolveSubagentQuota(options.runtime, options.parentSessionId);
+            const header = `quota depth ${quota.depth}/${quota.maxDepth}` +
+                ` · active ${quota.active}/${quota.maxActive}` +
+                ` · slots_free ${quota.slotsFree}` +
+                ` · delegated ${quota.delegated}`;
+            if (!entries.length) {
+                return { content: `${header}\n(no subagents)` };
+            }
+            const lines = entries.map((e) => {
+                if (e.kind === "diagnostic") {
+                    return `${e.id ?? "?"}\tdiagnostic\t${e.reason ?? "unavailable"}`;
+                }
+                const id = e.id ?? "?";
+                const label = e.label ?? "subagent";
+                const mode = e.mode ?? "?";
+                const activity = e.activity ?? "idle";
+                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}`;
+            });
+            return { content: [header, ...lines].join("\n") };
         },
     };
 }
 function createSendMessageTool(options) {
     return {
         name: "send_message",
-        description: "Send a follow-up to a continuable background subagent by child session id. " +
-            "If the child is still working, the message waits in its inbox (does not steer the in-flight turn). " +
-            "Returns delivery confirmation only — not the child's answer.",
+        description: "Pass a message to a continuable background subagent without forcing a new task turn by default. " +
+            "delivery=queue (default): land in the child's inbox if it is still working. " +
+            "delivery=steer: nudge at the next tool-step / turn boundary. " +
+            "For a new task that should trigger a turn, prefer `followup_task`. " +
+            "Clears human takeover pause on the Agent Teams task board. " +
+            "Returns delivery confirmation only — not the child's answer (use `wait_agent`).",
         parameters: {
             type: "object",
             properties: {
@@ -357,6 +663,10 @@ function createSendMessageTool(options) {
                     description: "Child session id from subagent / list_agents.",
                 },
                 message: { type: "string", description: "Follow-up text for the child." },
+                delivery: {
+                    type: "string",
+                    description: "queue (default) or steer.",
+                },
             },
             required: ["agent_id", "message"],
         },
@@ -370,10 +680,60 @@ function createSendMessageTool(options) {
                     isError: true,
                 };
             }
+            const delivery = a.delivery === "steer" || a.delivery === "queue" ? a.delivery : "queue";
             const prompted = await dispatchFaceMethod(options.runtime, "subagent.prompt", `tool-sa-sm-${childId}`, {
                 parentSessionId: options.parentSessionId,
                 childSessionId: childId,
                 mode: "continuable",
+                delivery,
+                content: [{ type: "text", text: message }],
+            });
+            if (!prompted.result.ok) {
+                return {
+                    content: prompted.result.error.message,
+                    isError: true,
+                };
+            }
+            options.runtime.agentTeamTasks.markResumed(childId);
+            return { content: `sent to ${childId} (${delivery})` };
+        },
+    };
+}
+function createFollowupTaskTool(options) {
+    return {
+        name: "followup_task",
+        description: "Give an existing continuable subagent a new task and trigger a turn (Codex followup_task / TriggerTurn). " +
+            "Unlike `send_message` (default queue-only), this always wakes the child. " +
+            "Returns delivery confirmation only — use `wait_agent` for the answer.",
+        parameters: {
+            type: "object",
+            properties: {
+                agent_id: {
+                    type: "string",
+                    description: "Child session id from subagent / list_agents.",
+                },
+                message: {
+                    type: "string",
+                    description: "New task text for the child (triggers a turn).",
+                },
+            },
+            required: ["agent_id", "message"],
+        },
+        async execute(args) {
+            const a = args;
+            const childId = String(a.agent_id ?? "").trim();
+            const message = String(a.message ?? "").trim();
+            if (!childId || !message) {
+                return {
+                    content: "followup_task requires agent_id and message",
+                    isError: true,
+                };
+            }
+            const prompted = await dispatchFaceMethod(options.runtime, "subagent.prompt", `tool-sa-fu-${childId}`, {
+                parentSessionId: options.parentSessionId,
+                childSessionId: childId,
+                mode: "continuable",
+                delivery: "steer",
                 content: [{ type: "text", text: message }],
             });
             if (!prompted.result.ok) {
@@ -382,14 +742,187 @@ function createSendMessageTool(options) {
                     isError: true,
                 };
             }
-            return { content: `sent to ${childId}` };
+            options.runtime.agentTeamTasks.markResumed(childId);
+            return { content: `followup_task sent to ${childId} (steer)` };
+        },
+    };
+}
+function parseWaitTargets(args) {
+    const out = [];
+    const push = (raw) => {
+        const id = String(raw ?? "").trim();
+        if (id && !out.includes(id))
+            out.push(id);
+    };
+    if (Array.isArray(args.targets)) {
+        for (const t of args.targets)
+            push(t);
+    }
+    else if (typeof args.targets === "string" && args.targets.trim()) {
+        for (const part of args.targets.split(/[\s,]+/))
+            push(part);
+    }
+    push(args.agent_id);
+    return out;
+}
+function createWaitAgentTool(options) {
+    return {
+        name: "wait_agent",
+        description: "Wait until listed child subagents become idle (Codex wait_agent targets). " +
+            "Returns each child's final status and last assistant text when idle. " +
+            "Prefer longer timeouts (minutes) over busy-polling with list_agents.",
+        parameters: {
+            type: "object",
+            properties: {
+                targets: {
+                    type: "array",
+                    description: "Child session ids to wait on (from subagent / list_agents).",
+                    items: { type: "string" },
+                },
+                agent_id: {
+                    type: "string",
+                    description: "Convenience single-target alias of targets=[agent_id].",
+                },
+                timeout_ms: {
+                    type: "number",
+                    description: `Max wait in ms (default ${WAIT_AGENT_DEFAULT_MS}; max ${FOREGROUND_WAIT_MS}).`,
+                },
+            },
+        },
+        async execute(args, signal) {
+            const a = args;
+            const targets = parseWaitTargets(a);
+            if (!targets.length) {
+                return {
+                    content: "wait_agent requires targets or agent_id",
+                    isError: true,
+                };
+            }
+            let timeoutMs = WAIT_AGENT_DEFAULT_MS;
+            if (typeof a.timeout_ms === "number" && Number.isFinite(a.timeout_ms)) {
+                timeoutMs = Math.min(FOREGROUND_WAIT_MS, Math.max(WAIT_AGENT_MIN_MS, Math.floor(a.timeout_ms)));
+            }
+            for (const childId of targets) {
+                const link = options.runtime.subagents.getByChild(childId);
+                if (!link ||
+                    link.parentSessionId !== options.parentSessionId ||
+                    link.mode === "fork") {
+                    return {
+                        content: `wait_agent: ${childId} is not a delegated child of this session`,
+                        isError: true,
+                    };
+                }
+            }
+            const deadline = Date.now() + timeoutMs;
+            const stillRunning = () => targets.some((id) => isChildSessionActive(options.runtime, id));
+            while (stillRunning()) {
+                if (signal?.aborted) {
+                    throw new DOMException("aborted", "AbortError");
+                }
+                if (Date.now() > deadline)
+                    break;
+                const remaining = Math.max(0, deadline - Date.now());
+                const slice = Math.min(POLL_MS * 20, remaining);
+                const activeOnes = targets.filter((id) => isChildSessionActive(options.runtime, id));
+                if (activeOnes.length === 1 &&
+                    options.runtime.drain.run &&
+                    !options.runtime.externalAgents.has(activeOnes[0])) {
+                    try {
+                        await Promise.race([
+                            options.runtime.drain.run(activeOnes[0]),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error("wait slice")), Math.max(POLL_MS, slice))),
+                        ]);
+                    }
+                    catch {
+                        /* keep polling until deadline */
+                    }
+                }
+                else {
+                    await new Promise((r) => setTimeout(r, Math.max(POLL_MS, slice)));
+                }
+            }
+            const timedOut = stillRunning();
+            const lines = [
+                timedOut
+                    ? `wait_agent timed out after ${timeoutMs}ms`
+                    : `wait_agent completed (${timeoutMs}ms budget)`,
+            ];
+            for (const childId of targets) {
+                const running = isChildSessionActive(options.runtime, childId);
+                const text = running
+                    ? undefined
+                    : lastAssistantBodyText(readSessionEvents(options.runtime.store, childId));
+                const inbox = childInboxCounts(options.runtime, childId);
+                lines.push([
+                    childId,
+                    running ? "running" : "idle",
+                    `q=${inbox.queued}`,
+                    `steer=${inbox.steering}`,
+                    text
+                        ? `answer:\n${text}`
+                        : running
+                            ? "(still running)"
+                            : "(no assistant text)",
+                ].join("\t"));
+            }
+            return {
+                content: lines.join("\n"),
+                ...(timedOut ? { isError: true } : {}),
+            };
+        },
+    };
+}
+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.",
+        parameters: { type: "object", properties: {} },
+        isConcurrencySafe: () => true,
+        async execute() {
+            const quota = resolveSubagentQuota(options.runtime, options.parentSessionId);
+            const parentPending = listPendingAdmits(readSessionEvents(options.runtime.store, options.parentSessionId), options.parentSessionId);
+            let parentQueued = 0;
+            let parentSteer = 0;
+            for (const admit of parentPending) {
+                if (admit.delivery === "steer")
+                    parentSteer += 1;
+                else
+                    parentQueued += 1;
+            }
+            const lines = [
+                `purpose: local-debug`,
+                `depth: ${quota.depth}/${quota.maxDepth}`,
+                `active: ${quota.active}/${quota.maxActive}`,
+                `slots_free: ${quota.slotsFree}`,
+                `delegated: ${quota.delegated}`,
+                `parent_inbox: queue=${parentQueued} steer=${parentSteer}`,
+                "children:",
+            ];
+            const children = options.runtime.subagents.listDelegated(options.parentSessionId);
+            if (!children.length) {
+                lines.push("  (none)");
+            }
+            else {
+                for (const link of children) {
+                    const activity = isChildSessionActive(options.runtime, link.childSessionId)
+                        ? "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}`);
+                }
+            }
+            return { content: lines.join("\n") };
         },
     };
 }
 function createInterruptAgentTool(options) {
     return {
         name: "interrupt_agent",
-        description: "Interrupt a running child subagent by session id.",
+        description: "Interrupt a running child subagent by session id. " +
+            "Suppresses the automatic parent completion steer for this idle stretch. " +
+            "Set takeover true to mark the Agent Teams task as paused for human ownership " +
+            "(open the child session in the UI; resume later with send_message).",
         parameters: {
             type: "object",
             properties: {
@@ -397,18 +930,25 @@ function createInterruptAgentTool(options) {
                     type: "string",
                     description: "Child session id from subagent / list_agents.",
                 },
+                takeover: {
+                    type: "boolean",
+                    description: "If true, pause the task board entry and hand the child to a human (no auto completion notice).",
+                },
             },
             required: ["agent_id"],
         },
         async execute(args) {
-            const childId = String(args.agent_id ?? "").trim();
+            const a = args;
+            const childId = String(a.agent_id ?? "").trim();
             if (!childId) {
                 return { content: "interrupt_agent requires agent_id", isError: true };
             }
+            const takeover = a.takeover === true;
             const stopped = await dispatchFaceMethod(options.runtime, "subagent.interrupt", `tool-sa-int-${childId}`, {
                 parentSessionId: options.parentSessionId,
                 childSessionId: childId,
                 mode: "continuable",
+                ...(takeover ? { takeover: true } : {}),
             });
             if (!stopped.result.ok) {
                 // one-shot children: fall back to session.cancel
@@ -419,8 +959,16 @@ function createInterruptAgentTool(options) {
                         isError: true,
                     };
                 }
+                options.runtime.suppressOwnedSubagentCompletion(childId);
             }
-            return { content: `interrupted ${childId}` };
+            if (takeover) {
+                options.runtime.agentTeamTasks.markTakeover(childId);
+            }
+            return {
+                content: takeover
+                    ? `interrupted ${childId} (human takeover — task paused)`
+                    : `interrupted ${childId}`,
+            };
         },
     };
 }
@@ -430,6 +978,9 @@ export function bindSubagentTools(tools, options) {
         createSubagentTool(options),
         createListAgentsTool(options),
         createSendMessageTool(options),
+        createFollowupTaskTool(options),
+        createWaitAgentTool(options),
+        createAnalyticsTool(options),
         createInterruptAgentTool(options),
     ]) {
         if (tools.get(tool.name)) {
@@ -439,5 +990,6 @@ export function bindSubagentTools(tools, options) {
             tools.register(tool);
         }
     }
+    bindRalphTool(tools, options);
 }
 //# sourceMappingURL=subagent-tools.js.map