feat(v2): Ultra mode toggle — proactive delegation for every model/effort

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 <status|on|off|mode <v1|default|v2>|threads <n>>`
+### `ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>|mode-hint <text|--clear>>`
 
 Manage the Codex `multi_agent_v2` feature flag and the three-state multi-agent surface mode.
 
@@ -30,20 +30,35 @@ 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 <n>` | Set the active v1/v2 thread limit to an integer of at least 1. |
+| `mode-hint <text>` | 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
 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.
 Mode and flag transitions move the current numeric thread limit between the valid v1/v2 Codex keys;
 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 <list|show|set|remove> ...` · `ocx route combo ...`

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 <v1|default|v2>|threads <n>`.
+Manage the surface with the dashboard or
+`ocx v2 status|on|off|mode <v1|default|v2>|threads <n>|mode-hint <text|--clear>`.
 Mode changes apply to new sessions. `maxConcurrentThreadsPerSession` is a `PUT /api/v2` field, not a
 `config.json` key; `ocx v2 threads <n>` 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.

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 (
     <div className="swi-delegation">
+      {ultraLoadFailed && (
+        <div className="swi-delegation-row">
+          <div className="setting-copy">
+            <div className="font-semibold">{t("sub.ultraMode")}</div>
+            <div className="muted setting-hint">{t("sub.ultraModeLoadFail")}</div>
+          </div>
+          <button type="button" className="btn btn-ghost btn-sm" onClick={onUltraModeRetry}>
+            {t("common.retry")}
+          </button>
+        </div>
+      )}
       <div className="swi-delegation-row">
         <div className="setting-copy">
           <div className="font-semibold">{t("sub.delegation.model")}</div>
@@ -100,6 +127,101 @@ export default function SubagentDelegationSection({
           <span className="knob" />
         </button>
       </div>
+
+      <div className="swi-delegation-row">
+        <div className="setting-copy">
+          <div className="font-semibold">{t("sub.ultraMode")}</div>
+          <div className="muted setting-hint">{t("sub.ultraModeHint")}</div>
+        </div>
+        <button
+          type="button"
+          className={`switch ${ultraOn ? "on" : ""}`}
+          onClick={() => onUltraModeSave({ multiAgentModeHintText: ultraOn ? null : ULTRA_MODE_PRESET })}
+          // Turning OFF (clear) is always safe, even when v2 is disabled — a stale
+          // hint would otherwise silently re-activate on the next v2 enable.
+          disabled={saving || ultraSaving || (!ultraOn && !ultraMode.multiAgentV2Enabled)}
+          aria-label={t("sub.ultraMode")}
+          aria-pressed={ultraOn}
+        >
+          <span className="knob" />
+        </button>
+        {!ultraMode.multiAgentV2Enabled && (
+          <div className="muted setting-hint">{t("sub.ultraModeV2Required")}</div>
+        )}
+      </div>
+      {ultraOn && (
+        <div className="swi-delegation-row swi-ultra-mode-editor">
+          <UltraModeEditor
+            key={ultraMode.hintText}
+            initialHint={ultraMode.hintText ?? ""}
+            disabled={saving || ultraSaving}
+            onSave={onUltraModeSave}
+            preset={ULTRA_MODE_PRESET}
+            labels={{
+              text: t("sub.ultraModeText"),
+              preset: t("sub.ultraModePreset"),
+              save: t("common.save"),
+            }}
+          />
+        </div>
+      )}
     </div>
   );
 }
+
+/**
+ * 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 (
+    <>
+      <textarea
+        className="input swi-ultra-mode-textarea"
+        value={draft}
+        onChange={e => setDraft(e.target.value)}
+        disabled={disabled}
+        rows={4}
+        aria-label={labels.text}
+      />
+      <button
+        type="button"
+        className="btn btn-ghost btn-sm"
+        onClick={() => setDraft(preset)}
+        disabled={disabled}
+      >
+        {labels.preset}
+      </button>
+      <button
+        type="button"
+        className="btn btn-primary btn-sm"
+        onClick={commit}
+        disabled={disabled || draft.trim().length === 0}
+      >
+        {labels.save}
+      </button>
+    </>
+  );
+}
+
+/** Canonical Proactive delegation text mirrored from codex-rs (multi_agent_mode_instructions.rs). */
+export const ULTRA_MODE_PRESET =
+  "Proactive multi-agent delegation is active. Any earlier instruction requiring an explicit user request before spawning sub-agents no longer applies. Delegate independent sub-tasks to sub-agents whenever parallel work would materially improve speed or quality — do not serialize work that can run concurrently. Each sub-agent runs in its own context and can use all available tools; prefer spawning specialists over doing everything yourself. This mode remains active until a later multi-agent mode developer message changes it.";

gui/src/components/subagents-workspace/SubagentsWorkspace.tsx

@@ -27,7 +27,7 @@ import { modelLabel } from "../../model-display";
 import { SectionTabs } from "../section-tabs";
 import { sectionAnchorId } from "../../section-anchors";
 import SubagentDelegationSection from "./SubagentDelegationSection";
-import type { DelegationPatch, DelegationModelOption } from "../../pages/use-subagent-delegation";
+import type { DelegationPatch, DelegationModelOption, UltraModePatch, UltraModeState } from "../../pages/use-subagent-delegation";
 
 export interface SubagentsWorkspaceProps {
   available: string[];
@@ -45,6 +45,11 @@ export interface SubagentsWorkspaceProps {
     syncCodexDefaults: boolean;
     saving: boolean;
     onSave: (patch: DelegationPatch) => void;
+    ultraMode: UltraModeState;
+    ultraSaving: boolean;
+    onUltraModeSave: (patch: UltraModePatch) => void;
+    ultraLoadFailed: boolean;
+    onUltraModeRetry: () => void;
   };
 }
 
@@ -224,6 +229,11 @@ export default function SubagentsWorkspace({
             syncCodexDefaults={delegation.syncCodexDefaults}
             saving={delegation.saving}
             onSave={delegation.onSave}
+            ultraMode={delegation.ultraMode}
+            ultraSaving={delegation.ultraSaving}
+            onUltraModeSave={delegation.onUltraModeSave}
+            ultraLoadFailed={delegation.ultraLoadFailed}
+            onUltraModeRetry={delegation.onUltraModeRetry}
           />
         </section>
       </div>

gui/src/i18n/de.ts

@@ -567,6 +567,14 @@ export const de: Record<TKey, string> = {
   "sub.workspace.selectModel": "Modell auswählen",
   "sub.workspace.selectModelDesc": "Wählen Sie ein Modell aus der Liste, um Details anzuzeigen und es für spawn_agent hervorzuheben.",
   "sub.workspace.selector": "Öffentlicher Selektor",
+  "sub.ultraMode": "Ultra-Modus",
+  "sub.ultraModeHint": "Aktiviert die proaktive Multi-Agent-Delegierungsrichtlinie für alle Modelle und Reasoning-Efforts (ändert den Reasoning-Effort selbst nicht). Schreibt features.multi_agent_v2.multi_agent_mode_hint_text in config.toml.",
+  "sub.ultraModeV2Required": "Erfordert die v2-Multi-Agent-Oberfläche — aktivieren Sie zuerst multi_agent_v2 und wählen Sie v2 in der Subagentenmodus-Steuerung.",
+  "sub.ultraModeText": "Delegierungstext des Ultra-Modus",
+  "sub.ultraModePreset": "Voreinstellung wiederherstellen",
+  "sub.ultraModeLoadFail": "Ultra-Modus-Einstellungen konnten nicht geladen werden — läuft der Proxy?",
+  "sub.ultraModeSaveFail": "Ultra-Modus-Einstellungen konnten nicht gespeichert werden",
+  "sub.ultraModeSaved": "Ultra-Modus gespeichert. Gilt für neue Codex-Sitzungen.",
   "logs.title": "Anfrage-Protokolle",
   "logs.tabLogs": "Protokolle",
   "logs.tabDebug": "Diagnose",

gui/src/i18n/en.ts

@@ -588,6 +588,14 @@ export const en = {
   "sub.workspace.mainAria": "Subagent model details",
   "sub.workspace.notFeatured": "Not featured",
   "sub.workspace.priority": "Priority",
+  "sub.ultraMode": "Ultra mode",
+  "sub.ultraModeHint": "Enable the Proactive multi-agent delegation policy for every model and reasoning effort (does not change reasoning effort itself). Writes features.multi_agent_v2.multi_agent_mode_hint_text in config.toml.",
+  "sub.ultraModeV2Required": "Requires the v2 multi-agent surface — enable multi_agent_v2 and select v2 in the Sub-agent mode control first.",
+  "sub.ultraModeText": "Ultra mode delegation text",
+  "sub.ultraModePreset": "Restore preset",
+  "sub.ultraModeLoadFail": "Failed to load Ultra mode settings — is the proxy running?",
+  "sub.ultraModeSaveFail": "Failed to save Ultra mode settings",
+  "sub.ultraModeSaved": "Ultra mode saved. Applies to new Codex sessions.",
   "sub.workspace.removeFromFeatured": "Remove {m} from featured",
   "sub.workspace.selectModel": "Select a model",
   "sub.workspace.selectModelDesc": "Pick a model from the list to see details and feature it for spawn_agent.",

gui/src/i18n/ja.ts

@@ -550,6 +550,14 @@ export const ja: Record<TKey, string> = {
   "sub.workspace.selectModel": "モデルを選択",
   "sub.workspace.selectModelDesc": "一覧からモデルを選んで詳細を確認し、spawn_agent のおすすめに設定します。",
   "sub.workspace.selector": "公開セレクター",
+  "sub.ultraMode": "ウルトラモード",
+  "sub.ultraModeHint": "すべてのモデルと reasoning effort で Proactive マルチエージェント委任ポリシーを有効にします（reasoning effort 自体は変更しません）。config.toml に features.multi_agent_v2.multi_agent_mode_hint_text を書き込みます。",
+  "sub.ultraModeV2Required": "v2 マルチエージェントサーフェスが必要です — 先に multi_agent_v2 を有効にし、サブエージェントモードで v2 を選択してください。",
+  "sub.ultraModeText": "ウルトラモード委任テキスト",
+  "sub.ultraModePreset": "プリセットを復元",
+  "sub.ultraModeLoadFail": "ウルトラモード設定を読み込めませんでした — プロキシは実行中ですか？",
+  "sub.ultraModeSaveFail": "ウルトラモード設定の保存に失敗しました",
+  "sub.ultraModeSaved": "ウルトラモードを保存しました。新しい Codex セッションから適用されます。",
 
   // logs
   "logs.title": "リクエストログ",

gui/src/i18n/ko.ts

@@ -584,6 +584,14 @@ export const ko: Record<TKey, string> = {
   "sub.workspace.selectModel": "모델 선택",
   "sub.workspace.selectModelDesc": "목록에서 모델을 선택하여 세부 정보를 확인하고 spawn_agent에 추천하세요.",
   "sub.workspace.selector": "공개 셀렉터",
+  "sub.ultraMode": "울트라 모드",
+  "sub.ultraModeHint": "모든 모델과 reasoning effort에서 Proactive 멀티에이전트 위임 정책을 켭니다 (reasoning effort 자체는 변경하지 않음). config.toml에 features.multi_agent_v2.multi_agent_mode_hint_text를 기록합니다.",
+  "sub.ultraModeV2Required": "v2 멀티에이전트 서피스가 필요합니다 — 먼저 multi_agent_v2를 켜고 서브에이전트 모드에서 v2를 선택하세요.",
+  "sub.ultraModeText": "울트라 모드 위임 텍스트",
+  "sub.ultraModePreset": "프리셋 복원",
+  "sub.ultraModeLoadFail": "울트라 모드 설정을 불러오지 못했습니다 — 프록시가 실행 중인가요?",
+  "sub.ultraModeSaveFail": "울트라 모드 설정 저장에 실패했습니다",
+  "sub.ultraModeSaved": "울트라 모드가 저장되었습니다. 새 Codex 세션부터 적용됩니다.",
 
   // logs
   "logs.title": "요청 로그",

gui/src/i18n/ru.ts

@@ -582,6 +582,14 @@ export const ru: Record<TKey, string> = {
   "sub.workspace.selectModel": "Выберите модель",
   "sub.workspace.selectModelDesc": "Выберите модель из списка, чтобы увидеть детали и добавить её в избранные для spawn_agent.",
   "sub.workspace.selector": "Публичный селектор",
+  "sub.ultraMode": "Ультра-режим",
+  "sub.ultraModeHint": "Включает политику упреждающего делегирования мультиагентов для всех моделей и уровней reasoning effort (сам reasoning effort не меняется). Записывает features.multi_agent_v2.multi_agent_mode_hint_text в config.toml.",
+  "sub.ultraModeV2Required": "Требуется мультиагентная поверхность v2 — сначала включите multi_agent_v2 и выберите v2 в переключателе режима субагентов.",
+  "sub.ultraModeText": "Текст делегирования ультра-режима",
+  "sub.ultraModePreset": "Восстановить пресет",
+  "sub.ultraModeLoadFail": "Не удалось загрузить настройки ультра-режима — работает ли прокси?",
+  "sub.ultraModeSaveFail": "Не удалось сохранить настройки ультра-режима",
+  "sub.ultraModeSaved": "Ультра-режим сохранён. Применяется к новым сеансам Codex.",
 
   // logs
   "logs.title": "Журнал запросов",

gui/src/i18n/tr.ts

@@ -589,6 +589,14 @@ export const tr: Record<TKey, string> = {
   "sub.workspace.selectModel": "Bir model seçin",
   "sub.workspace.selectModelDesc": "Detayları görmek için listeden bir model seçin.",
   "sub.workspace.selector": "Genel seçici",
+  "sub.ultraMode": "Ultra modu",
+  "sub.ultraModeHint": "Tüm modeller ve reasoning effort için Proactive çoklu ajan delegasyon politikasını etkinleştirir (reasoning effort değerini değiştirmez). config.toml dosyasına features.multi_agent_v2.multi_agent_mode_hint_text yazar.",
+  "sub.ultraModeV2Required": "v2 çoklu ajan yüzeyi gerekir — önce multi_agent_v2'yi etkinleştirin ve alt ajan modu denetiminde v2'yi seçin.",
+  "sub.ultraModeText": "Ultra modu delegasyon metni",
+  "sub.ultraModePreset": "Ön ayarı geri yükle",
+  "sub.ultraModeLoadFail": "Ultra modu ayarları yüklenemedi — proxy çalışıyor mu?",
+  "sub.ultraModeSaveFail": "Ultra modu ayarları kaydedilemedi",
+  "sub.ultraModeSaved": "Ultra modu kaydedildi. Yeni Codex oturumlarına uygulanır.",
 
   // logs
   "logs.title": "İstek Günlükleri",