claude-code - 💡(How to fix) Fix [FEATURE] Expose agent instance ID in API request headers [2 comments, 2 participants]

Preflight Checklist

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

Problem Statement

When building observability/proxy tools that sit between Claude Code and the Anthropic API, there is no way to identify which agent instance a request belongs to. The only option is fragile substring matching on system prompt content, which:

• Breaks when Claude Code updates its prompts
• Cannot distinguish parallel instances of the same agent type (e.g., 3 concurrent Explore agents)
• Fails entirely for anonymized/stripped traces
• Cannot detect custom user-defined agents

Claude Code already generates per-agent instance IDs internally (createAgentId() in AgentTool.tsx, stored in AsyncLocalStorage via runWithAgentContext), but these are not included in outgoing API requests.

Proposed Solution

Add two headers to outgoing Anthropic API requests:

x-claude-code-agent-id: <unique ID per agent instance>
x-claude-code-parent-agent-id: <agent ID of the parent, absent for main>

The agentId and parent context already exist in the agent context object (agentId, parentSessionId, invokingRequestId). They just need to be forwarded to the HTTP client layer, similar to how x-claude-code-session-id is already sent.

Alternative Solutions

Currently we pattern-match against system prompt text (e.g., "file search specialist" → Explore Agent, "You are an agent for Claude Code" → General Agent). This requires maintaining a list of 13+ fragile substring patterns and still can't handle custom agents or parallel same-type instances.

We also explored hashing the parent's Agent tool_use prompt and matching against child requests' first user message, but this has race conditions, doesn't survive anonymization, and requires cross-request correlation.

Priority

Nice to have - Would improve my workflow

Feature Category

CLI commands and flags

Use Case Example

1. A team runs Claude Code through a recording proxy to track usage and costs
2. A developer asks Claude to "launch 3 Explore agents in parallel to search different parts of the codebase"
3. The proxy records 30+ interleaved Haiku requests from the 3 agents
4. With agent ID headers: each request is tagged to its specific agent instance, enabling per-agent grouping, cost attribution, and conversation reconstruction
5. Without: all 30 requests merge into one "Explore Agent" blob with no way to separate them

Additional Context

The agentId already flows through AsyncLocalStorage in runWithAgentContext() with fields including agentId, parentSessionId, agentType, subagentName, isBuiltIn, and invokingRequestId. Exposing even just agentId and parentAgentId as request headers would enable deterministic agent identification for any downstream tool.