1. What approval_ux is

approval_ux is the visual and flow schema with which Metnos asks Roberto (and anyone paired as Supervised) to confirm a critical action before executing it. It lives on the pairing channel — today Telegram, tomorrow Signal and voice — and triggers when the policy computes an effective_outcome equal to approval_required.

The base pattern is the dialog manager pattern: a 3-line card, two inline buttons (Approve / Reject), an opaque token that uniquely identifies the request. The card is modulated as a function of how many times the same request has already been issued — at the tenth "may I download?" Roberto already knows what he is approving and a compact line is enough. A territory concession (for a session, permanently) is signalled with a textual marker.

Behind the card lives an infrastructure of three components:

• the renderer (runtime/channels/approval.py) which produces the OutboundMessage with text and buttons;
• the SQLite registry (runtime/approval_registry.py) which tracks every pending request with TTL and status;
• the dispatcher (runtime/channels/daemon.py + runtime/channels/telegram.py) which receives the button clicks and resolves the token.

2. The 3-line card

The dialog manager pattern prescribes three canonical lines, each with a precise function. The render_approval_card function (runtime/channels/approval.py:60-87) composes them from the fields of ApprovalRequest:

Below the three lines, two inline buttons:

buttons = [[
    {"text": "Approva", "data": f"approve:{req.token}"},
    {"text": "Rifiuta", "data": f"reject:{req.token}"},
]]

The token is the opaque reference issued by the approval_registry when the pending request was created (see ch. 6); the data of the buttons is the only information that will come back when the user clicks, hence the token must be enough to identify the request.

The rendering signature is minimal:

def render_approval_card(req: ApprovalRequest) -> OutboundMessage:
    """Produces an OutboundMessage with the 3-line card + two buttons."""

No styling parameters, no i18n: everything that varies is in the ApprovalRequest fields (runtime/channels/approval.py:60-62).

3. The ApprovalRequest dataclass

The contract between the request raiser (Vaglio, Policy, future integrated planner) and the renderer is a frozen dataclass of eight fields. Reference: runtime/channels/approval.py:27-38.

The dataclass is frozen=True: once built, an ApprovalRequest cannot be modified. This makes it safe to pass between modules without fear of side mutations, and lends itself well to hashing for future deduplication.

4. Recurrence-based modulation

The same request raised ten times in a row does not deserve the same care as the first. The module foresees three forms of the card, chosen based on the recurrence_count field:

Selection is done by _shape_for_recurrence (runtime/channels/approval.py:52-57):

def _shape_for_recurrence(n: int) -> Literal["full", "medium", "short"]:
    if n >= _RECURRENCE_THRESHOLDS[1]:
        return "short"
    if n >= _RECURRENCE_THRESHOLDS[0]:
        return "medium"
    return "full"

The thresholds are in a module-level constant, declared next to the renderer:

_RECURRENCE_THRESHOLDS = (3, 8)  # < 3: full | 3..7: medium | ≥ 8: short

Reference: runtime/channels/approval.py:48-49. Changing the thresholds is a one-line local edit; the rendering structure is untouched.

Medium and short forms are designed for cases where Roberto knows what he is approving: an agent running a recurring macro, a long session in which the same action repeats every minute. Full remains the default for the first time and the second time: the care of showing details matters more than reading speed.

5. Territory marker

A territory concession is when, by approving, Roberto says not only "yes to this action" but also "yes to this class of actions in the future". Three levels, three textual markers:

The marker is appended at the tail of the meta classification. Reference: runtime/channels/approval.py:42-46:

_TERRITORY_MARKER = {
    "none": "",
    "session": " [territorio: sessione]",
    "permanent": " [territorio: permanente]",
}

It is a dictionary, not a function: the mapping is static and depends on nothing else. Robust ASCII on every client (no glyphs that vary from font to font). The square bracket opens a block visually distinct from the rest of the meta line, which uses the vertical bar as separator. The concession is visible at a glance even in a truncated push notification.

6. SQLite approval registry

When the policy decides that an action requires approval, someone has to track the pending request until the user responds (or the TTL expires). That someone is runtime/approval_registry.py: a SQLite-only module, no daemon, no classes (apart from the record dataclass).

6.1 Schema

A single table pending, primary key the token. Reference: runtime/approval_registry.py:34-52:

CREATE TABLE IF NOT EXISTS pending (
    token              TEXT PRIMARY KEY,
    channel            TEXT NOT NULL,
    sender_id          TEXT NOT NULL,
    capability_class   TEXT NOT NULL,
    action_verb        TEXT NOT NULL,
    target_summary     TEXT NOT NULL,
    created_at         TEXT NOT NULL,
    expires_at         TEXT NOT NULL,
    status             TEXT NOT NULL DEFAULT 'pending',
    decision_at        TEXT,
    decision_by_channel TEXT,
    decision_by_sender  TEXT,
    request_extra      TEXT
);
CREATE INDEX IF NOT EXISTS idx_pending_status ON pending(status);
CREATE INDEX IF NOT EXISTS idx_pending_expires ON pending(expires_at);

Four recognised states for the status column: pending, approved, rejected, expired. Dates are ISO-8601 in UTC (%Y-%m-%dT%H:%M:%SZ), convenient for lexicographic comparison.

6.2 API

Five public functions. All open and close the SQLite connection on every call: no connection pool, no global state.

6.3 Database and TTL

The DB path is resolved in order: explicit argument db_path > environment variable METNOS_APPROVALS_DB > default ~/.local/state/metnos/approvals.db. The directory is created if missing. Reference: runtime/approval_registry.py:86-92.

The default TTL is 600 seconds (10 minutes). It is the time within which Roberto must respond before the request is marked expired; a reminder system or a re-issue remains the caller's responsibility. Reference: runtime/approval_registry.py:30.

6.4 The security rule

The point of tension is resolve(). Four checks, in order, plus an important detail about persistence. Reference: runtime/approval_registry.py:177-205:

1. Known token. If the token does not exist, ApprovalError("token sconosciuto").
2. Status pending. If already resolved (approved/rejected/expired), ApprovalError("token già risolto"): no double-spending of the decision.
3. Not expired. If expires_at < now, an UPDATE is written that marks status='expired' and then ApprovalError is raised. The connection is opened in autocommit (isolation_level=None) precisely because the transition to expired must survive the exception.
4. Decider = requester. If row["channel"] != by_channel or row["sender_id"] != by_sender, ApprovalError("decisore non autorizzato"): who requested is who can approve. This is the identity axis described in ch. 5 of the Architecture.

Only after the four checks does the final UPDATE write the decision and return the updated PendingRequest.

7. Telegram callback dispatcher

What remains to explain is how a click on the "Approva" button on Telegram becomes a call to approval_registry.resolve(). The chain crosses three components: the channel out (which drew the buttons), the channel in (which receives the callback), the daemon dispatcher.

7.1 Outbound buttons

OutboundMessage.buttons is list[list[dict]]; each dict has the keys text (visible label) and data (callback_data that will return to the server). render_approval_card uses a single row of two buttons:

buttons = [[
    {"text": "Approva", "data": f"approve:{req.token}"},
    {"text": "Rifiuta", "data": f"reject:{req.token}"},
]]

TelegramChannel.send translates this structure into reply_markup.inline_keyboard in Telegram format (runtime/channels/telegram.py:108-114). The buttons are thus shown attached to the card message.

7.2 Incoming callback_query

When the user clicks, Telegram does not send a new message: it sends a callback_query object in the next getUpdates. TelegramChannel.poll recognises it explicitly. Reference: runtime/channels/telegram.py:135-156:

cbq = u.get("callback_query")
if cbq:
    msg_ctx = cbq.get("message") or {}
    out.append(InboundMessage(
        channel=self.name,
        sender_id=str(cbq.get("from", {}).get("id")
                       or msg_ctx.get("chat", {}).get("id", "")),
        text=cbq.get("data", ""),
        message_id=str(msg_ctx.get("message_id", "")),
        received_at=float(msg_ctx.get("date", time.time())),
        extra={"kind": "callback", "callback_id": cbq.get("id"),
                "from": cbq.get("from", {}), "update_id": uid},
    ))
    cb_id = cbq.get("id")
    if cb_id:
        self._call("answerCallbackQuery", {"callback_query_id": cb_id})
    continue

Three details to note. (a) The text of the InboundMessage is not human text: it is the raw callback_data (approve:<tok> or reject:<tok>). (b) The sender_id is taken from cbq.from.id (who clicked), with fallback to the original chat: it serves to verify that the clicker is the one who generated the request. (c) The marker extra={"kind": "callback"} distinguishes the message from regular texts when the dispatcher decides how to treat it. The final call to answerCallbackQuery is required by Telegram to remove the loading spinner on the clicked button; it sends no content, just an acknowledgement.

7.3 Dispatch in the daemon

ChannelDaemon.handle_message looks at extra.kind first: if it is callback, it routes to the dedicated dispatcher. Reference: runtime/channels/daemon.py:122-154 and runtime/channels/daemon.py:156-162:

def _handle_callback(self, msg: InboundMessage) -> dict:
    """Resolves an 'approve:<token>' or 'reject:<token>' callback_query."""
    data = (msg.text or "").strip()
    if data.startswith("approve:"):
        decision = "approved"
        token = data[len("approve:"):]
        user_label = "Approvato"
    elif data.startswith("reject:"):
        decision = "rejected"
        token = data[len("reject:"):]
        user_label = "Rifiutato"
    else:
        log.warning("callback_data non riconosciuto: %r", data)
        return {"ok": False, "reason": "unknown_callback", "data": data}
    if not token:
        return {"ok": False, "reason": "missing_token"}
    try:
        rec = approval_registry.resolve(
            token, decision,
            by_channel=self.channel.name, by_sender=msg.sender_id,
        )
    except approval_registry.ApprovalError as e:
        self._send_text(msg.sender_id,
                        f"Approval non risolvibile: {e}",
                        reply_to=msg.message_id)
        return {"ok": False, "reason": "approval_failed", "error": str(e)}
    log.info("approval risolto: token=%s decision=%s sender=%s",
             token, decision, msg.sender_id)
    self._send_text(msg.sender_id,
                    f"{user_label}: {rec.action_verb} {rec.target_summary}",
                    reply_to=msg.message_id)
    return {"ok": True, "decision": decision, "token": token,
            "capability_class": rec.capability_class}

The logic is linear: parsing of the approve: / reject: prefix, extraction of the token, call to resolve(), textual confirmation to the user. Any ApprovalError (token already resolved, expired, decider not authorised) is translated into an error message to the sender.

7.4 The identity axis in practice

Architecture ch. 5 distinguishes three security axes: freedom/safety, identity/safety, perimeter/robustness. The approval flow puts the identity axis to work: every request is tagged with the channel and sender that generated it, and every resolution verifies the decider's identity before consuming the token. An attacker who managed to sniff a token and use it from another chat ID would not be able to resolve it: ApprovalError("decisore non autorizzato").

8. Tests

Three groupings, all green as of 27 April 2026. The numbers point to clusters in the runtime test framework.

8.1 Cluster approval_registry (6/6)

8.2 Cluster channels — callback dispatcher (5/5)

8.3 Module cases — card rendering (3)

9. End-to-end examples

Three examples of the same request at three recurrence stages. Buttons are rendered as pseudo-elements below the card.

In all cases the two buttons have callback_data of the form approve:<tok> and reject:<tok>; the token is the same one the approval_registry issued when the request was created. When the user clicks, the flow described in ch. 7 starts: the callback_query reaches the daemon, _handle_callback calls resolve(), the user receives the textual confirmation "Approvato: scarichi rapporto.pdf da drive.google.com -> ~/downloads/ (~2.4 MB)".

10. Limits and what is deferred to v1.2+

Final notes

approval_ux is a small component by lines of code (renderer ~90 lines, registry ~280, dispatcher ~30 in the daemon) but dense in meaning: it is the moment when Metnos pauses and asks. The care of the 3-line card — conjugated verb, readable object, meta classification — is not aesthetic: it is the way an informed user decision is made possible in two seconds.

The decider = requester rule, written inside resolve(), is the fixed point that allows the callback dispatcher to precede the pairing check without creating holes. It does not trust the dispatcher; it trusts only the registry. Security is concentrated in the right place.