@robota-sdk/agent-command 3.0.0-beta.78 → 3.0.0-beta.81

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

@@ -2,9 +2,12 @@ import { describe, expect, it, vi } from 'vitest';
 import type {
   ICommandHostContext,
   IEditCheckpointRestoreResult,
+  IPermissionRuleLayer,
+  IPermissionsCommandState,
 } from '@robota-sdk/agent-framework';
 import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
 import { createPermissionsCommandModule } from '../permissions-command-module.js';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
 
 type TPermissionModeName = 'plan' | 'default' | 'acceptEdits' | 'bypassPermissions';
 type TSetPermissionModeSpy = ReturnType<typeof vi.fn<(nextMode: TPermissionModeName) => void>>;
@@ -28,41 +31,55 @@ function createCheckpointResult(): IEditCheckpointRestoreResult {
 function createCommandHostContext(options?: {
   mode?: TPermissionModeName;
   sessionAllowed?: readonly string[];
-}): ICommandHostContext & { setPermissionMode: TSetPermissionModeSpy } {
+  rules?: { allow: string[]; deny: string[]; ask: string[] };
+  denials?: IPermissionsCommandState['recentDenials'];
+  layers?: readonly IPermissionRuleLayer[];
+  retryDenial?: (index: number) => IPermissionsCommandState['recentDenials'][number] | undefined;
+}): ReturnType<typeof createTestCommandHost> & { setPermissionMode: TSetPermissionModeSpy } {
   let mode = options?.mode ?? 'default';
   const setPermissionMode = vi.fn((nextMode: TPermissionModeName) => {
     mode = nextMode;
   });
 
   return {
-    getSession: () => {
-      throw new Error('permissions command should use the permission mode adapter');
-    },
-    getCommandHostAdapters: () => ({
-      permissionMode: {
-        getPermissionMode: () => mode,
-        setPermissionMode,
-        listSessionAllowedTools: () => options?.sessionAllowed ?? [],
+    ...createTestCommandHost({
+      overrides: {
+        getSession: () => {
+          throw new Error('permissions command should use the permission mode adapter');
+        },
+        getCommandHostAdapters: () => ({
+          permissionMode: {
+            getPermissionMode: () => mode,
+            setPermissionMode,
+            listSessionAllowedTools: () => options?.sessionAllowed ?? [],
+            getPermissionRules: () => options?.rules ?? { allow: [], deny: [], ask: [] },
+            listRecentDenials: () => options?.denials ?? [],
+            retryDenial: (index: number) => options?.retryDenial?.(index),
+          },
+          ...(options?.layers !== undefined
+            ? { permissionRules: { readLayers: () => options.layers! } }
+            : {}),
+        }),
+        getContextState: () => ({
+          usedTokens: 0,
+          maxTokens: 1,
+          usedPercentage: 0,
+          remainingPercentage: 100,
+        }),
+        getAutoCompactThreshold: () => 0.835,
+        compactContext: async () => undefined,
+        getCwd: () => '/workspace',
+        listEditCheckpoints: () => [],
+        restoreEditCheckpoint: async () => createCheckpointResult(),
+        rollbackEditCheckpoint: async () => createCheckpointResult(),
+        getUsedMemoryReferences: () => [],
+        recordMemoryEvent: () => undefined,
+        listBackgroundTasks: () => [],
+        readBackgroundTaskLog: async () => ({ taskId: 'task_1', lines: [] }),
+        cancelBackgroundTask: async () => undefined,
+        closeBackgroundTask: async () => undefined,
       },
     }),
-    getContextState: () => ({
-      usedTokens: 0,
-      maxTokens: 1,
-      usedPercentage: 0,
-      remainingPercentage: 100,
-    }),
-    getAutoCompactThreshold: () => 0.835,
-    compactContext: async () => undefined,
-    getCwd: () => '/workspace',
-    listEditCheckpoints: () => [],
-    restoreEditCheckpoint: async () => createCheckpointResult(),
-    rollbackEditCheckpoint: async () => createCheckpointResult(),
-    getUsedMemoryReferences: () => [],
-    recordMemoryEvent: () => undefined,
-    listBackgroundTasks: () => [],
-    readBackgroundTaskLog: async () => ({ taskId: 'task_1', lines: [] }),
-    cancelBackgroundTask: async () => undefined,
-    closeBackgroundTask: async () => undefined,
     setPermissionMode,
   };
 }
@@ -78,7 +95,7 @@ describe('createPermissionsCommandModule', () => {
       expect.objectContaining({
         name: 'permissions',
         description: 'Show/change permission mode and permission rules',
-        argumentHint: 'plan | default | acceptEdits | bypassPermissions',
+        argumentHint: 'plan | default | acceptEdits | bypassPermissions | auto',
         source: 'permissions',
         modelInvocable: false,
       }),
@@ -88,12 +105,13 @@ describe('createPermissionsCommandModule', () => {
       'default',
       'acceptEdits',
       'bypassPermissions',
+      'auto',
     ]);
     expect(command).toEqual(
       expect.objectContaining({
         name: 'permissions',
         description: 'Show/change permission mode and permission rules',
-        argumentHint: 'plan | default | acceptEdits | bypassPermissions',
+        argumentHint: 'plan | default | acceptEdits | bypassPermissions | auto',
         lifecycle: 'inline',
         modelInvocable: false,
       }),
@@ -109,7 +127,9 @@ describe('createPermissionsCommandModule', () => {
     const result = await executor.execute('permissions', createCommandHostContext(), '');
 
     expect(result?.success).toBe(true);
-    expect(result?.message).toBe('Permission mode: default\nNo session-approved tools.');
+    expect(result?.message).toBe(
+      'Permission mode: default\n\nRules: none configured.\n\nNo session-approved tools.\n\nRecent denials: none.',
+    );
     expect(result?.data).toEqual({ mode: 'default', sessionAllowed: [] });
   });
 
@@ -125,12 +145,59 @@ describe('createPermissionsCommandModule', () => {
     );
 
     expect(result?.success).toBe(true);
-    expect(result?.message).toBe(
-      'Permission mode: acceptEdits\nSession-approved tools: Bash, Read',
-    );
+    expect(result?.message).toContain('Approved this session ("allow always"): Bash, Read');
     expect(result?.data).toEqual({ mode: 'acceptEdits', sessionAllowed: ['Bash', 'Read'] });
   });
 
+  it('lists the effective rules under the settings file each comes from, and recent denials (issue #3082)', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createPermissionsCommandModule().systemCommands ?? []),
+    ]);
+    const at = new Date(2026, 8, 25, 9, 5, 7).getTime();
+    const result = await executor.execute(
+      'permissions',
+      createCommandHostContext({
+        rules: { allow: ['Read', 'mcp__docs__*'], deny: ['Bash(rm *)'], ask: ['Bash(git push*)'] },
+        layers: [
+          {
+            source: '~/.robota/settings.json',
+            scope: 'user',
+            allow: ['Read'],
+            deny: ['Bash(rm *)'],
+            ask: [],
+          },
+          {
+            source: '.robota/settings.json',
+            scope: 'project',
+            allow: ['Read', 'Stale'],
+            deny: [],
+            ask: ['Bash(git push*)'],
+          },
+        ],
+        denials: [{ toolName: 'Bash', argument: 'rm -rf ~', reason: 'policy', at }],
+      }),
+      '',
+    );
+    expect(result?.message).toContain(
+      [
+        'Rules (checked deny, then ask, then allow):',
+        '  ~/.robota/settings.json [user]',
+        '    deny: Bash(rm *)',
+        '    allow: Read',
+        '  .robota/settings.json [project]',
+        '    ask: Bash(git push*)',
+        '    allow: Read',
+        '  this session (CLI flags, preset, commands)',
+        '    allow: mcp__docs__*',
+      ].join('\n'),
+    );
+    // A layer's rule the session does not enforce is not listed as if it were.
+    expect(result?.message).not.toContain('Stale');
+    expect(result?.message).toContain(
+      'Recent denials (most recent first):\n  1. 09:05:07  Bash(rm -rf ~) — denied by a rule or the mode',
+    );
+  });
+
   it('updates valid permission modes through the SDK command adapter', async () => {
     const executor = new SystemCommandExecutor([
       ...(createPermissionsCommandModule().systemCommands ?? []),
@@ -140,9 +207,7 @@ describe('createPermissionsCommandModule', () => {
     const result = await executor.execute('permissions', context, 'plan');
 
     expect(result?.success).toBe(true);
-    expect(result?.message).toBe(
-      'Permission mode set to: plan\nPermission mode: plan\nNo session-approved tools.',
-    );
+    expect(result?.message).toMatch(/^Permission mode set to: plan\nPermission mode: plan\n/);
     expect(result?.data).toEqual({ mode: 'plan', sessionAllowed: [] });
     expect(context.setPermissionMode).toHaveBeenCalledWith('plan');
   });
@@ -157,8 +222,55 @@ describe('createPermissionsCommandModule', () => {
 
     expect(result?.success).toBe(false);
     expect(result?.message).toBe(
-      'Invalid mode. Valid: plan | default | acceptEdits | bypassPermissions',
+      'Invalid mode. Valid: plan | default | acceptEdits | bypassPermissions | auto',
     );
     expect(context.setPermissionMode).not.toHaveBeenCalled();
   });
+
+  it('reports a mode the session refuses instead of throwing', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createPermissionsCommandModule().systemCommands ?? []),
+    ]);
+    const context = createCommandHostContext();
+    context.setPermissionMode.mockImplementation(() => {
+      throw new Error('Auto mode is unavailable: this session has no permission classifier.');
+    });
+
+    const result = await executor.execute('permissions', context, 'auto');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toBe(
+      'Auto mode is unavailable: this session has no permission classifier.',
+    );
+  });
+
+  it('retries a classifier denial by the number /permissions shows (issue #3082)', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createPermissionsCommandModule().systemCommands ?? []),
+    ]);
+    const denial = {
+      toolName: 'Bash',
+      argument: 'npm publish',
+      reason: 'classifier' as const,
+      detail: 'publishes a package',
+      at: new Date(2026, 8, 25, 13, 4, 5).getTime(),
+    };
+    const retryDenial = vi.fn((index: number) => (index === 0 ? denial : undefined));
+    const context = createCommandHostContext({ denials: [denial], retryDenial });
+
+    const listed = await executor.execute('permissions', context, '');
+    expect(listed?.message).toContain(
+      '1. 13:04:05  Bash(npm publish) — blocked by the auto-mode classifier: publishes a package',
+    );
+    expect(listed?.message).toContain('/permissions retry <n>');
+
+    const retried = await executor.execute('permissions', context, 'retry 1');
+    expect(retried?.success).toBe(true);
+    expect(retried?.message).toContain('Bash(npm publish) will run once');
+    expect(retryDenial).toHaveBeenCalledWith(0);
+
+    const missing = await executor.execute('permissions', context, 'retry 2');
+    expect(missing?.success).toBe(false);
+    expect(missing?.message).toMatch(/^Usage: \/permissions retry <n>/);
+  });
 });

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

