claude-code - 💡(How to fix) Fix [DOCS] Agent SDK Read tool docs omit size-cap behavior and `parts` output [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-sdk/typescript

Section/Topic

Read tool reference (FileReadInput / FileReadOutput) in the Agent SDK TypeScript and Python references

Current Documentation

The TypeScript reference currently says:

type FileReadInput = { file_path: string; offset?: number; limit?: number; pages?: string; };

Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks. Use pages for PDF page ranges (for example, "1-5").

Later on the same page it also says:

type FileReadOutput = ... | { type: "parts"; file: { filePath: string; originalSize: number; count: number; outputDir: string; }; };

Returns file contents in a format appropriate to the file type. Discriminated on the type field.

The Python reference currently documents only:

{ "file_path": str, "offset": int | None, "limit": int | None, }

Output (Text files): { "content": str, "total_lines": int, "lines_returned": int }

Output (Images): { "image": str, "mime_type": str, "file_size": int }

What's Wrong or Missing?

Changelog v2.1.119 includes: Fixed SDK/bridge read_file not correctly enforcing size cap on growing files.

That indicates SDK/bridge read_file / Read calls have a real size-cap behavior that callers can hit, but the current docs never explain:

A. When the size cap applies

The reference does not say that large reads can be capped, or that files growing during a read can still hit that cap.

B. What type: "parts" means in practice

The TypeScript reference exposes a parts variant with originalSize, count, and outputDir, but it does not explain when this variant is returned or how callers should handle it instead of inline content.

C. Python/TypeScript parity

The Python reference omits the corresponding large-file/PDF/alternate-output behavior entirely, so Python SDK users are more likely to assume Read only returns inline text or image payloads.

Suggested Improvement

Add a short note to the Read tool docs that:

• Read enforces a maximum inline payload size
• files that exceed that cap can return type: "parts" with outputDir, count, and originalSize instead of a single inline payload
• this can also matter for files that grow while they are being read
• offset and limit are the recommended way to page through large text files
• the Python and TypeScript SDK references should document the same Read inputs and output variants

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.119

Changelog entry: Fixed SDK/bridge read_file not correctly enforcing size cap on growing files