Docs: `permissions.defaultMode` is missing from the settings reference table

Status Open
Reported on v2.1.220
Maintainer reply None cached
Activity 0 comments · opened Jul 27, 2026

What's wrong

permissions.defaultMode is documented on /docs/en/permission-modes but does not appear in the
settings reference table on /docs/en/settings.

Where it is documented

/docs/en/permission-modes, CLI tab:

As a default: set defaultMode in a settings file such as ~/.claude/settings.json: ``json { "permissions": { "defaultMode": "acceptEdits" } } ``

and, with a constraint that is easy to miss and easy to get wrong (VS Code tab):

To start in auto mode by default, set defaultMode in your user settings instead. Claude Code ignores defaultMode: "auto" in project and local settings.

Why it matters

Someone checking the settings reference for a default-permission-mode key finds nothing and reasonably
concludes none exists. That happened to us: we searched the settings table, concluded the key didn't
exist, and were close to filing a feature request for a mechanism that already ships. The
user-settings-only constraint on auto is also the kind of rule that produces a silent no-op when
someone puts it in project settings.

Suggested fix

Add a permissions.defaultMode row to the /docs/en/settings table with its accepted values,
cross-linked to the permission-modes page, and note the user-settings-only constraint for auto.

Secondary, same area

/docs/en/mobile states flatly:

you can't select Auto for a Remote Control session

On 27 Jul 2026 the iOS mode dropdown displayed Auto for a Remote Control session on its own, with
no user selection, once the session had taken a turn — and the same account was able to select Auto on
a Remote Control session the previous day. This line appears to lag the client. (Client build not
recorded; host was Claude Code 2.1.220.)

View original on GitHub ↗