feat(agents): add opt-in plaintext V2 collaboration messages

docs-site/src/content/docs/guides/sub-agent-surface.md

@@ -138,6 +138,16 @@ Recovery options are to select a native ChatGPT child, add a native ChatGPT targ
 v1 for heterogeneous-provider delegation, or resend the task as plaintext v2 `agent_message`
 content when you control the caller.
 
+The experimental `plaintextV2AgentMessages: true` option attempts to prevent application-layer
+encryption for eligible new native ChatGPT v2 tool calls. It assigns request-scoped aliases to the
+namespace and three reserved message-tool names, removes the message marker, and restores the
+original identities in the response. It handles
+`spawn_agent`, `send_message`, and `followup_task` and adds no recovery request. HTTPS remains
+encrypted, but task text can be retained in Codex history, routed-provider requests, and local
+response/debug state. Existing ciphertext is unchanged, and the option depends on undocumented
+ChatGPT and Codex behavior. See
+[Agent configuration: Plaintext v2 agent messages](/reference/configuration/agents/#plaintext-v2-agent-messages).
+
 An experimental, disabled-by-default `agentTaskRecovery` option can recover this specific native-
 to-routed shape through a raw Responses passthrough to the fixed ChatGPT `/responses` endpoint using
 the incoming credential shape used by the canonical `openai` provider with `authMode: "forward"`.

docs-site/src/content/docs/reference/configuration/agents.md

@@ -23,6 +23,7 @@ routes, and limits delegated work.
 | `subagentModelFallbackPollMs?` | `number` | `60000` | Availability-probe cache interval. Values below 1000 ms fall back to the default. |
 | `effortCap?` | `string` | — | Hard ceiling for qualifying v2 main turns and marked spawned-child turns. Accepts `low` through `ultra`. |
 | `subagentEffortCap?` | `string` | — | Additional ceiling for spawned-child turns only. When both caps apply, the lower wins. |
+| `plaintextV2AgentMessages?` | `boolean` | `false` | Experimental opt-in that asks native ChatGPT v2 parents to emit `spawn_agent`, `send_message`, and `followup_task` message arguments as plaintext. See [Plaintext v2 agent messages](#plaintext-v2-agent-messages). |
 | `agentTaskRecovery?` | `object` | — | Experimental opt-in recovery for backend-encrypted v2 tasks sent to routed providers. Disabled unless `enabled: true`; see [Encrypted v2 task recovery](#encrypted-v2-task-recovery). |
 
 Manage the surface with the dashboard or
@@ -120,6 +121,42 @@ fails instead of routing unreadable ciphertext elsewhere.
 }
 ```
 
+## Plaintext v2 agent messages
+
+`plaintextV2AgentMessages` is an experimental, disabled-by-default alternative to post-encryption
+recovery. On a v2 Responses request whose final destination is the canonical ChatGPT backend,
+opencodex recognizes the v2 catalog by a top-level `collaboration` namespace with a direct
+`spawn_agent` child. It removes `parameters.properties.message.encrypted: true`, when present, only
+from `spawn_agent`, `send_message`, and `followup_task`. ChatGPT reserves both the `collaboration`
+namespace and those three tool names, so the request uses fixed private aliases for all four
+identities. OpenCodex restores the original namespace and tool names in JSON, SSE, and WebSocket
+responses before Codex receives the tool call. The `encrypted_function_args: []` field is preserved
+so compatible Codex clients recognize the message as plaintext.
+
+This path adds no recovery request and therefore does not spend the extra ChatGPT quota used by a
+cache miss in `agentTaskRecovery`. It cannot change tasks that are already encrypted. If the request
+already declares the private alias or a conflicting reference, opencodex leaves that request
+unchanged; separately enabled recovery can still handle a routed task that is later encrypted. If
+ChatGPT rejects or ignores the modified schema, or the Codex client does not recognize the plaintext
+response fields, the call can fail. OpenCodex does not retry the parent request with the original
+schema because doing so could duplicate quota use or tool calls.
+
+For successfully rewritten calls, the option removes application-layer encryption from agent
+message arguments. HTTPS still encrypts network transport, but message text can appear in Codex
+task history, routed-provider requests, `responses-state.json` or its spill files, and
+`usage-debug.jsonl` when debug capture is enabled. The behavior depends on undocumented ChatGPT
+schema and response fields and may stop working after a backend or client update. Startup prints a
+warning while it is enabled.
+
+```json
+{
+  "plaintextV2AgentMessages": true
+}
+```
+
+The equivalent CLI command is `ocx config set plaintextV2AgentMessages true`. Restart the proxy
+after changing the setting.
+
 ## Encrypted v2 task recovery
 
 `agentTaskRecovery` is an experimental compatibility path for a native ChatGPT parent spawning a

docs-site/src/content/docs/zh-cn/guides/sub-agent-surface.md

@@ -86,6 +86,13 @@ opencodex 会安全失败，而不是转发空任务或不可读任务：
 
 恢复选项是选择原生 ChatGPT 子级、在 combo 中添加原生 ChatGPT 目标、在异构 provider 委派中使用 v1，或者在你控制调用方时将任务作为明文 v2 `agent_message` 内容重新发送。
 
+实验性的 `plaintextV2AgentMessages: true` 会尝试取消符合条件的新原生 ChatGPT v2 工具调用的
+应用层加密。它临时改写 namespace 和三个保留工具名，并删除消息字段的加密标记；响应返回 Codex
+前会恢复原 namespace 与工具名。它处理 `spawn_agent`、`send_message` 和 `followup_task`，不会增加恢复请求。
+HTTPS 仍会加密网络传输，但任务文字可能保存在 Codex 历史、外部模型请求和本地响应或调试文件中。
+已有密文不会改变。该选项依赖 ChatGPT 和 Codex 未公开的行为。详见
+[明文 v2 代理消息](/zh-cn/reference/configuration/agents/#明文-v2-代理消息)。
+
 实验性的 `agentTaskRecovery` 默认关闭。显式启用后，它可以通过向固定 ChatGPT 端点发送额外的认证请求来恢复这种格式，但会消耗配额、增加延迟，并依赖非公开的后端行为。任何失败都会保留原有的 `unreadable_encrypted_agent_task` 错误。详见[英文配置参考](/reference/configuration/agents/#encrypted-v2-task-recovery)。
 
 ## 更改模式

docs-site/src/content/docs/zh-cn/reference/configuration/agents.md

@@ -21,6 +21,7 @@ description: 多代理界面、委派引导、首选模型、回退链、原生
 | `subagentModelFallbackPollMs?` | `number` | `60000` | 可用性探测缓存间隔。低于 1000 ms 的值会回退到默认值。 |
 | `effortCap?` | `string` | — | 对符合条件的 v2 主轮次和标记的派生子轮次设置硬上限。接受 `low` 到 `ultra`。 |
 | `subagentEffortCap?` | `string` | — | 仅针对派生子轮次的额外上限。两个上限同时适用时，较低者生效。 |
+| `plaintextV2AgentMessages?` | `boolean` | `false` | 实验性选项。启用后，opencodex 会尝试让符合条件的新 `spawn_agent`、`send_message` 和 `followup_task` 调用使用明文消息参数。详见[明文 v2 代理消息](#明文-v2-代理消息)。 |
 
 通过仪表板或 `ocx v2 status|on|off|mode <v1|default|v2>|threads <n>` 管理该界面。模式变更会应用于新会话。`maxConcurrentThreadsPerSession` 是 `PUT /api/v2` 字段，不是 `config.json` 键；`ocx v2 threads <n>` 会在启用 v2 后，将 `max_concurrent_threads_per_session` 写入 Codex 的 `$CODEX_HOME/config.toml` 中的 `[features.multi_agent_v2]` 下。
 
@@ -70,6 +71,31 @@ opencodex 会跳过已禁用、不可路由、不健康、处于冷却中，或
 }
 ```
 
+## 明文 v2 代理消息
+
+`plaintextV2AgentMessages` 默认关闭。opencodex 只识别顶层 `collaboration` namespace，而且它必须直接包含
+`spawn_agent`。原生 ChatGPT 收到这类 v2 Responses 请求前，opencodex 会删除 `spawn_agent`、
+`send_message` 和 `followup_task` 中已有的 `parameters.properties.message.encrypted: true`。
+ChatGPT 会按保留的 `collaboration` namespace 和三个工具名处理消息，因此请求会给这四个名称使用固定的
+临时别名。opencodex 在 JSON、SSE 和 WebSocket 响应中恢复原名称，并保留
+`encrypted_function_args: []`，让兼容的 Codex 客户端把参数识别为明文。
+
+这个选项不会增加恢复请求，也不会使用 `agentTaskRecovery` 在缓存未命中时产生的额外 ChatGPT
+配额。它只能影响新工具调用，不能修改已有密文。请求已占用私有名称或有冲突引用时，opencodex 会保持该请求不变；若它后来生成加密的路由子任务，单独启用的 `agentTaskRecovery` 仍可处理。ChatGPT 拒绝或忽略修改后的 schema，或 Codex 客户端不识别明文响应字段时，调用可能失败。opencodex 不会用原 schema 自动重发父请求，因为重发可能重复消耗配额或重复执行工具。
+
+成功改写后，这个选项会取消代理消息参数的应用层加密。HTTPS 仍会加密网络传输，但消息文字可能出现在 Codex
+任务历史、外部模型请求、`responses-state.json` 及其 spill 文件，以及启用调试记录时的
+`usage-debug.jsonl`。该行为依赖 ChatGPT 未公开的 schema 和响应字段，后端或客户端更新后可能失效。
+服务启动时会打印警告。
+
+```json
+{
+  "plaintextV2AgentMessages": true
+}
+```
+
+等价命令是 `ocx config set plaintextV2AgentMessages true`。修改后重启代理。
+
 ## Effort 上限
 
 上限只适用于 v2 协作功能：当主轮次的工具暴露 v2 时，它就符合条件；当子轮次在 `x-codex-turn-metadata` 中带有 codex-rs 的精确 `x-openai-subagent: collab_spawn` 或 `"subagent_kind": "thread_spawn"` 标记时，它也符合条件，即使叶子工具已经不再暴露协作。V1 主轮次、`multiAgentMode: "v1"`、压缩、审查以及记忆整合轮次都会绕过上限。

src/adapters/base.ts

@@ -76,6 +76,8 @@ export interface AdapterRequest {
     convertedRoutedToolSearchNames?: ReadonlySet<string>;
     /** Upstream-only aliases for namespace tools flattened in this request. */
     convertedRoutedNamespaceToolAliases?: ReadonlyMap<string, { namespace: string; name: string; kind: "function" | "custom" }>;
+    /** Request-declared collaboration child names eligible for plaintext-v2 alias restoration. */
+    plaintextV2AgentMessageToolNames?: ReadonlySet<string>;
     /** Releases observation of a serialized request body after its final fetch attempt settles. */
     releaseBodyObservation?: () => void;
     /** Exact reasoning parameter emitted by the adapter, for request-log diagnostics only. */

src/adapters/openai-responses.ts

@@ -18,6 +18,7 @@ import type { TranslatorBudget } from "../lib/translator-budget";
 import { rewriteRoutedCustomToolsForUpstream } from "../responses/custom-tool-compat";
 import { rewriteRoutedToolSearchForUpstream } from "../responses/tool-search-compat";
 import { rewriteRoutedNamespaceToolsForUpstream } from "../responses/namespace-tool-compat";
+import { preparePlaintextV2AgentMessages } from "../responses/plaintext-v2-agent-messages";
 import { openaiResponsesUrl } from "./openai-responses-url";
 import { normalizeXaiResponsesWebSearch } from "./xai-web-search";
 import {
@@ -1767,6 +1768,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       let routedCustomToolRepairNames: Set<string> | undefined;
       let convertedRoutedToolSearchNames: Set<string> | undefined;
       let convertedRoutedNamespaceToolAliases: Map<string, { namespace: string; name: string; kind: "function" | "custom" }> | undefined;
+      let plaintextV2AgentMessageToolNames: ReadonlySet<string> | undefined;
       const unexpandedMiss = !!parsed.previousResponseId && parsed._previousResponseInputExpanded !== true;
       let outBody = stripPreviousResponseId(
         parsed._rawBody,
@@ -1858,6 +1860,16 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       if (parsed._compactionRequest === true && !isCanonicalOpenAiForwardProvider(provider)) {
         outBody = buildRoutedCompactionBody(outBody);
       }
+      if (
+        parsed._plaintextV2AgentMessages === true
+        && isCanonicalOpenAiForwardProvider(provider)
+      ) {
+        const prepared = preparePlaintextV2AgentMessages(outBody);
+        outBody = prepared.body;
+        plaintextV2AgentMessageToolNames = prepared.namespaceAliased
+          ? prepared.toolNames
+          : undefined;
+      }
       const threadServingIdentityChanged = parsed._stripReasoningEncryptedContent === true;
       const sanitizedBody = normalizeToolSchemas(stripSparkCompatibility(stripUnsupportedReasoningParams(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(
         outBody,
@@ -1901,6 +1913,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         ...(routedCustomToolRepairNames ? { routedCustomToolRepairNames } : {}),
         ...(convertedRoutedToolSearchNames ? { convertedRoutedToolSearchNames } : {}),
         ...(convertedRoutedNamespaceToolAliases ? { convertedRoutedNamespaceToolAliases } : {}),
+        ...(plaintextV2AgentMessageToolNames ? { plaintextV2AgentMessageToolNames } : {}),
         ...(tierLog ? { tierLog } : {}),
       };
     },

src/config.ts

@@ -894,6 +894,8 @@ const configSchema = z.object({
   providerContextCaps: z.record(z.string(), z.number().int().positive()).optional(),
   contextCapValue: z.number().int().positive().optional(),
   multiAgentGuidanceEnabled: z.boolean().optional(),
+  // Invalid hand edits disable only this experimental plaintext path.
+  plaintextV2AgentMessages: z.boolean().optional().catch(undefined),
   // Invalid optional recovery config must not discard unrelated provider/account state.
   agentTaskRecovery: agentTaskRecoverySchema.optional().catch(undefined),
   // These selections pre-date schema validation and used to pass through as
@@ -1677,6 +1679,19 @@ function warnDegradedAgentTaskRecovery(rawParsed: unknown): void {
   if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
 }
 
+function malformedPlaintextV2AgentMessagesWarning(rawParsed: unknown): string | null {
+  const raw = rawConfigRecord(rawParsed);
+  if (!raw || !Object.hasOwn(raw, "plaintextV2AgentMessages")) return null;
+  const enabled = raw.plaintextV2AgentMessages;
+  if (enabled === undefined || typeof enabled === "boolean") return null;
+  return "plaintextV2AgentMessages ignored: expected a boolean";
+}
+
+function warnDegradedPlaintextV2AgentMessages(rawParsed: unknown): void {
+  const warning = malformedPlaintextV2AgentMessagesWarning(rawParsed);
+  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
+}
+
 type NativeSubagentPersistedField = "injectionModel" | "injectionEffort" | "syncCodexSubagentDefaults";
 
 function rawConfigRecord(rawParsed: unknown): Record<string, unknown> | null {
@@ -1829,6 +1844,7 @@ export function loadConfig(): OcxConfig {
       warnDegradedNativeSubagentConfig(parsed, config);
       warnDegradedCodexAccountPicker(parsed);
       warnDegradedUpstreamHostCircuitThreshold(parsed);
+      warnDegradedPlaintextV2AgentMessages(parsed);
       warnDegradedAgentTaskRecovery(parsed);
       return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
     }
@@ -1853,6 +1869,7 @@ export function loadConfig(): OcxConfig {
       warnDegradedNativeSubagentConfig(parsed, config);
       warnDegradedCodexAccountPicker(parsed);
       warnDegradedUpstreamHostCircuitThreshold(parsed);
+      warnDegradedPlaintextV2AgentMessages(parsed);
       warnDegradedAgentTaskRecovery(parsed);
       return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
     }
@@ -1873,6 +1890,7 @@ export function loadConfig(): OcxConfig {
         warnDegradedNativeSubagentConfig(parsed, config);
         warnDegradedCodexAccountPicker(parsed);
         warnDegradedUpstreamHostCircuitThreshold(parsed);
+        warnDegradedPlaintextV2AgentMessages(parsed);
         warnDegradedAgentTaskRecovery(parsed);
         return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
       }
@@ -1974,6 +1992,8 @@ function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): Conf
   if (hostCircuitWarning) warnings.push(hostCircuitWarning);
   const recoveryWarning = malformedAgentTaskRecoveryWarning(rawParsed);
   if (recoveryWarning) warnings.push(recoveryWarning);
+  const plaintextMessagesWarning = malformedPlaintextV2AgentMessagesWarning(rawParsed);
+  if (plaintextMessagesWarning) warnings.push(plaintextMessagesWarning);
   if (syncDisabledReason) {
     warnings.push(`syncCodexSubagentDefaults ignored: ${syncDisabledReason}`);
   }
@@ -2065,6 +2085,14 @@ function agentTaskRecoveryError(value: unknown): string | null {
   return `schema_invalid: agentTaskRecovery${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`;
 }
 
+function plaintextV2AgentMessagesError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "plaintextV2AgentMessages")) return null;
+  const enabled = raw.plaintextV2AgentMessages;
+  if (enabled === undefined || typeof enabled === "boolean") return null;
+  return "schema_invalid: plaintextV2AgentMessages: must be a boolean or omitted";
+}
+
 /**
  * Same reasoning as {@link blankHostnameError}, and more urgent: the read path degrades a
  * malformed selection-order map to undefined, which on a write would drop every entry the
@@ -2176,6 +2204,7 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
     ?? claudeSubagentEffortError(value)
     ?? appOwnedMemoryBudgetError(value)
     ?? upstreamHostCircuitThresholdError(value)
+    ?? plaintextV2AgentMessagesError(value)
     ?? agentTaskRecoveryError(value)
     ?? googleAntigravityStaticCatalogVersionError(value)
     ?? codexAccountPrioritiesError(value)