[BUG] plugin.json dependencies never resolve for --plugin-dir plugins, silently disabling the whole plugin

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

If a plugin loaded via --plugin-dir declares dependencies in its plugin.json (e.g. [{"name": "plugin-dev", "marketplace": "claude-plugins-official"}]), the dependency never resolves and Claude Code disables the entire plugin: 0 skills, 0 agents, 0 commands. There is no user-visible error. The failure only shows up with --debug --debug-to-stderr.

The dependency fails to resolve no matter how the dependency plugin is present. I tested all of these, and each fails identically with dependency-unsatisfied:

• dependency installed and enabled in ~/.claude/settings.json
• dependency recorded in ~/.claude/plugins/installed_plugins.json
• dependency itself passed as another --plugin-dir in the same invocation

This hits the desktop app hard. The macOS desktop app spawns its bundled CLI (~/Library/Application Support/Claude/claude-code/2.1.197/claude.app/Contents/MacOS/claude) and passes every enabled plugin as an explicit --plugin-dir <path> flag. Plugins loaded this way register as <name>@inline (Plugin "pstack" from --plugin-dir overrides installed version). So any plugin that declares dependencies is silently dead in the desktop app, while the identical install works in the terminal CLI and the VS Code extension, which resolve plugins natively from settings and marketplaces.

One more piece: optional: true on a dependency entry passes claude plugin validate but the loader ignores it and still treats the dependency as hard.

What Should Happen?

The plugin should load. When a dependency genuinely can't resolve, I'd expect a visible warning naming the plugin and the missing dependency, not a silent no-op. And optional: true should either make the dependency non-blocking or fail validation. Validating it and then ignoring it is the worst of both.

Suggested fixes, any subset helps:

• resolve dependencies against installed_plugins.json, or match by plugin name among the session's inline plugins, when running in --plugin-dir mode
• show plugin load failures as a user-visible warning instead of a debug-only line
• honor optional in the loader, or reject it in the schema

Error Messages/Logs

Plugin "pstack" from --plugin-dir overrides installed version
Plugin not available for MCP: pstack@inline - error type: dependency-unsatisfied
Dependency "plugin-dev@claude-plugins-official" is not installed

Steps to Reproduce

No marketplace or settings needed:

1. git clone https://github.com/michael-denyer/pstack-claude && cd pstack-claude && git checkout 54d6617 (v0.9.2, the last commit that still has the dependencies field)
2. Run:

``sh
claude --debug --debug-to-stderr --setting-sources "" --settings '{}' \
--plugin-dir "$PWD/plugins/pstack" -p 'ok' 2>&1 | grep -i dependenc
``

1. stderr shows dependency-unsatisfied and Dependency "plugin-dev@claude-plugins-official" is not installed. The plugin contributes nothing to the session.
2. Delete the dependencies key from plugins/pstack/.claude-plugin/plugin.json and rerun step 2. The same invocation now loads 44 skills and 1 agent.

The --setting-sources "" --settings '{}' isolation just makes the repro deterministic. The same failure happens with real settings where plugin-dev@claude-plugins-official is installed, enabled, and recorded in installed_plugins.json, and even when the dependency is passed as a second --plugin-dir.

Is this a regression?

I don't know

Claude Code Version

2.1.197 (also the version bundled with the current macOS desktop app)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

zsh (the repro is headless -p; the same failure occurs inside the desktop app, which is where the impact is)

Additional Information

Reproduced 2026-07-01 on Claude Code 2.1.197, macOS 15.x (Darwin 25.5.0).

Related issues, neither of which covers this loader behavior: #49308 asks for docs on plugin_errors in the headless init event; #51775 (closed) asked for docs on the dependencies field itself.

Repro repo: https://github.com/michael-denyer/pstack-claude at commit 54d6617.