hilos-agent 0.6.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # hilos-agent
 
-Run **your own** coding agent — Claude Code, Codex, Cursor, Hermes, or any command — as
+Run **your own** coding agent — Claude Code, Codex, Cursor, opencode, Hermes, or any command — as
 an autonomous teammate inside a [hilos](https://hilos.sh) channel.
 
 It connects to hilos over MCP, watches for `@mentions` of your agent in a
@@ -42,7 +42,7 @@ Running from elsewhere, or want to map several repos explicitly? Use a config:
   "url": "https://hilos.sh/api/mcp",
   "token": "mgo_…",
   "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
-  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text --trust", "agy -p", any command
+  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text --trust", "opencode run", "agy -p", any command
   "codingModel": "",  // model preset tier ("opus" | "sonnet" | "haiku") resolved at run time against the CLI's own model list (Cursor only today); "" = the tool's default
   "chatCmd": "",  // FAST command for chat replies + the plan-ack. Empty = derived from codingCmd's tool (codex daemons chat with codex, etc.); set to override
   "defaultBranch": "main",
@@ -82,9 +82,24 @@ hilos-agent --channel <id>   # scope to one channel
   `repos`. No mapping → the agent says so and stops.
 - **Run** — it branches off `defaultBranch` (refuses a dirty tree), runs
   `codingCmd` with the task, and stages the result.
+- **Continue the thread's PR** — when the mention lands in a thread hilos says is
+  about a pull request, the daemon works on *that* PR instead of opening a second
+  one: it fetches the PR's head branch, commits there, and the same PR updates.
+  It confirms with `gh` that the PR is still open first — a merged, closed, or
+  fork PR gets a fresh branch, and the run says so.
+- **Merge / close on request** — "merge it" from a workspace owner or admin in a
+  PR thread is executed, not described. The daemon relays the request to hilos
+  with the id of the message that asked; hilos verifies the person's role and
+  that their message really asks for it, then acts with the workspace's GitHub
+  App. The daemon never merges on its own judgment and holds no merge rights.
 - **Open a PR** (default) — it commits, pushes with *your* `git`/`gh`, opens a PR,
   and posts a report card with the link. Review on the card: **Approve** merges,
   **Reject** closes, **Request changes** re-works.
+- **Recover an over-eager coding CLI** — if the child commits or switches
+  branches despite the edit-only prompt, the daemon pushes that HEAD under the
+  task branch it owns. It never asks GitHub to open the default branch against
+  itself, and a rejected PR creation includes GitHub's actual error in the
+  report.
 - **Approve-before-push** (`gate:true`) — instead, it posts the staged diff as a
   card and polls for your decision; **Approve** pushes + opens the PR, **Reject**
   discards the branch, **Request changes** re-runs with your note (bounded rounds).
@@ -187,6 +202,14 @@ explains what each permission level means.
 `codingCmd` decides how much the coding agent can do on its own. Three levels,
 safest first:
 
+- **`opencode run` (runtime-gated).** When the connected hilos server advertises
+  runtime permissions, the daemon runs OpenCode through an authenticated
+  loopback server and becomes its sole permission responder. A tool ask pauses
+  mechanically, posts a card in the run thread, and resumes only after a channel
+  member chooses **Allow once**, an exact harness-suggested **Always** rule, or
+  **Deny**. Missing transport, expiry, and cancellation all reject the tool
+  call. `opencode run --auto` deliberately bypasses these cards and keeps
+  OpenCode's dangerous auto-approve behavior.
 - **`--permission-mode acceptEdits` (default).** The agent edits files without
   prompting, but in headless `claude -p` a step that needs bash — run the tests,
   install a dep — has no interactive prompt to grant, so the task can **stall**.
@@ -208,7 +231,10 @@ safest first:
 
 The default stays `acceptEdits`. Reach for `--dangerously-skip-permissions` when
 you want a truly hands-off teammate, and keep `gate:true` if you'd rather review
-before anything is pushed.
+before anything is pushed. OpenCode is the first harness with the runtime-card
+bridge; Claude Code, Codex, Cursor, and other adapters still follow their own
+CLI permission modes until their native approval hooks join the same
+vendor-neutral hilos substrate.
 
 ## Hooks — stream a raw Claude Code session
 

package/bin/hilos-agent.mjs

@@ -16,10 +16,18 @@
 // codingCmd in hilos-agent.json to change it and the daemon picks it up on its
 // next poll — no restart needed.
 
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
 import { resolveConfig, decodeJoin, writeStarterConfig, GLOBAL_CONFIG } from "../src/config.mjs";
 import { run } from "../src/run.mjs";
 import { hookMain, hooksMain } from "../src/hook.mjs";
 
+function packageVersion() {
+  const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+  return JSON.parse(readFileSync(pkgPath, "utf8")).version;
+}
+
 function parseArgs(argv) {
   const flags = {};
   const positional = [];
@@ -38,6 +46,7 @@ function parseArgs(argv) {
     else if (a === "--no-gate") flags.gate = false;
     else if (a === "--global") flags.global = true;
     else if (a === "-h" || a === "--help") flags.help = true;
+    else if (a === "-v" || a === "--version") flags.version = true;
     else positional.push(a);
   }
   return { cmd: positional[0] || "run", flags, positional };
@@ -57,7 +66,8 @@ Options:
   --channel <id>     watch only one channel (per-channel override)
   --config <path>    use a specific config file
   --coding-cmd <cmd> the coding agent to run — claude -p, codex exec,
-                     cursor-agent -p --trust, agy -p, hermes, or any command
+                     cursor-agent -p --trust, opencode run, agy -p, hermes,
+                     or any command
                      that takes a prompt as its last arg (default: "claude -p")
   --coding-model <tier>  model preset tier (opus | sonnet | haiku) resolved at
                      run time against the CLI's own model list — never a baked
@@ -68,12 +78,17 @@ Options:
   --once             one poll then exit (cron-friendly)
   --backfill         also act on mentions that predate startup
   --no-gate          propose only; don't wait for approval / push
+  -v, --version      print the installed version
   -h, --help         this help
 
 Docs: https://hilos.sh  ·  https://www.npmjs.com/package/hilos-agent`;
 
 async function main() {
   const { cmd, flags, positional } = parseArgs(process.argv.slice(2));
+  if (flags.version || cmd === "version") {
+    console.log(packageVersion());
+    return;
+  }
   if (flags.help || cmd === "help") {
     console.log(HELP);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions in channels and threads, makes the change, and opens a PR for review — your code and credentials never leave your machine. (Approve-before-push is available via gate:true.)",
   "type": "module",
   "bin": {

package/src/acp-session.mjs

@@ -0,0 +1,538 @@
+// ACP (Agent Client Protocol) session runner (0759).
+//
+// Drives an agent subprocess over ACP — JSON-RPC 2.0, newline-delimited, on
+// stdio — instead of argv + stdout scraping. The 0596 spike proved the loop
+// live against `opencode acp`: permissions arrive as blocking JSON-RPC
+// requests with allow-once/always/reject options, and streaming arrives as
+// structured session/update notifications.
+//
+// The permission callback contract is EXACTLY the HTTP bridge's
+// (requestPermission / getPermissionDecision, see opencode-permissions.mjs),
+// so neither transport can become the ungated exception; the decision
+// vocabulary is shared via mapOpenCodePermissionDecision. Every failure mode
+// answers the agent with a rejection — fail closed, never fail open.
+//
+// The public runner returns the same small shape as runCli /
+// runOpenCodeHttpSession so handler.mjs keeps one integration seam:
+//   { status, stdout, stderr, error?, sessionId?, aborted? }
+
+import { spawn } from "node:child_process";
+import { mapOpenCodePermissionDecision } from "./opencode-permissions.mjs";
+
+const DEFAULT_TIMEOUT_MS = 30 * 60_000;
+const DEFAULT_POLL_MS = 1_000;
+const SHUTDOWN_GRACE_MS = 750;
+const PROTOCOL_VERSION = 1;
+const MAX_LINE_BYTES = 4 * 1024 * 1024;
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function abortError(reason = "cancelled") {
+  const error = new Error(String(reason || "cancelled"));
+  error.name = "AbortError";
+  return error;
+}
+
+function raceWithAbort(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(abortError(signal.reason));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal.reason));
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve(promise).then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Choose the agent's option id for a hilos reply ("once"|"always"|"reject").
+ * Matches on the ACP option `kind` first (allow_once / allow_always /
+ * reject_once / reject_always), then falls back to id/name heuristics. A
+ * reject reply with no recognizable option returns null — the caller answers
+ * with a protocol-level cancel, which the agent must treat as not-allowed.
+ */
+export function pickAcpPermissionOption(options, reply) {
+  const list = Array.isArray(options) ? options.filter(isObject) : [];
+  const byKind = (kind) => list.find((o) => o.kind === kind);
+  const byPattern = (re) =>
+    list.find((o) => re.test(`${o.optionId ?? ""} ${o.name ?? ""}`));
+  if (reply === "always") {
+    // The name fallback must never land on "Reject always" — a human's
+    // allow-always answered with a rejection would invert the decision.
+    return (
+      byKind("allow_always") ??
+      list.find(
+        (o) =>
+          !String(o.kind ?? "").startsWith("reject") &&
+          /always/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`) &&
+          !/reject|deny|\bno\b/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`),
+      ) ??
+      null
+    );
+  }
+  if (reply === "once") {
+    // Never widen a single-use approval into a persistent one: an allow_once
+    // option is required; allow_always is NOT an acceptable stand-in.
+    return (
+      byKind("allow_once") ??
+      list.find(
+        (o) =>
+          o.kind !== "allow_always" &&
+          /\bonce\b|allow/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`) &&
+          !/always/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`),
+      ) ??
+      null
+    );
+  }
+  return (
+    byKind("reject_once") ??
+    byKind("reject_always") ??
+    byPattern(/reject|deny|no\b/i) ??
+    null
+  );
+}
+
+/**
+ * Shape an ACP session/request_permission into the vendor-neutral request the
+ * hilos permission callbacks expect (the same fields the SSE relay produces).
+ */
+export function normalizeAcpPermissionRequest(params, fallbackId, vendor = "opencode") {
+  const toolCall = isObject(params?.toolCall) ? params.toolCall : {};
+  const rawInput = isObject(toolCall.rawInput) ? toolCall.rawInput : {};
+  const locations = Array.isArray(toolCall.locations)
+    ? toolCall.locations
+        .map((l) => (isObject(l) && typeof l.path === "string" ? l.path : null))
+        .filter(Boolean)
+    : [];
+  const command = typeof rawInput.command === "string" ? rawInput.command : null;
+  const resources = locations.length ? locations : command ? [command] : [];
+  const vendorRequestId =
+    typeof toolCall.toolCallId === "string" && toolCall.toolCallId
+      ? toolCall.toolCallId
+      : `acp_${fallbackId}`;
+  return {
+    vendor,
+    vendorRequestId,
+    sessionId: typeof params?.sessionId === "string" ? params.sessionId : "",
+    action: typeof toolCall.kind === "string" && toolCall.kind ? toolCall.kind : "tool",
+    resources,
+    suggestedSave: undefined,
+    metadata: {
+      ...(typeof toolCall.title === "string" && toolCall.title
+        ? { title: toolCall.title }
+        : {}),
+      ...(command ? { command } : {}),
+      transport: "acp",
+    },
+    source: { type: "tool", ...(typeof toolCall.title === "string" ? { name: toolCall.title } : {}) },
+  };
+}
+
+/** Split a stdout stream into newline-delimited JSON-RPC messages. */
+export function createNdjsonParser() {
+  let buffer = "";
+  return {
+    push(chunk) {
+      buffer += String(chunk);
+      if (buffer.length > MAX_LINE_BYTES) {
+        // A frame this large is not a protocol message; drop it rather than
+        // letting a runaway agent grow the daemon's heap without bound.
+        buffer = "";
+        return [];
+      }
+      const messages = [];
+      let idx;
+      while ((idx = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, idx).trim();
+        buffer = buffer.slice(idx + 1);
+        if (!line) continue;
+        try {
+          const parsed = JSON.parse(line);
+          if (isObject(parsed)) messages.push(parsed);
+        } catch {
+          // Non-JSON stdout noise (banners, stray logs) is not a frame.
+        }
+      }
+      return messages;
+    },
+  };
+}
+
+/**
+ * Run one prompt against an ACP agent subprocess.
+ *
+ * Slice 1 (0759) intentionally mirrors the HTTP runner's text mode: stdout
+ * collects the agent's completed message text, tool activity stays off the
+ * transcript, and the session id is returned for the caller's records.
+ *
+ * @param {{
+ *   cmd?: string,
+ *   acpArgs?: string[],
+ *   vendor?: string,
+ *   cwd?: string,
+ *   prompt?: string,
+ *   env?: Record<string, string | undefined>,
+ *   timeoutMs?: number,
+ *   pollIntervalMs?: number,
+ *   signal?: AbortSignal,
+ *   onData?: (chunk: string) => void,
+ *   requestPermission?: (request: object, context: object) => Promise<unknown>,
+ *   getPermissionDecision?: (handle: unknown, context: object) => Promise<unknown>,
+ *   mcpServers?: object[],
+ *   spawnImpl?: (cmd: string, args: string[], options: object) => import("node:child_process").ChildProcess,
+ *   setTimer?: typeof setTimeout,
+ *   clearTimer?: typeof clearTimeout,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   now?: () => number,
+ *   log?: { error?: (message: string) => void },
+ * }} [options]
+ * @returns {Promise<{ status: number | null, stdout: string, stderr: string, error?: Error | null, sessionId?: string | null, aborted?: boolean }>}
+ */
+export async function runAcpSession({
+  cmd = "opencode",
+  acpArgs = ["acp"],
+  vendor = "opencode",
+  cwd,
+  prompt,
+  env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  pollIntervalMs = DEFAULT_POLL_MS,
+  signal,
+  onData,
+  requestPermission,
+  getPermissionDecision,
+  mcpServers = [],
+  spawnImpl = spawn,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+  log = console,
+} = {}) {
+  if (!cwd) {
+    return { status: null, stdout: "", stderr: "", error: new Error("ACP requires cwd") };
+  }
+  if (typeof requestPermission !== "function" || typeof getPermissionDecision !== "function") {
+    // Without the hilos gate there is no one to answer asks; refuse to start
+    // rather than run a session whose permissions would dead-end.
+    return {
+      status: null,
+      stdout: "",
+      stderr: "",
+      error: new Error("ACP transport requires the hilos permission callbacks"),
+    };
+  }
+
+  const controller = new AbortController();
+  let abortKind = null;
+  const abort = (kind, reason) => {
+    if (controller.signal.aborted) return;
+    abortKind = kind;
+    controller.abort(reason);
+  };
+  const onParentAbort = () => abort("cancelled", signal?.reason ?? "cancelled");
+  if (signal?.aborted) onParentAbort();
+  else signal?.addEventListener?.("abort", onParentAbort, { once: true });
+  const timeout =
+    timeoutMs > 0
+      ? setTimer(() => abort("timeout", `ACP session timed out after ${timeoutMs}ms`), timeoutMs)
+      : null;
+  timeout?.unref?.();
+
+  let child = null;
+  let sessionId = null;
+  let stdout = "";
+  let stderr = "";
+  let nextId = 0;
+  const pending = new Map();
+  const permissionTasks = new Set();
+  let currentMessageId = null;
+  let messageBuffer = "";
+
+  const emitOutput = (text) => {
+    try {
+      onData?.(`${text}\n`);
+    } catch {
+      // Output observers never own session correctness.
+    }
+  };
+  const flushMessage = () => {
+    const text = messageBuffer.trim();
+    messageBuffer = "";
+    currentMessageId = null;
+    if (!text) return;
+    stdout += `${text}\n`;
+    emitOutput(text);
+  };
+
+  const writeFrame = (frame) => {
+    if (!child || child.stdin.destroyed) return false;
+    try {
+      child.stdin.write(`${JSON.stringify(frame)}\n`);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const rpc = (method, params) => {
+    const id = ++nextId;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject, method });
+      if (!writeFrame({ jsonrpc: "2.0", id, method, params })) {
+        pending.delete(id);
+        reject(new Error(`ACP agent is not accepting frames (${method})`));
+      }
+    });
+  };
+  const respond = (id, result, error) => {
+    writeFrame(
+      error
+        ? { jsonrpc: "2.0", id, error }
+        : { jsonrpc: "2.0", id, result },
+    );
+  };
+  const failPending = (reason) => {
+    for (const [, entry] of pending) entry.reject(new Error(reason));
+    pending.clear();
+  };
+
+  async function settlePermission(msg) {
+    const request = normalizeAcpPermissionRequest(msg.params, msg.id, vendor);
+    const receivedAt = now();
+    const deadlineAt = receivedAt + Math.max(1, timeoutMs || DEFAULT_TIMEOUT_MS);
+    let reply = "reject";
+    let handle = null;
+    try {
+      if (controller.signal.aborted) throw abortError(controller.signal.reason);
+      handle = await raceWithAbort(
+        requestPermission(request, { signal: controller.signal, deadlineAt }),
+        controller.signal,
+      );
+      let decision = handle;
+      let mapped = mapOpenCodePermissionDecision(decision);
+      while (!mapped) {
+        if (now() >= deadlineAt) throw abortError("timeout");
+        decision = await raceWithAbort(
+          getPermissionDecision(handle, {
+            request,
+            signal: controller.signal,
+            deadlineAt,
+          }),
+          controller.signal,
+        );
+        mapped = mapOpenCodePermissionDecision(decision);
+        if (mapped) break;
+        const waitMs = Math.min(Math.max(1, pollIntervalMs), Math.max(1, deadlineAt - now()));
+        await raceWithAbort(sleep(waitMs), controller.signal);
+      }
+      reply = mapped;
+    } catch (error) {
+      reply = "reject";
+      log?.error?.(`acp permission decision: ${error?.message ?? error}`);
+      // The agent is about to be failed closed. Settle the durable hilos card
+      // too, on a bounded one-shot call — the run signal may already be gone.
+      if (handle) {
+        try {
+          await getPermissionDecision(handle, {
+            request,
+            deadlineAt,
+            failClosed: true,
+          });
+        } catch (settlementError) {
+          log?.error?.(
+            `acp permission settlement: ${settlementError?.message ?? settlementError}`,
+          );
+        }
+      }
+    }
+    const option = pickAcpPermissionOption(msg.params?.options, reply);
+    if (option && (reply !== "reject" || option.kind?.startsWith("reject"))) {
+      respond(msg.id, { outcome: { outcome: "selected", optionId: option.optionId } });
+    } else if (reply === "reject") {
+      // No recognizable reject option: cancel the ask at the protocol level.
+      respond(msg.id, { outcome: { outcome: "cancelled" } });
+    } else {
+      // An approval we cannot express in the agent's options must not become
+      // an implicit rejection card-side; the wire still gets a cancel.
+      log?.error?.("acp permission: no matching option for reply, cancelling");
+      respond(msg.id, { outcome: { outcome: "cancelled" } });
+    }
+  }
+
+  function handleUpdate(update) {
+    if (!isObject(update)) return;
+    const kind = update.sessionUpdate;
+    if (kind === "agent_message_chunk") {
+      const messageId = typeof update.messageId === "string" ? update.messageId : null;
+      if (currentMessageId !== null && messageId !== currentMessageId) flushMessage();
+      currentMessageId = messageId;
+      const text =
+        isObject(update.content) && typeof update.content.text === "string"
+          ? update.content.text
+          : "";
+      messageBuffer += text;
+      return;
+    }
+    // Thoughts, tool calls, usage, command lists: structurally received, not
+    // part of slice 1's transcript (parity with the HTTP runner's text mode).
+  }
+
+  function handleMessage(msg) {
+    if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+      const entry = pending.get(msg.id);
+      if (!entry) return;
+      pending.delete(msg.id);
+      if (msg.error) {
+        entry.reject(
+          new Error(
+            `ACP ${entry.method} failed: ${msg.error.message ?? JSON.stringify(msg.error)}`,
+          ),
+        );
+      } else {
+        entry.resolve(msg.result);
+      }
+      return;
+    }
+    if (msg.method === "session/update") {
+      if (isObject(msg.params) && msg.params.sessionId === sessionId) {
+        handleUpdate(msg.params.update);
+      }
+      return;
+    }
+    if (msg.method === "session/request_permission" && msg.id !== undefined) {
+      const task = settlePermission(msg).finally(() => permissionTasks.delete(task));
+      permissionTasks.add(task);
+      return;
+    }
+    if (msg.id !== undefined && msg.method) {
+      // fs/terminal requests should never arrive (capabilities declared off);
+      // refuse anything unexpected instead of guessing.
+      respond(msg.id, undefined, {
+        code: -32601,
+        message: `hilos does not implement ${msg.method}`,
+      });
+    }
+  }
+
+  try {
+    child = spawnImpl(cmd, acpArgs, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+    const spawned = new Promise((resolve, reject) => {
+      child.once("spawn", resolve);
+      child.once("error", reject);
+    });
+    child.once("exit", (code) => {
+      failPending(`ACP agent exited (${code ?? "signal"}) before replying`);
+    });
+    const parser = createNdjsonParser();
+    child.stdout.on("data", (chunk) => {
+      for (const msg of parser.push(chunk)) {
+        try {
+          handleMessage(msg);
+        } catch (error) {
+          log?.error?.(`acp frame handling: ${error?.message ?? error}`);
+        }
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+      if (stderr.length > MAX_LINE_BYTES) stderr = stderr.slice(-MAX_LINE_BYTES);
+    });
+    await raceWithAbort(spawned, controller.signal);
+
+    const init = await raceWithAbort(
+      rpc("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: {
+          fs: { readTextFile: false, writeTextFile: false },
+          terminal: false,
+        },
+      }),
+      controller.signal,
+    );
+    if (isObject(init) && init.protocolVersion !== undefined && init.protocolVersion !== PROTOCOL_VERSION) {
+      throw new Error(`ACP agent speaks protocol ${init.protocolVersion}, expected ${PROTOCOL_VERSION}`);
+    }
+
+    const session = await raceWithAbort(
+      rpc("session/new", { cwd, mcpServers }),
+      controller.signal,
+    );
+    sessionId = isObject(session) && typeof session.sessionId === "string" ? session.sessionId : null;
+    if (!sessionId) throw new Error("ACP agent created a session without an id");
+
+    const turn = await raceWithAbort(
+      rpc("session/prompt", {
+        sessionId,
+        prompt: [{ type: "text", text: String(prompt ?? "") }],
+      }),
+      controller.signal,
+    );
+    flushMessage();
+    // Every in-flight permission has been answered or is being failed closed by
+    // its own error path; give those settlements a bounded chance to finish.
+    await Promise.allSettled([...permissionTasks]);
+
+    const stopReason = isObject(turn) && typeof turn.stopReason === "string" ? turn.stopReason : null;
+    const clean = stopReason === "end_turn" || stopReason == null;
+    return {
+      status: clean ? 0 : 1,
+      stdout: stdout.trimEnd(),
+      stderr: stderr.trimEnd(),
+      error: clean ? null : new Error(`ACP turn stopped: ${stopReason}`),
+      sessionId,
+    };
+  } catch (error) {
+    flushMessage();
+    const aborted = abortKind === "cancelled";
+    const timedOut = abortKind === "timeout";
+    return {
+      status: null,
+      stdout: stdout.trimEnd(),
+      stderr: stderr.trimEnd(),
+      ...(aborted ? { aborted: true } : {}),
+      ...(sessionId ? { sessionId } : {}),
+      error:
+        error instanceof Error && !timedOut
+          ? error
+          : new Error(timedOut ? "ACP session timed out" : String(error)),
+    };
+  } finally {
+    if (timeout != null) clearTimer(timeout);
+    signal?.removeEventListener?.("abort", onParentAbort);
+    if (child && child.exitCode === null && !child.killed) {
+      // Ask for a graceful stop first (the agent may flush state), then kill.
+      if (sessionId) {
+        writeFrame({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+      }
+      try {
+        child.stdin.end();
+      } catch {
+        // Already gone.
+      }
+      const grace = setTimer(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // Already gone.
+        }
+      }, SHUTDOWN_GRACE_MS);
+      grace?.unref?.();
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // Already gone.
+      }
+    }
+    failPending("ACP session finished");
+  }
+}