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 053ad66
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 (requires a model)
98
+
curl -X PUT http://localhost:10100/api/injection-model \
# 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
+20-8Lines changed: 20 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. |
@@ -61,17 +61,29 @@ The **Models** switches show final Codex visibility: a routed model is on only w
61
61
## Delegation picker vs spawn routing
62
62
63
63
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.
67
74
68
75
:::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
72
79
[Sub-agent Surface](/guides/sub-agent-surface/) for the canonical v1/base/v2 behavior.
73
80
:::
74
81
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
+
75
87
The picker offers enabled native and routed models plus the global Codex effort ladder. The API
76
88
validates the selected effort globally; Codex still validates a spawn effort against the target
77
89
catalog entry.
@@ -107,7 +119,7 @@ The GUI is a thin client over the proxy's JSON management API. Useful endpoints
107
119
|`POST /api/sync`| Rebuild the shared model catalog and stale the Codex model cache. |
0 commit comments