@minhspark/codex-mcp-bridge 1.16.1 → 1.18.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.18.0] - 2026-09-23
+
+### Changed
+
+- Guide agents to write every cross-agent prompt in English with a fixed section order: Goal, Context, Task, Scope, Constraints, Done when, Reply format. The Codex, Claude and VS Code bridges share one definition in their server instructions, sending-tool descriptions and prompt fields, and text supplied by the user is still sent unchanged.
+
+## [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:
@@ -209,6 +231,22 @@ Example requests:
 
 Use the exact project directory and destination task. If several Claude sessions match, specify the task ID. A `reply_received` receipt confirms a reply; a timeout does not mean the task stopped, so inspect it before retrying.
 
+The sending tools ask agents to write each prompt in English with these sections, dropping any that do not apply: `Goal`, `Context`, `Task`, `Scope`, `Constraints`, `Done when`, `Reply format`. The first line names the sender, the project and the purpose. Text the user supplied is sent unchanged.
+
+```text
+[From Claude Code · my-app · edit coordination]
+
+## Goal
+Avoid conflicting edits while Claude Code patches `src/export.ps1`.
+
+## Task
+1. Do not modify `src/export.ps1` or `README.txt` until told otherwise.
+2. Write any unsaved edits to those files to disk now.
+
+## Reply format
+Exactly one line: `DONE — changed: <files>` or `DONE — no changes`.
+```
+
 ## Important behavior
 
 - Desktop mode uses the native relay and the apps' permissions; it does not fall back to an external app-server.
@@ -286,7 +324,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 +384,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.18.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.18.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

@@ -22,10 +22,11 @@ import { readClaudeAccountContext } from "./desktop-account-context.mjs";
 import { assertAccountIdentity, bindUnsolicitedClaudeMessageAccount, publicAccountState, readBridgeAccounts, requireBridgeAccounts, sameAccountIdentity } from "./bridge-account-context.mjs";
 import { resolveClaudeDesktopSession, sameClaudeDesktopRecipient } from "./claude-session-router.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
+import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.16.1";
+const VERSION = "1.18.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
@@ -261,7 +262,8 @@ const server = new McpServer(
       "The sender class follows the verified approval policy; automated review flags are reported but never change it. " +
       "A Desktop recipient whose settings refuse or hold inbound messages, or whose task metadata shows a different permission class without an explicit accept, is refused before sending, because Claude Desktop cannot show the approval dialog. " +
       "Never launch a CLI session or an external app-server as a substitute. A receipt confirms a reply, not visual verification in the app. " +
-      "A held receipt does not prove that Desktop exposes an approval button; verify the UI before asking the user to approve.",
+      "A held receipt does not prove that Desktop exposes an approval button; verify the UI before asking the user to approve. " +
+      AGENT_PROMPT_GUIDANCE,
   },
 );
 
@@ -280,7 +282,7 @@ registerTool(
     inputSchema: {
       requestId: z.string().describe("Stable UUID for this creation; reuse exactly when inspecting or retrying"),
       cwd: z.string().describe("Exact absolute directory of the existing Claude Desktop project"),
-      prompt: z.string().describe("Initial prompt for the NEW conversation; shown for user confirmation"),
+      prompt: z.string().describe(`Initial prompt for the NEW conversation; shown for user confirmation. ${PROMPT_FIELD_HINT}`),
     },
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
   },
@@ -369,7 +371,7 @@ registerTool(
       "The sender's current permissions are verified per call; environment overrides and manual binding cannot bypass an unknown sender. It never creates a replacement session.",
     inputSchema: {
       target: z.string().describe("Use auto for current-account discovery in expectedCwd, an exact session identity, or new to prepare a separate Desktop conversation requiring user confirmation"),
-      message: z.string().describe("The message text to deliver"),
+      message: z.string().describe(`The message text to deliver. ${PROMPT_FIELD_HINT}`),
       expectedCwd: z.string().optional().describe("Exact absolute project directory independently verified by the caller; required in Desktop-only mode"),
       expectedTaskId: z.string().optional().describe("Exact native Claude Desktop task ID from list_claude_sessions; verify its title in the app before sending"),
       waitSec: z

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

@@ -30,10 +30,11 @@ import { createRuntimeState } from "./runtime-state.mjs";
 import { assertRoutingReload, clientReloadReason, createReloadControl } from "./reload-control.mjs";
 import { accountIdentity, assertAccountIdentity, publicAccountState, readBridgeAccounts, requireBridgeAccounts } from "./bridge-account-context.mjs";
 import { assertClaudeSenderContext, readClaudeSenderContext, requireClaudeSenderContext } from "./claude-sender-context.mjs";
+import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.16.1";
+const VERSION = "1.18.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -345,7 +346,8 @@ const server = new McpServer(
       "requested cwd. With Desktop tasks enabled it assigns the exact saved project and starts visibly in " +
       "Codex Desktop using Desktop permissions. Otherwise it releases the bridge writer lock and opens the exact thread in " +
       "Codex Desktop. Use send_to_codex_thread only when an existing threadId is intentional; use " +
-      "list_codex_threads or read_codex_thread to inspect sessions and codex_bridge_status to inspect wiring.",
+      "list_codex_threads or read_codex_thread to inspect sessions and codex_bridge_status to inspect wiring. " +
+      AGENT_PROMPT_GUIDANCE,
   },
 );
 
