@minhspark/codex-mcp-bridge 1.10.1 → 1.11.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [1.11.0] - 2026-08-23
+
+### Added
+
+- `CODEX_BRIDGE_THREAD_POLICY` selects what authorizes a thread: `owned` (unchanged default) or `roots`.
+
+  Under the only behaviour that existed before, a thread opened in the Codex app or the VS Code extension
+  was not merely restricted - it was unreachable. Codex assigns the thread ID at the moment it opens, so
+  the ID cannot have been listed in `CODEX_BRIDGE_ALLOWED_THREADS` beforehand, and the bridge-owned set
+  lives in memory and empties on every MCP server restart. The listing showed those threads, because
+  listing is gated on the workspace, and then every send into one answered `not authorized`. On a machine
+  with ten live threads, nine of them were unreachable and the tenth only because the bridge had just
+  created it.
+
+  `roots` grants on the workspace instead of the ID: a thread already working inside a directory named in
+  `CODEX_BRIDGE_ALLOWED_ROOTS` is reachable. That is the same containment every tool already enforces on
+  the `cwd` it is handed, applied to the `cwd` the thread reports. It is opt-in so an existing install
+  cannot widen silently on upgrade, and an unknown workspace fails closed exactly like one outside the
+  roots.
+
+### Fixed
+
+- Authorization now happens **before** `thread/resume`. Attaching takes the per-thread writer lock away
+  from whoever else has the thread open, so deciding afterwards would have locked a thread on its way to
+  being refused.
+- `openInApp` no longer raises a thread on screen before that thread is known to be in scope - a refusal
+  that leaked which threads exist.
+- `codex_bridge_status` printed the approval policy under a `thread policy` label. Two different settings:
+  one was misreported, the other invisible. It now names both.
+- The `NOT AUTHORIZED` line in `list_codex_threads` pointed only at `CODEX_BRIDGE_ALLOWED_THREADS`, which
+  is the option that cannot work for a thread a human just opened. It now names the policy as well.
+
 ## [1.10.1] - 2026-08-20
 
 ### Fixed

package/README.md

@@ -262,7 +262,16 @@ On macOS and Linux the `codex` launcher is a Node script with a `#!/usr/bin/env
 
 `send_to_codex_thread` also accepts `timeoutSec` (default 240), `cwd`, `model`, `effort`, and `openInApp` (macOS — surface the thread in the desktop app before sending). A timeout does **not** cancel the turn: the bridge returns what it collected plus the `turnId`; keep reading with `read_codex_thread` or stop it with `interrupt_codex_turn`.
 
-Thread operations are deny-by-default. Set `CODEX_BRIDGE_ALLOWED_THREADS` to a comma-separated list of exact thread IDs you want this MCP server to access; threads created by `start_codex_thread` are authorized for the lifetime of this bridge process. Set `CODEX_BRIDGE_ALLOWED_ROOTS` to the absolute project directories the bridge may use. The installer defaults that root to this repository, so change it when delegating into another project.
+Thread operations are deny-by-default, and `CODEX_BRIDGE_THREAD_POLICY` decides what counts as permission:
+
+| Policy | A thread is reachable when | Use it when |
+|---|---|---|
+| `owned` *(default)* | the bridge created it with `start_codex_thread`, or its exact ID is listed in `CODEX_BRIDGE_ALLOWED_THREADS` | the bridge drives threads it opens itself |
+| `roots` | it is working inside a directory named in `CODEX_BRIDGE_ALLOWED_ROOTS` | you open threads in the Codex app or VS Code and want Claude to talk to them |
+
+Under `owned`, a thread a human opened is **unreachable rather than merely restricted**: Codex assigns its ID at the moment it opens, so the ID cannot have been allowlisted beforehand, and the bridge-owned set lives in memory and empties whenever the MCP server restarts. If every live thread answers `NOT AUTHORIZED`, that is the cause — switch to `roots`.
+
+`roots` does not remove a gate; it moves it from the ID to the workspace, which is the containment every tool already applies to the `cwd` it is handed. The bridge resolves a thread's workspace with a read **before** attaching, so a thread outside every root is refused without ever taking its writer lock. Set `CODEX_BRIDGE_ALLOWED_ROOTS` to the absolute project directories the bridge may use — the installer defaults that root to this repository, so change it when delegating into another project. A root as broad as `/` or `C:\` makes `roots` mean *every thread on this machine*.
 
 ## Tools — `claude-bridge` (runs inside Codex)
 
@@ -364,6 +373,7 @@ The bridge reads these from the environment its MCP client hands it — there is
 | `CODEX_APP_SERVER_URL` | `ws://127.0.0.1:8791` | Shared **loopback-only** app-server endpoint. Non-loopback endpoints are rejected because this bridge does not implement remote WebSocket authentication. |
 | `CODEX_BIN` | auto-detected | Path to `codex` used for autostart. |
 | `CODEX_BRIDGE_AUTOSTART` | `1` | `0` = never spawn an app-server; one must already be running. |
