Follow up OpenCode upstream updates: notification/permissionDenied hook mappings, references key, V2 beta tracking

[dyoshikawa]

Summary

Three OpenCode drifts as of v1.18.14: two canonical hook events (notification, permissionDenied) have faithful upstream plugin counterparts but are unmapped, and the stable references config key — a genuine context-provisioning surface — has no rulesync coverage. Additionally, the OpenCode V2 beta restructures nearly every key rulesync emits and deserves a tracking note.

Canonical repo note: sst/opencode 301-redirects to anomalyco/opencode (same repository id). Latest stable at research time: v1.18.14 (2026-08-05).

Recent Releases

• v1.18.14 (2026-08-05) — latest stable — https://github.com/anomalyco/opencode/releases
• v1.17.4 (2026-06-12) — MCP cwd for local servers (already followed).
• v1.17.1 (2026-06-10) — reference renamed to references (gap 3 below).
• V2 beta — separate opencode2 binary via @opencode-ai/cli@next — https://opencode.ai/v2/docs (gap 4).

Gaps

1. hooks — canonical notification unmapped despite tui.toast.show

• Upstream: the plugin API exposes tui.toast.show (payload: message, variant info/success/warning/error, optional title, duration) — https://opencode.ai/docs/plugins/
• rulesync (project, global): notification is mapped for many other tools but absent from OPENCode_HOOK_EVENTS (src/types/hooks.ts:323) and CANONICAL_TO_OPENCODE_EVENT_NAMES (:1115), so OpenCode users get no plugin stub for it.
• Follow-up: add notification to the event set and map it to tui.toast.show.

2. hooks — canonical permissionDenied unmapped despite permission.replied

• Upstream: permission.replied carries sessionID, requestID, and reply ("once" | "always" | "reject"), so denial is distinguishable — https://opencode.ai/docs/plugins/
• rulesync: maps permissionRequest → permission.asked but nothing to permission.replied.
• Follow-up: gate on reply === "reject" using the same mechanism as SHELL_EVENT_TOOL_GATES in src/features/hooks/opencode-style-generator.ts. Because KILO_HOOK_EVENTS aliases the OpenCode set (src/types/hooks.ts:345), this lands for Kilo too.

3. rules — the references config key has no coverage

• Upstream: references (stable V1; renamed from deprecated reference in v1.17.1) maps an alias to a local path or a git repository (+ branch), with description and hidden; entries carrying a description are injected into the agent's system context automatically — a context-provisioning surface alongside instructions, not just autocomplete. https://opencode.ai/docs/references/
• rulesync: writes instructions into opencode.json but never touches references.
• Follow-up: discretionary — decide whether rulesync should author references (most likely via a tool-scoped opencode section). This is a new capability rather than a fix.

4. Forward-looking — V2 beta restructures nearly every emitted key

Per https://opencode.ai/v2/docs/migrate-v1: permission/tools → ordered permissions array, agent → agents, command → commands, plugin → plugins, reference → references, agent prompt → system, disable → disabled, permission actions bash → shell / task → subagent, MCP enabled → inverted disabled, timeout split into timeout.catalog/timeout.execution. V1 config is not auto-migrated and the binary is separate (opencode2), so this would be a new target id, not a change to the existing adapters. Track; do not implement while the APIs are marked unstable.

Proposed Follow-up

1. Map notification → tui.toast.show and permissionDenied → gated permission.replied (fixes Kilo simultaneously).
2. Decide on references authoring.
3. Keep a watch on V2 GA for an opencode2 target.

References

• https://opencode.ai/docs/plugins/ — TUI events + permission events (gaps 1–2)
• https://opencode.ai/docs/references/ — references key (gap 3)
• https://opencode.ai/v2/docs/migrate-v1 — V2 rename table (gap 4)
• https://opencode.ai/config.json — published JSON schema used to verify the non-gaps
• https://github.com/anomalyco/opencode/releases — release dating

[dyoshikawa]

Gaps 1 and 2 are resolved in #2617 (merged).

• notification -> tui.toast.show and permissionDenied -> permission.replied, both verified against anomalyco/opencode v1.18.14 (packages/schema/src/tui-event.ts and packages/schema/src/v1/permission.ts) and listed as subscribable plugin events in the plugins docs. permission.replied fires for every reply, so the generated handler is gated on event.properties.reply === "reject".
• One deliberate asymmetry: notification landed for OpenCode only. Kilo's plugin docs enumerate the same events except that they document no TUI section at all, so emitting tui.toast.show into a Kilo plugin risked a hook that never fires - the same failure mode as the old command.executed mapping. KILO_HOOK_EVENTS now filters it out. Happy to add it if Kilo documents TUI events later.

Not addressed, and why:

• Gap 3 (references authoring) is discretionary and needs a design decision on the authoring shape first.
• Gap 4 (the V2 GA gate) has not fired - the latest release is still 1.18.14, so there is nothing to follow yet.