Skip to content

jackson2w/claude-code-skills / claude-code-headless-tool-restriction

claude-code-headless-tool-restriction

Unverified

This skill should be used when building an unattended/headless `claude -p` invocation (cron job, systemd timer, CI step, webhook handler) that needs a real security boundary restricting which tools the agent can use — not just permission-prompt convenience. Trigger phrases include "headless claude code", "unattended claude -p", "restrict claude code tools", "claude code allowedTools", "claude code disallowedTools", "safe automated claude invocation".

Restricting tool access in headless Claude Code invocations

Covers what actually works when a headless/scheduled claude -p invocation must be genuinely prevented from running certain tools (Bash, Edit, network access, etc.) — as opposed to interactive use, where permission prompts are just a UX convenience. Verified via direct empirical testing on Claude Code 2.1.214 (2026-07-18); re-verify against the current version before relying on this for a new build, since this is exactly the kind of CLI behavior that could change between releases.

The core finding: --allowedTools is not an allowlist

It's tempting to assume --permission-mode dontAsk --allowedTools "Read,Write" restricts the agent to only those two tools. This is false. Tested directly: with only --allowedTools 'Read Write' set (no --disallowedTools), the agent's Bash tool still ran — whoami executed successfully despite Bash never being named in --allowedTools.

--allowedTools only pre-approves the named tools so they skip permission prompts. It does not hide or block any tool not on the list. If tool restriction is a real safety requirement (the agent has SSH/infrastructure access, handles credentials, or runs unattended against production systems), --allowedTools alone provides no security boundary at all.

The fix: --disallowedTools, naming every tool explicitly

The only mechanism confirmed to reliably block a tool is --disallowedTools, listing it by name. Both flags are needed together, because they solve two different problems:

claude --permission-mode dontAsk \
  --allowedTools 'Read Write' \
  --disallowedTools 'Bash Edit Agent CronCreate CronDelete CronList DesignSync EnterWorktree ExitWorktree Monitor NotebookEdit PushNotification SendMessage TaskCreate TaskGet TaskList TaskOutput TaskStop TaskUpdate WebFetch WebSearch Workflow ToolSearch Skill ScheduleWakeup ReportFindings' \
  -p "<prompt>"
  • --disallowedTools is what actually blocks tools — confirmed the agent reports them as genuinely unavailable ("I have no Bash tool in this environment"), not merely declined.
  • --allowedTools is still required alongside it for any tool that Claude Code treats as write-capable/permission-gated (e.g. Write, Edit). --permission-mode dontAsk denies those outright unless explicitly allowed — confirmed: Write failed with "permission denied ('don't ask mode')" when only --disallowedTools was set and Write wasn't also in --allowedTools. These are two independent mechanisms, not redundant with each other.
  • Omit --bare if the agent needs to write files. --bare silently suppresses the Write tool entirely regardless of --allowedTools — a Write test under --bare produced no file and no error, just silent failure. (--bare otherwise skips hook/skill/MCP auto-discovery, which is often desirable for a fixed, predictable unattended task — keep using it, just not combined with a Write requirement.)

Get the full tool list before writing the deny list

Enumerate what's actually available first, so the deny list is complete rather than guessed:

claude --permission-mode dontAsk --allowedTools 'Read Write' \
  -p 'List every tool name you have access to, one per line, nothing else.'

As of 2.1.214 (no --bare), the full default set is: Bash Edit Read ReportFindings ScheduleWakeup Skill ToolSearch Workflow Write Agent CronCreate CronDelete CronList DesignSync EnterWorktree ExitWorktree Monitor NotebookEdit PushNotification SendMessage TaskCreate TaskGet TaskList TaskOutput TaskStop TaskUpdate WebFetch WebSearch. Include ToolSearch in the deny list specifically — it can load additional deferred tools (MCP connectors, RemoteTrigger, etc.) not in this base list at all, and was confirmed blocked from doing so when disallowed (ToolSearch: blocked — no ToolSearch tool is available to load Bash).

Why this matters more than it looks

