[DOCS] Monitoring reference omits subagent `agent_id` and `parent_agent_id` on OTEL tool spans

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/monitoring-usage

Section/Topic

Traces (beta) → Span hierarchy and Span attributes

Current Documentation

The docs currently say:

Each user prompt starts a claude_code.interaction root span. API calls, tool calls, and hook executions are recorded as its children. Tool spans have two child spans of their own: one for the time spent waiting on a permission decision and one for the execution itself. When the Task tool spawns a subagent, the subagent's API and tool spans nest under the parent's claude_code.tool span.

claude_code.llm_request | Attribute | Description | | --- | --- | | agent_id | Identifier of the subagent or teammate that issued the request. Absent on the main session | | parent_agent_id | Identifier of the agent that spawned this one. Absent for the main session and for agents spawned directly from it |

claude_code.tool | Attribute | Description | | --- | --- | | tool_name | Tool name | | duration_ms | Wall-clock duration including permission wait and execution | | result_tokens | Approximate token size of the tool result | | subagent_type | Subagent type for the Task tool |

What's Wrong or Missing?

The page documents the subagent trace-parenting change, and it documents agent_id / parent_agent_id for claude_code.llm_request spans, but the claude_code.tool attribute table does not document those same subagent-attribution fields.

For the v2.1.145 tracing change, this leaves the tool-span schema incomplete: someone querying OpenTelemetry traces can see that subagent spans nest under the dispatching tool span, but the reference does not tell them that the dispatching/subagent tool spans also carry agent_id and parent_agent_id for correlation.

Suggested Improvement

Add agent_id and parent_agent_id rows to the claude_code.tool span attribute table, with the same scope notes used for claude_code.llm_request:

• agent_id: identifier of the subagent or teammate that issued the tool span; absent on the main session
• parent_agent_id: identifier of the agent that spawned this one; absent on the main session and for agents spawned directly from it

That would make the trace-parenting explanation and the span-attribute reference consistent for subagent tracing.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
| --- | --- | --- |
| https://code.claude.com/docs/en/monitoring-usage | 141-177, 199-209 | Span hierarchy documents nested subagent traces, but the claude_code.tool attribute table omits subagent-attribution fields |
| https://code.claude.com/docs/en/agent-sdk/observability | 145-149 | SDK observability guide repeats the nested-subagent trace model and points readers back to the monitoring reference for span details |

Total scope: 2 pages affected

Relevant changelog version: v2.1.145