What the painters were given

Tools the painter could call

19 tools, as listed to the model with its system prompt

Given to 1 painter:

read

Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp). Images are sent as attachments. For text files, output is truncated to 2000 lines or 50KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.

parametertypewhat it is
path *stringPath to the file to read (relative or absolute)
offsetnumberLine number to start reading from (1-indexed)
limitnumberMaximum number of lines to read

bash

Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last 2000 lines or 50KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.

parametertypewhat it is
command *stringShell command to execute
timeoutnumberTimeout in seconds (optional, no default timeout)

edit

Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes.

parametertypewhat it is
path *stringPath to the file to edit (relative or absolute)
edits *arrayOne or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.

write

Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.

parametertypewhat it is
path *stringPath to the file to write (relative or absolute)
content *stringContent to write to the file

subagent

Spawn a sub-[local account redacted] in a dedicated terminal herdr pane. For Pi-backed OpenAI or OpenAI-Codex subagents, set fast: true to opt into service_tier: "priority" (fast mode). Omit fast or set it to false to force the standard service_tier: "default". This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. When the sub-[local account redacted] finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT call subagents_list or any other tool to 'check' status. All of that is wasted work — the harness handles delivery for you. DO NOT fabricate, assume, or summarize results after calling this tool. After spawning, either end your turn immediately, or work on other independent tasks (including spawning more subagents in parallel). The harness will wake you with the result when it is ready.

parametertypewhat it is
name *stringDisplay name for the subagent
task *stringTask/prompt for the sub-[local account redacted]
[local account redacted]string[local account redacted] name to load defaults from the available named subagent catalog. [local account redacted] frontmatter can provide model, thinking, tools, skills, and role instructions.
systemPromptstringAppended to system prompt (role instructions)
modelstringExact authenticated provider/model-id. Omit to use a named [local account redacted]'s model default, then the configured or parent model. Passing a value explicitly overrides [local account redacted] frontmatter for this spawn.
fastbooleanOpt into OpenAI priority processing for this Pi-backed subagent. Set true for service_tier: "priority". Omit or set false to force the standard service_tier: "default". Ignored by non-Pi or non-OpenAI runtimes.
thinkingPi thinking level. Omit to use a named [local account redacted]'s thinking default, then the parent level. Passing a value explicitly overrides [local account redacted] frontmatter for this spawn.
skillsstringComma-separated skills (overrides [local account redacted] default)
toolsstringComma-separated tools (overrides [local account redacted] default)
cwdstringWorking directory for the sub-[local account redacted]. The [local account redacted] starts in this folder and picks up its local .pi/ config, CLAUDE.md, skills, and extensions. Use for role-specific subfolders.
forkbooleanForce the full-context fork mode for this spawn. The sub-[local account redacted] inherits the current session conversation, overriding any [local account redacted] frontmatter session-mode.
interactivebooleanMark the subagent as interactive (long-running, user drives the conversation in its own pane). When true, the main session is not woken by status transitions (stalled/recovered) for this subagent. If omitted, falls back to the [local account redacted]'s `interactive` frontmatter, otherwise the inverse of `auto-exit` (agents that auto-exit are autonomous and get stall pings; agents that don't are interactive and stay quiet).
resumeSessionIdstringResume a previous Claude Code session by its ID. Loads the conversation history and continues where it left off. The session ID is returned in details of every claude tool call. Use this to retry cancelled runs or ask follow-up questions.

subagent_interrupt

Send Escape to the active turn of a currently running Pi-backed subagent. The child pane, session, watcher, and running entry remain alive; this returns only a local acknowledgement and does not emit a subagent_result solely because of this request.

parametertypewhat it is
idstringExact running subagent id
namestringExact running subagent display name

subagents_list

List all available subagent definitions. Scans project-local .pi/agents/ and global [local path redacted] Project-local agents override global ones with the same name.

subagent_resume

Resume a previous sub-[local account redacted] session in a new herdr pane. For Pi-backed OpenAI or OpenAI-Codex subagents, set fast: true to opt into service_tier: "priority" (fast mode). Omit fast or set it to false to force the standard service_tier: "default". This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. When the resumed sub-[local account redacted] finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT poll for status. All of that is wasted work — the harness handles delivery for you. DO NOT fabricate or assume results. After resuming, either end your turn or work on other independent tasks; the harness will wake you when the result is ready. Use when a sub-[local account redacted] was cancelled or needs follow-up work.

