Claude Code Subagent Effort: Overrides, Resumed Tasks and Model Limits

Choose between a reusable default and a request for one task

To give a custom subagent a reusable effort setting, add effort to its YAML frontmatter. For a different level on one delegation, Claude Code 2.1.292 or later lets you ask Claude to invoke a non-fork subagent at that level; Claude can pass the parameter through the Agent tool.

Released on October 6, 2026 at 18:59 UTC, version 2.1.292 adds the option to specify effort for an individual invocation. Definition fields provide a reusable default, while invocation parameters apply to one task. How they take effect also depends on the environment and model rules in the current documentation.

Check the environment before the invocation and definition

First check whether CLAUDE_CODE_EFFORT_LEVEL is set in the environment that launches Claude Code. It takes precedence over both the subagent definition and the per-invocation parameter. Editing the definition's effort field alone cannot override it.

Without that environment override, effort passed for a non-fork invocation takes precedence over the definition's effort field, which in turn overrides the session setting. Follow that order when troubleshooting instead of assuming the session's selected level is the final value for every subagent.

Per-invocation effort stays in effect when the same subagent is resumed. Resuming does not remove the environment variable's higher precedence, however, so do not assume that returning to a task automatically restores the definition's default.

Confirm the version and model, then choose where to set effort

First, confirm your Claude Code version. Per-invocation effort requires 2.1.292 or later. A missing parameter in an older version is a different issue from a malformed definition file.

Next, identify the model the subagent actually uses and check which effort levels it supports. The current subagent reference lists low, medium, high, xhigh and max while explicitly making availability model dependent. It does not provide a universal compatibility table for every model and provider.

Finally, choose the scope of the setting. Put a reusable default in the definition's effort field, such as effort: high when the model supports high. For one delegation, state the desired level in your request so Claude can pass it at invocation. The definition still needs valid name and description fields and frontmatter; effort alone is not a complete definition.

A hypothetical example: one reviewer, two bounded tasks

Suppose a review subagent uses a model that supports both low and high, and its definition defaults to high. You could keep that default for a close review of a clearly bounded module. For a separate task that only locates where a configuration value is defined, you could ask Claude to invoke that non-fork subagent with low effort. This example illustrates configuration choices; it does not promise that a level will be faster or complete the task successfully.

With no environment override, low on the second invocation overrides high in the definition and persists when that task is resumed. If CLAUDE_CODE_EFFORT_LEVEL is set, account for that higher-priority setting first. Changing effort does not also change the model or the tools the task is allowed to use.

Keep effort separate from model selection, thinking and forks

Model selection and effort are separate settings. A subagent can receive a model through its invocation, definition or environment settings, or inherit the main conversation's model. Organization allowlists and model-forcing settings can also constrain the result. Establish the actual model before checking its supported effort levels; CLAUDE_CODE_SUBAGENT_MODEL is not the environment override for effort.

Extended thinking has its own rule: current documentation says that since 2.1.198, subagents inherit the main conversation's extended-thinking configuration, with no separate per-subagent thinking setting. A fork inherits the main session's model, system prompt, tools and history. The documented per-invocation effort behavior explicitly concerns non-fork subagents, so it should not be assumed to apply independently to forks.

Use task details to inspect configuration, not infer performance

While a subagent is running, the official documentation describes using /tasks to see its actual model and any effort level configured for it on the task's row. That display requires 2.1.242 or later. It helps inspect configuration; it does not measure reasoning, answer quality or elapsed time.

If the display differs from your expectation, review the environment variable, invocation request, definition and actual model. Subagents make their own requests that count toward the main conversation's usage limits. These sources provide no effort-based price or performance guarantee. Choose a lasting default with your task requirements and the current model documentation in mind.