sidekick-shared 0.29.1 → 0.30.0

package/dist/esm/aggregation/EventAggregator.js

@@ -18,7 +18,8 @@ import { HeatmapTracker } from './HeatmapTracker';
 import { PatternExtractor } from './PatternExtractor';
 import { categorizeError } from '../extractors/errorTaxonomy';
 import { estimateTextTokens } from '../tokenEstimation';
-import { isSubagentSpawnTool, isTaskNotificationSystemEvent, parseAsyncAgentLaunch, parseTaskNotification, taskNotificationFromEvent, taskNotificationOutcome, taskNotificationPromptFromAttachment, } from '../subagentSpawn';
+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;
@@ -27,8 +28,26 @@ 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 ──
@@ -47,6 +66,62 @@ function taskNotificationFromAttachmentFollowEvent(event) {
     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.
@@ -132,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;
@@ -194,8 +271,32 @@ export class EventAggregator {
                 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) {
@@ -261,12 +362,13 @@ export class EventAggregator {
     // processFollowEvent — adapter for CLI FollowEvent format
     // ═══════════════════════════════════════════════════════════════════════
     processFollowEvent(event) {
-        // A mid-turn task-notification attachment, like its SessionEvent form above.
+        // 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 notification = taskNotificationFromAttachmentFollowEvent(event);
-            if (notification) {
-                this.applyTaskNotification(notification, event.timestamp);
-                this.addTaskNotificationTimeline(event.timestamp, notification);
+            const record = subagentRecordFromFollowEvent(event);
+            if (record) {
+                this.applySubagentFollowRecord(record, event.timestamp);
                 return;
             }
         }
@@ -276,6 +378,8 @@ export class EventAggregator {
             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;
@@ -407,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 })) }
@@ -503,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;
@@ -636,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]
             : [];
