docs(model-routing): explain Copilot CLI vs SDK mode, define allowed-models, add compiling examples

[Copilot]

The model routing guide had fallen behind main. It never said that cross-family sub-agents work only in Copilot SDK mode. It called allowed-models the request policy. It still listed threat detection as a limitation (fixed in #66670) and stated an old default AWF version. Only docs/src/content/docs/reference/model-routing.md changes.

CLI mode vs SDK mode (new section)

• Routing works in both modes. Only SDK mode (engine.copilot-sdk: true) supports sub-agents from a different model family in the same run, because it builds one provider per wire API (Fix Copilot SDK model routing and cross-family sub-agents #67509).
• In CLI mode, one wire API serves the whole session. A cross-family sub-agent fails, the main model redoes its work (BYOK: sub-agents always use the session's wire API, so a sub-agent on a model from the other family fails with a 400 copilot-cli#5103), and Select Copilot wire APIs from AWF metadata and surface model mismatches #67487 logs a warning at startup.
• What this means for mixed-family candidate pools:
  • SDK mode: any routing pick works with any declared sub-agent.
  • CLI mode: a mixed pool works without sub-agents. With sub-agents, every candidate must be in the sub-agents' family.
• The "Sub-agents" section and the last "Known limitations" entry now say the limit applies only to the Copilot engine in CLI mode. pi already runs sub-agents from both families.

allowed-models

• Now described as the router's candidate list for the main agent, which compiles to AWF routing.candidateModels.
• Declared sub-agent models are allowed automatically (Separate routing candidates from sub-agent model policy #66234). Listing one also makes it a main-agent candidate.
• The request policy is models.allowed / models.blocked, linked to the glossary's Model Policy entry. Both the candidates and the sub-agent models must satisfy it.

Examples and reference workflows

• CLI mode routes over a GPT pool with a GPT inline sub-agent.
• SDK mode routes over a mixed six-model pool with a Claude inline sub-agent:

  permissions:
    contents: read
    copilot-requests: write
  engine:
    id: copilot
    copilot-sdk: true
    model-routing:
      goal: cost
      mode: auto
      allowed-models: [gpt-5.4-mini, gpt-5.6-luna, gpt-5.6-sol, claude-haiku-4.5, claude-sonnet-5, claude-opus-5]

  The inline sub-agent (## agent:) sets model: claude-haiku-4.5.
• Links the three routing smokes:
  • smoke-copilot-routed.md routes over three models and has no sub-agents.
  • smoke-copilot-sdk-routed.md and smoke-pi-routed.md route over a single model only so their sub-agent checks stay deterministic. This is not a recommendation.

Other fixes

• Removed the stale "Threat detection is not routed" limitation. One sentence now says detection jobs aren't routed and use their configured detection model (Keep model routing out of threat detection jobs #66670).
• New "Steering notices" note:
  • With AWF v0.28.51 or later, gh aw audit lists budget and timeout notices as steering_notices (Emit AWF agentTimeout for literal timeouts and show delivered steering notices in audit/logs #67597).
  • The default AWF version is still v0.28.50, so these notices need an explicit sandbox.agent.version.
  • The note links the token steering section of sandbox.md.
• The AWF version is now worded as "gh-aw's default AWF version (currently v0.28.50)" instead of v0.28.37.

Compile results (required by the issue)

gh-aw was built from this branch, which is based on b04b77e (not the 7f713c7 named in the issue) and has no code changes. Both examples were compiled as scratch workflows:

$ gh-aw compile routing-cli
✓ Compiled 1 workflow: 1 succeeded, 0 warnings
$ gh-aw compile routing-sdk
✓ Compiled 1 workflow: 1 succeeded, 0 warnings

In both, the compiled candidateModels matches allowed-models. allowedModels was not checked.

The docs build (astro build) reports "All internal links are valid." The automated code review did not run (its model was unavailable), so the wording has not been reviewed yet. No checks were found failing on main because of this PR.

• Fixes Model routing guide: CLI vs Copilot SDK mode for mixed model families, what allowed-models means, and tested examples #67754

[Copilot]

🟡 Changes recommended

Two statements overstate CLI recovery behavior and smoke workflow validation coverage.

2 open findings

• Clarify delegation recovery is nondeterministic after a 400 error · New
• Avoid overstating smoke checks as validating every request endpoint · New

What changed in this PR

Updates the model-routing reference to match current routing behavior and observability.

Changes:

• Clarifies allowed-models and model policy semantics.
• Documents CLI versus SDK cross-family sub-agent behavior with examples.
• Refreshes AWF versions, smoke references, and steering notices.

File	Description
docs/​src/​content/​docs/​reference/​model-routing.md	Updates model-routing guidance, examples, limitations, and observability.

🧠 Review effort: Balanced

[github-actions]

✅ Test Quality Sentinel completed test quality analysis.

No test files were added or modified in this PR. Test Quality Sentinel skipped. PR #67755 only modifies docs/src/content/docs/reference/model-routing.md (a documentation file); no Go or JavaScript test files are in scope.

🧪 Test quality analysis by Test Quality Sentinel

[gh-aw-bot]

@copilot address the following outstanding work in one pass:

1. Update this branch with the latest main using make merge-main, resolving any conflicts and preserving the intended changes.
2. Review (docs/src/content/docs/reference/model-routing.md:77): The linked CLI issue does not guarantee that the main model redoes the failed delegation: its recorded runs either reported the missing result or did the work another way. Stating that it always redoes the work could lead authors to assume the delegated task still completes after the 400. Describe the recovery as nondeterministic instead. - docs(model-routing): explain Copilot CLI vs SDK mode, define allowed-models, add compiling examples #67755 (comment)
3. Review (docs/src/content/docs/reference/model-routing.md:144): This overstates what the smoke assertion helper verifies. It checks every main-agent request against the candidate models, but R3 and S3 require only one successful request on a supported/declared endpoint; they do not validate every request's endpoint. Describe these as model/endpoint evidence checks rather than per-request checks. - docs(model-routing): explain Copilot CLI vs SDK mode, define allowed-models, add compiling examples #67755 (comment)

Push the necessary fixes, reply to each listed review thread and resolve it when addressed. Ignore feedback already answered or resolved. Use the pr-finisher skill and stop when only human review or CI remains; do not trigger CI.

Sous-chef head: dc125f9
Sous-chef work: 18714d38b1e6cceac462fd6f67f2f0803ab83cbaf5a3bf3cbdb9a1bbb4872e53 beacfba3f5e1805e4d26541b477a16292eee7a490a0ed48fd0671cdf1e7924cc
Sous-chef state: e05e046cfc5901d0b4571966c241ae2b27c31cffc59da5ba890c4b47ac1f266c

Generated by 👨‍🍳 PR Sous Chef · pi · haiku45 · 3.44 AIC · ⌖ 7.1 AIC · ⊞ 1K · ◷
_{Comment /souschef to run again}

[SivaKesava1]

@copilot /pr-finisher

[Copilot]

@copilot address the following outstanding work in one pass:

1. Update this branch with the latest main using make merge-main, resolving any conflicts and preserving the intended changes....

The two linked review threads were updated in 9f8079e and are already resolved. make merge-main confirmed this branch is current with main at 6e59aae, so no additional commit was needed; the current head is 5fe82c3.

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.91.9