feat: Implement Plan Mode for Safe Code Planning (#658)

packages/cli/src/ui/commands/approvalModeCommand.test.ts

@@ -0,0 +1,495 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { approvalModeCommand } from './approvalModeCommand.js';
+import {
+  type CommandContext,
+  CommandKind,
+  type MessageActionReturn,
+} from './types.js';
+import { createMockCommandContext } from '../../test-utils/mockCommandContext.js';
+import { ApprovalMode } from '@qwen-code/qwen-code-core';
+import { SettingScope, type LoadedSettings } from '../../config/settings.js';
+
+describe('approvalModeCommand', () => {
+  let mockContext: CommandContext;
+  let setApprovalModeMock: ReturnType<typeof vi.fn>;
+  let setSettingsValueMock: ReturnType<typeof vi.fn>;
+  const originalEnv = { ...process.env };
+  const userSettingsPath = '/mock/user/settings.json';
+  const projectSettingsPath = '/mock/project/settings.json';
+  const userSettingsFile = { path: userSettingsPath, settings: {} };
+  const projectSettingsFile = { path: projectSettingsPath, settings: {} };
+
+  const getModeSubCommand = (mode: ApprovalMode) =>
+    approvalModeCommand.subCommands?.find((cmd) => cmd.name === mode);
+
+  const getScopeSubCommand = (
+    mode: ApprovalMode,
+    scope: '--session' | '--user' | '--project',
+  ) => getModeSubCommand(mode)?.subCommands?.find((cmd) => cmd.name === scope);
+
+  beforeEach(() => {
+    setApprovalModeMock = vi.fn();
+    setSettingsValueMock = vi.fn();
+
+    mockContext = createMockCommandContext({
+      services: {
+        config: {
+          getApprovalMode: vi.fn().mockReturnValue(ApprovalMode.DEFAULT),
+          setApprovalMode: setApprovalModeMock,
+        },
+        settings: {
+          merged: {},
+          setValue: setSettingsValueMock,
+          forScope: vi
+            .fn()
+            .mockImplementation((scope: SettingScope) =>
+              scope === SettingScope.User
+                ? userSettingsFile
+                : scope === SettingScope.Workspace
+                  ? projectSettingsFile
+                  : { path: '', settings: {} },
+            ),
+        } as unknown as LoadedSettings,
+      },
+    } as unknown as CommandContext);
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+    vi.clearAllMocks();
+  });
+
+  it('should have the correct command properties', () => {
+    expect(approvalModeCommand.name).toBe('approval-mode');
+    expect(approvalModeCommand.kind).toBe(CommandKind.BUILT_IN);
+    expect(approvalModeCommand.description).toBe(
+      'View or change the approval mode for tool usage',
+    );
+  });
+
+  it('should show current mode, options, and usage when no arguments provided', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      '',
+    )) as MessageActionReturn;
+
+    expect(result.type).toBe('message');
+    expect(result.messageType).toBe('info');
+    const expectedMessage = [
+      'Current approval mode: default',
+      '',
+      'Available approval modes:',
+      '  - plan: Plan mode - Analyze only, do not modify files or execute commands',
+      '  - default: Default mode - Require approval for file edits or shell commands',
+      '  - auto-edit: Auto-edit mode - Automatically approve file edits',
+      '  - yolo: YOLO mode - Automatically approve all tools',
+      '',
+      'Usage: /approval-mode <mode> [--session|--user|--project]',
+    ].join('\n');
+    expect(result.content).toBe(expectedMessage);
+  });
+
+  it('should display error when config is not available', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const nullConfigContext = createMockCommandContext({
+      services: {
+        config: null,
+      },
+    } as unknown as CommandContext);
+
+    const result = (await approvalModeCommand.action(
+      nullConfigContext,
+      '',
+    )) as MessageActionReturn;
+
+    expect(result.type).toBe('message');
+    expect(result.messageType).toBe('error');
+    expect(result.content).toBe('Configuration not available.');
+  });
+
+  it('should change approval mode when valid mode is provided', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      'plan',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.PLAN);
+    expect(setSettingsValueMock).not.toHaveBeenCalled();
+    expect(result.type).toBe('message');
+    expect(result.messageType).toBe('info');
+    expect(result.content).toBe('Approval mode changed to: plan');
+  });
+
+  it('should accept canonical auto-edit mode value', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      'auto-edit',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.AUTO_EDIT);
+    expect(setSettingsValueMock).not.toHaveBeenCalled();
+    expect(result.type).toBe('message');
+    expect(result.messageType).toBe('info');
+    expect(result.content).toBe('Approval mode changed to: auto-edit');
+  });
+
+  it('should accept auto-edit alias for compatibility', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      'auto-edit',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.AUTO_EDIT);
+    expect(setSettingsValueMock).not.toHaveBeenCalled();
+    expect(result.content).toBe('Approval mode changed to: auto-edit');
+  });
+
+  it('should display error when invalid mode is provided', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      'invalid',
+    )) as MessageActionReturn;
+
+    expect(result.type).toBe('message');
+    expect(result.messageType).toBe('error');
+    expect(result.content).toContain('Invalid approval mode: invalid');
+    expect(result.content).toContain('Available approval modes:');
+    expect(result.content).toContain(
+      'Usage: /approval-mode <mode> [--session|--user|--project]',
+    );
+  });
+
+  it('should display error when setApprovalMode throws an error', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const errorMessage = 'Failed to set approval mode';
+    mockContext.services.config!.setApprovalMode = vi
+      .fn()
+      .mockImplementation(() => {
+        throw new Error(errorMessage);
+      });
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      'plan',
+    )) as MessageActionReturn;
+
+    expect(result.type).toBe('message');
+    expect(result.messageType).toBe('error');
+    expect(result.content).toBe(
+      `Failed to change approval mode: ${errorMessage}`,
+    );
+  });
+
+  it('should allow selecting auto-edit with user scope via nested subcommands', async () => {
+    if (!approvalModeCommand.subCommands) {
+      throw new Error('approvalModeCommand must have subCommands.');
+    }
+
+    const userSubCommand = getScopeSubCommand(ApprovalMode.AUTO_EDIT, '--user');
+    if (!userSubCommand?.action) {
+      throw new Error('--user scope subcommand must have an action.');
+    }
+
+    const result = (await userSubCommand.action(
+      mockContext,
+      '',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.AUTO_EDIT);
+    expect(setSettingsValueMock).toHaveBeenCalledWith(
+      SettingScope.User,
+      'approvalMode',
+      'auto-edit',
+    );
+    expect(result.content).toBe(
+      `Approval mode changed to: auto-edit (saved to user settings at ${userSettingsPath})`,
+    );
+  });
+
+  it('should allow selecting plan with project scope via nested subcommands', async () => {
+    if (!approvalModeCommand.subCommands) {
+      throw new Error('approvalModeCommand must have subCommands.');
+    }
+
+    const projectSubCommand = getScopeSubCommand(
+      ApprovalMode.PLAN,
+      '--project',
+    );
+    if (!projectSubCommand?.action) {
+      throw new Error('--project scope subcommand must have an action.');
+    }
+
+    const result = (await projectSubCommand.action(
+      mockContext,
+      '',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.PLAN);
+    expect(setSettingsValueMock).toHaveBeenCalledWith(
+      SettingScope.Workspace,
+      'approvalMode',
+      'plan',
+    );
+    expect(result.content).toBe(
+      `Approval mode changed to: plan (saved to project settings at ${projectSettingsPath})`,
+    );
+  });
+
+  it('should allow selecting plan with session scope via nested subcommands', async () => {
+    if (!approvalModeCommand.subCommands) {
+      throw new Error('approvalModeCommand must have subCommands.');
+    }
+
+    const sessionSubCommand = getScopeSubCommand(
+      ApprovalMode.PLAN,
+      '--session',
+    );
+    if (!sessionSubCommand?.action) {
+      throw new Error('--session scope subcommand must have an action.');
+    }
+
+    const result = (await sessionSubCommand.action(
+      mockContext,
+      '',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.PLAN);
+    expect(setSettingsValueMock).not.toHaveBeenCalled();
+    expect(result.content).toBe('Approval mode changed to: plan');
+  });
+
+  it('should allow providing a scope argument after selecting a mode subcommand', async () => {
+    if (!approvalModeCommand.subCommands) {
+      throw new Error('approvalModeCommand must have subCommands.');
+    }
+
+    const planSubCommand = getModeSubCommand(ApprovalMode.PLAN);
+    if (!planSubCommand?.action) {
+      throw new Error('plan subcommand must have an action.');
+    }
+
+    const result = (await planSubCommand.action(
+      mockContext,
+      '--user',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.PLAN);
+    expect(setSettingsValueMock).toHaveBeenCalledWith(
+      SettingScope.User,
+      'approvalMode',
+      'plan',
+    );
+    expect(result.content).toBe(
+      `Approval mode changed to: plan (saved to user settings at ${userSettingsPath})`,
+    );
+  });
+
+  it('should support --user plan pattern (scope first)', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      '--user plan',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.PLAN);
+    expect(setSettingsValueMock).toHaveBeenCalledWith(
+      SettingScope.User,
+      'approvalMode',
+      'plan',
+    );
+    expect(result.content).toBe(
+      `Approval mode changed to: plan (saved to user settings at ${userSettingsPath})`,
+    );
+  });
+
+  it('should support plan --user pattern (mode first)', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      'plan --user',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.PLAN);
+    expect(setSettingsValueMock).toHaveBeenCalledWith(
+      SettingScope.User,
+      'approvalMode',
+      'plan',
+    );
+    expect(result.content).toBe(
+      `Approval mode changed to: plan (saved to user settings at ${userSettingsPath})`,
+    );
+  });
+
+  it('should support --project auto-edit pattern', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      '--project auto-edit',
+    )) as MessageActionReturn;
+
+    expect(setApprovalModeMock).toHaveBeenCalledWith(ApprovalMode.AUTO_EDIT);
+    expect(setSettingsValueMock).toHaveBeenCalledWith(
+      SettingScope.Workspace,
+      'approvalMode',
+      'auto-edit',
+    );
+    expect(result.content).toBe(
+      `Approval mode changed to: auto-edit (saved to project settings at ${projectSettingsPath})`,
+    );
+  });
+
+  it('should display error when only scope flag is provided', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      '--user',
+    )) as MessageActionReturn;
+
+    expect(result.type).toBe('message');
+    expect(result.messageType).toBe('error');
+    expect(result.content).toContain('Missing approval mode');
+    expect(setApprovalModeMock).not.toHaveBeenCalled();
+    expect(setSettingsValueMock).not.toHaveBeenCalled();
+  });
+
+  it('should display error when multiple scope flags are provided', async () => {
+    if (!approvalModeCommand.action) {
+      throw new Error('approvalModeCommand must have an action.');
+    }
+
+    const result = (await approvalModeCommand.action(
+      mockContext,
+      '--user --project plan',
+    )) as MessageActionReturn;
+
+    expect(result.type).toBe('message');
+    expect(result.messageType).toBe('error');
+    expect(result.content).toContain('Multiple scope flags provided');
+    expect(setApprovalModeMock).not.toHaveBeenCalled();
+    expect(setSettingsValueMock).not.toHaveBeenCalled();
+  });
+
+  it('should surface a helpful error when scope subcommands receive extra arguments', async () => {
+    if (!approvalModeCommand.subCommands) {
+      throw new Error('approvalModeCommand must have subCommands.');
+    }
+
+    const userSubCommand = getScopeSubCommand(ApprovalMode.DEFAULT, '--user');
+    if (!userSubCommand?.action) {
+      throw new Error('--user scope subcommand must have an action.');
+    }
+
+    const result = (await userSubCommand.action(
+      mockContext,
+      'extra',
+    )) as MessageActionReturn;
+
+    expect(result.type).toBe('message');
+    expect(result.messageType).toBe('error');
+    expect(result.content).toBe(
+      'Scope subcommands do not accept additional arguments.',
+    );
+    expect(setApprovalModeMock).not.toHaveBeenCalled();
+    expect(setSettingsValueMock).not.toHaveBeenCalled();
+  });
+
+  it('should provide completion for approval modes', async () => {
+    if (!approvalModeCommand.completion) {
+      throw new Error('approvalModeCommand must have a completion function.');
+    }
+
+    // Test partial mode completion
+    const result = await approvalModeCommand.completion(mockContext, 'p');
+    expect(result).toEqual(['plan']);
+
+    const result2 = await approvalModeCommand.completion(mockContext, 'a');
+    expect(result2).toEqual(['auto-edit']);
+
+    // Test empty completion - should suggest available modes first
+    const result3 = await approvalModeCommand.completion(mockContext, '');
+    expect(result3).toEqual(['plan', 'default', 'auto-edit', 'yolo']);
+
+    const result4 = await approvalModeCommand.completion(mockContext, 'AUTO');
+    expect(result4).toEqual(['auto-edit']);
+
+    // Test mode first pattern: 'plan ' should suggest scope flags
+    const result5 = await approvalModeCommand.completion(mockContext, 'plan ');
+    expect(result5).toEqual(['--session', '--project', '--user']);
+
+    const result6 = await approvalModeCommand.completion(
+      mockContext,
+      'plan --u',
+    );
+    expect(result6).toEqual(['--user']);
+
+    // Test scope first pattern: '--user ' should suggest modes
+    const result7 = await approvalModeCommand.completion(
+      mockContext,
+      '--user ',
+    );
+    expect(result7).toEqual(['plan', 'default', 'auto-edit', 'yolo']);
+
+    const result8 = await approvalModeCommand.completion(
+      mockContext,
+      '--user p',
+    );
+    expect(result8).toEqual(['plan']);
+
+    // Test completed patterns should return empty
+    const result9 = await approvalModeCommand.completion(
+      mockContext,
+      'plan --user ',
+    );
+    expect(result9).toEqual([]);
+
+    const result10 = await approvalModeCommand.completion(
+      mockContext,
+      '--user plan ',
+    );
+    expect(result10).toEqual([]);
+  });
+});

