Session Handoff

What it does

Session Handoff is an evacuation and return protocol for unfinished AI-assisted work. It is used when the current execution window itself is becoming risky: quota, context, runtime, provider limits, or a deliberate switch between machines or agents.

The goal is recoverability, not transcript preservation. The next agent should receive enough verified state to continue from the actual source, not enough prose to reconstruct an entire conversation.

Two pressure stages

PREPARE — 80% default when credible telemetry exists

PREPARE is cheap and reversible.

• Keep working.
• Refresh the compact objective, decisions, repository identity, validation evidence, and likely next action.
• Refresh a local handoff package when useful.
• Avoid opening a large new branch of work that cannot be drained safely.
• Do not create an extra remote checkpoint merely because PREPARE was entered.

The 80% threshold is a default for environments that expose trustworthy quota or rate-limit telemetry. If the host does not expose it, do not manufacture a percentage. Use a provider warning, explicit operator request, or an unknown / manual signal instead.

EVACUATE — 90% default or equivalent near-limit signal

At EVACUATE, enter drain mode:

1. Do not begin a new large implementation step.
2. Finish only the smallest safe atomic operation already underway.
3. Inspect the actual repository, worktree, branch, HEAD, staged/unstaged state, and applicable instructions.
4. Run only the minimum useful validation likely to finish safely.
5. Preserve every task-relevant source change.
6. Make the source state recoverable by the receiver.
7. Produce the handoff package.
8. Transfer the execution lease and freeze the source side.
9. Report a ready signal only when the receiver can actually recover the work.

A provider near-limit warning, insufficient remaining capacity, or a manual HANDOFF NOW request can enter EVACUATE directly.

Portable handoff package

A practical filesystem shape is:

.session-handoff/
└─ <cycle-id>/
   ├─ manifest.json
   └─ HANDOFF.md

The machine-readable capsule should capture only continuation-critical state:

• trigger reason and only actually observed usage data;
• source and destination role when relevant;
• cycle ID and transfer leg;
• objective, acceptance criteria, scope, and out-of-scope boundaries;
• repository/worktree/base/current branch, HEAD, upstream, dirty state, and relevant files;
• completed / in-progress / remaining / blocked / deferred work;
• decisions, assumptions, rejected approaches, and do_not_repeat items;
• validations actually run, including failures and not-run checks;
• safe metadata for skills, tools, integrations, and instructions actually used;
• recoverable checkpoint location;
• first files to read, one exact next action, risks, and decisions not to change silently.

The human brief is the scan-first view of the same state. It should not become a transcript dump.

Source recoverability comes first

A context document alone is not a handoff when source changed. Prefer the least expensive repository-approved mechanism that makes the exact work available to the receiver:

1. the existing task branch/current remote branch checkpoint;
2. a repository-specific handoff branch or orchestrator checkpoint;
3. an approved shared filesystem or worktree;
4. capsule-only only when source did not change.

An operational checkpoint push does not imply permission to push protected main, merge a PR, force-push, tag/release, deploy to Production, change credentials, or perform destructive operations.

Execution lease

A handoff cycle has one authoritative executor.

• Before transfer, the current owner holds the lease.
• After HANDOFF_READY, the destination accepts the lease only after verifying the real repository and instructions.
• Once the source side is frozen, it can review or communicate but should not independently keep editing the same task.
• If the work later returns, the same rule applies in reverse.

This avoids split-brain work when the same task exists on two machines, sessions, or agents.

Verified takeover

The receiver does not start implementing immediately after reading a handoff.

1. Read the capsule and human brief.
2. Fresh-read repository instructions such as AGENTS.md or CLAUDE.md.
3. Verify repository identity, branch, HEAD, working tree, and referenced files.
4. Compare the recorded checkpoint with actual source state.
5. Let real source state win when the capsule is stale.
6. Accept the execution lease only after verification.
7. Resume from the recorded single next action.
8. Do not repeat completed work or explicitly rejected approaches without new evidence.

Optional emergency-return profile

Some teams have a normal execution environment and a separate emergency environment with more available capacity. Session Handoff supports a bidirectional cycle:

PRIMARY / NORMAL
  → PREPARE
  → EVACUATE
  → HANDOFF_READY
  → EMERGENCY TAKEOVER + WORK
  → RETURN_HANDOFF_READY
  → PRIMARY VERIFY + RESUME/REVIEW
  → CLOSED

The labels can represent different seats, machines, accounts, people, or providers. The protocol is the same: make source recoverable, transfer one lease, and return it explicitly.

A return handoff is required even when the emergency executor finished all implementation. The original owner should resume at review/verification, not redo completed work.

Manual fallback is part of the design

Provider-specific status lines, hooks, or quota adapters can improve trigger quality, but they are optional. A host-neutral protocol should still work when automation is unavailable:

• telemetry adapter available → trigger PREPARE/EVACUATE automatically at a safe boundary;
• only provider warning available → use that warning;
• no reliable signal available → manual prepare/handoff remains the fallback.

Automation must never fabricate a threshold event from token or context estimates.

How this differs from Agent Handoff

Agent Handoff is the general skill for planned transfers between agents or sessions.

Session Handoff is the continuity specialization for execution-window risk. It adds:

• pressure-aware PREPARE and EVACUATE stages;
• recoverable source checkpoints;
• one-owner execution leases and source freezing;
• verified takeover;
• explicit return handoff and closure;
• optional provider adapters without making the core protocol provider-specific.

Use Agent Handoff for a calm planned transfer. Use Session Handoff when interruption risk itself must be managed.