Agent tools

These are the tools the model can call. Each one runs in the session’s worker with the access of the account that worker runs as. There is no path allowlist and no approval step, as Security explains. Where it runs says what a worker can reach.

To limit what an agent may use, list tools in its allowed-tools. To run a check around a call, use a hook. Configuration lists the limit behind each bound below.

Reading files

Tool	What it does
listFiles	Lists one directory, or a bounded tree with recursive. Reports type, size, and permission mode. Nothing is hidden, so dotfiles, .git, and .env are listed like anything else. Symlinks are reported and not followed.
searchText	Searches text files for a literal string, or a regular expression with regex. Takes a file or a directory, and include globs that match the base name. While walking, it skips binary, unreadable, and oversized files.
readFile	Reads a line window from a text file and reports the sha256 of the whole file. Reads a .png, .jpg, .jpeg, .gif, or .webp file as an image, and extracts the text of a PDF.
webFetch	Fetches an http or https URL from the worker’s network and returns the body as text. HTML comes back as its readable text. Images, PDFs, and other binary content are refused. A 4xx or 5xx status is not an error.

Changing files

The change tools check that the agent knows what it is changing. Replacing or removing a file needs a read in the same turn, and writeFile and removePath also need that read’s hash in expectedSha256. A mismatch means the file changed underneath the agent, and the call is refused.

Tool	What it does
writeFile	Creates a text file or replaces one whole. Creates parent directories as needed. A new file needs no prior read.
editFile	Applies exact text replacements. Each old string must appear exactly once, and edits must not overlap. Nothing is written unless every edit resolves. Returns a bounded diff and the new hash.
applyPatch	Applies one exact-match patch across several files, in the *** Begin Patch envelope, with add, update, delete, and move actions.
movePath	Renames or moves a file or directory. It never overwrites, and it creates missing parent directories of the destination.
makeDirectory	Creates a directory and any missing parents. An existing directory succeeds.
removePath	Removes a file or directory. A non-empty directory needs recursive. A symlink is removed as a link. Removal is permanent.
changeDirectory	Changes the agent’s current directory and loads the target’s AGENTS.md, rules, skills, agents, hooks, and event handlers. A shell cd does not persist, so this is the way to move. Call it alone in a tool round.

Running commands

runCommand runs a shell command at once, with no confirmation, and records a purpose that says why. timeout bounds how long the call waits, never how long the command may run. A command still going when the wait ends keeps running as a background job, which the job tools handle. See process jobs.

Tool	What it does
runCommand	Runs a shell command in the current workspace, or in directory.
listJobs	Lists the session’s running and finished commands with their purpose, state, timings, and buffered output.
readJobOutput	Reads a bounded window of a job’s output without waiting. A non-zero dropped count means the buffer lost its oldest lines.
waitJob	Blocks until a job exits or the wait ends, and returns its state, exit code, and new output.
signalJob	Stops a job. stop sends SIGTERM to the whole process group and escalates to SIGKILL. kill goes straight to SIGKILL.

Skills and child agents

Tool	What it does
useSkill	Loads one skill’s full instructions by name. Files beside its SKILL.md are not preloaded.
launchAgent	Starts a child agent on a task and returns its agentRunId at once. The child is a stored agent named with agent, or an inline agentDefinition.
sendMessage	Sends a message to another agent in the session, root or a running agent’s agentRunId.
waitMessages	Blocks until a message waits for the agent.
stopAgent	Stops a running child and the children it launched.
ask	Asks a question and waits. A child asks the agent that launched it. The root asks the user.

Every agent has sendMessage, waitMessages, stopAgent, and ask, whether allowed-tools lists them or not.

Retained work

These tools work on what Peen kept after a stop or a crash. Recovery after a crash explains the flow.

Tool	What it does
searchExecutions	Finds retained work in this session by text, identity, state, or time. Reading does not resume anything.
readExecution	Reads an execution’s metadata, saved context, activities, events, or inbox without resuming it.
resumeExecution	Continues paused work. The agent uses it only when the user asks, after inspecting the saved history and the workspace.
resolveExecutionActivity	Records a decision on an uncertain step, retry or accept, with evidence of what the agent checked.

Metrics

readMetrics reads the session’s own stored observations. summary picks tools, models, turns, agents, hooks, or sessions. Rows come slowest first.

MCP and custom tools

MCP servers add their tools next to these. An embedded runtime can add Go handlers with Options.Tools.