commandmate 0.37.0 → 0.38.1

package/dist/server/src/lib/session/claude-executor.js

@@ -14,12 +14,15 @@
  * - Validates cliToolId against ALLOWED_CLI_TOOLS whitelist [SEC-001]
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COMMAND_CODE_EXIT_REASONS = exports.ALLOWED_CLI_TOOLS = exports.MAX_MESSAGE_LENGTH = exports.EXECUTION_TIMEOUT_MS = exports.MAX_STORED_OUTPUT_SIZE = exports.MAX_OUTPUT_SIZE = void 0;
+exports.EXECUTION_LOG_WARNING_HEAD_LENGTH = exports.COMMAND_CODE_BLOCKED_WARNING_PREFIX = exports.COMMAND_CODE_EXIT_REASONS = exports.ALLOWED_CLI_TOOLS = exports.MAX_MESSAGE_LENGTH = exports.EXECUTION_TIMEOUT_MS = exports.MAX_STORED_OUTPUT_SIZE = exports.MAX_OUTPUT_SIZE = void 0;
 exports.getCommandForTool = getCommandForTool;
 exports.truncateOutput = truncateOutput;
 exports.buildCliArgs = buildCliArgs;
 exports.extractOpencodeFinalText = extractOpencodeFinalText;
 exports.extractCommandCodeResult = extractCommandCodeResult;
+exports.readCommandCodeStream = readCommandCodeStream;
+exports.describeCommandCodeBlockedToolCalls = describeCommandCodeBlockedToolCalls;
+exports.readExecutionLogWarning = readExecutionLogWarning;
 exports.describeCommandCodeFailure = describeCommandCodeFailure;
 exports.executeClaudeCommand = executeClaudeCommand;
 exports.getActiveProcesses = getActiveProcesses;
