AI Agent Permission Boundary Checklist

This checklist structures permissions; it does not grant them. It is a review aid, not a security certification — completing it does not mean your agent setup is safe. Never paste secrets, private keys, or wallet material into a third-party AI tool. Agents draft, summarize, compare, and suggest; a named human — a person, not a role — decides what gets approved, merged, deployed, or signed. Treat any capability you have not reviewed as Unknown, which means not-allowed.

What this checklist does

It turns "we let the agents do stuff" into an explicit, reviewable boundary: every agent on your stack, every capability it can touch, the permission state for each, and the named human who has to stop it before it crosses into production or funds.

When to use it

• You have turned on a coding agent or copilot (Claude Code, Cursor, Copilot, Codex) against a private repo and have not written down what it may do.
• You are about to add an MCP server that gives agents repo, issue, or PR write access.
• You are considering an AI wallet or transaction agent anywhere near a multisig, timelock, or treasury.
• An agent already opened a PR, edited a config, or touched a deploy script and nobody had decided in advance whether it was allowed to.
• Before a release, so the boundary is reviewed and boring instead of discovered during an incident.
• On a recurring cadence — agents, MCP tools, and their scopes change faster than your policy does.

How to use it

Cadence: review at every agent or MCP-scope change, before each release, and at least quarterly. New agent, new tool, new scope — re-run the matrix.

Resource kit

Grab the blank checklist, the agent-by-capability permission matrix, the engineering-handbook policy template, the drop-in AGENTS.md starter, the human-approval rubric, and the filled DroidVault example. Copy them into your repo or hand them to your security reviewer.

Agent inventory

List every agent that can read your repo, write to it, run commands, or touch your infrastructure. Name the agent, what it does, where it runs, and its highest reachable capability. An agent you forgot to list is an agent with no boundary.

For each agent record: Agent: ____ · Purpose: ____ · Where it runs (local / cloud / CI): ____ · Highest capability it can reach: ____ · Risk level (0–4): ____ · Owner (named human): ____.

The eight agents below are the canonical inventory used in the filled example. Yours will differ — the shape does not.

Permission boundary matrix

Score each agent at its highest reachable capability, not its average one. A "docs helper" that can also run shell is a shell-running agent. Every cell gets one of five states — never leave a reachable capability as Unknown in production.

Permission states (use exactly):

• Allowed — agent may do this autonomously, within policy.
• Ask each time — agent may attempt it, but a human approves each invocation.
• Human-only — only a named person does this; the agent may draft, never execute.
• Prohibited — the agent must not attempt this at all.
• Unknown — not yet reviewed. Treat as not-allowed until a human sets a state.

Risk / approval levels (0–4, named, never color-only):

Set a state for every capability, per agent:

The diagonal rule: as a capability gets closer to production or funds, the allowed state moves from Allowed toward Human-only and Prohibited — never the other way.

Risk and approval rubric

When unsure of an agent's level, round up. The level is set by the worst thing the agent can reach, not the best thing it usually does.

Floor rule. Any agent that can reach a Level 4 capability — even occasionally, even through a tool — is a Level 4 agent, and that capability is Human-only or Prohibited. There is no autonomous Level 4.

Secrets and data boundary

The fastest way an agent causes harm is by reading something it should never see, then putting it somewhere it should never go. Deny by path, not by hope.

• No agent may read .env, *.key, *.pem, keystores, mnemonics, or wallet files.
• Deny-list these paths in agent config (ignore files / tool denylists), not just in the prompt.
• .env.example is safe to read; the real .env path must be explicitly denied.
• Tokens, API keys, RPC URLs with embedded keys, and CI secrets are out of agent scope.
• Audit reports and internal docs are shareable only with tools your data policy allows.
• Never paste secrets, keys, or private contract code into a third-party model.
• Verify the denial works — ask the agent to read a denied path and confirm it cannot.

A prompt that says "don't read secrets" is not a control. A denylist the tooling enforces is.

Tool, shell, network, and MCP boundary

Reading and writing files is one risk surface; running things is another. Shell, network, and MCP turn a text generator into an actor.

• Shell: local command execution is Ask each time, not Allowed, for any Level 2+ agent.
• Network: outbound calls are gated; no silent exfiltration paths, no arbitrary fetch.
• MCP scope: restrict each MCP server to selected repos and the narrowest action set.
• MCP GitHub: read issues and draft PR comments only — no autonomous merge, no broad write.
• Package execution: no npm install / arbitrary script execution without human approval.
• CI triggers: an agent may propose a CI run; a human approves anything that can deploy.
• Tool inventory: every MCP tool an agent can call is listed and reviewed — Unknown tools are off.

MCP is the capability that most often gets over-scoped. A server granted broad repo write is a Level 3 actor regardless of how you describe it. Scope it down to comment-only on the repos that need it.

Web3 production boundary

This is the line that protects funds. Past this line, no agent acts autonomously — it may draft, never execute.

