Prelooping¶

Prelooping is the practice of wrapping tools with safety policies (allow, deny, or require approval) so you can automate safely with AI agents.

The Core Idea¶

The product and docs now use more precise terms:

Traditional approach:

AI Agent -> Tool -> Risky action executes immediately

With prelooping:

AI Agent -> Preloop -> Policy Check -> Allow / Deny / Approval -> Safe execution

Why "Preloop"?¶

The name comes from putting a "loop" (policy check and optional approval) before tool execution:

Pre = Before
Loop = Policy enforcement cycle

When you preloop a tool, you're adding a safety checkpoint that enforces your policies before any operation executes.

What Does Prelooping Do?¶

1. Intercepts Tool Calls¶

When an AI agent tries to use a prelooped tool, Preloop intercepts the request before it executes.

sequenceDiagram
    participant Agent as AI Agent
    participant Preloop as Preloop
    participant Human as Human Approver
    participant Tool as Actual Tool

    Agent->>Preloop: Call deploy_production()
    Preloop->>Preloop: Is this tool prelooped?
    Preloop->>Human: 🚨 Approval needed!
    Human->>Preloop: ✅ Approved
    Preloop->>Tool: Execute deploy_production()
    Tool-->>Preloop: Success
    Preloop-->>Agent: ✅ Deployed successfully

2. Creates Approval Request¶

Preloop creates a structured approval request with:

What tool is being called
What arguments are being passed
Who requested it (which agent/user)
When it was requested
Why it needs approval (risk assessment)

3. Notifies Approvers¶

Approvers get notified through multiple channels:

📧 Email with approve/decline buttons
📱 Mobile app (iOS/Android) with push notifications
💬 Slack/Mattermost with interactive buttons
🌐 Web dashboard with detailed view

4. Waits for Decision¶

The tool call is paused (not blocked, not cancelled—just waiting) until:

✅ Someone approves → Tool executes
❌ Someone declines → Error returned to agent
⏰ Timeout expires → Configured behavior (usually decline)

5. Executes or Rejects¶

Based on the decision:

Approved: Tool executes with original arguments, result returned to agent
Declined: Error message returned to agent, audit log created
Timeout: Configured action (usually decline with timeout reason)

When Should You Preloop a Tool?¶

✅ Always Preloop These¶

Production Operations:

deploy_production - Deploy code to production
rollback - Roll back deployments
scale_up/down - Modify infrastructure
restart_service - Restart production services

Data Operations:

delete_* - Any deletion operations
drop_table - Drop database tables
truncate - Truncate data
modify_schema - Schema changes

Financial Operations:

charge_customer - Process payments
refund - Issue refunds
update_pricing - Modify prices
approve_budget - Budget approvals

Security Operations:

grant_access - Grant permissions
create_api_key - Generate credentials
modify_firewall - Change firewall rules
rotate_secrets - Rotate secrets

🤔 Consider Prelooping These¶

Configuration Changes:

update_config - Modify configuration
change_feature_flags - Toggle features
update_environment_vars - Change environment variables

Code Operations:

merge_pr - Merge pull requests (conditionally)
create_release - Create releases
revert_commit - Revert code changes

Communication:

send_announcement - Send to all users
post_to_slack_all - Broadcast messages
send_email_blast - Mass emails

Prelooping Strategies¶

Strategy 1: Blanket Approval¶

Require approval for every call to a tool.

Example: Always approve production deployments

tool: deploy_production
approval: required
condition: null  # Always require

Use when:

Tool is extremely risky
You want oversight on every use
Compliance requires it

Strategy 2: Conditional Approval¶

Require approval only when specific conditions are met.

Example: Approve only production deployments (not staging)

tool: deploy
approval: conditional
condition: args.environment == "production"

Use when:

Tool has risky and safe use cases
You want to balance speed and safety
You can define clear risk criteria

Strategy 3: Amount-Based Approval¶

Require approval above a threshold.

Example: Approve refunds over $100

tool: issue_refund
approval: conditional
condition: args.amount > 100

Use when:

Risk scales with a parameter
Small operations are safe enough
You have clear thresholds

Strategy 4: Time-Based Approval¶

Require approval during certain times.

Example: Approve deployments on weekends

