read-handoffs

name	read-handoffs
description	Resume a session by loading recent handoffs from Engram. Use at the start of a session or when the user wants to review what was done previously.
disable-model-invocation	true

Load session context from Engram via the mcp__engram__handoff_resume MCP tool. Engram is the canonical store; legacy .claude/handoff/*.md files were ported via engram-port-handoffs and are no longer read.

Steps

1. Call mcp__engram__handoff_resume with no arguments. Defaults: current branch, max_sections: 5, include_off_branch: false.

2. Inspect the result. Engram returns:

   • branch — the resolved branch (or null if detached HEAD)
   • latest_handoff_id — most recent handoff on this branch
   • chain — handoff ids ordered oldest-to-newest via continues_from (capped at depth 5, cycle-detected)
   • top_sections — highest-scoring sections across the chain, each with handoff_id, section_name, section_text, score
   • linked_memories — decision/pattern/debug memories the latest handoff links to via derived_from
   • message — only present when branch could not be resolved

3. Handle the empty case. If chain is empty AND latest_handoff_id is null, say "No prior handoffs on this branch." Then call mcp__engram__handoff_resume again with include_off_branch: true to surface handoffs from other branches as background.

4. Handle detached HEAD. If message is set, tell the user no current branch was detected and present whatever off-branch results came back, flagged as such.

5. Present to the user, in this order:

   • Status line: Resuming \`, handoff(s) in chain, latest from `
   • Top sections: summarize each top_sections entry. Group by handoff_id if multiple sections come from the same handoff. Quote the strongest section text verbatim; paraphrase weaker matches.
   • Open todos / blockers from the latest handoff: surface these explicitly so the user immediately sees what's pending.
   • Linked memories: bullet list of linked_memories with their type and content preview ("Related decision: ...", "Related debug: ...").

6. Pair with mcp__engram__memory_context. Call it with a short description of the inferred current task (derived from top_sections and linked_memories). Surface any additional memories that didn't come through the handoff chain.

7. Closing note. End with a one-liner: which handoff in the chain is the working starting point, and whether you followed any cross-references the user might want expanded.

Why this matters

The handoff chain encodes session-to-session continuity: each continues_from link means "the next agent should pick up from here". The top-sections retrieval is hybrid (similarity + recency); a single old but highly-relevant section can outrank newer but generic content. Trust the ranking; do not just present the latest handoff verbatim.

Specific lookups

If the user asks about a specific past handoff (by date, by topic), use mcp__engram__handoff_search with a query string. Filter by section with section_filter: ["blockers"] etc. when the user is asking targeted questions like "have we hit this kind of error before?".