Custom agents created during session not discoverable until restart — request hot-reload

Summary

When custom agents are created in \~/.claude/agents/<name>/agent.md\ during an active Claude Code session, they are not discovered until the session is restarted. This forces the user to interrupt their workflow, restart the CLI, and lose conversation state to use newly created agents.

Empirical reproduction (verified 2026-06-08)

1. Start Claude Code session
2. Ask Claude (in plan mode + auto mode) to create 3 custom agents at:

• \~/.claude/agents/claim-anchor-validator/agent.md\
• \~/.claude/agents/quant-math-auditor/agent.md\
• \~/.claude/agents/inference-pattern-detector/agent.md\

1. Files are created successfully on disk (verified via \ls -la ~/.claude/agents/\)
2. Try to invoke one of the new agents via Agent tool in same session
3. Result: \Agent type 'claim-anchor-validator' not found. Available agents: claude-code-guide, Explore, general-purpose, Plan, statusline-setup\

Expected behavior

Custom agents should be discoverable without restart, either:

• Automatically (filesystem watcher on \~/.claude/agents/\ and \.claude/agents/\)
• Via explicit \/agents reload\ slash command
• Via existing \/hooks\ command (currently unclear if it triggers agent reload)

Actual behavior

Discovery happens only at session startup. Per the \claude-code-guide\ agent documentation accessed in the same session: \"Claude Code discovers agents at startup only\".

This is a documented limitation but creates significant friction:

• User must \/exit\ and restart CLI
• Session conversation history is lost or requires manual resume
• For users without technical competence, the restart procedure is non-obvious
• Defeats the purpose of having Claude itself create custom agents during a workflow

Impact

High for users iterating on agent definitions. Empirical case from this session: user with no technical competence wanted to install 3 audit agents that Claude itself created. Installation succeeded on disk but agents could not be used in the same session, requiring restart explanation and manual user action.

Proposed solutions (any one)

1. Filesystem watcher on \~/.claude/agents/\ and \.claude/agents/\, auto-reload on file change
2. Explicit \/agents reload\ slash command to trigger rediscovery without full restart
3. At minimum: document clearly in CLI output / docs how to refresh agents after creation (current docs say \"startup only\" but don't explain the restart UX)

Environment

• OS: macOS Darwin 24.6.0
• Claude Code: current latest as of 2026-06-08
• Session mode at the time: plan mode -> ExitPlanMode -> auto mode
• gh CLI: 2.88.1

Additional context

Custom agents are increasingly important as users create domain-specific validators (in our case: claim-anchor-validator, quant-math-auditor, inference-pattern-detector for trading workflows). Iteration speed on agent definitions is a key productivity factor. Restart-only discovery makes the inner loop slow and error-prone for non-technical users.