[FEATURE]: Plugin extensibility gaps blocking dictation/voice input plugins

[mathew-cf]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Dictation and voice input are highly requested (#4695, #9264, #11345), but implementing them as a plugin is currently difficult to deliver a reasonable user experience due to three missing extension points. This means every voice implementation either forks core (#11345) or lives entirely outside OpenCode (#4695 comment thread workarounds with Raycast, Handy, etc.).

The same gaps also block other categories of plugins — anything that needs to react to UI state, inject input, or clean up resources.

Gap 1: No active session awareness
Plugins receive sessionID in several hooks, but there is no way to know:

• Which session is currently focused in the UI
• When the user switches sessions (tui.session.select exists internally but isn't surfaced to plugins)
  Minimal addition: Surface session.focus / session.blur events through the plugin event hook, or provide a query like getActiveSession() on PluginInput.

Gap 2: No plugin-triggered input injection or custom keybinds
Plugins can intercept outbound flows but cannot inject input into the UI:

• No hook to register custom keybindings (TUI Config.Keybinds schema is .strict())
• No API to programmatically insert text into the user's input box (while plugins can send messages or intercept outgoing chat, they cannot stage text for the user to review/edit before sending)
• No way to register commands in the web UI command palette
  Minimal addition: A command hook for registering plugin commands (with optional keybind), and an input.inject method on PluginInput to programmatically insert text.

Gap 3: No shutdown/dispose lifecycle hook (previously requested in #10524 and #10003)
Plugins cannot clean up when OpenCode exits. For dictation, this leaves audio recording processes running.
Minimal addition: A shutdown hook in the Hooks interface, called before Instance.dispose().

Summary of proposed additions

export interface Hooks {
  // Existing hooks...

  // New: cleanup before exit (refs #10524, #10003)
  shutdown?(): Promise<void>

  // New: register commands (with optional keybind)
  command?(): CommandDefinition[]
}

Plus surfacing session.focus / session.blur through the existing event hook, and an input.inject() helper on PluginInput.

These additions would allow dictation (and other resource-heavy or UI-interacting features) to exist purely as plugins rather than requiring forks of core.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Feature Request: Plugin shutdown hook for graceful cleanup #10524: Plugin shutdown hook for graceful cleanup (covers Gap 3 directly)
• [FEATURE]: Add shutdown/exit event allowing a plugin to right before closing. #10003: Plugin shutdown/exit event (also covers Gap 3)
• [FEATURE]: Plugin Hook for Instant TUI Commands #5305: Plugin Hook for Instant TUI Commands (covers the command hook concept in Gap 2)

This issue bundles three separate extension points together; Gap 3 in particular is already tracked in two open issues you referenced. Consider whether this should be a meta-tracking issue that links those, or whether the novel parts (Gap 1: session focus events, Gap 2: input injection) warrant a standalone request scoped to those gaps only.

[mathew-cf]

I've been building opencode-voice, a companion tool that adds local push-to-talk dictation (whisper.cpp) to OpenCode. It hits all three gaps directly:

• Session awareness: The use-session-api branch had to build a heuristic that tracks session.updated/session.created SSE events and guesses which session is active. It cannot know which session the user is actually viewing.
• Input injection: The main branch uses /tui/append-prompt which silently does nothing in web mode. The use-session-api branch switched to the session API but lost the ability to stage text for user review before sending.
• Shutdown: The tool has to call std::process::exit(0) because the global hotkey listener thread cannot be gracefully cancelled, and there's no OpenCode shutdown event to trigger cleanup.

The entire project exists as a separate process rather than a plugin because the plugin API doesn't have the primitives needed.

[mathew-cf]

@thdxr any feedback here? if you gave your blessing, I'd love to put up some PRs to fill the gaps and enable dictation via plugin.