Permissions, Sandboxes and Hooks: Containing an AI Agent

A coding agent runs commands it wrote a moment ago, on a machine that holds your source code, credentials and network access. Two things can go wrong. The model can simply make a destructive mistake. Or text it reads, in an issue, a web page or a dependency's README, can steer it: prompt injection, covered in its own lesson in How Agentic AI systems work.

Simon Willison named the dangerous combination the lethal trifecta. An agent is exposed to data theft when it has all three of:

1. access to private data
2. exposure to untrusted content
3. the ability to communicate externally

Any one or two are manageable. All three together let injected instructions read your secrets and send them somewhere. Willison's advice is to avoid the combination entirely rather than trust a filter to catch attacks, noting that vendors claim to stop "95% of attacks" while "in web application security 95% is very much a failing grade."

Key idea: Harness security is mostly about removing a leg of the trifecta by construction, then making the remaining permissions narrow enough that mistakes stay small.

Controls on an agent differ in who enforces them, and that decides what they can be trusted with.

Claude Code's documentation states the first line of this table directly: permission rules are enforced by Claude Code, not by the model, and instructions in a prompt or CLAUDE.md shape what Claude tries to do but do not change what it is allowed to do.

In practice: Use instructions for preferences, permission rules and hooks for policy, and the sandbox for anything whose failure would be a security incident.

Agents expose a dial between asking about everything and asking about nothing. Claude Code's documented modes make the spectrum concrete:

OpenAI's Codex CLI splits the same dial into two settings: a sandbox mode (read-only, workspace-write, danger-full-access) that decides what the process can do, and an approval policy (such as untrusted, on-request, never) that decides when it asks.

Gotcha: dontAsk and bypassPermissions sound alike and are opposites. One refuses whatever is not pre-approved; the other approves almost everything.

Permission rules are patterns over tool calls, kept in settings files you can commit to the repository so the whole team shares them:

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)", "WebFetch(domain:docs.python.org)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Read(./.env)", "Read(./secrets/**)", "Bash(curl *)"]
  }
}

Claude Code evaluates rules in a fixed order: deny, then ask, then allow, and the first match wins regardless of which rule is more specific. So a broad deny cannot be carved open by a narrow allow. Managed settings deployed by an administrator sit above user and project settings, and no other level, including command-line flags, can override a managed rule.

Two practical consequences follow. Deny lists are the right tool for "never", since nothing downstream can undo them. And allow rules should be as narrow as the work permits: Bash(npm run *) approves every npm script, including ones added to package.json later.

The settings above deny Bash(curl *). Suppose injected text convinces the agent to send the contents of a file to an outside server.

An operating-system sandbox restricts the agent's processes directly, so it applies to every command and every child process, however it was spelled. Anthropic's post on Claude Code sandboxing describes two boundaries:

• Filesystem isolation: processes can read and write only approved directories, so an injected agent cannot modify sensitive system files.
• Network isolation: outbound traffic goes through a proxy that allows only approved domains and asks the user about new ones.

These are enforced with OS primitives, bubblewrap on Linux and Seatbelt on macOS, and Anthropic published the runtime as the open-source sandbox-runtime package. The post is emphatic that you need both: without network isolation a compromised agent can exfiltrate files like SSH keys; without filesystem isolation it could escape the sandbox and gain network access.

Key idea: Network isolation removes the third leg of the lethal trifecta for everything inside the box. That is why it is worth more than any number of command-pattern rules.

It is tempting to treat every approval prompt as a safety feature. Anthropic's sandboxing post argues the reverse: constantly clicking approve leads to approval fatigue, "where users might not pay close attention to what they're approving, and in turn making development less safe."

A sandbox changes the question from "is this command safe?" to "is this command safe inside these boundaries?", which is nearly always yes. Anthropic reports that in its internal usage, sandboxing reduced permission prompts by 84%. The prompts that remain are the ones that deserve attention: a request to reach a new domain, or to write outside the project.

In practice: Measure how often your team approves prompts without reading them. If the answer is "most of the time", the prompts have stopped being a control.

A hook is a script the agent program runs at a fixed point in its lifecycle. In Claude Code a PreToolUse hook receives the pending tool call as JSON on stdin; exit code 2 blocks the call and whatever the script writes to stderr is shown to the model. This one protects paths that no agent should edit:

#!/usr/bin/env python3
# PreToolUse hook for Edit|Write: refuse writes to protected paths.
import json, sys
from fnmatch import fnmatch

PROTECTED = [".env*", "*/.env*", "*/migrations/*", ".github/workflows/*"]

event = json.load(sys.stdin)
path = event.get("tool_input", {}).get("file_path", "")
rel = path.removeprefix(event.get("cwd", "") + "/")
if any(fnmatch(rel, pat) for pat in PROTECTED):
    print(f"Blocked: {rel} is protected. Propose the change in your reply instead.",
          file=sys.stderr)
    sys.exit(2)   # block; stderr goes back to the model
sys.exit(0)       # no decision; normal permission rules apply

Registered under hooks.PreToolUse with matcher "Edit|Write", it turns a write to db/migrations/0042_drop_users.sql into a refusal with a reason. The documentation specifies the interaction with rules: a blocking hook stops the call even if an allow rule matches, but a hook returning "allow" cannot override a deny rule.

Each layer can stop the call; only the last one is enforced by the operating system.

The most reliable secret is one the agent's processes cannot read at all. Anthropic's post describes how Claude Code on the web applies this: git credentials and signing keys are never inside the sandbox. A proxy outside the sandbox handles git operations, and the sandbox authenticates to that proxy with a scoped credential, so a compromised session cannot copy the real key.

The same principle scales down to a laptop:

• Deny reads of secret files (Read(./.env), Read(./secrets/**)) and keep them outside the sandbox's readable paths.
• Give agents scoped, short-lived tokens: read-only where possible, limited to one repository, expiring after the task.
• Prefer a proxy or tool that performs a privileged action over handing the agent the credential that performs it.
• Keep deploy and billing access out of agent sessions entirely; let a human or a separate pipeline hold them.

Gotcha: An environment variable is readable by every process the agent starts. Exporting a production key "just for this session" puts it one env command away from any injected instruction.

Put together, the layers let you decide which leg of the trifecta each agent gives up, instead of hoping a filter catches attacks.

The last row is the default state of many local setups. The other three are ordinary configurations of the tools covered in this lesson.

Try it: For each agent your team runs, fill in this table. Any row with three "Yes" entries needs a sandbox with network isolation, a narrower tool, or a split into two agents that never share context.