sidekick-shared 0.29.0 → 0.30.0

package/dist/esm/aggregation/EventAggregator.js

@@ -18,6 +18,8 @@ import { HeatmapTracker } from './HeatmapTracker';
 import { PatternExtractor } from './PatternExtractor';
 import { categorizeError } from '../extractors/errorTaxonomy';
 import { estimateTextTokens } from '../tokenEstimation';
+import { describeSubagentActivity, isSubagentActivitySystemEvent, subagentActivityFromEvent, } from '../subagentActivity';
+import { agentsStoppedNoticeFromEvent, describeAgentsStopped, describeTaskStatus, isAgentsKilledSystemEvent, isCodexSubagentSpawnTool, isFinalTaskStatus, isSubagentSpawnTool, isTaskNotificationSystemEvent, isTaskStatusSystemEvent, parseAgentsStoppedNotice, parseAsyncAgentLaunch, parseCodexSpawnLaunch, parseTaskNotification, taskNotificationFromEvent, taskNotificationOutcome, taskNotificationPromptFromAttachment, taskStatusFromAttachment, taskStatusFromEvent, } from '../subagentSpawn';
 import { calculateNormalizedUsageCost, extractNormalizedUsage, normalizeProviderUsage, } from '../usageNormalization';
 // ── Defaults ──
 const DEFAULT_TIMELINE_CAP = 200;
@@ -26,10 +28,100 @@ const DEFAULT_CONTEXT_TIMELINE_CAP = 2_000;
 const DEFAULT_BURN_WINDOW_MS = 5 * 60_000;
 const DEFAULT_BURN_SAMPLE_MS = 10_000;
 const COMPACTION_DROP_THRESHOLD = 0.8; // >20% drop
-/** Schema version for serialized snapshots. v6: token totals count each Claude response and Codex call once. */
-export const SNAPSHOT_SCHEMA_VERSION = 6;
+/**
+ * Schema version for serialized snapshots. v6: token totals count each Claude
+ * response and Codex call once. v7: subagent lifecycles track Codex spawns and
+ * record what settled a background agent (`settledBy`).
+ */
+export const SNAPSHOT_SCHEMA_VERSION = 7;
+// Checked without the schema module so this file stays free of Zod.
+const PERMISSION_MODES = new Set([
+    'default',
+    'acceptEdits',
+    'bypassPermissions',
+    'plan',
+    'auto',
+    'dontAsk',
+]);
+function asPermissionMode(value) {
+    return typeof value === 'string' && PERMISSION_MODES.has(value)
+        ? value
+        : null;
+}
 // ── Goal gate detection regex ──
 const GOAL_GATE_REGEX = /\b(CRITICAL|MUST|blocker|required|must.?complete|goal.?gate|essential|do.?not.?skip|blocking)\b/i;
