[FEATURE]: headless prompt-mutation hook for opencode run (parallel to tui.prompt.append)

[haabe]

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

opencode 1.15.1 documents tui.prompt.append as a plugin hook for
mutating the outbound prompt before it reaches the model. In the
interactive TUI this is exactly what frameworks need to inject
session-level context (pre-task checklists, project conventions,
guardrails) without the user having to repeat it every turn.

In opencode run (headless mode), the hook is silently inert.
plugin.init fires, but tui.prompt.append never does. Consistent
with the tui.* namespace, fine. But it leaves no documented
headless equivalent for prompt mutation.

Use case: frameworks like Mycelium (theory-grounded agent harness,
https://github.com/haabe/mycelium) want one plugin that injects
pre-task context whether the user is in TUI or running headless via
opencode run from a parent process.

Possible shapes:

• A new event like session.prompt.append or agent.prompt.before
  that fires in both modes.
• A documented promotion of an existing event (session.created,
  agent.start) to cover prompt mutation in headless.
• Explicit docs that no such hook exists and the supported pattern
  is config-level system-prompt injection.

The asymmetry between TUI and headless plugin surfaces is worth
calling out in the docs either way, even if the design intent is
"headless agents don't get prompt mutation."

Related: #27813 covers TUI-side projected session hooks; this
request is the headless counterpart. Likely complementary, not
duplicate.

Reproduction:

1. Install opencode-ai 1.15.1 locally.
2. Create .opencode/plugin/test.js that registers
   tui.prompt.append, appends a token to the prompt, and logs to
   a file.
3. Run opencode run "echo your prompt verbatim" and inspect the
   log. plugin.init fires; tui.prompt.append does not.

Verified 2026-05-16 with local Ollama provider (no API auth issues)
against llama3.1:8b. Full reproduction context:
https://github.com/haabe/mycelium/blob/main/docs/receipts/cases/2026-05-16-opencode-phase1-runtime.md

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• Feature requests must use the Feature Request template, which requires a verification checkbox confirming the feature hasn't been suggested before
• The issue title should start with [FEATURE]: (e.g. [FEATURE]: headless prompt-mutation hook for opencode run)

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

---

This issue might be related to an existing issue. Please check:

• [FEATURE]: TUI plugin API: projected-session prompt hooks and session notice slot #27813: Similar request for TUI plugin API prompt hooks and session notice slot — while that issue focuses on TUI-side projected session hooks, yours focuses on the headless (opencode run) equivalent, so they may be complementary rather than duplicates.

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

[github-actions]

Thanks for updating the issue! It now follows the contributing guidelines and feature request template. We appreciate the clear description, reproduction steps, and the context around your use case.

[haabe]

Happy to draft a PR if it'd help. The design surface here matters more than the implementation (where the event fires in the headless lifecycle, payload shape, interaction with existing tui.prompt.append), so a one-line steer from a maintainer on the preferred shape would save a round-trip. Otherwise no rush from my side — I have a Mycelium-side workaround pattern (wrap opencode run from a parent process) that doesn't require this to land.