[BUG] `agents` subcommand invalidates plugin cache via --plugin-dir but never reloads plugin skills/agents

Open 💬 0 comments Opened Jul 2, 2026 by zordius

Bug Description

claude ... agents (background-agent dashboard subcommand) accepts --plugin-dir (both as a top-level flag and as its own subcommand option per claude agents --help), but it never actually reloads the plugin's skills/agents into the registry — regardless of where --plugin-dir or --json are placed on the command line. A normal session (claude --plugin-dir <path> -p "...") loads the same plugin's skills correctly every time.

This looks distinct from #58624 (closed, fixed in v2.1.142 — that one was about the agents subcommand ignoring top-level flags entirely). Here the flag is recognized in some orderings (see matrix below — clearPluginCache fires), but the actual reload step ([STARTUP] Loading commands and agentsgetPluginSkillsLoaded N skills from plugin ...) never runs before the subcommand exits.

Environment

  • Version: 2.1.198 (Claude Code)
  • Platform: Linux
  • Plugin used in repro: a real, git-tracked plugin (zordius-ai, https://github.com/zordius/ai) with .claude-plugin/plugin.json + skills/ (3 skills, no agents/ dir) — also reproduced with a minimal synthetic plugin (manifest + 1 file in agents/)

Repro

Baseline — normal session loads the plugin fully:

claude --plugin-dir ~/zrepos/ai --debug-file /tmp/normal.log -p "say hi" --output-format json
grep -i skill /tmp/normal.log
Loading skills from: managed=..., user=..., project=[...]
getPluginSkills: Processing 1 enabled plugins
Checking plugin zordius-ai: skillsPath=exists
Attempting to load skills from plugin zordius-ai default skillsPath: /home/.../zrepos/ai/skills
Loaded 3 skills from plugin zordius-ai default directory
Total plugin skills loaded: 3

Under agents, in every flag ordering tried, that entire sequence is missing:

| Command | clearPluginCache fires? | Skills/agents actually reloaded? |
|---|---|---|
| claude --plugin-dir X --debug-file Y agents --json | ✅ yes | ❌ no |
| claude --plugin-dir X --debug-file Y agents (no --json, no TTY) | ✅ yes (then errors: "requires an interactive terminal") | ❌ no |
| claude --debug-file Y agents --plugin-dir X --json | ❌ no | ❌ no |
| claude --debug-file Y agents --json --plugin-dir X | ❌ no | ❌ no |

Full debug log for the first row (14 lines total, vs. 300+ for the baseline session) ends at:

[DEBUG] clearPluginCache: invalidating loadAllPlugins cache (preAction: --plugin-dir inline plugins)

— and nothing plugin/skill/agent-related follows before the process exits (either printing the --json session list, or erroring on the TTY check). --json's position relative to --plugin-dir doesn't change the outcome in either direction, so it isn't the trigger; the only variable that matters is whether --plugin-dir is given at the top level (fires the cache-invalidation preAction, but nothing after it) or as the agents subcommand's own option (doesn't even fire that).

Expected Behavior

Per claude agents --help's own description of --plugin-dir ("Load plugins from specified directory for the agent view and dispatched sessions"), the plugin's skills/agents should be loaded into the registry the same way a normal session loads them — visible in the agent view and available to sessions dispatched from it.

Actual Behavior

--plugin-dir is (sometimes) parsed enough to invalidate the plugin cache, but the subsequent load step that would repopulate it from the given directory never runs under the agents subcommand, in any flag ordering tested.

View original on GitHub ↗