sidekick-shared 0.29.1 → 0.30.0

package/dist/aggregation/EventAggregator.js

@@ -22,6 +22,7 @@ const HeatmapTracker_1 = require("./HeatmapTracker");
 const PatternExtractor_1 = require("./PatternExtractor");
 const errorTaxonomy_1 = require("../extractors/errorTaxonomy");
 const tokenEstimation_1 = require("../tokenEstimation");
+const subagentActivity_1 = require("../subagentActivity");
 const subagentSpawn_1 = require("../subagentSpawn");
 const usageNormalization_1 = require("../usageNormalization");
 // ── Defaults ──
@@ -31,8 +32,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. */
-exports.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`).
+ */
+exports.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 ──
@@ -51,6 +70,62 @@ function taskNotificationFromAttachmentFollowEvent(event) {
     const asEvent = raw;
     return (0, subagentSpawn_1.isTaskNotificationSystemEvent)(asEvent) ? (0, subagentSpawn_1.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 = (0, subagentSpawn_1.taskNotificationPromptFromAttachment)(raw);
+    const notice = prompt !== null ? (0, subagentSpawn_1.parseAgentsStoppedNotice)(prompt) : (0, subagentSpawn_1.agentsStoppedNoticeFromEvent)(asEvent);
+    if (notice)
+        return { kind: 'stopped', notice };
+    if (prompt !== null || (0, subagentSpawn_1.isTaskNotificationSystemEvent)(asEvent)) {
+        // A notification this release cannot read: still bookkeeping.
+        return { kind: 'unreadable' };
+    }
+    const status = (0, subagentSpawn_1.taskStatusFromAttachment)(raw) ?? (0, subagentSpawn_1.taskStatusFromEvent)(asEvent);
+    if (status)
+        return { kind: 'task-status', status };
+    if ((0, subagentActivity_1.isSubagentActivitySystemEvent)(asEvent)) {
+        const activity = (0, subagentActivity_1.subagentActivityFromEvent)(asEvent);
+        return activity ? { kind: 'activity', activity } : { kind: 'unreadable' };
+    }
+    if ((0, subagentSpawn_1.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 ((0, subagentSpawn_1.parseCodexSpawnLaunch)(content))
+        return 'launch';
+    if (codex)
+        return isError ? 'end' : 'launch';
+    return !isError && (0, subagentSpawn_1.parseAsyncAgentLaunch)(content) ? 'launch' : 'end';
+}
 // ── Todo dependency parsing ──
 /**
  * Parses dependency references from a todo item's content text.
@@ -136,6 +211,8 @@ 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;
@@ -198,8 +275,32 @@ 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 = (0, subagentSpawn_1.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 ((0, subagentSpawn_1.isTaskStatusSystemEvent)(event)) {
+            const status = (0, subagentSpawn_1.taskStatusFromEvent)(event);
+            if (status)
+                this.applyTaskStatus(status, event.timestamp);
+            return;
+        }
+        if ((0, subagentActivity_1.isSubagentActivitySystemEvent)(event)) {
+            const activity = (0, subagentActivity_1.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 ((0, subagentSpawn_1.isAgentsKilledSystemEvent)(event))
+            this.applyAgentsKilled(event.timestamp);
         // 1. Increment counters, capture timestamps
         this.eventCount++;
         if (!this.sessionStartTime) {
@@ -265,12 +366,13 @@ 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;
             }
         }
@@ -280,6 +382,8 @@ 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;
@@ -411,6 +515,10 @@ 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 })) }
@@ -507,6 +615,7 @@ class EventAggregator {
         this.activeTaskId = null;
         this.subagents = [];
         this.pendingSubagents.clear();
+        this.pendingCodexSpawns.clear();
         this.planExtractor.reset();
         this.planState = null;
         this.planEnteredAt = undefined;
@@ -640,7 +749,7 @@ 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]
             : [];
@@ -667,6 +776,7 @@ 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.
@@ -1153,7 +1263,7 @@ class EventAggregator {
                 else if (name === 'UpdatePlan') {
                     this.handleUpdatePlan(input, new Date(event.timestamp));
                 }
-                else if ((0, subagentSpawn_1.isSubagentSpawnTool)(name) && toolUseId) {
+                else if ((0, subagentSpawn_1.isSubagentSpawnTool)(name, input) && toolUseId) {
                     this.handleAgentSpawn(toolUseId, input, new Date(event.timestamp));
                 }
             }
@@ -1197,7 +1307,7 @@ class EventAggregator {
             else if (event.toolName === 'UpdatePlan') {
                 this.handleUpdatePlan(input, new Date(event.timestamp));
             }
-            else if ((0, subagentSpawn_1.isSubagentSpawnTool)(event.toolName) && toolUseId) {
+            else if ((0, subagentSpawn_1.isSubagentSpawnTool)(event.toolName, input) && toolUseId) {
                 this.handleAgentSpawn(toolUseId, input, new Date(event.timestamp));
             }
         }
@@ -1496,8 +1606,9 @@ 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,
@@ -1520,8 +1631,9 @@ class EventAggregator {
         if (!agentTask)
             return;
         // A background launch returns at once; its task notification finishes it.
-        if (!isError && (0, subagentSpawn_1.parseAsyncAgentLaunch)(content))
+        if (spawnResultKind(this.pendingCodexSpawns.has(toolUseId), content, isError) === 'launch') {
             return;
+        }
         agentTask.status = isError ? 'deleted' : 'completed';
         agentTask.updatedAt = new Date(timestamp);
     }
@@ -1548,12 +1660,12 @@ class EventAggregator {
         if (!Array.isArray(content))
             return;
         for (const block of content) {
-            if (block.type === 'tool_use' && (0, subagentSpawn_1.isSubagentSpawnTool)(block.name)) {
+            if (block.type === 'tool_use' && (0, subagentSpawn_1.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, (0, subagentSpawn_1.isCodexSubagentSpawnTool)(block.name, input));
             }
             else if (block.type === 'tool_result') {
                 const toolUseId = block.tool_use_id;
@@ -1568,10 +1680,10 @@ class EventAggregator {
     // ═══════════════════════════════════════════════════════════════════════
     extractSubagentFromFollowEvent(event) {
         const raw = event.raw;
-        if (event.type === 'tool_use' && (0, subagentSpawn_1.isSubagentSpawnTool)(event.toolName)) {
+        if (event.type === 'tool_use' && (0, subagentSpawn_1.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, (0, subagentSpawn_1.isCodexSubagentSpawnTool)(event.toolName, raw.input));
         }
         else if (event.type === 'tool_result') {
             if (!raw)
@@ -1588,11 +1700,12 @@ 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',
         };
@@ -1600,19 +1713,23 @@ 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 : (0, subagentSpawn_1.parseAsyncAgentLaunch)(content);
-        if (launch) {
+        const codex = this.pendingCodexSpawns.delete(toolUseId);
+        if (spawnResultKind(codex, content, isError) === 'launch') {
+            const launch = (0, subagentSpawn_1.parseCodexSpawnLaunch)(content) ?? (0, subagentSpawn_1.parseAsyncAgentLaunch)(content) ?? {};
             this.markBackgroundLaunch(idx, launch);
             return;
         }
@@ -1624,6 +1741,8 @@ 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);
@@ -1631,16 +1750,58 @@ 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,
@@ -1663,20 +1824,13 @@ 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;
@@ -1690,6 +1844,206 @@ 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, (0, subagentSpawn_1.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, (0, subagentSpawn_1.describeAgentsStopped)(notice));
+    }
+    /** A background agent's final `task_status` attachment, matched by agent id. */
+    applyTaskStatus(status, timestamp) {
+        if (!(0, subagentSpawn_1.isFinalTaskStatus)(status.status))
+            return;
+        const agent = this.findSubagent(undefined, status.taskId);
+        if (!agent)
+            return;
+        if (this.settleRunningSubagent(agent, timestamp, (0, subagentSpawn_1.taskNotificationOutcome)(status.status), 'task-status')) {
+            this.addSubagentTimeline(timestamp, (0, subagentSpawn_1.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, (0, subagentActivity_1.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)
@@ -1940,9 +2294,9 @@ 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/aggregation/types.d.ts

@@ -119,9 +119,23 @@ export interface BurnRateInfo {
 }
 /** How a subagent ended: a failed spawn, or a background agent's notification status. */
 export type SubagentOutcome = 'completed' | 'failed' | 'killed' | 'stopped';
+/**
+ * What settled a background subagent, when something other than its spawn's
+ * own tool result did:
+ *
+ * - `notification`: its final task notification (Claude Code), or a Codex
+ *   `SubAgentActivity` `completed` record or `FINAL_ANSWER` report.
+ * - `meta`: the host's evidence from Claude Code's `agent-<id>.meta.json`
+ *   (`finished`, `stoppedByUser`), via `EventAggregator.applySubagentEvidence()`.
+ * - `stop-marker`: an in-stream stop: Claude Code's `agents_killed` system
+ *   line or its "background agents were stopped by the user" notice, or a
+ *   Codex `interrupt_agent` record.
+ * - `task-status`: a Claude Code `task_status` attachment with a final status.
+ */
+export type SubagentSettledBy = 'notification' | 'meta' | 'stop-marker' | 'task-status';
 /** Subagent lifecycle info (for tracking spawn/completion from tool events). */
 export interface SubagentLifecycle {
-    /** The spawning tool_use id (`Agent` / `Task`). */
+    /** The spawning tool_use id (`Agent` / `Task`, or Codex `spawn_agent`). */
     id: string;
     description: string;
     subagentType: string;
@@ -133,12 +147,22 @@ export interface SubagentLifecycle {
      */
     status: 'running' | 'completed';
     durationMs?: number;
-    /** Claude Code's agent id (the `agent-<id>.jsonl` transcript name), once known. */
+    /**
+     * The agent's id, once known: Claude Code's agent id (the `agent-<id>.jsonl`
+     * transcript name), or the Codex child thread id (its rollout's session id).
+     */
     agentId?: string;
+    /** Codex: the child's agent path (e.g. `/root/review_builder`), once known. */
+    agentPath?: string;
     /** The agent was launched in the background (its spawn returned at once). */
     background?: boolean;
     /** How the agent ended, once `status` is `completed`. */
     outcome?: SubagentOutcome;
+    /**
+     * What settled a background agent (see {@link SubagentSettledBy}); absent
+     * while it runs and when its spawn's own result settled it.
+     */
+    settledBy?: SubagentSettledBy;
 }
 /** Frequency entry for tool/word frequency tracking. */
 export interface FrequencyMetric {
@@ -178,7 +202,7 @@ export interface AggregatedMetrics {
     taskState: TaskState;
     subagents: SubagentLifecycle[];
     plan: PlanState | null;
-    /** Current permission mode (default | acceptEdits | bypassPermissions | plan) */
+    /** Current permission mode (default | acceptEdits | bypassPermissions | plan | auto | dontAsk) */
     permissionMode: PermissionMode | null;
     /** History of permission mode changes */
     permissionModeHistory: PermissionModeChange[];