approval-md 0.4.0 → 0.4.2

package/schema/fixtures/policy/valid/delegation-off.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "delegation": {
+    "model": null,
+    "classes": [],
+    "max_autonomy": "manual",
+    "daily_cap": 0,
+    "escalate_on": [],
+    "advice": false,
+    "reviewers": []
+  }
+}

package/schema/fixtures/policy/valid/tools-mapping.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "unmapped_tool": "record"
+  },
+  "classes": {
+    "marketplace.*": { "autonomy": "manual" },
+    "marketplace.app.read": { "autonomy": "autonomous" },
+    "harness.tool.unmapped": { "autonomy": "supervised-retro" }
+  },
+  "tools": [
+    { "match": "mcp__contextsling__publish", "class": "marketplace.contextsling.publish" },
+    { "match": "mcp__contextsling__*", "class": "marketplace.app.read" },
+    { "match": "*", "class": "marketplace.app.read" }
+  ]
+}

package/schema/policy.schema.json

@@ -41,6 +41,12 @@
           "default": "manual",
           "examples": ["manual", "sealed"]
         },
+        "unmapped_tool": {
+          "type": "string",
+          "enum": ["record", "ask"],
+          "description": "SPEC.md §5.2 (APRV-499, proposed): what a harness hook does with a tool call that neither the harness adapter's own tables (its shell, file, read and pass-through tools and its hard-coded rule table) nor any `tools` entry claims. `record`: the call is classified `harness.tool.unmapped`, which resolves `autonomous` when no `classes` rule matches it, so it proceeds and leaves an `execution.started` naming the tool. `ask`: the same class resolves `manual` when no rule matches it, so the call waits for a human. A `classes` rule matching `harness.tool.unmapped` decides it instead, exactly as a rule decides any class over `defaults.autonomy`. ABSENT, the behaviour of every policy written before the key existed: such a call is not a gate question, is allowed, and leaves no record.",
+          "examples": ["record", "ask"]
+        },
         "on_expiry": {
           "type": "string",
           "enum": ["reject"],
@@ -85,6 +91,112 @@
         ]
       ]
     },
