1. What policy is

Policy is the legality filter of Metnos: layer 2 of the architecture (ch. 6 of the Architecture). For every combination of autonomy level, capability and target it decides one outcome among allowed, denied, approval_required. It is the module that embodies the rules shared between Roberto and the agent: what may be done without asking, what must be asked, what is never done.

Policy lives alongside two other layers that decide different things, and this is the clarity point that v1.0 lacked:

• policy decides the right — does this level have title to do this thing on this target?
• the vaglio decides sense — does it make sense to do it, given the request context?
• the sandbox confines execution — once we decide to act, we act inside a kernel-level shell that bounds damage.

The three filters are in series: policy runs first (it is the cheapest, a table lookup plus an optional SQLite query); if it passes, vaglio applies contextual LLM judgement; if vaglio also passes, the sandbox wraps the invocation. The runtime/policy.py module is ~360 lines, no daemon, no global state apart from the table cache and the grants SQLite file.

2. Capability Registry v1.1

The registry is the closed dictionary of actions Metnos recognises. Thirteen canonical entries, defined in runtime/policy.py:CAPABILITY_REGISTRY (runtime/policy.py:46-121). Each entry is a CapabilitySpec with four attributes:

• name — the canonical name (format family:mode, e.g. fs:read);
• critical — True if the action is irreversible or high-stakes (write, send, exec);
• default_approval — default approval mode: none (never), per_target (once per new target), always (every time, even for previously seen targets);
• target_kind — target type: path_glob, host, exact, none.

The registry is closed: record_grant rejects a capability that is not in it (runtime/policy.py:243-244). Adding a capability means modifying the registry in code and running the tests — no runtime registration. This is a deliberate choice: the action vocabulary is a security asset, not an extension surface freely open.

2.1 Reading the registry

Three families are critical: fs:write, code:exec, mail:send. These are actions that change the world irreversibly (a written file, an already-run shell command, a sent email). Two of them have default_approval = always: code:exec and mail:send. Even at the highest autonomy level, these two always pass through an explicit confirmation.

Four capabilities have default_approval = none: llm:local, channel:in, time:read, parse:local. These are zero-cost, reversible actions, with no side effects on the outside world (listening to a channel, reading a clock, parsing a PDF inside the sandbox). They stay outside the approval flow even at the most conservative level.

3. Autonomy × capability table

The table is the cartesian product of the three autonomy levels (ReadOnly, Supervised, Full) by the 13 capabilities. For each cell an outcome: allowed, approval_required, denied. Generated in runtime/policy.py:_TABLE and _init_table (runtime/policy.py:140-171) according to canonical rules, not hand-written.

3.1 The three rules that generate the table

The table is not arbitrary: it derives from three rules, one per level, that _init_table applies while iterating over the registry.

ReadOnly. Read-only capabilities only, no side effects visible to the outside world. Never write, never send, never exec, never online LLM (which carries an outgoing monetary cost). Read capabilities with default_approval = per_target (fs:read, mail:read, calendar:read) stay approval_required: the most conservative level does not give them up but asks confirmation for each new target. Critical ones and others with default per_target or always become denied.

Supervised. Everything ReadOnly can do, plus it raises denied to approval_required: every capability with default_approval ≠ none requires approval. This is the level at which the system is fully operational but every action with effects on the world goes through Roberto.

Full. All allowed except capabilities with default_approval = always: code:exec and mail:send stay approval_required. These are the two where a mistake cannot be undone, and for that reason they are never granted without explicit confirmation, regardless of trust level.

4. Persistent per_target grants

The table alone is not enough. When Roberto approves a request — "yes, go ahead and write to ~/Documents/invoices-2026/* for the next two months" — we want the system to remember that concession and not ask again for every saved file. The memory of these concessions lives in a single-file SQLite table: the grants.

4.1 SQLite schema

Defined in runtime/policy.py:SCHEMA (runtime/policy.py:186-202):

CREATE TABLE IF NOT EXISTS grants (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    channel         TEXT NOT NULL,
    sender_id       TEXT NOT NULL,
    capability      TEXT NOT NULL,
    target          TEXT NOT NULL,
    granted_at      TEXT NOT NULL,
    expires_at      TEXT,
    granted_by      TEXT,
    revoked_at      TEXT
);

A grant is identified by the four-tuple (channel, sender_id, capability, target): who approved (e.g. Telegram + user Roberto), for which action, on which target. Dates granted_at/expires_at/revoked_at are ISO 8601 UTC. Two indexes accelerate the two typical queries: exact lookup and active-grants scan.

File path: ~/.local/state/metnos/grants.db, override available via the METNOS_GRANTS_DB environment variable (runtime/policy.py:27, 223-229). The parent folder is created on first access.

4.2 API

All four functions open and close the connection per call: no in-memory state. Throughput is not the point — we are in the few-queries-per-second regime — and per-call isolation simplifies test reasoning.

4.3 When grants are written

In v1.1 the policy module is read-only from the planner: the planner reads the table and the grants but never creates them. Creation happens in the approval dispatcher (ch. 5 phase 5, see approval_ux): when a pending request resolves as approved with scope this and similar, the dispatcher calls record_grant and from that moment the concession is persistent.

5. Combined outcome (effective_outcome)

The effective_outcome function (runtime/policy.py:330-355) is the single entry point for the planner. It combines table and grants into one outcome, according to four cases:

The logic is linear: if the table already decides cleanly (allowed or denied), the grant is not even consulted; if it decides approval_required, an active grant turns it into allowed, otherwise it stays approval_required.

5.1 Concrete examples

6. Runtime integration

In v1.1 runtime/policy.py is a separate module, complete and tested, but not yet stitched into the planner. Integration into agent_runtime is the last line of phase 5 and will arrive in the next iteration. The planned shape:

def execute_step(step, ctx):
    cap = step.capability        # e.g. "fs:write"
    target = step.target         # e.g. "/home/roberto/Documents/invoices-2026/04.pdf"
    outcome = policy.effective_outcome(
        ctx.autonomy_level,      # "ReadOnly" | "Supervised" | "Full"
        cap,
        channel=ctx.channel,     # e.g. "telegram"
        sender_id=ctx.sender_id, # e.g. "roberto"
        target=target,
    )
    if outcome == "denied":
        return Refused(reason="insufficient level for " + cap)
    if outcome == "approval_required":
        pending = approval_registry.create_pending(step, ctx)
        channels.approval.render_approval_card(pending, ctx.channel)
        return Awaiting(pending_id=pending.id)
    # outcome == "allowed"
    return invoke_executor(step.executor, step.args, autonomy=ctx.autonomy_level)

Three references to existing modules:

• approval_registry.create_pending queues the request and returns an id;
• channels.approval.render_approval_card composes the three-line card and sends it on the originating channel (see approval_ux);
• invoke_executor is the same point at which the sandbox wraps the command; the autonomy parameter is already pass-through (ch. 6 of sandbox.html).

The planner never reads the table or the grants directly: it makes a single call to effective_outcome and branches on the outcome. This keeps policy as the single source of truth for the rules; the day the rules change (v1.2: cost tier, rate limit), the planner is not touched.

7. CLI

The module is runnable as a script (runtime/policy.py:360-423): useful for manual inspection and to build dashboards in a few lines. Four subcommands.

JSON-line output makes piping into jq easy: for instance python3 -m policy table | jq shows the matrix in readable form.

8. Tests

Cluster policy in the runtime test framework: 10/10 green as of April 27, 2026. Cases cover the registry, the three table rules, the grants round-trip, and the security invariant separating denied from grant-elevatable cases.

The three [security]-marked cases are the invariants that bind future evolution of the module: any change that breaks them is a dismantling of the security posture, not a refactor.

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

Final notes

Policy is a small module by design: all the complexity of the legality filter lives in two structures readable at a glance (a 13-entry dictionary, a 3×13 table) plus a SQLite round-trip for grants. No DSL, no rules expressed in natural language, no runtime configuration that can break by loading a malformed file.

The constraint that a grant can never elevate a denied to allowed is the heart of the separation between the tactical plane (targeted concession, inside a level that allows it) and the strategic plane (the level itself, chosen deliberately during pairing). Keeping these two planes distinct is what allows Metnos to scale in autonomy without sliding toward more permissions than intended.