claude-code - 💡(How to fix) Fix [DOCS] `plugin update` docs do not specify whether existing dependencies of a meta-plugin are re-resolved

Documentation Type

Missing documentation (feature not documented)

Documentation Location

claude plugin update <plugin> behavior when the target plugin declares a dependencies array — i.e. is itself a meta-plugin / bundle.

Section/Topic

https://code.claude.com/docs/en/plugins-reference (plugin update command reference) https://code.claude.com/docs/en/plugin-dependencies

Current Documentation

The plugin update command reference says:

plugin update

Update a plugin to the latest version.

claude plugin update <plugin> [options]

The plugin-dependencies docs document dependency resolution at install time:

When you install a plugin that declares dependencies, Claude Code resolves and installs them automatically and lists which dependencies were added at the end of the install output.

And describe a recovery path tied to install / /reload-plugins:

If a dependency later goes missing, /reload-plugins and the background plugin auto-update reinstall it … Re-running claude plugin install on the dependent plugin … also resolves any outstanding missing dependencies.

The plugin-dependencies version-constraint docs cover the auto-update path:

Auto-update fetches a constrained dependency at the highest git tag that satisfies every installed plugin's range.

What's Wrong or Missing?

Neither the plugin update command reference nor the plugin-dependencies docs specify what claude plugin update <meta> does to the meta-plugin's existing declared dependencies. Four scenarios that come up when authoring a bundle plugin are not covered:

1. Existing dep already at the marketplace's latest version. Meta v1.0.0 declares ["dep-a"]; both are installed; dep-a is at the latest tag. User runs claude plugin update <meta>. Is dep-a re-fetched? Re-resolved against constraint? Left untouched? No-op?

2. Existing dep at an older version than the marketplace. Same setup, but dep-a on the laptop is at 1.0.0 and the marketplace now has 1.1.0. The meta still declares the bare string "dep-a" (no version constraint change). Does the dep get upgraded to 1.1.0 as a side-effect of updating the meta, or stay at 1.0.0?

3. Newly-added dep. Meta bumps from v1.0.0 (dependencies: ["a","b"]) to v1.1.0 (dependencies: ["a","b","c"]). After claude plugin update <meta>, does c get installed? At the latest tag, or is there a constraint resolution pass?

4. Removed dep. Meta bumps from v1.0.0 (["a","b","c"]) to v1.2.0 (["a","b"]). After claude plugin update <meta>, what happens to c? Auto-removed? Disabled? Left as an orphan that claude plugin prune handles? The plugin-dependencies docs describe the prune semantics for uninstall, but not for "removed from a meta's dependency array via update."

In short: dependency install-time resolution is documented; update-time resolution is not. This is the gap that lets a user verify their understanding of install from the docs but not of update — and "what happens when I bump a meta-plugin" is a routine question for anyone authoring a bundle.

I'm shipping a meta-plugin (a baseline bundle that cascade-installs three policy-enforcement plugins via dependencies) and wanted to use a SessionStart hook to keep laptops current with the bundle. The intuitive design was:

claude plugin marketplace update <my-marketplace>      # refresh catalog
claude plugin update <my-meta-plugin>@<my-marketplace> # upgrade meta + cascade

The first command is documented as catalog-only. The second is where the docs go quiet — and the cascade behavior is exactly the property the design relies on.

I ended up shipping a defensive workaround: read the dependencies array from my own plugin's plugin.json at runtime in the hook, and explicitly run claude plugin update <dep>@<marketplace> for each one. That works, but it's only necessary because the documented contract for plugin update cascade is silent.

Suggested Improvement

Add a short "Behavior on update" subsection to either the plugin update command reference or the plugin-dependencies page that specifies the answer to all four scenarios above. A 4-row table covering existing-current / existing-stale / newly-added / removed would be enough.

Specifically, please clarify:

1. Whether plugin update <meta> re-evaluates the meta-plugin's dependencies array against installed deps at all, or only on install / /reload-plugins / per-marketplace background auto-update.
2. If yes, whether constraint re-resolution applies to (a) deps with a version constraint, (b) bare-string deps, or (c) both.
3. The treatment of newly-added deps in the new meta version — install at latest tag, or any other resolution rule.
4. The treatment of removed deps — auto-prune, disable, leave-as-orphan-for-prune.

Even a one-line "plugin update <meta> does not currently re-resolve dependencies; use /reload-plugins or rerun claude plugin install <meta> to repair" would close the gap, if that turns out to be the actual behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages: