@pellux/goodvibes-agent 1.0.0 → 1.0.2

package/src/cli/local-library-command.ts

@@ -33,6 +33,20 @@ interface ParsedOptions {
   readonly positionals: readonly string[];
 }
 
+const LOCAL_LIBRARY_VALUE_OPTIONS = [
+  'name',
+  'description',
+  'body',
+  'procedure',
+  'tags',
+  'triggers',
+  'requires-env',
+  'requires-command',
+  'requires-commands',
+  'skills',
+  'provenance',
+] as const;
+
 function jsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
   return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
 }
@@ -50,24 +64,30 @@ function failure(runtime: CliCommandRuntime, kind: string, error: string, exitCo
   };
 }
 
-function parseOptions(args: readonly string[]): ParsedOptions {
+function parseOptions(args: readonly string[], valueOptions: readonly string[] = LOCAL_LIBRARY_VALUE_OPTIONS): ParsedOptions {
+  const valued = new Set(valueOptions);
   const values = new Map<string, string>();
   const flags = new Set<string>();
   const positionals: string[] = [];
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index] ?? '';
+    if (arg === '--') {
+      positionals.push(...args.slice(index + 1));
+      break;
+    }
     if (!arg.startsWith('--')) {
       positionals.push(arg);
       continue;
     }
-    const equalIndex = arg.indexOf('=');
+    const raw = arg.slice(2);
+    const equalIndex = raw.indexOf('=');
     if (equalIndex >= 0) {
-      values.set(arg.slice(2, equalIndex), arg.slice(equalIndex + 1));
+      values.set(raw.slice(0, equalIndex), raw.slice(equalIndex + 1));
       continue;
     }
-    const name = arg.slice(2);
+    const name = raw;
     const next = args[index + 1];
-    if (next !== undefined && !next.startsWith('--')) {
+    if (next !== undefined && (valued.has(name) || !next.startsWith('--'))) {
       values.set(name, next);
       index += 1;
       continue;

package/src/cli/routines-command.ts

@@ -43,6 +43,7 @@ interface ParsedRoutineOptions {
 }
 
 const ROUTINE_CREATE_USAGE = 'Usage: goodvibes-agent routines create --name <name> --description <summary> --steps <steps> [--tags a,b] [--triggers a,b] [--requires-env A,B] [--requires-command gh,jq] [--enabled]';
+const ROUTINE_VALUE_OPTIONS = ['name', 'description', 'steps', 'tags', 'triggers', 'requires-env', 'requires-command', 'requires-commands'] as const;
 
 function jsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
   return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
@@ -83,19 +84,30 @@ function splitList(value: string | undefined): readonly string[] {
 }
 
 function parseRoutineOptions(args: readonly string[]): ParsedRoutineOptions {
+  const valued: ReadonlySet<string> = new Set(ROUTINE_VALUE_OPTIONS);
   const flags = new Map<string, string>();
   const positionals: string[] = [];
   let yes = false;
   for (let index = 0; index < args.length; index += 1) {
     const token = args[index] ?? '';
+    if (token === '--') {
+      positionals.push(...args.slice(index + 1));
+      break;
+    }
     if (token === '--yes') {
       yes = true;
       continue;
     }
-    if (token.startsWith('--')) {
-      const key = token.slice(2);
+    if (token.startsWith('--') && token.length > 2) {
+      const raw = token.slice(2);
+      const equalIndex = raw.indexOf('=');
+      if (equalIndex >= 0) {
+        flags.set(raw.slice(0, equalIndex), raw.slice(equalIndex + 1));
+        continue;
+      }
+      const key = raw;
       const next = args[index + 1];
-      if (next !== undefined && !next.startsWith('--')) {
+      if (next !== undefined && (valued.has(key) || !next.startsWith('--'))) {
         flags.set(key, next);
         index += 1;
       } else {

package/src/config/agent-settings-policy.ts

@@ -0,0 +1,44 @@
+export const AGENT_EXTERNAL_HOST_SETTING_LOCK_REASON = 'GoodVibes Agent uses a connected GoodVibes host. Change host lifecycle and bind posture from the owning host; Agent settings are read-only for those controls.';
+
+const AGENT_HIDDEN_SETTING_PREFIXES = [
+  ['cloud', 'flare.'].join(''),
+  ['surfaces.', 'home', 'assistant.'].join(''),
+  'batch.',
+  'controlPlane.',
+  'danger.',
+  'httpListener.',
+  'network.',
+  'orchestration.',
+  'runtime.',
+  'service.',
+  'sandbox.',
+  'web.',
+  'watchers.',
+  'wrfc.',
+] as const;
+
+const AGENT_HIDDEN_SETTING_KEYS = new Set<string>([
+  'ui.wrfcMessages',
+]);
+
+const EXTERNAL_HOST_SETTING_PREFIXES = [
+  'service.',
+  'controlPlane.',
+  'httpListener.',
+  'web.',
+] as const;
+
+const EXTERNAL_HOST_SETTING_KEYS = new Set<string>([
+  'danger.daemon',
+  'danger.httpListener',
+]);
+
+export function isExternalHostOwnedSettingKey(key: string): boolean {
+  return EXTERNAL_HOST_SETTING_KEYS.has(key)
+    || EXTERNAL_HOST_SETTING_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+
+export function isAgentHiddenSettingKey(key: string): boolean {
+  return AGENT_HIDDEN_SETTING_KEYS.has(key)
+    || AGENT_HIDDEN_SETTING_PREFIXES.some((prefix) => key.startsWith(prefix));
+}

package/src/input/agent-workspace-activation.ts

@@ -9,12 +9,14 @@ import type {
   AgentWorkspaceActionResult,
   AgentWorkspaceCategory,
   AgentWorkspaceCommandDispatcher,
+  AgentWorkspaceEditorKind,
   AgentWorkspaceFocusPane,
   AgentWorkspaceLocalEditor,
   AgentWorkspaceLocalEditorKind,
   AgentWorkspaceLocalLibraryItem,
   AgentWorkspaceLocalOperation,
   AgentWorkspaceRuntimeSnapshot,
+  AgentWorkspaceRuntimeStarterTemplateItem,
 } from './agent-workspace-types.ts';
 
 interface AgentWorkspaceActivationHost {
@@ -55,7 +57,10 @@ export function activateAgentWorkspaceSelection(
   const action = workspace.selectedAction;
   if (!action) return;
   if (action.kind === 'editor' && action.editorKind) {
-    const editor = createWorkspaceEditor(workspace, action.editorKind);
+    const editor = createAgentWorkspaceEditor(action.editorKind, {
+      runtimeStarterTemplates: workspace.runtimeSnapshot?.runtimeStarterTemplates ?? [],
+      selectedRoutine: workspace.selectedLocalLibraryItem('routine'),
+    });
     if (!editor) {
       workspace.status = `Editor unavailable: ${action.editorKind}.`;
       workspace.lastActionResult = {
@@ -143,11 +148,14 @@ export function activateAgentWorkspaceSelection(
   workspace.dispatchWorkspaceCommand(action.command);
 }
 
-function createWorkspaceEditor(
-  workspace: AgentWorkspaceActivationHost,
-  editorKind: NonNullable<AgentWorkspaceCategory['actions'][number]['editorKind']>,
+export function createAgentWorkspaceEditor(
+  editorKind: AgentWorkspaceEditorKind,
+  options: {
+    readonly runtimeStarterTemplates?: readonly AgentWorkspaceRuntimeStarterTemplateItem[];
+    readonly selectedRoutine?: AgentWorkspaceLocalLibraryItem | null;
+  } = {},
 ): AgentWorkspaceLocalEditor | null {
-  if (editorKind === 'profile') return createProfileEditor(workspace.runtimeSnapshot?.runtimeStarterTemplates ?? []);
+  if (editorKind === 'profile') return createProfileEditor(options.runtimeStarterTemplates ?? []);
   if (editorKind === 'learned-behavior') return createLearnedBehaviorEditor();
   if (editorKind === 'web-research') return createAgentWorkspaceWebResearchEditor('research');
   if (editorKind === 'web-fetch') return createAgentWorkspaceWebResearchEditor('fetch');
@@ -155,7 +163,7 @@ function createWorkspaceEditor(
   if (editorKind === 'knowledge-ask') return createAgentKnowledgeQueryEditor('ask');
   if (editorKind === 'knowledge-search') return createAgentKnowledgeQueryEditor('search');
   if (editorKind === 'reminder-schedule') return createReminderScheduleEditor();
-  if (editorKind === 'routine-schedule') return createRoutineScheduleEditor(workspace.selectedLocalLibraryItem('routine'));
+  if (editorKind === 'routine-schedule') return createRoutineScheduleEditor(options.selectedRoutine ?? null);
   if (
     editorKind === 'memory'
     || editorKind === 'note'

package/src/input/agent-workspace-knowledge-url-editor.ts

@@ -1,5 +1,6 @@
 import type { AgentWorkspaceActionResult, AgentWorkspaceLocalEditor } from './agent-workspace-types.ts';
 import { isAffirmative, splitList } from './agent-workspace-editors.ts';
+import { quoteSlashCommandArg } from './slash-command-parser.ts';
 
 type AgentWorkspaceFieldReader = (fieldId: string) => string;
 
@@ -65,18 +66,10 @@ export function buildAgentKnowledgeUrlEditorSubmission(
   }
 
   const folder = readField('folder');
-  if (/\s/.test(folder)) {
-    return {
-      kind: 'editor',
-      editor: { ...editor, message: 'Folder paths with spaces are not supported from this compact workspace form.' },
-      status: 'Folder path contains spaces.',
-    };
-  }
-
   const tags = splitList(readField('tags'));
-  const parts = ['/knowledge', 'ingest-url', url];
-  if (tags.length > 0) parts.push('--tags', tags.join(','));
-  if (folder.length > 0) parts.push('--folder', folder);
+  const parts = ['/knowledge', 'ingest-url', quoteSlashCommandArg(url)];
+  if (tags.length > 0) parts.push('--tags', quoteSlashCommandArg(tags.join(',')));
+  if (folder.length > 0) parts.push('--folder', quoteSlashCommandArg(folder));
   parts.push('--yes');
   const command = parts.join(' ');
 

package/src/input/commands/agent-local-library-args.ts

@@ -0,0 +1,52 @@
+export interface ParsedAgentLocalLibraryArgs {
+  readonly rest: readonly string[];
+  readonly flags: ReadonlyMap<string, string>;
+  readonly yes: boolean;
+}
+
+export interface AgentLocalLibraryArgOptions {
+  readonly valueFlags: readonly string[];
+}
+
+export function parseAgentLocalLibraryArgs(
+  args: readonly string[],
+  options: AgentLocalLibraryArgOptions,
+): ParsedAgentLocalLibraryArgs {
+  const valueFlags = new Set(options.valueFlags);
+  const flags = new Map<string, string>();
+  const rest: string[] = [];
+  let yes = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index] ?? '';
+    if (token === '--') {
+      rest.push(...args.slice(index + 1));
+      break;
+    }
+    if (token === '--yes') {
+      yes = true;
+      continue;
+    }
+    if (token.startsWith('--') && token.length > 2) {
+      const raw = token.slice(2);
+      const equalIndex = raw.indexOf('=');
+      if (equalIndex >= 0) {
+        flags.set(raw.slice(0, equalIndex), raw.slice(equalIndex + 1));
+        continue;
+      }
+      if (valueFlags.has(raw)) {
+        const next = args[index + 1];
+        if (next !== undefined) {
+          flags.set(raw, next);
+          index += 1;
+        } else {
+          flags.set(raw, '');
+        }
+        continue;
+      }
+      flags.set(raw, 'true');
+      continue;
+    }
+    rest.push(token);
+  }
+  return { rest, flags, yes };
+}

package/src/input/commands/agent-skills-runtime.ts

@@ -10,38 +10,13 @@ import {
 import { discoverSkills, type SkillRecord } from '../../agent/skill-discovery.ts';
 import { formatAgentRecordOrigin, formatAgentRecordReviewState } from '../../agent/record-labels.ts';
 import type { CommandContext, CommandRegistry } from '../command-registry.ts';
+import { parseAgentLocalLibraryArgs, type ParsedAgentLocalLibraryArgs } from './agent-local-library-args.ts';
 import { requireShellPaths } from './runtime-services.ts';
 
-interface ParsedSkillArgs {
-  readonly rest: readonly string[];
-  readonly flags: ReadonlyMap<string, string>;
-  readonly yes: boolean;
-}
+const SKILL_VALUE_FLAGS = ['name', 'description', 'procedure', 'tags', 'triggers', 'requires-env', 'requires-command', 'requires-commands', 'skills'] as const;
 
-function parseSkillArgs(args: readonly string[]): ParsedSkillArgs {
-  const flags = new Map<string, string>();
-  const rest: string[] = [];
-  let yes = false;
-  for (let index = 0; index < args.length; index += 1) {
-    const token = args[index] ?? '';
-    if (token === '--yes') {
-      yes = true;
-      continue;
-    }
-    if (token.startsWith('--')) {
-      const key = token.slice(2);
-      const next = args[index + 1];
-      if (next !== undefined && !next.startsWith('--')) {
-        flags.set(key, next);
-        index += 1;
-      } else {
-        flags.set(key, 'true');
-      }
-      continue;
-    }
-    rest.push(token);
-  }
-  return { rest, flags, yes };
+function parseSkillArgs(args: readonly string[]): ParsedAgentLocalLibraryArgs {
+  return parseAgentLocalLibraryArgs(args, { valueFlags: SKILL_VALUE_FLAGS });
 }
 
 function splitList(value: string | undefined): readonly string[] {

package/src/input/commands/mcp-runtime.ts

@@ -3,9 +3,14 @@ import type { McpConfigScope, McpReloadResult, McpServerConfig } from '@pellux/g
 import { requireMcpApi, requireShellPaths } from './runtime-services.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { requireYesFlag, stripYesFlag } from './confirmation.ts';
+import { quoteSlashCommandArg } from '../slash-command-parser.ts';
 
 const MCP_ROLES = ['general', 'docs', 'filesystem', 'git', 'database', 'browser', 'automation', 'ops', 'remote'] as const;
 const MCP_TRUST_MODES = ['constrained', 'ask-on-risk', 'allow-all', 'blocked'] as const;
+const MCP_COMMAND_TRUST_MODES = ['constrained', 'ask-on-risk', 'blocked'] as const;
+const MCP_ADD_COMMAND_USAGE = '/mcp add <name> <command> ... --yes; options: --scope project|global, --role <role>, --trust constrained|ask-on-risk|blocked, --env KEY=VALUE, --path <path>, --host <host>';
+const MCP_TRUST_COMMAND_USAGE = '/mcp trust <server> <constrained|ask-on-risk|blocked> --yes';
+const MCP_ROLE_COMMAND_USAGE = '/mcp role <server> <general|docs|filesystem|git|database|browser|automation|ops|remote> --yes';
 
 interface ParsedMcpAddArgs {
   readonly scope: McpConfigScope;
@@ -25,10 +30,37 @@ function isMcpTrustMode(value: string): value is NonNullable<McpServerConfig['tr
   return MCP_TRUST_MODES.includes(value as NonNullable<McpServerConfig['trustMode']>);
 }
 
+function isMcpCommandTrustMode(value: string): value is Exclude<NonNullable<McpServerConfig['trustMode']>, 'allow-all'> {
+  return MCP_COMMAND_TRUST_MODES.includes(value as Exclude<NonNullable<McpServerConfig['trustMode']>, 'allow-all'>);
+}
+
 function isMcpScope(value: string): value is McpConfigScope {
   return value === 'project' || value === 'global';
 }
 
+function stripMcpAddYesFlag(args: readonly string[]): { readonly rest: readonly string[]; readonly yes: boolean } {
+  const rest: string[] = [];
+  let yes = false;
+  let passthrough = false;
+  for (const token of args) {
+    if (passthrough) {
+      rest.push(token);
+      continue;
+    }
+    if (token === '--') {
+      passthrough = true;
+      rest.push(token);
+      continue;
+    }
+    if (token === '--yes') {
+      yes = true;
+      continue;
+    }
+    rest.push(token);
+  }
+  return { rest, yes };
+}
+
 function formatMcpTrustMode(mode: McpDisplayTrustMode): string {
   if (mode === 'ask-on-risk') return 'ask on risky actions';
   if (mode === 'allow-all') return 'allow all actions';
@@ -64,7 +96,7 @@ function parseAddServerArgs(args: string[]): ParsedMcpAddArgs {
   const name = args[1]?.trim();
   const command = args[2]?.trim();
   if (!name || !command) {
-    throw new Error('Usage: /mcp add <name> <command> [args...] [--scope project|global] [--role <role>] [--trust <mode>] [--env KEY=VALUE] [--path <path>] [--host <host>]');
+    throw new Error(`Usage: ${MCP_ADD_COMMAND_USAGE}`);
   }
   const nameError = validateServerName(name);
   if (nameError) throw new Error(nameError);
@@ -106,6 +138,9 @@ function parseAddServerArgs(args: string[]): ParsedMcpAddArgs {
     if (token === '--trust') {
       const value = readFlagValue(tokens, index, token);
       if (!isMcpTrustMode(value)) throw new Error(`Invalid MCP trust mode "${value}". Expected one of ${MCP_TRUST_MODES.join(', ')}.`);
+      if (!isMcpCommandTrustMode(value)) {
+        throw new Error(`Use /settings -> MCP to explicitly enable allow-all.\nUsage: ${MCP_ADD_COMMAND_USAGE}`);
+      }
       trustMode = value;
       index += 1;
       continue;
@@ -162,7 +197,7 @@ export function registerMcpRuntimeCommands(registry: CommandRegistry): void {
     async handler(args, ctx) {
       const mcpApi = requireMcpApi(ctx);
       const listServerSecurity = () => mcpApi.listServerSecurity();
-      const confirmation = stripYesFlag(args);
+      const confirmation = args[0] === 'add' ? stripMcpAddYesFlag(args) : stripYesFlag(args);
       const commandArgs = [...confirmation.rest];
       const subcommand = commandArgs[0];
       if (!subcommand && ctx.openMcpWorkspace) {
@@ -259,7 +294,7 @@ export function registerMcpRuntimeCommands(registry: CommandRegistry): void {
         }
         const nextSteps = [
           selected.schemaFreshness === 'quarantined'
-            ? `/mcp quarantine ${selected.name} approve operator --yes`
+            ? `/mcp quarantine ${quoteSlashCommandArg(selected.name)} approve operator --yes`
             : null,
           !selected.connected ? '/auth review' : null,
           '/mcp review',
@@ -281,48 +316,58 @@ export function registerMcpRuntimeCommands(registry: CommandRegistry): void {
 
       if (subcommand === 'trust') {
         const serverName = commandArgs[1];
-        const mode = commandArgs[2] as 'constrained' | 'ask-on-risk' | 'allow-all' | 'blocked' | undefined;
-        if (serverName && mode) {
+        const requestedMode = commandArgs[2];
+        if (serverName && requestedMode) {
+          if (!isMcpTrustMode(requestedMode)) {
+            ctx.print(`Invalid MCP trust mode "${requestedMode}". Expected constrained, ask-on-risk, blocked, or allow-all.\nUsage: ${MCP_TRUST_COMMAND_USAGE}\nUse /settings -> MCP to explicitly enable allow-all.`);
+            return;
+          }
+          const mode = requestedMode;
           if (mode === 'allow-all') {
             ctx.print(`Use /settings → MCP to explicitly enable allow-all for ${serverName}. Direct command escalation is blocked.`);
             ctx.openSettingsModal?.();
             return;
           }
           if (!confirmation.yes) {
-            requireYesFlag(ctx, `change MCP trust mode for ${serverName}`, '/mcp trust <server> <constrained|ask-on-risk|blocked> --yes');
+            requireYesFlag(ctx, `change MCP trust mode for ${serverName}`, MCP_TRUST_COMMAND_USAGE);
             return;
           }
           mcpApi.setServerTrustMode(serverName, mode);
           ctx.print(`Updated MCP trust mode for ${serverName} to ${formatMcpTrustMode(mode)}.`);
           return;
         }
-        if (serverName || mode) {
-          ctx.print('Usage: /mcp trust <server> <constrained|ask-on-risk|blocked>\nUse /settings → MCP to explicitly enable allow-all.');
+        if (serverName || requestedMode) {
+          ctx.print(`Usage: ${MCP_TRUST_COMMAND_USAGE}\nUse /settings -> MCP to explicitly enable allow-all.`);
           return;
         }
       }
 
       if (subcommand === 'role') {
         const serverName = commandArgs[1];
-        const role = commandArgs[2] as 'general' | 'docs' | 'filesystem' | 'git' | 'database' | 'browser' | 'automation' | 'ops' | 'remote' | undefined;
-        if (serverName && role) {
+        const requestedRole = commandArgs[2];
+        if (serverName && requestedRole) {
+          if (!isMcpRole(requestedRole)) {
+            ctx.print(`Invalid MCP role "${requestedRole}". Expected one of ${MCP_ROLES.join(', ')}.\nUsage: ${MCP_ROLE_COMMAND_USAGE}`);
+            return;
+          }
+          const role = requestedRole;
           if (!confirmation.yes) {
-            requireYesFlag(ctx, `change MCP role for ${serverName}`, '/mcp role <server> <general|docs|filesystem|git|database|browser|automation|ops|remote> --yes');
+            requireYesFlag(ctx, `change MCP role for ${serverName}`, MCP_ROLE_COMMAND_USAGE);
             return;
           }
           mcpApi.setServerRole(serverName, role);
           ctx.print(`Updated MCP role for ${serverName} to ${formatMcpRole(role)}.`);
           return;
         }
-        if (serverName || role) {
-          ctx.print('Usage: /mcp role <server> <general|docs|filesystem|git|database|browser|automation|ops|remote>');
+        if (serverName || requestedRole) {
+          ctx.print(`Usage: ${MCP_ROLE_COMMAND_USAGE}`);
           return;
         }
       }
 
       if (subcommand === 'add') {
         if (!confirmation.yes) {
-          requireYesFlag(ctx, 'add or update an MCP server config', '/mcp add <name> <command> [args...] [--scope project|global] [--role <role>] [--trust <mode>] --yes');
+          requireYesFlag(ctx, 'add or update an MCP server config', MCP_ADD_COMMAND_USAGE);
           return;
         }
         let parsedAdd: ParsedMcpAddArgs;
@@ -422,8 +467,10 @@ export function registerMcpRuntimeCommands(registry: CommandRegistry): void {
             '',
             'Add or update from inside Agent with explicit confirmation',
             '  Open /mcp and choose Add or update server, or use Agent Workspace -> Tools & MCP -> Add MCP server.',
+            '  Use Settings -> MCP for allow-all decisions.',
+            '  Use -- before server args that look like Agent flags.',
             'Automation equivalent',
-            '  /mcp add <name> <command> [args...] [--scope project|global] [--role <role>] [--trust <mode>] --yes',
+            `  ${MCP_ADD_COMMAND_USAGE}`,
           ].join('\n'));
         } catch (error) {
           ctx.print(`MCP config read failed ${summarizeError(error)}`);

package/src/input/commands/operator-runtime.ts

@@ -2,14 +2,150 @@ import type { CommandRegistry } from '../command-registry.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { requireYesFlag, stripYesFlag } from './confirmation.ts';
+import {
+  formatHarnessError,
+  formatHarnessMutation,
+  formatHarnessSetting,
+  formatHarnessSettingList,
+  getHarnessSetting,
+  listHarnessSettings,
+  resetHarnessSetting,
+  setHarnessSetting,
+} from '../../agent/harness-control.ts';
+
+function readValuedFlag(args: readonly string[], flag: string): string | undefined {
+  const assignmentPrefix = `${flag}=`;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === flag) {
+      const value = args[index + 1];
+      return value && !value.startsWith('--') ? value : undefined;
+    }
+    if (arg?.startsWith(assignmentPrefix)) return arg.slice(assignmentPrefix.length);
+  }
+  return undefined;
+}
+
+function stripValuedFlag(args: readonly string[], flag: string): readonly string[] {
+  const next: string[] = [];
+  const assignmentPrefix = `${flag}=`;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === flag) {
+      const value = args[index + 1];
+      if (value && !value.startsWith('--')) index += 1;
+      continue;
+    }
+    if (arg?.startsWith(assignmentPrefix)) {
+      continue;
+    }
+    next.push(arg!);
+  }
+  return next;
+}
+
+function parseSettingListArgs(args: readonly string[]): {
+  readonly category?: string;
+  readonly prefix?: string;
+  readonly query?: string;
+  readonly includeHidden: boolean;
+  readonly limit?: number;
+} {
+  const category = readValuedFlag(args, '--category');
+  const prefix = readValuedFlag(args, '--prefix');
+  const limitText = readValuedFlag(args, '--limit');
+  const remaining = stripValuedFlag(stripValuedFlag(stripValuedFlag(args, '--category'), '--prefix'), '--limit')
+    .filter((arg) => arg !== '--include-hidden');
+  const query = remaining.join(' ').trim();
+  return {
+    ...(category ? { category } : {}),
+    ...(prefix ? { prefix } : {}),
+    ...(query ? { query } : {}),
+    includeHidden: args.includes('--include-hidden'),
+    ...(limitText ? { limit: Number(limitText) } : {}),
+  };
+}
 
 export function registerOperatorRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
     name: 'settings',
     aliases: ['cfg-ui'],
-    description: 'Open the fullscreen configuration workspace',
-    handler(_args, ctx) {
-      if (ctx.openSettingsModal) ctx.openSettingsModal();
+    description: 'Open, inspect, or update Agent settings',
+    usage: '[category|key|list|get <key>|set <key> <value> --yes|reset <key> --yes]',
+    argsHint: '[list|get|set|reset]',
+    async handler(args, ctx) {
+      const parsed = stripYesFlag(args);
+      const commandArgs = [...parsed.rest];
+      const sub = commandArgs[0];
+
+      if (!sub) {
+        if (ctx.openSettingsModal) ctx.openSettingsModal();
+        else ctx.print('Configuration workspace is not available in this runtime.');
+        return;
+      }
+
+      if (sub === 'list' || sub === 'schema') {
+        ctx.print(formatHarnessSettingList(listHarnessSettings(ctx.platform.configManager, parseSettingListArgs(commandArgs.slice(1)))));
+        return;
+      }
+
+      if (sub === 'get' || sub === 'show') {
+        const key = commandArgs[1];
+        if (!key) {
+          ctx.print('Usage: /settings get <key>');
+          return;
+        }
+        ctx.print(formatHarnessSetting(getHarnessSetting(ctx.platform.configManager, key)));
+        return;
+      }
+
+      if (sub === 'set') {
+        const key = commandArgs[1];
+        const rawValue = commandArgs.slice(2).join(' ');
+        if (!key || rawValue.length === 0) {
+          ctx.print('Usage: /settings set <key> <value> --yes');
+          return;
+        }
+        if (!parsed.yes) {
+          requireYesFlag(ctx, `set setting ${key}`, '/settings set <key> <value> --yes');
+          return;
+        }
+        try {
+          const result = await setHarnessSetting(ctx.platform.configManager, ctx.platform.secretsManager, key, rawValue);
+          ctx.print(formatHarnessMutation(result));
+          ctx.renderRequest();
+        } catch (error) {
+          ctx.print(formatHarnessError(error));
+        }
+        return;
+      }
+
+      if (sub === 'reset') {
+        const key = commandArgs[1];
+        if (!key) {
+          ctx.print('Usage: /settings reset <key> --yes');
+          return;
+        }
+        if (!parsed.yes) {
+          requireYesFlag(ctx, `reset setting ${key}`, '/settings reset <key> --yes');
+          return;
+        }
+        try {
+          const result = await resetHarnessSetting(ctx.platform.configManager, ctx.platform.secretsManager, key);
+          ctx.print(formatHarnessMutation(result));
+          ctx.renderRequest();
+        } catch (error) {
+          ctx.print(formatHarnessError(error));
+        }
+        return;
+      }
+
+      if (sub.includes('.')) {
+        ctx.print(formatHarnessSetting(getHarnessSetting(ctx.platform.configManager, sub)));
+        return;
+      }
+
+      if (ctx.openSettingsModal) ctx.openSettingsModal(sub);
       else ctx.print('Configuration workspace is not available in this runtime.');
     },
   });