Cross-Agent Handoff Methodology

The problem

The AI coding CLIs in common use (Claude Code, Codex CLI, Cursor, Gemini CLI) do not share session state with each other. Each one keeps its conversation buffer in its own process and its own on-disk format. Nothing in any vendor protocol asks them to coordinate. When a session ends (daily quota, context window, restart, machine change), the next session is a cold start.

The common recovery pattern is paste-the-transcript: copy the previous conversation into the new CLI and explain where the work stopped. That pattern has three known failure modes. First, it is lossy. The transcript contains words but not a structured handle the next agent can act on, so the agent infers state by re-reading dialogue and frequently infers it wrong. Second, it drops the tool envelope. The policy preset, the allowed-tool list, and the governance kernel state are not in the transcript, so the next agent runs with whatever defaults the new CLI applies. Third, it does not survive across machines or model versions. A transcript pasted into a different model is not a faithful replay of the original session.

The re-derivation cost is paid every handoff. It scales with how long the original session ran. That is the cost the pattern below removes.

The pattern: artifact, not conversation

The handoff artifact IS the shared state. A single JSON record written to ~/.delimit/sessions/ with seven named fields. Any CLI that speaks MCP to the same Delimit server reads and writes the same record. The artifact, not the conversation, carries continuity.

Two properties make the pattern work. First, the writer is the MCP server, not the CLI; the on-disk shape is identical regardless of which CLI produced it. Second, the record is local-first and content-addressed by its id; any reader at the same id sees the same fields. The CLI vendors do not need to coordinate because the coordination point is the artifact, not the protocol.

This is the same primitive Delimit uses for the merge gate (deterministic classification of API diffs against a published schema). Applied to session state, the schema is the seven fields below, and the deterministic write is delimit_session_handoff.

The seven fields

The on-disk record is a flat JSON object with seven named fields. The shape is fixed; new fields are additive and never rename or remove an existing one. Field semantics:

1. 1. id

   Session identifier in the form session_YYYYMMDD_HHMMSS. Content-addresses the record; same id from any reader yields the same payload.

2. 2. timestamp

   ISO-8601 UTC string at the moment the handoff was written. Establishes a stable ordering for the directory.

3. 3. venture

   Optional project or venture tag (defaults to all). Lets a reader filter handoffs when multiple projects share one handoff store.

4. 4. summary

   Short prose statement of where the session is leaving the work. One to three sentences. Replaces the transcript wall with a structured one-paragraph summary.

5. 5. items_completed / items_added

   Two parallel string lists for ledger items closed during the session and new items raised by the session. The next agent reads both to know what to skip and what to triage.

6. 6. key_decisions / blockers

   Two string lists. Decisions captures locked-in choices the next agent must not re-litigate; blockers captures live open questions the next agent should resolve.

7. 7. files_changed

   String list of file paths touched in the session, with optional inline status (e.g. an (in progress) marker). The resuming agent re-opens this set before doing any new edits.

Tool sources for the signature above: delimit-gateway/ai/ledger_manager.py (on-disk writer, function session_handoff) and delimit-gateway/ai/server.py (MCP tool definition exposed as delimit_session_handoff).

Producer side (writing the handoff)

The producer is whatever CLI is winding down. The agent in that CLI calls delimit_session_handoff with the structured fields. The MCP server (not the CLI) writes the JSON record. The call shape:

# Inside the producing CLI, near end of session
delimit_session_handoff(
  summary="One-paragraph statement of where the work is.",
  items_completed=["LED-1234"],
  items_added=["LED-1240"],
  key_decisions=["Helper signature locked: (input, opts?) -> Result"],
  blockers=["Caller B return shape open"],
  files_changed=["src/lib/helper.ts", "src/callers/a.ts", "src/callers/b.ts (in progress)"],
  venture="all"
)
# Returns: {"saved": "session_20260512_143012", "path": "~/.delimit/sessions/session_20260512_143012.json"}

Because the writer is the server, the on-disk shape is invariant across producing CLIs. A handoff written from Claude Code and a handoff written from Codex are byte-identical in schema; the only differences are the field values.

Consumer side (reading the handoff)

The consumer is the resuming CLI. Two MCP tools cover the read path. delimit_revive loads the latest captured soul (active task, open question, files modified) and surfaces it as next-step context. delimit_ledger_context loads the open ledger items, recent decisions, and active policy preset. A shell verb, delimit resume, wraps the same read for terminal use outside an MCP session.

# Inside the resuming CLI, at session start
delimit_revive()
# Returns the latest handoff fields plus the captured soul:
#   active_task, files_modified, open_question, next_step

delimit_ledger_context()
# Returns:
#   open_items, recent_decisions, policy_preset

The resuming agent does not re-read a transcript. It reads two structured records. The work resumes at the open question with the decisions intact and the file set already loaded.

Where the handoff falls short

The handoff is a structured summary, not a complete session replay. It is bounded by design. Reading it as proof of any of the items below is reading it incorrectly.

• File diffs

  The handoff records file paths touched, not the diffs themselves. Diffs live in git; the handoff complements git, it does not replace it. A clean commit is still the portable record for finished work.

• Raw conversation transcript

  The handoff is a structured summary; it does not preserve the back-and-forth dialogue. If the prior session's reasoning trace matters, capture it separately (CLI buffer export, log file, or a manual memory_store call).

• Tool-call traces

  The handoff names the active policy preset but does not record every tool invocation in the prior session. Tool-call evidence is what delimit_evidence_collect produces; the handoff is a different artifact class.