Skip to content

Write a session handoff

The successor must reach its first useful action from the HeyAira task alone. Use this procedure in any interactive MCP client when asked to hand off, at task completion, a topic change, the end of the day, or when context is past roughly half the window. Coding runs started with scripts/heyaira-run.sh report to the coordinator, who records results with task_update. Write durable fields in the project's working language; never copy conversation history, repository contents or secrets into HeyAira.

  1. Check identity. Call server_identity for the intended project and compare resource, instance and project with the supplied profile. Stop on mismatch. write_context uses that pinned profile, never guessed values.
  2. Find the task. Use the supplied ID, the task already read in this session, or task_list(status=in_progress) matched by title/tags. If there is no single clear task, ask for clarification. If the work has no task, propose creating one and wait for authorization.
  3. Read current state. Call task_get for the current version, description, handoff and receipts. Preserve earlier decisions and completed work.
  4. Prepare the handoff and receipt. Record concrete, attributable facts:
  5. handoff_completed: repository (owner/name or URL), branch, commits and PR references; distinguish prepared code, tested behavior, deployed state and verification in production. Include actual commands and test totals; identify unrun checks. Do not imply a deployment from a passing test.
  6. handoff_next: the first executable command or instruction (with file, branch or PR), then remaining steps in order. End with Previous session: <session-reference> using a native session ID if available, otherwise a stable label explicitly identified as a label.
  7. handoff_blockers: what blocks, who moves next and what is needed; empty when nothing blocks.
  8. summary: at most 280 characters describing the current state in one sentence for the next session's task list.
  9. work_receipt: actual session_ref, harness, model, branch, base_commit, result_commit, tests, completed_work, next_step and blockers. It has no repository field: put the repository in the handoff. Save decisions that must outlive the task with memory_add(kind=decision) and name their IDs in handoff_next; keep task-specific agreements in the handoff. Use a useful one-sentence summary for every write.
  10. Write and verify. Call task_update with matching write_context and current expected_version. Follow the project's work contract: use in_progress for an authorized session continuation, todo when releasing paused work with no owner, blocked with the three-part blocker, or done only when the completion criteria and required reviews are met (plus RESULT). On version_conflict, re-read and merge; never overwrite. Call task_get again and confirm the new version and saved fields.
  11. Return a portable line. Say what was saved and give handoff: <first 8 characters of task UUID> v<saved version> to paste into a fresh session. The successor follows take-over-session; no client slash command is required. This session stops working on the task after handoff.
  12. Late messages. Do not act on new task messages in this old session. Find the successor from the task's Taken over by session ... line or available session metadata. Forward when messaging is available and authorized, with sender attribution; tell the sender where work moved. If there is no successor yet, return the versioned handoff line. Do not use messaging as durable project state.

If the client has session-management tools (for example Claude Desktop), use get_session("self") for the actual session ID and client harness in the receipt and Previous session: line; a scratchpad or transcript directory name is not the session ID. The successor may use list_sessions, archive_session and set_session_title to take over the old title and handle messages. Do not archive this session yourself: the successor archives it after confirming takeover and reading messages in flight. If these tools are unavailable, report that fact without promising archival or message delivery.

Sources