@pellux/goodvibes-agent 1.0.4 → 1.0.5

package/docs/README.md

@@ -22,7 +22,7 @@ Important baseline constraints:
 - Agent depends on `@pellux/goodvibes-sdk@0.33.35`.
 - Agent connects to a GoodVibes host owned outside this product.
 - Agent does not start, stop, restart, install, uninstall, or own the connected GoodVibes host.
-- User-facing Agent workspace actions, built-in panels, top-level CLI mirrors, fixed shortcuts, configurable keybindings, slash commands, command policy metadata, model tools, settings, local registries, and connected-host capability boundaries are model-visible through Agent-owned tools. Mutations remain explicit and confirmation-gated.
+- User-facing Agent workspace actions, built-in panels, modal/overlay/picker UI surfaces, top-level CLI mirrors, fixed shortcuts, configurable keybindings, slash commands, command policy metadata, model tools, settings, local registries, and connected-host capability boundaries are model-visible through Agent-owned tools. Mutations and visible UI routing remain explicit and confirmation-gated.
 - Agent Knowledge uses only `/api/goodvibes-agent/knowledge/*`; there is no default knowledge or non-Agent product fallback.
 - Agent supports isolated Agent homes with `GOODVIBES_AGENT_HOME=<path>` and named profile homes with `goodvibes-agent profiles create <name> --template <starter> --yes` plus `--agent-profile <name>`.
 - Agent supports connected-host URL overrides with `--runtime-url http://host:port` or `GOODVIBES_AGENT_RUNTIME_URL=http://host:port`; these only change the Agent connection target.

package/docs/getting-started.md

@@ -44,7 +44,7 @@ After setup has been applied once, the TUI opens directly into the Agent operato
 
 Press `/` inside the Agent workspace to search every workspace action by name, category, command, or detail. Use that finder before reaching for shell commands; CLI subcommands are scriptable mirrors of these TUI workflows.
 
-The model can inspect and use the same harness surface through Agent-owned tools. `agent_harness` exposes workspace action discovery, built-in panel discovery/routing, top-level CLI mirror discovery, fixed shortcut and configurable keybinding discovery, keybinding mutation with confirmation, slash-command discovery, command policy metadata, command execution with confirmation, model tool discovery, settings inspection/mutation, and connected-host posture. CLI mirror modes are read-only catalog/parser inspection and point the model to the matching in-process tool, workspace action, setting mode, or slash-command mirror. Panel modes expose catalog/open state and route visible panel/workspace changes through the current Agent shell bridge with confirmation. Shortcut modes expose the fixed runtime/editor shortcuts and the live keybindings table; confirmed keybinding edits write the same `keybindings.json` file the user edits and reload the runtime manager. Workspace action discovery can include editor field schemas with `includeParameters:true`, including starter-template defaults for profile creation and selected-routine defaults for routine schedule promotion when `recordId` is supplied. Selection-based local workspace actions accept a local `recordId`, so the model can use the same note promotion and local registry flows as the TUI. First-class model tools cover the main product workflows directly: Agent Knowledge, Agent Knowledge ingest, Agent-local memory/notes/personas/skills/routines, operator actions, notifications, channel sends, reminders, generated media, and work plans.
+The model can inspect and use the same harness surface through Agent-owned tools. `agent_harness` exposes workspace action discovery, built-in panel discovery/routing, modal/overlay/picker UI surface discovery/routing, top-level CLI mirror discovery, fixed shortcut and configurable keybinding discovery, keybinding mutation with confirmation, slash-command discovery, command policy metadata, command execution with confirmation, model tool discovery, settings inspection/mutation, and connected-host posture. CLI mirror modes are read-only catalog/parser inspection and point the model to the matching in-process tool, workspace action, setting mode, or slash-command mirror. Panel modes expose catalog/open state and route visible panel/workspace changes through the current Agent shell bridge with confirmation. UI surface modes expose help, shortcuts, context, bookmarks, model/provider pickers, session/profile pickers, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose the fixed runtime/editor shortcuts and the live keybindings table; confirmed keybinding edits write the same `keybindings.json` file the user edits and reload the runtime manager. Workspace action discovery can include editor field schemas with `includeParameters:true`, including starter-template defaults for profile creation and selected-routine defaults for routine schedule promotion when `recordId` is supplied. Selection-based local workspace actions accept a local `recordId`, so the model can use the same note promotion and local registry flows as the TUI. First-class model tools cover the main product workflows directly: Agent Knowledge, Agent Knowledge ingest, Agent-local memory/notes/personas/skills/routines, operator actions, notifications, channel sends, reminders, generated media, and work plans.
 
 Use the Artifacts area for concrete files and generated output: attach images to prompts, export conversations or saved sessions, ingest local source files and URL lists into Agent Knowledge, import bookmarks or browser history, inspect source records, and generate media artifacts from confirmed prompts.
 
