Skip to content

Session handoff and resume

A long session gets more expensive with every message: each turn re-reads the whole context, and once the prompt cache expires the next turn pays for all of it again. The fix is not to keep the thread alive but to close it: write the state into the session's HeyAira task, and start a fresh session that reads only that task. This document is the procedure. It works in any client that has the HeyAira MCP tools; client-specific steps (session ids, archiving) are marked as optional.

When to hand off

  • The task is done, or the work is about to change topic.
  • The context is past roughly half of the window and the next step does not need the conversation history.
  • End of the working day: a session resumed the next morning has lost its cache anyway.

The session proposes the handoff itself at these points; the owner only starts the next session.

Handoff (old session)

  1. server_identity on the project the work belongs to and compare it with the connection profile you were given; stop on a mismatch. write_context comes from that profile, never from echoing the server's answer (safe-mutations.md).
  2. Find the task this session is working on (an id given by the owner, the task this conversation already read or updated, or task_list with status=in_progress matched by title or tag). No clear task: ask the owner one question; work without a task: propose task_create and wait.
  3. task_get for the current version and the existing handoff, so earlier decisions are kept, not overwritten.
  4. Write the handoff — concrete, no conversation history, no secrets:
  5. handoff_completed: what is done, split into prepared (code) · tested · deployed · verified in production, with pull requests, commits and test results with numbers.
  6. handoff_next: the first step as a command the next session can run without searching (file, branch, pull request, command), then the remaining steps in order. Last line: Previous session: <id> when the client exposes a session id.
  7. handoff_blockers: what the work waits for and from whom; empty if nothing.
  8. summary (≤ 280 characters): the state in one sentence, as the task list should show it.
  9. work_receipt: session_ref, harness, model, branch, base_commit, result_commit, tests, completed_work, next_step, blockers. The receipt has no repository field: name the repository (URL or owner/name) in handoff_completed or handoff_next.
  10. Decisions that must outlive the task: memory_add, and name their ids in handoff_next.
  11. task_update with write_context and expected_version, and the status that matches the work: in_progress when the next session continues it; done when the task is finished (plus the RESULT memory AGENTS.md requires); blocked with a specific reason in handoff_blockers. On version_conflict, re-read and merge; never overwrite.
  12. task_get again and confirm the new version holds the handoff.
  13. Reply to the owner with one sentence and one line to paste into the new session: handoff: <first 8 characters of the task id> v<version>.

Resume (new session)

  1. Read the repository's AGENTS.md, then server_identity and continuity_context — read-only.
  2. Find the task by the id prefix (task_list by status, then task_get with the full id). If its version is higher than the one in the handoff line, also read that version and tell the owner something changed since.
  3. Read handoff_completed, handoff_next, handoff_blockers, the last receipt and the memories it names — only what the first step needs. Check the Git state of the named branch.
  4. Confirm the takeover on the task, so a handoff that was written but never picked up is visible: task_update whose handoff_completed is the current text from the latest task_get with one line appended saying which session took it over. The field is replaced, not appended to — sending only the new line erases the handoff. On version_conflict, re-read and append again.
  5. Optional, where the client can: archive the previous session named in handoff_next, unless it is still running.
  6. Report in two or three sentences: the task, its state, the first step — then do that step, or ask one question if it needs the owner.

What a good handoff is measured by

The next session reaches its first useful action from the task alone: no re-reading of the repository history, no questions the handoff could have answered. If it has to search, fix the handoff, not the resume step.