[BUG] Task tool `model` parameter returns 404 - Blocks cost-optimized workflows (10-30x unnecessary spending)

What's Wrong?

The Task tool's model parameter is completely broken in Claude Code 2.1.12+, creating a catch-22 that blocks cost-effective mixed model architectures and causes 10-30x unnecessary spending on simple operations.

The problem:

• CLI validation requires short model names: "haiku", "sonnet", "opus"
• API rejects those same short names with 404 errors: {"type":"not_found_error","message":"model: haiku"}
• Full model IDs (e.g., "claude-haiku-4-5-20251001") are rejected by CLI validation

Result: Users cannot use Opus/Sonnet for main session while delegating simple tasks (file searches, exploration) to Haiku. All sub-agent operations inherit the expensive parent model, causing massive cost waste.

---

What Should Happen?

The Task tool's model parameter should:

1. Accept short model names ("haiku", "sonnet", "opus")
2. Map them to full model IDs using ANTHROPIC_DEFAULT_*_MODEL environment variables
3. Allow cost-optimized workflows: Expensive models for reasoning, cheap models for execution

Expected workflow:

// Main session uses Opus for architecture
// But delegate simple tasks to Haiku
Task({
  subagent_type: "Explore",
  model: "haiku",  // Should work, currently returns 404
  prompt: "Find authentication code"
})

---

Cost Impact (HIGH PRIORITY)

This bug forces 10-30x unnecessary spending on routine operations for power users.

Scenario 1: Opus Main Session (Architecture Work)

| Task Type | Intended Model | Forced to Use | Cost Multiplier | Daily Operations |
|-----------|----------------|---------------|-----------------|------------------|
| Deep reasoning, planning | Opus | Opus ✅ | 1x (correct) | ~5/day |
| File searches | Haiku | Opus ❌ | 30x | ~10/day |
| Code exploration | Haiku | Opus ❌ | 30x | ~8/day |
| Browser automation | Haiku | Opus ❌ | 30x | ~3/day |

Monthly waste for active Opus users: Hundreds of thousands of unnecessary Opus tokens

Scenario 2: Sonnet Main Session (Standard Development)

| Task Type | Intended Model | Forced to Use | Cost Multiplier | Daily Operations |
|-----------|----------------|---------------|-----------------|------------------|
| Implementation | Sonnet | Sonnet ✅ | 1x (correct) | ~10/day |
| File searches | Haiku | Sonnet ❌ | 10x | ~15/day |
| Simple queries | Haiku | Sonnet ❌ | 10x | ~10/day |

Impact multipliers:

• Individual developers: 10-30x cost increase on 50%+ of daily operations
• Teams: Multiplied across entire team
• Rate limits: Burning Opus/Sonnet limits on trivial file searches

---

Blocked Workflows

This bug prevents:

1. Cost-optimized development

• ❌ Opus for architecture decisions + Haiku for codebase exploration
• ❌ Sonnet for implementation + Haiku for testing/verification

1. Rate limit management

• ❌ Users hitting Opus limits cannot offload simple tasks to Haiku
• ❌ Forced to wait for Opus rate limits even with Sonnet capacity available

1. Team cost control

• ❌ Cannot implement "Opus for architects, Sonnet for developers, Haiku for automation"
• ❌ All-or-nothing model selection per session

1. Budget-conscious usage

• ❌ Educational/hobbyist users cannot use occasional Opus reasoning with Haiku for bulk operations

---

Steps to Reproduce

Environment:

• Claude Code version: 2.1.12
• Platform: macOS (also confirmed on Linux)
• Session model: Sonnet or Opus (set in ~/.claude/settings.json)

Setup:

1. Configure environment variables in ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5-20250929"
  },
  "model": "sonnet"
}

1. Verify environment variable is loaded:

$ echo $ANTHROPIC_DEFAULT_HAIKU_MODEL
claude-haiku-4-5-20251001  # Confirmed loaded

Test 1: Short model name (documented approach)

1. Attempt to spawn Haiku subagent:

Task({
  subagent_type: "Explore",
  model: "haiku",
  description: "Test haiku model",
  prompt: "List files in src/"
})

Expected: Haiku subagent launches
Actual: API Error: 404 {"type":"error","error":{"type":"not_found_error","message":"model: haiku"}}

Test 2: Full model ID

1. Try using full model ID directly:

Task({
  subagent_type: "Explore",
  model: "claude-haiku-4-5-20251001",
  description: "Test full model ID",
  prompt: "List files in src/"
})

Expected: Should work with full model ID
Actual: InputValidationError: Invalid option: expected one of "sonnet"|"opus"|"haiku"

Test 3: Omit model parameter (current workaround)

1. Omit model parameter:

Task({
  subagent_type: "Explore",
  description: "Test without model",
  prompt: "List files in src/"
})

Result: ✅ Works, but inherits Sonnet/Opus (defeats the purpose, 10-30x cost waste)

---

Error Messages/Logs

// Attempt 1: Short name "haiku"
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: haiku"
  },
  "request_id": "req_011CXDVkqrUchawYnkT2Yfq3"
}

// Attempt 2: Full model ID
{
  "code": "invalid_value",
  "values": ["sonnet", "opus", "haiku"],
  "path": ["model"],
  "message": "Invalid option: expected one of \"sonnet\"|\"opus\"|\"haiku\""
}

---

Technical Analysis

The Catch-22

Short model names ("haiku", "sonnet", "opus"):
  ✅ Pass CLI validation
  ❌ Fail at API → 404 "model not found"

Full model IDs ("claude-haiku-4-5-20251001"):
  ❌ Fail CLI validation
  ✅ Would work at API (never gets there)

Omit model parameter:
  ✅ Works (inherits parent model)
  ❌ Defeats cost optimization purpose

Root Cause Hypothesis

The Task tool's model parameter uses a different code path than:

• Main session model selection (works correctly)
• Agent frontmatter model: field (works with full IDs)

Evidence suggests the Task tool:

1. ✅ Validates input accepts only short names
2. ❌ Skips environment variable resolution step
3. ❌ Passes raw short name directly to API
4. ❌ API rejects unrecognized short name

Environment Variable Testing

Configured:

"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001"

Verified loaded:

$ echo $ANTHROPIC_DEFAULT_HAIKU_MODEL
claude-haiku-4-5-20251001  # ✅ Present

Task tool result:

model: "haiku" → Still returns 404

Conclusion: Task tool's model parameter does not consult ANTHROPIC_DEFAULT_*_MODEL environment variables.

---

Related Issues (4+ Months Old, Still Not Fixed)

This is the parent issue for multiple related problems:

| Issue | Status | Date | Description |
|-------|--------|------|-------------|
| #9243 | OPEN | Oct 9, 2025 | Invalid Model Name 'sonnet' (original report) |
| #11682 | Closed (dup) | Nov 15, 2025 | Task Tool Model Parameter 404 Error |
| #9749 | Open | Unknown | Feature: Allow Sonnet/Haiku combo like opusplan |
| #5456 | Unknown | Unknown | Sub-agents don't inherit model config |
| #8932 | Unknown | Unknown | general-purpose agent sets model wrong |
| #10993 | Unknown | Unknown | Subagent model selection behavior unclear |

Timeline:

