TUI: client.tui.showToast() from command.execute.before corrupts input box

[dchristal]

Bug: /good's toast notification corrupts the input box, using the officially documented client.tui.showToast() API

opencode version: 1.18.32
OS: Arch Linux (7.1.9-arch1-2)
TERM: xterm-256color, COLORTERM=truecolor

Description

A local plugin implements a custom slash command (/good) via the command.execute.before hook. On invocation, the hook:

1. Sets output.parts = [] (correctly suppresses the LLM turn per the documented Part[] contract for this hook)
2. Runs some local bookkeeping (shell/sqlite calls)
3. Calls client.tui.showToast({ body: { title, message, variant: "success" } }) — the documented SDK method for /tui/show-toast

Every single invocation of this command visually corrupts/"butchers" the TUI's input box immediately after the toast fires. This reproduces 100% of the time, across fresh sessions (confirmed by fully killing and restarting the opencode process between attempts), ruling out stale plugin state.

What we ruled out

• Not caused by hot-reload/stale-plugin-state: reproduced on fully fresh process restarts.
• Not caused by weird bytes/control characters in the toast message: verified plain ASCII via od -c, no embedded escape sequences.
• Not caused by using output.parts to fake a synthetic assistant message: rewrote the plugin to use output.parts = [] (no synthetic message at all) plus the sanctioned client.tui.showToast() API instead — corruption still occurs identically.
• Not caused by the plugin's shell subprocess calls per se — the toast fires only after those complete, and the visual corruption appears specifically once the toast renders.

This points to the toast rendering/dismissal path in the TUI conflicting with the input box's own render cycle, specifically when the toast is triggered from within a command.execute.before hook (as opposed to a normal event hook context, e.g. session.idle, which is the only toast-trigger example shown in the docs).

Repro plugin

export const GoodPlugin = async ({ client }) => {
  return {
    "command.execute.before": async (input, output) => {
      if (input.command !== "good") return;
      output.parts = [];
      await client.tui.showToast({
        body: { title: "test", message: "hello", variant: "success" },
      }).catch(() => {});
    },
  };
};

Paired with a minimal command file:

---
description: test
---
This command is handled entirely by the plugin. Do not execute anything.

Expected

Toast renders without disturbing the input box's layout/redraw state.

Actual

Input box becomes visually corrupted/garbled immediately after the toast is shown, every time, on this terminal setup.

[dchristal]

Update: this is NOT specific to the good.js plugin — reproduces with any local slash command

Further testing today isolated the actual bug. It has nothing to do with plugin code, toast APIs, or command template content — all of which I initially (incorrectly) suspected and ruled out one by one.

Actual reproduction steps:

