Design: unify route-specific tool projection before request dispatch
- Dominant language
- Rust
- Stars
- 41k
- Forks
- 3.6k
- Avg merge
- 13h 59m
- Merged PRs (30d)
- 299
Description
## 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](https://github.com/Hmbown/CodeWhale/pull/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.
Contributor guide
Research direction
Start with the CodeWhale request-preparation layer and compare the route-specific request builders with PR #5636's narrow Moonshot stopgap. Trace how dispatch, request preview, tool_choice, deferred/tool-search discovery, and diagnostics currently obtain tool data. Done means maintainers agree on the projection seam, typed outcomes, privacy-bounded diagnostics, and shared preview and dispatch state.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend-api-design
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100