packages/cli/src/ui/commands/approvalModeCommand.ts

@@ -0,0 +1,434 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  SlashCommand,
+  CommandContext,
+  MessageActionReturn,
+} from './types.js';
+import { CommandKind } from './types.js';
+import { ApprovalMode, APPROVAL_MODES } from '@qwen-code/qwen-code-core';
+import { SettingScope } from '../../config/settings.js';
+
+const USAGE_MESSAGE =
+  'Usage: /approval-mode <mode> [--session|--user|--project]';
+
+const normalizeInputMode = (value: string): string =>
+  value.trim().toLowerCase();
+
+const tokenizeArgs = (args: string): string[] => {
+  const matches = args.match(/(?:"[^"]*"|'[^']*'|[^\s"']+)/g);
+  if (!matches) {
+    return [];
+  }
+
+  return matches.map((token) => {
+    if (
+      (token.startsWith('"') && token.endsWith('"')) ||
+      (token.startsWith("'") && token.endsWith("'"))
+    ) {
+      return token.slice(1, -1);
+    }
+    return token;
+  });
+};
+
+const parseApprovalMode = (value: string | null): ApprovalMode | null => {
+  if (!value) {
+    return null;
+  }
+
+  const normalized = normalizeInputMode(value).replace(/_/g, '-');
+  const matchIndex = APPROVAL_MODES.findIndex(
+    (candidate) => candidate === normalized,
+  );
+
+  return matchIndex === -1 ? null : APPROVAL_MODES[matchIndex];
+};
+
+const formatModeDescription = (mode: ApprovalMode): string => {
+  switch (mode) {
+    case ApprovalMode.PLAN:
+      return 'Plan mode - Analyze only, do not modify files or execute commands';
+    case ApprovalMode.DEFAULT:
+      return 'Default mode - Require approval for file edits or shell commands';
+    case ApprovalMode.AUTO_EDIT:
+      return 'Auto-edit mode - Automatically approve file edits';
+    case ApprovalMode.YOLO:
+      return 'YOLO mode - Automatically approve all tools';
+    default:
+      return `${mode} mode`;
+  }
+};
+
+const parseApprovalArgs = (
+  args: string,
+): {
+  mode: string | null;
+  scope: 'session' | 'user' | 'project';
+  error?: string;
+} => {
+  const trimmedArgs = args.trim();
+  if (!trimmedArgs) {
+    return { mode: null, scope: 'session' };
+  }
+
+  const tokens = tokenizeArgs(trimmedArgs);
+  let mode: string | null = null;
+  let scope: 'session' | 'user' | 'project' = 'session';
+  let scopeFlag: string | null = null;
+
+  // Find scope flag and mode
+  for (const token of tokens) {
+    if (token === '--session' || token === '--user' || token === '--project') {
+      if (scopeFlag) {
+        return {
+          mode: null,
+          scope: 'session',
+          error: 'Multiple scope flags provided',
+        };
+      }
+      scopeFlag = token;
+      scope = token.substring(2) as 'session' | 'user' | 'project';
+    } else if (!mode) {
+      mode = token;
+    } else {
+      return {
+        mode: null,
+        scope: 'session',
+        error: 'Invalid arguments provided',
+      };
+    }
+  }
+
+  if (!mode) {
+    return { mode: null, scope: 'session', error: 'Missing approval mode' };
+  }
+
+  return { mode, scope };
+};
+
+const setApprovalModeWithScope = async (
+  context: CommandContext,
+  mode: ApprovalMode,
+  scope: 'session' | 'user' | 'project',
+): Promise<MessageActionReturn> => {
+  const { services } = context;
+  const { config } = services;
+
+  if (!config) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: 'Configuration not available.',
+    };
+  }
+
+  try {
+    // Always set the mode in the current session
+    config.setApprovalMode(mode);
+
+    // If scope is not session, also persist to settings
+    if (scope !== 'session') {
+      const { settings } = context.services;
+      if (!settings || typeof settings.setValue !== 'function') {
+        return {
+          type: 'message',
+          messageType: 'error',
+          content:
+            'Settings service is not available; unable to persist the approval mode.',
+        };
+      }
+
+      const settingScope =
+        scope === 'user' ? SettingScope.User : SettingScope.Workspace;
+      const scopeLabel = scope === 'user' ? 'user' : 'project';
+      let settingsPath: string | undefined;
+
+      try {
+        if (typeof settings.forScope === 'function') {
+          settingsPath = settings.forScope(settingScope)?.path;
+        }
+      } catch (_error) {
+        settingsPath = undefined;
+      }
+
+      try {
+        settings.setValue(settingScope, 'approvalMode', mode);
+      } catch (error) {
+        return {
+          type: 'message',
+          messageType: 'error',
+          content: `Failed to save approval mode: ${(error as Error).message}`,
+        };
+      }
+
+      const locationSuffix = settingsPath ? ` at ${settingsPath}` : '';
+
+      const scopeSuffix = ` (saved to ${scopeLabel} settings${locationSuffix})`;
+
+      return {
+        type: 'message',
+        messageType: 'info',
+        content: `Approval mode changed to: ${mode}${scopeSuffix}`,
+      };
+    }
+
+    return {
+      type: 'message',
+      messageType: 'info',
+      content: `Approval mode changed to: ${mode}`,
+    };
+  } catch (error) {
+    return {
+      type: 'message',
+      messageType: 'error',
+      content: `Failed to change approval mode: ${(error as Error).message}`,
+    };
+  }
+};
+
+export const approvalModeCommand: SlashCommand = {
+  name: 'approval-mode',
+  description: 'View or change the approval mode for tool usage',
+  kind: CommandKind.BUILT_IN,
+  action: async (
+    context: CommandContext,
+    args: string,
+  ): Promise<MessageActionReturn> => {
+    const { config } = context.services;
+    if (!config) {
+      return {
+        type: 'message',
+        messageType: 'error',
+        content: 'Configuration not available.',
+      };
+    }
+
+    // If no arguments provided, show current mode and available options
+    if (!args || args.trim() === '') {
+      const currentMode =
+        typeof config.getApprovalMode === 'function'
+          ? config.getApprovalMode()
+          : null;
+
+      const messageLines: string[] = [];
+
+      if (currentMode) {
+        messageLines.push(`Current approval mode: ${currentMode}`);
+        messageLines.push('');
+      }
+
+      messageLines.push('Available approval modes:');
+      for (const mode of APPROVAL_MODES) {
+        messageLines.push(`  - ${mode}: ${formatModeDescription(mode)}`);
+      }
+      messageLines.push('');
+      messageLines.push(USAGE_MESSAGE);
+
+      return {
+        type: 'message',
+        messageType: 'info',
+        content: messageLines.join('\n'),
+      };
+    }
+
+    // Parse arguments flexibly
+    const parsed = parseApprovalArgs(args);
+
+    if (parsed.error) {
+      return {
+        type: 'message',
+        messageType: 'error',
+        content: `${parsed.error}. ${USAGE_MESSAGE}`,
+      };
+    }
+
+    if (!parsed.mode) {
+      return {
+        type: 'message',
+        messageType: 'info',
+        content: USAGE_MESSAGE,
+      };
+    }
+
+    const requestedMode = parseApprovalMode(parsed.mode);
+
+    if (!requestedMode) {
+      let message = `Invalid approval mode: ${parsed.mode}\n\n`;
+      message += 'Available approval modes:\n';
+      for (const mode of APPROVAL_MODES) {
+        message += `  - ${mode}: ${formatModeDescription(mode)}\n`;
+      }
+      message += `\n${USAGE_MESSAGE}`;
+      return {
+        type: 'message',
+        messageType: 'error',
+        content: message,
+      };
+    }
+
+    return setApprovalModeWithScope(context, requestedMode, parsed.scope);
+  },
+  subCommands: APPROVAL_MODES.map((mode) => ({
+    name: mode,
+    description: formatModeDescription(mode),
+    kind: CommandKind.BUILT_IN,
+    subCommands: [
+      {
+        name: '--session',
+        description: 'Apply to current session only (temporary)',
+        kind: CommandKind.BUILT_IN,
+        action: async (
+          context: CommandContext,
+          args: string,
+        ): Promise<MessageActionReturn> => {
+          if (args.trim().length > 0) {
+            return {
+              type: 'message',
+              messageType: 'error',
+              content: 'Scope subcommands do not accept additional arguments.',
+            };
+          }
+          return setApprovalModeWithScope(context, mode, 'session');
+        },
+      },
+      {
+        name: '--project',
+        description: 'Persist for this project/workspace',
+        kind: CommandKind.BUILT_IN,
+        action: async (
+          context: CommandContext,
+          args: string,
+        ): Promise<MessageActionReturn> => {
+          if (args.trim().length > 0) {
+            return {
+              type: 'message',
+              messageType: 'error',
+              content: 'Scope subcommands do not accept additional arguments.',
+            };
+          }
+          return setApprovalModeWithScope(context, mode, 'project');
+        },
+      },
+      {
+        name: '--user',
+        description: 'Persist for this user on this machine',
+        kind: CommandKind.BUILT_IN,
+        action: async (
+          context: CommandContext,
+          args: string,
+        ): Promise<MessageActionReturn> => {
+          if (args.trim().length > 0) {
+            return {
+              type: 'message',
+              messageType: 'error',
+              content: 'Scope subcommands do not accept additional arguments.',
+            };
+          }
+          return setApprovalModeWithScope(context, mode, 'user');
+        },
+      },
+    ],
+    action: async (
+      context: CommandContext,
+      args: string,
+    ): Promise<MessageActionReturn> => {
+      if (args.trim().length > 0) {
+        // Allow users who type `/approval-mode plan --user` via the subcommand path
+        const parsed = parseApprovalArgs(`${mode} ${args}`);
+        if (parsed.error) {
+          return {
+            type: 'message',
+            messageType: 'error',
+            content: `${parsed.error}. ${USAGE_MESSAGE}`,
+          };
+        }
+
+        const normalizedMode = parseApprovalMode(parsed.mode);
+        if (!normalizedMode) {
+          return {
+            type: 'message',
+            messageType: 'error',
+            content: `Invalid approval mode: ${parsed.mode}. ${USAGE_MESSAGE}`,
+          };
+        }
+
+        return setApprovalModeWithScope(context, normalizedMode, parsed.scope);
+      }
+
+      return setApprovalModeWithScope(context, mode, 'session');
+    },
+  })),
+  completion: async (_context: CommandContext, partialArg: string) => {
+    const tokens = tokenizeArgs(partialArg);
+    const hasTrailingSpace = /\s$/.test(partialArg);
+    const currentSegment = hasTrailingSpace
+      ? ''
+      : tokens.length > 0
+        ? tokens[tokens.length - 1]
+        : '';
+
+    const normalizedCurrent = normalizeInputMode(currentSegment).replace(
+      /_/g,
+      '-',
+    );
+
+    const scopeValues = ['--session', '--project', '--user'];
+
+    const normalizeToken = (token: string) =>
+      normalizeInputMode(token).replace(/_/g, '-');
+
+    const normalizedTokens = tokens.map(normalizeToken);
+
+    if (tokens.length === 0) {
+      if (currentSegment.startsWith('-')) {
+        return scopeValues.filter((scope) => scope.startsWith(currentSegment));
+      }
+      return APPROVAL_MODES;
+    }
+
+    if (tokens.length === 1 && !hasTrailingSpace) {
+      const originalToken = tokens[0];
+      if (originalToken.startsWith('-')) {
+        return scopeValues.filter((scope) =>
+          scope.startsWith(normalizedCurrent),
+        );
+      }
+      return APPROVAL_MODES.filter((mode) =>
+        mode.startsWith(normalizedCurrent),
+      );
+    }
+
+    if (tokens.length === 1 && hasTrailingSpace) {
+      const normalizedFirst = normalizedTokens[0];
+      if (scopeValues.includes(tokens[0])) {
+        return APPROVAL_MODES;
+      }
+      if (APPROVAL_MODES.includes(normalizedFirst as ApprovalMode)) {
+        return scopeValues;
+      }
+      return APPROVAL_MODES;
+    }
+
+    if (tokens.length === 2 && !hasTrailingSpace) {
+      const normalizedFirst = normalizedTokens[0];
+      if (scopeValues.includes(tokens[0])) {
+        return APPROVAL_MODES.filter((mode) =>
+          mode.startsWith(normalizedCurrent),
+        );
+      }
+      if (APPROVAL_MODES.includes(normalizedFirst as ApprovalMode)) {
+        return scopeValues.filter((scope) =>
+          scope.startsWith(normalizedCurrent),
+        );
+      }
+      return [];
+    }
+
+    return [];
+  },
+};