@agentex/agent 0.0.36 → 0.0.37

package/dist/providers/claude/session.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { GoalController, latestGoalFromEvents, isTerminalGoalStatus } from "../../goals/index.js";
 import { claudeGoalCapability } from "./goal-capability.js";
 import { claudeSessionCodec } from "./codec.js";
+import { backgroundTaskEventFromClaude } from "./parse.js";
 import { createSessionRecord } from "../../sessions/record.js";
 import { claudeTranscriptOps } from "./transcript.js";
 import { findBinary } from "../../utils/binary.js";
@@ -204,6 +205,14 @@ export async function createClaudeSession(ctx) {
  * heavy session module (spec §5.1).
  */
 export { claudeGoalCapability } from "./goal-capability.js";
+/** Provider tag stamped on every event this session emits. */
+const CLAUDE_PROVIDER_TYPE = "claude";
+/**
+ * `command_lifecycle` states that retire a host message. `completed` follows a
+ * `result`; the rest do not produce one at all, which is why they have to
+ * close a turn themselves.
+ */
+const TERMINAL_COMMAND_STATES = new Set(["completed", "cancelled", "discarded", "refused"]);
 export class ClaudeSessionImpl {
     proc;
     ctx;
@@ -211,6 +220,79 @@ export class ClaudeSessionImpl {
     mcpConfigPath;
     _state = "idle";
     _sessionId = null;
+    /**
+     * The open root turn, or null.
+     *
+     * `commandUuids` is a set because the CLI coalesces: a second host message
+     * dequeued while a turn is running joins that turn rather than starting its
+     * own. Modelling one uuid per turn left every coalesced message unsettled.
+     *
+     * An empty set means the provider opened this turn itself.
+     */
+    _openTurn = null;
+    /** Monotonic turn counter, so `turn_start`/`turn_end` can be paired by id. */
+    _turnSeq = 0;
+    /**
+     * Host messages the CLI has acknowledged and not yet claimed by a turn,
+     * keyed by the uuid `send()` generated.
+     *
+     * The CLI echoes that uuid back on every `command_lifecycle` record, so a
+     * turn opened by a `started` naming one of these *is* that message's turn —
+     * exact, not inferred. Entries leave only two ways: claimed by a turn, or
+     * retired by a terminal lifecycle record.
+     */
+    _outstandingCommands = new Set();
+    /** Background tasks currently live, by id, with the type they started as. */
+    _activeTasks = new Map();
+    /**
+     * Task ids whose results were delivered while no turn was open, and whose
+     * resume turn has not arrived yet.
+     *
+     * A set rather than a flag: two subagents finishing together deliver twice,
+     * and one bit could not represent that. Used only to hold `drain()` across
+     * the 24-71ms gap between a delivery and the turn it triggers — the task is
+     * no longer live by then, so nothing else covers it. Cleared when a turn
+     * opens or closes, so a delivery the CLI folds into a running turn cannot
+     * pin the session.
+     */
+    _pendingDeliveries = new Set();
+    /**
+     * Settlement batches captured but not yet resolved, one array per turn.
+     *
+     * Isolated so no turn can drain another's — that sharing is what made two
+     * back-to-back results resolve both sends with the first result — but still
+     * reachable, so a process exit mid-drain can reject them instead of
+     * stranding the caller forever.
+     */
+    _settlingBatches = new Set();
+    /**
+     * Whether this CLI build has ever emitted `command_lifecycle`. Learned once:
+     * builds that emit it do so for every host message, so after the first
+     * sighting an unnamed turn is genuinely provider-initiated and the
+     * oldest-unclaimed fallback must not fire.
+     */
+    _seenCommandLifecycle = false;
+    /**
+     * Whether this stream has produced a `result` yet. `system/init` is session
+     * metadata at boot but heads every provider-initiated resume turn, and this
+     * is what tells the two apart.
+     */
+    _seenResult = false;
+    /**
+     * Task type and description as first reported on `task_started`, keyed by
+     * task id. Later lifecycle records are sparse — `task_updated` is a bare
+     * patch and `task_notification` carries no type — so without this a
+     * finished subagent normalizes to `taskType: "unknown"` and hosts render
+     * "Background task completed" for what is plainly a subagent.
+     */
+    _taskFacts = new Map();
+    /**
+     * Cap on `_taskFacts`. Entries cannot be dropped on task completion, because
+     * a completion arrives as two records and the second still needs enriching,
+     * so the map is bounded by eviction instead. A session that ran this many
+     * background tasks will not miss the oldest one's label.
+     */
+    static TASK_FACT_LIMIT = 512;
     _lineBuffer = "";
     _stderrBuffer = "";
     // Pending result-resolvers. With concurrent send, multiple in-flight send()
@@ -316,9 +398,162 @@ export class ClaudeSessionImpl {
             }
         });
     }
