›_ Claude Code Issues
Claude Code Issues / #52194

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

Status Fixed / completed
Maintainer reply None cached
Activity 4 comments · opened Apr 23, 2026 · closed Jun 27, 2026

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

View original on GitHub ↗

4 Comments

coygeek · 5 months ago

Still relevant as of 2026-05-18. This documentation gap has not been addressed in the docs yet.

coygeek · 4 months ago

Verified against the latest docs; this still appears unresolved.

coygeek · 3 months ago

Issue #52194 Verification

Title: [DOCS] Auto mode docs omit "$defaults" sentinel for extending built-in rules
Issue Date: 2026-04-23
Verification Date: 2026-06-27
Status: RESOLVED

---

Issue Summary

Issue #52194 reports that, as of 2026-04-23, the auto mode classifier documentation described autoMode.soft_deny, autoMode.allow, and autoMode.environment as fully replacing the built-in rule lists, and only suggested claude auto-mode defaults + "copy the full default lists" as the customization workflow. The issue notes that changelog v2.1.118 (2026-04-23) added a "$defaults" sentinel that lets custom rules extend the built-in list rather than replace it, and asks for that sentinel to be documented across permissions, permission-modes, settings, server-managed-settings, and cli-reference.

---

Verification Results

Claim 1: The docs at https://code.claude.com/docs/en/permissions describe customization as a full-replacement workflow

Status: RESOLVED

The auto mode classifier configuration has been split out of the general permissions page into a dedicated reference at https://code.claude.com/docs/en/auto-mode-config. The current permissions page no longer carries the customization guidance the issue quoted; it only references auto mode in passing and links out to the dedicated page. At https://code.claude.com/docs/en/permissions, line 449 now reads:

Configure auto mode: tell the auto mode classifier which infrastructure your organization trusts

The dedicated auto mode page, at https://code.claude.com/docs/en/auto-mode-config, line 52, opens the environment section with:

The default environment list trusts the working repo and its configured remotes. To add your own entries alongside that default, include the literal string "$defaults" in the array. The default entries are spliced in at that position, so your custom entries can go before or after them.

And at line 121, the override-the-defaults section now reads:

To keep the built-in rules while adding your own, include the literal string "$defaults" in the array. The default rules are spliced in at that position, so your custom rules can go before or after them, and you continue to inherit updates as the built-in list changes across releases.

Verdict: The custom-rule guidance now defaults to the extension workflow the issue asked for. The "Setting allow or soft_deny replaces the entire default list" warning the issue quoted is still present (now line 151 of auto-mode-config) but is correctly framed as the consequence of omitting "$defaults" and is paired with the extension pattern.

Claim 2: The docs do not mention "$defaults" anywhere

Status: RESOLVED

The sentinel is documented in multiple places:

  • https://code.claude.com/docs/en/auto-mode-config — lines 52, 58, 83, 121, 129, 133, 138, 143, 151, 156, 180, 182 (with examples in lines 54-66, 79-94, and 125-148).
  • https://code.claude.com/docs/en/settings — line 218 explicitly states: Include the literal string "$defaults" in an array to inherit the built-in rules at that position.
  • https://code.claude.com/docs/en/whats-new/2026-w17 — line 106 announces the feature.
  • https://code.claude.com/docs/en/changelog — line 1399 carries the original v2.1.118 release note.

Verdict: The "$defaults" sentinel is now documented in both the dedicated reference and the settings key reference.

Claim 3: https://code.claude.com/docs/en/permission-modes only points at claude auto-mode defaults without mentioning "$defaults"

Status: RESOLVED

At https://code.claude.com/docs/en/permission-modes, line 234 reads:

Sandbox network access requests are routed through the classifier rather than allowed by default. 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: see Configure auto mode.

The sentence still describes claude auto-mode defaults as the inspection command and autoMode.environment as the customization lever, but it now links directly into the auto-mode-config page that documents "$defaults". The auto-mode-config page itself, at lines 156 and 182, explains when claude auto-mode defaults is still useful (taking full ownership by omitting "$defaults"):

Only omit "$defaults" when you intend to take full ownership of the list. To do that safely, run claude auto-mode defaults to print the built-in rules, copy them into your settings file, then review each rule against your own pipeline and risk tolerance.
If you need to remove or rewrite a built-in rule rather than add alongside it, save the output of claude auto-mode defaults to a file, edit the lists, and paste the result into your settings file in place of "$defaults".

Verdict: The "when to copy the full list vs use $defaults" framing the issue requested is now present on the linked configuration page.

Claim 4: https://code.claude.com/docs/en/settings autoMode row does not mention the sentinel behavior

Status: RESOLVED

At https://code.claude.com/docs/en/settings, the autoMode row (line 218) now reads:

