feat(agents): keep ChatGPT-native models on v1 when catalog is v2

docs-site/src/content/docs/guides/sub-agent-surface.md

@@ -20,6 +20,11 @@ Choose the mode for **new sessions**. Existing sessions keep the surface they st
 | **base** (default) | Upstream model pins: GPT-5.6 Sol/Terra use v2, Luna uses v1, and unpinned models follow Codex's `multi_agent_v2` feature flag. | Most users. It follows Codex's intended surface for each model without forcing one globally. |
 | **v2** | Flat `spawn_agent`, `send_message`, `followup_task`, `interrupt_agent`, and agent-list tools, with concurrent sessions. | Users who want the newer concurrent workflow and understand model inheritance and the encrypted-task limitation below. |
 
+On **v2**, an optional **Keep ChatGPT on v1** switch (`keepNativeChatGptOnV1`) leaves Sol/Terra
+on the v1 surface so they can still spawn Grok or Claude. ChatGPT-native parents encrypt v2
+`NEW_TASK` bodies; routed models cannot read them. Routed parents stay on v2, where child tasks
+are plaintext. This is a switch *inside* v2, not a fourth catalog mode.
+
 :::tip[Not sure?]
 Start with **base**. Choose **v1** when cross-provider delegation must work predictably. Force **v2**
 only when you specifically want its newer session model across every catalog entry.
@@ -31,7 +36,7 @@ The selected mode controls the `multi_agent_version` field in every catalog entr
 
 - **v1** stamps `multi_agent_version = "v1"` on every model.
 - **base** restores upstream pins. Unpinned entries follow the native `multi_agent_v2` feature flag.
-- **v2** stamps `multi_agent_version = "v2"` on every model.
+- **v2** stamps `multi_agent_version = "v2"` on every model, except when **Keep ChatGPT on v1** is enabled: ChatGPT-native rows stay `"v1"` and routed or combo rows stay `"v2"`.
 
 opencodex applies this as the final pass to both the live `/v1/models` catalog and the catalog synced
 to disk. That is why a mode change affects newly created App, CLI, and TUI sessions consistently.

docs-site/src/content/docs/reference/configuration/agents.md

