ADR-096: Token Limit Pivot Management System

Status

Accepted

Context

Claude Code sessions have a finite context window (~200K tokens). As sessions progress, context fills and eventually requires management. Without proactive detection and orchestration:

1. Context overflow - Session terminates unexpectedly
2. Degraded performance - "Lost in the middle" phenomenon
3. Lost work - Unsaved context disappears
4. Manual intervention - User must remember to export

We need an automated system to detect approaching limits and orchestrate optimal pivot strategies.

Decision

Implement a Token Limit Pivot Management System with four components:

1. Detection Layer (Hook)

hooks/token-limit-pivot-detector.py - PreToolUse hook that:

• Monitors context usage via tool call tracking
• Reads actual context % from codi-watcher state when available
• Triggers warnings at configurable thresholds
• Integrates with context-degradation skill for pattern detection

2. Orchestration Layer (Agent)

agents/token-limit-pivot-orchestrator.md - Agent that:

• Analyzes current context state
• Selects optimal pivot strategy
• Executes pivot with minimal disruption
• Ensures continuity via checkpoint creation

3. Command Interface

commands/token-status.md - User command that:

• Shows current context usage
• Displays degradation patterns detected
• Recommends actions
• Allows manual pivot trigger

4. Configuration

config/token-pivot-config.json - Settings for:

• Threshold percentages
• Strategy preferences
• Auto-pivot behavior
• Integration toggles

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    TOKEN LIMIT PIVOT SYSTEM                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  DETECTION              ANALYSIS              ORCHESTRATION      │
│  ─────────              ────────              ─────────────      │
│                                                                  │
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐   │
│  │ token-limit- │      │  context-    │      │ token-limit- │   │
│  │ pivot-       │─────▶│  degradation │─────▶│ pivot-       │   │
│  │ detector     │      │  skill       │      │ orchestrator │   │
│  │ (PreToolUse) │      │              │      │ (Agent)      │   │
│  └──────────────┘      └──────────────┘      └──────────────┘   │
│         │                     │                     │            │
│         ▼                     ▼                     ▼            │
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐   │
│  │ Thresholds:  │      │ Patterns:    │      │ Strategies:  │   │
│  │ • 50% Warn   │      │ • Lost-mid   │      │ • Chunk      │   │
│  │ • 70% Alert  │      │ • Distract   │      │ • Compress   │   │
│  │ • 85% Crit   │      │ • Confusion  │      │ • Export     │   │
│  │ • 95% Emerg  │      │ • Clash      │      │ • Spawn      │   │
│  └──────────────┘      └──────────────┘      └──────────────┘   │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│  DATA SOURCES                                                    │
│  ────────────                                                    │
│  • codi-watcher state file (actual context %)                   │
│  • Tool call counter (estimated usage)                          │
│  • Session message history                                       │
│  • Previous pivot decisions                                      │
└─────────────────────────────────────────────────────────────────┘

Threshold Definitions

Level	Context %	Behavior	User Impact
Normal	0-50%	Silent monitoring	None
Warning	50-70%	Log to state file	None
Alert	70-85%	Show notification	Sees ℹ️ message
Critical	85-95%	Recommend export	Sees ⚠️ warning
Emergency	95%+	Auto-trigger pivot	Auto /export

Pivot Strategy Decision Matrix

Context %	Degradation Pattern	Task Complexity	Strategy
50-70%	None	Any	Monitor only
50-70%	Lost-in-middle	Complex	Suggest chunking
70-85%	None	Simple	Continue
70-85%	Distraction	Any	Compress context
70-85%	Any	Research	Chunk to sub-agents
85-95%	None	Any	Recommend /export
85-95%	Any	Any	Auto-export + checkpoint
95%+	Any	Any	Emergency spawn

Pivot Strategies

1. Chunk Strategy

• Decompose remaining work into sub-agent tasks
• Each sub-agent gets fresh context
• Results aggregated by orchestrator
• Uses: chunking-strategies skill

2. Compress Strategy

• Summarize completed work
• Remove redundant context
• Keep essential state
• Uses: context-compression skill

3. Export Strategy

• Run /export to save session
• Run /cx to extract context
• Create checkpoint file
• Uses: Built-in commands

4. Spawn Strategy

• Create continuation prompt
• Save to clipboard/file
• Guide user to new session
• Uses: session-handoff workflow

Integration Points

Component	Integration	Purpose
codi-watcher	State file	Actual context %
context-degradation	Skill	Pattern detection
context-compression	Skill	Token reduction
chunking-strategies	Skill	Work decomposition
/export	Command	Session preservation
/cx	Command	Context extraction
create-checkpoint.py	Script	Checkpoint files

State File Format

~/PROJECTS/.coditect-data/context-storage/token-limit-state.json:

{
  "session_id": "abc123",
  "session_start": "2026-01-22T10:00:00Z",
  "tool_calls": 150,
  "estimated_tokens": 75000,
  "context_percent": 0.42,
  "context_source": "codi-watcher",
  "thresholds_triggered": ["warning"],
  "degradation_patterns": [],
  "last_pivot": null,
  "warnings_shown": 1,
  "auto_export_enabled": true
}

User Commands

# Check current status
/token-status

# Manual pivot with specific strategy
/token-status --pivot chunk
/token-status --pivot export

# Reset warnings for session
/token-status --reset

# Configure thresholds
/token-status --set-critical 80

Consequences

Positive

• Prevents data loss - Auto-export before overflow
• Maintains quality - Detects degradation early
• Reduces friction - Automated pivoting
• Transparent - User sees status when needed

Negative

• Hook overhead - Small latency per tool call
• False positives - May warn when not needed
• Complexity - Multiple components to maintain

Neutral

• Learning curve - Users need to understand pivot strategies
• Configuration - Thresholds may need tuning per user

Implementation Checklist

• ADR-096 specification (this document)
• hooks/token-limit-pivot-detector.py
• agents/token-limit-pivot-orchestrator.md
• commands/token-status.md
• config/token-pivot-config.json
• Integration tests
• Documentation in CLAUDE.md

References

• ADR-040: Token Accounting
• ADR-075: Token Usage Tracking System
• context-degradation skill
• chunking-strategies skill

---

Author: CODITECT Team Created: 2026-01-22 Track: H (Infrastructure) Task: H.8