Watching sessions Added in 0.9.10

An agent can watch other sessions instead of checking on them again and again. It subscribes, goes on with its own work or waits, and OAR wakes it when something happens in the watched sessions: a question waits for an answer, a turn fails, a session replies, a background task ends. The wake-up is a short message that OAR writes into the watcher's conversation.

Typical requests:

• Babysit a batch. "Watch the three review sessions. Wake me when one asks a question or fails, and sum up the replies when they are all done."
• Wait for a long job. "Start the full test run in a session and watch it. Tell me when its background task finishes, and say so if it fails."
• Keep an eye on another machine. "Watch the nightly deploy session on build-box and tell me about errors."

The sessions can be on this relay (with agent sessions switched on) or on a paired relay. Every provider can watch except Claude Cloud and OpenAI Image, whose sessions cannot subscribe (see By provider). The tool itself, relay_tool's subscribe, is listed in Watching sessions in the reference; this page explains what you see and what you control.

What wakes a watcher #

A subscription names the sessions to watch, or all sessions of a relay, sessions created later included. It can ask to be told about:

Added in 0.9.13 A subscription that names no events is not woken by a shell command or monitor that ended well: a busy session ends one every minute or so, and each would cost the watcher a turn on its whole context. Finished sub-agents and failed tasks still wake it. An agent that must follow every command asks for every task end. Subscriptions made earlier without naming events switch to this default by themselves; those that named their events keep them.

The exact event names, and the options a subscription has (a regular expression that replies and task results must match, ending after it fired once, the quiet time before stalled), are in the reference.

The watcher's own conversation is never watched, so its own turns cannot wake it.

The approval card #

The first time an agent in a conversation subscribes to sessions of a relay, it has to ask you. An approval card appears in that conversation:

This agent wants to watch “Review: server/” (3f9c…), “Review: web/” (a12b…) and be woken by their events.

Events: question_asked, error, turn_end, subagent_finished, task_failed, stalled, all_idle

Special cases:

• All sessions. A subscription to all is always spelled out ("ALL sessions of this relay, including ones created later"; Added in 0.9.16 with "except N it leaves out" when it leaves sessions out). If the first card was not for all, a later subscription to all asks again. If it was, Allow covers every later subscription, all included.
• A paired relay. The card names the relay. Each relay is asked on its own, and nothing is asked on the other relay.
• Taking over. An agent that replaces another watcher can hand over every subscription of the old one. This always asks, however many cards you allowed before. The card says how many subscriptions move and from which session; the old session stops getting their events, and the subscriptions keep their settings. Your Allow also counts as the approval for subscriptions on the relays involved, all included if one of them watched all sessions.

Added in 0.9.16 The card also names a subscription's options: once, heartbeat every N min, digest every N min and quiet HH:MM–HH:MM with the time zone.

The card shows in every relay mode: it does not depend on ask, plan or agent. The approval belongs to the conversation and is kept across a relay restart.

What you see #

The chip and its list #

While a conversation has subscriptions, its header shows watching N sessions, counting every distinct session it watches. With a subscription to all sessions it reads watching all sessions, followed by (+N listed) when the conversation also lists sessions by name. Added in 0.9.16 A small hint beside it shows a subscription's options, digest N min or quiet HH:MM–HH:MM, at most two. Click the chip to open the list: one row per subscription, with the sessions (or the relay), the events, and whether it is once or has a heartbeat, Added in 0.9.16 a digest, quiet hours or sessions left out (N left out). Unsubscribe ends that subscription at once, without asking the agent.

The watched badge #

A session that another conversation watches by name carries a watched badge in the session list and in its header. Hover it to see who watches; an agent on a paired relay shows as its session and relay. A subscription to all sessions adds no badge in the session list, only in each session's header. A subscription of yours on a paired relay adds no badge on your side. Added in 0.9.16 A session that a subscription to all leaves out shows no badge for it.

Event rows #

In the watcher's transcript an event is a compact row tagged relay event, never one of your messages. It is folded to one line such as:

relay event   3 events · question, reply

Open it to read the lines, for example:

[relay event] session "Review: server/" (3f9c…): turn_end (done) "Found 4 places without input checks: …"

A row with a question or an error stays open. A row that gathers events held back by the hourly limit starts with Digest; Added in 0.9.16 so does one a subscription's digest gathered, and one held during quiet hours starts with After quiet hours. A row tagged replayed holds events a paired relay kept while the link was down.

