tracebox 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor LG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# tracebox
+
+**See what your coding agent actually did.** tracebox records every Claude Code
+session — tools called, files touched, commands run, tokens spent — into an
+auditable timeline, and flags where the agent *claimed* an edit that never
+landed.
+
+[![npm](https://img.shields.io/npm/v/tracebox.svg)](https://www.npmjs.com/package/tracebox)
+[![license](https://img.shields.io/npm/l/tracebox.svg)](./LICENSE)
+![node](https://img.shields.io/node/v/tracebox.svg)
+
+100% local. Zero telemetry. Your session data never leaves your machine.
+
+![tracebox session view — instrument summary, timeline, and claims-vs-reality panel](https://raw.githubusercontent.com/VictorLG98/tracebox/main/docs/screenshot.png)
+
+## Install
+
+Requires Node.js ≥ 20.
+
+```bash
+npm install -g tracebox
+
+tracebox install   # registers hooks in ~/.claude/settings.json
+tracebox list      # your past sessions are already there
+tracebox ui        # open the web UI
+```
+
+Or run without installing:
+
+```bash
+npx tracebox list
+```
+
+### From source
+
+```bash
+git clone https://github.com/VictorLG98/tracebox.git && cd tracebox
+npm install && npm run build && npm link
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `tracebox install` | Register collection hooks (Claude Code) |
+| `tracebox list` | Recent sessions: project, started, events, tokens |
+| `tracebox show <id>` | Timeline of one session |
+| `tracebox stats` | Token usage by day and by project |
+| `tracebox ui` | Open the local web UI (Ctrl-C to stop) |
+
+## Web UI
+
+`tracebox ui` ingests the latest data, starts a local server on `127.0.0.1`
+(no auth, no network — it binds loopback only), and opens your browser. It
+serves a small single-page app with two views:
+
+- **Session list** — project, date, duration, tokens, files touched, and a
+  badge on sessions with a claims-vs-reality discrepancy.
+- **Session view** — three zones: a summary header, a filterable/searchable
+  timeline (subagent events nested), and a **claims-vs-reality** panel.
+
+### Claims vs. reality
+
+For each file the agent tried to edit, the panel shows whether the edit
+**succeeded** (✓), **failed** (✗), or was **attempted** with no recorded
+outcome (⚠). This is a structural, deterministic comparison — attempts come
+from the agent's `Edit`/`Write` calls, outcomes come from the hook results.
+No text analysis, no guessing.
+
+The "reality" signal requires hooks (`tracebox install`). Sessions recorded
+before hooks were installed still show attempted edits, marked ⚠ with a
+"hooks not installed" note — never a blank screen.
+
+## How it works
+
+Claude Code hooks append raw events to `~/.tracebox/raw/` (the collector
+never fails and never slows your session). Transcripts under
+`~/.claude/projects/` are parsed on demand for token usage — which is why
+sessions from before you installed tracebox show up too. Everything is
+normalized into SQLite at `~/.tracebox/db.sqlite`.
+
+## Status
+
+MVP: Claude Code only. The ingestion layer is adapter-based — other agents
+are on the roadmap.

package/dist/atf.js

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+export function makeUniqKey(...parts) {
+    return createHash('sha1').update(parts.join('|')).digest('hex');
+}
+export function classifyTool(toolName, input) {
+    const inp = (input ?? {});
+    switch (toolName) {
+        case 'Bash':
+            return { type: 'command', detail: String(inp.command ?? '') };
+        case 'Read':
+            return { type: 'file_touch', detail: String(inp.file_path ?? ''), touch: { path: String(inp.file_path ?? ''), action: 'read' } };
+        case 'Edit':
+        case 'NotebookEdit':
+            return { type: 'file_touch', detail: String(inp.file_path ?? inp.notebook_path ?? ''), touch: { path: String(inp.file_path ?? inp.notebook_path ?? ''), action: 'edit' } };
+        case 'Write':
+            return { type: 'file_touch', detail: String(inp.file_path ?? ''), touch: { path: String(inp.file_path ?? ''), action: 'write' } };
+        case 'Task':
+        case 'Agent':
+            return { type: 'subagent_spawn', detail: String(inp.description ?? String(inp.prompt ?? '').slice(0, 80)) };
+        default:
+            return { type: 'tool_call', detail: JSON.stringify(inp).slice(0, 120) };
+    }
+}

package/dist/browser.js

@@ -0,0 +1,21 @@
+import { spawn } from 'node:child_process';
+export function browserOpenCommand(platform, url) {
+    if (platform === 'darwin')
+        return { cmd: 'open', args: [url] };
+    if (platform === 'win32')
+        return { cmd: 'cmd', args: ['/c', 'start', '', url] };
+    return { cmd: 'xdg-open', args: [url] };
+}
+/** Best-effort browser open. Never throws — a failed spawn is swallowed so the
+ *  command still prints the URL and stays up. */
+export function openBrowser(url) {
+    try {
+        const { cmd, args } = browserOpenCommand(process.platform, url);
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        /* ignore */
+    }
+}

package/dist/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { collect } from './collector.js';
+import { cmdList } from './commands/list.js';
+import { cmdShow } from './commands/show.js';
+import { cmdStats } from './commands/stats.js';
+import { cmdInstall } from './commands/install.js';
+import { cmdUi } from './commands/ui.js';
+import { dbPath, traceboxHome } from './paths.js';
+import { VERSION } from './version.js';
+import fs from 'node:fs';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const HELP = `tracebox ${VERSION} — local trace recorder for coding agent sessions
+
+Usage:
+  tracebox install     register hooks in ~/.claude/settings.json
+  tracebox list        recent sessions
+  tracebox show <id>   session timeline
+  tracebox stats       token usage aggregates
+  tracebox ui          open the local web UI (Ctrl-C to stop)
+  tracebox collect     (internal) hook entry point, reads stdin
+`;
+async function withStore(fn) {
+    const [{ openStore }, { runIngest }] = await Promise.all([
+        import('./store.js'),
+        import('./ingest/ingest.js'),
+    ]);
+    fs.mkdirSync(traceboxHome(), { recursive: true });
+    const store = openStore(dbPath());
+    try {
+        runIngest(store);
+        return fn(store);
+    }
+    finally {
+        store.close();
+    }
+}
+export async function main(argv) {
+    const [cmd] = argv;
+    switch (cmd) {
+        case 'collect':
+            await collect(process.stdin);
+            return 0; // contract: never non-zero
+        case 'install':
+            return cmdInstall();
+        case 'list':
+            await withStore((s) => cmdList(s));
+            return 0;
+        case 'show': {
+            const idPrefix = argv[1];
+            if (!idPrefix) {
+                console.error('Usage: tracebox show <session-id-prefix>');
+                return 1;
+            }
+            return await withStore((s) => cmdShow(s, idPrefix));
+        }
+        case 'stats':
+            await withStore((s) => cmdStats(s));
+            return 0;
+        case 'ui':
+            return await cmdUi();
+        case '--version':
+        case '-v':
+            console.log(VERSION);
+            return 0;
+        case 'help':
+        case '--help':
+        case undefined:
+            console.log(HELP);
+            return 0;
+        default:
+            console.error(`Unknown command: ${cmd}\n\n${HELP}`);
+            return 1;
+    }
+}
+// Detect direct execution robustly, including when invoked via a symlinked bin
+// (npm install / npm link put a symlink on PATH, so argv[1] is the link path
+// while import.meta.url is the resolved real path — a bare string compare fails).
+const isDirectRun = (() => {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    const self = fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(entry) === self;
+    }
+    catch {
+        return entry === self;
+    }
+})();
+if (isDirectRun) {
+    main(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((err) => {
+        const isCollect = process.argv[2] === 'collect';
+        if (!isCollect)
+            console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = isCollect ? 0 : 1;
+    });
+}

package/dist/collector.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { rawLogDir } from './paths.js';
+const MAX_RAW_BYTES = 1_000_000;
+export async function collect(stdin) {
+    try {
+        const chunks = [];
+        for await (const c of stdin)
+            chunks.push(Buffer.from(c));
+        const text = Buffer.concat(chunks).toString('utf8').trim();
+        if (!text)
+            return;
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            payload = { unparsed: text.slice(0, MAX_RAW_BYTES) };
+        }
+        const isoNow = new Date().toISOString();
+        const line = JSON.stringify({ received_at: isoNow, payload }) + '\n';
+        const dir = rawLogDir();
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, `hooks-${isoNow.slice(0, 10)}.jsonl`);
+        fs.appendFileSync(file, line);
+    }
+    catch {
+        // Contract: the collector runs inside the user's agent session.
+        // It must never throw, never block, never break the session.
+    }
+}

package/dist/commands/install.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { claudeSettingsPath, traceboxHome } from '../paths.js';
+const HOOK_EVENTS = ['SessionStart', 'PreToolUse', 'PostToolUse', 'Stop'];
+const COLLECT_ENTRY = { hooks: [{ type: 'command', command: 'tracebox collect' }] };
+export function buildHookConfig(settings) {
+    const out = structuredClone(settings);
+    const hooks = out.hooks ?? {};
+    out.hooks = hooks;
+    for (const ev of HOOK_EVENTS) {
+        const entries = Array.isArray(hooks[ev]) ? hooks[ev] : [];
+        hooks[ev] = entries;
+        if (!JSON.stringify(entries).includes('tracebox collect')) {
+            entries.push(structuredClone(COLLECT_ENTRY));
+        }
+    }
+    return out;
+}
+export function cmdInstall() {
+    try {
+        fs.mkdirSync(traceboxHome(), { recursive: true });
+        const file = claudeSettingsPath();
+        let settings = {};
+        try {
+            const raw = fs.readFileSync(file, 'utf8');
+            try {
+                settings = JSON.parse(raw);
+            }
+            catch {
+                console.error(`install aborted: ${file} exists but is not valid JSON — fix or remove it first`);
+                return 1;
+            }
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+            // file missing: proceed with empty settings
+        }
+        const updated = buildHookConfig(settings);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(updated, null, 2) + '\n');
+        console.log(`tracebox hooks registered in ${file}`);
+        console.log('Past sessions are already visible: try `tracebox list`');
+        return 0;
+    }
+    catch (err) {
+        console.error(`install failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}

package/dist/commands/list.js

@@ -0,0 +1,14 @@
+import path from 'node:path';
+import { formatTokens, pad } from '../format.js';
+export function cmdList(store) {
+    const rows = store.listSessions();
+    console.log(`${pad('SESSION', 10)}${pad('PROJECT', 22)}${pad('STARTED', 18)}${pad('EVENTS', 8)}TOKENS`);
+    for (const r of rows) {
+        const started = (r.started_at ?? '').slice(0, 16).replace('T', ' ');
+        const project = r.project_dir ? path.basename(r.project_dir) : '(unknown)';
+        console.log(`${pad(r.id.slice(0, 8), 10)}${pad(project, 22)}${pad(started, 18)}${pad(String(r.event_count), 8)}${formatTokens(r.total_tokens)}`);
+    }
+    if (rows.length === 0) {
+        console.log('(no sessions yet — run some agent sessions or check ~/.claude/projects)');
+    }
+}

package/dist/commands/show.js

@@ -0,0 +1,32 @@
+import { formatTokens, pad } from '../format.js';
+function duration(start, end) {
+    if (!start || !end)
+        return '?';
+    const ms = new Date(end).getTime() - new Date(start).getTime();
+    if (Number.isNaN(ms) || ms < 0)
+        return '?';
+    const mins = Math.round(ms / 60_000);
+    return mins >= 60 ? `${Math.floor(mins / 60)}h${mins % 60}m` : `${mins}m`;
+}
+export function cmdShow(store, idPrefix) {
+    const s = store.findSession(idPrefix);
+    if (!s) {
+        console.error(`No session matching '${idPrefix}'. Try: tracebox list`);
+        return 1;
+    }
+    const tokens = store.sessionTokens(s.id);
+    console.log(`session   ${s.id}`);
+    console.log(`project   ${s.project_dir ?? '(unknown)'}`);
+    console.log(`model     ${s.model ?? '(unknown)'}`);
+    console.log(`duration  ${duration(s.started_at, s.ended_at)}`);
+    console.log(`tokens    ${formatTokens(tokens.input + tokens.output)} (in ${formatTokens(tokens.input)} / out ${formatTokens(tokens.output)} / cache-read ${formatTokens(tokens.cacheRead)})`);
+    console.log(`files     ${store.fileTouchCount(s.id)} touched`);
+    console.log('');
+    for (const e of store.eventsForSession(s.id)) {
+        const time = e.ts.slice(11, 19);
+        const prefix = e.sidechain ? '  ↳ ' : '';
+        const tool = e.toolName ? `${e.toolName}  ` : '';
+        console.log(`${time}  ${prefix}${pad(e.type, 15)}${tool}${e.detail}`);
+    }
+    return 0;
+}

package/dist/commands/stats.js

@@ -0,0 +1,12 @@
+import { formatTokens, pad } from '../format.js';
+export function cmdStats(store) {
+    console.log('TOKENS BY DAY (last 14)');
+    for (const r of store.statsByDay()) {
+        console.log(`  ${pad(r.day, 12)}${formatTokens(r.tokens)}`);
+    }
+    console.log('');
+    console.log('TOKENS BY PROJECT');
+    for (const r of store.statsByProject()) {
+        console.log(`  ${pad(r.project, 40)}${formatTokens(r.tokens)}`);
+    }
+}

package/dist/commands/ui.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import { dbPath, traceboxHome } from '../paths.js';
+export function runUi(deps) {
+    return new Promise((resolve) => {
+        deps.ingest();
+        deps.start().then(({ url, close }) => {
+            deps.log(`tracebox UI running at ${url} — press Ctrl-C to stop`);
+            deps.open(url);
+            deps.onStop(() => {
+                close();
+                resolve(0);
+            });
+        });
+    });
+}
+export async function cmdUi() {
+    const [{ openStore }, { runIngest }, { startServer }, { openBrowser }] = await Promise.all([
+        import('../store.js'),
+        import('../ingest/ingest.js'),
+        import('../server/server.js'),
+        import('../browser.js'),
+    ]);
+    fs.mkdirSync(traceboxHome(), { recursive: true });
+    const store = openStore(dbPath());
+    return runUi({
+        ingest: () => runIngest(store),
+        start: async () => {
+            const { server, url } = await startServer(store);
+            return { url, close: () => { server.close(); store.close(); } };
+        },
+        open: (url) => openBrowser(url),
+        onStop: (fn) => process.once('SIGINT', fn),
+        log: (msg) => console.log(msg),
+    });
+}

package/dist/format.js

@@ -0,0 +1,10 @@
+export function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return String(n);
+}
+export function pad(s, w) {
+    return s.length >= w ? s.slice(0, w) : s.padEnd(w);
+}

package/dist/ingest/hooks.js

@@ -0,0 +1,80 @@
+import { classifyTool, makeUniqKey } from '../atf.js';
+export function classifyOutcomeSuccess(toolResponse) {
+    if (toolResponse == null)
+        return null;
+    if (typeof toolResponse === 'string') {
+        if (toolResponse.trim() === '')
+            return null;
+        return /^\s*error/i.test(toolResponse) ? false : true;
+    }
+    if (typeof toolResponse === 'object') {
+        const obj = toolResponse;
+        if ('error' in obj && obj.error)
+            return false;
+        return Object.keys(obj).length === 0 ? null : true;
+    }
+    return null;
+}
+export function normalizeHookLine(line) {
+    let rec;
+    try {
+        rec = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    const p = rec?.payload;
+    const sessionId = p?.session_id;
+    const ts = rec?.received_at;
+    if (typeof sessionId !== 'string' || typeof ts !== 'string')
+        return null;
+    const base = { sessionId, ts, source: 'hook', sidechain: false };
+    const key = (...extra) => makeUniqKey(ts, sessionId, ...extra);
+    switch (p.hook_event_name) {
+        case 'SessionStart':
+            return {
+                events: [{ ...base, type: 'session_start', toolName: null, detail: String(p.cwd ?? ''), uniqKey: key('session_start') }],
+                touches: [],
+                session: { id: sessionId, ...(p.cwd ? { projectDir: String(p.cwd) } : {}), startedAt: ts },
+            };
+        case 'Stop':
+            return {
+                events: [{ ...base, type: 'session_end', toolName: null, detail: '', uniqKey: key('session_end') }],
+                touches: [],
+                session: { id: sessionId, endedAt: ts },
+            };
+        case 'PreToolUse': {
+            const toolName = String(p.tool_name ?? 'unknown');
+            const c = classifyTool(toolName, p.tool_input);
+            const uniqKey = key('pre', toolName, JSON.stringify(p.tool_input ?? null));
+            const events = [{ ...base, type: c.type, toolName, detail: c.detail, uniqKey }];
+            const touches = c.touch
+                ? [{ sessionId, path: c.touch.path, action: c.touch.action, ts, uniqKey: makeUniqKey(uniqKey, 'touch') }]
+                : [];
+            return { events, touches, session: { id: sessionId } };
+        }
+        case 'PostToolUse': {
+            const toolName = String(p.tool_name ?? 'unknown');
+            const c = classifyTool(toolName, p.tool_input);
+            // Only file-mutating tools carry a claims-relevant outcome.
+            const isFileMutation = c.touch && (c.touch.action === 'edit' || c.touch.action === 'write');
+            if (!isFileMutation) {
+                return { events: [], touches: [], session: { id: sessionId } };
+            }
+            const rawResponse = JSON.stringify(p.tool_response ?? null).slice(0, 2000);
+            const uniqKey = makeUniqKey(ts, sessionId, 'post', toolName, c.touch.path);
+            const outcome = {
+                sessionId,
+                path: c.touch.path,
+                toolName,
+                success: classifyOutcomeSuccess(p.tool_response),
+                rawResponse,
+                ts,
+                uniqKey,
+            };
+            return { events: [], touches: [], session: { id: sessionId }, outcome };
+        }
+        default:
+            return { events: [], touches: [], session: { id: sessionId } };
+    }
+}

package/dist/ingest/ingest.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { rawLogDir, claudeProjectsDir } from '../paths.js';
+import { normalizeHookLine } from './hooks.js';
+import { normalizeTranscriptLine } from './transcripts.js';
+function readLines(file) {
+    try {
+        return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+function listFiles(dir, ext) {
+    try {
+        return fs.readdirSync(dir).filter((f) => f.endsWith(ext)).map((f) => path.join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+function ingestHooks(store) {
+    for (const file of listFiles(rawLogDir(), '.jsonl')) {
+        for (const line of readLines(file)) {
+            const norm = normalizeHookLine(line);
+            if (!norm)
+                continue;
+            if (norm.session)
+                store.upsertSession(norm.session);
+            for (const e of norm.events)
+                store.insertEvent(e);
+            for (const t of norm.touches)
+                store.insertFileTouch(t);
+            if (norm.outcome)
+                store.insertToolOutcome(norm.outcome);
+        }
+    }
+}
+function ingestTranscripts(store) {
+    const projectDirs = (() => {
+        try {
+            const root = claudeProjectsDir();
+            return fs
+                .readdirSync(root, { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .map((d) => path.join(root, d.name));
+        }
+        catch {
+            return [];
+        }
+    })();
+    for (const dir of projectDirs) {
+        for (const file of listFiles(dir, '.jsonl')) {
+            const norms = readLines(file)
+                .map(normalizeTranscriptLine)
+                .filter((n) => n !== null);
+            if (norms.length === 0)
+                continue;
+            for (const n of norms) {
+                if (n.session)
+                    store.upsertSession(n.session);
+                if (n.usage)
+                    store.insertTokenUsage(n.usage);
+            }
+            // Hook events are the primary source; transcripts only backfill sessions
+            // recorded before tracebox was installed. Claude Code writes one session
+            // per transcript file, so gating on the first found is safe. Events without
+            // a session are dropped (unattributable without a session).
+            const sessionId = norms.find((n) => n.session)?.session?.id;
+            if (sessionId && store.hookEventCount(sessionId) === 0) {
+                for (const n of norms) {
+                    for (const e of n.events)
+                        store.insertEvent(e);
+                    for (const t of n.touches)
+                        store.insertFileTouch(t);
+                }
+            }
+        }
+    }
+}
+export function runIngest(store) {
+    ingestHooks(store);
+    ingestTranscripts(store);
+}

package/dist/ingest/transcripts.js

@@ -0,0 +1,58 @@
+import { classifyTool, makeUniqKey } from '../atf.js';
+export function normalizeTranscriptLine(line) {
+    let obj;
+    try {
+        obj = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    const sessionId = obj?.sessionId;
+    const ts = obj?.timestamp;
+    if (typeof sessionId !== 'string' || typeof ts !== 'string')
+        return null;
+    const session = { id: sessionId, startedAt: ts, endedAt: ts };
+    if (typeof obj.cwd === 'string')
+        session.projectDir = obj.cwd;
+    const out = { events: [], touches: [], session };
+    if (obj.type !== 'assistant' || !obj.message)
+        return out;
+    const msg = obj.message;
+    if (typeof msg.model === 'string')
+        session.model = msg.model;
+    if (msg.usage && typeof obj.uuid === 'string') {
+        out.usage = {
+            sessionId,
+            messageUuid: obj.uuid,
+            model: typeof msg.model === 'string' ? msg.model : null,
+            ts,
+            inputTokens: msg.usage.input_tokens ?? 0,
+            outputTokens: msg.usage.output_tokens ?? 0,
+            cacheReadTokens: msg.usage.cache_read_input_tokens ?? 0,
+            cacheCreationTokens: msg.usage.cache_creation_input_tokens ?? 0,
+        };
+    }
+    const content = Array.isArray(msg.content) ? msg.content : [];
+    content.forEach((block, i) => {
+        if (block?.type !== 'tool_use' || typeof block.name !== 'string')
+            return;
+        const c = classifyTool(block.name, block.input);
+        out.events.push({
+            sessionId,
+            ts,
+            type: c.type,
+            toolName: block.name,
+            detail: c.detail,
+            source: 'transcript',
+            sidechain: !!obj.isSidechain,
+            uniqKey: makeUniqKey('transcript', String(obj.uuid ?? ts), String(i), block.name),
+        });
+        if (c.touch) {
+            out.touches.push({
+                sessionId, path: c.touch.path, action: c.touch.action, ts,
+                uniqKey: makeUniqKey('transcript-touch', String(obj.uuid ?? ts), String(i), block.name),
+            });
+        }
+    });
+    return out;
+}