@@ -122,7 +122,7 @@ Use `/channels` inside the TUI for channel readiness and exact confirmed sends.
 
 The main assistant conversation can perform narrow confirmed operator actions when the user explicitly asks for a specific target: approve/deny/cancel one approval, run/pause/resume one automation job, cancel/retry one automation run, or run one schedule. Those calls use only public connected-host routes, require confirmation, and do not create, edit, or delete automation definitions.
 
-When the main assistant conversation needs to change Agent settings, change Agent keybindings, or run a user-facing harness action, it should use `agent_harness` rather than generic SDK context/settings tools. Setting descriptors report writability, workspace visibility, and lock reasons; keybinding descriptors report fixed shortcuts, resolved bindings, defaults, custom state, and config path; secret-backed settings store raw values through the secret manager; connected-host lifecycle settings stay read-only in Agent; and destructive local record deletion requires explicit confirmation.
+When the main assistant conversation needs to change Agent settings, change Agent keybindings, open a visible UI surface, or run a user-facing harness action, it should use `agent_harness` rather than generic SDK context/settings tools. Setting descriptors report writability, workspace visibility, and lock reasons; keybinding descriptors report fixed shortcuts, resolved bindings, defaults, custom state, and config path; UI surface descriptors report the visible shell opener, preferred model route, and confirmation policy; secret-backed settings store raw values through the secret manager; connected-host lifecycle settings stay read-only in Agent; and destructive local record deletion requires explicit confirmation.
 
 ## Connected GoodVibes Host
 

package/docs/tools-and-commands.md

@@ -43,14 +43,16 @@ Host-management and coding-first commands that would imply connected-host lifecy
 
 The main Agent model has an Agent-owned harness bridge rather than generic SDK settings/context control. Use these model tools as the supported parity layer:
 
-- `agent_harness`: inspect workspace categories/actions, inspect built-in panels, inspect top-level CLI mirrors, inspect fixed shortcuts and configurable keybindings, inspect slash commands and command policy metadata, run concrete workspace or slash-command mirrors with confirmation, inspect model tools, inspect or change Agent settings/keybindings, and inspect connected-host posture.
+- `agent_harness`: inspect workspace categories/actions, inspect built-in panels, inspect modal/overlay/picker UI surfaces, inspect top-level CLI mirrors, inspect fixed shortcuts and configurable keybindings, inspect slash commands and command policy metadata, run concrete workspace or slash-command mirrors with confirmation, inspect model tools, inspect or change Agent settings/keybindings, and inspect connected-host posture.
 - `agent_local_registry`: inspect and maintain Agent-local memory, notes, personas, skills, skill bundles, and routines. Deleting local records requires `confirm:true` and `explicitUserRequest`.
 - `agent_knowledge` and `agent_knowledge_ingest`: ask/search and ingest into the isolated Agent Knowledge segment.
 - `agent_operator_briefing` and `agent_operator_action`: inspect connected work/approval/automation posture, or run exact confirmed approval/automation actions.
 - `agent_work_plan`: keep the visible Agent-local work plan current from the conversation.
 - `agent_channel_send`, `agent_notify`, `agent_reminder_schedule`, and `agent_media_generate`: perform confirmed external delivery, notification, reminder, or media actions when the user explicitly asks.
 
