Summary

claude plugin install <name>@<marketplace> does not refresh the local marketplace clone before resolving the plugin name. When the local clone is older than the marketplace's current marketplace.json, install fails with Plugin not found in marketplace '<name>' — even though the plugin is genuinely listed in the public manifest. The error gives no recovery hint, sending users down manual-installation paths instead of the one-line fix.

Environment

• Claude Code: 2.1.123
• Platform: macOS (darwin 25.4.0)
• Marketplace type: git-source marketplace (cloned to `~/.claude/plugins/marketplaces/<name>/`)

Reproduction

1. Add a new plugin entry to a marketplace's `marketplace.json` and push to the remote.

2. On a separate machine where the marketplace was cloned before step 1:

   ```bash claude plugin install <new-plugin>@<marketplace>

   → Plugin not found in marketplace '<marketplace>'

   ```

3. Workaround:

   ```bash claude plugin marketplace update <marketplace> claude plugin install <new-plugin>@<marketplace> # succeeds ```

The same staleness issue affects `claude plugin update <name>@<marketplace>`: the target version is resolved against the local clone, so a marketplace that bumped a plugin's version after the user's last refresh effectively serves stale versions.

Two distinct bugs

Bug 1 — `install`/`update` don't refresh the clone. Neither command runs `git pull` (or otherwise re-fetches the manifest) before resolving plugin names or versions. The `autoUpdate` flag in `known_marketplaces.json` is per-marketplace and may be `false`; even when `true`, it is unclear whether it fires before resolution or only on a separate cadence.

Bug 2 — the error message is a dead end. `Plugin not found in marketplace '<name>'` is accurate from the local clone's perspective but actively misleads. Users assume the plugin doesn't exist; plugin authors receive bug reports that aren't their plugin's fault.

A recovery hint closes the loop:

``` Plugin not found in marketplace 'xiaolai'. Try: claude plugin marketplace update xiaolai (your local marketplace clone may be out of date) ```

Suggested fixes (in order of leverage)

1. Auto-refresh on resolution failure. If a plugin name doesn't resolve, attempt one `git pull` of the marketplace and retry before erroring. Cheap, robust, no flag required.
2. Honor `autoUpdate: true` before every install. Make the contract explicit: the local clone is refreshed before any install/update operation against that marketplace.
3. At minimum, add the recovery hint to the error message. Smallest change with the biggest user-experience win.

Real-world impact

A third-party user reported install failures for a plugin that had been listed in the marketplace for days. Both `plugin.json` and `marketplace.json` were correct; the local clone was simply stale. Diagnosis took significant time. The pattern affects every git-source marketplace, not a specific one.