[DOCS] Auto mode docs omit `"$defaults"` sentinel for extending built-in rules

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Configure the auto mode classifier" → "Override the block and allow rules"

Current Documentation

The docs currently say on https://code.claude.com/docs/en/permissions:

Two additional fields let you replace the classifier's built-in rule lists: autoMode.soft_deny controls what gets blocked, and autoMode.allow controls which exceptions apply. To loosen: remove rules from soft_deny when the defaults block something your pipeline already guards against with PR review, CI, or staging environments, or add to allow when the classifier repeatedly flags a routine pattern the default exceptions don't cover. To tighten: add to soft_deny for risks specific to your environment that the defaults miss, or remove from allow to hold a default exception to the block rules. In all cases, run claude auto-mode defaults to get the full default lists, then copy and edit: never start from an empty list. Setting allow or soft_deny replaces the entire default list for that section. If you set soft_deny with a single entry, every built-in block rule is discarded: force push, data exfiltration, curl | bash, production deploys, and all other default block rules become allowed.

Related pages repeat or depend on the same guidance. For example, https://code.claude.com/docs/en/permission-modes says:

Run claude auto-mode defaults to see the full rule lists. If routine actions get blocked, an administrator can add trusted repos, buckets, and services via the autoMode.environment setting.

What's Wrong or Missing?

Changelog v2.1.118 added support for including "$defaults" inside autoMode.allow, autoMode.soft_deny, and autoMode.environment so custom rules can extend the built-in lists instead of replacing them.

The current docs still describe customization as a full replacement workflow and tell users to copy the entire default lists into their settings. They do not document the new "$defaults" sentinel at all, so the documented behavior is now outdated.

This leaves two gaps:

A. The new merge mechanism is undocumented

There is no explanation that users can write entries like "$defaults" plus their own custom rules.

B. Existing guidance now implies the old behavior is the only safe option

Pages that point readers to claude auto-mode defaults and "copy the full default lists" should explain when that is still useful versus when "$defaults" is the simpler way to keep built-ins intact.

Suggested Improvement

Update the auto mode documentation to describe "$defaults" explicitly for all three arrays: autoMode.environment, autoMode.allow, and autoMode.soft_deny.

Suggested additions:

1. In https://code.claude.com/docs/en/permissions, add a short rule summary such as: "$defaults" keeps the built-in rules for that section and appends your custom entries.
2. Replace the current copy-the-entire-list-only guidance with examples that show both patterns:

{
"autoMode": {
"allow": [
"$defaults",
"Deploying to the staging namespace is allowed: staging is isolated from production and resets nightly"
],
"soft_deny": [
"$defaults",
"Never run database migrations outside the migrations CLI"
],
"environment": [
"$defaults",
"Trusted internal domains: *.corp.example.com"
]
}
}

1. Update linked summary pages (settings, permission-modes, managed-settings docs, and CLI reference) to mention that claude auto-mode defaults prints the built-ins, while "$defaults" lets users keep those built-ins without copying the whole list into settings.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/permissions | Primary auto mode classifier documentation; currently says custom allow/soft_deny lists replace defaults |
| https://code.claude.com/docs/en/permission-modes | Tells readers to inspect defaults and extend autoMode.environment, but does not mention "$defaults" |
| https://code.claude.com/docs/en/settings | autoMode config reference lists the three arrays but does not mention the sentinel behavior |
| https://code.claude.com/docs/en/server-managed-settings | Managed settings example links readers to the auto mode classifier guidance and its current warnings |
| https://code.claude.com/docs/en/cli-reference | Documents claude auto-mode defaults, which should cross-reference the new "$defaults" workflow |

Total scope: 5 pages affected

Source: Changelog v2.1.118

Exact changelog entry:

Auto mode: include "$defaults" in autoMode.allow, autoMode.soft_deny, or autoMode.environment to add custom rules alongside the built-in list instead of replacing it