[FEATURE] Add per-call effort parameter to the Agent (Task) tool

Open 💬 0 comments Opened Jul 13, 2026 by riptscripts

Summary

The Agent (Task) tool accepts a per-call model override, but no effort override. To spawn a single subagent at a different reasoning effort than the session, you must pre-author a whole agent definition file with effort: frontmatter — there is no way to set it at call time.

Motivation

Effort is the main cost/quality dial, and the right level is task-shaped, not agent-shaped: the same general-purpose agent might do a trivial file sweep (low) or a deep design review (high) in the same session. Today the options are:

  • session-wide (/effort, /model, CLAUDE_CODE_EFFORT_LEVEL) — affects everything, not the one spawn;
  • effort: frontmatter in a .claude/agents/*.md file — requires creating a persistent agent definition for what is a one-off call.

Creating a throwaway agent file just to change one spawn's effort is heavy friction, and it forks agent definitions into foo-low/foo-high variants.

Precedent

  • #25669 — same request, closed as completed, but no changelog entry ever shipped a Task-tool effort parameter; only agent-frontmatter effort: exists (referenced in the changelog's status-bar fix note).
  • #25591 — same request for teammates/subagents, closed as duplicate and locked.

Both are locked; the auto-close bot directs filing a new issue referencing them.

Proposed shape

Add an optional effort parameter alongside the existing model parameter:

{
  "subagent_type": "general-purpose",
  "model": "opus",        // existing per-call override
  "effort": "high",       // proposed: "low" | "medium" | "high" | ...
  "prompt": "..."
}

Precedence mirroring model: call-time effort > agent frontmatter effort: > inherited session effort.

Acceptance criteria

  • effort is accepted on Agent/Task tool calls and applied to that subagent only.
  • Omitted → current behavior unchanged (frontmatter, else session inheritance).
  • Invalid values rejected with a clear error; levels unsupported by the resolved model handled the same way /effort handles them.

View original on GitHub ↗