@minhspark/codex-mcp-bridge 1.12.4 → 1.13.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [1.13.0] - 2026-09-05
+
+### Added
+
+- Opt-in Desktop task delivery: `delegate_to_codex` creates a task in the exact saved local project and opens it while running. `send_to_codex_thread` continues through Desktop without a second writer. `start_codex_thread` accepts an initial prompt and requires it in Desktop mode.
+- Enable with `codex-native-relay-install --desktop-tasks` or `CODEX_BRIDGE_DESKTOP_TASKS=1`. Desktop mode uses Desktop permissions and preserves bridge workspace/thread authorization. Missing, ambiguous, remote, or parent-only project matches fail before creation; the requested checkout is preserved.
+- Strictly allowlisted native operations and a separate Desktop task socket allow upgrades alongside an older legacy relay owner. Read/open operations use Desktop too; timed-out native tasks point to Desktop's Stop control.
+
+### Fixed
+
+- Distinguish task acceptance, model failure, attention requests, and observation timeout. Follow-up polling ignores the previous completed turn; unconfirmed creation or sending is never automatically retried through another backend.
+- Mark prompt-bearing task creation as potentially destructive in MCP annotations, and preserve the shared Desktop opt-in when bootstrapping a relay executor.
+
+### Verification
+
+- Added project matching, authorization, protocol validation, socket transport, uncertain acknowledgement, attention, timeout, and full MCP creation/opening tests.
+- A real Windows Desktop task appeared under PCC4SH and completed with `cwd=C:\PCC4SH`, `HEAD=74ed553`. A subsequent native message reached that same task and reported an account usage-limit failure; a second successful model response was not claimed.
+
+## [1.12.5] - 2026-09-05
+
+### Fixed
+
+- Preserve the configured environment when the Claude diagnostic starts its MCP child, including sender permission mode and native-relay settings. The MCP SDK's default environment whitelist otherwise drops these settings and can make the diagnostic exercise a different receiver policy than the installed bridge.
+
+### Verification
+
+- The live Codex MCP bridge returned a real Claude Desktop answer through the UUID-correlated transcript path with the expected workspace. The native Codex relay also delivered its marker into the existing Desktop task. No receiver permission settings or Desktop tool restrictions were changed.
+- The live `check:claude` command reported bridge 1.12.5, received the correlated Desktop response, and exited with code 0.
+
 ## [1.12.4] - 2026-09-05
 
 ### Fixed

package/README.md

@@ -8,7 +8,23 @@
 
 A **two-way** bridge between Claude and Codex: Claude pushes prompts into a **live Codex thread**, and Codex messages back into a **running Claude Code session**. Each side sees the other's sessions and follows the conversation inside its own app. Runs on **macOS, Windows and Linux** (the Codex → Claude direction uses unix sockets on macOS/Linux and named pipes on Windows).
 
-This is not `codex exec`, which starts a fresh session every time. The bridge speaks JSON-RPC to the real Codex app-server, so the thread keeps its history, its `cwd`, its model and its rollout file — and a human can watch it run in the Codex desktop app instead of reading the transcript afterwards.
+The bridge preserves task history and working directories across messages. Enable **Desktop tasks** to create, assign, and watch work directly in Codex Desktop. The separate app-server backend remains available for CLI use; it cannot provide live Desktop viewing while it owns the task's writer lock.
+
+### Visible tasks in the correct Desktop project
+
+Install the native companion, add the exact checkout directory as a local project in Codex Desktop, and enable Desktop task delivery:
+
+```bash
+codex-native-relay-install --desktop-tasks
+```
+
+Reload the native companion and the Claude MCP client after upgrading. The installer stores the opt-in in the existing `~/.codex/native-relay.json`; `CODEX_BRIDGE_DESKTOP_TASKS=1` also enables it, and an explicit `0` overrides the shared setting. Desktop mode uses **Codex Desktop permissions**, while the bridge's workspace and thread authorization checks still apply. Existing installations keep their app-server permission settings unless they opt in.
+
+Call `delegate_to_codex` with `cwd`, `prompt`, and optionally `name`. The bridge resolves the real directory, selects the saved local project with that exact path, starts in its existing checkout, and opens the task immediately while it runs. `openInApp: false` suppresses page navigation; project assignment still happens. It never selects a parent directory, remote namesake, or a new worktree. An unsaved worktree must first be saved as its own local project; missing or ambiguous project matches return an error before creating a task.
+
+`start_codex_thread` requires `prompt` in Desktop mode and returns after acceptance. Use `delegate_to_codex` to also wait for the reply. `send_to_codex_thread` continues the existing Desktop task without attaching another writer; its cwd cannot be changed. On timeout, the task continues. Inspect it in Desktop and use its Stop button to interrupt it. Quota failures and approval/input requests remain visible; delivery does not bypass them. An uncertain creation or send is never automatically repeated through another backend.
+
+The updated companion exposes a separate `-desktop-tasks` endpoint so a previous companion holding the legacy reply socket need not be killed during an upgrade. `codex_bridge_status` reports the selected mode; `native_relay_status` reports both endpoints.
 
 ## Architecture
 
