Pre-run check (preflight)

Ask DriftGuard whether dependent contracts are safe before you start an agent run, deploy, or outbound tool call.

The preflight API is a single HTTP call (or MCP status tools) that returns allowed or a structured block list with agentActions for remediation.

When to use preflight

• Before agent runs — LangGraph, custom orchestrators, or FuseGuard-wrapped agents
• Before deploys — gate when production agents depend on vendor MCP catalogs
• CI smoke — assert fleet health alongside coverage assert

For one-off JSON comparison without fleet context, use offline compare_json instead.

Ask DriftGuard (console)

On Command home, use Ask for read-only answers about breaking drift, MCP health, MTTR, and vendor hotspots — structured blocks cite live workspace data on Pro+. Trial and demo sessions use fixture responses. Pair with the weekly Contract Brief email (opt-in under Settings → Notifications) for retention.

Watch list preflight

Check explicit watch IDs your run depends on:

curl -s https://driftguard.org/api/preflight \
  -H "Authorization: Bearer dg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"watchIds":["550e8400-e29b-41d4-a716-446655440000"]}'

Allowed response

{
  "allowed": true,
  "blocked": [],
  "durationMs": 12
}

Blocked response

When a watch is drifted, errored, never checked, or disabled:

{
  "allowed": false,
  "blocked": [{
    "watchId": "…",
    "name": "stripe-api",
    "driftStatus": "drifted",
    "reasons": ["breaking_drift"],
    "agentActions": ["update_tool_schema", "ack_incident"]
  }],
  "durationMs": 18
}

If a drift policy enforces block_new_runs or kill_in_flight, HTTP status is 409 with policyBlocked: true.

Block reason taxonomy

Each blocked watch includes a stable reasons[] array for runbooks and automation:

OSS FuseGuard maps blocks to trip reason contract_drift_blocked with this payload in trip metadata.

Pair with acknowledgement trail (E11)

Preflight blocks unsafe runs; it does not replace human oversight. For ack-gated policies:

1. Drift webhook opens incident (incident.open)
2. Preflight returns breaking_drift + agentActions hints
3. Operator acknowledge_drift in console or MCP
4. Preflight allowed: true — agent resumes

DriftGuard does not ship HITL approval queues — route ack timestamps to your ITSM/SOAR. See drift management and OSS webhook ack trail.

Agent binding preflight

Check all watches bound to a production agent (from agents.yaml or console bindings):

curl -s https://driftguard.org/api/preflight \
  -H "Authorization: Bearer dg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"billing-agent"}'

Requires org-scoped API key or signed-in session. Returns agent status plus the same allowed / blocked shape.

MCP equivalents

• get_watch_status — single watch canonical status
• get_agent_status — agent binding + policy action
• list_affected_agents — after drift on a watch, see impacted agents

See MCP tools reference.

FuseGuard integration

OSS FuseGuard calls POST /api/preflight before each outbound tool call when DRIFTGUARD_API_KEY and FUSEGUARD_WATCH_IDS or FUSEGUARD_AGENT_ID are set. Trips use contract_drift_blocked with agentActions in metadata.

export DRIFTGUARD_API_KEY="dg_live_…"
export FUSEGUARD_AGENT_ID="billing-agent"
export FUSEGUARD_TRIP_LOG=".fuseguard/trip.json"

Guide: Runtime contract preflight (OSS) · example: examples/fuseguard/preflight_wrap.py

Limits & performance

• Up to 100 watchIds per request
• Latency logged server-side as preflight.complete (target p95 review in CP-1b)
• Empty watchIds returns allowed: true

Related

• API: POST /api/preflight
• Glossary — drift_status, agentAction
• Portfolio overview — fleet health summary