@tmustier/pi-usage-extension 0.9.1 → 0.9.4

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.9.4] - 2026-07-22
+
+### Changed
+- Radically simplified nested-agent reconciliation. Child sessions on disk are now trusted as the record: when every child session file behind a tool report is part of the scan, the parent's aggregate is skipped; otherwise the whole report (or each unresolved legacy child) is counted under `Tools / summaries`. This replaces 0.9.3's exact contiguous token-and-cost vector matching and residual arithmetic (~250 lines) with a file-existence check — validated byte-identical against 0.9.3 on a 10 GB / 6,166-session corpus.
+- Resolved child identities are unioned across copied parent history before emission, because branch copies change runId-derived child paths. Same outcome as 0.9.3's global reconciliation, without vector identity keys.
+- Known trade-offs: a crash-truncated child session slightly undercounts, and a partially-missing child set counts the full aggregate (slight overcount). Neither case appeared in the audit corpus.
+
+### Internal
+- Cache format stays **v5** — no rebuild on upgrade.
+
+## [0.9.3] - 2026-07-22
+
+### Fixed
+- Reconcile nested-agent tool usage against recursively scanned child sessions using exact contiguous token-and-cost vectors. Canonical tool aggregates now exclude child usage already counted from session files, and mixed aggregates add only the unmatched residual under `Tools / summaries`.
+- Reconcile globally across copied parent history, so a stale copy with a missing child path cannot win deduplication and reintroduce usage represented by another copy's linked child session.
+- Backfill recognised legacy `subagent` and `subagent_wait` child usage only when no scanned child-session span represents it.
+
+### Performance
+- Extract accounting metadata from large tool results without decoding or JSON-parsing multi-megabyte output bodies.
+
+### Internal
+- Cache format bumped to **v5** to retain tool reports and child-session linkage. The first `/usage` open after upgrading performs a one-off rebuild.
+- Document the irrecoverable historical boundary: compaction and branch-summary entries written without usage metadata remain unmetered. The compatibility audit found 2,753 such compactions and 20 branch summaries.
+
+## [0.9.2] - 2026-07-21
+
+### Fixed
+- Include usage persisted by Pi 0.81.0 on tool results, compactions, and branch summaries. Auxiliary cost and token fields now participate in `/usage` accounting under the same synthetic `Tools / summaries` bucket as Pi's footer and `/session`, while `Msgs` remains an assistant-message count.
+- Keep auxiliary usage out of conversation context/cache-miss classification, attribute it separately in Insights, and deduplicate copied auxiliary entries by stable session entry id.
+
+### Internal
+- Cache format bumped to **v4**. The first `/usage` open after upgrading performs a one-off rebuild so previously ignored auxiliary entries are ingested.
+
 ## [0.9.1] - 2026-07-17
 
 ### Changed

package/README.md

@@ -7,7 +7,9 @@ A Pi extension that displays aggregated usage statistics across all sessions.
 ## Compatibility
 
 - **Pi version:** 0.42.4+
-- **Last updated:** 2026-07-17 (0.9.1)
+- **Last updated:** 2026-07-22 (0.9.3)
+
+Pi 0.81.0+ can persist tool-result, compaction, and branch-summary usage. `/usage` includes that auxiliary usage in totals under `Tools / summaries`. Nested-agent reports are reconciled against recursively scanned child sessions, so a child call is counted once: when every child session file behind a report is part of the scan, the children are the record and the parent's aggregate is skipped; otherwise the report is counted. Older Pi versions remain supported.
 
 ## Installation
 
@@ -83,6 +85,7 @@ The **Insights** view has two sections, facts first:
 
 | Insight | Detail |
 |---|---|
+| Tool and summary usage | share of cost reported by nested tool calls, compaction, and branch summarization (Pi 0.81.0+) |
 | Context tax | share of cost spent at ≥ 150k context, with the average per-message cost vs messages under 100k |
 | Project mix | top 3 project directories by cost, derived from each session's working directory (worktrees collapse into their repository; hidden when one project is ≥ 90% — you already know) |
 | Reasoning share | share of output tokens that were hidden reasoning (recorded by pi 0.80.3+ only; hidden below 5%) |
@@ -136,7 +139,7 @@ The **Graphs** view plots usage over time for the active period as a braille lin
 - **Buckets**: hourly for Today / This Week / Last Week, daily for Last 30 Days / All Time.
 - **Line clipping**: every series (provider, model, thinking level, `other`, Total) is drawn only between its first and last bucket with usage, so late-starting or retired series don't drag a flat zero/flat tail across the whole period.
 
-Thinking levels are replayed from `thinking_level_change` entries in each session file; messages before the first recorded change appear as `unknown`. Reasoning token counts come from `usage.reasoning` where providers report them; pi only records this field since **pi 0.80.3 (30 June 2026)**, so earlier sessions show zero reasoning tokens even though thinking models were in use.
+Thinking levels are replayed from `thinking_level_change` entries in each session file; messages before the first recorded change appear as `unknown`. Auxiliary usage has no reliable thinking-level attribution and appears as `Tools/summaries` in that grouping. Reasoning token counts come from `usage.reasoning` where providers report them; pi only records this field since **pi 0.80.3 (30 June 2026)**, so earlier sessions show zero reasoning tokens even though thinking models were in use.
 
 ### Time Periods
 
@@ -160,8 +163,8 @@ Time periods are calculated in the local timezone where Pi runs. If you want to
 |--------|-------------|
 | **Provider / Model** | Provider name, expandable to show models |
 | **Sessions** | Number of unique sessions |
-| **Msgs** | Number of assistant messages |
-| **Cost** | Total cost in USD (from API response) |
+| **Msgs** | Number of assistant messages; auxiliary `Tools / summaries` usage does not inflate this count |
+| **Cost** | Total cost in USD (from API response), including usage reported by tools and summaries |
 | **Tokens** | Fresh tokens for the turn: input + output + cache write |
 | **↑In** | Fresh input tokens: input + cache write *(dimmed)* |
 | **↓Out** | Output tokens *(dimmed)* |
@@ -195,13 +198,16 @@ On narrow terminals, `/usage` automatically switches to a compact table instead
 - **On-disk cache.** Per-file extraction results are cached in `<agentDir>/usage-extension-cache.json` (respects `PI_CODING_AGENT_DIR`), keyed by file size + mtime. Warm opens only re-parse session files that changed since the last run — on a 5.2 GB / 3,310-file corpus that takes the open from ~17 s to ~0.3 s.
 - **First open** after install (or after deleting the cache) does a one-off full build, showing the usual cancellable loader. Cancelling saves partial progress, so the next open resumes where it left off.
 - The cache is safe to delete at any time; it is rebuilt automatically. Corrupt or version-mismatched caches are ignored and rebuilt rather than trusted.
