approval-md 0.4.1 → 0.4.3

package/schema/event.schema.json

@@ -70,7 +70,7 @@
     "actor": {
       "type": "string",
       "pattern": "^(human|agent|system):.+",
-      "description": "SPEC.md §8: who caused the event, as `<kind>:<id>` (the example record uses `human:carter`). Three kinds: `human:` for a person acting through a channel or the CLI, `agent:` for an agent-originated event, and `system:` for events the daemon originates with no external prompt (for example `approval.expired`, which fires on TTL lapse rather than on any actor's action). Approval decisions are restricted to `human:` — see the per-type rules below."
+      "description": "SPEC.md §8: who caused the event, as `<kind>:<id>` (the example record uses `human:carter`). Three kinds: `human:` for a person acting through a channel or the CLI, `agent:` for an agent-originated event, and `system:` for events the daemon originates with no external prompt (for example `approval.expired`, which fires on TTL lapse rather than on any actor's action). Approval decisions are restricted to `human:` — see the per-type rules below. A fourth kind, `model:<name>@<version>` (the judge, a pinned model reviewer), is RESERVED by APRV-500 (amended SPEC.md §5.2 proposed) and deliberately absent from this pattern: no record written by this release carries it, so a `model:` actor is refused here at the write boundary until a later core admits it on named events."
     },
     "alg": {
       "const": "sha256/jcs",
@@ -274,7 +274,7 @@
             "verdict_source": {
               "type": "string",
               "const": "explicit",
-              "description": "SPEC.md §5.2 (amended, PR #614 refutation F5): how the verdict was given. `explicit` is the only value: since APRV-482 a verdict is said by the reviewer (`--ok`/`--deny`, a card's OK or second Deny) and never defaulted. A review written before then may carry `verdict: \"ok\"` that the runtime filled in for a grade-only tap or a bare terminal review, and nothing else in the record tells the two apart, so this field is the discriminator a follower reads: present means explicit, absent (on an old record) means the verdict may have been defaulted. REQUIRED on new records."
+              "description": "SPEC.md §5.2 (amended, PR #614 refutation F5): how the verdict was given. `explicit` is the only value: since APRV-482 a verdict is said by the reviewer (`--ok`/`--deny`, a card's OK or second Deny) and never defaulted. A review written before then may carry `verdict: \"ok\"` that the runtime filled in for a grade-only tap or a bare terminal review, and nothing else in the record tells the two apart, so this field is the discriminator a follower reads: present means explicit, absent (on an old record) means the verdict may have been defaulted. REQUIRED on new records. A second value, `model` (a review given by the judge, `model:<name>@<version>`), is RESERVED by APRV-500 (amended SPEC.md §10.3 proposed): registered so the word means nothing else, never written by this release, and refused here by the `const`. A follower that meets it may ignore it, and then never counts a model review as a human approval."
             },
             "payload_hash": {
               "type": "string",
@@ -1007,6 +1007,38 @@
         }
       }
     },
+    {
+      "$comment": "SPEC.md §8 (APRV-499, proposed): a harness `execution.started` whose class came from the policy's tool mapping (a `tools` entry, or `harness.tool.unmapped` under `defaults.unmapped_tool`) carries `harness_tool`, the harness tool NAME the call was made under, because several tools share one such class and the class alone cannot say which ran. The name only: the call's arguments are bound by `payload_hash` and are never written to the log. OPTIONAL and additive: every record written before the field existed still validates and still verifies, and a start on any other path records none. Only the SHAPE is constrained here: the characters a `tools` match may name (letters, digits, `_`, `.`, `:`, `-`), at most 256 of them, so a name outside that set refuses the append rather than writing bytes no mapping could have named.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "execution.started"
+          }
+        },
+        "required": [
+          "event"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "properties": {
+              "harness_tool": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 256,
+                "pattern": "^[A-Za-z0-9_.:-]+$",
+                "description": "SPEC.md §8 (APRV-499, proposed): the harness tool name a policy-mapped or unmapped harness execution was made under.",
+                "examples": ["mcp__contextsling__publish"]
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "$comment": "SPEC.md §10.3 (amended, APRV-38): a decision collected as part of a batch gesture carries the batch's channel delivery id as a first-class payload field. Optional — a unit decision has no batch — and constrained only when present, so the field can never arrive as an empty string or a number that audit would have to guess at.",
       "if": {

package/schema/fixtures/event/invalid/audit-reviewed-model-actor.json

@@ -0,0 +1,20 @@
+{
+  "seq": 16,
+  "ts": "2026-08-04T09:26:02Z",
+  "event": "audit.reviewed",
+  "task": "task-049",
+  "action_key": "task-049:archive:2026-08-04",
+  "actor": "model:judge@0.3.0",
+  "channel": "cli",
+  "payload": {
+    "subject_seq": 15,
+    "subject_event": "audit.sampled",
+    "reviewed": true,
+    "sampled_subject_hash": "6c1d3f0b9a8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a392817060504",
+    "verdict": "ok",
+    "verdict_source": "explicit"
+  },
+  "alg": "sha256/jcs",
+  "prev": "7f625051c176f2f260a1f7e25c9a933717ebb49917a8788ac25ae7a4614ebb30",
+  "hash": "6752e6617b2b810c1cc0cf09c51678c78891ff6fdfd8bb9399aecbdfca00dd5b"
+}

package/schema/fixtures/event/invalid/audit-reviewed-verdict-source-model.json

@@ -0,0 +1,20 @@
+{
+  "seq": 16,
+  "ts": "2026-08-04T09:26:02Z",
+  "event": "audit.reviewed",
+  "task": "task-049",
+  "action_key": "task-049:archive:2026-08-04",
+  "actor": "human:carter",
+  "channel": "cli",
+  "payload": {
+    "subject_seq": 15,
+    "subject_event": "audit.sampled",
+    "reviewed": true,
+    "sampled_subject_hash": "6c1d3f0b9a8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a392817060504",
+    "verdict": "ok",
+    "verdict_source": "model"
+  },
+  "alg": "sha256/jcs",
+  "prev": "7f625051c176f2f260a1f7e25c9a933717ebb49917a8788ac25ae7a4614ebb30",
+  "hash": "6752e6617b2b810c1cc0cf09c51678c78891ff6fdfd8bb9399aecbdfca00dd5b"
+}

package/schema/fixtures/event/invalid/execution-started-harness-tool-space.json

@@ -0,0 +1,18 @@
+{
+  "seq": 12,
+  "ts": "2026-10-05T22:50:00Z",
+  "event": "execution.started",
+  "task": "hook:sess-1:tu-4",
+  "action_key": "hook:sess-1:tu-4:harness.tool.unmapped",
+  "actor": "agent:claude-code",
+  "payload": {
+    "class": "harness.tool.unmapped",
+    "est_cost_usd": "0",
+    "execution": "harness",
+    "payload_hash": "3c987d69fe833bbea2b588ea7e7bc0848bbfb90703b298729a3d2d6d45346011",
+    "harness_tool": "mcp tool\nwith a line break"
+  },
+  "alg": "sha256/jcs",
+  "prev": "d973375d6aeec5e6cd2de3a0f7dc8f5bc1d9be77225f9af0f851e7fc519a07c3",
+  "hash": "4b7e0c2d9a8f6e5d4c3b2a1908f7e6d5c4b3a2918f7e6d5c4b3a291807f6e5d4"
+}

package/schema/fixtures/event/valid/execution-started-harness-tool.json

@@ -0,0 +1,19 @@
+{
+  "seq": 12,
+  "ts": "2026-10-05T22:50:00Z",
+  "event": "execution.started",
+  "task": "hook:sess-1:tu-4",
+  "action_key": "hook:sess-1:tu-4:harness.tool.unmapped",
+  "actor": "agent:claude-code",
+  "payload": {
+    "class": "harness.tool.unmapped",
+    "est_cost_usd": "0",
+    "execution": "harness",
+    "payload_hash": "3c987d69fe833bbea2b588ea7e7bc0848bbfb90703b298729a3d2d6d45346011",
+    "policy_sha256": "5f1c0de9a3b7e2d4c6f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e",
+    "harness_tool": "mcp__contextsling__publish"
+  },
+  "alg": "sha256/jcs",
+  "prev": "d973375d6aeec5e6cd2de3a0f7dc8f5bc1d9be77225f9af0f851e7fc519a07c3",
+  "hash": "4b7e0c2d9a8f6e5d4c3b2a1908f7e6d5c4b3a2918f7e6d5c4b3a291807f6e5d4"
+}

package/schema/fixtures/policy/invalid/delegation-advice-string.json

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

package/schema/fixtures/policy/invalid/delegation-class-duplicate.json

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

package/schema/fixtures/policy/invalid/delegation-class-wildcard.json

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

package/schema/fixtures/policy/invalid/delegation-daily-cap-fractional.json

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

package/schema/fixtures/policy/invalid/delegation-daily-cap-negative.json

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

package/schema/fixtures/policy/invalid/delegation-daily-cap-too-high.json

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

package/schema/fixtures/policy/invalid/delegation-escalate-duplicate.json

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

package/schema/fixtures/policy/invalid/delegation-escalate-unknown.json

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

package/schema/fixtures/policy/invalid/delegation-max-autonomy-alias.json

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

package/schema/fixtures/policy/invalid/delegation-max-autonomy-autonomous.json

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

package/schema/fixtures/policy/invalid/delegation-model-no-version.json

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

package/schema/fixtures/policy/invalid/delegation-model-provider-form.json

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

package/schema/fixtures/policy/invalid/delegation-null.json

@@ -0,0 +1,7 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "delegation": null
+}

package/schema/fixtures/policy/invalid/delegation-reviewer-agent.json

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

package/schema/fixtures/policy/invalid/delegation-reviewer-bare-id.json

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

package/schema/fixtures/policy/invalid/delegation-unknown-key.json

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

package/schema/fixtures/policy/invalid/tools-class-wildcard.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.1",
+  "classes": {
+    "marketplace.*": { "autonomy": "manual" }
+  },
+  "tools": [
+    { "match": "mcp__contextsling__*", "class": "marketplace.*" }
+  ]
+}

package/schema/fixtures/policy/invalid/tools-match-double-star.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.1",
+  "classes": {
+    "marketplace.*": { "autonomy": "manual" }
+  },
+  "tools": [
+    { "match": "mcp__**", "class": "marketplace.app.read" }
+  ]
+}

package/schema/fixtures/policy/invalid/unmapped-tool-unknown.json

@@ -0,0 +1,7 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual",
+    "unmapped_tool": "allow"
+  }
+}

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

@@ -0,0 +1,7 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "delegation": {}
+}

package/schema/fixtures/policy/valid/delegation-grammar-full.json

@@ -0,0 +1,41 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "approvers": {
+    "resident": {
+      "channels": [
+        "telegram"
+      ]
+    }
+  },
+  "classes": {
+    "intent.publish.inferred.index": {
+      "autonomy": "manual"
+    },
+    "digest.share": {
+      "autonomy": "manual"
+    }
+  },
+  "delegation": {
+    "model": "model:judge@0.3.0",
+    "classes": [
+      "intent.publish.inferred.index",
+      "digest.share"
+    ],
+    "max_autonomy": "manual",
+    "daily_cap": 10,
+    "escalate_on": [
+      "deny",
+      "low_confidence",
+      "irreversible",
+      "unknown_class"
+    ],
+    "advice": true,
+    "reviewers": [
+      "model:judge@0.3.0",
+      "human:resident"
+    ]
+  }
+}

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" }
+  ]
+}