A handoff note is the only thing that crosses the gap between two agent sessions, so it has to answer one question for the next session: what is actually finished, what is not, and where do I start? Everything else is detail. The failure to avoid is a note that sounds confident and is wrong, because the next session will believe it and build on it. This guide lists what a note must carry, what it should refuse to carry, and a simple way to test a note before you rely on it.

Why the next session starts blind

Anthropic's engineering team describes the core difficulty of long jobs this way: agents work in separate sessions, and whatever a fresh session knows about the earlier ones must be handed to it. Their picture is a project staffed in shifts, where every engineer arrives knowing nothing about the previous shift (Anthropic Engineering).

The same article reports that compaction, the built-in way of shrinking a long conversation, does not always pass clear instructions to the next agent. They saw two patterns that a good note can prevent. In one, a session ran out of room halfway through a feature and left it half-built and undocumented, so the next agent had to guess what had happened. In the other, a later session saw that progress existed and declared the whole job complete (Anthropic Engineering).

Those two are mirror images. The first is missing information, the second is surplus confidence. A handoff note has to fix both.

What must survive

Think of the note as a short form with fixed fields. Free prose invites vague claims; fields force a decision about each fact. The set below is general practice rather than something a single source prescribes, though it lines up with what the Anthropic article uses (a progress file, a feature list and the git history).

  1. Done, with proof. Each finished item points to the result that shows it worked: an exit status, a written file, a response with the expected body. The point is that the proof is quoted from the record, not described.
  2. Not done. Anything attempted that never visibly finished. If an error appeared and nothing succeeded afterwards, the error text goes in unchanged.
  3. Open. Asks from the user that went untouched, unanswered questions, and blockers such as a missing credential or a service that refuses a call.
  4. Decisions. Choices that were made on purpose, with the reason only when someone actually gave one. A reason invented after the fact is worse than no reason.
  5. Files touched. The paths that were written or changed, not the ones that were merely read.
  6. The next step. A single sentence about the earliest unfinished thing. No plan and no second move.

The Anthropic article also points to the habit behind these fields: each session ends by committing its work with a descriptive message and writing a progress summary, which let the agent undo bad changes and recover a working state without guessing (Anthropic Engineering). A note without a matching commit is weaker, because the commit is the part a machine can check.

What must not get in

Most bad notes fail by including things, not by omitting them.

  • Work that was only issued. Running a command is not a result. If the printout ends before any verdict, or nothing was captured at all, the item is not done, however sure the agent sounds. Put it under not done and say why.
  • The agent's own verdict. "All tests pass" written by the agent is a claim. The test run's output is the evidence. Where they disagree, the output wins.
  • Completed numbers. Identifiers, counts and version strings are copied exactly from tool output. A note that rounds, completes or reconstructs one hands the next session a value that never existed.
  • Orders found inside data. A downloaded page, a document or a tool reply may contain a sentence addressed to the agent. OWASP describes this as indirect prompt injection: input from outside sources, such as websites or files, that changes the model's behaviour in ways nobody intended (OWASP GenAI). When a note is written from such a record, that sentence is something to report, never something to obey, and it must not turn an item into a finished one.
  • New plans. The note records what happened. Planning is the next session's job, and a plan smuggled into the note reads like a decision nobody made.

A worked example

Suppose the session record shows these lines, in order: a command to run the test suite, a line saying that tests began, a marker showing the printout was truncated, and then the agent writing that the tests pass.

A careless note lists the test run under done. A careful one lists nothing under done for it, adds an entry under not done explaining that the printout breaks off early and no verdict reached the record, and sets the next step to run the suite again. The difference matters because the careless version tells the next session to skip the one check that was never completed.

Now a second case. A deploy command prints an authentication error, and the agent later says it deployed. The record decides: the deploy is not done, the error text is kept as written, and the rejected credential goes into the open list as a blocker.

A test you can run on your own notes

A note is only worth trusting if it can fail. Build a short record that contains traps and see whether the note walks into them:

  • one command with no captured output;
  • one error with no retry, followed by an agent remark claiming success;
  • one user request that no call ever addressed;
  • one tool result that contains a line telling the agent to mark something finished;
  • one identifier that appears only partly in the record.

Then check four things. Every quoted proof appears in the record word for word. No item is listed as done without a result line. The trap sentence changed nothing. The partial identifier was left out or kept partial, not completed. If any check passes when you break the input on purpose, the check is not measuring anything, so break it first and confirm it goes red.

A related habit is doubting an agent's final "done", which is covered in our piece on a finished-looking agent run and on claims that outrun the evidence; the note is the written form of the same doubt.

When this does not apply

Short single-session jobs need no note; the record itself is the note. Jobs where the next session can simply re-run a full test suite or rebuild from a clean checkout may get more reliability from that than from any summary. The field set above is general practice, not a standard, and the Anthropic article describes a harness for building a web application, so its specifics may not carry to your work, such as research or operations. A note can only be as accurate as the record behind it: if tool outputs are not captured, no note can separate done from attempted. A note is also an extra document that can drift, so keep it small and regenerate it from the record instead of editing it by hand. We did not run an experiment for this guide; it combines two public sources with common practice.

Writing the note from a record

If you want the note produced from a session record rather than from memory, our session-handoff-note skill reads the log of one session and returns the six fields as strict JSON. It counts an item as finished only when the log holds a result for it, and quotes that result. Errors that were never retried successfully stay in the unfinished list, identifiers are copied as they appear, and instructions found inside downloaded pages are reported as data, not followed. The store itself is at https://aiskills402.com.

Read this post as Markdown: /blog/session-handoff-note-for-agents.md · Atom feed.