Claude Code Permissions Best Practices: Headless Template

Posted on Oct 20 • Originally published at en.aobaworks.com

For unattended Claude Code runs, the best practice is simple to state. Every tool call the job can reach should resolve to a firm allow or deny in settings.json. Nothing should be left to a prompt. Run with claude -p in dontAsk or auto mode, add --permission-prompts none, which the official docs recommend " when nobody is available to answer permission prompts, for example in a scheduled job ", and keep a deny list for destructive and outbound commands. Save --dangerously-skip-permissions for a disposable container.

Start with a scoped allow list in dontAsk mode if this is your first overnight job. Move to auto mode once you trust the setup. Use bypass only inside a throwaway sandbox.

Why dontAsk for beginners: it denies every call that would otherwise prompt, so the worst outcome of a missing rule is a skipped step. You never get a surprise action. Why auto for daily work: a classifier judges the long tail of commands you didn't foresee. The trade-off is less predictability.

Claude Code permission rules have three outcomes, allow, ask and deny, and they're evaluated deny first, then ask, then allow. The first match wins. On top of the rules, a permission mode decides what happens to calls no rule covers.

The order is the key fact for unattended design. Specificity doesn't matter. A broad Bash(aws *) deny blocks aws s3 ls even if you also allow that exact command. Ask beats allow in the same way: a matching ask rule prompts even when a narrower allow rule also matches ( permissions docs ).

Some calls need no rule at all. In Manual mode (config value default ), file reads and Grep inside the working directory run without approval. So does a built-in set of read-only Bash commands. Edits, other shell commands, WebFetch and WebSearch need approval ( permissions docs ).

The modes, as of October 2026 ( permission modes, headless docs ):

Two version notes matter for scheduled jobs. From v2.1.302, claude -p runs start in Manual mode when nothing sets a permission mode. From v2.1.283, auto mode became the built-in starting mode for interactive terminal and VS Code sessions. The upshot is that a job you tested interactively may have run in a different mode than your cron job does. Always set the mode explicitly.

Put permission rules under the permissions key in settings.json. List them in allow, ask and deny arrays of Tool or Tool(pattern) strings.

Pick the file by who the rule is for ( settings docs ):

For a scheduled job, use the committed project file. The rules then travel with the repo to whatever machine runs the job.

This is an example to adapt. Swap npm for your own toolchain.

{ "permissions": { "defaultMode": "dontAsk", "allow": [ "Edit", "Bash(npm test)", "Bash(npm test *)", "Bash(npm run lint)", "Bash(npm run lint *)", "Bash(git status)", "Bash(git diff *)", "Bash(git log *)", "Bash(git add *)", "Bash(git commit *)" ], "ask": [], "deny": [ "Bash(git push *)", "Bash(rm *)", "Bash(curl *)", "Bash(wget *)", "Bash(sudo *)", "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)", "WebFetch" ] } } Enter fullscreen mode Exit fullscreen mode Path syntax for Read and Edit follows gitignore rules. Each prefix means something different ( permissions docs ):

A common mistake is writing Read(/etc/passwd) and expecting an absolute path. The single leading slash means "relative to the settings source". For absolute paths you need //.

To run Claude Code unattended, use claude -p, set a mode explicitly, and add --permission-prompts none. Then make sure every call the job needs is covered by an allow rule.

"Halting" happens in three different ways, and each has its own fix:

cd /path/to/repo && claude --bare -p "Run the test suite, fix failures, and commit the fix" \ --permission-mode dontAsk \ --permission-prompts none \ --settings.claude/settings.json \ --output-format json > /var/log/claude-nightly.json Enter fullscreen mode Exit fullscreen mode Why each flag:

For the scheduling side (crontab entries, environment variables, logging), see Claude Code Cron Job Setup: Run Automations Overnight. For jobs that died for reasons other than permissions, Why Claude Code Stops Mid-Automation (and How to Fix It) covers the rest.

Choose dontAsk when the task is the same every night, like running tests or regenerating docs. Choose auto when the task varies and you can't list every command ahead of time.

Auto mode has limits worth knowing. It needs a recent model: per the feature availability page, that means Opus 4.6+, Sonnet 4.6+, Haiku 5.5, or a Fable model. In an interactive session, auto mode pauses and goes back to prompting after the classifier blocks 3 actions in a row or 20 in total. In a -p run, Claude Code doesn't stop the run at those thresholds. Billing depends on setup. On Pro, Max and Team plans, classifier calls no longer count toward usage limits, but behind an LLM gateway or proxy Claude Code may make its own billed classifier requests. Check that page if you route through one.

Auto mode isn't the right fit if you need exact reproducibility or an audit trail where "a model decided" won't do.

For single-value keys like defaultMode, Claude Code uses this precedence: managed settings, then command line, then project local, then shared project, then user. Permission arrays don't override each other. They merge.

From the settings docs: "A key set at a higher level overrides the same key set lower down."

The part that trips people up is arrays. When permissions.allow or permissions.deny appears in several files, Claude Code combines the lists. So a deny in your user file blocks an allow in the project file, and the reverse is true as well. Deny rules from every scope are checked before any allow rule.

Write Claude Code Bash allow rules for specific commands and subcommands, such as Bash(git commit *), never a bare Bash or Bash(git *).

How matching works ( permissions docs, headless docs ):

For ready-made rule sets, AI Agent Guardrails Example: Copy-Paste Claude Code Rules has more templates.

Deny dangerous actions in Claude Code with permissions.deny entries for destructive commands, network tools and secret files. Deny beats allow at every scope.

A deny list is a filter on command strings. It isn't a jail. Bash(rm *) doesn't stop find. -delete or python -c "import shutil;...". Read(./.env) covers Claude's file tools, but a shell command like cat.env is a Bash call that needs its own rule. Two backstops close these gaps:

If a run does damage local files, Claude Code Checkpoints: How Rollback Works in Automations explains what can and can't be undone.

Use a Claude Code PreToolUse hook to approve, deny or escalate a tool call from a script. A PermissionRequest hook answers prompts that would otherwise reach a human.

The two events do different jobs ( hooks reference ):

When several PreToolUse hooks disagree, deny beats defer, which beats ask, which beats allow. A hook's "allow" also has limits. It skips the prompt, but it doesn't override the actions no mode auto-approves ( hooks reference ). In the Agent SDK, deny and ask rules are still evaluated after a hook returns allow ( SDK permissions ).

This is an illustrative example. Save it as.claude/hooks/push-guard.sh and make it executable ( chmod +x ).

#!/usr/bin/env bash cmd = $( jq -r '.tool_input.command // ""' ) if [[ " $cmd " = ~ ^git \ push \ origin \ bot/[A-Za-z0-9._-]+ $ ]]; then decision = allow; reason = "push to bot/ branch" elif [[ " $cmd " == git \ push * ]]; then decision = deny; reason = "only bot/* pushes allowed overnight" else exit 0 fi jq -n --arg d " $decision " --arg r " $reason " \ '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:$d,permissionDecisionReason:$r}}' Enter fullscreen mode Exit fullscreen mode Register it in.claude/settings.json:

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": ".claude/hooks/push-guard.sh" } ] } ] } } Enter fullscreen mode Exit fullscreen mode Remove Bash(git push *) from your deny list for this to work. Deny rules are still checked, and a deny would block the push the hook approved.

Don't use hooks this way if your only need is a fixed command list. Plain rules are easier to audit. Also keep in mind that --bare skips hook discovery, so pass hooks through --settings in bare runs. More scripts are in Claude Code Hooks Examples: 7 Copy-Paste Scripts.

Test a Claude Code permission config by running the exact headless command once while you're watching. Then read permission_denials and turn each one into an explicit allow or deny.

The file is settings.json, not permissions.json. A file named permissions.json is never read, which is a common reason "my rules do nothing".

claude -p "<same prompt>" --permission-mode dontAsk --permission-prompts none \ --output-format stream-json --verbose > preflight.jsonl Enter fullscreen mode Exit fullscreen mode List what got blocked. Denials show up as permission_denied system messages, and the final result lists them in permission_denials ( headless docs ): jq 'select(.type=="result") |.permission_denials' preflight.jsonl Enter fullscreen mode Exit fullscreen mode For each denial, decide: needed means add a scoped allow, never needed means add an explicit deny. Repeat until permission_denials is empty, or contains only denials you expected.

Check the exit code ( echo $? ). Claude Code exits non-zero when the run fails, but a run with denials can still exit 0. Make your wrapper fail the job when permission_denials isn't empty.

Common pre-flight mistakes Testing in a different directory than cron uses../ rules resolve against the current directory. Start the cron command with cd /path/to/repo. Testing interactively in auto mode.

The classifier approved things that dontAsk will deny. Test with the same mode you'll schedule. Running cron as root.

Bypass mode refuses root ( permission modes ), and root makes every rule gap more costly. Use a dedicated user. Ignoring cost and rate limits during testing.

Several test runs add up. See Claude Code: How to See Token Usage (and Reduce It) and Claude Code Rate Limit Reached: Retry Setup for Cron Jobs. Next steps You can finish the setup in under an hour today.

If you'd rather not do it yourself: the realistic option is an official plan with fewer moving parts. Claude Pro costs $20/month billed monthly, and Max starts at $100/month ( Claude pricing, as of October 2026; check the official page). Claude Code is included in both, and auto mode's classifier calls don't count toward usage limits on these plans ( billing page ). That lets auto mode cover commands you didn't list.

Team Standard seats are $25/month billed monthly ( pricing, as of October 2026). Those add organization-level managed settings, if several people share the jobs.

Yes. Put rules in each repo's.claude/settings.json and they apply only there. Within a repo, Read and Edit rules take gitignore-style paths like Edit(/src/**), so you can limit edits to one folder. Rules in ~/.claude/settings.json apply everywhere and merge with the repo's lists ( settings docs ).

The deny rule wins. Claude Code checks deny rules first, then ask, then allow, and stops at the first match. How specific each rule is doesn't change that, and neither does which settings file it came from ( permissions docs ).

Only inside an isolated container or VM with no secrets and restricted network. The flag equals --permission-mode bypassPermissions, which even allows writes to.git and.claude ( permission modes ). On shared runners, prefer dontAsk with an allow list, and set disableBypassPermissionsMode so nobody can turn bypass on.

The Agent SDK uses the same rules but adds your own code to the flow. Hooks run first, then deny rules, ask rules, the permission mode, allow rules, and finally your canUseTool callback ( SDK permissions ). The risk unattended is that callback: if it waits for a human, the run waits too. Pass --permission-prompts none, or make the callback return a decision without waiting for anyone.

This article was created with the help of AI. Sources are linked inline; check the official documentation for the latest details.