@dreb/coding-agent 2.34.3 → 2.35.0

package/dist/core/tools/subagent.js

@@ -1,8 +1,8 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { completeSimple } from "@dreb/ai";
 import { Text } from "@dreb/tui";
 import { Type } from "@sinclair/typebox";
@@ -143,7 +143,53 @@ export function filterSubagentTools(tools) {
 function findDrebBinary() {
     return DREB_SCRIPT;
 }
-async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentProvider, sessionDir, parentSessionFile) {
+/**
+ * Handle one line of a subagent child's JSONL stdout. Parses the line and
+ * dispatches to the sinks: full-event relay, assistant-message collection,
+ * tool progress, resolved model, and non-JSON passthrough.
+ */
+export function handleChildJsonlLine(line, sinks) {
+    if (!line.trim())
+        return;
+    // Separate JSON.parse from event handling so only parse failures
+    // are caught as non-JSON lines — errors in handling propagate normally
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        // Capture non-JSON lines — on failure these often contain the real error
+        // (e.g. startup errors printed before JSONL mode begins)
+        sinks.onPlainLine(line.trim());
+        if (line.trim().startsWith("{")) {
+            log.warn(`[subagent] Failed to parse JSONL event: ${line.slice(0, 200)}`);
+        }
+        return;
+    }
+    if (event === null || typeof event !== "object") {
+        // Valid JSON but not an event object (e.g. a bare string or number) — treat
+        // like a plain line so diagnostic content is preserved.
+        sinks.onPlainLine(line.trim());
+        return;
+    }
+    if (typeof event.type === "string") {
+        sinks.onEvent?.(event);
+    }
+    if (event.type === "agent_start" && event.model) {
+        sinks.onModel(event.model.id);
+    }
+    if (event.type === "message_end" && event.message?.role === "assistant") {
+        sinks.onAssistantMessage(event.message);
+    }
+    if (event.type === "tool_execution_start" && sinks.onProgress) {
+        sinks.toolNameRef.current = event.toolName || "";
+        sinks.onProgress(`Using ${sinks.toolNameRef.current}...`);
+    }
+    if (event.type === "tool_execution_end" && sinks.onProgress) {
+        sinks.onProgress(`${sinks.toolNameRef.current} done`);
+    }
+}
+async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentProvider, sessionDir, parentSessionFile, onChildEvent) {
     const drebBin = findDrebBinary();
     log.debug(`[subagent] spawn: agent=${agentConfig.name} cwd=${cwd}`);
     // Validate cwd exists — spawn() throws a misleading ENOENT blaming the
@@ -224,7 +270,7 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
         let stderrSize = 0;
         const MAX_STDERR_BYTES = 8192;
         const plainStdoutLines = [];
-        let lastToolName = "";
+        const toolNameRef = { current: "" };
         let resolvedModel;
         // Drain stderr concurrently to avoid pipe deadlock (capped to prevent OOM from verbose subagents)
         proc.stderr?.on("data", (chunk) => {
@@ -243,36 +289,16 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
                 log.warn(`[subagent] stdout stream error (agent=${agentConfig.name}): ${err.message}`);
             });
             attachJsonlLineReader(proc.stdout, (line) => {
-                if (!line.trim())
-                    return;
-                // Separate JSON.parse from event handling so only parse failures
-                // are caught as non-JSON lines — errors in handling propagate normally
-                let event;
-                try {
-                    event = JSON.parse(line);
-                }
-                catch {
-                    // Capture non-JSON lines — on failure these often contain the real error
-                    // (e.g. startup errors printed before JSONL mode begins)
-                    plainStdoutLines.push(line.trim());
-                    if (line.trim().startsWith("{")) {
-                        log.warn(`[subagent] Failed to parse JSONL event: ${line.slice(0, 200)}`);
-                    }
-                    return;
-                }
-                if (event.type === "agent_start" && event.model) {
-                    resolvedModel = event.model.id;
-                }
-                if (event.type === "message_end" && event.message?.role === "assistant") {
-                    collectedMessages.push(event.message);
-                }
-                if (event.type === "tool_execution_start" && onProgress) {
-                    lastToolName = event.toolName || "";
-                    onProgress(`Using ${lastToolName}...`);
-                }
-                if (event.type === "tool_execution_end" && onProgress) {
-                    onProgress(`${lastToolName} done`);
-                }
+                handleChildJsonlLine(line, {
+                    onEvent: onChildEvent,
+                    onAssistantMessage: (message) => collectedMessages.push(message),
+                    onProgress,
+                    onModel: (modelId) => {
+                        resolvedModel = modelId;
+                    },
+                    onPlainLine: (plain) => plainStdoutLines.push(plain),
+                    toolNameRef,
+                });
             });
         }
         // Handle abort signal (guard kill() against ESRCH race if process already exited)
