User guide / Agent access to workspace context

Terminal proposals

Development reference · View source

With the proposal grant, an agent can ask to type literal text into a terminal. You review it in Review terminal text:

  1. The exact proposed value comes first, then the requester, target terminal, workspace, untrusted reason (if any), and recent output.
  2. Page with j / k if it is long. Each page must actually reach the screen before approval is enabled; until then, choosing Insert text (no Enter) names the page still to read.
  3. Reject is selected at first. Down or Tab selects Insert text (no Enter), and Up returns to Reject.
  4. One fresh physical Enter inserts the text. That Enter belongs to the overlay. Submit separately in the terminal.

Making hidden characters visible. In the proposed value, spaces show as ·, backslashes are doubled, and non-ASCII characters are escaped. Labels keep printable Unicode and spaces but escape control, zero-width, bidirectional, and space-like characters. A short proposal fits on one page. The overlay needs at least 80 × 24 cells.

What cannot approve: macros, pasted keys, repeated input, and the context API.

What a proposal can contain:

  • single-line text of at most 4 KiB;
  • no line breaks, control characters, escape sequences, or Unicode line or paragraph separators.

Runyte never appends Enter, clears existing input, or sends cursor keys. Insertion uses the child’s current input position, and recent output does not prove the input line is empty. Some programs act on printable input at once, so approval to insert is no guarantee that the child waits for submission.

Limits and cancellation:

  • Each reader may queue four proposals, sixteen per host, expiring after two minutes.
  • Existing prompts keep their input ownership. A detached target refuses proposals until you attach.
  • Changes to terminal input or input modes invalidate an approval.
  • Disconnect, revocation, exit, and attachment loss cancel queued work before writing begins.
  • Delivery means the bytes reached the PTY, not that the child accepted a command. A partial write or lost response is uncertain and must never be retried automatically.