What to Check Before Approving an AI Coding Agent Run

Before approving an AI coding agent's work, inspect the change itself, the exact checks that ran, their results, and what remains uncertain. A green summary is a useful pointer, but it is not the evidence. If the next step is a deployment or another costly action, place the human decision before that action and give the reviewer enough context to say yes, no, or “run one more check.”

Statewright can put a review step and an approval gate in a workflow. The gate controls when a transition may proceed; it does not prove that the code is correct or replace the reviewer's judgment. The same distinction applies to run history: it records Statewright-observed events and tool calls, within the limits of the host integration.

Read the diff before the summary

Start with the task's intended scope. Which files were supposed to change? Which files actually changed? A brief explanation is useful, but the diff shows the implementation and any incidental edits. Look for a new dependency, a migration, a changed permission, a broadened API response, or a test that was weakened to pass. These deserve attention even when the main feature works.

For a refactor, compare observable behavior before and after the change. For a bug fix, check that the test fails for the old behavior and passes for the new one when that is practical. For a new feature, compare the result with the acceptance criteria. If the agent says “no change needed,” ask what it inspected and how it established that conclusion. The engineering starter has an explicit path for investigations and already-correct behavior, with a handoff that should name its evidence and limits.

Ask for the command, result, and environment

“Tests pass” is too vague for a release decision. Ask which command ran, what it covered, whether it exited successfully, and whether the environment resembled the target. A unit test on a developer laptop does not establish that a deployment configuration works; a browser screenshot does not establish that a database migration is safe. The required checks depend on the change.

The reviewer can use a short checklist:

1. Scope: Does the diff match the requested change, and is the source revision identifiable?
2. Validation: Are the actual commands and their results available, including failures and retries?
3. Behavior: Is there evidence for the user-visible or API behavior the task required?
4. Risk: Are untested paths, environment differences, and irreversible steps named?
5. Decision: Is the person authorized to approve this transition clear?

Keep a failed check in the record even if a later run passes. The sequence can reveal a flaky test or a repair that changed more than intended. Statewright's Quick Start notes that a recorded validation result is still the agent's report, not independent proof. Its review phase is not necessarily a second reviewer. Use the report to locate evidence, then inspect the evidence.

Put the approval before the risky transition

In a Statewright workflow, a transition can set requires_approval and an approval_message. A reviewer can be assigned to that transition; if none is specified, the workflow creator is the default. The workflow schema reference describes the gate, reviewer identity, and optional guard conditions.

Place the gate where it can still change the outcome. For example, a transition from validated to deploying can require both a passing guard and human approval. A gate after deployment can still acknowledge the result, but it cannot prevent that deployment. Define a revision path so an insufficient packet can lead back to implementation or validation without pretending the run is complete.

For Statewright's approval UI, set meta.approval_mode to ui in the definition and check the current plan and integration requirements. The published schema reference says approval resolution requires an active Pro, Team, or Enterprise subscription for the workflow owner. Native host permissions are separate from a Statewright review decision: approving a workflow transition does not grant a shell command or file access that the host would otherwise deny.

Give the reviewer a compact evidence packet

An approval request should name the candidate being reviewed and make the decisive artifacts easy to find. A useful packet includes a short summary, a checklist tied to the task, the diff or source revision, and the validation receipt. Statewright supports an optional, versioned evidence packet on an approval transition. In managed Codex and Claude clients, supported project-relative artifacts can be hashed and uploaded for the designated reviewer; the schema reference specifies the file and size limits. Check your client guide before depending on that path.

Avoid making the packet a substitute for source inspection. A concise artifact list helps a reviewer reach the evidence without searching a long conversation, but a summary can omit a critical detail. If the commands, scope, or remaining risk are unclear, withhold approval and ask for the missing check. A useful approval gate makes that pause a normal part of the workflow.