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

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 {
@@ -1185,7 +1284,20 @@ class ClaudeCodeAdapter {
             const errName = error instanceof Error ? error.name : '';
             const errMsg = error instanceof Error ? error.message : String(error);
             const errStack = error instanceof Error ? error.stack : undefined;
-            if (errName === 'AbortError' || errMsg.includes('aborted by user')) {
+            // CHANGED from 20x: the runner stops the session at the end of EVERY
+            // turn (one process per turn), and the SDK reports that stop as a plain
+            // `Error: Operation aborted`. That is the expected end of a finished
+            // turn, not a failure: it used to be logged as "Stream error" with a
+            // stack trace after every successful turn, and marked the session failed.
+            // Both conditions: the adapter asked for the stop AND the error is the
+            // SDK's own word for a stopped process. An unrelated failure that
+            // happens to arrive after the stop is still reported below.
+            const stoppedByUs = session.abortController?.signal.aborted === true &&
+                /\babort(ed)?\b/i.test(errMsg);
+            if (stoppedByUs) {
+                console.log('[ClaudeCodeAdapter] Stream stopped at the end of the turn');
+            }
+            else if (errName === 'AbortError' || errMsg.includes('aborted by user')) {
                 console.log('[ClaudeCodeAdapter] Stream aborted by user');
                 // Don't set error status - this is normal when sending a new message
             }
@@ -1221,6 +1333,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;
@@ -16,6 +40,8 @@ interface PendingApproval {
         kind: string;
     }>;
     responseKind: 'execCommand' | 'commandExecution' | 'fileChange' | 'permissions' | 'elicitation' | 'userInput' | 'generic';
+    /** What `item/permissions/requestApproval` asked for; echoed back on allow. */
+    requestedPermissions?: unknown;
 }
 export declare class CodexAppServerAdapter implements CodingAgentAdapter {
     private sessions;

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` ->
@@ -54,7 +57,62 @@ 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 codex_approval_text_1 = require("./codex-approval-text");
 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;
@@ -220,12 +278,6 @@ function isSubpath(parent, child) {
     const rel = (0, path_1.relative)((0, path_1.resolve)(parent), (0, path_1.resolve)(child));
     return rel === '' || (!!rel && !rel.startsWith('..') && !(0, path_1.isAbsolute)(rel));
 }
-function summarizeApproval(params, fallback) {
-    const command = asString(params.command);
-    const reason = asString(params.reason);
-    const itemId = asString(params.itemId) || asString(params.callId);
-    return [command || fallback, reason, itemId ? `id: ${itemId}` : ''].filter(Boolean).join('\n');
-}
 function normalizeDecisionName(decision) {
     if (typeof decision === 'string')
         return decision;
@@ -234,24 +286,6 @@ function normalizeDecisionName(decision) {
     }
     return 'accept';
 }
-function decisionLabel(decision) {
-    switch (decision) {
-        case 'accept':
-        case 'approved':
-            return 'Allow';
-        case 'acceptForSession':
-        case 'approved_for_session':
-            return 'Allow for Session';
-        case 'decline':
-        case 'denied':
-            return 'Deny';
-        case 'cancel':
-        case 'abort':
-            return 'Deny and Stop';
-        default:
-            return decision;
-    }
-}
 class CodexAppServerAdapter {
     sessions = new Map();
     codexExecutablePath = null;
@@ -269,7 +303,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 +329,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 +381,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),
@@ -483,14 +517,24 @@ class CodexAppServerAdapter {
         if (!approval)
             return;
         const selected = optionId || approval.options.find((option) => approved
-            ? ['acceptForSession', 'accept', 'approved_for_session', 'approved'].includes(option.optionId)
-            : ['cancel', 'abort', 'decline', 'denied'].includes(option.optionId))?.optionId || (approved ? 'accept' : 'cancel');
-        const response = this.buildApprovalResponse(approval.responseKind, selected, approved);
+            ? ['accept', 'approved'].includes(option.optionId)
+            : ['decline', 'denied'].includes(option.optionId))?.optionId || (
+        // The older requests take `approved` / `denied`.
+        approval.responseKind === 'execCommand'
+            ? (approved ? 'approved' : 'denied')
+            : (approved ? 'accept' : 'decline'));
+        const response = this.buildApprovalResponse(approval.responseKind, selected, approved, approval.requestedPermissions);
         this.sendRpcResponse(session, approval.requestId, response);
         session.pendingApproval = null;
-        if (!approved) {
-            session.status = coding_agent_adapter_1.SessionStatusType.IDLE;
-        }
+        // CHANGED from 20x, which marked the session idle on every denial. A
+        // denial that continues the turn (`decline`, `denied`) is followed by the
+        // model's own answer; calling the session idle here ended the turn before
+        // that answer arrived. Only a denial that stops the turn is idle at once.
+        // (No button sends `cancel` or `abort` any more; a caller that names one
+        // explicitly still gets the stop it asked for.)
+        session.status = !approved && (selected === 'cancel' || selected === 'abort')
+            ? coding_agent_adapter_1.SessionStatusType.IDLE
+            : coding_agent_adapter_1.SessionStatusType.BUSY;
     }
     async getRunningTools(sessionId, _config) {
         return Array.from(this.sessions.get(sessionId)?.runningTools.values() || []);
@@ -822,44 +866,73 @@ class CodexAppServerAdapter {
         if (session.config.permissionMode === 'allow') {
             const responseKind = this.getApprovalResponseKind(request.method);
             const selected = responseKind === 'execCommand' ? 'approved' : 'accept';
-            this.sendRpcResponse(session, request.id, this.buildApprovalResponse(responseKind, selected, true));
+            this.sendRpcResponse(session, request.id, this.buildApprovalResponse(responseKind, selected, true, params.permissions));
             return;
         }
         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 : [];
-        const approvalOptions = rawDecisions.length > 0
-            ? rawDecisions.map((decision) => {
-                const optionId = normalizeDecisionName(decision);
-                return {
-                    optionId,
-                    name: decisionLabel(optionId),
-                    kind: optionId.includes('accept') || optionId === 'approved' ? 'allow' : 'reject'
-                };
-            })
+        // 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 withheld = offered.map(normalizeDecisionName).filter(isStandingApprovalDecision);
+        if (withheld.length > 0) {
+            console.log(`[CodexAppServerAdapter] Not offering approval decisions: ${withheld.join(', ')}`);
+        }
+        /*
+         * CHANGED from 20x: ONE "Allow" AND ONE "Deny", AND DENY LETS THE TURN GO ON.
+         *
+         * Codex has two denials. `cancel` ("abort" in the older form) also
+         * interrupts the turn: the chat went idle with no word from the agent, as
+         * if nothing had been asked. `decline` ("denied") refuses the action and
+         * lets the model carry on, so it can say that it was not allowed and what
+         * it will do instead. Both are in the protocol for every request that has
+         * a decision, whether or not `availableDecisions` lists them, so "Deny" is
+         * always the one that continues.
+         */
+        const legacy = responseKind === 'execCommand';
+        const approvalOptions = legacy
+            ? [
+                { optionId: 'approved', name: 'Allow', kind: 'allow' },
+                { optionId: 'denied', name: 'Deny', kind: 'reject' }
+            ]
             : [
                 { optionId: 'accept', name: 'Allow', kind: 'allow' },
-                { optionId: 'cancel', name: 'Deny', kind: 'reject' }
+                { optionId: 'decline', name: 'Deny', kind: 'reject' }
             ];
+        // The item the request is about, when it has been announced: a file
+        // change's paths are on the item, not on the request.
+        const itemId = asString(params.itemId) || asString(params.callId);
+        const item = itemId ? session.runningTools.get(`tool-${itemId}`)?.input : undefined;
         session.pendingApproval = {
             requestId: request.id,
             toolCallId,
-            question: summarizeApproval(params, request.method),
+            question: (0, codex_approval_text_1.describeCodexApproval)(request.method, params, item, session.config.workspaceDir),
             options: approvalOptions,
-            responseKind
+            responseKind,
+            ...(responseKind === 'permissions' ? { requestedPermissions: params.permissions } : {})
         };
         session.status = coding_agent_adapter_1.SessionStatusType.WAITING_APPROVAL;
         this.onDataAvailable?.(session.threadId || session.sessionId);
     }
-    buildApprovalResponse(responseKind, selected, approved) {
+    buildApprovalResponse(responseKind, selected, approved, requestedPermissions) {
         switch (responseKind) {
             case 'execCommand':
-                return { decision: approved ? (selected === 'approved_for_session' ? 'approved_for_session' : 'approved') : (selected === 'denied' ? 'denied' : 'abort') };
+                // The older requests (`execCommandApproval`, `applyPatchApproval`)
+                // take a ReviewDecision. `denied` continues the turn; `abort` stops it.
+                return { decision: approved ? 'approved' : (selected === 'abort' ? 'abort' : 'denied') };
             case 'commandExecution':
-                return { decision: selected };
             case 'fileChange':
+                return { decision: approved ? 'accept' : (selected === 'cancel' ? 'cancel' : 'decline') };
             case 'permissions':
-                return { decision: selected };
+                // CHANGED from 20x, which answered `{ decision }`. This request has no
+                // decision: the answer is the permissions granted, for this turn only.
+                // Granting nothing is the denial.
+                return {
+                    permissions: approved && isObject(requestedPermissions) ? requestedPermissions : {},
+                    scope: 'turn'
+                };
             case 'elicitation':
                 return approved
                     ? { action: 'accept', content: {} }
@@ -869,11 +942,11 @@ class CodexAppServerAdapter {
                     ? { response: selected }
                     : { response: null };
             default:
-                return { decision: approved ? selected : 'cancel' };
+                return { decision: approved ? 'accept' : 'decline' };
         }
     }
     getApprovalResponseKind(method) {
-        if (method === 'execCommandApproval')
+        if (method === 'execCommandApproval' || method === 'applyPatchApproval')
             return 'execCommand';
         if (method.includes('commandExecution'))
             return 'commandExecution';
@@ -922,8 +995,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/codex-approval-text.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What a person is shown when `codex app-server` asks for an approval.
+ *
+ * The card used to show the protocol itself: `item/fileChange/requestApproval`
+ * and `id: exec-…`, with the file name only in the item above it. This module
+ * turns each kind of request the app-server can send into a first line that
+ * says what will happen ("Write: src/a.ts", "Run: npm test") and further lines
+ * with what helps to decide (where, why, which files).
+ *
+ * The first line is the title; the control plane's card shows it on its own.
+ * No ids: nobody can decide anything from one.
+ *
+ * Request kinds, from `codex app-server generate-json-schema` (ServerRequest):
+ *   item/commandExecution/requestApproval   a command, or input to a terminal
+ *   item/fileChange/requestApproval         a patch; the files are on the item
+ *   item/permissions/requestApproval        wider sandbox access for the turn
+ *   mcpServer/elicitation/request           an MCP server asks (incl. to run
+ *                                           one of its tools)
+ *   item/tool/requestUserInput              the model asks a question
+ *   execCommandApproval, applyPatchApproval the older forms of the first two
+ * Kept out of the adapter, which is a copy of 20x's, so it can be tested alone.
+ */
+type Json = Record<string, unknown>;
+interface FileChange {
+    path: string;
+    kind: string;
+    added: number;
+    removed: number;
+}
+/**
+ * The files of a change, from either shape Codex uses:
+ *   v2 item       `changes: [{ path, kind: { type }, diff }]`
+ *   older request `fileChanges: { [path]: { add | delete | update: {…} } }`
+ */
+export declare function readFileChanges(source: unknown): FileChange[];
+/**
+ * The text of one approval request.
+ *
+ * @param item the thread item the request is about, when the adapter has seen
+ *   it (`item/started` arrives before the request). A file change's paths are
+ *   only there.
+ */
+export declare function describeCodexApproval(method: string, params: Json, item?: Json, 
+/** The session's workspace; paths inside it are shown relative to it. */
+workspaceDir?: string): string;
+export {};