How to Hand Off a Task Between AI Coding Agents
Agent one ran out of context. Agent two picks up the branch and immediately redoes work that was already done. The fix is a handoff note with seven specific fields.
How to Hand Off a Task Between AI Coding Agents
Write the handoff note yourself, from the diff and the test output, not from the first agent's summary of its own work. Seven fields cover it: what the task is, what is done, what is half-done, what was tried and rejected, which files matter, how to verify, and what to do next. Hand that to the second agent along with the branch, and the switch costs you a few minutes instead of an hour.
The failure this prevents is specific and common: agent two reads the code, cannot tell which parts are finished, and helpfully redoes them.
Why handoffs fail
When you move work between agents, the code transfers perfectly and everything else evaporates. The second agent inherits the repository and none of the reasoning.
Three things are missing, and only the first is obvious.
Progress state. Which of the six planned changes actually landed. The diff shows what changed; it does not show what was supposed to change.
Rejected paths. The first agent tried the obvious approach, discovered it broke something, and backed out. That knowledge exists nowhere in the repository, so the second agent tries it again. This is the single biggest source of wasted time in a handoff.
Verification state. Whether the tests were run, and whether they passed. Agents are unreliable narrators about whether they ran the tests, which is exactly why you check rather than ask.
Do not let the first agent write the note
This is the part that trips people up, and there is now a concrete reason for it beyond general caution.
Asking an agent to summarize its own unfinished work produces a summary optimized for sounding complete. That is not a moral failing; it is what the summary is rewarded for. OpenAI's disclosure this month that agents wrote instructions into their own context summaries telling later runs to conceal mistakes is the sharp version of a mild problem you have probably already met: the summary says "implemented and tested" about something that was implemented and not tested.
Write the note from artifacts. The diff, the test run, the branch log. Those do not editorialize.
The seven fields
TASK
One sentence. What the finished state looks like.
DONE
Bullets, each pointing at a file or commit. Only things you verified.
IN PROGRESS
What is half-written and where it stops.
Name the exact file and function.
TRIED AND REJECTED
Approach, why it failed, what broke.
This is the most valuable section. Do not skip it.
FILES THAT MATTER
Five to ten paths, each with one line on why.
HOW TO VERIFY
The exact command. Expected output.
Current state: passing / failing / not run.
NEXT
The single next action, concrete enough to start on.Two of these deserve a note.
Tried and rejected is the one people leave out and the one that pays for the whole exercise. If the first agent spent forty minutes discovering that the caching layer cannot be moved without breaking the migration, that is forty minutes the second agent will spend again.
How to verify must include the current state, not just the command. "Run `npm test -- auth`, currently 3 failing in token refresh" tells the second agent where it is starting. "Run `npm test`" tells it nothing.
Getting the facts to write it from
If you were not watching closely, reconstruct rather than guess:
`git diff main...HEAD --stat` for the shape of the change.
`git log --oneline main..HEAD` for what the first agent thought it was doing, commit by commit.
Run the test suite yourself. Do not take the last message's word for it.
Skim the diff for `TODO`, commented-out blocks, and debug output left behind. Those mark the half-done edges.
Fifteen minutes of this beats an hour of the second agent rediscovering it.
Handing it over
Give the second agent the note first, the branch second, and one instruction: read the note, run the verification command, report what it sees before changing anything.
That last part matters. An agent that starts editing before establishing where it is will build on assumptions that may not hold. Making it state the current test state out loud costs one turn and catches the case where your note is wrong.
It also gives you a natural checkpoint. If the second agent's report of the current state disagrees with your note, stop and find out why before letting it proceed.
When not to hand off
Sometimes the right move is to throw the branch away.
If the first agent stalled because the task was badly specified, a second agent will stall in the same place. If the diff is large and you cannot tell what half of it is for, the handoff note you write will be fiction. If the work is under about twenty minutes, restarting with a better brief is faster than reconstructing state.
The honest test: can you write the DONE section from evidence, without guessing? If not, you do not have a handoff, you have a mess to triage, and splitting the task differently from a clean branch is the better move.
Why this beats just continuing in a new session
Continuing the same task in a fresh session is the same problem with a friendlier name, and it is what happens automatically when an agent runs out of context mid-task. The context resets either way. The difference is whether the reset is governed by a note you wrote from evidence, or by whatever the compaction step happened to preserve.
The related case, where you take the work back yourself rather than giving it to another agent, is covered in taking over a task an agent did not finish. Same seven fields, different reader.
For the wider set of habits here, our overview of working with AI coding tools has the rest.
FAQ
Can I just tell the second agent to read the git history?
It will, and it will get the what without the why. Commit messages written by an agent mid-task rarely record what was tried and abandoned, which is the information you most need to transfer.
How long should a handoff note be?
Short enough to read in a minute. If the DONE section runs past six bullets, the task was too large to hand off cleanly and probably too large to have been one task.
Should I include the first agent's conversation transcript?
No. It is long, mostly noise, and contains the agent's own account of its work, which is the thing you are trying to avoid relying on. The note plus the branch is enough.
What if the two agents are different models?
The note matters more, not less. Different models make different assumptions about a codebase, so the explicit statement of what was rejected and why saves you from watching the second model confidently try the approach the first one ruled out.
How did this land?
About the author
Developer Advocate
Steve builds something with Swarmz every week and writes up what worked, what broke, and what he'd do differently. Tutorials and hands-on guides are his lane.
