Skip to content

Tools the app gives agents

The app gives every agent it starts a set of tools of its own, alongside the runtime's tools, on every runtime (see Runtimes). This page lists them all, in the order an agent sees them. Every runtime takes them over a local http address the app serves on this computer only, with a key only that agent's session holds; the key stops working when the session ends. Copilot uses its own follow-up suggestions instead of the app's.

The last column says whether you are asked before the tool runs. Where it says the app answers, the runtime's permission question is answered by the app and you do not see it. Where it says the runtime decides, you get the same permission card as for any other tool if the runtime asks; Claude and Cursor ask, and Copilot asks before every tool call.

There's no tool for ending a turn. The app works out how each one ended: Complete, or Waiting on your answer when a question card is open or the agent's last words ask one, with the first sentence of its last message under its name (the question, when it waits on one). A turn that stopped short (cancelled, refused, out of tokens, failed) shows how it stopped instead. The conversation's name comes from the runtime, or from your first prompt when the runtime sends none. An agent that needs you asks, with its own question tool or ask_form. finish_turn was removed; a conversation that began before then can still call it, and what it says is kept.

Tool What it does Asks the person first?
show_file Opens a file in the files pane beside the conversation, at a line. A Markdown file opens as a page that follows the agent's edits; an HTML file opens rendered, with scripts and the network off (see Look at an HTML page). The file must be inside the folders the agent was given. If you are reading another conversation, it waits until you open this one. No. The app answers.
manage_workflows Lists, reads, writes and removes this project's workflows, and turns them off and on. A workflow an agent writes or changes appears on the project page straight away, waiting for your OK: it does not run until you click Approve, and you can archive it instead. A new one an agent writes also starts turned off, and its page says Off: written by an agent until you turn it on. An agent can turn any workflow off, but can turn back on only one an agent turned off: one you turned off, one an agent wrote, and one whose file says enabled: false for any other reason stay off until you turn them on. Off and archived are lines in the workflow's own file (enabled: false, archived: true), so turning one off writes that file; an agent's rewrite of a workflow keeps whatever those lines said. A project may have at most three workflows waiting for your OK; an agent writing a fourth is refused until you approve or remove one. Approved ones don't count. See Workflow triggers and actions and its limits. No. The app answers.
ask_form Asks you a question or a short form and waits for your answer. Reaches you on the Mac or on your phone. Used when the runtime has no working ask tool of its own, or when that tool never reaches the model. No. The app answers.
start_session Starts another session in this project with a prompt of its own, marked as started by this session. It can choose the runtime, model, a permission mode no looser than its own, and whether to work in the project folder, a new worktree, an existing worktree or a branch. If the project would go over either of its two helper limits, how many may be running and how many may exist not yet archived (3 and 5 unless you set them in Project Settings ▸ General), the session is queued instead, and the answer says which limit, names the sessions holding it and gives its place in the queue. A queued session runs nothing until a running place and a not-archived place are both free, behind working and waiting agents, and then starts by itself, oldest first; it shows under Waiting as Queued, 1st, Queued, 2nd and so on, and survives a restart. Past the third limit, how many may be queued (5 unless you set it), the start is refused, naming the limits and sessions. A runtime that can't take an agent on this Mac (not installed, not signed in, or out of the pool on the Agent Runtimes page) is refused before anything starts, with the reason and the runtimes that can; so is a model the runtime doesn't offer, naming the ones it does. With no runtime named, it starts on Claude, which is checked the same way. The runtime decides.
stop_session Stops a session this agent started, or one below it, as your Stop would. That frees its running place; it keeps its not-archived place until it is archived. A queued one is taken off the queue and never starts; so is one you or the agent archives. The runtime decides.
archive_session With no id, archives the agent's own session once its turn ends, if the turn ends Complete, Nothing to do or Partly done; an ending that asks you something else (a question, stuck, blocked) drops it, and so does anything you send first. Where it needs your approval, the session then carries an Archiving needs approval mark and is listed in Needs You, with a card at the end of its chat, until you click Approve (see Statuses and groups). A workflow's run its workflow lets archive itself (when-done: archive-allowed or archive, see When a run is done), or a session started by another in a project where sessions may archive the sessions they started, is archived without your approval, if the turn ends Complete or Nothing to do. It goes with move_worktree: the agent moves, and stays there waiting for approval instead of being started again. With an id, for a session this agent started or one below it, once its work is merged or abandoned: where Sessions may archive the sessions they started is on in Project Settings ▸ General (on unless you turn it off), it is archived now, as your Archive would, or when its turn ends if it is still working (if that turn ends Complete or Nothing to do; otherwise it waits for your approval). Its conversation says which agent archived it, agent.archived says by another agent, and you can bring it back from Archived. Where the switch is off, it waits for you to approve archiving it. Either way its running place is freed once its turn has ended; it keeps its not-archived place until it is archived. Refused, in words, for your own sessions, a workflow's, and sessions not below this agent. The runtime decides.
move_worktree Moves the agent once its turn ends. On Claude, Copilot, Cursor and Codex only: the runtimes that can carry the conversation into another folder. worktree names a new worktree of the project or gives the path of one that exists, and leave_worktree (keep or remove) goes back to the project folder. Neither takes back a move it asked for. The agent is started again there to carry on, unless it also asked to be archived. A move doesn't go with a wait or with Waiting on your answer. Nothing uncommitted comes along. Removing takes the branch too when the app made it and it is merged; an unmerged branch is kept with its commits, so a lane can remove its worktree as soon as its work is committed. Removing is refused for a worktree the app did not make, another agent works in, or that is detached or whose branch is gone (its commits would be on no branch), and, unless the agent says to discard, when anything in it is uncommitted. The refusal names the files. The runtime decides.
set_session_labels Adds or removes labels the agent owns on its own session, at once. It cannot remove or claim one of yours. The runtime decides.
list_sessions Lists the sessions in this project, most recent first, its own included: each one's id, title, runtime, status, worktree and branch, the resources it holds, and what it last said. Nothing from another project. With started_by: me, it lists only the sessions this agent started, and the ones below them, that are not archived (one it did not start itself says who did), what each is doing and last said, after how many of the project's running and not-archived places are in use, such as "2 of 3 running, 4 of 5 not archived", with ", 2 of 5 queued" once any are. A queued one says queued (position 1). It ends with the runtimes start_session can start one on here, as of that moment, each with its model where this project has used it, and why each of the others can't. No. The app answers.
read_session Reads one session in this project, by its id or exact title: what you asked, what the agent said, the tools it ran and the files they touched, what it said of how the work went, and its plan as it last stood. A long one keeps the first request and the latest turns and says how many were left out. Reading it changes nothing. A title used twice, a deleted session, or one not in this project is refused in words. Used when you ask an agent to continue another session's work. No. The app answers.
message_session Sends words to another session in this project, by its id or exact title. It reads them as a prompt marked as the sender's, and its chat shows them as "From" that agent on the Mac, the Remote and the web. A session that is working reads it after its turn; one that is done is woken by it, yours included, within the project's running limit for sessions started by sessions; one that is stopped, or one waiting on your answer, is not woken: the message waits in its chat for you. It never answers a question or permission card. Limits: 4,000 characters, 30 messages an hour per sender, and at most 3 messages between agents in a row with no prompt from you; your next prompt starts the count again. Raises agent.messaged. No. The app answers.
lease_resource Takes a turn with something only one agent should use at a time: a simulator, a browser, the screen, or anything it names. Waits up to 45 seconds if someone else holds it, then keeps the agent's place in line. A lease lasts 30 minutes unless the agent asks for up to 240 (or the declared resource's own lengths), and calling it again extends it. A declared resource may allow more than one holder at once. The runtime decides.
release_resource Gives back a lease, or leaves the line for one. The runtime decides.
list_resources Lists what can be leased on this Mac, and who holds or is waiting for what. Resources declared in Settings ▸ Resources come first, with their descriptions, even when free; the agent is told to lease one whenever its description applies. The runtime decides.
wait_for_event Waits until something happens in this project or on this Mac, such as agent.finished, branch.moved, or mac.wake, optionally narrowed by a filter: branch on branch.moved or why on person.away and person.back (one value, or a list meaning any of them, such as {"branch": ["main", "develop"]}; checked against the event's inputSchema with the same checker as an MCP server's event's, so any other key, or a value a filter cannot have, is refused in the same words, naming what it takes) and with a time limit, until_minutes, of 1 minute to 24 hours, which every wait needs: one without it is refused, so no wait can last for ever. The call waits up to 45 s; after that the agent can end its turn, which costs nothing, and it is started again when the event happens or the time runs out. One wait per agent; a new one replaces the old. Also lists recent events, and with action list every event it can wait for in one list: the app's, then the project's MCP servers', each a line of JSON in events/list's shape (name, source, description, inputSchema, payloadSchema). A woken agent's details are named as the payloadSchema names them. Named agents instead of events, by id or exact title, it is a block: the agent's turn ends at once, it shows as Blocked, and it is started again, told how each one ended, once every one has finished, or the first with wake_on: any, when it is told which are still running. until_minutes is needed here too: with agents, or on its own, it starts it again then anyway, to check on something the app can't see, like a CI run, or a helper still running, which it can wait on again; message is what its row says meanwhile. See Events. The runtime decides.
cancel_wait Stops the agent's wait, so nothing starts it again for it. The runtime decides.
list_workspaces Lists the machines the control plane's hosts run on, from every workspace provider: each workspace's state, the host it is linked to and that host's state, and, for a provider that can make workspaces, the choices a new one takes. Never a provider's secrets. On a host that isn't on a control plane, it says there are none. See Start workspaces from Agents. The runtime decides.
start_workspace Starts the workspace a host runs on, by the host's name. It answers at once; the host is up when it connects, which the agent can wait for with wait_for_event on server.online. The runtime decides.
stop_workspace Stops the workspace a host runs on, and every agent there with it. While agents are working there it is refused, naming them, unless the agent says confirm_running. The runtime decides.
make_workspace Makes a new workspace at a provider that can, with its choices; it joins as a host of the same name. It may cost money while it runs. Yes, always. A question card on every client, and nothing is made without your Make it.
delete_workspace Deletes the workspace a host runs on, with everything on its disk, and removes the host with its agents. Yes, always. A question card on every client, and nothing is deleted without your Delete it.

set_session_labels adds or removes labels owned by the agent. start_session can give the new session up to five labels, which it owns from its first moment. Labels are unique within a session without regard to case. An agent cannot remove or claim a person-owned label; the whole call is refused if it tries. See Label a session.

start_session, stop_session, archive_session and list_sessions with started_by: me are given to every agent, including one another agent started (#940). The project's helper limits are the bound: they count every session an agent started, whoever started it. An agent can stop, archive and list the sessions it started and every session below them (the sessions those started, and so on), never your sessions, a workflow's, or another agent's. Each session keeps its direct starter, so the chain shows who started whom. Archiving or stopping an agent leaves the sessions it started working; every agent above it, and you, can still stop or archive them. Every agent is told, once at the start, to ask to archive its own session in its last turn, once its work is merged or abandoned and cleaned up (#703).

Before #638 these were start_agent, stop_agent, request_archive, archive_agent, list_my_agents and message_agent (and park_agent before request_archive). They are no longer offered or answered; a conversation that called them still shows those calls as the app's own.

A session started by another counts as running while it is working, waiting on a question or permission, starting, or waiting to carry on by itself: blocked on other agents or a time, waiting on events, or waiting for an allowance. Finished, stopped and archived helpers don't, nor does one waiting for archive approval. So a lead that stops a helper whose part is done, or archives it, frees a running place once its turn has ended; the helper's not-archived place stays taken until it is archived. A lead should archive a helper once its work is merged or abandoned, rather than remove the helper's worktree under it; archiving removes a worktree the app made for it once everything in it is committed. Both limits are yours alone to change: the tools only read them. They are kept in the project's .agents/project.json; a value written there by hand is held to the maximums. list_sessions, read_session and message_session are given to every agent, including one another agent started.

The five workspace tools are given to every agent. The control plane does what they ask as it would for you, and its log names the agent that asked. Agents reach providers only through the control plane, never directly.

The writer's tools

The agent that writes a provider's map at Add Provider (#858) has these seven tools and no others, of the app's or of its runtime's. No other agent has them. The control plane answers each one, with every secret's value replaced by ${NAME}.

Tool What it does Asks you first?
read_tools The MCP server's tools: names, descriptions, input schemas and annotations. No.
read_help ‹cli› ‹words…› --help, for at most three subcommands that the help printed. No.
check_draft Checks a map or config as Add does, with one list. Only when the list may change something: Run Check.
prove_start, prove_stop Starts or stops one workspace from the last list with the draft. Yes, always, in the sheet.
send_draft The result, with a note of up to three lines. No.
give_up Ends with a reason. No.

See also