You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c233079
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs-site/src/content/docs/guides/sub-agent-surface.md
+11-4Lines changed: 11 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,7 +39,9 @@ The override is the final pass in both the live `/v1/models` catalog response an
39
39
40
40
### Delegation model and effort
41
41
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.
43
45
44
46
`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.
45
47
@@ -56,7 +58,7 @@ To replace the built-in v2 guidance, set `injectionPrompt` (config key, or `PUT
56
58
-**Dashboard** → first stat cell: click **v1**, **base**, or **v2**.
57
59
-**Models** page → top-row segmented control.
58
60
- 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)).
60
62
61
63
### CLI
62
64
@@ -92,6 +94,11 @@ curl -X PUT http://localhost:10100/api/injection-model \
# Opt in to native Codex defaults for new tasks after sync/restart
98
+
curl -X PUT http://localhost:10100/api/injection-model \
99
+
-H 'Content-Type: application/json' \
100
+
-d '{"syncCodexSubagentDefaults": true}'
101
+
95
102
# Set a custom guidance prompt ({{model}}/{{effort}}/{{roster}} placeholders)
96
103
curl -X PUT http://localhost:10100/api/injection-model \
97
104
-H 'Content-Type: application/json' \
@@ -103,11 +110,11 @@ curl -X PUT http://localhost:10100/api/injection-model \
103
110
-d '{"model": null}'
104
111
```
105
112
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.
107
114
108
115
## Reasoning effort
109
116
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.
111
118
112
119
`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:
Copy file name to clipboardExpand all lines: docs-site/src/content/docs/guides/web-dashboard.md
+15-8Lines changed: 15 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,7 +26,7 @@ bun run dev:gui
26
26
| Area | What it does |
27
27
| --- | --- |
28
28
|**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. |
30
30
|**Sidecars**| Choose the web-search model and effort plus the vision-description model. Changes apply on the next request. |
31
31
|**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. |
32
32
|**Startup safety**| Show whether injected Codex routing survives a restart, with separate service and launcher-shim health plus exact repair commands. |
@@ -60,14 +60,21 @@ The **Models** switches show final Codex visibility: a routed model is on only w
60
60
## Delegation picker vs spawn routing
61
61
62
62
The Dashboard's **Sub-agent delegation** picker stores `injectionModel` and, optionally,
63
-
`injectionEffort`. On a v1 turn, opencodex injects guidance telling the parent agent which exact
64
-
model and reasoning effort to pass to `spawn_agent`. Choosing a model enables that guidance at any
65
-
parent reasoning effort; clearing the model also clears the stored effort.
63
+
`injectionEffort`. **OpenCodex multi-agent guidance** independently controls the delegation
64
+
instructions that use those values. On eligible v2 turns, that guidance tells the parent
65
+
agent which exact model and reasoning effort to pass to `spawn_agent`; clearing the model also clears
66
+
the stored effort.
67
+
68
+
The default-off **Use as native Codex subagent defaults** switch applies the same selection to Codex's
69
+
native `[agents]` defaults on the next sync/restart when OpenCodex manages the active Codex routing.
70
+
External user-managed provider configs remain untouched. Those defaults affect newly created Codex tasks
71
+
and do not themselves cause delegation. Existing user-owned `[agents]` defaults are preserved rather
72
+
than overwritten, so they may continue to override the requested defaults.
66
73
67
74
:::caution
68
-
This picker is delegation guidance for the v1 compatibility surface. On `multi_agent_v2`, the
69
-
current proxy does not append the v1 injection message, and every spawned sub-agent inherits the
70
-
parent session's model. It is not a proxy-side cross-model router. See
75
+
Neither control is a proxy-side cross-model spawn router. OpenCodex guidance asks Codex to pass
76
+
overrides to `spawn_agent`; native `[agents]` defaults apply only when Codex creates a new task after
77
+
they have been synchronized. See
71
78
[Sub-agent Surface](/guides/sub-agent-surface/) for the canonical v1/base/v2 behavior.
72
79
:::
73
80
@@ -106,7 +113,7 @@ The GUI is a thin client over the proxy's JSON management API. Useful endpoints
106
113
|`POST /api/sync`| Rebuild the shared model catalog and stale the Codex model cache. |
0 commit comments