burn waste: per-tool-call and per-file spend attribution

[willwashburn]

Goal

Answer the question every Claude Code user has but nobody can: which tool calls and which files actually cost me the most?

At session / workflow / repo granularity. This is the feature that distinguishes burn from every other token tracker — none of them keep tool-call content at ingest, so none of them can do this.

Approach

Two cost components per tool_use:

1. Initial cost — the turn right after the tool call. When the user turn carrying this tool's tool_result is sent back to the model, turn N+1 charges for those tokens as either fresh_input, cacheCreate_5m, or cacheCreate_1h. Allocate turn N+1's (fresh + cacheCreate) across the blocks that entered context between N and N+1, proportional to their size.

2. Persistence cost — the same tool_result stays in context for turn N+2, N+3, … until the session ends or the cache tier evicts. It shows up in those turns' cacheRead. Allocate each subsequent turn's cacheRead across the blocks still in its context by size share.

Total cost of a tool call = initial + sum(persistence). Priced per-tier using the existing @relayburn/analyze pricing loader.

Output (MVP)

burn waste [--since 7d] [--project <path>] [--session <id>] [--workflow <id>]

Three tables:

• Top files by cumulative cost — columns: path, first-read turn, initial tokens, persistence tokens, riding-along-turns, total USD, % of session.
• Top Bash commands by cost — grouped by argsHash so repeated commands aggregate.
• Top subagent calls by cost — Agent/Task tool uses with their subagent_type.

Default output: top 10 per table. --all for full. --json for programmatic consumption.

Depends on

#1 (user-turn block sizes).

Acceptance

• Synthetic session test: session containing one 8k-token Read followed by 20 turns that each touch the cache. burn waste ranks that file first and its reported total cost is within ±10% of hand-computed truth.
• Reported per-tool-call USD totals sum to the session's grand total within ±2% (some overhead — system prompt, tool definitions — won't attribute cleanly; budget for it and report an "unattributed" line).
• Handles edge cases: sidechain subagent turns (separate session context), cache tier transitions (5m → 1h), session resumption after cache eviction.

Stretch

burn waste --suggest — heuristics over the output: "file X was read twice, second read was identical; skipping would have saved $Y." "Bash command Z was run 11 times for the same args; could have been cached." Out of scope for MVP, good follow-up.

[willwashburn]

Updated plan after #33 (content sidecar).

Per-tool-call attribution gets a much cleaner implementation path:

Initial cost: for each tool_use, look up the matching tool_result in the content sidecar (~/.relayburn/content/<sessionId>.jsonl), tokenize its content directly. This is the token count that entered context between turn N and N+1. No delta math, no rolling-share estimation.

Persistence cost: unchanged — same rolling attribution over subsequent turns' cacheRead by size share. The share becomes more accurate because initial sizes are now exact.

Revised math (both paths remain in the codebase):

// Primary (content available)
initial_tokens = tokenize(contentSidecar.lookup(toolUseId).tool_result.content)

// Fallback (content.store=hash-only, or historical session)
initial_tokens = estimateFromDeltaMath(turn_N, turn_N_plus_1)  // from #2

Acceptance impact: the ±10% accuracy target becomes ±2% when content is available. The fallback path still meets the looser bound.

Dependency: sidecar (#33) + reader changes (#2). Neither strictly blocks burn waste MVP if the fallback path ships first — but the content path is what users will actually run in practice.