@pellux/goodvibes-agent 1.0.35 → 1.0.37

package/src/tools/agent-harness-tool.ts

@@ -33,7 +33,7 @@ import { describeHarnessUiSurface, listHarnessUiSurfaces, openHarnessUiSurface,
 import { AGENT_WORKSPACE_CATEGORIES, allWorkspaceActions, buildWorkspaceEditorContext, createWorkspaceEditor, describeWorkspaceAction, describeWorkspaceCategory, describeWorkspaceEditor, listWorkspaceActions, resolveWorkspaceActionDetail } from './agent-harness-workspace-actions.ts';
 import { describeWorkspaceEditorModelExecution } from './agent-harness-workspace-editor-execution.ts';
 import { connectedHostSummary, describeConnectedHostCapability, settingsPolicySummary } from './agent-harness-metadata.ts';
-import { formatHarnessError, listHarnessSettings, resetHarnessSetting, resolveHarnessSetting, setHarnessSetting } from '../agent/harness-control.ts';
+import { countHarnessSettings, formatHarnessError, listHarnessSettings, resetHarnessSetting, resolveHarnessSetting, setHarnessSetting } from '../agent/harness-control.ts';
 
 interface AgentHarnessToolArgs {
   readonly mode?: unknown;
@@ -126,33 +126,21 @@ function output(value: unknown): { readonly success: true; readonly output: stri
 
 function error(message: string): { readonly success: false; readonly error: string } { return { success: false, error: message }; }
 
+function harnessModeIdsByKind(kind: AgentHarnessModeGuideKind): readonly AgentHarnessMode[] {
+  return HARNESS_MODE_DESCRIPTORS
+    .filter((descriptor) => descriptor.kind === kind)
+    .map((descriptor) => descriptor.id);
+}
+
+type AgentHarnessModeGuideKind = typeof HARNESS_MODE_DESCRIPTORS[number]['kind'];
+
 function compactHarnessModeGuide(): Record<string, unknown> {
   return {
-    discover: [
-      'modes',
-      'cli_commands', 'panels', 'ui_surfaces', 'shortcuts', 'keybindings',
-      'commands', 'channels', 'notifications', 'provider_accounts', 'mcp_servers',
-      'setup_posture', 'model_routing', 'pairing_posture', 'delegation_posture',
-      'security_posture', 'support_bundles', 'media_posture', 'sessions',
-      'settings', 'workspace', 'workspace_categories', 'workspace_actions',
-      'tools', 'release_evidence', 'release_readiness', 'operator_methods',
-      'service_posture', 'connected_host', 'daemon',
-    ],
-    inspect: [
-      'mode',
-      'cli_command', 'panel', 'ui_surface', 'keybinding', 'command', 'channel',
-      'notification_target', 'provider_account', 'mcp_server', 'setup_item',
-      'model_route', 'pairing_route', 'delegation_route', 'security_finding',
-      'support_bundle', 'media_provider', 'session', 'get_setting',
-      'workspace_action', 'tool', 'release_evidence_artifact',
-      'release_readiness_item', 'operator_method', 'service_endpoint',
-      'connected_host_capability', 'connected_host_status', 'daemon_status',
-    ],
-    effects: [
-      'open_panel', 'open_ui_surface', 'run_keybinding', 'set_keybinding',
-      'reset_keybinding', 'run_command', 'set_setting', 'reset_setting',
-      'run_workspace_action',
-    ],
+    start: ['summary', 'modes', 'mode'],
+    discover: harnessModeIdsByKind('discover'),
+    inspect: harnessModeIdsByKind('inspect'),
+    effects: harnessModeIdsByKind('effect'),
+    aliases: harnessModeIdsByKind('alias'),
     pattern: 'Use query|target for search, exact ids for inspect modes, and confirm:true plus explicitUserRequest for effects.',
   };
 }
@@ -180,12 +168,12 @@ function detailedHarnessModelAccessGuide(): Record<string, string> {
     settings: 'List mode:"settings" with category|prefix|query|includeHidden:true; mode:"get_setting", mode:"set_setting", and mode:"reset_setting" use key|target|query; writes require confirmation.',
     tools: 'List mode:"tools" with query|limit|includeParameters:true; inspect mode:"tool" with toolName|target|query.',
     modeCatalog: 'Search mode:"modes" with query|target; inspect one contract with mode:"mode" target:"...".',
-    releaseEvidence: 'List mode:"release_evidence"; inspect mode:"release_evidence_artifact"; includeParameters:true inlines artifact detail.',
-    releaseReadiness: 'List mode:"release_readiness"; inspect mode:"release_readiness_item"; includeParameters:true inlines item detail.',
+    releaseEvidence: 'Operator/audit: list mode:"release_evidence"; inspect mode:"release_evidence_artifact"; includeParameters:true inlines artifact detail.',
+    releaseReadiness: 'Operator/audit: list mode:"release_readiness"; inspect mode:"release_readiness_item"; includeParameters:true inlines item detail.',
     operatorMethods: 'List mode:"operator_methods"; inspect mode:"operator_method"; execute only through the returned first-class tool.',
     servicePosture: 'List mode:"service_posture"; inspect mode:"service_endpoint"; includeParameters:true adds probes and redacted log tail.',
     connectedHost: 'Map mode:"connected_host"; inspect mode:"connected_host_capability"; no lifecycle control.',
-    connectedHostStatus: 'Live read-only mode:"connected_host_status" for host reachability, SDK compatibility, token posture, and Knowledge readiness.',
+    connectedHostStatus: 'Live read-only mode:"connected_host_status" for host reachability, token posture, and Knowledge readiness.',
     daemon: 'Daemon aliases route to mode:"connected_host" and mode:"connected_host_status"; lifecycle control is not exposed.',
   };
 }
@@ -394,7 +382,7 @@ async function runWorkspaceAction(
   }
   if (action.kind === 'editor' && action.editorKind) {
     const editor = createWorkspaceEditor(action.editorKind, buildWorkspaceEditorContext(deps.commandContext, args));
-    if (!editor) return error(`No workspace editor bridge exists for ${action.editorKind}.`);
+    if (!editor) return error(`No workspace editor route exists for ${action.editorKind}.`);
     return runWorkspaceEditorAction(deps, action, editor, args);
   }
   if (action.kind === 'local-selection' || action.kind === 'local-operation') {
@@ -501,7 +489,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             panels,
             returned: panels.length,
             total: totalHarnessPanels(deps.commandContext),
-            policy: 'Panel modes expose Agent/TUI operator view catalog and open state. open_panel is confirmation-gated and routes through the current Agent shell bridge.',
+            policy: 'Panel modes expose Agent/TUI operator view catalog and open state. open_panel is confirmation-gated and routes through the current Agent operator surface.',
           });
         }
         if (args.mode === 'panel') {
@@ -640,16 +628,20 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
           return error(resolved.usage);
         }
         if (args.mode === 'settings') {
-          const settings = listHarnessSettings(deps.commandContext.platform.configManager, {
+          const filters = {
             category: readString(args.category) || undefined,
             prefix: readString(args.prefix) || undefined,
             query: readString(args.query) || undefined,
             includeHidden: args.includeHidden === true,
-            limit: readLimit(args.limit, 100),
+            limit: readLimit(args.limit, 500),
+          };
+          const settings = listHarnessSettings(deps.commandContext.platform.configManager, {
+            ...filters,
           }, {
             includeParameters: args.includeParameters === true,
           });
-          return output({ settings, returned: settings.length, policy: settingsPolicySummary() });
+          const total = countHarnessSettings(deps.commandContext.platform.configManager, filters);
+          return output({ settings, returned: settings.length, total, policy: settingsPolicySummary() });
         }
         if (args.mode === 'get_setting') {
           const setting = resolveHarnessSetting(deps.commandContext.platform.configManager, settingLookupArgs(args));

package/src/tools/agent-harness-ui-surface-metadata.ts

@@ -74,7 +74,7 @@ function opened(surface: UiSurfaceDefinition, extra: Record<string, unknown> = {
     surface: surface.id,
     kind: surface.kind,
     ...extra,
-    note: 'UI routing was handed to the current Agent shell bridge.',
+    note: 'UI routing was handed to the current Agent operator surface.',
   };
 }
 
@@ -154,18 +154,26 @@ function openPanelWorkspaceSurface(
       categoryId: options.categoryId,
       panelId: options.panelId,
       pane: pane ?? 'default',
-      route: 'panel-bridge',
+      route: 'panel-route',
     });
   }
   return routeUnavailable(surface);
 }
 
