[DOCS] Project-scoped plugins loading from git worktrees is fixed in v2.1.200 but never documented in the plugin reference or discover-plugins guide

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugins-reference

Section/Topic

The "Project scope" section of plugins-reference.md (around the trust-gate explanation and the @skills-dir warning) and the "Install to project scope" guidance in discover-plugins.md.

Current Documentation

plugins-reference.md:380-391 describes project-scope plugins and a worktree-related warning, but the warning is only about subdirectory launch:

A project-scope plugin is checked into the repository and reaches every collaborator who clones it. Because that content comes from you rather than from your repository, it loads only after the same trust gate that governs .claude/settings.json, and components that run code are restricted further: MCP servers it declares go through the same per-server approval as a project .mcp.json LSP servers start only after you trust the workspace * Background monitors do not load Project-scope @skills-dir plugins load only from the .claude/skills/ of the directory where you start Claude Code. They do not walk up to the repository root the way plain skills and commands do, so launching from a subdirectory misses a plugin that lives at the repo root. Launch from the repository root, or run /reload-plugins after changing directories.

plugin-marketplaces.md:592 mentions marketplaces and worktrees but in the context of marketplace location, not plugin loading:

If you use a local directory or file source with a relative path, the path resolves against your repository's main checkout. When you run Claude Code from a git worktree, the path still points at the main checkout, so all worktrees share the same marketplace location. Marketplace state is stored once per user in ~/.claude/plugins/known_marketplaces.json, not per project.

discover-plugins.md documents the three installation scopes but does not address worktrees at all.

What's Wrong or Missing?

A. Project-scoped plugins not loading from a worktree is the exact bug v2.1.200 fixed

The v2.1.200 changelog says:

Fixed project-scoped plugins not loading correctly from git worktrees of the same repository

Before v2.1.200, opening Claude Code in a git worktree of a repository that had project-scoped plugins enabled in .claude/settings.json would not load those plugins, even though the same plugins loaded correctly in the main checkout. Neither plugins-reference.md nor discover-plugins.md mentioned this case, so users hitting it had no doc hint that the bug was specific to worktrees.

B. The worktree scope is the dominant multi-checkout pattern

The current prose only addresses "launching from a subdirectory". Git worktrees are a different situation: a worktree is a separate working copy of the same repository, sharing .git and the same .claude/settings.json on disk, but with its own checked-out files. The plugin loader had to special-case this; the docs currently do not call out that worktree-specific behavior.

C. There is no doc hint about what the v2.1.200 fix changed

The plugins-reference.md page has no min-version note for project-scope plugin loading and no mention that the worktree-loading behavior changed. A reader cannot tell that anything worktree-related was recently fixed or how it interacts with the existing "launch from the repository root" guidance.

Suggested Improvement

Add a new paragraph under the "Project scope" heading in plugins-reference.md, after the existing @skills-dir warning, for example:

{/ min-version: 2.1.200 /}Project-scope plugins also load when you open Claude Code from a git worktree of the same repository. Before v2.1.200, launching from a worktree would not load the plugins enabled in .claude/settings.json, even though the same plugins loaded in the main checkout; that bug is fixed. If a plugin still does not appear in a worktree, run /reload-plugins after cd-ing into the worktree.

Cross-link from discover-plugins.md's "Project scope" bullet to the new paragraph so users installing for the team see the worktree caveat.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/plugins-reference | 380-391 | "Project scope" section |
| https://code.claude.com/docs/en/discover-plugins | 280 | "Project scope" bullet |
| https://code.claude.com/docs/en/plugin-marketplaces | 592 | Worktree paragraph (different scope: marketplace location, not plugin loading) |

Total scope: 3 pages; only the plugins-reference page needs the new prose, the other two should cross-link.

The release note for this fix appears in v2.1.200 (July 3, 2026).