claude-code - 💡(How to fix) Fix [DOCS] Auto mode docs omit `settings.autoMode.hard_deny` for unconditional classifier blocks

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/auto-mode-config

Section/Topic

autoMode classifier rule configuration, especially the "Override the block and allow rules" section and the autoMode settings reference.

Current Documentation

The docs currently say:

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. Each is an array of prose descriptions, read as natural-language rules. There is no autoMode.deny field; to hard-block an action regardless of intent, use permissions.deny, which runs before the classifier.

Inside the classifier, precedence works in three tiers:

• soft_deny rules block first
• allow rules then override matching blocks as exceptions
• Explicit user intent overrides both: if the user's message directly and specifically describes the exact action Claude is about to take, the classifier allows it even when a soft_deny rule matches

And the settings reference says:

autoMode | Customize what the auto mode classifier blocks and allows. Contains environment, allow, and soft_deny arrays of prose rules. Include the literal string "$defaults" in an array to inherit the built-in rules at that position.

What's Wrong or Missing?

The current docs still describe autoMode as if it only supports environment, allow, and soft_deny, and they explicitly direct readers to permissions.deny as the only way to create an unconditional block.

That is outdated for v2.1.136: the changelog entry says Claude Code added settings.autoMode.hard_deny for classifier rules that block unconditionally regardless of user intent or allow exceptions.

As written now, the docs leave administrators with the wrong model for classifier precedence:

A. The new setting is undiscoverable

There is no documentation for autoMode.hard_deny in the auto mode guide or the main settings reference.

B. The current precedence description is incomplete

The docs currently say explicit user intent overrides classifier block rules, but they do not explain that hard_deny is the classifier-level mechanism that should not be overridden by user intent or allow exceptions.

C. The workaround described is a different layer

permissions.deny still matters, but it is a pre-classifier permission rule, not the same feature as a classifier-level autoMode.hard_deny rule.

Suggested Improvement

Update the auto mode docs and settings reference to document autoMode.hard_deny explicitly.

Minimum fix:

1. Add hard_deny to the autoMode settings reference alongside environment, allow, and soft_deny.
2. Update the auto mode configuration page to explain precedence between hard_deny, soft_deny, and allow.
3. Clarify that explicit user intent can override soft_deny, but not hard_deny.
4. Keep permissions.deny documented as the separate permission-system layer that runs before the classifier, rather than describing it as the only unconditional-block option.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Relevant changelog context: v2.1.136 added settings.autoMode.hard_deny for classifier rules that block unconditionally regardless of user intent or allow exceptions.