@dreb/coding-agent 2.71.0 → 2.73.0

package/dist/core/tools/subagent.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, realpathSync, statSync, } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { completeSimple } from "@dreb/ai";
@@ -238,6 +238,13 @@ export function handleChildJsonlLine(line, sinks) {
         sinks.onProgress(`${sinks.toolNameRef.current} done`);
     }
 }
+/**
+ * How long a gracefully aborted (RPC `abort`) child may take to finish its run and
+ * emit `agent_end` before it is terminated with SIGTERM.
+ */
+export const SUBAGENT_ABORT_GRACE_MS = 5000;
+/** Delay between SIGTERM and the SIGKILL backstop for a child that is still alive. */
+export const SUBAGENT_SIGKILL_BACKSTOP_MS = 5000;
 async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentProvider, sessionDir, parentSessionFile, onChildEvent, thinkingOverride, onControlAvailable) {
     const drebBin = findDrebBinary();
     log.debug(`[subagent] spawn: agent=${agentConfig.name} cwd=${cwd}`);
@@ -325,6 +332,7 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
         }
         let settled = false;
         let killTimer = null;
+        let abortGraceTimer = null;
         const collectedMessages = [];
         const stderrChunks = [];
         let stderrSize = 0;
@@ -335,6 +343,8 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
         let resolvedThinking;
         let rpcRequestId = 0;
         let rpcCompleted = false;
+        /** Set once a graceful RPC `abort` has been sent for a user stop. */
+        let gracefulAbortRequested = false;
         let controlError;
         const pendingRpc = new Map();
         const sendRpc = (command) => {
@@ -353,16 +363,11 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
                 getState: async () => sendRpc({ type: "get_state" }),
             }
             : undefined;
-        // Terminally fail a controlled child: remember the first failure, reject all
-        // in-flight control requests, and stop the process (with the same SIGKILL
-        // backstop as the abort path) so the close handler settles instead of the
-        // child idling in RPC mode forever.
-        const failControlledChild = (err) => {
-            if (!controlError)
-                controlError = err;
-            for (const request of pendingRpc.values())
-                request.reject(err);
-            pendingRpc.clear();
+        // Escalating termination: SIGTERM now, SIGKILL if the process is still alive
+        // after the backstop delay. Liveness is judged by exitCode/signalCode —
+        // `proc.killed` only reports that a signal was *sent*, so it is already true
+        // after the SIGTERM and cannot gate the SIGKILL escalation.
+        const forceKill = () => {
             try {
                 proc.kill("SIGTERM");
             }
@@ -370,14 +375,41 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
                 /* process already exited */
             }
             killTimer ??= setTimeout(() => {
+                if (proc.exitCode !== null || proc.signalCode !== null)
+                    return;
                 try {
-                    if (!proc.killed)
-                        proc.kill("SIGKILL");
+                    proc.kill("SIGKILL");
                 }
                 catch {
                     /* process already exited */
                 }
-            }, 5000);
+            }, SUBAGENT_SIGKILL_BACKSTOP_MS);
+        };
+        // Terminally fail a controlled child: remember the first failure, reject all
+        // in-flight control requests, and stop the process (with the same SIGKILL
+        // backstop as the abort path) so the close handler settles instead of the
+        // child idling in RPC mode forever.
+        const failControlledChild = (err) => {
+            if (!controlError)
+                controlError = err;
+            for (const request of pendingRpc.values())
+                request.reject(err);
+            pendingRpc.clear();
+            forceKill();
+        };
+        // Ask a controlled child to abort its own run (graceful stop). If the request cannot
+        // be delivered or the child refuses it, terminate the child instead.
+        const requestGracefulAbort = () => {
+            if (!proc.stdin?.writable) {
+                forceKill();
+                return;
+            }
+            sendRpc({ type: "abort" }).catch((err) => {
+                if (settled)
+                    return;
+                log.warn(`[subagent] graceful abort failed (agent=${agentConfig.name}): ${err instanceof Error ? err.message : String(err)}; terminating child`);
+                forceKill();
+            });
         };
         proc.stdin?.on("error", (err) => {
             log.warn(`[subagent] stdin stream error (agent=${agentConfig.name}): ${err.message}`);
@@ -405,7 +437,17 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
                         const message = JSON.parse(line);
                         if (message?.type === "agent_end" && !rpcCompleted) {
                             rpcCompleted = true;
-                            setImmediate(() => proc.kill("SIGTERM"));
+                            setImmediate(forceKill);
+                        }
+                        if (message?.type === "agent_start" && gracefulAbortRequested && !rpcCompleted) {
+                            // The child handles commands concurrently. An abort that arrived while
+                            // its initial prompt was still in its pre-run preamble (API-key
+                            // resolution, input/before-start hooks) was acknowledged without
+                            // aborting anything, because no run existed yet. Abort the run that
+                            // has now started, before it can execute tools the user just stopped.
+                            // Otherwise it would keep working until the grace period expires, and
+                            // SIGTERM would orphan any tool process tree it had started.
+                            requestGracefulAbort();
                         }
                         if (message?.type === "response" && typeof message.id === "string") {
                             const pending = pendingRpc.get(message.id);
@@ -455,23 +497,22 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
                 failControlledChild(error);
             });
         }
