@koreanhole/opencodex 2.96.0 → 2.98.0

package/AGENTS_INSTALL.md

@@ -23,21 +23,34 @@ To use Gemini instead, authenticate it through its official CLI and select the
 provider:
 
 ```bash
-gemini   # official login or existing GEMINI_API_KEY configuration
+gemini   # configure a Gemini Developer API or Vertex AI API key
 ocx provider add gemini-cli --set-default
 ocx start
+ocx codex sync
 ```
 
+`ocx codex sync` refreshes the Codex app catalog with locally discovered Gemini
+models and reasoning levels. Restart the Codex app/app-server after refresh. The
+catalog file is written only when `model_catalog_json` names an opencodex catalog
+or through the documented default path; unrelated Codex settings are not changed.
+
 ## Credential rules
 
 - Use the operator's existing Cline or Gemini CLI sign-in. Do not copy vendor
-  tokens into config, environment files, logs, prompts, or package content.
+  tokens into config, environment files, logs, prompts, or package content. The
+  only exception is Cline's mode-0600 request-scoped staging copy.
 - Do not authenticate on a request path. If Cline reports `auth_required`, stop
   and ask the operator to run `ocx login cline-cli`.
-- Do not edit the operator's real Cline provider store unless the operator asks.
+- Do not edit the operator's real Cline provider store. Read it only to create a
+  mode-0600 request-scoped copy; remove that copy after the turn.
 - Do not import or replay Gemini OAuth/API-key material; the Gemini CLI remains
   the authentication authority.
-- The proxy writes only under `$OPENCODEX_HOME` (default `~/.opencodex`).
+- Third-party use must use a Gemini Developer API key or Vertex AI GenAI API key.
+  Gemini CLI's official FAQ identifies third-party use of its personal Google
+  OAuth authentication as a terms violation. OAuth is not a supported
+  opencodex setup path.
+- The proxy writes under `$OPENCODEX_HOME` (default `~/.opencodex`) and may update
+  the active opencodex Codex model catalog selected by `model_catalog_json`.
 
 ## Operation
 
@@ -59,6 +72,7 @@ bun run typecheck
 bun test tests/e2e/cline-only.test.ts
 bun run test:e2e:gemini
 bun run test:e2e:gemini-tool
+bun run test:e2e:gemini-reasoning
 ```
 
 Report whether each evidence path used a deterministic ACP fixture or a real

package/README.md

@@ -17,13 +17,23 @@ npm install -g cline
 cline auth
 
 npm install -g @google/gemini-cli
-gemini   # use the official login or configure GEMINI_API_KEY
+gemini   # configure GEMINI_API_KEY before using it through opencodex
 ```
 
+Cline must advertise ACP (`cline --help` includes `--acp`). opencodex uses ACP
+only and fails closed with `cline_acp_unsupported` for older one-shot-only
+builds.
+
 Gemini authentication remains in Gemini CLI's own home/settings. The proxy never
 copies, logs, or stores an API key, OAuth token, bearer token, or full request
 body.
 
+For third-party clients such as opencodex, use a Gemini Developer API key
+(Google AI Studio) or a Vertex AI GenAI API key. Do not use Gemini CLI's
+personal Google OAuth flow: Gemini CLI's official FAQ identifies third-party
+software piggybacking on its OAuth authentication as a terms violation and says
+the supported third-party method is an API key.
+
 ## Install
 
 ```bash
@@ -56,6 +66,7 @@ name = "opencodex (Cline or Gemini CLI)"
 base_url = "http://127.0.0.1:10100/v1"
 wire_api = "responses"
 requires_openai_auth = false
+model_catalog_url = "http://127.0.0.1:10100/v1/model-catalog"
 ```
 
 The model list is live. Cline ACP models are exposed as `cline-cli/<encoded-id>`;
@@ -63,6 +74,34 @@ Gemini ACP models are exposed as `gemini-cli/<encoded-id>`. Each provider keeps
 `default` selector. A provider prefix routes only to that vendor; unprefixed
 `default` uses the configured default provider.
 
