commandmate 0.30.2 → 0.31.0

package/dist/server/src/types/agent-transcript.js

@@ -39,7 +39,7 @@
  * @module types/agent-transcript
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_MARKDOWN_REQUEST_ID_PREFIXES = exports.ANTIGRAVITY_PROMPT_REQUEST_ID_PREFIX = exports.ANTIGRAVITY_MARKDOWN_REQUEST_ID_PREFIX = exports.CODEX_PROMPT_REQUEST_ID_PREFIX = exports.CODEX_MARKDOWN_REQUEST_ID_PREFIX = exports.CLAUDE_PROMPT_REQUEST_ID_PREFIX = exports.CLAUDE_MARKDOWN_REQUEST_ID_PREFIX = exports.AGENT_MARKDOWN_REQUEST_ID_PREFIX = void 0;
+exports.AGENT_MARKDOWN_REQUEST_ID_PREFIXES = exports.COMMAND_CODE_PROMPT_REQUEST_ID_PREFIX = exports.COMMAND_CODE_MARKDOWN_REQUEST_ID_PREFIX = exports.ANTIGRAVITY_PROMPT_REQUEST_ID_PREFIX = exports.ANTIGRAVITY_MARKDOWN_REQUEST_ID_PREFIX = exports.CODEX_PROMPT_REQUEST_ID_PREFIX = exports.CODEX_MARKDOWN_REQUEST_ID_PREFIX = exports.CLAUDE_PROMPT_REQUEST_ID_PREFIX = exports.CLAUDE_MARKDOWN_REQUEST_ID_PREFIX = exports.AGENT_MARKDOWN_REQUEST_ID_PREFIX = void 0;
 exports.isAgentAuthoredMarkdown = isAgentAuthoredMarkdown;
 exports.opencodeTurnRequestId = opencodeTurnRequestId;
 exports.claudeTurnRequestId = claudeTurnRequestId;
@@ -48,6 +48,8 @@ exports.codexTurnRequestId = codexTurnRequestId;
 exports.codexPromptRequestId = codexPromptRequestId;
 exports.antigravityTurnRequestId = antigravityTurnRequestId;
 exports.antigravityPromptRequestId = antigravityPromptRequestId;
+exports.commandCodeTurnRequestId = commandCodeTurnRequestId;
+exports.commandCodePromptRequestId = commandCodePromptRequestId;
 /**
  * Prefix on `chat_messages.request_id` for a row whose `content` is opencode's
  * own Markdown rather than a scrape of its terminal.
@@ -152,6 +154,40 @@ exports.ANTIGRAVITY_MARKDOWN_REQUEST_ID_PREFIX = 'antigravity-turn:';
  * a codex turn can.
  */
 exports.ANTIGRAVITY_PROMPT_REQUEST_ID_PREFIX = 'antigravity-prompt:';
+/**
+ * The same, for a turn read out of Command Code's transcript JSONL (Issue #2252).
+ *
+ * A fifth namespace for the fifth reader, for the reason
+ * {@link CLAUDE_MARKDOWN_REQUEST_ID_PREFIX} gives: the value is an idempotency
+ * key as well as a marker, and Command Code names its records with an **8-hex
+ * short id of its own minting** (`cb06ab09`), which is a far smaller space than
+ * claude's uuids. Sharing a prefix with claude would therefore not merely be
+ * untidy — a `command-code` id is exactly the shape a claude uuid's first
+ * segment has, and a collision between two tools' ids reads as "already saved",
+ * which is the one failure a key must not have.
+ *
+ * `command-code-` and not `cc-`: the string is what an operator reads in the row
+ * when they ask why History shows Markdown, and the tool id is what they will
+ * search the codebase for.
+ */
+exports.COMMAND_CODE_MARKDOWN_REQUEST_ID_PREFIX = 'command-code-turn:';
+/**
+ * Prefix on a **user** row whose text was read out of Command Code's transcript
+ * JSONL (Issue #2252).
+ *
+ * Deliberately absent from {@link AGENT_MARKDOWN_REQUEST_ID_PREFIXES}, for the
+ * whole of the reason {@link CLAUDE_PROMPT_REQUEST_ID_PREFIX} states: the
+ * operator's own text is drawn verbatim and must not change shape because it
+ * happened to contain a `#` or a `|`.
+ *
+ * Keyed on the same record id as the turn's assistant row, which is claude's
+ * arrangement rather than codex's. It is the right one here because Command
+ * Code opens a turn with exactly one fresh `role: "user"` record — its own
+ * `isFreshUserTurn` is `role === 'user' && no tool_result block`, and a prompt
+ * typed while a turn is running is appended as a `meta.source: "steering"`
+ * record that opens a turn of its own rather than joining the one in flight.
+ */
+exports.COMMAND_CODE_PROMPT_REQUEST_ID_PREFIX = 'command-code-prompt:';
 /**
  * Every prefix that means "this row holds source, not a rendering".
  *
@@ -166,6 +202,7 @@ exports.AGENT_MARKDOWN_REQUEST_ID_PREFIXES = [
     exports.CLAUDE_MARKDOWN_REQUEST_ID_PREFIX,
     exports.CODEX_MARKDOWN_REQUEST_ID_PREFIX,
     exports.ANTIGRAVITY_MARKDOWN_REQUEST_ID_PREFIX,
+    exports.COMMAND_CODE_MARKDOWN_REQUEST_ID_PREFIX,
 ];
 /**
  * Whether this row's `content` may be rendered as Markdown.
@@ -314,3 +351,38 @@ function antigravityTurnRequestId(conversationId, stepIndex) {
 function antigravityPromptRequestId(conversationId, stepIndex) {
     return `${exports.ANTIGRAVITY_PROMPT_REQUEST_ID_PREFIX}${antigravityTurnKey(conversationId, stepIndex)}`;
 }
+/**
+ * The row id for one Command Code turn (Issue #2252).
+ *
+ * The turn is named by the **prompt record it answers** — the `id` of the fresh
+ * `role: "user"` record the operator's text arrived on. That is claude's
+ * arrangement (#2121) and antigravity's (#2198) rather than codex's, because
+ * Command Code writes nothing that closes a turn and nothing that links a reply
+ * back to its prompt: `parentId` chains one record to the previous one in file
+ * order, not a reply to its question, so what opens the turn is the only
+ * boundary in the file.
+ *
+ * Deliberately not the assistant record's own `id`: one turn produces one
+ * assistant record per round of the agent loop — the captured two-tool turn has
+ * two — and keying on those would split one reply into several History rows.
+ *
+ * @param promptId - `id` of the user record that opened the turn
+ */
+function commandCodeTurnRequestId(promptId) {
+    return `${exports.COMMAND_CODE_MARKDOWN_REQUEST_ID_PREFIX}${promptId}`;
+}
+/**
+ * The row id for the **prompt** that opened one Command Code turn (Issue #2252).
+ *
+ * Same `id`, different prefix, and therefore a different row — exactly the
+ * relationship {@link claudePromptRequestId} has with {@link claudeTurnRequestId},
+ * and for the same reason: one record names one turn, and a turn is a user row
+ * plus an assistant row, so keying both on the record that opened it is what
+ * makes the pair reconstructible from the transcript alone, including on a
+ * re-read where both halves must resolve to "already there" independently.
+ *
+ * @param promptId - `id` of the user record the operator's text arrived on
+ */
+function commandCodePromptRequestId(promptId) {
+    return `${exports.COMMAND_CODE_PROMPT_REQUEST_ID_PREFIX}${promptId}`;
+}

package/dist/server/src/types/terminal-keys.js

@@ -19,7 +19,74 @@
  * Values only — no tmux process access — so this module is safe from any layer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TERMINAL_KEY_VALUES = exports.OPENCODE_NAVIGATION_KEY_VALUES = exports.OPENCODE_DIRECT_KEY_VALUES = exports.OPENCODE_LEADER_CHORD_VALUES = exports.OPENCODE_LEADER_KEY = exports.NAVIGATION_KEY_VALUES = void 0;
