Skip to content

feat(codex): add opt-in native subagent defaults #498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Wibias merged 1 commit into from
Jul 27, 2026
Merged

feat(codex): add opt-in native subagent defaults #498

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions docs-site/src/content/docs/guides/codex-app-models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,9 +136,10 @@ Set the mode from the Dashboard or Models page, `ocx v2 mode v1|default|v2`, or
with `{ "multiAgentMode": "v1" }`. Changes apply to new Codex sessions.

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

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

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

## Refreshing model state

Expand Down
15 changes: 11 additions & 4 deletions docs-site/src/content/docs/guides/sub-agent-surface.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,9 @@ The override is the final pass in both the live `/v1/models` catalog response an

### Delegation model and effort

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.
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.

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.

`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.

Expand All @@ -56,7 +58,7 @@ To replace the built-in v2 guidance, set `injectionPrompt` (config key, or `PUT
- **Dashboard** → first stat cell: click **v1**, **base**, or **v2**.
- **Models** page → top-row segmented control.
- Both pages have a **?** button that opens a help modal with a link back here.
- **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)).
- **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)).

### CLI

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

# Opt in to native Codex defaults for new tasks after sync/restart (requires a model)
curl -X PUT http://localhost:10100/api/injection-model \
-H 'Content-Type: application/json' \
-d '{"model": "anthropic/claude-sonnet-5", "syncCodexSubagentDefaults": true}'

# Set a custom guidance prompt ({{model}}/{{effort}}/{{roster}} placeholders)
curl -X PUT http://localhost:10100/api/injection-model \
-H 'Content-Type: application/json' \
Expand All @@ -103,11 +110,11 @@ curl -X PUT http://localhost:10100/api/injection-model \
-d '{"model": null}'
```

`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.
`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.

## Reasoning effort

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.
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.

`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:

Expand Down
28 changes: 20 additions & 8 deletions docs-site/src/content/docs/guides/web-dashboard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ bun run dev:gui
| Area | What it does |
| --- | --- |
| **Dashboard summary** | Multi-agent mode, online state, version, uptime, provider count, 30-day token total, active providers, and available native/routed models. |
| **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. |
| **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. |
| **Sidecars** | Choose the web-search model and effort plus the vision-description model. Changes apply on the next request. |
| **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. |
| **Startup safety** | Show whether injected Codex routing survives a restart, with separate service and launcher-shim health plus exact repair commands. |
Expand Down Expand Up @@ -61,17 +61,29 @@ The **Models** switches show final Codex visibility: a routed model is on only w
## Delegation picker vs spawn routing

The Dashboard's **Sub-agent delegation** picker stores `injectionModel` and, optionally,
`injectionEffort`. On a v1 turn, opencodex injects guidance telling the parent agent which exact
model and reasoning effort to pass to `spawn_agent`. Choosing a model enables that guidance at any
parent reasoning effort; clearing the model also clears the stored effort.
`injectionEffort`. **OpenCodex multi-agent guidance** independently controls the delegation
instructions that use those values. On eligible v2 turns, that guidance tells the parent
agent which exact model and reasoning effort to pass to `spawn_agent`; clearing the model also clears
the stored effort.
Comment on lines 63 to +67

@coderabbitai coderabbitai Bot Jul 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Qualify the spawn-agent guarantee when custom prompts are used.

This wording implies every guidance variant passes the exact model and effort to spawn_agent, but injectionPrompt can replace the built-in guidance entirely. A custom prompt without {{model}} or {{effort}} will not necessarily provide those overrides. Clarify that this guarantee applies to built-in guidance, and document that custom prompts must include the placeholders when needed.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-site/src/content/docs/guides/web-dashboard.md` around lines 62 - 66,
Update the documentation around the Sub-agent delegation picker and OpenCodex
multi-agent guidance to limit the exact model and reasoning-effort guarantee to
the built-in guidance. State that custom injectionPrompt content replaces the
built-in guidance and must include the {{model}} and/or {{effort}} placeholders
when those overrides are required.

Source: Path instructions


The default-off **Use as native Codex subagent defaults** switch applies the same selection to Codex's
native `[agents]` defaults on the next sync/restart when OpenCodex manages the active Codex routing.
External user-managed provider configs remain untouched. Those defaults affect newly created Codex tasks
and do not themselves cause delegation. Existing user-owned `[agents]` defaults are preserved rather
than overwritten, so they may continue to override the requested defaults.

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

The spawn override guarantee applies to the **built-in** v2 guidance text. A custom
`injectionPrompt` replaces that text entirely and must include `{{model}}` and `{{effort}}`
placeholders (and optionally `{{roster}}`) or those values will not appear in the injected
guidance.

The picker offers enabled native and routed models plus the global Codex effort ladder. The API
validates the selected effort globally; Codex still validates a spawn effort against the target
catalog entry.
Expand Down Expand Up @@ -107,7 +119,7 @@ The GUI is a thin client over the proxy's JSON management API. Useful endpoints
| `POST /api/sync` | Rebuild the shared model catalog and stale the Codex model cache. |
| `GET /api/update/check` · `POST /api/update/run` · `GET /api/update/status` | Check, run, and monitor self-update jobs. |
| `GET` / `PUT /api/sidecar-settings` | Read or set search/vision sidecar model settings. |
| `GET` / `PUT /api/injection-model` | Read or set the v1 delegation guidance model and optional effort. |
| `GET` / `PUT /api/injection-model` | Read or set the shared sub-agent model/effort selection and the independent guidance/native-default switches. |
| `GET` / `PUT /api/v2` | Read or set the surface mode, Codex feature flag, and v2 thread limit. |
| `GET /api/providers` · `POST /api/providers` · `PATCH /api/providers?name=...` · `DELETE /api/providers?name=...` | List, add/replace, enable/disable, or remove providers. |
| `GET /api/models` · `PUT /api/disabled-models` | List native/routed model rows and update the shared disabled-model set. |
Expand Down
12 changes: 6 additions & 6 deletions docs-site/src/content/docs/ja/guides/codex-app-models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,10 +112,10 @@ opencodex は全カタログ項目の `multi_agent_version` を制御する 3
セッションから適用されます。

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

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

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

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

Expand Down
Loading
Loading