commandmate 0.30.1 → 0.31.0

package/dist/lib/session/tmux-session-surface.js

@@ -0,0 +1,525 @@
+"use strict";
+/**
+ * The tmux "surface" CommandMate publishes on its own sessions (Issue #2317).
+ *
+ * Everything here is a pure argument builder or a pure predicate — no
+ * `child_process`, no `@/` path alias, and one constants import. Three
+ * constraints put it here rather than under `lib/tmux/`, and all three are
+ * load-bearing:
+ *
+ * 1. **`tsconfig.cli.json` sets `"paths": {}`.** The CLI bundle resolves nothing
+ *    through `@/…`, so a module the `attach` command needs may only reach the
+ *    rest of `src/` through relative specifiers. `lib/tmux/tmux.ts` cannot be
+ *    that module — it imports `@/lib/cli-tools/validation` and `@/lib/logger`.
+ * 2. **The Issue #1922 import guard.** `.eslintrc.json` forbids `src/cli/**`
+ *    from importing anything matching `**‍/tmux/**`, and its allowlist is
+ *    explicitly one-way ("may only shrink"). A pure argv builder is not the kind
+ *    of tmux access that guard exists to stop — it issues no command and opens
+ *    no session — but the rule is a path pattern, so the module lives on a path
+ *    the CLI may read. Nothing here can reach tmux: the executors are in
+ *    `lib/tmux/`, and those are what the guard still covers.
+ * 3. **One wire form, two callers.** The server writes `@cm_status` from the
+ *    status poll and the CLI writes `@cm_delegated` from `attach --live`. If
+ *    each spelled its own `set-option` argv, the two could disagree about the
+ *    target form (`=name:` vs `name`), and a bare name prefix-matches — the
+ *    Issue #1156 leak, in a new place. Tests assert the builders, so a change to
+ *    the wire form is a change to exactly one line.
+ *
+ * ## What is deliberately NOT here
+ *
+ * Anything server-global. Every builder below takes a session name and produces
+ * a `-t <session>` form: `set-option -g`, `bind-key` and `set-hook -g` are
+ * absent on purpose (Issue #2317 決定事項 2 — the only global tmux mutation
+ * CommandMate makes is #1623's `bind-key`, and it stays where it is, in
+ * `lib/tmux/read-mode.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTACH_HOOK_FORMATS = exports.AUTO_POPUP_ENV = exports.LIVE_ATTACH_HOOK_ENV = exports.AUTO_POPUP_HOOK = exports.DELEGATE_HOOK = exports.ALT_SCREEN_TOOLS = exports.LIVE_ATTACH_TOOLS = exports.TMUX_STATUS_ENV = exports.CM_STATUS_RIGHT_FORMAT = exports.CM_SESSION_OPTIONS = exports.CM_DELEGATED_OPTION = exports.CM_UPDATED_OPTION = exports.CM_INSTANCE_OPTION = exports.CM_TOOL_OPTION = exports.CM_WORKTREE_OPTION = exports.CM_STATUS_OPTION = exports.MCBD_SESSION_PREFIX = void 0;
+exports.exactSessionTarget = exactSessionTarget;
+exports.isCommandMateSession = isCommandMateSession;
+exports.buildSetSessionOptionArgs = buildSetSessionOptionArgs;
+exports.buildUnsetSessionOptionArgs = buildUnsetSessionOptionArgs;
+exports.buildShowSessionOptionArgs = buildShowSessionOptionArgs;
+exports.buildShowSessionOptionValueArgs = buildShowSessionOptionValueArgs;
+exports.buildSetStatusRightArgs = buildSetStatusRightArgs;
+exports.buildUnsetStatusRightArgs = buildUnsetStatusRightArgs;
+exports.isTmuxStatusEnabled = isTmuxStatusEnabled;
+exports.buildSetSessionHookArgs = buildSetSessionHookArgs;
+exports.buildUnsetSessionHookArgs = buildUnsetSessionHookArgs;
+exports.buildShowSessionHooksArgs = buildShowSessionHooksArgs;
+exports.buildWindowSizeArgs = buildWindowSizeArgs;
+exports.buildResizeWindowArgs = buildResizeWindowArgs;
+exports.buildListClientsArgs = buildListClientsArgs;
+exports.countHumanClients = countHumanClients;
+exports.buildAttachArgs = buildAttachArgs;
+exports.buildSwitchClientArgs = buildSwitchClientArgs;
+exports.isLiveAttachSupported = isLiveAttachSupported;
+exports.isLiveAttachEligibleSession = isLiveAttachEligibleSession;
+exports.usesAltScreen = usesAltScreen;
+exports.isLiveAttachHookEnabled = isLiveAttachHookEnabled;
+exports.isAutoPopupEnabled = isAutoPopupEnabled;
+exports.quoteScriptPathForHook = quoteScriptPathForHook;
+exports.buildHookRunShellBody = buildHookRunShellBody;
+exports.buildInstallDelegateHookArgs = buildInstallDelegateHookArgs;
+exports.buildRemoveDelegateHookArgs = buildRemoveDelegateHookArgs;
+exports.buildInstallAutoPopupHookArgs = buildInstallAutoPopupHookArgs;
+exports.buildRemoveAutoPopupHookArgs = buildRemoveAutoPopupHookArgs;
+exports.buildDelegateGeometryCommands = buildDelegateGeometryCommands;
+exports.buildRestoreGeometryCommands = buildRestoreGeometryCommands;
+const tmux_pane_config_1 = require("../../config/tmux-pane-config");
+/**
+ * Session-name prefix every CommandMate tmux session carries.
+ *
+ * `lib/tmux/read-mode.ts` owns a constant of the same name for #1623's key
+ * binding; `tests/unit/tmux/session-surface-2317.test.ts` pins the two together
+ * so a rename breaks a test instead of silently turning a guard into a permanent
+ * "never fire". Not imported from `cli-tools/base.ts` because it is a template
+ * literal there, not a constant.
+ */
+exports.MCBD_SESSION_PREFIX = 'mcbd-';
+/**
+ * Exact-match tmux target for a session (Issue #1156's `=name:` form).
+ *
+ * The same string `exactTarget()` in `lib/tmux/tmux.ts` produces — that function
+ * stays the one the server-side module uses, and the test above pins the two to
+ * each other so this copy cannot drift. It exists at all because `tmux.ts` is
+ * unreachable from the CLI bundle (see the module docblock).
+ *
+ * @param sessionName - Exact tmux session name
+ * @returns `=<name>:` — exact session match, valid as both a session and a
+ *   window/pane target
+ */
+function exactSessionTarget(sessionName) {
+    return `=${sessionName}:`;
+}
+/** True when `sessionName` looks like a session CommandMate created. */
+function isCommandMateSession(sessionName) {
+    return sessionName.startsWith(exports.MCBD_SESSION_PREFIX);
+}
+// ---------------------------------------------------------------------------
+// Phase B: the state CommandMate publishes onto its own sessions
+// ---------------------------------------------------------------------------
+/** User option carrying the session's status word. */
+exports.CM_STATUS_OPTION = '@cm_status';
+/** User option carrying the worktree id the session belongs to. */
+exports.CM_WORKTREE_OPTION = '@cm_worktree';
+/** User option carrying the CLI tool id running in the session. */
+exports.CM_TOOL_OPTION = '@cm_tool';
+/** User option carrying the agent instance id. */
+exports.CM_INSTANCE_OPTION = '@cm_instance';
+/** User option carrying the ISO timestamp of the last status write. */
+exports.CM_UPDATED_OPTION = '@cm_updated';
+/**
+ * User option set to `1` while a human client owns the session's geometry
+ * (Phase D). Read by the server so it can stand down from resizing and from
+ * saving a scraped reply off a terminal-sized frame.
+ */
+exports.CM_DELEGATED_OPTION = '@cm_delegated';
+/**
+ * Every `@cm_*` option this feature writes, in the order they are removed.
+ *
+ * The opt-out path (`CM_TMUX_STATUS=off`) iterates this list rather than
+ * re-typing names, so an option added above cannot be left behind on a user's
+ * tmux server.
+ */
+exports.CM_SESSION_OPTIONS = [
+    exports.CM_STATUS_OPTION,
+    exports.CM_WORKTREE_OPTION,
+    exports.CM_TOOL_OPTION,
+    exports.CM_INSTANCE_OPTION,
+    exports.CM_UPDATED_OPTION,
+    exports.CM_DELEGATED_OPTION,
+];
+/**
+ * The session-scoped `status-right` CommandMate installs.
+ *
+ * A tmux FORMAT, not an interpolated string: the values come from the `@cm_*`
+ * options above, so the status line re-renders on every status write without a
+ * second write for the line itself. `window_width`x`window_height` is on it
+ * because the whole Issue is about a window whose size the reader cannot see —
+ * during Phase D delegation it is the fastest way to tell whether the geometry
+ * handover actually happened.
+ */
+exports.CM_STATUS_RIGHT_FORMAT = '[CommandMate #{@cm_tool}/#{@cm_instance} #{@cm_status}] #{window_width}x#{window_height}';
+/** `tmux set-option -t <session> <name> <value>`. */
+function buildSetSessionOptionArgs(sessionName, option, value) {
+    return ['set-option', '-t', exactSessionTarget(sessionName), option, value];
+}
+/** `tmux set-option -u -t <session> <name>` — remove a session-scoped value. */
+function buildUnsetSessionOptionArgs(sessionName, option) {
+    return ['set-option', '-u', '-t', exactSessionTarget(sessionName), option];
+}
+/**
+ * `tmux show-options -t <session> <name>`.
+ *
+ * Deliberately WITHOUT `-v`: the empty-vs-set distinction is the whole point of
+ * the call at the `status-right` site. Measured on tmux 3.5a — a session that
+ * has never had `status-right` set answers with empty stdout and exit 0, and one
+ * that has answers `status-right "…"`. `-v` would print an empty line for the
+ * first case too, and "the user already customised this session" would become
+ * indistinguishable from "nobody has".
+ */
+function buildShowSessionOptionArgs(sessionName, option) {
+    return ['show-options', '-t', exactSessionTarget(sessionName), option];
+}
+/**
+ * `tmux show-options -v -t <session> <name>` — the VALUE alone.
+ *
+ * The right shape when only the value matters (`@cm_delegated` is `1` or it is
+ * nothing). {@link buildShowSessionOptionArgs} is the right shape when the
+ * distinction between "set to empty" and "never set" matters, which is the
+ * `status-right` case.
+ */
+function buildShowSessionOptionValueArgs(sessionName, option) {
+    return ['show-options', '-v', '-t', exactSessionTarget(sessionName), option];
+}
+/** `tmux set-option -t <session> status-right '<format>'`. */
+function buildSetStatusRightArgs(sessionName, format) {
+    return buildSetSessionOptionArgs(sessionName, 'status-right', format);
+}
+/** `tmux set-option -u -t <session> status-right`. */
+function buildUnsetStatusRightArgs(sessionName) {
+    return buildUnsetSessionOptionArgs(sessionName, 'status-right');
+}
+/** Environment variable that turns the Phase B surface off. */
+exports.TMUX_STATUS_ENV = 'CM_TMUX_STATUS';
+/**
+ * True unless the operator set `CM_TMUX_STATUS` to `off` / `0` / `false`.
+ *
+ * Read at CALL time from an injected environment rather than at module load, so
+ * a test can flip it without module-registry surgery and so a process started
+ * with the variable set is not at the mercy of import order.
+ */
+function isTmuxStatusEnabled(env = process.env) {
+    const raw = (env[exports.TMUX_STATUS_ENV] ?? '').trim().toLowerCase();
+    return raw !== 'off' && raw !== '0' && raw !== 'false';
+}
+// ---------------------------------------------------------------------------
+// Session-scoped hooks
+// ---------------------------------------------------------------------------
+/**
+ * `tmux set-hook -t <session> <hook> <command>`.
+ *
+ * The command is passed as ONE argv element. Do not fold an `if-shell -F` into
+ * it: measured on tmux 3.5a (Issue #2317 技術検証), a hook body of the shape
+ * `if-shell -F '#{…}' 'display-popup …'` is accepted and then silently never
+ * fires. A `run-shell -b '<script> #{session_name} #{client_control_mode}'` that
+ * hands the formats to a script DOES fire, so every hook this feature installs
+ * has that shape and the branching happens in the script.
+ */
+function buildSetSessionHookArgs(sessionName, hook, command) {
+    return ['set-hook', '-t', exactSessionTarget(sessionName), hook, command];
+}
+/** `tmux set-hook -u -t <session> <hook>`. */
+function buildUnsetSessionHookArgs(sessionName, hook) {
+    return ['set-hook', '-u', '-t', exactSessionTarget(sessionName), hook];
+}
+/** `tmux show-hooks -t <session>` — session-scoped hooks only, never the global table. */
+function buildShowSessionHooksArgs(sessionName) {
+    return ['show-hooks', '-t', exactSessionTarget(sessionName)];
+}
+// ---------------------------------------------------------------------------
+// Geometry
+// ---------------------------------------------------------------------------
+/** `tmux set-window-option -t <session> window-size <mode>`. */
+function buildWindowSizeArgs(sessionName, mode) {
+    return ['set-window-option', '-t', exactSessionTarget(sessionName), 'window-size', mode];
+}
+/** `tmux resize-window -t <session> -x <w> -y <h>`. */
+function buildResizeWindowArgs(sessionName, width, height) {
+    return [
+        'resize-window',
+        '-t',
+        exactSessionTarget(sessionName),
+        '-x',
+        String(width),
+        '-y',
+        String(height),
+    ];
+}
+/**
+ * `tmux list-clients -t <session> -F '#{client_control_mode}'`.
+ *
+ * `client_control_mode` is `1` for a `tmux -C` client — which is what
+ * CommandMate's own control-mode transport attaches as — and `0` for a human
+ * terminal. Phase D hands the geometry back when the HUMAN count reaches zero,
+ * so a control client sitting on the session forever must not keep the
+ * delegation open (Issue #2317 受入条件 Phase D 4).
+ */
+function buildListClientsArgs(sessionName) {
+    return ['list-clients', '-t', exactSessionTarget(sessionName), '-F', '#{client_control_mode}'];
+}
+/**
+ * Number of human (control-mode `0`) clients in `list-clients` output.
+ *
+ * Counts lines that are exactly `0`, NOT lines that are "anything but 1". The
+ * difference matters twice: `list-clients` exits 0 with EMPTY stdout on a
+ * detached session, and a line this function does not recognise is not evidence
+ * that a person is looking at the pane. Since the answer gates a resize, "I
+ * could not read this" has to mean "nobody is attached" — the reading that
+ * leaves `reconcileSessionGeometry` doing its normal job — rather than "somebody
+ * is", which would pin a window open on an unparsed byte.
+ *
+ * `#{client_control_mode}` is `1` for a `tmux -C` client and `0` for a terminal;
+ * measured on tmux 3.5a, a human client attached to a CommandMate session
+ * reports exactly `0`.
+ *
+ * @param stdout - Raw stdout of {@link buildListClientsArgs}
+ * @returns How many attached clients are humans
+ */
+function countHumanClients(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line === '0').length;
+}
+/** `tmux attach-session -t '=<session>:'`, with `-r` when read-only. */
+function buildAttachArgs(sessionName, readOnly) {
+    const args = ['attach-session'];
+    if (readOnly)
+        args.push('-r');
+    args.push('-t', exactSessionTarget(sessionName));
+    return args;
+}
+/** `tmux switch-client -t '=<session>:'` — the in-tmux equivalent of attaching. */
+function buildSwitchClientArgs(sessionName) {
+    return ['switch-client', '-t', exactSessionTarget(sessionName)];
+}
+// ---------------------------------------------------------------------------
+// Which tools each behaviour applies to
+// ---------------------------------------------------------------------------
+/**
+ * CLI tools `attach --live` will hand the pane geometry to (Issue #2317 決定事項 3).
+ *
+ * claude alone, and the list is a measurement rather than a starting point:
+ * claude's reply is written from its own transcript JSONL, so a terminal-sized
+ * frame during delegation cannot lose History. Every other tool either reads its
+ * reply off the pane (copilot / gemini / vibe-local), or has detection rules
+ * that were only ever measured at 200x1000 (codex / antigravity / command-code),
+ * or cannot survive a width change at all (opencode paints a sidebar at >=121
+ * columns). Widening this set is out of scope for #2317 and requires
+ * re-measuring the tool it adds.
+ */
+exports.LIVE_ATTACH_TOOLS = ['claude'];
+/** Whether `attach --live` is allowed for a CLI tool. */
+function isLiveAttachSupported(cliToolId) {
+    return exports.LIVE_ATTACH_TOOLS.includes(cliToolId);
+}
+/**
+ * Whether a tmux session's NAME says it runs a tool `--live` supports.
+ *
+ * The session name is `mcbd-<tool>-<worktree>` and no supported tool id is a
+ * prefix of another, so this is exact rather than a guess. It exists because
+ * the two callers that need the answer — the attach hook script's installer and
+ * the response poller — hold a session name and nothing else: a hook fires with
+ * tmux formats, and the poller must not pay a tmux round-trip to ask about a
+ * session that could never be delegated in the first place.
+ *
+ * @param sessionName - tmux session name
+ */
+function isLiveAttachEligibleSession(sessionName) {
+    if (!isCommandMateSession(sessionName))
+        return false;
+    return exports.LIVE_ATTACH_TOOLS.some((tool) => sessionName.startsWith(`${exports.MCBD_SESSION_PREFIX}${tool}-`));
+}
+/**
+ * CLI tools that paint their transcript in the terminal's alternate screen.
+ *
+ * The reason a bare `tmux attach` looks EMPTY for them: the TUI draws the
+ * transcript at the top of a 1000-row canvas and its composer at the bottom, and
+ * tmux follows the cursor, so a 44-row client sees the composer and nothing
+ * else. `attach` prints its hint for exactly these.
+ *
+ * Deliberately a local list rather than an import of `usesAlternateScreen()`:
+ * this module must stay free of `lib/cli-tools`, whose graph the CLI bundle
+ * cannot afford (see the module docblock). The two are pinned to each other by
+ * `tests/unit/tmux/session-surface-2317.test.ts`, so a tool moving in or out of
+ * the alternate screen breaks a test rather than silently dropping the hint.
+ */
+exports.ALT_SCREEN_TOOLS = ['claude', 'opencode', 'copilot'];
+/** Whether `attach` should warn that a bare attach shows no transcript. */
+function usesAltScreen(cliToolId) {
+    return exports.ALT_SCREEN_TOOLS.includes(cliToolId);
+}
+// ---------------------------------------------------------------------------
+// Phase D: live attach — handing the geometry over and taking it back
+// ---------------------------------------------------------------------------
+/**
+ * ## The safety net is a poll, NOT a `client-detached` hook — measured
+ *
+ * Issue #2317's 技術検証 says a session-scoped `client-detached` hook fires.
+ * Re-measured on tmux 3.5a against a private socket before this was written, it
+ * does not, and two further facts make the shape unusable:
+ *
+ * | probe (tmux 3.5a, `tmux -L`)                        | result |
+ * |-----------------------------------------------------|--------|
+ * | `set-hook -t <s> client-attached`, human attaches    | fires; `#{session_name}` is the session, `#{client_control_mode}` is `0` |
+ * | same, control-mode client attaches                   | does NOT fire |
+ * | `set-hook -t <s> client-detached`, human detaches    | **never fires** |
+ * | `set-hook -g client-detached`, human detaches        | fires — but `#{session_name}` is the CLIENT's other session and `#{client_control_mode}` is EMPTY |
+ *
+ * So the detach edge is unreachable session-scoped, and reaching it globally
+ * would both break 決定事項 2 (no global tmux mutation) and arrive without the
+ * session identity the restore needs. The restore therefore runs from the status
+ * poll instead — `reconcileDelegatedGeometry()` in `lib/tmux/session-hooks.ts` —
+ * which sees every session every couple of seconds, needs no tmux state of its
+ * own, and covers cases a hook could not anyway: the CLI being killed, the
+ * terminal window being closed, and a detach from some other client.
+ *
+ * The `client-attached` edge DOES work session-scoped, and that is the one the
+ * opt-in hooks below are installed on.
+ *
+ * Both opt-in features hang off that same edge, and a tmux hook name without an
+ * index IS `[0]`: installing two of them unindexed would mean the second
+ * silently replaced the first. Measured on tmux 3.5a — `client-attached[0]` and
+ * `client-attached[1]` both fire, and `set-hook -u` removes one without
+ * disturbing the other.
+ */
+exports.DELEGATE_HOOK = 'client-attached[0]';
+/** @see DELEGATE_HOOK */
+exports.AUTO_POPUP_HOOK = 'client-attached[1]';
+/**
+ * Environment variable that also installs the geometry hand-over for a session
+ * the user attached to BY HAND (`tmux attach`), not through
+ * `commandmate attach --live`.
+ *
+ * Opt-in, because installing it unasked would mean a hand-rolled `tmux attach`
+ * silently changes a session's geometry — the one thing Issue #2317 決定事項 1
+ * says must not happen by default.
+ */
+exports.LIVE_ATTACH_HOOK_ENV = 'CM_LIVE_ATTACH_HOOK';
+/**
+ * Environment variable that opens the following read popup on attach (Phase C).
+ * Default off; see `AUTO_POPUP_SCRIPT` for why.
+ */
+exports.AUTO_POPUP_ENV = 'CM_READ_MODE_AUTO_POPUP';
+/** True when the operator opted into the attach-time geometry hand-over. */
+function isLiveAttachHookEnabled(env = process.env) {
+    return (env[exports.LIVE_ATTACH_HOOK_ENV] ?? '').trim().toLowerCase() === 'on';
+}
+/** True when the operator opted into the automatic read popup. */
+function isAutoPopupEnabled(env = process.env) {
+    return (env[exports.AUTO_POPUP_ENV] ?? '').trim().toLowerCase() === 'on';
+}
+/**
+ * Quote a path for the `sh` command a tmux hook runs.
+ *
+ * Double quotes rather than single, because the whole shell-command is already
+ * inside tmux's own single quotes and tmux's lexer does not process escapes
+ * inside those — a `'\''` would end the tmux string, not the shell one.
+ *
+ * Returns undefined for a path carrying any character that would change the
+ * meaning of a double-quoted word (`"`, `$`, a backtick, a backslash) or that
+ * cannot appear on a command line at all (newline / carriage return). Callers
+ * treat that as "install no hook": a home directory nobody can quote safely is a
+ * reason to fall back to the CLI's own hand-over, not a reason to run a command
+ * whose parse is a guess.
+ *
+ * @param path - Absolute script path
+ * @returns The double-quoted word, or undefined when it cannot be represented
+ */
+function quoteScriptPathForHook(path) {
+    if (/["$`\\\n\r]/.test(path))
+        return undefined;
+    return `"${path}"`;
+}
+/**
+ * The `run-shell` body of a session-scoped hook.
+ *
+ * `-b` because a hook that blocks the tmux server for the length of a shell
+ * script is a hook that makes tmux feel broken.
+ *
+ * The formats are passed as separate words and consumed as `$1`, `$2`, `$3` by
+ * the script, which is why none of them is quoted here — a tmux format that
+ * expanded to something with a space would be split, and all three of these
+ * (`session_name`, `client_control_mode`, `client_name`) are single words by
+ * construction.
+ *
+ * @param quotedScriptPath - Result of {@link quoteScriptPathForHook}
+ * @param formats - tmux formats to hand the script
+ * @param extraArgs - Literal words appended after the formats
+ * @returns The command string to hand to `set-hook`
+ */
+function buildHookRunShellBody(quotedScriptPath, formats, extraArgs = []) {
+    const words = [quotedScriptPath, ...formats, ...extraArgs].join(' ');
+    return `run-shell -b '${words}'`;
+}
+/**
+ * Formats every attach hook hands to its script.
+ *
+ * `#{client_name}` is included for both because the auto-popup needs it
+ * (`display-popup -c <client>`) and the delegate script ignores extra arguments
+ * — one format list is one thing to keep right.
+ */
+exports.ATTACH_HOOK_FORMATS = [
+    '#{session_name}',
+    '#{client_control_mode}',
+    '#{client_name}',
+];
+/**
+ * `set-hook -t <session> client-attached[0] 'run-shell -b …'`, or undefined when
+ * the script path cannot be quoted safely.
+ *
+ * @param sessionName - Target session
+ * @param scriptPath - Absolute path of the materialized delegate script
+ */
+function buildInstallDelegateHookArgs(sessionName, scriptPath) {
+    const quoted = quoteScriptPathForHook(scriptPath);
+    if (quoted === undefined)
+        return undefined;
+    return buildSetSessionHookArgs(sessionName, exports.DELEGATE_HOOK, buildHookRunShellBody(quoted, exports.ATTACH_HOOK_FORMATS));
+}
+/** `set-hook -u -t <session> client-attached[0]`. */
+function buildRemoveDelegateHookArgs(sessionName) {
+    return buildUnsetSessionHookArgs(sessionName, exports.DELEGATE_HOOK);
+}
+/**
+ * `set-hook -t <session> client-attached[1] 'run-shell -b …'`, or undefined when
+ * the script path cannot be quoted safely.
+ */
+function buildInstallAutoPopupHookArgs(sessionName, scriptPath) {
+    const quoted = quoteScriptPathForHook(scriptPath);
+    if (quoted === undefined)
+        return undefined;
+    return buildSetSessionHookArgs(sessionName, exports.AUTO_POPUP_HOOK, buildHookRunShellBody(quoted, exports.ATTACH_HOOK_FORMATS));
+}
+/** `set-hook -u -t <session> client-attached[1]`. */
+function buildRemoveAutoPopupHookArgs(sessionName) {
+    return buildUnsetSessionHookArgs(sessionName, exports.AUTO_POPUP_HOOK);
+}
+/**
+ * The tmux commands that hand a session's geometry to the attaching terminal.
+ *
+ * Ordered: the flag is raised BEFORE `window-size latest`, so a status poll that
+ * lands between the two sees "delegated, still 200x1000" — which suppresses the
+ * scraped save one poll early — rather than "not delegated, 44 rows", which
+ * would save a truncated reply. The cheap failure is the safe one.
+ *
+ * @param sessionName - Target session
+ * @returns Argument vectors, to run in order
+ */
+function buildDelegateGeometryCommands(sessionName) {
+    return [
+        buildSetSessionOptionArgs(sessionName, exports.CM_DELEGATED_OPTION, '1'),
+        buildWindowSizeArgs(sessionName, 'latest'),
+    ];
+}
+/**
+ * The tmux commands that take a session's geometry back.
+ *
+ * The mirror image of {@link buildDelegateGeometryCommands}, and ordered the
+ * other way for the same reason: the canvas is restored first and the flag is
+ * dropped last, so no poll can ever see "not delegated" while the pane is still
+ * the size of somebody's terminal.
+ *
+ * @param sessionName - Target session
+ * @param width - Canvas width (defaults to the pinned {@link TUI_PANE_WIDTH})
+ * @param height - Canvas height (defaults to the pinned {@link TUI_PANE_HEIGHT})
+ */
+function buildRestoreGeometryCommands(sessionName, width = tmux_pane_config_1.TUI_PANE_WIDTH, height = tmux_pane_config_1.TUI_PANE_HEIGHT) {
+    return [
+        buildWindowSizeArgs(sessionName, 'manual'),
+        buildResizeWindowArgs(sessionName, width, height),
+        buildUnsetSessionOptionArgs(sessionName, exports.CM_DELEGATED_OPTION),
+    ];
+}

package/dist/server/src/config/cli-tool-timing-config.js

@@ -20,7 +20,7 @@
  * All values are preserved from the original literals (no behavior change).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIVENESS_CONFIRM_DELAY_MS = exports.CLAUDE_RESTART_DELAY_MS = exports.CLAUDE_ENV_SANITIZE_WAIT_MS = exports.VIBE_LOCAL_DOUBLE_ENTER_WAIT_MS = exports.COPILOT_EXIT_WAIT_MS = exports.OPENCODE_INTERRUPT_SECOND_ESCAPE_DELAY_MS = exports.OPENCODE_EXIT_WAIT_MS = exports.CODEX_DIALOG_SETTLE_MS = exports.TUI_EXIT_WAIT_MS = exports.TUI_INTERRUPT_SETTLE_MS = exports.TUI_MESSAGE_PROCESSED_WAIT_MS = exports.TUI_TEXT_INPUT_WAIT_MS = exports.TUI_SESSION_CREATE_WAIT_MS = void 0;
+exports.LIVENESS_CONFIRM_DELAY_MS = exports.CLAUDE_RESTART_DELAY_MS = exports.CLAUDE_ENV_SANITIZE_WAIT_MS = exports.COMMAND_CODE_INIT_WAIT_MS = exports.VIBE_LOCAL_DOUBLE_ENTER_WAIT_MS = exports.COPILOT_EXIT_WAIT_MS = exports.OPENCODE_INTERRUPT_SECOND_ESCAPE_DELAY_MS = exports.OPENCODE_EXIT_WAIT_MS = exports.CODEX_DIALOG_SETTLE_MS = exports.TUI_EXIT_WAIT_MS = exports.TUI_INTERRUPT_SETTLE_MS = exports.TUI_MESSAGE_PROCESSED_WAIT_MS = exports.TUI_TEXT_INPUT_WAIT_MS = exports.TUI_SESSION_CREATE_WAIT_MS = void 0;
 /**
  * Wait (ms) after `createSession()` before sending the first keys, giving tmux
  * time to spin up the session.
@@ -127,6 +127,17 @@ exports.COPILOT_EXIT_WAIT_MS = 3000;
  * Site: vibe-local sendMessage().
  */
 exports.VIBE_LOCAL_DOUBLE_ENTER_WAIT_MS = 200;
+/**
+ * How long Command Code needs before its composer is worth polling for
+ * (Issue #2250).
+ *
+ * The same 3000 ms agy's launch uses, and for the same reason: the readiness
+ * poll below it is what actually decides, so this only keeps the first
+ * `capture-pane` from firing at a pane that still holds a shell prompt. Measured
+ * launches of 1.40.1 drew the composer at ~2.5 s (block-art logo, three banner
+ * rows, then the rules).
+ */
+exports.COMMAND_CODE_INIT_WAIT_MS = 3000;
 /**
  * Wait (ms) for the `unset CLAUDECODE` command to reach the shell while
  * sanitizing the session environment (empirically determined).

package/dist/server/src/config/detection-evidence-config.js

@@ -74,6 +74,11 @@ exports.IDLE_EVIDENCE_DEFAULT_MODE = {
     gemini: 'legacy',
     antigravity: 'legacy',
     'vibe-local': 'legacy',
+    // Issue #2250: Command Code ships `legacy` for the reason D1 決定 1 gives --
+    // its module declares no `readIdleEvidence`, so the chain answers `'positive'`
+    // whatever this row says, and claiming `enforce` would state a rollout that
+    // does not exist. Epic #2249 決定 3 pins the same value from the other side.
+    'command-code': 'legacy',
 };
 /**
  * The kill switch.

package/dist/server/src/config/schedule-config.js

@@ -10,7 +10,7 @@
  * [S4-014] UUID v4 format validation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UUID_V4_PATTERN = exports.DEFAULT_PERMISSIONS = exports.NO_PERMISSION_FLAGS = exports.OPENCODE_PERMISSIONS = exports.VIBE_LOCAL_PERMISSIONS = exports.GEMINI_PERMISSIONS = exports.ANTIGRAVITY_PERMISSIONS = exports.COPILOT_PERMISSIONS = exports.CODEX_SANDBOXES = exports.CLAUDE_PERMISSIONS = exports.MAX_SCHEDULE_CRON_LENGTH = exports.MAX_SCHEDULE_MESSAGE_LENGTH = exports.MAX_SCHEDULE_NAME_LENGTH = void 0;
+exports.UUID_V4_PATTERN = exports.DEFAULT_PERMISSIONS = exports.NO_PERMISSION_FLAGS = exports.OPENCODE_PERMISSIONS = exports.VIBE_LOCAL_PERMISSIONS = exports.GEMINI_PERMISSIONS = exports.COMMAND_CODE_PERMISSIONS = exports.ANTIGRAVITY_PERMISSIONS = exports.COPILOT_PERMISSIONS = exports.CODEX_SANDBOXES = exports.CLAUDE_PERMISSIONS = exports.MAX_SCHEDULE_CRON_LENGTH = exports.MAX_SCHEDULE_MESSAGE_LENGTH = exports.MAX_SCHEDULE_NAME_LENGTH = void 0;
 exports.getPermissionOptionsForTool = getPermissionOptionsForTool;
 exports.isValidUuidV4 = isValidUuidV4;
 // =============================================================================
@@ -38,6 +38,30 @@ exports.COPILOT_PERMISSIONS = [
 exports.ANTIGRAVITY_PERMISSIONS = [
     '--dangerously-skip-permissions',
 ];
+/**
+ * Allowed permission values for Command Code CLI (`--permission-mode`),
+ * Issue #2250.
+ *
+ * Read off the shipped bundle rather than off `--help`, and the two disagree:
+ * `commandcode --help` advertises `(standard, plan, auto-accept)`, while the
+ * option is declared
+ * `.addOption(new Be("--permission-mode <mode>", …).choices(["default",
+ * "standard","plan","auto-accept","dont-ask"]))` in
+ * `command-code@1.40.1/dist/cli.mjs`. `.choices()` is what actually validates,
+ * so all five are accepted and `default` is the one the tool reports back in its
+ * own hook payloads (`"permission_mode":"default"`).
+ *
+ * `--yolo` / `--dangerously-skip-permissions` is a separate boolean flag rather
+ * than a `--permission-mode` value, so it is not on this list — the same axis
+ * distinction `OPENCODE_PERMISSIONS` records for `--auto`.
+ */
+exports.COMMAND_CODE_PERMISSIONS = [
+    'default',
+    'standard',
+    'plan',
+    'auto-accept',
+    'dont-ask',
+];
 /** Allowed permission values for gemini CLI (no permission flags) */
 exports.GEMINI_PERMISSIONS = [];
 /** Allowed permission values for vibe-local CLI (no permission flags) */
@@ -84,6 +108,7 @@ exports.DEFAULT_PERMISSIONS = {
     opencode: '',
     copilot: 'allow-all-tools',
     antigravity: '--dangerously-skip-permissions',
+    'command-code': 'default',
 };
 /**
  * Resolve the allowed Permission dropdown options for a CLI tool (Issue #824).
@@ -118,6 +143,8 @@ function getPermissionOptionsForTool(cliToolId) {
             return exports.COPILOT_PERMISSIONS;
         case 'antigravity':
             return exports.ANTIGRAVITY_PERMISSIONS;
+        case 'command-code':
+            return exports.COMMAND_CODE_PERMISSIONS;
         case 'gemini':
             return exports.GEMINI_PERMISSIONS;
         case 'vibe-local':

package/dist/server/src/lib/cli-tools/antigravity.js

@@ -20,7 +20,7 @@ const sources_1 = require("../../lib/hooks/sources");
 const agent_session_lifecycle_1 = require("../../lib/session/agent-session-lifecycle");
 const logger_1 = require("../../lib/logger");
 const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
-const session_start_error_1 = require("../session/session-start-error");
+const install_hints_1 = require("./install-hints");
 const logger = (0, logger_1.createLogger)('cli-tools/antigravity');
 /**
  * Extract error message from unknown error type (DRY).
@@ -109,7 +109,7 @@ class AntigravityTool extends base_1.BaseCLITool {
         // Check if agy is installed
         const available = await this.isInstalled();
         if (!available) {
-            throw new session_start_error_1.SessionStartUnavailableError(this.name, 'Antigravity CLI (agy) is not installed or not in PATH');
+            throw (0, install_hints_1.missingToolError)(this);
         }
         const sessionName = this.getSessionName(worktreeId, instanceId);
         // Check if session already exists

package/dist/server/src/lib/cli-tools/base.js

@@ -291,16 +291,21 @@ class BaseCLITool {
      *
      * The default IS the pre-#2046 global list, verbatim: the twelve navigation
      * keys plus the codex pager's `q` that `NAVIGATION_KEY_VALUES` has published
-     * since #1017, and no leader. claude / codex / copilot / gemini / antigravity
-     * / vibe-local all take it unchanged, which is the point of putting it here
-     * rather than copying a literal into six classes — there is no per-tool list
-     * to drift, so "the six existing tools' key sets did not change" is true by
-     * construction and not merely by review.
+     * since #1017, and no leader. codex / copilot / gemini / antigravity /
+     * vibe-local all take it unchanged, which is the point of putting it here
+     * rather than copying a literal into five classes — there is no per-tool list
+     * to drift, so "those tools' key sets did not change" is true by construction
+     * and not merely by review.
      * `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts` asserts it
      * against `NAVIGATION_KEY_VALUES` anyway, because a future edit could still
-     * add an override to one of the six.
-     *
-     * opencode overrides it. Nothing else does.
+     * add an override to one of them.
+     *
+     * THREE tools override it now:
+     *  - opencode, with its `ctrl+x` leader and chord letters (#2046);
+     *  - claude and Command Code, with `CLAUDE_NAVIGATION_KEY_VALUES` — the base
+     *    pad plus `s`, the key claude's `/model` footer offers for "use this
+     *    session only" while `Enter` on the same overlay rewrites the user's
+     *    global default (#2297 / #1495).
      *
      * @returns This tool's {@link NavigationKeySpec}
      */