[Anooshiravan]

Issue for this PR

Closes #32548

Type of change

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

What does this PR do?

When an agent hits its step cap, opencode appends a "MAXIMUM STEPS REACHED" notice to the request with role: "assistant". Providers treat a trailing assistant message as a prefill — something the model should continue, not instructions to follow. So instead of summarizing its work, the model just emits a stop token and the turn ends empty. On Claude with thinking enabled it's worse: the request 400s, because you can't prefill an assistant turn that's supposed to start with a thinking block.

The notice is an instruction, so it belongs in a user message. Changing the role to "user" makes the model read it as instructions and actually produce the summary.

Two call sites, both changed:

• packages/opencode/src/session/prompt.ts (V1)
• packages/core/src/session/runner/llm.ts (V2)

How did you verify your code works?

• packages/opencode/test/session/prompt.test.ts — added loop sends max steps instruction as a user message. 57 pass.
• packages/core/test/session-runner.test.ts — the existing forces a text response on an agent's configured final step test asserted role: "assistant", which locked the bug in. Updated to "user". 80 pass.
• bun turbo typecheck — 29/29.

Screenshots / recordings

Not a UI change.

Checklist

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

Related

• fix(opencode): gate step-cap assistant message behind maxStepsMessage config #32546 — alternative approach, gates the message behind a config flag.
• fix: send max-steps instruction as user message, not assistant #36970 — duplicate V1-only fix by @rguliyev, closed in favor of this one. Their regression test is folded in here.

[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]

The following comment was made by an LLM, it may be inaccurate:

Based on my search, I found one potentially related PR:

Related PR:

• fix(opencode): gate step-cap assistant message behind maxStepsMessage config #32546 - fix(opencode): gate step-cap assistant message behind maxStepsMessage config
  • fix(opencode): gate step-cap assistant message behind maxStepsMessage config #32546
  • This PR addresses the same step-cap assistant message issue but with a different approach (gating behind config rather than changing the role to user)

This PR appears to be related to the same problem area (step cap messages), though it takes a different solution approach. The current PR (#34276) fixes the issue by changing the message role from assistant to user, whereas #32546 gates the message behind a config option.

[rguliyev]

Independent confirmation this fix is correct and needed: hit this exact
bug in production overnight, traced it back to this exact line
(prompt.ts isLastStep branch appending role: "assistant") before
finding this PR already existed.

Data point that might help build a case for merging: searched our own
opencode instance's message history for the literal error text across
the last 24h. It's not model- or provider-specific — hit it on every
model we use in proportion to usage (Claude, GPT, Gemini), all with
zero-cost/zero-token failed turns tracing to this same code path. This
isn't an edge case limited to thinking-enabled Claude models or one
provider; it's a general request-shape bug that fires whenever the step
cap is reached mid-turn with the wrong role, regardless of backend.

This PR (and the V2 fix alongside it) also happens to fully address it —
opened a duplicate (#36970, now closed in favor of this one) with the
same V1 role fix plus a regression test in prompt.test.ts asserting
the appended max-steps message is role: "user", in case a test is
useful to fold in here.

Given three PRs (#32546, this one, and the now-closed duplicate) have
been open against #32548 for close to a month with no maintainer review,
would be great to get eyes on this — it's a real, frequently-hit
reliability bug, not a rare edge case.

[github-actions]

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

• PR description is missing required template sections. Please use the PR template.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

This pull request has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new pull request that follows our guidelines.

[SConaway]

@Anooshiravan any chance you're interested in re-opening this PR?

[Anooshiravan]

@SConaway I'd reopen it if I could, but GitHub won't let me — it 422s from both the CLI and the REST API. A brand-new PR is the only option.

I'm not keen on that. All three PRs against #32548 — #32546, #36970 and this one — were closed without a single maintainer comment. Mine got auto-closed by the template bot two hours after it flagged me. Refiling just restarts that clock.

For what it's worth, the fix is still valid: both call sites on dev still send the notice with role: "assistant" (packages/core/src/session/runner/llm.ts, packages/opencode/src/session/prompt.ts), #32548 is still open, and the four lines here apply with no conflicts. I've also filled in the template sections the bot closed this for.

If a maintainer says they'll look, I'll open a fresh PR the same day. Until then anyone who needs it can cherry-pick from my branch.