@gleapai/kai-bridge 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Run Gleap Kai Code sessions on your own machine with your own Claude Code / Codex login — and preview your real dev servers from the dashboard or the phone.",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@agentclientprotocol/claude-agent-acp": "0.73.0",
-    "@agentclientprotocol/codex-acp": "1.8.0",
+    "@agentclientprotocol/codex-acp": "1.10.0",
     "@agentclientprotocol/sdk": "1.4.0",
     "@playwright/mcp": "^0.0.79",
     "@sockudo/client": "^2.0.0",

package/runner/acp-runner.mjs

@@ -39,8 +39,9 @@ import {
   startHeartbeat,
   traceLog,
 } from "./lib/contract.mjs";
-import { deriveEngineSlug, getHarness, isNativeAnthropic, pickSessionMode, resolveHarnessId } from "./lib/acp/harnesses.mjs";
+import { deriveEngineSlug, getHarness, isNativeAnthropic, pickSessionConfigOptions, pickSessionMode, resolveHarnessId } from "./lib/acp/harnesses.mjs";
 import { createAcpMapper, permissionPolicy } from "./lib/acp/mapper.mjs";
+import { describeProviderError, extractProviderError } from "./lib/acp/providerError.mjs";
 import { aggregateUsageRows, lastRootContextSnapshot } from "./lib/acp/transcripts.mjs";
 import { needsWireProxy, startWireProxy } from "./lib/wire-proxy.mjs";
 
@@ -115,6 +116,13 @@ const ASK_USER_MCP_PATH = process.env.KAI_ASK_USER_MCP_PATH || join(RUNNER_DIR,
 // todo tool at all. `todo_write` calls are folded onto the canonical
 // TodoWrite path by the mapper, which emits the dashboard `todos`
 // events either way.
+// Predicted next user prompt (Claude Code's composer ghost text).
+// The SDK generates it AFTER the turn's result on the warm prompt
+// cache (measured 1–3s behind the result); the runner holds the
+// process open for at most this long to pick it up. Only when the
+// harness can produce one — otherwise the turn ends as before.
+const PROMPT_SUGGESTION_WAIT_MS = Math.max(0, Number(process.env.KAI_PROMPT_SUGGESTION_WAIT_MS ?? 5000) || 0);
+const PROMPT_SUGGESTIONS_ENABLED = process.env.KAI_PROMPT_SUGGESTIONS !== "0" && PROMPT_SUGGESTION_WAIT_MS > 0;
 const TODO_SERVER_KEY = "kai_todos";
 const TODO_MCP_PATH = process.env.KAI_TODO_MCP_PATH || join(RUNNER_DIR, "tools", "todo-mcp.mjs");
 const TODO_NOTE =
@@ -145,6 +153,17 @@ const GATEWAY_PLAN_GUARD =
   `If you asked questions via the ${ASK_USER_TOOL_REF}, ` +
   "do NOT also finalise the plan in the same turn — wait for " +
   "the answers first.";
+// Harnesses without an enforced read-only plan mode (codex-acp's
+// "read-only" is a workspace-write sandbox that merely asks before
+// touching files OUTSIDE the workspace — found live 2026-09-06 when
+// Codex implemented the whole ticket during its plan turn). The prompt
+// has to carry the rule, and the bridge discards plan-turn edits.
+const READ_ONLY_PLAN_NOTE =
+  "PLAN MODE IS READ-ONLY. Do not create, edit or delete files and do " +
+  "not run commands that change the workspace (no installs, no " +
+  "formatters, no git writes) — nothing enforces this for you, and every " +
+  "change made during a plan turn is discarded before the build starts. " +
+  "Read, search and reason; then end your turn with the plan.";
 // Tool allow-lists (Claude permission rules). Plan mode and artifact
 // writers (kai-asker / researcher / documentarian: `.kai/` outputs only,
 // never repo edits) run under the CLI's own gating with these rules;
@@ -244,6 +263,7 @@ function buildAppendSystemPrompt() {
   }
   if (NEEDS_ASK_USER_MCP && !IS_ARTIFACT_WRITER) sections.push(GATEWAY_QUESTION_NOTE);
   if (IS_PLAN_MODE) sections.push(NEEDS_ASK_USER_MCP ? GATEWAY_PLAN_GUARD : PLAN_QUESTION_GUARD);
+  if (IS_PLAN_MODE && HARNESS_ID !== "claude") sections.push(READ_ONLY_PLAN_NOTE);
   if (!IS_PLAN_MODE) sections.push(GIT_HANDOFF_PROMPT);
   // After the safety guards (their leading position is load-bearing for
   // cursor's prompt-prefix mode) but before project instructions.
@@ -573,6 +593,15 @@ async function main() {
       traceLog("session.mode.failed", { modeId: desiredMode, error: String(err?.message ?? err) });
     }
   }
+  // Codex's native plan collaboration mode (see pickSessionConfigOptions).
+  for (const option of pickSessionConfigOptions(HARNESS_ID, ctx, sessionResponse.configOptions)) {
+    try {
+      await conn.setSessionConfigOption({ sessionId: acpSessionId, ...option });
+      traceLog("session.config", option);
+    } catch (err) {
+      traceLog("session.config.failed", { ...option, error: String(err?.message ?? err) });
+    }
+  }
 
   // Artifact writers must leave the repo untouched: snapshot before,
   // revert anything outside `.kai/` after (belt-and-braces under the
