@vellumai/assistant 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/src/tools/acp/spawn.test.ts

@@ -147,6 +147,11 @@ const { _resetAdapterInstallCacheForTests } =
   await import("../../acp/auto-install.js");
 const { ACP_CLAUDE_OAUTH_MISSING_CODE } =
   await import("../../acp/prepare-agent-env.js");
+const { ACP_CLAUDE_AUTH_REQUIRED_CODE, AcpAuthRequiredError } =
+  await import("../../acp/auth-required.js");
+const { hasAcpConnectCardRaised } =
+  await import("../../acp/acp-connect-card-state.js");
+const { AcpAgentProcess } = await import("../../acp/agent-process.js");
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -547,3 +552,95 @@ describe("executeAcpSpawn — CLAUDE_CODE_OAUTH_TOKEN injection", () => {
     expect(result.errorCode).toBe(ACP_CLAUDE_OAUTH_MISSING_CODE);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Pre-spawn Claude auth rejection
+// ---------------------------------------------------------------------------
+
+describe("pre-spawn Claude auth rejection", () => {
+  test("raises the recovery surface: errorCode, card guidance, registry mark", async () => {
+    // The adapter can reject session creation with auth_required (a stored
+    // credential the server refuses). The error thrown here is produced by
+    // the REAL conversion seam, not hand-built: a wire-shaped JSON-RPC
+    // auth_required rejection driven through AcpAgentProcess.createSession's
+    // actual retry path, so this test fails if that seam stops yielding the
+    // typed error the tool boundary maps to the recovery surface.
+    const proc = new AcpAgentProcess(
+      "claude",
+      { command: "claude-agent-acp", args: [] },
+      (() => ({})) as never,
+    );
+    (proc as unknown as { connection: unknown }).connection = {
+      newSession: () =>
+        Promise.reject({ code: -32000, message: "Authentication required" }),
+    };
+    (proc as unknown as { initializeResponse: unknown }).initializeResponse = {
+      authMethods: [
+        {
+          id: "claude-ai-login",
+          name: "Claude Subscription",
+          type: "terminal",
+        },
+      ],
+    };
+    (proc as unknown as { spawnedEnv: unknown }).spawnedEnv = {};
+    const realSeamError: unknown = await proc.createSession("/tmp").then(
+      () => null,
+      (e: unknown) => e,
+    );
+    expect(realSeamError).toBeInstanceOf(AcpAuthRequiredError);
+
+    spawnMock.mockImplementationOnce(async () => {
+      throw realSeamError;
+    });
+
+    const context = { ...makeContext(), conversationId: "conv-prespawn-auth" };
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      context,
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.errorCode).toBe(ACP_CLAUDE_AUTH_REQUIRED_CODE);
+    expect(result.content).toContain("Connect Claude Code");
+    expect(hasAcpConnectCardRaised("conv-prespawn-auth")).toBe(true);
+  });
+
+  test("a raw wire auth_required object (unwrapped initialize path) gets the same surface", async () => {
+    // initialize() cannot ride withAuthRetry (its response advertises the
+    // methods the retry selects from), so its rejection arrives as the plain
+    // JSON-RPC object rather than the typed error. The gate must recognize
+    // both shapes or this path silently flattens to a generic failure.
+    spawnMock.mockImplementationOnce(async () => {
+      throw { code: -32000, message: "Authentication required" };
+    });
+
+    const context = { ...makeContext(), conversationId: "conv-prespawn-raw" };
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      context,
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.errorCode).toBe(ACP_CLAUDE_AUTH_REQUIRED_CODE);
+    expect(result.content).toContain("Connect Claude Code");
+    expect(hasAcpConnectCardRaised("conv-prespawn-raw")).toBe(true);
+  });
+
+  test("a non-auth spawn failure keeps the plain flattened result", async () => {
+    spawnMock.mockImplementationOnce(async () => {
+      throw new Error("adapter exploded");
+    });
+
+    const context = { ...makeContext(), conversationId: "conv-prespawn-boom" };
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something" },
+      context,
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.errorCode).toBeUndefined();
+    expect(result.content).toContain("adapter exploded");
+    expect(hasAcpConnectCardRaised("conv-prespawn-boom")).toBe(false);
+  });
+});

package/src/tools/acp/spawn.ts

@@ -3,6 +3,12 @@ import { basename } from "node:path";
 import { z } from "zod";
 
 import { markAcpConnectCardRaised } from "../../acp/acp-connect-card-state.js";
