@poolzin/pool-bot 2026.2.20 → 2026.2.22

package/dist/auto-reply/reply/commands-subagents.js

@@ -1,58 +1,134 @@
 import crypto from "node:crypto";
-import { abortEmbeddedPiRun } from "../../agents/pi-embedded.js";
 import { AGENT_LANE_SUBAGENT } from "../../agents/lanes.js";
-import { listSubagentRunsForRequester } from "../../agents/subagent-registry.js";
+import { abortEmbeddedPiRun } from "../../agents/pi-embedded.js";
+import { clearSubagentRunSteerRestart, listSubagentRunsForRequester, markSubagentRunTerminated, markSubagentRunForSteerRestart, replaceSubagentRunAfterSteer, } from "../../agents/subagent-registry.js";
+import { spawnSubagentDirect } from "../../agents/subagent-spawn.js";
 import { extractAssistantText, resolveInternalSessionKey, resolveMainSessionAlias, sanitizeTextContent, stripToolMessages, } from "../../agents/tools/sessions-helpers.js";
-import { loadSessionStore, resolveStorePath, updateSessionStore } from "../../config/sessions.js";
+import { loadSessionStore, resolveStorePath, updateSessionStore, } from "../../config/sessions.js";
 import { callGateway } from "../../gateway/call.js";
 import { logVerbose } from "../../globals.js";
+import { formatTimeAgo } from "../../infra/format-time/format-relative.js";
 import { parseAgentSessionKey } from "../../routing/session-key.js";
+import { extractTextFromChatContent } from "../../shared/chat-content.js";
+import { formatDurationCompact, formatTokenUsageDisplay, truncateLine, } from "../../shared/subagents-format.js";
 import { INTERNAL_MESSAGE_CHANNEL } from "../../utils/message-channel.js";
-import { formatAgeShort, formatDurationShort, formatRunLabel, formatRunStatus, sortSubagentRuns, } from "./subagents-utils.js";
 import { stopSubagentsForRequester } from "./abort.js";
 import { clearSessionQueues } from "./queue.js";
+import { formatRunLabel, formatRunStatus, sortSubagentRuns } from "./subagents-utils.js";
 const COMMAND = "/subagents";
