approval-md 0.4.1 → 0.4.2

package/dist/src/core/tool-map.js

@@ -0,0 +1,179 @@
+/**
+ * Policy-declared tool-name mapping (APRV-499, amended SPEC.md §5.2 proposed).
+ *
+ * A harness hook classifies a tool call through the adapter's own tables: its
+ * shell tool, its file and read tools, its pass-through tools, and (Hermes) a
+ * hard-coded rule table over the harness's side-effecting tools. A call none of
+ * those claims used to be answered "not a gated tool" and allowed with no
+ * record, which put every MCP tool (`mcp__<server>__<tool>` on Claude Code)
+ * outside the gate and made a new app a core release.
+ *
+ * This module is the policy's half of the answer, and it is pure: no I/O, no
+ * clock. Two keys:
+ *
+ * - `tools`: an ORDERED list of `{match, class}`. `match` is a glob over the
+ *   whole tool name whose only wildcard is `*` (any run of characters,
+ *   including none); `class` is a concrete class the policy declares. The first
+ *   entry that matches decides, and later entries are not read.
+ * - `defaults.unmapped_tool`: `record` or `ask`, for a call no entry matches.
+ *   Such a call is judged under {@link UNMAPPED_TOOL_CLASS}, whose default
+ *   autonomy the key supplies (see `core/policy-match.ts`'s `fromDefaults`).
+ *   Absent, the call stays outside the gate exactly as before.
+ *
+ * The adapter's own tables keep precedence over every entry, and that ordering
+ * lives in the hook, not here: those tables read the call's ARGUMENTS
+ * (`cronjob_manage list` is a read, `create` is not), while an entry reads only
+ * the NAME, so letting an entry override them would let a name-only line
+ * loosen a call the runtime classified from what it does.
+ */
+/**
+ * The class a harness tool call is judged under when no `tools` entry claims it
+ * and the policy declares `defaults.unmapped_tool` (APRV-499).
+ *
+ * Fixed rather than derived from the tool name, so one `classes` line prices
+ * every unmapped call and a policy cannot be surprised by a class it never
+ * wrote. The tool's NAME rides on the record instead (`harness_tool` on the
+ * `execution.started` payload, and the whole call in a gated request's
+ * payload).
+ */
+export const UNMAPPED_TOOL_CLASS = "harness.tool.unmapped";
+/**
+ * Can this tool name be recorded? (APRV-499, refutation S4.)
+ *
+ * The shape the event schema admits for `harness_tool` on an
+ * `execution.started` (letters, digits, `_`, `.`, `:`, `-`, at most 256),
+ * which is also every literal a `tools` match may spell. The hook asks this
+ * BEFORE it classifies a call under a mapped or unmapped class, so a name
+ * outside it is refused by name rather than at the write boundary as an opaque
+ * `append-failed`. Model APIs already cap tool names well inside this set, so
+ * the refusal is a corner; what it buys is a message that says what is wrong.
+ */
+export function isRecordableToolName(name) {
+    return /^[A-Za-z0-9_.:-]{1,256}$/u.test(name);
+}
+/**
+ * Does the glob `pattern` match the whole of `name`?
+ *
+ * `*` matches any run of characters, including none; every other character is
+ * literal and compared case-sensitively. Linear in the name for a fixed
+ * pattern: the literal runs between wildcards are found leftmost-first, which
+ * is exact for a language whose only wildcard is `*` (taking an earlier
+ * occurrence of a run never rules out a match a later one would allow).
+ */
+export function matchesToolPattern(pattern, name) {
+    const parts = pattern.split("*");
+    if (parts.length === 1)
+        return pattern === name;
+    const first = parts[0] ?? "";
+    const last = parts[parts.length - 1] ?? "";
+    if (name.length < first.length + last.length)
+        return false;
+    if (!name.startsWith(first) || !name.endsWith(last))
+        return false;
+    let position = first.length;
+    const end = name.length - last.length;
+    for (let index = 1; index < parts.length - 1; index += 1) {
+        const part = parts[index] ?? "";
+        if (part === "")
+            continue;
+        const at = name.indexOf(part, position);
+        if (at === -1 || at + part.length > end)
+            return false;
+        position = at + part.length;
+    }
+    return true;
+}
+/**
+ * The policy's verdict for `toolName`: the first matching entry, else the
+ * unmapped-tool default, else not gated.
+ */
+export function toolMapVerdict(policy, toolName) {
+    const entries = policy.tools ?? [];
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (entry === undefined)
+            continue;
+        if (matchesToolPattern(entry.match, toolName)) {
+            return { kind: "mapped", cls: entry.class, match: entry.match, index };
+        }
+    }
+    const mode = policy.defaults?.unmapped_tool;
+    if (mode === "record" || mode === "ask") {
+        return { kind: "unmapped", cls: UNMAPPED_TOOL_CLASS, mode };
+    }
+    return { kind: "not-gated" };
+}
+/**
+ * Is `cls` declared by `classes`: an exact key, or under a trailing family key
+ * `<prefix>.*` whose literal prefix it extends?
+ *
+ * The family half is the reading `agent_may_request` gives a family (APRV-445):
+ * interior wildcards and the bare `*` are not families, because a pattern that
+ * could match across branches would declare classes nobody looked at.
+ */
+export function classDeclared(classes, cls) {
+    if (Object.prototype.hasOwnProperty.call(classes, cls))
+        return true;
+    const segments = cls.split(".");
+    for (let length = segments.length - 1; length >= 1; length -= 1) {
+        const family = `${segments.slice(0, length).join(".")}.*`;
+        if (Object.prototype.hasOwnProperty.call(classes, family))
+            return true;
+    }
+    return false;
+}
+/**
+ * The load-time checks on `tools` that no JSON Schema can state, because each
+ * relates an entry to another part of the file (APRV-499).
+ *
+ * Any error fails the WHOLE policy closed (`schema-invalid`), exactly as a
+ * malformed glob does at the schema: a mapping its author believes is in force
+ * and the runtime does not apply is the failure this project exists to
+ * prevent, and the strict answer to it is every class `manual`.
+ *
+ * - An entry's `class` must be declared by `classes`. A class nothing prices
+ *   would resolve by `defaults.autonomy`, which reads in the log as a decision
+ *   the operator made about this app when they made none.
+ * - An entry may not name {@link UNMAPPED_TOOL_CLASS}: that class asserts that
+ *   no entry claimed the call, and a record saying so about a call an entry did
+ *   claim would be false.
+ * - Two entries may not share a `match`. The second can never decide, so its
+ *   author would be reading a line that is not in force.
+ */
+export function toolMapErrors(policy) {
+    const errors = [];
+    const entries = policy.tools ?? [];
+    const classes = policy.classes ?? {};
+    const seen = new Map();
+    entries.forEach((entry, index) => {
+        const at = `/tools/${String(index)}`;
+        const earlier = seen.get(entry.match);
+        if (earlier !== undefined) {
+            errors.push({
+                path: `${at}/match`,
+                keyword: "tool-match-duplicate",
+                message: `match ${JSON.stringify(entry.match)} repeats entry ${String(earlier)}; the first matching entry decides, so this one could never be read`,
+            });
+        }
+        else {
+            seen.set(entry.match, index);
+        }
+        if (entry.class === UNMAPPED_TOOL_CLASS) {
+            errors.push({
+                path: `${at}/class`,
+                keyword: "tool-class-reserved",
+                message: `${UNMAPPED_TOOL_CLASS} names the calls no tools entry claims, so an entry may not map to it; price unmapped calls with defaults.unmapped_tool or a classes line for ${UNMAPPED_TOOL_CLASS}`,
+            });
+            return;
+        }
+        if (!classDeclared(classes, entry.class)) {
+            errors.push({
+                path: `${at}/class`,
+                keyword: "tool-class-undeclared",
+                message: `class ${JSON.stringify(entry.class)} is not declared by classes (as an exact key or under a trailing <prefix>.* family key); declare it so the mapping resolves under a line the policy wrote rather than defaults.autonomy`,
+            });
+        }
+    });
+    return errors;
+}
+//# sourceMappingURL=tool-map.js.map

