Agent deletes production database
Agent sends emails to all customers
Agent accesses sensitive data
Agent makes unauthorized purchases

Agent can only use approved tools
Sensitive tools require approval
Actions are logged and auditable
Users control what agent can do

User has role → Role has permissions → Agent inherits permissions

Example:
- Admin role: Can use all tools
- User role: Can use read-only tools
- Guest role: Can use search tools only

Permissions based on attributes:
- User attributes (department, level)
- Resource attributes (sensitivity, owner)
- Environment attributes (time, location)

Example:
- Finance department can use payment tools
- During business hours only
- For amounts < $1000

User grants specific capabilities to agent

Example:
- "You can search my emails"
- "You can book meetings on my calendar"
- "You cannot delete anything"

class ToolPermissions:
    def __init__(self):
        self.roles = {
            "admin": ["*"],  # All tools
            "user": ["search_web", "get_weather", "calculate"],
            "guest": ["search_web"]
        }
    
    def can_use_tool(self, user_role, tool_name):
        """Check if role has permission for tool"""
        allowed_tools = self.roles.get(user_role, [])
        
        # Check wildcard
        if "*" in allowed_tools:
            return True
        
        # Check specific tool
        return tool_name in allowed_tools

# Usage
permissions = ToolPermissions()

if permissions.can_use_tool(user_role="user", tool_name="search_web"):
    result = search_web(query)
else:
    raise PermissionError("Not allowed to use search_web")

CREATE TABLE roles (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) UNIQUE NOT NULL
);

CREATE TABLE tools (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) UNIQUE NOT NULL,
    description TEXT,
    risk_level VARCHAR(20)  -- low, medium, high, critical
);

CREATE TABLE role_tool_permissions (
    role_id INT REFERENCES roles(id),
    tool_id INT REFERENCES tools(id),
    can_use BOOLEAN DEFAULT TRUE,
    requires_approval BOOLEAN DEFAULT FALSE,
    PRIMARY KEY (role_id, tool_id)
);

CREATE TABLE user_roles (
    user_id VARCHAR(100),
    role_id INT REFERENCES roles(id),
    PRIMARY KEY (user_id, role_id)
);

def can_use_tool(user_id, tool_name):
    """Check if user has permission for tool"""
    result = db.query_one("""
        SELECT rtp.can_use, rtp.requires_approval
        FROM user_roles ur
        JOIN role_tool_permissions rtp ON ur.role_id = rtp.role_id
        JOIN tools t ON rtp.tool_id = t.id
        WHERE ur.user_id = %s AND t.name = %s
    """, (user_id, tool_name))
    
    if not result:
        return False, False
    
    return result["can_use"], result["requires_approval"]

TOOL_RISK_LEVELS = {
    # Low risk (read-only)
    "search_web": "low",
    "get_weather": "low",
    "calculate": "low",
    
    # Medium risk (write, non-destructive)
    "send_email": "medium",
    "create_calendar_event": "medium",
    
    # High risk (destructive)
    "delete_file": "high",
    "update_database": "high",
    
    # Critical risk (financial, security)
    "make_payment": "critical",
    "grant_access": "critical"
}

def execute_tool_with_approval(user_id, tool_name, params):
    """Execute tool, requesting approval if needed"""
    risk_level = TOOL_RISK_LEVELS.get(tool_name, "medium")
    
    if risk_level in ["high", "critical"]:
        # Request approval
        approval_id = request_approval(
            user_id=user_id,
            tool_name=tool_name,
            params=params,
            risk_level=risk_level
        )
        
        # Wait for approval (or timeout)
        approved = wait_for_approval(approval_id, timeout_seconds=300)
        
        if not approved:
            raise PermissionError("Approval denied or timeout")
    
    # Execute tool
    return execute_tool(tool_name, params)

def request_approval(user_id, tool_name, params, risk_level):
    """Request approval for tool execution"""
    approval_id = generate_id()
    
    # Store approval request
    db.execute("""
        INSERT INTO approval_requests
        (id, user_id, tool_name, params, risk_level, status, created_at)
        VALUES (%s, %s, %s, %s, %s, 'pending', NOW())
    """, (approval_id, user_id, tool_name, json.dumps(params), risk_level))
    
    # Notify user
    send_notification(
        user_id=user_id,
        title="Agent Approval Required",
        message=f"Agent wants to use {tool_name}. Approve?",
        actions=[
            {"label": "Approve", "action": f"approve:{approval_id}"},
            {"label": "Deny", "action": f"deny:{approval_id}"}
        ]
    )
    
    return approval_id

def approve_request(approval_id, user_id):
    """Approve tool execution"""
    db.execute("""
        UPDATE approval_requests
        SET status = 'approved', approved_by = %s, approved_at = NOW()
        WHERE id = %s
    """, (user_id, approval_id))
    
    log_event(f"User {user_id} approved {approval_id}")

def deny_request(approval_id, user_id, reason=None):
    """Deny tool execution"""
    db.execute("""
        UPDATE approval_requests
        SET status = 'denied', denied_by = %s, denied_at = NOW(), denial_reason = %s
        WHERE id = %s
    """, (user_id, approval_id, reason))
    
    log_event(f"User {user_id} denied {approval_id}: {reason}")

import time

def wait_for_approval(approval_id, timeout_seconds=300):
    """Wait for approval (or timeout)"""
    start_time = time.time()
    
    while time.time() - start_time < timeout_seconds:
        status = db.query_one("""
            SELECT status FROM approval_requests WHERE id = %s
        """, (approval_id,))
        
        if status["status"] == "approved":
            return True
        
        if status["status"] == "denied":
            return False
        
        time.sleep(5)  # Check every 5 seconds
    
    # Timeout
    db.execute("""
        UPDATE approval_requests
        SET status = 'timeout'
        WHERE id = %s
    """, (approval_id,))
    
    return False

def can_use_tool_at_time(user_id, tool_name, current_time):
    """Check if user can use tool at current time"""
    permissions = db.query_one("""
        SELECT allowed_hours_start, allowed_hours_end
        FROM tool_permissions
        WHERE user_id = %s AND tool_name = %s
    """, (user_id, tool_name))
    
    if not permissions:
        return False
    
    current_hour = current_time.hour
    start_hour = permissions["allowed_hours_start"]
    end_hour = permissions["allowed_hours_end"]
    
    return start_hour <= current_hour < end_hour

# Example: Only allow during business hours (9 AM - 5 PM)

def can_access_resource(user_id, resource_id):
    """Check if user can access specific resource"""
    # Check ownership
    resource = db.query_one("""
        SELECT owner_id FROM resources WHERE id = %s
    """, (resource_id,))
    
    if resource["owner_id"] == user_id:
        return True
    
    # Check shared access
    shared = db.query_one("""
        SELECT * FROM resource_shares
        WHERE resource_id = %s AND user_id = %s
    """, (resource_id, user_id))
    
    return shared is not None

def can_make_payment(user_id, amount):
    """Check if user can make payment of given amount"""
    # Check user's spending limit
    limit = db.query_one("""
        SELECT daily_spending_limit FROM user_limits
        WHERE user_id = %s
    """, (user_id,))
    
    # Check today's spending
    spent_today = db.query_one("""
        SELECT COALESCE(SUM(amount), 0) as total
        FROM payments
        WHERE user_id = %s AND DATE(created_at) = CURRENT_DATE
    """, (user_id,))
    
    remaining = limit["daily_spending_limit"] - spent_today["total"]
    
    return amount <= remaining

def delegate_permission(from_user_id, to_user_id, tool_name, expires_at=None):
    """Delegate permission to another user"""
    db.execute("""
        INSERT INTO delegated_permissions
        (from_user_id, to_user_id, tool_name, expires_at, created_at)
        VALUES (%s, %s, %s, %s, NOW())
    """, (from_user_id, to_user_id, tool_name, expires_at))
    
    log_event(f"User {from_user_id} delegated {tool_name} to {to_user_id}")

# Example: Manager delegates approval to assistant
delegate_permission(
    from_user_id="manager@example.com",
    to_user_id="assistant@example.com",
    tool_name="approve_expense",
    expires_at=datetime.now() + timedelta(days=7)
)

def log_tool_usage(user_id, tool_name, params, result, approved_by=None):
    """Log tool usage for audit"""
    db.execute("""
        INSERT INTO tool_usage_log
        (user_id, tool_name, params, result, approved_by, timestamp)
        VALUES (%s, %s, %s, %s, %s, NOW())
    """, (user_id, tool_name, json.dumps(params), json.dumps(result), approved_by))

def get_tool_usage_history(user_id, start_date, end_date):
    """Get tool usage history for user"""
    return db.query("""
        SELECT tool_name, params, result, approved_by, timestamp
        FROM tool_usage_log
        WHERE user_id = %s
          AND timestamp BETWEEN %s AND %s
        ORDER BY timestamp DESC
    """, (user_id, start_date, end_date))

# Good: Only grant necessary permissions
user_permissions = ["search_web", "get_weather"]

# Bad: Grant all permissions
user_permissions = ["*"]

# Good
if TOOL_RISK_LEVELS[tool_name] == "critical":
    require_approval()

# Bad
# No approval for critical tools

# Good
delegate_permission(from_user, to_user, tool, expires_at=now + timedelta(days=7))

# Bad
delegate_permission(from_user, to_user, tool)  # Never expires

# Good
log_tool_usage(user_id, tool_name, params, result)

# Bad
# No logging

# Review permissions quarterly
def audit_permissions():
    # Find users with excessive permissions
    # Find unused permissions
    # Find expired delegations
    pass