-        // Handle abort signal (guard kill() against ESRCH race if process already exited)
+        // Handle abort signal (user stop / stop-all). A controlled child is stopped
+        // gracefully first: the RPC `abort` makes the child abort its own run, so its
+        // tools unwind — notably the bash tool kills its detached process group on its
+        // abort signal, which a bare SIGTERM to this child would orphan. The child's
+        // resulting agent_end triggers the normal SIGTERM above; a run that starts only
+        // after the abort was handled is aborted again on its agent_start. If the abort
+        // cannot be delivered or the child does not finish within the grace period,
+        // escalate to SIGTERM and then the SIGKILL backstop.
         const onAbort = () => {
-            try {
-                proc.kill("SIGTERM");
-            }
-            catch {
-                /* process already exited */
+            if (!controlClient || rpcCompleted || controlError || !proc.stdin?.writable) {
+                forceKill();
+                return;
             }
-            killTimer = setTimeout(() => {
-                try {
-                    if (!proc.killed)
-                        proc.kill("SIGKILL");
-                }
-                catch {
-                    /* process already exited */
-                }
-            }, 5000);
+            gracefulAbortRequested = true;
+            abortGraceTimer ??= setTimeout(forceKill, SUBAGENT_ABORT_GRACE_MS);
+            requestGracefulAbort();
         };
         signal?.addEventListener("abort", onAbort, { once: true });
         proc.on("error", (err) => {
@@ -484,6 +525,8 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
             pendingRpc.clear();
             if (killTimer)
                 clearTimeout(killTimer);
+            if (abortGraceTimer)
+                clearTimeout(abortGraceTimer);
             signal?.removeEventListener("abort", onAbort);
             rejectPromise(new Error(`Subagent process error: ${err.message}`));
         });
@@ -497,6 +540,8 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
             pendingRpc.clear();
             if (killTimer)
                 clearTimeout(killTimer);
+            if (abortGraceTimer)
+                clearTimeout(abortGraceTimer);
             signal?.removeEventListener("abort", onAbort);
             const exitCode = rpcCompleted ? 0 : (code ?? 1);
             const stderr = stderrChunks.join("");
@@ -928,10 +973,6 @@ export function formatModelFallbackSummary(skippedModels, proposalModel, finalMo
         : `using "${finalModel ?? proposalModel ?? "unknown"}".`;
     return `[MODEL FALLBACK: skipped ${skippedModels.length} unavailable model(s); ${routeSummary}]\n${skipped}`;
 }
-export function prependModelFallbackSummary(output, skippedModels, proposalModel, finalModel) {
-    const fallbackSummary = formatModelFallbackSummary(skippedModels, proposalModel, finalModel);
-    return fallbackSummary ? `${fallbackSummary}\n\n${output}` : output;
-}
 function formatSkippedModelFailureDetails(skippedModels) {
     if (skippedModels.length === 0)
         return undefined;
@@ -939,6 +980,13 @@ function formatSkippedModelFailureDetails(skippedModels) {
 }
 const MAX_PARALLEL_TASKS = 8;
 const MAX_TASK_LENGTH = 32_768; // 32 KB — prevent E2BIG from oversized argv
+/** Thrown by {@link SubagentConcurrencyGate.acquire} when its signal aborts before a slot is granted. */
+export class SubagentSlotWaitAbortedError extends Error {
+    constructor() {
+        super("Cancelled while waiting for a subagent concurrency slot.");
+        this.name = "SubagentSlotWaitAbortedError";
+    }
+}
 /**
  * Create a concurrency gate limited to `maxConcurrent` simultaneous holders. The count lives in
  * this closure, so a single gate instance shared across tool rebuilds keeps counting in-flight
@@ -951,16 +999,27 @@ export function createSubagentConcurrencyGate(maxConcurrent) {
     let running = 0;
     const waiters = [];
     return {
-        acquire() {
+        acquire(signal) {
+            if (signal?.aborted)
+                return Promise.reject(new SubagentSlotWaitAbortedError());
             if (running < maxConcurrent) {
                 running++;
                 return Promise.resolve();
             }
-            return new Promise((resolve) => {
-                waiters.push(() => {
+            return new Promise((resolve, reject) => {
+                const grant = () => {
+                    signal?.removeEventListener("abort", onAbort);
                     running++;
                     resolve();
-                });
+                };
+                const onAbort = () => {
+                    const index = waiters.indexOf(grant);
+                    if (index !== -1)
+                        waiters.splice(index, 1);
+                    reject(new SubagentSlotWaitAbortedError());
+                };
+                waiters.push(grant);
+                signal?.addEventListener("abort", onAbort, { once: true });
             });
         },
         release() {
@@ -1272,11 +1331,19 @@ singleModelMode) {
     onProgress?.(`Running ${name} agent${usedModel ? ` (${usedModel})` : ""}...`);
     const result = await spawnSubagent(effectiveConfig, task, cwd, signal, onProgress, resolvedProvider, sessionDir, parentSessionFile, onChildEvent, finalThinking, onControlAvailable);
     const finalSelectedModel = result.model ?? (usedModel ? canonicalModelRef(resolvedProvider, usedModel) : undefined);
-    result.output = prependModelFallbackSummary(result.output, skippedModels, arbitrationEnabled ? proposalSelectedModel : finalSelectedModel, arbitrationEnabled ? finalSelectedModel : undefined);
+    // Spawn-time routing notes are system text, not the child's words: keep them out of
+    // `output` so the parent sees them outside the agent-output block (and so a chain's
+    // `{previous}` carries only the previous agent's output).
+    const notes = [];
     if (warning) {
         const warningContext = arbitrationEnabled ? `Proposal resolution: ${warning}` : warning;
-        result.output = `[WARNING: ${warningContext}]\n\n${result.output}`;
+        notes.push(`[WARNING: ${warningContext}]`);
     }
+    const fallbackSummary = formatModelFallbackSummary(skippedModels, arbitrationEnabled ? proposalSelectedModel : finalSelectedModel, arbitrationEnabled ? finalSelectedModel : undefined);
+    if (fallbackSummary)
+        notes.push(fallbackSummary);
+    if (notes.length > 0)
+        result.notes = notes;
     return result;
 }
 async function executeChain(agents, chain, defaultCwd, signal, onProgress, parentProvider, registry, sessionBaseDir, defaultAgent, defaultModel, defaultThinking, parentModel, getAgentModelsForAgentFn, parentSessionFile, onChildEvent, arbitration, onControlAvailable, 
@@ -1540,6 +1607,11 @@ function findFirstUserMessageSummary(sessionFile) {
     }
     return undefined;
 }
+/**
+ * Infer a finished child's status from the last assistant message in its session log.
+ * `aborted` only occurs when the parent gracefully cancelled the child (user stop), so it
+ * maps to `cancelled`; `error` maps to `failed`.
+ */
 function inferCompletedSessionStatus(sessionFile) {
     const tail = readFileTail(sessionFile, TAIL_READ_BYTES);
     if (!tail)
@@ -1554,10 +1626,88 @@ function inferCompletedSessionStatus(sessionFile) {
         if (entry.message.role !== "assistant")
             continue;
         const stopReason = entry.message.stopReason;
-        return stopReason === "error" || stopReason === "aborted" ? "failed" : "completed";
+        if (stopReason === "aborted")
+            return "cancelled";
+        return stopReason === "error" ? "failed" : "completed";
     }
     return "completed";
 }
+/**
+ * File in a background agent's session directory recording that the user stopped it.
+ * A stop doesn't always leave a trailing `aborted` message in the child's log: a chain
+ * stopped between steps, a child terminated after the grace period, and an agent stopped
+ * while queued or before spawn (which has no log at all). The marker is the authoritative
+ * record that rehydration checks first.
+ */
+export const SUBAGENT_CANCELLED_MARKER_FILE = "cancelled.json";
+/**
+ * Record a user stop in the agent's session directory (created if the agent never
+ * spawned). Agents without a session directory or parent session file can't be
+ * rehydrated, so nothing is written for them. A write failure doesn't block the stop
+ * itself. It is logged as an error, because the agent may show as completed or be
+ * missing after a reload.
+ */
+function writeCancellationMarker(info) {
+    if (!info.sessionDir || !info.parentSessionFile)
+        return;
+    const marker = {
+        type: "subagent_cancelled",
+        version: 1,
+        cancelledAt: new Date().toISOString(),
+        parentSession: info.parentSessionFile,
+        agentType: info.agentType,
+        taskSummary: info.taskSummary,
+        startedAt: new Date(info.startedAt).toISOString(),
+        ...(info.cwd ? { cwd: info.cwd } : {}),
+    };
+    try {
+        mkdirSync(info.sessionDir, { recursive: true });
+        writeFileSync(join(info.sessionDir, SUBAGENT_CANCELLED_MARKER_FILE), `${JSON.stringify(marker)}\n`);
+    }
+    catch (err) {
+        log.error(`[subagent] Failed to record the cancellation of background agent ${info.agentId} in ${info.sessionDir}: ${err instanceof Error ? err.message : String(err)}. After a reload it may show as completed or be missing.`);
+    }
+}
+function isCancellationMarker(value) {
+    return (isRecord(value) &&
+        value.type === "subagent_cancelled" &&
+        typeof value.parentSession === "string" &&
+        typeof value.agentType === "string" &&
+        value.agentType.trim() !== "" &&
+        typeof value.taskSummary === "string" &&
+        typeof value.startedAt === "string" &&
+        Number.isFinite(Date.parse(value.startedAt)) &&
+        (value.cwd === undefined || typeof value.cwd === "string"));
+}
+/**
+ * Read an agent's cancellation marker. Returns `undefined` when there is none, the parsed
+ * marker when valid, and `"malformed"` (after a warning) when the file exists but can't be
+ * used. A malformed marker still proves the stop happened, but can't identify the parent.
+ * Filesystem errors other than absence propagate to the caller's recovery policy.
+ */
+function readCancellationMarker(sessionDir) {
+    const markerPath = join(sessionDir, SUBAGENT_CANCELLED_MARKER_FILE);
+    let raw;
+    try {
+        raw = readFileSync(markerPath, "utf8");
+    }
+    catch (err) {
+        if (isMissingFilesystemError(err))
+            return undefined;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (isCancellationMarker(parsed))
+        return parsed;
+    log.warn(`[subagent] ignoring malformed cancellation marker ${markerPath}; the agent is still reported as cancelled`);
+    return "malformed";
+}
 function parseStartedAt(header, sessionFile) {
     if (typeof header.timestamp === "string") {
         const timestamp = Date.parse(header.timestamp);
@@ -1575,21 +1725,38 @@ function parseStartedAt(header, sessionFile) {
 }
 function hasRegisteredSession(sessionDir, sessionFile) {
     const comparableSessionDir = canonicalExistingPath(sessionDir);
-    const comparableSessionFile = canonicalExistingPath(sessionFile);
+    const comparableSessionFile = sessionFile ? canonicalExistingPath(sessionFile) : undefined;
     for (const agent of backgroundAgentRegistry.values()) {
         if (agent.sessionDir && canonicalExistingPath(agent.sessionDir) === comparableSessionDir)
             return true;
-        if (agent.sessionFile && canonicalExistingPath(agent.sessionFile) === comparableSessionFile)
+        if (comparableSessionFile &&
+            agent.sessionFile &&
+            canonicalExistingPath(agent.sessionFile) === comparableSessionFile) {
             return true;
+        }
     }
     return false;
 }
+/** A registry ID for a rehydrated agent, derived from its session directory name and kept unique. */
+function nextRehydratedAgentId(sessionDirName) {
+    const baseAgentId = `${REHYDRATED_AGENT_ID_PREFIX}${sessionDirName}`;
+    let agentId = baseAgentId;
+    let suffix = 2;
+    while (backgroundAgentRegistry.has(agentId)) {
+        agentId = `${baseAgentId}-${suffix++}`;
+    }
+    return agentId;
+}
 /**
  * Recover completed background subagents after a dashboard/RPC process resumes
  * an existing parent session. Live background-agent state is an in-memory
  * registry, while child sessions are durable JSONL files under the subagent
  * sessions directory.
  *
+ * A user stop's cancellation marker ({@link SUBAGENT_CANCELLED_MARKER_FILE}) takes
+ * precedence over status inferred from the log. An agent stopped before it spawned has
+ * only the marker, and is recovered from it.
+ *
  * The first root is authoritative: absence races and malformed JSON are skipped,
  * while operational filesystem failures throw. Later roots are compatibility
  * stores, so their operational filesystem failures are warned and skipped.
@@ -1640,8 +1807,29 @@ export function rehydrateBackgroundAgentsFromDisk(parentSessionFile, subagentSes
                     continue;
                 seenSessionDirs.add(canonicalSessionDir);
                 const sessionFiles = discoverSessionFiles(sessionDir, entry.name, { throwOnOperationalError: true });
-                if (sessionFiles.length === 0)
+                const cancellationMarker = readCancellationMarker(sessionDir);
+                if (sessionFiles.length === 0) {
+                    // A user stop while the agent was queued or before it spawned leaves no log,
+                    // only the cancellation marker.
+                    if (cancellationMarker === undefined || cancellationMarker === "malformed")
+                        continue;
+                    if (!parentSessionMatches(cancellationMarker.parentSession, parentSessionFile))
+                        continue;
+                    if (hasRegisteredSession(sessionDir))
+                        continue;
+                    const agentId = nextRehydratedAgentId(entry.name);
+                    backgroundAgentRegistry.set(agentId, {
+                        agentId,
+                        agentType: cancellationMarker.agentType,
+                        taskSummary: cancellationMarker.taskSummary,
+                        startedAt: Date.parse(cancellationMarker.startedAt),
+                        status: "cancelled",
+                        sessionDir,
+                        cwd: cancellationMarker.cwd,
+                    });
+                    registered++;
                     continue;
+                }
                 let sessionFile;
                 let header;
                 for (const candidateFile of sessionFiles) {
@@ -1660,12 +1848,7 @@ export function rehydrateBackgroundAgentsFromDisk(parentSessionFile, subagentSes
                 }
                 if (!sessionFile || !header || hasRegisteredSession(sessionDir, sessionFile))
                     continue;
-                const baseAgentId = `${REHYDRATED_AGENT_ID_PREFIX}${entry.name}`;
-                let agentId = baseAgentId;
-                let suffix = 2;
-                while (backgroundAgentRegistry.has(agentId)) {
-                    agentId = `${baseAgentId}-${suffix++}`;
-                }
+                const agentId = nextRehydratedAgentId(entry.name);
                 const statusFile = sessionFiles[sessionFiles.length - 1] ?? sessionFile;
                 const agentType = typeof header.agentType === "string" && header.agentType.trim() ? header.agentType : "agent";
                 const taskSummary = findFirstUserMessageSummary(sessionFile) ?? `${agentType} (${entry.name})`;
@@ -1674,7 +1857,9 @@ export function rehydrateBackgroundAgentsFromDisk(parentSessionFile, subagentSes
                     agentType,
                     taskSummary,
                     startedAt: parseStartedAt(header, sessionFile),
-                    status: inferCompletedSessionStatus(statusFile),
+                    // The marker is authoritative: a stop between chain steps or a terminated child
+                    // doesn't leave a trailing `aborted` message for inference to find.
+                    status: cancellationMarker !== undefined ? "cancelled" : inferCompletedSessionStatus(statusFile),
                     sessionDir,
                     sessionFile,
                     cwd: typeof header.cwd === "string" ? header.cwd : undefined,
@@ -1725,14 +1910,49 @@ export async function getBackgroundAgentPendingSteering(agentId) {
     const [state, pending] = await Promise.all([client.getState(), client.getPendingMessages()]);
     return { steeringMode: state.steeringMode, pending };
 }
-/** Abort all running background agents. */
+/**
+ * Mark one registry entry cancelled, record the stop on disk, and abort its
+ * controller. The status is set before aborting so anything reacting
+ * synchronously to the abort (and the lifecycle, which skips status updates once
+ * its signal is aborted) observes `cancelled` rather than `running`. The
+ * controller's abort listeners perform the graceful child shutdown (RPC abort
+ * first, then SIGTERM/SIGKILL backstops).
+ */
+function cancelBackgroundAgentEntry(agentId, controller) {
+    const entry = backgroundAgentRegistry.get(agentId);
+    if (entry && entry.status === "running") {
+        entry.status = "cancelled";
+        writeCancellationMarker(entry);
+    }
+    backgroundAbortControllers.delete(agentId);
+    backgroundControlClients.delete(agentId);
+    controller.abort();
+}
+/**
+ * Cancel exactly one running background agent (user stop). Siblings, the parent
+ * session, and their control channels are untouched. Works for agents that are
+ * executing, queued for a concurrency slot, or between chain steps; a chain is
+ * stopped as a whole. Completion is reported asynchronously through the normal
+ * background-complete path with `cancelled = true`.
+ *
+ * Throws for unknown agents and agents that are no longer running (completed,
+ * failed, cancelled, or rehydrated from disk) — never a silent no-op.
+ */
+export function abortBackgroundAgent(agentId) {
+    const info = backgroundAgentRegistry.get(agentId);
+    if (!info)
+        throw new Error(`Unknown background agent "${agentId}".`);
+    if (info.status !== "running")
+        throw new Error(`Background agent "${agentId}" is no longer running.`);
+    const controller = backgroundAbortControllers.get(agentId);
+    if (!controller)
+        throw new Error(`Background agent "${agentId}" has no abort controller; it cannot be stopped.`);
+    cancelBackgroundAgentEntry(agentId, controller);
+}
+/** Cancel all running background agents (Esc / parent stop). */
 export function abortBackgroundAgents() {
-    for (const [id, controller] of backgroundAbortControllers) {
-        controller.abort();
-        const entry = backgroundAgentRegistry.get(id);
-        if (entry && entry.status === "running") {
-            entry.status = "failed";
-        }
+    for (const [id, controller] of [...backgroundAbortControllers]) {
+        cancelBackgroundAgentEntry(id, controller);
     }
     backgroundAbortControllers.clear();
     backgroundControlClients.clear();
@@ -1860,7 +2080,22 @@ function formatSubagentResult(result, options, theme, showImages) {
     }
     return text;
 }
-export function formatSingleResult(result) {
+/**
+ * Wrap a subagent's own output in labelled delimiter lines so it can't be mistaken for
+ * the system lines around it (execution metadata, cancellation/error notes, session log,
+ * still-running list). `partial` marks output from a run that did not finish cleanly
+ * (cancelled, failed, or truncated). Blank lines around the delimiters keep them as
+ * separate paragraphs when the text is rendered as Markdown (dashboard, Telegram).
+ */
+export function formatAgentOutputBlock(output, partial) {
+    return `--- agent output${partial ? " (partial)" : ""} ---\n\n${output}\n\n--- end of agent output ---`;
+}
+/**
+ * Render one subagent result (used for each chain step). The agent's output is wrapped by
+ * `formatAgentOutputBlock`; `cancelled` marks a step that was stopped by the user, whose
+ * output is therefore partial.
+ */
+export function formatSingleResult(result, cancelled = false) {
     const metadata = [
         result.model ? `model: ${result.model}` : undefined,
         result.thinking ? `thinking: ${result.thinking}` : undefined,
@@ -1878,8 +2113,12 @@ export function formatSingleResult(result) {
         // Clean exit but an error was surfaced (e.g. truncation at the token limit).
         text += `**Error**: ${result.errorMessage}\n`;
     }
+    if (result.notes && result.notes.length > 0) {
+        text += `\n${result.notes.join("\n\n")}\n`;
+    }
     if (result.output) {
-        text += `\n${result.output}`;
+        const partial = cancelled || result.exitCode !== 0 || !!result.errorMessage;
+        text += `\n${formatAgentOutputBlock(result.output, partial)}`;
     }
     else if (result.exitCode === 0 && !result.errorMessage) {
         text += "\n(No output)";
@@ -1914,7 +2153,7 @@ export function createSubagentToolDefinition(cwd, options) {
     // supplied (external SDK callers, tests) the tool owns a fresh per-instance gate, which
     // still keeps separately embedded sessions from coupling through module-global state.
     const concurrencyGate = options?.concurrencyGate ?? createSubagentConcurrencyGate(maxConcurrentSubagents);
-    const acquireBackgroundSlot = () => concurrencyGate.acquire();
+    const acquireBackgroundSlot = (signal) => concurrencyGate.acquire(signal);
     const releaseBackgroundSlot = () => concurrencyGate.release();
     // Discover agents at definition time to build the prompt guidelines.
     // This is cheap (reads .md files) and the same call happens on every execute().
@@ -2010,6 +2249,7 @@ export function createSubagentToolDefinition(cwd, options) {
                         status: "running",
                         sessionDir,
                         cwd: agentCwd,
+                        parentSessionFile: getParentSessionFile(),
                     });
                     backgroundAbortControllers.set(agentId, bgAbort);
                     onBackgroundStart?.(agentId, agentName, taskSummary, sessionDir);
@@ -2051,8 +2291,12 @@ export function createSubagentToolDefinition(cwd, options) {
                         }
                     };
                     const run = async () => {
-                        await acquireBackgroundSlot();
+                        // A stop while queued for a slot settles immediately (the gate rejects
+                        // without taking a slot), so only release a slot this run acquired.
+                        let slotAcquired = false;
                         try {
+                            await acquireBackgroundSlot(bgSignal);
+                            slotAcquired = true;
                             const result = await runFn(bgSignal, onChildEvent, onArbitrationRecord, onControlAvailable);
                             const entry = backgroundAgentRegistry.get(agentId);
                             if (entry && !bgSignal.aborted)
@@ -2078,7 +2322,8 @@ export function createSubagentToolDefinition(cwd, options) {
                         }
                         finally {
                             backgroundControlClients.delete(agentId);
-                            releaseBackgroundSlot();
+                            if (slotAcquired)
+                                releaseBackgroundSlot();
                         }
                     };
                     run().catch((err) => {
@@ -2191,8 +2436,11 @@ export function createSubagentToolDefinition(cwd, options) {
                                 getAgentModelsForAgent,
                             }
                             : undefined, onControlAvailable, getParentSessionId(), getSingleModelMode);
+                        // A user stop ends the chain at its current (last) step, so only that step's
+                        // output can be cut short.
+                        const stoppedAtLastStep = signal.aborted;
                         const resultText = results
-                            .map((r, i) => `### Step ${i + 1}\n${formatSingleResult(r)}`)
+                            .map((r, i) => `### Step ${i + 1}\n${formatSingleResult(r, stoppedAtLastStep && i === results.length - 1)}`)
                             .join("\n\n---\n\n");
                         const failed = results.filter((r) => r.exitCode !== 0);
                         // Per-step session logs are already embedded in resultText via formatSingleResult