Subagent files are not hot-reloaded mid-session despite docs (v2.1.202, Windows, git-worktree session)

Open 💬 1 comment Opened Jul 7, 2026 by gbmrrr

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).

View original on GitHub ↗

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