Feature: effort/thinking configuration for Task tool subagents

Feature Request: Effort/Thinking Configuration for Task Tool Subagents

Summary

The Task tool should support an effort parameter (and optionally thinking configuration) when spawning subagents, enabling programmatic control over reasoning depth and token spend per-subagent — similar to how the model parameter already allows per-subagent model selection.

Problem

Claude Code's Task tool currently exposes model, max_turns, prompt, and subagent_type for subagent dispatch. However, there is no mechanism to control the effort level or thinking budget of spawned subagents, despite the underlying Claude API fully supporting these parameters (effort: "low" | "medium" | "high" | "max" for Opus 4.6, and thinking: {type: "adaptive"} for extended thinking).

This creates a capability gap: users and the main agent cannot optimize cost/quality tradeoffs across subagent dispatches. A quick file lookup subagent and a deep architectural analysis subagent are treated identically in terms of reasoning effort.

Additionally, it is undocumented whether a subagent inherits the parent session's effort level or receives a hardcoded default. This ambiguity makes it impossible to reason about subagent behavior or token costs.

Proposed Solution

Add an optional effort parameter to the Task tool:

// Task tool parameters (proposed additions)
{
  model?: "sonnet" | "opus" | "haiku",    // existing
  effort?: "low" | "medium" | "high" | "max",  // NEW
  max_turns?: number,                      // existing
  prompt: string,                          // existing
  subagent_type: string                    // existing
}

For custom subagent definitions (frontmatter), extend the schema:

---
name: deep-analyzer
model: opus
effort: high
---

Default behavior should be documented explicitly — whether effort inherits from the parent session or defaults to a specific level.

Use Cases

Cost optimization for parallel dispatch:
A main Opus agent spawning 5+ parallel subagents could use Haiku with low effort for simple lookups and Opus with high effort for complex analysis — in a single coordinated dispatch. Currently, the only lever is model selection.

Adaptive reasoning depth:
When the main agent determines a task is straightforward (e.g., "find the file that defines X"), it could dispatch with effort: "low". For tasks requiring deep analysis (e.g., "analyze the architectural implications of this change"), it could use effort: "high" or "max".

Deterministic token budgeting:
Teams using Claude Code in CI/CD or automated workflows need predictable token costs. Without effort control on subagents, costs per subagent are unpredictable and untunable.

Questions This Would Answer

These are questions that arose during investigation and that the feature, if implemented, would make answerable:

1. "Can I set effort level for subagents, for example 'use Opus 4.6 high effort for this task'?"
2. "If an Opus subagent is dispatched, what effort level is used? Is it the same as the main agent?"
3. "Can the main agent autonomously choose different reasoning depths for different subtasks?"
4. "How do I control token spend across parallel subagent dispatches?"
5. "Does the /think toggle or effort setting in the main session propagate to subagents?"
6. "Can I configure extended thinking budgets per-subagent?"
7. "How do I optimize cost when some subagent tasks are trivial and others are complex?"

Current State (Sources)

| Aspect | Status | Source |
|--------|--------|--------|
| Task tool model parameter | Supported | Claude Code subagents docs |
| Task tool effort parameter | Not supported | Parameter not present in Task tool schema |
| API-level effort parameter | Supported (Opus 4.6) | Effort docs |
| API-level thinking config | Supported | Extended thinking docs |
| Agent SDK AgentDefinition effort field | Not present | Agent SDK TypeScript reference |
| Subagent effort inheritance behavior | Undocumented | No documentation found in Claude Code docs, Agent SDK docs, or API docs |
| Main agent self-model-switching | Not supported (user-only via /model) | GitHub #17772, #12645 |
| Task tool model parameter bugs | Known issues | GitHub #18873 |

Additional Recommendations

1. Document inheritance behavior now — Even before implementing the feature, document whether subagents currently inherit the parent's effort level. This is a zero-cost improvement.
2. Consider a thinking parameter too — For Opus 4.5 and models using explicit thinking budgets, a thinking_budget parameter would complement effort.
3. Align with Agent SDK — If the Agent SDK's AgentDefinition type gains an effort field, Claude Code's Task tool should mirror it.

Environment

• Claude Code CLI (interactive mode)
• Model: claude-opus-4-6
• Platform: macOS (Darwin 24.2.0)