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.
| Option | Tool definition in the request | Effect on calls |
|---|---|---|
| allowed_tools=["Read", "Grep"] | Unchanged; unlisted tools still exist | Read and Grep auto-approved; other calls fall through to the permission mode and canUseTool |
| disallowed_tools=["Bash"] | Bash removed | No Bash calls possible |
| disallowed_tools=["Bash(rm *)"] | Bash kept | Matching calls denied in every mode; /bin/rm and other Bash calls fall through |
| disallowed_tools=["*"] or ["mcp__*"] | Glob matches every tool, or every MCP tool | Matching 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.
allowed_tools only approves calls. It never removes a tool, so unlisted tools are still in the request. A bare name in disallowed_tools removes the definition. A scoped deny or allow entry keeps the tool and acts only on calls that match the pattern as written.
“Other tools not listed here still exist, and calls to them that need approval fall through to the permission mode and canUseTool.”Source: code.claude.com
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:
- Hooks, which can allow, deny, or modify the request.
- Deny rules.
- Ask rules.
- The permission mode.
- Allow rules.
- The
canUseToolcallback, 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.
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?
Under dontAsk, any call that would otherwise prompt is denied, so the scoped allow list is the whole grant and nobody has to list dangerous commands. A deny list on a bare Bash grant misses other spellings of the same command. acceptEdits auto-approves rm and mv. Under bypassPermissions the call is approved before the callback is consulted, so the callback never runs.
“Any call that would otherwise prompt is denied without calling canUseTool”Source: code.claude.com
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?
Correct answer: A — Move to the permission mode that denies unlisted tool calls rather than asking, and leave the pre-approved list at the three read tools.
- A. Correct. In the mode that denies instead of prompting, the three pre-approved read tools run and any other call is refused outright. That gives a hard read-only boundary, and CI never waits on a prompt.
- B. Incorrect. The mode that approves every call decides before a permission callback is consulted, so the callback never gets to reject the shell or write tools. Blocking them would take a deny rule or a pre-tool-use hook, so the agent could still edit files and run commands.
- C. Incorrect. The pre-approved list only grants tools up front and does not limit a mode that approves every call. Emptying it changes nothing, because the mode itself still approves the shell and write tools.
- D. Incorrect. This mode auto-approves file edits and filesystem commands in the working directory, so the agent could still modify the repository. That breaks the security team's read-only requirement.
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?
Correct answer: A — Allow file reading plus a shell rule limited to the unit-test command, and run in the mode that denies tool calls missing from the allow list instead of asking for approval, so the job never hangs.
- A. Correct: a shell rule scoped to the test command, paired with a mode that denies unlisted tool calls rather than prompting, makes a closed allowlist. It runs unattended, grants only reading and testing, and needs no one to anticipate dangerous commands.
- B. Incorrect: full shell access plus deny rules is the denylist design the security lead rejected. It depends on foreseeing risky commands, and variants such as a different deletion path or another download tool would not match the listed rules and would still run.
- C. Incorrect: the edit-approving mode also pre-approves filesystem commands such as removing, moving or copying files in the working directory. That grants write capability a read-and-test job does not need, so the setup is broader than required.
- D. Incorrect: a mode that skips permission checks lets tool calls proceed without consulting the allow list, so the shell rule no longer restricts anything. Other tools and shell commands beyond the test command would run, defeating the narrow scope.
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.
---
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.
---
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?
Turning on memory adds Read, Write and Edit to the subagent, whatever its tools line says. The parent's mode only overrides the subagent's mode under bypassPermissions, acceptEdits or auto, not default. Inheriting every tool comes from leaving out the tools field, not from leaving out disallowedTools.
“Read, Write, and Edit tools are automatically enabled so the subagent can manage its memory files.”Source: code.claude.com
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.
{
"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?
Deferring through tool search keeps rarely used definitions out of Claude's context until search finds them. Every definition must still be sent in the tools array so the search can run. Trimming or caching still loads all 74 tools on every turn, which is above the range where selection accuracy drops. A single execute tool removes the per-tool names that permission rules rely on.
“Tool selection accuracy: Tool selection accuracy degrades with more than 30-50 tools loaded at once.”Source: code.claude.com
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?
Correct answer: A — Set defer_loading on the rarely used tools and add the tool search tool, so Claude fetches a schema only when a conversation needs that tool.
- A. Correct: tools marked with
defer_loadingstay out of the prompt until the tool search tool finds them, so most requests carry only a few definitions while every tool remains available. - B. Incorrect: a single
executetool leaves Claude without the per-endpoint names, parameters and validation it needs to call the ticketing and MCP tools correctly, so the capability is effectively lost. - C. Incorrect: prompt caching only makes re-reading cheaper. The schemas still sit in the context window and count toward input size on every request, and the MCP tools no longer exist as callable tool definitions.
- D. Incorrect: trimming descriptions saves some tokens, but all 74 definitions are still sent each time. The lost parameter detail also makes Claude less accurate at choosing tools and filling their arguments.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 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.https://code.claude.com/docs/en/agent-sdk/subagentsOfficial docs
“subagents can be limited to specific tools, reducing the risk of unintended actions”
↩︎ Scoping subagent tools and MCP servers - 3.https://code.claude.com/docs/en/sub-agentsOfficial docs
“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.
“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.
“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 - 6.https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligenceOfficial docs
“With tool search, the run cost stayed flat at every catalog size.”
↩︎ Replacing a large tool catalog with on-demand loading