Preserve Claude route agents across plugin refresh

[lilly-luo]

Problem

Claude Code 2.1.248's interactive plugin refresh replaces its agent registry without preserving definitions supplied through --agents. Unity Gateway's routing hook then rewrites an ordinary Explore call to an agent name that Claude no longer recognizes. Built-in and plugin agents remain available.

This is reproducible with one subagent call: complete a routed call, run /reload-plugins --force, and repeat the call in the same TUI. The second call fails with Agent type 'ucode-route-glm-5-3-982d9f93' not found. Parallel spawning and nesting are unnecessary. Headless trials do not exercise the affected refresh path.

Change

Register the existing per-model route definitions in a launch-scoped plugin, pass it through --plugin-dir, and route to its qualified agent names. Claude reloads these definitions from disk during plugin refresh. Preserve caller --agents arguments. No per-route model-discovery request is added.

Generated plugins are never globally installed or passed to non-routed launches. Cleanup covers normal exit, plugin-generation failures, and process-start failures. Every Claude launch also removes abandoned plugin directories; a lease inherited by Claude prevents a concurrent non-routed launch from deleting an active session's definitions, including when the UG parent has exited. User plugins are preserved.

Existing Claude sessions need to restart after upgrading UG: hooks invoke the installed executable, and the new plugin-qualified names must match the registrations created at launch.

The diagnostic script now supports a real interactive before/reload/after experiment and checks actual tool errors, child completion notifications, and debug-log routing evidence. See scripts/repro_stale_claude_subagent.md for commands and scope.

For future affected sessions, UG_CLAUDE_DEBUG_LOG_DIR="$HOME/ug-debug" isaac enables Claude's native --debug-file capture through UG. Each launch creates a unique private log, reports its path to stderr, and retains it after exit. Explicit --debug-file wins. Capture is local only; it does not upload logs or recover earlier sessions. See the README for retrieval commands.

Validation

• Real Claude 2.1.248 TUI, CLI registration: child completed before refresh; exact missing-agent tool error afterward.
• Same TUI version, plugin registration: routed children completed before and after refresh.
• Reanalysis of saved evidence: CLI exit 1 (registry_failure), plugin exit 0 (no_failure_observed).
• 39 focused tests passed: diagnostic evidence parsing, integration contract checks, Claude launcher and subagent routing.
• After adding env-based debug capture, 236 Claude-agent and smart-routing tests passed, including log permissions, flag precedence, errors, and forwarding across launch paths.
• Cleanup validation: 678 tests passed across Claude, routing, CLI, and Codex checks; two Codex model-selection tests fail identically on the unchanged pre-cleanup revision. Cleanup tests cover both routing flags, disabled launches, startup failures, active leases, and real subprocess/PTY descriptor inheritance.
• Ruff and diff checks passed. The live gateway hook integration test was updated for qualified names but was not run in this validation.

The live diagnostic uses a small fixed routing hook and inherited child models; it validates the registration mechanism, not Isaac's launcher, smart-router decisions, or production GLM inference. The affected user's reported UG version is 0.1.0+9858a84. To attribute that specific incident to automatic plugin refresh, inspect its debug logs for Auto-refreshing plugins or refreshActivePlugins before the first missing-agent error.