[FEATURE] Mods: configurable toast placement and visible remaining time

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

A mod that changes what the user sent needs to make sure the user notices. Our mod masks a key pasted into a prompt before the model reads it (a prompt.submit hook) and reports the change with $.ui.toast.

In the desktop Code tab, the toast is drawn at the lower right, beside the prompt and mostly outside the transcript column, and it was missed (screenshot below). With no visible timer, there is also no cue for how long it stays.

The types describe "the stack of plugin toasts over the transcript's top right corner", so the desktop placement also differs from what the docs say.

Proposed Solution

Add two presentation options to $.ui.toast:

$.ui.toast(text, { timeoutMs: 8000, placement: "top-right", progress: "bar" })

• placement: a corner of the transcript; a host that cannot honor it falls back to its default.
• progress: "bar" | "ring" | "none", drawn from timeoutMs. A line along the bottom or a ring shows how long the toast remains; hover pauses it, as hover holds the toast today.
• Preserve the existing click-to-dismiss and hover-to-hold behavior.

Alternative Solutions

• $.ui.log: a dim transcript line, which we now add alongside the toast.
• An AbovePrompt band with a hand-animated line, which keeps a region open above the prompt and requires the mod to implement the timer UI.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

1. A user pastes a key into a prompt in the desktop Code tab.
2. A mod masks it in a prompt.submit hook before the model reads it.
3. The mod calls $.ui.toast to explain that the submitted text changed.
4. With transcript-relative placement and a visible timer, the user can notice the change and see how long the notice will remain.

Additional Context

Current API and transport

• ToastOptions has only timeoutMs; the desktop app clamps it to 4–60 seconds.
• The notice relayed by the desktop app to the Code tab carries { kind: "toast", plugin, text, timeout_ms }. Nothing carries a position or a progress style, so the client alone decides both.

Related

• #99306 ($.ui.notify for native notifications)
• #99026 and #99118 (the /diff pane holding mod toasts)
• #91870 (mods umbrella)

Environment

• Claude desktop app on macOS, Code tab (bundled engine 2.1.286); CLI 2.1.289
• Mods API, a plugin loaded through CLAUDE_CODE_PLUGIN_DIRS

Screenshot

The toast appears beside the prompt, outside the transcript column:

<img width="1129" height="214" alt="Image" src="https://github.com/user-attachments/assets/9f8b6377-4911-4da1-9bb4-455c2b1f24ff" />