+Gemini model IDs and reasoning ladders are discovered from the installed Gemini
+CLI. Thinking-capable models expose the locally supported levels; non-thinking
+models do not get an invented ladder. For a running Codex app, refresh the active
+catalog and reload the app/app-server:
+
+```bash
+bun run src/cli/index.ts codex sync
+```
+
+The command updates the root `model_catalog_json` target when it names an
+opencodex catalog, otherwise it writes `$CODEX_HOME/opencodex-catalog.json` and
+prints the activation setting. `model_catalog_url` avoids the file when the app
+catalog is fetched dynamically.
+
+Codex 0.165.0 can use the Responses WebSocket transport when the provider sets
+`supports_websockets = true` and the process is started with
+`--enable responses_websockets`. opencodex accepts the WebSocket on
+`/v1/responses`, handles the `generate=false` warmup, and maps the following
+`previous_response_id` onto the stored Gemini session. HTTP remains the fallback.
+
+Gemini context capacity, prompt modalities, and session-load support are
+discovered from the installed ACP agent at runtime; the proxy does not hardcode a
+model context window. A reusable Codex conversation uses
+`previous_response_id`, `prompt_cache_key`, or a documented conversation header
+to load the vendor session and send only the new input. Tool-use turns fall back
+to bounded replay because the vendor session is cancelled when a tool intent is
+captured.
+
 ## Claude Code
 
 ```bash
@@ -77,18 +116,28 @@ Use a `cline-cli/...` model to route the same Messages surface to Cline.
 ## Security boundary
 
 - Neither Cline nor Gemini receives filesystem or terminal capability from the proxy.
+- Cline turns use a request-scoped Cline home with built-in/plugin tools, hooks,
+  telemetry, updates, and automatic approval disabled. The real vendor provider
+  store is immutable; a mode-0600 copy inside the staged home lets the vendor CLI
+  refresh auth state and is removed after the turn.
 - Gemini native tools are removed by a per-turn deny policy; permission requests
   are cancelled, and no ACP filesystem/terminal client capabilities are advertised.
   User MCP servers, extensions, skills, and hooks are disabled for the session; only
   the isolated `opencodex` MCP catalog can receive a client tool call.
+- Gemini runs with a staged `GEMINI_CLI_HOME` under opencodex control; only the
+  minimum vendor auth files are linked from the real home, and staged session
+  state is bounded and reclaimed.
 - Declared client tools are exposed only through a request-scoped MCP process that
   records bounded intent and never executes; Codex owns approval and execution.
 - Vendor credentials remain in the vendor's real home or authenticated
-  environment. The proxy stores no vendor token.
+  environment. Cline's request-scoped copy is never logged or persisted beyond
+  the turn. The proxy stores no vendor token.
 - Request-path traffic never starts an interactive login.
 - The listener is loopback-only by default; a non-loopback listener requires an
   explicit API token.
-- Image, video, and audio input are rejected before a vendor process starts.
+- Image input is forwarded only when the selected Gemini model and ACP agent
+  advertise image capability; video and audio input are rejected before a vendor
+  process starts.
 
 ## Commands
 
@@ -114,6 +163,11 @@ bun test tests
 bun run test:e2e
 bun run test:e2e:gemini
 bun run test:e2e:gemini-tool
+bun run test:e2e:gemini-multiturn
+bun run test:e2e:gemini-previous-response
+bun run test:e2e:gemini-websocket
+bun run test:e2e:gemini-websocket-tool
+bun run test:e2e:gemini-reasoning
 bun run privacy:scan
 bun run structure:check
 ```
@@ -131,19 +185,44 @@ Codex's `exec_command`, Codex executes a fixed read-only `printf`, and Gemini
 returns the final answer. Both commands use no retries. Missing binaries,
 authentication, or a Flash Lite model cause a hard failure.
 
+`test:e2e:gemini-multiturn` starts a persisted real Codex session, resumes it with
+`codex exec resume`, and asserts that the proxy loads the Gemini session and
+sends only the new turn. Codex 0.165.0 sends `prompt_cache_key` for this path.
+
+`test:e2e:gemini-previous-response` sends a direct Responses continuation with
+`previous_response_id` and verifies that the proxy loads the stored Gemini
+session and sends only the new input.
+
+`test:e2e:gemini-websocket` and `test:e2e:gemini-websocket-tool` enable Codex's
+actual WebSocket transport with `supports_websockets = true` and
+`--enable responses_websockets`. They verify the `generate=false` warmup, the
+real request's non-empty `previous_response_id`, and the WebSocket tool loop.
+
+`test:e2e:gemini-reasoning` discovers a thinking-capable model and level from the
+local Gemini CLI, validates the refreshed Codex catalog, and runs one minimal
+reasoning-enabled turn. It fails when the authenticated account cannot execute
+the discovered model.
+
 Optional overrides are `CLINE_BIN_PATH`, `GEMINI_BIN_PATH`, and `CODEX_BIN_PATH`.
 
 ## Troubleshooting
 
 - **Cline not found**: install `cline` and verify `cline --help` works.
 - **Cline authentication required**: run `ocx login cline-cli`, then retry.
-- **Cline ACP unavailable**: the adapter falls back to the one-shot JSON path when
-  the model is `default`; native model selection requires ACP.
+- **Cline ACP unavailable**: opencodex no longer falls back to the one-shot JSON
+  path. Upgrade Cline so `cline --help` advertises `--acp`, or set
+  `OPENCODEX_CLINE_ACP=1`; otherwise requests fail with
+  `cline_acp_unsupported`.
 - **Gemini not found**: install it and verify `gemini --help` works, or set
   `GEMINI_BIN_PATH`.
-- **Gemini authentication required**: configure Gemini CLI's official login or API
-  key; do not pass the key to opencodex.
+- **Gemini authentication required**: configure a Gemini Developer API key or
+  Vertex AI API key for Gemini CLI; do not use personal Google OAuth with this
+  third-party proxy and do not pass the key to opencodex.
 - **Gemini ACP unavailable**: upgrade Gemini CLI to a version advertising `--acp`.
+- **Gemini Pro quota exhausted**: reasoning-capable models may require paid Pro
+  quota; the catalog stays accurate but that model cannot complete a live turn.
+- **Codex model picker is stale**: run `ocx codex sync`, then restart the Codex
+  app/app-server.
 - **Port in use**: choose another port with `ocx start --port <port>`.
 - **Stale runtime state**: run `ocx stop`; it removes stale state only when the
   recorded process and health endpoint cannot be verified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koreanhole/opencodex",
-  "version": "2.96.0",
+  "version": "2.98.0",
   "description": "Cline and Gemini CLI provider proxy for OpenAI Codex and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",
@@ -32,6 +32,11 @@
     "test:e2e": "bun test tests/e2e/cline-only.test.ts",
     "test:e2e:gemini": "bun test ./tests/e2e/gemini-codex.live.ts -t \"one minimal Flash Lite completion\"",
     "test:e2e:gemini-tool": "bun test ./tests/e2e/gemini-codex.live.ts -t \"one short Gemini tool call\"",
+    "test:e2e:gemini-multiturn": "bun test ./tests/e2e/gemini-codex.live.ts -t \"reuses a live Codex multi-turn session\"",
+    "test:e2e:gemini-previous-response": "bun test ./tests/e2e/gemini-codex.live.ts -t \"loads a live Gemini session for a previous_response_id continuation\"",
+    "test:e2e:gemini-websocket": "bun test ./tests/e2e/gemini-codex.live.ts -t \"runs a live Codex WebSocket turn\"",
+    "test:e2e:gemini-websocket-tool": "bun test ./tests/e2e/gemini-codex.live.ts -t \"runs a live Codex WebSocket tool loop\"",
+    "test:e2e:gemini-reasoning": "bun test ./tests/e2e/gemini-reasoning.live.ts",
     "typecheck": "bun check --no-script --noEmit",
     "privacy:scan": "bun scripts/privacy-scan.ts",
     "structure:check": "bun scripts/structure-check.ts",

package/src/adapters/cli-agent/acp-client.ts

@@ -49,9 +49,19 @@ export interface AcpAuthMethod {
   description?: string;
 }
 
+export interface AcpAgentCapabilities {
+  loadSession: boolean;
+  prompt: {
+    image: boolean;
+    audio: boolean;
+    embeddedContext: boolean;
+  };
+}
+
 export interface AcpInitialize {
   protocolVersion: number;
   authMethods: readonly AcpAuthMethod[];
+  capabilities: AcpAgentCapabilities;
   agentVersion?: string;
 }
 
@@ -224,7 +234,21 @@ export function parseAcpInitialize(
     : [];
   const agentInfo = asRecord(result.agentInfo);
   const agentVersion = nonEmpty(agentInfo?.version, 256);
-  return { protocolVersion: version, authMethods, ...(agentVersion ? { agentVersion } : {}) };
+  const agentCapabilities = asRecord(result.agentCapabilities);
+  const promptCapabilities = asRecord(agentCapabilities?.promptCapabilities);
+  return {
+    protocolVersion: version,
+    authMethods,
+    capabilities: {
+      loadSession: agentCapabilities?.loadSession === true,
+      prompt: {
+        image: promptCapabilities?.image === true,
+        audio: promptCapabilities?.audio === true,
+        embeddedContext: promptCapabilities?.embeddedContext === true,
+      },
+    },
+    ...(agentVersion ? { agentVersion } : {}),
+  };
 }
 
 function acpError(error: unknown, fallbackAllowed: boolean, label: string): AcpError {
@@ -443,6 +467,32 @@ export class AcpClient {
     }
   }
 
+  async loadSession(params: {
+    sessionId: string;
+    cwd: string;
+    mcpServers: readonly Record<string, unknown>[];
+  }): Promise<AcpSessionInfo> {
+    try {
+      const response = await deadline(
+        this.connection.request<unknown>(acp.AGENT_METHODS.session_load, {
+          sessionId: params.sessionId,
+          cwd: params.cwd,
+          mcpServers: params.mcpServers.slice(0, MAX_MCP_SERVERS),
+        }),
+        this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        () => this.terminate(),
+        this.label,
+        this.fallbackAllowed,
+      );
+      const session = parseAcpSession(response, this.label, this.fallbackAllowed);
+      this.sessionId = session.sessionId;
+      return session;
+    } catch (error) {
+      if (error instanceof AcpError) throw error;
+      throw acpError(error, this.fallbackAllowed, this.label);
+    }
+  }
+
   async setModel(sessionId: string, modelId: string): Promise<void> {
     await deadline(
       this.connection.request("session/set_model", { sessionId, modelId }),
@@ -499,11 +549,18 @@ export class AcpClient {
     });
   }
 
-  async prompt(sessionId: string, text: string, cancellationSignal?: AbortSignal): Promise<acp.PromptResponse> {
+  async prompt(
+    sessionId: string,
+    content: string | readonly acp.ContentBlock[],
+    cancellationSignal?: AbortSignal,
+  ): Promise<acp.PromptResponse> {
+    const prompt = typeof content === "string"
+      ? [{ type: "text" as const, text: content }]
+      : content;
     return await deadline(
       this.connection.request(
         acp.AGENT_METHODS.session_prompt,
-        { sessionId, prompt: [{ type: "text" as const, text }] },
+        { sessionId, prompt },
         { ...(cancellationSignal ? { cancellationSignal } : {}) },
       ),
       this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,

package/src/adapters/cli-agent/cline/acp.ts

@@ -522,7 +522,6 @@ export async function runClineAcpTurn(
   let client: AcpClient | undefined;
   let session: ClineAcpSessionInfo | undefined;
   let terminalEmitted = false;
-  let sawOutput = false;
   let safetyError: string | undefined;
   let aborted = false;
   let timedOut = false;
@@ -531,10 +530,6 @@ export async function runClineAcpTurn(
   const seenToolCalls = new Set<string>();
 
   const deliver = (event: AdapterEvent): void => {
-    if (event.type === "text_delta" || event.type === "thinking_delta"
-      || event.type === "tool_call_start" || event.type === "tool_call_delta" || event.type === "tool_call_end") {
-      sawOutput = true;
-    }
     if (event.type === "done" || event.type === "error" || event.type === "incomplete") {
       if (terminalEmitted) return;
       terminalEmitted = true;
@@ -593,7 +588,7 @@ export async function runClineAcpTurn(
   };
 
   try {
-    client = await AcpClient.connect({ binary: input.binary, env: input.env, cwd: input.cwd, hooks, label: "Cline ACP", fallbackAllowed: true, ...(input.args ? { args: input.args } : {}) }, deps);
+    client = await AcpClient.connect({ binary: input.binary, env: input.env, cwd: input.cwd, hooks, label: "Cline ACP", fallbackAllowed: false, ...(input.args ? { args: input.args } : {}) }, deps);
     session = await client.newSession({ cwd: input.cwd, mcpServers: input.mcpServers });
     await applyClineAcpModel(client, session, input.modelId);
 
@@ -677,7 +672,6 @@ export async function runClineAcpTurn(
       });
     }
   } catch (error) {
-    if (error instanceof AcpError && error.fallbackAllowed && !sawOutput) throw error;
     if (!terminalEmitted) {
       const failure = timedOut
         ? new ClineAcpError("Cline ACP turn timed out.", 504, "upstream_error", "timeout", true, false)

package/src/adapters/cli-agent/cline/adapter.ts

@@ -1,19 +1,14 @@
 import { fileURLToPath } from "node:url";
-import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
 import type { AdapterEvent, IncomingMeta, OcxParsedRequest } from "../../../types";
 import { buildCodingAgentToolCatalog, CodingAgentToolCatalogError } from "../../tool-catalog";
 import { buildConversationInput, buildSystemPrompt } from "../protocol";
 import { whichFromPath, type WhichFn } from "../../coding-agent/profile";
 import { isStandaloneBinary } from "../../../lib/standalone";
-import { runCliAgentTurn } from "../turn";
 import type { CliAgentTurnDeps } from "../types";
 import {
   assertClineAdvisoryDestinationSafe,
   buildClineChildEnv,
   ClineSettingsError,
-  mergeClineDisabledTools,
-  preflightClineTools,
   resolveClineProviderSettingsPath,
   stageClineTurn,
   type ClineStagedTurn,
@@ -23,12 +18,9 @@ import {
   buildClineAcpEnv,
   probeClineAcpSupport,
   runClineAcpTurn,
-  stageClineAcpWorkspace,
   type ClineAcpDeps,
-  type ClineAcpMode,
   type ClineAcpTurnInput,
 } from "./acp";
-import { classifyClineFailure, createClineStreamState, mapClineMessage } from "./stream";
 import { AcpError } from "../acp-client";
 
 export const CLINE_CLI_BASE_URL = "https://api.cline.bot";
@@ -50,9 +42,7 @@ export interface ClineTurnDeps extends CliAgentTurnDeps {
   env?: NodeJS.ProcessEnv;
   providerSettingsPath?: string;
   stageTurn?: typeof stageClineTurn;
-  preflightTools?: typeof preflightClineTools;
   probeAcp?: typeof probeClineAcpSupport;
-  stageAcp?: typeof stageClineAcpWorkspace;
   runAcp?: (input: ClineAcpTurnInput, emit: (event: AdapterEvent) => void, deps?: ClineAcpDeps) => Promise<void>;
   acpDeps?: ClineAcpDeps;
 }
@@ -92,10 +82,6 @@ export function buildClinePrompt(
   ].filter(Boolean).join("\n\n");
 }
 
-export function buildClineArgs(): string[] {
-  return ["--json", "Follow the piped conversation and instructions."];
-}
-
 function toolNameMap(catalog: ReturnType<typeof buildCodingAgentToolCatalog>): Map<string, string> {
   const names = new Map<string, string>();
   for (const [vendorName, wireName] of catalog.emittedNameMap) {
@@ -192,12 +178,14 @@ export async function runClineTurn(
     return;
   }
 
-  const vendorNames = toolNameMap(catalog);
-  const vendorNameByWire = new Map([...catalog.emittedNameMap.values()].map(wireName => [
-    wireName,
-    wireName.startsWith("opencodex__") ? wireName : `opencodex__${wireName}`,
-  ]));
-  const fixedSystem = systemPromptWithToolNames(catalog);
+  const providerSettingsPath = deps.providerSettingsPath ?? resolveClineProviderSettingsPath(sourceEnv);
+  try {
+    await assertClineAdvisoryDestinationSafe(providerSettingsPath);
+  } catch (error) {
+    emit(settingsError(error));
+    return;
+  }
+
   const acpDeps: ClineAcpDeps = {
     ...deps.acpDeps,
     env: sourceEnv,
@@ -209,153 +197,68 @@ export async function runClineTurn(
     ...(deps.killWindowsProcessTree ? { killWindowsProcessTree: deps.killWindowsProcessTree } : {}),
   };
   const acpEnv = buildClineAcpEnv(sourceEnv);
-  let acpMode: ClineAcpMode = { acp: false };
+  let acpMode: { acp: boolean; autoApproveFlag?: boolean } = { acp: false };
   try {
     acpMode = await (deps.probeAcp ?? probeClineAcpSupport)(binary, acpEnv, acpDeps);
   } catch {
     acpMode = { acp: false };
   }
-
-  if (acpMode.acp) {
-    let workspace: Awaited<ReturnType<typeof stageClineAcpWorkspace>> | undefined;
-    try {
-      workspace = await (deps.stageAcp ?? stageClineAcpWorkspace)(catalog.tools);
-      const mcpServers = workspace.catalogPath && catalog.emittedNameMap.size > 0
-        ? [{
-            type: "stdio",
-            name: CLINE_MCP_SERVER_NAME,
-            command: process.execPath,
-            args: isStandaloneBinary() ? ["__cli-agent-mcp", workspace.catalogPath] : [CLINE_MCP_SERVER_PATH, workspace.catalogPath],
-            env: [],
-          }]
-        : [];
-      let acpOutput = false;
-      const acpEmit = (event: AdapterEvent): void => {
-        if (event.type === "text_delta" || event.type === "thinking_delta"
-          || event.type === "tool_call_start" || event.type === "tool_call_delta" || event.type === "tool_call_end") {
-          acpOutput = true;
-        }
-        emit(event);
-      };
-      try {
-        await (deps.runAcp ?? runClineAcpTurn)({
-          binary,
-          env: acpEnv,
-          cwd: workspace.cwd,
-          modelId: requestedModel,
-          prompt: buildClinePrompt(parsed, vendorNameByWire, fixedSystem),
-          toolNames: vendorNames,
-          mcpServers,
-          args: acpMode.autoApproveFlag ? ["--acp", "--auto-approve", "false"] : ["--acp"],
-          maxToolCalls: 16,
-          requireToolCall: catalog.requireToolCall,
-          incoming,
-          deps: acpDeps,
-        }, acpEmit, acpDeps);
-        return;
-      } catch (error) {
-        if (!(error instanceof AcpError && error.fallbackAllowed && !acpOutput && requestedModel === "default")) {
-          emit(acpFailure(error));
-          return;
-        }
-        if (error.authRequired) {
-          console.warn("[opencodex] Cline ACP authentication required [code=acp_auth_required]; using one-shot fallback.");
-        } else {
-          console.warn("[opencodex] Cline ACP unavailable; using one-shot fallback.");
-        }
-      }
-    } finally {
-      await workspace?.cleanup();
-    }
-  }
-
-  if (requestedModel !== CLINE_CLI_MODEL_ID) {
-    emit({ type: "error", message: `Cline ACP is required to select model "${requestedModel}". Enable ACP or use the default model.`, status: 400, errorType: "invalid_request_error", code: "cline_model_unsupported", retryable: false });
-    return;
-  }
-
-  const providerSettingsPath = deps.providerSettingsPath ?? resolveClineProviderSettingsPath(sourceEnv);
-  try {
-    await assertClineAdvisoryDestinationSafe(providerSettingsPath);
-  } catch (error) {
-    emit(settingsError(error));
-    return;
-  }
-
-  const mcpLaunch = catalog.emittedNameMap.size > 0
-    ? (isStandaloneBinary()
-      ? { kind: "entrypoint" as const, entrypoint: "__cli-agent-mcp" }
-      : { kind: "module" as const, modulePath: CLINE_MCP_SERVER_PATH })
-    : undefined;
-  let staged: ClineStagedTurn;
-  try {
-    staged = await (deps.stageTurn ?? stageClineTurn)({
-      providerSettingsPath,
-      catalog: catalog.tools,
-      ...(mcpLaunch ? { mcpLaunch } : {}),
-    });
-  } catch (error) {
-    emit(settingsError(error));
-    return;
-  }
-
-  const env = buildClineChildEnv(staged, sourceEnv);
-  const preflightTools = deps.preflightTools ?? preflightClineTools;
-  let preflight = await preflightTools({ binary, env, cwd: staged.workspaceDir });
-  if (!preflight.ok && preflight.enabledTools && preflight.enabledTools.length > 0) {
-    try {
-      await mergeClineDisabledTools(staged, preflight.enabledTools.map(tool => tool.id));
-    } catch (error) {
-      await staged.cleanup();
-      emit(settingsError(error));
-      return;
-    }
-    preflight = await preflightTools({ binary, env, cwd: staged.workspaceDir });
-  }
-  if (!preflight.ok) {
-    await staged.cleanup();
+  if (!acpMode.acp) {
     emit({
       type: "error",
-      message: preflight.detail || "Cline tool preflight failed.",
-      status: 502,
-      errorType: "upstream_error",
-      code: preflight.unsupported ? "cline_tool_preflight_unsupported" : "cline_tool_preflight_failed",
+      message: "The installed Cline CLI does not advertise --acp. Upgrade Cline or enable ACP.",
+      status: 400,
+      errorType: "invalid_request_error",
+      code: "cline_acp_unsupported",
       retryable: false,
     });
     return;
   }
 
-  const state = createClineStreamState();
-  const promptFile = join(staged.root, "prompt.txt");
+  const vendorNames = toolNameMap(catalog);
+  const vendorNameByWire = new Map([...catalog.emittedNameMap.values()].map(wireName => [
+    wireName,
+    wireName.startsWith("opencodex__") ? wireName : `opencodex__${wireName}`,
+  ]));
+  const fixedSystem = systemPromptWithToolNames(catalog);
+  let staged: ClineStagedTurn | undefined;
   try {
-    await writeFile(promptFile, buildClinePrompt(parsed, vendorNameByWire, fixedSystem), {
-      encoding: "utf8",
-      mode: 0o600,
-      flag: "wx",
+    staged = await (deps.stageTurn ?? stageClineTurn)({
+      providerSettingsPath,
+      catalog: catalog.tools,
     });
-  } catch {
-    await staged.cleanup();
-    emit({ type: "error", message: "Cline prompt could not be staged securely.", status: 500, errorType: "upstream_error", code: "cli_prompt_staging_failed", retryable: false });
-    return;
-  }
-
-  await runCliAgentTurn({
-    label: "Cline CLI",
-    binary,
-    args: buildClineArgs(),
-    env,
-    cwd: staged.workspaceDir,
-    stdin: "",
-    stdinFile: promptFile,
-    state,
-    requireToolCall: catalog.requireToolCall,
-    classifyFailure: ({ exitCode, stderr }) => classifyClineFailure(exitCode, stderr),
-    parseLine: (message, current) => mapClineMessage(message, current, {
+    const env = buildClineChildEnv(staged, sourceEnv);
+    const mcpServers = catalog.emittedNameMap.size > 0
+      ? [{
+          type: "stdio",
+          name: CLINE_MCP_SERVER_NAME,
+          command: process.execPath,
+          args: isStandaloneBinary()
+            ? ["__cli-agent-mcp", staged.catalogPath]
+            : [CLINE_MCP_SERVER_PATH, staged.catalogPath],
+          env: [],
+        }]
+      : [];
+    await (deps.runAcp ?? runClineAcpTurn)({
+      binary,
+      env,
+      cwd: staged.workspaceDir,
+      modelId: requestedModel,
+      prompt: buildClinePrompt(parsed, vendorNameByWire, fixedSystem),
       toolNames: vendorNames,
+      mcpServers,
+      args: acpMode.autoApproveFlag ? ["--acp", "--auto-approve", "false"] : ["--acp"],
       maxToolCalls: 16,
-    }),
-    cleanup: staged.cleanup,
-  }, incoming, emit, deps);
+      requireToolCall: catalog.requireToolCall,
+      incoming,
+      deps: acpDeps,
+    }, emit, acpDeps);
+  } catch (error) {
+    if (error instanceof ClineSettingsError) emit(settingsError(error));
+    else emit(acpFailure(error));
+  } finally {
+    await staged?.cleanup();
+  }
 }
 
 export { resolveClineBinary } from "./binary";