Lesson 5 · 17 min
A handoff written by the agent itself certifies itself: it can say it tested what it did not test, and the file may not even have been written. Since 10/17/2026 the proof is out of the text: a script writes a stamp, commit and fingerprint of the files, and the hook checks in the transcript that the handoff was really saved.
Start the lesson
Goal: write a handoff with the script, check its freshness with --conferir, and know when the hook nags, writes on its own, or warns that it did not save.
Skills session-handoff and prime from the agente-claude-codex 1.8.3 kit, with hook-longrun 1.9.6.
Decision rule: still true after the task → persistent memory (CLAUDE.md, AGENTS.md). State of this task → handoff. Record of what happened → history (git, progress, failures, decisions).
From the 10/17/2026 analysis of the kit.
The resume map, the sources of the test questions, and the evidence are paths and commits. That survives compaction, a new session, and a model switch.
A long history buries what the next agent needs to do.
The state block belongs to the script, not the agent. Each [confirmed] points to commit, teste:, or arquivo:.
In a long run, what decides whether it is finished is still the test run by the loop (lesson 6).
[confirmed] app.py devolve 1 (commit: base; teste: python3 -c "import app; print(app.f())" → 1)
Task and done criterion; last decision and why; what must not change; what is half done; next action and why. The source for each one is a project file, never the handoff itself.
After compaction or --resume, the hook asks for the 5 memory answers before opening the handoff, and the agent records the score with nota-retomada.py.
The agent grades itself: the answers are written down beforehand, so you can audit them, but it is not an independent check.
Codex has no hook: asking for and checking the handoff is left to the written rule and to you. The handoff and /prime work the same in both.
The skills come from the agente-claude-codex kit (1.8.3). The rehearsal runs in a throwaway repository in /tmp.
git clone https://github.com/inematds/agente-claude-codex ~/projetos/agente-claude-codex cd ~/projetos/agente-claude-codex cp -r skills/session-handoff/dist/claude/session-handoff skills/prime/dist/claude/prime ~/.claude/skills/ mkdir -p ~/.agents/skills cp -r skills/session-handoff/dist/codex/session-handoff skills/prime/dist/codex/prime ~/.agents/skills/ mkdir -p ~/projetos/<seu-projeto>/handoffs/history # the hook only asks for a handoff where this folder exists
rm -rf /tmp/ensaio-handoff && mkdir -p /tmp/ensaio-handoff/handoffs/history && cd /tmp/ensaio-handoff git init -q && git config user.name ensaio && git config user.email ensaio@local echo "def f(): return 1" > app.py && git add -A && git commit -qm base H=~/.claude/skills/session-handoff/scripts/handoff-grava.py cat > /tmp/corpo-handoff.md <<'EOF' # Handoff — ensaio-conferir ## Estado aceito - [confirmed] `app.py` devolve 1 (commit: base; teste: python3 -c "import app; print(app.f())" → 1) ## Não fazer - Não mudar a assinatura de f(). ## Próxima ação Trocar o retorno de f() para 2 e rodar o mesmo teste, que deve imprimir 2. ## Perguntas-teste 1. Qual é a tarefa e o critério de pronto? (fonte: app.py) 2. Qual foi a última decisão e por quê? (fonte: git log) 3. O que não pode mudar? (fonte: app.py) 4. O que está pela metade? (fonte: app.py) 5. Qual é a próxima ação e por quê? (fonte: app.py) EOF python3 $H --assunto ensaio-conferir < /tmp/corpo-handoff.md F=$(ls handoffs/history/*.md | head -1) python3 $H --conferir $F; echo "saída: $?" echo "def f(): return 2" > app.py python3 $H --conferir $F; echo "saída: $?"
snapshot: handoffs/history/2026-10-19T070502Z-ensaio-conferir.md latest.md: 1 assunto(s) aberto(s): ensaio-conferir commit 8900d4e ensaio <ensaio@local> (sem push) retomar ESTE handoff numa sessão nova (Codex: /new no lugar de /clear): /clear /prime handoffs/history/2026-10-19T070502Z-ensaio-conferir.md frescor: igual (1 arquivo(s) conferido(s); commit b89d8ad3ba51) saída: 0 frescor: divergente — o handoff é pista, não fato; confira antes de agir - app.py: mudou (citado no handoff) saída: 2
The stamp and the hashes change on every run. The snapshot: line is the one the hook reads in the transcript to know which handoff THIS session wrote.
corpo do handoff vazio ou curto demais).The first two do not use your quota. The third uses one of your sessions.
Install session-handoff and prime for Claude and for Codex and create handoffs/history/ in your long run's project.
Done when: python3 ~/.claude/skills/session-handoff/scripts/handoff-grava.py --help | grep -c conferir → 1 or more, and ls ~/.agents/skills lists prime and session-handoff.
Run the whole --conferir rehearsal.
Done when: frescor: igual with saída: 0, and after changing app.py, frescor: divergente with - app.py: mudou and saída: 2.
In your long run's project, ask for /session-handoff at the end of a block of work. Open a new session and run /prime with the path the script printed.
Done when: the /prime summary shows the freshness line (igual) and Perguntas-teste: N/5; write down the N in the run's progress.md.
Question 1 of 4
Who writes the state block (commit and sha256) of the handoff?skill
Question 2 of 4
--conferir exited with code 2. What does that mean?skill
Question 3 of 4
The hook asked for a handoff and, within 8 events, nothing appeared in handoffs/history/. What happens?
Question 4 of 4
"We ran the integration tests with --fast only on this machine" holds forever in this project. Where does it go?
Pick an answer. The explanation shows up after you try.