Every tool lives in src/tools/<ToolName>/ as a self-contained module. Tools are registered in src/tools.ts and invoked by the Query Engine during LLM tool-call loops.
Each tool defines:
- Input schema — Zod-validated parameters
- Permission model — What requires user approval
- Execution logic — The tool’s implementation
- UI components — Terminal rendering for invocation and results
- Concurrency safety — Whether it can run in parallel
export const MyTool = buildTool({
name: 'MyTool',
aliases: ['my_tool'],
description: 'What this tool does',
inputSchema: z.object({
param: z.string(),
}),
async call(args, context, canUseTool, parentMessage, onProgress) {
// Execute and return { data: result, newMessages?: [...] }
},
async checkPermissions(input, context) { /* Permission checks */ },
isConcurrencySafe(input) { /* Can run in parallel? */ },
isReadOnly(input) { /* Non-destructive? */ },
prompt(options) { /* System prompt injection */ },
renderToolUseMessage(input, options) { /* UI for invocation */ },
renderToolResultMessage(content, progressMessages, options) { /* UI for result */ },
})
src/tools/MyTool/
├── MyTool.ts # Main implementation
├── UI.tsx # Terminal rendering
├── prompt.ts # System prompt contribution
└── utils.ts # Tool-specific helpers
| Tool | Description | Read-only |
|---|
FileReadTool | Read file contents (text, images, PDFs, notebooks). Supports line ranges | Yes |
FileWriteTool | Create or overwrite files | No |
FileEditTool | Partial file modification via string replacement | No |
GlobTool | Find files matching glob patterns (e.g. **/*.ts) | Yes |
GrepTool | Content search using ripgrep (regex-capable) | Yes |
NotebookEditTool | Edit Jupyter notebook cells | No |
TodoWriteTool | Write to a structured todo/task file | No |
| Tool | Description | Read-only |
|---|
BashTool | Execute shell commands in bash | No |
PowerShellTool | Execute PowerShell commands (Windows) | No |
REPLTool | Run code in a REPL session (Python, Node, etc.) | No |
| Tool | Description | Read-only |
|---|
AgentTool | Spawn a sub-agent for complex tasks | No |
SendMessageTool | Send messages between agents | No |
TeamCreateTool | Create a team of parallel agents | No |
TeamDeleteTool | Remove a team agent | No |
EnterPlanModeTool | Switch to planning mode (no execution) | No |
ExitPlanModeTool | Exit planning mode, resume execution | No |
EnterWorktreeTool | Isolate work in a git worktree | No |
ExitWorktreeTool | Exit worktree isolation | No |
SleepTool | Pause execution (proactive mode) | Yes |
SyntheticOutputTool | Generate structured output | Yes |
| Tool | Description | Read-only |
|---|
TaskCreateTool | Create a new background task | No |
TaskUpdateTool | Update a task’s status or details | No |
TaskGetTool | Get details of a specific task | Yes |
TaskListTool | List all tasks | Yes |
TaskOutputTool | Get output from a completed task | Yes |
TaskStopTool | Stop a running task | No |
| Tool | Description | Read-only |
|---|
WebFetchTool | Fetch content from a URL | Yes |
WebSearchTool | Search the web | Yes |
MCP (Model Context Protocol) tools
| Tool | Description | Read-only |
|---|
MCPTool | Invoke tools on connected MCP servers | Varies |
ListMcpResourcesTool | List resources exposed by MCP servers | Yes |
ReadMcpResourceTool | Read a specific MCP resource | Yes |
McpAuthTool | Handle MCP server authentication | No |
ToolSearchTool | Discover deferred/dynamic tools from MCP servers | Yes |
| Tool | Description | Read-only |
|---|
LSPTool | Language Server Protocol operations (go-to-definition, find references, etc.) | Yes |
SkillTool | Execute a registered skill | Varies |
Scheduling & triggers
| Tool | Description | Read-only |
|---|
ScheduleCronTool | Create a scheduled cron trigger | No |
RemoteTriggerTool | Fire a remote trigger | No |
| Tool | Description | Read-only |
|---|
AskUserQuestionTool | Prompt the user for input during execution | Yes |
BriefTool | Generate a brief/summary | Yes |
ConfigTool | Read or modify Claude Code configuration | No |
Permission model
Every tool invocation passes through the permission system at src/hooks/toolPermission/. Each tool implements checkPermissions() returning { granted: boolean, reason?, prompt? }.
Permission modes
| Mode | Behavior |
|---|
default | Prompt the user for each potentially destructive operation |
plan | Show the full execution plan, ask once for batch approval |
bypassPermissions | Auto-approve all operations (dangerous — for trusted environments only) |
auto | ML-based classifier automatically decides (experimental) |
Permission rule syntax
Rules use wildcard patterns to match tool invocations:
Bash(git *) # Allow all git commands without prompt
Bash(npm test) # Allow 'npm test' specifically
FileEdit(/src/*) # Allow edits to anything under src/
FileRead(*) # Allow reading any file
bypassPermissions mode auto-approves all tool invocations, including destructive file writes and shell commands. Only use it in fully trusted, sandboxed environments.
src/tools.ts for different contexts. For example, read-only tools are used for code review workflows while the full toolset is enabled for active development sessions.
