Design: unify route-specific tool projection before request dispatch

[h3c-hexin]

Problem

Provider routes accept different tool-schema subsets and sometimes require different wire shapes. Today those compatibility decisions live inside individual request builders. That can make the wire tool list, tool_choice, deferred/tool-search discovery, request preview, and user diagnostics disagree. It also gives one incompatible tool a much larger blast radius than necessary.

Suggested direction

Consider a route-specific tool projection seam in the CodeWhale request-preparation layer (not in an embedding app):

• Keep the canonical tool catalog unchanged.
• Project that catalog for the resolved provider route into a small typed result containing the wire tools, a reconciled tool_choice, and bounded diagnostics.
• Let request preview and actual dispatch consume the same projection result.
• Represent compatibility outcomes explicitly (for example: exact, safely relaxed, or omitted) so deferred/tool-search surfaces can avoid advertising a tool that the active route cannot send, or can at least explain that state.
• Keep user-facing diagnostics privacy-bounded: tool names and outcome codes are useful; raw schemas and schema values are not.

The exact type, cache/fingerprint strategy, and how tool search should consume projection state are intentionally left open for maintainer input.

Why this belongs upstream

This is provider-routing and request-lifecycle behavior shared by every host. Implementing it in an app layer would duplicate CodeWhale's tool catalog and could still drift from the final provider request.

Current stopgap

PR #5636 proposes a narrow Moonshot fix: omit only MFJS-incompatible tools, reconcile named tool_choice, and surface a typed warning. That PR should remain a stopgap rather than growing into the general projection layer.

Non-goal

This issue is a design direction, not a complete implementation proposal or an implementation commitment from the downstream fork.

[Hmbown]

@h3c-hexin — the design is accepted. Thank you, and credit to @qiuYliangM / Lfanxing for the Moonshot stopgap (Pinvou#22) and to you for splitting the general layer out of that patch instead of growing a provider if into architecture.

What we are taking

A route-specific tool projection seam in Codewhale request preparation, not in an embedding app:

• Canonical tool catalog stays provider-neutral.
• After the route is resolved, project once into a small typed result: wire tools, reconciled tool_choice, bounded diagnostics.
• /preview-request and actual dispatch consume the same PreparedOutboundRequest. That seam already exists (prepare_outbound_request → build_chat_wire_body). Projection belongs there, not in individual transports.
• Compatibility outcomes are explicit (exact / safely relaxed / omitted) so deferred/tool-search cannot advertise a tool the active route will not send.
• User-facing diagnostics: tool names and outcome codes only. Never raw schemas or schema values.

That is the right layer. Doing it in a host would duplicate the catalog and drift from the wire body.

What landing looks like

Slice 1 — Moonshot stopgap, then stop. Per-tool degrade instead of failing the whole request; omit tools/tool_choice when nothing compatible remains; reject a named tool_choice that points at an omitted tool; one typed warning per affected request.

• fix(tui): degrade incompatible Moonshot tools per request #5636 is that stopgap. It is not on origin/main, and its GitHub merge is currently dirty.
• Rescue is fix(tui): rescue route-specific tool projection #5646 (codex/pr5636-rescue-20260827, head 41dd93525): Lfanxing's patch as the first commit, then a maintainer bound of the diagnostic to eight sanitized names. CI on that PR is green. It also needs a rebase onto current main (a96ea6cb) before it can merge — mergeable_state: dirty. Another lane owns that merge.
• Known follow-up from the fix(tui): rescue route-specific tool projection #5646 review, not a reason to grow the stopgap: streaming surfaces ToolProjectionWarning; blocking create_message() currently drops the same tools with only tracing::warn!. Fleet/subagent/review/verify/compaction use the blocking path. That warning must ride the shared prepared-request result, not a stream-only side channel.

Slice 2 — general projection, this issue. After the Moonshot omit path is on main, replace per-provider sanitizers (sanitize_moonshot_chat_tools still fail-closes the whole catalog on origin/main today at crates/tui/src/client/chat.rs:945) with a route capability table. Moonshot MFJS, xAI object-root, Anthropic, Responses, etc. become rows, not more if provider blocks. Fingerprint/cache strategy can wait until the typed result exists; do not invent a cache first.

This issue stays open until slice 2 exists. Do not close it when #5646 merges.