Guardrails in five layers

By the end you can score a repository on five layers of control and name the one fix that closes its biggest gap.

TL;DR

• A prompt is a request, not a control. Destructive actions need layers the agent cannot talk its way past: permissions, sandbox, secrets, hooks and telemetry.
• Least privilege is the spine and redundancy is the control. The sandbox is the hard boundary against prompt injection - and even it can have bugs.
• Keep production credentials out of the session, and send the agent's pull requests through the same gates as everyone else's.

What are the five layers?

A prompt is a request. A control is something the agent cannot talk its way past.

PocketOS (the Prologue) had a natural-language instruction, which is weaker than layer one. Three lessons get quoted from it, and all three are wrong:

• "The agent ignored its instructions." It did, as agents sometimes do; a prompt is never a hard control for a destructive action.
• "AI agents are unsafe." So is any tool pointed at production without controls.
• "Do not use AI for database operations." That throws away real productivity when layers can bound the risk.

Underneath all five sits least privilege: at every level - the agent, its process, its credentials, its network - grant the minimum that lets the work happen.

No single layer would have saved PocketOS with certainty; any one enforceable layer could have broken the chain. A second 2026 incident, at DataTalks.Club, was the mirror image: Claude Code ran terraform destroy against a stale state file. Same cure: confirmation on destructive operations, only the credentials the task needs, and state the team has verified.

Layer 1: Permissions

Permissions answer one question: is this agent allowed to do this, right now?

I recommend a classifier that makes the allow, ask or deny call on each action, with a small set of explicit rules on top, such as denying writes to .env files. Ten to fifteen overrides per repository is a sound ceiling; past that, your AGENTS.md is too thin, not your rule list too short.

Every team starts here, and a successful prompt injection can defeat it. Necessary, not sufficient.

Layer 2: Sandbox

The kernel does not listen to the agent's reasoning, so injection cannot talk its way past it.

For most teams the default is to read the whole repository, write only inside the worktree, reach only allowlisted hosts and block everything else.

Calibrate by friction: if the agent hits the limits often in normal work, widen them. It costs an afternoon to configure, and some agents ship it opt-in, so check yours (Chapter 1).

Layer 3: Secrets

The safest credential is the one the session never held.

Do not commit .env files, and remember that agents can pick them up from the working directory unasked. Keep secrets in a vault and pull them at runtime through an explicit fetch step the agent can be configured to skip. Put sensitive paths on the sandbox deny-read list: the agent literally cannot read them, whatever the system prompt says.

Layer 4: Hooks

Hooks are the precision instrument: a programmable gate for the categories your team cares about.

A hook is code that runs before the agent executes a given kind of action (pre-tool-use) and, against your rules, allows it, asks for confirmation or blocks it. Off-the-shelf plugins ship a baseline: secret leaks in diffs, SQL injection patterns, hardcoded credentials.

Your own rules go on top: any change to currency-conversion logic needs explicit approval; any commit touching the customer table needs a security reviewer. Reach for a hook when permissions are too coarse and the sandbox too blunt.

Layer 5: Telemetry

The first four layers prevent; telemetry detects, so a failed prevention costs minutes instead of days.

Log every tool call - each Bash command, file write and external API request, with arguments and results - to a central store the security team owns. Then "which sessions touched the payments service in the last thirty days" is a query, not a grep through eighty engineers' local histories. Watch for:

• an edit outside the assigned task
• calls to hosts off the allowlist
• repeated permission denials: a bug in the rules or an injection attempt
• production credentials in context

Injection arrives through the work itself

Treat everything the agent reads as untrusted text, and do not count on the agent to spot the attack.

Anywhere the agent reads natural language is a surface: a Jira ticket whose acceptance criteria say "ignore all previous instructions"; an outside contributor's PR comment with an instruction hidden in a review note; an error message from a flaky third-party test; a harmless-looking repository whose planted error nudges the agent to run a "fix" that pulls in its real payload. I have watched an agent follow an instruction buried in a pasted log file because the operator did not think of a log file as untrusted input.

Constrain what the agent can do regardless of what it has read. The sandbox catches the dangerous action even when the agent is convinced it is legitimate; the hook catches the dangerous category even when "just this once" sounds fine. A poisoned AGENTS.md can change the agent on every session start, one more reason it is reviewed like code (Chapter 6).

Beyond the five

Two ordinary practices catch what the layers do not.

• Environment separation. The agent does not hold production credentials by default. Production actions go through a separate gate - a human approval, a CI pipeline, a deploy script - that the agent triggers but does not execute end to end.
• Protected branches, CODEOWNERS and CI policy. The agent opens pull requests like any contributor; make sure its PRs flow through these rules, not around them.

In the loop

The rigor lives in the layers below execute; execute just runs the work.

In Chapter 4's execute phase every tool call passes the permission gate, every Bash command the hooks, every file write the sandbox. A blocked action goes back to the orchestrator to decide.

When it breaks

• Every layer is code, and code has bugs. In mid-2026 a red team disclosed two critical zero-click escapes of one vendor's kernel-backed sandbox (patched), and a permission check once skipped its deny rules on very long command chains. That is the argument for five layers.
• A log with no alert is not a layer. PocketOS's platform recorded the delete, but no alert fired when an agent session used a production token; the first signal was an unreachable database.

Do this Monday

Score each layer DEFAULT, CONFIGURED, ENFORCED or MONITORED. DEFAULT or CONFIGURED across the board is normal; ENFORCED or MONITORED everywhere is production-grade.

• [ ] Pick one repository your team owns, ideally one where an agent already commits code.
• [ ] Permissions: what runs without a prompt? Are rm, terraform destroy, drop table and force push to main gated?
• [ ] Sandbox: kernel-enforced, or only path validation inside the agent's own code?
• [ ] Secrets: are .env files committed? Can the agent reach a production token?
• [ ] Hooks: does any pre-tool-call hook audit, log or gate dangerous operations?
• [ ] Telemetry: would a destructive command show on a dashboard within minutes?
• [ ] For every layer below ENFORCED, write one fix and one owner. That sheet is next quarter's plan; rerun it after every incident.

Go deeper

• Template: the scorecard above; for plugins that ship hooks, Appendix B.10, plugin vetting.
• Deep dive: Appendix D, Chapter 2 - the named vulnerability classes, sandbox escapes, per-agent sandbox defaults and what the platforms changed after the incidents.
• Sources: Appendix C.