Agent Capabilities System - Implementation Proposal

Shipwright: Forge
Date: 2026-02-25
Status: Proof of Concept
Risk Level: LOW (Additive only)

Overview

Proposal to add per-agent capability levels (SAFE/BUILDER/OPERATOR) to ENVO HQ with zero breaking changes and gradual rollout strategy.

1. Data Model Proposal

Storage Location: `agents` table extension

-- Add new column with default fallback
ALTER TABLE agents 
ADD COLUMN capability_level VARCHAR(10) DEFAULT 'SAFE' NOT NULL;

-- Add constraint for valid values
ALTER TABLE agents 
ADD CONSTRAINT check_capability_level 
CHECK (capability_level IN ('SAFE', 'BUILDER', 'OPERATOR'));

-- Index for dispatcher queries
CREATE INDEX idx_agents_capability_level ON agents(capability_level);

Capability Definitions

SAFE:
  description: "Read-only operations, basic queries"
  tools: [read, web_search, web_fetch, image]
  restrictions: no_writes, no_external_actions
  
BUILDER:
  description: "Development and file operations" 
  tools: [read, write, edit, exec, web_search, web_fetch, image]
  restrictions: no_external_messaging, sandbox_only
  
OPERATOR:
  description: "Full system access including external actions"
  tools: [all]
  restrictions: audit_logged

Migration Strategy

-- Existing agents default to SAFE
UPDATE agents SET capability_level = 'SAFE' WHERE capability_level IS NULL;

-- Promote specific agents manually
UPDATE agents SET capability_level = 'BUILDER' WHERE name IN ('theo', 'dev-agent');
UPDATE agents SET capability_level = 'OPERATOR' WHERE name IN ('admin-agent');

2. UI Changes

Agent Management Interface

Location: /admin/agents page

New Elements:

// Add capability selector to agent form
<FormField>
  <Label>Capability Level</Label>
  <Select 
    value={agent.capability_level} 
    onChange={(val) => setAgent({...agent, capability_level: val})}
  >
    <Option value="SAFE">🔒 SAFE - Read-only operations</Option>
    <Option value="BUILDER">🔧 BUILDER - Development access</Option>
    <Option value="OPERATOR">⚡ OPERATOR - Full system access</Option>
  </Select>
  <HelpText>Controls which tools and operations this agent can perform</HelpText>
</FormField>

// Add capability badge to agent list
<Badge variant={getCapabilityVariant(agent.capability_level)}>
  {agent.capability_level}
</Badge>

Agent Dashboard

Location: Individual agent pages

New Section:

<Card title="Capabilities">
  <CapabilityLevel level={agent.capability_level} />
  <AllowedTools tools={getToolsForLevel(agent.capability_level)} />
  <RestrictionsList restrictions={getRestrictionsForLevel(agent.capability_level)} />
</Card>

Changes Required

Frontend: Add capability selector to agent forms
Backend: Extend agent CRUD operations to handle capability_level
API: Update /agents endpoints to include capability_level field

3. Enforcement Strategy

Dispatcher Integration

Location: src/dispatcher/tool-filter.js (new file)

const CAPABILITY_TOOLS = {
  SAFE: ['read', 'web_search', 'web_fetch', 'image'],
  BUILDER: ['read', 'write', 'edit', 'exec', 'web_search', 'web_fetch', 'image', 'canvas'],
  OPERATOR: ['all'] // No restrictions
};

function filterToolsForCapability(requestedTools, agentCapability) {
  if (agentCapability === 'OPERATOR') return requestedTools;
  
  const allowedTools = CAPABILITY_TOOLS[agentCapability] || CAPABILITY_TOOLS.SAFE;
  return requestedTools.filter(tool => allowedTools.includes(tool));
}

function enforceCapabilityLimits(toolCall, agentCapability) {
  // Additional parameter filtering based on capability
  switch (agentCapability) {
    case 'SAFE':
      return restrictSafeMode(toolCall);
    case 'BUILDER':
      return restrictBuilderMode(toolCall);
    default:
      return toolCall;
  }
}

Integration Point: src/dispatcher/main.js

// Before tool execution
const agentCapability = await getAgentCapability(agentId);
const filteredTools = filterToolsForCapability(requestedTools, agentCapability);
const enforcedCalls = filteredTools.map(call => enforceCapabilityLimits(call, agentCapability));

Backwards Compatibility

Default behavior: All existing agents get 'SAFE' level automatically
Graceful degradation: Tools silently filtered, no errors thrown
Audit trail: All capability checks logged for monitoring

4. Rollout Plan

Phase 1: Database Schema (Week 1)

Add capability_level column with default 'SAFE'
Run migration on staging environment
Verify existing functionality unchanged

Phase 2: Backend Integration (Week 2)

Implement tool filtering logic
Add capability checking to dispatcher
Create capability management API endpoints
Unit tests for all capability logic

Phase 3: Frontend UI (Week 3)

Add capability selector to admin interface
Display capability badges on agent listings
Show capability details on agent dashboard
Integration testing

Phase 4: Gradual Promotion (Week 4)

Monitor all agents running as SAFE level
Manually promote trusted agents to BUILDER
Promote admin agents to OPERATOR
Monitor for any issues or unexpected behavior

Phase 5: Documentation & Monitoring (Week 5)

Update admin documentation
Add capability metrics to monitoring dashboard
Create alerts for capability violations
Team training on new capability system

5. Risk Mitigation

Safety Measures

Default to lowest privilege: All new agents start as SAFE
Audit everything: Log all capability checks and promotions
Easy rollback: Can set all agents to SAFE instantly if needed
Gradual deployment: Phase by phase with monitoring at each step

Monitoring Points

Tool access attempts by capability level
Performance impact of capability checking
User satisfaction with capability restrictions
Security incidents related to agent permissions

Rollback Plan

-- Emergency rollback: remove capability restrictions
UPDATE agents SET capability_level = 'OPERATOR';

-- Or disable the system entirely by updating dispatcher config
UPDATE system_config SET capability_enforcement = false;

NEXT Actions

Create database migration script - Write and test the schema changes for adding capability_level column with proper constraints and default values
Implement tool filtering logic - Build the core dispatcher integration that checks agent capabilities before allowing tool execution
Design capability management UI - Create mockups and wireframes for the admin interface showing how capabilities will be displayed and edited

Implementation Notes:

Total estimated effort: 3-4 weeks
No breaking changes to existing functionality
Full backwards compatibility maintained
Can be feature-flagged for safe rollout
Zero downtime deployment possible

Success Metrics:

All existing agents continue working normally
New capability restrictions properly enforced
Admin interface intuitive and functional
Zero security incidents during rollout

Ship Proof Forge Capabilities