Inject context usage percentage into system-reminder for model self-awareness

Summary

The model has no awareness of how much context it has consumed. It can't proactively save information to memory, wrap up tasks, or warn the user. The model only discovers context pressure when compaction happens — and by then information is already lost.

The statusline already has context_window.used_percentage. Proposing that this same data be injected into <system-reminder> tags at configurable thresholds so the model can act on it.

Related Issues

• #34184 — Expose context window usage percentage to the model
• #34879 — Expose context window usage metrics to Claude for self-analysis
• #36678 — Expose session_id and context_window usage to the AI model
• #34685 — Claude Opus 4.6 1M context: self-reported degradation starting at 40%
• #32659 — Context amnesia in long sessions — constraints silently dropped
• #38523 — Add token_count to PreCompact hook input (companion proposal)
• #38524 — Add ContextThreshold hook event (companion proposal)

Proposed Tiered Thresholds

At 60% (informational):

<system-reminder>
Context usage: 62% (620k/1000k tokens).
</system-reminder>

At 75% (warning):

<system-reminder>
Context usage: 80% (800k/1000k tokens). Consider flushing important information to memory to preserve it across context compaction.
</system-reminder>

At 90% (critical):

<system-reminder>
Context usage: 92% (920k/1000k tokens). CRITICAL: Context compaction is imminent. Flush all important information to memory NOW using the memory system. Prioritize: decisions made, current task state, key findings.
</system-reminder>

Implementation

The <system-reminder> injection infrastructure already exists — it's used for task reminders, date changes, and skill listings. The regex rS1 = /^<system-reminder>\n?([\s\S]*?)\n?<\/system-reminder>$/ is already parsed by the system.

Add one new reminder source in the message assembly pipeline:

function getContextUsageReminder(tokenCount, contextWindowSize) {
  const usagePercent = Math.round((tokenCount / contextWindowSize) * 100);
  if (usagePercent < 60) return null;
  
  const usageK = Math.round(tokenCount / 1000);
  const totalK = Math.round(contextWindowSize / 1000);

  if (usagePercent >= 90)
    return `Context usage: ${usagePercent}% (${usageK}k/${totalK}k tokens). CRITICAL: ...`;
  if (usagePercent >= 75)
    return `Context usage: ${usagePercent}% (${usageK}k/${totalK}k tokens). Consider flushing ...`;
  return `Context usage: ${usagePercent}% (${usageK}k/${totalK}k tokens).`;
}

Proposed Configuration

{
  "contextUsageReminders": {
    "enabled": true,
    "thresholds": {
      "info": 60,
      "warning": 75,
      "critical": 90
    }
  }
}

Complexity

Low-Medium. The system-reminder injection infrastructure already exists. This adds one new source of reminders. Main considerations:

• Token overhead: ~30-60 tokens per injection (minimal)
• Frequency: Should only inject when usage has changed by >5% since last injection to avoid spamming
• Model compliance: The model must be instructed (via CLAUDE.md or system prompt) to act on these reminders — but the auto-memory system already does this

Why This Matters

Unlike hooks (which run external scripts), system-reminders are visible to the model itself. This is the only mechanism that gives the model agency to manage its own context pressure. Without it:

1. Long sessions silently lose information during compaction
2. The model can't prioritize what to save because it doesn't know compaction is coming
3. Users discover data loss after the fact, with no recovery possible
4. Autonomous agents (teams, subagents) are especially vulnerable — they can't ask the user for help

The combination of all three proposals (#38523 token count in hooks, #38524 ContextThreshold event, and this one) would give both external tooling and the model itself full awareness of context pressure.

Current Workaround

We've built an approximation using PostToolUse hooks that read a sidecar file written by the statusline script. This works but is fragile (depends on statusline timing, file I/O race conditions) and the output is just appended text, not a proper system-reminder that the model is trained to attend to.

Community Demand

8+ existing issues requesting context awareness for the model, with particular urgency from users of 1M-context Opus sessions where context management is critical. The existing issues span memory management, task planning, and autonomous agent reliability.

---
Labels suggestion: enhancement, area:hooks