+import {
+  ACP_AUTH_RECOVERY_GUIDANCE,
+  ACP_CLAUDE_AUTH_REQUIRED_CODE,
+  CLAUDE_ACP_COMMAND,
+  isAcpAuthRequired,
+} from "../../acp/auth-required.js";
 import { resolveAgentWithAutoInstall } from "../../acp/auto-install.js";
 import { getAcpSessionManager } from "../../acp/index.js";
 import {
@@ -64,10 +70,12 @@ export async function executeAcpSpawn(
     return { content: '"task" is required.', isError: true };
   }
 
-  // Pure precondition: check for a connected client BEFORE any side effects
-  // (auto-install mutates the host via a `bun` global install and can block
-  // for up to the install timeout). Without a client the spawn cannot
-  // succeed anyway.
+  // Pure precondition: the session streams its results through the
+  // conversation's event sink, so a context with no sink at all (a tool run
+  // outside any conversation, e.g. the standalone CLI runner) cannot host a
+  // spawn. Checked BEFORE any side effects (auto-install mutates the host via
+  // a `bun` global install and can block for up to the install timeout).
+  // Inside a conversation the sink always exists and is always live.
   const sendToClient = getSendToClient(context);
   if (!sendToClient) {
     return {
@@ -147,6 +155,32 @@ export async function executeAcpSpawn(
 
     return { content: payload, isError: false };
   } catch (err) {
+    // A pre-spawn rejection of the stored Claude credential (the adapter
+    // raises auth_required during session creation) gets the same recovery
+    // surface as the missing-token preflight: the errorCode raises the inline
+    // Connect card off this failed tool call, the registry mark dedups a
+    // redundant secure prompt, and the guidance keeps the model pointed at
+    // the card. Adapter-gated: the card repairs Claude credentials only.
+    // `isAcpAuthRequired` rather than an instanceof: it also recognizes the
+    // raw JSON-RPC auth_required object, which is how a rejection reaches
+    // this catch from the one protocol call `withAuthRetry` cannot wrap
+    // (`initialize`, whose response is what advertises the auth methods the
+    // retry would need).
+    if (
+      isAcpAuthRequired(err) &&
+      basename(agentConfig.command) === CLAUDE_ACP_COMMAND
+    ) {
+      const message =
+        err instanceof Error
+          ? err.message
+          : String((err as { message?: unknown }).message ?? err);
+      markAcpConnectCardRaised(context.conversationId);
+      return {
+        content: `${message}\n\n${ACP_AUTH_RECOVERY_GUIDANCE}`,
+        isError: true,
+        errorCode: ACP_CLAUDE_AUTH_REQUIRED_CODE,
+      };
+    }
     const msg =
       err instanceof Error
         ? err.message

package/src/tools/credentials/ref-parse.ts

@@ -0,0 +1,35 @@
+/**
+ * Credential reference parsing. Pure string work, no store access.
+ *
+ * `"service/field"` is the shared vocabulary of every credential entry point:
+ * the CLI, the reveal and set routes, and the plugin-facing read and write
+ * APIs all name credentials this way. The rules for what counts as a valid
+ * reference live here so each path applies the same ones.
+ *
+ * Deliberately separate from {@link ./resolve}, which reads the metadata store:
+ * a caller that only needs to split a reference should not import a module
+ * whose behavior depends on what is stored.
+ */
+
+/**
+ * Parse a `"service/field"` credential reference into its parts.
+ *
+ * Returns undefined for anything that is not exactly one non-empty segment on
+ * each side of a single slash: no slash, a leading or trailing slash, or more
+ * than one slash as in `"fal/api/key"`.
+ */
+export function parseServiceFieldRef(
+  ref: string,
+): { service: string; field: string } | undefined {
+  const slashIndex = ref.indexOf("/");
+  if (slashIndex <= 0 || slashIndex >= ref.length - 1) {
+    return undefined;
+  }
+  if (ref.indexOf("/", slashIndex + 1) !== -1) {
+    return undefined;
+  }
+  return {
+    service: ref.slice(0, slashIndex),
+    field: ref.slice(slashIndex + 1),
+  };
+}

package/src/tools/credentials/resolve.ts

@@ -16,6 +16,7 @@ import {
   listCredentialMetadata,
 } from "./metadata-store.js";
 import type { CredentialInjectionTemplate } from "./policy-types.js";
+import { parseServiceFieldRef } from "./ref-parse.js";
 
 export interface ResolvedCredential {
   credentialId: string;
@@ -95,18 +96,11 @@ export function resolveCredentialRef(
   }
 
   // Try as service/field
-  const slashIndex = ref.indexOf("/");
-  if (slashIndex <= 0 || slashIndex >= ref.length - 1) {
+  const parsed = parseServiceFieldRef(ref);
+  if (!parsed) {
     return undefined;
   }
-  // Reject refs with more than one slash (e.g. "fal/api/key")
-  if (ref.indexOf("/", slashIndex + 1) !== -1) {
-    return undefined;
-  }
-
-  const service = ref.slice(0, slashIndex);
-  const field = ref.slice(slashIndex + 1);
-  return resolveByServiceField(service, field);
+  return resolveByServiceField(parsed.service, parsed.field);
 }
 
 /**

package/src/tools/credentials/store.ts

@@ -0,0 +1,168 @@
+/**
+ * Credential write path. The single sequence every "store a credential"
+ * caller runs.
+ *
+ * Storing a credential is not one write: the plaintext goes to the secure
+ * backend, the value is scrubbed from recent transcripts, the metadata record
+ * is upserted, and manual-token providers reconcile their connection row.
+ * Order matters (see {@link storeCredentialValue}), so the sequence lives here
+ * rather than being re-typed per entry point. The `credentials/set` route and
+ * the plugin-facing {@link ../../plugin-api/store-credential.storeCredential}
+ * both compose it.
+ *
+ * The transcript scrub and the connection sync are imported lazily, at the
+ * point of use. Both pull heavy graphs behind them (the scrub reaches the
+ * conversation database and registry; the sync reaches the OAuth store), and
+ * this module sits under `@vellumai/plugin-api`, so a static edge would drag
+ * that machinery into every plugin-api consumer for a write most of them never
+ * perform.
+ *
+ * Callers own their own transport-level argument validation and error mapping;
+ * this module throws {@link InvalidCredentialInputError} for a value it will
+ * not store and {@link CredentialStorageError} when the secure backend write
+ * fails.
+ */
+
+import {
+  ACP_SERVICE,
+  assertAcpCredentialFormat,
+} from "../../acp/acp-credentials.js";
+import { credentialKey } from "../../security/credential-key.js";
+import { normalizeSecretValue } from "../../security/secret-normalize.js";
+import {
+  getActiveBackendName,
+  setSecureKeyAsync,
+} from "../../security/secure-keys.js";
+import { getLogger } from "../../util/logger.js";
+import {
+  assertMetadataWritable,
+  upsertCredentialMetadata,
+} from "./metadata-store.js";
+import type { CredentialInjectionTemplate } from "./policy-types.js";
+
+const log = getLogger("credential-store");
+
+/** Raised for a value the store refuses before writing anything. */
+export class InvalidCredentialInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidCredentialInputError";
+  }
+}
+
+/** Raised when the secure backend write itself fails. */
+export class CredentialStorageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialStorageError";
+  }
+}
+
+export interface StoreCredentialValueInput {
+  service: string;
+  field: string;
+  /** Plaintext value. Edge whitespace is trimmed before storage. */
+  value: string;
+  /** Human-friendly alias shown in credential listings. */
+  alias?: string;
+  /** What the credential is for, surfaced to the agent. */
+  usageDescription?: string;
+  allowedTools?: string[];
+  allowedDomains?: string[];
+  injectionTemplates?: CredentialInjectionTemplate[];
+  /**
+   * Skip the retroactive transcript scrub. Set it only when the plaintext
+   * provably never transited a conversation (a token minted by an OAuth
+   * refresh, say), since the scrub is a bounded but real sweep of recent
+   * history.
+   */
+  skipTranscriptScrub?: boolean;
+}
+
+export interface StoredCredential {
+  credentialId: string;
+  service: string;
+  field: string;
+}
+
+/**
+ * Store a credential's plaintext and reconcile everything that hangs off it.
+ *
+ * The order is load-bearing:
+ * 1. Validate the value (and the ACP format guard) so a rejected write leaves
+ *    no side effects.
+ * 2. Fail early when credential metadata is not writable.
+ * 3. Write the plaintext to the secure backend.
+ * 4. Scrub the value from recent transcripts. This runs BEFORE the metadata
+ *    upsert and the connection sync, because those can throw and a
+ *    stored-but-unscrubbed secret must not depend on them succeeding. The
+ *    credential IS stored at this point, so the scrub is best-effort hygiene
+ *    and stays invisible to the caller.
+ * 5. Upsert metadata and reconcile the manual-token connection row.
+ *
+ * @throws {InvalidCredentialInputError} when the value is empty or malformed
+ *   for its service.
+ * @throws {CredentialStorageError} when the secure backend rejects the write.
+ */
+export async function storeCredentialValue(
+  input: StoreCredentialValueInput,
+): Promise<StoredCredential> {
+  const { service, field } = input;
+
+  const value = normalizeSecretValue(input.value);
+  if (value.length === 0) {
+    throw new InvalidCredentialInputError("value is required");
+  }
+
+  // Reject an Anthropic API key pasted into the ACP OAuth-token field (a 401
+  // footgun) before it reaches storage.
+  if (service === ACP_SERVICE) {
+    assertAcpCredentialFormat(field, value);
+  }
+
+  assertMetadataWritable();
+
+  const stored = await setSecureKeyAsync(credentialKey(service, field), value);
+  if (!stored) {
+    throw new CredentialStorageError(
+      `Failed to store credential in secure storage (backend: ${getActiveBackendName()})`,
+    );
+  }
+
+  // The stored plaintext may already sit in recent transcripts: the user
+  // message that pasted it, the persisted tool_use input, the tool result
+  // echoing the command. This is the scrub seam, not setSecureKeyAsync, which
+  // also fires on OAuth refresh rotations and MCP header writes whose values
+  // never transited a transcript.
+  if (!input.skipTranscriptScrub) {
+    const { isNonSecretPlatformField, scrubStoredCredentialFromTranscripts } =
+      await import("../../daemon/credential-transcript-scrub.js");
+    if (!isNonSecretPlatformField(service, field)) {
+      try {
+        const scrubbed = await scrubStoredCredentialFromTranscripts(value);
+        log.info(
+          { service, field, ...scrubbed },
+          "Credential stored; scrubbed value from recent transcripts",
+        );
+      } catch (err) {
+        log.warn(
+          { err, service, field },
+          "Credential stored, but transcript scrub failed",
+        );
+      }
+    }
+  }
+
+  const metadata = upsertCredentialMetadata(service, field, {
+    alias: input.alias,
+    usageDescription: input.usageDescription,
+    allowedTools: input.allowedTools,
+    allowedDomains: input.allowedDomains,
+    injectionTemplates: input.injectionTemplates,
+  });
+  const { syncManualTokenConnection } =
+    await import("../../oauth/manual-token-connection.js");
+  await syncManualTokenConnection(service);
+
+  return { credentialId: metadata.credentialId, service, field };
+}

package/src/tools/document/document-tool.ts

@@ -426,13 +426,22 @@ export function executeDocumentUpdate(
     };
   }
 
