RPC extension UI protocol

Extension UI Protocol

Extensions can request user interaction via ctx.ui.select(), ctx.ui.confirm(), etc. In RPC mode, these are translated into a request/response sub-protocol on top of the base command/event flow. There are two categories of extension UI methods:

Dialog methods (select, confirm, input, editor, and questionnaire for a client that opted in): emit an extension_ui_request on stdout and block until the client sends back an extension_ui_response on stdin with the matching id.
Fire-and-forget methods (notify, setStatus, setWidget, setTitle, set_editor_text): emit an extension_ui_request on stdout but do not expect a response. The client can display the information or ignore it.

If a dialog method includes a timeout field, the agent-side will auto-resolve with a default value when the timeout expires. The client does not need to track timeouts. Some ExtensionUIContext methods are not supported or degraded in RPC mode because they require direct TUI access:

custom() returns undefined
setWorkingMessage(), setWorkingIndicator(), setFooter(), setHeader(), setEditorComponent() are no-ops
getEditorText() returns ""
setToolsExpanded() and getToolsExpanded() maintain context-local expansion state; getChatRenderSettings().toolOutputExpanded reports the same value. A same-value setToolsExpanded() call is a no-op and does not request a custom-UI render. This state is not sent through the client extension-UI protocol.
pasteToEditor() delegates to setEditorText() (no paste/collapse handling)
getAllThemes() returns []
getTheme() returns undefined
setTheme() returns { success: false, error: "..." }

Note: ctx.mode is "rpc" and ctx.hasUI is true in RPC mode because the dialog and fire-and-forget methods are functional via the extension UI sub-protocol. Use ctx.mode === "tui" to guard TUI-specific features like custom() that require a real terminal.

Extension UI Requests (stdout)

All requests have type: "extension_ui_request", a unique id, and a method field.

select

Prompt the user to choose from a list. Dialog methods with a timeout field include the timeout in milliseconds; the agent auto-resolves with undefined if the client doesn’t respond in time.

{
  "type": "extension_ui_request",
  "id": "uuid-1",
  "method": "select",
  "title": "Allow dangerous command?",
  "options": ["Allow", "Block"],
  "timeout": 10000
}

Expected response: extension_ui_response with value (the selected option string) or cancelled: true.

confirm

Prompt the user for yes/no confirmation.

{
  "type": "extension_ui_request",
  "id": "uuid-2",
  "method": "confirm",
  "title": "Clear session?",
  "message": "All messages will be lost.",
  "timeout": 5000
}

Expected response: extension_ui_response with confirmed: true/false or cancelled: true.

input

Prompt the user for free-form text.

{
  "type": "extension_ui_request",
  "id": "uuid-3",
  "method": "input",
  "title": "Enter a value",
  "placeholder": "type something..."
}

Expected response: extension_ui_response with value (the entered text) or cancelled: true.

editor

Open a multi-line text editor with optional prefilled content.

{
  "type": "extension_ui_request",
  "id": "uuid-4",
  "method": "editor",
  "title": "Edit some text",
  "prefill": "Line 1\nLine 2\nLine 3"
}

Expected response: extension_ui_response with value (the edited text) or cancelled: true.

questionnaire

A whole ask_user_question call: one to four questions, each with a short header, its options (label, description, optional markdown preview) and multiSelect. Sent only to a client that turned the questionnaire capability on with set_extension_ui_capabilities; otherwise ask_user_question fails in RPC mode, because it needs a terminal.

{
  "type": "extension_ui_request",
  "id": "uuid-5",
  "method": "questionnaire",
  "questions": [
    {
      "question": "Which storage should runs use?",
      "header": "Storage",
      "options": [
        { "label": "SQLite", "description": "A local file" },
        { "label": "libSQL", "description": "A shared database" }
      ]
    }
  ]
}

Expected response: extension_ui_response with answers, one per answered question, or cancelled: true. Each answer names its questionIndex and repeats its question, and its kind says what the user chose:

