@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/dist/agents/subagent-announce.js

@@ -1,97 +1,258 @@
-import crypto from "node:crypto";
-import path from "node:path";
 import { resolveQueueSettings } from "../auto-reply/reply/queue.js";
+import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
 import { loadConfig } from "../config/config.js";
 import { loadSessionStore, resolveAgentIdFromSessionKey, resolveMainSessionKey, resolveStorePath, } from "../config/sessions.js";
 import { callGateway } from "../gateway/call.js";
-import { formatDurationCompact } from "../infra/format-time/format-duration.js";
 import { normalizeMainKey } from "../routing/session-key.js";
 import { defaultRuntime } from "../runtime.js";
+import { extractTextFromChatContent } from "../shared/chat-content.js";
 import { deliveryContextFromSession, mergeDeliveryContext, normalizeDeliveryContext, } from "../utils/delivery-context.js";
+import { isDeliverableMessageChannel } from "../utils/message-channel.js";
+import { buildAnnounceIdFromChildRun, buildAnnounceIdempotencyKey, resolveQueueAnnounceId, } from "./announce-idempotency.js";
 import { isEmbeddedPiRunActive, queueEmbeddedPiMessage, waitForEmbeddedPiRunEnd, } from "./pi-embedded.js";
 import { enqueueAnnounce } from "./subagent-announce-queue.js";
