Skip to content

Commit 053ad66

Browse files
authored
feat(codex): add opt-in native subagent defaults (#498)
Co-authored-by: wonsh42 <[email protected]>
1 parent 458c363 commit 053ad66

55 files changed

Lines changed: 2545 additions & 293 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs-site/src/content/docs/guides/codex-app-models.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -136,9 +136,10 @@ Set the mode from the Dashboard or Models page, `ocx v2 mode v1|default|v2`, or
136136
with `{ "multiAgentMode": "v1" }`. Changes apply to new Codex sessions.
137137

138138
:::caution
139-
On the v2 (`multi_agent_v2`) surface, spawned sub-agents inherit the parent session's model. The
140-
dashboard's delegation model/effort picker is v1 prompt guidance, not a proxy-side per-spawn
141-
cross-model router. See [Sub-agent Surface](/guides/sub-agent-surface/) for the canonical
139+
On the v2 (`multi_agent_v2`) surface, a spawn without an explicit model can inherit the parent
140+
session's model. OpenCodex guidance can ask Codex to pass the selected model/effort explicitly, and
141+
the separate native-default opt-in can supply defaults after sync/restart. Neither mechanism is a
142+
proxy-side per-spawn router. See [Sub-agent Surface](/guides/sub-agent-surface/) for the canonical
142143
behavior.
143144
:::
144145

@@ -175,8 +176,9 @@ Codex sorts picker-visible catalog entries by ascending `priority` and advertise
175176
through `subagentModels` or the dashboard Subagents page; opencodex gives those entries priorities
176177
0-4 in the chosen order. Other models remain callable by exact id.
177178

178-
The featured-model list is separate from the Dashboard's **Sub-agent delegation** guidance. In
179-
particular, featured model overrides do not bypass v2's parent-model inheritance rule.
179+
The featured-model list is separate from the Dashboard's **Sub-agent delegation** selection. It
180+
controls which overrides Codex offers first; it does not select a model or trigger delegation by
181+
itself.
180182

181183
## Refreshing model state
182184

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

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,9 @@ The override is the final pass in both the live `/v1/models` catalog response an
3939

4040
### Delegation model and effort
4141

42-
The dashboard's **Sub-agent delegation** picker stores an `injectionModel` and, optionally, an `injectionEffort`. These are delegation guidance settings, not a proxy-side spawn router. An optional `injectionPrompt` replaces the built-in guidance text entirely.
42+
The dashboard's **Sub-agent delegation** picker stores an `injectionModel` and, optionally, an `injectionEffort`. OpenCodex-authored delegation guidance can use these selections, but it remains controlled separately by **OpenCodex multi-agent guidance**. These settings are not a proxy-side spawn router. An optional `injectionPrompt` replaces the built-in guidance text entirely.
43+
44+
The default-off **Use as native Codex subagent defaults** switch sets `syncCodexSubagentDefaults`. When OpenCodex manages the active Codex routing, a sync or restart applies the selected model and effort as native Codex `[agents]` defaults for newly created Codex tasks. External user-managed provider configs remain untouched. This does not trigger delegation. Existing user-owned `[agents]` defaults are preserved rather than overwritten, so they remain authoritative.
4345

4446
`multiAgentGuidanceText` identifies the surface from the request's tools — including the Codex Desktop WebSocket path (`responses_lite`), where tools arrive inside an `additional_tools` input item instead of the request's `tools` array.
4547

@@ -56,7 +58,7 @@ To replace the built-in v2 guidance, set `injectionPrompt` (config key, or `PUT
5658
- **Dashboard** → first stat cell: click **v1**, **base**, or **v2**.
5759
- **Models** page → top-row segmented control.
5860
- Both pages have a **?** button that opens a help modal with a link back here.
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)).
61+
- **Dashboard** → **Sub-agent delegation**: choose a preferred model and optional reasoning effort. Enable **OpenCodex multi-agent guidance** for delegation instructions, or independently enable **Use as native Codex subagent defaults** to apply the selection to new Codex tasks after sync/restart. The defaults switch does not cause delegation, and existing user-owned `[agents]` defaults are preserved rather than overwritten. 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)).
6062

6163
### CLI
6264

@@ -92,6 +94,11 @@ curl -X PUT http://localhost:10100/api/injection-model \
9294
-H 'Content-Type: application/json' \
9395
-d '{"model": "anthropic/claude-sonnet-5", "effort": "xhigh"}'
9496

97+
# Opt in to native Codex defaults for new tasks after sync/restart (requires a model)
98+
curl -X PUT http://localhost:10100/api/injection-model \
99+
-H 'Content-Type: application/json' \
100+
-d '{"model": "anthropic/claude-sonnet-5", "syncCodexSubagentDefaults": true}'
101+
95102
# Set a custom guidance prompt ({{model}}/{{effort}}/{{roster}} placeholders)
96103
curl -X PUT http://localhost:10100/api/injection-model \
97104
-H 'Content-Type: application/json' \
@@ -103,11 +110,11 @@ curl -X PUT http://localhost:10100/api/injection-model \
103110
-d '{"model": null}'
104111
```
105112

106-
`GET /api/injection-model` returns `model`, `effort`, `prompt`, the global `efforts` ladder, and enabled native/routed `available` models. For PUT, omitting `effort` or `prompt` keeps the current value, `null` clears it, and clearing `model` always clears the effort too. The API validates effort against the global Codex ladder; Codex still validates a spawn effort against the target catalog entry.
113+
`GET /api/injection-model` returns `model`, `effort`, `prompt`, `multiAgentGuidanceEnabled`, `syncCodexSubagentDefaults`, the global `efforts` ladder, and enabled native/routed `available` models. PUT is partial: omitted fields keep their current values, `null` clears nullable values, and clearing `model` always clears both the effort and native-default opt-in. Enabling `syncCodexSubagentDefaults` requires a model. The API validates effort against the global Codex ladder; Codex still validates a spawn effort against the target catalog entry.
107114

108115
## Reasoning effort
109116

110-
The optional sub-agent effort setting is stored as `injectionEffort` and is meaningful only with an injection model. It adds a `reasoning_effort` instruction to the injected v2 guidance; it does not change the parent session's effort. On any fork that accepts overrides, Codex applies a `reasoning_effort` passed to `spawn_agent` directly.
117+
The optional sub-agent effort setting is stored as `injectionEffort` and is meaningful only with an injection model. It adds a `reasoning_effort` instruction to the injected v2 guidance; with native-default sync enabled, it also becomes the `[agents]` reasoning default for new Codex tasks after sync/restart. It does not change the parent session's effort. On any fork that accepts overrides, Codex applies a `reasoning_effort` passed to `spawn_agent` directly.
111118

112119
`ultra` ranks above `max` in the Codex catalog and adds automatic-delegation semantics, but it never reaches a provider as a literal wire value. Codex converts `ultra` to `max` at the client boundary. opencodex then keeps the provider request valid:
113120

‎docs-site/src/content/docs/guides/web-dashboard.md‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ bun run dev:gui
2626
| Area | What it does |
2727
| --- | --- |
2828
| **Dashboard summary** | Multi-agent mode, online state, version, uptime, provider count, 30-day token total, active providers, and available native/routed models. |
29-
| **Sub-agent delegation** | Choose a native or routed guidance model and an optional reasoning effort for v1 delegation prompts. This is not a per-spawn router; see below. |
29+
| **Sub-agent delegation** | Choose a native or routed model and optional reasoning effort shared by OpenCodex delegation guidance and the separate native-default opt-in. This is not a proxy-side per-spawn router; see below. |
3030
| **Sidecars** | Choose the web-search model and effort plus the vision-description model. Changes apply on the next request. |
3131
| **Maintenance** | Resync the Codex model catalog, inspect project-local config bypass warnings, check the latest or preview release, and run an update with optional proxy restart. |
3232
| **Startup safety** | Show whether injected Codex routing survives a restart, with separate service and launcher-shim health plus exact repair commands. |
@@ -61,17 +61,29 @@ The **Models** switches show final Codex visibility: a routed model is on only w
6161
## Delegation picker vs spawn routing
6262

6363
The Dashboard's **Sub-agent delegation** picker stores `injectionModel` and, optionally,
64-
`injectionEffort`. On a v1 turn, opencodex injects guidance telling the parent agent which exact
65-
model and reasoning effort to pass to `spawn_agent`. Choosing a model enables that guidance at any
66-
parent reasoning effort; clearing the model also clears the stored effort.
64+
`injectionEffort`. **OpenCodex multi-agent guidance** independently controls the delegation
65+
instructions that use those values. On eligible v2 turns, that guidance tells the parent
66+
agent which exact model and reasoning effort to pass to `spawn_agent`; clearing the model also clears
67+
the stored effort.
68+
69+
The default-off **Use as native Codex subagent defaults** switch applies the same selection to Codex's
70+
native `[agents]` defaults on the next sync/restart when OpenCodex manages the active Codex routing.
71+
External user-managed provider configs remain untouched. Those defaults affect newly created Codex tasks
72+
and do not themselves cause delegation. Existing user-owned `[agents]` defaults are preserved rather
73+
than overwritten, so they may continue to override the requested defaults.
6774

6875
:::caution
69-
This picker is delegation guidance for the v1 compatibility surface. On `multi_agent_v2`, the
70-
current proxy does not append the v1 injection message, and every spawned sub-agent inherits the
71-
parent session's model. It is not a proxy-side cross-model router. See
76+
Neither control is a proxy-side cross-model spawn router. OpenCodex guidance asks Codex to pass
77+
overrides to `spawn_agent`; native `[agents]` defaults apply only when Codex creates a new task after
78+
they have been synchronized. See
7279
[Sub-agent Surface](/guides/sub-agent-surface/) for the canonical v1/base/v2 behavior.
7380
:::
7481

82+
The spawn override guarantee applies to the **built-in** v2 guidance text. A custom
83+
`injectionPrompt` replaces that text entirely and must include `{{model}}` and `{{effort}}`
84+
placeholders (and optionally `{{roster}}`) or those values will not appear in the injected
85+
guidance.
86+
7587
The picker offers enabled native and routed models plus the global Codex effort ladder. The API
7688
validates the selected effort globally; Codex still validates a spawn effort against the target
7789
catalog entry.
@@ -107,7 +119,7 @@ The GUI is a thin client over the proxy's JSON management API. Useful endpoints
107119
| `POST /api/sync` | Rebuild the shared model catalog and stale the Codex model cache. |
108120
| `GET /api/update/check` · `POST /api/update/run` · `GET /api/update/status` | Check, run, and monitor self-update jobs. |
109121
| `GET` / `PUT /api/sidecar-settings` | Read or set search/vision sidecar model settings. |
110-
| `GET` / `PUT /api/injection-model` | Read or set the v1 delegation guidance model and optional effort. |
122+
| `GET` / `PUT /api/injection-model` | Read or set the shared sub-agent model/effort selection and the independent guidance/native-default switches. |
111123
| `GET` / `PUT /api/v2` | Read or set the surface mode, Codex feature flag, and v2 thread limit. |
112124
| `GET /api/providers` · `POST /api/providers` · `PATCH /api/providers?name=...` · `DELETE /api/providers?name=...` | List, add/replace, enable/disable, or remove providers. |
113125
| `GET /api/models` · `PUT /api/disabled-models` | List native/routed model rows and update the shared disabled-model set. |

‎docs-site/src/content/docs/ja/guides/codex-app-models.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -112,10 +112,10 @@ opencodex は全カタログ項目の `multi_agent_version` を制御する 3
112112
セッションから適用されます。
113113

114114
:::caution
115-
v2(`multi_agent_v2`)サーフェスで生成されたサブエージェントは親セッションのモデルを継承します。ダッシュボードの
116-
委任モデル/強度セレクターは v1 プロンプトガイダンスであり、プロキシがスポーンごとに別モデルにルーティングする機能では
117-
ありません。正確な動作は[サブエージェントサーフェス](/ja/guides/sub-agent-surface/)を
118-
参照してください。
115+
v2(`multi_agent_v2`)サーフェスでは、モデルを明示しないスポーンは親セッションのモデルを継承できます。
116+
OpenCodex ガイダンスは選択したモデル/強度を明示的に渡すよう Codex に指示でき、別のネイティブデフォルト設定は
117+
sync/restart 後に既定値を提供できます。どちらもプロキシ側のスポーン単位ルーターではありません。正確な動作は
118+
[サブエージェントサーフェス](/ja/guides/sub-agent-surface/)を参照してください。
119119
:::
120120

121121
## 最上位推論段階
@@ -151,8 +151,8 @@ Codex はピッカーに表示されるカタログ項目を `priority` 昇順
151151
ネイティブ ID または `provider/model` ID を最大 5 つ選ぶと opencodex が選択順に priority 0-4 を
152152
付与します。残りのモデルも正確な ID で直接呼び出し可能です。
153153

154-
フィーチャー済みモデル一覧はダッシュボードの **Sub-agent delegation** ガイダンスとは別物です。特にフィーチャー済みモデル
155-
オーバーライドで v2 の親モデル継承ルールをバイパスできません。
154+
フィーチャー済みモデル一覧はダッシュボードの **Sub-agent delegation** 選択とは別物です。Codex が最初に提示する
155+
オーバーライドを決めるだけで、モデルの選択や委任の開始は行いません。
156156

157157
## モデル状態のリフレッシュ
158158

0 commit comments

Comments
 (0)