@pellux/goodvibes-agent 1.0.30 → 1.0.33

package/src/tools/agent-harness-connected-host-status.ts

@@ -135,7 +135,7 @@ export async function connectedHostStatusSummary(
     ],
     findings: connectedHostFindings(runtime, tokenUsable),
     modelAccess: {
-      diagnostics: 'Use mode:"connected_host_status" for live read-only host readiness. Use mode:"connected_host" for capability and boundary inventory.',
+      diagnostics: 'Use mode:"connected_host_status" for live read-only host readiness, mode:"service_posture" for endpoint posture, mode:"service_endpoint" for one endpoint, and mode:"connected_host" for capability and boundary inventory.',
       cliMirrors: ['goodvibes-agent status --json', 'goodvibes-agent doctor', 'goodvibes-agent compat'],
       tuiMirrors: ['Agent Workspace -> Home -> Host compatibility', 'Agent Workspace -> Home -> Doctor diagnostics', 'Agent Workspace -> Home -> Review health'],
     },

package/src/tools/agent-harness-delegation-posture.ts

@@ -0,0 +1,216 @@
+import type { CommandContext } from '../input/command-registry.ts';
+
+export interface AgentHarnessDelegationArgs {
+  readonly delegationRouteId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+type DelegationResolution =
+  | { readonly status: 'found'; readonly route: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+type DelegationLookupSource = 'delegationRouteId' | 'target' | 'query';
+
+interface DelegationRoute {
+  readonly id: string;
+  readonly label: string;
+  readonly detail: string;
+  readonly effect: 'read-only' | 'main-conversation' | 'delegated-work' | 'blocked';
+  readonly command?: string;
+  readonly commandTemplate?: string;
+  readonly workspaceActionId?: string;
+  readonly confirmationRequired?: boolean;
+  readonly reviewPolicy?: 'explicit-only' | 'not-applicable';
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function lookupFromArgs(args: AgentHarnessDelegationArgs): { readonly source: DelegationLookupSource; readonly input: string } | null {
+  const delegationRouteId = readString(args.delegationRouteId);
+  if (delegationRouteId) return { source: 'delegationRouteId', input: delegationRouteId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function routes(): readonly DelegationRoute[] {
+  return [
+    {
+      id: 'delegate-build-task',
+      label: 'Delegate build/fix/review task',
+      detail: 'Send one explicit build, fix, implementation, patch, or review task to GoodVibes TUI/shared-session routes with the full original ask.',
+      effect: 'delegated-work',
+      commandTemplate: '/delegate <full original user ask>',
+      workspaceActionId: 'delegate-task',
+      confirmationRequired: true,
+      reviewPolicy: 'explicit-only',
+    },
+    {
+      id: 'delegate-build-task-with-review',
+      label: 'Delegate with requested review',
+      detail: 'Request delegated review only when the user explicitly asks for review or explicitly requests review as part of a build/fix/review handoff.',
+      effect: 'delegated-work',
+      commandTemplate: '/delegate --review <full original user ask>',
+      workspaceActionId: 'delegate-task',
+      confirmationRequired: true,
+      reviewPolicy: 'explicit-only',
+    },
+    {
+      id: 'delegation-status',
+      label: 'Delegation status',
+      detail: 'Inspect build-delegation receipts and shared-session status without starting coding work.',
+      effect: 'read-only',
+      command: '/delegate status',
+      workspaceActionId: 'delegation-status',
+      reviewPolicy: 'not-applicable',
+    },
+    {
+      id: 'ordinary-agent-work',
+      label: 'Ordinary Agent work',
+      detail: 'Planning, research, operations, memory, configuration, approvals, automation observability, media generation, and ordinary assistant work stay in the main Agent conversation or first-class Agent tools.',
+      effect: 'main-conversation',
+      reviewPolicy: 'not-applicable',
+    },
+    {
+      id: 'local-coding-blocked',
+      label: 'Local coding execution blocked in Agent',
+      detail: 'Agent does not own file edits, git/worktree workflows, execution isolation UX, coding panels, or local delegated review chains.',
+      effect: 'blocked',
+      reviewPolicy: 'not-applicable',
+    },
+  ];
+}
+
+function routeSearchText(route: DelegationRoute): string {
+  return [
+    route.id,
+    route.label,
+    route.detail,
+    route.effect,
+    route.command ?? '',
+    route.commandTemplate ?? '',
+    route.workspaceActionId ?? '',
+    route.reviewPolicy ?? '',
+  ].join('\n').toLowerCase();
+}
+
+function describeCandidate(route: DelegationRoute): Record<string, unknown> {
+  return {
+    delegationRouteId: route.id,
+    label: route.label,
+    effect: route.effect,
+    confirmationRequired: route.confirmationRequired === true,
+  };
+}
+
+function describeRoute(
+  context: CommandContext,
+  route: DelegationRoute,
+  options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {},
+): Record<string, unknown> {
+  return {
+    delegationRouteId: route.id,
+    label: route.label,
+    detail: route.detail,
+    effect: route.effect,
+    ...(route.command ? { command: route.command } : {}),
+    ...(route.commandTemplate ? { commandTemplate: route.commandTemplate } : {}),
+    ...(route.workspaceActionId ? { workspaceActionId: route.workspaceActionId } : {}),
+    confirmationRequired: route.confirmationRequired === true,
+    reviewPolicy: route.reviewPolicy ?? 'not-applicable',
+    runtime: {
+      sessionId: context.session.runtime.sessionId,
+      operatorClientAttached: Boolean(context.clients?.operator),
+    },
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    policy: {
+      effect: route.effect,
+      values: 'Delegation posture returns policy, route, confirmation, and runtime availability metadata only; it does not submit delegated work.',
+      mutation: 'Delegated work submission stays a visible confirmed workspace or slash-command flow and must preserve the full original user ask.',
+    },
+    ...(options.includeParameters ? {
+      modelAccess: {
+        inspectDelegation: 'agent_harness mode:"delegation_posture"',
+        inspectRoute: 'agent_harness mode:"delegation_route"',
+        workspaceAction: route.workspaceActionId ? `agent_harness mode:"workspace_action" actionId:"${route.workspaceActionId}"` : null,
+        runWorkspaceAction: route.workspaceActionId ? `agent_harness mode:"run_workspace_action" actionId:"${route.workspaceActionId}" confirm:true explicitUserRequest:"..."` : null,
+        runCommand: route.command ? `agent_harness mode:"run_command" command:"${route.command}" confirm:true explicitUserRequest:"..."` : null,
+        runCommandTemplate: route.commandTemplate ? `agent_harness mode:"run_command" command:"${route.commandTemplate}" confirm:true explicitUserRequest:"..."` : null,
+      },
+    } : {}),
+  };
+}
+
+export function delegationPostureCatalogStatus(context: CommandContext): Record<string, unknown> {
+  return {
+    modes: ['delegation_posture', 'delegation_route'],
+    routes: routes().length,
+    operatorClientAttached: Boolean(context.clients?.operator),
+    readOnly: true,
+  };
+}
+
+export function delegationPostureSummary(context: CommandContext, args: AgentHarnessDelegationArgs): Record<string, unknown> {
+  const query = readString(args.query).toLowerCase();
+  const includeParameters = args.includeParameters === true;
+  const filtered = routes()
+    .filter((route) => !query || routeSearchText(route).includes(query))
+    .slice(0, readLimit(args.limit, 100));
+  return {
+    status: 'available',
+    summary: {
+      routes: routes().length,
+      operatorClientAttached: Boolean(context.clients?.operator),
+      sessionId: context.session.runtime.sessionId,
+      delegatedReviewPolicy: 'explicit-build-delegation-only',
+      normalChatPolicy: 'ordinary assistant work stays in the main Agent conversation',
+      codingOwnership: 'GoodVibes TUI owns file edits, git/worktree workflows, execution isolation UX, coding panels, and delegated review coordination',
+    },
+    routes: filtered.map((route) => describeRoute(context, route, { includeParameters })),
+    returned: filtered.length,
+    total: routes().length,
+    policy: 'Read-only delegation posture. Delegation submission requires an explicit build/fix/review/implementation user request, visible confirmation, and preservation of the full original ask.',
+  };
+}
+
+export function describeHarnessDelegationRoute(context: CommandContext, args: AgentHarnessDelegationArgs): DelegationResolution {
+  const lookup = lookupFromArgs(args);
+  if (!lookup) {
+    return {
+      status: 'missing_lookup',
+      usage: 'delegation_route requires delegationRouteId, target, or query. Use mode:"delegation_posture" to inspect delegation route ids.',
+    };
+  }
+  const all = routes();
+  const normalized = lookup.input.toLowerCase();
+  const exact = all.find((route) => route.id === lookup.input);
+  if (exact) return { status: 'found', route: describeRoute(context, exact, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const insensitive = all.find((route) => route.id.toLowerCase() === normalized);
+  if (insensitive) return { status: 'found', route: describeRoute(context, insensitive, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const searched = all.filter((route) => routeSearchText(route).includes(normalized));
+  if (searched.length === 1) return { status: 'found', route: describeRoute(context, searched[0]!, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 8).map(describeCandidate),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown delegation route ${lookup.input}. Use mode:"delegation_posture" to inspect delegation route ids.`,
+  };
+}

package/src/tools/agent-harness-keybinding-metadata.ts

@@ -53,6 +53,7 @@ interface KeybindingOperationRoute {
 }
 
 type KeybindingsOverrideFile = Record<string, unknown>;
+type KeybindingEntry = { readonly action: KeyAction; readonly description: string; readonly combos: KeyCombo[] };
 
 interface KeybindingLookup {
   readonly source: 'actionId' | 'target' | 'key' | 'query';
@@ -93,6 +94,19 @@ function requireKeybindingsManager(context: CommandContext): KeybindingsManager
   return manager;
 }
 
+function readKeybindingsManager(context: CommandContext): KeybindingsManager | null {
+  return context.workspace.keybindingsManager ?? null;
+}
+
+function defaultKeybindingEntries(): KeybindingEntry[] {
+  return (Object.entries(DEFAULT_KEYBINDINGS) as [KeyAction, KeyCombo[]][])
+    .map(([action, combos]) => ({
+      action,
+      description: ACTION_DESCRIPTIONS[action],
+      combos: combos.map((combo) => ({ ...combo })),
+    }));
+}
+
 function isKeyAction(action: string): action is KeyAction {
   return Object.hasOwn(ACTION_DESCRIPTIONS, action);
 }
@@ -162,13 +176,23 @@ function combosEqual(left: readonly KeyCombo[], right: readonly KeyCombo[]): boo
   return left.every((combo, index) => comboFingerprint(combo) === comboFingerprint(right[index]));
 }
 
-function describeCombo(manager: KeybindingsManager, combo: KeyCombo): Record<string, unknown> {
+function formatCombo(manager: KeybindingsManager | null, combo: KeyCombo): string {
+  if (manager) return manager.formatCombo(combo);
+  const parts: string[] = [];
+  if (combo.ctrl) parts.push('Ctrl');
+  if (combo.alt) parts.push('Alt');
+  if (combo.shift) parts.push('Shift');
+  parts.push(combo.key.length === 1 ? combo.key.toUpperCase() : combo.key);
+  return parts.join('+');
+}
+
+function describeCombo(manager: KeybindingsManager | null, combo: KeyCombo): Record<string, unknown> {
   return {
     key: combo.key,
     ctrl: combo.ctrl === true,
     shift: combo.shift === true,
     alt: combo.alt === true,
-    label: manager.formatCombo(combo),
+    label: formatCombo(manager, combo),
   };
 }
 
@@ -184,33 +208,33 @@ function keybindingLookupFromArgs(args: HarnessKeybindingArgs): { readonly sourc
   return null;
 }
 
-function bindingSearchText(manager: KeybindingsManager, entry: { readonly action: KeyAction; readonly description: string; readonly combos: KeyCombo[] }): string {
+function bindingSearchText(manager: KeybindingsManager | null, entry: KeybindingEntry): string {
   return [
     entry.action,
     entry.description,
     ...entry.combos.map((combo) => comboFingerprint(combo)),
-    ...entry.combos.map((combo) => manager.formatCombo(combo)),
+    ...entry.combos.map((combo) => formatCombo(manager, combo)),
   ].join('\n').toLowerCase();
 }
 
-function bindingCandidate(manager: KeybindingsManager, entry: { readonly action: KeyAction; readonly description: string; readonly combos: KeyCombo[] }): Record<string, unknown> {
+function bindingCandidate(manager: KeybindingsManager | null, entry: KeybindingEntry): Record<string, unknown> {
   return {
     action: entry.action,
     description: entry.description,
-    labels: entry.combos.map((combo) => manager.formatCombo(combo)),
+    labels: entry.combos.map((combo) => formatCombo(manager, combo)),
   };
 }
 
-function bindingMatches(manager: KeybindingsManager, entry: { readonly action: KeyAction; readonly description: string; readonly combos: KeyCombo[] }, query: string): boolean {
+function bindingMatches(manager: KeybindingsManager | null, entry: KeybindingEntry, query: string): boolean {
   if (!query) return true;
   return bindingSearchText(manager, entry).includes(query.toLowerCase());
 }
 
 function resolveHarnessKeybinding(context: CommandContext, args: HarnessKeybindingArgs): KeybindingResolution | null {
-  const manager = requireKeybindingsManager(context);
+  const manager = readKeybindingsManager(context);
   const lookup = keybindingLookupFromArgs(args);
   if (!lookup) return null;
-  const entries = manager.getAll();
+  const entries = manager?.getAll() ?? defaultKeybindingEntries();
   if (isKeyAction(lookup.input)) return { status: 'found', action: lookup.input, lookup: { ...lookup, resolvedBy: 'action' } };
   const inputLower = lookup.input.toLowerCase();
   const ciActions = entries.filter((entry) => entry.action.toLowerCase() === inputLower);
@@ -222,7 +246,7 @@ function resolveHarnessKeybinding(context: CommandContext, args: HarnessKeybindi
   return null;
 }
 
-function describeBinding(manager: KeybindingsManager, action: KeyAction, combos: KeyCombo[], lookup?: KeybindingLookup): Record<string, unknown> {
+function describeBinding(manager: KeybindingsManager | null, action: KeyAction, combos: KeyCombo[], lookup?: KeybindingLookup): Record<string, unknown> {
   const defaults = DEFAULT_KEYBINDINGS[action];
   const customized = !combosEqual(combos, defaults);
   return {
@@ -230,10 +254,10 @@ function describeBinding(manager: KeybindingsManager, action: KeyAction, combos:
     description: ACTION_DESCRIPTIONS[action],
     ...(lookup ? { lookup } : {}),
     bindings: combos.map((combo) => describeCombo(manager, combo)),
-    labels: combos.map((combo) => manager.formatCombo(combo)),
+    labels: combos.map((combo) => formatCombo(manager, combo)),
     defaultBindings: defaults.map((combo) => describeCombo(manager, combo)),
     customized,
-    source: customized ? 'custom' : 'default',
+    source: manager ? (customized ? 'custom' : 'default') : 'default-fallback',
     modelOperation: keybindingOperationRoute(action),
   };
 }
@@ -377,7 +401,7 @@ function writeOverrideFile(configPath: string, overrides: KeybindingsOverrideFil
 }
 
 export function totalHarnessKeybindings(context: CommandContext): number {
-  return context.workspace.keybindingsManager?.getAll().length ?? 0;
+  return context.workspace.keybindingsManager?.getAll().length ?? Object.keys(DEFAULT_KEYBINDINGS).length;
 }
 
 export function totalHarnessShortcuts(context: CommandContext): number {
@@ -391,41 +415,52 @@ export function listHarnessShortcuts(context: CommandContext, args: HarnessKeybi
     .filter((shortcut) => !query || `${shortcut.key}\n${shortcut.description}`.toLowerCase().includes(query))
     .slice(0, readLimit(args.limit, 200))
     .map((shortcut) => ({ ...shortcut, source: 'fixed', userEditable: false }));
+  const degraded = keybindings.status === 'degraded';
   return {
+    status: degraded ? 'degraded' : 'available',
     configPath: keybindings.configPath,
     fixedShortcuts: fixed,
     configurableKeybindings: keybindings.keybindings,
     returned: fixed.length + Number(keybindings.returned ?? 0),
     total: totalHarnessShortcuts(context),
-    policy: 'Fixed shortcuts are runtime/editor controls. Configurable keybindings can be inspected, supported shell-safe actions can be run with run_keybinding, and bindings can be changed with set_keybinding/reset_keybinding.',
+    policy: degraded
+      ? 'Fixed shortcuts and default keybindings are available for discovery. Live keybinding execution and mutation require the runtime keybinding manager.'
+      : 'Fixed shortcuts are runtime/editor controls. Configurable keybindings can be inspected, supported shell-safe actions can be run with run_keybinding, and bindings can be changed with set_keybinding/reset_keybinding.',
   };
 }
 
 export function listHarnessKeybindings(context: CommandContext, args: HarnessKeybindingArgs): Record<string, unknown> {
-  const manager = requireKeybindingsManager(context);
+  const manager = readKeybindingsManager(context);
   const query = readString(args.query);
-  const entries = manager.getAll()
+  const allEntries = manager?.getAll() ?? defaultKeybindingEntries();
+  const entries = allEntries
     .filter((entry) => bindingMatches(manager, entry, query))
     .slice(0, readLimit(args.limit, 200))
     .map((entry) => describeBinding(manager, entry.action, entry.combos));
   return {
-    configPath: manager.getConfigPath(),
+    status: manager ? 'available' : 'degraded',
+    configPath: manager?.getConfigPath() ?? null,
     keybindings: entries,
     returned: entries.length,
-    total: manager.getAll().length,
-    policy: 'Reads the live resolved keybindings, including modelOperation route metadata. run_keybinding executes only supported shell-safe actions. set_keybinding/reset_keybinding write the same keybindings.json file the user can edit and reload the runtime manager.',
+    total: allEntries.length,
+    policy: manager
+      ? 'Reads the live resolved keybindings, including modelOperation route metadata. run_keybinding executes only supported shell-safe actions. set_keybinding/reset_keybinding write the same keybindings.json file the user can edit and reload the runtime manager.'
+      : 'Live keybinding manager is unavailable; default keybindings are shown for discovery only. run_keybinding, set_keybinding, and reset_keybinding require a live manager.',
   };
 }
 
 export function describeHarnessKeybinding(context: CommandContext, args: HarnessKeybindingArgs): Record<string, unknown> | null {
-  const manager = requireKeybindingsManager(context);
+  const manager = readKeybindingsManager(context);
   const resolved = resolveHarnessKeybinding(context, args);
   if (resolved?.status === 'ambiguous') return { status: 'ambiguous', input: resolved.input, candidates: resolved.candidates };
   if (!resolved) return null;
-  const entry = manager.getAll().find((candidate) => candidate.action === resolved.action);
+  const entries = manager?.getAll() ?? defaultKeybindingEntries();
+  const entry = entries.find((candidate) => candidate.action === resolved.action);
   return entry ? {
-    configPath: manager.getConfigPath(),
+    status: manager ? 'available' : 'degraded',
+    configPath: manager?.getConfigPath() ?? null,
     ...describeBinding(manager, entry.action, entry.combos, resolved.lookup),
+    ...(manager ? {} : { note: 'Default keybinding descriptor only; live run/set/reset operations require the runtime keybinding manager.' }),
   } : null;
 }
 

package/src/tools/agent-harness-mcp-metadata.ts

@@ -0,0 +1,246 @@
+import type { CommandContext } from '../input/command-registry.ts';
+
+export interface AgentHarnessMcpArgs {
+  readonly mcpServerId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+type McpServerLookupSource = 'mcpServerId' | 'target' | 'query';
+
+type McpServerResolution =
+  | { readonly status: 'found'; readonly server: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+type McpServerRecord = ReturnType<NonNullable<NonNullable<CommandContext['clients']>['mcpApi']>['listServerSecurity']>[number];
+
+interface McpToolRecord {
+  readonly serverName: string;
+  readonly toolName: string;
+  readonly description?: string;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function resolveMcpApi(context: CommandContext): {
+  readonly listServerSecurity: () => readonly McpServerRecord[];
+  readonly listAllTools?: (() => Promise<readonly McpToolRecord[]>) | undefined;
+} | null {
+  const api = context.clients?.mcpApi ?? context.extensions?.mcpRegistry;
+  if (!api || typeof api.listServerSecurity !== 'function') return null;
+  return {
+    listServerSecurity: () => api.listServerSecurity(),
+    ...(typeof (api as { readonly listAllTools?: unknown }).listAllTools === 'function'
+      ? { listAllTools: () => (api as { listAllTools: () => Promise<readonly McpToolRecord[]> }).listAllTools() }
+      : {}),
+  };
+}
+
+function lookupFromArgs(args: AgentHarnessMcpArgs): { readonly source: McpServerLookupSource; readonly input: string } | null {
+  const mcpServerId = readString(args.mcpServerId);
+  if (mcpServerId) return { source: 'mcpServerId', input: mcpServerId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function serverSearchText(server: McpServerRecord): string {
+  return [
+    server.name,
+    server.connected ? 'connected' : 'disconnected',
+    server.trustMode,
+    server.role,
+    server.schemaFreshness,
+    server.quarantineReason ?? '',
+    server.quarantineDetail ?? '',
+    ...server.allowedHosts,
+  ].join('\n').toLowerCase();
+}
+
+function describeCandidate(server: McpServerRecord): Record<string, unknown> {
+  return {
+    mcpServerId: server.name,
+    connected: server.connected,
+    trustMode: server.trustMode,
+    role: server.role,
+    schemaFreshness: server.schemaFreshness,
+  };
+}
+
+function toolsByServer(tools: readonly McpToolRecord[]): ReadonlyMap<string, readonly McpToolRecord[]> {
+  const grouped = new Map<string, McpToolRecord[]>();
+  for (const tool of tools) {
+    const entries = grouped.get(tool.serverName) ?? [];
+    entries.push(tool);
+    grouped.set(tool.serverName, entries);
+  }
+  return grouped;
+}
+
+function describeServer(
+  server: McpServerRecord,
+  options: {
+    readonly includeParameters?: boolean;
+    readonly tools?: readonly McpToolRecord[];
+    readonly lookup?: Record<string, unknown>;
+  } = {},
+): Record<string, unknown> {
+  const tools = options.tools ?? [];
+  return {
+    name: server.name,
+    connected: server.connected,
+    trustMode: server.trustMode,
+    role: server.role,
+    schemaFreshness: server.schemaFreshness,
+    allowedPathCount: server.allowedPaths.length,
+    allowedHostCount: server.allowedHosts.length,
+    ...(server.quarantineReason ? { quarantineReason: server.quarantineReason } : {}),
+    ...(server.quarantineDetail ? { quarantineDetail: server.quarantineDetail } : {}),
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    ...(options.includeParameters ? {
+      tools: tools.map((tool) => ({
+        name: tool.toolName,
+        ...(tool.description ? { description: tool.description } : {}),
+      })),
+      toolCount: tools.length,
+    } : { toolCount: tools.length }),
+    policy: {
+      effect: 'read-only',
+      values: 'Server posture returns trust, role, connection, quarantine, and tool metadata; env values and secret config values are never returned.',
+      mutation: 'MCP add/remove/reload/trust/role/quarantine operations stay explicit confirmation-gated workspace or slash-command flows.',
+      allowAll: 'allow-all trust decisions remain routed through Settings -> MCP, not direct command escalation.',
+    },
+    modelAccess: {
+      reviewCommand: '/mcp review',
+      serversCommand: '/mcp servers',
+      toolsCommand: `/mcp tools ${server.name}`,
+      repairCommand: `/mcp repair ${server.name}`,
+      authReviewCommand: '/mcp auth-review',
+      configCommand: '/mcp config',
+      workspaceActionIds: [
+        'mcp-review',
+        'mcp-tools-server',
+        'mcp-repair',
+        'mcp-config',
+        'mcp-add-server',
+        'mcp-settings',
+      ],
+      confirmationGatedCommands: [
+        `/mcp trust ${server.name} <constrained|ask-on-risk|blocked> --yes`,
+        `/mcp role ${server.name} <role> --yes`,
+        `/mcp quarantine ${server.name} approve <operatorId> --yes`,
+        `/mcp remove ${server.name} --yes`,
+      ],
+    },
+  };
+}
+
+async function readMcpTools(api: ReturnType<typeof resolveMcpApi>, includeParameters: boolean): Promise<readonly McpToolRecord[]> {
+  if (!includeParameters || !api?.listAllTools) return [];
+  try {
+    return await api.listAllTools();
+  } catch {
+    return [];
+  }
+}
+
+export function mcpServerCatalogStatus(context: CommandContext): Record<string, unknown> {
+  const api = resolveMcpApi(context);
+  if (!api) {
+    return {
+      modes: ['mcp_servers', 'mcp_server'],
+      status: 'unavailable',
+      readOnly: true,
+    };
+  }
+  const servers = api.listServerSecurity();
+  return {
+    modes: ['mcp_servers', 'mcp_server'],
+    servers: servers.length,
+    connected: servers.filter((server) => server.connected).length,
+    attention: servers.filter((server) => !server.connected || server.schemaFreshness === 'quarantined').length,
+    readOnly: true,
+  };
+}
+
+export async function mcpServerSummary(context: CommandContext, args: AgentHarnessMcpArgs): Promise<Record<string, unknown>> {
+  const api = resolveMcpApi(context);
+  if (!api) {
+    return {
+      status: 'unavailable',
+      servers: [],
+      returned: 0,
+      total: 0,
+      policy: 'MCP runtime API is unavailable in this Agent context.',
+    };
+  }
+  const query = readString(args.query).toLowerCase();
+  const includeParameters = args.includeParameters === true;
+  const servers = api.listServerSecurity();
+  const tools = toolsByServer(await readMcpTools(api, includeParameters));
+  const filtered = servers
+    .filter((server) => !query || serverSearchText(server).includes(query))
+    .slice(0, readLimit(args.limit, 100));
+  return {
+    servers: filtered.map((server) => describeServer(server, {
+      includeParameters,
+      tools: tools.get(server.name) ?? [],
+    })),
+    returned: filtered.length,
+    total: servers.length,
+    connected: servers.filter((server) => server.connected).length,
+    attention: servers.filter((server) => !server.connected || server.schemaFreshness === 'quarantined').length,
+    policy: 'Read-only MCP server posture. Use confirmed workspace actions or slash-command mirrors for add/remove/reload/trust/role/quarantine mutations.',
+  };
+}
+
+export async function describeHarnessMcpServer(context: CommandContext, args: AgentHarnessMcpArgs): Promise<McpServerResolution> {
+  const lookup = lookupFromArgs(args);
+  if (!lookup) {
+    return {
+      status: 'missing_lookup',
+      usage: 'mcp_server requires mcpServerId, target, or query. Use mode:"mcp_servers" to inspect MCP server ids.',
+    };
+  }
+  const api = resolveMcpApi(context);
+  if (!api) {
+    return {
+      status: 'missing_lookup',
+      usage: 'MCP runtime API is unavailable in this Agent context.',
+    };
+  }
+  const servers = api.listServerSecurity();
+  const normalized = lookup.input.toLowerCase();
+  const exact = servers.find((server) => server.name === lookup.input);
+  const tools = toolsByServer(await readMcpTools(api, true));
+  if (exact) return { status: 'found', server: describeServer(exact, { includeParameters: true, tools: tools.get(exact.name) ?? [], lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const insensitive = servers.find((server) => server.name.toLowerCase() === normalized);
+  if (insensitive) return { status: 'found', server: describeServer(insensitive, { includeParameters: true, tools: tools.get(insensitive.name) ?? [], lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const searched = servers.filter((server) => serverSearchText(server).includes(normalized));
+  if (searched.length === 1) {
+    return { status: 'found', server: describeServer(searched[0]!, { includeParameters: true, tools: tools.get(searched[0]!.name) ?? [], lookup: { ...lookup, resolvedBy: 'search' } }) };
+  }
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 8).map(describeCandidate),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown MCP server ${lookup.input}. Use mode:"mcp_servers" to inspect MCP server ids.`,
+  };
+}