Skip to main content
Module 1: Core Agent 2 / 6
Beginner S02 Tools Permissions Security

Tool System & Permissions

Learn how Claude Code turns model requests into tool actions, and how permission modes and rules gate those actions.

March 20, 2026 15 min read
Verified Curriculum reviewed: Oct 21, 2026

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:

ModeWhat runs without routine approvalIntended use
default (manual alias)ReadsLearning and sensitive work
acceptEditsReads, file edits, common filesystem commandsLocal iteration you are reviewing
planReads, plus classifier-approved commands when auto mode is availableAnalyze and design before editing
autoActions approved by background safety checksTrusted long-running work
dontAskReads and pre-approved tools; anything that would prompt is deniedNon-interactive, allowlisted automation
bypassPermissionsAlmost everythingIsolated 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:

  1. 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 find and grep through Bash instead of the Glob and Grep tools.
  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 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.