approval-md 0.4.0 → 0.4.2

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). |
@@ -348,6 +361,8 @@ semantics: SPEC.md section 5.
 | `channels.<name>.prompt.rows` | Order only, for `telegram`, `web` and `cli`: the rows named here render in this order ahead of the rest, which keep their default relative order behind them. Never a whitelist, so a field added later cannot be lost to a list written before it existed. Absent means the layout the channel ships (§5.2, §10.3, APRV-218). |
 | `channels.<name>.prompt.always` | Rows this channel renders only when abnormal, or not at all, render on every prompt instead. The anomaly mark stays a statement about the value, so a forced-on row shouts only when the value is in fact the reason to look. Absent means the channel's own visibility rules (§5.2, §10.3, APRV-218). |
 | `channels.<name>.prompt.hide` | Rows this channel never renders. Refused for the rows required for a decision (`action_key`, `class`, `command_breakdown`, `protected_path`, `policy_diff`, `policy_load`) with `prompt-row-required`, and refused for a row `always` also names. Absent means nothing is hidden, and the canonical payload block is out of reach either way (§5.2, §10.3, APRV-218). |
+| `channels.<name>.prompt.style` | `technical` (the default, and what an absent key or an unloaded policy means: the prompt every earlier build sent) or `minimal`: one Telegram message in plain words, with a headline the runtime computes from the class, the payload's own words quoted, a deadline, Approve and Deny, and the whole technical card, canonical rendering included, collapsed under "Full details". A request the minimal card cannot draw honestly (an opaque payload without a `say` entry naming every key, an attestation, a policy edit, a digest, a truncated payload, an abnormal row, a batch, a card over 3800 characters, a card the Bot API refuses) is sent as the technical card, and the decision record says so in `payload.rendering`. Only Telegram draws it; `web` and `cli` ignore the key. An older core refuses it and fails the policy closed, so roll the core out first (§5.2, §10.3, APRV-489). |
+| `channels.<name>.prompt.say` | Per EXACT class name (a pattern such as `files.*` is refused, `prompt-say-wildcard`), the operator's words for the minimal card: `does` (the verb phrase after "Your agent wants to": no sentence punctuation, markup or leading symbol; refused for a class core phrases itself, whose own phrase always wins, and for a class the command classifier emits, `prompt-say-kind`; drawn only over an opaque payload, never over a command, file change or email, whose kind phrase the runtime draws), `quote` (every top-level key an opaque payload may carry, mapped to its label or `~` for deliberately not shown, which the card then names under the box; at least one key shown; any other key sends the technical card) and `note` (`summary` or `none`: whether the agent's own summary is shown, labelled "not checked"). Read only under `style: minimal`, for each card as it is drawn (§5.2, APRV-489). |
 | `channels.<other>` | An unknown channel name is accepted as an object, so a third-party transport does not fail the whole policy closed (§10.3). A `prompt` block written under such a name is still validated: a layout is checked wherever it appears. |
 
 And the values block (SPEC.md §5.3), which is guidance and reaches no