A coding-agent handoff should survive a fresh session

Before a coding session is compacted or handed to another agent, preserve the task's current state, the evidence behind it and the next bounded action. A summary of the conversation is useful background. A handoff should also let its reader distinguish finished work from an intention that was never executed.

Anthropic's November 2025 account of long-running agents describes both unfinished features left between sessions and later sessions declaring success too early. Its experimental harness paired incremental work with a progress file and Git history. The account is evidence for that team's design, not proof that a generic handoff template guarantees completion. ^[1]

The transferable question is more concrete: could a new session continue the task without trusting an unsupported “all tests passed” sentence?

On 3 October, Reddit user speciallight described a handoff mod carrying the goal, decisions, rejected approaches, file references and verification command into a new session. A reply emphasized saving this state outside the original transcript so another tool could use it. Both accounts promote their authors' tools; neither establishes a measured reliability or cost improvement. Their useful proposal is a portable artifact whose contents can be inspected. ^[2]

A handoff has to agree with the workspace

Preserve the state, not every turn

Take a hypothetical CSV-import fix. An agent has changed the parser and added a fixture, but the database integration test failed because the local service was unavailable. It has not yet checked whether blank optional fields survive the API response. The user authorized a draft pull request, not deployment.

A weak handoff says: “Fixed CSV import; tests mostly pass; finish and deploy.” It collapses three distinct facts into a misleading instruction. A useful handoff identifies the changed files, records the blocked integration check and preserves the publication boundary.

Our proposed structure is deliberately small:

This is a workflow proposal. It is not a standard that clients automatically load. Store it in a documented project location and explicitly tell the receiving session to read it.

Keep instructions and progress separate

Stable rules belong in the project's instruction mechanism. Temporary execution state belongs in the task note. Copying a full investigation into AGENTS.md or CLAUDE.md makes every unrelated future task inherit obsolete details.

Claude Code's documentation says project-root CLAUDE.md is re-read after compaction, while nested instructions and path-scoped rules reload when relevant files are accessed. That does not mean an arbitrary task note is automatically restored, or that every conversational detail survives. ^[3]

Use a short durable pointer where the workflow requires it: “For task continuation, read the current task's handoff before editing.” The handoff then names the relevant task document rather than claiming that the agent remembers its contents. Other clients have different resumption behavior; test the route you actually use.

The useful unit is one current note per task, with older checkpoints retained only where history is valuable. A growing pile of similarly named summaries creates another selection problem. Put the task identifier and update time inside the note, and record which earlier checkpoint it replaces.

Attach results to the files they tested

“Tests passed” is missing the command, environment and revision. A command may have run before the final edit, selected zero tests or exercised a different checkout. A handoff should make those possibilities visible without embedding a megabyte of logs.

For the CSV example, record the working directory, actual command, result, selected test count if available, and the tested revision or patch state. Link to a retained log for details. If another edit follows, say which evidence is now stale. Do not upgrade a successful unit check into an integration result.

Use explicit states: passed, failed, blocked, not run. “Blocked” means the required observation is missing, with a reason and a recovery step. It is not a softer synonym for passed. A pending process should have its tool session or job identifier recorded so the next worker can inspect it before starting another copy.

Anthropic's harness account also emphasizes using an environment initializer and checking basic functionality when a new session begins. Our adaptation is to name the smallest observation needed to establish that the handoff still describes the current workspace. ^[1]

Reconcile before continuing

A new session should inspect the current branch, diff and relevant files before executing the next action. This is a read-only reconciliation, not permission to discard changes. If the handoff says the fixture is committed but it exists only as an untracked file, preserve it and correct the note.

Conversation continuity and file continuity can diverge. VS Code documents that a forked chat has separate conversation history, but its code is isolated only when a different folder or worktree is used. Some Copilot session forks continue in the same worktree. A fresh-looking conversation therefore does not establish a fresh filesystem. ^[4]

That distinction matters when two sessions can write. In the example, the successor should confirm that the previous worker has stopped editing the parser, or establish explicit ownership of the next change. A useful handoff names active workers and their paths; it does not assume that a summary ended the original process.

Our application-state analysis^[5] addresses shared databases and workers. A handoff adds the human-readable record of which instance, fixture and branch produced the current evidence.

Preserve rejected paths and unresolved decisions

One sentence about a failed approach can prevent a full repeat investigation. Write the reason, not merely “tried option B.” For example: “A parser-wide trim removed significant whitespace from quoted fields; rejected by fixture quoted-spaces.csv.” The successor can inspect that fixture rather than taking the note on faith.

Separate an unresolved product decision from an implementation blocker. Whether an empty string should become null is a contract question. A stopped database is an environment problem. The latter may be recoverable autonomously; the former needs an authoritative requirement or a decision from its owner.

Do not copy tokens, cookies or private data into the note. Preserve the names of required connections and the safe path to obtain access. Do not translate yesterday's limited approval into unrestricted authority merely to make the handoff shorter.

Try one handoff before relying on it

For the next long task, stop at a natural boundary and write the note. Open a fresh session with the normal project instructions and that note, then ask it to identify the current state and next action without editing. Compare its answer with the actual workspace.

If it cannot tell whether the integration test ran, fix the evidence field. If it chooses the wrong branch, fix the workspace field. The acceptance test for your handoff is whether continuation begins from the right state; the number of paragraphs preserved is incidental.