[FEATURE] Add agent instance ID to API request headers/metadata

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When analyzing Claude Code API usage (costs, token consumption, session traces), there is no way to determine which agent instance a given API request belongs to. If Claude Code spawns multiple parallel subagents, their requests are interleaved and indistinguishable — they share the same session ID and have no agent-level identifier.

This makes it difficult to:

• Attribute costs to specific agent invocations
• Understand which subagent produced which output
• Debug agent behavior in complex multi-agent sessions

Proposed Solution

Include a unique agent instance ID (e.g., a UUID generated when a subagent is spawned) in outgoing API requests, either as a header or in the request metadata. Ideally two fields:

x-claude-code-agent-id: <unique ID for this agent instance>
x-claude-code-parent-agent-id: <ID of the agent that spawned this one, absent for main>

This would be analogous to how x-claude-code-session-id already identifies sessions — just one level deeper.

Alternative Solutions

The only current workaround is pattern-matching against system prompt content to guess the agent type. This is fragile, breaks on prompt changes, can't distinguish parallel instances of the same type, and doesn't work for custom user-defined agents.

Priority

Nice to have - Would improve my workflow

Feature Category

CLI commands and flags

Use Case Example

1. A developer asks Claude Code to "launch 3 Explore agents in parallel"
2. Claude Code spawns 3 agent instances, each making multiple API calls
3. All requests share the same x-claude-code-session-id with no way to tell which belongs to which agent
4. With per-agent IDs: straightforward cost attribution, conversation reconstruction, and debugging per agent instance

Additional Context

The x-claude-code-session-id header already solves this problem at the session level. This request is for the same concept applied one level deeper — per-agent-invocation identity.