Plugins: v2 definition API exposes no tool/event registration - v1 hook-map plugins fail every load, docs still show the v1 shape #56630

Activity

1. opencode-agent commented on Oct 18, 2026

   

   opencode-agentBot

   on Oct 18, 2026 – with OpenCode Agent

   Contributor

   More actions

   Thanks for the detailed write-up! I think this is a duplicate of #48138, which asks for v1 hook-map plugins to keep loading in v2 (or to fail with a clear migration hint instead of a bare schema error).

   One correction that may unblock you now: in 2.0.29 the context passed to setup(ctx) does expose tool and event registration. The Context type includes tool, event, shell, session, permission and more, not only the domains you listed. The v2 "Migrate plugins from V1" guide maps each v1 hook to its v2 replacement, for example:

   V1	V2
   tool: { ... } map	ctx.tool.transform((editor) => editor.add(...))
   tool.execute.before / after	ctx.tool.hook("execute.before" / "execute.after", ...)
   event (file / session events)	ctx.event.subscribe()
   shell.env	ctx.shell.hook("create.before", ...)
   permission.ask	ctx.permission.hook("evaluate", ...)

   import { Plugin } from "@opencode/plugin"
   
   export default Plugin.define({
     id: "my.plugin",
     async setup(ctx) {
       await ctx.tool.hook("execute.before", (event) => { /* ... */ })
       await ctx.shell.hook("create.before", (event) => { event.env.FOO = "bar" })
     },
   })

   The opencode.ai/docs/plugins page you found documents the v1 API, which is why it shows the hook-map shape.

   Possible duplicates and closely related issues, ordered from most to least likely:

   • [FEATURE]: backward compatibility for v1 plugins in v2 #48138: backward compatibility / migration path for v1 plugins in v2 (your requests 1 and 2)
   • beta: V1 plugins unloadable with no migration path, custom commands unreachable headless, no V2 plugin/API docs for agents #48365: v1 plugins unloadable under the v2 schema with no migration path, plus missing v2 plugin docs
   • plugin: function default export rejected by v2 loader schema (SDK root Plugin type mismatch) #50590: the same Expected object at ["default"] schema error for a function default export
   • plugin: configured local plugin file paths silently dropped since #46105 #46551: configured local plugin file paths (including file://) dropped with configured plugin path must be a directory (your request 3)
   • plugins for V2: local plugin paths fail to load (file entries rejected, @opencode/plugin unresolvable) #49608: local plugin file entries rejected in v2, and docs for the accepted entry forms

   The bot will close this issue as a duplicate in 1 day unless you reply explaining how your problem is different, for example if a ctx.tool / ctx.event based plugin still doesn't work for you on 2.0.29.
2. opencode-agent

   added

   pending close

   triaging

   on Oct 18, 2026
3. opencode-agent

   closed this as duplicateon Oct 19, 2026
4. opencode-agent commented on Oct 19, 2026

   

   opencode-agentBot

   on Oct 19, 2026 – with OpenCode Agent

   Contributor

   More actions

   Closing this as a duplicate of #48138, since there's been no reply in the last day saying how this differs.

   The remaining asks are tracked here:

   • [FEATURE]: backward compatibility for v1 plugins in v2 #48138: compatibility or a migration path for v1 hook-map plugins in v2
   • beta: V1 plugins unloadable with no migration path, custom commands unreachable headless, no V2 plugin/API docs for agents #48365 and plugin: function default export rejected by v2 loader schema (SDK root Plugin type mismatch) #50590: v1 plugins rejected by the v2 loader with the Expected object at ["default"] schema error, and the missing docs
   • plugin: configured local plugin file paths silently dropped since #46105 #46551 and plugins for V2: local plugin paths fail to load (file entries rejected, @opencode/plugin unresolvable) #49608: file:// and file-path plugin entries rejected with configured plugin path must be a directory

   To port a plugin now: the v2 setup(ctx) context already has tool and event registration. Use ctx.tool.transform(...) and ctx.tool.hook("execute.before" | "execute.after", ...) for tools, ctx.event.subscribe() for events and ctx.shell.hook("create.before", ...) in place of shell.env. The v2 "Migrate plugins from V1" guide maps every v1 hook. If a ctx.tool / ctx.event based plugin still doesn't work for you on 2.x, please open a new issue with the plugin code and the log output.