Repository navigation
[FEATURE]: headless prompt-mutation hook for opencode run (parallel to tui.prompt.append) #27899
Description
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.appendoragent.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:
- Install opencode-ai 1.15.1 locally.
- Create
.opencode/plugin/test.jsthat registers
tui.prompt.append, appends a token to the prompt, and logs to
a file. - Run
opencode run "echo your prompt verbatim"and inspect the
log.plugin.initfires;tui.prompt.appenddoes 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
Activity
github-actions commentedon May 16, 2026
This issue doesn't fully meet our contributing guidelines.
What needs to be fixed:
[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:
opencode run) equivalent, so they may be complementary rather than duplicates.If you believe this was flagged incorrectly, please let a maintainer know.
[-]Feature request: headless prompt-mutation hook for opencode run (parallel to tui.prompt.append)[/-][+][FEATURE]: headless prompt-mutation hook for opencode run (parallel to tui.prompt.append)[/+]github-actions commentedon May 16, 2026
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 commentedon May 19, 2026
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 (wrapopencode runfrom a parent process) that doesn't require this to land.github-actions commentedon Jul 19, 2026
To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.