@pellux/goodvibes-agent 1.0.34 → 1.0.35

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

@@ -13,6 +13,10 @@ export type ConnectedHostCapabilityResolution =
   | { readonly status: 'found'; readonly detail: Record<string, unknown> }
   | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] };
 
+function agentHarnessModes(...modes: readonly string[]): string {
+  return `agent_harness ${modes.map((mode) => `mode:"${mode}"`).join(', ')}`;
+}
+
 export function describeCommandPolicy(commandName: string): CommandExecutionPolicy {
   const root = commandName.replace(/^\//, '').trim().toLowerCase();
   const confirmation = 'agent_harness mode:"run_command" requires confirm:true and explicitUserRequest for every slash command invocation.';
@@ -20,7 +24,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'ui-navigation',
       confirmation,
-      preferredModelTool: 'agent_harness workspace/workspace_categories/workspace_actions/workspace_action/run_workspace_action',
+      preferredModelTool: agentHarnessModes('workspace', 'workspace_categories', 'workspace_actions', 'workspace_action', 'run_workspace_action'),
       boundary: 'Agent workspace navigation is visible shell routing. Use workspace action modes for concrete model-readable operation.',
     };
   }
@@ -28,7 +32,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'ui-navigation',
       confirmation,
-      preferredModelTool: 'agent_harness workspace_actions/workspace_action/open_ui_surface',
+      preferredModelTool: agentHarnessModes('workspace_actions', 'workspace_action', 'open_ui_surface'),
       boundary: 'Setup opens the visible Agent onboarding or setup workspace. Model-side changes should use setting modes or workspace actions.',
     };
   }
@@ -36,7 +40,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'ui-navigation',
       confirmation,
-      preferredModelTool: root === 'shortcuts' ? 'agent_harness shortcuts/keybindings/keybinding' : 'agent_harness commands/command',
+      preferredModelTool: root === 'shortcuts' ? agentHarnessModes('shortcuts', 'keybindings', 'keybinding') : agentHarnessModes('commands', 'command'),
       boundary: 'Discovery commands open visible help surfaces. The model should inspect the matching harness catalog directly before invoking commands.',
     };
   }
@@ -44,7 +48,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'read-only',
       confirmation,
-      preferredModelTool: 'agent_harness shortcuts/keybindings/keybinding/run_keybinding/set_keybinding/reset_keybinding',
+      preferredModelTool: agentHarnessModes('shortcuts', 'keybindings', 'keybinding', 'run_keybinding', 'set_keybinding', 'reset_keybinding'),
       boundary: 'Keybinding inspection is read-only. Keybinding execution or edits require explicit confirmation through agent_harness keybinding modes.',
     };
   }
@@ -52,7 +56,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'mixed',
       confirmation,
-      preferredModelTool: 'agent_harness settings/get_setting/set_setting/reset_setting',
+      preferredModelTool: agentHarnessModes('settings', 'get_setting', 'set_setting', 'reset_setting'),
       boundary: 'Model-writable settings can be changed through agent_harness. Connected-host lifecycle/listener settings remain read-only.',
     };
   }
@@ -60,7 +64,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'mixed',
       confirmation,
-      preferredModelTool: 'agent_harness settings/get_setting/set_setting/open_ui_surface',
+      preferredModelTool: agentHarnessModes('settings', 'get_setting', 'set_setting', 'open_ui_surface'),
       boundary: 'Model and reasoning-effort changes affect the current Agent chat route. Prefer settings modes for concrete values and UI surface routing for visible pickers.',
     };
   }
@@ -68,7 +72,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'mixed',
       confirmation,
-      preferredModelTool: 'agent_harness settings/get_setting/set_setting/open_ui_surface',
+      preferredModelTool: agentHarnessModes('settings', 'get_setting', 'set_setting', 'open_ui_surface'),
       boundary: 'Provider selection and custom provider files belong to Agent provider configuration. Adding, removing, or switching providers requires explicit user intent.',
     };
   }
@@ -76,7 +80,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'external-network',
       confirmation,
-      preferredModelTool: 'agent_harness settings/tools',
+      preferredModelTool: agentHarnessModes('settings', 'tools'),
       boundary: 'Model catalog refresh may call provider discovery routes and update local provider metadata. Do not run it without explicit user request.',
     };
   }
@@ -84,7 +88,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'local-state',
       confirmation,
-      preferredModelTool: 'agent_harness run_command',
+      preferredModelTool: agentHarnessModes('run_command'),
       boundary: 'Pinned model changes mutate local Agent provider preferences only and require an explicit model id.',
     };
   }
@@ -92,7 +96,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'local-state',
       confirmation,
