Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Agent tool model parameter enum rejects 1M-context variants (opus[1m], claude-opus-4-7[1m])

Type: Bug / Feature gap Component: Claude Code — Agent tool JSONSchema validation Severity: Medium (blocks optimal per-role configuration in multi-agent orchestration)

Summary

The Agent tool's model parameter is constrained by a strict JSONSchema enum: "sonnet" | "opus" | "haiku". This prevents spawning subagents with Opus 4.7's 1M-context variant using the documented suffix syntax [1m] (e.g. opus[1m] or claude-opus-4-7[1m]), even though the underlying model and runtime already support this identifier when set via the CLAUDE_CODE_SUBAGENT_MODEL environment variable in settings.json.

Business value / Why this matters

Multi-agent orchestration workflows (team-based development, parallel review cascades, long-running persistent roles) rely on Opus subagents handling large contexts: phase plans, architectural specs, lessons-learned docs, 20+ work-item descriptions with attachments, rolling journal files, external adversarial-review reports.

When such a subagent hits the 200K limit of standard Opus mid-task it compacts, losing its reasoning chain and potentially overwriting partially-completed artefacts (plans, review verdicts, postmortems). The 1M variant of Opus 4.7 is the correct tool for these roles, but the Agent tool currently cannot target it from code. This forces a global settings-level workaround that cannot differ between subagents in the same session (e.g. a persistent Architect needing 1M, while a short-lived one-shot Defect-Fixer is fine with 200K).

Problem

Calling Agent with the 1M-context identifier returns a validation error before the subagent is ever spawned:

InputValidationError: [
  {
    "code": "invalid_value",
    "values": ["sonnet", "opus", "haiku"],
    "path": ["model"],
    "message": "Invalid option: expected one of \"sonnet\"|\"opus\"|\"haiku\""
  }
]

The same identifier (claude-opus-4-7[1m]) is accepted by the runtime when supplied via CLAUDE_CODE_SUBAGENT_MODEL environment variable in ~/.claude/settings.json. This inconsistency suggests the Agent tool's enum is lagging behind the runtime's capabilities.

What Should Happen?

Expected behavior

The Agent tool accepts the [1m] suffix (or a fully-qualified model ID such as claude-opus-4-7[1m]) and spawns a subagent with the requested context window. Per-call specification should be possible — the env-var workaround applies globally and loses granularity between different subagent roles in the same session.

Actual behavior

Validation fails before spawn. Only the three base aliases (sonnet, opus, haiku) are accepted, with no mechanism to target context-window variants.

Proposed solution

Either of the following would fix this:

Option 1 — Extend the enum (minimal, matches documented syntax):

"sonnet" | "opus" | "haiku" | "opus[1m]" | "sonnet[1m]" | "claude-opus-4-7[1m]" | "claude-sonnet-4-6[1m]"

Option 2 — Change the field to a pattern-validated string (more flexible, future-proof for new models/variants):

{
  "type": "string",
  "pattern": "^(sonnet|opus|haiku|claude-[a-z]+-\\d-\\d)(\\[1m\\])?$"
}

Option 3 — Accept any string and delegate validation to the runtime (mirrors how the env-var path already works).

Any of the three would allow per-call context-window selection without breaking existing callers.

Current workarounds

1. CLAUDE_CODE_SUBAGENT_MODEL in settings.json — works, but applies to every subagent in the session. Cannot differentiate between a long-running Architect (needs 1M) and a short one-shot Defect-Fixer (200K is fine and cheaper).

2. Context-budget discipline in the spawn prompt — instructing the subagent to read files in priority tiers, force-flush findings at 70% usage, and avoid loading entire large specs. Works for well-scoped one-shot roles; fails for persistent roles (Architect) where context accumulation is unavoidable over the lifetime of a phase.

Neither workaround matches the ergonomics of a simple model parameter.

Error Messages/Logs

agent team orchestrator spawns Opus 200k Token Model and has no ability to spawn 1M Opus Model

Steps to Reproduce

How to reproduce

1. In any Claude Code session (v2.1.110 or later), invoke the Agent tool with a 1M-context model identifier:

   Agent({
     subagent_type: "general-purpose",
     name: "test-1m",
     model: "opus[1m]",
     prompt: "test"
   })

2. Observe: InputValidationError with the enum constraint message above. The subagent is never spawned.

3. Confirm the runtime supports the identifier: add to ~/.claude/settings.json:

   {
     "env": {
       "CLAUDE_CODE_SUBAGENT_MODEL": "claude-opus-4-7[1m]"
     }
   }

   Then spawn any subagent with model: "opus" and verify via /status or inspecting the subagent's context that the 1M window is active.

Same error occurs for the fully-qualified identifier model: "claude-opus-4-7[1m]".

Impact

Any orchestration skill or workflow that needs per-role context-window selection is blocked from optimal configuration. In practice this leads to:

• Mid-task compaction of long-running subagents, losing reasoning chains.
• Re-spawning subagents with fresh context (expensive, and loses prior work unless explicit handoff files are written).
• Prompt-level discipline workarounds that shift complexity into the spawn prompt rather than the tool surface.

Environment

• Claude Code CLI version: (2.1.114)
• OS: (Ununtu 24.04 WSL2)
• Opus 4.7 (1M context) confirmed available via Anthropic API and via CLAUDE_CODE_SUBAGENT_MODEL env var.
• Reproduction: consistent across sessions, different subagent_type values, different prompt sizes.

References

• Documentation mentioning opus[1m] syntax: Claude Code model configuration docs.
• Runtime support confirmed via env-var path: CLAUDE_CODE_SUBAGENT_MODEL.
• Agent tool JSONSchema: exposes strict enum for model field.

Suggested label(s): bug, agent-tool, model-config, feature-gap

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

No response

Claude Code Version

2.1.114

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Windows Terminal

Additional Information

No response