parametertypewhat it is
sessionPath *stringPath to the session .jsonl file to resume
namestringDisplay name for the terminal tab. Default: 'Resume'
messagestringOptional message to send after resuming (e.g. follow-up instructions)
autoExitbooleanWhether the resumed session should automatically exit after completing its response. Defaults to true for autonomous follow-up work; set false for interactive resumed sessions.
fastbooleanOpt into OpenAI priority processing for this resumed Pi session. Set true for service_tier: "priority". Omit or set false to force the standard service_tier: "default".

caller_ping

Send a help request to the parent [local account redacted] and exit this session. The parent will be notified with your message and can resume this session with a response. Use when you're stuck, need clarification, or need the parent to take action.

parametertypewhat it is
message *stringWhat you need help with

subagent_done

Call this tool when you have completed your task. It will close this session and return your results to the main session. Your LAST assistant message before calling this becomes the summary returned to the caller.

todo

Manage a task list for tracking multi-step progress. Actions: create (new task), update (change status/fields/dependencies), list (all tasks, optionally filtered by status), get (single task details), delete (tombstone), clear (reset all). Status: pending → in_progress → completed, plus deleted tombstone. Use this to plan and track multi-step work like research, design, and implementation.

parametertypewhat it is
action *string
subjectstringTask subject line (required for create)
descriptionstringLong-form task description
activeFormstringPresent-continuous spinner label shown while status is in_progress (e.g. 'writing tests')
statusstringSet this task's status (update): one of pending, in_progress, completed, deleted. When action is list, filters returned tasks by this status.
blockedByarrayInitial blockedBy ids (create only)
addBlockedByarrayTask ids to add to blockedBy (update only, additive merge)
removeBlockedByarrayTask ids to remove from blockedBy (update only, additive merge)
ownerstring[local account redacted]/owner assigned to this task
metadataobjectArbitrary metadata; pass null value for a key to delete that key on update
idnumberTask id (required for update, get, delete)
includeDeletedbooleanIf true, list action returns deleted (tombstoned) tasks as well. Default: false.

Search the web using the current supported provider (Google Gemini, OpenAI, or Anthropic). Optionally include URLs to analyze alongside search results.

parametertypewhat it is
query *stringThe search query or question to answer
urlsarrayAdditional URLs to analyze along with search (up to 20)

url_context

Analyze the content of up to 20 public URLs using Gemini URL Context. Supports web pages, documents, images, and YouTube videos.

parametertypewhat it is
query *stringQuestion or task to perform on the URLs
urls *arrayPublic URLs to analyze (web pages, documents, images, YouTube videos, etc).

bg_start

Start a task asynchronously only when background execution is genuinely needed: for concurrent work, later interaction, or an explicit user request. Its unique name can immediately reference ordered follow-up bg_* calls in the same assistant response.

parametertypewhat it is
name *stringA short unique name for the task (case-insensitive among retained tasks)
command *stringThe shell command to run
cwdstringWorking directory (defaults to current)
ptybooleanRun in a pseudoterminal for interactive/TUI programs (default: false)
colsnumberInitial PTY columns (default: current terminal or 120)
rowsnumberInitial PTY rows (default: current terminal or 30)

bg_wait

Wait for a finite task to finish or time out and include its latest pipe log line when available. Use bg_logs for full pipe output or PTY terminal output.

parametertypewhat it is
id *stringTask ID or unique name (case-insensitive)
timeoutnumberMaximum seconds to wait (default: 300)

bg_status

Inspect task status and metadata or list current tasks, including each task's latest pipe log line when available. This is not a polling or waiting tool and does not return full or PTY output.

parametertypewhat it is
idstringTask ID or unique name. If omitted, lists all retained tasks.

bg_logs

Read retained pipe or PTY output when the latest pipe line returned by bg_wait or bg_status is insufficient. Place bg_logs after bg_wait in the same response when fuller final output is needed.

parametertypewhat it is
id *stringTask ID or unique name (case-insensitive)
tailnumberRead last N lines (default: 100)
streamstringWhich stream (default: 'both'); use terminal for explicit PTY output
from_linenumberStart from this line (0-indexed). Overrides tail.
max_linesnumberMax lines with from_line (default: 500)

bg_send

Send text and terminal keys to a running task, or signal a running/disconnected adapter-owned task.

parametertypewhat it is
id *stringTask ID or unique name (case-insensitive)
inputstringExact text; terminal keys must use <...> tokens, for example y<Enter>, <A-f>, or <C-d>
signalstringNamed signal validated against the task's local or adapter execution environment

bg_kill

Terminate a running or disconnected background task and report the result. Sends SIGTERM by default or SIGKILL with force=true; does not return process output.

parametertypewhat it is
id *stringTask ID or unique name (case-insensitive)
forcebooleanSend SIGKILL instead of SIGTERM (default: false)

* required

Source