+// ── Task notifications delivered as attachments ──
+/**
+ * The notification a `system` FollowEvent carries when it stands for a
+ * mid-turn task-notification attachment (its `raw` is the attachment line or
+ * the SessionEvent `extractSessionEvents` made from it).
+ */
+function taskNotificationFromAttachmentFollowEvent(event) {
+    const raw = event.raw;
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const prompt = taskNotificationPromptFromAttachment(raw);
+    if (prompt !== null)
+        return parseTaskNotification(prompt);
+    const asEvent = raw;
+    return isTaskNotificationSystemEvent(asEvent) ? taskNotificationFromEvent(asEvent) : null;
+}
+function subagentRecordFromFollowEvent(event) {
+    const raw = event.raw;
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const notification = taskNotificationFromAttachmentFollowEvent(event);
+    if (notification)
+        return { kind: 'notification', notification };
+    const asEvent = raw;
+    const prompt = taskNotificationPromptFromAttachment(raw);
+    const notice = prompt !== null ? parseAgentsStoppedNotice(prompt) : agentsStoppedNoticeFromEvent(asEvent);
+    if (notice)
+        return { kind: 'stopped', notice };
+    if (prompt !== null || isTaskNotificationSystemEvent(asEvent)) {
+        // A notification this release cannot read: still bookkeeping.
+        return { kind: 'unreadable' };
+    }
+    const status = taskStatusFromAttachment(raw) ?? taskStatusFromEvent(asEvent);
+    if (status)
+        return { kind: 'task-status', status };
+    if (isSubagentActivitySystemEvent(asEvent)) {
+        const activity = subagentActivityFromEvent(asEvent);
+        return activity ? { kind: 'activity', activity } : { kind: 'unreadable' };
+    }
+    if (isAgentsKilledSystemEvent(raw))
+        return { kind: 'agents-killed' };
+    return null;
+}
+// ── Subagent spawn input ──
+/**
+ * Description and type of a spawn: Claude Code's `description` /
+ * `subagent_type`, or Codex `spawn_agent`'s `task_name` / `agent_type`.
+ */
+function spawnFields(input) {
+    const text = (value) => typeof value === 'string' && value ? value : undefined;
+    const description = text(input.description) ?? text(input.task_name);
+    const subagentType = text(input.subagent_type) ?? text(input.subagentType) ?? text(input.agent_type);
+    return {
+        ...(description ? { description } : {}),
+        ...(subagentType ? { subagentType } : {}),
+    };
+}
+/**
+ * Whether a spawn's tool result launched the agent in the background or
+ * ended it. A Codex `spawn_agent` result is always a launch unless it failed
+ * ("collab spawn failed: …"); its `{"task_name": …}` output is a launch even
+ * when the output's text looked like an error to the parser (an agent path
+ * such as `/root/fix_failed_tests`).
+ */
+function spawnResultKind(codex, content, isError) {
+    // Read first: the `codex` hint does not survive a snapshot boundary.
+    if (parseCodexSpawnLaunch(content))
+        return 'launch';
+    if (codex)
+        return isError ? 'end' : 'launch';
+    return !isError && parseAsyncAgentLaunch(content) ? 'launch' : 'end';
+}
 // ── Todo dependency parsing ──
 /**
  * Parses dependency references from a todo item's content text.
@@ -115,6 +207,8 @@ export class EventAggregator {
     // Subagent lifecycle
     subagents = [];
     pendingSubagents = new Map(); // toolUseId -> index
+    /** Codex `spawn_agent` calls still waiting for their result (always a background launch). */
+    pendingCodexSpawns = new Set();
     // Plan state
     planExtractor;
     planState = null;
