[FEATURE]: Allow project-local agent files to extend (not just replace) the global agent prompt #15773

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

When a project-local agent .md file (e.g., .opencode/agents/retrospective.md) overrides a global agent (e.g., ~/.config/opencode/agents/retrospective.md), the markdown body in the project-local file replaces the global agent's prompt entirely.
This is because loadAgent unconditionally sets prompt: md.content.trim(), and the ?? operator in the agent merge logic (value.prompt ?? item.prompt) treats any non-null string — including "" — as an intentional override.

This means there's no way to create a project-local agent file that:

• Overrides only frontmatter properties (permissions, model, temperature, etc.)
• While preserving the global agent's prompt body

The only workaround is to duplicate the entire global body into every project-local agent file, appending project-specific additions at the end.
This creates maintenance burden — any change to the global agent body must be manually propagated to every project that overrides it.

Concrete example

I maintain a global retrospective agent with a 171-line prompt covering the review procedure, output structure, chezmoi workflow, and rules.

In a specific project, I need to:

1. Add project-specific permissions (allow editing .opencode/agents/* and AGENTS.md, allow git push)
2. Append a small project-specific rule about the project's pre-completion checklist

What I want to write — a lightweight project-local override:

---
permission:
  edit:
    ".opencode/agents/*": allow
    "AGENTS.md": allow
  bash:
    "git push*": allow
---

## Project-Specific Rules

- **Pre-completion checklist** — Run the pre-completion checklist from AGENTS.md before recommending handoff.

What I have to write instead — duplicate the entire 171-line global body into the project-local file, because any body content (even an empty string or HTML comment) silently replaces the global prompt.
The project-local file becomes 177 lines instead of 10.

This pattern repeats across agents — I have the same problem with my TDD agent (105 lines) and build agent (16 lines) in the same project.

Proposed solution

Add a prompt_mode field to the agent config schema, defaulting to replace (current behavior):

---
prompt_mode: extend  # "replace" (default) | "extend"
permission:
  edit:
    ".opencode/agents/*": allow
  bash:
    "git push*": allow
---

## Project-Specific Rules

- **Pre-completion checklist** — Run the pre-completion checklist from AGENTS.md before recommending handoff.

When prompt_mode: extend, the project-local body would be appended to the global agent's prompt rather than replacing it.
The final prompt would be: <global body>\n<project-local body>.

A file with prompt_mode: extend and no body (frontmatter-only) would preserve the global prompt unchanged — solving the "permissions-only override" case as well.

Alternatives considered

1. Empty body = no override — Treat md.content.trim() === "" as "no prompt specified" (skip setting the prompt key). This solves the "permissions-only override" case but doesn't help when you want to add project-specific instructions to the global prompt.
2. prompt_prefix / prompt_suffix fields — More flexible but more complex. prompt_mode: extend covers the common case with a simpler model.
3. Duplicate the global body (current workaround) — Works but creates maintenance burden across multiple projects.

Related issues

• Built-in agent overrides don't fully apply #3895 — Built-in agent overrides don't fully apply (metadata/description not propagated)
• BUG: Overriding built-in agents, doesn't allow overriding permissions #3575 — Overriding built-in agents doesn't allow overriding permissions
• Local agent settings don't override global settings #4217 — Local agent settings don't override global settings (closed as duplicate of Built-in agent overrides don't fully apply #3895/BUG: Overriding built-in agents, doesn't allow overriding permissions #3575)
• [FEATURE]: Allow custom system prompts in global, project or custom directories #7101 — Allow custom system prompts in global, project, or custom directories

These issues cover the broader agent override experience.
This request is specifically about the prompt merge semantics — allowing project-local prompts to extend rather than replace the global prompt.