## Bug report **Environment** - Claude Code version: 2.1.241 (also reproduced on 2.1.263 in an earlier session) - Entrypoint: claude-vscode (VSCode extension) - OS: Windows 11 Pro - Shell: Git Bash (MSYS2) ## Summary A custom subagent defined in `~/.claude/agents/ .md` is silently absent from the Agent tool's available-agents list, even though its frontmatter is structurally identical (same fields, same encoding, same line endings) to sibling agent files in the exact same directory that

Reproducing this on the native VS Code extension today (2026-09-24). - Extension: `anthropic.claude-code` v2.1.281 (darwin-arm64), latest available at time of testing - `claude --version` (separate CLI binary on the same machine): 2.1.183 - OS: macOS (Darwin 25.5.0) - Project has 6 subagents in `.claude/agents/*.md` at the git root, each with valid frontmatter (`name`, `description`, `tools`, `model: inherit`) — same shape as the working examples in the docs, confirmed with a byte-identical cop

Custom subagent silently missing from Agent tool's available list despite valid, sibling-identical frontmatter

Status Open

Reported on v2.1.241

Maintainer reply None cached

Workaround ✓ Mentioned in thread ↓

Activity 3 comments · opened Sep 9, 2026

Bug report

Environment

Claude Code version: 2.1.241 (also reproduced on 2.1.263 in an earlier session)
Entrypoint: claude-vscode (VSCode extension)
OS: Windows 11 Pro
Shell: Git Bash (MSYS2)

Summary

A custom subagent defined in ~/.claude/agents/<name>.md is silently absent from the Agent tool's available-agents list, even though its frontmatter is structurally identical (same fields, same encoding, same line endings) to sibling agent files in the exact same directory that load correctly.

Steps to reproduce

~/.claude/agents/ contains 7 custom agent definition files: auditor.md, developpeur.md, documenter.md, prompt.md, reseau.md, reviewer.md, ros-agent.md.
Calling the Agent tool with subagent_type: "developpeur" fails:

``Agent type 'developpeur' not found. Available agents: auditor, claude, claude-code-guide, documenter, Explore, general-purpose, Plan, prompt, reseau, reviewer, ros-agent, statusline-setup`Notedeveloppeur` is the only one of the 7 custom files missing from the list — the other 6 load fine.

Restarting the whole Claude Code session (closing/reopening the VSCode window, fresh conversation) does not fix it — same result.

What was ruled out (diagnostic done in-session)

Frontmatter validity: well-formed YAML, no syntax error.

``--- name: developpeur description: <normal single-line French description, ~270 chars> tools: Read, Bash, Glob, Grep, Edit, Write model: sonnet ---``

Line endings: file is uniformly CRLF (163/163 lines have \r), byte-identical in style to reviewer.md (also fully CRLF), which loads correctly.
tools: field: identical string (Read, Bash, Glob, Grep, Edit, Write) is also used verbatim by reseau.md, which loads correctly.
model: field: sonnet, same as every other agent file, all of which load correctly.
name: field: verified byte-for-byte via hexdump — pure ASCII developpeur, no BOM, no zero-width/invisible characters, no trailing whitespace beyond the line terminator.
No duplicate/conflicting name: developpeur declaration anywhere else in ~/.claude/ (only an inert backup copy under ~/.claude/backups/, not on any scan path).
No exclusion list: ~/.claude/settings.json and ~/.claude/settings.local.json contain only permission allowlists, nothing referencing agent names.

None of the above explains why this one file's agent fails to register while 6 structurally-identical siblings in the same directory succeed. A similar-looking issue (CRLF corrupting the name: value into developpeur\r) was previously diagnosed and fixed on a different machine/session for the same file — but on this machine, CRLF is present uniformly across working files too, so that fix doesn't apply here and the current failure appears to have a different root cause.

Expected behavior

developpeur should appear in the Agent tool's available-agents list, consistent with its sibling files in the same directory.

View original on GitHub ↗

3 Comments

Manu512 · 1 month ago

Update: upgraded via claude update from 2.1.241 to 2.1.266 (latest available), restarted the session fully — same result, developpeur still absent from the available-agents list while its 6 siblings in the same directory still load correctly. Not version-specific.

Manu512 · 1 month ago

Further update: deleted both ~/.claude/agents/developpeur.md and ~/.claude/commands/dev.md, then recreated them from scratch (fresh inode, LF line endings this time instead of the original CRLF) with byte-identical content otherwise. Same result — still absent from the available-agents list. This rules out file-content, encoding, and filesystem-level explanations entirely (also checked: no NTFS alternate data streams). At this point the only remaining hypothesis is something internal to Claude Code treating the literal string "developpeur" specially (a reserved/denylisted name, a hash collision, or a diacritic-normalization collision with something else, e.g. "développeur").

actiontrackerhapaglloyd-cpu · 20 days ago

Reproducing this on the native VS Code extension today (2026-09-24).

Extension: anthropic.claude-code v2.1.281 (darwin-arm64), latest available at time of testing
claude --version (separate CLI binary on the same machine): 2.1.183
OS: macOS (Darwin 25.5.0)
Project has 6 subagents in .claude/agents/*.md at the git root, each with valid frontmatter (name, description, tools, model: inherit) — same shape as the working examples in the docs, confirmed with a byte-identical copy that also fails.

Calling the Agent tool with subagent_type set to one of the project's own agent names returns, live, in the current session:

Agent type 'web-arte' not found. Available agents: claude, claude-code-guide, Explore, general-purpose, Plan, statusline-setup

Only the fixed built-in roster is ever offered — none of the .claude/agents/*.md agents appear, even after the working directory was corrected mid-session to the actual git root that contains .claude/agents/ (confirmed via git rev-parse --show-toplevel). Notably, project-level Skills in .claude/skills/ did get picked up dynamically after that same directory correction (a "New skills discovered" system notice fired), so this isn't a general "project config only loads at session start" issue — custom subagents specifically never make it into the Agent tool's registry in this host, matching #24439's report. Terminal claude in the same directory is expected to work per that issue and the docs; haven't re-tested that path directly this session.

Workaround in use meanwhile (from #24439): spawn general-purpose and have it read the subagent's .md file itself and follow it as instructions — works functionally but doesn't enforce the tools: allow-list from the frontmatter, so the simulated agent has access to everything rather than the restricted toolset the subagent was designed with.