Concept 06
Tool Permission Design
Least privilege applied to AI agents. Not a security checklist. A quality mechanism that keeps agents focused on their role.
"An agent with too many tools will use them. Permissions are guardrails, not prison walls."
A planner with write access will start implementing. A reviewer with execute access will start running things. Permissions enforce role discipline.
The Principle of Least Privilege for AI Agents
In traditional security, processes get only the access they need. Same thing with AI agents. An agent with too many tools will use them, not maliciously, but eagerly. A planner with write access starts implementing. A reviewer with execute access may start running scripts, introducing unintended side effects.
Think of a hospital. The surgeon (Build) has access to everything in the operating room. The radiologist (Review) reads scans but does not operate. The receptionist (Plan) reads patient records but does not prescribe treatment. Everyone has what they need. Nothing more.
Two enforcement mechanisms
Permission boundaries can be enforced at two levels:
Runtime enforcement
The agent runtime restricts which tools are available per phase. A planner agent literally cannot call the file-write tool. This is the strongest guarantee; a prompt injection cannot bypass it.
Runtime enforcement requires an agent runtime that supports per-phase tool configuration. Not all do. When available, it is the preferred mechanism for high-autonomy (L3-L4) workflows.
Prompt-level enforcement
The prompt template instructs the agent to restrict its own behavior. A plan template says "research the codebase; do not modify any files." The agent follows the instruction.
Prompt-level enforcement works because modern agent models follow instructions reliably. It is weaker than runtime enforcement (a sufficiently adversarial input could theoretically bypass it), but it is universally available across all agent runtimes and often sufficient for L1-L2 workflows.
In practice, use both
Runtime enforcement sets the hard boundary. Prompt-level enforcement provides intent. It tells the agent WHY it shouldn't write files during planning, not just that it can't. Both matter:
- - Runtime without prompts: the agent hits permission errors and wastes turns trying forbidden operations
- - Prompts without runtime: the agent follows instructions but there's no safety net if it doesn't
- - Both together: the agent understands its role AND can't exceed it
Why It Matters
Quality
A Review agent restricted to Read+Search produces findings. Give it Write access and it starts "fixing" issues, producing unreviewed code that bypasses the Build/Test loop.
Predictability
When you know an agent can only read, you know it cannot change your codebase. The blast radius is zero.
Debugging
When something goes wrong, permissions narrow the investigation. If Plan is read-only, the Plan phase cannot have introduced a file modification.
Trust
Each autonomy level depends on agents staying within their bounds. Permissions make that verifiable, not just hoped-for.
The permission matrix
Each workflow phase gets exactly the tool categories it needs. Green means allowed, red means denied. Hover over any row to see the rationale.
| Phase | Read | Search | Execute | Write |
|---|---|---|---|---|
| Plan | Yes | Yes | No | No |
| Build | Yes | Yes | Yes | Yes |
| Test | Yes | Yes | Yes | Yes |
| Review | Yes | Yes | No | No |
| Document | Yes | Yes | No | Yes |
| Deploy | Yes | Yes | Yes | No |
| Monitor | Yes | Yes | Yes | No |
Implementation note: This matrix can be enforced via runtime tool configuration, prompt-level instructions, or both. For L1-L2 workflows, prompt-level enforcement alone is practical. For L3-L4 workflows, runtime enforcement is strongly recommended as the primary mechanism.
Tool categories explained
Read
file reading, directory listing, environment variables, configuration. The most basic capability. Zero risk.
Search
grep, glob, find, AST search, semantic code search. Discovery and navigation. Zero risk.
Execute
shell commands, test runners, linters, git commands, CI triggers. Actions with side effects. Medium risk.
Write
file creation, editing, deletion. Permanent changes to the filesystem. Highest risk.
Common mistakes
Giving Review write access
The reviewer starts "helpfully" fixing issues instead of reporting them. Unreviewed code bypasses the Build/Test cycle. Review exists for analysis, not correction.
Giving Plan execute access
The planner starts building during the planning phase. Plans become coupled to implementation details instead of staying strategic. Keep research and execution separate.
Giving Deploy write access
The deploy agent modifies source files after review. Changes go out unreviewed. The code should be finalized before reaching the Deploy phase.
Designing Permissions for Custom Phases
If you add a custom phase (e.g., "Security Audit"), ask three questions:
- 1. Does this phase need to modify files? If no, deny Write.
- 2. Does this phase need to run commands? If no, deny Execute.
- 3. What is the worst thing this phase could do with each permission? If that risk is unacceptable, deny it.
Default: start with Read+Search only. Add permissions only when the phase demonstrably needs them.
# workflow.yaml -- permission configuration
phases:
plan:
tools:
read: true
search: true
execute: false
write: false
# Explicit deny with explanation
deny_reasons:
execute: "Plan phase must not run code"
write: "Plan phase must not modify files"
build:
tools:
read: true
search: true
execute: true
write: true
# Scoped execute (advanced)
execute_allowlist:
- "npm test"
- "npm run lint"
- "git diff"