-`agent_harness` discovery modes are read-only. `summary` reports the model access map; `panels` and `panel` return the built-in panel catalog, current open/focused state, and each panel's matching Agent workspace route; `cli_commands` and `cli_command` return top-level package CLI mirror metadata, parser output, blocked command tokens, and preferred in-process model routes; `shortcuts` returns fixed runtime/editor shortcuts plus configurable keybindings; `keybindings` and `keybinding` return the live resolved keybinding table, default bindings, custom state, and config path; `commands` and `command` return slash-command descriptions plus effect/confirmation/preferred-tool/boundary policy metadata; `workspace_actions` lists Agent workspace actions and can inline editor field schemas with `includeParameters:true`; `workspace_action` returns one action with its editor schema; `tools` can inline model tool JSON schemas with `includeParameters:true`; `settings` returns setting descriptors plus setting policy; and `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability.
+`agent_harness` discovery modes are read-only. `summary` reports the model access map; `panels` and `panel` return the built-in panel catalog, current open/focused state, and each panel's matching Agent workspace route; `ui_surfaces` and `ui_surface` return modal, overlay, picker, and workspace entrypoints with shell-opener availability and preferred model routes; `cli_commands` and `cli_command` return top-level package CLI mirror metadata, parser output, blocked command tokens, and preferred in-process model routes; `shortcuts` returns fixed runtime/editor shortcuts plus configurable keybindings; `keybindings` and `keybinding` return the live resolved keybinding table, default bindings, custom state, and config path; `commands` and `command` return slash-command descriptions plus effect/confirmation/preferred-tool/boundary policy metadata; `workspace_actions` lists Agent workspace actions and can inline editor field schemas with `includeParameters:true`; `workspace_action` returns one action with its editor schema; `tools` can inline model tool JSON schemas with `includeParameters:true`; `settings` returns setting descriptors plus setting policy; and `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability.
+
+`open_ui_surface` is a confirmation-gated visible navigation mode for the same shell surfaces the user can open: Agent workspace, settings, MCP workspace, model/provider pickers, session/profile pickers, bookmarks, context inspector, help, shortcuts, and onboarding. It does not perform hidden operations; use first-class model tools, settings modes, workspace actions, or confirmed slash-command mirrors for actual state changes.
 
 `set_keybinding` and `reset_keybinding` are confirmation-gated control modes. They write the same Agent `keybindings.json` file exposed by `/keybindings`, reload the runtime keybinding manager, and leave fixed runtime/editor shortcuts read-only.
 
@@ -58,7 +60,7 @@ The main Agent model has an Agent-owned harness bridge rather than generic SDK s
 
 CLI mirror modes are catalog and parser inspection only. When the user asks the model to operate from inside the main conversation, use the returned first-class model tool, workspace action, setting mode, or confirmed slash-command mirror instead of launching a hidden nested `goodvibes-agent` process.
 
-Setting writes, setting resets, keybinding writes/resets, slash-command invocation, workspace-action invocation, local record deletion, channel sends, notifications, reminders, media generation, and connected-host operator mutations require explicit user request and confirmation. Secret-backed settings are stored through the secret manager, and connected-host lifecycle/listener settings remain read-only in Agent.
+Setting writes, setting resets, keybinding writes/resets, UI surface routing, slash-command invocation, workspace-action invocation, local record deletion, channel sends, notifications, reminders, media generation, and connected-host operator mutations require explicit user request and confirmation. Secret-backed settings are stored through the secret manager, and connected-host lifecycle/listener settings remain read-only in Agent.
 
 Selection-based local workspace actions use the same bridge. `agent_harness` reports the required model tool for each local action; for actions that depend on the TUI selection, call `run_workspace_action` with the selected local `recordId`. Note promotion actions can prefill and create memory, personas, skills, routines, or isolated Agent Knowledge URL ingests through the matching first-class model tool. Profile creation schemas include the current runtime starter-template inventory, and routine schedule schemas prefill the selected routine when `recordId` or a `routineId` field matches a local routine.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "private": false,
   "description": "GoodVibes personal operator assistant TUI with a proactive Agent product brain, isolated Agent Knowledge, local profiles, routines, skills, personas, and explicit build delegation.",
   "type": "module",

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