@@ -7,7 +7,7 @@ import {
 import { executePermissionsCommand } from './permissions-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 export function createPermissionsCommandEntry(): ICommand {
   return {
@@ -17,6 +17,7 @@ export function createPermissionsCommandEntry(): ICommand {
     source: 'permissions',
     argumentHint: PERMISSION_MODE_ARGUMENT_HINT,
     subcommands: buildPermissionModeSubcommands('permissions'),
+    // User-only: edits permission rules; permission widening is the user's.
     modelInvocable: false,
   };
 }

package/src/permissions/permissions-command.ts

@@ -4,17 +4,58 @@ import {
   isPermissionMode,
   parsePermissionModeArgument,
   readCommandPermissionsState,
+  retryCommandPermissionDenial,
   writeCommandPermissionMode,
 } from '@robota-sdk/agent-framework';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type {
+  ICommandHostAdapterAccess,
+  ICommandHostSessionAccess,
+} from '@robota-sdk/agent-framework';
+import type { TPermissionMode } from '@robota-sdk/agent-core';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+/** Switch the mode, or the refusal to show when the session will not enter it. */
+export function tryWritePermissionMode(
+  context: ICommandHostAdapterAccess & ICommandHostSessionAccess,
+  mode: TPermissionMode,
+): ICommandResult | undefined {
+  try {
+    writeCommandPermissionMode(context, mode);
+    return undefined;
+  } catch (error) {
+    return { message: error instanceof Error ? error.message : String(error), success: false };
+  }
+}
+
+function executeRetry(
+  context: ICommandHostAdapterAccess & ICommandHostSessionAccess,
+  args: string,
+): ICommandResult {
+  const position = Number(args.trim().split(/\s+/)[1]);
+  const denial = retryCommandPermissionDenial(context, position);
+  if (denial === undefined) {
+    return {
+      message:
+        'Usage: /permissions retry <n>, where <n> numbers a call blocked by the auto-mode ' +
+        'classifier in /permissions.',
+      success: false,
+    };
+  }
+  const call =
+    denial.argument !== undefined ? `${denial.toolName}(${denial.argument})` : denial.toolName;
+  return {
+    message: `${call} will run once, without the classifier, when the model tries it again.`,
+    success: true,
+  };
+}
 
 export function executePermissionsCommand(
-  context: ICommandHostContext,
+  context: ICommandHostAdapterAccess & ICommandHostSessionAccess,
   args: string,
 ): ICommandResult {
   const arg = parsePermissionModeArgument(args);
+  if (arg === 'retry') return executeRetry(context, args);
   if (arg !== undefined) {
     if (!isPermissionMode(arg)) {
       return {
@@ -23,7 +64,8 @@ export function executePermissionsCommand(
       };
     }
 
-    writeCommandPermissionMode(context, arg);
+    const refused = tryWritePermissionMode(context, arg);
+    if (refused !== undefined) return refused;
     const state = readCommandPermissionsState(context);
     return {
       message: `Permission mode set to: ${arg}\n${formatCommandPermissionsMessage(state)}`,

package/src/plan/__tests__/plan-command.test.ts

@@ -0,0 +1,129 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { executePlanCommand } from '../plan-command.js';
+
+import type { IPlanArtifact } from '@robota-sdk/agent-interface-session';
+import {
+  createTestCommandHost,
+  type ICreateTestCommandHostOptions,
+} from '@robota-sdk/agent-framework/testing';
+
+function plan(overrides: Partial<IPlanArtifact> = {}): IPlanArtifact {
+  return {
+    id: 'p1',
+    objective: 'ship the feature',
+    steps: [{ id: 'p1_0', description: 'draft the change', status: 'pending' }],
+    phase: 'planning',
+    createdAt: '2026-07-17T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+function host(overrides: ICreateTestCommandHostOptions['overrides'] = {}) {
+  // ARCH-029: the partial is now an OVERRIDE over a conformant host, not a cast that turns the
+  // check off. A fixture that names three members no longer claims to satisfy 46.
+  return createTestCommandHost({ overrides });
+}
+
+describe('executePlanCommand (SELFHOST-002 /plan)', () => {
+  it('drafts a plan from the objective text', async () => {
+    const setPlan = vi.fn().mockResolvedValue(plan());
+    const result = await executePlanCommand(host({ setPlan }), 'ship the feature');
+    expect(setPlan).toHaveBeenCalledWith('ship the feature');
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('/plan approve');
+    expect(result.data).toMatchObject({ planId: 'p1' });
+  });
+
+  it('renders the current plan on "status"', async () => {
+    const result = await executePlanCommand(
+      host({ getPlanState: () => plan({ phase: 'awaiting-approval' }) }),
+      'status',
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('ship the feature');
+    expect(result.message).toContain('Phase: awaiting-approval');
+    expect(result.message).toContain('1. [pending] draft the change');
+  });
+
+  it('reports when no plan is active', async () => {
+    const result = await executePlanCommand(host({ getPlanState: () => null }), 'status');
+    expect(result.message).toBe('No plan is active.');
+  });
+
+  it('approves via approvePlan and reports the executing phase', async () => {
+    const approvePlan = vi.fn().mockReturnValue(plan({ phase: 'executing' }));
+    const result = await executePlanCommand(
+      host({ getPlanState: () => plan({ phase: 'awaiting-approval' }), approvePlan }),
+      'approve',
+    );
+    expect(approvePlan).toHaveBeenCalled();
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('edits will auto-apply');
+    expect(result.data).toMatchObject({ phase: 'executing' });
+  });
+
+  it('rejects approve when no plan exists', async () => {
+    const approvePlan = vi.fn();
+    const result = await executePlanCommand(
+      host({ getPlanState: () => null, approvePlan }),
+      'approve',
+    );
+    expect(approvePlan).not.toHaveBeenCalled();
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('No plan to approve');
+  });
+
+  it('surfaces an out-of-phase approval error as a failed result', async () => {
+    const approvePlan = vi.fn(() => {
+      throw new Error('approve requires phase "awaiting-approval", got "executing".');
+    });
+    const result = await executePlanCommand(
+      host({ getPlanState: () => plan({ phase: 'executing' }), approvePlan }),
+      'approve',
+    );
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('awaiting-approval');
+  });
+
+  it('reverts via revertPlan', async () => {
+    const revertPlan = vi.fn().mockReturnValue(plan({ phase: 'planning' }));
+    const result = await executePlanCommand(
+      host({ getPlanState: () => plan({ phase: 'executing' }), revertPlan }),
+      'revert',
+    );
+    expect(revertPlan).toHaveBeenCalled();
+    expect(result.message).toContain('edits are blocked again');
+  });
+
+  it('shows usage on empty args or help', async () => {
+    const result = await executePlanCommand(host({}), '');
+    expect(result.message).toContain('Usage:');
+    expect(result.message).toContain('/plan approve');
+  });
+
+  it('ARCH-029 TC-09: the availability guards are gone from the source', () => {
+    // Review caught the first attempt at this case: it re-asserted "No plan is active." for a
+    // null-returning host, which `reports when no plan is active` above already pins with a
+    // STRONGER matcher, over an override that is the double's own default. It would have passed
+    // unchanged on the pre-fix code — a check that cannot fail on the thing it names.
+    //
+    // Stated plainly instead: there is NO behavioural test for this deletion, because there was no
+    // behaviour. `if (!context.setPlan) return 'Plan mode is not available in this session.'` was
+    // already unreachable — the members are unconditionally implemented on `InteractiveSession`
+    // over always-constructed controllers, and it is the only host (`implements` is compiler-
+    // checked, casts are ratcheted at 0, and heritage-clause aliases are counted since this
+    // review). Required-ness makes the branch unreachable for the type checker too. So what can be
+    // pinned is that the branch is not in the file, and that is what this asserts.
+    const source = readFileSync(
+      fileURLToPath(new URL('../plan-command.js', import.meta.url)).replace(/\.js$/, '.ts'),
+      'utf8',
+    );
+
+    expect(source).not.toContain('is not available in this session');
+    expect(source).not.toMatch(/if \(!context\.[a-zA-Z]+\)/);
+  });
+});

package/src/plan/index.ts

@@ -0,0 +1,9 @@
+/**
+ * SELFHOST-002: `/plan` explicit plan-mode command.
+ *
+ * Only the module factory is a package-entry export (matching the other command modules — sources,
+ * command handlers, and descriptions stay internal, imported by direct path). This keeps the
+ * package's public surface minimal and its SPEC Public API table in sync.
+ */
+
+export { createPlanCommandModule } from './plan-command-module.js';

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

@@ -0,0 +1,49 @@
+/**
+ * SELFHOST-002: `/plan` command module registration.
+ */
+
+import { executePlanCommand, PLAN_COMMAND_DESCRIPTION } from './plan-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createPlanCommandEntry(): ICommand {
+  return {
+    name: 'plan',
+    displayName: 'Plan Mode',
+    description: PLAN_COMMAND_DESCRIPTION,
+    source: 'plan',
+    // User-only: approving a plan unblocks edits; that permission change is the user's.
+    modelInvocable: false,
+  };
+}
+
+function createPlanSystemCommand(): ISystemCommand {
+  const entry = createPlanCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executePlanCommand,
+  };
+}
+
+export class PlanCommandSource implements ICommandSource {
+  readonly name = 'plan';
+
+  getCommands(): ICommand[] {
+    return [createPlanCommandEntry()];
+  }
+}
+
+export function createPlanCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-plan',
+    commandSources: [new PlanCommandSource()],
+    systemCommands: [createPlanSystemCommand()],
+  };
+}

package/src/plan/plan-command.ts

@@ -0,0 +1,92 @@
+/**
+ * SELFHOST-002: the `/plan` slash command — explicit plan-mode (plan → review → approve → act).
+ * Delegates to the framework-owned plan controller via the command host context; the phase machine
+ * and the `setPermissionMode` application both live in agent-framework. The mutation block stays the
+ * existing `plan` permission mode; approving flips to `acceptEdits` (edits auto-apply, shell stays
+ * per-call confirmed).
+ */
+
+import type { ICommandHostPlan } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IPlanArtifact } from '@robota-sdk/agent-interface-session';
+
+export const PLAN_COMMAND_DESCRIPTION =
+  'Draft a reviewable plan, then approve it to unblock edits (plan → review → approve → act).';
+
+const PLAN_COMMAND_USAGE =
+  'Usage:\n  /plan <objective>   draft a plan for review (stays read-only until approved)\n' +
+  '  /plan status         show the current plan and phase\n' +
+  '  /plan approve        approve the plan (edits auto-apply; shell stays confirmed)\n' +
+  '  /plan revert         return to drafting (re-blocks edits)';
+
+function formatPlan(plan: IPlanArtifact): string {
+  const lines = [
+    `Plan: ${plan.objective}`,
+    `Phase: ${plan.phase}${plan.approvedAt ? ` (approved ${plan.approvedAt})` : ''}`,
+  ];
+  plan.steps.forEach((step, index) => {
+    lines.push(`  ${index + 1}. [${step.status}] ${step.description}`);
+  });
+  return lines.join('\n');
+}
+
+export async function executePlanCommand(
+  context: ICommandHostPlan,
+  args: string,
+): Promise<ICommandResult> {
+  const trimmed = args.trim();
+  const verb = trimmed.split(/\s+/)[0]?.toLowerCase() ?? '';
+
+  if (trimmed.length === 0 || verb === 'help') {
+    return { message: PLAN_COMMAND_USAGE, success: true };
+  }
+
+  if (verb === 'status') {
+    const plan = context.getPlanState();
+    return plan
+      ? { message: formatPlan(plan), success: true, data: { phase: plan.phase } }
+      : { message: 'No plan is active.', success: true };
+  }
+
+  if (verb === 'approve') {
+    if (!context.getPlanState()) {
+      return { message: 'No plan to approve. Start one with /plan <objective>.', success: false };
+    }
+    try {
+      const plan = context.approvePlan();
+      return {
+        message: `Plan approved — edits will auto-apply; shell steps stay confirmed.\nPhase: ${plan.phase}`,
+        success: true,
+        data: { phase: plan.phase },
+      };
+    } catch (error) {
+      // allow-fallback: an out-of-phase approval surfaces as a failed command, not a crash
+      return { message: error instanceof Error ? error.message : String(error), success: false };
+    }
+  }
+
+  if (verb === 'revert') {
+    if (!context.getPlanState()) {
+      return { message: 'No plan to revert.', success: false };
+    }
+    const plan = context.revertPlan();
+    return {
+      message: `Reverted to drafting — edits are blocked again (plan mode).\nPhase: ${plan.phase}`,
+      success: true,
+      data: { phase: plan.phase },
+    };
+  }
+
+  let plan: IPlanArtifact;
+  try {
+    plan = await context.setPlan(trimmed);
+  } catch (error) {
+    // allow-fallback: surface an invalid-objective error as a failed command result, not a crash
+    return { message: error instanceof Error ? error.message : String(error), success: false };
+  }
+  return {
+    message: `Plan drafted (read-only until approved). Review it, then run /plan approve:\n${plan.objective}`,
+    success: true,
+    data: { planId: plan.id },
+  };
+}