The permissions and settings documentation is contradictory across pages in ways that cause AI assistants (and users) to give and receive conflicting advice. I spent several sessions having Claude try to fix a broken permissions config; each session read a different doc page and gave a different (wrong) answer. Here is a concrete accounting of the contradictions.

Bug 1 — Three different names for the same feature, no cross-references

None of these pages state that the other two exist or that they control the same feature.

Bug 2 — disableBypassPermissionsMode shown in Settings page example without noting it's managed-only

The Settings page shows:

{ "disableBypassPermissionsMode": "disable" }

with no caveat. The Permissions page notes this is a managed-only setting (enterprise MDM deployment). A regular user putting this in ~/.claude/settings.json gets silently ignored. The Settings page should either omit this or mark it clearly as managed-only.

Bug 3 — Contradictory docs on whether bypassPermissions is available by default

The CLI reference describes --allow-dangerously-skip-permissions as "enable permission bypassing as an option without immediately activating it" — implying bypass must be explicitly unlocked before it can be used. The Permissions page reads as if bypassPermissions is always available unless an admin disables it. These are contradictory.

Bug 4 — Bash pattern syntax only documented on the Permissions page; Settings page shows no wildcards

The Settings page shows only "Bash(npm run lint)" — no wildcards, no explanation of the matching rules. The critical space-before-asterisk distinction (Bash(ls *) matches ls -la but not lsof; Bash(ls*) matches both) and the deprecated colon syntax (Bash(ls:*)) appear only on the Permissions page. Users and AI assistants reading only the Settings page will write incorrect patterns.

Bug 5 — defaultMode values not enumerated on the Settings page

The Settings page shows only "defaultMode": "acceptEdits" as an example. The valid values (default, acceptEdits, plan, dontAsk, bypassPermissions) are only listed on the Permissions page. A user looking for bypass permissions in the Settings page reference will not find it.

Bug 6 — No documentation of precedence between "defaultMode" in settings.json and --permission-mode CLI flag

The Settings page shows a scope precedence table (managed > CLI args > local > project > user) but does not mention --permission-mode or how it relates to defaultMode. If both are set, which wins?

Suggested fix: A single "Permissions reference" page (or a clearly-linked sidebar) that consolidates: the three naming systems and their equivalence, the settings.json key with all valid values, the Bash pattern syntax with examples, the managed-only distinction, and the CLI flag. Right now the information is spread across at least 4 pages with no cross-links.

Claude Code version: 2.1.51, macOS 15.7.3 arm64