+  // The store drops append content that merely restates the document's tail,
+  // so the client renders what actually landed rather than the submission.
+  const applied = result.appliedMarkdown;
+  const message = result.duplicateLeadingContentSkipped
+    ? applied.length === 0
+      ? "Nothing appended: the content is already at the end of the document"
+      : "Document content updated (leading content already at the end of the document was skipped)"
+    : "Document content updated";
+
   // Send document_editor_update message to update the built-in RTE
   if (context.sendToClient) {
     context.sendToClient({
       type: "document_editor_update",
       conversationId: context.conversationId,
       surfaceId,
-      markdown: content,
+      markdown: applied,
       mode,
     });
 
@@ -441,7 +450,7 @@ export function executeDocumentUpdate(
         success: true,
         surface_id: surfaceId,
         mode,
-        message: "Document content updated",
+        message,
       }),
       isError: false,
     };
@@ -458,7 +467,7 @@ export function executeDocumentUpdate(
       success: true,
       surface_id: surfaceId,
       mode,
-      message: "Document content updated (no client connected to render it)",
+      message: `${message} (no client connected to render it)`,
     }),
     isError: false,
   };

package/src/tools/executor.ts

@@ -1,9 +1,21 @@
 import { readFile } from "node:fs/promises";
 
+import type {
+  RiskAllowlistOption,
+  RiskDirectoryScopeOption,
+  RiskPatternScopeOption,
+} from "@vellumai/gateway-client";
+
 import { getConfig } from "../config/loader.js";
