Why is my permission mode not being applied?

claude --permission-mode plan

The flag always wins. If the flag works and the setting does not, the setting is being dropped somewhere below.

Answer

A mode set on the command line always applies. A mode set in a settings file can be dropped in five documented places: auto or bypassPermissions written in a project file, bypassPermissions or dontAsk on Claude Code for the web, a subagent's own permissionMode while the parent runs auto mode, a settings file outranked by another, and broad allow rules dropped on entering auto mode. Each one fails quietly.

What it does

The mode you set and the mode you get can differ, and nothing announces the difference. Five documented places drop a mode, each with its own tell.

Start by establishing which half of the problem you have. Run the mode as a flag:

claude --permission-mode plan

The flag outranks every settings file. If the flag works and your configured default does not, the mode itself is fine and the setting is being dropped; read on. If the flag also fails to change behaviour, the mode is applying and something inside it is prompting; that is a different question.

`auto` or `bypassPermissions` written in a project settings file

Two modes have a documented scope restriction: they do not take effect from .claude/settings.json or .claude/settings.local.json. What you get instead differs. With auto there, Claude Code skips straight to the built-in default for your plan, not to a defaultMode from ~/.claude/settings.json. With bypassPermissions there, the session starts in Manual. The bypassPermissions restriction is new in v2.1.257; before that it took effect from any file.

This is the most common version of this problem, because a project file is the natural place to put a team default, and the failure is silent. Move the value to ~/.claude/settings.json. See setting a default permission mode for which file outranks which.

`bypassPermissions` or `dontAsk` on Claude Code for the web

Cloud sessions do not honour defaultMode: "bypassPermissions" or "dontAsk" from settings files. A repository's checked-in settings cannot start a cloud session in either mode.

The setting is ignored silently and the session starts in the mode shown in the mode dropdown instead. So the same committed file behaves one way locally and another way on the web, which reads as a bug in the file rather than a documented restriction on the surface.

A subagent's own `permissionMode`, under auto mode

While the parent session runs auto mode, every subagent action goes through the classifier under the parent's rules, and any permissionMode in the subagent's frontmatter is ignored.

A subagent configured to run in acceptEdits therefore does not, if the session above it is in auto mode. The frontmatter is not wrong; it is outranked.

A settings file outranked by another

permissions.defaultMode exists in four files and only one of them wins. ~/.claude/settings.json is the weakest, so a project you cloned last week can quietly replace a default you set months ago. The file you are editing may simply not be the file in effect.

Broad allow rules dropped on entering auto mode

Not a mode being dropped, but the same symptom from the other direction: entering auto mode removes allow rules that amount to arbitrary code execution: blanket Bash(*), wildcarded interpreters like Bash(python*), package-manager run commands, Agent and Monitor rules.

Narrow rules such as Bash(npm test) stay. Claude Code restores the dropped rules when you leave auto mode. The effect is that switching *into* the mode meant to reduce prompts can produce more of them, for exactly the commands your broadest rule used to cover.

How to check

Work from the strongest source down, because that is the order that decides which value survives.

The flag first, as above: it settles whether the mode or the configuration is at fault. Then, if the setting is being dropped, check in this order:

1. Which surface — local CLI, cloud session, or subagent. Two of the five causes are surface restrictions, not file problems, and no amount of editing a settings file fixes them. 2. Which file — work down the precedence order and find the first file that sets a mode. That is the one in effect. 3. Which mode — auto and bypassPermissions from a project file are ignored; the rest are not.

Example

A .claude/settings.json committed for the team:

{
  "permissions": {
    "defaultMode": "auto"
  }
}

On an Enterprise plan or an API key, sessions keep starting in Manual, and the file looks correct because it is. auto is simply not read from a project file. On Pro, Max and Team the built-in default is auto anyway, so the same file appears to work while doing nothing, right up until a teammate on an account whose built-in default is Manual clones the repository. The same content works from ~/.claude/settings.json:

{
  "permissions": {
    "defaultMode": "auto"
  }
}

Which means a team default of auto cannot be committed at all, and from v2.1.257 neither can bypassPermissions: each person sets it in their own user file. A project file can carry the other modes.

Common mistakes

Editing the file that loses. Four files can set defaultMode, and ~/.claude/settings.json is the weakest of them. Confirm which file is in effect before rewriting its contents.

Assuming permission rules follow the same precedence as the mode. They do not. allow, ask and deny merge across files rather than replacing each other; only the mode follows file precedence. See why Claude Code keeps asking.

Treating a cloud session as the same environment. bypassPermissions and dontAsk from settings files do not apply there, by design. A file that works locally and not on the web is not broken.

Expecting a subagent to keep its own mode. Under auto mode it does not: the parent's rules apply and the subagent's permissionMode is ignored.

Reaching for a broader mode when one command keeps prompting. A permissions.allow rule for that command fixes the specific prompt without removing every other one. Switching to auto mode may even drop the broad rule you already had.