wrapClaudeAgentSDK should re-enter active tool spans inside local tool handlers

[AbhiPrasad]

Summary

wrapClaudeAgentSDK does not wrap local tool() handlers, so nested traces created inside a local SDK MCP tool handler are not reliably parented under the active tool span. The Python integration wraps SDK MCP tool handlers, re-enters the active tool span, creates a fallback tool span when there is no active streamed span, and disambiguates same-name concurrent tool calls by input.

What instrumentation is missing

• js/src/wrappers/claude-agent-sdk/claude-agent-sdk.ts explicitly passes tool through unchanged.
• There is no JS equivalent to Python's active-tool-span re-entry, fallback tool span creation, or same-name concurrent-call matching.
• This reduces fidelity for local tools created with the official tool() / createSdkMcpServer() surface, especially when a tool handler creates nested spans or when sibling subagents invoke the same tool name concurrently.

Why this is a concrete gap

The official TypeScript SDK supports local in-process MCP tools, and Braintrust's docs present wrapClaudeAgentSDK(...).tool(...) as an automatically traced path. Today the JS integration traces the outer tool call, but not the nested tool-handler work with the same fidelity as Python.

Braintrust docs status

unclear

Exact upstream sources

• Claude Agent SDK TypeScript reference: https://platform.claude.com/docs/en/agent-sdk/typescript
• Claude Agent SDK hooks: https://platform.claude.com/docs/en/agent-sdk/hooks

Exact Braintrust docs sources

• Claude Agent SDK integration guide: https://www.braintrust.dev/docs/integrations/agent-frameworks/claude-agent-sdk

Exact local repo files inspected

• js/src/wrappers/claude-agent-sdk/claude-agent-sdk.ts
• js/src/wrappers/claude-agent-sdk/claude-agent-sdk.test.ts
• /Users/abhijeetprasad/workspace/braintrust-sdk-python/py/src/braintrust/wrappers/claude_agent_sdk/_wrapper.py
• /Users/abhijeetprasad/workspace/braintrust-sdk-python/py/src/braintrust/wrappers/claude_agent_sdk/test_wrapper.py