@peakflo/agent-harness 0.2.9-rc.4 → 0.2.9-rc.5

package/README.md

@@ -98,6 +98,33 @@ about what a third-party program prints.
 `PF_HARNESS_DISCOVERY=0`. The runner then starts none of these programs and
 reports no list. Running turns with Pi is not affected.
 
+## Permission modes on Codex, Claude Code and Cursor
+
+An agent's permission mode is applied by the runner for each turn. A vendor
+harness never runs with fewer questions than the mode asks for; where a mode
+cannot be honoured exactly, the runner uses the stricter behaviour.
+
+| Agent's mode             | Codex                                                                                         | Claude Code                                  | Cursor                                                                    |
+| ------------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
+| Ask before each action   | Asks before every command it does not know to be read-only                                    | Asks before every tool that needs permission | Runs in Cursor's read-only "Ask" mode: reads and answers, changes nothing |
+| Accept edits             | Same as "Ask before each action"                                                              | Same as "Ask before each action"             | Same as "Ask before each action"                                          |
+| Plan only                | Read-only sandbox; asks before a command that would write, and a command you approve does run | Claude Code's own plan mode                  | Runs in Cursor's read-only "Plan" mode                                    |
+| Don't ask for permission | Runs without asking                                                                           | Runs without asking                          | Runs without asking; each request Cursor raises is approved once          |
+
+Cursor is read-only in the asking modes because it asks only about commands
+that are not on the allow-list in its own settings (`~/.cursor/cli-config.json`).
+The runner does not read or change that file, so it cannot promise a question
+before each action. If Cursor will not accept the read-only mode, the turn is
+refused.
+
+The runner never answers a request with "always allow", and does not offer
+that answer to the person approving: Codex and Cursor would save it as a
+standing rule in their own configuration.
+
+Cursor reports an account limit as a normal reply ("Upgrade your plan to
+continue"). The runner turns a reply that is only that sentence into a failed
+turn that says it comes from the Cursor account on the runner.
+
 ## Troubleshooting
 
 **`npx @peakflo/agent-harness` fails with a 404.** Your `~/.npmrc` maps the

package/dist/adapter-resolver.d.ts

@@ -30,6 +30,16 @@ export declare function stopAtTurnEnd<T extends CodingAgentAdapter>(adapter: T,
      * (`agent-response-1`). See `pollMessages` below.
      */
     partIdsRestartEveryProcess?: boolean;
+    /**
+     * The vendor's way of saying "this account cannot run the turn" when it
+     * says so in the model's own reply and ends the turn normally. See
+     * `pollMessages` and `getStatus` below.
+     */
+    accountLimit?: {
+        isReply: (text: string | undefined) => boolean;
+        mayBecomeReply: (text: string | undefined) => boolean;
+        error: string;
+    };
 }): T;
 /**
  * A random id for THIS runner's vendor sessions, written once into the

package/dist/adapter-resolver.js

@@ -8,6 +8,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const adapters_1 = require("./adapters");
+const cursor_acp_1 = require("./adapters/cursor-acp");
 const vendor_backends_1 = require("./vendor-backends");
 /**
  * Hand the vendor CLI the workspace by its REAL path.
@@ -65,6 +66,24 @@ function stopAtTurnEnd(adapter, instanceId, options = {}) {
             () => instanceId;
     }
     const started = new Map();
+    /**
+     * BOUNDED. This runs between a turn's last part and the release of its
+     * lease; a vendor CLI that will not die must not hold that up.
+     */
+    const stopSession = async (sessionId, config) => {
+        try {
+            await Promise.race([
+                adapter.destroySession(sessionId, config),
+                new Promise((resolve) => {
+                    const timer = setTimeout(resolve, exports.STOP_TIMEOUT_MS);
+                    timer.unref();
+                })
+            ]);
+        }
+        catch {
+            // Teardown is best-effort; the next id still gets its turn.
+        }
+    };
     const realIds = new Map();
     const createSession = adapter.createSession.bind(adapter);
     const resumeSession = adapter.resumeSession.bind(adapter);