@@ -11,6 +11,7 @@ routes, and limits delegated work.
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `multiAgentMode?` | `"v1" \| "default" \| "v2"` | `"default"` | `v1` stamps every catalog model as v1; `v2` stamps every model as v2. `default` restores upstream pins (Sol/Terra v2, Luna v1) and otherwise follows the native `multi_agent_v2` flag. Applies to new sessions. |
+| `keepNativeChatGptOnV1?` | `boolean` | `false` | When `multiAgentMode` is `"v2"`, stamp ChatGPT-native rows (Sol/Terra and other ChatGPT-backend models) as v1. Routed parents stay on v2. Use this so a ChatGPT parent can still spawn Grok or Claude — native v2 child tasks are backend-encrypted ([#92](https://github.com/lidge-jun/opencodex/issues/92)). Ignored in `v1` and `default`. |
 | `subagentModels?` | `string[]` | `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.4-mini` | Up to five bare native, account-qualified `<selector>/<native-openai-model>`, or routed `provider/model` ids featured first in the sub-agent picker. The dashboard offers only bare native and routed ids and omits exact account-qualified choices when it saves; use `ocx agent subagents set` or edit the configuration for exact choices. An explicit empty list is preserved. |
 | `injectionModel?` | `string` | — | Preferred native or routed sub-agent model used in proxy-authored v2 delegation guidance. |
 | `injectionEffort?` | `string` | — | Preferred effort (`low` through `ultra`), meaningful only with `injectionModel`. |
@@ -25,7 +26,7 @@ routes, and limits delegated work.
 | `agentTaskRecovery?` | `object` | — | Experimental opt-in recovery for backend-encrypted v2 tasks sent to routed providers. Disabled unless `enabled: true`; see [Encrypted v2 task recovery](#encrypted-v2-task-recovery). |
 
 Manage the surface with the dashboard or
-`ocx v2 status|on|off|mode <v1|default|v2>|threads <n>|mode-hint <text|--clear>`.
+`ocx v2 status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|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.

gui/src/i18n/de.ts

@@ -503,7 +503,9 @@ export const de: Record<TKey, string> = {
   "models.v2ModeDesc_v1": "Alle Modelle → v1-Oberfläche",
   "models.v2ModeDesc_default": "Upstream-Standard (sol/terra=v2, luna=v1)",
   "models.v2ModeDesc_v2": "Alle Modelle → v2-Oberfläche",
-  "models.v2Help": "Steuert die Multi-Agent-Oberfläche für alle Modelle.\n\nv1: Klassischer Single-Thread-Agent. Jedes Modell nutzt die v1-Collab-Oberfläche.\nbase: Upstream-Standard — sol/terra nutzen v2, luna v1, andere folgen dem Codex-Feature-Flag.\nv2: Multi-Thread-Agent mit spawn_agent. Jedes Modell nutzt die v2-Collab-Oberfläche.\n\nÄnderungen gelten für neue Sitzungen.",
+  "models.keepNativeOnV1": "ChatGPT auf v1 lassen",
+  "models.keepNativeOnV1Hint": "ChatGPT-native Eltern verschlüsseln v2-Kindaufgaben — Grok und Claude können sie nicht lesen. An lassen, wenn Sol/Terra weiterhin geroutete Modelle starten sollen. Geroutete Eltern bleiben auf v2.",
+  "models.v2Help": "Steuert die Multi-Agent-Oberfläche für alle Modelle.\n\nv1: Klassischer Single-Thread-Agent. Jedes Modell nutzt die v1-Collab-Oberfläche.\nbase: Upstream-Standard — sol/terra nutzen v2, luna v1, andere folgen dem Codex-Feature-Flag.\nv2: Multi-Thread-Agent mit spawn_agent. Jedes Modell nutzt die v2-Collab-Oberfläche.\n\nUnter v2 lässt „ChatGPT auf v1 lassen“ Sol/Terra auf v1, damit sie weiter Grok oder Claude starten können. ChatGPT verschlüsselt v2-Kindaufgaben; geroutete Modelle können sie nicht lesen. Geroutete Eltern bleiben auf v2.\n\nÄnderungen gelten für neue Sitzungen.",
   "dash.multiAgent": "Sub-Agent",
   "models.v2Conflict": "[agents] max_threads ist gesetzt — codex verweigert den Start; entferne es aus config.toml",
   "models.v2Applied": "Sub-Agent-Modus aktualisiert — gilt für neue Sitzungen (Codex-App neu starten, um die Auswahl zu aktualisieren)",

gui/src/i18n/en.ts

@@ -528,7 +528,9 @@ export const en = {
   "models.v2ModeDesc_v1": "All models → v1 surface",
   "models.v2ModeDesc_default": "Upstream defaults (sol/terra=v2, luna=v1)",
   "models.v2ModeDesc_v2": "All models → v2 surface",
-  "models.v2Help": "Controls the multi-agent surface for all models.\n\nv1: Classic single-thread agent. Every model uses the v1 collab surface.\nbase: Upstream defaults — sol/terra use v2, luna uses v1, others follow the codex feature flag.\nv2: Multi-thread agent with spawn_agent. Every model uses the v2 collab surface.\n\nChanges apply to new sessions.",
+  "models.keepNativeOnV1": "Keep ChatGPT on v1",
+  "models.keepNativeOnV1Hint": "ChatGPT encrypts v2 child tasks only when a ChatGPT-native parent stays on v2, so Grok and Claude cannot read them. Turn this on to keep Sol/Terra on v1 and avoid that encryption. Routed parents keep v2.",
+  "models.v2Help": "Controls the multi-agent surface for all models.\n\nv1: Classic single-thread agent. Every model uses the v1 collab surface.\nbase: Upstream defaults — sol/terra use v2, luna uses v1, others follow the codex feature flag.\nv2: Multi-thread agent with spawn_agent. Every model uses the v2 collab surface.\n\nOn v2, Keep ChatGPT on v1 leaves Sol/Terra on the v1 surface so they can still spawn Grok or Claude. ChatGPT encrypts v2 child tasks; routed models cannot read them. Routed parents stay on v2.\n\nChanges apply to new sessions.",
   "dash.multiAgent": "Sub-agent",
   "models.v2Conflict": "[agents] max_threads is set — codex will refuse to start; remove it from config.toml",
   "models.v2Applied": "Sub-agent mode updated — applies to new sessions (restart the Codex app to refresh the picker)",

gui/src/i18n/fr.ts

@@ -513,7 +513,9 @@ export const fr: Record<TKey, string> = {
   "models.v2ModeDesc_v1": "Tous les modèles → interface v1",
   "models.v2ModeDesc_default": "Valeurs par défaut en amont (sol/terra=v2, luna=v1)",
   "models.v2ModeDesc_v2": "Tous les modèles → interface v2",
-  "models.v2Help": "Contrôle l’interface multi-agent pour tous les modèles.\n\nv1 : agent classique à fil unique. Tous les modèles utilisent l’interface collab v1.\nbase : valeurs par défaut en amont — sol/terra utilisent v2, luna utilise v1 et les autres suivent l’indicateur de fonctionnalité codex.\nv2 : agent multifil avec spawn_agent. Tous les modèles utilisent l’interface collab v2.\n\nLes modifications s’appliquent aux nouvelles sessions.",
+  "models.keepNativeOnV1": "Garder ChatGPT sur v1",
+  "models.keepNativeOnV1Hint": "ChatGPT chiffre les tâches enfants v2 uniquement lorsqu’un parent natif ChatGPT reste sur v2, de sorte que Grok et Claude ne peuvent pas les lire. Activez cette option pour garder Sol/Terra sur v1 et éviter ce chiffrement. Les parents routés restent sur v2.",
+  "models.v2Help": "Contrôle l’interface multi-agent pour tous les modèles.\n\nv1 : agent classique à fil unique. Tous les modèles utilisent l’interface collab v1.\nbase : valeurs par défaut en amont — sol/terra utilisent v2, luna utilise v1 et les autres suivent l’indicateur de fonctionnalité codex.\nv2 : agent multifil avec spawn_agent. Tous les modèles utilisent l’interface collab v2.\n\nEn v2, « Garder ChatGPT sur v1 » laisse Sol/Terra sur l’interface v1 afin qu’ils puissent encore lancer Grok ou Claude. ChatGPT chiffre les tâches enfants v2 ; les modèles routés ne peuvent pas les lire. Les parents routés restent sur v2.\n\nLes modifications s’appliquent aux nouvelles sessions.",
   "dash.multiAgent": "Sous-agent",
   "models.v2Conflict": "[agents] max_threads est défini — codex refusera de démarrer ; supprimez-le de config.toml",
   "models.v2Applied": "Mode sous-agent mis à jour — s’applique aux nouvelles sessions (redémarrez l’application Codex pour actualiser le sélecteur)",

gui/src/i18n/ja.ts

@@ -511,7 +511,9 @@ export const ja: Record<TKey, string> = {
   "models.v2ModeDesc_v1": "すべてのモデル → v1 サーフェス",
   "models.v2ModeDesc_default": "上流のデフォルト(sol/terra=v2、luna=v1)",
   "models.v2ModeDesc_v2": "すべてのモデル → v2 サーフェス",
-  "models.v2Help": "すべてのモデルのマルチエージェントサーフェスを制御します。\n\nv1: クラシックな単一スレッドエージェント。すべてのモデルが v1 コラボサーフェスを使います。\nベース: 上流のデフォルト — sol/terra は v2、luna は v1、それ以外は codex のフィーチャーフラグに従います。\nv2: spawn_agent を備えたマルチスレッドエージェント。すべてのモデルが v2 コラボサーフェスを使います。\n\n変更は新規セッションに適用されます。",
+  "models.keepNativeOnV1": "ChatGPT を v1 のまま",
+  "models.keepNativeOnV1Hint": "ChatGPT ネイティブの親は v2 子タスクを暗号化するため、Grok や Claude は読めません。Sol/Terra から routed モデルを spawn するならオンのまま。routed 親は v2 のままです。",
+  "models.v2Help": "すべてのモデルのマルチエージェントサーフェスを制御します。\n\nv1: クラシックな単一スレッドエージェント。すべてのモデルが v1 コラボサーフェスを使います。\nベース: 上流のデフォルト — sol/terra は v2、luna は v1、それ以外は codex のフィーチャーフラグに従います。\nv2: spawn_agent を備えたマルチスレッドエージェント。すべてのモデルが v2 コラボサーフェスを使います。\n\nv2 では「ChatGPT を v1 のまま」にすると Sol/Terra が v1 に留まり、Grok や Claude を spawn できます。ChatGPT は v2 子タスクを暗号化するため routed モデルは読めません。routed 親は v2 のままです。\n\n変更は新規セッションに適用されます。",
   "dash.multiAgent": "サブエージェント",
   "models.v2Conflict": "[agents] max_threads が設定されています — codex は起動を拒否します; config.toml から削除してください",
   "models.v2Applied": "サブエージェントモードを更新しました — 新規セッションに適用(ピッカーを更新するには Codex アプリを再起動)",

gui/src/i18n/ko.ts

@@ -513,7 +513,9 @@ export const ko: Record<TKey, string> = {
   "models.v2ModeDesc_v1": "전 모델 → v1 서피스",
   "models.v2ModeDesc_default": "업스트림 기본값 (sol/terra=v2, luna=v1)",
   "models.v2ModeDesc_v2": "전 모델 → v2 서피스",
-  "models.v2Help": "모든 모델의 멀티에이전트 서피스를 제어합니다.\n\nv1: 단일 스레드 에이전트. 모든 모델이 v1 서피스를 사용합니다.\nbase: 업스트림 기본값 — sol/terra는 v2, luna는 v1, 나머지는 codex 플래그를 따릅니다.\nv2: 멀티 스레드 에이전트(spawn_agent). 모든 모델이 v2 서피스를 사용합니다.\n\n새 세션부터 적용됩니다.",
+  "models.keepNativeOnV1": "ChatGPT는 v1 유지",
+  "models.keepNativeOnV1Hint": "ChatGPT 네이티브 부모는 v2 자식 작업을 암호화해서 Grok/Claude가 읽지 못합니다. Sol/Terra가 routed 모델을 spawn해야 하면 켜 두세요. routed 부모는 v2를 유지합니다.",
+  "models.v2Help": "모든 모델의 멀티에이전트 서피스를 제어합니다.\n\nv1: 단일 스레드 에이전트. 모든 모델이 v1 서피스를 사용합니다.\nbase: 업스트림 기본값 — sol/terra는 v2, luna는 v1, 나머지는 codex 플래그를 따릅니다.\nv2: 멀티 스레드 에이전트(spawn_agent). 모든 모델이 v2 서피스를 사용합니다.\n\nv2에서 ChatGPT는 v1 유지를 켜면 Sol/Terra가 v1에 남아 Grok이나 Claude를 spawn할 수 있습니다. ChatGPT는 v2 자식 작업을 암호화하므로 routed 모델은 읽지 못합니다. routed 부모는 v2를 유지합니다.\n\n새 세션부터 적용됩니다.",
   "models.v2DocsLink": "v1 / v2가 뭔가요?",
   "dash.multiAgent": "서브에이전트",
   "models.v2Conflict": "[agents] max_threads가 남아 있어 codex가 부팅을 거부합니다 — config.toml에서 제거하세요",

gui/src/i18n/ru.ts

@@ -516,7 +516,9 @@ export const ru: Record<TKey, string> = {
   "models.v2ModeDesc_v1": "Все модели → поверхность v1",
   "models.v2ModeDesc_default": "Вышестоящие значения по умолчанию (sol/terra=v2, luna=v1)",
   "models.v2ModeDesc_v2": "Все модели → поверхность v2",
-  "models.v2Help": "Управляет мультиагентной поверхностью для всех моделей.\n\nv1: Классический однопоточный агент. Каждая модель использует поверхность взаимодействия v1.\nbase: Вышестоящие значения по умолчанию — sol/terra используют v2, luna использует v1, остальные следуют функциональному флагу codex.\nv2: Многопоточный агент со spawn_agent. Каждая модель использует поверхность взаимодействия v2.\n\nИзменения применяются к новым сессиям.",
+  "models.keepNativeOnV1": "Оставить ChatGPT на v1",
+  "models.keepNativeOnV1Hint": "Нативные родители ChatGPT шифруют дочерние задачи v2 — Grok и Claude их не читают. Оставьте включённым, если Sol/Terra должны порождать routed-модели. Routed-родители остаются на v2.",
+  "models.v2Help": "Управляет мультиагентной поверхностью для всех моделей.\n\nv1: Классический однопоточный агент. Каждая модель использует поверхность взаимодействия v1.\nbase: Вышестоящие значения по умолчанию — sol/terra используют v2, luna использует v1, остальные следуют функциональному флагу codex.\nv2: Многопоточный агент со spawn_agent. Каждая модель использует поверхность взаимодействия v2.\n\nНа v2 «Оставить ChatGPT на v1» оставляет Sol/Terra на v1, чтобы они могли порождать Grok или Claude. ChatGPT шифрует дочерние задачи v2 — routed-модели их не читают. Routed-родители остаются на v2.\n\nИзменения применяются к новым сессиям.",
   "dash.multiAgent": "Подагент",
   "models.v2Conflict": "Задан [agents] max_threads — codex откажется запускаться; удалите его из config.toml",
   "models.v2Applied": "Режим подагента обновлён — применяется к новым сессиям (перезапустите приложение Codex, чтобы обновить селектор моделей)",

gui/src/i18n/tr.ts

@@ -519,7 +519,9 @@ export const tr: Record<TKey, string> = {
   "models.v2ModeDesc_v1": "Tüm modeller → v1 yüzeyi",
   "models.v2ModeDesc_default": "Yukarı akış varsayılanları",
   "models.v2ModeDesc_v2": "Tüm modeller → v2 yüzeyi",
-  "models.v2Help": "v1 alt ajanları birincil modelle sınırlandırır; base standart ajan sınırlarını devralır; v2 tam çoklu ajan orkestrasyonunu etkinleştirir.",
+  "models.keepNativeOnV1": "ChatGPT v1'de kalsın",
+  "models.keepNativeOnV1Hint": "ChatGPT yerel ebeveynleri v2 çocuk görevlerini şifreler; Grok ve Claude okuyamaz. Sol/Terra yönlendirilmiş modelleri spawn edecekse açık bırakın. Yönlendirilmiş ebeveynler v2'de kalır.",
+  "models.v2Help": "v1 alt ajanları birincil modelle sınırlandırır; taban standart ajan sınırlarını devralır; v2 tam çoklu ajan orkestrasyonunu etkinleştirir.\n\nv2'de ChatGPT v1'de kalsın, Sol/Terra'yı v1'de bırakır; böylece Grok veya Claude spawn edebilirler. ChatGPT v2 çocuk görevlerini şifreler; yönlendirilmiş modeller okuyamaz. Yönlendirilmiş ebeveynler v2'de kalır.\n\nDeğişiklikler yeni oturumlara uygulanır.",
   "dash.multiAgent": "Alt Ajan",
   "models.v2Conflict": "[agents] max_threads ayarlanmış — config.toml dosyasından kaldırın",
   "models.v2Applied": "Çoklu ajan modu güncellendi. Yeni oturumlar bu modu kullanacaktır; model seçiciyi yenilemek için Codex uygulamasını yeniden başlatın.",

gui/src/i18n/zh-TW.ts

@@ -395,7 +395,9 @@ export const zhTW: Record<TKey, string> = {
   "models.v2ModeDesc_v1": "所有模型 → v1 介面",
   "models.v2ModeDesc_default": "上游預設值 (sol/terra=v2, luna=v1)",
   "models.v2ModeDesc_v2": "所有模型 → v2 介面",
-  "models.v2Help": "控制所有模型的多代理介面。\n\nv1: 經典單執行緒代理。所有模型使用 v1 協作介面。\nbase: 上游預設值 — sol/terra 使用 v2，luna 使用 v1，其餘跟隨 codex 功能標誌。\nv2: 多執行緒代理（spawn_agent）。所有模型使用 v2 協作介面。\n\n更改在新會話中生效。",
+  "models.keepNativeOnV1": "ChatGPT 維持 v1",
+  "models.keepNativeOnV1Hint": "ChatGPT 原生父代理會加密 v2 子任務，Grok/Claude 無法讀取。若 Sol/Terra 仍需派發路由模型，請保持開啟。路由父代理仍使用 v2。",
+  "models.v2Help": "控制所有模型的多代理介面。\n\nv1: 經典單執行緒代理。所有模型使用 v1 協作介面。\nbase: 上游預設值 — sol/terra 使用 v2，luna 使用 v1，其餘跟隨 codex 功能標誌。\nv2: 多執行緒代理（spawn_agent）。所有模型使用 v2 協作介面。\n\n在 v2 下，「ChatGPT 維持 v1」會讓 Sol/Terra 留在 v1，以便繼續派發 Grok 或 Claude。ChatGPT 會加密 v2 子任務，路由模型無法讀取；路由父代理仍留在 v2。\n\n更改在新會話中生效。",
   "dash.multiAgent": "子代理",
   "models.v2Conflict": "[agents] max_threads 仍存在 — codex 將拒絕啟動，請從 config.toml 移除",
   "models.v2Applied": "子代理模式已更新 — 新會話生效（重新啟動 Codex 應用以重新整理選擇器）",