@@ -382,44 +408,108 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
         });
     });
 }
-// ---------------------------------------------------------------------------
-// Session file discovery and cleanup
-// ---------------------------------------------------------------------------
+const STEP_SESSION_DIR_RE = /^step-(\d+)$/;
+function findNewestJsonlFileInDir(dir) {
+    let best;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.name.endsWith(".jsonl"))
+            continue;
+        if (entry.isDirectory())
+            continue;
+        const fullPath = join(dir, entry.name);
+        try {
+            const mtime = statSync(fullPath).mtime.getTime();
+            if (!best || mtime > best.mtime)
+                best = { path: fullPath, mtime };
+        }
+        catch (err) {
+            if (isExpectedFilesystemError(err))
+                continue;
+            throw err;
+        }
+    }
+    return best;
+}
+function discoverStepSessionFileCandidates(sessionDir) {
+    const steps = [];
+    for (const entry of readdirSync(sessionDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const match = STEP_SESSION_DIR_RE.exec(entry.name);
+        if (!match)
+            continue;
+        steps.push({ name: entry.name, index: Number(match[1]) });
+    }
+    steps.sort((a, b) => a.index - b.index || a.name.localeCompare(b.name));
+    const files = [];
+    for (const step of steps) {
+        try {
+            const candidate = findNewestJsonlFileInDir(join(sessionDir, step.name));
+            if (candidate)
+                files.push(candidate);
+        }
+        catch (err) {
+            if (isExpectedFilesystemError(err))
+                continue;
+            throw err;
+        }
+    }
+    return files;
+}
 /**
- * Find the most recently modified .jsonl file in a session directory.
- * Returns the full path, or undefined if no session file was written
- * (e.g., subagent was killed before the first assistant message).
+ * Find session JSONL files for a subagent session directory.
+ *
+ * Normal subagents write one .jsonl directly under sessionDir, so this returns
+ * the most recently modified flat file. Chain-mode subagents register the chain
+ * root as sessionDir but write each step under step-N/, so when no flat file is
+ * present this recurses one level into step-* directories and returns one file
+ * per step in numeric step order.
  */
-export function discoverSessionFile(sessionDir, agentName) {
+export function discoverSessionFiles(sessionDir, agentName) {
     try {
         if (!existsSync(sessionDir))
-            return undefined;
-        const files = readdirSync(sessionDir).filter((f) => f.endsWith(".jsonl"));
-        if (files.length === 0)
-            return undefined;
-        // Pick the most recently modified file (typically there's only one per subagent dir)
-        let best;
-        for (const f of files) {
-            try {
-                const fullPath = join(sessionDir, f);
-                const mtime = statSync(fullPath).mtime.getTime();
-                if (!best || mtime > best.mtime) {
-                    best = { path: fullPath, mtime };
-                }
-            }
-            catch {
-                // File disappeared or is a bad symlink — skip it, keep any valid candidate
-            }
+            return [];
+        const flatFile = findNewestJsonlFileInDir(sessionDir);
+        if (flatFile) {
+            log.debug(`[subagent] session file: ${flatFile.path} (agent=${agentName})`);
+            return [flatFile.path];
         }
-        if (best) {
-            log.debug(`[subagent] session file: ${best.path} (agent=${agentName})`);
-            return best.path;
+        const stepFiles = discoverStepSessionFileCandidates(sessionDir);
+        if (stepFiles.length > 0) {
+            log.debug(`[subagent] chain session files: ${stepFiles.map((file) => file.path).join(", ")} (agent=${agentName})`);
+            return stepFiles.map((file) => file.path);
         }
     }
     catch (err) {
+        if (!isExpectedFilesystemError(err))
+            throw err;
         log.warn(`[subagent] failed to discover session file (agent=${agentName}): ${err instanceof Error ? err.message : String(err)}`);
     }
-    return undefined;
+    return [];
+}
+/**
+ * Find the most recently modified .jsonl file in a session directory.
+ * Returns the full path, or undefined if no session file was written
+ * (e.g., subagent was killed before the first assistant message).
+ */
+export function discoverSessionFile(sessionDir, agentName) {
+    const files = discoverSessionFiles(sessionDir, agentName);
+    if (files.length <= 1)
+        return files[0];
+    let best;
+    for (const file of files) {
+        try {
+            const candidate = { path: file, mtime: statSync(file).mtime.getTime() };
+            if (!best || candidate.mtime > best.mtime)
+                best = candidate;
+        }
+        catch (err) {
+            if (isExpectedFilesystemError(err))
+                continue;
+            throw err;
+        }
+    }
+    return best?.path;
 }
 // ---------------------------------------------------------------------------
 // Execution modes
@@ -714,7 +804,7 @@ function clampCwd(defaultCwd, itemCwd) {
     }
     return { ok: true, cwd: resolved };
 }
-export async function executeSingle(agents, agentName, task, cwd, signal, onProgress, modelOverride, parentProvider, registry, sessionDir, parentModel, agentModels, parentSessionFile) {
+export async function executeSingle(agents, agentName, task, cwd, signal, onProgress, modelOverride, parentProvider, registry, sessionDir, parentModel, agentModels, parentSessionFile, onChildEvent) {
     const name = agentName || DEFAULT_AGENT;
     const config = agents.get(name);
     if (!config) {
@@ -773,14 +863,14 @@ export async function executeSingle(agents, agentName, task, cwd, signal, onProg
     }
     const usedModel = effectiveConfig.model?.toString();
     onProgress?.(`Running ${name} agent${usedModel ? ` (${usedModel})` : ""}...`);
-    const result = await spawnSubagent(effectiveConfig, task, cwd, signal, onProgress, resolvedProvider, sessionDir, parentSessionFile);
+    const result = await spawnSubagent(effectiveConfig, task, cwd, signal, onProgress, resolvedProvider, sessionDir, parentSessionFile, onChildEvent);
     result.output = prependModelFallbackSummary(result.output, skippedModels, result.model ?? usedModel);
     if (warning) {
         result.output = `[WARNING: ${warning}]\n\n${result.output}`;
     }
     return result;
 }
-async function executeChain(agents, chain, defaultCwd, signal, onProgress, parentProvider, registry, sessionBaseDir, defaultAgent, defaultModel, parentModel, getAgentModelsForAgentFn, parentSessionFile) {
+async function executeChain(agents, chain, defaultCwd, signal, onProgress, parentProvider, registry, sessionBaseDir, defaultAgent, defaultModel, parentModel, getAgentModelsForAgentFn, parentSessionFile, onChildEvent) {
     const results = [];
     let previousOutput = "";
     for (let i = 0; i < chain.length; i++) {
@@ -817,7 +907,7 @@ async function executeChain(agents, chain, defaultCwd, signal, onProgress, paren
         const stepSessionDir = sessionBaseDir ? join(sessionBaseDir, `step-${i + 1}`) : undefined;
         const stepAgentName = step.agent || defaultAgent || DEFAULT_AGENT;
         const stepMach6Models = getAgentModelsForAgentFn?.(stepAgentName);
-        const result = await executeSingle(agents, step.agent || defaultAgent, task, cwdResult.cwd, signal, onProgress, step.model || defaultModel, parentProvider, registry, stepSessionDir, parentModel, stepMach6Models, parentSessionFile);
+        const result = await executeSingle(agents, step.agent || defaultAgent, task, cwdResult.cwd, signal, onProgress, step.model || defaultModel, parentProvider, registry, stepSessionDir, parentModel, stepMach6Models, parentSessionFile, onChildEvent);
         results.push(result);
         if (result.exitCode !== 0) {
             break; // stop chain on error
@@ -834,6 +924,283 @@ function generateAgentId() {
 }
 const backgroundAgentRegistry = new Map();
 const backgroundAbortControllers = new Map();
+const REHYDRATED_AGENT_ID_PREFIX = "rehydrated-";
+const HEADER_READ_CHUNK_BYTES = 8192;
+const MAX_HEADER_READ_BYTES = 256 * 1024;
+const METADATA_READ_BYTES = 256 * 1024;
+const TAIL_READ_BYTES = 64 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isExpectedFilesystemError(err) {
+    return typeof err?.code === "string";
+}
+function parseJsonlLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return undefined;
+        throw err;
+    }
+}
+function readFirstNonEmptyLine(filePath) {
+    let fd;
+    try {
+        fd = openSync(filePath, "r");
+        const chunk = Buffer.alloc(HEADER_READ_CHUNK_BYTES);
+        let buffered = "";
+        let bytesReadTotal = 0;
+        while (bytesReadTotal < MAX_HEADER_READ_BYTES) {
+            const bytesRead = readSync(fd, chunk, 0, Math.min(chunk.length, MAX_HEADER_READ_BYTES - bytesReadTotal), null);
+            if (bytesRead === 0)
+                break;
+            bytesReadTotal += bytesRead;
+            buffered += chunk.toString("utf8", 0, bytesRead);
+            const lines = buffered.split(/\r?\n/);
+            const completeLines = buffered.endsWith("\n") || buffered.endsWith("\r") ? lines : lines.slice(0, -1);
+            for (const line of completeLines) {
+                if (line.trim())
+                    return line;
+            }
+            buffered = lines.at(-1) ?? "";
+        }
+        return buffered.trim() ? buffered : undefined;
+    }
+    catch (err) {
+        if (isExpectedFilesystemError(err))
+            return undefined;
+        throw err;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Best-effort observability: close errors are filesystem cleanup noise.
+            }
+        }
+    }
+}
+function readFileSlice(filePath, start, length) {
+    let fd;
+    try {
+        fd = openSync(filePath, "r");
+        const buffer = Buffer.alloc(length);
+        const bytesRead = readSync(fd, buffer, 0, length, start);
+        return buffer.toString("utf8", 0, bytesRead);
+    }
+    catch (err) {
+        if (isExpectedFilesystemError(err))
+            return undefined;
+        throw err;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Best-effort observability: close errors are filesystem cleanup noise.
+            }
+        }
+    }
+}
+function readFileStart(filePath, maxBytes) {
+    let size = maxBytes;
+    try {
+        size = Math.min(statSync(filePath).size, maxBytes);
+    }
+    catch (err) {
+        if (isExpectedFilesystemError(err))
+            return undefined;
+        throw err;
+    }
+    return readFileSlice(filePath, 0, size);
+}
+function readFileTail(filePath, maxBytes) {
+    let start = 0;
+    let length = maxBytes;
+    try {
+        const size = statSync(filePath).size;
+        start = Math.max(0, size - maxBytes);
+        length = size - start;
+    }
+    catch (err) {
+        if (isExpectedFilesystemError(err))
+            return undefined;
+        throw err;
+    }
+    return readFileSlice(filePath, start, length);
+}
+function parseSessionHeader(sessionFile) {
+    const headerLine = readFirstNonEmptyLine(sessionFile);
+    if (!headerLine)
+        return undefined;
+    return parseJsonlLine(headerLine);
+}
+function comparablePath(pathValue) {
+    const resolved = resolve(pathValue);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function parentSessionMatches(recordedParentSession, parentSessionFile) {
+    if (recordedParentSession === parentSessionFile)
+        return true;
+    if (comparablePath(recordedParentSession) === comparablePath(parentSessionFile))
+        return true;
+    // Older/foreign invocations may disagree about absolute vs relative roots, but
+    // dreb session filenames include a timestamp and UUID. A basename match is a
+    // safe final fallback for recovering observability across process boundaries.
+    return basename(recordedParentSession) === basename(parentSessionFile);
+}
+function extractTextFromContent(content) {
+    if (typeof content === "string")
+        return content.trim() || undefined;
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const item of content) {
+        if (!isRecord(item))
+            continue;
+        if (item.type === "text" && typeof item.text === "string" && item.text.trim()) {
+            parts.push(item.text.trim());
+        }
+    }
+    const text = parts.join("\n").trim();
+    return text || undefined;
+}
+function truncateTaskSummary(text) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    return normalized.length > 120 ? `${normalized.slice(0, 117)}...` : normalized;
+}
+function findFirstUserMessageSummary(sessionFile) {
+    const head = readFileStart(sessionFile, METADATA_READ_BYTES);
+    if (!head)
+        return undefined;
+    for (const line of head.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        const entry = parseJsonlLine(line);
+        if (entry?.type !== "message" || !isRecord(entry.message))
+            continue;
+        if (entry.message.role !== "user")
+            continue;
+        const text = extractTextFromContent(entry.message.content);
+        if (text)
+            return truncateTaskSummary(text);
+    }
+    return undefined;
+}
+function inferCompletedSessionStatus(sessionFile) {
+    const tail = readFileTail(sessionFile, TAIL_READ_BYTES);
+    if (!tail)
+        return "completed";
+    const lines = tail.split(/\r?\n/).reverse();
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        const entry = parseJsonlLine(line);
+        if (entry?.type !== "message" || !isRecord(entry.message))
+            continue;
+        if (entry.message.role !== "assistant")
+            continue;
+        const stopReason = entry.message.stopReason;
+        return stopReason === "error" || stopReason === "aborted" ? "failed" : "completed";
+    }
+    return "completed";
+}
+function parseStartedAt(header, sessionFile) {
+    if (typeof header.timestamp === "string") {
+        const timestamp = Date.parse(header.timestamp);
+        if (Number.isFinite(timestamp))
+            return timestamp;
+    }
+    try {
+        return statSync(sessionFile).mtime.getTime();
+    }
+    catch (err) {
+        if (isExpectedFilesystemError(err))
+            return Date.now();
+        throw err;
+    }
+}
+function hasRegisteredSession(sessionDir, sessionFile) {
+    const comparableSessionDir = comparablePath(sessionDir);
+    const comparableSessionFile = comparablePath(sessionFile);
+    for (const agent of backgroundAgentRegistry.values()) {
+        if (agent.sessionDir && comparablePath(agent.sessionDir) === comparableSessionDir)
+            return true;
+        if (agent.sessionFile && comparablePath(agent.sessionFile) === comparableSessionFile)
+            return true;
+    }
+    return false;
+}
+/**
+ * Best-effort recovery for 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.
+ *
+ * Returns the number of newly registered agents. Expected filesystem and JSONL
+ * parse failures are skipped; unexpected programming errors are allowed to throw.
+ */
+export function rehydrateBackgroundAgentsFromDisk(parentSessionFile, subagentSessionsBase = getSubagentSessionsDir()) {
+    if (!parentSessionFile)
+        return 0;
+    let entries;
+    try {
+        entries = readdirSync(subagentSessionsBase, { withFileTypes: true });
+    }
+    catch (err) {
+        if (isExpectedFilesystemError(err))
+            return 0;
+        throw err;
+    }
+    let registered = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const sessionDir = join(subagentSessionsBase, entry.name);
+        const sessionFiles = discoverSessionFiles(sessionDir, entry.name);
+        if (sessionFiles.length === 0)
+            continue;
+        let sessionFile;
+        let header;
+        for (const candidateFile of sessionFiles) {
+            const candidateHeader = parseSessionHeader(candidateFile);
+            if (candidateHeader?.type !== "session" || typeof candidateHeader.parentSession !== "string")
+                continue;
+            if (!parentSessionMatches(candidateHeader.parentSession, parentSessionFile))
+                continue;
+            sessionFile = candidateFile;
+            header = candidateHeader;
+            break;
+        }
+        if (!sessionFile || !header)
+            continue;
+        const agentId = `${REHYDRATED_AGENT_ID_PREFIX}${entry.name}`;
+        if (backgroundAgentRegistry.has(agentId) || hasRegisteredSession(sessionDir, sessionFile))
+            continue;
+        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})`;
+        backgroundAgentRegistry.set(agentId, {
+            agentId,
+            agentType,
+            taskSummary,
+            startedAt: parseStartedAt(header, sessionFile),
+            status: inferCompletedSessionStatus(statusFile),
+            sessionDir,
+            sessionFile,
+            cwd: typeof header.cwd === "string" ? header.cwd : undefined,
+        });
+        registered++;
+    }
+    return registered;
+}
 /** Get a snapshot of all tracked background agents (running and recently completed). Returns readonly clones. */
 export function getBackgroundAgents() {
     return [...backgroundAgentRegistry.values()].map((a) => ({ ...a }));
@@ -980,6 +1347,7 @@ export function formatSingleResult(result) {
 export function createSubagentToolDefinition(cwd, options) {
     const onBackgroundStart = options?.onBackgroundStart;
     const onBackgroundComplete = options?.onBackgroundComplete;
+    const onBackgroundEvent = options?.onBackgroundEvent;
     const getParentProvider = options?.parentProvider ?? (() => undefined);
     const getParentModel = options?.parentModel ?? (() => undefined);
     const getParentSessionFile = options?.parentSessionFile ?? (() => undefined);
@@ -1058,9 +1426,11 @@ export function createSubagentToolDefinition(cwd, options) {
                  * Shared lifecycle for all background launches: generates agent ID,
                  * sets up registry/abort/notification, gates on the concurrency
                  * semaphore, and handles errors. The caller provides the actual
-                 * work via `runFn(signal)` which must return a SubagentResult.
+                 * work via `runFn(signal, onChildEvent)` which must return a
+                 * SubagentResult; `onChildEvent` (when defined) must be forwarded to
+                 * the spawn so the child's JSONL events reach the relay.
                  */
-                const launchBackgroundLifecycle = (agentName, taskSummary, runFn) => {
+                const launchBackgroundLifecycle = (agentName, taskSummary, sessionDir, agentCwd, runFn) => {
                     const agentId = generateAgentId();
                     const bgAbort = new AbortController();
                     backgroundAgentRegistry.set(agentId, {
@@ -1069,9 +1439,23 @@ export function createSubagentToolDefinition(cwd, options) {
                         taskSummary,
                         startedAt: Date.now(),
                         status: "running",
+                        sessionDir,
+                        cwd: agentCwd,
                     });
                     backgroundAbortControllers.set(agentId, bgAbort);
-                    onBackgroundStart?.(agentId, agentName, taskSummary);
+                    onBackgroundStart?.(agentId, agentName, taskSummary, sessionDir);
+                    // Relay child JSONL events tagged with this agent's ID. Guarded so a
+                    // throwing relay listener can never kill the stdout reader.
+                    const onChildEvent = onBackgroundEvent
+                        ? (event) => {
+                            try {
+                                onBackgroundEvent(agentId, event);
+                            }
+                            catch (err) {
+                                log.warn(`[subagent] onBackgroundEvent threw for agent ${agentId}: ${err instanceof Error ? err.message : String(err)}`);
+                            }
+                        }
+                        : undefined;
                     const bgSignal = bgAbort.signal;
                     const safeNotify = (result) => {
                         try {
@@ -1084,10 +1468,12 @@ export function createSubagentToolDefinition(cwd, options) {
                     const run = async () => {
                         await bgAcquire();
                         try {
-                            const result = await runFn(bgSignal);
+                            const result = await runFn(bgSignal, onChildEvent);
                             const entry = backgroundAgentRegistry.get(agentId);
                             if (entry && !bgSignal.aborted)
                                 entry.status = result.exitCode === 0 ? "completed" : "failed";
+                            if (entry && result.sessionFile)
+                                entry.sessionFile = result.sessionFile;
                             backgroundAbortControllers.delete(agentId);
                             safeNotify(result);
                         }
@@ -1139,7 +1525,7 @@ export function createSubagentToolDefinition(cwd, options) {
                     const sessionId = generateAgentId();
                     const sessionDir = join(subagentSessionsBase, sessionId);
                     const agentModels = getAgentModelsForAgent?.(agentName || DEFAULT_AGENT);
-                    return launchBackgroundLifecycle(agentName, taskLabel, (signal) => executeSingle(agents, agentName === DEFAULT_AGENT ? undefined : agentName, task, resolvedCwd, signal, undefined, modelOverride, getParentProvider(), modelRegistry, sessionDir, getParentModel(), agentModels, getParentSessionFile()));
+                    return launchBackgroundLifecycle(agentName, taskLabel, sessionDir, resolvedCwd, (signal, onChildEvent) => executeSingle(agents, agentName === DEFAULT_AGENT ? undefined : agentName, task, resolvedCwd, signal, undefined, modelOverride, getParentProvider(), modelRegistry, sessionDir, getParentModel(), agentModels, getParentSessionFile(), onChildEvent));
                 };
                 if (params.task) {
                     // Single background task
@@ -1204,8 +1590,8 @@ export function createSubagentToolDefinition(cwd, options) {
                     const taskSummary = `${params.chain.length}-step chain`;
                     const chainSteps = params.chain;
                     const chainSessionDir = join(subagentSessionsBase, `chain-${generateAgentId()}`);
-                    const agentId = launchBackgroundLifecycle(agentName, taskSummary, async (signal) => {
-                        const results = await executeChain(agents, chainSteps, cwd, signal, undefined, getParentProvider(), modelRegistry, chainSessionDir, params.agent, params.model, getParentModel(), getAgentModelsForAgent, getParentSessionFile());
+                    const agentId = launchBackgroundLifecycle(agentName, taskSummary, chainSessionDir, cwd, async (signal, onChildEvent) => {
+                        const results = await executeChain(agents, chainSteps, cwd, signal, undefined, getParentProvider(), modelRegistry, chainSessionDir, params.agent, params.model, getParentModel(), getAgentModelsForAgent, getParentSessionFile(), onChildEvent);
                         const resultText = results
                             .map((r, i) => `### Step ${i + 1}\n${formatSingleResult(r)}`)
                             .join("\n\n---\n\n");