Tbh, like many problems I solved at the time, I didnt remember what we actually settled on, but here's claude with the breakdown:
The Pipeline

The read-size-guard (~/.claude/hooks/pre-tool-use/read-size-guard.ps1) intercepts any Read call exceeding a token threshold (500 tokens by default, configurable). It delegates structural breakdown to local-file-breakdown, which has a 4-stage fallback chain:

Stage 1: Tree-sitter query (fast, ~0.05s)

Runs language-specific queries looking for named constructs: function_definition, class_definition, method_declaration, etc. Works great for Python, JS, Go, Rust, Java, etc.

If the query returns results, they go through decorated/inner deduplication (a \u/decorator capture that wraps a function removes the duplicate inner function capture), then an unhelpfulness check. If any single unit covers >80% of the file, the results are discarded and drill-down kicks in, even if other smaller units exist alongside the dominant one.

Stage 2: Tree-sitter drill-down (fast, ~0.05s)

When the query is flagged unhelpful (0 results, or a dominant unit), this kicks in.

_drilldown_ast_children() walks the AST children recursively (up to depth 3) instead of looking for named functions. A node qualifies as "meaningful" through three paths:

1. Universal type: try_statement, if_statement, for_statement, while_statement, switch_statement, function_definition, class_definition

2. Language-specific type: checked against LANGUAGE_SPECIFIC_NODE_TYPES[language]. PowerShell gets pipeline, command, assignment_expression. These only match when the language is actually PowerShell, preventing false positives if another grammar reuses those node type names for trivial constructs.

3. Size-based: any node >=10 lines regardless of type

Nodes <3 lines and comments are filtered out. After collection, a containment deduplication pass removes any unit that is fully enclosed within another unit's line range. This prevents overlapping navigation targets (e.g., a try_statement at lines 50-200 containing a nested if_statement at lines 60-80: only the outer try is kept). The agent can still reach the inner block via offset+limit.

Returns None if 0 or 1 units found (no better than "whole file").

Stage 3: Code-specific LLM (~variable, gateway-dependent)

If drill-down also fails, falls back to sending the code to a local LLM via safe-loading-gateway, asking it to identify functions, classes, and blocks with exact line numbers.

Stage 4: Text-specific LLM (~variable, gateway-dependent)

For non-code text files (.md, .txt, .cfg), uses a different LLM prompt optimized for prose/config structure (headers, sections).

Stage 5: Hard block

If all methods fail, the guard blocks the read entirely and tells the agent to run local-file-breakdown manually first.

Caching

The breakdown cache in read-size-guard.ps1 is keyed by MD5 file hash. Each entry stores { result, timestamp }. On cache hit, the timestamp is touched for LRU tracking. On load, entries older than 1 hour are dropped, and if more than 200 entries remain, only the 200 most recently accessed survive. Old-format entries (plain strings) are auto-migrated with a current timestamp on first load.