viewable-one 0.0.0-stage → 0.12.2

package/lib/agents.mjs

@@ -0,0 +1,914 @@
+// WHICH ENGINE RUNS A SESSION, and the one place that knows how to drive it.
+//
+// The runner was never Claude-specific in shape - the binary and its arguments
+// came from PM_CLAUDE_BIN and PM_CLAUDE_ARGS, and nothing else in runner.mjs
+// knew what it was running. But the DEFAULTS were, and they were baked into a
+// single fallback array, so adding a second engine meant either an env
+// variable nobody would set or a branch in the middle of runRequest.
+//
+// So each engine is described once, here, and a request says which one it
+// wants. The runner asks this file for a command line and stays ignorant.
+//
+// TWO THINGS THAT ARE NOT THE SAME BETWEEN THEM, and both matter:
+//
+// PERMISSIONS. Claude Code takes an ALLOWLIST; opencode's only headless
+// option is `--auto`, which its own help calls "auto-approve permissions that
+// are not explicitly denied (dangerous!)": a deny list, no allow list, so the
+// shape is inverted. An opencode session is meaningfully less fenced than a
+// Claude Code one, in the same worktree, spending the same way. That is
+// recorded on each entry as `fenced`, so a caller can say so out loud rather
+// than discover it.
+//
+// WHAT `fenced: true` DOES AND DOES NOT MEAN. It used to say here, and in
+// bridge/README.md, that a Claude session "cannot open a shell". That was
+// false when it was written and it is false now: CLAUDE_TOOLS below carries
+// `Bash(git:*)`, `Bash(npm:*)`, `Bash(npx:*)` and `Bash(node:*)`, and
+// `Bash(node:*)` alone is `node -e '<anything>'` - an arbitrary program with
+// the session's own file access. `npx` is arbitrary package execution. Write
+// and Edit are unscoped, so the session may write any path it can reach,
+// which includes its own worktree's .git hooks. A claim a reader trusts and
+// the code does not keep is worse than no claim, so:
+//
+//   what the fence DOES stop: an interactive prompt nobody can answer
+//     (CLAUDE_DISALLOWED_TOOLS), a tool the session was never offered, and -
+//     with the git worktree, not with this list - edits landing on the
+//     checkout the user is looking at;
+//   what it does NOT stop: arbitrary code execution through node/npx, writes
+//     to any path the process can reach, or network access from inside one of
+//     those.
+//
+// One consequence is worth naming because it is not obvious: `PM_SPAWN_DEPTH`
+// stops a session running its OWN runner; it does not stop one asking the
+// board, over the hosted endpoint it is connected to, for another session.
+// Since brief 30 a request is a `runs` ROW filed through the app's own RPC
+// under the person's account, never a file in `.glytch/inbox/spawn/` (that
+// mailbox is not read by any runner any more), so the fence is the endpoint's
+// own gate rather than who wrote a file. The bounds that still hold are the
+// ones that never depended on the transport: the wall clock, no
+// retry, and a person reading the frames that appear on the board.
+//
+// NARROWING THE LIST IS A SEPARATE DECISION and is not made here: it changes
+// what a brief can do, so it is the user's to rule on.
+//
+// REACHING THE BOARD. Claude Code reads .mcp.json from the folder it runs in,
+// which is how a spawned session gets get_board, report and ask_user. opencode
+// does not read that file - it keeps its own config, and `opencode mcp list`
+// in a fresh checkout says "No MCP servers configured". A session that cannot
+// reach the board cannot report, cannot ask, and cannot come home to its own
+// frame, which is the whole design. `needsBoardSetup` says which engines have
+// to be wired up before they are worth offering.
+//
+// A THIRD ENGINE THAT IS NOT A THIRD BINARY (2026-09-02). `acp-claude` runs
+// Claude Code through the Agent Client Protocol adapter, which speaks
+// JSON-RPC over stdio rather than stream-json on stdout. Everything that
+// differs lives in lib/acp.mjs; what lives HERE is one row carrying
+// `protocol: "acp"`, and `runnerFor` picks the run function off that row -
+// so runRequest gained no branch. Read the head of acp.mjs for what maps
+// onto what and, more importantly, for the two things ACP does not give: a
+// spend CEILING (there is no field to set one) and a spend FIGURE (only
+// tokens). That is exactly why `claude` keeps its own path and stays the
+// default. Brief 15's ACP amendment says to treat "beside" as permanent
+// rather than as a migration step, and this table is where that is kept.
+//
+// ITS BOARD ACCESS IS ALSO NOT A FILE. Claude Code reads .mcp.json from the
+// folder it runs in; the ACP adapter is handed the board server inline, in
+// `session/new`'s `mcpServers` - verified in the spike, where the model
+// called the stub server and its answer came back in a tool_call_update. So
+// `needsBoardSetup` is false for a second, different reason, and
+// `acpServersFor` below is where the server is described.
+
+import { adapterEntry } from "./acp.mjs";
+import { computerAppsOffRule, conversationRules } from "./conversationRules.mjs";
+import { runEngineFor } from "./run-engine.mjs";
+// ONE LIST, not two: spawn.mjs's checkRequest is the validator a request
+// meets first, and this file's draft branch is what actually builds the
+// restricted command line for whichever engine gets past it. Importing
+// rather than repeating the name list means the two cannot drift apart the
+// way a comment and a `switch` always eventually do.
+import { PLAN_MODE_AGENTS } from "./spawn.mjs";
+// THE MCP SERVER KEY, imported rather than repeated (brief 31, Move 3b): the
+// per-session injection below used to name it "board" inline in three
+// places (the ACP server list, Claude's --mcp-config JSON, opencode's
+// OPENCODE_CONFIG_CONTENT); init-connect.mjs's own agent verbs
+// (`claude mcp login glytch`, etc.) already needed the same string as
+// SERVER_KEY, so this imports that one spelling rather than adding a fourth
+// copy of the literal.
+import { SERVER_KEY } from "./init-connect.mjs";
+
+/** What a spawned session may do under Claude Code.
+ *
+ * A list rather than "everything" or "nothing": a session with no permissions
+ * does NOTHING and stalls politely into a log nobody reads. This is what a
+ * brief on that board actually asks for.
+ *
+ * BE HONEST ABOUT WHAT SCOPING BUYS. Every Bash entry names its command, and
+ * that is a real narrowing - `Bash(rm:*)` is not on this list, and neither is
+ * bare `Bash`. It is NOT a fence against arbitrary execution: `Bash(node:*)`
+ * covers `node -e '<anything>'` and `Bash(npx:*)` covers running any package,
+ * so a session that wants a shell has two. Write and Edit are unscoped, so
+ * the session may write any path the process can reach. The comment above
+ * this file's AGENTS table has the full statement of what the fence does and
+ * does not stop, and why narrowing it is a ruling rather than a patch. */
+export const CLAUDE_TOOLS = [
+  "Read",
+  // KEPT, BUT IT WAS NEVER THE FIX (2026-08-30). Allowlisting ExitPlanMode
+  // (2026-08-29, after p-mteflfvk) was supposed to let a planning session
+  // proceed. It did not: spawn-mtf3xbm7 entered plan mode with this exact
+  // allowlist and every ExitPlanMode call came back `is_error: "Exit plan
+  // mode?"` - plan APPROVAL is an interactive prompt, not a tool permission,
+  // and --allowedTools does not cover it. The user typed "I approve" over
+  // stdin; the next three ExitPlanMode calls errored the same way. The real
+  // fix is CLAUDE_DISALLOWED_TOOLS below: never let a headless session enter
+  // plan mode at all. This entry stays so a legacy session resumed mid-plan
+  // can still TRY, and because removing it changes nothing either way.
+  //
+  // THE OLD SENTENCE "there is no --permission-prompt-tool" IS STALE (checked
+  // 2026-10-14 against Claude Code 2.1.299). The flag exists, and the
+  // streaming path now passes `--permission-prompt-tool stdio` (see
+  // streamingArgs): a tool call outside this list arrives on stdout as a
+  // `control_request` and child.mjs answers it, after the person has answered
+  // a question in the idea (bridge/lib/permissionAsk.mjs). The one-shot `-p`
+  // path has no stdin to answer on and is unchanged: outside the list, a tool
+  // call is refused.
+  "ExitPlanMode",
+  "Write",
+  "Edit",
+  "Glob",
+  "Grep",
+  // TodoWrite is GONE on Claude Code 2.1.270 - verified live 2026-09-21,
+  // `echo "list your tools" | claude -p ... --allowedTools "... TodoWrite
+  // Task"` lists TaskCreate/TaskUpdate/TaskList/TaskGet and no TodoWrite.
+  // Kept for an OLDER Claude Code that still ships it; the four Task* tools
+  // are the plan surface on every CLI actually in use now.
+  "TodoWrite",
+  "TaskCreate",
+  "TaskUpdate",
+  "TaskList",
+  "TaskGet",
+  "Task",
+  // RENAMED 2026-09-12 (brief 31, Move 3b): the MCP namespace the injected
+  // per-session server answers to is `SERVER_KEY` ("glytch") now, not
+  // "board" - acpServersFor and commandFor's --mcp-config both name the
+  // server that below, so an allowlist still saying "mcp__board" would
+  // match nothing a spawned session actually calls and silently cut off
+  // get_board, propose, ask_user and report.
+  `mcp__${SERVER_KEY}`,
+  "Bash(git:*)",
+  "Bash(npm:*)",
+  "Bash(npx:*)",
+  "Bash(node:*)",
+  "Bash(ls:*)",
+  "Bash(cat:*)",
+  "Bash(rg:*)",
+  "Bash(find:*)",
+  "Bash(sed:*)",
+  "Bash(grep:*)",
+];
+
+/** Tools a headless session must never be OFFERED, because they open an
+ * interactive prompt no one is there to answer.
+ *
+ * EnterPlanMode (2026-08-30): spawn-mtf3xbm7 called it unprompted, wrote a
+ * plan, and then could not leave - plan approval is an interactive gate that
+ * neither --permission-mode acceptEdits, nor an allowlisted ExitPlanMode, nor
+ * a typed "I approve" on stdin can pass on CLI 2.1.34. The session parked in
+ * plan mode across three resumes ($2.63 total) with its frame reading
+ * RUNNING. The brief IS the plan for a spawned session; the board's ask_user
+ * is the channel for real forks.
+ *
+ * AskUserQuestion: the same shape one step earlier - a question rendered in a
+ * terminal nobody is watching. The preamble already points every session at
+ * the board's ask_user instead; taking the dead tool away means the model
+ * reaches for the live one first rather than after a failed call. */
+export const CLAUDE_DISALLOWED_TOOLS = ["EnterPlanMode", "AskUserQuestion"];
+
+/** The two tools that reach the web. Allowed up front only when the person
+ * turned web search on for this run (`webSearch: true` on the spawn request);
+ * otherwise they are outside the list, and on the streaming path a call to
+ * one is a question in the idea ("Can I search the web?"). */
+export const CLAUDE_WEB_TOOLS = ["WebSearch", "WebFetch"];
+
+/** The allowlist for one run: the standing list, plus the web tools when the
+ * request switched web search on. A plain function of the request, so the
+ * one-shot and streaming command lines cannot disagree. */
+export const claudeToolsFor = (wants = {}) =>
+  wants.webSearch === true ? [...CLAUDE_TOOLS, ...CLAUDE_WEB_TOOLS] : CLAUDE_TOOLS;
+
+export const AGENTS = {
+  codex: {
+    label: "Codex", bin: "codex", binEnv: "PM_CODEX_BIN", argsEnv: "PM_CODEX_ARGS",
+    protocol: "codex-app-server", fenced: true, needsBoardSetup: false,
+    modelFlag: null, effortFlag: null, protocolEffort: true,
+    // RENAMED 2026-09-12 (brief 31, Move 3b): the server codexBoardArgs
+    // registers is `mcp_servers.glytch` now (lib/codex.mjs), so this is the
+    // namespace codex's own tool list actually answers to.
+    boardTool: (name) => `mcp__${SERVER_KEY}__${name}`, todoTool: "update_plan",
+    args: () => ["app-server"], sessionArgs: () => [], resumeArgs: () => [],
+  },
+  claude: {
+    label: "Claude Code",
+    bin: "claude",
+    binEnv: "PM_CLAUDE_BIN",
+    argsEnv: "PM_CLAUDE_ARGS",
+    // Fenced by an allowlist: the session is offered a named set of tools
+    // rather than all of them. Read what that does and does not stop at the
+    // top of this file before repeating it as "it cannot open a shell" - it
+    // can, through Bash(node:*) and Bash(npx:*), both on the list.
+    fenced: true,
+    // Reads .mcp.json from the folder it runs in, so a linked project wires
+    // itself up with no extra step.
+    needsBoardSetup: false,
+    // --model takes an alias (opus, sonnet) or a full name. There is NO
+    // unconditional effort flag: commandFor requires a fresh CLI capability probe.
+    modelFlag: "--model",
+    effortFlag: null,
+    // Claude Code exposes an MCP server's tools under mcp__<server>__<tool>,
+    // and answers to the bare name too.
+    boardTool: (name) => name,
+    // brief 23 ruling 4a (2026-09-07): the plan contract in preambleFor
+    // names this tool, so a session can be told the true name of the thing
+    // that carries its plan. UPDATED 2026-09-21: Claude Code 2.1.270 has no
+    // TodoWrite at all (verified live - see the CLAUDE_TOOLS comment above);
+    // it ships TaskCreate/TaskUpdate/TaskList/TaskGet instead. `write` and
+    // `update` are the tools preambleFor tells a session to plan with;
+    // `fallback` is TodoWrite for an older Claude Code that still has it -
+    // both are already allowlisted above.
+    todoTool: { write: "TaskCreate", update: "TaskUpdate", fallback: "TodoWrite" },
+    // ORDER MATTERS AND IT COST A RUN. `--allowedTools <tools...>` is
+    // VARIADIC: it eats every following argument that does not begin with a
+    // dash. With the prompt last it was swallowed as one more tool name and
+    // the session spawned, billed, and never saw its brief. The prompt goes
+    // immediately after -p, before any variadic flag.
+    //
+    // stream-json because in text mode `-p` prints only its closing message,
+    // so a session's log stayed empty for its whole run and the live terminal
+    // had nothing to draw. --verbose is required alongside it for -p.
+    args: (wants = {}) => [
+      "-p",
+      "{prompt}",
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      "--permission-mode",
+      "acceptEdits",
+      "--allowedTools",
+      claudeToolsFor(wants).join(" "),
+      // Variadic like --allowedTools, and for the same reason it sits after
+      // the prompt: one joined string, so it cannot eat what follows.
+      "--disallowedTools",
+      CLAUDE_DISALLOWED_TOOLS.join(" "),
+    ],
+    // SESSION PERSISTENCE: --session-id mints a new session, --resume
+    // continues one. Both are UUIDs, both verified on CLI 2.1.34.
+    // The runner appends exactly one of these to the args array.
+    sessionArgs: (sessionId) => ["--session-id", sessionId],
+    resumeArgs: (resumeId) => ["--resume", resumeId],
+    // STREAMING INPUT (part 3): the child stays alive and takes further user
+    // messages on stdin as JSON lines. The prompt is NOT in the args - it goes
+    // as the first message on stdin. --replay-user-messages echoes the typed
+    // reply back on stdout, which is what the terminal needs to draw it.
+    // Verified on CLI 2.1.34.
+    //
+    // ASK IN THE IDEA: with `askPermissions` the CLI is told to send every tool
+    // call outside the allowlist to us as a `control_request` on stdout
+    // (`--permission-prompt-tool stdio`, the SDK's own door; it is a hidden
+    // flag, present on 2.1.299). child.mjs answers it on stdin once the person
+    // has answered the question filed in the idea. Without the flag such a
+    // call is refused silently, which is what every run did before. A flag
+    // with a value, so it cannot swallow what follows it.
+    streamingArgs: (wants = {}) => [
+      "-p",
+      "--input-format", "stream-json",
+      "--output-format", "stream-json",
+      "--verbose",
+      "--replay-user-messages",
+      "--permission-mode", "acceptEdits",
+      ...(wants.askPermissions === true ? ["--permission-prompt-tool", "stdio"] : []),
+      "--allowedTools", claudeToolsFor(wants).join(" "),
+      // The streaming path is the one long sessions take, and it is exactly
+      // where spawn-mtf3xbm7 parked - so the same tools are barred here.
+      "--disallowedTools", CLAUDE_DISALLOWED_TOOLS.join(" "),
+    ],
+  },
+
+  // CLAUDE CODE, THE OTHER WAY ROUND (2026-09-02, brief 15 decision 8).
+  //
+  // Same model, same machine, same allowlist - a different pipe. The adapter
+  // is a node program, so `bin` is node itself and the single argument is the
+  // adapter's entrypoint, resolved from bridge/node_modules at command time.
+  // `PM_ACP_ADAPTER` overrides that, which is both the escape hatch for an
+  // odd install and the seam the tests drive a fake adapter through.
+  //
+  // WHAT THIS ENGINE IS FOR, and it is not "replacing claude". It is the one
+  // engine whose events arrive in a shape the live view of brief 15 wants
+  // without inference: streamed text, tool open and close, an
+  // auto-answerable permission door, a session that takes a second prompt,
+  // and a `session/cancel` for Stop. What it costs is the two things this
+  // bridge learned the hard way and acp.mjs re-states: no ceiling to set, and
+  // no dollar figure to report. Every receipt from here says "estimate".
+  "acp-claude": {
+    label: "Claude Code via ACP",
+    bin: process.execPath,
+    binEnv: "PM_ACP_NODE_BIN",
+    argsEnv: "PM_ACP_CLAUDE_ARGS",
+    // The SAME allowlist as `claude`, enforced at a different door: there it
+    // is `--allowedTools`, here it is the client answering
+    // session/request_permission from CLAUDE_TOOLS. One list, two doors.
+    fenced: true,
+    // The board server is passed inline at session/new (acpServersFor), so
+    // there is nothing to write into the worktree.
+    needsBoardSetup: false,
+    // NEITHER IS A FLAG on this engine: the model is a per-session config
+    // option (`session/set_config_option`, verified) and effort has no option
+    // at all on claude-agent-acp 0.73.0. modelFlag stays null so commandFor
+    // does not append a flag the adapter would choke on, and acp.model
+    // carries the request's choice instead. effortFlag stays null so an
+    // effort asked for is RECORDED as ignored rather than silently dropped.
+    modelFlag: null,
+    effortFlag: null,
+    boardTool: (name) => name,
+    // Same tools, same reason as the `claude` spec above: this is the same
+    // engine through a different pipe, so it carries the same Task* plan
+    // tools (updated 2026-09-21 alongside the `claude` spec).
+    todoTool: { write: "TaskCreate", update: "TaskUpdate", fallback: "TodoWrite" },
+    protocol: "acp",
+    adapter: "@agentclientprotocol/claude-agent-acp",
+    // dist/index.js, NOT the package name. The package's `main` is
+    // `dist/lib.js`, the adapter as a LIBRARY; the program that speaks
+    // JSON-RPC on stdio is its `bin`. Resolving the package name here got
+    // ERR_PACKAGE_PATH_NOT_EXPORTED on the first real run, because the "."
+    // export offers only an `import` condition. The spike used this same
+    // path.
+    adapterModule: "@agentclientprotocol/claude-agent-acp/dist/index.js",
+    // No `{prompt}` placeholder anywhere: the prompt is not an argument on
+    // this engine, it is the body of a session/prompt request. The runner
+    // passes it in the options object, which the other two engines ignore.
+    args: (wants = {}) => {
+      const entry = adapterEntry(
+        "@agentclientprotocol/claude-agent-acp/dist/index.js",
+        wants.env ?? process.env,
+      );
+      return entry ? [entry] : [];
+    },
+    // SESSION PERSISTENCE, and the honest state of it: a new session is minted
+    // by session/new every run, and a `resumeSessionId` is TRIED through
+    // session/load and falls back to a fresh session when it fails. The spike
+    // saw `loadSession: true` advertised but never loaded one, so this path
+    // is designed-for rather than proven - acp.mjs says so where it lives and
+    // bridge/SPAWN.md lists it as untested.
+    sessionArgs: () => [],
+    resumeArgs: () => [],
+  },
+
+  opencode: {
+    label: "opencode",
+    bin: "opencode",
+    binEnv: "PM_OPENCODE_BIN",
+    argsEnv: "PM_OPENCODE_ARGS",
+    // NOT fenced, and this is the honest difference. `--auto` auto-approves
+    // anything not explicitly denied. The worktree still bounds what it can
+    // WRITE; nothing bounds what it can RUN.
+    fenced: false,
+    // Keeps its own MCP config: `glytch init` writes the hosted `glytch`
+    // entry into opencode.json and `opencode mcp auth glytch` signs it in
+    // (brief 31, 2026-09-12; the spawned `glytch mcp` command this comment
+    // used to name is retired). Until that is done an opencode session runs
+    // blind - no get_board, no ask_user, no report - and its frame would open
+    // and never be written in.
+    needsBoardSetup: true,
+    // -m takes provider/model, which happens to be the same shape as an
+    // OpenRouter id. --variant IS reasoning effort, in its own words:
+    // "provider-specific reasoning effort, e.g., high, max, minimal".
+    modelFlag: "-m",
+    effortFlag: "--variant",
+    // opencode NAMESPACES them by the server key: <key>_get_board,
+    // <key>_report, <key>_ask_user. Telling a session to call `report` there
+    // is telling it to call something that does not exist - and it did
+    // exactly that, said "my tool list doesn't include get_board", and gave
+    // up. It was right. RENAMED 2026-09-12 (brief 31, Move 3b): the key
+    // prepareWorkspace registers under OPENCODE_CONFIG_CONTENT is
+    // SERVER_KEY ("glytch") now, not "board", so this must namespace the
+    // same way or a session is told to call a tool that no longer exists.
+    boardTool: (name) => `${SERVER_KEY}_${name}`,
+    todoTool: "todowrite",
+    // `run <message>` is the headless form; --format json is its event stream,
+    // the counterpart of Claude's stream-json. The message is a positional and
+    // goes first, for the same variadic reason.
+    args: () => ["run", "{prompt}", "--format", "json", "--auto"],
+  },
+};
+
+export const DEFAULT_AGENT = "claude";
+
+/** The agent a request asked for, or the default. Unknown names fall back
+ *  rather than throwing: a request naming an engine this runner has never
+ *  heard of should run on the default and say so, not die holding a claim. */
+export function agentFor(name) {
+  const key = typeof name === "string" ? name.trim().toLowerCase() : "";
+  return Object.prototype.hasOwnProperty.call(AGENTS, key) ? key : DEFAULT_AGENT;
+}
+
+// `isKnownAgent` was here and nothing called it. Removed 2026-09-02, and the
+// reason is a rule rather than tidiness: NOTHING in this runner refuses an
+// unknown engine name. agentFor falls back to the default and the receipt
+// says which ran, because dying while holding a claim on a request nobody
+// will retry is the expensive failure (checkRequest in spawn.mjs says so in
+// as many words). A predicate that answers "is this a known agent?" exists
+// only to be branched on, so leaving it here was an invitation to write the
+// branch that ruling forbids.
+
+/** Does this name belong to a coding CLI this bridge can run?
+ *
+ * THIS IS NOT `isKnownAgent`, the predicate retired above, and the difference
+ * is which decision it feeds. That one was asked "which engine runs this
+ * session?", and the ruling there stands: agentFor falls back to the default
+ * and the receipt says which ran, because dying while holding a claim on a
+ * request nobody will retry is the expensive failure.
+ *
+ * This one is asked "may this name reach a CHAT TURN at all?" (brief 25,
+ * 2026-09-07), and a fallback there is the exact confusion the brief exists to
+ * end. The whole ruling 1A is that a DM with a coding agent runs on Claude
+ * Code on his subscription rather than on an API key; a chat-turn file naming
+ * an engine this bridge does not have means the APP's routing broke, and
+ * quietly answering it as `claude` would tell him he is talking to the agent
+ * he named when he is not. So the chat door refuses, in words, and the
+ * session door still falls back. One predicate, one caller, one reason. */
+export const isCodingCli = (name) =>
+  typeof name === "string" && Object.prototype.hasOwnProperty.call(AGENTS, name.trim().toLowerCase());
+
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+
+/** Does this request run a PERSISTENT session - one that mints or resumes a
+ * session id, so its worktree is kept and it can be resumed? */
+export const isPersistentRequest = (request) =>
+  nonEmpty(request?.sessionId) || nonEmpty(request?.resumeSessionId);
+
+/** Can a message be delivered INTO this session while it runs?
+ *
+ * A persistent session whose engine has a DOOR, and there are two of them
+ * now. On `claude` the door is stdin: the runner starts that child with
+ * `--input-format stream-json` and holds the pipe open. On `acp-claude` the
+ * door is a second `session/prompt` into the same sessionId - the spike
+ * proved a session stays alive between turns with no stdin trick, and
+ * runAcpChild delivers each reply file that way.
+ *
+ * opencode still has neither, and a one-shot request on either engine has
+ * none either: nothing reads reply files on that path, so a reply written
+ * beside a one-shot child sits on disk for ever.
+ *
+ * This is the same expression `runRequest` uses to choose the persistent
+ * path, and it lives here rather than in both places: the local stdio
+ * server's list_sessions asserted the opposite of it for every session
+ * ("no receipt, can receive messages"), and two spellings of one rule is how
+ * that happens. */
+export const acceptsMessages = (request) =>
+  request?.planMode !== "draft" && isPersistentRequest(request) && runEngineFor(AGENTS[agentFor(request?.agent)]).acceptsMessages;
+
+
+/** WHICH FUNCTION RUNS THE CHILD, off the engine row rather than out of a
+ * branch in runRequest.
+ *
+ * This existed as `useStreaming ? runStreamingChild : runChild` in the middle
+ * of runRequest, which was fine while every engine spoke stream-json on
+ * stdout. `acp-claude` does not, so the choice became a property of the
+ * engine - which is what this table has always been for. runRequest asks and
+ * stays ignorant, exactly as it does for the command line. */
+export function runnerFor(agent, streaming) {
+  const spec = AGENTS[agentFor(agent)];
+  const engine = runEngineFor(spec);
+  return streaming ? engine.streaming : engine.run;
+}
+
+/** The board, described the way an ACP `session/new` wants it.
+ *
+ * MOVED ONTO THE HOSTED ENDPOINT, 2026-09-11 (brief 30, W2a): the local
+ * stdio server this used to spawn as a subprocess of the adapter is
+ * retired - every engine reaches the board over HTTP now
+ * (supabase/functions/board-mcp), never through a locally-spawned process. A
+ * stdio entry became an HTTP one; nothing else about how ACP is handed its
+ * MCP servers changed - still inline at `session/new` rather than a file on
+ * disk, because ACP takes it as a request parameter (verified in the spike
+ * that this reaches the model as `mcp__<name>__<tool>`, so preambleFor's
+ * Claude naming needs no change here either).
+ *
+ * THE SHAPE IS THE PROTOCOL'S OWN, checked against
+ * @agentclientprotocol/sdk@1.4.0's schema (`McpServerHttp`, dist/schema/
+ * types.gen.d.ts): `{type: "http", name, url, headers: Array<{name, value}>}`
+ * - an ARRAY of {name, value} pairs for headers, the same shape env already
+ * used, not a plain object. This is a wire-format fact checked against the
+ * installed SDK's TypeScript types, not run against a live adapter: whether
+ * claude-agent-acp 0.73.0 actually implements an HTTP-type server (as
+ * opposed to merely accepting the shape and failing later) is UNVERIFIED - it
+ * advertises `McpCapabilities.http` at `initialize`, and nothing in this
+ * bridge has checked that flag or run a real session against it. */
+export function acpServersFor(agent, { mcpUrl, token, sessionKey, boardId }) {
+  const spec = AGENTS[agentFor(agent)];
+  if (spec.protocol !== "acp" || !mcpUrl || !token) return [];
+  const headers = [{ name: "Authorization", value: `Bearer ${token}` }];
+  if (sessionKey) headers.push({ name: "X-Glytch-Session", value: sessionKey });
+  // THE RUN'S OWN BOARD (2026-09-21, board reporting fix), same rule as
+  // X-Glytch-Session above: board-mcp/index.ts seeds `boardFor`'s fallback
+  // from this header, so `report` and friends land on the board this run
+  // actually belongs to rather than guessing the account's most recent one.
+  if (boardId) headers.push({ name: "X-Glytch-Board", value: boardId });
+  return [{ type: "http", name: SERVER_KEY, url: mcpUrl, headers }];
+}
+
+/** Binary and arguments for one engine, with env overrides applied.
+ *
+ * `<AGENT>_ARGS` still overrides the lot for anyone who wants something else,
+ * and junk falls back to the engine's own default rather than to nothing -
+ * a malformed override must not quietly strip the permission flags. */
+// ASK RULES FOR EVERY APP TOOL (#481). Claude Code checks deny, then ask,
+// then allow, across every settings file, so an ask rule beats an allow the
+// person saved earlier ("Yes, and don't ask again" on a Gmail tool). One
+// `mcp__*` would also stop glytch's own tools, and a rule's only wildcard is
+// `*`, so "every MCP tool but glytch's" is spelled out a character at a
+// time: any name that leaves `mcp__glytch__` at some position. Claude Code
+// turns every other character of a server name into `_`, so these
+// characters are all a tool name can hold there. The last two rules catch a
+// server of the person's named `glytch_` or `glytch__x`, whose tools would
+// otherwise read as glytch's; no glytch tool starts with `_` or holds `__`.
+const TOOL_NAME_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-";
+export function appAskRules(keep = `mcp__${SERVER_KEY}__`) {
+  const rules = [];
+  for (let i = "mcp__".length; i < keep.length; i += 1) {
+    for (const c of TOOL_NAME_CHARS) if (c !== keep[i]) rules.push(`${keep.slice(0, i)}${c}*`);
+  }
+  return [...rules, `${keep}_*`, `${keep}*__*`];
+}
+
+export function commandFor(agent, env = process.env, wants = {}) {
+  const spec = AGENTS[agentFor(agent)];
+  const bin = env[spec.binEnv]?.trim() || spec.bin;
+  // A draft never inherits a wider command line, MCP server, hook, skill,
+  // persisted session or shell tool. --tools removes capabilities entirely;
+  // --allowedTools alone only skips interactive permission prompts.
+  //
+  // WHICH ENGINES REACH THIS BRANCH IS NOT A LOCAL DECISION - see
+  // PLAN_MODE_AGENTS in bridge/lib/spawn.mjs, the checked validator, and
+  // briefs/plan-mode-beyond-claude.md for what was verified before each name
+  // was added. Codex joined Claude here 2026-09-11: the native app-server's
+  // `sandbox: "read-only"` thread policy is an OS-level seatbelt/landlock
+  // restriction the child process cannot argue its way out of (verified
+  // against the installed codex-cli 0.153.4's own generated protocol schema,
+  // `codex app-server generate-json-schema` - `ReadOnlySandboxPolicy`
+  // defaults `networkAccess: false` on top of blocking writes), combined
+  // with `approvalPolicy: "never"` (a blocked write is returned to the model
+  // as a failure, never escalated) and never configuring the board MCP
+  // server for that thread's process at all (runCodexChild, codex.mjs, skips
+  // `codexBoardArgs` outright when `config.planMode === "draft"` - the actual
+  // enforcement lives there, this branch only refuses to hand it anything to
+  // enforce against). opencode is deliberately absent: see the note beside
+  // `PLAN_MODE_AGENTS` in spawn.mjs for why its shipped `plan` agent does not
+  // meet this bar.
+  if (wants.planMode === "draft") {
+    const engine = agentFor(agent);
+    if (!PLAN_MODE_AGENTS.includes(engine)) throw new Error("Read-only planning currently requires Claude Code or Codex.");
+    if (engine === "codex") {
+      return {
+        bin, args: ["app-server"], spec, ignored: [], acp: null,
+        codex: {
+          model: typeof wants.model === "string" ? wants.model.trim() : "",
+          effort: typeof wants.effort === "string" ? wants.effort.trim() : "",
+          // NO RESUME, EVER, on a draft: a fresh thread every time, so a
+          // draft can never inherit a prior turn's permissions or history.
+          resumeSessionId: "",
+          // NO BOARD ACCESS: omitted rather than passed and ignored, so a
+          // future change to runCodexChild cannot accidentally wire a board
+          // server back in for a draft by forgetting to check planMode a
+          // second time.
+          boardUrl: undefined, sessionKey: undefined, boardId: undefined, argsOverridden: false,
+          // NO APPS EITHER (#481): runCodexChild switches off every MCP
+          // server the person set up in Codex for a draft, whatever the
+          // agent's own setting says.
+          computerApps: false,
+          planMode: "draft",
+        },
+      };
+    }
+    const args = ["-p", "{prompt}", "--output-format", "stream-json", "--verbose",
+      "--permission-mode", "dontAsk", "--tools", "Read,Glob,Grep,WebSearch,WebFetch",
+      "--allowedTools", "Read,Glob,Grep,WebSearch,WebFetch",
+      "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}',
+      "--setting-sources", "", "--settings", '{"disableAllHooks":true}',
+      "--disable-slash-commands", "--no-chrome", "--no-session-persistence"];
+    if (typeof wants.model === "string" && wants.model.trim()) args.push("--model", wants.model.trim());
+    const effort = typeof wants.effort === "string" ? wants.effort.trim() : "";
+    if (effort && wants.claudeEfforts?.includes(effort)) args.push("--effort", effort);
+    return { bin, args, spec, ignored: effort && !wants.claudeEfforts?.includes(effort) ? ["effort (not supported by this model on this computer)"] : [], acp: null };
+  }
+  const raw = env[spec.argsEnv];
+  // STREAMING MODE: when the caller asks for streaming and the engine supports
+  // it, use the streaming args (prompt on stdin, child stays alive for replies).
+  // `env` rides along in `wants` so an engine whose command line depends on
+  // the environment can build it - `acp-claude` resolves its adapter's
+  // entrypoint, and PM_ACP_ADAPTER overrides it. Every other engine ignores
+  // the field.
+  const asked = { ...wants, env };
+  let args = asked.streaming && spec.streamingArgs ? spec.streamingArgs(asked) : spec.args(asked);
+  let overridden = false;
+  if (typeof raw === "string" && raw.trim() !== "") {
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed) && parsed.every((a) => typeof a === "string")) {
+        args = parsed;
+        overridden = true;
+      }
+    } catch {
+      /* fall through to the engine's default rather than failing to start */
+    }
+  }
+
+  // WHAT THE CIRCLE ASKED FOR. Appended rather than woven in, so it cannot
+  // disturb the argument ORDER that a variadic flag depends on - the prompt
+  // has to stay ahead of --allowedTools, and a model flag inserted in the
+  // middle is how that breaks again.
+  //
+  // Skipped entirely when PM_*_ARGS replaced the command line: someone who
+  // wrote their own arguments meant them, and appending to them is guessing.
+  //
+  // An engine with no effort flag DROPS the request rather than approximating
+  // it. Claude requires local capability evidence before adding --effort;
+  // an older CLI must not fail the whole run over a preference.
+  const ignored = [];
+  if (!overridden) {
+    const model = typeof wants.model === "string" ? wants.model.trim() : "";
+    if (model !== "" && spec.modelFlag) args = [...args, spec.modelFlag, model];
+    const effort = typeof wants.effort === "string" ? wants.effort.trim() : "";
+    if (effort !== "") {
+      if (agentFor(agent) === "claude" && wants.claudeEfforts?.includes(effort)) args = [...args, "--effort", effort];
+      else if (spec.effortFlag) args = [...args, spec.effortFlag, effort];
+      else if (!spec.protocolEffort) ignored.push(agentFor(agent) === "claude" ? "effort (not supported by this model on this computer)" : `effort (${spec.label} has no such setting)`);
+    }
+    // SESSION PERSISTENCE: resume takes priority over sessionId. Both are
+    // appended AFTER --allowedTools because they are not variadic, and they
+    // must come after the prompt for the same reason model and effort do.
+    //
+    // Only Claude Code supports this on 2.1.34. opencode has no equivalent.
+    const resume = typeof wants.resumeSessionId === "string" ? wants.resumeSessionId.trim() : "";
+    const session = typeof wants.sessionId === "string" ? wants.sessionId.trim() : "";
+    if (resume !== "" && spec.resumeArgs) {
+      args = [...args, ...spec.resumeArgs(resume)];
+    } else if (session !== "" && spec.sessionArgs) {
+      args = [...args, ...spec.sessionArgs(session)];
+    }
+    // THE BOARD, OVER THE HOSTED ENDPOINT (2026-09-11, brief 30 W2a).
+    // The local stdio server Claude Code used to reach through a checked-in
+    // .mcp.json is retired - so this engine gets its
+    // board access the same way session/new and codexBoardArgs give it to
+    // the other two: built here, from what the runner resolved once through
+    // lib/auth.mjs (bridge/lib/runner.mjs), never from a file in the
+    // worktree. opencode and codex have their own wiring (an env override, a
+    // `-c` override, respectively) because a bare bearer token in THEIR
+    // command line would sit in `ps`; ACP gets it as protocol payload over
+    // stdio (the `acp` object below), never argv either.
+    //
+    // VERIFIED against the installed claude 2.1.34: `claude mcp add
+    // --transport http board <url> --header "Authorization: Bearer x"
+    // --header "X-Glytch-Session: y" -s project` writes exactly this shape
+    // into .mcp.json - `{"mcpServers":{"board":{"type":"http","url":...,
+    // "headers":{...}}}}` - so this is the JSON `--mcp-config` is documented
+    // to accept as a string, run against the real binary rather than assumed.
+    // RENAMED 2026-09-12 (brief 31, Move 3b): the key WRITTEN below is
+    // `glytch` (SERVER_KEY), not `board` - the verification above predates
+    // the rename and is kept dated rather than rerun, since it was checking
+    // the shape `--mcp-config` accepts, not the key name.
+    //
+    // --strict-mcp-config makes this the ONLY MCP config the session sees:
+    // any committed .mcp.json (which may still name the retired local
+    // server), any user- or project-level config, all of it ignored. Skipped
+    // when PM_CLAUDE_ARGS replaced the command line, for the same reason
+    // model/effort/session are: someone who wrote their own arguments meant
+    // them, and this bridge appending to a fully custom command line is
+    // guessing at what would not clash. A run with no boardUrl/boardToken
+    // (not signed in, no VIEWABLE_BOARD_TOKEN) still gets `--strict-mcp-config`
+    // with an EMPTY server list - no board tools, rather than a session that
+    // silently tries a stale local one.
+    if (agentFor(agent) === "claude") {
+      const boardUrl = typeof wants.boardUrl === "string" ? wants.boardUrl.trim() : "";
+      const boardToken = typeof wants.boardToken === "string" ? wants.boardToken.trim() : "";
+      const sessionKey = typeof wants.sessionKey === "string" ? wants.sessionKey.trim() : "";
+      const boardId = typeof wants.boardId === "string" ? wants.boardId.trim() : "";
+      const mcpServers =
+        boardUrl && boardToken
+          ? {
+              [SERVER_KEY]: {
+                type: "http",
+                url: boardUrl,
+                headers: {
+                  Authorization: `Bearer ${boardToken}`,
+                  ...(sessionKey ? { "X-Glytch-Session": sessionKey } : {}),
+                  // THE RUN'S OWN BOARD (2026-09-21, board reporting fix) -
+                  // same reasoning as acpServersFor's X-Glytch-Board above.
+                  ...(boardId ? { "X-Glytch-Board": boardId } : {}),
+                },
+              },
+            }
+          : {};
+      // USE MY COMPUTER'S APPS (#481). Off, the default: strict, glytch
+      // only, as above. On, for this one agent and this one person: the
+      // strict flag goes, so the person's own Claude Code MCP servers load
+      // beside glytch. Their tools are NOT added to --allowedTools, and an
+      // ask rule covers every one of them, so a tool the person allowed in
+      // their own settings before still asks each time; in -p mode that
+      // ask is refused until the permission ask (#478) reaches the person.
+      const apps = wants.computerApps === true
+        ? ["--settings", JSON.stringify({ permissions: { ask: appAskRules() } })]
+        : ["--strict-mcp-config"];
+      args = [...args, ...apps, "--mcp-config", JSON.stringify({ mcpServers })];
+    }
+  }
+  // WHAT AN ACP ENGINE NEEDS THAT AN ARGUMENT LIST CANNOT CARRY. Model,
+  // permission mode, the board's MCP server and the allowlist are all
+  // protocol payload rather than command line, so they travel beside the
+  // command instead of inside it. Null for every other engine, and runAcpChild
+  // is the only reader.
+  //
+  // The MODEL IS NOT DROPPED HERE even though modelFlag is null: the block
+  // above skips it because there is no flag to put it on, and it arrives at
+  // the session through `session/set_config_option` instead. Effort is a
+  // genuine drop and is on `ignored` above, because the adapter offers no
+  // reasoning option at all.
+  const acp =
+    spec.protocol === "acp"
+      ? {
+          label: spec.label,
+          adapter: spec.adapter,
+          allowTools: CLAUDE_TOOLS,
+          mode: "acceptEdits",
+          model: typeof wants.model === "string" ? wants.model.trim() : "",
+          mcpServers: acpServersFor(agent, {
+            mcpUrl: wants.boardUrl,
+            token: wants.boardToken,
+            sessionKey: wants.sessionKey,
+            boardId: wants.boardId,
+          }),
+          resumeSessionId:
+            typeof wants.resumeSessionId === "string" ? wants.resumeSessionId.trim() : "",
+        }
+      : null;
+
+  const codex = spec.protocol === "codex-app-server" ? {
+    model: wants.model?.trim() ?? "", effort: wants.effort?.trim() ?? "",
+    resumeSessionId: wants.resumeSessionId?.trim() ?? "",
+    boardUrl: wants.boardUrl, sessionKey: wants.sessionKey, boardId: wants.boardId, argsOverridden: overridden,
+    // ASK IN THE IDEA: on-request approvals instead of never, so a step outside
+    // the sandbox reaches the runner (codex.mjs onRequest) instead of being
+    // refused. Only when the runner can actually ask (it passes
+    // `askPermissions` only with a board to ask on).
+    askPermissions: wants.askPermissions === true,
+    // The person turned web search on for this run.
+    webSearch: wants.webSearch === true,
+    computerApps: wants.computerApps === true,
+  } : null;
+  return { bin, args, spec, ignored, acp, codex };
+}
+
+/** Give an engine what it needs to reach the board, in the tree it will run in.
+ *
+ * Claude Code needs nothing here: its board access is on the command line
+ * commandFor already built (`--strict-mcp-config --mcp-config`).
+ *
+ * opencode keeps its own config and a fresh checkout reports "No MCP servers
+ * configured", so without this an opencode session runs blind - no get_board,
+ * no ask_user, no report - and its run would open on the idea and
+ * have nothing written into it (DATED REWRITE 2026-09-07, brief 26 ruling 4:
+ * was "its frame would open and never be written in").
+ *
+ * MOVED OFF A WRITTEN opencode.json ONTO OPENCODE_CONFIG_CONTENT, 2026-09-11
+ * (brief 30, W2a): the local server this used to name as a
+ * `type: "local"` entry is retired, and the replacement is a bearer
+ * token - writing THAT into a file inside the session's own worktree is a
+ * secret sitting on disk for as long as the worktree lives (kept for review,
+ * resumed, or simply not yet cleaned up), for no gain over an env var the
+ * child alone sees. `OPENCODE_CONFIG_CONTENT` is confirmed present in the
+ * installed opencode 1.18.23 binary (`strings` for the name) and its
+ * `type: "remote"` MCP shape is confirmed by running `opencode mcp add
+ * --url <url> --header "Name=value"` against a real project and reading back
+ * what it wrote - `{"mcp":{"board":{"type":"remote","url":...,
+ * "headers":{...}}}}` - checked against the real binary rather than assumed.
+ * Whether OPENCODE_CONFIG_CONTENT MERGES with a project's own opencode.json
+ * or replaces it outright is unverified either way; this bridge no longer
+ * writes a competing file for opencode, so there is nothing for either
+ * reading to conflict with.
+ *
+ * RENAMED 2026-09-12 (brief 31, Move 3b): the key WRITTEN below is `glytch`
+ * (SERVER_KEY), not `board` - the verification above predates the rename
+ * and is kept dated rather than rerun, since it was checking the shape
+ * `opencode mcp add` produces, not the key name. */
+export async function prepareWorkspace(agent, { mcpUrl, token, sessionKey, boardId }) {
+  const spec = AGENTS[agentFor(agent)];
+  if (!spec.needsBoardSetup) return { wrote: null };
+  if (!mcpUrl || !token) return { wrote: null };
+
+  const config = {
+    $schema: "https://opencode.ai/config.json",
+    mcp: {
+      [SERVER_KEY]: {
+        type: "remote",
+        url: mcpUrl,
+        enabled: true,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          ...(sessionKey ? { "X-Glytch-Session": sessionKey } : {}),
+          // THE RUN'S OWN BOARD (2026-09-21, board reporting fix) - same
+          // reasoning as acpServersFor's X-Glytch-Board above.
+          ...(boardId ? { "X-Glytch-Board": boardId } : {}),
+        },
+      },
+    },
+  };
+  return { wrote: null, env: { OPENCODE_CONFIG_CONTENT: JSON.stringify(config) } };
+}
+
+/** What every brief is prefixed with, in the tool names THAT engine uses.
+ *
+ * It was one fixed string naming `ask_user` and `report`. Claude Code answers
+ * to those; opencode namespaces its MCP tools as `board_ask_user` and
+ * `board_report`, so a session was being told to call things that did not
+ * exist. It said so - "my tool list doesn't include get_board" - and stopped,
+ * which was the correct response to a wrong instruction.
+ *
+ * A session cannot be MADE to ask or report. It can only be told, accurately,
+ * in the one place it always reads. */
+export function preambleFor(agent, { workplace, computerApps } = {}) {
+  const spec = AGENTS[agentFor(agent)];
+  const ask = spec.boardTool("ask_user");
+  const report = spec.boardTool("report");
+  return (
+    "You were spawned from a canvas by a person who is not watching a terminal. " +
+    (workplace ?? "You are in your own git worktree: commit your work on this branch, never " +
+    "merge to main, and never touch the checkout above you.\n\n") +
+    `If a permission or anything else blocks you, ask on the board with ${ask} ` +
+    `rather than stopping quietly - it lands as a question on your idea that the person answers ` +
+    "on the canvas, and that is the only channel you have. Then, whatever happens, " +
+    // DATED REWRITE 2026-09-07 (brief 26, ruling 4, found still standing in
+    // the QA sweep of the runner): "a session that ends without reporting
+    // leaves a frame reading DONE with nothing in it". There is no frame and
+    // no DONE badge - the run's record rides the idea and its card
+    // reads it - so the sentence named a surface the person cannot see any
+    // more. What has not changed is the consequence, which is the reason the
+    // sentence exists at all: silence looks exactly like success.
+    `call ${report} before you finish, including when you did nothing: the ` +
+    "card on the person's idea just reads finished, and they cannot " +
+    "tell that apart from success.\n\n" +
+    `Your board tools are named ${spec.boardTool("get_board")}, ` +
+    `${spec.boardTool("get_node")}, ${spec.boardTool("propose")}, ${ask} and ${report}.\n\n` +
+    // brief 23 ruling 4a (2026-09-07): the app derives the run's structure
+    // - its steps, decisions and waiting state - from this session's own
+    // log, and this preamble is the one place every session reads. So the
+    // plan contract has to live here: propose a plan, keep it current with
+    // whatever tool tracks it, say the word when a choice is made, and ask
+    // rather than guess.
+    //
+    // SHARPENED 2026-09-07 (QA sweep of the runner): no run in the sweep
+    // showed any run steps. The app reads the plan out of the todo
+    // tool's own calls (src/folder/sessionLog/plan.ts), so a session that
+    // writes the plan in prose, or writes it after the work, shows no steps.
+    // The two bounds below are what the design's plan spine needs and what a
+    // session cannot guess: WHEN to write it (before the first edit) and HOW
+    // MANY (3 to 8 - fewer is not a plan, more is a transcript).
+    "Work to a plan, and keep it where the board can read it. Before your " +
+    "first edit, write a plan of 3 to 8 steps in the order you mean to do " +
+    "them, one line each.\n\n" +
+    todoSentenceFor(spec.todoTool) +
+    "Whenever you make a choice the person would want to know about, write " +
+    'one line beginning "Decided: " saying what you chose and why. One ' +
+    "sentence, your own words. Those lines are what the person reads " +
+    "instead of the transcript.\n\n" +
+    `If you are blocked on something only the person can rule on, ask with ${ask} rather than guessing.\n\n` +
+    // The switch exists for Claude Code and Codex only (#481), so only they
+    // are told how to ask for it.
+    (["claude", "codex"].includes(agentFor(agent)) && computerApps !== true ? computerAppsOffRule() : "") +
+    conversationRules(spec, ask)
+  );
+}
+
+/** The plan-tool sentence of preambleFor, split out because `todoTool` now
+ * comes in two shapes: a plain tool name (codex's `update_plan`, opencode's
+ * `todowrite`) or, since 2026-09-21, `{write, update, fallback}` for the
+ * `claude` and `acp-claude` specs - Claude Code 2.1.270 dropped TodoWrite and
+ * ships TaskCreate/TaskUpdate/TaskList/TaskGet instead (verified live; see
+ * the CLAUDE_TOOLS comment above). `fallback` names TodoWrite for an older
+ * Claude Code that still has it. */
+function todoSentenceFor(todoTool) {
+  if (!todoTool) return "";
+  if (typeof todoTool === "string") {
+    return (
+      `Write that plan with the ${todoTool} tool, one todo per step, and ` +
+      "keep the statuses current as you go: exactly one step in progress " +
+      "at a time, and a step marked completed the moment it is done. The " +
+      "run screen shows that list as the run's steps.\n\n"
+    );
+  }
+  const { write, update, fallback } = todoTool;
+  return (
+    `Write that plan with ${write}, one task per step, in the order you ` +
+    `mean to do them. Keep the statuses current as you go with ${update}: ` +
+    "exactly one step in_progress at a time, and a step marked completed " +
+    `the moment it is done (on an older Claude Code with no ${write}, use ` +
+    `${fallback} instead). The run screen shows that list as the run's ` +
+    "steps.\n\n"
+  );
+}