@agentex/agent 0.0.40 → 0.0.42

package/src/providers/antigravity/session.ts

@@ -38,7 +38,8 @@ import { AGY_SIGN_IN_MESSAGE, buildAgyArgs, findAgyBinary, readAgyResumeId } fro
 interface ActiveTurn {
   turnId: string;
   abort: AbortController;
-  done: Promise<TurnResult>;
+  /** Set once the turn starts; a turn_start handler can interrupt before that. */
+  done: Promise<TurnResult> | null;
 }
 
 /**
@@ -74,8 +75,20 @@ class AntigravitySession implements AgentSession {
   /** Events received from agy processes, to tell whether one saw a message. */
   private connectionEvents = 0;
   private draining = false;
-  /** Instructions go into the first message of a conversation this session starts. */
-  private pendingInstructions: string | null;
+  /**
+   * agy has no system-prompt flag, so instructions ride on the first message
+   * each process accepts, like a per-process system prompt. They stay pending
+   * until agy acknowledges a message that carried them, so a failed start or
+   * sign-in never drops them, and a resume agy could not honor (a new
+   * conversation) still gets them.
+   */
+  private readonly instructions: string | null;
+  /** Conversations this session saw agy accept the instructions into. */
+  private readonly instructedConversations = new Set<string>();
+  /** The current process accepted a message that carried the instructions. */
+  private connectionInstructed = false;
+  /** The conversation the current process was started to resume, if any. */
+  private connectionResumeId: string | null = null;
   private readonly cwd: string;
   private readonly goals: GoalController;
 
