CertSafari
    Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards· Lessons

    Domain 3 · Lesson 13/39

    Least-privilege tool configuration for agents and subagents

    Least-Privilege Tool Configuration

    16 min read
    2.63% of exam
    6 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Tell apart the tools an agent can see from the calls that run without approval, and say which setting controls each
    • Find the gap in an agent configuration whose permission mode approves calls before any allow rule or callback is checked
    • Pick an unattended configuration that runs only the listed calls and refuses everything else
    • Scope a subagent's tools and MCP servers, and spot settings that quietly give it more tools
    • Decide when a large tool catalog should be deferred behind tool search instead of cut down or merged

    Key concept

    Exposure versus approval — An agent's privilege has two layers. Exposure is which tool definitions the model can see and call. Approval is which of those calls run without anyone checking them. A least-privilege review has to narrow both, because a setting that pre-approves some tools does nothing to stop the other tools from existing.

    1.Exposure versus approval: what an allow list does not do

    Least privilege for an agent means it can do what its job needs and nothing more. Minimal footprint adds a second goal: carry only the tool definitions the job needs. Most over-privileged agents fail both goals for the same reason. The person who configured them assumed that listing a few tools in allowed_tools restricted the agent to those tools. It doesn't. allowed_tools is an approval setting: calls to the listed tools run without a prompt, and every other tool is still in the request.

    Removing a tool is a separate setting. disallowed_tools=["Bash"] deletes the Bash definition from the request, so the model never sees a shell tool. A scoped deny such as disallowed_tools=["Bash(rm *)"] works differently. Bash stays available, and only calls that match the pattern as written are refused. That refusal holds in every permission mode, bypassPermissions included. A path variant like /bin/rm doesn't match the pattern, so it falls through to the permission mode like any other Bash call.

    Agent SDK query options compared by what they change
    OptionTool definition in the requestEffect on calls
    allowed_tools=["Read", "Grep"]Unchanged; unlisted tools still existRead and Grep auto-approved; other calls fall through to the permission mode and canUseTool
    disallowed_tools=["Bash"]Bash removedNo Bash calls possible
    disallowed_tools=["Bash(rm *)"]Bash keptMatching calls denied in every mode; /bin/rm and other Bash calls fall through
    disallowed_tools=["*"] or ["mcp__*"]Glob matches every tool, or every MCP toolMatching calls denied

    An allow entry can be narrow too. A bare name such as Read or mcp__github__get_issue approves every call to that tool. A scoped rule such as Bash(npm test *) approves only the calls that match it. Any other Bash call that needs approval goes on to the permission mode. When the agent needs one shell command, grant that command, not the shell.

    Checkpoint 1 of 7· Match them up

    A reviewer is tightening an agent's Agent SDK query options. Match each setting to what it actually does to the agent's tools.

    Tap a term, then the definition that fits it.

    Sources1

    2.Permission evaluation order and unattended modes

    Whether a configuration is safe depends on the order in which checks run. Each tool call passes through these steps, and the first step that settles the call wins:

    1. Hooks, which can allow, deny, or modify the request.
    2. Deny rules.
    3. Ask rules.
    4. The permission mode.
    5. Allow rules.
    6. The canUseTool callback, used only when no earlier step settled the call.

    bypassPermissions approves calls at the mode step, so allow rules and the callback never get a vote. Shrinking allowed_tools to an empty list changes nothing under this mode, because the mode approves the call before the allow rules run. Only an earlier step can stop a call here: a deny rule, or a PreToolUse hook, which is where checks belong if they must cover calls the mode would otherwise approve.

    For a job with no human watching, dontAsk is the least-privilege mode. Any call that would otherwise prompt is denied, and canUseTool is never called. Calls covered by allowed_tools still run, so the allow list becomes the whole grant. Nothing has to list dangerous commands, because anything not granted is refused. One detail: calls that need no approval even in default mode also run under dontAsk. When a tool must not exist at all, remove it with disallowed_tools as well.

    Read-only and unattended: three tools granted, every other call refused instead of promptingtypescript
    const options = {
      allowedTools: ["Read", "Glob", "Grep"],
      permissionMode: "dontAsk"
    };

    The other modes don't fit a read-only or test-only agent. acceptEdits auto-approves file edits and filesystem commands such as mkdir, rm and mv inside the working directories, which is exactly the capability such an agent must not have. A deny list on top of a bare Bash grant has the opposite flaw. You must think of every dangerous command in advance, and a different spelling of the same command still gets through. For a CI agent that reads code and runs npm test, the narrow grant is ["Read", "Grep", "Bash(npm test *)"] under dontAsk. Where these options sit in a full SDK setup is covered in Agent SDK configuration.

    Checkpoint 2 of 7· Check yourself

    Your CI pipeline runs an agent with no human watching. Its job is to read the code and run npm test. Which configuration gives it the least privilege?

    Checkpoint 3 of 7· Exam question

    A security team will sign off on a code-review agent only if it can read the repository and nothing else: no file changes and no shell commands. The agent pre-approves three read tools but runs in a permission mode that approves every other tool call too, chosen so CI never stalls on prompts. A review shows it could still edit files and run commands. Which change should the architect make?

    Checkpoint 4 of 7· Exam question

    A CI pipeline runs an Agent SDK agent that only reads source files and runs the project's unit-test command. The security lead wants the narrowest setup that runs with nobody present to approve prompts, and rejects any design that depends on predicting which commands are dangerous. Which configuration should the architect propose?

    Sources1

    3.Scoping subagent tools and MCP servers

    A subagent is easiest to restrict when it has a single purpose. Limiting its tools reduces the risk of unintended actions. A doc reviewer that only has Read and Grep can analyse files but can't change them. The trap is the default: a subagent definition with no tools field inherits every tool available to subagents. An empty tools field is the most permissive setting, not a neutral one.

    The disallowedTools field also behaves differently in subagent frontmatter than in SDK query options. In the frontmatter, an entry with a specifier such as Bash(git push *) removes the whole Bash tool. In query options, Bash(rm *) denies only the matching calls. Read a specifier according to where it is written.

    MCP access is scoped by tool-name patterns. tools: mcp__github__* grants every tool from one server. disallowedTools: mcp__github withholds that server's tools, and mcp__* withholds every MCP tool. Prefix matching cuts both ways. In tools, mcp__reports__v2 without the trailing __* matches none of that server's tools. In disallowedTools, mcp__reports also removes every reports__v2 tool, because those names begin with mcp__reports__ too.

    Keeping everything the parent offers except one MCP serveryaml
    ---
    name: local-only
    description: Inherits every tool except those from the github MCP server
    disallowedTools: mcp__github
    ---

    A server that only one subagent needs belongs inline in that subagent's mcpServers list. An inline definition is scoped to that subagent, so the main conversation and other subagents never carry it. Delegation can be narrowed the same way. tools: Agent(worker, researcher) lets a coordinator spawn only those two agent types, and denying the Agent tool in permissions.deny stops all delegation.

    When a subagent needs a tool for one narrow purpose, scope the tool down instead of removing it. The db-reader example keeps Bash and adds a PreToolUse hook, scoped to that subagent, that runs a script blocking SQL write statements. The hook runs only while that subagent is active.

    Bash kept but limited to read-only queries by a hook scoped to the subagentyaml
    ---
    name: db-reader
    description: Execute read-only database queries
    tools: Bash
    hooks:
      PreToolUse:
        - matcher: "Bash"
          hooks:
            - type: command
              command: "./scripts/validate-readonly-query.sh"
    ---

    Two settings widen a subagent's footprint without changing its tools line. First, the parent's mode wins. When the main conversation runs in bypassPermissions, acceptEdits or auto, the subagent runs in that same mode and its own permissionMode is ignored. Second, setting memory automatically enables Read, Write and Edit so the subagent can manage its memory files. A reviewer declared as tools: Read, Grep, Glob gains write tools as soon as memory is turned on.

    Checkpoint 5 of 7· Check yourself

    A reviewer subagent is declared with tools: Read, Grep, Glob, memory: project and model: sonnet. The main conversation runs in default mode, yet the reviewer edited a file during the session. What explains the edit?

    Sources23

    4.Replacing a large tool catalog with on-demand loading

    Minimal footprint also covers tools the agent is allowed to use but rarely calls. Every loaded definition costs context: 50 tools can use 10–20K tokens, and tool selection accuracy degrades once more than 30 to 50 tools are loaded at once. Take a support agent with 14 ticketing tools and 60 MCP tools that most conversations barely touch. It pays that cost on every request and is past the point where selection gets worse.

    The fix is to defer, not delete. On the Messages API, add the tool search tool and set defer_loading: true on the rarely used tools. Deferred tools load only when Claude finds them through search. You still send every full definition in the tools array on every request, because the API needs them to run the search. What changes is what enters Claude's context. Keep the 3–5 most frequently used tools non-deferred so Claude can call them without searching first. In one measurement, run cost with tool search stayed flat as the catalog grew. On the Agent SDK, tool search is already on by default for newer models and is controlled by ENABLE_TOOL_SEARCH. How deferral compares with loading everything up front is covered in progressive discovery.

    A tool definition marked for on-demand loadingjson
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" },
          "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
        },
        "required": ["location"]
      },
      "defer_loading": true
    }

    The tempting shortcuts each give something up. Merging all 74 tools into one generic execute tool shrinks the schema but costs control. Permission rules name individual tools, as in mcp__github__get_issue, and with one generic tool every endpoint shares one name, so you can no longer allow, deny or scope a single endpoint. Trimming descriptions, or caching the schemas in the system prompt, keeps all 74 tools loaded on every turn. That stays above the range where selection accuracy drops, whatever it saves on price.

    Checkpoint 6 of 7· Check yourself

    Which change cuts the context cost of a support agent's 74-tool catalog and also brings it back under the point where tool selection gets worse, without losing per-tool permission control?

    Checkpoint 7 of 7· Exam question

    A support agent on the Messages API is given 14 per-endpoint tool definitions for a ticketing system plus 60 tools from three MCP servers. Traces show the tool definitions consume a large share of every request's input tokens, while most conversations use fewer than five tools. Which change best reduces the footprint without removing any capability?

    Sources4561

    Sources

    (6)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “The Bash tool definition is removed from the request.”
      ↩︎ Exposure versus approval: what an allow list does not do
      “Other Bash calls, including /bin/rm, fall through to the permission mode.”
      ↩︎ Exposure versus approval: what an allow list does not do
      “Scoped rule: an entry like Bash(npm test *) auto-approves calls that match it”
      ↩︎ Exposure versus approval: what an allow list does not do
      “In default and dontAsk mode, the call goes on to the allow rules.”
      ↩︎ Permission evaluation order and unattended modes
      “Tool calls are approved before canUseTool is consulted, so your callback runs for only a few calls”
      ↩︎ Permission evaluation order and unattended modes
      “Any call that would otherwise prompt is denied without calling canUseTool”
      ↩︎ Permission evaluation order and unattended modes
      “File edits and filesystem operations (mkdir, rm, mv, etc.) inside your working directories are automatically approved”
      ↩︎ Permission evaluation order and unattended modes
      “Bare name: an entry like Read or mcp__github__get_issue auto-approves every call to that tool”
      ↩︎ Replacing a large tool catalog with on-demand loading
      “Other tools not listed here still exist, and calls to them that need approval fall through to the permission mode and canUseTool.”
      ↩︎ Key concept
      “Other tools not listed here still exist, and calls to them that need approval fall through to the permission mode and canUseTool.”
      ↩︎ Exam trap 1
      “To check the approved calls too, put your callback’s checks in a PreToolUse hook”
      ↩︎ Exam trap 2
      “Other Bash calls, including /bin/rm, fall through to the permission mode.”
      ↩︎ Exam trap 3
      “Other tools not listed here still exist, and calls to them that need approval fall through to the permission mode and canUseTool.”
      ↩︎ Checkpoint
    2. 2.
      “subagents can be limited to specific tools, reducing the risk of unintended actions”
      ↩︎ Scoping subagent tools and MCP servers
    3. 3.
      “Inherits every tool available to subagents if omitted.”
      ↩︎ Scoping subagent tools and MCP servers
      “An entry with a specifier, such as Bash(git push *), still removes the whole tool”
      ↩︎ Scoping subagent tools and MCP servers
      “Without the trailing __*, mcp__reports__v2 matches none of that server’s tools.”
      ↩︎ Scoping subagent tools and MCP servers
      “Inline definition: scoped to this subagent only”
      ↩︎ Scoping subagent tools and MCP servers
      “To prevent Claude from delegating to any subagent, deny the Agent tool itself with permissions.deny.”
      ↩︎ Scoping subagent tools and MCP servers
      “define hooks that run only while that subagent is active”
      ↩︎ Scoping subagent tools and MCP servers
      “the subagent runs in that same mode and Claude Code ignores the permissionMode you set”
      ↩︎ Scoping subagent tools and MCP servers
      “Read, Write, and Edit tools are automatically enabled so the subagent can manage its memory files.”
      ↩︎ Scoping subagent tools and MCP servers
      “Read, Write, and Edit tools are automatically enabled so the subagent can manage its memory files.”
      ↩︎ Exam trap 4
    4. 4.
      “Tool definitions can consume large portions of the context window (50 tools can use 10-20K tokens), leaving less room for actual work.”
      ↩︎ Replacing a large tool catalog with on-demand loading
      “Tool selection accuracy degrades with more than 30-50 tools loaded at once.”
      ↩︎ Replacing a large tool catalog with on-demand loading
      “Tool selection accuracy: Tool selection accuracy degrades with more than 30-50 tools loaded at once.”
      ↩︎ Checkpoint
    5. 5.
      “Tools with defer_loading: true load only when Claude discovers them through search.”
      ↩︎ Replacing a large tool catalog with on-demand loading
      “Keep your 3–5 most frequently used tools non-deferred so Claude can call them without searching first.”
      ↩︎ Replacing a large tool catalog with on-demand loading
      “You still send every tool’s full definition in the tools array on every request, including the deferred ones.”
      ↩︎ Replacing a large tool catalog with on-demand loading
      “You still send every tool’s full definition in the tools array on every request, including the deferred ones.”
      ↩︎ Exam trap 5

    Ready to test yourself?

    Practise Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.