-      preferredModelTool: 'agent_harness settings/get_setting/set_setting',
+      preferredModelTool: agentHarnessModes('settings', 'get_setting', 'set_setting'),
       boundary: 'Interaction-mode changes affect the current Agent operator notification posture and should be explicit.',
     };
   }
@@ -108,7 +112,9 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'read-only',
       confirmation,
-      preferredModelTool: root === 'compat' ? 'agent_harness service_posture/service_endpoint/connected_host_status' : 'agent_harness service_posture/service_endpoint/connected_host_status/settings/tools/open_ui_surface',
+      preferredModelTool: root === 'compat'
+        ? agentHarnessModes('service_posture', 'service_endpoint', 'connected_host_status')
+        : agentHarnessModes('service_posture', 'service_endpoint', 'connected_host_status', 'settings', 'tools', 'open_ui_surface'),
       boundary: 'Diagnostics and review commands inspect Agent, provider, MCP, security, and connected-host readiness without taking lifecycle ownership.',
     };
   }
@@ -116,7 +122,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'mixed',
       confirmation,
-      preferredModelTool: 'agent_harness run_command',
+      preferredModelTool: agentHarnessModes('run_command'),
       boundary: 'Review subcommands are read-only; bundle export/import or auth/trust bundle export writes local files and requires explicit confirmation.',
     };
   }
@@ -124,7 +130,9 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'mixed',
       confirmation,
-      preferredModelTool: root === 'secrets' || root === 'secret' ? 'agent_harness settings/get_setting/set_setting/reset_setting' : 'agent_harness workspace_actions/settings/open_ui_surface',
+      preferredModelTool: root === 'secrets' || root === 'secret'
+        ? agentHarnessModes('settings', 'get_setting', 'set_setting', 'reset_setting')
+        : agentHarnessModes('workspace_actions', 'settings', 'open_ui_surface'),
       boundary: 'Harness-owned configuration, secret, voice, subscription, and MCP commands can expose credentials or external account state. Mutations require explicit user intent and should prefer secret refs over raw values.',
     };
   }
@@ -150,7 +158,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'ui-navigation',
       confirmation,
-      preferredModelTool: 'agent_harness workspace_actions/workspace_action/run_workspace_action or agent_local_registry',
+      preferredModelTool: `${agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action')} or agent_local_registry`,
       boundary: 'Notes workspace routing is visible navigation; note record mutations should use Agent-local registry or workspace action modes.',
     };
   }
@@ -198,7 +206,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'external-network',
       confirmation,
-      preferredModelTool: 'agent_harness open_ui_surface',
+      preferredModelTool: agentHarnessModes('open_ui_surface'),
       boundary: 'Image attachment reads a local image and submits a model turn with image content. Use only for explicit user-supplied files.',
     };
   }
@@ -206,7 +214,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'external-network',
       confirmation,
-      preferredModelTool: 'agent_harness settings/open_ui_surface',
+      preferredModelTool: agentHarnessModes('settings', 'open_ui_surface'),
       boundary: 'Live TTS submits a normal prompt and may call model and speech providers; stopping playback is local runtime control.',
     };
   }
@@ -222,7 +230,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'delegated-work',
       confirmation,
-      preferredModelTool: 'agent_harness workspace_actions/workspace_action/run_workspace_action',
+      preferredModelTool: agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action'),
       boundary: 'Delegation is explicit user-directed work only; no hidden background review or separate Agent job should be created implicitly.',
     };
   }
@@ -245,7 +253,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'session-lifecycle',
       confirmation,
-      preferredModelTool: 'agent_harness commands/command/run_command',
+      preferredModelTool: agentHarnessModes('commands', 'command', 'run_command'),
       boundary: 'Session and conversation commands operate on the visible harness session lifecycle.',
     };
   }
@@ -253,7 +261,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'local-state',
       confirmation,
-      preferredModelTool: 'agent_harness workspace_actions/workspace_action/run_workspace_action or agent_harness run_command',
+      preferredModelTool: `${agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action')} or ${agentHarnessModes('run_command')}`,
       boundary: 'Conversation export writes a local workspace file and requires an explicit output intent.',
     };
   }
@@ -261,7 +269,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'ui-navigation',
       confirmation,
-      preferredModelTool: root === 'bookmarks' ? 'agent_harness open_ui_surface' : 'agent_harness run_command',
+      preferredModelTool: root === 'bookmarks' ? agentHarnessModes('open_ui_surface') : agentHarnessModes('run_command'),
       boundary: 'Conversation display navigation mutates only the visible transcript view or scroll position.',
     };
   }
@@ -269,7 +277,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'local-state',
       confirmation,