+function openSimpleContextSurface(context: CommandContext, surfaceId: string, openerKey: keyof CommandContext): Record<string, unknown> {
+  const surface = findSurfaceById(surfaceId)!;
+  const opener = context[openerKey] as unknown;
+  if (typeof opener !== 'function') return routeUnavailable(surface);
+  (opener as () => void)();
+  return opened(surface);
+}
+
 const UI_SURFACES: readonly UiSurfaceDefinition[] = [
   {
     id: 'agent-workspace',
     label: 'Agent Workspace',
     kind: 'workspace',
-    summary: 'Fullscreen operator workspace with setup, knowledge, local state, channels, automation, and delegation routes.',
+    summary: 'Operator workspace for setup, knowledge, channels, and automation.',
     command: '/agent',
     preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action')} for model operation; use mode:"open_ui_surface" only to visibly navigate.`,
     parameters: ['categoryId'],
@@ -182,7 +190,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'panel-picker',
     label: 'Panel Picker',
     kind: 'picker',
-    summary: 'Keyboard-accessible operator panel route that now opens the Agent Workspace home surface.',
+    summary: 'Operator panel route into Agent Workspace home.',
     command: 'Ctrl+P',
     preferredModelRoute: `Use ${agentHarnessModes('panels', 'panel', 'open_panel')} for panel catalog and routing, or mode:"workspace_actions" for concrete model operation.`,
     available: (context) => typeof context.openPanelPicker === 'function' || typeof context.openAgentWorkspace === 'function',
@@ -199,15 +207,11 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'security-panel',
     label: 'Security Panel',
     kind: 'workspace',
-    summary: 'Security review operator surface for token posture, MCP attack paths, policy posture, and plugin risk.',
+    summary: 'Operator security review for tokens, MCP, policy, and plugin risk.',
     command: '/security',
     preferredModelRoute: `Use mode:"workspace_actions" for security review actions or ${agentHarnessModes('run_command')} for confirmed /security review output.`,
     parameters: ['pane'],
-    available: (context) => (
-      typeof context.openAgentWorkspace === 'function'
-      || typeof context.openSecurityPanel === 'function'
-      || typeof context.showPanel === 'function'
-    ),
+    available: (context) => typeof context.openAgentWorkspace === 'function' || typeof context.openSecurityPanel === 'function' || typeof context.showPanel === 'function',
     open: (context, args) => {
       const surface = findSurfaceById('security-panel')!;
       return openPanelWorkspaceSurface(context, args, surface, {
@@ -221,15 +225,11 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'knowledge-panel',
     label: 'Knowledge Panel',
     kind: 'workspace',
-    summary: 'Agent Knowledge operator surface for isolated status, source/node/issue libraries, item lookup, map review, connectors, ask/search, and ingest forms.',
+    summary: 'Operator Knowledge surface for isolated status, search, and ingest.',
     command: '/knowledge',
     preferredModelRoute: `Use agent_knowledge, agent_knowledge_ingest, mode:"workspace_actions", or ${agentHarnessModes('run_command')} for confirmed /knowledge operation.`,
     parameters: ['pane'],
-    available: (context) => (
-      typeof context.openAgentWorkspace === 'function'
-      || typeof context.openKnowledgePanel === 'function'
-      || typeof context.showPanel === 'function'
-    ),
+    available: (context) => typeof context.openAgentWorkspace === 'function' || typeof context.openKnowledgePanel === 'function' || typeof context.showPanel === 'function',
     open: (context, args) => {
       const surface = findSurfaceById('knowledge-panel')!;
       return openPanelWorkspaceSurface(context, args, surface, {
@@ -243,15 +243,11 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'subscription-panel',
     label: 'Subscription Panel',
     kind: 'workspace',
-    summary: 'Provider subscription operator surface for subscription review, provider inspection, login, logout, and bundle flows.',
+    summary: 'Operator subscription surface for provider review, auth, and bundles.',
     command: '/subscription',
     preferredModelRoute: `Use mode:"workspace_actions" or ${agentHarnessModes('run_command')} for confirmed /subscription mirrors.`,
     parameters: ['pane'],
-    available: (context) => (
-      typeof context.openAgentWorkspace === 'function'
-      || typeof context.openSubscriptionPanel === 'function'
-      || typeof context.showPanel === 'function'
-    ),
+    available: (context) => typeof context.openAgentWorkspace === 'function' || typeof context.openSubscriptionPanel === 'function' || typeof context.showPanel === 'function',
     open: (context, args) => {
       const surface = findSurfaceById('subscription-panel')!;
       return openPanelWorkspaceSurface(context, args, surface, {
@@ -265,7 +261,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'settings',
     label: 'Settings',
     kind: 'modal',
-    summary: 'Fullscreen settings workspace for Agent-owned configuration, subscriptions, secrets, MCP, tools, and surface settings.',
+    summary: 'Fullscreen settings workspace for Agent config, secrets, MCP, and tools.',
     command: '/settings',
     preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting', 'reset_setting')} for model operation; use mode:"open_ui_surface" only to visibly navigate.`,
     parameters: ['target', 'key', 'prefix'],
@@ -286,12 +282,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/mcp',
     preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'tools', 'settings')} for model operation.`,
     available: (context) => typeof context.openMcpWorkspace === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('mcp-workspace')!;
-      if (!context.openMcpWorkspace) return routeUnavailable(surface);
-      context.openMcpWorkspace();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'mcp-workspace', 'openMcpWorkspace'),
   },
   {
     id: 'model-picker',
@@ -339,7 +330,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'reasoning-effort-picker',
     label: 'Reasoning Effort Picker',
     kind: 'picker',
-    summary: 'Interactive reasoning-effort selector for the current main chat model when that model exposes effort levels.',
+    summary: 'Reasoning-effort selector for models that expose effort levels.',
     command: '/effort',
     preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for provider.reasoningEffort when a concrete level is known, or mode:"run_workspace_action" setup-effort with confirmation.`,
     available: (context) => typeof context.openReasoningEffortPicker === 'function',
@@ -367,7 +358,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'tts-provider-picker',
     label: 'TTS Provider Picker',
     kind: 'picker',
-    summary: 'Interactive streaming TTS provider picker opened from the Agent settings flow.',
+    summary: 'Streaming TTS provider picker from Agent settings.',
     command: '/config tts.provider',
     preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for tts.provider when a concrete provider id is known; use mode:"open_ui_surface" only to visibly navigate.`,
     available: (context) => typeof context.openSelection === 'function' && Boolean(context.platform.voiceProviderRegistry),
@@ -382,7 +373,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'tts-voice-picker',
     label: 'TTS Voice Picker',
     kind: 'picker',
-    summary: 'Interactive TTS voice picker opened from the Agent settings flow for the selected or supplied provider.',
+    summary: 'TTS voice picker for the selected or supplied provider.',
     command: '/config tts.voice',
     preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting', 'reset_setting')} for tts.voice when a concrete voice id is known; use mode:"open_ui_surface" only to visibly navigate.`,
     parameters: ['target'],
@@ -405,12 +396,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/sessions',
     preferredModelRoute: 'Use session slash-command mirrors with confirmation for concrete save/load/export actions.',
     available: (context) => typeof context.openSessionPicker === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('session-picker')!;
-      if (!context.openSessionPicker) return routeUnavailable(surface);
-      context.openSessionPicker();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'session-picker', 'openSessionPicker'),
   },
   {
     id: 'profile-picker',
@@ -420,12 +406,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/agent-profile',
     preferredModelRoute: 'Use workspace profile actions or profile slash-command mirrors for concrete model operation.',
     available: (context) => typeof context.openProfilePicker === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('profile-picker')!;
-      if (!context.openProfilePicker) return routeUnavailable(surface);
-      context.openProfilePicker();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'profile-picker', 'openProfilePicker'),
   },
   {
     id: 'bookmark-modal',
@@ -435,12 +416,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/bookmarks',
     preferredModelRoute: 'Use slash-command mirrors for concrete bookmark inspection; opening is visible navigation only.',
     available: (context) => typeof context.openBookmarkModal === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('bookmark-modal')!;
-      if (!context.openBookmarkModal) return routeUnavailable(surface);
-      context.openBookmarkModal();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'bookmark-modal', 'openBookmarkModal'),
   },
   {
     id: 'context-inspector',
@@ -450,33 +426,23 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/context',
     preferredModelRoute: 'Use slash-command mirrors for text output; opening is visible navigation only.',
     available: (context) => typeof context.openContextInspector === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('context-inspector')!;
-      if (!context.openContextInspector) return routeUnavailable(surface);
-      context.openContextInspector();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'context-inspector', 'openContextInspector'),
   },
   {
     id: 'process-monitor',
     label: 'Runtime Activity Monitor',
     kind: 'modal',
-    summary: 'Visible running-process and live-output monitor opened by the same shell route as F2.',
+    summary: 'Visible running-process and live-output monitor.',
     command: 'F2',
     preferredModelRoute: 'Use this only for visible supervision of runtime activity; use first-class model tools or confirmed commands for actual operations.',
     available: (context) => typeof context.openProcessModal === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('process-monitor')!;
-      if (!context.openProcessModal) return routeUnavailable(surface);
-      context.openProcessModal();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'process-monitor', 'openProcessModal'),
   },
   {
     id: 'live-tail',
     label: 'Live Process Output',
     kind: 'modal',
-    summary: 'Visible live-output tail for a running process, opened by the same shell route as Enter from the runtime activity monitor.',
+    summary: 'Visible live-output tail for a running process.',
     command: 'F2, Enter',
     preferredModelRoute: 'Use this only for visible supervision of a running process output stream; use first-class model tools or confirmed commands for actual operations.',
     parameters: ['target', 'query', 'prefix', 'key'],
@@ -508,7 +474,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'conversation-search',
     label: 'Conversation Search',
     kind: 'overlay',
-    summary: 'Visible transcript search overlay opened by the same shell route as Ctrl+F.',
+    summary: 'Visible transcript search overlay.',
     command: 'Ctrl+F',
     preferredModelRoute: 'Use conversation/session/content modes for model-readable inspection; use this surface for visible transcript search navigation.',
     parameters: ['query', 'prefix', 'key'],
@@ -525,7 +491,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'prompt-history-search',
     label: 'Prompt History Search',
     kind: 'overlay',
-    summary: 'Visible reverse prompt-history search opened by the same shell route as Ctrl+R.',
+    summary: 'Visible reverse prompt-history search.',
     command: 'Ctrl+R',
     preferredModelRoute: 'Use this only for visible prompt recall; accepting a result remains an explicit interactive shell action.',
     parameters: ['query', 'prefix', 'key'],
@@ -542,7 +508,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'slash-command-mode',
     label: 'Slash Command Mode',
     kind: 'overlay',
-    summary: 'Slash-command autocomplete route opened by the same shell path as typing / in an empty prompt.',
+    summary: 'Slash-command autocomplete route for empty prompts.',
     command: '/',
     preferredModelRoute: `Use ${agentHarnessModes('commands', 'command')} for model-readable command discovery and mode:"run_command" for confirmed command execution.`,
     parameters: ['query', 'prefix', 'key'],
@@ -567,7 +533,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'command-browser',
     label: 'Command Browser',
     kind: 'picker',
-    summary: 'Registry-driven searchable slash-command browser opened by /commands and /help.',
+    summary: 'Searchable slash-command browser opened by commands or help.',
     command: '/commands',
     preferredModelRoute: `Use ${agentHarnessModes('commands', 'command')} for model-readable slash-command discovery and mode:"run_command" for confirmed command execution.`,
     available: (context) => typeof context.executeCommand === 'function',
@@ -589,7 +555,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'file-picker',
     label: 'File Picker',
     kind: 'picker',
-    summary: 'Visible project file picker opened by the same prompt route as @ and !@ references.',
+    summary: 'Visible project file picker for file references and injection.',
     command: '@',
     preferredModelRoute: 'Use first-class file, workspace, or artifact tools for model operation; use this for visible file reference navigation.',
     parameters: ['target=reference|inject', 'query', 'prefix', 'key'],
@@ -608,7 +574,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'block-actions',
     label: 'Block Actions',
     kind: 'overlay',
-    summary: 'Visible nearest-block action menu opened by the same shell route as pressing Enter on an empty prompt near transcript content.',
+    summary: 'Visible nearest-block action menu for transcript content.',
     command: 'Enter on empty prompt',
     preferredModelRoute: 'Use conversation/session/content modes or confirmed slash-command mirrors for concrete block operations; use this surface for visible block-action navigation.',
     available: (context) => typeof context.openBlockActions === 'function',
@@ -634,12 +600,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/help',
     preferredModelRoute: `Use ${agentHarnessModes('commands', 'command', 'shortcuts')} for model-readable discovery.`,
     available: (context) => typeof context.openHelpOverlay === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('help-overlay')!;
-      if (!context.openHelpOverlay) return routeUnavailable(surface);
-      context.openHelpOverlay();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'help-overlay', 'openHelpOverlay'),
   },
   {
     id: 'shortcuts-overlay',
@@ -649,12 +610,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/shortcuts',
     preferredModelRoute: `Use ${agentHarnessModes('shortcuts', 'keybindings')} for model-readable discovery, mode:"run_keybinding" for supported shell-safe actions, and confirmed keybinding edits for binding changes.`,
     available: (context) => typeof context.openShortcutsOverlay === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('shortcuts-overlay')!;
-      if (!context.openShortcutsOverlay) return routeUnavailable(surface);
-      context.openShortcutsOverlay();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'shortcuts-overlay', 'openShortcutsOverlay'),
   },
   {
     id: 'onboarding',
@@ -687,6 +643,7 @@ function surfaceMatches(surface: Record<string, unknown>, query: string): boolea
     surface.kind,
     surface.summary,
     surface.command,
+    surface.modelRoute,
     surface.preferredModelRoute,
   ].map((value) => String(value ?? '')).join('\n').toLowerCase().includes(query.toLowerCase());
 }