+import {
+  classifyRisk,
+  type RiskClassificationWithMeta,
+} from "../permissions/checker.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
-import { RiskLevel } from "../permissions/types.js";
-import { runInPluginContext } from "../plugins/plugin-execution-context.js";
+import {
+  runInPluginContext,
+  runOutsidePluginContext,
+} from "../plugins/plugin-execution-context.js";
 import { TokenExpiredError } from "../security/token-manager.js";
 import {
   recordToolError,
@@ -30,6 +42,7 @@ import { MAX_FILE_SIZE_BYTES } from "./shared/filesystem/size-guard.js";
 import { ToolApprovalHandler } from "./tool-approval-handler.js";
 import { resolveToolInvocationAlias } from "./tool-name-aliases.js";
 import { recordToolCompletion } from "./tool-profiler.js";
+import { RISK_LEVEL_UNCLASSIFIED } from "./tool-types.js";
 import { type ToolContext, type ToolExecutionResult } from "./types.js";
 
 export class ToolExecutor {
@@ -60,18 +73,34 @@ export class ToolExecutor {
   ): Promise<ToolExecutionResult> {
     const startTime = Date.now();
     let decision = "allow";
-    let riskLevel: string = RiskLevel.Low;
+    // The invocation's one classification, taken before the gates so every
+    // audit row this call can produce (gate denial, gate error, grant-consumed
+    // execution, permission decision) records the risk of what the model asked
+    // for, then handed down to `checkPermission`. A classification that does
+    // not complete (aborted, gateway unreachable) is recorded as such rather
+    // than as a level; the permission check still requires one and fails
+    // closed on its own.
+    let classification: RiskClassificationWithMeta | undefined;
+    try {
+      classification = await classifyRisk(
+        name,
+        input,
+        context.workingDir,
+        undefined,
+        undefined,
+        context.signal,
+      );
+    } catch {
+      // Stays undefined; the audit row records RISK_LEVEL_UNCLASSIFIED.
+    }
+    let riskLevel: string = classification?.level ?? RISK_LEVEL_UNCLASSIFIED;
     let permRiskMeta:
       | {
           riskLevel: string;
           riskReason: string;
-          riskScopeOptions: Array<{ pattern: string; label: string }>;
-          riskAllowlistOptions?: Array<{
-            label: string;
-            description: string;
-            pattern: string;
-          }>;
-          riskDirectoryScopeOptions?: Array<{ scope: string; label: string }>;
+          riskScopeOptions: RiskPatternScopeOption[];
+          riskAllowlistOptions?: RiskAllowlistOption[];
+          riskDirectoryScopeOptions?: RiskDirectoryScopeOption[];
           isContainerized?: boolean;
         }
       | undefined;
@@ -106,6 +135,11 @@ export class ToolExecutor {
     // consumed; substitute the parsed value (with `.catch()` recoveries
     // applied) so validation and execution see the same input.
     if (gateResult.parsedInput) {
+      // The permission decision is about the input that runs, so a parse that
+      // reshaped it (a `.catch()` recovery) gets its own classification.
+      if (!Bun.deepEquals(input, gateResult.parsedInput)) {
+        classification = undefined;
+      }
       input = gateResult.parsedInput;
     }
 
@@ -189,6 +223,7 @@ export class ToolExecutor {
           context,
           startTime,
           computePreviewDiff,
+          classification,
         );
 
         riskLevel = permResult.riskLevel;
@@ -235,15 +270,18 @@ export class ToolExecutor {
       const execContext = context;
 
       // Mark the owning plugin as in context (via AsyncLocalStorage) so host
-      // APIs the tool reaches — e.g. resolveCredential — can scope to it. The
+      // APIs the tool reaches, e.g. resolveCredential, can scope to it. The
       // context must be established around the `execute()` call itself so the
-      // returned promise carries the binding across its awaits. Non-plugin
-      // tools (default/skill/mcp/workspace) establish no context.
+      // returned promise carries the binding across its awaits. A non-plugin
+      // tool (default/skill/mcp/workspace) runs with the context explicitly
+      // cleared rather than merely unset: the turn may have been started by a
+      // plugin (a route handler calling `runConversationTurn`), and this tool
+      // is host code that must not inherit that plugin's identity.
       const owner = getToolOwner(name);
       const execPromise =
         owner?.kind === "plugin"
           ? runInPluginContext(owner.id, () => tool.execute(input, execContext))
-          : tool.execute(input, execContext);
+          : runOutsidePluginContext(() => tool.execute(input, execContext));
 
       let execResult: ToolExecutionResult = await executeWithTimeout(
         execPromise,
@@ -295,7 +333,7 @@ export class ToolExecutor {
         safeResult.isError,
       );
 
-      // Merge risk metadata from the classifier assessment cache onto the
+      // Merge the classification's risk metadata onto the
       // tool result so downstream consumers (AgentEvent → handleToolResult →
       // ToolResult SSE message) can forward it to the client.
       if (permRiskMeta) {

package/src/tools/filesystem/read.ts

@@ -12,6 +12,7 @@ import {
   IMAGE_EXTENSIONS,
   readImageFile,
 } from "../shared/filesystem/image-read.js";
+import { legacyReadArgsError } from "../shared/filesystem/legacy-read-args.js";
 import { sandboxReadPolicy } from "../shared/filesystem/path-policy.js";
 import {
   invalidToolInputResult,
@@ -25,8 +26,8 @@ import type {
 
 /**
  * Model-input schema, the single source for both runtime validation (via
- * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below. `offset` and
- * `limit` catch to `undefined` because the tool has always ignored non-numeric
+ * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below. `start_index`
+ * and `max_chars` catch to `undefined` because the tool ignores non-numeric
  * values rather than failing the read.
  */
 export const fileReadInputSchema = z.looseObject({
@@ -36,14 +37,16 @@ export const fileReadInputSchema = z.looseObject({
     .describe(
       "The path to the file to read (absolute or relative to working directory)",
     ),
-  offset: z
+  start_index: z
     .number()
-    .describe("Line number to start reading from (1-indexed)")
+    .describe("Character to start reading from (0-indexed). Text files only.")
     .optional()
     .catch(undefined),
-  limit: z
+  max_chars: z
     .number()
-    .describe("Maximum number of lines to read (defaults to 2000)")
+    .describe(
+      "Maximum number of characters to read. Defaults to 20000, which is also the ceiling. Text files only.",
+    )
     .optional()
     .catch(undefined),
   activity: z
@@ -58,7 +61,7 @@ export const fileReadInputSchema = z.looseObject({
 export const fileReadTool = {
   name: "file_read",
   description:
-    "Read the contents of a file on your own machine. Text reads return the first 2000 lines unless you pass `limit`; when a read stops short the result says so, and `offset` pages on from there. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. For audio files (MP3, WAV, OGG, FLAC, AAC, M4A), returns the audio for listening. Use host_file_read for files on your guardian's device instead.",
+    "Read the contents of a file on your own machine. Text reads return the first 20000 characters unless you pass `max_chars`; when a read stops short the result says so, and `start_index` pages on from there. To find where something is in a large file, code_search is cheaper than paging through it. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. For audio files (MP3, WAV, OGG, FLAC, AAC, M4A), returns the audio for listening. Use host_file_read for files on your guardian's device instead.",
   category: "filesystem",
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Low,
@@ -75,9 +78,14 @@ export const fileReadTool = {
     if (!parsed.success) {
       return invalidToolInputResult("file_read", parsed.error);
     }
-    const { path: rawPath, offset, limit } = parsed.data;
+    const {
+      path: rawPath,
+      start_index: startIndex,
+      max_chars: maxChars,
+    } = parsed.data;
 
-    // For image files, delegate to the shared image reader.
+    // For image files, delegate to the shared image reader. Media reads carry
+    // no window, so the legacy-argument guard below does not apply to them.
     const ext = extname(rawPath).toLowerCase();
     if (IMAGE_EXTENSIONS.has(ext)) {
       const pathCheck = sandboxReadPolicy(rawPath, context.workingDir);
@@ -102,11 +110,20 @@ export const fileReadTool = {
       return readAudioFile(pathCheck.resolved);
     }
 
+    const legacyArgs = legacyReadArgsError("file_read", input);
+    if (legacyArgs !== undefined) {
+      return { content: legacyArgs, isError: true };
+    }
+
     const ops = new FileSystemOps((path, opts) =>
       sandboxReadPolicy(path, context.workingDir, opts),
     );
 
-    const result = await ops.readFileSafe({ path: rawPath, offset, limit });
+    const result = await ops.readFileSafe({
+      path: rawPath,
+      startIndex,
+      maxChars,
+    });
 
     if (!result.ok) {
       const { error } = result;