+exports.TERMINAL_KEY_VALUES = exports.OPENCODE_NAVIGATION_KEY_VALUES = exports.OPENCODE_DIRECT_KEY_VALUES = exports.OPENCODE_LEADER_CHORD_VALUES = exports.OPENCODE_LEADER_KEY = exports.SESSION_SCOPE_KEY_TOOL_IDS = exports.CLAUDE_NAVIGATION_KEY_VALUES = exports.NAVIGATION_KEY_VALUES = exports.SESSION_SCOPE_KEY = exports.ANSWER_KEY_VALUES = void 0;
+/**
+ * The characters a dialog is answered WITH rather than navigated by (Issue #2254).
+ *
+ * `1`–`9` are the option numbers every numbered TUI dialog in this repository
+ * offers (codex's trust / `/model` pickers, claude's `PermissionRequest`
+ * screens, the hooks-review flow), and `y` / `n` are the two letters a bare
+ * `[y/n]` accepts. They are LITERAL characters on the wire, exactly like the
+ * codex pager's `q` has been since #1017 and opencode's chord letters since
+ * #2046 — `tmux send-keys -- 1` types a `1`.
+ *
+ * WHY THEY ARE IN THE BASE VOCABULARY, i.e. offered to every tool
+ * ---------------------------------------------------------------
+ * The state this exists for is "a wait is on screen and nothing could read it"
+ * (`ChatSurface`'s `promptUnreadable`). By construction nobody knows which tool
+ * drew that dialog *shape*, so there is no per-tool declaration to hang these
+ * off; what IS known is that the dialog is waiting for an answer, and that the
+ * chat surface had no way to send one before this Issue — the `/send` route
+ * refuses with `prompt_waiting`, and `/special-keys` published only arrows.
+ *
+ * The cost is the same one #2046 weighed for opencode's letters: a caller may
+ * POST `{cliToolId:"claude", keys:["y"]}` at an IDLE pane and type a `y` into
+ * the composer. That is a typo, not an escalation — the route has always been
+ * able to type `q` into any composer, sending a character is what the route is
+ * FOR, and the UI only draws these buttons while a wait is unreadable. What is
+ * deliberately still refused is a free string: `/send`'s `prompt_waiting` guard
+ * is untouched, `MAX_KEYS_LENGTH` is 10, and every other letter stays a 400.
+ *
+ * Note the overlap with {@link OPENCODE_LEADER_CHORD_VALUES}: `n` is in both,
+ * and `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts` pins the
+ * intersection to exactly `['n']` so a future widening of either list cannot
+ * quietly hand another tool an opencode chord letter.
+ */
+exports.ANSWER_KEY_VALUES = [
+    '1', '2', '3', '4', '5', '6', '7', '8', '9',
+    'y', 'n',
+];
+/**
+ * claude's "use this session only" key (Issue #2297).
+ *
+ * MEASURED on claude 2.1.259 / 2.1.260 (`tests/fixtures/chat-dialog-card-2254/
+ * claude-model-2-1-259.txt`, and a live 200x1000 probe re-run for #2297): the
+ * `/model` overlay's footer reads
+ *
+ *     Enter to set as default · s to use this session only · Esc to cancel
+ *
+ * so on that ONE screen `Enter` is not "confirm" — it rewrites `model` in
+ * `~/.claude/settings.json` (Issue #1495), and `s` is the only key that takes
+ * the highlighted model for the current session and leaves the file alone.
+ * Neither the shared pad nor the transport carried `s`, so the chat surface
+ * could offer the destructive half of that footer and not the safe half.
+ *
+ * A LITERAL character on the wire, exactly like the codex pager's `q` (#1017),
+ * opencode's chord letters (#2046) and the answer characters (#2254):
+ * `tmux send-keys -- s` types an `s`.
+ *
+ * WHY IT IS **NOT** IN {@link NAVIGATION_KEY_VALUES}
+ * -------------------------------------------------
+ * Unlike #2254's answer characters, this one has a named owner. `s` is a live
+ * binding on other tools' screens — copilot's session picker footer reads
+ * `s sort:relevance` (measured on 1.0.82), and opencode types a bare letter
+ * into its composer whenever a leader chord is not in flight. Publishing `s` to
+ * every tool would hand those screens a button that does something else. So it
+ * is declared by the claude-family tools alone, through
+ * {@link CLAUDE_NAVIGATION_KEY_VALUES}, and the route's per-tool check
+ * (Issue #2046) answers 400 for everyone else.
+ */
+exports.SESSION_SCOPE_KEY = 's';
 /**
  * Navigation keys accepted by the special-keys API and the terminal UI.
  *
@@ -34,7 +101,46 @@ exports.NAVIGATION_KEY_VALUES = [
     // Issue #1017: Codex pager / edit-previous mode keys surfaced by NavigationButtons.
     // 'q' is the pager quit key (literal char). PageUp/PageDown/Home/End are tmux named keys.
     'PageUp', 'PageDown', 'Home', 'End', 'q',
+    // Issue #2254: the answer characters. Appended rather than interleaved so the
+    // pre-#2254 prefix of this list is still readable as one line in a diff.
+    ...exports.ANSWER_KEY_VALUES,
 ];
+/**
+ * What a claude-family pane may be sent: the base pad plus
+ * {@link SESSION_SCOPE_KEY} (Issue #2297).
+ *
+ * Returned by `ClaudeTool.navigationKeys()` and `CommandCodeTool.navigationKeys()`
+ * — the two tools whose TUI is claude's inline overlay renderer. Command Code
+ * takes it for kinship rather than for a measured `/model` footer of its own:
+ * its own picker (v1.40.1, measured for this Issue) is a name list with a search
+ * box and an `enter to select · esc to cancel` footer and offers no session
+ * scope at all, so nothing DRAWS the `s` button there — see
+ * `readSelectionListShape()`, which gates the button on the footer being on
+ * screen rather than on the tool id. Declaring the key for both keeps the two
+ * halves of the claude family from drifting apart the day Command Code grows the
+ * footer, and costs nothing while it has not: an undrawn button sends nothing.
+ *
+ * `tests/unit/lib/cli-tools/session-scope-key-2297.test.ts` pins the membership
+ * in both directions, and the #2046 suite still pins every OTHER tool to the
+ * base pad exactly.
+ */
+exports.CLAUDE_NAVIGATION_KEY_VALUES = [
+    ...exports.NAVIGATION_KEY_VALUES,
+    exports.SESSION_SCOPE_KEY,
+];
+/**
+ * The tool ids whose `navigationKeys()` carry {@link SESSION_SCOPE_KEY}.
+ *
+ * Read by the chat surface, which cannot call `navigationKeys()` — that lives
+ * behind the CLITool gateway on the server — but must not draw a button whose
+ * key the route would answer 400 for. Pinned against the real registry by
+ * `tests/unit/lib/cli-tools/session-scope-key-2297.test.ts`, so this list and
+ * the declarations cannot disagree.
+ *
+ * Typed as a plain string tuple rather than `CLIToolType[]` so this module keeps
+ * the "values only, safe from any layer" property its header depends on.
+ */
+exports.SESSION_SCOPE_KEY_TOOL_IDS = ['claude', 'command-code'];
 // ---------------------------------------------------------------------------
 // Per-tool vocabularies (Issue #2046)
 // ---------------------------------------------------------------------------
