Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions agent/orchestrator/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ A session started from CanvasTTY's launcher with the **Orchestrator** role has t

1. `list_providers`: which agents CanvasTTY can launch here. Each entry's `id` is the exact `spawn_agent.provider` value; prefer entries that are `available` with `signIn: "ok"` (`unknown` only means CanvasTTY has not checked yet). When plugins offer launch options (for example an accounts plugin's `list_routes` tool), the answer names that tool.
2. `spawn_agent` once per part of the task: a known `provider` id, an absolute `cwd` and a self-contained prompt. An unknown provider is refused with a pointer back to `list_providers`. **If the person names a model, pass it as `model`** in the format `list_providers` gives for that provider (`model.format`; OpenCode takes `provider/model`, for example `zai-coding-plan/glm-5.3-flash`, and `model.known` lists what `opencode models` reported); without `model` the CLI uses its own default. `effort` sets the reasoning effort where the CLI has one (`efforts`). Without `profile` the subagent gets your own launch profile, or the next lower one its CLI has (never more than yours, never YOLO); `list_providers` shows each provider's `profiles`. `cwd` must be this project's folder or a folder inside it. A refusal says why (a folder outside the project, a profile above yours, a limit the person set): change the request, do not retry it.
3. `wait_for_agent` for each subagent (`timeoutSeconds` up to 600; a call returns within 50 seconds unless you are Claude Code; `timeout` means it is still running, so read `output` as progress and call it again) instead of polling. `needs_approval` means the person must answer a prompt in that card: never answer it yourself.
3. `wait_for_agent` for each subagent (`timeoutSeconds` up to 600; a call returns within 50 seconds unless you are Claude Code; `timeout` means it is still running, so read `output` as progress and call it again) instead of polling. `needs_approval` means the person must answer a prompt in that card (`output` shows it, for example a shell command): never answer it yourself, and `send_to_agent` is refused meanwhile. Tell the person what it asks, then call `wait_for_agent` again: it waits for their answer.
4. `get_agent_result` to read what the subagent produced; check the actual files before reporting success.

Do not explore the filesystem, `PATH` or config folders (for example `~/.local/bin` or `~/.config/<cli>`) looking for agents or their configuration: `list_providers` is what CanvasTTY can launch, and delegation goes through `spawn_agent`.
Expand All @@ -32,10 +32,10 @@ Use the bundled `canvastty-control.mjs` CLI with a running CanvasTTY instance wh

Run `providers` first to see which providers are installed and signed in. If the person names a model, add `--model <id>` (OpenCode: `provider/model`); `--effort <level>` works for Codex, Claude and Grok.

`--provider` accepts codex, claude, qwen, kimi, opencode, hermes, grok, omp and pi; each worker uses that provider's own normal/YOLO launch flags. The create response includes `capabilities`: only Codex workers have `result: true` (captured final answer) and `menus: true` (startup/approval menus that `choose`/`dismiss` can act on). For other providers, `result` ends as `no_result` and menus must be resolved by the user; treat their `screen` text as the only evidence. From the person's own terminal CLI creation defaults to YOLO, using the provider's full-access, no-approval launch flag; inside an Orchestrator session it defaults to that session's profile. It does not change global provider settings. `--profile normal` is available when the user requests their ordinary configured profile; do not silently replace their selected permissions.
`--provider` accepts codex, claude, qwen, kimi, opencode, hermes, grok, omp and pi; each worker uses that provider's own normal/YOLO launch flags. The create response includes `capabilities`: only Codex workers have `result: true` (captured final answer) and `menus: true` (startup menus that `choose`/`dismiss` can act on). For other providers, `result` ends as `no_result` and menus must be resolved by the user; treat their `screen` text as the only evidence. From the person's own terminal CLI creation defaults to YOLO, using the provider's full-access, no-approval launch flag; inside an Orchestrator session it defaults to that session's profile. It does not change global provider settings. `--profile normal` is available when the user requests their ordinary configured profile; do not silently replace their selected permissions.
4. Save the returned session ID and request ID. Verify provider, profile, cwd and launch status. A returned ID or an idle status alone does not prove a working agent.
5. Inspect `screen <id>` until the worker is at an empty composer (verified automatically for Codex; for other providers judge from the screen text). Trust, authentication, permission menus and startup failures are not task prompts. Do not submit a task to dismiss them.
6. Resolve only reviewed, authorized menu actions: `choose <id> --choice <observed-number> --revision <interaction.revision>`. For an idle menu offering Escape, `dismiss <id> --revision <screen.revision>` closes it. A stale revision requires another inspection. In particular, inspect new or changed lifecycle hooks before trusting them; YOLO does not imply approval of unknown hooks. Verify the next screen after each choice.
6. An approval or permission prompt (`status` is `needs_approval`, or Codex asks to run a command, apply edits or grant access) is the person's to answer, never yours: inside an Orchestrator session `choose`, `dismiss` and `send` are refused with `NEEDS_PERSON` meanwhile, and `choose`/`dismiss` are refused on any Codex menu other than hooks review or a model, rate-limit or update notice. Tell the person what it asks, then check `status` again. Resolve only reviewed, authorized startup menu actions: `choose <id> --choice <observed-number> --revision <interaction.revision>`. For an idle menu offering Escape, `dismiss <id> --revision <screen.revision>` closes it. A stale revision requires another inspection. In particular, inspect new or changed lifecycle hooks before trusting them; YOLO does not imply approval of unknown hooks. Verify the next screen after each choice.

