diff --git a/docs-site/public/assets/ultra-mode-subagents.png b/docs-site/public/assets/ultra-mode-subagents.png new file mode 100644 index 000000000..0a75c75b8 Binary files /dev/null and b/docs-site/public/assets/ultra-mode-subagents.png differ diff --git a/docs-site/src/content/docs/reference/cli/agents.md b/docs-site/src/content/docs/reference/cli/agents.md index b98c036aa..37508e129 100644 --- a/docs-site/src/content/docs/reference/cli/agents.md +++ b/docs-site/src/content/docs/reference/cli/agents.md @@ -17,7 +17,7 @@ surface modes, delegation, effort, and fallback behavior fit together. ocx agent subagents set ark/model-a,openai/gpt-5.5 ``` -### `ocx v2 |threads >` +### `ocx v2 |threads |mode-hint >` Manage the Codex `multi_agent_v2` feature flag and the three-state multi-agent surface mode. @@ -30,6 +30,8 @@ Manage the Codex `multi_agent_v2` feature flag and the three-state multi-agent s | `mode default` | Respect upstream model surface pins. | | `mode v2` | Force all models to v2, enable native v2, and preserve the active thread limit. | | `threads ` | Set the active v1/v2 thread limit to an integer of at least 1. | +| `mode-hint ` | Set the Proactive delegation hint (Ultra mode) for every model and effort. | +| `mode-hint --clear` | Remove the hint so the effort-derived policy (ultra = proactive) resumes. | ```bash ocx v2 status @@ -37,6 +39,8 @@ ocx v2 mode v1 ocx v2 mode default ocx v2 on ocx v2 threads 16 +ocx v2 mode-hint "Proactive multi-agent delegation is active." +ocx v2 mode-hint --clear ``` The `mode` subcommand writes `multiAgentMode` to the opencodex config and resyncs the Codex catalog. @@ -44,6 +48,17 @@ Mode and flag transitions move the current numeric thread limit between the vali a failed transition restores the original `config.toml`. Changes apply to new Codex sessions, while running sessions keep their pinned surface. +`mode-hint` writes `features.multi_agent_v2.multi_agent_mode_hint_text` in Codex's +`$CODEX_HOME/config.toml` even when `multi_agent_v2` is currently disabled. The +command only persists the override; it does not enable or disable the feature, so +the hint takes effect when a matching Codex surface is active. The hint overrides +codex-rs's effort-derived multi-agent policy, so any model and any reasoning effort +receives the Proactive delegation prompt. It does **not** change reasoning effort +itself. A missing argument or a whitespace-only value is rejected; only `--clear` +removes the hint. The Subagents dashboard's Ultra mode **on** toggle has a stricter +gate: it requires the native feature to be enabled with an explicit v2 surface +(`ocx v2 mode v2`); `ocx v2 on` alone does not satisfy that dashboard gate. + ## Combo routing ### `ocx combo ...` · `ocx route combo ...` diff --git a/docs-site/src/content/docs/reference/configuration/agents.md b/docs-site/src/content/docs/reference/configuration/agents.md index f490626d2..dddf8d465 100644 --- a/docs-site/src/content/docs/reference/configuration/agents.md +++ b/docs-site/src/content/docs/reference/configuration/agents.md @@ -23,11 +23,26 @@ routes, and limits delegated work. | `effortCap?` | `string` | — | Hard ceiling for qualifying v2 main turns and marked spawned-child turns. Accepts `low` through `ultra`. | | `subagentEffortCap?` | `string` | — | Additional ceiling for spawned-child turns only. When both caps apply, the lower wins. | -Manage the surface with the dashboard or `ocx v2 status|on|off|mode |threads `. +Manage the surface with the dashboard or +`ocx v2 status|on|off|mode |threads |mode-hint `. Mode changes apply to new sessions. `maxConcurrentThreadsPerSession` is a `PUT /api/v2` field, not a `config.json` key; `ocx v2 threads ` writes `max_concurrent_threads_per_session` under `[features.multi_agent_v2]` in Codex's `$CODEX_HOME/config.toml` after v2 is enabled. +**Ultra mode** (the Subagents dashboard toggle, `PUT /api/v2` field +`multiAgentModeHintText`, and `ocx v2 mode-hint`) writes +`features.multi_agent_v2.multi_agent_mode_hint_text` in Codex's +`$CODEX_HOME/config.toml`. The CLI `ocx v2 mode-hint` command persists this key even +when `multi_agent_v2` is disabled; it does not toggle the feature. The hint overrides +codex-rs's effort-derived multi-agent policy, so any model and any reasoning effort +receives the Proactive delegation prompt; it does **not** change reasoning effort. +A `null` value removes the key so the effort-derived policy (ultra = proactive, +otherwise explicit) resumes; empty or whitespace-only values are rejected because a +present empty override would suppress even the ultra-derived Proactive message. The +Subagents dashboard's Ultra mode **on** toggle requires both the native feature and +an explicit v2 surface (`multiAgentMode: "v2"`, equivalent to `ocx v2 mode v2`); +`ocx v2 on` alone does not satisfy that dashboard gate. + The management API exposes `GET`/`PUT /api/v2`, `/api/injection-model`, `/api/effort-caps`, `/api/subagent-models`, and `/api/subagent-model-fallback`. Injection-model updates are partial; the custom prompt is the `prompt` field on that API. diff --git a/gui/src/components/subagents-workspace/SubagentDelegationSection.tsx b/gui/src/components/subagents-workspace/SubagentDelegationSection.tsx index 2cf672b93..d2e60c3cd 100644 --- a/gui/src/components/subagents-workspace/SubagentDelegationSection.tsx +++ b/gui/src/components/subagents-workspace/SubagentDelegationSection.tsx @@ -6,10 +6,12 @@ * better next to the roster it affects: the roster picks who may be called, this picks who * gets called first. */ +import { useState } from "react"; import { Select } from "../../ui"; import { useT } from "../../i18n/shared"; import { formatNamespacedModelId } from "../../provider-icons"; import type { DelegationPatch, DelegationModelOption } from "../../pages/use-subagent-delegation"; +import type { UltraModePatch, UltraModeState } from "../../pages/use-subagent-delegation"; export interface SubagentDelegationSectionProps { model: string; @@ -20,6 +22,11 @@ export interface SubagentDelegationSectionProps { syncCodexDefaults: boolean; saving: boolean; onSave: (patch: DelegationPatch) => void; + ultraMode: UltraModeState; + ultraSaving: boolean; + onUltraModeSave: (patch: UltraModePatch) => void; + ultraLoadFailed: boolean; + onUltraModeRetry: () => void; } export default function SubagentDelegationSection({ @@ -31,11 +38,31 @@ export default function SubagentDelegationSection({ syncCodexDefaults, saving, onSave, + ultraMode, + ultraSaving, + onUltraModeSave, + ultraLoadFailed, + onUltraModeRetry, }: SubagentDelegationSectionProps) { const t = useT(); + // A present empty/whitespace hint is an upstream override that suppresses the + // Proactive message, so it must render as OFF (and the toggle can install the + // preset). Only a nonblank hint is "on". + const ultraOn = (ultraMode.hintText ?? "").trim().length > 0; return (
+ {ultraLoadFailed && ( +
+
+
{t("sub.ultraMode")}
+
{t("sub.ultraModeLoadFail")}
+
+ +
+ )}
{t("sub.delegation.model")}
@@ -100,6 +127,101 @@ export default function SubagentDelegationSection({
+ +
+
+
{t("sub.ultraMode")}
+
{t("sub.ultraModeHint")}
+
+ + {!ultraMode.multiAgentV2Enabled && ( +
{t("sub.ultraModeV2Required")}
+ )} +
+ {ultraOn && ( +
+ +
+ )}
); } + +/** + * Local-draft editor for the Ultra mode hint. Drafts are owned here and committed + * explicitly; the parent remounts this editor (via `key`) whenever the committed + * server value changes, so a stale draft never survives a reload or toggle flip. + */ +function UltraModeEditor({ + initialHint, + disabled, + onSave, + preset, + labels, +}: { + initialHint: string; + disabled: boolean; + onSave: (patch: UltraModePatch) => void; + preset: string; + labels: { text: string; preset: string; save: string }; +}) { + const [draft, setDraft] = useState(initialHint); + const commit = () => { + if (draft.trim().length === 0) return; + onSave({ multiAgentModeHintText: draft }); + }; + return ( + <> +