Keep a message the person sent to an agent in the reply history. The same message again moves to the end. A message keeps at most 256 KiB of pastes and images: past that the largest are dropped and named. Only the person adds to it, with a live human_nonce.
Param
Type
Required
Default
Description
target
string
yes
The key the client keeps the history under.
parts
[]object
yes
The message, as queue-prompt takes it.
human_nonce
string
The nonce from the attach reply of a client attached now. The TUI sends its own. Without a live one the call is not the person's.
Result field
Type
Description
dropped
[]string
The blocks too large to keep.
{"id":1,"verb":"add-reply-history","params":{"target":"claude-code:/work/api","parts":[{"kind":"text","text":"rerun with -count=1"}],"human_nonce":"<from the attach reply>"}}
Answer an ask-human question for the person. Only a client attached right now can, with the nonce from its attach reply: an agent never can. The answer must be one of the question's options. The first answer wins; a later one is answered with the one that stands and applied false.
Param
Type
Required
Default
Description
request_id
string
The request_id of the ask item.
answer
string
One of the item's options.
human_nonce
string
The nonce the daemon issued in an attach reply, for a client attached now over the same kind of connection. The TUI sends its own.
question
string
The question the answer was picked from. When given and it is not the item's, nothing is answered: applied is false with reason changed. The TUI always sends it.
upgrade_dialog
bool
The answer is a key pressed in a client's live upgrade dialog. A live upgrade's ask takes only an answer that carries it. The TUI sends it from that dialog alone, and gui-bridge drops it.
Result field
Type
Description
request_id
string
The question answered.
answer
string
The answer that stands: this one when applied, an earlier one when not.
applied
bool
False when an earlier answer stands or the question changed.
reason
string
answered, or how the question ended before this answer, or changed.
answered_by
string
The id of the client whose answer stands.
{"id":1,"verb":"answer-ask","params":{"request_id":"9f86d081884c7d65","answer":"yes","human_nonce":"<from the attach reply>"}}
Drop messages from a pane's delivery queue before they are typed. The person, with a live human_nonce, may drop any entry; a pane only the entries it queued; a linked machine only the entries it queued; a caller outside every pane every entry but the person's. An entry being typed cannot be dropped. Dropping a stalled entry closes its Inbox question; the entries behind it are typed at the pane's next rest, one reached after the stalled entry was typed. A linked machine that gave no name drops only what it queued on the same connection.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. With all, omit it to target the focused window. With id, omit it to find the entry in any pane of the session.
id
string
The entry to drop.
all
bool
false
Drop every entry of the window the caller may drop.
human_nonce
string
The attached client's nonce, to drop as the person. One that does not verify is refused with not_human.
host
string
A machine from [hosts]: drop from a pane's queue there, over the link. The link drops only the entries this machine queued there. Only a caller outside every pane may ask; the far machine's policy for this one must allow write.
Read what one turn changed: the diff of a checkpoint against the pane's checkpoint before it, or against HEAD when it was taken for the first one. Nothing in the repository, its index or its working tree is changed. The text is the repository's, so it is marked untrusted.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. Omit to target the focused window.
n
int
The checkpoint. Omit for the newest.
paths
[]string
Only these paths, relative to the repository root. Omit for every changed file.
context
int
3
Lines of context around each change, 0 to 20.
Result field
Type
Description
session
string
The session of the pane.
window
string
The pane, by id.
worktree
string
The root of the work tree.
checkpoint
object
The checkpoint read: n, ref, commit, tree, head, kind (turn or safety), pane, session, turn, state, label, worktree, at (Unix nanoseconds), and skipped and skipped_count (the untracked files left out as larger than max_untracked_mb, omitted when none).
base
string
What the diff runs from: checkpoint N, HEAD <hash>, or an empty tree.
base_tree
string
The tree the diff runs from.
files
[]object
One entry per changed file, as review-diff returns them.
totals
object
files, added and removed over the whole diff.
truncated
bool
The diff passed a cap (400 files, 2 MiB, 5000 lines in a file) and the files past it carry counts only.
untrusted
bool
Always true: the text is the repository's, not the daemon's.
Close one Inbox item for the person. Only a client attached right now can do it, with the nonce from its attach reply: an agent cannot clear what is waiting for the person. Dismissing a finished item marks the pane's turns seen, and dismissing mail marks the person's mail in the thread read. An item of a linked host is hidden on this daemon only, until that host changes it; nothing on that host is marked.
Param
Type
Required
Default
Description
id
string
The item id list-attention printed.
human_nonce
string
The nonce the daemon issued in an attach reply, for a client attached now over the same kind of connection. The TUI sends its own.
Result field
Type
Description
id
string
The item that was closed.
kind
string
Its kind. One of approval, plan, ask, question, mail, errored, resume, finished, outbox or held_mail.
session
string
Its session.
host
string
The linked host the item came from. Omitted for this machine.
dismissed
bool
Always true on success.
{"id":1,"verb":"dismiss-attention","params":{"id":"17","human_nonce":"<from the attach reply>"}}
Read a held approval or plan whole: the summary, the tool and its target, the answers it takes, the plan text of a plan, and the risk rules its command matched with why. Served only while the hook holds it. The text is the agent's, so it is marked untrusted.
Param
Type
Required
Default
Description
request_id
string
yes
The request_id of the Inbox item.
session
string
The session the approval is in. When given, an approval in another session is not found. From a pane without the admin grant it is the pane's own unless named.
List the Inbox: everything in every session waiting for the person, on this machine and on every linked host. An item is an approval, a plan to approve or a question (a pane on needs_input), a question put with ask-human (kind ask), mail to human, a pane on errored, or a finished turn nobody has looked at. Items are grouped in that order, oldest first inside each group. Every change to the list is an attention event on subscribe.
Param
Type
Required
Default
Description
session
string
Only list items in this session. Omit for every session. Unlike most verbs, an omitted session does not mean the most recently active one. Without host it names a session on this machine.
kinds
[]string
Only list these kinds. Omit for all of them. One of approval, plan, ask, question, mail, errored, resume, finished, outbox or held_mail.
host
string
Only list items of this machine: "local" for this one, or a linked host by name. Omit for every machine.
select
string
A selector: space-separated key:value terms, all of which must match, each with comma-separated alternatives. Keys: harness (id or program name), state, needs:you, session (glob), group (fan-out group, glob), host (local or a host name, glob), name (window name, glob), cwd (the directory or under it; ~ is home), task (a task card the pane holds, by id, glob), stage (the stage of a card the pane holds), parent and root (the parent agent pane, or the first of its chain, by window id or a start of it). Keeps the items it matches. An item's state is the one its kind stands for: needs_input for an approval or a question, errored, and done for finished; mail and resume have none. group and cwd are known only for items of this machine.
include_snoozed
bool
false
Also list the items the person snoozed, each with snoozed_until.
Result field
Type
Description
items
[]object
One entry per item: id, kind, host, session, window, workspace, harness, name, summary, options, request_id, expires, always_scope, since, seq, thread, count, completion_seq, stale, seen_at. request_id, expires and always_scope are set only on an approval a hook holds on this machine (see request-approval); options is then the decisions reply-approval takes. An ask item carries request_id and options too: the question's id and its answers, which answer-ask takes. since is when the item started waiting, in unix nanoseconds. seq is the Inbox revision of its last change. summary is one line, with control characters removed, likely secrets masked and at most 160 bytes. thread is the mail thread, and count is the unread messages it stands for (mail) or the turns (finished). seen, on a mail item, is how many of count were seen with a peek and not read. host is empty for this machine; an item of a linked host has an id of the form host:id. stale is true for an item of a host whose link is down, and seen_at is when that host was last heard from, in unix nanoseconds. Additive fields, each absent when unset: snoozed_until on a snoozed item listed with include_snoozed (unix nanoseconds, -1 for until it changes), marked_unread on a finished item the person reopened, risk (the risk rules an approval matched), deny_message (the harness takes a reason with a deny), and plan_lines and plan_sha on a plan item.
counts
object
Open items per kind over the whole Inbox, every machine included, before the session, kinds and host filters. Every kind is present.
total
int
How many items are listed.
seq
int
The event seq the answer is current to. Subscribe with after_seq set to it and the boot_id below, and every attention event after the listing is replayed.
List the checkpoints of a pane: the state of its git work tree, saved each time its agent finished a turn that changed a file, and before each restore. Oldest first. The labels are the agent's prompts, so the result is marked untrusted.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. Omit to target the focused window.
Result field
Type
Description
session
string
The session of the pane.
window
string
The pane, by id.
worktree
string
The root of the work tree the pane is in, symbolic links resolved.
enabled
bool
Whether checkpoints are taken: [agents.checkpoints] enabled.
keep
int
How many checkpoints one pane keeps: [agents.checkpoints] keep.
checkpoints
[]object
One entry per checkpoint: n, ref, commit, tree, head, kind (turn or safety), pane, session, turn, state, label, worktree, at (Unix nanoseconds), and skipped and skipped_count (the untracked files left out as larger than max_untracked_mb, omitted when none).
List the messages waiting in a pane's delivery queue, or in every pane of the session.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. Omit to list every pane of the session.
host
string
A machine from [hosts]: list a pane's queue there, over the link. Session and window name the pane there. The person's replies queued from this machine are by link:THIS-MACHINE there. Only a caller outside every pane may ask; the far machine's policy for this one must allow list.
Result field
Type
Description
session
string
The session listed.
entries
[]object
id, session, window, name, at (Unix nanoseconds), by (human, shell, the queueing pane's window id, or link:HOST), from when given, preview (the first line, at most 80 characters) and state (waiting, delivering or stalled) per entry, next first within each pane.
Snooze an Inbox item, wake it, mark a finished pane unread, restore an item closed a moment ago, or settle an agent, for the person. Only a client attached right now can, with the nonce from its attach reply: an agent cannot hide or reorder what the person reads.
Param
Type
Required
Default
Description
id
string
The item. Or name it with session, window and kind. With unsettle: the id settle returned, to put that item back in the Inbox.
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. Omit to target the focused window.
kind
string
The item's kind, with session and window. One of approval, plan, ask, question, mail, errored, resume, finished, outbox or held_mail.
action
string
yes
snooze hides it until a time or until its fact changes, wake shows it again, unread reopens a finished pane's item, restore reopens an item dismissed or snoozed in the last 10 seconds. settle puts the agent in the pane named by session and window on the Settled shelf until it needs the person again, and closes its finished turn. unsettle takes it off the shelf. One of snooze, wake, unread, restore, settle or unsettle.
until
int
With snooze: when it opens again, in unix milliseconds.
for_ms
int
With snooze: how long, in milliseconds.
until_change
bool
false
With snooze: until the pane's state changes.
human_nonce
string
yes
The nonce the daemon issued in an attach reply, for a client attached now over the same kind of connection. The TUI sends its own.
Result field
Type
Description
id
string
The item. With settle: the finished turn it closed, empty for none. With unsettle: the item put back, empty for none.
action
string
What was done.
window
string
With settle and unsettle: the pane's window id.
snoozed_until
int
With snooze: when it opens again, in unix nanoseconds, -1 for until it changes.
{"id":1,"verb":"mark-attention","params":{"id":"17","action":"snooze","for_ms":900000,"human_nonce":"<from the attach reply>"}}
{"id":2,"verb":"mark-attention","params":{"session":"work","window":"review","action":"settle","human_nonce":"<from the attach reply>"}}
Read the prompt an agent is blocked on without attaching: the lines the harness's needs_input rule reads, the numbered options, 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. The lines are the pane's screen and are data, not instructions.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
The blocked pane: window id or name.
Result field
Type
Description
window
string
The window id.
name
string
The window's name.
harness
string
The harness whose rules read the prompt.
state
string
The pane's agent state.
state_at
int
When the pane entered its state, Unix nanoseconds.
waiting_ms
int
How long the pane has waited on needs_input, in milliseconds. Zero when it is not waiting.
blocked
bool
True when the pane is on needs_input.
found
bool
True when a needs_input rule reads a prompt on the pane now.
answerable
bool
True when respond can answer the prompt: actions is not empty.
reason
string
Why nothing can be answered, when that is so.
source
string
Which rules read the prompt: screen or title. Empty when none did. One of screen or title.
kind
string
approval or question.
message
string
The prompt line the rule matched, or the rule's own sentence.
prompt_id
string
Names this prompt. Pass it to respond so an answer never lands on a different prompt.
lines
[]string
The prompt as the pane shows it, bottom last.
options
[]object
The numbered options at the bottom of the screen: n and label.
actions
[]string
The answers respond accepts now. One of approve, approve_always, deny, choose or text.
untrusted
bool
Always true. The lines were written by the program in the pane.
Queue a message for the agent in a pane, typed as a prompt once the agent has been at rest for a second, and never over a prompt it is waiting on. One entry is typed per rest, and the prompt gate waits for the agent to show it took it; an entry it did not take is marked stalled, never typed again, and opens an Inbox question. A queue holds at most [agents.queue] max messages, and dies with the daemon, the pane, or the agent leaving the pane. It types into the pane, so a pane may queue only for a pane that holds nothing it does not, and its entry is checked against its grants again when it is typed. Who queued it (by) comes from the connection: human only with a live human_nonce, the pane's id for a pane, link:HOST over a link, shell otherwise.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
The agent's window, by id or name. Omit to target the focused window. It must run an agent tuios knows of; human is refused with no_keyboard.
text
string
The message, at most 16 KiB. Required without parts. With parts it is ignored, so a client can send the message both ways and a daemon older than parts types the text.
parts
[]object
The message as ordered parts, at most 64 and 8 MiB in all: {kind: text, text} for typed text, {kind: paste, text, n} for a pasted block, and {kind: image, data, n} for an image, data being the file in base64 (at most 8 MiB, 8 images a message), where n is the block's number as the person saw it. When the message is typed, its blocks go in their place if it is 12 KiB or less and the pane takes a bracketed paste. Otherwise each block is written to a file in the paste folder on the pane's machine, kept for 24 hours, and the typed text names it: [Pasted text #1: PATH, 42 lines]. Each image is written to a file there too; the harness's [input] images says whether its path goes in a paste of its own (path_paste), in the text (path_text), or is refused (none). The text parts with the labels must fit 16 KiB. Over a link, blocks need files in the link's policy.
human_nonce
string
The attached client's nonce, to queue as the person (by human). One that does not verify is refused with not_human.
from
string
The window the message is from. From a pane, its own; omit it there. human needs human_nonce.
client_id
string
The client's own name for this message, at most 128 bytes. Use a random id. A second call from the same sender with the same client_id for the same pane queues nothing and answers as the first did, with duplicate true. The daemon keeps the last 256 for 7 days, in memory, and forgets them when it restarts. It does not go with host.
host
string
A machine from [hosts]: queue for a pane there. This daemon passes the message to that machine's daemon over the link, where it is queued by link:THIS-MACHINE and typed. Session and window name the pane there. Only a caller outside every pane may send one; the far machine's policy for this one must allow write, and files for a block or an image.
Result field
Type
Description
id
string
The entry, which cancel-queued takes.
position
int
Its place in the queue, 1 for next.
queued
int
How many entries the queue holds now.
delivering
bool
True when it is next and the agent is at rest now, so it is typed within about a second rather than after the agent's turn.
parts
int
With parts, how many were read. A daemon older than parts leaves it out.
duplicate
bool
True when client_id was seen: nothing was queued, and the rest is the first answer.
{"id":1,"verb":"queue-prompt","params":{"session":"work","window":"build","text":"make the backoff jitter configurable"}}
{"id":1,"verb":"queue-prompt","params":{"session":"work","window":"build","parts":[{"kind":"text","text":"this test fails: "},{"kind":"paste","text":"--- FAIL: TestJitter\n...","n":1}]}}
Pass a message from another machine that this machine held for the person (hold_mail in its link policy) on to the window it was for. Only the person at a client attached right now can, with the nonce from its attach reply. The message is delivered as a new message with its original sender and origin, and the held copy is marked read. A message is released once.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
id
int
yes
The message_id of the held message, as read-agent-messages -w human shows it, or held_id on its Inbox item.
human_nonce
string
The nonce the daemon issued in an attach reply, for a client attached now. The TUI sends its own.
Result field
Type
Description
held_id
int
The held message.
message_id
int
The message that was delivered.
to
string
The window it was delivered to, empty for a notice.
to_name
string
That window's name.
thread_id
int
The delivered message's thread.
{"id":1,"verb":"release-agent-message","params":{"session":"work","id":12,"human_nonce":"<from the attach reply>"}}
Answer a held approval for the person. Only a client attached right now can, with the nonce from its attach reply: an agent never can. The first reply wins; a later one is answered with the decision that stands and applied false. A decision closes the Inbox item as answered and moves the pane to working. ask gives the prompt back to the pane with no decision.
Param
Type
Required
Default
Description
request_id
string
The request_id of the Inbox item. Or name the pane with session and window instead.
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
The pane whose held prompt to answer, when request_id is not given.
decision
string
once, always or deny, whichever the item's options offer, or ask to give the prompt back to the pane. One of once, always, deny or ask.
message
string
The reason for a deny, which the harness passes to the model. One line, at most 500 bytes.
human_nonce
string
The nonce the daemon issued in an attach reply, for a client attached now over the same kind of connection. The TUI sends its own.
summary
string
The item's summary the decision was made from. Required for once and always: an allow without it is refused with invalid_params and nothing is answered. When the hold is now on another line, nothing is answered: applied is false with reason changed, and the hold runs on. A deny may leave it out.
risk_ack
[]string
For once or always on an item that matched risk rules: exactly the item's risk list, which says the person saw them. Without it such an allow is refused with risk_unacknowledged. A deny needs none.
plan_sha
string
For a plan item: the plan_sha of the plan that was shown. An answer without it, or for another plan, is not applied.
Result field
Type
Description
request_id
string
The hold that was answered.
decision
string
The decision that stands: this reply's when applied, an earlier one's when not, ask when the prompt was given back, empty when the line changed.
applied
bool
False when an earlier reply had already answered it, or the line changed.
reason
string
How the hold ended: answered, or handed_back. changed when the hold is on another line than summary, and nothing was answered.
summary
string
With reason changed, the line the hold is on now.
answered_by
string
The id of the client whose answer stands.
session
string
The pane's session, when the reply ended the hold.
window
string
The pane, when the reply ended the hold.
{"id":1,"verb":"reply-approval","params":{"request_id":"9f86d081884c7d65","decision":"once","human_nonce":"<from the attach reply>"}}
Read what the person sent to an agent, oldest first, for the reply editor's up and ctrl+r. It is kept in the daemon's memory only and ends with it: 100 messages a target, 64 targets, the least used going first. Only the person reads it, with a live human_nonce.
Param
Type
Required
Default
Description
target
string
yes
The key the client keeps the history under, such as the agent's harness and folder. At most 512 bytes.
human_nonce
string
The nonce from the attach reply of a client attached now. The TUI sends its own. Without a live one the call is not the person's.
Result field
Type
Description
target
string
The target read.
entries
[]object
parts (as queue-prompt takes them), at (unix ms), and dropped: the blocks too large to keep, such as "Pasted text #1".
{"id":1,"verb":"reply-history","params":{"target":"claude-code:/work/api","human_nonce":"<from the attach reply>"}}
Hold a pane's permission prompt for an answer from the Inbox. tuios agent-hook calls it for a harness named in [agents.approvals]; the call does not answer until the person answers with reply-approval or the hold ends, and a hold that ends with no decision leaves the harness to ask in its pane. The pane must already be on needs_input with kind approval. Refused over a link, and a caller inside a pane may only hold its own pane's prompt. Send nothing else on the connection while it waits: the daemon reads it only to see the caller go, and a byte sent is discarded.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
The pane whose prompt is held, normally $TUIOS_PANE_ID.
harness
string
The harness the prompt belongs to, by id or alias. Nothing is held unless [agents.approvals] enabled names it, or the pane is one start-agent --protocol opened.
options
[]string
The decisions the harness can take. Omit for once and deny. always is dropped unless always_scope shows what it adds. One of once, always or deny.
summary
string
The line the person answers from: the whole request, as the hook reported it. The held item shows it for as long as the hold runs. Nothing is held (reason not_shown) when the Inbox could not show it as it is: longer than 160 bytes, with a control or format character, whitespace it would collapse, or text it would mask.
always_scope
[]string
What always allows from now on, one rule per line, shown beside the key. Required for always to be offered: one to four lines, each shown as it is.
kind
string
approval
What is held: approval for a tool call, plan for a plan an agent in plan mode asks to have approved. One of approval or plan.
plan
string
With kind plan: the plan's text, at most 32 KiB. get-approval serves it while the hold runs.
tool
string
The tool the call is for, as the harness names it (Bash, Edit), which the risk rules match on.
target
string
What the tool acts on: the command line, or the path.
deny_message
bool
false
Whether the harness passes a reason with a deny to its model, so the Inbox may offer to type one.
cwd
string
The folder the call runs in, as the harness sent it. The risk rules resolve a relative path against it. Omit it and the pane's own folder is used.
Result field
Type
Description
request_id
string
The hold's id, empty when nothing was held.
decision
string
The person's answer, or empty when there is none and the harness should ask in its pane. One of once, always or deny.
message
string
What the person gave as the reason for a deny, one line.
reason
string
Why the call returned: answered, or why there is no answer. disabled: the harness is not in [agents.approvals]. not_blocked: the pane is not on needs_input with kind approval. not_shown: the summary could not be shown as it is. viewed: the person has the pane in front of them, or turned to it. timeout, handed_back (enter on the item, or reply-approval ask), superseded (a newer request for the pane), caller_gone, shutdown, and the Inbox close reasons resolved, dismissed, window_closed, session_closed and evicted.
answered_by
string
The id of the client the answer came from.
{"id":1,"verb":"request-approval","params":{"session":"work","window":"build","harness":"claude-code","options":["once","always","deny"],"summary":"approve Bash: go test ./...","always_scope":["Bash(go test:*) in .claude/settings.local.json"]}}
Answer the prompt an agent is blocked on, with the keys its harness's manifest declares, without attaching. It reads the prompt again first and refuses with prompt_changed when the pane left needs_input, when the prompt is not the one prompt_id names, or when another client already answered it: the first answer wins. It then waits up to timeout for the pane to leave needs_input and returns its state. Only the person may call it: a client attached right now passing its attach nonce, or, when the daemon runs with [daemon] respond_from_shell, a process outside every pane. A pane the person gave the respond grant may also call it, for a pane in its own session, in its fan group when it also holds fan, and anywhere when it also holds admin.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
The blocked pane: window id or name.
action
string
The answer. approve, approve_always and deny press the keys the rule declares; choose presses an option's number; text types value and submits it. One of approve, approve_always, deny, choose or text.
value
string
The option number for choose, or the answer for text.
prompt_id
string
The prompt_id peek-prompt gave. With it, a prompt that changed since the peek is refused rather than answered. Without it, whatever prompt is on the pane now is answered.
human_nonce
string
The nonce from the attach reply of a client attached now. The Inbox sends its own.
timeout
int
5000
Milliseconds to wait for the pane to leave needs_input after the answer, at most 30000.
risk_ack
[]string
For an approving action on a prompt that matched risk rules: exactly the rules it matched. A deny needs none.
Result field
Type
Description
window
string
The window id.
action
string
The action taken.
sent
string
What was pressed, in words: the keys, or text.
prompt_id
string
The prompt that was answered.
settled_by
string
How the wait ended: state (the pane left needs_input), prompt (another prompt, or none, is on the screen), gone (the window closed) or timeout. One of state, prompt, gone or timeout.
state
string
The pane's agent state when the wait ended.
message
string
The pane's agent message when the wait ended.
by_pane
string
The pane that answered under its respond grant. Absent when the person answered.
{"id":1,"verb":"respond","params":{"session":"work","window":"a1b2c3d4","action":"approve","prompt_id":"<from peek-prompt>","human_nonce":"<from the attach reply>"}}
Put a pane's git work tree back to a checkpoint. The work tree is first saved as a safety checkpoint, so the restore can be undone by restoring that one. Only files that differ are written or removed. The index, HEAD, the branch and ignored files are not changed. Refused while the pane's agent is working or waiting on a prompt, unless force is given.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. Omit to target the focused window.
n
int
yes
The checkpoint to restore.
force
bool
false
Restore while the agent is mid-turn.
Result field
Type
Description
session
string
The session of the pane.
window
string
The pane, by id.
worktree
string
The root of the work tree.
restored
object
The checkpoint restored.
safety
object
The checkpoint that holds the work tree as it was before the restore. Restore it to undo.
written
[]string
The files written from the checkpoint.
removed
[]string
The files removed, which the checkpoint does not have.
skipped
[]string
The submodules that differ from the checkpoint. A restore does not change a submodule.
Read what the agent in a pane changed: the diff of its worktree against the base it was made from, or for a plain repository against the upstream merge base, untracked files included (one larger than max_untracked_mb is listed as skipped and not read) and ignored files left out. Nothing in the repository, its index or its working tree is changed. The text is the repository's, so it is marked untrusted.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. Omit to target the focused window.
base
string
The ref to diff against. Omit for the worktree's base, else the upstream merge base, else HEAD (uncommitted changes only).
against
string
A fan sibling session to diff against instead of a base: the two attempts compared with each other.
uncommitted
bool
false
Only what is not committed yet, against HEAD.
paths
[]string
Only these paths, relative to the repository root. Omit for every changed file.
context
int
3
Lines of context around each change, 0 to 20.
index
string
Read the worktree's index instead of the base. unstaged is the index against the working files, untracked files included. staged is HEAD against the index. Omit for the diff against the base. Not with base, against or uncommitted. One of unstaged or staged.
highlight
bool
false
Add the syntax colour and the changed part to each line: hl and changed. classes names the colour classes.
Result field
Type
Description
session
string
The session of the pane reviewed.
window
string
The pane reviewed, by id: the one its notes are kept for.
repo_root
string
The repository's main checkout.
worktree
string
The worktree the diff was read from, symbolic links resolved.
base
string
The base as named (the ref given, the worktree's base, the upstream branch, or HEAD), empty with against. With index unstaged it is index, with index staged it is HEAD.
base_sha
string
The commit the diff runs from: the merge base of HEAD and the base, or HEAD for uncommitted changes only. With index it is a tree: the index, or HEAD's tree.
index
string
The index mode read, unstaged or staged. Absent without index.
classes
[]string
With highlight: the names of the colour classes, in the order of their numbers in hl. Absent without highlight.
uncommitted
bool
The diff shows only what is not committed: asked for, or no base was found.
tree_sha
string
The tree the working state was written to, for a later diff of the same state.
against
string
The sibling session, when one was given.
against_tree
string
The tree the sibling's working state was written to, with against.
files
[]object
One entry per changed file: path, old_path, status (A, M, D, R, or U for untracked), added, removed, binary, truncated, and hunks, each with header, old_start, old_lines, new_start, new_lines and lines of op (context, add or delete), old, new, text and no_newline. With highlight a line also has hl, its colour as [start, end, class] runs in bytes of text, and changed, the [start, end] bytes that changed against its paired line. Each is absent when empty.
totals
object
files, added and removed over the whole diff.
truncated
bool
The diff passed a cap (400 files, 2 MiB, 5000 lines in a file) and the files past it carry counts only.
notes
[]object
The pane's review notes, found again in this diff, as review-note lists them.
untrusted
bool
Always true: the text is the repository's, not the daemon's.
Keep the review notes on a pane's changes: add one on a line or a hunk, edit, remove, list or clear them. Notes are held by the daemon per worktree, so every client and the CLI see the same ones, and follow their line as the diff moves. A note is the person's only with a live human_nonce, and a pane without admin adds or edits notes only on panes it could type into.
Param
Type
Required
Default
Description
action
string
yes
What to do. One of add, edit, remove, list or clear.
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. Omit to target the focused window.
path
string
The file the note is on, relative to the repository root. Needed to add.
line
int
The line the note is on, on side. Omit with hunk for a note on the whole hunk.
side
string
new
Which side of the diff line counts on. One of new or old.
quote
string
The text of the line, which finds the line again when the diff moves.
hunk
string
The hunk header the note is on.
text
string
The note, at most 1000 bytes. Needed to add and edit.
id
string
The note to edit or remove.
human_nonce
string
The nonce from the attach reply of a client attached now. The TUI sends its own. Without a live one the call is not the person's.
Result field
Type
Description
session
string
The session of the pane.
window
string
The pane the notes are for, by id.
worktree
string
The worktree the notes are kept on.
id
string
The note added or edited.
removed
int
How many notes remove or clear dropped.
kept
int
clear only: how many of the pane's notes were left because this caller may not change them (the person's, or another pane's or machine's).
notes
[]object
The pane's notes after the call, by path then line: id, path, side, line, quote, hunk_header, text, by, at, sent_at and outdated.
{"id":1,"verb":"review-note","params":{"action":"add","session":"work","window":"build","path":"api/retry.go","line":42,"quote":"if err == nil {","text":"log the attempt number here too"}}
Stage or unstage a change in the worktree of a pane. Name a whole file, one hunk, or some lines of a hunk. Only the index changes. The working files do not change. Every result carries an undo object. Send it back with action undo to undo the call. The undo result carries its own undo object, which redoes the call.
Param
Type
Required
Default
Description
action
string
yes
What to do. One of stage, unstage or undo.
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. Omit to target the focused window.
path
string
The file, relative to the repository root. Needed to stage and unstage.
hunk
string
The hunk header, exactly as review-diff returned it. Stage reads it from index unstaged, unstage from index staged. Omit for the whole file.
lines
[]int
Indices into the lines of the hunk. Only added and removed lines count. Context lines are ignored. Omit for the whole hunk.
context
int
3
The context of the diff the hunk came from, 0 to 20. It must match that diff.
undo
object
For action undo: the undo object of the result to undo, with entries and after.
human_nonce
string
The nonce from the attach reply of a client attached now. The TUI sends its own. Without a live one the call is not the person's.
Result field
Type
Description
session
string
The session of the pane.
window
string
The pane, by id.
worktree
string
The worktree whose index changed.
path
string
The file named.
action
string
The action done: stage, unstage or undo.
undo
object
entries: the index entries of the paths touched before the call, each path with mode and sha, or absent. after: the same paths after the call. Send it with action undo to undo the call.
Send a pane's unsent review notes to its agent as one message, through the delivery queue: typed now when the agent is at rest, else when it next comes to rest. The message says it is from the person only with a live human_nonce, and labels each note written by someone other than the sender with its author. It types into the pane, so a pane may send only to a pane that holds nothing it does not, and a note whose author may not type there now is withheld.
Param
Type
Required
Default
Description
session
string
Session name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
window
string
Window id or name. Omit to target the focused window.
ids
[]string
Only these notes. Omit for every unsent one.
now
bool
false
Type it now or not at all: refuse with agent_blocked or not_ready instead of queueing.
human_nonce
string
The nonce from the attach reply of a client attached now. The TUI sends its own. Without a live one the call is not the person's.
Result field
Type
Description
notes
int
How many notes the message carries.
ids
[]string
The notes sent, now marked with sent_at.
queued_id
string
The queue entry, which cancel-queued takes.
position
int
Its place in the pane's queue, 1 for next.
queued
int
How many messages the pane's queue holds now.
delivering
bool
The message is next and the agent is at rest, so it is typed within about a second.
withheld
[]string
Notes left out, not sent and not marked: their author (a pane, or a linked machine) may not type into this pane now, or the pane that wrote them is gone. Absent when none.
withheld_reason
string
Why the first withheld note was left out. Absent when none.
{"id":1,"verb":"send-review","params":{"session":"work","window":"build","human_nonce":"<from the attach reply>"}}
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.