The problem
A debugging session from two hours ago investigated an application bug and incorrectly concluded that the root cause was inside the authentication module. The following morning, an engineer resumes that session using --resume to continue the task — and the agent ingests the entire flawed premise as ground truth because nothing in the session state was flagged as obsolete. The entire morning is wasted reversing an assumption that should have been discarded hours ago.
Resuming a session is never neutral. It pulls back every accumulated token, including stale tool observations that have lost validity and discarded hypotheses that have already been refuted. The architectural decision here is: when is accumulated session history still an asset, and when is it dead weight that must be replaced by an explicit structured summary?
The core architectural concept
--resume <session-name> restores a previous session with its complete conversation history intact. This is optimal when accumulated context remains completely valid — the session was merely paused, not invalidated, and resuming avoids re-establishing established facts. However, when intermediate tool observations become stale — files were modified, a hypothesis was disproven, an architectural decision was reversed — reloading that historical context reintroduces the hallucination. In such cases, the correct architectural choice is initializing a new session seeded with an explicit structured summary: a compact record of verified facts, refuted hypotheses with reasons, and open items. This drastically reduces token consumption and, crucially, purges stale premises.
fork_session solves a different architectural challenge: exploring competing implementation paths without cross-contaminating the primary reasoning branch. If two candidate approaches must be benchmarked — optimizing an existing database query versus refactoring the data access layer — forking the session enables each branch to execute in isolation without speculative reasoning polluting the alternative branch. Without session forking, the main session becomes cluttered with dead ends from both approaches.
The third pillar is how structured errors and partial results traverse session and subagent boundaries. A subagent that fails mid-task must never terminate silently — it must return a structured error payload detailing what was attempted, where failure occurred, and which facts were verified prior to failure. A partial result is actionable telemetry: "successfully verified X and Y, but failed at Z because tool W timed out." A subagent emitting only binary success/failure codes forces downstream orchestrators to repeat diagnostics from scratch.
The antipattern to avoid is treating --resume as the universal default purely out of convenience. Convenience is not an architectural criterion — context validity is. A session from two weeks ago almost always contains more dead weight than signal; a hand-crafted, 30-line structured summary serves the next iteration far better than blindly resuming stale state.
Put it into practice
In this lesson's lab, you will implement a session lifecycle engine in Python: given session age and invalidation flags, it decides whether to resume an active session or seed a fresh session with a structured summary, paired with a subagent error-handling contract that propagates partial execution progress across boundaries.