@@ -210,7 +213,9 @@ function buildCliArgs(message, cliToolId, permission, options) {
             // `shell_command` / `monitor_command` / `kill_shell` with `block: true`;
             // the mode flag never reaches it. A blocked call does not fail the run —
             // it ends exit 0 with `subtype: "success"` — so a schedule that asked for
-            // `default` looked successful and changed nothing.
+            // `default` looked successful and changed nothing. (Issue #2577 now
+            // records those blocks as a warning beside the status; see
+            // {@link readCommandCodeStream}.)
             //
             // So the column now spells `--yolo` as the value `yolo`
             // ({@link COMMAND_CODE_SCHEDULE_PERMISSIONS}, copilot's shape), and the
@@ -444,7 +449,44 @@ exports.COMMAND_CODE_EXIT_REASONS = {
  * @returns The decoded result line, or null when stdout carried none
  */
 function extractCommandCodeResult(stdout) {
-    let found = null;
+    return readCommandCodeStream(stdout).result;
+}
+/**
+ * The result line *and* the blocked tool calls of one command-code stream.
+ *
+ * ## Why the blocks are read here, before the result line wins
+ *
+ * Issue #2577: `commandcode -p` without `--yolo` gets the `print-permission-gate`
+ * mod, which blocks `edit_file` / `write_file` / `shell_command` /
+ * `monitor_command` / `kill_shell`. A blocked call does not fail the run — it
+ * ends exit 0 with `subtype: "success"` — and the only trace of the refusal is
+ * an event in the middle of the stream. Keeping just the result line threw that
+ * event away, so a run whose every write was refused was stored as the model's
+ * `finalText`, which need not mention the refusal at all.
+ *
+ * The measured event (1.53.1, fixtures under
+ * `tests/unit/session/fixtures/command-code-tool-hook-blocked-2577/`) is
+ *
+ * ```text
+ * {"type":"event","event":{"type":"tool_hook_blocked","toolCallId":"call_…",
+ *  "toolName":"write_file","hookOutput":"Error: Tool \"write_file\" requires permissions. …"}}
+ * ```
+ *
+ * and `executeOne` returns straight after emitting it, so a blocked call has no
+ * `tool_running` / `tool_completed`. That is why the blocks are counted off this
+ * event and not inferred from tool results or from `finalText`.
+ *
+ * Every block is kept, whichever mod raised it: the gate's five tools are the
+ * case that prompted this, but a call a user's own hook refused is equally a
+ * call that did not happen.
+ *
+ * @param stdout - Raw stdout from `commandcode -p … --output-format json`
+ * @returns The decoded stream; never throws
+ */
+function readCommandCodeStream(stdout) {
+    let result = null;
+    const blockedToolCalls = [];
+    let startedToolCalls = 0;
     for (const line of stdout.split('\n')) {
         const trimmed = line.trim();
         if (!trimmed.startsWith('{'))
@@ -459,17 +501,127 @@ function extractCommandCodeResult(stdout) {
         if (typeof frame !== 'object' || frame === null)
             continue;
         const record = frame;
-        if (record.type !== 'result')
+        if (record.type === 'result') {
+            if (typeof record.subtype !== 'string')
+                continue;
+            result = {
+                subtype: record.subtype,
+                finalText: typeof record.finalText === 'string' ? record.finalText : '',
+                ...(typeof record.error === 'string' ? { error: record.error } : {}),
+            };
+            continue;
+        }
+        if (record.type !== 'event')
             continue;
-        if (typeof record.subtype !== 'string')
+        if (typeof record.event !== 'object' || record.event === null)
             continue;
-        found = {
-            subtype: record.subtype,
-            finalText: typeof record.finalText === 'string' ? record.finalText : '',
-            ...(typeof record.error === 'string' ? { error: record.error } : {}),
-        };
+        const event = record.event;
+        if (event.type === 'tool_running') {
+            startedToolCalls += 1;
+            continue;
+        }
+        if (event.type === 'tool_hook_blocked') {
+            blockedToolCalls.push({
+                toolCallId: typeof event.toolCallId === 'string' ? event.toolCallId : null,
+                // A block with no name is still a block; counting it matters more than
+                // naming it.
+                toolName: typeof event.toolName === 'string' && event.toolName !== ''
+                    ? event.toolName
+                    : '(unnamed tool)',
+                hookOutput: typeof event.hookOutput === 'string' ? event.hookOutput : '',
+            });
+        }
+    }
+    return { result, blockedToolCalls, startedToolCalls };
+}
+/**
+ * How a stored execution-log result starts when the run had blocked tool calls.
+ *
+ * The list API matches this against the head of `execution_logs.result` without
+ * reading the rest of the column, which is why the warning is always the first
+ * line of the output rather than wherever it would read best.
+ */
+exports.COMMAND_CODE_BLOCKED_WARNING_PREFIX = 'Warning: command-code blocked ';
+/**
+ * How many characters of `execution_logs.result` the list API reads to recover
+ * the warning line. The summary line is bounded well below this (tool names are
+ * capped in count and length), so the line is never cut by the read.
+ */
+exports.EXECUTION_LOG_WARNING_HEAD_LENGTH = 1024;
+const MAX_WARNING_TOOL_NAMES = 5;
+const MAX_WARNING_TOOL_NAME_LENGTH = 80;
+const MAX_WARNING_DETAIL_LINES = 5;
+const MAX_WARNING_HOOK_OUTPUT_LENGTH = 300;
+/** The summary line's exact shape, so an answer that merely quotes the prefix is not read as one. */
+const BLOCKED_WARNING_LINE = /^Warning: command-code blocked \d+ tool call\(s\) \(tool_hook_blocked\): /;
+/** Text from the stream, flattened to one bounded line. */
+function toWarningField(text, maxLength) {
+    const flattened = (0, cli_patterns_1.stripAnsi)(text).replace(/[\x00-\x1f\x7f\s]+/g, ' ').trim();
+    return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}…` : flattened;
+}
+/**
+ * The warning block for a stream that carried blocked tool calls, or null.
+ *
+ * The first line is the summary — how many calls were blocked, which tools, and
+ * how many tool calls did run — and is what the execution-log list shows. The
+ * lines after it carry each distinct `hookOutput`, so the detail view says *why*
+ * without the operator digging through the event dump that is no longer stored.
+ *
+ * It does not judge whether the run produced anything. "Were calls blocked" and
+ * "how did the CLI exit" are recorded as two facts; whether a report was written
+ * or a mail went out is not something this layer can see (Issue #2577 対応内容 3).
+ *
+ * @param stream - A decoded stream from {@link readCommandCodeStream}
+ * @returns `[summary, ...details]`, or null when nothing was blocked
+ */
+function describeCommandCodeBlockedToolCalls(stream) {
+    const { blockedToolCalls, startedToolCalls } = stream;
+    if (blockedToolCalls.length === 0)
+        return null;
+    const countsByTool = new Map();
+    const detailLines = new Map();
+    for (const call of blockedToolCalls) {
+        const toolName = toWarningField(call.toolName, MAX_WARNING_TOOL_NAME_LENGTH);
+        countsByTool.set(toolName, (countsByTool.get(toolName) ?? 0) + 1);
+        const hookOutput = toWarningField(call.hookOutput, MAX_WARNING_HOOK_OUTPUT_LENGTH)
+            || '(no hook output)';
+        const key = JSON.stringify([toolName, hookOutput]);
+        if (!detailLines.has(key))
+            detailLines.set(key, `Blocked ${toolName}: ${hookOutput}`);
+    }
+    const tools = [...countsByTool]
+        .slice(0, MAX_WARNING_TOOL_NAMES)
+        .map(([toolName, count]) => `${toolName} (${count})`);
+    if (countsByTool.size > MAX_WARNING_TOOL_NAMES) {
+        tools.push(`+${countsByTool.size - MAX_WARNING_TOOL_NAMES} more`);
+    }
+    const summary = `${exports.COMMAND_CODE_BLOCKED_WARNING_PREFIX}${blockedToolCalls.length} tool call(s)`
+        + ` (tool_hook_blocked): ${tools.join(', ')}; ${startedToolCalls} tool call(s) ran`;
+    const details = [...detailLines.values()].slice(0, MAX_WARNING_DETAIL_LINES);
+    if (detailLines.size > MAX_WARNING_DETAIL_LINES) {
+        details.push(`Blocked: +${detailLines.size - MAX_WARNING_DETAIL_LINES} more distinct reason(s)`);
     }
-    return found;
+    return [summary, ...details];
+}
+/**
+ * The blocked-tool-call warning at the head of a stored execution-log result,
+ * or null.
+ *
+ * Only the first line is considered, and only in the exact summary shape
+ * {@link describeCommandCodeBlockedToolCalls} writes, so an answer that happens
+ * to contain the words further down — or a row written before Issue #2577 — is
+ * not flagged.
+ *
+ * @param result - `execution_logs.result`, or any prefix of it at least
+ *   {@link EXECUTION_LOG_WARNING_HEAD_LENGTH} characters long
+ * @returns The summary line, or null
+ */
+function readExecutionLogWarning(result) {
+    if (typeof result !== 'string')
+        return null;
+    const newline = result.indexOf('\n');
+    const firstLine = newline === -1 ? result : result.slice(0, newline);
+    return BLOCKED_WARNING_LINE.test(firstLine) ? firstLine : null;
 }
 /**
  * One line naming why a Command Code run failed, or null when it did not.
@@ -548,11 +700,21 @@ async function executeClaudeCommand(message, cwd, cliToolId = 'claude', permissi
                 // line — so the answer and the CLI's own reason are on stdout even
                 // here. Decoding them turns a log that said "Error: Command failed"
                 // over a 4KB event dump into the reason plus the text.
-                const commandCodeResult = cliToolId === 'command-code'
-                    ? extractCommandCodeResult(stdout || '')
+                //
+                // Issue #2577: the same stream says which tool calls were blocked. A
+                // failed or timed-out run stays failed or timed out — the warning is
+                // recorded next to that verdict, never instead of it — and it goes
+                // first because the list API only reads the head of the stored result.
+                const commandCodeStream = cliToolId === 'command-code'
+                    ? readCommandCodeStream(stdout || '')
+                    : null;
+                const commandCodeResult = commandCodeStream ? commandCodeStream.result : null;
+                const blockedWarning = commandCodeStream
+                    ? describeCommandCodeBlockedToolCalls(commandCodeStream)
                     : null;
                 const exitCodeNumber = typeof errCode === 'number' ? errCode : null;
                 const errorSummary = [
+                    ...(blockedWarning ?? []),
                     `Error: ${error.message}`,
                     `Code: ${errCode ?? 'unknown'}`,
                     `Signal: ${error.signal ?? 'none'}`,
@@ -581,6 +743,7 @@ async function executeClaudeCommand(message, cwd, cliToolId = 'claude', permissi
                     exitCode: exitCodeNumber,
                     status: isTimeout ? 'timeout' : 'failed',
                     error: error.message,
+                    ...(blockedWarning ? { warning: blockedWarning[0] } : {}),
                 });
                 return;
             }
@@ -596,15 +759,25 @@ async function executeClaudeCommand(message, cwd, cliToolId = 'claude', permissi
             // practice — but the subtype is read rather than assumed, because
             // "the process exited 0" and "the agent answered" are two facts and
             // this layer is the only one that can still see the second.
+            //
+            // Issue #2577: and exit 0 with `subtype: "success"` is also what a run
+            // whose every write was refused by `print-permission-gate` looks like.
+            // Failing it would also fail the run that was refused once and got its
+            // work done another way, so the status stays the CLI's verdict and the
+            // blocks are recorded beside it: a warning line at the head of the
+            // output (where the list API finds it) and `warning` on the result.
             if (cliToolId === 'command-code') {
-                const result = extractCommandCodeResult(stdout || '');
-                const failure = describeCommandCodeFailure(0, result);
-                const body = result ? result.finalText : (stdout || '');
+                const stream = readCommandCodeStream(stdout || '');
+                const failure = describeCommandCodeFailure(0, stream.result);
+                const blockedWarning = describeCommandCodeBlockedToolCalls(stream);
+                const body = stream.result ? stream.result.finalText : (stdout || '');
+                const head = [...(blockedWarning ?? []), ...(failure ? [failure] : [])];
                 resolve({
-                    output: truncateOutput((0, cli_patterns_1.stripAnsi)(failure ? `${failure}\n${body}` : body)),
+                    output: truncateOutput((0, cli_patterns_1.stripAnsi)([...head, body].join('\n'))),
                     exitCode: 0,
                     status: failure ? 'failed' : 'completed',
                     ...(failure ? { error: failure } : {}),
+                    ...(blockedWarning ? { warning: blockedWarning[0] } : {}),
                 });
                 return;
             }

package/dist/server/src/types/cli-tool-contracts.js

@@ -15,12 +15,13 @@
  * and types only — nothing here touches a process.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GRACEFUL_EXIT_FAILURE_REASONS = exports.KEY_SEQUENCE_KEY_NAMES = void 0;
+exports.AGENT_MODE_NOTE_IDS = exports.AGENT_MODE_UNKNOWN = exports.AGENT_MODE_IDS = exports.GRACEFUL_EXIT_FAILURE_REASONS = exports.KEY_SEQUENCE_KEY_NAMES = void 0;
 exports.keyStep = keyStep;
 exports.literalStep = literalStep;
 exports.isLiteralStep = isLiteralStep;
 exports.isKeyStep = isKeyStep;
 exports.isKeySequenceKeyName = isKeySequenceKeyName;
+exports.isAgentModeId = isAgentModeId;
 // ---------------------------------------------------------------------------
 // Key sequences (受入条件 S9)
 // ---------------------------------------------------------------------------
@@ -73,3 +74,76 @@ function isKeySequenceKeyName(name) {
  *      worktree, silently. The number must not be reused until it goes quiet.
  */
 exports.GRACEFUL_EXIT_FAILURE_REASONS = ['graceful_exit_timeout', 'port_orphaned'];
+// ---------------------------------------------------------------------------
+// Permission / approval mode cycling (Issue #2592)
+// ---------------------------------------------------------------------------
+/**
+ * Every permission-mode name CommandMate can name, across every tool.
+ *
+ * A **union of measured vocabularies**, not a model of one tool's state machine.
+ * Six of the eight supported CLIs put a mode on `shift+tab`, and no two spell
+ * their modes the same way or cycle the same members — claude has four and no
+ * "default", codex has two, Command Code cycles three but can *sit* in two more
+ * that its cycle skips. So the ids here are the superset, and which of them a
+ * given tool can be in is that tool's own {@link AgentModeSpec.cycle}.
+ *
+ * Measured 2026-09-16 across all eight tools at the production 200x60 geometry
+ * (Issue #2592), plus the footer tables #1927 (claude 2.1.240) and #2250
+ * (Command Code 1.40.1 / 1.49.0) already carried:
+ *
+ * | id              | who prints it                    | spelling on the pane            |
+ * |-----------------|----------------------------------|---------------------------------|
+ * | `manual`        | claude                           | `⏸ manual mode on`              |
+ * | `auto`          | claude                           | `⏵⏵ auto mode on`               |
+ * | `accept-edits`  | claude / Command Code / agy      | `⏵⏵ accept edits on`, `» accept edits on`, `accept-edits ·` |
+ * | `plan`          | all five                         | `⏸ plan mode on`, `plan mode`, `Plan mode (shift+tab to cycle)`, `plan` |
+ * | `autopilot`     | copilot                          | `autopilot` in the hint bar     |
+ * | `bypass`        | Command Code (NOT in its cycle)  | `» permission bypass on`        |
+ * | `dont-ask`      | Command Code (NOT in its cycle)  | `» don't-ask on`                |
+ * | `default`       | Command Code                     | `? for shortcuts` (its own row) |
+ *
+ * `bypass` and `dont-ask` are declared even though `shift+tab` cannot REACH
+ * them, and that is the point: a user who put Command Code in one of those from
+ * the terminal is in a state the pane can be read for, and leaving them out
+ * would make the reader fall through to whichever indicator matched next — on
+ * 1.53.1, where `? for shortcuts` is drawn in every mode, that fall-through is
+ * a chip that says `default` while the agent bypasses permissions.
+ */
+exports.AGENT_MODE_IDS = [
+    'default',
+    'manual',
+    'accept-edits',
+    'plan',
+    'auto',
+    'autopilot',
+    'bypass',
+    'dont-ask',
+];
+/**
+ * The verdict for a frame nothing in {@link AgentModeSpec.indicators} matched.
+ *
+ * **Not a mode.** It is the reader declining to answer, and every consumer must
+ * treat it that way: the chip is not drawn, `capture --json` publishes the
+ * string rather than a guess, and nothing anywhere maps it to `default`.
+ *
+ * The distinction is load-bearing because four of the five tools draw NOTHING in
+ * their base mode (Issue #2592 §「設計に効く事実」3). If "no row" meant `default`
+ * then every frame captured mid-repaint, every frame whose footer scrolled out
+ * of the read window, and every future build that renames a row would publish a
+ * confident `default` for a pane that might be in `plan`. A missing chip is a
+ * question the operator can answer by looking at the terminal; a wrong chip is
+ * one they have no reason to ask.
+ */
+exports.AGENT_MODE_UNKNOWN = 'unknown';
+/** Whether `value` is a mode id (as opposed to {@link AGENT_MODE_UNKNOWN}). */
+function isAgentModeId(value) {
+    return exports.AGENT_MODE_IDS.includes(value);
+}
+/**
+ * A translator key for a caution the UI must print next to the mode button.
+ *
+ * A token rather than prose because the sentence is user-facing and has to be
+ * translated (`.eslintrc.json`'s i18n rule, Issue #1271), and because the tool
+ * declaring it has no way to call `useTranslations()`.
+ */
+exports.AGENT_MODE_NOTE_IDS = ['codexModelCoupled'];

package/dist/types/cli-tool-contracts.d.ts

@@ -399,4 +399,166 @@ export type ToolLivenessVerdict = {
     readonly alive: false;
     readonly reason: string;
 };
+/**
+ * Every permission-mode name CommandMate can name, across every tool.
+ *
+ * A **union of measured vocabularies**, not a model of one tool's state machine.
+ * Six of the eight supported CLIs put a mode on `shift+tab`, and no two spell
+ * their modes the same way or cycle the same members — claude has four and no
+ * "default", codex has two, Command Code cycles three but can *sit* in two more
+ * that its cycle skips. So the ids here are the superset, and which of them a
+ * given tool can be in is that tool's own {@link AgentModeSpec.cycle}.
+ *
+ * Measured 2026-09-16 across all eight tools at the production 200x60 geometry
+ * (Issue #2592), plus the footer tables #1927 (claude 2.1.240) and #2250
+ * (Command Code 1.40.1 / 1.49.0) already carried:
+ *
+ * | id              | who prints it                    | spelling on the pane            |
+ * |-----------------|----------------------------------|---------------------------------|
+ * | `manual`        | claude                           | `⏸ manual mode on`              |
+ * | `auto`          | claude                           | `⏵⏵ auto mode on`               |
+ * | `accept-edits`  | claude / Command Code / agy      | `⏵⏵ accept edits on`, `» accept edits on`, `accept-edits ·` |
+ * | `plan`          | all five                         | `⏸ plan mode on`, `plan mode`, `Plan mode (shift+tab to cycle)`, `plan` |
+ * | `autopilot`     | copilot                          | `autopilot` in the hint bar     |
+ * | `bypass`        | Command Code (NOT in its cycle)  | `» permission bypass on`        |
+ * | `dont-ask`      | Command Code (NOT in its cycle)  | `» don't-ask on`                |
+ * | `default`       | Command Code                     | `? for shortcuts` (its own row) |
+ *
+ * `bypass` and `dont-ask` are declared even though `shift+tab` cannot REACH
+ * them, and that is the point: a user who put Command Code in one of those from
+ * the terminal is in a state the pane can be read for, and leaving them out
+ * would make the reader fall through to whichever indicator matched next — on
+ * 1.53.1, where `? for shortcuts` is drawn in every mode, that fall-through is
+ * a chip that says `default` while the agent bypasses permissions.
+ */
+export declare const AGENT_MODE_IDS: readonly ["default", "manual", "accept-edits", "plan", "auto", "autopilot", "bypass", "dont-ask"];
+/** One permission mode a supported CLI can be in. */
+export type AgentModeId = typeof AGENT_MODE_IDS[number];
+/**
+ * The verdict for a frame nothing in {@link AgentModeSpec.indicators} matched.
+ *
+ * **Not a mode.** It is the reader declining to answer, and every consumer must
+ * treat it that way: the chip is not drawn, `capture --json` publishes the
+ * string rather than a guess, and nothing anywhere maps it to `default`.
+ *
+ * The distinction is load-bearing because four of the five tools draw NOTHING in
+ * their base mode (Issue #2592 §「設計に効く事実」3). If "no row" meant `default`
+ * then every frame captured mid-repaint, every frame whose footer scrolled out
+ * of the read window, and every future build that renames a row would publish a
+ * confident `default` for a pane that might be in `plan`. A missing chip is a
+ * question the operator can answer by looking at the terminal; a wrong chip is
+ * one they have no reason to ask.
+ */
+export declare const AGENT_MODE_UNKNOWN = "unknown";
+/** What {@link AgentModeSpec.indicators} can be read to say about a frame. */
+export type AgentMode = AgentModeId | typeof AGENT_MODE_UNKNOWN;
+/** Whether `value` is a mode id (as opposed to {@link AGENT_MODE_UNKNOWN}). */
+export declare function isAgentModeId(value: string): value is AgentModeId;
+/**
+ * One "this frame is in mode X" reading.
+ *
+ * `pattern` is applied to a **stripAnsi-ed** row. Every measured indicator lives
+ * inside SGR sequences on the wire — claude's footer arrives as
+ * `\x1b[38;5;220m⏵⏵ auto mode on\x1b[38;5;246m (shift+tab to cycle)` — so a
+ * pattern run against raw bytes matches nothing at all. `tests/fixtures/
+ * agent-mode-2592/` keeps ANSI-bearing frames so that regression fails a test
+ * rather than a user's screen.
+ */
+export interface AgentModeIndicator {
+    /** The mode this row proves the tool is in. */
+    readonly mode: AgentModeId;
+    /**
+     * Whole-row pattern, matched against the stripped row.
+     *
+     * No `/g` (keeps `.test()` stateless) and no nested quantifiers (ReDoS-safe),
+     * the same rule `cli-patterns.ts` documents for every pattern in this repo.
+     */
+    readonly pattern: RegExp;
+}
+/**
+ * A translator key for a caution the UI must print next to the mode button.
+ *
+ * A token rather than prose because the sentence is user-facing and has to be
+ * translated (`.eslintrc.json`'s i18n rule, Issue #1271), and because the tool
+ * declaring it has no way to call `useTranslations()`.
+ */
+export declare const AGENT_MODE_NOTE_IDS: readonly ["codexModelCoupled"];
+/** Which caution one tool's mode button carries, if any. */
+export type AgentModeNoteId = typeof AGENT_MODE_NOTE_IDS[number];
+/**
+ * How one tool cycles permission modes, and how its current mode is read
+ * (Issue #2592).
+ *
+ * Returned by `ICLITool.agentModeSpec()`, `null` for a tool that has no mode on
+ * `shift+tab`. The §4 D4 shape {@link ComposerSpec} / {@link CaptureSpec} /
+ * {@link ToolLivenessSpec} / {@link NavigationKeySpec} already take: the tool
+ * answers for itself and nothing outside `src/lib/cli-tools/**` branches on a
+ * `CLIToolType`.
+ *
+ * ## Why the mode is READ and not remembered
+ *
+ * CommandMate is not the only thing pressing this key. `commandmate attach`
+ * puts the operator in the same pane, the agent's own `/permissions` command
+ * moves the mode, and a restart of the CommandMate server forgets everything.
+ * A counter incremented per button press would be wrong after any of those and
+ * would stay wrong silently, which is exactly the failure #2592's B half exists
+ * to prevent ("B 無しの A は盲打ちになって使えない"). So the tool's own footer is
+ * the only source, and when it cannot be read the answer is
+ * {@link AGENT_MODE_UNKNOWN}.
+ *
+ * ## The #2032 invariant, restated
+ *
+ * {@link key} must be a key `sendSpecialKeys()` will actually deliver AND one
+ * this tool's {@link NavigationKeySpec} publishes, or the button draws a request
+ * the route answers 400 for (or, worse, validates and then throws mid-send —
+ * Issue #2032's exact shape). `tests/unit/lib/cli-tools/agent-mode-declaration-2592.test.ts`
+ * pins both halves against the real registry.
+ */
+export interface AgentModeSpec {
+    /**
+     * The key that advances the cycle — `BTab` for all five declaring tools.
+     *
+     * Declared rather than hard-coded so the invariant above is checkable, and so
+     * a tool that moves its binding changes one line.
+     */
+    readonly key: TerminalKey;
+    /**
+     * The cycle, in the order measured by pressing {@link key} repeatedly.
+     *
+     * The first element is where the measurement started, not a "default": claude
+     * has no default mode at all. A mode this tool can SIT in but cannot reach
+     * with {@link key} (Command Code's `bypass` / `dont-ask`) is deliberately
+     * absent here and present in {@link indicators} — the cycle is what the button
+     * does, the indicators are what the pane can say.
+     */
+    readonly cycle: readonly AgentModeId[];
+    /**
+     * How a mode is recognised, most specific FIRST.
+     *
+     * The reader returns the first match, so an indicator that is drawn in every
+     * mode (Command Code's `? for shortcuts` on 1.53.1) must come last or it wins
+     * over the row that actually names the mode.
+     */
+    readonly indicators: readonly AgentModeIndicator[];
+    /**
+     * How many non-blank rows from the bottom of the frame {@link indicators} may
+     * look at.
+     *
+     * A window, not the frame, for the reason `ToolLivenessSpec.aliveTailLines`
+     * is one: a mode row does not disappear when the mode changes, it scrolls up.
+     * Command Code renders INLINE (#2250 measured `alternate_on` 0), so a 1000-row
+     * capture of its pane holds every footer it has ever drawn, and a whole-frame
+     * test would answer with the oldest one forever.
+     */
+    readonly tailRows: number;
+    /**
+     * A caution this tool's button must carry, or `null`.
+     *
+     * codex alone today: its modes are coupled to the model and reasoning effort
+     * (`xhigh` ⇄ `medium`, measured 2026-09-16), so one press of a button labelled
+     * "mode" also moves the model tier. Issue #2592 §「設計に効く事実」4 requires
+     * that be visible rather than discovered.
+     */
+    readonly noteId: AgentModeNoteId | null;
+}
 //# sourceMappingURL=cli-tool-contracts.d.ts.map

package/dist/types/cli-tool-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-tool-contracts.d.ts","sourceRoot":"","sources":["../../src/types/cli-tool-contracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-tool-contracts.d.ts","sourceRoot":"","sources":["../../src/types/cli-tool-contracts.ts"],"names":[],"mappings":"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"}

package/dist/types/cli-tool-contracts.js

@@ -15,12 +15,13 @@
  * and types only — nothing here touches a process.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GRACEFUL_EXIT_FAILURE_REASONS = exports.KEY_SEQUENCE_KEY_NAMES = void 0;
+exports.AGENT_MODE_NOTE_IDS = exports.AGENT_MODE_UNKNOWN = exports.AGENT_MODE_IDS = exports.GRACEFUL_EXIT_FAILURE_REASONS = exports.KEY_SEQUENCE_KEY_NAMES = void 0;
 exports.keyStep = keyStep;
 exports.literalStep = literalStep;
 exports.isLiteralStep = isLiteralStep;
 exports.isKeyStep = isKeyStep;
 exports.isKeySequenceKeyName = isKeySequenceKeyName;
+exports.isAgentModeId = isAgentModeId;
 // ---------------------------------------------------------------------------
 // Key sequences (受入条件 S9)
 // ---------------------------------------------------------------------------
@@ -73,3 +74,76 @@ function isKeySequenceKeyName(name) {
  *      worktree, silently. The number must not be reused until it goes quiet.
  */
 exports.GRACEFUL_EXIT_FAILURE_REASONS = ['graceful_exit_timeout', 'port_orphaned'];
+// ---------------------------------------------------------------------------
+// Permission / approval mode cycling (Issue #2592)
+// ---------------------------------------------------------------------------
+/**
+ * Every permission-mode name CommandMate can name, across every tool.
+ *
+ * A **union of measured vocabularies**, not a model of one tool's state machine.
+ * Six of the eight supported CLIs put a mode on `shift+tab`, and no two spell
+ * their modes the same way or cycle the same members — claude has four and no
+ * "default", codex has two, Command Code cycles three but can *sit* in two more
+ * that its cycle skips. So the ids here are the superset, and which of them a
+ * given tool can be in is that tool's own {@link AgentModeSpec.cycle}.
+ *
+ * Measured 2026-09-16 across all eight tools at the production 200x60 geometry
+ * (Issue #2592), plus the footer tables #1927 (claude 2.1.240) and #2250
+ * (Command Code 1.40.1 / 1.49.0) already carried:
+ *
+ * | id              | who prints it                    | spelling on the pane            |
+ * |-----------------|----------------------------------|---------------------------------|
+ * | `manual`        | claude                           | `⏸ manual mode on`              |
+ * | `auto`          | claude                           | `⏵⏵ auto mode on`               |
+ * | `accept-edits`  | claude / Command Code / agy      | `⏵⏵ accept edits on`, `» accept edits on`, `accept-edits ·` |
+ * | `plan`          | all five                         | `⏸ plan mode on`, `plan mode`, `Plan mode (shift+tab to cycle)`, `plan` |
+ * | `autopilot`     | copilot                          | `autopilot` in the hint bar     |
+ * | `bypass`        | Command Code (NOT in its cycle)  | `» permission bypass on`        |
+ * | `dont-ask`      | Command Code (NOT in its cycle)  | `» don't-ask on`                |
+ * | `default`       | Command Code                     | `? for shortcuts` (its own row) |
+ *
+ * `bypass` and `dont-ask` are declared even though `shift+tab` cannot REACH
+ * them, and that is the point: a user who put Command Code in one of those from
+ * the terminal is in a state the pane can be read for, and leaving them out
+ * would make the reader fall through to whichever indicator matched next — on
+ * 1.53.1, where `? for shortcuts` is drawn in every mode, that fall-through is
+ * a chip that says `default` while the agent bypasses permissions.
+ */
+exports.AGENT_MODE_IDS = [
+    'default',
+    'manual',
+    'accept-edits',
+    'plan',
+    'auto',
+    'autopilot',
+    'bypass',
+    'dont-ask',
+];
+/**
+ * The verdict for a frame nothing in {@link AgentModeSpec.indicators} matched.
+ *
+ * **Not a mode.** It is the reader declining to answer, and every consumer must
+ * treat it that way: the chip is not drawn, `capture --json` publishes the
+ * string rather than a guess, and nothing anywhere maps it to `default`.
+ *
+ * The distinction is load-bearing because four of the five tools draw NOTHING in
+ * their base mode (Issue #2592 §「設計に効く事実」3). If "no row" meant `default`
+ * then every frame captured mid-repaint, every frame whose footer scrolled out
+ * of the read window, and every future build that renames a row would publish a
+ * confident `default` for a pane that might be in `plan`. A missing chip is a
+ * question the operator can answer by looking at the terminal; a wrong chip is
+ * one they have no reason to ask.
+ */
+exports.AGENT_MODE_UNKNOWN = 'unknown';
+/** Whether `value` is a mode id (as opposed to {@link AGENT_MODE_UNKNOWN}). */
+function isAgentModeId(value) {
+    return exports.AGENT_MODE_IDS.includes(value);
+}
+/**
+ * A translator key for a caution the UI must print next to the mode button.
+ *
+ * A token rather than prose because the sentence is user-facing and has to be
+ * translated (`.eslintrc.json`'s i18n rule, Issue #1271), and because the tool
+ * declaring it has no way to call `useTranslations()`.
+ */
+exports.AGENT_MODE_NOTE_IDS = ['codexModelCoupled'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "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",