@humwick/runner 0.0.0-stage → 0.130.0

package/src/adapters/claude-transcript.ts

@@ -0,0 +1,812 @@
+// Phase 1 live-session lane: extract the user-visible assistant turn from a
+// Claude Code transcript JSONL so it can be surfaced in the dashboard chat
+// without the agent re-emitting it via /reply (zero agent tokens).
+//
+// Transcript shape (one JSON object per line):
+//   { type: "user", message: { content: "..." | [{type:"text"|"tool_result", ...}] } }
+//   { type: "assistant", message: { content: [{type:"thinking"|"text"|"tool_use", ...}], stop_reason } }
+//
+// The "current turn" is everything after the last *real* user prompt (a user
+// entry carrying text, not just tool_result blocks). We collect the assistant
+// `text` blocks from that turn — thinking and tool_use are dropped.
+
+import { isRecord, type ToolCallCategory } from "@humwick/sdk";
+import type { ProviderSessionEvent } from "../adapter";
+import { computeContextRatio, type SessionAnalysis, type SessionEvent } from "../session-insights";
+import { absoluteToolPaths, clipToolSummary, redactAndCapParams, summarizeToolInput } from "./tool-summary";
+
+interface TranscriptBlock {
+  type?: string;
+  text?: string;
+  thinking?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  is_error?: boolean;
+  id?: string;
+  tool_use_id?: string;
+}
+
+export interface TurnStep {
+  type: "narration" | "reasoning" | "tool";
+  text: string;
+  label?: string;
+  category?: ToolCallCategory;
+  occurredAt?: number;
+  /** #2437 — redacted, size-capped tool input, only set for type "tool". */
+  params?: unknown;
+  /** The native tool_use id, only set for type "tool"; pairs the call with its tool_result. */
+  toolUseId?: string;
+  /** #3411 — absolute file paths the tool reads or edits, only set for type "tool". */
+  paths?: string[];
+}
+
+export interface TranscriptMessage {
+  role?: string;
+  content?: string | TranscriptBlock[];
+  stop_reason?: string;
+  // Assistant entries carry the model id and the API-reported token usage for
+  // the turn. `usage.{input,cache_creation_input,cache_read_input}_tokens` sum to
+  // the same context-size figure the status-line probe reports — read here so the
+  // runner can keep context stats advancing every turn without the probe (#1512).
+  model?: string;
+  usage?: TranscriptUsage;
+}
+
+export interface TranscriptUsage {
+  input_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+  output_tokens?: number;
+}
+
+/** Fresh, per-turn context usage read straight from the transcript (#1512). */
+export interface TranscriptContextUsage {
+  /** input + cache-creation + cache-read tokens — the context size sent this turn. */
+  tokensUsed: number;
+  model?: string;
+  /** Wall-clock ms of the assistant entry, when the transcript stamps one. */
+  occurredAt?: number;
+}
+
+interface TranscriptEntry {
+  type?: string;
+  timestamp?: string;
+  message?: TranscriptMessage;
+  // Claude Code stamps every transcript entry with `isSidechain`: true for
+  // entries belonging to a Task (subagent) run, false for the root session.
+  // Current CC writes sidechains to a separate subagents/*.jsonl so they don't
+  // reach the root transcript the runner tails — but older CC inlined them, and
+  // the behavior can revert, so the chat-mirror parsers below defensively skip
+  // sidechain entries to keep a subagent's reasoning/tools/responses from
+  // leaking into the parent agent's chat. Insights parsers (collectClaudeSession-
+  // Events/countSubstantiveTurns) intentionally do NOT filter — changing them
+  // would shift the #184/#185 baselines, a separate concern.
+  isSidechain?: boolean;
+  // Every entry carries its own `uuid` and its `parentUuid` (the entry it was
+  // appended after), forming a causal chain for the whole session. A `user`-type
+  // entry — whether the real prompt or a synthetic tool_result — is stamped with
+  // `promptId`: the same UUID Claude's Stop-hook payload reports as `prompt_id`,
+  // shared by every entry from that prompt until the next one. Assistant entries
+  // don't carry `promptId` directly; their turn is resolved by walking `parentUuid`
+  // back to the nearest ancestor that has one (see resolveEntryPromptId).
+  uuid?: string;
+  parentUuid?: string;
+  promptId?: string;
+}
+
+function blocks(message: TranscriptMessage | undefined): TranscriptBlock[] {
+  if (!message || !Array.isArray(message.content)) return [];
+  return message.content.filter((b): b is TranscriptBlock => Boolean(b) && typeof b === "object");
+}
+
+/** True for a subagent (Task) transcript entry — see the note on TranscriptEntry.isSidechain. */
+function isSidechainEntry(entry: TranscriptEntry): boolean {
+  return entry.isSidechain === true;
+}
+
+function isRealUserPrompt(entry: TranscriptEntry): boolean {
+  if (entry.type !== "user") return false;
+  const content = entry.message?.content;
+  if (typeof content === "string") return content.trim().length > 0;
+  // An array user entry is a real prompt only if it carries a text block;
+  // pure tool_result entries are mid-turn plumbing, not a new prompt.
+  return blocks(entry.message).some((b) => b.type === "text" && Boolean(b.text?.trim()));
+}
+
+// #2840 — `closingOnly` keeps just the text after the turn's last tool call (the closing message,
+// without narration the reasoning tail already mirrored); a turn ending on a tool keeps its last text.
+class AssistantTurnText {
+  private texts: string[] = [];
+  private lastSegment: string[] = [];
+  constructor(private readonly closingOnly: boolean) {}
+
+  reset(): void {
+    this.texts = [];
+    this.lastSegment = [];
+  }
+
+  add(entry: TranscriptEntry): void {
+    if (entry.type !== "assistant") return;
+    for (const b of blocks(entry.message)) {
+      if (this.closingOnly && b.type === "tool_use") {
+        if (this.texts.length) this.lastSegment = this.texts;
+        this.texts = [];
+      } else if (b.type === "text" && typeof b.text === "string" && b.text.trim()) this.texts.push(b.text.trim());
+    }
+  }
+
+  text(): string {
+    return (this.texts.length ? this.texts : this.lastSegment).join("\n\n").trim();
+  }
+}
+
+/**
+ * Returns true when the transcript's final parseable entry is an assistant
+ * message with stop_reason "end_turn", meaning the full turn has been flushed.
+ * Used to detect a race where the Stop hook reads the file before the last
+ * assistant block is written to disk.
+ */
+export function transcriptLooksComplete(jsonl: string): boolean {
+  const state = new LatestTurnStepAccumulator();
+  state.appendJsonl(jsonl);
+  return state.transcriptLooksComplete;
+}
+
+/**
+ * Returns the concatenated assistant `text` for the most recent turn (since the
+ * last real user prompt), or "" if there is nothing user-visible to surface.
+ */
+export function extractLastAssistantTurn(jsonl: string, closingOnly = false): string {
+  const lines = jsonl.split("\n");
+  const collected = new AssistantTurnText(closingOnly);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (isSidechainEntry(entry)) continue;
+    if (isRealUserPrompt(entry)) {
+      collected.reset();
+      continue;
+    }
+    collected.add(entry);
+  }
+  return collected.text();
+}
+
+/**
+ * Like extractLastAssistantTurn but skips the first `afterEntry` valid JSON entries.
+ * Used when a partial transcript flush already emitted entries 1..afterEntry so the
+ * Stop-hook full-mode capture doesn't re-emit the already-published text.
+ */
+export function extractLastAssistantTurnAfterEntry(jsonl: string, afterEntry: number, closingOnly = false): string {
+  const lines = jsonl.split("\n");
+  const collected = new AssistantTurnText(closingOnly);
+  let entryIndex = 0;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    entryIndex++;
+    if (isSidechainEntry(entry)) continue;
+    if (isRealUserPrompt(entry)) {
+      collected.reset();
+      continue;
+    }
+    if (entryIndex <= afterEntry) continue;
+    collected.add(entry);
+  }
+  return collected.text();
+}
+
+/**
+ * Resolve the `promptId` (Stop hook's `prompt_id`) a transcript entry belongs to.
+ * A `user`-type entry (the real prompt, or a synthetic tool_result) carries its own
+ * `promptId`; an assistant entry doesn't, so its turn is resolved by walking
+ * `parentUuid` back through the causal chain until an ancestor with one is found.
+ * Returns undefined for an entry with no resolvable ancestor (e.g. the very first
+ * turn of a process, before any `promptId` has ever been stamped).
+ */
+function resolveEntryPromptId(entry: TranscriptEntry, byUuid: ReadonlyMap<string, TranscriptEntry>): string | undefined {
+  let current: TranscriptEntry | undefined = entry;
+  const visited = new Set<string>();
+  while (current) {
+    if (typeof current.promptId === "string" && current.promptId) return current.promptId;
+    const parentUuid = current.parentUuid;
+    if (!parentUuid || visited.has(parentUuid)) return undefined;
+    visited.add(parentUuid);
+    current = byUuid.get(parentUuid);
+  }
+  return undefined;
+}
+
+/**
+ * Deterministic replacement for extractLastAssistantTurnAfterEntry's "walk back to
+ * the last real user prompt" heuristic: collects assistant `text` blocks for entries
+ * whose resolved promptId (see resolveEntryPromptId) equals the Claude-native
+ * `promptId` the Stop hook reported for this turn. Skips the first `afterEntry`
+ * entries the same way, for pre-flush resume. Since entries never move once
+ * written, a turn's promptId membership is exact — no text-shape guessing about
+ * what counts as a "real" prompt.
+ */
+export function extractAssistantTurnForPrompt(jsonl: string, promptId: string, afterEntry = 0, closingOnly = false): string {
+  const lines = jsonl.split("\n");
+  const byUuid = new Map<string, TranscriptEntry>();
+  const collected = new AssistantTurnText(closingOnly);
+  let entryIndex = 0;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    entryIndex++;
+    if (typeof entry.uuid === "string" && entry.uuid) byUuid.set(entry.uuid, entry);
+    if (isSidechainEntry(entry)) continue;
+    if (entryIndex <= afterEntry) continue;
+    if (entry.type !== "assistant") continue;
+    if (resolveEntryPromptId(entry, byUuid) !== promptId) continue;
+    collected.add(entry);
+  }
+  return collected.text();
+}
+
+/**
+ * Count valid JSON entries in a JSONL string. Used to record the high-water-mark
+ * after a pre-flush so the Stop hook knows where to resume in full-capture mode.
+ */
+export function countTranscriptEntries(jsonl: string): number {
+  let count = 0;
+  for (const line of jsonl.split("\n")) {
+    if (!line.trim()) continue;
+    try { JSON.parse(line); count++; } catch {}
+  }
+  return count;
+}
+
+interface QueueOperationEntry extends TranscriptEntry {
+  operation?: string;
+  content?: unknown;
+}
+
+/**
+ * #2919 — prompts left in Claude's input queue at the end of `jsonl`: a mid-turn prompt is `enqueue`d,
+ * then `remove`d when a tool boundary absorbs it, or `dequeue`d (every queued prompt at once) to run as
+ * the next turn after the Stop. So a dequeue or a new promptId empties the queue.
+ */
+export function pendingQueuedPrompts(jsonl: string): string[] {
+  let pending: string[] = [];
+  let promptId: string | undefined;
+  for (const line of jsonl.split("\n")) {
+    if (!line.includes("\"queue-operation\"") && !line.includes("\"promptId\"")) continue;
+    let entry: QueueOperationEntry;
+    try {
+      entry = JSON.parse(line) as QueueOperationEntry;
+    } catch {
+      continue;
+    }
+    if (isSidechainEntry(entry)) continue;
+    if (entry.promptId && entry.promptId !== promptId) {
+      promptId = entry.promptId;
+      pending = [];
+    }
+    if (entry.type !== "queue-operation") continue;
+    const content = typeof entry.content === "string" ? entry.content : undefined;
+    if (entry.operation === "dequeue") pending = [];
+    else if (entry.operation === "enqueue" && content !== undefined) pending.push(content);
+    else if (entry.operation === "remove" && content !== undefined && pending.includes(content)) pending.splice(pending.indexOf(content), 1);
+  }
+  return pending;
+}
+
+/** Key-order-independent structural equality, cheap enough for a small tool_input object. */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * True when the transcript already contains the exact assistant tool_use block that
+ * triggered a PreToolUse hook — the settle-poll anchor (#1116). The hook payload's own
+ * `tool_name`/`tool_input` are the precise call that fired it, so matching them against
+ * the transcript's tool_use blocks (name + structural input equality) is exact, unlike
+ * guessing from transcript shape alone. Claude's JSONL flush is async/bursty and can
+ * lag well behind the hook firing, so the entry backing the hook's own call may still be
+ * missing from disk the instant the hook runs — this is what the settle-poll waits for.
+ * #1086 should adopt this same anchor for its own turn-final settle marker rather than
+ * inventing a second one.
+ */
+export function transcriptHasToolUseAnchor(jsonl: string, toolName: string, toolInput: unknown): boolean {
+  const wantInput = canonicalJson(toolInput ?? {});
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "assistant" || isSidechainEntry(entry)) continue;
+    for (const block of blocks(entry.message)) {
+      if (block.type === "tool_use" && block.name === toolName && canonicalJson(block.input ?? {}) === wantInput) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * The transcript-embedded `timestamp` of the specific assistant entry carrying the exact
+ * tool_use block that triggered a PreToolUse hook (same anchor match as
+ * transcriptHasToolUseAnchor above). Used to stamp a resolved permission prompt with the
+ * tool call's real event time — a hook's own wall-clock receipt time can end up earlier than
+ * the entry the provider eventually flushes for that same call, which otherwise sorts the
+ * resolved prompt ahead of the narration that led up to it (#1185).
+ */
+export function transcriptToolUseOccurredAt(jsonl: string, toolName: string, toolInput: unknown): number | undefined {
+  const wantInput = canonicalJson(toolInput ?? {});
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "assistant" || isSidechainEntry(entry)) continue;
+    for (const block of blocks(entry.message)) {
+      if (block.type === "tool_use" && block.name === toolName && canonicalJson(block.input ?? {}) === wantInput) {
+        return transcriptEntryOccurredAt(entry);
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extract the ordered narration, reasoning, and tool steps for the most recent
+ * turn (since the last real user prompt). Used by the reasoning tailer to stream
+ * progress into chat while a turn is in flight. `narration` is the assistant's
+ * intermediate `text` between tool calls (the terminal's `●` lines); it is the
+ * primary, default-visible turn content. Returns steps in transcript order so the
+ * tailer can emit only the ones it hasn't seen yet.
+ */
+export function extractLatestTurnSteps(jsonl: string): TurnStep[] {
+  const state = new LatestTurnStepAccumulator();
+  state.appendJsonl(jsonl);
+  return state.steps;
+}
+
+export class LatestTurnStepAccumulator {
+  private latestSteps: TurnStep[] = [];
+  private newUserPrompts: Array<{ text: string; occurredAt?: number }> = [];
+  private lastAssistantStopReason: string | undefined;
+  private parsedEntries = 0;
+  private latestPromptId: string | undefined;
+
+  get steps(): TurnStep[] {
+    return [...this.latestSteps];
+  }
+
+  get transcriptLooksComplete(): boolean {
+    return this.lastAssistantStopReason === "end_turn";
+  }
+
+  get entryCount(): number {
+    return this.parsedEntries;
+  }
+
+  /** Claude's native prompt id for the latest turn, when its prompt entry carries one. */
+  get promptId(): string | undefined {
+    return this.latestPromptId;
+  }
+
+  drainUserPrompts(): Array<{ text: string; occurredAt?: number }> {
+    const prompts = this.newUserPrompts;
+    this.newUserPrompts = [];
+    return prompts;
+  }
+
+  reset(): void {
+    this.latestSteps = [];
+    this.newUserPrompts = [];
+    this.lastAssistantStopReason = undefined;
+    this.parsedEntries = 0;
+    this.latestPromptId = undefined;
+  }
+
+  appendJsonl(jsonl: string): void {
+    for (const line of jsonl.split("\n")) this.appendLine(line);
+  }
+
+  appendLine(line: string): void {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      return;
+    }
+    this.parsedEntries += 1;
+    if (isSidechainEntry(entry)) return;
+    if (entry.type === "assistant") this.lastAssistantStopReason = entry.message?.stop_reason;
+    if (isRealUserPrompt(entry)) {
+      const content = entry.message?.content;
+      const text = typeof content === "string" ? content : blocks(entry.message).filter((block) => block.type === "text").map((block) => block.text ?? "").join("\n");
+      this.newUserPrompts.push({ text, occurredAt: transcriptEntryOccurredAt(entry) });
+      this.latestSteps = [];
+      this.latestPromptId = entry.promptId;
+      return;
+    }
+    if (entry.type !== "assistant") return;
+    this.latestSteps.push(...claudeAssistantSteps(entry.message, transcriptEntryOccurredAt(entry)));
+  }
+}
+
+/** Narration, reasoning and tool steps of one assistant message, shared by the transcript tail and the headless stream (#2771). */
+export function claudeAssistantSteps(message: TranscriptMessage | undefined, occurredAt?: number): TurnStep[] {
+  const steps: TurnStep[] = [];
+  for (const b of blocks(message)) {
+    if (b.type === "text" && typeof b.text === "string" && b.text.trim()) {
+      steps.push({ type: "narration", text: b.text.trim(), ...(occurredAt ? { occurredAt } : {}) });
+    } else if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.trim()) {
+      steps.push({ type: "reasoning", text: b.thinking.trim(), ...(occurredAt ? { occurredAt } : {}) });
+    } else if (b.type === "tool_use" && typeof b.name === "string" && b.name) {
+      const paths = claudeToolPaths(b.name, b.input);
+      steps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input), category: claudeToolCategory(b.name), params: redactAndCapParams(b.input), ...(typeof b.id === "string" && b.id ? { toolUseId: b.id } : {}), ...(occurredAt ? { occurredAt } : {}), ...(paths ? { paths } : {}) });
+    }
+  }
+  return steps;
+}
+
+// #3411 — Claude's file tools and the input field naming their file. Keyed on the tool name, not the
+// category: MultiEdit is "generic". Claude's file tools take absolute paths only.
+const CLAUDE_TOOL_PATH_FIELDS: Record<string, string> = {
+  Read: "file_path",
+  Edit: "file_path",
+  MultiEdit: "file_path",
+  Write: "file_path",
+  NotebookEdit: "notebook_path",
+};
+
+/** The absolute file path a Claude file tool reads or edits, from its raw (uncapped) input. */
+export function claudeToolPaths(name: string, input: Record<string, unknown> | undefined): string[] | undefined {
+  const field = CLAUDE_TOOL_PATH_FIELDS[name];
+  return field && input ? absoluteToolPaths([input[field]]) : undefined;
+}
+
+/** The raw PostToolUse payload uses the same path contract as transcript tools (#3646). */
+export function claudeToolHookPaths(input: unknown): string[] | undefined {
+  return isRecord(input) && typeof input.tool_name === "string"
+    ? claudeToolPaths(input.tool_name, isRecord(input.tool_input) ? input.tool_input : undefined) : undefined;
+}
+
+/** The session event of one step, shared by the transcript tail and the headless stream. */
+export function turnStepEvent(step: TurnStep, turnId: string | undefined): ProviderSessionEvent {
+  return {
+    type: step.type,
+    origin: "provider",
+    body: step.text,
+    ...(step.occurredAt ? { occurredAt: step.occurredAt } : {}),
+    ...(turnId ? { turnId } : {}),
+    ...(step.label ? { label: step.label } : {}),
+    ...(step.category ? { category: step.category } : {}),
+    ...(step.params !== undefined ? { params: step.params } : {}),
+    ...(step.paths ? { paths: step.paths } : {}),
+  };
+}
+
+/** tool_use_id → error outcome for each tool_result block of a user message. */
+export function claudeToolResults(message: TranscriptMessage | undefined): Array<{ toolUseId: string; isError: boolean }> {
+  return blocks(message).flatMap((b) => b.type === "tool_result" && typeof b.tool_use_id === "string" ? [{ toolUseId: b.tool_use_id, isError: b.is_error === true }] : []);
+}
+
+function transcriptEntryOccurredAt(entry: TranscriptEntry): number | undefined {
+  if (typeof entry.timestamp !== "string" || !entry.timestamp) return undefined;
+  const parsed = Date.parse(entry.timestamp);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+/**
+ * Stable dedup keys for a turn's steps, in order. Each key is salted with how many
+ * identical (type,label,text) steps preceded it in the same window — so running the
+ * same tool twice with identical input within a turn yields two distinct keys and
+ * both show in the activity trace (#265). Keying on occurrence-within-window rather
+ * than raw transcript index keeps the reasoning tailer idempotent when the "latest
+ * turn" window shrinks/resets mid-poll: a surviving step recomputes to the same or a
+ * lower occurrence, so an already-emitted step never re-fires.
+ */
+export function stepDedupKeys(steps: TurnStep[]): string[] {
+  const counts = new Map<string, number>();
+  return steps.map((step) => {
+    const base = JSON.stringify([step.type, step.label ?? "", step.text]);
+    const occ = counts.get(base) ?? 0;
+    counts.set(base, occ + 1);
+    return JSON.stringify([step.type, step.label ?? "", step.text, occ]);
+  });
+}
+
+// #1498: Claude's native tool names → the provider-independent category taxonomy. Tools with
+// no dedicated category (Grep, Glob, LS, WebFetch, WebSearch, ...) fall to "generic" rather than
+// being force-fit into a category that doesn't really describe them — the fallback exists
+// precisely so nothing is hidden from the dashboard's activity trace.
+const CLAUDE_TOOL_CATEGORIES: Record<string, ToolCallCategory> = {
+  Bash: "cli-bash",
+  Read: "read",
+  Edit: "edit",
+  Write: "edit",
+  NotebookEdit: "edit",
+  AskUserQuestion: "ask-user-question",
+  ExitPlanMode: "plan",
+  Task: "agent-spawn",
+  ToolSearch: "mcp-tool-search",
+};
+
+/** Map a Claude tool_use name onto the provider-independent tool-call category (#1498). */
+export function claudeToolCategory(name: string): ToolCallCategory {
+  if (name.startsWith("mcp__")) return "mcp-tool-call";
+  return CLAUDE_TOOL_CATEGORIES[name] ?? "generic";
+}
+
+/** Compact one-line summary of a tool invocation for the discreet activity row. The one-line +
+ *  redact + clip is the provider-neutral primitive in `tool-summary.ts` (shared with Codex and
+ *  OpenCode); only the Claude-specific candidate-field order lives here. */
+export function summarizeToolUse(name: string, input: Record<string, unknown> | undefined): string {
+  const summary = summarizeToolInput(input);
+  if (!summary) return name;
+  return clipToolSummary(summary);
+}
+
+// --- Insights #184: context-gathering ratio (epic #183, docs/self-improvement.md) ---
+//
+// Computed mechanically from the whole-session transcript at session end — no model
+// involvement, so it costs zero agent tokens and the agent can't game it. The ratio is
+// paired with cheap outcome proxies (user re-prompts, tool errors) so it's never read
+// alone — see the anti-Goodhart constraint in the epic.
+
+/**
+ * Normalize a full Claude transcript into the provider-agnostic `SessionEvent` stream
+ * (#183/#184). The classifier and ratio math live in `session-insights.ts` and are shared
+ * across providers; this only knows the Claude JSONL shape. Events are emitted in
+ * transcript order so `leadingGather` is meaningful.
+ */
+export function collectClaudeSessionEvents(jsonl: string): SessionEvent[] {
+  const events: SessionEvent[] = [];
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (isRealUserPrompt(entry)) events.push({ type: "user_prompt" });
+    if (entry.type === "user") {
+      for (const b of blocks(entry.message)) {
+        if (b.type === "tool_result" && b.is_error === true) events.push({ type: "tool_error" });
+      }
+      continue;
+    }
+    if (entry.type !== "assistant") continue;
+    let producedSomething = false;
+    for (const b of blocks(entry.message)) {
+      if (b.type === "text" && b.text?.trim()) producedSomething = true;
+      if (b.type !== "tool_use" || typeof b.name !== "string" || !b.name) continue;
+      producedSomething = true;
+      events.push({ type: "tool", name: b.name });
+    }
+    if (producedSomething) events.push({ type: "turn" });
+  }
+  return events;
+}
+
+/**
+ * Walk the full transcript and compute the context-gathering ratio plus paired outcome
+ * proxies. Returns null when there's nothing substantive to measure (no tool calls) —
+ * trivial sessions have nothing to learn from and shouldn't pollute the baselines.
+ */
+export function analyzeSession(jsonl: string): SessionAnalysis | null {
+  return computeContextRatio(collectClaudeSessionEvents(jsonl));
+}
+
+/** Count substantive assistant turns — used by the #185 introspection gate. */
+export function countSubstantiveTurns(jsonl: string): number {
+  let turns = 0;
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "assistant") continue;
+    const hasContent = blocks(entry.message).some(
+      (b) => (b.type === "text" && b.text?.trim()) || (b.type === "tool_use" && b.name),
+    );
+    if (hasContent) turns++;
+  }
+  return turns;
+}
+
+// Walk the transcript from the end and return the most recent root-session
+// assistant turn's token usage (#1512). This is the SAME input+cache token sum
+// the Claude status-line probe reports, but read directly from the transcript —
+// which the Stop hook hands the runner every turn — so context stats keep
+// advancing across compact/clear/native-resume even when the status-line probe
+// goes silent. Sidechain (subagent) entries are skipped so a Task's usage never
+// masquerades as the root session's context size.
+export function extractLatestContextUsage(jsonl: string): TranscriptContextUsage | undefined {
+  const lines = jsonl.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const trimmed = lines[i]?.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "assistant" || isSidechainEntry(entry)) continue;
+    const usage = entry.message?.usage;
+    if (!usage) continue;
+    const tokensUsed = sumUsageTokens(usage);
+    if (tokensUsed === undefined) continue;
+    const occurredAt = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : NaN;
+    return {
+      tokensUsed,
+      ...(typeof entry.message?.model === "string" ? { model: entry.message.model } : {}),
+      ...(Number.isFinite(occurredAt) ? { occurredAt } : {}),
+    };
+  }
+  return undefined;
+}
+
+// Context size == prompt input tokens for the turn: fresh input + newly-cached
+// input + cache-read input. Matches the status-line probe's sum (output tokens
+// are excluded — they are not part of the context window carried forward).
+export function sumUsageTokens(usage: TranscriptUsage): number | undefined {
+  let total = 0;
+  let seen = false;
+  for (const value of [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens]) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      total += value;
+      seen = true;
+    }
+  }
+  return seen ? total : undefined;
+}
+
+// #2482 — the token-usage spine's capture parser. Where extractLatestContextUsage
+// collapses a turn's usage into one context-size sum, this sibling keeps the RAW
+// per-entry breakdown the spine records, one record per assistant transcript entry:
+//   dedupeKey = the entry `uuid` (entries never move once written, so the uuid is the
+//   stable turn-less key — replay-safe against the spine's dedupe_key upsert);
+//   createdAt = the entry `timestamp` (the provider's observed usage time, which the
+//   spine requires and never defaults from a receipt clock).
+// Sidechain (subagent) entries are skipped exactly as extractLatestContextUsage does —
+// a Task's usage is the subagent's own session's accounting, not the root turn's.
+export interface TranscriptTokenUsageEntry {
+  uuid: string;
+  /** The Stop hook's prompt_id this entry belongs to (resolved via the parentUuid chain). */
+  promptId?: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  occurredAt: number;
+  /** #3351 — an API assistant entry without a usage block: spend happened, counts are unknown. */
+  usageStatus?: "unknown";
+}
+
+export function extractTokenUsageEntries(jsonl: string, afterEntry = 0): TranscriptTokenUsageEntry[] {
+  const extractor = new TranscriptTokenUsageExtractor(afterEntry);
+  const entries: TranscriptTokenUsageEntry[] = [];
+  for (const line of jsonl.split("\n")) {
+    const entry = extractor.appendLine(line);
+    if (entry) entries.push(entry);
+  }
+  return entries;
+}
+
+/** One parseable transcript line → its spine usage record, or undefined when the line
+ *  is blank/malformed, isn't a reportable root-session assistant usage entry, or falls
+ *  inside the suppressed prefix. */
+function usageEntryFromTranscriptEntry(entry: TranscriptEntry, byUuid: ReadonlyMap<string, TranscriptEntry>, includeSidechain = false): TranscriptTokenUsageEntry | undefined {
+  if (entry.type !== "assistant" || (!includeSidechain && isSidechainEntry(entry))) return undefined;
+  const usage = entry.message?.usage;
+  const occurredAt = transcriptEntryOccurredAt(entry);
+  const uuid = typeof entry.uuid === "string" ? entry.uuid : "";
+  const model = typeof entry.message?.model === "string" && entry.message.model ? entry.message.model : usage ? "unknown" : "";
+  // The spine requires both an observed createdAt and a dedupeKey: an entry the
+  // transcript hasn't stamped yet is not reportable this pass (it stays unconsumed
+  // and is picked up once Claude flushes the full entry).
+  if (!uuid || occurredAt === undefined || !model) return undefined;
+  const promptId = resolveEntryPromptId(entry, byUuid);
+  return {
+    uuid,
+    ...(promptId ? { promptId } : {}),
+    model,
+    inputTokens: usageCount(usage?.input_tokens),
+    outputTokens: usageCount(usage?.output_tokens),
+    cacheReadTokens: usageCount(usage?.cache_read_input_tokens),
+    cacheWriteTokens: usageCount(usage?.cache_creation_input_tokens),
+    occurredAt,
+    ...(usage ? {} : { usageStatus: "unknown" as const }),
+  };
+}
+
+/**
+ * Incremental #2482 extractor: feeds transcript lines one at a time so a caller can
+ * consume only newly-appended data without re-walking the file. promptId is resolved
+ * against the entries THIS instance has seen (the uuid→entry map) — feed a whole file
+ * for whole-transcript resolution, or feed only an appended tail and accept that an
+ * entry whose promptId-bearing ancestor was flushed in an earlier pass resolves without
+ * one. promptId is diagnostic metadata only; the spine record keys on the entry uuid
+ * alone. `skipFirst` suppresses the first N parseable lines (the afterEntry cursor of
+ * {@link extractTokenUsageEntries}); the capture passes none.
+ */
+export class TranscriptTokenUsageExtractor {
+  private readonly byUuid = new Map<string, TranscriptEntry>();
+  private seenCount = 0;
+
+  constructor(private readonly skipFirst = 0, private readonly includeSidechain = false) {}
+
+  appendLine(line: string): TranscriptTokenUsageEntry | undefined {
+    const trimmed = line.trim();
+    if (!trimmed) return undefined;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      return undefined;
+    }
+    this.seenCount++;
+    if (typeof entry.uuid === "string" && entry.uuid) this.byUuid.set(entry.uuid, entry);
+    if (this.seenCount <= this.skipFirst) return undefined;
+    return usageEntryFromTranscriptEntry(entry, this.byUuid, this.includeSidechain);
+  }
+}
+
+/** Claude API usage fields are non-negative integers; anything else reports as 0. */
+function usageCount(value: number | undefined): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+/** Claude names its transcript file `<sessionId>.jsonl` (#1235), so the provider's own
+ *  session uuid is recoverable from the path even when the status probe is silent. */
+export function claudeSessionIdFromTranscriptPath(transcriptPath: string): string {
+  const file = transcriptPath.split(/[\\/]/).pop() ?? "";
+  return file.replace(/\.[^.]+$/, "");
+}
+
+export function extractHookAssistantMessage(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return (content as TranscriptBlock[])
+    .filter((b) => b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text!.trim())
+    .filter(Boolean)
+    .join("\n\n");
+}