approval-md 0.4.1 → 0.4.3

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": [