Lesson 3 · 18 min
The biggest enemy of a long session is repeated compaction: the goal survives, but what is done and what remains get diluted. The hook-longrun measures the context and acts before the limit, in three bands. In this lesson you turn on the hook and trigger all three bands in a rehearsal, without spending a token.
Start the lesson
Goal: turn on the hook-longrun and trigger the three bands in a rehearsal, knowing what each one asks of the agent and when to do /clear + /prime.
The percentage is of the point at which Claude Code compacts by size, not of the whole window.
Hook-longrun 1.9.6 (10/18/2026). The bands change with LONGRUN_FAIXAS="50,70,85". The warning arrives one tool call later, because the transcript is written with a delay.
What each path keeps, measured on 10/15/2026 (17 compactions with a handoff from the same session in the 3 h before).
The summary cites 20 to 54 files and keeps recent steps and commands. Within the same session, it holds more concrete detail than the handoff.
But it doesn't separate what's confirmed from what's a guess, it mixes the decisions into the narrative, and it doesn't survive /clear.
It cites 1 to 27 files, but it marks what was proven, and keeps the decisions and the next action in a section of their own.
It's the only one that works for another session, another day, or Codex. The two together are better than either one alone.
Writing the handoff from the compaction summary: it becomes a copy of a copy.
The new session rediscovers things: 80% of the first 25 steps were reads, versus 51–59% after compacting.
That's why the new session comes at band 3 or the 3rd compaction, at the end of the unit in progress, and not early.
Half of a 1.84 GB JSONL measured on 10/01/2026 was tool output. Write logs to a file and read the part you need (tail -50).
A subagent spends its own context and returns only the summary; Anthropic cites returns of 1,000 to 2,000 tokens. How to use subagents is the topic of course 3.
The rehearsal writes a fake transcript with whatever number of tokens you want and calls the hook the way Claude Code would.
{
"cleanupPeriodDays": 365,
"hooks": {
"PreCompact": [{ "hooks": [{ "type": "command", "command": "bash ~/projetos/execucao-longa/tools/hook-longrun.sh 2>/dev/null || true", "timeout": 10 }] }],
"SessionStart": [{ "matcher": "compact|resume|clear", "hooks": [{ "type": "command", "command": "bash ~/projetos/execucao-longa/tools/hook-longrun.sh 2>/dev/null || true", "timeout": 10 }] }],
"PostToolUse": [{ "hooks": [{ "type": "command", "command": "bash ~/projetos/execucao-longa/tools/hook-longrun.sh 2>/dev/null || true", "timeout": 10 }] }],
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash ~/projetos/execucao-longa/tools/hook-longrun.sh 2>/dev/null || true", "timeout": 10 }] }],
"Stop": [{ "hooks": [{ "type": "command", "command": "bash ~/projetos/execucao-longa/tools/hook-longrun.sh 2>/dev/null || true", "timeout": 10 }] }]
}
}# ensaio-hook.sh — dispara o hook-longrun com uma transcrição FALSA (nenhum token gasto)
# uso: bash ensaio-hook.sh <tokens|-> [minutos-parado] [evento] ("-" reaproveita a transcrição anterior)
E=/tmp/ensaio-hook; K=~/projetos/execucao-longa
mkdir -p $E/proj/longrun/2026-10-19-teste $E/proj/handoffs/history
[ -f $E/proj/longrun/2026-10-19-teste/state.md ] || echo "# Estado" > $E/proj/longrun/2026-10-19-teste/state.md
[ "${1:-500000}" = "-" ] || python3 - "${1:-500000}" "${2:-0}" > $E/t.jsonl <<'PY'
import json, sys, time, datetime
n, parado = int(sys.argv[1]), float(sys.argv[2])
ts = datetime.datetime.fromtimestamp(time.time() - parado * 60, datetime.timezone.utc).isoformat().replace("+00:00", "Z")
print(json.dumps({"type": "assistant", "timestamp": ts, "message": {"model": "claude-opus-5-5",
"content": [{"type": "text", "text": "ok"}],
"usage": {"input_tokens": 10, "cache_read_input_tokens": n - 10, "cache_creation_input_tokens": 0}}}))
PY
echo "{\"hook_event_name\":\"${3:-PostToolUse}\",\"cwd\":\"$E/proj\",\"session_id\":\"ensaio\",\"transcript_path\":\"$E/t.jsonl\",\"prompt\":\"oi\"}" \
| LONGRUN_ESTADO=$E/estado LONGRUN_AGENDAR_ARQ=$E/agenda.jsonl python3 $K/tools/hook-longrun.py
echorm -rf /tmp/ensaio-hook bash ensaio-hook.sh 500000 # faixa 1 bash ensaio-hook.sh 500000 # mesma faixa: silêncio (uma vez por faixa) bash ensaio-hook.sh 700000 # faixa 2 bash ensaio-hook.sh 830000 # faixa 3
$ bash ensaio-hook.sh 500000
{"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext":
"Contexto em 52% do ponto de compactação (500 mil de 967 mil tokens). FAIXA 1 de 3:
antes de seguir, acrescente em longrun/2026-10-19-teste/canal.md o que você precisaria
se o histórico sumisse agora (…) Só acrescentar. Depois continue o trabalho normalmente."}}
$ bash ensaio-hook.sh 500000
$ bash ensaio-hook.sh 700000
{… "Contexto em 72% do ponto de compactação (700 mil de 967 mil tokens). FAIXA 2 de 3:
atualize state.md, progress.md e (…) canal.md; termine a unidade de trabalho atual e
grave o handoff agora (…)"},
"systemMessage": "Execução longa em 72% do ponto de compactação: hora de /compact
(o agente foi avisado)."}
$ bash ensaio-hook.sh 830000
{… "Contexto em 86% do ponto de compactação (830 mil de 967 mil tokens). FAIXA 3 de 3:
não abra trabalho novo. (…) /session-handoff, sessão nova e /prime (…) ao fim da
unidade em curso, sem largá-la no meio. (…)"},
"systemMessage": "Execução longa em 86% do ponto de compactação: hora de
/session-handoff + sessão nova + /prime."}Line breaks and (…) added to fit the screen; the text is from hook-longrun 1.9.6. The additionalContext goes to the agent; the systemMessage appears to you.
/status; what follows the bands is the AGENTS.md rule (lesson 1) and you./compact earlier.compact_prompt; the structured prompt in ~/.codex/config.toml only applies to the manual /compact.The first exercise touches your settings.json: make a backup first.
Copy settings.json to settings.json.bak and merge the hooks excerpt into the ones you already have (don't delete yours). Open a new Claude Code session to load it.
Done when: python3 -c "import json,os;h=json.load(open(os.path.expanduser('~/.claude/settings.json')))['hooks'];print(sorted(e for e,l in h.items() if 'hook-longrun' in json.dumps(l)))" → ['PostToolUse', 'PreCompact', 'SessionStart', 'Stop', 'UserPromptSubmit'].
Save ensaio-hook.sh and run the three-band sequence. Then delete /tmp/ensaio-hook and run LONGRUN_TETO=600000 bash ensaio-hook.sh 500000.
Done when: these appear, in this order: FAIXA 1 de 3, nothing, FAIXA 2 de 3, and FAIXA 3 de 3; with LONGRUN_TETO=600000, 500 thousand already lands in FAIXA 2 de 3 (83% of 600 thousand).
Question 1 of 4
On a 1M model, at how many tokens does the hook warn for band 2 by default?skill
Question 2 of 4
Band 3 fired in the middle of a refactor. What should the agent do?skill
Question 3 of 4
Within the same session, which one keeps more concrete detail (files, steps)?
Question 4 of 4
You use Codex. How do you follow the bands?
Pick an answer. The explanation shows up after you try.