package/dist/src/core/tool-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-map.js","sourceRoot":"","sources":["../../../src/core/tool-map.ts"],"names":[],"mappings":"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"}

package/dist/src/daemon/git-evidence.d.ts

@@ -71,9 +71,9 @@ import type { LogHead } from "../core/log.js";
  * because a module that resolves its own package root differs between the source
  * tree and the build output for no benefit at all.
  */
-export declare const APPROVALD_VERSION = "0.4.1";
+export declare const APPROVALD_VERSION = "0.4.2";
 /** `user.name` on every commit this module makes. */
-export declare const GIT_EVIDENCE_AUTHOR_NAME = "approvald 0.4.1";
+export declare const GIT_EVIDENCE_AUTHOR_NAME = "approvald 0.4.2";
 /** `user.email` on every commit: fixed, and deliberately undeliverable. */
 export declare const GIT_EVIDENCE_AUTHOR_EMAIL = "approvald@noreply.approval.md";
 /**

package/dist/src/daemon/git-evidence.js

@@ -75,7 +75,7 @@ import { PAYLOAD_STORE_DIRNAME } from "../core/payload-store.js";
  * because a module that resolves its own package root differs between the source
  * tree and the build output for no benefit at all.
  */
-export const APPROVALD_VERSION = "0.4.1";
+export const APPROVALD_VERSION = "0.4.2";
 /** `user.name` on every commit this module makes. */
 export const GIT_EVIDENCE_AUTHOR_NAME = `approvald ${APPROVALD_VERSION}`;
 /** `user.email` on every commit: fixed, and deliberately undeliverable. */

