@robota-sdk/agent-command 3.0.0-beta.100

package/src/default/__tests__/__snapshots__/model-exposure.test.ts.snap

@@ -0,0 +1,121 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`built-in commands offered to the model > pins the descriptor each offered command gets 1`] = `
+{
+  "agent": {
+    "argumentHint": "PROMPT | AGENT_NAME PROMPT | list | parallel [--wait|--detach] LABEL:"PROMPT" [LABEL=AGENT_NAME:"PROMPT"] | wait GROUP_ID | read AGENT_ID [OFFSET] | send AGENT_ID PROMPT | stop AGENT_ID | close AGENT_ID",
+    "description": "Start and manage background subagent jobs. Natural-language arguments start one background agent job. When the user explicitly asks to create, run, spawn, delegate to, or use agents/subagents, start the requested agent command immediately and do not ask a follow-up question unless execution is impossible or unsafe. If the target item is unspecified, include target selection inside the agent prompt instead of delaying execution. The parallel form starts multiple background agent jobs as a wait_all group and returns a consolidated group summary unless --detach is present. list, wait, read, send, stop, close, and open manage existing agent jobs. Returns the started job id (or group summary), the job list, or the requested log page.",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "agent",
+    "requiresPermission": false,
+    "safety": "background-agent",
+    "userInvocable": true,
+  },
+  "compact": {
+    "argumentHint": "[instructions]",
+    "description": "Summarize older conversation turns to free context-window space. Use it when the context is nearly full (check with the context command) or before starting a large new task; optional instructions say what the summary must keep. Returns how many messages were removed and the context usage before and after.",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "compact",
+    "requiresPermission": false,
+    "safety": "write",
+    "userInvocable": true,
+  },
+  "context": {
+    "argumentHint": "[list]",
+    "description": "Inspect the context window. Use it before a large task or before deciding to compact, or to see which files the user pinned into context. Bare returns used/max tokens and percentage, the auto-compact threshold, the pinned-reference summary and the turn count; \`list\` returns the per-category token breakdown and every pinned reference.
+Subcommands you may run (bare \`context\` is also allowed):
+- list: List loaded context references",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "context",
+    "requiresPermission": false,
+    "userInvocable": true,
+  },
+  "cost": {
+    "description": "Report this session’s token usage and estimated cost. Use it before an expensive step (a large refactor, many subagents) or when the user asks what the session has cost. Returns the message count, input/output token totals and the estimated USD cost, with the remaining monthly budget when one is set. Setting or clearing the budget is the user’s decision: suggest \`/cost budget <amount>\`.
+Run it with no arguments.",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "cost",
+    "requiresPermission": false,
+    "userInvocable": true,
+  },
+  "loop": {
+    "argumentHint": "[prompt] | <N><s|m|h|d> [prompt] | <prompt> every <N> <unit> | list | stop <id>",
+    "description": "Repeat a prompt on a fixed cadence (\`<N><s|m|h|d> <prompt>\`) or self-paced (\`<prompt>\`: each iteration chooses its next delay or stops). Use it when the user asks for recurring work in this session, and always give your own prompt: any form that would fall back to the host's default maintenance prompt — bare \`/loop\` or an interval alone (\`<N><s|m|h|d>\`) — needs a person to confirm it and is always refused for you, whether or not one is attached. \`list\` shows active loops; \`stop <id>\` ends one, even mid-turn. Returns the loop id and its next fire time, the loop list, or a refusal naming the command to suggest.",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "loop",
+    "requiresPermission": true,
+    "userInvocable": true,
+  },
+  "mcp": {
+    "argumentHint": "[status | skill-list <server>]",
+    "description": "Show which MCP servers are configured and why any of them is unavailable. Use it when an MCP server or its tools are missing, a tool call reports that a server needs sign-in or approval, or the user asks about MCP servers. Returns one line per server: its name, activation state, sign-in state, and the command to suggest to the user when the server needs their approval, sign-in or workspace trust. Use skill-list <server> to discover advertised skill names, URIs and descriptions without loading instructions. Returns an invocation name for each supported skill; use the session skill activation command with that exact name when its workflow fits the task. If content consent is needed, ask the user to run /mcp skill-inspect <server> <uri> and approve the reviewed fingerprint. You cannot approve, inspect instructions, sign in or sign out yourself.
+Subcommands you may run (bare \`mcp\` is also allowed):
+- status: Show every MCP server’s name, activation state and sign-in state
+- skill-list: Discover MCP skill metadata and exact invocation names, or reasons they are unavailable, without activating instructions",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "mcp",
+    "requiresPermission": false,
+    "userInvocable": true,
+  },
+  "memory": {
+    "argumentHint": "[list | show [topic] | add <user|feedback|project|reference> <topic> <text> | pending | used]",
+    "description": "Read and write this project’s durable memory. Use \`list\` or \`show [topic]\` to look up stored conventions, preferences or references before asking the user again; \`add <type> <topic> <text>\` 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. 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>\`. Correcting or forgetting saved knowledge is also user-only: suggest \`/memory correct <type> <topic> <text>\` to replace every entry in a topic or \`/memory forget <topic>\` to remove it from active recall. These operations block automatic restoration of that topic; historical transcripts and backups remain.
+Subcommands you may run (bare \`memory\` is also allowed):
+- list: List project memory topics
+- show: Show project memory index or a topic
+- add: Save durable project memory
+- pending: List pending memory candidates
+- used: Show memory references used in the current turn",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "memory",
+    "requiresPermission": false,
+    "safety": "write",
+    "userInvocable": true,
+  },
+  "monitor": {
+    "argumentHint": ""<command>" "<pattern>" <instruction>",
+    "description": "Run a command in the background and wake yourself when a line of its output matches a pattern. Use it to wait for a server to start, a test to fail or a log line to appear instead of polling. The command is allowed, refused or asked about by the same permission rules as a shell tool call. Returns the monitor task id, or a refusal naming what the user must allow.",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "monitor",
+    "requiresPermission": false,
+    "userInvocable": true,
+  },
+  "schedule": {
+    "argumentHint": "in <N><s|m|h|d> <instruction> | cron "<expr>" <instruction> | list | pause <id> | resume <id> | edit <id> <spec>",
+    "description": "Wake yourself later with an instruction. Use it when work must wait (a deploy, a long build, a reply) instead of polling: \`in <N><s|m|h|d> <instruction>\` or \`cron "<expr>" <instruction>\`; \`list\`, \`pause\`, \`resume\` and \`edit\` manage existing schedules. Returns the schedule id, or the schedule list.",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "schedule",
+    "requiresPermission": false,
+    "userInvocable": true,
+  },
+  "skill-read": {
+    "argumentHint": "["<skill-name>", "<resource-uri>"]",
+    "description": "Read verified supporting bytes from a skill already activated in this execution. Use when its instructions refer to a resource in the returned manifest. Args are a JSON array ["<skill-name>", "<resource-uri>"]. Returns the verified URI, digest, size and text or base64 blob with optional MIME type. This does not activate nested skills or grant consent; unactivated skills, undeclared resources and ended executions are refused. Binary blobs are returned as encoded data, not a rendered image.",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "skill-read",
+    "requiresPermission": false,
+    "safety": "read-only",
+    "userInvocable": true,
+  },
+  "skills": {
+    "argumentHint": "[list | <skill-name> [args]]",
+    "description": "Skill command. Before following a matching registered skill from the system prompt Skills section, invoke the projected skills command tool with args "<skill-name> [args]". Without arguments, list registered skills. With a skill name, activate that skill; a skill that declares it is not model-invocable is refused. Returns the skill list with each skill's description, or the activated skill's instructions to follow. Slash syntax is a UI input/display concern; the SDK command identity is "skills".",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "skills",
+    "requiresPermission": false,
+    "safety": "read-only",
+    "userInvocable": true,
+  },
+}
+`;

