Clarify plugin guidance for experimental.chat.system.transform to avoid extra system messages

[zhangdw156]

Description

A lot of memory/context plugins use experimental.chat.system.transform by doing output.system.push(...) for recalled context or status blocks.

That is a natural reading of the current hook type, but it can make those plugins incompatible with many model backends that only accept a single system message at the start of the conversation, especially vLLM-served Qwen models and similar OpenAI-compatible deployments.

The hook itself is useful and does not need a behavior change here. What seems to be missing is guidance for plugin authors: if they are adding supplemental prompt/context, they should usually merge it into the primary system block instead of pushing a new array entry.

Plugins

Memory and context injection plugins using experimental.chat.system.transform

OpenCode version

Current dev branch as of 2026-04-21

Steps to reproduce

1. Implement a plugin that injects recalled context with output.system.push(...) inside experimental.chat.system.transform
2. Use that plugin with an OpenAI-compatible backend that only allows a single system message
3. Send a request
4. The backend rejects the request because multiple system messages were produced

Screenshot and/or share link

No response

Operating System

No response

Terminal

No response

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Qwen/Qwen3.5-397B-A17B: system message must be at the beginning #20785: Describes the same root problem — a plugin using experimental.chat.system.transform to push additional system message entries causes Qwen/vLLM-compatible backends (which only accept a single system message at the start) to reject the request with "system message must be at the beginning". The symptoms and affected backends are identical.

If your issue is the same, please consider adding your context there. If it's meaningfully different (e.g. you're specifically requesting documentation/guidance for plugin authors rather than reporting a runtime error), please clarify that distinction in this issue.

[zhangdw156]

Related, but narrower: issue-20785 reports the runtime failure itself. This issue is specifically asking for plugin-author guidance on experimental.chat.system.transform so plugin authors avoid creating extra system-message entries in the first place. No hook behavior change requested here, only clearer guidance/docs for plugin authors.