-      preferredModelTool: 'agent_harness run_keybinding',
+      preferredModelTool: agentHarnessModes('run_keybinding'),
       boundary: 'Paste reads the local clipboard and mutates the visible prompt or image attachment state.',
     };
   }
@@ -277,7 +285,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'mixed',
       confirmation,
-      preferredModelTool: 'agent_harness workspace_actions/workspace_action/run_workspace_action',
+      preferredModelTool: agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action'),
       boundary: 'Agent profile commands manage isolated Agent runtime profiles and starter templates. Mutations require explicit confirmation.',
     };
   }
@@ -285,7 +293,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'read-only',
       confirmation,
-      preferredModelTool: 'agent_harness run_command',
+      preferredModelTool: agentHarnessModes('run_command'),
       boundary: 'Pairing details are displayed for explicit operator use; the Agent does not manage connected-host listener lifecycle.',
     };
   }
@@ -330,7 +338,9 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
     return {
       effect: root === 'tui' || root === 'onboarding' ? 'ui-navigation' : 'read-only',
       confirmation,
-      preferredModelTool: root === 'onboarding' || root === 'tui' ? 'agent_harness workspace/workspace_actions/workspace_action/run_workspace_action' : 'agent_harness cli_commands/cli_command',
+      preferredModelTool: root === 'onboarding' || root === 'tui'
+        ? agentHarnessModes('workspace', 'workspace_actions', 'workspace_action', 'run_workspace_action')
+        : agentHarnessModes('cli_commands', 'cli_command'),
       boundary: 'Top-level CLI launch, setup, help, version, and completion commands are package entrypoint surfaces; use in-process workspace and slash-command bridges from the model when operating inside the TUI.',
     };
   }
@@ -346,7 +356,7 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
     return {
       effect: 'read-only',
       confirmation,
-      preferredModelTool: root === 'tasks' ? 'agent_operator_briefing' : 'agent_harness service_posture/service_endpoint/connected_host_status/connected_host/settings/tools',
+      preferredModelTool: root === 'tasks' ? 'agent_operator_briefing' : agentHarnessModes('service_posture', 'service_endpoint', 'connected_host_status', 'connected_host', 'settings', 'tools'),
       boundary: 'Diagnostics and posture commands are readable from Agent-owned settings, provider, model, and connected-host capability surfaces without taking connected-host lifecycle ownership.',
     };
   }
@@ -354,7 +364,7 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
     return {
       effect: 'local-state',
       confirmation,
-      preferredModelTool: root === 'profiles' ? 'agent_harness workspace_actions/workspace_action/run_workspace_action' : 'agent_local_registry',
+      preferredModelTool: root === 'profiles' ? agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action') : 'agent_local_registry',
       boundary: 'Local library/profile/session/bundle CLI commands operate on Agent-local data. Mutations require explicit user intent and should use first-class Agent-local tools where available.',
     };
   }
@@ -370,7 +380,7 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
     return {
       effect: 'delegated-work',
       confirmation,
-      preferredModelTool: 'agent_harness workspace_actions/workspace_action/run_workspace_action',
+      preferredModelTool: agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action'),
       boundary: 'Delegation is explicit user-directed work only; no hidden background review or separate Agent job should be created implicitly.',
     };
   }
@@ -378,7 +388,9 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
     return {
       effect: root === 'pair' ? 'external-network' : 'mixed',
       confirmation,
-      preferredModelTool: root === 'pair' ? 'agent_harness workspace_actions/workspace_action/run_workspace_action' : 'agent_harness settings/get_setting/set_setting/reset_setting or workspace_actions',
+      preferredModelTool: root === 'pair'
+        ? agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action')
+        : `${agentHarnessModes('settings', 'get_setting', 'set_setting', 'reset_setting')} or ${agentHarnessModes('workspace_actions')}`,
       boundary: 'Provider subscription, secret, and pairing flows can expose credentials or external account state. Use only explicit user-directed flows and prefer secret refs over raw values.',
     };
   }