@@ -168,6 +262,41 @@ export class EventAggregator {
     // processEvent — main entry for SessionEvent
     // ═══════════════════════════════════════════════════════════════════════
     processEvent(event) {
+        // Opt-in mid-turn task notifications (`extractSessionEvents` with
+        // `includeTaskNotifications`) only finish background subagents and mark
+        // the timeline: they are not messages, prompts, context, or activity.
+        if (isTaskNotificationSystemEvent(event)) {
+            const notification = taskNotificationFromEvent(event);
+            if (notification) {
+                this.applyTaskNotification(notification, event.timestamp);
+                this.addTaskNotificationTimeline(event.timestamp, notification);
+            }
+            else {
+                // The plain-text "background agents were stopped by the user" notice.
+                const notice = agentsStoppedNoticeFromEvent(event);
+                if (notice)
+                    this.applyAgentsStopped(notice, event.timestamp);
+            }
+            return;
+        }
+        // So are a background agent's final `task_status` (same opt-in) and the
+        // opt-in Codex subagent lifecycle records (`subagentActivityFromEvent`).
+        if (isTaskStatusSystemEvent(event)) {
+            const status = taskStatusFromEvent(event);
+            if (status)
+                this.applyTaskStatus(status, event.timestamp);
+            return;
+        }
+        if (isSubagentActivitySystemEvent(event)) {
+            const activity = subagentActivityFromEvent(event);
+            if (activity)
+                this.applySubagentActivity(activity, event.timestamp);
+            return;
+        }
+        // The user killed every running background agent. The line itself is
+        // counted below as before.
+        if (isAgentsKilledSystemEvent(event))
+            this.applyAgentsKilled(event.timestamp);
         // 1. Increment counters, capture timestamps
         this.eventCount++;
         if (!this.sessionStartTime) {
@@ -233,12 +362,24 @@ export class EventAggregator {
     // processFollowEvent — adapter for CLI FollowEvent format
     // ═══════════════════════════════════════════════════════════════════════
     processFollowEvent(event) {
+        // Subagent bookkeeping (a mid-turn task-notification or task-status
+        // attachment, a stop notice or `agents_killed` line, a Codex lifecycle
+        // record), like its SessionEvent form above: not counted as activity.
+        if (event.type === 'system') {
+            const record = subagentRecordFromFollowEvent(event);
+            if (record) {
+                this.applySubagentFollowRecord(record, event.timestamp);
+                return;
+            }
+        }
         // 1. Increment counters, capture timestamps
         this.eventCount++;
         if (!this.sessionStartTime) {
             this.sessionStartTime = event.timestamp;
         }
         this.lastEventTime = event.timestamp;
+        // Followed events carry the mode as a plain string.
+        this.trackPermissionMode(event);
         // Provider
         if (!this._providerId && event.providerId) {
             this._providerId = event.providerId;
@@ -370,6 +511,10 @@ export class EventAggregator {
     getSubagents() {
         return [...this.subagents];
     }
+    /** Timestamp of the last counted event (`getMetrics().lastEventTime`), without building the metrics. */
+    getLastEventTime() {
+        return this.lastEventTime;
+    }
     getPlan() {
         return this.planState
             ? { ...this.planState, steps: this.planState.steps.map((step) => ({ ...step })) }
@@ -466,6 +611,7 @@ export class EventAggregator {
         this.activeTaskId = null;
         this.subagents = [];
         this.pendingSubagents.clear();
+        this.pendingCodexSpawns.clear();
         this.planExtractor.reset();
         this.planState = null;
         this.planEnteredAt = undefined;
@@ -599,7 +745,7 @@ export class EventAggregator {
         this.tasks = new Map(state.tasks);
         this.activeTaskId = state.activeTaskId;
         this.subagents = [...state.subagents];
-        this.currentPermissionMode = state.permissionMode ?? null;
+        this.currentPermissionMode = asPermissionMode(state.permissionMode) ?? null;
         this.permissionModeHistory = state.permissionModeHistory
             ? [...state.permissionModeHistory]
             : [];
@@ -626,6 +772,15 @@ export class EventAggregator {
         this.pendingToolCalls.clear();
         this.pendingTaskCreates.clear();
         this.pendingSubagents.clear();
+        this.pendingCodexSpawns.clear();
+        // A spawn still waiting for its tool_result is resolved by that result,
+        // which can land after the snapshot boundary. Background agents need no
+        // entry: their notifications are matched against every subagent.
+        this.subagents.forEach((agent, idx) => {
+            if (agent.status === 'running' && !agent.background && agent.id) {
+                this.pendingSubagents.set(agent.id, idx);
+            }
+        });
         this.pendingUserRequest = null;
         this.planExtractor.reset();
         return true;
@@ -1104,7 +1259,7 @@ export class EventAggregator {
                 else if (name === 'UpdatePlan') {
                     this.handleUpdatePlan(input, new Date(event.timestamp));
                 }
-                else if ((name === 'Agent' || name === 'Task') && toolUseId) {
+                else if (isSubagentSpawnTool(name, input) && toolUseId) {
                     this.handleAgentSpawn(toolUseId, input, new Date(event.timestamp));
                 }
             }
@@ -1114,7 +1269,7 @@ export class EventAggregator {
                     continue;
                 const isError = block.is_error ?? false;
                 this.resolveTaskCreate(toolUseId, block.content ?? block.output, event.timestamp, isError);
-                this.resolveAgentResult(toolUseId, isError, event.timestamp);
+                this.resolveAgentResult(toolUseId, isError, event.timestamp, block.content ?? block.output);
             }
         }
     }
@@ -1148,7 +1303,7 @@ export class EventAggregator {
             else if (event.toolName === 'UpdatePlan') {
                 this.handleUpdatePlan(input, new Date(event.timestamp));
             }
-            else if ((event.toolName === 'Agent' || event.toolName === 'Task') && toolUseId) {
+            else if (isSubagentSpawnTool(event.toolName, input) && toolUseId) {
                 this.handleAgentSpawn(toolUseId, input, new Date(event.timestamp));
             }
         }
@@ -1160,7 +1315,7 @@ export class EventAggregator {
                 return;
             const isError = raw.is_error ?? false;
             this.resolveTaskCreate(toolUseId, raw.content, event.timestamp, isError);
-            this.resolveAgentResult(toolUseId, isError, event.timestamp);
+            this.resolveAgentResult(toolUseId, isError, event.timestamp, raw.content);
         }
     }
     applyTaskUpdate(input) {
@@ -1447,8 +1602,9 @@ export class EventAggregator {
     // ═══════════════════════════════════════════════════════════════════════
     handleAgentSpawn(toolUseId, input, now) {
         const agentTaskId = `agent-${toolUseId}`;
-        const description = input.description ? String(input.description) : 'Subagent';
-        const subagentType = input.subagent_type || input.subagentType || undefined;
+        const spawn = spawnFields(input);
+        const description = spawn.description ?? 'Subagent';
+        const subagentType = spawn.subagentType;
         const task = {
             taskId: agentTaskId,
             subject: description,
@@ -1465,11 +1621,15 @@ export class EventAggregator {
         };
         this.tasks.set(agentTaskId, task);
     }
-    resolveAgentResult(toolUseId, isError, timestamp) {
+    resolveAgentResult(toolUseId, isError, timestamp, content) {
         const agentTaskId = `agent-${toolUseId}`;
         const agentTask = this.tasks.get(agentTaskId);
         if (!agentTask)
             return;
+        // A background launch returns at once; its task notification finishes it.
+        if (spawnResultKind(this.pendingCodexSpawns.has(toolUseId), content, isError) === 'launch') {
+            return;
+        }
         agentTask.status = isError ? 'deleted' : 'completed';
         agentTask.updatedAt = new Date(timestamp);
     }
@@ -1489,31 +1649,25 @@ export class EventAggregator {
     // Private: Subagent Tracking from SessionEvent
     // ═══════════════════════════════════════════════════════════════════════
     extractSubagentFromEvent(event) {
+        const notification = taskNotificationFromEvent(event);
+        if (notification)
+            this.applyTaskNotification(notification, event.timestamp);
         const content = event.message?.content;
         if (!Array.isArray(content))
             return;
         for (const block of content) {
-            if (block.type === 'tool_use' && block.name === 'Task') {
+            if (block.type === 'tool_use' && isSubagentSpawnTool(block.name, block.input)) {
                 const input = block.input;
                 const toolUseId = block.id;
                 if (!input || !toolUseId)
                     continue;
-                const info = {
-                    id: toolUseId,
-                    description: input.description || 'Unknown task',
-                    subagentType: input.subagent_type || input.subagentType || 'general',
-                    spawnTime: event.timestamp,
-                    status: 'running',
-                };
-                const idx = this.subagents.length;
-                this.subagents.push(info);
-                this.pendingSubagents.set(toolUseId, idx);
+                this.trackSubagentSpawn(toolUseId, input, event.timestamp, isCodexSubagentSpawnTool(block.name, input));
             }
             else if (block.type === 'tool_result') {
                 const toolUseId = block.tool_use_id;
                 if (!toolUseId)
                     continue;
-                this.completeSubagent(toolUseId, event.timestamp);
+                this.resolveSubagentResult(toolUseId, block.content ?? block.output, block.is_error === true, event.timestamp);
             }
         }
     }
@@ -1522,23 +1676,10 @@ export class EventAggregator {
     // ═══════════════════════════════════════════════════════════════════════
     extractSubagentFromFollowEvent(event) {
         const raw = event.raw;
-        if (event.type === 'tool_use' && event.toolName === 'Task') {
+        if (event.type === 'tool_use' && isSubagentSpawnTool(event.toolName, raw?.input)) {
             if (!raw?.input)
                 return;
-            const input = raw.input;
-            const toolUseId = raw.id || '';
-            const info = {
-                id: toolUseId,
-                description: input.description || 'Unknown task',
-                subagentType: input.subagent_type || input.subagentType || 'general',
-                spawnTime: event.timestamp,
-                status: 'running',
-            };
-            const idx = this.subagents.length;
-            this.subagents.push(info);
-            if (toolUseId) {
-                this.pendingSubagents.set(toolUseId, idx);
-            }
+            this.trackSubagentSpawn(raw.id || '', raw.input, event.timestamp, isCodexSubagentSpawnTool(event.toolName, raw.input));
         }
         else if (event.type === 'tool_result') {
             if (!raw)
@@ -1546,22 +1687,374 @@ export class EventAggregator {
             const toolUseId = raw.tool_use_id;
             if (!toolUseId)
                 return;
-            this.completeSubagent(toolUseId, event.timestamp);
+            this.resolveSubagentResult(toolUseId, raw.content, raw.is_error === true, event.timestamp);
+        }
+        else if (event.type === 'user' && raw?.type === 'user') {
+            // Claude Code delivers most task notifications as their own user line.
+            const notification = taskNotificationFromEvent(raw);
+            if (notification)
+                this.applyTaskNotification(notification, event.timestamp);
+        }
+    }
+    trackSubagentSpawn(toolUseId, input, timestamp, codex = false) {
+        const spawn = spawnFields(input);
+        const info = {
+            id: toolUseId,
+            description: spawn.description ?? 'Unknown task',
+            subagentType: spawn.subagentType ?? (codex ? 'default' : 'general'),
+            spawnTime: timestamp,
+            status: 'running',
+        };
+        const idx = this.subagents.length;
+        this.subagents.push(info);
+        if (toolUseId) {
+            this.pendingSubagents.set(toolUseId, idx);
+            if (codex)
+                this.pendingCodexSpawns.add(toolUseId);
         }
     }
-    completeSubagent(toolUseId, timestamp) {
+    /**
+     * The spawning tool call's result. A foreground agent ends here; a
+     * background launch only reports the agent id (a Codex spawn, its agent
+     * path), and the agent keeps running until a notification or another
+     * record says it ended.
+     */
+    resolveSubagentResult(toolUseId, content, isError, timestamp) {
         const idx = this.pendingSubagents.get(toolUseId);
         if (idx === undefined)
             return;
-        this.pendingSubagents.delete(toolUseId);
+        const codex = this.pendingCodexSpawns.delete(toolUseId);
+        if (spawnResultKind(codex, content, isError) === 'launch') {
+            const launch = parseCodexSpawnLaunch(content) ?? parseAsyncAgentLaunch(content) ?? {};
+            this.markBackgroundLaunch(idx, launch);
+            return;
+        }
+        this.completeSubagent(toolUseId, timestamp, isError ? 'failed' : 'completed');
+    }
+    markBackgroundLaunch(idx, launch) {
         const agent = this.subagents[idx];
+        this.pendingSubagents.delete(agent.id);
+        agent.background = true;
+        if (launch.agentId)
+            agent.agentId = launch.agentId;
+        if (launch.agentPath && !agent.agentPath)
+            agent.agentPath = launch.agentPath;
+    }
+    completeSubagent(toolUseId, timestamp, outcome = 'completed') {
+        const idx = this.pendingSubagents.get(toolUseId);
+        if (idx === undefined)
+            return;
+        this.finishSubagent(this.subagents[idx], timestamp, outcome);
+    }
+    finishSubagent(agent, timestamp, outcome, settledBy) {
+        this.pendingSubagents.delete(agent.id);
+        this.pendingCodexSpawns.delete(agent.id);
         agent.status = 'completed';
         agent.completionTime = timestamp;
+        agent.outcome = outcome;
+        if (settledBy)
+            agent.settledBy = settledBy;
+        else
+            delete agent.settledBy;
         const start = new Date(agent.spawnTime).getTime();
         const end = new Date(timestamp).getTime();
         if (!isNaN(start) && !isNaN(end) && end >= start) {
             agent.durationMs = end - start;
         }
+        else {
+            delete agent.durationMs;
+        }
+    }
+    /** Puts a settled agent back to running (it resumed). */
+    reopenSubagent(agent, timestamp) {
+        this.pendingSubagents.delete(agent.id);
+        agent.status = 'running';
+        delete agent.completionTime;
+        delete agent.durationMs;
+        delete agent.outcome;
+        delete agent.settledBy;
+        this.settleAgentTask(agent.id, null, timestamp);
+    }
+    /**
+     * Settles a lifecycle that is still running (and its task card). Agents
+     * already settled are left alone: a stop notice or status can name agents
+     * that finished earlier.
+     */
+    settleRunningSubagent(agent, timestamp, outcome, settledBy) {
+        if (agent.status !== 'running')
+            return false;
+        this.finishSubagent(agent, timestamp, outcome, settledBy);
+        this.settleAgentTask(agent.id, outcome, timestamp);
+        return true;
+    }
+    /**
+     * Moves an agent's task card with its lifecycle: `null` back to in
+     * progress, a failure to deleted, any other outcome to completed.
+     */
+    settleAgentTask(toolUseId, outcome, timestamp) {
+        const agentTask = toolUseId ? this.tasks.get(`agent-${toolUseId}`) : undefined;
+        if (!agentTask?.isSubagent)
+            return;
+        agentTask.status =
+            outcome === null ? 'in_progress' : outcome === 'failed' ? 'deleted' : 'completed';
+        agentTask.updatedAt = new Date(timestamp);
+    }
+    /**
+     * Applies a background task's notification to the subagent it reports on,
+     * matched by the spawning tool_use id (or by agent id when the notification
+     * has none). The latest notification wins: an interim one ("waiting on its
+     * own background work") keeps or puts the agent back to running, a final one
+     * completes it. Notifications for background shell tasks match nothing.
+     */
+    applyTaskNotification(notification, timestamp) {
+        const agent = this.findNotifiedSubagent(notification);
+        const toolUseId = agent?.id || notification.toolUseId;
+        const outcome = taskNotificationOutcome(notification.status);
+        if (agent) {
+            agent.background = true;
+            if (!agent.agentId)
+                agent.agentId = notification.taskId;
+            if (notification.interim) {
+                this.pendingSubagents.delete(agent.id);
+                agent.status = 'running';
+                delete agent.completionTime;
+                delete agent.durationMs;
+                delete agent.outcome;
+                delete agent.settledBy;
+            }
+            else {
+                this.finishSubagent(agent, timestamp, outcome, 'notification');
+            }
+        }
+        this.settleAgentTask(toolUseId, notification.interim ? null : outcome, timestamp);
+    }
+    findNotifiedSubagent(notification) {
+        const { toolUseId, taskId } = notification;
+        for (let i = this.subagents.length - 1; i >= 0; i--) {
+            if (toolUseId && this.subagents[i].id === toolUseId)
+                return this.subagents[i];
+        }
+        for (let i = this.subagents.length - 1; i >= 0; i--) {
+            if (this.subagents[i].agentId === taskId)
+                return this.subagents[i];
+        }
+        return undefined;
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // Subagent settling: evidence, stop markers, task statuses, Codex records
+    // ═══════════════════════════════════════════════════════════════════════
+    /**
+     * Applies host evidence about a subagent (Claude Code's meta flags):
+     * `stoppedByUser` settles a running agent as `stopped`, `finished` as
+     * `completed` (`settledBy: 'meta'`). Agents already settled some other way
+     * keep their outcome; `finished: false` reopens an agent that only meta
+     * settled. Matches by `toolUseId`, then `agentId` (the newest such agent),
+     * and records the agent id when matched by tool_use id.
+     *
+     * @param timestamp ISO time to record as the completion (the agent's last
+     *   activity, when the host knows it)
+     * @returns Whether a lifecycle changed
+     */
+    applySubagentEvidence(evidence, timestamp) {
+        const agent = this.findSubagent(evidence.toolUseId, evidence.agentId);
+        if (!agent)
+            return false;
+        let changed = false;
+        if (evidence.agentId && !agent.agentId) {
+            agent.agentId = evidence.agentId;
+            changed = true;
+        }
+        if (agent.status === 'running') {
+            const outcome = evidence.stoppedByUser
+                ? 'stopped'
+                : evidence.finished
+                    ? 'completed'
+                    : null;
+            if (outcome)
+                changed = this.settleRunningSubagent(agent, timestamp, outcome, 'meta') || changed;
+        }
+        else if (agent.settledBy === 'meta' &&
+            evidence.finished === false &&
+            evidence.stoppedByUser !== true) {
+            this.reopenSubagent(agent, timestamp);
+            changed = true;
+        }
+        return changed;
+    }
+    /** The newest lifecycle with this spawning tool_use id, else with this agent id. */
+    findSubagent(toolUseId, agentId) {
+        if (toolUseId) {
+            for (let i = this.subagents.length - 1; i >= 0; i--) {
+                if (this.subagents[i].id === toolUseId)
+                    return this.subagents[i];
+            }
+        }
+        if (agentId) {
+            for (let i = this.subagents.length - 1; i >= 0; i--) {
+                if (this.subagents[i].agentId === agentId)
+                    return this.subagents[i];
+            }
+        }
+        return undefined;
+    }
+    /** `agents_killed`: the user killed every running background agent. */
+    applyAgentsKilled(timestamp) {
+        let settled = 0;
+        for (const agent of this.subagents) {
+            if (!agent.background)
+                continue;
+            if (this.settleRunningSubagent(agent, timestamp, 'stopped', 'stop-marker'))
+                settled++;
+        }
+        if (settled > 0)
+            this.addSubagentTimeline(timestamp, describeAgentsStopped(null));
+    }
+    /**
+     * "N background agents were stopped by the user: "A", "B"": settles the
+     * running agents with those descriptions, the newest first for repeats.
+     */
+    applyAgentsStopped(notice, timestamp) {
+        const taken = new Set();
+        for (const description of notice.descriptions) {
+            for (let i = this.subagents.length - 1; i >= 0; i--) {
+                const agent = this.subagents[i];
+                if (taken.has(agent) || agent.status !== 'running')
+                    continue;
+                if (agent.description.trim() !== description)
+                    continue;
+                taken.add(agent);
+                this.settleRunningSubagent(agent, timestamp, 'stopped', 'stop-marker');
+                break;
+            }
+        }
+        this.addSubagentTimeline(timestamp, describeAgentsStopped(notice));
+    }
+    /** A background agent's final `task_status` attachment, matched by agent id. */
+    applyTaskStatus(status, timestamp) {
+        if (!isFinalTaskStatus(status.status))
+            return;
+        const agent = this.findSubagent(undefined, status.taskId);
+        if (!agent)
+            return;
+        if (this.settleRunningSubagent(agent, timestamp, taskNotificationOutcome(status.status), 'task-status')) {
+            this.addSubagentTimeline(timestamp, describeTaskStatus(status), agent.id);
+        }
+    }
+    /**
+     * A Codex subagent lifecycle record: `started` links the spawn to its child
+     * thread; `completed` (a child turn finished) and `final-answer` (the
+     * child's report, matched by its agent path) complete it; `interacted`
+     * after `followup_task` puts it back to running (a `send_message` does
+     * not: it does not start a turn); `interrupted` (`interrupt_agent`) settles
+     * it as `stopped`, since the child keeps its thread and a follow-up can
+     * run it again, like a user stop rather than a kill.
+     */
+    applySubagentActivity(activity, timestamp) {
+        const byThread = () => this.findSubagent(undefined, activity.agentThreadId) ??
+            this.findSubagentByPath(activity.agentPath);
+        let agent;
+        switch (activity.kind) {
+            case 'started': {
+                agent = this.findSubagent(activity.callId, undefined);
+                if (!agent)
+                    break;
+                agent.background = true;
+                if (activity.agentThreadId)
+                    agent.agentId = activity.agentThreadId;
+                if (activity.agentPath)
+                    agent.agentPath = activity.agentPath;
+                break;
+            }
+            case 'completed':
+                agent = byThread();
+                if (agent)
+                    this.settleRunningSubagent(agent, timestamp, 'completed', 'notification');
+                break;
+            case 'final-answer':
+                agent = this.findSubagentByPath(activity.agentPath, true);
+                if (agent)
+                    this.settleRunningSubagent(agent, timestamp, 'completed', 'notification');
+                break;
+            case 'interacted':
+                agent = byThread();
+                if (agent && activity.tool === 'followup_task' && agent.status === 'completed') {
+                    this.reopenSubagent(agent, timestamp);
+                }
+                break;
+            case 'interrupted':
+                agent = byThread();
+                if (agent)
+                    this.settleRunningSubagent(agent, timestamp, 'stopped', 'stop-marker');
+                break;
+        }
+        this.addSubagentTimeline(timestamp, describeSubagentActivity(activity), agent?.id);
+    }
+    /** The newest lifecycle with this Codex agent path (with `runningFirst`, a running one first). */
+    findSubagentByPath(agentPath, runningFirst = false) {
+        if (!agentPath)
+            return undefined;
+        let fallback;
+        for (let i = this.subagents.length - 1; i >= 0; i--) {
+            const agent = this.subagents[i];
+            if (agent.agentPath !== agentPath)
+                continue;
+            if (!runningFirst || agent.status === 'running')
+                return agent;
+            fallback ??= agent;
+        }
+        return fallback;
+    }
+    applySubagentFollowRecord(record, timestamp) {
+        switch (record.kind) {
+            case 'notification':
+                this.applyTaskNotification(record.notification, timestamp);
+                this.addTaskNotificationTimeline(timestamp, record.notification);
+                break;
+            case 'stopped':
+                this.applyAgentsStopped(record.notice, timestamp);
+                break;
+            case 'task-status':
+                this.applyTaskStatus(record.status, timestamp);
+                break;
+            case 'activity':
+                this.applySubagentActivity(record.activity, timestamp);
+                break;
+            case 'agents-killed':
+                this.applyAgentsKilled(timestamp);
+                break;
+            case 'unreadable':
+                break;
+        }
+    }
+    addSubagentTimeline(timestamp, description, toolUseId) {
+        const text = description.length > 200 ? description.substring(0, 197) + '...' : description;
+        this.timeline.push({
+            type: 'tool_result',
+            timestamp,
+            description: text,
+            noiseLevel: 'system',
+            messageClassification: 'system',
+            ...(toolUseId ? { metadata: { toolUseId } } : {}),
+        });
+        if (this.timeline.length > this.timelineCap) {
+            this.timeline.shift();
+        }
+    }
+    addTaskNotificationTimeline(timestamp, notification) {
+        let description = notification.summary ?? `Background task ${notification.status ?? 'finished'}`;
+        if (description.length > 200)
+            description = description.substring(0, 197) + '...';
+        this.timeline.push({
+            type: 'tool_result',
+            timestamp,
+            description,
+            noiseLevel: 'system',
+            messageClassification: 'system',
+            ...(notification.toolUseId ? { metadata: { toolUseId: notification.toolUseId } } : {}),
+        });
+        if (this.timeline.length > this.timelineCap) {
+            this.timeline.shift();
+        }
     }
     // ═══════════════════════════════════════════════════════════════════════
     // Private: Plan Extraction from SessionEvent
@@ -1797,9 +2290,9 @@ export class EventAggregator {
     // Private: Permission Mode
     // ═══════════════════════════════════════════════════════════════════════
     trackPermissionMode(event) {
-        if (!event.permissionMode)
+        const mode = asPermissionMode(event.permissionMode);
+        if (!mode)
             return;
-        const mode = event.permissionMode;
         if (mode !== this.currentPermissionMode) {
             this.permissionModeHistory.push({
                 timestamp: event.timestamp,