Handoff

🤝 handoff — Bidirectional Agent Handoff & Session Resumption Engine

Aliases: agent-handoff | subagent-handoff | context-packet | resume | where-were-we

handoff provides bidirectional context continuity across agent lifecycles:

1. Inbound Resumption: Resumes previous agent sessions with boundary-safe directory matching, leading with any unanswered open questions.
2. Outbound Dispatch: Generates lean, bounded context packets before dispatching subagents or stepping away.

When to Use

Mode A: Inbound Session Resumption

• User asks: "where were we", "resume", "pick up where I left off", "what was I doing", or begins a session with no fresh prompt.
• Restoring state after an interruption or machine restart.

Mode B: Outbound Subagent Dispatch

• Before dispatching any subagent for backend, frontend, testing, or refactoring.
• Before spawning multi-agent teams or worker processes.
• Before stepping away from a long-running session (>30 minutes).
• Whenever a task prompt to another agent exceeds 3 sentences.

Quick Reference

Inbound vs Outbound Comparison

Procedures

🔄 Mode A: Inbound Session Resumption Procedure

1. Resolve Workspace Directory: Normalize the current working directory. If a directory override argument is provided, resolve to an absolute path.
2. Retrieve Prior Session: Query session history (via MCP memory tools memory_sessions / memory_recall or inspect .agents/artifacts/ and .agents/context/current.md).
   • Enforce Directory-Boundary Isolation:

     // Prohibit raw prefix matching to prevent sibling repo bleed:
     session.cwd === projectPath || session.cwd.startsWith(projectPath + path.sep)
     

3. Surface Unanswered Questions FIRST: If the prior session ended on an unanswered user question (?), highlight it at the very top of your response. Do not guess the answer.
4. Format Resumption Summary:

   Resuming [session_id] "[session_title]".
   
   ❓ Open Question from Last Session:
   [Unanswered question, if present]
   
   📌 State Summary:
   - Key decisions & modified files
   - Active roadblocks
   
   👉 Immediate Next Step:
   [Single concrete atomic action]
   

📦 Mode B: Outbound Subagent Dispatch Procedure

1. Extract Operational Facts:
   • Objective: Exact 1-sentence goal starting with an imperative verb.
   • Decisions Made: Irreversible choices not to be re-litigated.
   • Ruled-Out Paths: Approaches tried and eliminated with failure reasons.
   • Target Scope: Exact files to touch.
   • Hard Constraints: Forbidden files, libraries, or credentials (MUST NOT).
   • Deterministic Verification: Exact test or build command.
   • If Blocked: Escalation fallback.
2. Write Handoff Packet: Save to .agents/artifacts/handoff-<timestamp>.md:

# Agent Handoff — <ISO timestamp>

## Objective
[One sentence starting with an imperative verb.]

## Context the Subagent Needs
- [Key architectural decision, API behavior, or business rule]
- [Runtime invariant not obvious from static source]

## Already Tried — Do NOT Re-Attempt
- [Approach A]: [Exact failure reason]
- [Approach B]: [Exact failure reason]

## Files to Touch
- `path/to/file.ts` — [Exact modification]

## Hard Constraints
- [MUST NOT]: [Forbidden scope, .env, credentials, or prohibited library]

## Success Criterion
- [ ] [Verifiable command — test passes, build succeeds, HTTP 200]

## If Blocked
[Explicit fallback action — emit dead-letter record, escalate with finding.]

3. Echo & Dispatch: Embed packet directly into the subagent invocation prompt.

Pitfalls

• Raw Prefix Collisions: Never match session directories using raw startsWith(path); sibling directories like /project-staging will falsely match /project.
• Hiding Open Questions: Never bury an unanswered user question under a wall of status logs.
• Compound Objectives: Never combine multiple decoupled tasks into one outbound packet.
• Omitted Ruled-Out Paths: Subagents re-explore failed attempts unless explicitly forbidden.

Verification

• Inbound resumption surfaces any unanswered question before status text.
• Session matching strictly validates directory boundaries.
• Outbound handoff packet is written to .agents/artifacts/handoff-<timestamp>.md.
• All 7 outbound sections are populated with zero placeholder text.