Claude Architect · 课时

最小权限原则

只向每个代理提供其角色所需的工具。

最小权限原则 是 CoddyKit 上的免费 Claude Architect 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Claude Architect 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Claude Architect 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

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.

常见问题解答

「最小权限原则」课时是免费的吗？

是的 — 「最小权限原则」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Claude Architect 课程的其余内容，请升级到 CoddyKit PRO。 Claude Architect 课程共包含 4 节课。

「最小权限原则」这节课中我会学到什么？

只向每个代理提供其角色所需的工具。你通过在浏览器中直接运行的动手代码来练习 Claude Architect，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Claude Architect 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Claude Architect 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「最小权限原则」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Claude Architect 课中编写并运行代码吗？

能。每节 Claude Architect 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Claude Architect