@sema-agent/core 7.33.8 → 7.35.0

package/dist/core/gate-lanes.js

@@ -1,14 +1,18 @@
 import { attestClassifierDenyCause, classifierDenyCauseOf, decisionText, describeThrown } from "./tool-policy.js";
-import { classifierMayAnswer, classifierMayAnswerMandate, mandateDisclosureOf, persistedRuleMandateOf, ruleClearanceOf, safetyAxisOf, sandboxMayAdmitMandate, stampAskOrigin } from "./ask-origin.js";
-import { classifierParseFailureDenyMessage, classifierUnavailableDenyMessage, denialLimitFallbackMessage, unarmedWindow } from "./auto-mode.js";
+import { arbitrateByMode, classifyAsk, fileCommandOptionsSentence, mandateDisclosureOf, persistedRuleMandateOf, ruleClearanceOf, safetyAxisOf, stampAskOrigin } from "./ask-origin.js";
+import { classifierParseFailureDenyMessage, denialLimitFallbackMessage, unarmedWindow } from "./auto-mode.js";
+import { classifierUnavailableArm } from "./classifier-unavailable-arm.js";
 import { SETTLEMENT_NOBODY_JUDGED } from "./gate-outcome.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { isRuleBehavior } from "./permission-rule-model.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 import { applyPersistedTightening, disclosedRuleSet } from "./persisted-rule-arms.js";
-import { readOnlyShellVerdict } from "./read-only-shell.js";
+import { CD_GIT_COMPOUND_SENTENCE, changesDirectoryBeforeGit, readOnlyShellVerdict } from "./read-only-shell.js";
+import { readShellCommand } from "./shell-lexer.js";
 import { COMMAND_RULE_TOOL } from "./permission-rule-model.js";
 import { catalogRuleFaceOf } from "./tool-registry.js";
+import { callAnswersTo, callFaceSeat } from "./tool-roster.js";
+import { modeAcceptsFileCommand } from "./mode-policy.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
 import { exitGate } from "./runner/gate-exit.js";
 import { traceHookCrash } from "./gate-crash-trace.js";
@@ -165,14 +169,19 @@ export async function runGateLanes(pass) {
         writeProtected: pass.writeProtected === true,
         writeProtectionUnresolved: pass.writeProtectionUnresolved === true,
     });
