@minhspark/codex-mcp-bridge 1.21.5 → 1.22.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.21.5",
+  "version": "1.22.0",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -4,6 +4,35 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.22.0] - 2026-10-12
+
+### Added
+
+- Optional response preferences for Desktop reads and reply observation, with tool payload filtering and bounded, replayable cursor pages. Snapshots remain bound to the caller, accounts, workspace, selected task, and delivery receipt (#125).
+
+### Fixed
+
+- Accept completed Desktop replies whose memory citation is represented separately in the completion event, but appended to the authoritative response item. Require an exact reconstruction from validated citation metadata and preserve reply IDs, hashes, lifecycle checks, and conflict rejection (#123).
+- Preserve bounded default history reads while allowing explicit tool output selection. Return structured oversize errors across native transport and serialized MCP responses.
+
+### Upgrade notes
+
+- Update both bridge and native relay companion. Calls without response preferences retain existing response formats and the 2,000-character default item budget. Preferred history reads use a 16,000-character item budget; exact-turn reads retain authoritative assistant text.
+- Cursor pages default to 64 KiB and support 8–96 KiB budgets. Native responses above 8 MiB and authoritative replies above 1 MiB remain explicit limits.
+
+## [1.21.6] - 2026-10-12
+
+### Fixed
+
+- Continue observing a delivered Desktop task through bounded `read_thread` snapshots when the `wait_threads` renderer stops returning results after relay recovery. Preserve the original deadline, access checks, and authoritative reply validation without resending the prompt (#122, #123).
+- Keep native requests capped at 128 KiB while accepting responses up to 8 MiB on both relay hops. Reject larger responses explicitly, trim internal metadata reads, omit tool output from default transcript reads, and bound the serialized MCP read result (#123).
+- Identify failed rollout validation checks and record byte offsets in bounded diagnostics without exposing reply contents. Validation requirements remain unchanged; unsupported rollout sequences still fail closed pending concrete evidence (#123).
+
+### Upgrade notes
+
+- Update both the bridge and native relay companion. Default Desktop transcript reads omit tool outputs and cap each included item at 2,000 characters; use an exact `turnId` for authoritative assistant response inspection.
+- Native frames above 8 MiB, rollout files above 16 MiB, and authoritative replies above 1 MiB remain explicit limits.
+
 ## [1.21.5] - 2026-10-11
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">codex-mcp-bridge</h1>
 
-Local Desktop handoff guides: [daily workflow and directory verification](docs/daily-handoffs.md), [new-machine setup and permissions](docs/new-machine-setup.md), and [project onboarding](docs/project-onboarding.md).
+Local Desktop handoff guides: [daily workflow and directory verification](docs/daily-handoffs.md), [Windows setup](docs/new-windows-setup.md), [macOS setup](docs/new-macos-setup.md), and [project onboarding](docs/project-onboarding.md).
 
 [![npm](https://img.shields.io/npm/v/@minhspark/codex-mcp-bridge?logo=npm&color=CB3837)](https://www.npmjs.com/package/@minhspark/codex-mcp-bridge)
 [![npm downloads](https://raw.githubusercontent.com/buidangminh23/codex-mcp-bridge/analytics/stats-npm-downloads.svg)](https://www.npmjs.com/package/@minhspark/codex-mcp-bridge)

package/docs/daily-handoffs.md

@@ -3,7 +3,7 @@
 Install the messaging MCP entries first. Local Card Bridge Desktop is optional
 and is needed only for automatic task-card startup and its settings UI. Neither
 component uploads an entire local project. For initial installation see
-[new-machine setup](new-machine-setup.md); for grants see
+[Windows setup](new-windows-setup.md) or [macOS setup](new-macos-setup.md); for grants see
 [project onboarding](project-onboarding.md).
 
 Workspace trust, project authorization and host tool permission are separate.

package/docs/new-macos-setup.md

@@ -0,0 +1,67 @@
+# New macOS setup
+
+Connect Claude Desktop's **Code tab** and Codex Desktop through local MCP
+processes and sockets. Both apps still authenticate with their providers and
+use hosted models; local bridge transport does not mean offline inference.
+
+## Local installation: required steps
+
+The [ChatGPT plugin setup](../README.md#chatgpt-plugin) uses a hosted Sites
+connector. For a local Desktop installation, use the following path instead:
+
+1. Install and sign in to Codex Desktop and Claude Desktop under the same macOS
+   user. Have Node.js 22+, npm, the Codex CLI, and the Claude Code CLI available.
+   Save the intended local project in Codex Desktop and open it in Claude's
+   Code tab.
+2. Follow [macOS installation](../README.md#macos-terminal) to install the bridge
+   and register the native relay and reverse bridge. Keep bootstrap enabled on
+   the first relay install. Do not use the ChatGPT plugin pairing instructions,
+   run `codex-sites-connector`, or configure a hosted endpoint.
+3. Follow [Claude Code registration](../README.md#register-claude-code) for the
+   forward bridge. Use the intended project directories for
+   `CODEX_BRIDGE_ALLOWED_ROOTS`, rather than the example's entire home directory;
+   macOS separates multiple roots with `:`. Preserve an existing entry's
+   custom settings.
+4. Add [native relay pipe forwarding](../README.md#native-relay-pipe-forwarding)
+   to the existing relay entry. Forward `CODEX_APP_TOOLS_PIPE_PATH` by name,
+   not its temporary value. The relay needs the trusted app-bundled Node runtime
+   selected by the installer; do not substitute an arbitrary Homebrew/nvm Node.
+5. Reconnect the affected MCP servers in the actual Desktop Code conversations,
+   or restart the affected app after active work finishes. Complete
+   [installation verification](../README.md#verify-the-installation), including
+   a message and reply in each direction.
+
+There are three registrations: `codex-bridge` in Claude Code, and
+`claude-bridge` plus `codex-native-relay` in Codex Desktop. The relay is transport
+plumbing, not a third agent. Ordinary Claude chat has a separate MCP registry;
+adding a server there does not register it in the Code tab.
+
+## Restricted local configuration
+
+Local transport does not require Full Access. Keep the intended sandbox,
+approval reviewer, and project restrictions. Before running installers, check
+for `$CODEX_HOME/bridge-full-access.enabled` (normally
+`~/.codex/bridge-full-access.enabled`): a saved opt-in makes them enable Full
+Access even without `--full-access`. Resolve that existing opt-in deliberately
+before installing; `CODEX_BRIDGE_ENFORCE_FULL_ACCESS=0` does not disable it.
+
+For a restricted Codex setup, these are top-level configuration settings,
+before any `[table]`:
+
+```toml
+approval_policy = "on-request"
+approvals_reviewer = "auto_review"
+sandbox_mode = "workspace-write"
+```
+
+Verify the active Desktop task uses the intended restrictions; defaults alone
+are not evidence of its effective permissions. To suppress optional reporting,
+set `CODEX_BRIDGE_TELEMETRY=0` in all three MCP registrations' environments;
+see [telemetry controls](../README.md#optional-active-install-statistics).
+
+For workspace trust, shared project grants, and optional messaging automation,
+use [project onboarding](project-onboarding.md). For target selection,
+permission mismatches, and uncertain deliveries, use
+[daily Desktop handoffs](daily-handoffs.md) and the
+[technical reference](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md). Tool discovery or a connected socket
+alone does not establish a completed exchange.

package/docs/{new-machine-setup.md → new-windows-setup.md}

@@ -1,4 +1,4 @@
-# New-machine setup and initial permissions
+# New Windows setup and initial permissions
 
 This is a Windows local Desktop source-install guide, not evidence of testing
 on a second machine. Use a pinned source revision containing these scripts;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.21.5",
+  "version": "1.22.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",
@@ -48,7 +48,8 @@
     "LICENSE",
     "CHANGELOG.md",
     "docs/daily-handoffs.md",
-    "docs/new-machine-setup.md",
+    "docs/new-windows-setup.md",
+    "docs/new-macos-setup.md",
     "docs/project-onboarding.md",
     "docs/desktop-handoff-design.md"
   ],

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.21.5",
+  "version": "1.22.0",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs

@@ -23,7 +23,7 @@ import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-acce
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.5";
+const VERSION = "1.22.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

@@ -29,7 +29,7 @@ import { registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.5";
+const VERSION = "1.22.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/codex-native-response.mjs

@@ -21,6 +21,15 @@ function unavailable(reason) {
   return { status: "unavailable", reason: reason?.message ?? String(reason) };
 }
 
+function validationError(message, check, fields = {}) {
+  const details = Object.entries({ check, ...fields }).map(([key, value]) => `${key}=${value}`).join("; ");
+  return new Error(`${message} [${details}]`);
+}
+
+function recordOffsets(entries) {
+  return entries.slice(0, 3).map(({ start }) => start).join(",") || "none";
+}
+
 function configuredSessions(env) {
   const configuredHome = env.CODEX_HOME || path.join(env.HOME || env.USERPROFILE || os.homedir(), ".codex");
   if (!path.isAbsolute(configuredHome)) throw new Error("The configured Codex home must be absolute");
@@ -165,27 +174,44 @@ function recordBelongsToTurn(entry, threadId, turnId) {
   const metadata = object(payload.internal_chat_message_metadata_passthrough) ? payload.internal_chat_message_metadata_passthrough : {};
   const turnFields = [payload.turn_id, payload.root_turn_id, metadata.turn_id, metadata.root_turn_id].filter((value) => value !== undefined);
   if (!turnFields.includes(turnId)) return false;
-  if (turnFields.some((value) => value !== turnId)) throw new Error("The native response contains contradictory turn identity");
+  if (turnFields.some((value) => value !== turnId)) throw validationError("The native response contains contradictory turn identity", "turn_identity", { recordByte: entry.start });
   const threadFields = [payload.thread_id, metadata.thread_id].filter((value) => value !== undefined);
-  if (threadFields.some((value) => value !== threadId)) throw new Error("The native response contains contradictory task identity");
+  if (threadFields.some((value) => value !== threadId)) throw validationError("The native response contains contradictory task identity", "task_identity", { recordByte: entry.start });
   return true;
 }
 
-function responseItemText(payload) {
-  if (!Array.isArray(payload.content) || payload.content.some((item) => !object(item) || item.type !== "output_text" || typeof item.text !== "string")) {
-    throw new Error("The native final response contains unsupported content");
+function responseItemText(entry) {
+  const { payload } = entry.record;
+  const invalidPart = Array.isArray(payload.content)
+    ? payload.content.findIndex((item) => !object(item) || item.type !== "output_text" || typeof item.text !== "string") : "not_array";
+  if (invalidPart !== -1) {
+    throw validationError("The native final response contains unsupported content", "response_content", { responseItemByte: entry.start, contentPart: invalidPart });
   }
   return payload.content.map((item) => item.text).join("");
 }
 
-function completedEventText(item) {
+function completedEventText(entry) {
+  const item = entry.record.payload.item;
   if (!object(item) || item.type !== "AgentMessage" || item.phase !== "final_answer") return null;
-  if (!Array.isArray(item.content) || item.content.some((part) => !object(part) || part.type !== "Text" || typeof part.text !== "string")) {
-    throw new Error("The native completed assistant item contains unsupported content");
+  const invalidPart = Array.isArray(item.content)
+    ? item.content.findIndex((part) => !object(part) || part.type !== "Text" || typeof part.text !== "string") : "not_array";
+  if (invalidPart !== -1) {
+    throw validationError("The native completed assistant item contains unsupported content", "completed_content", { completedEventByte: entry.start, contentPart: invalidPart });
   }
   return item.content.map((part) => part.text).join("");
 }
 
+function completedMemoryCitation(item) {
+  const citation = item.memory_citation;
+  if (!object(citation) || !Array.isArray(citation.entries) || !Array.isArray(citation.rolloutIds)) return null;
+  const singleLine = (value) => typeof value === "string" && !/[\r\n<>]/.test(value);
+  if (citation.entries.some((entry) => !object(entry) || !singleLine(entry.path) || !entry.path || !singleLine(entry.note) ||
+      !Number.isSafeInteger(entry.lineStart) || entry.lineStart < 1 || !Number.isSafeInteger(entry.lineEnd) || entry.lineEnd < entry.lineStart) ||
+      citation.rolloutIds.some((id) => typeof id !== "string" || !UUID.test(id))) return null;
+  const entries = citation.entries.map((entry) => `${entry.path}:${entry.lineStart}-${entry.lineEnd}|note=[${entry.note}]`).join("\n");
+  return `<oai-mem-citation>\n<citation_entries>\n${entries}\n</citation_entries>\n<rollout_ids>\n${citation.rolloutIds.join("\n")}\n</rollout_ids>\n</oai-mem-citation>`;
+}
+
 function inspectTurnRecords(records, threadId, turnId, cwd, { requireDispatch } = {}) {
   const turns = records.filter((entry) => recordBelongsToTurn(entry, threadId, turnId));
   const starts = turns.filter(({ record }) => record.type === "event_msg" && STARTED.has(record.payload.type));
@@ -193,10 +219,16 @@ function inspectTurnRecords(records, threadId, turnId, cwd, { requireDispatch }
   const completions = turns.filter(({ record }) => record.type === "event_msg" && COMPLETED.has(record.payload.type));
   const failures = turns.filter(({ record }) => record.type === "event_msg" &&
     (FAILED.has(record.payload.type) || record.payload.error || ["failed", "aborted", "interrupted"].includes(record.payload.status)));
-  if (failures.length || starts.length !== 1 || contexts.length !== 1 || completions.length !== 1 ||
-      canonicalDirectory(contexts[0].record.payload.cwd, "The observed turn workspace") !== cwd ||
-      starts[0].start >= contexts[0].start || contexts[0].start >= completions[0].start) {
-    throw new Error("The native turn lifecycle is missing, ambiguous, failed, or out of order");
+  const lifecycleError = (check, fields) => validationError("The native turn lifecycle is missing, ambiguous, failed, or out of order", check, fields);
+  if (failures.length) throw lifecycleError("lifecycle_failure", { count: failures.length, eventBytes: recordOffsets(failures) });
+  for (const [kind, entries] of [["start", starts], ["context", contexts], ["completion", completions]]) {
+    if (entries.length !== 1) throw lifecycleError(`lifecycle_${kind}_count`, { count: entries.length, recordBytes: recordOffsets(entries) });
+  }
+  if (canonicalDirectory(contexts[0].record.payload.cwd, "The observed turn workspace") !== cwd) {
+    throw lifecycleError("lifecycle_workspace", { contextByte: contexts[0].start });
+  }
+  if (starts[0].start >= contexts[0].start || contexts[0].start >= completions[0].start) {
+    throw lifecycleError("lifecycle_order", { startByte: starts[0].start, contextByte: contexts[0].start, completionByte: completions[0].start });
   }
 
   let dispatch = null;
@@ -205,47 +237,67 @@ function inspectTurnRecords(records, threadId, turnId, cwd, { requireDispatch }
       record.payload.namespace === "codex_app" && record.payload.name === (requireDispatch.operation ?? "send_message_to_thread"));
     if (dispatches.length !== 1 || !requireDispatch.outputs.includes(dispatches[0].record.payload.output) ||
         contexts[0].start >= dispatches[0].start || dispatches[0].start >= completions[0].start) {
-      throw new Error("The newly observed turn is not correlated to the exact native dispatch");
+      throw validationError("The newly observed turn is not correlated to the exact native dispatch", "dispatch_correlation", {
+        count: dispatches.length, dispatchBytes: recordOffsets(dispatches), contextByte: contexts[0].start, completionByte: completions[0].start,
+      });
     }
     dispatch = dispatches[0];
   }
 
   const allAssistantEntries = turns.filter(({ record }) => record.type === "response_item" && record.payload.type === "message" && record.payload.role === "assistant");
   const finalEntries = allAssistantEntries.filter(({ record }) => record.payload.phase === "final_answer");
-  if (!finalEntries.length && allAssistantEntries.length) throw new Error("The completed native turn has assistant items but no final assistant reply");
+  if (!finalEntries.length && allAssistantEntries.length) throw validationError("The completed native turn has assistant items but no final assistant reply", "missing_final_phase", {
+    count: allAssistantEntries.length, responseItemBytes: recordOffsets(allAssistantEntries),
+  });
   const assistantItems = [];
-  const ids = new Set();
+  const ids = new Map();
   for (const entry of finalEntries) {
     const { payload } = entry.record;
     if (typeof payload.id !== "string" || !payload.id.trim() || ids.has(payload.id) ||
         entry.start <= (dispatch?.start ?? contexts[0].start) || entry.start >= completions[0].start) {
-      throw new Error("The native final response item identity is missing, duplicated, or out of order");
+      const check = typeof payload.id !== "string" || !payload.id.trim() ? "response_item_id_missing" : ids.has(payload.id) ? "response_item_id_duplicate" : "response_item_order";
+      throw validationError("The native final response item identity is missing, duplicated, or out of order", check, {
+        responseItemByte: entry.start, previousItemByte: ids.get(payload.id)?.start ?? "none",
+        afterByte: dispatch?.start ?? contexts[0].start, completionByte: completions[0].start,
+      });
     }
-    ids.add(payload.id);
-    const text = responseItemText(payload);
-    if (!text.trim()) throw new Error("The native final response item is empty");
+    ids.set(payload.id, entry);
+    const text = responseItemText(entry);
+    if (!text.trim()) throw validationError("The native final response item is empty", "response_item_empty", { responseItemByte: entry.start });
     assistantItems.push({ id: payload.id, text });
   }
 
   const eventItems = new Map();
-  for (const { record, start } of turns) {
+  for (const entry of turns) {
+    const { record, start } = entry;
     if (record.type !== "event_msg" || record.payload.type !== "item_completed") continue;
     const eventItem = record.payload.item;
     if (ids.has(eventItem?.id) && (eventItem.type !== "AgentMessage" || eventItem.phase !== "final_answer")) {
-      throw new Error("The native assistant item representations conflict in type or phase");
+      throw validationError("The native assistant item representations conflict in type or phase", "assistant_representation_type_phase", {
+        responseItemByte: ids.get(eventItem.id).start, completedEventByte: start,
+      });
     }
-    const text = completedEventText(record.payload.item);
+    const text = completedEventText(entry);
     if (text === null) continue;
     const id = record.payload.item.id;
     if (typeof id !== "string" || !id.trim() || eventItems.has(id) || start <= contexts[0].start || start >= completions[0].start) {
-      throw new Error("The native completed assistant item identity is missing, duplicated, or out of order");
+      const check = typeof id !== "string" || !id.trim() ? "completed_item_id_missing" : eventItems.has(id) ? "completed_item_id_duplicate" : "completed_item_order";
+      throw validationError("The native completed assistant item identity is missing, duplicated, or out of order", check, {
+        completedEventByte: start, previousEventByte: eventItems.get(id)?.start ?? "none",
+        contextByte: contexts[0].start, completionByte: completions[0].start,
+      });
     }
-    eventItems.set(id, text);
+    eventItems.set(id, { text, start, memoryCitation: completedMemoryCitation(eventItem) });
   }
   for (const item of assistantItems) {
-    if (eventItems.has(item.id) && eventItems.get(item.id) !== item.text) throw new Error("The native assistant item representations conflict");
+    const event = eventItems.get(item.id);
+    if (event && event.text !== item.text && (!event.memoryCitation || event.text + event.memoryCitation !== item.text)) throw validationError("The native assistant item representations conflict", "assistant_representation_text", {
+      responseItemByte: ids.get(item.id).start, completedEventByte: eventItems.get(item.id).start,
+    });
+  }
+  for (const [id, event] of eventItems) {
+    if (!ids.has(id)) throw validationError("The native completed assistant item has no matching authoritative response item", "authoritative_response_missing", { completedEventByte: event.start });
   }
-  if ([...eventItems.keys()].some((id) => !ids.has(id))) throw new Error("The native completed assistant item has no matching authoritative response item");
 
   const text = assistantItems.map((item) => item.text).join("\n\n");
   if (Buffer.byteLength(text, "utf8") > MAX_REPLY_BYTES) throw new Error("The native final response exceeds the bounded reply limit");

package/src/desktop-read-tools.mjs

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { DESKTOP_TOOL_BUDGET_MS } from "./thread-delivery.mjs";
+import { captureProjectScope, recheckProjectScope } from "./project-scope.mjs";
+import { ResponseSnapshots, responsePreferencesSchema, normalizeResponsePreferences, projectHistory, projectReply, assertResponseResultSize } from "./response-preferences.mjs";
+
+export function registerDesktopReadTools(registerTool, {
+  desktopTasksEnabled, desktopTasks, replyReceipts, security, client,
+  context: operationContext, assertOperation,
+  assertThreadAccess, normalizeThreadCwd, textResult, replyResult, failure,
+}) {
+  const snapshots = new ResponseSnapshots();
+  const invalid = (message) => Object.assign(new Error(message), { code: "INVALID_RESPONSE_PREFERENCES" });
+  const receiptHash = (delivered) => createHash("sha256").update(JSON.stringify(delivered)).digest("hex");
+  const binding = (operation) => {
+    const { accounts, caller } = operationContext();
+    return { operation, accounts, caller: { sessionId: caller.sessionId, taskId: caller.taskId, cwd: caller.cwd } };
+  };
+  const selector = (values) => Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+
+  async function authorize(auth, deliveryId) {
+    const context = operationContext();
+    await assertOperation(context);
+    if (deliveryId && receiptHash(replyReceipts.read(deliveryId, context)) !== auth.receiptHash) {
+      throw new Error("Reply observation binding changed; cached content was withheld");
+    }
+    if (auth.projectScope) recheckProjectScope(auth.projectScope);
+    if (auth.scopeBinding) security.hardenedRoots.recheck(auth.scopeBinding);
+    if (auth.threadId) {
+      const current = await desktopTasks.inspect(auth.threadId, auth.cwd, { deadline: context.deadline });
+      if (auth.projectScope) recheckProjectScope(auth.projectScope, current.projectScope);
+      if (auth.scopeBinding) security.hardenedRoots.recheck(auth.scopeBinding);
+    }
+    await assertOperation(context);
+  }
+
+  async function authorization(threadId, cwd, deliveryId, originalReceipt) {
+    const inspected = threadId ? await desktopTasks.inspect(threadId, cwd, { deadline: operationContext().deadline }) : null;
+    return { threadId, cwd: inspected?.thread.cwd ?? cwd, projectScope: inspected?.projectScope ?? captureProjectScope(operationContext().caller.cwd, cwd),
+      scopeBinding: inspected?.scopeBinding ?? (security.hardenedRoots?.mode === "project-policy" ? security.hardenedRoots.capture(cwd) : undefined), ...(deliveryId ? { receiptHash: receiptHash(originalReceipt) } : {}) };
+  }
+
+  async function continuation(preferences, owner, selection, deliveryId) {
+    const cached = snapshots.inspect(preferences, owner, selection);
+    await authorize(cached.authorization, deliveryId);
+    const result = snapshots.continue({ preferences, binding: owner, selection });
+    await authorize(cached.authorization, deliveryId);
+    return result;
+  }
+
+  async function respond({ preferences, owner, selection, metadata, items, auth, deliveryId }) {
+    await authorize(auth, deliveryId);
+    const result = snapshots.respond({ preferences, binding: owner, selection, metadata, items, authorization: auth });
+    await authorize(auth, deliveryId);
+    return result;
+  }
+
+  async function preferredRead({ threadId, turnId, limit, responsePreferences }) {
+    const owner = binding("read_codex_thread");
+    const selection = selector({ threadId, turnId, limit });
+    if (responsePreferences.delivery?.options?.cursor) return continuation(responsePreferences, owner, selection);
+    const preferences = normalizeResponsePreferences(responsePreferences);
+    const auth = await authorization(threadId);
+    const deadline = operationContext().deadline;
+    if (turnId) {
+      const response = await desktopTasks.inspectNativeTurn(threadId, turnId, auth.cwd, { deadline });
+      const { assistantItems, text, ...metadata } = response;
+      return respond({ preferences, owner, selection: { ...selection, limit: limit ?? 10 }, auth,
+        metadata: { ...metadata, threadId, turnId, turnStatus: response.turnStatus ?? (["completed", "completed_no_reply"].includes(response.status) ? "completed" : null) },
+        items: projectReply(assistantItems ?? [], turnId) });
+    }
+    const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10), includeOutputs: preferences.filter.includeToolPayloads, maxOutputCharsPerItem: 16000 }, { deadline });
+    const projected = projectHistory(response.turns ?? [], preferences.filter);
+    return respond({ preferences, owner, selection: { ...selection, limit: limit ?? 10 }, auth,
+      metadata: { threadId, turnId: response.turns?.[0]?.id ?? null, turnStatus: response.turns?.[0]?.status ?? null,
+        turns: projected.turns, sourceHasMore: response.page?.hasMore ?? Boolean(response.page?.nextCursor), omissions: projected.omissions },
+      items: projected.items });
+  }
+
+  async function preferredWait({ deliveryId, timeoutSec, responsePreferences }) {
+    const owner = binding("wait_codex_reply");
+    const selection = { deliveryId };
+    if (responsePreferences.delivery?.options?.cursor) {
+      if (timeoutSec !== undefined) throw invalid("A cursor reads a snapshot; omit timeoutSec on continuation");
+      return continuation(responsePreferences, owner, selection, deliveryId);
+    }
+    const preferences = normalizeResponsePreferences(responsePreferences);
+    const context = operationContext();
+    const originalReceipt = replyReceipts.read(deliveryId, context);
+    let delivered = originalReceipt;
+    // Leave time for the live authorization checks after observation.
+    const remaining = Math.max(0, context.deadline - Date.now());
+    const observationDeadline = context.deadline - Math.min(1000, Math.floor(remaining / 4));
+    const timeout = () => ({ threadId: delivered.threadId, status: "timeout", responseStatus: "unavailable", text: "" });
+    if (delivered.creationObservation) {
+      delivered = await desktopTasks.resolveCreation(delivered, { deadline: observationDeadline }) ?? delivered;
+    }
+    const auth = await authorization(delivered.threadId, delivered.cwd, deliveryId, originalReceipt);
+    const finish = async (result) => {
+      const { text, assistantItems, activity, ...metadata } = result;
+      return respond({ preferences, owner, selection, auth, deliveryId,
+        metadata: { ...metadata, threadId: delivered.threadId, turnId: result.turnId ?? null,
+          turnStatus: ["completed", "interrupted", "failed"].includes(result.status) ? result.status : null, deliveryId,
+          deliveryStatus: ["completed", "completed_no_reply"].includes(result.responseStatus) ? "accepted" : delivered.deliveryStatus ?? "accepted",
+          nextAction: result.status === "timeout" ? "wait_codex_reply" : "none" },
+        items: projectReply(assistantItems ?? [], result.turnId) });
+    };
+    if (!delivered.threadId || Date.now() >= observationDeadline) return finish(timeout());
+    const result = await desktopTasks.withThread(delivered.threadId, () => desktopTasks.wait(delivered.threadId, {
+      timeoutMs: Math.max(0, observationDeadline - Date.now()), previousTurnId: delivered.previousTurnId,
+      responseObservation: delivered.responseObservation,
+    }), { deadline: observationDeadline, onDeadline: timeout });
+    return finish(result);
+  }
+registerTool(
+  "wait_codex_reply",
+  {
+    title: "Continue waiting for a Codex reply",
+    description: "Continue a Desktop creation or send using its deliveryId; an unconfirmed acknowledgement does not prove delivery, including after MCP reconnect. Never sends a message or creates a task. On timeout, call again with the same deliveryId; do not ask the user to fetch the answer or resend. Stops for approval, user input or a verification error. Only the original verified Claude session and accounts can use the receipt.",
+    inputSchema: {
+      responsePreferences: responsePreferencesSchema.optional().describe("Opt in to versioned filtered responses and cursor delivery; omitted preserves existing behavior. Inspect the returned envelope and follow nextCursor with the same tool and selector."),
+      deliveryId: z.string().uuid().describe("Exact deliveryId returned by send_to_codex_thread, delegate_to_codex or start_codex_thread"),
+      timeoutSec: z.number().int().min(1).max(40).optional().describe("Bounded observation time, default 40 seconds; repeat with the same receipt if still running"),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  async ({ deliveryId, timeoutSec, responsePreferences }) => {
+    if (responsePreferences !== undefined) {
+      try {
+        if (!desktopTasksEnabled) throw invalid("responsePreferences requires Desktop native delivery");
+        return await preferredWait({ deliveryId, timeoutSec, responsePreferences });
+      } catch (error) { return failure(error); }
+    }
+    if (!desktopTasksEnabled) return failure(new Error("Reply continuations require Desktop native delivery"));
+    const context = operationContext();
+    let delivered = replyReceipts.read(deliveryId, context);
+    if (delivered.creationObservation) {
+      const resolved = await desktopTasks.resolveCreation(delivered, { deadline: context.deadline });
+      if (!resolved) return replyResult(delivered, deliveryId, { threadId: null, status: "timeout", responseStatus: "unavailable", text: "" });
+      delivered = resolved;
+    }
+    const { threadId } = delivered;
+    const expired = () => replyResult(delivered, deliveryId, { threadId, status: "timeout", responseStatus: "unavailable", text: "" });
+    return desktopTasks.withThread(threadId, async () => {
+      await desktopTasks.inspect(threadId, delivered.cwd, { deadline: context.deadline });
+      const result = await desktopTasks.wait(threadId, { timeoutMs: Math.max(0, context.deadline - Date.now()), previousTurnId: delivered.previousTurnId, responseObservation: delivered.responseObservation });
+      return replyResult(delivered, deliveryId, result);
+    }, { deadline: context.deadline, onDeadline: expired });
+  },
+);
+
+registerTool(
+  "read_codex_thread",
+  {
+    title: "Read a Codex thread",
+    description: "Read a Codex thread without sending anything. In Desktop mode, pass the exact turnId returned by send_to_codex_thread for authoritative assistant item IDs, text, and reply hash; without turnId the native recent-history view may omit items.",
+    inputSchema: {
+      responsePreferences: responsePreferencesSchema.optional().describe("Opt in to versioned filtered responses and cursor delivery; omitted preserves existing behavior. Inspect the returned envelope and follow nextCursor with the same tool and selector."),
+      threadId: z.string().describe("Codex thread id"),
+      turnId: z.string().optional().describe("Exact turn id to inspect authoritatively in Codex Desktop mode"),
+      limit: z.number().int().min(1).max(50).optional().describe("How many recent messages to show (default 10)"),
+    },
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ threadId, turnId, limit, responsePreferences }) => {
+    try {
+      if (responsePreferences !== undefined) {
+        if (!desktopTasksEnabled) throw invalid("responsePreferences requires Desktop native delivery");
+        return await preferredRead({ threadId, turnId, limit, responsePreferences });
+      }
+      if (desktopTasksEnabled) {
+        const deadline = operationContext()?.deadline ?? Date.now() + DESKTOP_TOOL_BUDGET_MS;
+        if (turnId) {
+          const response = await desktopTasks.inspectNativeTurn(threadId, turnId, undefined, { deadline });
+          return assertResponseResultSize(textResult(JSON.stringify(response, null, 2), response.status === "unavailable"));
+        }
+        await desktopTasks.inspect(threadId, undefined, { deadline });
+        const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10), includeOutputs: false, maxOutputCharsPerItem: 2000 }, { deadline });
+        return assertResponseResultSize(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 });
+      security.assertCwd(thread.cwd);
+      const items = (thread.turns ?? []).flatMap((t) => t.items ?? []);
+      const msgs = items
+        .filter((i) => i?.type === "agentMessage" || i?.type === "userMessage")
+        .slice(-(limit ?? 10))
+        .map((i) => {
+          const body =
+            i.type === "userMessage"
+              ? (i.content ?? [])
+                  .map((c) => (c.type === "text" ? c.text : `<${c.type}>`))
+                  .join(" ")
+              : (i.text ?? "");
+          return `[${i.type === "userMessage" ? "user" : "codex"}] ${body.trim()}`;
+        });
+      const header = `thread ${threadId}\n  title: ${thread.name ?? "(unnamed)"}\n  cwd: ${thread.cwd ?? "?"}\n  status: ${thread.status?.type ?? "?"}`;
+      return textResult(msgs.length ? `${header}\n\n${msgs.join("\n\n")}` : `${header}\n\n(no messages found)`);
+    } catch (err) {
+      return failure(err);
+    }
+  },
+);
+}