1. Scopo: perché l'approvazione è il punto critico

L'approvazione è dove l'utilità (agisco in fretta), l'intelligenza (so cosa chiedere e come) e l'autonomia (non disturbo se non serve) si incontrano in un'unica superficie. Sbagliare qui non è un bug, è un fallimento di prodotto: gli utenti cliccano "ok" riflessi, gli agenti abusano, e la Supervised mode diventa una firma in bianco.

Questo documento è il contratto di comportamento dei flussi di approvazione: quando si chiede, come si presenta, quanto si aspetta, come si batcha, come si revoca, come si rompe il pilota automatico. È la reificazione delle tensioni 1 e 2 del giudizio di fase 0.

Cosa copre

• La macchina a stati di una ApprovalRequest (pending → granted/denied/timeout/batch_auto_granted).
• Le regole di batching ("per i prossimi 10 minuti, fs_write in ~/downloads approvato per default").
• Le regole di pausa di lettura (pulsante disabilitato per 3s).
• Il tutor mode (interrompere una sequenza di N approvazioni identiche).
• La UI per canale: CLI, Telegram (priorità fase 3), voce (futuro).
• La revoca di un'azione in corso (/undo).

Cosa non copre

• La decisione se serve l'approvazione (→ policy.html).
• La costruzione dell'ApprovalRequest: è del Gateway (→ gateway §4.1). Qui definiamo solo la forma, il ciclo di vita e l'UX di consegna.
• L'esecuzione dell'azione approvata (→ sandbox.html).
• La persistenza dell'audit log (→ observability.html).

2. Tre antipattern da evitare

Prima di descrivere il design, nominiamo tre modelli di approvazione che abbiamo esplicitamente rifiutato. Nominare il fallimento previene la sua sottigliezza futura.

3. Il ciclo di approvazione canonico

Ogni volta che la Policy restituisce "approve_required", nasce una ApprovalRequest che attraversa cinque stati. Il runtime del §8 del doc agent_runtime si sospende finché la richiesta non è decisa (qualunque il verdetto).

Cosa contiene una richiesta di approvazione

Il messaggio presentato all'utente non è mai "Procedo?" generico. È strutturato in 4 pezzi obbligatori:

4. Batching: approva simili per N minuti

La singola richiesta "approvi questa operazione?" è una firma singola. Il batching permette di dare una firma per classe: "per i prossimi 10 minuti, tutte le operazioni simili sono approvate per default".

Cos'è una "classe di azione"

La classe è fissata da Policy e ha granularità intenzionalmente stretta:

effect_class: "fs_write:~/downloads/*"          # scrittura in ~/downloads e sotto
effect_class: "shell_run:apt_family"            # apt / apt-get / aptitude
effect_class: "telegram_send:@famiglia"         # messaggi al gruppo famiglia
effect_class: "fs_delete:~/trash/*"             # eliminazione file in ~/trash

Una classe non è "qualunque fs_write". Quella è una scorciatoia pericolosa: includerebbe scrittura in ~/.bashrc. La classe lega verbo + ambito.

Esempio concreto

L'ultimo pulsante è il batching. Premendolo, myclaw annota internamente:

BatchGrant(
  sender="telegram:@roberto",
  effect_class="fs_write:~/downloads/*",
  expires_at="2026-04-21T22:24:00Z",
  created_by_request_id=UUID(...)
)

Per i 10 minuti successivi, richieste che matchano effect_class e sender transitano da Pending direttamente a Batch auto-granted senza presentazione all'utente. Ma la trace continua a registrarle (Legge 3, tracciabilità).

Regole forti sul batching

• Il batching è per sender. Roberto su CLI non impatta Roberto su Telegram.
• Il batching non si estende a forbidden paths. Anche se la classe matcha, se l'azione specifica tocca /etc o simili, si torna in Pending.
• Le azioni irreversibili non sono mai batchate. Il pulsante "approva per 10 min" non viene mostrato.
• Il batch si invalida se l'utente cambia autonomy level (Supervised → ReadOnly).
• Tutti i batch attivi sono visibili con myclaw approvals list e revocabili con myclaw approvals revoke <id>.

5. Pausa di lettura: il ritardo di 3 secondi

È il cuore della mitigazione contro approval fatigue e dual-process theory. Il pulsante "Approva" non è cliccabile per 3 secondi dopo la visualizzazione della richiesta. Suona paternalistico: lo è, volutamente.

Perché 3 secondi

• Sotto 1s la pausa non è percepita, non cambia comportamento.
• A 3s l'utente ha letto il nome dell'azione, il bersaglio, la reversibilità. Fine.
• A 5s la percezione è "sistema lento", irritazione cresce. 3 è il punto dolce.