tool: deploy_production
approval: conditional
condition: timestamp(now()).getDayOfWeek() in [0, 6]

Use when:

Risk varies by time
You have maintenance windows
You want extra caution at certain times

Strategy 5: Team-Based Approval & Quorum¶

Require multiple approvers or specific teams, with optional quorum (minimum number of approvals).

Example 1: Require ANY 1 approval from database team (default)

tool: drop_table
approval: required
approvers: [database_team]
quorum: 1  # Any one member can approve

Example 2: Require 2 approvals from database team (quorum)

tool: drop_table
approval: required
approvers: [database_team]
quorum: 2  # Need 2 team members to approve

Example 3: Mix teams with quorum

tool: deploy_production
approval: required
approvers: [sre_team, platform_team]
quorum: 2  # Need 2 approvals from any combination

Use when:

Decision requires multiple perspectives ("four eyes" principle)
You want consensus for critical operations
Compliance requires multiple sign-offs
Reducing risk of single person error

How quorum works:

quorum: 1 (default) - Any ONE approver can approve
quorum: 2 - Need TWO approvers to approve
quorum: 3 - Need THREE approvers to approve
If you have 5 approvers but quorum is 2, you need any 2 of the 5 to approve
All approvals are tracked in audit log with timestamps

Strategy 6: Escalation Policies¶

Escalate to higher authority if primary approvers don't respond.

Example: Escalate to CTO if SRE team doesn't approve production deploy within 10 minutes

tool: deploy_production
approval: required
approvers: [sre_team]
timeout: 600  # 10 minutes
escalation:
  enabled: true
  escalate_to: [cto, vp_engineering]
  escalation_delay: 600  # Escalate after 10 minutes

Use when:

Time-sensitive operations need faster resolution
Primary approvers may be unavailable
Critical operations require escalation path
Compliance requires defined escalation chain

How it works:

Approval request sent to primary approvers (SRE team)
If no response after 10 minutes → escalate to CTO/VP Engineering
Escalated approvers can approve on behalf of primary approvers
Original approvers can still approve even after escalation
Full audit trail of who was notified when

Benefits of Prelooping¶

1. Speed + Safety¶

❌ Without prelooping: - Give AI full access → Fast but dangerous - Lock down AI → Safe but slow

✅ With prelooping: - AI automates everything - Humans approve risky operations - Best of both worlds!

2. Empower Junior Developers¶

Let junior developers use AI agents with senior oversight:

Junior dev's agent can deploy to production
Senior engineer approves each deployment
Junior learns, senior maintains control

3. Audit Trail¶

Every prelooped tool call creates an audit log:

Who requested it
Who approved/declined it
When it happened
What arguments were used
What the result was

Perfect for compliance and debugging.

Accessing Audit Logs:

Web UI: Navigate to Approvals → History, filter by date, tool, approver, status
API: GET /api/v1/approvals?start_date=2025-01-01&end_date=2025-01-31
Export: CSV/JSON export for analysis or SIEM integration

4. Gradual Autonomy¶

Start with everything prelooped, gradually trust the AI:

Week 1: Approve every tool call
Week 2: Remove prelooping from safe tools
Week 3: Add conditional approval (only risky cases)
Week 4: Trust fully automated workflows

5. Catch Mistakes¶

Even the best AI agents make mistakes:

Misunderstood requirements
Hallucinated code
Edge cases not considered
Context window limitations

Prelooping catches these before they cause damage.

Real-World Examples¶

Example 1: Safe Infrastructure Automation¶

Scenario: Platform team uses AI agent to manage Kubernetes clusters

Without prelooping:

Agent: "Scale down prod cluster to save costs"
❌ Scales down immediately
❌ Production goes down

With prelooping:

Agent: "Scale down prod cluster to save costs"
🔔 Human: "Wait, that's production! Decline."
✅ No downtime

Example 2: Safe Database Migrations¶

Scenario: Developer uses AI to write and run migrations

Without prelooping:

Agent: "DROP TABLE old_users"
❌ Drops immediately
❌ Data lost forever

With prelooping:

Agent: "DROP TABLE old_users"
🔔 Human: "Did you back up first?"
Agent: "Let me check... no backup found"
❌ Declined
✅ Data saved

