From 9a9557f737614881b3a6f7d316e23e42d1716f54 Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Wed, 9 Sep 2026 08:30:49 +0000
Subject: [PATCH 1/2] fix(app): support Codex custom-scheme origins

---
 .changeset/pin-codex-sandbox-origin.md        |   5 +
 docs/entry-conventions.md                     |  16 +--
 packages/agent-bundle/src/app/index.ts        |  49 ++++++--
 .../agent-bundle/tests/app-client.test.ts     | 117 +++++++++++++++++-
 .../tests/public-api-packed.test.ts           |  38 ++++++
 website/docs/en/guide/authoring/mcp.mdx       |  22 ++--
 website/docs/en/reference/security.mdx        |  18 +--
 website/docs/zh/guide/authoring/mcp.mdx       |  15 +--
 website/docs/zh/reference/security.mdx        |  13 +-
 9 files changed, 235 insertions(+), 58 deletions(-)
 create mode 100644 .changeset/pin-codex-sandbox-origin.md

diff --git a/.changeset/pin-codex-sandbox-origin.md b/.changeset/pin-codex-sandbox-origin.md
new file mode 100644
index 000000000..1e432101b
--- /dev/null
+++ b/.changeset/pin-codex-sandbox-origin.md
@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Allow `createAppClient()` to pin Codex Desktop `codex-sandbox://` response origins while keeping configured `targetOrigin` HTTP(S)-only (#PR)
diff --git a/docs/entry-conventions.md b/docs/entry-conventions.md
index d573a1ee0..3e8a4918f 100644
--- a/docs/entry-conventions.md
+++ b/docs/entry-conventions.md
@@ -1799,25 +1799,25 @@ that cancellation cannot bypass consent or reach a request the App did not
 start. Hosts outside the framework apply their own policy; the client's
 behavior is the same either way.
 
-### Opaque sandbox handshake
+### Dynamic sandbox handshake
 
 The Workbench and `serve-app` render the App as `<iframe sandbox="allow-scripts"
 referrerpolicy="no-referrer" srcdoc=…>`, so the document has an opaque
 origin and no referrer to learn its host origin from. The client therefore
 sends exactly one frame to `'*'` — its own `ui/initialize` — and accepts a
 response only when `event.source` is the configured parent, the id is that
-bootstrap request's, and the result validates; it then pins `event.origin`,
-held to the same rule as `targetOrigin` — an exact `http:` or `https:` origin;
-an empty, `'null'`, or other-scheme origin fails the handshake as
-`invalid-message` — posts `ui/notifications/initialized` and every later
-request to that exact origin, and ignores every message from another source or
-origin. The initialize result also names the opening tool
+bootstrap request's, and the result validates; it then pins `event.origin`
+raw for inbound messages. Exact `http:` or `https:` origins are also used as
+the outbound target; opaque `'null'` and host-private origins such as
+`codex-sandbox://…` use `'*'` outbound. An empty or literal `'*'` origin fails
+the handshake as `invalid-message`. Every later inbound message must match
+both the parent and exact raw pinned origin. The initialize result also names the opening tool
 (`hostContext.toolInfo.tool.name`), which is what the opening-notification
 listeners dispatch on. A malformed message that still names a pending id
 rejects that request as `invalid-message`. A host that can name its origin
 passes `targetOrigin` — an exact `http:` or `https:` origin; `'*'`, `'null'`,
 other schemes, and non-origin strings are a `TypeError` — and no wildcard frame
-is sent. Author code has no wildcard send path. The transport is DOM-shaped
+is sent. The transport is DOM-shaped
 (`AppWindow`, `AppMessageTarget`) rather than bound to the global `window`, so
 `tests/app-client.test.ts` and non-DOM hosts drive the same core through
 injected ports.
diff --git a/packages/agent-bundle/src/app/index.ts b/packages/agent-bundle/src/app/index.ts
index 9783d34f5..2bc3a14a5 100644
--- a/packages/agent-bundle/src/app/index.ts
+++ b/packages/agent-bundle/src/app/index.ts
@@ -198,6 +198,11 @@ interface PendingRequest {
   readonly abort?: () => void;
 }
 
+interface AppOriginPin {
+  readonly incoming: string;
+  readonly outgoing: string;
+}
+
 type AnyListener = (value: unknown) => Promise<void> | void;
 
 const allowedMessageKeys = Object.freeze(['error', 'id', 'jsonrpc', 'method', 'params', 'result']);
@@ -237,6 +242,17 @@ const trustedOrigin = (value: string | undefined): string | undefined => {
   return value;
 };
 
+const originPin = (value: string): AppOriginPin => {
+  if (value === '*' || !nonempty(value)) {
+    throw new TypeError('App client cannot pin an empty or wildcard origin.');
+  }
+  try {
+    return { incoming: value, outgoing: trustedOrigin(value)! };
+  } catch {
+    return { incoming: value, outgoing: '*' };
+  }
+};
+
 const currentWindow = (): AppWindow => {
   const candidate = (globalThis as { readonly window?: AppWindow }).window;
   if (candidate === undefined) {
@@ -339,6 +355,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
   let parent = options.parent ?? boundWindow.parent;
   let configuredOrigin = trustedOrigin(options.targetOrigin);
   let pinnedOrigin = configuredOrigin;
+  let postOrigin = configuredOrigin;
   let nextId = 0;
   let connectionGeneration = 0;
   let connection: Promise<AppInitializeResult> | undefined;
@@ -365,7 +382,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
 
   const post = (message: JsonObject, targetOrigin: string): void => {
     try {
-      parent.postMessage(message, targetOrigin === 'null' ? '*' : targetOrigin);
+      parent.postMessage(message, targetOrigin);
     } catch {
       throw new AppClientError('invalid-message', 'The App host rejected a JSON-RPC message.');
     }
@@ -383,13 +400,13 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
   };
 
   const notifyCancelled = (id: null | number | string, reason: string): void => {
-    if (connectedResult === undefined || pinnedOrigin === undefined) return;
+    if (connectedResult === undefined || postOrigin === undefined) return;
     try {
       post({
         jsonrpc: '2.0',
         method: 'notifications/cancelled',
         params: { reason, requestId: id },
-      }, pinnedOrigin);
+      }, postOrigin);
     } catch {
       // The original timeout or abort remains the observable request failure.
     }
@@ -407,8 +424,8 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
   };
 
   const sendResponse = (id: null | number | string, result: JsonObject): void => {
-    if (pinnedOrigin === undefined) return;
-    post({ id, jsonrpc: '2.0', result }, pinnedOrigin);
+    if (postOrigin === undefined) return;
+    post({ id, jsonrpc: '2.0', result }, postOrigin);
   };
 
   const publishOpening = (listeners: Map<string, Set<AnyListener>>, value: unknown): void => {
@@ -429,6 +446,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     connectedResult = undefined;
     openingToolName = undefined;
     pinnedOrigin = undefined;
+    postOrigin = undefined;
     inputListeners.clear();
     resultListeners.clear();
     errorListeners.clear();
@@ -450,10 +468,10 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     if (message.method === undefined) {
       const request = message.id === undefined ? undefined : clearPending(message.id);
       if (request === undefined) return;
-      let responseOrigin: string | undefined;
+      let responseOrigin: AppOriginPin | undefined;
       if (request.initialize && configuredOrigin === undefined) {
         try {
-          responseOrigin = event.origin === 'null' ? 'null' : trustedOrigin(event.origin);
+          responseOrigin = originPin(event.origin);
         } catch {
           request.reject(new AppClientError('invalid-message', 'The App host returned an unpinnable origin.'));
           return;
@@ -471,12 +489,15 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
         request.reject(new AppClientError('invalid-message', `The App host did not negotiate protocol ${APP_PROTOCOL_VERSION}.`));
         return;
       }
-      if (responseOrigin !== undefined) pinnedOrigin = responseOrigin;
+      if (responseOrigin !== undefined) {
+        pinnedOrigin = responseOrigin.incoming;
+        postOrigin = responseOrigin.outgoing;
+      }
       request.resolve(message.result);
       return;
     }
 
-    if (pinnedOrigin === undefined || connectedResult === undefined) return;
+    if (postOrigin === undefined || connectedResult === undefined) return;
     if (message.id !== undefined) {
       if (message.method === 'ui/resource-teardown') {
         try {
@@ -490,7 +511,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
         error: { code: -32601, message: `${message.method} is not supported by this App client.` },
         id: message.id,
         jsonrpc: '2.0',
-      }, pinnedOrigin);
+      }, postOrigin);
       return;
     }
     if (message.method === 'ui/notifications/tool-input') {
@@ -550,7 +571,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
       return Promise.reject(new AppClientError('invalid-message', 'App client request params must be finite strict JSON.'));
     }
     const id = ++nextId;
-    const targetOrigin = initialize ? configuredOrigin ?? '*' : pinnedOrigin;
+    const targetOrigin = initialize ? configuredOrigin ?? '*' : postOrigin;
     if (targetOrigin === undefined) {
       return Promise.reject(new AppClientError('capability-unavailable', 'The App client is not connected.'));
     }
@@ -604,10 +625,10 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
         throw new AppClientError('connection-rebound', 'The App client connection was rebound.');
       }
       const initialized = initializeResult(result);
