claude-code-handoff 1.5.1 → 1.6.0

package/README.md

@@ -161,7 +161,7 @@ The biggest risk with handoffs is **forgetting to save**. You're deep in a task,
 
 ### How It Works
 
-A [Claude Code hook](https://docs.anthropic.com/en/docs/claude-code/hooks) runs after every Claude response (Stop event). It checks the transcript file size against a configurable threshold. When the threshold is exceeded, it **blocks** Claude's next action and forces an immediate handoff save.
+A [Claude Code hook](https://docs.anthropic.com/en/docs/claude-code/hooks) runs after every Claude response (Stop event). It reads the **actual token count** from Claude's API usage data in the JSONL transcript and compares it against the 200K token context window. When the threshold is exceeded, it **blocks** Claude's next action and forces an immediate handoff save.
 
 ```mermaid
 flowchart TD
@@ -178,18 +178,21 @@ flowchart TD
 
 ### Threshold Configuration
 
-The threshold is configured as a **percentage of the estimated maximum context** (~500KB transcript). This makes it intuitive — you think in terms of "how full is my context?" rather than raw byte counts.
+The threshold is configured as a **percentage of the 200K token context window**. The hook reads the **actual token count** from Claude's API usage data in the transcript — no guesswork, no byte-to-token estimation.
 
 | Preset | Value | Triggers at | Best for |
 |--------|-------|-------------|----------|
-| **90% (default)** | `THRESHOLD_PERCENT=90` | ~450KB | Maximizing context usage |
-| **80%** | `THRESHOLD_PERCENT=80` | ~400KB | Balance between space and safety |
-| **75%** | `THRESHOLD_PERCENT=75` | ~375KB | Short sessions, early handoff |
+| **90% (default)** | `THRESHOLD_PERCENT=90` | 180K tokens | Maximizing context usage |
+| **80%** | `THRESHOLD_PERCENT=80` | 160K tokens | Balance between space and safety |
+| **75%** | `THRESHOLD_PERCENT=75` | 150K tokens | Short sessions, early handoff |
 
-The calculation is straightforward:
+The calculation uses real data:
 ```
-MAX_CONTEXT_SIZE = 500000  (500KB — estimated max transcript)
-THRESHOLD = MAX_CONTEXT_SIZE × THRESHOLD_PERCENT / 100
+MAX_CONTEXT_TOKENS = 200000   (Claude Code's context window)
+THRESHOLD = MAX_CONTEXT_TOKENS × THRESHOLD_PERCENT / 100
+
+# The hook reads input_tokens from the last assistant message in the JSONL
+# This is the ACTUAL context size — not an estimate
 ```
 
 ### Three Ways to Configure
@@ -572,7 +575,7 @@ A: The commands automatically summarize older sessions into a "Prior Sessions Su
 A: Absolutely. They're plain markdown. You can add notes, reorder next steps, or clean up history.
 
 **Q: How does the auto-handoff threshold work?**
-A: The threshold is a percentage of the estimated maximum transcript size (~500KB). At 90% (default), the hook triggers when the transcript reaches ~450KB. You can set any value from 1-100 via env var (`CLAUDE_CONTEXT_THRESHOLD=80`) or the `/auto-handoff` command.
+A: The threshold is a percentage of Claude Code's 200K token context window. At 90% (default), the hook triggers at 180K tokens. The hook reads the **actual token count** from Claude's API usage data — not file size estimates. You can set any value from 1-100 via env var (`CLAUDE_CONTEXT_THRESHOLD=80`) or the `/auto-handoff` command.
 
 **Q: Can I disable auto-handoff?**
 A: Yes. Run `/auto-handoff` and select "Disable", or manually create the file `.claude/hooks/.auto-handoff-disabled`. Delete the file to re-enable.

package/hooks/context-monitor.sh

@@ -9,11 +9,11 @@ if [ -f "$SCRIPT_DIR/.auto-handoff-disabled" ]; then
   exit 0
 fi
 
-# Contexto máximo estimado (bytes). 500KB ~ transcript máximo típico
-MAX_CONTEXT_SIZE=500000
+# Contexto máximo do Claude Code (tokens)
+MAX_CONTEXT_TOKENS=200000
 # Threshold configurável (% do contexto). 90% padrão — maximiza uso do contexto
 THRESHOLD_PERCENT=${CLAUDE_CONTEXT_THRESHOLD:-90}
-THRESHOLD=$((MAX_CONTEXT_SIZE * THRESHOLD_PERCENT / 100))
+THRESHOLD_TOKENS=$((MAX_CONTEXT_TOKENS * THRESHOLD_PERCENT / 100))
 
 INPUT=$(cat)
 TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty')
@@ -28,11 +28,52 @@ if [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
-# Verifica tamanho do transcript
-SIZE=$(wc -c < "$TRANSCRIPT_PATH" 2>/dev/null || echo 0)
-SIZE=$(echo "$SIZE" | tr -d ' ')
+# Extrai o input_tokens da última mensagem do assistente no JSONL.
+# Isso reflete o tamanho REAL do contexto que o Claude está usando.
+# Campos: input_tokens + cache_read_input_tokens + cache_creation_input_tokens = total input
+CURRENT_TOKENS=0
+if command -v python3 &>/dev/null; then
+  CURRENT_TOKENS=$(python3 -c "
+import json, sys
+last = 0
+with open('$TRANSCRIPT_PATH') as f:
+    for line in f:
+        try:
+            e = json.loads(line)
+            if e.get('type') == 'assistant':
+                u = e.get('message', {}).get('usage', {})
+                t = u.get('input_tokens', 0) + u.get('cache_read_input_tokens', 0) + u.get('cache_creation_input_tokens', 0)
+                if t > 0:
+                    last = t
+        except:
+            pass
+print(last)
+" 2>/dev/null)
+elif command -v node &>/dev/null; then
+  CURRENT_TOKENS=$(node -e "
+const fs = require('fs');
+const lines = fs.readFileSync('$TRANSCRIPT_PATH', 'utf-8').trim().split('\n');
+let last = 0;
+for (const line of lines) {
+  try {
+    const e = JSON.parse(line);
+    if (e.type === 'assistant' && e.message?.usage) {
+      const u = e.message.usage;
+      const t = (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
+      if (t > 0) last = t;
+    }
+  } catch {}
+}
+console.log(last);
+" 2>/dev/null)
+fi
+
+CURRENT_TOKENS=$(echo "$CURRENT_TOKENS" | tr -d ' \n')
+if [ -z "$CURRENT_TOKENS" ] || [ "$CURRENT_TOKENS" -eq 0 ] 2>/dev/null; then
+  exit 0
+fi
 
-if [ "$SIZE" -lt "$THRESHOLD" ]; then
+if [ "$CURRENT_TOKENS" -lt "$THRESHOLD_TOKENS" ]; then
   exit 0
 fi
 
@@ -43,10 +84,13 @@ if [ -f "$FLAG" ]; then
 fi
 touch "$FLAG"
 
+# Calcula % atual
+CURRENT_PERCENT=$((CURRENT_TOKENS * 100 / MAX_CONTEXT_TOKENS))
+
 # Bloqueia e força handoff
 cat <<HOOKEOF
 {
   "decision": "block",
-  "reason": "⚠️ AUTO-HANDOFF: O contexto atingiu ${THRESHOLD_PERCENT}% do limite. Você DEVE salvar o handoff AGORA.\n\nSiga estes passos IMEDIATAMENTE:\n1. Analise a conversa inteira e extraia: o que foi feito, próximos passos, arquivos-chave, decisões\n2. Escreva o handoff em .claude/handoffs/_active.md seguindo o template padrão\n3. Diga ao usuário: 'Handoff salvo automaticamente. Use /clear e depois /resume para continuar.'\n\nNÃO continue com outro trabalho até o handoff estar salvo."
+  "reason": "⚠️ AUTO-HANDOFF: O contexto atingiu ${CURRENT_PERCENT}% do limite (${CURRENT_TOKENS}/${MAX_CONTEXT_TOKENS} tokens). Você DEVE salvar o handoff AGORA.\n\nSiga estes passos IMEDIATAMENTE:\n1. Analise a conversa inteira e extraia: o que foi feito, próximos passos, arquivos-chave, decisões\n2. Escreva o handoff em .claude/handoffs/_active.md seguindo o template padrão\n3. Diga ao usuário: 'Handoff salvo automaticamente. Use /clear e depois /resume para continuar.'\n\nNÃO continue com outro trabalho até o handoff estar salvo."
 }
 HOOKEOF

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-handoff",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Session continuity for Claude Code — 5 slash commands to save, resume, delete, and switch workstreams across /clear",
   "bin": {
     "claude-code-handoff": "./cli.js"