package/docs/README-extended.md

@@ -292,6 +292,7 @@ The closed [policy schema](../schema/policy.schema.json) and [SPEC section 5](..
 | `channels` | Telegram and web configuration, plus supported prompt-layout choices. |
 | `vault` | The name of the environment variable holding the vault passphrase. |
 | `payload_retention` | Optional pruning policy for eligible stored payloads; absence means retain them. |
+| `delegation` | The judge's bounds, reserved in 0.4.2: loads only when off and changes nothing. |
 
 Keys ending in `_env` name environment variables, not secret values. Prompt customization cannot hide the fields required for a decision or remove the canonical payload from the authority path.
 
@@ -312,12 +313,16 @@ semantics: SPEC.md section 5.
 | `defaults.approval_ttl` | How long a pending request stays actionable. Duration string, `24h`. No default; the scaffolded policy writes one (§5.1). |
 | `defaults.token_delivery` | How a minted token reaches the process that will spend it. `manual` (the default, and what an absent key means): printed once on the granting surface and carried by a human. `sealed`: sealed to a per-request X25519 key so `approval wait` can hand it back, which addresses the token and never authorizes it (§10.4, APRV-105). |
 | `defaults.on_expiry` | What happens when the TTL lapses. `reject` is the only value, and absent means `reject` (§5.1). |
+| `defaults.unmapped_tool` | What a harness hook does with a tool call that neither the adapter's own tables nor any `tools` entry claims. `record`: judged under `harness.tool.unmapped`, which resolves `autonomous` unless a `classes` rule says otherwise, so the call runs and its `execution.started` names the tool (such record-only starts are not charged to `daily_actions` and do not accrue to the loop floor). `ask`: the same class resolves `manual`, so a human decides. Absent means the call is not a gate question and leaves no record, as before the key existed (§5.2, APRV-499, proposed). |
 | `payload_retention` | How long payload bytes are kept after their action is terminal. Absent means nothing is ever pruned (§5.2). |
 | `protected_paths` | Repo-relative files and directory prefixes whose edit is classified `policy.edit`. A bare string is the whole entry. Additive only, no globs, and absent means the built-in protected set alone (§5.2, APRV-107). |
 | `protected_paths[].path` | The path half of the object form: the same grammar as the bare string, an exact file (`SPEC.md`) or a directory prefix (`design/`) (§5.2, APRV-266). |
 | `protected_paths[].class` | The class half: one lowercase segment under `policy.edit`. Four reserved names, `policy.edit.spec`, `policy.edit.harness`, `policy.edit.ci` and `policy.edit.design`, plus any word an author mints beside them. Nothing outside `policy.edit` may be named, and a route below the `policy.edit` line is refused `protected-route-floor`. No default: an entry that wants a sub-class states it (§5.2, APRV-266). |
 | `read_scope` | Directories an agent's reads may stay inside. A read resolving outside every root is `read.file.out_of_scope`. Additive only: the gate root (this policy's own directory), the session scratchpad and the system temp root are in scope whatever this says, and absent means those alone (§5.2, APRV-347). |
 | `read_scope.roots` | The extra directories. Absolute, or relative to the gate root. No globs and no negation; each is resolved on disk before it is compared, so a symlink cannot smuggle a read out of one. Absent means no widening (§5.2, APRV-347). |