-import { readLatestAssistantReply } from "./tools/agent-step.js";
+import { getSubagentDepthFromSessionStore } from "./subagent-depth.js";
+import { sanitizeTextContent, extractAssistantText } from "./tools/sessions-helpers.js";
+function buildCompletionDeliveryMessage(params) {
+    const findingsText = params.findings.trim();
+    const hasFindings = findingsText.length > 0 && findingsText !== "(no output)";
+    const header = `✅ Subagent ${params.subagentName} finished`;
+    if (!hasFindings) {
+        return header;
+    }
+    return `${header}\n\n${findingsText}`;
+}
+function summarizeDeliveryError(error) {
+    if (error instanceof Error) {
+        return error.message || "error";
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    if (error === undefined || error === null) {
+        return "unknown error";
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return "error";
+    }
+}
+function extractToolResultText(content) {
+    if (typeof content === "string") {
+        return sanitizeTextContent(content);
+    }
+    if (content && typeof content === "object" && !Array.isArray(content)) {
+        const obj = content;
+        if (typeof obj.text === "string") {
+            return sanitizeTextContent(obj.text);
+        }
+        if (typeof obj.output === "string") {
+            return sanitizeTextContent(obj.output);
+        }
+        if (typeof obj.content === "string") {
+            return sanitizeTextContent(obj.content);
+        }
+        if (typeof obj.result === "string") {
+            return sanitizeTextContent(obj.result);
+        }
+        if (typeof obj.error === "string") {
+            return sanitizeTextContent(obj.error);
+        }
+        if (typeof obj.summary === "string") {
+            return sanitizeTextContent(obj.summary);
+        }
+    }
+    if (!Array.isArray(content)) {
+        return "";
+    }
+    const joined = extractTextFromChatContent(content, {
+        sanitizeText: sanitizeTextContent,
+        normalizeText: (text) => text,
+        joinWith: "\n",
+    });
+    return joined?.trim() ?? "";
+}
+function extractSubagentOutputText(message) {
+    if (!message || typeof message !== "object") {
+        return "";
+    }
+    const role = message.role;
+    const content = message.content;
+    if (role === "assistant") {
+        const assistantText = extractAssistantText(message);
+        if (assistantText) {
+            return assistantText;
+        }
+        if (typeof content === "string") {
+            return sanitizeTextContent(content);
+        }
+        if (Array.isArray(content)) {
+            return (extractTextFromChatContent(content, {
+                sanitizeText: sanitizeTextContent,
+                normalizeText: (text) => text.trim(),
+                joinWith: "",
+            }) ?? "");
+        }
+        return "";
+    }
+    if (role === "toolResult" || role === "tool") {
+        return extractToolResultText(message.content);
+    }
+    if (typeof content === "string") {
+        return sanitizeTextContent(content);
+    }
+    if (Array.isArray(content)) {
+        return (extractTextFromChatContent(content, {
+            sanitizeText: sanitizeTextContent,
+            normalizeText: (text) => text.trim(),
+            joinWith: "",
+        }) ?? "");
+    }
+    return "";
+}
+async function readLatestSubagentOutput(sessionKey) {
+    const history = await callGateway({
+        method: "chat.history",
+        params: { sessionKey, limit: 50 },
+    });
+    const messages = Array.isArray(history?.messages) ? history.messages : [];
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const msg = messages[i];
+        const text = extractSubagentOutputText(msg);
+        if (text) {
+            return text;
+        }
+    }
+    return undefined;
+}
+async function readLatestSubagentOutputWithRetry(params) {
+    const RETRY_INTERVAL_MS = 100;
+    const deadline = Date.now() + Math.max(0, Math.min(params.maxWaitMs, 15_000));
+    let result;
+    while (Date.now() < deadline) {
+        result = await readLatestSubagentOutput(params.sessionKey);
+        if (result?.trim()) {
+            return result;
+        }
+        await new Promise((resolve) => setTimeout(resolve, RETRY_INTERVAL_MS));
+    }
+    return result;
+}
+function formatDurationShort(valueMs) {
+    if (!valueMs || !Number.isFinite(valueMs) || valueMs <= 0) {
+        return "n/a";
+    }
+    const totalSeconds = Math.round(valueMs / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0) {
+        return `${hours}h${minutes}m`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m${seconds}s`;
+    }
+    return `${seconds}s`;
+}
 function formatTokenCount(value) {
-    if (!value || !Number.isFinite(value))
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
         return "0";
-    if (value >= 1_000_000)
+    }
+    if (value >= 1_000_000) {
         return `${(value / 1_000_000).toFixed(1)}m`;
-    if (value >= 1_000)
+    }
+    if (value >= 1_000) {
         return `${(value / 1_000).toFixed(1)}k`;
+    }
     return String(Math.round(value));
 }
-function formatUsd(value) {
-    if (value === undefined || !Number.isFinite(value))
-        return undefined;
-    if (value >= 1)
-        return `$${value.toFixed(2)}`;
-    if (value >= 0.01)
-        return `$${value.toFixed(2)}`;
-    return `$${value.toFixed(4)}`;
-}
-function resolveModelCost(params) {
-    const provider = params.provider?.trim();
-    const model = params.model?.trim();
-    if (!provider || !model)
-        return undefined;
-    const models = params.config.models?.providers?.[provider]?.models ?? [];
-    const entry = models.find((candidate) => candidate.id === model);
-    return entry?.cost;
-}
-async function waitForSessionUsage(params) {
+async function buildCompactAnnounceStatsLine(params) {
     const cfg = loadConfig();
     const agentId = resolveAgentIdFromSessionKey(params.sessionKey);
     const storePath = resolveStorePath(cfg.session?.store, { agentId });
     let entry = loadSessionStore(storePath)[params.sessionKey];
-    if (!entry)
-        return { entry, storePath };
-    const hasTokens = () => entry &&
-        (typeof entry.totalTokens === "number" ||
-            typeof entry.inputTokens === "number" ||
-            typeof entry.outputTokens === "number");
-    if (hasTokens())
-        return { entry, storePath };
-    for (let attempt = 0; attempt < 4; attempt += 1) {
-        await new Promise((resolve) => setTimeout(resolve, 200));
-        entry = loadSessionStore(storePath)[params.sessionKey];
-        if (hasTokens())
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const hasTokenData = typeof entry?.inputTokens === "number" ||
+            typeof entry?.outputTokens === "number" ||
+            typeof entry?.totalTokens === "number";
+        if (hasTokenData) {
             break;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 150));
+        entry = loadSessionStore(storePath)[params.sessionKey];
+    }
+    const input = typeof entry?.inputTokens === "number" ? entry.inputTokens : 0;
+    const output = typeof entry?.outputTokens === "number" ? entry.outputTokens : 0;
+    const ioTotal = input + output;
+    const promptCache = typeof entry?.totalTokens === "number" ? entry.totalTokens : undefined;
+    const runtimeMs = typeof params.startedAt === "number" && typeof params.endedAt === "number"
+        ? Math.max(0, params.endedAt - params.startedAt)
+        : undefined;
+    const parts = [
+        `runtime ${formatDurationShort(runtimeMs)}`,
+        `tokens ${formatTokenCount(ioTotal)} (in ${formatTokenCount(input)} / out ${formatTokenCount(output)})`,
+    ];
+    if (typeof promptCache === "number" && promptCache > ioTotal) {
+        parts.push(`prompt/cache ${formatTokenCount(promptCache)}`);
     }
-    return { entry, storePath };
+    return `Stats: ${parts.join(" • ")}`;
 }
 function resolveAnnounceOrigin(entry, requesterOrigin) {
+    const normalizedRequester = normalizeDeliveryContext(requesterOrigin);
+    const normalizedEntry = deliveryContextFromSession(entry);
+    if (normalizedRequester?.channel && !isDeliverableMessageChannel(normalizedRequester.channel)) {
+        // Ignore internal/non-deliverable channel hints (for example webchat)
+        // so a valid persisted route can still be used for outbound delivery.
+        return mergeDeliveryContext({
+            accountId: normalizedRequester.accountId,
+            threadId: normalizedRequester.threadId,
+        }, normalizedEntry);
+    }
     // requesterOrigin (captured at spawn time) reflects the channel the user is
     // actually on and must take priority over the session entry, which may carry
     // stale lastChannel / lastTo values from a previous channel interaction.
-    return mergeDeliveryContext(requesterOrigin, deliveryContextFromSession(entry));
+    return mergeDeliveryContext(normalizedRequester, normalizedEntry);
 }
 async function sendAnnounce(item) {
+    const requesterDepth = getSubagentDepthFromSessionStore(item.sessionKey);
+    const requesterIsSubagent = requesterDepth >= 1;
     const origin = item.origin;
     const threadId = origin?.threadId != null && origin.threadId !== "" ? String(origin.threadId) : undefined;
+    // Share one announce identity across direct and queued delivery paths so
+    // gateway dedupe suppresses true retries without collapsing distinct events.
+    const idempotencyKey = buildAnnounceIdempotencyKey(resolveQueueAnnounceId({
+        announceId: item.announceId,
+        sessionKey: item.sessionKey,
+        enqueuedAt: item.enqueuedAt,
+    }));
     await callGateway({
         method: "agent",
         params: {
             sessionKey: item.sessionKey,
             message: item.prompt,
-            channel: origin?.channel,
-            accountId: origin?.accountId,
-            to: origin?.to,
-            threadId,
-            deliver: true,
-            idempotencyKey: crypto.randomUUID(),
+            channel: requesterIsSubagent ? undefined : origin?.channel,
+            accountId: requesterIsSubagent ? undefined : origin?.accountId,
+            to: requesterIsSubagent ? undefined : origin?.to,
+            threadId: requesterIsSubagent ? undefined : threadId,
+            deliver: !requesterIsSubagent,
+            idempotencyKey,
         },
-        expectFinal: true,
-        timeoutMs: 60_000,
+        timeoutMs: 15_000,
     });
 }
 function resolveRequesterStoreKey(cfg, requesterSessionKey) {
     const raw = requesterSessionKey.trim();
-    if (!raw)
+    if (!raw) {
         return raw;
-    if (raw === "global" || raw === "unknown")
+    }
+    if (raw === "global" || raw === "unknown") {
         return raw;
-    if (raw.startsWith("agent:"))
+    }
+    if (raw.startsWith("agent:")) {
         return raw;
+    }
     const mainKey = normalizeMainKey(cfg.session?.mainKey);
     if (raw === "main" || raw === mainKey) {
         return resolveMainSessionKey(cfg);
@@ -112,8 +273,9 @@ async function maybeQueueSubagentAnnounce(params) {
     const { cfg, entry } = loadRequesterSessionEntry(params.requesterSessionKey);
     const canonicalKey = resolveRequesterStoreKey(cfg, params.requesterSessionKey);
     const sessionId = entry?.sessionId;
-    if (!sessionId)
+    if (!sessionId) {
         return "none";
+    }
     const queueSettings = resolveQueueSettings({
         cfg,
         channel: entry?.channel ?? entry?.lastChannel,
@@ -123,8 +285,9 @@ async function maybeQueueSubagentAnnounce(params) {
     const shouldSteer = queueSettings.mode === "steer" || queueSettings.mode === "steer-backlog";
     if (shouldSteer) {
         const steered = queueEmbeddedPiMessage(sessionId, params.triggerMessage);
-        if (steered)
+        if (steered) {
             return "steered";
+        }
     }
     const shouldFollowup = queueSettings.mode === "followup" ||
         queueSettings.mode === "collect" ||
@@ -135,6 +298,7 @@ async function maybeQueueSubagentAnnounce(params) {
         enqueueAnnounce({
             key: canonicalKey,
             item: {
+                announceId: params.announceId,
                 prompt: params.triggerMessage,
                 summaryLine: params.summaryLine,
                 enqueuedAt: Date.now(),
@@ -148,47 +312,137 @@ async function maybeQueueSubagentAnnounce(params) {
     }
     return "none";
 }
-async function buildSubagentStatsLine(params) {
+function queueOutcomeToDeliveryResult(outcome) {
+    if (outcome === "steered") {
+        return {
+            delivered: true,
+            path: "steered",
+        };
+    }
+    if (outcome === "queued") {
+        return {
+            delivered: true,
+            path: "queued",
+        };
+    }
+    return {
+        delivered: false,
+        path: "none",
+    };
+}
+async function sendSubagentAnnounceDirectly(params) {
     const cfg = loadConfig();
-    const { entry, storePath } = await waitForSessionUsage({
-        sessionKey: params.sessionKey,
+    const canonicalRequesterSessionKey = resolveRequesterStoreKey(cfg, params.targetRequesterSessionKey);
+    try {
+        const completionDirectOrigin = normalizeDeliveryContext(params.completionDirectOrigin);
+        const completionChannelRaw = typeof completionDirectOrigin?.channel === "string"
+            ? completionDirectOrigin.channel.trim()
+            : "";
+        const completionChannel = completionChannelRaw && isDeliverableMessageChannel(completionChannelRaw)
+            ? completionChannelRaw
+            : "";
+        const completionTo = typeof completionDirectOrigin?.to === "string" ? completionDirectOrigin.to.trim() : "";
+        const hasCompletionDirectTarget = !params.requesterIsSubagent && Boolean(completionChannel) && Boolean(completionTo);
+        if (params.expectsCompletionMessage &&
+            hasCompletionDirectTarget &&
+            params.completionMessage?.trim()) {
+            const completionThreadId = completionDirectOrigin?.threadId != null && completionDirectOrigin.threadId !== ""
+                ? String(completionDirectOrigin.threadId)
+                : undefined;
+            await callGateway({
+                method: "send",
+                params: {
+                    channel: completionChannel,
+                    to: completionTo,
+                    accountId: completionDirectOrigin?.accountId,
+                    threadId: completionThreadId,
+                    sessionKey: canonicalRequesterSessionKey,
+                    message: params.completionMessage,
+                    idempotencyKey: params.directIdempotencyKey,
+                },
+                timeoutMs: 15_000,
+            });
+            return {
+                delivered: true,
+                path: "direct",
+            };
+        }
+        const directOrigin = normalizeDeliveryContext(params.directOrigin);
+        const threadId = directOrigin?.threadId != null && directOrigin.threadId !== ""
+            ? String(directOrigin.threadId)
+            : undefined;
+        await callGateway({
+            method: "agent",
+            params: {
+                sessionKey: canonicalRequesterSessionKey,
+                message: params.triggerMessage,
+                deliver: !params.requesterIsSubagent,
+                channel: params.requesterIsSubagent ? undefined : directOrigin?.channel,
+                accountId: params.requesterIsSubagent ? undefined : directOrigin?.accountId,
+                to: params.requesterIsSubagent ? undefined : directOrigin?.to,
+                threadId: params.requesterIsSubagent ? undefined : threadId,
+                idempotencyKey: params.directIdempotencyKey,
+            },
+            expectFinal: true,
+            timeoutMs: 15_000,
+        });
+        return {
+            delivered: true,
+            path: "direct",
+        };
+    }
+    catch (err) {
+        return {
+            delivered: false,
+            path: "direct",
+            error: summarizeDeliveryError(err),
+        };
+    }
+}
+async function deliverSubagentAnnouncement(params) {
+    // Non-completion mode mirrors historical behavior: try queued/steered delivery first,
+    // then (only if not queued) attempt direct delivery.
+    if (!params.expectsCompletionMessage) {
+        const queueOutcome = await maybeQueueSubagentAnnounce({
+            requesterSessionKey: params.requesterSessionKey,
+            announceId: params.announceId,
+            triggerMessage: params.triggerMessage,
+            summaryLine: params.summaryLine,
+            requesterOrigin: params.requesterOrigin,
+        });
+        const queued = queueOutcomeToDeliveryResult(queueOutcome);
+        if (queued.delivered) {
+            return queued;
+        }
+    }
+    // Completion-mode uses direct send first so manual spawns can return immediately
+    // in the common ready-to-deliver case.
+    const direct = await sendSubagentAnnounceDirectly({
+        targetRequesterSessionKey: params.targetRequesterSessionKey,
+        triggerMessage: params.triggerMessage,
+        completionMessage: params.completionMessage,
+        directIdempotencyKey: params.directIdempotencyKey,
+        completionDirectOrigin: params.completionDirectOrigin,
+        directOrigin: params.directOrigin,
+        requesterIsSubagent: params.requesterIsSubagent,
+        expectsCompletionMessage: params.expectsCompletionMessage,
     });
-    const sessionId = entry?.sessionId;
-    const transcriptPath = sessionId && storePath ? path.join(path.dirname(storePath), `${sessionId}.jsonl`) : undefined;
-    const input = entry?.inputTokens;
-    const output = entry?.outputTokens;
-    const total = entry?.totalTokens ??
-        (typeof input === "number" && typeof output === "number" ? input + output : undefined);
-    const runtimeMs = typeof params.startedAt === "number" && typeof params.endedAt === "number"
-        ? Math.max(0, params.endedAt - params.startedAt)
-        : undefined;
-    const provider = entry?.modelProvider;
-    const model = entry?.model;
-    const costConfig = resolveModelCost({ provider, model, config: cfg });
-    const cost = costConfig && typeof input === "number" && typeof output === "number"
-        ? (input * costConfig.input + output * costConfig.output) / 1_000_000
-        : undefined;
-    const parts = [];
-    const runtime = formatDurationCompact(runtimeMs);
-    parts.push(`runtime ${runtime ?? "n/a"}`);
-    if (typeof total === "number") {
-        const inputText = typeof input === "number" ? formatTokenCount(input) : "n/a";
-        const outputText = typeof output === "number" ? formatTokenCount(output) : "n/a";
-        const totalText = formatTokenCount(total);
-        parts.push(`tokens ${totalText} (in ${inputText} / out ${outputText})`);
-    }
-    else {
-        parts.push("tokens n/a");
-    }
-    const costText = formatUsd(cost);
-    if (costText)
-        parts.push(`est ${costText}`);
-    parts.push(`sessionKey ${params.sessionKey}`);
-    if (sessionId)
-        parts.push(`sessionId ${sessionId}`);
-    if (transcriptPath)
-        parts.push(`transcript ${transcriptPath}`);
-    return `Stats: ${parts.join(" \u2022 ")}`;
+    if (direct.delivered || !params.expectsCompletionMessage) {
+        return direct;
+    }
+    // If completion path failed direct delivery, try queueing as a fallback so the
+    // report can still be delivered once the requester session is idle.
+    const queueOutcome = await maybeQueueSubagentAnnounce({
+        requesterSessionKey: params.requesterSessionKey,
+        announceId: params.announceId,
+        triggerMessage: params.triggerMessage,
+        summaryLine: params.summaryLine,
+        requesterOrigin: params.requesterOrigin,
+    });
+    if (queueOutcome === "steered" || queueOutcome === "queued") {
+        return queueOutcomeToDeliveryResult(queueOutcome);
+    }
+    return direct;
 }
 function loadSessionEntryByKey(sessionKey) {
     const cfg = loadConfig();
@@ -197,70 +451,84 @@ function loadSessionEntryByKey(sessionKey) {
     const store = loadSessionStore(storePath);
     return store[sessionKey];
 }
-async function readLatestAssistantReplyWithRetry(params) {
-    let reply = params.initialReply?.trim() ? params.initialReply : undefined;
-    if (reply) {
-        return reply;
-    }
-    const deadline = Date.now() + Math.max(0, Math.min(params.maxWaitMs, 15_000));
-    while (Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, 300));
-        const latest = await readLatestAssistantReply({ sessionKey: params.sessionKey });
-        if (latest?.trim()) {
-            return latest;
-        }
-    }
-    return reply;
-}
 export function buildSubagentSystemPrompt(params) {
     const taskText = typeof params.task === "string" && params.task.trim()
         ? params.task.replace(/\s+/g, " ").trim()
         : "{{TASK_DESCRIPTION}}";
+    const childDepth = typeof params.childDepth === "number" ? params.childDepth : 1;
+    const maxSpawnDepth = typeof params.maxSpawnDepth === "number" ? params.maxSpawnDepth : 1;
+    const canSpawn = childDepth < maxSpawnDepth;
+    const parentLabel = childDepth >= 2 ? "parent orchestrator" : "main agent";
     const lines = [
         "# Subagent Context",
         "",
-        "You are a **subagent** spawned by the main agent for a specific task.",
+        `You are a **subagent** spawned by the ${parentLabel} for a specific task.`,
         "",
         "## Your Role",
         `- You were created to handle: ${taskText}`,
         "- Complete this task. That's your entire purpose.",
-        "- You are NOT the main agent. Don't try to be.",
+        `- You are NOT the ${parentLabel}. Don't try to be.`,
         "",
         "## Rules",
         "1. **Stay focused** - Do your assigned task, nothing else",
-        "2. **Complete the task** - Your final message will be automatically reported to the main agent",
+        `2. **Complete the task** - Your final message will be automatically reported to the ${parentLabel}`,
         "3. **Don't initiate** - No heartbeats, no proactive actions, no side quests",
         "4. **Be ephemeral** - You may be terminated after task completion. That's fine.",
+        "5. **Trust push-based completion** - Descendant results are auto-announced back to you; do not busy-poll for status.",
+        "6. **Recover from compacted/truncated tool output** - If you see `[compacted: tool output removed to free context]` or `[truncated: output exceeded context limit]`, assume prior output was reduced. Re-read only what you need using smaller chunks (`read` with offset/limit, or targeted `rg`/`head`/`tail`) instead of full-file `cat`.",
         "",
         "## Output Format",
         "When complete, your final response should include:",
-        "- What you accomplished or found",
-        "- Any relevant details the main agent should know",
+        `- What you accomplished or found`,
+        `- Any relevant details the ${parentLabel} should know`,
         "- Keep it concise but informative",
         "",
         "## What You DON'T Do",
-        "- NO user conversations (that's main agent's job)",
+        `- NO user conversations (that's ${parentLabel}'s job)`,
         "- NO external messages (email, tweets, etc.) unless explicitly tasked with a specific recipient/channel",
         "- NO cron jobs or persistent state",
-        "- NO pretending to be the main agent",
-        "- Only use the `message` tool when explicitly instructed to contact a specific external recipient; otherwise return plain text and let the main agent deliver it",
+        `- NO pretending to be the ${parentLabel}`,
+        `- Only use the \`message\` tool when explicitly instructed to contact a specific external recipient; otherwise return plain text and let the ${parentLabel} deliver it`,
         "",
-        "## Session Context",
+    ];
+    if (canSpawn) {
+        lines.push("## Sub-Agent Spawning", "You CAN spawn your own sub-agents for parallel or complex work using `sessions_spawn`.", "Use the `subagents` tool to steer, kill, or do an on-demand status check for your spawned sub-agents.", "Your sub-agents will announce their results back to you automatically (not to the main agent).", "Default workflow: spawn work, continue orchestrating, and wait for auto-announced completions.", "Do NOT repeatedly poll `subagents list` in a loop unless you are actively debugging or intervening.", "Coordinate their work and synthesize results before reporting back.", "");
+    }
+    else if (childDepth >= 2) {
+        lines.push("## Sub-Agent Spawning", "You are a leaf worker and CANNOT spawn further sub-agents. Focus on your assigned task.", "");
+    }
+    lines.push("## Session Context", ...[
         params.label ? `- Label: ${params.label}` : undefined,
-        params.requesterSessionKey ? `- Requester session: ${params.requesterSessionKey}.` : undefined,
+        params.requesterSessionKey
+            ? `- Requester session: ${params.requesterSessionKey}.`
+            : undefined,
         params.requesterOrigin?.channel
             ? `- Requester channel: ${params.requesterOrigin.channel}.`
             : undefined,
         `- Your session: ${params.childSessionKey}.`,
-        "",
-    ].filter((line) => line !== undefined);
+    ].filter((line) => line !== undefined), "");
     return lines.join("\n");
 }
