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

# Confirmation Flows

Confirmation system for high-risk actions to ensure user consent before executing sensitive operations.

## Features

- **Risk Classification**: Categorizes tools by risk level (LOW, MEDIUM, HIGH, CRITICAL)
- **Confirmation Tokens**: Signed tokens for validated confirmations
- **Token Validation**: Verifies tokens match intended actions
- **Expiration**: Tokens expire after 5 minutes for security

## Usage

### Checking if Confirmation is Required

```python
from safety.confirmations.flow import get_flow

flow = get_flow()

# Check if confirmation needed
requires, message = flow.check_confirmation_required(
    tool_name="send_email",
    to="user@example.com",
    subject="Important"
)

if requires:
    print(f"Confirmation needed: {message}")
```

### Processing Confirmation Request

```python
# Agent proposes action
response = flow.process_confirmation_request(
    tool_name="send_email",
    parameters={
        "to": "user@example.com",
        "subject": "Important",
        "body": "Message content"
    },
    session_id="session-123",
    user_id="user-1"
)

if response["confirmation_required"]:
    # Present message to user
    user_confirmed = ask_user(response["message"])
    
    if user_confirmed:
        # Validate token before executing
        is_valid, error = flow.validate_confirmation(
            token=response["token"],
            tool_name="send_email",
            parameters=response["parameters"]
        )
        
        if is_valid:
            # Execute tool
            execute_tool("send_email", **parameters)
```

### In MCP Tools

Tools should check for confirmation tokens:

```python
from safety.confirmations.flow import get_flow

flow = get_flow()

def execute(self, agent_type: str, confirmation_token: Optional[str] = None, **kwargs):
    # Check if confirmation required
    requires, message = flow.check_confirmation_required(self.name, **kwargs)
    
    if requires:
        if not confirmation_token:
            raise ValueError(f"Confirmation required: {message}")
        
        # Validate token
        is_valid, error = flow.validate_confirmation(
            confirmation_token,
            self.name,
            kwargs
        )
        
        if not is_valid:
            raise ValueError(f"Invalid confirmation: {error}")
    
    # Execute tool...
```

## Risk Levels

### LOW Risk
- No confirmation needed
- Examples: `get_current_time`, `list_tasks`, `read_note`

### MEDIUM Risk
- Optional confirmation
- Examples: `update_task_status`, `append_to_note`, `create_reminder`

### HIGH Risk
- Confirmation required
- Examples: `send_email`, `create_calendar_event`, `set_smart_home_scene`

### CRITICAL Risk
- Explicit confirmation required
- Examples: `send_email`, `delete_calendar_event`, `set_smart_home_scene`

## Token Security

- Tokens are signed with HMAC-SHA256
- Tokens expire after 5 minutes
- Tokens are tied to specific tool and parameters
- Secret key is stored securely in `data/.confirmation_secret`

## Integration

### With LLM

The LLM should:
1. Detect high-risk tool calls
2. Request confirmation from user
3. Include token in tool call
4. Tool validates token before execution

### With Clients

Clients should:
1. Present confirmation message to user
2. Collect user response (Yes/No)
3. Include token in tool call if confirmed
4. Handle rejection gracefully

## Future Enhancements

- Voice confirmation support
- Multi-step confirmations for critical actions
- Confirmation history and audit log
- Custom confirmation messages per tool
- Rate limiting on confirmation requests