diff --git a/agent/orchestrator/SKILL.md b/agent/orchestrator/SKILL.md index 3ac0ab598..7b49e0519 100644 --- a/agent/orchestrator/SKILL.md +++ b/agent/orchestrator/SKILL.md @@ -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/`) looking for agents or their configuration: `list_providers` is what CanvasTTY can launch, and delegation goes through `spawn_agent`. @@ -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 ` (OpenCode: `provider/model`); `--effort ` 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 ` 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 --choice --revision `. For an idle menu offering Escape, `dismiss --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 --choice --revision `. For an idle menu offering Escape, `dismiss --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 diff --git a/docs/agent-orchestration.md b/docs/agent-orchestration.md index 08114b621..d21cef31d 100644 --- a/docs/agent-orchestration.md +++ b/docs/agent-orchestration.md @@ -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 @@ -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. @@ -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. diff --git a/native/canvastty-helper/catalog.json b/native/canvastty-helper/catalog.json index 4c9ff8e2c..c48ae3cf2 100644 --- a/native/canvastty-helper/catalog.json +++ b/native/canvastty-helper/catalog.json @@ -1057,7 +1057,7 @@ }, { "name": "send_to_agent", - "description": "Write a prompt into one of this session's subagents. sent: true confirms a PTY write. Inspect delivery.stage (pasted or submitted), delivery.acceptance (confirmed or unconfirmed), and delivery.reason; a partial paste must not be resent blindly. Codex, Claude and Kimi receive a separate submit key only after the paste appears in their input field. Use wait_for_agent and inspect its answer or screen to confirm progress; never retry Enter blindly. Plain terminal sessions are not agents.", + "description": "Write a prompt into one of this session's subagents. sent: true confirms a PTY write. Inspect delivery.stage (pasted or submitted), delivery.acceptance (confirmed or unconfirmed), and delivery.reason; a partial paste must not be resent blindly. Codex, Claude and Kimi receive a separate submit key only after the paste appears in their input field. Use wait_for_agent and inspect its answer or screen to confirm progress; never retry Enter blindly. Plain terminal sessions are not agents. Refused while the subagent is needs_approval: that prompt is the person's to answer.", "inputSchema": { "type": "object", "properties": { @@ -1107,7 +1107,7 @@ }, { "name": "wait_for_agent", - "description": "Wait until one of this session's subagents stops working, instead of polling observe_agent or get_agent_result; nothing is sent to it while it waits. Returns reason \"idle\" (the turn that answers your latest prompt ended and it waits for input; an idle before that turn started does not count), \"needs_approval\" (its card shows a prompt only the person may answer; never answer it yourself), \"done\" or \"failed\" (its process exited), \"quiet\" (it reports no status or no turn start and its screen stopped changing, so judge from output), \"closed\" (its card was closed) or \"timeout\" after timeoutSeconds (default 55, at most 600; unless this session is Claude Code, a call returns after at most 50 seconds, before its MCP client would end the call), with status, exitCode, waitedMs, the end of its screen as masked plain text as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents); when the subagent's process exited (for example at once, on a model its CLI does not know), exitLines holds the last lines of its screen as plain text, which say why. A timeout means it is still running: read output as its progress and call wait_for_agent again. Then read get_agent_result.", + "description": "Wait until one of this session's subagents stops working, instead of polling observe_agent or get_agent_result; nothing is sent to it while it waits. Returns reason \"idle\" (the turn that answers your latest prompt ended and it waits for input; an idle before that turn started does not count), \"needs_approval\" (its card shows a prompt only the person may answer, such as a shell command it wants to run, shown in output; never answer it yourself: tell the person what it asks, then call wait_for_agent again, which waits for their answer instead of returning the same prompt again), \"done\" or \"failed\" (its process exited), \"quiet\" (it reports no status or no turn start and its screen stopped changing, so judge from output), \"closed\" (its card was closed) or \"timeout\" after timeoutSeconds (default 55, at most 600; unless this session is Claude Code, a call returns after at most 50 seconds, before its MCP client would end the call), with status, exitCode, waitedMs, the end of its screen as masked plain text as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents); when the subagent's process exited (for example at once, on a model its CLI does not know), exitLines holds the last lines of its screen as plain text, which say why. A timeout means it is still running: read output as its progress and call wait_for_agent again. Then read get_agent_result.", "inputSchema": { "type": "object", "properties": { diff --git a/scripts/canvastty-control.mjs b/scripts/canvastty-control.mjs index 462db18c4..000744a11 100644 --- a/scripts/canvastty-control.mjs +++ b/scripts/canvastty-control.mjs @@ -155,8 +155,11 @@ create --cwd [--provider ] [--title ] [--yolo | --profile --model: the CLI's own --model for this worker (OpenCode: provider/model); if the person names a model, pass it. --effort: codex, claude and grok only. providers shows each provider's model format and effort levels. - Only Codex workers report a captured result and expose startup/approval menus - to choose/dismiss; the create response lists each worker's capabilities. + Only Codex workers report a captured result and expose startup menus to + choose/dismiss; the create response lists each worker's capabilities. From an + Orchestrator session, choose, dismiss and send are refused (NEEDS_PERSON) while + a worker waits at an approval or permission prompt: only the person answers it. + There, choose/dismiss act only on hooks review and model or update notices. list status screen diff --git a/src/agent-browser/orchestration-catalog.mjs b/src/agent-browser/orchestration-catalog.mjs index 0442893b2..62967aa1e 100644 --- a/src/agent-browser/orchestration-catalog.mjs +++ b/src/agent-browser/orchestration-catalog.mjs @@ -77,7 +77,7 @@ export const ORCHESTRATION_TOOL_DEFINITIONS = Object.freeze([ ), tool( "send_to_agent", - "Write a prompt into one of this session's subagents. sent: true confirms a PTY write. Inspect delivery.stage (pasted or submitted), delivery.acceptance (confirmed or unconfirmed), and delivery.reason; a partial paste must not be resent blindly. Codex, Claude and Kimi receive a separate submit key only after the paste appears in their input field. Use wait_for_agent and inspect its answer or screen to confirm progress; never retry Enter blindly. Plain terminal sessions are not agents.", + "Write a prompt into one of this session's subagents. sent: true confirms a PTY write. Inspect delivery.stage (pasted or submitted), delivery.acceptance (confirmed or unconfirmed), and delivery.reason; a partial paste must not be resent blindly. Codex, Claude and Kimi receive a separate submit key only after the paste appears in their input field. Use wait_for_agent and inspect its answer or screen to confirm progress; never retry Enter blindly. Plain terminal sessions are not agents. Refused while the subagent is needs_approval: that prompt is the person's to answer.", { sessionId, prompt, submit: boolean() }, ["sessionId", "prompt"] ), @@ -89,7 +89,7 @@ export const ORCHESTRATION_TOOL_DEFINITIONS = Object.freeze([ ), tool( "wait_for_agent", - `Wait until one of this session's subagents stops working, instead of polling observe_agent or get_agent_result; nothing is sent to it while it waits. Returns reason "idle" (the turn that answers your latest prompt ended and it waits for input; an idle before that turn started does not count), "needs_approval" (its card shows a prompt only the person may answer; never answer it yourself), "done" or "failed" (its process exited), "quiet" (it reports no status or no turn start and its screen stopped changing, so judge from output), "closed" (its card was closed) or "timeout" after timeoutSeconds (default ${DEFAULT_AGENT_WAIT_SECONDS}, at most ${MAX_AGENT_WAIT_SECONDS}; unless this session is Claude Code, a call returns after at most ${CLIENT_SAFE_AGENT_WAIT_SECONDS} seconds, before its MCP client would end the call), with status, exitCode, waitedMs, the end of its screen as masked plain text as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents); when the subagent's process exited (for example at once, on a model its CLI does not know), exitLines holds the last lines of its screen as plain text, which say why. A timeout means it is still running: read output as its progress and call wait_for_agent again. Then read get_agent_result.`, + `Wait until one of this session's subagents stops working, instead of polling observe_agent or get_agent_result; nothing is sent to it while it waits. Returns reason "idle" (the turn that answers your latest prompt ended and it waits for input; an idle before that turn started does not count), "needs_approval" (its card shows a prompt only the person may answer, such as a shell command it wants to run, shown in output; never answer it yourself: tell the person what it asks, then call wait_for_agent again, which waits for their answer instead of returning the same prompt again), "done" or "failed" (its process exited), "quiet" (it reports no status or no turn start and its screen stopped changing, so judge from output), "closed" (its card was closed) or "timeout" after timeoutSeconds (default ${DEFAULT_AGENT_WAIT_SECONDS}, at most ${MAX_AGENT_WAIT_SECONDS}; unless this session is Claude Code, a call returns after at most ${CLIENT_SAFE_AGENT_WAIT_SECONDS} seconds, before its MCP client would end the call), with status, exitCode, waitedMs, the end of its screen as masked plain text as output, and answer (the final reply of the turn that ended, for Codex and OpenCode subagents); when the subagent's process exited (for example at once, on a model its CLI does not know), exitLines holds the last lines of its screen as plain text, which say why. A timeout means it is still running: read output as its progress and call wait_for_agent again. Then read get_agent_result.`, { sessionId, timeoutSeconds: integer({ minimum: 1, maximum: MAX_AGENT_WAIT_SECONDS }) }, ["sessionId"] ), diff --git a/src/main/services/AgentControlService.ts b/src/main/services/AgentControlService.ts index 0b498cd11..0a95d0c1a 100644 --- a/src/main/services/AgentControlService.ts +++ b/src/main/services/AgentControlService.ts @@ -144,6 +144,12 @@ export class PromptNotDeliveredError extends Error { export class AgentControlService { private readonly terminals: TerminalManager; private readonly options: AgentControlOptions; + /** + * The approval request (TerminalManager.approvalRequest) wait_for_agent last returned needs_approval for, per + * subagent. While the card still shows that same request, the next wait waits for the person's answer instead of + * returning it again; a new request, even one with no status change in between, is returned at once. + */ + private readonly reportedApprovals = new Map(); constructor(terminals: TerminalManager, options: AgentControlOptions = {}) { this.terminals = terminals; @@ -225,6 +231,9 @@ export class AgentControlService { if (!capabilities.send) throw new Error(`${session.provider} cannot receive prompts.`); if (typeof text !== "string" || text.length === 0) throw new Error("Prompt text is required."); if (session.exitCode !== null) throw new Error("Agent session has already exited."); + // The card shows a prompt only the person may answer (OpenCode's own shell prompt, for example): text typed into + // it now, or the Enter after it, would answer that prompt on the person's behalf. + if (session.status === "needs_approval") throw new DelegationRefusal(APPROVAL_REFUSAL); return this.deliver(sessionId, text, submit, "text", signal); } @@ -367,6 +376,8 @@ export class AgentControlService { const started = Date.now(); const answer = async (session: SessionMetadata | null, reason: AgentWaitReason): Promise => { const waitedMs = Date.now() - started; + if (reason === "needs_approval") this.reportedApprovals.set(sessionId, this.approvalRequest(sessionId)); + else if (session?.status !== "needs_approval") this.reportedApprovals.delete(sessionId); if (!session) return { sessionId, reason, exitCode: null, waitedMs, output: "" }; let observation: AgentObservation | null = null; try { observation = await this.observe(sessionId); } catch { observation = null; } @@ -385,7 +396,10 @@ export class AgentControlService { if (current !== offset) { offset = current; changedAt = now; } const quietFor = now - changedAt; if (session.exitCode !== null) return answer(session, session.exitCode === 0 ? "done" : "failed"); - if (session.status === "needs_approval") return answer(session, "needs_approval"); + // A request a wait already returned (the card shows no newer one) is the person's to answer: wait for it. + const reported = this.reportedApprovals.has(sessionId) && this.reportedApprovals.get(sessionId) === this.approvalRequest(sessionId); + if (session.status === "needs_approval" && !reported) return answer(session, "needs_approval"); + if (session.status !== "needs_approval") this.reportedApprovals.delete(sessionId); // After a prompt, an idle that no turn followed (the CLI's startup idle, or one reported before the turn began) // is not the answer: only an idle after a turn that started since that prompt is. A CLI that never reports its // turns still ends as "quiet" once its screen stops changing. @@ -469,6 +483,12 @@ export class AgentControlService { return tail(typeof this.terminals.redactSecrets === "function" ? this.terminals.redactSecrets(text) : text, maxChars); } + /** The card's current approval request (TerminalManager.approvalRequest); undefined when the manager has none. */ + private approvalRequest(sessionId: string): number | undefined { + try { return typeof this.terminals.approvalRequest === "function" ? this.terminals.approvalRequest(sessionId) ?? undefined : undefined; } + catch { return undefined; } + } + private turnProgress(sessionId: string): { promptSent: boolean; turnStartedSincePrompt: boolean } | null { try { return typeof this.terminals.turnProgress === "function" ? this.terminals.turnProgress(sessionId) : null; } catch { return null; } } @@ -499,6 +519,11 @@ export class AgentControlService { } } +/** send_to_agent while the subagent's card waits for the person (needs_approval). */ +export const APPROVAL_REFUSAL = "This subagent is waiting for the person to answer a prompt in its card (needs_approval); " + + "only the person may answer it, so nothing was sent. Tell the person what it asks (wait_for_agent's output shows it), " + + "then call wait_for_agent again: it waits for their answer."; + /** A delegation rule refused the request; the text says why, for the orchestrator to adapt instead of retrying. */ export class DelegationRefusal extends LaunchRefusal { constructor(message: string) { diff --git a/src/main/services/TerminalManager.ts b/src/main/services/TerminalManager.ts index 03d2417e8..9c0d28cfd 100644 --- a/src/main/services/TerminalManager.ts +++ b/src/main/services/TerminalManager.ts @@ -188,6 +188,11 @@ interface ManagedSession { hookSignals?: number; /** Set after the person answered a hooked Claude prompt; see settleAnsweredPrompt. */ answeredPromptTimer?: ReturnType; + /** + * Counts the approval requests the card has shown (see approvalRequest). Never reset, a relaunch included, so a + * reader comparing it with an earlier value never mistakes a new request for one it already saw. + */ + approvalRequests?: number; } type EnvironmentService = Pick mark }; } + /** + * Identifies the approval request the card shows now: it advances each time the card turns needs_approval, and on + * each further request hook while it stays needs_approval (a second PermissionRequest right after the person answered + * the first moves neither the status nor the revision). A permission_prompt Notification while the card already + * waits is the same prompt again and does not advance it. null when the session does not exist. + */ + approvalRequest(id: string): number | null { + const session = this.sessions.get(id); + return session ? session.approvalRequests ?? 0 : null; + } + /** The session's output offset without copying its scrollback; null when it does not exist. */ outputOffset(id: string): number | null { return this.sessions.get(id)?.outputOffset ?? null; @@ -1373,6 +1389,10 @@ export class TerminalManager { } const nextStatus = signal.state; + if (nextStatus === "needs_approval" && (session.metadata.status !== "needs_approval" + || (source === "hook" && signal.event !== "Notification"))) { + session.approvalRequests = (session.approvalRequests ?? 0) + 1; + } const submittedTurn = source === "hook" && signal.event === "UserPromptSubmit" && session.promptDelivery?.stage === "submitted" && session.promptDelivery.acceptance === "unconfirmed"; if (nextStatus === "working") { diff --git a/src/main/services/agent-control/AgentControlGateway.ts b/src/main/services/agent-control/AgentControlGateway.ts index d5dc4484d..8c3d606fb 100644 --- a/src/main/services/agent-control/AgentControlGateway.ts +++ b/src/main/services/agent-control/AgentControlGateway.ts @@ -620,7 +620,21 @@ export class AgentControlGateway { : capabilities.menus && codexTerminalComposerReady(owned.terminal, this.options.terminals.codexUnstyledComposerAllowed?.(id)); if (request.method === "screen") return { sessionId: id, text: screen, revision: hash(screen), outputOffset: owned.outputOffset, interaction: capabilities.menus ? codexChoices(screen) : null, composerReady }; - if ((request.method === "choose" || request.method === "dismiss") && !capabilities.menus) { + // A prompt only the person may answer: the card waits for them (needs_approval, from the CLI's own permission + // hook), or Codex shows its approval prompt (before that hook's report arrived; for text, only while no composer is + // ready, so earlier output on screen does not refuse a task). An orchestrator's connection never answers it, with a + // choice, Escape or text. The person's own connection and the card itself still can. + const menuAction = request.method === "choose" || request.method === "dismiss"; + const approvalOnScreen = capabilities.menus && (menuAction || !composerReady) && codexApprovalPrompt(screen); + if (agent && (menuAction || request.method === "send") && (fresh.status === "needs_approval" || approvalOnScreen)) { + throw new ControlError("NEEDS_PERSON", PERSON_ANSWERS_REFUSAL); + } + // Fail closed: an orchestrator's connection resolves only the Codex menus known not to be approvals. A menu it does + // not recognise (an approval worded differently, a newer Codex, folder trust) is the person's. + if (agent && menuAction && capabilities.menus && !codexOrchestratorMenu(screen)) { + throw new ControlError("NEEDS_PERSON", UNKNOWN_MENU_REFUSAL); + } + if (menuAction && !capabilities.menus) { throw new ControlError("NOT_SUPPORTED", `Menus are parsed for Codex only; inspect screen and ask the person to resolve the ${fresh.provider} prompt in its terminal card. Do not switch to desktop automation.`); } // Its launch plugins are still preparing it: nothing can be written yet, and nothing is queued. @@ -800,6 +814,38 @@ export class AgentControlGateway { } } +/** What an orchestrator's connection gets for choose, dismiss or send while its worker waits for the person. */ +export const PERSON_ANSWERS_REFUSAL = "This worker is waiting for the person to answer an approval or permission prompt in its card " + + "(needs_approval); only the person may answer it, so nothing was written. Do not retry: tell the person what it asks " + + "(screen shows it), then check status again. Once they have answered it is no longer needs_approval."; + +/** What an orchestrator's connection gets for choose or dismiss on a Codex menu it is not known to own. */ +export const UNKNOWN_MENU_REFUSAL = "This worker shows a menu that is not one an orchestrator may resolve (hooks review, a model " + + "or rate-limit notice, an update notice); it may be an approval or a trust decision, so only the person may answer it " + + "and nothing was written. Do not retry: tell the person what it shows (screen shows it), then check status again."; + +/** + * The Codex menus an orchestrator's own connection may resolve: startup and notice menus that answer no request of the + * agent's. Everything else on a Codex screen is the person's, whether or not codexApprovalPrompt recognises it. + */ +export function codexOrchestratorMenu(screen: string): boolean { + if (codexApprovalPrompt(screen)) return false; + return /^\s*Hooks need review\b/m.test(screen) + || /^\s*\d+ hooks? reviewed\b/m.test(screen) + || /^\s*Approaching rate limits\b/m.test(screen) + || /^\s*Update available\b/m.test(screen); +} + +/** + * Codex's own approval prompts (running a command, applying edits, granting permissions or network access, an MCP + * server's request): the person's to answer, whatever the card's status says yet. Its other menus (hooks review, + * model and update notices) are not approvals. + */ +export function codexApprovalPrompt(screen: string): boolean { + return /Would you like to (?:run the following command|make the following edits|grant these permissions)|\bneeds your approval\b|Do you want to approve\b|Update Model Permissions\b/i.test(screen) + || /^\s*(?:›\s*)?\d+\.\s+(?:Yes, proceed\b|Yes, and don['’]t ask again\b|No, and tell Codex what to do differently\b)/m.test(screen); +} + function codexChoices(screen: string): { revision: string; selected: number; options: Array<{ number: number; label: string }> } | null { const matches = screen.split("\n").map((line) => line.match(/^\s*(›\s*)?(\d+)\.\s+(.+)$/)).filter((m) => m !== null); if (matches.length < 2 || matches.length > 12 || matches.filter((m) => m[1]).length !== 1) return null; diff --git a/src/main/services/agent-control/controlCapabilities.ts b/src/main/services/agent-control/controlCapabilities.ts index e1b872f5a..2d4d37dc5 100644 --- a/src/main/services/agent-control/controlCapabilities.ts +++ b/src/main/services/agent-control/controlCapabilities.ts @@ -17,7 +17,10 @@ export const CONTROL_PROVIDERS: readonly AgentProviderId[] = AGENT_PROVIDERS; export interface ControlCapabilities { /** The worker reports a captured final answer through `result`. */ result: boolean; - /** `screen` parses startup/approval menus that `choose`/`dismiss` can act on. */ + /** + * `screen` parses numbered menus that `choose`/`dismiss` can act on. An approval or permission prompt is the person's: + * an orchestrator's own connection is refused it (NEEDS_PERSON). + */ menus: boolean; } diff --git a/src/main/services/openCodeConfig.ts b/src/main/services/openCodeConfig.ts index d319cb55e..ce3b85d6c 100644 --- a/src/main/services/openCodeConfig.ts +++ b/src/main/services/openCodeConfig.ts @@ -102,7 +102,8 @@ export function openCodeYoloEnvironment( * Auto's rules: read, glob, grep, list allowed, except `.env` files (they ask, like OpenCode's default); edit (edit, * write, apply_patch) allowed; bash allowed only when `shellGuarded` (CanvasTTY's base protection is on and its guard * runs in this OpenCode), otherwise it asks. external_directory is not touched: a path outside the project still asks. - * `thirdPartyModel` (a launch contributor put OpenCode on another model) keeps bash asking, like accept-edits. + * `thirdPartyModel` (a launch contributor put OpenCode on another model) keeps bash asking, like accept-edits, in a + * subagent's card too: that ask reaches the person through needs_approval, and the orchestrator cannot answer it. */ export function openCodeAutoEnvironment( environment: Readonly>, diff --git a/tests/opencode-subagent-ask.test.mjs b/tests/opencode-subagent-ask.test.mjs new file mode 100644 index 000000000..21b9b20e5 --- /dev/null +++ b/tests/opencode-subagent-ask.test.mjs @@ -0,0 +1,192 @@ +/** + * An OpenCode subagent on a launch contributor's model keeps `bash` on "ask" (the rule of 566cb4f7: a third-party + * model's own judgement is not a safety boundary). Its ask must reach someone who may answer it: + * - a decision service's deny fails the call before OpenCode asks; an allow answers OpenCode's prompt once; + * - with no verdict, OpenCode's own prompt stays and the card turns needs_approval: Needs attention lists it, the + * orchestrator's wait_for_agent returns it with the prompt, the orchestrator cannot answer it, and the person's + * answer resumes the subagent and the orchestrator's next wait. + * The real OpenCode plugin module, runtime gateway, decision hooks, TerminalManager and orchestration tools run here; + * no OpenCode, no model. HOME is whatever the test runner's fake HOME is. + */ +import assert from "node:assert/strict"; +import { mkdtemp, realpath, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { AGENT_RUNTIME_ENV, OPENCODE_DECISIONS_ENV } from "../src/agent-runtime/runtime-protocol.mjs"; +import { AgentControlService, APPROVAL_REFUSAL } from "../src/main/services/AgentControlService.ts"; +import { DecisionHooks } from "../src/main/services/DecisionHooks.ts"; +import { LaunchPipeline } from "../src/main/services/LaunchPipeline.ts"; +import { TerminalManager } from "../src/main/services/TerminalManager.ts"; +import { RuntimeGateway } from "../src/main/services/agent-runtime/RuntimeGateway.ts"; +import { ScopedOrchestrationHandler } from "../src/main/services/agent-browser/OrchestrationTools.ts"; +import { attentionSessions } from "../src/renderer/src/features/home/attentionQueue.ts"; +import { availableRegistry, fakeSpawner } from "./helpers/terminal.mjs"; + +const POSIX = { skip: process.platform === "win32" ? "Unix sockets." : false }; +const until = async (check, what, ms = 4_000) => { + const deadline = Date.now() + ms; + while (!check()) { + if (Date.now() > deadline) throw new Error(`timed out waiting for ${what}`); + await new Promise((resolve) => setTimeout(resolve, 5)); + } +}; + +function runtime(decisions) { + return { + prepareLaunch: () => ({ args: [], environment: decisions ? { CANVASTTY_RUNTIME_DECISIONS: "1" } : {}, decisions, cleanup() {} }), + currentStatus: () => null + }; +} + +/** A launch contributor that puts OpenCode on its own model, as the Assistant's Auto router does. */ +async function modelContributor(t) { + const runsRoot = await mkdtemp(join(tmpdir(), "ctty-oc-ask-runs-")); + t.after(() => rm(runsRoot, { recursive: true, force: true })); + return new LaunchPipeline({ + contributors: () => [{ pluginId: "p.router", pluginName: "Router", serviceId: "svc", secrets: false, + launch: { fields: [{ key: "on", label: "On", kind: "boolean", default: true }], delegable: true } }], + call: async () => ({ thirdPartyModel: true }), + secret: async () => null, + runsRoot, + timeoutMs: 500 + }); +} + +async function cards(t, { thirdPartyModel }) { + const root = await realpath(await mkdtemp(join(tmpdir(), "ctty-oc-ask-"))); + t.after(() => rm(root, { recursive: true, force: true })); + const calls = []; + const writes = []; + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, runtime(true), true, + fakeSpawner(calls, { onWrite: (data, options) => writes.push({ data, options }) })); + terminals.configureBaseProtection(() => true); + t.after(() => terminals.disposeAll()); + if (thirdPartyModel) terminals.configureLaunchPipeline(await modelContributor(t)); + const options = thirdPartyModel ? { launchOptions: { "p.router": { on: true } } } : {}; + const launch = async (request) => { + const before = calls.length; + const created = terminals.create({ provider: "opencode", cwd: root, profile: "auto", position: { x: 0, y: 0 }, ...options, ...request }); + await until(() => calls.length > before, "the launch"); + const inline = calls.at(-1).options.env.OPENCODE_CONFIG_CONTENT; + return { id: created.id, env: calls.at(-1).options.env, bash: JSON.parse(inline).agent.build.permission.bash, + metadata: () => terminals.getMetadata(created.id) }; + }; + const person = await launch({}); + const orchestrator = await launch({ role: "orchestrator" }); + const subagent = await launch({ role: "subagent", parentSessionId: orchestrator.id }); + return { root, terminals, writes, person, orchestrator, subagent }; +} + +test("a subagent on a launch contributor's model keeps bash asking; person cards and an own-model OpenCode are unchanged", async (t) => { + const routed = await cards(t, { thirdPartyModel: true }); + for (const card of [routed.person, routed.orchestrator, routed.subagent]) { + assert.equal(card.bash, "ask", "a third-party model's shell commands ask, in every card"); + assert.equal(card.metadata().autoDowngraded, true, "and the card says auto runs as edits only"); + } + assert.equal(routed.subagent.metadata().role, "subagent"); + const own = await cards(t, { thirdPartyModel: false }); + for (const card of [own.person, own.orchestrator, own.subagent]) { + assert.equal(card.bash, "allow", "OpenCode on its own model under base protection: the guard is the gate, as before"); + assert.equal(card.metadata().autoDowngraded, undefined); + } +}); + +test("the subagent's shell ask: decisions answer OpenCode's prompt, otherwise it reaches the person, not the orchestrator", POSIX, async (t) => { + const { terminals, writes, orchestrator, subagent, root } = await cards(t, { thirdPartyModel: true }); + // What the decision service answers for each command; null is no opinion. + const verdicts = { "npm test": { verdict: "allow", reason: "tests" }, "rm -rf build": { verdict: "deny", reason: "not that" }, ls: null }; + const decide = new DecisionHooks({ + baseProtection: () => true, + services: () => [{ pluginId: "p.review", pluginName: "Review", serviceId: "decide", mayAllow: true }], + call: async (_plugin, _service, _method, params) => verdicts[params.tool.command] ?? null, + session: (id) => id === subagent.id ? { provider: "opencode", role: "subagent", cwd: root, configDirs: [], profile: "auto" } : null + }); + const runtimeDirectory = await mkdtemp(join(tmpdir(), "ctty-oc-ask-rt-")); + const gateway = new RuntimeGateway({ + runtimeDirectory, + onPermissionRequest: (id, request, signal) => decide.decide(id, request, signal), + // As src/main/index.ts applies it. + onSignal: (id, signal) => terminals.applyProviderSignal(id, { kind: "lifecycle", state: signal.state, event: signal.event, + ...(signal.turnId ? { requestId: signal.turnId } : {}), ...(signal.threadId ? { threadId: signal.threadId } : {}) }) + }); + await gateway.start(); + t.after(async () => { await gateway.close(); await rm(runtimeDirectory, { recursive: true, force: true }); }); + const capability = gateway.registerSession(subagent.id, "opencode", false, undefined, true); + + // The subagent's OpenCode loads CanvasTTY's plugin with the environment its launch gives it. + assert.equal(subagent.env[OPENCODE_DECISIONS_ENV], "1", "the launch installs the guard"); + Object.assign(process.env, { + [OPENCODE_DECISIONS_ENV]: "1", + [AGENT_RUNTIME_ENV.address]: capability.address, + [AGENT_RUNTIME_ENV.terminalSessionId]: subagent.id, + [AGENT_RUNTIME_ENV.provider]: "opencode", + [AGENT_RUNTIME_ENV.capabilityToken]: capability.capabilityToken + }); + const { CanvasTTYLifecycle } = await import("../src/agent-runtime/opencode-plugin.mjs"); + const replies = []; + const plugin = await CanvasTTYLifecycle({ client: { permission: { reply: async (body) => { replies.push(body); return { response: { ok: true } }; } } } }); + const root_ = "ses_root01"; + const event = (type, properties) => plugin.event({ event: { type, properties } }); + await event("session.created", { info: { id: root_ } }); + await event("session.status", { sessionID: root_, status: { type: "busy" } }); + await until(() => subagent.metadata().status === "working", "the subagent working"); + const bash = async (callID, command) => { + await plugin["tool.execute.before"]({ tool: "bash", sessionID: root_, callID }, { args: { command } }); + // The guard let the call go on: OpenCode now checks bash, which asks. + await event("permission.asked", { id: `per_${callID}`, sessionID: root_, permission: "bash", patterns: [command], tool: { messageID: "msg_1", callID } }); + }; + + // A decision service's allow answers OpenCode's prompt once; nobody else is asked. + await bash("c1", "npm test"); + assert.deepEqual(replies, [{ requestID: "per_c1", reply: "once" }]); + assert.equal(subagent.metadata().status, "working", "no needs_approval for an answered prompt"); + // Its deny fails the call with the reason before OpenCode asks anything. + await assert.rejects(plugin["tool.execute.before"]({ tool: "bash", sessionID: root_, callID: "c2" }, { args: { command: "rm -rf build" } }), + /Review.*not that/u); + assert.equal(replies.length, 1); + + // No verdict: OpenCode's own prompt stays, for the person. CanvasTTY never answers it. + await bash("c3", "ls"); + assert.equal(replies.length, 1, "no verdict is never turned into an allow"); + await until(() => subagent.metadata().status === "needs_approval", "needs_approval"); + assert.deepEqual(attentionSessions(terminals.list()).map((session) => session.id), [subagent.id], "Needs attention lists the subagent"); + + // The orchestrator learns at once, with the prompt; it cannot answer it. + const control = new AgentControlService(terminals, { waitTiming: { checkMs: 5, settleMs: 20, quietMs: 60_000 } }); + const handler = new ScopedOrchestrationHandler(control, null, { cli: () => "available", limits: () => ({ maxDepth: 2, maxSubagents: 8 }) }); + const call = (tool, args) => handler.execute(orchestrator.id, { id: "r", tool, arguments: args }); + const first = await call("wait_for_agent", { sessionId: subagent.id, timeoutSeconds: 5 }); + assert.equal(first.reason, "needs_approval"); + assert.ok(first.waitedMs < 1_000); + const typed = writes.length; + for (const prompt of ["y", "allow"]) { + await assert.rejects(call("send_to_agent", { sessionId: subagent.id, prompt }), (error) => { + assert.equal(error.bridgeError?.code ?? error.code, "INVALID_REQUEST"); + assert.equal(error.message, APPROVAL_REFUSAL); + return true; + }); + } + assert.equal(writes.length, typed, "nothing reached the subagent's terminal"); + + // The next wait waits for the person instead of returning the same prompt again. + const again = call("wait_for_agent", { sessionId: subagent.id, timeoutSeconds: 5 }); + let settled = false; + void again.then(() => { settled = true; }, () => { settled = true; }); + await new Promise((resolve) => setTimeout(resolve, 150)); + assert.equal(settled, false, "still waiting while the prompt waits for the person"); + // The person answers OpenCode's prompt in the card; OpenCode replies, runs `ls` and ends the turn. + await event("permission.replied", { sessionID: root_, requestID: "per_c3", reply: "once" }); + await until(() => subagent.metadata().status === "working", "the subagent working again"); + assert.deepEqual(attentionSessions(terminals.list()), [], "the answered card leaves Needs attention"); + await event("session.status", { sessionID: root_, status: { type: "idle" } }); + const done = await again; + assert.equal(done.reason, "idle"); + assert.equal(replies.length, 1, "the person answered, not CanvasTTY"); + + // A new prompt after that is reported at once again. + await event("session.status", { sessionID: root_, status: { type: "busy" } }); + await bash("c4", "ls"); + await until(() => subagent.metadata().status === "needs_approval", "the second prompt"); + assert.equal((await call("wait_for_agent", { sessionId: subagent.id, timeoutSeconds: 5 })).reason, "needs_approval"); +}); diff --git a/tests/orchestrator-approval-answers.test.mjs b/tests/orchestrator-approval-answers.test.mjs new file mode 100644 index 000000000..adc2d2080 --- /dev/null +++ b/tests/orchestrator-approval-answers.test.mjs @@ -0,0 +1,307 @@ +import assert from "node:assert/strict"; +import { randomUUID } from "node:crypto"; +import { mkdir, mkdtemp, realpath, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { setTimeout as delay } from "node:timers/promises"; +import test from "node:test"; +import { controlRequest } from "../scripts/canvastty-control.mjs"; +import { AgentControlService, APPROVAL_REFUSAL, DelegationRefusal } from "../src/main/services/AgentControlService.ts"; +import { AgentControlGateway, PERSON_ANSWERS_REFUSAL, UNKNOWN_MENU_REFUSAL, codexApprovalPrompt, codexOrchestratorMenu } from "../src/main/services/agent-control/AgentControlGateway.ts"; +import { TerminalManager } from "../src/main/services/TerminalManager.ts"; +import { OPENCODE_STARTUP_READY, availableRegistry, echoPromptInput, fakeSpawner } from "./helpers/terminal.mjs"; + +// An orchestrator never answers a subagent's approval or permission prompt: not with send_to_agent (MCP), and not with +// choose, dismiss or send on its own control connection. Those prompts are the person's (or a decision service's the +// person allowed, which answers before the CLI asks). Non-approval menus stay the orchestrator's, the person's own +// connection and the card's own input are unchanged. + +const localSocket = { skip: process.platform === "win32" ? "Unix socket tests" : false }; +const at = { x: 0, y: 0 }; +const COMPOSER = "\x1b[2J\x1b[H>_ OpenAI Codex\r\nmodel: test\r\n\r\n› \x1b[2mAsk Codex to do anything\x1b[22m"; +const APPROVAL = "\x1b[2J\x1b[HWould you like to run the following command?\r\n\r\n $ rm -rf build\r\n\r\n" + + "› 1. Yes, proceed (y)\r\n 2. Yes, and don't ask again for this command (p)\r\n" + + " 3. No, and tell Codex what to do differently (esc)\r\n\r\nPress enter to confirm or esc to cancel"; +const EDITS = "\x1b[2J\x1b[HWould you like to make the following edits?\r\n\r\n src/a.ts (+1 -0)\r\n\r\n" + + "› 1. Yes, proceed (y)\r\n 2. Yes, and don't ask again for these files (a)\r\n" + + " 3. No, and tell Codex what to do differently (esc)\r\n\r\nPress enter to confirm or esc to cancel"; +const HOOKS = "\x1b[2J\x1b[HHooks need review\r\n› 1. Review hooks\r\n 2. Trust all and continue\r\n 3. Continue without hooks\r\n" + + "Press enter to confirm or esc to cancel"; +// An approval worded in a way codexApprovalPrompt does not know (a newer Codex, another kind of request). +const UNKNOWN_APPROVAL = "\x1b[2J\x1b[HAllow Codex to open the browser on example.com?\r\n\r\n" + + "› 1. Allow\r\n 2. Allow for this session\r\n 3. Deny\r\n\r\nPress enter to confirm or esc to cancel"; +const TRUST = "\x1b[2J\x1b[HDo you trust the contents of this directory?\r\n› 1. Yes, continue\r\n 2. No, quit\r\nPress enter to continue"; +const PERMISSIONS = "\x1b[2J\x1b[HUpdate Model Permissions\r\n› 1. Allow full access\r\n 2. Keep current permissions\r\nPress enter to confirm or esc to cancel"; +const UPDATE = "\x1b[2J\x1b[HUpdate available! 0.200.0 -> 0.201.0\r\n› 1. Update now\r\n 2. Skip\r\n 3. Skip until next version\r\nPress enter to continue"; +// The empty composers Claude Code and Kimi 2.x show, for a follow-up task's paste-then-submit delivery. +const CLAUDE_COMPOSER = "\x1b[2J\x1b[H❯ "; +const KIMI_COMPOSER = "\x1b[2J\x1b[HKimi Code 2.4.0\r\n╭──────────────────────╮\r\n│ > │\r\n╰──────────────────────╯\r\n\x1b[3;6H"; +const MODEL = "\x1b[2J\x1b[HApproaching rate limits\r\nSwitch to a smaller model for lower credit usage?\r\n" + + "› 1. Switch model\r\n 2. Keep current model\r\n 3. Keep current model (never show again)\r\nPress enter to confirm or esc to go back"; + +async function fixture(t) { + const root = await realpath(await mkdtemp(join(tmpdir(), "ctty-no-approve-"))); + const userData = await realpath(await mkdtemp(join("/tmp", "ctty-no-approve-grant-"))); + t.after(() => Promise.all([rm(root, { recursive: true, force: true }), rm(userData, { recursive: true, force: true })])); + const project = join(root, "project"); + const inner = join(project, "src"); + await mkdir(inner, { recursive: true }); + const calls = []; + const writes = new Map(); + let gateway; + const terminals = new TerminalManager((channel, payload) => gateway?.observe(channel, payload), availableRegistry(), undefined, undefined, true, + fakeSpawner(calls, { onWrite: (data, options) => { + const call = calls.find((entry) => entry.options === options); + if (call) writes.set(call, [...(writes.get(call) ?? []), data]); + } })); + const control = new AgentControlService(terminals, { waitTiming: { checkMs: 10, settleMs: 20, quietMs: 200 } }); + gateway = new AgentControlGateway({ userDataPath: userData, terminals, lifecycleEnabled: () => true, + spawnSubagent: (request) => control.spawn(request) }); + const appConnection = await gateway.start(); + terminals.setControlConnection({ connectionPath: appConnection, cliPath: "/cli.mjs", grant: (id) => gateway.grantSession(id) }); + t.after(async () => { await gateway.close(); await terminals.shutdown(); }); + const orchestrator = terminals.create({ provider: "codex", profile: "auto", cwd: project, position: at, role: "orchestrator" }); + const connectionPath = calls.at(-1).options.env.CANVASTTY_CONTROL_CONNECTION; + assert.ok(connectionPath && connectionPath !== appConnection, "the orchestrator has its own connection"); + const agentClient = join(dirname(connectionPath), "controller.json"); + const agent = (method, params = {}, requestId = randomUUID()) => + controlRequest({ connectionPath, clientPath: agentClient, method, params, requestId, timeoutMs: 10_000 }); + const person = (method, params = {}, requestId = randomUUID()) => + controlRequest({ connectionPath: appConnection, clientPath: join(userData, "person-client.json"), method, params, requestId, timeoutMs: 10_000 }); + // The card a create just launched (each launch spawns one PTY). + const callOf = (id) => { + const call = calls.at(-1); + assert.equal(terminals.getMetadata(id)?.exitCode, null); + return call; + }; + const written = (call) => writes.get(call) ?? []; + return { root, project, inner, terminals, control, gateway, orchestrator, calls, agent, person, callOf, written }; +} + +/** Prints a screen into the card and waits until its controller's view shows it. */ +async function show(request, id, call, data, expected) { + call.process.emitData(data); + for (let i = 0; i < 60; i++) { + const screen = await request("screen", { sessionId: id }); + if (screen.text.includes(expected)) return screen; + await delay(5); + } + assert.fail(`the screen did not show ${expected}`); +} + +const needsPerson = (error) => error.code === "NEEDS_PERSON" && error.message === PERSON_ANSWERS_REFUSAL; +const unknownMenu = (error) => error.code === "NEEDS_PERSON" && error.message === UNKNOWN_MENU_REFUSAL; + +test("Codex's approval prompts are told apart from its other menus", () => { + for (const screen of [APPROVAL, EDITS, "Would you like to grant these permissions?\n› 1. Yes\n 2. No", + "Do you want to approve network access to \"example.com\"?\n› 1. Yes, just this once\n 2. No", + "docs needs your approval.\n› 1. Yes, provide the requested info\n 2. No, but continue without it", + "› 1. Yes, proceed (y)\n 2. No (esc)"]) { + assert.equal(codexApprovalPrompt(screen), true, screen); + } + for (const screen of [HOOKS, MODEL, COMPOSER, "Do you trust the contents of this directory?\n› 1. Yes, continue\n 2. No, quit", + "Update available!\n› 1. Update now\n 2. Skip\n 3. Skip until next version"]) { + assert.equal(codexApprovalPrompt(screen), false, screen); + } + // What an orchestrator may resolve is a short list of known menus; anything else (recognised or not) is the person's. + // The gateway passes the rendered screen, without control sequences. + const plain = (screen) => screen.replace(/\x1b\[[0-9;]*[A-Za-z]/gu, "").replace(/\r/gu, ""); + for (const screen of [HOOKS, MODEL, UPDATE, "Hooks\n6 hooks reviewed\nPress esc to close"]) assert.equal(codexOrchestratorMenu(plain(screen)), true, screen); + for (const screen of [APPROVAL, EDITS, UNKNOWN_APPROVAL, TRUST, PERMISSIONS, COMPOSER, + "Hooks need review\n› 1. Yes, proceed (y)\n 2. No (esc)"]) { + assert.equal(codexOrchestratorMenu(plain(screen)), false, screen); + } +}); + +test("an orchestrator's control connection cannot choose, dismiss or type into a subagent's approval prompt; the person still answers it", localSocket, async (t) => { + const f = await fixture(t); + const created = await f.agent("create", { provider: "codex", cwd: f.inner }); + const id = created.session.id; + assert.equal(f.terminals.getMetadata(id).parentSessionId, f.orchestrator.id); + assert.equal(created.capabilities.menus, true); + const call = f.callOf(id); + echoPromptInput(call.process, "codex", COMPOSER); + + // A task the orchestrator legitimately sends, at an empty composer: its paste, then its submit key. + f.terminals.applyProviderSignal(id, { kind: "lifecycle", state: "idle" }); + await show(f.agent, id, call, COMPOSER, "Ask Codex"); + await f.agent("send", { sessionId: id, text: "clean the build" }); + assert.deepEqual(f.written(call), ["\x1b[200~clean the build\x1b[201~", "\r"]); + f.terminals.applyProviderSignal(id, { kind: "lifecycle", state: "working" }); + + // Codex shows its approval prompt before its PermissionRequest hook's report arrived: the screen alone refuses. + const early = await show(f.agent, id, call, APPROVAL, "Yes, proceed"); + assert.equal(early.interaction.options.length, 3, "the menu is still shown to the orchestrator"); + await assert.rejects(f.agent("choose", { sessionId: id, choice: 1, revision: early.interaction.revision }), needsPerson); + await assert.rejects(f.agent("dismiss", { sessionId: id, revision: early.revision }), needsPerson); + await assert.rejects(f.agent("send", { sessionId: id, text: "y" }), needsPerson, "text (and its Enter) would answer it too"); + // The hook's report: the card is needs_approval. + f.terminals.applyProviderSignal(id, { kind: "lifecycle", state: "needs_approval" }); + const screen = await f.agent("screen", { sessionId: id }); + for (const choice of [1, 2, 3]) { + await assert.rejects(f.agent("choose", { sessionId: id, choice, revision: screen.interaction.revision }), needsPerson, `choice ${choice}`); + } + await assert.rejects(f.agent("dismiss", { sessionId: id, revision: screen.revision }), needsPerson, "Escape is an answer too"); + await assert.rejects(f.agent("send", { sessionId: id, text: "y" }), needsPerson); + // Not retryable: the same request id replays the refusal instead of writing. + const again = randomUUID(); + await assert.rejects(f.agent("choose", { sessionId: id, choice: 1, revision: screen.interaction.revision }, again), needsPerson); + await assert.rejects(f.agent("choose", { sessionId: id, choice: 1, revision: screen.interaction.revision }, again), needsPerson); + assert.equal(f.written(call).length, 2, "nothing reached the prompt"); + // Reading stays open, and stopping its own turn is not an answer: the asked command does not run. + assert.equal((await f.agent("status", { sessionId: id })).session.status, "needs_approval"); + await f.agent("interrupt", { sessionId: id }); + assert.deepEqual(f.written(call).slice(2), ["\x03"]); + + // The person answers in the card (its own input path), whatever the orchestrator was refused. + f.terminals.input(id, "y"); + assert.deepEqual(f.written(call).slice(3), ["y"]); + f.terminals.applyProviderSignal(id, { kind: "lifecycle", state: "working" }); + f.terminals.applyProviderSignal(id, { kind: "lifecycle", state: "idle", event: "Stop" }); + // Edits ask the same way. + const edits = await show(f.agent, id, call, EDITS, "make the following edits"); + await assert.rejects(f.agent("choose", { sessionId: id, choice: 1, revision: edits.interaction.revision }), needsPerson); + + // An approval CanvasTTY does not recognise by its text: before the hook's report the screen is not a menu the + // orchestrator may resolve, so it is refused anyway; after the report the status refuses it as well. + const unknown = await show(f.agent, id, call, UNKNOWN_APPROVAL, "open the browser"); + await assert.rejects(f.agent("choose", { sessionId: id, choice: 1, revision: unknown.interaction.revision }), unknownMenu); + await assert.rejects(f.agent("dismiss", { sessionId: id, revision: unknown.revision }), unknownMenu); + f.terminals.applyProviderSignal(id, { kind: "lifecycle", state: "needs_approval" }); + for (const choice of [1, 2, 3]) { + await assert.rejects(f.agent("choose", { sessionId: id, choice, revision: unknown.interaction.revision }), needsPerson, `choice ${choice}`); + } + await assert.rejects(f.agent("dismiss", { sessionId: id, revision: unknown.revision }), needsPerson); + await assert.rejects(f.agent("send", { sessionId: id, text: "1" }), needsPerson); + f.terminals.input(id, "3"); + f.terminals.applyProviderSignal(id, { kind: "lifecycle", state: "idle", event: "Stop" }); + // A permissions change and folder trust are the person's too. + for (const [screen, expected] of [[PERMISSIONS, "Update Model Permissions"], [TRUST, "trust the contents"]]) { + const menu = await show(f.agent, id, call, screen, expected); + await assert.rejects(f.agent("choose", { sessionId: id, choice: 1, revision: menu.interaction.revision }), + (error) => error.code === "NEEDS_PERSON", expected); + } + assert.deepEqual(f.written(call).slice(3), ["y", "3"], "only the person's answers reached the card"); +}); + +test("an orchestrator still resolves menus that are not approvals, and the person's own connection still chooses approvals", localSocket, async (t) => { + const f = await fixture(t); + const { session } = await f.agent("create", { provider: "codex", cwd: f.inner }); + const call = f.callOf(session.id); + echoPromptInput(call.process, "codex", COMPOSER); + f.terminals.applyProviderSignal(session.id, { kind: "lifecycle", state: "idle" }); + const hooks = await show(f.agent, session.id, call, HOOKS, "Hooks need review"); + await f.agent("choose", { sessionId: session.id, choice: 3, revision: hooks.interaction.revision }); + const model = await show(f.agent, session.id, call, MODEL, "Approaching rate limits"); + await f.agent("choose", { sessionId: session.id, choice: 2, revision: model.interaction.revision }); + const notice = await show(f.agent, session.id, call, "\x1b[2J\x1b[HHooks\r\n6 hooks reviewed\r\nPress esc to close", "Press esc"); + await f.agent("dismiss", { sessionId: session.id, revision: notice.revision }); + const update = await show(f.agent, session.id, call, UPDATE, "Update available"); + await f.agent("choose", { sessionId: session.id, choice: 2, revision: update.interaction.revision }); + assert.deepEqual(f.written(call), ["\x1b[B\x1b[B\r", "\x1b[B\r", "\x1b", "\x1b[B\r"]); + // A worker with no approval pending takes the orchestrator's task as before. + await show(f.agent, session.id, call, COMPOSER, "Ask Codex"); + await f.agent("send", { sessionId: session.id, text: "next task" }); + assert.deepEqual(f.written(call).slice(4), ["\x1b[200~next task\x1b[201~", "\r"]); + + // The person's own automation (the app-wide connection) is the person: its worker's approval prompt is its to choose. + const own = await f.person("create", { provider: "codex", profile: "normal", cwd: f.inner, title: "Person's worker" }); + const ownCall = f.callOf(own.session.id); + f.terminals.applyProviderSignal(own.session.id, { kind: "lifecycle", state: "needs_approval" }); + const approval = await show(f.person, own.session.id, ownCall, APPROVAL, "Yes, proceed"); + await f.person("choose", { sessionId: own.session.id, choice: 3, revision: approval.interaction.revision }); + assert.deepEqual(f.written(ownCall), ["\x1b[B\x1b[B\r"]); + // And the orchestrator cannot reach the person's worker at all. + await assert.rejects(f.agent("choose", { sessionId: own.session.id, choice: 1, revision: approval.interaction.revision }), + (error) => error.code === "SESSION_NOT_FOUND"); +}); + +test("send_to_agent is refused at every CLI's approval or permission prompt and allowed once the person answered", async (t) => { + const root = await realpath(await mkdtemp(join(tmpdir(), "ctty-no-approve-send-"))); + t.after(() => rm(root, { recursive: true, force: true })); + const calls = []; + const writes = new Map(); + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner(calls, { + onWrite: (data, options) => writes.set(options, [...(writes.get(options) ?? []), data]) + })); + t.after(() => terminals.shutdown()); + const control = new AgentControlService(terminals); + const orchestrator = terminals.create({ provider: "claude", profile: "normal", cwd: root, position: at, role: "orchestrator" }); + calls.forEach((entry) => { entry.claimed = true; }); + // Each maps its CLI's own approval signal to needs_approval: Claude Code, Codex, Qwen and Kimi PermissionRequest, + // Grok's permission_prompt notification, Hermes pre_approval_request, OpenCode permission.asked and question.asked. + for (const provider of ["claude", "codex", "grok", "kimi", "qwen", "hermes", "opencode"]) { + const child = terminals.create({ provider, profile: "normal", cwd: root, position: at, role: "subagent", parentSessionId: orchestrator.id }); + if (provider === "grok") terminals.resize(child.id, 80, 24); // Grok starts with the renderer-measured grid. + let call; + for (let i = 0; i < 100 && !call; i++) { + call = calls.find((entry) => entry.options.cwd === root && JSON.stringify([entry.command, entry.args]).includes(`/resolved/${provider}`) && !entry.claimed); + if (!call) await delay(5); + } + assert.ok(call, `${provider}: launched`); + call.claimed = true; + terminals.applyProviderSignal(child.id, { kind: "lifecycle", state: "needs_approval" }); + for (const prompt of ["y", "1", "allow", "yes, and don't ask again"]) { + assert.throws(() => control.send(child.id, prompt), (error) => error instanceof DelegationRefusal && error.message === APPROVAL_REFUSAL, `${provider}: ${prompt}`); + assert.throws(() => control.send(child.id, prompt, false), DelegationRefusal, `${provider}: ${prompt} without Enter`); + } + assert.deepEqual(writes.get(call.options) ?? [], [], `${provider}: nothing reached its prompt`); + // The person answers in the card; the subagent works and finishes its turn. + terminals.input(child.id, "1"); + terminals.applyProviderSignal(child.id, { kind: "lifecycle", state: "working" }); + terminals.applyProviderSignal(child.id, { kind: "lifecycle", state: "idle", event: "Stop" }); + // Codex, Claude and Kimi take a pasted task and a separate submit key once their composer shows it. + const composer = { codex: COMPOSER, claude: CLAUDE_COMPOSER, kimi: KIMI_COMPOSER }[provider]; + if (composer) { + echoPromptInput(call.process, provider, composer); + call.process.emitData(composer); + } + if (provider === "opencode") call.process.emitData(OPENCODE_STARTUP_READY); + await control.send(child.id, "next task"); + const sent = writes.get(call.options); + assert.equal(sent?.[0], "1", `${provider}: the person's answer`); + assert.deepEqual(sent.slice(1), composer ? ["\x1b[200~next task\x1b[201~", "\r"] : ["next task\r"], + `${provider}: the orchestrator's next task once the person answered`); + } +}); + +test("wait_for_agent reports each approval request once, a consecutive one with no status change in between too", async (t) => { + const root = await realpath(await mkdtemp(join(tmpdir(), "ctty-approval-identity-"))); + t.after(() => rm(root, { recursive: true, force: true })); + const calls = []; + const terminals = new TerminalManager(() => undefined, availableRegistry(), undefined, undefined, true, fakeSpawner(calls)); + t.after(() => terminals.shutdown()); + const control = new AgentControlService(terminals, { waitTiming: { checkMs: 5, settleMs: 20, quietMs: 60_000 } }); + const orchestrator = terminals.create({ provider: "claude", profile: "normal", cwd: root, position: at, role: "orchestrator" }); + const child = terminals.create({ provider: "claude", profile: "normal", cwd: root, position: at, role: "subagent", parentSessionId: orchestrator.id }); + const pending = async (promise, ms = 150) => { + let settled = false; + void promise.then(() => { settled = true; }, () => { settled = true; }); + await delay(ms); + return !settled; + }; + + terminals.applyProviderSignal(child.id, { kind: "lifecycle", state: "needs_approval", event: "PermissionRequest" }); + const first = await control.waitFor(child.id, { timeoutMs: 5_000 }); + assert.equal(first.reason, "needs_approval"); + // Claude Code echoes the same prompt as a permission_prompt Notification: still that prompt, not a new one. + terminals.applyProviderSignal(child.id, { kind: "lifecycle", state: "needs_approval", event: "Notification" }); + // Nor is a card change that is no approval request (its thread id arriving, say). + terminals.applyProviderSignal(child.id, { kind: "lifecycle", state: "needs_approval", event: "Notification", threadId: "11111111-1111-4111-8111-111111111111" }); + const same = control.waitFor(child.id, { timeoutMs: 5_000 }); + assert.equal(await pending(same), true, "the reported prompt waits for the person"); + + // The person answers in the card and Claude asks again at once: a second PermissionRequest with no status change. + const revision = terminals.getMetadata(child.id).revision; + terminals.input(child.id, "1"); + terminals.applyProviderSignal(child.id, { kind: "lifecycle", state: "needs_approval", event: "PermissionRequest" }); + assert.equal(terminals.getMetadata(child.id).revision, revision, "the card's revision did not move"); + const next = await same; + assert.equal(next.reason, "needs_approval", "the new request is reported"); + assert.ok(next.waitedMs < 2_000, `reported at once, not at the timeout (${next.waitedMs} ms)`); + // And reported once: the next wait waits for the person again. + assert.equal(await pending(control.waitFor(child.id, { timeoutMs: 5_000 })), true); + // A third one, from another CLI's request event, is new again. + terminals.applyProviderSignal(child.id, { kind: "lifecycle", state: "needs_approval", event: "pre_approval_request" }); + assert.equal((await control.waitFor(child.id, { timeoutMs: 5_000 })).reason, "needs_approval"); +});