Tools
43 toolsClaude Code has 43 built-in tools, each implementing a unified Tool<Input, Output, Progress> interface. Tools are built via the buildTool() factory and validated with Zod schemas at runtime.
- All 43 tools implement the same Tool<Input, Output, Progress> interface and are built via buildTool() — same pattern whether it's Bash, FileEdit, or MCP.
- Read-only tools (FileRead, Grep, Glob) run up to 10 in parallel. Write tools serialize. This split is why reading feels fast but edits are sequential.
- The Agent tool spawns a full isolated sub-agent with zero-cost cache sharing — the child inherits the exact same system prompt bytes, auto-hitting the parent's prompt cache.
Tool Interface (Tool.ts)
Start here if you want the mental model that unifies Bash, Edit, MCP, Agent, and the rest.
interface Tool<Input, Output, Progress> {
name: string
aliases?: string[] // backwards compatibility
searchHint?: string // for ToolSearch keyword matching
inputSchema: ZodSchema // validated at runtime
strict?: boolean // strict API mode
// Core execution
call(args, context, canUseTool, parentMessage, onProgress): Promise<ToolResult>
// Metadata
description(input, options): Promise<string>
prompt(): string // system prompt instructions
userFacingName(): string // display name for UI
// Security
validateInput(): ValidationResult
checkPermissions(): PermissionResult
isReadOnly(): boolean
isDestructive(): boolean
isConcurrencySafe(): boolean
// Rendering
renderToolUseMessage(): ReactNode
renderToolResultMessage(): ReactNode
getToolUseSummary(): string // compact status display
getActivityDescription(): string // "Reading src/foo.ts"
// Limits
maxResultSizeChars?: number // triggers disk persistence if exceeded
}Built-in Tools (43 total)
This section helps you orient which tools are for reading, writing, searching, spawning, or protocol bridging.
Shell commands with AST security analysis, sandbox, ML classifier
String find/replace with fuzzy matching and unified diff
Full content atomic file replacement
Read files with PDF, notebook, image handling
Ripgrep-based content search with permission filtering
Fast file pattern matching, mod-time sorted
Isolated sub-agents with zero-cost cache sharing
User-defined prompt templates from .md files
Wraps external tools via Model Context Protocol
Web search integration
Fetch web page content
Jupyter notebook cell editing
Git worktree creation and cleanup
Inter-agent messaging
Create, get, update, stop tracked subtasks
Deferred tool loading for large tool sets
Language Server Protocol queries
Windows PowerShell execution
Async wait/delay
Exit worktree/plan with safety checks
BashTool Deep Dive
Read this if you want to understand why shell execution in Claude Code is so heavily guarded.
The BashTool is the largest and most complex tool (~300KB across 5 files). It has multi-layered security to prevent dangerous command execution.
Detects dangerous patterns: redirections, pipes, subshells
AI evaluates command safety with confidence scoring, can auto-approve safe patterns
Exact, prefix (*), and wildcard (*test*) patterns
Detects dangerous redirections to system files, blocks shell config modifications
Blocks write commands in non-privileged sessions, prevents privilege escalation
// Execution flow:
Input → validateInput()
→ checkPermissions() [bashToolHasPermission]
→ shouldUseSandbox()?
→ exec() via SandboxManager
→ Output parsing + image detection
→ Result persistence if >100K chars
// Key files:
bashPermissions.ts — 98KB — Permission rules + classifier
bashSecurity.ts — 102KB — Dangerous pattern detection
readOnlyValidation.ts — 68KB — Privilege escalation prevention
sedValidation.ts — 21KB — Sed command validation
shouldUseSandbox.ts — Sandbox decision logicFileEditTool
This section explains why edits are more than a simple string replace.
// Input schema:
{
file_path: string // absolute path
old_string: string // text to find
new_string: string // replacement text
replace_all?: boolean // global replace
}
// Key features:
1. findActualString() — fuzzy matching
→ Quote-style preservation
→ Whitespace/indentation variations
→ Multiple match handling via exact-position lookup
2. Validation
→ File must exist or be newly created
→ File must have been read first (tracked via readFileState)
→ File timestamp must not have changed since read
→ Blocks team memory files with secrets
3. Side effects
→ Notifies LSP servers (triggers diagnostics)
→ Notifies VSCode SDK MCP
→ Updates file modification tracking
→ Discovers conditional skills by path pattern
→ Fires fileHistoryTrackEdit for versioningTool Orchestration Strategy
Use this section to understand how many tool calls can happen in one turn without corrupting shared state.
Read-only (parallel, up to 10)
Write (serial)
Tools declare isConcurrencySafe() to enable parallel execution. The orchestrator partitions tool calls into batches.
// toolOrchestration.ts — runTools() generator
1. Partition by concurrency safety:
→ Group consecutive read-only tools (Grep, Glob, Read)
→ Isolate write tools (Edit, Write, Bash)
2. Read-only batch: parallel execution
→ Up to 10 concurrent tool calls
→ No state interference between reads
3. Write batch: serial execution
→ One tool at a time
→ Context modifiers applied between calls
→ File state cache updated after each
4. Result collection:
→ Each tool returns ToolResult<Output>
→ data, newMessages, contextModifier, mcpMeta
→ Wrapped in tool_result block with tool_use_id pairing