[Bug] Agent discovery inconsistently loads user and project agents

Bug Description
Bug Report for Claude Code Issue Tracker

Title: Inconsistent agent discovery - user and project agents not loaded together

Environment:

• Claude Code Version: 2.0.27
• OS: macOS 15.1.0 (Darwin Kernel 25.1.0, ARM64)
• Platform: darwin

Description:

When starting Claude Code with claude -c in a project directory that has both user-level agents (~/.claude/agents/) and
project-level agents (.claude/agents/), the agent discovery system inconsistently loads agents across different sessions.

Expected Behavior:

All agents from both locations should be visible in every session via the /agents command:

• 6 project-level agents (.claude/agents/*.md)
• 9 user-level agents (~/.claude/agents/*.md)
• Total expected: 15 agents visible in every session

Actual Behavior:

Agent visibility varies unpredictably across restarts:

1. First claude -c start: No agents visible
2. Exit and restart: Only user agents visible (9 agents)
3. Exit and restart again: Only project agents visible (6 agents)

The pattern repeats inconsistently - sometimes user agents appear, sometimes project agents appear, sometimes none appear. if they appear they are never merged and displayed together.

Reproduction Steps:

1. Create a project with project-level agents in .claude/agents/ (multiple .md files)
2. Have user-level agents in ~/.claude/agents/ (multiple .md files)
3. Run claude -c in the project directory
4. Execute /agents command - observe which agents are visible
5. Exit Claude Code
6. Repeat steps 3-5 multiple times
7. Observe that agent visibility changes between sessions

Project Structure:

Project: /Users/name/development/logAnalysis

.claude/agents/:

• db-log-analyzer.md
• firewall-enrichment.md
• ip-lookup.md
• log-analysis.md
• log-fetch.md
• sql-injection-analyzer.md

~/.claude/agents/:

• context.md
• docs.md
• documentation-creator.md
• explain-mysql.md
• git.md
• java-coder.md
• java-investigate.md
• maven.md
• search.md

Suspected Root Cause:

The agent discovery system appears to have one of these issues:

1. Race condition when scanning both directories in parallel
2. Caching mechanism that overwrites instead of merging agent lists
3. Initialization order problem where the last-loaded directory replaces the first

Impact:

• Users cannot reliably access their full set of agents
• Workflow is disrupted when expected agents are not available
• No error message indicates which agents failed to load

Workaround:

None currently - users must restart multiple times hoping to get the agents they need for their current task.

Environment Info

• Platform: darwin
• Terminal: Apple_Terminal
• Version: 2.0.27
• Feedback ID: 2a4a2479-c9b7-4088-b7eb-2ffd00400120

Errors

[{"error":"AbortError: The operation was aborted.\n    at unknown\n    at abortChildProcess (node:child_process:937:42)\n    at onAbortListener2 (node:child_process:35:24)\n    at abort (unknown)","timestamp":"2025-10-25T14:04:38.324Z"},{"error":"AbortError: The operation was aborted.\n    at unknown\n    at abortChildProcess (node:child_process:937:42)\n    at onAbortListener2 (node:child_process:35:24)\n    at abort (unknown)","timestamp":"2025-10-25T14:04:38.324Z"},{"error":"Error: Language not supported while highlighting code, falling back to markdown: \n    at Vz (/$bunfs/root/claude:1119:3158)\n    at map (native:1:11)\n    at y7 (/$bunfs/root/claude:1119:2875)\n    at JH1 (/$bunfs/root/claude:1726:6314)\n    at PD (/$bunfs/root/claude:100:19415)\n    at hi (/$bunfs/root/claude:102:42816)\n    at CG (/$bunfs/root/claude:102:38357)\n    at fg (/$bunfs/root/claude:102:38285)\n    at gD (/$bunfs/root/claude:102:38139)\n    at xw (/$bunfs/root/claude:102:35218)","timestamp":"2025-10-25T14:08:23.865Z"}]