-const ACTIONS = new Set(["list", "stop", "log", "send", "info", "help"]);
+const COMMAND_KILL = "/kill";
+const COMMAND_STEER = "/steer";
+const COMMAND_TELL = "/tell";
+const ACTIONS = new Set(["list", "kill", "log", "send", "steer", "info", "spawn", "help"]);
+const RECENT_WINDOW_MINUTES = 30;
+const SUBAGENT_TASK_PREVIEW_MAX = 110;
+const STEER_ABORT_SETTLE_TIMEOUT_MS = 5_000;
+function compactLine(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function formatTaskPreview(value) {
+    return truncateLine(compactLine(value), SUBAGENT_TASK_PREVIEW_MAX);
+}
+function resolveModelDisplay(entry, fallbackModel) {
+    const model = typeof entry?.model === "string" ? entry.model.trim() : "";
+    const provider = typeof entry?.modelProvider === "string" ? entry.modelProvider.trim() : "";
+    let combined = model.includes("/") ? model : model && provider ? `${provider}/${model}` : model;
+    if (!combined) {
+        // Fall back to override fields which are populated at spawn time,
+        // before the first run completes and writes model/modelProvider.
+        const overrideModel = typeof entry?.modelOverride === "string" ? entry.modelOverride.trim() : "";
+        const overrideProvider = typeof entry?.providerOverride === "string" ? entry.providerOverride.trim() : "";
+        combined = overrideModel.includes("/")
+            ? overrideModel
+            : overrideModel && overrideProvider
+                ? `${overrideProvider}/${overrideModel}`
+                : overrideModel;
+    }
+    if (!combined) {
+        combined = fallbackModel?.trim() || "";
+    }
+    if (!combined) {
+        return "model n/a";
+    }
+    const slash = combined.lastIndexOf("/");
+    if (slash >= 0 && slash < combined.length - 1) {
+        return combined.slice(slash + 1);
+    }
+    return combined;
+}
+function resolveDisplayStatus(entry) {
+    const status = formatRunStatus(entry);
+    return status === "error" ? "failed" : status;
+}
 function formatTimestamp(valueMs) {
-    if (!valueMs || !Number.isFinite(valueMs) || valueMs <= 0)
+    if (!valueMs || !Number.isFinite(valueMs) || valueMs <= 0) {
         return "n/a";
+    }
     return new Date(valueMs).toISOString();
 }
 function formatTimestampWithAge(valueMs) {
-    if (!valueMs || !Number.isFinite(valueMs) || valueMs <= 0)
+    if (!valueMs || !Number.isFinite(valueMs) || valueMs <= 0) {
         return "n/a";
-    return `${formatTimestamp(valueMs)} (${formatAgeShort(Date.now() - valueMs)})`;
+    }
+    return `${formatTimestamp(valueMs)} (${formatTimeAgo(Date.now() - valueMs, { fallback: "n/a" })})`;
 }
-function resolveRequesterSessionKey(params) {
-    const raw = params.sessionKey?.trim() || params.ctx.CommandTargetSessionKey?.trim();
-    if (!raw)
+function resolveRequesterSessionKey(params, opts) {
+    const commandTarget = params.ctx.CommandTargetSessionKey?.trim();
+    const commandSession = params.sessionKey?.trim();
+    const raw = opts?.preferCommandTarget
+        ? commandTarget || commandSession
+        : commandSession || commandTarget;
+    if (!raw) {
         return undefined;
+    }
     const { mainKey, alias } = resolveMainSessionAlias(params.cfg);
     return resolveInternalSessionKey({ key: raw, alias, mainKey });
 }
 function resolveSubagentTarget(runs, token) {
     const trimmed = token?.trim();
-    if (!trimmed)
+    if (!trimmed) {
         return { error: "Missing subagent id." };
+    }
     if (trimmed === "last") {
         const sorted = sortSubagentRuns(runs);
         return { entry: sorted[0] };
     }
     const sorted = sortSubagentRuns(runs);
+    const recentCutoff = Date.now() - RECENT_WINDOW_MINUTES * 60_000;
+    const numericOrder = [
+        ...sorted.filter((entry) => !entry.endedAt),
+        ...sorted.filter((entry) => !!entry.endedAt && (entry.endedAt ?? 0) >= recentCutoff),
+    ];
     if (/^\d+$/.test(trimmed)) {
         const idx = Number.parseInt(trimmed, 10);
-        if (!Number.isFinite(idx) || idx <= 0 || idx > sorted.length) {
+        if (!Number.isFinite(idx) || idx <= 0 || idx > numericOrder.length) {
             return { error: `Invalid subagent index: ${trimmed}` };
         }
-        return { entry: sorted[idx - 1] };
+        return { entry: numericOrder[idx - 1] };
     }
     if (trimmed.includes(":")) {
         const match = runs.find((entry) => entry.childSessionKey === trimmed);
         return match ? { entry: match } : { error: `Unknown subagent session: ${trimmed}` };
     }
+    const lowered = trimmed.toLowerCase();
+    const byLabel = runs.filter((entry) => formatRunLabel(entry).toLowerCase() === lowered);
+    if (byLabel.length === 1) {
+        return { entry: byLabel[0] };
+    }
+    if (byLabel.length > 1) {
+        return { error: `Ambiguous subagent label: ${trimmed}` };
+    }
+    const byLabelPrefix = runs.filter((entry) => formatRunLabel(entry).toLowerCase().startsWith(lowered));
+    if (byLabelPrefix.length === 1) {
+        return { entry: byLabelPrefix[0] };
+    }
+    if (byLabelPrefix.length > 1) {
+        return { error: `Ambiguous subagent label prefix: ${trimmed}` };
+    }
     const byRunId = runs.filter((entry) => entry.runId.startsWith(trimmed));
-    if (byRunId.length === 1)
+    if (byRunId.length === 1) {
         return { entry: byRunId[0] };
+    }
     if (byRunId.length > 1) {
         return { error: `Ambiguous run id prefix: ${trimmed}` };
     }
@@ -60,81 +136,93 @@ function resolveSubagentTarget(runs, token) {
 }
 function buildSubagentsHelp() {
     return [
-        "🧭 Subagents",
+        "Subagents",
         "Usage:",
         "- /subagents list",
-        "- /subagents stop <id|#|all>",
+        "- /subagents kill <id|#|all>",
         "- /subagents log <id|#> [limit] [tools]",
         "- /subagents info <id|#>",
         "- /subagents send <id|#> <message>",
+        "- /subagents steer <id|#> <message>",
+        "- /subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]",
+        "- /kill <id|#|all>",
+        "- /steer <id|#> <message>",
+        "- /tell <id|#> <message>",
         "",
-        "Ids: use the list index (#), runId prefix, or full session key.",
+        "Ids: use the list index (#), runId/session prefix, label, or full session key.",
     ].join("\n");
 }
-function normalizeMessageText(text) {
-    return text.replace(/\s+/g, " ").trim();
-}
 export function extractMessageText(message) {
     const role = typeof message.role === "string" ? message.role : "";
     const shouldSanitize = role === "assistant";
-    const content = message.content;
-    if (typeof content === "string") {
-        const normalized = normalizeMessageText(shouldSanitize ? sanitizeTextContent(content) : content);
-        return normalized ? { role, text: normalized } : null;
-    }
-    if (!Array.isArray(content))
-        return null;
-    const chunks = [];
-    for (const block of content) {
-        if (!block || typeof block !== "object")
-            continue;
-        if (block.type !== "text")
-            continue;
-        const text = block.text;
-        if (typeof text === "string") {
-            const value = shouldSanitize ? sanitizeTextContent(text) : text;
-            if (value.trim()) {
-                chunks.push(value);
-            }
-        }
-    }
-    const joined = normalizeMessageText(chunks.join(" "));
-    return joined ? { role, text: joined } : null;
+    const text = extractTextFromChatContent(message.content, {
+        sanitizeText: shouldSanitize ? sanitizeTextContent : undefined,
+    });
+    return text ? { role, text } : null;
 }
 function formatLogLines(messages) {
     const lines = [];
     for (const msg of messages) {
         const extracted = extractMessageText(msg);
-        if (!extracted)
+        if (!extracted) {
             continue;
+        }
         const label = extracted.role === "assistant" ? "Assistant" : "User";
         lines.push(`${label}: ${extracted.text}`);
     }
     return lines;
 }
-function loadSubagentSessionEntry(params, childKey) {
+function loadSubagentSessionEntry(params, childKey, storeCache) {
     const parsed = parseAgentSessionKey(childKey);
     const storePath = resolveStorePath(params.cfg.session?.store, { agentId: parsed?.agentId });
-    const store = loadSessionStore(storePath);
+    let store = storeCache?.get(storePath);
+    if (!store) {
+        store = loadSessionStore(storePath);
+        storeCache?.set(storePath, store);
+    }
     return { storePath, store, entry: store[childKey] };
 }
 export const handleSubagentsCommand = async (params, allowTextCommands) => {
-    if (!allowTextCommands)
+    if (!allowTextCommands) {
         return null;
+    }
     const normalized = params.command.commandBodyNormalized;
-    if (!normalized.startsWith(COMMAND))
+    const handledPrefix = normalized.startsWith(COMMAND)
+        ? COMMAND
+        : normalized.startsWith(COMMAND_KILL)
+            ? COMMAND_KILL
+            : normalized.startsWith(COMMAND_STEER)
+                ? COMMAND_STEER
+                : normalized.startsWith(COMMAND_TELL)
+                    ? COMMAND_TELL
+                    : null;
+    if (!handledPrefix) {
         return null;
+    }
     if (!params.command.isAuthorizedSender) {
-        logVerbose(`Ignoring /subagents from unauthorized sender: ${params.command.senderId || "<unknown>"}`);
+        logVerbose(`Ignoring ${handledPrefix} from unauthorized sender: ${params.command.senderId || "<unknown>"}`);
         return { shouldContinue: false };
     }
-    const rest = normalized.slice(COMMAND.length).trim();
-    const [actionRaw, ...restTokens] = rest.split(/\s+/).filter(Boolean);
-    const action = actionRaw?.toLowerCase() || "list";
-    if (!ACTIONS.has(action)) {
-        return { shouldContinue: false, reply: { text: buildSubagentsHelp() } };
+    const rest = normalized.slice(handledPrefix.length).trim();
+    const restTokens = rest.split(/\s+/).filter(Boolean);
+    let action = "list";
+    if (handledPrefix === COMMAND) {
+        const [actionRaw] = restTokens;
+        action = actionRaw?.toLowerCase() || "list";
+        if (!ACTIONS.has(action)) {
+            return { shouldContinue: false, reply: { text: buildSubagentsHelp() } };
+        }
+        restTokens.splice(0, 1);
+    }
+    else if (handledPrefix === COMMAND_KILL) {
+        action = "kill";
+    }
+    else {
+        action = "steer";
     }
-    const requesterKey = resolveRequesterSessionKey(params);
+    const requesterKey = resolveRequesterSessionKey(params, {
+        preferCommandTarget: action === "spawn",
+    });
     if (!requesterKey) {
         return { shouldContinue: false, reply: { text: "⚠️ Missing session key." } };
     }
@@ -143,39 +231,71 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
         return { shouldContinue: false, reply: { text: buildSubagentsHelp() } };
     }
     if (action === "list") {
-        if (runs.length === 0) {
-            return { shouldContinue: false, reply: { text: "🧭 Subagents: none for this session." } };
-        }
         const sorted = sortSubagentRuns(runs);
-        const active = sorted.filter((entry) => !entry.endedAt);
-        const done = sorted.length - active.length;
-        const lines = ["🧭 Subagents (current session)", `Active: ${active.length} · Done: ${done}`];
-        sorted.forEach((entry, index) => {
-            const status = formatRunStatus(entry);
-            const label = formatRunLabel(entry);
-            const runtime = entry.endedAt && entry.startedAt
-                ? formatDurationShort(entry.endedAt - entry.startedAt)
-                : formatAgeShort(Date.now() - (entry.startedAt ?? entry.createdAt));
-            const runId = entry.runId.slice(0, 8);
-            lines.push(`${index + 1}) ${status} · ${label} · ${runtime} · run ${runId} · ${entry.childSessionKey}`);
+        const now = Date.now();
+        const recentCutoff = now - RECENT_WINDOW_MINUTES * 60_000;
+        const storeCache = new Map();
+        let index = 1;
+        const activeLines = sorted
+            .filter((entry) => !entry.endedAt)
+            .map((entry) => {
+            const { entry: sessionEntry } = loadSubagentSessionEntry(params, entry.childSessionKey, storeCache);
+            const usageText = formatTokenUsageDisplay(sessionEntry);
+            const label = truncateLine(formatRunLabel(entry, { maxLength: 48 }), 48);
+            const task = formatTaskPreview(entry.task);
+            const runtime = formatDurationCompact(now - (entry.startedAt ?? entry.createdAt));
+            const status = resolveDisplayStatus(entry);
+            const line = `${index}. ${label} (${resolveModelDisplay(sessionEntry, entry.model)}, ${runtime}${usageText ? `, ${usageText}` : ""}) ${status}${task.toLowerCase() !== label.toLowerCase() ? ` - ${task}` : ""}`;
+            index += 1;
+            return line;
+        });
+        const recentLines = sorted
+            .filter((entry) => !!entry.endedAt && (entry.endedAt ?? 0) >= recentCutoff)
+            .map((entry) => {
+            const { entry: sessionEntry } = loadSubagentSessionEntry(params, entry.childSessionKey, storeCache);
+            const usageText = formatTokenUsageDisplay(sessionEntry);
+            const label = truncateLine(formatRunLabel(entry, { maxLength: 48 }), 48);
+            const task = formatTaskPreview(entry.task);
+            const runtime = formatDurationCompact((entry.endedAt ?? now) - (entry.startedAt ?? entry.createdAt));
+            const status = resolveDisplayStatus(entry);
+            const line = `${index}. ${label} (${resolveModelDisplay(sessionEntry, entry.model)}, ${runtime}${usageText ? `, ${usageText}` : ""}) ${status}${task.toLowerCase() !== label.toLowerCase() ? ` - ${task}` : ""}`;
+            index += 1;
+            return line;
         });
+        const lines = ["active subagents:", "-----"];
+        if (activeLines.length === 0) {
+            lines.push("(none)");
+        }
+        else {
+            lines.push(activeLines.join("\n"));
+        }
+        lines.push("", `recent subagents (last ${RECENT_WINDOW_MINUTES}m):`, "-----");
+        if (recentLines.length === 0) {
+            lines.push("(none)");
+        }
+        else {
+            lines.push(recentLines.join("\n"));
+        }
         return { shouldContinue: false, reply: { text: lines.join("\n") } };
     }
-    if (action === "stop") {
+    if (action === "kill") {
         const target = restTokens[0];
         if (!target) {
-            return { shouldContinue: false, reply: { text: "⚙️ Usage: /subagents stop <id|#|all>" } };
+            return {
+                shouldContinue: false,
+                reply: {
+                    text: handledPrefix === COMMAND
+                        ? "Usage: /subagents kill <id|#|all>"
+                        : "Usage: /kill <id|#|all>",
+                },
+            };
         }
         if (target === "all" || target === "*") {
-            const { stopped } = stopSubagentsForRequester({
+            stopSubagentsForRequester({
                 cfg: params.cfg,
                 requesterSessionKey: requesterKey,
             });
-            const label = stopped === 1 ? "subagent" : "subagents";
-            return {
-                shouldContinue: false,
-                reply: { text: `⚙️ Stopped ${stopped} ${label}.` },
-            };
+            return { shouldContinue: false };
         }
         const resolved = resolveSubagentTarget(runs, target);
         if (!resolved.entry) {
@@ -187,7 +307,7 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
         if (resolved.entry.endedAt) {
             return {
                 shouldContinue: false,
-                reply: { text: "⚙️ Subagent already finished." },
+                reply: { text: `${formatRunLabel(resolved.entry)} is already finished.` },
             };
         }
         const childKey = resolved.entry.childSessionKey;
@@ -198,7 +318,7 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
         }
         const cleared = clearSessionQueues([childKey, sessionId]);
         if (cleared.followupCleared > 0 || cleared.laneCleared > 0) {
-            logVerbose(`subagents stop: cleared followups=${cleared.followupCleared} lane=${cleared.laneCleared} keys=${cleared.keys.join(",")}`);
+            logVerbose(`subagents kill: cleared followups=${cleared.followupCleared} lane=${cleared.laneCleared} keys=${cleared.keys.join(",")}`);
         }
         if (entry) {
             entry.abortedLastRun = true;
@@ -208,10 +328,17 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
                 nextStore[childKey] = entry;
             });
         }
-        return {
-            shouldContinue: false,
-            reply: { text: `⚙️ Stop requested for ${formatRunLabel(resolved.entry)}.` },
-        };
+        markSubagentRunTerminated({
+            runId: resolved.entry.runId,
+            childSessionKey: childKey,
+            reason: "killed",
+        });
+        // Cascade: also stop any sub-sub-agents spawned by this child.
+        stopSubagentsForRequester({
+            cfg: params.cfg,
+            requesterSessionKey: childKey,
+        });
+        return { shouldContinue: false };
     }
     if (action === "info") {
         const target = restTokens[0];
@@ -228,14 +355,14 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
         const run = resolved.entry;
         const { entry: sessionEntry } = loadSubagentSessionEntry(params, run.childSessionKey);
         const runtime = run.startedAt && Number.isFinite(run.startedAt)
-            ? formatDurationShort((run.endedAt ?? Date.now()) - run.startedAt)
+            ? (formatDurationCompact((run.endedAt ?? Date.now()) - run.startedAt) ?? "n/a")
             : "n/a";
         const outcome = run.outcome
             ? `${run.outcome.status}${run.outcome.error ? ` (${run.outcome.error})` : ""}`
             : "n/a";
         const lines = [
             "ℹ️ Subagent info",
-            `Status: ${formatRunStatus(run)}`,
+            `Status: ${resolveDisplayStatus(run)}`,
             `Label: ${formatRunLabel(run)}`,
             `Task: ${run.task}`,
             `Run: ${run.runId}`,
@@ -268,10 +395,10 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
                 reply: { text: `⚠️ ${resolved.error ?? "Unknown subagent."}` },
             };
         }
-        const history = (await callGateway({
+        const history = await callGateway({
             method: "chat.history",
             params: { sessionKey: resolved.entry.childSessionKey, limit },
-        }));
+        });
         const rawMessages = Array.isArray(history?.messages) ? history.messages : [];
         const filtered = includeTools ? rawMessages : stripToolMessages(rawMessages);
         const lines = formatLogLines(filtered);
@@ -281,13 +408,20 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
         }
         return { shouldContinue: false, reply: { text: [header, ...lines].join("\n") } };
     }
-    if (action === "send") {
+    if (action === "send" || action === "steer") {
+        const steerRequested = action === "steer";
         const target = restTokens[0];
         const message = restTokens.slice(1).join(" ").trim();
         if (!target || !message) {
             return {
                 shouldContinue: false,
-                reply: { text: "✉️ Usage: /subagents send <id|#> <message>" },
+                reply: {
+                    text: steerRequested
+                        ? handledPrefix === COMMAND
+                            ? "Usage: /subagents steer <id|#> <message>"
+                            : `Usage: ${handledPrefix} <id|#> <message>`
+                        : "Usage: /subagents send <id|#> <message>",
+                },
             };
         }
         const resolved = resolveSubagentTarget(runs, target);
@@ -297,34 +431,94 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
                 reply: { text: `⚠️ ${resolved.error ?? "Unknown subagent."}` },
             };
         }
+        if (steerRequested && resolved.entry.endedAt) {
+            return {
+                shouldContinue: false,
+                reply: { text: `${formatRunLabel(resolved.entry)} is already finished.` },
+            };
+        }
+        const { entry: targetSessionEntry } = loadSubagentSessionEntry(params, resolved.entry.childSessionKey);
+        const targetSessionId = typeof targetSessionEntry?.sessionId === "string" && targetSessionEntry.sessionId.trim()
+            ? targetSessionEntry.sessionId.trim()
+            : undefined;
+        if (steerRequested) {
+            // Suppress stale announce before interrupting the in-flight run.
+            markSubagentRunForSteerRestart(resolved.entry.runId);
+            // Force an immediate interruption and make steer the next run.
+            if (targetSessionId) {
+                abortEmbeddedPiRun(targetSessionId);
+            }
+            const cleared = clearSessionQueues([resolved.entry.childSessionKey, targetSessionId]);
+            if (cleared.followupCleared > 0 || cleared.laneCleared > 0) {
+                logVerbose(`subagents steer: cleared followups=${cleared.followupCleared} lane=${cleared.laneCleared} keys=${cleared.keys.join(",")}`);
+            }
+            // Best effort: wait for the interrupted run to settle so the steer
+            // message is appended on the existing conversation state.
+            try {
+                await callGateway({
+                    method: "agent.wait",
+                    params: {
+                        runId: resolved.entry.runId,
+                        timeoutMs: STEER_ABORT_SETTLE_TIMEOUT_MS,
+                    },
+                    timeoutMs: STEER_ABORT_SETTLE_TIMEOUT_MS + 2_000,
+                });
+            }
+            catch {
+                // Continue even if wait fails; steer should still be attempted.
+            }
+        }
         const idempotencyKey = crypto.randomUUID();
         let runId = idempotencyKey;
         try {
-            const response = (await callGateway({
+            const response = await callGateway({
                 method: "agent",
                 params: {
                     message,
                     sessionKey: resolved.entry.childSessionKey,
+                    sessionId: targetSessionId,
                     idempotencyKey,
                     deliver: false,
                     channel: INTERNAL_MESSAGE_CHANNEL,
                     lane: AGENT_LANE_SUBAGENT,
+                    timeout: 0,
                 },
                 timeoutMs: 10_000,
-            }));
-            if (response?.runId)
-                runId = response.runId;
+            });
+            const responseRunId = typeof response?.runId === "string" ? response.runId : undefined;
+            if (responseRunId) {
+                runId = responseRunId;
+            }
         }
         catch (err) {
+            if (steerRequested) {
+                // Replacement launch failed; restore announce behavior for the
+                // original run so completion is not silently suppressed.
+                clearSubagentRunSteerRestart(resolved.entry.runId);
+            }
             const messageText = err instanceof Error ? err.message : typeof err === "string" ? err : "error";
-            return { shouldContinue: false, reply: { text: `⚠️ Send failed: ${messageText}` } };
+            return { shouldContinue: false, reply: { text: `send failed: ${messageText}` } };
+        }
+        if (steerRequested) {
+            replaceSubagentRunAfterSteer({
+                previousRunId: resolved.entry.runId,
+                nextRunId: runId,
+                fallback: resolved.entry,
+                runTimeoutSeconds: resolved.entry.runTimeoutSeconds ?? 0,
+            });
+            return {
+                shouldContinue: false,
+                reply: {
+                    text: `steered ${formatRunLabel(resolved.entry)} (run ${runId.slice(0, 8)}).`,
+                },
+            };
         }
         const waitMs = 30_000;
-        const wait = (await callGateway({
+        const wait = await callGateway({
             method: "agent.wait",
             params: { runId, timeoutMs: waitMs },
             timeoutMs: waitMs + 2000,
-        }));
+        });
         if (wait?.status === "timeout") {
             return {
                 shouldContinue: false,
@@ -332,17 +526,18 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
             };
         }
         if (wait?.status === "error") {
+            const waitError = typeof wait.error === "string" ? wait.error : "unknown error";
             return {
                 shouldContinue: false,
                 reply: {
-                    text: `⚠️ Subagent error: ${wait.error ?? "unknown error"} (run ${runId.slice(0, 8)}).`,
+                    text: `⚠️ Subagent error: ${waitError} (run ${runId.slice(0, 8)}).`,
                 },
             };
         }
-        const history = (await callGateway({
+        const history = await callGateway({
             method: "chat.history",
             params: { sessionKey: resolved.entry.childSessionKey, limit: 50 },
-        }));
+        });
         const filtered = stripToolMessages(Array.isArray(history?.messages) ? history.messages : []);
         const last = filtered.length > 0 ? filtered[filtered.length - 1] : undefined;
         const replyText = last ? extractAssistantText(last) : undefined;
@@ -353,5 +548,62 @@ export const handleSubagentsCommand = async (params, allowTextCommands) => {
             },
         };
     }
+    if (action === "spawn") {
+        const agentId = restTokens[0];
+        // Parse remaining tokens: task text with optional --model and --thinking flags.
+        const taskParts = [];
+        let model;
+        let thinking;
+        for (let i = 1; i < restTokens.length; i++) {
+            if (restTokens[i] === "--model" && i + 1 < restTokens.length) {
+                i += 1;
+                model = restTokens[i];
+            }
+            else if (restTokens[i] === "--thinking" && i + 1 < restTokens.length) {
+                i += 1;
+                thinking = restTokens[i];
+            }
+            else {
+                taskParts.push(restTokens[i]);
+            }
+        }
+        const task = taskParts.join(" ").trim();
+        if (!agentId || !task) {
+            return {
+                shouldContinue: false,
+                reply: {
+                    text: "Usage: /subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]",
+                },
+            };
+        }
+        const commandTo = typeof params.command.to === "string" ? params.command.to.trim() : "";
+        const originatingTo = typeof params.ctx.OriginatingTo === "string" ? params.ctx.OriginatingTo.trim() : "";
+        const fallbackTo = typeof params.ctx.To === "string" ? params.ctx.To.trim() : "";
+        // OriginatingTo reflects the active conversation target and is safer than
+        // command.to for cross-surface command dispatch.
+        const normalizedTo = originatingTo || commandTo || fallbackTo || undefined;
+        const result = await spawnSubagentDirect({ task, agentId, model, thinking, cleanup: "keep", expectsCompletionMessage: true }, {
+            agentSessionKey: requesterKey,
+            agentChannel: params.ctx.OriginatingChannel ?? params.command.channel,
+            agentAccountId: params.ctx.AccountId,
+            agentTo: normalizedTo,
+            agentThreadId: params.ctx.MessageThreadId,
+            agentGroupId: params.sessionEntry?.groupId ?? null,
+            agentGroupChannel: params.sessionEntry?.groupChannel ?? null,
+            agentGroupSpace: params.sessionEntry?.space ?? null,
+        });
+        if (result.status === "accepted") {
+            return {
+                shouldContinue: false,
+                reply: {
+                    text: `Spawned subagent ${agentId} (session ${result.childSessionKey}, run ${result.runId?.slice(0, 8)}).`,
+                },
+            };
+        }
+        return {
+            shouldContinue: false,
+            reply: { text: `Spawn failed: ${result.error ?? result.status}` },
+        };
+    }
     return { shouldContinue: false, reply: { text: buildSubagentsHelp() } };
 };