Example 3: Cost Control¶

Scenario: Agent automates cloud resource provisioning

Without prelooping:

Agent: "Provision 100 GPU instances for training"
❌ Provisions immediately
❌ $50,000/month bill

With prelooping (conditional):

Agent: "Provision 100 GPU instances"
(Conditional: cost > $1000/month)
🔔 Human: "That's expensive! Let's use 10 instead."
Agent: "Adjusting to 10 instances..."
✅ Cost controlled

Example 4: Compliance Requirements¶

Scenario: Financial services company automates customer operations

Requirement: All customer data modifications require approval

With prelooping:

Agent: "Update customer credit limit to $10,000"
🔔 Compliance officer reviews
✅ Approved with audit log
✅ Compliance maintained

How Prelooping Works Technically¶

The MCP Proxy Layer¶

Preloop acts as an MCP (Model Context Protocol) server that:

Exposes tools to AI agents (via MCP)
Checks policies when tool is called
Pauses execution if approval needed
Resumes execution after approval

graph TD
    A[AI Agent] -->|MCP Request| B[Preloop MCP Server]
    B --> C{Prelooped?}
    C -->|No| D[Execute Immediately]
    C -->|Yes| E{Approval Policy}
    E -->|Blanket| F[Create Approval Request]
    E -->|Conditional| G{Condition Met?}
    G -->|Yes| F
    G -->|No| D
    F --> H[Notify Approvers]
    H --> I{Decision?}
    I -->|Approved| J[Execute Tool]
    I -->|Declined| K[Return Error]
    I -->|Timeout| L[Handle Timeout]
    J --> M[Return Result]
    K --> M
    L --> M
    M --> A

    style B fill:#4CAF50
    style F fill:#FFC107
    style J fill:#4CAF50
    style K fill:#f44336

Tool Configuration¶

Each tool has a configuration:

{
  "tool_name": "deploy_production",
  "source": "external_mcp_server",
  "approval_required": true,
  "approval_policy_id": "pol_xyz123",
  "conditions": [
    {
      "type": "argument",
      "expression": "args.environment == 'production'",
      "enabled": true
    }
  ]
}

Approval Policy¶

Each policy defines:

{
  "id": "pol_xyz123",
  "name": "Production Deployments",
  "approvers": ["user_123", "user_456"],
  "teams": ["platform_team"],
  "notification_channels": ["email", "slack", "mobile"],
  "timeout_seconds": 600,
  "quorum": 1
}

Making Approval Decisions¶

When you receive an approval request as an approver, consider these factors:

What to Check¶

1. Is this expected? - Did you or your team initiate this automation? - Is this a known workflow or agent? - Does the timing make sense?

2. Are the arguments correct? - Correct environment (production vs staging)? - Correct recipient/target? - Reasonable amount/scale?

3. What's the blast radius? - What happens if this goes wrong? - How quickly can we recover? - Are there dependencies?

4. Is now the right time? - Any ongoing incidents? - Maintenance windows active? - Other deployments in progress?

5. Do we have rollback? - Can we undo this operation? - Do we have backups? - Is monitoring in place?

Red Flags (When to Decline)¶

❌ Decline if: - Unexpected request (nobody initiated this) - Wrong environment (deploying to prod when you meant staging) - Suspicious timing (3 AM on a weekend) - Excessive amount/scale (way larger than normal) - Missing context (can't tell what this will do) - System is unhealthy (ongoing incident, degraded state) - No rollback plan

When declining, always provide a clear reason to help the AI or user understand what went wrong.

Notification Channels¶

Approvers are notified through multiple channels:

Email¶

Instant email with approve/decline buttons
Tool name, arguments, requester info
Direct links to approve or decline

Mobile App¶

Push notifications to iOS/Android
One-tap approve or decline
Biometric auth (Face ID, Touch ID)
Full request details in app

Slack/Mattermost¶

Message posted to configured channel
Interactive approve/decline buttons
Threaded responses for discussion

Web Dashboard¶

Real-time notification with bell badge
Dropdown with pending requests
Full details in modal view
Safety Layer & Access Rules
MCP Tool Integration
Policy-as-Code

Those pages reflect the current product model more accurately than the older approval-only framing.