Which values can I pass for the Agent Tool's effort?
The official changelog only says an effort parameter was added and lists no values. The community proposal suggests low, medium, high, xhigh and max, but that is proposal content, not confirmed shipped behavior.
Check the official sub-agents documentation, or call it once with each value in a test project to see which are accepted and which raise errors.
Does a per-call effort override the effort in the agent definition?
The proposal wants per-call to beat the agent definition, which in turn beats the session level, matching the usual intuition that the caller overrides the default. The official notes do not say so, and I found no maintainer confirmation.
A test is simple: define an agent with effort low, pass high per call, and check the actual behavior and Token usage.
Will lowering effort always save money?
In direction it usually does, since fewer thinking tokens are used, but there are no official figures for how much each level saves, and quality can drop at the same time.
So measure a baseline first, lower effort only on repetitive tasks where mistakes are cheap, and confirm with both the bill and the quality of results.
I already have tiered agents like reviewer-low and reviewer-high. Should I merge them right away?
No rush. First confirm the per-call values and precedence behave as expected, then consolidate the tiered agents into one step by step.
Keep the old setup for a while before merging, run both approaches in parallel for a round, and remove the old ones once behavior matches.
Claude Code v2.1.292 (October 6, 2026) lists one line among its additions: an effort parameter for the Agent Tool. That is all the official notes say, with no list of values and no precedence rules, so this article keeps what is confirmed apart from what is inferred.
Before this, the Agent tool could already take a per-call model, but a Subagent's effort could only come from two places: the effort in the agent definition (frontmatter or --agents JSON), or the main session's level. Several community GitHub proposals asked for this, and one states the need concretely: run the main session at medium, use low for a mechanical batch and xhigh for a tricky review, with the same agent. Without a per-call parameter, the workaround is one agent type per level, such as reviewer-low and reviewer-high, which clutters the agent list.
Confirmed is the changelog line: the Agent tool now has an effort parameter, released alongside items like claude Plugin install --marketplace. Not confirmed are the details. The proposal above suggests the values low, medium, high, xhigh and max, with precedence of per-call effort over agent-definition effort over session level, but that is the content of a proposal; in the sources I found there is no maintainer confirmation of the shipped behavior and no statement of which models support it. Another project's integration notes treat frontmatter as the default and per-call as an override, which is also a user-side reading. For the accepted values and precedence, rely on the official sub-agents documentation or a small test of your own.
Effort directly affects how many thinking tokens are used, and thinking tokens are billed at the output price. Lowering effort for low-risk, repetitive subtasks (scanning files, format checks, extracting fields) and raising it for the few reviews that need judgment is a way to spend budget where it counts. It follows the same logic as pairing small models like Haiku 5.5 with subagents: different subtasks deserve different costs. There are no official figures yet on how much each level saves, so the benefit is yours to measure.
If your team runs many subagents, first measure a one-week baseline: average tokens and cost per agent. Then pick the most repetitive agent, run the same batch with a lower per-call effort, and compare quality and billing. Change defaults only if quality holds and cost really drops. Until there is official per-level data, treat how much it saves as a hypothesis and verify it against your own bill.