[BUG] Read tool: explicit offset/limit reads that exceed the 25k-token cap hard-error with advice to "use offset and limit parameters" — the 2.1.145 PARTIAL-view truncation only covers whole-file reads

Summary

Since 2.1.145 ("Improved the Read tool to return a truncated first page with a 'PARTIAL view' notice instead of a hard error when a whole-file read exceeds the token limit"), a whole-file Read over the ~25,000-token page cap returns a useful truncated page with an exact continuation recipe. But a Read with explicit offset/limit whose selected range exceeds the cap still takes the old hard-error path, and the error tells the model to do what it just did:

File content (84502 tokens) exceeds maximum allowed tokens (25000). Use offset and limit
parameters to read specific portions of the file, or search for specific content instead of
reading the whole file.

The model did pass offset/limit. The error names the token count but not the file's line count, how many lines fit under the cap, or any concrete smaller range — so the retry loop has no convergence guidance. Contrast with the whole-file path on the same file, which computes exactly that:

[Truncated: PARTIAL view — <path>: showing lines 1-754 of 3000 total (84502 tokens, cap 25000).
Call Read with offset=755 limit=754 for the next page, or Grep to find a specific section. ...]

The 256KB byte-cap error has the same gap (states cap and size, no line count, no computed page):

File content (1.1MB) exceeds maximum allowed size (256KB). Use offset and limit parameters to
read specific portions of the file, or search for specific content instead of reading the whole
file.

Why it matters (measured, approximate)

In a 7-day transcript audit of one monorepo (26,857 subagent tool calls), 126 Reads died on the size caps (82 token-cap, 44 byte-cap), and only roughly 1 in 5 recovered with a paged retry. Treat both figures as approximate: the classification was extracted from transcripts, and the token-cap subset may conflate some pre-2.1.145-style whole-file behavior (e.g. PARTIAL-view truncations misfiled as failures); the raw dataset is no longer available to re-split. The per-call behavior in the repro below is exact and current on 2.1.209.

The failure mode is consistent: agents reason in lines ("it's only 265 lines") while the caps are tokens/bytes; when the guessed limit still overflows, they receive the identical "use offset and limit" error for a call that used offset and limit, and typically fall back to shell (sed -n) or give up on the file. Each bounce is a wasted model roundtrip.

Steps to reproduce (CLI 2.1.209, macOS)

1. Generate a text file of 3,000 lines that totals ~85k tokens under 256KB (e.g. ~75 chars/line, ~234KB).
2. Read(file_path) — no offset/limit → works well: PARTIAL first page with exact next-page recipe (offset=755 limit=754).
3. Read(file_path, offset=1, limit=3000) → hard error quoted above; no truncation, no recipe, advice restates the parameters already in use.
4. For the byte cap: same with a >256KB file and no offset/limit → hard error quoted above. (Paged reads on the >256KB file work fine, so the advice is followable there — it is just uncomputed.)

Expected

One mechanism, uniformly: the harness already knows the file's total line count, the token count of the requested range, and how to compute the largest prefix that fits (it does this in the PARTIAL-view notice, and computes "Read chunk sizes for text" in the MCP large-output truncation prompt since 2.1.105). Either:

• Auto-truncate explicit-range overflows exactly like whole-file reads: return offset..offset+N that fits the cap, with the same PARTIAL notice and next-page recipe; or
• at minimum, put the computed recipe in the error: "lines X–Y of Z requested (84,502 tokens, cap 25,000); lines X–X+753 fit — call Read with offset=X limit=754."

And give the 256KB byte-cap error the same treatment (it can cite total lines and a fitting first page from a stat + line count without reading the whole file into memory).

Related

• #73281 (PARTIAL-view reads reportedly not satisfying the read-before-edit guard) is the adjacent area, for cross-reference only. Data point: it did not reproduce for us on 2.1.209 — after a whole-file PARTIAL-view Read, Edits succeeded both on text inside the displayed page and on text beyond it. If explicit-range truncation is adopted, it should register read-state the same way whole-file PARTIAL views evidently now do.