Analyzed: March 31, 2026 leak snapshot
This page covers the built-in tool framework: registration, schema injection, permission checks, and execution flow. The per-tool catalog belongs on separate reference pages.

​
What a tool is in Claude Code

In this codebase, a tool is not just a callable function. It is a typed runtime object with:
  • A stable name exposed to the model
  • A Zod input schema
  • A JSON schema projection for model context
  • Validation and permission hooks
  • Optional UI rendering and progress updates
  • Execution behavior such as concurrency and interruption rules
The central types live in src/Tool.ts. Execution happens in src/services/tools/toolExecution.ts and src/services/tools/StreamingToolExecutor.ts.

​
High-level architecture

​
Tool definition pattern

Claude Code uses a common tool contract rather than ad hoc function calls. The important shared concepts visible in src/Tool.ts are:
  • ToolInputJSONSchema: the JSON-schema-like shape handed to the model
  • ToolPermissionContext: permission mode plus allow, deny, and ask rules
  • ToolUseContext: the per-turn execution context, including app state, abort signals, tools, commands, MCP clients, and thinking config
That ToolUseContext is load-bearing. It is how tools reach session state without owning global state directly.

​
What the model actually sees

Tools are injected into the prompt as schemas, not as source code. The model gets:
  • The tool name
  • The description
  • The input schema
  • Any prompt-side guidance specific to the tool
That is why schema quality matters. A vague or bloated schema directly degrades tool selection.
The codebase treats tool descriptions as part of the model interface. MCP descriptions are even capped to avoid dumping large OpenAPI blobs into context.

​
Main tool categories

The source tree groups tools by capability. The major categories are:
  • File and code editing: read, write, edit, notebook tools
  • Shell execution: BashTool, PowerShellTool
  • Web access: fetch and search
  • Agent orchestration: subagents and task-oriented tools
  • MCP bridge tools: remote server tools, MCP auth, resource listing, resource reads
  • Meta and output tools: synthetic output, structured output, brief, skill tool
Some tools are local-only. Others are wrappers around external systems such as MCP servers.

​
Execution lifecycle

The common execution path in src/services/tools/toolExecution.ts is:
  1. Find the tool by name.
  2. Parse input with the tool’s Zod schema.
  3. Resolve permission behavior.
  4. Run pre-tool hooks and safety checks.
  5. Execute the tool and stream progress messages.
  6. Convert the result into assistant-visible tool_result messages.
  7. Feed those results back into the main query loop.
If any stage fails, the framework still tries to return a structured error block rather than crashing the turn.

​
Permissions and approvals

Permission logic is split between shared infrastructure and tool-specific behavior. Shared layer:
  • Permission mode is carried through ToolPermissionContext
  • Rules can come from session state, user settings, local settings, policy settings, CLI args, or managed config
  • The framework records why a decision happened, not just the decision itself
Tool-specific layer:
  • A tool can define extra checks after validation
  • Some tools reason about command prefixes, paths, domains, or content before approval
  • Some tools can be auto-approved in specific contexts
This split is deliberate. Global policy stays centralized, while dangerous edge cases stay close to the tool implementation.

​
Concurrency model

Claude Code can execute some tools while the model is still streaming more output. StreamingToolExecutor manages this.
  • Concurrency-safe tools may run in parallel
  • Non-concurrent tools require exclusive access
  • Results are buffered so the model still sees them in arrival order
  • A sibling error can cancel parallel tools to avoid inconsistent state
That design trades some throughput for determinism. The code is optimizing for predictable follow-up reasoning, not raw maximum parallelism.

​
Interrupt behavior

Tools are not all interruptible in the same way.
  • Some tools can be cancelled when the user interrupts the turn
  • Others are treated as blocking and must finish or fail explicitly
  • Parallel tool cancellation uses a child abort controller, so one failed tool does not automatically terminate the whole query loop
This is why tool cancellation logic lives beside execution orchestration rather than inside each tool.

​
Deferred and dynamically loaded tools

Not every tool is loaded eagerly.
  • The code distinguishes always-loaded versus deferred tools
  • MCP tools are registered dynamically as servers connect
  • Skills can surface model-invocable functionality through the skill tool path
The prompt therefore reflects the active tool set for the current turn, not a static compile-time list.

​
MCP tools are normalized into the same model

External MCP tools are adapted into Claude Code’s internal tool format rather than handled as a separate execution universe. That means MCP tools participate in:
  • Name normalization
  • Permission routing
  • Progress reporting
  • Error shaping
  • Result injection back into the loop
From the model’s perspective, an MCP tool still looks like a tool call. The difference is in the backend transport and auth path.

​
Design takeaways

The tool system is built around a few consistent constraints:
  • Tool calls must be serializable into model context
  • Execution must survive partial failures
  • Permissions must remain explainable
  • Streaming must not reorder semantic results
  • External integrations must fit the same contract as built-ins
That consistency is one reason the agent loop can stay relatively generic.