@@ -86,7 +99,7 @@ class AntigravitySession implements AgentSession {
   ) {
     this.cwd = ctx.cwd ?? process.cwd();
     this.conversationId = readAgyResumeId(ctx.sessionParams, this.cwd);
-    this.pendingInstructions = this.conversationId ? null : instructions;
+    this.instructions = instructions;
     this.goals = new GoalController({
       providerType: ANTIGRAVITY_PROVIDER_TYPE,
       capability: EMULATED_GOAL_CAPABILITY,
@@ -118,12 +131,14 @@ class AntigravitySession implements AgentSession {
     const uuid = uuidv7();
     const turnId = uuidv7();
     const abort = new AbortController();
-    const text = this.pendingInstructions ? `${this.pendingInstructions}\n\n${message}` : message;
-    this.pendingInstructions = null;
 
     this._state = "thinking";
-    const done = this.runTurn(text, turnId, abort, options);
-    this.active = { turnId, abort, done };
+    // Registered before the turn runs, so interrupt() can reach it from inside
+    // a turn_start handler.
+    const active: ActiveTurn = { turnId, abort, done: null };
+    this.active = active;
+    const done = this.runTurn(message, turnId, abort, options);
+    active.done = done;
     void done.then((result) => this.goals.onTurnSettled(result)).catch(() => undefined);
     return { uuid, result: done };
   }
@@ -133,6 +148,8 @@ class AntigravitySession implements AgentSession {
     const config = this.ctx.config ?? {};
     // A replacement process picks the conversation back up where it stopped.
     this.conversationId = this.sessionId;
+    this.connectionResumeId = this.conversationId;
+    this.connectionInstructed = false;
     const parser = new AgyStreamParser({
       includePartialMessages: config.includePartialMessages,
       conversationId: this.conversationId,
@@ -162,18 +179,21 @@ class AntigravitySession implements AgentSession {
   }
 
   private async runTurn(
-    text: string,
+    message: string,
     turnId: string,
     abort: AbortController,
     options?: SendOptions,
   ): Promise<TurnResult> {
-    await this.emitTurnEdge({ type: "turn_start", turnId, trigger: "send" });
-
+    // Arm every stop before the first await: an interrupt that lands while
+    // turn_start handlers run must still stop the turn.
     const timeoutSec = options?.timeoutSec ?? this.ctx.config?.timeoutSec;
     const graceSec = this.ctx.config?.graceSec;
     let timer: ReturnType<typeof setTimeout> | null = null;
     const guards: Promise<"timeout" | "aborted">[] = [
-      new Promise((resolve) => abort.signal.addEventListener("abort", () => resolve("aborted"), { once: true })),
+      new Promise((resolve) => {
+        if (abort.signal.aborted) resolve("aborted");
+        else abort.signal.addEventListener("abort", () => resolve("aborted"), { once: true });
+      }),
     ];
     if (timeoutSec && timeoutSec > 0) {
       guards.push(new Promise((resolve) => { timer = setTimeout(() => resolve("timeout"), timeoutSec * 1000); }));
@@ -184,15 +204,30 @@ class AntigravitySession implements AgentSession {
       else options.signal.addEventListener("abort", onSendAbort, { once: true });
     }
 
-    let connection = this.ensureConnection();
+    let connection: AgyConnection | null = null;
     try {
+      await this.emitTurnEdge({ type: "turn_start", turnId, trigger: "send" });
+      if (abort.signal.aborted) {
+        // Stopped before agy saw anything: nothing to interrupt, nothing spawned.
+        await this.emitTurnEdge({ type: "turn_end", turnId, trigger: "send", reason: "cancelled" });
+        return { summary: null, costUsd: null, status: "aborted", errorCode: "aborted", errorMessage: "Turn aborted" };
+      }
+
+      connection = this.ensureConnection();
       let result: TurnResult | null = null;
       let reason: "result" | "cancelled" | "session_closed" = "result";
       for (let attempt = 0; result === null; attempt++) {
         const eventsBefore = this.connectionEvents;
+        const carriesInstructions = this.needsInstructions();
         const pending = connection.nextTurn();
-        connection.write(text);
+        connection.write(carriesInstructions ? `${this.instructions}\n\n${message}` : message);
         const first = await Promise.race([pending, ...guards]);
+        // Any event from agy means it accepted the message, instructions included.
+        if (carriesInstructions && this.connectionEvents > eventsBefore) {
+          this.connectionInstructed = true;
+          const conversation = this.parser?.conversationId;
+          if (conversation) this.instructedConversations.add(conversation);
+        }
         if (first === "timeout" || first === "aborted") {
           const outcome = await interruptAgyTurn(connection, pending, graceSec);
           // agy may report INTERRUPTED and then exit. Learn which before the
@@ -230,11 +265,17 @@ class AntigravitySession implements AgentSession {
       if (timer) clearTimeout(timer);
       options?.signal?.removeEventListener("abort", onSendAbort);
       this.active = null;
-      if (!connection.alive && this.connection === connection) this.connection = null;
+      if (connection && !connection.alive && this.connection === connection) this.connection = null;
       if (this._state !== "closed") this._state = "idle";
     }
   }
 
+  /** The next message must carry the instructions (see `instructions`). */
+  private needsInstructions(): boolean {
+    if (!this.instructions || this.connectionInstructed) return false;
+    return !(this.connectionResumeId && this.instructedConversations.has(this.connectionResumeId));
+  }
+
   private usageOf(outcome: AgyTurnOutcome | null): { usage?: TurnResult["usage"] } {
     const usage = agyUsageRecord(outcome?.result?.turnUsage ?? null, this.parser?.model ?? this.ctx.config?.model ?? null);
     return usage ? { usage } : {};
@@ -335,12 +376,12 @@ class AntigravitySession implements AgentSession {
     const active = this.active;
     if (!active) return;
     active.abort.abort();
-    await active.done.catch(() => undefined);
+    await active.done?.catch(() => undefined);
   }
 
   async drain(): Promise<void> {
     this.draining = true;
-    if (this.active) await this.active.done.catch(() => undefined);
+    await this.active?.done?.catch(() => undefined);
     await this.close();
   }
 
@@ -350,7 +391,7 @@ class AntigravitySession implements AgentSession {
     const active = this.active;
     if (active) {
       active.abort.abort();
-      await active.done.catch(() => undefined);
+      await active.done?.catch(() => undefined);
     }
     const connection = this.connection;
     this.connection = null;

package/src/providers/codex/parse.ts

@@ -81,6 +81,61 @@ function parseStringArray(value: unknown): string[] {
  * tells it to do — rendered no row for completions that reached it by the
  * reconcile path. Mirrors the Claude gate in `claude/parse.ts`.
  */
+/**
+ * The name an MCP tool call goes by: `mcp__<server>__<tool>`, the name the
+ * model calls it by and the shape Claude reports, so hosts render both alike.
+ * Codex's `tool` can be dotted (`github.create_branch` on the `codex_apps`
+ * server); the model sees `mcp__codex_apps__github_create_branch`.
+ */
+export function codexMcpToolName(server: string, tool: string | null): string {
+  const clean = (part: string) => part.replace(/[^A-Za-z0-9_-]/g, "_");
+  return tool ? `mcp__${clean(server)}__${clean(tool)}` : `mcp__${clean(server)}`;
+}
+
+function isMcpToolCallItem(itemType: string): boolean {
+  return itemType === "mcpToolCall" || itemType === "mcp_tool_call";
+}
+
+/** What an MCP tool call returned: its error, else its text content, else its structured content. */
+function mcpToolCallOutput(item: Record<string, unknown>): string {
+  const error = parseObject(item["error"]);
+  const message = asString(error["message"], "");
+  if (message) return message;
+  const result = parseObject(item["result"]);
+  const content = Array.isArray(result["content"]) ? result["content"] : [];
+  const text = content
+    .map((part) => {
+      const block = parseObject(part);
+      return block["type"] === "text" ? asString(block["text"], "") : JSON.stringify(part);
+    })
+    .filter(Boolean)
+    .join("\n");
+  if (text) return text;
+  const structured = result["structuredContent"] ?? result["structured_content"];
+  return structured === undefined || structured === null ? "" : JSON.stringify(structured);
+}
+
+function mcpToolCallEvent(
+  phase: "started" | "completed",
+  item: Record<string, unknown>,
+  itemId: string | null,
+  base: BaseStreamEventFields,
+): StreamEvent {
+  const name = codexMcpToolName(asString(item["server"], ""), asNullableString(item["tool"]));
+  if (phase === "started") {
+    return { type: "tool_call", toolCallId: itemId, name, input: item["arguments"] ?? {}, ...base };
+  }
+  return {
+    type: "tool_result",
+    toolCallId: itemId,
+    toolName: name,
+    content: mcpToolCallOutput(item),
+    isError: item["status"] === "failed" || Object.keys(parseObject(item["error"])).length > 0,
+    exitCode: null,
+    ...base,
+  };
+}
+
 export function codexBackgroundTaskReport(
   phase: "started" | "progress" | "completed",
   status: "pending" | "running" | "paused" | "completed" | "failed" | "stopped" | null,
@@ -402,6 +457,7 @@ function parseV2Notification(event: Record<string, unknown>): StreamEvent | Stre
           ...base,
         };
       }
+      if (isMcpToolCallItem(itemType)) return mcpToolCallEvent("started", item, itemId, base);
       // reasoning, agentMessage, userMessage — wait for item/completed.
       return null;
     }
@@ -432,6 +488,7 @@ function parseV2Notification(event: Record<string, unknown>): StreamEvent | Stre
         ...base,
       };
     }
+    if (isMcpToolCallItem(itemType)) return mcpToolCallEvent("completed", item, itemId, base);
     if (itemType === "agentMessage") {
       const directText = asString(item["text"], "");
       if (directText || directText === "") {
@@ -690,6 +747,7 @@ function parseNdjsonEvent(
         ...base,
       };
     }
+    if (isMcpToolCallItem(itemType)) return mcpToolCallEvent("started", item, itemId, base);
   }
 
   if (type === "item.completed") {
@@ -721,6 +779,7 @@ function parseNdjsonEvent(
         ...base,
       };
     }
+    if (isMcpToolCallItem(itemType)) return mcpToolCallEvent("completed", item, itemId, base);
     if (itemType === "agent_message") {
       const phase = asMessagePhase(item["phase"]);
       const directText = asString(item["text"], "");

package/src/providers/codex/permissions.ts

@@ -0,0 +1,61 @@
+/**
+ * The approval policy and sandbox a Codex app-server thread runs with.
+ *
+ * `codex app-server` reads root `-c key=value` overrides but drops the
+ * interactive flags (`--sandbox`, `--dangerously-bypass-approvals-and-sandbox`):
+ * they belong to the TUI, and the `app-server` subcommand never receives them
+ * (codex-rs `cli/src/main.rs`, verified on 0.160). Sessions spawned with those
+ * flags ran on Codex's own defaults instead: approvals `on-request` and a
+ * `workspace-write` or `read-only` sandbox, whatever the host asked for.
+ *
+ * So the policy is set twice, through the two channels app-server does read:
+ * the `-c` overrides at spawn (every thread the process runs, child agents and
+ * resumed threads included) and the `thread/start` / `thread/resume` params
+ * (the root thread, explicitly, so a resumed thread created under different
+ * settings takes the current ones).
+ *
+ * It matters beyond the sandbox. Under `never` with full disk access, Codex
+ * approves MCP and app tool calls itself (`mcp_permission_prompt_is_auto_approved`
+ * in codex-rs `codex-mcp`). Under `on-request` it asks the client first, through
+ * `mcpServer/elicitation/request`.
+ */
+
+import type { ProviderConfig } from "../../types.js";
+
+export type CodexSandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+
+export interface CodexThreadPermissions {
+  /** Unset leaves Codex's configured default (`on-request` unless the user changed it). */
+  approvalPolicy?: "never";
+  /** Unset leaves Codex's configured default, which depends on the folder's trust. */
+  sandbox?: CodexSandboxMode;
+}
+
+/**
+ * Plan mode wins over `skipPermissions`, as it does for the spawn flags:
+ * read-only, with approvals left on so an escalation still reaches the host.
+ * Anything else leaves Codex's defaults, which is what no flag ever meant.
+ */
+export function codexThreadPermissions(
+  config: Pick<ProviderConfig, "planMode" | "skipPermissions"> | undefined,
+): CodexThreadPermissions {
+  if (config?.planMode) return { sandbox: "read-only" };
+  if (config?.skipPermissions) return { approvalPolicy: "never", sandbox: "danger-full-access" };
+  return {};
+}
+
+/** The same settings as root `-c` overrides, placed before the `app-server` subcommand. */
+export function codexPermissionConfigArgs(permissions: CodexThreadPermissions): string[] {
+  const args: string[] = [];
+  if (permissions.approvalPolicy) args.push("-c", `approval_policy="${permissions.approvalPolicy}"`);
+  if (permissions.sandbox) args.push("-c", `sandbox_mode="${permissions.sandbox}"`);
+  return args;
+}
+
+/** The same settings as `thread/start` / `thread/resume` params. */
+export function codexPermissionThreadParams(permissions: CodexThreadPermissions): Record<string, unknown> {
+  return {
+    ...(permissions.approvalPolicy ? { approvalPolicy: permissions.approvalPolicy } : {}),
+    ...(permissions.sandbox ? { sandbox: permissions.sandbox } : {}),
+  };
+}

package/src/providers/codex/session.ts

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import type {
   BackgroundTaskReport,
   AgentSession,
+  ElicitationResponse,
   CancelResult,
   ClearGoalResult,
   GoalOptions,
@@ -28,11 +29,16 @@ import { translateEndpoint } from "../../utils/endpoint.js";
 import { injectWorkspaceSkills } from "../../utils/skills.js";
 import { resolveInstructions } from "../../utils/instructions.js";
 import { createToolNameTracker } from "../../utils/tool-names.js";
-import { parseCodexStreamLines, codexBackgroundTaskReport } from "./parse.js";
+import { parseCodexStreamLines, codexBackgroundTaskReport, codexMcpToolName } from "./parse.js";
 import { withPlanModePreamble } from "./plan-mode.js";
 import { scanCodexSessionUsage } from "./usage-scanner.js";
 import { codexSessionCodec } from "./codec.js";
 import { parseCollaborationModes, resolveCollaborationModeParam } from "./modes.js";
+import {
+  codexPermissionConfigArgs,
+  codexPermissionThreadParams,
+  codexThreadPermissions,
+} from "./permissions.js";
 
 /**
  * Extract a resume thread id from session params (reusing the codec's
@@ -122,6 +128,52 @@ function buildCodexUserInputAnswers(
   return out;
 }
 
+/** An MCP tool call Codex has started and not finished (`item/started`, `mcpToolCall`). */
+interface InFlightMcpCall {
+  itemId: string;
+  threadId: string | null;
+  server: string;
+  tool: string;
+  arguments: unknown;
+}
+
+/**
+ * One line for an MCP tool approval from Codex's `tool_params_display`
+ * (`[{ name, display_name, value }]`), e.g.
+ * `Repository: acme/web · Branch name: fix/login · Base ref: main`.
+ */
+function describeMcpToolParams(display: unknown): string | undefined {
+  if (!Array.isArray(display)) return undefined;
+  const parts: string[] = [];
+  for (const entry of display) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const param = entry as Record<string, unknown>;
+    const label = str(param, "display_name") || str(param, "name");
+    if (!label) continue;
+    const raw = param["value"];
+    const value = typeof raw === "string" ? raw : JSON.stringify(raw);
+    if (value === undefined) continue;
+    parts.push(`${label}: ${value.length > 120 ? `${value.slice(0, 117)}...` : value}`);
+  }
+  return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+
+/** The elicitation reply Codex expects: `action`, plus `content` only on an accept. */
+function elicitationReply(resp: ElicitationResponse): Record<string, unknown> {
+  return {
+    action: resp.action,
+    ...(resp.action === "accept" && resp.content ? { content: resp.content } : {}),
+  };
+}
+
+/** JSON with object keys sorted, so two argument objects compare by value. */
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, (_key, v: unknown) =>
+    v && typeof v === "object" && !Array.isArray(v)
+      ? Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)))
+      : v) ?? "";
+}
+
 /** A pending `send()` whose `result` Promise hasn't settled yet. */
 interface PendingResult {
   resolve: (result: TurnResult) => void;
@@ -328,15 +380,13 @@ export async function createCodexSession(ctx: SessionContext): Promise<AgentSess
   // Spawn Codex in interactive JSON-RPC mode via the `app-server` subcommand
   // (codex-cli 0.130.0+; the old top-level `--json` flag was removed).
   //
-  // Args order matters: `--sandbox` and `--dangerously-bypass-approvals-and-sandbox`
-  // are TOP-LEVEL options and must come BEFORE the `app-server` subcommand.
+  // Approval policy and sandbox go in as root `-c` overrides, BEFORE the
+  // subcommand: app-server ignores `--sandbox` and
+  // `--dangerously-bypass-approvals-and-sandbox` (see ./permissions.ts). The
+  // handshake repeats them on the thread itself.
   // extraArgs land after the subcommand — semantics depend on the user's intent.
   const args = [...resolved.prefixArgs];
-  if (config.planMode) {
-    args.push("--sandbox", "read-only");
-  } else if (config.skipPermissions) {
-    args.push("--dangerously-bypass-approvals-and-sandbox");
-  }
+  args.push(...codexPermissionConfigArgs(codexThreadPermissions(config)));
   // Custom endpoint model_providers overrides are top-level `-c` options, placed
   // with the other top-level flags before the `app-server` subcommand (the
   // position that is always valid for global options).
@@ -437,6 +487,9 @@ export class CodexSessionImpl implements AgentSession {
   /** Stamps `tool_result.toolName` by correlating with prior `tool_call`s. */
   private readonly _trackToolName = createToolNameTracker();
 
+  /** MCP tool calls started and not yet completed, by item id, for pairing approvals. */
+  private readonly _mcpCallsInFlight = new Map<string, InFlightMcpCall>();
+
   // Per-turn accumulators. Cleared after each result delivery so a subsequent
   // turn's events don't inherit stale values.
   private _turnSummary: string | null = null;
@@ -771,6 +824,10 @@ export class CodexSessionImpl implements AgentSession {
     this.proc.stdin!.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
   }
 
+  private rpcError(id: number, code: number, message: string): void {
+    this.proc.stdin!.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
+  }
+
   // -------------------------------------------------------------------------
   // Handshake
   // -------------------------------------------------------------------------
@@ -791,9 +848,12 @@ export class CodexSessionImpl implements AgentSession {
     //    otherwise start a fresh one. `thread/resume` continues the SAME thread
     //    with its full context retained — distinct from `thread/fork`, which is
     //    a divergent rewind copy. The thread keeps its original cwd/model, so we
-    //    pass only the thread id (+ refreshed developer instructions).
+    //    pass only the thread id (+ refreshed developer instructions, and the
+    //    approval policy and sandbox this session runs with, which may differ
+    //    from the ones the thread was created under).
+    const permissionParams = codexPermissionThreadParams(codexThreadPermissions(this.ctx.config));
     if (this._resumeThreadId) {
-      const resumeParams: Record<string, unknown> = { threadId: this._resumeThreadId };
+      const resumeParams: Record<string, unknown> = { threadId: this._resumeThreadId, ...permissionParams };
       if (this.instructions) resumeParams["developerInstructions"] = this.instructions;
       try {
         const res = await this.rpcRequest("thread/resume", resumeParams);
@@ -830,7 +890,7 @@ export class CodexSessionImpl implements AgentSession {
     }
 
     // thread/start (fresh)
-    const threadParams: Record<string, unknown> = { cwd: this.cwd };
+    const threadParams: Record<string, unknown> = { cwd: this.cwd, ...permissionParams };
     if (this.model) threadParams["model"] = this.model;
     if (this.instructions) threadParams["developerInstructions"] = this.instructions;
 
@@ -1236,16 +1296,174 @@ export class CodexSessionImpl implements AgentSession {
     ) {
       // `tool/requestUserInput` is the legacy method name on older codex builds.
       void this.handleUserInputRequest(id, params);
+    } else if (method === "mcpServer/elicitation/request") {
+      void this.handleMcpElicitation(id, params);
+    } else {
+      // A request this file does not handle. Every server request the protocol
+      // defines declares required response fields, so the `{}` this used to
+      // send was schema-invalid, and Codex read it as a refusal: that is how
+      // MCP tool approvals were silently declined before they were handled
+      // here. "Method not found" is the honest answer and fails visibly.
+      // What's left is opt-in (`attestation/generate`), never sent to a client
+      // that registers no dynamic tools and no external auth (`item/tool/call`,
+      // `account/chatgptAuthTokens/refresh`), or v1-only (`applyPatchApproval`,
+      // `execCommandApproval`).
+      this.rpcError(id, -32601, `agentex does not handle the ${method} request`);
+    }
+  }
+
+  /**
+   * Handle `mcpServer/elicitation/request`. Codex sends two kinds.
+   *
+   * With `_meta.codex_approval_kind: "mcp_tool_call"` it is a tool permission:
+   * an MCP tool (a ChatGPT app such as GitHub, or a server in the user's
+   * config.toml) that needs a yes before it runs. Codex asks only while the
+   * thread's approval policy is on; under `never` with full access it approves
+   * these itself. It goes to `onUserInputRequest` like every other approval.
+   *
+   * Anything else is an MCP elicitation proper, a form or a URL an MCP server
+   * asks the user to fill in or open, and goes to `onElicitation`.
+   *
+   * The reply must carry `action`. Before this was handled, the generic `{}`
+   * reply was read as a decline, so every app write failed as "user rejected
+   * MCP tool call" with nobody asked.
+   */
+  private async handleMcpElicitation(id: number, params: Record<string, unknown>): Promise<void> {
+    const meta = asObj(params, "_meta");
+    if (str(meta, "codex_approval_kind") === "mcp_tool_call") {
+      await this.handleMcpToolApproval(id, params, meta);
     } else {
-      // Unknown server request. `{}` is a best-effort reply, NOT a guarantee
-      // that the turn proceeds: every server request the protocol defines but
-      // this file does not handle declares required response fields, so an
-      // empty result is schema-invalid for all of them. A JSON-RPC error reply
-      // would be the honest answer, but `rpcResponse` has no error path and
-      // introducing one changes behavior (an error can abort a turn where this
-      // limps along), so that is a deliberate follow-up rather than a fix here.
-      this.rpcResponse(id, {});
+      await this.handleElicitation(id, params);
+    }
+  }
+
+  private async handleMcpToolApproval(
+    id: number,
+    params: Record<string, unknown>,
+    meta: Record<string, unknown>,
+  ): Promise<void> {
+    const requestThreadId = str(params, "threadId") || null;
+    const foreign = this.isForeignThread(requestThreadId);
+    if (!foreign) this._state = "waiting_for_approval";
+    const restore = () => { if (!foreign) this.restoreStateAfter("waiting_for_approval"); };
+
+    // No host handler: allowed, like the command and file-change approvals.
+    if (!this.ctx.onUserInputRequest) {
+      this.rpcResponse(id, { action: "accept" });
+      restore();
+      return;
+    }
+
+    // The request names neither the tool nor the call it gates. The call has
+    // already started (Codex reports `item/started` before it asks), so pair
+    // the two through the in-flight MCP calls.
+    const server = str(params, "serverName");
+    const toolParams = meta["tool_params"];
+    const call = this.findMcpCallForApproval(requestThreadId, server, toolParams);
+    const input = call?.arguments ?? toolParams;
+
+    try {
+      const resp = await this.ctx.onUserInputRequest({
+        toolName: codexMcpToolName(call?.server ?? server, call?.tool ?? null),
+        input: input && typeof input === "object" && !Array.isArray(input)
+          ? input as Record<string, unknown>
+          : {},
+        // The call's item id lines the approval up with its tool_call event,
+        // as `itemId` does for command approvals. Without a match, a fresh id:
+        // hosts key pending approvals on this, so it must never repeat.
+        toolUseId: call?.itemId ?? `codex-mcp-approval-${randomUUID()}`,
+        // Codex's own question, e.g. `Allow GitHub to run tool "create_branch"?`.
+        title: str(params, "message") || undefined,
+        displayName: str(meta, "tool_title") || str(meta, "connector_name") || undefined,
+        description: describeMcpToolParams(meta["tool_params_display"]),
+        ...(foreign && requestThreadId ? { agentId: requestThreadId } : {}),
+      });
+      // A plain accept runs this one call. Codex also offers "for this
+      // session" and "always" (`_meta.persist`), which agentex's yes/no
+      // permission has no way to express, so the host is asked each time.
+      this.rpcResponse(id, { action: resp.allow ? "accept" : "decline" });
+    } catch {
+      this.rpcResponse(id, { action: "decline" });
+    }
+
+    restore();
+  }
+
+  /** An MCP server's form or URL request, for the host's `onElicitation`. Declined without one. */
+  private async handleElicitation(id: number, params: Record<string, unknown>): Promise<void> {
+    if (!this.ctx.onElicitation) {
+      this.rpcResponse(id, { action: "decline" });
+      return;
+    }
+
+    const requestThreadId = str(params, "threadId") || null;
+    const foreign = this.isForeignThread(requestThreadId);
+    if (!foreign) this._state = "waiting_for_input";
+    const restore = () => { if (!foreign) this.restoreStateAfter("waiting_for_input"); };
+
+    const url = str(params, "url");
+    const elicitationId = str(params, "elicitationId");
+    const schema = params["requestedSchema"];
+    try {
+      const resp = await this.ctx.onElicitation({
+        mcpServerName: str(params, "serverName"),
+        message: str(params, "message"),
+        mode: str(params, "mode") === "url" ? "url" : "form",
+        ...(url ? { url } : {}),
+        ...(elicitationId ? { elicitationId } : {}),
+        ...(schema && typeof schema === "object" && !Array.isArray(schema)
+          ? { requestedSchema: schema as Record<string, unknown> }
+          : {}),
+      });
+      this.rpcResponse(id, elicitationReply(resp));
+    } catch {
+      this.rpcResponse(id, { action: "cancel" });
+    }
+
+    restore();
+  }
+
+  /**
+   * Remember the MCP tool calls Codex has started and not finished, on every
+   * thread, so an approval request can be paired with the call it gates.
+   */
+  private trackMcpToolCall(method: string, params: Record<string, unknown>): void {
+    if (method !== "item/started" && method !== "item/completed") return;
+    const item = asObj(params, "item");
+    if (str(item, "type") !== "mcpToolCall") return;
+    const itemId = str(item, "id");
+    if (!itemId) return;
+    if (method === "item/completed") {
+      this._mcpCallsInFlight.delete(itemId);
+      return;
+    }
+    this._mcpCallsInFlight.set(itemId, {
+      itemId,
+      threadId: str(params, "threadId") || null,
+      server: str(item, "server"),
+      tool: str(item, "tool"),
+      arguments: item["arguments"],
+    });
+  }
+
+  /**
+   * The in-flight call an approval is about: on the asking thread and server,
+   * the one whose arguments match the approval's `tool_params`, else the most
+   * recently started (Codex asks right after it starts a call).
+   */
+  private findMcpCallForApproval(
+    threadId: string | null,
+    server: string,
+    toolParams: unknown,
+  ): InFlightMcpCall | null {
+    const candidates = [...this._mcpCallsInFlight.values()].filter((call) =>
+      call.server === server && (!threadId || !call.threadId || call.threadId === threadId));
+    if (toolParams !== undefined) {
+      const wanted = stableJson(toolParams);
+      const exact = candidates.find((call) => stableJson(call.arguments) === wanted);
+      if (exact) return exact;
     }
+    return candidates.at(-1) ?? null;
   }
 
   /**
@@ -1965,6 +2183,7 @@ export class CodexSessionImpl implements AgentSession {
 
   private handleNotification(method: string, params: Record<string, unknown>, rawLine: string): void {
     if (this._state === "closed") return;
+    this.trackMcpToolCall(method, params);
     // codex/event — legacy wrapper
     if (method === "codex/event") {
       const innerMsg = str(params, "msg");