Agent registry is cached at session start; newly-created ~/.claude/agents files don't register until restart
Summary
The subagent registry appears to be cached at session start. A subagent definition newly created in ~/.claude/agents/ (or a project's .claude/agents/) during a session is not available until the session is fully restarted — even though the file is on disk and valid.
Repro
- In an active session, create
~/.claude/agents/my-agent.mdwith valid frontmatter (name,description,model,effort). - Try to use it — e.g. spawn it via the Task/Agent tool or a Workflow
agent({ agentType: 'my-agent' }). - It fails:
Agent type 'my-agent' not found. Available agents: ...(the new agent is absent; previously-loaded ones are listed). - Restart the session → the same file now registers and works.
Impact
This is a real papercut when iterating on agent definitions or building a workflow that relies on custom agentType pins: you create the agent, then can't use it without a full restart, which is especially disruptive mid-task. We hit this while creating model+effort pin agents to use inside a workflow.
Proposed
Either re-scan ~/.claude/agents/ and .claude/agents/ on demand (e.g. when an unknown agentType is requested, before erroring), or provide an in-session command/flag to reload the agent registry (similar to reloading settings). Documenting the current "registers only at session start" behavior would also help in the meantime.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