opencode-subagent-ask-user-plugin

A plugin that pauses subagent execution to prompt a human user via the OpenCode UI.

UIBridge Contract

This plugin ships no concrete UI implementation. The OpenCode plugin host must inject a UIBridge implementation via context.uiBridge when invoking any tool handler.

Interface the host must satisfy

interface UIBridge {
  dispatch(payload: PromptPayload, signal: AbortSignal): Promise<UserResponse | null>;
}

dispatch behaviour

| Result | Condition | |---|---| | UserResponse | User submits input | | null | User explicitly cancels | | Rejects / aborts | UI client disconnects or host shuts down |

The AbortSignal passed to dispatch is pre-wired to a 5-minute timeout and an external cancellation path. Implementations must propagate it to any underlying I/O.

Example host environments

• TUI — an Ink/React renderer that mounts a prompt component and resolves when the user submits or presses Escape.
• Web UI — a WebSocket relay that forwards the payload to a browser client and waits for the response frame, honouring abort via socket close.

Prompt Types

| Type | Shape | Purpose | |---|---|---| | text | { type: "text", question: string } | Free-form text input | | choice | { type: "choice", question: string, options: string[] } | Single selection from a fixed list | | form | { type: "form", questions: Array<TextPrompt | ChoicePrompt> } | Multi-field structured input |

Plugin Registration

import plugin from "opencode-subagent-ask-user-plugin";

// Host wires its concrete UIBridge into every tool invocation via PluginContext.
// Example (pseudo-code):
const host = new PluginHost({
  plugins: [plugin],
  contextFactory: (req) => ({
    uiBridge: myConcreteUIBridge, // must satisfy UIBridge interface above
  }),
});

Build

npm run build   # compiles TypeScript → dist/

Output lands in dist/ (dist/index.js + dist/index.d.ts).