Session State, Resumption, and Forking

Estimated time: 3 minutes

Two mechanisms, easy to reach for backwards:

  • --resume <session-name> continues a specific, named prior conversation.
  • fork_session creates independent branches from a shared analysis baseline — the right tool when you want to compare two different strategies (two refactoring approaches, two testing approaches) against one piece of shared upstream analysis, not when you're simply picking a conversation back up.

The discriminator is staleness. Resume when the prior context is mostly still valid. Start fresh — with a structured summary injected into the new session — when tool results have gone stale: files were modified, dependencies were upgraded, the build changed. The model has no way to detect on its own that context it's holding is now out of date; stale tool results don't just fail to help, they actively mislead, because the model treats them as current unless told otherwise.

Resume versus fork decision tree, branching first on whether prior context is still valid, then on whether the task is comparing multiple strategies against a shared baseline Staleness is the first branch, not "is there a session to resume." Only once context is confirmed current does the second question — comparing strategies against one shared baseline — decide between resume and fork_session.

The trap that shows up constantly: "just resume, it has all the context" offered as the answer in a scenario that explicitly mentions modified files or a changed build. Having more context isn't the same as having current context. The fix, when files changed, isn't just resuming — it's resuming while explicitly naming which files changed, or starting fresh with an injected summary of what's still true.