atlas/home-voice-agent/safety/boundaries/README.md

# Boundary Enforcement

Enforces strict separation between work and family agents to ensure privacy and safety.

## Features

- **Path Whitelisting**: Restricts file system access to allowed directories
- **Tool Access Control**: Limits which tools each agent can use
- **Network Separation**: Controls network access
- **Config Validation**: Ensures config files don't mix work/family data

## Usage

```python
from safety.boundaries.policy import get_enforcer

enforcer = get_enforcer()

# Check path access
allowed, reason = enforcer.check_path_access(
    agent_type="family",
    path=Path("/home/beast/Code/atlas/home-voice-agent/data/tasks/home")
)
if not allowed:
    raise PermissionError(reason)

# Check tool access
allowed, reason = enforcer.check_tool_access(
    agent_type="family",
    tool_name="add_task"
)
if not allowed:
    raise PermissionError(reason)

# Check network access
allowed, reason = enforcer.check_network_access(
    agent_type="family",
    target="10.0.30.63"
)
if not allowed:
    raise PermissionError(reason)
```

## Policies

### Family Agent Policy

**Allowed Paths**:
- `data/tasks/home/` - Home task Kanban
- `data/notes/home/` - Family notes
- `data/conversations.db` - Conversation history
- `data/timers.db` - Timers and reminders

**Forbidden Paths**:
- Work repositories
- Work-specific data directories

**Allowed Tools**:
- All home management tools (time, weather, timers, tasks, notes)
- No work-specific tools

**Network Access**:
- Localhost only (by default)
- Can be configured for specific networks

### Work Agent Policy

**Allowed Paths**:
- All family paths (read-only)
- Work-specific data directories

**Forbidden Paths**:
- Family notes (should not modify)

**Network Access**:
- Broader access including GPU VM

## Integration

### In MCP Tools

Tools should check boundaries before executing:

```python
from safety.boundaries.policy import get_enforcer

enforcer = get_enforcer()

def execute(self, agent_type: str, **kwargs):
    # Check tool access
    allowed, reason = enforcer.check_tool_access(agent_type, self.name)
    if not allowed:
        raise PermissionError(reason)
    
    # Check path access if applicable
    if "path" in kwargs:
        allowed, reason = enforcer.check_path_access(agent_type, Path(kwargs["path"]))
        if not allowed:
            raise PermissionError(reason)
    
    # Execute tool...
```

### In Router

The router can enforce network boundaries:

```python
from safety.boundaries.policy import get_enforcer

enforcer = get_enforcer()

# Before routing, check network access
allowed, reason = enforcer.check_network_access(agent_type, target_url)
```

## Static Policy Checks

For CI/CD, create a script that validates:
- Config files don't mix work/family paths
- Code doesn't grant cross-access
- Path whitelists are properly enforced

## Future Enhancements

- Container/namespace isolation
- Firewall rule generation
- Runtime monitoring and alerting
- Audit logging for boundary violations