sidekick-shared 0.29.0 → 0.29.1

package/dist/parsers/subagentTraceParser.js

@@ -6,10 +6,13 @@
  * (not just stats) for drill-down trace visualization. Applies noise classification
  * and tool summary formatting from the formatters module.
  *
- * Three-phase parent-child linking:
- * 1. Result-based: match toolUseResult.agentId → parent tool_use_id
- * 2. Team summary: parse <teammate-message> XML blocks
- * 3. Positional fallback: timestamp ordering + proximity
+ * Parent-child linking, exact links first:
+ * 1. Meta `parentAgentId` (Claude Code writes it for nested spawns)
+ * 2. The child's spawning tool_use id (meta `toolUseId`) found in another
+ *    trace's `Agent` / `Task` calls
+ * Only traces without that spawn metadata (older Claude Code) fall back to:
+ * 3. Team summary: parse <teammate-message> XML blocks
+ * 4. Positional fallback: timestamp ordering + proximity
  *
  * @module parsers/subagentTraceParser
  */
@@ -55,6 +58,8 @@ const noiseClassifier_1 = require("../formatters/noiseClassifier");
 const claudeUsageDedupe_1 = require("../usage/claudeUsageDedupe");
 const subagentUsage_1 = require("../usage/subagentUsage");
 const subagentScanner_1 = require("./subagentScanner");
+const subagentSpawn_1 = require("../subagentSpawn");
+const ownKey_1 = require("../ownKey");
 // ── Constants ──
 const AGENT_FILE_PATTERN = /^agent-(.+)\.jsonl$/;
 // ── Public API ──
@@ -86,10 +91,8 @@ function scanSubagentTraces(sessionDir, sessionId) {
             if (trace)
                 traces.push(trace);
         }
-        // Link parent-child relationships
-        linkTraces(traces);
-        // Return only top-level traces (those without parents)
-        return traces.filter((t) => !t.parentToolUseId);
+        // Link parent-child relationships; returns the traces with no parent agent.
+        return linkTraces(traces);
     }
     catch {
         return [];
@@ -169,8 +172,8 @@ function parseAgentTrace(filePath, agentId) {
                                 input: block.input || {},
                                 timestamp,
                             });
