# Tools Reference

> Complete reference for CodeBuddy Code's available tools, including permission requirements.

CodeBuddy Code includes a set of built-in tools to help understand and modify your codebase. The tool names in the table below are the identifiers used in [permission rules](iam.md#tool-specific-permission-rules), [sub-agent tool lists](sub-agents.md), and [Hook matchers](hooks.md).

| Tool | Description | Requires Permission |
| :--- | :--- | :------- |
| `Agent` | Spawns a [sub-agent](sub-agents.md) with an independent context window to handle tasks | No |
| `AskUserQuestion` | Asks the user a multiple-choice question to gather requirements or clarify ambiguities | Yes |
| `Bash` | Executes shell commands in your environment. See [Bash Tool Behavior](#bash-tool-behavior) | Yes |
| `CronCreate` | Schedules recurring or one-time tasks within the current session (expires on exit). See [Scheduled Tasks](scheduled-tasks.md) | No |
| `CronDelete` | Cancels a scheduled task by ID | No |
| `CronList` | Lists all scheduled tasks in the current session | No |
| `DeferExecuteTool` | Executes a deferred tool discovered via `ToolSearch` | No |
| `Edit` | Performs precise string replacement edits on files | Yes |
| `EnterPlanMode` | Switches to plan mode for designing implementation approaches before coding | No |
| `EnterWorktree` | Creates an isolated [git worktree](worktree.md) and switches into it | Yes |
| `ExitPlanMode` | Submits a plan for user approval and exits plan mode | Yes |
| `Glob` | Finds files using glob patterns | No |
| `Grep` | Searches file contents using regex patterns | No |
| `ImageEdit` | Edits or modifies existing images based on text instructions | Yes |
| `ImageGen` | Generates images from text descriptions | Yes |
| `LeaveWorktree` | Exits the worktree session and returns to the original directory | Yes |
| `ListMcpResources` | Lists all resources/templates exposed by connected [MCP servers](mcp.md); optionally filtered by server name | No |
| `LSP` | Provides code intelligence via Language Server. Automatically reports type errors and warnings after file edits. Also supports navigation operations such as go-to-definition, find references, get type info, list symbols, find implementations, and trace call hierarchies. Requires a [Code Intelligence Plugin](plugins.md) and its language server binary | No |
| `MultiEdit` | Performs multiple edits on the same file in a single atomic operation | Yes |
| `NotebookEdit` | Modifies Jupyter notebook cell contents | Yes |
| `NotebookRead` | Reads Jupyter notebook cell contents; specify `cell_id` to read a single cell | No |
| `PowerShell` | Executes PowerShell commands on Windows. Only available on Windows, see [PowerShell Tool Behavior](#powershell-tool-behavior) | Yes |
| `Read` | Reads file contents, supporting images, PDFs, and Jupyter notebooks | No |
| `ReadMcpResource` | Reads the content of a specific MCP resource by server + URI; pairs with `ListMcpResources` | Yes |
| `SendMessage` | Sends messages to teammates in an [Agent Team](agent-teams.md) | No |
| `Skill` | Executes a [Skill](skills.md) in the main conversation | No |
| `SlashCommand` | Executes a custom [slash command](slash-commands.md) | Yes |
| `StructuredOutput` | Returns structured output conforming to a JSON Schema | No |
| `TaskCreate` | Creates a new task in the task list | No |
| `TaskGet` | Retrieves full details of a specific task | No |
| `TaskList` | Lists all tasks with their current status | No |
| `TaskOutput` | Retrieves output from a background task or sub-agent | No |
| `TaskStop` | Stops a running background task by ID | No |
| `TaskUpdate` | Updates task status, dependencies, details, or deletes a task | No |
| `TeamCreate` | Creates an [Agent Team](agent-teams.md) for coordinating multiple agents | No |
| `TeamDelete` | Deletes an Agent Team and its task directory | No |
| `ToolSearch` | Searches and loads deferred tools, supporting both built-in tools and [MCP tools](mcp.md#deferred-loading-defer_loading) | No |
| `WaitForMcpServers` | Waits for the specified MCP servers to finish connecting (defaults to all pending servers), with a 5-second timeout | No |
| `WebFetch` | Fetches content from a specified URL and performs AI analysis | Yes |
| `WebSearch` | Performs a web search | Yes |
| `Workflow` | Launches a [Dynamic Workflow](workflows.md) asynchronously, returns a runId immediately, and runs in the background; pull results via `TaskOutput` | Yes |
| `Write` | Creates or overwrites files | Yes |

Permission rules can be configured via the `/permissions` command or in [permission settings](settings.md#permission-settings). See also [Tool-Specific Permission Rules](iam.md#tool-specific-permission-rules).

## Tool Aliases

Some tools have aliases that can be used interchangeably in permission rules:

| Tool | Alias |
| :--- | :--- |
| `TaskOutput` | `BashOutput` |
| `TaskStop` | `KillShell` |
| `PowerShell` | `pwsh`, `ps` |

## Bash Tool Behavior

The Bash tool executes each command in a separate process with the following persistence characteristics:

* **Working directory** persists across commands. Set `CODEBUDDY_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` to reset to the project directory after each command.
* **Environment variables do not persist**. An `export` in one command will not take effect in the next command.

Activate your virtualenv or conda environment before launching CodeBuddy Code. To persist environment variables across Bash commands, set [`CODEBUDDY_ENV_FILE`](env-vars.md) to point to a shell script before startup, or use a [SessionStart Hook](hooks.md) to populate it dynamically.

### Sandbox Mode

The Bash tool supports [sandbox isolation](bash-sandboxing.md), which can restrict filesystem and network access. When sandbox is enabled, commands execute in a restricted environment to prevent unauthorized system access.

The `dangerouslyDisableSandbox` parameter allows bypassing the sandbox on a per-command basis (requires user approval).

### Background Execution

The `run_in_background` parameter allows running commands in the background, using the `TaskOutput` tool to read the output. This is suitable for long-running builds, tests, and similar scenarios.

## PowerShell Tool Behavior

The PowerShell tool is only available on Windows and provides native PowerShell command execution.

### Relationship with Bash Tool

* **With Git Bash**: Both Bash and PowerShell tools are available; the model chooses the appropriate tool based on the scenario
* **Without Git Bash**: The Bash tool is automatically disabled, and the PowerShell tool becomes the only shell tool
* The PowerShell tool is not available on macOS/Linux

### Version Adaptation

The PowerShell tool automatically detects the PowerShell version, preferring PowerShell 7+ (pwsh) and falling back to Windows PowerShell 5.1. Syntax guidance in prompts adjusts automatically based on version differences (e.g., the `&&` operator is only supported in 7+).

### Security Checks

The PowerShell tool includes a built-in security checker covering dangerous patterns such as code injection, download-and-execute, privilege escalation, and system destruction. Dangerous commands (e.g., `Invoke-Expression`, `Add-Type`) are blocked, and system-modifying commands require user confirmation.

### Environment Variables

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_POWERSHELL_PATH` | Explicitly specify the PowerShell path (takes priority over auto-detection) |
| `CODEBUDDY_USE_POWERSHELL_TOOL` | Set to `0` to disable the PowerShell tool |

## Deferred Tool Loading

Some tools (such as those provided via [MCP servers](mcp.md)) use deferred loading. These tools do not appear in the initial tool list and must be discovered and activated via `ToolSearch`. Once activated, tools remain available for the rest of the session.

## See Also

* [Identity and Access Management](iam.md): Permission system, rule syntax, and tool-specific rules
* [Sub-Agents](sub-agents.md): Configuring tool access for sub-agents
* [Hooks](hooks-guide.md): Running custom commands before and after tool execution
* [MCP Integration](mcp.md): Extending available tools via MCP servers
* [Scheduled Tasks](scheduled-tasks.md): Scheduling automated tasks with CronCreate
* [Agent Teams](agent-teams.md): Multi-agent collaborative team system
