feat(claude-messages)!: emit invoke_agent, chat and execute_tool spans

[apucacao]

Replaces one flat span per call with the tree the TypeScript SDK emits, for claude-messages.

invoke_agent                     one per call, carries the LD identity and the run total
├── chat {model}                 one per model turn, with that turn's own tokens
└── execute_tool {name}          one per tool call, a sibling of chat

A multi-turn run with tools was previously one span with one set of token counts, so per-turn cost and latency were not recoverable from a trace, and a tool call left no trace beyond its LD metric event.

What else changed

• Span construction moved to spans.py beside the handler, so the tool loop reads as a tool loop rather than as span bookkeeping with a provider call in the middle. The five handler PRs above follow this shape.
• Cache tokens now reach the span. A turn that read 19,971 tokens from cache and wrote 3,580 more previously reported an input of 3; it now reports 23,554, and there is a test with those numbers in it.
• The handler still returns the cache fields unfolded, in Anthropic's own names, because parse_usage folds exactly once. RawRunUsage carries that shape and is named so it cannot be confused with the client's cache-inclusive RunUsage.
• Finish reasons are mapped: end_turn becomes stop, tool_use becomes tool_calls.
• A failed run reports what its completed turns cost, but only when a turn actually reported usage. All-zero attributes would assert the run cost nothing, which a run whose first call died mid-flight cannot claim.
• The streaming path gets a finally. A consumer that breaks out of the iteration skips except entirely, because GeneratorExit inherits from BaseException, so the root span was never ended and never exported: the whole run vanished from AI Config Monitoring along with the feature_flag event it carries.

The telemetry tests are rewritten rather than extended, because they pinned the old flat span. The single shared mock span is replaced with a recorder that keeps one object per span, since the old approach could not tell a parent from a child.

Not changed: the tool catalog is still unfiltered, unlike the TypeScript SDK. That difference predates this work and changes what the model is offered rather than what the span reports.

Breaking change

The span is renamed from claude.messages to invoke_agent. Queries selecting on the old name will not match. Prompt and completion content is no longer on spans unless the caller passes capture_content=True.

Where this sits

Needs the usage layer (#28) and the content layer (#29). Independent of the other five handler PRs; the stack orders them only because gh stack is linear.

Tests: 711 to 729.

---

Note

Overview
Replaces the flat claude.messages span with the TypeScript SDK's span tree for both blocking and streaming paths: an invoke_agent root, one chat {model} child per model turn, and sibling execute_tool {name} spans per tool call.

Span construction moves into a new spans.py. Cache tokens are now folded into span input totals (previously under-counted), finish reasons map to semconv (end_turn → stop, tool_use → tool_calls), and failed runs still report completed-turn spend on the root.

Breaking: prompt/completion content is off by default; pass capture_content=True to emit it. Streaming adds a finally so abandoned generators still end and export spans instead of vanishing from AI Config Monitoring.

^{Reviewed by Cursor Bugbot for commit 80c5a66. Bugbot is set up for automated code reviews on this repo. Configure here.}

[apucacao]

bugbot run

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit a4e837e. Configure here.}

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 80c5a66. Configure here.}

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 80c5a66. Configure here.}

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 80c5a66. Configure here.}