In letteratura HCI (Nielsen, Norman) la "speed bump" è un pattern noto: l'introduzione di un attrito minimo per rompere l'automazione ha riduzione del 30-50% di errori su azioni rischiose.

Come è implementata

Il pulsante è reso visivamente disabilitato (grigio, italico "attendi 3s...") con un countdown. A click durante la pausa, il click è ignorato e un micro-haptic/visual feedback segnala "non ancora". A fine pausa, il pulsante cambia aspetto e accetta input.

Nelle CLI (§8) la pausa si traduce in: il prompt [y/N] non accetta input per 3 secondi; i caratteri digitati prima vengono scartati. Nessuna magia: è lo stesso effetto.

6. Revoca: il comando /undo

La pausa di lettura previene l'errore prima del click. La revoca lo ripara dopo. Un comando /undo (Telegram), un ctrl-c esteso (CLI) o un vocale "fermati" (voce futura) arresta l'esecuzione in corso e, se possibile, inverte l'effetto.

Il comando /undo agisce sulla trace più recente dello stesso sender. Per agire su una trace specifica: /undo <trace_id_short>.

7. Tutor mode: anti-automation-bias

Paradosso della selezione: più un neurone (o una classe di azione) è "affidabile", meno l'utente lo controlla, più automation bias cresce. Il tutor mode introduce una rottura deliberata ogni K approvazioni consecutive.

Cosa cambia in un tutor-interrupt

• Pausa di lettura: 10s invece di 3s.
• Summary espanso: non solo "scrivi file X", ma "scrivi il file X. Negli ultimi 3 giorni l'hai approvato 15 volte. L'effetto è Y. La reversibilità è Z."
• Un pulsante aggiuntivo: "questa classe è routine, lasciala stare" — disabilita il tutor per questa classe per 30 giorni, loggato.
• Se l'utente rifiuta nel tutor-interrupt, scatta un log speciale tutor_caught che segnala "il tutor ha prevenuto un errore potenziale".

8. Differenze per canale

CLI (fase 1)

Telegram (fase 3)

Inline buttons, messaggio editabile, emoji sobrio. Il pulsante Approva si abilita dopo 3s via edit del messaggio.

Voce (futuro)

Pausa di lettura = TTS lento del summary (non accelerato). La conferma vocale richiede parola-chiave riconosciuta (es. "procedi") per evitare false conferme da rumori. Un "sì" generico non basta: serve intent esplicito.

Timeout per canale

9. Contratto Python

from typing import Protocol, Literal
from dataclasses import dataclass
from datetime import datetime
from uuid import UUID

@dataclass
class ApprovalRequest:
    request_id: UUID
    trace_id: UUID
    sender: str                    # es. "telegram:@roberto"
    channel: str
    tool_name: str
    args: dict
    effect_class: str              # es. "fs_write:~/downloads/*"
    summary: str                   # one-line human readable
    reversibility: Literal["reversible", "reversible_with_cost", "irreversible"]
    risk: Literal["medium", "high"]
    requested_at: datetime
    timeout_at: datetime

@dataclass
class Approval:
    request_id: UUID
    granted: bool
    granter: str                   # sender identity
    granted_at: datetime
    via: Literal["explicit", "batch", "timeout_deny", "never_list"]
    batch_window_expires_at: datetime | None = None
    reason: str | None = None      # motivazione, se negato

class ApprovalBroker(Protocol):
    async def request(self, req: ApprovalRequest) -> Approval:
        """Presenta la richiesta, attende, restituisce esito."""
        ...

    async def active_batches(self, sender: str) -> list["BatchGrant"]:
        """Elenco dei batch grant attivi per il sender."""
        ...

    async def revoke_batch(self, sender: str, batch_id: UUID) -> None:
        """Invalida un batch attivo."""
        ...

    async def undo(self, sender: str, trace_id: UUID | None = None) -> UndoResult:
        """Tenta la revoca dell'ultima azione (o di una specifica)."""
        ...

@dataclass
class BatchGrant:
    batch_id: UUID
    sender: str
    effect_class: str
    created_at: datetime
    expires_at: datetime
    approval_counter: int          # quante richieste batched so-far
    source_request_id: UUID

@dataclass
class UndoResult:
    trace_id: UUID
    status: Literal["undone", "partial", "irreversible", "already_completed"]
    message: str

10. Alternative considerate e scartate

11. Test di conformità

12. Riferimenti

Continua a leggere

myclaw — approval_ux microprogettazione v1.0 — 2026-04-21
Secondo dei tre doc trasversali di fase 1. Prossimo: eval.html.