-    const askOriginFacts = (org, ruleStore) => ({
-        contentQuestion: toolName === ASK_USER_QUESTION_TOOL_NAME,
+    const askOriginFacts = (org, ruleCallUnreadable) => ({
+        contentQuestion: callAnswersTo(pass.req, ASK_USER_QUESTION_TOOL_NAME),
         markedUnresolvable: markedUnresolvable(),
         org,
-        ...(ruleStore !== undefined ? { ruleStore } : {}),
+        ...(ruleCallUnreadable ? { ruleCallUnreadable } : {}),
         tightened: pass.tightenedBy,
         mandateMarks: mandateMarksNow(),
+        ...(input.toolMarkSources !== undefined ? { toolMarkSources: input.toolMarkSources } : {}),
+        ...(input.a2aIsolatePeers === true ? { a2aIsolatePeers: true } : {}),
     });
+    const classifyStanding = (unstamped, facts) => {
+        pass.askClassification = classifyAsk(unstamped, facts);
+    };
     let orgTightenCount = 0;
     let orgEvidence = (() => {
         const w = input.orgRules === undefined ? "not_wired" : "not_adjudicated";
@@ -191,7 +200,7 @@ export async function runGateLanes(pass) {
         let decided = current;
         let pending;
         try {
-            pending = Promise.resolve(input.orgRules.adjudicate({ toolName, args, toolCallId }));
+            pending = Promise.resolve(input.orgRules.adjudicate({ toolName, args, toolCallId, ...callFaceSeat(pass.req.face) }));
         }
         catch (err) {
             pending = Promise.resolve({ status: "unavailable", disclosures: [`the org adjudication face threw before answering: ${describeThrown(err)}`] });
@@ -208,18 +217,14 @@ export async function runGateLanes(pass) {
             orgEvidence = { revisionAbsent: "unavailable", ruleAbsent: "unavailable" };
             orgRealApprovalRequired = true;
             await notifier.notifyAsync(() => input.orgRules?.onUnavailable?.({ toolName, toolCallId, message: answer.disclosures.join("; ") }), "toolGate.orgSnapshotUnavailable");
+            const orgUnavailableMessage = `tool "${toolName}" needs approval: this deployment is org-governed and cannot currently adjudicate ` +
+                `against an organization policy snapshot — every allow tightens to a real approval until it can`;
             if (decided.action === "allow") {
-                decided = {
-                    action: "ask",
-                    message: `tool "${toolName}" needs approval: this deployment is org-governed and cannot currently adjudicate ` +
-                        `against an organization policy snapshot — every allow tightens to a real approval until it can`,
-                    decisionReason: ORG_UNAVAILABLE_DECISION_REASON,
-                    requiresRealApproval: true,
-                };
+                decided = { action: "ask", message: orgUnavailableMessage, decisionReason: ORG_UNAVAILABLE_DECISION_REASON, requiresRealApproval: true };
                 orgTightenCount += 1;
             }
             else if (decided.action === "ask" && decided.requiresRealApproval !== true) {
-                decided = { ...decided, requiresRealApproval: true };
+                decided = { ...decided, requiresRealApproval: true, ...(pass.tightenedBy !== undefined ? { message: orgUnavailableMessage } : {}) };
                 orgTightenCount += 1;
             }
             return { decision: decided, org: "unavailable" };
@@ -241,23 +246,20 @@ export async function runGateLanes(pass) {
             return { decision: decided, org: undefined };
         orgTightenCount += 1;
         orgRealApprovalRequired = true;
+        const orgRuleMessage = unreadable !== undefined
+            ? `an organization policy rule (${rule}) may reach this call, which could not be read against it (${unreadable}) — a person must decide`
+            : `an organization policy rule (${rule}) requires approval for this call`;
         return {
             decision: decided.action === "ask"
-                ? { ...decided, requiresRealApproval: true }
-                : {
-                    action: "ask",
-                    message: unreadable !== undefined
-                        ? `an organization policy rule (${rule}) may reach this call, which could not be read against it (${unreadable}) — a person must decide`
-                        : `an organization policy rule (${rule}) requires approval for this call`,
-                    decisionReason: ORG_RULE_DECISION_REASON,
-                    requiresRealApproval: true,
-                },
+                ?
+                    { ...decided, requiresRealApproval: true, ...(decided.requiresRealApproval !== true && pass.tightenedBy !== undefined ? { message: orgRuleMessage } : {}) }
+                : { action: "ask", message: orgRuleMessage, decisionReason: ORG_RULE_DECISION_REASON, requiresRealApproval: true },
             org: "rule",
         };
     };
     const orgAnswer = await applyOrgLayer(pass.decision, pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput);
     pass.decision = orgAnswer.decision;
-    const ruleStoreUnreadableOf = (lane) => lane?.unreadable === true ? (lane.reason !== undefined ? "call" : "store") : undefined;
+    const ruleCallUnreadableOf = (lane) => lane?.unreadable === true && lane.reason !== undefined;
     const readPersistedRules = async (req) => {
         let pendingHit;
         try {
@@ -348,10 +350,10 @@ export async function runGateLanes(pass) {
                 };
             }
         }
-        const originFacts = askOriginFacts(orgAnswer.org, ruleStoreUnreadableOf(laneAnswer));
+        const originFacts = askOriginFacts(orgAnswer.org, ruleCallUnreadableOf(laneAnswer));
         if (pass.decision.action === "ask") {
-            const { ruleStoreUnreadable: _selfDeclared, ...unstamped } = pass.decision;
-            const stamped = { ...unstamped, ruleEvidence: mintRuleEvidence(personalEvidence), ...(laneCoverage !== undefined ? { segmentCoverage: laneCoverage } : {}), ...(originFacts.ruleStore !== undefined ? { ruleStoreUnreadable: originFacts.ruleStore } : {}) };
+            const stamped = { ...pass.decision, ruleEvidence: mintRuleEvidence(personalEvidence), ...(laneCoverage !== undefined ? { segmentCoverage: laneCoverage } : {}) };
+            classifyStanding(stamped, originFacts);
             pass.decision = stampAskOrigin(stamped, originFacts);
         }
         if (allowLayerMayClear() && pass.decision.action === "ask" && ruleMayClear() && pass.probeBoundaryDeclined !== true && pass.req.toolName === COMMAND_RULE_TOOL) {
@@ -359,7 +361,8 @@ export async function runGateLanes(pass) {
             const args = pass.req.args;
             const command = typeof args === "object" && args !== null && !Array.isArray(args) ? args[commandParam] : undefined;
             const backgrounded = typeof args === "object" && args !== null && args.run_in_background === true;
-            if (typeof command === "string" && !backgrounded && readOnlyShellVerdict(command).readOnly) {
+            const shape = typeof command === "string" ? readShellCommand(command) : undefined;
+            if (typeof command === "string" && shape !== undefined && !backgrounded && readOnlyShellVerdict(command, shape, input.trackedCwd?.()).readOnly) {
                 pass.decision = {
                     action: "allow",
                     message: "the command is read-only (upstream's read-only command tables) — allowed without asking",
@@ -368,15 +371,21 @@ export async function runGateLanes(pass) {
                 };
                 await notifier.notifyAsync(() => input.onReadOnlyAllowed?.({ toolName: pass.req.toolName, toolCallId, command }), "toolGate.readOnlyAllowed");
             }
+            else if (shape !== undefined && pass.tightenedBy === "shell_gate" && changesDirectoryBeforeGit(shape, input.trackedCwd?.())) {
+                pass.decision = { ...pass.decision, message: CD_GIT_COMPOUND_SENTENCE };
+            }
         }
         if (pass.decision.action === "ask")
             ledger.supersede();
-        if (input.autoMode && pass.decision.action === "ask" && pass.decision.origin !== undefined && classifierMayAnswer(pass.decision.origin) && classifierMayAnswerMandate(persistedRuleMandate)) {
-            const verdict = await input.autoMode.decider
-                .decide({ req: pass.req, askMessage: decisionText(pass.decision) }, input.abortSignal)
+        if (input.autoMode && pass.decision.action === "ask" && pass.decision.origin !== undefined && pass.askClassification?.row.classifierEligible === true && (input.permissionMode === undefined || input.permissionMode() === "auto")) {
+            const classifySignal = callSignal ?? input.abortSignal;
+            const heard = await input.autoMode.decider
+                .decide({ req: pass.req, askMessage: decisionText(pass.decision) }, classifySignal)
                 .catch(() => ({ kind: "unavailable", cause: "error" }));
-            pass.classifierRound = verdict.classifier;
-            if (verdict.kind === "allow") {
+            const verdict = heard.kind === "allow" && input.permissionMode !== undefined && input.permissionMode() !== "auto" ? undefined : heard;
+            if (verdict !== undefined)
+                pass.classifierRound = verdict.classifier;
+            if (verdict?.kind === "allow") {
                 input.autoMode.denialTracking?.recordAllow();
                 pass.decision = {
                     action: "allow",
@@ -385,14 +394,17 @@ export async function runGateLanes(pass) {
                     ...(pass.policyRewrite !== undefined ? { updatedInput: pass.policyRewrite } : {}),
                 };
             }
-            else if (verdict.kind === "unavailable") {
-                pass.decision = attestClassifierDenyCause({
-                    action: "deny",
-                    message: classifierUnavailableDenyMessage(toolName, verdict.cause, verdict.classifier),
-                    decisionReason: "classifier",
-                }, "unavailable", pass.req);
+            else if (verdict?.kind === "unavailable") {
+                const arm = classifierUnavailableArm({ ask: pass.decision, req: pass.req, cause: verdict.cause, attribution: verdict.classifier, seat: input.autoMode.unavailable, aborted: classifySignal?.aborted === true });
+                if (arm.kind === "asked") {
+                    classifyStanding(arm.ask, originFacts);
+                    pass.decision = stampAskOrigin(arm.ask, originFacts);
+                    pass.classifierRound = undefined;
+                }
+                else
+                    pass.decision = arm.deny;
             }
-            else {
+            else if (verdict !== undefined) {
                 const reason = verdict.kind === "block" ? (verdict.reason ? inlineUntrusted(verdict.reason) : "") : classifierParseFailureDenyMessage(verdict.classifier);
                 const category = verdict.kind === "block" && verdict.category ? inlineUntrusted(verdict.category) : "";
                 const tracked = input.autoMode.denialTracking?.recordBlock();
@@ -404,6 +416,7 @@ export async function runGateLanes(pass) {
                         requiresRealApproval: true,
                         denialLimitFallback: tracked.fallback,
                     };
+                    classifyStanding(fallbackAsk, originFacts);
                     pass.decision = stampAskOrigin(fallbackAsk, originFacts);
                 }
                 else {
@@ -430,7 +443,7 @@ export async function runGateLanes(pass) {
             pass.hookAsk === undefined &&
             input.egress !== true &&
             input.peerMessage !== true &&
-            sandboxMayAdmitMandate(persistedRuleMandate) &&
+            pass.askClassification?.row.sandboxAdmission === true &&
             pass.probeBoundaryDeclined !== true &&
             input.sandboxAdmission.boundaryCapable !== true) {
             const recorded = input.sandboxAdmission.askClassesOf(toolCallId);
@@ -447,6 +460,42 @@ export async function runGateLanes(pass) {
                 };
             }
         }
+        if (pass.decision.action === "ask" && input.permissionMode !== undefined && pass.askClassification !== undefined) {
+            const standing = pass.decision;
+            const mode = input.permissionMode();
+            const fileCommandByWord = modeAcceptsFileCommand(mode, toolName, pass.policyRewrite ?? pass.currentInput);
+            const verdict = arbitrateByMode(mode, pass.askClassification, { ...(standing.origin !== undefined ? { origin: standing.origin } : {}), ...(standing.mandate !== undefined ? { mandate: standing.mandate } : {}) }, { fileCommand: pass.shellWritesPlaced === true && fileCommandByWord });
+            if (verdict.kind === "ask" && fileCommandByWord && pass.shellWritesPlaced !== true && pass.shellUnplacedOptions !== undefined && pass.askClassification.classes.size === 1 && pass.askClassification.classes.has("ordinary")) {
+                pass.decision = { ...standing, message: fileCommandOptionsSentence(pass.shellUnplacedOptions.program) };
+            }
+            if (verdict.kind === "accepted") {
+                ledger.supersede();
+                pass.decision = { action: "allow", message: `accepted by the ${verdict.mode} permission mode (one of its file commands)`, decisionReason: "mode", ...(pass.policyRewrite !== undefined ? { updatedInput: pass.policyRewrite } : {}) };
+            }
+            else if (verdict.kind === "released") {
+                pass.arbitration = verdict;
+                ledger.supersede();
+                await notifier.notifyAsync(() => input.onModeReleased?.({ toolName, toolCallId, release: { mode: verdict.mode, askClass: verdict.askClass, classes: verdict.classes, ...(verdict.origin !== undefined ? { origin: verdict.origin } : {}), ...(verdict.mandate !== undefined ? { mandate: verdict.mandate } : {}), ...(verdict.reason !== undefined ? { reason: verdict.reason } : {}) }, ...(pass.shellReadUnestablished === true ? { readUnestablished: true } : {}) }), "toolGate.onModeReleased");
+                pass.decision = {
+                    action: "allow",
+                    message: `released by the ${verdict.mode} permission mode (the ${verdict.askClass} ask was not put to anyone)`,
+                    decisionReason: "mode",
+                    ...(pass.policyRewrite !== undefined ? { updatedInput: pass.policyRewrite } : {}),
+                };
+            }
+            else if (verdict.kind === "denied_by_mode") {
+                pass.arbitration = verdict;
+                pass.deniedBy = "mode";
+                pass.denyCause = undefined;
+                pass.decision = {
+                    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`
+                        : `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",
+                };
+            }
+        }
         const safety = safetyAxisOf({
             egress: input.egress,
             shellGated: input.shellGated,
@@ -466,8 +515,8 @@ export async function runGateLanes(pass) {
             ...(callSignal !== undefined ? { signal: callSignal } : {}),
             ...(d.action === "ask" && d.denialLimitFallback !== undefined ? { denialLimitFallback: unarmedWindow(d.denialLimitFallback) } : {}),
             ...(d.action === "ask" && d.origin !== undefined ? { origin: d.origin } : {}),
-            ...(d.action === "ask" && d.ruleStoreUnreadable !== undefined ? { ruleStoreUnreadable: d.ruleStoreUnreadable } : {}),
             ...(d.action === "ask" && d.mandated === true ? { mandated: true, ...(d.mandate !== undefined ? { mandate: d.mandate } : {}) } : {}),
+            ...(d.action === "ask" && d.authoredBy === "deployment" ? { authoredBy: "deployment" } : {}),
         });
         if (suspendAsk && pass.decision.action === "ask") {
             const parkArgs = [pass.req, pass.currentInput, safety, undefined, realApprovalOf(pass.decision), pass.decision.action === "ask" ? pass.decision.persistedRuleShadowed : undefined, pass.decision.action === "ask" ? pass.decision.decisionReason : undefined, pass.decision.action === "ask" ? pass.decision.probeReason : undefined, pass.decision.action === "ask" ? pass.decision.probeCause : undefined, pass.decision.action === "ask" ? pass.decision.segmentCoverage : undefined, pass.decision.action === "ask" ? pass.decision.matchedAskRule : undefined, pass.decision.action === "ask" ? pass.decision.probeMandated : undefined];
@@ -642,10 +691,10 @@ export async function runGateLanes(pass) {
                         editDenied = recheck;
                         break;
                     }
-                    let editRuleStore;
+                    let editRuleCallUnreadable = false;
                     if (input.persistedRules !== undefined && toolName !== ASK_USER_QUESTION_TOOL_NAME) {
                         const editLane = await readPersistedRules({ toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) });
-                        editRuleStore = ruleStoreUnreadableOf(editLane);
+                        editRuleCallUnreadable = ruleCallUnreadableOf(editLane);
                         const editTightened = applyPersistedTightening(recheck, editLane);
                         recheck = editTightened.decision;
                         if (editTightened.tightened === "deny")
@@ -666,10 +715,27 @@ export async function runGateLanes(pass) {
                         editArgs = recheck.updatedInput;
                         editRewrittenSinceHuman = true;
                     }
-                    const { ruleStoreUnreadable: _selfDeclaredOnEdit, ...recheckUnstamped } = recheck;
-                    const editAskSnapshot = { ...recheckUnstamped, ruleEvidence: mintRuleEvidence({ dotsAbsent: "not_adjudicated" }) };
+                    const editAskSnapshot = { ...recheck, ruleEvidence: mintRuleEvidence({ dotsAbsent: "not_adjudicated" }) };
                     markedThisRound = undefined;
-                    const editAskDecision = stampAskOrigin({ ...editAskSnapshot, ...(editRuleStore !== undefined ? { ruleStoreUnreadable: editRuleStore } : {}) }, askOriginFacts(editOrg.org, editRuleStore));
+                    const editFacts = askOriginFacts(editOrg.org, editRuleCallUnreadable);
+                    classifyStanding(editAskSnapshot, editFacts);
+                    const editAskDecision = stampAskOrigin(editAskSnapshot, editFacts);
+                    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") {
+                            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");
+                            break;
+                        }
+                        if (editVerdict.kind === "denied_by_mode") {
+                            ledger.supersede();
+                            pass.arbitration = editVerdict;
+                            editDenied = { action: "deny", message: `the approved edit for "${toolName}" raised a new approval requirement that the ${editVerdict.mode} permission mode refuses`, decisionReason: "mode" };
+                            pass.deniedBy = "mode";
+                            break;
+                        }
+                    }
                     const editAskReq = { toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) };
                     const rr = await (callSignal !== undefined ? resolveAsk(editAskDecision, editAskReq, callSignal) : resolveAsk(editAskDecision, editAskReq));
                     ledger.fromResolved(rr, editAskDecision, toolName);
@@ -702,14 +768,14 @@ export async function runGateLanes(pass) {
                 }
                 if (editDenied === undefined && input.shellReadCheck !== undefined) {
                     const station = input.shellReadCheck;
-                    const judged = station.judge(toolName, editArgs, input.trackedCwd?.(), callSignal ?? input.abortSignal, { seat: "rejudge", toolCallId });
+                    const judged = station.judge(pass.req, editArgs, input.trackedCwd?.(), callSignal ?? input.abortSignal, { seat: "rejudge", toolCallId });
                     if (judged !== null) {
                         let verdict;
                         try {
                             verdict = await withGateTimeout(judged, boundedAwaitDeadlineMs(), callSignal ?? input.abortSignal, "shellReadStation");
                         }
                         catch {
-                            verdict = station.unanswered(toolName, "the read station could not answer");
+                            verdict = station.unanswered(pass.req, "the read station could not answer");
                         }
                         if (verdict.disposition !== "vouch") {
                             editDenied = {

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

@@ -7,7 +7,7 @@
  * policy composes: a policy says allow / ask / deny; this file says how the pass that consumed that
  * verdict ended.
  */
-import { type AskOrigin, type AssertAllKeysHandled } from "./ask-origin.js";
+import { type AskClass, type AskOrigin, type AssertAllKeysHandled, type PermissionMode, type PersistedRuleMandate } from "./ask-origin.js";
 import { type AutoModeClassifierRound } from "./auto-mode.js";
 /**
  * How the wait an ask was in ENDED — the closed set. One word per way a wait can end; the `who` on the
@@ -197,7 +197,8 @@ export type NobodyJudgedTableCoversEveryKind = AssertAllKeysHandled<Exclude<Sett
  *  - `org` — an organization policy rule denied.
  *  - `classifier` — the auto-mode classifier denied directly (its ASK-side role is `origin:
  *    "denial_limit_fallback"`).
- *  - `plan_mode` — plan mode's read-only block on a write tool.
+ *  - `persisted_rule` — the person's persisted-rule lane refused: a deny row (live), or, on a durable resume, a deny
+ *    row, a call unreadable against the rows, or a wait for them the task's cancel ended.
  *  - `compliance` — the compliance call-time lock.
  *  - `write_protection` — an approved edit was rewritten by the restriction chain onto a write-protected
  *    path that no approval covers.
@@ -206,15 +207,18 @@ export type NobodyJudgedTableCoversEveryKind = AssertAllKeysHandled<Exclude<Sett
  *  - `read_boundary` — the shell read station refused: a deny-listed read (refused on every seat, with no
  *    ask), a read the read-only shell face may not make, or a rewritten / re-established command whose reads
  *    no longer are what a person approved.
+ *  - `mode` — the permission MODE refused a surviving ask at the gate's arbitration point: `dontAsk` turns an
+ *    ask nobody is present to answer into a refusal, and `bypassPermissions` refuses a write whose protection
+ *    could not be judged. The disposition carries `mode`, `askClass` and `classes` beside the word.
  */
-export declare const DENIED_BY_VALUES: readonly ["policy", "hook", "org", "persisted_rule", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution", "read_boundary"];
+export declare const DENIED_BY_VALUES: readonly ["policy", "hook", "org", "persisted_rule", "classifier", "compliance", "write_protection", "ask_resolution", "read_boundary", "mode"];
 export type DeniedBy = (typeof DENIED_BY_VALUES)[number];
 /** Membership test for {@link DeniedBy}. */
 export declare function isDeniedBy(v: unknown): v is DeniedBy;
 /** Which layers may VETO an approval a person already gave (invariant I3: a `human_allowed` settlement
  *  beside a `denied` disposition names one of these). The approval-edit re-screen (hook), the policy, org
  *  and persisted-rule re-checks, and the write-protection re-judge run AFTER the person's yes; the
- *  classifier, plan mode and compliance run before any ask exists, and `ask_resolution` IS the
+ *  classifier and compliance run before any ask exists, and `ask_resolution` IS the
  *  settlement, not a veto of it. `persisted_rule` = a person's own standing DENY row (their settings'
  *  deny list, imported) — the personal-store sibling of `org`, and like it re-judged on an edited
  *  command. `read_boundary` vetoes too: the rewrite re-judge and the pre-spawn re-establishment run after
@@ -225,11 +229,11 @@ export declare const DENIED_BY_MAY_VETO: {
     readonly org: true;
     readonly persisted_rule: true;
     readonly classifier: false;
-    readonly plan_mode: false;
     readonly compliance: false;
     readonly write_protection: true;
     readonly ask_resolution: false;
     readonly read_boundary: true;
+    readonly mode: false;
 };
 /** Compile-time fence: `never` while every deny layer has a veto row. */
 export type VetoTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedBy, keyof typeof DENIED_BY_MAY_VETO>>;
@@ -259,11 +263,11 @@ export declare const DENIED_BY_MAY_CARRY_CAUSE: {
     readonly org: false;
     readonly persisted_rule: false;
     readonly classifier: true;
-    readonly plan_mode: false;
     readonly compliance: false;
     readonly write_protection: false;
     readonly ask_resolution: false;
     readonly read_boundary: false;
+    readonly mode: false;
 };
 /** Compile-time fence: `never` while every deny layer has a cause row. */
 export type CauseTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedBy, keyof typeof DENIED_BY_MAY_CARRY_CAUSE>>;
@@ -285,12 +289,37 @@ export type CauseTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedB
 export type GateDisposition = {
     kind: "allowed";
     classifier?: AutoModeClassifierRound;
+    released?: ModeRelease;
 } | {
     kind: "denied";
     deniedBy: DeniedBy;
     cause?: ClassifierDenyCause;
     classifier?: AutoModeClassifierRound;
+    mode?: ModeRefusal["mode"];
+    askClass?: AskClass;
+    classes?: readonly AskClass[];
 };
+/**
+ * A permission MODE released a surviving ask — the allowed disposition's account of the question it did not put
+ * to anyone: the mode, the disclosed class word (`askClass`, the first member of the folded set in `ASK_CLASSES`
+ * order — one of {@link RELEASABLE_ASK_CLASSES}), the whole set, and the origin / mandate words the card would
+ * have shown. `reason: "rule_unreadable"` marks a release over a rule the call could not be read against.
+ */
+export interface ModeRelease {
+    mode: PermissionMode;
+    askClass: AskClass;
+    classes: readonly AskClass[];
+    origin?: AskOrigin;
+    mandate?: PersistedRuleMandate;
+    reason?: "rule_unreadable";
+}
+/** The two modes that refuse on their own account (`deniedBy: "mode"`): `dontAsk` every non-authority ask,
+ *  `bypassPermissions` a write whose protection could not be judged. `plan` refuses nothing here — its questions ask. */
+export interface ModeRefusal {
+    mode: "bypassPermissions" | "dontAsk";
+    askClass: AskClass;
+    classes: readonly AskClass[];
+}
 /**
  * The WHOLE record of one tool-gate pass: the final disposition, plus — when this pass settled an ask —
  * the settlement it consumed and the ask's origin. Minted ONCE (the gate's exit; the decide lane for a
@@ -310,7 +339,11 @@ export type GateDisposition = {
  *  I6  `disposition.classifier` present ⇒ both model ids are non-empty strings, and a `fallback` on it
  *      names a `to` that IS `modelUsed` (the ladder landed where the record says) with a cause in
  *      {@link import("./auto-mode.js").AUTO_MODE_FALLBACK_CAUSES} — a record whose `to` and `modelUsed`
- *      disagree would let a reader answer "which model decided this call?" two ways.
+ *      disagree would let a reader answer "which model decided this call?" two ways;
+ *  I7  `disposition.released` present ⇒ `kind === "allowed"`, no settlement, `mode` is `bypassPermissions`,
+ *      `askClass` is a releasable class and every member of `classes` is an ask class — a mode releases nothing
+ *      a person answered and nothing the table calls immune;
+ *  I8  `deniedBy === "mode"` ⇔ `mode` present (`bypassPermissions` | `dontAsk`) with `askClass` and `classes`.
  * 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.

package/dist/core/gate-outcome.js

@@ -1,4 +1,4 @@
-import { isAskOrigin } from "./ask-origin.js";
+import { isAskClass, isAskOrigin, isPermissionMode, RELEASABLE_ASK_CLASSES } from "./ask-origin.js";
 import { isAutoModeFallbackCause } from "./auto-mode.js";
 export const SETTLEMENT_KINDS = [
     "human_allowed",
@@ -56,7 +56,7 @@ export const SETTLEMENT_NOBODY_JUDGED = {
     policy_refused: true,
     task_aborted: false,
 };
-export const DENIED_BY_VALUES = ["policy", "hook", "org", "persisted_rule", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution", "read_boundary"];
+export const DENIED_BY_VALUES = ["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) {
     return DENIED_BY_SET.has(v);
@@ -67,11 +67,11 @@ export const DENIED_BY_MAY_VETO = {
     org: true,
     persisted_rule: true,
     classifier: false,
-    plan_mode: false,
     compliance: false,
     write_protection: true,
     ask_resolution: false,
     read_boundary: true,
+    mode: false,
 };
 export const CLASSIFIER_DENY_CAUSES = ["unavailable", "parse_error"];
 const CLASSIFIER_DENY_CAUSE_SET = new Set(CLASSIFIER_DENY_CAUSES);
@@ -84,11 +84,11 @@ export const DENIED_BY_MAY_CARRY_CAUSE = {
     org: false,
     persisted_rule: false,
     classifier: true,
-    plan_mode: false,
     compliance: false,
     write_protection: false,
     ask_resolution: false,
     read_boundary: false,
+    mode: false,
 };
 export function screenGateOutcome(g) {
     const defects = [];
@@ -116,6 +116,28 @@ export function screenGateOutcome(g) {
         else if (isDeniedBy(d.deniedBy) && !DENIED_BY_MAY_CARRY_CAUSE[d.deniedBy])
             defects.push(`I5: a classifier cause cannot stand beside deniedBy "${d.deniedBy}"`);
     }
+    if (d.kind === "allowed" && d.released !== undefined) {
+        const r = d.released;
+        if (s !== undefined)
+            defects.push("I7: a mode release carries no settlement — nobody answered the ask it released");
+        if (r.mode !== "bypassPermissions")
+            defects.push(`I7: a mode release names mode "${String(r.mode)}" — only bypassPermissions releases`);
+        if (!isAskClass(r.askClass) || !RELEASABLE_ASK_CLASSES.includes(r.askClass))
+            defects.push(`I7: released.askClass "${String(r.askClass)}" is not a releasable class`);
+        if (!Array.isArray(r.classes) || r.classes.length === 0 || !r.classes.every((c) => isAskClass(c)))
+            defects.push("I7: released.classes must be a non-empty list of ask classes");
+        if (r.origin !== undefined && !isAskOrigin(r.origin))
+            defects.push(`I7: released.origin "${String(r.origin)}" is outside the closed set`);
+    }
+    if (d.kind === "denied") {
+        const modeRefusal = d.deniedBy === "mode";
+        if (modeRefusal !== (d.mode !== undefined))
+            defects.push("I8: deniedBy mode and disposition.mode must be present together");
+        if (modeRefusal && (!isPermissionMode(d.mode) || (d.mode !== "bypassPermissions" && d.mode !== "dontAsk")))
+            defects.push(`I8: a mode refusal names mode "${String(d.mode)}" — only bypassPermissions, dontAsk and plan refuse`);
+        if (modeRefusal && (!isAskClass(d.askClass) || !Array.isArray(d.classes) || d.classes.length === 0 || !d.classes.every((c) => isAskClass(c))))
+            defects.push("I8: a mode refusal carries askClass and a non-empty classes list");
+    }
     const attribution = d.classifier;
     if (attribution !== undefined) {
         const named = (v) => typeof v === "string" && v !== "";

package/dist/core/governance-codes.d.ts

@@ -12,7 +12,6 @@ export declare const GOVERNANCE_CODES: {
     readonly "config.compliance_required": "transient";
     readonly "config.compliance_denied": "terminal";
     readonly "config.locked_key": "terminal";
-    readonly "config.tool_mount_denied": "terminal";
     readonly "memory.capture_optout_denied": "terminal";
 };
 export type GovernanceCode = keyof typeof GOVERNANCE_CODES;
@@ -42,6 +41,23 @@ export declare const NON_GOVERNANCE_MEMORY_CODES: ReadonlySet<string>;
  * `undefined` (NOT governance — the caller falls through to its ordinary taxonomy).
  */
 export declare function governanceRetryClass(code: string): GovernanceRetryClass | undefined;
+/**
+ * The CLOSED set of codes the `spec.tools` DECLARATION door refuses a caller's tool entry with, at prepare,
+ * before anything mounts: the entry cannot be built from its own members (`config.tool_mount_denied`), a
+ * member over a roster row's wire bound (`config.tool_roster_bound` / `config.tool_name_too_long` /
+ * `config.tool_contract_too_long`), a schema over the row's key bounds (`config.tool_schema_bound`), a
+ * declared face or result card the schema / namespace cannot carry (`config.tool_face_invalid`), a name or
+ * alias in the engine's protocol namespace (`config.tool_name_invalid`), an egress tool declared other than
+ * `write` (`config.egress_requires_write_effect` — also minted, same meaning, for a protocol tool's resolved
+ * axes), a name the run reserves for a tool the engine injects (`config.reserved_tool_name` — structured output,
+ * the skill tool, tool search, the offload reader, an injected protocol tool; `runGoal`'s completion tool, which
+ * refuses before any run). Each ends the run `failed` with the code on `terminal.code`. A caller-shape refusal, not a policy
+ * verdict: none of these is a governance code ({@link GOVERNANCE_CODES}); re-issuing the same declaration
+ * changes nothing. Every mint site at the door types its code against this set.
+ */
+export declare const TOOL_DECLARATION_CODES: readonly ["config.tool_mount_denied", "config.tool_roster_bound", "config.tool_name_too_long", "config.tool_contract_too_long", "config.tool_schema_bound", "config.tool_face_invalid", "config.tool_name_invalid", "config.egress_requires_write_effect", "config.reserved_tool_name"];
+/** A code in {@link TOOL_DECLARATION_CODES}. */
+export type ToolDeclarationCode = (typeof TOOL_DECLARATION_CODES)[number];
 /**
  * The CLOSED registry of reasons a permission-rule sync round may refuse an inbound record or move a
  * local row into the quarantine area (design/182 §4.3/§5.2/§8.1). Same doctrine as
@@ -119,7 +135,7 @@ export type NoticeAudience = "user" | "operator";
  * the union's catalog ({@link EngineNotice.code}). The groups below say only which family a row joins,
  * so the catalog is not written a second time here and the two cannot drift.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "config.permission_mode_unavailable", "permission.ask_released_by_mode", "permission.read_deny_unapplied", "permission.rule_store_unavailable", "resume.legacy_mode_seed_migrated", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "classifier.unavailable", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed"];
 /** A code this engine mints (see {@link ENGINE_NOTICE_CODES}). NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */

package/dist/core/governance-codes.js

@@ -5,7 +5,6 @@ export const GOVERNANCE_CODES = {
     "config.compliance_required": "transient",
     "config.compliance_denied": "terminal",
     "config.locked_key": "terminal",
-    "config.tool_mount_denied": "terminal",
     "memory.capture_optout_denied": "terminal",
 };
 export const NON_GOVERNANCE_MEMORY_CODES = new Set([
@@ -93,6 +92,17 @@ export function governanceRetryClass(code) {
         return "terminal";
     return undefined;
 }
+export const TOOL_DECLARATION_CODES = [
+    "config.tool_mount_denied",
+    "config.tool_roster_bound",
+    "config.tool_name_too_long",
+    "config.tool_contract_too_long",
+    "config.tool_schema_bound",
+    "config.tool_face_invalid",
+    "config.tool_name_invalid",
+    "config.egress_requires_write_effect",
+    "config.reserved_tool_name",
+];
 export const RULE_SYNC_DROP_CODES = {
     invalid_rule_text: "inbound-refused-or-local-quarantined",
     metadata_mismatch: "inbound-refused-or-local-quarantined",
@@ -128,6 +138,11 @@ export const ENGINE_NOTICE_CODES = [
     "config.peer_admission_out_of_range",
     "config.peer_lane_unmounted",
     "config.secret_env_scrubbed",
+    "config.permission_mode_unavailable",
+    "permission.ask_released_by_mode",
+    "permission.read_deny_unapplied",
+    "permission.rule_store_unavailable",
+    "resume.legacy_mode_seed_migrated",
     "peer.inbound_disposition",
     "peer.held_settled",
     "peer.idle_subscription",
@@ -135,6 +150,7 @@ export const ENGINE_NOTICE_CODES = [
     "classifier.fallback",
     "classifier.role_defaulted",
     "classifier.contract_broken",
+    "classifier.unavailable",
     "checkpoint.execution_outcome_unrecorded",
     "delegation.transcript_integrity",
     "delegation.ask_unresolvable",
@@ -187,6 +203,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "task.user_steer_undrained": "user",
     "task.user_followup_undrained": "user",
     "classifier.denial_limit": "user",
+    "classifier.unavailable": "user",
     "classifier.fallback": "operator",
     "classifier.role_defaulted": "operator",
     "classifier.contract_broken": "operator",
@@ -198,11 +215,16 @@ const NOTICE_AUDIENCE_TABLE = {
     "approval.read_root_granted": "user",
     "approval.read_root_grant_rejected": "user",
     "config.durable_gate_unavailable": "user",
+    "config.permission_mode_unavailable": "user",
+    "permission.ask_released_by_mode": "user",
+    "permission.read_deny_unapplied": "user",
+    "permission.rule_store_unavailable": "user",
     "memory.capture_opted_out": "user",
     "memory.capture_optout_unpersisted": "user",
     "memory.consolidation_withheld": "operator",
     "delegation.ask_unresolvable": "user",
     "config.autocompact_window_clamped": "operator",
+    "resume.legacy_mode_seed_migrated": "operator",
     "config.env_timeout_discarded": "operator",
     "config.materialize_env_discarded": "operator",
     "config.models_swapped": "operator",