From 7ae8b69ec91ed1b2682b9ddba3e01d0ca4c33ad6 Mon Sep 17 00:00:00 2001
From: Levi Neely <141506390+lneely@users.noreply.github.com>
Date: Sun, 17 May 2026 12:51:49 +0200
Subject: [PATCH] tools: per-tool semantic truncation (file_grep 50,
 lsp_references 50, memory_recall 10/50, file_read 500)

---
 tools/file_grep      | 10 ++++++++--
 tools/file_read      | 30 ++++++++++++++++++++++--------
 tools/lsp_references | 11 +++++++++--
 tools/memory_recall  | 15 ++++++++++++++-
 4 files changed, 53 insertions(+), 13 deletions(-)

diff --git a/tools/file_grep b/tools/file_grep
index 05cdfa1..1c7de22 100755
--- a/tools/file_grep
+++ b/tools/file_grep
@@ -65,11 +65,15 @@ if result.returncode > 1:
     sys.exit(1)
 
 lines = result.stdout.splitlines()
+total = len(lines)
 
 if args.offset:
     lines = lines[args.offset:]
-if args.head:
-    lines = lines[:args.head]
+
+max_matches = args.head if args.head else 50
+capped = len(lines) > max_matches
+if capped:
+    lines = lines[:max_matches]
 
 if args.mode == 'content':
     formatted = []
@@ -88,3 +92,5 @@ if args.mode == 'content':
     lines = formatted
 
 print('\n'.join(lines))
+if capped:
+    print(f"\n(showing {max_matches} of {total} matches; use --head=N or --offset=N for more)")
diff --git a/tools/file_read b/tools/file_read
index b1dc64a..d1f74ad 100755
--- a/tools/file_read
+++ b/tools/file_read
@@ -2,22 +2,32 @@
 # ollie:parallel read
 # ollie:tier cold
 # description: Read a file with accurate line numbers. Prefer segments (start/end) over full-file reads.
-# Args: <file_path> [start] [end]
+# Args: <file_path> [start] [end] [--head=<n>]
 
 import sys
 import os
 from itertools import islice
 
-MAX_LINES = 2000
+MAX_LINES = 500       # default window for whole-file reads (no start/end)
+MAX_SEGMENT = 2000    # max window when start/end are given
 MAX_LINE_LEN = 2000
 
-if len(sys.argv) < 2:
-    print("usage: file_read <file_path> [start] [end]")
+# Parse --head=N from args
+head = None
+args = []
+for a in sys.argv[1:]:
+    if a.startswith('--head='):
+        head = int(a.split('=', 1)[1])
+    else:
+        args.append(a)
+
+if not args:
+    print("usage: file_read <file_path> [start] [end] [--head=N]")
     sys.exit(1)
 
-file_path = sys.argv[1]
-start = int(sys.argv[2]) if len(sys.argv) > 2 else 1
-end   = int(sys.argv[3]) if len(sys.argv) > 3 else None
+file_path = args[0]
+start = int(args[1]) if len(args) > 1 else 1
+end   = int(args[2]) if len(args) > 2 else None
 
 if not os.path.isabs(file_path):
     print(f"error: path must be absolute, got: {file_path}")
@@ -37,8 +47,12 @@ with open(file_path, 'rb') as f:
         sys.exit(0)
 
 start = max(1, start)
-if end is None:
+if head:
+    end = start + head - 1
+elif end is None:
     end = start + MAX_LINES - 1
+else:
+    end = min(end, start + MAX_SEGMENT - 1)
 
 with open(file_path, 'r', errors='replace') as f:
     # Skip lines before start
diff --git a/tools/lsp_references b/tools/lsp_references
index d373c1a..f8e869b 100755
--- a/tools/lsp_references
+++ b/tools/lsp_references
@@ -23,7 +23,11 @@ if not result:
     print("(no references found)")
     sys.exit(0)
 
-for loc in result:
+total = len(result)
+cap = 50
+refs = result[:cap] if total > cap else result
+
+for loc in refs:
     uri = loc.get("uri", "")
     path = uri[7:] if uri.startswith("file://") else uri
     pos = loc.get("range", {}).get("start", {})
@@ -31,4 +35,7 @@ for loc in result:
     ch = pos.get("character", 0) + 1
     print(f"{path}:{ln}:{ch}")
 
-print(f"\n({len(result)} references)")
+if total > cap:
+    print(f"\n(showing {cap} of {total} references)")
+else:
+    print(f"\n({total} references)")
diff --git a/tools/memory_recall b/tools/memory_recall
index e951d55..5bdd675 100755
--- a/tools/memory_recall
+++ b/tools/memory_recall
@@ -29,8 +29,21 @@ if [ -z "$matches" ]; then
     exit 0
 fi
 
+max_files=10
+max_lines_per_file=50
+count=0
+
 while IFS= read -r file; do
+    count=$((count + 1))
+    if [ $count -gt $max_files ]; then
+        echo "(showing $max_files of $(echo "$matches" | wc -l) matched files)"
+        break
+    fi
     echo "=== $(basename "$file") ==="
-    cat "$file" || echo "error: could not read $file"
+    head -n $max_lines_per_file "$file" || echo "error: could not read $file"
+    lines=$(wc -l < "$file" 2>/dev/null)
+    if [ "$lines" -gt $max_lines_per_file ] 2>/dev/null; then
+        echo "... ($lines lines total, showing first $max_lines_per_file)"
+    fi
     echo
 done <<< "$matches"