Control Protocol

Verbs: The Inbox, the queue and review

Verbs: The Inbox, the queue and review: part of the Control Protocol of TUIOS.

This page is one part of docs/protocol.md of the tuios repository. The Control Protocol page lists every part.

review-diff

What the agent in a pane changed. The pane is window (default the focused one) of session, and the repository is the session's worktree when the pane is in it, else the repository holding the pane's directory; none is not_repo, and so is a pane whose process runs on another machine. The working state, committed or not, untracked files included and ignored files left out, is written as a git tree through a temporary copy of the worktree's index, so its index, its files and what the agent staged are not changed. An untracked file larger than [agents.checkpoints] max_untracked_mb is left out of the tree and never read; it is listed with status U, skipped true and no counts or hunks. Every git call of one diff together is bounded at 10 seconds (git_failed past it). AGENT_STATE.md has the whole contract.

Params: session, window, base (a ref; omit for the worktree's recorded base, else the merge base with the upstream, else HEAD), against (another session of the same fan: the two attempts diffed with each other; not with base or uncommitted), uncommitted (only what is not committed, against HEAD), paths (at most 256, relative, each taken literally), context (0 to 20, default 3), index (unstaged or staged; see below). A base that does not resolve, or reads as an option, is invalid_params, and so is an against that is not another attempt of the fan. A named or recorded base is taken through its merge base with HEAD.

{"verb": "review-diff", "params": {"session": "api-fan-retry-2"}}
{"result": {"type": "review_diff", "session": "api-fan-retry-2", "window": "4be1c09a-...",
 "repo_root": "/src/api", "worktree": "/home/u/.local/share/tuios/worktrees/api/fan-retry-2",
 "base": "main", "base_sha": "1a760e8f...", "uncommitted": false, "tree_sha": "9d0c...",
 "files": [
  {"path": "api/retry.go", "status": "M", "added": 12, "removed": 1, "hunks": [
   {"header": "@@ -40,7 +40,19 @@ func Do(ctx context.Context", "old_start": 40, "old_lines": 7, "new_start": 40, "new_lines": 19,
    "lines": [{"op": "context", "old": 40, "new": 40, "text": "\tfor attempt := 0; ; attempt++ {"},
              {"op": "delete", "old": 41, "text": "\t\tif err := f(); err == nil {"},
              {"op": "add", "new": 41, "text": "\t\terr := f()"}]}]},
  {"path": "docs/retry.md", "status": "U", "added": 9, "removed": 0, "hunks": []}],
 "totals": {"files": 2, "added": 21, "removed": 1}, "truncated": false,
 "notes": [], "untrusted": true}}

status is A, M, D, R (with old_path) or U (untracked: new and not yet added to git). A line's op is context, add or delete, with old and new its numbers on each side, and no_newline on the last line of a side without one. Past 400 files, 2 MiB of diff text, or 5000 lines in one file, a file carries its counts with truncated and no hunks, and the diff says truncated. A binary file has binary and counts only. With against, base and base_sha are empty and against and against_tree name the other attempt.

Every call finds the pane's notes again in the diff it read and returns them as notes, as review-note lists them. The answer is marked untrusted: the text is the repository's.

index reads the worktree's own index instead of a base. unstaged is the index (written with git write-tree) against the working files, untracked files included as U. staged is HEAD (the empty tree before the first commit) against the index. base is then index or HEAD, base_sha is a tree, and the result has index. It takes no base, against or uncommitted. The notes are returned, and are not moved by an index diff. A hunk's header and its lines are the same as review-stage reads them for the same index and context.

highlight (default false) adds two fields to each line. hl is the syntax colour: [start, end, class] runs in bytes of text, where class is a number. The result's classes names the numbers in order (plain, keyword, type, ...). changed is the [start, end] bytes of a removed or added line that changed against the line it pairs with. Each field is absent when it is empty. The old side and the new side of a hunk are each coloured as one text. A truncated file, a binary file and a very large text are not coloured.

A pane without admin reads its own session and fan group, and the session against names must be in its reach too. Over a link it needs write, since it returns file contents.

review-stage

Stage or unstage a change in the worktree under a pane. Only the index changes. The working files do not change. One call runs at a time in a worktree.

Params: session, window (as for review-diff), action (stage, unstage or undo), path (relative to the repository root), hunk (a header exactly as review-diff returned it; omit for the whole file), lines (indices into that hunk's lines; only added and removed lines count; omit for the whole hunk), context (the context of that diff, default 3), undo (for undo), human_nonce.

  • stage reads the unstaged diff of path again. A whole file is git add -A, which also stages a deletion or an untracked file. A hunk or lines become a patch applied with git apply --cached: an unselected added line is left out, and an unselected removed line stays.
  • unstage reads the staged diff. A whole file is git reset, or a removal from the index before the first commit. A hunk or lines are the reverse: an unselected added line stays, and an unselected removed line is left out.
  • A rename and its old path are staged together, and only whole, as is a binary file (whole_file_only). A hunk no longer in the diff is hunk_changed.
  • Every result has undo: entries, the index entries of the paths touched before the call ({path, mode, sha}, or {path, absent: true}), and after, the same paths after it.
  • undo takes that object. It is index_changed unless the index still holds after. Then it writes entries back with git update-index, and answers with undo swapped, so sending that back redoes the call.
{"verb": "review-stage", "params": {"action": "stage", "session": "work",
 "path": "list.txt", "hunk": "@@ -8,5 +8,7 @@ seven", "lines": [4]}}
{"result": {"type": "review_stage", "session": "work", "window": "ee773ef6-...",
 "worktree": "/src/repo", "path": "list.txt", "action": "stage",
 "undo": {"entries": [{"path": "list.txt", "mode": "100644", "sha": "e68fa666..."}],
          "after": [{"path": "list.txt", "mode": "100644", "sha": "e5dcefbe..."}]}}}

It is the person's tool: refused on a restricted connection, admin for a pane, write over a link. A human_nonce that is given must be live. The review overlay calls it with the keys a, d, A, D and z.

review-note

Keep the notes on a pane's changes. They are held by the daemon per worktree and per pane: at most 200 on a worktree, 1000 bytes each, saved across a restart for the panes that come back, and dropped with the pane or the worktree.

Params: action (required: add, edit, remove, list, clear), session, window, and:

  • add: path (relative to the repository root), then line (from 1) with side (new, the default, or old for a removed line numbered as in the base) and quote (the line's text; omit it and the daemon reads it from the file, new side), or hunk, a hunk header, for a note on the whole hunk; text.
  • edit: id, text. The note becomes the caller's and unsent again.
  • remove: id. clear: every note the caller may remove; kept in the result counts the ones left because the caller may not change them.
  • human_nonce: with a live nonce the note is the person's (by: human). A nonce that does not verify is not_human.
{"verb": "review-note", "params": {"action": "add", "session": "work", "window": "build", "path": "api/retry.go", "line": 42, "text": "log the attempt number here too"}}
{"result": {"type": "review_notes", "session": "work", "window": "4be1c09a-...", "worktree": "/src/api", "id": "n3",
 "notes": [{"id": "n3", "path": "api/retry.go", "side": "new", "line": 42, "quote": "if err == nil {",
  "text": "log the attempt number here too", "by": "shell", "at": 1790000000000000000}]}}

A note carries id, path, side, line, quote or hunk_header, text, by (human, a pane's window id, shell, or link:HOST), at, sent_at once sent, and outdated when its line could not be found again. Notes are listed by path, then line.

Who may change a note: the person any note, a pane or a linked machine only the notes it wrote, a caller outside every pane every note but the person's. Another's note is forbidden. A pane needs write and reaches its own session and fan group; over a link it needs write. A note is typed into its pane when it is sent, so a pane without admin may add or edit notes only on itself or a pane that holds nothing it does not, the rule send-text follows; elsewhere it is forbidden. A pane on another machine calling through its report channel is forbidden.

send-review

Send a pane's unsent notes, or the ones ids names (sent or not), to its agent as one message through the delivery queue (see The delivery queue). The pane must run an agent (invalid_params otherwise). The notes are marked sent_at when queued.

Params: session, window, ids, now (send only when the agent is at rest with nothing queued: not_ready for a busy one, agent_blocked for one on needs_input, and nothing is queued), human_nonce.

{"verb": "send-review", "params": {"session": "work", "window": "build", "human_nonce": "<from the attach reply>"}}
{"result": {"type": "review_sent", "session": "work", "window": "4be1c09a-...", "notes": 2, "ids": ["n3", "n4"],
 "queued_id": "q7", "position": 1, "queued": 1, "delivering": true}}

The message reads "Review notes on your changes (vs BASE), from SENDER:", then one numbered entry per note (path:line, on "quote" cut to 120 characters, or the hunk's range and header; outdated said when it is), the note's text indented under it, and "Address each note, then say which you changed." The sender is "the person" only with a live human_nonce, "pane NAME" from a pane, "a caller on HOST" over a link, and "a script" otherwise. A note written by someone other than the sender carries a line under its place naming its author, "(written by pane NAME)", with ", not by the person" when the person sends it, so no pane's note reads as the person's.

Each note is typed with the authority of whoever wrote it, checked as it is now: a note by a pane that no longer holds write reach to the session, or may not type into the pane (it holds more than the author), or whose pane is gone, and a note by a linked machine whose link may no longer write, is withheld. It is left out, not marked sent, and listed in withheld with withheld_reason. When every note picked is withheld the call is forbidden and nothing is queued. Editing a note makes it the editor's. BASE is the base of the pane's last review-diff. A message over 16 KiB is invalid_params. Errors: no_notes when nothing is unsent, queue_full, not_human, forbidden.

It types into the pane, so it is held like queue-prompt: a pane needs write, may send only to a pane that holds nothing it does not and is not on needs_input unless it holds respond, and is checked again when the message is typed. Over a link it needs write.

list-checkpoints

The checkpoints of a pane, oldest first. A checkpoint is the pane's git work tree saved as a commit under refs/tuios/checkpoints/<window id>/<n>: when its agent finishes a turn that changed a file, and before each restore. See Turn checkpoints for when one is taken. The repository is found as for review-diff: none is not_repo, and so is a pane whose process runs on another machine.

Params: session, window.

{"verb": "list-checkpoints", "params": {"session": "work", "window": "build"}}
{"result": {"type": "checkpoint_list", "session": "work", "window": "4be1c09a-...",
 "worktree": "/src/api", "enabled": true, "keep": 50, "untrusted": true,
 "checkpoints": [
  {"n": 1, "ref": "refs/tuios/checkpoints/4be1c09a-.../1", "commit": "e958e3b...", "tree": "9d24e28...",
   "head": "95f2766...", "kind": "turn", "pane": "4be1c09a-...", "session": "work", "turn": 1,
   "state": "done", "label": "Add a retry with backoff.", "worktree": "/src/api", "at": 1791102811086683744}]}}

kind is turn or safety. turn is the pane's finished-turn count (completion_seq) when the checkpoint was taken, and head is HEAD then. label is the prompt of the turn, else the line it ended with, else the state's message, at most 120 bytes. The answer is marked untrusted: the labels are the agent's text. enabled and keep are [agents.checkpoints]. A pane without admin needs read in its own session and fan group. Over a link it needs list.

checkpoint-diff

What one turn changed: a checkpoint's tree against the pane's checkpoint before it, or for the first one against HEAD when it was taken (the empty tree in a repository with no commit). Nothing in the repository changes.

Params: session, window, n (omit for the newest), paths (at most 256, relative, each taken literally), context (0 to 20, default 3). A number the pane has no checkpoint for is no_checkpoint, with the numbers it has in the hint's available.

{"verb": "checkpoint-diff", "params": {"session": "work", "window": "build", "n": 2}}
{"result": {"type": "checkpoint_diff", "session": "work", "window": "4be1c09a-...", "worktree": "/src/api",
 "checkpoint": {"n": 2, "kind": "turn", "...": "..."}, "base": "checkpoint 1", "base_tree": "9d24e28...",
 "files": [{"path": "notes.txt", "status": "M", "added": 1, "removed": 0, "hunks": ["..."]}],
 "totals": {"files": 1, "added": 1, "removed": 0}, "truncated": false, "untrusted": true}}

files, totals and truncated are as review-diff returns them, with the same caps. A file the base does not have is A: the checkpoint does not say whether git tracked it. A pane without admin needs read. Over a link it needs write, since it returns file contents.

restore-checkpoint

Put a pane's git work tree back to a checkpoint. The daemon first saves the work tree as a safety checkpoint, labelled "before restoring checkpoint N", so restoring that one undoes the restore. Then it writes the files that differ between the two trees and removes the files the checkpoint does not have, through a temporary index. The index, HEAD, the branch and the stash do not change, and ignored files are in no checkpoint and are not touched, so nothing git can see is lost. git status afterwards shows the restored files as changes against the index. A submodule that differs is left as it is and listed in skipped.

The checkpoint can have a file where the disk has one that no checkpoint holds, such as an ignored file. Then the restore is invalid_params, available lists those paths, and nothing changes. Writing over such a file would lose it.

Params: session, window, n (required), force. While the pane's agent is working or needs_input the restore is not_ready and changes nothing, since the agent would go on writing: wait for the turn to end, or pass force. A checkpoint taken in another work tree than the one the pane is in now is invalid_params. Errors: no_checkpoint, git_failed (when it fails after the safety checkpoint, the hint says to restore that one).

{"verb": "restore-checkpoint", "params": {"session": "work", "window": "build", "n": 1}}
{"result": {"type": "checkpoint_restored", "session": "work", "window": "4be1c09a-...", "worktree": "/src/api",
 "restored": {"n": 1, "...": "..."}, "safety": {"n": 3, "kind": "safety", "...": "..."},
 "written": ["notes.txt"], "removed": [], "skipped": []}}

A restore writes the files the pane's agent works on, so a pane without admin needs write, and may restore only a pane that holds nothing it does not, as review-note adds notes. Over a link it needs write.

list-attention

List the Inbox: everything waiting for the person, in every session on this daemon and on every linked host it follows (see Following linked hosts). Each item is one of these kinds, and the list is grouped in this order, oldest first inside each group:

KindOpens whenCloses when
approvalA pane goes to needs_input with blocked_by approval. risk names the risk rules its line matched.The pane leaves needs_input.
planA hook holds a plan with request-approval kind: plan. It is the pane's approval item for as long as the hold runs, with plan_lines and plan_sha.The pane leaves needs_input, the person answers, or the hold ends (it is an approval again).
askask-human puts a question to the person. summary is the question, options its answers and request_id the question's id.The person answers it (answered, with answer and answered_by) or dismisses it, the asking pane asks another (superseded) or closes.
questionA pane goes to needs_input with any other blocked_by, or none.The pane leaves needs_input.
mailA message to human lands in a thread. One item per thread; count is the unread messages.The person's mail in the thread is read.
erroredA pane goes to errored.The pane leaves errored.
resumeA restore brings back a pane with a conversation its harness can resume, with daemon.resume_agents on ask. The summary is the command.resume-agent types it, or the pane goes to working or needs_input (an agent is running there again).
finishedA pane's completion_seq goes up as it comes to rest.An attached client focuses the pane, the agent starts another turn (working), blocks, or errors.
outboxsend-agent-message with host is kept here because that machine's link is down, or a kept message was refused there. One item per machine, with for_host; count is the messages waiting, and the summary says how many and the last refusal.Everything waiting was delivered and nothing was refused, or dismiss-attention, which also discards what waits.

Every item also closes when its pane closes (mail excepted: the message is still unread), when its session ends, and on dismiss-attention. A pane has at most one blocking item, one errored item and one finished item, so a harness repeating itself or a fan of agents moving together updates rows rather than adding them, and an update that changes nothing publishes nothing.

A blocking or errored item follows the pane's latest report, not only its state changes. A pane that stays on needs_input and reports a new blocked_by or message (a harness hook that says approval after the screen tier already set needs_input, say) updates its item: it moves between question and approval, and its summary is the new message. The item keeps its id and its since. A change of the pane's name, harness or workspace updates it the same way. None of this is an agent-state event, since the state did not change, and no hook fires for it; only the attention event with action updated is sent.

Params: session (optional; unlike most verbs, omitted means every session; without host it names a session on this machine), kinds (optional list, from approval, plan, ask, question, mail, errored, resume, finished, outbox), include_snoozed (optional bool: also list the items the person snoozed, after the open ones and in the same order among themselves, each with snoozed_until; they are not in counts), host (optional: local for this machine or a linked host's name; omitted means every machine; an unknown name is unknown_host), select (optional, a selector: keeps the items it matches, reading an item's state from its kind, needs_input for an approval or a question, errored, done for finished; group and cwd are known for items of this machine only).

Response:

{"result": {"type": "attention_list", "items": [{"id": "17", "kind": "approval", "session": "fan-3", "window": "3f2a9c1e", "workspace": 1, "harness": "claude-code", "name": "claude", "summary": "approve Bash: go test ./...", "since": 1790142942055373000, "seq": 41}], "counts": {"approval": 1, "question": 0, "mail": 0, "errored": 0, "resume": 0, "finished": 0}, "total": 1, "seq": 1180, "boot_id": "9f2c41d07a3e8b65"}}

Item fields: id (stable, never reused on this machine; an item of a linked host is host:id, the host's own id after the colon), kind, host (empty for this machine, the host's name for an item of a linked host), session, window, workspace, harness, name, summary, options (the decisions reply-approval takes, set only while a hook holds the item), request_id and expires (the held request and when its hold ends, in unix nanoseconds; see request-approval), always_scope (what answering always adds, one rule per line, set only while held with always offered), since (unix nanoseconds, when the item started waiting; an update keeps it), seq (the Inbox revision of the item's last change), thread and count (mail), seen (mail: how many of count were seen with a peek and not read), completion_seq (finished), snoozed_until (a snoozed item listed with include_snoozed: when it opens again, in unix nanoseconds, or -1 for when its fact changes), marked_unread (a finished item the person reopened with mark-attention unread), stale and seen_at (an item of a host whose link is down: what the host said last, and when this daemon last heard from it, in unix nanoseconds), held_id and held_for (mail from another machine held for the person by hold_mail: the message release-agent-message takes and the window it was for), for_host (outbox: the machine the mail waits for).

summary is text an agent wrote. The daemon keeps it to one line, removes control characters, masks what looks like a credential (TOKEN=..., password: ..., Bearer ...) and cuts it to 160 bytes before it is stored, sent to a subscriber or written to disk. The masking is a net for the common shapes, not a guarantee.

seq and boot_id are the stream position the answer is current to. To follow the Inbox without missing anything, list it and then subscribe with types: ["attention"], after_seq and boot_id from the listing. Every change after the listing is replayed; a gap means list again.

Persistence: part of the queue survives a daemon restart. On start the daemon keeps the finished and errored items whose session and pane came back. It drops approval and question items, because the prompt died with the process that painted it, and mail items, because the message ring they point into does not survive a restart and thread ids start again from 1, so a saved item could only be merged into an unrelated new thread. An item opened while the saved queue is still loading keeps its id and wins over a saved item for the same pane and kind. A saved item whose id such an item already holds is kept under a fresh id, so no two items ever share one. A snoozed finished or errored item is saved with snoozed_until and comes back asleep; one whose time passed while the daemon was down wakes on start. It drops resume items too: the restore that runs on start opens them again from each window's agent_session_id, after the saved items are loaded. outbox items are opened again from the outbox, which is saved on its own and survives a restart whole.

Wire compatibility: new verb and new event type. An older daemon answers unknown_verb, and the tuios client then shows the Inbox as unavailable.

Selectors

A selector addresses every agent pane that fits a description. It is one string of terms separated by spaces, all of which must match; a term is key:value, and commas in the value are alternatives. The keys are harness (the harness id, or a program name a manifest detects), state, needs (only needs:you: needs_input or errored), session (glob), group (the fan-out group, glob), host (local or a host name, glob), name (window name, glob), cwd (the directory or under it; a leading ~ is the daemon's home), task (a task card the pane holds, by id, glob; see Task verbs) and stage (the stage of a card the pane holds; a done card has no holder, so stage:done matches no pane). Globs are path.Match: * does not cross a slash. A term a pane cannot answer does not match. A selector that does not parse is invalid_params naming select, with the keys in accepted.

Reads: list-agents, list-host-agents, list-attention and wait-for (agent-state) keep what the selector matches. Writes: send-agent-message and ask-agent send to every agent pane on this machine the selector matches, in every session, and take no session, no window or to, and for a message no reply_to. A write reaches at most 32 panes, an ask at most 16; more is invalid_params, and none is window_not_found.

A write is confirmed before anything is sent. Without confirm the call fails with confirm_required:

{"id": 1, "error": {"code": "confirm_required", "message": "the selector matches 2 panes; nothing was sent",
 "hint": {"param": "confirm", "available": ["api-fan-retry/codex (3f2a9c1e)", "web/codex (91bd07aa)"],
  "confirm": "5c1f0e9ad2b37744", "detail": "..."}}}

The token is a hash of the set of panes (each by window id). The call again with "confirm": "5c1f0e9ad2b37744" goes ahead only if the selector still matches exactly that set; otherwise it fails with confirm_required again and the new set. list-agents with the same select answers with the same token in confirm. The token is not a secret and grants nothing: it only says the caller saw the set.

A confirmed message answers agent_messages_sent:

{"result": {"type": "agent_messages_sent", "select": "harness:codex", "sent": 2, "failed": 0, "total": 2,
 "results": [{"session": "api-fan-retry", "window": "3f2a9c1e-...", "name": "codex", "ok": true, "message_id": 14, "thread_id": 14},
             {"session": "web", "window": "91bd07aa-...", "name": "codex", "ok": true, "message_id": 3, "thread_id": 3}]}}

A confirmed ask answers agent_replies, with replies holding one row per pane: ok, and either the fields of a single ask's answer (reply, settled_by, state, lines, truncated, waited_for) or error with the code, message and hint the single ask would have failed with. answered and failed count them, and untrusted is always true.

Each pane of a write goes through the checks of a single call: the rate cap per pane, the human rules, agent_blocked for a pane on needs_input unless allow_blocked, the wait for a working pane unless force, and the loop guard. from may name the sender's pane in another session by its exact window id. A call that names select from a pane on another machine running its calls through its owner is refused with forbidden, since such a call acts only as the window it is drawn in.

dismiss-attention

Close one Inbox item for the person.

Params: id (required), human_nonce (required: the nonce from the attach reply of a TUI client attached right now, over the same kind of connection as this call).

Only the person may clear what is waiting for the person. An agent in a pane has no attach and so no nonce, and gets not_human. The nonce is checked the way a reply from human is (see "A process inside a pane cannot act as the person" under Changes to existing verbs): a caller inside a pane of this daemon, or on a link stream the hub did not vouch for, gets not_human even with a live nonce, and where the kernel gives both pids the caller must be the process that holds the attach. A client attached to any session may dismiss items in any session, since the Inbox spans them. A second dismiss of the same item, or an id that is not open, is invalid_params.

Dismissing a finished item marks the pane's turns seen. Dismissing a mail item marks the person's unread mail in the thread read. The other kinds only leave the list; the pane's agent state is not touched, and a later transition opens a new item. A snoozed item can be dismissed by its id too.

For 10 seconds after, the dismiss can be undone with mark-attention restore, except on an outbox item, whose dismiss discarded the mail, and an ask, whose asker was told.

An item of a linked host is hidden on this daemon and nothing else: nothing on the host is marked, and the item comes back when the host changes it. The result then carries host.

Response:

{"result": {"type": "attention_dismissed", "id": "17", "kind": "approval", "session": "fan-3", "dismissed": true}}

mark-attention

Snooze an Inbox item, wake it, mark a finished pane unread, restore an item dismissed or snoozed in the last 10 seconds, or settle an agent, for the person.

Params: action (required: snooze, wake, unread, restore, settle or unsettle), id, or session, window and kind to name the item by what it is about (unread, settle and unsettle need only session and window), human_nonce (required, as for dismiss-attention). With snooze, exactly one of until (unix milliseconds, within the next year), for_ms (at most a year) and until_change (true).

  • snooze closes an open item with the reason snoozed. It opens again with its id and since when its time comes, when its fact changes (the pane reports something the item does not already say, or a hook starts holding the approval), or on wake or restore. A report that repeats what the item says leaves it asleep. until_change waits only for the change. A snooze of an item already asleep changes when it wakes. Only these kinds can be snoozed: finished, errored, mail, resume, question, and an approval no hook is holding. A held approval, a plan and an ask wait on an answer, and outbox is about a link, so each is invalid_params.
  • wake opens a snoozed item now.
  • unread reopens a pane's finished turn: the daemon forgets that it was seen, so the next client to focus the pane marks it seen again, and a finished item opens (or an open one is marked) with marked_unread. The pane must be on this machine, have finished a turn, and be at rest.
  • restore reopens an item this daemon closed for a dismiss or a snooze less than 10 seconds ago, with its id and since. A restored finished item forgets the look again, like unread; restored mail comes back as a row, and its messages stay read. An approval, question, plan or error comes back only while the pane is still in the state it was about, and nothing comes back over a newer item about the same thing. The check and the reopen are one step: a transition that arrives during a restore lands after it and closes the restored item as it would any other.
  • settle puts the agent in the pane on the Settled shelf: the window state's agent_settled is true until the agent needs the person again (it goes to needs_input, errored or none, finishes a turn, or sends the person mail) or until unsettle. It closes the pane's open finished item as a dismiss does, and the answer names that item as id. A pane with no agent, a pane on needs_input, and a pane with any other open item are invalid_params. A settle that changes the pane runs the after-settle hook with TUIOS_SETTLE_REASON=person.
  • unsettle takes the agent off the shelf. With id, the item settle closed, it also restores that item as restore does, and the answer names it as id when it came back.

An item of a linked host is snoozed on this daemon only, like a dismiss: nothing on the host changes, and the item wakes when the host changes it or its time comes. unread does not reach another machine's panes.

A client finds out whether a daemon has this verb by asking list-verbs for it once per attach; tuios's own client hides its snooze, undo and unread keys from a daemon that does not.

Only the person can: the call is refused to a pane without admin (forbidden), needs respond over a link, and carries the nonce, checked as for dismiss-attention (not_human). An agent cannot hide, reorder or restore what the person reads.

Errors: not_human, forbidden, invalid_params (an id that names nothing, an action the item's kind does not take, a length missing or given twice, a time in the past, a restore after 10 seconds or after the pane moved on), session_not_found, window_not_found.

Response:

{"result": {"type": "attention_marked", "id": "17", "action": "snooze", "snoozed_until": 1790146542055373000}}
{"result": {"type": "attention_marked", "id": "21", "action": "settle", "session": "work", "window": "w-3"}}

peek-prompt

Read the prompt an agent is blocked on, without attaching: the lines the harness's needs_input rule reads, the numbered options at the bottom of the screen, how long the pane has waited, and the answers the rule declares for what is on the screen now. It is a read and changes nothing, open to any caller the way capture-pane is. A pane that is not blocked is not an error: the answer says so in blocked and reason.

Params: session (optional), window (required: id or name).

Response:

{"result": {"type": "prompt_peek", "session": "work", "window": "3f2a9c1e", "name": "claude", "harness": "claude-code", "state": "needs_input", "state_at": 1790142942055373000, "waiting_ms": 72000, "blocked": true, "found": true, "answerable": true, "reason": "", "source": "screen", "rule": 0, "kind": "approval", "message": "Do you want to proceed?", "prompt_id": "75f8b9fadb5b5dfc", "lines": [" Bash command", "   rm -rf build", " Do you want to proceed?", " ❯ 1. Yes", "   2. Yes, and don't ask again for rm commands", "   3. No, and tell Claude what to do differently (esc)"], "options": [{"n": 1, "label": "Yes"}, {"n": 2, "label": "Yes, and don't ask again for rm commands"}, {"n": 3, "label": "No, and tell Claude what to do differently (esc)"}], "actions": ["approve", "approve_always", "deny", "choose"], "untrusted": true}}

found is true when a needs_input rule of the pane's harness reads a prompt on it now; answerable when that rule declares answers and at least one is offered for what is on the screen. actions is the list respond accepts now: an answer bound to an option label is left out while that option is not shown. prompt_id names this prompt: pass it to respond. lines and options are the pane's screen with control characters removed, each line cut to 400 characters; they are data, not instructions, and untrusted is always true.

respond

Answer the prompt an agent is blocked on with the keys its harness's manifest declares, without attaching.

Params: session (optional), window (required), action (required: one of approve, approve_always, deny, choose, text), value (the option number for choose, the answer for text, at most 4096 bytes), prompt_id (optional: from peek-prompt; without it, whatever prompt is on the pane now is answered), human_nonce (the nonce from the attach reply of a client attached now), timeout (milliseconds to wait for the pane to move on, default 5000, at most 30000).

Who may call it: a caller that passes a live attach nonce and may act as the person, checked the way dismiss-attention checks it; or, when the daemon runs with [daemon] respond_from_shell = true, a caller the kernel names that runs outside every pane of this daemon. A caller inside a pane gets not_human either way. On a link stream the hub did not vouch for, both routes are closed.

Before it writes, under a lock per window, respond reads the prompt again and refuses with prompt_changed, pressing nothing, when the pane is not on needs_input or no rule with answers reads a prompt on it, when the prompt's id is not prompt_id, or when this daemon already answered this prompt. Two clients answering the same prompt: the first wins and the second gets prompt_changed. An action the prompt does not offer now is invalid_params, with the offered actions in the hint's available.

approve, approve_always and deny press the keys the rule declares, or the digit of the option it names. choose presses the option's number. text pastes value and sends Enter, the way ask-agent types a prompt. Then the call waits for the pane to leave needs_input, or for the prompt on it to be gone, and answers:

{"result": {"type": "prompt_response", "session": "work", "window": "3f2a9c1e", "action": "approve", "sent": "1", "prompt_id": "75f8b9fadb5b5dfc", "settled_by": "state", "state": "working", "message": ""}}

settled_by is state (the pane left needs_input), prompt (the prompt is gone but the state has not followed yet), gone (the window closed) or timeout (the prompt is still on the screen; look at the pane).

Wire compatibility: new verbs. An older daemon answers unknown_verb.

request-approval

Hold a pane's permission prompt until the person answers it in the Inbox. tuios agent-hook calls it; a script has little reason to. It is for a harness that takes a decision back from its hook: Claude Code's and Qwen Code's PermissionRequest hook, and opencode or Kilo through the plugin tuios installs. The call does not answer until the person answers with reply-approval or the hold ends, and it is opt in: nothing is held unless [agents.approvals] in the config names the harness, or the pane is one start-agent opened with protocol (see Headless agents: protocol).

[agents.approvals]
enabled = ["claude-code", "opencode"]
hold_seconds = 120

Params: session (optional), window (required), harness (required, an id or alias), options (optional list of the decisions the harness can take, from once, always, deny; omitted means once and deny), summary (required: the line the person answers from, which must be the whole request), always_scope (optional list: what always allows from now on, one rule per line).

The pane must already be on needs_input with an approval item open, which the hook's own report sets up just before. The item then carries request_id, options, expires and always_scope, its summary becomes the given line for as long as the hold runs, and the Inbox shows the keys that answer it.

The person answers from that line, so it has to be the whole request. The hook only asks for a call whose effect one argument decides and whose line shows that argument in full (see Approvals from the Inbox). The daemon checks again: a summary the Inbox could not show as it is, because it is longer than 160 bytes, has a control or format character (a bidi override, a zero width space), a newline, tab or doubled space, or text the Inbox would mask as a secret, holds nothing and answers at once with reason not_shown. always is dropped from options unless always_scope has one to four lines, each of which passes the same check, so always is never offered without the rules it adds on screen.

Response, when the person answered:

{"result": {"type": "approval_result", "request_id": "9f86d081884c7d65", "decision": "once", "reason": "answered", "answered_by": "client-1790155072046345000"}}

decision is once, always or deny, or empty when there is none. An empty decision means the harness should ask in its pane, as it would have without tuios, and reason says why:

reasonMeaning
answeredThe person answered. decision is set, and message too when they gave a reason for a deny.
disabled[agents.approvals] does not name the harness. Answered at once.
not_blockedThe pane is not on needs_input with an approval item. Answered at once.
not_shownThe Inbox could not show summary as it is. Answered at once.
viewedA client of the person has the pane focused, or focused it during the hold. The prompt is quickest to answer in the pane.
timeouthold_seconds passed (120 by default, kept between 10 and 300).
handed_backThe person pressed enter on the item to go to the pane, or sent reply-approval with ask.
supersededA newer request-approval for the same pane replaced this one.
caller_goneThe caller closed its connection, which is how a harness that gave up on its hook shows.
shutdownThe daemon is stopping.
resolved, dismissed, window_closed, session_closed, evictedThe Inbox item closed for that reason: the pane moved on, the person dismissed it, and so on.

Who may call it: it is refused with forbidden over a link, and a caller inside a pane of this daemon may only hold its own pane's prompt (the daemon places the caller by its process ancestry, then its controlling terminal, then its TUIOS_PANE_ID; a caller it cannot place is refused). What the caller gets back is the answer to the prompt it asked about, nothing more.

Send nothing else on the connection while the call waits. The daemon reads it only to notice the caller going away, and a byte that arrives is discarded.

Robustness: a daemon that is gone, restarts during the hold, or predates the verb (unknown_verb) gives the hook an error, and the hook prints nothing. A hold is not saved across a restart. The hook only ever prints a decision the daemon returned and the harness was offered.

reply-approval

Answer a held approval for the person.

Params: request_id (the item's; or name the pane with session and window instead), decision (required: once, always, deny, or ask to give the prompt back to the pane with no decision), message (optional, the reason for a deny, passed to the model; one line, at most 500 bytes), human_nonce (required, as for dismiss-attention), summary (optional: the item's summary the decision was made from; the TUI always sends it).

When summary is given and the hold is now on another line, nothing is answered: the response has applied: false, reason changed, an empty decision and the summary the hold is on now, and the hold runs on so the person can read it and answer. This closes the gap between drawing an item and the key arriving. ask is never refused this way.

Only a client attached right now can answer, with the nonce its attach reply carried, checked exactly as dismiss-attention checks it: a caller inside a pane, or on a link the hub did not vouch for, gets not_human even with a live nonce. No mail, ask-agent, send-keys or send-text reaches a hold, so an agent cannot approve its own call or another agent's.

A decision the item's options do not offer is invalid_params, and so is a request that is not held. The first reply wins: a later reply for the same request answers with the decision that stands and applied: false, and changes nothing. A decision closes the Inbox item with reason answered and moves the pane to working. ask ends the hold and leaves the item open.

Response:

{"result": {"type": "approval_replied", "request_id": "9f86d081884c7d65", "decision": "once", "applied": true, "reason": "answered", "answered_by": "client-1790155072046345000", "session": "fan-3", "window": "3f2a9c1e"}}

Wire compatibility: both verbs are new, and the item fields are additive. An older daemon answers unknown_verb, which the hook reads as no decision. reply-approval must carry summary for an allow (once or always): an allow without it answers nothing and is refused with invalid_params, so a caller cannot approve a call by not saying which line it read. A deny may leave it out. The TUI Inbox and guios have always sent it.

A client's push that moves the focus to a held pane ends the hold as viewed only when the person moved it. A push made while the client ran a routed run-command, or keys from send-keys or a tape, carries focus_by_command, and the hold runs on. focus-window, which the daemon carries out itself, never ended a hold.

Risky approvals and plans

Two additions to held approvals make an allow harder to give by mistake: risk rules, and plans.

Risk rules. The daemon matches every approval against the rules of [agents.approvals.risk]: the shipped ones (recursive delete, force push, hard reset, clean, discard changes, pipe to shell, sudo, disk, wide permissions, database, infrastructure, outside the worktree) unless builtin = false, and the person's own. See Risk rules for what each one matches. They run on a held call's tool and target when the hook names them, else on its summary, and on the line of every approval item nobody holds (tuios's own hooks report approve <Tool>: <what>, which is read as that tool and argument; any other line is read as a command). The names of the rules that matched are the item's risk. That line is clipped and redacted, so a line that does not show the whole call also carries cut short in risk, which is acknowledged like a rule. A path in such a line is read only up to the ***, or, for the last word of a clipped line, up to the ... the clip adds. A ... at any other place is part of the path. outside the worktree measures from the pane's root: the first of the session's worktree when tuios made it, the folder the pane started in, and the folder its agent started in (agent_cwd on the first set-agent-state of the agent session) that is narrower than the home folder. A cd, an OSC 7 or a later report does not move it. A pane with no root has every absolute or ~ path read as outside. Links are resolved before paths are compared. A relative path is read from the folder the call runs in: the cwd the hook sends on request-approval, else the folder the pane's process is in. A cd earlier in the command moves that folder, and a cd in a subshell or a pipeline ends with it. A relative path is outside when that folder is not known or is outside the root. A path with a variable in it, other than a leading $HOME, is outside. outside the worktree names a cut path only when the part the line shows already leaves the worktree. A Codex apply_patch line always carries cut short, because every patch starts with *** Begin Patch. A daemon that read no config file uses the shipped rules.

  • reply-approval with once or always on an item with risk must carry risk_ack naming exactly those rules, in any order. Otherwise the call is refused with risk_unacknowledged (the hint's accepted lists the rules), nothing is answered and the hold runs on. A deny needs none.
  • respond holds its allowing answers to the same rule, against the risk of the pane's Inbox item: approve, approve_always, text, and choose unless the option presses exactly the keys the prompt's deny does. From a pane answering under its respond grant, such an answer is refused with forbidden even with risk_ack, unless panes_may_allow = true. A deny is always taken.
  • This is a change for an older client: one that sends no risk_ack cannot allow a risky call from the Inbox or the peek. The harness asks in its pane as before once the hold ends. Nothing changes for a call no rule matched.

The rules are a speed bump, not a sandbox: a command written to hide what it does passes them, and the harness's own permission system stays the boundary.

Plans. request-approval with kind: plan holds a plan an agent in plan mode asks to have approved (Claude Code's ExitPlanMode). plan is its text, at most 32 KiB of UTF-8, required with kind: plan and refused without it. summary is only its title: it is cleaned the way every item line is rather than refused. Nothing is held (reason disabled) when hold_plans = false. While the hold runs the pane's item is of kind plan, with plan_lines and plan_sha (the SHA-256 of the text, hex); the pane's blocked_by stays approval. When the hold ends without an answer, the item is the pane's approval again, with no plan fields.

  • reply-approval with once or always on a plan must carry plan_sha, the digest of the plan that was shown. Without it, or with another, nothing is answered: applied: false, reason changed, and the result carries the hold's plan_sha. deny keeps the agent planning and needs none; its message reaches the model.
  • get-approval serves the text while the hold runs.

Deny reasons. deny_message: true on request-approval says the harness passes a deny's reason to its model (Claude Code, opencode, Kilo), and the item carries it so the Inbox offers to type one. The reason itself is reply-approval's message, cleaned and cut to 500 bytes.

tool (at most 128 bytes) and target (at most 16 KiB) are what the hook names the call as; longer is invalid_params.

Wire compatibility: every field is additive. A hook sends kind, plan, tool, target, cwd and deny_message only to a daemon whose request-approval lists them, and does not hold a plan at all with a daemon that does not list plan, which would hold it as a plain approval.

get-approval

Read a held approval or plan whole.

Params: request_id (required), session (optional: when given, a hold in another session is not found; from a pane without admin it is the pane's own unless named).

Response:

{"result": {"type": "approval", "request_id": "9f86d081884c7d65", "kind": "plan", "session": "web", "window": "3f2a9c1e", "summary": "plan: Refactor the retry loop", "tool": "", "target": "", "options": ["once", "always", "deny"], "always_scope": ["Mode accept edits, for this session"], "plan": "# Refactor the retry loop\n1. ...", "plan_sha": "5d41402abc4b2a76b9719d911017c592...", "risk": [], "deny_message": true, "untrusted": true}}

risk is [{"rule": "...", "why": "..."}] for each rule the call matched. The text is the agent's, so the result is marked untrusted. A request that is not held, or held in another session than session, is invalid_params. Scope: read; over a link, list.

answer-ask

Answer an ask item for the person. Only a client attached right now can, with human_nonce from its attach reply and from a process outside every pane, the proof reply-approval takes; anything else is not_human.

Params: request_id (required), answer (required: one of the item's options, else invalid_params naming them), human_nonce (required), question (optional: the question the answer was picked from; when it is not the item's, nothing is answered and the reply says applied: false, reason: changed), upgrade_dialog (optional: a key pressed in a client's live upgrade dialog sent the answer. A live upgrade's ask takes only an answer that carries it, and gui-bridge drops it from what its renderer sends).

Response:

{"result": {"type": "ask_answered", "request_id": "9f86d081884c7d65", "answer": "no", "applied": true, "reason": "answered", "answered_by": "client-1790155072046345000"}}

The first answer wins. A later one gets applied: false with the answer that stands. The item closes with reason answered, carrying answer and answered_by, so every other client can say it was answered elsewhere.

Wire compatibility: both verbs are new and the item fields are the ones an approval already uses. An older client lists an ask item under its own heading, or not at all, and cannot answer it; an older daemon answers unknown_verb.

Following linked hosts

A daemon with a [hosts] table follows the agents and the Inbox of every linked host. For each host whose link is up it opens one connection over the link, calls list-attention with host: "local" there, and subscribes to attention, agent-state, agent-message, session-created, session-closed, window-created and window-closed from the listing's seq and boot_id. From then on:

  • The host's own items are mirrored into this Inbox (see list-attention). Items the host mirrors from its own hosts are not passed on: they are that machine's to report.
  • A burst of the host's agent and session events refreshes a cache of the host's list-sessions and list-agents answers, then publishes host-changed and pushes MsgHostsChanged to the attached clients.
  • With subscribe hosts: true, a subscriber also receives the host's agent-state, session-created and session-closed events, with host set, session and window cut to 128 bytes, and nothing else from the host's event.

When the link drops, the host's items are marked stale with seen_at, and list-host-sessions and list-host-agents answer from the cache with stale and fetched_at. On a redial the stream resumes from the last seq it delivered; a gap from the host, or a host that restarted, lists again.

A host whose tuios has no list-attention or no resumable stream is followed by polling, as every host was before: list-hosts reports events: "polling" with an events_note that names the update, and the tuios client keeps its poll for it.

Everything a host sends is data from another machine. Lines are bounded to 1 MiB, an item's kind must be one this build knows and its id a short token, its text is cleaned and cut as a local summary is, a host holds at most 256 items here, apart from this machine's so it cannot evict one of them, and the cache keeps at most 512 sessions and 2048 agent rows per host. Nothing a host sends runs a command, types into a pane, fires a hook or marks anything on this machine.

Reports from a pane on another machine

A window's process can run on another machine (new-window with host). Its reports travel back over a connection the owner opened, since the link is dialled one way:

  1. The owner sends window, its window id, with open-pane. The far daemon exports it to the process as TUIOS_PANE_ID and returns calls_token.
  2. The owner calls pane-calls with pane and token on a new connection. After the reply the connection carries requests from the far daemon, {"id":1,"verb":"set-agent-state","params":{...}}, one per line, and the owner answers each with {"id":1,"result":{...}} or {"id":1,"error":{...}}, in any order.
  3. On the far machine, a call of set-agent-state, set-agent-meta, set-agent-session or report-agent-activity with window, read-agent-messages with to, send-agent-message with from, or wait-for with condition agent-message and window, set to the pane's id or window id, is sent to the owner, and the owner's answer is the answer.

How the grant is held to that:

  • The far daemon forwards only for a caller that runs in the pane: the pane's process, a descendant of it, or a process on the pane's terminal, by the pid the kernel gave for the connection. Anyone else naming the pane gets forbidden. A platform that does not give the pid forwards nothing.
  • Only the verbs above cross; wait-for for anything but agent-message is forbidden.
  • The owner runs each request as the window itself: session and the addressing param are overwritten with the window's own, transcript_path, harness_pid, human_nonce, from_host and any_session are dropped, send-agent-message from anyone but the window is forbidden, and the call runs as a caller inside a pane, so it cannot act as the person. A far daemon that writes its own requests gets no more than the pane's process would.
  • send-agent-message may attach only paths in the session's stash, as on the link: its process and the far daemon are on the other machine, so a path names a file on the owner they cannot see. Any other path is invalid_params before it is looked at, so the answer does not say whether the file exists on the owner.
  • wait-for runs on the owner with timeout capped at one hour, whatever the request said, and ends when the channel it came on ends. The owner does not wait for calls in flight before it opens the next channel.
  • pane-calls needs the token, which only the owner saw. At most 16 calls per pane are in flight, and lines are bounded to 1 MiB.

An owner from before this sends no window, and the far daemon exports no TUIOS_PANE_ID and answers a call naming the pane id with protocol_mismatch. A far daemon from before this refuses open-pane with invalid_params, because it checks every request against its schema and its open-pane has no window. Nothing is spawned by that refusal and the connection still takes requests, so the owner sends open-pane again on it without window. The pane opens as before, with no calls_token, and the owner opens no channel.

open-pane with "resumable": true asks the far daemon to keep the pane through a dropped connection. The far daemon decides for how long, from its own hosted_grace for the asking machine (ten minutes by default, "0" for none, at most a day), and says so in the reply:

{"id": 1, "result": {"type": "pane", "pane": "f2c1...", "calls_token": "...", "resume_token": "9e0a...", "grace": 600}}

With no grace given there is no resume_token, and the pane ends with its connection as it always did. With one, the far daemon reads the process's output whether or not a connection is attached, keeps the last 64 KB, and counts every byte. When the connection drops it waits grace seconds. The asking daemon reattaches on a new connection:

{"id": 1, "verb": "open-pane", "params": {"resume": {"pane": "f2c1...", "token": "9e0a...", "offset": 18234}}}

offset is how many bytes of output it has received. The reply is {"type":"pane","pane":...,"resumed":true,"gap":false,"grace":600}, and after it the connection carries what was missed from offset on, then the live stream, exactly as after an open. gap is true when more was missed than the ring holds; the whole ring is sent then. A wrong token is forbidden, and a pane whose process exited or whose grace ran out is unknown_pane: both are final. A reattach closes a connection still attached to the pane.

release-agent-message

{"id": 1, "verb": "release-agent-message", "params": {"session": "work", "id": 12, "human_nonce": "<from the attach reply>"}}

Delivers the held message as a new message to the window it was for, with its original sender, origin and origin_host, and released_from set to the held id. The held copy is marked released and read, and its Inbox item closes when nothing else in the thread is unread. Only a client attached right now can call it, with its nonce (not_human otherwise), and over a link it needs respond. A message is released once; a second call, or an id that is not a held message the ring still holds, is invalid_params. A window that closed while the message was held is window_not_found.

Result: held_id, message_id, to, to_name, thread_id.

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page