Project custom agents (.claude/agents/) deregister after EnterWorktree and are not restored by ExitWorktree (delayed self-heal ~15 min)
Summary
Project-level custom agents (.claude/agents/*.md) are deregistered mid-session after EnterWorktree switches the session into a git worktree; ExitWorktree does not restore them immediately. The registry self-heals on a later rescan (~15 min in our observation) without a restart. During the outage, Agent(subagent_type: <custom>) errors "Agent type not found" and lists only built-in/plugin agents.
Environment
- Claude Code VSCode extension, Windows 11 (win32), PowerShell primary
- Model: claude-fable-5
- Project has 7 custom agents in
<repo>/.claude/agents/, all tracked in git (so present byte-identical in every worktree checkout)
Reproduction (as observed in a live session)
- Start a session in the main repo checkout. Custom agents spawn fine (verified: three different types spawned and one was resumed across 4 SendMessage rounds).
EnterWorktree(worktree created under.claude/worktrees/<name>; the checkout contains the same.claude/agents/*.md).- Within ~10-15 min, a system reminder announces the custom agent types "no longer available"; spawns error
Agent type '<name>' not found. Available agents: general-purpose, statusline-setup, claude, Explore, Plan, claude-code-guide, feature-dev:*. ExitWorktree(action: remove) returns the session to the original root. Custom agents STILL not spawnable (probe errored). Additionally, a Skill invoked after the exit resolved its base directory to the REMOVED worktree's path — so some cwd-dependent config cache survives the exit despite ExitWorktree's documented "clears CWD-dependent caches".- ~15 min later (a subsequent user turn), the harness announced the types available again and a probe spawn succeeded — no restart.
Expected
Per docs (code.claude.com/docs/en/sub-agents): "Project subagents are discovered by walking up from the current working directory". The worktree contains the same .claude/agents/, so the agents should stay registered across the transition — or at minimum be re-registered immediately on ExitWorktree.
Actual
All project agents drop some time after the cwd change and stay unregistered across ExitWorktree until a delayed rescan.
Impact / workaround
Any worktree-based workflow that spawns custom agents mid-worktree or right after exit breaks. Workaround we use: run agent-dependent phases before entering the worktree, and wait out the re-registration after exit.
Possibly related: #23620 (agent-team state lost on compaction) — but this reproduces without compaction; #32485 (ToolSearch never indexes custom agents) makes in-session recovery attempts futile.