agent_spawn MCP schema: expose exact native model identity and effort beyond Claude aliases
- 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
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