Project-level custom subagent (.claude/agents/*.md) not loaded into Agent tool (desktop app v1.20186.1)

Bug report: Project-level custom subagent (.claude/agents/*.md) not loaded into Agent tool

Summary

A project defines a custom subagent via .claude/agents/code-reviewer-opus.md
with valid frontmatter (name, description, tools, model). In the
current session's Agent tool, this custom subagent does not appear in the
list of available agent types — only a fixed built-in set is offered. The
project's CLAUDE.md explicitly requires this custom subagent to be
available for a mandatory review workflow, but there is no way to load or
invoke it from within this session.

This is not limited to one install flavor: the user previously had both
the standalone @anthropic-ai/claude-code npm CLI and the Claude desktop
app installed side by side, and the custom subagent did not work in
either one. To rule out cross-contamination between the two install
methods, the user did a clean uninstall of both and reinstalled only the
Claude desktop app — the problem persists in that clean single-install
state.

Environment

• Client (current, clean-reinstall state): Claude desktop app, version

1.20186.1 (/Applications/Claude.app/Contents/Info.plist,
CFBundleShortVersionString / CFBundleVersion both 1.20186.1).

• Prior state (also affected, before cleanup): standalone

@anthropic-ai/claude-code npm CLI installed alongside the desktop app.
The custom subagent did not load in that configuration either. Both
were then fully uninstalled and only the desktop app was reinstalled,
to eliminate the possibility that two coexisting install methods were
interfering with each other — the bug still reproduces.

• Session surface inside the desktop app: appears to be a "local agent

mode" runtime — shell PATH includes
/Users/<user>/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin/<id>/<id>/bin

• In the current clean-reinstall state, no standalone claude binary is

present on PATH (which -a claude → "not found"; exit code 127 when
invoked), and no @anthropic-ai/claude-code package appears in
npm ls -g --depth=0 (only corepack, npm itself) — consistent with
the intended clean, desktop-only install.

• OS: macOS (Darwin 25.5.0), zsh shell.
• Repo: local git repository with a checked-in CLAUDE.md and

.claude/agents/code-reviewer-opus.md.

Expected behavior

Per Claude Code's documented custom subagent feature, any well-formed
Markdown file under .claude/agents/ in the project root (with valid
YAML frontmatter: name, description, tools, model) should be
discovered at session start and become invocable via the Agent tool
using its subagent_type, alongside built-in agents like Explore or
general-purpose.

Actual behavior

The Agent tool's system reminder lists only a fixed set of agent types
for this session:

- claude
- claude-code-guide
- Explore
- general-purpose
- Plan
- statusline-setup

code-reviewer-opus — despite existing on disk at
.claude/agents/code-reviewer-opus.md with correct frontmatter — is
absent from this list and cannot be invoked via
Agent({ subagent_type: "code-reviewer-opus" }).

Steps to reproduce

1. In a project, create .claude/agents/code-reviewer-opus.md with

valid frontmatter, e.g.:
``yaml
---
name: code-reviewer-opus
description: >
Use proactively immediately after a phase from plan.md has been
implemented and its tests pass. Reviews the phase's diff...
tools: Read, Grep, Glob, Bash
model: opus
---
``

1. Open the project in the Claude desktop app in a mode that surfaces

the Agent tool ("local agent mode" / FleetView-style session).

1. Ask Claude to check available agent types, or inspect the

<system-reminder> block listing agent types.

1. Observe that code-reviewer-opus is not listed, even though the

file is present and well-formed.

1. Attempt claude --agent code-reviewer-opus from a terminal as a

workaround — this also did not surface/load the custom subagent
when the standalone CLI was previously installed alongside the
desktop app.

1. Fully uninstall both the npm CLI and the desktop app, then

reinstall only the desktop app (current version 1.20186.1) to rule
out interference between the two install methods.

1. Repeat steps 2–4 in this clean, desktop-only install — the custom

subagent is still absent from the Agent tool's available types.

Impact

• Any CLAUDE.md-driven workflow that depends on a mandatory,

project-defined custom subagent (e.g. "always use a different model
to review each phase") silently cannot be honored — there is no
error, just an absent agent type, so the gap is easy to miss until
someone reads the fine print of the available-agents list.

• This was reproduced both with the CLI and desktop app coexisting and

with a clean, desktop-app-only install (v1.20186.1), so it does not
appear to be caused by conflicting install methods. No in-session or
in-app workaround was found to register or load a project-level
custom subagent manually.

Suggested fix / ask

• Investigate why project-level .claude/agents/*.md custom subagent

definitions are not being discovered/loaded into the Agent tool in
the Claude desktop app (v1.20186.1), including in a clean
single-install state with no other Claude Code install present.

• If custom subagents are intended to work in the desktop app at all,

provide a way to verify what is/isn't being picked up (e.g. a
diagnostic listing which .claude/agents/ files were parsed
successfully vs. skipped, and why).

• If custom subagents are intentionally unsupported in this client,

document that limitation clearly in-product (e.g. a note when a
.claude/agents/ directory is detected but unused) so users don't
silently lose a workflow requirement that a checked-in CLAUDE.md
assumes is available.

Additional notes

This report was drafted by Claude Code itself at the user's request,
based on direct observation within one session. It has not been
deduplicated against existing reports and has not been submitted
anywhere — the user intends to review and submit it manually.