claude-code - 💡(How to fix) Fix Support mid-session refresh of the `.claude/agents/` registry without requiring a session restart [1 comments, 2 participants]

What I'm trying to do

Build out a multi-agent workflow where, mid-session, a new agent is installed at `.claude/agents/{name}.md` (the discipline files at `agents/{name}/` plus the invocation spec). The agent should then be dispatchable via the Task tool's `subagent_type` parameter without restarting Claude Code.

What happens

Newly installed agents are not dispatchable until the session is restarted. The agent registry is read once at session start and does not update mid-session. Dispatch attempts return: "Agent type '{name}' not found. Available agents: {list-from-start-of-session}."

What I checked

• No `/agents`, `/refresh`, or `/reload` slash command for the registry.
• No hook event (e.g., `SessionRefresh`, `ToolUseUpdate`) that triggers a registry reload.
• No config setting for dynamic agent discovery.
• The agent files land correctly on disk; Read tool sees them; commits land cleanly. The behaviour is specifically a Claude Code harness limitation.

The workaround works: install all agents in a batch within one session, restart Claude Code, the next session picks all of them up. The friction this creates compounds for users with multi-agent installation workflows.

Why this matters

I'm building a training program (Superesque Pro) where students bring multiple AI agents they've previously built (on TypingMind) over into a Claude Code-based personal Ship. A typical student might import three to five agents in their first sprint. Under the current behaviour, this is either:

• One session restart per agent install (high friction, breaks flow).
• All installs batched into one session followed by one restart (workable but constrains the skill's UX — the skill has to know to never invoke the new agent until restart, which means tests and verification on the new agent get delayed across the restart boundary).

A mid-session registry refresh would resolve this directly. The principal could install an agent, verify it, run a test dispatch, and move on — same session.

Shape of a fix

Any of:

1. A `/agents refresh` (or `/agents reload`) slash command that re-reads `.claude/agents/` and updates the registry in the current session.
2. Automatic registry-refresh-on-file-change for `.claude/agents/*.md` (filesystem watcher inside the Claude Code process).
3. Automatic registry refresh on the next message after a `.claude/agents/*.md` write (less ambitious; more robust to filesystem-watcher complexity).
4. A `SessionRefresh` hook event that triggers a registry reload.

Any of (1)–(4) would resolve the friction.

Reproduction

1. Start a Claude Code session in a project with some agents at `.claude/agents/`.
2. Create a new agent file at `.claude/agents/new-agent.md` (any valid invocation spec).
3. Attempt to dispatch: invoke the Task tool with `subagent_type: "new-agent"`.
4. Observe: "Agent type 'new-agent' not found."
5. Restart Claude Code; same dispatch succeeds.

Environment

• Claude Code in WSL on Windows; verified the behaviour is harness-level, not OS-specific (the file is correctly written to disk; no filesystem issue).
• Tested 2026-05-13.

Thanks for considering — happy to provide more context or test fixes against the workflow if useful.