Message a running agent

Send guidance to a live session while preserving the attempt’s conversation.

Prerequisites

A running attempt with a live session and project operator access or a higher role.

Procedure

1. Open the run drawer or conversation. Choose Message the parent or Message this child for a live child.
2. Send the guidance. A message places a hold, so an idle session waits for you before returning its result. A working session can queue the message until its next delivery point.
3. Read the response and delivery status. If the message says Not delivered, inspect whether the session is paused or has ended before sending again. Use Pause session if you need to interrupt the current work.
4. Select Release parent or Release child when the session can continue or return its answer.

Check the result

The transcript includes your message and the attempt shows Operator intervened. Release removes the hold. Wall-clock runaway limits exclude held time; token limits still count.

A parent waiting on a delegated child reads an operator message after the child returns. A child’s delivery point depends on its harness.

The API’s Steer action adds guidance without a hold. A steer addressed to the parent is forwarded to its child when exactly one child is live. The transcript shows Forwarded to child and a queued note until the child reads it. If the child refuses the steer or stops before reading it, the parent takes a separate turn to act on the guidance before ending the attempt. This also applies after an orchestrator restart. With no child or several live children, the parent takes that separate turn directly.

An attempt without a parent session sends input addressed to the parent, including Pause session and release, to its live child. The transcript shows Forwarded to child. While the next child starts, the input waits for it. With no live or starting child, such as while the coordinator handles a child’s report, the input is rejected, and the transcript records the reason. A held child’s answer ends the attempt only after you release it. If you messaged the child and it answers without changing anything, the attempt fails once you release it: an answer to the operator with no commit, pull request, comment, or step output is not a result. Holds, pauses, and messages the child hasn’t read survive an orchestrator restart.

The run page shows Delivered to parent when the parent reads the guidance. Not acted on means the steer was withdrawn or its session ended before reading it. An interruption withdraws unread steers, including guidance queued for a separate parent turn after a child refuses delivery, and leaves the parent paused until new guidance or release. See the operator API.

A terminal resume action is available only while the checkout and required local credential still exist. Gateway-authenticated Codex sessions have no resume action because a terminal lacks the gateway credential.