claude-code

src/tools/FileReadTool/imageProcessor.ts

@@ -0,0 +1,95 @@
+import type { Buffer } from 'buffer'
+import { isInBundledMode } from '../../utils/bundledMode.js'
+
+export type SharpInstance = {
+  metadata(): Promise<{ width: number; height: number; format: string }>
+  resize(
+    width: number,
+    height: number,
+    options?: { fit?: string; withoutEnlargement?: boolean },
+  ): SharpInstance
+  jpeg(options?: { quality?: number }): SharpInstance
+  png(options?: {
+    compressionLevel?: number
+    palette?: boolean
+    colors?: number
+  }): SharpInstance
+  webp(options?: { quality?: number }): SharpInstance
+  toBuffer(): Promise<Buffer>
+}
+
+export type SharpFunction = (input: Buffer) => SharpInstance
+
+type SharpCreatorOptions = {
+  create: {
+    width: number
+    height: number
+    channels: 3 | 4
+    background: { r: number; g: number; b: number }
+  }
+}
+
+type SharpCreator = (options: SharpCreatorOptions) => SharpInstance
+
+let imageProcessorModule: { default: SharpFunction } | null = null
+let imageCreatorModule: { default: SharpCreator } | null = null
+
+export async function getImageProcessor(): Promise<SharpFunction> {
+  if (imageProcessorModule) {
+    return imageProcessorModule.default
+  }
+
+  if (isInBundledMode()) {
+    // Try to load the native image processor first
+    try {
+      // Use the native image processor module
+      const imageProcessor = await import('image-processor-napi')
+      const sharp = imageProcessor.sharp || imageProcessor.default
+      imageProcessorModule = { default: sharp }
+      return sharp
+    } catch {
+      // Fall back to sharp if native module is not available
+      // biome-ignore lint/suspicious/noConsole: intentional warning
+      console.warn(
+        'Native image processor not available, falling back to sharp',
+      )
+    }
+  }
+
+  // Use sharp for non-bundled builds or as fallback.
+  // Single structural cast: our SharpFunction is a subset of sharp's actual type surface.
+  const imported = (await import(
+    'sharp'
+  )) as unknown as MaybeDefault<SharpFunction>
+  const sharp = unwrapDefault(imported)
+  imageProcessorModule = { default: sharp }
+  return sharp
+}
+
+/**
+ * Get image creator for generating new images from scratch.
+ * Note: image-processor-napi doesn't support image creation,
+ * so this always uses sharp directly.
+ */
+export async function getImageCreator(): Promise<SharpCreator> {
+  if (imageCreatorModule) {
+    return imageCreatorModule.default
+  }
+
+  const imported = (await import(
+    'sharp'
+  )) as unknown as MaybeDefault<SharpCreator>
+  const sharp = unwrapDefault(imported)
+  imageCreatorModule = { default: sharp }
+  return sharp
+}
+
+// Dynamic import shape varies by module interop mode — ESM yields { default: fn }, CJS yields fn directly.
+type MaybeDefault<T> = T | { default: T }
+
+function unwrapDefault<T extends (...args: never[]) => unknown>(
+  mod: MaybeDefault<T>,
+): T {
+  return typeof mod === 'function' ? mod : mod.default
+}
+

src/tools/FileReadTool/limits.ts

@@ -0,0 +1,93 @@
+/**
+ * Read tool output limits.  Two caps apply to text reads:
+ *
+ *   | limit         | default | checks                    | cost          | on overflow     |
+ *   |---------------|---------|---------------------------|---------------|-----------------|
+ *   | maxSizeBytes  | 256 KB  | TOTAL FILE SIZE (not out) | 1 stat        | throws pre-read |
+ *   | maxTokens     | 25000   | actual output tokens      | API roundtrip | throws post-read|
+ *
+ * Known mismatch: maxSizeBytes gates on total file size, not the slice.
+ * Tested truncating instead of throwing for explicit-limit reads that
+ * exceed the byte cap (#21841, Mar 2026).  Reverted: tool error rate
+ * dropped but mean tokens rose — the throw path yields a ~100-byte error
+ * tool-result while truncation yields ~25K tokens of content at the cap.
+ */
+import memoize from 'lodash-es/memoize.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from 'src/services/analytics/growthbook.js'
+import { MAX_OUTPUT_SIZE } from 'src/utils/file.js'
+export const DEFAULT_MAX_OUTPUT_TOKENS = 25000
+
+/**
+ * Env var override for max output tokens. Returns undefined when unset/invalid
+ * so the caller can fall through to the next precedence tier.
+ */
+function getEnvMaxTokens(): number | undefined {
+  const override = process.env.CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS
+  if (override) {
+    const parsed = parseInt(override, 10)
+    if (!isNaN(parsed) && parsed > 0) {
+      return parsed
+    }
+  }
+  return undefined
+}
+
+export type FileReadingLimits = {
+  maxTokens: number
+  maxSizeBytes: number
+  includeMaxSizeInPrompt?: boolean
+  targetedRangeNudge?: boolean
+}
+
+/**
+ * Default limits for Read tool when the ToolUseContext doesn't supply an
+ * override. Memoized so the GrowthBook value is fixed at first call — avoids
+ * the cap changing mid-session as the flag refreshes in the background.
+ *
+ * Precedence for maxTokens: env var > GrowthBook > DEFAULT_MAX_OUTPUT_TOKENS.
+ * (Env var is a user-set override, should beat experiment infrastructure.)
+ *
+ * Defensive: each field is individually validated; invalid values fall
+ * through to the hardcoded defaults (no route to cap=0).
+ */
+export const getDefaultFileReadingLimits = memoize((): FileReadingLimits => {
+  const override =
+    getFeatureValue_CACHED_MAY_BE_STALE<Partial<FileReadingLimits> | null>(
+      'tengu_amber_wren',
+      {},
+    )
+
+  const maxSizeBytes =
+    typeof override?.maxSizeBytes === 'number' &&
+    Number.isFinite(override.maxSizeBytes) &&
+    override.maxSizeBytes > 0
+      ? override.maxSizeBytes
+      : MAX_OUTPUT_SIZE
+
+  const envMaxTokens = getEnvMaxTokens()
+  const maxTokens =
+    envMaxTokens ??
+    (typeof override?.maxTokens === 'number' &&
+    Number.isFinite(override.maxTokens) &&
+    override.maxTokens > 0
+      ? override.maxTokens
+      : DEFAULT_MAX_OUTPUT_TOKENS)
+
+  const includeMaxSizeInPrompt =
+    typeof override?.includeMaxSizeInPrompt === 'boolean'
+      ? override.includeMaxSizeInPrompt
+      : undefined
+
+  const targetedRangeNudge =
+    typeof override?.targetedRangeNudge === 'boolean'
+      ? override.targetedRangeNudge
+      : undefined
+
+  return {
+    maxSizeBytes,
+    maxTokens,
+    includeMaxSizeInPrompt,
+    targetedRangeNudge,
+  }
+})
+

src/tools/FileReadTool/prompt.ts

@@ -0,0 +1,50 @@
+import { isPDFSupported } from '../../utils/pdfUtils.js'
+import { BASH_TOOL_NAME } from '../BashTool/toolName.js'
+
+// Use a string constant for tool names to avoid circular dependencies
+export const FILE_READ_TOOL_NAME = 'Read'
+
+export const FILE_UNCHANGED_STUB =
+  'File unchanged since last read. The content from the earlier Read tool_result in this conversation is still current — refer to that instead of re-reading.'
+
+export const MAX_LINES_TO_READ = 2000
+
+export const DESCRIPTION = 'Read a file from the local filesystem.'
+
+export const LINE_FORMAT_INSTRUCTION =
+  '- Results are returned using cat -n format, with line numbers starting at 1'
+
+export const OFFSET_INSTRUCTION_DEFAULT =
+  "- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters"
+
+export const OFFSET_INSTRUCTION_TARGETED =
+  '- When you already know which part of the file you need, only read that part. This can be important for larger files.'
+
+/**
+ * Renders the Read tool prompt template.  The caller (FileReadTool) supplies
+ * the runtime-computed parts.
+ */
+export function renderPromptTemplate(
+  lineFormat: string,
+  maxSizeInstruction: string,
+  offsetInstruction: string,
+): string {
+  return `Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to ${MAX_LINES_TO_READ} lines starting from the beginning of the file${maxSizeInstruction}
+${offsetInstruction}
+${lineFormat}
+- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.${
+    isPDFSupported()
+      ? '\n- This tool can read PDF files (.pdf). For large PDFs (more than 10 pages), you MUST provide the pages parameter to read specific page ranges (e.g., pages: "1-5"). Reading a large PDF without the pages parameter will fail. Maximum 20 pages per request.'
+      : ''
+  }
+- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.
+- This tool can only read files, not directories. To read a directory, use an ls command via the ${BASH_TOOL_NAME} tool.
+- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.`
+}
+