@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/gate-lanes.js

@@ -1,21 +1,23 @@
 import { argsAsTheToolReads, withArgsReading } from "./effective-path-target.js";
-import { attest, attestationOf, bindableArgsOf, decisionText, foldHookAsk, mergeAttestation, refusalOf, refuseOutOfContractDecision, withAttestation } from "./tool-policy.js";
-import { arbitrateByMode, classifyAsk, decisionAskClassesOf, fileCommandOptionsSentence, persistedRuleMandateOf, safetyAxisOf, stampAskOrigin } from "./ask-origin.js";
+import { attest, attestationOf, bindableArgsOf, decisionText, foldHookAsk, refusalOf, refuseOutOfContractDecision } from "./tool-policy.js";
+import { outletAsk, readRejudge, rewriteChasedSentence, screenRewrite } from "./rewrite-rejudge.js";
+import { arbitrateByMode, classifyAsk, decisionAskClassesOf, dontAskRefusalMessage, fileCommandOptionsSentence, persistedRuleMandateOf, safetyAxisOf, stampAskOrigin } from "./ask-origin.js";
 import { classifierParseFailureDenyMessage, denialLimitFallbackMessage, rungDidNotRule, unarmedWindow } from "./auto-mode.js";
 import { classifierNoRulingArm, settleNoRulingAsk } from "./classifier-unavailable-arm.js";
 import { SETTLEMENT_NOBODY_JUDGED } from "./gate-outcome.js";
 import { inlineUntrusted } from "./untrusted-text.js";
-import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
+import { ASK_USER_QUESTION_TOOL_NAME, isEngineQuestionFace } from "./ask-question.js";
+import { engineMountedAs } from "./tool-catalog-entries.js";
 import { applyPersistedTightening, disclosedRuleSet } from "./persisted-rule-arms.js";
 import { skillAllowDecision, skillRowRefusal } from "./skill-grant.js";
-import { allowRuleShadowOf } from "./allow-entry.js";
+import { allowRuleShadowOf, withAllowRuleShadow } from "./allow-entry.js";
 import { CD_GIT_COMPOUND_SENTENCE, changesDirectoryBeforeGit, readOnlyShellVerdict } from "./read-only-shell.js";
 import { readShellCommand } from "./shell-run-candidates.js";
-import { COMMAND_RULE_TOOL } from "./permission-rule-model.js";
-import { catalogRuleFaceOf } from "./tool-registry.js";
+import { COMMAND_RULE_TOOL, ruleShapeOf } from "./permission-rule-model.js";
+import { catalogRuleFaceOf, isProtectedWrite } from "./tool-registry.js";
 import { callFaceSeat } from "./tool-roster.js";
-import { heldBy, wireOf } from "./tool-name-readings.js";
-import { asksUnstated, modeAcceptsFileCommand, permissionSeatAt, unstatedAskMessage } from "./mode-policy.js";
+import { wireOf } from "./tool-name-readings.js";
+import { modeAcceptsFileCommand } from "./mode-policy.js";
 import { ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, orgUnreadableClause } from "./permission-rule-org.js";
 import { exitGate, passAskFace, untakenValueExit } from "./runner/gate-exit.js";
 import { readOrgRuleLane, readPersistedRuleLane } from "./rule-lane-reads.js";
@@ -23,9 +25,9 @@ import { traceHookCrash } from "./gate-crash-trace.js";
 import { createGateDeadline, awaitWriteProtectionJudgment, withGateTimeout } from "./gate-bounded-await.js";
 import { readStationAnswer } from "./shell-read-silence.js";
 import { agentIdOf, judgedInputOf, raiseToolCheck } from "./mods/stations.js";
-import { readToolChecks } from "./tool-check-reading.js";
+import { extensionAllowOf, readToolChecks } from "./tool-check-reading.js";
 import { policyThrowLine, reportPolicyThrow } from "./runner/policy-throw.js";
-const QUESTION_TOOL_NAMES = new Set([ASK_USER_QUESTION_TOOL_NAME]);
+const routesContent = engineMountedAs(["ask-user-question", "structured-output", "report-blocked"]);
 function parkWith(suspendAsk, parkArgs, carry) {
     return suspendAsk(...parkArgs, carry);
 }
