[BUG] Custom agents silently not loaded when exceeding ~37 agents - no error or warning

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Description

When having more than approximately 37-40 custom agents in ~/.claude/agents/, some agents are silently not loaded into the system prompt. There is no error message, warning, or indication that agents were skipped.

Environment

• Claude Code version: Latest (Jan 2026, VSCode Extension)
• OS: macOS (Darwin 25.2.0)
• Platform: VSCode Extension + Terminal

What Should Happen?

Expected Behavior

• All agents with valid frontmatter should be loaded
• OR if there's a limit, Claude Code should warn the user which agents were skipped
• OR there should be documentation about the maximum number of agents supported

Actual Behavior

• Only ~37 custom agents are loaded (+ 6 built-in = 43 total in Task tool)
• 19 agents silently ignored with no error or warning
• No way to know which agents loaded without manually comparing lists

Investigation Results

I compared the agents in my system prompt vs the files on disk:

| Metric | Count |
|--------|-------|
| Total agent files | 56 |
| Agents loaded (custom) | 37 |
| Agents loaded (built-in) | 6 |
| Agents NOT loaded | 19 |

The agents that didn't load have:

• ✅ Valid YAML frontmatter (verified with od -c)
• ✅ Valid name and description fields
• ✅ Same structure as agents that DID load
• ✅ No encoding issues (pure ASCII/UTF-8)
• ✅ Similar description lengths (~200-300 chars)
• ✅ No ~/.ripgreprc with --color=always (checked per #8256)

Hypothesis

Based on the claude-code-system-prompts repo, agent descriptions are injected via ${AGENT_TYPE_REGISTRY_STRING}.

With 56 agents × ~250 chars each = ~14,000 characters just for agent descriptions. There may be an undocumented limit on:

1. Total number of agents, OR
2. Total characters/tokens in AGENT_TYPE_REGISTRY_STRING

Impact

• High: Users unknowingly lose access to agents they created
• Confusing: No feedback about which agents loaded
• Debugging difficult: Requires manual comparison to discover the issue
• Undocumented: Official docs don't mention any limit

Suggested Fixes

1. Document the limit if it's intentional
2. Warn users when agents are skipped (e.g., "Loaded 37/56 agents. 19 skipped due to limit.")
3. Allow configuration of which agents to prioritize (e.g., .claude/agents-priority file)
4. Increase the limit or make it configurable via env var

Related Issues

• #11205 - Custom Subagents not discovered (different root cause - discovery mechanism)
• #8256 - Agents not loading due to ripgrep color config (not applicable here)
• #4728, #5185 - Similar discovery issues

Error Messages/Logs

Steps to Reproduce

1. Create 50+ custom agents in ~/.claude/agents/ with valid frontmatter:

```yaml
---
name: agent-name
description: Valid description with triggers
model: sonnet
---

1. Start a new Claude Code session
2. Ask Claude to list available agents from the Task tool
3. Compare with actual .md files in the agents directory

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.75

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_