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

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

@@ -1,37 +1,68 @@
 import { executeContextCommand } from './context-command.js';
+import { createSystemCommandFromEntry } from '../command-module-utils.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 createContextCommandEntry(): ICommand {
   return {
     name: 'context',
     displayName: 'Context References',
     description: 'Context window info, reference inventory, and auto-compact controls',
+    // Model-invocable for the read-only views only: knowing how full the context is lets the model
+    // decide when to compact. Pinning, unpinning and clearing references and the auto-compact
+    // policy are the user's curation and preference, so they stay user-only.
+    modelDescription:
+      '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.',
     source: 'context',
-    modelInvocable: false,
+    modelInvocable: true,
+    userInvocable: true,
     argumentHint: 'list | add <path> | remove <path> | clear | auto ...',
     subcommands: [
-      { name: 'list', description: 'List loaded context references', source: 'context' },
-      { name: 'add', description: 'Add a file to active context references', source: 'context' },
-      { name: 'remove', description: 'Remove a context reference', source: 'context' },
-      { name: 'clear', description: 'Clear context references', source: 'context' },
-      { name: 'auto', description: 'Inspect or change auto-compact policy', source: 'context' },
+      {
+        name: 'list',
+        description: 'List loaded context references',
+        source: 'context',
+        modelInvocable: true,
+      },
+      {
+        name: 'add',
+        description: 'Add a file to active context references',
+        source: 'context',
+        modelInvocable: false,
+      },
+      {
+        name: 'remove',
+        description: 'Remove a context reference',
+        source: 'context',
+        modelInvocable: false,
+      },
+      {
+        name: 'clear',
+        description: 'Clear context references',
+        source: 'context',
+        modelInvocable: false,
+      },
+      {
+        name: 'auto',
+        description: 'Inspect or change auto-compact policy',
+        source: 'context',
+        modelInvocable: false,
+      },
     ],
   };
 }
 
 function createContextSystemCommand(): ISystemCommand {
   const entry = createContextCommandEntry();
-  return {
-    name: entry.name,
-    displayName: entry.displayName,
-    description: entry.description,
+  return createSystemCommandFromEntry(entry, {
     requiresPermission: false,
-    userInvocable: true,
-    modelInvocable: false,
+    lifecycle: 'inline',
     execute: executeContextCommand,
-  };
+  });
 }
 
 export class ContextCommandSource implements ICommandSource {

package/src/context/context-command.ts

@@ -1,4 +1,3 @@
-import { CONTEXT_ESTIMATE_CHARS_PER_TOKEN } from '@robota-sdk/agent-core';
 import {
   addCommandContextReference,
   clearCommandContextReferences,
@@ -13,13 +12,26 @@ import {
   writeAutoCompactThresholdSetting,
 } from '@robota-sdk/agent-framework';
 
-import type { IHistoryEntry, TUniversalMessage } from '@robota-sdk/agent-core';
+import {
+  buildToolDisplayList,
+  formatContextReferenceLine,
+  formatFullContextBreakdown,
+} from './context-breakdown.js';
+
 import type {
-  ICommandHostContext,
+  ICommandHostAdapterAccess,
+  ICommandHostContextReferences,
+  ICommandHostContextWindow,
+  ICommandHostSessionAccess,
   TAutoCompactThreshold,
   TAutoCompactThresholdSource,
 } from '@robota-sdk/agent-framework';
-import type { ICommandResult, IContextReferenceItem } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IContextReferenceItem } from '@robota-sdk/agent-interface-session';
+
+import { formatAutoCompactLine, formatThreshold } from './auto-compact-format.js';
+
+export { formatAutoCompactLine } from './auto-compact-format.js';
 
 const PERCENT = 100;
 const USAGE = [
@@ -27,29 +39,23 @@ const USAGE = [
   'Examples: /context list, /context add AGENTS.md, /context remove AGENTS.md, /context auto 85%',
 ].join('\n');
 
-function formatThreshold(threshold: TAutoCompactThreshold): string {
-  if (threshold === false) {
-    return 'disabled';
-  }
-  return `${Math.round(threshold * PERCENT)}%`;
-}
-
-function formatAutoCompactLine(
-  threshold: TAutoCompactThreshold,
-  source: TAutoCompactThresholdSource,
-): string {
-  if (threshold === false) {
-    return `Auto compact: disabled (${source})`;
-  }
-  return `Auto compact: ${formatThreshold(threshold)} (${source})`;
-}
-
 function formatPersistenceSuffix(persisted: boolean): string {
   return persisted ? 'settings' : 'current session only';
 }
 
+/** The roles the `/context` surface reads. Named once so five signatures do not restate it. */
+type TContextCommandHost = ICommandHostAdapterAccess &
+  ICommandHostContextReferences &
+  ICommandHostContextWindow &
+  ICommandHostSessionAccess;
+
+/** The subset the threshold operations need — no context-reference role. */
+type TContextThresholdHost = ICommandHostAdapterAccess &
+  ICommandHostContextWindow &
+  ICommandHostSessionAccess;
+
 export async function executeContextCommand(
-  context: ICommandHostContext,
+  context: TContextCommandHost,
   args: string,
 ): Promise<ICommandResult> {
   const parts = args
@@ -87,7 +93,7 @@ export async function executeContextCommand(
 }
 
 async function executeContextSubcommand(
-  context: ICommandHostContext,
+  context: TContextCommandHost,
   parts: readonly string[],
 ): Promise<ICommandResult> {
   const [subcommand, ...rest] = parts;
@@ -117,7 +123,7 @@ async function executeContextSubcommand(
 }
 
 function executeAutoContextSubcommand(
-  context: ICommandHostContext,
+  context: TContextThresholdHost,
   parts: readonly string[],
 ): ICommandResult {
   const [action, extra] = parts;
@@ -160,7 +166,7 @@ function executeAutoContextSubcommand(
 }
 
 async function executeAddContextReference(
-  context: ICommandHostContext,
+  context: ICommandHostContextReferences,
   args: readonly string[],
 ): Promise<ICommandResult> {
   const path = args.join(' ').trim();
@@ -188,7 +194,7 @@ async function executeAddContextReference(
 }
 
 function executeRemoveContextReference(
-  context: ICommandHostContext,
+  context: ICommandHostContextReferences,
   args: readonly string[],
 ): ICommandResult {
   const path = args.join(' ').trim();
@@ -210,7 +216,7 @@ function executeRemoveContextReference(
 }
 
 function applyAutoCompactThreshold(
-  context: ICommandHostContext,
+  context: TContextThresholdHost,
   threshold: TAutoCompactThreshold,
   action: 'enabled' | 'disabled' | 'threshold set',
 ): ICommandResult {
@@ -245,8 +251,7 @@ function formatApplyMessage(
 }
 
 type TParseThresholdResult =
-  | { success: true; threshold: number }
-  | { success: false; message: string };
+  { success: true; threshold: number } | { success: false; message: string };
 
 function parseThreshold(raw: string): TParseThresholdResult {
   if (raw.endsWith('%')) {
@@ -284,231 +289,3 @@ function formatContextReferenceSummary(references: readonly IContextReferenceIte
 }
 
 // 1 token ≈ 4 chars — sourced from the agent-core estimation SSOT.
-const TOOL_ARG_MAX_LEN = 60;
-
-function estimateTokens(charLength: number): number {
-  return Math.ceil(charLength / CONTEXT_ESTIMATE_CHARS_PER_TOKEN);
-}
-
-function formatContextReferenceLine(reference: IContextReferenceItem): string {
-  return [
-    reference.relativePath,
-    `[${reference.loadType}, ${reference.status}]`,
-    `~${estimateTokens(reference.byteLength).toLocaleString()} tokens`,
-  ].join(' ');
-}
-
-// ── History analysis ────────────────────────────────────────────────────────
-
-interface IToolResultSummary {
-  toolName: string;
-  displayArg: string;
-}
-
-interface IMessageTokensByRole {
-  systemTokens: number;
-  userTokens: number;
-  userCount: number;
-  assistantTokens: number;
-  assistantCount: number;
-  toolTokens: number;
-  toolCallCount: number;
-  totalTokens: number;
-}
-
-interface IToolDisplayList {
-  turnCount: number;
-  toolResults: IToolResultSummary[];
-  totalToolCallCount: number;
-}
-
-function parseToolCallArgs(argsJson: string): Record<string, unknown> | null {
-  try {
-    return JSON.parse(argsJson) as Record<string, unknown>;
-  } catch {
-    // allow-fallback: tool call arguments JSON may be malformed; display-only degradation, not a terminal path
-    return null;
-  }
-}
-
-function extractFirstToolArg(argsJson: string): string {
-  const parsed = parseToolCallArgs(argsJson);
-  if (parsed === null) return '';
-  const first = Object.values(parsed)[0];
-  const raw = typeof first === 'string' ? first : JSON.stringify(first);
-  return raw.length > TOOL_ARG_MAX_LEN ? `${raw.slice(0, TOOL_ARG_MAX_LEN)}…` : raw;
-}
-
-function computeMessageTokensByRole(rawMessages: TUniversalMessage[]): IMessageTokensByRole {
-  let systemTokens = 0;
-  let userTokens = 0;
-  let userCount = 0;
-  let assistantTokens = 0;
-  let assistantCount = 0;
-  let toolTokens = 0;
-  let toolCallCount = 0;
-
-  for (const msg of rawMessages) {
-    const t = Math.ceil(JSON.stringify(msg).length / CONTEXT_ESTIMATE_CHARS_PER_TOKEN);
-    if (msg.role === 'system') {
-      systemTokens += t;
-    } else if (msg.role === 'user') {
-      userTokens += t;
-      userCount++;
-    } else if (msg.role === 'assistant') {
-      assistantTokens += t;
-      assistantCount++;
-    } else if (msg.role === 'tool') {
-      toolTokens += t;
-      toolCallCount++;
-    }
-  }
-
-  return {
-    systemTokens,
-    userTokens,
-    userCount,
-    assistantTokens,
-    assistantCount,
-    toolTokens,
-    toolCallCount,
-    totalTokens: systemTokens + userTokens + assistantTokens + toolTokens,
-  };
-}
-
-function buildToolDisplayList(history: IHistoryEntry[]): IToolDisplayList {
-  type TToolCallEntry = { name: string; firstArg: string };
-  const toolCallMap = new Map<string, TToolCallEntry>();
-
-  for (const entry of history) {
-    if (entry.category !== 'chat' || entry.type !== 'assistant') continue;
-    const data = entry.data as {
-      toolCalls?: Array<{ id: string; function: { name: string; arguments: string } }>;
-    };
-    for (const tc of data.toolCalls ?? []) {
-      toolCallMap.set(tc.id, {
-        name: tc.function.name,
-        firstArg: extractFirstToolArg(tc.function.arguments),
-      });
-    }
-  }
-
-  let turnCount = 0;
-  let totalToolCallCount = 0;
-  const toolDisplayMap = new Map<string, IToolResultSummary>();
-
-  for (const entry of history) {
-    if (entry.category !== 'chat') continue;
-    if (entry.type === 'user') {
-      turnCount++;
-    } else if (entry.type === 'tool') {
-      const data = entry.data as { toolCallId?: string };
-      const tc = toolCallMap.get(data.toolCallId ?? '');
-      const toolName = tc?.name ?? 'tool';
-      const displayArg = tc?.firstArg ?? '';
-      totalToolCallCount++;
-      toolDisplayMap.set(`${toolName}:${displayArg}`, { toolName, displayArg });
-    }
-  }
-
-  return {
-    turnCount,
-    toolResults: [...toolDisplayMap.values()],
-    totalToolCallCount,
-  };
-}
-
-// ── Full context breakdown (for /context list) ──────────────────────────────
-
-function formatSection(title: string, tokens: number, lines: string[]): string {
-  const tokenLabel = tokens > 0 ? ` — ~${tokens.toLocaleString()} tokens` : '';
-  const header = `${title}${tokenLabel}:`;
-  return lines.length === 0
-    ? `${header}\n  (none)`
-    : [header, ...lines.map((l) => `  ${l}`)].join('\n');
-}
-
-function formatFullContextBreakdown(context: ICommandHostContext): ICommandResult {
-  const state = readCommandContextState(context);
-  const autoCompactThreshold = readAutoCompactThreshold(context);
-  const autoCompactThresholdSource = readAutoCompactThresholdSource(context);
-  const rawMessages = context.getSession().getHistory();
-  const msgTokens = computeMessageTokensByRole(rawMessages);
-  const display = buildToolDisplayList(context.getSession().getFullHistory());
-  const references = listCommandContextReferences(context);
-
-  const systemRefs = references.filter((r) => r.loadType === 'system');
-  const manualRefs = references.filter((r) => r.loadType === 'manual');
-  const promptRefs = references.filter((r) => r.loadType === 'prompt-reference');
-
-  const systemRefTokens = systemRefs.reduce((s, r) => s + estimateTokens(r.byteLength), 0);
-  const manualTokens = manualRefs.reduce((s, r) => s + estimateTokens(r.byteLength), 0);
-  const promptRefTokens = promptRefs.reduce((s, r) => s + estimateTokens(r.byteLength), 0);
-
-  const convTurnLabel =
-    display.turnCount === 0
-      ? 'Conversation history — 0 turns'
-      : `Conversation history — ${display.turnCount} turn${display.turnCount !== 1 ? 's' : ''} | ~${msgTokens.totalTokens.toLocaleString()} tokens`;
-
-  const toolResultLines = display.toolResults.map(
-    (t) => `${t.toolName}${t.displayArg ? `: ${t.displayArg}` : ''}`,
-  );
-
-  const uniqueToolCount = display.toolResults.length;
-  const totalToolCallCount = display.totalToolCallCount;
-  const toolResultsLabel =
-    totalToolCallCount === 0
-      ? 'Tool results (0): (none)'
-      : uniqueToolCount < totalToolCallCount
-        ? `Tool results (${uniqueToolCount} unique / ${totalToolCallCount} calls, ~${msgTokens.toolTokens.toLocaleString()} tokens):`
-        : `Tool results (${uniqueToolCount}, ~${msgTokens.toolTokens.toLocaleString()} tokens):`;
-
-  const conversationLines: string[] =
-    display.turnCount === 0
-      ? []
-      : [
-          `User (${msgTokens.userCount}): ~${msgTokens.userTokens.toLocaleString()} tokens`,
-          `Assistant (${msgTokens.assistantCount}): ~${msgTokens.assistantTokens.toLocaleString()} tokens`,
-          ...(msgTokens.systemTokens > 0
-            ? [`System messages: ~${msgTokens.systemTokens.toLocaleString()} tokens`]
-            : []),
-          totalToolCallCount > 0
-            ? [toolResultsLabel, ...toolResultLines.map((l) => `  ${l}`)].join('\n')
-            : toolResultsLabel,
-        ];
-
-  const convSection =
-    display.turnCount === 0
-      ? `${convTurnLabel}:\n  (none)`
-      : [`${convTurnLabel}:`, ...conversationLines.map((l) => `  ${l}`)].join('\n');
-
-  const message = [
-    `Context: ${state.usedTokens.toLocaleString()} / ${state.maxTokens.toLocaleString()} tokens (${Math.round(state.usedPercentage)}%)`,
-    formatAutoCompactLine(autoCompactThreshold, autoCompactThresholdSource),
-    '',
-    formatSection(
-      'System prompt (active every turn)',
-      systemRefTokens,
-      systemRefs.map(formatContextReferenceLine),
-    ),
-    '',
-    convSection,
-    '',
-    formatSection('Manually added', manualTokens, manualRefs.map(formatContextReferenceLine)),
-    '',
-    formatSection(
-      'Prompt references (@-syntax)',
-      promptRefTokens,
-      promptRefs.map(formatContextReferenceLine),
-    ),
-  ].join('\n');
-
-  return {
-    success: true,
-    message,
-    data: {
-      references,
-      history: { turnCount: display.turnCount, toolResults: display.toolResults },
-    },
-  };
-}

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

@@ -0,0 +1,110 @@
+// 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 (bare or prompt only: each iteration chooses its next delay or stops). Use it when the user asks for recurring work in this session. \`list\` shows active loops; \`stop <id>\` ends one. Returns the loop id and its next fire time, or the loop list.",
+    "kind": "builtin-command",
+    "modelInvocable": true,
+    "name": "loop",
+    "requiresPermission": true,
+    "userInvocable": true,
+  },
+  "mcp": {
+    "argumentHint": "[status]",
+    "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. You cannot approve, 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",
+    "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. 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>\`.
+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,
+  },
+  "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

@@ -26,10 +26,10 @@ const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
   writeTargetSettings: () => undefined,
 };
 
-const baseOptions = { cwd: '/tmp', providerDefinitions, providerSettingsAdapter } as const;
+const baseOptions = { cwd: '/tmp', userLocalStorageRoot: '/tmp/robota-test', providerDefinitions, providerSettingsAdapter } as const;
 
 function moduleNames(opts: Parameters<typeof createDefaultCommandModules>[0]): string[] {
-  return createDefaultCommandModules(opts).map((module) => module.name);
+  return createDefaultCommandModules(opts).modules.map((module) => module.name);
 }
 
 describe('createDefaultCommandModules — PRESET-004 module-selection delta', () => {
@@ -40,21 +40,34 @@ describe('createDefaultCommandModules — PRESET-004 module-selection delta', ()
 
   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 24 modules.
-    expect(names).toHaveLength(24);
+    // 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). 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(35);
     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-memory',
+      'agent-command-mcp-activation',
       'agent-command-user-local',
       'agent-command-compact',
       'agent-command-context',
@@ -66,6 +79,9 @@ describe('createDefaultCommandModules — PRESET-004 module-selection delta', ()
       'agent-command-statusline',
       'agent-command-plugin',
       'agent-command-settings',
+      'agent-command-peers',
+      'agent-command-handoff',
+      'agent-command-remote-control',
       'agent-command-provider',
     ]);
   });
@@ -76,6 +92,16 @@ describe('createDefaultCommandModules — PRESET-004 module-selection delta', ()
     expect(names).toHaveLength(2);
   });
 
+  it('BEHAVIOR-2003: registers /keybindings only when the file capability is injected', () => {
+    expect(moduleNames(baseOptions)).not.toContain('agent-command-keybindings');
+    expect(
+      moduleNames({
+        ...baseOptions,
+        keybindingsFilePort: { ensureFile: async () => '/tmp/keybindings.json' },
+      }),
+    ).toContain('agent-command-keybindings');
+  });
+
   it('TC-02: disabledCommandModules blacklist removes the named module', () => {
     const full = moduleNames(baseOptions);
     const names = moduleNames({ ...baseOptions, disabledCommandModules: [BACKGROUND] });
@@ -93,8 +119,34 @@ describe('createDefaultCommandModules — PRESET-004 module-selection delta', ()
     expect(names).not.toContain(AGENT);
   });
 
-  it('whitelist with an unknown name simply yields no module for it', () => {
-    const names = moduleNames({ ...baseOptions, enabledCommandModules: [HELP, 'does-not-exist'] });
-    expect(names).toEqual([HELP]);
+  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([]);
   });
 });