# Agentic Workflow - HANDOFF with Full Context Transfer

**Last Updated:** November 20, 2025

## Decision: HANDOFF Mode for Long Sessions

Use **HANDOFF (mode: "new")** to:
- Move to a fresh new session when current session gets too long
- **Preserve ALL context** from previous session
- Continue work without token limit constraints
- Start with clean slate but full awareness

## Use Case

```
Long Conversation in Session A (70+ turns)
        ↓ (approaching token limit)
Session gets too long
        ↓
Execute HANDOFF:
  session({ mode: "new", agent: "build", text: "Continue from where we left off. Full context from previous session preserved." })
        ↓
Fresh Session B starts
- All previous conversation context available
- No token baggage
- Continue work seamlessly
```

## How It Works

1. **Session A**: Work progresses normally
2. **Detection**: Session approaching token limits (70+ turns)
3. **HANDOFF Trigger**: `session({ mode: "new", agent: "build", text: "Continue..." })`
4. **Session B**: Starts with:
   - ✅ Full context from Session A
   - ✅ Fresh token budget
   - ✅ Clean execution environment
   - ✅ All conversation history visible

## Key Difference from COMPRESS Mode

| Feature | HANDOFF (mode: "new") | COMPRESS (mode: "compact") |
|---------|----------------------|---------------------------|
| New Session | ✅ Yes | ❌ No |
| Full Context | ✅ Yes | ✅ Yes (compressed) |
| Token Refresh | ✅ Yes | ✅ Yes |
| Best For | Long work sessions | Token optimization |

## Implementation

```typescript
// In Session A, when reaching ~70 turns or token limit
session({
  mode: "new",
  agent: "build",  // or any agent
  text: "Continue working on the implementation. Full context from previous session is available."
})

// Session B starts fresh
// - Has access to all previous conversation
// - New token budget
// - Continue seamlessly
```

## When to Use HANDOFF

✅ Session has 70+ turns
✅ Approaching token limits
✅ Need to refresh conversation state
✅ Want clean execution environment
✅ But need to preserve all context

## Configuration

Session tool enabled in both agents:
```yaml
tools:
  session: true
```

## Workflow Example

### Session A (Reaching Limit)
1. Hour 1: Research phase (20 turns)
2. Hour 2: Design phase (25 turns)
3. Hour 3: Implementation starts (25 turns)
4. Status: ~70 turns, approaching limit

### HANDOFF Trigger
```typescript
session({
  mode: "new",
  agent: "build",
  text: "Continue implementation. All previous context (research, design, progress) is preserved in conversation history."
})
```

### Session B (Fresh Start)
1. Receives: Full conversation history + new message
2. Starts: Fresh token budget
3. Continues: Implementation work
4. Can go: Another 70+ turns before next HANDOFF

## Benefits

1. **No Context Loss**: All previous conversation preserved
2. **No Token Waste**: Fresh budget for new session
3. **Seamless Continuation**: Pick up exactly where you left off
4. **Scalable**: Can chain multiple sessions for long projects
5. **Clean Execution**: Each session gets optimal performance

## Best Practices

1. **Monitor Token Usage**: Track conversation length
2. **Trigger at ~70 turns**: Before hitting hard limits
3. **Summarize in HANDOFF message**: Reference key decisions
4. **All context stays**: Don't lose any information
5. **Chain sessions**: Multiple HANDOFFs for very long projects