@pellux/goodvibes-agent 1.0.20 → 1.0.22

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Product-facing release notes for GoodVibes Agent.
 
+## 1.0.22 - 2026-06-03
+
+- Refuse ambiguous agent_harness model-tool schema lookup with candidate tools instead of selecting the first partial match.
+- Refuse ambiguous connected-host capability lookup with candidate capabilities while preserving exact and unique lookup behavior.
+- Refresh model-visible harness parameter descriptions, preferred route hints, package docs, and focused harness coverage for no-guess single-item lookup parity.
+
+## 1.0.21 - 2026-06-03
+
+- Resolve agent_harness run_workspace_action by actionId, command, target, or query using the same lookup contract as workspace_action inspection.
+- Refuse ambiguous workspace action run requests with candidate actions instead of requiring exact action ids or guessing.
+- Refresh package-facing docs and focused harness coverage for workspace action run parity.
+
 ## 1.0.20 - 2026-06-03
 
 - Add agent_harness run_keybinding for confirmation-gated shell-safe shortcut equivalents such as search, prompt-history search, paste, clear screen, cancel generation, panel focus/close routes, and visible block-action routing.

package/README.md

@@ -66,7 +66,7 @@ Use the workspace as the primary product surface:
 
 Inside the Agent workspace, press `/` to search every workspace action by name, category, command, or detail. This is the primary discovery path for product actions; slash commands and CLI subcommands remain power-user/scriptable mirrors.
 
-The model has the same harness map through `agent_harness`: it can list Agent workspace actions, inspect one workspace action by `actionId`, `command`, `target`, or `query`, list built-in panels and inspect one panel by `panelId`, `target`, or `query`, inspect modal/overlay/picker UI surfaces by `surfaceId`, `target`, or `query`, list top-level CLI mirrors and inspect one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, inspect fixed shortcuts and configurable keybindings by `actionId`, `target`, `key`, or `query`, run shell-safe keybinding equivalents with confirmation, list slash commands, inspect one slash command by `command`, `commandName`, `target`, or `query` with parsed arguments and policy metadata, inspect model tool definitions or one model tool schema, inspect or change Agent settings by `key`, `target`, or `query` with confirmation, run concrete workspace or slash-command mirrors with confirmation, and report connected-host capability and live readiness posture. CLI mirror modes are read-only catalog and parser inspection; inside the main conversation, the model uses the returned preferred model tool, workspace action, setting mode, or confirmed slash-command mirror instead of launching hidden nested CLI processes. 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, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose fixed runtime/editor controls plus the live resolved keybinding table; each keybinding descriptor reports its model operation route, `run_keybinding` executes only supported shell-safe equivalents with confirmation, and prompt-editor-only or terminal-selection shortcuts remain explicit direct user interaction. `set_keybinding` and `reset_keybinding` write the same `keybindings.json` file the user edits and require confirmation. Workspace action discovery can inline editor field schemas with `includeParameters:true`; single-action lookup uses the same user-facing search fields and returns lookup metadata plus editor schema; CLI mirror, panel, UI surface, keybinding, and setting lookup use their catalog search fields and refuse ambiguous route or mutation requests with candidates; profile editors use the current starter-template inventory, and routine schedule editors can prefill a selected local routine from `recordId`. 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. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. The `connected_host` report includes route families, allowed capabilities, blocked lifecycle/non-Agent surfaces, and availability for the first-class Agent tools; `connected_host_capability` inspects one allowed or blocked capability by id, target, or query with its route families and boundary. The `connected_host_status` report performs a read-only live check of the connected-host status route and the isolated Agent Knowledge status route, reports SDK compatibility, token posture, endpoint bindings, route readiness, and actionable findings, and still refuses connected-host lifecycle control. The model uses those first-class tools for product workflows where they exist, such as Agent Knowledge, local memory/notes/personas/skills/routines, channel sends, notifications, reminders, media generation, work plans, and connected-host operator actions.
+The model has the same harness map through `agent_harness`: it can list Agent workspace actions, inspect or run one workspace action by `actionId`, `command`, `target`, or `query`, list built-in panels and inspect one panel by `panelId`, `target`, or `query`, inspect modal/overlay/picker UI surfaces by `surfaceId`, `target`, or `query`, list top-level CLI mirrors and inspect one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, inspect fixed shortcuts and configurable keybindings by `actionId`, `target`, `key`, or `query`, run shell-safe keybinding equivalents with confirmation, list slash commands, inspect one slash command by `command`, `commandName`, `target`, or `query` with parsed arguments and policy metadata, inspect model tool definitions or one model tool schema, inspect or change Agent settings by `key`, `target`, or `query` with confirmation, run concrete slash-command mirrors with confirmation, and report connected-host capability and live readiness posture. CLI mirror modes are read-only catalog and parser inspection; inside the main conversation, the model uses the returned preferred model tool, workspace action, setting mode, or confirmed slash-command mirror instead of launching hidden nested CLI processes. 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, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose fixed runtime/editor controls plus the live resolved keybinding table; each keybinding descriptor reports its model operation route, `run_keybinding` executes only supported shell-safe equivalents with confirmation, and prompt-editor-only or terminal-selection shortcuts remain explicit direct user interaction. `set_keybinding` and `reset_keybinding` write the same `keybindings.json` file the user edits and require confirmation. Workspace action discovery can inline editor field schemas with `includeParameters:true`; single-action lookup and execution use the same user-facing search fields, return or preserve lookup metadata where the action result carries descriptors, and refuse ambiguous run requests with candidates; CLI mirror, panel, UI surface, keybinding, model tool, setting, and connected-host capability lookup use their catalog search fields and refuse ambiguous route, schema, capability, or mutation requests with candidates; profile editors use the current starter-template inventory, and routine schedule editors can prefill a selected local routine from `recordId`. 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. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. The `connected_host` report includes route families, allowed capabilities, blocked lifecycle/non-Agent surfaces, and availability for the first-class Agent tools; `connected_host_capability` inspects one allowed or blocked capability by id, target, or query with its route families and boundary. The `connected_host_status` report performs a read-only live check of the connected-host status route and the isolated Agent Knowledge status route, reports SDK compatibility, token posture, endpoint bindings, route readiness, and actionable findings, and still refuses connected-host lifecycle control. The model uses those first-class tools for product workflows where they exist, such as Agent Knowledge, local memory/notes/personas/skills/routines, channel sends, notifications, reminders, media generation, work plans, and connected-host operator actions.
 
 The setup workspace surfaces discovered Agent-local persona, skill, and routine markdown files so day-one setup can import useful behavior instead of starting from blank records. It can also create one initial scratchpad note, local persona, skill, and routine directly during first-run setup; those records stay in Agent-local registries and never write to default knowledge or non-Agent segments.
 

package/dist/package/main.js