Behind the row is a message that starts with a line saying it is automated, not from you, and that it approves nothing. The agent reads that line too.

When the watcher is busy #

• Idle. The message starts a new turn.
• In the middle of a turn. On Claude, on DeepSeek and on the SDK engine of GitHub Copilot and OpenAI, the message is steered into the running turn. On the other providers it waits and becomes the next turn. Events that arrive while a message is still waiting are added to it, so a busy watcher gets one follow-up, not one per event.

Pacing #

Every wake-up costs the watcher a turn, so OAR limits them.

• Bundling. Events within 30 seconds arrive as one message.
• Hourly cap. After 20 wake-ups within the last hour, the rest is held and sent as a digest every 10 minutes. Wake-ups of 30-second bundles resume as soon as fewer than 20 wake-ups fall within the last hour.
• Never held back. A question, Added in 0.9.16 your answer to an ask, and an error always come at once, past the cap too. They still count toward it.
• Stalled. A session counts as stalled when it has been quiet for 15 minutes (or the time the subscription chose) while a turn or background task still runs. It is reported once per quiet spell. A session that waits for an answer is not stalled: its question was already reported.
• Heartbeat. If the agent asked for one, it gets a message at that interval while a watched turn or task runs, and none while everything is idle. It tells the watcher that its watching works. A heartbeat is not held for the digest and does not count toward the cap.

The same numbers are in How events arrive in the reference.

Fewer wake-ups Added in 0.9.16 #

An agent can ask for fewer wake-ups per subscription. A question and an error still come at once; everything else waits.

On the night the clocks go back and the end time comes twice, the window ends the first time and is not entered again in the repeated hour; on the night they go forward and skip the end time, it ends the moment they jump. One limit: a start time inside the repeated hour starts the window on the first pass, and on the second pass the minutes before the start time count as outside it.

No echo. When the watcher prompts a session itself and waits for the finished reply (from send, create_session or a later wait), that turn's reply does not wake it a second time. Its errors and questions still do, and a prompt it did not wait for wakes it as before.

Held events survive a relay restart, and the hourly cap still applies on top. The agent sees with list_subscriptions how many events each subscription holds and when they are due. The details are in Fewer wake-ups in the reference.

How long a subscription lasts #

A subscription ends when:

• the agent or you unsubscribe;
• the watcher's conversation is archived or deleted;
• a watched session is archived or deleted. A subscription that lists several sessions keeps the others, and ends with the last one;
• it was a once subscription and fired (with a regular expression, on its first match);
• for a paired relay, the pairing is removed: the subscriptions on that relay end at once.

Subscriptions and events not yet delivered survive a relay restart.

A conversation can hold 20 subscriptions at a time.

Sessions on a paired relay #

Watching a session on a paired relay needs the same as any relay_tool call there:

• the relay is unlocked in the conversation;
• its Agents may level for this relay is at least reading (what a paired relay allows);
• the other relay accepts other relays' agents (Accept prompts from other relays' agents).

The card is asked here, as described above. The pairing needs to exist in one direction only. Your relay fetches the events from the other one every few seconds, and their lines start with the other relay's name:

[relay event] build-box · session "Nightly deploy" (77aa…): turn_end (done) "Deployed. The health check is green."

If the other relay does not answer for a minute, the link counts as lost. The other relay keeps what happens: up to 500 events per subscription, for up to 7 days. When it answers again, one row tagged replayed brings them in, questions and errors first, between a link_lost and a link_restored line. If more happened than it could keep, the last line says how many were dropped. A subscription that nobody fetched for 7 days ends there. Added in 0.9.16 Replayed events keep to the subscription's digest and quiet hours like any other; the last line then says how many of them come later.

Added in 0.9.16 The digest and quiet hours of a subscription to a paired relay apply here, where the watcher is; the other relay is told which sessions are left out. A paired relay on an older OAR does not know exclude: your relay still drops those sessions' events, but that relay counts them for "nothing runs any more", for stalls and in the heartbeat's list.

A paired relay that runs an older OAR answers that it needs an update.

By provider #

Which sessions can be watched does not depend on the provider: any session of the relay can be. What differs is the session that watches.

Which providers get relay_tool at all is in Agent tools.