Subagent definitions added mid-session are not spawnable for minutes (docs say "within a few seconds")

Summary

A subagent definition added to ~/.claude/agents/ during a session is not spawnable for several minutes. The Agent tool returns Agent type '<name>' not found, and the "Available agents" list shows only the definitions that existed at session start. A fresh process loads the same files straight away, so the files are valid.

The sub-agents docs say:

Claude Code watches ~/.claude/agents/ and .claude/agents/. When you add or edit a subagent file on disk, or ask Claude to write one for you, Claude Code detects the change within a few seconds and the next delegation uses the updated definition, with no restart needed.

The docs' one exception (no agents directory at session start) does not apply here: ~/.claude/agents/ already existed and held nine definitions that spawned normally.

Environment

• Claude Code 2.1.285 (also seen on 2.1.280), CLI, interactive session in tmux
• macOS (Darwin 25.6)
• Auto mode

Reproduction

1. Start an interactive session with an existing, populated ~/.claude/agents/.
2. Mid-session, write two new files, e.g. ~/.claude/agents/zz-probe-a.md:

``markdown
---
name: zz-probe-a
description: Temporary probe. Delete after use.
model: haiku
tools: Read
---
You are a probe. Answer the prompt in one short line.
``

1. Ask Claude to spawn it: Agent(subagent_type: "zz-probe-a", prompt: "reply ONE").
2. Retry after 1 minute, then after 3–4 minutes.

Expected: found within a few seconds, per the docs.

Actual: Agent type 'zz-probe-a' not found. Available agents: … on the first attempt and on a retry about 3 minutes later. The list contains only the pre-existing definitions. In the same minute, claude -p started in another directory spawned both new agents successfully.

Pattern across sightings

There were four earlier sightings on 2.1.280, in three sessions:

• One definition was still "not found" about 8 minutes after it was written, all within a single assistant turn. touching the file did not help. It was available at the start of the next turn.
• Another stayed unspawnable through a background-task notification wake, and appeared only after the user's next message.
• A third set became available on a background-task wake alone.

So the reload seems to be tied to some turn boundaries rather than to the file watcher's few seconds. This isn't certain: one wake did pick the files up and another didn't.

Impact

Orchestration that writes a definition and then delegates to it in the same turn fails. The docs promise that this works, so the failure is unexpected. The workaround is to ship every definition before the session starts.

Related

• #22050 and #29202: the original hot-reload requests, closed as duplicates.
• #88023: custom agents disappearing after /compact, a different trigger.