Skip to content

TOOLS.md

Latest commit

 

History

History
374 lines (294 loc) · 9.5 KB

TOOLS.md

File metadata and controls

374 lines (294 loc) · 9.5 KB
Raw

yo-code Tool Reference

Snapshot documentation of the built-in tools found in the imported yo-code source tree.

Tool Categories

File Operations

Tool Description Key Features
FileReadTool Read file contents Line ranges, syntax highlighting, large file handling
FileEditTool Edit files with SEARCH/REPLACE Diff-based editing, conflict detection
FileWriteTool Create or overwrite files Directory creation, overwrite protection
GlobTool Find files by pattern Glob patterns, recursive search

Shell Execution

Tool Description Key Features
BashTool Execute shell commands Permission modes, sandbox, timeouts
PowerShellTool Windows PowerShell Windows-specific commands

Search

Tool Description Key Features
GrepTool Search file contents Regex support, file filtering
ToolSearchTool Search available tools Tool discovery by name/description

Web

Tool Description Key Features
WebSearchTool Search the web Query-based search results
WebFetchTool Fetch URL contents HTML extraction, content parsing

Agent Management

Tool Description Key Features
AgentTool Spawn subagents Isolated context, parallel execution
TaskCreateTool Create tasks Task tracking, status updates
TaskGetTool Get task details Task information retrieval
TaskListTool List all tasks Task overview
TaskOutputTool Get task output Task result retrieval
TaskStopTool Stop a task Task cancellation
TaskUpdateTool Update task Task metadata updates

MCP Integration

Tool Description Key Features
MCPTool Call MCP server tools External tool execution
ListMcpResourcesTool List MCP resources Resource discovery
ReadMcpResourceTool Read MCP resource Resource content retrieval
McpAuthTool MCP authentication OAuth flow for MCP servers

IDE Integration

Tool Description Key Features
LSPTool Language Server Protocol Code intelligence, diagnostics

Planning

Tool Description Key Features
EnterPlanModeTool Enter planning mode Structured planning workflow
ExitPlanModeTool Exit planning mode Plan execution
EnterWorktreeTool Enter git worktree Isolated development
ExitWorktreeTool Exit git worktree Worktree cleanup

Communication

Tool Description Key Features
AskUserQuestionTool Ask user for input Interactive clarification
SendMessageTool Send messages Inter-agent communication
RemoteTriggerTool Trigger remote actions Remote session control

Utility

Tool Description Key Features
TodoWriteTool Manage todo lists Task tracking
SleepTool Delay execution Timed waits
SkillTool Load skills Dynamic skill loading
ConfigTool Manage configuration Settings updates
BriefTool Generate briefs Task summaries
ScheduleCronTool Schedule cron jobs Recurring tasks
REPLTool REPL execution Interactive sessions
NotebookEditTool Edit notebooks Jupyter notebook support

Tool Interface

All tools implement a standardized interface:

interface Tool {
  // Tool identification
  name: string;
  description: string;
  
  // Input validation
  inputSchema: ToolInputJSONSchema;
  
  // Execution
  execute(
    input: Record<string, unknown>,
    context: ToolUseContext
  ): Promise<ToolResult>;
}

ToolUseContext

Provides execution context:

interface ToolUseContext {
  appState: AppState;
  canUseTool: CanUseToolFn;
  appendSystemMessage?: (msg: SystemMessage) => void;
  setAppState?: (updater: (state) => newState) => void;
  // ... additional context
}

ToolResult

Standardized result format:

interface ToolResult {
  content: ContentBlock[];
  isError?: boolean;
  // ... additional fields
}

Permission System

Tools support three permission modes:

Mode Behavior
auto-approve Execute without asking
ask Prompt user for approval
deny Block execution

Permission Checks

// Before executing any tool
const permission = await canUseTool(toolName, input, context);
if (!permission.approved) {
  return { content: [], isError: true };
}

BashTool Deep Dive

The most complex and security-sensitive tool.

Security Features

  1. Permission Modes:

    • Auto-approve for safe commands
    • Ask for potentially destructive commands
    • Deny for blocked commands

  2. Command Classification:

    • Read-only commands (ls, cat, grep, etc.)
    • Write commands (echo >, touch, etc.)
    • Dangerous commands (rm -rf, dd, etc.)

  3. Sandbox Execution:

    • Optional containerized execution
    • File system restrictions
    • Network isolation

  4. Output Handling:

    • Truncation for large outputs
    • ANSI stripping
    • Error stream separation

Configuration

interface BashConfig {
  permissionMode: 'auto' | 'ask' | 'deny';
  sandboxEnabled: boolean;
  timeoutMs: number;
  maxOutputBytes: number;
  allowlist: string[];
  blocklist: string[];
}

FileEditTool Deep Dive

Diff-based file editing with conflict detection.

SEARCH/REPLACE Format

<<<<<<< SEARCH
original code here
=======
replacement code here
>>>>>>> REPLACE

Features

  • Multiple edits: Apply multiple SEARCH/REPLACE blocks
  • Conflict detection: Detect when search text doesn't match
  • Undo support: File history for rollback
  • Large file handling: Efficient diff application

AgentTool Deep Dive

Subagent spawning for parallel task execution.

Usage

// Spawn a subagent
const result = await runForkedAgent({
  promptMessages: [createUserMessage({ content: task })],
  canUseTool: createCanUseTool(context),
  querySource: 'subagent',
  forkLabel: 'task',
  skipTranscript: true,
});

Features

  • Isolated context: Separate message history
  • Shared tools: Access to parent's tool set
  • Abort support: Cancellation via AbortController
  • Progress reporting: Real-time status updates
  • Resource limits: Token and cost tracking

Adding Custom Tools

  1. Create tool directory:
src/tools/MyTool/
├── MyTool.ts
├── constants.ts
├── prompt.ts
└── index.ts
  1. Implement tool interface:
export const MY_TOOL_NAME = 'MyTool';

export function createMyTool(): Tool {
  return {
    name: MY_TOOL_NAME,
    description: 'Description of what the tool does',
    inputSchema: z.object({
      param1: z.string().describe('Parameter description'),
      param2: z.number().optional(),
    }),
    execute: async (input, context) => {
      // Implementation
      return { content: [{ type: 'text', text: 'Result' }] };
    },
  };
}
  1. Register in src/tools.ts:
import { createMyTool } from './tools/MyTool';

export function getTools(): Tools {
  return {
    // ... existing tools
    MyTool: createMyTool(),
  };
}

Tool Execution Flow

LLM generates tool_use block
         │
         ▼
┌─────────────────────┐
│ Parse tool name     │
│ and input           │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Validate input      │
│ against schema      │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Check permissions   │
│ (auto/ask/deny)     │
└────────┬────────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
  Denied   Approved
    │         │
    │         ▼
    │   ┌─────────────┐
    │   │ Execute     │
    │   │ tool        │
    │   └──────┬──────┘
    │          │
    │          ▼
    │   ┌─────────────┐
    │   │ Format      │
    │   │ result      │
    │   └──────┬──────┘
    │          │
    ▼          ▼
┌─────────────────────┐
│ Append tool_result  │
│ to message history  │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Continue query      │
│ (LLM processes      │
│  tool result)       │
└─────────────────────┘

Tool Limits

The system enforces various limits:

Limit Description
Max tool calls per turn Prevents infinite loops
Max output size Truncates large outputs
Timeout Kills long-running tools
Concurrent tools Limits parallel execution
File size limits Restricts file operations

See src/constants/toolLimits.ts for specific values.