Skip to content

Permissions & Auto Mode

Repeated permission prompts break autonomy. Three options, in order of trust.

"On Pro, Max, and Team plans, the built-in starting permission mode is auto mode." — Anthropic, Choose a permission mode

This changes the framing below. Auto mode used to be something you opted into for unattended runs. For most readers on those plans it is now where a session already starts, so the live question is no longer "when do I turn auto mode on" but when do I turn it off — see option 2, below.

1. Permission allowlists (surgical)

Allow specific commands you know are safe:

# In .claude/settings.json
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git *)", "Bash(pnpm *)", "Edit", "Read"]
  }
}

2. Auto mode (the default on Pro, Max, and Team — not an opt-in)

A separate classifier model reviews each tool call instead of you. Blocks scope escalation, unknown infrastructure changes, and actions that look driven by hostile content Claude read. Lets routine work proceed without interruption:

claude --permission-mode auto -p "fix all lint errors and commit"

The classifier itself defaults to a specific model, version-stamped:

"Improved auto mode: the permission classifier now defaults to Sonnet 5 for external sessions, validated on the session's first request and pinned for the session." — CHANGELOG.md, v2.1.210

If the classifier blocks an action 3 times in a row — not necessarily the same action; any allowed action resets the consecutive counter — or 20 times total in the session, auto mode pauses and Claude Code falls back to prompting you rather than looping forever (Choose a permission mode).

When it does NOT start in auto mode

The built-in starting mode is plan- and surface-dependent, not universal:

Surface Built-in starting mode
Terminal or VS Code, Pro/Max/Team plan (Claude Code v2.1.228+ on macOS/Linux/WSL, v2.1.233+ on native Windows) auto
claude -p (headless) or the Agent SDK default (Manual)
Enterprise plan or a Claude Console API key default (Manual)
Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS, or a signed-in Claude apps gateway session default (Manual) — but auto mode is selectable without an opt-in flag; see the v2.1.207 row below

("Which mode a session starts in", Anthropic. On earlier CLI versions than those listed, the built-in default is Manual everywhere.)

Turning it off

The official guidance is explicit that auto mode is convenience, not a safety guarantee:

"Auto mode reduces permission prompts but does not guarantee safety. Use it for tasks where you trust the general direction, not as a replacement for review on sensitive operations." — Anthropic, Choose a permission mode

Turn it off for one session with claude --permission-mode default (or Shift+Tab to cycle back to Manual), or as a standing default:

// ~/.claude/settings.json
{
  "permissions": { "defaultMode": "default" }
}

An organization can remove auto mode entirely, so nobody can select it, via managed settings:

{ "permissions": { "disableAutoMode": "disable" } }

Gotcha, version-stamped (v2.1.207): defaultMode: "auto" does not take effect from .claude/settings.json or .claude/settings.local.json — both repo-resident — only from ~/.claude/settings.json (user) or managed settings. A loop whose config lives in the repo and sets "defaultMode": "auto" there silently falls back to Manual mode with no error. Before v2.1.207, .claude/settings.local.json was read for this key, so a config that worked on an older CLI can go silently stale after an upgrade.

Auto mode: what changed, v2.1.205 → v2.1.257

Every row below is version-stamped and quoted verbatim from CHANGELOG.md (the rendered changelog at code.claude.com only covers v2.1.235 and later, so earlier entries here come from the raw GitHub file).

