diff --git a/docs/agent-orchestration.md b/docs/agent-orchestration.md index e664752b0..580ccd93a 100644 --- a/docs/agent-orchestration.md +++ b/docs/agent-orchestration.md @@ -152,9 +152,9 @@ 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. 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. +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, each recognised by its title right above its own options and by exactly those options, so a title the worker printed elsewhere does not count. In hooks review the orchestrator may only choose "Continue without hooks" or dismiss it: reviewing or trusting the hooks is the person's decision and is refused with `NEEDS_PERSON`. `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. +Codex may show **Hooks need review** on first launch or after the bundled lifecycle helpers change. The person reviews the listed commands and decides whether to trust them; an orchestrator may continue without them. 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. ## Retry and ownership diff --git a/scripts/canvastty-control.mjs b/scripts/canvastty-control.mjs index c61ea4ae3..43375d0db 100644 --- a/scripts/canvastty-control.mjs +++ b/scripts/canvastty-control.mjs @@ -161,7 +161,8 @@ create --cwd [--provider ] [--title ] [--yolo | --profile 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. + There, choose/dismiss act only on hooks review (Continue without hooks or + dismiss; trusting hooks is the person's) and model or update notices. list status screen diff --git a/src/main/services/agent-control/AgentControlGateway.ts b/src/main/services/agent-control/AgentControlGateway.ts index c4123e0a7..04749db95 100644 --- a/src/main/services/agent-control/AgentControlGateway.ts +++ b/src/main/services/agent-control/AgentControlGateway.ts @@ -632,8 +632,14 @@ export class AgentControlGateway { } // 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 (agent && menuAction && capabilities.menus) { + const menu = orchestratorMenu(screen); + if (!menu) throw new ControlError("NEEDS_PERSON", UNKNOWN_MENU_REFUSAL); + // Trusting or reviewing hooks is the person's decision; the orchestrator may only continue without them. + const label = request.method === "choose" ? codexChoices(screen)?.options.find((option) => option.number === params.choice)?.label : undefined; + if (menu.choices && label !== undefined && !menu.choices.includes(label.trim())) { + throw new ControlError("NEEDS_PERSON", HOOK_TRUST_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.`); @@ -827,16 +833,52 @@ export const UNKNOWN_MENU_REFUSAL = "This worker shows a menu that is not one an + "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."; +/** What an orchestrator's connection gets for a hooks-review option that trusts or reviews the hooks. */ +export const HOOK_TRUST_REFUSAL = "Trusting or reviewing this worker's hooks is the person's decision, so nothing was written. " + + "An orchestrator may only choose \"Continue without hooks\" or dismiss the menu; otherwise tell the person what it shows " + + "(screen shows it), then check status again."; + +/** + * The Codex menus an orchestrator's connection may resolve, each by its title and its exact options. `choices` limits + * which options it may choose; dismiss is allowed on each. + */ +const ORCHESTRATOR_MENUS: ReadonlyArray<{ title: RegExp; options: readonly string[]; choices?: readonly string[] }> = [ + { title: /^Hooks need review\b/, options: ["Review hooks", "Trust all and continue", "Continue without hooks"], choices: ["Continue without hooks"] }, + { title: /^Approaching rate limits\b/, options: ["Switch model", "Keep current model", "Keep current model (never show again)"] }, + { title: /^Update available\b/, options: ["Update now", "Skip", "Skip until next version"] } +]; +const MENU_OPTION = /^\s*(?:›\s*)?\d+\.\s+(.+)$/; + +/** + * The menu an orchestrator's connection may resolve, or null. A worker can print any text, so a menu counts only when + * its title is one of the three lines right above its options and the options are exactly that menu's; the hooks + * reviewed notice only when it is the last thing on the screen, above its "Press esc to close". + */ +function orchestratorMenu(screen: string): { choices?: readonly string[] } | null { + if (codexApprovalPrompt(screen)) return null; + const lines = screen.split("\n").map((line) => line.trim()); + const first = lines.findIndex((line) => MENU_OPTION.test(line)); + if (first === -1) { + const shown = lines.filter(Boolean); + return shown.length >= 2 && /^Press esc to close\b/i.test(shown.at(-1)!) && shown.slice(-3, -1).some((line) => /^\d+ hooks? reviewed\b/.test(line)) ? {} : null; + } + let last = first; + while (last + 1 < lines.length && MENU_OPTION.test(lines[last + 1])) last++; + if (lines.slice(last + 1).some((line) => MENU_OPTION.test(line))) return null; + const labels = lines.slice(first, last + 1).map((line) => line.match(MENU_OPTION)![1].trim()); + const above = lines.slice(Math.max(0, first - 3), first); + const menu = ORCHESTRATOR_MENUS.find((known) => above.some((line) => known.title.test(line)) + && labels.length === known.options.length && labels.every((label, i) => label === known.options[i])); + return menu ? (menu.choices ? { choices: menu.choices } : {}) : null; +} + /** - * 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. + * Whether an orchestrator's own connection may resolve the menu on this Codex screen: hooks review (only continuing + * without the hooks), the hooks reviewed notice, the model or rate-limit notice and the update notice. 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); + return orchestratorMenu(screen) !== null; } /** diff --git a/tests/orchestrator-approval-answers.test.mjs b/tests/orchestrator-approval-answers.test.mjs index adc2d2080..d6e9b505f 100644 --- a/tests/orchestrator-approval-answers.test.mjs +++ b/tests/orchestrator-approval-answers.test.mjs @@ -184,6 +184,44 @@ test("an orchestrator's control connection cannot choose, dismiss or type into a assert.deepEqual(f.written(call).slice(3), ["y", "3"], "only the person's answers reached the card"); }); +test("a known menu's title only counts in the menu's own block, over its own options", () => { + // A worker can print any text: a title elsewhere on the screen, or over options that are not that menu's, does not + // make an unrecognised prompt the orchestrator's. + const unknown = "Allow Codex to open the browser on example.com?\n› 1. Allow\n 2. Allow for this session\n 3. Deny"; + for (const screen of [ + `Hooks need review\nsome output\nmore output\nand more\n${unknown}`, + `Update available! 0.200.0 -> 0.201.0\n\n\n\n\n${unknown}`, + "Approaching rate limits\n› 1. Allow\n 2. Deny", + "Hooks need review\n› 1. Review hooks\n 2. Trust all and continue\n 3. Continue without hooks\n 4. Allow network access", + `6 hooks reviewed\n${unknown}\nPress esc to close`, + `Hooks\n6 hooks reviewed\nPress esc to close\n${unknown}` + ]) { + assert.equal(codexOrchestratorMenu(screen), false, screen); + } +}); + +test("hooks review stays the person's trust decision: an orchestrator may only continue without hooks or dismiss it", 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"); + const trustRefused = (error) => error.code === "NEEDS_PERSON" && /Continue without hooks/.test(error.message); + for (const choice of [1, 2]) { + await assert.rejects(f.agent("choose", { sessionId: session.id, choice, revision: hooks.interaction.revision }), trustRefused); + } + assert.deepEqual(f.written(call), [], "nothing was written"); + await f.agent("dismiss", { sessionId: session.id, revision: hooks.revision }); + await f.agent("choose", { sessionId: session.id, choice: 3, revision: hooks.interaction.revision }); + assert.deepEqual(f.written(call), ["\x1b", "\x1b[B\x1b[B\r"]); + + // A title the worker printed above an unrecognised prompt does not make that prompt the orchestrator's. + const spoof = await show(f.agent, session.id, call, `\x1b[2J\x1b[HHooks need review\r\nnote\r\nnote\r\nnote\r\n${UNKNOWN_APPROVAL.slice(7)}`, "Allow Codex"); + await assert.rejects(f.agent("choose", { sessionId: session.id, choice: 1, revision: spoof.interaction.revision }), unknownMenu); + assert.equal(f.written(call).length, 2); +}); + 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 });