option: one of the question’s options; answer is its label.
multi: for a multiSelect question; answer is null and selected lists the chosen labels.
custom: free text typed instead of an option (single-select questions without previews); answer is the text.
chat: the user wants to talk it over instead; answer is their text or null.

{
  "type": "extension_ui_response",
  "id": "uuid-5",
  "answers": [{ "questionIndex": 0, "question": "Which storage should runs use?", "kind": "option", "answer": "libSQL" }]
}

Answers that don’t match the questions, such as an unknown label, are rejected and the tool call fails.

notify

Display a notification. Fire-and-forget, no response expected.

{
  "type": "extension_ui_request",
  "id": "uuid-5",
  "method": "notify",
  "message": "Command blocked by user",
  "notifyType": "warning"
}

The notifyType field is "info", "warning", or "error". Defaults to "info" if omitted.

setStatus

Set or clear a status entry in the footer/status bar. Fire-and-forget.

{
  "type": "extension_ui_request",
  "id": "uuid-6",
  "method": "setStatus",
  "statusKey": "my-ext",
  "statusText": "Turn 3 running..."
}

Send statusText: undefined (or omit it) to clear the status entry for that key.

setWidget

Set or clear a widget (block of text lines) displayed above or below the editor. Fire-and-forget.

{
  "type": "extension_ui_request",
  "id": "uuid-7",
  "method": "setWidget",
  "widgetKey": "my-ext",
  "widgetLines": ["--- My Widget ---", "Line 1", "Line 2"],
  "widgetPlacement": "aboveEditor"
}

Send widgetLines: undefined (or omit it) to clear the widget. The widgetPlacement field is "aboveEditor" (default) or "belowEditor". Only string arrays are supported in RPC mode; component factories are ignored.

setTitle

Set the terminal window/tab title. Fire-and-forget.

{
  "type": "extension_ui_request",
  "id": "uuid-8",
  "method": "setTitle",
  "title": "atomic - my project"
}

set_editor_text

Set the text in the input editor. Fire-and-forget.

{
  "type": "extension_ui_request",
  "id": "uuid-9",
  "method": "set_editor_text",
  "text": "prefilled text for the user"
}

Extension UI Responses (stdin)

Responses are sent for dialog methods only (select, confirm, input, editor, questionnaire). The id must match the request. A questionnaire is answered with answers (see questionnaire).

Value response (select, input, editor)

{"type": "extension_ui_response", "id": "uuid-1", "value": "Allow"}

Confirmation response (confirm)

{"type": "extension_ui_response", "id": "uuid-2", "confirmed": true}

Cancellation response (any dialog)

Dismiss any dialog method. The extension receives undefined (for select/input/editor) or false (for confirm).

{"type": "extension_ui_response", "id": "uuid-3", "cancelled": true}

Build with Atomic

Extend a session

Orchestrate work

Distribute

Models and providers

Programmatic use

RPC extension UI protocol

RPC extension UI protocol

Extension UI Protocol

Extension UI Requests (stdout)

select

confirm

input

editor

questionnaire

notify

setStatus

setWidget

setTitle

set_editor_text

Extension UI Responses (stdin)

Value response (select, input, editor)

Confirmation response (confirm)

Cancellation response (any dialog)

​RPC extension UI protocol

​Extension UI Protocol

​Extension UI Requests (stdout)

​select

​confirm

​input

​editor

​questionnaire

​notify

​setStatus

​setWidget

​setTitle

​set_editor_text

​Extension UI Responses (stdin)

​Value response (select, input, editor)

​Confirmation response (confirm)

​Cancellation response (any dialog)

RPC extension UI protocol

Extension UI Protocol

Extension UI Requests (stdout)

select

confirm

input

editor

questionnaire

notify

setStatus

setWidget

setTitle

set_editor_text

Extension UI Responses (stdin)

Value response (select, input, editor)

Confirmation response (confirm)

Cancellation response (any dialog)