[Bug] Custom project agents in .claude/agents/ not resolvable as subagents via Agent tool
Bug Description
Bug: Custom project agents in .claude/agents/ cannot be spawned as subagents via the Agent tool
Environment
- Claude Code CLI, macOS (Darwin 25.3.0), zsh
- Model: claude-sonnet-4-6
What happened
A custom agent was defined at .claude/agents/android-code-reviewer.md following the project agent
format (frontmatter with name, description, tools, model). When attempting to spawn it as a
subagent by passing subagent_type: "android-code-reviewer" to the Agent tool, the call failed
immediately with:
Agent type 'android-code-reviewer' not found. Available agents: claude, claude-code-guide,
Explore, general-purpose, Plan, statusline-setup
Expected behavior
Project-scoped agents defined in .claude/agents/ should be resolvable by their filename slug
(without .md) as a subagent_type, the same way built-in agent types are. The agent definition file
was present and valid.
Actual behavior
The Agent tool only recognizes a hardcoded set of built-in agent types. Custom project agents are
not registered in this lookup, so any attempt to spawn one returns "not found" with no further
diagnostic information.
Workaround
None available through the Agent tool. The only path is to manually embed the custom agent's
system prompt into a claude subagent call, losing the agent encapsulation entirely.
Environment Info
- Platform: darwin
- Terminal: Apple_Terminal
- Version: 2.1.143
- Feedback ID: b13fe6a7-87d8-41c2-bf8c-2ac6ff969de3
Errors
[{"error":"Error: File does not exist. Note: your current working directory is /Users/potato/Dev/Android/SneakyGame.\n at call (/$bunfs/root/src/entrypoints/cli.js:4954:11529)\n at processTicksAndRejections (native:7:39)","timestamp":"2026-05-17T01:38:03.761Z"},{"error":"Error: File does not exist. Note: your current working directory is /Users/potato/Dev/Android/SneakyGame.\n at call (/$bunfs/root/src/entrypoints/cli.js:4954:11529)\n at processTicksAndRejections (native:7:39)","timestamp":"2026-05-17T01:38:04.118Z"},{"error":"Error: Agent type 'android-code-reviewer' not found. Available agents: claude, claude-code-guide, Explore, general-purpose, Plan, statusline-setup\n at call (/$bunfs/root/src/entrypoints/cli.js:3138:51436)\n at a63 (/$bunfs/root/src/entrypoints/cli.js:4200:8363)\n at processTicksAndRejections (native:7:39)","timestamp":"2026-05-17T02:38:09.212Z"}]This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