Least Privilege (Tool Access)
PatternsDefinition
A security principle applied to agent tool design: give each agent and subagent only the minimum tools required to complete its specific task. Reduces blast radius if an agent is compromised or makes an error. Implemented via AgentDefinition tool lists and skill allowed-tools.
Example Usage
A code review subagent gets read_file and list_directory tools only — not write_file, execute_command, or network tools.
Why It Matters for the CCA-F Exam
Exam questions test whether candidates can identify least-privilege violations in presented agent designs (e.g., a read-only subagent with a `write_file` tool in its list), distinguish the three implementation layers (skill frontmatter vs. AgentDefinition vs. MCP Roots), and explain why orchestrators should *not* accumulate all tools even when they delegate tasks to subagents.
In Depth
The Principle Applied to Agents
Least privilege in security means: grant any principal only the minimum permissions required to perform its designated function, and nothing more. Applied to agent tool design, this translates to a concrete engineering rule: every subagent's tool list should be the *intersection* of (a) all available tools and (b) the exact tools that subagent needs for its specific task — and that intersection should be computed at design time, not discovered at runtime.
This is not a performance optimization. It is a blast-radius constraint. If a subagent is compromised by a prompt injection attack, or simply makes an error, the damage it can cause is bounded by the tools it can access. A code-review subagent that can only call read_file and list_directory cannot delete production data, exfiltrate credentials via an HTTP tool, or escalate privileges — even if an attacker crafts an adversarial instruction telling it to try.
Implementation Layers
Least privilege in Claude-based agent systems operates at three distinct layers:
| Layer | Mechanism | Scope |
|---|---|---|
| Claude Code Skills | allowed-tools in skill frontmatter | Restricts what tools a skill can invoke during its run |
| AgentDefinition | tools array in the agent definition | Specifies which tools are available to a subagent at invocation time |
| MCP Roots | File system path restrictions in MCP server config | Limits which directories an MCP file tool can read/write |
These layers compose: even if a skill's allowed-tools list includes write_file, if the AgentDefinition does not grant that tool, the subagent cannot call it. MCP Roots add a third constraint that operates below the tool-selection layer.
Designing Tool Lists by Subagent Role
A reliable design practice is to define tool lists by *role archetype* before assigning them to subagents:
- Read-only analyst:
read_file,list_directory,search— no write, no network, no execution. - Report generator:
read_file,write_file(to a designated output directory only) — no deletion, no execution. - Code executor:
bash(sandboxed, time-limited) — no file write outside sandbox, no network. - Orchestrator:
task_tool(to spawn subagents) — no direct file or network tools; delegates to role-typed subagents.
The orchestrator pattern illustrates a key least-privilege corollary: *orchestrators should delegate capabilities, not accumulate them.* An orchestrator that holds all tools and passes subsets to subagents is not applying least privilege — it is a single point of capability accumulation. A correctly designed orchestrator has only the tools needed to route work (primarily the Task tool) and spawns role-typed subagents for capability-bearing work.
The Capability Creep Anti-Pattern
The most common violation of least privilege in agent systems is capability creep during development: a subagent is given a broad tool list during prototyping for convenience, and that list is never pruned before production deployment. Treat the tool list audit as a required pre-deployment step, the same way you would audit database permissions before a production schema migration.
For how tool lists are configured in skills, see allowed-tools. For MCP-level path restrictions, see MCP Roots. The concept guide Tool Distribution & Least Privilege covers the full design-time workflow for assigning tool lists to subagent roles.
How It Compares
| Implementation Layer | Where Configured | Enforcement Point | Granularity |
|---|---|---|---|
Skill allowed-tools | Skill SKILL.md frontmatter | Claude Code skill runner | Per-skill, tool-name level |
AgentDefinition tools | Agent SDK AgentDefinition object | Subagent invocation | Per-subagent, tool-name level |
| MCP Roots | MCP server config / .mcp.json | MCP server (file/resource access) | Per-server, file-path level |
| System prompt instruction | System prompt text | Model behavior (soft constraint) | Semantic, not enforced at API level |
Frequently Asked Questions
Is a system prompt instruction like 'do not use write_file' sufficient for least privilege?
No. System prompt instructions are soft constraints — they guide model behavior but are not enforced at the API or tool-invocation layer. A prompt injection attack or a sufficiently confident model reasoning error could override them. True least privilege requires that the tool is simply not present in the agent's tool list, so it cannot be called regardless of what the model decides. System prompt instructions are a useful secondary layer, not the primary control.
How does least privilege interact with the orchestrator pattern?
The orchestrator pattern and least privilege together produce a clean capability architecture: the orchestrator holds only routing tools (primarily the Task tool to spawn subagents), and each subagent holds only the tools for its specific task type. This means no single component in the system holds all capabilities. Even if the orchestrator is compromised, it cannot directly read files or execute commands — it can only spawn new subagents, which are themselves constrained. See [AgentDefinition](/glossary/agent-definition) for how to configure per-subagent tool lists.
What is the difference between least privilege for tools vs. least privilege for MCP resources?
Tool-level least privilege controls which *actions* an agent can perform (which tools it can call). MCP Roots add a second dimension: within a tool like `read_file`, which *paths* is the agent allowed to access. A subagent might correctly have `read_file` in its tool list but should only be able to read from `/project/reports/`, not from `/project/secrets/`. [MCP Roots](/glossary/mcp-roots) configure that path-level restriction at the MCP server layer, independent of the tool list.