@minhspark/codex-mcp-bridge 1.16.1 → 1.17.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.17.0] - 2026-09-21
+
+### Added
+
+- Bridge existing Claude Code and Codex conversations inside VS Code on Windows, with same-project session checks and delivery receipts.
+- Mirror published releases to GitHub Packages alongside npm.
+
+### Fixed
+
+- Keep discovering the Codex Desktop native tools pipe when it is absent during companion startup. Retry with capped backoff until Desktop is ready or the companion closes, without sending user messages or requiring another task to restart the relay.
+- Repair current bridge client configurations while refusing to overwrite changes from active client writers.
+- Distinguish unreadable process identity from a confirmed identity change during session validation.
+- Preserve hosted demo media and keep analytics Pages deployment working when analytics sources are incomplete.
+
+### Changed
+
+- Document release notification subscriptions and improve receipt test reliability under load.
+
 ## [1.16.1] - 2026-09-15
 
 ### Changed

package/README.md

@@ -6,7 +6,15 @@
 
 Send prompts and replies between **Claude and Codex**, keeping each conversation in its own app. Supports Windows, macOS, and Linux; native Desktop integration supports Windows and macOS.
 
-[![Claude and Codex exchanging messages](https://buidangminh23.github.io/codex-mcp-bridge/desktop-demo.gif)](https://buidangminh23.github.io/codex-mcp-bridge/desktop-demo.mp4)
+https://github.com/user-attachments/assets/98b23989-826f-4d7d-9dcb-ad7dd2739095
+
+## Release notifications
+
+To receive new release notifications, open [this repository](https://github.com/buidangminh23/codex-mcp-bridge), select **Watch → Custom → Releases**, then click **Apply**. Choose GitHub or email delivery in your [notification settings](https://github.com/settings/notifications).
+
+Starring the repository or downloading/installing a package does not subscribe you to release notifications. Notifications do not update your installed copy; follow the installation instructions to update.
+
+[View release notes](https://github.com/buidangminh23/codex-mcp-bridge/releases).
 
 ## Project statistics
 
@@ -18,6 +26,20 @@ Send prompts and replies between **Claude and Codex**, keeping each conversation
 
 ## Installation
 
+### GitHub Packages
+
+The repository-linked copy is [@buidangminh23/codex-mcp-bridge](https://github.com/buidangminh23/codex-mcp-bridge/packages)
+on npm.pkg.github.com. The npmjs.com package remains @minhspark/codex-mcp-bridge.
+GitHub's npm registry requires authentication with a classic token with read:packages,
+even for public packages. Authenticate locally and never commit a token:
+
+```bash
+npm login --scope=@buidangminh23 --registry=https://npm.pkg.github.com --auth-type=legacy
+npm install -g @buidangminh23/codex-mcp-bridge --registry=https://npm.pkg.github.com
+```
+
+Then follow the platform registration and verification instructions below.
+
 [Windows](#windows-powershell) · [macOS](#macos-terminal) · [Linux / WSL](#linux--wsl-bash) · [Claude Code registration](#register-claude-code) · [Verify](#verify-the-installation) · [Troubleshooting](#troubleshooting)
 
 Choose the mode for the conversations you want to connect:
@@ -286,7 +308,7 @@ For unresolved failures, [open an issue](https://github.com/buidangminh23/codex-
 
 ## Repository analytics
 
-The live dashboard polls the aggregate API every 30 seconds. Installation counts reflect reports received by the server; this is not a count of currently online processes. Public GitHub/npm sources are refreshed with a short cache, but their own statistics may be delayed. Private GitHub traffic is archived hourly when the owner's scheduled collector is available. The README image is a snapshot and may be cached by GitHub; open the live dashboard for automatic updates. Source timestamps show freshness; missing data is unavailable, not zero. Only aggregate figures are published. Installation IDs stay in the private database.
+The live dashboard polls the aggregate API every 30 seconds. Installation counts reflect reports received by the server; this is not a count of currently online processes. Public GitHub/npm sources are refreshed with a short cache, but their own statistics may be delayed. GitHub Actions refreshes and archives statistics hourly through the `Repository analytics` workflow, including private GitHub traffic; scheduled runs may be delayed by GitHub. That workflow needs the `ANALYTICS_TOKEN` repository secret set to a token with push access to this repository (fine-grained: Contents read/write plus Administration read); the default workflow token cannot read GitHub traffic, so without it the views/clones sources are retained from the last successful run and the run is reported as incomplete while the Pages deployment still succeeds. The README image is a snapshot and may be cached by GitHub; open the live dashboard for automatic updates. Source timestamps show freshness; missing data is unavailable, not zero. Only aggregate figures are published. Installation IDs stay in the private database.
 
 Repository owners can view [GitHub traffic](https://github.com/buidangminh23/codex-mcp-bridge/graphs/traffic) for recent views and clones. Downloads and clones include updates, reinstalls, and automation; they do not measure active users. GitHub traffic only covers the recent 14-day window, so collect it regularly to keep a longer history.
 
@@ -346,4 +368,4 @@ npm test
 
 On Windows, use `node --test --test-concurrency=2` (also avoids npm versions that reject forwarded flags). CI tests Node 22 and 24 on Linux, macOS, and Windows. Tests use isolated fixtures and do not spend model quota. For the optional telemetry endpoint, also run `deno test --allow-env supabase/functions/bridge-usage/contract-check.ts`.
 
-[Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [MIT license](LICENSE)
+[Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [MIT license](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.16.1",
+  "version": "1.17.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/scripts/collect-repo-analytics.mjs

@@ -45,6 +45,11 @@ function traffic(data, key) {
   return { count: count(data.count), uniques: count(data.uniques), [key]: data[key].map(row => ({ timestamp: `${day(row.timestamp)}T00:00:00Z`, count: count(row.count), uniques: count(row.uniques) })) };
 }
 
+export function httpStatus(error) {
+  const match = /\(HTTP (\d{3})\)/.exec(`${error?.stderr ?? ''}\n${error?.message ?? ''}`);
+  return match ? Number(match[1]) : undefined;
+}
+
 async function github(endpoint, paginate = false) {
   const args = ['api', '--hostname', 'github.com', '-H', 'Accept: application/vnd.github+json', '-H', 'X-GitHub-Api-Version: 2022-11-28', endpoint];
   if (paginate) args.push('--paginate', '--slurp');
@@ -79,7 +84,12 @@ export async function collectSources(options, { gh = github, fetcher = fetch, no
   };
   await Promise.all(Object.entries(jobs).map(async ([source, job]) => {
     try { snapshot[source] = await job(); }
-    catch { snapshot.errors.push({ source, message: source === 'npm' ? 'Request failed or response invalid. Check npm package, network, and npm API availability.' : 'Request failed or response invalid. Check gh authentication, repository permissions, network, and GitHub API limits.' }); }
+    catch (error) {
+      const entry = { source, message: source === 'npm' ? 'Request failed or response invalid. Check npm package, network, and npm API availability.' : 'Request failed or response invalid. Check gh authentication, repository permissions, network, and GitHub API limits.' };
+      const status = httpStatus(error);
+      if (status) entry.status = status;
+      snapshot.errors.push(entry);
+    }
   }));
   snapshot.errors.sort((a, b) => a.source.localeCompare(b.source));
   return snapshot;

package/scripts/install-native-relay.mjs

@@ -22,7 +22,7 @@ import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.16.1";
+const VERSION = "1.17.0";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/scripts/refresh-hosted-analytics.mjs

@@ -28,6 +28,10 @@ const directory = path.resolve('public-analytics');
 await mkdir(directory, { recursive: true });
 for (const [name, content] of Object.entries(publicFiles(history, usage))) await writeFile(path.join(directory, name), content);
 console.log(`Published aggregate analytics: ${sha}`);
-for (const error of snapshot.errors) console.error(`::warning::${error.source} was not refreshed; previous data retained.`);
+for (const error of snapshot.errors) {
+  const status = error.status ? ` (HTTP ${error.status})` : '';
+  const hint = error.status === 403 && ['views', 'clones'].includes(error.source) ? ' GitHub traffic requires the ANALYTICS_TOKEN secret to be a token with push access (fine-grained: Administration read); the default workflow token cannot read traffic.' : '';
+  console.error(`::warning::${error.source} was not refreshed${status}; previous data retained.${hint}`);
+}
 if (usageFailed) console.error('::warning::Usage was not refreshed; previous data retained.');
 if (snapshot.errors.length || usageFailed) process.exitCode = 1;

package/src/claude-bridge.mjs

@@ -25,7 +25,7 @@ import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.16.1";
+const VERSION = "1.17.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/codex-sender-context.mjs

@@ -29,7 +29,7 @@ function reviewFlag(metadata, field) {
   return "invalid";
 }
 
-function findRollout(sessions, threadId) {
+export function findRollout(sessions, threadId) {
   if (!fs.lstatSync(sessions).isDirectory()) throw new Error("The Codex sessions path is not a regular directory");
   const queue = [{ directory: sessions, depth: 0 }];
   const matches = [];
@@ -57,7 +57,7 @@ function findRollout(sessions, threadId) {
   return matches[0];
 }
 
-function readState(file, maxBytes) {
+export function readState(file, maxBytes) {
   const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
   try {
     const before = fs.fstatSync(descriptor);
@@ -120,7 +120,7 @@ function permissionClass(context, metadata) {
   throw new Error("The caller's effective approval policy is unsupported");
 }
 
-export function readCodexSenderContext(meta, { env = process.env, maxRolloutBytes = MAX_ROLLOUT_BYTES } = {}) {
+export function readCodexSenderContext(meta, { env = process.env, maxRolloutBytes = MAX_ROLLOUT_BYTES, originator = "Codex Desktop" } = {}) {
   const metadata = object(meta) ? meta[METADATA_KEY] : undefined;
   if (!object(metadata) || typeof metadata.thread_id !== "string" || typeof metadata.turn_id !== "string" || !UUID.test(metadata.thread_id) || !UUID.test(metadata.turn_id)) return unavailable("This MCP call has no valid host-supplied Codex task and turn identity");
   const identity = { threadId: metadata.thread_id, turnId: metadata.turn_id,
@@ -134,7 +134,8 @@ export function readCodexSenderContext(meta, { env = process.env, maxRolloutByte
     const file = findRollout(sessions, identity.threadId);
     const state = readState(file, Math.min(MAX_ROLLOUT_BYTES, maxRolloutBytes));
     const { session, context, lifecycle } = state;
-    if (session?.id !== identity.threadId || session.originator !== "Codex Desktop" || session.source !== "vscode") throw new Error("The caller rollout does not confirm a root Codex Desktop task");
+    if (!["Codex Desktop", "codex_vscode"].includes(originator)) throw new Error("Unsupported calling host");
+    if (session?.id !== identity.threadId || session.originator !== originator || session.source !== "vscode") throw new Error(`The caller rollout does not confirm a root ${originator} task`);
     if (context?.turn_id !== identity.turnId || lifecycle?.turn_id !== identity.turnId || !STARTED.has(lifecycle?.type)) throw new Error("The calling turn is no longer the latest active Codex turn");
     if (typeof context.cwd !== "string" || !path.isAbsolute(context.cwd) || typeof session.cwd !== "string" || !path.isAbsolute(session.cwd)) throw new Error("The caller's workspace is missing or invalid");
     const cwd = fs.realpathSync.native(context.cwd);

package/src/index.mjs

@@ -33,7 +33,7 @@ import { assertClaudeSenderContext, readClaudeSenderContext, requireClaudeSender
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.16.1";
+const VERSION = "1.17.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 

package/src/native-relay-companion.mjs

@@ -34,7 +34,7 @@ import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.16.1";
+const VERSION = "1.17.0";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {
@@ -635,11 +635,6 @@ export function startRelayWhenAvailable({ nativeTools, relay, log: logFn = () =>
     } catch (err) {
       if (stopped) return;
       if (!nativeConnected) nativeTools.close();
-      if (!nativeTools.socketPath && !nativeTools.hasDiscoveredSocket) {
-        logFn(`native relay unavailable (${err.message})`);
-        resolveReady(false);
-        return;
-      }
       logFn(`native relay unavailable (${err.message}); retrying in ${delayMs}ms`);
       timer = globalThis.setTimeout(() => {
         timer = null;

package/src/peer-protocol.mjs

@@ -104,7 +104,11 @@ function readPeerToken(socket) {
     const identity = readPeerProcessIdentity(key);
     const hasIdentity = Object.hasOwn(key, "procStart") || (IS_WINDOWS && Object.hasOwn(key, "procStartFt"));
     if (!identity && (hasIdentity || (IS_WINDOWS && hardenedBridgeEnabled()))) throw new Error("Peer process identity missing or invalid");
-    if (identity && identity !== readProcessStart(candidates[0].pid)) throw new Error("Peer process identity changed");
+    if (identity) {
+      const current = readProcessStart(candidates[0].pid);
+      if (current === null) throw new Error("The live peer process identity could not be read; message was not sent. That failure is not itself evidence the process changed.");
+      if (identity !== current) throw new Error("Peer process identity changed");
+    }
     return key.peerToken;
   } catch {
     if (IS_WINDOWS) throw new Error("The destination inbox authentication key is missing or invalid; message was not sent");
@@ -123,21 +127,31 @@ export function readPeerProcessIdentity(entry, platform = process.platform) {
   return values[0];
 }
 
+const PROCESS_START_TIMEOUT_MS = 30000;
+
 /**
  * MCP servers are spawned with an empty PATH, so `ps` must be addressed by its
  * absolute path - a bare lookup throws ENOENT and takes the whole server down
- * before it can answer the client's initialize call. The timestamp only guards
- * against pid reuse, so an empty value is an acceptable fallback.
+ * before it can answer the client's initialize call.
+ *
+ * A failed read is reported as null rather than as an empty string, because
+ * the callers compare this against a recorded identity and an empty string
+ * silently compares as "changed". A cold PowerShell on a contended Windows
+ * runner has been measured in this repo between 5s and 15s, so the previous
+ * 3s ceiling turned ordinary slowness into a report that the peer process had
+ * been swapped - the alarming reading of the two, and the one that fails a
+ * send. The budget now matches what the suites already give their own
+ * identity reads.
  */
 function readProcessStart(pid) {
   try {
     if (IS_WINDOWS) {
       const shell = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
-      return execFileSync(shell, ["-NoProfile", "-NonInteractive", "-Command", `[System.Diagnostics.Process]::GetProcessById(${Number(pid)}).StartTime.ToUniversalTime().ToFileTimeUtc().ToString()`], { timeout: 3000, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
+      return execFileSync(shell, ["-NoProfile", "-NonInteractive", "-Command", `[System.Diagnostics.Process]::GetProcessById(${Number(pid)}).StartTime.ToUniversalTime().ToFileTimeUtc().ToString()`], { timeout: PROCESS_START_TIMEOUT_MS, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
     }
-    return execFileSync(PS_BIN, ["-o", "lstart=", "-p", String(pid)], { env: { ...process.env, LC_ALL: "C", TZ: "UTC" }, timeout: 3000 }).toString().trim();
+    return execFileSync(PS_BIN, ["-o", "lstart=", "-p", String(pid)], { env: { ...process.env, LC_ALL: "C", TZ: "UTC" }, timeout: PROCESS_START_TIMEOUT_MS }).toString().trim();
   } catch {
-    return "";
+    return null;
   }
 }
 
@@ -251,10 +265,13 @@ export function assertClaudeSessionCwd(session, expectedCwd) {
 }
 
 export function assertClaudeSessionProcess(session) {
-  if (!session?.alive || typeof session.processStart !== "string" || !session.processStart ||
-      readProcessStart(session.pid) !== session.processStart) {
-    throw new Error("The live Claude process identity is missing or changed. No message was sent; reopen the existing Desktop task and inspect its session again.");
+  const changed = "The live Claude process identity is missing or changed. No message was sent; reopen the existing Desktop task and inspect its session again.";
+  if (!session?.alive || typeof session.processStart !== "string" || !session.processStart) throw new Error(changed);
+  const current = readProcessStart(session.pid);
+  if (current === null) {
+    throw new Error("The live Claude process identity could not be read, so this send was refused rather than sent unverified. That failure is not itself evidence the session changed; inspect the existing Desktop task before retrying.");
   }
+  if (current !== session.processStart) throw new Error(changed);
 }
 
 /**
@@ -462,7 +479,7 @@ export class PeerEndpoint {
 
   async #startOnce() {
     this.#sweepDeadBridges();
-    const procStart = readProcessStart(this.pid);
+    const procStart = readProcessStart(this.pid) ?? "";
     const peerToken = crypto.randomBytes(16).toString("hex");
     this.peerToken = peerToken;
     this.keyPath = peerKeyPath(this.pid, this.socketPath);

package/src/vscode-bridge.mjs

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { VSCodeIpc } from "./vscode-ipc.mjs";
+import { classifyClaudeDelivery, classifyCodexCompletion } from "./vscode-delivery.mjs";
+import { findRollout, readState, readCodexSenderContext } from "./codex-sender-context.mjs";
+import { readProcessAncestry } from "./claude-sender-context.mjs";
+import { listClaudeSessions, assertClaudeSessionCwd, assertClaudeSessionProcess, PeerEndpoint } from "./peer-protocol.mjs";
+import { readClaudeInboundPolicy } from "./claude-inbound-policy.mjs";
+
+const host = process.argv[2];
+if (!["claude", "codex"].includes(host)) throw new Error("Specify the calling extension: claude or codex");
+if (process.platform !== "win32") throw new Error("VS Code bridge preview currently supports Windows only");
+const roots = (process.env.VSCODE_BRIDGE_ALLOWED_ROOTS ?? "").split(path.delimiter).filter(Boolean).map((root) => fs.realpathSync.native(root));
+if (!roots.length || roots.some((root) => path.parse(root).root === root)) throw new Error("Configure explicit project roots in VSCODE_BRIDGE_ALLOWED_ROOTS");
+const sessions = path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "sessions");
+const peer = new PeerEndpoint({ name: "codex-vscode-bridge" });
+const unresolved = new Map();
+const deliveryOwners = new Map();
+const result = (value, isError = false) => ({ content: [{ type: "text", text: JSON.stringify(value) }], isError });
+const samePath = (left, right) => path.relative(fs.realpathSync.native(left), fs.realpathSync.native(right)) === "";
+
+function assertRoot(cwd) {
+  const resolved = fs.realpathSync.native(cwd);
+  if (!roots.some((root) => {
+    const relative = path.relative(root, resolved);
+    return !path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`);
+  })) throw new Error("The session is outside the configured project roots");
+  return resolved;
+}
+
+async function caller(meta) {
+  if (host === "codex") {
+    const sender = readCodexSenderContext(meta, { originator: "codex_vscode" });
+    if (sender.status !== "verified") throw new Error(sender.reason);
+    assertRoot(sender.cwd);
+    return sender;
+  }
+  const ancestry = await readProcessAncestry();
+  const matches = listClaudeSessions().filter((session) => session.entrypoint === "claude-vscode" && ancestry.some((row) => row.pid === session.pid && row.processStart === session.processStart));
+  if (matches.length !== 1) throw new Error("This MCP server must be launched by one live Claude Code VS Code session");
+  assertClaudeSessionProcess(matches[0]);
+  assertRoot(matches[0].cwd);
+  return matches[0];
+}
+
+function codexTask(threadId, cwd) {
+  if (!/^[0-9a-f-]{36}$/.test(threadId)) throw new Error("Invalid task ID");
+  const file = findRollout(sessions, threadId);
+  const state = readState(file, 64 * 1024 * 1024);
+  if (state.session?.id !== threadId || state.session.originator !== "codex_vscode" || state.session.source !== "vscode") throw new Error("The target is not a Codex VS Code task");
+  assertRoot(state.session.cwd);
+  if (!samePath(state.session.cwd, cwd) || !samePath(state.context.cwd, cwd)) throw new Error("Target and caller must use the same project directory");
+  return { ...state, file };
+}
+
+function taskCandidates(cwd) {
+  const queue = [{ directory: sessions, depth: 0 }];
+  const rows = [];
+  let count = 0;
+  while (queue.length) {
+    const { directory, depth } = queue.pop();
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (++count > 100000) throw new Error("Session scan limit exceeded");
+      if (entry.isSymbolicLink()) continue;
+      const file = path.join(directory, entry.name);
+      if (depth < 3 && entry.isDirectory() && /^\d{2,4}$/.test(entry.name)) queue.push({ directory: file, depth: depth + 1 });
+      if (depth !== 3 || !entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+      const fd = fs.openSync(file, "r");
+      let first;
+      try { const data = Buffer.alloc(65536); const size = fs.readSync(fd, data); first = JSON.parse(data.subarray(0, size).toString("utf8").split("\n")[0]); }
+      catch { continue; }
+      finally { fs.closeSync(fd); }
+      const session = first.payload;
+      if (first.type === "session_meta" && session?.originator === "codex_vscode" && session.source === "vscode" && samePath(session.cwd, cwd)) rows.push({ threadId: session.id, cwd: session.cwd });
+    }
+  }
+  return rows.slice(-50);
+}
+
+const server = new McpServer({ name: `vscode-${host}-bridge`, version: "0.1.0" });
+function tool(name, description, inputSchema, action) {
+  server.registerTool(name, { description, inputSchema }, async (args, extra) => {
+    try { return result(await action(args, await caller(extra?._meta), extra?._meta)); }
+    catch (error) { return result({ error: error.message, ...(error.msgId ? { msgId: error.msgId } : {}), ...(error.delivery ? { delivery: error.delivery } : {}) }, true); }
+  });
+}
+
+tool("vscode_bridge_status", "Verify this extension caller and list same-project counterparts in VS Code. Desktop sessions are excluded.", {}, async (_, sender) => {
+  if (host === "codex") return { host, cwd: sender.cwd, sessions: listClaudeSessions().filter((session) => session.entrypoint === "claude-vscode" && samePath(session.cwd, sender.cwd)).map(({ sessionId, cwd }) => ({ sessionId, cwd })) };
+  const ipc = await new VSCodeIpc().connect();
+  try {
+    const tasks = [];
+    for (const candidate of taskCandidates(sender.cwd)) {
+      try { await ipc.owner(candidate.threadId); tasks.push(candidate); } catch {}
+    }
+    return { host, cwd: sender.cwd, tasks };
+  } finally { ipc.close(); }
+});
+
+if (host === "claude") {
+  tool("send_to_codex_vscode", "Send to an existing Codex extension task in this project, preserving its selected permissions. Never retries or opens another app. Use read_codex_vscode_reply after submission.", { threadId: z.string(), message: z.string().min(1).max(50000) }, async ({ threadId, message }, sender, meta) => {
+    if (unresolved.has(threadId)) throw new Error("An earlier send is unresolved. Read its reply before sending again.");
+    const inspect = () => {
+      const state = codexTask(threadId, sender.cwd);
+      if (!["task_complete", "task_completed", "turn_complete", "turn_completed", "turn_aborted", "task_aborted"].includes(state.lifecycle?.type)) throw new Error("The target is busy or its lifecycle is unknown; wait for it to finish");
+    };
+    inspect();
+    const ipc = await new VSCodeIpc().connect();
+    try {
+      return await ipc.send(threadId, message, { beforeSend: async () => {
+        const current = await caller(meta);
+        if (current.sessionId !== sender.sessionId || current.processStart !== sender.processStart) throw new Error("Caller session changed");
+        inspect();
+        if (unresolved.has(threadId)) throw new Error("Another send is already pending for this task");
+        unresolved.set(threadId, "submission outcome unknown");
+      } }).then((receipt) => { unresolved.set(threadId, receipt.turnId); return receipt; });
+    } finally { ipc.close(); }
+  });
+  tool("read_codex_vscode_reply", "Read completion of the exact returned turn ID. A submission receipt alone does not prove completion.", { threadId: z.string(), turnId: z.string() }, async ({ threadId, turnId }, sender) => {
+    const state = codexTask(threadId, sender.cwd);
+    const completion = classifyCodexCompletion(state.lifecycle, turnId);
+    if (["completed", "failed", "interrupted"].includes(completion.status) && unresolved.get(threadId) === turnId) unresolved.delete(threadId);
+    return { threadId, ...completion };
+  });
+} else {
+  tool("send_to_claude_vscode", "Send to the exact Claude Code VS Code session in this project. Never changes recipient permissions. Do not ask the recipient to call back while this synchronous request waits.", { sessionId: z.string(), message: z.string().min(1).max(50000), waitSec: z.number().int().min(0).max(45).default(30) }, async ({ sessionId, message, waitSec }, sender, meta) => {
+    const inspect = () => {
+      const matches = listClaudeSessions().filter((session) => session.entrypoint === "claude-vscode" && session.sessionId === sessionId);
+      if (matches.length !== 1) throw new Error("No unique live Claude Code VS Code session matches");
+      const session = matches[0];
+      assertClaudeSessionCwd(session, sender.cwd);
+      assertClaudeSessionProcess(session);
+      const policy = readClaudeInboundPolicy(session.cwd);
+      if (["hold", "refuse"].includes(policy.value)) throw new Error(`Recipient crossSessionInbound is ${policy.value}; no message sent`);
+      return session;
+    };
+    const recipient = inspect();
+    await peer.start();
+    const receipt = await peer.sendAndWait(recipient.socket, message, { timeoutMs: waitSec * 1000, permissionMode: sender.mode, transcriptSession: { sessionId, cwd: recipient.cwd }, beforeSend: async () => {
+      const current = await caller(meta);
+      if (current.turnId !== sender.turnId || current.mode !== sender.mode) throw new Error("Caller turn or permissions changed");
+      const target = inspect();
+      if (target.pid !== recipient.pid || target.socket !== recipient.socket || target.processStart !== recipient.processStart) throw new Error("Recipient session changed");
+    } }).catch((error) => {
+      if (error.msgId) deliveryOwners.set(error.msgId, sender.threadId);
+      throw error;
+    });
+    deliveryOwners.set(receipt.msgId, sender.threadId);
+    return classifyClaudeDelivery(receipt, sender.mode);
+  });
+  tool("read_claude_vscode_delivery", "Inspect an earlier send without resending it.", { msgId: z.string() }, async ({ msgId }, sender) => {
+    if (deliveryOwners.get(msgId) !== sender.threadId) throw new Error("This receipt does not belong to the calling task");
+    return peer.readDelivery(msgId) ?? { status: "unknown" };
+  });
+}
+
+process.on("exit", () => peer.stop());
+await server.connect(new StdioServerTransport());

package/src/vscode-delivery.mjs

@@ -0,0 +1,19 @@
+const BLOCKED = new Set(["held", "refused", "denied", "expired", "dropped"]);
+
+export function classifyClaudeDelivery(receipt, senderMode) {
+  if (receipt.reply) return { ...receipt, status: "reply_received" };
+  const status = receipt.delivery?.status ?? "sent_unconfirmed";
+  if (BLOCKED.has(status)) {
+    throw Object.assign(new Error(`Claude returned ${status}: ${receipt.delivery.reason ?? "the message was not delivered to the conversation"}. Sender permission class: ${senderMode}. This does not prove an approval control exists in the VS Code extension. Report the receipt to the user; do not resend, change permissions, or claim that the user can click an unverified approval button.`), { msgId: receipt.msgId, delivery: receipt.delivery });
+  }
+  return { ...receipt, status };
+}
+
+export function classifyCodexCompletion(lifecycle, turnId) {
+  if (lifecycle?.turn_id !== turnId) return { status: "pending_or_unavailable", turnId };
+  if (["turn_aborted", "task_aborted"].includes(lifecycle.type)) return { status: "interrupted", turnId };
+  if (!["task_complete", "task_completed", "turn_complete", "turn_completed"].includes(lifecycle.type)) return { status: "pending_or_unavailable", turnId };
+  if (lifecycle.error) return { status: "failed", turnId, error: lifecycle.error };
+  if (typeof lifecycle.last_agent_message !== "string") return { status: "response_unavailable", turnId };
+  return { status: "completed", turnId, text: lifecycle.last_agent_message };
+}

package/src/vscode-ipc.mjs

@@ -0,0 +1,80 @@
+import net from "node:net";
+import { randomUUID } from "node:crypto";
+
+export class VSCodeIpc {
+  constructor({ socketPath = "\\\\.\\pipe\\codex-ipc", timeoutMs = 10000 } = {}) {
+    this.socketPath = socketPath;
+    this.timeoutMs = timeoutMs;
+    this.pending = new Map();
+    this.buffer = Buffer.alloc(0);
+  }
+
+  async connect() {
+    this.socket = net.createConnection(this.socketPath);
+    this.socket.on("data", (data) => {
+      try {
+        this.buffer = Buffer.concat([this.buffer, data]);
+        while (this.buffer.length >= 4) {
+          const length = this.buffer.readUInt32LE(0);
+          if (!length || length > 16 * 1024 * 1024) throw new Error("Invalid IPC frame length");
+          if (this.buffer.length < length + 4) break;
+          const frame = JSON.parse(this.buffer.subarray(4, length + 4).toString("utf8"));
+          this.buffer = this.buffer.subarray(length + 4);
+          if (frame.type !== "response") continue;
+          const pending = this.pending.get(frame.requestId);
+          if (!pending) continue;
+          this.pending.delete(frame.requestId);
+          clearTimeout(pending.timer);
+          if (frame.resultType !== "success") pending.reject(new Error(`IPC ${pending.method}: ${frame.error ?? "request failed"}`));
+          else if (pending.target && frame.handledByClientId !== pending.target) pending.reject(new Error("IPC owner changed"));
+          else pending.resolve(frame);
+        }
+      } catch (error) { this.close(error); }
+    });
+    this.socket.on("error", (error) => this.close(error));
+    this.socket.on("close", () => this.close(new Error("IPC connection closed")));
+    const response = await this.request("initialize", { clientType: "codex-mcp-bridge" }, 0);
+    if (typeof response.result?.clientId !== "string") throw new Error("IPC initialization omitted client identity");
+    this.clientId = response.result.clientId;
+    return this;
+  }
+
+  request(method, params, version = 1, target) {
+    return new Promise((resolve, reject) => {
+      const requestId = randomUUID();
+      const timer = setTimeout(() => {
+        this.pending.delete(requestId);
+        reject(new Error(`IPC ${method} timed out; inspect the original task before retrying a send`));
+      }, this.timeoutMs);
+      this.pending.set(requestId, { resolve, reject, timer, method, target });
+      const body = Buffer.from(JSON.stringify({ type: "request", requestId, sourceClientId: this.clientId ?? "initializing-client", version, method, params, ...(target ? { targetClientId: target } : {}) }));
+      const header = Buffer.alloc(4);
+      header.writeUInt32LE(body.length);
+      this.socket.write(Buffer.concat([header, body]));
+    });
+  }
+
+  async owner(threadId) {
+    const response = await this.request("thread-owner-discovery", { hostId: "local", conversationId: threadId });
+    if (!response.handledByClientId) throw new Error("No live owner for this task");
+    return response.handledByClientId;
+  }
+
+  async send(threadId, message, { beforeSend } = {}) {
+    const owner = await this.owner(threadId);
+    await beforeSend?.();
+    const response = await this.request("thread-follower-start-turn", {
+      conversationId: threadId,
+      turnStart: { request: { threadId, input: [{ type: "text", text: message, text_elements: [] }] }, context: { inheritThreadSettings: true } },
+    }, 2, owner);
+    const turnId = response.result?.result?.turn?.id;
+    if (typeof turnId !== "string") throw new Error("Submission was acknowledged without a turn ID; inspect the original task before retrying");
+    return { threadId, turnId, owner, status: "submitted" };
+  }
+
+  close(error = new Error("IPC client closed")) {
+    this.socket?.destroy();
+    for (const entry of this.pending.values()) { clearTimeout(entry.timer); entry.reject(error); }
+    this.pending.clear();
+  }
+}