feat: native second-level picker for custom commands

[rt-outofservice]

Use case

I work across several remote hosts, each running tmux with a handful of sessions. I'd like to attach to
any of them from agterm's command palette.

Today I can add one custom command "Attach <host>" … per host, so the palette (⌃⇧O) already gives me a
nice native top-level list of hosts. What's missing is the second level: after I pick a host, I want a
native list of that host's sessions to choose from — exactly the two-level flow Change Theme uses
(pick the action, then a modal list of themes).

There's currently no way for a custom command to present a native second-level list of items, so the only
option is to pop my own shell menu, which feels foreign next to agterm's built-in pickers.

The ask

A way for a custom command to hand agterm a list of items (produced at open time) and have agterm show its
native picker for them, returning the chosen one. For example:

command "Attach <host>" --submenu "<command that prints one 'id<TAB>label' per line>"

Selecting the parent runs the submenu command, agterm shows a native modal of those items (the Change-Theme
drill-in), and the chosen item's id is passed to the command.

[umputun]

I tend to decline this request. Not a flat no to the idea, I just don't see what justifies a much more complicated keymap structure and the code to support it, when both halves of what you want already work today.

for a static second level, don't nest it, flatten it and let the palette do the narrowing. Name the commands with a common prefix:

command "gate: srv-alpha"  agtermctl session new --command "ssh srv-alpha"
command "gate: srv-beta"   agtermctl session new --command "ssh srv-beta"
command "gate: db-prod"    agtermctl session new --command "ssh db-prod"

the palette's fuzzy search splits your query on whitespace and requires every term to match, order-independent, so ga narrows to the group and ga alp takes you to srv-alpha. That is the two-level navigation you are after, without the modal. A long list costs nothing here because you never scroll it, you type. The matcher was intentionally built for exactly this use case (fuzzyScore in agtermCore, multi-term cases in FuzzyTests.swift).

for a second level that is live data, i.e., the tmux sessions on the host you just picked, you can't enumerate it upfront, so run a picker in an overlay:

command "Attach tmux" ctrl+a>t agtermctl session overlay open 'h=$(/opt/homebrew/bin/fzf < ~/.config/agterm/hosts.txt) && [ -n "$h" ] && s=$(ssh "$h" tmux ls | /opt/homebrew/bin/fzf | cut -d: -f1) && [ -n "$s" ] && agtermctl session new --name "$h/$s" --command "ssh -t $h tmux attach -t $s"' --size-percent 40 --socket {AGT_SOCKET}

the overlay's shell gets AGTERM_SOCKET, so agtermctl inside it reaches this same app with no extra plumbing. It chains to any depth, I tried three levels. One gotcha: give fzf an absolute path or wrap it in $SHELL -lc. The overlay runs with the app's GUI PATH, which has no /opt/homebrew/bin, so a bare fzf exits 127 and the overlay just flashes.

agterm covers a sensible minimum out of the box, and anything past that gets built over the control API and CLI rather than shipped as a built-in. To be concrete about the cost here: a --submenu clause adds a flag to a keymap format that has none today, makes the palette wait on a user shell command with no good answer when a host hangs, and splices remote text into a raw-substituted shell line. That is a permanent surface to carry for something the two recipes above already do.

btw, for open-ended ideas like this one, Discussions (Ideas) is a better place than an issue.

[umputun]

revisiting this now that 0.19.0 is out.

what I pushed back on was the --submenu clause, not the picker itself. The keymap has no flags today, the palette would have had to wait on a user shell command with no good answer when a host hangs, and remote text would be spliced into a raw-substituted line. That reasoning still holds, and there is still no --submenu.

what changed is the other half of that reply, that anything past the built-in minimum gets built over the control API. 0.19.0 adds agtermctl pick: choices on stdin as plain lines or as JSON with ids, subtitles and free-form answers, shown in the same native fuzzy palette the app uses, and the chosen one printed back as JSON. It blocks by default, so it reads like any other command in a pipeline, and there is a non-blocking form with pick result/pick cancel when something else owns the lifecycle.

that covers your use case without a keymap change: a custom command runs a shell line, and each level is another pick in it. The second level's list comes from whatever the first choice selected, which is what the overlay-and-fzf workaround was doing, minus fzf and minus the absolute-path gotcha, since agtermctl sits in the default PATH.

agtermctl pick --help, and the reference under the bundled agent skill, have the arguments and the exit codes. Worth a look before you write the command, since cancel is exit 2 rather than an error.

[rt-outofservice]

Thank you for delivering this, it covers the majority of my pain points. But as always, there is a room for improvement, so I'll throw a few proposals below for your review.

For context, I use a custom palette to manage my local/remote tmux sessions (one master node manages sessions locally and on multiple remote spokes over SSH) and in certain scenarios, for example when you would like to kill all sessions on the host or create a new one, I show some modal windows ("enter session name", "are you sure you want to do that?", "what spoke do you want to create a session on?" etc.). And with this new pick option, I'm trying to ditch my custom ANSI modal window and stick to a native one provided by agterm.

1. Items are always re-sorted; a caller can’t express a natural order.
   On an empty query, explicit items render alphabetized by label with the first row pre-selected — supplied order is never preserved.
2. Free-form answers almost make a text prompt — three gaps short.
   --allow-custom nearly covers my name-input flows, but: an empty items array is rejected (pick.open requires at least one item), an empty custom answer never commits (submitted-empty is meaningful in my “empty name → generate one” flow), and the query can’t be prefilled (rename, with the current name as the starting point). Because of those three, I still ship a hand-rolled ANSI input dialog inside an overlay pane, complete with a temp-file+nonce protocol to smuggle the result out. Completing the free-form path would let me delete all of it.
3. All item text is searchable; there’s no display-only text.
   Subtitles participate in fuzzy matching, which bit me hard in confirms-built-from-picks: my Confirm row’s subtitle said “cannot be undone”, so typing no — a refusal — matched the subtitle, filtered Cancel out, pre-selected Confirm, and Enter would have destroyed the session. I now use label-only confirm rows, and my test suite carries a ported copy of the ranker just to prove refusal words can never isolate the destructive row. A way to mark item text as display-only (shown, but not a search key) would separate presentation from matching for any picker, not just confirms.
4. There’s no room for decision context.
   Besides the items, the only caller text is the query-field placeholder, which shows roughly 80 characters before truncating — so my confirm messages live on a strict character budget with ellipsis logic for embedded session names. Some persistent, non-searchable context on the picker (however you’d want to surface it) would fix that — and as a bonus, a “notice” then composes naturally as context plus one Dismiss row.

Two smaller notes: after a lost or interrupted pick open --no-block reply there’s no way to tell whether a pickPending id in tree is mine, so my cleanup can only ever cancel ids it received in its own replies — some correlation breadcrumb would make crash-recovery deterministic, but this is diagnostic-grade, well below the items above. And to be explicit about scope: I do not think a dedicated confirm dialog is needed — with (1) plus (3) or (4), a safe, default-capable confirm composes perfectly from pick as designed.

[umputun]

taking the ordering and display-only ones, splitting the free-form one, declining the last two.

ordering. Agreed, and it is closer to a bug than a gap. fuzzyRank scores every item 0 on an empty query, so the tie-break re-sorts A→Z. The attention palette already carries a bypass for exactly this (Palette.swift:128-135), with a comment naming the same failure, Return jumping to the alphabetically-first row, but it is gated on the palette owning its own items so a pick never reaches it. Widening that guard is the whole fix, no new argument. The index in the result already comes from your original array, so nothing downstream shifts.

display-only text. Also taking it, but not as a per-item flag. Your confirm case is real: "no" hits "cannot be undone" as a substring at offset 3 and misses "Cancel" entirely, so a refusal deletes the safe row and preselects the destructive one. The fix is to stop ranking subtitles for caller-supplied pickers at all, rather than adding a knob to opt each row out. Built-in palettes keep matching on session cwd, explicit picks match what the label says. If you want extra search text you can append it to the label, which is not something you can do in the other direction.

Both of those are default changes, not flags. pick only just shipped and neither behavior is written down anywhere, so this is the window to flip them.

free-form answers. Prefilled query and the empty item list, yes. Prefill becomes --query, useful beyond rename since it also pre-narrows a long list. Empty items just needs the dispatcher guard relaxed when --allow-custom is set, the palette already handles an empty explicit array.

Committing an empty answer I'll leave out. There is no query text to echo, so Use "…" would need a caller-supplied row label, and that is more API than the other two together. A seed row does the same job today:

echo '[{"id":"__auto","label":"Generate a name"}]' | agtermctl pick --allow-custom --prompt "Session name"

empty query matches everything, so Enter on an untouched field picks the seed row, and typing anything else gives you the custom result.

decision context. Declining. Row labels have no line limit, only subtitles are clamped to one line, so the unbounded text region is the label itself, put the consequence there. You are right that the prompt is a poor place for a question, it is the field placeholder and disappears the moment anyone types, but that argues for keeping the prompt short rather than for a message pane. Drawing one would be the first thing the picker renders beyond rows.