@@ -389257,6 +389257,23 @@ function createSchema2(db) {
   `);
   db.run(`CREATE INDEX IF NOT EXISTS idx_knowledge_schedules_job_id ON knowledge_schedules(job_id)`);
 }
+function getKnowledgeSchemaStatements() {
+  const statements = [];
+  createSchema2({
+    run(sql) {
+      const normalized = sql.trim();
+      if (normalized.length > 0)
+        statements.push(normalized);
+    }
+  });
+  return statements;
+}
+function renderKnowledgeSchemaSql() {
+  return `${getKnowledgeSchemaStatements().map((statement) => statement.endsWith(";") ? statement : `${statement};`).join(`
+
+`)}
+`;
+}
 function rowObject(columns, values2) {
   return Object.fromEntries(columns.map((column, index) => [column, values2[index]]));
 }
@@ -702594,6 +702611,9 @@ var init_ingest = __esm(() => {
 // node_modules/@pellux/goodvibes-sdk/dist/platform/knowledge/browser-history/index.js
 var init_browser_history = __esm(() => {
   init_ingest();
+  init_discover();
+  init_readers();
+  init_paths2();
 });
 
 // node_modules/graphql/jsutils/devAssert.mjs
@@ -720233,6 +720253,7 @@ var init_semantic = __esm(() => {
   init_llm();
   init_gap_repair();
   init_service4();
+  init_self_improvement();
 });
 
 // node_modules/@pellux/goodvibes-sdk/dist/platform/knowledge/home-graph/helpers.js
@@ -724201,8 +724222,40 @@ var init_map_view = __esm(() => {
 });
 
 // node_modules/@pellux/goodvibes-sdk/dist/platform/knowledge/home-graph/types.js
-var HOME_GRAPH_CAPABILITIES;
+var HOME_GRAPH_NODE_KINDS, HOME_GRAPH_RELATIONS, HOME_GRAPH_CAPABILITIES;
 var init_types6 = __esm(() => {
+  HOME_GRAPH_NODE_KINDS = [
+    "ha_home",
+    "ha_entity",
+    "ha_device",
+    "ha_area",
+    "ha_automation",
+    "ha_script",
+    "ha_scene",
+    "ha_label",
+    "ha_integration",
+    "ha_room",
+    "ha_device_passport",
+    "ha_maintenance_item",
+    "ha_troubleshooting_case",
+    "ha_purchase",
+    "ha_network_node"
+  ];
+  HOME_GRAPH_RELATIONS = [
+    "controls",
+    "located_in",
+    "belongs_to_device",
+    "has_manual",
+    "has_receipt",
+    "has_warranty",
+    "has_issue",
+    "fixed_by",
+    "uses_battery",
+    "connected_via",
+    "part_of_network",
+    "mentioned_by",
+    "source_for"
+  ];
   HOME_GRAPH_CAPABILITIES = [
     "knowledge-space-isolation",
     "snapshot-sync",
@@ -725609,6 +725662,7 @@ var init_service5 = __esm(() => {
 var init_home_graph = __esm(() => {
   init_service5();
   init_extension();
+  init_types6();
 });
 
 // node_modules/@pellux/goodvibes-sdk/dist/platform/knowledge/store-refinement.js
@@ -727936,10 +727990,14 @@ var init_service6 = __esm(() => {
 var init_project_planning = __esm(() => {
   init_service6();
   init_helpers3();
+  init_readiness();
 });
 
 // node_modules/@pellux/goodvibes-sdk/dist/platform/knowledge/persistence.js
-var init_persistence = () => {};
+var init_persistence = __esm(() => {
+  init_store_schema();
+  init_store_load();
+});
 
 // node_modules/@pellux/goodvibes-sdk/dist/platform/knowledge/projections.js
 class KnowledgeProjectionService {
@@ -731447,21 +731505,21 @@ var init_service7 = __esm(() => {
 var exports_knowledge = {};
 __export(exports_knowledge, {
   withKnowledgeSpace: () => withKnowledgeSpace,
-  uniqKnowledgeValues: () => uniq3,
-  stabilizeKnowledgeText: () => stableText2,
-  runKnowledgeSemanticSelfImprovement: () => runKnowledgeSemanticSelfImprovement2,
+  uniqKnowledgeValues: () => uniq2,
+  stabilizeKnowledgeText: () => stableText,
+  runKnowledgeSemanticSelfImprovement: () => runKnowledgeSemanticSelfImprovement,
   resolveProjectPlanningSpace: () => resolveProjectPlanningSpace,
-  resolveKnowledgeDbPathFromControlPlaneDir: () => resolveKnowledgeDbPathFromControlPlaneDir2,
+  resolveKnowledgeDbPathFromControlPlaneDir: () => resolveKnowledgeDbPathFromControlPlaneDir,
   renderPacket: () => renderPacket,
   renderKnowledgeSchemaSql: () => renderKnowledgeSchemaSql,
   renderKnowledgeMap: () => renderKnowledgeMap,
   readKnowledgeSearchText: () => readKnowledgeSearchText,
-  readBrowserKnowledgeProfile: () => readBrowserKnowledgeProfile2,
+  readBrowserKnowledgeProfile: () => readBrowserKnowledgeProfile,
   projectPlanningSourceId: () => projectPlanningSourceId,
   projectPlanningProjectIdFromPath: () => projectPlanningProjectIdFromPath,
   projectPlanningCanonicalUri: () => projectPlanningCanonicalUri,
   projectKnowledgeSpaceId: () => projectKnowledgeSpaceId,
-  parseKnowledgeJsonValue: () => parseJsonValue2,
+  parseKnowledgeJsonValue: () => parseJsonValue,
   normalizeProjectId: () => normalizeProjectId,
   normalizeKnowledgeSpaceId: () => normalizeKnowledgeSpaceId,
   normalizeHomeAssistantInstallationId: () => normalizeHomeAssistantInstallationId,
@@ -731469,12 +731527,12 @@ __export(exports_knowledge, {
   materializeGeneratedKnowledgeProjection: () => materializeGeneratedKnowledgeProjection,
   looksLikeRawPdfPayload: () => looksLikeRawPdfPayload,
   looksBinaryLikeText: () => looksBinaryLikeText,
-  loadKnowledgeStoreSnapshot: () => loadKnowledgeStoreSnapshot2,
+  loadKnowledgeStoreSnapshot: () => loadKnowledgeStoreSnapshot,
   listGeneratedKnowledgePages: () => listGeneratedKnowledgePages,
-  listBrowserKinds: () => listBrowserKinds2,
+  listBrowserKinds: () => listBrowserKinds,
   knowledgeSpaceMetadata: () => knowledgeSpaceMetadata,
   knowledgePageSourceWeight: () => knowledgePageSourceWeight,
-  knowledgeNowMs: () => nowMs2,
+  knowledgeNowMs: () => nowMs,
   knowledgeExtractionNeedsRefresh: () => knowledgeExtractionNeedsRefresh,
   isUsefulKnowledgePageSourceCandidate: () => isUsefulKnowledgePageSourceCandidate,
   isUsefulKnowledgePageSource: () => isUsefulKnowledgePageSource,
@@ -731494,12 +731552,12 @@ __export(exports_knowledge, {
   generatedKnowledgeSourceId: () => generatedKnowledgeSourceId,
   generatedKnowledgeCanonicalUri: () => generatedKnowledgeCanonicalUri,
   extractKnowledgeArtifact: () => extractKnowledgeArtifact,
-  evaluateProjectPlanningReadiness: () => evaluateProjectPlanningReadiness2,
-  discoverBrowserKnowledgeProfiles: () => discoverBrowserKnowledgeProfiles2,
+  evaluateProjectPlanningReadiness: () => evaluateProjectPlanningReadiness,
+  discoverBrowserKnowledgeProfiles: () => discoverBrowserKnowledgeProfiles,
   createWebKnowledgeGapRepairer: () => createWebKnowledgeGapRepairer,
   createProviderBackedKnowledgeSemanticLlm: () => createProviderBackedKnowledgeSemanticLlm,
   createMemoryApi: () => createMemoryApi,
-  createKnowledgeSchema: () => createSchema3,
+  createKnowledgeSchema: () => createSchema2,
   createKnowledgeApi: () => createKnowledgeApi,
   createDefaultKnowledgeConnectorRegistry: () => createDefaultKnowledgeConnectorRegistry,
   compareKnowledgePageSources: () => compareKnowledgePageSources,
@@ -733937,7 +733995,7 @@ var init_delivery_manager = __esm(() => {
 });
 
 // node_modules/@pellux/goodvibes-sdk/dist/platform/automation/scheduler-capacity.js
-function computeSchedulerCapacity(slotsTotal, runs, nowMs3 = Date.now()) {
+function computeSchedulerCapacity(slotsTotal, runs, nowMs2 = Date.now()) {
   let slotsInUse = 0;
   const queuedRuns = [];
   for (const run7 of runs) {
@@ -733947,7 +734005,7 @@ function computeSchedulerCapacity(slotsTotal, runs, nowMs3 = Date.now()) {
       queuedRuns.push(run7);
   }
   const queueDepth = queuedRuns.length;
-  const oldestQueuedAgeMs = queueDepth > 0 ? nowMs3 - Math.min(...queuedRuns.map((r5) => r5.queuedAt)) : null;
+  const oldestQueuedAgeMs = queueDepth > 0 ? nowMs2 - Math.min(...queuedRuns.map((r5) => r5.queuedAt)) : null;
   return { slotsTotal, slotsInUse, queueDepth, oldestQueuedAgeMs };
 }
 
@@ -816508,7 +816566,7 @@ var createStyledCell = (char, overrides = {}) => ({
 // src/version.ts
 import { readFileSync } from "fs";
 import { join } from "path";
-var _version = "1.0.20";
+var _version = "1.0.22";
 var _sdkVersion = "0.33.35";
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"), "utf-8"));
@@ -839370,7 +839428,7 @@ var WORK_PLAN_STATUSES = [
   "failed",
   "cancelled"
 ];
-function nowMs3() {
+function nowMs2() {
   return Date.now();
 }
 function isObject5(value) {
@@ -839476,7 +839534,7 @@ class WorkPlanStore {
     if (!normalizedTitle)
       throw new Error("Work plan item title is required.");
     const plan = this.readPlan();
-    const time4 = nowMs3();
+    const time4 = nowMs2();
     const item = {
       id: createItemId(),
       title: normalizedTitle,
@@ -839500,7 +839558,7 @@ class WorkPlanStore {
   updateItem(idOrPrefix, patch2) {
     const plan = this.readPlan();
     const item = this.resolveItem(plan, idOrPrefix);
-    const time4 = nowMs3();
+    const time4 = nowMs2();
     const nextStatus = patch2.status ?? item.status;
     const next = this.pruneItem({
       ...item,
@@ -839533,7 +839591,7 @@ class WorkPlanStore {
   removeItem(idOrPrefix) {
     const plan = this.readPlan();
     const item = this.resolveItem(plan, idOrPrefix);
-    const time4 = nowMs3();
+    const time4 = nowMs2();
     const remaining = plan.items.filter((candidate) => candidate.id !== item.id);
     this.writePlan({
       ...plan,
@@ -839553,7 +839611,7 @@ class WorkPlanStore {
       ...plan,
       items: remaining,
       activeItemId: remaining[0]?.id,
-      updatedAt: nowMs3()
+      updatedAt: nowMs2()
     });
     return removed;
   }
@@ -839592,7 +839650,7 @@ class WorkPlanStore {
     const parsed = JSON.parse(raw);
     if (!isObject5(parsed))
       return this.createEmptyPlan();
-    const time4 = nowMs3();
+    const time4 = nowMs2();
     const createdAt = typeof parsed.createdAt === "number" ? parsed.createdAt : time4;
     const updatedAt = typeof parsed.updatedAt === "number" ? parsed.updatedAt : createdAt;
     const items = Array.isArray(parsed.items) ? parsed.items.map((item) => normalizeItem(item, createdAt)).filter((item) => item !== null) : [];
@@ -839611,7 +839669,7 @@ class WorkPlanStore {
     };
   }
   createEmptyPlan() {
-    const time4 = nowMs3();
+    const time4 = nowMs2();
     return {
       id: createPlanId(this.options.projectId, this.options.projectRoot),
       projectId: this.options.projectId,
@@ -879403,7 +879461,7 @@ function describeCommandPolicy(commandName) {
     return {
       effect: "ui-navigation",
       confirmation,
-      preferredModelTool: "agent_harness workspace/workspace_actions/workspace_action",
+      preferredModelTool: "agent_harness workspace/workspace_actions/workspace_action/run_workspace_action",
       boundary: "Navigation and discovery commands should be inspected through agent_harness when possible."
     };
   }
@@ -879454,7 +879512,7 @@ function describeCliCommandPolicy(commandName) {
     return {
       effect: root === "tui" || root === "onboarding" ? "ui-navigation" : "read-only",
       confirmation,
-      preferredModelTool: root === "onboarding" || root === "tui" ? "agent_harness workspace/workspace_actions" : "agent_harness cli_commands/cli_command",
+      preferredModelTool: root === "onboarding" || root === "tui" ? "agent_harness workspace/workspace_actions/workspace_action/run_workspace_action" : "agent_harness 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."
     };
   }
@@ -879477,7 +879535,7 @@ function describeCliCommandPolicy(commandName) {
     return {
       effect: "local-state",
       confirmation,
-      preferredModelTool: root === "profiles" ? "agent_harness workspace_actions/run_workspace_action" : "agent_local_registry",
+      preferredModelTool: root === "profiles" ? "agent_harness 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."
     };
   }
@@ -879657,31 +879715,52 @@ function relatedConnectedHostRouteFamilies(capability) {
     return capabilityId.length > 0 && recordTextMatches(family, capabilityId);
   });
 }
-function describeConnectedHostCapability(toolRegistry, rawQuery) {
-  const query2 = normalizeCapabilityQuery(rawQuery);
-  if (!query2)
-    return null;
-  const allowedCapability = connectedHostCapabilityMap(toolRegistry).find((capability) => recordTextMatches(capability, query2));
-  if (allowedCapability) {
+function describeConnectedHostCapabilityCandidates(entries) {
+  return entries.slice(0, 8).map((entry) => ({
+    status: entry.status,
+    capabilityId: typeof entry.capability.id === "string" ? entry.capability.id : "",
+    purpose: typeof entry.capability.purpose === "string" ? entry.capability.purpose : undefined,
+    reason: typeof entry.capability.reason === "string" ? entry.capability.reason : undefined
+  }));
+}
+function connectedHostCapabilityDetail(entry) {
+  if (entry.status === "allowed") {
     return {
       status: "allowed",
-      capability: allowedCapability,
-      relatedRouteFamilies: relatedConnectedHostRouteFamilies(allowedCapability),
+      capability: entry.capability,
+      relatedRouteFamilies: relatedConnectedHostRouteFamilies(entry.capability),
       statusMode: 'Use agent_harness mode:"connected_host_status" for live read-only reachability, SDK compatibility, token posture, and Agent Knowledge route readiness.',
       boundary: "Use only the listed first-class model tools, slash-command families, and workspace categories. Mutations still require explicit confirmation through those tools or command bridges."
     };
   }
-  const blockedCapability = blockedConnectedHostCapabilities().find((capability) => recordTextMatches(capability, query2));
-  if (blockedCapability) {
-    return {
-      status: "blocked",
-      capability: blockedCapability,
-      allowed: false,
-      available: false,
-      boundary: "This connected-host surface is intentionally not exposed to the model as an Agent operation.",
-      statusMode: 'Use agent_harness mode:"connected_host_status" only for read-only readiness diagnostics.'
-    };
-  }
+  return {
+    status: "blocked",
+    capability: entry.capability,
+    allowed: false,
+    available: false,
+    boundary: "This connected-host surface is intentionally not exposed to the model as an Agent operation.",
+    statusMode: 'Use agent_harness mode:"connected_host_status" only for read-only readiness diagnostics.'
+  };
+}
+function describeConnectedHostCapability(toolRegistry, rawQuery) {
+  const query2 = normalizeCapabilityQuery(rawQuery);
+  if (!query2)
+    return null;
+  const entries = [
+    ...connectedHostCapabilityMap(toolRegistry).map((capability) => ({ status: "allowed", capability })),
+    ...blockedConnectedHostCapabilities().map((capability) => ({ status: "blocked", capability }))
+  ];
+  const exact = entries.find((entry) => entry.capability.id === rawQuery);
+  if (exact)
+    return { status: "found", detail: connectedHostCapabilityDetail(exact) };
+  const insensitive = entries.find((entry) => typeof entry.capability.id === "string" && entry.capability.id.toLowerCase() === query2);
+  if (insensitive)
+    return { status: "found", detail: connectedHostCapabilityDetail(insensitive) };
+  const searched = entries.filter((entry) => recordTextMatches(entry.capability, query2));
+  if (searched.length === 1)
+    return { status: "found", detail: connectedHostCapabilityDetail(searched[0]) };
+  if (searched.length > 1)
+    return { status: "ambiguous", input: rawQuery, candidates: describeConnectedHostCapabilityCandidates(searched) };
   return null;
 }
 function connectedHostSummary(context, toolRegistry) {
@@ -881269,37 +881348,77 @@ function readLimit9(value, fallback) {
     return fallback;
   return Math.max(1, Math.min(500, Math.trunc(parsed)));
 }
-function listHarnessModelTools(toolRegistry, args2) {
-  const query2 = readString56(args2.query).toLowerCase();
-  const includeParameters = args2.includeParameters === true;
-  const limit3 = readLimit9(args2.limit, 200);
-  return toolRegistry.getToolDefinitions().filter((tool2) => !query2 || [tool2.name, tool2.description, ...tool2.sideEffects ?? []].join(`
-`).toLowerCase().includes(query2)).sort((a4, b3) => a4.name.localeCompare(b3.name)).slice(0, limit3).map((tool2) => ({
+function modelToolSearchText(tool2) {
+  return [
+    tool2.name,
+    tool2.description,
+    ...tool2.sideEffects ?? []
+  ].join(`
+`).toLowerCase();
+}
+function modelToolLookupFromArgs(args2) {
+  const toolName = readString56(args2.toolName);
+  if (toolName)
+    return { source: "toolName", input: toolName };
+  const target = readString56(args2.target);
+  if (target)
+    return { source: "target", input: target };
+  const query2 = readString56(args2.query);
+  return query2 ? { source: "query", input: query2 } : null;
+}
+function describeModelTool(tool2, options = {}) {
+  return {
     name: tool2.name,
     description: tool2.description,
     sideEffects: tool2.sideEffects ?? [],
     concurrency: tool2.concurrency ?? "parallel",
     supportsProgress: tool2.supportsProgress ?? false,
     supportsStreamingOutput: tool2.supportsStreamingOutput ?? false,
-    ...includeParameters ? { parameters: tool2.parameters } : {}
+    ...options.lookup ? { lookup: options.lookup } : {},
+    ...options.includeParameters ? { parameters: tool2.parameters } : {}
+  };
+}
+function describeModelToolCandidates(tools3) {
+  return tools3.slice(0, 8).map((tool2) => ({
+    toolName: tool2.name,
+    description: tool2.description,
+    sideEffects: tool2.sideEffects ?? []
   }));
 }
+function listHarnessModelTools(toolRegistry, args2) {
+  const query2 = readString56(args2.query).toLowerCase();
+  const includeParameters = args2.includeParameters === true;
+  const limit3 = readLimit9(args2.limit, 200);
+  return toolRegistry.getToolDefinitions().filter((tool2) => !query2 || modelToolSearchText(tool2).includes(query2)).sort((a4, b3) => a4.name.localeCompare(b3.name)).slice(0, limit3).map((tool2) => describeModelTool(tool2, { includeParameters }));
+}
 function describeHarnessModelTool(toolRegistry, args2) {
-  const query2 = readString56(args2.toolName || args2.target || args2.query).toLowerCase();
-  if (!query2)
+  const lookup = modelToolLookupFromArgs(args2);
+  if (!lookup)
     return null;
-  const tool2 = toolRegistry.getToolDefinitions().find((candidate) => candidate.name.toLowerCase() === query2 || candidate.name.toLowerCase().includes(query2));
-  if (!tool2)
+  const tools3 = toolRegistry.getToolDefinitions().sort((a4, b3) => a4.name.localeCompare(b3.name));
+  const normalized = lookup.input.toLowerCase();
+  const exact = tools3.find((tool2) => tool2.name === lookup.input);
+  const found = exact ? { tool: exact, resolvedBy: "name" } : (() => {
+    const insensitive = tools3.find((tool2) => tool2.name.toLowerCase() === normalized);
+    if (insensitive)
+      return { tool: insensitive, resolvedBy: "case-insensitive-name" };
+    const searched = tools3.filter((tool2) => modelToolSearchText(tool2).includes(normalized));
+    if (searched.length === 1)
+      return { tool: searched[0], resolvedBy: "search" };
+    if (searched.length > 1)
+      return { candidates: searched };
     return null;
+  })();
+  if (!found)
+    return null;
+  if ("candidates" in found)
+    return { status: "ambiguous", input: lookup.input, candidates: describeModelToolCandidates(found.candidates) };
   return {
-    name: tool2.name,
-    description: tool2.description,
-    sideEffects: tool2.sideEffects ?? [],
-    concurrency: tool2.concurrency ?? "parallel",
-    supportsProgress: tool2.supportsProgress ?? false,
-    supportsStreamingOutput: tool2.supportsStreamingOutput ?? false,
-    parameters: tool2.parameters,
-    policy: "This is a first-class model tool definition. Use the returned JSON schema directly; mutating or external side-effect tools still require the explicit confirmation arguments defined by that tool."
+    status: "found",
+    tool: {
+      ...describeModelTool(found.tool, { includeParameters: true, lookup: { ...lookup, resolvedBy: found.resolvedBy } }),
+      policy: "This is a first-class model tool definition. Use the returned JSON schema directly; mutating or external side-effect tools still require the explicit confirmation arguments defined by that tool."
+    }
   };
 }
 
@@ -881352,11 +881471,11 @@ var AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   query: {
     type: "string",
-    description: "Search text for command, CLI mirror, panel, UI surface, keybinding, workspace action, setting, or tool catalogs; also slash-command, CLI mirror, setting, panel, UI surface, or keybinding lookup for single-item modes."
+    description: "Search text for slash-command, CLI mirror, panel, UI surface, keybinding, workspace action, model tool, setting, or connected-host capability catalogs; also lookup text for the matching single-item modes."
   },
   command: {
     type: "string",
-    description: 'Full slash command string for mode command, workspace_action lookup, or 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".'
+    description: 'Full slash command string for mode command, workspace_action/run_workspace_action lookup, or 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",
@@ -881385,7 +881504,7 @@ var AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   actionId: {
     type: "string",
-    description: "Agent workspace action id for workspace_action or run_workspace_action, or keybinding action id for keybinding/run_keybinding/set_keybinding/reset_keybinding. target or query can also look up one keybinding action."
+    description: "Agent workspace action id for workspace_action or run_workspace_action, or keybinding action id for keybinding/run_keybinding/set_keybinding/reset_keybinding. command, target, or query can also look up one workspace action; target or query can also look up one keybinding action."
   },
   fields: {
     type: "object",
@@ -881419,7 +881538,7 @@ var AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   target: {
     type: "string",
-    description: "Optional lookup target, such as a model-picker target, top-level CLI mirror/search text, panel id/search text, UI surface id/search text, workspace action id/search text, slash command root or invocation, setting key/search text, keybinding action/search text, model tool name, or connected-host capability id."
+    description: "Optional lookup target, such as a model-picker target, top-level CLI mirror/search text, panel id/search text, UI surface id/search text, workspace action id/search text, slash command root or invocation, setting key/search text, keybinding action/search text, model tool name/search text, or connected-host capability id/search text."
   },
   capabilityId: {
     type: "string",
@@ -881456,11 +881575,11 @@ var AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   confirm: {
     type: "boolean",
-    description: "Required true for set_setting, reset_setting, run_keybinding, run_command, open_panel, open_ui_surface, and mutating run_workspace_action calls after an explicit user request."
+    description: "Required true for set_setting, reset_setting, run_keybinding, run_command, open_panel, open_ui_surface, and executable or 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, keybinding action, or harness UI/command invocation."
+    description: "Exact user request or faithful short summary authorizing a setting mutation, keybinding change/action, harness UI routing, slash-command invocation, or workspace-action invocation."
   }
 };
 
@@ -882424,17 +882543,6 @@ function listWorkspaceActions(deps, args2) {
   const source = query2 ? searchAgentWorkspaceActions(AGENT_WORKSPACE_CATEGORIES, query2).map((result2) => ({ category: result2.category, action: result2.action })) : allWorkspaceActions();
   return source.filter((entry) => !categoryId || entry.category.id === categoryId).slice(0, limit3).map((entry) => describeWorkspaceAction(entry.category, entry.action, { includeEditor, editorContext }));
 }
-function findWorkspaceAction(args2) {
-  const actionId = readString58(args2.actionId || args2.query);
-  const categoryId = readString58(args2.categoryId || args2.category);
-  if (!actionId)
-    return null;
-  return allWorkspaceActions().find((entry) => {
-    if (categoryId && entry.category.id !== categoryId)
-      return false;
-    return entry.action.id === actionId || entry.action.label.toLowerCase() === actionId.toLowerCase();
-  }) ?? null;
-}
 function workspaceActionLookupFromArgs(args2) {
   const actionId = readString58(args2.actionId);
   if (actionId)
@@ -882642,10 +882750,12 @@ async function runWorkspaceEditorAction(deps, action2, editor, args2) {
   });
 }
 async function runWorkspaceAction(deps, args2) {
-  const found = findWorkspaceAction(args2);
-  if (!found)
-    return error52('run_workspace_action requires a valid actionId. Use mode:"workspace_actions" to inspect available actions.');
-  const { category, action: action2 } = found;
+  const resolved = resolveWorkspaceActionDetail(args2);
+  if (resolved?.status === "ambiguous")
+    return error52(`Ambiguous Agent workspace action ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+  if (!resolved)
+    return error52('run_workspace_action requires a valid actionId, command, target, or query. Use mode:"workspace_actions" to inspect available actions.');
+  const { category, action: action2, lookup } = resolved;
   if (action2.safety === "blocked") {
     return error52(`Workspace action ${action2.id} is blocked in Agent: ${action2.detail}`);
   }
@@ -882653,14 +882763,14 @@ async function runWorkspaceAction(deps, args2) {
     const editorContext2 = buildWorkspaceEditorContext(deps.commandContext, args2);
     return output7({
       status: "guidance",
-      action: describeWorkspaceAction(category, action2, { includeEditor: true, editorContext: editorContext2 })
+      action: describeWorkspaceAction(category, action2, { includeEditor: true, editorContext: editorContext2, lookup })
     });
   }
   if (action2.kind === "workspace" && action2.targetCategoryId) {
     const target = AGENT_WORKSPACE_CATEGORIES.find((entry) => entry.id === action2.targetCategoryId);
     return output7({
       status: "workspace_target",
-      action: describeWorkspaceAction(category, action2),
+      action: describeWorkspaceAction(category, action2, { lookup }),
       targetCategory: target ? describeWorkspaceCategory(target) : action2.targetCategoryId,
       targetActions: target ? target.actions.map((entry) => describeWorkspaceAction(target, entry)).slice(0, 40) : []
     });
@@ -882669,7 +882779,7 @@ async function runWorkspaceAction(deps, args2) {
     if (/<[^>\s]+(?:\s+[^>]*)?>/.test(action2.command)) {
       return output7({
         status: "needs_concrete_command",
-        action: describeWorkspaceAction(category, action2),
+        action: describeWorkspaceAction(category, action2, { lookup }),
         note: 'This workspace action is a command template. Provide concrete values with mode:"run_command" once the exact command is known.'
       });
     }
@@ -882687,7 +882797,7 @@ async function runWorkspaceAction(deps, args2) {
   const editorContext = buildWorkspaceEditorContext(deps.commandContext, args2);
   return output7({
     status: "no_direct_effect",
-    action: describeWorkspaceAction(category, action2, { includeEditor: true, editorContext })
+    action: describeWorkspaceAction(category, action2, { includeEditor: true, editorContext, lookup })
   });
 }
 function createAgentHarnessTool(deps) {
@@ -882733,7 +882843,7 @@ function createAgentHarnessTool(deps) {
               uiSurfaces: 'Use mode:"ui_surfaces" to list and mode:"ui_surface" with surfaceId, target, or query 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:"keybinding" with actionId, target, key, or query; use mode:"run_keybinding" for confirmation-gated shell-safe shortcut equivalents; 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" to list slash commands and mode:"command" with command, commandName, target, or query to inspect one command; use mode:"run_command" with confirm:true plus explicitUserRequest to execute.',
-              workspace: 'Use mode:"workspace_actions" to list and mode:"workspace_action" with actionId, command, target, or query for one action and editor schema; set includeParameters:true on workspace_actions to inline editor schemas.',
+              workspace: 'Use mode:"workspace_actions" to list, mode:"workspace_action" with actionId, command, target, or query for one action and editor schema, and mode:"run_workspace_action" with the same lookup fields plus confirmation for executable actions; set includeParameters:true on workspace_actions to inline editor schemas.',
               settings: 'Use mode:"settings" to list and mode:"get_setting" with key, target, or query for one setting. Use mode:"set_setting" or mode:"reset_setting" with key, target, or query plus confirm:true and explicitUserRequest.',
               tools: 'Use mode:"tools" to list first-class model tools, or mode:"tool" with toolName, target, or query to inspect one schema.',
               connectedHost: 'Use mode:"connected_host" for the connected-host capability map and blocked boundaries. Use mode:"connected_host_capability" with capabilityId, target, or query for one allowed or blocked capability.',
@@ -882898,15 +883008,23 @@ function createAgentHarnessTool(deps) {
         }
         if (args2.mode === "tool") {
           const query2 = readString58(args2.toolName || args2.target || args2.query);
-          const tool2 = describeHarnessModelTool(deps.toolRegistry, args2);
-          return tool2 ? output7(tool2) : error52(`Unknown model tool ${query2 || "<missing>"}. Use mode:"tools" to inspect available model tools.`);
+          const resolved = describeHarnessModelTool(deps.toolRegistry, args2);
+          if (resolved?.status === "found")
+            return output7(resolved.tool);
+          if (resolved?.status === "ambiguous")
+            return error52(`Ambiguous model tool ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+          return error52(`Unknown model tool ${query2 || "<missing>"}. Use mode:"tools" to inspect available model tools.`);
         }
         if (args2.mode === "connected_host")
           return output7(connectedHostSummary(deps.commandContext, deps.toolRegistry));
         if (args2.mode === "connected_host_capability") {
           const query2 = readString58(args2.capabilityId || args2.target || args2.query);
-          const capability = describeConnectedHostCapability(deps.toolRegistry, query2);
-          return capability ? output7(capability) : error52(`Unknown connected-host capability ${query2 || "<missing>"}. Use mode:"connected_host" to inspect allowed and blocked capability ids.`);
+          const resolved = describeConnectedHostCapability(deps.toolRegistry, query2);
+          if (resolved?.status === "found")
+            return output7(resolved.detail);
+          if (resolved?.status === "ambiguous")
+            return error52(`Ambiguous connected-host capability ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+          return error52(`Unknown connected-host capability ${query2 || "<missing>"}. Use mode:"connected_host" to inspect allowed and blocked capability ids.`);
         }
         if (args2.mode === "connected_host_status")
           return output7(await connectedHostStatusSummary(deps.commandContext, deps.toolRegistry));

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, single workspace-action lookup, built-in panels and single-panel lookup, modal/overlay/picker UI surfaces and single-surface lookup, named operator surfaces, top-level CLI mirrors and single-mirror lookup, fixed shortcuts, configurable keybindings, single-keybinding lookup, shell-safe keybinding execution, slash commands, single-command lookup with policy metadata, model tools and individual model tool schemas, settings and single-setting lookup, local registries, connected-host capability boundaries, single connected-host capability inspection, and live connected-host readiness are model-visible through Agent-owned tools. Visible UI routing includes the command browser, reasoning-effort picker, live process output, runtime activity, settings, workspaces, and pickers the user can open. Local memory, note, persona, skill, and routine create editors can also run through confirmed workspace actions. Mutations, visible UI routing, and keybinding execution remain explicit and confirmation-gated; prompt-editor-only shortcuts stay direct user interaction; and ambiguous lookup matches are refused with candidates instead of guessed.
+- User-facing Agent workspace actions, single workspace-action lookup/execution, built-in panels and single-panel lookup, modal/overlay/picker UI surfaces and single-surface lookup, named operator surfaces, top-level CLI mirrors and single-mirror lookup, fixed shortcuts, configurable keybindings, single-keybinding lookup, shell-safe keybinding execution, slash commands, single-command lookup with policy metadata, model tools and individual model tool schemas, settings and single-setting lookup, local registries, connected-host capability boundaries, single connected-host capability inspection, and live connected-host readiness are model-visible through Agent-owned tools. Visible UI routing includes the command browser, reasoning-effort picker, live process output, runtime activity, settings, workspaces, and pickers the user can open. Local memory, note, persona, skill, and routine create editors can also run through confirmed workspace actions. Mutations, visible UI routing, and keybinding execution remain explicit and confirmation-gated; prompt-editor-only shortcuts stay direct user interaction; and ambiguous lookup matches are refused with candidates instead of guessed.
 - 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, single workspace-action inspection by action id, command, or lookup text, built-in panel discovery/routing by panel id or lookup text, modal/overlay/picker UI surface discovery/routing by surface id or lookup text, top-level CLI mirror discovery and single-mirror lookup by command string, command token, or lookup text, fixed shortcut and configurable keybinding discovery, keybinding inspection/mutation by action id or lookup text, confirmation-gated shell-safe keybinding execution, slash-command discovery, single slash-command inspection by typed command or lookup text, command policy metadata, command execution with confirmation, model tool discovery and single-tool schema inspection, settings inspection/mutation by key or lookup text, connected-host capability inventory, single connected-host capability inspection, and live connected-host readiness 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, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, 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; keybinding descriptors include a model operation route, `run_keybinding` executes supported shell-safe equivalents only with confirmation, prompt-editor-only or terminal-selection shortcuts remain direct user interaction, and 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; single-action lookup uses the same user-facing search fields and returns lookup metadata plus the editor schema; single-CLI-mirror, single-panel, single-surface, single-keybinding, and single-setting lookup use their catalog search fields, return lookup metadata, and refuse ambiguous route or mutation requests with candidates. 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. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. 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, single workspace-action inspection and execution by action id, command, or lookup text, built-in panel discovery/routing by panel id or lookup text, modal/overlay/picker UI surface discovery/routing by surface id or lookup text, top-level CLI mirror discovery and single-mirror lookup by command string, command token, or lookup text, fixed shortcut and configurable keybinding discovery, keybinding inspection/mutation by action id or lookup text, confirmation-gated shell-safe keybinding execution, slash-command discovery, single slash-command inspection by typed command or lookup text, command policy metadata, command execution with confirmation, model tool discovery and single-tool schema inspection, settings inspection/mutation by key or lookup text, connected-host capability inventory, single connected-host capability inspection, and live connected-host readiness 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, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, 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; keybinding descriptors include a model operation route, `run_keybinding` executes supported shell-safe equivalents only with confirmation, prompt-editor-only or terminal-selection shortcuts remain direct user interaction, and 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; single-action lookup and execution use the same user-facing search fields, return lookup metadata where the action result carries descriptors, and refuse ambiguous run requests with candidates. Single-CLI-mirror, single-panel, single-surface, single-keybinding, single-tool, single-setting, and single-connected-host-capability lookup use their catalog search fields, return lookup metadata where the result carries it, and refuse ambiguous route, schema, capability, or mutation requests with candidates. 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. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. 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.
 

package/docs/tools-and-commands.md

@@ -43,14 +43,14 @@ 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 and one workspace action by action id, command, or lookup text, inspect built-in panels and one panel by id or lookup text, inspect modal/overlay/picker UI surfaces and named operator surfaces by id or lookup text, inspect top-level CLI mirrors and one mirror by command string, command token, or lookup text, inspect fixed shortcuts and configurable keybindings, inspect/change/run one keybinding by action id or lookup text where a shell-safe model route exists, inspect slash commands and one slash command by typed command or lookup text with policy metadata, run concrete workspace or slash-command mirrors with confirmation, inspect model tools or one model tool schema, inspect or change Agent settings by exact key or lookup text, inspect connected-host capability boundaries or one connected-host capability, and inspect live connected-host readiness.
+- `agent_harness`: inspect workspace categories/actions and inspect or run one workspace action by action id, command, or lookup text, inspect built-in panels and one panel by id or lookup text, inspect modal/overlay/picker UI surfaces and named operator surfaces by id or lookup text, inspect top-level CLI mirrors and one mirror by command string, command token, or lookup text, inspect fixed shortcuts and configurable keybindings, inspect/change/run one keybinding by action id or lookup text where a shell-safe model route exists, inspect slash commands and one slash command by typed command or lookup text with policy metadata, run concrete slash-command mirrors with confirmation, inspect model tools or one model tool schema, inspect or change Agent settings by exact key or lookup text, inspect connected-host capability boundaries or one connected-host capability, and inspect live connected-host readiness.
 - `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` lists the built-in panel catalog, and `panel` resolves one panel by `panelId`, `target`, or `query` with current open/focused state plus its matching Agent workspace route; `ui_surfaces` lists modal, overlay, picker, and workspace entrypoints, and `ui_surface` resolves one by `surfaceId`, `target`, or `query` with shell-opener availability and preferred model routes; `cli_commands` lists top-level package CLI mirror metadata, and `cli_command` resolves one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, returning parser output for concrete invocations, blocked command tokens, lookup metadata, and preferred in-process model routes; `shortcuts` returns fixed runtime/editor shortcuts plus configurable keybindings; `keybindings` lists the live resolved keybinding table, and `keybinding`, `run_keybinding`, `set_keybinding`, and `reset_keybinding` resolve one action by `actionId`, `target`, `key`, or `query` with default bindings, custom state, config path, lookup metadata, and model-operation route metadata; `commands` lists slash-command descriptions; `command` returns one slash-command detail by `command`, `commandName`, `target`, or `query`, including parsed arguments 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 by `actionId`, `command`, `target`, or `query`, using the same user-facing action-search fields and returning lookup metadata plus its editor schema; `tools` lists model tool definitions and can inline JSON schemas with `includeParameters:true`; `tool` returns one model tool schema by `toolName`, `target`, or `query`; `settings` returns setting descriptors plus setting policy; `get_setting`, `set_setting`, and `reset_setting` resolve one setting by `key`, `target`, or `query`, return lookup metadata on success, and refuse ambiguous matches with candidate settings; `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability; `connected_host_capability` returns one allowed or blocked connected-host capability by `capabilityId`, `target`, or `query` with related route families and boundary text; and `connected_host_status` performs a live read-only check of the connected-host status and Agent Knowledge status routes and reports endpoint bindings, token posture, SDK compatibility, route readiness, and findings without printing token values.
+`agent_harness` discovery modes are read-only. `summary` reports the model access map; `panels` lists the built-in panel catalog, and `panel` resolves one panel by `panelId`, `target`, or `query` with current open/focused state plus its matching Agent workspace route; `ui_surfaces` lists modal, overlay, picker, and workspace entrypoints, and `ui_surface` resolves one by `surfaceId`, `target`, or `query` with shell-opener availability and preferred model routes; `cli_commands` lists top-level package CLI mirror metadata, and `cli_command` resolves one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, returning parser output for concrete invocations, blocked command tokens, lookup metadata, and preferred in-process model routes; `shortcuts` returns fixed runtime/editor shortcuts plus configurable keybindings; `keybindings` lists the live resolved keybinding table, and `keybinding`, `run_keybinding`, `set_keybinding`, and `reset_keybinding` resolve one action by `actionId`, `target`, `key`, or `query` with default bindings, custom state, config path, lookup metadata, and model-operation route metadata; `commands` lists slash-command descriptions; `command` returns one slash-command detail by `command`, `commandName`, `target`, or `query`, including parsed arguments 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` and `run_workspace_action` resolve one action by `actionId`, `command`, `target`, or `query`, using the same user-facing action-search fields; inspection returns lookup metadata plus editor schema, and execution refuses ambiguous requests with candidate actions before any effect; `tools` lists model tool definitions and can inline JSON schemas with `includeParameters:true`; `tool` returns one model tool schema by `toolName`, `target`, or `query` and refuses ambiguous schema lookup with candidate tools; `settings` returns setting descriptors plus setting policy; `get_setting`, `set_setting`, and `reset_setting` resolve one setting by `key`, `target`, or `query`, return lookup metadata on success, and refuse ambiguous matches with candidate settings; `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability; `connected_host_capability` returns one allowed or blocked connected-host capability by `capabilityId`, `target`, or `query` with related route families and boundary text and refuses ambiguous capability lookup with candidates; and `connected_host_status` performs a live read-only check of the connected-host status and Agent Knowledge status routes and reports endpoint bindings, token posture, SDK compatibility, route readiness, and findings without printing token values.
 
 `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/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, conversation search, prompt-history search, slash-command mode, command browser, file picker, block actions, bookmarks, context inspector, runtime activity monitor, live process output, 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. Ambiguous UI surface lookup text is refused with candidate surfaces instead of routed.
 
@@ -64,7 +64,7 @@ CLI mirror modes are catalog and parser inspection only. When the user asks the
 
 Setting writes, setting resets, supported keybinding actions, 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`. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted `fields` through `run_workspace_action`; the harness validates required fields, requires `confirm:true` and `explicitUserRequest`, and dispatches through `agent_local_registry`. 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.
+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` plus an `actionId`, `command`, `target`, or `query` that resolves to one action. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted `fields` through `run_workspace_action`; the harness validates required fields, requires `confirm:true` and `explicitUserRequest`, and dispatches through `agent_local_registry`. 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.
 
 Use first-class Agent tools before falling back to slash-command mirrors. Slash-command execution is for harness parity and scriptable mirrors, not for bypassing Agent product boundaries.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "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-metadata.ts

@@ -9,6 +9,10 @@ export interface CommandExecutionPolicy {
   readonly boundary: string;
 }
 
+export type ConnectedHostCapabilityResolution =
+  | { readonly status: 'found'; readonly detail: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] };
+
 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.';
@@ -105,7 +109,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'ui-navigation',
       confirmation,
-      preferredModelTool: 'agent_harness workspace/workspace_actions/workspace_action',
+      preferredModelTool: 'agent_harness workspace/workspace_actions/workspace_action/run_workspace_action',
       boundary: 'Navigation and discovery commands should be inspected through agent_harness when possible.',
     };
   }
@@ -168,7 +172,7 @@ 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' : 'agent_harness cli_commands/cli_command',
+      preferredModelTool: root === 'onboarding' || root === 'tui' ? 'agent_harness workspace/workspace_actions/workspace_action/run_workspace_action' : 'agent_harness 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.',
     };
   }
@@ -191,7 +195,7 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
     return {
       effect: 'local-state',
       confirmation,
-      preferredModelTool: root === 'profiles' ? 'agent_harness workspace_actions/run_workspace_action' : 'agent_local_registry',
+      preferredModelTool: root === 'profiles' ? 'agent_harness 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.',
     };
   }
@@ -385,35 +389,55 @@ function relatedConnectedHostRouteFamilies(capability: Record<string, unknown>):
   });
 }
 
-export function describeConnectedHostCapability(
-  toolRegistry: ToolRegistry,
-  rawQuery: string,
-): Record<string, unknown> | null {
-  const query = normalizeCapabilityQuery(rawQuery);
-  if (!query) return null;
+function describeConnectedHostCapabilityCandidates(
+  entries: readonly { readonly status: 'allowed' | 'blocked'; readonly capability: Record<string, unknown> }[],
+): readonly Record<string, unknown>[] {
+  return entries.slice(0, 8).map((entry) => ({
+    status: entry.status,
+    capabilityId: typeof entry.capability.id === 'string' ? entry.capability.id : '',
+    purpose: typeof entry.capability.purpose === 'string' ? entry.capability.purpose : undefined,
+    reason: typeof entry.capability.reason === 'string' ? entry.capability.reason : undefined,
+  }));
+}
 
-  const allowedCapability = connectedHostCapabilityMap(toolRegistry).find((capability) => recordTextMatches(capability, query));
-  if (allowedCapability) {
+function connectedHostCapabilityDetail(entry: { readonly status: 'allowed' | 'blocked'; readonly capability: Record<string, unknown> }): Record<string, unknown> {
+  if (entry.status === 'allowed') {
     return {
       status: 'allowed',
-      capability: allowedCapability,
-      relatedRouteFamilies: relatedConnectedHostRouteFamilies(allowedCapability),
+      capability: entry.capability,
+      relatedRouteFamilies: relatedConnectedHostRouteFamilies(entry.capability),
       statusMode: 'Use agent_harness mode:"connected_host_status" for live read-only reachability, SDK compatibility, token posture, and Agent Knowledge route readiness.',
       boundary: 'Use only the listed first-class model tools, slash-command families, and workspace categories. Mutations still require explicit confirmation through those tools or command bridges.',
     };
   }
+  return {
+    status: 'blocked',
+    capability: entry.capability,
+    allowed: false,
+    available: false,
+    boundary: 'This connected-host surface is intentionally not exposed to the model as an Agent operation.',
+    statusMode: 'Use agent_harness mode:"connected_host_status" only for read-only readiness diagnostics.',
+  };
+}
 
-  const blockedCapability = blockedConnectedHostCapabilities().find((capability) => recordTextMatches(capability, query));
-  if (blockedCapability) {
-    return {
-      status: 'blocked',
-      capability: blockedCapability,
-      allowed: false,
-      available: false,
-      boundary: 'This connected-host surface is intentionally not exposed to the model as an Agent operation.',
-      statusMode: 'Use agent_harness mode:"connected_host_status" only for read-only readiness diagnostics.',
-    };
-  }
+export function describeConnectedHostCapability(
+  toolRegistry: ToolRegistry,
+  rawQuery: string,
+): ConnectedHostCapabilityResolution | null {
+  const query = normalizeCapabilityQuery(rawQuery);
+  if (!query) return null;
+
+  const entries = [
+    ...connectedHostCapabilityMap(toolRegistry).map((capability) => ({ status: 'allowed' as const, capability })),
+    ...blockedConnectedHostCapabilities().map((capability) => ({ status: 'blocked' as const, capability })),
+  ];
+  const exact = entries.find((entry) => entry.capability.id === rawQuery);
+  if (exact) return { status: 'found', detail: connectedHostCapabilityDetail(exact) };
+  const insensitive = entries.find((entry) => typeof entry.capability.id === 'string' && entry.capability.id.toLowerCase() === query);
+  if (insensitive) return { status: 'found', detail: connectedHostCapabilityDetail(insensitive) };
+  const searched = entries.filter((entry) => recordTextMatches(entry.capability, query));
+  if (searched.length === 1) return { status: 'found', detail: connectedHostCapabilityDetail(searched[0]!) };
+  if (searched.length > 1) return { status: 'ambiguous', input: rawQuery, candidates: describeConnectedHostCapabilityCandidates(searched) };
 
   return null;
 }

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

@@ -8,6 +8,13 @@ export interface AgentHarnessModelToolCatalogArgs {
   readonly limit?: unknown;
 }
 
+type HarnessModelToolDefinition = ReturnType<ToolRegistry['getToolDefinitions']>[number];
+type ModelToolLookupSource = 'toolName' | 'target' | 'query';
+
+export type HarnessModelToolResolution =
+  | { readonly status: 'found'; readonly tool: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] };
+
 function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -18,39 +25,78 @@ function readLimit(value: unknown, fallback: number): number {
   return Math.max(1, Math.min(500, Math.trunc(parsed)));
 }
 
+function modelToolSearchText(tool: HarnessModelToolDefinition): string {
+  return [
+    tool.name,
+    tool.description,
+    ...(tool.sideEffects ?? []),
+  ].join('\n').toLowerCase();
+}
+
+function modelToolLookupFromArgs(args: AgentHarnessModelToolCatalogArgs): { readonly source: ModelToolLookupSource; readonly input: string } | null {
+  const toolName = readString(args.toolName);
+  if (toolName) return { source: 'toolName', input: toolName };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function describeModelTool(tool: HarnessModelToolDefinition, options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {}): Record<string, unknown> {
+  return {
+    name: tool.name,
+    description: tool.description,
+    sideEffects: tool.sideEffects ?? [],
+    concurrency: tool.concurrency ?? 'parallel',
+    supportsProgress: tool.supportsProgress ?? false,
+    supportsStreamingOutput: tool.supportsStreamingOutput ?? false,
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    ...(options.includeParameters ? { parameters: tool.parameters } : {}),
+  };
+}
+
+function describeModelToolCandidates(tools: readonly HarnessModelToolDefinition[]): readonly Record<string, unknown>[] {
+  return tools.slice(0, 8).map((tool) => ({
+    toolName: tool.name,
+    description: tool.description,
+    sideEffects: tool.sideEffects ?? [],
+  }));
+}
+
 export function listHarnessModelTools(toolRegistry: ToolRegistry, args: AgentHarnessModelToolCatalogArgs): readonly Record<string, unknown>[] {
   const query = readString(args.query).toLowerCase();
   const includeParameters = args.includeParameters === true;
   const limit = readLimit(args.limit, 200);
   return toolRegistry.getToolDefinitions()
-    .filter((tool) => !query || [tool.name, tool.description, ...(tool.sideEffects ?? [])].join('\n').toLowerCase().includes(query))
+    .filter((tool) => !query || modelToolSearchText(tool).includes(query))
     .sort((a, b) => a.name.localeCompare(b.name))
     .slice(0, limit)
-    .map((tool) => ({
-      name: tool.name,
-      description: tool.description,
-      sideEffects: tool.sideEffects ?? [],
-      concurrency: tool.concurrency ?? 'parallel',
-      supportsProgress: tool.supportsProgress ?? false,
-      supportsStreamingOutput: tool.supportsStreamingOutput ?? false,
-      ...(includeParameters ? { parameters: tool.parameters } : {}),
-    }));
-}
-
-export function describeHarnessModelTool(toolRegistry: ToolRegistry, args: AgentHarnessModelToolCatalogArgs): Record<string, unknown> | null {
-  const query = readString(args.toolName || args.target || args.query).toLowerCase();
-  if (!query) return null;
-  const tool = toolRegistry.getToolDefinitions()
-    .find((candidate) => candidate.name.toLowerCase() === query || candidate.name.toLowerCase().includes(query));
-  if (!tool) return null;
+    .map((tool) => describeModelTool(tool, { includeParameters }));
+}
+
+export function describeHarnessModelTool(toolRegistry: ToolRegistry, args: AgentHarnessModelToolCatalogArgs): HarnessModelToolResolution | null {
+  const lookup = modelToolLookupFromArgs(args);
+  if (!lookup) return null;
+  const tools = toolRegistry.getToolDefinitions().sort((a, b) => a.name.localeCompare(b.name));
+  const normalized = lookup.input.toLowerCase();
+  const exact = tools.find((tool) => tool.name === lookup.input);
+  const found = exact
+    ? { tool: exact, resolvedBy: 'name' }
+    : (() => {
+        const insensitive = tools.find((tool) => tool.name.toLowerCase() === normalized);
+        if (insensitive) return { tool: insensitive, resolvedBy: 'case-insensitive-name' };
+        const searched = tools.filter((tool) => modelToolSearchText(tool).includes(normalized));
+        if (searched.length === 1) return { tool: searched[0]!, resolvedBy: 'search' };
+        if (searched.length > 1) return { candidates: searched };
+        return null;
+      })();
+  if (!found) return null;
+  if ('candidates' in found) return { status: 'ambiguous', input: lookup.input, candidates: describeModelToolCandidates(found.candidates) };
   return {
-    name: tool.name,
-    description: tool.description,
-    sideEffects: tool.sideEffects ?? [],
-    concurrency: tool.concurrency ?? 'parallel',
-    supportsProgress: tool.supportsProgress ?? false,
-    supportsStreamingOutput: tool.supportsStreamingOutput ?? false,
-    parameters: tool.parameters,
-    policy: 'This is a first-class model tool definition. Use the returned JSON schema directly; mutating or external side-effect tools still require the explicit confirmation arguments defined by that tool.',
+    status: 'found',
+    tool: {
+      ...describeModelTool(found.tool, { includeParameters: true, lookup: { ...lookup, resolvedBy: found.resolvedBy } }),
+      policy: 'This is a first-class model tool definition. Use the returned JSON schema directly; mutating or external side-effect tools still require the explicit confirmation arguments defined by that tool.',
+    },
   };
 }

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

@@ -23,11 +23,11 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   query: {
     type: 'string',
-    description: 'Search text for command, CLI mirror, panel, UI surface, keybinding, workspace action, setting, or tool catalogs; also slash-command, CLI mirror, setting, panel, UI surface, or keybinding lookup for single-item modes.',
+    description: 'Search text for slash-command, CLI mirror, panel, UI surface, keybinding, workspace action, model tool, setting, or connected-host capability catalogs; also lookup text for the matching single-item modes.',
   },
   command: {
     type: 'string',
-    description: 'Full slash command string for mode command, workspace_action lookup, or 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".',
+    description: 'Full slash command string for mode command, workspace_action/run_workspace_action lookup, or 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',
@@ -56,7 +56,7 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   actionId: {
     type: 'string',
-    description: 'Agent workspace action id for workspace_action or run_workspace_action, or keybinding action id for keybinding/run_keybinding/set_keybinding/reset_keybinding. target or query can also look up one keybinding action.',
+    description: 'Agent workspace action id for workspace_action or run_workspace_action, or keybinding action id for keybinding/run_keybinding/set_keybinding/reset_keybinding. command, target, or query can also look up one workspace action; target or query can also look up one keybinding action.',
   },
   fields: {
     type: 'object',
@@ -90,7 +90,7 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   target: {
     type: 'string',
-    description: 'Optional lookup target, such as a model-picker target, top-level CLI mirror/search text, panel id/search text, UI surface id/search text, workspace action id/search text, slash command root or invocation, setting key/search text, keybinding action/search text, model tool name, or connected-host capability id.',
+    description: 'Optional lookup target, such as a model-picker target, top-level CLI mirror/search text, panel id/search text, UI surface id/search text, workspace action id/search text, slash command root or invocation, setting key/search text, keybinding action/search text, model tool name/search text, or connected-host capability id/search text.',
   },
   capabilityId: {
     type: 'string',
@@ -127,10 +127,10 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   confirm: {
     type: 'boolean',
-    description: 'Required true for set_setting, reset_setting, run_keybinding, run_command, open_panel, open_ui_surface, and mutating run_workspace_action calls after an explicit user request.',
+    description: 'Required true for set_setting, reset_setting, run_keybinding, run_command, open_panel, open_ui_surface, and executable or 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, keybinding action, or harness UI/command invocation.',
+    description: 'Exact user request or faithful short summary authorizing a setting mutation, keybinding change/action, harness UI routing, slash-command invocation, or workspace-action invocation.',
   },
 } as const;

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

@@ -273,16 +273,6 @@ function listWorkspaceActions(deps: AgentHarnessToolDeps, args: AgentHarnessTool
     .map((entry) => describeWorkspaceAction(entry.category, entry.action, { includeEditor, editorContext }));
 }
 
-function findWorkspaceAction(args: AgentHarnessToolArgs): { readonly category: AgentWorkspaceCategory; readonly action: AgentWorkspaceAction } | null {
-  const actionId = readString(args.actionId || args.query);
-  const categoryId = readString(args.categoryId || args.category);
-  if (!actionId) return null;
-  return allWorkspaceActions().find((entry) => {
-    if (categoryId && entry.category.id !== categoryId) return false;
-    return entry.action.id === actionId || entry.action.label.toLowerCase() === actionId.toLowerCase();
-  }) ?? null;
-}
-
 function workspaceActionLookupFromArgs(args: AgentHarnessToolArgs): { readonly source: WorkspaceActionLookup['source']; readonly input: string } | null {
   const actionId = readString(args.actionId);
   if (actionId) return { source: 'actionId', input: actionId };
@@ -509,9 +499,10 @@ async function runWorkspaceAction(
   deps: AgentHarnessToolDeps,
   args: AgentHarnessToolArgs,
 ): Promise<{ readonly success: boolean; readonly output?: string; readonly error?: string }> {
-  const found = findWorkspaceAction(args);
-  if (!found) return error('run_workspace_action requires a valid actionId. Use mode:"workspace_actions" to inspect available actions.');
-  const { category, action } = found;
+  const resolved = resolveWorkspaceActionDetail(args);
+  if (resolved?.status === 'ambiguous') return error(`Ambiguous Agent workspace action ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+  if (!resolved) return error('run_workspace_action requires a valid actionId, command, target, or query. Use mode:"workspace_actions" to inspect available actions.');
+  const { category, action, lookup } = resolved;
 
   if (action.safety === 'blocked') {
     return error(`Workspace action ${action.id} is blocked in Agent: ${action.detail}`);
@@ -520,14 +511,14 @@ async function runWorkspaceAction(
     const editorContext = buildWorkspaceEditorContext(deps.commandContext, args);
     return output({
       status: 'guidance',
-      action: describeWorkspaceAction(category, action, { includeEditor: true, editorContext }),
+      action: describeWorkspaceAction(category, action, { includeEditor: true, editorContext, lookup }),
     });
   }
   if (action.kind === 'workspace' && action.targetCategoryId) {
     const target = AGENT_WORKSPACE_CATEGORIES.find((entry) => entry.id === action.targetCategoryId);
     return output({
       status: 'workspace_target',
-      action: describeWorkspaceAction(category, action),
+      action: describeWorkspaceAction(category, action, { lookup }),
       targetCategory: target ? describeWorkspaceCategory(target) : action.targetCategoryId,
       targetActions: target ? target.actions.map((entry) => describeWorkspaceAction(target, entry)).slice(0, 40) : [],
     });
@@ -536,7 +527,7 @@ async function runWorkspaceAction(
     if (/<[^>\s]+(?:\s+[^>]*)?>/.test(action.command)) {
       return output({
         status: 'needs_concrete_command',
-        action: describeWorkspaceAction(category, action),
+        action: describeWorkspaceAction(category, action, { lookup }),
         note: 'This workspace action is a command template. Provide concrete values with mode:"run_command" once the exact command is known.',
       });
     }
@@ -553,7 +544,7 @@ async function runWorkspaceAction(
   const editorContext = buildWorkspaceEditorContext(deps.commandContext, args);
   return output({
     status: 'no_direct_effect',
-    action: describeWorkspaceAction(category, action, { includeEditor: true, editorContext }),
+    action: describeWorkspaceAction(category, action, { includeEditor: true, editorContext, lookup }),
   });
 }
 
@@ -599,7 +590,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
               uiSurfaces: 'Use mode:"ui_surfaces" to list and mode:"ui_surface" with surfaceId, target, or query 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:"keybinding" with actionId, target, key, or query; use mode:"run_keybinding" for confirmation-gated shell-safe shortcut equivalents; 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" to list slash commands and mode:"command" with command, commandName, target, or query to inspect one command; use mode:"run_command" with confirm:true plus explicitUserRequest to execute.',
-              workspace: 'Use mode:"workspace_actions" to list and mode:"workspace_action" with actionId, command, target, or query for one action and editor schema; set includeParameters:true on workspace_actions to inline editor schemas.',
+              workspace: 'Use mode:"workspace_actions" to list, mode:"workspace_action" with actionId, command, target, or query for one action and editor schema, and mode:"run_workspace_action" with the same lookup fields plus confirmation for executable actions; set includeParameters:true on workspace_actions to inline editor schemas.',
               settings: 'Use mode:"settings" to list and mode:"get_setting" with key, target, or query for one setting. Use mode:"set_setting" or mode:"reset_setting" with key, target, or query plus confirm:true and explicitUserRequest.',
               tools: 'Use mode:"tools" to list first-class model tools, or mode:"tool" with toolName, target, or query to inspect one schema.',
               connectedHost: 'Use mode:"connected_host" for the connected-host capability map and blocked boundaries. Use mode:"connected_host_capability" with capabilityId, target, or query for one allowed or blocked capability.',
@@ -765,18 +756,18 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
         }
         if (args.mode === 'tool') {
           const query = readString(args.toolName || args.target || args.query);
-          const tool = describeHarnessModelTool(deps.toolRegistry, args);
-          return tool
-            ? output(tool)
-            : error(`Unknown model tool ${query || '<missing>'}. Use mode:"tools" to inspect available model tools.`);
+          const resolved = describeHarnessModelTool(deps.toolRegistry, args);
+          if (resolved?.status === 'found') return output(resolved.tool);
+          if (resolved?.status === 'ambiguous') return error(`Ambiguous model tool ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+          return error(`Unknown model tool ${query || '<missing>'}. Use mode:"tools" to inspect available model tools.`);
         }
         if (args.mode === 'connected_host') return output(connectedHostSummary(deps.commandContext, deps.toolRegistry));
         if (args.mode === 'connected_host_capability') {
           const query = readString(args.capabilityId || args.target || args.query);
-          const capability = describeConnectedHostCapability(deps.toolRegistry, query);
-          return capability
-            ? output(capability)
-            : error(`Unknown connected-host capability ${query || '<missing>'}. Use mode:"connected_host" to inspect allowed and blocked capability ids.`);
+          const resolved = describeConnectedHostCapability(deps.toolRegistry, query);
+          if (resolved?.status === 'found') return output(resolved.detail);
+          if (resolved?.status === 'ambiguous') return error(`Ambiguous connected-host capability ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+          return error(`Unknown connected-host capability ${query || '<missing>'}. Use mode:"connected_host" to inspect allowed and blocked capability ids.`);
         }
         if (args.mode === 'connected_host_status') return output(await connectedHostStatusSummary(deps.commandContext, deps.toolRegistry));
         return error(`Unhandled agent_harness mode: ${args.mode}`);

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '1.0.20';
+let _version = '1.0.22';
 let _sdkVersion = '0.33.35';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8')) as {