+| `CODEX_BRIDGE_THREAD_POLICY` | `owned` | What authorizes a thread: `owned` (created by this bridge, or listed in `CODEX_BRIDGE_ALLOWED_THREADS`) or `roots` (working inside `CODEX_BRIDGE_ALLOWED_ROOTS`). Default is unchanged on upgrade, so an existing install never widens by itself. |
 | `CODEX_BRIDGE_ALLOWED_THREADS` | empty | Exact comma-separated thread IDs permitted for read/send/interrupt/open/list. Empty means no pre-existing thread access. |
 | `CODEX_BRIDGE_ALLOWED_ROOTS` | empty (installer sets its repo root) | Absolute project directories permitted for `cwd`, separated by `:` (`;` on Windows). |
 | `CODEX_BRIDGE_APPROVAL` | `deny` | How to answer approval requests from Codex. `approve` is ignored unless `CODEX_BRIDGE_AUTO_APPROVE_ACK=1` is also set. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",

package/src/claude-bridge.mjs

@@ -8,7 +8,7 @@ import { PLATFORM_LABEL } from "./platform.mjs";
 import { PeerEndpoint, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
 import { runTurn } from "./turn.mjs";
 
-const VERSION = "1.10.1";
+const VERSION = "1.11.0";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 

package/src/index.mjs

@@ -19,7 +19,7 @@ import {
 import { runTurn } from "./turn.mjs";
 import { BridgeSecurityPolicy } from "./security-policy.mjs";
 
-const VERSION = "1.10.1";
+const VERSION = "1.11.0";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -43,14 +43,38 @@ const textResult = (text, isError = false) => ({
 
 const failure = (err) => textResult(`Codex bridge error: ${err?.message ?? String(err)}`, true);
 
+/**
+ * Decides whether this bridge may act on a thread, before anything acts on it.
+ *
+ * Under `roots` the answer depends on where the thread works, which only
+ * `thread/read` reports - and it must be asked before `thread/resume`, because
+ * resuming takes the per-thread writer lock away from whoever else has the
+ * thread open. Reading first means a thread outside every root is refused
+ * without ever being locked. A thread the bridge already owns or the operator
+ * allowlisted skips the round-trip entirely: its answer cannot change.
+ */
+async function assertThreadAccess(threadId) {
+  if (security.isThreadAuthorized(threadId)) return null;
+  if (security.threadPolicy !== "roots") {
+    security.assertThread(threadId);
+    return null;
+  }
+  const res = await client.call("thread/read", { threadId });
+  const thread = res?.thread ?? res ?? {};
+  security.assertThread(threadId, thread.cwd);
+  security.assertCwd(thread.cwd);
+  return thread;
+}
+
 function formatThreadRow(t) {
   const title = t.name || (t.preview ?? "").replace(/\s+/g, " ").slice(0, 70) || "(no title)";
   const updated = t.updatedAt ? new Date(t.updatedAt * 1000).toISOString().replace("T", " ").slice(0, 16) : "?";
   const status = t.status?.type ?? "?";
   const deepLink = IS_MACOS && hasCodexDesktopApp() ? `\n    open: ${codexThreadUrl(t.id)}` : "";
-  const authorized = security.isThreadAuthorized(t.id)
+  const authorized = security.isThreadAuthorized(t.id, t.cwd)
     ? ""
-    : "\n    NOT AUTHORIZED: add this id to CODEX_BRIDGE_ALLOWED_THREADS to send into it";
+    : "\n    NOT AUTHORIZED: add this id to CODEX_BRIDGE_ALLOWED_THREADS, or set " +
+      "CODEX_BRIDGE_THREAD_POLICY=roots to reach every thread inside an allowed root";
   return `- ${t.id}\n    title: ${title}\n    cwd: ${t.cwd ?? "?"}\n    updated: ${updated}  status: ${status}  source: ${t.source ?? "?"}${deepLink}${authorized}`;
 }
 
@@ -143,14 +167,7 @@ server.registerTool(
   async ({ threadId, prompt, timeoutSec, cwd, model, effort, openInApp }) => {
     let openNote = null;
     try {
-      security.assertThread(threadId);
-      if (openInApp) {
-        try {
-          openNote = `opened in Codex app: ${await openThreadInCodexApp(threadId)}`;
-        } catch (err) {
-          openNote = `could not open the thread in the Codex app: ${err.message}`;
-        }
-      }
+      await assertThreadAccess(threadId);
       let resolvedCwd = null;
       if (cwd) {
         const workspace = resolveWorkspacePath(cwd);
@@ -160,6 +177,18 @@ server.registerTool(
       }
       const attached = await client.ensureThreadAttached(threadId, resolvedCwd ? { cwd: resolvedCwd } : {});
       security.assertCwd(attached.thread?.cwd);
+      /**
+       * Opening the thread in the app comes after both gates. It ran first
+       * once, which meant a thread this bridge was about to refuse still got
+       * raised on screen - a refusal that leaked which threads exist.
+       */
+      if (openInApp) {
+        try {
+          openNote = `opened in Codex app: ${await openThreadInCodexApp(threadId)}`;
+        } catch (err) {
+          openNote = `could not open the thread in the Codex app: ${err.message}`;
+        }
+      }
       const result = await runTurn(client, {
         threadId,
         input: [{ type: "text", text: prompt }],
@@ -291,7 +320,7 @@ server.registerTool(
   },
   async ({ threadId, limit }) => {
     try {
-      security.assertThread(threadId);
+      await assertThreadAccess(threadId);
       const res = await client.call("thread/read", { threadId, includeTurns: true });
       const thread = res?.thread ?? res ?? {};
       security.assertCwd(thread.cwd);
@@ -334,7 +363,7 @@ server.registerTool(
   },
   async ({ threadId, turnId }) => {
     try {
-      security.assertThread(threadId);
+      await assertThreadAccess(threadId);
       const thread = await client.call("thread/read", { threadId });
       security.assertCwd((thread?.thread ?? thread)?.cwd);
       await client.call("turn/interrupt", { threadId, turnId });
@@ -368,7 +397,7 @@ server.registerTool(
   },
   async ({ threadId, background }) => {
     try {
-      security.assertThread(threadId);
+      await assertThreadAccess(threadId);
       const thread = await client.call("thread/read", { threadId });
       security.assertCwd((thread?.thread ?? thread)?.cwd);
       const url = await openThreadInCodexApp(threadId, { activate: !background });
@@ -442,7 +471,7 @@ server.registerTool(
       `defaults:       model ${DEFAULT_MODEL ?? "(from ~/.codex/config.toml)"}, effort ${DEFAULT_EFFORT ?? "(from ~/.codex/config.toml)"}`,
       `app-server:     ${client.url} - ${up ? "live" : "not reachable"}`,
       `autostart:      ${client.autoStart ? "on" : "off"}   approvals: ${client.approval}`,
-      `security:       ${security.summary().authorizedThreads} authorized thread(s), ${security.summary().allowedRoots.length} allowed root(s), sandbox ${security.sandbox}, thread policy ${security.approvalPolicy}`,
+      `security:       thread policy ${security.threadPolicy} (${security.summary().authorizedThreads} pre-authorized thread(s)), ${security.summary().allowedRoots.length} allowed root(s), sandbox ${security.sandbox}, approvals ${security.approvalPolicy}`,
       `live threads:   ${liveThreads ?? "(unknown)"}`,
       `claude desktop config: ${claudeDesktopConfigPath()}`,
     ];

package/src/security-policy.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 
 const APPROVAL_POLICIES = new Set(["untrusted", "on-failure", "on-request", "never"]);
 const SANDBOXES = new Set(["read-only", "workspace-write"]);
+const THREAD_POLICIES = new Set(["owned", "roots"]);
 
 /**
  * Resolves the deepest ancestor that exists and re-appends the rest, rather
@@ -81,6 +82,30 @@ export class BridgeSecurityPolicy {
     this.allowedRoots = parseRoots(env.CODEX_BRIDGE_ALLOWED_ROOTS);
     this.ownedThreadIds = new Set();
 
+    /**
+     * Which threads this bridge may act on, beyond the ones it created itself.
+     *
+     * `owned` was the only behaviour until now, and it does not merely
+     * restrict the everyday workflow - it makes it impossible. A thread opened
+     * in the Codex app or the VS Code extension is given its id at that
+     * moment, so it can never have appeared in CODEX_BRIDGE_ALLOWED_THREADS
+     * beforehand; and the bridge-owned set lives in memory, so it empties
+     * every time the MCP server restarts. That left the operator allowlisting
+     * an id that is already stale by the next turn, and every thread a human
+     * actually opened answered "not authorized".
+     *
+     * `roots` grants on the workspace instead of the id: a thread already
+     * working inside a directory the operator declared in scope is reachable.
+     * This is not a weaker gate bolted on - it is the same containment every
+     * acting tool already enforces on the cwd it is handed, applied to the cwd
+     * the thread itself reports. It stays opt-in so an existing install cannot
+     * widen silently on upgrade.
+     */
+    this.threadPolicy = env.CODEX_BRIDGE_THREAD_POLICY ?? "owned";
+    if (!THREAD_POLICIES.has(this.threadPolicy)) {
+      throw new Error(`CODEX_BRIDGE_THREAD_POLICY must be owned or roots: ${this.threadPolicy}`);
+    }
+
     this.approvalPolicy = env.CODEX_BRIDGE_APPROVAL_POLICY ?? "on-request";
     if (!APPROVAL_POLICIES.has(this.approvalPolicy)) {
       throw new Error(`Invalid CODEX_BRIDGE_APPROVAL_POLICY: ${this.approvalPolicy}`);
@@ -96,18 +121,49 @@ export class BridgeSecurityPolicy {
     if (threadId) this.ownedThreadIds.add(threadId);
   }
 
-  isThreadAuthorized(threadId) {
-    return this.ownedThreadIds.has(threadId) || this.allowedThreadIds.has(threadId);
+  /**
+   * `cwd` is optional because the id almost always arrives before the
+   * workspace does: a caller holds an id from a listing, and the cwd is only
+   * known once the thread has been read. Under `owned` the answer never
+   * depended on the workspace, so omitting it changes nothing. Under `roots`
+   * an unknown workspace is never a grant - a thread that cannot be placed
+   * inside a root is refused exactly like one placed outside it.
+   */
+  isThreadAuthorized(threadId, cwd) {
+    if (this.ownedThreadIds.has(threadId) || this.allowedThreadIds.has(threadId)) return true;
+    if (this.threadPolicy !== "roots") return false;
+    return cwd == null ? false : this.isCwdAuthorized(cwd);
   }
 
-  assertThread(threadId) {
-    if (this.isThreadAuthorized(threadId)) return;
+  assertThread(threadId, cwd) {
+    if (this.isThreadAuthorized(threadId, cwd)) return;
+
+    if (this.threadPolicy === "roots") {
+      /**
+       * Refused here rather than waved through to a later cwd check, because
+       * the caller has to attach to a thread before it can act on it, and
+       * attaching takes the per-thread writer lock away from whoever else has
+       * the thread open. Deciding afterwards would mean a thread outside every
+       * root still got locked on the way to being rejected.
+       */
+      throw new Error(
+        cwd == null
+          ? `Codex thread ${threadId} reports no workspace, so it cannot be matched against CODEX_BRIDGE_ALLOWED_ROOTS`
+          : `Codex thread ${threadId} works in ${cwd}, which is outside CODEX_BRIDGE_ALLOWED_ROOTS`,
+      );
+    }
+
     if (!this.allowedThreadIds.size && !this.ownedThreadIds.size) {
       throw new Error(
-        "No authorized Codex threads are configured. Set CODEX_BRIDGE_ALLOWED_THREADS or create a thread with start_codex_thread.",
+        "No authorized Codex threads are configured. Set CODEX_BRIDGE_ALLOWED_THREADS, create one with " +
+          "start_codex_thread, or set CODEX_BRIDGE_THREAD_POLICY=roots to reach any thread already working " +
+          "inside CODEX_BRIDGE_ALLOWED_ROOTS.",
       );
     }
-    throw new Error(`Codex thread ${threadId} is not authorized for this bridge`);
+    throw new Error(
+      `Codex thread ${threadId} is not authorized for this bridge. Add it to CODEX_BRIDGE_ALLOWED_THREADS, ` +
+        "or set CODEX_BRIDGE_THREAD_POLICY=roots to reach any thread inside CODEX_BRIDGE_ALLOWED_ROOTS.",
+    );
   }
 
   /**
@@ -115,8 +171,8 @@ export class BridgeSecurityPolicy {
    * both ways left no path to a thread id at all: you cannot allowlist a
    * thread whose id you have no way to learn, so the only usable thread was
    * one the bridge had created itself. An operator who names a root has
-   * declared that project in scope, and the id is still useless without being
-   * allowlisted for the calls that act.
+   * declared that project in scope, and under the default `owned` policy the
+   * id is still useless without being allowlisted for the calls that act.
    */
   filterThreads(threads) {
     return threads.filter((thread) => this.isCwdAuthorized(thread?.cwd));
@@ -142,6 +198,7 @@ export class BridgeSecurityPolicy {
     return {
       authorizedThreads: this.allowedThreadIds.size + this.ownedThreadIds.size,
       allowedRoots: this.allowedRoots,
+      threadPolicy: this.threadPolicy,
       approvalPolicy: this.approvalPolicy,
       sandbox: this.sandbox,
     };