-- **0.7.0 bumps the cache format to v3** (adds session working directory and compaction markers; 0.6.0's v2 added thinking level and reasoning tokens). The first open after upgrading does a one-off full rebuild (with a progress message and live file counter), then warm opens are fast again.
+- **0.9.3 bumps the cache format to v5** to retain child-session linkage for tool-usage reconciliation (v4 added Pi 0.81.0 tool and summary usage; v3 added session working directory and compaction markers; v2 added thinking level and reasoning tokens). The first open after upgrading does a one-off full rebuild (with a progress message and live file counter), then warm opens are fast again.
+- Large nested-agent tool results use an allocation-safe metadata parser: multi-megabyte output bodies are scanned as bytes rather than decoded and JSON-parsed in full.
 
 ## Provider Notes
 
 ### Cost Tracking
 
-Cost data comes directly from the API response (`usage.cost.total`). Accuracy depends on the provider reporting costs.
+Cost data comes directly from persisted usage values. For assistant messages it is grouped by provider/model. Pi 0.81.0+ can also persist usage reported by tools, compaction, and branch summarization; because those entries do not carry reliable provider/model attribution, `/usage` groups them under `Tools / summaries`, matching Pi's `/session` breakdown. Recognised legacy `subagent` and `subagent_wait` details are used as a fallback when their child session is no longer available. Accuracy depends on the provider or tool reporting costs.
+
+Only persisted usage can be counted. Pi did not add usage metadata retroactively, so historical compaction or branch-summary entries written without `usage` remain unmetered: their exact token and cost vectors cannot be reconstructed. The compatibility audit corpus contained 2,753 such compactions and 20 branch summaries.
 
 ### Cache Tokens
 
@@ -219,9 +225,9 @@ The "Cache" column combines both read and write tokens.
 
 ## Data Source
 
-Statistics are parsed recursively from session files in `~/.pi/agent/sessions/`, including nested subagent runs such as `run-0/` directories. Each session is a JSONL file containing message entries with usage data.
+Statistics are parsed recursively from session files in `~/.pi/agent/sessions/`, including nested subagent runs such as `run-0/` directories. Each session is a JSONL file containing assistant messages and, on Pi 0.81.0+, optional usage on tool-result, compaction, and branch-summary entries.
 
-Assistant messages duplicated across branched session files are deduplicated by timestamp + total tokens, matching the extension's previous behavior while still including recursive subagent sessions.
+Assistant messages duplicated across branched session files are deduplicated by timestamp + total tokens. Auxiliary usage is deduplicated by its stable session entry id, which avoids collapsing parallel tools that happen to report identical usage. Nested-agent reports are suppressed when their child session files are part of the scan (resolved across all copies of the parent entry, since branch copies change runId-derived paths); reports whose children are missing stay under `Tools / summaries`. Tool and summary usage contributes cost and tokens to totals, graphs, project/session mix, and burn trend, but does not count as an assistant message or distort conversation context/cache insights.
 
 Respects the `PI_CODING_AGENT_DIR` environment variable if set.
 

package/data.ts

@@ -2,10 +2,10 @@
  * Data collection, caching, and insights for the /usage dashboard.
  *
  * Performance model (see CHANGELOG 0.4.0):
- * - Session JSONL files are scanned at the buffer level. Only lines that can
- *   possibly be a session header or an assistant message are UTF-8 decoded and
- *   JSON.parsed — the multi-megabyte tool-result lines that dominate session
- *   files are skipped with a cheap byte search.
+ * - Session JSONL files are scanned at the buffer level. Only lines relevant
+ *   to assistant or auxiliary accounting are decoded and JSON.parsed. Ordinary
+ *   multi-megabyte tool results are skipped; accounting-bearing large results
+ *   use an allocation-safe byte parser for their small metadata fields.
  * - Per-file extraction results are persisted to an on-disk cache keyed by
  *   (size, mtimeMs). Session files are append-only, so a warm load only
  *   re-parses files that changed since the last run.
@@ -13,7 +13,7 @@
 
 import { readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
 // =============================================================================
 // Types
@@ -66,8 +66,12 @@ interface CostCount {
 }
 
 interface PeriodRawData {
+	/** All recorded cost, including usage reported by tools and summaries. */
 	totalCost: number;
-	totalMessages: number;
+	/** Cost attached to assistant messages, used as the turn-insight denominator. */
+	assistantCost: number;
+	/** Usage reported by tool results, compactions, and branch summaries. */
+	auxiliaryCost: number;
 	/** Messages at ≥ CTX_TAX_THRESHOLD context. */
 	ctxHigh: CostCount;
 	/** Messages below CTX_LOW_THRESHOLD context (comparison group). */
@@ -164,18 +168,31 @@ export type TabName = "today" | "thisWeek" | "lastWeek" | "last30Days" | "allTim
 
 export const TAB_ORDER: TabName[] = ["today", "thisWeek", "lastWeek", "last30Days", "allTime"];
 
-export interface SessionMessage {
-	provider: string;
-	model: string;
-	/** Thinking level active when the message was produced; "" when unknown. */
-	thinkingLevel: string;
+export type UsageSource = "assistant" | "auxiliary";
+
+/** Pi's own label for usage that cannot be attributed to a provider/model. */
+export const AUXILIARY_PROVIDER = "Tools";
+export const AUXILIARY_MODEL = "summaries";
+export const AUXILIARY_THINKING_LEVEL = "Tools/summaries";
+
+export interface UsageAmount {
 	cost: number;
 	input: number;
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
-	/** Reasoning output tokens reported by the provider (0 when absent). */
 	reasoning: number;
+}
+
+export interface SessionMessage extends UsageAmount {
+	provider: string;
+	model: string;
+	/** Thinking level active when the message was produced; "" when unknown. */
+	thinkingLevel: string;
+	/** Assistant response, or usage reported by a tool/summary entry. */
+	source: UsageSource;
+	/** Session entry id used to dedupe copied auxiliary entries; empty for assistant messages. */
+	sourceId: string;
 	timestamp: number;
 	/**
 	 * True when a compaction entry occurred between the previous assistant
@@ -185,13 +202,34 @@ export interface SessionMessage {
 	afterCompaction: boolean;
 }
 
+export interface ChildToolUsage {
+	resultIndex: number;
+	/** Persisted child session path when the tool supplied one; empty otherwise. */
+	sessionFile: string;
+	usage: UsageAmount;
+}
+
+export interface ToolUsageRecord {
+	/** Parent tool-result entry id, stable across copied branch history. */
+	sourceId: string;
+	timestamp: number;
+	/** Canonical Pi 0.81+ tool usage; null for legacy nested-agent results. */
+	reportedUsage: UsageAmount | null;
+	/** Run id used to derive the standard nested-session path when needed. */
+	runId: string;
+	/** Recognised per-child usage from nested-agent tool details. */
+	children: ChildToolUsage[];
+}
+
 export interface ParsedSessionFile {
 	/** Empty string when the file has no session header — such files are ignored. */
 	sessionId: string;
 	/** Working directory from the session header; "" when absent. */
 	cwd: string;
-	/** Extracted assistant messages, pre-dedupe. Dedupe happens at aggregation. */
+	/** Extracted assistant and summary usage records, pre-dedupe. */
 	messages: SessionMessage[];
+	/** Tool usage is reconciled against recursively scanned child sessions later. */
+	toolUsages: ToolUsageRecord[];
 }
 
 // =============================================================================
@@ -252,35 +290,374 @@ const NEWLINE = 0x0a;
 // only cost a wasted JSON.parse — the parsed entry is still shape-checked.
 const PATTERN_ASSISTANT_COMPACT = Buffer.from('"role":"assistant"');
 const PATTERN_ASSISTANT_SPACED = Buffer.from('"role": "assistant"');
+const PATTERN_TOOL_RESULT_COMPACT = Buffer.from('"role":"toolResult"');
+const PATTERN_TOOL_RESULT_SPACED = Buffer.from('"role": "toolResult"');
+const PATTERN_USAGE_COMPACT = Buffer.from('"usage":{');
+const PATTERN_USAGE_SPACED = Buffer.from('"usage": {');
 const PATTERN_SESSION_COMPACT = Buffer.from('"type":"session"');
 const PATTERN_SESSION_SPACED = Buffer.from('"type": "session"');
 const PATTERN_THINKING_COMPACT = Buffer.from('"type":"thinking_level_change"');
 const PATTERN_THINKING_SPACED = Buffer.from('"type": "thinking_level_change"');
 const PATTERN_COMPACTION_COMPACT = Buffer.from('"type":"compaction"');
 const PATTERN_COMPACTION_SPACED = Buffer.from('"type": "compaction"');
+const PATTERN_BRANCH_SUMMARY_COMPACT = Buffer.from('"type":"branch_summary"');
+const PATTERN_BRANCH_SUMMARY_SPACED = Buffer.from('"type": "branch_summary"');
+// pi-subagents versions predating Pi 0.81 persisted child usage in details but
+// could not put it on the canonical tool-result usage field. Their tool names
+// are near the start of the line, so we can recover those records without
+// scanning every multi-megabyte tool result.
+const PATTERN_SUBAGENT_TOOL_COMPACT = Buffer.from('"toolName":"subagent"');
+const PATTERN_SUBAGENT_TOOL_SPACED = Buffer.from('"toolName": "subagent"');
+const PATTERN_SUBAGENT_WAIT_TOOL_COMPACT = Buffer.from('"toolName":"subagent_wait"');
+const PATTERN_SUBAGENT_WAIT_TOOL_SPACED = Buffer.from('"toolName": "subagent_wait"');
 
 const PARSE_YIELD_EVERY_LINES = 2000;
 
+function finiteNumber(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function parseUsageAmount(value: unknown): UsageAmount | null {
+	if (!value || typeof value !== "object") return null;
+	const persisted = value as Record<string, unknown>;
+	const costValue = persisted.cost;
+	const cost =
+		typeof costValue === "number"
+			? finiteNumber(costValue)
+			: costValue && typeof costValue === "object"
+				? finiteNumber((costValue as Record<string, unknown>).total)
+				: 0;
+	const usage = {
+		cost,
+		input: finiteNumber(persisted.input),
+		output: finiteNumber(persisted.output),
+		cacheRead: finiteNumber(persisted.cacheRead),
+		cacheWrite: finiteNumber(persisted.cacheWrite),
+		reasoning: finiteNumber(persisted.reasoning),
+	};
+	return usage.cost === 0 && usage.input === 0 && usage.output === 0 && usage.cacheRead === 0 && usage.cacheWrite === 0
+		? null
+		: usage;
+}
+
+function parsedTimestamp(messageTimestamp: unknown, entryTimestamp: unknown): number {
+	const parsed =
+		typeof messageTimestamp === "number"
+			? messageTimestamp
+			: new Date(String(messageTimestamp ?? entryTimestamp ?? "")).getTime();
+	return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function auxiliaryMessage(usage: UsageAmount, timestamp: number, sourceId: string): SessionMessage {
+	return {
+		provider: AUXILIARY_PROVIDER,
+		model: AUXILIARY_MODEL,
+		thinkingLevel: AUXILIARY_THINKING_LEVEL,
+		source: "auxiliary",
+		sourceId,
+		...usage,
+		timestamp,
+		afterCompaction: false,
+	};
+}
+
+function buildToolUsageRecord(
+	toolName: unknown,
+	detailsValue: unknown,
+	reportedValue: unknown,
+	sourceIdValue: unknown,
+	messageTimestamp: unknown,
+	entryTimestamp: unknown
+): ToolUsageRecord | null {
+	const reportedUsage = parseUsageAmount(reportedValue);
+	const details = detailsValue && typeof detailsValue === "object" ? (detailsValue as Record<string, unknown>) : null;
+	const totalChildUsage = parseUsageAmount(details?.totalChildUsage);
+	const knownNestedTool = toolName === "subagent" || toolName === "subagent_wait";
+	const children: ChildToolUsage[] = [];
+	if (details && Array.isArray(details.results)) {
+		for (let resultIndex = 0; resultIndex < details.results.length; resultIndex++) {
+			const result = details.results[resultIndex];
+			if (!result || typeof result !== "object") continue;
+			const child = result as Record<string, unknown>;
+			const usage = parseUsageAmount(child.usage);
+			const sessionFile = typeof child.sessionFile === "string" ? child.sessionFile : "";
+			// Legacy fallback is deliberately restricted to recognised nested-agent
+			// records. Generic Pi 0.81 tools remain canonical through reportedUsage.
+			if (usage && (knownNestedTool || totalChildUsage || (reportedUsage && sessionFile))) {
+				children.push({ resultIndex, sessionFile, usage });
+			}
+		}
+	}
+	if (!reportedUsage && children.length === 0) return null;
+	return {
+		sourceId: typeof sourceIdValue === "string" ? sourceIdValue : "",
+		timestamp: parsedTimestamp(messageTimestamp, entryTimestamp),
+		reportedUsage,
+		runId: details && typeof details.runId === "string" ? details.runId : "",
+		children,
+	};
+}
+
+const LARGE_TOOL_RESULT_BYTES = 64 * 1024;
+const PROPERTY_ID = Buffer.from('"id":');
+const PROPERTY_TIMESTAMP = Buffer.from('"timestamp":');
+const PROPERTY_MESSAGE = Buffer.from('"message":');
+const PROPERTY_TOOL_NAME = Buffer.from('"toolName":');
+const PROPERTY_DETAILS = Buffer.from('"details":');
+const PROPERTY_USAGE = Buffer.from('"usage":');
+const DIRECT_CHILD_PROPERTIES = new Set(["usage", "sessionFile"]);
+
+function skipJsonWhitespace(buffer: Buffer, offset: number, limit: number): number {
+	while (offset < limit && (buffer[offset] === 0x20 || buffer[offset] === 0x09 || buffer[offset] === 0x0a || buffer[offset] === 0x0d)) offset++;
+	return offset;
+}
+
+/** Find one JSON value's end without decoding large strings or container bodies. */
+function jsonValueEnd(buffer: Buffer, offset: number, limit: number): number {
+	offset = skipJsonWhitespace(buffer, offset, limit);
+	if (offset >= limit) return offset;
+	const first = buffer[offset];
+	if (first === 0x22) {
+		let escaped = false;
+		for (let i = offset + 1; i < limit; i++) {
+			const byte = buffer[i];
+			if (escaped) escaped = false;
+			else if (byte === 0x5c) escaped = true;
+			else if (byte === 0x22) return i + 1;
+		}
+		return limit;
+	}
+	if (first === 0x7b || first === 0x5b) {
+		let depth = 0;
+		let inString = false;
+		let escaped = false;
+		for (let i = offset; i < limit; i++) {
+			const byte = buffer[i];
+			if (inString) {
+				if (escaped) escaped = false;
+				else if (byte === 0x5c) escaped = true;
+				else if (byte === 0x22) inString = false;
+				continue;
+			}
+			if (byte === 0x22) inString = true;
+			else if (byte === 0x7b || byte === 0x5b) depth++;
+			else if (byte === 0x7d || byte === 0x5d) {
+				depth--;
+				if (depth === 0) return i + 1;
+			}
+		}
+		return limit;
+	}
+	let end = offset;
+	while (end < limit && buffer[end] !== 0x2c && buffer[end] !== 0x5d && buffer[end] !== 0x7d) end++;
+	return end;
+}
+
+function parseJsonValueAt(buffer: Buffer, offset: number, limit: number): unknown {
+	const start = skipJsonWhitespace(buffer, offset, limit);
+	const end = jsonValueEnd(buffer, start, limit);
+	if (end <= start) return undefined;
+	try {
+		return JSON.parse(buffer.toString("utf8", start, end));
+	} catch {
+		return undefined;
+	}
+}
+
+function parsePropertyValue(buffer: Buffer, property: Buffer, from: number, to: number): unknown {
+	const propertyOffset = buffer.indexOf(property, from);
+	if (propertyOffset < 0 || propertyOffset >= to) return undefined;
+	return parseJsonValueAt(buffer, propertyOffset + property.length, to);
+}
+
+function parseLastPropertyValue(buffer: Buffer, property: Buffer, from: number, to: number): unknown {
+	const propertyOffset = buffer.lastIndexOf(property, to - 1);
+	if (propertyOffset < from) return undefined;
+	return parseJsonValueAt(buffer, propertyOffset + property.length, to);
+}
+
+interface DirectObjectScan {
+	end: number;
+	values: Map<string, [start: number, end: number]>;
+}
+
+/** Scan direct object properties while skipping nested values allocation-free. */
+function scanDirectObjectProperties(buffer: Buffer, objectStart: number, limit: number, wanted: Set<string>): DirectObjectScan {
+	const values = new Map<string, [number, number]>();
+	let cursor = objectStart + 1;
+	while (cursor < limit) {
+		cursor = skipJsonWhitespace(buffer, cursor, limit);
+		if (buffer[cursor] === 0x7d) return { end: cursor + 1, values };
+		if (buffer[cursor] === 0x2c) {
+			cursor++;
+			continue;
+		}
+		if (buffer[cursor] !== 0x22) return { end: jsonValueEnd(buffer, objectStart, limit), values };
+		const keyEnd = jsonValueEnd(buffer, cursor, limit);
+		let colon = skipJsonWhitespace(buffer, keyEnd, limit);
+		if (buffer[colon] !== 0x3a) return { end: jsonValueEnd(buffer, objectStart, limit), values };
+		const valueStart = skipJsonWhitespace(buffer, colon + 1, limit);
+		const valueEnd = jsonValueEnd(buffer, valueStart, limit);
+		const key = buffer.toString("utf8", cursor + 1, keyEnd - 1);
+		if (wanted.has(key)) values.set(key, [valueStart, valueEnd]);
+		if (valueEnd <= valueStart) return { end: limit, values };
+		cursor = valueEnd;
+	}
+	return { end: limit, values };
+}
+
+function parseJsonRange(buffer: Buffer, range: [number, number] | undefined): unknown {
+	if (!range) return undefined;
+	try {
+		return JSON.parse(buffer.toString("utf8", range[0], range[1]));
+	} catch {
+		return undefined;
+	}
+}
+
+interface ChildResultsScan {
+	end: number;
+	results: Array<Record<string, unknown>>;
+}
+
+function scanChildResults(buffer: Buffer, arrayStart: number, limit: number): ChildResultsScan {
+	const results: Array<Record<string, unknown>> = [];
+	let cursor = arrayStart + 1;
+	while (cursor < limit) {
+		cursor = skipJsonWhitespace(buffer, cursor, limit);
+		if (buffer[cursor] === 0x5d) return { end: cursor + 1, results };
+		if (buffer[cursor] === 0x2c) {
+			cursor++;
+			continue;
+		}
+		if (buffer[cursor] === 0x7b) {
+			const scanned = scanDirectObjectProperties(buffer, cursor, limit, DIRECT_CHILD_PROPERTIES);
+			results.push({
+				usage: parseJsonRange(buffer, scanned.values.get("usage")),
+				sessionFile: parseJsonRange(buffer, scanned.values.get("sessionFile")),
+			});
+			if (scanned.end <= cursor) return { end: limit, results };
+			cursor = scanned.end;
+			continue;
+		}
+		const valueEnd = jsonValueEnd(buffer, cursor, limit);
+		if (valueEnd <= cursor) return { end: limit, results };
+		cursor = valueEnd;
+	}
+	return { end: limit, results };
+}
+
+interface LargeDetailsScan {
+	end: number;
+	details: Record<string, unknown>;
+}
+
+/** Scan nested-agent details and its result metadata in a single byte pass. */
+function scanLargeDetails(buffer: Buffer, objectStart: number, limit: number): LargeDetailsScan {
+	const details: Record<string, unknown> = { results: [] };
+	let cursor = objectStart + 1;
+	while (cursor < limit) {
+		cursor = skipJsonWhitespace(buffer, cursor, limit);
+		if (buffer[cursor] === 0x7d) return { end: cursor + 1, details };
+		if (buffer[cursor] === 0x2c) {
+			cursor++;
+			continue;
+		}
+		if (buffer[cursor] !== 0x22) return { end: jsonValueEnd(buffer, objectStart, limit), details };
+		const keyEnd = jsonValueEnd(buffer, cursor, limit);
+		let colon = skipJsonWhitespace(buffer, keyEnd, limit);
+		if (buffer[colon] !== 0x3a) return { end: jsonValueEnd(buffer, objectStart, limit), details };
+		const valueStart = skipJsonWhitespace(buffer, colon + 1, limit);
+		const key = buffer.toString("utf8", cursor + 1, keyEnd - 1);
+		let valueEnd: number;
+		if (key === "results" && buffer[valueStart] === 0x5b) {
+			const scanned = scanChildResults(buffer, valueStart, limit);
+			details.results = scanned.results;
+			valueEnd = scanned.end;
+		} else {
+			valueEnd = jsonValueEnd(buffer, valueStart, limit);
+			if (key === "runId" || key === "totalChildUsage") {
+				details[key] = parseJsonRange(buffer, [valueStart, valueEnd]);
+			}
+		}
+		if (valueEnd <= valueStart) return { end: limit, details };
+		cursor = valueEnd;
+	}
+	return { end: limit, details };
+}
+
+/**
+ * Parse only the small accounting fields from a large tool-result line. This
+ * avoids UTF-8 decoding and JSON.parse allocation for multi-megabyte content.
+ */
+function parseLargeToolResultLine(line: Buffer): ToolUsageRecord | null {
+	const messageOffset = line.indexOf(PROPERTY_MESSAGE);
+	if (messageOffset < 0) return null;
+	const detailsOffset = line.indexOf(PROPERTY_DETAILS, messageOffset);
+	let detailsEnd = -1;
+	let details: Record<string, unknown> | null = null;
+	if (detailsOffset >= 0) {
+		const detailsStart = skipJsonWhitespace(line, detailsOffset + PROPERTY_DETAILS.length, line.length);
+		if (line[detailsStart] === 0x7b) {
+			const scanned = scanLargeDetails(line, detailsStart, line.length);
+			detailsEnd = scanned.end;
+			details = scanned.details;
+		}
+	}
+
+	const reportedUsage = detailsEnd >= 0
+		? parsePropertyValue(line, PROPERTY_USAGE, detailsEnd, line.length)
+		: parseLastPropertyValue(line, PROPERTY_USAGE, messageOffset, line.length);
+	const sourceId = parsePropertyValue(line, PROPERTY_ID, 0, messageOffset);
+	const entryTimestamp = parsePropertyValue(line, PROPERTY_TIMESTAMP, 0, messageOffset);
+	const messageTimestamp = parseLastPropertyValue(line, PROPERTY_TIMESTAMP, messageOffset, line.length);
+	const toolName = parsePropertyValue(line, PROPERTY_TOOL_NAME, messageOffset, detailsOffset >= 0 ? detailsOffset : line.length);
+	return buildToolUsageRecord(toolName, details, reportedUsage, sourceId, messageTimestamp, entryTimestamp);
+}
+
 function lineMightBeRelevant(line: Buffer): boolean {
+	// Entry type/role fields are at the front of Pi's JSONL objects. Restrict
+	// those checks to a small prefix so multi-megabyte tool output is not scanned
+	// repeatedly for every possible entry shape.
+	const head = line.length > 1024 ? line.subarray(0, 1024) : line;
+	if (head.includes(PATTERN_ASSISTANT_COMPACT) || head.includes(PATTERN_ASSISTANT_SPACED)) return true;
+
+	if (head.includes(PATTERN_TOOL_RESULT_COMPACT) || head.includes(PATTERN_TOOL_RESULT_SPACED)) {
+		if (
+			head.includes(PATTERN_SUBAGENT_TOOL_COMPACT) ||
+			head.includes(PATTERN_SUBAGENT_TOOL_SPACED) ||
+			head.includes(PATTERN_SUBAGENT_WAIT_TOOL_COMPACT) ||
+			head.includes(PATTERN_SUBAGENT_WAIT_TOOL_SPACED)
+		) {
+			return true;
+		}
+		// Pi serializes optional tool usage after content/details and immediately
+		// before the small isError/timestamp suffix. Checking the tail preserves
+		// the fast path for ordinary tool results, which dominate session bytes.
+		const tail = line.length > 4096 ? line.subarray(line.length - 4096) : line;
+		return tail.includes(PATTERN_USAGE_COMPACT) || tail.includes(PATTERN_USAGE_SPACED);
+	}
+
 	return (
-		line.includes(PATTERN_ASSISTANT_COMPACT) ||
-		line.includes(PATTERN_SESSION_COMPACT) ||
-		line.includes(PATTERN_THINKING_COMPACT) ||
-		line.includes(PATTERN_COMPACTION_COMPACT) ||
-		line.includes(PATTERN_ASSISTANT_SPACED) ||
-		line.includes(PATTERN_SESSION_SPACED) ||
-		line.includes(PATTERN_THINKING_SPACED) ||
-		line.includes(PATTERN_COMPACTION_SPACED)
+		head.includes(PATTERN_SESSION_COMPACT) ||
+		head.includes(PATTERN_THINKING_COMPACT) ||
+		head.includes(PATTERN_COMPACTION_COMPACT) ||
+		head.includes(PATTERN_BRANCH_SUMMARY_COMPACT) ||
+		head.includes(PATTERN_SESSION_SPACED) ||
+		head.includes(PATTERN_THINKING_SPACED) ||
+		head.includes(PATTERN_COMPACTION_SPACED) ||
+		head.includes(PATTERN_BRANCH_SUMMARY_SPACED)
 	);
 }
 
 /**
- * Extract the session id and assistant messages from a session JSONL buffer.
+ * Extract the session id plus assistant/tool/summary usage from a JSONL buffer.
  * Returns partial results when aborted — callers must check `signal.aborted`
  * before caching or using the result.
  */
 export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal): Promise<ParsedSessionFile> {
 	const messages: SessionMessage[] = [];
+	const toolUsages: ToolUsageRecord[] = [];
 	let sessionId = "";
 	let cwd = "";
 	// Assistant messages don't carry the thinking level; pi records it as separate
@@ -289,6 +666,7 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 	// to the level active when it was produced.
 	let thinkingLevel = "";
 	let compactionPending = false;
+
 	let start = 0;
 	let lineNumber = 0;
 
@@ -299,10 +677,18 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 		lineNumber++;
 		if (lineNumber % PARSE_YIELD_EVERY_LINES === 0) {
 			await new Promise<void>((resolve) => setImmediate(resolve));
-			if (signal?.aborted) return { sessionId, cwd, messages };
+			if (signal?.aborted) return { sessionId, cwd, messages, toolUsages };
 		}
 
-		if (end > start && lineMightBeRelevant(buffer.subarray(start, end))) {
+		const lineBuffer = buffer.subarray(start, end);
+		if (end > start && lineMightBeRelevant(lineBuffer)) {
+			const head = lineBuffer.subarray(0, Math.min(1024, lineBuffer.length));
+			if (lineBuffer.length > LARGE_TOOL_RESULT_BYTES && head.includes(PATTERN_TOOL_RESULT_COMPACT)) {
+				const toolUsage = parseLargeToolResultLine(lineBuffer);
+				if (toolUsage) toolUsages.push(toolUsage);
+				start = end + 1;
+				continue;
+			}
 			try {
 				const entry = JSON.parse(buffer.toString("utf8", start, end));
 
@@ -312,7 +698,12 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 				} else if (entry.type === "thinking_level_change") {
 					if (typeof entry.thinkingLevel === "string") thinkingLevel = entry.thinkingLevel;
 				} else if (entry.type === "compaction") {
+					const usage = parseUsageAmount(entry.usage);
+					if (usage) messages.push(auxiliaryMessage(usage, parsedTimestamp(undefined, entry.timestamp), typeof entry.id === "string" ? entry.id : ""));
 					compactionPending = true;
+				} else if (entry.type === "branch_summary") {
+					const usage = parseUsageAmount(entry.usage);
+					if (usage) messages.push(auxiliaryMessage(usage, parsedTimestamp(undefined, entry.timestamp), typeof entry.id === "string" ? entry.id : ""));
 				} else if (entry.type === "message" && entry.message?.role === "assistant") {
 					const msg = entry.message;
 					if (msg.usage && msg.provider && msg.model) {
@@ -321,6 +712,8 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 							provider: msg.provider,
 							model: msg.model,
 							thinkingLevel,
+							source: "assistant",
+							sourceId: "",
 							cost: msg.usage.cost?.total || 0,
 							input: msg.usage.input || 0,
 							output: msg.usage.output || 0,
@@ -332,6 +725,10 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 						});
 						compactionPending = false;
 					}
+				} else if (entry.type === "message" && entry.message?.role === "toolResult") {
+					const msg = entry.message;
+					const toolUsage = buildToolUsageRecord(msg.toolName, msg.details, msg.usage, entry.id, msg.timestamp, entry.timestamp);
+					if (toolUsage) toolUsages.push(toolUsage);
 				}
 			} catch {
 				// Skip malformed lines
@@ -341,14 +738,14 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 		start = end + 1;
 	}
 
-	return { sessionId, cwd, messages };
+	return { sessionId, cwd, messages, toolUsages };
 }
 
 // =============================================================================
 // On-disk cache
 // =============================================================================
 
-const CACHE_VERSION = 3;
+const CACHE_VERSION = 5;
 
 type CachedMessageTuple = [
 	providerIdx: number,
@@ -362,6 +759,31 @@ type CachedMessageTuple = [
 	thinkingLevelIdx: number,
 	reasoning: number,
 	afterCompaction: 0 | 1,
+	auxiliary: 0 | 1,
+	sourceIdIdx: number,
+];
+
+type CachedUsageTuple = [
+	cost: number,
+	input: number,
+	output: number,
+	cacheRead: number,
+	cacheWrite: number,
+	reasoning: number,
+];
+
+type CachedChildToolUsageTuple = [
+	resultIndex: number,
+	sessionFileIdx: number,
+	usage: CachedUsageTuple,
+];
+
+type CachedToolUsageTuple = [
+	sourceIdIdx: number,
+	timestamp: number,
+	reportedUsage: CachedUsageTuple | null,
+	runIdIdx: number,
+	children: CachedChildToolUsageTuple[],
 ];
 
 interface CacheFileEntry {
@@ -370,6 +792,7 @@ interface CacheFileEntry {
 	sessionId: string;
 	cwd: string;
 	messages: CachedMessageTuple[];
+	toolUsages: CachedToolUsageTuple[];
 }
 
 export interface CachedFileState {
@@ -398,21 +821,29 @@ export async function loadUsageCache(cachePath: string): Promise<Map<string, Cac
 			typeof entry.mtimeMs !== "number" ||
 			typeof entry.sessionId !== "string" ||
 			typeof entry.cwd !== "string" ||
-			!Array.isArray(entry.messages)
+			!Array.isArray(entry.messages) ||
+			!Array.isArray(entry.toolUsages)
 		) {
 			continue;
 		}
 		const messages: SessionMessage[] = [];
 		let valid = true;
 		for (const tuple of entry.messages) {
-			if (!Array.isArray(tuple) || tuple.length !== 11) {
+			if (!Array.isArray(tuple) || tuple.length !== 13) {
 				valid = false;
 				break;
 			}
 			const provider = names[tuple[0]];
 			const model = names[tuple[1]];
 			const thinkingLevel = names[tuple[8]];
-			if (typeof provider !== "string" || typeof model !== "string" || typeof thinkingLevel !== "string") {
+			const sourceId = names[tuple[12]];
+			if (
+				typeof provider !== "string" ||
+				typeof model !== "string" ||
+				typeof thinkingLevel !== "string" ||
+				typeof sourceId !== "string" ||
+				(tuple[11] !== 0 && tuple[11] !== 1)
+			) {
 				valid = false;
 				break;
 			}
@@ -420,6 +851,8 @@ export async function loadUsageCache(cachePath: string): Promise<Map<string, Cac
 				provider,
 				model,
 				thinkingLevel,
+				source: tuple[11] === 1 ? "auxiliary" : "assistant",
+				sourceId,
 				cost: Number(tuple[2]) || 0,
 				input: Number(tuple[3]) || 0,
 				output: Number(tuple[4]) || 0,
@@ -431,15 +864,70 @@ export async function loadUsageCache(cachePath: string): Promise<Map<string, Cac
 			});
 		}
 		if (!valid) continue;
+		const toolUsages: ToolUsageRecord[] = [];
+		for (const tuple of entry.toolUsages) {
+			if (!Array.isArray(tuple) || tuple.length !== 5 || !Array.isArray(tuple[4])) {
+				valid = false;
+				break;
+			}
+			const sourceId = names[tuple[0]];
+			const runId = names[tuple[3]];
+			const reportedUsage = cachedUsageAmount(tuple[2]);
+			if (typeof sourceId !== "string" || typeof runId !== "string" || (tuple[2] !== null && !reportedUsage)) {
+				valid = false;
+				break;
+			}
+			const children: ChildToolUsage[] = [];
+			for (const childTuple of tuple[4]) {
+				if (!Array.isArray(childTuple) || childTuple.length !== 3) {
+					valid = false;
+					break;
+				}
+				const sessionFile = names[childTuple[1]];
+				const usage = cachedUsageAmount(childTuple[2]);
+				if (typeof childTuple[0] !== "number" || typeof sessionFile !== "string" || !usage) {
+					valid = false;
+					break;
+				}
+				children.push({ resultIndex: childTuple[0], sessionFile, usage });
+			}
+			if (!valid) break;
+			toolUsages.push({
+				sourceId,
+				timestamp: Number(tuple[1]) || 0,
+				reportedUsage,
+				runId,
+				children,
+			});
+		}
+		if (!valid) continue;
 		result.set(filePath, {
 			size: entry.size,
 			mtimeMs: entry.mtimeMs,
-			parsed: { sessionId: entry.sessionId, cwd: entry.cwd, messages },
+			parsed: { sessionId: entry.sessionId, cwd: entry.cwd, messages, toolUsages },
 		});
 	}
 	return result;
 }
 
+function cachedUsageAmount(value: unknown): UsageAmount | null {
+	if (!Array.isArray(value) || value.length !== 6 || value.some((part) => typeof part !== "number" || !Number.isFinite(part))) {
+		return null;
+	}
+	return {
+		cost: value[0],
+		input: value[1],
+		output: value[2],
+		cacheRead: value[3],
+		cacheWrite: value[4],
+		reasoning: value[5],
+	};
+}
+
+function cacheUsageAmount(usage: UsageAmount): CachedUsageTuple {
+	return [usage.cost, usage.input, usage.output, usage.cacheRead, usage.cacheWrite, usage.reasoning];
+}
+
 export async function saveUsageCache(cachePath: string, states: Map<string, CachedFileState>): Promise<void> {
 	const names: string[] = [];
 	const nameIndex = new Map<string, number>();
@@ -472,6 +960,19 @@ export async function saveUsageCache(cachePath: string, states: Map<string, Cach
 				intern(m.thinkingLevel),
 				m.reasoning,
 				m.afterCompaction ? 1 : 0,
+				m.source === "auxiliary" ? 1 : 0,
+				intern(m.source === "auxiliary" ? m.sourceId : ""),
+			]),
+			toolUsages: state.parsed.toolUsages.map((tool): CachedToolUsageTuple => [
+				intern(tool.sourceId),
+				tool.timestamp,
+				tool.reportedUsage ? cacheUsageAmount(tool.reportedUsage) : null,
+				intern(tool.runId),
+				tool.children.map((child): CachedChildToolUsageTuple => [
+					child.resultIndex,
+					intern(child.sessionFile),
+					cacheUsageAmount(child.usage),
+				]),
 			]),
 		};
 	}
@@ -511,7 +1012,8 @@ function emptyTimeFilteredStats(): TimeFilteredStats {
 function emptyPeriodRawData(): PeriodRawData {
 	return {
 		totalCost: 0,
-		totalMessages: 0,
+		assistantCost: 0,
+		auxiliaryCost: 0,
 		ctxHigh: { cost: 0, messages: 0 },
 		ctxLow: { cost: 0, messages: 0 },
 		projectCosts: new Map(),
@@ -581,7 +1083,7 @@ function addToHourlyBuckets(hourly: Map<number, Map<HourlyKey, HourlyCell>>, msg
 		cell = { messages: 0, cost: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0 };
 		bucket.set(key, cell);
 	}
-	cell.messages++;
+	if (msg.source === "assistant") cell.messages++;
 	cell.cost += msg.cost;
 	cell.input += msg.input;
 	cell.output += msg.output;
@@ -594,9 +1096,10 @@ function addToHourlyBuckets(hourly: Map<number, Map<HourlyKey, HourlyCell>>, msg
 function accumulateStats(
 	target: BaseStats,
 	cost: number,
-	tokens: { total: number; input: number; output: number; cacheRead: number; cacheWrite: number }
+	tokens: { total: number; input: number; output: number; cacheRead: number; cacheWrite: number },
+	countMessage: boolean
 ): void {
-	target.messages++;
+	if (countMessage) target.messages++;
 	target.cost += cost;
 	target.tokens.total += tokens.total;
 	target.tokens.input += tokens.input;
@@ -683,18 +1186,30 @@ function addMessagesToUsageData(
 				providerStats.models.set(msg.model, modelStats);
 			}
 
+			const isAssistant = msg.source === "assistant";
 			modelStats.sessions.add(sessionId);
-			accumulateStats(modelStats, msg.cost, tokens);
+			accumulateStats(modelStats, msg.cost, tokens, isAssistant);
 
 			providerStats.sessions.add(sessionId);
-			accumulateStats(providerStats, msg.cost, tokens);
+			accumulateStats(providerStats, msg.cost, tokens, isAssistant);
 
-			accumulateStats(stats.totals, msg.cost, tokens);
+			accumulateStats(stats.totals, msg.cost, tokens, isAssistant);
 			sessionContributed[period] = true;
 
 			const raw = rawByPeriod[period];
 			raw.totalCost += msg.cost;
-			raw.totalMessages++;
+			raw.projectCosts.set(project, (raw.projectCosts.get(project) ?? 0) + msg.cost);
+			raw.sessionCosts.set(sessionId, (raw.sessionCosts.get(sessionId) ?? 0) + msg.cost);
+
+			// Auxiliary calls belong in accounting totals, project/session mix, and
+			// burn trend. They are not assistant turns, so do not let their synthetic
+			// model identity or nested context distort turn/cache insights.
+			if (!isAssistant) {
+				raw.auxiliaryCost += msg.cost;
+				continue;
+			}
+			raw.assistantCost += msg.cost;
+
 			const ctx = msg.input + msg.cacheRead + msg.cacheWrite;
 			if (ctx >= CTX_TAX_THRESHOLD) {
 				raw.ctxHigh.cost += msg.cost;
@@ -703,8 +1218,6 @@ function addMessagesToUsageData(
 				raw.ctxLow.cost += msg.cost;
 				raw.ctxLow.messages++;
 			}
-			raw.projectCosts.set(project, (raw.projectCosts.get(project) ?? 0) + msg.cost);
-			raw.sessionCosts.set(sessionId, (raw.sessionCosts.get(sessionId) ?? 0) + msg.cost);
 			if (mm.isSessionStart) raw.upfrontCost += msg.cost;
 			if (
 				!msg.afterCompaction &&
@@ -729,6 +1242,103 @@ function addMessagesToUsageData(
 	if (sessionContributed.allTime) data.allTime.totals.sessions++;
 }
 
+// =============================================================================
+// Nested tool-usage accounting
+// =============================================================================
+
+// Recognised nested-agent tool results report usage for child runs that
+// pi-subagents also persists as ordinary session files, which this scan
+// already counts with full model attribution. When every child session file
+// behind a report is part of the scan, the children speak for themselves and
+// the parent's aggregate is skipped. Otherwise the aggregate (or, for pre-0.81
+// legacy entries, each unresolved child's reported usage) is counted under
+// Tools / summaries.
+//
+// Copied branch history gets a new parent filename, so a copy's runId-derived
+// child paths can dangle even though the original's resolve. Resolved child
+// identities are therefore unioned across all copies of an entry before any
+// emission, and identical emissions collapse in the sourceId dedupe.
+
+interface ScannedSessionIndex {
+	/** Resolved paths of scanned files that have a session header. */
+	paths: Set<string>;
+	/** Directory of each scanned file → number of scanned files inside it. */
+	fileCountByDir: Map<string, number>;
+}
+
+function buildScannedSessionIndex(states: Map<string, CachedFileState>): ScannedSessionIndex {
+	const paths = new Set<string>();
+	const fileCountByDir = new Map<string, number>();
+	for (const [filePath, state] of states) {
+		if (!state.parsed.sessionId) continue;
+		const resolved = resolve(filePath);
+		paths.add(resolved);
+		const dir = dirname(resolved);
+		fileCountByDir.set(dir, (fileCountByDir.get(dir) ?? 0) + 1);
+	}
+	return { paths, fileCountByDir };
+}
+
+function childSessionScanned(
+	parentFilePath: string,
+	tool: ToolUsageRecord,
+	child: ChildToolUsage,
+	index: ScannedSessionIndex
+): boolean {
+	if (child.sessionFile) {
+		const explicit = isAbsolute(child.sessionFile)
+			? resolve(child.sessionFile)
+			: resolve(dirname(parentFilePath), child.sessionFile);
+		if (index.paths.has(explicit)) return true;
+	}
+	if (tool.runId) {
+		const runDir = resolve(dirname(parentFilePath), basename(parentFilePath, ".jsonl"), tool.runId, `run-${child.resultIndex}`);
+		// The run directory holds exactly one session per child run, so either the
+		// conventional name or a lone scanned file inside it identifies the child.
+		if (index.paths.has(join(runDir, "session.jsonl"))) return true;
+		if (index.fileCountByDir.get(runDir) === 1) return true;
+	}
+	return false;
+}
+
+/** Identity of one child slot of one tool entry, stable across copied history. */
+function toolChildIdentity(tool: ToolUsageRecord, child: ChildToolUsage): string {
+	const fingerprint = child.usage.input + child.usage.output + child.usage.cacheRead + child.usage.cacheWrite;
+	return `${tool.sourceId}:${tool.timestamp}:${child.resultIndex}:${fingerprint}`;
+}
+
+function resolvedToolChildIdentities(states: Map<string, CachedFileState>, index: ScannedSessionIndex): Set<string> {
+	const resolved = new Set<string>();
+	for (const [filePath, state] of states) {
+		for (const tool of state.parsed.toolUsages) {
+			if (!tool.sourceId) continue;
+			for (const child of tool.children) {
+				if (childSessionScanned(filePath, tool, child, index)) resolved.add(toolChildIdentity(tool, child));
+			}
+		}
+	}
+	return resolved;
+}
+
+function toolUsageMessages(
+	parentFilePath: string,
+	tool: ToolUsageRecord,
+	index: ScannedSessionIndex,
+	resolvedChildren: Set<string>
+): SessionMessage[] {
+	const scanned = (child: ChildToolUsage) =>
+		childSessionScanned(parentFilePath, tool, child, index) ||
+		(tool.sourceId !== "" && resolvedChildren.has(toolChildIdentity(tool, child)));
+	if (tool.reportedUsage) {
+		if (tool.children.length > 0 && tool.children.every(scanned)) return [];
+		return [auxiliaryMessage(tool.reportedUsage, tool.timestamp, tool.sourceId)];
+	}
+	// Before Pi 0.81, recognised nested-agent tools persisted per-child usage in
+	// details only. Count just the children whose sessions this scan cannot see.
+	return tool.children
+		.filter((child) => !scanned(child))
+		.map((child) => auxiliaryMessage(child.usage, tool.timestamp, tool.sourceId ? `${tool.sourceId}:child:${child.resultIndex}` : ""));
+}
 // =============================================================================
 // Collection orchestration
 // =============================================================================
@@ -925,6 +1535,8 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 	const costByDayIdx = new Map<number, number>();
 	const seenSessions = new Set<string>();
 	const seenHashes = new Set<string>();
+	const scannedSessions = buildScannedSessionIndex(current);
+	const resolvedToolChildren = resolvedToolChildIdentities(current, scannedSessions);
 	let processedFiles = 0;
 
 	for (const filePath of filePaths) {
@@ -939,15 +1551,26 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 		// Deduplicate copied history across branched session files, computing
 		// adjacency metadata (idle gaps, previous context) on the raw file order
 		// so branch copies do not distort miss classification.
-		const rawMsgs = state.parsed.messages;
+		const toolMessages = state.parsed.toolUsages.flatMap((tool) => toolUsageMessages(filePath, tool, scannedSessions, resolvedToolChildren));
+		const rawMsgs = toolMessages.length > 0 ? [...state.parsed.messages, ...toolMessages] : state.parsed.messages;
 		const deduped: SessionMessage[] = [];
 		const meta: MessageMeta[] = [];
-		for (let i = 0; i < rawMsgs.length; i++) {
-			const m = rawMsgs[i]!;
-			const hash = `${m.timestamp}:${m.input + m.output + m.cacheRead + m.cacheWrite}`;
+		let previousAssistant: SessionMessage | null = null;
+		for (const m of rawMsgs) {
+			// Auxiliary usage is interleaved with conversation entries, but it must
+			// not become the "previous message" for cache-miss classification.
+			const prev = m.source === "assistant" ? previousAssistant : null;
+			if (m.source === "assistant") previousAssistant = m;
+
+			// Pi entry ids survive copied branch history and distinguish parallel
+			// tool results that happen to report identical usage in the same ms.
+			const tokenFingerprint = m.input + m.output + m.cacheRead + m.cacheWrite;
+			const hash =
+				m.source === "auxiliary" && m.sourceId
+					? `auxiliary:${m.sourceId}:${m.timestamp}:${tokenFingerprint}`
+					: `${m.source}:${m.timestamp}:${tokenFingerprint}`;
 			if (seenHashes.has(hash)) continue;
 			seenHashes.add(hash);
-			const prev = i > 0 ? rawMsgs[i - 1]! : null;
 			deduped.push(m);
 			meta.push({
 				gapMs: prev && prev.timestamp > 0 && m.timestamp > 0 ? m.timestamp - prev.timestamp : -1,
@@ -957,9 +1580,10 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 			});
 		}
 		if (deduped.length === 0) continue;
-		if (!seenSessions.has(state.parsed.sessionId)) {
+		const firstAssistantIndex = deduped.findIndex((m) => m.source === "assistant");
+		if (firstAssistantIndex !== -1 && !seenSessions.has(state.parsed.sessionId)) {
 			seenSessions.add(state.parsed.sessionId);
-			meta[0]!.isSessionStart = true;
+			meta[firstAssistantIndex]!.isSessionStart = true;
 		}
 
 		addMessagesToUsageData(
@@ -1045,42 +1669,44 @@ function fmtPercent(p: number): string {
  * distinct empty-state for that case.
  */
 function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodInsights {
-	if (raw.totalMessages === 0 || raw.totalCost <= 0) {
+	if (raw.totalCost <= 0) {
 		return { insights: [] };
 	}
 	const total = raw.totalCost;
+	const assistantTotal = raw.assistantCost;
+	const assistantPctLabel = raw.auxiliaryCost > 0 ? "assistant-message cost" : "this period";
 	const insights: Insight[] = [];
 
 	// --- Alarms (listed first) ---
 
-	const ttlPct = (raw.ttlMissCost / total) * 100;
+	const ttlPct = assistantTotal > 0 ? (raw.ttlMissCost / assistantTotal) * 100 : 0;
 	if (ttlPct >= CACHE_MISS_ALARM_PERCENT && raw.ttlMissCost >= CACHE_MISS_ALARM_MIN_COST) {
 		insights.push({
 			kind: "alarm",
 			stat: fmtMoney(raw.ttlMissCost),
-			headline: `spent resuming conversations after a break (${fmtPercent(ttlPct)} of this period)`,
+			headline: `spent resuming conversations after a break (${fmtPercent(ttlPct)} of ${assistantPctLabel})`,
 			advice:
 				"Sent context is only reusable for a few minutes. After a longer pause, the next message pays to send the whole conversation again. Replying while a session is fresh avoids this.",
 		});
 	}
 
-	const switchPct = (raw.modelSwitchMissCost / total) * 100;
+	const switchPct = assistantTotal > 0 ? (raw.modelSwitchMissCost / assistantTotal) * 100 : 0;
 	if (switchPct >= CACHE_MISS_ALARM_PERCENT && raw.modelSwitchMissCost >= CACHE_MISS_ALARM_MIN_COST) {
 		insights.push({
 			kind: "alarm",
 			stat: fmtMoney(raw.modelSwitchMissCost),
-			headline: `spent switching models mid-conversation (${fmtPercent(switchPct)} of this period)`,
+			headline: `spent switching models mid-conversation (${fmtPercent(switchPct)} of ${assistantPctLabel})`,
 			advice:
 				"Changing model re-sends the whole conversation at full price — the previous model's saved context doesn't transfer. Switching between tasks instead of mid-conversation avoids this.",
 		});
 	}
 
-	const prefixPct = (raw.prefixMissCost / total) * 100;
+	const prefixPct = assistantTotal > 0 ? (raw.prefixMissCost / assistantTotal) * 100 : 0;
 	if (prefixPct >= CACHE_MISS_ALARM_PERCENT && raw.prefixMissCost >= CACHE_MISS_ALARM_MIN_COST) {
 		insights.push({
 			kind: "alarm",
 			stat: fmtMoney(raw.prefixMissCost),
-			headline: `spent re-sending conversations mid-session (${fmtPercent(prefixPct)} of this period)`,
+			headline: `spent re-sending conversations mid-session (${fmtPercent(prefixPct)} of ${assistantPctLabel})`,
 			advice:
 				"These messages paid full price for context that had already been sent — with no break, compaction, or model switch to explain it. Usually a tool or workflow is restarting or rewriting conversations. Worth a look if it stays high.",
 		});
@@ -1100,17 +1726,17 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 		}
 	}
 
-	const upfrontPct = (raw.upfrontCost / total) * 100;
+	const upfrontPct = assistantTotal > 0 ? (raw.upfrontCost / assistantTotal) * 100 : 0;
 	if (upfrontPct >= UPFRONT_ALARM_PERCENT) {
 		insights.push({
 			kind: "alarm",
 			stat: fmtMoney(raw.upfrontCost),
-			headline: `spent on the opening message of new sessions (${fmtPercent(upfrontPct)} of this period)`,
+			headline: `spent on the opening message of new sessions (${fmtPercent(upfrontPct)} of ${assistantPctLabel})`,
 			advice: "A session's first message sends everything from scratch. Fewer, longer sessions cut this overhead.",
 		});
 	}
 
-	if (total >= LEVERAGE_MIN_COST && raw.freshTokens >= LEVERAGE_MIN_FRESH_TOKENS) {
+	if (assistantTotal >= LEVERAGE_MIN_COST && raw.freshTokens >= LEVERAGE_MIN_FRESH_TOKENS) {
 		const leverage = raw.cacheReadTokens / raw.freshTokens;
 		if (leverage < LEVERAGE_FLOOR) {
 			insights.push({
@@ -1125,8 +1751,20 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 
 	// --- Structure (always-on) ---
 
-	if (raw.ctxHigh.messages > 0) {
-		const pct = (raw.ctxHigh.cost / total) * 100;
+	if (raw.auxiliaryCost > 0) {
+		const pct = (raw.auxiliaryCost / total) * 100;
+		if (pct >= 1) {
+			insights.push({
+				kind: "structure",
+				stat: fmtPercent(pct),
+				headline: "of your cost came from usage reported by tools and conversation summaries",
+				advice: "Pi records this separately because it cannot be attributed reliably to a specific provider and model.",
+			});
+		}
+	}
+
+	if (raw.ctxHigh.messages > 0 && assistantTotal > 0) {
+		const pct = (raw.ctxHigh.cost / assistantTotal) * 100;
 		if (pct >= 1) {
 			const avgHigh = raw.ctxHigh.cost / raw.ctxHigh.messages;
 			const avgLow = raw.ctxLow.messages > 0 ? raw.ctxLow.cost / raw.ctxLow.messages : 0;
@@ -1137,7 +1775,7 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 			insights.push({
 				kind: "structure",
 				stat: fmtPercent(pct),
-				headline: `of your cost came from messages with ≥${formatThresholdTokens(CTX_TAX_THRESHOLD)} tokens loaded${cmp}`,
+				headline: `of your ${raw.auxiliaryCost > 0 ? "assistant-message cost" : "cost"} came from messages with ≥${formatThresholdTokens(CTX_TAX_THRESHOLD)} tokens loaded${cmp}`,
 				advice: "Long conversations cost more per message. /compact mid-task and /clear between tasks keep them lean.",
 			});
 		}

package/index.ts

@@ -673,7 +673,11 @@ class UsageComponent {
 		const th = this.theme;
 		const stats = this.data[this.activeTab];
 		const { insights } = stats.insights;
-		const hasMessages = stats.totals.messages > 0;
+		const hasUsage =
+			stats.totals.messages > 0 ||
+			stats.totals.cost > 0 ||
+			stats.totals.tokens.total > 0 ||
+			stats.totals.tokens.cacheRead > 0;
 		const hasCost = stats.totals.cost > 0;
 		const lines: string[] = [];
 
@@ -687,7 +691,7 @@ class UsageComponent {
 		}
 		lines.push("");
 
-		if (!hasMessages) {
+		if (!hasUsage) {
 			lines.push(th.fg("dim", "  No usage recorded for this period."));
 			lines.push("");
 			return lines;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-usage-extension",
-  "version": "0.9.1",
+  "version": "0.9.4",
   "description": "Usage statistics dashboard for Pi sessions.",
   "license": "MIT",
   "author": "Thomas Mustier",