[BUG] Custom .claude/agents/*.md subagent_type ignored — always falls back to built-in Explore/general-purpose

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?

Bug description

Custom subagents defined in .claude/agents/*.md with proper YAML frontmatter (name, description, model) are never dispatched via the Agent tool. Claude Code always falls back to built-in subagent types (Explore, general-purpose, Plan) regardless of CLAUDE.md instructions.

Environment

• Claude Code v2.1.73
• Model: claude-opus-4-6
• OS: Ubuntu Linux 6.17.0-14-generic
• 31 custom agents in .claude/agents/ (react-expert, drizzle-expert, schema-designer, etc.)
• All agents have valid frontmatter with name, description, model fields

```

1. Ask Claude to investigate a React component issue

1. Expected: Claude spawns Agent(subagent_type="react-expert")
2. Actual: Claude spawns Agent(subagent_type="Explore") or Agent(subagent_type="general-purpose") every time

What I tried (none worked)

1. CLAUDE.md instructions saying "NEVER use Explore, ALWAYS use project agents" — ignored
2. Inline agent catalog listing all 31 agents with subagent_type|use_when mapping — ignored
3. tools-routing.md with "FORBIDDEN" / "MANDATORY" / "CRITICAL" directives — ignored
4. Plan Mode specific rules — ignored (Plan Mode seems to override all CLAUDE.md rules)
5. Global ~/.claude/CLAUDE.md + project CLAUDE.md both reinforcing the same rules — still ignored

Additional context

This appears to be the same root cause as:

• #20931 — Custom agents not loaded as Task subagent types
• #11205 — Custom subagents not discovered (reported since v2.0.35)
• #4750 — Ambiguity in subagent behavior in Plan Mode
• #24072 — Skill tool not available in Plan Mode

The system prompt's built-in subagent type definitions take absolute precedence over any user-defined CLAUDE.md instructions, making .claude/agents/ effectively non-functional for automatic dispatch.

What Should Happen?

When .claude/agents/react-expert.md exists with valid frontmatter, Agent(subagent_type="react-expert") should work and Claude should prefer project agents over generic built-in ones, especially when CLAUDE.md explicitly instructs it to do so.

Error Messages/Logs

none

Steps to Reproduce

Reproduction steps

1. Create .claude/agents/react-expert.md with valid frontmatter:

``yaml
---
name: react-expert
description: Analyze React components, hooks, state management, and render optimization.
model: opus
---
[agent instructions]
``

1. Add instructions in CLAUDE.md:

```yaml
orchestration:
principle: Use Agent(subagent_type="react-expert") for React tasks

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

last

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

VS Code integrated terminal

Additional Information

TITLE: Custom .claude/agents/*.md subagent_type ignored — always falls back to built-in Explore/general-purpose

---

BODY:

Bug description

Custom subagents defined in .claude/agents/*.md with proper YAML frontmatter (name, description, model) are never dispatched via the Agent tool. Claude Code always falls back to built-in subagent types (Explore, general-purpose, Plan) regardless of CLAUDE.md instructions.

Environment

• Claude Code v2.1.73
• Model: claude-opus-4-6
• OS: Ubuntu Linux 6.17.0-14-generic
• 31 custom agents in .claude/agents/ (react-expert, drizzle-expert, schema-designer, etc.)
• All agents have valid frontmatter with name, description, model fields

Reproduction steps

1. Create .claude/agents/react-expert.md with valid frontmatter:

``yaml
---
name: react-expert
description: Analyze React components, hooks, state management, and render optimization.
model: opus
---
[agent instructions]
``

1. Add instructions in CLAUDE.md:

``yaml
orchestration:
principle: Use Agent(subagent_type="react-expert") for React tasks
``

1. Ask Claude to investigate a React component issue

1. Expected: Claude spawns Agent(subagent_type="react-expert")
2. Actual: Claude spawns Agent(subagent_type="Explore") or Agent(subagent_type="general-purpose") every time

What I tried (none worked)

1. CLAUDE.md instructions saying "NEVER use Explore, ALWAYS use project agents" — ignored
2. Inline agent catalog listing all 31 agents with subagent_type|use_when mapping — ignored
3. tools-routing.md with "FORBIDDEN" / "MANDATORY" / "CRITICAL" directives — ignored
4. Plan Mode specific rules — ignored (Plan Mode seems to override all CLAUDE.md rules)
5. Global ~/.claude/CLAUDE.md + project CLAUDE.md both reinforcing the same rules — still ignored

Additional context

This appears to be the same root cause as:

• #20931 — Custom agents not loaded as Task subagent types
• #11205 — Custom subagents not discovered (reported since v2.0.35)
• #4750 — Ambiguity in subagent behavior in Plan Mode
• #24072 — Skill tool not available in Plan Mode

The system prompt's built-in subagent type definitions take absolute precedence over any user-defined CLAUDE.md instructions, making .claude/agents/ effectively non-functional for automatic dispatch.

Expected behavior

When .claude/agents/react-expert.md exists with valid frontmatter, Agent(subagent_type="react-expert") should work and Claude should prefer project agents over generic built-in ones, especially when CLAUDE.md explicitly instructs it to do so.