How to Verify AI Coding Agent Work Before Handoff

An AI coding agent handoff is complete only when another person can understand, verify, and safely accept the returned work. A patch, passing command, pull request, specification, or recording is evidence, but it is not the whole acceptance decision.

This tutorial teaches one end-to-end task: build a reproducible acceptance packet for a bounded coding-agent change. The worked example used a disposable local Git repository, an uncommitted two-file diff, repository-owned tests, positive and negative CLI checks, and a restore-and-reapply drill. The process also applies to editor agents, structured-spec tools, and managed cloud sessions.

Product controls vary. Cursor documents both its CLI and background-agent web and mobile workflow. Kiro documents Specs and steering. Devin documents guidance on when to use Devin and its computer-use environment. Pi documents its runtime, security boundary, and extensions. Check the current documentation for the mode you actually use.

You will produce an acceptance packet containing a bounded task contract, an execution-boundary record, a baseline, an event ledger, a complete change inventory, final test output, a user-visible workflow check, a recovery drill, and an explicit accept-or-reject decision. The packet lets another maintainer reproduce the critical checks without reading the entire agent conversation.

The example acceptance condition is concrete: all three verification fields set to true must print ACCEPTED and exit 0; setting rollback_verified to false must print REJECTED: missing rollback verification and exit 2. Malformed JSON must remain rejected with INVALID_PACKET and exit 1.

Prepare a reversible repository task that changes user-visible behavior, a clean baseline or an explicit inventory of pre-existing changes, repository-owned build and test instructions, and a low-risk environment for any external-system check. Use a reviewer who did not author the agent prompt.

Do not start with production credentials, irreversible data changes, or an architecture decision whose owner is unavailable. Record the selected execution mode and consult its current vendor documentation. For example, Kiro's steering documentation describes project guidance, while Pi's security documentation explains why the launching environment matters.

1. Write the task contract — agent-handoff-01-scope. State the affected user, behavior that must become true, behavior that must remain unchanged, allowed and forbidden paths, required verification, and delivery artifact. In the real run, the delivery was one uncommitted diff limited to src/check-handoff.mjs and test/check-handoff.test.mjs. Expected result: the final diff can be judged against explicit pass/fail conditions.

1. Record the execution boundary — agent-handoff-02-boundary. Capture the execution mode, repository access, operating-system permissions, loaded rules or extensions, connected credentials, external systems, and approval requirements. The real run used an ephemeral non-interactive Codex CLI session with workspace-write, no commit permission, no instructed network use, and no allowed external writes. Expected result: the maintainer knows what the agent could read, change, run, and communicate with.

1. Capture the baseline — agent-handoff-03-baseline. Record the source revision, branch, tracked and untracked changes, lockfile state, relevant tests, and active fixtures or services. The real run began clean on main at revision acacc338f8a12801d6104f33746d5184a517e237; two baseline tests passed. Expected result: later changes can be attributed to this task instead of earlier work.

1. Observe meaningful events — agent-handoff-04-observe. Record clarifying questions, plans, files read and changed, commands, approvals, external writes, tests, failures, retries, and recovery. In the real run, an initial implementation caused an existing negative test to omit the new field, so its fixture was adjusted to isolate the original condition. Expected result: the handoff explains how the result was produced without dumping the full transcript.

1. Inspect the complete change set — agent-handoff-05-inspect. Inventory tracked, untracked, generated, dependency, configuration, schema, migration, deletion, test, and documentation changes. The real run reported two changed files, 16 insertions, no forbidden paths, no whitespace errors, and patch SHA-256 ccafb202c9ff65f529a96d893d277a7a42e06300ec520233512d6707fdde77eb. Expected result: every changed artifact is required, explicitly accepted, or removed.

1. Run repository-owned verification — agent-handoff-06-tests. Use the repository's documented commands and tie their output to the inspected source state. In the example, the repository command and static diff check were:

The final reapplied patch passed all three tests, and the diff check exited 0. Expected result: reproducible command output is attached to the exact final patch rather than to an earlier state.

1. Verify the user-visible workflow — agent-handoff-07-user-flow. Run the closest practical path affected by the change and include both success and failure cases. The real CLI run produced ACCEPTED with exit 0 when all fields were true, REJECTED: missing rollback verification with exit 2 when rollback verification was false, and INVALID_PACKET with exit 1 for malformed JSON. Expected result: the promised behavior is visible in the intended interface.

1. Test rejection and recovery — agent-handoff-08-recover. Revert only the scoped change, confirm baseline behavior and tests, then reapply the exact patch and repeat verification. The real drill restored a clean tree with two passing tests, reapplied the patch, and returned to three passing tests without touching unrelated paths. Expected result: the team has observed a safe rollback and a reproducible forward application.

1. Make the acceptance decision — agent-handoff-09-decide. Summarize whether the user-visible requirement became true, existing behavior remained true, every artifact is understood, repository checks passed, external writes were controlled, and recovery worked. Record uncertainty instead of translating it into a pass. The real record accepted the uncommitted change while retaining one risk: workspace-write constrained edits but did not prove a repository-only read boundary. Expected result: another maintainer can explain and reproduce the decision.

Checkpoint one: compare every changed path and behavior against agent-handoff-01-scope. The example changed only the two allowed paths, preserved malformed-input handling, and added the missing rollback rejection. Any unexplained file is a failure until it is understood or removed.

Checkpoint two: bind the final test output and workflow outputs to the same patch digest. The example's final test record and recovery record both identify patch SHA-256 ccafb202c9ff65f529a96d893d277a7a42e06300ec520233512d6707fdde77eb.

Checkpoint three: reproduce the negative path. A false rollback field must exit 2 with the specified rejection message; a happy-path result alone cannot establish the acceptance condition.

Checkpoint four: restore and reapply the change without touching unrelated work. The baseline should return before reapplication, and the final tests should pass again afterward.

• The agent changed unrelated files. The task boundary or permissions were too broad. Stop, inspect the complete inventory, separate required changes from scope drift, and retry with narrower allowed paths.

• Tests pass but the feature is wrong. The suite does not cover the actual acceptance condition. Add or run the user-visible positive and negative checks, then repair the owning contract instead of relying on a passing aggregate.

• A background task cannot be reproduced locally. Material environment details are missing. Record its source revision, dependencies, commands, permissions, and external services; treat the result as unverified until it can be independently checked.

• A project extension or hook changes behavior unexpectedly. The execution boundary did not account for loaded code. Disable the untrusted resource, return to the recorded baseline, inspect its source and dependencies, and rerun the task.

• Recovery touches unrelated work. The baseline or source-control boundary was inadequate. Restore the unrelated work, isolate the task, and repeat the drill from a clean or explicitly inventoried state.

This process does not establish a universal agent-quality ranking, prove that unrelated regressions are absent, or replace security review for credentials and legal review for data handling. Managed environments can differ by organization policy and execution mode. Vendor controls, commands, models, plans, and interfaces may change; verify them in current official documentation.

A workspace-write sandbox limits edits but does not by itself prove a repository-only read boundary. Treat confidentiality, external integrations, and project-local extensions as separate risks. Next, store the acceptance packet with the patch or pull request so the next maintainer can rerun the decisive checks.