Hmbown / Hmbown/Codewhale

Design: unify route-specific tool projection before request dispatch

Open
#5,633 1 comment 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.