A person's controls
Agents do the work; some decisions stay a person's. This page is where those decisions live: what is waiting on you, how to answer an agent, and the controls on a card that only a person can use.
That last part is deliberate. Every control below is recorded on the plan with who and when, and none of them has an MCP tool. An agent that could approve its own issue, turn on auto-merge for its own PR, jump its own node up the queue or decide its own review's findings would make each of those a formality. Plan authoring over MCP cannot reach them either: none is part of a plan's YAML except the merge policy, and add_plan_node / change_plan_node / import_plan refuse to turn that one on.
Who you are
Stoat has no sign-in. Every control on this page records a name: the one in the topbar's You field, kept in this browser. Set it once; until you do, what you do is recorded as stoat-ui.
On its own machine that is all there is to it. On a server other machines reach (Stoat Team), anyone who can open the page can use every control here: there are no accounts or per-person permissions, and the name recorded is whatever that person's browser says. Keep a team server where only the team can reach it.
What is waiting on you
Three places say it, and they read the same list, so they never disagree.
- The top bar, on every page: a waiting on you count. Questions come first, since an agent is stopped on each, then go-aheads, fixes, merges and reviews. Clicking a question opens the chat below.
- The ready board's "needs a human" strip (the landing page): agents blocked on a permission prompt (from the hook sidecars), questions an agent left in its final message, stalled claims (alive, idle and holding a node), PRs open under
manual-review, and the plan runner's callouts: afixit could not get its agent to make, amergeit held,main-red, adriftconflict, acloudnode waiting for a launch, a give-up. - Notifications, when configured: a desktop notification or a webhook for the callout kinds you name. On a Mac a desktop notification for each question is on by default. See Configuration.
A usage-limit callout is shown and never counted: it is information, and the runner resumes those agents itself at the reset (Usage limits).
Where an agent of the runner ran the node, the row carries the way back into its context: cd <worktree> && claude --resume <session>, with a copy button. A stalled or waiting agent never gets one: it is still running, and resuming it would put a second process on the same session.
Answering an agent
An agent that needs a person asks with ask_person and parks until it is answered: up to four hours by default, its lease renewed while it waits. It says what it would do if nobody answers (recommended), which the chat shows as its default. If the wait times out, the question stays open and says so (⏱ it stopped waiting); the agent is told to park on it again with its questionId, and only if it truly cannot wait, to go with its recommended option and say so, never quietly with the smallest one. A question never changes the node's status, and it dies with the claim.
Clicking a question opens a chat with that agent: the question with its options and default, the agent's last report and output, every question and answer on the node so far, and a reply box. The reply goes where the question waits (POST /api/plans/{slug}/nodes/{id}/conversation):
- An agent parked in
ask_persongets it on its claim and carries on at once. - An agent that exited with a question in its final message (a paragraph starting
Question for a person:, which the runner raises as aquestioncallout) is resumed by the plan runner, in its own session, worktree and claim, with your answer as its next prompt. The callout clears as the resume starts, the chat shows the agent's log while it works and its final message as its reply, and the answer is kept on the plan's Activity. A runner whose launcher cannot resume (codex, gemini), or a node with an agent already on it, refuses, and the callout stays. Until then the runner holds the node rather than retrying it; dismiss on the runner panel lets it go. - A cloud agent asks through
ask_personor its REST twin like any other, so it is the first case.
The card's ? answer answers a parked question in place, and so does the node's zoomed-in view.
A lead agent
A plan run in practice often has a supervising session working with the person. Stoat makes that role explicit: an agent takes the lead of a plan with lead_plan, and is then the first responder for its workers' questions marked needs: agent. It parks on them with await_questions, answers with answer_question, or hands one to you with escalate_question, after which it is yours for good. A question left unmarked goes to the lead while one is alive, else to a person.
- The lead is never the authority. A question marked
personis never answerable over MCP, by the lead or anyone, and the lead holds none of the controls below. - Stoat decides whether the lead is alive from what it observes of the lead's session, not from anything the lead reports. A lead whose session is gone leaves no question unrouted: everything it held is a person's at once.
- The plan header shows the lead, and its × clears it (
DELETE /api/plans/{slug}/lead), alive or not. Only one lead at a time, and taking the lead is refused while another lead's session is alive. - The lead may relay your answer to an exited worker's question (
answer_questionwith noquestionId, naming you inrelayFor); the runner resumes the worker with it as above.
Stoat routes to the lead and never depends on it, and never launches one.
The controls on a card
| Control | What it does | More |
|---|---|---|
| approve for agents | The go-ahead: the plan runner claims no issue node without one. Cleared when the node changes or is rebound, since it covered what you saw. | Issue nodes |
| approve all (n) / withdraw all | The same, for every card in a board column that can take one, after a confirm naming each card. A card that went done, lost its binding or was approved meanwhile is skipped and named. | |
| ◉ review / ⇢ auto-merge | The merge policy pill: manual-review or merge-on-green, where the runner merges the PR itself once its CI is green. Asks before turning review off; keeps the go-ahead. | The merge |
| ⇡ expedite | Launch this node next, ahead of leverage. Changes the order only. | Expediting |
| ☁ | Keep the node for a cloud agent: the runner never takes a local slot for it. | Cloud agents |
| allow asserted | Let an agent's report_gate_result decide this gate. Cleared when the node changes. | Test-run gates |
| ⟲ re-verify | Make a done gate's earlier passes stop counting, so it runs again. | Gates that re-arm |
| + note | A person's note on the plan or a node. The card shows the latest as ✍, every note is a line of the Activity, and nothing derives from it. | |
| ↻ restart | On the runner panel: stop a running agent, release its claim and launch the node from a fresh attempt. | Steering |
| Start / Pause | The resident runner's panel. Pause stops new claims and nothing else. | Steering |
None of them is exported, apart from the merge policy (merge:), which is part of the node. An expedite and a cloud mark survive a change to the node and are dropped by a rebind; the go-ahead is cleared by either, and the asserted-results grant by a change.
Editing the plan from its page
+ node and a card's ✎ add, change, remove and rewire a plan's own nodes through the same commands the MCP tools send. The preview says what the save does to the run before it happens:
- A change to a node's own fields replaces it and so clears its go-ahead and asserted-results grant; the preview warns first. A rewire is sent as link/unlink and a new number as a bind, which clear nothing.
- "Needed by" links other nodes to this one: a new node that four waiting gates must depend on is one edit, not four.
- Removing a node first unlinks the plan's own nodes that depend on it, after a confirm naming them.
- A node's brief is Markdown instructions for whoever works it, on any kind; the runner puts it in the agent's prompt. A new brief is a change, and clears the go-ahead, on purpose.
Deciding a review
A review node is launched by run-plan with a prompt to review the plan's integration branch as a whole and change nothing. The reviewer submits its findings (submit_review), each a title, a brief and optionally a severity and steps. Each finding is then yours:
- Accept it: a fix node (a test-run gate by default, titled and briefed by the finding; edit it first if you like) is added to the plan, and the review is linked to depend on it, so whatever comes after the review waits for the fix too.
- Reject it, with a reason.
- A review that found nothing is done only when you sign it off.
The review reads waiting (nothing submitted; launchable), then findings (yours to decide; not ready), then fixing (accepted fix nodes not done), then done. The card's findings button opens them.
Archiving and purging
Archiving takes a plan out of the active set and keeps its stream: its history, and everything it ever said. Purging (the plans page's archived list) deletes an archived plan for good, with its claims and publish baselines, after writing its YAML to Stoat:PurgedPath (~/.stoat/purged/{slug}-{timestamp}.yaml); importing that file is the only way back. It is refused while an active plan depends on one of its nodes, and the plans directory never brings a purged plan back from its file. See POST /api/plans/{slug}/purge.
See also
- Plans and nodes — the card, the zoomed-in node, and what a status means
- The chapter runner — what the runner does with each of these decisions
- REST API — the routes behind the buttons