@@ -0,0 +1,127 @@
+export const AGENT_HARNESS_MODES = [
+  'summary', 'cli_commands', 'cli_command', 'panels', 'panel', 'open_panel',
+  'ui_surfaces', 'ui_surface', 'open_ui_surface',
+  'shortcuts', 'keybindings', 'keybinding', 'set_keybinding', 'reset_keybinding',
+  'commands', 'command', 'run_command', 'settings', 'get_setting', 'set_setting',
+  'reset_setting', 'workspace', 'workspace_categories', 'workspace_actions',
+  'workspace_action', 'run_workspace_action', 'tools', 'connected_host',
+] as const;
+
+const KEY_COMBO_PARAMETER_SCHEMA = {
+  type: 'object',
+  properties: { key: { type: 'string' }, ctrl: { type: 'boolean' }, shift: { type: 'boolean' }, alt: { type: 'boolean' } },
+  required: ['key'],
+  additionalProperties: false,
+} as const;
+
+export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
+  mode: {
+    type: 'string',
+    enum: AGENT_HARNESS_MODES,
+    description: 'Harness operation to perform.',
+  },
+  query: {
+    type: 'string',
+    description: 'Search text for command, setting, tool, or UI surface catalogs.',
+  },
+  command: {
+    type: 'string',
+    description: 'Full slash command string for mode run_command, for example "/settings get provider.model". In cli_command mode this may also hold a top-level CLI string such as "goodvibes-agent status --json".',
+  },
+  cliCommand: {
+    type: 'string',
+    description: 'Top-level CLI command string for mode cli_command, for example "goodvibes-agent status --json" or "profiles list". This mode is read-only metadata/parse inspection.',
+  },
+  commandName: {
+    type: 'string',
+    description: 'Slash command root without the leading slash for mode command or run_command, or a top-level CLI command token for cli_command.',
+  },
+  args: {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Slash command argument tokens for mode run_command when commandName is used.',
+  },
+  categoryId: {
+    type: 'string',
+    description: 'Agent workspace category id for workspace action filtering or ui surface routing.',
+  },
+  surfaceId: {
+    type: 'string',
+    description: 'UI surface id for ui_surface or open_ui_surface modes.',
+  },
+  panelId: {
+    type: 'string',
+    description: 'Built-in panel id for panel or open_panel modes.',
+  },
+  actionId: {
+    type: 'string',
+    description: 'Agent workspace action id for workspace_action or run_workspace_action, or keybinding action id for keybinding/set_keybinding/reset_keybinding.',
+  },
+  fields: {
+    type: 'object',
+    additionalProperties: { type: 'string' },
+    description: 'Field values for run_workspace_action when the workspace action opens an editor form.',
+  },
+  combo: {
+    ...KEY_COMBO_PARAMETER_SCHEMA,
+    description: 'Single key combo for set_keybinding, for example { "key": "g", "ctrl": true }.',
+  },
+  combos: {
+    type: 'array',
+    items: KEY_COMBO_PARAMETER_SCHEMA,
+    description: 'Multiple key combos for set_keybinding.',
+  },
+  recordId: {
+    type: 'string',
+    description: 'Selected Agent-local record id for selection-based local workspace operations.',
+  },
+  key: {
+    type: 'string',
+    description: 'Agent setting key for get_setting, set_setting, or reset_setting.',
+  },
+  value: {
+    anyOf: [
+      { type: 'string' },
+      { type: 'number' },
+      { type: 'boolean' },
+    ],
+    description: 'Setting value for set_setting. Strings, booleans, numbers, and enum strings are accepted.',
+  },
+  target: {
+    type: 'string',
+    description: 'Optional UI target, such as a model-picker target or settings target key.',
+  },
+  category: {
+    type: 'string',
+    description: 'Setting category filter such as provider, behavior, tools, ui, tts, permissions, automation, or surfaces.',
+  },
+  prefix: {
+    type: 'string',
+    description: 'Setting key prefix filter such as surfaces.slack.',
+  },
+  includeHidden: {
+    type: 'boolean',
+    description: 'Include settings hidden from the Agent workspace because they are host-owned or non-Agent lifecycle settings.',
+  },
+  includeParameters: {
+    type: 'boolean',
+    description: 'Include model tool JSON schemas in tools mode, or workspace editor field schemas in workspace_actions mode.',
+  },
+  limit: {
+    type: 'number',
+    description: 'Maximum catalog entries to return.',
+  },
+  pane: {
+    type: 'string',
+    enum: ['top', 'bottom'],
+    description: 'Preferred panel pane for open_panel when the current shell supports panel routing.',
+  },
+  confirm: {
+    type: 'boolean',
+    description: 'Required true for set_setting, reset_setting, run_command, open_panel, open_ui_surface, and mutating run_workspace_action calls after an explicit user request.',
+  },
+  explicitUserRequest: {
+    type: 'string',
+    description: 'Exact user request or faithful short summary authorizing a setting mutation or harness UI/command invocation.',
+  },
+} as const;

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

