Recover a session from stale tool results

Learning objective

Choose targeted re-analysis after known file changes or a fresh session with an injected summary when earlier tool results are stale.

Core idea

A resumed session remembers what tools returned during the earlier investigation. It does not turn those results into observations of the code that exists now. If a file changed after analysis, the saved conclusion can be internally consistent and still be wrong for the checkout you are about to modify.

For an architect managing an investigation, choose how much context to retain based on the validity of its evidence. When changes are known and localized, resume the useful investigation and request targeted re-analysis. When changes invalidate much of the earlier exploration, start fresh with a structured summary that preserves the task and decisions while requiring fresh inspection of the changed implementation.

The deciding factor is how much of the earlier context remains useful, not how long ago you closed the terminal.

How it works

Identify which conclusions depend on changed files

Claude Code resumption restores conversation history, including tool calls and results. Agent SDK sessions likewise persist the conversation rather than the filesystem. A transcript that contains yesterday’s read of src/auth/refresh.ts therefore preserves yesterday’s content. A successful --resume confirms access to the conversation, not the freshness of that content.

Before asking the resumed agent to act, state what changed and what that change invalidates. Name the file paths, describe the relevant behavior or interface change, and identify conclusions that need reconsideration. This gives the agent a bounded re-analysis task instead of a vague instruction to continue.

For example, changing the refresh function’s error return can invalidate caller behavior and tests even when only one implementation file changed. The scope is the evidence dependency, not the count of edited files. Conversely, unrelated formatting changes need not discard a sound analysis of the authentication contract. Establish the actual change before choosing a recovery strategy.

Resume and request targeted re-analysis

When most of the prior context is valid, use claude --resume auth-timeout-investigation or the SDK’s resume option with the captured session ID. Supply the change notice as the next user prompt. The mechanism is explicit resumption plus a targeted prompt; session restoration itself is not the re-analysis.

A change notice can be concise while still making its requirements testable:

Since the previous analysis, src/auth/refresh.ts changed: refresh errors
now return a typed failure instead of throwing. Re-read that file and
its callers in src/auth/login.ts. Recheck the timeout conclusions that
assumed exceptions. Preserve the requirement to avoid duplicate refreshes.
Run the affected tests and report which earlier conclusions still hold.

The illustrative prompt asks for fresh tool evidence, names a dependent caller, and separates a stable requirement from an invalidated assumption, without forcing rediscovery of unrelated modules. It follows Claude Code’s best-practices advice to name symptoms, likely locations, and what success looks like. If targeted inspection reveals a wider interface migration, reconsider whether the resumed history is still helping.

Start fresh with a selective summary

When the implementation changed broadly, a fresh session removes the competing obsolete observations. Anthropic also recommends a reset after you correct Claude more than twice on the same issue in one session: run /clear and start fresh with a more specific prompt that incorporates what you learned. In Claude Code, /clear starts with empty context and saves the previous session for later resumption. Starting a separate invocation without --resume or --continue also gives you a fresh conversation. In the Python Agent SDK, a query() call starts fresh unless you supply continue_conversation=True or resume.

For cross-host recovery, the Agent SDK sessions guidance recommends capturing analysis output, decisions, and file diffs as application state and passing them into a fresh session’s prompt; it describes this as often more robust than shipping transcript files between hosts. For an SDK call, pass the summary as the prompt argument without the resumption options. In Claude Code, paste the summary into the fresh conversation or pipe a summary file into print mode:

cat investigation-summary.md | claude -p "Continue from this handoff."

Here investigation-summary.md is a handoff file you prepared. Claude Code documents piping content into claude -p to supply context; the summary is an explicit input, not restored conversation history.

Include these distinct kinds of information:

• The investigation’s goal, unresolved question, and acceptance criteria.
• Stable requirements and decisions, with their reasons.
• The implementation changes and paths that need fresh inspection.
• Earlier findings that remain useful, distinguished from invalidated hypotheses.
• The next reads and verification needed before a code change is accepted.

