[FEATURE] Generate globally-unique subagent IDs to enable reliable session analysis
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 building tools that analyze Claude Code session history (export, sync, search), subagent transcripts are identified by short hex
IDs (e.g., agent-ad58932). These IDs are not globally unique — the same ID can appear under multiple parent sessions in
~/.claude/projects/<project>/<session>/subagents/.
On a machine with ~600 sessions, I found 6 agent IDs that collide across different parent sessions:
agent-a5e94f0 → parent sessions 9df1b45f and 66ea21ef (different content: 5 vs 1 lines)
agent-ab4f231 → parent sessions 3f2c040e and c7a21ec8
agent-ad49f52 → parent sessions 9df1b45f and 66ea21ef
agent-ad58932 → parent sessions 66ea21ef and c1d866db
agent-adae482 → parent sessions 3f2c040e and c7a21ec8
agent-ae1fb95 → parent sessions 3f2c040e and c7a21ec8
This makes it impossible to reliably look up a subagent by its ID alone without knowing its parent session context. Any tool scanning
all sessions hits AmbiguousAgentSessionError and must skip those agents.
Proposed Solution
Generate longer or globally-unique agent IDs (e.g., full UUIDs like parent sessions already use) so that each subagent transcript is
unambiguously addressable by its ID alone, regardless of which parent session it belongs to.
Alternative Solutions
_No response_
Priority
Medium - Would be very helpful
Feature Category
CLI commands and flags
Use Case Example
- I use my tool to sync all Claude Code sessions to a SQLite/PostgreSQL database for analysis
- The sync enumerates all sessions and calls getAgentSession(agentId) for each subagent
- For 6 out of 601 sessions, this fails with "Agent ID is ambiguous" because the short hex ID exists under 2 different parent sessions
- With globally-unique IDs, every subagent would be addressable without ambiguity, and the sync would complete with 0 errors
Additional Context
- The collision rate is low (~1%) but grows with usage since short hex IDs have limited entropy
- Parent sessions already use full UUIDs — applying the same scheme to subagents would be consistent
- This would also benefit claude view agent-<id> within Claude Code itself
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