🔧 The Tool System

Toda capacidade que o Claude Code expoe ao modelo -- leitura de arquivos, execucao de bash, busca web, chamadas MCP -- e uma Tool. O tool system e a ponte entre o raciocinio em linguagem natural da IA e os efeitos colaterais concretos na sua maquina.

Arquivos cobertos: Tool.ts, tools.ts, tools/utils.ts, services/tools/toolOrchestration.ts, services/tools/toolExecution.ts, services/tools/StreamingToolExecutor.ts

O tipo Tool<Input, Output, P> e um protocol contract -- um tipo estrutural TypeScript que toda ferramenta deve satisfazer. E generico sobre tres parametros: o schema Zod de input, o tipo de output e o shape do evento de progresso.

Core Required Members

export type Tool<
  Input extends AnyObject,
  Output,
  P extends ToolProgressData
> = {
  name: string                 // primary identifier the model uses
  aliases?: string[]          // legacy names for backward compat
  inputSchema: Input          // Zod schema -- source of truth for validation
  maxResultSizeChars: number  // overflow -> persist to disk

  call(
    args: z.infer<Input>,
    context: ToolUseContext,
    canUseTool: CanUseToolFn,
    parentMessage: AssistantMessage,
    onProgress?: ToolCallProgress<P>
  ): Promise<ToolResult<Output>>

  checkPermissions(
    input: z.infer<Input>,
    context: ToolUseContext
  ): Promise<PermissionResult>

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

ToolResult e contextModifier

export type ToolResult<T> = {
  data: T
  newMessages?: (UserMessage | AssistantMessage | ...)[]
  // Only honored for non-concurrency-safe tools
  contextModifier?: (context: ToolUseContext) => ToolUseContext
}

O contextModifier e como uma tool (ex: EnterPlanMode) muta estado compartilhado sem acessar variaveis globais. Tools concorrentes NAO podem usar contextModifier -- limitacao conhecida documentada no StreamingToolExecutor.

Metodos Opcionais: UI e Classifier

Em vez de forcar autores a suprir cada metodo, buildTool() faz merge de um ToolDef (parcial) com defaults seguros. Os defaults sao fail-closed: assumem writes, assumem nao-safe para concorrencia.

const TOOL_DEFAULTS = {
  isEnabled:         () => true,
  isConcurrencySafe: () => false,   // conservative: assume state mutation
  isReadOnly:        () => false,
  isDestructive:     () => false,
  checkPermissions:  (input) =>
    Promise.resolve({ behavior: 'allow', updatedInput: input }),
  toAutoClassifierInput: () => '',
  userFacingName:    () => '',
}

export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return {
    ...TOOL_DEFAULTS,
    userFacingName: () => def.name,
    ...def,
  } as BuiltTool<D>
}

tools.ts e a source of truth para quais tools existem. Implementa um pipeline de assembly de tres camadas.

getAllBaseTools() -- Catalogo Exaustivo

export function getAllBaseTools(): Tools {
  return [
    AgentTool, TaskOutputTool, BashTool,
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    FileReadTool, FileEditTool, FileWriteTool,
    WebFetchTool, TodoWriteTool, WebSearchTool,
    // ... 30+ more tools, conditionally included
    ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),
  ]
}

getTools() -- Filtrado por Contexto

assembleToolPool() -- Built-ins + MCP

export function assembleToolPool(
  permissionContext: ToolPermissionContext,
  mcpTools: Tools,
): Tools {
  const builtInTools = getTools(permissionContext)
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)

  // Built-ins sorted alphabetically, then MCP tools sorted alphabetically.
  // Keeps a stable cache breakpoint between the two groups.
  const byName = (a, b) => a.name.localeCompare(b.name)
  return uniqBy(
    [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),
    'name',
  )
}

Quando uma resposta do modelo contem multiplos blocos tool_use, o orchestrator decide quais rodam concorrentemente e quais serialmente usando partitionToolCalls().

Algoritmo de Particionamento

// Simplified from partitionToolCalls()
for (const toolUse of toolUseMessages) {
  const safe = isConcurrencySafe(toolUse)
  if (safe && lastBatch?.isConcurrencySafe) {
    lastBatch.blocks.push(toolUse)       // extend parallel group
  } else {
    acc.push({ isConcurrencySafe: safe, blocks: [toolUse] })
  }
}

Context Modifier Dance

// Serial: apply immediately so next tool sees updated context
if (update.contextModifier) {
  currentContext = update.contextModifier.modifyContext(currentContext)
}

// Concurrent: queue, apply after batch
queuedContextModifiers[toolUseID].push(modifyContext)
// ... after all concurrent tools complete:
for (const modifier of modifiers) {
  currentContext = modifier(currentContext)
}

A variante real-time: inicia tools enquanto blocos ainda stream da API, antes da resposta completa do modelo. E a classe usada em producao no modo streaming.

Tool Lifecycle States

Concurrency Guard: canExecuteTool()

private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executing = this.tools.filter(t => t.status === 'executing')
  return (
    executing.length === 0 ||
    (isConcurrencySafe && executing.every(t => t.isConcurrencySafe))
  )
}

Sibling Abort: Bash Errors Cascade

runToolUse() e a funcao central de dispatch. O fluxo completo de checkPermissionsAndCallTool() tem 9 etapas:

Defense-in-Depth: _simulatedSedEdit Stripping

if (tool.name === BASH_TOOL_NAME && '_simulatedSedEdit' in processedInput) {
  const { _simulatedSedEdit: _, ...rest } = processedInput
  processedInput = rest  // field stripped, execution proceeds safely
}

Medida de defense-in-depth mesmo que o Zod strictObject ja devesse rejeitar o campo.

Input Mutation Safety

O ToolPermissionContext (wrapped em DeepImmutable) flui por todo o sistema. Controla tanto filtragem no registro quanto permission checks em runtime.

export type ToolPermissionContext = DeepImmutable<{
  mode: PermissionMode             // 'default' | 'plan' | 'bypassPermissions'
  additionalWorkingDirectories: Map<string, AdditionalWorkingDirectory>
  alwaysAllowRules: ToolPermissionRulesBySource
  alwaysDenyRules:  ToolPermissionRulesBySource
  alwaysAskRules:   ToolPermissionRulesBySource
  isBypassPermissionsModeAvailable: boolean
  shouldAvoidPermissionPrompts?: boolean  // background agents: auto-deny
}>