Custom subagent .claude/agents/tdd-worker.md never registers, identical siblings work fine (Agent type 'X' not found)
Summary
A valid, git-tracked custom subagent definition (.claude/agents/tdd-worker.md) is never registered as a usable subagent_type for the Agent/Task tool, while every structurally-identical sibling agent in the same directory loads correctly. Agent(subagent_type: "tdd-worker", ...) always fails with Agent type 'tdd-worker' not found, and the returned available-agents list is missing tdd-worker from exactly the alphabetical slot it should occupy — every neighboring agent (sprint-worker, statusline-setup, test-writer) is present and functional.
Environment
- Claude Code:
2.1.199(native, win32-x64), confirmed latest viaclaude update - OS: Windows 11, PowerShell + Git Bash
- Repo: private monorepo (
minas-team-ai),.claude/agents/tdd-worker.mdpresent at repo root
Evidence the file itself is not the problem
- Tracked in git since commit
483933f8(2026-06-18), byte-for-byte unchanged since (git log --followconfirms no deletion/rewrite). - Valid YAML frontmatter (
name: tdd-worker,description,model: opus, plus two non-standard-but-tolerated fields,user_invocableandpermissions.allow, that are also present — and working — on 4 sibling agents:sprint-worker.md,work-planner.md,implementation-worker.md,test-writer.md). name: tdd-worker— lowercase letters and hyphens only, compliant with the documented naming rule.- No BOM, no homoglyphs, no Zone.Identifier ADS (Windows "blocked file" marker) — checked via
Get-Item -Stream *. Same CRLF line endings as every other file in the repo. - Referenced by name in 3 other agent files' own descriptions (
implementation-worker.md,test-writer.mdboth say "used by tdd-worker"), plusREADME.md,docs/skills.md,.claude/ARCHITECTURE.md— not an orphaned/abandoned file. - No same-scope duplicate
name: tdd-workeranywhere: checked~/.claude/agents/, allvouchercloud/*submodule directories, and the whole repo tree viagrep -rl "^name: tdd-worker". Only one file declares this name. /doctor(which the docs say "reports same-scope duplicate agent names and shows which definition is active" as of v2.1.196) shows zero agent-related warnings — ruling out a shadowing conflict.
Reproduction steps
- In a repo with
.claude/agents/tdd-worker.mdpresent (frontmatter as above), call the Agent tool withsubagent_type: "tdd-worker". - Observe:
Agent type 'tdd-worker' not found. Available agents: <25 comma-separated names, tdd-worker absent>.
What I ruled out, in order
- Stale session cache — reproduced in multiple fresh sessions within the same Claude Code install.
- Stale app-level cache — reproduced after a full Claude Code app + terminal restart.
- Outdated CLI —
claude updateconfirms2.1.199is already latest. - Fresh process / headless invocation — reproduced via an independent
claude --print "..."subprocess (own system-context injection, not sharing session state). - Same-scope duplicate agent name shadowing it —
/doctorreports no conflicts; manual filesystem search found no duplicatename: tdd-workeranywhere reachable from the working directory or~/.claude/agents/. - A third-party plugin interfering — this repo also had the
context-modeMCP plugin installed, which injects a SessionStart-hook routing block into session context. Disabled it entirely (claude plugin disable context-mode, confirmed viaclaude plugin list --json→"enabled": false, then/reload-plugins, confirmed via the reload summary that context-mode's hooks/MCP server were gone) and re-ran the probe — identical failure, ruling this out as a contributing factor. - Frontmatter schema deviation (
permissions.allowinstead of the documentedtools:field, plus an undocumenteduser_invocablefield) — present on 4 other agents that all load correctly, so not the differentiator.
Expected behavior
tdd-worker should appear in the available-agents list and be dispatchable, identical to its siblings.
Actual behavior
Consistently absent from registration, with no diagnostic signal from /doctor or any other tool pointing at why.
Happy to share the full file contents or transcript excerpts if useful for reproduction.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