Repository navigation
Plugin hook parity with Claude Code lifecycle events (7 gaps) #50133
Description
Plugin hook parity with Claude Code's lifecycle events
I'm a plugin author (opencode plugin driving a knowledge-base lifecycle: capture on stop, retrieval on prompt, tooling-finding harvest on subagent stop). Mapping Claude Code's 33 documented hook events (https://code.claude.com/docs/en/hooks) against the opencode plugin API, most of the core loop ports cleanly — thank you. The gaps below are all cases where the information exists inside opencode but no plugin surface exposes it. One consolidated issue rather than seven; happy to split if you prefer.
What already ports (for context)
SessionStart→chat.system.transform, UserPromptSubmit→chat.message, PreToolUse→tool.execute.before (throw=block works), PostToolUse→tool.execute.after, SubagentStart/Stop→task before/after, Stop→session.idle, PreCompact→session.compacting, SessionEnd→session.deleted, StopFailure→session.error, PostCompact→session.compacted.
The gaps
PostToolUseFailurehas no documented signal.tool.execute.afterreceives{title, output, metadata}— but nothing says whether it fires when the tool call fails, or how a failure surfaces in that payload. A documentederror/statusfield (or a dedicated hook) would let plugins react to failures vs successes differently.- No
PostToolBatch. Parallel tool calls resolving as a batch is invisible; plugins see N individual afters with no grouping. - Notifications are send-only. Plugins can push
tui.toast, but there is no event for receiving notification-worthy moments (permission prompts, idle) the way Claude'sNotificationevent provides. - No
CwdChanged/DirectoryAdded. Session cwd tracking is invisible to plugins. Concrete cost: path-scoped guards (e.g. "refuse broadgit addonly inside repo X") cannot be written safely. - No
PreModelSwitch/PostModelSwitch. Model changes mid-session are invisible. - Tool hooks carry no
cwd.tool.execute.before/afterinput is{tool, sessionID, callID}(+argson output for before). Without cwd, any guard that should only fire in one project must match on command text, which is fragile. This is the single highest-value addition for guard authors. - No per-agent hooks. Claude lets subagent/skill frontmatter declare hooks that live only while that agent runs. In opencode every enforcement must live in the global plugin with manual agent-name matching.
Environment
opencode with @opencode-ai/plugin + @opencode-ai/sdk (types as installed 2026-09-20). Willing to test early cuts of any of these.
Activity
opencodejr commentedon Oct 28, 2026
Thanks for the detailed write-up and the Claude Code mapping, it's really useful.
This is about the v1 plugin API (
@opencode-ai/plugin/@opencode-ai/sdk, with hooks liketool.execute.after,chat.system.transformandsession.idle). v1 (0.x/1.x) only gets fixes for critical bugs, so new hook surface there is unlikely to be added.OpenCode v2 (
@opencode/cli) has a completely new plugin API in@opencode/plugin, where hooks are registered per domain (ctx.tool.hook,ctx.session.hook,ctx.permission.hook, ...). Part of your list already looks different there. For example, the v2 toolexecute.afterevent includesstatus: "completed" | "error"(your gap 1) and theagentID of the call. We'd encourage you to try porting your plugin to v2. If any of these gaps are still there in v2, please open a new issue against v2 for them (split up or together, whichever you prefer).If you think something here is a critical problem in v1, please reply and explain.
opencodejr commentedon Oct 29, 2026
Closing this as not planned. These hook requests are for the v1 plugin API (
@opencode-ai/plugin), and v1 only gets critical fixes. Nobody has replied to say any of them is critical in v1.Thanks again for the thorough Claude Code mapping. If you port your plugin to the v2 API (
@opencode/plugin) and find gaps that are still there (cwd on tool hooks, model-switch events, per-agent hooks and so on), please open a new issue for v2 and reference this one.