Coding Agent to Developer Handoff Checkpoint: Worktree Evidence, Open Assumptions, and Continuation Confirmation

When a coding Agent says "the code is basically done, just one test left", the developer still does not know which commit that sentence maps to, which untracked files exist, or which commands actually ran, nor whether the Agent's assumptions have already gone stale. Editing directly might overwrite unsaved changes; handing off to another Agent might repeat a migration, file generation, or external write. The goal of the handoff point is not to archive the full chat transcript, but to freeze "the currently continuable state" into an engineering artifact that can be independently verified.

This differs from Long-Running Agent Workflows: the latter lets the runtime auto-resume steps, while this article handles the moment the Agent hands unfinished coding responsibility to a specific developer. It also does not replace the business approval of Human Review Queues for Agents; the recipient confirms the work state and next-step responsibility, not approval of a high-risk operation.

Freeze the handoff.v1 versioned contract

handoff.v1 records at least taskId, checkpointGeneration, producerRunId, repositoryId, baseCommit, headCommit, worktreeTree, indexTree, a digest of the untracked file list, patch and object-bundle digests, path-lease references, last edit time, completed claims, open assumptions, unexecuted commands, known failures, suggested next step, and forbidden actions. Each piece of evidence is content-digest addressed, and the whole manifest is hashed into a checkpointDigest; any field change yields a new generation and cannot overwrite the old record.

schema: handoff.v1
taskId: DEV-1842
generation: 7
repository: {base: 91b2..., head: a771..., worktreeTree: 8e43...}
artifacts:
  patch: {uri: artifact:patch/4c1f..., sha256: 4c1f...}
  gitBundle: {uri: artifact:bundle/920a..., sha256: 920a...}
claims:
  - {id: AC-3, state: evidenced, receipt: test/72d9...}
  - {id: AC-4, state: open, reason: needs_product_decision}
next: {action: choose_null_semantics, forbidden: [merge, deploy]}

worktreeTree cannot capture only HEAD. The staging area, unstaged files, renames, deletions, the executable bit, symlinks, and untracked files must all enter the snapshot; secrets and build caches excluded by .gitignore are only registered as "excluded rule and reason" and must not be packaged. You can read HEAD into a temporary index, add the permitted paths, and use git write-tree to obtain the tree object, avoiding changes to the developer's real index. The private checkpoint ref uses git update-ref <ref> <new> <old> for a compare-and-swap, rejecting a late Agent's overwrite.

A Git bundle can carry reachable objects and refs, but it does not automatically save an arbitrary dirty worktree, so the manifest additionally needs an independent patch, an untracked-file archive, and binary digests. Run git bundle verify in a temporary clean clone first, then apply the patch and check the final tree; unrecoverable Git LFS objects, submodule commits, or externally generated sources must be listed as blockers, not excused with "available locally". The entity/activity/agent relationships of W3C PROV can express who produced which artifact based on which repository state, but real acceptance still relies on digests and replay results.

Deliver only evidenced completeness

Every "completed" item must reference an acceptance claim and verification receipt. Command evidence is provided by Coding Agent Command Transcript Evidence and Redaction; the handoff manifest only references the receipt ID, the covered tree digest, and the conclusion, without copying logs that may contain sensitive data. Failure investigation references the bundle ID from Coding Agent Debug Reproduction Bundle, so the handoff protocol does not reinvent environment collection.

Open items must be decidable entries, not "a few edge cases remain". Each registers an owner, two or three mutually exclusive options, existing evidence, blocking claims, a latest decision time, and a safe default action. When the Agent is unsure whether a field is empty or missing, it must state explicitly "undecided, migration forbidden", rather than choosing an implementation and then softening the risk in the summary. Agent Failure Recovery Order still decides whether to retry after failure; the handoff only faithfully freezes the attempts that occurred and the remaining responsibility.

The acceptance action uses a separate handoff-accept.v1: the developer submits their identity, the checkpointDigest they read, the accepted generation, the chosen next action, and the new responsibility deadline. The server accepts only when the task's current generation matches exactly; if the Agent writes files while the developer is reading, the old confirmation returns STALE_CHECKPOINT. The path write set still references the parallel-work protocol's lease; a handoff cannot silently expand ownership, nor use "human takeover" as an excuse to bypass the permission boundaries in Agent Delegation Contracts.

Prove the handoff package is recoverable with fault injection

Testing must not stop at schema validation. First let the Agent modify a tracked file, add an untracked fixture, delete a file, and change the executable bit, then secretly edit one line after generating the manifest; the acceptance must fail due to a tree-digest mismatch. Then separately inject a missing bundle object, a corrupted patch, an unreachable submodule, a missing LFS object, a test secret hit in the archive, and a developer confirming with an old generation; all expected outcomes are blocks that name the exact artifact.

The recovery drill starts from an empty directory with minimal credentials, rebuilding the worktree using only the sources declared in the handoff manifest, re-running the permitted verification commands, and having a different executor judge the next step. If it can only continue by accessing the Agent's chat history, local absolute paths, or unregistered caches, the checkpoint is incomplete. Run an additional late-write drill: after the developer has accepted generation 7, an old Agent attempts to publish a revision of generation 6, and both update-ref and the task state machine must reject it.

Quantitative acceptance gates and reversible rollout

Before forcing a takeover, set hard gates: change-path coverage within the permitted scope and untracked-file digest coverage at 100%; baseCommit, submodules, and key artifacts all reachable; patch, bundle, and manifest digest verification errors at 0; secret-scan high-severity hits at 0; every completed claim has a receipt bound to the current worktreeTree; every open claim has an owner and a safe default action; clean-clone recovery success rate 100%, with p95 recovery to the first verification command under 10 minutes. When randomly sampling 20 checkpoints, unexplained diffs must be 0, and the interception rate of old-generation acceptance and late writes must be 100%.

Rollout first generates handoff.v1 for the existing pause flow in shadow mode, without changing ownership, and compares manual reconstruction results for two consecutive weeks; then enables explicit accept for only 10% of handoffs on low-risk repositories, and expands tier by tier once the thresholds above are met. The toggle is controlled per repository and contract version; old clients that do not recognize v1 must use the old flow and cannot treat unknown fields as confirmed.

On rollback, disable mandatory accept, stop creating new generations, and restore unaccepted tasks to the original manual queue; accepted responsibility records stay immutable and the audit chain cannot be deleted by rollback. Checkpoint refs and artifacts are cleaned up on a delayed retention schedule, and the recovery tool keeps both the current and previous contract resolvers. What is retracted is the execution gate, not the handoff evidence; developers can still accurately answer which state they took over, what they accepted, and which work was never completed.