Agent discovery: initial scan silently skips some project .claude/agents/*.md; the same files' names absent all session while a newly created agent hot-loads fine
Summary: On session start, the agent registry loaded 5 of the 7 project agent definitions in .claude/agents/ — two tracked, structurally ordinary files (tdd-auditor.md, review-md-auditor.md) were silently absent from the available-agents list. A brand-new agent file WRITTEN mid-session was announced and usable within moments, so discovery demonstrably hot-reloads on create events; the initial scan is what skipped the two files.
Environment: Claude Code 2.1.238, Windows 11 Pro 10.0.26200, main git checkout (not a worktree — distinct from the closed #25816, though possibly the same discovery path).
Observed:
.claude/agents/(all git-tracked, committed long before the session):dragon.md,flashlight.md,placement-auditor.md,review-md-auditor.md,spartan.md,style-hygiene-auditor.md,tdd-auditor.md.- Session-start agent list contained dragon, flashlight, placement-auditor, spartan, style-hygiene-auditor — plus built-ins and one user-level agent from
~/.claude/agents/.tdd-auditorandreview-md-auditormissing. - The two missing files have the same frontmatter shape as the five loaded ones (
name, multi-linedescription,model: opus,tools:list,color:). Both have long single-line descriptions with backticks and parentheses — as doesstyle-hygiene-auditor.md, which loaded. - Mid-session, writing a new
.claude/agents/rescue-bot.mdproduced a system notice "New agent types are now available … rescue-bot" without any restart — create-event hot-reload works. - Calling
Agentwith the missingsubagent_typewould fail; the session worked around it viageneral-purpose+ reading the definition file as the prompt.
Untested discriminator: whether an edit/touch of one of the skipped files triggers the same hot-reload announcement (would distinguish "initial scan raced/partial" from "these names are wedged for the session"). Can run on request; not run yet because a review agent was holding the tree.
Expected: every parseable .claude/agents/*.md present at session start appears in the initial registry, or a warning names the file and the reason it was skipped. Silent partial loading is the worst case — the orchestrator plans around agents it believes don't exist.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