@@ -708,10 +665,52 @@ function surfaceCandidate(surface: UiSurfaceDefinition): Record<string, unknown>
     kind: surface.kind,
     summary: surface.summary,
     command: surface.command,
-    preferredModelRoute: surface.preferredModelRoute,
+    modelRoute: uiSurfaceModelRoute(surface),
   };
 }
 
+function uiSurfaceModelRoute(surface: UiSurfaceDefinition): string {
+  switch (surface.id) {
+    case 'agent-workspace':
+    case 'panel-picker':
+    case 'security-panel':
+    case 'subscription-panel':
+    case 'mcp-workspace':
+    case 'onboarding':
+      return 'agent_harness mode:"workspace_actions" or mode:"open_ui_surface"';
+    case 'knowledge-panel':
+      return 'agent_knowledge, agent_knowledge_ingest, or workspace_actions';
+    case 'settings':
+    case 'tts-provider-picker':
+    case 'tts-voice-picker':
+    case 'reasoning-effort-picker':
+      return 'agent_harness mode:"settings" or mode:"open_ui_surface"';
+    case 'model-picker':
+    case 'provider-picker':
+      return 'agent_harness mode:"settings" or mode:"run_command"';
+    case 'session-picker':
+    case 'bookmark-modal':
+    case 'context-inspector':
+    case 'slash-command-mode':
+    case 'command-browser':
+    case 'block-actions':
+      return 'agent_harness mode:"commands" or mode:"run_command"';
+    case 'process-monitor':
+    case 'live-tail':
+    case 'file-picker':
+      return 'first-class tools or agent_harness mode:"open_ui_surface"';
+    case 'conversation-search':
+    case 'prompt-history-search':
+      return 'agent_harness mode:"open_ui_surface"';
+    case 'help-overlay':
+      return 'agent_harness mode:"commands" or mode:"shortcuts"';
+    case 'shortcuts-overlay':
+      return 'agent_harness mode:"shortcuts" or mode:"keybindings"';
+    default:
+      return 'agent_harness mode:"open_ui_surface"';
+  }
+}
+
 function resolveHarnessUiSurface(args: AgentHarnessUiSurfaceArgs): UiSurfaceResolution | null {
   const lookup = surfaceLookupFromArgs(args);
   if (!lookup) return null;
@@ -744,9 +743,10 @@ function describeSurface(
     summary: surface.summary,
     command: surface.command,
     ...(options.lookup ? { lookup: options.lookup } : {}),
-    preferredModelRoute: surface.preferredModelRoute,
+    modelRoute: uiSurfaceModelRoute(surface),
     available: surface.available(context),
     ...(options.includeParameters ? {
+      preferredModelRoute: surface.preferredModelRoute,
       parameters: surface.parameters ?? [],
       policy: {
         effect: 'visible-ui-navigation',

package/src/tools/agent-harness-workspace-actions.ts

@@ -4,6 +4,8 @@ import { AGENT_WORKSPACE_CATEGORIES } from '../input/agent-workspace-categories.
 import { searchAgentWorkspaceActions } from '../input/agent-workspace-search.ts';
 import { buildAgentWorkspaceRuntimeSnapshot } from '../input/agent-workspace-snapshot.ts';
 import type { AgentWorkspaceAction, AgentWorkspaceCategory, AgentWorkspaceEditorKind, AgentWorkspaceLocalEditor, AgentWorkspaceLocalLibraryItem, AgentWorkspaceRuntimeSnapshot } from '../input/agent-workspace-types.ts';
+import { parseSlashCommand } from '../input/slash-command-parser.ts';
+import { describeCommandPolicy } from './agent-harness-metadata.ts';
 import { describeLocalWorkspaceModelExecution } from './agent-harness-local-operations.ts';
 import { describeWorkspaceEditorModelExecution } from './agent-harness-workspace-editor-execution.ts';
 
@@ -97,9 +99,66 @@ export function describeWorkspaceEditor(editor: AgentWorkspaceLocalEditor): Reco
   };
 }
 
-function previewText(value: string, maxLength = 120): string {
+function previewText(value: string, maxLength = 56): string {
   const normalized = value.replace(/\s+/g, ' ').trim();
-  return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 1).trimEnd()}...`;
+  return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 3).trimEnd()}...`;
+}
+
+function commandRouteHint(command: string): string {
+  const parsed = parseSlashCommand(command);
+  const commandName = parsed.name || command.replace(/^\//, '').trim().split(/\s+/)[0] || command;
+  return describeCommandPolicy(commandName).preferredModelTool ?? 'agent_harness mode:"run_command"';
+}
+
+function editorRouteHint(editorKind: AgentWorkspaceEditorKind): string {
+  if (
+    editorKind === 'memory'
+    || editorKind === 'note'
+    || editorKind === 'persona'
+    || editorKind === 'skill'
+    || editorKind === 'routine'
+  ) return 'agent_local_registry';
+  if (
+    editorKind === 'knowledge-url'
+    || editorKind === 'knowledge-urls'
+    || editorKind === 'knowledge-file'
+    || editorKind === 'knowledge-bookmarks'
+    || editorKind === 'knowledge-browser-history'
+    || editorKind === 'knowledge-connector-ingest'
+  ) return 'agent_knowledge_ingest';
+  if (
+    editorKind === 'knowledge-reindex'
+    || editorKind === 'knowledge-review-issue'
+    || editorKind === 'knowledge-consolidate'
+  ) return 'agent_harness mode:"run_workspace_action"';
+  if (editorKind.startsWith('knowledge-')) return 'agent_knowledge';
+  if (editorKind === 'web-research' || editorKind === 'web-fetch') return 'main conversation prompt';
+  if (editorKind === 'media-generate') return 'agent_media_generate';
+  if (editorKind === 'channel-send') return 'agent_channel_send';
+  if (editorKind === 'notify-send' || editorKind === 'notify-webhook-test') return 'agent_notify';
+  if (editorKind === 'reminder-schedule') return 'agent_reminder_schedule';
+  if (
+    editorKind.startsWith('approval-')
+    || editorKind.startsWith('automation-')
+    || editorKind === 'schedule-run'
+  ) return 'agent_operator_action';
+  if (editorKind.startsWith('workplan-') || editorKind.startsWith('plan-') || editorKind.startsWith('task-')) return 'agent_work_plan';
+  return 'agent_harness mode:"run_workspace_action"';
+}
+
+function localActionRouteHint(action: AgentWorkspaceAction): string {
+  const modelExecution = describeLocalWorkspaceModelExecution(action);
+  const tool = modelExecution && typeof modelExecution.tool === 'string' ? modelExecution.tool : '';
+  return tool || 'agent_local_registry';
+}
+
+function workspaceActionRouteHint(action: AgentWorkspaceAction): string {
+  if (action.command) return commandRouteHint(action.command);
+  if (action.editorKind) return editorRouteHint(action.editorKind);
+  if (action.kind === 'local-selection' || action.kind === 'local-operation') return localActionRouteHint(action);
+  if (action.targetCategoryId || action.kind === 'workspace') return 'agent_harness mode:"open_ui_surface"';
+  if (action.kind === 'guidance') return action.safety === 'blocked' ? 'main conversation policy' : 'main conversation';
+  return 'agent_harness mode:"workspace_action"';
 }
 
 function selectedRoutineFromArgs(
@@ -152,6 +211,7 @@ export function describeWorkspaceAction(
     detail: action.detail,
     kind: action.kind,
     safety: action.safety,
+    modelRoute: previewText(workspaceActionRouteHint(action)),
     ...(action.command ? { command: action.command } : {}),
     ...(action.targetCategoryId ? { targetCategoryId: action.targetCategoryId } : {}),
     ...(action.editorKind ? { editorKind: action.editorKind } : {}),
@@ -181,6 +241,7 @@ function describeWorkspaceActionSummary(
     summary: previewText(action.detail),
     kind: action.kind,
     safety: action.safety,
+    modelRoute: previewText(workspaceActionRouteHint(action)),
     ...(action.command ? { command: action.command } : {}),
     ...(action.targetCategoryId ? { targetCategoryId: action.targetCategoryId } : {}),
     ...(action.editorKind ? { editorKind: action.editorKind } : {}),
@@ -195,7 +256,7 @@ export function listWorkspaceActions(
 ): readonly Record<string, unknown>[] {
   const query = readString(args.query);
   const categoryId = readString(args.categoryId || args.category);
-  const limit = readLimit(args.limit, 200);
+  const limit = readLimit(args.limit, 500);
   const includeEditor = args.includeParameters === true;
   const editorContext = includeEditor ? buildWorkspaceEditorContext(context, args) : null;
   const source = query

package/src/tools/agent-knowledge-ingest-tool.ts

@@ -326,7 +326,7 @@ export function createAgentKnowledgeIngestTool(
           },
           allowPrivateHosts: {
             type: 'boolean',
-            description: 'Allow private-host source URLs where the Agent Knowledge route supports it.',
+            description: 'Allow supported private-host source URLs.',
           },
           confirm: {
             type: 'boolean',

package/src/tools/agent-knowledge-tool.ts

@@ -142,7 +142,7 @@ export function createAgentKnowledgeTool(
           },
           connectorId: {
             type: 'string',
-            description: 'Connector id for action connector or connector_doctor. id may also be used.',
+            description: 'Connector id for connector or connector_doctor.',
           },
           limit: {
             type: 'number',

package/src/tools/agent-media-generate-tool.ts

@@ -74,11 +74,11 @@ export function createAgentMediaGenerateTool(
           },
           confirm: {
             type: 'boolean',
-            description: 'Required true only when the user explicitly asked for this media generation.',
+            description: 'Required true only when user requested this media.',
           },
           explicitUserRequest: {
             type: 'string',
-            description: 'Short quote or summary of the user request that authorized this generation.',
+            description: 'User request authorizing this media generation.',
           },
         },
         required: ['prompt', 'confirm', 'explicitUserRequest'],

package/src/tools/agent-notify-tool.ts

@@ -88,7 +88,7 @@ export function createAgentNotifyTool(
           },
           confirm: {
             type: 'boolean',
-            description: 'Required true only when the user explicitly asked to send this notification.',
+            description: 'Required true only when user requested notification.',
           },
           explicitUserRequest: {
             type: 'string',