How to hand off context between AI coding agents
Give the next agent the evidence and authority needed for one task, with a clear way to report back.
An effective context handoff gives the next AI coding agent enough information to complete a bounded task and explains what it may change. Include the objective, exact workspace and revision, relevant evidence, decisions already made, permitted actions, and expected return artifact. A full transcript is rarely the easiest starting point.
Consider a change that adds validation to a search form. The implementation agent knows the conversation that led to it. The reviewer needs the intended behavior, the changed files, the baseline, and the failure cases. Copying every earlier idea makes those facts harder to find and can carry assumptions the review should challenge.
Build the brief around an observable outcome
Use this example as a structure, replacing every project-specific value:
Outcome: Empty or whitespace-only searches must not be submitted. Workspace: The absolute path to the checkout being reviewed. Revision: The base commit and current commit, or a frozen working diff. Scope: Search form, submission handler, and their relevant tests. Evidence: Changed file list, test command, result, and known failures. Decisions: Keep existing error placement and keyboard behavior. Permissions: Review only. Do not edit files or run external actions. Return: Findings with severity, file and line, reproduction, and rationale. Completion: Explicitly say no findings if no actionable issue is found. Blocker: Report missing inputs before guessing or broadening the task.
The interactive brief builder lets you adapt and copy a brief. It prepares text; it does not execute an agent or grant permissions. Prompt wording is also not a substitute for enforced runtime access controls.
Transfer evidence in layers
Put the acceptance criterion and current state first. Follow with the minimum evidence needed to assess that state, then links to deeper material. A short test log with the failing assertion is easier to use than an unfiltered terminal transcript. Keep the full log available when it is needed to investigate an unexpected result.
Distinguish facts from decisions and unresolved hypotheses. “The check failed with this error” is an observation. “The cache caused the failure” is a hypothesis until investigated. “Do not change the public API” is a constraint. Preserving these distinctions helps the recipient challenge the reasoning without accidentally reopening settled requirements.
Include provenance: where a result came from, which revision it describes, and when it was observed. A passing test from an earlier tree cannot validate a later edit. If another worker changes the checkout while the review is running, refresh the baseline or ask the reviewer to identify the exact revision it inspected.
Share selected context deliberately
Repository instructions, a public API contract, and a narrow task brief can usually be shared with a reviewer. Credentials, unrelated customer material, private conversations, and confidential decisions require a reason and an authorized destination. Prefer a reference the recipient can access over copying a secret into the brief.
OpenScout's broker owns its coordination records. External Claude Code, Codex, and other harness transcripts remain observed source material under the data model. Discoverability of a transcript is not permission to disclose it or proof that a new worker automatically inherits it.
Continue the same work intentionally
After a handoff, retain the returned reference. A follow-up such as “check the updated validation branch” should identify the same review or its exact continuing session when continuity is intended. A fresh request to the same model can create a new context.
If the reply is delayed, inspect the work before launching a replacement. The artifact may exist even when its completion acknowledgement is missing. Compare the request, execution status, changed files, and returned result; see delivery versus completion.
Check the handoff before expanding the workflow
Run one small review. Ask the recipient to identify the acceptance criterion and inspected revision in its response. Confirm that its findings refer to the expected files and that it respected the requested scope. Track reconstruction time and clarification questions. Those observations tell you what the brief omitted without assuming that a longer prompt would solve the problem.
The Claude/Codex review guide provides a concrete next step. Watch how agent handoffs work for the request, execution, and acceptance sequence.