# Medusa Slack Gate

**Human-in-the-loop approval for autonomous AI agents — enforced where teams already work: Slack.**

Built for the [Slack Agent Builder Challenge](https://slackhack.devpost.com/) (Salesforce/Devpost).

> ⚠️ **Eligibility note:** Quebec residents are excluded from this hackathon's prize track per the official rules ("Canada, excluding Quebec"). This submission is a portfolio/proof-of-concept build, not a prize entry.

---

## The Problem

Autonomous AI agents are getting real tool access — posting to channels, updating user roles, writing to databases. Most agent frameworks have no concept of "this action is risky enough that a human should see it first." One bad tool call and an agent can broadcast a false outage notice, grant admin access, or wipe production data — with nobody in the loop until it's already done.

## The Solution: 4-Pillar Zero-Trust Gate

Medusa Slack Gate wraps any MCP-connected agent with a deterministic risk gate:

1. **Risk classification** — every tool call is scored LOW / MEDIUM / HIGH based on the tool name and payload (e.g. anything touching `user_role`, `admin`, or `broadcast` keys is automatically HIGH)
2. **Auto-pass for LOW risk** — reads, replies, and other non-destructive actions execute immediately, no friction
3. **Freeze + human approval for MEDIUM/HIGH** — the action is held, logged as `PENDING` in an append-only SQLite audit trail, and a real Slack Block Kit card is posted with **Approve / Deny** buttons
4. **Real-time unblock** — a human clicks in Slack, the click flows through a Bolt Socket Mode receiver, the audit log updates, and the waiting agent resumes (or is denied) within seconds

No agent action executes in the MEDIUM/HIGH path without a human's explicit click. No exceptions, no silent timeouts that default to "allow."

## Architecture

```mermaid
sequenceDiagram
    autonumber
    actor User as Administrateur (Phil)
    participant Agent as Agent IA (Mock)
    participant Gate as Medusa MCP Gate
    participant DB as Base SQLite (Audit Log)
    participant Slack as Canal #agent-approvals

    Note over Agent, Gate: Étape 1 : Action Bas Risque (LOW)
    Agent->>Gate: Appelle l'outil 'reply_thread'
    Gate->>Gate: Évaluation : Risque Bas (LOW)
    Gate-->>Agent: Statut : AUTO_PASSED (Exécution immédiate)

    Note over Agent, Slack: Étape 2 : Action Haut Risque (HIGH)
    Agent->>Gate: Appelle l'outil 'post_public_announcement'
    Gate->>Gate: Évaluation : Risque Élevé (HIGH)
    Gate->>DB: Enregistre la requête (Statut: PENDING)
    Gate->>Slack: Envoie la carte interactive (Block Kit)
    Note over Agent: L'Agent IA se fige (Polling actif)

    Note over Slack, Agent: Étape 3 : Validation Humaine en Temps Réel
    User->>Slack: Clique sur le bouton vert [Approve]
    Slack->>DB: Le récepteur Bolt met à jour la base (Statut: APPROVED)
    DB-->>Gate: Le polling détecte le changement de statut
    Gate-->>Agent: Renvoie la décision : APPROVED
    Note over Agent: L'Agent IA se débloque et s'exécute !
    Gate->>Slack: Met à jour la carte (Affichage: ✅ APPROVED)
```

**Stack:** Model Context Protocol (MCP) · Slack Bolt SDK (Socket Mode — no public endpoint required) · Slack Block Kit · SQLite (audit trail)

## Live Demo Result

Real end-to-end run, real Slack workspace, real human click:

```json
{
  "tool_name": "post_public_announcement",
  "decision": "APPROVED",
  "risk_level": "HIGH",
  "request_id": "c2f5206b1b47",
  "executed": true,
  "result": "[executed] post_public_announcement with {'public_announcement': True, 'channel': '#general'}"
}
```

The Slack card updated in place to `✅ APPROVED by @Phil Mach-1` the instant the button was clicked — no polling delay visible to the human approver.

A LOW-risk action in the same run passed through instantly with zero Slack noise:

```json
{
  "tool_name": "reply_thread",
  "decision": "AUTO_PASSED",
  "risk_level": "LOW",
  "executed": true
}
```

## Installation

```bash
git clone <this-repo>
cd slack_agent
pip install -r requirements.txt
```

Create a Slack app from the manifest below (`Create App → From a manifest`):

```json
{
  "display_information": {
    "name": "Medusa Slack Gate",
    "description": "Human approval gate for risky agent actions before execution.",
    "background_color": "#050810"
  },
  "features": {
    "bot_user": { "display_name": "Medusa Gatekeeper", "always_online": true }
  },
  "oauth_config": {
    "scopes": { "bot": ["chat:write", "commands"] }
  },
  "settings": {
    "interactivity": { "is_enabled": true },
    "org_deploy_enabled": false,
    "socket_mode_enabled": true,
    "token_rotation_enabled": false
  }
}
```

Generate an App-Level Token (`connections:write` scope), install the app, invite the bot to your approval channel, then create `.env`: