Review Summary

Review started. Now recording findings.## Review Summary — PR #87: 5-way token breakdown + context-window utilization

Overall: Solid implementation. The buildContextWindow helper is clean, its null/zero handling matches the documented null sentinel contract, the example payload in EVENTS.md is internally consistent (used = 1024 + 8800 + 1024 = 10848, ratio = 0.05424), the non-overlapping bucket definition and context.used = input + cache.read + cache.write are correct, and the ModelNotFoundError-only catch correctly rethrows other errors. No blockers.

Findings (2, both MINOR):

1. Source-text substring tests give false confidence (usage-token-breakdown.test.ts:149) — The message_complete emit block shape describe block reads run.ts as a raw string and asserts substring presence inside arbitrary byte windows. These don't exercise the emit path: they pass if the keywords appear only in comments, break on harmless refactors, and the contextUsed includes cache.write test never actually validates the arithmetic. Prefer a behavioral test (stub Provider.getModel, capture the emit payload) or drop them in favor of the strong buildContextWindow unit tests.

2. reasoning may emit undefined (silently dropped) (run.ts:497) — JSON.stringify omits undefined, so if StepFinishPart leaves reasoning unset for non-thinking models the field is absent rather than 0, breaking the EVENTS.md contract. Verify the info.tokens shape; a defensive ?? 0 on each field guarantees the documented schema.

Both findings recorded via MCP. Review complete.