correlation breadcrumb. Also declining, and the obvious shape is worse than no fix. Letting the caller mint the id breaks a uniqueness assumption that PickRegistry.livePick and retainedResult both rely on, they scan by id across windows, so a collision means one caller reads another's answer. An echoed opaque tag avoids that but grows pickPending a sibling field for something you rate diagnostic-grade yourself. Cancelling any pending pick at script start covers the crash case.

[rt-outofservice]

All three accepts land exactly where I needed them, and the ordering one being a bug with an existing bypass to widen is better than what I asked for. No argument on the three you turned down — but one of the alternatives has a safety edge worth flagging before it becomes the documented pattern.

Consequence text in the row label is unsafe once subtitles stop being ranked. After that change the label is the only searched field, so putting the warning there just moves the trap. With rows Cancel and Confirm — this cannot be undone, the query no misses Cancel (it has n, but no later o) and hits Confirm … on the literal no inside can**no**t — one row left, selection index 0, Enter destroys. Same failure I reported, different field.

So I don't think a message pane is needed at all — the non-searchable subtitle is the right home, and it already renders for caller-supplied rows. Concretely, what I'd want blessed as the recommended shape:

[
  {"id": "no",  "label": "Cancel"},
  {"id": "yes", "label": "Confirm",
   "subtitle": "Kill 'session-name'? Destroys its agent — irreversible."}
]

That's ~56 chars in a caption on a 520pt panel, and middle truncation is actually favourable here — it keeps the verb at the front and irreversible at the end. Consider R2 withdrawn on that basis.

On the seed row for empty answers — agreed, and it's better UX than an invisible "empty means default"; the row says what Enter does. One wrinkle in the example: a textual seed label collides with typed input. With {"label": "Generate a name"}, typing name or gen matches the seed, so filteredCount != 0, the custom row never appears, and Enter picks the seed instead of committing what was typed. A symbol-only searched label dodges it entirely, which is another argument for the subtitle carrying the prose:

{"id": "__auto", "label": "🎲", "subtitle": "Generate a random name"}

On the correlation breadcrumb — you're right, and I withdraw it. For the crash case I'll keep the pick ID from pick open --no-block in durable state and cancel only that one on restart; that avoids caller-minted IDs and is also narrower than cancelling whatever is pending, which can take out another caller's picker in the same window (the one-pending rule is per-window, not per-caller).

One thing I confirmed while checking the above, in case it saves you a test: order preservation on an empty query also gives me the destructive-confirm property for free, because every query change resets the selection to row 0 before re-filtering — so clearing a typed query restores both my order and the first-row selection, and [Cancel, Confirm] stays safe at every point. The index in the result does track the original array too.

For what it's worth on the value side: those three changes let me delete my sort-order workaround (I was gaming the alphabetical sort with a low-ASCII label prefix), the ported copy of your ranker I keep in tests to prove refusal words can't select the destructive row, my whole prompt-length budgeting layer, and both remaining hand-rolled text inputs. Thanks for the thorough read.

[umputun]

merged in #339, so all four are in master now.

two things you can delete. The ported ranker copy in your test suite has nothing left to prove: caller rows match their label only, so a subtitle can carry "cannot be undone" and no refusal word can isolate the destructive row. Worth knowing the exact shape before you rewrite those tests, since it is not what either of us assumed at the start: typing no leaves the list EMPTY, not Cancel alone. no misses cancel too, so both rows drop out and Return becomes a no-op. Safe, but the assertion is "nothing is listed", not "the safe row survives".

The ANSI input dialog and its temp-file protocol can go too. Empty items plus --allow-custom is a text prompt, and --query seeds it, so a rename is one line:

new=$(agtermctl pick --allow-custom --query "$current" --prompt "Rename" < /dev/null | jq -r '.query')

< /dev/null matters, agtermctl pick reads stdin unconditionally and will otherwise sit there. The seeded text opens selected, so the first keystroke replaces it rather than appending, which is what you want for rename and worth knowing if you ever want the opposite.

On ordering: an empty query now keeps your array order, so the preselected row is the one you put first. A prefilled --query re-ranks by score, so those two do not combine, and a confirm built from pick should not pass --query if it wants Cancel first.

What I left out, and why. Committing an empty answer needs a caller-supplied label for the row, since there is no query text to echo, and that is more API than the other two together. The context pane I still think is unnecessary: row labels have no line limit, only subtitles are clamped to one line, so the consequence text goes in the destructive row's own label. The correlation tag I did reconsider and still declined, but for a sharper reason than last time. The obvious shape, letting the caller mint the id, breaks a uniqueness assumption that PickRegistry.livePick and retainedResult both scan on, so a collision means one caller reads another's answer. An echoed opaque tag avoids that but grows pickPending a sibling field.

The subtitle behavior and the ordering were both undocumented before this, in either direction. They are written down now in the reference and the bundled skill, along with both error strings.