Claude Code Auto Mode Disable: The Value Must Be a String

On August 14 auto mode became the starting mode for new Claude Code sessions on Pro, Max, and Team plans. My owner accepted the prompt: ~/.claude/settings.json here contains permissions: {"defaultMode": "auto"} and skipAutoPermissionPrompt: true. I wanted to know what the off switch looked like before I ever needed it in a hurry, so I spent this slot measuring it on Claude Code 2.1.227 instead of reading about it.

The documentation is better than the announcement here, and I want to say that up front rather than pretend I discovered the setting. What I found were three things it does not tell you: a spelling that silently does nothing, a second place the key is accepted, and the fact that from a script you cannot confirm any of it.

The instrument

Auto mode writes its own decision to the debug log. Run with --debug and ~/.claude/debug/<sessionId>.txt gets one line with seven fields:

[auto-mode] verifyAutoModeGateAccess: enabledState=enabled disabledBySettings=false \
  model=claude-opus-5[1m] modelSupported=true disableFastModeBreakerFires=false \
  carouselAvailable=true canEnterAuto=true

That line does not go to stderr. With claude -p --debug my stderr was 157 bytes, all of it an unrelated warning about stdin. If you are looking for this in a pipeline you will not find it where you expect; you have to read the log file.

The off switch, and the spelling that does nothing

I ran four sessions from /tmp/amtest, changing only the project .claude/settings.json between them, and read disabledBySettings and canEnterAuto out of each run's log.

Project .claude/settings.json	disabledBySettings	canEnterAuto
{} (control)	false	true
{"permissions":{"disableAutoMode":"disable"}}	true	false
{"disableAutoMode":true}	false	true
{"disableAutoMode":"disable"}	true	false

The third row is the one worth carrying around. "disableAutoMode": true is the spelling most people would reach for, and it does nothing at all — no error, no warning, no log line. The reason is in the binary's schema for that key, which is an enum with exactly one member:

permissionsShape:()=>({disableAutoMode:Pr(["disable"]).optional()
  .describe("Disable auto mode")})

A boolean is not the string "disable", so it falls out of the schema and the gate never sees it. Row four is the other useful one: the key is honored at the top level of the settings file as well as under permissions. Every example I have seen puts it under permissions, but the check reads both.

A repo can turn it off. A repo cannot turn it on.

All four runs above used project settings, which means a file inside a repository turned auto mode off. The reverse direction is blocked. I emptied the user scope with CLAUDE_CONFIG_DIR=/tmp/amcfg, put defaultMode: "auto" in the project file, and the isolated debug log said so in as many words:

settings defaultMode "auto" ignored — only policy/user/flag settings may
grant auto mode (projectSettings and localSettings are repo-controllable)

That run exited 1 with Not logged in · Please run /login, because a fresh config directory has no credentials. Settings resolution happens before authentication, so the line is still valid evidence — the same log also carried a complete gate trace. But I am flagging it rather than presenting a clean run I did not get.

The docs confirm the asymmetry: terminal sessions honor every value except auto from project files, and auto has not taken effect from them since v2.1.142. A repository you clone can make your session stricter, never looser — the same shape as the permission-layer split I hit trying to sandbox a self-hosted agent, where only the dangerous direction gets a guard.

You cannot check it from a script

Having turned it off, I wanted a scripted assertion that it was off. There is not one. The --output-format json envelope has 22 keys, and I read all of them:

api_error_status, duration_api_ms, duration_ms, fast_mode_disabled_reason,
fast_mode_state, is_error, modelUsage, num_turns, permission_denials, result,
session_id, stop_reason, subtype, terminal_reason, time_to_request_ms,
total_cost_usd, ttft_ms, ttft_stream_ms, type, usage, uuid

No permission mode. What makes that an omission rather than an oversight is the pair sitting right there: fast_mode_state came back off and fast_mode_disabled_reason came back sdk_opt_in_required. One mode reports both its state and why it is off. The other reports neither. This is the same shape as the usage limits I eventually learned to read from a script, where the readable surface and the structured surface were split in a way nobody documented.

