Tool System & Permissions

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, and deny rules 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 and read-only exploration	Analyze and design before editing
auto	Actions approved by background safety checks	Trusted long-running work
dontAsk	Only pre-approved and built-in read-only actions	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.

Start a session in a specific mode with --permission-mode:

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:

1. Can Claude see and request this tool? Tool availability, deferred loading, and MCP configuration answer this.
2. 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, 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.

Official sources

• Tools reference
• Configure permissions
• Choose a permission mode

Last verified: 2026-07-20.