@minhspark/codex-mcp-bridge 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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

package/README.md

@@ -231,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.17.0",
+  "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/install-native-relay.mjs

@@ -22,7 +22,7 @@ import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.17.0";
+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/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.17.0";
+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/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.17.0";
+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.17.0";
+const VERSION = "1.18.0";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {

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

@@ -10,6 +10,7 @@ import { findRollout, readState, readCodexSenderContext } from "./codex-sender-c
 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");
@@ -102,7 +103,7 @@ tool("vscode_bridge_status", "Verify this extension caller and list same-project
 });
 
 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) => {
+  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);
@@ -127,7 +128,7 @@ if (host === "claude") {
     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) => {
+  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");