Document (or shim) the v1 → v2 plugin event renames: legacy tool.execute.* / file.changed subscriptions now fail silently #40808

Description

Summary

opencode's plugin event model was renamed between v1 and v2 (@opencode-ai/plugin 1.x with SDK v2 types). Plugins that subscribe to the legacy event names — tool.execute.before, tool.execute.after, file.changed — are silently dead: they register successfully, log "Plugin returning hooks: ...", but never receive any event and produce no error or log entry. This makes broken plugin configuration undiagnosable.

Verified on opencode v1.18.14 (Windows 11) with:

• opencode-command-hooks@0.5.3 (subscribes to tool.execute.before/after)
• opencode-yaml-hooks@2026.3.29 (subscribes to file.changed)

Marker-file probes confirmed zero event delivery; opencode.log shows the plugin initializing and then zero activity.

The actual event names in v2

From @opencode-ai/sdk/dist/v2/gen/types.gen.d.ts (v1.17.13), the 167 event types include:

Why this matters

1. Silent failure is the core problem. A plugin subscribing to a renamed event is not an error — the runtime simply never calls the handler. Third-party plugin authors (command-hooks, yaml-hooks, and many others) can't discover the breakage without deep log forensics. In our case, the entire automation layer (verification after every file edit) was configured and registered, but never ran.
2. Ecosystem fragmentation risk. Every third-party plugin built against the v1 event names breaks when users upgrade; without a migration guide, the fix is a slow game of whack-a-mole.

Requested changes (any of)

1. Documentation: publish an explicit v1→v2 event-name migration table (as above) in the plugin authoring docs / Event API docs, so plugin authors can update.
2. Deprecation shim (preferred): for a transition window, forward the legacy event names to their v2 equivalents when a plugin subscribes via event.subscribe("tool.execute.after"), and log a deprecation warning once (e.g. plugin event "tool.execute.after" is deprecated, use "session.next.tool.success"). This un-breaks the installed base immediately.
3. At minimum, emit a runtime warning when a plugin registers a hook/event subscription that has no matching event in the current event model.

Plugins

opencode-command-hooks@0.5.3, opencode-yaml-hooks@2026.3.29 (both third-party, not maintained by opencode)

OpenCode version

v1.18.14

Steps to reproduce

1. Install any plugin subscribing to legacy v1 event names (e.g. opencode-command-hooks@0.5.3 → tool.execute.before/after, or opencode-yaml-hooks@2026.3.29 → file.changed)
2. Configure a hook that creates a marker file, e.g. .opencode/command-hooks.jsonc: { "tool": [{ "id": "probe", "when": { "phase": "after", "tool": "write" }, "run": ["node C:/abs/probe.js"] }] }
3. Use the agent so a write tool runs, then check: plugin logs "Plugin returning hooks: ..." at startup, but the marker file is never created and no event delivery or error appears in opencode.log

Screenshot and/or share link

No response

Operating System

Windows 11

Terminal

Windows Terminal