## Run and verify

Expand Down
12 changes: 8 additions & 4 deletions docs/agent-orchestration.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ A session launched from the desktop with the **Orchestrator** role gets the `can
| --- | --- |
| `list_providers` | The agent providers CanvasTTY can launch as subagents: `id` (the exact `spawn_agent.provider` value), `name`, `installed`/`available` (from the provider CLI registry resolved at startup or on a recheck), `signIn` (`ok`, `signed_out`, `expired` or `unknown`, from the last usage-limits read; it never starts a read and never reads credentials), `subagent` and `orchestrator` support, `model` (whether the CLI takes one, its format, and for OpenCode the models a cached `opencode models` listing reported: run in the background with a 5 s timeout, refreshed after 10 minutes, never awaited) and `efforts`, and plugin launch options (`launchOptions`, plus `launchOptionTools` such as an accounts plugin's `list_routes`). Fast: cached state only, no network calls. |
| `spawn_agent` | Launches a subagent (profile: see below). `provider` must be a `list_providers` id (the schema lists them); an unknown one is refused with `INVALID_REQUEST` naming `list_providers`. Optional `model` goes to the CLI's own `--model` for that run (OpenCode `provider/model`; Codex, Claude, Qwen, Kimi alias, Grok, OMP, Pi, Cursor; Hermes, MiniMax, Devin and Antigravity take none) and optional `effort` to its reasoning effort (Codex `-c model_reasoning_effort`, Claude `--effort`, Grok `--reasoning-effort`). Both are checked per provider, kept on restart and restore, and never written to the CLI's configuration. If the person names a model, the orchestrator passes it as `model`. An OpenCode model its own `opencode models` list does not contain is refused before launch with up to five closest listed ids (OpenCode would otherwise stop with only "Unexpected server error"); when that list cannot be read, the model is passed as given. A subagent that exits anyway reports the last lines of its screen as `exitLines` in `wait_for_agent`, `observe_agent` and `get_agent_result`. |
| `wait_for_agent` | `{ sessionId, timeoutSeconds ≤ 600 }` (default 55). For an orchestrator other than Claude Code a call returns after at most 50 seconds, because its MCP client (Codex, OpenCode and others) ends a tool call after about 60 seconds; `timeout` then means the subagent is still running, with its progress in the plain-text output. Returns when the subagent is `idle` (after a prompt: only once a turn that started after the latest delivered prompt has ended, so the CLI's startup idle does not count), `needs_approval`, `done`/`failed` (exited), `quiet` (reports no status and its screen stopped changing), `closed`, or on `timeout`, with `status`, `exitCode`, `waitedMs` and the end of the subagent's screen as masked plain text (as `get_agent_result`). Only this orchestrator's own subagents; it stops at once when the call is canceled or the orchestrator disconnects. |
| `wait_for_agent` | `{ sessionId, timeoutSeconds ≤ 600 }` (default 55). For an orchestrator other than Claude Code a call returns after at most 50 seconds, because its MCP client (Codex, OpenCode and others) ends a tool call after about 60 seconds; `timeout` then means the subagent is still running, with its progress in the plain-text output. Returns when the subagent is `idle` (after a prompt: only once a turn that started after the latest delivered prompt has ended, so the CLI's startup idle does not count), `needs_approval` (once per prompt: a later wait on the same prompt waits for the person's answer instead of returning it again, while a new request, even one right after the person answered the last, returns at once), `done`/`failed` (exited), `quiet` (reports no status and its screen stopped changing), `closed`, or on `timeout`, with `status`, `exitCode`, `waitedMs` and the end of the subagent's screen as masked plain text (as `get_agent_result`). Only this orchestrator's own subagents; it stops at once when the call is canceled or the orchestrator disconnects. |
| `get_agent_result`, `observe_agent` | `get_agent_result`: `answer`, the final reply of the subagent's last turn as the agent itself reported it (Codex through its Stop hook, OpenCode through CanvasTTY's plugin reading the session's last assistant message at `session.idle`; at most 4,096 characters with the end kept, masked, in memory only and cleared when a prompt is submitted or the next turn starts), plus `status`, the exit state and the end of the subagent's screen as masked plain text (a headless terminal renders the redraws of a full-screen TUI such as OpenCode from the last 64 KiB of masked output, so no control sequences remain; `wait_for_agent` returns the same). Other providers have no `answer`: read that text. `observe_agent`: the current status and the end of the screen as the same plain text (at most `maxChars`). |
| `send_to_agent`, `cancel_agent`, `list_agents` | Follow-up prompts, disposing a subagent, listing this session's subagents. |
| `send_to_agent`, `cancel_agent`, `list_agents` | Follow-up prompts, disposing a subagent, listing this session's subagents. `send_to_agent` is refused while the subagent is `needs_approval` (any CLI's own approval or permission prompt: Claude Code, Codex, Grok, Kimi, Qwen, Hermes, OpenCode's permission and question prompts): what it typed (or its Enter) would answer the person's prompt. |

### Subagent profiles

Expand All @@ -28,7 +28,11 @@ OpenCode's native `--auto` skips approvals, so CanvasTTY's supervised auto profi
- `external_directory` is untouched: anything outside the project folder asks as before (each tool checks it first).
- The person's own deny and ask rules for these tools (global and project `opencode.json(c)`, `OPENCODE_CONFIG`, the inline config) are appended after the auto rules, so they still win: auto never allows what the person denied or wanted to be asked about.

A launch contributor that puts OpenCode on another model keeps `bash` asking, like accept-edits for the other CLIs.
A launch contributor that puts OpenCode on another model keeps `bash` asking, like accept-edits for the other CLIs. In a subagent's card that ask goes to the person as every subagent's prompt does:

- CanvasTTY's guard sees the command first. A decision service's deny fails the call with its reason before OpenCode asks; an allow from a plugin the person let allow answers OpenCode's prompt once. Neither leaves a prompt waiting.
- With no verdict, OpenCode's own prompt stays. The card turns `needs_approval`, which puts it in Needs attention (and the notification, when it is on). Its row opens the card, where the person answers the prompt OpenCode shows for that exact call.
- The orchestrator's `wait_for_agent` returns `needs_approval` with the prompt in `output`. It cannot answer it: `send_to_agent` is refused while the subagent waits, and a second `wait_for_agent` waits for the person's answer, then for the subagent's turn to end.

The control CLI's `create --profile` accepts `auto`, `normal`, `ask`, `askCached`, `acceptEdits`, `dontAsk`, `autonomous`, `plan`, `readOnly`, and `yolo`, where the provider supports them. See the [complete launch-mode matrix](agent-launch-modes.md) for native mappings and restrictions. From the person's own terminal it defaults to YOLO, which needs the person's acknowledgement for that CLI; subagents never receive YOLO.

Expand Down Expand Up @@ -143,7 +147,7 @@ and clipped unstyled hints remain blocked. See the [program status protocol](htt

On macOS/Linux, OpenCode delivery waits for its current launch's alternate-screen then visible-cursor sequence; CLIs without that sequence fail without a write, Windows retains its existing ungated startup behavior, and this startup check does not protect an OpenCode human draft or acknowledge acceptance.

For a visible numbered menu, `screen` returns `interaction.options`, the selected option and a screen revision. After inspecting the choices and confirming the action is within the task's authorization, use `choose SESSION_ID --choice N --revision HASH`. To close an idle menu that explicitly offers Escape, use `dismiss SESSION_ID --revision HASH`. Both commands reject a changed screen, act only on the owned PTY and return delivery receipts; inspect the next screen to confirm the outcome. They do not automatically approve anything.
For a visible numbered menu, `screen` returns `interaction.options`, the selected option and a screen revision. After inspecting the choices and confirming the action is within the task's authorization, use `choose SESSION_ID --choice N --revision HASH`. To close an idle menu that explicitly offers Escape, use `dismiss SESSION_ID --revision HASH`. Both commands reject a changed screen, act only on the owned PTY and return delivery receipts; inspect the next screen to confirm the outcome. They do not automatically approve anything. On an orchestrator's own connection they never answer an approval or permission prompt: while the worker is `needs_approval`, or the menu is Codex's own approval prompt (run a command, apply edits, grant permissions or network access, an MCP server's request), `choose`, `dismiss` and `send` are refused with `NEEDS_PERSON` and nothing is written. The person answers it in the card (or a decision service they allowed does, before the CLI asks); the orchestrator tells them what it asks and checks `status` again. Only hooks review (and its "hooks reviewed" notice), the model or rate-limit notice and the update notice stay the orchestrator's to resolve: `choose` and `dismiss` on any other Codex menu (folder trust, a permissions change, an approval worded in a way CanvasTTY does not recognise) are refused with `NEEDS_PERSON` the same way, so a new or unrecognised prompt fails closed. The person's own connection (the app-wide descriptor) is unchanged. `interrupt` still stops the orchestrator's own submitted turn: stopping is not an answer, and the asked call does not run.

Codex may show **Hooks need review** on first launch or after the bundled lifecycle helpers change. Review the listed commands before trusting them through the observed menu. This is a separate startup step from selecting YOLO and is never dismissed by submitting a task. Controlled launches disable Codex's terminal animations for stable composer detection; ordinary sessions keep their configuration.

Expand Down
Loading
Loading