1. Type a local slash command (e.g. /good, /efficiency — both defined in ~/.config/opencode/commands/*.md, no special content).
2. Press Enter. The cursor advances one space; the command does not submit/execute.
3. Press Enter again.
4. The command's raw markdown template body is dumped verbatim into the chat as if the user had typed/pasted it, rather than being consumed by the command-execution pipeline. It gets sent to the agent as literal user input.

This reproduces identically for two independent commands with completely different templates (one intercepted entirely by a plugin hook with output.parts = [], one a normal multi-paragraph instructional template with no plugin involvement at all). Since both — despite having nothing in common code-wise — exhibit the exact same "double-Enter, cursor shifts once, template body leaks into chat as literal text" symptom, the common factor is the TUI's slash-command dispatch/submission path itself, not anything in the command definitions.

Environment: opencode 1.18.32, Arch Linux, TERM=xterm-256color, COLORTERM=truecolor.

This supersedes my earlier toast-rendering theory in the issue body above — please disregard the client.tui.showToast() angle; that was a red herring from chasing the wrong plugin.

[dchristal]

Further isolation: scoped to file-defined local commands, not built-ins

Tested a built-in command (/debug) — it submits and executes normally on the first Enter, no cursor-shift, no template leak.

This narrows the bug specifically to commands loaded from **/*.md files under .opencode/command(s)/ or ~/.config/opencode/command(s)/ (per the docs' command-loading mechanism), as opposed to built-in/internal commands. Both /good and /efficiency (file-defined, confirmed broken above) vs. /debug (built-in, works correctly) is a clean A/B.

This points at something in the file-based command loader/dispatch path specifically — possibly how the TUI submits a command whose template comes from a loaded .md file vs. one defined internally, rather than the TUI's slash-command input handling in general.

[argszero]

I looked into this on the current dev head and the mechanism is now pinned. Your A/B isolation is what makes it visible.

Where the two paths diverge. The autocomplete builds its slash list from two sources (packages/tui/src/component/prompt/autocomplete.tsx):

• built-in commands come from useCommandSlashes() (packages/tui/src/keymap.tsx:286), whose onSelect is keymap.dispatchCommand(entry.command.name) — it executes the command;
• file-defined commands come from sync.data.command (autocomplete.tsx:450-463), whose onSelect only rewrites the input text to "/" + name + " " and moves the cursor. It never executes and never submits.

select() (autocomplete.tsx:553-558) is what runs on Enter (bound at :611-618 as prompt.autocomplete.select): it calls hide() and then onSelect?.(). For a built-in that dispatches the command. For a file command it just re-inserts /name — exactly the "cursor advances one space, nothing is submitted" step you observed. The second Enter then submits the completed line through the normal prompt path.

One correction to the body: the template body appearing in the chat as literal user input is expected — for file commands the template IS the prompt that gets sent, so that symptom is the normal path, not a second defect. The real defect is narrower than the original report: the first Enter is consumed by the completion even when the typed text already names the command exactly, so file commands need two Enters while built-ins need one.

Fix direction (small, one file): when the selected file command already matches the typed text exactly, Enter should submit instead of re-completing. Autocomplete currently has no submit callback among its props (autocomplete.tsx:75-86), so this is either a submit prop threaded in from the prompt, or the autocomplete declining to consume Enter on an exact match.

I would like to work on this. Plan: base on dev, keep the change to the file-command branch of the completion path, and cover both cases (exact match submits, partial match still completes) with a test in the prompt autocomplete suite.

[argszero]

Narrowing the mechanism further, now that I have read the keymap defaults — this makes the defect sharper than my first analysis and changes which fix shape is smallest.

Enter is bound to two commands. On dev (packages/tui/src/config/keybind.ts):

• :217 "prompt.autocomplete.select": keybind("return", …)
• :163 input_submit: keybind("return", "Submit input")

The autocomplete registers its bindings with enabled: () => Boolean(store.visible) (autocomplete.tsx:583) on the input, so while the slash list is open, Enter means "select", and submit never sees the key. That is why file commands need two Enters and why the first one cannot submit: it is not a timing or render problem, the key is routed elsewhere.

And the "cursor advances one space" is literally a text wipe plus rewrite. select() (:553-558) runs hide() before onSelect(), and hide() (:650-660) clears the input when the text starts with / and has no trailing space:

props.input().deleteRange(0, 0, cursor.row, cursor.col)

So for /good: hide() deletes the whole typed command, then the file-command branch of onSelect (:456-462) inserts "/good " back. The command text reappears with a trailing space and the cursor at the end of it — exactly the one-position shift reported. Nothing was submitted, and the trailing space is also why the autocomplete does not reopen on the next keystroke (the onInput guard at :682 sees whitespace before the cursor).

Why built-ins differ: same Enter, same hide(), but the built-in branch resolves to keymap.dispatchCommand(entry.command.name) (keymap.tsx:286) — an execution, not a rewrite — so it completes its action on the first press.

Smallest fix shapes, in order of preference:

1. Stop the autocomplete from staying open on an already-complete command name. onInput (:676-700) currently only hides on the two-token rule at :684; a bare /good stays open. Hiding when the input is a single token that matches a command hands the next Enter straight to input_submit — no prop threading, one predicate.
2. Thread a submit callback from the prompt into Autocomplete and have select() submit on an exact match (Autocomplete has no such prop today, :75-86).
3. Handle it inside the prompt.autocomplete.select run handler — least invasive to the completion path, but it puts submit semantics in a keymap handler rather than the component that owns the state.

I still want to work on this and will take shape 1 unless you prefer otherwise. Note there is currently no autocomplete unit test — packages/tui/test/ has prompt/ and cli/tui/prompt-submit-race.test.ts but nothing over the completion path — so the PR would add the first one, covering "exact match submits on one Enter" and "partial match still completes".

[argszero]

Opened #51714 with a fix, based on dev.

Your two isolation steps were what pinned this. Summary of the mechanism, with the paths:

• Enter is bound twice on the input: prompt.autocomplete.select and input_submit both take return (packages/tui/src/config/keybind.ts). The autocomplete registers its bindings with enabled: () => Boolean(store.visible), so while the slash list is open Enter always means select, and submit never sees the key.
• What select then does differs by command type, which is why your /debug versus /good A/B is clean. A built-in comes from useCommandSlashes() and its onSelect runs keymap.dispatchCommand(name), so it acts immediately. A file-defined command comes from sync.data.command and its onSelect only rewrites the input to "/" + name + " " and moves the cursor, which is the one-space shift you saw and why a second Enter is needed.

The fix collapses the list once the typed text already names a whole command, so the following Enter reaches the input own submit path and dispatches the command. Further typing reopens the list, so prefix browsing still works.

Two honest caveats:

• With the arrow keys, selecting an entry from the list still inserts /name and waits for the following Enter, since the selection itself is what inserts the text. If you would prefer a selected file-defined command to submit straight away like a built-in does, say so and I will add it.
• Every file-defined command declares a template, and executing it turns that template into the prompt, so the template body reaching the conversation after the command runs is the command executing rather than the TUI pasting text into the input box. The PR only changes how many Enter presses it takes to get there.

Test results in the PR: bun test in packages/tui is 199 pass / 1 skip / 0 fail, the new predicate tests are 5 pass / 0 fail, and typecheck, oxlint and prettier are clean.

I could not reproduce on macOS with your exact terminal setup, so I would value a confirmation on Arch once you have tried the branch.