feat(opencode): monitor delivery via opencode-sentinel plugin

[tsukimiya]

What

Adds monitor mode to the opencode agent type, routing real-time delivery through the opencode-sentinel plugin's sentinel_monitor tool (same shape as Claude Code's Monitor tool). Falls back to turn-mode self-checks when the plugin is absent.

Why

opencode has no built-in Monitor-tool equivalent, so until now it could only use turn or off — messages wait until the next tool call to surface. With the external opencode-sentinel plugin installed, opencode sessions gain a resident command-runner whose stdout lines arrive as steer notifications even in idle sessions — exactly what agmsg's watch.sh needs to stream incoming messages in real time.

The rule instructs the agent to launch watch.sh under sentinel_monitor at session start (or on /agmsg), passing $SENTINEL_SESSION_ID so the watcher persists its watermark per session. watch.sh is runtime-agnostic and tolerates an empty session-id arg, so the command is safe even when the variable is unset. A fallback (turn-mode self-poll) is included for when sentinel_monitor is unavailable.

Scope

• scripts/drivers/types/opencode/type.conf: monitor=yes, delivery_modes=monitor turn off
• scripts/drivers/types/opencode/_delivery.sh: monitor case writes the sentinel_monitor rule; status reports mode from rule content
• scripts/drivers/types/opencode/template.md: monitor added to the mode picker, plus an "ensure monitor is running" step and the actas/drop watcher-switch flow
• tests/test_delivery.bats: monitor-mode coverage (rule content, status, turn→monitor rewrite, both still rejected)
• README.md / README.ja.md / docs/opencode.md: monitor listed as supported via the plugin, with the turn-fallback note

Depends on the companion spawn PR (#546) — the two commits below it are that PR's.

Tests

bats tests/test_delivery.bats -f opencode → 9/9 pass.

Related

• Companion spawn PR: fix(spawn): keep opencode worker resident via TUI --prompt instead of run --interactive #546
• opencode-sentinel plugin: https://github.com/tsukimiya/opencode-sentinel

[Copilot]

Pull request overview

Adds a new monitor delivery mode for the OpenCode agent type by generating an OpenCode rule that instructs use of the external opencode-sentinel plugin’s sentinel_monitor tool to run watch.sh, with a documented fallback to turn-based self-checks when the plugin/tools aren’t available.

Changes:

• Enable OpenCode monitor delivery mode (delivery_modes=monitor turn off) and generate a corresponding rule file + status detection.
• Update the OpenCode command template and documentation to describe monitor-mode setup and watcher management flows.
• Extend Bats coverage for OpenCode delivery and spawn command shape (--prompt).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/test_spawn.bats	Updates spawn assertion to expect opencode --prompt form.
tests/test_delivery.bats	Adds monitor-mode tests (rule content, status, rewrite behavior).
scripts/drivers/types/opencode/type.conf	Enables monitor and switches spawn CLI to opencode + prompt_arg=--prompt.
scripts/drivers/types/opencode/template.md	Adds monitor to the mode picker and documents how to start/switch the watcher.
scripts/drivers/types/opencode/_delivery.sh	Implements monitor/turn/off rule writing and status derivation from rule content.
README.md	Updates OpenCode support statement (monitor via plugin; spawn via --prompt).
README.ja.md	Japanese README parity update for OpenCode support statement.
docs/opencode.md	Documents monitor mode via opencode-sentinel and spawn via --prompt.
docs/agent-types.md	Updates prompt_arg docs to include opencode’s --prompt.

Comments suppressed due to low confidence (2)

scripts/drivers/types/opencode/template.md:128

• Same as the main monitor command: use "${SENTINEL_SESSION_ID:--}" so watch.sh receives a stable argv even if SENTINEL_SESSION_ID is empty/unset.

      - command: `~/.agents/skills/__SKILL_NAME__/scripts/watch.sh "$SENTINEL_SESSION_ID" "$(pwd)" opencode <name>`

scripts/drivers/types/opencode/template.md:139

• Same as the main monitor command: use "${SENTINEL_SESSION_ID:--}" so watch.sh receives a stable argv even if SENTINEL_SESSION_ID is empty/unset.

   - command: `~/.agents/skills/__SKILL_NAME__/scripts/watch.sh "$SENTINEL_SESSION_ID" "$(pwd)" opencode`

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tsukimiya]

Thanks @copilot — all six comments addressed in e03fe89:

• "$SENTINEL_SESSION_ID" → "${SENTINEL_SESSION_ID:--}" at all four sites (_delivery.sh + template.md x3). watch.sh documents that some launcher shells drop a quoted-but-empty first arg and shift later parameters; it recommends the ${VAR:--} sentinel (same shape it asks grok-build callers to use for GROK_SESSION_ID).
• template.md actas/drop now explicitly say to skip the sentinel_* tool calls when the plugin is unavailable, instead of assuming the tools exist whenever mode=monitor.
• README.md / README.ja.md delivery-modes table updated: the monitor row notes OpenCode requires the plugin; the turn row scopes OpenCode to the plugin-not-installed case (the template picker now defaults to monitor when the plugin is present).

The macos-latest failures (watch: restart delivers messages..., watch: persists a watermark file..., launcher: a replacement dispatcher...) are pre-existing flakiness on main — #541 is still open for the watch-suite sleeps, and the launcher test is unrelated to this PR's changes. Ubuntu/Windows jobs are green.

[fujibee]

@tsukimiya

Both of these are in. Thank you — between them opencode goes from "spawn does not stay up" to a type with a real-time delivery path, and the analysis in each PR made them quick to review.

They landed from branches in this repository (#569 and #570) rather than by merging your PRs directly. That is mechanical, not a judgement: the bats suite was split into shards after your PRs last ran, which renamed the required status check, so the required context could never report on those heads and GitHub held them blocked regardless of content. The red macOS job you may have seen on #546 was not a real failure either — it was the watch: persists a watermark file flake, from a run that predates the fix for it. Rather than ask you to rebase for our CI churn, we moved the commits.

Your commits were cherry-picked, not rewritten, so they land under your authorship — you can see your name on all six on main. We also checked equivalence rather than assuming it: each commit's git patch-id --stable matches its original.

Two commits on #570 are ours, and we want to be explicit about what they changed and why.

Wording. The docs said monitor "never silently drops messages". agmsg writes the rule but does not detect whether sentinel_monitor exists, so the fallback is an instruction the agent follows rather than a code path agmsg enforces — an agent that ignores it delivers nothing, and nothing reports that. The text now says monitor degrades to turn, states what is and is not guaranteed, and names turn as the mode to choose when delivery must not depend on an agent honouring a rule. The design is unchanged and we think it is the right one for the constraint; only the promise was adjusted to match what the code can keep. We would rather tell you we edited your wording than have you find it later.

Quoting. The generated commands wrapped the project path in literal single quotes. delivery.sh accepts an apostrophe in a path because it is a legal POSIX character, and such a path ended the quoted argument early in both the watcher command and the fallback — which also made shell metacharacters after it live. The path now goes through printf '%q' once and is used in all three generated commands. The regression parses the generated lines with bash -n, so it fails on a broken quote rather than on a wording change. This is the same class as an existing gap we are tracking in #550; opencode is now off that list because it is fixed.

Also noting that the two points from the automated review — the missing cmd_prefix=$ and the test ordering — were already addressed in 762ad02 before we picked it up. That fix is what makes the spawned actas prompt use $agmsg rather than the Claude Code spelling, so it mattered.

Closing both in favour of #569 and #570. The work is yours; only the branches are ours.