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

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

# 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:

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