claude-code - 💡(How to fix) Fix [DOCS] Managed marketplace policy docs outdated about install/update enforcement [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

blockedMarketplaces and strictKnownMarketplaces in the settings reference, plus the managed marketplace restrictions guidance

Current Documentation

The settings reference currently says:

blockedMarketplaces | (Managed settings only) Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem.

strictKnownMarketplaces | (Managed settings only) Allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only.

Later on the same page, the detailed guidance says:

strictKnownMarketplaces is a policy gate: it controls what users may add but does not register any marketplaces.

The restriction applies only to adding NEW marketplaces; previously installed marketplaces remain accessible

The marketplace guide currently says:

For organizations requiring strict control over plugin sources, administrators can restrict which plugin marketplaces users are allowed to add using the strictKnownMarketplaces setting in managed settings.

strictKnownMarketplaces restricts what users can add, but does not register marketplaces on its own.

The discover/install guide documents refresh and auto-update behavior:

Refresh plugin listings from a marketplace: /plugin marketplace update marketplace-name

Claude Code can automatically update marketplaces and their installed plugins at startup.

What's Wrong or Missing?

Changelog v2.1.117 says managed-settings blockedMarketplaces and strictKnownMarketplaces are now enforced on plugin install, update, refresh, and autoupdate.

The current docs still describe strictKnownMarketplaces as an add-time-only restriction and explicitly say previously installed marketplaces remain accessible. That is now outdated if installs, manual refreshes, updates, and startup autoupdates are also blocked by policy.

The docs also do not explain the broader enforcement surface for either setting:

A. Install/update/refresh enforcement is missing

Admins and users are not told that marketplace policy can block /plugin install, /plugin marketplace update, marketplace refreshes, and automatic marketplace/plugin updates.

B. Existing marketplace behavior is now unclear

The current statement that previously installed marketplaces remain accessible conflicts with the new changelog behavior and needs to be clarified or removed.

C. blockedMarketplaces is under-documented in user-facing marketplace docs

The settings table mentions pre-download blocking, but the marketplace guide does not explain how blockedMarketplaces affects existing configured marketplaces during refresh/update flows.

Suggested Improvement

Update the managed marketplace policy docs to describe enforcement across the full plugin lifecycle, not just marketplace addition.

Suggested changes:

1. In settings and plugin-marketplaces, add a short enforcement matrix for:

• /plugin marketplace add
• /plugin install
• /plugin marketplace update
• marketplace refresh in the /plugin UI
• startup autoupdate / automatic plugin updates

1. Replace the current “applies to marketplace additions only” / “previously installed marketplaces remain accessible” wording with behavior that matches v2.1.117.
2. Add a blockedMarketplaces subsection to the marketplace guide that explains how blocked sources behave when a marketplace was already configured before policy changed.
3. Cross-link the discover/install guide so readers managing marketplaces can see that policy may block refresh and auto-update operations too.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.117

Exact changelog entry: Managed-settings blockedMarketplaces and strictKnownMarketplaces are now enforced on plugin install, update, refresh, and autoupdate