@pellux/goodvibes-agent 1.0.33 → 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.',
     };
   }
@@ -618,22 +630,40 @@ export function describeConnectedHostCapability(
   return null;
 }
 
-export function connectedHostSummary(context: CommandContext, toolRegistry: ToolRegistry): Record<string, unknown> {
+export function connectedHostSummary(
+  context: CommandContext,
+  toolRegistry: ToolRegistry,
+  options: { readonly includeParameters?: boolean } = {},
+): Record<string, unknown> {
   const shellPaths = context.workspace.shellPaths;
   const homeDirectory = shellPaths?.homeDirectory ?? context.platform.configManager.getHomeDirectory() ?? '';
   const connection = resolveAgentConnectedHostConnection(context.platform.configManager, homeDirectory);
+  const routeFamilies = connectedHostRouteFamilies();
+  const capabilities = connectedHostCapabilityMap(toolRegistry);
+  const blockedCapabilities = blockedConnectedHostCapabilities();
   return {
     baseUrl: connection.baseUrl,
     operatorToken: connection.token ? 'configured' : 'missing',
     tokenPath: connection.tokenPath,
     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.',
-    servicePostureMode: 'Use agent_harness mode:"service_posture" for endpoint binding, network-facing posture, issue, and redacted-log diagnostics. Use mode:"service_endpoint" for one endpoint.',
-    operatorMethodMode: 'Use agent_harness mode:"operator_methods" for the public operator and Agent Knowledge method catalog. Use mode:"operator_method" for one method.',
-    statusMode: 'Use agent_harness mode:"connected_host_status" for live read-only reachability, SDK compatibility, token posture, and Agent Knowledge route readiness.',
-    routeFamilies: connectedHostRouteFamilies(),
-    capabilities: connectedHostCapabilityMap(toolRegistry),
-    blockedCapabilities: blockedConnectedHostCapabilities(),
+    modes: {
+      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,
+      allowedCapabilities: capabilities.length,
+      availableCapabilities: capabilities.filter((capability) => capability.available === true).length,
+      blockedCapabilities: blockedCapabilities.length,
+    },
+    ...(options.includeParameters === true ? {
+      routeFamilies,
+      capabilities,
+      blockedCapabilities,
+    } : {}),
   };
 }
 

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-model-routing.ts

@@ -320,19 +320,19 @@ function describeRoute(route: RouteCandidate, options: { readonly includeParamet
     commands: route.commands,
     uiSurfaces: route.uiSurfaces,
     ...(options.lookup ? { lookup: options.lookup } : {}),
-    policy: {
-      effect: 'read-only',
-      values: 'Model routing posture returns model ids, provider ids, route state, capabilities, and safe setting keys only; provider credentials are never returned.',
-      mutation: 'Model/provider selection, catalog refresh, favorites, custom provider edits, and route setting changes stay explicit user-facing picker, settings, workspace, or slash-command flows.',
-    },
     ...(options.includeParameters ? {
+      policy: {
+        effect: 'read-only',
+        values: 'Model routing posture returns model ids, provider ids, route state, capabilities, and safe setting keys only; provider credentials are never returned.',
+        mutation: 'Model/provider selection, catalog refresh, favorites, custom provider edits, and route setting changes stay explicit user-facing picker, settings, workspace, or slash-command flows.',
+      },
       modelAccess: {
         inspectRouting: 'agent_harness mode:"model_routing"',
         inspectRoute: 'agent_harness mode:"model_route"',
         settingRead: 'agent_harness mode:"get_setting"',
         settingMutation: 'agent_harness mode:"set_setting" confirm:true explicitUserRequest:"..."',
-        openModelPicker: 'agent_harness mode:"open_ui_surface" surfaceId:"model-picker" confirm:true',
-        openProviderPicker: 'agent_harness mode:"open_ui_surface" surfaceId:"provider-picker" confirm:true',
+        openModelPicker: 'agent_harness mode:"open_ui_surface" surfaceId:"model-picker" confirm:true explicitUserRequest:"..."',
+        openProviderPicker: 'agent_harness mode:"open_ui_surface" surfaceId:"provider-picker" confirm:true explicitUserRequest:"..."',
       },
     } : {}),
   };
@@ -350,19 +350,19 @@ function describeModel(model: ModelCandidate, options: { readonly includeParamet
     pinned: model.pinned,
     contextWindow: model.contextWindow,
     reasoningEffort: model.reasoningEffort,
-    capabilities: model.capabilities,
     ...(options.lookup ? { lookup: options.lookup } : {}),
-    policy: {
-      effect: 'read-only',
-      mutation: 'Selecting this model stays a visible picker, settings, workspace, or slash-command flow with explicit user request.',
-    },
     ...(options.includeParameters ? {
+      capabilities: model.capabilities,
+      policy: {
+        effect: 'read-only',
+        mutation: 'Selecting this model stays a visible picker, settings, workspace, or slash-command flow with explicit user request.',
+      },
       modelAccess: {
         selectModelCommand: `/model ${model.registryKey}`,
         selectProviderCommand: `/provider ${model.providerId}`,
         pinCommand: `/pin ${model.registryKey}`,
         unpinCommand: `/unpin ${model.registryKey}`,
-        setMainModel: `agent_harness mode:"set_setting" key:"provider.model" value:"${model.registryKey}" confirm:true`,
+        setMainModel: `agent_harness mode:"set_setting" key:"provider.model" value:"${model.registryKey}" confirm:true explicitUserRequest:"..."`,
       },
     } : {}),
   };
@@ -433,7 +433,7 @@ export async function modelRoutingSummary(context: CommandContext, args: AgentHa
         reasoningEffort: modelReasoning(currentModel),
         capabilities: modelCapabilities(currentModel),
         pinned: false,
-      }) : null,
+      }, { includeParameters }) : null,
     },
     providers: providerIds,
     routes: filteredRoutes.slice(0, limit).map((route) => describeRoute(route, { includeParameters })),

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

@@ -25,6 +25,11 @@ function readLimit(value: unknown, fallback: number): number {
   return Math.max(1, Math.min(500, Math.trunc(parsed)));
 }
 
+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 modelToolSearchText(tool: HarnessModelToolDefinition): string {
   return [
     tool.name,
@@ -45,7 +50,7 @@ function modelToolLookupFromArgs(args: AgentHarnessModelToolCatalogArgs): { read
 function describeModelTool(tool: HarnessModelToolDefinition, options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {}): Record<string, unknown> {
   return {
     name: tool.name,
-    description: tool.description,
+    ...(options.includeParameters ? { description: tool.description } : { summary: previewText(tool.description) }),
     sideEffects: tool.sideEffects ?? [],
     concurrency: tool.concurrency ?? 'parallel',
     supportsProgress: tool.supportsProgress ?? false,
@@ -58,7 +63,7 @@ function describeModelTool(tool: HarnessModelToolDefinition, options: { readonly
 function describeModelToolCandidates(tools: readonly HarnessModelToolDefinition[]): readonly Record<string, unknown>[] {
   return tools.slice(0, 8).map((tool) => ({
     toolName: tool.name,
-    description: tool.description,
+    summary: previewText(tool.description),
     sideEffects: tool.sideEffects ?? [],
   }));
 }