[DOCS] Server-managed settings docs omit `forceRemoteSettingsRefresh` fail-closed startup behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Available settings for managed/server-managed settings, plus the Fetch and caching behavior section on the server-managed settings page

Current Documentation

No documentation currently exists for forceRemoteSettingsRefresh on either the settings reference page or the server-managed settings page.

The related server-managed settings page currently says:

Claude Code fetches settings from Anthropic's servers at startup and polls for updates hourly during active sessions. First launch without cached settings: Claude Code fetches settings asynchronously If the fetch fails, Claude Code continues without managed settings There is a brief window before settings load where restrictions are not yet enforced Subsequent launches with cached settings: Cached settings apply immediately at startup Claude Code fetches fresh settings in the background Cached settings persist through network failures

What's Wrong or Missing?

A. The new policy setting is undocumented

Changelog v2.1.92 added forceRemoteSettingsRefresh, but the docs do not explain:

• where administrators configure it
• which settings scopes support it
• what value it accepts
• whether it applies only to remote/server-managed settings

B. The fetch/caching docs do not explain the fail-closed override

The existing Fetch and caching behavior section only describes async fetch plus cached/no-settings fallback behavior. It does not explain that when forceRemoteSettingsRefresh is enabled, the CLI blocks startup until remote managed settings are freshly fetched and exits if the fetch fails.

Without that documentation, administrators cannot tell that Claude Code now supports a stricter fail-closed startup mode instead of only the currently documented permissive startup behavior.

Suggested Improvement

Add a forceRemoteSettingsRefresh row to the settings reference that documents:

• scope and availability (for example, whether it is managed-only or specific to server-managed settings)
• accepted value(s)
• exact startup behavior: the CLI waits for a fresh remote/server-managed settings fetch before starting
• failure behavior: startup exits if the fetch fails instead of proceeding with stale or absent remote settings
• cache interaction: whether cached settings are ignored or insufficient when this setting is enabled

Then update the server-managed settings page so Fetch and caching behavior clearly distinguishes:

• the default async/cached behavior
• the behavior when forceRemoteSettingsRefresh is enabled

An example note would help here, such as:

With forceRemoteSettingsRefresh enabled: Claude Code blocks startup until remote managed settings are freshly fetched. If the fetch fails, startup exits instead of continuing with cached or missing remote settings.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/settings | Canonical settings reference where managed and policy keys are documented |
| https://code.claude.com/docs/en/server-managed-settings | Fetch and caching behavior currently documents only async/background refresh and cached fallback |

Total scope: 2 pages affected

Source: Changelog v2.1.92

Exact changelog entry:

Added forceRemoteSettingsRefresh policy setting: when set, the CLI blocks startup until remote managed settings are freshly fetched, and exits if the fetch fails (fail-closed)