Feature Request: Add subagent context to hooks API for proper tool call attribution

[arnavsharma93]

Problem

When using subagents with the Claude Agent SDK, tool calls made by subagents cannot be properly attributed to their originating subagent in observability traces. The hooks API (PreToolUse, PostToolUse, etc.) does not provide any context about which subagent (if any) is making the tool call.

Current Behavior

When a conversation uses subagents (via the Task tool):

1. Main agent spawns multiple subagents (potentially in parallel)
2. Each subagent makes tool calls
3. The PreToolUse/PostToolUse hooks receive the tool call information
4. No information is available about which subagent made the call

This makes it impossible to:

• Correctly parent tool call spans under their originating subagent in trace trees
• Distinguish between main agent tools and subagent tools
• Track which subagent is responsible for which operations

Expected Behavior

The hooks API should provide subagent context, such as:

@dataclass
class PreToolUse:
    tool_name: str
    tool_input: dict[str, Any]
    subagent_id: str | None  # NEW: ID of the subagent making this call, None if main agent
    subagent_name: str | None  # NEW: Name/description of the subagent
    # ... existing fields

Or via a separate context object:

from claude_agent_sdk import get_current_subagent

# In hook handler
def on_pre_tool_use(self, event: PreToolUse) -> None:
    subagent_ctx = get_current_subagent()
    if subagent_ctx:
        # This is a subagent tool call
        parent_span = self.subagent_spans[subagent_ctx.id]
    else:
        # This is a main agent tool call
        parent_span = self.conversation_span

Use Case

Building observability integrations (OpenTelemetry, Braintrust, etc.) that need to:

1. Create proper hierarchical trace trees: Main Agent → Subagent → Tool Calls
2. Track parallel subagent execution correctly
3. Attribute costs and tokens to the correct subagent
4. Debug which subagent made which decisions

Workaround Attempted

Tried tracking subagent context via a stack in PreToolUse/PostToolUse:

• Works for sequential subagents
• Fails for parallel subagents - no way to know which parallel subagent made which tool call

Impact

Without this feature, observability tools cannot properly represent the true execution flow of multi-agent conversations, making debugging and optimization significantly harder.

Environment

• claude-agent-sdk: v0.1.4
• Python: 3.11+
• Use case: Custom OpenTelemetry integration with Braintrust backend

---

Related: This came up while building production observability for a multi-agent VOC analysis system where parallel subagents perform independent queries and synthesis.