RFC: Pre-Read hook for context efficiency feedback #199

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

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