[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.

[m13v]

hit this exact three-way split wiring a local PTT dictation loop for a desktop agent last quarter. the shutdown hook gap is the sneakiest. std::process::exit(0) to kill a dangling hotkey thread works until the transcription worker has a half-flushed audio buffer and you corrupt the next session's first utterance. the fix that held up was giving the hotkey listener a crossbeam channel and a select! loop so a parent shutdown token cancels it cleanly, but that only works if the host actually fires a shutdown event.

on the inject vs send question, I'd push back on the framing. users want both and the right split isn't policy, it's length. anything under ~4 words is a command and should send; longer utterances should stage in the input so you can fix the inevitable whisper mis-hears of proper nouns. we ended up with a config flag plus a hard cap because the "always stage" mode felt clunky for short confirmations.

[mathew-cf]

@m13v this feels incredibly validating lol. thank you for commenting.

I think inject vs send can be configured to user preference but I've found that Anthropic models are generally pretty good at sussing out dictation errors if you specify that you're using dictation in AGENTS.md (or equivalent).

As long as the core functionality is available, it can be configured in the respective plugins.