Skip to content
Agentic Control Plane

AI Agent Tool Allowlists: Deny by Default, Scope per Task, Audit Everything

David Crowe David Crowe · · Updated · 7 min read
tool-policy allowlist default-deny claude-code codex mcp
Share X HN LinkedIn

An AI agent tool allowlist is the list of tools an agent may call. Everything not on the list is denied. It is the highest-leverage control you can put on an agent, because what an agent can do matters more than what it usually does. In one real Claude Code session we captured, the harness declared 76 tools to the model and 64 were never used. Each of those 64 is standing capability: send email, publish a web page, schedule its own future runs. Nothing stops them except the model deciding not to.

This page covers what an allowlist is, how to set one in Claude Code, Codex CLI and MCP, how to scope it per task, and where a client-side list stops holding.

Why deny by default, and where it goes wrong

A denied tool the agent did not need costs nothing. An allowed tool it misused costs whatever that tool could do, and for tools that send, pay or delete, you cannot roll that back.

Apply it too hard and you get the failure everyone hits: the agent asks permission to read a file, asks hundreds of times a session, and by day two you approve on reflex. So the working rule, argued in full here, is:

  • Allow the core loop. Read, search, edit, run code in a sandbox. That is the agent’s hands.
  • Deny the outward tail until you have a real need. That means send, publish, schedule and remote-spawn. Un-deny one tool at a time, not a whole family.
  • Put a human in front of anything irreversible, if your approval step is one a person actually reads.

The Tool Surface Index keeps captures of what each coding agent declares, grouped by how much damage a tool can do. Sort your agent’s tools into those groups and the allowlist mostly writes itself.

Claude Code

Claude Code reads permission rules from settings.json, either project-level .claude/settings.json or user-level ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(npm run test:*)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "WebFetch",
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(curl:*)"
    ]
  }
}

Three things the example does not show:

  1. Bash rules match the start of the command text. Bash(git diff:*) allows anything that begins with git diff. Anthropic’s docs say Bash deny rules can be sidestepped by how a command is written. Treat them as guardrails against accidents, not a security boundary.
  2. deny beats allow. A rule in both lists is denied.
  3. MCP tools are named mcp__servername__toolname. You can allow one tool from a server without allowing the whole server.

Codex CLI

Codex declares far fewer tools (17 in our capture, against 76 for Claude Code). It controls them with approval policies and sandbox modes instead of per-tool lists, in ~/.codex/config.toml:

approval_policy = "untrusted"     # ask before any command not on the trusted list
sandbox_mode    = "workspace-write"  # writes confined to the workspace

You get less detail, but the sandbox does structural work a list of command prefixes cannot. Codex has no per-tool allow or deny for its non-shell tools. To get that, put the control at the MCP connection or a hook.

MCP tools

An MCP server is a bundle of tools, and connecting one grants the whole bundle. The calendar server you added for scheduling can also read every event. There are two places to narrow it.

  • In the client. The mcp__server__tool rules above give you per-tool control. They live in a config file on the machine and apply to that one client.
  • At a gateway. Put a gateway in front of the MCP server that lists only the tools you enabled. The agent’s tools/list never includes the rest, so there is nothing to talk around. ACP’s MCP endpoint (https://api.agenticcontrolplane.com/mcp) works this way: a workspace has an enabled-tools list, and the dashboard can see the full catalog so you can turn tools on.

Scope per task, not per install

A standing allowlist answers what the agent may ever do. The better question is what it needs for this task. A code-review agent needs read and comment. The same harness doing a release needs push and publish. Two habits make that cheap:

  • Split by context. Interactive sessions, where you are watching, can ask. Background runs such as cron jobs and CI have nobody to ask, so the same tool should often be denied there.
  • Start narrow and widen on need. When the agent needs a denied tool, the deny message names the rule that fired. Un-denying one tool is a one-line change. That beats guessing the full list up front.

The longer argument for narrow, typed tools is in agent access control with scoped tools.

Where client-side allowlists stop holding

A list in settings.json, or any check that runs inside the agent’s own process, holds against mistakes. That is most of what goes wrong. It does not hold against two things people often assume it does.

  1. Command text hides the effect. A denied Bash(rm:*) does not catch the same deletion written as a script the agent created and then ran. The effect of a shell command is not in its first word. We walk through the documented cases in Claude Code’s deny list can be bypassed.
  2. Whoever can edit the config can remove the rule. A settings file is not a boundary. (--dangerously-skip-permissions is not that kind of opt-out in Claude Code. It removes prompts, and hooks and deny rules still run. Other harnesses differ. On Antigravity, the same flag removes hooks too.)

Two things help. Put the rules in a managed settings file users cannot edit, where your harness supports one. And keep a second layer that sees the actual call. ACP is a hook of that kind: it checks each tool call before it runs and writes a log row for it. It runs on the developer’s machine, so it is not out of the agent’s reach either. Turning off hooks turns it off, and the log is evidence, not proof. For the calls that matter, pair a hook with a sandbox, or with tools that live behind a gateway as above.

Audit keeps the list current

A list nobody reviews drifts. Harnesses load tools lazily, MCP servers connect mid-session, and updates add tool families. In our captured traffic, one session gained 21 tools partway through the day, with no prompt and no changelog. The list you wrote in January is matched against a tool surface you counted in January.

So the loop is: capture the declared tools, compare them across sessions, and log every allow and deny with the rule behind it. ACP does that for coding agents:

curl -sf https://agenticcontrolplane.com/install.sh | bash

Without ACP, the habit still works. Deny by default, allow the core loop, scope to the task, and recount the tools every so often.

Running Codex? One command adds a hook for shell, apply_patch and MCP calls. Each call is recorded, and a force-push, destructive SQL or curl | sh is blocked until you approve it on the console or from the email.

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
irm https://agenticcontrolplane.com/install.ps1 | iex

What the installer writes  ·  Codex guide  ·  free up to 5 agents

Share X HN LinkedIn
Get the next data drop
What agents actually cost, new tool-surface captures, and the occasional incident post-mortem — sent when we publish something worth your inbox, not on a schedule. Unsubscribe anytime.
Share: Twitter LinkedIn
Related posts

← back to blog