@vellumai/assistant 0.4.56 → 0.5.0

package/src/tools/shared/filesystem/path-policy.ts

@@ -34,7 +34,7 @@ const CONTAINER_WORKSPACE_EXACT = "/workspace";
  *
  * For existing paths, symlinks are resolved via realpathSync so a symlink
  * pointing outside the boundary is caught. For new paths (e.g. file_write),
- * pass `mustExist: false` — the nearest existing ancestor directory is
+ * pass `mustExist: false` - the nearest existing ancestor directory is
  * resolved via realpathSync to catch symlinks in parent dirs.
  *
  * Paths starting with `/workspace/` are treated as container-scoped and
@@ -71,7 +71,7 @@ export function sandboxPolicy(
     try {
       realResolved = realpathSync(resolved);
     } catch {
-      // File doesn't exist — will be caught by the tool's own existence check
+      // File doesn't exist - will be caught by the tool's own existence check
       realResolved = resolved;
     }
   } else {

package/src/tools/shared/shell-output.ts

@@ -9,7 +9,7 @@ export interface ShellOutputResult {
 /**
  * Format the raw stdout/stderr/exit-code from a spawned shell command into the
  * final tool result.  Both `shell.ts` (sandbox bash) and `host-shell.ts`
- * (host_bash) must produce identical output formatting — this shared function
+ * (host_bash) must produce identical output formatting - this shared function
  * is the single source of truth for that logic.
  */
 export function formatShellOutput(

package/src/tools/side-effects.ts

@@ -1,4 +1,4 @@
-// Side-effect tool classification — single source of truth.
+// Side-effect tool classification - single source of truth.
 // Tools that modify state outside the assistant (filesystem writes,
 // shell commands, network requests that trigger actions, etc.).
 // Used by private-conversation gating and permission simulation to decide

package/src/tools/skills/execute.ts

@@ -27,7 +27,7 @@ export class SkillExecuteTool implements Tool {
             description:
               "Tool-specific parameters as documented in the skill's instructions",
           },
-          reason: {
+          activity: {
             type: "string",
             description:
               "Brief non-technical explanation of what you are doing and why, shown to the user as a status update.",

package/src/tools/skills/load.ts

@@ -113,7 +113,7 @@ function formatToolSchemas(
 export class SkillLoadTool implements Tool {
   name = "skill_load";
   description =
-    "Load full instructions for a configured skill from ~/.vellum/workspace/skills.";
+    "Load full instructions for a skill. Works for both bundled skills (listed in the catalog) and workspace skills in ~/.vellum/workspace/skills.";
   category = "skills";
   defaultRiskLevel = RiskLevel.Low;
 
@@ -249,7 +249,7 @@ export class SkillLoadTool implements Tool {
         catalogIndex = indexCatalogById(catalog);
       }
 
-      // Validate (fail-closed — catches genuinely missing deps + cycles)
+      // Validate (fail-closed - catches genuinely missing deps + cycles)
       const validation = validateIncludes(skill.id, catalogIndex);
       if (!validation.ok) {
         if (validation.error === "missing") {
@@ -307,7 +307,7 @@ export class SkillLoadTool implements Tool {
           continue;
 
         childLines.push(
-          `  - ${child.id}: ${child.displayName} — ${child.description} (${child.skillFilePath})`,
+          `  - ${child.id}: ${child.displayName} - ${child.description} (${child.skillFilePath})`,
         );
 
         // Load the included skill's body content

package/src/tools/skills/sandbox-runner.ts

@@ -204,7 +204,7 @@ function spawnRunner(
         return;
       }
 
-      // No structured result — fall back to raw output
+      // No structured result - fall back to raw output
       if (code !== 0) {
         const truncatedStderr =
           stderr.length > MAX_OUTPUT_CHARS
@@ -261,7 +261,7 @@ function parseSkillResult(
         }
       }
     } catch {
-      // malformed line — keep scanning
+      // malformed line - keep scanning
     }
     searchFrom = lineStart;
   }
@@ -285,7 +285,7 @@ function parseSkillResult(
         };
       }
     } catch {
-      // malformed line — keep scanning
+      // malformed line - keep scanning
     }
     searchFrom = lineStart;
   }

package/src/tools/subagent/read.ts

@@ -44,7 +44,7 @@ export async function executeSubagentRead(
     };
   }
 
-  // Extract assistant messages only — that's the subagent's output.
+  // Extract assistant messages only - that's the subagent's output.
   const output: string[] = [];
   for (const msg of dbMessages) {
     if (msg.role !== "assistant") continue;

package/src/tools/subagent/spawn.ts

@@ -23,7 +23,7 @@ export async function executeSubagentSpawn(
     | undefined;
   if (!sendToClient) {
     return {
-      content: "No client connected — cannot spawn subagent.",
+      content: "No client connected - cannot spawn subagent.",
       isError: true,
     };
   }
@@ -45,7 +45,7 @@ export async function executeSubagentSpawn(
         subagentId,
         label,
         status: "pending",
-        message: `Subagent "${label}" spawned. You will be notified automatically when it completes or fails — do NOT poll subagent_status. Continue the conversation normally.`,
+        message: `Subagent "${label}" spawned. You will be notified automatically when it completes or fails - do NOT poll subagent_status. Continue the conversation normally.`,
       }),
       isError: false,
     };

package/src/tools/swarm/delegate.ts

@@ -73,7 +73,7 @@ export const swarmDelegateTool: Tool = {
       return { content: "Cancelled", isError: true };
     }
 
-    // Recursion guard — scoped to conversation so independent conversations are not blocked
+    // Recursion guard - scoped to conversation so independent conversations are not blocked
     const conversationKey = context.conversationId;
     if (activeConversations.has(conversationKey)) {
       return {
@@ -129,7 +129,7 @@ export const swarmDelegateTool: Tool = {
           config.providerOrder,
         );
       } catch {
-        // No provider available for synthesis — will use fallback
+        // No provider available for synthesis - will use fallback
       }
 
       const summary = await executeSwarm({
@@ -199,7 +199,7 @@ export const swarmDelegateTool: Tool = {
   },
 };
 
-/** Clear all active conversations — only for testing. */
+/** Clear all active conversations - only for testing. */
 export function _resetSwarmActive(): void {
   activeConversations.clear();
 }

package/src/tools/system/request-permission.ts

@@ -53,8 +53,9 @@ const FRIENDLY_NAMES: Record<PermissionType, string> = {
 class RequestSystemPermissionTool implements Tool {
   name = "request_system_permission";
   description =
-    "Ask the user to grant a macOS system permission (e.g. Full Disk Access) via System Settings. " +
-    "Use this when a tool execution fails because of a TCC/permission error.";
+    "Ask the user to grant a macOS system permission via System Settings. " +
+    "Use when a tool fails with a permission/access error (e.g. 'Operation not permitted', 'EACCES', sandbox denial). " +
+    "Do not explain how to open System Settings manually - this tool handles it with a clickable button.";
   category = "system";
   defaultRiskLevel = RiskLevel.High;
 
@@ -70,13 +71,13 @@ class RequestSystemPermissionTool implements Tool {
             enum: [...PERMISSION_TYPES],
             description: "The macOS system permission to request",
           },
-          reason: {
+          activity: {
             type: "string",
             description:
               "Short explanation of why this permission is needed (shown to the user)",
           },
         },
-        required: ["permission_type", "reason"],
+        required: ["permission_type", "activity"],
       },
     };
   }

package/src/tools/terminal/backends/native.ts

@@ -31,12 +31,12 @@ function buildSandboxProfile(
   denyReadPaths?: string[],
 ): string {
   const networkRule = allowNetwork
-    ? ";; Allow network access (proxied mode — needed to reach the credential proxy)\n(allow network*)"
+    ? ";; Allow network access (proxied mode - needed to reach the credential proxy)\n(allow network*)"
     : ";; Block network access\n(deny network*)";
 
   // Build deny-read rules for protected paths (CES shell lockdown).
   // These are placed AFTER the allow file-read* rule because SBPL uses
-  // last-match-wins semantics — the more specific deny overrides the
+  // last-match-wins semantics - the more specific deny overrides the
   // general allow.
   const denyReadRules =
     denyReadPaths && denyReadPaths.length > 0
@@ -149,13 +149,13 @@ let bwrapAvailable = false;
 /**
  * Check whether bwrap is installed AND functional (can create namespaces).
  *
- * Just testing `bwrap --version` is not enough — the binary may exist but
+ * Just testing `bwrap --version` is not enough - the binary may exist but
  * namespace creation can be blocked by the kernel (e.g. inside containers
  * or when user namespaces are disabled). We run a minimal sandbox that
  * exercises all namespace types used by buildBwrapArgs() (mount, network,
  * PID) to verify end-to-end functionality.
  *
- * Only positive results are cached — if bwrap is unavailable, we re-check
+ * Only positive results are cached - if bwrap is unavailable, we re-check
  * on every call so that a mid-session install is picked up immediately.
  */
 function isBwrapAvailable(): boolean {

package/src/tools/terminal/parser.ts

@@ -38,7 +38,7 @@ export interface ParsedCommand {
 }
 
 const SHELL_PROGRAMS = new Set(["sh", "bash", "zsh", "dash", "ksh", "fish"]);
-// Script interpreters that can execute arbitrary code from stdin — piping
+// Script interpreters that can execute arbitrary code from stdin - piping
 // untrusted data into these is as dangerous as piping into a shell.
 const SCRIPT_INTERPRETERS = new Set([
   "python",
@@ -55,7 +55,7 @@ const STDIN_EXEC_FLAGS = new Set(["-c", "-e", "-"]);
 // Per-interpreter flags that consume the next argument as a value (not a filename).
 // Mapped by interpreter name since flags differ across interpreters
 // (e.g. -I is standalone in Python but takes a value in Ruby).
-// Note: `-m` is intentionally excluded — it means "run module", so the next arg
+// Note: `-m` is intentionally excluded - it means "run module", so the next arg
 // is a module name and the interpreter is NOT in stdin-exec mode.
 const INTERPRETER_VALUE_FLAGS: ReadonlyMap<
   string,
@@ -128,7 +128,7 @@ const initGuard = new PromiseGuard<void>();
  * In development / `bunx` the file lives under `node_modules/` relative
  * to the source tree.  In compiled Bun binaries `import.meta.dirname`
  * points into the virtual `/$bunfs/` filesystem where binary assets
- * don't exist — fall back to:
+ * don't exist - fall back to:
  *   1. `../Resources/<file>` (macOS .app bundle layout)
  *   2. Next to the compiled binary (process.execPath)
  * This matches the pattern used for compiled Bun binary asset resolution.
@@ -352,7 +352,7 @@ function extractSegments(node: TSNode): CommandSegment[] {
 }
 
 /**
- * Returns true when the interpreter args indicate stdin-exec mode — i.e. the
+ * Returns true when the interpreter args indicate stdin-exec mode - i.e. the
  * interpreter will read code from stdin (or from an inline -c/-e argument)
  * rather than from a file.  Concretely:
  *   - Any STDIN_EXEC_FLAGS present → stdin-exec
@@ -367,7 +367,7 @@ function isStdinExecMode(interpreter: string, args: string[]): boolean {
     if (STDIN_EXEC_FLAGS.has(arg)) return true;
     // First non-flag argument is a filename/module → file mode
     if (!arg.startsWith("-")) return false;
-    // Flags like -W, -X consume the next token as their value — skip it
+    // Flags like -W, -X consume the next token as their value - skip it
     if (valueFlags.has(arg)) i++;
   }
   // No positional arguments at all → interpreter reads from stdin
@@ -581,7 +581,7 @@ export async function parse(command: string): Promise<ParsedCommand> {
   const parser = await ensureParser();
   const tree = parser.parse(command);
   if (!tree) {
-    // Parser couldn't parse — treat as opaque
+    // Parser couldn't parse - treat as opaque
     return { segments: [], dangerousPatterns: [], hasOpaqueConstructs: true };
   }
   const rootNode = tree.rootNode;

package/src/tools/terminal/sandbox-diagnostics.ts

@@ -46,7 +46,7 @@ function checkNativeBackend(): SandboxCheckResult {
       return {
         label: "Native sandbox (Linux bwrap)",
         ok: false,
-        detail: "bwrap not available — install bubblewrap",
+        detail: "bwrap not available - install bubblewrap",
       };
     }
   }

package/src/tools/terminal/shell.ts

@@ -39,13 +39,13 @@ function buildCredentialRefTrace(
  * inside the sandbox when CES shell lockdown is active.
  *
  * Protected paths include:
- * - ~/.vellum/protected/ — credential store secrets (also covers local-mode
+ * - ~/.vellum/protected/ - credential store secrets (also covers local-mode
  *   CES data root at ~/.vellum/protected/credential-executor/)
- * - ~/.vellum/workspace/data/db/ — database files that may contain credential metadata
- * - CES bootstrap socket directory (/run/ces-bootstrap/ or CES_BOOTSTRAP_SOCKET_DIR) —
+ * - ~/.vellum/workspace/data/db/ - database files that may contain credential metadata
+ * - CES bootstrap socket directory (/run/ces-bootstrap/ or CES_BOOTSTRAP_SOCKET_DIR) -
  *   prevents untrusted shells from connecting to the CES sidecar directly
  * - CES managed-mode data root (CES_DATA_DIR, or /ces-data when
- *   CES_MANAGED_MODE is set) — prevents access to CES-private state in
+ *   CES_MANAGED_MODE is set) - prevents access to CES-private state in
  *   managed deployments (local-mode is already covered by the protected/
  *   entry)
  */
@@ -53,7 +53,7 @@ function buildCesProtectedPaths(): string[] {
   const root = getRootDir();
   const paths = [`${root}/protected`, `${root}/workspace/data/db`];
 
-  // CES bootstrap socket directory — block access to the Unix socket that
+  // CES bootstrap socket directory - block access to the Unix socket that
   // accepts RPC commands from the assistant process.
   const bootstrapSocketDir =
     process.env["CES_BOOTSTRAP_SOCKET_DIR"] || "/run/ces-bootstrap";
@@ -68,7 +68,7 @@ function buildCesProtectedPaths(): string[] {
     paths.push(dirname(process.env["CES_BOOTSTRAP_SOCKET"]));
   }
 
-  // CES managed-mode private data root — in managed deployments the CES
+  // CES managed-mode private data root - in managed deployments the CES
   // data lives outside the Vellum root, so it isn't covered by the
   // `protected/` entry above.
   const cesDataDir = process.env["CES_DATA_DIR"];
@@ -100,7 +100,7 @@ class ShellTool implements Tool {
             type: "string",
             description: "The shell command to execute",
           },
-          reason: {
+          activity: {
             type: "string",
             description:
               'Brief non-technical explanation of what this command does and why, shown to a non-technical user in the permission prompt. Avoid jargon and technical terms. Good: "to check if a required program is installed on your computer". Bad: "to check if gcloud CLI is installed". Good: "to download a helper program". Bad: "to run npm install".',
@@ -123,7 +123,7 @@ class ShellTool implements Tool {
               'Optional list of credential IDs to inject via the proxy when network_mode is "proxied".',
           },
         },
-        required: ["command", "reason"],
+        required: ["command", "activity"],
       },
     };
   }
@@ -140,7 +140,7 @@ class ShellTool implements Tool {
       };
     }
 
-    // Reject commands containing null bytes — they cause truncation at the
+    // Reject commands containing null bytes - they cause truncation at the
     // OS level while the parser sees the full string, enabling bypass.
     if (command.includes("\0")) {
       return { content: "Error: command contains null bytes", isError: true };
@@ -155,7 +155,7 @@ class ShellTool implements Tool {
       input.network_mode === "proxied" ? "proxied" : "off";
 
     // -----------------------------------------------------------------------
-    // CES shell lockdown — reject proxied credential sessions for untrusted
+    // CES shell lockdown - reject proxied credential sessions for untrusted
     // actors when the lockdown flag is active. Proxied sessions grant the
     // subprocess access to credentials through the egress proxy, which
     // violates the secrecy guarantee.
@@ -183,7 +183,7 @@ class ShellTool implements Tool {
     }
 
     // -----------------------------------------------------------------------
-    // CES shell lockdown — reject non-empty credential-ref mode for untrusted
+    // CES shell lockdown - reject non-empty credential-ref mode for untrusted
     // actors. Even when network_mode is "off", passing credential_ids could
     // allow the model to probe stored credential metadata.
     // -----------------------------------------------------------------------
@@ -201,7 +201,7 @@ class ShellTool implements Tool {
     }
 
     // Resolve credential refs (UUID or service/field) to canonical UUIDs.
-    // Fail fast if any ref is unresolvable — partial execution with missing
+    // Fail fast if any ref is unresolvable - partial execution with missing
     // credentials is worse than a clear error.
     const credentialIds: string[] = [];
     if (networkMode === "proxied" && rawCredentialRefs.length > 0) {
@@ -264,7 +264,7 @@ class ShellTool implements Tool {
       "Executing shell command",
     );
 
-    // Resolve sandbox config early — needed both for proxy env and command wrapping.
+    // Resolve sandbox config early - needed both for proxy env and command wrapping.
     const sandboxConfig =
       context.sandboxOverride != null
         ? { ...config.sandbox, enabled: context.sandboxOverride }
@@ -273,7 +273,7 @@ class ShellTool implements Tool {
     // Acquire proxy session if proxied mode is requested.
     // `getOrStartSession` serializes per-conversation so concurrent proxied
     // commands share a single session instead of each creating one.
-    // Sessions are NOT stopped here — the session manager's idle timer handles
+    // Sessions are NOT stopped here - the session manager's idle timer handles
     // cleanup after all commands finish (see resetIdleTimer / stopAllSessions).
     let proxyEnv: ProxyEnvVars | null = null;
 
@@ -291,7 +291,7 @@ class ShellTool implements Tool {
       } catch (err) {
         log.error({ err }, "Failed to start proxy session");
         return {
-          content: `Error: failed to start proxy session — ${
+          content: `Error: failed to start proxy session - ${
             err instanceof Error ? err.message : String(err)
           }`,
           isError: true,
@@ -385,7 +385,7 @@ class ShellTool implements Tool {
         resolve({
           content: `Error spawning command: ${err.message}${
             (err as NodeJS.ErrnoException).code === "ENOENT"
-              ? ". The command was not found — check that it is installed and in PATH."
+              ? ". The command was not found - check that it is installed and in PATH."
               : ""
           }`,
           isError: true,

package/src/tools/tool-approval-handler.ts

@@ -82,7 +82,7 @@ export async function waitForInlineGrant(
       return { outcome: "aborted" };
     }
 
-    // Check if the canonical request was rejected — exit early without
+    // Check if the canonical request was rejected - exit early without
     // waiting for the full timeout.
     const request = getCanonicalGuardianRequest(escalationRequestId);
     if (request && request.status === "denied") {
@@ -98,7 +98,7 @@ export async function waitForInlineGrant(
       return { outcome: "denied", requestId: escalationRequestId };
     }
 
-    // Try to consume the grant — if the guardian approved, the canonical
+    // Try to consume the grant - if the guardian approved, the canonical
     // decision primitive will have minted a scoped grant by now.
     const grantResult = await consumeGrantForInvocation(consumeParams, {
       maxWaitMs: 0,
@@ -112,7 +112,7 @@ export async function waitForInlineGrant(
           grantId: grantResult.grant.id,
           elapsedMs: maxWait - (deadline - Date.now()),
         },
-        "Grant found during inline wait — tool execution proceeding",
+        "Grant found during inline wait - tool execution proceeding",
       );
       return { outcome: "granted", grant: { id: grantResult.grant.id } };
     }
@@ -125,16 +125,25 @@ export async function waitForInlineGrant(
       toolName: consumeParams.toolName,
       maxWaitMs: maxWait,
     },
-    "Inline grant wait timed out — no guardian decision within budget",
+    "Inline grant wait timed out - no guardian decision within budget",
   );
   return { outcome: "timeout", requestId: escalationRequestId };
 }
 
+const UI_SURFACE_TOOLS = new Set(["ui_show", "ui_update", "ui_dismiss"]);
+
 function requiresGuardianApprovalForActor(
   toolName: string,
   input: Record<string, unknown>,
   executionTarget: ExecutionTarget,
 ): boolean {
+  // UI surface tools are passive, user-visible operations (cards, forms,
+  // tables). User input is voluntary and user-controlled — skip the guardian
+  // gate so they work during fresh onboarding before trust is established.
+  if (UI_SURFACE_TOOLS.has(toolName)) {
+    return false;
+  }
+
   // Side-effect tools always require guardian approval for untrusted actors.
   // Read-only host execution is also blocked because it can leak sensitive
   // local information (e.g. shell/file reads).
@@ -425,13 +434,13 @@ export class ToolApprovalHandler {
             executionTarget,
             grantId: grantResult.grant.id,
           },
-          "Scoped grant consumed — allowing untrusted actor tool invocation",
+          "Scoped grant consumed - allowing untrusted actor tool invocation",
         );
 
         return { allowed: true, tool, grantConsumed: true };
       }
 
-      // Treat abort as a cancellation — not a grant denial. This matches
+      // Treat abort as a cancellation - not a grant denial. This matches
       // the abort check at the top of checkPreExecutionGates so the caller
       // sees a consistent "Cancelled" result instead of a spurious
       // guardian_approval_required denial during voice barge-in.
@@ -458,12 +467,12 @@ export class ToolApprovalHandler {
         };
       }
 
-      // No matching grant or race condition — deny or wait inline.
+      // No matching grant or race condition - deny or wait inline.
       //
       // For verified non-guardian actors (trusted_contact) with sufficient
       // context, escalate to the guardian by creating a canonical
       // tool_grant_request. Then wait bounded for the grant to become
-      // available — this lets the tool call succeed inline after guardian
+      // available - this lets the tool call succeed inline after guardian
       // approval without the requester having to retry manually.
       //
       // Unverified actors remain fail-closed with no escalation or wait.
@@ -524,7 +533,7 @@ export class ToolApprovalHandler {
                 grantId: waitResult.grant.id,
                 escalationRequestId: escalation.requestId,
               },
-              "Inline grant wait succeeded — allowing trusted contact tool invocation",
+              "Inline grant wait succeeded - allowing trusted contact tool invocation",
             );
             return { allowed: true, tool, grantConsumed: true };
           }
@@ -589,7 +598,7 @@ export class ToolApprovalHandler {
               waitOutcome: waitResult.outcome,
               escalationRequestId: escalation.requestId,
             },
-            "Inline grant wait ended without approval — denying trusted contact tool invocation",
+            "Inline grant wait ended without approval - denying trusted contact tool invocation",
           );
           const durationMs = Date.now() - startTime;
           emitLifecycleEvent({
@@ -610,10 +619,10 @@ export class ToolApprovalHandler {
             result: { content: escalationMessage, isError: true },
           };
         }
-        // escalation.failed — fall through to generic denial.
+        // escalation.failed - fall through to generic denial.
       }
 
-      // Unknown/unverified actors or escalation failures — generic denial.
+      // Unknown/unverified actors or escalation failures - generic denial.
       const reason = guardianApprovalDeniedMessage(context.trustClass, name);
       log.warn(
         {

package/src/tools/tool-manifest.ts

@@ -1,5 +1,5 @@
 /**
- * Declarative tool manifest — single place to inspect what gets registered.
+ * Declarative tool manifest - single place to inspect what gets registered.
  *
  * Each entry describes HOW a tool (or group of tools) gets loaded and
  * registered.  `initializeTools()` in `registry.ts` iterates this list
@@ -73,7 +73,7 @@ export const eagerModuleToolNames: string[] = [
 // a test registry reset) and tools that have always been explicit.
 
 export const explicitTools: Tool[] = [
-  // Previously-eager tools — kept here so initializeTools() can re-register
+  // Previously-eager tools - kept here so initializeTools() can re-register
   // them after __resetRegistryForTesting() clears the registry (ESM caching
   // prevents their side-effect registrations from re-running).
   shellTool,
@@ -99,7 +99,7 @@ export const explicitTools: Tool[] = [
 // This list is intentionally separate from `explicitTools` so that
 // initializeTools() in registry.ts can conditionally include them.
 
-/** All CES tools — stable references for the manifest snapshot. */
+/** All CES tools - stable references for the manifest snapshot. */
 export const cesTools: Tool[] = [
   makeAuthenticatedRequestTool,
   runAuthenticatedCommandTool,
@@ -123,7 +123,7 @@ export function getCesToolsIfEnabled(): Tool[] {
       );
     }
   } catch {
-    // Config not yet loaded (e.g. during test setup) — CES tools stay off.
+    // Config not yet loaded (e.g. during test setup) - CES tools stay off.
   }
   return [];
 }

package/src/tools/types.ts

@@ -114,7 +114,7 @@ export interface ToolContext {
   sandboxOverride?: boolean;
   /** Optional callback for tool lifecycle events (start/prompt/deny/execute/error/secret_detected). */
   onToolLifecycleEvent?: ToolLifecycleEventHandler;
-  /** Optional resolver for proxy tools — delegates execution to an external client. */
+  /** Optional resolver for proxy tools - delegates execution to an external client. */
   proxyToolResolver?: ProxyToolResolver;
   /** When set, only tools in this set may execute. Tools outside the set are blocked with an error. */
   allowedToolNames?: Set<string>;
@@ -147,7 +147,7 @@ export interface ToolContext {
   forcePromptSideEffects?: boolean;
   /**
    * When true, the tool requires a fresh interactive approval for every
-   * invocation — no cached grants, temporary overrides, persistent
+   * invocation - no cached grants, temporary overrides, persistent
    * "Always Allow" rules, or non-interactive auto-approve shortcuts may
    * bypass the prompt. This flag is independently sufficient: it
    * promotes allow → prompt decisions on its own and suppresses
@@ -231,7 +231,7 @@ export interface ToolExecutionResult {
 }
 
 // ---------------------------------------------------------------------------
-// Proxy approval types — local definitions for the outbound-proxy contract.
+// Proxy approval types - local definitions for the outbound-proxy contract.
 // The proxy service owns the canonical shapes; these are the assistant's
 // minimal view of the approval callback interface.
 // ---------------------------------------------------------------------------

package/src/tools/ui-surface/definitions.ts

@@ -28,43 +28,15 @@ function proxyExecute(): Promise<ToolExecutionResult> {
 export const uiShowTool: Tool = {
   name: "ui_show",
   description:
-    'Show structured data or UI to the user. Use for displaying weather, flights, stock prices, quick tables, cards, lists, forms, or any temporary data visualization. Use display: "inline" (default) to embed in chat, or "panel" for a floating window. For long-form writing use the document skill instead; for interactive apps use the app-builder skill instead.\n\n' +
-    "Supported surface types:\n" +
-    "- card: Informational card with title, subtitle, body text, and optional metadata key-value pairs. " +
-    "Cards support an optional template field for specialized native rendering. " +
-    "data shape: { title: string, subtitle?: string, body: string, metadata?: Array<{ label: string, value: string }>, template?: string, templateData?: object }\n" +
-    '  Template "weather_forecast": renders an Apple Weather-style forecast widget. ' +
-    'templateData shape: { location: string, currentTemp: number, feelsLike: number, unit: "F"|"C", condition: string, humidity: number, windSpeed: number, windDirection: string, ' +
-    "hourly: Array<{ time: string, icon: string (SF Symbol name), temp: number }>, " +
-    "forecast: Array<{ day: string, icon: string (SF Symbol name), low: number, high: number, precip: number|null, condition: string }> }\n" +
-    '  Template "task_progress": renders a live-updating task progress widget showing structured step-by-step progress. ' +
-    'templateData shape: { title: string, status: "in_progress"|"completed"|"failed", ' +
-    'steps: Array<{ label: string, status: "pending"|"in_progress"|"completed"|"failed", detail?: string }> }\n' +
-    "- table: Data table with columns, selectable rows, and action buttons. " +
-    'data shape: { columns: Array<{ id: string, label: string, width?: number }>, rows: Array<{ id: string, cells: Record<string, string | { text: string, icon?: string, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?: boolean, selected?: boolean }>, selectionMode?: "none"|"single"|"multiple", caption?: string }. ' +
-    "Cell values can be plain strings or rich objects with icon (SF Symbol name) and iconColor. " +
-    "Column width is in points — use it for narrow columns (e.g. counts, short labels) so flexible columns get more space. Omit width for columns that should expand.\n" +
-    "- form: Input form with typed fields. " +
-    'data shape: { description?: string, fields: Array<{ id: string, type: "text"|"textarea"|"select"|"toggle"|"number"|"password", label: string, placeholder?: string, required?: boolean, defaultValue?: string|number|boolean, options?: Array<{ label: string, value: string }> }>, submitLabel?: string }. ' +
-    "For multi-page forms, use pages array instead of top-level fields: { pages: [{ id: string, title: string, description?: string, fields: [...] }], pageLabels?: { next?: string, back?: string, submit?: string }, submitLabel?: string }\n" +
-    "- list: Selectable list of items. " +
-    'data shape: { items: Array<{ id: string, title: string, subtitle?: string, icon?: string, selected?: boolean }>, selectionMode: "single"|"multiple"|"none" }\n' +
-    "- confirmation: Yes/no confirmation dialog. " +
-    "data shape: { message: string, detail?: string, confirmLabel?: string, confirmedLabel?: string, cancelLabel?: string, destructive?: boolean }\n" +
-    "- dynamic_page: Custom HTML page rendered in a sandboxed container. " +
-    "data shape: { html: string, width?: number, height?: number, preview?: { title: string, subtitle?: string, description?: string, icon?: string (emoji), metrics?: Array<{ label: string, value: string }> } }. " +
-    'When preview is provided, a compact preview card is shown inline in chat with the title, subtitle, description, metric pills, and a "View Output" button that opens the full page.\n' +
-    "- file_upload: File upload dialog where the user can drag-and-drop or browse for files. " +
-    "data shape: { prompt: string, acceptedTypes?: string[], maxFiles?: number }\n\n" +
-    "Action payload conventions:\n" +
-    "- Multi-select tables: use `window.vellum.sendAction(actionId, { selectedIds: [...] })` to send selected row IDs\n" +
-    "- Bulk actions: include `selectedRows` array with full row data for context\n\n" +
-    "Presenting choices: When the user needs to make a choice or provide structured input, prefer interactive surfaces over plain text. " +
-    "Use list (2-8 options, single select), form (structured input with typed fields), confirmation (destructive/important actions), or table (data review with selectable rows).\n\n" +
-    "Tool chaining: After gathering data via tools (web search, browser, APIs), synthesize results into a visual output.\n\n" +
-    'Task progress for multi-step workflows: Create a card with template "task_progress" and templateData containing steps. ' +
-    "As each step completes, call ui_update to patch data.templateData (not top-level fields). " +
-    'Set templateData.status to "completed" or "failed" when done.',
+    "Show structured data or UI to the user. For long-form writing use the document skill; for interactive apps use the app-builder skill.\n\n" +
+    "Surface types (data shapes):\n" +
+    "- card: { title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Templates: \"weather_forecast\" (native weather widget), \"task_progress\" (live step tracker - update via ui_update on data.templateData; shape: { title, status: \"in_progress\"|\"completed\"|\"failed\", steps: [{ label, status: \"pending\"|\"in_progress\"|\"completed\"|\"failed\", detail? }] })\n" +
+    '- table: { columns: [{ id, label, width? }], rows: [{ id, cells: Record<id, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }\n' +
+    '- form: { description?, fields: [{ id, type: "text"|"textarea"|"select"|"toggle"|"number"|"password", label, placeholder?, required?, defaultValue?, options?: [{ label, value }] }], submitLabel? }. Multi-page: { pages: [{ id, title, description?, fields }], pageLabels?: { next?, back?, submit? }, submitLabel? }\n' +
+    '- list: { items: [{ id, title, subtitle?, icon?, selected? }], selectionMode: "single"|"multiple"|"none" }\n' +
+    "- confirmation: { message, detail?, confirmLabel?, confirmedLabel?, cancelLabel?, destructive? }\n" +
+    "- dynamic_page: { html, width?, height?, preview?: { title, subtitle?, description?, icon?, metrics?: [{ label, value }] } }\n" +
+    "- file_upload: { prompt, acceptedTypes?, maxFiles? }",
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",