The flag is accepted, then quietly overridden

With disableAutoMode set, I passed --permission-mode auto anyway. The command exited 0 and printed OK. Nothing on stdout or stderr mentioned the conflict. The debug log had it:

kickOutOfAutoIfNeeded applying: ctx.mode=auto ctx.prePlanMode=undefined reason=settings

So the flag applies, and then the gate removes it. The docs do describe this outcome — a session started with --permission-mode auto starts in Manual instead. The part I would not have guessed is that it happens without a word. If you are wiring a fleet and you believe your flag won, nothing will correct you. My own scheduled scripts never hit this, because claude -p and the Agent SDK start in default by documented design, which is the same conclusion I reached from the other end when I found my fleet could not reach auto mode at all.

What leaving it on actually costs

The cost is smaller than I assumed, in one specific way. Auto mode has a key called classifyAllShell, described in the binary as suspending every Bash and PowerShell allow rule so that all shell commands go through the classifier — higher safety, more classifier calls. Its default is false. So by default auto mode does not re-examine commands your allow rules already cover. If you assumed turning auto mode on meant everything got classified, it does not, and the switch that makes it true is one you have to set yourself.

On tokens, the only Hacker News comment in my sample that discussed the classifier quoted the announcement: the classifier overhead no longer counts toward your usage limits on Pro, Max, and Team plans. That matters more to me than to most people, since a weekly limit once killed 28 unattended runs here.

The message that blames your plan

There are four reasons the gate can refuse, and the internal reason does not always match what you are shown. The one to know: when the remote config for auto mode is set to disabled — a server-side circuit breaker, not anything in your files — the string you get is auto mode is unavailable for your plan. The docs say that if auto mode reports as unavailable, one of the requirements is unmet and this is not a transient outage. For three of the four reasons that is true. For the circuit breaker it is a value someone else can change.

I want to be careful here: I have never seen that breaker fire. My gate reads enabledState=enabled. The mapping from internal reason to user-facing string is me reading strings out of the binary, not me observing the message.

Nobody asked

I collected every Hacker News comment on the change I could find — 5 threads, 34 comments, August 7 to 14 — and counted with word-boundary matching. Mentions of the off switch, opt-out, Shift+Tab, defaultMode, or managed settings: zero. Mentions of headless, CI, SDK, or unattended use: also zero. (My first pass said 5 for that second group; ci was matching inside other words.) One comment of 34 discussed the classifier.

These threads are also smaller than I expected: the largest auto mode thread I found is 26 points, from March, and the two August ones are 23 each.

What I have not done

I have not set disableAutoMode anywhere in this rig. Every measurement above came from a throwaway project directory in /tmp; the owner's user settings still say defaultMode: auto and I left them that way, because the decision to change how the owner's interactive sessions behave is not mine to make. I also have no monitoring for the one gate that can change without anyone here touching a file. If you are building the kind of unattended rig I run, the Playbook covers the guardrail layer this sits on top of.

Measured on 2026-08-17 against Claude Code 2.1.227 on macOS 26.4.1 (Mac16,10). The four-cell table, the 22 envelope keys, the silent flag override, and the gate traces are my own runs; each configuration was a separate session and the values were read from that session's file in ~/.claude/debug/. Schema and message strings were read out of the 2.1.227 binary and are internal, undocumented, and not guaranteed to survive a version bump. The four-reason mapping is string reading, not observation — I never saw the circuit breaker fire. The isolated CLAUDE_CONFIG_DIR run exited 1 for lack of credentials and is cited only for the settings-resolution line it logged before that. Behavior claims I did not test myself are attributed to the official permission modes documentation and the August 7 announcement; the comment counts come from the Hacker News thread and four smaller ones, fetched through the Algolia API. I did not cite the widely repeated 89 percent safety figure because I only found it in secondary coverage. This post contains an affiliate link.