Subagent files are not hot-reloaded mid-session despite docs (v2.1.202, Windows, git-worktree session)
Docs say
https://code.claude.com/docs/en/sub-agents ("Write subagent files" Note):
Claude Code watches~/.claude/agents/and.claude/agents/. When you add or edit a subagent file on disk [...] Claude Code detects the change within a few seconds and the next delegation uses the updated definition, with no restart needed.
Actual
New agent .md files created mid-session are never picked up. The Agent tool returns
"Agent type 'X' not found" listing only the startup set. 4 attempts:
- project scope (
.claude/agents/of the session's git worktree): waits of ~15s, ~60s, ~2min - user scope (
~/.claude/agents/): wait of ~4min
Files had valid frontmatter (name/description/tools/model); plain and underscore-free names tested.
Environment
Claude Code 2.1.202, Windows 11, session running inside a git worktree
(.claude/worktrees/<name>) created via claude --worktree. CHANGELOG.md has no entry for
agent watch/hot-reload (only /reload-skills for skills in 2.1.152), so we could not date the
feature to confirm whether 2.1.202 should have it.
Expected
Either the watcher picks up new files in both documented scopes (including worktree sessions),
or the docs note the actual constraint (restart required / non-worktree only / edit-only-not-add).
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