Claude Code Tool Internals: BashTool, FileEditTool, AgentTool, Compact

Earlier posts covered the tool protocol and execution service. This post covers what tools actually do — the implementation logic behind the agent's most-used capabilities.

Several tools are substantially more complex than their names suggest.

File structure

src/
├── services/
│   ├── compact/
│   │   ├── autoCompact.ts
│   │   ├── microCompact.ts
├── tools/
│   ├── AgentTool/
│   │   ├── AgentTool.tsx
│   ├── BashTool/
│   │   ├── BashTool.tsx
│   │   ├── bashPermissions.ts
│   │   ├── readOnlyValidation.ts
│   │   ├── pathValidation.ts
│   │   ├── destructiveCommandWarning.ts
│   │   └── shouldUseSandbox.ts
│   ├── FileEditTool/
│   │   └── FileEditTool.ts
│   ├── FileReadTool/
│   │   └── FileReadTool.ts

BashTool's five-layer defense model

BashTool is not a thin wrapper around exec. It has five defense layers:

The speculative pre-check pattern

One of the most interesting patterns in BashTool is speculative permission pre-checking.

The problem: the user approves a tool call in the permission dialog, but the bash permission check inside BashTool immediately denies it. This produces a confusing UX where the user said "yes" and nothing happened.

The solution: clearSpeculativeChecks() in bashPermissions.ts runs the bash permission check ahead of the approval dialog. If the bash layer would deny the command, the approval dialog is not shown — instead, the agent is told immediately that the command is not permitted.

This is permission validation at two levels: the main permission engine asks "is the user allowing this tool category?" and the bash layer asks "is this specific command allowed within that category?" The speculative check ensures both questions are answered before the user sees the dialog.

Auto-backgrounding long-running commands

BashTool has a 15-second budget for foreground execution in assistant mode (ASSISTANT_BLOCKING_BUDGET_MS).

Commands that run longer than 15 seconds auto-background. The agent receives a task handle and can check the result later.

Additionally, common build tools — npm, yarn, python, pytest, cargo — are detected by name and backgrounded proactively without waiting for the 15-second budget to expire.

This is a product decision: build commands are always long-running, so there is no value in blocking the foreground turn for 15 seconds before deciding to background them.

The run_in_background: true tool property in the model's response can also explicitly request backgrounding for a specific command.

FileReadTool's device blocking

The device path check in FileReadTool is worth examining because it reveals a class of failure that naive implementations miss.

Without the check, the agent could call read_file('/dev/stdin') and wait indefinitely for input that never arrives. Or call read_file('/dev/zero') and read an infinite stream of null bytes until memory is exhausted.

The block list includes:

• /dev/zero, /dev/null, /dev/random, /dev/urandom
• /dev/stdin, /dev/stdout, /dev/stderr
• /proc/self/fd/*

These are not security concerns — they are correctness guards against the agent accidentally hanging itself or exhausting memory.

FileEditTool's correctness guards

FileEditTool has three guards that a minimal implementation would omit:

Staleness detection: The tool tracks the file's mtime at read time. If the file has been modified between read and edit, the edit is rejected. This prevents the agent from applying a diff to a version of the file that no longer matches what it read. Without this, a file modified externally during a long agent turn could receive a corrupted edit.

UNC path blocking: On Windows, paths like \\server\share\file trigger automatic NTLM authentication negotiation with the remote server. FileEditTool blocks UNC paths explicitly. An agent that edits files over UNC paths would silently leak the user's Windows credentials to any SMB server it contacts.

Team memory secret guard: Edits to team memory files (.claude/CLAUDE.md and similar) are scanned for secret patterns before committing. An agent that writes a secret into team memory would persist it into the repository for all team members to share.

sed -i TOCTOU mitigation: The sed -i write path in BashTool has an interesting security property. Rather than executing sed -i and then checking what it did, the tool pre-computes the final file content at permission-preview time — before the user sees the approval dialog. The content shown in the preview is byte-exact what will be written if the user approves. This eliminates the TOCTOU window where the file could change between preview and execution. The same computed content is used for both preview and the actual write.

Each guard protects against a different failure class: correctness (staleness), security (UNC), accidental secret exposure (team memory), and preview/execution divergence (TOCTOU).

GrepTool's pagination design

GrepTool does not return unbounded results. It enforces a default head limit of 250 lines and reports the applied limit and offset back to the model as structured metadata.

This is a deliberate pagination design: the model can request head_limit=0 for unlimited results, or pass an offset to continue from a previous page. The tool result includes appliedLimit and appliedOffset so the model knows what slice it received.

The reason for the default limit is context budget. A grep across a large codebase can return tens of thousands of lines. Injecting all of them into context would consume the budget before the agent could do anything with them. The 250-line default is a token budget decision, not a correctness one.

microCompact: tool result pruning over time

There are two compaction systems in Claude Code, not one.

autoCompact (covered above) summarizes the entire conversation when it approaches the context limit.

microCompact is a separate system that prunes old tool result bodies over time, while keeping the metadata. It runs before API requests rather than reactively.

The prunable tools are: FILE_READ, BASH, GREP, GLOB, WEB_SEARCH, WEB_FETCH, FILE_EDIT, FILE_WRITE. For each, the content body is removed after a time window, but the tool call record and result status remain in the conversation so the model knows the operation happened.

The distinction is important: autoCompact produces a summary that replaces conversation history. microCompact is surgical — it removes large payloads from individual tool results while leaving the conversation structure intact. A large file read from turn 3 does not need to occupy context in turn 50.

AgentTool's nesting depth limit

The subagent nesting depth limit (MAX_AGENT_NESTING_DEPTH = 4) prevents the most obvious runaway failure mode: an agent that spawns an agent, which spawns an agent, recursively.

The depth counter is passed through the task context and checked at AgentTool invocation time. Attempting to spawn a subagent at depth 4 returns an error immediately rather than spawning.

The limit of 4 is a product judgment: deep enough to support coordinator → worker → sub-worker patterns, but not so deep that a looping agent can cause significant resource consumption before the limit fires.

AutoCompact's circuit breaker

The circuit breaker in autoCompact.ts addresses a failure mode that is easy to overlook:

What happens if the compacted summary is itself too long?

Without a circuit breaker: compact the conversation → the result is still too large → compact again → loop indefinitely.

The circuit breaker tracks how many compaction attempts have been made for the current conversation. After one failed compaction (where the output still exceeds the context budget), the breaker opens and prevents further attempts. The agent instead receives a hard context limit error, which it can handle explicitly.

// BashTool: layered validation before execution
async function executeBashCommand(
command: string,
context: ToolExecutionContext
): Promise<ToolResult> {
// Layer 1: read-only validation (semantic, not string matching)
const readOnlyResult = validateReadOnly(command)
if (readOnlyResult.blocked) {
  return toolError(`Command blocked: ${readOnlyResult.reason}`)
}

// Layer 2: path validation (must be within working directory)
const pathResult = validatePaths(command, context.workingDir)
if (pathResult.blocked) {
  return toolError(`Path outside allowed directory: ${pathResult.path}`)
}

// Layer 3: destructive command confirmation (fires dialog)
if (isDestructiveCommand(command)) {
  const confirmed = await showDestructiveWarning(command)
  if (!confirmed) return toolError('User declined destructive command')
}

// Layer 4: sandbox routing (when enabled)
const exec = shouldUseSandbox(command)
  ? sandboxExecutor
  : directExecutor

// Auto-background for long-running commands
const timeout = getTimeoutMs(command)  // npm/yarn/pytest → immediate background
if (timeout === BACKGROUND_IMMEDIATELY || context.runInBackground) {
  return spawnBackgroundTask(command, exec)
}

return exec.run(command, { timeout, context })
}

// Speculative pre-check: validate bash permissions BEFORE showing approval dialog
function speculativePreCheck(command: string, context: SessionContext): boolean {
// If bash layer would deny, don't show the approval dialog at all
const bashResult = clearSpeculativeChecks(command, context)
return bashResult.allowed  // false → skip dialog, return denied immediately
}

// AgentTool: nesting depth guard
const MAX_AGENT_NESTING_DEPTH = 4

async function agentTool(
task: string,
context: ToolExecutionContext
): Promise<ToolResult> {
const depth = context.agentNestingDepth ?? 0

if (depth >= MAX_AGENT_NESTING_DEPTH) {
  return toolError(
    `Maximum agent nesting depth (${MAX_AGENT_NESTING_DEPTH}) exceeded. ` +
    `Cannot spawn a subagent from depth ${depth}.`
  )
}

// Run the subagent — same query loop as parent, with incremented depth
const result = await runAgent(task, {
  ...context,
  agentNestingDepth: depth + 1
})

// Materialize conversation as structured tool result
return { type: 'agent_result', output: result.finalOutput, conversation: result.messages }
}