+| `tools` | Ordered `{match, class}` entries naming the class a harness's own tool calls are judged under, for the calls the adapter's built-in tables do not claim (every MCP tool among them). The first matching entry decides; the adapter's shell, file, read and pass-through tools and Hermes's rule table keep precedence. Absent or empty maps nothing (§5.2, APRV-499, proposed). |
+| `tools[].match` | A glob over the whole tool name, case-sensitive, `*` the only wildcard (any run, including none); otherwise letters, digits, `_`, `.`, `:` and `-`, at most 256. Two `*` in a row, or two entries with one `match`, fail the policy closed. Required (§5.2, APRV-499). |
+| `tools[].class` | The concrete class the call is judged under. Must be declared by `classes`, exactly or under a trailing `<prefix>.*` family, and may not be `harness.tool.unmapped`; either fault fails the policy closed. Required (§5.2, APRV-499). |
 | `approvers.<name>.channels` | The channels one approver can decide on. At least one: an approver reachable nowhere can never grant. No default (§5.1). |
 | `approvers.<name>.senders` | The transport account ids this person decides from, per channel: `senders.telegram: "12345678"`, the numeric `callback_query.from.id` and never a `@handle`, which is mutable and would transfer an identity. Optional and additive; absent everywhere means every decision is recorded against the identity the deciding process was launched with, exactly as before the key existed. Declaring the first entry for a channel turns enforcement on for that channel: a sender it authenticates and this block does not name is refused `sender-unmapped` and nothing is recorded. Two approvers claiming one id refuses the whole policy (`sender-ambiguous`), so every class resolves `manual`. Only channels whose transport authenticates a sender may appear, which today is `telegram` alone (§5.2, §10.3, APRV-324). |
 | `classes.<pattern>.autonomy` | Required on every class rule, so it has no default. Six levels, strictest first: `human-only`, `manual`, `supervised-live`, `supervised-retro`, `autonomous`, and `supervised`, which is the pre-split spelling and the DEPRECATED alias of `supervised-retro`: it still parses, `approval doctor`'s `autonomy-alias` row names every rule that writes it, and a future schema version removes it (§5.2, APRV-127, APRV-185, APRV-335). |
@@ -335,6 +340,14 @@ semantics: SPEC.md section 5.
 | `audit.sampling_secret_env` | Name of the variable holding the operator's HMAC sampling secret. Unnamed means sampling is off and says so (§5.2, §11). |
 | `audit.skew_tolerance` | How far a gate-typed event's timestamp may step back before verification reports an anomaly. Report-only; default 2 seconds (§8). |
 | `audit.checkpoint_keys` | Public halves of the Ed25519 keys permitted to sign a `log.checkpoint`, base64 DER SPKI. The private halves live in the vault and never in this file. A list, so a retired key stays listed: a checkpoint signed by a key the list does not carry is refused. Absent, empty or unreadable means verification skips the checkpoint check with a reason and never reports it as a pass (§9, APRV-220). |
