ktg-plugin-marketplace/plugins/graceful-handoff/docs/brief-context-window-detection.md

Brief: Modell-bevisst kontekstvindu i graceful-handoff

Dato: 2026-05-01 Status: Forslag — ikke implementert Trigger: Bruker oppdaget at Opus 4.7 har 1M kontekstvindu, ikke 200K. Plugin antar 200K i fallback.

Problem

hooks/scripts/stop-context-monitor.mjs:23 definerer:

const FALLBACK_WINDOW = 200_000;

Logikken (linje 76-77):

const windowSize = payload?.context_window?.context_window_size || FALLBACK_WINDOW;
const pctRaw = estimateUsedPct(transcriptPath, windowSize);

Hvis Stop-hook payload ikke leverer context_window.context_window_size — eller leverer 0/undefined — beregner hooken brukt prosent mot 200K. På en Opus 4.7-sesjon med faktisk 1M-vindu betyr det:

• Estimat treffer 70% når faktisk bruk er ~14% (140K av 1M)
• Auto-handoff fyrer 5-7x for tidlig
• Bruker mister kontinuitet i lange sesjoner

statusline-monitor.mjs har ikke samme problem — den leser used_percentage direkte fra payload og er modell-agnostisk.

Hvorfor 200K-fallback ble valgt

Kommentar (linje 14-16):

Token estimation: char_count / 3.5 → approximate tokens. Compares against context_window_size from payload (200000 fallback). Approximation is known to drift ±10% — 70% threshold is conservative buffer.

Antakelsen ved skriving av v2.0: Claude-modeller har 200K-vindu som standard. Det stemmer ikke lenger.

Modell-landskap (verifisert 2026-05-01)

Modell	Kontekstvindu
Opus 4.7	1M tokens (standard, ingen long-context premium)
Sonnet 4.6	1M tokens (1M tier, beta) eller 200K
Haiku 4.5	200K tokens
Eldre Claude 3.x	200K tokens

Kilder:

• https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7
• https://platform.claude.com/docs/en/build-with-claude/context-windows

Løsningsalternativer

Alt 1 — Bedre fallback-detektering (minimal endring)

Detekter modell fra payload (payload?.model eller lignende felt) og map til kontekstvindu:

const MODEL_WINDOWS = {
  'claude-opus-4-7': 1_000_000,
  'claude-sonnet-4-6': 200_000, // default, kan ha 1M tier
  'claude-haiku-4-5-20251001': 200_000,
};

function resolveWindowSize(payload) {
  const fromPayload = payload?.context_window?.context_window_size;
  if (fromPayload && fromPayload > 0) return fromPayload;
  const model = payload?.model || payload?.session?.model;
  if (model && MODEL_WINDOWS[model]) return MODEL_WINDOWS[model];
  return 1_000_000; // safer default i 2026
}

Pros: Minimal kode, dekker 95% av tilfellene. Cons: Hard-kodet modell-tabell må vedlikeholdes. Sonnet 4.6 1M-tier er ikke alltid aktiv — kan over-estimere.

Alt 2 — Foretrekk used_percentage fra payload (foretrukket)

Hvis Stop-hook payload har context_window.used_percentage (slik statusline-payload har), bruk den direkte og hopp over transcript-estimat helt:

function estimateUsedPct(payload, transcriptPath, windowSize) {
  const direct = payload?.context_window?.used_percentage;
  if (typeof direct === 'number' && !isNaN(direct)) {
    return direct / 100; // already a percent
  }
  // Fall back to transcript-size estimate
  const stat = statSync(transcriptPath);
  const tokens = stat.size / CHARS_PER_TOKEN;
  return tokens / windowSize;
}

Pros: Bruker autoritativ kilde når tilgjengelig. Modell-agnostisk. Cons: Krever verifisering av Stop-hook payload-schema — usikkert om feltet alltid er der.

Alt 3 — Kombinert (anbefalt)

1. Foretrekk used_percentage fra payload (Alt 2)
2. Hvis ikke tilgjengelig, bruk context_window_size fra payload + transcript-estimat
3. Hvis heller ikke det, prøv modell-mapping (Alt 1)
4. Siste fallback: 1M (oppdatert default for 2026)

Behold 70% terskel — den er prosent-basert og fungerer uavhengig av vindusstørrelse.

Sekundært designspørsmål

Er fast 70% terskel optimal for både 200K og 1M?

• 200K × 70% = 140K brukt → 60K headroom
• 1M × 70% = 700K brukt → 300K headroom

Det er rimelig argumenterbart at terskelen bør være høyere ved store vinduer (f.eks. 75-80% for 1M-modeller), siden absolutt headroom betyr mer enn relativ. Men auto-compaction og prompt cache TTL er også prosent-baserte fenomener — så en universell 70% er sannsynligvis fortsatt riktig som default. Lavere prioritet enn fallback-fixen.

Verifisering

Etter implementering, test:

1. Smoke test: Opus 4.7-sesjon, kjør til ~50% (statusline viser pct), bekreft at auto-handoff IKKE trigger.
2. Unit test: Mock payload uten context_window, med model: 'claude-opus-4-7', verifiser at windowSize resolver til 1M.
3. Unit test: Payload med used_percentage: 75, verifiser at funksjonen returnerer 0.75 uansett windowSize.
4. Regresjon: Eksisterende tester i tests/ skal fortsatt passere.

Scope-vurdering

• Innenfor: Fix av stop-context-monitor.mjs fallback. Oppdater inline-kommentar (linje 14-16) og README/CLAUDE.md hvis 200K nevnes der.
• Utenfor: Endring av terskel-strategi (70% → variabel). Kan vurderes som separat oppgave.
• Utenfor: Endring av statusline-monitor.mjs (fungerer allerede modell-agnostisk).

Estimat

• Implementering: ~30 min (én fil + tester)
• Verifisering: ~15 min smoke + 15 min regresjon
• Doc-oppdatering: ~10 min (README, CLAUDE.md, CHANGELOG)
• Total: ~70 min, én sesjon

Neste skritt (når godkjent)

1. Bekreft Stop-hook payload-schema (har den used_percentage eller bare context_window_size?)
2. Implementer Alt 3 i stop-context-monitor.mjs
3. Oppdater fallback-kommentaren
4. Skriv tester for nye fallback-veier
5. Bump til v2.1.0 (minor — bug-fix + behavioral change)
6. Oppdater CHANGELOG, README, CLAUDE.md, rot-README