hilos-agent 0.9.0 → 0.9.2

package/src/codex-mcp-session.mjs

@@ -0,0 +1,619 @@
+// Codex runtime-permission adapter (0777).
+//
+// WHAT THE LIVE INVESTIGATION FOUND (codex-cli 0.144.1, never docs-trusted):
+//
+//   • `codex exec` has NO approval channel. `-a/--ask-for-approval` exists on
+//     the INTERACTIVE `codex` only — `codex exec --help` does not list it — and
+//     forcing the policy through config (`codex exec -c approval_policy=
+//     "untrusted" --json`) changes nothing: a blocked command emits no approval
+//     event and no prompt, it just fails inside the sandbox ("Operation not
+//     permitted") and the model is told to try something else. There is no
+//     stdin answer channel and no approval frame in the `--json` stream. So the
+//     exec transport CANNOT be gated, at any flag combination, on this version.
+//
+//   • `codex mcp-server` CAN. Codex-as-an-MCP-server takes `approval-policy` as
+//     a tool argument and asks its CLIENT for the decision as a standard MCP
+//     `elicitation/create` REQUEST, carrying `codex_elicitation:"exec-approval"`,
+//     the `codex_command`, its cwd, and a `codex_call_id`. The client answers
+//     `{"decision":"approved"|"denied"|…}`. Proven end to end both ways: a
+//     denied ask left the file uncreated and the model was told "rejected by
+//     user"; an approved ask — deliberately answered 20 SECONDS late — really
+//     ran, so the call blocks on the human exactly like the other vendors.
+//     (A malformed answer fails closed: codex logs a deserialize error and
+//     treats it as a rejection.)
+//
+// So codex's gate is a transport swap, not a flag. This module is the sibling
+// of acp-session.mjs: same `{status, stdout, stderr, error?, sessionId?,
+// aborted?}` return shape so handler.mjs keeps one seam, and the SAME shared
+// permission gate, so codex cannot become the lenient vendor.
+//
+// `codex-reply` ({threadId, prompt}) is this transport's resume, which is why
+// gated codex runs keep session continuity (0778) instead of trading it away.
+//
+// WHAT THE WIRE CARRIES (0785, probed live against the same 0.144.1 binary):
+// `tools/list` says the `codex` tool takes exactly `prompt`, `model`, `cwd`,
+// `approval-policy`, `sandbox`, `config`, `base-instructions`,
+// `developer-instructions`, `compact-prompt` — `additionalProperties:false`,
+// and the server enforces it. Sending an `images` argument came back
+// `isError:true` with the CLI listing those nine fields as the whole vocabulary,
+// so there is NO image lane on this transport under any spelling.
+//
+//   • MODEL: real. A call with `model:"gpt-5.4-mini"` answered
+//     `session_configured … "model":"gpt-5.4-mini"`, so the run's resolved tier
+//     (0783) reaches a gated run exactly like `--model` reaches an exec one.
+//     `codex-reply` takes ONLY {threadId, prompt} — a resumed thread keeps the
+//     model it was created with, which is why the model rides the first call.
+//   • IMAGES: impossible on the wire, so a gated run degrades HONESTLY — the
+//     files are already on disk (0779) and the prompt names them. Proven live:
+//     given a prompt naming a local png, codex called its own `view_image` tool
+//     on that path and described the picture. The one thing that must NOT
+//     happen is the exec transport's prompt line ("they are attached to this
+//     prompt") on a run where nothing was attached — see `imagesNeedReading`.
+
+import { spawn } from "node:child_process";
+import { createNdjsonParser } from "./acp-session.mjs";
+import { codexUsageEvent } from "./agent-events.mjs";
+import {
+  DEFAULT_PERMISSION_POLL_MS,
+  DEFAULT_PERMISSION_TIMEOUT_MS,
+  resolveHilosPermissionReply,
+} from "./permission-gate.mjs";
+
+const DEFAULT_TIMEOUT_MS = 30 * 60_000;
+const SHUTDOWN_GRACE_MS = 750;
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function abortError(reason = "cancelled") {
+  const error = new Error(String(reason || "cancelled"));
+  error.name = "AbortError";
+  return error;
+}
+
+/**
+ * Render codex's argv-array command as the one line a human decides about.
+ * Codex wraps shell work as ["/bin/zsh","-lc","<the real command>"]; showing
+ * the wrapper would bury the thing being approved.
+ */
+export function codexCommandText(command) {
+  if (typeof command === "string") return command;
+  if (!Array.isArray(command) || command.length === 0) return "";
+  const parts = command.map((c) => String(c ?? ""));
+  const flagIdx = parts.findIndex((p) => p === "-lc" || p === "-c");
+  if (flagIdx >= 0 && parts[flagIdx + 1]) return parts[flagIdx + 1];
+  return parts.join(" ");
+}
+
+/**
+ * Shape a codex elicitation into the SAME vendor-neutral request the other
+ * adapters produce, so one card renders every vendor's ask.
+ */
+export function normalizeCodexPermissionRequest(params, fallbackId = "0") {
+  const kind = typeof params?.codex_elicitation === "string" ? params.codex_elicitation : "";
+  const command = codexCommandText(params?.codex_command);
+  const cwd = typeof params?.codex_cwd === "string" ? params.codex_cwd : null;
+  const vendorRequestId =
+    typeof params?.codex_call_id === "string" && params.codex_call_id
+      ? params.codex_call_id
+      : `codex_${fallbackId}`;
+  const message = typeof params?.message === "string" ? params.message : "";
+  const title = command || message || kind || "permission";
+  const isPatch = kind === "patch-approval" || kind === "apply-patch-approval";
+  return {
+    vendor: "codex",
+    vendorRequestId,
+    sessionId: typeof params?.threadId === "string" ? params.threadId : "",
+    action: isPatch ? "edit" : "execute",
+    resources: command ? [command] : [],
+    suggestedSave: undefined,
+    metadata: {
+      title,
+      ...(command ? { command } : {}),
+      ...(cwd ? { cwd } : {}),
+      ...(kind ? { kind } : {}),
+      transport: "codex-mcp",
+    },
+    source: { type: "tool", name: isPatch ? "apply_patch" : "exec" },
+  };
+}
+
+/**
+ * Map a hilos reply onto codex's ReviewDecision vocabulary.
+ *
+ * A single-use approval is NEVER widened into a session-wide one: "once" must
+ * answer plain `approved` even though `approved_for_session` is on offer. The
+ * reverse direction is safe — an `always` with no session option narrows to a
+ * one-shot approval rather than persisting something nobody agreed to.
+ * A rejection is `denied` (the agent continues and tries something else), never
+ * `abort`, which would kill work a human only meant to redirect.
+ */
+export function mapCodexDecision(reply, availableDecisions) {
+  const available = Array.isArray(availableDecisions)
+    ? availableDecisions.filter((d) => typeof d === "string")
+    : [];
+  const offers = (value) => available.length === 0 || available.includes(value);
+  if (reply === "once") return "approved";
+  if (reply === "always") return offers("approved_for_session") ? "approved_for_session" : "approved";
+  return "denied";
+}
+
+/**
+ * Run one prompt against `codex mcp-server`, gated by hilos permission cards.
+ *
+ * @param {{
+ *   cmd?: string,
+ *   serverArgs?: string[],
+ *   cwd?: string,
+ *   prompt?: string,
+ *   env?: Record<string, string | undefined>,
+ *   model?: string | null,
+ *   sandbox?: string,
+ *   approvalPolicy?: string,
+ *   resumeThreadId?: string | null,
+ *   timeoutMs?: number,
+ *   pollIntervalMs?: number,
+ *   signal?: AbortSignal,
+ *   onData?: (chunk: string) => void,
+ *   onEvent?: (event: object) => void,
+ *   requestPermission?: (request: object, context: object) => Promise<unknown>,
+ *   getPermissionDecision?: (handle: unknown, context: object) => Promise<unknown>,
+ *   spawnImpl?: typeof spawn,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   now?: () => number,
+ *   log?: { error?: (message: string) => void },
+ * }} [options]
+ * @returns {Promise<{ status: number|null, stdout: string, stderr: string, error?: Error|null, sessionId?: string|null, initialized: boolean, sawFrame: boolean, exitCode: number|null, timedOut?: boolean, aborted?: boolean }>}
+ */
+export async function runCodexMcpSession({
+  cmd = "codex",
+  serverArgs = ["mcp-server"],
+  cwd = process.cwd(),
+  prompt = "",
+  env,
+  model = null,
+  sandbox = "workspace-write",
+  approvalPolicy = "untrusted",
+  resumeThreadId = null,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  pollIntervalMs = DEFAULT_PERMISSION_POLL_MS,
+  signal,
+  onData,
+  onEvent,
+  requestPermission,
+  getPermissionDecision,
+  spawnImpl = spawn,
+  sleep,
+  now = () => Date.now(),
+  log,
+} = {}) {
+  if (typeof requestPermission !== "function" || typeof getPermissionDecision !== "function") {
+    throw new Error("codex mcp session requires hilos permission callbacks");
+  }
+
+  const controller = new AbortController();
+  const onOuterAbort = () => controller.abort(signal?.reason ?? "cancelled");
+  if (signal?.aborted) onOuterAbort();
+  else signal?.addEventListener("abort", onOuterAbort, { once: true });
+
+  const child = spawnImpl(cmd, serverArgs, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+  const parser = createNdjsonParser();
+  const pending = new Map();
+  const approvals = new Map(); // codex call_id → its available decisions
+  const messages = [];
+  let stderr = "";
+  let sessionId = null;
+  let spawnError = null;
+  let nextId = 1;
+  let aborted = false;
+  let timedOut = false;
+  // The three facts a caller needs to tell "this codex has no mcp-server" from
+  // "this codex's mcp-server failed" (0785): did it complete the handshake, did
+  // it speak MCP AT ALL, and how did it exit. All three are necessary — see
+  // codexMcpTransportUnavailable.
+  let initialized = false;
+  let sawFrame = false;
+  let exitCode = null;
+
+  const write = (frame) => {
+    if (child.stdin.destroyed) return;
+    try {
+      child.stdin.write(JSON.stringify(frame) + "\n");
+    } catch {
+      /* a dead pipe surfaces through the exit path */
+    }
+  };
+  const respond = (id, result) => write({ jsonrpc: "2.0", id, result });
+  /**
+   * Reject everything still waiting on an answer.
+   *
+   * A child that exits normally, or is killed by a signal, emits `close` and
+   * NOT `error` — so without this, an in-flight `initialize` or `tools/call`
+   * would simply never settle and the run's task queue would hang forever
+   * behind a dead process. Cancellation and timeout land here too.
+   */
+  const failPending = (reason) => {
+    if (pending.size === 0) return;
+    const error = new Error(reason);
+    for (const [, entry] of pending) entry.reject(error);
+    pending.clear();
+  };
+  const rpc = (method, params) =>
+    new Promise((resolve, reject) => {
+      const id = nextId++;
+      pending.set(id, { resolve, reject });
+      write({ jsonrpc: "2.0", id, method, params });
+    });
+
+  const emit = (event) => {
+    if (!onEvent || !event) return;
+    try {
+      onEvent(event);
+    } catch {
+      /* narration must never break the run */
+    }
+  };
+  const feed = (text) => {
+    if (!onData || !text) return;
+    try {
+      onData(text);
+    } catch {
+      /* progress must never break the run */
+    }
+  };
+
+  async function settleElicitation(msg) {
+    const params = isObject(msg.params) ? msg.params : {};
+    const request = normalizeCodexPermissionRequest(params, String(msg.id));
+    const available = approvals.get(request.vendorRequestId) ?? null;
+    const { reply } = await resolveHilosPermissionReply({
+      request,
+      requestPermission,
+      getPermissionDecision,
+      signal: controller.signal,
+      timeoutMs,
+      pollIntervalMs,
+      sleep,
+      now,
+      log,
+      label: "codex permission",
+    });
+    respond(msg.id, { decision: mapCodexDecision(reply, available) });
+  }
+
+  function handleEvent(msg) {
+    if (!isObject(msg)) return;
+    const type = typeof msg.type === "string" ? msg.type : "";
+    if (type === "session_configured") {
+      const id = msg.thread_id || msg.session_id;
+      if (typeof id === "string" && id) sessionId = id;
+      return;
+    }
+    if (type === "exec_approval_request") {
+      // Recorded only to learn which decisions this ask actually offers; the
+      // elicitation request is the thing that blocks and gets answered.
+      if (typeof msg.call_id === "string") {
+        approvals.set(msg.call_id, Array.isArray(msg.available_decisions) ? msg.available_decisions : null);
+      }
+      const command = codexCommandText(msg.command);
+      if (command) emit({ t: "run", cmd: command });
+      return;
+    }
+    // 0787 — this transport's usage frame. `codex exec --json` prices a run on
+    // `turn.completed`; the MCP server never sends that envelope at all, so a
+    // gated codex run (the DEFAULT once a workspace is granted runtime
+    // permissions) reported nothing. It sends `token_count` instead, once per
+    // API call, and the distinction in it matters:
+    //
+    //   {"type":"token_count","info":{
+    //      "total_token_usage":{"input_tokens":36419,"cached_input_tokens":24064,
+    //        "output_tokens":154,"reasoning_output_tokens":0,"total_tokens":36573},
+    //      "last_token_usage":{"input_tokens":18309,"cached_input_tokens":17152,
+    //        "output_tokens":27,…},"model_context_window":258400}, "rate_limits":{…}}
+    //
+    // `total_token_usage` is CUMULATIVE for the thread and `last_token_usage`
+    // is the delta for the call that just finished. Live-captured on a
+    // two-call run, the deltas sum to the total exactly (18110+18309=36419 in,
+    // 6912+17152=24064 cached, 127+27=154 out), so folding the deltas is both
+    // correct and additive — folding the totals would have billed 54,529 input
+    // tokens for a run that used 36,419. Deltas are also the only safe read
+    // across `codex-reply`, where a resumed thread's cumulative figure may
+    // already include a previous turn hilos never ran.
+    if (type === "token_count") {
+      const usage = isObject(msg.info) ? msg.info.last_token_usage : null;
+      const event = codexUsageEvent(usage);
+      if (event) emit(event);
+      return;
+    }
+    if (type === "agent_message_content_delta" && typeof msg.delta === "string") {
+      feed(msg.delta);
+      return;
+    }
+    if (type === "agent_message" && typeof msg.message === "string") {
+      messages.push(msg.message);
+      return;
+    }
+    if (type === "item_started" || type === "item_completed") {
+      const item = isObject(msg.item) ? msg.item : {};
+      if (type === "item_started" && item.type === "CommandExecution") {
+        const command = codexCommandText(item.command);
+        if (command) emit({ t: "run", cmd: command });
+      }
+      if (type === "item_completed" && item.type === "FileChange") {
+        const changes = Array.isArray(item.changes) ? item.changes : [];
+        for (const change of changes) {
+          const p = isObject(change) && typeof change.path === "string" ? change.path : null;
+          if (p) emit({ t: "edit", path: p });
+        }
+      }
+    }
+  }
+
+  function handleMessage(msg) {
+    // Server → client REQUEST (has both id and method): the approval lane.
+    if (msg.id !== undefined && typeof msg.method === "string") {
+      if (msg.method === "elicitation/create") {
+        void settleElicitation(msg).catch((error) => {
+          log?.error?.(`codex elicitation: ${error?.message ?? error}`);
+          // Fail closed — never leave codex blocked on an unanswered ask.
+          respond(msg.id, { decision: "denied" });
+        });
+        return;
+      }
+      // Any other server request is answered with a refusal rather than left
+      // hanging; an unknown ask is not something hilos can consent to.
+      respond(msg.id, { decision: "denied" });
+      return;
+    }
+    if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+      const entry = pending.get(msg.id);
+      if (!entry) return;
+      pending.delete(msg.id);
+      if (msg.error) entry.reject(new Error(msg.error?.message ?? "codex rpc error"));
+      else entry.resolve(msg.result);
+      return;
+    }
+    if (msg.method === "codex/event") {
+      handleEvent(isObject(msg.params?.msg) ? msg.params.msg : null);
+    }
+  }
+
+  child.stdout?.setEncoding?.("utf8");
+  child.stdout?.on("data", (chunk) => {
+    for (const msg of parser.push(chunk)) {
+      // One well-formed frame is proof this process IS an MCP server, whatever
+      // goes wrong afterwards.
+      sawFrame = true;
+      try {
+        handleMessage(msg);
+      } catch (error) {
+        log?.error?.(`codex frame: ${error?.message ?? error}`);
+      }
+    }
+  });
+  child.stderr?.setEncoding?.("utf8");
+  child.stderr?.on("data", (chunk) => {
+    stderr += chunk;
+    if (stderr.length > 200_000) stderr = stderr.slice(-100_000);
+  });
+  child.on("error", (error) => {
+    spawnError = error;
+    for (const [, entry] of pending) entry.reject(error);
+    pending.clear();
+  });
+
+  const exited = new Promise((resolve) =>
+    child.on("close", (code) => {
+      exitCode = code;
+      failPending(`codex mcp-server exited (${code}) with a request in flight`);
+      resolve(code);
+    }),
+  );
+  // Some fakes and some runtimes emit only `exit`; either one means no answer
+  // is coming.
+  child.on("exit", (code) => failPending(`codex mcp-server exited (${code}) with a request in flight`));
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort("timeout");
+  }, Math.max(1, timeoutMs || DEFAULT_TIMEOUT_MS));
+  const onAbort = () => {
+    aborted = true;
+    // Reject first, then kill: a cancelled or timed-out run must stop waiting
+    // on answers immediately, not depend on the child's exit arriving.
+    failPending(timedOut ? "codex session timed out" : "codex session cancelled");
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      /* already gone */
+    }
+    setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* already gone */
+      }
+    }, SHUTDOWN_GRACE_MS).unref?.();
+  };
+  controller.signal.addEventListener("abort", onAbort, { once: true });
+
+  let status = null;
+  let error = null;
+  try {
+    await rpc("initialize", {
+      protocolVersion: "2025-06-18",
+      // Declaring elicitation is what makes codex ask US instead of deciding
+      // for itself — without it there is no gate.
+      capabilities: { elicitation: {} },
+      clientInfo: { name: "hilos-agent", version: "1.0.0" },
+    });
+    initialized = true;
+    write({ jsonrpc: "2.0", method: "notifications/initialized" });
+    // `codex-reply` takes {threadId, prompt} and nothing else (its schema, live)
+    // — a resumed thread already runs on the model its first call configured,
+    // so there is nothing to re-send and nothing lost by not sending it.
+    const toolCall = resumeThreadId
+      ? { name: "codex-reply", arguments: { threadId: resumeThreadId, prompt } }
+      : {
+          name: "codex",
+          arguments: {
+            prompt,
+            cwd,
+            "approval-policy": approvalPolicy,
+            sandbox,
+            ...(model ? { model } : {}),
+          },
+        };
+    if (resumeThreadId) sessionId = resumeThreadId;
+    const result = await rpc("tools/call", { name: toolCall.name, arguments: toolCall.arguments });
+    status = result?.isError === true ? 1 : 0;
+  } catch (callError) {
+    error = spawnError ?? callError;
+    status = null;
+  } finally {
+    clearTimeout(timer);
+    controller.signal.removeEventListener("abort", onAbort);
+    signal?.removeEventListener("abort", onOuterAbort);
+    try {
+      child.stdin.end();
+    } catch {
+      /* already closed */
+    }
+    if (!controller.signal.aborted) {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        /* already gone */
+      }
+    }
+    await exited;
+  }
+
+  if (spawnError) error = spawnError;
+  if (timedOut && !error) error = new Error("codex session timed out");
+  // Cancellation and timeout both tear the child down, but only a cancellation
+  // is "aborted" — a timeout is a failed run and must read as one.
+  const cancelled = aborted && Boolean(signal?.aborted) && !timedOut;
+  const stdout = messages.join("\n\n").trim();
+  return {
+    status: error ? null : status,
+    stdout,
+    stderr,
+    error: error ?? null,
+    sessionId,
+    initialized,
+    sawFrame,
+    exitCode,
+    ...(timedOut ? { timedOut: true } : {}),
+    ...(cancelled ? { aborted: true } : {}),
+  };
+}
+
+/**
+ * The one thing a codex WITHOUT `mcp-server` says, and nothing else does.
+ *
+ * A CLI too old to have the subcommand doesn't reject it — it forwards the
+ * unrecognized word to the interactive TUI as a PROMPT, which then finds our
+ * pipe where it wanted a terminal. Captured verbatim off codex 0.144.1 by
+ * handing the real binary a subcommand it doesn't have:
+ *
+ *   exit=1  frames=0  stdout=""  stderr="Error: stdin is not a terminal\n"
+ *
+ * The second pattern is not live-observed on any build I have (0.144.1 forwards
+ * unknown subcommands rather than erroring on them) but is accepted because it
+ * is still the CLI positively saying the subcommand does not exist, which is
+ * the only claim this matcher is allowed to act on.
+ */
+const CODEX_NO_MCP_SERVER_RE = /stdin is not a terminal|unrecognized subcommand|unknown subcommand/i;
+
+/**
+ * Did this run fail because the CLI has no `mcp-server` at all (0785)?
+ *
+ * This gate fails CLOSED, and the asymmetry is the whole reason: a wrongly
+ * failed run is recoverable — a human sees it and runs it again — while a
+ * wrongly UNGATED run has already executed the commands nobody approved. So
+ * "the handshake didn't happen" is NOT enough. It has to be positive evidence
+ * that the subcommand is absent, because failures that say nothing about the
+ * subcommand look identical from the outside. All three of these are exit 1
+ * with zero frames and no handshake, live-captured:
+ *
+ *   • missing subcommand  → "Error: stdin is not a terminal"
+ *   • broken -c override  → "Error: error parsing -c overrides: …"
+ *   • unreadable CODEX_HOME → "Error: error loading config: …"
+ *
+ * Only the first may degrade. The other two are failed runs and are reported as
+ * such — as is a cancelled run, a timed-out run, a missing binary (ENOENT: there
+ * is nothing to degrade TO), anything that spoke a single MCP frame, and any
+ * failure after a successful handshake.
+ *
+ * @param {{ initialized?: boolean, sawFrame?: boolean, exitCode?: number|null,
+ *   stderr?: string, aborted?: boolean, timedOut?: boolean,
+ *   error?: (Error & {code?: string})|null }} [run]
+ */
+export function codexMcpTransportUnavailable(run) {
+  if (!run || run.initialized || run.aborted || run.timedOut) return false;
+  if (!run.error) return false;
+  if (run.error.code === "ENOENT") return false;
+  // It spoke MCP, so the subcommand exists whatever went wrong next.
+  if (run.sawFrame) return false;
+  // It has to have actually exited, and not cleanly.
+  if (typeof run.exitCode !== "number" || run.exitCode === 0) return false;
+  return CODEX_NO_MCP_SERVER_RE.test(String(run.stderr || ""));
+}
+
+/**
+ * Does this run get the codex permission gate?
+ *
+ * Same rule as every other vendor: runtime permissions granted, and a run
+ * configured to answer its own asks (the `skip` tier's bypass flag) is left
+ * alone. Codex's sandbox tiers are NOT an escape hatch — `workspace-write`
+ * still escalates out-of-workspace work to an ask, which is the whole point.
+ *
+ * @param {{ vendor?: string, runtimePermissions?: boolean, codeArgs?: string[] }} o
+ */
+export function shouldGateCodexPermissions({ vendor, runtimePermissions, codeArgs = [] }) {
+  if (vendor !== "codex" || runtimePermissions !== true) return false;
+  const args = Array.isArray(codeArgs) ? codeArgs : [];
+  if (args.includes("--dangerously-bypass-approvals-and-sandbox")) return false;
+  return true;
+}
+
+/** The sandbox tiers codex actually accepts. */
+const CODEX_SANDBOXES = new Set(["read-only", "workspace-write", "danger-full-access"]);
+
+/**
+ * The codex sandbox tier implied by the run's argv, so the gated transport
+ * keeps the operator's chosen posture instead of silently widening it.
+ *
+ * Both spellings count: `--sandbox read-only` and `--sandbox=read-only` (and
+ * the `-s` short forms), because a config that said read-only and quietly got
+ * workspace-write is the one failure this function must never produce. When a
+ * sandbox flag IS present but its value is missing or unrecognized, the answer
+ * is the TIGHTEST tier, not the default — an unreadable intent is never
+ * grounds for widening. Only the absence of any flag falls back.
+ *
+ * @param {string[]} [codeArgs]
+ * @param {string} [fallback]
+ */
+export function codexSandboxFromArgs(codeArgs = [], fallback = "workspace-write") {
+  const args = (Array.isArray(codeArgs) ? codeArgs : []).map((a) => String(a ?? ""));
+  let raw = null;
+  let sawFlag = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--sandbox" || arg === "-s") {
+      sawFlag = true;
+      raw = args[i + 1] ?? null;
+      continue;
+    }
+    const eq = /^(?:--sandbox|-s)=(.*)$/.exec(arg);
+    if (eq) {
+      sawFlag = true;
+      raw = eq[1];
+    }
+  }
+  if (!sawFlag) return fallback;
+  const value = (raw ?? "").trim();
+  // A flag whose value we cannot read fails CLOSED.
+  return CODEX_SANDBOXES.has(value) ? value : "read-only";
+}