+| `delegation` | The judge's bounds (a pinned model that may later review samples, advise on cards and decide manual cards in named classes). RESERVED in 0.4.2: the block is validated and loads only in its off form (`model: null`, every list empty, `max_autonomy: manual`, `daily_cap: 0`, `advice: false`; `{}` is the same), which changes nothing. Any other value fails the policy closed with `delegation-not-supported`, so every class resolves `manual`. Absent means no judge, exactly as before the key existed. Cores before 0.4.2 refuse the key outright (§5.2 proposed, APRV-500; `docs/cli-reference.md`, policy check). |
+| `delegation.model` | The judge identity, `model:<name>@<major>.<minor>.<patch>`, or `null`. Reserved: non-null is `delegation-not-supported` (APRV-500). |
+| `delegation.classes` | Exact keys of `classes` the judge may act on: no wildcard, not `human-only`, not `autonomous`. Reserved: non-empty is `delegation-not-supported` (APRV-500). |
+| `delegation.max_autonomy` | `manual` (default), `supervised-live` or `supervised-retro`: a pin, so every delegated class must declare an autonomy at least as strict. Reserved: anything but `manual` is `delegation-not-supported` (APRV-500). |
+| `delegation.daily_cap` | Judge grants per rolling day, 0 to 1000; above 0 requires `escalate_on` to hold `irreversible` and `unknown_class`. Reserved: anything but 0 is `delegation-not-supported` (APRV-500). |
+| `delegation.escalate_on` | Judge outcomes sent to a human: `deny`, `low_confidence`, `irreversible`, `unknown_class`. Reserved: non-empty is `delegation-not-supported` (APRV-500). |
+| `delegation.advice` | Whether the judge advises on manual cards. Reserved: `true` is `delegation-not-supported` (APRV-500). |
+| `delegation.reviewers` | Extra review identities: `human:<approver id>` or `model:<name>@<version>` equal to `model`. The only place a `model:` identity parses; every verb still requires `human:`. Reserved: non-empty is `delegation-not-supported` (APRV-500). |
 | `daemons` | The daemon instance ids permitted to append to this log, for the case where one party runs the daemon for another. Optional and additive; ABSENT means no restriction, exactly as before the key existed, and an empty list admits no daemon at all. Every record a daemon appends carries its id (`daemon` on the record), which is `APPROVAL_DAEMON_ID` from that process's launch environment or the derived `daemon-<instance id>` that `approval status` and `approval doctor` print. An id this list does not name is refused at the write boundary (`daemon-not-allowed`) with nothing written; an id it DOES name gains nothing else, since the id is self-reported and no verdict, budget, floor, draw or token reads it. Read from the attested policy only (§5.2, APRV-383, `design/hosted-daemon-identity.md`). |
 | `audit.checkpoint_every` | How long the log may go without a human-signed checkpoint before verification says one is due, and before the listener puts one `CHECKPOINT DUE` prompt on the approver's channel (`approval setup checkpoint` mints the key). Report-only at every layer: a due checkpoint is a warning and never a refusal. Absent means the cadence is off and nothing is ever reported as due (§9, APRV-220, APRV-257). |
 | `daemon.read_proof` | Which prefix proof a long-lived reader runs before reusing a cached prefix: `full` (the default, re-hash the whole prefix on every read) or `incremental` (hash only the appended bytes, re-proving in full on a cadence). One-shot processes, the Claude Code hook and `approval log verify` prove in full regardless (§5.2, APRV-217). |

package/docs/cli-reference.md

@@ -730,7 +730,8 @@ channel; policy-authorized execution is never represented as a human grant.
  "provenance":"rule"|"default"|"inherited"|"fail-closed"|"floor",
  "manualBecause":null|"matched-rule"|"irreversibility-floor"|"load-failure",
  "loadFailure":null|{"code":"file-missing"|"no-block"|"multiple-blocks"|
-                     "yaml-error"|"schema-invalid"|"protected-route-floor",
+                     "yaml-error"|"schema-invalid"|"protected-route-floor"|
+                     "sender-ambiguous"|"delegation-not-supported",
                      "message":"..."},
  "matched":null|{"pattern":"vcs.push.main","rule":{"autonomy":"supervised"}},
  "overridden":null|{"pattern":"read.web"|null,"autonomy":"autonomous"},
@@ -774,6 +775,62 @@ protected surface without removing a path from any list. The policy does not
 load, so every class answers `manual` with `manualBecause: "load-failure"`, and
 the message names the offending entry.
 
