Human-in-the-Loop Gates

Human-in-the-loop gates are deliberate pause points where the pipeline stops and waits for human review before continuing. Unlike escalation (which is triggered by failure), human gates are triggered by policy — certain decisions are too consequential for fully automated execution. Database migrations, API contract changes, security-sensitive modifications, and production deployments are common gate triggers.

Designing effective human gates requires balancing safety with throughput. Too many gates and the pipeline is no faster than manual development — the human spends more time reviewing intermediate steps than they would spend doing the work themselves. Too few gates and the pipeline runs unsupervised through high-risk changes. The sweet spot is gates at decision boundaries: after planning (is the plan correct?), after implementation (does the code look right?), and before deployment (is this safe to release?).

from agents import Agent, Runner
import json
from pathlib import Path

GATE_FILE = Path(".codex/gate-request.json")

def request_human_review(gate_name: str, summary: str,
                         artifacts: list[str]):
    """Pause pipeline and request human review."""
    gate_request = {
        "gate": gate_name,
        "status": "pending",
        "summary": summary,
        "artifacts": artifacts,
        "options": ["approve", "revise", "abort"],
    }
    GATE_FILE.write_text(json.dumps(gate_request, indent=2))
    print(f"\n⏸ Pipeline paused at gate: {gate_name}")
    print(f"  Review: {summary}")
    print(f"  Artifacts: {artifacts}")
    print(f"  Respond in {GATE_FILE}\n")

def check_gate_response() -> str:
    """Poll for human response."""
    if not GATE_FILE.exists():
        return "pending"
    gate = json.loads(GATE_FILE.read_text())
    return gate.get("status", "pending")

# Pipeline integration
# After planning phase:
request_human_review(
    gate_name="plan-review",
    summary="Review the implementation plan before execution",
    artifacts=[".codex/plan.md", ".codex/decisions.json"],
)