[FEATURE] First-class multi-model orchestration — Haiku-as-Scout, cascading pipelines, capability matrix

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Multi-model workflows in Claude Code require undocumented trial-and-error to build. We built a production system with 6 custom agents (5 Sonnet, 1 Haiku) and 2 model-switching commands — but discovering model capabilities, limitations, and optimal patterns took ~2 hours of empirical testing that should've been a 30-second docs lookup.

Here's what we ran into:

1. No capability matrix: Haiku's 200k context limit [Claude-documentation], lack of effort control, and missing tool_reference support are all undocumented;
2. No pipeline primitives: Each agent invocation is independent. There are no way to chain [between] a cheap model (like `Haiku**, for file discovery) -> into a smarter one (like **Sonnet-high**, for analysis) -> into the strongest (like like **Opus-max`, for validation);
3. No effort inheritance: When Claude launches a subagent, effort settings are silently lost
4. No cost guidance: Users designing agent workflows have no reference for relative model costs

Proposed Solution

Four concrete features, each independently valuable:

1. Model capability matrix [in Claude-documentation]

A single reference table would save hours of trial-and-error:

| Capability | Haiku | Sonnet | Opus |
|-----------|-------|--------|------|
| Context window | 200k | 1M | 1M |
| effortLevel support | NO | YES (low/med/high) | YES (low/med/high/max) |
| Extended thinking | NO | YES | YES |
| Tool use | YES | YES | YES |
| tool_reference blocks | NO (#14863) | YES | YES |

2. Cascading pipeline support

A cascade field in agent frontmatter:

---
name: smart-search
cascade:
  - model: haiku
    role: scout
    instruction: "Find files matching pattern, return paths only"
  - model: sonnet
    role: analyst
    instruction: "Evaluate candidates, filter to top 3 with rationale"
---

3. Effort inheritance documentation

Document whether subagents inherit the parent's effort level (our testing suggests they don't).

4. Cost indicators per model

| Model | Relative cost |
|-------|---------------|
| Haiku | 1x (baseline) |
| Sonnet | ~4x |
| Opus | ~19x |

Even just relative costs would help users make informed model assignments.

Alternative Solutions

We currently orchestrate manually:

• 6 agents with model: in frontmatter (this works)
• 2 commands with model: for depth switching (this works)
• Manual result passing between agents (text serialization)
• Empirical capability testing per model (slow, undocumented)

This works, but it's fragile (yet), and we only figured it out through trial and error. First-class support would make multi-model workflows accessible to everyone, not just those willing to invest hours in experimentation.

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

Haiku-as-Scout pattern (FORM vs CONTENT) | `[the cheap model]`

Haiku is excellent for structural filtering but unreliable for semantic analysis:

| Task type | Haiku | Example |
|-----------|-------|---------|
| File discovery by pattern | GOOD | "Find all *_test.py files" |
| Syntax validation | GOOD | "Does this file import numpy?" |
| Semantic code review | BAD | "Is this algorithm correct?" |
| Architectural decisions | BAD | "Should this go in the shared library?" |

Golden rule: Haiku filters by FORM (structure), never by CONTENT (meaning).

This enables a ~6x cost reduction:

Haiku (scout) -> scans 50 files, filters to 8 by structure
    |
Sonnet (analyst) -> reads 8 files, evaluates semantically
    |
Opus (reviewer) -> validates critical decisions

Our production setup

"algorithm-discovery":        model: sonnet  # Finds math patterns in legacy codebases
"visual-pattern-explorer":    model: sonnet  # Extracts layout/chart/typography patterns
"knowledge-pattern-explorer": model: sonnet  # Discovers interpretation & narrative patterns
"visualization-qa":           model: sonnet  # Reviews chart modules for correctness
"interpretation-qa":          model: sonnet  # Reviews domain knowledge for accuracy
"synthetic-data-gen":         model: haiku   # Generates test datasets (structural/formulaic)

Additional Context

Open questions (genuine — we couldn't find answers in docs or GitHub)

1. What's Haiku's actual reasoning depth? Without effort control, is it roughly Sonnet at effort: low? Or fundamentally different?
2. Can agents pass structured data to the next agent? Scout results currently go through text serialization. A typed handoff would make cascades more reliable.

Related issues

• #24316 (custom agents as teammates — 26 upvotes, OPEN. Ask 2 extends this to sequential model-assigned cascades)
• #14321 (enable extended thinking for subagents — 15 upvotes. Ask 3 is the documentation companion, not duplicate)
• #33000 (/effort broken — 26 upvotes. Urgency evidence for Ask 3: effort system needs documentation)
• #18873 (model 404 blocks cost-optimized workflows — quantifies 10-30x cost waste. Ask 4 prevents this)
• #9749 (combined Sonnet/Haiku like opusplan — implemented, two-tier precedent for Ask 2)
• #29612 (flexible plan/execute model pairing — closed as dup)
• #29768 (Explore inherits parent model — supporting evidence for Ask 1)
• #14863 (Haiku tool_reference — fixed in v2.0.76, evidence for Ask 1 matrix)
• #32732 (agent model field override)
• #10993 (subagent model selection behavior unclear — evidence for Ask 1)

Environment: Claude Code for VSCode 2.1.70, Windows 10 Pro, 6 custom agents + 2 commands with model frontmatter