Tool System

This page answers “what can Claude Code do” — and more importantly — “why it does it that way.” 43 tool entities form the system’s capability surface, organized with a unified governance layer, fail-safe defaults, and OS-level sandboxing.

Overview

Tool System Overview

    flowchart TD
  subgraph Model
    M[LLM requests tool_use]
  end
  subgraph Filtering
    FF[Feature Flag] --> DR[Deny Rules] --> MC[MCP Merge]
  end
  subgraph Governance
    PM[PermissionMode] --> RL[Rule Matching] --> HK[toolPermission Hook] --> SB[Sandbox]
  end
  subgraph Execution
    SE[StreamingToolExecutor]
    RO[Read-only tools · parallel]
    RW[Write tools · serial]
    SE --> RO
    SE --> RW
  end
  M --> FF
  MC --> PM
  SB --> SE
  

Core Design: Tool-First Architecture

Claude Code adopts a Tool-First architecture — the model never executes operations directly; it calls standardized tools. This is a deliberate engineering decision with major consequences:

Source evidence: src/Tool.ts (tool base class) and src/services/tools/toolOrchestration.ts (orchestration layer).

Tool Groups

File Operations (8 tools, 32 files)

Execution & Shell (4 tools, 35 files)

BashTool: Four-Layer Security Deep Dive

BashTool has the most complex security design because it directly faces command injection risks:

• Layer 1 — Command Parsing: Extracts actual program names and arguments before execution
• Layer 2 — Pattern Matching: Built-in dangerous pattern library (rm -rf, fork bombs, Zsh bypass tricks)
• Layer 3 — Semantic Analysis: Understands intent (force push = destructive, echo $API_KEY = data leak)
• Layer 4 — OS-Level Sandbox: macOS sandbox-exec / Linux bubblewrap + seccomp, filesystem and network allow-lists

Agents & Teams (5 tools, 36 files)

Sub-Agent Type System

Key isolation: each sub-agent gets its own ID, AbortController, and tool whitelist. Explore Agent sets omitClaudeMd: true to save tokens. Permission requests bubble up to the parent via permissionMode: 'bubble'.

Planning & Workflows (13 tools, 44 files)

Plan mode, task management, cron scheduling, and worktree isolation.

External Systems (10 tools, 33 files)

Web, MCP, LSP, and user interaction tools for bridging to external systems.

Infrastructure (3 modules, 4 files)

Shared utilities, testing framework, and helper functions for the tool system.

Unified Tool Contract

All tools register through a unified type defined in Tool.ts:

Key Philosophy: All safety-related defaults are false (most restrictive). If a tool developer forgets to set a property, the system runs in the most conservative mode. Better slow than sorry.

Three-Layer Tool Filtering

Tools are not all exposed to the model. Each query loop iteration filters the tool list:

1. Feature Flag: isEnabled() === false → silently removed
2. Permission Deny rules: Explicitly disabled tools removed before reaching the model
3. MCP Merge: External MCP server tools dynamically merged

The filtered list is serialized as the tools parameter in the API request.

Lessons for Agent Builders