Agent registry is cached at session start; newly-created ~/.claude/agents files don't register until restart

Resolved 💬 2 comments Opened Jun 12, 2026 by zeyuri Closed Jun 16, 2026

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

  1. In an active session, create ~/.claude/agents/my-agent.md with valid frontmatter (name, description, model, effort).
  2. Try to use it — e.g. spawn it via the Task/Agent tool or a Workflow agent({ agentType: 'my-agent' }).
  3. It fails: Agent type 'my-agent' not found. Available agents: ... (the new agent is absent; previously-loaded ones are listed).
  4. 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.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