+function buildAnnounceReplyInstruction(params) {
+    if (params.expectsCompletionMessage) {
+        return `A completed ${params.announceType} is ready for user delivery. Convert the result above into your normal assistant voice and send that user-facing update now. Keep this internal context private (don't mention system/log/stats/session details or announce type).`;
+    }
+    if (params.remainingActiveSubagentRuns > 0) {
+        const activeRunsLabel = params.remainingActiveSubagentRuns === 1 ? "run" : "runs";
+        return `There are still ${params.remainingActiveSubagentRuns} active subagent ${activeRunsLabel} for this session. If they are part of the same workflow, wait for the remaining results before sending a user update. If they are unrelated, respond normally using only the result above.`;
+    }
+    if (params.requesterIsSubagent) {
+        return `Convert this completion into a concise internal orchestration update for your parent agent in your own words. Keep this internal context private (don't mention system/log/stats/session details or announce type). If this result is duplicate or no update is needed, reply ONLY: ${SILENT_REPLY_TOKEN}.`;
+    }
+    return `A completed ${params.announceType} is ready for user delivery. Convert the result above into your normal assistant voice and send that user-facing update now. Keep this internal context private (don't mention system/log/stats/session details or announce type), and do not copy the system message verbatim. Reply ONLY: ${SILENT_REPLY_TOKEN} if this exact result was already delivered to the user in this same turn.`;
+}
 export async function runSubagentAnnounceFlow(params) {
     let didAnnounce = false;
+    const expectsCompletionMessage = params.expectsCompletionMessage === true;
     let shouldDeleteChildSession = params.cleanup === "delete";
     try {
-        const requesterOrigin = normalizeDeliveryContext(params.requesterOrigin);
+        let targetRequesterSessionKey = params.requesterSessionKey;
+        let targetRequesterOrigin = normalizeDeliveryContext(params.requesterOrigin);
         const childSessionId = (() => {
             const entry = loadSessionEntryByKey(params.childSessionKey);
             return typeof entry?.sessionId === "string" && entry.sessionId.trim()
@@ -272,7 +540,7 @@ export async function runSubagentAnnounceFlow(params) {
         let outcome = params.outcome;
         // Lifecycle "end" can arrive before auto-compaction retries finish. If the
         // subagent is still active, wait for the embedded run to fully settle.
-        if (childSessionId && isEmbeddedPiRunActive(childSessionId)) {
+        if (!expectsCompletionMessage && childSessionId && isEmbeddedPiRunActive(childSessionId)) {
             const settled = await waitForEmbeddedPiRunEnd(childSessionId, settleTimeoutMs);
             if (!settled && isEmbeddedPiRunActive(childSessionId)) {
                 // The child run is still active (e.g., compaction retry still in progress).
@@ -313,19 +581,21 @@ export async function runSubagentAnnounceFlow(params) {
                     outcome = { status: "timeout" };
                 }
             }
-            reply = await readLatestAssistantReply({ sessionKey: params.childSessionKey });
+            reply = await readLatestSubagentOutput(params.childSessionKey);
         }
         if (!reply) {
-            reply = await readLatestAssistantReply({ sessionKey: params.childSessionKey });
+            reply = await readLatestSubagentOutput(params.childSessionKey);
         }
         if (!reply?.trim()) {
-            reply = await readLatestAssistantReplyWithRetry({
+            reply = await readLatestSubagentOutputWithRetry({
                 sessionKey: params.childSessionKey,
-                initialReply: reply,
                 maxWaitMs: params.timeoutMs,
             });
         }
-        if (!reply?.trim() && childSessionId && isEmbeddedPiRunActive(childSessionId)) {
+        if (!expectsCompletionMessage &&
+            !reply?.trim() &&
+            childSessionId &&
+            isEmbeddedPiRunActive(childSessionId)) {
             // Avoid announcing "(no output)" while the child run is still producing output.
             shouldDeleteChildSession = false;
             return false;
@@ -333,12 +603,20 @@ export async function runSubagentAnnounceFlow(params) {
         if (!outcome) {
             outcome = { status: "unknown" };
         }
-        // Build stats
-        const statsLine = await buildSubagentStatsLine({
-            sessionKey: params.childSessionKey,
-            startedAt: params.startedAt,
-            endedAt: params.endedAt,
-        });
+        let activeChildDescendantRuns = 0;
+        try {
+            const { countActiveDescendantRuns } = await import("./subagent-registry.js");
+            activeChildDescendantRuns = Math.max(0, countActiveDescendantRuns(params.childSessionKey));
+        }
+        catch {
+            // Best-effort only; fall back to direct announce behavior when unavailable.
+        }
+        if (!expectsCompletionMessage && activeChildDescendantRuns > 0) {
+            // The finished run still has active descendant subagents. Defer announcing
+            // this run until descendants settle so we avoid posting in-progress updates.
+            shouldDeleteChildSession = false;
+            return false;
+        }
         // Build status label
         const statusLabel = outcome.status === "ok"
             ? "completed successfully"
@@ -350,56 +628,112 @@ export async function runSubagentAnnounceFlow(params) {
         // Build instructional message for main agent
         const announceType = params.announceType ?? "subagent task";
         const taskLabel = params.label || params.task || "task";
-        const triggerMessage = [
-            `A ${announceType} "${taskLabel}" just ${statusLabel}.`,
+        const subagentName = resolveAgentIdFromSessionKey(params.childSessionKey);
+        const announceSessionId = childSessionId || "unknown";
+        const findings = reply || "(no output)";
+        let completionMessage = "";
+        let triggerMessage = "";
+        let requesterDepth = getSubagentDepthFromSessionStore(targetRequesterSessionKey);
+        let requesterIsSubagent = !expectsCompletionMessage && requesterDepth >= 1;
+        // If the requester subagent has already finished, bubble the announce to its
+        // requester (typically main) so descendant completion is not silently lost.
+        // BUT: only fallback if the parent SESSION is deleted, not just if the current
+        // run ended. A parent waiting for child results has no active run but should
+        // still receive the announce — injecting will start a new agent turn.
+        if (requesterIsSubagent) {
+            const { isSubagentSessionRunActive, resolveRequesterForChildSession } = await import("./subagent-registry.js");
+            if (!isSubagentSessionRunActive(targetRequesterSessionKey)) {
+                // Parent run has ended. Check if parent SESSION still exists.
+                // If it does, the parent may be waiting for child results — inject there.
+                const parentSessionEntry = loadSessionEntryByKey(targetRequesterSessionKey);
+                const parentSessionAlive = parentSessionEntry &&
+                    typeof parentSessionEntry.sessionId === "string" &&
+                    parentSessionEntry.sessionId.trim();
+                if (!parentSessionAlive) {
+                    // Parent session is truly gone — fallback to grandparent
+                    const fallback = resolveRequesterForChildSession(targetRequesterSessionKey);
+                    if (!fallback?.requesterSessionKey) {
+                        // Without a requester fallback we cannot safely deliver this nested
+                        // completion. Keep cleanup retryable so a later registry restore can
+                        // recover and re-announce instead of silently dropping the result.
+                        shouldDeleteChildSession = false;
+                        return false;
+                    }
+                    targetRequesterSessionKey = fallback.requesterSessionKey;
+                    targetRequesterOrigin =
+                        normalizeDeliveryContext(fallback.requesterOrigin) ?? targetRequesterOrigin;
+                    requesterDepth = getSubagentDepthFromSessionStore(targetRequesterSessionKey);
+                    requesterIsSubagent = requesterDepth >= 1;
+                }
+                // If parent session is alive (just has no active run), continue with parent
+                // as target. Injecting the announce will start a new agent turn for processing.
+            }
+        }
+        let remainingActiveSubagentRuns = 0;
+        try {
+            const { countActiveDescendantRuns } = await import("./subagent-registry.js");
+            remainingActiveSubagentRuns = Math.max(0, countActiveDescendantRuns(targetRequesterSessionKey));
+        }
+        catch {
+            // Best-effort only; fall back to default announce instructions when unavailable.
+        }
+        const replyInstruction = buildAnnounceReplyInstruction({
+            remainingActiveSubagentRuns,
+            requesterIsSubagent,
+            announceType,
+            expectsCompletionMessage,
+        });
+        const statsLine = await buildCompactAnnounceStatsLine({
+            sessionKey: params.childSessionKey,
+            startedAt: params.startedAt,
+            endedAt: params.endedAt,
+        });
+        completionMessage = buildCompletionDeliveryMessage({
+            findings,
+            subagentName,
+        });
+        const internalSummaryMessage = [
+            `[System Message] [sessionId: ${announceSessionId}] A ${announceType} "${taskLabel}" just ${statusLabel}.`,
             "",
-            "Findings:",
-            reply || "(no output)",
+            "Result:",
+            findings,
             "",
             statsLine,
-            "",
-            "Summarize this naturally for the user. Keep it brief (1-2 sentences). Flow it into the conversation naturally.",
-            `Do not mention technical details like tokens, stats, or that this was a ${announceType}.`,
-            "You can respond with NO_REPLY if no announcement is needed (e.g., internal task with no user-facing result).",
         ].join("\n");
-        const queued = await maybeQueueSubagentAnnounce({
-            requesterSessionKey: params.requesterSessionKey,
+        triggerMessage = [internalSummaryMessage, "", replyInstruction].join("\n");
+        const announceId = buildAnnounceIdFromChildRun({
+            childSessionKey: params.childSessionKey,
+            childRunId: params.childRunId,
+        });
+        // Send to the requester session. For nested subagents this is an internal
+        // follow-up injection (deliver=false) so the orchestrator receives it.
+        let directOrigin = targetRequesterOrigin;
+        if (!requesterIsSubagent) {
+            const { entry } = loadRequesterSessionEntry(targetRequesterSessionKey);
+            directOrigin = resolveAnnounceOrigin(entry, targetRequesterOrigin);
+        }
+        // Use a deterministic idempotency key so the gateway dedup cache
+        // catches duplicates if this announce is also queued by the gateway-
+        // level message queue while the main session is busy (#17122).
+        const directIdempotencyKey = buildAnnounceIdempotencyKey(announceId);
+        const delivery = await deliverSubagentAnnouncement({
+            requesterSessionKey: targetRequesterSessionKey,
+            announceId,
             triggerMessage,
+            completionMessage,
             summaryLine: taskLabel,
-            requesterOrigin,
+            requesterOrigin: targetRequesterOrigin,
+            completionDirectOrigin: targetRequesterOrigin,
+            directOrigin,
+            targetRequesterSessionKey,
+            requesterIsSubagent,
+            expectsCompletionMessage: expectsCompletionMessage,
+            directIdempotencyKey,
         });
-        if (queued === "steered") {
-            didAnnounce = true;
-            return true;
+        didAnnounce = delivery.delivered;
+        if (!delivery.delivered && delivery.path === "direct" && delivery.error) {
+            defaultRuntime.error?.(`Subagent completion direct announce failed for run ${params.childRunId}: ${delivery.error}`);
         }
-        if (queued === "queued") {
-            didAnnounce = true;
-            return true;
-        }
-        // Send to main agent - it will respond in its own voice
-        let directOrigin = requesterOrigin;
-        if (!directOrigin) {
-            const { entry } = loadRequesterSessionEntry(params.requesterSessionKey);
-            directOrigin = deliveryContextFromSession(entry);
-        }
-        await callGateway({
-            method: "agent",
-            params: {
-                sessionKey: params.requesterSessionKey,
-                message: triggerMessage,
-                deliver: true,
-                channel: directOrigin?.channel,
-                accountId: directOrigin?.accountId,
-                to: directOrigin?.to,
-                threadId: directOrigin?.threadId != null && directOrigin.threadId !== ""
-                    ? String(directOrigin.threadId)
-                    : undefined,
-                idempotencyKey: crypto.randomUUID(),
-            },
-            expectFinal: true,
-            timeoutMs: 60_000,
-        });
-        didAnnounce = true;
     }
     catch (err) {
         defaultRuntime.error?.(`Subagent announce failed: ${String(err)}`);