Capability Control System

Cortex provides a 4-tier access level system for fine-grained control over what AI agents can do. This builds on the existing 56 capabilities with graduated permission levels.

Access Levels

Level	Name	Behavior
0	none	Capability completely disabled. API returns 403.
1	read	Read-only. GET requests allowed, mutations blocked with 403.
2	write	Read + write. Dangerous operations require human confirmation (returns 202).
3	autonomous	Full access. All operations execute immediately, including dangerous ones.

How It Works

Standard Operations (non-dangerous)

Agent Request → Check access_level →
  autonomous (3): execute immediately
  write (2):      execute immediately
  read (1):       allow GET only, block POST/PATCH/DELETE with 403
  none (0):       return 403

Dangerous Operations

For the 10 dangerous capabilities, the write level introduces a confirmation flow:

Agent Request (dangerous op) → Check access_level →
  autonomous (3): execute immediately
  write (2):      return 202 with confirmationId
                   → Human approves via dashboard or API
                   → Agent retries with X-Confirmation-Id header
  read (1):       return 403
  none (0):       return 403

Confirmation Flow

When a write-level agent attempts a dangerous operation:

Step 1: Agent makes the request

curl -X DELETE https://api.cortex.acrobi.com/api/agents/old-agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agent-Definition: cleanup-agent"

Step 2: API returns 202 with confirmation ID

{
  "status": "pending_confirmation",
  "confirmationId": "conf-abc123",
  "operation": "agent.delete",
  "target": "old-agent",
  "expiresAt": "2026-04-03T13:00:00.000Z",
  "message": "This operation requires human approval. Approve via dashboard or POST /api/confirmations/conf-abc123/approve"
}

Step 3: Human approves (via dashboard or API)

curl -X POST https://api.cortex.acrobi.com/api/confirmations/conf-abc123/approve \
  -H "Authorization: Bearer $HUMAN_TOKEN"

Step 4: Agent retries with confirmation

curl -X DELETE https://api.cortex.acrobi.com/api/agents/old-agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Confirmation-Id: conf-abc123"

Setting Access Levels

Per-Agent Configuration

curl -X PATCH https://api.cortex.acrobi.com/api/agent-capabilities/profile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "my-coder-agent",
    "scope": "project",
    "entityId": "proj-123",
    "capabilities": {
      "agent.create": "write",
      "agent.read": "autonomous",
      "agent.delete": "none",
      "task.create": "autonomous",
      "task.read": "autonomous",
      "memory.create": "write",
      "org.billing": "none"
    }
  }'

Apply a Preset Then Customize

# Start with the "coder" preset
curl -X POST https://api.cortex.acrobi.com/api/agent-capabilities/profile/apply-preset \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agentName": "my-coder-agent", "preset": "coder"}'

# Then override specific capabilities
curl -X PATCH https://api.cortex.acrobi.com/api/agent-capabilities/profile \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agentName": "my-coder-agent", "capabilities": {"agent.delete": "none"}}'

Organization-Level Defaults

Set default access levels for all agents in an organization:

curl -X PATCH https://api.cortex.acrobi.com/api/agent-capabilities/org-defaults \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organization-Id: org-123" \
  -d '{
    "defaults": {
      "org.billing": "none",
      "org.members": "read",
      "agent.delete": "write",
      "system.admin": "none"
    }
  }'

Resolution Algorithm

Access levels resolve through the same hierarchical intersection as boolean capabilities:

effective_level = min(
  definition_level,
  instance_level,
  project_level,
  workspace_level
)

Each level can only restrict — a project cannot grant autonomous if the workspace limits to write.

Database Schema

The capability control system extends the existing capability_toggles table:

-- Existing table (extended)
ALTER TABLE capability_toggles
  ADD COLUMN access_level TEXT DEFAULT 'none'
  CHECK (access_level IN ('none', 'read', 'write', 'autonomous'));

-- Migration: existing enabled=true → 'write', enabled=false → 'none'
UPDATE capability_toggles
  SET access_level = CASE WHEN enabled = 1 THEN 'write' ELSE 'none' END;

Dashboard UI

The capability control is managed in Settings > Agent Capabilities:

1. Select an agent from the dropdown
2. Optionally apply a preset profile as a starting point
3. For each of the 56 capabilities, set the access level via dropdown (none / read / write / autonomous)
4. Dangerous capabilities are highlighted with a warning indicator
5. Save to apply immediately

Pending confirmations appear in the Notifications panel with approve/deny buttons.