@@ -79,7 +98,20 @@ function stopAtTurnEnd(adapter, instanceId, options = {}) {
         // started the process.
         setRealWorkspacePath(config);
         started.set(sessionId, config);
-        return resumeSession(sessionId, config);
+        try {
+            return await resumeSession(sessionId, config);
+        }
+        catch (error) {
+            /*
+             * A FAILED RESUME LEAVES NOTHING RUNNING. The runner answers a failed
+             * resume by starting a new session on this same adapter. Seen with
+             * Cursor: the first process was still alive when the second was asked
+             * for `session/new`, and that request timed out.
+             */
+            await stopSession(sessionId, config);
+            started.delete(sessionId);
+            throw error;
+        }
     };
     /*
      * A PART WITH NO ROLE IS THE ASSISTANT'S — the rule 20x applies where it
@@ -110,6 +142,46 @@ function stopAtTurnEnd(adapter, instanceId, options = {}) {
         parts: new Set(),
         lengths: new Map()
     };
+    /*
+     * AN ACCOUNT LIMIT THAT ARRIVES AS AN ANSWER IS A FAILED TURN.
+     *
+     * Cursor reports its plan limit by sending "Upgrade your plan to continue"
+     * as the assistant's reply and ending the turn normally, so the chat showed
+     * a completed turn whose answer was a billing notice. When the WHOLE reply
+     * is that notice it is kept out of the transcript and the turn ends with an
+     * error that names where it comes from.
+     *
+     * The reply arrives in pieces. While it could still become the notice it is
+     * held back, so no half of the notice is stored; as soon as it cannot, it
+     * goes through as usual. A turn that ends on a held reply that is not the
+     * notice (an answer that is only "Upgrade") gets one more poll to hand it
+     * over — nothing a model said is ever dropped.
+     */
+    // ONE TURN'S STATE. `createAdapterResolver` builds and wraps a new adapter
+    // for every turn, so what is held or answered here never carries over to
+    // the next turn of the same chat.
+    const accountLimit = options.accountLimit;
+    const held = new Map();
+    const answered = new Set();
+    let flushHeld = false;
+    const holdBack = (part) => {
+        if (!accountLimit || !part.id)
+            return false;
+        if (part.type !== adapters_1.MessagePartType.TEXT)
+            return false;
+        if (part.role !== adapters_1.MessageRole.ASSISTANT)
+            return false;
+        if (accountLimit.mayBecomeReply(part.text)) {
+            held.set(part.id, part);
+            return true;
+        }
+        // It grew past the notice: a real answer. `update` is cleared because the
+        // runner never saw the earlier pieces.
+        if (held.delete(part.id))
+            part.update = false;
+        answered.add(part.id);
+        return false;
+    };
     const pollMessages = adapter.pollMessages.bind(adapter);
     adapter.pollMessages = async (...args) => {
         const scoped = options.partIdsRestartEveryProcess === true;
@@ -117,6 +189,11 @@ function stopAtTurnEnd(adapter, instanceId, options = {}) {
         const parts = scoped
             ? await pollMessages(args[0], ownSeen.messages, ownSeen.parts, ownSeen.lengths, args[4])
             : await pollMessages(...args);
+        const kept = flushHeld ? [...held.values()] : [];
+        if (flushHeld) {
+            held.clear();
+            flushHeld = false;
+        }
         for (const part of parts) {
             if (scoped && turnId && part.id)
                 part.id = `${turnId}:${part.id}`;
@@ -126,8 +203,25 @@ function stopAtTurnEnd(adapter, instanceId, options = {}) {
             // `createSession` returned. See `checkpointSessionId` below.
             if (part.realSessionId)
                 realIds.set(args[0], part.realSessionId);
+            if (holdBack(part))
+                continue;
+            kept.push(part);
         }
-        return parts;
+        return kept;
+    };
+    const getStatus = adapter.getStatus.bind(adapter);
+    adapter.getStatus = async (...args) => {
+        const status = await getStatus(...args);
+        if (status.type !== adapters_1.SessionStatusType.IDLE || held.size === 0) {
+            return status;
+        }
+        const onlyTheNotice = answered.size === 0 &&
+            [...held.values()].every((part) => accountLimit?.isReply(part.text));
+        if (onlyTheNotice) {
+            return { type: adapters_1.SessionStatusType.ERROR, message: accountLimit?.error };
+        }
+        flushHeld = true;
+        return { type: adapters_1.SessionStatusType.BUSY };
     };
     /*
      * The session id to SAVE for the next turn. Claude Code's real id arrives on
@@ -138,20 +232,7 @@ function stopAtTurnEnd(adapter, instanceId, options = {}) {
     adapter.stopServer =
         async () => {
             for (const [sessionId, config] of started) {
-                try {
-                    // BOUNDED. This runs between a turn's last part and the release of
-                    // its lease; a vendor CLI that will not die must not hold that up.
-                    await Promise.race([
-                        adapter.destroySession(sessionId, config),
-                        new Promise((resolve) => {
-                            const timer = setTimeout(resolve, exports.STOP_TIMEOUT_MS);
-                            timer.unref();
-                        })
-                    ]);
-                }
-                catch {
-                    // Teardown is best-effort; the next id still gets its turn.
-                }
+                await stopSession(sessionId, config);
             }
             started.clear();
         };
@@ -234,7 +315,16 @@ stateDir) {
             if (blocker) {
                 throw new Error(`Backend "${backend}" cannot run here. ${blocker}`);
             }
-            return stopAtTurnEnd(build(backend), instanceId ? `${backend}:${instanceId}` : null, { partIdsRestartEveryProcess: backend === 'cursor' });
+            return stopAtTurnEnd(build(backend), instanceId ? `${backend}:${instanceId}` : null, backend === 'cursor'
+                ? {
+                    partIdsRestartEveryProcess: true,
+                    accountLimit: {
+                        isReply: cursor_acp_1.isCursorPlanLimitReply,
+                        mayBecomeReply: cursor_acp_1.mayBecomeCursorPlanLimitReply,
+                        error: cursor_acp_1.CURSOR_PLAN_LIMIT_ERROR
+                    }
+                }
+                : {});
         }
         throw new Error(`Backend "${backend}" is not wired in this build. ` +
             'Available: pi, and on a desktop or self-hosted runner codex, ' +

package/dist/adapters/acp-adapter.d.ts

@@ -7,6 +7,13 @@
  */
 import type { CodingAgentAdapter, SessionConfig, SessionMessage, SessionStatus, MessagePart } from './coding-agent-adapter';
 export type AcpAgentType = 'codex' | 'cursor';
+/**
+ * How long the agent process may take to start and open a session. A cold
+ * `cursor-agent acp` took 26.7 s and then 34 s to answer `session/new` on a
+ * busy desktop; with the 30 s that every other request gets, the second one
+ * failed the turn with "Request timeout: session/new".
+ */
+export declare const ACP_SESSION_START_TIMEOUT_MS = 120000;
 interface AcpPermissionRequest {
     requestId: string | number;
     toolCallId: string;
@@ -152,6 +159,14 @@ export declare class AcpAdapter implements CodingAgentAdapter {
     private sendRpcResponse;
     private sendRpcNotification;
     private handlePermissionRequest;
+    /**
+     * Put a Cursor session into the mode the agent's permission mode requires,
+     * and select its model. See `cursor-acp.ts` for both mappings.
+     *
+     * The mode is not best-effort: when a read-only mode was asked for and
+     * Cursor does not accept it, this throws and the turn does not run.
+     */
+    private applyCursorSessionOptions;
     private extractAcpSessionId;
     /**
      * Convert internal McpServerConfig map to ACP-spec McpServer array.

package/dist/adapters/acp-adapter.js

@@ -7,13 +7,23 @@
  * Spec: https://github.com/agentclientprotocol/typescript-sdk
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AcpAdapter = void 0;
+exports.AcpAdapter = exports.ACP_SESSION_START_TIMEOUT_MS = void 0;
 /**
  * Extracted verbatim from 20x `src/main/adapters/acp-adapter.ts`.
  * CHANGED: imports only — `../child-stream-guards` ->
  * `../runtime/child-stream-guards`. The `app.asar` -> `app.asar.unpacked`
  * path rewrite is a plain string replace with no Electron import and is left
  * exactly as it was. Source formatting (no semicolons) preserved.
+ *
+ * CHANGED SINCE, for Cursor on a runner (rules in `./cursor-acp.ts`):
+ *   - starting the process and opening a session may take
+ *     `ACP_SESSION_START_TIMEOUT_MS`, not the 30 s of other requests
+ *   - a JSON-RPC error keeps `error.data.message` ("Session … not found")
+ *   - a failed `session/load` always stops its process
+ *   - the model is chosen from the session's own `model` option
+ *   - an asking permission mode puts Cursor in a read-only mode, or the turn
+ *     is refused; "always allow" is not offered to the person answering and
+ *     is not what a bypass turn answers with
  */
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
@@ -23,11 +33,24 @@ const os_1 = require("os");
 const path_1 = require("path");
 const util_1 = require("util");
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
+const cursor_acp_1 = require("./cursor-acp");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
-const CURSOR_ACP_MODEL_VALUES = {
-    'composer-2.5': 'composer-2.5[fast=true]',
-    'grok-4.5': 'grok-4.5[effort=high,fast=true]'
-};
+/**
+ * The ACP options known to answer ONE request (`allow_once`, `reject_once`).
+ * Anything else — "always", "for session", or a name nobody here has seen —
+ * is treated as a standing answer.
+ */
+function isStandingAcpOption(option) {
+    const oneTime = ['allow_once', 'reject_once', 'allow-once', 'reject-once'];
+    return !oneTime.includes(option.kind) && !oneTime.includes(option.optionId);
+}
+/**
+ * How long the agent process may take to start and open a session. A cold
+ * `cursor-agent acp` took 26.7 s and then 34 s to answer `session/new` on a
+ * busy desktop; with the 30 s that every other request gets, the second one
+ * failed the turn with "Request timeout: session/new".
+ */
+exports.ACP_SESSION_START_TIMEOUT_MS = 120_000;
 /**
  * Unified ACP adapter for all ACP-compatible agents
  */
@@ -338,7 +361,7 @@ class AcpAdapter {
                 name: 'pf-desktop',
                 version: '0.0.1'
             }
-        });
+        }, exports.ACP_SESSION_START_TIMEOUT_MS);
         // Authenticate if required
         await this.authenticateSession(session, initResult);
         // Create ACP session (only accepts cwd and mcpServers per ACP spec)
