@sema-agent/core 7.36.0 → 7.37.0

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -381,6 +381,24 @@ export async function checkpointStoreContract(make, runAssertion) {
         assert.equal("mandate" in byId.get("mw-absent"), false, "absent must project the key OMITTED");
         assert.equal("mandate" in byId.get("mw-bogus"), false, "a word outside the closed set must read as absent, never project verbatim");
     });
+    run("#1214 ask class pair: a tool_approval row's `askClass` / `classes` survive the round-trip verbatim (the array whole, in its order); an absent pair stays absent", async () => {
+        const store = make();
+        const single = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "ac-single" });
+        Object.assign(single.pendingAction, { askClass: "denial_limit_fallback", classes: ["denial_limit_fallback"] });
+        const several = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "ac-several" });
+        Object.assign(several.pendingAction, { askClass: "transcript_write", classes: ["transcript_write", "org_rule"] });
+        const absent = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "ac-absent" });
+        for (const cp of [single, several, absent])
+            await store.put(cp.token, cp);
+        for (const [cp, askClass, classes] of [[single, "denial_limit_fallback", ["denial_limit_fallback"]], [several, "transcript_write", ["transcript_write", "org_rule"]]]) {
+            const back = (await store.get(cp.token)).pendingAction;
+            assert.equal(back.askClass, askClass, "the row's askClass must survive the round-trip verbatim");
+            assert.deepEqual(back.classes, classes, "the row's classes must survive the round-trip as the same array, in the same order");
+        }
+        const bare = (await store.get(absent.token)).pendingAction;
+        assert.equal("askClass" in bare, false, "an absent askClass must stay OMITTED on the row");
+        assert.equal("classes" in bare, false, "an absent classes must stay OMITTED on the row");
+    });
     await settle();
 }
 const sortByToken = (a, b) => a.token.localeCompare(b.token);

package/dist/core/tool-name-readings.d.ts

@@ -203,6 +203,10 @@ export declare const NAME_READINGS: {
         readonly rank: "member";
         readonly file: string;
     };