@@ -663,6 +772,7 @@ 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.
@@ -1149,7 +1259,7 @@ export class EventAggregator {
                 else if (name === 'UpdatePlan') {
                     this.handleUpdatePlan(input, new Date(event.timestamp));
                 }
-                else if (isSubagentSpawnTool(name) && toolUseId) {
+                else if (isSubagentSpawnTool(name, input) && toolUseId) {
                     this.handleAgentSpawn(toolUseId, input, new Date(event.timestamp));
                 }
             }
@@ -1193,7 +1303,7 @@ export class EventAggregator {
             else if (event.toolName === 'UpdatePlan') {
                 this.handleUpdatePlan(input, new Date(event.timestamp));
             }
-            else if (isSubagentSpawnTool(event.toolName) && toolUseId) {
+            else if (isSubagentSpawnTool(event.toolName, input) && toolUseId) {
                 this.handleAgentSpawn(toolUseId, input, new Date(event.timestamp));
             }
         }
@@ -1492,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,
@@ -1516,8 +1627,9 @@ export class EventAggregator {
         if (!agentTask)
             return;
         // A background launch returns at once; its task notification finishes it.
-        if (!isError && parseAsyncAgentLaunch(content))
+        if (spawnResultKind(this.pendingCodexSpawns.has(toolUseId), content, isError) === 'launch') {
             return;
+        }
         agentTask.status = isError ? 'deleted' : 'completed';
         agentTask.updatedAt = new Date(timestamp);
     }
@@ -1544,12 +1656,12 @@ export class EventAggregator {
         if (!Array.isArray(content))
             return;
         for (const block of content) {
-            if (block.type === 'tool_use' && isSubagentSpawnTool(block.name)) {
+            if (block.type === 'tool_use' && isSubagentSpawnTool(block.name, block.input)) {
                 const input = block.input;
                 const toolUseId = block.id;
                 if (!input || !toolUseId)
                     continue;
-                this.trackSubagentSpawn(toolUseId, input, event.timestamp);
+                this.trackSubagentSpawn(toolUseId, input, event.timestamp, isCodexSubagentSpawnTool(block.name, input));
             }
             else if (block.type === 'tool_result') {
                 const toolUseId = block.tool_use_id;
@@ -1564,10 +1676,10 @@ export class EventAggregator {
     // ═══════════════════════════════════════════════════════════════════════
     extractSubagentFromFollowEvent(event) {
         const raw = event.raw;
-        if (event.type === 'tool_use' && isSubagentSpawnTool(event.toolName)) {
+        if (event.type === 'tool_use' && isSubagentSpawnTool(event.toolName, raw?.input)) {
             if (!raw?.input)
                 return;
-            this.trackSubagentSpawn(raw.id || '', raw.input, event.timestamp);
+            this.trackSubagentSpawn(raw.id || '', raw.input, event.timestamp, isCodexSubagentSpawnTool(event.toolName, raw.input));
         }
         else if (event.type === 'tool_result') {
             if (!raw)
@@ -1584,11 +1696,12 @@ export class EventAggregator {
                 this.applyTaskNotification(notification, event.timestamp);
         }
     }
-    trackSubagentSpawn(toolUseId, input, timestamp) {
+    trackSubagentSpawn(toolUseId, input, timestamp, codex = false) {
+        const spawn = spawnFields(input);
         const info = {
             id: toolUseId,
-            description: input.description || 'Unknown task',
-            subagentType: input.subagent_type || input.subagentType || 'general',
+            description: spawn.description ?? 'Unknown task',
+            subagentType: spawn.subagentType ?? (codex ? 'default' : 'general'),
             spawnTime: timestamp,
             status: 'running',
         };
@@ -1596,19 +1709,23 @@ export class EventAggregator {
         this.subagents.push(info);
         if (toolUseId) {
             this.pendingSubagents.set(toolUseId, idx);
+            if (codex)
+                this.pendingCodexSpawns.add(toolUseId);
         }
     }
     /**
      * The spawning tool call's result. A foreground agent ends here; a
-     * background launch only reports the agent id, and the agent keeps running
-     * until its task notification arrives.
+     * 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;
-        const launch = isError ? null : parseAsyncAgentLaunch(content);
-        if (launch) {
+        const codex = this.pendingCodexSpawns.delete(toolUseId);
+        if (spawnResultKind(codex, content, isError) === 'launch') {
+            const launch = parseCodexSpawnLaunch(content) ?? parseAsyncAgentLaunch(content) ?? {};
             this.markBackgroundLaunch(idx, launch);
             return;
         }
@@ -1620,6 +1737,8 @@ export class EventAggregator {
         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);
@@ -1627,16 +1746,58 @@ export class EventAggregator {
             return;
         this.finishSubagent(this.subagents[idx], timestamp, outcome);
     }
-    finishSubagent(agent, 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,
@@ -1659,20 +1820,13 @@ export class EventAggregator {
                 delete agent.completionTime;
                 delete agent.durationMs;
                 delete agent.outcome;
+                delete agent.settledBy;
             }
             else {
-                this.finishSubagent(agent, timestamp, outcome);
+                this.finishSubagent(agent, timestamp, outcome, 'notification');
             }
         }
-        const agentTask = toolUseId ? this.tasks.get(`agent-${toolUseId}`) : undefined;
-        if (agentTask?.isSubagent) {
-            agentTask.status = notification.interim
-                ? 'in_progress'
-                : outcome === 'failed'
-                    ? 'deleted'
-                    : 'completed';
-            agentTask.updatedAt = new Date(timestamp);
-        }
+        this.settleAgentTask(toolUseId, notification.interim ? null : outcome, timestamp);
     }
     findNotifiedSubagent(notification) {
         const { toolUseId, taskId } = notification;
@@ -1686,6 +1840,206 @@ export class EventAggregator {
         }
         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)
@@ -1936,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,

package/dist/esm/browser.js

@@ -17,7 +17,8 @@ export { addLocalDays, formatDurationMs, formatLocalDateKey, formatTokenCount, p
 export { parseMcpToolName } from './parsers/mcpToolName';
 export { buildSessionContextSnapshot, calculateSessionContextPressure, createSessionContextProjector, } from './context/sessionContext';
 export { ACCOUNT_PROVIDER_IDS, MODEL_PROVIDER_IDS, QUOTA_PROVIDER_IDS, RUNTIME_QUOTA_PROVIDER_IDS, SESSION_PROVIDER_IDS, } from './providerIds';
-export { SUBAGENT_SPAWN_TOOL_NAMES, isSubagentSpawnTool, isTaskNotificationSystemEvent, parseTaskNotification, taskNotificationFromEvent, } from './subagentSpawn';
+export { SUBAGENT_SPAWN_TOOL_NAMES, agentsStoppedNoticeFromEvent, isAgentsKilledSystemEvent, isCodexSubagentSpawnTool, isSubagentSpawnTool, isTaskNotificationSystemEvent, isTaskStatusSystemEvent, parseAgentsStoppedNotice, parseCodexSpawnLaunch, parseTaskNotification, taskNotificationFromEvent, taskStatusFromAttachment, taskStatusFromEvent, } from './subagentSpawn';
+export { SUBAGENT_PARENT_IDLE_ENDED_MS, SUBAGENT_UNREPORTED_QUIET_MS, resolveSubagentDisplayState, subagentDisplayLabel, } from './subagentDisplayState';
 export { assistantTurnEventsFromSessionEvents, extractTurnSubagents, isAssistantTurnSubagentTool, reasoningSummary, segmentAssistantTurn, } from './turns/assistantTurn';
 export { parseModelId, getModelPricing, resolveModelPricing, getModelInfo, calculateCost, calculateCostWithPricing, calculateCostWithProvenance, mergeCostSources, shortModelName, getModelDisplayInfo, compareModelIds, sortModelIds, formatCost, canonicalModelId, isMovingModelAlias, registerModelPricing, clearRegisteredModelPricing, getPricingCatalogInfo, costSourceFromPricingProvenance, mergeCostComponents, } from './modelInfo';
 export { exportResolvedModelCatalog, importResolvedModelCatalog, registerModelAlias, resolveModelAlias, RESOLVED_MODEL_CATALOG_SCHEMA_VERSION, } from './modelCatalog';
@@ -31,6 +32,7 @@ export { isAggregateCodexLimit } from './types/codex';
 // Codex rollout parsing (pure: no filesystem access)
 export { CodexRolloutParser, DEFAULT_MAX_TRACKED_TOOL_CALLS, extractPatchFilePaths, normalizeCodexToolName, normalizeCodexToolInput, resolveCodexCallUsage, } from './parsers/codexParser';
 export { codexRolloutOrigin, codexSpawnParentFromSource } from './parsers/codexRolloutOrigin';
+export { SUBAGENT_ACTIVITY_BLOCK_TYPE, SUBAGENT_ACTIVITY_ORIGIN_KIND, describeSubagentActivity, isSubagentActivitySystemEvent, parseCodexAgentMessageText, subagentActivityFromEvent, } from './subagentActivity';
 export { HUMAN_CLAUDE_ENTRYPOINTS, HUMAN_CODEX_SOURCES, humanPromptText, isHumanPrompt, } from './humanPrompt';
 export { renderHandoffUrlTemplate } from './handoffUrl';
 // Tool categories across providers

package/dist/esm/context/sessionContext.js

@@ -8,7 +8,8 @@ import { EventAggregator } from '../aggregation/EventAggregator';
 import { getModelContextWindowSize } from '../modelContext';
 import { parseMcpToolName } from '../parsers/mcpToolName';
 import { estimateTextTokens } from '../tokenEstimation';
-import { isTaskNotificationSystemEvent } from '../subagentSpawn';
+import { isTaskNotificationSystemEvent, isTaskStatusSystemEvent } from '../subagentSpawn';
+import { isSubagentActivitySystemEvent } from '../subagentActivity';
 const DEFAULT_CONTEXT_SOURCE_LIMIT = 200;
 const DEFAULT_SNIPPET_MAX_CHARS = 240;
 const DEFAULT_BODY_MAX_CHARS = 5000;
@@ -207,7 +208,10 @@ function extractSourcesFromEvent(event, state) {
 }
 function extractSystemSource(event, state) {
     // Background-task notices only update subagent lifecycles (like the aggregator).
-    if (isTaskNotificationSystemEvent(event))
+    if (isTaskNotificationSystemEvent(event) || isTaskStatusSystemEvent(event))
+        return;
+    // So are subagent lifecycle records (opt-in Codex parser events).
+    if (isSubagentActivitySystemEvent(event))
         return;
     const message = event.message;
     const text = extractText(message?.content);