feat(usage): split recorded cache usage by request shape

[devlikebear]

Summary

Makes the measurement #933's test plan deferred (cache_read_input_tokens growth, still unchecked) actually readable. Instrumentation only — no placement or request-building change, so existing cache behavior is untouched.

Why the numbers were unreadable

Anthropic builds one prefix-matched cache key from tools → system → messages. A request that omits tools therefore cannot hit an entry written by a tool-bearing request — not even inside the same turn. agent.Loop ends every turn with a tools-absent call (ToolChoice: none, internal/agent/loop.go:431), so each turn emits both shapes and their cache reads/writes were summed into the same rows.

That is exactly why the open question from the #933 review — does the tools-absent final call pay a 1.25x cache write for an entry nothing reads back? — could not be answered from recorded usage.

What changed

• usage.Entry records ToolCount from len(opts.Tools).
• A shape group-by keys on tool presence, so GET /v1/usage/summary?period=today&group_by=shape returns with-tools and no-tools rows. The handler already passes group_by straight through to tracker.Summary, so no API change was needed.
• docs/usage-signals.md documents how to read the rows and what a regression looks like.

How to collect the answer

curl -s 'http://127.0.0.1:43180/v1/usage/summary?period=today&group_by=shape' | jq '.summary.rows'

Run a few multi-turn sessions that exercise the tool loop first.

Row	Healthy	Regression
with-tools	cache_read_tokens grows with conversation length	reads flat at 0 → a silent invalidator upstream
no-tools	reads roughly match the previous turn's writes	writes every turn with reads at 0 → paying the write premium for nothing

If no-tools shows sustained writes with near-zero reads, the fix is to keep tools on that final call and rely on tool_choice: none — already supported by toAnthropicToolChoice (internal/llm/anthropic.go:717) but never exercised, because Tools: nil means the tool_choice key is never emitted.

Honest caveats (documented, not buried)

• tool_count only exists from this change onward. Older entries default to 0 and land in no-tools, so any comparison must start after the upgrade — otherwise the regression appears real when it is just missing data.
• Anthropic's minimum cacheable prefix is ~1024 tokens; below it nothing caches and both rows read 0 regardless of placement.
• Ephemeral entries expire after 5 minutes, so a slow turn misses for reasons unrelated to placement.

Test plan

• New test pins the shape split, including the write/no-read signature of the suspected regression
• Verified red before the change (unknown field ToolCount)
• make test — full suite green
• make vet, gofmt clean
• make lint-diff — 0 issues
• make test-cover-diff — 90.0% (9/10 changed lines), threshold 80%

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
85.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud