Tool System & Permissions
Learn how Claude Code turns model requests into tool actions, and how permission modes and rules gate those actions.
What You’ll Learn
Tools let Claude Code act on your environment instead of only producing text. This session explains:
- How Claude selects and calls built-in tools
- Where permission checks happen
- What each permission mode actually changes
- How
allow,ask, anddenyrules refine the baseline
From Intent to Action
A tool has a name, a description, and an input schema. Claude chooses a tool and supplies structured input; Claude Code validates the call and applies permission policy before executing it.
User request
↓
Claude proposes a tool call
↓
Claude Code checks mode + permission rules
├─ allow → execute
├─ ask → wait for approval
└─ deny → block and return the result to Claude
Built-in tool names such as Read, Edit, Bash, WebFetch, and TaskCreate are also the exact names used in permission rules, subagent tool lists, and hook matchers. Large tool catalogs can be deferred and loaded through ToolSearch, so the full schema for every tool is not necessarily present in context at once.
Permission Baseline
In Manual mode, whose configuration value is default, reads inside the working directory normally run without a prompt. File edits and non-read-only shell commands normally ask first. Other modes change that baseline:
| Mode | What runs without routine approval | Intended use |
|---|---|---|
default (manual alias) | Reads | Learning and sensitive work |
acceptEdits | Reads, file edits, common filesystem commands | Local iteration you are reviewing |
plan | Reads, plus classifier-approved commands when auto mode is available | Analyze and design before editing |
auto | Actions approved by background safety checks | Trusted long-running work |
dontAsk | Reads and pre-approved tools; anything that would prompt is denied | Non-interactive, allowlisted automation |
bypassPermissions | Almost everything | Isolated containers or VMs only |
auto and bypassPermissions are not synonyms. Auto mode evaluates actions with a separate safety classifier and still honors explicit rules. Bypass mode skips ordinary permission checks and has far weaker protection.
Know which mode you start in. Since v2.1.284, interactive terminal and VS Code sessions start in auto when no permission mode is configured; since v2.1.302, claude -p and Agent SDK runs start in Manual (default). If auto mode isn’t available to a session, it starts in Manual instead. --permission-mode and permissions.defaultMode override the built-in default, but auto or bypassPermissions set in a project’s .claude/settings.json or .claude/settings.local.json doesn’t take effect.
Start a session in a specific mode with --permission-mode:
claude --permission-mode default # Manual mode; "manual" also works
claude --permission-mode plan
claude --permission-mode auto
claude --permission-mode dontAsk
claude --permission-mode bypassPermissions
The legacy convenience flag below is equivalent to bypassPermissions, not Auto mode:
claude --dangerously-skip-permissions
Fine-Grained Rules
Modes set the baseline. Rules then decide which calls should be allowed, always asked about, or denied. Rules use Tool or Tool(specifier) syntax:
{
"permissions": {
"allow": [
"Bash(npm test *)",
"Read(/docs/**)"
],
"ask": [
"Bash(git push *)"
],
"deny": [
"Read(./.env)",
"WebFetch(domain:paste.example)"
]
}
}
Rules are evaluated in this order: deny → ask → allow. A broad deny cannot be overridden by a narrower allow. Use /permissions to inspect the effective rules and the settings file each rule came from.
Practical Mental Model
Treat the system as two separate questions:
- Can Claude see and request this tool? Tool availability, deferred loading, and MCP configuration answer this. Availability varies more than you might expect: current models get the Task tools only when you opt in (Session 3), and on macOS, Linux, and WSL Claude searches with
findandgrepthroughBashinstead of theGlobandGreptools. - May this exact call execute now? The active mode, permission rules, protected paths, hooks, and organization policy answer this.
Hiding a tool and denying a specific use are different controls. A bare deny such as "Bash" removes the tool from Claude’s context; a scoped deny such as "Bash(rm *)" leaves Bash available but blocks matching calls.
Try It
Create .claude/settings.local.json with a narrow rule set, start in Manual mode with claude --permission-mode default (current versions otherwise start interactive sessions in auto mode), then ask Claude to run tests and push a branch. Confirm that the test rule runs without a prompt while the push rule still asks:
{
"permissions": {
"allow": ["Bash(npm test *)"],
"ask": ["Bash(git push *)"]
}
}
Prefer narrow command patterns over blanket Bash access. Permission patterns are a policy boundary, not a substitute for reviewing dangerous commands.
Next Session
In Session 3, we’ll use the structured TaskCreate, TaskGet, TaskList, and TaskUpdate tools to turn an approved plan into visible, trackable work, including the opt-in that current models need before those tools appear.
Official sources
Last verified: 2026-10-21.