Inside Claude Code: Tools and Permissions

Tools are the boundary between model intent and real side effects.

Previous: agentic loop. Next: memory and sub-agents.

Claude Code tool system and permission flow

The 30 Second Version

Claude emits tool-use blocks. The runtime decides whether and how to execute them.
Every tool has a schema, permission check, read-only check, concurrency check, execution function, and UI renderer.
Read/search tools can run in parallel. Mutating tools are serialized.
Permission rules sit in the execution path, not just the terminal UI.
Bash is the biggest safety surface because one command can be harmless, destructive, or long-running.

The Tool Contract

All tools fit the same shape from src/Tool.ts:

Tool = {
  name,
  inputSchema,
  description(input, context),
  isConcurrencySafe(input),
  isReadOnly(input),
  checkPermissions(input, context),
  call(input, context)
}

This abstraction covers file reads, edits, bash, MCP, web fetch, sub-agents, skills, notebook edits, and config changes. The agent loop can therefore treat built-in and external capabilities through one orchestration path.

Risk Categories

Filesystem: Read, Edit, Write, Glob, Grep, NotebookEdit.
Execution: Bash, PowerShell, REPL tools.
Agent tools: Agent, message passing, task management.
External tools: WebFetch, WebSearch, MCP tools.
Control/meta tools: skills, plan mode, config, sleep, user questions.

Risk depends on input, not only tool name. Bash("ls") is effectively read-only. Bash("rm -rf ...") is not. That is why isReadOnly() is a method.

Concurrency

Claude Code batches tool calls using isConcurrencySafe().

Safe reads/searches can fan out in parallel.
Writes and risky execution run serially.
The default max concurrency is 10, configurable with CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY.

This gives the model fast codebase exploration without letting mutating operations race each other.

Permissions

Permissions are checked before execution. The system supports modes like default, plan, auto, and bypass; allow/deny/ask rules; tool-specific checks; and hooks that can intercept or modify calls.

In the terminal, a risky operation can become a prompt. In SDK or background contexts, the same decision may return a structured denial. In coordinator/swarm mode, permission decisions can be synchronized between leader and workers.

The key design choice: permissioning is part of the tool pipeline, so it applies regardless of whether the request came from the REPL, SDK, IDE, MCP, or a sub-agent.

Bash And MCP

Bash needs the most guard rails: command classification, permission prompts, sandboxing, timeouts, read-only detection, and long-running process handling.

MCP tools are normalized into the same tool infrastructure. That means external tools still participate in schema validation, permissioning, rendering, and the agent loop instead of becoming a separate execution path.

Key Takeaway

The model proposes actions. The runtime validates, permission-checks, schedules, executes, renders, and records them.

Next: how memory, sub-agents, and swarms extend the loop.

Ask about Sushen