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 (--allowedTools, /permissions add), in a custom agent's tools and disallowedTools lists, and in hook 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	When a model-invocable skill exists
`Task`	Delegate to a subagent	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	When the server is connected

Which tools may run without asking depends on the permission mode: 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 can restore the file.

Paths outside the workspace ask for approval; see 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.

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 Ctrl+T to show or hide the list.

ExitPlanMode

Used in 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.

Skill

Runs a skill. Parameters: name (one of the skills the agent may invoke) and args.

Delegation

Task

Starts a subagent 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 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 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 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.

Permissions: Modes, allow rules, and the workspace boundary
Custom Agents: Limiting an agent's tools
Subagents: Delegation with Task
MCP Servers: Tools from external servers
Hooks: Run commands before and after tool calls
Notebooks: Pairing with a Jupyter notebook
Plans & Goals: Plan mode, scheduling, and /rewind