Python: fix(claude): propagate usage details and finish_reason from ResultMessage

[droideronline]

Closes #6929

Summary

The Claude Agent SDK's ResultMessage carries token usage statistics (input_tokens, output_tokens, cache tokens) and a stop_reason that were previously discarded by the agent framework. As a result, AgentResponse.usage_details was always None and AgentResponse.finish_reason was always None when using the Claude agent.

Problem

When calling agent.run() with the Claude agent, AgentResponse.usage_details and AgentResponse.finish_reason are always None, even though the underlying Claude Agent SDK's ResultMessage contains this information.

Direct SDK call returns:

ResultMessage(
    session_id="...",
    stop_reason="end_turn",
    usage={"input_tokens": 42, "output_tokens": 18, "cache_read_input_tokens": 5},
)

Agent Framework before this fix:

response.usage_details  # None ❌
response.finish_reason  # None ❌

Agent Framework after this fix:

response.usage_details  # {"input_token_count": 42, "output_token_count": 18, "total_token_count": 60, "cache_read_input_token_count": 5} ✅
response.finish_reason  # "end_turn" ✅

Changes

python/packages/claude/agent_framework_claude/_agent.py

1. Adds UsageDetails to imports from agent_framework.
2. Adds _parse_claude_usage_details() — converts the Claude API usage dict to the framework's UsageDetails TypedDict.
3. Emits usage metadata from ResultMessage — in _get_stream(), when ResultMessage arrives the handler now:
   • Converts message.usage → UsageDetails and yields an AgentResponseUpdate with Content.from_usage() so the standard _process_update() path populates AgentResponse.usage_details
   • Maps message.stop_reason → finish_reason on the update so AgentResponse.finish_reason is set
   • No extra update is emitted when ResultMessage has no usage or stop_reason (backward-compatible no-op)

python/packages/claude/tests/test_claude_agent.py

Adds 4 tests:

• test_run_propagates_usage_details_from_result_message
• test_run_propagates_finish_reason_from_result_message
• test_run_stream_propagates_usage_details
• test_run_no_usage_no_stop_reason_no_extra_update

Testing

All 65 existing tests pass. 4 new tests added (69 total).

[Copilot]

Pull request overview

This PR updates the Python Claude agent integration to propagate token usage statistics and the model stop reason from the Claude Agent SDK’s ResultMessage into the Agent Framework’s AgentResponse, so callers can access usage_details and finish_reason when using Claude.

Changes:

• Added _parse_claude_usage_details() to map Claude usage dict keys into the framework’s UsageDetails.
• Emitted an AgentResponseUpdate at ResultMessage time to flow usage (via Content.from_usage) and finish_reason through the standard update processing path.
• Added test coverage to validate usage_details and finish_reason propagation for both non-streaming and streaming runs, plus a no-op scenario.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
python/packages/claude/agent_framework_claude/_agent.py	Parses Claude usage into UsageDetails and emits a final update containing usage/finish metadata from ResultMessage.
python/packages/claude/tests/test_claude_agent.py	Adds tests ensuring usage_details and finish_reason propagate (and no extra update is emitted when absent).

[droideronline]

@moonbox3 @eavanvalkenburg - kindly take a look when you get a chance. Thanks!