@@ -593,6 +622,14 @@ async function main() {
   inFlight = false;
   stopHeartbeat?.();
 
+  // Start the suggestion wait NOW so it overlaps the transcript/usage
+  // work below; awaited just before the harness is torn down. Skipped
+  // when the turn ended abnormally or by a question / plan hand-off
+  // (the SDK suppresses suggestions there anyway).
+  const wantSuggestion =
+    PROMPT_SUGGESTIONS_ENABLED && !promptError && !cancelRequested && stopReason !== "refusal" && !!HARNESS.supportsPromptSuggestions?.(ctx);
+  const suggestionPromise = wantSuggestion ? mapper.waitForPromptSuggestion(PROMPT_SUGGESTION_WAIT_MS) : Promise.resolve(null);
+
   const finished = mapper.finish();
   if (IS_ARTIFACT_WRITER) {
     try {
@@ -642,6 +679,12 @@ async function main() {
     tracker.setProviderCostUsd(finished.usage.costUsd);
   }
 
+  const suggestionWaitStarted = Date.now();
+  const promptSuggestion = await suggestionPromise;
+  if (wantSuggestion) {
+    traceLog("prompt_suggestion", { received: !!promptSuggestion, waitedMs: Date.now() - suggestionWaitStarted });
+  }
+
   try {
     child.kill("SIGTERM");
   } catch {
@@ -658,8 +701,26 @@ async function main() {
   if (stopReason === "refusal") {
     emit({ type: "error", message: "The model declined to continue (refusal)." });
   }
+  // A backend rejection codex-acp forwarded as text is a failed turn,
+  // not an answer — and never a plan (see providerError.mjs).
+  const providerError = cancelRequested ? null : extractProviderError(finished.lastText);
+  if (providerError) {
+    traceLog("provider.error", providerError);
+    emitSync({ type: "error", message: describeProviderError(providerError) });
+    emitSync(tracker.buildResultEvent({ sessionId: acpSessionId }));
+    process.exit(1);
+  }
   const resultMessage = IS_PLAN_MODE && !finished.planEmitted && !finished.questionAsked ? finished.lastText : "";
   if (IS_PLAN_MODE && resultMessage) emit({ type: "plan", message: resultMessage });
+  // Before `result`: the host treats result as terminal, and the bridge
+  // relay answers 410 for events on an ended turn.
+  if (promptSuggestion) {
+    emit({
+      type: "prompt_suggestion",
+      message: promptSuggestion,
+      promptSuggestion: { text: promptSuggestion, source: "harness", harness: HARNESS_ID },
+    });
+  }
   emitSync(tracker.buildResultEvent({ message: resultMessage, sessionId: acpSessionId }));
   debugLog("done", { stopReason, cancelRequested, steps: usageRows.length });
   process.exit(0);

package/runner/lib/acp/harnesses.mjs

@@ -8,10 +8,11 @@
 // Adding a harness = adding an entry here; the runner and the mapper
 // never branch on harness id.
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import { findClaudeTranscript, findCodexRollout, readClaudeTurnUsage, readCodexTurnUsage } from "./transcripts.mjs";
+import { isClaudeAcpPatched } from "../../tools/patch-claude-acp.mjs";
 
 export const HARNESS_IDS = ["claude", "codex", "cursor"];
 
@@ -48,6 +49,24 @@ export function resolveHarnessId(explicit, model) {
  * advertises (`session/new` → `modes.availableModes`); null when the
  * agent advertises no modes (then `session/set_mode` is skipped).
  */
+/**
+ * Session config options to set right after the mode. Codex has a NATIVE
+ * plan collaboration mode ("Plan before making changes") that codex-acp
+ * exposes as the `collaboration_mode` select option — the only real
+ * read-only plan mode Codex has: its ACP "read-only" mode is a
+ * workspace-write sandbox, and the prompt alone did not stop it from
+ * editing during a plan turn (2026-09-06). Empty when the agent does not
+ * advertise the option (older codex-acp, other harnesses).
+ */
+export function pickSessionConfigOptions(harnessId, ctx, configOptions) {
+  if (harnessId !== "codex" || !ctx?.isPlanMode) return [];
+  const option = (Array.isArray(configOptions) ? configOptions : []).find((o) => o?.id === "collaboration_mode");
+  if (!option) return [];
+  const values = (Array.isArray(option.options) ? option.options : []).map((o) => String(o?.value ?? o));
+  if (!values.includes("plan")) return [];
+  return option.currentValue === "plan" ? [] : [{ configId: "collaboration_mode", value: "plan" }];
+}
+
 export function pickSessionMode(preferred, available) {
   const ids = new Set((Array.isArray(available) ? available : []).map((m) => String(m?.id ?? m)));
   if (ids.size === 0) return preferred[0] ?? null;
@@ -85,6 +104,27 @@ function resolveAgentCommand(runnerDir, name, extraArgs = []) {
   return { cmd: name, args: [...extraArgs] };
 }
 
+/**
+ * Does the resolved claude-agent-acp build forward the SDK's
+ * `prompt_suggestion` (see tools/patch-claude-acp.mjs)? Upstream drops
+ * it, so the runner only waits for a suggestion when the marker is
+ * present — an unpatched adapter costs nothing but the feature.
+ */
+function claudeAdapterForwardsSuggestions(ctx) {
+  // Test hook: the conformance suite drives a scripted agent (no adapter
+  // build on disk) and asserts the suggestion path end to end.
+  if (process.env.KAI_PROMPT_SUGGESTIONS === "force") return true;
+  const { cmd } = resolveAgentCommand(ctx.runnerDir, "claude-agent-acp");
+  // `.bin/claude-agent-acp` → `<pkg>/dist/index.js`; acp-agent.js sits beside it.
+  let target = cmd;
+  try {
+    target = realpathSync(cmd);
+  } catch {
+    return false;
+  }
+  return isClaudeAcpPatched(join(dirname(target), "acp-agent.js"));
+}
+
 const tomlString = (v) => JSON.stringify(String(v ?? ""));
 const sanitizeMcpKey = (raw) => String(raw || "").replace(/[^a-zA-Z0-9_-]/g, "_");
 
@@ -102,6 +142,12 @@ export function buildCodexConfigToml(mcpServers) {
     "show_raw_agent_reasoning = true",
     "[features]",
     "collaboration_modes = true",
+    // The user's ChatGPT connectors ("apps") stay out of Kai sessions:
+    // a bridge turn runs under the teammate's own ChatGPT login, and
+    // with apps on, Codex reached the Gleap connector of that account —
+    // tools the session's MCP config had disabled (draft_reply_to_composer
+    // landed in the composer through it; found live 2026-09-06).
+    "apps = false",
   ];
   for (const server of mcpServers || []) {
     if (!server || typeof server !== "object") continue;
@@ -200,6 +246,11 @@ export const HARNESSES = {
       claudeCode: {
         options: {
           model: ctx.engineModel || deriveEngineSlug(ctx.model),
+          // Predicted next user prompt after each turn (Claude Code's
+          // ghost text). Rides the turn's prompt cache, so ~free; the
+          // patched adapter forwards it, the runner emits it as a
+          // `prompt_suggestion` contract event.
+          promptSuggestions: true,
           // BYO inherits the user's OWN MCP world by design (their
           // user-scope servers + claude.ai connectors, alongside the
           // project's injected ones): it's their machine and only they
@@ -235,6 +286,13 @@ export const HARNESSES = {
         },
       },
     }),
+    /**
+     * Can this harness hand back a predicted next prompt after a turn?
+     * Claude: the SDK generates one (suppressed in plan mode, after
+     * errors, near usage limits) and the patched adapter forwards it.
+     * Absent on codex/cursor — neither exposes anything comparable.
+     */
+    supportsPromptSuggestions: (ctx) => !ctx.isPlanMode && !ctx.isArtifactWriter && claudeAdapterForwardsSuggestions(ctx),
     /** ACP session modes to try, in order (`session/set_mode`) — the adapter's own ids. */
     sessionModePreference: (ctx) => (ctx.isPlanMode ? ["plan"] : ctx.isArtifactWriter ? ["dontAsk", "plan"] : ["bypassPermissions", "acceptEdits", "default"]),
     /** A prior turn's transcript on disk is what makes `resume` viable. */

package/runner/lib/acp/mapper.mjs

@@ -66,6 +66,21 @@ export function toolNameFromUpdate(update) {
   return "Tool";
 }
 
+/**
+ * codex-acp's post-plan permission request ("Implement this plan?", kind
+ * switch_mode, `_meta.codex.kind: "plan_review"`, the plan in
+ * `rawInput.plan`) → the plan markdown; null for every other request.
+ */
+export function planReviewText(params) {
+  const toolCall = params?.toolCall ?? {};
+  const isPlanReview =
+    params?._meta?.codex?.kind === "plan_review" ||
+    (toolCall.kind === "switch_mode" && /implement this plan/i.test(String(toolCall.title ?? "")));
+  if (!isPlanReview) return null;
+  const plan = toolCall.rawInput?.plan;
+  return typeof plan === "string" ? plan.trim() : "";
+}
+
 /** Normalise adapter-specific raw inputs into the shapes summarizeTool knows. */
 export function normalizeToolInput(name, update) {
   const raw = update?.rawInput;
@@ -208,6 +223,7 @@ function contentToValue(content) {
  * @param {boolean} opts.isPlanMode            plan agents hold prose for the result
  * @param {(reason: string) => void} opts.onTurnShouldEnd  question/plan asked → caller cancels the ACP turn
  * @param {(model: string, tokens: number, window?: number) => void} [opts.onContextSnapshot]
+ * @param {(text: string) => void} [opts.onPromptSuggestion] predicted next user prompt (harness-provided, arrives after the turn's result)
  */
 /**
  * Permission policy for `request_permission`: build mode allows everything
@@ -239,7 +255,7 @@ export function permissionPolicy({ isPlanMode = false, isArtifactWriter = false,
   };
 }
 
-export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onContextSnapshot, mcpServerIds = {}, readPlanFile = () => "", allowTool = () => true }) {
+export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onContextSnapshot, onPromptSuggestion, mcpServerIds = {}, readPlanFile = () => "", allowTool = () => true }) {
   /** toolCallId → { name, input, parent, emitted } */
   const tools = new Map();
   /** MCP server keys whose `connected` status already went out. */
@@ -269,6 +285,14 @@ export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onC
   let planEmitted = false;
   let lastPlanMarkdown = "";
   let lastUsage = null; // { used, size, costUsd }
+  /** Harness-predicted next user prompt (null until one arrives). */
+  let promptSuggestion = null;
+  /** Resolvers parked by waitForPromptSuggestion. */
+  const suggestionWaiters = [];
+  const settleSuggestion = (text) => {
+    promptSuggestion = text;
+    for (const resolve of suggestionWaiters.splice(0)) resolve(text);
+  };
 
   const flushThought = () => {
     const t = thoughtBuffer.trim();
@@ -482,12 +506,25 @@ export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onC
           }
           return;
         }
+        case "session_info_update": {
+          // Harness-agnostic extension point: an adapter that predicts
+          // the user's next prompt rides it in `_meta.kai.promptSuggestion`
+          // (claude-agent-acp via tools/patch-claude-acp.mjs today; a
+          // codex adapter could do the same tomorrow). Title/updatedAt
+          // stay ignored — the dashboard owns the session title.
+          const text = update._meta?.kai?.promptSuggestion;
+          if (typeof text === "string" && text.trim()) {
+            const clean = text.trim();
+            settleSuggestion(clean);
+            onPromptSuggestion?.(clean);
+          }
+          return;
+        }
         case "compaction_update":
         case "compaction_summary_chunk":
         case "current_mode_update":
         case "config_option_update":
         case "available_commands_update":
-        case "session_info_update":
         case "user_message_chunk":
         case "plan_update":
         case "plan_removed":
@@ -507,9 +544,26 @@ export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onC
       const toolCall = params?.toolCall ?? {};
       const name = toolNameFromUpdate(toolCall);
       const input = toolCall.rawInput ?? null;
-      if (handleTurnEndingTool(name, input)) return null;
       const options = Array.isArray(params?.options) ? params.options : [];
       const pick = (kind) => options.find((o) => o?.kind === kind)?.optionId;
+      // Codex's native plan mode ends with "Implement this plan?" — and
+      // codex-acp asks the CLIENT: a "yes" switches to default mode and
+      // runs the implementation inside the same prompt. We auto-allowed
+      // it like any unknown permission, so Codex implemented during plan
+      // turns (2026-09-06). Gleap owns that question (the dashboard's plan
+      // card): capture the plan, end the turn, answer no.
+      const planReview = isPlanMode ? planReviewText(params) : null;
+      if (planReview !== null) {
+        if (!planEmitted) {
+          planEmitted = true;
+          flushThought();
+          flushText();
+          emit({ type: "plan", message: planReview || lastText });
+        }
+        onTurnShouldEnd?.("plan");
+        return pick("reject_once") ?? pick("reject_always") ?? "__reject__";
+      }
+      if (handleTurnEndingTool(name, input)) return null;
       if (!allowTool(name, input)) {
         emit({
           type: "tool_status",
@@ -548,6 +602,28 @@ export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onC
       return true;
     },
 
+    /**
+     * The harness's predicted next prompt, or null once `timeoutMs`
+     * passes without one. The SDK emits it AFTER the turn's result (a
+     * background request on the warm cache), and emits nothing at all
+     * when it skips (plan mode, errors, usage limit) — hence the cap.
+     */
+    waitForPromptSuggestion(timeoutMs) {
+      if (promptSuggestion) return Promise.resolve(promptSuggestion);
+      return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          const i = suggestionWaiters.indexOf(settle);
+          if (i >= 0) suggestionWaiters.splice(i, 1);
+          resolve(null);
+        }, Math.max(0, Number(timeoutMs) || 0));
+        const settle = (text) => {
+          clearTimeout(timer);
+          resolve(text);
+        };
+        suggestionWaiters.push(settle);
+      });
+    },
+
     /** End-of-turn bookkeeping; returns what the runner needs for `result`. */
     finish() {
       flushThought();

package/runner/lib/acp/providerError.mjs

@@ -0,0 +1,83 @@
+// A backend rejection the ACP adapter forwarded as prose.
+//
+// codex-acp streams a non-retryable app-server error (an HTTP 4xx from
+// the Responses API: unknown model, bad request, model gated behind a
+// newer CLI) as a plain agent text chunk — `${message}\n\n`, where
+// `message` is the raw JSON envelope — and then ends the turn normally.
+// Without this the runner took that text for the agent's answer; in
+// plan mode it BECAME the plan and the dashboard asked "Implement this
+// plan?" over `{"type":"error","status":400,…}` (found live 2026-09-06:
+// gpt-6-astra on a bundled Codex CLI too old for it).
+
+/**
+ * The provider error hidden in the agent's final text, or `null` when
+ * the text is a real answer. Only the LAST paragraph decides: the CLI's
+ * own "Warning: …" lines ride ahead of the envelope, while an error the
+ * agent quoted and then worked past is still an answer.
+ */
+export function extractProviderError(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  const paragraphs = text.trim().split(/\n\s*\n/);
+  const candidate = paragraphs[paragraphs.length - 1].trim();
+  if (!candidate.startsWith("{") || !candidate.endsWith("}")) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(candidate);
+  } catch {
+    return null; // prose that happens to sit in braces
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.type !== "error")
+    return null;
+  const inner =
+    parsed.error && typeof parsed.error === "object" ? parsed.error : parsed;
+  const message =
+    typeof inner.message === "string" && inner.message.trim()
+      ? inner.message.trim()
+      : candidate;
+  const status = Number.isInteger(parsed.status)
+    ? parsed.status
+    : Number.isInteger(inner.status)
+      ? inner.status
+      : null;
+  const code =
+    inner !== parsed && typeof inner.type === "string"
+      ? inner.type
+      : typeof inner.code === "string"
+        ? inner.code
+        : null;
+  return { message, status, code };
+}
+
+/**
+ * What the teammate can DO about it. The provider's own text is written
+ * for people running the CLI by hand ("upgrade the latest app or CLI") —
+ * on a paired machine the CLI is bundled with Kai Bridge, so the fix is
+ * the bridge, not Codex. Null when there is no known remedy.
+ */
+export function adviseProviderError(error) {
+  const text = `${error.message} ${error.code ?? ""}`;
+  if (/newer version of codex|upgrade .*(app|cli)/i.test(text)) {
+    return (
+      "This model needs a newer Codex than the one bundled with Kai Bridge on this machine. " +
+      "Kai Bridge updates itself when idle (0.2.6 and later) — give it a few minutes and retry, " +
+      "or run `npm i -g @gleapai/kai-bridge@latest` there. Or pick a model from this machine's list."
+    );
+  }
+  if (error.status === 401 || /unauthori[sz]ed|not logged in|login required|invalid.*(token|api key)/i.test(text)) {
+    return "The Codex login on this machine has expired — run `kai-bridge login` there, then retry.";
+  }
+  if (error.status === 404 || /model.*(not found|does not exist|unknown|unsupported)|unknown model/i.test(text)) {
+    return "This machine's Codex does not know that model — pick one from this machine's list.";
+  }
+  if (error.status === 429 || /rate limit|too many requests|usage limit/i.test(text)) {
+    return "The ChatGPT account on this machine is rate-limited — wait for the window to reset or run in Gleap Cloud.";
+  }
+  return null;
+}
+
+/** One line for the dashboard's failed-turn row: what happened, then what to do. */
+export function describeProviderError(error) {
+  const where = error.status ? ` (HTTP ${error.status})` : "";
+  const advice = adviseProviderError(error);
+  return `The model provider rejected the request${where}: ${error.message}${advice ? ` ${advice}` : ""}`;
+}

package/runner/tools/patch-claude-acp.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Patch `@agentclientprotocol/claude-agent-acp` so the Agent SDK's
+// `prompt_suggestion` message (the predicted next user prompt Claude
+// Code shows as ghost text in its own composer) reaches the runner.
+//
+// Upstream (≤ 0.75.1) drops the message on the floor — `case
+// "prompt_suggestion": break;` — because ACP has no update kind for it.
+// We forward it as a `session_info_update` carrying `_meta.kai
+// .promptSuggestion` (ACP's sanctioned extension point; the SDK's
+// zod schema allows an arbitrary `_meta` record), which the mapper
+// turns into the `prompt_suggestion` contract event.
+//
+// Idempotent and loud: re-running on a patched build is a no-op, a
+// build whose source drifted from the expected shape exits 2 so the
+// image bake / bridge install notices instead of silently shipping a
+// harness that never suggests. The runner itself detects the patch by
+// the `PATCH_MARKER` string, so an unpatched adapter costs nothing but
+// the feature.
+//
+//   node patch-claude-acp.mjs [<node_modules root>]
+//   node patch-claude-acp.mjs --file <path/to/acp-agent.js>
+//   node patch-claude-acp.mjs --check [...]      exit 0 patched / 1 not
+//
+// Default root: the runner's own `node_modules`, then one level up
+// (the kai-bridge package's `node_modules`) — the same lookup order
+// `resolveAgentCommand` uses to find the adapter binary.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PATCH_MARKER = "[gleap:prompt-suggestion]";
+
+const UNPATCHED = /case "tool_use_summary":\s*\n(\s*)case "prompt_suggestion":\s*\n\s*break;/;
+
+/** Apply the patch to the adapter source. Returns `{ source, status }`. */
+export function patchClaudeAcpSource(source) {
+  if (typeof source !== "string") return { source, status: "invalid" };
+  if (source.includes(PATCH_MARKER)) return { source, status: "already" };
+  const match = UNPATCHED.exec(source);
+  if (!match) return { source, status: "unrecognized" };
+  const indent = match[1];
+  const replacement = [
+    `case "tool_use_summary":`,
+    `${indent}    break;`,
+    `${indent}case "prompt_suggestion":`,
+    `${indent}    // ${PATCH_MARKER} Forward the SDK's predicted next prompt as a`,
+    `${indent}    // session_info_update; the Kai runner reads _meta.kai.promptSuggestion.`,
+    `${indent}    if (typeof message.suggestion === "string" && message.suggestion.trim()) {`,
+    `${indent}        await this.client.sessionUpdate({`,
+    `${indent}            sessionId: params.sessionId,`,
+    `${indent}            update: { sessionUpdate: "session_info_update", _meta: { kai: { promptSuggestion: message.suggestion } } },`,
+    `${indent}        });`,
+    `${indent}    }`,
+    `${indent}    break;`,
+  ].join("\n");
+  return { source: source.replace(UNPATCHED, replacement), status: "patched" };
+}
+
+/** Locate `dist/acp-agent.js` under a node_modules root. */
+export function resolveAdapterFile(root) {
+  return join(root, "@agentclientprotocol", "claude-agent-acp", "dist", "acp-agent.js");
+}
+
+/** True when the adapter at `file` forwards prompt suggestions. */
+export function isClaudeAcpPatched(file) {
+  try {
+    return readFileSync(file, "utf8").includes(PATCH_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/** Patch the adapter on disk. Returns the status string. */
+export function patchClaudeAcpFile(file) {
+  if (!existsSync(file)) return "missing";
+  const before = readFileSync(file, "utf8");
+  const { source, status } = patchClaudeAcpSource(before);
+  if (status === "patched") writeFileSync(file, source);
+  return status;
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const argv = process.argv.slice(2);
+  const check = argv.includes("--check");
+  const fileIdx = argv.indexOf("--file");
+  let file = null;
+  if (fileIdx >= 0 && argv[fileIdx + 1]) {
+    file = resolve(argv[fileIdx + 1]);
+  } else {
+    const positional = argv.filter((a) => !a.startsWith("--"));
+    const runnerDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const roots = positional.length > 0 ? positional.map((p) => resolve(p)) : [join(runnerDir, "node_modules"), join(runnerDir, "..", "node_modules")];
+    file = roots.map(resolveAdapterFile).find((f) => existsSync(f)) ?? resolveAdapterFile(roots[0]);
+  }
+  if (check) {
+    const ok = isClaudeAcpPatched(file);
+    console.log(`[patch-claude-acp] ${ok ? "patched" : "NOT patched"}: ${file}`);
+    process.exit(ok ? 0 : 1);
+  }
+  const status = patchClaudeAcpFile(file);
+  console.log(`[patch-claude-acp] ${status}: ${file}`);
+  if (status === "unrecognized" || status === "missing" || status === "invalid") process.exit(2);
+}

package/scripts/postinstall.mjs

@@ -8,6 +8,14 @@
 //
 // MUST never fail or block an install: CI, docker builds, and dependency
 // installs all run this too.
+// Forward Claude Code's prompt suggestions through the bundled adapter
+// (upstream drops them). Best-effort — see src/acp-patch.mjs.
+try {
+  const { ensureClaudeAcpPatched } = await import("../src/acp-patch.mjs");
+  ensureClaudeAcpPatched();
+} catch {
+  // The daemon retries on start; a missing patch only means no suggestions.
+}
 try {
   const interactive = process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;
   const isGlobal = process.env.npm_config_global === "true";

package/src/acp-patch.mjs

@@ -0,0 +1,48 @@
+// Keep the bundled claude-agent-acp forwarding prompt suggestions.
+//
+// The Agent SDK predicts the user's next prompt after every turn; the
+// upstream adapter drops that message. The runner ships the patch
+// (runner/tools/patch-claude-acp.mjs) and applies it to the sandbox
+// image at bake time — on a device it has to be applied to THIS
+// package's node_modules instead, after every install (self-update
+// reinstalls the package) and, belt and braces, on daemon start. Always
+// best-effort: a read-only install just means no suggestions.
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+import { isClaudeAcpPatched, patchClaudeAcpFile } from "../runner/tools/patch-claude-acp.mjs";
+
+/** `dist/acp-agent.js` of the claude-agent-acp build this package resolves. */
+export function bundledClaudeAcpFile() {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
+    return join(dirname(pkg), "dist", "acp-agent.js");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Apply the patch if needed. Returns `{ file, status }` — status is
+ * `patched` | `already` | `missing` | `unrecognized` | `error`.
+ */
+export function ensureClaudeAcpPatched({ log } = {}) {
+  const file = bundledClaudeAcpFile();
+  if (!file) return { file: null, status: "missing" };
+  try {
+    const status = patchClaudeAcpFile(file);
+    if (status === "patched") log?.("info", "acp.patch.applied", { file });
+    else if (status !== "already") log?.("warn", "acp.patch.skipped", { file, status });
+    return { file, status };
+  } catch (err) {
+    log?.("warn", "acp.patch.failed", { file, error: err?.message ?? String(err) });
+    return { file, status: "error" };
+  }
+}
+
+/** True when the bundled adapter forwards prompt suggestions. */
+export function claudeAcpForwardsSuggestions() {
+  const file = bundledClaudeAcpFile();
+  return !!file && isClaudeAcpPatched(file);
+}

package/src/daemon.mjs

@@ -16,11 +16,12 @@ import { join, resolve as resolvePath } from "node:path";
 import { homedir, platform } from "node:os";
 
 import { BridgeApi, createEventBatcher } from "./api.mjs";
+import { ensureClaudeAcpPatched } from "./acp-patch.mjs";
 import { KAI_HOME, defaultConfig, loadConfig, saveConfig } from "./config.mjs";
 import { runTurn } from "./executor.mjs";
 import { createManagedProfile, describeProfiles, managedConfigDir, ambientConfigDir, openLoginTerminal, probeUsageLimits } from "./profiles.mjs";
 import { defaultRoots, groupByRepo, preferredCloneRoot, scanRoots, toDeviceRepoReport } from "./repos.mjs";
-import { collectChanges, commitAndPush, copyPrimaryEnvFiles, currentBranch, materializeBinding, sessionSlug, worktreePath, ensureCommitExcludes } from "./workspace.mjs";
+import { discardChanges, collectChanges, commitAndPush, copyPrimaryEnvFiles, currentBranch, materializeBinding, sessionSlug, worktreePath, ensureCommitExcludes } from "./workspace.mjs";
 import { ServiceRunner, detectDevConfig, previewMcpServer, readDevConfig } from "./preview.mjs";
 import { describeHarnesses, installHarness, probeHarnessAuth } from "./harnesses.mjs";
 import { probeHarnessModels } from "./models.mjs";
@@ -155,6 +156,10 @@ export class BridgeDaemon {
     // worktree — interleaved events, racing pushes, mangled diffs. Very
     // easy to hit: `kai-bridge install` and then `kai-bridge start`.
     this.acquireLock();
+    // The bundled claude-agent-acp must forward prompt suggestions
+    // (postinstall applies the patch; a self-update or --ignore-scripts
+    // install can leave it unpatched). Idempotent, best-effort.
+    ensureClaudeAcpPatched({ log: (level, event, data) => this.log(level, event, data) });
     // A previous run that was killed (reboot, crash, `kill -9`) never got
     // to report its turns. Tell the server before doing anything else,
     // so those sessions settle instead of spinning.
@@ -925,6 +930,21 @@ export class BridgeDaemon {
       const completed = !ctrl.signal.aborted && res.code === 0 && !res.rateLimited;
       const changes = [...bound, ...this.adoptSessionWorktrees(turn, bound)].map((b) => {
         ensureCommitExcludes(b.cwd, { allowDevConfig: !!turn.allowDevConfig });
+        // A plan turn must leave the worktree as it found it — see
+        // discardChanges. Local checkouts are the user's; only report.
+        if (turn.planMode) {
+          const leaked = b.mode === "worktree" ? discardChanges(b.cwd).discarded : collectChanges(b.cwd).files;
+          if (leaked.length > 0) {
+            this.log("warn", "plan.changes", { turnId, repo: b.key, mode: b.mode, files: leaked.length, discarded: b.mode === "worktree" });
+            batcher.push({
+              type: "text",
+              message:
+                b.mode === "worktree"
+                  ? `Plan mode is read-only — ${leaked.length} file change${leaked.length === 1 ? "" : "s"} made during planning ${leaked.length === 1 ? "was" : "were"} discarded; the build starts from the plan.`
+                  : `Plan mode is read-only, but ${leaked.length} file change${leaked.length === 1 ? "" : "s"} landed in your local checkout of ${b.key} — review them before building.`,
+            });
+          }
+        }
         const diff = collectChanges(b.cwd);
         // Build turns in worktree mode publish the session branch so the
         // Server can open the PR; plan turns and local mode never push.
@@ -940,6 +960,10 @@ export class BridgeDaemon {
         // work that stayed on this machine (files but no push).
         return { key: b.key, mode: b.mode, branch: b.branch, base: b.base, cwd: b.cwd, adopted: b.adopted || undefined, ...diff, push };
       });
+      // The plan-mode notices above were queued AFTER the post-turn
+      // flush; land them before the result closes the turn (the Server
+      // answers 410 for events on an ended turn).
+      await batcher.flush();
       // Built OUTSIDE the report call: if posting the result throws, the
       // catch below must not turn a finished turn into a failed one. The
       // work is already committed and pushed at this point.
@@ -996,7 +1020,9 @@ export class BridgeDaemon {
         notes.push(
           `\n\nNo .gleap/dev.yaml found in ${b.key}. If you figure out how this project's dev server runs, ` +
             `write .gleap/dev.yaml (services: { <name>: { cwd, run, port, health } }, preview: <name>) ` +
-            `so Gleap can run live previews for this repo in future sessions.`,
+            `so Gleap can run live previews for this repo in future sessions. This is optional housekeeping ` +
+            `for Gleap, not part of the task: it is committed separately, so never count it as work the user asked for ` +
+            `or mention it in your summary.`,
         );
       }
       if (!committed || !live) continue;

package/src/models.mjs

@@ -11,18 +11,23 @@
 //            (subscription tier, `availableModels` allowlist, gateway
 //            settings all applied by the CLI itself). Spawns the CLI
 //            (~2s), so never on hello's path — see the daemon's refresh.
-//   codex  — `<CODEX_HOME>/models_cache.json`, the model catalogue the
-//            Codex CLI fetches for the signed-in ChatGPT account. No
-//            spawn, plain file read.
+//   codex  — `codex debug models` from the BUNDLED CLI: the catalogue the
+//            backend serves for THIS client version under the signed-in
+//            ChatGPT account (spawns the CLI, ~1-2s). The profile's
+//            models_cache.json is only the fallback — another Codex (the
+//            ChatGPT app, a newer global CLI) writes it and lists models
+//            the bundled CLI cannot run yet.
 //   cursor — no catalogue surface; the dashboard keeps its static list.
 //
 // Ids are namespaced exactly like the Server's registry (`anthropic/…`,
 // `openai/…`) so the harness derivation, the BYO gate and the runner's
 // engine-slug derivation all keep working unchanged.
 
-import { existsSync, readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { promisify } from "node:util";
 import { harnessBinary } from "./harnesses.mjs";
 import { ambientConfigDir } from "./profiles.mjs";
 
@@ -168,7 +173,56 @@ export async function probeClaudeModels(configDir, kaiHome = process.env.KAI_HOM
   }
 }
 
-export function probeCodexModels(configDir) {
+const execFileAsync = promisify(execFile);
+
+/**
+ * Where the Codex catalogue probe runs. `codex debug models` needs a
+ * login, and CODEX_HOME must never be the user's real ~/.codex (the CLI
+ * writes its own cache + config there) — so a scratch home under
+ * ~/.kai/state seeded with a COPY of the profile's auth.json, the same
+ * rule the executor applies for turns.
+ */
+export function codexProbeHome(configDir, kaiHome) {
+  const home = join(kaiHome, "state", "models-probe", "codex");
+  mkdirSync(home, { recursive: true });
+  const auth = join(configDir, "auth.json");
+  if (existsSync(auth)) copyFileSync(auth, join(home, "auth.json"));
+  return home;
+}
+
+/**
+ * The bundled CLI's OWN catalogue: `codex debug models` renders the
+ * list the backend serves for THIS client version. The profile's
+ * models_cache.json is written by whichever Codex the user runs (the
+ * ChatGPT app, a newer global CLI) and can list models the bundled CLI
+ * cannot run yet — found live 2026-09-06: the picker offered
+ * gpt-6-astra, the turn died with "requires a newer version of Codex".
+ * `null` = the CLI could not answer (missing, signed out, timeout).
+ */
+export async function codexModelsFromCli(configDir, kaiHome, { timeoutMs = 30_000, exec = execFileAsync } = {}) {
+  const bin = harnessBinary("codex", kaiHome);
+  if (!bin) return null;
+  const env = { ...process.env, CODEX_HOME: codexProbeHome(configDir, kaiHome) };
+  delete env.OPENAI_API_KEY;
+  const { stdout } = await exec(bin, ["debug", "models"], { env, cwd: kaiHome, timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024 });
+  const parsed = JSON.parse(String(stdout));
+  const rows = codexModelsFromCache(parsed);
+  return rows.length ? rows : null;
+}
+
+/**
+ * Codex models under a login: the bundled CLI's own answer first, the
+ * profile's cache file only when the CLI cannot answer — never a list
+ * the CLI would then reject.
+ */
+export async function probeCodexModels(configDir, kaiHome = process.env.KAI_HOME || join(HOME, ".kai"), opts = {}) {
+  let fromCli = null;
+  try {
+    fromCli = await codexModelsFromCli(configDir, kaiHome, opts);
+  } catch {
+    fromCli = null;
+  }
+  if (fromCli) return fromCli;
   const cache = readCodexModelsCache(configDir);
   return cache ? codexModelsFromCache(cache) : null;
 }
@@ -181,6 +235,6 @@ export function probeCodexModels(configDir) {
  */
 export async function probeHarnessModels(harness, configDir, kaiHome, opts) {
   if (harness === "claude") return probeClaudeModels(configDir, kaiHome, opts);
-  if (harness === "codex") return probeCodexModels(configDir);
+  if (harness === "codex") return probeCodexModels(configDir, kaiHome, opts);
   return null;
 }

package/src/workspace.mjs

@@ -118,7 +118,12 @@ export function currentBranch(cwd) {
 
 /** Diff of what the turn changed (for the dashboard's file-changes panel). */
 export function collectChanges(cwd) {
-  const status = git(cwd, ["status", "--porcelain"]);
+  // NOT via git(): its trailing .trim() also strips the LEADING space of
+  // the first porcelain line, so a first entry that is a tracked
+  // modification (" M path") lost its space and every field shifted one
+  // char left — the file list reported to the Server read "EADME.md"
+  // (found 2026-09-06). Read raw; porcelain columns are fixed-width.
+  const status = execFileSync("git", ["status", "--porcelain"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
   const files = status
     .split("\n")
     .filter(Boolean)
@@ -127,6 +132,25 @@ export function collectChanges(cwd) {
   return { files, diff };
 }
 
+/**
+ * Throw away everything a turn left uncommitted — tracked edits and new
+ * files alike (ignored files stay: node_modules, .env copies). Plan
+ * turns are read-only by contract, but not every harness enforces it:
+ * codex-acp's "read-only" mode is a workspace-write sandbox that only
+ * asks before touching files OUTSIDE the workspace, and Codex went on to
+ * implement a whole ticket during its plan turn (2026-09-06). Whatever a
+ * plan turn changed is discarded here so the build turn starts from the
+ * base, exactly as the plan promised. Worktree mode only — a `local`
+ * binding is the user's own checkout and is never reset.
+ */
+export function discardChanges(cwd) {
+  const before = collectChanges(cwd).files;
+  if (before.length === 0) return { discarded: [] };
+  git(cwd, ["checkout", "--", "."]);
+  git(cwd, ["clean", "-fd"]);
+  return { discarded: before };
+}
+
 /** Drop a session's worktrees (after merge/close). */
 export function removeWorktree({ kaiHome, repo, sessionId, title }) {
   const dir = worktreePath(kaiHome, repo.name, sessionSlug(sessionId, title));