@vellumai/assistant 0.4.55 → 0.4.57

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
@@ -361,7 +361,7 @@ function extractHtmlMetadata(html: string): {
   const stripped = candidate.replace(/<script[\s>][\s\S]*?<\/script>/gi, "");
   const headEnd = stripped.search(/<\/head[\s>]/i);
   const searchRegion =
-    headEnd > 0 ? stripped.slice(0, headEnd + 10) : stripped.slice(0, 50_000);
+    headEnd >= 0 ? stripped.slice(0, headEnd + 10) : stripped.slice(0, 50_000);
 
   const title = extractFirstMatch(
     searchRegion,

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

@@ -1,7 +1,7 @@
 import { getConfig } from "../../config/loader.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
-import { getSecureKeyAsync } from "../../security/secure-keys.js";
+import { getProviderKeyAsync } from "../../security/secure-keys.js";
 import { getLogger } from "../../util/logger.js";
 import {
   DEFAULT_BASE_DELAY_MS,
@@ -43,10 +43,10 @@ interface PerplexityResponse {
 
 function getWebSearchProvider(): WebSearchProvider {
   const config = getConfig();
-  const configured = config.webSearchProvider ?? "perplexity";
-  // 'anthropic-native' is handled by the Anthropic client directly;
-  // fall back to perplexity for other providers.
-  if (configured === "anthropic-native") return "perplexity";
+  const configured = config.services["web-search"].provider ?? "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;
 }
 
@@ -54,11 +54,11 @@ async function getApiKey(
   provider: WebSearchProvider,
 ): Promise<string | undefined> {
   if (provider === "brave") {
-    return (await getSecureKeyAsync("brave")) ?? undefined;
+    return (await getProviderKeyAsync("brave")) ?? undefined;
   }
 
   // Perplexity
-  return (await getSecureKeyAsync("perplexity")) ?? undefined;
+  return (await getProviderKeyAsync("perplexity")) ?? undefined;
 }
 
 function formatBraveResults(

package/src/tools/permission-checker.ts

@@ -10,9 +10,9 @@ import type { PermissionPrompter } from "../permissions/prompter.js";
 import { addRule } from "../permissions/trust-store.js";
 import {
   getEffectiveMode,
-  setThreadMode,
+  setConversationMode,
   setTimedMode,
-} from "../runtime/session-approval-overrides.js";
+} from "../runtime/conversation-approval-overrides.js";
 import { getLogger } from "../util/logger.js";
 import { buildPolicyContext } from "./policy-context.js";
 import { isSideEffectTool } from "./side-effects.js";
@@ -89,8 +89,8 @@ export class PermissionChecker {
         context.signal,
       );
 
-      // Private threads force prompting for side-effect tools even when a
-      // trust/allow rule would auto-allow. Deny decisions are preserved —
+      // Private conversations force prompting for side-effect tools even when a
+      // trust/allow rule would auto-allow. Deny decisions are preserved -
       // only allow → prompt promotion happens here.
       if (
         context.forcePromptSideEffects &&
@@ -99,7 +99,18 @@ export class PermissionChecker {
       ) {
         result.decision = "prompt";
         result.reason =
-          "Private thread: side-effect tools require explicit approval";
+          "Private conversation: side-effect tools require explicit approval";
+      }
+
+      // requireFreshApproval independently promotes allow → prompt so that
+      // cached grants, persistent trust rules, and auto-approve shortcuts
+      // cannot bypass the interactive prompt. This is separate from the
+      // forcePromptSideEffects path above to ensure requireFreshApproval
+      // is self-sufficient without relying on SIDE_EFFECT_TOOLS membership.
+      if (context.requireFreshApproval && result.decision === "allow") {
+        result.decision = "prompt";
+        result.reason =
+          "Fresh approval required: per-invocation human review enforced";
       }
 
       if (result.decision === "deny") {
@@ -110,7 +121,6 @@ export class PermissionChecker {
           executionTarget,
           input,
           workingDir: context.workingDir,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           requestId: context.requestId,
           riskLevel,
@@ -129,10 +139,13 @@ 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.
+        // 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 &&
-          context.trustClass === "guardian"
+          context.trustClass === "guardian" &&
+          !context.requireFreshApproval
         ) {
           log.info(
             { toolName: name, riskLevel },
@@ -145,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;
@@ -159,7 +172,6 @@ export class PermissionChecker {
             executionTarget,
             input,
             workingDir: context.workingDir,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             requestId: context.requestId,
             riskLevel,
@@ -176,13 +188,17 @@ export class PermissionChecker {
         }
 
         // Temporary approval override: if the guardian has enabled a
-        // conversation-scoped "allow all" mode (allow_10m or allow_thread),
+        // 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 -
+        // cached temporary overrides cannot substitute for per-invocation
+        // human review.
         if (
           context.trustClass === "guardian" &&
-          getEffectiveMode(context.conversationId) !== undefined
+          getEffectiveMode(context.conversationId) !== undefined &&
+          !context.requireFreshApproval
         ) {
           log.info(
             {
@@ -190,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 };
         }
@@ -218,14 +234,16 @@ export class PermissionChecker {
           sandboxed = wrapped.sandboxed;
         }
 
-        const persistentDecisionsAllowed = true;
+        const persistentDecisionsAllowed = !context.requireFreshApproval;
 
-        // Offer temporary approval options to guardians.
+        // Offer temporary approval options to guardians. Suppressed when
+        // requireFreshApproval is true - temporary overrides would be
+        // misleading since future invocations still require fresh approval.
         const temporaryOptionsAvailable:
-          | Array<"allow_10m" | "allow_thread">
+          | Array<"allow_10m" | "allow_conversation">
           | undefined =
-          context.trustClass === "guardian"
-            ? ["allow_10m", "allow_thread"]
+          context.trustClass === "guardian" && !context.requireFreshApproval
+            ? ["allow_10m", "allow_conversation"]
             : undefined;
 
         emitLifecycleEvent({
@@ -234,7 +252,6 @@ export class PermissionChecker {
           executionTarget,
           input,
           workingDir: context.workingDir,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           requestId: context.requestId,
           riskLevel,
@@ -250,7 +267,7 @@ export class PermissionChecker {
           toolName: name,
           input: sanitizeToolInput(name, input),
           riskLevel,
-          sessionId: context.sessionId,
+          conversationId: context.conversationId,
         });
 
         const response = await this.prompter.prompt(
@@ -275,7 +292,7 @@ export class PermissionChecker {
           toolName: name,
           decision: response.decision,
           riskLevel,
-          sessionId: context.sessionId,
+          conversationId: context.conversationId,
         });
 
         if (response.decision === "deny") {
@@ -298,7 +315,6 @@ export class PermissionChecker {
             executionTarget,
             input,
             workingDir: context.workingDir,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             requestId: context.requestId,
             riskLevel,
@@ -347,7 +363,6 @@ export class PermissionChecker {
             executionTarget,
             input,
             workingDir: context.workingDir,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             requestId: context.requestId,
             riskLevel,
@@ -402,7 +417,7 @@ export class PermissionChecker {
         }
 
         // Activate temporary approval mode when the user chooses a
-        // time-limited or thread-scoped override. Subsequent tool
+        // time-limited or conversation-scoped override. Subsequent tool
         // invocations in this conversation will auto-approve without
         // prompting (checked above in the temporary override block).
         if (response.decision === "allow_10m") {
@@ -411,11 +426,11 @@ export class PermissionChecker {
             { toolName: name, conversationId: context.conversationId },
             "Activated timed (10m) temporary approval mode",
           );
-        } else if (response.decision === "allow_thread") {
-          setThreadMode(context.conversationId);
+        } else if (response.decision === "allow_conversation") {
+          setConversationMode(context.conversationId);
           log.info(
             { toolName: name, conversationId: context.conversationId },
-            "Activated thread-scoped temporary approval mode",
+            "Activated conversation-scoped temporary approval mode",
           );
         }
 

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"
@@ -223,8 +223,13 @@ export function getAllToolDefinitions(): ToolDefinition[] {
 }
 
 export async function initializeTools(): Promise<void> {
-  const { loadEagerModules, eagerModuleToolNames, explicitTools } =
-    await import("./tool-manifest.js");
+  const {
+    loadEagerModules,
+    eagerModuleToolNames,
+    explicitTools,
+    getCesToolsIfEnabled,
+    cesTools,
+  } = await import("./tool-manifest.js");
 
   // Capture tool names already in the registry before any manifest
   // registrations.  In production this is empty; in tests a non-skill tool
@@ -234,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);
   }
@@ -251,6 +256,12 @@ export async function initializeTools(): Promise<void> {
     registerTool(tool);
   }
 
+  // CES tools - registered only when the CES feature flag is enabled.
+  const activeCesTools = getCesToolsIfEnabled();
+  for (const tool of activeCesTools) {
+    registerTool(tool);
+  }
+
   registerUiSurfaceTools();
   registerAppTools();
 
@@ -267,6 +278,7 @@ export async function initializeTools(): Promise<void> {
       ...eagerModuleToolNames,
       ...explicitTools.map((t: Tool) => t.name),
       ...hostTools.map((t: Tool) => t.name),
+      ...cesTools.map((t: Tool) => t.name),
       ...allComputerUseTools.map((t: Tool) => t.name),
       ...allUiSurfaceTools.map((t: Tool) => t.name),
       ...coreAppProxyTools.map((t: Tool) => t.name),
@@ -286,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

@@ -84,7 +84,6 @@ export class SecretDetectionHandler {
       executionTarget,
       input,
       workingDir: context.workingDir,
-      sessionId: context.sessionId,
       conversationId: context.conversationId,
       requestId: context.requestId,
       matches: matchSummary,
@@ -229,7 +228,6 @@ export class SecretDetectionHandler {
       executionTarget,
       input,
       workingDir: context.workingDir,
-      sessionId: context.sessionId,
       conversationId: context.conversationId,
       requestId: context.requestId,
       riskLevel,
@@ -244,7 +242,7 @@ export class SecretDetectionHandler {
       riskLevel,
       isError: true,
       durationMs,
-      sessionId: context.sessionId,
+      conversationId: context.conversationId,
     });
 
     return { result: blockedResult, earlyReturn: true };
@@ -282,7 +280,6 @@ export class SecretDetectionHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel: RiskLevel.High,
@@ -297,7 +294,7 @@ export class SecretDetectionHandler {
         riskLevel,
         isError: true,
         durationMs,
-        sessionId: context.sessionId,
+        conversationId: context.conversationId,
       });
 
       return {
@@ -318,7 +315,6 @@ export class SecretDetectionHandler {
       executionTarget,
       input: promptInput,
       workingDir: context.workingDir,
-      sessionId: context.sessionId,
       conversationId: context.conversationId,
       requestId: context.requestId,
       riskLevel: RiskLevel.High,
@@ -352,7 +348,6 @@ export class SecretDetectionHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel: RiskLevel.High,
@@ -367,7 +362,7 @@ export class SecretDetectionHandler {
         riskLevel,
         isError: true,
         durationMs,
-        sessionId: context.sessionId,
+        conversationId: context.conversationId,
       });
 
       return {
@@ -376,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) {

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 {