[FEATURE] Unscoped Read of an over-cap file: return stats + outline instead of a billed first-page slice (the pre-flight half of 2.1.145's PARTIAL view)

Preflight Checklist

• [x] I have searched existing requests — closest is #22699 (closed NOT_PLANNED pre-2.1.145; broader scope incl. @ attachments); see "Prior art" for why this is a distinct, narrower ask
• [x] This is a single feature request

Problem Statement

Since 2.1.145, a whole-file Read over the ~25k-token cap returns a truncated
first page with a "PARTIAL view" notice and an exact continuation recipe. That
is the right post-hoc behavior — but it runs in the wrong order: the full cap
is billed into the context before the model learns the file didn't fit, and the
file's size was knowable for free (one stat + line count) before reading a byte.

Measured instance (today, Opus/Fable-class session): an unscoped Read of a
2,548-line project methods document billed the full 25k-token cap and delivered
964 lines (38% of the file). The section actually needed was ~10 lines, findable
from the document's own heading index. The 25k stays in the session prefix for
every subsequent turn. The PARTIAL notice arrived as a receipt, not a choice.

The model cannot make the scoped/unscoped decision well on its own: an unscoped
Read is correct for the overwhelming majority of files (under the cap), so
habit carries it onto the occasional large file, where the cost is 50–100× the
information used.

Proposed Solution

When an unscoped Read (no offset/limit) targets a file whose content
exceeds the cap, return metadata instead of a billed slice:

• size, total line count, estimated tokens (all already computed for the

PARTIAL notice today);

• a cheap structural outline — markdown headings / top-level symbols / first

line, whichever is trivially available (even grep -n '^## '-grade is
enough);

• the same continuation recipe the PARTIAL view already prints

("Call Read with offset=… limit=…, or Grep for a section").

Cost: a few hundred tokens instead of 25,000, and nothing is lost — a model
that genuinely wants the head re-issues with an explicit limit and gets
today's behavior. Explicit offset/limit reads keep returning content pages
unchanged (and per #77489 the scoped path should get the PARTIAL treatment it
currently lacks).

Prior art / relationship to existing issues

• #22699 (closed NOT_PLANNED, 2026-03): proposed pre-flight size-awareness

broadly (Read + @ attachments). Closed before 2.1.145 shipped the PARTIAL
view — i.e. before the post-hoc half of that request was built. This issue
asks only for the remaining pre-flight half, Read tool only.

• 2.1.145 changelog: PARTIAL view for whole-file over-cap reads — the

infrastructure (token estimate, line accounting, recipe text) this proposal
reuses.

• #77489 (open): scoped over-cap reads hard-error without convergence guidance

— sibling gap on the scoped path.

• #26018 (open): Read can exceed the 20MB API limit without pre-checking

payload size — the same missing pre-flight check at a different scale.

Workaround we run today

A local PreToolUse hook denies an unscoped Read of a file over the cap
(>2000 lines or >256KB) with guidance to re-issue scoped; the corrected retry
passes. It works — the deny-with-recipe loop converges in one retry — but it
can only block the call; the harness could answer it with the outline,
which is strictly better.

---
🤖 Drafted with Claude Code — reviewed and submitted by the account owner.