package/src/default/__tests__/default-command-modules.test.ts

@@ -0,0 +1,192 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, describe, expect, it } from 'vitest';
+
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type {
+  IProviderCommandSettingsAdapter,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+
+import { createDefaultCommandModules } from '../default-command-modules.js';
+
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'agent-test-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
+const providerDefinitions: readonly IProviderDefinition[] = [
+  {
+    type: 'anthropic',
+    defaults: { model: 'claude-sonnet-4-6', apiKey: '$ENV:ANTHROPIC_API_KEY' },
+    setupSteps: [{ key: 'apiKey', title: 'anthropic API key', masked: true }],
+    requiresApiKey: true,
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+];
+
+const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => ({}) as TProviderSettingsDocument,
+  readTargetSettings: () => ({}) as TProviderSettingsDocument,
+  writeTargetSettings: () => undefined,
+};
+
+const baseOptions = { cwd: '/tmp', userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT, providerDefinitions, providerSettingsAdapter } as const;
+
+function moduleNames(opts: Parameters<typeof createDefaultCommandModules>[0]): string[] {
+  return createDefaultCommandModules(opts).modules.map((module) => module.name);
+}
+
+describe('createDefaultCommandModules — PRESET-004 module-selection delta', () => {
+  // Module `name`s are the stable ICommandModule ids (the `agent-command-*` form).
+  const HELP = 'agent-command-help';
+  const AGENT = 'agent-command-agent';
+  const BACKGROUND = 'agent-command-background';
+
+  it('TC-04: neither enabled nor disabled given → full default set unchanged (no-regression)', () => {
+    const names = moduleNames(baseOptions);
+    // No-regression: the default set length is the documented 32 modules (SELFHOST-002 added
+    // `/plan`; PEER-004 added `/peers`; CLI-1994 added `/fork`; MCP-2520 added `/mcp`; CLI-1988 added
+    // `/output-style`; FLOW-008 added `/effort`; `/advisor` joined beside it; #3282 §2 added `/model`).
+    // The list below is the assertion that matters — a length on its own can be restored by any
+    // substitution, and the count exists only to catch an addition that also removed something.
+    expect(names).toHaveLength(39);
+    expect(names).toEqual([
+      'agent-command-skills',
+      'agent-command-help',
+      'agent-command-agent',
+      'agent-command-effort',
+      'agent-command-advisor',
+      'agent-command-permissions',
+      'agent-command-mode',
+      'agent-command-sandbox',
+      'agent-command-preset',
+      'agent-command-output-style',
+      'agent-command-language',
+      'agent-command-background',
+      // CLI-1994: registered beside `/background`, because a fork IS a background job.
+      'agent-command-fork',
+      'agent-command-goal',
+      'agent-command-plan',
+      'agent-command-shell',
+      'agent-command-editor',
+      'agent-command-git',
+      'agent-command-keybindings',
+      'agent-command-theme',
+      'agent-command-memory',
+      'agent-command-mcp-activation',
+      'agent-command-user-local',
+      'agent-command-compact',
+      'agent-command-context',
+      'agent-command-exit',
+      'agent-command-session',
+      'agent-command-reset',
+      'agent-command-rewind',
+      'agent-command-schedule',
+      'agent-command-statusline',
+      'agent-command-plugin',
+      'agent-command-settings',
+      'agent-command-peers',
+      'agent-command-events',
+      'agent-command-handoff',
+      'agent-command-remote-control',
+      'agent-command-provider',
+      'agent-command-model',
+    ]);
+  });
+
+  it('TC-01: enabledCommandModules whitelist keeps exactly the listed module names', () => {
+    const names = moduleNames({ ...baseOptions, enabledCommandModules: [HELP, AGENT] });
+    expect(new Set(names)).toEqual(new Set([HELP, AGENT]));
+    expect(names).toHaveLength(2);
+  });
+
+  it('#3186: /keybindings and /theme exist on a host without a terminal, and say where they work', async () => {
+    const { modules } = createDefaultCommandModules(baseOptions);
+    const commands = modules.flatMap((module) => module.systemCommands ?? []);
+    for (const name of ['keybindings', 'theme']) {
+      const command = commands.find((candidate) => candidate.name === name);
+      expect(command, name).toBeDefined();
+      const result = await command!.execute({} as never, '');
+      expect(result).toMatchObject({ success: false });
+      expect(result.message).toMatch(/interactive terminal/);
+    }
+  });
+
+  it('#3189: exactly /editor, /keybindings, /shell and /theme run on the terminal client', () => {
+    const { modules } = createDefaultCommandModules(baseOptions);
+    const TERMINAL_CLIENT = ['editor', 'keybindings', 'shell', 'theme'];
+
+    // The executable commands: what the runtime keeps in its catalog and what the listing reads.
+    const clientSystemCommands = modules
+      .flatMap((module) => module.systemCommands ?? [])
+      .filter((command) => command.runner === 'client');
+    expect(clientSystemCommands.map((command) => command.name).sort()).toEqual(TERMINAL_CLIENT);
+    for (const command of clientSystemCommands) {
+      expect(command.surfaces, command.name).toEqual(['terminal']);
+    }
+
+    // The palette entries, which must say the same — the two views cannot disagree.
+    const clientEntries = modules
+      .flatMap((module) => module.commandSources ?? [])
+      .flatMap((source) => source.getCommands())
+      .filter((entry) => entry.runner === 'client');
+    expect(clientEntries.map((entry) => entry.name).sort()).toEqual(TERMINAL_CLIENT);
+    for (const entry of clientEntries) {
+      expect(entry.surfaces, entry.name).toEqual(['terminal']);
+      // Running on the client does not change who may run it: all four stay user-only.
+      expect(entry.modelInvocable, entry.name).toBe(false);
+    }
+  });
+
+  it('TC-02: disabledCommandModules blacklist removes the named module', () => {
+    const full = moduleNames(baseOptions);
+    const names = moduleNames({ ...baseOptions, disabledCommandModules: [BACKGROUND] });
+    expect(names).not.toContain(BACKGROUND);
+    expect(names).toHaveLength(full.length - 1);
+  });
+
+  it('TC-03: a name in both enabled and disabled is excluded (deny > allow)', () => {
+    const names = moduleNames({
+      ...baseOptions,
+      enabledCommandModules: [HELP, AGENT],
+      disabledCommandModules: [AGENT],
+    });
+    expect(new Set(names)).toEqual(new Set([HELP]));
+    expect(names).not.toContain(AGENT);
+  });
+
+  it('INFRA-032: an unknown whitelist name yields no module for it AND is reported as unknown', () => {
+    const result = createDefaultCommandModules({
+      ...baseOptions,
+      enabledCommandModules: [HELP, 'does-not-exist'],
+    });
+    // Known-name filtering is unchanged — only the matched module survives.
+    expect(result.modules.map((module) => module.name)).toEqual([HELP]);
+    // The unmatched name is surfaced (no longer silently dropped).
+    expect(result.unknownModuleNames).toEqual([{ name: 'does-not-exist', kind: 'enabled' }]);
+  });
+
+  it('INFRA-032: an unknown disabled name (short form) is reported as unknown', () => {
+    const result = createDefaultCommandModules({
+      ...baseOptions,
+      disabledCommandModules: ['editor'],
+    });
+    // The short form "editor" matches no module name (agent-command-editor stays enabled)…
+    expect(result.modules.map((module) => module.name)).toContain('agent-command-editor');
+    // …and is surfaced rather than silently ignored.
+    expect(result.unknownModuleNames).toEqual([{ name: 'editor', kind: 'disabled' }]);
+  });
+
+  it('INFRA-032: all names matching → unknownModuleNames is empty', () => {
+    const result = createDefaultCommandModules({
+      ...baseOptions,
+      enabledCommandModules: [HELP, AGENT],
+      disabledCommandModules: [AGENT],
+    });
+    expect(result.unknownModuleNames).toEqual([]);
+  });
+});

package/src/default/__tests__/model-exposure.test.ts

@@ -0,0 +1,269 @@
+/**
+ * What of the built-in command set the MODEL is offered, and what it is told.
+ *
+ * Pins, per command: offered or not, the exact model-facing descriptor, and that a user-only
+ * subcommand is neither offered nor runnable. The invariant behind it: trust, credential and
+ * permission-widening actions are never model-invocable. The reasons for each decision sit beside
+ * each command's entry.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, afterEach, describe, expect, it, vi } from 'vitest';
+
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createDoctorCommandModule } from '../../doctor/index.js';
+import { createKeybindingsCommandModule } from '../../keybindings/index.js';
+import { createThemeCommandModule } from '../../theme/index.js';
+import { createDoctorFixture } from '../../doctor/__tests__/doctor-fixture.js';
+import { createDefaultCommandModules } from '../default-command-modules.js';
+
+import type { IDoctorFixture } from '../../doctor/__tests__/doctor-fixture.js';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type {
+  IProviderCommandSettingsAdapter,
+  ISystemCommand,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+import type { IThemeCataloguePort } from '@robota-sdk/agent-interface-command';
+
+const providerDefinitions: readonly IProviderDefinition[] = [];
+const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => ({}) as TProviderSettingsDocument,
+  readTargetSettings: () => ({}) as TProviderSettingsDocument,
+  writeTargetSettings: () => undefined,
+};
+const themeCataloguePort: IThemeCataloguePort = {
+  listThemes: () => [],
+  getTheme: () => undefined,
+  getAppearance: () => ({
+    settings: { theme: 'dark', syntaxHighlighting: true, reducedMotion: false },
+  }),
+};
+
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'agent-test-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
+const fixtures: IDoctorFixture[] = [];
+afterEach(() => {
+  for (const fixture of fixtures.splice(0)) fixture.cleanup();
+});
+
+/** Every built-in command, including the ones only registered when their host port exists. */
+function allBuiltInCommands(): ISystemCommand[] {
+  const fixture = createDoctorFixture({ env: {} });
+  fixtures.push(fixture);
+  const { modules } = createDefaultCommandModules({
+    cwd: '/tmp',
+    userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
+    providerDefinitions,
+    providerSettingsAdapter,
+  });
+  // /keybindings and /theme are in the default set; built here with their capabilities instead.
+  const withoutPortless = modules.filter(
+    (module) =>
+      module.name !== 'agent-command-keybindings' && module.name !== 'agent-command-theme',
+  );
+  return [
+    ...withoutPortless,
+    createKeybindingsCommandModule({ ensureFile: async () => '/tmp/keybindings.json' }),
+    createThemeCommandModule(themeCataloguePort),
+    createDoctorCommandModule(fixture.inputs, fixture.deps),
+  ].flatMap((module) => [...(module.systemCommands ?? [])]);
+}
+
+/** Each command with its `execute` replaced, so a test can see whether it ran at all. */
+function spiedExecutor(): {
+  executor: SystemCommandExecutor;
+  executed: ReturnType<typeof vi.fn>;
+} {
+  const executed = vi.fn(() => ({ success: true, message: 'ran' }));
+  const commands = allBuiltInCommands().map((command) => ({ ...command, execute: executed }));
+  return { executor: new SystemCommandExecutor(commands), executed };
+}
+
+/** Offered to the model, each for a reason given beside its entry. */
+const MODEL_INVOCABLE = [
+  'agent',
+  'compact',
+  'context',
+  'cost',
+  'loop',
+  'mcp',
+  'memory',
+  'monitor',
+  'schedule',
+  'skill-read',
+  'skills',
+];
+
+/** Whole commands the model is never offered. */
+const USER_ONLY_COMMANDS = [
+  // Trust decisions.
+  'plugin',
+  'reload-plugins',
+  'remote-control',
+  'events',
+  // Account and credential actions.
+  'provider',
+  // Cost and capability decisions: the person chooses, never the model on its own (#3282 §2).
+  'model',
+  // Permission widening or permission-mode changes.
+  'mode',
+  'permissions',
+  'sandbox',
+  'preset',
+  'plan',
+  'goal',
+  'cd',
+  // Crossing into another session, machine or process the user owns.
+  'peers',
+  'handoff',
+  'fork',
+  'shell',
+  'git',
+  // Exits and destructive session changes.
+  'exit',
+  'clear',
+  'reset',
+  'rewind',
+  'resume',
+  // UI-only preferences, and views the user reads.
+  'advisor',
+  'effort',
+  'language',
+  'output-style',
+  'statusline',
+  'theme',
+  'keybindings',
+  'settings',
+  'editor',
+  'rename',
+  'help',
+  'background',
+  'doctor',
+  'user-local',
+  'validate-session',
+];
+
+/** User-only subcommands of commands the model IS offered; `list` is an alias `/mcp` accepts for the user. */
+const USER_ONLY_SUBCOMMANDS: Record<string, readonly string[]> = {
+  mcp: [
+    'approve',
+    'reject',
+    'revoke',
+    'logout',
+    'login',
+    'list',
+    'skill-inspect',
+    'skill-approve',
+    'skill-withdraw',
+  ],
+  memory: ['approve', 'reject'],
+  context: ['add', 'remove', 'clear', 'auto'],
+  cost: ['budget'],
+};
+
+describe('built-in commands offered to the model', () => {
+  it('offers exactly the model-invocable set', () => {
+    const { executor } = spiedExecutor();
+    const offered = executor
+      .listModelInvocableCommands()
+      .map((descriptor) => descriptor.name)
+      .sort();
+    expect(offered).toEqual([...MODEL_INVOCABLE].sort());
+  });
+
+  it('covers every built-in command with a decision', () => {
+    const names = allBuiltInCommands()
+      .map((command) => command.name)
+      .sort();
+    expect(names).toEqual([...MODEL_INVOCABLE, ...USER_ONLY_COMMANDS].sort());
+  });
+
+  it('describes every offered command for the model: what, when, and what it returns', () => {
+    for (const command of allBuiltInCommands().filter((c) => c.modelInvocable === true)) {
+      expect(command.modelDescription, command.name).toBeDefined();
+      expect(command.modelDescription, command.name).toMatch(/\bUse\b|\bBefore\b|\bWhen\b/);
+      expect(command.modelDescription, command.name).toMatch(/\b[Rr]eturns\b/);
+    }
+  });
+
+  it('pins the descriptor each offered command gets', () => {
+    const { executor } = spiedExecutor();
+    const descriptors = Object.fromEntries(
+      executor
+        .listModelInvocableCommands()
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((descriptor) => [descriptor.name, descriptor]),
+    );
+    expect(descriptors).toMatchSnapshot();
+  });
+
+  it('never offers or runs a user-only command', async () => {
+    const { executor, executed } = spiedExecutor();
+    const host = createTestCommandHost();
+    for (const name of USER_ONLY_COMMANDS) {
+      expect(executor.isModelInvocable(name), name).toBe(false);
+      expect(await executor.executeModelInvocable(name, host, ''), name).toBeNull();
+    }
+    expect(executed).not.toHaveBeenCalled();
+  });
+
+  it('never offers a user-only subcommand, and refuses it before the command runs', async () => {
+    const { executor, executed } = spiedExecutor();
+    const host = createTestCommandHost();
+    const descriptors = executor.listModelInvocableCommands();
+    for (const [name, subcommands] of Object.entries(USER_ONLY_SUBCOMMANDS)) {
+      const descriptor = descriptors.find((candidate) => candidate.name === name);
+      const offeredBlock = descriptor?.description.split('Subcommands you may run')[1] ?? '';
+      for (const sub of subcommands) {
+        expect(descriptor?.argumentHint ?? '', `${name} ${sub}`).not.toMatch(
+          new RegExp(`(?:^|\\s|\\[|\\|)${sub}(?=\\s|\\]|\\||$)`),
+        );
+        expect(offeredBlock, `${name} ${sub}`).not.toContain(`- ${sub}:`);
+        const result = await executor.executeModelInvocable(name, host, `${sub} some-arg`);
+        expect(result?.success, `${name} ${sub}`).toBe(false);
+      }
+    }
+    expect(executed).not.toHaveBeenCalled();
+  });
+
+  it('runs the read-only subset for the model', async () => {
+    const { executor, executed } = spiedExecutor();
+    const host = createTestCommandHost();
+    for (const [name, args] of [
+      ['mcp', ''],
+      ['mcp', 'status'],
+      ['mcp', 'skill-list docs'],
+      ['memory', 'list'],
+      ['context', ''],
+      ['context', 'list'],
+      ['cost', ''],
+    ] as const) {
+      expect((await executor.executeModelInvocable(name, host, args))?.message).toBe('ran');
+    }
+    expect(executed).toHaveBeenCalledTimes(7);
+  });
+
+  it('skips the by-name prompt only where the model reaches nothing that needs it', () => {
+    const { executor } = spiedExecutor();
+    const byName = Object.fromEntries(
+      executor.listModelInvocableCommands().map((d) => [d.name, d.requiresPermission]),
+    );
+    // `/mcp`: the model reaches only `status`. `/monitor`: its command is decided by the shell
+    // gate instead (monitor-model-permission-functional.test.ts).
+    expect(byName.mcp).toBe(false);
+    expect(byName.monitor).toBe(false);
+    // Neither becomes read-only for the user or a remote read-only policy.
+    for (const name of ['mcp', 'monitor']) {
+      const command = executor.getCommand(name)!;
+      expect(executor.resolveRequiresPermission(command), name).toBe(true);
+    }
+  });
+});