@@ -74,6 +180,25 @@ exports.OPENCODE_LEADER_CHORD_VALUES = [
  * `Tab` / `BTab` cycle the agent and are already in {@link NAVIGATION_KEY_VALUES}.
  */
 exports.OPENCODE_DIRECT_KEY_VALUES = ['C-p', 'C-t'];
+/**
+ * {@link OPENCODE_LEADER_CHORD_VALUES} minus what the base pad already carries.
+ *
+ * Issue #2254 moved `n` into {@link ANSWER_KEY_VALUES}, and therefore into
+ * {@link NAVIGATION_KEY_VALUES}, which every tool's declaration starts from —
+ * so spreading the full chord list into the two unions below would list `n`
+ * twice. A duplicate is harmless to `Array.prototype.includes`, which is all the
+ * route does with these, and that is exactly why it needs its own guard: the
+ * only thing that would notice is the "no duplicate entries" assertion in
+ * `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts`.
+ *
+ * Written out rather than filtered at runtime because both unions are `as const`
+ * tuples whose LITERAL member types are the `TerminalKey` union — a
+ * `.filter()` would collapse them to `string[]` and take the compile-time check
+ * with it. The same suite pins this list to
+ * `OPENCODE_LEADER_CHORD_VALUES \ NAVIGATION_KEY_VALUES` so it cannot drift out
+ * of step with either side.
+ */
+const OPENCODE_CHORD_ONLY_VALUES = ['a', 'l', 't', 'm', 'g', 'u', 'r', 'c'];
 /**
  * Everything an opencode pane may be sent — the base navigation pad plus this
  * tool's own chords. Returned by `OpenCodeTool.navigationKeys()`.
@@ -82,7 +207,7 @@ exports.OPENCODE_NAVIGATION_KEY_VALUES = [
     ...exports.NAVIGATION_KEY_VALUES,
     exports.OPENCODE_LEADER_KEY,
     ...exports.OPENCODE_DIRECT_KEY_VALUES,
-    ...exports.OPENCODE_LEADER_CHORD_VALUES,
+    ...OPENCODE_CHORD_ONLY_VALUES,
 ];
 /**
  * The union of every tool's vocabulary — what the tmux transport must be able to
@@ -99,7 +224,10 @@ exports.OPENCODE_NAVIGATION_KEY_VALUES = [
  */
 exports.TERMINAL_KEY_VALUES = [
     ...exports.NAVIGATION_KEY_VALUES,
+    // Issue #2297: claude / Command Code declare it; nothing else does.
+    exports.SESSION_SCOPE_KEY,
     exports.OPENCODE_LEADER_KEY,
     ...exports.OPENCODE_DIRECT_KEY_VALUES,
-    ...exports.OPENCODE_LEADER_CHORD_VALUES,
+    // Issue #2254: `n` is in the base pad now — see OPENCODE_CHORD_ONLY_VALUES.
+    ...OPENCODE_CHORD_ONLY_VALUES,
 ];

package/dist/types/terminal-keys.d.ts

@@ -17,6 +17,70 @@
  *
  * Values only — no tmux process access — so this module is safe from any layer.
  */
+/**
+ * The characters a dialog is answered WITH rather than navigated by (Issue #2254).
+ *
+ * `1`–`9` are the option numbers every numbered TUI dialog in this repository
+ * offers (codex's trust / `/model` pickers, claude's `PermissionRequest`
+ * screens, the hooks-review flow), and `y` / `n` are the two letters a bare
+ * `[y/n]` accepts. They are LITERAL characters on the wire, exactly like the
+ * codex pager's `q` has been since #1017 and opencode's chord letters since
+ * #2046 — `tmux send-keys -- 1` types a `1`.
+ *
+ * WHY THEY ARE IN THE BASE VOCABULARY, i.e. offered to every tool
+ * ---------------------------------------------------------------
+ * The state this exists for is "a wait is on screen and nothing could read it"
+ * (`ChatSurface`'s `promptUnreadable`). By construction nobody knows which tool
+ * drew that dialog *shape*, so there is no per-tool declaration to hang these
+ * off; what IS known is that the dialog is waiting for an answer, and that the
+ * chat surface had no way to send one before this Issue — the `/send` route
+ * refuses with `prompt_waiting`, and `/special-keys` published only arrows.
+ *
+ * The cost is the same one #2046 weighed for opencode's letters: a caller may
+ * POST `{cliToolId:"claude", keys:["y"]}` at an IDLE pane and type a `y` into
+ * the composer. That is a typo, not an escalation — the route has always been
+ * able to type `q` into any composer, sending a character is what the route is
+ * FOR, and the UI only draws these buttons while a wait is unreadable. What is
+ * deliberately still refused is a free string: `/send`'s `prompt_waiting` guard
+ * is untouched, `MAX_KEYS_LENGTH` is 10, and every other letter stays a 400.
+ *
+ * Note the overlap with {@link OPENCODE_LEADER_CHORD_VALUES}: `n` is in both,
+ * and `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts` pins the
+ * intersection to exactly `['n']` so a future widening of either list cannot
+ * quietly hand another tool an opencode chord letter.
+ */
+export declare const ANSWER_KEY_VALUES: readonly ["1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n"];
+/**
+ * claude's "use this session only" key (Issue #2297).
+ *
+ * MEASURED on claude 2.1.259 / 2.1.260 (`tests/fixtures/chat-dialog-card-2254/
+ * claude-model-2-1-259.txt`, and a live 200x1000 probe re-run for #2297): the
+ * `/model` overlay's footer reads
+ *
+ *     Enter to set as default · s to use this session only · Esc to cancel
+ *
+ * so on that ONE screen `Enter` is not "confirm" — it rewrites `model` in
+ * `~/.claude/settings.json` (Issue #1495), and `s` is the only key that takes
+ * the highlighted model for the current session and leaves the file alone.
+ * Neither the shared pad nor the transport carried `s`, so the chat surface
+ * could offer the destructive half of that footer and not the safe half.
+ *
+ * A LITERAL character on the wire, exactly like the codex pager's `q` (#1017),
+ * opencode's chord letters (#2046) and the answer characters (#2254):
+ * `tmux send-keys -- s` types an `s`.
+ *
+ * WHY IT IS **NOT** IN {@link NAVIGATION_KEY_VALUES}
+ * -------------------------------------------------
+ * Unlike #2254's answer characters, this one has a named owner. `s` is a live
+ * binding on other tools' screens — copilot's session picker footer reads
+ * `s sort:relevance` (measured on 1.0.82), and opencode types a bare letter
+ * into its composer whenever a leader chord is not in flight. Publishing `s` to
+ * every tool would hand those screens a button that does something else. So it
+ * is declared by the claude-family tools alone, through
+ * {@link CLAUDE_NAVIGATION_KEY_VALUES}, and the route's per-tool check
+ * (Issue #2046) answers 400 for everyone else.
+ */
+export declare const SESSION_SCOPE_KEY = "s";
 /**
  * Navigation keys accepted by the special-keys API and the terminal UI.
  *
@@ -26,11 +90,44 @@
  * [DR3-001] Named NAVIGATION_KEY_VALUES to avoid collision with existing SPECIAL_KEY_VALUES.
  * [DR2-004] Exported as an `as const` array + type guard (not a Set) for immutability.
  */
-export declare const NAVIGATION_KEY_VALUES: readonly ["Up", "Down", "Left", "Right", "Enter", "Escape", "Tab", "BTab", "PageUp", "PageDown", "Home", "End", "q"];
+export declare const NAVIGATION_KEY_VALUES: readonly ["Up", "Down", "Left", "Right", "Enter", "Escape", "Tab", "BTab", "PageUp", "PageDown", "Home", "End", "q", "1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n"];
 /**
  * Navigation key type derived from NAVIGATION_KEY_VALUES.
  */
 export type NavigationKey = typeof NAVIGATION_KEY_VALUES[number];
+/**
+ * What a claude-family pane may be sent: the base pad plus
+ * {@link SESSION_SCOPE_KEY} (Issue #2297).
+ *
+ * Returned by `ClaudeTool.navigationKeys()` and `CommandCodeTool.navigationKeys()`
+ * — the two tools whose TUI is claude's inline overlay renderer. Command Code
+ * takes it for kinship rather than for a measured `/model` footer of its own:
+ * its own picker (v1.40.1, measured for this Issue) is a name list with a search
+ * box and an `enter to select · esc to cancel` footer and offers no session
+ * scope at all, so nothing DRAWS the `s` button there — see
+ * `readSelectionListShape()`, which gates the button on the footer being on
+ * screen rather than on the tool id. Declaring the key for both keeps the two
+ * halves of the claude family from drifting apart the day Command Code grows the
+ * footer, and costs nothing while it has not: an undrawn button sends nothing.
+ *
+ * `tests/unit/lib/cli-tools/session-scope-key-2297.test.ts` pins the membership
+ * in both directions, and the #2046 suite still pins every OTHER tool to the
+ * base pad exactly.
+ */
+export declare const CLAUDE_NAVIGATION_KEY_VALUES: readonly ["Up", "Down", "Left", "Right", "Enter", "Escape", "Tab", "BTab", "PageUp", "PageDown", "Home", "End", "q", "1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n", "s"];
+/**
+ * The tool ids whose `navigationKeys()` carry {@link SESSION_SCOPE_KEY}.
+ *
+ * Read by the chat surface, which cannot call `navigationKeys()` — that lives
+ * behind the CLITool gateway on the server — but must not draw a button whose
+ * key the route would answer 400 for. Pinned against the real registry by
+ * `tests/unit/lib/cli-tools/session-scope-key-2297.test.ts`, so this list and
+ * the declarations cannot disagree.
+ *
+ * Typed as a plain string tuple rather than `CLIToolType[]` so this module keeps
+ * the "values only, safe from any layer" property its header depends on.
+ */
+export declare const SESSION_SCOPE_KEY_TOOL_IDS: readonly ["claude", "command-code"];
 /**
  * opencode's leader prefix — the first half of a two-step chord.
  *
@@ -69,7 +166,7 @@ export declare const OPENCODE_DIRECT_KEY_VALUES: readonly ["C-p", "C-t"];
  * Everything an opencode pane may be sent — the base navigation pad plus this
  * tool's own chords. Returned by `OpenCodeTool.navigationKeys()`.
  */
-export declare const OPENCODE_NAVIGATION_KEY_VALUES: readonly ["Up", "Down", "Left", "Right", "Enter", "Escape", "Tab", "BTab", "PageUp", "PageDown", "Home", "End", "q", "C-x", "C-p", "C-t", "a", "l", "n", "t", "m", "g", "u", "r", "c"];
+export declare const OPENCODE_NAVIGATION_KEY_VALUES: readonly ["Up", "Down", "Left", "Right", "Enter", "Escape", "Tab", "BTab", "PageUp", "PageDown", "Home", "End", "q", "1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n", "C-x", "C-p", "C-t", "a", "l", "t", "m", "g", "u", "r", "c"];
 /**
  * The union of every tool's vocabulary — what the tmux transport must be able to
  * deliver.
@@ -83,7 +180,7 @@ export declare const OPENCODE_NAVIGATION_KEY_VALUES: readonly ["Up", "Down", "Le
  * `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts` pin both
  * halves.
  */
-export declare const TERMINAL_KEY_VALUES: readonly ["Up", "Down", "Left", "Right", "Enter", "Escape", "Tab", "BTab", "PageUp", "PageDown", "Home", "End", "q", "C-x", "C-p", "C-t", "a", "l", "n", "t", "m", "g", "u", "r", "c"];
+export declare const TERMINAL_KEY_VALUES: readonly ["Up", "Down", "Left", "Right", "Enter", "Escape", "Tab", "BTab", "PageUp", "PageDown", "Home", "End", "q", "1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n", "s", "C-x", "C-p", "C-t", "a", "l", "t", "m", "g", "u", "r", "c"];
 /** Any key name a tool may declare in its {@link NavigationKeySpec}. */
 export type TerminalKey = typeof TERMINAL_KEY_VALUES[number];
 //# sourceMappingURL=terminal-keys.d.ts.map

package/dist/types/terminal-keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-keys.d.ts","sourceRoot":"","sources":["../../src/types/terminal-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,sHAKxB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAMjE;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,wDAE/B,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,yBAA0B,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,8BAA8B,wLAKjC,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,wLAKtB,CAAC;AAEX,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"terminal-keys.d.ts","sourceRoot":"","sources":["../../src/types/terminal-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,iBAAiB,kEAGpB,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,6KAQxB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,4BAA4B,kLAG/B,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,qCAAsC,CAAC;AAM9E;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,wDAE/B,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,yBAA0B,CAAC;AAsBlE;;;GAGG;AACH,eAAO,MAAM,8BAA8B,0OAKjC,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,+OAQtB,CAAC;AAEX,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC"}

package/dist/types/terminal-keys.js

@@ -19,7 +19,74 @@
  * Values only — no tmux process access — so this module is safe from any layer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TERMINAL_KEY_VALUES = exports.OPENCODE_NAVIGATION_KEY_VALUES = exports.OPENCODE_DIRECT_KEY_VALUES = exports.OPENCODE_LEADER_CHORD_VALUES = exports.OPENCODE_LEADER_KEY = exports.NAVIGATION_KEY_VALUES = void 0;
+exports.TERMINAL_KEY_VALUES = exports.OPENCODE_NAVIGATION_KEY_VALUES = exports.OPENCODE_DIRECT_KEY_VALUES = exports.OPENCODE_LEADER_CHORD_VALUES = exports.OPENCODE_LEADER_KEY = exports.SESSION_SCOPE_KEY_TOOL_IDS = exports.CLAUDE_NAVIGATION_KEY_VALUES = exports.NAVIGATION_KEY_VALUES = exports.SESSION_SCOPE_KEY = exports.ANSWER_KEY_VALUES = void 0;
+/**
+ * The characters a dialog is answered WITH rather than navigated by (Issue #2254).
+ *
+ * `1`–`9` are the option numbers every numbered TUI dialog in this repository
+ * offers (codex's trust / `/model` pickers, claude's `PermissionRequest`
+ * screens, the hooks-review flow), and `y` / `n` are the two letters a bare
+ * `[y/n]` accepts. They are LITERAL characters on the wire, exactly like the
+ * codex pager's `q` has been since #1017 and opencode's chord letters since
+ * #2046 — `tmux send-keys -- 1` types a `1`.
+ *
+ * WHY THEY ARE IN THE BASE VOCABULARY, i.e. offered to every tool
+ * ---------------------------------------------------------------
+ * The state this exists for is "a wait is on screen and nothing could read it"
+ * (`ChatSurface`'s `promptUnreadable`). By construction nobody knows which tool
+ * drew that dialog *shape*, so there is no per-tool declaration to hang these
+ * off; what IS known is that the dialog is waiting for an answer, and that the
+ * chat surface had no way to send one before this Issue — the `/send` route
+ * refuses with `prompt_waiting`, and `/special-keys` published only arrows.
+ *
+ * The cost is the same one #2046 weighed for opencode's letters: a caller may
+ * POST `{cliToolId:"claude", keys:["y"]}` at an IDLE pane and type a `y` into
+ * the composer. That is a typo, not an escalation — the route has always been
+ * able to type `q` into any composer, sending a character is what the route is
+ * FOR, and the UI only draws these buttons while a wait is unreadable. What is
+ * deliberately still refused is a free string: `/send`'s `prompt_waiting` guard
+ * is untouched, `MAX_KEYS_LENGTH` is 10, and every other letter stays a 400.
+ *
+ * Note the overlap with {@link OPENCODE_LEADER_CHORD_VALUES}: `n` is in both,
+ * and `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts` pins the
+ * intersection to exactly `['n']` so a future widening of either list cannot
+ * quietly hand another tool an opencode chord letter.
+ */
+exports.ANSWER_KEY_VALUES = [
+    '1', '2', '3', '4', '5', '6', '7', '8', '9',
+    'y', 'n',
+];
+/**
+ * claude's "use this session only" key (Issue #2297).
+ *
+ * MEASURED on claude 2.1.259 / 2.1.260 (`tests/fixtures/chat-dialog-card-2254/
+ * claude-model-2-1-259.txt`, and a live 200x1000 probe re-run for #2297): the
+ * `/model` overlay's footer reads
+ *
+ *     Enter to set as default · s to use this session only · Esc to cancel
+ *
+ * so on that ONE screen `Enter` is not "confirm" — it rewrites `model` in
+ * `~/.claude/settings.json` (Issue #1495), and `s` is the only key that takes
+ * the highlighted model for the current session and leaves the file alone.
+ * Neither the shared pad nor the transport carried `s`, so the chat surface
+ * could offer the destructive half of that footer and not the safe half.
+ *
+ * A LITERAL character on the wire, exactly like the codex pager's `q` (#1017),
+ * opencode's chord letters (#2046) and the answer characters (#2254):
+ * `tmux send-keys -- s` types an `s`.
+ *
+ * WHY IT IS **NOT** IN {@link NAVIGATION_KEY_VALUES}
+ * -------------------------------------------------
+ * Unlike #2254's answer characters, this one has a named owner. `s` is a live
+ * binding on other tools' screens — copilot's session picker footer reads
+ * `s sort:relevance` (measured on 1.0.82), and opencode types a bare letter
+ * into its composer whenever a leader chord is not in flight. Publishing `s` to
+ * every tool would hand those screens a button that does something else. So it
+ * is declared by the claude-family tools alone, through
+ * {@link CLAUDE_NAVIGATION_KEY_VALUES}, and the route's per-tool check
+ * (Issue #2046) answers 400 for everyone else.
+ */
+exports.SESSION_SCOPE_KEY = 's';
 /**
  * Navigation keys accepted by the special-keys API and the terminal UI.
  *
@@ -34,7 +101,46 @@ exports.NAVIGATION_KEY_VALUES = [
     // Issue #1017: Codex pager / edit-previous mode keys surfaced by NavigationButtons.
     // 'q' is the pager quit key (literal char). PageUp/PageDown/Home/End are tmux named keys.
     'PageUp', 'PageDown', 'Home', 'End', 'q',
+    // Issue #2254: the answer characters. Appended rather than interleaved so the
+    // pre-#2254 prefix of this list is still readable as one line in a diff.
+    ...exports.ANSWER_KEY_VALUES,
 ];
+/**
+ * What a claude-family pane may be sent: the base pad plus
+ * {@link SESSION_SCOPE_KEY} (Issue #2297).
+ *
+ * Returned by `ClaudeTool.navigationKeys()` and `CommandCodeTool.navigationKeys()`
+ * — the two tools whose TUI is claude's inline overlay renderer. Command Code
+ * takes it for kinship rather than for a measured `/model` footer of its own:
+ * its own picker (v1.40.1, measured for this Issue) is a name list with a search
+ * box and an `enter to select · esc to cancel` footer and offers no session
+ * scope at all, so nothing DRAWS the `s` button there — see
+ * `readSelectionListShape()`, which gates the button on the footer being on
+ * screen rather than on the tool id. Declaring the key for both keeps the two
+ * halves of the claude family from drifting apart the day Command Code grows the
+ * footer, and costs nothing while it has not: an undrawn button sends nothing.
+ *
+ * `tests/unit/lib/cli-tools/session-scope-key-2297.test.ts` pins the membership
+ * in both directions, and the #2046 suite still pins every OTHER tool to the
+ * base pad exactly.
+ */
+exports.CLAUDE_NAVIGATION_KEY_VALUES = [
+    ...exports.NAVIGATION_KEY_VALUES,
+    exports.SESSION_SCOPE_KEY,
+];
+/**
+ * The tool ids whose `navigationKeys()` carry {@link SESSION_SCOPE_KEY}.
+ *
+ * Read by the chat surface, which cannot call `navigationKeys()` — that lives
+ * behind the CLITool gateway on the server — but must not draw a button whose
+ * key the route would answer 400 for. Pinned against the real registry by
+ * `tests/unit/lib/cli-tools/session-scope-key-2297.test.ts`, so this list and
+ * the declarations cannot disagree.
+ *
+ * Typed as a plain string tuple rather than `CLIToolType[]` so this module keeps
+ * the "values only, safe from any layer" property its header depends on.
+ */
+exports.SESSION_SCOPE_KEY_TOOL_IDS = ['claude', 'command-code'];
 // ---------------------------------------------------------------------------
 // Per-tool vocabularies (Issue #2046)
 // ---------------------------------------------------------------------------
@@ -74,6 +180,25 @@ exports.OPENCODE_LEADER_CHORD_VALUES = [
  * `Tab` / `BTab` cycle the agent and are already in {@link NAVIGATION_KEY_VALUES}.
  */
 exports.OPENCODE_DIRECT_KEY_VALUES = ['C-p', 'C-t'];
+/**
+ * {@link OPENCODE_LEADER_CHORD_VALUES} minus what the base pad already carries.
+ *
+ * Issue #2254 moved `n` into {@link ANSWER_KEY_VALUES}, and therefore into
+ * {@link NAVIGATION_KEY_VALUES}, which every tool's declaration starts from —
+ * so spreading the full chord list into the two unions below would list `n`
+ * twice. A duplicate is harmless to `Array.prototype.includes`, which is all the
+ * route does with these, and that is exactly why it needs its own guard: the
+ * only thing that would notice is the "no duplicate entries" assertion in
+ * `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts`.
+ *
+ * Written out rather than filtered at runtime because both unions are `as const`
+ * tuples whose LITERAL member types are the `TerminalKey` union — a
+ * `.filter()` would collapse them to `string[]` and take the compile-time check
+ * with it. The same suite pins this list to
+ * `OPENCODE_LEADER_CHORD_VALUES \ NAVIGATION_KEY_VALUES` so it cannot drift out
+ * of step with either side.
+ */
+const OPENCODE_CHORD_ONLY_VALUES = ['a', 'l', 't', 'm', 'g', 'u', 'r', 'c'];
 /**
  * Everything an opencode pane may be sent — the base navigation pad plus this
  * tool's own chords. Returned by `OpenCodeTool.navigationKeys()`.
@@ -82,7 +207,7 @@ exports.OPENCODE_NAVIGATION_KEY_VALUES = [
     ...exports.NAVIGATION_KEY_VALUES,
     exports.OPENCODE_LEADER_KEY,
     ...exports.OPENCODE_DIRECT_KEY_VALUES,
-    ...exports.OPENCODE_LEADER_CHORD_VALUES,
+    ...OPENCODE_CHORD_ONLY_VALUES,
 ];
 /**
  * The union of every tool's vocabulary — what the tmux transport must be able to
@@ -99,7 +224,10 @@ exports.OPENCODE_NAVIGATION_KEY_VALUES = [
  */
 exports.TERMINAL_KEY_VALUES = [
     ...exports.NAVIGATION_KEY_VALUES,
+    // Issue #2297: claude / Command Code declare it; nothing else does.
+    exports.SESSION_SCOPE_KEY,
     exports.OPENCODE_LEADER_KEY,
     ...exports.OPENCODE_DIRECT_KEY_VALUES,
-    ...exports.OPENCODE_LEADER_CHORD_VALUES,
+    // Issue #2254: `n` is in the base pad now — see OPENCODE_CHORD_ONLY_VALUES.
+    ...OPENCODE_CHORD_ONLY_VALUES,
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.30.2",
+  "version": "0.31.0",
   "description": "A local control plane for agent CLIs — orchestration and visibility for Claude Code, Codex, Gemini CLI, and more across Git worktrees",
   "keywords": [
     "claude-code",