Cursor subagents ignore the model you set: why model frontmatter and fast=false don't stick

Last verified: November 22, 2026
You give a custom Cursor subagent its own model, start a task, and the subagent card shows something else: a Composer 2.5 Fast run you never asked for, the parent chat's model, or Auto. Developers have reported this on the Cursor forum since June 2026, across Windows, macOS, Linux and the CLI, and Cursor staff have confirmed in several threads that the behavior is unintended and tracked.
The short version is that the model you write in an agent file is a default, and several things can override it. The most common one is the parent agent naming a model when it launches the subagent, which wins over your file. The others are a model string Cursor cannot resolve, which falls back silently, a missing variant option that lets the backend apply Fast, plan and admin rules, and agents installed from a marketplace plugin, whose model field Cursor does not apply at the moment. Each one has a different check and a different fix, and some are already fixed on Cursor's side.
··········
HOW CURSOR DECIDES WHICH MODEL A SUBAGENT RUNS.
A subagent is a helper agent that the main chat (the parent) starts to handle part of a task, such as searching the codebase or reviewing a change. Cursor ships built-in subagents like Explore, which by default uses a faster model to run many searches in parallel, and lets you define custom ones as Markdown files with a short YAML header at the top, called frontmatter.
According to the official subagents documentation, custom subagents live in `.cursor/agents/` inside a project or in `~/.cursor/agents/` for every project of the current user. Cursor also reads `.claude/agents/` and `.codex/agents/`, and project files win over user files with the same name.
The `model` field is optional and defaults to `inherit`, which means the subagent uses the parent's model. Any other value must be a model ID, optionally followed by options in square brackets. The documentation lists these forms:
........
Value in the model field | What the documentation says it does |
inherit (default) | Uses the same model as the parent agent |
composer-2 or gpt-5.6-sol | Runs that specific model ID |
composer-2.5[] | Pins the base model; empty brackets select the standard variant instead of the fast one |
composer-2.5[fast=false] | Selects the standard, non-fast variant explicitly |
claude-opus-5[effort=high] | Sets reasoning effort to high |
claude-opus-5[effort=high,context=300k] | Combines several options, separated by commas |
........
The same page states that Cursor honors the `model` value unless the team admin has blocked that model, the model needs Max Mode on a legacy request-based plan that does not have it, or the model is not included in the current plan. In those cases Cursor falls back to a compatible model. The subagent task card shows which model actually ran, and the usage dashboard lists the same model on the matching row, which gives you two places to check every fix below.
··········
WHY A CURSOR SUBAGENT RUNS ON THE WRONG MODEL: CAUSES TABLE.
The causes below come from the official documentation and from replies by Cursor team members in the forum threads where users reported the problem. The last column says where each one stands as of the newest replies.
........
Cause | How to check | Fix | Status |
The parent agent named a model when it launched the subagent | The task card shows a model that is neither your file's model nor the parent's | Add a User Rule telling the agent never to specify a model for subagents | Known issue, tracked |
The model string cannot be resolved (typo, wrong option name) | The subagent silently runs on the parent's model | Copy the ID from the models reference; use the right option key | Silent fallback by design |
A Composer 2.5 pin without brackets | The card or dashboard shows Composer 2.5 Fast | Write composer-2.5[fast=false] or composer-2.5[] | Fix announced in October |
The agent comes from a marketplace plugin | Plugin agents ignore model; a local copy behaves | Copy the agent file into .cursor/agents/ or ~/.cursor/agents/ | Open as of November 5 |
Plan or admin rules | Legacy request-based plan without Max Mode, or the model is blocked by the team | Enable Max Mode, ask the admin, or pick an allowed model | Documented behavior |
Built-in Explore subagent ignores its Settings model | Explore runs on another model than the one picked in Settings | Set Explore to inherit from the parent, or run the parent on standard Composer 2.5 | Known issue, tracked |
Some new models started on Auto | Subagents set to Grok 4.7 or Gemini 3.8 Flash ran on Auto | No action needed; Cursor says it fixed this server-side | Fixed October 1 |
........
··········
FIX 1: STOP THE CURSOR PARENT AGENT FROM CHOOSING THE SUBAGENT MODEL.
When the parent hands off a task, it can include a model in the call that starts the subagent, and that explicit model takes priority over the frontmatter and over the Settings picker. A Cursor team member described one such case in August: the agent itself picked the model when handing off the task, independently of the picker or settings. In September another team member confirmed that an explicit model in the subagent call currently takes precedence and that the issue is tracked.
The workaround Cursor staff gave in both threads:
1. Open Cursor Settings and add a User Rule such as "When launching subagents, never specify a model. Always inherit the current chat's model." If your subagents use a pinned model from their agent file, word the rule as "never specify a model; use the model set in the agent file".
2. Start a new chat so the rule is loaded, run the task again and read the model name on each subagent card.
3. If a specific model keeps appearing, staff also suggested disabling it under Cursor Settings > Models. They added that this applies to local IDE subagents and may not hold for Cloud Agents.
A rule is an instruction to the model and lowers the frequency without guaranteeing the result, so check the task cards for a few runs.
··········
FIX 2: CHECK THE CURSOR MODEL STRING AND ITS OPTIONS.
When Cursor cannot resolve the value in `model`, it does not show an error. A Cursor team member wrote in July that an invalid model silently falls back to the parent agent's model, and another staff reply in November gave a concrete case: for Grok 4.7 the option key is `reasoning_effort`, so a pin written with `effort=high` does not resolve and the subagent quietly runs on something else.
The frontmatter below is illustrative, built only from the fields and values in Cursor's subagents documentation:
---
name: planner
description: Plans multi-step changes before any file is edited.
model: claude-opus-5[effort=high]
readonly: true
---To check yours:
1. Copy the model ID from Cursor's models reference instead of typing it from memory, and keep the exact spelling and version.
2. Check that each option inside the brackets exists for that model. The documentation says available options depend on the model and use the same `id=value` pairs as the SDK's model parameters.
3. Run the subagent once and compare the task card with your file. If the card shows the parent's model, the string did not resolve.
4. The CLI behaves the same way: a Cursor team member reproduced the silent fallback in cursor-agent in June.
··········
FIX 3: CURSOR COMPOSER 2.5 SUBAGENTS RUNNING AS COMPOSER 2.5 FAST.
Composer 2.5 has a standard and a Fast variant. A Cursor team member explained in June that the backend still applies the default `fast=true` when the variant is not stated, and in July that `model: composer-2.5` without brackets can silently fall back to Fast. The documented way to pin the standard variant is `composer-2.5[fast=false]`, or `composer-2.5[]` with empty brackets.
From September, users reported a second form of the problem: with the parent chat on a different model, such as Grok 4.7, Composer subagents ran and were billed as Composer 2.5 Fast even with the `[fast=false]` pin. Cursor staff called it an issue they were tracking and said it was not a misconfiguration. On October 21 a team member wrote that a fix had landed, partly server-side, with the rest included in an upcoming version of Cursor, and on October 31 that it should be fixed on Cursor's side. One user reported on November 3 that desktop version 3.28.7 worked, while another wrote on November 18 that some issues remained, with the app showing a Fast label on a run she said was not billed as Fast.
What to do now:
1. Update Cursor to the latest version, since part of the fix ships in the app.
2. Write the pin with brackets: `composer-2.5[fast=false]`.
3. If Composer subagents still show as Fast, the workaround staff gave before the fix was to run the parent chat on Composer 2.5 with Fast turned off. One user confirmed this as the reliable way to keep subagents on the standard variant; toggling Fast on and off in the picker did not help him in three attempts.
4. Check the usage dashboard row for the subagent, which shows the model that was billed.
··········
FIX 4: CURSOR MARKETPLACE PLUGIN AGENTS AND THE MODEL FIELD.
Agents installed as part of a marketplace plugin are a separate case. A Cursor team member first said in August that the behavior was unexpected and related to subagent model resolution in general, then wrote on November 5 that for agents that come from a plugin, `model` in the frontmatter is not applied right now.
The workaround from the same reply, confirmed by one user on Linux:
1. Find the plugin's agent file and copy it into `.cursor/agents/` in the project or `~/.cursor/agents/` for all your projects.
2. Give the copy its own name if you keep the plugin installed, so the two definitions are easy to tell apart.
3. Start the copied agent and confirm on the task card that it runs on the model in its frontmatter. Another user reported that pointing to the plugin file through a symlink did not help.
··········
FIX 5: CURSOR PLAN RULES, MAX MODE AND THE BUILT-IN EXPLORE SUBAGENT.
Some fallbacks are documented behavior. Cursor's subagents FAQ says that on legacy request-based plans without Max Mode, subagents run using Composer regardless of any `model` configuration, and that on usage-based plans, or legacy plans with Max Mode, subagents default to the parent model. A Cursor team member called this plan policy and said Max Mode on the parent removes it. If your admin has blocked Composer on a legacy plan, subagents run only with Max Mode enabled.
The built-in Explore subagent has its own model picker in Settings. Cursor staff confirmed between July and August that this picker does not always respect the selected model and that the issue is tracked without a date. The two workarounds given in October were setting the Explore subagent model to "Inherit from parent" or running the parent on standard Composer 2.5. The same reply noted that an explicit model in the launch call still takes priority, so Fix 1 applies here too.
........
Situation | Model a subagent runs, per Cursor's documentation and staff |
Usage-based plan, model set to inherit | The parent's model |
Usage-based plan, valid pinned model | The pinned model, unless the launch call names another |
Legacy request-based plan without Max Mode | Composer, whatever the frontmatter says |
Legacy plan with Max Mode | The parent's model by default |
Model blocked by the team admin or not on the plan | A compatible fallback model |
Unresolvable model string | The parent's model, with no warning |
........
··········
DOCUMENTED BEHAVIOR VERSUS CURSOR BUGS STILL OPEN.
Cursor's subagents page documents the default `inherit`, the bracket options, the fallback for admin blocks, Max Mode and plan limits, and the Composer-only rule on legacy plans without Max Mode. The launch-model override, the silent fallback for unresolvable IDs, the plugin agents' ignored model field and the unreliable Explore picker are confirmed only in staff replies on the forum, and no changelog entry was found for them. Staff describe two problems as fixed: Composer 2.5 subagents running as Fast under a different parent model (October 21 and 31, no version number) and subagents set to Grok 4.7 or Gemini 3.8 Flash starting on Auto (server-side, October 1). The residual Fast label of November 18 and the symlinked plugin case are user reports without a staff answer. The reports span Cursor versions 3.8 to 3.28 on Windows, macOS, Linux and the CLI.
··········
HOW TO KEEP CURSOR SUBAGENTS ON THE RIGHT MODEL AFTER UPDATES.
A pin that stops resolving after a release falls back without a warning, so after each Cursor update run one subagent from each custom agent file and compare the task card with the frontmatter. Check the usage dashboard weekly for models you did not configure. Keep agent files in `.cursor/agents/` under version control, so a teammate's change to a model line shows up in review, and pair them with a User Rule about subagent models, which works alongside project rules of the kind described in our guide to why Cursor rules are not applied.
For background on the Composer models that subagents default to, see our explainer on what Cursor Composer 2 is and how its pricing works. If the agent does not start at all on Windows, the cause is a different one, covered in our page on the "agent process didn't respond" error.
··········
CURSOR SUBAGENT MODEL SELECTION: WHAT TO CHANGE TODAY.
The configured model of a Cursor subagent is a starting point that the parent agent, the plan, the admin settings and the plugin system can all replace, and in most of those cases Cursor does not warn you. The fixes that hold up best are the ones staff confirmed: bracket syntax such as `composer-2.5[fast=false]`, model IDs copied from the reference with the right option keys, agent files kept in `.cursor/agents/` instead of a plugin, and a User Rule that stops the parent from naming a model. The Composer Fast routing and the Auto fallback are fixed on Cursor's side, while the launch-model override, the plugin field and the Explore picker remain tracked issues with no date, so the task card and the usage dashboard stay the final check on which model ran.
··········
FOLLOW US FOR MORE.
·····
DATA STUDIOS
·····
datastudios.org




