@vellumai/assistant 0.4.56 → 0.4.57

package/src/tools/host-terminal/host-shell.ts

@@ -1,10 +1,10 @@
 /**
- * Host shell tool — `host_bash`.
+ * Host shell tool - `host_bash`.
  *
  * Unlike the sandboxed `bash` tool, `host_bash` runs commands directly on the
  * host machine without the OS-level sandbox. Under CES shell lockdown for
  * untrusted actors, `host_bash` remains available as a user-approved escape
- * hatch — the guardian must explicitly approve each invocation. It is NOT part
+ * hatch - the guardian must explicitly approve each invocation. It is NOT part
  * of the strong CES secrecy guarantee because it runs unsandboxed and could
  * access protected paths or credential material on disk.
  *
@@ -48,7 +48,8 @@ function buildHostShellEnv(): Record<string, string> {
 
 class HostShellTool implements Tool {
   name = "host_bash";
-  description = "Execute a shell command on the host machine";
+  description =
+    "LAST RESORT — Execute a shell command directly on the user's host machine. You MUST strongly prefer the regular `bash` tool for all commands. Only use `host_bash` when you are absolutely certain the command MUST run on the user's host machine and CANNOT run in the workspace (e.g., managing host-level system services, accessing host-only peripherals, or interacting with host paths outside the workspace). If in doubt, use `bash` instead. Approval-gated: your user must allow each invocation. Do not use for commands that require injected credentials or secrets.";
   category = "host-terminal";
   // host_bash is a weaker-tier escape hatch under CES lockdown. It remains
   // Medium risk by default but persistent approvals are disabled for
@@ -64,9 +65,9 @@ class HostShellTool implements Tool {
         properties: {
           command: {
             type: "string",
-            description: "The host shell command to execute",
+            description: "The host 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".',
@@ -82,7 +83,7 @@ class HostShellTool implements Tool {
               "Optional timeout in seconds. Uses configured default and max limits.",
           },
         },
-        required: ["command", "reason"],
+        required: ["command", "activity"],
       },
     };
   }
@@ -128,7 +129,7 @@ class HostShellTool implements Tool {
     // lockdown is active for untrusted actors, persistent approvals are
     // disabled (every invocation requires fresh guardian approval) and the
     // VELLUM_UNTRUSTED_SHELL flag is injected to self-deny raw-secret CLI
-    // commands. This does NOT provide the strong CES secrecy guarantee —
+    // commands. This does NOT provide the strong CES secrecy guarantee -
     // the subprocess runs unsandboxed and could access protected paths.
     //
     // NOTE: forcePromptSideEffects is set in executor.ts BEFORE the
@@ -260,7 +261,7 @@ class HostShellTool implements Tool {
         if ((err as NodeJS.ErrnoException).code === "ENOENT") {
           hint = !existsSync(workingDir)
             ? `. The working directory does not exist: ${workingDir}`
-            : ". 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.";
         }
         resolve({
           content: `Error spawning command: ${err.message}${hint}`,

package/src/tools/mcp/mcp-tool-factory.ts

@@ -37,9 +37,10 @@ export function createMcpTool(
 ): Tool {
   const namespacedName = mcpToolName(serverId, metadata.name);
   const riskLevel = riskMap[serverConfig.defaultRiskLevel] ?? RiskLevel.High;
-  const serverDefinesReason = schemaDefinesProperty(
+  const serverDefinesActivity = schemaDefinesProperty(
     metadata.inputSchema,
-    "reason",
+    "activity",
+    { refBehavior: "assume-defined" },
   );
 
   return {
@@ -64,14 +65,14 @@ export function createMcpTool(
       _context: ToolContext,
     ): Promise<ToolExecutionResult> {
       try {
-        // Strip injected reason before sending to MCP server
-        const { reason: _reason, ...mcpInput } = input as Record<
+        // Strip injected activity before sending to MCP server
+        const { activity: _activity, ...mcpInput } = input as Record<
           string,
           unknown
         > & {
-          reason?: unknown;
+          activity?: unknown;
         };
-        const forwardInput = serverDefinesReason ? input : mcpInput;
+        const forwardInput = serverDefinesActivity ? input : mcpInput;
         const result = await manager.callTool(
           serverId,
           metadata.name,

package/src/tools/memory/definitions.ts

@@ -3,19 +3,19 @@ import type { ToolDefinition } from "../../providers/types.js";
 export const memoryRecallDefinition: ToolDefinition = {
   name: "memory_recall",
   description:
-    "Hybrid search across memory (semantic and recency) for specific information. Use this when you need to recall details about past conversations, decisions, preferences, project context, or any prior knowledge. Returns formatted memory context with item IDs for use with memory_manage.",
+    "Hybrid search across memory (semantic and recency) for specific information. Relevant memories are auto-injected each turn, so only call this when the auto-injected context doesn't contain what you need - e.g. the user references a past session, or you need deeper recall. Be specific in your query for best results. Returns formatted memory context with item IDs for use with memory_manage.",
   input_schema: {
     type: "object",
     properties: {
       query: {
         type: "string",
-        description: "The search query — be specific and descriptive",
+        description: "The search query - be specific and descriptive",
       },
       scope: {
         type: "string",
         enum: ["default", "conversation"],
         description:
-          'Scope to search — "default" searches all memory, "conversation" restricts to current conversation',
+          'Scope to search - "default" searches all memory, "conversation" restricts to current conversation',
       },
     },
     required: ["query"],
@@ -47,7 +47,8 @@ const memoryManageProperties = {
       "constraint",
       "event",
     ],
-    description: "Category of the memory item (required for save)",
+    description:
+      'Category of the memory item (required for save). Use "constraint" for mistakes, gotchas, discoveries, and working solutions - write as advice to your future self.',
   },
   subject: {
     type: "string" as const,
@@ -58,7 +59,7 @@ const memoryManageProperties = {
 export const memoryManageDefinition: ToolDefinition = {
   name: "memory_manage",
   description:
-    "Save, update, or delete memory items. Use 'save' for new information worth remembering, 'update' to correct existing items, 'delete' to remove outdated items.",
+    "Save, update, or delete memory items. Memory does not survive session restarts - if you want to remember something, save it now. Use 'save' for new information worth remembering (facts, preferences, mistakes, discoveries, gotchas), 'update' to correct existing items, 'delete' to remove outdated items. When a user says 'remember this', save immediately. For user profile or personality changes, update workspace files (USER.md, SOUL.md) instead.",
   input_schema: {
     type: "object",
     properties: memoryManageProperties,

package/src/tools/memory/handlers.test.ts

@@ -305,7 +305,7 @@ describe("handleMemoryRecall", () => {
   // ── Empty results ─────────────────────────────────────────────────
 
   test("returns empty result when no memories match", async () => {
-    // No items seeded — tables cleared in beforeEach
+    // No items seeded - tables cleared in beforeEach
     const result = await handleMemoryRecall(
       { query: "quantum physics" },
       TEST_CONFIG,

package/src/tools/network/__tests__/web-search.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
-// Mutable mock state — set per test
+// Mutable mock state - set per test
 let mockWebSearchProvider: string | undefined = "perplexity";
 let mockBraveSecureKey: string | undefined;
 let mockPerplexitySecureKey: string | undefined;
@@ -383,8 +383,8 @@ describe("web_search tool", () => {
     expect(capturedUrl).toContain("perplexity");
   });
 
-  test("maps anthropic-native to perplexity", async () => {
-    mockWebSearchProvider = "anthropic-native";
+  test("maps inference-provider-native to perplexity", async () => {
+    mockWebSearchProvider = "inference-provider-native";
     mockPerplexitySecureKey = "pplx-key";
     let capturedUrl = "";
     globalThis.fetch = (async (url: string) => {

package/src/tools/network/domain-normalize.ts

@@ -55,13 +55,13 @@ export function normalizeDomain(input: string): DomainInfo | null {
 
   if (!hostname) return null;
 
-  // Reject IP addresses and localhost — they don't have registrable domains
+  // Reject IP addresses and localhost - they don't have registrable domains
   if (isIPAddress(hostname) || hostname === "localhost") {
     return null;
   }
 
   // Reject malformed hostnames. Each DNS label must start and end with an
-  // alphanumeric and contain only alphanumerics/hyphens — no consecutive dots,
+  // alphanumeric and contain only alphanumerics/hyphens - no consecutive dots,
   // no labels starting or ending with hyphens.
   if (
     !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/.test(

package/src/tools/network/script-proxy/session-manager.ts

@@ -128,7 +128,7 @@ function resolveInjectionTemplates(
 }
 
 // ---------------------------------------------------------------------------
-// Session start hooks — wires assistant credential resolution into core
+// Session start hooks - wires assistant credential resolution into core
 // ---------------------------------------------------------------------------
 
 function buildSessionStartHooks(): SessionStartHooks {
@@ -216,13 +216,13 @@ function buildSessionStartHooks(): SessionStartHooks {
               if (bestCandidates.length === 1) {
                 perCredentialBest.push({ credId, tpl: bestCandidates[0] });
               } else if (bestCandidates.length > 1) {
-                // Same credential, same-specificity tie — ambiguous, block
+                // Same credential, same-specificity tie - ambiguous, block
                 return null;
               }
             }
 
             if (perCredentialBest.length === 0) return req.headers;
-            // Cross-credential ambiguity — block
+            // Cross-credential ambiguity - block
             if (perCredentialBest.length > 1) return null;
 
             const { credId, tpl } = perCredentialBest[0];
@@ -245,7 +245,7 @@ function buildSessionStartHooks(): SessionStartHooks {
               if (!headerValue) {
                 log.warn(
                   { host: req.hostname, credentialId: credId },
-                  "MITM rewrite: blocking request — composeWith credential missing",
+                  "MITM rewrite: blocking request - composeWith credential missing",
                 );
                 return null;
               }
@@ -325,7 +325,7 @@ function buildSessionStartHooks(): SessionStartHooks {
               if (!headerValue) {
                 log.warn(
                   { hostname, credentialId },
-                  "Policy: blocking matched request — composeWith credential missing",
+                  "Policy: blocking matched request - composeWith credential missing",
                 );
                 return null;
               }
@@ -334,7 +334,7 @@ function buildSessionStartHooks(): SessionStartHooks {
             return {};
           }
           case "ambiguous":
-            return null; // block — can't auto-resolve
+            return null; // block - can't auto-resolve
           case "ask_missing_credential":
           case "ask_unauthenticated":
             if (managed.approvalCallback) {
@@ -364,7 +364,7 @@ function buildSessionStartHooks(): SessionStartHooks {
 }
 
 // ---------------------------------------------------------------------------
-// Public API — thin wrappers that delegate to session-core with the store
+// Public API - thin wrappers that delegate to session-core with the store
 // ---------------------------------------------------------------------------
 
 /**
@@ -389,7 +389,7 @@ export function createSession(
 }
 
 /**
- * Start the proxy session — opens an HTTP server on an ephemeral port.
+ * Start the proxy session - opens an HTTP server on an ephemeral port.
  */
 export async function startSession(
   sessionId: ProxySessionId,
@@ -399,7 +399,7 @@ export async function startSession(
 }
 
 /**
- * Gracefully stop a session — closes the HTTP server and clears the idle timer.
+ * Gracefully stop a session - closes the HTTP server and clears the idle timer.
  */
 export async function stopSession(sessionId: ProxySessionId): Promise<void> {
   return coreStopSession(sessionId, store);
@@ -414,7 +414,7 @@ export function getSessionEnv(sessionId: ProxySessionId): ProxyEnvVars {
 }
 
 /**
- * Atomically acquire a proxy session for a conversation — reuses an active
+ * Atomically acquire a proxy session for a conversation - reuses an active
  * session or creates + starts a new one.
  */
 export async function getOrStartSession(

package/src/tools/network/web-fetch.ts

@@ -309,7 +309,7 @@ function normalizeText(text: string): string {
 }
 
 // Lighter normalization for markdown that preserves indentation, multiple spaces,
-// and trailing whitespace — all of which carry semantic meaning in markdown
+// and trailing whitespace - all of which carry semantic meaning in markdown
 // (code blocks, nested lists, table alignment, line breaks).
 function normalizeMarkdown(text: string): string {
   return text

package/src/tools/network/web-search.ts

@@ -44,9 +44,9 @@ interface PerplexityResponse {
 function getWebSearchProvider(): WebSearchProvider {
   const config = getConfig();
   const configured = config.services["web-search"].provider ?? "perplexity";
-  // 'anthropic-native' is handled by the Anthropic client directly;
-  // fall back to perplexity for other providers.
-  if (configured === "anthropic-native") return "perplexity";
+  // 'inference-provider-native' is handled by the inference provider client
+  // directly; fall back to perplexity for other providers.
+  if (configured === "inference-provider-native") return "perplexity";
   return configured as WebSearchProvider;
 }
 

package/src/tools/permission-checker.ts

@@ -90,7 +90,7 @@ export class PermissionChecker {
       );
 
       // Private conversations force prompting for side-effect tools even when a
-      // trust/allow rule would auto-allow. Deny decisions are preserved —
+      // trust/allow rule would auto-allow. Deny decisions are preserved -
       // only allow → prompt promotion happens here.
       if (
         context.forcePromptSideEffects &&
@@ -139,8 +139,8 @@ export class PermissionChecker {
       if (result.decision === "prompt") {
         // Guardian-trust sessions (e.g. scheduled jobs, reminders) should be
         // able to use bundled tools without interactive approval. The guardian
-        // is the owner — prompting makes no sense when there is no client.
-        // Exception: requireFreshApproval tools cannot be auto-approved —
+        // is the owner - prompting makes no sense when there is no client.
+        // Exception: requireFreshApproval tools cannot be auto-approved -
         // without a human present, bundle installation must be denied.
         if (
           context.isInteractive === false &&
@@ -158,7 +158,7 @@ export class PermissionChecker {
           };
         }
 
-        // Non-interactive sessions have no client to respond to prompts —
+        // Non-interactive sessions have no client to respond to prompts -
         // deny immediately instead of blocking for the full permission timeout.
         if (context.isInteractive === false) {
           const durationMs = Date.now() - startTime;
@@ -190,9 +190,9 @@ export class PermissionChecker {
         // Temporary approval override: if the guardian has enabled a
         // conversation-scoped "allow all" mode (allow_10m or allow_conversation),
         // skip the interactive prompt and auto-approve. Only applies to
-        // guardian actors — untrusted actors cannot leverage this to bypass
+        // guardian actors - untrusted actors cannot leverage this to bypass
         // guardian-required gates (those are enforced in pre-execution gates).
-        // Exception: requireFreshApproval tools must always show the prompt —
+        // Exception: requireFreshApproval tools must always show the prompt -
         // cached temporary overrides cannot substitute for per-invocation
         // human review.
         if (
@@ -206,7 +206,7 @@ export class PermissionChecker {
               riskLevel,
               conversationId: context.conversationId,
             },
-            "Temporary approval override active — auto-approving without prompt",
+            "Temporary approval override active - auto-approving without prompt",
           );
           return { allowed: true, decision: "temporary_override", riskLevel };
         }
@@ -237,7 +237,7 @@ export class PermissionChecker {
         const persistentDecisionsAllowed = !context.requireFreshApproval;
 
         // Offer temporary approval options to guardians. Suppressed when
-        // requireFreshApproval is true — temporary overrides would be
+        // requireFreshApproval is true - temporary overrides would be
         // misleading since future invocations still require fresh approval.
         const temporaryOptionsAvailable:
           | Array<"allow_10m" | "allow_conversation">

package/src/tools/registry.ts

@@ -65,7 +65,7 @@ export function registerSkillTools(newTools: Tool[]): Tool[] {
         );
         continue;
       }
-      // Existing is also a skill tool — only allow replacement from the same owner.
+      // Existing is also a skill tool - only allow replacement from the same owner.
       if (existing.ownerSkillId !== tool.ownerSkillId) {
         throw new Error(
           `Skill tool "${tool.name}" is already registered by skill "${existing.ownerSkillId}"`,
@@ -108,7 +108,7 @@ export function unregisterSkillTools(skillId: string): void {
     return;
   }
 
-  // Last reference — actually remove the tools
+  // Last reference - actually remove the tools
   skillRefCount.delete(skillId);
   for (const [name, tool] of tools) {
     if (tool.origin === "skill" && tool.ownerSkillId === skillId) {
@@ -210,9 +210,9 @@ export function getSkillRefCount(skillId: string): number {
 }
 
 export function getAllToolDefinitions(): ToolDefinition[] {
-  // Exclude proxy tools (e.g. computer_use_* tools) — they are projected
+  // Exclude proxy tools (e.g. computer_use_* tools) - they are projected
   // into sessions by the skill system, not via the global tool list.
-  // Exclude skill-origin tools — they are managed by the session-level
+  // Exclude skill-origin tools - they are managed by the session-level
   // skill projection system (projectSkillTools) and must not leak into
   // the base tool list, which is shared across sessions via the global
   // registry.  Including them here causes "Tool names must be unique"
@@ -239,7 +239,7 @@ export async function initializeTools(): Promise<void> {
   // Import tool modules to trigger registration side effects.
   await loadEagerModules();
 
-  // Explicit tool instances — no side-effect import required.
+  // Explicit tool instances - no side-effect import required.
   for (const tool of explicitTools) {
     registerTool(tool);
   }
@@ -256,7 +256,7 @@ export async function initializeTools(): Promise<void> {
     registerTool(tool);
   }
 
-  // CES tools — registered only when the CES feature flag is enabled.
+  // CES tools - registered only when the CES feature flag is enabled.
   const activeCesTools = getCesToolsIfEnabled();
   for (const tool of activeCesTools) {
     registerTool(tool);
@@ -298,7 +298,7 @@ export async function initializeTools(): Promise<void> {
 
 /**
  * Reset registry to its post-initializeTools() baseline. Exposed
- * exclusively for test isolation — prevents cross-file contamination
+ * exclusively for test isolation - prevents cross-file contamination
  * when multiple test suites share a single Bun process.
  *
  * Restores core tools from a snapshot taken after the first

package/src/tools/schedule/list.ts

@@ -116,14 +116,14 @@ export async function executeScheduleList(
     if (oneShot) {
       const fireTime = formatLocalDate(job.nextRunAt);
       lines.push(
-        `  - [${status}] ${job.name} (id: ${job.id}) (one-shot, ${job.mode}) — fire at: ${fireTime} [${job.status}]`,
+        `  - [${status}] ${job.name} (id: ${job.id}) (one-shot, ${job.mode}) - fire at: ${fireTime} [${job.status}]`,
       );
     } else {
       const next = job.enabled ? formatLocalDate(job.nextRunAt) : "n/a";
       lines.push(
         `  - [${status}] ${job.name} (id: ${job.id}) ([${
           job.syntax
-        }] ${describeSchedule(job)}, ${job.mode}) — next: ${next}`,
+        }] ${describeSchedule(job)}, ${job.mode}) - next: ${next}`,
       );
     }
   }

package/src/tools/schema-transforms.ts

@@ -1,26 +1,22 @@
 import type { ToolDefinition } from "../providers/types.js";
 
 /**
- * Tools that should never have a `reason` field injected into their schema.
+ * Tools that should never have an `activity` field injected into their schema.
+ * Now empty — all tools define their own `activity` property or get it injected.
  */
-export const REASON_SKIP_SET = new Set<string>([
-  "skill_execute",
-  "bash",
-  "host_bash",
-  "request_system_permission",
-]);
+export const ACTIVITY_SKIP_SET = new Set<string>();
 
 /**
- * Injects a `reason` string property into each tool definition's input schema,
- * unless the tool is in the skip set, already has a reason field, or has a
- * non-object schema.
+ * Injects an `activity` string property into each tool definition's input
+ * schema, unless the tool is in the skip set, already has an activity field,
+ * or has a non-object schema.
  *
- * CRITICAL: Never mutates the input definitions — always returns deep clones
+ * CRITICAL: Never mutates the input definitions - always returns deep clones
  * for any modified definition, since `getDefinition()` returns shared refs.
  */
-export function injectReasonField(
+export function injectActivityField(
   definitions: ToolDefinition[],
-  skip: Set<string> = REASON_SKIP_SET,
+  skip: Set<string> = ACTIVITY_SKIP_SET,
 ): ToolDefinition[] {
   return definitions.map((def) => {
     if (skip.has(def.name)) {
@@ -33,15 +29,22 @@ export function injectReasonField(
     }
 
     const properties = schema.properties as Record<string, unknown>;
-    if (schemaDefinesProperty(schema, "reason")) {
+    if (schemaDefinesProperty(schema, "activity")) {
       return def;
     }
 
     // Deep clone to avoid mutating shared refs
-    const newProperties = { ...properties, reason: { type: "string" } };
+    const newProperties = {
+      ...properties,
+      activity: {
+        type: "string",
+        description:
+          "Brief, natural description of what you're doing, shown as a live status update (e.g. 'Checking your project settings')",
+      },
+    };
     const existingRequired = Array.isArray(schema.required)
-      ? [...schema.required, "reason"]
-      : ["reason"];
+      ? [...schema.required, "activity"]
+      : ["activity"];
 
     return {
       ...def,
@@ -57,21 +60,28 @@ export function injectReasonField(
 /**
  * Checks whether a JSON Schema defines a given property name.
  * Walks `allOf`, `oneOf`, `anyOf` recursively.
- * Fail-closed on `$ref`: returns false if a `$ref` is encountered.
+ *
+ * `$ref` handling is configurable via `refBehavior`:
+ * - `'assume-undefined'` (default): fail-closed, treat `$ref` as not defining
+ *   the property. Good for injection (safe to double-inject).
+ * - `'assume-defined'`: fail-open, treat `$ref` as possibly defining the
+ *   property. Good for stripping decisions (don't strip what the server may need).
  */
 export function schemaDefinesProperty(
   schema: unknown,
   propertyName: string,
+  options?: { refBehavior?: "assume-defined" | "assume-undefined" },
 ): boolean {
   if (schema == null || typeof schema !== "object") {
     return false;
   }
 
   const s = schema as Record<string, unknown>;
+  const refBehavior = options?.refBehavior ?? "assume-undefined";
 
-  // Fail-closed on $ref — we can't resolve it, so treat as "doesn't define it"
+  // $ref: we can't resolve it, so use the configured behavior
   if ("$ref" in s) {
-    return false;
+    return refBehavior === "assume-defined";
   }
 
   // Check direct properties
@@ -88,7 +98,7 @@ export function schemaDefinesProperty(
     const arr = s[keyword];
     if (Array.isArray(arr)) {
       for (const member of arr) {
-        if (schemaDefinesProperty(member, propertyName)) {
+        if (schemaDefinesProperty(member, propertyName, options)) {
           return true;
         }
       }

package/src/tools/secret-detection-handler.ts

@@ -371,7 +371,7 @@ export class SecretDetectionHandler {
       };
     }
 
-    // User allowed — pass content through unchanged
+    // User allowed - pass content through unchanged
     return { result: execResult, earlyReturn: false };
   }
 }

package/src/tools/sensitive-output-placeholders.ts

@@ -43,7 +43,7 @@ const VALID_KINDS = new Set<string>(Object.keys(KIND_PREFIX));
 
 /**
  * Generate an 8-char uppercase base-36 short ID.
- * Provides ~41 bits of entropy — sufficient for intra-request uniqueness.
+ * Provides ~41 bits of entropy - sufficient for intra-request uniqueness.
  */
 function generateShortId(): string {
   const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";

package/src/tools/shared/filesystem/edit-engine.ts

@@ -29,7 +29,7 @@ export type EditEngineResult =
  * Core match/replace logic shared by both sandbox and host edit tools,
  * and by the executor's preview-diff computation.
  *
- * This function is pure — it takes file content and edit parameters and
+ * This function is pure - it takes file content and edit parameters and
  * returns the result without performing any I/O.
  */
 export function applyEdit(

package/src/tools/shared/filesystem/file-ops-service.ts

@@ -132,7 +132,7 @@ export class FileSystemOps {
         try {
           oldContent = readFileSync(filePath, "utf-8");
         } catch {
-          // Unreadable existing file — keep oldContent as empty string.
+          // Unreadable existing file - keep oldContent as empty string.
         }
       }
 
@@ -167,14 +167,14 @@ export class FileSystemOps {
     }
     const filePath = pathCheck.resolved;
 
-    // Size-check the file on disk (swallow ENOENT — readFileSync gives a clearer error)
+    // Size-check the file on disk (swallow ENOENT - readFileSync gives a clearer error)
     try {
       const sizeErr = checkFileSizeOnDisk(filePath, this.sizeLimit);
       if (sizeErr) {
         return { ok: false, error: Err.sizeLimitExceeded(filePath, sizeErr) };
       }
     } catch {
-      // Fall through — the readFileSync below will surface NOT_FOUND.
+      // Fall through - the readFileSync below will surface NOT_FOUND.
     }
 
     let content: string;

package/src/tools/shared/filesystem/image-read.ts

@@ -14,7 +14,8 @@ export const IMAGE_EXTENSIONS = new Set([
   ".webp",
 ]);
 
-const MAX_SIZE_BYTES = 20 * 1024 * 1024; // 20 MB
+const MAX_SIZE_BYTES = 20 * 1024 * 1024; // 20 MB — LLM API transport limit (post-optimization)
+const MAX_SOURCE_SIZE_BYTES = 100 * 1024 * 1024; // 100 MB — pre-optimization guard
 
 // Images above this threshold get auto-optimized via sips (macOS) to avoid
 // sending multi-MB base64 payloads to the LLM API.
@@ -102,7 +103,7 @@ function optimizeWithSips(srcPath: string): string | null {
  * Read an image file from disk, optionally optimize it, and return a
  * ToolExecutionResult with base64-encoded image content blocks.
  *
- * The caller is responsible for path resolution and sandbox enforcement —
+ * The caller is responsible for path resolution and sandbox enforcement -
  * `resolvedPath` must be an already-validated absolute path.
  */
 export function readImageFile(resolvedPath: string): ToolExecutionResult {
@@ -120,10 +121,10 @@ export function readImageFile(resolvedPath: string): ToolExecutionResult {
     return { content: `Error: ${resolvedPath} is not a file`, isError: true };
   }
 
-  if (stat.size > MAX_SIZE_BYTES) {
+  if (stat.size > MAX_SOURCE_SIZE_BYTES) {
     const sizeMB = (stat.size / (1024 * 1024)).toFixed(1);
     return {
-      content: `Error: image too large (${sizeMB} MB). Maximum is 20 MB.`,
+      content: `Error: image too large (${sizeMB} MB). Maximum source file size is 100 MB.`,
       isError: true,
     };
   }
@@ -139,6 +140,14 @@ export function readImageFile(resolvedPath: string): ToolExecutionResult {
         buffer = readFileSync(tmpPath) as Buffer;
         optimized = true;
       } else {
+        // sips unavailable — fast-fail if original file exceeds the transport limit
+        if (stat.size > MAX_SIZE_BYTES) {
+          const sizeMB = (stat.size / (1024 * 1024)).toFixed(1);
+          return {
+            content: `Error: image too large (${sizeMB} MB). Maximum is 20 MB. Image optimization (sips) is unavailable on this platform.`,
+            isError: true,
+          };
+        }
         buffer = readFileSync(resolvedPath) as Buffer;
       }
     } else {
@@ -157,7 +166,18 @@ export function readImageFile(resolvedPath: string): ToolExecutionResult {
     }
   }
 
-  // Detect actual format from magic bytes — never trust the file extension
+  if (buffer.length > MAX_SIZE_BYTES) {
+    const sizeMB = (buffer.length / (1024 * 1024)).toFixed(1);
+    const msg = optimized
+      ? `Error: image too large after optimization (${sizeMB} MB). Maximum is 20 MB.`
+      : `Error: image too large (${sizeMB} MB). Maximum is 20 MB.`;
+    return {
+      content: msg,
+      isError: true,
+    };
+  }
+
+  // Detect actual format from magic bytes - never trust the file extension
   // alone, since sips converts to JPEG and files can be misnamed.
   const detectedType = detectMediaType(buffer);
   if (!detectedType) {