[DOCS] `forceRemoteSettingsRefresh` setting is documented only for server-managed delivery and omits the v2.1.191 fetch `Cache-Control: no-cache` behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/server-managed-settings

Section/Topic

The "Enforce fail-closed startup" section under the forceRemoteSettingsRefresh documentation, and the forceRemoteSettingsRefresh row in the settings table on https://code.claude.com/docs/en/settings.

Current Documentation

The current docs only describe forceRemoteSettingsRefresh in the context of server-managed delivery and do not mention the HTTP cache behavior of the fetch request.

The "Enforce fail-closed startup" section on https://code.claude.com/docs/en/server-managed-settings only frames the setting as a server-delivery feature:

### Enforce fail-closed startup By default, if the remote settings fetch fails at startup, the CLI continues without managed settings. For environments where this brief unenforced window is unacceptable, set forceRemoteSettingsRefresh: true in your managed settings. When this setting is active, the CLI blocks at startup until remote settings are freshly fetched. If the fetch fails, the CLI exits rather than proceeding without the policy. This setting self-perpetuates: once delivered from the server, it is also cached locally so that subsequent startups enforce the same behavior even before the first successful fetch of a new session. To enable this, add the key to your managed settings configuration: ``json theme={null} { "forceRemoteSettingsRefresh": true } ` Before enabling this setting, ensure your network policies allow connectivity to api.anthropic.com`. If that endpoint is unreachable, the CLI exits at startup and users cannot start Claude Code.

The forceRemoteSettingsRefresh row in the settings table on https://code.claude.com/docs/en/settings is tagged "Managed settings only" with no distinction between server-, MDM-, and file-delivery, and no mention of HTTP cache headers:

| forceRemoteSettingsRefresh | (Managed settings only) Block CLI startup until remote managed settings are freshly fetched from the server. If the fetch fails, the CLI exits rather than continuing with cached or no settings. When not set, startup continues without waiting for remote settings. See fail-closed enforcement | true |

Nothing in either page mentions Cache-Control: no-cache, HTTP fetch headers, or how intermediate proxies are handled for the settings request.

What's Wrong or Missing?

As of v2.1.191, the v2.1.191 release notes for this entry state: "Fixed managed settings: forceRemoteSettingsRefresh now takes effect when set via MDM or file policy, and the fetch sends Cache-Control: no-cache to prevent proxies from serving stale responses." The current documentation does not cover either half of this fix:

A. forceRemoteSettingsRefresh is now honored when delivered through MDM or file-based managed settings

The "Enforce fail-closed startup" section lives entirely on the server-managed settings page, and the settings table row is tagged "(Managed settings only)" with its link pointing only to the server-managed doc. A reader who tries to enforce fail-closed behavior from a Jamf/Iru/Intune/Group Policy profile or a managed-settings.json drop-in will not find a documented statement that the setting is honored from those sources after v2.1.191. The surrounding prose still says "once delivered from the server, it is also cached locally" — wording that implies the setting is fundamentally a server-delivery feature and offers no guidance for MDM/file-based admins.

B. The settings fetch now sends Cache-Control: no-cache

The docs never describe the HTTP fetch behavior at all (request headers, retry semantics, or how stale proxy responses are handled). After v2.1.191, the request is sent with Cache-Control: no-cache so an intermediate HTTP proxy cannot serve a stale api.anthropic.com settings response. This is the only mechanism that prevents the policy from appearing to "work" while a proxy is still serving a cached pre-change payload. There is no documentation of this behavior, no troubleshooting guidance for admins whose proxies are still serving stale settings, and no mention of what the request looks like on the wire.

Suggested Improvement

Option A: Comprehensive fix

Update the "Enforce fail-closed startup" section on https://code.claude.com/docs/en/server-managed-settings so that it is no longer framed as a server-only feature:

• Move or re-frame the section so it applies to all managed delivery mechanisms, or add a cross-reference from the MDM/file-policy sections on https://code.claude.com/docs/en/settings that says forceRemoteSettingsRefresh is honored from those sources as of v2.1.191.
• Add a short paragraph documenting that the settings fetch request now sends Cache-Control: no-cache, and explain why (so that proxies do not serve a stale api.anthropic.com settings payload after a policy change).
• Replace the example "in your managed settings" wording with explicit guidance for each delivery mechanism (Jamf/Iru configuration profile key, Intune/GPO registry value, managed-settings.json / managed-settings.d/*.json).

Update the forceRemoteSettingsRefresh row in the settings table on https://code.claude.com/docs/en/settings to:

• Clarify that the setting is honored from server-managed, MDM, and file-based managed sources.
• Note the Cache-Control: no-cache request behavior introduced in v2.1.191.
• Keep the link to the fail-closed section but expect that section to cover the multi-delivery scope.

Option B: Minimum fix

Add a short note under the "Enforce fail-closed startup" section stating: "As of v2.1.191, forceRemoteSettingsRefresh is honored when delivered via MDM configuration profiles, the HKLM\SOFTWARE\Policies\ClaudeCode registry value, or managed-settings.json (and managed-settings.d/*.json) — not only from server-managed settings. As of v2.1.191, the settings fetch request also includes Cache-Control: no-cache so HTTP proxies do not serve a stale cached settings response after a policy change." Update the forceRemoteSettingsRefresh row in the settings table to mention the multi-delivery scope and the v2.1.191 fetch behavior.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/server-managed-settings | Primary location: the "Enforce fail-closed startup" section is the only dedicated prose for forceRemoteSettingsRefresh, and currently frames the setting as server-managed-only. |
| https://code.claude.com/docs/en/settings | Settings table row at forceRemoteSettingsRefresh (around the alphabetical f block) is tagged "(Managed settings only)" with no breakdown of which delivery mechanisms honor it. |
| https://code.claude.com/docs/en/settings | The "Configuration scopes" section enumerates the three managed delivery mechanisms (server-managed, MDM/OS-level policies, file-based) but forceRemoteSettingsRefresh is not mentioned in any of them. |

Total scope: 2 pages affected (3 locations).

Version where behavior changed: Claude Code v2.1.191. The release entry for v2.1.191 reads: "Fixed managed settings: forceRemoteSettingsRefresh now takes effect when set via MDM or file policy, and the fetch sends Cache-Control: no-cache to prevent proxies from serving stale responses."

Related (not duplicate) open issues:

• An open issue about server-managed settings partial-apply behavior when a delivered payload contains an invalid entry is a different root cause (payload validation) and does not address the MDM/file-policy trigger scope or the proxy-cache fetch behavior.
• An open issue about the enforceAvailableModels managed setting being undocumented is a different missing setting and is not related to forceRemoteSettingsRefresh delivery scope.