-      if (initialized === undefined || pinnedOrigin === undefined) {
+      if (initialized === undefined || pinnedOrigin === undefined || postOrigin === undefined) {
         throw new AppClientError('invalid-message', 'The App host returned an invalid initialize result.');
       }
-      post({ jsonrpc: '2.0', method: 'ui/notifications/initialized' }, pinnedOrigin);
+      post({ jsonrpc: '2.0', method: 'ui/notifications/initialized' }, postOrigin);
       connectedResult = initialized;
       const toolInfo = isPlainDataRecord(initialized.hostContext.toolInfo)
         ? initialized.hostContext.toolInfo
@@ -715,6 +736,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
       connectedResult = undefined;
       openingToolName = undefined;
       pinnedOrigin = undefined;
+      postOrigin = undefined;
       const replacementWindow = rebindOptions.window ?? boundWindow;
       if (replacementWindow !== boundWindow) {
         boundWindow.removeEventListener('message', receive);
@@ -724,6 +746,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
       parent = rebindOptions.parent ?? boundWindow.parent;
       configuredOrigin = nextOrigin;
       pinnedOrigin = configuredOrigin;
+      postOrigin = configuredOrigin;
       return await connect();
     },
     dispose,
diff --git a/packages/agent-bundle/tests/app-client.test.ts b/packages/agent-bundle/tests/app-client.test.ts
index 7820db93c..55081a9e7 100644
--- a/packages/agent-bundle/tests/app-client.test.ts
+++ b/packages/agent-bundle/tests/app-client.test.ts
@@ -73,6 +73,12 @@ interface PostedMessage {
 }
 
 const hostOrigin = 'https://host.example';
+const codexOrigin = 'codex-sandbox://stable-dashboard-id';
+const dynamicHostOriginMatrix = [
+  { host: 'Codex Desktop registered scheme', incoming: codexOrigin, outgoing: '*' },
+  { host: 'Codex opaque sandbox', incoming: 'null', outgoing: '*' },
+  { host: 'Workbench HTTP parent', incoming: hostOrigin, outgoing: hostOrigin },
+] as const;
 const typeProofs: readonly [
   RouteIdProof,
   RouteInputProof,
@@ -151,6 +157,16 @@ it('uses one shared protocol version for the App client and MCP App profile', ()
   expect(APP_PROTOCOL_VERSION).toBe(MCP_APP_PROTOCOL_VERSION);
 });
 
+it('conforms to the dynamic host origin matrix', async () => {
+  for (const profile of dynamicHostOriginMatrix) {
+    const target = harness();
+    const client = createAppClient({ window: target.window });
+    await connect(client, target, profile.incoming);
+    expect(target.posts.at(-1)?.targetOrigin, profile.host).toBe(profile.outgoing);
+    client.dispose();
+  }
+});
+
 it('accepts AbortController signals through the structural app contract', () => {
   const signal: AppAbortSignal = new AbortController().signal;
   const options: AppRequestOptions = { signal };
@@ -222,6 +238,47 @@ it('connects and calls through Codex opaque origin only for the matching parent'
   await expect(called).resolves.toEqual({ active: 3, status: 'healthy' });
 });
 
+it('connects and calls through a pinned Codex custom-scheme origin', async () => {
+  const target = harness();
+  const foreignParent = {};
+  const client = createAppClient({ window: target.window });
+  const connecting = client.connect();
+
+  let initialized = false;
+  void connecting.then(() => { initialized = true; }, () => { initialized = true; });
+  target.emit({ id: 1, jsonrpc: '2.0', result: initializeResult }, codexOrigin, foreignParent);
+  await flushListeners();
+  expect(initialized).toBe(false);
+  target.emit({ id: 1, jsonrpc: '2.0', result: initializeResult }, codexOrigin);
+  await expect(connecting).resolves.toEqual(initializeResult);
+  expect(target.posts.at(-1)).toEqual({
+    message: { jsonrpc: '2.0', method: 'ui/notifications/initialized' },
+    targetOrigin: '*',
+  });
+
+  const called = client.call('tool:hauler/hauler_status', { limit: 40 });
+  expect(target.posts.at(-1)?.targetOrigin).toBe('*');
+  const callId = responseId(target.posts.at(-1)!);
+  const result = {
+    id: callId,
+    jsonrpc: '2.0',
+    result: {
+      content: [{ text: 'healthy', type: 'text' }],
+      structuredContent: { active: 3, status: 'healthy' },
+    },
+  } as const;
+  let settled = false;
+  void called.then(() => { settled = true; }, () => { settled = true; });
+  target.emit(result, codexOrigin, foreignParent);
+  target.emit(result, 'https://host.example');
+  target.emit(result, 'null');
+  target.emit(result, 'codex-sandbox://changed-dashboard-id');
+  await flushListeners();
+  expect(settled).toBe(false);
+  target.emit(result, codexOrigin);
+  await expect(called).resolves.toEqual({ active: 3, status: 'healthy' });
+});
+
 it('dynamically pins the Workbench HTTP parent origin', async () => {
   const target = harness();
   const client = createAppClient({ window: target.window });
@@ -270,14 +327,24 @@ it('uses an exact trusted targetOrigin from the first message and rejects a mism
     targetOrigin: 'file:///tmp/host.html',
     window: target.window,
   })).toThrow(/exact trusted http/u);
+  expect(() => createAppClient({
+    targetOrigin: codexOrigin,
+    window: target.window,
+  })).toThrow(/exact trusted http/u);
+  expect(() => createAppClient({
+    targetOrigin: '',
+    window: target.window,
+  })).toThrow(/exact trusted origin/u);
 });
 
-it('rejects a bootstrap response whose origin is not an exact supported web origin', async () => {
-  const target = harness();
-  const client = createAppClient({ window: target.window });
-  const connecting = client.connect();
-  target.emit({ id: 1, jsonrpc: '2.0', result: initializeResult }, 'file://');
-  await expect(connecting).rejects.toMatchObject({ code: 'invalid-message' });
+it('rejects an empty or wildcard dynamic bootstrap origin', async () => {
+  for (const origin of ['', '*']) {
+    const target = harness();
+    const client = createAppClient({ window: target.window });
+    const connecting = client.connect();
+    target.emit({ id: 1, jsonrpc: '2.0', result: initializeResult }, origin);
+    await expect(connecting).rejects.toMatchObject({ code: 'invalid-message' });
+  }
 });
 
 it('calls a route by its protocol tool name and returns structuredContent directly', async () => {
@@ -578,6 +645,25 @@ it('rejects old pending work on rebind and establishes a fresh exact-origin conn
   expect(second.posts.at(-1)?.targetOrigin).toBe(secondOrigin);
 });
 
+it('clears a custom origin pin and wildcard post target on rebind', async () => {
+  const first = harness();
+  const second = harness();
+  const client = createAppClient({ window: first.window });
+  await connect(client, first, codexOrigin);
+
+  const rebound = client.rebind({ window: second.window });
+  expect(second.posts[0]?.targetOrigin).toBe('*');
+  const reboundId = responseId(second.posts[0]!);
+  let settled = false;
+  void rebound.then(() => { settled = true; }, () => { settled = true; });
+  second.emit({ id: reboundId, jsonrpc: '2.0', result: initializeResult }, codexOrigin, first.parent);
+  await flushListeners();
+  expect(settled).toBe(false);
+  second.emit({ id: reboundId, jsonrpc: '2.0', result: initializeResult }, hostOrigin);
+  await expect(rebound).resolves.toEqual(initializeResult);
+  expect(second.posts.at(-1)?.targetOrigin).toBe(hostOrigin);
+});
+
 it('validates a rebind origin before changing the live connection', async () => {
   const target = harness();
   const client = createAppClient({ window: target.window });
@@ -691,3 +777,22 @@ it('acknowledges host teardown before disposing and makes disposal idempotent',
   await expect(client.connect()).rejects.toBeInstanceOf(AppClientError);
   await expect(client.connect()).rejects.toMatchObject({ code: 'disposed' });
 });
+
+it('uses the custom origin wildcard target before dispose clears both pins', async () => {
+  const target = harness();
+  const client = createAppClient({ window: target.window });
+  await connect(client, target, codexOrigin);
+
+  target.emit({
+    id: 'close-custom',
+    jsonrpc: '2.0',
+    method: 'ui/resource-teardown',
+    params: {},
+  }, codexOrigin);
+  expect(target.posts.at(-1)).toEqual({
+    message: { id: 'close-custom', jsonrpc: '2.0', result: {} },
+    targetOrigin: '*',
+  });
+  expect(client.disposed).toBe(true);
+  expect(client.connected).toBe(false);
+});
diff --git a/packages/agent-bundle/tests/public-api-packed.test.ts b/packages/agent-bundle/tests/public-api-packed.test.ts
index f5fb1f556..c7312b7ee 100644
--- a/packages/agent-bundle/tests/public-api-packed.test.ts
+++ b/packages/agent-bundle/tests/public-api-packed.test.ts
@@ -380,6 +380,44 @@ it('imports the externalized config entry from a packed npm consumer', async ()
   }
 }, 30_000);
 
+it('runs the packed App client through a Codex custom-scheme parent', async () => {
+  const { tarball } = await sharedPackedTarball('agent-bundle');
+  const consumerRoot = await mkdtemp(join(tmpdir(), 'agent-bundle-packed-app-client-'));
+  try {
+    await writeFile(join(consumerRoot, 'package.json'), '{"type":"module"}\n');
+    await execFile(
+      'npm', ['install', ...cachedNpmInstallArguments, tarball],
+      { cwd: consumerRoot, env: isolatedCommandEnvironment() },
+    );
+
+    const { stdout } = await execFile(process.execPath, [
+      '--input-type=module',
+      '--eval',
+      [
+        "import { APP_PROTOCOL_VERSION, createAppClient } from 'agent-bundle/app';",
+        'const listeners = new Set();',
+        'const posts = [];',
+        'const parent = { postMessage(message, targetOrigin) { posts.push({ message, targetOrigin }); } };',
+        "const appWindow = { parent, addEventListener(_type, listener) { listeners.add(listener); }, removeEventListener(_type, listener) { listeners.delete(listener); } };",
+        "const emit = (data) => { for (const listener of listeners) listener({ data, origin: 'codex-sandbox://packed-dashboard-id', source: parent }); };",
+        'const client = createAppClient({ window: appWindow });',
+        'const connecting = client.connect();',
+        'emit({ id: posts.at(-1).message.id, jsonrpc: \'2.0\', result: { hostCapabilities: { serverTools: {} }, hostContext: {}, hostInfo: { name: \'codex\', version: \'0.153.4\' }, protocolVersion: APP_PROTOCOL_VERSION } });',
+        'await connecting;',
+        "const called = client.call('tool:hauler/hauler_status', { limit: 40 });",
+        'emit({ id: posts.at(-1).message.id, jsonrpc: \'2.0\', result: { content: [{ text: \'healthy\', type: \'text\' }], structuredContent: { active: 0, status: \'healthy\' } } });',
+        'const result = await called;',
+        "if (!posts.every(({ targetOrigin }) => targetOrigin === '*')) throw new Error('custom-origin post target was not wildcard');",
+        'console.log(JSON.stringify(result));',
+      ].join('\n'),
+    ], { cwd: consumerRoot, env: isolatedCommandEnvironment() });
+
+    expect(JSON.parse(stdout)).toEqual({ active: 0, status: 'healthy' });
+  } finally {
+    await rm(consumerRoot, { force: true, recursive: true });
+  }
+}, 30_000);
+
 it('invokes a prebuilt MCP server from a clean packed consumer', async () => {
   const { tarball } = await sharedPackedTarball('agent-bundle');
 
diff --git a/website/docs/en/guide/authoring/mcp.mdx b/website/docs/en/guide/authoring/mcp.mdx
index 15c5f59b2..df952d42c 100644
--- a/website/docs/en/guide/authoring/mcp.mdx
+++ b/website/docs/en/guide/authoring/mcp.mdx
@@ -925,18 +925,20 @@ document cannot know its parent's origin up front. `connect()` therefore sends e
 to `'*'` — the framework-owned `ui/initialize` — and accepts a response only from the configured
 parent window (`event.source`), with that request's id and a valid initialize result (protocol
 version `2026-01-26`, `hostInfo`, `hostCapabilities`, `hostContext`). An exact `http:`/`https:`
-response origin is pinned for both inbound and outbound messages. An opaque `"null"` response
-origin from that same parent enters opaque mode: later inbound messages must still come from the
-same parent with origin `"null"`, and outbound messages use `'*'` because an opaque target cannot
-be addressed by origin. Empty and other-scheme origins fail the handshake with `invalid-message`;
-messages from another window or a changed origin are ignored. A host that can supply a trusted
-origin passes `targetOrigin` — an exact `http:`/`https:` origin; both `'*'` and `"null"` are
-rejected — and no wildcard frame is sent at all. `connect()` is idempotent: a connected client
-resolves the cached result, a connecting one returns the in-flight handshake.
+response origin is pinned raw for inbound messages. Exact `http:`/`https:` origins are also used
+as the outbound target. Opaque `"null"` and host-private origins such as Codex Desktop's
+`codex-sandbox://…` use `'*'` outbound because those targets cannot be addressed portably by
+origin; later inbound messages must still come from the same parent with the exact raw pinned
+origin. Empty and literal `'*'` origins fail the handshake with `invalid-message`; messages from
+another window or any origin change after pinning are ignored. A host that can supply a trusted
+origin passes `targetOrigin` — an exact `http:`/`https:` origin; `'*'`, `"null"`, and custom
+schemes are rejected — and no wildcard frame is sent at all. `connect()` is idempotent: a
+connected client resolves the cached result, a connecting one returns the in-flight handshake.
 `rebind({ parent?, targetOrigin?, window? })` rejects the previous generation's pending requests
 with `connection-rebound` — a `connect()` still in flight included, which never becomes the live
-connection — clears either origin mode, keeps the configured `targetOrigin` unless the call names
-one, and performs the handshake again against the new parent. `dispose()`, also idempotent,
+connection — clears both the incoming pin and outgoing target, keeps the configured `targetOrigin`
+unless the call names one, and performs the handshake again against the new parent. `dispose()`,
+also idempotent,
 removes the listener, rejects pending requests with `disposed`, and drops every registration; a
 host's `ui/resource-teardown` request is accepted only through the current source-and-origin pin,
 acknowledged, and then disposes the client. Cancellation and teardown replies use that same
diff --git a/website/docs/en/reference/security.mdx b/website/docs/en/reference/security.mdx
index 49f39d042..8a7bd8695 100644
--- a/website/docs/en/reference/security.mdx
+++ b/website/docs/en/reference/security.mdx
@@ -65,14 +65,16 @@ The Workbench and `serve-app` use a separate loopback HTTP sandbox proxy, while
 Codex can provide an opaque parent, so the document cannot know its parent's origin before the
 first frame. Each `connect()` handshake attempt sends one framework-owned `ui/initialize` request
 to `'*'` and accepts a response only from the configured parent window with that request's id and
-a valid initialize result. An exact `http:`/`https:` response origin is pinned for inbound and
-outbound traffic. An opaque `"null"` response from that same parent instead pins opaque mode:
-later inbound messages must keep the same source and `"null"` origin, while outbound messages use
-`'*'` because opaque targets cannot be addressed by origin. Empty and other-scheme origins fail
-the handshake. A host that can name its origin passes `targetOrigin` (an exact `http:`/`https:`
-origin; both `'*'` and `"null"` are rejected) and no wildcard frame is sent. `rebind()` and
-`dispose()` revoke either pin and reject every request still pending, a handshake still in flight
-included, so a stale generation cannot receive a later host's messages.
+a valid initialize result. The raw nonempty response origin is pinned for inbound traffic.
+An exact `http:`/`https:` origin is also used as the outbound target. Opaque `"null"` and
+host-private origins such as Codex Desktop's `codex-sandbox://…` instead use `'*'` outbound,
+because those targets cannot be addressed portably by origin; later inbound messages must still
+keep both the same source and exact raw pinned origin. Empty and literal `'*'` origins fail the
+handshake, and an origin cannot change after pinning. A host that can name its origin passes
+`targetOrigin` (an exact `http:`/`https:` origin; `'*'`, `"null"`, and custom schemes are rejected)
+and no wildcard frame is sent. `rebind()` and `dispose()` revoke both the incoming pin and
+outgoing target and reject every request still pending, a handshake still in flight included, so
+a stale generation cannot receive a later host's messages.
 
 The host relay is the security boundary. The App client speaks only to its expected parent; the
 Workbench, `serve-app`, or an embedding MCP host forwards permitted requests to the one server the
diff --git a/website/docs/zh/guide/authoring/mcp.mdx b/website/docs/zh/guide/authoring/mcp.mdx
index bfef983f2..87c8326e7 100644
--- a/website/docs/zh/guide/authoring/mcp.mdx
+++ b/website/docs/zh/guide/authoring/mcp.mdx
@@ -807,14 +807,15 @@ JSON-RPC result。两者都会在尚未 `connect()` 时先连接；每个请求
 之后，而 Codex 可以把它渲染在 opaque sandbox 中；两种情况下文档都无法事先知道 parent origin。
 `connect()` 只向 `'*'` 发送一帧——框架拥有的 `ui/initialize`——并且只接受 configured parent window
 （`event.source`）以同一 request id 返回的有效 initialize result（协议版本 `2026-01-26`，以及
-`hostInfo`、`hostCapabilities`、`hostContext`）。响应若带精确的 `http:` / `https:` origin，客户端就
-把它同时固定为入站与出站 origin。若同一个 parent 返回 opaque `"null"` origin，客户端则进入 opaque
-模式：之后的入站消息仍须来自同一个 parent 且 origin 为 `"null"`；出站消息使用 `'*'`，因为浏览器无法按
-origin 寻址 opaque target。空 origin 与其他 scheme 会以 `invalid-message` 令握手失败；其他 window
-或发生变化的 origin 所发消息会被忽略。能预先给出可信 origin 的宿主可传入精确的 `http:` / `https:`
-`targetOrigin`；`'*'` 与 `"null"` 都会被拒绝，且不会有任何 wildcard frame。`connect()` 幂等。
+`hostInfo`、`hostCapabilities`、`hostContext`）。客户端会把非空的原始响应 origin 固定用于入站消息；
+精确的 `http:` / `https:` origin 也会作为出站 target。opaque `"null"` 与 Codex Desktop 的
+`codex-sandbox://…` 等宿主私有 origin 使用 `'*'` 出站，因为浏览器无法可靠地按 origin 寻址这些
+target；之后的入站消息仍须来自同一个 parent 且带完全相同的原始 origin。空 origin 与字面值 `'*'` 会以
+`invalid-message` 令握手失败；其他 window 或固定后发生变化的 origin 所发消息会被忽略。能预先给出
+可信 origin 的宿主可传入精确的 `http:` / `https:` `targetOrigin`；`'*'`、`"null"` 与自定义 scheme
+都会被拒绝，且不会有任何 wildcard frame。`connect()` 幂等。
 `rebind({ parent?, targetOrigin?, window? })` 以 `connection-rebound` 拒绝旧 generation 的 pending
-request、清除任一种 origin 模式，再对新 parent 握手。`dispose()` 同样幂等：移除 listener，以
+request、清除入站 pin 与出站 target，再对新 parent 握手。`dispose()` 同样幂等：移除 listener，以
 `disposed` 拒绝 pending request，并丢弃所有注册；只有通过当前 source 与 origin pin 的
 `ui/resource-teardown` request 才会先得到确认，再 dispose 客户端。取消与 teardown 回复会在连接状态
 清除之前沿当前 parent 及出站模式发送。可注入的 `window` 与 `parent` 让测试及非 DOM 宿主能驱动同一个客户端。
diff --git a/website/docs/zh/reference/security.mdx b/website/docs/zh/reference/security.mdx
index 259239643..1d142c890 100644
--- a/website/docs/zh/reference/security.mdx
+++ b/website/docs/zh/reference/security.mdx
@@ -53,12 +53,13 @@ App 文档内的 `agent-bundle/app` 客户端也不会信任任意 `postMessage`
 `serve-app` 使用独立的 loopback HTTP sandbox proxy，而 Codex 等宿主可以提供 opaque parent，因此文档
 在第一帧前不知道 parent origin。每次 `connect()` 握手尝试只向 `'*'` 发送一条框架拥有的
 `ui/initialize` request，并且只接受 configured parent window 以该 request id 返回的有效 initialize
-result。精确的 `http:` / `https:` 响应 origin 会同时固定入站与出站流量。若同一个 parent 返回 opaque
-`"null"` origin，客户端则固定 opaque 模式：之后的入站消息必须保持同一个 source 和 `"null"` origin，
-而出站消息使用 `'*'`，因为浏览器无法按 origin 寻址 opaque target。空 origin 与其他 scheme 会使握手
-失败。能给出宿主 origin 的调用方传入精确的 `http:` / `https:` `targetOrigin`；`'*'` 与 `"null"` 都会
-被拒绝，且不会发送任何 wildcard frame。`rebind()` 与 `dispose()` 都撤销任一种 pin 并拒绝所有 pending
-request，旧 generation 因此不可能收到后续宿主的消息。
+result。客户端会把非空的原始响应 origin 固定用于入站流量；精确的 `http:` / `https:` origin 也会作为
+出站 target。opaque `"null"` 与 Codex Desktop 的 `codex-sandbox://…` 等宿主私有 origin 则使用
+`'*'` 出站，因为浏览器无法可靠地按 origin 寻址这些 target；之后的入站消息仍必须同时保持同一个 source
+与完全相同的原始 origin。空 origin 与字面值 `'*'` 会使握手失败，固定后 origin 也不能发生变化。能给出
+宿主 origin 的调用方传入精确的 `http:` / `https:` `targetOrigin`；`'*'`、`"null"` 与自定义 scheme
+都会被拒绝，且不会发送任何 wildcard frame。`rebind()` 与 `dispose()` 都撤销入站 pin 与出站 target，
+并拒绝所有 pending request，旧 generation 因此不可能收到后续宿主的消息。
 
 这条桥接以宿主 relay 为安全边界：App 客户端只与预期 parent 通信；Workbench、`serve-app` 或嵌入式 MCP
 宿主负责把允许的请求转发到所绑定的那一个服务器，并继续执行各自的认证、能力与同意策略。App 不会绕过

From f4d345a4ea1ecefc8ef6201b75ae90d033f02464 Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Wed, 9 Sep 2026 08:31:22 +0000
Subject: [PATCH 2/2] docs(changeset): reference PR 772

---
 .changeset/pin-codex-sandbox-origin.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/pin-codex-sandbox-origin.md b/.changeset/pin-codex-sandbox-origin.md
index 1e432101b..4c4781e5b 100644
--- a/.changeset/pin-codex-sandbox-origin.md
+++ b/.changeset/pin-codex-sandbox-origin.md
@@ -2,4 +2,4 @@
 "agent-bundle": patch
 ---
 
-Allow `createAppClient()` to pin Codex Desktop `codex-sandbox://` response origins while keeping configured `targetOrigin` HTTP(S)-only (#PR)
+Allow `createAppClient()` to pin Codex Desktop `codex-sandbox://` response origins while keeping configured `targetOrigin` HTTP(S)-only (#772)