docs(sub-agents): describe v2 fork override rule as a prompt convention

[parkjs101]

What

Describe the v2 full-history-fork / model-override interaction as a prompt-level convention instead of a runtime rejection, and fix the FAQ's causal explanation.

Why

The wording came from Codex's own v2 usage hint (openai/codex#32749), which still says full-history forks "do not accept overrides". That was accurate when openai/codex#20077 was filed, but openai/codex#37252 removed the rejection: the current v2 spawn handler calls apply_requested_spawn_agent_model_overrides unconditionally, and is_full_history_fork now gates only the role branch.

The FAQ entry was also misdiagnosing the cause. A child uses the parent model whenever model is omitted -- the default for every fork mode, not something a full-history fork triggers. Readers following the old text switch fork_turns and still see the parent model because they never passed model.

Changes

• Reframe the guidance paragraph as a convention, with the #20077 -> #37252 history.
• Rewrite the FAQ answer around the real cause (model omitted).
• Add the schema-exposure case: features.multi_agent_v2.expose_spawn_agent_model_overrides and GPT-5.6 Sol cannot specify subagent models, forcing all subagents to also be Sol instances openai/codex#31814 for ChatGPT-native parents.
• Apply the same corrections to ko/ja/zh-cn/zh-tw/ru/fr/tr; zh-tw also had two stale sentences outside the main paragraph (the intro tip and the mode table).

Testing

Docs-only change; no runtime behavior is affected. Verified against upstream openai/codex@main sources on 2026-08-21.

Notes

Draft: filed openai/codex#20077 comment asking whether the remaining usage-hint wording is intentional policy or leftover text. If upstream softens the hint, this page can cite that instead.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cb9de27c-8ad1-4514-a395-f7ce6369034b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ All CI tests are green on my local testing.
• ⬜ I pushed my PR to the latest dev commit.
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

This PR stays in draft until every box above is ticked.

[Ingwannu]

The upstream correction is directionally useful, but this exact head is internally inconsistent with the shipped OpenCodex behavior and with other text on the same canonical page.

Blockers on d85cf057bf87f1a2a01f11cd0531008b55fda9a0:

1. The English intro note and v2 mode-table row still state that full-history forks reject overrides (docs-site/src/content/docs/guides/sub-agent-surface.md, near the top of the page), while the new paragraph says that rejection was removed. The same stale claims must be audited in every locale, not only zh-TW.
2. OpenCodex itself still injects the hard claim full-history forks reject overrides from src/server/responses/collaboration.ts, and src/server/effort-policy.ts documents the same invariant. A docs-only change cannot describe this solely as Codex built-in guidance while the shipped proxy continues to emit the old rule. Either update the actual injected guidance plus focused tests and all docs, or explicitly document that OpenCodex intentionally keeps the conservative prompt convention despite upstream runtime acceptance.
3. The PR body says it was verified on 2026-08-21, but today is 2026-08-20. Please correct or remove that future-dated verification claim.

Upstream source does support the narrow runtime fact: current multi_agents_v2/spawn.rs applies requested model/reasoning overrides before the full-history role branch, and openai/codex#37252 removed the full-history agent_type rejection. The blocker is synchronization and attribution across OpenCodex code/docs, not that core upstream observation.

Please update the canonical English page first, propagate the same meaning to every translation, run the required docs build, and then mark the PR ready.

[lidge-jun]

리뷰 · 우선순위 36 / 80

docs만임. draft. 런타임 코드 안 건드림. types.ts/config.ts 스플릿이랑도 상관 없음. 닫을 중복 아님.

내용은 맞음. 예전 FAQ가 full-history fork가 override를 거절한다고 적혀 있었는데, upstream openai/codex#37252가 그 거절을 뺐음. 지금 v2 spawn은 apply_requested_spawn_agent_model_overrides를 무조건 부름. is_full_history_fork는 롤 분기만 가림. 자식이 부모 모델을 쓰는 진짜 이유는 model을 안 넣어서임. fork_turns만 바꿔도 안 풀림.

스키마 노출 케이스(features.multi_agent_v2.expose_spawn_agent_model_overrides, openai/codex#31814)까지 적은 게 쓸모 있음. ko/ja/zh-cn/zh-tw/ru/fr/tr 같이 고침. zh-tw 인트로/모드 테이블 낡은 문장도 손봄.

draft로 둔 이유가 upstream usage-hint 코멘트 기다림임. 힌트가 정책이면 이 문서가 맞고, leftover면 인용만 바꾸면 됨. 코드 머지 급함 아님.

해결방안: upstream 답 오면 draft 해제하고 dev 머지. 런타임 가드를 이 PR에 넣지 말 것. 프롬프트 컨벤션 문서만 유지.

이 댓글은 grok-bot이 작성했습니다