Verbs: Agents and messages
Verbs: Agents and messages: 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.
restrict-connection
Give up authority on this connection for as long as it is open. It is how a
caller that drives tuios for an agent, tuios mcp above all, makes the daemon
hold every later call on the connection to what the agent was granted, so a
prompt-injected agent cannot reach further through that caller than the grant.
Params:
scope:own(the default) orall. Underownthe connection reaches only the caller's own session, the sessions in its fan group (sessions a singlefanstarted together, in the same repository) and the sessions afanrun from its session started.allleaves the sessions alone, forread_onlyby itself.read_only: refusesend-text,send-keys,ask-agent,respondandfan. The caller may still read, report its own pane's state and meta, and leave mail.pane_id,pane_token: the caller's$TUIOS_PANE_IDand$TUIOS_PANE_TOKEN, for when the kernel cannot place the caller.
The caller's pane is found first from the kernel's record of the process that
connected (SO_PEERCRED on Linux, LOCAL_PEERPID on macOS), walked up to a
pane's shell or matched by its controlling terminal, the same way
request-approval places its caller. Only when that places the caller in no
pane is pane_id checked against pane_token, an HMAC of the window id under
a key the daemon picks at start and never writes down. A pane_id that
disagrees with the kernel's answer is refused with forbidden, and so is a
token that does not match. A caller placed in no pane gets an empty window
and no error; under own it then reaches no session at all. Over a link the
kernel's answer is the local proxy's, and tokens are never good there, so a
restricted link connection reaches nothing under own.
A later call may narrow further (turn on read_only, or go from all to
own) and never widen: lifting read_only, going back to all, or naming
another pane is refused with forbidden, and the connection keeps the
restriction it had.
Result:
{"result": {"type": "connection_restricted", "scope": "own", "read_only": true,
"window": "7f3c...", "session": "work", "via": "pid", "sessions": ["work", "work-fan-retry"]}}via is pid, token, or empty when no pane was found. sessions is
present under own and lists what the connection reaches now; sessions a
fan starts later join it.
What a restricted connection may call:
| Class | Verbs | Under own | Under read_only |
|---|---|---|---|
| open | hello, list-verbs, unsubscribe, restrict-connection | allowed | allowed |
| across sessions | list-sessions, list-clients, list-attention, list-worktrees, list-hosts, list-host-sessions, list-host-agents, list-themes, list-glyphs, list-hooks, get-keep-awake | forbidden | allowed |
| read one session | session-info, list-windows, get-window, list-workspaces, capture-pane, get-agent-state, list-agents, wait-for, subscribe, peek-prompt, read-agent-messages, explain-agent-screen, list-options, get-option, stash-list, stash-get, ssh-agent-path, display-env | session in reach | allowed |
| own pane's record | set-agent-state, set-agent-meta, set-agent-session, report-agent-activity, agent-hook-event, agent-statusline-event, report-program-status, agent-mail-notice, ask-human | own pane only | allowed |
| mail and stash | send-agent-message, stash-put | session in reach, sent as the own pane | allowed |
| type into a pane | send-text, send-keys, ask-agent, respond, run | session in reach | forbidden |
| start sessions | fan, start-agent | needs a pane; start-agent opens its pane in a session in reach | forbidden |
| read the paste buffers | list-buffers, show-buffer | forbidden | allowed |
| change the paste buffers | set-buffer, delete-buffer | forbidden | forbidden |
| paste a buffer | paste-buffer | forbidden: it reads the buffers | forbidden |
| everything else | forbidden | forbidden |
Under own:
- A verb that takes
sessionand names none gets the caller's own session.subscribewith no session streams every session in reach, and each event is checked as it is written, so a session that joins the reach later is streamed from then on. Events that name no session, and events relayed from linked hosts, are not written. all_sessionsonlist-agentsandlist-tasks,any_sessiononwait-forandhostsonsubscribeare refused.selectis refused on every verb butlist-agents, where it reads only the caller's own session: a selector reaches every session.- A
hostnaming another machine, such assend-agent-message's outbox delivery, is refused: no session on another machine is in reach. set-agent-state,set-agent-meta,set-agent-session,report-agent-activityandreport-program-statuswith nowindowland on the caller's own pane, and naming another pane is refused.send-agent-messageandask-agentin the caller's own session getfromset to the caller's pane, and a differentfromis refused.read-agent-messagesmay name only the caller's own inbox into.
This scopes what goes through a restricted connection. A process in a pane can still open a connection of its own with the tuios CLI and not restrict it; a harness's shell tool can do that. What the restriction bounds is the MCP surface, which is what an agent reaches without writing a shell command, and the one a harness can offer without a shell tool at all. Pane grants, below, bound that connection too.
pane-grants
Say what the caller may do through tuios. Every pane holds a set of grants,
and the daemon holds every JSON verb and every client protocol message from a
connection placed in a pane to them, before the handler runs and before
restrict-connection is applied. A connection placed in no pane (the
person's own CLI, the attached client, the hooks and dock components the
person configured) is held to nothing new.
| Grant | Allows |
|---|---|
read | Read the pane's own session and the sessions of its fan group (the reach restrict-connection calls own): listings, captures, agent state, waits, the event stream, mail and stash reads |
write | Type into the panes of its own session (send-text, send-keys, ask-agent, run) that hold nothing it does not, and leave mail and stashed files there |
fan | What write allows, in the sessions of its fan group and the sessions it launched, and start agents with fan and start-agent |
respond | Answer an on-screen prompt with respond, without the person's human_nonce, on a pane in its reach, and type into a pane on needs_input |
files | The transfer verbs, held to two rules. transfer-start: each end on this machine is inside the pane's folder (its session's worktree when tuios made it, else the folder the pane started in; a cd or an OSC 7 does not move it, and the home folder, a folder above it or a folder another user owns is never one. The folder is resolved through its links once, when it is recorded), and every file the copy reads or writes here goes through an os.Root at that folder, and each end on a host is under that host's home or is its receive folder (no path). The other transfer verbs see and act on only the copies the pane started. A pane without admin starts windows (new-window, new-session, popup, start-agent, a plugin pane) only inside its folder, and types only into panes whose files folder is inside its own |
task | The task verbs that change a card (add-task, claim-task, finish-task, set-task-stage, block-task, release-task) in the pane's own session. A pane claims only for itself and changes only the card it holds. See Task verbs |
admin | Everything else, as every pane could before grants: every session, the listings across sessions, windows, layouts, options, kill-session, any task card and remove-task, and the client protocol (attach, and run-command, which sends a client protocol message). Implies read, write, fan, files and task, never respond |
Whatever it holds, a pane may call hello, list-verbs, unsubscribe,
restrict-connection, pane-grants and resolve-pane, and report about
itself: set-agent-state, set-agent-meta, set-agent-session,
report-agent-activity, ask-human and request-approval, on its own pane
only.
A pane holds the grants it was given: new-window, start-agent and fan
take grants, and set-pane-grants changes them later. A pane given none
holds the default of [agents.permissions] in config.toml: admin under
mode = "open", which is the default mode, and the grants list under
mode = "strict" (default read, write, fan). A mode the daemon does not
know is read as strict, and an unknown grant name is dropped.
A pane can never hand out more than it holds. From a pane that does not hold
admin, a launch that names no grants gives the new pane the caller's own,
and a grants the caller does not hold is forbidden. admin cannot give
respond. A link or a pane run for another machine cannot give respond.
A pane cannot gain grants by typing either. What is typed into a pane runs
with that pane's grants, so a pane without admin that calls send-text,
send-keys, run or ask-agent on any pane but its own is also held to the
target pane:
- The target must hold nothing the caller does not, counting what
adminimplies. Otherwise the call isforbidden, and the message names what the target holds. - A target on
needs_inputisforbiddenunless the caller holdsrespond, since keys typed there answer its prompt.ask-agentwithoutallow_blockedanswersagent_blockedfirst, as before. - A call that names no window is pinned to the pane focused when it is checked, and both checks run again right before anything is written.
send-keysfrom such a pane is written to the target's terminal, never routed through an attached client, where the prefix key drives the window manager.
respond is not held to the first rule: the respond grant is the person's
consent to answer prompts on the panes in the pane's reach.
A pane that holds admin is held to the second rule for send-text,
send-keys, run, ask-agent and client protocol input: into another pane
on needs_input it is forbidden unless it also holds respond. A pane
without respond, admin included, never types through the attached client:
send-keys with no window goes to the focused pane's terminal, PREFIX is
refused, and run-command may not press keys or type.
How a connection is placed in a pane, strongest first:
- The kernel's record of the peer's pid (
SO_PEERCRED,LOCAL_PEERPID), walked up to a pane's shell or matched by its controlling terminal, asrequest-approvaldoes. A process does not change panes, so the answer is kept for the connection once it names one. - For a process the kernel places inside the daemon's panes but in no pane
yet, the
TUIOS_PANE_IDin its environment, when it names a pane the daemon is still creating. Every local pane is entered in the grant table before its process starts, so a process never runs before its grants hold. - Where the daemon cannot read the peer's pid (Windows, the BSDs), the pane
id and token the connection presents with
pane-grants. ThetuiosCLI does this on every connection it opens from a pane. The token is therestrict-connectiontoken: an HMAC of the window id under a key picked at daemon start, so it names one pane and cannot be made for another.
The daemon places a connection when it accepts it, and pins the process with
its start time. A connection whose process has exited, or whose pid now names
another process, is held to the grants list of [agents.permissions] in no
session. So is a process the kernel places inside the daemon's panes and in
none of them, such as a process the daemon starts outside every pane shell
(a hook, git, or what ssh runs); under open it holds admin, as a pane on
the default does. A process placed only by its environment is not held.
A connection on a link socket whose process runs inside a pane of this
daemon, or was started by the daemon, is refused with forbidden for every
verb and message: those sockets are for the link proxy, which sshd starts.
A connection over a link is held to that link's policy instead (see
What a linked machine may do here), and
a report from a pane run for another machine is held on the machine that owns
the pane. A call such a process makes to this machine's daemon directly holds
this machine's default and reaches no session here, so under strict it may
call only the verbs every pane may.
Params:
pane_id,pane_token: the caller's$TUIOS_PANE_IDand$TUIOS_PANE_TOKEN. Used only where the kernel places the caller in no pane; apane_idthat disagrees with the kernel isforbidden, and so is a token that does not match. A connection placed by token stays in that pane for as long as it is open, and a second pane's token isforbidden.
Result, from a pane:
{"result": {"type": "pane_grants", "pane": true, "window": "7f3c...", "session": "work",
"via": "pid", "grants": ["read", "write", "fan"], "explicit": false,
"mode": "strict", "default_grants": ["read", "write", "fan"]}}From outside every pane, pane is false and only mode and
default_grants are set. via is pid, env or token. explicit is true
for a pane given grants of its own.
A refusal:
{"error": {"code": "forbidden",
"message": "send-text is refused for this pane: writing into the pane's own session needs the write grant",
"hint": {"verb": "pane-grants", "command": "tuios pane-grants",
"detail": "Pane 7f3c1a2b holds read, the grants it was given. Nothing was done. The person can give this pane more with tuios set-pane-grants -w 7f3c1a2b --grants <names>, or every pane started with none with mode and grants under [agents.permissions] in config.toml."}}}The daemon log records every refusal. For a pane without admin, a verb that
takes session and names none gets the pane's own session, and a subscription
carries only the sessions the pane may read, as they stood at its subscribe.
This scopes accidents and prompt-injected agents that use tuios the ordinary way, not a determined local attacker: a process that leaves its pane on purpose (a double fork with a cleaned environment, a service manager) is not placed in it, and is then treated as the person, as the human checks are. See AGENT_STATE.md.
set-pane-grants
Give a pane grants, or with reset the default of [agents.permissions].
Params: session and window (omit either from a pane for its own; from
outside every pane session defaults to the most recently active one),
grants (names, or ["none"]), reset. Pass grants or reset, not both.
From outside every pane anything may be given. From a pane, the target must be
its own pane unless it holds admin, and what it gives, or the default for
reset, must be something it holds, so a pane can narrow itself and never
widen itself. Refused over a link and for a window on another machine. The
change applies to the pane's next call; TUIOS_PANE_GRANTS in the running
process is not rewritten. The grants are saved with the window and hold again
after a restore.
Result:
{"result": {"type": "pane_grants_set", "session": "work", "window": "7f3c...",
"grants": ["read"], "explicit": true, "previous": ["read", "write", "fan"], "previous_explicit": false}}artifact-list
List what one pane has shown the person, newest first. Params: window, the
pane's window id. Each artifact has id, kind (tml or screenshot),
title, at (Unix nanoseconds) and window_id. A tml artifact adds
surface, target, open, doc and state; a closed one adds reason
and value. A screenshot adds path and format. The daemon keeps the
last 20 of each pane, for the last 128 panes that showed something, until it
restarts. A pane reads its own list with no grant. Another pane's list needs
the read grant and the pane's session in scope.
start-agent
Start an agent in a new pane of a session, and answer once it is ready for a
prompt, on the same evidence fan waits for: idle or done, from a report,
a hook, the screen or the title, with unknown counting only for a harness
that can never show idle. A pane on needs_input ends the wait at once with
ready: false, outcome: "blocked" and blocked_by, and is kept: whatever it
asks is the person's to answer, and the Inbox already shows it. A pane that is
not ready for 30 seconds gets the same Inbox question as a held fan prompt.
With prompt, the first prompt is typed once the agent is ready and checked
the way fan checks it.
The session session names is created when it does not exist. With no
session, the most recently active one is used, or a new one named after the
harness or program when there is none. The pane starts in cwd, or in the
main checkout of the repository repo or repo_url names (see
new-worktree for repo_url, repos_root and clone), or
else in the caller's directory when the caller runs in a pane, or else in the
focused pane's directory. Passing cwd and a repository is
invalid_params. From another machine it is reached like every session verb,
with a host-qualified session, and names the repository by repo_url.
Params: session, agent (required, written as for fan), args (more
argv after the agent's own words), name (the window's name, which
list-agents shows and -w and name: take), cwd, repo, repo_url,
repos_root, clone, workspace, focus (default false), prompt,
ready_timeout (milliseconds, default 120000), env (the rules of fan),
protocol (acp or codex; see below).
The agent is checked before a clone, so a missing agent does not cost one. A
call that reaches the daemon
over a host link is refused with forbidden when it carries env, since the
variables describe the caller's machine. tuios start-agent -s host:session
therefore sends no env unless --env was passed, and the agent is looked up
on the far machine's PATH.
Response:
{"result": {"type": "agent_started", "session": "work", "session_id": "...", "created_session": false,
"window_id": "4be1c09a-...", "pty_id": "...", "workspace": 1, "name": "reviewer", "agent": "claude-code",
"command": "claude", "cwd": "/src/api", "ready": true, "ready_by": "idle", "state": "idle",
"outcome": "ready", "prompt_status": "sent"}}cloned is true when the call cloned the repository.
outcome is ready, blocked, timeout, window_closed (the program
exited), session_closed or shutdown, and reason says in words why a pane
is not ready. prompt_status is sent, stalled or not_sent with a
prompt_note, and absent without prompt.
Headless agents: protocol
With protocol, the agent runs headless over a structured protocol instead of
in its own TUI, and the pane shows the conversation as a transcript:
acpis the Agent Client Protocol, version 1:initialize,session/new,session/prompt,session/cancel,session/updateandsession/request_permission.agentis the agent's ACP command, such as"opencode acp".codexis the Codex app-server protocol, its v2 core:initializeandinitialized,thread/start,turn/start,turn/interrupt, theitem/*andturn/completednotifications, anditem/commandExecution/requestApprovalanditem/fileChange/requestApproval. A file change approval is never held for the Inbox, and itsgrantRoot, when set, is shown in the pane.app-serveris added to the agent's words when neither they norargsname it, between the two, soargsare the app-server's own.
The pane's process is this daemon's own binary, tuios agent-proto --protocol P --harness H -- <agent argv>, and it execs the agent's argv directly, with
pipes for its stdin and stdout, in a session of its own with no controlling
terminal. It advertises no file system and no terminal capability, and answers
every request it does not handle (fs/*, terminal/*, MCP elicitations,
dynamic tool calls) with method not found, so the agent can do nothing
through tuios that it could not do in its own TUI. Everything it shows is
cleaned of escape sequences and control characters before it reaches the pane.
It reports the pane's state with set-agent-state under the harness the
manifest named, or the protocol: idle once the conversation is open,
working during a turn, done with the reply's first line, errored with
why, and needs_input with kind approval and the request's line when the
agent asks permission. The pane is ready on that report alone. A prompt from
prompt, ask-agent or send-text is typed into its prompt line and sent as
one turn.
A permission is shown in the pane with a number key per answer. When its line
is the whole request (see request-approval: a command
with nothing the line leaves out, not a diff, an edit or input to a running
command), the pane program also holds it with request-approval, which a
protocol pane may do without [agents.approvals]. The first answer wins: a key
in the pane ends the hold by closing its connection, and a decision from the
Inbox answers the agent and is written into the pane. The Inbox offers once
and deny only, mapped to ACP's allow_once and reject_once or Codex's
accept and decline; the other answers, which allow more than the one call,
are the pane's. A digit answers only once the question has been on screen for
half a second, and a paste never answers. Ctrl+C in the pane cancels the turn
and answers the agent cancelled (Codex: cancel).
The result gains protocol, and command is the agent's command, not the pane
program's. list-agents shows protocol for the pane.
set-agent-state
Record the agent state a pane reports. Params: session, window, state
(required), message, source (default report), harness, and fields
a hook reporter adds, each optional. Without window, a caller in a pane
reports about its own pane, and its own session when session is omitted. A
caller outside every pane reports about the focused window, as before.
The optional hook fields:
kind:approvalorquestion, what aneeds_inputstate waits for. Only valid withneeds_input. Stored as the window'sagent_kindand reported byget-agent-stateandlist-agentsasblocked_by. Without it the kind is guessed frommessage, as described under Changes to existing verbs.agent_session_id: the harness's own conversation id. Stored as the window'sagent_session_id, persisted, and kept when the agent exits. It also turns on the nested-session guard below.transcript_path: the transcript file the harness writes. For a harness whose manifest has a transcript reader, the window is joined to exactly that file. It is held in daemon memory and never synced.transcript_leaf: the entry of a tree-structured transcript, which today is Pi's, that the harness has selected. It needstranscript_pathand a harness whose manifest names a tree reader, or the call isinvalid_params. At most 128 ASCII letters, digits,_or-. A present empty string selects the empty branch before the first entry. Omitting it keeps the selection already reported, or shows the branch that ends at the last complete entry for an older integration. It stays in daemon memory, never in persisted window state or events.if_state: comma-separated states. The report applies only while the window is in one of them.subagent_id: withneeds_inputonly, the subagent whose prompt the pane shows, 1 to 128 letters, digits,_,.,:,@or-. Omitted, the prompt is the pane's own agent's. Held in daemon memory.if_subagent_id: the report applies only while the window is on aneeds_inputthat named thissubagent_id, and is otherwise refused withif_state. A subagent's hook clears the prompt it raised with it, and leaves one the main agent or another subagent raised.notification: true on a report read from an event the harness sends once and never takes back, such as Claude Code'sNotificationandPermissionRequesthooks. Its state holds until the pane writes again, and from then on a look at the pane's title or screen may replace it, as for a desktop notification the pane sends. Claude Code sends nothing when a prompt goes without a tool running, after Esc at a permission menu or once a background agent's question is answered in its own view, so without this the pane stayed onneeds_input. Aneeds_inputmarked so ends on a look only while the screen reads idle (the empty prompt box), and only once that reading has held as long as a working pane's idle must: the title's rest glyph is drawn at a menu too. No working look ends it, whether a spinner in the title or a working line on the screen, since one can be drawn between the hook and its menu, nor does a desktop notification or the transcript. A hook's report ends it at once, such asPostToolUseonce the prompt is answered. A screen rule that takes the prompt over while it is drawn hands it back, message and kind included, when a frame no rule reads stands in its place. Claude Code'selicitation_url_dialogis sent without it, since no screen rule is known to read that form.harness_pid: the pid of the harness process that ran the hook. Read only withagent_session_id, and held in daemon memory. It lets a new session from the same harness process pass the nested-session guard below. When it is the calling process or one of its ancestors, its exit also clears a report's state once the pane is back at its shell.session_start: true on the report a conversation'sSessionStartsends. It matters only for a harness whose manifest setsshared_server. See the guard below.activity: the hook event itself, for the pane's activity ring:event(prompt,tool,tool_done,tool_failedorturn_end),tool,target,text,files,okandmodel, all optional butevent. It is recorded when the report passes the nested-session guard below, whether or not the state applies, and read back with agent-activity. It also sets the reserved metadata keysnowandprompt(see set-agent-meta). An unknowneventisinvalid_paramsand nothing is applied. The answer then carriesactivity_recorded.
Request:
{"verb": "set-agent-state", "params": {"session": "work", "window": "build", "state": "working", "if_state": "needs_input", "agent_session_id": "5f1c"}}Response:
{"result": {"type": "agent_state_set", "state": "done", "message": "", "source": "report", "applied": false, "reason": "if_state"}}state is what the window shows after the call. reason is present only when
applied is false: outranked (a higher-ranked source owns the window),
if_state (the condition did not hold), foreign_pane, foreign_session or
foreign_harness. foreign_pane refuses a report whose harness_pid is a
local process that inherited the pane in TUIOS_PANE_ID but runs outside it,
not the pane's process and not on its terminal, under a harness daemon,
even one that is itself a child of the pane: Claude Code's daemon or the pty host of its background
sessions. A harness under anything else that left the pane, such as a tmux
server or a rootless container's conmon, is taken for the pane that shows
it. A harness_pid that is not
the caller or one of its ancestors is not believed, and the caller is checked
in its place. A report without harness_pid, from a link, for a pane on
another machine, or from a harness that cannot be read (it exited, or the
platform has no process reader) is not checked. The last two refuse a report carrying agent_session_id
while the window's own harness is working or needs_input by its own report
and the report names a different session, or comes from a different harness:
a nested run, such as a claude -p a tool call started inside the pane. At rest
a different session is accepted and replaces the stored id. Mid-turn, a
different session is also accepted when its harness_pid is the one the
window's current session was reported with: that is a new conversation in the
same process, such as /clear after an interrupted turn that never reported
Stop.
A harness whose manifest sets shared_server = true (Codex) runs the hooks of
every conversation from one server process. A conversation in another
terminal can share that process, its pid and the pane's TUIOS_PANE_ID. For
such a harness, a report with session_start sets the conversation that owns
the window. A report for another conversation of the same harness is refused
with foreign_session, at rest and mid-turn, unless it carries
session_start. The last four conversations that owned the window are the
exception: the next report from one of them takes the window back, and the
owner it displaces joins the list. report-agent-activity from one of them is
not refused either. The daemon forgets both when the pane is back at
its shell. Until a session_start arrives, the window is open to any report.
set-agent-session is not guarded this way, and it clears the guard.
The server keeps the TUIOS_PANE_ID of the pane that started it, so its hooks
can name a window that is gone. Such a report, from a caller outside every pane,
goes to the one live pane of that harness that runs its conversation: the pane
that holds agent_session_id, the pane joined to transcript_path, or the pane
whose agent started in the transcript's folder near the transcript's start. The
answer then names that pane in session and window. With no such pane, or
with two, the report fails with window_not_found as before. The daemon records
the pane's agent process as the harness, not the server.
report-agent-activity is placed the same way, by agent_session_id only.
reason, activity_recorded and the hook fields are additive. A client that
sends none of the fields is handled exactly as before. A daemon older than them does not
reject them: params are decoded leniently, so it ignores the fields and applies
the report without them. A client that depends on one, if_state above all,
has to ask list-verbs for set-agent-state first and check the field is
listed. tuios agent-hook and tuios set-agent-state --if-state do, and the
hook sends activity only to a daemon that lists it.
set-agent-session
Store the conversation id a harness reports for a pane, without changing the
pane's agent state, the source that holds it, or its harness attribution. It is
what tuios agent-hook sends for a harness whose hooks can name the
conversation but cannot be trusted with its state, so the pane's screen rules
keep deciding the state. Params: session, window, harness (required),
agent_session_id (required, at most 256 bytes), harness_pid, and optional
transcript_path and transcript_leaf.
The transcript fields use the same checks and meanings as in set-agent-state.
They name the conversation already in the pane: a different session id is
refused with foreign_session, even at rest, so a delayed old report cannot
replace the current conversation. An accepted leaf change raises transcript
even when the file did not change. It does not change the state, its time, its
source, the prompt or the completion count. A rejected path is explained in
transcript_refused, and a refusal for the same conversation keeps the previous
join.
{"verb": "set-agent-session", "params": {"session": "work", "window": "build", "harness": "qwen", "agent_session_id": "5f1c", "harness_pid": 4100}}{"result": {"type": "agent_session_set", "agent_session_id": "5f1c", "applied": true}}The id is stored as the window's agent_session_id, the field
set-agent-state writes, persisted and read back by get-agent-state and
list-agents. agent_session_id in the result is the id the window holds after
the call. A report naming the id the window already holds is applied and changes
nothing. Three refusals keep another agent's id off the pane, with applied: false:
foreign_pane: the report'sharness_pidruns outside the pane its environment names, as forset-agent-state.foreign_harness: the window is attributed to a different harness.foreign_session: the window isworkingorneeds_input, holds a different id, and that id was reported by a known harness process other than the report'sharness_pid. The same process may replace its own id, and a report with no pid, or onto a window at rest, is applied. The daemon forgets the pid when the detector sees the agent leave the pane, so a harness restarted in the pane is not refused.
A report never attributes the window: a pane nothing has named stores the id
and stays a non-agent pane until the detector or a set-agent-state names its
harness.
Security: it grants a subset of what set-agent-state with agent_session_id
already grants any socket caller, the one field and no state.
Wire compatibility: a new verb. An older daemon answers unknown_verb, and
tuios agent-hook asks list-verbs first and sends nothing to a daemon
without it. The optional transcript fields are sent only when list-verbs names
them; an older daemon gets the identity report without them.
agent-hook-event
Runs one harness hook event in the daemon, the way tuios agent-hook runs it in
a process of its own, so a hook can report without starting tuios. Params:
harness (required, an id or alias such as claude-code or claude), event
(for a harness whose payload does not name it), payload (the hook's JSON
payload as a string) and env, the hook process's variables the mapping reads
(TUIOS_AGENT, CODEX_THREAD_ID, CURSOR_VERSION, GROK_SESSION_ID,
CRUSH_SESSION_ID; any other name is invalid_params). The result is
{"stdout": "..."}, what the hook would print for the harness to read, and
with explain the decision tuios agent-hook --explain prints.
The pane is never a param. The daemon finds it from the process that sent the
call, as the hook finds its own: that process's TUIOS_PANE_ID and
TUIOS_SESSION as the kernel reports them, else its terminal session and
ancestors matched against the panes' shells. A call from outside every pane
reports nothing. Each report the event makes is a set-agent-state,
set-agent-session, report-agent-activity, set-agent-meta,
agent-mail-notice or request-approval call on the caller's own connection,
checked as that call would be.
agent-statusline-event
Runs one status line payload in the daemon, the way tuios agent-statusline
runs it without --then: the model, context use and cost go to the caller's
pane as agent metadata, at most once every 15 seconds while they change.
Params: harness, payload or payload_json, env (the same variables as
agent-hook-event), turn_end and explain. The result is sent, skip and,
when finding the pane or writing failed, error. The pane is found from the
calling process as for agent-hook-event, and the one write is a
set-agent-meta on the caller's connection. With forwarder the reply is the
line TUIOS-HOOK-OK and the connection ends.
report-agent-activity
Record one hook event of a pane's own agent without reporting a state. It is
what tuios agent-hook sends for an event that says nothing about what the
pane's agent is doing: Claude Code's SubagentStart and SubagentStop, a
subagent's tool calls and the other news of a subagent (subagent_update),
and the session_start that follows a SessionStart's state report. Params:
session, window, activity (required), harness, agent_session_id,
harness_pid. Without window, a caller in a pane reports about its own
pane, as with set-agent-state.
activity is set-agent-state's activity with four more events, the list
list-verbs gives as accepted: subagent_start and subagent_stop, with
agent_id (required: 1 to 128 letters, digits, _, ., :, @ or -,
which pairs a start with its stop) and agent_type, a stop's text being
what the subagent said last; subagent_update; and session_start, with how
the conversation started as text. An unknown event, and a subagent event
without a valid agent_id, is invalid_params and nothing is recorded.
subagent_update is news about a subagent the pane holds. It names the
subagent by agent_id, or without one by call_id, the tool call that
launched it, and carries any of:
| Field | Meaning |
|---|---|
text | its description, which replaces the one it has; with outcome failed, the error |
tool, target | the tool call it runs; with ok, how that call ended |
outcome | stopping (the agent asked to stop it, so its stop reads as stopped) or failed (it ends now as failed) |
tools | how many tool calls it made |
call_id | the call that launched it, kept for a later update by call_id |
An update for a subagent the pane does not hold changes nothing. A call_id
that is not a valid id, an outcome other than those, or tools outside 0 to
1000000 is invalid_params. The ring keeps no update, except one that ends
the subagent, which it keeps as that subagent's subagent_stop.
A launch: a tool event, set-agent-state's or a subagent_update's, with
spawn: true names a subagent about to start, agent_type the type asked for,
target its description and call_id the call. The next subagent_start on
the pane takes the oldest launch of its type, else the oldest, within 30
seconds. An older daemon ignores spawn and records the tool event as before.
{"verb": "report-agent-activity", "params": {"session": "work", "window": "build", "harness": "claude-code", "agent_session_id": "5f1c", "activity": {"event": "subagent_start", "agent_id": "a3f09c2e71d4b5a68", "agent_type": "Explore"}}}{"result": {"type": "agent_activity_reported", "window_id": "3f2a9c1e", "state": "done", "recorded": true, "subagents": 3}}The event goes into the pane's activity ring and moves the reserved metadata
keys as set-agent-state's activity does, and nothing else moves: not the
state, its source or its stamp, the message or the harness attribution.
state in the answer is what the window shows, and subagents how many
subagents it holds after the call.
The pane's subagents:
subagent_startadds one andsubagent_stopends it:donewith atext,stoppedwithout one or afteroutcome: stopping. The window carries the running count asagent_subagents, and the reserved metadata keysubagentssays it in words. A pane holds at most 64 running.- The window also carries the list,
agent_subagent_list, whichget-agent-stateandlist-agentsreturn assubagent_list: id, type, description, state (running,done,failed,stopped), started_at, ended_at, now, last, tools and result, at most 16 in start order. An ended subagent stays a minute (five whenfailed), at most 8 of them per pane. recordedis false, and the ring keeps nothing, for a stop of a subagent the pane does not hold or already ended, a start past 64, a start on a pane whose state isnone, and a second start of one already running, which renews when the pane last heard of it. For asubagent_updateit says whether the update changed the subagent.- The tool calls of the subagents in one session are pushed to attached clients at most once per 250 ms: one that comes sooner is pushed with the next, by a timer armed only while such calls arrive.
- They are forgotten on
session_start, when the window's state goes tonone(aSessionEnd, the agent leaving the pane,set-agent-state none) and when the window closes. One the pane hears nothing more of for an hour, a stop lost to an interrupt, is dropped then, and the change is pushed like any other. They are daemon memory only.
The guard: a report naming a conversation other than the one the window
holds is refused with reason: foreign_session, and one naming a harness
other than the one it is attributed to with foreign_harness, at rest as well
as mid-turn, and one whose harness_pid runs outside the pane with
foreign_pane, as for set-agent-state. A state report from another
conversation takes a pane at rest over; this report never takes a pane over,
so another conversation's
subagent is not the pane's, such as one a claude -p the agent left running
in the background starts.
Rate: a pane may report a burst of 64 events, then 10 a second. A call past
that is rate_limited and records nothing. Each recorded event may push
state to every attached client, and the cap of 64 bounds memory, not pushes.
Who may call it: as set-agent-state, a pane for itself only; over a link it
needs write, and a hosted pane's process sends it to its owner.
Wire compatibility: a new verb. An older daemon answers unknown_verb, which
changes nothing: tuios agent-hook then reports the SessionStart's state
alone, and nothing for a subagent. A daemon from before subagent_update
answers it with invalid_params, and the hook sends no more updates for that
event.
resume-agent
Resume the agent conversation recorded for a pane: type the harness's resume command into the pane's shell. A daemon restart ends every program in every pane, and the restore starts a new shell in each; this is how a pane gets its conversation back. It brings back the conversation, not the process: the turn that was running when the daemon stopped did not finish.
Params: session, window (default: the focused window), dry_run (return
the command without typing it).
{"verb": "resume-agent", "params": {"session": "work", "window": "build"}}{"result": {"type": "agent_resumed", "window_id": "3f2a9c1e", "harness": "claude-code", "agent_session_id": "5f1c", "argv": ["claude", "--resume", "5f1c"], "command": "claude --resume 5f1c", "typed": true}}The command is the harness manifest's [resume] argv with {session_id}
replaced by the window's agent_session_id. The harness is the window's
agent_session_harness, else its harness_id for state written before that
field existed. The command is typed followed by a carriage return, and the
pane's resume Inbox item, if one is open, closes with reason resolved.
Failures, each with nothing typed:
not_resumable: noagent_session_idon the window; a harness with no[resume]block; an id that is empty, over 256 bytes, starts with-, or holds anything but letters, digits and_ . / : -; or a window whose process runs on another machine.not_ready: the pane's shell does not hold its terminal's foreground, so a program is running there. Where the kernel does not report the foreground process group (Windows, the BSDs), the daemon falls back to the detector's last reading: no foreground program and agent statenone.
Security: what a caller can make it type is fixed by the manifest and by an id
already stored on the window, and the manifest loader and the id check hold
every token to characters every supported shell (sh, bash, zsh, fish,
PowerShell, cmd) reads as one unquoted argument, so a pane that reported a
hostile id cannot turn it into a second command. It types only into a pane at
its shell prompt. That is strictly less than send-text, which every caller of
the socket, a pane or a link included, already has, so it is not gated on the
person. User manifests (under the user harness directory) can set any
program as the first token; that directory is the user's own configuration.
Restore behaviour, from daemon.resume_agents:
ask(default, and any unrecognised value): oneresumeInbox item per restored pane with a resumable conversation. The Inbox answers it withy, which calls this verb.auto: the daemon waits for each restored shell to draw its prompt (up to 10 seconds, then 300 ms of quiet), and types the command, 100 ms apart between panes. A pane that does not get there, or whose shell is not in the foreground, gets theaskitem instead.off: nothing. The id stays on the window, so this verb still works.
Wire compatibility: a new verb. An older daemon answers unknown_verb.
resolve-pane
Name the pane a process runs in, for a hook reporter whose environment lost
TUIOS_PANE_ID. Params: sid (the caller's session id) and pids (its
ancestors, nearest first). A pane's shell leads the session of the pane's
terminal, so sid is matched first; then the first ancestor that is a pane's
shell. Only panes on the daemon's own machine are matched.
{"verb": "resolve-pane", "params": {"sid": 4242, "pids": [4250, 4242]}}{"result": {"type": "pane_resolved", "session": "work", "window_id": "3c1f6e4e", "by": "tty", "pid": 4242}}No match is window_not_found.
set-agent-meta
Record display metadata about the agent in a pane: its model, how full its
context is, what the turn cost, a one-line summary. The rail draws it on the
second line of the agent's row. It is display only. Nothing reads it to decide
an agent state, a wait-for, an alert or a message.
Params: session (optional), window (optional, default the focused pane),
tokens (an object of key to string, or to null to remove the key; required
unless clear is true), source (optional, recorded on each key), ttl_ms
(optional, 0 to 86400000, default 0 for no expiry), clear (optional bool).
Limits: 16 keys per call and 32 per pane. A key is 1 to 24 lower-case letters,
digits, _ or -, starting with a letter. A value has control characters
replaced with spaces and is cut to 80 characters. A bad key, too many keys, or
a TTL out of range is invalid_params; a cut value is not an error, and its
key is listed in truncated.
Reserved keys: now (what the agent is doing, such as Bash: go test ./...),
prompt (the first line of the last prompt) and subagents (how many
subagents the agent is running, such as 3 subagents) are written by tuios
from the activity a hook reports with set-agent-state or
report-agent-activity, with source activity. This
verb refuses them with invalid_params, and its clear leaves them. A hook
that names a model also sets model, with source hook, which a caller may
still write.
Unchanged writes: a key set to the value it holds, by the source that wrote it, changes nothing, and its TTL is renewed only once less than half of it is left. A call that changes nothing leaves the session version alone and pushes nothing to clients, so a feed may write as often as it likes.
Order: a key keeps the position it first arrived in, and a new key goes at the
end in the order the tokens object lists it, so a feed that rewrites every
key on each tick does not reorder the row.
Lifetime: clear removes every key the same source wrote, or every key when
source is empty, before tokens is applied. Keys set with ttl_ms are dropped
by the daemon when it runs out, and the change reaches clients through the
ordinary state sync. All metadata clears when the agent leaves the pane, which is
the pane's agent state going to none.
Request:
{"verb": "set-agent-meta", "params": {"session": "work", "window": "build", "source": "statusline", "tokens": {"model": "opus", "context": "42%"}, "ttl_ms": 60000}}Response:
{"result": {"type": "agent_meta_set", "window_id": "3f2a9c1e", "meta": {"model": "opus", "context": "42%"}, "truncated": []}}get-agent-state and each list-agents entry carry the same meta object,
and subagents, the count meta's subagents key states, as a number.
ask-human
Put a question with a fixed set of answers to the person, and wait for the
answer. The question is an ask item in the Inbox. A client the person holds
that shows the asking pane opens the Inbox on it at once, unless the person
typed into the pane in the last 600 ms or an overlay is open there, and then
drops every key for 400 ms; anywhere else it waits there with the usual
alert, and with nobody attached it waits for the next attach.
Params:
session(optional).window(optional): the pane asking, where a late answer is mailed. A caller inside a pane asks as its own pane when it names none, and naming another isforbidden. A caller outside every pane may name any pane, or none.question(required unlessrequest_id): one line of printable text, at most 160 bytes, that the Inbox shows as written. Anything the Inbox would cut, mask or rewrite isinvalid_params.options(required unlessrequest_id): 1 to 9 answers, each one line of printable text of at most 60 bytes, no two the same. The person picks one with the digit keys.timeout(optional int): milliseconds to wait, default 120000, at most one hour. The question outlives the wait.wait(optional bool, default true): false asks and answerspendingat once.request_id(optional): come back for a question already asked: wait on it again, or read how it ended. It takes no question or options, and a caller inside a pane may come back only for its own pane's questions.
Response:
{"result": {"type": "human_answer", "request_id": "9f86d081884c7d65", "status": "answered", "answer": "no", "answer_index": 2, "answered_by": "client-1790155072046345000", "verified_human": true}}status is answered, pending (the wait ended first), dismissed,
superseded (the pane asked another question), window_closed,
session_closed, evicted or shutdown. A pending question stays in the
Inbox; the answer, when it comes, is mailed to the asking pane from human
with verified_human set, so wait-for agent-message returns on it, and a
call with request_id reads it. A question from no pane is only read that way.
When the caller goes away while it waits, the daemon learns so only when it
cannot write the reply. If that reply was the person's answer to a question
from a pane, the answer is mailed to the pane the same way, so an agent whose
tool killed the call still gets it.
Refused over a link (forbidden): a question is put to the person at this
machine's clients by something on this machine. At most 16 questions from no
pane are open per session (rate_limited); a pane has one, and a new one
supersedes it. Questions do not survive a daemon restart.
agent-mail-notice
{"id": 1, "verb": "agent-mail-notice", "params": {"session": "work", "window": "$TUIOS_PANE_ID"}}Answers with one line that tells a pane's agent about its unread mail.
tuios agent-hook calls it for Claude Code and Codex on SessionStart,
UserPromptSubmit and PostToolUse, and the harness adds the line to the
agent's context. The line holds the count, the senders' names cut to letters,
digits and . _ - : @, and the read-agent-messages command to run. It never
holds a subject or a body: those are written by another program.
Each message is announced once. The call marks the unread mail it describes as
announced, and the next call answers with an empty notice until newer mail
arrives. reset: true announces all unread mail again; the hook sets it on a
SessionStart, since a new, resumed or compacted conversation no longer holds
the earlier line. The marks live in daemon memory and go with the pane.
A hook asks with lease: true and its harness, agent_session_id and
harness_pid. The guard of report-agent-activity applies: a pane attributed
to another harness or conversation, or a harness outside the pane, gets no
notice and the reason. With a lease, the mail counts as announced for 3
seconds, and the answer carries a lease token. The hook sends it back in
commit once it wrote the line. A hook that missed its deadline sends nothing,
the lease runs out, and the next hook announces the mail again.
From a pane it is the pane's own record: window must be the caller's pane.
Result: window_id, unread (seen messages included), notice (empty for
nothing new), lease for a call with a lease that gave a notice, committed
for a call with commit, and reason when the guard gave no notice.
agent-activity
Read what the agent in a pane has been doing. The daemon keeps a ring of the
newest 256 entries per pane, in memory only, from the activity its hooks
report with set-agent-state. A pane gets a ring on the first report that
carries activity, so a plain shell pane and an agent whose harness has no
hooks have none. Once it has one, the commands its shell finishes (OSC 133)
and its agent state changes are added too. The ring goes when the window
closes, when the session ends, and with the daemon.
Params: session, window (default the focused pane), since (unix
nanoseconds; entries after it), since_seq (entries after it), limit (1 to
256, default 64: the newest that many), recap (bool).
Each entry has seq (per pane, from 1), at (unix nanoseconds) and kind:
kind | From | Fields |
|---|---|---|
prompt | a prompt submitted | text: its first line |
tool | a tool call starting | tool, target (the command, file, URL or pattern) |
tool_done | a tool call that finished | tool, target, files it wrote, ok when the harness said |
tool_failed | a tool call that failed | tool, target, ok false, text: the error's first line |
turn_end | the agent finishing a turn | text: the first line of what it said last, absent when the harness sent none |
subagent_start | a subagent starting, or a teammate waking to work, reported with report-agent-activity; kept only when the pane did not have it running already | text: its description and type, "Research tmux (general-purpose)", or its type alone |
subagent_stop | a subagent ending, or a teammate going idle; kept only for one the pane saw start, once | text as for a start; outcome: done, failed or stopped; duration_ms; tools |
session_start | the agent starting a conversation | text: how, such as startup, resume or clear |
command | a command the pane's shell finished | target: the command line, exit when the shell sent one |
state | the pane's agent state changing | text: the new state |
Every string is the agent's or its shell's: one line, control characters
removed, likely secrets masked, cut to 160 bytes (a file path to 256, a tool
name to 64). A command entry's command line is held to the same 160 bytes,
although the shell's own record of it (last_cmdline, the
command-finished event) keeps up to 512. The answer is marked untrusted.
A pane's first report with activity gets its ring before its state applies,
so a first report that finishes a turn (a Stop from hooks installed
mid-session, or after a daemon restart mid-turn) records its state entry
and counts the turn, like any later one.
With recap, the answer also summarises every entry after since and
since_seq, whatever the limit:
since: where the summary starts, thesinceasked for, or the oldest entry the ring holds when it was asked for everything or has dropped entries aftersince;turns: how many turns finished, the sum of the pane'scompletion_seqsteps its state entries recorded;files(the first 20, first written first) andfiles_total;commands: shell tool calls (Bash,shell,exec_command,local_shell,run_shell_command) plus the shell's own commands;tests: the newest command matching[agents.recap] test_patterns, withcmdline,atandok: true or false from a finished or failed tool call or a shell exit status, and null when nothing said (a call still running, or a shell that sent no status). Absent when no command matched;last_said: the first line of the newestturn_end;state: the pane's agent state now.
Request:
{"id": 1, "verb": "agent-activity", "params": {"session": "work", "window": "api", "since": 1790000000000000000, "recap": true}}Response:
{"id": 1, "result": {"type": "agent_activity", "session": "work", "window": "3f2a9c1e", "last_seq": 42, "untrusted": true,
"entries": [{"seq": 41, "at": 1790000123000000000, "kind": "tool_done", "tool": "Bash", "target": "go test ./...", "ok": true},
{"seq": 42, "at": 1790000125000000000, "kind": "turn_end", "text": "Added retry with backoff and tests."}],
"recap": {"since": 1790000000000000000, "turns": 3, "files": ["api/retry.go", "api/retry_test.go"], "files_total": 2, "commands": 11,
"tests": {"cmdline": "go test ./...", "ok": true, "at": 1790000123000000000}, "last_said": "Added retry with backoff and tests.", "state": "done"}}}Who may read it: from a pane, read reaches its own session and fan group, as
for the other reads; over a link it needs list. Only the pane's own reports
write the ring: activity rides set-agent-state, which a pane may call only
for itself, and it is recorded only past the identity guard. Nothing reads the
ring to decide a state, a wait or an alert.
The event type agent-activity carries each entry as it is recorded, as
entry, to a subscription whose types names it. It is not replayed on a
resume; read the ring instead.
tuios agent-log is this verb on the command line.
agent-transcript
Read the conversation of the agent in a pane, as data. A client uses it to show the conversation in its own view, for example a phone app: prompts, answers, thinking, tool calls, diffs of edits, plans and todo lists.
The daemon reads the transcript file that the pane is joined to. The pane is
joined when the agent's hooks report transcript_path, or when the daemon
finds the one file that belongs to the pane. The path stays in the daemon.
The caller names a window, never a file. The daemon reads Claude Code, Codex, Gemini CLI, Qwen Code, Copilot CLI, Amp,
OpenCode, Cursor Agent and Pi transcripts.
Pi sessions
Pi's pi-jsonl reader supports its tree-structured session versions 2 and 3,
checked against Pi 1.3.0. A session is a tree of entries and sibling entries are
different conversations, so the reader shows the branch that ends at the last
complete entry, and nothing from another branch. The allowed folder is
sessions in Pi's agent folder, $PI_CODING_AGENT_DIR or ~/.pi/agent, as the
daemon's environment has it. Sessions kept anywhere else need a matching
harness manifest; a hook cannot widen the folder by naming a file. A session
with no file (--no-session) has no transcript to read, and an accepted new
session identity with no usable file clears the previous conversation rather
than showing stale history.
The version 3 Pi integration reports the exact file and the entry Pi has
selected, which includes /tree navigation that appends nothing to the file,
and the reader shows that branch. Update the integration through your normal
management and reload or restart Pi to load it. An older integration reports no
selection, so the reader keeps showing the branch that ends at the last complete
entry and cannot see a rewind that exists only in memory. An entry named before
its line is written gives an empty view until the line is complete, never
another branch.
Pi reads are bounded: a file over 32 MiB or with more than 100,000 entries is
refused, and a record over 16 MiB is left out, as the other readers skip a
line that long. The daemon keeps what it parsed for a short time, keyed by the
file's size and modification time, so paging through a long session does not
read the whole file again. Pi transcript events carry no cursor, as with
other readers of a document: read with the cursor of your last reply and honor
the reply's reset field.
The daemon accepts a reported transcript_path only when all of these are
true. Otherwise it does not join the pane, and the set-agent-state reply
says why in transcript_refused:
- A process in a pane names a file only for its own pane.
- The file is under the harness's transcript folder. For Claude Code that is
~/.claude/projects, or$CLAUDE_CONFIG_DIR/projects, for Codex~/.codex/sessions, or$CODEX_HOME/sessions, and for Pi~/.pi/agent/sessions, or$PI_CODING_AGENT_DIR/sessions. The variable is read from the environment of the process that sends the report, which is the hook the agent runs, so each pane follows the profile its agent started with. The default folder is accepted as well. The symbolic links in the path are resolved first, so a link in the folder that leads out of it does not count. The folder itself may be reached through a link, such as a profile folder that is a link, but the one the variable names must still end inprojects(sessionsfor Codex and Pi) once its links are resolved, so aprojectsfolder that is a link to a folder with another name does not count. A relative value, or one with a{in it, names no folder. The variable is not a boundary: a process in a pane can set it to any folder that has aprojectsfolder in it (sessionsfor Codex and Pi), and name a file there that matches the pattern, for its own pane. - The file name matches the harness's pattern (
*.jsonl). - The file is a regular file. The daemon opens it without waiting and checks it again on each read, so a FIFO or a link put in its place is not read.
Params:
-
session(optional). -
window(required): the window id or name of the pane. -
human_nonce(required): the nonce of a client attached now, or of attach-presence on this connection. -
after(optional): thecursorof an earlier reply. -
before(optional): theoldercursor of an earlier reply. Do not giveafterandbeforetogether. -
limit(optional int): the most entries to return, 1 to 1000. The default is 200. Leave it out for the default. Alimitof 0 isinvalid_params. -
image(optional): theidof an entry that hasimage. The reply is then that image alone:{"type": "agent_transcript_image", "session", "window", "image", "media_type", "data", "untrusted": true}, withdatathe image bytes as base64. The daemon reads only the one record the id names, in the file the pane is joined to. An id that names no image isinvalid_params. Only Claude Code transcripts carry images.Two images are files, not transcript data, and the daemon adds an entry for each after the entry that names it, with an
idof the formfile.<entry id>.<k>: a file of this daemon's paste folder (atuios-paste-name) that a prompt names, and an image an agent's read tool (view_image,read_file,read_many_files,read,view) named by an absolute path when no image follows the call. A prompt gives 4 at most. The entry is there only while the file is a regular file of at most 10 MB. Animageread of such an id finds the entry again in the newest 1000 entries and takes the path from it, so the caller never names a path. The file is opened without following a link, and its first bytes must be PNG, JPEG, GIF or WebP:media_typeis what the bytes are, whatever the name says.
Without after and before, the reply holds the newest limit entries.
With after, it holds the entries after that cursor. With before, it holds
the newest limit entries before that cursor. The entries are always oldest
first.
To show the history, read without a cursor first. Then send the reply's
older as before to get the page before it. Repeat until older is empty.
Request:
{"id": 1, "verb": "agent-transcript", "params": {"session": "work", "window": "api", "human_nonce": "294e0a278581acd0f07ff40561c52bf7"}}Response:
{"id": 1, "result": {"type": "agent_transcript", "session": "work", "window": "3f2a9c1e", "harness": "claude-code",
"cursor": "t1.5b0c9e2a41d7f003.2kq9", "older": "t1.5b0c9e2a41d7f003.0", "reset": false, "more": false, "untrusted": true,
"entries": [
{"id": "0-0", "at": 1791531791506, "role": "user", "kind": "text", "text": "Add retry to the client"},
{"id": "1g-0", "at": 1791531793120, "role": "assistant", "kind": "tool_call", "tool": "Edit", "target": "api/client.go", "status": "ok", "tool_id": "toolu_01",
"diff": {"file": "api/client.go", "added": 1, "removed": 1, "hunks": [{"old_start": 12, "new_start": 12, "lines": [
{"op": " ", "text": "func get() {", "spans": [{"s": 0, "e": 4, "k": "kd"}, {"s": 5, "e": 8, "k": "nf"}, {"s": 8, "e": 10, "k": "p"}, {"s": 11, "e": 12, "k": "p"}]},
{"op": "-", "text": "\treturn do()", "spans": [{"s": 1, "e": 7, "k": "k"}, {"s": 8, "e": 10, "k": "nf"}, {"s": 10, "e": 12, "k": "p"}], "words": [{"s": 8, "e": 11}]},
{"op": "+", "text": "\treturn retry(do)", "spans": [{"s": 1, "e": 7, "k": "k"}, {"s": 8, "e": 13, "k": "nf"}, {"s": 13, "e": 14, "k": "p"}, {"s": 14, "e": 16, "k": "nx"}, {"s": 16, "e": 17, "k": "p"}], "words": [{"s": 8, "e": 16}]}]}]}},
{"id": "2c-0", "at": 1791531793300, "role": "tool", "kind": "tool_result", "status": "ok", "tool_id": "toolu_01", "text": "The file api/client.go has been updated."},
{"id": "3a-0", "at": 1791531794000, "role": "assistant", "kind": "todos", "tool": "TodoWrite", "status": "running", "tool_id": "toolu_02",
"todos": [{"text": "Add retry", "status": "completed"}, {"text": "Run the tests", "status": "in_progress"}]}]}}The reply:
cursor: send it asafterto read what comes next. It is opaque.older: send it asbeforeto read the entries before this page. It is opaque. It is empty when the page starts at the first entry of the file. After a read withafter,oldercan name a place with no entry before it. A read with thatbeforethen returns no entries and an emptyolder.reset:truewhenafterorbeforeis not a cursor into the file as it is now, for example when the agent started a new file at the same path. The entries are then the newestlimit, and the client starts its list again.more:truewhen a read after a cursor stopped before the end of the file, atlimitentries or at the size bound. Read again with the new cursor.
Each entry has:
| Field | Meaning |
|---|---|
id | A stable id. A read of the same record gives the same id. An entry with an id that the client holds replaces it. |
at | When the agent wrote the record, unix milliseconds. |
role | user, assistant or tool. |
kind | text, thinking, tool_call, tool_result, plan, todos, error or interrupt. A thinking entry can have no text: Claude Code keeps most thinking as a signature only, and the entry still says the agent thought. Its time less the time of the entry before it is how long. interrupt marks where the person stopped the agent, with role user and no text. It is not a prompt. error is an error the harness wrote, such as a failed request. |
text | The text. For a tool_result, the first 20 lines. |
truncated | true when text or plan was cut, or a tool result had more lines. |
tool | The tool name of a call: Bash, Edit, TodoWrite. |
target | One line that says what the call acts on: the command, the file path, the URL or the pattern. |
status | ok, error, running or declined. A call gets the status of its result when the result is in the same reply, and running when it is not. declined says the person declined the call. The result's text is then what they said with it, or empty, not the harness's own words. |
tool_id | Joins a call to its result. When a result arrives in a later reply, update the call with that tool_id from it. |
diff | For Edit, MultiEdit and Write: file, added, removed, truncated, plain, whole_replace and hunks. Each hunk has old_start, new_start and lines, and each line has op (" ", "+" or "-"), text, spans and words. See Diff colours. A Write of a new file is all +. When the result carries the file's own line numbers (Claude Code's structuredPatch), the result has the diff too, and a call in the same reply takes those hunks. Without them, the line numbers count from the start of the edited text. |
plan | For ExitPlanMode: the plan, as markdown. |
todos | For TodoWrite: the list, each item with text and status. |
image | On an image the person pasted, or one a tool result holds: media_type (image/png, image/jpeg, image/gif or image/webp), and width and height in pixels when the transcript says them. The entry's text is [image]. An image of a tool result, such as a Read of a PNG, is an entry of role tool right after the result, with its tool_id, at most 8 for one result. Read its bytes with the image param. |
calls | On a tool call that talked to another agent or to the person through tuios: a shell command that runs send-agent-message, ask-agent, read-agent-messages, ask-human, start-agent, delegate or queue, in a pipeline or a list too, or the MCP tool of one of those verbs. One object per command, at most 4: verb (send, ask, read, ask-human, start, delegate or queue), and what the command line or the input gave of session, to, self (the caller's own pane), select, subject, text, reply_to, thread, options, harness, name, unread, peek, sent and json. The command line is read with a shell's word rules and each command's own flags, so a command with a flag tuios does not know, or a subshell, has no calls. |
Diff colours
Each diff line can carry the colours to draw it with. The daemon works them out with the same rules as the review view in tuios.
spans: the syntax tokens of the line, as{"s": start, "e": end, "k": class}.kis the short CSS class name that chroma gives the token type, for examplek(keyword),kd,kt,s,s2,c,c1,nf,nc,m,mi,o,p,nbandbp. Plain text and white space have no span. The daemon picks the language by the file name infile. A file with no extension and a#!first line is read by that line. A file of an unknown type has no spans.words: the part of a changed line that changed, as{"s": start, "e": end}. Only+and-lines have it. A run of removed lines and the run of added lines after it are paired in order: the first removed line with the first added line, and so on. A line with no partner, and a line that changed too much for a mark to help, has nowords.- Offsets count UTF-16 code units of
text, the unit of a Kotlin or Java string index. A range starts atsand stops beforee. - The lines of one side of a hunk are read as one text: the context and removed lines, then the context and added lines. A context line takes its spans from the second read. So a comment or a string that runs over lines has its colour on every line.
plain:truewhen the reply reached its limit for colours before this diff. The lines then havewordsand nospans. Read a smaller page, with a lowerlimit, to get the spans.
Whole replace
The daemon matches the old and new lines of an edit to find what changed.
The work for this has a limit: 4,194,304 table cells for one reply, all diffs
together. An edit of n changed old lines and m changed new lines uses
(n+1)×(m+1) cells. The newest diffs of a read without after are matched
first. A diff that does not fit in what is left is not matched:
whole_replaceistrue.- Each hunk shows the changed old lines as
-, then the changed new lines as+. Equal lines at the start and the end are context as usual. addedandremovedcount the changed lines of each side.- At most 200 lines of each side are shown, and
truncatedistruewhen some are left out.
Show such a diff as one block replaced by another. Read a smaller page to get it matched.
The daemon builds the diff, its colours and its clean text only for the entries in the reply.
Diff colour limits
The colours have a limit because the lexers are slow, about 0.5 MB a second.
For one reply, the daemon lexes at most 16 KiB of code, or one hunk when the
first hunk is larger. On a 400-line diff that is about 50 ms. The newest
diffs of a read without after get their colours first. A line longer than
2000 characters has no spans.
A subagent's own records (isSidechain) and the records that Claude Code
marks as meta are left out. The Task call that started the subagent stays.
Bounds: text and plan are cut to 8 KiB, a diff to 400 lines and each diff
line to 1 KiB, a target to 512 bytes, and a todo list to 100 items. The
entries of one reply are at most 2 MiB as JSON. A read without after looks
at most 32 MiB back from the end of the file, or from the before cursor.
When that part of the file holds fewer than limit entries, the reply holds
what it found, and older goes on from there. A read with before reads only
the part of the file before the cursor that the page needs, so a page far
back costs the same as the newest page.
Every string is the agent's or its tools'. The daemon removes control
characters other than newline and tab, removes bidirectional controls, and
masks likely secrets as it does for the Inbox. The reply is marked
untrusted.
The daemon also masks secrets that span lines, in text, tool results and the lines of each diff hunk:
- A PEM private key: the lines from its
BEGINline to itsENDline become[redacted]. TheBEGINandENDlines stay. - Two or more lines in a row of base64 alone, 40 characters or more each,
become
[redacted]. This is the body of a key with itsBEGINline out of view. - Two or more
KEY=VALUElines in a row, with an upper case key, as in an.envfile: each value becomes[redacted]. The key stays.
Who may read it: only the person. The call needs a human_nonce that
verifies by the rules of reply-approval, so a process
inside a pane and a link stream that the hub did not vouch for get
not_human. Nonce scope applies: a presence made with a session
reads only the panes of that session, and gets not_human for a pane of
another session. A restricted connection is refused with forbidden. Over a link
it needs transcripts, which the default grants and respond includes. A
client attached through a host sends the call to the far daemon over the link,
with the nonce of its attach there.
The transcript event says when to read again. Subscribe
with types that name transcript, and call agent-transcript with your
cursor when an event has a different one.
Errors: invalid_params when window is missing, limit is out of range,
or after and before are both given.
not_human without a live nonce. no_transcript when the pane is not joined
to a transcript or the file is gone. unsupported_harness when the pane's
harness keeps no transcript that the daemon reads. window_not_found and
session_not_found as for every verb.
Agent review, triage and queue verbs
Every one of these verbs is built: agent-activity (see
agent-activity), the delivery queue's three (see
The delivery queue), compare-fan, verify-fan and
keep-fan, which have sections of their own, mark-attention (see
mark-attention), get-approval (see
get-approval) and the three review verbs (see
review-diff). list-verbs
describes each one's parameters and result. What is fixed now is who may call
them:
| Verb | What it does | A pane without admin | Over a link | The person only |
|---|---|---|---|---|
review-diff | The diff of what the agent in a pane changed, against its base or a fan sibling, marked untrusted | read, own session and fan group | write (file contents) | no |
review-note | Add, edit, remove, list or clear review notes on a pane's changes | write; add and edit only on a pane the caller could type into | write | a note is the person's only with a live human_nonce |
review-stage | Stage or unstage a file, a hunk or lines of a pane's worktree, and undo it; only the index changes | refused | write | no; a human_nonce that is given must be live |
send-review | Send the unsent notes to the agent through the delivery queue | write, and a typing verb: the target holds nothing the caller does not, and is not on needs_input unless the caller holds respond | write | "from the person" only with a live human_nonce; a note by anyone else is labelled with its author, and withheld when its author may not type there now |
compare-fan | One row per attempt of a fan: branch, agent, state, changes, last check | read, own fan group | list | no |
verify-fan | Run one check with sh -c in a window named verify in every attempt; the window holds no grants | fan, own fan group | open and write | no |
keep-fan | Keep one attempt and remove the others, refusing a dirty one without stash or force | refused | write | admin or the person |
mark-attention | Snooze, wake, mark unread or restore an Inbox item, or settle an agent | refused | respond | yes: human_nonce from a live attach, never from inside a pane |
agent-activity | The pane's ring of hook events, and a recap of it, marked untrusted | read, own session and fan group | list | no |
queue-prompt | Queue a message, typed when the agent comes to rest and never over a prompt | write, and a typing verb as for send-review; checked again against the caller's grants when typed | write | "by the person" only with a live human_nonce |
list-queued | The messages waiting in a pane's queue | read | list | no |
cancel-queued | Drop queued messages; a pane drops only what it queued | write | write | the person's entries need a live human_nonce |
get-approval | A held approval or plan whole, with its risk rules, marked untrusted. Built: see get-approval | read; its session is the pane's own unless named | list | no |
list-checkpoints | The checkpoints of a pane's work tree, one per turn that changed a file, marked untrusted. See list-checkpoints | read, own session and fan group | list | no |
checkpoint-diff | What one turn changed, marked untrusted | read, own session and fan group | write (file contents) | no |
restore-checkpoint | Put a pane's work tree back to a checkpoint, after a safety checkpoint | write, only on a pane the caller could type into | write | no |
ship-commit | Commit every change in a pane's work tree on its branch, as the person | write, only on a pane the caller could type into | write | no |
ship-merge | Merge a worktree's branch into its base in the main checkout, undoing a conflict | write, only on a pane the caller could type into | write | no |
ship-push, ship-pr | Push the branch, and open a pull request with gh, after a confirm token | write, and the person's allow in the Inbox | refused | the person outside every pane on an unrestricted connection goes ahead with the token alone. Every other caller waits for the person in the Inbox |
ship-status | The branch's pull request and its checks | read | list | no |
A connection restricted with restrict-connection is held the same way: with
read_only, review-note, send-review, queue-prompt, cancel-queued
and verify-fan are refused, and keep-fan and mark-attention are refused
on any restricted connection.
The delivery queue
queue-prompt, list-queued and cancel-queued are built. A queued message
is typed as a prompt once the agent in the pane has been at rest for a
second: idle or done, or unknown for a harness whose rules can never
show idle. One message is typed per rest, never over a pane on
needs_input, and never twice. After a message is typed, the next waits for a
rest reached after it, even if the queue emptied in between; a pane whose
harness cannot show working, and so may never change state, also reaches one
by printing something and then going silent for 5 seconds. AGENT_STATE.md
describes the whole lifecycle.
queue-prompt params: session, window (default the focused window; it
must run an agent, and human is no_keyboard), text (at most 16 KiB,
required without parts), parts, human_nonce, from.
{"id":1,"verb":"queue-prompt","params":{"session":"work","window":"build","text":"make the backoff jitter configurable"}}
{"id":1,"result":{"type":"prompt_queued","id":"q3","position":1,"queued":1,"delivering":false}}client_id is the client's own name for the message, at most 128 bytes. A
phone that lost the answer sends the message again with the same client_id,
and the daemon queues nothing and answers as the first time, with
duplicate: true. Use a random id. An id counts for one sender and one pane:
the sender is the kind of caller and, for a link, the machine, or for a pane,
the pane. Two machines whose links give no name count as one sender. The daemon
keeps the last 256 ids across all panes for 7 days, in memory. A daemon restart
forgets them, so a message sent again after a restart is queued again. It does
not go with host. A daemon older than client_id refuses the param
with invalid_params, so ask list-verbs before sending it.
host names a machine from [hosts]: the message is for a pane there. This
daemon passes it, with its parts, to that machine's daemon over the link, on
a connection of its own, and answers with the far daemon's result and host.
The far daemon queues it as link:THIS-MACHINE, held to its policy for this
machine: write, and files for a block or an image. Only a caller outside
every pane may send one, since the far daemon sees only the link. The
person's nonce is checked here and not sent on.
parts is the message as ordered parts, the form the reply composer sends:
{"kind":"text","text":…} for typed text, {"kind":"paste","text":…,"n":1}
for a pasted block, and {"kind":"image","data":…,"n":1} for an image, data
being the file in base64, where n is the block's number as the person saw
it. A message takes at most 64 parts, 8 images of 8 MiB each, and 8 MiB in
all. With parts, text is ignored, so
a client can send both and a daemon older than parts types the text. Such a
daemon answers without the parts count in the result.
{"id":1,"verb":"queue-prompt","params":{"window":"build","parts":[{"kind":"text","text":"this fails: "},{"kind":"paste","text":"--- FAIL: TestJitter\n…","n":1}]}}
{"id":1,"result":{"type":"prompt_queued","id":"q4","position":1,"queued":1,"delivering":true,"parts":2}}The daemon on the pane's machine chooses how each block travels when it types the message, not when it queues it:
- When the whole message is 12 KiB or less and the pane takes a bracketed paste, each block is typed in its place, as one paste.
- Otherwise each block is written to a file in the paste folder beside the
daemon's socket, and the typed text names it in the block's place:
[Pasted text #1: PATH, 42 lines]. The file is mode 0600 in a 0700 folder, written through anos.Rootat the folder and never through a link. It is kept for 24 hours and removed when the daemon stops. - Each image is written there too, named by the type its bytes show. The
harness's
[input] imagesplaces its path: in a paste of its own between the text before and after it (path_paste, when the pane takes a bracketed paste), as[Image #1] PATHin the text (path_text), or nowhere:images = "none"refuses the message atqueue-promptwithinvalid_params.
The text parts with each block's label must fit 16 KiB. A pane's queue holds
at most 32 MiB and every queue together 128 MiB; past either, queue_full.
Over a link, a message with a block needs files in that machine's
[hosts] policy, at queue-prompt and again when it is typed. A message
whose file cannot be written is dropped, and an Inbox question says so on the
pane's blocking key.
delivering is true when the entry is next and the agent is at rest now, so
it is typed within about a second. Errors: queue_full when the pane already
holds [agents.queue] max entries, no_keyboard, not_human for a nonce
that does not verify, forbidden, invalid_params.
list-queued params: session, window (omit it to list every pane of the
session). Each entry has id, session, window, name, at (Unix
nanoseconds), by, from when given, preview (the first line, at most 80
characters, control characters left out) and state (waiting,
delivering or stalled), next first within each pane.
cancel-queued params: session, window, and id or all, and
human_nonce. It answers cancelled (the ids dropped) and queued (what the
pane holds now). Dropping a stalled entry leaves the next to the pane's next
rest.
Who queued an entry, by, is the daemon's own reading of the connection:
human only with a live human_nonce, link:HOST over a link (the peer the
link-peer handshake named, * for none), the pane's window id for a process
in a pane, and shell for anything else. What each is held to:
| Origin | At queue-prompt | When it is typed | May drop with cancel-queued |
|---|---|---|---|
human | the nonce | nothing more | every entry |
| a pane | write, and the typing rules of send-text | its grants as they are then, against the target; a refusal drops the entry | only its own |
link:HOST | write in its [hosts] policy | the policy as it is then; a refusal drops the entry | only its own; for a machine that gave no name, only what it queued on the same connection |
shell | nothing new | nothing new | every entry but human's |
For every entry the pane is checked for needs_input right before it is
typed. An entry being typed cannot be dropped. A pane on another machine,
whose calls arrive through its report channel, may neither queue nor drop:
both verbs answer forbidden.
The reply history
reply-history and add-reply-history keep what the person sent to each
agent, for the reply editor's up and ctrl+r. The history is in the
daemon's memory only and ends with it: replies hold pasted logs and secrets.
Both verbs take a live human_nonce, so no pane and no caller without it
reads or adds to it. The history holds what was sent to the agents of every
session, so the nonce must prove the person for every session: an attach
nonce, or a presence made with no session. A presence made for one session is
refused. Over a link they need respond.
add-reply-history params: target (the key the client keeps the history
under, at most 512 bytes), parts (as queue-prompt takes them),
human_nonce. A target keeps 100 messages, and 64 targets are kept, the
least used going first. 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 dropped names them. The whole history holds at most 32 MiB;
past that the oldest messages of the least used targets go first.
reply-history params: target, human_nonce. It answers entries, oldest
first, each with parts, at (Unix ms) and dropped.
{"id":1,"verb":"reply-history","params":{"target":"harness:claude-code:/work/api","human_nonce":"…"}}
{"id":1,"result":{"type":"reply_history","target":"harness:claude-code:/work/api","entries":[{"parts":[{"kind":"text","text":"rerun with -count=1"}],"at":1792181183703}]}}The TUI's target is harness:HARNESS:FOLDER when it knows both, and
pane:SESSION/WINDOW otherwise.
Task verbs
A task card is one unit of work in a session: a title, the prompt for the
pane that takes it, a stage, and at most one holder, the window id of the pane
working on it. The daemon keeps the cards on the session's state, so they are
saved with it. After a restart they come back with every holder released and a
released history entry with reason restart, since no agent comes back from
a restart. A card is also released when its pane closes (reason pane closed)
and when the agent leaves its pane, which reports none (reason agent left).
tuios task wraps the verbs.
The stages are todo, plan, doing, verify, review, shipped and
done. claim-task moves a card in todo or plan to doing, and
finish-task moves it to done and clears its holder; every other move is
set-task-stage's. A move to done there is a finish: it clears the holder
and the block and sends task-finished. Finishing a card that is done
already, or moving a card to the stage it is in, changes nothing and sends no
event.
release-task clears the holder and keeps the stage. block-task marks a card
stuck with a reason, keeping its holder and stage, and clear lifts the mark.
The daemon also moves a card on its own when it records a fact about the
card's work, unless [tasks] auto_stage is false. Each move fires only when
the card is in one of the move's stages, never on a blocked or done card, and
writes a staged history entry with by tuios and reason:
| Fact | Cards | From | To | reason |
|---|---|---|---|---|
A plan hold opens (request-approval with kind plan) | held by the pane | todo, doing | plan | plan held for approval |
The plan is approved (reply-approval with a decision other than deny) | held by the pane | plan | doing | plan approved |
verify-fan starts | stamped with the fan | doing | verify | fan check started |
| Every attempt's check ended and none passed | stamped with the fan | verify | doing | fan check failed in every attempt |
| The worktree's pull request is first seen open | held in the worktree's session, or stamped with its fan | plan, doing, verify | review | pull request #N opened |
| It is seen merged | the same | plan, doing, verify, review | shipped | pull request #N merged |
| It is seen closed without a merge | the same | review | doing | pull request #N closed without a merge |
A plan kept planning, or a hold that ends with no answer through tuios (it
timed out, or its caller went), leaves the card in plan until its pull
request opens, which is proof enough that the plan went through. A pull request
reaches every card held in the worktree's session, whatever pane holds it,
and with a fan each attempt's pull request reaches the fan's cards in turn.
A card is stamped with a fan when it is added in one of the fan's sessions, or
when fan is called with task. fan with task writes the fan's group
and fan_id onto the card and, with [tasks] auto_stage on, moves it from
todo or plan to doing (reason fanned out to GROUP, by the caller). It
leaves the card with no holder. A fan that stops partway stamps the card once
one session exists, and says so in the refusal's detail.
claim-task with next skips a card stamped with a fan of another session
while that fan has a session. start-agent with task claims the card for
the pane it opens, as claim-task would, as soon as the pane exists. Both
check the card, and that the caller may do what claim-task needs, before
they make anything: a refusal names task in its hint.
| Verb | What it does | A pane without admin | Over a link | Result type |
|---|---|---|---|---|
add-task | Add a card: title (required, at most 200 bytes), prompt (at most 16 KiB), stage (default todo), project (the repository's origin URL) | task, own session | write | task_added |
list-tasks | The session's cards, oldest first. stage, holder and open (leave out done) narrow it. all_sessions lists every session's, in session name order, and takes no session or holder. project lists one repository's cards from every session; hosts with it also asks each linked machine for its own, and hosts with all_sessions adds every linked machine's project cards | read | list | task_list |
get-task | One card with its prompt, history and attachments | read | list | task |
attach-task | Put a file (content, base64, with name), several (files, each name and content, one change and one history entry), a link, or a pane the daemon takes (screenshot or capture, each with window, scrollback, lines) on the card, with note; host passes it on to the machine that owns a project card; replace puts it in the place of one with the same name. Refusals: attachment_too_large, attachment_limit | task; the card it holds, or the card it finished while it waits in verify or review | write | task_attached with attachment and task |
detach-task | Take the attachment name off the card; its file goes when no card names it | as attach-task | write | task_changed |
get-task-attachment | One attachment by name, with the file in content (base64); a link has none. A pr link adds pr (number, state, title, checks) or pr_error, read through gh at most once a minute. Refusal: no_attachment | read | list | task_attachment |
claim-task | Take the card id, or with next the oldest card no pane holds that is not blocked or done, for window | task; for itself only | write | task_claimed |
finish-task | Mark the card done. From the pane that holds it, the card is let go and goes to verify or review instead | task; only the card it holds | write | task_finished |
run-task-verify | Run a board's verify command in the worktree of window, a pane here, for the machine that owns the card; with probe, only say whether the pane is here (here) | refused | open | task_verify with exit, note, tail |
set-task-stage | Move the card to stage | task; only the card it holds | write | task_changed |
block-task | Mark the card stuck with reason, or lift it with clear | task; only the card it holds | write | task_changed |
release-task | Let the card go and keep its stage | task; only the card it holds | write | task_changed |
remove-task | Remove the card and its history | refused | write | task_removed with id |
get-task-dispatch | The dispatch settings: paused, stopped (why all dispatch stopped on its own), quiet, quiet_now, boards (each with board, project or session, mode, failures, stopped), and board for the board project or session names | read | list | task_dispatch |
set-task-dispatch | action: mode (with mode manual, pull or auto, for the board project or session names; auto needs a preset), preset (agent, model, effort, permission_mode, machine), cap (cap, machine_cap), pause, resume (lifts the pause and every stop), quiet (with quiet, such as 22:00-07:00, or off) or verify (with verify, a shell line or off, and verify_timeout in seconds) | pause only; verify is refused; the rest need admin | refused | task_dispatch |
A row also carries the card's lifecycle: attempts (times it went back to
todo after a failed verify or an errored agent), note (why the last one
did), work (host, session, window, dir where its agent worked) and
verify (state running, passed or failed, exit, note, tail, the last
2 KiB of the output, started_at, finished_at). The history action
verified records how a verify ended.
add-task also takes harness, the agent the card is for, and ask_first,
which keeps the card for a person. A row carries them, and dispatched when
dispatch made the card's last claim. On a board in pull mode, an agent that
finishes its card is given the board's next open card in the same state change
as the claim, and mail from tuios tells it. A board stops after 3 dispatched
cards in a row end without a finish; all dispatch stops when an agent reports
limit_reached (or errored with kind usage_limit, which lands as it). See tuios task.
Every verb but list-tasks and remove-task answers with the card's row at
the top level of the result: id, session, title, preview (the first
line of the prompt, at most 80 characters), stage, stage_at, holder
(window, name, harness and state read from the pane now, and
held_at; null when no pane holds it), by, at, blocked (reason,
by, at; null when it is not blocked), and fan (fan, fan_id: the
session's fan group and fan id) for a card added in a fan's session. list-tasks
answers tasks, one row each, and session, or all_sessions: true instead
for every session. Times are Unix nanoseconds, as list-queued
gives them.
Who made a change (by, and each history entry's by) is decided from the
connection, as for the queue: human only with a live human_nonce,
link:HOST over a link, the pane's window id for a process in a pane,
plugin:ID for a native plugin, and shell otherwise. A change tuios made on
its own has by tuios.
A pane claims only for itself: it leaves window out or names its own. It
finishes, stages, blocks or releases only the card it holds. A pane holding
admin, the person, a shell, a link and a plugin name the window on a claim
and change any card; outside a pane window is required. The pick and the
take of a claim happen in one state change, so two panes that claim next at
once take two cards.
A card with a project is on that repository's board. project is the
normalised origin URL (host and path, no user, port or .git), so two
spellings of one repository match, and a local path is invalid_params.
list-tasks with project answers project and tasks; with hosts the
rows from another machine carry host, and machines that did not answer are
in hosts_down (host, error). A list-tasks that came over a link lists
that daemon's own cards only and never asks its links, so two machines that
link each other list each card once.
The daemon that made a card owns it. claim-task, release-task and
finish-task with host and the owner's session are for a pane working on
a card another machine owns: its daemon checks the calling pane, then calls
the owner with remote_window, remote_name and remote_harness. The owner
records the holder as that window on the link's peer name (holder.host),
never a name from a param, and refuses remote_window outside a link and on a
card without a project. A claim by the pane that holds the card already
succeeds, so a retry after a lost answer is safe. The worker's daemon releases
the card on the owner when the pane closes or its agent leaves, best effort.
A refusal from the owner keeps its code, with the message prefixed on HOST:.
claim-task of a card another pane holds is task_held. An unknown id, or
next with nothing open to take, is no_task. Claiming a card that is done
or blocked is invalid_params.
attach-task sends the file's bytes in content; the daemon never reads a
path. A file over [tasks] attachment_max_mib, or one that takes the
session's card files over attachment_session_mib, is
attachment_too_large, and a card that holds attachments_per_card already
is attachment_limit. A name already on the card with other content is
invalid_params unless replace is set; with the same content it is left as
it is and named in unchanged, so a retry succeeds. A name the card does not have is no_attachment. A state
push never carries a card's attachments; the row's attachment_count says how
many there are, and get-task lists them.
{"id":1,"verb":"add-task","params":{"session":"work","title":"make the backoff jitter configurable","prompt":"Read api/retry.go and add a jitter option, with a test."}}
{"id":1,"result":{"type":"task_added","id":"t1","session":"work","title":"make the backoff jitter configurable","preview":"Read api/retry.go and add a jitter option, with a test.","stage":"todo","stage_at":1793000355960400000,"holder":null,"by":"shell","at":1793000355960400000,"blocked":null}}
{"id":2,"verb":"claim-task","params":{"session":"work","next":true,"window":"build"}}
{"id":2,"result":{"type":"task_claimed","id":"t1","session":"work","title":"make the backoff jitter configurable","preview":"Read api/retry.go and add a jitter option, with a test.","stage":"doing","stage_at":1793000361002300000,"holder":{"window":"3a42ab8f-…","name":"build","harness":"claude-code","state":"working","held_at":1793000361002300000},"by":"shell","at":1793000355960400000,"blocked":null}}The events task-claimed, task-finished and task-changed follow every
change (see Event stream), and the selector key task
names the pane holding a card (see Selectors).
Verbs: Options, themes and the dock
Verbs: Options, themes and the dock: part of the Control Protocol of TUIOS.
Verbs: The Inbox, the queue and review
Verbs: The Inbox, the queue and review: part of the Control Protocol of TUIOS.
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.