Custom subagent .claude/agents/tdd-worker.md never registers, identical siblings work fine (Agent type 'X' not found)

Resolved 💬 1 comment Opened Jul 3, 2026 by nufiko Closed Jul 7, 2026

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 via claude update
  • OS: Windows 11, PowerShell + Git Bash
  • Repo: private monorepo (minas-team-ai), .claude/agents/tdd-worker.md present 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 --follow confirms no deletion/rewrite).
  • Valid YAML frontmatter (name: tdd-worker, description, model: opus, plus two non-standard-but-tolerated fields, user_invocable and permissions.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.md both say "used by tdd-worker"), plus README.md, docs/skills.md, .claude/ARCHITECTURE.md — not an orphaned/abandoned file.
  • No same-scope duplicate name: tdd-worker anywhere: checked ~/.claude/agents/, all vouchercloud/* submodule directories, and the whole repo tree via grep -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

  1. In a repo with .claude/agents/tdd-worker.md present (frontmatter as above), call the Agent tool with subagent_type: "tdd-worker".
  2. Observe: Agent type 'tdd-worker' not found. Available agents: <25 comma-separated names, tdd-worker absent>.

What I ruled out, in order

  1. Stale session cache — reproduced in multiple fresh sessions within the same Claude Code install.
  2. Stale app-level cache — reproduced after a full Claude Code app + terminal restart.
  3. Outdated CLIclaude update confirms 2.1.199 is already latest.
  4. Fresh process / headless invocation — reproduced via an independent claude --print "..." subprocess (own system-context injection, not sharing session state).
  5. Same-scope duplicate agent name shadowing it/doctor reports no conflicts; manual filesystem search found no duplicate name: tdd-worker anywhere reachable from the working directory or ~/.claude/agents/.
  6. A third-party plugin interfering — this repo also had the context-mode MCP plugin installed, which injects a SessionStart-hook routing block into session context. Disabled it entirely (claude plugin disable context-mode, confirmed via claude 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.
  7. Frontmatter schema deviation (permissions.allow instead of the documented tools: field, plus an undocumented user_invocable field) — 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.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