Chapter 4: Tool System
The tool system is the carrier of Claude Code's capabilities. 60+ built-in tools + MCP extensions = unlimited possibilities.
All of Claude Code's capabilities—file read/write, Shell commands, code search, sub-Agent spawning, MCP external service calls—are exposed to the model through a unified tool system. The model does not directly operate on the filesystem or network; instead, it accomplishes all side-effecting operations by calling tools. The tool system is the sole bridge connecting "model intelligence" to "the real world."
The core architecture of this system is divided into three layers:
- Design layer: The
Toolgeneric interface (src/Tool.ts)—defines the contract every tool must implement: execution logic, input Schema, safety semantic markers (read-only/destructive/concurrency-safe), permission checks, and UI rendering - Assembly layer:
getAllBaseTools()→getTools()→assembleToolPool()(src/tools.ts)—from compile-time pruning to runtime filtering, ultimately merging built-in tools and MCP tools into a unified tool pool - Execution layer:
StreamingToolExecutor(src/services/tools/)—executes tools concurrently while the model streams output, handling permission checks, Hook callbacks, and result formatting
This design yields two key advantages: adding a new tool only requires implementing the Tool interface, with no changes needed to the execution pipeline or permission system; safety semantics (isReadOnly, isDestructive) are encoded as interface methods rather than external configuration, ensuring that safety properties always stay in sync with the tool implementation.
Chapter roadmap: Sections 4.1–4.2 cover interface definition and the assembly pipeline; 4.3 provides a full inventory of built-in tools; 4.4–4.5 explain the execution lifecycle and concurrency control; 4.6–4.7 dive deep into the two most complex tools (BashTool and AgentTool); 4.8–4.10 cover large result handling, MCP integration, and deferred loading; 4.11–4.12 summarize design insights and UI rendering patterns.