Version What changed Verbatim
v2.1.205 Session transcripts protected from tampering "Added an auto mode rule that blocks tampering with session transcript files."
v2.1.205 Unresolved deletion targets now questioned "Improved auto mode to ask before running rm -rf on a variable it can't resolve from context."
v2.1.207 Opt-in requirement removed on three providers "Auto mode is now available without CLAUDE_CODE_ENABLE_AUTO_MODE opt-in on Bedrock, Vertex AI, and Foundry; disable via disableAutoMode in settings."
v2.1.207 Repo-resident settings stop carrying autoMode "Changed auto mode to no longer read autoMode from .claude/settings.local.json (repo-resident); use ~/.claude/settings.json instead."
v2.1.208 Substitution forms close a deletion loophole "Catastrophic removals (e.g. rm -rf ~) in commands containing $(…)/backticks/<(…) now prompt in --dangerously-skip-permissions and auto mode, matching the plain form."
v2.1.210 Classifier model pinned per session "Improved auto mode: the permission classifier now defaults to Sonnet 5 for external sessions, validated on the session's first request and pinned for the session."
v2.1.211 Always-allow rules persist across worktrees "When you choose 'Yes, and don't ask again' … Claude Code saves the rule to .claude/settings.local.json at the root of the git repository, resolved through worktrees to the main checkout." — Configure permissions
v2.1.214 Long Bash commands always prompt "Fixed Bash permission checks misjudging very long commands — commands over 10,000 characters now always prompt instead of running automatically."
v2.1.236 Monitor allow rules paused during auto mode "Improved auto mode: Monitor allow rules are now set aside while auto mode is active, so Monitor commands are reviewed the same way Bash commands are."
v2.1.236 Git-status spoofing closed "Improved auto mode: the git status check can no longer be fooled by a repo's status.showUntrackedFiles=no setting into reporting a clean tree."
v2.1.246 Auto mode rules become editable in the UI "Added an Auto mode tab to /permissions for viewing and editing auto mode classifier rules."
v2.1.248 Hardened --restricted session mode added "Added --restricted (or CLAUDE_CODE_RESTRICTED=1): removes the built-in tools that run commands or code and WebFetch (unless named in --tools), keeps file tools inside the working directory, refuses bypassPermissions, and ignores user, project and local settings files."
v2.1.257 Cloud/container-escape primitives blocked by default "Added a Containment Escape rule to auto mode so cloud metadata-credential fetches, egress evasion, and cross-tenant reach are no longer auto-approved unless your environment marks them expected."
v2.1.257 Reads outside working directories can be fenced "Added a one-time prompt in auto mode before the first file read outside the working directories, with the option to block such reads (permissions.blockReadsOutsideWorkingDirectories)."
v2.1.257 bypassPermissions no longer settable from project settings "Changed defaultMode: \"bypassPermissions\" in .claude/settings.json or .claude/settings.local.json to be ignored, like \"auto\"; set it in user or managed settings, or pass --permission-mode."

The last row is a new setting, not just a prompt: set "permissions": {"blockReadsOutsideWorkingDirectories": true} to make the file tools refuse such reads in every permission mode, in every later session — not only auto mode (Configure permissions).

Two of the v2.1.207 changes above matter together for anyone deploying loops on Bedrock, Vertex, or Foundry: auto mode stopped requiring the CLAUDE_CODE_ENABLE_AUTO_MODE flag, and in the same release stopped reading autoMode from the repo-resident settings file. A loop config that relied on both — the env var and a committed .claude/settings.local.json — needs re-checking after an upgrade past v2.1.207: the flag now does nothing (accepted for compatibility only), and the setting needs to move to ~/.claude/settings.json.

Repo settings cannot escalate their own privilege

The v2.1.207 change above is one instance of a broader pattern across three releases: a committed .claude/settings.json or gitignored .claude/settings.local.json — both repo-resident, both writable by anything that can write to the repo — lost the ability to grant elevated trust on its own. defaultMode: "bypassPermissions" in project settings stopped being honored in v2.1.257 (table above); autoMode in .claude/settings.local.json stopped being read in v2.1.207 (table above); and outside permissions entirely, which binary the sandbox trusts for ripgrep was restricted to non-project sources in v2.1.232:

"Changed sandbox.ripgrep to be honored only from user, managed, and --settings settings; project settings can no longer override the sandbox's ripgrep binary." — CHANGELOG.md, v2.1.232

For a loop that clones and operates on an untrusted repository, this matters directly: the repo's own config file — which a hostile repo could ship pre-poisoned — can no longer vote itself into bypassPermissions, auto mode, or a substituted sandbox binary. Only settings outside the repo's write access (user-level, managed, or CLI flags) can grant that trust. See Agent Security Hardening § Where Default-Deny Actually Gets Loaded for the same principle applied at the OS/sandbox layer, plus a v2.1.260 nuance worth knowing before relying on strict sandbox mode.

The same boundary has a fail-open edge that points the other way, and it is easy to miss. A settings file's env block cannot turn restricted mode on either — the reference states it plainly: "Claude Code ignores this variable in a settings file's env block." So a loop that tries to pin its own hardening by committing

{ "env": { "CLAUDE_CODE_RESTRICTED": "1" } }

gets an unrestricted session and no error: the file is read, the variable is dropped, and nothing reports it. Set it in the environment the loop actually runs in, or pass --restricted (v2.1.248+). This is the same defect class as a silently-defaulting pipeline check — a control that cannot take effect must fail loudly, not pass quietly.

The confused-environment attack class

On 2026-08-27, Simon Willison published Breaking Claude Code Opus 5 Auto Mode, covering an exploit from prompt-injection researcher Johann Rehberger that worked 80% of the time. The mechanism, verbatim:

"tricking Claude Code into downloading and uncompressing a zip archive, then executing code that imports base64 without noticing that this will import and execute a local struct.py file extracted from the archive."

This is explicitly not classic prompt injection — no malicious instruction is ever followed. A reader named hyperpape put the distinction precisely, in a Lobsters comment Willison quoted in a 2026-08-30 update to the post:

"this doesn't fit the bill of a classic prompt injection attack because at no point are malicious instructions from the website accidentally followed by the LLM" — instead "this is more of a confused environment attack where the nature of the environment that the agent is exposed to results in an exploit."

The failure that made it worse than the exploit itself: auto mode's own safety gate blocked the agent's correct response. Willison, quoting the writeup:

"In a few cases auto mode directly prevented the agent from preventing harmful code from continuing to execute! … Claude detects the compromise, but Auto Mode blocks its cleanup command."

Willison's recommended mitigations, verbatim: "Run unattended coding agents in a container, VM or OS sandbox. Restrict network egress. Monitor your agents. Do not expose home directories, SSH keys, cloud credentials,… to the agent runtime." This is the same conclusion as Agent Security Hardening: OS-layer isolation is the load-bearing control for unattended loops, because a software-layer permission system — even a diligent one — can misjudge a case its designers didn't anticipate.

Timeline, stated without asserting causation. Five days after Willison's post, Claude Code v2.1.257 (2026-09-01) shipped the Containment Escape rule quoted in the table above — cloud metadata-credential fetches, egress evasion, and cross-tenant reach no longer auto-approved by default. The v2.1.257 release notes name none of Willison's post, Rehberger, or "confused environment attack," and the rule's own scope (cloud metadata endpoints, egress evasion, cross-tenant reach) is a different attack surface than Rehberger's local package-shadowing exploit. The five-day gap makes a connection plausible; nothing in either the post or the release notes establishes that v2.1.257 was a direct response to it.

3. bypassPermissions (CI / containers only)

Runs all tools without asking. Only use in isolated environments (Docker, CI, VMs) where the agent's actions cannot affect systems you care about.

claude --permission-mode bypassPermissions -p "run migration"

As of v2.1.126, bypass mode's own scope over protected paths has widened twice: --dangerously-skip-permissions first stopped prompting for writes to .claude/skills/, .claude/agents/, and .claude/commands/ (v2.1.121), then to .claude/, .git/, .vscode/, shell config files, and "other previously-protected paths" more broadly (v2.1.126) — no later changelog entry re-narrows this. Don't assume .claude/ or .git/ still get any special write protection under bypass mode on a current CLI; "isolated environment only" is the operative constraint, not a belief that repo-control files are fenced off. Bypass mode is still not an unconditional skip, though: explicit ask rules, rm/rmdir targeting a critical path, the cross-session messaging safeguards, and tools that require user interaction (AskUserQuestion, MCP tools marked requiresUserInteraction) all still prompt even in bypass mode. (CHANGELOG.md, v2.1.121, v2.1.126; Anthropic, Choose a permission mode.)

Deny and ask lists

Block specific tools or prompt for confirmation before others run:

// .claude/settings.json
{
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm run *)", "Edit", "Read"],
    "deny":  ["Bash(curl *)", "Bash(rm -rf *)"],
    "ask":   ["Bash(git push *)", "Bash(npm publish)"]
  }
}
  • deny — tool call is blocked outright
  • ask — permission dialog appears even in auto mode
  • "*" in the deny list blocks all tools (emergency lockdown) — except EndConversation, which a bare or glob deny rule can never remove while any other tool remains (added v2.1.214; Configure permissions § Tool name wildcards)

Command-argument and input-parameter patterns

Bash(git *) and Bash(rm -rf *) match on the Bash command text itself — a wildcard within the tool's primary content field. Agent(model:opus) uses a different mechanism, matching a named input parameter, that only works for fields other than a tool's primary content: a rule like Bash(command:rm *) is rejected with a startup warning ("would be bypassable by a compound command"); use Bash(rm *) instead (Configure permissions § Match by input parameter).

"allow": ["Bash(git *)"],          // command-text wildcard: any git command
"deny":  ["Agent(model:opus)"],    // input-parameter match: block Opus subagents (see caveat below)
"deny":  ["Bash(rm -rf *)"]        // command-text wildcard: block recursive deletes

Agent(...) rules were not enforced for named subagent spawns before v2.1.186 — the syntax parsed and silently did nothing. Subagents → Controlling subagent permissions has the four enforcement gaps and the version each closed in.

* matches any text and can appear at any position in a rule (v2.1.0+); a trailing wildcard like Bash(ls *) needs the preceding space to exclude prefix matches like lsof, and Bash(ls:*) is an equivalent trailing-wildcard shorthand. ** matches across path segments in Read/Edit/Cd rules. There is no single-character (?) wildcard. Configure permissions documents only * and ** — checked on the live page plus Wayback snapshots from 2026-06-03, 2026-07-03 and 2026-08-03, i.e. spanning the whole period this KB has made the claim, so this is not a token that was quietly dropped. A rule using ? matches literally, not as a wildcard.

PermissionRequest hook

Handle permission decisions programmatically instead of relying only on static allow/deny lists. The event is not auto-mode-specific: it runs whenever Claude Code is about to ask you for permission to use a tool — the ordinary interactive prompt in default mode included — and also in sessions that cannot show a prompt, where it denies the call if no hook returns a decision:

{
  "hooks": {
    "PermissionRequest": [
      {
        "type": "command",
        "command": "scripts/check-permission.sh"
      }
    ]
  }
}

The hook receives the tool name and input and returns a decision object inside hookSpecificOutput — not the permissionDecision field (whose allow/deny/ask/defer values belong to PreToolUse hooks, not this event):

{ "hookSpecificOutput": { "hookEventName": "PermissionRequest",
    "decision": { "behavior": "allow", "updatedInput": { "command": "npm run lint" } } } }

decision.behavior is "allow" or "deny" only — there is no ask or defer for this event. allow can carry updatedInput (replaces the tool's input, re-checked against deny/ask rules — v2.1.110) and updatedPermissions (persists a rule via the same addRules/replaceRules entries the interactive dialog uses). deny can carry message (shown to Claude) and interrupt (stops Claude entirely). The input also carries permission_suggestions, the rule updates behind the dialog's "always allow" options (not an exact list of what a human sees — the dialog can withhold or add options of its own) — so a hook can echo one back as its own updatedPermissions instead of composing a new rule (added v2.0.54).

Unattended-loop gotcha: a hook that exits without setting decision leaves the permission flow unchanged. That's harmless when a human can see the interactive prompt that follows, but a background subagent or other non-interactive session has no prompt to fall back to — the tool call is denied, not deferred to the auto-mode classifier. (Hooks reference — PermissionRequest, fetched 2026-09-07; CHANGELOG.md, v2.0.54, v2.1.89, v2.1.110.)

Approval Binding: The Action Approved Is Not Always the Action Run

Every gate above assumes that the action a human (or a classifier) approves, A, is the action the harness then executes. Approval Laundering (arXiv 2609.38983, 2026-09-30; preprint) tests that assumption and reports it failing systematically. It names six ways a harness can silently substitute A' for A after approval: Scope, Argument, Temporal, Tool, Delegation and Semantic laundering. The authors instrumented Claude Code's PreToolUse mediation point and ran a controlled, headless, repeated-measures study of each class (N=19-20 runs per class), reporting a Bound-Gap Rate with confidence intervals.

They also prototyped an Approval Token: a keyed capability over principal, agent id, session id, tool, arguments, scope and expiry, issued by a mediator that never gives the key to the agent. In a paired replay of 118 runs it fully eliminated Delegation laundering and, for their seeded session-identity-mismatch construction, Temporal laundering, but left Scope laundering unaffected by design and showed no significant reduction in Argument laundering. The authors call this an honest negative result: those two classes leave every recorded dispatch field unchanged, so a verifier that checks only fields at the tool-invocation boundary cannot see them. For a loop, the practical reading is that a PreToolUse or PermissionRequest hook that matches on the call it is shown is necessary but not sufficient; what the call does one process level down is a separate thing to test (compare Reject+Replan for the human side of the same gate). The results come from the authors' own instrumentation of one harness, and are a preprint.

Measured effects of permission mechanisms (HarnessSecurity-Bench)

HarnessSecurity-Bench (arXiv 2610.07639, 2026-10-06; preprint) is a 23-task, five-attack-surface benchmark run across six harnesses (Claude Code, Codex CLI, Gemini CLI, gptme, Qwen Code, GitHub Copilot), with GLM-5.2 as the fixed model so the harness is the variable (2,500 trials, 81,155 tool calls). Because the model is not a Claude model, read the numbers as properties of the mechanisms, not of any Claude configuration.

Mechanism Reported effect
Auto-approve Raises utility and raises attack success from 29.2% to 95.6%
Network isolation, read-only mode Reduce attack effects, with substantial utility loss
Command allowlisting Reduces attack effects with a small utility loss
Command denylisting Reduces attack effects with a utility gain

The task-level cases carry the transferable point: a restriction on a shared capability can obstruct legitimate and malicious operations alike, and an allowed tool or command can leave unauthorised operations reachable through an alternative execution path. That is the same reason Agent Security Hardening keeps OS-layer isolation underneath the permission list. The paper also finds about half of confirmed security mechanisms are opt-in, so check which are actually on.

Third-party classifiers in the auto-mode slot (OpenRouter Armor, beta)

explainx.ai's write-up (Oct 2026; a secondary explainer summarising OpenRouter's documentation) describes Armor, a beta classifier that sits between the model and your application and evaluates every tool call against plain-English rules in three tiers: hard-deny (nothing clears it), soft-deny (an allow rule or the user asking for that exact operation can clear it) and allow (exceptions only). It has an audit mode that returns the same verdicts but releases every call, so rules can be tuned on real traffic before enforcing. In its Claude Code compatible mode, Anthropic's own classifier is used where the request reaches an Anthropic endpoint that supports the beta, and Armor otherwise; the explainer notes the calling application is what actually stops a flagged call, so a client that ignores the verdict field will run it. OpenRouter's claim to beat Claude Code's auto classifier on accuracy and cost is unverified: per the explainer, no test set or numbers are published. Treat it as one more probabilistic gate, not a replacement for the sandbox layer.

Risk-Tiered Authorization by Consequence

Rather than categorising permissions by tool name, classify them by the reversibility of their outcome. This framing catches dangerous tool combinations that name-based lists miss:

Tier Consequence Examples Policy
Read Fully reversible — observation only File reads, listing directories, running tests Allow freely in all modes
Write Reversible with effort — changes can be undone File edits, git commits, opening PRs Allow in auto mode; log all actions
Irreversible Cannot be undone without significant recovery work rm -rf, force-push, database drops, secret rotation, production deploys Deny by default; require explicit ask even in auto mode

Apply this framing to the allow/deny/ask lists in .claude/settings.json:

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash(git commit *)", "Bash(git push origin feature-*)"],
    "ask":   ["Bash(git push origin main)", "Bash(npm publish)", "Bash(rm -rf *)"],
    "deny":  ["Bash(git push --force *)", "Bash(DROP TABLE *)"]
  }
}

(wquguru/harness-books, AgentWay, Jun 2026.)

Safety Path Denylist

For unattended loops, maintain a denylist of paths the loop must never touch autonomously, regardless of what it is instructed to do:

{
  "permissions": {
    "deny": [
      "Edit(**/.env)",
      "Edit(**/secrets/**)",
      "Edit(auth/**)",
      "Edit(payments/**)",
      "Edit(**/migrations/**)",
      "Edit(k8s/production/**)",
      "Edit(**/credentials/**)"
    ]
  }
}

Add project-specific sensitive paths to this list in .claude/settings.json before deploying any unattended loop. The denylist is a last-resort safety net — it does not replace scoped allowlists.

(cobusgreyling/loop-engineering, Jun 2026.)

Reject+Replan Pattern

When a safety gate (deny list, PermissionRequest hook, or budget cap) blocks an action, the loop should replan rather than abort. The safety layer is not a terminal error — it is a constraint the agent must reason around.

The pipeline within a single loop turn:

Validate (schema, intent) → Scope (permissions, boundaries) → Budget (cost, step, rate limit)
    → Allow  → execute
    → Reject → return rejection reason to agent → replan the step

Prompt addition for loops that will encounter permission gates:

If a tool call is denied, treat the denial message as a constraint, not a failure.
Replan the current step using an approach that does not require the denied action.
If no alternative exists, produce a handoff verdict with the blocked action listed
explicitly so a human can unblock it.

This prevents the loop from producing a silent stopped verdict when a gate fires. The agent either finds an alternative path or escalates cleanly as a handoff — both are deliberate outcomes. See Verification for the full verdict taxonomy.

(@akshay_pachaar, DailyDoseofDS, Jun 2026.)

Agent Trust Ramp

Before granting any loop write permissions, build trust incrementally:

Stage Mode What the loop can do
1. Read-only plan permission mode Read files, analyse state, report findings — no writes
2. Summarise Auto mode + read + summarise Write summaries to a dedicated output file; no code edits
3. Hard limits Auto mode + allow list Write code in specified paths only; hard denylist for infra/secrets
4. Loop cap Full auto mode Standard unattended loop with BUDGET cap and escalation path

Start every new loop at Stage 1, regardless of engineer experience. Advance only after one full week of zero unexpected actions at the current stage. These stages align with the per-loop readiness levels (L1 report-only → L2 assisted → L3 autonomous) — the trust ramp is the permission configuration that makes each readiness level operational.

"before you trust an agent to run on its own, do these 4 things" — @Sabrina_Ramonov, Jun 2026

The Cost of Refusal

Every gate above is tuned against one failure mode: a false ALLOW, where the model does something it shouldn't. A hardened gate has a second, symmetric failure mode that none of the tables on this page currently model — a false DENY, where the gate blocks work that was legitimate. That cost is not hypothetical; it changed which harness Andrew Ng's team runs.

Ng's team hit it directly while trying to security-review their own open source project:

"Unfortunately, when we tried to perform one such review, both Claude Code (running Fable 5) and Codex (running GPT 5.6 Sol) refused. Notably, Codex did a decent job mapping out possible attack vectors (following well known procedures like those documented by the U.S.-funded nonprofit MITRE) but then refused to proceed beyond a certain point." — Andrew Ng, Open Models, Open Harnesses, Open Security, 2026-07-31

Their response was not to loosen either harness's guardrails — it was to switch harness and model entirely:

"So we used an open agentic harness — OpenWorker itself! — with both GLM 5.2 and Kimi K3 to complete our security review." — Andrew Ng, same source

That is a false-refusal rate acting as a harness selection criterion, not a threshold tuned inside one harness. A week earlier, the same team made the identical move for the identical reason, one layer down the stack — a commercially hosted model wouldn't help analyse logs from a live attack on Hugging Face's infrastructure:

"the LLM refused to do so on safety grounds" — Andrew Ng, When Guardrails Go Wrong, 2026-07-24

Hugging Face used the open GLM 5.2 model instead — which had the side benefit of keeping the sensitive logs, attacker data, and credentials on their own infrastructure rather than sent to a third party.

Ng is explicit that this is not an argument against guardrails as such:

"Guardrails on LLMs do have a place. There are certain requests, such as for detailed directions to harm oneself or others, or for clearly criminal acts, that we're better off having models refuse." — Andrew Ng, When Guardrails Go Wrong

The design point for this page: deny and ask are tuned against the cost of a wrongly-allowed action. Nothing above is tuned against the cost of a wrongly-refused one — and for at least one team, that second cost was large enough to change which harness they run. A denylist or PermissionRequest hook that never gets measured for its false-refusal rate is only half specified. See Agent Security Hardening § Hardening During the Incident It Exists For for the same tension at the OS-hardening layer.

Relationship to Agent Security Hardening

The Agent Security Hardening doc covers the OS-layer complement to these software-layer controls: OS-user-per-agent kernel isolation, credential broker/sidecar dispositions, and the SECURITY_MATRIX.md adversarial policy.

Software-layer permission lists operate inside the model's execution environment. OS-layer hardening operates outside it — enforcing boundaries that the model cannot override even if instructed to. The two layers are designed to be deployed together.

ASK Verdict and Soft Warning Thresholds

Beyond hard ALLOW/DENY, a permission system can return a third verdict: ASK — "proceed only after human confirmation." This is distinct from DENY (blocked) and ALLOW (auto).

ASK verdict behaviour

Validate → Scope → Budget
    → ALLOW   → execute immediately
    → DENY    → reject; agent replans
    → ASK     → pause; surface to human; wait for explicit approval

ASK fires when an action is within the agent's declared scope but exceeds a risk or cost threshold. The agent does not retry, does not replan — it waits. This is the same Surface action described in Verification: emit a situation report and halt until a human responds.

Soft warning thresholds

omnigent-ai/omnigent's cost_budget policy gates spend at two levels: soft checkpoints that ASK once when cumulative spend first crosses them, and a hard max_cost_usd limit that then acts as a downgrade gate — denying further calls only while the session is on an expensive model, not stopping the session outright. It is configured as a server-side YAML policy, not a .claude/settings.json key:

# server_config.yaml (omnigent)
budget:
  type: function
  handler: omnigent.policies.builtins.cost.cost_budget
  factory_params:
    max_cost_usd: 5.00
    ask_thresholds_usd: [1.00, 3.00]

When cumulative session spend first crosses $1.00 or $3.00, the session ASKs for approval; once spend reaches $5.00, further turns/tool calls are blocked while the session is on an expensive model. Claude Code itself has no native budget_tokens, max_cost_usd, or ask_thresholds_usd settings keys — this is omnigent's own policy layer, illustrating the soft-threshold pattern rather than a .claude/settings.json feature.

The "approval valve" refinement — a hard block that used to be silent. A later omnigent fix changes what happens at an orchestrator-attached subagent cost budget specifically (one the orchestrator sets when spawning a subagent, not one the user configured): instead of a silent hard block when the subagent's cost cap is hit, it now surfaces an approval card and waits — the same ASK behaviour the ladder above already applies to user-set budgets, extended to budgets the system itself imposes. The approval decision is persisted in session state so the same subagent does not re-ask on every subsequent call once approved once. (omnigent-ai/omnigent #6505, Sep 2026.)

Evaluation order for a layered gate

Policies compose, and the order they run in matters: a cost/budget gate that fires before a scope (allow/deny) check would let a denied action consume budget before being blocked. A layered gate should evaluate cheapest/most-fundamental checks first: 1. Schema / intent validation (cheapest to check) 2. Scope (permission list — ALLOW/DENY/ASK per action) 3. Soft cost threshold (ASK) 4. Hard budget cap (fires last)

This is a general design pattern, not omnigent's own evaluation order — omnigent's policies run in the declaration order they're listed in the server/agent config, and any policy's DENY short-circuits the rest (docs/POLICIES.md).

(omnigent-ai/omnigent, docs/POLICIES.md, fetched 2026-09-07.)

Settings precedence

Highest wins — not "later overrides earlier." When the same key is set in more than one place, Claude Code uses the value from the highest level below; nothing you set overrides managed settings: 1. Managed settings (IT/org-wide — managed-settings.json, an MDM policy, or server-managed settings from the claude.ai console) 2. CLI flags (--permission-mode, --allowedTools, --settings <file-or-json>) 3. .claude/settings.local.json (project-local, gitignored) 4. .claude/settings.json (project, committed) 5. ~/.claude/settings.json (user)

List-valued keys such as permissions.allow merge across files instead of the higher level replacing the lower one. A small set of security-sensitive keys go the other way — Claude Code honors a stricter value from a lower level over a managed one ("Exceptions to managed settings precedence" on the same page). disableAllHooks is not one of those keys — it does not appear in the live "Exceptions to managed settings precedence" table (fetched 2026-09-07). The related v2.1.49 fix shows the ordinary rule being repaired, not an exception to it: before it, a non-managed setting could disable hooks a managed policy had turned on, and the fix — "Fixed disableAllHooks setting to respect managed settings hierarchy" — restored managed-wins. Hook entries follow a different rule again — see Hooks → Scope hierarchy. (Settings — Settings precedence, fetched 2026-09-07; CHANGELOG.md, v2.1.49.)