claude-code-headless-tool-restrictionlisted

# 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