1. Scopo: la Policy come autorità operativa unica

La Policy risponde a una sola domanda per ogni tool call: "è lecito?". Con tre possibili risposte: allow, deny, approve_required. Nessun altro componente prende questa decisione. Il runtime la consulta, la sandbox la esegue, la channel la recapita — ma il verdetto nasce qui.

Cosa copre

• I tre livelli di autonomy come regole formali.
• L'albero di decisione che riduce ogni tool call a uno dei tre verdetti.
• Rate limits e cost caps (5ª Legge operativa).
• Il cost tiering: routing del modello LLM tra local-fast e frontier.
• Il check dei forbidden paths prima di delegare alla Sandbox.
• Integrazione con batching e never-list (approval_ux).
• Il preflight costituzionale: prima di qualunque altro check la Policy interroga Constitution.check(PlannedAction) e, se riporta violazione di Legge 0–2, short-circuita a deny (vedi §3 Check 0).
• Il trust-gating: promozione dinamica approve_required → allow basata su TrustScore per azioni a basso rischio con storia positiva (vedi §3 Check 6 e types §4).

Cosa non copre

• L'esecuzione effettiva dell'azione (→ sandbox).
• Il flusso di approvazione UX (→ approval_ux). La Policy emette solo il verdetto approve_required + un ApprovalRequestDraft minimo; la costruzione finale della ApprovalRequest e la sua consegna al broker sono del gateway (vedi gateway §4.1).
• L'identificazione del sender (→ pairing.html).
• La definizione delle 4 Leggi (→ constitution.html). La Policy le applica via Constitution.check(); la Costituzione le enuncia.

2. I tre livelli di autonomy, formalizzati

I livelli sono stati introdotti narrativamente nell'Architettura intro §6. Qui diventano tabella operativa che la Policy legge come fonte di verità.

Green zone per autonomy

Un'azione è "in green zone" se soddisfa tutte:

