Tools

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
}

// Execution flow:
Input → validateInput()
     → checkPermissions() [bashToolHasPermission]
     → shouldUseSandbox()?
     → exec() via SandboxManager
     → Output parsing + image detection
     → Result persistence if >100K chars

// Security layers:
1. AST-based parsing (tree-sitter)
   → Detects dangerous patterns: redirection, pipes, subshells

2. ML classifier (opt-in)
   → AI evaluates command safety with confidence scoring
   → Can auto-approve safe patterns (git status, ls, etc.)

3. Permission rule matching
   → Exact: "git"
   → Prefix: "git *" (any git subcommand)
   → Wildcard: "*test*" (contains pattern)

4. Semantic analysis
   → Detects dangerous redirections to system files
   → Blocks shell config modifications (.bashrc, .zshrc)

5. Read-only constraints
   → Blocks write commands in non-privileged sessions
   → Prevents privilege escalation via package managers

// 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 logic

// 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 versioning