[FEATURE] Allow specifying effort at subagent invocation (Agent/Task tool)

Priority: Medium - Would be very helpful · Feature Category: API and model interactions

Problem Statement

When the orchestrator spawns a subagent via the Agent/Task tool, it can override the subagent's model per invocation but not its reasoning effort. Effort is configurable only as a static frontmatter default on the agent definition (effort: low|medium|high|xhigh|max, available since ~v2.1.196).

Task difficulty varies per invocation, and the orchestrator — which authored the task prompt — is best positioned to judge how hard a given spawn is. Yet it can dial capability (model) but not reasoning depth (effort). These are complementary knobs; exposing one without the other is half-control. The only workaround is duplicating agent definitions per effort level (e.g. search-low / search-high), which fragments maintenance and doesn't scale to the model×effort matrix.

Proposed Solution

Add an optional effort parameter to the Agent/Task tool, accepting the same enum as the frontmatter field (low|medium|high|xhigh|max). Resolution precedence should mirror model: per-invocation effort > frontmatter effort > session effort.

Task({
  subagent_type: "code-explorer",
  model: "sonnet",
  effort: "low",        // NEW — orchestrator-chosen per spawn
  prompt: "Find every caller of CreateUser in this repo."
})

Precedent: the Claude Code Workflow tool's agent() API already supports a per-call effort option (opts.effort: 'low' | 'medium' | 'high' | 'xhigh' | 'max'). This request simply brings the interactive Agent/Task tool to parity with capability that already ships in the workflow harness.

Alternative Solutions

• Frontmatter effort: (exists today) — static per definition; can't reflect per-task difficulty.
• Cloning agents per effort level (agent-low / agent-high) — registry bloat, fragmented maintenance, combinatorial with model.
• Session-level /effort — too coarse; applies to the whole session, not a single delegated task.
• A global env var for effort (à la CLAUDE_CODE_SUBAGENT_MODEL) — not per-invocation; same limitation as the model env var.

Use Case Example

In multi-agent orchestration, one search/lookup agent handles both a trivial symbol lookup (wants effort: low — fast, cheap) and a cross-repo trace (wants effort: xhigh). The orchestrator knows which at spawn time and already varies model accordingly — it should be able to vary effort the same way, instead of being locked to one static frontmatter value or forced to maintain duplicate agent files.

The same need shows up in review/fan-out pipelines: mechanical clusters at low, reasoning-heavy clusters at high, launched in one parallel batch.

Additional Context

Verified against Claude Code v2.1.197: subagents.md ("Choose a model") lists only model and isolation as per-invocation parameters; effort is documented as a frontmatter-only field. The Workflow agent() API's existing opts.effort option indicates the underlying capability is already implemented in one harness.