@@ -16,7 +32,7 @@ Two MCP servers, one living inside each agent:
 
 ```
                      ┌──────────────── codex-mcp-bridge (runs inside Claude) ──────────────┐
-Claude Desktop ──────┤ stdio                                    WebSocket                  ├──> codex app-server ──> thread shows in Codex Desktop
+Claude Desktop ──────┤ stdio                                    WebSocket                  ├──> separate codex app-server
                      └────────────────────────────────────────────────────────────────────┘
 
                      ┌──────────────── claude-bridge (runs inside Codex) ──────────────────┐
@@ -26,14 +42,14 @@ Codex ───────────────┤ stdio             unix so
 Codex TUI  ──codex --remote ws://127.0.0.1:8791──> same app-server, same live thread
 
                      ┌── codex-native-relay (launched by Codex Desktop, Windows/macOS) ────┐
-claude-bridge ───────┤ named pipe / unix socket                         native tools       ├──> the thread already open in Codex Desktop
+both bridges ───────┤ named pipe / unix socket                         native tools       ├──> visible project tasks in Codex Desktop
                      └────────────────────────────────────────────────────────────────────┘
 ```
 
 - The app-server is a **singleton per port**. The bridge probes `http://127.0.0.1:8791/readyz`; if nothing answers it spawns a detached `codex app-server --listen ws://127.0.0.1:8791`, which keeps running after the bridge exits.
 - Every client pointed at the same URL shares **one app-server**, so `thread/resume` with a `threadId` rejoins the running thread instead of opening a new session.
 - The bridge keeps exactly one WebSocket, calls `initialize` once, and routes notifications by `threadId`, so parallel threads never bleed into each other.
