An AI agent handoff should preserve the current goal, accepted decisions and their reasons, source evidence, exact artifact versions, unresolved questions, permission boundaries, and the next action with an owner. Test it in a fresh session: the receiving agent should recover those facts from the saved record without being coached through the previous conversation.
The same checklist applies when you reopen one AI tool or move work between Claude Code, Codex, Cursor, and another client. Whether a particular setup transfers the record successfully is something to test. A connected tool alone does not prove that the next agent received the right context.
A copyable AI agent handoff template
Store the handoff where the receiving agent has authorized access. Use stable links and version references. For each field, include the source or write “unknown.”
- Goal and scope: What outcome are we pursuing? What is explicitly excluded?
- Current state: What is proposed, in progress, completed, checked, accepted, or blocked? Keep these states separate.
- Decision of record: What was chosen, by whom, and when? Link the recorded decision.
- Reason and tradeoff: Why was that option chosen? Which rejected alternative matters for the next step? What change would justify reconsidering it?
- Artifacts: Which file, document revision, commit, or deployment is the current working version? Which older versions have been superseded?
- Evidence: What supports the current claims? Identify the check, result, timestamp, and version checked. Include failures and missing checks.
- Authority: What actions are allowed, which require approval, and where is that authorization recorded? Include scope and expiry if applicable.
- Open questions: What remains unresolved? Name the decision owner and explain which work depends on the answer.
- Next action: What is the smallest useful next step, who owns it, and what would count as completion?
- Freshness: When was this handoff updated, by whom, and what must be rechecked before action?
Keep the summary brief and let links carry the detail. Do not copy credentials or unrelated private conversations into a shared record.
For important technical choices, a separate decision record can carry the rationale. Michael Nygard's original architecture decision record format includes context, decision, status, and consequences. It also preserves superseded decisions with a reference to their replacements. That history helps the next agent understand why a choice changed.
A filled handoff example
This fictional example describes a support-documentation change. It is not an OrgX customer result or benchmark.
Goal and scope: Update the public setup guide for a renamed configuration field. Changing application behavior is outside scope.
State: The revised guide is drafted and its example has been checked locally. Publication is pending.
Decision: Keep the old field name in the migration note. The documentation owner accepted that approach because existing installations may still use it. The decision record links to the compatibility requirement.
Artifacts: Guide revision v4 and the associated example file at the recorded commit. Revision v3 is superseded.
Evidence: The example runs with the new field name. The migration note has been checked against the release documentation. The old-version installation path has not been rerun.
Authority: The next agent may inspect the guide and prepare corrections. Publishing requires the documentation owner's approval for the final revision. The decision to retain the migration note is not publication approval.
Open question: Does the old-version installation path need another test before release? The documentation owner decides.
Next action: Inspect the compatibility source, propose the missing test if needed, and return the final revision for approval.
Freshness and sources: Updated September 30, 2026, at 15:00 UTC. Attach the decision record, guide revision, test result, and authorization reference. Recheck the current release documentation before making changes.
The receiving agent has enough information to continue usefully. It should not infer permission to publish from the fact that someone accepted a wording decision.
Test the handoff in a fresh session
Run this test before relying on a handoff for consequential work. Use read-only access for the test itself.
- Write an answer key. Record the decision, reason, owner, artifact version, unresolved issue, and permitted next action. Include source references.
- Save the handoff. Verify that the record exists outside the current conversation and that the receiving client can access it.
- Open a fresh session. Start with the project or initiative identifier and the normal retrieval instructions. Do not paste the answer key or the old chat into the new session.
- Ask for recovery. Have the agent explain what was decided, why, who owns it, which version is current, what remains unresolved, and what it may do next. Require a source for each answer.
- Compare against the key. Mark each field correct, incorrect, or missing. Treat unsupported guesses as failures, even when they happen to match.
- Repair the failure. Fix the record, retrieval path, or access problem, then repeat with another fresh session.
A pass supports that specific test. Record the source client, destination client, date, and setup. Repeating the same pair does not establish parity across other clients, workspaces, permissions, or artifact types.
If a check fails, preserve the failure in the test result. A decision that survives while its rationale disappears is a partial handoff. An inaccessible artifact is still inaccessible even if the summary names it correctly.
Keep guidance separate from enforceable permission
Project instructions help an agent locate context and follow conventions. They should point to the current handoff and decision records rather than accumulating every session's transcript.
They also have limits. Anthropic documents that Claude Code treats its instruction and memory files as context rather than enforced configuration. Its documentation directs developers to hooks when they need to block actions. See Claude Code's memory documentation.
Apply that distinction to your workflow: use the tool's permissions and approval controls for actions that must be stopped. A note saying “ask before publishing” is not evidence that a publishing operation is technically gated. Before acting, the receiving agent should check current authorization and whether the artifact or scope changed.
Where OrgX fits
OrgX preserves decision provenance across sessions, including source context and evidence. Its no-self-approval rule prevents an agent from approving its own work. Capture depth differs by client; broad cross-client recovery remains a beta capability to validate against your installed setup. See OrgX's acceptance and provenance overview.
You can also implement this template with version-controlled documents and source links. Choose the smallest record your team can keep accurate, then run the fresh-session test. The useful result is observable: the next agent identifies the right decision, preserves its limits, and knows the next authorized step.