• First reported: October 9, 2025 (Issue #9243)
• Still broken: January 17, 2026 (4+ months)
• Risk: Issue #9243 has 30-day inactivity notice (may auto-close)

---

Business Impact

For Individual Developers

• 💰 Cost overrun: Paying 10-30x more for simple file searches and exploration
• 🚫 Rate limits: Hitting Opus limits on trivial tasks, blocking real architecture work
• ⚠️ Workflow inefficiency: Cannot use optimal model for each task type

For Teams & Enterprise

• 📊 Budget impact: 10-30x waste multiplied across entire team's daily operations
• ❌ Policy enforcement impossible: Cannot mandate "cheap models for automation, expensive for reasoning"
• 🏢 Barrier to enterprise adoption: Teams evaluating Claude Code see uncontrolled costs

For Claude Code Adoption

• 📉 Competitive disadvantage: Other tools allow model optimization
• 😤 User frustration: Documented feature doesn't work for 4+ months
• 🔴 Reputation risk: "opusplan removed, now can't even mix models manually"

---

Requested Fix

Primary Solution

Fix the Task tool's model name resolution to:

1. Consult ANTHROPIC_DEFAULT_*_MODEL environment variables
2. Map short names to full model IDs (same logic as main session)
3. Use the same resolution code path as main session model selection

Alternative Solutions

Option A: Accept full model IDs in CLI validation

• Update validation to accept both short names and full model IDs
• Map short names via environment variables, pass full IDs directly

Option B: Add explicit model_id parameter

• Keep model for short names (fix the resolution)
• Add model_id for full model IDs (bypass validation)

Testing Checklist

• [ ] model: "haiku" launches Haiku subagent
• [ ] model: "sonnet" launches Sonnet subagent
• [ ] model: "opus" launches Opus subagent
• [ ] Environment variables are consulted for resolution
• [ ] Custom models (AWS Bedrock, Azure) work via env vars
• [ ] Omitting model still inherits parent (backward compatibility)

---

Workarounds (All Inadequate)

Workaround 1: Omit model parameter

Task({ subagent_type: "Explore", prompt: "..." })

✅ Pros: Works, no errors
❌ Cons: Inherits parent model, 10-30x cost increase, defeats purpose

Workaround 2: Switch main session model

/model haiku  # For exploration
Task(...)
/model opus   # Switch back

✅ Pros: Uses correct model
❌ Cons: Manual, breaks flow, context loss, main session suboptimal

Workaround 3: Custom agents with frontmatter

---
model: claude-haiku-4-5-20251001  # Works in YAML
---

✅ Pros: Full model IDs work in frontmatter
❌ Cons: Only for custom agents, can't use Task tool, no dynamic selection

---

Why This Needs Priority

This bug blocks a documented, advertised feature (Task tool model parameter) and causes real financial harm:

1. ✅ Easy to fix: Main session and agent frontmatter already work correctly
2. 💰 High cost impact: 10-30x waste on 50%+ of operations for power users
3. ⏰ Long-standing: 4+ months without fix (Issue #9243)
4. 🏢 Blocks enterprise: Teams cannot control costs effectively
5. 📉 Adoption barrier: Cost-conscious users cannot use Claude Code optimally

The fix is likely straightforward - just use the same model resolution code path that already works for main sessions and agent frontmatter.

---

Environment Details

• Claude Code Version: 2.1.12
• Platform: macOS (confirmed), Linux (confirmed)
• API: Anthropic API (not AWS Bedrock or Azure)
• Affects: All users trying to use Task tool model parameter
• Severity: HIGH - Causes 10-30x cost waste, blocks documented feature

---

Additional Context

What works:

• ✅ Main session model selection via "model": "sonnet" in settings
• ✅ Environment variables load correctly (ANTHROPIC_DEFAULT_*_MODEL)
• ✅ Agent frontmatter with full model IDs: model: claude-haiku-4-5-20251001
• ✅ Task tool without model parameter (inherits parent, expensive but functional)

What's broken:

• ❌ Task tool model: "haiku" → 404 error
• ❌ Task tool model: "claude-haiku-4-5-20251001" → CLI validation error
• ❌ Environment variables not consulted by Task tool

Community validation:

• Multiple independent reports (Issues #9243, #11682, #8932)
• Users creating validation hooks specifically to enforce model parameter (to prevent inheritance)
• Feature requests for "sonnetplan" (15+ comments in #9749)

---

Request for Timeline:

• When will this be fixed?
• Can this be prioritized given the cost impact?
• Any interim solution if fix requires major refactoring?

Thank you for your attention to this critical cost and functionality issue.