@@ -80,7 +82,8 @@ export async function runGateLanes(pass) {
     });
     const readFaceNow = input.readFace?.();
     const askOriginFacts = (org, lane) => ({
-        contentQuestion: heldBy("lanes.contentQuestionClass", QUESTION_TOOL_NAMES, pass.req),
+        call: { toolCallId: pass.req.toolCallId, toolName: pass.req.toolName },
+        contentQuestion: isEngineQuestionFace(pass.req.face),
         markedUnresolvable: markedUnresolvable(),
         org,
         ...(ruleCallUnreadableOf(lane) ? { ruleCallUnreadable: true } : {}),
@@ -159,7 +162,7 @@ export async function runGateLanes(pass) {
     pass.decision = orgAnswer.decision;
     const readPersistedRules = (req) => readPersistedRuleLane(input.persistedRules, req, input.abortSignal);
     const laneReq = Object.freeze(pass.policyRewrite !== undefined ? await withArgsReading(pass.req, pass.policyRewrite, pass.callSignal ?? input.abortSignal) : { ...pass.req });
-    const laneAnswer = input.persistedRules !== undefined && wireOf("lanes.persistedLaneSkip", pass.req) !== ASK_USER_QUESTION_TOOL_NAME ? await readPersistedRules(laneReq) : undefined;
+    const laneAnswer = input.persistedRules !== undefined && !routesContent(pass.req.face) ? await readPersistedRules(laneReq) : undefined;
     {
         const tightened = applyPersistedTightening(pass.decision, laneAnswer, laneReq);
         pass.decision = tightened.tightened === "deny" ? refusalOf(tightened.decision, laneReq.args) : tightened.decision;
@@ -229,7 +232,7 @@ export async function runGateLanes(pass) {
         if (laneAnswer?.unreadable === true)
             personalEvidence = { dotsAbsent: "unavailable" };
         let laneCoverage;
-        const questionTool = wireOf("lanes.allowLayerQuestionSkip", pass.req) === ASK_USER_QUESTION_TOOL_NAME;
+        const questionTool = originFacts.contentQuestion;
         const laneIsProvenance = orgAnswer.org === undefined &&
             pass.decision.action === "ask" &&
             pass.decision.requiresRealApproval !== true &&
@@ -269,10 +272,10 @@ export async function runGateLanes(pass) {
         });
         const storedAllows = laneAnswer?.hit?.behavior === "allow" ? laneAnswer.hit.rules : undefined;
         const members = [
-            ["hook", () => (pass.hookAllowedBy !== undefined && pass.policyRewrite === undefined ? { entries: pass.hookAllowedBy, clear: () => ({ action: "allow", message: "a PreToolUse hook allowed this call", decisionReason: "hook" }), afterClear: async () => undefined } : undefined)],
+            ["hook", () => (pass.hookAllowedBy !== undefined ? { entries: pass.hookAllowedBy, clear: () => extensionAllowOf(pass.hookAllowedBy ?? [], pass.policyRewrite), afterClear: async () => undefined } : undefined)],
             ["deployment", () => {
                     const hit = input.deploymentAllows?.allowing(pass.req, mode);
-                    return hit && { entries: hit.entries, clear: () => listAllow("deployment_rule", "the deployment's", hit.entries), afterClear: () => notifier.notifyAsync(() => input.deploymentAllows?.onAllowed?.({ toolName: pass.req.toolName, toolCallId, entries: hit.entries }), "toolGate.allowedToolsResolved") };
+                    return hit && { entries: hit.entries, ...(hit.positions !== undefined ? { positions: hit.positions } : {}), clear: () => listAllow("deployment_rule", "the deployment's", hit.entries), afterClear: () => notifier.notifyAsync(() => input.deploymentAllows?.onAllowed?.({ toolName: pass.req.toolName, toolCallId, entries: hit.entries }), "toolGate.allowedToolsResolved") };
                 }],
             ["persisted", () => storedAllows && {
                     entries: storedAllows.map((r) => r.rule),
@@ -286,10 +289,18 @@ export async function runGateLanes(pass) {
                 }],
             ["request", () => {
                     const hit = input.requestAllows?.allowing(pass.req, mode);
-                    return hit && { entries: hit.entries, clear: () => listAllow("request_rule", "this run's", hit.entries), afterClear: () => notifier.notifyAsync(() => input.requestAllows?.onAllowed?.({ toolName: pass.req.toolName, toolCallId, entries: hit.entries }), "toolGate.allowedToolsResolved") };
+                    return hit && { entries: hit.entries, ...(hit.positions !== undefined ? { positions: hit.positions } : {}), clear: () => listAllow("request_rule", "this run's", hit.entries), afterClear: () => notifier.notifyAsync(() => input.requestAllows?.onAllowed?.({ toolName: pass.req.toolName, toolCallId, entries: hit.entries }), "toolGate.allowedToolsResolved") };
                 }],
         ];
-        const shadows = [];
+        const clearAs = async (member, hit) => {
+            const cleared = hit.clear();
+            pass.clearedBy = { ...allowRuleShadowOf(member, hit.entries), ...(hit.positions !== undefined ? { positions: hit.positions } : {}) };
+            await hit.afterClear();
+            if (member !== "hook")
+                afterRuleClear();
+            return cleared;
+        };
+        let shadows = [];
         if (!questionTool) {
             for (const [member, match] of members) {
                 if (pass.decision.action !== "ask")
@@ -298,13 +309,10 @@ export async function runGateLanes(pass) {
                 if (hit === undefined)
                     continue;
                 if (allowMayClear()) {
-                    pass.decision = hit.clear();
-                    await hit.afterClear();
-                    if (member !== "hook")
-                        afterRuleClear();
+                    pass.decision = await clearAs(member, hit);
                     break;
                 }
-                shadows.push(allowRuleShadowOf(member, hit.entries));
+                shadows = withAllowRuleShadow(shadows, allowRuleShadowOf(member, hit.entries));
                 hit.shadowed?.();
             }
         }
@@ -347,7 +355,7 @@ export async function runGateLanes(pass) {
             if (read?.kind === "denied")
                 refuseByExtension(read.deny);
             else if (read?.kind === "cleared")
-                pass.decision = read.allow;
+                pass.decision = await clearAs("hook", { entries: read.entries, clear: () => read.allow, afterClear: async () => undefined });
             else if (read?.kind === "asked") {
                 const asked = read.minted ? { ...read.ask, ruleEvidence: mintRuleEvidence(personalEvidence) } : read.ask;
                 if (read.marked === true)
@@ -356,7 +364,7 @@ export async function runGateLanes(pass) {
                 pass.decision = stampAskOrigin(asked, facts, classifyStanding(asked, facts));
             }
             else if (read?.kind === "shadowed" && pass.decision.action === "ask")
-                pass.decision = { ...pass.decision, allowRuleShadowed: [...(pass.decision.allowRuleShadowed ?? []), ...read.shadows] };
+                pass.decision = { ...pass.decision, allowRuleShadowed: read.shadows.reduce(withAllowRuleShadow, [...(pass.decision.allowRuleShadowed ?? [])]) };
             else if (read?.kind === "approved")
                 takeApprovedEdit(read);
         }
@@ -413,7 +421,6 @@ export async function runGateLanes(pass) {
         }
         if (input.sandboxAdmission !== undefined &&
             pass.decision.action === "ask" &&
-            wireOf("lanes.sandboxQuestionSkip", pass.req) !== ASK_USER_QUESTION_TOOL_NAME &&
             input.isMarkedUnresolvable?.(input.event.toolCallId) !== true &&
             pass.decision.requiresRealApproval !== true &&
             pass.decision.decisionReason !== "hook" &&
@@ -468,7 +475,7 @@ export async function runGateLanes(pass) {
                 pass.decision = refusalOf({
                     action: "deny",
                     message: verdict.mode === "dontAsk"
-                        ? `refused by the dontAsk permission mode: this call needed approval (${verdict.askClass}) and the mode answers no ask; run under a mode with an approver, or change the call`
+                        ? dontAskRefusalMessage({ toolName, classification: pass.askClassification, coveredWrite: isProtectedWrite(pass.req), ruleShape: ruleShapeOf(pass.req, "allow") ?? toolName })
                         : `refused by the bypassPermissions permission mode: the write-protection judge could not resolve this write's target, and with nobody to ask the mode refuses rather than releases it`,
                     decisionReason: "mode",
                 }, finalArgs);
@@ -480,7 +487,7 @@ export async function runGateLanes(pass) {
             if (parked)
                 return parked;
         }
-        if (pass.decision.action === "ask" && wireOf("lanes.contentAskRoute", pass.req) === ASK_USER_QUESTION_TOOL_NAME) {
+        if (pass.decision.action === "ask" && originFacts.contentQuestion) {
             const outcome = input.resolveContentAsk !== undefined ? await (callSignal !== undefined ? input.resolveContentAsk(pass.req, callSignal) : input.resolveContentAsk(pass.req)) : { kind: "unavailable", parkDeclined: false };
             if (outcome.kind === "answered") {
                 pass.decision = { action: "allow" };
@@ -548,7 +555,6 @@ export async function runGateLanes(pass) {
     if (approvedWithArgs && pass.decision.action === "allow" && pass.decision.updatedInput !== undefined) {
         let editArgs = pass.decision.updatedInput;
         let editDenied;
-        let editRewrittenSinceHuman = false;
         let editAnswer = pass.decision;
         let unanswered;
         const refusedAtResolution = (d) => { editDenied = d; pass.deniedBy = "ask_resolution"; };
@@ -571,6 +577,7 @@ export async function runGateLanes(pass) {
                 break;
             }
             let editHookAsk;
+            let rewrittenEdit = false;
             if (screening !== undefined) {
                 const screened = await screening.screen(editArgs, `the approved edit for "${toolName}"`);
                 if (screened.kind === "refused") {
@@ -591,9 +598,10 @@ export async function runGateLanes(pass) {
                         const { updatedInput: _adopted, ...ask } = hr;
                         editHookAsk = ask;
                     }
-                    if (hr.updatedInput !== undefined) {
-                        editArgs = argsAsTheToolReads(pass.req, hr.updatedInput);
-                        editRewrittenSinceHuman = true;
+                    const hookRead = readRejudge(pass.req, editArgs, hr);
+                    if (hookRead.kind === "rewritten") {
+                        editArgs = hookRead.form;
+                        rewrittenEdit = true;
                     }
                 }
             }
@@ -601,7 +609,7 @@ export async function runGateLanes(pass) {
             if (adjudicate) {
                 try {
                     const editReq = Object.freeze({ toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) });
-                    recheck = refuseOutOfContractDecision(await (callSignal !== undefined ? adjudicate(editReq, callSignal) : adjudicate(editReq)));
+                    recheck = refuseOutOfContractDecision(await (callSignal !== undefined ? adjudicate(editReq, callSignal) : adjudicate(editReq)), { call: editReq });
                 }
                 catch (err) {
                     reportPolicyThrow((e) => traceHookCrash(input, e, notifier), "the tool policy's re-check of the approved edit", { toolName, toolCallId }, err, callSignal ?? input.abortSignal);
@@ -624,9 +632,30 @@ export async function runGateLanes(pass) {
                     break;
                 }
             }
-            if (recheck.updatedInput !== undefined) {
-                editArgs = argsAsTheToolReads(pass.req, recheck.updatedInput);
-                editRewrittenSinceHuman = true;
+            const policyRead = recheck.action !== "deny" ? readRejudge(pass.req, editArgs, recheck) : undefined;
+            if (recheck.action !== "deny" && recheck.updatedInput !== undefined) {
+                const { updatedInput: _form, ...verdict } = recheck;
+                recheck = verdict;
+            }
+            if (policyRead?.kind === "rewritten") {
+                if (rewrittenEdit) {
+                    editDenied = { action: "deny", message: rewriteChasedSentence(toolName) };
+                    pass.deniedBy = "policy";
+                    break;
+                }
+                editArgs = policyRead.form;
+                rewrittenEdit = true;
+                const second = screening !== undefined ? await screenRewrite(screening, pass.req, editArgs, `the rewritten edit for "${toolName}"`) : undefined;
+                if (second?.kind === "refused") {
+                    editDenied = { action: "deny", message: second.reason };
+                    pass.deniedBy = "hook";
+                    break;
+                }
+                if (second?.kind === "stands") {
+                    if (second.answer?.additionalContext)
+                        pass.preToolContext.push(second.answer.additionalContext);
+                    editHookAsk = second.answer?.action === "ask" ? second.answer : undefined;
+                }
             }
             const editOrg = await applyOrgLayer(recheck, editArgs);
             recheck = editOrg.decision;
@@ -636,7 +665,7 @@ export async function runGateLanes(pass) {
             }
             let editLane;
             const editLaneReq = Object.freeze(await withArgsReading(pass.req, editArgs, callSignal ?? input.abortSignal));
-            if (input.persistedRules !== undefined && wireOf("lanes.persistedEditSkip", pass.req) !== ASK_USER_QUESTION_TOOL_NAME) {
+            if (input.persistedRules !== undefined && !routesContent(pass.req.face)) {
                 editLane = await readPersistedRules(editLaneReq);
                 const editTightened = applyPersistedTightening(recheck, editLane, editLaneReq);
                 recheck = editTightened.decision;
@@ -653,21 +682,17 @@ export async function runGateLanes(pass) {
                 pass.deniedBy = "policy";
                 break;
             }
-            if (recheck.action === "allow") {
-                if (recheck.updatedInput !== undefined) {
-                    editArgs = argsAsTheToolReads(pass.req, recheck.updatedInput);
-                    editRewrittenSinceHuman = true;
-                }
-                const answeredRecheck = withAttestation(recheck, mergeAttestation(pass.req, attestationOf(editAnswer, pass.req), attestationOf(recheck, pass.req), "answer"));
-                if (asksUnstated(answeredRecheck, pass.req, editArgs, permissionSeatAt(input, editArgs)?.seat, input.permissionMode?.())) {
-                    recheck = { action: "ask", message: permissionSeatAt(input, editArgs)?.question ?? unstatedAskMessage(toolName) };
-                    pass.tightenedBy = "unstated";
+            if (rewrittenEdit && input.writeProtectionCheck !== undefined) {
+                const check = input.writeProtectionCheck;
+                const verdict = await awaitWriteProtectionJudgment((deadline) => check(toolName, editArgs, pass.req.face, input.trackedCwd?.(), deadline), boundedAwaitDeadlineMs, callSignal ?? input.abortSignal);
+                if (verdict !== undefined && verdict.kind !== "clear") {
+                    editDenied = { action: "deny", message: verdict.kind === "hit" ? `the approved edit for "${toolName}" was rewritten by the restriction chain onto a write-protected path (table entry "${verdict.hit.name}") that no approval covers — denied fail-closed; re-submit the edited action directly` : `the approved edit for "${toolName}" was rewritten by the restriction chain onto a target whose destination could not be determined (target_unresolved: ${verdict.cause}) — denied fail-closed; re-submit the edited action directly` };
+                    pass.deniedBy = "write_protection";
+                    break;
                 }
             }
-            if (recheck.updatedInput !== undefined) {
-                editArgs = argsAsTheToolReads(pass.req, recheck.updatedInput);
-                editRewrittenSinceHuman = true;
-            }
+            if (rewrittenEdit)
+                recheck = outletAsk(recheck, toolName, editArgs);
             let editFacts;
             const stampEditAsk = (ask) => {
                 const editAskSnapshot = { ...ask, ruleEvidence: mintRuleEvidence({ dotsAbsent: "not_adjudicated" }) };
@@ -683,7 +708,9 @@ export async function runGateLanes(pass) {
             if (carriedOwnAsk !== undefined) {
                 const { updatedInput: _theOriginalBytes, ...carried } = carriedOwnAsk;
                 const rra = carried.requiresRealApproval === true ? { requiresRealApproval: true } : {};
-                editDecision = stampEditAsk(editDecision.action === "ask" ? { ...editDecision, foldedAskClasses: [...(editDecision.foldedAskClasses ?? []), ...decisionAskClassesOf(carried), ...(carried.classes ?? [])], ...rra } : carried);
+                const call = { toolCallId, toolName };
+                const folded = new Set([...(editDecision.action === "ask" ? (attestationOf(editDecision, call)?.foldedClasses ?? []) : []), ...decisionAskClassesOf(carried, call), ...(carried.classes ?? [])]);
+                editDecision = stampEditAsk(editDecision.action === "ask" ? attest({ ...editDecision, ...rra }, call, { foldedClasses: [...folded] }) : carried);
                 carriedOwnAsk = undefined;
             }
             const editRead = await checkTool(editDecision, editArgs, editOrg.org, undefined);
@@ -696,7 +723,6 @@ export async function runGateLanes(pass) {
                 carriedOwnAsk = editRead.outstanding ?? (editDecision.action === "ask" ? editDecision : undefined);
                 editArgs = editRead.allow.updatedInput;
                 editAnswer = editRead.allow;
-                editRewrittenSinceHuman = false;
                 continue;
             }
             if (editRead?.kind === "asked" && editRead.marked === true)
@@ -704,13 +730,13 @@ export async function runGateLanes(pass) {
             if (editRead?.kind === "asked")
                 editDecision = stampEditAsk(editRead.ask);
             else if (editRead?.kind === "shadowed" && editDecision.action === "ask")
-                editDecision = { ...editDecision, allowRuleShadowed: [...(editDecision.allowRuleShadowed ?? []), ...editRead.shadows] };
+                editDecision = { ...editDecision, allowRuleShadowed: editRead.shadows.reduce(withAllowRuleShadow, [...(editDecision.allowRuleShadowed ?? [])]) };
             if (editDecision.action !== "ask")
                 break;
             const editAskDecision = editDecision;
             if (input.permissionMode !== undefined && pass.askClassification !== undefined) {
                 const editVerdict = arbitrateByMode(input.permissionMode(), pass.askClassification, { ...(editAskDecision.origin !== undefined ? { origin: editAskDecision.origin } : {}), ...(editAskDecision.mandate !== undefined ? { mandate: editAskDecision.mandate } : {}) });
-                if (editVerdict.kind === "released") {
+                if (editVerdict.kind === "released" && !rewrittenEdit) {
                     ledger.supersede();
                     pass.arbitration = editVerdict;
                     await notifier.notifyAsync(() => input.onModeReleased?.({ toolName, toolCallId, release: { mode: editVerdict.mode, askClass: editVerdict.askClass, classes: editVerdict.classes, ...(editVerdict.origin !== undefined ? { origin: editVerdict.origin } : {}), ...(editVerdict.mandate !== undefined ? { mandate: editVerdict.mandate } : {}), ...(editVerdict.reason !== undefined ? { reason: editVerdict.reason } : {}) }, ...(pass.shellReadUnestablished === true ? { readUnestablished: true } : {}) }), "toolGate.onModeReleased");
@@ -732,34 +758,21 @@ export async function runGateLanes(pass) {
             const rr = ledger.fromResolved(await (callSignal !== undefined ? resolveAsk(editAskDecision, editAskReq, callSignal) : resolveAsk(editAskDecision, editAskReq)), editAskDecision, editAskReq);
             if (rr.action !== "allow") {
                 refusedAtResolution(rr);
+                if (rewrittenEdit)
+                    pass.denyDetails = { editRewritten: { acceptableForm: editArgs } };
                 if (rr.approverUnavailable === true)
                     unanswered = { ask: editAskDecision, req: editAskReq, org: editOrg.org, deny: rr };
                 break;
             }
             if (rr.updatedInput === undefined) {
-                editRewrittenSinceHuman = false;
                 break;
             }
             editArgs = rr.updatedInput;
             editAnswer = rr;
             if (editAskDecision.action === "ask")
                 editAskedOrigin = editAskDecision.origin;
-            editRewrittenSinceHuman = false;
         }
         const rejudged = () => editDenied === undefined || editDenied === unanswered?.deny;
-        if (rejudged() && editRewrittenSinceHuman && input.writeProtectionCheck !== undefined) {
-            const check = input.writeProtectionCheck;
-            const verdict = await awaitWriteProtectionJudgment((deadline) => check(toolName, editArgs, pass.req.face, input.trackedCwd?.(), deadline), boundedAwaitDeadlineMs, callSignal ?? input.abortSignal);
-            if (verdict !== undefined && verdict.kind !== "clear") {
-                editDenied = {
-                    action: "deny",
-                    message: verdict.kind === "hit"
-                        ? `the approved edit for "${toolName}" was rewritten by the restriction chain onto a write-protected path (table entry "${verdict.hit.name}") that no approval covers — denied fail-closed; re-submit the edited action directly`
-                        : `the approved edit for "${toolName}" was rewritten by the restriction chain onto a target whose destination could not be determined (target_unresolved: ${verdict.cause}) — denied fail-closed; re-submit the edited action directly`,
-                };
-                pass.deniedBy = "write_protection";
-            }
-        }
         if (rejudged() && input.shellReadCheck !== undefined) {
             const station = input.shellReadCheck;
             const judged = station.judge(pass.req, editArgs, input.trackedCwd?.(), callSignal ?? input.abortSignal, { seat: "rejudge", toolCallId });

package/dist/core/gate-outcome.d.ts

@@ -9,6 +9,8 @@
  */
 import { type AskClass, type AskOrigin, type AssertAllKeysHandled, type ModeReleaseReason, type PermissionMode, type PersistedRuleMandate } from "./ask-origin.js";
 import { type AutoModeClassifierRound, type AutoModeFallbackCause } from "./auto-mode.js";
+import { type AllowRuleClearance } from "./allow-rule-shadow.js";
+import type { ResolvedOutcome } from "./checkpoint-store.js";
 /**
  * How the wait an ask was in ENDED — the closed set. One word per way a wait can end; the `who` on the
  * record says which party ended it and is fixed BY the word (see {@link Settlement}).
@@ -243,6 +245,18 @@ export declare const SETTLEMENT_NOBODY_JUDGED: {
 };
 /** Compile-time fence: `never` while every settlement kind has a nobody-judged row. */
 export type NobodyJudgedTableCoversEveryKind = AssertAllKeysHandled<Exclude<SettlementKind, keyof typeof SETTLEMENT_NOBODY_JUDGED>>;
+/** Which words of a durable row's winner ({@link ResolvedOutcome.decision}) are the ALLOW direction: a tool approval's `allow`, a plan
+ *  pause's `approve` / `edit`; the others refuse. Total over the winner's words — the fence below refuses a word without a row — so
+ *  invariant I11 compares directions by table lookup. */
+declare const WINNER_DECISION_ALLOWS: {
+    readonly allow: true;
+    readonly approve: true;
+    readonly edit: true;
+    readonly deny: false;
+    readonly reject: false;
+};
+/** Compile-time fence: `never` while every word a winner can hold has a direction row. */
+export type WinnerDecisionTableCoversEveryDecision = AssertAllKeysHandled<Exclude<ResolvedOutcome["decision"], keyof typeof WINNER_DECISION_ALLOWS>>;
 /**
  * WHO REFUSED a call — the layer whose verdict is the deny. The other question a deny raises, "who ASKED",
  * is answered by {@link GateOutcome.origin} (an {@link import("./ask-origin.js").AskOrigin}); the two used
@@ -302,9 +316,9 @@ export type VetoTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedBy
  * deny came through the classifier station. The classifier ends a round three ways, and until this
  * member the wire carried the three as one layer word plus prose:
  *  - `unavailable` — the classifier could not run (the model leg threw / rejected / ran past the cap):
- *    a fail-closed refusal that SAYS SO — the call may simply be retried later (CC 2.1.250 `x1t`);
+ *    a fail-closed refusal that SAYS SO — the call may simply be retried later;
  *  - `parse_error` — the classifier answered outside its verdict contract: blocked for safety, counted by
- *    the denial limit like a ruling (CC 2.1.250 `Ure`);
+ *    the denial limit like a ruling;
  *  - ABSENT beside `deniedBy: "classifier"` — the classifier's own RULING (a `<block>yes` verdict).
  * The WHY behind an `unavailable` (error vs timeout) is not a branching fact: the deny sentence spells it
  * and the `auto_mode.classified` trace frame carries it (`cause: "error" | "timeout"`).
@@ -350,11 +364,19 @@ export type CauseTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedB
  *  candidate ladder and can name no model (a hand-built decider; a parked ancestor's cross-process rebuild,
  *  whose single fresh leg has none); or one did not rule (it could not run, or replied with no verdict) and
  *  handed the question to the approval seat, whose settlement then names the resolution that ask reached.
- *  Additive. Invariant I6 ({@link screenGateOutcome}) screens its shape. */
+ *  Additive. Invariant I6 ({@link screenGateOutcome}) screens its shape.
+ *
+ *  `clearedBy` — the allow layer's account of a call it let run without asking: which member cleared the ask (`hook`, an
+ *  extension's `classic.PreToolUse` or `tool.check` allow, / `deployment` / `persisted` / `skill` / `request`) and the entries it stood on, sanitized and capped as a shadow
+ *  record is, with `positions` for a list member (the indices of those entries in the list the run received — a host maps them
+ *  onto the declaration it sent for this run). Present exactly when an allow member cleared a standing ask and nobody answered
+ *  it: absent on a call nothing asked about, a mode's release or acceptance, the read-only arm's, the classifier's or the
+ *  sandbox's allow, and a person's yes. Additive. Invariant I9 ({@link screenGateOutcome}) screens its shape. */
 export type GateDisposition = {
     kind: "allowed";
     classifier?: AutoModeClassifierRound;
     released?: ModeRelease;
+    clearedBy?: AllowRuleClearance;
 } | {
     kind: "denied";
     deniedBy: DeniedBy;
@@ -395,7 +417,7 @@ export interface ModeRefusal {
  * payload, the call's `tool_end` frame, and the durable row's resolved outcome. The three faces are the
  * same object graph, so they cannot tell different stories.
  *
- * The three members are orthogonal but bound by four invariants ({@link screenGateOutcome}):
+ * The three members are orthogonal but bound by the invariants ({@link screenGateOutcome}):
  *  I1  `settlement` present ⇔ `origin` present (they describe the same ask);
  *  I2  `disposition.deniedBy === "ask_resolution"` ⇒ `settlement` present and a refusal kind;
  *  I3  `settlement` an approval (a kind {@link SETTLEMENT_IS_REFUSAL} says is not a refusal) ∧
@@ -415,7 +437,15 @@ export interface ModeRefusal {
  *      record outlives the policy of its day), every member of `classes` is an ask class, `origin` / `mandate` / `reason`,
  *      when present, are members of their closed sets, and `reason` names a member of `classes` (the mint takes it from
  *      that set) — a mode releases nothing a person answered;
- *  I8  `deniedBy === "mode"` ⇔ `mode` present (`bypassPermissions` | `dontAsk`) with `askClass` and `classes`.
+ *  I8  `deniedBy === "mode"` ⇔ `mode` present (`bypassPermissions` | `dontAsk`) with `askClass` and `classes`;
+ *  I9  `disposition.clearedBy` present ⇒ `kind === "allowed"`, no settlement and no release (an allow member cleared the ask
+ *      before anyone answered it), `member` one of the allow layer's members, `entries` a list of strings, `omitted` a positive
+ *      whole number when present, and `positions` — only on a list member (`request`, `deployment`) — a list of non-negative
+ *      whole numbers;
+ *  I10 `settlement.when` present ⇒ a finite number (epoch ms — the moment the wait ended is a value a reader can order);
+ *  I11 a winner's `decision` stated beside the record (the caller reads a durable row: `winnerDecision`) ⇒ a word a winner holds,
+ *      and its direction (allow: `allow` / `approve` / `edit`; refusal: `deny` / `reject`) is the direction of the record's
+ *      settlement ({@link SETTLEMENT_IS_REFUSAL}) and of its disposition (`allowed` / `denied`) — one decision, one direction.
  * Nothing here is read out of an ABSENCE: an ordinary allow with no ask is `{ disposition: { kind: "allowed" } }`,
  * a direct policy deny is `{ disposition: { kind: "denied", deniedBy: "policy" } }`, and neither carries a
  * settlement because neither settled one.
@@ -493,7 +523,7 @@ type DenyOnlyMember = Exclude<keyof Extract<GateDisposition, {
 /** Compile-time fence: `never` while the list is exactly the denied arm's own members. */
 export type DenyOnlyMembersAreListed = AssertAllKeysHandled<Exclude<DenyOnlyMember, (typeof DENY_ONLY_MEMBERS)[number]> | Exclude<(typeof DENY_ONLY_MEMBERS)[number], DenyOnlyMember>>;
 /**
- * The one invariant screen for a {@link GateOutcome} (I1–I8 above, plus the closed-set word each member carries). Two readings:
+ * The one invariant screen for a {@link GateOutcome} (I1–I11 above, plus the closed-set word each member carries). Two readings:
  *  - `"archive"` (the default) — a record read back from where it was kept (a replay, a ledger, a durable row): its shape, with
  *    every closed set read as its live members plus {@link RETIRED_MEMBERS}. A record lawful when minted is not a defect later.
  *  - `"producer"` — a record THIS engine is composing or publishing now: the live sets alone, and the engine's release law
@@ -501,10 +531,14 @@ export type DenyOnlyMembersAreListed = AssertAllKeysHandled<Exclude<DenyOnlyMemb
  * The record is read as whatever it holds (`unknown`): a member that is not the shape the type names — `null`, an array, a
  * primitive where a record belongs, an object where a word belongs — is a defect naming its position, never an exception, and
  * every class, reason, origin and mandate word is read wherever the record carries it.
+ * A caller reading a durable row's winner ({@link ResolvedOutcome}) states the winner's `decision` beside the record it carries
+ * (`winnerDecision`, the key present whatever it holds, read as `reading` is read): invariant I11 then reads that word, so the decision and the record it filed
+ * cannot be read as two directions. Without the key there is no winner beside the record and I11 reads nothing.
  * Returns the defects as sentences (an empty list is a clean record); the caller decides the fail-loud form (report + withhold,
  * or refuse), never silently repairs the record. An options value that is not an object, or a reading outside the two, throws.
  */
 export declare function screenGateOutcome(g: unknown, opts?: {
     readonly reading?: "archive" | "producer";
+    readonly winnerDecision?: unknown;
 }): string[];
 export {};

package/dist/core/gate-outcome.js

@@ -1,5 +1,6 @@
 import { isAskClass, isAskOrigin, isModeReleaseReason, isPermissionMode, isPersistedRuleMandate, ASK_FACES, releasableAskClassesFor } from "./ask-origin.js";
 import { isAutoModeFallbackCause } from "./auto-mode.js";
+import { ALLOW_RULE_MEMBERS } from "./allow-rule-shadow.js";
 export const SETTLEMENT_KINDS = Object.freeze([
     "human_allowed",
     "human_refused",
@@ -74,6 +75,16 @@ export const SETTLEMENT_NOBODY_JUDGED = {
     policy_refused: true,
     task_aborted: false,
 };
+const WINNER_DECISION_ALLOWS = {
+    allow: true,
+    approve: true,
+    edit: true,
+    deny: false,
+    reject: false,
+};
+function isWinnerDecision(v) {
+    return typeof v === "string" && Object.hasOwn(WINNER_DECISION_ALLOWS, v);
+}
 export const DENIED_BY_VALUES = Object.freeze(["policy", "hook", "org", "persisted_rule", "classifier", "compliance", "write_protection", "ask_resolution", "read_boundary", "mode"]);
 const DENIED_BY_SET = new Set(DENIED_BY_VALUES);
 export function isDeniedBy(v) {
@@ -153,6 +164,31 @@ export function releasePolicyDefects(g) {
     const held = [askClass, ...classes];
     return ASK_FACES.some((face) => held.every((c) => releasableAskClassesFor(face).includes(c))) ? [] : [`I7: released.classes ${JSON.stringify(classes)} is not a set one face of this engine's table releases`];
 }
+const LIST_MEMBERS = new Set(["request", "deployment"]);
+const ALLOW_MEMBER_SET = new Set(ALLOW_RULE_MEMBERS);
+function clearanceDefects(v, settled, released) {
+    const c = objectOf(v);
+    if (c === undefined)
+        return [`I9: disposition.clearedBy is not an object (${shapeOf(v)})`];
+    const out = [];
+    if (settled)
+        out.push("I9: a clearance carries no settlement — an allow rule cleared the ask before anyone answered it");
+    if (released)
+        out.push("I9: a clearance stands beside no mode release — the ask it cleared never reached the mode");
+    if (!ALLOW_MEMBER_SET.has(c.member))
+        out.push(`I9: clearedBy.member ${spelled(c.member)} is not one of the allow layer's members (${ALLOW_RULE_MEMBERS.join(", ")})`);
+    if (!Array.isArray(c.entries) || !c.entries.every((e) => typeof e === "string"))
+        out.push("I9: clearedBy.entries must be a list of strings");
+    if (c.omitted !== undefined && !(typeof c.omitted === "number" && Number.isInteger(c.omitted) && c.omitted > 0))
+        out.push(`I9: clearedBy.omitted ${spelled(c.omitted)} is not a positive whole number`);
+    if (c.positions !== undefined) {
+        if (!LIST_MEMBERS.has(c.member))
+            out.push(`I9: clearedBy.positions stands only on a list member (request, deployment), not ${spelled(c.member)}`);
+        if (!Array.isArray(c.positions) || !c.positions.every((p) => typeof p === "number" && Number.isInteger(p) && p >= 0))
+            out.push("I9: clearedBy.positions must be a list of non-negative whole numbers");
+    }
+    return out;
+}
 const DENY_ONLY_MEMBERS = Object.freeze(["deniedBy", "cause", "mode", "askClass", "classes"]);
 function objectOf(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v) ? v : undefined;
@@ -205,6 +241,8 @@ export function screenGateOutcome(g, opts) {
     const party = objectOf(s?.who)?.party;
     if (s !== undefined && !member("settlementParty", party))
         defects.push(outside("settlement.who.party", "settlementParty", party));
+    if (s !== undefined && !(typeof s.when === "number" && Number.isFinite(s.when)))
+        defects.push(`I10: settlement.when ${spelled(s.when)} is not a finite number (epoch ms)`);
     if (record.origin !== undefined && !member("askOrigin", record.origin))
         defects.push(outside("origin", "askOrigin", record.origin));
     if (settled !== (record.origin !== undefined))
@@ -252,6 +290,10 @@ export function screenGateOutcome(g, opts) {
                 defects.push(`I7: released.reason "${String(r.reason)}" is not a member of released.classes`);
         }
     }
+    if (denied !== undefined && denied.clearedBy !== undefined)
+        defects.push("I9: disposition.clearedBy stands only on an allowed disposition");
+    if (d !== undefined && d.clearedBy !== undefined)
+        defects.push(...clearanceDefects(d.clearedBy, settled, d.released !== undefined));
     if (denied !== undefined) {
         const modeRefusal = denied.deniedBy === "mode";
         if (modeRefusal !== (denied.mode !== undefined))
@@ -287,6 +329,20 @@ export function screenGateOutcome(g, opts) {
             }
         }
     }
+    if (opts !== undefined && "winnerDecision" in opts) {
+        const decision = opts.winnerDecision;
+        if (!isWinnerDecision(decision))
+            defects.push(`I11: winnerDecision ${spelled(decision)} is none of the words a winner holds (${Object.keys(WINNER_DECISION_ALLOWS).join(", ")})`);
+        else {
+            const allows = WINNER_DECISION_ALLOWS[decision];
+            const says = allows ? "allow" : "refusal";
+            if (kind !== undefined && SETTLEMENT_IS_REFUSAL[kind] === allows)
+                defects.push(`I11: the winner's decision "${decision}" is the ${says} direction but the settlement kind ${kind} ended the wait as ${allows ? "a refusal" : "an approval"}`);
+            const recordAllows = allowed !== undefined ? true : denied !== undefined ? false : undefined;
+            if (recordAllows !== undefined && recordAllows !== allows)
+                defects.push(`I11: the winner's decision "${decision}" is the ${says} direction but the disposition reads ${recordAllows ? "allowed" : "denied"}`);
+        }
+    }
     if (producer)
         defects.push(...releasePolicyDefects(g));
     return defects;