@vellumai/assistant 0.4.56 → 0.5.0

package/src/tools/credentials/broker-types.ts

@@ -52,13 +52,13 @@ export interface BrowserFillRequest {
   toolName: string;
   domain?: string;
   /**
-   * Opaque fill callback — the broker calls this with the plaintext value internally.
+   * Opaque fill callback - the broker calls this with the plaintext value internally.
    * The caller provides the fill function but never receives the secret value.
    */
   fill: (value: string) => Promise<void>;
 }
 
-/** Result of a broker-mediated browser fill — contains only metadata, never plaintext. */
+/** Result of a broker-mediated browser fill - contains only metadata, never plaintext. */
 export interface BrowserFillResult {
   success: boolean;
   reason?: string;
@@ -70,13 +70,13 @@ export interface ServerUseRequest<T> {
   field: string;
   toolName: string;
   /**
-   * Opaque callback — the broker calls this with the plaintext value internally.
+   * Opaque callback - the broker calls this with the plaintext value internally.
    * The caller provides the function but never receives the secret value directly.
    */
   execute: (value: string) => Promise<T>;
 }
 
-/** Result of a broker-mediated server-side credential use — contains the callback result, never plaintext. */
+/** Result of a broker-mediated server-side credential use - contains the callback result, never plaintext. */
 export interface ServerUseResult<T> {
   success: boolean;
   result?: T;
@@ -89,7 +89,7 @@ export interface ServerUseByIdRequest {
   requestingTool: string;
 }
 
-/** Successful by-id lookup result — metadata + injection templates, never plaintext. */
+/** Successful by-id lookup result - metadata + injection templates, never plaintext. */
 export interface ServerUseByIdSuccess {
   success: true;
   credentialId: string;

package/src/tools/credentials/broker.ts

@@ -68,7 +68,7 @@ export class CredentialBroker {
       };
     }
 
-    // Tool policy enforcement — deny if tool is not in the credential's allowed list
+    // Tool policy enforcement - deny if tool is not in the credential's allowed list
     if (!isToolAllowed(request.toolName, metadata.allowedTools)) {
       const tools = metadata.allowedTools ?? [];
       return {
@@ -76,7 +76,7 @@ export class CredentialBroker {
         reason:
           `Tool "${request.toolName}" is not allowed to use credential ${request.service}/${request.field}. ` +
           (tools.length === 0
-            ? "No tools are currently allowed — update the credential with allowed_tools via credential_store."
+            ? "No tools are currently allowed - update the credential with allowed_tools via credential_store."
             : `Allowed tools: ${tools.join(", ")}.`),
       };
     }
@@ -125,7 +125,7 @@ export class CredentialBroker {
 
     token.consumed = true;
     const storageKey = credentialKey(token.service, token.field);
-    // Check for transient value first (one-time send) — consume and return the value
+    // Check for transient value first (one-time send) - consume and return the value
     // directly since transient values are never persisted to secure storage.
     const transient = this.transientValues.get(storageKey);
     if (transient !== undefined) {
@@ -166,7 +166,7 @@ export class CredentialBroker {
    * Fill a browser field using a credential without exposing plaintext to the caller.
    *
    * The broker resolves the credential, reads the secret internally, and passes it
-   * to the provided fill callback. The return value contains only metadata — the
+   * to the provided fill callback. The return value contains only metadata - the
    * plaintext never leaves this method's scope.
    */
   async browserFill(request: BrowserFillRequest): Promise<BrowserFillResult> {
@@ -178,7 +178,7 @@ export class CredentialBroker {
       };
     }
 
-    // Tool policy enforcement — deny if tool is not in the credential's allowed list
+    // Tool policy enforcement - deny if tool is not in the credential's allowed list
     if (!isToolAllowed(request.toolName, metadata.allowedTools)) {
       const tools = metadata.allowedTools ?? [];
       return {
@@ -186,12 +186,12 @@ export class CredentialBroker {
         reason:
           `Tool "${request.toolName}" is not allowed to use credential ${request.service}/${request.field}. ` +
           (tools.length === 0
-            ? "No tools are currently allowed — update the credential with allowed_tools via credential_store."
+            ? "No tools are currently allowed - update the credential with allowed_tools via credential_store."
             : `Allowed tools: ${tools.join(", ")}.`),
       };
     }
 
-    // Domain policy enforcement — deny if the page domain is not in the credential's allowed list
+    // Domain policy enforcement - deny if the page domain is not in the credential's allowed list
     const browserDomains = metadata.allowedDomains ?? [];
     if (browserDomains.length > 0) {
       if (!request.domain) {
@@ -228,7 +228,7 @@ export class CredentialBroker {
     try {
       await request.fill(value);
       // Only discard the transient value after a successful fill, and only if
-      // the map still holds the same reference — a concurrent injectTransient()
+      // the map still holds the same reference - a concurrent injectTransient()
       // call during the async fill could have replaced it with a new value.
       if (
         transient !== undefined &&
@@ -246,7 +246,7 @@ export class CredentialBroker {
       );
       return { success: true };
     } catch (err) {
-      // Log the raw error for debugging but never return it — the callback
+      // Log the raw error for debugging but never return it - the callback
       // error text may embed the credential value, leaking plaintext outside
       // the broker's trust boundary.
       log.error(
@@ -262,7 +262,7 @@ export class CredentialBroker {
    *
    * Like browserFill, the broker reads the secret internally and passes it
    * to the provided callback. The return value contains only the callback's
-   * result — the plaintext never leaves this method's scope.
+   * result - the plaintext never leaves this method's scope.
    */
   async serverUse<T>(
     request: ServerUseRequest<T>,
@@ -282,12 +282,12 @@ export class CredentialBroker {
         reason:
           `Tool "${request.toolName}" is not allowed to use credential ${request.service}/${request.field}. ` +
           (tools.length === 0
-            ? "No tools are currently allowed — update the credential with allowed_tools via credential_store."
+            ? "No tools are currently allowed - update the credential with allowed_tools via credential_store."
             : `Allowed tools: ${tools.join(", ")}.`),
       };
     }
 
-    // Domain policy enforcement — credentials with domain restrictions are
+    // Domain policy enforcement - credentials with domain restrictions are
     // scoped to browser use on those domains and cannot be used server-side.
     const serverDomains = metadata.allowedDomains ?? [];
     if (serverDomains.length > 0) {
@@ -341,7 +341,7 @@ export class CredentialBroker {
    *
    * Returns metadata and injection templates so the proxy knows how to
    * inject the credential into outbound requests. The secret value is
-   * never included in the result — the proxy reads it separately via
+   * never included in the result - the proxy reads it separately via
    * the secure key backend at injection time.
    */
   async serverUseById(
@@ -365,12 +365,12 @@ export class CredentialBroker {
         reason:
           `Tool "${request.requestingTool}" is not allowed to use credential ${metadata.service}/${metadata.field}. ` +
           (tools.length === 0
-            ? "No tools are currently allowed — update the credential with allowed_tools via credential_store."
+            ? "No tools are currently allowed - update the credential with allowed_tools via credential_store."
             : `Allowed tools: ${tools.join(", ")}.`),
       };
     }
 
-    // Domain policy enforcement — credentials with domain restrictions are
+    // Domain policy enforcement - credentials with domain restrictions are
     // scoped to browser use on those domains and cannot be used server-side.
     const domains = metadata.allowedDomains ?? [];
     if (domains.length > 0) {

package/src/tools/credentials/metadata-store.ts

@@ -22,7 +22,7 @@ import type { CredentialInjectionTemplate } from "./policy-types.js";
 /**
  * CredentialMetadata extends the shared StaticCredentialRecord with
  * assistant-specific injection template fields (composeWith, valueTransform).
- * Structurally compatible — the shared store persists all fields as-is.
+ * Structurally compatible - the shared store persists all fields as-is.
  */
 export interface CredentialMetadata {
   credentialId: string;
@@ -60,7 +60,7 @@ function getStore(): StaticCredentialMetadataStore {
 }
 
 // ---------------------------------------------------------------------------
-// Public API — unchanged signatures, delegates to shared store
+// Public API - unchanged signatures, delegates to shared store
 // ---------------------------------------------------------------------------
 
 /**

package/src/tools/credentials/resolve.ts

@@ -1,5 +1,5 @@
 /**
- * Credential resolver — maps between opaque IDs, service/field pairs,
+ * Credential resolver - maps between opaque IDs, service/field pairs,
  * and storage locators.
  *
  * This decouples external credential references from the underlying

package/src/tools/credentials/selection.ts

@@ -27,7 +27,7 @@ export interface CredentialSelectionResult {
 }
 
 /**
- * Tier scores — higher-priority criteria use larger values so they
+ * Tier scores - higher-priority criteria use larger values so they
  * dominate over lower-priority ones regardless of accumulation.
  */
 const SCORE_EXACT_HOST = 100;

package/src/tools/credentials/tool-policy.ts

@@ -13,7 +13,7 @@
  * @returns true if the tool is explicitly listed in allowedTools
  *
  * Semantics:
- * 1. Explicit allowlist — tool must be listed by exact name
+ * 1. Explicit allowlist - tool must be listed by exact name
  * 2. No wildcard support in v1
  * 3. Fail-closed on empty or missing list
  */

package/src/tools/credentials/vault.ts

@@ -1,5 +1,10 @@
 import { getConfig } from "../../config/loader.js";
+import {
+  setSlackChannelConfig,
+  type SlackChannelConfigResult,
+} from "../../daemon/handlers/config-slack-channel.js";
 import { orchestrateOAuthConnect } from "../../oauth/connect-orchestrator.js";
+import { syncManualTokenConnection } from "../../oauth/manual-token-connection.js";
 import {
   disconnectOAuthProvider,
   getAppByProviderAndClientId,
@@ -42,6 +47,39 @@ import { toPolicyFromInput, validatePolicyInput } from "./policy-validate.js";
 
 const log = getLogger("credential-vault");
 
+function isSlackChannelCredential(
+  service: string,
+  field: string,
+): field is "bot_token" | "app_token" {
+  return (
+    service === "slack_channel" &&
+    (field === "bot_token" || field === "app_token")
+  );
+}
+
+async function storeSlackChannelCredential(
+  field: "bot_token" | "app_token",
+  value: string,
+): Promise<SlackChannelConfigResult> {
+  return field === "bot_token"
+    ? setSlackChannelConfig(value, undefined)
+    : setSlackChannelConfig(undefined, value);
+}
+
+function formatSlackChannelStatus(
+  result: SlackChannelConfigResult,
+): string {
+  if (result.connected) {
+    const teamLabel = result.teamName ?? "Slack";
+    const botLabel = result.botUsername ? ` (@${result.botUsername})` : "";
+    return ` Slack channel connected to ${teamLabel}${botLabel}.`;
+  }
+  if (result.warning) {
+    return ` ${result.warning}`;
+  }
+  return "";
+}
+
 class CredentialStoreTool implements Tool {
   name = "credential_store";
   description =
@@ -67,7 +105,7 @@ class CredentialStoreTool implements Tool {
               "describe",
             ],
             description:
-              'The operation to perform. Use "prompt" to ask the user for a secret via secure UI — the value never enters the conversation. Use "oauth2_connect" to connect an OAuth2 service via browser authorization. Use "describe" to get setup metadata for a well-known OAuth service (dashboard URL, scopes, redirect URI, etc.). For well-known services (gmail, slack), only the service name is required — endpoints, scopes, and stored client credentials are resolved automatically.',
+              'The operation to perform. Use "prompt" to ask the user for a secret via secure UI - the value never enters the conversation. Use "oauth2_connect" to connect an OAuth2 service via browser authorization. Use "describe" to get setup metadata for a well-known OAuth service (dashboard URL, scopes, redirect URI, etc.). For well-known services (gmail, slack), only the service name is required - endpoints, scopes, and stored client credentials are resolved automatically.',
           },
           service: {
             type: "string",
@@ -322,13 +360,27 @@ class CredentialStoreTool implements Tool {
           };
         }
 
-        const key = credentialKey(service, field);
-        const ok = await setSecureKeyAsync(key, value);
-        if (!ok) {
-          return {
-            content: "Error: failed to store credential",
-            isError: true,
-          };
+        let slackChannelResult: SlackChannelConfigResult | undefined;
+        if (isSlackChannelCredential(service, field)) {
+          slackChannelResult = await storeSlackChannelCredential(field, value);
+          if (!slackChannelResult.success) {
+            return {
+              content: `Error: ${
+                slackChannelResult.error ??
+                "failed to configure Slack channel"
+              }`,
+              isError: true,
+            };
+          }
+        } else {
+          const key = credentialKey(service, field);
+          const ok = await setSecureKeyAsync(key, value);
+          if (!ok) {
+            return {
+              content: "Error: failed to store credential",
+              isError: true,
+            };
+          }
         }
         try {
           upsertCredentialMetadata(service, field, {
@@ -344,12 +396,19 @@ class CredentialStoreTool implements Tool {
             "metadata write failed after storing credential",
           );
         }
+        if (!isSlackChannelCredential(service, field)) {
+          await syncManualTokenConnection(service);
+        }
         const metadata = getCredentialMetadata(service, field);
         const credIdSuffix = metadata
           ? ` (credential_id: ${metadata.credentialId})`
           : "";
         return {
-          content: `Stored credential for ${service}/${field}.${credIdSuffix}`,
+          content: `Stored credential for ${service}/${field}.${credIdSuffix}${
+            slackChannelResult
+              ? formatSlackChannelStatus(slackChannelResult)
+              : ""
+          }`,
           isError: false,
         };
       }
@@ -477,7 +536,7 @@ class CredentialStoreTool implements Tool {
           if (oauthResult === "error") {
             log.warn(
               { service },
-              "OAuth disconnect failed after removing credential — secure key deletion error",
+              "OAuth disconnect failed after removing credential - secure key deletion error",
             );
           }
         } catch (err) {
@@ -653,6 +712,13 @@ class CredentialStoreTool implements Tool {
 
         // Handle one-time send delivery: inject into context without persisting
         if (result.delivery === "transient_send") {
+          if (isSlackChannelCredential(service, field)) {
+            return {
+              content:
+                "Error: Slack channel credentials must be saved to secure storage. Re-run the secure prompt and choose to store the token.",
+              isError: true,
+            };
+          }
           const config = getConfig();
           if (!config.secretDetection.allowOneTimeSend) {
             log.warn(
@@ -666,7 +732,7 @@ class CredentialStoreTool implements Tool {
             };
           }
           // Ensure metadata exists so broker policy checks work, but don't
-          // overwrite an existing record — a stored credential's policy should
+          // overwrite an existing record - a stored credential's policy should
           // not be silently replaced by the transient prompt's policy.
           // Metadata must be written before injecting the transient value so
           // we never leave a dangling value that fails policy checks.
@@ -703,14 +769,31 @@ class CredentialStoreTool implements Tool {
           };
         }
 
-        // Default: persist to keychain
-        const key = credentialKey(service, field);
-        const ok = await setSecureKeyAsync(key, result.value);
-        if (!ok) {
-          return {
-            content: "Error: failed to store credential",
-            isError: true,
-          };
+        let slackChannelResult: SlackChannelConfigResult | undefined;
+        if (isSlackChannelCredential(service, field)) {
+          slackChannelResult = await storeSlackChannelCredential(
+            field,
+            result.value,
+          );
+          if (!slackChannelResult.success) {
+            return {
+              content: `Error: ${
+                slackChannelResult.error ??
+                "failed to configure Slack channel"
+              }`,
+              isError: true,
+            };
+          }
+        } else {
+          // Default: persist to keychain
+          const key = credentialKey(service, field);
+          const ok = await setSecureKeyAsync(key, result.value);
+          if (!ok) {
+            return {
+              content: "Error: failed to store credential",
+              isError: true,
+            };
+          }
         }
         try {
           upsertCredentialMetadata(service, field, {
@@ -725,12 +808,19 @@ class CredentialStoreTool implements Tool {
             "metadata write failed after storing credential",
           );
         }
+        if (!isSlackChannelCredential(service, field)) {
+          await syncManualTokenConnection(service);
+        }
         const promptMeta = getCredentialMetadata(service, field);
         const promptCredIdSuffix = promptMeta
           ? ` (credential_id: ${promptMeta.credentialId})`
           : "";
         return {
-          content: `Credential stored for ${service}/${field}.${promptCredIdSuffix}`,
+          content: `Credential stored for ${service}/${field}.${promptCredIdSuffix}${
+            slackChannelResult
+              ? formatSlackChannelStatus(slackChannelResult)
+              : ""
+          }`,
           isError: false,
         };
       }
@@ -754,7 +844,7 @@ class CredentialStoreTool implements Tool {
         // Resolve client_id and client_secret.
         // Priority:
         //   1. Explicit input from the caller
-        //   2. oauth-store DB — when clientId is already known, look up the
+        //   2. oauth-store DB - when clientId is already known, look up the
         //      matching app so the secret comes from the same app. Only fall
         //      back to the most-recent-app heuristic when clientId is unknown.
         let clientId = input.client_id as string | undefined;
@@ -791,7 +881,7 @@ class CredentialStoreTool implements Tool {
             isError: true,
           };
 
-        // Fail early when client_secret is required but missing — guide the
+        // Fail early when client_secret is required but missing - guide the
         // agent to collect it from the user rather than letting it improvise
         // browser-automation workarounds that inevitably fail.
         const requiresSecret =
@@ -808,7 +898,7 @@ class CredentialStoreTool implements Tool {
           };
         }
 
-        // Delegate to the shared orchestrator — it resolves authUrl, tokenUrl,
+        // Delegate to the shared orchestrator - it resolves authUrl, tokenUrl,
         // extraParams, userinfoUrl, and tokenEndpointAuthMethod from the DB.
         const result = await orchestrateOAuthConnect({
           service: rawService,
@@ -909,7 +999,7 @@ class CredentialStoreTool implements Tool {
           redirectUri = `http://localhost:${loopbackPort}/oauth/callback`;
         } else if (transport === "loopback") {
           redirectUri =
-            "(automatic — no redirect URI needed, uses random localhost port)";
+            "(automatic - no redirect URI needed, uses random localhost port)";
         } else {
           // Try to compute the actual URL from config/env
           try {
@@ -920,7 +1010,7 @@ class CredentialStoreTool implements Tool {
             redirectUri = `${baseUrl}/webhooks/oauth/callback`;
           } catch {
             redirectUri =
-              "(requires ingress.publicBaseUrl — not currently configured)";
+              "(requires ingress.publicBaseUrl - not currently configured)";
           }
         }
 

package/src/tools/execution-target.ts

@@ -11,12 +11,12 @@ export function resolveExecutionTarget(
   manifestOverride?: ManifestOverride,
 ): ExecutionTarget {
   const tool = getTool(toolName);
-  // Manifest-declared execution target is authoritative — check it first so
+  // Manifest-declared execution target is authoritative - check it first so
   // skill tools with host_/computer_use_ prefixes aren't mis-classified.
   if (tool?.executionTarget) {
     return tool.executionTarget;
   }
-  // Check the tool's executionMode metadata — proxy tools run on the connected
+  // Check the tool's executionMode metadata - proxy tools run on the connected
   // client (host), not inside the sandbox.
   if (tool?.executionMode === "proxy") {
     return "host";

package/src/tools/executor.ts

@@ -88,7 +88,7 @@ export class ToolExecutor {
       // whether a scoped grant was consumed. Previously this was nested
       // inside the `!grantConsumed` block, meaning untrusted host_bash
       // calls that arrived with a consumed guardian-approval grant would
-      // skip this assignment entirely — defeating the lockdown.
+      // skip this assignment entirely - defeating the lockdown.
       if (
         name === "host_bash" &&
         isCesShellLockdownEnabled(getConfig()) &&
@@ -98,7 +98,7 @@ export class ToolExecutor {
       }
 
       // Secure command tool installation always requires fresh per-invocation
-      // approval — no persistent grants. This is unconditional (not gated on
+      // approval - no persistent grants. This is unconditional (not gated on
       // CES lockdown or trust class) because installing secure tools is
       // inherently high-impact.
       if (name === "manage_secure_command_tool") {
@@ -106,11 +106,11 @@ export class ToolExecutor {
         context.requireFreshApproval = true;
       }
 
-      // A consumed scoped grant is a complete authorization — skip the
+      // A consumed scoped grant is a complete authorization - skip the
       // interactive permission/prompt flow so non-interactive sessions
       // don't auto-deny prompt-gated tools and burn the one-time grant.
       // Exception: requireFreshApproval tools always go through the
-      // permission check even when a grant was consumed — the grant does
+      // permission check even when a grant was consumed - the grant does
       // not substitute for an interactive human review.
       if (!gateResult.grantConsumed || context.requireFreshApproval) {
         // Check permissions via the extracted PermissionChecker
@@ -164,7 +164,7 @@ export class ToolExecutor {
         return { content: msg, isError: true };
       }
 
-      // Execute the tool — proxy tools delegate to an external resolver
+      // Execute the tool - proxy tools delegate to an external resolver
       let execResult: ToolExecutionResult;
       let toolTimeoutMs: number;
       if (name === "bash" || name === "host_bash") {
@@ -276,7 +276,7 @@ export class ToolExecutor {
               grantId: bridgeResult.grantId,
               conversationId: context.conversationId,
             },
-            "CES approval granted — retrying tool invocation with grantId",
+            "CES approval granted - retrying tool invocation with grantId",
           );
 
           if (tool.executionMode === "proxy") {
@@ -579,7 +579,7 @@ function computePreviewDiff(
       };
     }
   } catch {
-    // Preview is best-effort — don't block the prompt on errors
+    // Preview is best-effort - don't block the prompt on errors
   }
   return undefined;
 }

package/src/tools/filesystem/edit.ts

@@ -9,9 +9,9 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class FileEditTool implements Tool {
   name = "file_edit";
   description =
-    "Replace an exact string in a file with a new string. Use this for surgical edits instead of rewriting entire files.";
+    "Replace an exact string in a file with a new string. Use this for surgical edits instead of rewriting entire files. To delete a file, use bash with rm instead.";
   category = "filesystem";
-  defaultRiskLevel = RiskLevel.Medium;
+  defaultRiskLevel = RiskLevel.Low;
 
   getDefinition(): ToolDefinition {
     return {

package/src/tools/filesystem/read.ts

@@ -14,7 +14,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class FileReadTool implements Tool {
   name = "file_read";
   description =
-    "Read the contents of a file. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis.";
+    "Read the contents of a file. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. Always use this tool (not host_file_read) for workspace files under .vellum.";
   category = "filesystem";
   defaultRiskLevel = RiskLevel.Low;
 
@@ -61,7 +61,10 @@ class FileReadTool implements Tool {
     if (IMAGE_EXTENSIONS.has(ext)) {
       const pathCheck = sandboxPolicy(rawPath, context.workingDir);
       if (!pathCheck.ok) {
-        return { content: `Error: ${pathCheck.error}`, isError: true };
+        return {
+          content: `Error: ${pathCheck.error}. To read files outside the workspace, use the host_file_read tool instead.`,
+          isError: true,
+        };
       }
       return readImageFile(pathCheck.resolved);
     }
@@ -89,8 +92,16 @@ class FileReadTool implements Tool {
             content: `Error reading file "${rawPath}": ${error.message}`,
             isError: true,
           };
-        default:
-          return { content: `Error: ${error.message}`, isError: true };
+        default: {
+          const hint =
+            error.code === "PATH_OUT_OF_BOUNDS"
+              ? ". To read files outside the workspace, use the host_file_read tool instead."
+              : "";
+          return {
+            content: `Error: ${error.message}${hint}`,
+            isError: true,
+          };
+        }
       }
     }
 

package/src/tools/filesystem/write.ts

@@ -10,7 +10,7 @@ class FileWriteTool implements Tool {
   name = "file_write";
   description = "Write content to a file, creating it if it does not exist";
   category = "filesystem";
-  defaultRiskLevel = RiskLevel.Medium;
+  defaultRiskLevel = RiskLevel.Low;
 
   getDefinition(): ToolDefinition {
     return {

package/src/tools/host-filesystem/edit.ts

@@ -7,7 +7,8 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 class HostFileEditTool implements Tool {
   name = "host_file_edit";
-  description = "Replace exact text in a host filesystem file with new text";
+  description =
+    "Replace exact text in a host filesystem file with new text. Not for workspace files under .vellum (use file_edit instead).";
   category = "host-filesystem";
   defaultRiskLevel = RiskLevel.Medium;
 

package/src/tools/host-filesystem/read.ts

@@ -1,12 +1,19 @@
+import { extname } from "node:path";
+
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
+import {
+  IMAGE_EXTENSIONS,
+  readImageFile,
+} from "../shared/filesystem/image-read.js";
 import { hostPolicy } from "../shared/filesystem/path-policy.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 class HostFileReadTool implements Tool {
   name = "host_file_read";
-  description = "Read the contents of a file on the host filesystem";
+  description =
+    "Read the contents of a file on the host filesystem, including images (JPEG, PNG, GIF, WebP). Not for workspace files under .vellum (use file_read instead).";
   category = "host-filesystem";
   defaultRiskLevel = RiskLevel.Medium;
 
@@ -62,6 +69,16 @@ class HostFileReadTool implements Tool {
       );
     }
 
+    // For image files, delegate to the shared image reader.
+    const ext = extname(rawPath).toLowerCase();
+    if (IMAGE_EXTENSIONS.has(ext)) {
+      const pathCheck = hostPolicy(rawPath);
+      if (!pathCheck.ok) {
+        return { content: `Error: ${pathCheck.error}`, isError: true };
+      }
+      return readImageFile(pathCheck.resolved);
+    }
+
     const ops = new FileSystemOps(hostPolicy);
 
     const result = ops.readFileSafe({

package/src/tools/host-filesystem/write.ts

@@ -8,7 +8,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class HostFileWriteTool implements Tool {
   name = "host_file_write";
   description =
-    "Write content to a file on the host filesystem, creating it if it does not exist";
+    "Write content to a file on the host filesystem, creating it if it does not exist. Not for workspace files under .vellum (use file_write instead).";
   category = "host-filesystem";
   defaultRiskLevel = RiskLevel.Medium;