Customize what the auto mode classifier blocks and allows. Contains environment, allow, soft_deny, and hard_deny arrays of prose rules. Include the literal string "$defaults" in an array to inherit the built-in rules at that position. See Configure auto mode. Not read from shared project settings

The example column for that row is {"soft_deny": ["$defaults", "Never run terraform apply"]}.

Verdict: The settings reference now documents "$defaults" directly in the autoMode row.

Claim 5: https://code.claude.com/docs/en/server-managed-settings example and surrounding text do not cover "$defaults"

Status: RESOLVED

The server-managed-settings example at https://code.claude.com/docs/en/server-managed-settings, lines 87-99, still shows a plain autoMode.environment block. It links out on line 99:

See Configure auto mode for how the autoMode entries affect what the classifier blocks and important warnings about the environment, allow, soft_deny, and hard_deny fields.

The linked target page (auto-mode-config) carries the full "$defaults" documentation, including the warning about omitting it (line 151) and the example block that keeps the built-ins via "$defaults" (lines 125-148). The server-managed-settings page is a deployment guide; the canonical reference for "$defaults" lives on the auto-mode-config page it links to.

Verdict: Although the managed-settings example does not embed the sentinel inline, it cross-links into the page that does. Combined with the settings reference and auto-mode-config reference, the sentinel is reachable from any path a reader would take from the managed-settings example.

Claim 6: https://code.claude.com/docs/en/cli-reference for claude auto-mode defaults does not cross-reference "$defaults"

Status: RESOLVED

At https://code.claude.com/docs/en/cli-reference, line 29, the claude auto-mode defaults entry now reads:

Print the built-in auto mode classifier rules as JSON. Use claude auto-mode config to see your effective config with settings applied

The command reference links to the permission-modes page, which links to the auto-mode-config page that documents "$defaults". The claude auto-mode config and claude auto-mode critique entries (lines 169-178 of auto-mode-config) also call out that the effective config expands "$defaults" in place and that claude auto-mode defaults is still the way to inspect or take full ownership of the built-in rules.

Verdict: Cross-references for the "$defaults" workflow now exist from the CLI reference, the permission-modes page, the settings reference, and the auto-mode-config page itself.

Claim 7: Suggested JSON example combining "$defaults" with custom rules across all three arrays

Status: RESOLVED

The example the issue proposed has been incorporated into auto-mode-config at lines 125-148. The published example is a superset of the suggestion (it also includes hard_deny) and uses the same prose style for the staging-deployment allow entry:

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/acme-corp and all repos under it"
    ],
    "allow": [
      "$defaults",
      "Deploying to the staging namespace is allowed: staging is isolated from production and resets nightly",
      "Writing to s3://acme-scratch/ is allowed: ephemeral bucket with a 7-day lifecycle policy"
    ],
    "soft_deny": [
      "$defaults",
      "Never run database migrations outside the migrations CLI, even against dev databases",
      "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"
    ],
    "hard_deny": [
      "$defaults",
      "Never send repository contents to third-party code-review APIs"
    ]
  }
}

Verdict: The example is published verbatim in the auto-mode-config reference.

---

Current State

| Claim | Status |
|-------|--------|
| 1. permissions page omits "$defaults" and documents replacement-only workflow | RESOLVED |
| 2. "$defaults" undocumented anywhere | RESOLVED |
| 3. permission-modes points at auto-mode defaults without cross-reference | RESOLVED |
| 4. settings autoMode row omits sentinel | RESOLVED |
| 5. server-managed-settings does not cross-reference "$defaults" | RESOLVED |
| 6. cli-reference for claude auto-mode defaults does not cross-reference "$defaults" | RESOLVED |
| 7. No example combining "$defaults" with custom rules | RESOLVED |

---

Suggested Fix

N/A — issue has been resolved.

---

References

---

Conclusion & Recommendation

Primary Concern: The auto mode documentation described custom allow/soft_deny/environment arrays as replacing the built-in rules and did not document the new "$defaults" sentinel that lets users extend the built-in list instead.

Resolution Status: RESOLVED

Recommendation: CLOSE

The dedicated auto-mode-config page now documents "$defaults" for environment, allow, soft_deny, and hard_deny, includes the JSON example pattern the issue proposed, explains when claude auto-mode defaults is still the right tool (taking full ownership of the list), and is reachable from permissions, permission-modes, settings, server-managed-settings, and cli-reference via cross-links. The settings reference row for autoMode also documents the sentinel directly.

github-actions[bot] · 1 month ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Related Claude Code issues

Matched on shared title terms, labels, topic and reported release — ranked so issues with real discussion come first.

Browse by topic

Browse all Claude Code issue topics →