@@ -400,7 +402,7 @@ registerTool(
       "return Codex's reply, and hand the session to Codex Desktop without leaving the bridge writer lock behind.",
     inputSchema: {
       cwd: z.string().describe("Absolute project directory where Codex must work"),
-      prompt: z.string().describe("The complete task Claude is delegating to Codex"),
+      prompt: z.string().describe(`The complete task Claude is delegating to Codex. ${PROMPT_FIELD_HINT}`),
       name: z.string().min(1).max(200).optional().describe("Optional Codex session title; otherwise one is derived from the prompt"),
       timeoutSec: z
         .number()
@@ -494,7 +496,7 @@ registerTool(
       "Do not close the task, create a replacement, or ask the user to copy the message manually.",
     inputSchema: {
       threadId: z.string().describe("Codex thread id (UUID) - get it from list_codex_threads"),
-      prompt: z.string().describe("The message to send to Codex, exactly as a user would type it"),
+      prompt: z.string().describe(`The message to send to Codex as a new user turn. ${PROMPT_FIELD_HINT}`),
       timeoutSec: z
         .number()
         .int()
@@ -703,7 +705,7 @@ registerTool(
     description: "Start a Codex task. In Desktop mode include the initial prompt to create and assign a visible task atomically; use delegate_to_codex to also wait for its reply.",
     inputSchema: {
       cwd: z.string().describe("Absolute working directory for the new Codex session"),
-      prompt: z.string().min(1).optional().describe("Initial task; required with CODEX_BRIDGE_DESKTOP_TASKS=1, starts immediately"),
+      prompt: z.string().min(1).optional().describe(`Initial task; required with CODEX_BRIDGE_DESKTOP_TASKS=1, starts immediately. ${PROMPT_FIELD_HINT}`),
       model: z.string().optional().describe("Model override, e.g. gpt-5.6-luna"),
       name: z.string().min(1).max(200).optional().describe("Optional title to show for the new Codex session"),
     },

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.18.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/prompt-guidance.mjs

@@ -0,0 +1,30 @@
+/**
+ * Every message this bridge carries is a prompt one agent wrote for another.
+ * A single paragraph that runs the request into the reply format leaves the
+ * recipient guessing where the task ends, so the sending tools all describe
+ * one shape. It lives here so the Codex, Claude and VS Code bridges cannot
+ * drift apart.
+ */
+export const PROMPT_SECTIONS = Object.freeze([
+  "Goal",
+  "Context",
+  "Task",
+  "Scope",
+  "Constraints",
+  "Done when",
+  "Reply format",
+]);
+
+export const AGENT_PROMPT_GUIDANCE =
+  "Write every prompt you compose for another agent in English, in this order, omitting sections that do not apply: " +
+  "a first line naming the sender, project and purpose, e.g. [From Claude Code · <project> · <purpose>]; " +
+  "## Goal, the outcome in one sentence; ## Context, measured facts, paths with line numbers and existing code to reuse; " +
+  "## Task, numbered imperative steps; ## Scope, the files that may and must not change; " +
+  "## Constraints, conventions and tests, plus: if the current state differs from this description, stop and report instead of reconciling it; " +
+  "## Done when, checkable criteria; ## Reply format, the exact shape of the reply. " +
+  "A short coordination message needs only Goal, Context, Task and Reply format. " +
+  "Send text the user supplied verbatim, and keep file names, identifiers and user-facing strings in their original language.";
+
+export const PROMPT_FIELD_HINT =
+  `The prompt for the recipient agent, in English with the sections ${PROMPT_SECTIONS.join(", ")} ` +
+  "(omit any that do not apply); text the user supplied is sent verbatim";

package/src/vscode-bridge.mjs

@@ -0,0 +1,163 @@
+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";
+import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.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. ${AGENT_PROMPT_GUIDANCE}`, { threadId: z.string(), message: z.string().min(1).max(50000).describe(PROMPT_FIELD_HINT) }, 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. ${AGENT_PROMPT_GUIDANCE}`, { sessionId: z.string(), message: z.string().min(1).max(50000).describe(PROMPT_FIELD_HINT), 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();
+  }
+}