What it can do

The tools the model is given, what each is good for, and the rules it has to follow to use them.

Every tool is offered to the model under a PascalCase name — Read, ListDirectory, SpawnAgent — and those are the names in the tables below and in the log. The dispatch additionally answers to a snake_case spelling of most of them (read_file, list_directory, request_permission) and to two names from other tool sets, Bash for Exec and multi_edit for Edit, so a model reaching for a habit rather than for the list still lands on the right tool instead of an error. Nothing advertises those aliases; they exist to absorb a mistake, not to be used.

Consecutive read-only calls — Read, Grep, Glob, ListDirectory, WebFetch, WebSearch, Skill — run together in one pass; anything that writes stays sequential and acts as a barrier for the calls around it, and results always come back in the order they were asked for.

Reading and searching

SearchSessions is the uncurated memory underneath the memory files: the session logs are kept anyway, and they hold what was tried here last week, which command failed and how, and what you said about a file. It is a linear read of the session files whose name carries this working directory, so a session can never see what a session in another repository said, and it needs no permission rule because it reads nothing under the sandbox root. A Role::User line in a session file is not the same thing as a line you typed — it may be a compaction preamble, a heartbeat, a scheduled wake, or a message from another agent — so each of those is marked as what it is. A match is a memory of what was said then rather than proof that it is still true.

Grep answers with the list of matching files by default, which is the cheap answer to "where is this". output_mode switches it to content for the lines themselves — with -n for line numbers and -A, -B, -C for context — or to count for hits per file. It can be narrowed by glob or by type (rust, py, ts, and so on, an unknown name taken as a bare file extension), matched case-insensitively with -i, spread across line breaks with multiline, and cut short with head_limit.

Writing

A file has to have been read before Edit or an overwriting Write touches it, and it has to be read again once it changed on disk underneath — the model cannot replace text it has never seen. What counts as changed is a hash of the contents rather than the modification time, because two writes within the same second are ordinary for an agent and a one-second timestamp would miss them.

Running commands

Exec takes typed fields rather than a command line: program, arguments as an array of strings, sudo, and a timeout in milliseconds. There is no shell — no &&, no $(), no redirects, and nothing to smuggle through quoting. A pipeline is written as a stages list instead: a | b becomes two stages, each resolved against the permission engine on its own, and the stdout of one stage is piped into the stdin of the next inside the program, never through a shell. A stage that is denied cancels the whole pipeline and names the stage. Output is truncated when it is long, and a command that runs past its timeout is stopped. The same path is reachable from the chat as /execute, so you and the model share one vocabulary. Under all of it a kernel sandbox limits what an allowed program may write to the working directory, /tmp, the toolchain caches and the granted files; the permissions page says which backend does it and what stays outside its reach.

Reaching outside the project

Both reach outside the sandbox by design: the sandbox governs which files the agent may touch, not whether it may read the public web.

Keeping track of itself

Asking you something

Skills

Skill opens an installed skill by name and returns its full text, so the model can follow a skill it recognizes from the list in its system prompt rather than asking you to run the slash command. It takes a name and never a path, searches the same directories the list came from, and an optional file reaches that skill's own references/, scripts/, and assets/ entries, checked for containment. See Skills and packages.

Handing work to another agent

SpawnAgent gives a self-contained subtask to a child agent with the same tools, the same working directory and the same permission rules, but a conversation of its own. The child works until it can answer, and its final message is the entire tool result — the twenty files it read never enter your conversation, which is the point of it. A model argument picks a cheaper model for wide, dull searches; without it the child runs on the same model. A child cannot spawn children, it stops after twelve steps, and Esc interrupts it along with the turn that started it. Its tokens count as the session's, because it is the session's bill.

A spec argument names a role instead of describing it. A file under subagents/ beside the memory directories holds the standing instructions of a role — a reviewer, a counter, a release checker — and SpawnAgent with spec gives the child those instructions and treats the prompt as the task they apply to. Only one line per spec reaches the model's prompt, the name and its first line of purpose, so a shelf full of roles costs almost nothing to keep. /refine can write one from a delegation that worked, and because a spec is a memory scope it is snapshotted and reversible like every other memory file. A spec naming nothing is an error rather than a plain spawn: a child with no instructions answers anyway, which is exactly why that mistake has to be loud.

A fork argument starts the child from this conversation instead of from nothing. It inherits every completed turn above as its own history and the prompt becomes the next message in it, which is what makes “check what I just did” a sentence rather than a retelling. The inheritance is close to free: the request the fork sends opens with the same system block, the same tools and the same messages the parent just sent, so the provider answers it out of the cache it already holds and the fork pays only for its own work. The cut is a turn boundary, the same rule compaction follows, so a fork never begins between a tool call and its result; a conversation with no completed turn yet is an error rather than a child that quietly starts empty. What it inherits is context and never authority — permissions, file grants and the voice at the prompt work exactly as they do for any child, a background fork is refused a prompt like any background child, and its history stays its own: nothing the fork does is written back into the conversation it came from.

