Skip to content

Commit 87af85f

Browse files
committed
docs(v2): explain encrypted agent task routing
1 parent 733cec4 commit 87af85f

2 files changed

Lines changed: 26 additions & 6 deletions

File tree

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

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: Control how Codex spawns and manages sub-agents across all models.
66
opencodex lets you choose the multi-agent collaboration surface for every model in the catalog. The **Sub-agent** toggle in the dashboard and Models page controls this globally.
77

88
:::note
9-
On the v2 surface (`multi_agent_v2`), a spawned sub-agent inherits the parent model **by default**: `fork_turns` defaults to `all`, and full-history forks reject overrides. Since v2.7.2 opencodex injects guidance that teaches the model how to break inheritance — a `spawn_agent` call that sets `fork_turns` to `"none"` (or a partial fork such as `"3"`) can pass `model` / `reasoning_effort` arguments, which the Codex runtime parses and applies even though the published tool schema hides them. Known limitation: when a **native** parent spawns a child routed to a **non-native** provider, the Codex client may send the `NEW_TASK` payload only as backend-encrypted `encrypted_content`, so the routed child receives an empty task body ([#92](https://github.com/lidge-jun/opencodex/issues/92)). The model override still applies, but the task text can be lost — the v1 surface remains the reliable choice for heterogeneous-provider delegation.
9+
On the v2 surface (`multi_agent_v2`), a spawned sub-agent inherits the parent model **by default**: `fork_turns` defaults to `all`, and full-history forks reject overrides. Since v2.7.2 opencodex injects guidance that teaches the model how to break inheritance — a `spawn_agent` call that sets `fork_turns` to `"none"` (or a partial fork such as `"3"`) can pass `model` / `reasoning_effort` arguments, which the Codex runtime parses and applies even though the published tool schema hides them. Known transport limitation: when a **native** parent spawns a child routed to a **non-native** provider, the Codex client may send the `NEW_TASK` payload only as backend-encrypted `encrypted_content` ([#92](https://github.com/lidge-jun/opencodex/issues/92)). opencodex does not forward that unreadable task to an external provider: a direct route fails with HTTP 400 and code `unreadable_encrypted_agent_task`, while a combo skips non-decrypting targets and selects a canonical native ChatGPT target when one is available. Use v1 for heterogeneous-provider delegation, select a native ChatGPT child, or resend the task as plaintext v2 `agent_message` content.
1010
:::
1111

1212
## Modes
@@ -15,7 +15,17 @@ On the v2 surface (`multi_agent_v2`), a spawned sub-agent inherits the parent mo
1515
| --- | --- | --- |
1616
| **v1** | `multi_agent_v1` | Classic namespaced agent tools with `send_input` / `close_agent` / `resume_agent`. A `spawn_agent` model override can start a sub-agent on a different model. |
1717
| **base** (default) | Upstream pins | Restores upstream model pins: gpt-5.6-sol and gpt-5.6-terra use v2, gpt-5.6-luna uses v1, and unpinned models follow the Codex `multi_agent_v2` feature flag. Spawn behavior follows the surface that resolves for that model. |
18-
| **v2** | `multi_agent_v2` | Flat `spawn_agent` tools with concurrent sessions and `send_message` / `followup_task` / `wait_agent` / `interrupt_agent`. Children inherit the parent model on full-history forks; `fork_turns: "none"` (or a partial fork) accepts `model` / `reasoning_effort` overrides. Task body may arrive encrypted for native→routed children ([#92](https://github.com/lidge-jun/opencodex/issues/92)). |
18+
| **v2** | `multi_agent_v2` | Flat `spawn_agent` tools with concurrent sessions and `send_message` / `followup_task` / `wait_agent` / `interrupt_agent`. Children inherit the parent model on full-history forks; `fork_turns: "none"` (or a partial fork) accepts `model` / `reasoning_effort` overrides. If a native→routed child receives only backend-encrypted task content, external routes return `unreadable_encrypted_agent_task`; mixed combos prefer a decrypt-capable native target ([#92](https://github.com/lidge-jun/opencodex/issues/92)). |
19+
20+
### Encrypted v2 task delivery
21+
22+
Only the native ChatGPT backend can read its encrypted task payload. For an unreadable v2 `agent_message`, opencodex applies these rules before provider dispatch:
23+
24+
- A direct non-native route returns HTTP 400 with `error.code = "unreadable_encrypted_agent_task"`. The response never echoes the encrypted payload.
25+
- A combo considers only canonical native ChatGPT targets for that task, including retries. If the combo has no decrypt-capable target, it returns the same 400 response instead of sending an empty task to an external provider.
26+
- Readable plaintext tasks keep the normal combo order and failover behavior.
27+
28+
To recover, switch the child to a native ChatGPT model, add a native target to the combo, use the v1 surface for heterogeneous-provider delegation, or resend the task as plaintext v2 `agent_message` content when you control the caller.
1929

2030
## How it works
2131

@@ -46,7 +56,7 @@ To replace the built-in v2 guidance, set `injectionPrompt` (config key, or `PUT
4656
- **Dashboard** → first stat cell: click **v1**, **base**, or **v2**.
4757
- **Models** page → top-row segmented control.
4858
- Both pages have a **?** button that opens a help modal with a link back here.
49-
- **Dashboard** → **Sub-agent delegation**: choose a preferred model and optional reasoning effort. On v2 the injected guidance instructs the agent to spawn with `fork_turns: "none"` so the model override applies — though for native→routed children the task body can currently arrive encrypted ([#92](https://github.com/lidge-jun/opencodex/issues/92)).
59+
- **Dashboard** → **Sub-agent delegation**: choose a preferred model and optional reasoning effort. On v2 the injected guidance instructs the agent to spawn with `fork_turns: "none"` so the model override applies. If a native→routed child receives only encrypted task content, use a native target or v1; external-only delivery now fails explicitly with `unreadable_encrypted_agent_task` ([#92](https://github.com/lidge-jun/opencodex/issues/92)).
5060

5161
### CLI
5262

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

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: 全局控制 Codex 在所有模型上生成和管理子代理的方
66
opencodex 允许你为目录中的所有模型选择多代理协作界面。仪表盘和 Models 页面中的 **Sub-agent** 开关会全局控制这一设置。
77

88
:::note
9-
在 v2 界面(`multi_agent_v2`)上,子代理**默认**继承父会话的模型:`fork_turns` 默认为 `all`,而全量历史 fork 会拒绝覆盖。自 v2.7.2 起,opencodex 注入的指引会教模型如何打破继承 —— 将 `fork_turns` 设为 `"none"`(或如 `"3"` 的部分 fork)的 `spawn_agent` 调用可以传入 `model` / `reasoning_effort` 参数;即使公开的工具 schema 中看不到这些参数,Codex 运行时也会解析并应用。已知限制:当**原生**父代理 spawn 一个路由到**非原生** provider 的子代理时,Codex 客户端可能只以后端加密的 `encrypted_content` 发送 `NEW_TASK` 载荷,路由子代理会收到空的任务正文([#92](https://github.com/lidge-jun/opencodex/issues/92))。模型覆盖仍会生效,但任务文本可能丢失 —— 异构 provider 委派请使用更可靠的 v1 界面。
9+
在 v2 界面(`multi_agent_v2`)上,子代理**默认**继承父会话的模型:`fork_turns` 默认为 `all`,而全量历史 fork 会拒绝覆盖。自 v2.7.2 起,opencodex 注入的指引会教模型如何打破继承 —— 将 `fork_turns` 设为 `"none"`(或如 `"3"` 的部分 fork)的 `spawn_agent` 调用可以传入 `model` / `reasoning_effort` 参数;即使公开的工具 schema 中看不到这些参数,Codex 运行时也会解析并应用。已知传输限制:当**原生**父代理 spawn 一个路由到**非原生** provider 的子代理时,Codex 客户端可能只以后端加密的 `encrypted_content` 发送 `NEW_TASK` 载荷([#92](https://github.com/lidge-jun/opencodex/issues/92))。opencodex 不会把这种无法读取的任务转发给外部 provider:直接路由会返回 HTTP 400 和错误码 `unreadable_encrypted_agent_task`;组合路由则会跳过无法解密的目标,并在存在可用目标时选择规范的原生 ChatGPT 目标。恢复方法:异构 provider 委派改用 v1、选择原生 ChatGPT 子代理,或将任务重新作为明文 v2 `agent_message` 内容发送。
1010
:::
1111

1212
## 模式
@@ -15,7 +15,17 @@ opencodex 允许你为目录中的所有模型选择多代理协作界面。仪
1515
| --- | --- | --- |
1616
| **v1** | `multi_agent_v1` | 使用经典的命名空间代理工具,以及 `send_input` / `close_agent` / `resume_agent`。`spawn_agent` 的模型覆盖可以在其他模型上生成子代理。 |
1717
| **base**(默认) | 上游固定值 | 恢复上游模型的固定值:gpt-5.6-sol 和 gpt-5.6-terra 使用 v2,gpt-5.6-luna 使用 v1;未固定的模型遵循 Codex 的 `multi_agent_v2` 功能开关。生成行为取决于该模型最终使用的界面。 |
18-
| **v2** | `multi_agent_v2` | 使用扁平的 `spawn_agent` 工具、并发会话,以及 `send_message` / `followup_task` / `wait_agent` / `interrupt_agent`。全量历史 fork 时子代理继承父模型;`fork_turns: "none"`(或部分 fork)时接受 `model` / `reasoning_effort` 覆盖。原生→路由子代理的任务正文可能以加密形式到达([#92](https://github.com/lidge-jun/opencodex/issues/92))。 |
18+
| **v2** | `multi_agent_v2` | 使用扁平的 `spawn_agent` 工具、并发会话,以及 `send_message` / `followup_task` / `wait_agent` / `interrupt_agent`。全量历史 fork 时子代理继承父模型;`fork_turns: "none"`(或部分 fork)时接受 `model` / `reasoning_effort` 覆盖。如果原生→路由子代理只收到后端加密的任务内容,外部路由会返回 `unreadable_encrypted_agent_task`;混合组合会优先选择可解密的原生目标([#92](https://github.com/lidge-jun/opencodex/issues/92))。 |
19+
20+
### 加密的 v2 任务传输
21+
22+
只有原生 ChatGPT 后端能够读取其加密任务载荷。对于无法读取的 v2 `agent_message`,opencodex 会在调用 provider 之前执行以下规则:
23+
24+
- 直接路由到非原生 provider 时,返回 HTTP 400,并设置 `error.code = "unreadable_encrypted_agent_task"`。响应不会回显加密载荷。
25+
- 组合路由只会为该任务考虑规范的原生 ChatGPT 目标,重试时也遵守同一规则。如果组合中没有可解密的目标,则返回同样的 400,而不会把空任务发送给外部 provider。
26+
- 可读取的明文任务仍保留正常的组合顺序与故障转移行为。
27+
28+
恢复方法:将子代理切换到原生 ChatGPT 模型、在组合中加入原生目标、异构 provider 委派改用 v1,或者在你能控制调用方时将任务重新作为明文 v2 `agent_message` 内容发送。
1929

2030
## 工作原理
2131

@@ -46,7 +56,7 @@ opencodex 允许你为目录中的所有模型选择多代理协作界面。仪
4656
- **Dashboard** → 第一个状态单元:选择 **v1**、**base** 或 **v2**。
4757
- **Models** 页面 → 使用顶部的分段控件。
4858
- 两个页面都有 **?** 按钮,可打开帮助弹窗并返回本文。
49-
- **Dashboard** → **子代理委托**:选择首选模型和可选的推理强度。在 v2 上,注入的指引会要求以 `fork_turns: "none"` 生成,使模型覆盖得以应用 —— 但原生→路由子代理的任务正文可能以加密形式到达([#92](https://github.com/lidge-jun/opencodex/issues/92))。
59+
- **Dashboard** → **子代理委托**:选择首选模型和可选的推理强度。在 v2 上,注入的指引会要求以 `fork_turns: "none"` 生成,使模型覆盖得以应用。如果原生→路由子代理只收到加密任务内容,请使用原生目标或 v1;仅外部目标的传输现在会明确返回 `unreadable_encrypted_agent_task`([#92](https://github.com/lidge-jun/opencodex/issues/92))。
5060

5161
### CLI
5262

0 commit comments

Comments
 (0)