@minhspark/codex-mcp-bridge 1.17.0 → 1.18.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.18.1] - 2026-09-25
+
+### Fixed
+
+- Report npm installation completion with an unchanged version instead of claiming the package is already up to date after a same-version reinstall.
+- Discover Claude Desktop sessions when accumulated task configuration exceeds 32 MiB. Retain only bounded identity fields and SHA-256 fingerprints while preserving account isolation, duplicate detection, and concurrent-change checks.
+- Report Desktop task verification failures separately from missing peer endpoints in session discovery and bridge status.
+
+## [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.1",
   "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.1";
 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/npm-footer.ps1

@@ -130,7 +130,7 @@ try {
     } elseif ($before.Status -eq 'missing') {
         Write-Host "Successfully installed: @minhspark/codex-mcp-bridge v$($after.Version)"
     } elseif ($before.Version -ceq $after.Version) {
-        Write-Host "Already up to date: @minhspark/codex-mcp-bridge v$($after.Version)"
+        Write-Host "Installation completed: @minhspark/codex-mcp-bridge v$($after.Version) (version unchanged)"
     } else {
         Write-Host "Successfully updated: @minhspark/codex-mcp-bridge v$($before.Version) -> v$($after.Version)"
     }

package/scripts/npm-footer.sh

@@ -70,7 +70,7 @@ npm() {
     if [ -z "$bridge_after" ] || [ "$bridge_before_verified" -ne 1 ] || [ "$bridge_after_root" != "$bridge_root" ]; then
       printf 'Warning: npm completed, but the installed @minhspark/codex-mcp-bridge version could not be verified.\n' >&2
     elif [ "$bridge_after_root" = "$bridge_root" ] && [ "$bridge_after" = "$bridge_before" ]; then
-      printf 'Already up to date: @minhspark/codex-mcp-bridge v%s\n' "$bridge_after"
+      printf 'Installation completed: @minhspark/codex-mcp-bridge v%s (version unchanged)\n' "$bridge_after"
     elif [ "$bridge_after_root" = "$bridge_root" ] && [ -n "$bridge_before" ]; then
       printf 'Successfully updated: @minhspark/codex-mcp-bridge v%s -> v%s\n' "$bridge_before" "$bridge_after"
     else

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.1";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
@@ -163,6 +164,40 @@ function withDesktopContext(session, account = readClaudeAccountContext()) {
     ? { ...session, desktop: readClaudeDesktopContext(session, { account }), inbound: readClaudeInboundPolicy(session.cwd) } : session;
 }
 
+function inspectDiscovery(sessions, account, expectedCwd) {
+  const eligible = [];
+  const excluded = [];
+  let nonDesktopCount = 0;
+  let candidateCount = 0;
+  for (const session of sessions) {
+    if (rootPolicy.enabled && !rootPolicy.allows(session.cwd)) continue;
+    if (expectedCwd !== undefined) {
+      try { assertClaudeSessionCwd(session, expectedCwd); }
+      catch { continue; }
+    }
+    if (desktopOnly && session.entrypoint !== "claude-desktop") {
+      nonDesktopCount += 1;
+      continue;
+    }
+    candidateCount += 1;
+    const inspected = withDesktopContext(session, account);
+    if (!desktopOnly || inspected.desktop?.status === "matched") {
+      eligible.push(inspected);
+      continue;
+    }
+    const status = inspected.desktop?.status ?? "missing";
+    const reason = inspected.desktop?.reason ?? "The Desktop task identity could not be verified.";
+    const previous = excluded.find((entry) => entry.status === status && entry.reason === reason);
+    if (previous) previous.count += 1;
+    else excluded.push({ status, reason, count: 1 });
+  }
+  return { sessions: eligible, discovery: { candidateCount, matchedCount: eligible.length, nonDesktopCount, excluded } };
+}
+
+function discoveryDetails(discovery) {
+  return discovery.excluded.map((entry) => `Desktop task verification: ${entry.count} candidate(s) ${entry.status} - ${entry.reason}`);
+}
+
 function assertSessionRoot(session, label = "Claude session") {
   return rootPolicy.assert(session?.cwd, `${label} working directory`);
 }
@@ -261,7 +296,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 +316,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 },
   },
@@ -338,17 +374,14 @@ registerTool(
       if (expectedCwd !== undefined) assertClaudeSessionCwd({ cwd: expectedCwd }, expectedCwd);
       const account = readClaudeAccountContext();
       if (desktopOnly && account.status !== "verified") return { ...textResult(`Claude account ${account.status}: ${account.reason} Sign in and retry discovery.`, true), structuredContent: { account: publicAccountState(account), sessions: [] } };
-      const sessions = listClaudeSessions({ includeDead: includeDead ?? false }).filter(
-        (s) => s.pid !== process.pid && (!desktopOnly || s.entrypoint === "claude-desktop"),
-      ).filter((session) => !rootPolicy.enabled || rootPolicy.allows(session.cwd)
-      ).filter((session) => {
-        if (expectedCwd === undefined) return true;
-        try { assertClaudeSessionCwd(session, expectedCwd); return true; }
-        catch { return false; }
-      }).map((session) => withDesktopContext(session, account)).filter((session) => !desktopOnly || session.desktop?.status === "matched");
-      if (!sessions.length) return textResult(desktopOnly ? missingDesktopSession : "No live Claude Code session found.");
-      return { ...textResult(`${sessions.length} Claude${desktopOnly ? " Desktop" : ""} session(s):\n\n${sessions.map(formatSessionRow).join("\n")}`),
-        structuredContent: { account: publicAccountState(account), sessions: sessions.map(({ socket, bridgeSessionId, ...session }) => session) } };
+      const { sessions, discovery } = inspectDiscovery(listClaudeSessions({ includeDead: includeDead ?? false }).filter((s) => s.pid !== process.pid), account, expectedCwd);
+      const summary = sessions.length
+        ? `${sessions.length} Claude${desktopOnly ? " Desktop" : ""} session(s):\n\n${sessions.map(formatSessionRow).join("\n")}`
+        : discovery.excluded.length
+          ? `Found ${discovery.candidateCount} registered Claude Desktop candidate(s) with messaging endpoints, but their Desktop task identities could not be verified. Delivery remains blocked.`
+          : desktopOnly ? missingDesktopSession : "No live Claude Code session found.";
+      return { ...textResult([summary, ...discoveryDetails(discovery)].join("\n")),
+        structuredContent: { account: publicAccountState(account), sessions: sessions.map(({ socket, bridgeSessionId, ...session }) => session), discovery } };
     } catch (err) {
       return failure(err);
     }