+    readonly "report.markSources": {
+        readonly kind: "any";
+        readonly file: string;
+    };
     readonly "verify.wroteThisRun": {
         readonly kind: "wire";
         readonly file: string;

package/dist/core/tool-name-readings.js

@@ -50,6 +50,7 @@ export const NAME_READINGS = {
     "report.riskAxes": seat("tier", CHAIN),
     "report.riskAxes.egress": any(CHAIN),
     "report.riskAxes.negatives": seat("member", CHAIN),
+    "report.markSources": any(CHAIN),
     "verify.wroteThisRun": wire(HANDLERS),
     "verify.wroteThisRunSeed": wire("src/core/runner/run-attachment-seats.ts"),
     "event.toolStartEnd": spelling(HANDLERS),

package/dist/core/tool-policy.d.ts

@@ -262,18 +262,9 @@ export declare function screenApproverAttribution(v: unknown): {
  * or `approver` member on its verdict is putting an unread property on it.
  * RB-479-B① (ruled 2026-08-02): the legacy `reason` field is REMOVED — one name for one thing.
  *
- * How far the TYPE carries that retirement (measured 2026-08-03, correcting this note's earlier claim
- * that a policy returning `{reason}` "compiles red for TS consumers"): TypeScript's excess-property
- * check fires only where the decision is a LITERAL in an ANNOTATED position — `const d: PermissionResult
- * = {…}`, or a `check` written with an explicit `: PermissionResult` return annotation. The ordinary
- * policy shape, `{ check: () => ({…}) }` with an INFERRED return type (also the method-syntax and
- * assign-then-return forms), compiles GREEN with a stray `reason`. That is not a hole to plug in the
- * type system — it is how contextual typing works — so the enforcement is at RUNTIME instead: every
- * point that CONSUMES a decision REFUSES one carrying an own `reason` property, fail-closed (deny, with
- * a migration message) — the {@link combinePolicies} fold, the PreToolUse hook face, and the durable
- * resume-edit rechecks (see {@link refuseOutOfContractDecision}). Same doctrine as the strict `approve`
- * / `onAsk` folds in this file: an out-of-contract value on the permission face is a loud rejection,
- * never a best-effort read.
+ * The TYPE carries that retirement only where a decision is a literal in an annotated position; an inferred `check`
+ * return compiles green with a stray `reason`, so the enforcement is at RUNTIME — every point that consumes a decision
+ * refuses one carrying an own `reason` property, fail-closed ({@link refuseOutOfContractDecision}).
  */
 export type PermissionResult = {
     action: "allow";
@@ -387,6 +378,13 @@ export type PermissionResult = {
      *  render the card by it. Optional on the TYPE only because a decision is caller-composable; every ask
      *  the gate hands to its resolver carries it. */
     origin?: import("./ask-origin.js").AskOrigin;
+    /** The ask's CLASS — the first member of {@link classes} (see {@link AskRequest.askClass}). ENGINE-STAMPED at the
+     *  same single stamp as {@link origin}, from the class set the gate's lanes read; a policy that self-declares it is
+     *  overwritten there, and no lane reads it back (they read the classification itself). */
+    askClass?: import("./ask-origin.js").AskClass;
+    /** The ask's whole class set, in {@link import("./ask-origin.js").ASK_CLASSES} order (see
+     *  {@link AskRequest.classes}). Stamped beside {@link askClass}, under the same rule. */
+    classes?: readonly import("./ask-origin.js").AskClass[];
     /** WHICH integrity guard minted this ask — the unverifiable recursive delete or the session-transcript
      *  write. ENGINE-STAMPED by the two guard policies; a fold-internal fact the class derivation reads
      *  ({@link import("./ask-origin.js").classifyAsk}) so the two guards, which mint the same
@@ -737,63 +735,53 @@ export declare function constraintChainEntryOfSuppliedLayer(layer: ConstraintCha
  * different frozen deny data now digest differently.
  */
 export declare function constraintChainDigest(chain: readonly ConstraintChainEntry[]): string;
+/** Every member of the decision union — a member the union gains and this list lacks is a type error at `satisfies`.
+ *  The receipt walks it: a contract member not held as an own enumerable data property is refused if a descriptor on the
+ *  prototype chain holds one (an `undefined` data value spells absence). Not re-exported from `src/index.ts`. */
+export type DecisionMember = PermissionResult extends infer U ? (U extends unknown ? keyof U : never) : never;
+export declare const DECISION_MEMBERS: readonly DecisionMember[];
 /**
- * Refuse a decision that speaks the retired `reason` dialect (RB-479-B①, tripwire ruled 2026-08-03).
- *
- * Applied at every point a decision is CONSUMED, because no single fold sees them all (ruled
- * 2026-08-03): {@link combinePolicies} (the runner's gate path), the PreToolUse hook's result seam
- * (`hooks.ts` — a hook result reaches the gate decision without ever passing through a fold), and the
- * durable resume-edit rechecks (`runtask.ts` — direct `check()` calls on the caller's own policy). The
- * wording is face-neutral for that reason: one construction point, three consumers. The export exists
- * for those two engine modules only and is deliberately NOT re-exported from `src/index.ts`: this is an
- * internal screen on inputs the engine receives, not a facility deployments call.
- *
- * Why this is a DENY and not a best-effort read of the old field: the retirement is settled, so the
- * value is out-of-contract input to the permission face — the same class as an untyped `approve`
- * returning a truthy non-`true`, which this file already refuses fail-closed. Reading the old name
- * anyway would re-open the two-names-for-one-thing surface; ignoring it (the pre-tripwire behavior)
- * silently dropped the policy's own text and returned the per-site generic default, so a deployment
- * whose deny messages had quietly degraded looked healthy. The type system cannot carry this alone —
- * excess-property checking does not reach an inferred `check` return (see {@link PermissionResult}).
- *
- * OWN property only (`hasOwnProperty`, not `in`): a decision whose PROTOTYPE happens to expose
- * `reason` never wrote the retired field. A non-object decision is passed through untouched — reading
- * `.action` off it is the caller's existing failure, and inventing a second failure mode here would
- * change which error a broken policy raises.
- *
- * Any accumulated `updatedInput` is deliberately NOT carried onto this deny: it came from the same
- * out-of-contract decision object, so it is not a rewrite this layer is willing to report as audited.
- * (A rewrite from an EARLIER, contract-shaped policy still rides out — {@link combinePolicies} adds it
- * on the deny path per the observer contract.)
- *
- * The second arm screens `decisionReason` against the closed set ({@link DecisionReason}): a
- * deployment-authored `ToolPolicy.check` returning a value outside it would otherwise ride silently
- * into every consumer that BRANCHES on the word — provenance-keyed exclusions, audit rows, checkpoint
- * discriminants — each of which would treat the unclassifiable value as "none of the reasons I know",
- * a meaning the producing policy never chose. Same doctrine as the retired-field arm: out-of-contract
- * input to the permission face is refused loudly, not passed through as an accidental tenth reason.
- * An ABSENT `decisionReason` stays legal (it is optional; `undefined` is the typed spelling of
- * absence), and hook results never reach here with a foreign word — the hook seam stamps its own
- * (`hooks.ts`) — so this arm's live producers are exactly the deployment policies the tripwire exists
- * to screen. Unlike the retired-field arm this one reads the property PLAINLY (prototype chain
- * included), because it answers a different question: the retired arm asks whether the AUTHOR wrote
- * the old field (own property = authorship), this arm asks what a CONSUMER would read — and every
- * consumer branches on a plain `d.decisionReason` read, which the prototype can satisfy.
- *
- * SCOPE of the carrier check (ruled after three review rounds converged on the same root): it screens
- * STRUCTURALLY unstable carriers — getters, prototype-supplied values — i.e. shapes an ordinary
- * deployment can write by accident. It does NOT try to defeat a Proxy whose descriptor trap reports a
- * data property while its get trap stays stateful: same-process JavaScript has no trust boundary a
- * function can enforce (an untrusted party who ships such a Proxy can as easily patch this module), so
- * chasing that shape adds complexity without adding a guarantee. The screen's promise is against
- * drift and accident, not against a untrusted co-resident.
- *
- * `reasonIsNonInput` (the HOOK seam's spelling — merged-code scan, 5.28 window): at that seam the
- * field is documented as DISCARDED — every mint point downstream unconditionally re-stamps
- * `decisionReason:"hook"` (fold, deny arm, delegated twin), and the allow path never reads it — so
- * both reason arms are skipped there: refusing a value that cannot travel would fail-close a call
- * over a field with no consumer, which inverted the discard contract the stamp exists to enforce.
- * The retired-`reason` arm still applies (that one is about the MESSAGE channel, which does travel).
+ * The RECEIPT of a permission decision — the one point at which the engine takes a decision in from whoever composed it,
+ * on every lane: each layer of {@link combinePolicies}' fold, the gate's adjudication entry and its approved-edit re-check,
+ * the inherited lane's receipts of an ancestor policy's decision, the final-form re-check, the direct `check()` rechecks
+ * (the resume edit, the park re-projection, the changed-files probe), and the PreToolUse hook's result seam (its own
+ * reach, below). NOT re-exported from `src/index.ts`: an internal screen on inputs the engine receives.
+ *
+ * WHAT COMES BACK is the engine's own frozen copy, never the caller's object. A decision is caller-supplied data: a
+ * stateful accessor, a Proxy, or a policy that keeps and mutates an object it returned could otherwise answer two
+ * consumers with two values, and which consumer read which value would decide the call. So the caller's object is read
+ * ONCE, here, and every station after the receipt (the fold's ranking, the origin stamp, the classifier's eligibility, the
+ * mode arbitration, the approval request, the rewrite that executes) reads the copy; a copy handed to the screen again
+ * comes back as it is, unread. In order: (1) the CARRIER's type — a decision that is not an object (a string, a function
+ * holding the members) has no `action`; (2) the ONE READ — ONE function ({@link receiveContract}) for the decision and for the
+ * records it nests ({@link NESTED_CONTRACTS}), on an ORDINARY object (a Proxy, as the carrier or anywhere on its prototype
+ * chain, is refused before a trap of its could run): each contract member absent or an own enumerable DATA property, its value
+ * taken off the carrier's own descriptor (a member outside the contract is neither read nor carried — a policy's self-declared
+ * record on another name finds no reader); any other spelling refused by name — an accessor (never invoked), a member the
+ * prototype or a non-enumerable property supplies unless that descriptor spells absence (an `undefined` data value) — judged by
+ * descriptor, never read; (3) the retired `reason` field as an OWN property, judged without a read (authorship of the old
+ * spelling: a prototype exposing it never wrote it; ignoring it silently dropped the policy's text); (4) the VALUES, off the engine's
+ * one-read record, never a second read of the caller's object — the retired window absent, `action` in
+ * {@link DECISION_ACTIONS} (a consumer ranks a decision by testing two of its words, so any other value used to rank as an
+ * allow; a `canUseTool` result outside its set is a failure in CC) and `decisionReason` in {@link DECISION_REASONS} when
+ * present (absence stays legal); (5) the DETACH —
+ * the contract members' values structured-cloned ({@link tryCloneArgs}; one that cannot be, a function inside a rewrite,
+ * is refused), the engine's identity-keyed records carried across ({@link carryEngineAttestations}), the copy frozen and
+ * marked as this module's. A refusal is a deny in the screen's words, one code for every arm (`decisionReason: "rule"`),
+ * carrying no `updatedInput` from the refused object (a rewrite from an EARLIER, contract-shaped layer still rides out of
+ * {@link combinePolicies}' deny path). `null` / `undefined` carry nothing and take the carrier's refusal (the caller's own
+ * read of `.action` would throw instead, and that throw was being reported as an aborted check).
+ *
+ * SCOPE: the receipt runs NONE of the carrier's code — a Proxy (its traps are the caller's code) is refused unread, and on an
+ * ordinary object descriptor looks and `Object.getPrototypeOf` invoke nothing. What the receipt does not reach: code inside a
+ * member's VALUE, run by the detach itself (an accessor inside a rewrite is invoked by the structured clone, and what it answers
+ * there is what is cloned and what runs — one read, consistent) and by a refusal's rendering of a foreign word (`String(v)` on an
+ * out-of-set `action`, after the deny is decided). Same-process JavaScript has no trust boundary a function can enforce.
+ *
+ * `reasonIsNonInput` (the HOOK seam): a hook's `decisionReason` is DISCARDED there — every mint point downstream re-stamps
+ * `"hook"`, and the seam maps a hook's deny and ask and reads anything else as no objection, the policy still adjudicating
+ * the call — so that seam takes the two retired-field arms alone and its object back unchanged (`undefined` = no
+ * opinion): refusing a value that cannot travel would fail-close a call over a field with no consumer.
  */
 export declare function refuseOutOfContractDecision(d: PermissionResult, opts?: {
     reasonIsNonInput?: boolean;
@@ -911,22 +899,11 @@ export declare function createApprovalPolicy(opts: {
  */
 export declare function combinePolicies(...policies: ToolPolicy[]): ToolPolicy;
 /**
- * The shell tools whose `{ command }` arg a coarse command-name policy parses. Other tools are out of scope.
- *
- * `Monitor` belongs here. It takes a `command` and runs it through the
- * SAME `env.spawnBackground` seam as Bash, and prepare-task's own note says so in as many words — "Monitor
- * runs an arbitrary shell `command` through the SAME env seam — it must sit behind the SAME shellGate
- * tighten (else it becomes a policy side-door around a gated Bash)". The shellGate half was implemented;
- * this half — the two ALWAYS-ON, core-owned parity gates that a caller's policy cannot remove — was keyed
- * on a list containing only "Bash". The probe drove the whole thing end to end: the identical
- * `rm -rf $(cat targets)` was denied as Bash and executed as Monitor, deleting a real directory with no
- * gate at all; the same substitution makes `rm -rf ~/.ai-agent/sessions` a way to erase the audit trail.
- */
-/**
- * EXPORTED. A downstream governance layer keeps its own copy of this list so its
- * per-command ask-list gates the same tools core does, and it had no way to read the real one — its guard
- * had to probe a hand-written candidate list of names, which stays green for any name nobody thought to
- * put in it. The list itself is the fact; publishing it removes the guess.
+ * The shell tools whose `{ command }` arg a coarse command-name policy parses; other tools are out of scope. `Monitor`
+ * belongs here: it runs an arbitrary shell `command` through the same env seam as Bash, so the always-on parity gates
+ * keyed on this list reach it too (a list of `Bash` alone let the identical command run ungated as `Monitor`). EXPORTED:
+ * a downstream governance layer keeps its own copy of this list so its per-command ask-list gates the same tools core
+ * does — the list itself is the fact, and publishing it removes the guess.
  */
 export declare const COARSE_SHELL_TOOLS: string[];
 /**
@@ -1389,6 +1366,19 @@ export interface AskRequest {
      *  therefore reading the deployment's own claim about its own ask, which is the direction that cannot
      *  loosen anything. */
     readonly origin?: import("./ask-origin.js").AskOrigin;
+    /** The ask's CLASS: the first member of {@link classes} in {@link import("./ask-origin.js").ASK_CLASSES} order — the
+     *  row key of {@link import("./ask-origin.js").MODE_ARBITRATION} a permission mode reads. Filled by every station that
+     *  fills {@link origin}, from the same classification the gate's lanes arbitrated this ask by; never written by a
+     *  caller or worker (a policy's self-declared value is replaced at the stamp), and a policy can move it only through
+     *  the tighten-only inputs the classification reads. ABSENT = unclassified: a request from a station that fills no
+     *  {@link origin} (the shared-artifact read confirmation), or a request built by a deployment itself. An approver
+     *  that answers by class treats absence as a class it will not answer. */
+    readonly askClass?: import("./ask-origin.js").AskClass;
+    /** Every class this ask belongs to, in {@link import("./ask-origin.js").ASK_CLASSES} order, `classes[0] ===
+     *  askClass`. One ask can carry several (an org verdict beside a hook's question); an approver that answers by class
+     *  reads the whole set — a class it will not answer anywhere in it is a question it does not answer. Present exactly
+     *  when {@link askClass} is. */
+    readonly classes?: readonly import("./ask-origin.js").AskClass[];
     /** Engine-judged risk axes of the action awaiting approval, for the human decision surface: a
      *  coarse `requiresRealApproval` cannot tell "cannot be undone" from "data leaves the machine",
      *  and those call for different scrutiny. Filled by the gate from the SAME resolved axes the

package/dist/core/tool-policy.js

@@ -13,6 +13,7 @@ import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
 import { describeRejectedValue } from "./tool-search-setting.js";
 import { thrownText } from "./thrown-value.js";
+import { receiveContract, refusedOutOfContract } from "./decision-receipt.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
 import { protocolOf } from "./protocol-table.js";
 import { isAbsoluteForFamily, isAbsolutePathForm, joinForFamily, normalizeAbsPathLexically, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
@@ -244,56 +245,90 @@ function stableJson(v) {
 export function constraintChainDigest(chain) {
     return `cpv1:${createHash("sha256").update(stableJson(chain)).digest("hex")}`;
 }
-const ALLOW = { action: "allow" };
+const ALLOW = Object.freeze({ action: "allow" });
 const RETIRED_TEXT_FIELD = "reason";
 const RETIRED_WINDOW_MEMBER = "autoDenyAfterMs";
 const RETIRED_WINDOW_MEMBER_DENY_MESSAGE = `a permission decision's "denialLimitFallback" carries "${RETIRED_WINDOW_MEMBER}" — the decision names the counts only; ` +
     `the auto-deny window is decided by the ask's route (a live approver arms it, every other route runs none) and cannot be ` +
     `declared by a policy; denied fail-closed rather than silently replacing the declared number`;
+const carriesRetiredWindow = (fallback) => typeof fallback === "object" && fallback !== null && fallback[RETIRED_WINDOW_MEMBER] !== undefined;
+const DECISION_ACTIONS = Object.keys({ allow: 0, deny: 0, ask: 0 });
+const DECISION_ACTION_SET = new Set(DECISION_ACTIONS);
+export const DECISION_MEMBERS = Object.keys({
+    action: 0, updatedInput: 0, message: 0, decisionReason: 0, requiresRealApproval: 0, denialLimitFallback: 0, persistedRuleShadowed: 0, probeReason: 0,
+    probeCause: 0, probeMandated: 0, mandated: 0, mandate: 0, probeReadRootCandidate: 0, matchedAskRule: 0, ruleEvidence: 0, segmentCoverage: 0,
+    origin: 0, askClass: 0, classes: 0, guard: 0, ruleUnreadable: 0, authoredBy: 0, foldedAskClasses: 0,
+});
+const OPERAND_MEMBERS = Object.keys({ shown: 0, total: 0 });
+const NESTED_CONTRACTS = [
+    ["", "denialLimitFallback", Object.keys({ consecutive: 0, total: 0, limit: 0, autoDenyAfterMs: 0 })],
+    ["", "probeCause", Object.keys({ code: 0, roots: 0, further: 0 })],
+    ["probeCause.", "roots", OPERAND_MEMBERS],
+    ["probeCause.", "further", OPERAND_MEMBERS],
+];
+const refusedAction = (what) => refusedOutOfContract(`a permission decision's "action" is ${what} — the closed set is ${DECISION_ACTIONS.join("/")}; denied fail-closed rather than reading a word outside it as an allow`);
+function renderForeignValue(v) {
+    try {
+        return JSON.stringify(String(v).slice(0, 64));
+    }
+    catch {
+        return `[unprintable ${typeof v}]`;
+    }
+}
 const RETIRED_TEXT_FIELD_DENY_MESSAGE = `a permission decision carries the retired "${RETIRED_TEXT_FIELD}" field — rename it to "message" (the one text field ` +
     `a decision carries); denied fail-closed rather than executing a decision whose text this layer cannot read`;
+const ENGINE_RECEIPTS = new WeakSet();
 export function refuseOutOfContractDecision(d, opts) {
+    if (opts?.reasonIsNonInput === true) {
+        if (d === null || d === undefined)
+            return d;
+        if (Object.prototype.hasOwnProperty.call(d, RETIRED_TEXT_FIELD))
+            return refusedOutOfContract(RETIRED_TEXT_FIELD_DENY_MESSAGE);
+        return carriesRetiredWindow(d.denialLimitFallback) ? refusedOutOfContract(RETIRED_WINDOW_MEMBER_DENY_MESSAGE) : d;
+    }
     if (typeof d !== "object" || d === null)
+        return refusedAction(`absent (the decision is ${d === null || d === undefined ? String(d) : `a ${typeof d}`}, not an object)`);
+    if (ENGINE_RECEIPTS.has(d))
         return d;
-    if (Object.prototype.hasOwnProperty.call(d, RETIRED_TEXT_FIELD)) {
-        return { action: "deny", message: RETIRED_TEXT_FIELD_DENY_MESSAGE, decisionReason: "rule" };
+    const decision = receiveContract(d, DECISION_MEMBERS, "");
+    if (decision.kind === "refused")
+        return decision.refused;
+    if (Object.prototype.hasOwnProperty.call(d, RETIRED_TEXT_FIELD))
+        return refusedOutOfContract(RETIRED_TEXT_FIELD_DENY_MESSAGE);
+    const contract = decision.held;
+    const records = Object.assign(Object.create(null), { "": contract });
+    for (const [holder, member, members] of NESTED_CONTRACTS) {
+        const held = records[holder];
+        if (held === undefined || typeof held[member] !== "object" || held[member] === null)
+            continue;
+        const nested = receiveContract(held[member], members, `${holder}${member}.`);
+        if (nested.kind === "refused")
+            return nested.refused;
+        held[member] = records[`${holder}${member}.`] = nested.held;
     }
-    const fb = d.denialLimitFallback;
-    if (typeof fb === "object" && fb !== null && fb.autoDenyAfterMs !== undefined) {
-        return { action: "deny", message: RETIRED_WINDOW_MEMBER_DENY_MESSAGE, decisionReason: "rule" };
+    if (carriesRetiredWindow(contract.denialLimitFallback))
+        return refusedOutOfContract(RETIRED_WINDOW_MEMBER_DENY_MESSAGE);
+    if (!DECISION_ACTION_SET.has(contract.action))
+        return refusedAction(contract.action === undefined ? "absent" : renderForeignValue(contract.action));
+    if (contract.decisionReason !== undefined && !DECISION_REASON_SET.has(contract.decisionReason)) {
+        return refusedOutOfContract(`a permission decision carries an unrecognized "decisionReason" value (${renderForeignValue(contract.decisionReason)}) — ` +
+            `the closed set is ${DECISION_REASONS.join("/")}; denied fail-closed rather than letting consumers branch on a value this layer cannot classify`);
     }
-    if (opts?.reasonIsNonInput === true)
-        return d;
-    const dr = d.decisionReason;
-    if (dr === undefined)
-        return d;
-    if (!DECISION_REASON_SET.has(dr)) {
-        let rendered;
-        try {
-            rendered = JSON.stringify(String(dr).slice(0, 64));
-        }
-        catch {
-            rendered = `[unprintable ${typeof dr}]`;
-        }
-        return {
-            action: "deny",
-            message: `a permission decision carries an unrecognized "decisionReason" value (${rendered}) — ` +
-                `the closed set is ${DECISION_REASONS.join("/")}; denied fail-closed rather than letting consumers ` +
-                `branch on a value this layer cannot classify`,
-            decisionReason: "rule",
-        };
+    const detached = tryCloneArgs(contract);
+    if (!detached.ok) {
+        return refusedOutOfContract(`a permission decision's members could not be detached from the policy that returned them (${detached.reason}) — ` +
+            `the engine keeps its own copy of what it read; denied fail-closed`);
     }
-    const carrier = Object.getOwnPropertyDescriptor(d, "decisionReason");
-    if (carrier === undefined || !("value" in carrier)) {
-        return {
-            action: "deny",
-            message: `a permission decision supplies "decisionReason" through ${carrier === undefined ? "its prototype" : "an accessor"} — ` +
-                `contract fields must be own data properties, so consumers re-reading the field cannot be shown a ` +
-                `different value than this screen validated; denied fail-closed`,
-            decisionReason: "rule",
-        };
+    const receipt = Object.freeze(detached.value);
+    const ownRecord = (o, k) => (typeof o === "object" && o !== null && Object.hasOwn(o, k) ? o[k] : undefined);
+    for (const [holder, member] of NESTED_CONTRACTS) {
+        const record = ownRecord(holder.split(".").filter(Boolean).reduce(ownRecord, receipt), member);
+        if (typeof record === "object" && record !== null)
+            Object.freeze(record);
     }
-    return d;
+    carryEngineAttestations(d, receipt);
+    ENGINE_RECEIPTS.add(receipt);
+    return receipt;
 }
 const DEADLINE_ELAPSED = Symbol("approval.deadline_elapsed");
 function withTimeout(p, ms, onTimeout) {

package/dist/index.d.ts

@@ -192,7 +192,7 @@ export { createAllowDenyPolicy, createApprovalPolicy,
 type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export { type ReadRootGrantScreen } from "./core/read-root-grant-screen.js";
 export { type AskOrigin, ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate } from "./core/ask-origin.js";
-export { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, RELEASABLE_ASK_CLASSES, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, type AskClassification, type AskClassFacts, type ToolMarkSource, arbitrateByMode, type Arbitration, fileCommandOptionsSentence } from "./core/ask-origin.js";
+export { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, RELEASABLE_ASK_CLASSES, MODE_RELEASE_REASONS, type ModeReleaseReason, isModeReleaseReason, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, type AskClassification, type AskClassFacts, type ToolMarkSource, arbitrateByMode, type Arbitration, fileCommandOptionsSentence } from "./core/ask-origin.js";
 export { modePolicyOf, type ModePolicy, PERMISSION_MODE_FOLD_REASONS, type PermissionModeFoldReason, type PermissionModeReceipt, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
 export { readDenyClassifierRules, renderClassifierDenyRules, type DerivedDenyRule } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource, type AutoModeDenySource } from "./core/runtime-caps.js";

package/dist/index.js

@@ -157,7 +157,7 @@ export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.
 export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export {} from "./core/read-root-grant-screen.js";
 export { ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, isPersistedRuleMandate } from "./core/ask-origin.js";
-export { PERMISSION_MODES, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, isAskClass, MODE_ARBITRATION, RELEASABLE_ASK_CLASSES, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, arbitrateByMode, fileCommandOptionsSentence } from "./core/ask-origin.js";
+export { PERMISSION_MODES, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, isAskClass, MODE_ARBITRATION, RELEASABLE_ASK_CLASSES, MODE_RELEASE_REASONS, isModeReleaseReason, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, arbitrateByMode, fileCommandOptionsSentence } from "./core/ask-origin.js";
 export { modePolicyOf, PERMISSION_MODE_FOLD_REASONS, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
 export { readDenyClassifierRules, renderClassifierDenyRules } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./core/runtime-caps.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.36.0",
+  "version": "7.37.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 2537,
+  "count": 2540,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -713,6 +713,7 @@
     "MEMORY_SEARCH_TOOL_NAME": "variable",
     "MODEL_ROLES": "variable",
     "MODE_ARBITRATION": "variable",
+    "MODE_RELEASE_REASONS": "variable",
     "MONITOR_BATCH_WINDOW_MS": "variable",
     "MONITOR_DEFAULT_TIMEOUT_MS": "variable",
     "MONITOR_MAX_BATCHES_PER_MINUTE": "variable",
@@ -822,6 +823,7 @@
     "ModePolicy": "interface",
     "ModeRefusal": "interface",
     "ModeRelease": "interface",
+    "ModeReleaseReason": "type",
     "Model": "interface",
     "ModelCriteria": "interface",
     "ModelMention": "interface",
@@ -2094,6 +2096,7 @@
     "isGateKind": "function",
     "isInstructionEntry": "function",
     "isIsolated": "function",
+    "isModeReleaseReason": "function",
     "isModelGatedForClass": "function",
     "isModelPriced": "function",
     "isNamespacedCoveringRuleName": "function",
@@ -3252,6 +3255,7 @@
     "MEMORY_SEARCH_TOOL_NAME": "advanced",
     "MODEL_ROLES": "advanced",
     "MODE_ARBITRATION": "advanced",
+    "MODE_RELEASE_REASONS": "advanced",
     "MONITOR_BATCH_WINDOW_MS": "advanced",
     "MONITOR_DEFAULT_TIMEOUT_MS": "advanced",
     "MONITOR_MAX_BATCHES_PER_MINUTE": "advanced",
@@ -3361,6 +3365,7 @@
     "ModePolicy": "advanced",
     "ModeRefusal": "advanced",
     "ModeRelease": "advanced",
+    "ModeReleaseReason": "advanced",
     "Model": "stable",
     "ModelCriteria": "advanced",
     "ModelMention": "advanced",
@@ -4633,6 +4638,7 @@
     "isGateKind": "advanced",
     "isInstructionEntry": "advanced",
     "isIsolated": "advanced",
+    "isModeReleaseReason": "advanced",
     "isModelGatedForClass": "advanced",
     "isModelPriced": "advanced",
     "isNamespacedCoveringRuleName": "advanced",