jackson2w/claude-code-skills / claude-code-headless-tool-restriction
claude-code-headless-tool-restriction
UnverifiedThis 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>"
--disallowedToolsis what actually blocks tools — confirmed the agent reports them as genuinely unavailable ("I have no Bash tool in this environment"), not merely declined.--allowedToolsis still required alongside it for any tool that Claude Code treats as write-capable/permission-gated (e.g.Write,Edit).--permission-mode dontAskdenies those outright unless explicitly allowed — confirmed:Writefailed with "permission denied ('don't ask mode')" when only--disallowedToolswas set andWritewasn't also in--allowedTools. These are two independent mechanisms, not redundant with each other.- Omit
--bareif the agent needs to write files.--baresilently suppresses theWritetool entirely regardless of--allowedTools— a Write test under--bareproduced no file and no error, just silent failure. (--bareotherwise 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
--allowedToolsalone 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, likewhoamivia 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_KEYis load-bearing. Without it, a "pass" might have come from Anthropic.ANTHROPIC_AUTH_TOKENis sent asAuthorization: Bearer, which most gateways accept.- Prove which model answered:
modelUsagekeys in the JSON output. Don't trust the flag. total_cost_usdis 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/nullon stdin. Without it every run stalls ~3 s waiting for input.- Probe the route before wiring anything. POST to
/v1/messageswith 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 lowchanged 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 464k | Updated | Claude CodeCodex | Verified | Install |
| 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: 464k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |