claude-code - 💡(How to fix) Fix [DOCS] [Admin] `parentSettingsBehavior` setting missing from settings reference

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Settings reference table — admin-tier keys or managed settings merge behavior section

Current Documentation

No documentation exists for parentSettingsBehavior in the settings reference. The settings table at settings.md lists all available keys but does not include parentSettingsBehavior among the managed-settings-only keys.

The settings hierarchy documentation at server-managed-settings.md describes merge behavior:

"Within the managed tier, the first source that delivers a non-empty configuration wins. Server-managed settings are checked first, then endpoint-managed settings. Sources do not merge: if server-managed settings deliver any keys at all, endpoint-managed settings are ignored entirely."

However, there is no mention of parentSettingsBehavior as an admin-controlled option for opting SDK managedSettings (parent tier) into a policy merge.

What's Wrong or Missing?

A. Missing settings key documentation

The parentSettingsBehavior admin-tier key (added in v2.1.133) with values "first-wins" or "merge" is not listed in the settings reference table at settings.md. Administrators cannot discover this key through official documentation.

B. No documentation for SDK parent-tier merge behavior

The changelog entry describes: "Added parentSettingsBehavior admin-tier key (first-wins | merge) to let admins opt SDK managedSettings (parent tier) into the policy merge." No documentation explains what the parent tier is, when "merge" is appropriate versus "first-wins", or how SDK managedSettings relates to the managed settings hierarchy.

C. No examples for the new key

No example configuration is provided showing how to set parentSettingsBehavior in managed settings.

Suggested Improvement

Add parentSettingsBehavior to the settings reference table at settings.md with documentation:

Option A — Minimum fix: Add to the settings table under managed-settings-only keys: | parentSettingsBehavior | (Managed settings only) Controls how SDK managedSettings (parent tier) is resolved against policy settings. "first-wins" (default) uses first-source-wins semantics; "merge" opts the parent tier into the policy merge. Requires Claude Code v2.1.133 or later. | "merge" |

Option B — Full fix: Add a new subsection to the settings hierarchy documentation (or to server-managed-settings.md) explaining:

• What "parent tier" means in the SDK context
• How parentSettingsBehavior changes the merge behavior for SDK managedSettings
• When to use "first-wins" vs "merge" with concrete examples
• Version requirement (v2.1.133+)

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

Changelog reference: v2.1.133 — "Added parentSettingsBehavior admin-tier key (first-wins | merge) to let admins opt SDK managedSettings (parent tier) into the policy merge"

Total scope: 2 pages affected