-                            // Extract agent info from Task tool
-                            if (block.name === 'Task' && block.input) {
+                            // Extract agent info from an Agent/Task spawn
+                            if ((0, subagentSpawn_1.isSubagentSpawnTool)(block.name) && block.input) {
                                 if (block.input.subagent_type && !agentType) {
                                     agentType = String(block.input.subagent_type);
                                 }
@@ -207,6 +210,14 @@ function parseAgentTrace(filePath, agentId) {
             agentId,
             agentType,
             description,
+            filePath,
+            ...(meta.toolUseId
+                ? { spawnToolUseId: meta.toolUseId, parentToolUseId: meta.toolUseId }
+                : {}),
+            ...(meta.parentAgentId ? { parentAgentId: meta.parentAgentId } : {}),
+            ...(meta.requestShape ? { background: meta.requestShape === 'background' } : {}),
+            ...(meta.finished !== undefined ? { finished: meta.finished } : {}),
+            ...(meta.stoppedByUser !== undefined ? { stoppedByUser: meta.stoppedByUser } : {}),
             events,
             children: [],
             stats: {
@@ -231,23 +242,61 @@ function parseAgentTrace(filePath, agentId) {
     }
 }
 // ── Parent-Child Linking ──
+/**
+ * Nests child traces under their parents and returns the traces with no
+ * parent agent. Exact metadata links come first; the heuristics only place
+ * traces Claude Code recorded no spawn metadata for.
+ */
 function linkTraces(traces) {
     const traceById = new Map();
     for (const trace of traces) {
         traceById.set(trace.agentId, trace);
     }
-    // Phase 1: Result-based linking
-    // Look for tool_result events that contain agentId references
+    const parentOf = new Map();
+    const attach = (parent, child) => {
+        if (parent === child || parentOf.has(child))
+            return false;
+        // Never nest an agent under its own descendant (malformed metadata).
+        for (let up = parent; up; up = parentOf.get(up)) {
+            if (up === child)
+                return false;
+        }
+        parentOf.set(child, parent);
+        parent.children.push(child);
+        return true;
+    };
+    // Phase 1: the meta file names the parent agent
+    for (const child of traces) {
+        const parent = child.parentAgentId ? traceById.get(child.parentAgentId) : undefined;
+        if (parent)
+            attach(parent, child);
+    }
+    // Phase 2: the child's spawning call is in another trace
+    const spawnOwner = new Map();
     for (const trace of traces) {
-        for (const traceEvent of trace.events) {
-            const evt = traceEvent.event;
-            if (evt.type === 'tool_use' && evt.tool?.name === 'Task') {
-                // The tool_use_id from this call should appear as a result in the parent
-                // but we can link via timestamp proximity to child traces
-            }
+        for (const id of spawnToolUseIdsOf(trace)) {
+            if (!spawnOwner.has(id))
+                spawnOwner.set(id, trace);
         }
     }
-    // Phase 2: Team summary linking
+    for (const child of traces) {
+        if (parentOf.has(child) || !child.spawnToolUseId)
+            continue;
+        const parent = spawnOwner.get(child.spawnToolUseId);
+        if (parent && attach(parent, child))
+            child.parentAgentId ??= parent.agentId;
+    }
+    // Heuristic links set parentAgentId and, as before, parentToolUseId to the
+    // parent's agent id.
+    const unresolved = (trace) => !parentOf.has(trace) && !trace.spawnToolUseId && !trace.parentAgentId;
+    const linkHeuristically = (parent, child) => {
+        if (!attach(parent, child))
+            return false;
+        child.parentAgentId = parent.agentId;
+        child.parentToolUseId = parent.agentId;
+        return true;
+    };
+    // Phase 3: Team summary linking
     for (const trace of traces) {
         for (const traceEvent of trace.events) {
             const content = traceEvent.event.message?.content;
@@ -255,45 +304,56 @@ function linkTraces(traces) {
                 // Parse teammate agent IDs from XML blocks
                 const matches = content.matchAll(/agent[_-]id['":\s]+([a-f0-9]+)/gi);
                 for (const match of matches) {
-                    const childId = match[1];
-                    const child = traceById.get(childId);
-                    if (child && child !== trace && !child.parentToolUseId) {
-                        child.parentToolUseId = trace.agentId;
-                        trace.children.push(child);
-                    }
+                    const child = traceById.get(match[1]);
+                    if (child && unresolved(child))
+                        linkHeuristically(trace, child);
                 }
             }
         }
     }
-    // Phase 3: Positional fallback — timestamp proximity
+    // Phase 4: Positional fallback — timestamp proximity
     // Traces without parents that fall within another trace's time window
-    const parentless = traces.filter((t) => !t.parentToolUseId);
-    for (const child of parentless) {
+    for (const child of traces.filter(unresolved)) {
         if (!child.stats.startTime)
             continue;
         const childStart = child.stats.startTime.getTime();
-        // Find a trace that was active (Task tool call) right before this child started
+        // Find a top-level trace that spawned an agent right before this child started
         for (const potential of traces) {
-            if (potential === child)
+            if (potential === child || parentOf.has(potential))
                 continue;
-            if (potential.parentToolUseId)
-                continue; // Already linked
             for (const traceEvent of potential.events) {
                 const evt = traceEvent.event;
-                if (evt.type === 'assistant' && evt.tool?.name === 'Task') {
+                if (evt.type === 'assistant' && (0, subagentSpawn_1.isSubagentSpawnTool)(evt.tool?.name)) {
                     const taskTime = new Date(evt.timestamp).getTime();
                     // Within 2 seconds before child start
                     if (taskTime <= childStart && childStart - taskTime < 2000) {
-                        child.parentToolUseId = potential.agentId;
-                        potential.children.push(child);
+                        linkHeuristically(potential, child);
                         break;
                     }
                 }
             }
-            if (child.parentToolUseId)
+            if (parentOf.has(child))
                 break;
         }
     }
+    return traces.filter((trace) => !parentOf.has(trace));
+}
+/** Ids of the `Agent` / `Task` calls a trace made. */
+function spawnToolUseIdsOf(trace) {
+    const ids = [];
+    for (const traceEvent of trace.events) {
+        const content = traceEvent.event.message?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block?.type === 'tool_use' &&
+                typeof block.id === 'string' &&
+                (0, subagentSpawn_1.isSubagentSpawnTool)(block.name)) {
+                ids.push(block.id);
+            }
+        }
+    }
+    return ids;
 }
 // ── Helpers ──
 function rawToSessionEvent(raw) {
@@ -308,7 +368,7 @@ function rawToSessionEvent(raw) {
         tool_result: 'tool_result',
         summary: 'summary',
     };
-    const mappedType = typeMap[type];
+    const mappedType = (0, ownKey_1.ownValue)(typeMap, type);
     if (!mappedType)
         return null;
     const message = raw.message;

package/dist/pricingCatalog.js

@@ -59,6 +59,7 @@ const node_fs_1 = require("node:fs");
 const path = __importStar(require("node:path"));
 const modelContext_1 = require("./modelContext");
 const modelInfo_1 = require("./modelInfo");
+const ownKey_1 = require("./ownKey");
 const paths_1 = require("./paths");
 const atomic_1 = require("./writers/atomic");
 // ── Constants ──
@@ -156,7 +157,7 @@ function normalizeLiteLlmCatalog(raw) {
             continue;
         // Catalog keys use both `provider/model` and bare `model` forms. Record both
         // the raw key and the bare-model form so lookups work regardless of caller.
-        out[key] = pricing;
+        (0, ownKey_1.setOwnValue)(out, key, pricing);
         const bare = stripProviderPrefix(key);
         if (bare && bare !== key && !out[bare]) {
             out[bare] = pricing;
@@ -193,7 +194,7 @@ function normalizeLiteLlmContextWindows(raw) {
         const window = entry.max_input_tokens;
         if (typeof window !== 'number' || !Number.isFinite(window) || window <= 0)
             continue;
-        out[key] = window;
+        (0, ownKey_1.setOwnValue)(out, key, window);
         const bare = stripProviderPrefix(key);
         if (bare && bare !== key) {
             const seen = aliasWindows.get(bare) ?? new Set();

package/dist/providers/claudeCode.js

@@ -155,7 +155,8 @@ class ClaudeCodeReader {
         this.usageDeduper = usageDeduper ?? new claudeUsageDedupe_1.ClaudeUsageDeduper();
         this.parser = new jsonl_1.JsonlParser({
             onEvent: (raw) => {
-                for (const event of (0, sessionEvent_1.extractSessionEvents)(raw)) {
+                // Mid-turn task notifications finish background subagents.
+                for (const event of (0, sessionEvent_1.extractSessionEvents)(raw, { includeTaskNotifications: true })) {
                     this.events.push(this.usageDeduper.apply((0, claudeUsageDedupe_1.normalizeClaudeUsage)(event)));
                 }
             },
@@ -244,6 +245,13 @@ class ClaudeCodeReader {
     wasTruncated() {
         return this._wasTruncated;
     }
+    /** The usage deduper's recent message ids, so a resumed reader does not recount a split response. */
+    getResumeState() {
+        return this.usageDeduper.exportState();
+    }
+    restoreResumeState(state) {
+        return this.usageDeduper.importState(state);
+    }
 }
 /**
  * Session provider for Claude Code CLI.

package/dist/providers/codex.js

@@ -306,6 +306,12 @@ class CodexReader {
     lineBuffer = '';
     _wasTruncated = false;
     decoder = new string_decoder_1.StringDecoder('utf8');
+    /**
+     * Position from `seekTo()` whose prefix still has to be parsed for model,
+     * turn, and cumulative-token context; `restoreResumeState()` supplies that
+     * context instead and clears it.
+     */
+    pendingSeek = null;
     constructor(rolloutPath, onContextWindowLimit, onRateLimits, onTokenUsage) {
         this.rolloutPath = rolloutPath;
         this.onContextWindowLimit = onContextWindowLimit;
@@ -315,9 +321,11 @@ class CodexReader {
     }
     /** Get the parser's session metadata. */
     getSessionMeta() {
+        this.settleSeek();
         return this.parser.getSessionMeta();
     }
     readNew(endPosition) {
+        this.settleSeek();
         this._wasTruncated = false;
         const events = [];
         try {
@@ -371,47 +379,51 @@ class CodexReader {
                     // Skip malformed JSON lines
                 }
             }
-            // Propagate model_context_window from token_count events to the provider.
-            // The model comes along so the value can be persisted per model — the
-            // window Codex reports is tier-specific, not the published maximum.
-            const mcw = this.parser.getModelContextWindow();
-            if (mcw && this.onContextWindowLimit) {
-                this.onContextWindowLimit(mcw, this.parser.getCurrentModel() ?? undefined);
-            }
-            // Propagate rate_limits from token_count events to the provider
-            const rateLimits = this.parser.getLastRateLimits();
-            if (rateLimits && this.onRateLimits) {
-                this.onRateLimits(rateLimits);
-            }
-            // Propagate last token usage snapshot to the provider
-            const lastUsage = this.parser.getLastTokenUsage();
-            if (lastUsage && this.onTokenUsage) {
-                const normalized = (0, usageNormalization_1.normalizeProviderUsage)({
-                    semantics: 'openai',
-                    provider: 'openai',
-                    source: 'codex-reader-snapshot',
-                    model: this.parser.getCurrentModel() || undefined,
-                    inputTokens: lastUsage.input_tokens,
-                    outputTokens: lastUsage.output_tokens,
-                    cacheReadTokens: lastUsage.cached_input_tokens,
-                    reasoningTokens: lastUsage.reasoning_output_tokens,
-                });
-                this.onTokenUsage({
-                    inputTokens: normalized.uncachedInputTokens,
-                    outputTokens: normalized.outputTokens,
-                    cacheWriteTokens: normalized.cacheWriteTokens,
-                    cacheReadTokens: normalized.cacheReadTokens,
-                    reasoningTokens: normalized.reasoningTokens,
-                    model: this.parser.getCurrentModel() || 'unknown',
-                    timestamp: new Date(),
-                });
-            }
+            this.propagateParserState();
         }
         catch {
             // Skip read errors
         }
         return events;
     }
+    /** Hands the parser's context window, rate limits, and last usage to the provider. */
+    propagateParserState() {
+        // Propagate model_context_window from token_count events to the provider.
+        // The model comes along so the value can be persisted per model — the
+        // window Codex reports is tier-specific, not the published maximum.
+        const mcw = this.parser.getModelContextWindow();
+        if (mcw && this.onContextWindowLimit) {
+            this.onContextWindowLimit(mcw, this.parser.getCurrentModel() ?? undefined);
+        }
+        // Propagate rate_limits from token_count events to the provider
+        const rateLimits = this.parser.getLastRateLimits();
+        if (rateLimits && this.onRateLimits) {
+            this.onRateLimits(rateLimits);
+        }
+        // Propagate last token usage snapshot to the provider
+        const lastUsage = this.parser.getLastTokenUsage();
+        if (lastUsage && this.onTokenUsage) {
+            const normalized = (0, usageNormalization_1.normalizeProviderUsage)({
+                semantics: 'openai',
+                provider: 'openai',
+                source: 'codex-reader-snapshot',
+                model: this.parser.getCurrentModel() || undefined,
+                inputTokens: lastUsage.input_tokens,
+                outputTokens: lastUsage.output_tokens,
+                cacheReadTokens: lastUsage.cached_input_tokens,
+                reasoningTokens: lastUsage.reasoning_output_tokens,
+            });
+            this.onTokenUsage({
+                inputTokens: normalized.uncachedInputTokens,
+                outputTokens: normalized.outputTokens,
+                cacheWriteTokens: normalized.cacheWriteTokens,
+                cacheReadTokens: normalized.cacheReadTokens,
+                reasoningTokens: normalized.reasoningTokens,
+                model: this.parser.getCurrentModel() || 'unknown',
+                timestamp: new Date(),
+            });
+        }
+    }
     readAll() {
         this.reset();
         return this.readNew();
@@ -423,11 +435,13 @@ class CodexReader {
         this.parser.reset();
         this.decoder = new string_decoder_1.StringDecoder('utf8');
         this._wasTruncated = false;
+        this.pendingSeek = null;
     }
     exists() {
         return fs.existsSync(this.rolloutPath);
     }
     flush() {
+        this.settleSeek();
         this.lineBuffer += this.decoder.end();
         // Process any remaining data in the line buffer
         if (this.lineBuffer.trim()) {
@@ -445,15 +459,45 @@ class CodexReader {
         return this.committedPosition;
     }
     seekTo(position) {
-        // Rebuild model, turn, and cumulative-token context before resuming.
-        // The prefix is parsed only; its events are already in the consumer snapshot.
         this.reset();
+        this.filePosition = position;
+        this.committedPosition = position;
+        // The prefix's context is rebuilt on the next read, unless
+        // restoreResumeState() supplies it first.
         if (position > 0)
-            this.readNew(position);
+            this.pendingSeek = position;
     }
     wasTruncated() {
         return this._wasTruncated;
     }
+    /** The parser's continuation state (see `CodexRolloutParser.exportResumeState`). */
+    getResumeState() {
+        this.settleSeek();
+        return this.parser.exportResumeState();
+    }
+    /**
+     * Restores parser state from `getResumeState()`; after `seekTo()` this
+     * replaces re-parsing the rollout up to that position.
+     */
+    restoreResumeState(state) {
+        if (!this.parser.importResumeState(state))
+            return false;
+        this.pendingSeek = null;
+        this.propagateParserState();
+        return true;
+    }
+    /**
+     * Rebuilds model, turn, and cumulative-token context for a pending
+     * `seekTo()` position. The prefix is parsed only; its events are already
+     * in the consumer snapshot.
+     */
+    settleSeek() {
+        const position = this.pendingSeek;
+        if (position === null)
+            return;
+        this.reset();
+        this.readNew(position);
+    }
 }
 // ---------------------------------------------------------------------------
 // CodexProvider — full SessionProviderBase implementation

package/dist/providers/types.d.ts

@@ -186,6 +186,20 @@ export interface SessionReader {
     seekTo(position: number): void;
     /** Check if file was truncated (size < position). */
     wasTruncated(): boolean;
+    /**
+     * Parse state the reader needs, beyond `getPosition()`, to continue
+     * correctly after a restart: JSON-serializable data to persist together
+     * with that position (for example which Claude responses were already
+     * counted). `undefined` when the reader keeps none. Optional.
+     */
+    getResumeState?(): unknown;
+    /**
+     * Restores state from `getResumeState()`. Call it right after `seekTo()`
+     * the position that state was taken at. Returns false, changing nothing,
+     * when `state` is missing or not valid for this reader; the caller should
+     * then replay from the start instead. Optional.
+     */
+    restoreResumeState?(state: unknown): boolean;
 }
 /**
  * Expanded session provider interface (no VS Code dependencies).

package/dist/schemas/index.d.ts

@@ -12,6 +12,7 @@
  */
 export { ACCOUNT_PROVIDER_IDS, QUOTA_PROVIDER_IDS, RUNTIME_QUOTA_PROVIDER_IDS, SESSION_PROVIDER_IDS, } from '../providerIds';
 export { messageUsageSchema, sessionMessageSchema, sessionEventSchema, permissionModeSchema, extractSessionEvents, userSessionEventSchema, assistantSessionEventSchema, summarySessionEventSchema, systemSessionEventSchema, toolUseSessionEventSchema, toolResultSessionEventSchema, } from './sessionEvent';
+export type { ExtractSessionEventsOptions } from './sessionEvent';
 export type { MessageUsage, SessionMessage, SessionEvent, PermissionMode, } from '../types/sessionEvent';
 export { normalizedUsageSchema, normalizedUsageCostSchema } from './usageNormalization';
 export type { NormalizedUsage, NormalizedUsageCost } from '../usageNormalization';

package/dist/schemas/sessionEvent.d.ts

@@ -76,12 +76,12 @@ export declare const userSessionEventSchema: z.ZodObject<{
     promptSource: z.ZodOptional<z.ZodString>;
     cwd: z.ZodOptional<z.ZodString>;
     gitBranch: z.ZodOptional<z.ZodString>;
-    permissionMode: z.ZodOptional<z.ZodEnum<{
+    permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
-    }>>;
+    }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
             usedPercent: z.ZodNumber;
@@ -165,12 +165,12 @@ export declare const assistantSessionEventSchema: z.ZodObject<{
     promptSource: z.ZodOptional<z.ZodString>;
     cwd: z.ZodOptional<z.ZodString>;
     gitBranch: z.ZodOptional<z.ZodString>;
-    permissionMode: z.ZodOptional<z.ZodEnum<{
+    permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
-    }>>;
+    }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
             usedPercent: z.ZodNumber;
@@ -255,12 +255,12 @@ export declare const systemSessionEventSchema: z.ZodObject<{
     promptSource: z.ZodOptional<z.ZodString>;
     cwd: z.ZodOptional<z.ZodString>;
     gitBranch: z.ZodOptional<z.ZodString>;
-    permissionMode: z.ZodOptional<z.ZodEnum<{
+    permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
-    }>>;
+    }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
             usedPercent: z.ZodNumber;
@@ -348,12 +348,12 @@ export declare const toolUseSessionEventSchema: z.ZodObject<{
     promptSource: z.ZodOptional<z.ZodString>;
     cwd: z.ZodOptional<z.ZodString>;
     gitBranch: z.ZodOptional<z.ZodString>;
-    permissionMode: z.ZodOptional<z.ZodEnum<{
+    permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
-    }>>;
+    }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
             usedPercent: z.ZodNumber;
@@ -442,12 +442,12 @@ export declare const toolResultSessionEventSchema: z.ZodObject<{
     promptSource: z.ZodOptional<z.ZodString>;
     cwd: z.ZodOptional<z.ZodString>;
     gitBranch: z.ZodOptional<z.ZodString>;
-    permissionMode: z.ZodOptional<z.ZodEnum<{
+    permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
-    }>>;
+    }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
             usedPercent: z.ZodNumber;
@@ -520,6 +520,19 @@ export declare const toolResultSessionEventSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const sessionEventSchema: z.ZodType<SessionEvent>;
+/** Options for {@link extractSessionEvents}. */
+export interface ExtractSessionEventsOptions {
+    /**
+     * Also turn Claude Code's mid-turn task-notification attachments
+     * (`{ type: 'attachment', attachment: { type: 'queued_command',
+     * commandMode: 'task-notification', prompt } }`) into one `system` event
+     * with `origin: { kind: 'task-notification' }`, `message: { role: 'user',
+     * sourceLabel: 'task notification', content: <prompt> }`, and the line's
+     * timestamp. They report background agents finishing. Default `false`:
+     * attachment lines yield no events.
+     */
+    includeTaskNotifications?: boolean;
+}
 /**
  * Extracts canonical SessionEvents from a raw JSONL value.
  *
@@ -528,5 +541,9 @@ export declare const sessionEventSchema: z.ZodType<SessionEvent>;
  * `sessionEventSchema` alone rejects. This helper tries a direct parse,
  * then unwraps progress envelopes (recursively, in case of nesting).
  * Returns zero events for unrecognized input — never throws.
+ *
+ * The second argument is either the starting progress depth (the original
+ * signature) or an options object.
  */
 export declare function extractSessionEvents(raw: unknown, depth?: number): SessionEvent[];
+export declare function extractSessionEvents(raw: unknown, options?: ExtractSessionEventsOptions): SessionEvent[];

package/dist/schemas/sessionEvent.js

@@ -12,6 +12,7 @@ exports.sessionEventSchema = exports.toolResultSessionEventSchema = exports.tool
 exports.extractSessionEvents = extractSessionEvents;
 const zod_1 = require("zod");
 const usageNormalization_1 = require("./usageNormalization");
+const subagentSpawn_1 = require("../subagentSpawn");
 // ── MessageUsage ──
 exports.messageUsageSchema = zod_1.z.object({
     input_tokens: zod_1.z.number(),
@@ -56,7 +57,9 @@ const eventBaseShape = {
     promptSource: zod_1.z.string().optional(),
     cwd: zod_1.z.string().optional(),
     gitBranch: zod_1.z.string().optional(),
-    permissionMode: exports.permissionModeSchema.optional(),
+    // A mode this release doesn't know (Claude Code added `auto`) is dropped
+    // rather than rejecting the whole line with its prompt or tool results.
+    permissionMode: exports.permissionModeSchema.optional().catch(undefined),
     rateLimits: zod_1.z
         .object({
         primary: zod_1.z
@@ -173,22 +176,21 @@ exports.sessionEventSchema = zod_1.z.union([
 // ── Progress unwrapping ──
 /** Recursion bound for nested progress envelopes; real data nests 1 level. */
 const MAX_PROGRESS_DEPTH = 8;
-/**
- * Extracts canonical SessionEvents from a raw JSONL value.
- *
- * Claude Code wraps subagent/SDK events as
- * `{ type: 'progress', data: { message: <SessionEvent> } }`, which
- * `sessionEventSchema` alone rejects. This helper tries a direct parse,
- * then unwraps progress envelopes (recursively, in case of nesting).
- * Returns zero events for unrecognized input — never throws.
- */
-function extractSessionEvents(raw, depth = 0) {
-    return extractSessionEventsWithProvenance(raw, depth, {});
+function extractSessionEvents(raw, depthOrOptions = 0) {
+    if (typeof depthOrOptions === 'number') {
+        return extractSessionEventsWithProvenance(raw, depthOrOptions, {}, {});
+    }
+    return extractSessionEventsWithProvenance(raw, 0, {}, depthOrOptions ?? {});
 }
-function extractSessionEventsWithProvenance(raw, depth, inherited) {
+function extractSessionEventsWithProvenance(raw, depth, inherited, options) {
     const direct = exports.sessionEventSchema.safeParse(raw);
     if (direct.success)
         return [{ ...inherited, ...direct.data }];
+    if (options.includeTaskNotifications) {
+        const notification = taskNotificationAttachmentEvent(raw);
+        if (notification)
+            return [{ ...inherited, ...notification }];
+    }
     if (depth >= MAX_PROGRESS_DEPTH)
         return [];
     if (typeof raw === 'object' && raw !== null && raw.type === 'progress') {
@@ -197,12 +199,31 @@ function extractSessionEventsWithProvenance(raw, depth, inherited) {
         if (typeof data === 'object' && data !== null) {
             const message = data.message;
             if (typeof message === 'object' && message !== null) {
-                return extractSessionEventsWithProvenance(message, depth + 1, provenance);
+                return extractSessionEventsWithProvenance(message, depth + 1, provenance, options);
             }
         }
     }
     return [];
 }
+/** The `system` event for a task-notification attachment line, or `null`. */
+function taskNotificationAttachmentEvent(raw) {
+    const prompt = (0, subagentSpawn_1.taskNotificationPromptFromAttachment)(raw);
+    if (prompt === null)
+        return null;
+    const line = raw;
+    const candidate = {
+        type: 'system',
+        timestamp: line.timestamp,
+        origin: { kind: 'task-notification' },
+        message: { role: 'user', sourceLabel: 'task notification', content: prompt },
+    };
+    for (const key of ['entrypoint', 'isSidechain', 'cwd', 'gitBranch']) {
+        if (line[key] !== undefined)
+            candidate[key] = line[key];
+    }
+    const parsed = exports.systemSessionEventSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : null;
+}
 function progressProvenance(raw) {
     const value = raw;
     const provenance = {};