agent tool: windowed read_file — don’t dump huge files

[btipling]

Summary

read_file should support a byte/line window (start / limit or equivalent) and must not dump a huge file into the model when no window is given.

Today: full file up to 16 MiB, then TOOL_RESULT_MAX_CHARS flatten. Large sources blow the turn; the model re-reads them next turn anyway because we drop tool_run (#549 — different issue).

Goal

• Args: existing path + window (line start/limit or byte range — pick one in plan, name the cap).
• Over a size/line threshold and no window: return {truncated/summarized, line_count or bytes, hint: request a window} — not the body.
• Optional later: language-agnostic outline. Do not ship Orrery’s Go-only func/type/package heuristic.
• Successful windowed read still counts as a full-enough grant for str_replace only if we can define that honestly (or require a full read for edit — lock in plan). Do not silently weaken read-before-edit (plan: agent read-before-edit + external file freshness (parent) #277).

Success: reading ui.zig does not inject 1400 lines unless the model asked for a slice.

Constraints

• Jail / cwd / in-jail abs unchanged.
• finalize / TOOL_RESULT_MAX_CHARS still apply to the window.
• Truncated-without-window must not authorize overwrite (freshness.recordRead(..., truncated: true) already exists).
• Caps: NEW window default + “too big” threshold in create-plan.

Non-goals

• Hashline anchors on every line (later, only if agent tool: stale/failed str_replace returns a small file window #564 + land-rate data say so)
• Combining list_dir into read (our split is fine)
• Agent-session compaction

Related

• read_file in lib/agent/tools.ts
• agent tool: first-class search (capped rg), stop exec-ing grep #562 search (hits → windowed read)
• agent tool: stale/failed str_replace returns a small file window #564 stale str_replace window
• plan: agent read-before-edit + external file freshness (parent) #277 / freshness

Suggested next

create-plan after #562’s result shape so search hits and read windows use the same line addressing.

[btipling]

Window shape is now locked on #688: Grok Build’s existing read_file args (offset 1-based start line, limit line count, defaults 1 / 1000, line-numbered window). No second tool. Edit-gate still requires a non-truncated (full-file) read.

[btipling]

Shipped in #690 (feat(agent): read_file line offset + limit window). (Closed manually — PR referenced #688 instead of this original source issue.)