@@ -22,6 +22,8 @@ import { describeHarnessKeybinding, listHarnessKeybindings, listHarnessShortcuts
 import { describeHarnessPanel, listHarnessPanels, openHarnessPanel, totalHarnessPanels } from './agent-harness-panel-metadata.ts';
 import { describeLocalWorkspaceModelExecution, runLocalWorkspaceAction } from './agent-harness-local-operations.ts';
 import { listHarnessModelTools } from './agent-harness-model-tool-catalog.ts';
+import { AGENT_HARNESS_MODES, AGENT_HARNESS_PARAMETER_PROPERTIES } from './agent-harness-tool-schema.ts';
+import { describeHarnessUiSurface, listHarnessUiSurfaces, openHarnessUiSurface, totalHarnessUiSurfaces } from './agent-harness-ui-surface-metadata.ts';
 import {
   connectedHostSummary,
   describeCommandPolicy,
@@ -35,15 +37,7 @@ import {
   setHarnessSetting,
 } from '../agent/harness-control.ts';
 
-const MODES = [
-  'summary', 'cli_commands', 'cli_command', 'panels', 'panel', 'open_panel',
-  'shortcuts', 'keybindings', 'keybinding', 'set_keybinding', 'reset_keybinding',
-  'commands', 'command', 'run_command', 'settings', 'get_setting', 'set_setting',
-  'reset_setting', 'workspace', 'workspace_categories', 'workspace_actions',
-  'workspace_action', 'run_workspace_action', 'tools', 'connected_host',
-] as const;
-
-type AgentHarnessMode = typeof MODES[number];
+type AgentHarnessMode = typeof AGENT_HARNESS_MODES[number];
 
 interface AgentHarnessToolArgs {
   readonly mode?: unknown;
@@ -59,8 +53,10 @@ interface AgentHarnessToolArgs {
   readonly fields?: unknown;
   readonly combo?: unknown;
   readonly combos?: unknown;
+  readonly surfaceId?: unknown;
   readonly key?: unknown;
   readonly value?: unknown;
+  readonly target?: unknown;
   readonly category?: unknown;
   readonly prefix?: unknown;
   readonly includeHidden?: unknown;
@@ -83,7 +79,7 @@ interface WorkspaceEditorContext {
 }
 
 function isMode(value: unknown): value is AgentHarnessMode {
-  return typeof value === 'string' && MODES.includes(value as AgentHarnessMode);
+  return typeof value === 'string' && AGENT_HARNESS_MODES.includes(value as AgentHarnessMode);
 }
 
 function readString(value: unknown): string {
@@ -115,13 +111,6 @@ function output(value: unknown): { readonly success: true; readonly output: stri
 
 function error(message: string): { readonly success: false; readonly error: string } { return { success: false, error: message }; }
 
-const KEY_COMBO_PARAMETER_SCHEMA = {
-  type: 'object',
-  properties: { key: { type: 'string' }, ctrl: { type: 'boolean' }, shift: { type: 'boolean' }, alt: { type: 'boolean' } },
-  required: ['key'],
-  additionalProperties: false,
-} as const;
-
 function commandMatches(command: SlashCommand, query: string): boolean {
   if (!query) return true;
   const haystack = [
@@ -514,115 +503,13 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
       name: 'agent_harness',
       description: [
         'Discover and operate the GoodVibes Agent harness from the main conversation.',
-        'Use this tool to inspect Agent workspace actions, built-in panels, top-level CLI mirrors, keybindings, slash commands with policy metadata, model tools, connected-host capabilities, and Agent settings, or to invoke a workspace action/command through the same in-process command registry the user uses in the TUI.',
-        'Discovery modes are read-only. Setting/keybinding writes, resets, slash command invocation, and workspace action invocation require confirm:true plus explicitUserRequest.',
+        'Use this tool to inspect Agent workspace actions, built-in panels, top-level CLI mirrors, UI surfaces, keybindings, slash commands with policy metadata, model tools, connected-host capabilities, and Agent settings, or to invoke a workspace action/command through the same in-process command registry the user uses in the TUI.',
+        'Discovery modes are read-only. Setting/keybinding writes, resets, UI routing, slash command invocation, and workspace action invocation require confirm:true plus explicitUserRequest.',
         'This tool preserves Agent product boundaries: connected-host lifecycle and listener posture stay externally owned, connected-host mode reports allowed and blocked route families, and secret-backed settings store raw values through the secret manager while config receives only a secret reference.',
       ].join(' '),
       parameters: {
         type: 'object',
-        properties: {
-          mode: {
-            type: 'string',
-            enum: MODES,
-            description: 'Harness operation to perform.',
-          },
-          query: {
-            type: 'string',
-            description: 'Search text for command, setting, or tool catalogs.',
-          },
-          command: {
-            type: 'string',
-            description: 'Full slash command string for mode run_command, for example "/settings get provider.model". In cli_command mode this may also hold a top-level CLI string such as "goodvibes-agent status --json".',
-          },
-          cliCommand: {
-            type: 'string',
-            description: 'Top-level CLI command string for mode cli_command, for example "goodvibes-agent status --json" or "profiles list". This mode is read-only metadata/parse inspection.',
-          },
-          commandName: {
-            type: 'string',
-            description: 'Slash command root without the leading slash for mode command or run_command, or a top-level CLI command token for cli_command.',
-          },
-          args: {
-            type: 'array',
-            items: { type: 'string' },
-            description: 'Slash command argument tokens for mode run_command when commandName is used.',
-          },
-          categoryId: {
-            type: 'string',
-            description: 'Agent workspace category id for workspace action filtering.',
-          },
-          panelId: {
-            type: 'string',
-            description: 'Built-in panel id for panel or open_panel modes.',
-          },
-          actionId: {
-            type: 'string',
-            description: 'Agent workspace action id for workspace_action or run_workspace_action, or keybinding action id for keybinding/set_keybinding/reset_keybinding.',
-          },
-          fields: {
-            type: 'object',
-            additionalProperties: { type: 'string' },
-            description: 'Field values for run_workspace_action when the workspace action opens an editor form.',
-          },
-          combo: {
-            ...KEY_COMBO_PARAMETER_SCHEMA,
-            description: 'Single key combo for set_keybinding, for example { "key": "g", "ctrl": true }.',
-          },
-          combos: {
-            type: 'array',
-            items: KEY_COMBO_PARAMETER_SCHEMA,
-            description: 'Multiple key combos for set_keybinding.',
-          },
-          recordId: {
-            type: 'string',
-            description: 'Selected Agent-local record id for selection-based local workspace operations.',
-          },
-          key: {
-            type: 'string',
-            description: 'Agent setting key for get_setting, set_setting, or reset_setting.',
-          },
-          value: {
-            anyOf: [
-              { type: 'string' },
-              { type: 'number' },
-              { type: 'boolean' },
-            ],
-            description: 'Setting value for set_setting. Strings, booleans, numbers, and enum strings are accepted.',
-          },
-          category: {
-            type: 'string',
-            description: 'Setting category filter such as provider, behavior, tools, ui, tts, permissions, automation, or surfaces.',
-          },
-          prefix: {
-            type: 'string',
-            description: 'Setting key prefix filter such as surfaces.slack.',
-          },
-          includeHidden: {
-            type: 'boolean',
-            description: 'Include settings hidden from the Agent workspace because they are host-owned or non-Agent lifecycle settings.',
-          },
-          includeParameters: {
-            type: 'boolean',
-            description: 'Include model tool JSON schemas in tools mode, or workspace editor field schemas in workspace_actions mode.',
-          },
-          limit: {
-            type: 'number',
-            description: 'Maximum catalog entries to return.',
-          },
-          pane: {
-            type: 'string',
-            enum: ['top', 'bottom'],
-            description: 'Preferred panel pane for open_panel when the current shell supports panel routing.',
-          },
-          confirm: {
-            type: 'boolean',
-            description: 'Required true for set_setting, reset_setting, run_command, open_panel, and mutating run_workspace_action calls after an explicit user request.',
-          },
-          explicitUserRequest: {
-            type: 'string',
-            description: 'Exact user request or faithful short summary authorizing a setting mutation or slash command invocation.',
-          },
-        },
+        properties: AGENT_HARNESS_PARAMETER_PROPERTIES,
         required: ['mode'],
         additionalProperties: false,
       },
@@ -638,6 +525,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             cliCommands: totalHarnessCliCommands(),
             blockedCliCommandTokens: blockedHarnessCliCommandTokens(),
             panels: totalHarnessPanels(deps.commandContext),
+            uiSurfaces: totalHarnessUiSurfaces(),
             shortcuts: totalHarnessShortcuts(deps.commandContext),
             keybindings: totalHarnessKeybindings(deps.commandContext),
             commands: deps.commandRegistry.list().length,
@@ -648,6 +536,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             modelAccess: {
               cliCommands: 'Use mode:"cli_commands" and mode:"cli_command" to inspect package CLI mirrors and their preferred in-process model routes. CLI modes are discovery-only.',
               panels: 'Use mode:"panels" and mode:"panel" to inspect built-in panel catalog/open state; use mode:"open_panel" with confirm:true plus explicitUserRequest to route a visible panel/workspace change.',
+              uiSurfaces: 'Use mode:"ui_surfaces" and mode:"ui_surface" to inspect modal/overlay/picker/workspace surfaces; use mode:"open_ui_surface" with confirm:true plus explicitUserRequest to route visible UI navigation.',
               shortcuts: 'Use mode:"shortcuts" to inspect fixed shortcuts plus configurable keybindings. Use mode:"set_keybinding" and mode:"reset_keybinding" with confirm:true plus explicitUserRequest to edit the same config file the user edits.',
               slashCommands: 'Use mode:"commands" and mode:"command" to inspect; use mode:"run_command" with confirm:true plus explicitUserRequest to execute.',
               workspace: 'Use mode:"workspace_actions" to list and mode:"workspace_action" for editor schemas; set includeParameters:true on workspace_actions to inline editor schemas.',
@@ -690,6 +579,19 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
           if (confirmationError) return error(confirmationError);
           return output(openHarnessPanel(deps.commandContext, args));
         }
+        if (args.mode === 'ui_surfaces') {
+          const surfaces = listHarnessUiSurfaces(deps.commandContext, args);
+          return output({ surfaces, returned: surfaces.length, total: totalHarnessUiSurfaces() });
+        }
+        if (args.mode === 'ui_surface') {
+          const surface = describeHarnessUiSurface(deps.commandContext, args);
+          return surface ? output(surface) : error(`Unknown UI surface ${readString(args.surfaceId || args.query) || '<missing>'}.`);
+        }
+        if (args.mode === 'open_ui_surface') {
+          const confirmationError = requireConfirmedAction(args, 'UI surface routing');
+          if (confirmationError) return error(confirmationError);
+          return output(openHarnessUiSurface(deps.commandContext, args));
+        }
         if (args.mode === 'shortcuts') return output(listHarnessShortcuts(deps.commandContext, args));
         if (args.mode === 'keybindings') return output(listHarnessKeybindings(deps.commandContext, args));
         if (args.mode === 'keybinding') {