Why Claude Code’s Tool System Relies on a Generic Triple for Safety and Flexibility

01 – Counter‑Intuitive Numbers: 46 Tool Directories, One Generic Interface

Claude Code contains 46 sub‑directories under src/tools/. With dynamically loaded MCP tools, LSP tools and feature‑flagged optional tools, the runtime pool exceeds 60 tools.

All tools are governed by a single type definition in src/Tool.ts, which declares a generic triple:

export type Tool<Input extends AnyObject = AnyObject, Output = unknown, P extends ToolProgressData = ToolProgressData> = { ... }

The three type parameters define the complete contract for any tool.

02 – Why a Unified Tool Interface Is Needed

Without a common interface each tool would define its own calling convention, scatter permission checks, lack a consistent UI rendering contract, and make testing nearly impossible. Early versions of Claude Code suffered from these problems when the tool count grew beyond ten.

The generic interface Tool<Input, Output, Progress> addresses all of these issues.

03 – Source Location: src/Tool.ts Overview

The file is about 800 lines and exports the core skeleton of the tool system:

// 1. Progress‑related types
export type ToolProgressData
export type ToolProgress<P extends ToolProgressData>
export type ToolCallProgress<P extends ToolProgressData = ToolProgressData>

// 2. Execution result
export type ToolResult<T>

// 3. Main tool interface
export type Tool<Input, Output, P>

// 4. Factory‑related types
export type ToolDef<Input, Output, P>
export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D>

// 5. Context types
export type ToolUseContext
export type ToolPermissionContext

04 – Core Implementation Walk‑Through

4.1 What the Three Generic Parameters Do

Input : a Zod schema. At runtime the framework extracts the concrete TypeScript type via z.infer<Input> and validates the arguments.

Output : the data type returned by the tool, wrapped in ToolResult<Output>, which can also carry additional messages or context modifiers.

P (Progress) : the type of progress data emitted by the tool (e.g., BashTool emits command‑line fragments, AgentTool emits sub‑agent status, WebSearchTool emits search stages). The generic keeps progress types type‑safe per tool.

All three parameters have default values, so a tool can be declared simply as Tool and the framework will use the most permissive types, which is useful for dynamically injected MCP tools.

4.2 The call Method – Five Parameters and Their Intent

call(
  args: z.infer<Input>,               // validated input
  context: ToolUseContext,           // DI container with 34 fields
  canUseTool: CanUseToolFn,            // runtime permission check
  parentMessage: AssistantMessage,     // message that triggered the call
  onProgress?: ToolCallProgress<P>    // optional streaming progress callback
): Promise<ToolResult<Output>>

args

: type‑safe input after Zod validation. context: provides access to tool lists, file caches, app state, etc. canUseTool: lets the tool query permissions before performing sub‑operations. parentMessage: enables tracing which message caused the tool invocation (used by AgentTool). onProgress: receives streamed progress events for tools that produce incremental output.

4.3 ToolResult<T> – More Than a Return Value

export type ToolResult<T> = {
  data: T
  newMessages?: (UserMessage | AssistantMessage | AttachmentMessage | SystemMessage)[]
  contextModifier?: (context: ToolUseContext) => ToolUseContext // only for non‑concurrency‑safe tools
  mcpMeta?: {
    _meta?: Record<string, unknown>
    structuredContent?: Record<string, unknown>
  }
}

newMessages : allows a tool to add messages (e.g., a large file read can be attached as a message).

contextModifier : lets a tool return a pure function that updates the shared context; it is ignored for concurrency‑safe tools.

mcpMeta : passes through MCP protocol metadata.

4.4 Progress System – Polymorphic ToolProgressData

Progress types are defined in src/types/tools.ts and re‑exported by Tool.ts:

export type ToolProgress<P extends ToolProgressData> = {
  toolUseID: string
  data: P // concrete progress payload
}
export type ToolCallProgress<P extends ToolProgressData = ToolProgressData> = (progress: ToolProgress<P>) => void

Concrete examples:

type BashProgress = { type: 'output'; output: string }
type AgentToolProgress = { type: 'agent_turn' | 'tool_use' /* … */ }
type WebSearchProgress = { type: 'searching' | 'fetching' /* … */ }

The generic P lets each tool define its own progress shape while the executor only needs to call onProgress(event) without knowing the specifics.

4.5 Concurrency Safety and Read‑Only Flags – Input‑Driven Dynamic Properties

The following helper functions receive the validated input and decide safety characteristics at runtime:

isConcurrencySafe(input: z.infer<Input>): boolean
isReadOnly(input: z.infer<Input>): boolean
isDestructive?(input: z.infer<Input>): boolean

