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

Status Open

Maintainer reply None cached

Activity 10 comments · opened Jul 13, 2026

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 ↗

7 Comments

cvmocanu · 1 month ago

It's worth flagging that the reaction count here understates the demand: this is the third time it has been asked.

#43083 asked for exactly this — frontmatter and per-invocation effort — collected 59 👍 / 14 ❤️, and was closed as completed when frontmatter-only effort: shipped. Commenters said at the time that frontmatter misses the point. #39220 was closed as not planned. Those votes never carried over here, so this issue reads as a 7-reaction request for something ~70 people have already asked for.

The cost is concrete. Effort is a property of the task, not of the agent: the dispatcher knows how demanding the work is, the agent file cannot. So every level becomes a duplicate file — I keep implementer.md/implementer-xhigh.md and reviewer.md/reviewer-xhigh.md, identical but for one frontmatter line, with the role text kept in sync by hand. A one-off dispatch at a higher level means authoring a permanent agent, and it is not dispatchable until the session picks the new file up.

The ask is small: an optional effort beside the model override that already exists on the Agent call, with call > frontmatter > session precedence.

zzJinux · 1 month ago

Note that the agent function in Workflow scripts has an effort parameter that overrides the value defined in the specified agent definition. This implies the Agent tool not having the effort parameter is inconsistency gap.

gtapps · 1 month ago

Re-tested on Claude Code 2.1.263 (2026-09-06). Adding one data point that may be useful for triage: a per-call effort field on the Agent tool is accepted without a validation error but silently ignored.

Setup: lead session at medium effort, four spawns via the Agent tool, effort read from the assistant entries in <session>/subagents/agent-*.jsonl.

| spawn | Agent call | subagent transcript effort |
|---|---|---|
| Sonnet, effort: "low" passed | accepted | medium (inherited from lead) |
| Sonnet, no effort field | accepted | medium |
| Haiku, effort: "low" passed | accepted | no effort field written |
| Haiku, no effort field | accepted | no effort field written |

So today the only working levers are still the agent definition's frontmatter effort: (which a plugin-shipped agent cannot expose to the user) or a session-wide /effort change before the spawn. Since the tool already accepts the key, a validation error or a working override would both be an improvement over the current silent drop.

Related: #79866 (same need from the plugin-shipped-agent angle).

cjsteigerwald · 1 month ago

+1, with a concrete case. We ship a verifier subagent in a plugin (model: fable, effort: medium). Per dispatch we can override model via the Agent tool, but not effort. So "default medium, raise it when asked" means maintaining a second agent file (fresh-verifier-high) that's identical except for effort: high. An optional effort parameter on the Agent tool, overriding frontmatter the same way model does, would remove the need for these variants.

verIdyia · 29 days ago

+1. Same need: main session at high, read-only scouts at low, picked per call instead of forking agent definitions.

markx3 · 24 days ago

+1. Data point from Claude Code 2.1.278 (2026-09-21), macOS.

Use case: a Fable 5.1 session at low effort as coordinator, wanting to dispatch heavy implementation to Opus 5 at high. model: opus works per call, but effort still can't be set at call time, so the only route is a .claude/agents/opus-high.md with effort: high.

Two frictions with that workaround, both of which a per-call parameter would remove:

The new agent file is not dispatchable in the session that created it (Agent type 'opus-high' not found); it only appears after a restart. A coordinator that decides mid-session it needs a high-effort worker has to stop and reopen.
The effective effort is invisible from the outside. The subagent's system prompt doesn't mention it and --debug logs the model (source=agent:custom:opus-high, model=claude-opus-5[1m]) but not the effort, so there's no way to confirm the frontmatter took. The binary's agent schema does declare effort ("low, medium, high, max, or an integer"), so it's presumably applied.

Effort is a property of the task the orchestrator is handing off, not of the agent file. Call-time effort > frontmatter > session, mirroring model, is the shape that fits how orchestration actually happens.

abhideepm · 18 days ago

+1. Two points not raised yet in this thread:

The frontmatter workaround is overridden by the env var. Per model-config, frontmatter effort applies "overriding the session level but not the environment variable". Anyone who sets CLAUDE_CODE_EFFORT_LEVEL in their shell (a common way to pin a session default) silently loses every effort: in their agent files. The only per-agent lever stops working, and nothing tells you. A call-time effort should rank above the env var, the same way the call-time model ranks above CLAUDE_CODE_SUBAGENT_MODEL.

Multi-model routing already works with per-call effort everywhere except the Agent tool. Our repo instructions route work across tiers by model and effort: an Opus review at high and Opus exploration at the session default, alongside another vendor's CLI that takes --effort on every call. Every tier can be written as "model + effort per call" except the Claude subagents, which need a separate agent file (opus-reviewer.md) that exists only to raise effort. The routing table in our CLAUDE.md can't express the Claude rows the way it expresses the others.

Shape as proposed: call-time effort > frontmatter > session, mirroring model.

Showing cached comments. Read the full discussion on GitHub ↗