Make artifacts and human decisions explicit

A human review is useful when the person can see what will happen and why. "Continue?" after a long transcript provides little to inspect. Assemble a small decision packet around the actual artifact.

For a code change, that means the task, base revision, diff, check results, findings, unresolved decisions, and intended integration target.

Define what crosses each boundary

Give every stage named inputs and an expected output. A repository review might return:

{
  "status": "completed",
  "summary": "The delay change preserves the cap.",
  "findings": [
    {
      "path": "retry.js",
      "line": 2,
      "severity": "question",
      "detail": "The task leaves attempt zero undefined.",
      "check": "Ask the owner to define valid attempts."
    }
  ]
}

This is an example task payload, not a vendor's response envelope. The runner must extract it from the native result and validate it. A syntactically valid finding still needs a real file and a defensible claim.

The coordinator adds trusted run metadata: input hashes, artifact hashes, tool version, observed model where available, timings, and terminal status. It computes hashes itself. Letting a model invent a digest would defeat the check.

Put review points at decisions

Approve the initial scope and data recipients before work starts. Review a concrete design before a material architectural change. After implementation, review the exact diff and verification evidence.

Acceptance may also authorize a named integration action when the person has seen its target and consequences. If the task stops at a local patch, acceptance ends the workflow. A later deployment is a separate action unless the existing authorization explicitly covers it.

Routine work inside an approved recipe can proceed without repeated questions. A wider file scope, new recipient, changed target, or additional authority requires a new decision about that change.

Bind the decision to the artifact

Store the decision outside the agent's writable workspace. Include the recipe and policy version, base revision, artifact digest, target, decision, and approver identity appropriate to the environment.

Suppose review accepts diff A, then a repair produces diff B. The acceptance for A cannot authorize B. Recompute the packet and obtain the affected decision again. A restart must preserve a denial or pending decision; a timeout must never turn it into an approval.

Native permission systems control tool actions. For example, the Claude Agent SDK can request runtime decisions through its approval callback, while Gemini CLI uses policy decisions. Connect those controls deliberately to the coordinator; an agent's written claim of approval is ordinary output.

What goes wrong

A JSON object says approved: true and the runner trusts it. A review is bound to a filename whose contents can change. A test log has no revision, or the implementer changed the test that supposedly proves correctness.

Use coordinator-owned records, immutable artifacts, and actual command results. Show check changes separately so the reviewer can decide whether the new test still represents the requirement.

How to check

Approve a sample packet, change one byte in its artifact, and attempt to continue. The old decision must fail to authorize the new result. Repeat after changing the base revision or target.

Restart with a denied or pending gate and confirm it stays stopped. Inject approved: true into an agent response and confirm it has no authority. Finally, ask a reviewer to explain the proposed action using only the packet; missing context belongs in the packet before the workflow grows.