@pellux/goodvibes-agent 1.0.33 → 1.0.35

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

@@ -28,14 +28,13 @@ import { describeHarnessSession, sessionCatalogStatus, sessionSummary } from './
 import { describeHarnessServiceEndpoint, servicePostureCatalogStatus, servicePostureSummary } from './agent-harness-service-posture.ts';
 import { describeHarnessSetupItem, setupPostureCatalogStatus, setupPostureSummary } from './agent-harness-setup-posture.ts';
 import { AGENT_HARNESS_MODES, AGENT_HARNESS_PARAMETER_PROPERTIES } from './agent-harness-tool-schema.ts';
+import { describeHarnessMode, HARNESS_MODE_DESCRIPTORS, listHarnessModes, type AgentHarnessMode } from './agent-harness-mode-catalog.ts';
 import { describeHarnessUiSurface, listHarnessUiSurfaces, openHarnessUiSurface, totalHarnessUiSurfaces } from './agent-harness-ui-surface-metadata.ts';
 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';
 
-type AgentHarnessMode = typeof AGENT_HARNESS_MODES[number];
-
 interface AgentHarnessToolArgs {
   readonly mode?: unknown;
   readonly query?: unknown;
@@ -127,6 +126,70 @@ 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 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',
+    ],
+    pattern: 'Use query|target for search, exact ids for inspect modes, and confirm:true plus explicitUserRequest for effects.',
+  };
+}
+
+function detailedHarnessModelAccessGuide(): Record<string, string> {
+  return {
+    cliCommands: 'List mode:"cli_commands"; inspect mode:"cli_command" with cliCommand|commandName|query. Discovery only.',
+    panels: 'List mode:"panels"; inspect mode:"panel"; navigate mode:"open_panel" with confirm:true and explicitUserRequest.',
+    uiSurfaces: 'List mode:"ui_surfaces"; inspect mode:"ui_surface"; navigate mode:"open_ui_surface" with confirmation.',
+    shortcuts: 'List mode:"shortcuts"; inspect mode:"keybinding"; run mode:"run_keybinding"; edit with set_keybinding/reset_keybinding and confirmation.',
+    slashCommands: 'List mode:"commands"; inspect mode:"command"; execute mode:"run_command" with confirmation.',
+    channels: 'List mode:"channels"; inspect mode:"channel"; deliver with agent_channel_send and confirmation.',
+    notifications: 'List mode:"notifications"; inspect mode:"notification_target"; deliver with agent_notify and confirmation.',
+    providerAccounts: 'List mode:"provider_accounts"; inspect mode:"provider_account"; auth changes stay confirmed workspace/command flows.',
+    mcpServers: 'List mode:"mcp_servers"; inspect mode:"mcp_server"; trust/server changes stay confirmed workspace/command flows.',
+    setupPosture: 'List mode:"setup_posture"; inspect mode:"setup_item"; setup mutations stay confirmed visible flows.',
+    modelRouting: 'List mode:"model_routing"; inspect mode:"model_route"; selection and provider edits stay confirmed visible flows.',
+    pairingPosture: 'List mode:"pairing_posture"; inspect mode:"pairing_route"; raw token/QR and pairing effects stay visible user flows.',
+    delegationPosture: 'List mode:"delegation_posture"; inspect mode:"delegation_route"; delegated submission stays confirmed visible flow.',
+    securityPosture: 'List mode:"security_posture"; inspect mode:"security_finding"; mutate only through confirmed security routes.',
+    supportBundles: 'List mode:"support_bundles"; inspect mode:"support_bundle"; export/import stays confirmation-gated.',
+    mediaPosture: 'List mode:"media_posture"; inspect mode:"media_provider"; generate with agent_media_generate and confirmation.',
+    sessions: 'List mode:"sessions"; inspect mode:"session"; save/resume/export/delete stays visible confirmed flow.',
+    workspace: 'List mode:"workspace" or mode:"workspace_categories"; actions via mode:"workspace_actions", mode:"workspace_action", and mode:"run_workspace_action"; includeParameters:true inlines editor schemas.',
+    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.',
+    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.',
+    daemon: 'Daemon aliases route to mode:"connected_host" and mode:"connected_host_status"; lifecycle control is not exposed.',
+  };
+}
+
 function requireConfirmedAction(args: AgentHarnessToolArgs, action: string): string | null {
   const explicitUserRequest = readString(args.explicitUserRequest);
   if (!explicitUserRequest) return `${action} requires explicitUserRequest with the user's exact request or a short faithful summary.`;
@@ -348,11 +411,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
   return {
     definition: {
       name: 'agent_harness',
-      description: [
-        'Inspect or operate the GoodVibes Agent harness.',
-        'Use summary for mode help.',
-        'Effects require confirm:true plus explicitUserRequest; no host lifecycle or raw secrets.',
-      ].join(' '),
+      description: 'Inspect or operate GoodVibes Agent harness surfaces.',
       parameters: {
         type: 'object',
         properties: AGENT_HARNESS_PARAMETER_PROPERTIES,
@@ -368,6 +427,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
       try {
         if (args.mode === 'summary') {
           return output({
+            harnessModes: HARNESS_MODE_DESCRIPTORS.length,
             cliCommands: totalHarnessCliCommands(),
             blockedCliCommandTokens: blockedHarnessCliCommandTokens(),
             panels: totalHarnessPanels(deps.commandContext),
@@ -407,38 +467,21 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             releaseReadiness: releaseReadinessInventoryStatus(),
             operatorMethods: operatorMethodCatalogStatus(),
             servicePosture: servicePostureCatalogStatus(),
-            modelAccess: {
-              cliCommands: 'List mode:"cli_commands"; inspect mode:"cli_command" with cliCommand|commandName|query. Discovery only.',
-              panels: 'List mode:"panels"; inspect mode:"panel"; navigate mode:"open_panel" with confirm:true and explicitUserRequest.',
-              uiSurfaces: 'List mode:"ui_surfaces"; inspect mode:"ui_surface"; navigate mode:"open_ui_surface" with confirmation.',
-              shortcuts: 'List mode:"shortcuts"; inspect mode:"keybinding"; run mode:"run_keybinding"; edit with set_keybinding/reset_keybinding and confirmation.',
-              slashCommands: 'List mode:"commands"; inspect mode:"command"; execute mode:"run_command" with confirmation.',
-              channels: 'List mode:"channels"; inspect mode:"channel"; deliver with agent_channel_send and confirmation.',
-              notifications: 'List mode:"notifications"; inspect mode:"notification_target"; deliver with agent_notify and confirmation.',
-              providerAccounts: 'List mode:"provider_accounts"; inspect mode:"provider_account"; auth changes stay confirmed workspace/command flows.',
-              mcpServers: 'List mode:"mcp_servers"; inspect mode:"mcp_server"; trust/server changes stay confirmed workspace/command flows.',
-              setupPosture: 'List mode:"setup_posture"; inspect mode:"setup_item"; setup mutations stay confirmed visible flows.',
-              modelRouting: 'List mode:"model_routing"; inspect mode:"model_route"; selection and provider edits stay confirmed visible flows.',
-              pairingPosture: 'List mode:"pairing_posture"; inspect mode:"pairing_route"; raw token/QR and pairing effects stay visible user flows.',
-              delegationPosture: 'List mode:"delegation_posture"; inspect mode:"delegation_route"; delegated submission stays confirmed visible flow.',
-              securityPosture: 'List mode:"security_posture"; inspect mode:"security_finding"; mutate only through confirmed security routes.',
-              supportBundles: 'List mode:"support_bundles"; inspect mode:"support_bundle"; export/import stays confirmation-gated.',
-              mediaPosture: 'List mode:"media_posture"; inspect mode:"media_provider"; generate with agent_media_generate and confirmation.',
-              sessions: 'List mode:"sessions"; inspect mode:"session"; save/resume/export/delete stays visible confirmed flow.',
-              workspace: 'List mode:"workspace" or mode:"workspace_categories"; actions via workspace_actions/workspace_action/run_workspace_action; includeParameters:true inlines editor schemas.',
-              settings: 'List mode:"settings" with category|prefix|query|includeHidden:true; get_setting/set_setting/reset_setting use key|target|query and confirmation for writes.',
-              tools: 'List mode:"tools" with query|limit|includeParameters:true; inspect mode:"tool" with toolName|target|query.',
-              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.',
-              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.',
-            },
+            modeGuide: compactHarnessModeGuide(),
+            ...(args.includeParameters === true ? { modelAccess: detailedHarnessModelAccessGuide() } : {}),
             settingsPolicy: settingsPolicySummary(),
-            connectedHost: connectedHostSummary(deps.commandContext, deps.toolRegistry),
+            connectedHost: connectedHostSummary(deps.commandContext, deps.toolRegistry, {
+              includeParameters: args.includeParameters === true,
+            }),
           });
         }
+        if (args.mode === 'modes') return output(listHarnessModes(args));
+        if (args.mode === 'mode') {
+          const mode = describeHarnessMode(args);
+          if (mode.status === 'ambiguous') return error(`Ambiguous harness mode ${String(mode.input)}. Candidates: ${JSON.stringify(mode.candidates)}`);
+          if (mode.status === 'missing_lookup') return error(String(mode.usage));
+          return output(mode.mode);
+        }
         if (args.mode === 'cli_commands') {
           const commands = listHarnessCliCommands(args);
           return output({
@@ -603,6 +646,8 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             query: readString(args.query) || undefined,
             includeHidden: args.includeHidden === true,
             limit: readLimit(args.limit, 100),
+          }, {
+            includeParameters: args.includeParameters === true,
           });
           return output({ settings, returned: settings.length, policy: settingsPolicySummary() });
         }
@@ -714,7 +759,11 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
           if (resolved.status === 'ambiguous') return error(`Ambiguous service endpoint ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
           return error(resolved.usage);
         }
-        if (args.mode === 'connected_host') return output(connectedHostSummary(deps.commandContext, deps.toolRegistry));
+        if (args.mode === 'connected_host' || args.mode === 'daemon') {
+          return output(connectedHostSummary(deps.commandContext, deps.toolRegistry, {
+            includeParameters: args.includeParameters === true,
+          }));
+        }
         if (args.mode === 'connected_host_capability') {
           const query = readString(args.capabilityId || args.target || args.query);
           const resolved = describeConnectedHostCapability(deps.toolRegistry, query);
@@ -722,7 +771,11 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
           if (resolved?.status === 'ambiguous') return error(`Ambiguous connected-host capability ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
           return error(`Unknown connected-host capability ${query || '<missing>'}. Use mode:"connected_host" to inspect allowed and blocked capability ids.`);
         }
-        if (args.mode === 'connected_host_status') return output(await connectedHostStatusSummary(deps.commandContext, deps.toolRegistry));
+        if (args.mode === 'connected_host_status' || args.mode === 'daemon_status') {
+          return output(await connectedHostStatusSummary(deps.commandContext, deps.toolRegistry, {
+            includeParameters: args.includeParameters === true,
+          }));
+        }
         return error(`Unhandled agent_harness mode: ${args.mode}`);
       } catch (err) {
         return error(formatHarnessError(err));

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

@@ -3,6 +3,10 @@ import { openTtsProviderPicker, openTtsVoicePicker } from '../input/tts-settings
 
 type UiSurfaceKind = 'overlay' | 'modal' | 'workspace' | 'picker';
 
+function agentHarnessModes(...modes: readonly string[]): string {
+  return `agent_harness ${modes.map((mode) => `mode:"${mode}"`).join(', ')}`;
+}
+
 export interface AgentHarnessUiSurfaceArgs {
   readonly query?: unknown;
   readonly surfaceId?: unknown;
@@ -11,6 +15,7 @@ export interface AgentHarnessUiSurfaceArgs {
   readonly target?: unknown;
   readonly key?: unknown;
   readonly prefix?: unknown;
+  readonly includeParameters?: unknown;
   readonly limit?: unknown;
   readonly pane?: unknown;
 }
@@ -162,7 +167,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'workspace',
     summary: 'Fullscreen operator workspace with setup, knowledge, local state, channels, automation, and delegation routes.',
     command: '/agent',
-    preferredModelRoute: 'Use workspace_actions/workspace_action/run_workspace_action for model operation; use open_ui_surface only to visibly navigate.',
+    preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action')} for model operation; use mode:"open_ui_surface" only to visibly navigate.`,
     parameters: ['categoryId'],
     available: (context) => typeof context.openAgentWorkspace === 'function',
     open: (context, args) => {
@@ -179,7 +184,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Keyboard-accessible operator panel route that now opens the Agent Workspace home surface.',
     command: 'Ctrl+P',
-    preferredModelRoute: 'Use panels/panel/open_panel for panel catalog and routing, or workspace_actions for concrete model operation.',
+    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',
     open: (context) => {
       const surface = findSurfaceById('panel-picker')!;
@@ -196,7 +201,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'workspace',
     summary: 'Security review operator surface for token posture, MCP attack paths, policy posture, and plugin risk.',
     command: '/security',
-    preferredModelRoute: 'Use workspace_actions for security review actions or run_command /security review for compact read-only output.',
+    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'
@@ -218,7 +223,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'workspace',
     summary: 'Agent Knowledge operator surface for isolated status, source/node/issue libraries, item lookup, map review, connectors, ask/search, and ingest forms.',
     command: '/knowledge',
-    preferredModelRoute: 'Use agent_knowledge, agent_knowledge_ingest, workspace_actions, or run_command /knowledge for concrete model operation.',
+    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'
@@ -240,7 +245,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'workspace',
     summary: 'Provider subscription operator surface for subscription review, provider inspection, login, logout, and bundle flows.',
     command: '/subscription',
-    preferredModelRoute: 'Use workspace_actions or confirmed run_command /subscription mirrors for concrete subscription operation.',
+    preferredModelRoute: `Use mode:"workspace_actions" or ${agentHarnessModes('run_command')} for confirmed /subscription mirrors.`,
     parameters: ['pane'],
     available: (context) => (
       typeof context.openAgentWorkspace === 'function'
@@ -262,7 +267,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'modal',
     summary: 'Fullscreen settings workspace for Agent-owned configuration, subscriptions, secrets, MCP, tools, and surface settings.',
     command: '/settings',
-    preferredModelRoute: 'Use settings/get_setting/set_setting/reset_setting for model operation; use open_ui_surface only to visibly navigate.',
+    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'],
     available: (context) => typeof context.openSettingsModal === 'function',
     open: (context, args) => {
@@ -279,7 +284,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'workspace',
     summary: 'MCP server setup, trust posture, and tool inventory workspace.',
     command: '/mcp',
-    preferredModelRoute: 'Use workspace_actions, tools, and settings modes for model operation.',
+    preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'tools', 'settings')} for model operation.`,
     available: (context) => typeof context.openMcpWorkspace === 'function',
     open: (context) => {
       const surface = findSurfaceById('mcp-workspace')!;
@@ -294,7 +299,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Interactive model picker for main, helper, tool, and TTS model routes.',
     command: '/model',
-    preferredModelRoute: 'Use settings mode for direct provider.model changes, or run_command /model with confirmation when a concrete model id is known.',
+    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for direct provider.model changes, or mode:"run_command" with confirmation when a concrete model id is known.`,
     parameters: ['target'],
     available: (context) => typeof context.openModelPicker === 'function' || typeof context.openModelPickerWithTarget === 'function',
     open: (context, args) => {
@@ -315,7 +320,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Interactive provider picker for model route setup.',
     command: '/provider',
-    preferredModelRoute: 'Use settings mode for direct provider routing changes, or run confirmed slash-command mirrors for concrete provider changes.',
+    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for direct provider routing changes, or confirmed mode:"run_command" mirrors for concrete provider changes.`,
     parameters: ['target'],
     available: (context) => typeof context.openProviderPicker === 'function' || typeof context.openProviderModelPickerWithTarget === 'function',
     open: (context, args) => {
@@ -336,7 +341,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Interactive reasoning-effort selector for the current main chat model when that model exposes effort levels.',
     command: '/effort',
-    preferredModelRoute: 'Use settings/get_setting/set_setting for provider.reasoningEffort when a concrete level is known, or run_workspace_action setup-effort with confirmation.',
+    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',
     open: (context) => {
       const surface = findSurfaceById('reasoning-effort-picker')!;
@@ -364,7 +369,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Interactive streaming TTS provider picker opened from the Agent settings flow.',
     command: '/config tts.provider',
-    preferredModelRoute: 'Use settings/get_setting/set_setting for tts.provider when a concrete provider id is known; use open_ui_surface only to visibly navigate.',
+    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),
     open: (context) => {
       const surface = findSurfaceById('tts-provider-picker')!;
@@ -379,7 +384,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Interactive TTS voice picker opened from the Agent settings flow for the selected or supplied provider.',
     command: '/config tts.voice',
-    preferredModelRoute: 'Use settings/get_setting/set_setting/reset_setting for tts.voice when a concrete voice id is known; use open_ui_surface only to visibly navigate.',
+    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'],
     available: (context) => typeof context.openSelection === 'function' && Boolean(context.platform.voiceService),
     open: async (context, args) => {
@@ -539,7 +544,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'overlay',
     summary: 'Slash-command autocomplete route opened by the same shell path as typing / in an empty prompt.',
     command: '/',
-    preferredModelRoute: 'Use commands/command for model-readable command discovery and run_command for confirmed command execution.',
+    preferredModelRoute: `Use ${agentHarnessModes('commands', 'command')} for model-readable command discovery and mode:"run_command" for confirmed command execution.`,
     parameters: ['query', 'prefix', 'key'],
     available: (context) => typeof context.openSlashCommandMode === 'function',
     open: (context, args) => {
@@ -564,7 +569,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Registry-driven searchable slash-command browser opened by /commands and /help.',
     command: '/commands',
-    preferredModelRoute: 'Use commands/command for model-readable slash-command discovery and run_command for confirmed command execution.',
+    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',
     open: async (context) => {
       const surface = findSurfaceById('command-browser')!;
@@ -627,7 +632,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'overlay',
     summary: 'Registry-driven command and shortcut help overlay.',
     command: '/help',
-    preferredModelRoute: 'Use commands/command and shortcuts modes for model-readable discovery.',
+    preferredModelRoute: `Use ${agentHarnessModes('commands', 'command', 'shortcuts')} for model-readable discovery.`,
     available: (context) => typeof context.openHelpOverlay === 'function',
     open: (context) => {
       const surface = findSurfaceById('help-overlay')!;
@@ -642,7 +647,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'overlay',
     summary: 'Keyboard shortcut reference overlay.',
     command: '/shortcuts',
-    preferredModelRoute: 'Use shortcuts/keybindings modes for model-readable discovery, run_keybinding for supported shell-safe actions, and confirmed keybinding edits for binding changes.',
+    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')!;
@@ -657,7 +662,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'modal',
     summary: 'First-run and setup review wizard for Agent readiness.',
     command: '/setup',
-    preferredModelRoute: 'Use workspace setup actions and settings modes for concrete model operation.',
+    preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'settings')} for concrete setup operation.`,
     parameters: ['target=new|edit|reopen'],
     available: (context) => typeof context.openOnboardingWizard === 'function',
     open: (context, args) => {
@@ -727,22 +732,28 @@ function resolveHarnessUiSurface(args: AgentHarnessUiSurfaceArgs): UiSurfaceReso
   return null;
 }
 
-function describeSurface(context: CommandContext, surface: UiSurfaceDefinition, lookup?: UiSurfaceLookup): Record<string, unknown> {
+function describeSurface(
+  context: CommandContext,
+  surface: UiSurfaceDefinition,
+  options: { readonly includeParameters?: boolean; readonly lookup?: UiSurfaceLookup } = {},
+): Record<string, unknown> {
   return {
     id: surface.id,
     label: surface.label,
     kind: surface.kind,
     summary: surface.summary,
     command: surface.command,
-    ...(lookup ? { lookup } : {}),
+    ...(options.lookup ? { lookup: options.lookup } : {}),
     preferredModelRoute: surface.preferredModelRoute,
-    parameters: surface.parameters ?? [],
     available: surface.available(context),
-    policy: {
-      effect: 'visible-ui-navigation',
-      confirmation: 'agent_harness mode:"open_ui_surface" requires confirm:true and explicitUserRequest.',
-      boundary: 'UI surface routing opens the same visible Agent shell surface the user can open. Use first-class model tools, settings modes, workspace actions, or confirmed slash-command mirrors for actual operations.',
-    },
+    ...(options.includeParameters ? {
+      parameters: surface.parameters ?? [],
+      policy: {
+        effect: 'visible-ui-navigation',
+        confirmation: 'agent_harness mode:"open_ui_surface" requires confirm:true and explicitUserRequest.',
+        boundary: 'UI surface routing opens the same visible Agent shell surface the user can open. Use first-class model tools, settings modes, workspace actions, or confirmed slash-command mirrors for actual operations.',
+      },
+    } : {}),
   };
 }
 
@@ -753,15 +764,16 @@ export function totalHarnessUiSurfaces(): number {
 export function listHarnessUiSurfaces(context: CommandContext, args: AgentHarnessUiSurfaceArgs): readonly Record<string, unknown>[] {
   const query = readString(args.query);
   const limit = readLimit(args.limit, 200);
+  const includeParameters = args.includeParameters === true;
   return UI_SURFACES
-    .map((surface) => describeSurface(context, surface))
+    .map((surface) => describeSurface(context, surface, { includeParameters }))
     .filter((surface) => surfaceMatches(surface, query))
     .slice(0, limit);
 }
 
 export function describeHarnessUiSurface(context: CommandContext, args: AgentHarnessUiSurfaceArgs): Record<string, unknown> | null {
   const resolved = resolveHarnessUiSurface(args);
-  if (resolved?.status === 'found') return describeSurface(context, resolved.surface, resolved.lookup);
+  if (resolved?.status === 'found') return describeSurface(context, resolved.surface, { includeParameters: true, lookup: resolved.lookup });
   if (resolved?.status === 'ambiguous') {
     return { status: 'ambiguous', input: resolved.input, candidates: resolved.candidates };
   }
@@ -783,6 +795,6 @@ export async function openHarnessUiSurface(context: CommandContext, args: AgentH
   const routed = await resolved.surface.open(context, args);
   return {
     ...routed,
-    descriptor: describeSurface(context, resolved.surface, resolved.lookup),
+    descriptor: describeSurface(context, resolved.surface, { includeParameters: true, lookup: resolved.lookup }),
   };
 }

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

@@ -97,6 +97,11 @@ export function describeWorkspaceEditor(editor: AgentWorkspaceLocalEditor): Reco
   };
 }
 
+function previewText(value: string, maxLength = 120): string {
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 1).trimEnd()}...`;
+}
+
 function selectedRoutineFromArgs(
   snapshot: AgentWorkspaceRuntimeSnapshot,
   args: AgentHarnessWorkspaceActionArgs,
@@ -163,6 +168,27 @@ export function describeWorkspaceAction(
   };
 }
 
+function describeWorkspaceActionSummary(
+  category: AgentWorkspaceCategory,
+  action: AgentWorkspaceAction,
+): Record<string, unknown> {
+  return {
+    id: action.id,
+    categoryId: category.id,
+    category: category.label,
+    group: category.group,
+    label: action.label,
+    summary: previewText(action.detail),
+    kind: action.kind,
+    safety: action.safety,
+    ...(action.command ? { command: action.command } : {}),
+    ...(action.targetCategoryId ? { targetCategoryId: action.targetCategoryId } : {}),
+    ...(action.editorKind ? { editorKind: action.editorKind } : {}),
+    ...(action.localKind ? { localKind: action.localKind } : {}),
+    ...(action.localOperation ? { localOperation: action.localOperation } : {}),
+  };
+}
+
 export function listWorkspaceActions(
   context: CommandContext,
   args: AgentHarnessWorkspaceActionArgs,
@@ -178,7 +204,9 @@ export function listWorkspaceActions(
   return source
     .filter((entry) => !categoryId || entry.category.id === categoryId)
     .slice(0, limit)
-    .map((entry) => describeWorkspaceAction(entry.category, entry.action, { includeEditor, editorContext }));
+    .map((entry) => includeEditor
+      ? describeWorkspaceAction(entry.category, entry.action, { includeEditor, editorContext })
+      : describeWorkspaceActionSummary(entry.category, entry.action));
 }
 
 function workspaceActionLookupFromArgs(args: AgentHarnessWorkspaceActionArgs): { readonly source: WorkspaceActionLookup['source']; readonly input: string } | null {

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

@@ -261,11 +261,7 @@ export function createAgentKnowledgeIngestTool(
   return {
     definition: {
       name: 'agent_knowledge_ingest',
-      description: [
-        'Ingest one confirmed source into isolated Agent Knowledge.',
-        'Use only for explicit ingest/import requests.',
-        'Supports URL, file, bookmark, history, and connector sources.',
-      ].join(' '),
+      description: 'Ingest one confirmed source into isolated Agent Knowledge.',
       parameters: {
         type: 'object',
         properties: {

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

@@ -123,11 +123,7 @@ export function createAgentKnowledgeTool(
   return {
     definition: {
       name: 'agent_knowledge',
-      description: [
-        'Read isolated Agent Knowledge.',
-        'Use for status, ask/search, source/node/issue lists, item lookup, map summary, and connector inspection.',
-        'Read-only.',
-      ].join(' '),
+      description: 'Read isolated Agent Knowledge.',
       parameters: {
         type: 'object',
         properties: {

package/src/tools/agent-local-registry-tool.ts

@@ -735,10 +735,7 @@ export function createAgentLocalRegistryTool(shellPaths: ShellPathService, memor
   return {
     definition: {
       name: 'agent_local_registry',
-      description: [
-        'Inspect or update Agent-local records: memory, notes, personas, skills, bundles, and routines.',
-        'Deletion requires confirm:true plus explicitUserRequest.',
-      ].join(' '),
+      description: 'Inspect or update Agent-local records.',
       parameters: {
         type: 'object',
         properties: {

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

@@ -52,11 +52,7 @@ export function createAgentMediaGenerateTool(
   return {
     definition: {
       name: 'agent_media_generate',
-      description: [
-        'Generate one confirmed image or video artifact.',
-        'Use only for explicit media generation requests.',
-        'Returns artifact ids, not inline base64.',
-      ].join(' '),
+      description: 'Generate one confirmed image or video artifact.',
       parameters: {
         type: 'object',
         properties: {

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

@@ -78,11 +78,7 @@ export function createAgentNotifyTool(
   return {
     definition: {
       name: 'agent_notify',
-      description: [
-        'Send one confirmed plain-text notification.',
-        'Use only for explicit notify/message/alert requests.',
-        'Uses existing targets only.',
-      ].join(' '),
+      description: 'Send one confirmed plain-text notification.',
       parameters: {
         type: 'object',
         properties: {

package/src/tools/agent-operator-action-tool.ts

@@ -35,11 +35,7 @@ export function createAgentOperatorActionTool(
   return {
     definition: {
       name: 'agent_operator_action',
-      description: [
-        'Run one confirmed allowlisted operator action.',
-        'Use only for explicit approval, automation, or schedule requests.',
-        'No automation definition edits or host lifecycle.',
-      ].join(' '),
+      description: 'Run one confirmed allowlisted operator action.',
       parameters: {
         type: 'object',
         properties: {

package/src/tools/agent-operator-briefing-tool.ts

@@ -175,11 +175,7 @@ export function createAgentOperatorBriefingTool(
   return {
     definition: {
       name: 'agent_operator_briefing',
-      description: [
-        'Read connected Agent operator state for a concise briefing.',
-        'Use for pending attention, approvals, automation, schedules, or status.',
-        'Read-only.',
-      ].join(' '),
+      description: 'Read connected Agent operator state for a concise briefing.',
       parameters: {
         type: 'object',
         properties: {},

package/src/tools/agent-read-policy.ts

@@ -126,10 +126,7 @@ export function isBlockedReadPath(path: string): boolean {
 }
 
 function narrowReadToolDefinitionForAgentPolicy(tool: Tool): void {
-  tool.definition.description = [
-    'Read ordinary project files for GoodVibes Agent with bounded, non-secret, main-conversation policy.',
-    'Hidden paths, secret-looking files, broad batches, unoptimized image extraction, and oversized image reads are disabled.',
-  ].join(' ');
+  tool.definition.description = 'Read ordinary non-secret project files for GoodVibes Agent.';
   tool.definition.sideEffects = ['read_fs'];
   tool.definition.concurrency = 'serial';
 

package/src/tools/agent-reminder-schedule-tool.ts

@@ -120,11 +120,7 @@ export function createAgentReminderScheduleTool(
   return {
     definition: {
       name: 'agent_reminder_schedule',
-      description: [
-        'Schedule one confirmed GoodVibes Agent reminder.',
-        'Use only for an explicit reminder request.',
-        'No host lifecycle, background job, or Knowledge write.',
-      ].join(' '),
+      description: 'Schedule one confirmed GoodVibes Agent reminder.',
       parameters: {
         type: 'object',
         properties: {