ADR-004: Fresh Agent Sessions (No --resume)
Status
Accepted
Context
Claude Code CLI supports --resume to continue a previous conversation. We must decide whether agents resume or start fresh each iteration.
Decision
Use fresh sessions every time. Each agent invocation is claude -p <prompt> with no --resume flag.
Rationale
- Prompt injection is our primary control mechanism — we assemble a new prompt each iteration with current messages, beads state, and context.
--resumewould carry stale context and make it harder to steer agents.- Fresh sessions give us a clean slate with precise control over what the agent sees.
- Session sequence number (
session_seq) tracks iterations for logging.
Tradeoffs
| Aspect | Fresh sessions | --resume |
|---|---|---|
| Context control | Full | Partial (can't unsay things) |
| Token cost | Higher (re-inject system prompt) | Lower |
| Simplicity | Simpler orchestrator logic | More complex state tracking |
| Failure recovery | Clean restart | Must handle corrupt resume state |
Consequences
- Every prompt must be self-contained (all context re-injected).
- The 5-stage prompt pipeline (system + user prompt + messages + beads + session context) runs every iteration.
session_seqincrements per spawn, used for log archival naming.- No need to manage conversation IDs or resume tokens.