Write the summary as a self-contained assignment, as Anthropic’s best practices do for moving from exploration to implementation: name files and interfaces, state scope, and give a verification step. Do not paste the old transcript, obsolete file bodies, or failed test output as if they still describe the working tree.

Do not confuse compaction with fresh evidence

/compact [instructions] replaces conversation history with a summary. It helps control context size, and you can focus it on relevant API changes. It does not itself re-read changed files or validate the summary’s conclusions against the checkout.

Claude Code can offer the same operation on resume. On a Pro or Max plan, resuming a session inactive for more than about an hour and over 100,000 tokens opens a dialog whose Resume from summary option runs /compact immediately. That summarizes the stale history; it is not a fresh session with a summary you selected.

/clear and /compact therefore solve different problems. Clearing gives you empty conversation context into which you supply selected facts. Compaction retains summarized history. Either choice still requires fresh tool results for claims about changed files. Likewise, forking the stale session through the mechanisms in 1.7.2 copies the stale history; a different session ID does not repair its evidence.

Key distinctions and trade-offs

Localized change versus widespread invalidation: Resume when you can name the invalidated evidence and retain the rest; start fresh when obsolete observations dominate the next step’s reasoning.

Summary versus transcript: A transcript preserves the investigation’s detailed path. A structured summary selects the goal, justified decisions, uncertainties, and required verification for the next task.

Context reduction versus evidence refresh: /compact reduces history size. A fresh Read result or test run establishes what changed code does. These operations are complementary, not interchangeable.

Targeted re-analysis depends on identifying the affected conclusions; a fresh handoff can omit a constraint the earlier conversation established. Either way, preserve reasons and acceptance criteria, and require inspection before carrying implementation claims forward.

Architecture / decision scenario

A developer-productivity agent investigated authentication timeouts. Since that analysis, one refresh function changed from throwing errors to returning typed failures. Its concurrency requirement and the surrounding API remain unchanged. The architect resumes the named investigation, identifies src/auth/refresh.ts and src/auth/login.ts, and asks for fresh reads, reconsideration of exception-based conclusions, and the affected test results. The agent can retain its useful analysis of duplicate refresh prevention.

Later, a refactor replaces the authentication interface across the service and rewrites the test harness. The saved conversation now includes obsolete call paths and several failed patches. Continuing it with a request to finish would mix those paths with the replacement design.

The architect starts a fresh session and injects a summary: prevent duplicate refreshes, preserve the externally visible timeout behavior, inspect the replacement interface, and verify the concurrency cases against the rewritten tests. The summary labels the exception-based diagnosis as invalidated and leaves its replacement as an open question. The agent inspects the replacement files before proposing an implementation.

Both choices preserve prior learning, and neither treats resumption, compaction, or forking as a substitute for re-analysis.

Common exam traps

Avoid these evidence-recovery mistakes:

• Assuming successful resumption updates prior tool results to match changed files.
• Requesting full codebase exploration after a precisely known, localized change.
• Resuming broadly invalidated history solely to avoid writing a handoff summary.
• Presenting a summary’s old implementation findings as fresh observations.
• Using /compact, Resume from summary, or a session fork as the mechanism that verifies changed code.
• Seeding the fresh session with the full earlier conversation, stale tool results included, instead of a structured summary.
• Dropping the acceptance criteria while preserving the rejected implementation details.

What to remember

Resume useful history with an explicit change notice when re-analysis can be targeted. Start fresh with a selective summary when earlier tool results are widely stale. Retain stable requirements and justified decisions, and require fresh file and test evidence before relying on implementation conclusions.

Knowledge check

References

• Anthropic, Manage sessions
• Anthropic, Work with sessions
• Anthropic, Best practices for Claude Code
• Anthropic, Python SDK reference
• Anthropic, Claude Certified Architect – Foundations Exam Guide