@@ -347,7 +370,7 @@ class AcpAdapter {
         const result = await this.sendRpcRequest(session, 'session/new', {
             cwd: config.workspaceDir,
             mcpServers: convertedMcpServers
-        });
+        }, exports.ACP_SESSION_START_TIMEOUT_MS);
         // Extract session ID from result
         const acpSessionId = this.extractAcpSessionId(result);
         if (acpSessionId) {
@@ -356,12 +379,23 @@ class AcpAdapter {
             this.sessions.delete(sessionId);
             this.sessions.set(acpSessionId, session);
         }
+        if (this.agentType === 'cursor' && acpSessionId) {
+            try {
+                await this.applyCursorSessionOptions(session, acpSessionId, config, result);
+            }
+            catch (error) {
+                // The turn must not run in a mode nobody chose. Stop the process too:
+                // a session that is refused here is never destroyed by its caller.
+                acpProcess.kill('SIGTERM');
+                this.sessions.delete(acpSessionId);
+                this.sessions.delete(sessionId);
+                throw error;
+            }
+        }
         // Set model if specified
-        if (config.model && acpSessionId) {
+        if (config.model && acpSessionId && this.agentType !== 'cursor') {
             try {
-                const modelValue = this.agentType === 'cursor'
-                    ? CURSOR_ACP_MODEL_VALUES[config.model] ?? config.model
-                    : config.model;
+                const modelValue = config.model;
                 await this.sendRpcRequest(session, 'session/set_config_option', {
                     sessionId: acpSessionId,
                     configId: 'model',
@@ -490,17 +524,22 @@ class AcpAdapter {
                 name: 'pf-desktop',
                 version: '0.0.1'
             }
-        });
+        }, exports.ACP_SESSION_START_TIMEOUT_MS);
         // Authenticate if required
         await this.authenticateSession(session, initResult);
         // Try to load existing session
         try {
-            await this.sendRpcRequest(session, 'session/load', {
+            const loaded = await this.sendRpcRequest(session, 'session/load', {
                 sessionId: sessionId,
                 cwd: config.workspaceDir,
                 mcpServers: this.convertMcpServers(config.mcpServers) || []
-            });
+            }, exports.ACP_SESSION_START_TIMEOUT_MS);
             console.log(`[AcpAdapter/${this.agentType}] Session loaded successfully: ${sessionId}`);
+            if (this.agentType === 'cursor') {
+                // A loaded session starts in Cursor's own default mode and model, so
+                // both are set again for this turn.
+                await this.applyCursorSessionOptions(session, sessionId, config, loaded);
+            }
             // Convert replayed notifications (buffered during session/load) to SessionMessages.
             // Without this, the renderer sees status:'idle' + messages:[] and hides the panel.
             const messages = await this.getAllMessages(sessionId, config);
@@ -512,10 +551,12 @@ class AcpAdapter {
         catch (error) {
             // Check if session not found
             const errMsg = error instanceof Error ? error.message : String(error);
+            // Whatever the reason, this process is of no further use: the caller
+            // starts a new session in a new process. Left running, it kept the
+            // agent's store open while the replacement tried to start.
+            acpProcess.kill('SIGTERM');
+            this.sessions.delete(sessionId);
             if (errMsg.includes('not found') || errMsg.includes('does not exist')) {
-                // Clean up process
-                acpProcess.kill('SIGTERM');
-                this.sessions.delete(sessionId);
                 throw new Error(`INCOMPATIBLE_SESSION_ID: This ${this.agentType} session does not exist or has expired. Please start a new session.`);
             }
             // Re-throw other errors
@@ -860,7 +901,7 @@ class AcpAdapter {
                     if (errorInfo) {
                         this.handleQuotaError(session, errorInfo);
                     }
-                    pending.reject(new Error(response.error.message));
+                    pending.reject(new Error((0, cursor_acp_1.describeAcpRpcError)(response.error)));
                 }
                 else if ('result' in response) {
                     pending.resolve(response.result);
@@ -1117,7 +1158,7 @@ class AcpAdapter {
             session.permanentMessages.splice(0, Math.ceil(AcpAdapter.MAX_PERMANENT_MESSAGES * 0.25));
         }
     }
-    async sendRpcRequest(session, method, params) {
+    async sendRpcRequest(session, method, params, timeoutMs = 30000) {
         const id = session.nextRequestId++;
         const request = {
             jsonrpc: '2.0',
@@ -1142,7 +1183,7 @@ class AcpAdapter {
                     session.pendingRequests.delete(id);
                     reject(new Error(`Request timeout: ${method}`));
                 }
-            }, 30000);
+            }, timeoutMs);
         });
     }
     sendRpcRequestNoWait(session, method, params) {
@@ -1204,17 +1245,51 @@ class AcpAdapter {
         console.log(`  Question: ${question}`);
         console.log(`  Tool: ${toolCall?.kind} - ${toolCall?.toolCallId}`);
         console.log(`  Options: ${options.map((o) => `${o.name} (${o.optionId})`).join(', ')}`);
-        const approvalOptions = options.map((o) => ({
+        const allApprovalOptions = options.map((o) => ({
             optionId: o.optionId,
             name: o.name,
             kind: o.kind
         }));
+        // "Always allow" answers more than this one request and Cursor saves it in
+        // its own config on the runner. A person answering from the control plane
+        // is offered the one-time answers only.
+        const oneTimeOptions = allApprovalOptions.filter((option) => !isStandingAcpOption(option));
+        const approvalOptions = this.agentType === 'cursor' && session.config.permissionMode !== 'allow' && oneTimeOptions.length > 0
+            ? oneTimeOptions
+            : allApprovalOptions;
         if (session.config.permissionMode === 'allow') {
+            // Cursor saves "allow always" as a standing rule in the runner owner's
+            // `~/.cursor/cli-config.json` (seen: one bypass turn added `Shell(echo)`
+            // and `Shell(cat)`), which would then also apply to turns that are meant
+            // to ask. Every request is approved once instead.
+            if (this.agentType === 'cursor') {
+                const once = approvalOptions.find((option) => option.optionId === 'allow-once')
+                    || approvalOptions.find((option) => option.kind === 'allow_once');
+                if (!once) {
+                    // Only standing answers on offer. Bypass means "do not ask", not
+                    // "write rules into the owner's Cursor settings": refuse this one.
+                    const reject = approvalOptions.find((option) => option.kind === 'reject_once' || option.optionId === 'reject-once');
+                    console.warn(`[AcpAdapter/cursor] Permission request offers no one-time approval; refusing it`);
+                    this.sendRpcResponse(session, request.id, {
+                        result: {
+                            outcome: reject
+                                ? { outcome: 'selected', optionId: reject.optionId }
+                                : { outcome: 'cancelled' }
+                        }
+                    });
+                    return;
+                }
+                console.log(`[AcpAdapter/cursor] Auto-approving permission with: ${once.optionId}`);
+                this.sendRpcResponse(session, request.id, {
+                    result: { outcome: { outcome: 'selected', optionId: once.optionId } }
+                });
+                return;
+            }
             const autoApprovedOptionId = approvalOptions.find((option) => option.optionId === 'approved-for-session')?.optionId
                 || approvalOptions.find((option) => option.optionId === 'allow-always')?.optionId
                 || approvalOptions.find((option) => option.optionId === 'approved')?.optionId
                 || approvalOptions.find((option) => option.optionId === 'allow-once')?.optionId
-                || (this.agentType === 'cursor' ? 'allow-once' : 'approved');
+                || 'approved';
             console.log(`[AcpAdapter/${this.agentType}] Auto-approving permission with: ${autoApprovedOptionId}`);
             this.sendRpcResponse(session, request.id, {
                 result: {
@@ -1237,6 +1312,53 @@ class AcpAdapter {
         session.status = coding_agent_adapter_1.SessionStatusType.WAITING_APPROVAL;
         console.log(`[AcpAdapter/${this.agentType}] Awaiting user approval...`);
     }
+    /**
+     * Put a Cursor session into the mode the agent's permission mode requires,
+     * and select its model. See `cursor-acp.ts` for both mappings.
+     *
+     * The mode is not best-effort: when a read-only mode was asked for and
+     * Cursor does not accept it, this throws and the turn does not run.
+     */
+    async applyCursorSessionOptions(session, acpSessionId, config, sessionResult) {
+        const mode = (0, cursor_acp_1.cursorModeFor)(config);
+        const modeValue = (0, cursor_acp_1.resolveCursorModeValue)(mode, sessionResult) ?? mode;
+        try {
+            await this.sendRpcRequest(session, 'session/set_config_option', {
+                sessionId: acpSessionId,
+                configId: 'mode',
+                value: modeValue
+            });
+            console.log(`[AcpAdapter/cursor] Mode set to: ${modeValue}`);
+        }
+        catch (error) {
+            const errMsg = error instanceof Error ? error.message : String(error);
+            if (mode !== 'agent') {
+                throw new Error(`Cursor did not accept its read-only "${mode}" mode (${errMsg}). The agent's ` +
+                    'permission mode asks before actions, which Cursor can only honour in a ' +
+                    'read-only mode, so this turn was not run.');
+            }
+            console.warn(`[AcpAdapter/cursor] Failed to set mode ${modeValue}: ${errMsg}`);
+        }
+        const modelValue = (0, cursor_acp_1.resolveCursorModelValue)(config.model, sessionResult);
+        if (!modelValue) {
+            if (config.model) {
+                console.log(`[AcpAdapter/cursor] Model "${config.model}" is not offered by this session; Cursor keeps its default`);
+            }
+            return;
+        }
+        try {
+            await this.sendRpcRequest(session, 'session/set_config_option', {
+                sessionId: acpSessionId,
+                configId: 'model',
+                value: modelValue
+            });
+            console.log(`[AcpAdapter/cursor] Model set to: ${modelValue}`);
+        }
+        catch (error) {
+            const errMsg = error instanceof Error ? error.message : String(error);
+            console.warn(`[AcpAdapter/cursor] Failed to set model ${modelValue}: ${errMsg}`);
+        }
+    }
     extractAcpSessionId(result) {
         if (!result || typeof result !== 'object')
             return null;

package/dist/adapters/claude-code-adapter.d.ts

@@ -90,6 +90,31 @@ export declare class ClaudeCodeAdapter implements CodingAgentAdapter {
     private loadSessionHistory;
     resumeSession(sessionId: string, config: SessionConfig): Promise<SessionMessage[]>;
     sendPrompt(sessionId: string, parts: MessagePart[], config: SessionConfig): Promise<void>;
+    /**
+     * Questions waiting for a person, oldest first, per session. Claude can ask
+     * about several tools at once (parallel tool use); they are answered one at
+     * a time, in the order they were asked, and none is answered by a reply
+     * that was meant for another.
+     */
+    private pendingToolApprovals;
+    private askToolApproval;
+    /**
+     * Refuse every question still waiting for this session. Called when the
+     * turn is aborted or the session is destroyed, so no tool is left waiting
+     * on an answer that can no longer come — whether or not the SDK passed an
+     * abort signal with the question.
+     */
+    private denyPendingToolApprovals;
+    getPendingApproval(sessionId: string): {
+        toolCallId: string;
+        question: string;
+        options: Array<{
+            optionId: string;
+            name: string;
+            kind: string;
+        }>;
+    } | null;
+    respondToApproval(sessionId: string, approved: boolean, optionId?: string): Promise<boolean>;
     getStatus(sessionId: string, _config: SessionConfig): Promise<SessionStatus>;
     /**
      * Exposes in-flight background subagents as "running tools" so agent-manager's

package/dist/adapters/claude-code-adapter.js

@@ -702,7 +702,18 @@ class ClaudeCodeAdapter {
             // the mode above decorative in exactly the way G1 was.
             ...(claudePermissionMode === 'bypassPermissions'
                 ? { allowDangerouslySkipPermissions: true }
-                : {}),
+                : {
+                    /*
+                     * ADDED, not in 20x. In every mode that asks, the SDK calls this
+                     * before a tool that needs permission. Without it the SDK has
+                     * nobody to ask and DENIES the tool: nothing unsafe runs, but
+                     * "Ask before each action" asked nobody and refused everything.
+                     * The question is held here until the runner brings the person's
+                     * answer (`getPendingApproval` / `respondToApproval`, the same
+                     * two methods the Codex and ACP adapters have).
+                     */
+                    canUseTool: (toolName, input, extra) => this.askToolApproval(sessionId, toolName, input, extra?.signal)
+                }),
             ...(secretHooks ? { hooks: secretHooks } : {}),
         };
         // Determine session continuation mode
@@ -804,6 +815,92 @@ class ClaudeCodeAdapter {
         // Start consuming stream
         session.streamTask = this.consumeStream(sessionId, session);
     }
+    /* ---------------------------------------------------------------------- */
+    /* Tool approvals (ADDED, not in 20x) — see `canUseTool` in startQuery       */
+    /* ---------------------------------------------------------------------- */
+    /**
+     * Questions waiting for a person, oldest first, per session. Claude can ask
+     * about several tools at once (parallel tool use); they are answered one at
+     * a time, in the order they were asked, and none is answered by a reply
+     * that was meant for another.
+     */
+    pendingToolApprovals = new Map();
+    askToolApproval(sessionId, toolName, input, signal) {
+        return new Promise((resolve) => {
+            // The command, path or URL is shown in full: a person must not approve
+            // from a shortened view of what will run. Only the fallback, a dump of
+            // an unknown tool's whole input, is cut, and says so.
+            const dump = JSON.stringify(input ?? {});
+            const detail = typeof input?.command === 'string' ? input.command
+                : typeof input?.file_path === 'string' ? input.file_path
+                    : typeof input?.url === 'string' ? input.url
+                        : dump.length > 300 ? `${dump.slice(0, 300)}… (input shortened)` : dump;
+            const toolCallId = `claude-approval-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const onAbort = () => entry.settle(false, 'The turn was stopped before this action was approved.');
+            const entry = {
+                toolCallId,
+                question: `${toolName}: ${detail}`,
+                settle: (approved, reason) => {
+                    signal?.removeEventListener('abort', onAbort);
+                    const queue = this.pendingToolApprovals.get(sessionId) ?? [];
+                    const index = queue.indexOf(entry);
+                    if (index < 0)
+                        return; // already answered
+                    queue.splice(index, 1);
+                    if (queue.length === 0)
+                        this.pendingToolApprovals.delete(sessionId);
+                    if (approved)
+                        resolve({ behavior: 'allow', updatedInput: input });
+                    else
+                        resolve({ behavior: 'deny', message: reason ?? 'The user did not approve this action.' });
+                    // The next question in the queue, if any, is now the one to show.
+                    if (queue.length > 0)
+                        this.onDataAvailable?.(sessionId);
+                }
+            };
+            const queue = this.pendingToolApprovals.get(sessionId) ?? [];
+            queue.push(entry);
+            this.pendingToolApprovals.set(sessionId, queue);
+            if (signal?.aborted)
+                onAbort();
+            else
+                signal?.addEventListener('abort', onAbort, { once: true });
+            this.onDataAvailable?.(sessionId);
+        });
+    }
+    /**
+     * Refuse every question still waiting for this session. Called when the
+     * turn is aborted or the session is destroyed, so no tool is left waiting
+     * on an answer that can no longer come — whether or not the SDK passed an
+     * abort signal with the question.
+     */
+    denyPendingToolApprovals(sessionId, reason) {
+        for (const entry of [...(this.pendingToolApprovals.get(sessionId) ?? [])]) {
+            entry.settle(false, reason);
+        }
+        this.pendingToolApprovals.delete(sessionId);
+    }
+    getPendingApproval(sessionId) {
+        const pending = this.pendingToolApprovals.get(sessionId)?.[0];
+        if (!pending)
+            return null;
+        return {
+            toolCallId: pending.toolCallId,
+            question: pending.question,
+            options: [
+                { optionId: 'allow', name: 'Allow', kind: 'allow' },
+                { optionId: 'deny', name: 'Deny', kind: 'reject' }
+            ]
+        };
+    }
+    async respondToApproval(sessionId, approved, optionId) {
+        const pending = this.pendingToolApprovals.get(sessionId)?.[0];
+        if (!pending)
+            return false;
+        // Only an explicit allow allows. A reply naming any other option denies.
+        pending.settle(approved && (optionId === undefined || optionId === 'allow'));
+        return true;
+    }
     async getStatus(sessionId, _config) {
         const session = this.sessions.get(sessionId);
         if (!session) {
@@ -887,6 +984,7 @@ class ClaudeCodeAdapter {
         session.enqueuePrompt = null;
         session.backgroundTasks.clear();
         session.abortController?.abort();
+        this.denyPendingToolApprovals(sessionId, 'The turn was stopped before this action was approved.');
         // Wait for stream to finish cleanup
         if (session.streamTask) {
             console.log(`[ClaudeCodeAdapter] Waiting for stream cleanup...`);
@@ -912,6 +1010,7 @@ class ClaudeCodeAdapter {
         session.enqueuePrompt = null;
         session.backgroundTasks.clear();
         session.abortController?.abort();
+        this.denyPendingToolApprovals(sessionId, 'The session was closed before this action was approved.');
         // Wait for stream task to complete
         if (session.streamTask) {
             try {
@@ -1221,6 +1320,9 @@ class ClaudeCodeAdapter {
         }
         finally {
             console.log('[ClaudeCodeAdapter] Stream consumption ended');
+            // ADDED, not in 20x: the stream that asked is gone (ended, failed or the
+            // process exited), so no answer can reach it. Nothing may stay queued.
+            this.denyPendingToolApprovals(sessionId, 'The turn ended before this action was approved.');
             // Always reset queryIterator when the stream ends (process exited).
             // Previously only error paths did this, leaving a truthy-but-exhausted
             // iterator after normal completion.  That caused the next sendPrompt to

package/dist/adapters/codex-app-server-adapter.d.ts

@@ -6,6 +6,30 @@
  * 20x's CodingAgentAdapter contract.
  */
 import type { CodingAgentAdapter, SessionConfig, SessionStatus, SessionMessage, MessagePart } from './coding-agent-adapter';
+/**
+ * `thread/items/list` returns each item inside an envelope:
+ * `{ turnId, item: { type: 'userMessage', … }, startedAtMs, completedAtMs }`.
+ * Read as an item, the envelope has no `type`, no role and no text, so it fell
+ * through to the "unknown item is a tool call" branch and the transcript showed
+ * a "tool / tool" card holding the echoed prompt as JSON after every reply.
+ */
+export declare function unwrapListedThreadItem(entry: unknown): unknown;
+/** A decision that approves more than the one request it answers, or may. */
+export declare function isStandingApprovalDecision(optionId: string): boolean;
+/**
+ * CHANGED from 20x, which sends `on-request` for every mode but "allow".
+ *
+ * `on-request` leaves it to the MODEL to ask, and it asks only when it wants
+ * to leave the sandbox. Inside a workspace-write sandbox that is never: Codex
+ * created files and ran shell commands with no prompt at all while the agent
+ * was set to "Ask before each action". Seen on staging and reproduced.
+ *
+ * `untrusted` is Codex's own "ask first" policy: commands on its short list of
+ * read-only ones (ls, cat, ...) run, and everything else — any other command,
+ * any file change — is sent to the client as an approval request before it
+ * runs. That is what "Ask before each action" says.
+ */
+export declare function codexApprovalPolicy(config: Pick<SessionConfig, 'permissionMode'>): 'never' | 'untrusted';
 interface PendingApproval {
     requestId: string | number;
     toolCallId: string;

package/dist/adapters/codex-app-server-adapter.js

@@ -41,6 +41,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodexAppServerAdapter = void 0;
+exports.unwrapListedThreadItem = unwrapListedThreadItem;
+exports.isStandingApprovalDecision = isStandingApprovalDecision;
+exports.codexApprovalPolicy = codexApprovalPolicy;
 /**
  * Extracted verbatim from 20x `src/main/adapters/codex-app-server-adapter.ts`.
  * CHANGED: imports only — `../child-stream-guards` ->
@@ -55,6 +58,60 @@ const path_1 = require("path");
 const util_1 = require("util");
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
 const DEFAULT_CODEX_APP_SERVER_MODEL = 'gpt-5.5';
+/**
+ * `thread/items/list` returns each item inside an envelope:
+ * `{ turnId, item: { type: 'userMessage', … }, startedAtMs, completedAtMs }`.
+ * Read as an item, the envelope has no `type`, no role and no text, so it fell
+ * through to the "unknown item is a tool call" branch and the transcript showed
+ * a "tool / tool" card holding the echoed prompt as JSON after every reply.
+ */
+function unwrapListedThreadItem(entry) {
+    if (!isObject(entry))
+        return entry;
+    if (asString(entry.type))
+        return entry;
+    return isObject(entry.item) ? entry.item : entry;
+}
+/**
+ * The decisions that answer ONE request and nothing more. A list of what is
+ * known to be safe, not of what is known to be unsafe: a decision Codex adds
+ * later (one that remembers a rule under a name nobody here has seen) is
+ * treated as standing until someone adds it here. The cost of that: a new
+ * ONE-TIME decision from Codex is also hidden until it is added; the withheld
+ * names are logged by `handleApprovalRequest` so that is visible.
+ */
+const ONE_TIME_APPROVAL_DECISIONS = new Set([
+    'accept',
+    'approved',
+    'decline',
+    'denied',
+    'cancel',
+    'abort'
+]);
+/** A decision that approves more than the one request it answers, or may. */
+function isStandingApprovalDecision(optionId) {
+    return !ONE_TIME_APPROVAL_DECISIONS.has(optionId);
+}
+/**
+ * CHANGED from 20x, which sends `on-request` for every mode but "allow".
+ *
+ * `on-request` leaves it to the MODEL to ask, and it asks only when it wants
+ * to leave the sandbox. Inside a workspace-write sandbox that is never: Codex
+ * created files and ran shell commands with no prompt at all while the agent
+ * was set to "Ask before each action". Seen on staging and reproduced.
+ *
+ * `untrusted` is Codex's own "ask first" policy: commands on its short list of
+ * read-only ones (ls, cat, ...) run, and everything else — any other command,
+ * any file change — is sent to the client as an approval request before it
+ * runs. That is what "Ask before each action" says.
+ */
+function codexApprovalPolicy(config) {
+    // `'allow'` is what `mapPermissionMode` makes of the agent's
+    // `bypassPermissions` ("Don't ask for permission"), and of nothing else.
+    // Only an explicit "allow" runs without asking. Anything else, including a
+    // value this build does not know, asks.
+    return config.permissionMode === 'allow' ? 'never' : 'untrusted';
+}
 const MAX_IPC_TOOL_INPUT_CHARS = 20_000;
 const MAX_IPC_TOOL_OUTPUT_CHARS = 100_000;
 const MIN_THREAD_LEVEL_ASSISTANT_DEDUPE_CHARS = 40;
@@ -269,7 +326,7 @@ class CodexAppServerAdapter {
         const result = await this.sendRpcRequest(session, 'thread/start', {
             cwd: config.workspaceDir,
             model: config.model || DEFAULT_CODEX_APP_SERVER_MODEL,
-            approvalPolicy: config.permissionMode === 'allow' ? 'never' : 'on-request',
+            approvalPolicy: codexApprovalPolicy(config),
             approvalsReviewer: 'user',
             sandbox: this.resolveSandboxMode(config),
             developerInstructions: config.systemPrompt || null,
@@ -295,7 +352,7 @@ class CodexAppServerAdapter {
             threadId: sessionId,
             cwd: config.workspaceDir,
             model: config.model || DEFAULT_CODEX_APP_SERVER_MODEL,
-            approvalPolicy: config.permissionMode === 'allow' ? 'never' : 'on-request',
+            approvalPolicy: codexApprovalPolicy(config),
             approvalsReviewer: 'user',
             sandbox: this.resolveSandboxMode(config),
             runtimeWorkspaceRoots: this.buildRuntimeWorkspaceRoots(config.workspaceDir),
@@ -347,7 +404,7 @@ class CodexAppServerAdapter {
             cwd: config.workspaceDir,
             model: config.model || DEFAULT_CODEX_APP_SERVER_MODEL,
             effort: config.reasoningEffort && config.reasoningEffort !== 'max' ? config.reasoningEffort : null,
-            approvalPolicy: config.permissionMode === 'allow' ? 'never' : 'on-request',
+            approvalPolicy: codexApprovalPolicy(config),
             approvalsReviewer: 'user',
             sandbox: this.resolveSandboxMode(config),
             sandboxPolicy: this.buildSandboxPolicy(config),
@@ -827,7 +884,17 @@ class CodexAppServerAdapter {
         }
         const toolCallId = asString(params.approvalId) || asString(params.itemId) || asString(params.callId) || String(request.id);
         const responseKind = this.getApprovalResponseKind(request.method);
-        const rawDecisions = Array.isArray(params.availableDecisions) ? params.availableDecisions : [];
+        // A decision that also writes a standing rule ("…WithExecpolicyAmendment",
+        // "…ForSession") would let one click approve later commands nobody saw, and
+        // the amendment is saved into the Codex config on the runner. Offer only
+        // the decisions known to answer this one request; the rest are logged.
+        const offered = Array.isArray(params.availableDecisions) ? params.availableDecisions : [];
+        const rawDecisions = offered
+            .filter((decision) => !isStandingApprovalDecision(normalizeDecisionName(decision)));
+        if (rawDecisions.length !== offered.length) {
+            const withheld = offered.map(normalizeDecisionName).filter(isStandingApprovalDecision);
+            console.log(`[CodexAppServerAdapter] Not offering approval decisions: ${withheld.join(', ')}`);
+        }
         const approvalOptions = rawDecisions.length > 0
             ? rawDecisions.map((decision) => {
                 const optionId = normalizeDecisionName(decision);
@@ -922,8 +989,9 @@ class CodexAppServerAdapter {
     }
     bufferThreadItems(session, result) {
         const items = isObject(result) && Array.isArray(result.data) ? result.data : [];
-        for (const item of items) {
-            this.bufferReconciledThreadItem(session, item, isObject(item) ? asString(item.turnId) : undefined);
+        for (const entry of items) {
+            const turnId = isObject(entry) ? asString(entry.turnId) : undefined;
+            this.bufferReconciledThreadItem(session, unwrapListedThreadItem(entry), turnId);
         }
     }
     /**

package/dist/adapters/cursor-acp.d.ts

@@ -0,0 +1,84 @@
+/**
+ * What the runner has to know about Cursor's ACP agent (`cursor-agent acp`)
+ * that the generic ACP adapter does not: how a model is named on the wire,
+ * which Cursor mode a permission mode maps to, and how the account's plan
+ * limit shows up.
+ *
+ * Kept out of `acp-adapter.ts`, which is a copy of the 20x adapter, so the
+ * copy stays close to its source and these rules can be tested on their own.
+ */
+/** One entry of `configOptions` in a `session/new` or `session/load` result. */
+interface AcpConfigOption {
+    id: string;
+    values: Array<{
+        value: string;
+        name: string;
+    }>;
+}
+/** The `configOptions` of a session result, in a shape that is safe to read. */
+export declare function readAcpConfigOptions(sessionResult: unknown): AcpConfigOption[];
+/**
+ * The value to send in `session/set_config_option { configId: 'model' }` for
+ * the model an agent names, or null when the session offers nothing that
+ * matches — in which case nothing is sent and Cursor keeps its own default.
+ *
+ * WHY THIS IS NOT THE ID ITSELF. Cursor's ACP agent accepts only the values it
+ * lists in the session's own `model` option, and those carry parameters:
+ * `default[]` (shown as "Auto"), `composer-2.5[fast=true]`,
+ * `gpt-5.6-sol[context=272k,reasoning=medium,fast=false]`. The ids an agent
+ * holds come from `cursor-agent models` (`auto`, `composer-2.5`,
+ * `gpt-5.6-sol-medium`), which is a different list. Sending such an id gave
+ * `Failed to set model: Invalid params` on every turn, "Auto" included.
+ *
+ * Tried in order: the exact value, the option's display name, the part before
+ * `[`, then the longest such part the id starts with (`gpt-5.6-sol-medium`
+ * → `gpt-5.6-sol[…]`). `auto` is Cursor's `default`.
+ */
+export declare function resolveCursorModelValue(model: string | undefined, sessionResult: unknown): string | null;
+export type CursorMode = 'agent' | 'plan' | 'ask';
+/**
+ * The Cursor mode a turn must run in.
+ *
+ * FAIL CLOSED. In its `agent` mode Cursor asks only about commands that are
+ * not on the allow-list in the runner owner's `~/.cursor/cli-config.json`
+ * (seen: "Not in allowlist: cat, echo"). The runner must not read or change
+ * that list, so it cannot know which actions Cursor will run unasked, and a
+ * permission mode that promises a question before EACH action cannot be
+ * promised for Cursor. Every asking mode therefore runs
+ * Cursor in one of its own read-only modes — stricter than what was asked for,
+ * never looser:
+ *
+ *   plan                       → Cursor `plan` (reads and proposes a plan)
+ *   default, acceptEdits       → Cursor `ask`  (reads and answers, no changes)
+ *   bypassPermissions          → Cursor `agent` (the only mode that may act)
+ *
+ * A permission request Cursor does raise is still put to the person.
+ */
+export declare function cursorModeFor(config: {
+    permissionMode?: string;
+    sandboxMode?: string;
+}): CursorMode;
+/**
+ * The exact value of the session's `mode` option for a Cursor mode, or null
+ * when the session does not offer it. The caller must refuse the turn on null
+ * for a read-only mode rather than run in whatever mode Cursor starts in.
+ */
+export declare function resolveCursorModeValue(mode: CursorMode, sessionResult: unknown): string | null;
+/**
+ * Is this whole assistant reply Cursor's plan-limit notice?
+ *
+ * Cursor does not report its account limit as an error. It sends the sentence
+ * "Upgrade your plan to continue" as the model's answer and ends the turn
+ * normally. Matched on the WHOLE reply only, so an answer that merely quotes
+ * the sentence is left alone.
+ */
+export declare function isCursorPlanLimitReply(text: string | undefined): boolean;
+/** Could this partial reply still grow into the plan-limit notice? */
+export declare function mayBecomeCursorPlanLimitReply(text: string | undefined): boolean;
+export declare const CURSOR_PLAN_LIMIT_ERROR: string;
+/** `error.message`, plus `error.data.message` when the agent sent one. */
+export declare function describeAcpRpcError(error: {
+    message?: unknown;
+    data?: unknown;
+}): string;
+export {};

package/dist/adapters/cursor-acp.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * What the runner has to know about Cursor's ACP agent (`cursor-agent acp`)
+ * that the generic ACP adapter does not: how a model is named on the wire,
+ * which Cursor mode a permission mode maps to, and how the account's plan
+ * limit shows up.
+ *
+ * Kept out of `acp-adapter.ts`, which is a copy of the 20x adapter, so the
+ * copy stays close to its source and these rules can be tested on their own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURSOR_PLAN_LIMIT_ERROR = void 0;
+exports.readAcpConfigOptions = readAcpConfigOptions;
+exports.resolveCursorModelValue = resolveCursorModelValue;
+exports.cursorModeFor = cursorModeFor;
+exports.resolveCursorModeValue = resolveCursorModeValue;
+exports.isCursorPlanLimitReply = isCursorPlanLimitReply;
+exports.mayBecomeCursorPlanLimitReply = mayBecomeCursorPlanLimitReply;
+exports.describeAcpRpcError = describeAcpRpcError;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readOptionValues(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const values = [];
+    for (const entry of raw) {
+        if (!isRecord(entry))
+            continue;
+        // A grouped option list: `{ group, name, options: [...] }`.
+        if (Array.isArray(entry.options)) {
+            values.push(...readOptionValues(entry.options));
+            continue;
+        }
+        if (typeof entry.value !== 'string')
+            continue;
+        values.push({
+            value: entry.value,
+            name: typeof entry.name === 'string' ? entry.name : entry.value
+        });
+    }
+    return values;
+}
+/** The `configOptions` of a session result, in a shape that is safe to read. */
+function readAcpConfigOptions(sessionResult) {
+    if (!isRecord(sessionResult) || !Array.isArray(sessionResult.configOptions)) {
+        return [];
+    }
+    const options = [];
+    for (const entry of sessionResult.configOptions) {
+        if (!isRecord(entry) || typeof entry.id !== 'string')
+            continue;
+        options.push({ id: entry.id, values: readOptionValues(entry.options) });
+    }
+    return options;
+}
+function optionValues(sessionResult, id) {
+    return (readAcpConfigOptions(sessionResult).find((option) => option.id === id)
+        ?.values ?? []);
+}
+/** `composer-2.5[fast=true]` → `composer-2.5`. */
+function baseOf(value) {
+    const bracket = value.indexOf('[');
+    return (bracket >= 0 ? value.slice(0, bracket) : value).trim().toLowerCase();
+}
+/**
+ * The value to send in `session/set_config_option { configId: 'model' }` for
+ * the model an agent names, or null when the session offers nothing that
+ * matches — in which case nothing is sent and Cursor keeps its own default.
+ *
+ * WHY THIS IS NOT THE ID ITSELF. Cursor's ACP agent accepts only the values it
+ * lists in the session's own `model` option, and those carry parameters:
+ * `default[]` (shown as "Auto"), `composer-2.5[fast=true]`,
+ * `gpt-5.6-sol[context=272k,reasoning=medium,fast=false]`. The ids an agent
+ * holds come from `cursor-agent models` (`auto`, `composer-2.5`,
+ * `gpt-5.6-sol-medium`), which is a different list. Sending such an id gave
+ * `Failed to set model: Invalid params` on every turn, "Auto" included.
+ *
+ * Tried in order: the exact value, the option's display name, the part before
+ * `[`, then the longest such part the id starts with (`gpt-5.6-sol-medium`
+ * → `gpt-5.6-sol[…]`). `auto` is Cursor's `default`.
+ */
+function resolveCursorModelValue(model, sessionResult) {
+    const wanted = (model ?? '').trim().toLowerCase();
+    if (!wanted)
+        return null;
+    const values = optionValues(sessionResult, 'model');
+    if (values.length === 0)
+        return null;
+    const exact = values.find((entry) => entry.value.toLowerCase() === wanted);
+    if (exact)
+        return exact.value;
+    const byName = values.find((entry) => entry.name.trim().toLowerCase() === wanted);
+    if (byName)
+        return byName.value;
+    const wantedBase = wanted === 'auto' ? 'default' : baseOf(wanted);
+    const byBase = values.find((entry) => baseOf(entry.value) === wantedBase);
+    if (byBase)
+        return byBase.value;
+    let best = null;
+    for (const entry of values) {
+        const base = baseOf(entry.value);
+        if (!base || !wantedBase.startsWith(`${base}-`))
+            continue;
+        if (!best || base.length > best.base.length) {
+            best = { value: entry.value, base };
+        }
+    }
+    return best?.value ?? null;
+}
+/**
+ * The Cursor mode a turn must run in.
+ *
+ * FAIL CLOSED. In its `agent` mode Cursor asks only about commands that are
+ * not on the allow-list in the runner owner's `~/.cursor/cli-config.json`
+ * (seen: "Not in allowlist: cat, echo"). The runner must not read or change
+ * that list, so it cannot know which actions Cursor will run unasked, and a
+ * permission mode that promises a question before EACH action cannot be
+ * promised for Cursor. Every asking mode therefore runs
+ * Cursor in one of its own read-only modes — stricter than what was asked for,
+ * never looser:
+ *
+ *   plan                       → Cursor `plan` (reads and proposes a plan)
+ *   default, acceptEdits       → Cursor `ask`  (reads and answers, no changes)
+ *   bypassPermissions          → Cursor `agent` (the only mode that may act)
+ *
+ * A permission request Cursor does raise is still put to the person.
+ */
+function cursorModeFor(config) {
+    // Only an explicit "allow" may act. An unknown value is treated as asking.
+    if (config.permissionMode === 'allow')
+        return 'agent';
+    return config.sandboxMode === 'read-only' ? 'plan' : 'ask';
+}
+/**
+ * The exact value of the session's `mode` option for a Cursor mode, or null
+ * when the session does not offer it. The caller must refuse the turn on null
+ * for a read-only mode rather than run in whatever mode Cursor starts in.
+ */
+function resolveCursorModeValue(mode, sessionResult) {
+    const values = optionValues(sessionResult, 'mode');
+    const found = values.find((entry) => entry.value.toLowerCase() === mode);
+    if (found)
+        return found.value;
+    // Older agents list modes under `modes.availableModes` instead.
+    if (isRecord(sessionResult) && isRecord(sessionResult.modes)) {
+        const available = sessionResult.modes.availableModes;
+        if (Array.isArray(available)) {
+            for (const entry of available) {
+                if (isRecord(entry) &&
+                    typeof entry.id === 'string' &&
+                    entry.id.toLowerCase() === mode) {
+                    return entry.id;
+                }
+            }
+        }
+    }
+    return null;
+}
+const CURSOR_PLAN_LIMIT_TEXT = 'upgrade your plan to continue';
+function normalise(text) {
+    return text
+        .trim()
+        .replace(/[.!]+$/, '')
+        .replace(/\s+/g, ' ')
+        .toLowerCase();
+}
+/**
+ * Is this whole assistant reply Cursor's plan-limit notice?
+ *
+ * Cursor does not report its account limit as an error. It sends the sentence
+ * "Upgrade your plan to continue" as the model's answer and ends the turn
+ * normally. Matched on the WHOLE reply only, so an answer that merely quotes
+ * the sentence is left alone.
+ */
+function isCursorPlanLimitReply(text) {
+    return typeof text === 'string' && normalise(text) === CURSOR_PLAN_LIMIT_TEXT;
+}
+/** Could this partial reply still grow into the plan-limit notice? */
+function mayBecomeCursorPlanLimitReply(text) {
+    if (typeof text !== 'string')
+        return false;
+    const partial = normalise(text);
+    return partial.length > 0 && CURSOR_PLAN_LIMIT_TEXT.startsWith(partial);
+}
+exports.CURSOR_PLAN_LIMIT_ERROR = 'Cursor answered "Upgrade your plan to continue" and did no work. This ' +
+    'comes from the Cursor account that is signed in on the runner, not from ' +
+    'Peakflo: its plan does not include the selected model or has reached its ' +
+    'limit. Choose the "Auto" model for this agent, upgrade or change the ' +
+    'Cursor account on the runner machine, or choose another harness.';
+/** `error.message`, plus `error.data.message` when the agent sent one. */
+function describeAcpRpcError(error) {
+    const message = typeof error.message === 'string' ? error.message : 'ACP error';
+    const detail = isRecord(error.data) && typeof error.data.message === 'string'
+        ? error.data.message
+        : typeof error.data === 'string'
+            ? error.data
+            : '';
+    return detail && !message.includes(detail)
+        ? `${message}: ${detail}`
+        : message;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.9-rc.4",
+  "version": "0.2.9-rc.5",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",