# Tools

> Source: https://parallelworks.com/docs/ai/code/tools

# Tools

The agent works through **tools**: reading and editing files, running shell commands, searching, fetching URLs, delegating to subagents. This page lists every built-in tool with its parameters and limits.

Tool names are case-sensitive. Use them exactly as written here in [allow rules](/docs/ai/code/permissions#allow-rules) (`--allowedTools`, `/permissions add`), in a [custom agent's](/docs/ai/code/custom-agents#tool-names) `tools` and `disallowedTools` lists, and in [hook](/docs/ai/code/hooks) matchers.

## At a Glance

| Tool | What it does | Available |
| --- | --- | --- |
| `Bash` | Run a shell command | Always |
| `BashOutput`, `KillShell` | Read or stop a background command | Main session |
| `ReadFile` | Read a file | Always |
| `WriteFile`, `EditFile` | Create, overwrite, or edit a file | Always |
| `GlobSearch` | Find files by name pattern | Always |
| `GrepSearch` | Search file contents | Always |
| `WebFetch` | Fetch a URL | Always |
| `NotebookRead`, `NotebookEdit` | Read and edit a paired Jupyter notebook | With `--notebook` |
| `NotebookRun` | Run code in the paired notebook's kernel | With `--notebook` and `--kernel` |
| `AskUserQuestion` | Ask you a question | Main session |
| `TodoWrite` | Keep a task list | Always |
| `ExitPlanMode` | Present a plan for approval | Main session |
| `Skill` | Run a [skill](/docs/ai/code/skills) | When a model-invocable skill exists |
| `Task` | Delegate to a [subagent](/docs/ai/code/subagents) | Unless subagents are off or nesting is not allowed |
| `SendMessage` | Send an interim message to the main session | Subagents only |
| `CronCreate`, `CronList`, `CronDelete`, `ScheduleWakeup` | Schedule prompts in this session | Main session |
| `mcp__<server>__<tool>` | A tool from an [MCP server](/docs/ai/code/mcp) | When the server is connected |

Which tools may run without asking depends on the [permission mode](/docs/ai/code/permissions#permission-modes): reads and searches always run, file edits run in `accept-edits` and above, shell commands and MCP tools ask unless an allow rule covers them, and `bypass-permissions` runs everything.

## Shell

### Bash

Runs a command with `bash` in the workspace root. Each call starts fresh: a `cd` or exported variable does not carry over to the next call.

| Parameter | Meaning |
| --- | --- |
| `command` | The command to run (required). |
| `workdir` | Directory for this command only, absolute or relative to the workspace. Taken literally, without shell expansion. |
| `env` | Environment variable overrides for this command and its children, as literal strings. Names may contain only letters, digits, and underscores. |
| `timeout` | Milliseconds. Default 120000 (2 minutes), maximum 600000 (10 minutes). |
| `description` | A short label for the command, shown in the transcript and in `/tasks`. |
| `run_in_background` | Start the command and return an ID right away. Main session only. |
| `dangerouslyDisableSandbox` | Skip the command safety checks. Has an effect only in `bypass-permissions` mode. |

- stdout and stderr are each captured up to 100 KB, along with the exit code.
- A `workdir` outside the workspace, or any `env` override, always asks for approval unless the session is in `bypass-permissions`. Overrides can change which programs run (through `PATH`, for example), so an allow rule does not skip that prompt.
- When the timeout expires, the whole process group is killed.

### Background Commands: BashOutput and KillShell

A command started with `run_in_background` gets an ID like `bash-1`. It keeps running while the conversation continues, and when it exits on its own, the agent is notified; an idle session wakes up to act on the result. `/tasks` lists background commands and their status.

| Tool | Parameters | Meaning |
| --- | --- | --- |
| `BashOutput` | `bash_id`, `filter` (optional regex) | Returns output produced since the last call, plus the status and exit code. With `filter`, only matching lines are returned; the rest are still consumed. |
| `KillShell` | `shell_id` | Stops the command and its whole process tree. Output it already produced stays readable. |

Each background command keeps its most recent 200 KB of output; older unread output is dropped with a note saying how much. Background commands are available only to the main session (subagents run commands in the foreground), and they are killed on `/clear` and when you resume another session.

## Files

### ReadFile

| Parameter | Meaning |
| --- | --- |
| `path` | File path, absolute or relative to the workspace (required). |
| `offset` | First line to read, 0-based. Default 0. |
| `limit` | Maximum lines to read. Default 2000. |

Output is line-numbered. A line longer than 2000 bytes is cut and marked `(line truncated)`. An image file is returned as an image the model can view. Other binary files are refused, as are files inside git's object store (use `git show` instead).

### WriteFile and EditFile

| Tool | Parameters | Meaning |
| --- | --- | --- |
| `WriteFile` | `path`, `content` | Creates or overwrites a file. Missing parent directories are created. |
| `EditFile` | `path`, `old_string`, `new_string`, `replace_all` | Replaces an exact string. `old_string` must match exactly once unless `replace_all` is `true`. |

Writes are atomic (a write that is interrupted never leaves a half-written file) and keep the file's existing permission bits, so an executable script stays executable. Every change is recorded so [`/rewind`](/docs/ai/code/plan-and-goals) can restore the file.

Paths outside the workspace ask for approval; see [Workspace Boundary](/docs/ai/code/permissions#workspace-boundary).

## Search

### GlobSearch

| Parameter | Meaning |
| --- | --- |
| `pattern` | Glob pattern (required). `**` matches across directories and `{a,b}` matches alternatives, as in `**/*.{ts,tsx}`. |
| `path` | Directory to search. Default: the workspace root. |

Returns up to 100 paths, most recently modified first. `.git`, `node_modules`, `vendor`, `__pycache__`, `.next`, and `dist` directories are skipped.

### GrepSearch

Searches file contents with a regular expression. It uses `rg` (ripgrep) when it is installed and a built-in search otherwise.

| Parameter | Meaning |
| --- | --- |
| `pattern` | Regular expression (required). |
| `path` | File or directory to search. Default: the workspace root. |
| `glob` | Only search files matching this glob, such as `*.go` or `*.{ts,tsx}`. |
| `type` | Only search this file type, such as `js`, `py`, or `go`. |
| `output_mode` | `files_with_matches` (default), `content` (matching lines), or `count`. |
| `A`, `B`, `C` / `context` | Lines of context after, before, or around each match (`content` mode). |
| `n` | Show line numbers. Default `true`. |
| `i` | Case-insensitive. |
| `multiline` | Let a pattern span lines. |
| `head_limit` | Return at most this many results. Default 250. |
| `offset` | Skip this many results first, for paging. |

## Web

### WebFetch

| Parameter | Meaning |
| --- | --- |
| `url` | An `http://` or `https://` URL (required). |
| `headers` | Extra HTTP headers to send. |

- HTML pages are converted to Markdown; other responses are returned as text.
- A request times out after 30 seconds, follows at most 10 redirects, and reads at most 2 MB of the response.
- Addresses that are not on the public internet are refused on every hop, including redirects: loopback (`localhost`), private networks, link-local and cloud metadata addresses, and carrier-grade NAT ranges. To read a local service, use `Bash` with `curl`, which goes through the normal shell approval.

## Notebooks

Present only when `pw code` is started with `--notebook`; `NotebookRun` also needs `--kernel`. See [Notebooks](/docs/ai/code/notebooks).

| Tool | Parameters | Meaning |
| --- | --- | --- |
| `NotebookRead` | `notebook_path` | Returns every cell's ID, type, execution count, source, and text output. |
| `NotebookEdit` | `notebook_path`, `cell_id`, `new_source`, `cell_type`, `edit_mode` | `edit_mode` is `replace` (default), `insert` (after `cell_id`, or at the top when it is empty; needs `cell_type` of `code` or `markdown`), or `delete`. Editing a code cell clears its outputs. |
| `NotebookRun` | `code`, `timeout_seconds` | Runs Python in the notebook's kernel, sharing its variables and imports. Default timeout 120 seconds, maximum 600; on timeout the kernel is interrupted. Not available in `read-only` or `plan` mode. |

## Interaction and Planning

### AskUserQuestion

| Parameter | Meaning |
| --- | --- |
| `question` | The question (required). |
| `header` | A short label summarizing it. |
| `options` | Choices, each with a `label` and optional `description`. Omit for a free-text question. |
| `multiSelect` | Allow picking more than one option. |

You can always type your own answer instead of picking an option, or choose **Chat about this** to talk it through before answering. Available only in the main session; subagents cannot ask you questions.

### TodoWrite

Keeps the agent's task list for the session. Each call sends the full list (`todos`), each item with `content`, `status` (`pending`, `in_progress`, or `completed`), and `activeForm` (the text shown while it runs). The agent keeps one item `in_progress` at a time. Press <kbd>Ctrl</kbd>+<kbd>T</kbd> to show or hide the list.

### ExitPlanMode

Used in [plan mode](/docs/ai/code/permissions#plan-mode) to present a finished plan (`plan`, as Markdown) and ask whether to build it. The plan is saved under `~/.local/state/pw/plans/`. Available only in the main session. See [Plans & Goals](/docs/ai/code/plan-and-goals).

### Skill

Runs a [skill](/docs/ai/code/skills#through-the-skill-tool). Parameters: `name` (one of the skills the agent may invoke) and `args`.

## Delegation

### Task

Starts a [subagent](/docs/ai/code/subagents) or sends follow-up work to one.

| Parameter | Meaning |
| --- | --- |
| `description` | A short label for the task (required). |
| `prompt` | Self-contained instructions (required). |
| `subagent_type` | A [custom agent](/docs/ai/code/custom-agents) name, a built-in type (`default` or `explore`), or `fork` to copy this conversation. Omit for a general-purpose subagent. |
| `background` | Default `true`. `false` waits for the result inline. One-shot runs and nested subagents always wait. |
| `task_id` | Resume an existing subagent, such as `task-3`, with its context intact. |
| `model` | Run this subagent on a different model. |

`Task` is missing when subagents are turned off, when the nesting depth does not allow another level, or when a custom agent's `tools` allowlist leaves it out.

### SendMessage

Present only in subagents. Sends a short interim message (`message`) to the main session, such as a blocker or a key finding, while the subagent keeps working.

## Scheduling

These tools schedule prompts that run later in the same session. They exist only in the main session and are removed entirely when the `CLAUDE_CODE_DISABLE_CRON` environment variable is set to `1`. See [Plans & Goals](/docs/ai/code/plan-and-goals) for `/loop` and how scheduled prompts run.

| Tool | Parameters | Meaning |
| --- | --- | --- |
| `CronCreate` | `cron`, `prompt`, `recurring` | Schedules `prompt` with a five-field cron expression (minute, hour, day of month, month, day of week) in local time. A one-shot task fires once and is deleted; a recurring task fires on every match and expires after 7 days. |
| `CronList` | none | Lists scheduled tasks and any pending self-paced wakeup. |
| `CronDelete` | `id` | Cancels a task by its 8-character ID. |
| `ScheduleWakeup` | `delay_minutes`, `prompt`, `stop` | Sets the delay before the next iteration of a self-paced loop (1 to 60 minutes), or ends the loop with `stop`. |

A session holds at most 50 scheduled tasks. Firing times get a small deterministic jitter so many sessions on the same schedule do not all fire at once.

## MCP Tools

Each tool from a connected [MCP server](/docs/ai/code/mcp) is named `mcp__<server>__<tool>`, for example `mcp__github__list_prs`. Its parameters come from the server. MCP tools ask before each call unless an allow rule covers them.

## Large Outputs

When a tool's output is larger than 50 KB (32 KB for `WebFetch`), the agent sees the beginning and end with the middle omitted. The full output is saved to a file under `~/.local/state/pw/code-tool-output/`, and the agent is told the path so it can read the rest with `ReadFile`. Saved outputs are deleted after 7 days.

## Related Documentation

- [Permissions](/docs/ai/code/permissions): Modes, allow rules, and the workspace boundary
- [Custom Agents](/docs/ai/code/custom-agents): Limiting an agent's tools
- [Subagents](/docs/ai/code/subagents): Delegation with `Task`
- [MCP Servers](/docs/ai/code/mcp): Tools from external servers
- [Hooks](/docs/ai/code/hooks): Run commands before and after tool calls
- [Notebooks](/docs/ai/code/notebooks): Pairing with a Jupyter notebook
- [Plans & Goals](/docs/ai/code/plan-and-goals): Plan mode, scheduling, and `/rewind`