+### Delegation block, reserved in 0.4.2; no behaviour (APRV-500)
+
+A policy may carry one top-level `delegation` block. It is where the judge
+will live: a pinned model, `model:<name>@<major>.<minor>.<patch>`, that may
+later review supervised samples, advise on manual cards, and decide manual
+cards in named classes within a daily cap. None of that exists in this core.
+The block is parsed, validated, and loaded only in its off form:
+
+```yaml
+delegation:
+  model: null            # no judge; every other key is inert
+  classes: []            # exact keys of classes, never a wildcard
+  max_autonomy: manual   # manual | supervised-live | supervised-retro
+  daily_cap: 0           # 0 to 1000 judge grants per rolling day
+  escalate_on: []        # deny, low_confidence, irreversible, unknown_class
+  advice: false
+  reviewers: []          # human:<approver id> or model:<name>@<version>
+```
+
+An empty mapping (`delegation: {}`) and any subset of these keys at these
+values is the same off form. It changes no resolution, no request and no
+record, and `policy check` adds one line to the trace saying the block is
+declared and off.
+
+Any other value fails the load with `loadFailure.code`
+`delegation-not-supported`, and the message names every key that is not off.
+The policy then answers `manual` for every class, like any policy that does
+not load. Accepting `daily_cap: 10` and doing nothing would leave the author
+believing a setting is in force that nobody enforces, so this core refuses it.
+
+The block's relationships to the rest of the file are checked first, and a
+fault there is `schema-invalid` with its own keyword in `errors`:
+
+| keyword | rule |
+| --- | --- |
+| `delegation-class-undeclared` | each `classes` entry is an exact key of `classes`; a class reached only through a `<prefix>.*` family is refused |
+| `delegation-class-level` | no delegated class declares `human-only` or `autonomous` |
+| `delegation-max-autonomy-pin` | every delegated class declares an autonomy at least as strict as `max_autonomy`. It is a pin: loosening a delegated row without rewriting this block fails the load |
+| `delegation-escalation-floor` | `daily_cap` above 0 requires `escalate_on` to contain `irreversible` and `unknown_class` |
+| `delegation-reviewer-model` | a `model:` reviewer equals `model` exactly |
+| `delegation-reviewer-unknown` | a `human:` reviewer names a key of `approvers` |
+| `delegation-model-required` | `advice: true`, a cap above 0 or a `model:` reviewer needs `model` |
+
+The `model:` identity is reserved with the block. `delegation.reviewers` is
+the only place it parses. Grant, reject, revoke, attest, `audit review` and
+every channel decision still require `human:` and refuse a `model:` actor
+with `actor-not-human`. The event schema admits no `model:` actor and no
+`verdict_source: model`, which is registered as reserved and never written.
+
+`policy diff` (and the `policy amend` ceremony) shows the block's keys as
+`delegation.<key>` paths and, for an edit that turns one on, the
+`delegation-not-supported` failure of the new side. Older cores (0.4.1 and
+earlier) do not know the key and refuse even the off form as
+`schema-invalid`, so a template carries the block only once every daemon that
+reads it runs 0.4.2 or later.
+
 Human output: the `decisionPath` lines, then a final line `-> <autonomy>`
 carrying "(fail-closed: `<code>`)" or "(floor applied over `<pattern>`:
 `<autonomy>`)" when either applies. stderr stays empty on a successful answer.
@@ -2068,7 +2125,9 @@ to decide whether to fix itself, stop retrying, or ask a human.
   attestation (detail: `not-attested` | `hash-mismatch` | `unreadable`). Run
   `approval policy attest`.
 - `envelope-invalid` — the envelope failed `envelope.schema.json`, or the task
-  file has no frontmatter or no `approval:` key.
+  file has no frontmatter or no `approval:` key. Also: an envelope, a proposal
+  or a token-minting `request` naming the class `harness.tool.unmapped`, which
+  is reserved to the harness hook (APRV-499).
 - `task-file-unreadable` — the task file could not be read (exit 4).
 - `task-already-registered` — this task id already has a `task.registered` record.
 - `envelope-missing` — the file carries no `approval:` envelope AND the log holds
@@ -2237,7 +2296,9 @@ Frozen public API in the same sense the gate's codes are.
   is wrong and nothing is recoverable: the grant is complete, and it authorized
   a process that runs the command itself rather than through `approval run`.
   Distinct from `token-mismatch`, which would send an agent hunting for a token
-  that deliberately never existed.
+  that deliberately never existed. Also returned by `run` and `consume` for any
+  grant on the class `harness.tool.unmapped`, which only the harness hook may
+  spend (APRV-499).
 - `class-human-only` — the class the grant authorizes resolves to `human-only`,
   so the token may not be spent and `approval token` reports it unspendable
   rather than live. The gate refuses the request that would mint such a token,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "approval-md",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Human approval for agent actions. CLI runtime for the approval.md convention (pre-release).",
   "type": "module",
   "bin": {
@@ -59,5 +59,5 @@
     "better-sqlite3": "12.11.1",
     "yaml": "2.9.0"
   },
-  "gitHead": "5f9b9c3da2b0b220b344590d6d5319d27edf3b61"
+  "gitHead": "9f796b03f184f139d4cccde09cea4a098951631d"
 }

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