fix(telemetry): an agent row says who could be named - #770

What

agentKeyOf read agent_name === undefined as the main thread, whatever the tool:

return record.agent_name === undefined ? NO_AGENT : record.agent_name;

Only Claude Code's reader ever sets that field (isSidechain + attributionAgent, claude-code-transcript.ts). The Codex, Copilot and OpenCode readers set it nowhere. So on those three tools every record was reported as the main thread — 100% of the axis, on no evidence at all.

The contract said so out loud and called it correct:

On every tool but Claude Code the field is never set at all, so that one row carries the whole period, which is the truth for a route that names no subagents.

The same source file already states the right rule twelve lines below, for step: "its absence here yields no step at all … rather than asserting 'no skill ran'."

Change

A record with no agent name joins one of two rows, and only the tool's own declaration says which.

TelemetryRouteSupply gains agentName, declared per route beside toolStatedStep and checked against real captures by the existing honesty guard — telemetry-route-supply.unit.test.ts observes what each capture actually yields, so a route claiming an agent name its reader never sets fails there.

The declaration is read rather than the record because the record cannot carry the absence: a tool that never names an agent writes exactly what a main-thread line writes.

What this does not fix

A line marked as a subagent's that carries no agent name still reads as the main thread. Measured 2026-09-05 across 1,852 transcripts: 157 of 122,637 subagent lines name no agent, 0.07%. Closing it needs a new field on the record, which no record already stored could ever gain (storeNewCandidates freezes a record's field set at first sight, #769). Stated on CostReportAgentRow rather than captured.

Proof

Two binaries against one copy of the sink, --days 30, 30,222 requests on both. This corpus is almost entirely Claude Code, so it can barely show the fault:

That one record is the sink's only Codex request. The magnitude is not in this corpus — for a Codex-only reader the same change moves the whole axis — so the guards are the proof and the record is the demonstration the path runs end to end. All eleven breakdowns reconcile to 30,222 on both.

Guards

Reconciliation is covered by a three-row case: named + main thread + not stated must still sum to the period total.

Envelope

No bump. The agent row gains attribution and the route supply gains agent_name — fields a consumer may ignore, no existing field changing meaning, the rule at cost-report-envelope.ts. A consumer that read by_agent as "one row per agent plus one for the main thread" now sees a third row; that is the same reasoning #768 applied to by_flow and CI accepted, stated here rather than implied.

Consumers updated in the same commit: the envelope type and mapper, the route-supply envelope shape, the --axis agent table, the terminal rendering, the contract, and the cost skill's reading instructions.

Also in this commit

• accumulate's per-record parameters became a RecordContext. Nine positional arguments in a fixed order is a call nobody checks by eye, and biome's function-length rule made the point at the ninth.
• Bundle budget raised 593 → 596 KB, measured 593.8 — the same 2.2 KB headroom the by_prompt raise left, recorded in check-bundle-size.mjs beside the two raises before it.

Gates: 3449 tests / 308 files, tsc, biome ci (2 pre-existing warnings, 0 errors), knip, jscpd, bundle within budget, 369 repository script tests, 0 broken links, cli layering clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VWNxk63AGKkqE8HRqHLjGp