RFC: Pre-Read hook for context efficiency feedback

[evansenter]

Problem Statement

Claude knows context efficiency best practices but doesn't follow them because there's no feedback loop. Documenting guidance in CLAUDE.md is ineffective - we're telling Claude things it already knows.

Evidence

From /improve-workflow analysis on session-analytics:

• 1,597 occurrences of Read → Read → Read pattern
• Files like Cargo.toml read 7+ times consecutively
• Sessions with 24:1 read:edit ratios
• 192 compactions across 7 days, preventable with better read patterns

Root Cause

Claude has no visibility into:

1. What files are already in context
2. How much context budget remains
3. When it's re-reading something it just read

Proposed Solution

Option A: Pre-Read Hook

A hook that fires before the Read tool executes:

#!/bin/bash
# hooks/pre-read.sh
FILE_PATH="$1"
SESSION_LOG="$CLAUDE_SESSION_LOG"  # if available

# Check if file was read recently (last N events)
if recently_read "$FILE_PATH" "$SESSION_LOG"; then
  echo "⚠️ This file is already in context. Reference by line number instead of re-reading."
fi

Challenges:

• Hook would need access to session state or recent tool history
• May need MCP tool to query "files in current context"

Option B: MCP Health Check Tool

Add to session-analytics:

check_context_health(session_id)
# Returns:
# {
#   "files_in_context": ["foo.rs", "bar.rs"],
#   "files_read_multiple_times": [{"path": "Cargo.toml", "count": 3}],
#   "estimated_context_pct": 65,
#   "warnings": ["Cargo.toml read 3 times - consider referencing by line"]
# }

Claude could call this periodically or when uncertain.

Option C: Post-Read Hook with Warning

Less preventive, but simpler - warn after the fact:

#!/bin/bash
# hooks/post-read.sh
# Inject warning into response if file was already in context

Tradeoffs

Option	Pros	Cons
A (Pre-Read)	Prevents waste before it happens	Complex, needs session state access
B (MCP Tool)	Claude can self-check	Requires Claude to remember to call it
C (Post-Read)	Simple implementation	Reactive, damage already done

Recommendation

Start with Option C (post-read warning) as a quick win, then explore Option B (MCP health check) for more sophisticated self-monitoring.

Related

• RFC: Improve compaction event analysis with session-level aggregation and summaries agent-session-analytics#81 - Post-hoc compaction analysis
• feat: Add limit parameters and efficiency metrics (closes #77, #78, #79) agent-session-analytics#80 - Added files_read_multiple_times metric

[evansenter]

Closing: Not worth the complexity

After discussion, we realized the core problem:

Knowing I read a file doesn't help if I don't have the contents.

Post-compaction, even with a signal like "you read foo.rs before," I still need to re-read it to do useful work. The signal tells me that I read something but not what was in it.

Possible behavioral changes were weak:

• Skip exploratory re-reads → summary already tells me what I learned
• Read smaller chunks → should do this anyway
• Ask user for specific lines → adds friction

The real fix is likely upstream (better compaction, file pinning) rather than hook-based feedback.

Removing the "Context Efficiency" section from CLAUDE.md as well - it's guidance I already know.