• Deploy: agents may draft a deployment checklist; they may not deploy. (Human-only.)
• Merge to protected branches: named human approval required; no agent self-merge.
• Roles / access control: admin, guardian, owner, pauser, multisig threshold — agent may not change. (Prohibited / Human-only.)
• Timelock: delay changes are Human-only; an agent may not shorten or bypass.
• Oracles / risk params: feeds, heartbeats, staleness/deviation bounds, caps, fees — agent may not alter. (Prohibited / Human-only.)
• Governance: agent may draft proposal text; it may not submit or execute. (Draft only.)
• Signing / transactions: an agent may prepare a checklist; only a named signer signs. (Human-only.)
• Treasury / funds: no agent path can move value. Verify there is none.

For DroidVault — an ERC-4626 vault behind a 3-of-5 multisig and a 48-hour timelock — every item above maps to a real contract surface. The agent's job ends at "here is the drafted change and the checklist." A named human signer does the rest.

What agents must not decide

The boundary is the whole point. Agents accelerate the work; they do not own the call. State this once, prominently, and put it in your AGENTS.md.

Agents may: draft, summarize, compare, suggest, list changes, propose risk levels, write checklists, and flag unknowns.

Agents must not — these require a named human, never the model:

• Approve, merge, or deploy anything.
• Sign or send a transaction.
• Change roles, the timelock, oracles, or risk parameters.
• Execute governance.
• Read secrets, keys, or wallet material.
• Delete logs or evidence.
• Decide whether something is "safe," "audited," or "ready."

Where any of these would be required, the agent writes "Human decision required" and stops.

Evidence required before signoff

A checked box without proof is not a control. Before you call the boundary reviewed, each claim points to something a reviewer can open.

The rule, stated once: a checked box without evidence is not a control.

Filled example

A worked example on the fictional protocol — DroidVault, an ERC-4626 yield vault with upgradeable contracts, oracle-based pricing, a 3-of-5 multisig admin behind a 48-hour timelock, and a RewardsDistributor. The team runs eight agents (the inventory above) and uses AI coding agents across its GitHub workflow. Findings are numbered AI-001 onward.

The two that matter most:

• AI-003 (Level 3). The MCP GitHub server arrived with broad repo write. That makes every agent behind it a workflow actor. The decision: scope it to selected repos and comment-only — read issues, draft PR comments, nothing else. No autonomous merge, no broad write.
• AI-005 and AI-007 (Level 4). .env was never on a denylist (AI-005) — fixed by denying .env, wallet, key, and token paths in tooling, not just the prompt. The proposed Wallet transaction agent (AI-007) would prepare multisig transactions; it is held at Human-only. It may produce a drafted transaction and a signing checklist; a named signer signs.

The decision: block the wallet agent from autonomous action. DroidVault adopts the Wallet transaction agent only as a drafting tool behind the 48-hour timelock and 3-of-5 multisig. It prepares; a named human reviews and signs. There is no configuration in which it signs on its own. That is the Level 4 floor rule in practice.

Grab the full worked example from the Resource kit (Filled DroidVault example) to see all seven findings, the complete permission matrix, and every decision filled in end to end.

Repo-ready usage

Put the boundary where the agents read it. Suggested locations:

• AGENTS.md (repo root) — the boundary file agents and reviewers both read.
• .github/ — branch protection + CODEOWNERS routing sensitive paths to named reviewers.
• docs/security/agent-policy.md — the engineering-handbook policy template.
• Agent config / ignore files — the enforced denylist for secrets and wallet paths.

Drop this starter into AGENTS.md and tailor the names:

# AGENTS.md — Agent permission boundary (DroidVault)
 
Agents may draft, summarize, compare, and suggest. A named human decides
anything that approves, merges, deploys, signs, or touches roles/oracles/funds.
Treat any capability not listed here as NOT ALLOWED until reviewed.
 
## Allowed
- Read public docs, issues, and private repo code (non-secret paths).
- Edit non-sensitive source and docs; open DRAFT pull requests.
- Propose tests; run the test suite (shell is ASK-EACH-TIME, not automatic).
- Draft PR comments via the MCP GitHub server (selected repos, comment-only).
 
## Ask each time (human approves each invocation)
- Local shell / command execution.
- Network / outbound calls and any MCP tool use.
- Edits to tests, CI, or configuration.
 
## Human-only (agent may draft, never execute)
- Merge to protected branches; approve PRs.
- Trigger CI that can deploy; run any deployment.
- Draft (never submit) governance proposals and deployment checklists.
 
## Prohibited
- Read .env, *.key, *.pem, keystores, mnemonics, wallet, or token files.
- Change roles, the timelock, oracles, or risk parameters.
- Sign or send transactions; move funds.
- Delete logs or evidence; declare anything "safe" or "audited."
 
Where any prohibited or human-only action would be required, write
"Human decision required" and stop. Decision owner: ____ (named human).

Commit it, link it from your PR template, and review it whenever an agent or MCP scope changes.

Related resources

• Security-Sensitive PR Review Card — review the PRs your agents open.
• Audit Drift Checklist — the release-level register agents can drift.
• The Access Snapshot — a free map of every owner, role, and signer on your live contracts, the on-chain half of this boundary work.

Version history