Example: when ls -la is executed, isReadOnly returns true, allowing the command to bypass write‑permission checks; when rm -rf is executed, isDestructive returns true, triggering a destructive‑operation warning.

This input‑driven approach enables fine‑grained permission and concurrency control instead of a blunt, tool‑wide static label.

05 – buildTool Factory: Fail‑Closed Default Values

The Tool<Input, Output, P> interface contains over 30 methods, but manually implementing all of them would be error‑prone. The buildTool factory fills in safe defaults:

// Default values (core logic)
const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: (_input?: unknown) => false, // default to exclusive execution
  isReadOnly: (_input?: unknown) => false,       // assume write capability
  isDestructive: (_input?: unknown) => false,   // avoid alert fatigue
  checkPermissions: (input, _ctx?) => Promise.resolve({ behavior: 'allow', updatedInput: input }),
  toAutoClassifierInput: (_input?: unknown) => '',
  userFacingName: (_input?: unknown) => ''
}

export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return {
    ...TOOL_DEFAULTS,
    userFacingName: () => def.name, // default display name
    ...def // tool‑specific overrides
  } as BuiltTool<D>
}

The rationale for the defaults:

isConcurrencySafe = false : new tools run exclusively to avoid race conditions; developers must explicitly opt‑in.

isReadOnly = false : new tools are assumed to perform writes, so write‑permission checks are enforced unless overridden.

isDestructive = false : defaulting to non‑destructive prevents constant warning dialogs, a pragmatic compromise to the strict fail‑closed principle.

checkPermissions = allow : permission logic is delegated to a central system ( permissions.ts).

toAutoClassifierInput = '' : forces safety‑critical tools to provide their own classifier input.

This design is called **Fail‑Closed**: defaults favor safety, and developers must actively relax them.

06 – Three Design Insights

Insight 1: Generic Parameters as Typed Protocol Boundaries – Tool<Input, Output, Progress> defines three independent contracts: input validation (Zod), output shape ( ToolResult), and real‑time progress ( onProgress).

Insight 2: contextModifier as a Precise State‑Management Escape Hatch – Instead of mutating global state, a tool returns a pure function that describes how the context should change; the framework applies it at a safe point, and it only works for non‑concurrency‑safe tools.

Insight 3: Only Three Methods Are Mandatory – Although the interface lists 30+ methods, a minimal tool needs just name, inputSchema, and call. The factory supplies the remaining safety‑related methods, and UI rendering methods are optional defaults.

07 – Critical Perspective: Limits of the Design

Interface Bloat : UI rendering methods (e.g., renderToolUseMessage, renderToolResultMessage) share the same interface as core logic, coupling backend changes with frontend rendering. Some projects already split UI into separate UI.tsx files, but the contract remains entangled.

ToolUseContext Is a Catch‑All : the context object contains 34 fields, acting as an ad‑hoc DI container without a formal IoC framework. Testing requires mocking many fields, creating tension between the lightweight QueryDeps and tool implementations.

Default isDestructive Paradox : fail‑closed would suggest defaulting to the strictest setting, yet isDestructive defaults to false to avoid overwhelming users with alerts. This reflects a trade‑off between security and usability.

08 – Practical Recommendations for Reusing the Pattern

Define a generic triple for your own tool protocol:

type Tool<Input extends ZodSchema, Output, Progress = never> = {
  name: string
  inputSchema: Input
  call(args: z.infer<Input>, onProgress?: (p: Progress) => void): Promise<Output>
}

Provide a factory that injects Fail‑Closed defaults:

const SAFE_DEFAULTS = { isConcurrencySafe: () => false, isReadOnly: () => false }
function buildTool<D extends ToolDef>(def: D) { return { ...SAFE_DEFAULTS, ...def } }

Keep progress types generic instead of any so each tool’s progress remains type‑safe.

type ToolCallProgress<P> = (progress: P) => void

Use contextModifier instead of mutating globals; return a pure function that the framework applies.

type ToolResult<T> = { data: T; contextModifier?: (ctx: Context) => Context }

Conclusion

The generic triple Tool<Input, Output, Progress> is the foundational type contract of Claude Code’s tool system.

Three generic parameters define independent protocol boundaries: input validation (Zod), output structure ( ToolResult), and real‑time communication (Progress callbacks).

The buildTool factory implements a Fail‑Closed strategy with safe defaults ( isConcurrencySafe = false, isReadOnly = false), forcing developers to explicitly relax constraints. ToolResult.contextModifier offers a pure‑function‑based state‑management escape hatch that only applies to non‑concurrency‑safe tools.

Input‑driven dynamic flags enable fine‑grained permission and concurrency decisions (e.g., distinguishing read‑only vs. destructive commands for BashTool).

Although the interface appears large, only three methods are required for a minimal tool; the rest are optional or supplied by the factory.