Claude Architect · Lesson

Principle of Least Privilege

Give each agent only the tools its role needs.

Principle of Least Privilege is a free Claude Architect lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Claude Architect learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Least Privilege?

The Principle of Least Privilege says: give each agent only the tools its role actually needs — nothing more.

In a multi-agent system, the coordinator decomposes work and delegates to specialist subagents. Each subagent should receive a tightly scoped toolset. A research subagent does not need a refund tool. A read-only reviewer does not need Write or Bash.

This is not just security hygiene. Scoped tools also make Claude select the right tool more reliably, which directly improves accuracy on the exam scenarios.

More Tools = Worse Selection

Tool selection is driven by the model reading tool descriptions. The more tools you pile onto one agent, the harder that choice becomes.

4-5 tools per agent is the sweet spot for reliable selection.
At 18+ tools, selection reliability degrades noticeably.
Overlapping or ambiguous descriptions cause misrouting to the wrong tool.

Least privilege and good accuracy point the same direction: keep each agent's toolset small and role-specific.

allowed_tools per Agent

In the Agent SDK, you scope a subagent with an AgentDefinition. Its fields are name, description, system_prompt, and allowed_tools.

The allowed_tools list is exactly where least privilege lives — it is the allowlist of tools that subagent may call. Give a researcher search and read tools only; never hand it write or refund actions.

research_agent = AgentDefinition(
    name="researcher",
    description="Gathers and summarizes external sources with citations.",
    system_prompt="Find sources, extract facts, keep claim->source mappings.",
    allowed_tools=["WebSearch", "WebFetch", "Read"],  # read-only, no Write/Bash
)

The Coordinator Needs Task

Least privilege is about giving the right minimum — not crippling the agent.

The coordinator in a hub-and-spoke system must be able to delegate, so its allowedTools has to include "Task". Without it, the coordinator cannot spawn subagents at all.

So: the coordinator gets Task plus only what it needs to aggregate and route. Each spoke gets just its job-specific tools.

coordinator = AgentDefinition(
    name="coordinator",
    description="Decomposes the request, delegates, aggregates, routes.",
    system_prompt="Break the task into subtasks and dispatch to specialists.",
    allowed_tools=["Task"],  # delegation is its whole job
)

Read-Only vs Write Agents

A common split is read-only investigators versus write-capable executors.

Claude Code's built-in tools make this concrete:

Read-only: Glob (find files by pattern), Grep (search contents), Read (load a file).
Mutating: Write (create), Edit (precise change), Bash (shell).

A code-review agent that only inspects code should get the read-only set. Withholding Write, Edit, and Bash means it physically cannot change the repo, even if a prompt is misread.

reviewer = AgentDefinition(
    name="reviewer",
    description="Reviews a diff for bugs. Never edits files.",
    system_prompt="Inspect code and report issues only.",
    allowed_tools=["Glob", "Grep", "Read"],  # no Write/Edit/Bash
)

Scope by Role, Not Convenience

It is tempting to give every agent the full toolbox "just in case." Resist it.

The fact sheet is blunt: scope tools to the role. Each agent's tools should map to its responsibilities, not to whatever might be handy.

Two reasons:

Safety — an agent cannot misuse a tool it was never given.
Reliability — fewer, role-relevant tools mean clearer, non-overlapping descriptions and better selection.

Privilege Boundaries Still Need Hooks

Least privilege limits which tools exist for an agent. But for a critical business rule inside an allowed tool, an allowlist is not enough.

Example: the support agent legitimately has process_refund, but refunds over $500 must be blocked. A prompt enforces a rule only ~90% of the time. A hook enforces it 100% deterministically.

Use an outgoing-call hook to block policy-violating actions when failure has financial, legal, or safety consequences.

# Pseudocode: deterministic guardrail on an allowed tool
def on_tool_call(tool_name, args):
    if tool_name == "process_refund" and args["amount"] > 500:
        return Block(reason="Refund over $500 requires human approval")
    return Allow()

Preconditions: Earn the Privilege

Least privilege also applies in time: an agent should not exercise a sensitive tool until preconditions are met.

In the customer support scenario, process_refund must not run until get_customer has returned a verified customer ID. A programmatic precondition gives a deterministic guarantee that prompt guidance alone cannot.

So privilege is conditional: the tool is in the allowlist, but a hook or precondition gates when it may fire.

def on_tool_call(tool_name, args, state):
    if tool_name == "process_refund" and not state.verified_customer_id:
        return Block(reason="Verify identity via get_customer first")
    return Allow()

Skills and Commands: allowed-tools

Least privilege is not only an SDK concept — Claude Code Skills support it too.

A skill's frontmatter can set allowed-tools to restrict what that skill may invoke, plus context: fork to isolate verbose output and argument-hint for inputs.

A skill that only formats text should not be allowed to run Bash. Restricting it in frontmatter keeps the privilege boundary close to the capability.

---
name: summarize-diff
description: Summarize a git diff in plain language.
allowed-tools: [Read, Grep]
context: fork
argument-hint: <path-to-diff>
---
Read the diff and produce a concise summary. Do not modify files.

Secrets Are a Privilege Too

Tools that reach external systems often need credentials — and credentials are privilege.

For MCP servers, inject secrets via environment variables like ${GITHUB_TOKEN}, and never commit tokens. Use .mcp.json at project scope (shared in VCS) for the server config, but keep the actual secret out of the file.

This keeps the token scoped to the environment that genuinely needs it, instead of leaking it into source control where every agent and teammate inherits it.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Putting It Together

A well-scoped hub-and-spoke system layers least privilege cleanly:

Coordinator: Task + routing tools, nothing destructive.
Researcher: WebSearch, WebFetch, Read — read-only.
Reviewer: Glob, Grep, Read — no writes.
Executor: Edit, Write, Bash — and its risky calls are gated by hooks/preconditions.

Every agent stays near the 4-5 tool sweet spot, descriptions stay crisp, and the dangerous capabilities are both scoped and deterministically guarded.

Quick Check

Apply least privilege to a multi-agent design decision.

Recap

Key takeaways for least-privilege agent design:

Give each agent only the tools its role needs — scope by role, not convenience.
Aim for 4-5 tools per agent; selection degrades at 18+.
Set allowed_tools per AgentDefinition; the coordinator must include Task to delegate.
Split read-only (Glob/Grep/Read) from write-capable (Write/Edit/Bash) agents.
For critical rules inside an allowed tool, enforce with hooks and preconditions (100% deterministic), not prompts (~90%).
Restrict skills via allowed-tools frontmatter, and inject secrets through env vars — never commit tokens.

Frequently asked questions

Is the “Principle of Least Privilege” lesson free?

Yes — the full text of “Principle of Least Privilege” is free to read here on the web, and the Claude Architect course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Claude Architect course, upgrade to CoddyKit PRO.

What will I learn in “Principle of Least Privilege”?

Give each agent only the tools its role needs. You practise Claude Architect with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Claude Architect?

No prior experience is required. Claude Architect on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Principle of Least Privilege” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Claude Architect lesson?

Yes. Every Claude Architect lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Claude Architect