• Il tool è esposto al livello corrente.
• Gli args risolti non toccano forbidden paths (§7).
• Non supera le quote attive (§4, §5).
• Rientra in una classe accettata di default per quel livello (es. fs_write:~/opt/myclaw/workspace/* è green per Supervised; fs_write:~/Downloads/* è yellow, fs_write:/etc/* è red forbidden).

Green → allow. Yellow → approve_required. Red → deny.

3. L'albero di decisione

Check 0 — Preflight costituzionale

Prima dei cinque check "operativi" sotto, la Policy esegue un check zero-th contro la Costituzione. È una chiamata sincrona, deterministica, senza LLM. Dal punto di vista architetturale questo check è l'invocazione della fase Guardia del Vaglio: la Policy delega a Vaglio.evaluate(action, flow="reactive"), che restituisce un ConstitutionalVerdict. Per il flusso reattivo, il Giudice teleologico non viene invocato (l'utente ha chiesto; il Telos non valuta richieste esplicite).

viol = constitution.check(PlannedAction.from_tool_call(tool_call, sender, trace, autonomy))
if viol is not None:
    if viol.law in ("law.0", "law.1"):
        return PolicyDecision(verdict="deny", via="forbidden",
                              reason=viol.reason, effect_class=...)
    if viol.law == "law.2":
        # Legge 2 "non ingannare": generalmente deny, ma il profilo di
        # rigidità può permettere approve_required per violazioni borderline.
        return PolicyDecision(verdict="deny", via="forbidden",
                              reason=viol.reason, effect_class=...)
    # law.3 (tracciabilità): non blocca, ma è materiale per observability
# continua con Check 1..6

Check 6 — Trust-gating (promozione approve_required → allow)

Dopo i cinque check deterministici, se il verdetto corrente è approve_required, la Policy applica un check non strutturale che guarda la storia: se la coppia (neuron, effect_class) ha un TrustScore sopra soglia e l'azione è a basso rischio, la Policy promuove il verdetto ad allow (salvo override di autonomy). Questo è il meccanismo di adattamento darwiniano che rl_offline definisce; la Policy ne è la sola utilizzatrice runtime.

trust = trust_store.get(subject=(tool_name, effect_class))
# TrustScore è definito in types.html §4.2
if verdict == "approve_required" and action.risk == "low":
    threshold = TRUST_THRESHOLDS[autonomy][effect_class]  # da config
    if trust is not None and trust.value >= threshold and trust.decayed_ok():
        return PolicyDecision(
            verdict="allow", via="trust_gated",
            reason=f"trust={trust.value:.2f} ≥ {threshold:.2f}",
            trust_snapshot=trust,
        )
# altrimenti il verdetto resta approve_required

Il TrustStore è persistente e aggiornato off-line da rl_offline (trace-scoring). La Policy lo legge soltanto a runtime: non scrive, non calcola, non aggiorna.

4. Rate limit: per sender, per tool, per trace

Tre assi di rate limiting, applicati a ogni tool call, indipendenti:

I contatori sono tenuti in RAM con sliding window + backup periodico su SQLite (workspace/state/rate_limits.db) per sopravvivere ai restart.

5. Cost caps: la 5ª Legge operativa

La 5ª Legge dell'omeostasi (proposta nel giudizio di fase 0, adattamento #3): "myclaw non deve divergere per consumo illimitato". Qui la reifichiamo in numeri concreti.

I contatori vivono in workspace/.audit/budget.json, aggiornati da ogni ThoughtStep.cost_usd della ExecutionTrace. Reset: a mezzanotte locale.

Override utente

Roberto può alzare temporaneamente il soft/hard cap con:

myclaw budget raise --soft 5 --hard 10 --for 24h --reason "sto facendo ricerca intensiva"

L'override scade da solo, è loggato, e viene mostrato nell'/admin/budget come elemento evidente ("budget elevato, torna al default il 2026-04-23 alle 10:00").

6. Cost tiering: quale modello per quale decisione

Il tiering è il pezzo della Policy che instrada ogni chiamata LLM verso il tier appropriato. Ogni chiamata LLM non è uguale alle altre: ragionare su un log richiede un frontier; decidere se "fs_write è permesso" non richiede nemmeno un LLM forte.

Tabella di routing

Risparmio atteso: con una distribuzione realistica 40% local-fast / 60% frontier, il costo giornaliero tipico scende da ~3€ a ~1.20€ (60% risparmio). Nel giudizio di fase 0 ho stimato 60-80% di risparmio potenziale: allineato.

7. Forbidden paths: integrazione con sandbox

La lista canonica dei forbidden paths vive in src/myclaw/sandbox/forbidden.py (vedi sandbox §8). La Policy non duplica la lista: la importa e la interroga.

from myclaw.sandbox.forbidden import FORBIDDEN_PATHS, is_forbidden

# Nella decisione della Policy:
def _check_forbidden(tool_name: str, args: dict) -> bool:
    for path_arg in _extract_path_args(tool_name, args):
        if is_forbidden(path_arg):
            return True
    return False

_extract_path_args sa, per ogni tool, quali argomenti sono path (es. fs_read.path, fs_write.path, shell_run.cwd). is_forbidden applica Path.resolve() prima del confronto (previene path traversal come workspace/../src).

8. Batching e never-list persistenti

La Policy interroga l'ApprovalBroker (approval_ux §9) per due pezzi:

1. active_batches(sender): elenco di BatchGrant attivi. Se la tool call matcha un batch → verdetto allow immediato (con flag via="batch" nella trace).
2. never_list(sender): elenco di effect_class blacklisted. Match → deny (check #2 in Figura 1).

Questi sono stato del broker. La Policy legge, non modifica. Il broker li aggiorna quando l'utente preme "approva per 10 min" o "mai più chiederlo" (approval_ux §4).

Persistenza

workspace/state/approvals.db           # SQLite
  └─ batches(batch_id, sender, effect_class, created_at, expires_at)
  └─ never_list(sender, effect_class, created_at, reason)

never_list non scade. È una decisione permanente di Roberto. Si rimuove solo via myclaw approvals revoke-never <effect_class>.

9. Contratto Python

from typing import Protocol, Literal
from dataclasses import dataclass

@dataclass
class PolicyDecision:
    verdict: Literal["allow", "deny", "approve_required"]
    reason: str                      # breve, user-facing se deny/approve
    effect_class: str                # ricavata dagli args (per batching)
    via: Literal["direct", "batch", "never_list", "budget", "rate",
                 "forbidden", "green_zone",
                 "constitution", "trust_promoted"] = "direct"
    tier_suggestion: Literal["local-fast", "frontier"] = "frontier"
    # Se verdict=="approve_required", draft per il gateway (vedi gateway §4.1):
    approval_draft: "ApprovalRequestDraft | None" = None
    # Se via=="trust_promoted", copia dello score consultato (audit):
    trust_snapshot: "TrustScore | None" = None

@dataclass
class ApprovalRequestDraft:
    """Pre-dato dalla Policy al Gateway. Il Gateway lo trasforma in
    ApprovalRequest completo (aggiunge request_id, timeout, etc.) e chiama
    ApprovalBroker.request(). Vedi gateway.html §4.1 per il flusso."""
    effect_class: str
    tool_name: str
    args_preview: dict            # redatta (no segreti)
    summary: str                  # one-line human; preferibilmente da tool.dry_run()
    reversibility: Literal["reversible", "reversible_with_cost", "irreversible"]
    risk: Literal["medium", "high"]
    violation_hint: "ViolationReport | None" = None

class Policy(Protocol):
    async def evaluate(
        self,
        tool_call: dict,
        trace: ExecutionTrace,
        sender: str,
        autonomy: str,
    ) -> PolicyDecision:
        """
        Decide in O(1) il verdetto per un tool call.

        Sequenza interna (vedi §3):
          0. Costruisce PlannedAction (types §4).
          1. Consulta Constitution.check(action):
             - violazione law.0/1/2 → deny immediato (via="constitution").
             - violazione law.3      → non blocca, emette evento osservabilità.
          2. Esegue i 5 check operativi (forbidden, never_list, rate, budget,
             green_zone).
          3. Se arriva a green_zone e l'azione è side-effect:
             legge TrustScore(subject=(tool_name, effect_class)); se
             supera TrustThreshold → allow con via="trust_promoted".
             Altrimenti approve_required con approval_draft popolato.
        """
        ...

    async def pick_llm_tier(
        self,
        purpose: Literal["classify", "gate", "compress", "reason",
                         "respond", "summarize-rich", "critic", "neuron-synthesis"],
        trace: ExecutionTrace | None = None,
    ) -> Literal["local-fast", "frontier"]:
        """Cost-tiering router (§6)."""
        ...

    async def check_budget(self) -> BudgetStatus:
        """Lettura dello stato budget corrente."""
        ...

@dataclass
class BudgetStatus:
    spent_today_eur: float
    soft_cap_eur: float
    hard_cap_eur: float
    soft_hit: bool
    hard_hit: bool
    rolling_hour_eur: float
    per_hour_cap_eur: float
    override_active: bool
    override_expires_at: datetime | None

10. Alternative considerate

11. Test di conformità

12. Riferimenti

Continua a leggere

myclaw — policy microprogettazione v1.0 — 2026-04-22
Primo doc di fase 2. Prossimo: workspace.html.