--disallowedTools is an explicit deny-list, not a true allowlist — there is no flag combination found so far that behaves as a genuine strict allowlist. This means:

  • The deny list must be re-enumerated whenever a Claude Code upgrade adds new tools this version doesn't have yet, or a newly-added tool silently slips through unblocked.
  • Never trust --allowedTools alone as a security boundary, no matter how narrow the allowed set looks. Always verify with a direct test (try to run something outside the intended scope, like whoami via Bash) before trusting a new unattended invocation with real credentials or infrastructure access.

Verifying the combination actually works

Before shipping any unattended job built this way, run a direct adversarial test — don't just trust the flags:

claude --permission-mode dontAsk \
  --allowedTools 'Read Write' \
  --disallowedTools '<full deny list>' \
  -p 'First try to run "whoami" via Bash. Then try to write OK to /tmp/test.txt via Write. Report exactly what happened.'

Expect: Bash reported as unavailable/blocked, Write succeeds and the file is actually created (verify on disk, don't just trust the model's claim).

Running a headless job on a different model endpoint, with a fallback (2026-09-12)

Claude Code can point at any Anthropic-compatible /v1/messages gateway (e.g. a flat-rate router serving non-Claude models). Scope it to the one subprocess. Never put ANTHROPIC_BASE_URL in settings.json, and never on a Remote Control host, where it disqualifies Remote Control:

env -u ANTHROPIC_API_KEY \
  ANTHROPIC_BASE_URL=https://gateway.example.com \
  ANTHROPIC_AUTH_TOKEN="$GATEWAY_KEY" \
  claude -p "$PROMPT" --model <gateway-model-id> --output-format json \
  --disallowedTools "<same deny list>" </dev/null > out.json
  • env -u ANTHROPIC_API_KEY is load-bearing. Without it, a "pass" might have come from Anthropic. ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer, which most gateways accept.
  • Prove which model answered: modelUsage keys in the JSON output. Don't trust the flag.
  • total_cost_usd is computed from the CLI's own Claude price table. On a flat-rate or non-Claude gateway it's meaningless; never use it in a cost comparison.
  • </dev/null on stdin. Without it every run stalls ~3 s waiting for input.
  • Probe the route before wiring anything. POST to /v1/messages with a deliberately invalid key: a 401 with an auth hint means the route exists, a 404 means it doesn't. No real credential needed.

Cross-provider fallback lives in the wrapper. The CLI's own fallback only switches models within one endpoint.

  • Run primary → validate → on failure re-run the fallback arm → record which arm produced the result and why (an append-only log plus the job's run record).
  • Fall back on: rc≠0; a sub-timeout (primary + fallback must both fit inside the unit's job timeout); is_error/subtype≠success; 429/overloaded/5xx; an empty result; or the job's own validation hook failing (required report sections, a JSON schema).
  • Cap the gateway arm's internal retries (e.g. CLAUDE_CODE_MAX_RETRIES-style env). Uncapped, an invalid key spent ~120 s retrying before failing.
  • Pass identical tool restrictions to both arms.
  • Test the fallback both ways: an injected bad key, a missing key, and a forced validation failure, each showing the fallback model in modelUsage.

Test a non-Claude model on the REAL workload before switching production. A short tool round trip (Read a file, answer) passed on GLM-5.3, then the same model failed both real jobs:

  • a long grading prompt used its full 540 s thinking and produced nothing
  • a report-writing prompt ran four back-to-back 32k-token thinking turns and wrote nothing in 30 min
  • a thinking-token cap and --effort low changed neither

A smaller sibling (GLM-5.3-flash) finished both, but burned a malformed tool call every run and graded and itemised more loosely than Claude. Failure-triggered fallback can't catch a well-formed but weaker answer. Run a shadow comparison against the incumbent model (no side effects, results diffed per item) for anything that feeds a report a person relies on.

Real-world reference implementation

Built for the homelab's weekly automated housekeeping sweep — a headless Claude Code invocation on a systemd timer that reads a read-only fleet-check script's JSON output plus a CLAUDE.md gotcha file for context, and writes a report, with zero ability to run Bash/Edit/ network tools against the actual infrastructure. See homelab-ansible/scripts/weekly-housekeeping-run.sh (graduated into version control 2026-08-17 — deployed to /root/bin on ansible-ctrl via homelab-report-timers.yml; previously kept local-only/uncommitted over a since-superseded worry about committing its --disallowedTools flags, which aren't secrets) for the full working wrapper.

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall