fix(opencode): gate step-cap assistant message behind maxStepsMessage config

[kevinfaveri]

Issue for this PR

Fixes #32548

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

When an agent hits its step cap, the prompt loop appends an assistant-role message with the "MAXIMUM STEPS REACHED" text. This ends the request on an assistant turn, which counts as a response prefill. Claude models with thinking enabled reject prefills with HTTP 400.

From Anthropic's extended thinking docs, Feature compatibility: "You can't pre-fill responses when thinking is enabled."

I ran into this with bounded subagents in opencode-fusion. Any agent hitting the step cap on a thinking-enabled Claude model gets the same 400.

The fix adds a maxStepsMessage boolean to agent config. Defaults to true, so existing behavior is unchanged. When set to false, the trailing assistant message is not appended.

Three files:

• packages/core/src/v1/config/agent.ts (schema + KNOWN_KEYS)
• packages/opencode/src/agent/agent.ts (runtime field + mapping, defaults true)
• packages/opencode/src/session/prompt.ts (gate: isLastStep && agent.maxStepsMessage !== false)

Important: this relates to many open issues like #13768 and #27920. However, those issues are more broad and don't involve a specific plugin usage (which can happen in scenarios with other plugins or local harness setup using structured outputs or max tools being very limited).

I choose to simply add a possibility that agents can be configured in any way the user want WHEN max steps are reached, avoiding taking any opinion on how it should be handled globally or not (e.g. don't affect the primary model at all). However, if you force your primary model to always call an agent, you could use this new feature to enforce removal of trailling message to fix the above issues OR alternatively you can set all built in agents opencode has to false on this new property so that it don't do message trailling that is what is problematic.

Note: Since plugins can access and set the config for specific agents they can create / dispatch, the idea is that I will use this so that opencode-fusion detects if its a claude 4.6+ model and then disable trailling message on the panel and/or judge.

Note 2, to reinforce: this PR is focused specifically on the edge case of when it reaches max steps, it appends a trailling message that is problematic with thinking on models.

How did you verify your code works?

Config test in test/agent/agent.test.ts: default resolves to true, explicit false resolves to false. Prompt loop tests in test/session/prompt.test.ts: default appends the message, maxStepsMessage: false omits it. Full suites pass locally. turbo typecheck passes all 23 packages. Build compiles on bun 1.3.14.

Checked with my own https://github.com/kevinfaveri/opencode-fusion plugin by setting editing its code to, when setting the unbounded agent that I use for panels and judge to set this maxStepsMessage to false. After this is merged, I will follow up with an updated version of opencode-fusion and edit the Readme.MD there to account for the new setting.

It is very easy to validate locally, by the way, if you want to double check: just set all your agents (built in like build/plan to steps: 1 and set the max steps message to false, which will make it work. Omit (current behavior) or set to true and it will fail loudly). Attached issue has example export et al.

Screenshots / recordings

No UI change.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

Hey! Your PR title Add maxStepsMessage agent option to opt out of the trailing MAXIMUM STEPS REACHED message doesn't follow conventional commit format.

Please update it to start with one of:

• feat: or feat(scope): new feature
• fix: or fix(scope): bug fix
• docs: or docs(scope): documentation changes
• chore: or chore(scope): maintenance tasks
• refactor: or refactor(scope): code refactoring
• test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[github-actions]

Thanks for updating your PR! It now meets our contributing guidelines. 👍