@@ -636,10 +648,10 @@ export function connectedHostSummary(
     ownership: 'external-connected-host',
     lifecycle: 'GoodVibes Agent can use public connected-host operator routes, but does not start, stop, restart, install, expose, or mutate the host listener.',
     modes: {
-      servicePosture: 'service_posture/service_endpoint',
-      operatorMethods: 'operator_methods/operator_method',
-      liveStatus: 'connected_host_status',
-      capabilityDetail: 'connected_host_capability',
+      servicePosture: agentHarnessModes('service_posture', 'service_endpoint'),
+      operatorMethods: agentHarnessModes('operator_methods', 'operator_method'),
+      liveStatus: agentHarnessModes('connected_host_status'),
+      capabilityDetail: agentHarnessModes('connected_host_capability'),
     },
     counts: {
       routeFamilies: routeFamilies.length,

package/src/tools/agent-harness-mode-catalog.ts

@@ -0,0 +1,205 @@
+import { AGENT_HARNESS_MODES } from './agent-harness-tool-schema.ts';
+
+export type AgentHarnessMode = typeof AGENT_HARNESS_MODES[number];
+
+type HarnessModeKind = 'summary' | 'discover' | 'inspect' | 'effect' | 'alias';
+
+interface HarnessModeDescriptor {
+  readonly id: AgentHarnessMode;
+  readonly kind: HarnessModeKind;
+  readonly family: string;
+  readonly summary: string;
+  readonly next?: string;
+  readonly requiresConfirmation?: boolean;
+  readonly aliases?: readonly AgentHarnessMode[];
+  readonly parameters?: readonly string[];
+}
+
+interface HarnessModeCatalogArgs {
+  readonly query?: unknown;
+  readonly target?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+export type HarnessModeResolution =
+  | { readonly status: 'found'; readonly mode: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+export const HARNESS_MODE_DESCRIPTORS: readonly HarnessModeDescriptor[] = [
+  { id: 'summary', kind: 'summary', family: 'start', summary: 'Compact harness map, counts, posture, and mode guide.', next: 'Use modes or a plural catalog mode to drill in.', parameters: ['includeParameters'] },
+  { id: 'modes', kind: 'discover', family: 'start', summary: 'Search all agent_harness modes by task, family, effect, or id.', next: 'Use mode for one exact mode contract.', parameters: ['query', 'target', 'limit', 'includeParameters'] },
+  { id: 'mode', kind: 'inspect', family: 'start', summary: 'Inspect one agent_harness mode contract and common next step.', next: 'Use target or query with a mode id or task phrase.', parameters: ['target', 'query'] },
+  { id: 'cli_commands', kind: 'discover', family: 'cli', summary: 'List top-level package CLI mirrors for discovery only.', next: 'Use cli_command for one command.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'cli_command', kind: 'inspect', family: 'cli', summary: 'Inspect one top-level CLI command, parser result, policy, aliases, and safe model route.', parameters: ['cliCommand', 'command', 'commandName', 'target', 'query'] },
+  { id: 'panels', kind: 'discover', family: 'ui', summary: 'List built-in panel catalog state and workspace routes.', next: 'Use panel or open_panel.', parameters: ['query', 'category', 'limit', 'includeParameters'] },
+  { id: 'panel', kind: 'inspect', family: 'ui', summary: 'Inspect one built-in panel, open state, workspace route, and navigation policy.', parameters: ['panelId', 'target', 'query'] },
+  { id: 'open_panel', kind: 'effect', family: 'ui', summary: 'Route the visible shell to one built-in panel.', requiresConfirmation: true, parameters: ['panelId', 'target', 'query', 'pane', 'confirm', 'explicitUserRequest'] },
+  { id: 'ui_surfaces', kind: 'discover', family: 'ui', summary: 'List modal, picker, and visible UI surfaces the model can request.', next: 'Use ui_surface or open_ui_surface.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'ui_surface', kind: 'inspect', family: 'ui', summary: 'Inspect one visible modal or picker surface and route contract.', parameters: ['surfaceId', 'target', 'query'] },
+  { id: 'open_ui_surface', kind: 'effect', family: 'ui', summary: 'Open one visible modal or picker through the shell bridge.', requiresConfirmation: true, parameters: ['surfaceId', 'target', 'query', 'confirm', 'explicitUserRequest'] },
+  { id: 'shortcuts', kind: 'discover', family: 'keyboard', summary: 'List fixed shortcuts and keybinding overview.', next: 'Use keybindings or keybinding for configurable actions.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'keybindings', kind: 'discover', family: 'keyboard', summary: 'List configurable keybinding actions and current/default combos.', next: 'Use keybinding, run_keybinding, set_keybinding, or reset_keybinding.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'keybinding', kind: 'inspect', family: 'keyboard', summary: 'Inspect one keybinding action, route, current combos, defaults, and policy.', parameters: ['actionId', 'key', 'target', 'query'] },
+  { id: 'run_keybinding', kind: 'effect', family: 'keyboard', summary: 'Run one supported keybinding action through the shell bridge.', requiresConfirmation: true, parameters: ['actionId', 'key', 'target', 'query', 'confirm', 'explicitUserRequest'] },
+  { id: 'set_keybinding', kind: 'effect', family: 'keyboard', summary: 'Set one configurable keybinding action.', requiresConfirmation: true, parameters: ['actionId', 'combo', 'combos', 'confirm', 'explicitUserRequest'] },
+  { id: 'reset_keybinding', kind: 'effect', family: 'keyboard', summary: 'Reset one configurable keybinding action to defaults.', requiresConfirmation: true, parameters: ['actionId', 'confirm', 'explicitUserRequest'] },
+  { id: 'commands', kind: 'discover', family: 'slash', summary: 'List registered slash commands and compact policies.', next: 'Use command or run_command.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'command', kind: 'inspect', family: 'slash', summary: 'Inspect one slash command, parsed args, policy, aliases, and preferred model route.', parameters: ['command', 'commandName', 'target', 'query'] },
+  { id: 'run_command', kind: 'effect', family: 'slash', summary: 'Run one slash command through shared command dispatch.', requiresConfirmation: true, parameters: ['command', 'commandName', 'args', 'target', 'query', 'confirm', 'explicitUserRequest'] },
+  { id: 'channels', kind: 'discover', family: 'delivery', summary: 'List channel readiness, accounts, delivery posture, and safe setup keys.', next: 'Use channel or agent_channel_send.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'channel', kind: 'inspect', family: 'delivery', summary: 'Inspect one channel readiness entry and delivery policy.', parameters: ['channelId', 'target', 'query'] },
+  { id: 'notifications', kind: 'discover', family: 'delivery', summary: 'List notification target posture with webhook values redacted.', next: 'Use notification_target or agent_notify.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'notification_target', kind: 'inspect', family: 'delivery', summary: 'Inspect one notification target and safe routing policy.', parameters: ['notificationTargetId', 'target', 'query'] },
+  { id: 'provider_accounts', kind: 'discover', family: 'providers', summary: 'List provider auth, subscription, usage-window, and repair posture.', next: 'Use provider_account.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'provider_account', kind: 'inspect', family: 'providers', summary: 'Inspect one provider account/auth posture without token leakage.', parameters: ['providerId', 'target', 'query'] },
+  { id: 'mcp_servers', kind: 'discover', family: 'tools', summary: 'List MCP server/tool/security posture without exposing env or secrets.', next: 'Use mcp_server.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'mcp_server', kind: 'inspect', family: 'tools', summary: 'Inspect one MCP server, tools, schemas, auth, and trust posture.', parameters: ['mcpServerId', 'target', 'query'] },
+  { id: 'setup_posture', kind: 'discover', family: 'setup', summary: 'Inspect first-run/setup capability posture and derived readiness flags.', next: 'Use setup_item.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'setup_item', kind: 'inspect', family: 'setup', summary: 'Inspect one setup/onboarding posture item and visible remediation route.', parameters: ['setupItemId', 'target', 'query'] },
+  { id: 'model_routing', kind: 'discover', family: 'providers', summary: 'List current model/provider route, available models, pins, and safe route settings.', next: 'Use model_route.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'model_route', kind: 'inspect', family: 'providers', summary: 'Inspect one model route or model candidate and visible selection paths.', parameters: ['modelRouteId', 'target', 'query'] },
+  { id: 'pairing_posture', kind: 'discover', family: 'companion', summary: 'List companion pairing routes, token posture, and connected-host readiness without raw token output.', next: 'Use pairing_route.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'pairing_route', kind: 'inspect', family: 'companion', summary: 'Inspect one companion pairing route and safe visible handoff.', parameters: ['pairingRouteId', 'target', 'query'] },
+  { id: 'delegation_posture', kind: 'discover', family: 'delegation', summary: 'List explicit build/fix/review delegation routes and boundaries.', next: 'Use delegation_route.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'delegation_route', kind: 'inspect', family: 'delegation', summary: 'Inspect one delegation route and exact visible submission contract.', parameters: ['delegationRouteId', 'target', 'query'] },
+  { id: 'security_posture', kind: 'discover', family: 'security', summary: 'List security posture findings without exposing secrets or raw config.', next: 'Use security_finding.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'security_finding', kind: 'inspect', family: 'security', summary: 'Inspect one security posture finding and safe remediation route.', parameters: ['findingId', 'target', 'query'] },
+  { id: 'support_bundles', kind: 'discover', family: 'support', summary: 'List support bundle artifacts and redacted export/import posture.', next: 'Use support_bundle.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'support_bundle', kind: 'inspect', family: 'support', summary: 'Inspect one support bundle artifact and redaction posture.', parameters: ['bundlePath', 'target', 'query'] },
+  { id: 'media_posture', kind: 'discover', family: 'media', summary: 'List voice/media provider readiness, browser posture, and artifact routes.', next: 'Use media_provider or agent_media_generate.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'media_provider', kind: 'inspect', family: 'media', summary: 'Inspect one voice or media provider readiness entry.', parameters: ['mediaProviderId', 'target', 'query'] },
+  { id: 'sessions', kind: 'discover', family: 'sessions', summary: 'List saved sessions, bookmarks, exports, and pending approvals posture.', next: 'Use session.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'session', kind: 'inspect', family: 'sessions', summary: 'Inspect one saved session or bookmark entry.', parameters: ['sessionId', 'target', 'query'] },
+  { id: 'settings', kind: 'discover', family: 'settings', summary: 'Search Agent settings compactly by category, prefix, or query.', next: 'Use get_setting, set_setting, or reset_setting.', parameters: ['category', 'prefix', 'query', 'includeHidden', 'limit', 'includeParameters'] },
+  { id: 'get_setting', kind: 'inspect', family: 'settings', summary: 'Inspect one Agent setting descriptor, current value, default, and policy.', parameters: ['key', 'target', 'query'] },
+  { id: 'set_setting', kind: 'effect', family: 'settings', summary: 'Set one Agent-owned setting through config/secret managers.', requiresConfirmation: true, parameters: ['key', 'target', 'query', 'value', 'confirm', 'explicitUserRequest'] },
+  { id: 'reset_setting', kind: 'effect', family: 'settings', summary: 'Reset one Agent-owned setting and delete secret refs when needed.', requiresConfirmation: true, parameters: ['key', 'target', 'query', 'confirm', 'explicitUserRequest'] },
+  { id: 'workspace', kind: 'discover', family: 'workspace', summary: 'List Agent workspace categories and action counts.', next: 'Use workspace_actions or workspace_action.' },
+  { id: 'workspace_categories', kind: 'discover', family: 'workspace', summary: 'Alias of workspace for category discovery.', next: 'Use workspace_actions or workspace_action.', aliases: ['workspace'] },
+  { id: 'workspace_actions', kind: 'discover', family: 'workspace', summary: 'Search all user-facing Agent workspace actions and compact model routes.', next: 'Use workspace_action or run_workspace_action.', parameters: ['categoryId', 'query', 'limit', 'includeParameters'] },
+  { id: 'workspace_action', kind: 'inspect', family: 'workspace', summary: 'Inspect one workspace action, editor schema, route bridge, and safety policy.', parameters: ['actionId', 'command', 'target', 'query', 'recordId'] },
+  { id: 'run_workspace_action', kind: 'effect', family: 'workspace', summary: 'Run one supported workspace action or return its concrete model execution handoff.', requiresConfirmation: true, parameters: ['actionId', 'command', 'target', 'query', 'recordId', 'fields', 'confirm', 'explicitUserRequest'] },
+  { id: 'tools', kind: 'discover', family: 'tools', summary: 'List first-class model tool definitions compactly.', next: 'Use tool for full schema.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'tool', kind: 'inspect', family: 'tools', summary: 'Inspect one first-class model tool definition and JSON schema.', parameters: ['toolName', 'target', 'query'] },
+  { id: 'release_evidence', kind: 'discover', family: 'release', summary: 'List packaged release evidence artifacts compactly.', next: 'Use release_evidence_artifact.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'release_evidence_artifact', kind: 'inspect', family: 'release', summary: 'Inspect one release evidence artifact and optional content.', parameters: ['artifactId', 'target', 'query'] },
+  { id: 'release_readiness', kind: 'discover', family: 'release', summary: 'Search the release-quality readiness inventory.', next: 'Use release_readiness_item.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'release_readiness_item', kind: 'inspect', family: 'release', summary: 'Inspect one release-quality readiness inventory item.', parameters: ['itemId', 'target', 'query'] },
+  { id: 'operator_methods', kind: 'discover', family: 'operator', summary: 'List allowlisted public operator/Agent Knowledge methods and owning tools.', next: 'Use operator_method.', parameters: ['query', 'limit', 'includeParameters'] },
+  { id: 'operator_method', kind: 'inspect', family: 'operator', summary: 'Inspect one allowlisted operator method and preferred first-class model tool.', parameters: ['methodId', 'target', 'query'] },
+  { id: 'service_posture', kind: 'discover', family: 'connected-host', summary: 'Inspect connected service endpoint posture, binding, issues, and optional probes.', next: 'Use service_endpoint.', parameters: ['includeParameters'] },
+  { id: 'service_endpoint', kind: 'inspect', family: 'connected-host', summary: 'Inspect one connected service endpoint binding and lifecycle boundary.', parameters: ['endpointId', 'target', 'query'] },
+  { id: 'connected_host', kind: 'discover', family: 'connected-host', summary: 'Map connected-host capabilities, boundaries, and model tool availability.', next: 'Use connected_host_capability or connected_host_status.', parameters: ['includeParameters'] },
+  { id: 'connected_host_status', kind: 'inspect', family: 'connected-host', summary: 'Run live read-only connected-host readiness checks.', parameters: ['includeParameters'] },
+  { id: 'connected_host_capability', kind: 'inspect', family: 'connected-host', summary: 'Inspect one connected-host capability and blocked lifecycle/non-Agent surfaces.', parameters: ['capabilityId', 'target', 'query'] },
+  { id: 'daemon', kind: 'alias', family: 'connected-host', summary: 'Alias for connected_host posture. Does not expose lifecycle control.', next: 'Use connected_host for canonical naming.', aliases: ['connected_host'], parameters: ['includeParameters'] },
+  { id: 'daemon_status', kind: 'alias', family: 'connected-host', summary: 'Alias for connected_host_status live readiness. Does not expose lifecycle control.', next: 'Use connected_host_status for canonical naming.', aliases: ['connected_host_status'], parameters: ['includeParameters'] },
+] as const;
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function describeHarnessModeDescriptor(
+  descriptor: HarnessModeDescriptor,
+  options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {},
+): Record<string, unknown> {
+  return {
+    id: descriptor.id,
+    kind: descriptor.kind,
+    family: descriptor.family,
+    summary: descriptor.summary,
+    ...(descriptor.next ? { next: descriptor.next } : {}),
+    ...(descriptor.requiresConfirmation ? { requiresConfirmation: true } : {}),
+    ...(descriptor.aliases ? { aliases: descriptor.aliases } : {}),
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    ...(options.includeParameters ? {
+      parameters: descriptor.parameters ?? [],
+      route: `agent_harness mode:"${descriptor.id}"`,
+    } : {}),
+  };
+}
+
+function harnessModeSearchText(descriptor: HarnessModeDescriptor): string {
+  return [
+    descriptor.id,
+    descriptor.id.replace(/_/g, ' '),
+    descriptor.kind,
+    descriptor.family,
+    descriptor.summary,
+    descriptor.next,
+    ...(descriptor.aliases ?? []),
+    ...(descriptor.parameters ?? []),
+  ].filter(Boolean).join('\n').toLowerCase();
+}
+
+function harnessModeMatchesSearch(descriptor: HarnessModeDescriptor, input: string): boolean {
+  const text = harnessModeSearchText(descriptor);
+  const normalized = input.toLowerCase().trim();
+  if (normalized.length === 0) return true;
+  if (text.includes(normalized)) return true;
+  const tokens = normalized.split(/[^a-z0-9]+/).filter((token) => token.length > 0);
+  return tokens.length > 0 && tokens.every((token) => text.includes(token));
+}
+
+function modeLookupInput(args: HarnessModeCatalogArgs): { readonly source: 'target' | 'query'; readonly input: string } | null {
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+export function listHarnessModes(args: HarnessModeCatalogArgs): Record<string, unknown> {
+  const lookup = modeLookupInput(args);
+  const limit = readLimit(args.limit, 120);
+  const normalized = lookup?.input.toLowerCase() ?? '';
+  const modes = HARNESS_MODE_DESCRIPTORS
+    .filter((descriptor) => harnessModeMatchesSearch(descriptor, normalized))
+    .map((descriptor) => describeHarnessModeDescriptor(descriptor, { includeParameters: args.includeParameters === true }))
+    .slice(0, limit);
+  return {
+    modes,
+    returned: modes.length,
+    total: HARNESS_MODE_DESCRIPTORS.length,
+    families: Array.from(new Set(HARNESS_MODE_DESCRIPTORS.map((descriptor) => descriptor.family))).sort(),
+    policy: 'Mode discovery is read-only. Effect modes still require confirm:true and explicitUserRequest.',
+  };
+}
+
+export function describeHarnessMode(args: HarnessModeCatalogArgs): HarnessModeResolution {
+  const lookup = modeLookupInput(args);
+  if (!lookup) {
+    return {
+      status: 'missing_lookup',
+      usage: 'mode inspection requires target or query. Use mode:"modes" to search available harness modes.',
+    };
+  }
+  const normalized = lookup.input.toLowerCase();
+  const exact = HARNESS_MODE_DESCRIPTORS.find((descriptor) => descriptor.id === lookup.input);
+  if (exact) return { status: 'found', mode: describeHarnessModeDescriptor(exact, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const insensitive = HARNESS_MODE_DESCRIPTORS.find((descriptor) => descriptor.id.toLowerCase() === normalized);
+  if (insensitive) return { status: 'found', mode: describeHarnessModeDescriptor(insensitive, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const searched = HARNESS_MODE_DESCRIPTORS.filter((descriptor) => harnessModeMatchesSearch(descriptor, normalized));
+  if (searched.length === 1) {
+    return { status: 'found', mode: describeHarnessModeDescriptor(searched[0]!, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
+  }
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 12).map((descriptor) => describeHarnessModeDescriptor(descriptor)),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown harness mode ${lookup.input}. Use mode:"modes" to inspect available modes.`,
+  };
+}

package/src/tools/agent-harness-operator-methods.ts

@@ -119,7 +119,7 @@ function agentKnowledgeMethods(): readonly OperatorMethodDescriptor[] {
       route: method.route,
       effect: readOnly ? 'read-only-network' : 'confirmed-agent-knowledge-write',
       owner: 'connected-host',
-      preferredModelTool: readOnly ? 'agent_knowledge' : key === 'reindex' ? 'agent_harness run_command' : 'agent_knowledge_ingest',
+      preferredModelTool: readOnly ? 'agent_knowledge' : key === 'reindex' ? 'agent_harness mode:"run_command"' : 'agent_knowledge_ingest',
       confirmation: readOnly ? 'Read-only; use the owning first-class tool.' : 'Requires explicit user request and confirmation through the owning tool or command bridge.',
       boundary: 'Isolated Agent Knowledge route family only; default knowledge and non-Agent knowledge segments are forbidden.',
       ...(readOnly ? {} : {
@@ -161,7 +161,7 @@ function allOperatorMethods(): readonly OperatorMethodDescriptor[] {
       route: '/api/automation/schedules',
       effect: 'confirmed-connected-host-state',
       owner: 'connected-host',
-      preferredModelTool: 'agent_reminder_schedule or agent_harness run_workspace_action',
+      preferredModelTool: 'agent_reminder_schedule or agent_harness mode:"run_workspace_action"',
       confirmation: 'Requires explicit user request and confirmation.',
       boundary: 'Connected schedule creation only; no hidden local scheduler or separate Agent job.',
       parameters: [

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

@@ -83,7 +83,7 @@ function describeEndpoint(
         effect: 'read-only',
         modelOperation: 'Inspect endpoint binding, network-facing posture, and optional reachability only.',
         lifecycle: 'GoodVibes Agent does not start, stop, restart, install, expose, or mutate connected-host listeners.',
-        settings: 'Use agent_harness settings/get_setting for read-only inspection of endpoint settings; connected-host lifecycle/listener settings stay locked in Agent.',
+        settings: 'Use agent_harness mode:"settings" or mode:"get_setting" for read-only inspection of endpoint settings; connected-host lifecycle/listener settings stay locked in Agent.',
       },
     } : {}),
   };

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

@@ -189,7 +189,7 @@ function describeItem(
         inspectSetupItem: 'agent_harness mode:"setup_item"',
         openOnboarding: 'agent_harness mode:"open_ui_surface" surfaceId:"onboarding" confirm:true explicitUserRequest:"..."',
         setupWorkspace: 'agent_harness mode:"workspace_action" target:"setup"',
-        settings: 'agent_harness modes settings/get_setting/set_setting/reset_setting',
+        settings: 'agent_harness mode:"settings"; inspect or mutate with get_setting, set_setting, or reset_setting',
         providerRouting: 'agent_harness mode:"model_routing"',
         providerAccounts: 'agent_harness mode:"provider_accounts"',
         channels: 'agent_harness mode:"channels"',

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

@@ -1,5 +1,5 @@
 export const AGENT_HARNESS_MODES = [
-  'summary', 'cli_commands', 'cli_command', 'panels', 'panel', 'open_panel',
+  'summary', 'modes', 'mode', 'cli_commands', 'cli_command', 'panels', 'panel', 'open_panel',
   'ui_surfaces', 'ui_surface', 'open_ui_surface',
   'shortcuts', 'keybindings', 'keybinding', 'run_keybinding', 'set_keybinding', 'reset_keybinding',
   'commands', 'command', 'run_command', 'channels', 'channel', 'notifications', 'notification_target',

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;
@@ -130,6 +129,7 @@ function error(message: string): { readonly success: false; readonly error: stri
 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',
@@ -139,6 +139,7 @@ function compactHarnessModeGuide(): Record<string, unknown> {
       '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',
@@ -175,9 +176,10 @@ function detailedHarnessModelAccessGuide(): Record<string, string> {
     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.',
+    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.',
@@ -425,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),
@@ -472,6 +475,13 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             }),
           });
         }
+        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({