-- `delegate_to_codex` starts the thread at the supplied `cwd`, names it, sends the prompt, and unsubscribes that thread after a terminal turn. It opens `codex://threads/<id>` only after unload is confirmed; other threads on the shared app-server keep running.
+- In app-server mode, `delegate_to_codex` starts the thread at the supplied `cwd`, names it, sends the prompt, and unsubscribes that thread after a terminal turn. It opens `codex://threads/<id>` only after unload is confirmed; other threads on the shared app-server keep running. Desktop mode instead creates and assigns the task through the app immediately.
 - The **native relay** (Windows/macOS, optional) is the third line: a thread the human is watching in Codex Desktop belongs to the app, and a second app-server cannot write to it. Instead of taking the thread away, `claude-bridge` hands the message to a companion the app itself launched, and the app delivers it. See [Codex Desktop native relay](#codex-desktop-native-relay).
 
 ## Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.12.4",
+  "version": "1.13.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/check-claude-bridge.mjs

@@ -7,6 +7,7 @@ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const transport = new StdioClientTransport({
   command: process.execPath,
   args: [path.join(root, "src", "claude-bridge.mjs")],
+  env: { ...process.env },
   stderr: "inherit",
 });
 const client = new Client({ name: "claude-bridge-check", version: "1.0.0" });

package/scripts/check.mjs

@@ -13,6 +13,8 @@ const bridgeEnvNames = [
   "CODEX_BRIDGE_AUTO_APPROVE_ACK",
   "CODEX_BRIDGE_APPROVAL_POLICY",
   "CODEX_BRIDGE_AUTOSTART",
+  "CODEX_BRIDGE_DESKTOP_TASKS",
+  "CODEX_NATIVE_RELAY_SOCKET",
   "CODEX_BRIDGE_EFFORT",
   "CODEX_BRIDGE_MODEL",
   "CODEX_BRIDGE_PATH_MAP",

package/scripts/install-claude-desktop.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { IS_WINDOWS, PLATFORM_LABEL, claudeDesktopConfigPath, resolveCodexBin } from "../src/platform.mjs";
+import { desktopTasksConfigured } from "../src/native-relay.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const cfgPath = process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath();
@@ -85,6 +86,7 @@ cfg.mcpServers["codex-bridge"] = {
     CODEX_BRIDGE_SANDBOX: settled("CODEX_BRIDGE_SANDBOX", "workspace-write"),
     CODEX_BRIDGE_OPEN_IN_APP: settled("CODEX_BRIDGE_OPEN_IN_APP", IS_WINDOWS ? "1" : "0"),
     CODEX_BRIDGE_RELEASE_AFTER_TURN: settled("CODEX_BRIDGE_RELEASE_AFTER_TURN", IS_WINDOWS ? "1" : "0"),
+    CODEX_BRIDGE_DESKTOP_TASKS: settled("CODEX_BRIDGE_DESKTOP_TASKS", desktopTasksConfigured() ? "1" : "0"),
     ...(process.env.CODEX_BRIDGE_ALLOWED_THREADS !== undefined
       ? { CODEX_BRIDGE_ALLOWED_THREADS: process.env.CODEX_BRIDGE_ALLOWED_THREADS }
       : {}),

package/scripts/install-native-relay.mjs

@@ -5,10 +5,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { CodexAppServerClient } from "../src/app-server-client.mjs";
-import { bootstrapRelayThread, readRelayConfig, relayConfigPath, relaySocketPath } from "../src/native-relay.mjs";
+import { bootstrapRelayThread, readRelayConfig, relayConfigPath, relaySocketPath, writeRelayConfig } from "../src/native-relay.mjs";
 import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
 
-const VERSION = "1.12.4";
+const VERSION = "1.13.0";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const entry = path.join(root, "src", "native-relay-companion.mjs");
 const serverName = process.env.CODEX_NATIVE_RELAY_NAME ?? "codex-native-relay";
@@ -81,5 +81,9 @@ if (existing) {
 }
 
 console.log(`\nrelay socket: ${relaySocketPath()}`);
+if (process.argv.includes("--desktop-tasks")) {
+  writeRelayConfig({ ...readRelayConfig(), desktopTasks: true });
+  console.log("Desktop task creation enabled: exact saved local projects, immediate visibility, Codex Desktop permissions.");
+}
 console.log("Restart Codex Desktop so it launches the companion, then check with native_relay_status.");
 console.log("remove: node scripts/install-native-relay.mjs --remove");

package/src/claude-bridge.mjs

@@ -8,7 +8,7 @@ import { PLATFORM_LABEL } from "./platform.mjs";
 import { PeerEndpoint, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
 import { createThreadDelivery } from "./thread-delivery.mjs";
 
-const VERSION = "1.12.4";
+const VERSION = "1.13.0";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 

package/src/index.mjs

@@ -22,8 +22,10 @@ import {
 } from "./platform.mjs";
 import { runTurn } from "./turn.mjs";
 import { BridgeSecurityPolicy } from "./security-policy.mjs";
+import { DesktopTaskDelivery } from "./thread-delivery.mjs";
+import { desktopTasksConfigured } from "./native-relay.mjs";
 
-const VERSION = "1.12.4";
+const VERSION = "1.13.0";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -42,6 +44,8 @@ const DEFAULT_RELEASE_AFTER_TURN = process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN
 const TERMINAL_TURN_STATUSES = new Set(["completed", "interrupted", "failed"]);
 const RELEASE_TURN_STATUSES = TERMINAL_TURN_STATUSES;
 const security = new BridgeSecurityPolicy();
+const desktopTasksEnabled = desktopTasksConfigured();
+const desktopTasks = new DesktopTaskDelivery({ security });
 
 const client = new CodexAppServerClient({
   clientInfo: { name: "codex-mcp-bridge", title: "Codex MCP Bridge", version: VERSION },
@@ -106,6 +110,36 @@ function threadNameFor({ cwd, prompt, name }) {
   );
 }
 
+async function delegateDesktopTask({ cwd, prompt, name, model, effort, timeoutSec, openInApp, waitForReply = true }) {
+  const workspace = resolveWorkspacePath(cwd);
+  const created = await desktopTasks.create({
+    cwd: workspace.path, prompt, name: threadNameFor({ cwd: workspace.path, prompt, name }),
+    model: model ?? DEFAULT_MODEL, effort: effort ?? DEFAULT_EFFORT,
+  });
+  const notes = [];
+  if (workspace.note) notes.push(workspace.note);
+  if (openInApp ?? DEFAULT_OPEN_IN_APP) {
+    try {
+      await desktopTasks.open(created.threadId);
+      notes.push("opened in Codex Desktop while the task runs");
+    } catch (err) {
+      notes.push(`task was accepted; opening its page failed: ${err.message}`);
+    }
+  }
+  const lines = [
+    "Delegated through Codex Desktop", `threadId: ${created.threadId}`, `name: ${created.name}`,
+    `cwd: ${created.cwd}`, `projectId: ${created.projectId}`, `project: ${created.projectName}`,
+    "permissions: Codex Desktop settings; no external app-server writer", ...notes,
+  ];
+  if (!waitForReply) return textResult([...lines, "status: accepted; the task is running in Desktop"].join("\n"));
+  try {
+    const result = await desktopTasks.wait(created.threadId, { timeoutMs: (timeoutSec ?? 240) * 1000 });
+    return textResult([...lines, "", formatTurn(result, { desktop: true })].join("\n"), result.status === "failed" || result.status === "systemError");
+  } catch (err) {
+    return textResult([...lines, `Task was accepted; observation failed: ${err.message}`, "Do not resend the prompt. Inspect the existing task."].join("\n"), true);
+  }
+}
+
 async function createCodexThread({ cwd, model, name, prompt }) {
   const workspace = resolveWorkspacePath(cwd);
   security.assertCwd(workspace.path);
@@ -189,7 +223,7 @@ function formatThreadRow(t) {
   return `- ${t.id}\n    title: ${title}\n    cwd: ${t.cwd ?? "?"}\n    updated: ${updated}  status: ${status}  source: ${t.source ?? "?"}${deepLink}${authorized}`;
 }
 
-function formatTurn(result) {
+function formatTurn(result, { desktop = false } = {}) {
   const lines = [];
   lines.push(`thread: ${result.threadId}`);
   lines.push(`turn:   ${result.turnId ?? "?"}  status: ${result.status}`);
@@ -214,8 +248,9 @@ function formatTurn(result) {
   if (result.status === "timeout") {
     lines.push(
       "",
-      "NOTE: the bridge stopped waiting, but the turn is still running inside Codex.",
-      `Read it later with read_codex_thread, or stop it with interrupt_codex_turn (turnId ${result.turnId}).`,
+      "NOTE: the bridge stopped waiting; it did not pause or cancel the task.",
+      desktop ? "Inspect the task in Codex Desktop; use its Stop button to stop the running turn. Do not resend the prompt." :
+        `Read it later with read_codex_thread, or stop it with interrupt_codex_turn (turnId ${result.turnId}).`,
     );
   }
   if (result.status === "disconnected") {
@@ -234,7 +269,8 @@ const server = new McpServer(
   {
     instructions:
       "Bridge Claude work into Codex. Prefer delegate_to_codex: it creates a named Codex thread at the " +
-      "requested cwd, sends the prompt, releases the bridge writer lock, and opens the exact thread in " +
+      "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.",
   },
@@ -266,7 +302,7 @@ server.registerTool(
       openInApp: z
         .boolean()
         .optional()
-        .describe("Open the finished session in Codex Desktop on Windows or macOS"),
+        .describe("Show the task in Codex Desktop; native tasks open immediately while running"),
       releaseAfterTurn: z
         .boolean()
         .optional()
@@ -284,6 +320,7 @@ server.registerTool(
     const shouldRelease = releaseAfterTurn ?? DEFAULT_RELEASE_AFTER_TURN;
     const notes = [];
     try {
+      if (desktopTasksEnabled) return await delegateDesktopTask({ cwd, prompt, name, model, effort, timeoutSec, openInApp });
       const created = await createCodexThread({ cwd, prompt, name, model });
       if (created.workspace.note) notes.push(created.workspace.note);
       if (shouldOpen && !shouldRelease) {
@@ -376,6 +413,26 @@ server.registerTool(
       const shouldOpen = openInApp ?? DEFAULT_OPEN_IN_APP;
       const shouldRelease = releaseAfterTurn ?? DEFAULT_RELEASE_AFTER_TURN;
       try {
+        if (desktopTasksEnabled) {
+          const workspace = cwd ? resolveWorkspacePath(cwd) : null;
+          if (workspace) security.assertCwd(workspace.path);
+          const delivered = await desktopTasks.send({ threadId, prompt, cwd: workspace?.path, model: model ?? DEFAULT_MODEL, effort: effort ?? DEFAULT_EFFORT, name });
+          notes.push("sent through Codex Desktop; no external app-server writer", `cwd: ${delivered.cwd}`);
+          if (shouldOpen) {
+            try {
+              await desktopTasks.open(threadId);
+              notes.push("opened in Codex Desktop while the task runs");
+            } catch (err) {
+              notes.push(`task was accepted; opening its page failed: ${err.message}`);
+            }
+          }
+          try {
+            const result = await desktopTasks.wait(threadId, { timeoutMs: (timeoutSec ?? 240) * 1000, previousTurnId: delivered.previousTurnId });
+            return textResult([...notes, formatTurn(result, { desktop: true })].join("\n"), result.status === "failed" || result.status === "systemError");
+          } catch (err) {
+            return textResult([...notes, `threadId: ${threadId}`, `Task was accepted; observation failed: ${err.message}. Do not resend.`].join("\n"), true);
+          }
+        }
         const authorizedThread = await assertThreadAccess(threadId);
         let resolvedCwd = null;
         if (cwd) {
@@ -519,21 +576,27 @@ server.registerTool(
   "start_codex_thread",
   {
     title: "Start a new Codex thread",
-    description: "Create a brand new Codex thread in the shared app-server and return its threadId.",
+    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"),
       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"),
     },
     annotations: {
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: false,
       openWorldHint: true,
     },
   },
-  async ({ cwd, model, name }) => {
+  async ({ cwd, model, name, prompt }) => {
     try {
+      if (desktopTasksEnabled) {
+        if (!prompt?.trim()) throw new Error("Desktop task creation requires the initial prompt. Use delegate_to_codex, or pass prompt to start_codex_thread. No task was created.");
+        return await delegateDesktopTask({ cwd, model, name, prompt, waitForReply: false });
+      }
+      if (prompt) throw new Error("Use delegate_to_codex to send an initial prompt in app-server mode.");
       const created = await createCodexThread({ cwd, model, name });
       return textResult(
         [
@@ -567,6 +630,11 @@ server.registerTool(
   },
   async ({ threadId, limit }) => {
     try {
+      if (desktopTasksEnabled) {
+        await desktopTasks.inspect(threadId);
+        const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10) });
+        return textResult(JSON.stringify(response, null, 2));
+      }
       await assertThreadAccess(threadId);
       const res = await client.call("thread/read", { threadId, includeTurns: true });
       const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
@@ -610,6 +678,10 @@ server.registerTool(
   },
   async ({ threadId, turnId }) => {
     try {
+      if (desktopTasksEnabled) {
+        await desktopTasks.inspect(threadId);
+        return textResult("This task is owned by Codex Desktop. Use its Stop button; the separate app-server cannot interrupt a Desktop turn.", true);
+      }
       await assertThreadAccess(threadId);
       const res = await client.call("thread/read", { threadId });
       const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
@@ -645,6 +717,12 @@ server.registerTool(
   },
   async ({ threadId, background }) => {
     try {
+      if (desktopTasksEnabled) {
+        await desktopTasks.inspect(threadId);
+        if (background) await openThreadInCodexApp(threadId, { activate: false });
+        else await desktopTasks.open(threadId);
+        return textResult(`Opened ${codexThreadUrl(threadId)} in Codex Desktop.`);
+      }
       await assertThreadAccess(threadId);
       const res = await client.call("thread/read", { threadId });
       const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
@@ -726,6 +804,7 @@ server.registerTool(
       `autostart:      ${client.autoStart ? "on" : "off"}   approvals: ${client.approval}`,
       `desktop links:  ${supportsCodexThreadLinks() ? "codex:// available" : "not available on this platform"}`,
       `security:       thread policy ${security.threadPolicy} (${summary.allowAllThreads ? "all threads" : `${summary.authorizedThreads} pre-authorized thread(s)`}), ${summary.allowAllRoots ? "all directories" : `${summary.allowedRoots.length} allowed root(s)`}, sandbox ${security.sandbox}, approvals ${security.approvalPolicy}`,
+      `desktop tasks:  ${desktopTasksEnabled ? "enabled; Desktop permissions, exact saved project, immediate visibility" : "disabled; app-server permissions (enable CODEX_BRIDGE_DESKTOP_TASKS=1 to use Desktop permissions)"}`,
       `live threads:   ${liveThreads ?? "(unknown)"}`,
       `claude desktop config: ${claudeDesktopConfigPath()}`,
     ];

package/src/native-relay-companion.mjs

@@ -14,10 +14,13 @@ import {
   RELAY_PROTOCOL_VERSION,
   relaySocketPath,
   resolveRelayThreadId,
+  desktopTaskSocketPath,
+  validateDesktopOperation,
+  decodeNativeToolResult,
 } from "./native-relay.mjs";
 import { IS_WINDOWS, PLATFORM_LABEL } from "./platform.mjs";
 
-const VERSION = "1.12.4";
+const VERSION = "1.13.0";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message) {
@@ -40,8 +43,11 @@ function errorCode(err) {
  */
 export async function handleRelayRequest(
   payload,
-  { dispatch, resolveExecutor = resolveRelayThreadId, env = process.env } = {},
+  { dispatch, dispatchDesktop, resolveExecutor = resolveRelayThreadId, env = process.env } = {},
 ) {
+  if (payload && typeof payload === "object" && Object.hasOwn(payload, "operation")) {
+    return handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env });
+  }
   if (!payload || typeof payload !== "object" || Array.isArray(payload) ||
       Object.keys(payload).some((key) => !["v", "targetThreadId", "message"].includes(key)) ||
       (payload.v !== undefined && payload.v !== RELAY_PROTOCOL_VERSION)) {
@@ -85,6 +91,37 @@ export async function handleRelayRequest(
   }
 }
 
+async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env }) {
+  if (Array.isArray(payload) || payload.v !== RELAY_PROTOCOL_VERSION ||
+      Object.keys(payload).some((key) => !["v", "operation", "arguments"].includes(key))) {
+    return errorResponse("RELAY_BAD_REQUEST", "expected an allowlisted Desktop operation");
+  }
+  try {
+    validateDesktopOperation(payload.operation, payload.arguments);
+    if (typeof dispatchDesktop !== "function") {
+      return errorResponse("NATIVE_OPERATION_UNAVAILABLE", "This companion does not support Desktop operations; reload the native relay");
+    }
+    const executorThreadId = resolveExecutor(env).threadId;
+    if (payload.operation === "send_message_to_thread" && payload.arguments.threadId === executorThreadId) {
+      return errorResponse("RELAY_BAD_REQUEST", "The relay executor cannot receive its own relayed message");
+    }
+    const nativeResult = await dispatchDesktop({
+      executorThreadId,
+      operation: payload.operation,
+      arguments: payload.arguments,
+    });
+    return {
+      ok: true,
+      v: RELAY_PROTOCOL_VERSION,
+      operation: payload.operation,
+      executorThreadId,
+      result: decodeNativeToolResult(nativeResult),
+    };
+  } catch (err) {
+    return errorResponse(errorCode(err), err?.message ?? String(err));
+  }
+}
+
 /**
  * Listens on a private local socket or Windows named pipe and answers one NDJSON line per request.
 *
@@ -95,6 +132,7 @@ export class RelaySocketServer {
   constructor({
     socketPath,
     dispatch,
+    dispatchDesktop,
     resolveExecutor = resolveRelayThreadId,
     restrictSocket = (target) => {
       if (!IS_WINDOWS) fs.chmodSync(target, 0o600);
@@ -103,6 +141,7 @@ export class RelaySocketServer {
   } = {}) {
     this.socketPath = socketPath;
     this.dispatch = dispatch;
+    this.dispatchDesktop = dispatchDesktop;
     this.resolveExecutor = resolveExecutor;
     this.restrictSocket = restrictSocket;
     this.log = logFn;
@@ -238,10 +277,11 @@ export class RelaySocketServer {
     }
     const response = await handleRelayRequest(payload, {
       dispatch: this.dispatch,
+      dispatchDesktop: this.dispatchDesktop,
       resolveExecutor: this.resolveExecutor,
     });
     if (!response.ok) this.log(`relay refused ${payload?.targetThreadId ?? "?"}: ${response.error.message}`);
-    else this.log(`relayed a message into thread ${response.targetThreadId}`);
+    else this.log(response.operation ? `completed Desktop operation ${response.operation}` : `relayed a message into thread ${response.targetThreadId}`);
     this.#reply(socket, response);
   }
 
@@ -338,7 +378,17 @@ if (invokedDirectly) {
   const nativeTools = new NativeToolsClient();
   const dispatch = (args) => nativeTools.dispatch(args);
 
-  const relay = new RelaySocketServer({ socketPath: relaySocketPath(), dispatch, log });
+  const relay = new RelaySocketServer({
+    socketPath: relaySocketPath(),
+    dispatch,
+    dispatchDesktop: (args) => nativeTools.dispatchDesktop(args),
+    log,
+  });
+  const desktopRelay = desktopTaskSocketPath() === relay.socketPath ? relay : new RelaySocketServer({
+    socketPath: desktopTaskSocketPath(),
+    dispatchDesktop: (args) => nativeTools.dispatchDesktop(args),
+    log,
+  });
 
   mcp.registerTool(
     "native_relay_status",
@@ -370,6 +420,7 @@ if (invokedDirectly) {
               `platform:       ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
               `companion:      codex-native-relay ${VERSION}`,
               `relay socket:   ${relay.started ? relay.socketPath : `${relay.socketPath} (${listening ? "shared companion listening" : "not listening"})`}`,
+              `desktop tasks:  ${desktopRelay.socketPath} (${await desktopRelay.isListening() ? "listening" : "not listening"})`,
               `executor:       ${executor}`,
               `dispatch:       ${process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD}`,
               `native pipe:    ${nativeTools.socketPath ?? "unavailable (requires Codex Desktop)"}`,
@@ -381,7 +432,8 @@ if (invokedDirectly) {
   );
 
   const startup = startRelayWhenAvailable({ nativeTools, relay, log });
-  mcp.server.onclose = () => startup.stop();
+  const desktopStartup = desktopRelay === relay ? startup : startRelayWhenAvailable({ nativeTools, relay: desktopRelay, log });
+  mcp.server.onclose = () => { startup.stop(); desktopStartup.stop(); };
   await mcp.connect(new StdioServerTransport());
   log(`ready on ${PLATFORM_LABEL} (${relay.started ? relay.socketPath : "socket down"})`);
 }

package/src/native-relay.mjs

@@ -66,6 +66,16 @@ export function relaySocketPath(env = process.env) {
   return env.CODEX_NATIVE_RELAY_SOCKET ?? (IS_WINDOWS ? WINDOWS_RELAY_SOCKET : path.join(codexHome(env), RELAY_SOCKET_NAME));
 }
 
+export function desktopTaskSocketPath(env = process.env) {
+  return env.CODEX_NATIVE_RELAY_SOCKET ?? `${relaySocketPath(env)}-desktop-tasks`;
+}
+
+export function desktopTasksConfigured(env = process.env) {
+  return env.CODEX_BRIDGE_DESKTOP_TASKS !== undefined
+    ? env.CODEX_BRIDGE_DESKTOP_TASKS === "1"
+    : readRelayConfig(env)?.desktopTasks === true;
+}
+
 export function relayConfigPath(env = process.env) {
   return path.join(codexHome(env), RELAY_CONFIG_NAME);
 }
@@ -141,6 +151,108 @@ export function nativeDispatchParams({ executorThreadId, targetThreadId, message
   };
 }
 
+const DESKTOP_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
+
+function exactObject(value, keys) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) &&
+    Object.keys(value).every((key) => keys.includes(key));
+}
+
+function nonempty(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function optionalText(value) {
+  return value === undefined || nonempty(value);
+}
+
+function optionalInteger(value, min, max) {
+  return value === undefined || Number.isSafeInteger(value) && value >= min && value <= max;
+}
+
+export function validateDesktopOperation(operation, args) {
+  let valid = false;
+  const modelSettings = () => optionalText(args.model) &&
+    (args.thinking === undefined || DESKTOP_EFFORTS.has(args.thinking));
+  switch (operation) {
+    case "list_projects":
+      valid = exactObject(args, []);
+      break;
+    case "create_thread":
+      valid = exactObject(args, ["prompt", "target", "model", "thinking", "title"]) &&
+        nonempty(args.prompt) && optionalText(args.title) && modelSettings() &&
+        exactObject(args.target, ["type", "projectId", "environment"]) &&
+        args.target.type === "project" && nonempty(args.target.projectId) &&
+        exactObject(args.target.environment, ["type"]) && args.target.environment.type === "local";
+      break;
+    case "send_message_to_thread":
+      valid = exactObject(args, ["threadId", "prompt", "model", "thinking"]) &&
+        nonempty(args.threadId) && nonempty(args.prompt) && modelSettings();
+      break;
+    case "read_thread":
+      valid = exactObject(args, ["threadId", "hostId", "cursor", "turnLimit", "includeOutputs", "maxOutputCharsPerItem"]) &&
+        nonempty(args.threadId) && (args.hostId === undefined || args.hostId === "local") &&
+        optionalText(args.cursor) && optionalInteger(args.turnLimit, 1, 10) &&
+        (args.includeOutputs === undefined || typeof args.includeOutputs === "boolean") &&
+        optionalInteger(args.maxOutputCharsPerItem, 1, 16000);
+      break;
+    case "wait_threads":
+      valid = exactObject(args, ["targets", "timeoutMs"]) && args.timeoutMs === 0 &&
+        Array.isArray(args.targets) && args.targets.length >= 1 && args.targets.length <= 8 &&
+        args.targets.every((target) => exactObject(target, ["threadId", "hostId", "afterCursor"]) &&
+          nonempty(target.threadId) && (target.hostId === undefined || target.hostId === "local") &&
+          optionalText(target.afterCursor));
+      break;
+    case "navigate_to_codex_page":
+      valid = exactObject(args, ["threadId"]) && nonempty(args.threadId);
+      break;
+    case "set_thread_title":
+      valid = exactObject(args, ["threadId", "title"]) && nonempty(args.threadId) && nonempty(args.title);
+      break;
+  }
+  if (!valid) throw new NativeRelayError(`Unsupported or invalid Desktop operation: ${operation}`, "RELAY_BAD_REQUEST");
+  return args;
+}
+
+export function nativeDesktopOperationParams({ executorThreadId, operation, arguments: args }) {
+  validateDesktopOperation(operation, args);
+  return {
+    arguments: args,
+    callId: `codex-native-relay-${randomUUID()}`,
+    namespace: "codex_app",
+    threadId: executorThreadId,
+    tool: operation,
+    turnId: `codex-native-relay-turn-${randomUUID()}`,
+  };
+}
+
+export function decodeNativeToolResult(result) {
+  if (result?.success !== true || result?.isError === true) {
+    const detail = (result?.contentItems ?? result?.content ?? []).filter((item) => typeof item?.text === "string").map((item) => item.text).join("\n").slice(0, 2000);
+    throw new NativeRelayError(detail || "Codex Desktop did not confirm the requested operation", "NATIVE_DISPATCH_FAILED");
+  }
+  let decoded = result.structuredContent;
+  if (decoded === undefined) {
+    const items = result.contentItems ?? result.content;
+    if (Array.isArray(items)) {
+      const text = items.filter((item) => item?.type === "inputText" || item?.type === "text")
+        .map((item) => item.text).filter((value) => typeof value === "string").join("\n");
+      if (text) {
+        try {
+          decoded = JSON.parse(text);
+        } catch {
+          decoded = { text };
+        }
+      }
+    }
+  }
+  decoded ??= result;
+  if (decoded?.isError === true || decoded?.success === false) {
+    throw new NativeRelayError("Codex Desktop rejected the requested operation", "NATIVE_DISPATCH_FAILED");
+  }
+  return decoded;
+}
+
 const execFileAsync = promisify(execFile);
 
 function splitDesktopCommandLine(commandLine, platform) {
@@ -389,12 +501,20 @@ export class NativeToolsClient {
   }
 
   async dispatch(args) {
+    return this.#request(nativeDispatchParams(args));
+  }
+
+  async dispatchDesktop(args) {
+    return this.#request(nativeDesktopOperationParams(args));
+  }
+
+  async #request(params) {
     const id = this.nextId++;
     const payload = Buffer.from(JSON.stringify({
       jsonrpc: "2.0",
       id,
       method: this.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD,
-      params: nativeDispatchParams(args),
+      params,
     }));
     if (payload.length > MAX_FRAME_BYTES) {
       throw new NativeRelayError("Native dispatch exceeds the frame limit", "RELAY_MESSAGE_TOO_LARGE");
@@ -503,6 +623,15 @@ export class NativeDesktopRelay {
 
   async sendMessage(targetThreadId, message, { timeoutMs = this.timeoutMs } = {}) {
     const request = { v: RELAY_PROTOCOL_VERSION, targetThreadId, message };
+    return this.#request(request, timeoutMs);
+  }
+
+  async requestDesktop(operation, args, { timeoutMs = this.timeoutMs } = {}) {
+    validateDesktopOperation(operation, args);
+    return this.#request({ v: RELAY_PROTOCOL_VERSION, operation, arguments: args }, timeoutMs);
+  }
+
+  async #request(request, timeoutMs) {
     const line = `${JSON.stringify(request)}\n`;
     if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES) {
       throw new NativeRelayError(
@@ -512,7 +641,10 @@ export class NativeDesktopRelay {
     }
 
     const response = await this.#roundTrip(line, timeoutMs);
-    if (response?.ok === true && response.v === RELAY_PROTOCOL_VERSION) return response;
+    if (response?.ok === true && response.v === RELAY_PROTOCOL_VERSION) {
+      if (request.operation && response.operation !== request.operation) throw new NativeRelayError("The relay answered a different Desktop operation; do not retry this request", "RELAY_BAD_RESPONSE", { reachedCompanion: true });
+      return response;
+    }
     throw new NativeRelayError(
       response?.error?.message ?? "the Codex Desktop relay refused the message",
       response?.error?.code ?? "NATIVE_DISPATCH_FAILED",
@@ -613,7 +745,7 @@ export async function bootstrapRelayThread(client, { cwd = homeDir(), env = proc
     try {
       await client.call("thread/name/set", { threadId, name });
     } catch {}
-    writeRelayConfig({ relayThreadId: threadId, createdAt: new Date().toISOString() }, env);
+    writeRelayConfig({ ...readRelayConfig(env), relayThreadId: threadId, createdAt: new Date().toISOString() }, env);
   } finally {
     release = await client.releaseThread(threadId);
   }

package/src/thread-delivery.mjs

@@ -1,5 +1,7 @@
-import { NativeDesktopRelay } from "./native-relay.mjs";
+import { NativeDesktopRelay, desktopTaskSocketPath } from "./native-relay.mjs";
 import { runTurn } from "./turn.mjs";
+import { realpathSync } from "node:fs";
+import path from "node:path";
 
 /**
  * Which backend puts a message into a Codex thread.
@@ -19,6 +21,124 @@ export const NATIVE_BACKEND = "codex-desktop-native";
 export const APP_SERVER_BACKEND = "app-server";
 const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed"]);
 
+export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync.native, paths = path } = {}) {
+  const requested = canonicalize(cwd);
+  const matches = projects.filter((project) => {
+    if (project.projectKind !== "local" || project.hostId !== "local" || !project.path || !project.projectId) return false;
+    try {
+      return paths.relative(requested, canonicalize(project.path)) === "";
+    } catch {
+      return false;
+    }
+  });
+  if (matches.length !== 1) {
+    throw new Error(matches.length
+      ? `Multiple Codex Desktop projects match ${cwd}; keep one saved project for this directory before delegating.`
+      : `No saved local Codex Desktop project exactly matches ${cwd}. Add that directory as a project in Codex Desktop first.`);
+  }
+  return matches[0];
+}
+
+export class DesktopTaskDelivery {
+  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now } = {}) {
+    this.relay = relay;
+    this.security = security;
+    this.sleep = sleep;
+    this.now = now;
+  }
+
+  async request(operation, args) {
+    const response = await this.relay.requestDesktop(operation, args);
+    return response.result;
+  }
+
+  async create({ cwd, prompt, name, model, effort }) {
+    this.security.assertCwd(cwd);
+    const listed = await this.request("list_projects", {});
+    if (!Array.isArray(listed?.projects)) throw new Error("Codex Desktop returned no project list; no task was created.");
+    const project = matchDesktopProject(listed.projects, cwd);
+    const response = await this.request("create_thread", {
+      prompt,
+      title: name,
+      target: { type: "project", projectId: project.projectId, environment: { type: "local" } },
+      ...(model ? { model } : {}),
+      ...(effort ? { thinking: effort } : {}),
+    });
+    const threadId = response?.threadId ?? response?.conversationId;
+    if (!threadId || response?.status === "outcome-unknown" || response?.firstTurn?.status === "outcome-unknown") {
+      throw new Error(`Desktop creation is not confirmed. Do not resend the prompt: ${JSON.stringify(response)}`);
+    }
+    this.security.registerThread(threadId);
+    if (response.hostId !== "local" || (response.firstTurn && response.firstTurn.status !== "accepted")) {
+      throw new Error(`Desktop created task ${threadId}, but did not confirm a local running turn: ${JSON.stringify(response)}. Inspect this task before retrying.`);
+    }
+    return { threadId, name, cwd, projectId: project.projectId, projectName: project.label, backend: NATIVE_BACKEND };
+  }
+
+  async inspect(threadId, cwd) {
+    const response = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1 });
+    const thread = response?.thread;
+    if (thread?.id !== threadId || thread.hostId !== "local" || !thread.cwd) throw new Error("Desktop did not confirm the task's local workspace.");
+    this.security.assertThread(threadId, thread.cwd);
+    this.security.assertCwd(thread.cwd);
+    if (cwd && path.relative(realpathSync.native(cwd), realpathSync.native(thread.cwd))) {
+      throw new Error("Native Desktop delivery cannot change an existing task's workspace; create a new task at the requested cwd.");
+    }
+    return { thread, latestTurnId: response.turns?.[0]?.id ?? null };
+  }
+
+  async send({ threadId, prompt, cwd, model, effort, name }) {
+    const inspected = await this.inspect(threadId, cwd);
+    if (name) await this.request("set_thread_title", { threadId, title: name.trim().slice(0, 200) });
+    const response = await this.request("send_message_to_thread", {
+      threadId, prompt,
+      ...(model ? { model } : {}),
+      ...(effort ? { thinking: effort } : {}),
+    });
+    if (response?.threadId !== threadId || response?.success === false || response?.isError === true ||
+        (response?.status !== undefined && !["accepted", "sent"].includes(response.status)) ||
+        (response?.firstTurn && response.firstTurn.status !== "accepted")) {
+      throw new Error(`Desktop send is not confirmed for ${threadId}. Do not resend: ${JSON.stringify(response)}`);
+    }
+    return { threadId, cwd: inspected.thread.cwd, name: inspected.thread.title, previousTurnId: inspected.latestTurnId, backend: NATIVE_BACKEND };
+  }
+
+  async open(threadId) {
+    const response = await this.request("navigate_to_codex_page", { threadId });
+    if (response?.navigated !== true) throw new Error(`Desktop did not confirm opening task ${threadId}`);
+  }
+
+  async wait(threadId, { timeoutMs = 240000, previousTurnId = null } = {}) {
+    const startedAt = this.now();
+    let cursor;
+    let turnId = null;
+    let text = "";
+    for (;;) {
+      const response = await this.request("wait_threads", {
+        targets: [{ threadId, hostId: "local", ...(cursor ? { afterCursor: cursor } : {}) }], timeoutMs: 0,
+      });
+      const poll = response?.polls?.find((item) => item.thread?.id === threadId && item.thread?.hostId === "local");
+      if (response?.errors?.length || !poll) throw new Error(`Could not observe task ${threadId}; it may still be running. Read it before retrying: ${JSON.stringify(response)}`);
+      cursor = poll.cursor;
+      const turn = poll.latestTurn;
+      const threadStatus = poll.thread.status?.type;
+      if (["systemError", "waitingOnApproval", "waitingOnUserInput"].includes(threadStatus)) {
+        return { threadId, turnId: turn?.id !== previousTurnId ? turn?.id ?? null : null, status: threadStatus, text: "", activity: [], errors: [], durationMs: this.now() - startedAt };
+      }
+      if (turn?.id && turn.id !== previousTurnId) {
+        turnId = turn.id;
+        if (poll.latestAssistantMessage?.turnId === turnId && poll.latestAssistantMessage?.phase === "final_answer") text = poll.latestAssistantMessage.text ?? text;
+        const status = turn.status;
+        if (RELEASE_STATUSES.has(status)) {
+          return { threadId, turnId, status, text, activity: [], errors: turn.error ? [turn.error] : [], durationMs: turn.durationMs ?? this.now() - startedAt };
+        }
+      }
+      if (this.now() - startedAt >= timeoutMs) return { threadId, turnId, status: "timeout", text, activity: [], errors: [], durationMs: this.now() - startedAt };
+      await this.sleep(Math.min(1500, timeoutMs - (this.now() - startedAt)));
+    }
+  }
+}
+
 export function createThreadDelivery({
   codex,
   relay = new NativeDesktopRelay(),