Send messages between agents through Orca mail, not terminal input (#43309)

* Send messages between agents through Orca mail, not terminal input

* Point the inject refusal at commands that work; qualify mail receipts

* Keep the refused terminal's workspace in the inject recovery

* Describe chat mail as delivered whole, terminal mail as a pointer

* Describe chat coordinator wakes and terminal mail notes precisely

* Describe the terminal-mailbox warning as agents see it

* Name the full send command and the check command the wake gives

* Tell agents how to find a tab's agent, and that mail isn't the user's answer

* Cover chat tabs, ambiguous tabs and an unset handle when finding an agent
This commit is contained in:
Brennan Benson
2026-11-17 01:17:13 -08:00
committed by GitHub
parent 50fa70b76e
commit c535dca47d
14 changed files with 86 additions and 48 deletions
+1 -1
View File
@@ -415,7 +415,7 @@ Hooks run in the workers of the Orca that handles the request, before it acts: f
| `workspace.create.before` | `{ kind: "worktree" \| "folder"; projectId: string; name: string; branch?: string; base?: string }` | `{ deny: string }` | `name`, `branch`, `base` | A worktree or folder workspace is about to be created. Change `name`, `branch` or `base` with `next`, or return `{ deny }` to refuse it. |
| `workspace.create.after` | `{ workspaceId: string; kind: "worktree" \| "folder"; path: string; branch: string }` | none | nothing | A worktree or folder workspace was created. Observe only: Orca does not wait for it, and results are ignored. |
| `agent.launch.before` | `{ agent: string; workspaceId: string \| null; workspaceKind: "worktree" \| "folder" \| null; terminalId?: string; command: string; env: Record<string, string> }` | `{ deny: string }` | `command`, `env` | Orca is about to start an agent CLI in a terminal, from any launcher (new tab, workspace create, CLI, automation, orchestration). Change `command` or add `env` with `next`, or return `{ deny }` to refuse the launch. Restores of saved sessions are not hooked. |
| `agent.prompt.before` | `{ agent: string \| null; terminalId: string; prompt: string; inputKind: "driving" \| "orchestration" \| "launch" }` | `{ deny: string }` | `prompt` | Orca is about to submit a prompt to an agent in a terminal: a launch prompt, an orchestration dispatch, an issue or task prompt, or `orca terminal send` to an agent. A prompt a person submits is never hooked, and writes to one terminal stay in order while it decides. Rewrite `prompt` with `next`, or return `{ deny }` to refuse it. |
| `agent.prompt.before` | `{ agent: string \| null; terminalId: string; prompt: string; inputKind: "driving" \| "orchestration" \| "launch" }` | `{ deny: string }` | `prompt` | Orca is about to submit a prompt to an agent in a terminal: a launch prompt, an orchestration dispatch, an issue or task prompt, or a prompt sent with `orca terminal send`. A prompt a person submits is never hooked, and writes to one terminal stay in order while it decides. Rewrite `prompt` with `next`, or return `{ deny }` to refuse it. |
| `agent.tool.before` | `{ agent: string; workspaceId: string \| null; terminalId?: string; tool: string; input: JSON; callId?: string }` | `{ deny: string }` | `input` | An agent in an Orca terminal is about to run a tool. Claude Code waits for the answer: return `{ deny }` to refuse the call (the agent sees the reason) or change `input` with `next`; the person is still asked as usual. Other agents only report the call, so their results are ignored. Agents on SSH or WSL hosts are not hooked yet. |
| `agent.tool.after` | `{ agent: string; workspaceId: string \| null; terminalId?: string; tool: string; input: JSON; callId?: string; output?: JSON }` | none | nothing | An agent in an Orca terminal finished a tool call (successfully or not). Observe only: Orca does not wait for it. |
| `editor.save.before` | `{ workspaceId: string \| null; path: string; languageId?: string; text: string }` | `{ deny: string }` | `text` | The person is about to save a text file from an Orca editor tab (an explicit save, not autosave). Change `text` with `next` (format on save) or return `{ deny }` to refuse the save, which shows your reason. Edits made while the hook ran stay unsaved. |
+4 -4
View File
@@ -7,7 +7,7 @@ import { Callout } from '@/components/docs/prose'
Orchestration is Orca's structured multi-agent layer: a **Run** (namespace + coordinator inbox), **Tasks**, **Dispatches**, supervised **workers**, messages, and decision gates.
Use it when you need ownership, completion tracking, or a DAG. For one-off prompts, use `orca terminal send`. For full ownership handoffs without supervision, use worktree/terminal commands from the `orca-cli` skill.
Use it when you need ownership, completion tracking, or a DAG. To send another agent a one-way message, use `orca orchestration send --to <terminal handle or orca_session_id:<id>> --subject "<topic>" --body "<message>"`; it needs no Run or Task. For full ownership handoffs without supervision, use `worktree create --agent` or `agent launch` from the `orca-cli` skill.
<Callout title="Experimental">
Enable orchestration under Settings → Experimental before using these commands. The CLI talks to
@@ -50,7 +50,7 @@ orca orchestration worker-start --task <taskId> --worktree current --agent claud
`--agent` takes any Orca agent ID enabled on the worker server, for example `claude`, `codex`, `cursor`, `antigravity`, `muse`, `opencode`, or `opencode2`. `--model` accepts opaque provider model IDs for Claude, Codex, Cursor, Antigravity, Grok, Muse, and Pi (for example `--agent muse --model muse-spark-1.3`); Pi takes a `provider/id` selector and maps `--effort` to its own `--thinking` level (off, minimal, low, medium, high, xhigh, max); OpenCode accepts a per-launch model only in an existing worktree, when the execution host verifies its CLI version and model availability; OpenCode effort remains unsupported. Other agents run the model from their own config. `--effort` requires `--model` and only applies when that agent/model supports the level. Neither flag can combine with `--terminal` (reuse an existing pane). Overrides apply to that launch only and show as `model` / `effort` in the start receipt (`--full --json` shows `launch.requested` / `launch.effective`). Federated starts need a worker host that advertises launch-preference support.
After starting workers, end your turn. Orca wakes the coordinator when a worker reports, asks, or stops; run the `check` command the wake gives you and handle every message it prints:
After starting workers, end your turn. Orca wakes the coordinator when a worker reports, asks, or stops. In a chat, each message arrives whole: act on it. When the wake names a `check` command (a terminal, or a chat message too large to deliver whole), run it and handle every message it prints:
```bash
orca orchestration check --run <runId>
@@ -150,7 +150,7 @@ Dispatched workers receive a preamble that tells them how to communicate with th
- Send `worker_done` exactly once, even on failure, with `--outcome`.
- Include a short `--body` summary: what was done, what was found, and what remains.
- Include both task and dispatch IDs so stale retries cannot complete the wrong dispatch.
- Use `orca orchestration ask` for questions instead of local TUI prompts, then end your turn. Orca wakes you with the answer as mail; `check` shows it.
- Use `orca orchestration ask` for questions instead of local TUI prompts, then end your turn. Orca wakes you with the answer as mail: in a chat it arrives whole, unless it is too large for one chat message; whenever the wake names a `check` command, run it.
```bash
orca orchestration ask \
@@ -194,7 +194,7 @@ orca orchestration reset --all
## Choosing the right command
Use `orca terminal send` for a lightweight prompt to an agent you are watching.
Use `orca orchestration send` for a one-way message to another agent. For ordinary mail, a chat receives the whole message with its sender header (a message too large for one chat message gets a note to run `orca orchestration check` instead), Orca never types your words into a terminal agent's input (it reads mail through `check`), and the receipt means the mail was stored, not read. A send to a finished worker's `dispatch:<id>` can instead start a follow-up Task, whose body the worker gets as its task; the receipt says which. Use `orca terminal send` for shells, dev servers and REPLs, never to message an agent.
Use `orca orchestration worker-start` (or `dispatch --inject`) when a worker must report `worker_done`, ask questions through the coordinator, and be tracked by task ID.
+2 -2
View File
@@ -53,13 +53,13 @@ For selectors, setup flags, parent/child worktrees, and the broader command map,
```
orca terminal list --json
orca terminal read --json
orca terminal send --text "continue" --enter --json
orca terminal send --text "npm test" --enter --json
orca terminal wait --for tui-idle --timeout-ms 30000 --json
orca terminal create --worktree path:/projects/app --command "npm test" --json
orca terminal split --direction vertical --command "npm run dev" --json
```
For tracked multi-agent work, use [Orchestration](/docs/cli/orchestration) instead of plain terminal prompts.
`terminal send` is for shells, dev servers and REPLs. To message another agent, use `orca orchestration send`; for tracked multi-agent work, use [Orchestration](/docs/cli/orchestration).
## File commands
+4 -4
View File
@@ -195,8 +195,8 @@ orca reference find STA-1234 --json
Choose an agent from `find`, then use its exact address:
```bash
orca terminal send --terminal '<terminal-from-find>' --text 'Status?' --enter
orca orchestration send --to '<mailbox-from-find>' --subject 'Status?' --type question
orca orchestration send --to '<terminal-from-find>' --subject 'Status' --body 'Status?' --type question
orca orchestration send --to '<mailbox-from-find>' --subject 'Status' --body 'Status?' --type question
```
Mailboxes are `dispatch:<id>` or `orca_session_id:<id>`; a `run:<id>` addresses a coordinator. Find never sends messages or assigns ownership. Adding references from a shell does not associate that shell with an agent.
@@ -209,7 +209,7 @@ orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --json
orca terminal read --terminal <handle> --screen --json
orca terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal send --terminal <handle> --text "npm test" --enter --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal create --worktree active --title "tests" --command "npm test" --json
orca terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
@@ -260,7 +260,7 @@ orca agent read orca_session_id:3540ecf3-47c3-4876-b825-81bf5d6b3595 --json
Every agent, chat or terminal, has an Orca session ID (`orca_session_id:<id>`), what Copy Orca Session ID copies. `agent list` lists agents in this host's workspaces with their IDs; a terminal agent shows none until it first reports to Orca. A chat keeps its ID across `/clear`; a terminal agent gets a new one. IDs belong to the host that runs the agent: agents on other hosts are not listed, and the output names those hosts with the `--environment` that lists them. A finished terminal agent stays listed as `done` while asleep, even after Orca restarts, unless it was reopened and slept again before doing anything new. An agent put to sleep mid-turn is not listed. After reopening, a terminal agent reappears only once it reports to Orca (for Codex, on its next turn). `agent read` still reads it in all these cases. `agent show` shows a listed sleeping agent's last state and where it wakes when its workspace is reopened.
`agent read` reads the conversation, not a screen: a chat's history, or a terminal agent's own transcript. The agent need not be running and reading never starts it. A terminal agent can be read while Orca knows where its transcript is (it is open, or asleep in a workspace; on Windows, a sleeping WSL agent only once its tab is reopened). The read can start with a state (`state` in `--json`) for the latest turn its own history records: `working` means that history shows an unfinished turn, so its reply may not be there yet, and `done` means the turn ended with its reply in the read. A terminal agent that exited mid-turn may keep reading `working`; check `orca agent show`. No state means unknown, never done. `agent list` and `agent show` report the last state known to Orca, which may differ. To message an agent, use `orca terminal send` or `orca orchestration send`; a sleeping terminal agent can't be messaged, so reopen its workspace first.
`agent read` reads the conversation, not a screen: a chat's history, or a terminal agent's own transcript. The agent need not be running and reading never starts it. A terminal agent can be read while Orca knows where its transcript is (it is open, or asleep in a workspace; on Windows, a sleeping WSL agent only once its tab is reopened). The read can start with a state (`state` in `--json`) for the latest turn its own history records: `working` means that history shows an unfinished turn, so its reply may not be there yet, and `done` means the turn ended with its reply in the read. A terminal agent that exited mid-turn may keep reading `working`; check `orca agent show`. No state means unknown, never done. `agent list` and `agent show` report the last state known to Orca, which may differ. To message an agent, use `orca orchestration send` with its terminal handle (a terminal agent) or `orca_session_id:<id>` (a chat), not `orca terminal send`; a sleeping terminal agent can't be messaged, so reopen its workspace first.
## Chats
+29 -12
View File
@@ -28,9 +28,9 @@ Prefer `--json` for agent-driven calls. If the CLI is missing, say so explicitly
A full handoff transfers ownership to another agent or worktree, then the original agent stops. Treat requests phrased as "hand off", "handoff", "handover", "give this to another agent", "give this to another worktree", "another agent", or "another worktree" as full handoffs unless the user expects the result back ("have another agent review this and report") or explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use decision gates, or manage ask/reply.
A handoff is done when the new worktree id and agent handle have been reported and the prompt was delivered: the launch's `prompt.outcome` is `journaled` or `handed-to-terminal`, or, for an agent that was already running, the send receipt reported `accepted: true`. Do not wait for the receiving agent to finish.
A handoff is done when the new worktree id and agent handle have been reported and the prompt was delivered: the launch's `prompt.outcome` is `journaled` or `handed-to-terminal`, or, for an agent that was already running, `orchestration send` returned a message ID. Do not wait for the receiving agent to finish.
Do not use `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. `task-create` is also forbidden because it records coordinator-owned tracking state; if a task row is needed, the user asked for supervised orchestration. Deliver the prompt with the agent launch, or with terminal commands for an agent that is already running.
Do not use `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. `task-create` is also forbidden because it records coordinator-owned tracking state; if a task row is needed, the user asked for supervised orchestration. Deliver the prompt with the agent launch, or with `orchestration send` for an agent that is already running (see Messaging agents); a one-way message needs no Task or Run.
For local work in the caller’s project, omit `--repo` and `--project`. Pass one to target another project or when Orca asks you to disambiguate; do not pick a repo from a list for unambiguous same-project work. The project comes from the caller’s directory, not the project visible in the app. Paired-server calls require an explicit server-side target.
@@ -56,10 +56,10 @@ For a fresh agent in a worktree that already exists, use `agent launch`, which t
ORCA agent launch --agent codex --worktree id:<repoId>::<worktreePath> --prompt "<task brief>" --json
```
Existing-terminal handoff:
Handoff to an agent that is already running:
```text
ORCA terminal send --terminal <handle> --text "<task brief>" --enter --json
ORCA orchestration send --to <terminal handle or orca_session_id:<chat id>> --subject "<task name>" --body "<task brief>" --json
```
## Starting agents
@@ -78,7 +78,25 @@ Every agent, chat or terminal, has an Orca session ID (`orca_session_id:<id>`; w
- `ORCA agent show <id> --json` shows where one agent is (none if closed, two if resumed in two panes). A listed sleeping terminal agent shows its last state and where it wakes when its workspace is reopened.
- `ORCA agent read <id> --json` reads what the agent said: a chat's history or a terminal agent's transcript, never its screen. It needs no running agent and never starts one. `state` describes the latest turn in this read's own history: `working` means that history shows an unfinished turn and the reply may not be there yet; a missing `state` means unknown, never done. A terminal agent that exited mid-turn may keep reading `working`; check `ORCA agent show`. `agent list`/`show` report the last state known to Orca, which may differ. A terminal agent is readable while Orca knows its transcript (open, or asleep in a workspace; on Windows, a sleeping WSL agent only once its tab is reopened).
A chat keeps its ID across `/clear`; a terminal agent gets a new one. A provider's own conversation id or a `term_…` handle is refused with the ID to use. To message an agent, use `terminal send` or `orchestration send` as below; a sleeping terminal agent can't be messaged, so reopen its workspace first.
A chat keeps its ID across `/clear`; a terminal agent gets a new one. A provider's own conversation id or a `term_…` handle is refused with the ID to use. To message an agent, use `orchestration send` (see Messaging agents); a sleeping terminal agent can't be messaged, so reopen its workspace first.
## Messaging agents
Send another agent a message with Orca mail, never by typing into its terminal:
```text
ORCA orchestration send --to <terminal handle or orca_session_id:<chat id>> --subject "<topic>" --body "<message>" --json
```
- Address a terminal agent by its terminal handle (`launch.outcome.handle`, or from `terminal list`); its Orca session ID is refused for sending today. Address a chat by `orca_session_id:<id>`.
- To find a terminal agent by its tab's name, match that name to a tab `title` in `terminal list --include-visual-layouts --json` and use the handle of the terminal in that tab. A terminal's own `title` is the agent's running title, and an agent may put the task's words in it, so it can repeat the name you are looking for. Chat tabs are not in that list; find a chat by its `title` in `agent list --json`. If no tab or several terminals match, ask the user. In a terminal, `ORCA_TERMINAL_HANDLE`, when set, is your own handle; never send to it.
- A one-way message needs no Task or Run. For a terminal, the warning that it "is a live terminal-only mailbox" and delivery "is not durable after that terminal closes" is expected; it only means the mail is lost if that terminal closes.
- For ordinary mail, the receipt means the mail was stored, not that the agent read it or started work. Exception: a send to a finished worker's `dispatch:<id>` can start a follow-up Task, and Orca enters its body in the worker as that task's prompt (the receipt says so). Follow progress with `agent read` or `terminal read`.
- For ordinary mail, a chat gets the whole message with its sender header; one too large for a chat message gets a note to run `orca orchestration check` instead. Ordinary mail never types your words into a terminal agent's input: when Orca wakes one, it types only that note, and the agent reads the mail by running the `check` command the note names (an agent already waiting in `check --wait` gets it as that call's result). Either answers with `ORCA orchestration reply --id <message_id> --body "<answer>" --json`.
- In a terminal, Orca sends that note only to an agent it recognizes as idle or working. A terminal agent Orca doesn't recognize (one that never reports its status to Orca) never gets it, and the mail waits unread. Start agents with `agent launch` or `worktree create --agent`, and put the first task in `--prompt`.
- As an agent, reach an agent on a paired server with `orchestration send --on <server>`, not `--environment` (see the `orchestration` skill).
- Mail comes from you, not the user. An agent waiting for its user's answer may still ask the user before acting on it; when it does, tell the user to answer that agent themselves.
- If mail is refused, follow the refusal or tell the user. Never fall back to `terminal send`.
## Worktrees
@@ -205,11 +223,11 @@ ORCA reference find STA-1234 --json
- Repeat create `--reference` to seed links before setup/agent startup. Do not combine it with legacy `--pr`, `--issue`, `--linear-issue`, `--gitlab-issue`, or `--gitlab-mr` flags. Legacy `worktree set --pr` still appends/selects; `linkedItems` remains the worktree output field.
- Find accepts a full URL or native issue key such as `STA-1234`; no bare numbers or custom shorthand. It searches stored links across sources, not conversation text (`ORCA search`). Narrow with `--worktree` or `--repo`; optionally `--include-archived`, `--limit` (default 50 workspaces). Check `truncated` before assuming complete coverage. Remote selectors refer to the execution host; never use local `current` for a paired host.
- Find returns all known agents in each matching workspace. `linked: true` requires recorded reference/session evidence; `linked: false` means ownership is unknown. Check `liveness` (`live`, `unverifiable`, `exited`) and choose the intended agent; never infer ownership merely from workspace membership.
- Send through the returned exact `terminal` handle or `mailbox` (`dispatch:<id>` / `orca_session_id:<id>`). If it returns a `dispatch:<id>` mailbox, the agent is a supervised worker: use the mailbox, not terminal input. A `run:<id>` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership.
- Message the agent with `orchestration send` to the returned `mailbox` (`dispatch:<id>` / `orca_session_id:<id>`) when there is one, otherwise to its exact `terminal` handle. A `dispatch:<id>` mailbox means the agent is a supervised worker. A `run:<id>` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership.
```text
ORCA terminal send --terminal <terminal-from-find> --text "Status?" --enter --json
ORCA orchestration send --to <mailbox-from-find> --subject "Status?" --type question --json
ORCA orchestration send --to <terminal-from-find> --subject "Status" --body "Status?" --type question --json
ORCA orchestration send --to <mailbox-from-find> --subject "Status" --body "Status?" --type question --json
```
## Worktree Comments
@@ -245,8 +263,7 @@ ORCA terminal read --terminal <handle> --json
ORCA terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
ORCA terminal read --terminal <handle> --screen --json
ORCA terminal read --json
ORCA terminal send --terminal <handle> --text "continue" --enter --json
ORCA terminal send --terminal <handle> --text "continue" --enter --wait-submit 10 --json
ORCA terminal send --terminal <handle> --text "npm test" --enter --json
ORCA terminal send --text "echo hello" --enter --json
ORCA terminal wait --terminal <handle> --for exit --timeout-ms 5000 --json
ORCA terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
@@ -277,9 +294,9 @@ Terminal rules:
- Use `terminal read` before `terminal send` unless the next input is obvious.
- `terminal read` returns accumulated output with escape sequences stripped, not the rendered screen, so anything that repaints (shells, progress bars, TUIs) reads as stacked fragments. Use `--screen` whenever the answer depends on what the terminal actually shows.
- `--screen` and `--cursor` are mutually exclusive: a screen read is the current frame and has no history to page.
- Use `terminal send` only for direct terminal input or one-off prompts where no task state, inbox, or reply tracking is needed.
- Use `terminal send` for shells, dev servers, REPLs and your own pane. Never use it to message another agent or answer its prompts, even when mail is refused; use `orchestration send` (see Messaging agents).
- `accepted: true` proves input acceptance, not a started turn. Use the receipt's `turn_started` stage when submission proof is needed; never resend on silence.
- A text-plus-Enter agent prompt is refused with `agent_prompt_blocked` while the agent shows a permission or trust menu. To answer the menu, send `--text` and `--enter` as separate commands.
- A text-plus-Enter agent prompt is refused with `agent_prompt_blocked` while the agent shows a permission or trust menu. A person answers it by sending `--text` and `--enter` as separate commands; never answer another agent's menu.
- A text-plus-Enter agent prompt returns a durable request ID and additive stages: `input_accepted`, then `turn_started` once the agent's turn is proven. Raw text-only, bare Enter, interrupt, and terminal query replies keep their existing direct-input behavior.
- A default send observes for 0 seconds, so a receipt that stops at `input_accepted` is expected and its warning means "unproven", not "failed". Pass `--wait-submit` when you need proof of submission.
- `--wait-submit <seconds>` only observes the same accepted prompt. A timeout returns queued/input-accepted truth without resending; after an ambiguous transport failure, repeat the exact command with the reported `--retry-request <id>`. Both text and `--json` receipts carry the same `warnings`.
@@ -168,7 +168,7 @@ List each in `contributes.hooks` (`{ "event", "onError"? }`; `main` and `trusted
event `{ workspaceId: string; kind: "worktree" | "folder"; path: string; branch: string }`; `next` may change nothing; stop with nothing (observe only)
- `agent.launch.before` (since 1.4.248): Orca is about to start an agent CLI in a terminal, from any launcher (new tab, workspace create, CLI, automation, orchestration). Change `command` or add `env` with `next`, or return `{ deny }` to refuse the launch. Restores of saved sessions are not hooked.
event `{ agent: string; workspaceId: string | null; workspaceKind: "worktree" | "folder" | null; terminalId?: string; command: string; env: Record<string, string> }`; `next` may change `command`, `env`; stop with `{ deny: string }`
- `agent.prompt.before` (since 1.4.248): Orca is about to submit a prompt to an agent in a terminal: a launch prompt, an orchestration dispatch, an issue or task prompt, or `orca terminal send` to an agent. A prompt a person submits is never hooked, and writes to one terminal stay in order while it decides. Rewrite `prompt` with `next`, or return `{ deny }` to refuse it.
- `agent.prompt.before` (since 1.4.248): Orca is about to submit a prompt to an agent in a terminal: a launch prompt, an orchestration dispatch, an issue or task prompt, or a prompt sent with `orca terminal send`. A prompt a person submits is never hooked, and writes to one terminal stay in order while it decides. Rewrite `prompt` with `next`, or return `{ deny }` to refuse it.
event `{ agent: string | null; terminalId: string; prompt: string; inputKind: "driving" | "orchestration" | "launch" }`; `next` may change `prompt`; stop with `{ deny: string }`
- `agent.tool.before` (since 1.4.248): An agent in an Orca terminal is about to run a tool. Claude Code waits for the answer: return `{ deny }` to refuse the call (the agent sees the reason) or change `input` with `next`; the person is still asked as usual. Other agents only report the call, so their results are ignored. Agents on SSH or WSL hosts are not hooked yet.
event `{ agent: string; workspaceId: string | null; terminalId?: string; tool: string; input: JSON; callId?: string }`; `next` may change `input`; stop with `{ deny: string }`
@@ -46,7 +46,7 @@ ORCA orchestration send --on <server> --to <term_…|orca_session_id:…> --subj
```
Your own Orca carries the mail and keeps the conversation. Replies come back to
your own `check`, and they wake you like local mail. The other agent answers
your own mailbox and wake you like local mail. The other agent answers
with a plain `reply --id <msg_id> --body <text>`; no flag is needed on either
side. Mail from another server names its sender as `<sender> on <server name>`.
@@ -180,9 +180,9 @@ export const ROOT_HELP_TEXT_SECONDARY = [
' $ orca worktree ps --limit 10',
' $ orca file open-changed --mode diff',
' $ orca file open src/App.tsx',
' $ orca terminal create --worktree active --command "codex"',
' $ orca terminal create --worktree active --command "pnpm dev"',
' $ orca terminal list --worktree path:/Users/me/orca/workspaces/orca/cli-test-1 --json',
' $ orca terminal send --terminal term_123 --text "hi" --enter',
' $ orca terminal send --terminal term_123 --text "npm test" --enter',
' $ orca terminal wait --terminal term_123 --for exit --timeout-ms 60000 --json',
' $ orca tab current --json',
' $ orca tab show --page page_123 --json',
@@ -201,8 +201,9 @@ function structuredSessionRefusal(flagName: 'from' | 'terminal'): RuntimeClientE
'no_active_sender_terminal',
`This chat session has no orchestration identity of its own, so --${flagName} cannot be inferred, ` +
`and no terminal handle names it — every live handle belongs to a different pane, and passing one ` +
`would consume that pane's mailbox. Drive a worker directly instead: create a worktree with ` +
`--agent to launch one in its first terminal, then use terminal send and terminal read.`
`would consume that pane's mailbox. To start other work, put its task in --prompt on ` +
`agent launch or worktree create --agent and follow it with agent read; otherwise tell the ` +
`user this chat cannot send Orca mail.`
)
}
@@ -20,7 +20,7 @@ export function attachDurableMutationRecovery(
// Why: a text-plus-Enter prompt refuses a menu; text-only and bare-Enter sends stay direct input.
const menuHint =
error.code === 'agent_prompt_blocked'
? ' The agent is showing a permission or trust prompt; to answer it, send --text and --enter as separate commands.'
? ' The agent is showing a permission or trust prompt; a person answers it with separate --text and --enter sends, and another agent never answers it.'
: ''
const message = `${error.message}${menuHint} Terminal prompt request ID: ${requestId}. Re-issue the exact command with --retry-request ${requestId} --wait-submit <seconds>; do not retry it without that ID.`
const data = {
+31 -14
View File
@@ -256,9 +256,9 @@ const ORCA_CLI_MARKDOWN = [
"",
"A full handoff transfers ownership to another agent or worktree, then the original agent stops. Treat requests phrased as \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"another agent\", or \"another worktree\" as full handoffs unless the user expects the result back (\"have another agent review this and report\") or explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use decision gates, or manage ask/reply.",
"",
"A handoff is done when the new worktree id and agent handle have been reported and the prompt was delivered: the launch's `prompt.outcome` is `journaled` or `handed-to-terminal`, or, for an agent that was already running, the send receipt reported `accepted: true`. Do not wait for the receiving agent to finish.",
"A handoff is done when the new worktree id and agent handle have been reported and the prompt was delivered: the launch's `prompt.outcome` is `journaled` or `handed-to-terminal`, or, for an agent that was already running, `orchestration send` returned a message ID. Do not wait for the receiving agent to finish.",
"",
"Do not use `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. `task-create` is also forbidden because it records coordinator-owned tracking state; if a task row is needed, the user asked for supervised orchestration. Deliver the prompt with the agent launch, or with terminal commands for an agent that is already running.",
"Do not use `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. `task-create` is also forbidden because it records coordinator-owned tracking state; if a task row is needed, the user asked for supervised orchestration. Deliver the prompt with the agent launch, or with `orchestration send` for an agent that is already running (see Messaging agents); a one-way message needs no Task or Run.",
"",
"For local work in the caller’s project, omit `--repo` and `--project`. Pass one to target another project or when Orca asks you to disambiguate; do not pick a repo from a list for unambiguous same-project work. The project comes from the caller’s directory, not the project visible in the app. Paired-server calls require an explicit server-side target.",
"",
@@ -284,10 +284,10 @@ const ORCA_CLI_MARKDOWN = [
"ORCA agent launch --agent codex --worktree id:<repoId>::<worktreePath> --prompt \"<task brief>\" --json",
"```",
"",
"Existing-terminal handoff:",
"Handoff to an agent that is already running:",
"",
"```text",
"ORCA terminal send --terminal <handle> --text \"<task brief>\" --enter --json",
"ORCA orchestration send --to <terminal handle or orca_session_id:<chat id>> --subject \"<task name>\" --body \"<task brief>\" --json",
"```",
"",
"## Starting agents",
@@ -306,7 +306,25 @@ const ORCA_CLI_MARKDOWN = [
"- `ORCA agent show <id> --json` shows where one agent is (none if closed, two if resumed in two panes). A listed sleeping terminal agent shows its last state and where it wakes when its workspace is reopened.",
"- `ORCA agent read <id> --json` reads what the agent said: a chat's history or a terminal agent's transcript, never its screen. It needs no running agent and never starts one. `state` describes the latest turn in this read's own history: `working` means that history shows an unfinished turn and the reply may not be there yet; a missing `state` means unknown, never done. A terminal agent that exited mid-turn may keep reading `working`; check `ORCA agent show`. `agent list`/`show` report the last state known to Orca, which may differ. A terminal agent is readable while Orca knows its transcript (open, or asleep in a workspace; on Windows, a sleeping WSL agent only once its tab is reopened).",
"",
"A chat keeps its ID across `/clear`; a terminal agent gets a new one. A provider's own conversation id or a `term_…` handle is refused with the ID to use. To message an agent, use `terminal send` or `orchestration send` as below; a sleeping terminal agent can't be messaged, so reopen its workspace first.",
"A chat keeps its ID across `/clear`; a terminal agent gets a new one. A provider's own conversation id or a `term_…` handle is refused with the ID to use. To message an agent, use `orchestration send` (see Messaging agents); a sleeping terminal agent can't be messaged, so reopen its workspace first.",
"",
"## Messaging agents",
"",
"Send another agent a message with Orca mail, never by typing into its terminal:",
"",
"```text",
"ORCA orchestration send --to <terminal handle or orca_session_id:<chat id>> --subject \"<topic>\" --body \"<message>\" --json",
"```",
"",
"- Address a terminal agent by its terminal handle (`launch.outcome.handle`, or from `terminal list`); its Orca session ID is refused for sending today. Address a chat by `orca_session_id:<id>`.",
"- To find a terminal agent by its tab's name, match that name to a tab `title` in `terminal list --include-visual-layouts --json` and use the handle of the terminal in that tab. A terminal's own `title` is the agent's running title, and an agent may put the task's words in it, so it can repeat the name you are looking for. Chat tabs are not in that list; find a chat by its `title` in `agent list --json`. If no tab or several terminals match, ask the user. In a terminal, `ORCA_TERMINAL_HANDLE`, when set, is your own handle; never send to it.",
"- A one-way message needs no Task or Run. For a terminal, the warning that it \"is a live terminal-only mailbox\" and delivery \"is not durable after that terminal closes\" is expected; it only means the mail is lost if that terminal closes.",
"- For ordinary mail, the receipt means the mail was stored, not that the agent read it or started work. Exception: a send to a finished worker's `dispatch:<id>` can start a follow-up Task, and Orca enters its body in the worker as that task's prompt (the receipt says so). Follow progress with `agent read` or `terminal read`.",
"- For ordinary mail, a chat gets the whole message with its sender header; one too large for a chat message gets a note to run `orca orchestration check` instead. Ordinary mail never types your words into a terminal agent's input: when Orca wakes one, it types only that note, and the agent reads the mail by running the `check` command the note names (an agent already waiting in `check --wait` gets it as that call's result). Either answers with `ORCA orchestration reply --id <message_id> --body \"<answer>\" --json`.",
"- In a terminal, Orca sends that note only to an agent it recognizes as idle or working. A terminal agent Orca doesn't recognize (one that never reports its status to Orca) never gets it, and the mail waits unread. Start agents with `agent launch` or `worktree create --agent`, and put the first task in `--prompt`.",
"- As an agent, reach an agent on a paired server with `orchestration send --on <server>`, not `--environment` (see the `orchestration` skill).",
"- Mail comes from you, not the user. An agent waiting for its user's answer may still ask the user before acting on it; when it does, tell the user to answer that agent themselves.",
"- If mail is refused, follow the refusal or tell the user. Never fall back to `terminal send`.",
"",
"## Worktrees",
"",
@@ -433,11 +451,11 @@ const ORCA_CLI_MARKDOWN = [
"- Repeat create `--reference` to seed links before setup/agent startup. Do not combine it with legacy `--pr`, `--issue`, `--linear-issue`, `--gitlab-issue`, or `--gitlab-mr` flags. Legacy `worktree set --pr` still appends/selects; `linkedItems` remains the worktree output field.",
"- Find accepts a full URL or native issue key such as `STA-1234`; no bare numbers or custom shorthand. It searches stored links across sources, not conversation text (`ORCA search`). Narrow with `--worktree` or `--repo`; optionally `--include-archived`, `--limit` (default 50 workspaces). Check `truncated` before assuming complete coverage. Remote selectors refer to the execution host; never use local `current` for a paired host.",
"- Find returns all known agents in each matching workspace. `linked: true` requires recorded reference/session evidence; `linked: false` means ownership is unknown. Check `liveness` (`live`, `unverifiable`, `exited`) and choose the intended agent; never infer ownership merely from workspace membership.",
"- Send through the returned exact `terminal` handle or `mailbox` (`dispatch:<id>` / `orca_session_id:<id>`). If it returns a `dispatch:<id>` mailbox, the agent is a supervised worker: use the mailbox, not terminal input. A `run:<id>` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership.",
"- Message the agent with `orchestration send` to the returned `mailbox` (`dispatch:<id>` / `orca_session_id:<id>`) when there is one, otherwise to its exact `terminal` handle. A `dispatch:<id>` mailbox means the agent is a supervised worker. A `run:<id>` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership.",
"",
"```text",
"ORCA terminal send --terminal <terminal-from-find> --text \"Status?\" --enter --json",
"ORCA orchestration send --to <mailbox-from-find> --subject \"Status?\" --type question --json",
"ORCA orchestration send --to <terminal-from-find> --subject \"Status\" --body \"Status?\" --type question --json",
"ORCA orchestration send --to <mailbox-from-find> --subject \"Status\" --body \"Status?\" --type question --json",
"```",
"",
"## Worktree Comments",
@@ -473,8 +491,7 @@ const ORCA_CLI_MARKDOWN = [
"ORCA terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json",
"ORCA terminal read --terminal <handle> --screen --json",
"ORCA terminal read --json",
"ORCA terminal send --terminal <handle> --text \"continue\" --enter --json",
"ORCA terminal send --terminal <handle> --text \"continue\" --enter --wait-submit 10 --json",
"ORCA terminal send --terminal <handle> --text \"npm test\" --enter --json",
"ORCA terminal send --text \"echo hello\" --enter --json",
"ORCA terminal wait --terminal <handle> --for exit --timeout-ms 5000 --json",
"ORCA terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json",
@@ -505,9 +522,9 @@ const ORCA_CLI_MARKDOWN = [
"- Use `terminal read` before `terminal send` unless the next input is obvious.",
"- `terminal read` returns accumulated output with escape sequences stripped, not the rendered screen, so anything that repaints (shells, progress bars, TUIs) reads as stacked fragments. Use `--screen` whenever the answer depends on what the terminal actually shows.",
"- `--screen` and `--cursor` are mutually exclusive: a screen read is the current frame and has no history to page.",
"- Use `terminal send` only for direct terminal input or one-off prompts where no task state, inbox, or reply tracking is needed.",
"- Use `terminal send` for shells, dev servers, REPLs and your own pane. Never use it to message another agent or answer its prompts, even when mail is refused; use `orchestration send` (see Messaging agents).",
"- `accepted: true` proves input acceptance, not a started turn. Use the receipt's `turn_started` stage when submission proof is needed; never resend on silence.",
"- A text-plus-Enter agent prompt is refused with `agent_prompt_blocked` while the agent shows a permission or trust menu. To answer the menu, send `--text` and `--enter` as separate commands.",
"- A text-plus-Enter agent prompt is refused with `agent_prompt_blocked` while the agent shows a permission or trust menu. A person answers it by sending `--text` and `--enter` as separate commands; never answer another agent's menu.",
"- A text-plus-Enter agent prompt returns a durable request ID and additive stages: `input_accepted`, then `turn_started` once the agent's turn is proven. Raw text-only, bare Enter, interrupt, and terminal query replies keep their existing direct-input behavior.",
"- A default send observes for 0 seconds, so a receipt that stops at `input_accepted` is expected and its warning means \"unproven\", not \"failed\". Pass `--wait-submit` when you need proof of submission.",
"- `--wait-submit <seconds>` only observes the same accepted prompt. A timeout returns queued/input-accepted truth without resending; after an ambiguous transport failure, repeat the exact command with the reported `--retry-request <id>`. Both text and `--json` receipts carry the same `warnings`.",
@@ -3240,7 +3257,7 @@ const ORCA_PLUGIN_AUTHORING_HOST_API_REFERENCE_MARKDOWN = [
" event `{ workspaceId: string; kind: \"worktree\" | \"folder\"; path: string; branch: string }`; `next` may change nothing; stop with nothing (observe only)",
"- `agent.launch.before` (since 1.4.248): Orca is about to start an agent CLI in a terminal, from any launcher (new tab, workspace create, CLI, automation, orchestration). Change `command` or add `env` with `next`, or return `{ deny }` to refuse the launch. Restores of saved sessions are not hooked.",
" event `{ agent: string; workspaceId: string | null; workspaceKind: \"worktree\" | \"folder\" | null; terminalId?: string; command: string; env: Record<string, string> }`; `next` may change `command`, `env`; stop with `{ deny: string }`",
"- `agent.prompt.before` (since 1.4.248): Orca is about to submit a prompt to an agent in a terminal: a launch prompt, an orchestration dispatch, an issue or task prompt, or `orca terminal send` to an agent. A prompt a person submits is never hooked, and writes to one terminal stay in order while it decides. Rewrite `prompt` with `next`, or return `{ deny }` to refuse it.",
"- `agent.prompt.before` (since 1.4.248): Orca is about to submit a prompt to an agent in a terminal: a launch prompt, an orchestration dispatch, an issue or task prompt, or a prompt sent with `orca terminal send`. A prompt a person submits is never hooked, and writes to one terminal stay in order while it decides. Rewrite `prompt` with `next`, or return `{ deny }` to refuse it.",
" event `{ agent: string | null; terminalId: string; prompt: string; inputKind: \"driving\" | \"orchestration\" | \"launch\" }`; `next` may change `prompt`; stop with `{ deny: string }`",
"- `agent.tool.before` (since 1.4.248): An agent in an Orca terminal is about to run a tool. Claude Code waits for the answer: return `{ deny }` to refuse the call (the agent sees the reason) or change `input` with `next`; the person is still asked as usual. Other agents only report the call, so their results are ignored. Agents on SSH or WSL hosts are not hooked yet.",
" event `{ agent: string; workspaceId: string | null; terminalId?: string; tool: string; input: JSON; callId?: string }`; `next` may change `input`; stop with `{ deny: string }`",
@@ -4282,7 +4299,7 @@ const ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN = [
"```",
"",
"Your own Orca carries the mail and keeps the conversation. Replies come back to",
"your own `check`, and they wake you like local mail. The other agent answers",
"your own mailbox and wake you like local mail. The other agent answers",
"with a plain `reply --id <msg_id> --body <text>`; no flag is needed on either",
"side. Mail from another server names its sender as `<sender> on <server name>`.",
"",
+2
View File
@@ -15,7 +15,9 @@ export const TERMINAL_SEND_COMMAND_SPEC: CommandSpec = {
'wait-submit',
'retry-request'
],
examples: ['orca terminal send --terminal term_123 --text "npm test" --enter --json'],
notes: [
'For shells, dev servers, REPLs and your own pane. To message another agent, use orca orchestration send; never type into its input.',
"Without --enter, --text is written to the PTY verbatim, so control bytes pass through (Bash/Zsh: --text $'\\x1b' for Escape, $'\\x15' for Ctrl+U).",
'With --enter and without --interrupt, a prompt to a recognized running agent is bracketed-pasted and embedded Escape bytes are made inert.',
'For a text-plus-Enter agent prompt, the result separates input acceptance from observed submission and turn start.',
@@ -82,8 +82,9 @@ export function buildInjectRejectionMessage(terminal: string): string {
return (
`Cannot dispatch --inject to terminal ${terminal}: no recognized agent detected. ` +
`Orca detects these agent CLIs (${RECOGNIZED_AGENT_PROCESS_NAMES.join(', ')}). ` +
'Start one in the terminal and let it finish launching, ' +
'or dispatch without --inject and send the prompt manually.'
'Start one in the terminal, let it finish launching, then retry; ' +
`or have Orca start one in its workspace: take worktreeId from orca terminal show --terminal ${terminal} --json, ` +
'then run orca orchestration worker-start --task <task_id> --worktree id:<worktreeId> --agent <agent>.'
)
}
@@ -101,7 +102,7 @@ export function injectRejectedRefusal(
reason,
nextSteps: [
'Start a recognized agent CLI in that terminal and wait for it to finish launching, or pick a terminal that already runs one.',
'Alternatively dispatch without --inject and deliver the prompt with orca terminal send --terminal <handle> --text <prompt> --enter --json.'
`Or have Orca start one in that terminal's workspace: take worktreeId from orca terminal show --terminal ${terminal} --json, then run orca orchestration worker-start --task <task_id> --worktree id:<worktreeId> --agent <agent> --json. Otherwise tell the user.`
]
}
}
@@ -164,7 +164,7 @@ export const PLUGIN_HOOK_SPECS = {
mutable: ['prompt'],
deadlineMs: PLUGIN_HOOK_DEFAULT_DEADLINE_MS,
summary:
'Orca is about to submit a prompt to an agent in a terminal: a launch prompt, an orchestration dispatch, an issue or task prompt, or `orca terminal send` to an agent. A prompt a person submits is never hooked, and writes to one terminal stay in order while it decides. Rewrite `prompt` with `next`, or return `{ deny }` to refuse it.'
'Orca is about to submit a prompt to an agent in a terminal: a launch prompt, an orchestration dispatch, an issue or task prompt, or a prompt sent with `orca terminal send`. A prompt a person submits is never hooked, and writes to one terminal stay in order while it decides. Rewrite `prompt` with `next`, or return `{ deny }` to refuse it.'
},
'agent.tool.before': {
payload: agentToolBeforeHookPayloadSchema,