[FEATURE] Add per-call effort parameter to the Agent (Task) tool
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/*.mdfile — 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
effortparameter; only agent-frontmattereffort: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
effortis 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
/efforthandles them.