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

Status Open
Reported on v2.1.238
Maintainer reply None cached
Activity 1 comment · opened Aug 21, 2026

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-auditor and review-md-auditor missing.
  • The two missing files have the same frontmatter shape as the five loaded ones (name, multi-line description, model: opus, tools: list, color:). Both have long single-line descriptions with backticks and parentheses — as does style-hygiene-auditor.md, which loaded.
  • Mid-session, writing a new .claude/agents/rescue-bot.md produced a system notice "New agent types are now available … rescue-bot" without any restart — create-event hot-reload works.
  • Calling Agent with the missing subagent_type would fail; the session worked around it via general-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.

View original on GitHub ↗

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