fix(subagent): move per-role model fallback into opencodex config (#1190)

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

@@ -86,9 +86,17 @@ write. External provider managers and user-owned root routing also remain author
 For a spawned worker, opencodex builds this priority order:
 
 1. The requested primary model.
-2. The role's `model_fallback` list from its `$CODEX_HOME/agents/*.toml` definition.
+2. A per-model chain from `subagentModelFallbackByModel` in opencodex config, keyed by
+   the requested primary model.
 3. The global `subagentModelFallback` list in opencodex config.
 
+Per-role fallback chains belong in opencodex config, not in
+`$CODEX_HOME/agents/*.toml`. Codex 0.146+ strictly deserializes agent role files and
+rejects `model_fallback` as an unknown field, which skips the entire role definition
+(#1190). opencodex can still read a legacy `model_fallback` line from the TOML for
+backwards compatibility, but `ocx doctor` warns about it and Codex itself will ignore
+the affected role.
+
 Duplicate model ids are removed while preserving the first occurrence. During selection, opencodex
 skips candidates that are disabled, unroutable, backed by a disabled provider, marked unhealthy,
 inside a cooldown, missing a usable pooled Codex account, or beyond the configured quota threshold.

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

@@ -65,9 +65,11 @@ v1 では、opencodex は、`max` または `ultra` の取り組みでアップ
 生成されたワーカーの場合、opencodex は次の優先順位を構築します。
 
 1. 要求されたプライマリ モデル。
-2. `$CODEX_HOME/agents/*.toml` 定義からのロールの `model_fallback` リスト。
+2. opencodex 構成内の `subagentModelFallbackByModel` によるモデル単位のチェーン（要求されたプライマリ モデルがキー）。
 3. opencodex 構成内のグローバル `subagentModelFallback` リスト。
 
+ロール単位のフォールバックチェーンは、`$CODEX_HOME/agents/*.toml` ではなく opencodex 構成に置く必要があります。Codex 0.146+ はエージェントロールファイルを厳密に逆シリアル化し、`model_fallback` を未知フィールドとして拒否するため、ロール定義全体がスキップされます（#1190）。opencodex は後方互換性のために TOML 内のレガシー `model_fallback` 行を引き続き読み取れますが、`ocx doctor` が警告を出し、Codex 自体は影響を受けるロールを無視します。
+
 重複するモデル ID は、最初に出現したモデル ID を保持しながら削除されます。選択中、opencodex は、無効になっている、ルーティングできない、無効なプロバイダーによってサポートされている、異常とマークされている、クールダウン中、使用可能なプールされた Codex アカウントがない、または設定されたクォータしきい値を超えている候補をスキップします。可用性プローブは `subagentModelFallbackPollMs` に対してキャッシュされます (デフォルトでは 60 秒)。
 
 フォールバックでは、互換性のない暗号化タスクは読み取り可能になりません。子タスクが ChatGPT 用に暗号化されている場合、外部モデルがチェーンの前の方に表示されている場合でも、選択は正規のネイティブ ChatGPT ターゲットに制限されます。

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

@@ -17,6 +17,7 @@ description: マルチエージェント サーフェス、委任ガイダンス
 | `multiAgentGuidanceEnabled?` | `boolean` | `true` | opencodex が作成した v1/v2 開発者ガイダンスのみを制御します。ネイティブ エージェントのデフォルト、ツール、ルーティング、ロスター、またはエフォート キャップは変更されません。 |
 | `syncCodexSubagentDefaults?` | `boolean` | `false` |同期/再起動中に、Codex のネイティブ デフォルトとして `injectionModel` およびオプションの `injectionEffort` を書き込むようにオプトインします。 `injectionModel`が必要です。 |
 | `subagentModelFallback?` | `string[]` | `[]` |生成された子ターンの優先順位付きグローバル フォールバック モデル。 |
+| `subagentModelFallbackByModel?` | `Record<string, string[]>` | `{}` | 要求されたプライマリ モデル id をキーとするモデル単位のフォールバックチェーン。ロール単位のフォールバックメタデータの推奨場所です。Codex の agent TOML に `model_fallback` を書くと Codex 0.146+ がロールをスキップします（#1190）。 |
 | `subagentModelFallbackPollMs?` | `number` | `60000` |可用性プローブのキャッシュ間隔。 1000 ミリ秒未満の値はデフォルトに戻ります。 |
 | `effortCap?` | `string` | — | v2 のメイン ターンとマークされた子ターンの条件を満たすためのハード シーリング。 `low` ～ `ultra` を受け入れます。 |
 | `subagentEffortCap?` | `string` | — |スポーンされた子のターンのみの追加の上限。両方の上限が適用される場合は、低い方が優先されます。 |
@@ -44,9 +45,14 @@ V1 ガイダンスは、`max` または `ultra` でのみプロアクティブ 
 生成された子のフォールバック順序は次のとおりです。
 
 1. 要求されたプライマリ モデル。
-2. ロールレベル `model_fallback` から `$CODEX_HOME/agents/*.toml`;それから
+2. `subagentModelFallbackByModel` によるモデル単位のチェーン（プライマリ モデルがキー）;それから
 3. グローバル `subagentModelFallback` エントリ。
 
+ロール単位のフォールバックチェーンは opencodex 構成に置く必要があります。`model_fallback` を
+`$CODEX_HOME/agents/*.toml` に書くと、Codex 0.146+ が未知フィールドとしてロールファイル全体を
+拒否し、ロールをスキップします（#1190）。TOML 内のレガシー `model_fallback` 行は後方互換性の
+ために引き続き読み取られますが、`ocx doctor` がそれをフラグ付けします。
+
 opencodex は、無効、ルーティング不能、異常、冷却期間、またはクォータしきい値の候補をスキップします。可用性スナップショットは `subagentModelFallbackPollMs` に対してキャッシュされます。暗号化された子タスクは、チェーンを正規のネイティブ ChatGPT ターゲットに制限できます。暗号化されたペイロードを読み取ることができる人がいない場合、読み取り不可能な暗号文が別の場所にルーティングされる代わりに、リクエストは失敗します。
 
 ```json
@@ -57,6 +63,9 @@ opencodex は、無効、ルーティング不能、異常、冷却期間、ま
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
   "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallbackByModel": {
+    "gpt-5.5": ["gpt-5.4-mini"]
+  },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
 }

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

@@ -65,9 +65,11 @@ v1에서는 opencodex가 `max` 또는 `ultra` 추론 강도에서만 업스트
 스폰된 작업자에 대해 opencodex는 다음 우선순위를 적용합니다.
 
 1. 요청한 기본 모델
-2. 역할의 `$CODEX_HOME/agents/*.toml` 정의에 있는 `model_fallback` 목록
+2. opencodex 설정의 `subagentModelFallbackByModel`에 있는 모델별 체인 (요청한 기본 모델이 키)
 3. opencodex 설정의 전역 `subagentModelFallback` 목록
 
+역할별 폴백 체인은 `$CODEX_HOME/agents/*.toml`이 아니라 opencodex 설정에 두어야 합니다. Codex 0.146+는 에이전트 역할 파일을 엄격하게 역직렬화하며 `model_fallback`을 알 수 없는 필드로 거부해 역할 정의 전체를 건너뜁니다 (#1190). opencodex는 하위 호환성을 위해 TOML의 기존 `model_fallback` 줄을 계속 읽을 수 있지만, `ocx doctor`가 경고하며 Codex 자체는 해당 역할을 무시합니다.
+
 중복 모델 id는 첫 번째 출현을 유지한 채 제거합니다. 선택 과정에서 opencodex는 비활성화된 후보, 라우팅 불가 후보, 비활성화된 프로바이더가 받쳐주는 후보, unhealthy로 표시된 후보, cooldown 중인 후보, 사용할 수 있는 pooled Codex 계정이 없는 후보, 또는 설정된 quota 임계치를 넘는 후보를 건너뜁니다. 가용성 프로브는 기본값 60초인 `subagentModelFallbackPollMs` 동안 캐시됩니다.
 
 폴백이 호환되지 않는 암호화 작업을 읽을 수 있게 만들어 주지는 않습니다. 자식 작업이 ChatGPT용으로 암호화되어 있으면, 체인 앞쪽에 외부 모델이 있더라도 선택은 정규 네이티브 ChatGPT 대상만 허용됩니다.

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

@@ -17,6 +17,7 @@ description: 멀티 에이전트 표면, 위임 안내, 선호 모델, 대체 
 | `multiAgentGuidanceEnabled?` | `boolean` | `true` | opencodex가 작성하는 v1/v2 개발자 안내만 제어합니다. 네이티브 에이전트 기본값, 도구, 라우팅, 로스터, 노력 상한은 바꾸지 않습니다. |
 | `syncCodexSubagentDefaults?` | `boolean` | `false` | 동기화 또는 재시작 시 `injectionModel`과 선택적 `injectionEffort`를 Codex의 네이티브 기본값으로 기록하도록 선택합니다. `injectionModel`이 필요합니다. |
 | `subagentModelFallback?` | `string[]` | `[]` | 생성된 하위 턴에 적용되는 전역 대체 모델 우선순위 목록입니다. |
+| `subagentModelFallbackByModel?` | `Record<string, string[]>` | `{}` | 요청한 기본 모델 id를 키로 하는 모델별 대체 체인입니다. 역할별 대체 메타데이터의 지원 위치입니다. Codex agent TOML에 `model_fallback`을 쓰면 Codex 0.146+가 역할을 건너뜁니다 (#1190). |
 | `subagentModelFallbackPollMs?` | `number` | `60000` | 사용 가능성 검사 캐시 간격입니다. 1000 ms 미만의 값은 기본값으로 돌아갑니다. |
 | `effortCap?` | `string` | — | 자격을 갖춘 v2 메인 턴과 표시된 생성 하위 턴에 대한 하드 상한입니다. `low`부터 `ultra`까지 허용합니다. |
 | `subagentEffortCap?` | `string` | — | 생성된 하위 턴에만 적용되는 추가 상한입니다. 두 상한이 모두 적용되면 더 낮은 값이 이깁니다. |
@@ -44,9 +45,14 @@ V1 안내는 `max` 또는 `ultra`에서만 선제 텍스트로 제공됩니다.
 생성된 하위 작업의 대체 순서는 다음과 같습니다.
 
 1. 요청된 기본 모델
-2. `$CODEX_HOME/agents/*.toml`의 역할 수준 `model_fallback`
+2. `subagentModelFallbackByModel`의 모델별 체인 (기본 모델이 키)
 3. 전역 `subagentModelFallback` 항목
 
+역할별 폴백 체인은 opencodex 설정에 있어야 합니다. `model_fallback`을
+`$CODEX_HOME/agents/*.toml`에 쓰면 Codex 0.146+가 알 수 없는 필드로 역할 파일 전체를
+거부하고 역할을 건너뜁니다 (#1190). TOML의 기존 `model_fallback` 줄은 하위 호환성을 위해
+계속 읽히지만 `ocx doctor`가 이를 표시합니다.
+
 opencodex는 비활성, 라우팅 불가, 비정상, 쿨다운 중, 또는 할당량 임계값에 걸린 후보를 건너뜁니다. 사용 가능성 스냅샷은 `subagentModelFallbackPollMs` 동안 캐시됩니다. 암호화된 하위 작업은 체인을 정규 네이티브 ChatGPT 대상으로만 제한할 수 있습니다. 어떤 대상도 암호화된 페이로드를 읽을 수 없으면, 읽을 수 없는 암호문을 다른 곳으로 라우팅하는 대신 요청이 실패합니다.
 
 ```json
@@ -57,6 +63,9 @@ opencodex는 비활성, 라우팅 불가, 비정상, 쿨다운 중, 또는 할
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
   "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallbackByModel": {
+    "gpt-5.5": ["gpt-5.4-mini"]
+  },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
 }

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

@@ -18,6 +18,7 @@ routes, and limits delegated work.
 | `multiAgentGuidanceEnabled?` | `boolean` | `true` | Controls only opencodex-authored v1/v2 developer guidance; it does not change native agent defaults, tools, routing, rosters, or effort caps. |
 | `syncCodexSubagentDefaults?` | `boolean` | `false` | Opt into writing `injectionModel` and optional `injectionEffort` as Codex's native defaults during sync/restart. Requires `injectionModel`. |
 | `subagentModelFallback?` | `string[]` | `[]` | Priority-ordered global fallback models for spawned child turns. |
+| `subagentModelFallbackByModel?` | `Record<string, string[]>` | `{}` | Per-primary-model fallback chains, keyed by the requested primary model id. This is the supported home for per-role fallback metadata; `model_fallback` inside Codex agent TOML makes Codex 0.146+ skip the role (#1190). |
 | `subagentModelFallbackPollMs?` | `number` | `60000` | Availability-probe cache interval. Values below 1000 ms fall back to the default. |
 | `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. |
@@ -73,9 +74,14 @@ created Codex tasks and do not cause delegation by themselves.
 Spawned-child fallback order is:
 
 1. the requested primary model;
-2. role-level `model_fallback` from `$CODEX_HOME/agents/*.toml`; then
+2. per-model chains from `subagentModelFallbackByModel` (keyed by the primary model); then
 3. global `subagentModelFallback` entries.
 
+Per-role fallback chains must live in opencodex config. Writing `model_fallback` into
+`$CODEX_HOME/agents/*.toml` makes Codex 0.146+ reject the whole role file as an unknown
+field and skip the role (#1190). A legacy `model_fallback` line in the TOML is still
+read for backwards compatibility, but `ocx doctor` flags it.
+
 opencodex skips disabled, unroutable, unhealthy, cooling-down, or quota-threshold candidates. The
 availability snapshot is cached for `subagentModelFallbackPollMs`. Encrypted child tasks can restrict
 the chain to canonical native ChatGPT targets; if none can read the encrypted payload, the request
@@ -89,6 +95,9 @@ fails instead of routing unreadable ciphertext elsewhere.
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
   "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallbackByModel": {
+    "gpt-5.5": ["gpt-5.4-mini"]
+  },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
 }

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

@@ -95,9 +95,15 @@ opencodex владеет активной маршрутизацией Codex, sy
 Для порождённого воркера opencodex строит такой порядок приоритета:
 
 1. Запрошенная основная модель.
-2. Список `model_fallback` роли из её определения `$CODEX_HOME/agents/*.toml`.
+2. Модельная цепочка из `subagentModelFallbackByModel` в конфигурации opencodex, ключ — запрошенная основная модель.
 3. Глобальный список `subagentModelFallback` в конфигурации opencodex.
 
+Модельные цепочки fallback для ролей должны храниться в конфигурации opencodex, а не в
+`$CODEX_HOME/agents/*.toml`. Codex 0.146+ строго десериализует файлы ролей агента и отвергает
+`model_fallback` как неизвестное поле, из-за чего пропускается всё определение роли (#1190).
+opencodex по-прежнему читает устаревшую строку `model_fallback` из TOML для обратной
+совместимости, но `ocx doctor` предупреждает о ней, а сам Codex игнорирует затронутую роль.
+
 Дубликаты id моделей удаляются с сохранением первого вхождения. При выборе opencodex пропускает
 кандидатов, которые отключены, немаршрутизируемы, опираются на отключённого провайдера, помечены
 как unhealthy, находятся в cooldown, не имеют доступного pooled-аккаунта Codex или вышли за

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

@@ -18,6 +18,7 @@ description: Multi-agent surface, guidance при делегировании, pr
 | `multiAgentGuidanceEnabled?` | `boolean` | `true` | Управляет только developer-guidance, написанным самим opencodex, для v1/v2; не меняет native default'ы агентов, tools, routing, roster'ы и effort cap'ы. |
 | `syncCodexSubagentDefaults?` | `boolean` | `false` | Разрешает записывать `injectionModel` и, при наличии, `injectionEffort` как native default'ы Codex при sync/restart. Требует `injectionModel`. |
 | `subagentModelFallback?` | `string[]` | `[]` | Глобальные fallback-модели для порождённых child-turn'ов в порядке приоритета. |
+| `subagentModelFallbackByModel?` | `Record<string, string[]>` | `{}` | Модельные цепочки fallback по ключу запрошенной основной модели. Это поддерживаемое место для per-role метаданных fallback; поле `model_fallback` в `$CODEX_HOME/agents/*.toml` поддерживается только как legacy и заставляет Codex 0.146+ пропустить роль (#1190). |
 | `subagentModelFallbackPollMs?` | `number` | `60000` | Интервал кэша для availability probe. Значения ниже 1000 ms возвращаются к дефолту. |
 | `effortCap?` | `string` | — | Жёсткий потолок effort для qualifying v2 main-turn'ов и помеченных spawned-child turn'ов. Принимает `low`–`ultra`. |
 | `subagentEffortCap?` | `string` | — | Дополнительный потолок только для spawned-child turn'ов. Если применимы оба cap'а, выигрывает более низкий. |
@@ -69,9 +70,14 @@ user-owned target field'ы считаются конфликтом и сохра
 Порядок fallback для spawned-child такой:
 
 1. запрошенная основная модель;
-2. role-level `model_fallback` из `$CODEX_HOME/agents/*.toml`; затем
+2. модельные цепочки из `subagentModelFallbackByModel` (ключ — основная модель); затем
 3. глобальные записи `subagentModelFallback`.
 
+Модельные цепочки fallback для ролей должны храниться в конфигурации opencodex. Запись
+`model_fallback` в `$CODEX_HOME/agents/*.toml` заставляет Codex 0.146+ отклонить весь файл
+роли как неизвестное поле и пропустить роль (#1190). Устаревшая строка `model_fallback` в TOML
+по-прежнему читается для обратной совместимости, но `ocx doctor` помечает её.
+
 opencodex пропускает кандидатов, которые отключены, не маршрутизируются, unhealthy, находятся в
 cooldown либо уже достигли порога quota. Availability-снимок кэшируется на
 `subagentModelFallbackPollMs`. Шифрованные child-task'и могут ограничить цепочку каноническими
@@ -86,6 +92,9 @@ native ChatGPT-target'ами; если ни одна из них не может
   "injectionEffort": "high",
   "syncCodexSubagentDefaults": true,
   "subagentModelFallback": ["gpt-5.4-mini"],
+  "subagentModelFallbackByModel": {
+    "gpt-5.5": ["gpt-5.4-mini"]
+  },
   "subagentModelFallbackPollMs": 60000,
   "subagentEffortCap": "high"
 }