@@ -369,7 +402,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
@@ -644,9 +677,7 @@ registerTool(
       await peer.start();
       const sessions = listClaudeSessions().filter((s) => s.pid !== process.pid);
       const accounts = readBridgeAccounts();
-      const eligible = sessions.filter((session) => !desktopOnly || session.entrypoint === "claude-desktop")
-        .filter((session) => !rootPolicy.enabled || rootPolicy.allows(session.cwd))
-        .filter((session) => !desktopOnly || withDesktopContext(session, accounts.claude).desktop?.status === "matched");
+      const { sessions: eligible, discovery } = inspectDiscovery(sessions, accounts.claude);
       const visibleInbox = peer.inbox.filter((record) => recordVisible(record, accounts));
       const visiblePending = [...peer.pendingMessages.keys()].filter((id) => readReceipt(id));
       const visibleForwarding = replyForwarder.status((record) => recordVisible(record, accounts));
@@ -664,7 +695,8 @@ registerTool(
         `Claude account: ${accounts.claude.status}${accounts.claude.fingerprint ? ` (${accounts.claude.fingerprint.slice(0, 12)})` : ` - ${accounts.claude.reason}`}`,
         `Codex account: ${accounts.codex.status}${accounts.codex.fingerprint ? ` (${accounts.codex.fingerprint.slice(0, 12)})` : ` - ${accounts.codex.reason}`}`,
         `live sessions: ${eligible.length}`,
-        ...(rootPolicy.enabled ? [] : [`excluded:      ${sessions.length - eligible.length} non-Desktop or inactive-account session(s)`]),
+        `excluded:      ${discovery.nonDesktopCount} non-Desktop session(s); ${discovery.candidateCount - eligible.length} Desktop candidate(s) failed task verification`,
+        ...discoveryDetails(discovery),
         `relay thread:  ${forwarding.threadId ?? "(none - use bind_codex_thread)"}`,
         `delivery:      ${delivery.describe()}`,
         `inbox:         ${visibleInbox.length} pending message(s)`,
@@ -674,7 +706,7 @@ registerTool(
       ];
       const state = runtime.status();
       lines.push(`runtime pid:   ${state.pid}`, `loaded source: ${state.revision}`, `disk source:   ${state.diskRevision ?? "unreadable"}`, `runtime state: ${state.current ? "current" : `STALE - ${state.reason}; reconnect this MCP server in the existing task`}`);
-      return { ...textResult(lines.join("\n"), !state.current), structuredContent: { runtime: state, accounts: { claude: publicAccountState(accounts.claude), codex: publicAccountState(accounts.codex) }, replyForwarding: visibleForwarding, ...(sender ? { sender } : {}) } };
+      return { ...textResult(lines.join("\n"), !state.current), structuredContent: { runtime: state, accounts: { claude: publicAccountState(accounts.claude), codex: publicAccountState(accounts.codex) }, discovery, replyForwarding: visibleForwarding, ...(sender ? { sender } : {}) } };
     } catch (err) {
       return failure(err);
     }

package/src/claude-desktop-context.mjs

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -7,7 +8,7 @@ const ACCOUNT_ID = new RegExp(`^${UUID}$`, "i");
 const TASK_FILE = new RegExp(`^(local_${UUID})\\.json$`, "i");
 const MAX_ENTRIES = 8192;
 const MAX_FILE_BYTES = 4 * 1024 * 1024;
-const MAX_TOTAL_BYTES = 32 * 1024 * 1024;
+const MAX_IDENTITY_BYTES = 32 * 1024 * 1024;
 const VERSION_FIELDS = ["size", "mtimeMs", "ctimeMs", "ino", "dev"];
 
 const sameVersion = (left, right) => VERSION_FIELDS.every((field) => left[field] === right[field]);
@@ -69,18 +70,16 @@ function readMetadata(file, budget) {
   try {
     const before = fs.fstatSync(descriptor);
     if (!before.isFile() || before.size > MAX_FILE_BYTES) throw new Error("file limit");
-    budget.bytes += before.size;
-    if (budget.bytes > MAX_TOTAL_BYTES) throw new Error("total limit");
     const bytes = Buffer.alloc(before.size);
     if (fs.readSync(descriptor, bytes, 0, bytes.length, 0) !== bytes.length) throw new Error("short read");
     const after = fs.fstatSync(descriptor);
     const current = fs.lstatSync(file);
     if (!sameVersion(before, after) || current.isSymbolicLink() || !sameVersion(current, after)) throw new Error("metadata changed");
     budget.versions.set(file, current);
-    budget.contents.set(file, bytes);
+    budget.digests.set(file, createHash("sha256").update(bytes).digest("hex"));
     const data = JSON.parse(bytes.toString("utf8"));
     if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error("invalid metadata");
-    return {
+    const record = {
       taskId: data.sessionId,
       fileTaskId: TASK_FILE.exec(path.basename(file))[1],
       cliSessionId: data.cliSessionId,
@@ -90,18 +89,14 @@ function readMetadata(file, budget) {
       isArchived: data.isArchived,
       permissionMode: data.permissionMode,
     };
+    budget.bytes += Buffer.byteLength(JSON.stringify(record));
+    if (budget.bytes > MAX_IDENTITY_BYTES) throw new Error("identity limit");
+    return record;
   } finally {
     fs.closeSync(descriptor);
   }
 }
 
-/**
- * Stat fields cannot prove a record is unchanged: a same-size rewrite inside
- * one filesystem timestamp tick (about 16 ms on Windows) keeps size, times
- * and inode identical. The final consistency pass therefore compares the
- * bytes themselves; the records are small JSON files, so the extra read is
- * cheap and the check is deterministic on every platform.
- */
 function rereadMetadata(file) {
   const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
   try {
@@ -109,7 +104,7 @@ function rereadMetadata(file) {
     if (!stat.isFile() || stat.size > MAX_FILE_BYTES) throw new Error("file limit");
     const bytes = Buffer.alloc(stat.size);
     if (fs.readSync(descriptor, bytes, 0, bytes.length, 0) !== bytes.length) throw new Error("short read");
-    return bytes;
+    return createHash("sha256").update(bytes).digest("hex");
   } finally {
     fs.closeSync(descriptor);
   }
@@ -138,8 +133,14 @@ export function readClaudeDesktopContext(session, { platform = process.platform,
     const directory = root ?? (account ? path.join(account.root, "claude-code-sessions") : sessionsRoot(platform, env));
     if (!fs.existsSync(directory)) return result("missing", "Claude Desktop task metadata is not available on this host.");
     records = readClaudeDesktopTasks({ platform, env, root, account });
-  } catch {
-    return result("mismatch", "Claude Desktop task metadata could not be read completely and consistently; no task identity is confirmed.");
+  } catch (error) {
+    const detail = {
+      "file limit": " A task metadata file exceeds the 4 MiB per-file limit.",
+      "identity limit": " Task identity fields exceed the 32 MiB retained-data limit.",
+      "scan limit": " The task directory exceeds the 8192-entry scan limit.",
+      "metadata changed": " Task metadata changed during inspection; retry discovery.",
+    }[error.message] ?? "";
+    return result("mismatch", `Claude Desktop task metadata could not be read completely and consistently; no task identity is confirmed.${detail}`);
   }
 
   const primary = records.filter((record) => record.cliSessionId === session.sessionId);
@@ -198,13 +199,13 @@ export function readClaudeDesktopTasks({ platform = process.platform, env = proc
   }
   const directory = root ?? (account ? path.join(account.root, "claude-code-sessions") : sessionsRoot(platform, env));
   const files = metadataFiles(directory, account?.accountId);
-  const budget = { bytes: 0, versions: new Map(), contents: new Map() };
+  const budget = { bytes: 0, versions: new Map(), digests: new Map() };
   const records = files.map((file) => readMetadata(file, budget));
   const currentFiles = metadataFiles(directory, account?.accountId);
   if (files.length !== currentFiles.length || files.some((file, index) => file !== currentFiles[index])) throw new Error("metadata changed");
   for (const file of files) {
     const current = fs.lstatSync(file);
-    if (!current.isFile() || !sameVersion(current, budget.versions.get(file)) || !rereadMetadata(file).equals(budget.contents.get(file))) throw new Error("metadata changed");
+    if (!current.isFile() || !sameVersion(current, budget.versions.get(file)) || rereadMetadata(file) !== budget.digests.get(file)) throw new Error("metadata changed");
   }
   return records;
 }

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.1";
 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.1";
 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");