ruvnet / ruvnet/ruflo

agent_spawn MCP schema: expose exact native model identity and effort beyond Claude aliases

Open
#3,215 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
72.7k
Forks
8.6k
Avg merge
2d 23h
Merged PRs (30d)
83

Description

## Summary

The public `agent_spawn` MCP schema cannot express an exact native host model plus reasoning effort as first-class, validated intent. Its top-level `model` is still a five-value Claude alias enum, even though the handler now preserves arbitrary `config.model` strings after #3007.

This is a **schema/coordination-record contract** request, not a claim that arbitrary model strings cannot be stored, not a new Fable auto-routing tier, and not a request to add an API/provider transport.

## Verified scope

- Observed live MCP tool declaration on 2026-09-06: `model?: "haiku" | "sonnet" | "opus" | "opus-4.7" | "inherit"`; `config` is free-form; no typed native runtime/provider, exact model ID, or reasoning-effort field.
- Current upstream `main` at [277c7bc03ad192eef6d6f57e59ab7bab69a5728d](https://github.com/ruvnet/ruflo/commit/277c7bc03ad192eef6d6f57e59ab7bab69a5728d), whose CLI manifest reports 3.38.21, has the same [schema](https://github.com/ruvnet/ruflo/blob/277c7bc03ad192eef6d6f57e59ab7bab69a5728d/v3/%40claude-flow/cli/src/mcp-tools/agent-tools.ts#L292-L313). Therefore this particular mismatch is not merely an old installed schema.
- [The handler](https://github.com/ruvnet/ruflo/blob/277c7bc03ad192eef6d6f57e59ab7bab69a5728d/v3/%40claude-flow/cli/src/mcp-tools/agent-tools.ts#L192-L205) already preserves non-alias `config.model` as `modelId`, with `model: "sonnet"` as the compatibility field. That escape hatch matters, but it is not a discoverable, typed native-executor contract.

## Minimal reproduction (schema inspection only; no worker or inference needed)

1. Inspect `tools/list` → `agent_spawn.inputSchema.properties.model`.
2. Check an exact host-selected ID such as `gpt-6-astra`, or the literal `claude-fable-5` discussed in #2357, against that enum: neither satisfies the advertised top-level schema.
3. Try to describe native execution identity and effort using only the declared typed fields: there are no such fields. Values can only be hidden in arbitrary `config` keys, with no public semantics for validation, round-trip reporting, or executor handoff.

This reproduces the **advertised contract gap**. I did not call `agent_spawn`/`agent_execute`, run model inference, or test native model availability. A tracked record must not itself be taken as proof that its requested model executed.

## Expected contract

- A backward-compatible, documented way to record **host/runtime, provider, exact requested model ID, and native reasoning-effort setting** without pretending a Codex model is a Claude alias.
- Keep routing-tier/legacy-alias metadata distinct from exact model identity; expose the exact requested values in agent status and handoff data.
- Native Claude Code/Codex subscription execution remains native. Recording the selection must not authorize a separately billed API, a proxy, or another provider.
- Unsupported explicit model/effort combinations fail clearly; do not silently substitute a model, effort, provider, or execution method. Where native execution is external to Ruflo, distinguish requested configuration from executor-observed evidence.
- Regression coverage for schema acceptance, exact configuration round-trip, and unsupported-input behavior. Effort validation should follow the selected native runtime rather than invent one universal numeric scale.

## Related work checked

- #2357 / open PR #2359: Fable alias/frontier routing tier. Related, but does not provide the provider-aware native MCP contract above.
- #1103: adaptive Opus effort routing. This request is about preserving explicit caller intent, not choosing effort heuristically.
- #2962 / merged #3007: arbitrary model/provider propagation through direct execution. Already fixed; this report does not repeat that bug.
- #2236 / #2356: subscription/host inference execution. This issue does not require those new execution paths; the coordination schema can accurately describe an independently launched native worker.
- Open PR #1469: environment-based model overrides, not an explicit per-agent native model/effort contract.

Contributor guide

Open the contributing guide

Research direction

Read v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts, especially the handler at lines 192-205 and schema at lines 292-313, then inspect tools/list. Define the backward-compatible typed contract for host, provider, exact model ID, and native effort while preserving legacy aliases. Done means regression coverage for schema acceptance, exact configuration round-trip, and clear rejection of unsupported combinations without silent substitution.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend-api-design, cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.