Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [FEATURE] Add agent instance ID to API request headers/metadata [1 comments, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#49207•Fetched 2026-04-17 08:47:51
View on GitHub
Comments
1
Participants
1
Timeline
6
Reactions
0
Author
cquil11cquil11
Participants
cquil11cquil11
Timeline (top)
labeled ×4commented ×1cross-referenced ×1

Fix Action

Fix / Workaround

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.

Code Example

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>
RAW_BUFFERClick to expand / collapse

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 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.

extent analysis

TL;DR

Including a unique agent instance ID in outgoing API requests would allow for attribution of costs and debugging of agent behavior in complex multi-agent sessions.

Guidance

  • To address the issue, consider adding a unique identifier for each agent instance, such as a UUID, to the API requests.
  • This identifier could be included as a header, such as x-claude-code-agent-id, or in the request metadata.
  • The proposed solution also suggests including a x-claude-code-parent-agent-id field to identify the parent agent that spawned the current agent.
  • Implementing this solution would require modifications to the Claude Code API to generate and include these identifiers in outgoing requests.

Example

GET /api/endpoint HTTP/1.1
x-claude-code-agent-id: 123e4567-e89b-12d3-a456-426655440000
x-claude-code-parent-agent-id: 123e4567-e89b-12d3-a456-426655440000
x-claude-code-session-id: existing-session-id

Notes

The proposed solution builds upon the existing x-claude-code-session-id header, which already identifies sessions. The added complexity of including agent instance IDs should be weighed against the benefits of improved cost attribution and debugging capabilities.

Recommendation

Apply workaround: Including unique agent instance IDs in API requests would provide the necessary information for cost attribution and debugging, making it a worthwhile implementation.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#request timeout

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING