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:
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:
An organization can remove auto mode entirely, so nobody can select it, via managed settings:
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.ripgrepto be honored only from user, managed, and--settingssettings; 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
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.
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 outrightask— permission dialog appears even in auto mode"*"in the deny list blocks all tools (emergency lockdown) — exceptEndConversation, 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.)