feat: add max steps for supervisor and sub-agents

[nwthomas]

Problem

See #3631 for more details about this feature. From the issue:

"We want to add a maxSteps constraint to prevent costly large iteration loops for the supervisor and sub-agents.

On the maxSteps - 1 loop iteration, it should kick out of any sub-agent tool calls and return a text response."

Solution

I went nine rounds in the ring with the AI harness for OpenCode and figuring out the most consistent way to enforce this behavior across many models (tried mainly Grok code Fast, Big Pickle, and GPT OSS 20B and Qwen3 30B which I am locally hosting).

I tried removing tools from the calls on the final step(s) and paired it with a system prompt, but I consistently had models ignore the system prompt and even lack of activeTools and tools values, resulting in breaking attempts to call tools that were not defined.

I also tried the Vercel AI SDK toolChoice param (since we're using that package), but I also found that models universally ignored that request.

What did work every time was conditionally placing both a system prompt and an assistant prompt on the last step. With both of these combined, all models I've tested respect the maxSteps limit and instantly return a text-based summary of actions taken and recommended next steps.

I've also taken the liberty of updating the website documentation for this feature.

Testing

	Windows	MacOS	Linux
With maxSteps = 4	Screen.Recording.2025-11-17.at.6.39.07.PM.mov	Screen.Recording.2025-11-17.at.6.49.45.PM.mov	Screencast.from.2025-11-17.19-08-05.webm
Without maxSteps in config	Screen.Recording.2025-11-17.at.6.40.15.PM.mov	Screen.Recording.2025-11-17.at.6.51.02.PM.mov	Screencast.from.2025-11-17.19-11-20.webm

[nwthomas]

Used for both the system prompt concat and also the new conditional assistant message

[nwthomas]

Conditional addition of the system prompt

[nwthomas]

Conditional addition of a new `assistant message. See PR description for more logic about why I went this route.

[nwthomas]

If maxSteps is undefined, this value will not cap agentic actions

[rekram1-node]

/review

[rekram1-node]

/oc use docs agent to update the example for max_steps it should only show an example for a subagent, dont show the setting being applied to general, plan or build

[opencode-agent]

Done! The docs agent has updated the max_steps example in packages/web/src/content/docs/agents.mdx to only show it being applied to a subagent (the "general" subagent). Examples showing max_steps applied to general, plan, or build primary agents have been removed.

opencode session  |  github run

[rekram1-node]

/oc use docs agent to update the max steps example to show a custom agent w/ max steps set, does have the example use any default agent we provide, this custom agent can be completely stupid it doesnt have to be real and the prompt for it can be super super simple too

[opencode-agent]

Perfect! The example has been successfully updated. The max steps section now shows:

✅ A custom agent named quick-thinker (not using any default agents like "general", "build", or "plan")
✅ A simple prompt - "You are a quick thinker. Solve problems with minimal steps."
✅ maxSteps set to 5 - demonstrating the configuration
✅ A description - "Fast reasoning with limited iterations"

The explanation text about what max steps does remains unchanged, and this is now the only example shown for this feature.

opencode session  |  github run