[Bug] Custom project agents in .claude/agents/ not resolvable as subagents via Agent tool

Resolved 💬 3 comments Opened May 17, 2026 by NicePotatoSalad Closed Jun 18, 2026

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"}]

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