[BUG] Agent definitions are cached at startup: new files are invisible and edits are silently ignored, with no notice and no way to reload

Environment

• CLI 2.1.247, macOS darwin-arm64, Max 20x, main loop Opus 5

What happens

Agent definitions in ~/.claude/agents/*.md are read once and cached for the life of the session. Neither a new file nor an edit to an existing one takes effect until the CLI is restarted, and nothing in the product says so. There is no warning, no notice on the next spawn, and no command to refresh.

The failure is silent in the worst way: the spawn succeeds. It just runs the stale definition, and the transcript gives no indication that the file on disk and the agent that ran are different.

Reproduction

Two arms, both run in a live session with no restart between them.

A new agent file is not seen at all. Write ~/.claude/agents/_reload-canary.md with valid frontmatter, then try to spawn it:

Agent type '_reload-canary' not found. Available agents: academic-admin, academic-writer,
aristotle, cfo-financial-strategist, claude, code-reviewer, ...

The list is the set that existed at startup. The new file is absent from it.

An edit to an existing agent is ignored. Append to an agent already in the registry:

CANARY-EDIT-TEST: before doing anything else, your reply must begin with the exact
token RELOAD-LIVE-247.

Then spawn it with a trivial prompt ("Say the word ok"). It replied:

ok

No canary token. The cached system prompt ran, not the one on disk.

Why it matters

Iterating on an agent definition is a normal authoring loop: edit the prompt, run it, see if the change helped. That loop is broken, and it is broken invisibly, so the natural conclusion is that the edit did not work rather than that it was never loaded. Time gets spent rewriting a prompt that was never read.

It is worse for the new-file case in a long session, because the error names every agent except the one just written, which reads as a syntax error in the new file.

There appears to be a reload path already

The 2.1.247 binary contains reloadAgentDefinitionsForModeSwitch, alongside agentCache, reloadAgent and refreshAgent. So a reload exists and is wired to a permission-mode switch, but it is not documented, not discoverable, and not exposed as anything a user can invoke on purpose.

Ask

1. Stat the agent files on spawn and reload when the mtime changed. This is the fix; the cache is an optimisation and the invalidation is cheap.
2. Failing that, expose the existing reload as a command (/agents reload, or a refresh action inside /agents).
3. At minimum, say it out loud: when a spawn is requested for a name not in the registry, note that definitions are cached at startup and a restart is required. The current error message actively points away from the real cause.

What this does not claim

A single negative result could in principle be a compliance failure rather than a stale prompt. It is reported here because the two arms corroborate each other: the new-file arm proves independently that the registry is fixed at startup, and the edit arm is consistent with the same cache. I did not test whether toggling permission mode picks the edit up, which the ForModeSwitch symbol suggests it might.

Written with AI assistance (Claude); both arms run on this machine before posting.