@robota-sdk/agent-command 3.0.0-beta.83 → 3.0.0-beta.85

package/src/mcp-activation/__tests__/mcp-activation-command.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
 import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
 
@@ -655,6 +655,230 @@ describe('/mcp login', () => {
   });
 });
 
+describe('/mcp reload (#3282 §4 part b-2)', () => {
+  function harness(
+    reload: ICommandMCPActivationAdapter['reload'],
+    taken: (names: string[]) => string[] = (names) => names,
+    approve: ICommandMCPActivationAdapter['approve'] = async () => summary(),
+  ) {
+    const added: IToolWithEventService[][] = [];
+    const reloadToolsAddedCalls: { token: string; added: readonly string[] }[] = [];
+    const port: ICommandMCPActivationAdapter = {
+      list: () => [],
+      approve,
+      reject: async () => summary({ status: 'rejected', allowed: false }),
+      revoke: async () => summary(),
+      reload,
+      reloadToolsAdded: (token, names) => reloadToolsAddedCalls.push({ token, added: names }),
+    };
+    const host = createTestCommandHost({
+      overrides: { getCommandHostAdapters: () => ({ mcpActivation: port }) },
+    });
+    const session = host.getSession();
+    host.getSession = () => ({
+      ...session,
+      addTools: async (tools) => {
+        added.push([...tools]);
+        return taken(tools.map((tool) => tool.schema.name));
+      },
+    });
+    return {
+      added,
+      reloadToolsAddedCalls,
+      run: (args: string) => executeMCPActivationCommand(host, args),
+    };
+  }
+
+  const forecast = new FunctionTool(
+    {
+      name: 'weather__forecast',
+      description: 'Forecast',
+      parameters: { type: 'object', properties: {} },
+    },
+    async () => 'sunny',
+  );
+
+  it('retries not-connected servers, adds the new tools to the session, and names what changed', async () => {
+    const h = harness(async () => ({
+      tools: [forecast],
+      connectedServerIds: ['weather'],
+      failedServerIds: ['flaky'],
+      reloadToken: 'token-1',
+    }));
+
+    const result = await h.run('reload');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('Connected: weather.');
+    expect(result.message).toContain('Still not connected: flaky');
+    expect(h.added).toEqual([[forecast]]);
+    expect(result.data).toEqual({
+      connectedServerIds: ['weather'],
+      failedServerIds: ['flaky'],
+      tools: ['weather__forecast'],
+    });
+  });
+
+  it('says plainly when nothing newly connected', async () => {
+    const h = harness(async () => ({ tools: [], connectedServerIds: [], failedServerIds: [] }));
+    const result = await h.run('reload');
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('No server newly connected.');
+  });
+
+  it('an approval connects the server in the running session', async () => {
+    const reload = vi.fn(async () => ({
+      tools: [forecast],
+      connectedServerIds: ['weather'],
+      failedServerIds: [],
+      reloadToken: 'token-1',
+    }));
+    const h = harness(reload, undefined, async () =>
+      summary({ serverId: 'weather', status: 'approved', allowed: true, reason: 'Approved.' }),
+    );
+
+    const result = await h.run('approve weather');
+
+    expect(reload).toHaveBeenCalledOnce();
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('is now approved');
+    expect(result.message).toContain('Connected: weather.');
+    expect(h.added).toEqual([[forecast]]);
+  });
+
+  it('acknowledges an empty-tool connection before approving another server', async () => {
+    let released = false;
+    const h = harness(
+      async () =>
+        released
+          ? {
+              tools: [forecast],
+              connectedServerIds: ['weather'],
+              failedServerIds: [],
+              reloadToken: 'second',
+            }
+          : { tools: [], connectedServerIds: ['empty'], failedServerIds: [], reloadToken: 'first' },
+      undefined,
+      async (id) => summary({ serverId: id, status: 'approved', allowed: true }),
+    );
+    await h.run('approve empty');
+    released = h.reloadToolsAddedCalls.some((call) => call.token === 'first');
+    const result = await h.run('approve weather');
+    expect(result.message).toContain('Connected: weather.');
+    expect(h.reloadToolsAddedCalls).toEqual([
+      { token: 'first', added: [] },
+      { token: 'second', added: ['weather__forecast'] },
+    ]);
+  });
+
+  it('preserves a saved approval when connecting fails, and suggests reload', async () => {
+    const h = harness(
+      async () => {
+        throw new Error('connection failed');
+      },
+      undefined,
+      async () => summary({ status: 'approved', allowed: true }),
+    );
+    const result = await h.run('approve weather');
+    expect(result.success).toBe(true);
+    expect(result.data).toMatchObject({ status: 'approved', allowed: true });
+    expect(result.message).toContain('connection failed');
+    expect(result.message).toContain('/mcp reload');
+  });
+
+  it('releases a staged reload even when adding tools throws', async () => {
+    const h = harness(
+      async () => ({
+        tools: [forecast],
+        connectedServerIds: ['weather'],
+        failedServerIds: [],
+        reloadToken: 'token-failed',
+      }),
+      () => {
+        throw new Error('cannot add tools');
+      },
+      async () => summary({ status: 'approved', allowed: true }),
+    );
+    const result = await h.run('approve weather');
+    expect(result.success).toBe(true);
+    expect(h.reloadToolsAddedCalls).toEqual([{ token: 'token-failed', added: [] }]);
+  });
+
+  it('a decision that is not an approval connects nothing', async () => {
+    const reload = vi.fn(async () => ({ tools: [], connectedServerIds: [], failedServerIds: [] }));
+    const h = harness(reload);
+
+    await h.run('reject weather');
+    await h.run('approve weather');
+
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it('is refused when the host offers no reload', async () => {
+    const h = harness(undefined);
+    const result = await h.run('reload');
+    expect(result.success).toBe(false);
+    expect(result.message).toBe('Reloading MCP servers is not available in this environment.');
+  });
+
+  it('tells the port which reloaded tools the session actually took, keyed to the reload it came from', async () => {
+    const h = harness(
+      async () => ({
+        tools: [forecast],
+        connectedServerIds: ['weather'],
+        failedServerIds: [],
+        reloadToken: 'token-1',
+      }),
+      (names) => names,
+    );
+
+    const result = await h.run('reload');
+
+    expect(result.success).toBe(true);
+    expect(h.reloadToolsAddedCalls).toEqual([{ token: 'token-1', added: ['weather__forecast'] }]);
+  });
+
+  it('tells the port when a reloaded tool collided and was dropped', async () => {
+    const h = harness(
+      async () => ({
+        tools: [forecast],
+        connectedServerIds: ['weather'],
+        failedServerIds: [],
+        reloadToken: 'token-1',
+      }),
+      () => [],
+    );
+
+    const result = await h.run('reload');
+
+    expect(result.success).toBe(true);
+    expect(h.reloadToolsAddedCalls).toEqual([{ token: 'token-1', added: [] }]);
+  });
+
+  it('never calls it when the reload has no token to acknowledge (nothing staged)', async () => {
+    // A defensive case: a host that returned tools without a token (should not happen in practice,
+    // since the composition only omits one when there is nothing to stage) must not be acknowledged
+    // — there would be nothing for the token to correlate to.
+    const h = harness(async () => ({
+      tools: [forecast],
+      connectedServerIds: ['weather'],
+      failedServerIds: [],
+    }));
+
+    await h.run('reload');
+
+    expect(h.reloadToolsAddedCalls).toEqual([]);
+  });
+
+  it('never calls it when nothing newly connected', async () => {
+    const h = harness(async () => ({ tools: [], connectedServerIds: [], failedServerIds: [] }));
+
+    await h.run('reload');
+
+    expect(h.reloadToolsAddedCalls).toEqual([]);
+  });
+});
+
 describe('/mcp command entry', () => {
   it('opens only `status` to the model, and describes login for the user', () => {
     const entry = createMCPActivationCommandEntry();

package/src/mcp-activation/mcp-activation-command-module.ts

@@ -35,6 +35,12 @@ export function createMCPActivationCommandEntry(): ICommand {
         source: 'mcp-activation',
         modelInvocable: true,
       },
+      {
+        name: 'reload',
+        description: 'Retry connecting every MCP server that is not currently connected',
+        source: 'mcp-activation',
+        modelInvocable: false,
+      },
       ...(['approve', 'reject', 'revoke', 'login', 'logout'] as const).map((verb) => ({
         name: verb,
         description: USER_ONLY_VERB_DESCRIPTION[verb],

package/src/mcp-activation/mcp-activation-command.ts

@@ -54,7 +54,7 @@ function revocationText(result: ICommandMCPOAuthLogoutResult): string {
 }
 
 const USAGE =
-  'Usage: /mcp [status] | /mcp <approve|reject|revoke|logout> <serverId> | /mcp login <serverId> [--no-browser]';
+  'Usage: /mcp [status] | /mcp <approve|reject|revoke|logout> <serverId> | /mcp login <serverId> [--no-browser] | /mcp reload';
 const LOGIN_USAGE = 'Usage: /mcp login <serverId> [--no-browser]';
 
 /**
@@ -147,6 +147,7 @@ async function listResult(mcp: ICommandMCPActivationAdapter | undefined): Promis
     data: {
       servers: entries.map((entry) => ({
         serverId: entry.serverId,
+        ...(entry.displayName === undefined ? {} : { displayName: entry.displayName }),
         source: entry.source,
         status: entry.status,
         allowed: entry.allowed,
@@ -154,6 +155,12 @@ async function listResult(mcp: ICommandMCPActivationAdapter | undefined): Promis
         definitionFingerprint: entry.definitionFingerprint,
         securityIdentity: entry.securityIdentity,
         ...(oauth.has(entry.serverId) ? { oauth: oauth.get(entry.serverId) } : {}),
+        // #3282 §4 part b-2: the Settings screen's MCP Servers section.
+        ...(entry.connection === undefined ? {} : { connection: entry.connection }),
+        ...(entry.connectionFailureReason === undefined
+          ? {}
+          : { connectionFailureReason: entry.connectionFailureReason }),
+        ...(entry.toolNames === undefined ? {} : { toolNames: entry.toolNames }),
       })),
       sourceProblems,
     },
@@ -183,6 +190,7 @@ export async function executeMCPActivationCommand(
       : mcpModelStatusResult(adapter(context));
   }
   if (verb === 'login') return loginResult(context, serverId);
+  if (verb === 'reload') return reloadResult(context);
 
   if (verb !== 'approve' && verb !== 'reject' && verb !== 'revoke' && verb !== 'logout') {
     return { message: `Unknown argument. ${USAGE}`, success: false };
@@ -205,7 +213,7 @@ export async function executeMCPActivationCommand(
 
   try {
     const result = await mcp[verb](serverId);
-    return {
+    const decided = {
       message: `MCP server ${serverId} is now ${result.status}. ${result.reason}`,
       success:
         result.status === 'approved' || result.status === 'rejected' || result.status === 'revoked',
@@ -219,6 +227,24 @@ export async function executeMCPActivationCommand(
         securityIdentity: result.securityIdentity,
       },
     };
+    // An approval takes effect now: the session connects the server as `/mcp reload` would.
+    if (verb !== 'approve' || result.status !== 'approved' || mcp.reload === undefined) {
+      return decided;
+    }
+    try {
+      const reloaded = await reloadResult(context);
+      return {
+        ...decided,
+        message: `${decided.message} ${reloaded.message}`,
+        data: { ...decided.data, reload: reloaded.data ?? {} },
+      };
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      return {
+        ...decided,
+        message: `${decided.message} Could not connect now: ${reason}. Run /mcp reload to retry.`,
+      };
+    }
   } catch (error) {
     return {
       message: error instanceof Error ? error.message : String(error),
@@ -250,6 +276,55 @@ async function logoutResult(
   };
 }
 
+/**
+ * #3282 §4 part b-2: `/mcp reload` and the Settings screen's "Reload servers" button — retries
+ * every server not currently connected and adds whatever tools it now offers to the live session,
+ * the same way a completed sign-in does.
+ */
+async function reloadResult(context: TMCPActivationCommandContext): Promise<ICommandResult> {
+  const mcp = adapter(context);
+  if (!mcp) {
+    return {
+      message: 'MCP activation management is not available in this environment.',
+      success: true,
+    };
+  }
+  if (mcp.reload === undefined) {
+    return {
+      message: 'Reloading MCP servers is not available in this environment.',
+      success: false,
+    };
+  }
+  const result = await mcp.reload();
+  let added: readonly string[] = [];
+  try {
+    added = result.tools.length === 0 ? [] : await context.getSession().addTools(result.tools);
+  } finally {
+    if (result.reloadToken !== undefined) mcp.reloadToolsAdded?.(result.reloadToken, added);
+  }
+  const dropped = result.tools.length - added.length;
+  const parts = [
+    result.connectedServerIds.length === 0
+      ? 'No server newly connected.'
+      : `Connected: ${result.connectedServerIds.join(', ')}.`,
+    result.failedServerIds.length === 0
+      ? undefined
+      : `Still not connected: ${result.failedServerIds.join(', ')} (see /mcp status).`,
+    dropped === 0
+      ? undefined
+      : `${dropped} of the new tools ${dropped === 1 ? 'was' : 'were'} left out: the session already has a tool by that name.`,
+  ].filter((part): part is string => part !== undefined);
+  return {
+    message: `Reloaded MCP servers. ${parts.join(' ')}`.trim(),
+    success: true,
+    data: {
+      connectedServerIds: result.connectedServerIds,
+      failedServerIds: result.failedServerIds,
+      tools: [...added],
+    },
+  };
+}
+
 let loginPrompts = 0;
 
 /** Before the browser opens: the URL it will show, and the choice to paste or cancel instead. */

package/src/memory/__tests__/memory-command-module.test.ts

@@ -101,10 +101,15 @@ function createMockRuntimeSession() {
   };
 }
 
-async function createInteractiveSession(cwd = makeProject()): Promise<InteractiveSession> {
+async function createInteractiveSession(
+  cwd = makeProject(),
+  permissionMode: 'default' | 'plan' = 'default',
+): Promise<InteractiveSession> {
+  const runtime = createMockRuntimeSession();
+  runtime.getPermissionMode.mockReturnValue(permissionMode);
   return new InteractiveSession({
     cwd,
-    session: createMockRuntimeSession() as never,
+    session: runtime as never,
     memoryStore: await createMemoryStore(cwd),
     commandModules: [createMemoryCommandModule()],
   });
@@ -362,4 +367,37 @@ describe('executeMemoryCommand', () => {
     expect(unknownResult.success).toBe(false);
     expect(existsSync(join(cwd, '.robota', 'memory', 'MEMORY.md'))).toBe(false);
   });
+
+  describe('in plan mode', () => {
+    it('refuses a memory the model asks to save, and writes nothing', async () => {
+      const cwd = makeProject();
+      const session = await createInteractiveSession(cwd, 'plan');
+
+      const result = await session.executeModelCommand('memory', 'add project build Use pnpm.');
+
+      expect(result?.success).toBe(false);
+      expect(result?.message).toContain('Plan mode saves no memory');
+      expect(existsSync(join(cwd, '.robota', 'memory', 'MEMORY.md'))).toBe(false);
+    });
+
+    // ARCH-047: project mutation is Linux-only (stable root-anchored host); refused elsewhere.
+    it.runIf(process.platform === 'linux')(
+      'still saves a memory the user adds by hand',
+      async () => {
+        const cwd = makeProject();
+        const session = await createInteractiveSession(cwd, 'plan');
+
+        const result = await session.executeCommand('memory', 'add project build Use pnpm.');
+
+        expect(result?.success).toBe(true);
+        expect(existsSync(join(cwd, '.robota', 'memory', 'MEMORY.md'))).toBe(true);
+      },
+    );
+
+    it('lets the model read memory', async () => {
+      const session = await createInteractiveSession(makeProject(), 'plan');
+      const result = await session.executeModelCommand('memory', 'list');
+      expect(result?.success).toBe(true);
+    });
+  });
 });

package/src/memory/__tests__/memory-command-unavailable.test.ts

@@ -0,0 +1,63 @@
+/**
+ * #3282 §4c review finding: `/memory` in a served (GUI) session throws instead of answering, because
+ * `executeMemoryCommand` never caught what `context.getMemoryStore()` throws when the host composed no
+ * memory store (off by default, or unavailable on this host — `WorkspaceAuthorityRequiredError`). The
+ * uncaught rejection reaches the transport's `command` handler
+ * (`session-message-handler.ts`'s `.then(_, error => deliver({ type: 'protocol_error', ... }))`), which
+ * the GUI renders as a `protocol_error` toast — the "red toast" the audit found — instead of the same
+ * plain `command_result` every other unavailable-command case gets (mirrors `rewind-command.ts`'s
+ * `formatError`, which already catches `EditCheckpointsUnavailableError` the same way).
+ */
+import { describe, expect, it } from 'vitest';
+
+import { WorkspaceAuthorityRequiredError } from '@robota-sdk/agent-framework';
+
+import { executeMemoryCommand } from '../memory-command.js';
+
+import type { ICommandHostMemory, ICommandHostWorkspace } from '@robota-sdk/agent-framework';
+
+function contextWithUnavailableMemory(): ICommandHostMemory & ICommandHostWorkspace {
+  return {
+    getUsedMemoryReferences: () => [],
+    recordMemoryEvent: () => {},
+    getMemoryStore: () => {
+      throw new WorkspaceAuthorityRequiredError("Project memory isn't available for this folder.");
+    },
+    getCwd: () => '/workspace',
+    getCommandInvocationSource: () => 'user',
+  };
+}
+
+describe('executeMemoryCommand — unavailable memory store', () => {
+  it('answers list with a plain failure instead of rejecting', async () => {
+    const result = await executeMemoryCommand(contextWithUnavailableMemory(), 'list');
+    expect(result.success).toBe(false);
+    expect(result.message).toBe("Project memory isn't available for this folder.");
+  });
+
+  it('answers show, pending, used and add the same way — never a throw', async () => {
+    const context = contextWithUnavailableMemory();
+    for (const args of ['show', 'pending', 'used', 'add project topic some durable fact']) {
+      await expect(executeMemoryCommand(context, args)).resolves.toMatchObject({
+        success: false,
+        message: "Project memory isn't available for this folder.",
+      });
+    }
+  });
+
+  it('still lets an ordinary Error through as a plain failure, not a throw', async () => {
+    const context: ICommandHostMemory & ICommandHostWorkspace = {
+      getUsedMemoryReferences: () => [],
+      recordMemoryEvent: () => {},
+      getMemoryStore: () => {
+        throw new Error('unexpected store failure');
+      },
+      getCwd: () => '/workspace',
+      getCommandInvocationSource: () => 'user',
+    };
+    await expect(executeMemoryCommand(context, 'list')).resolves.toEqual({
+      success: false,
+      message: 'unexpected store failure',
+    });
+  });
+});

package/src/memory/memory-command-module.ts

@@ -12,7 +12,8 @@ import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-comma
 /**
  * Model-invocable: remembering and recalling project conventions is the model's own work. The
  * subcommand flags (in `buildMemoryCommandSubcommands`) keep `approve`/`reject` user-only, because
- * pending candidates exist so the user reviews what the model proposed to remember.
+ * pending candidates exist so the user reviews what the model proposed to remember, and the command
+ * refuses the model's `add` in plan mode, which writes nothing.
  */
 const MEMORY_COMMAND_MODEL_DESCRIPTION =
   'Read and write this project’s durable memory. Use `list` or `show [topic]` to look up stored ' +
@@ -20,7 +21,8 @@ const MEMORY_COMMAND_MODEL_DESCRIPTION =
   'to save a durable preference, project convention, feedback item or reference worth reusing ' +
   'across sessions (never secrets, credentials or transient facts); `pending` to see candidates ' +
   'awaiting the user’s review; `used` to report which memory items informed this turn. Bare lists ' +
-  'topics. Returns the requested topics or entries, or a confirmation of what was saved. Approving ' +
+  'topics. In plan mode `add` is refused: save after plan mode ends. Returns the requested topics ' +
+  'or entries, or a confirmation of what was saved. Approving ' +
   'or rejecting a pending candidate is the user’s review: suggest `/memory approve <id>` or ' +
   '`/memory reject <id>`.';
 

package/src/memory/memory-command.ts

@@ -10,7 +10,9 @@ import {
 
 import type {
   IAppendMemoryInput,
+  ICommandHostAdapterAccess,
   ICommandHostMemory,
+  ICommandHostSessionAccess,
   ICommandHostWorkspace,
   IMemoryStore,
 } from '@robota-sdk/agent-framework';
@@ -36,6 +38,24 @@ function formatError(error: Error | string): ICommandResult {
   };
 }
 
+/**
+ * `context.getMemoryStore()` throws `WorkspaceAuthorityRequiredError` when the host composed no
+ * memory store — off by default, or unavailable on this host (mirrors `EditCheckpointsUnavailableError`
+ * for `/rewind`, `rewind-command.ts`'s `formatError`). Uncaught, that throw reaches the GUI as a raw
+ * `protocol_error` (a red toast) instead of the SAME plain `command_result` every other unavailable-
+ * command case gets — this is the one call in the command that can throw before any subcommand branch
+ * runs, so it is guarded once, here, rather than in each branch below.
+ */
+function getMemoryStoreOrError(
+  context: ICommandHostMemory,
+): { ok: true; store: IMemoryStore } | { ok: false; result: ICommandResult } {
+  try {
+    return { ok: true, store: createCommandMemoryStores(context) };
+  } catch (error) {
+    return { ok: false, result: formatError(error instanceof Error ? error : String(error)) };
+  }
+}
+
 async function formatList(store: IMemoryStore): Promise<ICommandResult> {
   const summary = await store.list();
   const topics =
@@ -190,15 +210,27 @@ function formatUsed(context: ICommandHostMemory): ICommandResult {
   };
 }
 
+/** The host's view of the session's permission mode, when it has one. */
+type TMemoryCommandModeAccess = ICommandHostAdapterAccess &
+  Partial<Pick<ICommandHostSessionAccess, 'getSession'>>;
+
+function isPlanMode(context: TMemoryCommandModeAccess): boolean {
+  const adapter = context.getCommandHostAdapters?.().permissionMode;
+  const mode = adapter?.getPermissionMode() ?? context.getSession?.().getPermissionMode();
+  return mode === 'plan';
+}
+
 export async function executeMemoryCommand(
-  context: ICommandHostMemory & ICommandHostWorkspace,
+  context: ICommandHostMemory & ICommandHostWorkspace & TMemoryCommandModeAccess,
   rawArgs: string,
 ): Promise<ICommandResult> {
   const args = rawArgs.trim().split(/\s+/).filter(Boolean);
   const subcommand = args[SUBCOMMAND_INDEX] ?? 'list';
   // SELFHOST-008 P1R: the single injected durable-memory port (or fs default) — authoritative for all
   // `/memory` operations, so a surface that swaps the store is honored here too (no split-brain).
-  const store = createCommandMemoryStores(context);
+  const resolved = getMemoryStoreOrError(context);
+  if (!resolved.ok) return resolved.result;
+  const store = resolved.store;
 
   if (subcommand === 'list') return formatList(store);
   if (subcommand === 'show') return formatShow(store, args[TYPE_INDEX]);
@@ -207,6 +239,14 @@ export async function executeMemoryCommand(
   if (subcommand === 'reject') return rejectPending(context, store, args[TYPE_INDEX]);
   if (subcommand === 'used') return formatUsed(context);
   if (subcommand === 'add') {
+    // Plan mode changes nothing, and saved memory is read back into every later session. The user
+    // can still save by hand; the model waits until plan mode ends.
+    if (context.getCommandInvocationSource() === 'model' && isPlanMode(context)) {
+      return {
+        message: 'Plan mode saves no memory. Save it after plan mode ends.',
+        success: false,
+      };
+    }
     const input = parseAdd(args);
     if (!input) return usage();
     if (hasSensitiveCommandMemoryContent(input.text)) {

package/src/mode/__tests__/mode-command-module.test.ts

@@ -97,6 +97,15 @@ describe('createModeCommandModule', () => {
       'bypassPermissions',
       'auto',
     ]);
+    // #3282 §2: a plain label beside every description, so a client never shows the raw id.
+    expect(entry?.subcommands?.map((subcommand) => subcommand.displayName)).toEqual([
+      'Plan only',
+      'Ask first',
+      'Accept edits',
+      'Skip all checks',
+      'Auto',
+    ]);
+    expect(entry?.subcommands?.every((subcommand) => subcommand.description.length > 0)).toBe(true);
     expect(command).toEqual(
       expect.objectContaining({
         name: 'mode',
@@ -150,6 +159,37 @@ describe('createModeCommandModule', () => {
     expect(context.setPermissionMode).not.toHaveBeenCalled();
   });
 
+  it('#3282 §2: the picker shows plain labels with their descriptions, never a raw id', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModeCommandModule().systemCommands ?? []),
+    ]);
+    const context = createCommandHostContext();
+    const ask = vi.fn().mockResolvedValue({ type: 'answer', values: ['plan'] });
+    const contextWithAsk = createTestCommandHost({
+      overrides: { ...context, getUserInteraction: () => ({ ask }) },
+    });
+
+    await executor.execute('mode', contextWithAsk, '');
+
+    expect(ask).toHaveBeenCalledTimes(1);
+    const request = ask.mock.calls[0]![0];
+    expect(request.options).toEqual([
+      { value: 'plan', label: 'Plan only', description: 'Plan only, no execution' },
+      { value: 'default', label: 'Ask first', description: 'Ask before risky actions' },
+      { value: 'acceptEdits', label: 'Accept edits', description: 'Auto-approve file edits' },
+      {
+        value: 'bypassPermissions',
+        label: 'Skip all checks',
+        description: 'Skip all permission checks',
+      },
+      {
+        value: 'auto',
+        label: 'Auto',
+        description: 'A model classifier approves or blocks risky actions',
+      },
+    ]);
+  });
+
   it('asks the user to pick a mode when no arg is given and a renderer is attached (CMD-004)', async () => {
     const executor = new SystemCommandExecutor([
       ...(createModeCommandModule().systemCommands ?? []),

package/src/mode/mode-command.ts

@@ -28,7 +28,7 @@ async function resolveModeViaAsk(
   if (!ui) return undefined;
   const options = buildPermissionModeSubcommands().map((sub) => ({
     value: sub.name,
-    label: sub.name,
+    label: sub.displayName ?? sub.name,
     description: sub.description,
   }));
   const response = await ui.ask(selectAction('mode', 'Select interaction mode', options));