[DOCS] Inconsistent precedence hierarchy for Managed Settings vs. CLI arguments

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/iam#settings-precedence - https://code.claude.com/docs/en/settings#settings-precedence

Section/Topic

The "Settings precedence" sections in both the Identity and Access Management and the Settings configuration pages.

Current Documentation

The Identity and Access Management page (https://code.claude.com/docs/en/iam#settings-precedence) lists the order as:

1. Managed settings (managed-settings.json)
2. Command line arguments
3. Local project settings...

The Settings page (https://code.claude.com/docs/en/settings#settings-precedence) states:
"Managed settings... cannot be overridden by user or project settings," but it does not explicitly clarify the relationship between Managed Settings and Command line arguments in its prioritized list.

What's Wrong or Missing?

There is a conflict in how the hierarchy is presented across different pages. Specifically, it is unclear whether CLI flags (like --allowedTools) can override a security policy defined in a system-level managed-settings.json.

If an organization-wide policy denies a specific tool, a developer might assume they can override it using a CLI flag based on the phrasing in the Settings section, whereas the IAM section suggests Managed Settings is the absolute root of truth (#1). This ambiguity creates a potential security misunderstanding for enterprise administrators.

Suggested Improvement

Standardize the precedence list in both locations to be identical and explicitly clear.

Suggested text for both sections:

1. Managed settings (managed-settings.json): Deployed by IT/DevOps to system directories. This is the absolute highest priority and cannot be overridden by CLI flags, project settings, or user settings.
2. Command line arguments: Temporary overrides for a specific session (cannot override Managed settings).
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User settings (~/.claude/settings.json)

Additionally, include a specific note: "If a tool is denied via Managed settings, using CLI flags like --allowedTools will not enable it."

Impact

High - Prevents users from using a feature

Additional Context

• Related documentation: https://code.claude.com/docs/en/iam#managed-settings
• This issue is particularly important for compliance-heavy environments where "Managed Settings" are used as a hard security boundary.