-    /** Reject every pending send() Promise and outgoing control_response. */
-    rejectAllPending(err) {
+    /**
+     * Open a root turn and announce it. Returns the turn that was opened.
+     *
+     * `commandUuids` starts with the message that opened it, if any; a coalesced
+     * message dequeued later joins the same turn via `joinTurn`.
+     */
+    openTurn(trigger, commandUuid, msg) {
+        const turnId = `turn-${++this._turnSeq}`;
+        // The set holds every command associated with this turn, including one the
+        // CLI named that we have no record of sending. `trigger` says whether it
+        // was ours; the set is what lets a terminal lifecycle record close the turn
+        // it opened. Without that, a `started`/`refused` pair for an unrecognized
+        // uuid opened a turn nothing could close.
+        this._openTurn = {
+            turnId,
+            trigger,
+            commandUuids: new Set(commandUuid ? [commandUuid] : []),
+        };
+        // The delivery that prompted this turn has been answered by it opening.
+        this._pendingDeliveries.clear();
+        // A host turn takes `thinking` from send(); a provider-initiated one has
+        // nothing else to set it, and `state` must not contradict `turn_start`.
+        if (this._state === "idle")
+            this._state = "thinking";
+        this.dispatchEvent({
+            type: "turn_start",
+            turnId,
+            trigger,
+            timestamp: new Date().toISOString(),
+            providerType: CLAUDE_PROVIDER_TYPE,
+            sessionId: this._sessionId,
+            messageId: null,
+            eventId: str(msg, "uuid") || null,
+            parentToolCallId: null,
+            raw: { type: str(msg, "type"), ...(commandUuid ? { command_uuid: commandUuid } : {}) },
+        });
+    }
+    /** Attach a coalesced host message to the turn already running. */
+    joinTurn(commandUuid) {
+        this._openTurn?.commandUuids.add(commandUuid);
+        this._outstandingCommands.delete(commandUuid);
+    }
+    /**
+     * Close the open turn and announce it. Returns what was closed, or null.
+     *
+     * Every `turn_start` gets exactly one `turn_end`, which is why this is the
+     * only place a turn is cleared. `result` alone could not serve: a cancelled,
+     * discarded, or refused message opens a turn and produces no result.
+     */
+    closeTurn(reason) {
+        const turn = this.takeOpenTurn();
+        this.emitTurnEnd(turn, reason);
+        return turn;
+    }
+    /**
+     * Clear the open turn and return it, without announcing the close.
+     *
+     * Split from the announcement because the state change has to be synchronous
+     * — the CLI can flush a result and the next turn's opening line in one chunk
+     * — while `turn_end` must be ordered *after* the `result` that carries the
+     * turn's payload.
+     */
+    takeOpenTurn() {
+        const turn = this._openTurn;
+        this._openTurn = null;
+        this._pendingDeliveries.clear();
+        return turn;
+    }
+    /** Announce a close for a turn already taken. No-op for a null turn. */
+    emitTurnEnd(turn, reason) {
+        if (!turn)
+            return;
+        this.dispatchEvent({
+            type: "turn_end",
+            turnId: turn.turnId,
+            trigger: turn.trigger,
+            reason,
+            timestamp: new Date().toISOString(),
+            providerType: CLAUDE_PROVIDER_TYPE,
+            sessionId: this._sessionId,
+            messageId: null,
+            eventId: null,
+            parentToolCallId: null,
+            raw: { reason },
+        });
+    }
+    /**
+     * Remove and return the send resolvers belonging to `turn`.
+     *
+     * Synchronous and exhaustive by design: the caller holds the only reference
+     * to the returned array, so no later turn can drain it.
+     */
+    claimSettlementBatch(turn) {
+        const batch = [];
+        this._settlingBatches.add(batch);
+        if (!turn) {
+            // A result with no turn to attribute it to. Settling everything is the
+            // lesser evil: resolving with a neighbouring turn's result is wrong, but
+            // hanging every caller is worse.
+            batch.push(...this._pendingResults.splice(0));
+            return batch;
+        }
+        if (turn.commandUuids.size === 0)
+            return batch; // provider-initiated
+        for (let i = this._pendingResults.length - 1; i >= 0; i--) {
+            if (turn.commandUuids.has(this._pendingResults[i].commandUuid)) {
+                batch.unshift(...this._pendingResults.splice(i, 1));
+            }
+        }
+        return batch;
+    }
+    /**
+     * Settle any send still waiting on a command the CLI has finished with.
+     *
+     * `completed` means its turn ran, so it takes that turn's result; the other
+     * terminal states mean it never ran at all.
+     */
+    settleCommand(commandUuid, state) {
+        for (let i = this._pendingResults.length - 1; i >= 0; i--) {
+            const entry = this._pendingResults[i];
+            if (entry.commandUuid !== commandUuid || entry.settled)
+                continue;
+            this._pendingResults.splice(i, 1);
+            entry.settled = true;
+            entry.cleanup?.();
+            // Reaching here means no turn ever claimed this message, so there is no
+            // result of its own to give it. `completed` without a claiming turn is
+            // not expected — it is reported honestly rather than papered over with a
+            // neighbouring turn's payload.
+            entry.resolve({
+                status: state === "completed" ? "completed" : "aborted",
+                summary: null,
+                costUsd: null,
+                errorCode: `command_${state}`,
+                errorMessage: `Message was ${state} by the CLI without a turn of its own`,
+            });
+        }
+    }
+    /**
+     * Reject every send still waiting on a turn, and clear the turn bookkeeping
+     * that described it. Shared by the fatal paths and by `close()`.
+     */
+    rejectPendingSends(err) {
         const pending = this._pendingResults.splice(0);
+        // Batches already captured for a turn still settling. Their handler may
+        // never resume — the process is gone — so they are rejected here rather
+        // than left hanging their callers.
+        for (const captured of this._settlingBatches)
+            pending.push(...captured);
+        this._settlingBatches.clear();
+        // No turn survives this, and the host is told so rather than left holding
+        // an unmatched `turn_start`.
+        this.closeTurn("session_closed");
+        this._outstandingCommands.clear();
+        this._activeTasks.clear();
+        this._taskFacts.clear();
         for (const p of pending) {
             if (p.settled)
                 continue;
@@ -326,6 +561,10 @@ export class ClaudeSessionImpl {
             p.cleanup?.();
             p.reject(err);
         }
+    }
+    /** Reject every pending send() Promise and outgoing control_response. */
+    rejectAllPending(err) {
+        this.rejectPendingSends(err);
         for (const [, p] of this._pendingControlResponses)
             p.reject(err);
         this._pendingControlResponses.clear();
@@ -370,6 +609,9 @@ export class ClaudeSessionImpl {
         if (this._state === "idle")
             this._state = "thinking";
         const uuid = randomUUID();
+        // The CLI echoes this back on every `command_lifecycle` record for the
+        // message, which is what lets a turn be attributed exactly.
+        this._outstandingCommands.add(uuid);
         // Write user message in stream-json format. `uuid` becomes the queue
         // key the CLI uses for `cancel_async_message`.
         const userMsg = ndjsonLine({
@@ -385,7 +627,7 @@ export class ClaudeSessionImpl {
             resolveFn = resolve;
             rejectFn = reject;
         });
-        const entry = { resolve: resolveFn, reject: rejectFn };
+        const entry = { commandUuid: uuid, resolve: resolveFn, reject: rejectFn };
         this._pendingResults.push(entry);
         // Track the in-flight turn so drain() can await it; drop it on settle.
         this._inFlight.add(result);
@@ -473,6 +715,8 @@ export class ClaudeSessionImpl {
         this.proc.stdin.write(cancelMsg);
         try {
             const response = await responsePromise;
+            // No bookkeeping here: the CLI emits `command_lifecycle/cancelled` for
+            // the message, and that is what retires it.
             return { cancelled: response["cancelled"] === true };
         }
         catch {
@@ -543,14 +787,57 @@ export class ClaudeSessionImpl {
             // Let every in-flight turn settle (resolve or reject) before closing, so
             // a running tool finishes rather than being killed mid-flight.
             await Promise.allSettled([...this._inFlight]);
+            // `_inFlight` only tracks turns this host dispatched. A provider-initiated
+            // turn — the CLI acting on a finished background task — has no send()
+            // behind it, so draining used to SIGTERM the CLI mid-turn and kill
+            // whatever that turn was doing. Now that the session can see those turns,
+            // the one API whose contract is "let in-flight work settle" honors them.
+            await this.awaitTurnClose();
             await this.close();
         })();
         return this._drainPromise;
     }
+    /**
+     * Resolve once no turn is open, or once the deadline passes.
+     *
+     * Bounded on purpose: a turn that never produces a `result` (a wedged CLI)
+     * must not make `drain()` hang forever. Polling rather than eventing because
+     * turn close is driven from the stream reader, and a missed edge here would
+     * be the same hang by another route.
+     */
+    async awaitTurnClose(timeoutMs = 120_000) {
+        const deadline = Date.now() + timeoutMs;
+        const settling = () => {
+            if (this._openTurn)
+                return true;
+            // A running subagent will hand its result back and open a resume turn,
+            // so it is in-flight work. Closing during the gap between the root
+            // result and that turn — measured at 8-11s live — killed it outright.
+            //
+            // Background *processes* are excluded on purpose: a dev server started
+            // with run_in_background may never exit, and the contract is "let the
+            // agent's work settle", not "outlive whatever it launched".
+            // A delivered result whose resume turn has not opened yet. This is the
+            // provider's own signal that more work is coming, used where it matters.
+            if (this._pendingDeliveries.size > 0)
+                return true;
+            for (const taskType of this._activeTasks.values()) {
+                if (taskType === "subagent")
+                    return true;
+            }
+            return false;
+        };
+        while (settling() && this._state !== "closed" && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    }
     async close() {
         if (this._state === "closed")
             return;
         this._state = "closed";
+        // Anything still waiting has no turn left to settle it. Without this a
+        // bare `close()` with a send in flight hung that caller for good.
+        this.rejectPendingSends(new Error("Session closed before the turn completed"));
         // Final transcript scan so a goal_status (e.g. `met`) written since the last
         // ~800ms poll isn't lost on a fast close. No-op when no goal is observed.
         await this.scanGoalTranscript().catch(() => { });
@@ -628,8 +915,20 @@ export class ClaudeSessionImpl {
         // await inside handleResult drains the chain so handlers settle before
         // the awaiting send() returns.
         if (type === "result") {
+            // Close the turn and snapshot its settlement batch synchronously, before
+            // any `await`. Both halves matter. Closing late swallows the next
+            // `turn_start`, because the CLI can flush this result and the following
+            // turn's opening line in one chunk. Snapshotting late is worse: the
+            // batch used to live in a field shared by every turn, so whichever
+            // async handler resumed first drained all of it and resolved the second
+            // turn's sends with the first turn's result.
+            const closingTurn = this.takeOpenTurn();
+            const batch = this.claimSettlementBatch(closingTurn);
+            this._seenResult = true;
             this.handleStreamMessage(msg, line);
-            void this.handleResult(msg);
+            // Announced after the result event, so the payload precedes the close.
+            this.emitTurnEnd(closingTurn, "result");
+            void this.handleResult(msg, batch);
             return;
         }
         // Stream events — forward via onEvent and parse for agentex StreamEvent
@@ -642,16 +941,24 @@ export class ClaudeSessionImpl {
         const requestId = str(msg, "request_id");
         const request = obj(msg, "request");
         const subtype = str(request, "subtype");
+        const nested = msg["parent_tool_use_id"] != null
+            || request["parent_tool_use_id"] != null;
         switch (subtype) {
             case "initialize":
                 this.sendControlResponse(requestId, {});
                 break;
+            // A detached subagent raises its own prompts, and those are the child
+            // being blocked, not this session. Parking the parent in
+            // `waiting_for_approval` there outlived the root turn with nothing able
+            // to clear it — the same nested-actor rule the stream path applies.
             case "can_use_tool":
-                this._state = "waiting_for_approval";
+                if (!nested)
+                    this._state = "waiting_for_approval";
                 this.handlePermissionRequest(requestId, request);
                 break;
             case "elicitation":
-                this._state = "waiting_for_input";
+                if (!nested)
+                    this._state = "waiting_for_input";
                 this.handleElicitationRequest(requestId, request);
                 break;
             case "hook_callback":
@@ -824,7 +1131,7 @@ export class ClaudeSessionImpl {
     // -------------------------------------------------------------------------
     // Result handling
     // -------------------------------------------------------------------------
-    async handleResult(msg) {
+    async handleResult(msg, batch = []) {
         const summary = typeof msg["result"] === "string" ? msg["result"] : null;
         const isError = msg["is_error"] === true;
         const costUsd = typeof msg["total_cost_usd"] === "number" ? msg["total_cost_usd"] : null;
@@ -899,13 +1206,19 @@ export class ClaudeSessionImpl {
         // session whose stdin is dead.
         if (this._state === "closed")
             return;
-        this._state = "idle";
-        // Drain ALL pending send() resolvers with this turn's result. Multiple
-        // concurrent sends coalesced by the CLI into one turn share the same
-        // TurnResult — documented in SendHandle JSDoc. Splice empties the list
-        // so subsequent sends queue against a fresh list for the next turn.
-        const pending = this._pendingResults.splice(0);
-        for (const p of pending) {
+        // Only fall back to idle if no new turn opened while the chain drained.
+        // The CLI can start the next turn in the same chunk as this result, and
+        // asserting idle over a turn that is already running is the exact false
+        // "finished" this release exists to remove.
+        if (!this._openTurn)
+            this._state = "idle";
+        // Settle the batch this turn owns — and only that batch. It was captured
+        // synchronously when the result line was read, so a turn that opened while
+        // this handler was suspended cannot have its sends resolved here. That
+        // sharing is what made two back-to-back results resolve both sends with
+        // the first result.
+        this._settlingBatches.delete(batch);
+        for (const p of batch) {
             // Skip sends already settled early by timeout / abort.
             if (p.settled)
                 continue;
@@ -920,20 +1233,91 @@ export class ClaudeSessionImpl {
     // Stream event forwarding
     // -------------------------------------------------------------------------
     handleStreamMessage(msg, rawLine) {
+        // A line can arrive during close()'s grace window. Acting on it would
+        // reopen a turn on a dead session, flip `state` off "closed", and emit a
+        // `turn_start` to a host that has already drained — with nothing left to
+        // ever close it again.
+        if (this._state === "closed")
+            return;
         // Extract session ID from any message that has one
         if (typeof msg["session_id"] === "string" && msg["session_id"]) {
             this._sessionId = msg["session_id"];
         }
-        // Update session state based on message type
+        // Update session state based on message type. Nested-actor lines are
+        // excluded for the same reason they do not open a turn: a detached
+        // subagent streams its own output onto the parent after the root result,
+        // and letting it drive `state` left the session reporting "thinking" for
+        // the child's whole run — directly contradicting `turn_start`/`result`,
+        // with nothing to clear it if the child is stopped or killed.
         const type = str(msg, "type");
-        if (type === "assistant" || type === "thinking") {
-            this._state = "thinking";
+        if (msg["parent_tool_use_id"] == null) {
+            if (type === "assistant" || type === "thinking") {
+                this._state = "thinking";
+            }
+            else if (type === "tool_use") {
+                this._state = "tool_executing";
+            }
+            else if (type === "tool_result") {
+                this._state = "thinking";
+            }
         }
-        else if (type === "tool_use") {
-            this._state = "tool_executing";
+        // Retire host messages the CLI has finished with, before deciding what a
+        // turn opening means. `refused`/`discarded` never produce a `result`, so
+        // this is also the only thing that closes a turn they opened — without it
+        // the session would pin as working with no path back.
+        if (type === "command_lifecycle") {
+            this._seenCommandLifecycle = true;
+            const commandUuid = str(msg, "command_uuid");
+            const state = str(msg, "state");
+            if (commandUuid && TERMINAL_COMMAND_STATES.has(state)) {
+                this._outstandingCommands.delete(commandUuid);
+                // The CLI is done with this message. Anything still waiting on it will
+                // never be settled by a `result` — a cancelled or refused message
+                // produces none, and a `completed` one whose turn we could not attribute
+                // would otherwise wait forever.
+                this.settleCommand(commandUuid, state);
+                if (state !== "completed" && this._openTurn?.commandUuids.has(commandUuid)) {
+                    // Nothing else will close this turn: these states never produce a
+                    // `result`. (A closed session returned above, so state is live.)
+                    this.closeTurn(state);
+                    this._state = "idle";
+                }
+            }
         }
-        else if (type === "tool_result") {
-            this._state = "thinking";
+        // Background-task state is session state: `drain()` waits on live
+        // subagents and turn attribution consumes delivered results. Decoded here
+        // from the wire rather than in the dispatch path, which only runs when a
+        // host subscribed — a host that reads `session.state` and calls `drain()`
+        // without an onEvent handler would otherwise get neither.
+        this.trackBackgroundTaskState(msg);
+        // Open a turn on the first line of turn content, before that line's own
+        // events, so a host sees turn_start → … → result → turn_end in order.
+        const namedUuid = type === "command_lifecycle" ? str(msg, "command_uuid") : "";
+        if (this._openTurn) {
+            // The CLI coalesces: a host message dequeued while a turn is running
+            // joins it rather than starting its own. Modelling one command per turn
+            // left every coalesced message permanently unsettled.
+            if (namedUuid && this._outstandingCommands.has(namedUuid))
+                this.joinTurn(namedUuid);
+        }
+        else if (this.opensTurn(msg, type)) {
+            // Exact attribution: the CLI stamps every `command_lifecycle` for a host
+            // message with the uuid `send()` minted, so a `started` naming one we are
+            // still waiting on *is* that message's turn. Anything else opened the
+            // turn without us asking — which is what this event exists to expose.
+            const claimedUuid = namedUuid
+                ? (this._outstandingCommands.has(namedUuid) ? namedUuid : null)
+                // Only guess for a build that has never named a command. Once one has,
+                // it names every host message, so an unnamed turn is provider-initiated
+                // and consuming a uuid here would mislabel twice.
+                : this._seenCommandLifecycle
+                    ? null
+                    : this._outstandingCommands.values().next().value ?? null;
+            if (claimedUuid)
+                this._outstandingCommands.delete(claimedUuid);
+            // Track the named command even when it is not one of ours, so its
+            // terminal lifecycle record can close this turn.
+            this.openTurn(claimedUuid ? "send" : "resume", claimedUuid ?? (namedUuid || null), msg);
         }
         // Parse + dispatch when there's an onEvent subscriber OR an active goal to
         // observe, so native goal_status transitions update getGoal() even with no
@@ -945,21 +1329,149 @@ export class ClaudeSessionImpl {
         }
     }
     /**
-     * Queue an event for in-order delivery to `onEvent`. Each call appends a
-     * `.then` to `_eventChain` so handler N+1 only starts after handler N's
-     * returned promise settles. Errors are swallowed inside the chain so a
-     * throwing handler does not break delivery of subsequent events.
+     * Whether this wire line is the first content of a turn.
+     *
+     * Deliberately excludes two things.
+     *
+     * The background-task records (`task_started`, `task_updated`,
+     * `task_notification`, `background_tasks_changed`) arrive *between* turns —
+     * a detached child reporting in while nothing is running — so treating one
+     * as a turn opening would report the session as working every time a
+     * background process coughed.
+     *
+     * `system/init` is special. It is boot metadata the first time — before any
+     * result, opening a turn on it would create a phantom `resume` at startup,
+     * leave it open, and swallow the first real send's `turn_start`. But the
+     * CLI re-emits it at the head of every provider-initiated resume turn, and
+     * measured live it precedes that turn's first assistant line by 1.4–1.9s.
+     * Ignoring it outright traded a phantom turn for a second-long blind window
+     * on exactly the turns this event exists to expose, so it opens a turn once
+     * a result has been seen on this stream and not before.
+     *
+     * And anything carrying `parent_tool_use_id`, which is a nested actor's own
+     * output. Claude streams a detached subagent's assistant text, thinking and
+     * tool calls onto the parent stream while the root turn is over. Those are
+     * the child working, not this session, and counting them would hold the
+     * session "working" for the entire detached run — when the honest answer,
+     * and what the CLI shows, is that the root turn finished and its result is
+     * ready to read. The real resume turn arrives afterwards, at root level,
+     * once the child's result is delivered back.
+     */
+    opensTurn(msg, type) {
+        if (msg["parent_tool_use_id"] != null)
+            return false;
+        // `stream_event` is the partial-message wrapper. Without it, a host that
+        // opted into `includePartialMessages` receives the whole streamed reply
+        // before `turn_start` — the turn's output arriving before the event that
+        // says the turn began.
+        if (type === "stream_event")
+            return true;
+        // `command_lifecycle/started` heads every host-dispatched turn and only
+        // those — never a resume — so it is safe to open on and carries no
+        // phantom-turn risk. It is also the earliest signal available: without it
+        // the session's very first turn has no opener until its first assistant
+        // line, measured live at 1.8-6.4s of reading as idle while working.
+        if (type === "command_lifecycle")
+            return str(msg, "state") === "started";
+        if (type === "system")
+            return this._seenResult && str(msg, "subtype") === "init";
+        // `thinking` and `tool_use` are content blocks inside an `assistant`
+        // message, not top-level wire types; they are listed because the state
+        // machine above accepts them and the two should not disagree about what
+        // counts as turn content.
+        return type === "assistant"
+            || type === "thinking"
+            || type === "tool_use"
+            || type === "user";
+    }
+    /**
+     * Fold one background-task wire record into session state.
+     *
+     * Separate from the enrichment below on purpose: this must run for every
+     * line regardless of whether anything is listening, because `drain()` and
+     * turn attribution read what it maintains.
      */
+    trackBackgroundTaskState(msg) {
+        const event = backgroundTaskEventFromClaude(msg);
+        if (!event)
+            return;
+        const terminal = event.status === "completed"
+            || event.status === "failed"
+            || event.status === "stopped";
+        if (terminal) {
+            this._activeTasks.delete(event.taskId);
+        }
+        else if (event.status !== null || event.phase === "started") {
+            // `status: null` means "no change reported" — a sparse patch that only
+            // renames a task says nothing about liveness. Writing the task back into
+            // the live set there resurrected work that had already completed.
+            this._activeTasks.set(event.taskId, this._taskFacts.get(event.taskId)?.taskType ?? event.taskType);
+        }
+        // The provider stating that a turn is coming — held so `drain()` does not
+        // close in the gap before it opens. Keyed on the outcome rather than on
+        // the delivery record alone, because a completion arrives as two records
+        // (`task_updated` then `task_notification`) and the first already removes
+        // the task from the live set: waiting only for the second left a window
+        // where neither the task nor the delivery was visible.
+        //
+        // Only for outcomes that actually deliver. A stopped task hands nothing
+        // back and starts no turn, so holding for one would just burn the deadline.
+        const delivers = event.status === "completed" || event.status === "failed";
+        if ((event.report || delivers) && !this._openTurn) {
+            this._pendingDeliveries.add(event.taskId);
+        }
+        if (event.phase === "started") {
+            this._taskFacts.set(event.taskId, {
+                taskType: event.taskType,
+                description: event.description,
+            });
+            // Evict oldest-first. Map iteration is insertion-ordered, so the first
+            // key is the least recently started task.
+            while (this._taskFacts.size > ClaudeSessionImpl.TASK_FACT_LIMIT) {
+                const oldest = this._taskFacts.keys().next();
+                if (oldest.done)
+                    break;
+                this._taskFacts.delete(oldest.value);
+            }
+        }
+    }
+    /**
+     * Fill in what a sparse background-task record leaves out.
+     *
+     * `task_started` is the only record that names the task's type; the patches
+     * and the completion notification that follow identify it by id alone. This
+     * remembers the first description and carries it forward so a completion
+     * still knows it was a subagent.
+     */
+    _trackTaskFacts(event) {
+        if (event.type !== "background_task")
+            return event;
+        const known = this._taskFacts.get(event.taskId);
+        if (!known)
+            return event;
+        const needsType = event.taskType === "unknown" && known.taskType !== "unknown";
+        const needsDescription = event.description === null && known.description !== null;
+        if (!needsType && !needsDescription)
+            return event;
+        return {
+            ...event,
+            taskType: needsType ? known.taskType : event.taskType,
+            description: needsDescription ? known.description : event.description,
+        };
+    }
     dispatchEvent(event) {
+        // Enrich and record before anything can bail out. `_trackTaskFacts` also
+        // maintains session state — which tasks are live, which results are
+        // waiting for a resume turn — and gating that on a subscriber meant
+        // `session.state`, `drain()` and turn attribution all silently degraded
+        // for a host that reads the session without an onEvent handler.
+        const enriched = this._trackTaskFacts(this._trackToolName(event));
         // Let the goal engine track native goal_status transitions even when no
         // onEvent handler is attached (keeps getGoal() accurate).
-        this._goals.observe(event);
+        this._goals.observe(enriched);
         const cb = this.ctx.onEvent;
         if (!cb)
             return;
-        // Enrich synchronously (in stream order) so tool_result events carry the
-        // name of the tool_call they answer.
-        const enriched = this._trackToolName(event);
         this._eventChain = this._eventChain.then(async () => {
             try {
                 await cb(enriched);