Design additive prompt layering for app agent personas

[opencode-agent]

Summary

OpenCode V2 currently treats a configured agent system prompt as a replacement for the model-family OpenCode system prompt. That is surprising for embedded/chat products such as OpenCode Agent: a short Discord/Slack persona can accidentally remove the baseline coding-agent behavior.

We should design a clearer prompt layering model before changing behavior.

Current observed behavior

In V2 request assembly, a non-empty agent system replaces the provider/model-family prompt:

system: [
  agent.info?.system ? agent.info.system : SessionRunnerSystemPrompt.provider(model),
  system.baseline,
]

So a Discord persona like “be a concise teammate in chat” becomes the privileged system prompt instead of being added after the standard OpenCode prompt.

Design directions to gang-grill

1. Additive app/persona instructions by default

   • Always include SessionRunnerSystemPrompt.provider(model).
   • Add app/channel persona as a separate later system part.

2. Split replacement from additions

   • Example fields: systemOverride vs instructions / persona.
   • Replacement stays possible, but has to be explicit.

3. Named prompt stack

   • Model/provider base prompt
   • Selected agent behavior
   • App/channel persona
   • Durable session baseline/context
   • UI/debug surfaces can show each layer separately.

Why this matters

• Embedded agents need product/chat persona without losing core OpenCode behavior.
• Debugging “why did the agent behave this way?” needs visibility into the effective prompt stack.
• Future app integrations should not have to copy/paste or manually preserve the base coding prompt.

Source discussion

Discord thread: https://discord.com/channels/1391832426048651334/1521895759694270584

This issue is intentionally tagged gang-grill so we can collect design topics and later run a focused team discussion without pinging everyone immediately.

[kitlangton]

Replacement semantics are still present and covered by tests, so the design question remains open. #34941 now gives embedders an additive per-session context seam, while #34721 tracks the concrete agent-system bug.

The remaining scope here is the agent configuration contract: explicit override versus additive instructions, ordering relative to provider and durable context, and whether the effective prompt stack needs inspection/debug visibility.

[opencode-agent]

Consolidated #34721 here. Preserve its concrete requirement: hosted/custom agents need a supported additive persona/instruction path without dropping the stock provider/model prompt. Verify both V2 and any still-applicable current/V1 behavior after the design lands.