A child's tool calls appear in the log indented and dimmed, so you can see what it is doing without it being mistaken for the main conversation.

Running a script

RunScript runs a revolve-script program: a markdown document whose list items are commands and whose block quotes are the prompts those commands send. Its each puts one agent on every element of a list, and the answers stay inside the interpreter — you get back only what a show line reports. A script that reviews forty files and shows the count of failures costs the conversation one number instead of forty reviews. Children run in parallel, so a fan-out over fourteen files takes about as long as the slowest one.

Its glob, read, and save go through the same sandboxed file layer as the tools, and its ask through SpawnAgent, so a script reaches exactly what the agent may reach and nothing more.

Names outlive the call. Everything a script binds stays in the session's environment, and the tool result lists what is being held — the name, its type, its size, never its content — so a later script starts from those names instead of reading the same material again. The environment lives in the process, so a resumed session starts with none.

See The script language for every command, its argument order, and a worked example run against this project's own source.

Talking to another running session

ListAgents reports the detached sessions answering their socket right now: name, model, whether one is mid-turn, and the directory it works in. SendAgentMessage addresses one of those names. Without wait_seconds the call returns as soon as the message is delivered and any answer comes back later as a message of its own, so nothing can hang. With wait_seconds it blocks until the receiving agent finishes the turn the message started and hands back what it wrote, which is what a session with no socket of its own needs. The receiving side is told which of the two it is, so an agent being waited on answers in its final message instead of sending one that arrives after the waiting stopped.

StartAgent is how the model gets a peer rather than a child: it starts another agent as its own process, with the task as its first message. That agent outlives the turn that started it, keeps its own conversation and its own token bill, and answers to its name from then on — unlike SpawnAgent, whose child lives inside the turn. A directory other than this one becomes a sandbox this session cannot reach, so you are asked before anything is started and a refusal starts nothing; a worktree instead puts the new agent in .worktrees/<branch> of this same repository, which needs no approval because it never leaves it, and cleanup says how such a one-shot worker ends itself once its report is sent — delete frees the session, compact keeps it addressable and condenses its history. A role names a subagents/ document the new agent carries in its own system prompt, and an every gives it a cron line, which is how work that recurs gets a home that is not your conversation.

StopAgent ends a running agent by name, session and process. It is for one that is done, went down the wrong road, or is stuck in a turn nobody is reading. It stops a process rather than anything on disk — the history stays and the session can be started again — and it cannot stop the session it is called from. A message sent to an agent that is about to be stopped is wasted: it wakes that agent into a turn the stop then ends.

Tools that appear only sometimes

EditorInfo — which documents are open, which pane is focused, what is selected — exists only when revolve is embedded in a program that answers it. The standalone binary's tool list does not have it. Tools from configured MCP servers join the list under <server>__<tool>, so two servers may each expose a search without colliding.

Every tool, as the model sees it

The table below is rendered from the tool definitions themselves rather than written beside them: the sentence is the one the model is given, and the arguments are the ones the schema declares, with their types and whether they have to be passed. A test regenerates it and fails when the committed file differs, so it cannot describe a tool the program no longer offers. Tools from MCP servers and the extension tools of a project join the list at runtime and stand in no table here.

Turn budgets

A turn runs under a ceiling on three things: how many tool rounds it may take, how many output tokens it may spend, and how long it may run. The defaults — 300 rounds, a million output tokens, an hour — exist to catch a runaway loop and never fire in ordinary use. A tight budget is worth setting for a scripted run, which is what --budget rounds=8,seconds=120 is for; every key is optional and 0 turns that limit off.

The tokens a child agent spends count against the turn that spawned it. A fan-out of fourteen children can outspend its parent by an order of magnitude, so a ceiling counting only the parent's own tokens would not be a ceiling.

Two things happen as a budget runs low. The model is told in that round's tool results how much is left and that the turn will stop where it stands, so it can summarize rather than find out by being cut off. And when a budget is tight to begin with, the system prompt states all three ceilings and AgentInfo reports what has been spent.

A limit ends the turn after the round that reached it, never between a tool call and its result, and both you and the model are told which limit it was — in those words, because a stop that reads like a completion is a lie about the work. Reaching a limit says nothing about whether the task succeeded. The conversation stays usable: the history is valid, the session resumes, and the next message continues where the turn stopped.