+    "tools": {
+      "type": "array",
+      "description": "SPEC.md §5.2 (APRV-499, proposed): the classes a harness's OWN tool calls are judged under, by tool name, for the calls the harness adapter's built-in tables do not claim (every MCP tool, `mcp__<server>__<tool>` on Claude Code, among them). ORDERED: the first entry whose `match` matches the tool name decides, and later entries are not read. The adapter's own tables keep precedence over every entry, because they read the call's arguments and an entry reads only its name: an entry matching `terminal`, `Bash` or a Hermes `cronjob_manage` is inert. An entry's `class` must be declared by `classes`, as an exact key or under a trailing family key `<prefix>.*` whose literal prefix it extends (checked at load); an undeclared class fails the policy closed, because a mapping to a class nothing prices would resolve by `defaults.autonomy` and read as a decision nobody made. Absent or empty: no tool is mapped.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["match", "class"],
+        "properties": {
+          "match": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^(?:[A-Za-z0-9_.:-]|\\*(?!\\*))+$",
+            "description": "The harness tool name this entry claims, compared case-sensitively against the WHOLE name. `*` is the only wildcard and matches any run of characters, including none, so `mcp__contextsling__*` claims every tool of that MCP server and `*` claims every tool nothing earlier claimed. Two `*` in a row, and every character outside letters, digits, `_`, `.`, `:` and `-`, are schema violations: a pattern language half-implemented here would be a mapping the author believed was in force and the runtime did not apply.",
+            "examples": ["mcp__contextsling__*", "mcp__zzz__post", "web_search"]
+          },
+          "class": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^[a-z0-9][a-z0-9_-]*(?:\\.[a-z0-9][a-z0-9_-]*)*$",
+            "description": "The concrete class (no wildcard) the call is judged under. It must be an exact key of `classes` or extend the literal prefix of a declared trailing family key (`marketplace.*` covers `marketplace.contextsling.publish`), and it may not be `harness.tool.unmapped`, which names the calls no entry claimed (both checked at load).",
+            "examples": ["marketplace.contextsling.publish", "marketplace.app.read"]
+          }
+        }
+      },
+      "examples": [
+        [
+          { "match": "mcp__contextsling__publish", "class": "marketplace.contextsling.publish" },
+          { "match": "mcp__contextsling__*", "class": "marketplace.app.read" }
+        ]
+      ]
+    },
+    "delegation": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.2 (APRV-500, proposed; RESERVED in 0.4.2, no behaviour): the judge, a pinned model that may later review supervised samples, advise on manual cards, and decide manual cards in named classes within bounds. This release parses and validates the block and does nothing with it. It loads only in its OFF form (`model` null or absent, `classes` empty, `max_autonomy: manual`, `daily_cap: 0`, `escalate_on` empty, `advice: false`, `reviewers` empty; an empty mapping is the same thing), and the off form changes no resolution, no request and no record. ANY other value fails the policy closed with the load code `delegation-not-supported`, so every class resolves `manual`: a core that accepted `daily_cap: 10` and did nothing would be a setting its author believed was in force and the runtime silently ignored, which this closed schema exists to prevent. The relationships between keys (classes are exact keys of `classes`, the `max_autonomy` pin, the escalation floors, reviewer identities) are checked at load before the off-form check and fail closed as `schema-invalid`. Absent: the behaviour of every policy written before the key existed.",
+      "properties": {
+        "model": {
+          "anyOf": [{ "$ref": "#/$defs/modelIdentity" }, { "type": "null" }],
+          "description": "The judge identity whose records a later core would accept, `model:<name>@<major>.<minor>.<patch>`. The version pins the judge release (prompt, rubric and model snapshot). `null` or absent: no judge, and every other key is inert. RESERVED: any non-null value is `delegation-not-supported` in 0.4.2.",
+          "examples": [null, "model:judge@0.3.0"]
+        },
+        "classes": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^[a-z0-9][a-z0-9_-]*(?:\\.[a-z0-9][a-z0-9_-]*)*$"
+          },
+          "description": "The classes the judge may act on. Each entry is a concrete class (no wildcard, no `*`) and must be an EXACT key of `classes` whose own autonomy is neither `human-only` nor `autonomous` (checked at load): the delegated set is a set of lines the operator wrote by name, the reasoning `agent_may_request` uses. RESERVED: a non-empty list is `delegation-not-supported` in 0.4.2.",
+          "examples": [[], ["intent.publish.inferred.index"]]
+        },
+        "max_autonomy": {
+          "type": "string",
+          "enum": ["manual", "supervised-live", "supervised-retro"],
+          "default": "manual",
+          "description": "A non-loosening PIN between this block and the class rows. Every class listed in `classes` must declare an autonomy at least as strict as this value in SPEC.md §5.2's strictness order (checked at load, `schema-invalid` otherwise). It is a tamper pin rather than a dial: loosening a delegated class's row without rewriting this block fails the load, so the judge's scope never grows as a side effect of an unrelated edit. Absent means `manual`. RESERVED: any value other than `manual` is `delegation-not-supported` in 0.4.2.",
+          "examples": ["manual"]
+        },
+        "daily_cap": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1000,
+          "default": 0,
+          "description": "The most judge grants in any rolling 24 hours, across every delegated class together. 0 means the delegated approver is off. A value above 0 requires `escalate_on` to contain `irreversible` and `unknown_class` and requires `model` (checked at load). RESERVED: any value other than 0 is `delegation-not-supported` in 0.4.2.",
+          "examples": [0]
+        },
+        "escalate_on": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["deny", "low_confidence", "irreversible", "unknown_class"]
+          },
+          "description": "The judge outcomes that go to a human instead of standing, from a fixed set. RESERVED: a non-empty list is `delegation-not-supported` in 0.4.2.",
+          "examples": [[], ["deny", "low_confidence", "irreversible", "unknown_class"]]
+        },
+        "advice": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the judge writes advice on manual cards in `classes`. `true` requires `model` (checked at load). RESERVED: `true` is `delegation-not-supported` in 0.4.2.",
+          "examples": [false]
+        },
+        "reviewers": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/delegationReviewer" },
+          "description": "Identities admitted to review samples of `classes`, in addition to each class's `approvers` roster: `human:<approver id>`, naming a key of `approvers`, or `model:<name>@<version>`, which must equal `model` exactly (both checked at load). This list is the ONLY place a `model:` identity is admitted: grants, attestations, reviews and channel decisions still require `human:`. RESERVED: a non-empty list is `delegation-not-supported` in 0.4.2.",
+          "examples": [[], ["model:judge@0.3.0", "human:alice"]]
+        }
+      },
+      "examples": [
+        {
+          "model": null,
+          "classes": [],
+          "max_autonomy": "manual",
+          "daily_cap": 0,
+          "escalate_on": [],
+          "advice": false,
+          "reviewers": []
+        }
+      ]
+    },
     "read_scope": {
       "type": "object",
       "additionalProperties": false,
@@ -333,6 +445,20 @@
     }
   },
   "$defs": {
+    "modelIdentity": {
+      "type": "string",
+      "maxLength": 128,
+      "pattern": "^model:[a-z0-9][a-z0-9-]{0,63}@[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "SPEC.md §5.2 (APRV-500, proposed; RESERVED): a judge identity, `model:<name>@<major>.<minor>.<patch>`. `<name>` is the judge service (lowercase alphanumerics and `-`, at most 64 characters) and the version pins one judge release. No record written by this release carries one: the event schema's actor patterns are unchanged, so a `model:` actor is refused at the write boundary.",
+      "examples": ["model:judge@0.3.0"]
+    },
+    "delegationReviewer": {
+      "type": "string",
+      "maxLength": 128,
+      "pattern": "^(?:human:[a-z0-9][a-z0-9_-]*|model:[a-z0-9][a-z0-9-]{0,63}@[0-9]+\\.[0-9]+\\.[0-9]+)$",
+      "description": "SPEC.md §5.2 (APRV-500, proposed; RESERVED): a reviewer identity in `delegation.reviewers`. `human:<approver id>` (the approver identifier grammar) or a `modelIdentity`.",
+      "examples": ["human:alice", "model:judge@0.3.0"]
+    },
     "promptRow": {
       "type": "string",
       "enum": [
@@ -386,6 +512,58 @@
           "$ref": "#/$defs/promptRows",
           "description": "Visibility DOWN: the row never renders on this channel. Refused for the rows required for a decision — `action_key`, `class`, `command_breakdown`, `protected_path`, `policy_diff`, `policy_load` — and refused at policy load with the machine-readable keyword `prompt-row-required`, which fails the whole policy closed. `payload_hash` is NOT among them because the bound hash is stated inside the canonical block on every channel, so hiding the row removes a duplicate rather than the binding. Naming one row in both `always` and `hide` is refused rather than resolved by precedence: an author who wrote both believes one of them, and picking for them would be a guess.",
           "examples": [["provenance", "chain", "requested_ts"]]
+        },
+        "style": {
+          "type": "string",
+          "enum": ["technical", "minimal"],
+          "default": "technical",
+          "description": "SPEC.md §5.2/§10.3 (APRV-489): how this channel lays out a prompt. `technical`, the default and what an absent key means, is the card every earlier build sent, byte for byte. `minimal` is a short card in plain words: a headline the runtime computes from the class, the payload's own words quoted from the bound bytes, a deadline in plain words, and the whole technical card, canonical rendering included, collapsed inside the same message as the Approve and Deny buttons (SPEC.md §10.3, amended APRV-489). Only Telegram draws it in this release; on `web` and `cli` the key is validated and IGNORED, which shows more than was asked for and never less. A request the minimal card cannot draw honestly (an opaque payload without a `say` declaration naming every key, an attestation, a policy edit, a digest, a truncated payload, an abnormal health row, a card over the message limit) is sent as the technical card. Review cards never change. The enum is closed: an unknown style fails validation, which fails the policy closed to all-`manual`.",
+          "examples": ["minimal"]
+        },
+        "say": {
+          "type": "object",
+          "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*(?:\\.[a-z0-9][a-z0-9_-]*)*$" },
+          "additionalProperties": { "$ref": "#/$defs/promptSay" },
+          "description": "SPEC.md §5.2 (APRV-489): what the minimal card says about a class, keyed by EXACT class name (no wildcard: one friendly phrase must never stand for several classes). Operator text the approver attests, never agent text. Read only under `style: minimal`.",
+          "examples": [
+            {
+              "digest.share": {
+                "does": "share a note about you",
+                "quote": { "scope": "Shared with", "expires_at": "Until", "text": "Note", "digest_id": null },
+                "note": "none"
+              }
+            }
+          ]
+        }
+      }
+    },
+    "promptSay": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.2 (APRV-489): one class's minimal-card declaration. `does` is required for a class core does not phrase itself and refused for one it does, or for a class the command classifier emits (checked at load). It is drawn only over an opaque payload: over a command, a file change or an email the runtime draws its own kind phrase.",
+      "properties": {
+        "does": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "description": "The plain-words verb phrase the headline completes: `Your agent wants to <does>`. Starts with a letter; no line break, sentence punctuation (. ! ? … : ;), markup or ⚠ (checked at load). Not allowed for a class core phrases itself or a class the command classifier emits (`prompt-say-kind`). Drawn only over an opaque payload: over a command, a file change or an email the runtime's kind phrase is drawn instead and the decision record notes `say_does_ignored`. The runtime chooses the entry by the exact class the log records."
+        },
+        "quote": {
+          "type": "object",
+          "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "string", "maxLength": 24 },
+              { "type": "null" }
+            ]
+          },
+          "description": "The closed field set for an OPAQUE payload: every top-level key the payload may carry, mapped to the label its value is quoted under (`\"\"` for no label), or `~` for a key known and deliberately left off the simple card (the card then names it under the quotations). At least one key must be shown (checked at load). A payload carrying any key this map does not name is sent as the technical card. Ignored for command, file-change and email payloads, whose excerpt is built in."
+        },
+        "note": {
+          "type": "string",
+          "enum": ["summary", "none"],
+          "default": "summary",
+          "description": "Whether the agent's own summary is shown, labelled as the agent's and as not checked: `summary` (the default) or `none`."
         }
       }
     },