@sema-agent/client-core 0.93.0 → 0.94.0

package/dist/generated/engineNoticeTables.js

@@ -28,6 +28,7 @@ export const CORE_ENGINE_NOTICE_CODES = Object.freeze([
     "permission.ask_released_by_mode",
     "permission.read_deny_unapplied",
     "permission.rule_store_unavailable",
+    "permission.rule_row_dropped",
     "permission.allowed_tool_not_granted",
     "peer.inbound_disposition",
     "peer.held_settled",
@@ -116,6 +117,7 @@ export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "permission.ask_released_by_mode": "user",
     "permission.read_deny_unapplied": "user",
     "permission.rule_store_unavailable": "user",
+    "permission.rule_row_dropped": "user",
     "permission.allowed_tool_not_granted": "user",
     "peer.inbound_disposition": "user",
     "peer.held_settled": "user",
@@ -210,6 +212,7 @@ export const CORE_NOTICE_MINTER = Object.freeze({
     "permission.ask_released_by_mode": "engine",
     "permission.read_deny_unapplied": "engine",
     "permission.rule_store_unavailable": "engine",
+    "permission.rule_row_dropped": "engine",
     "permission.allowed_tool_not_granted": "engine",
     "peer.inbound_disposition": "engine",
     "peer.held_settled": "engine",
@@ -278,3 +281,7 @@ export const CORE_TOOL_TURN_INCOMPLETE_CAUSES = Object.freeze([
     "bad_frame",
     "missing_result_synthesized",
 ]);
+export const CORE_USER_INPUT_UNDRAINED_FAMILIES = Object.freeze({
+    "steer": Object.freeze({ code: "task.user_steer_undrained", countKey: "steer" }),
+    "followUp": Object.freeze({ code: "task.user_followup_undrained", countKey: "followUp" }),
+});

package/dist/generated/sdkFactTables.d.ts

@@ -0,0 +1,3 @@
+export declare const SDK_ABORT_CAUSES: readonly ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb"];
+export declare const SDK_STATUS_DERIVED_COARSE_CODES: readonly ["request.rejected", "auth.unauthorized", "auth.forbidden", "not_found.resource", "request.payload_too_large", "request.unprocessable", "limit.rate_exceeded", "capability.unavailable", "internal.error"];
+export declare const SDK_DENY_REASON_ROUTING_FAILURE: "routing_failure_fail_closed";

package/dist/generated/sdkFactTables.js

@@ -0,0 +1,17 @@
+export const SDK_ABORT_CAUSES = Object.freeze([
+    "client_disconnected",
+    "ask_park_grace_exhausted",
+    "cancel_verb",
+]);
+export const SDK_STATUS_DERIVED_COARSE_CODES = Object.freeze([
+    "request.rejected",
+    "auth.unauthorized",
+    "auth.forbidden",
+    "not_found.resource",
+    "request.payload_too_large",
+    "request.unprocessable",
+    "limit.rate_exceeded",
+    "capability.unavailable",
+    "internal.error",
+]);
+export const SDK_DENY_REASON_ROUTING_FAILURE = "routing_failure_fail_closed";

package/dist/generated/settingsSchemaTables.d.ts

@@ -1,5 +1,8 @@
 export declare const SETTINGS_ENGINE_OWNED_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreCompact", "PostCompact", "Stop", "StopFailure", "UserPromptSubmit"];
 export declare const SETTINGS_SECRET_LITERAL_RE: RegExp;
+export declare const SETTINGS_PRIVATE_KEY_PEM_HEADER: RegExp;
+export declare const SETTINGS_DEVICE_CODE_TTL_SECONDS = 900;
+export declare const SETTINGS_DEVICE_POLL_INTERVAL_SECONDS = 5;
 export declare const SETTINGS_TIER_GROUP_NAME_RE: RegExp;
 export declare const SETTINGS_BUDGET_NUMBER_KEYS: readonly ["maxBudgetUsd", "tpmLimit", "rpmLimit", "maxParallelRequests", "maxRunCostUsd", "maxIterations"];
 export declare const SETTINGS_BUDGET_STRING_KEYS: readonly ["mode", "budgetDuration", "enforcement"];

package/dist/generated/settingsSchemaTables.js

@@ -10,6 +10,9 @@ export const SETTINGS_ENGINE_OWNED_HOOK_EVENTS = Object.freeze([
     "UserPromptSubmit",
 ]);
 export const SETTINGS_SECRET_LITERAL_RE = Object.freeze(/^(sk-|gh[opus]_|github_pat_|xox[baprse]-|xapp-|bearer\s|basic\s|eyJ[A-Za-z0-9_-]{10,}\.|AKIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|-----BEGIN[A-Z0-9 ]*PRIVATE KEY)/i);
+export const SETTINGS_PRIVATE_KEY_PEM_HEADER = Object.freeze(/-----BEGIN[A-Z0-9 ]*PRIVATE KEY/i);
+export const SETTINGS_DEVICE_CODE_TTL_SECONDS = 900;
+export const SETTINGS_DEVICE_POLL_INTERVAL_SECONDS = 5;
 export const SETTINGS_TIER_GROUP_NAME_RE = Object.freeze(/^[a-z0-9][a-z0-9._-]*$/i);
 export const SETTINGS_BUDGET_NUMBER_KEYS = Object.freeze([
     "maxBudgetUsd",

package/dist/headlessPermissionModeWire.d.ts

@@ -3,10 +3,10 @@ import { type PermissionModesReading } from './permissionModesCapability.js';
 import { type EnvLike } from './hostEnv.js';
 export declare const HEADLESS_PERMISSION_MODE_ENV = "SEMA_HEADLESS_PERMISSION_MODE";
 export declare const HEADLESS_PERMISSION_WIRE_MODES: readonly PermissionMode[];
-export declare function normalizeShellPermissionModeForWire(mode: string | undefined, permissionModes?: PermissionModesReading): string | undefined;
+export declare function normalizeShellPermissionModeForWire(mode: string | undefined, _permissionModes?: PermissionModesReading): string | undefined;
 export type HeadlessPermissionResolution = {
     fields: PermissionModeField;
-    source: 'flag' | 'env' | 'default' | 'absent';
+    source: 'flag' | 'env' | 'default';
     warning?: string;
 };
 export declare function permissionModeFromArgv(argv: readonly string[]): string | undefined;

package/dist/headlessPermissionModeWire.js

@@ -6,15 +6,10 @@ import { PERMISSION_MODE_WORDS } from './taskRequestWords.js';
 import { readOwnDataValue } from './ownKey.js';
 export const HEADLESS_PERMISSION_MODE_ENV = 'SEMA_HEADLESS_PERMISSION_MODE';
 export const HEADLESS_PERMISSION_WIRE_MODES = [...PERMISSION_MODE_WORDS];
-const SHELL_INTERNAL_MODE_TO_WIRE = new Map([
-    ['manual', 'default'],
-    ['dontAsk', 'default'],
-]);
-export function normalizeShellPermissionModeForWire(mode, permissionModes) {
+const SHELL_INTERNAL_MODE_TO_WIRE = new Map([['manual', 'default']]);
+export function normalizeShellPermissionModeForWire(mode, _permissionModes) {
     if (mode === undefined)
         return undefined;
-    if (mode === 'dontAsk' && permissionModeAdmitted(permissionModes, mode))
-        return mode;
     return SHELL_INTERNAL_MODE_TO_WIRE.get(mode) ?? mode;
 }
 export function permissionModeFromArgv(argv) {
@@ -35,8 +30,9 @@ export function resolveHeadlessPermissionMode(argv, env = hostEnv(), permissionM
     const flagMode = permissionModeFromArgv(argv);
     if (flagMode !== undefined) {
         const snap = flagMode === 'dontAsk' ? dontAskSnapshot(permissionModes) : undefined;
-        const normalized = normalizeShellPermissionModeForWire(flagMode, snap);
-        return { fields: permissionModeField(normalized, { stampDefault: true, permissionModes: snap }), source: 'flag' };
+        const normalized = normalizeShellPermissionModeForWire(flagMode);
+        const projected = permissionModeField(normalized, { stampDefault: true, permissionModes: snap });
+        return { fields: projected.permissionMode !== undefined ? projected : permissionModeField('default', { stampDefault: true }), source: 'flag' };
     }
     const raw = env[HEADLESS_PERMISSION_MODE_ENV]?.trim();
     if (raw === undefined || raw === '') {
@@ -44,21 +40,15 @@ export function resolveHeadlessPermissionMode(argv, env = hostEnv(), permissionM
     }
     if (HEADLESS_PERMISSION_WIRE_MODES.includes(raw)) {
         const snap = raw === 'dontAsk' ? dontAskSnapshot(permissionModes) : undefined;
-        if (raw === 'dontAsk' && snap === undefined) {
-            const downgraded = {
-                fields: permissionModeField('default', { stampDefault: true }),
-                source: 'env',
-            };
-            if (!warnedInvalidEnv) {
-                warnedInvalidEnv = true;
-                downgraded.warning = `sema: ${HEADLESS_PERMISSION_MODE_ENV}="dontAsk" is only sent once this client knows the engine accepts that mode, and ${dontAskWithheldClause(permissionModes)} — this run uses "default"`;
-            }
-            return downgraded;
-        }
-        return {
+        const resolution = {
             fields: permissionModeField(raw, { stampDefault: true, permissionModes: snap }),
             source: 'env',
         };
+        if (raw === 'dontAsk' && resolution.fields.permissionMode !== 'dontAsk' && !warnedInvalidEnv) {
+            warnedInvalidEnv = true;
+            resolution.warning = `sema: ${HEADLESS_PERMISSION_MODE_ENV}="dontAsk" is only sent once this client knows the engine accepts that mode, and ${dontAskWithheldClause(permissionModes)} — this run uses "default"`;
+        }
+        return resolution;
     }
     const resolution = {
         fields: permissionModeField('default', { stampDefault: true }),

package/dist/hitl/approvalHolds.d.ts

@@ -0,0 +1,36 @@
+import type { FsApprovalOutcome, ToolApprovalFrameOutcome } from './toolApprovalWire.js';
+export interface DurableDecisionHold {
+    readonly lane: 'durable';
+    readonly outcome: Promise<FsApprovalOutcome>;
+    presented: boolean;
+    readonly interrupt: () => void;
+    readonly cardSignal: AbortSignal;
+    trailing?: Promise<unknown>;
+}
+export interface LiveCardHold {
+    readonly lane: 'live';
+    readonly outcome: Promise<ToolApprovalFrameOutcome>;
+    phase: 'card' | 'respond';
+    superseded?: {
+        readonly parked: boolean;
+    };
+    readonly cardSignal: AbortSignal;
+    readonly interrupt: () => void;
+    trailing?: Promise<void>;
+}
+export type ApprovalHold = DurableDecisionHold | LiveCardHold;
+export interface ApprovalDecisionHoldTable {
+    readonly inFlight: Map<string, ApprovalHold>;
+    readonly settled: Map<string, DurableSettledHold>;
+    readonly openReads: Set<number>;
+    clock: number;
+}
+export interface DurableSettledHold {
+    readonly at: number;
+    readonly hold: DurableDecisionHold;
+}
+export declare const approvalDecisionHolds: ApprovalDecisionHoldTable;
+export declare function liveCardHoldOf(key: string): LiveCardHold | undefined;
+export declare function holdLiveCard(key: string, callerSignal: AbortSignal | undefined, present: (hold: LiveCardHold) => Promise<ToolApprovalFrameOutcome>): Promise<ToolApprovalFrameOutcome>;
+export declare function joinLiveCard(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ToolApprovalFrameOutcome>;
+export declare function supersedeLiveCard(key: string, parked: boolean): boolean;

package/dist/hitl/approvalHolds.js

@@ -0,0 +1,89 @@
+import { hostLog } from '../host.js';
+export const approvalDecisionHolds = { inFlight: new Map(), settled: new Map(), openReads: new Set(), clock: 0 };
+export function liveCardHoldOf(key) {
+    const h = approvalDecisionHolds.inFlight.get(key);
+    return h !== undefined && h.lane === 'live' ? h : undefined;
+}
+export function holdLiveCard(key, callerSignal, present) {
+    const h = approvalDecisionHolds;
+    const cut = new AbortController();
+    let settled = false;
+    const interrupt = () => {
+        if (!settled && !cut.signal.aborted)
+            cut.abort();
+    };
+    const unsubscribe = followCallerSignal(callerSignal, interrupt);
+    let resolveOutcome = () => { };
+    let rejectOutcome = () => { };
+    const outcome = new Promise((resolve, reject) => {
+        resolveOutcome = resolve;
+        rejectOutcome = reject;
+    });
+    const hold = { lane: 'live', outcome, phase: 'card', cardSignal: cut.signal, interrupt };
+    h.inFlight.set(key, hold);
+    const release = () => {
+        if (h.inFlight.get(key) === hold)
+            h.inFlight.delete(key);
+    };
+    const settle = (give) => {
+        settled = true;
+        unsubscribe();
+        const trailing = hold.trailing;
+        if (trailing === undefined) {
+            release();
+            give();
+            return;
+        }
+        give();
+        trailing.then(release, release);
+    };
+    let run;
+    try {
+        run = present(hold);
+    }
+    catch (e) {
+        run = Promise.reject(e);
+    }
+    run.then((o) => settle(() => resolveOutcome(o)), (e) => settle(() => rejectOutcome(e)));
+    return outcome;
+}
+export async function joinLiveCard(hold, signal) {
+    const unsubscribe = followCallerSignal(signal, hold.interrupt);
+    try {
+        const o = await hold.outcome;
+        return { ...o, joinedInFlight: true };
+    }
+    finally {
+        unsubscribe();
+    }
+}
+function followCallerSignal(signal, onAbort) {
+    if (signal === undefined || signal === null)
+        return () => { };
+    try {
+        if (signal.aborted === true) {
+            onAbort();
+            return () => { };
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+    }
+    catch {
+        return () => { };
+    }
+    return () => {
+        try {
+            signal.removeEventListener('abort', onAbort);
+        }
+        catch (e) {
+            hostLog('debug', `approvalHolds: could not detach from the caller's abort signal (${String(e).slice(0, 120)}) — the listener is one-shot and inert after settle`);
+        }
+    };
+}
+export function supersedeLiveCard(key, parked) {
+    const hold = liveCardHoldOf(key);
+    if (hold === undefined || hold.phase !== 'card' || hold.superseded !== undefined)
+        return false;
+    hold.superseded = Object.freeze({ parked });
+    hold.interrupt();
+    return true;
+}

package/dist/hitl/approvalOutcomeNote.js

@@ -17,7 +17,8 @@ function detailOf(r) {
 }
 export function approvalOutcomeNoteOf(frame, outcome) {
     const r = approvalResolutionOf(outcome);
-    const retracted = approvalNotSentCause(r) === 'retracted';
+    const cause = approvalNotSentCause(r);
+    const retracted = cause === 'retracted';
     const detail = detailOf(r);
     return {
         approvalId: frame.approvalId,

package/dist/hitl/approvalResolution.d.ts

@@ -1,9 +1,9 @@
 import type { DecideReceiptView } from '../decideReceipt.js';
 import type { HitlSafetyCode } from './hitlBridge.js';
-import type { FsApprovalOutcome, ToolApprovalFrameOutcome, ToolApprovalRespondAckView, ToolApprovalRespondDecision } from './toolApprovalWire.js';
+import type { FsApprovalOutcome, ToolApprovalFrameOutcome, ToolApprovalRespondAckView, ToolApprovalRespondDecision, ToolApprovalRespondParkingView } from './toolApprovalWire.js';
 export declare const APPROVAL_NOT_SENT_CAUSES: readonly ["retracted", "edit_refused", "no_pending", "fetch_failed", "no_input", "card_unavailable"];
 export type ApprovalNotSentCause = (typeof APPROVAL_NOT_SENT_CAUSES)[number];
-export declare const APPROVAL_UNSETTLED_CAUSES: readonly ["engine_refused", "decide_failed", "transport_exhausted", "safety_stop", "respond_failed", "interrupted", "orchestration", "unreadable"];
+export declare const APPROVAL_UNSETTLED_CAUSES: readonly ["engine_refused", "decide_failed", "transport_exhausted", "safety_stop", "respond_failed", "parking_in_progress", "interrupted", "orchestration", "unreadable"];
 export type ApprovalUnsettledCause = (typeof APPROVAL_UNSETTLED_CAUSES)[number];
 export interface ApprovalResolutionDecided {
     kind: 'decided';
@@ -26,6 +26,7 @@ export interface ApprovalResolutionUnsettled {
     errorCode?: string;
     status?: number;
     detail?: string;
+    parking?: ToolApprovalRespondParkingView;
 }
 export type ApprovalResolution = ApprovalResolutionDecided | ApprovalResolutionNotSent | ApprovalResolutionUnsettled;
 export type ApprovalLegOutcome = FsApprovalOutcome | ToolApprovalFrameOutcome;

package/dist/hitl/approvalResolution.js

@@ -12,6 +12,7 @@ export const APPROVAL_UNSETTLED_CAUSES = Object.freeze([
     'transport_exhausted',
     'safety_stop',
     'respond_failed',
+    'parking_in_progress',
     'interrupted',
     'orchestration',
     'unreadable',
@@ -98,11 +99,31 @@ function fsLegResolution(outcome, kind) {
         return { kind: 'unsettled', cause: 'orchestration', ...call, ...detail };
     return { kind: 'unsettled', cause: 'unreadable', ...call, ...detail };
 }
+function parkingViewOf(v) {
+    const approvalId = str(pick(v, 'approvalId'));
+    if (approvalId === undefined)
+        return undefined;
+    const hint = pick(v, 'retryAfterMs');
+    const retryAfterMs = typeof hint === 'number' && Number.isFinite(hint) && hint >= 0 ? hint : undefined;
+    const decidePath = str(pick(v, 'decidePath'));
+    const message = str(pick(v, 'message'));
+    return {
+        approvalId,
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(decidePath !== undefined ? { decidePath } : {}),
+        ...(message !== undefined ? { message } : {}),
+    };
+}
 function frameLegResolution(outcome) {
     if (pick(outcome, 'retracted') === true)
         return { kind: 'not_sent', cause: 'retracted' };
     if (pick(outcome, 'editRefused') === true)
         return { kind: 'not_sent', cause: 'edit_refused' };
+    if (pick(outcome, 'aborted') === true)
+        return { kind: 'unsettled', cause: 'interrupted' };
+    const parking = parkingViewOf(pick(outcome, 'parking'));
+    if (parking !== undefined)
+        return { kind: 'unsettled', cause: 'parking_in_progress', parking };
     if (pick(outcome, 'decision') === 'unresolved') {
         const refusal = pick(outcome, 'respondRefusal');
         return {

package/dist/hitl/approvalsFeed.js

@@ -1,6 +1,7 @@
 import { hostLog } from '../host.js';
 import { unrefTimer } from '../unrefTimer.js';
 import { readLivePendingRows } from './livePendingAsk.js';
+import { isInStreamDrainingEnd } from '../wireErrorTriage.js';
 const MAX_CONSECUTIVE_POLL_ESCAPES = 5;
 function readDurablePendingRows(raw) {
     if (!Array.isArray(raw))
@@ -415,6 +416,10 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
                     stats.heartbeats++;
                     continue;
                 }
+                if (isInStreamDrainingEnd(ev)) {
+                    hostLog('debug', 'approvalsFeed: push leg received the drain end frame — the engine is going down; the stream reconnects and re-syncs on its own');
+                    continue;
+                }
                 stats.pushEvents++;
                 await take('push');
             }

package/dist/hitl/askGateWire.js

@@ -27,6 +27,9 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
     while (true) {
         let park = null;
         for await (const ev of stream) {
+            const answering = led.answeringLiveCards();
+            if (answering.length > 0)
+                await Promise.all(answering);
             led.noteSeq(ev);
             if (isHostProgressFrame(ev))
                 progressedSinceReattach = true;

package/dist/hitl/automaticAnswerVerdict.d.ts

@@ -1,5 +1,7 @@
 import { type CoreModeArbitrationRow } from '../generated/engineFactTables.js';
-export type AutomaticAnswerLane = 'mode_posture' | 'standing_rule';
+import { CORE_ASK_FACES } from '../generated/engineAskFaceTables.js';
+export type AutomaticAnswerLane = 'mode_posture' | 'standing_rule' | 'permission_request_hook';
+export type AutomaticAnswerAskFace = (typeof CORE_ASK_FACES)[number];
 export interface AutomaticAnswerFacts {
     readonly settingsAskRuleMatched?: boolean;
 }
@@ -17,5 +19,9 @@ export type AutomaticAnswerVerdict = {
     readonly kind: 'unknown';
     readonly why: AutomaticAnswerUnknownWhy;
 };
-export declare function foldModeArbitrationRow(classes: Iterable<string>): CoreModeArbitrationRow;
+export declare const MODE_ARBITRATION: Readonly<Record<"hook" | "write_protection" | "mode" | "rule_unreadable" | "write_protection_unresolved" | "content_question" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "org_rule" | "governance_unavailable" | "ask_rule" | "denial_limit_fallback" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", CoreModeArbitrationRow>>;
+export declare function foldModeArbitrationRow(classes: Iterable<string>, askFace?: AutomaticAnswerAskFace): CoreModeArbitrationRow;
 export declare function automaticAnswerVerdict(card: object | null | undefined, lane: AutomaticAnswerLane, facts?: AutomaticAnswerFacts | null): AutomaticAnswerVerdict;
+export declare function mandatedApprovalDetailOf(card: object | null | undefined): string;
+export type PermissionRequestHookScope = 'allow_or_deny' | 'deny_only' | 'skip';
+export declare function permissionRequestHookScope(verdict: AutomaticAnswerVerdict | null | undefined): PermissionRequestHookScope;

package/dist/hitl/automaticAnswerVerdict.js

@@ -1,8 +1,11 @@
 import { CORE_MODE_ARBITRATION, CORE_MODE_RELEASE_REASONS } from '../generated/engineFactTables.js';
+import { CORE_RELEASABLE_ASK_CLASSES_BY_FACE, CORE_SHELL_FACE_TOOL_NAMES } from '../generated/engineAskFaceTables.js';
+import { mandatedApprovalDetail } from '../gateVocabulary.js';
 import { readOwnNonEmptyString } from '../ownKey.js';
 import { readAskClassPairState } from './askClassPair.js';
 import { approvalAllowRuleShadowed } from './allowRuleShadow.js';
 import { approvalIsMandated, readApprovalMandate } from './toolApprovalWire.js';
+export const MODE_ARBITRATION = CORE_MODE_ARBITRATION;
 const TABLE = CORE_MODE_ARBITRATION;
 const ORIGIN_IMPLIES_CLASS = Object.freeze({
     content_question: 'content_question',
@@ -12,12 +15,26 @@ const ORIGIN_IMPLIES_CLASS = Object.freeze({
     ask_rule: 'ask_rule',
     denial_limit_fallback: 'denial_limit_fallback',
 });
-const MANDATE_WORD_IMPLIES_CLASS = Object.freeze({
-    operator_always: 'shell_floor',
-    write_protection_unresolved: 'write_protection_unresolved',
-});
+function mandateWordClass(word) {
+    if (word === 'operator_always')
+        return 'shell_floor';
+    return Object.hasOwn(TABLE, word) ? word : undefined;
+}
 const ORDINARY_ROW = CORE_MODE_ARBITRATION.ordinary;
-export function foldModeArbitrationRow(classes) {
+function bypassImmuneOn(c, face) {
+    const on = face !== undefined && Object.hasOwn(CORE_RELEASABLE_ASK_CLASSES_BY_FACE, face) ? face : 'other';
+    return !CORE_RELEASABLE_ASK_CLASSES_BY_FACE[on].includes(c);
+}
+function askFaceOfCard(card) {
+    try {
+        const d = Object.getOwnPropertyDescriptor(card, 'toolName');
+        return d !== undefined && 'value' in d && typeof d.value === 'string' && CORE_SHELL_FACE_TOOL_NAMES.includes(d.value) ? 'shell' : 'other';
+    }
+    catch {
+        return 'other';
+    }
+}
+export function foldModeArbitrationRow(classes, askFace) {
     let any = false;
     let bypassImmune = false;
     let classifierEligible = true;
@@ -29,7 +46,7 @@ export function foldModeArbitrationRow(classes) {
             continue;
         const row = TABLE[c];
         any = true;
-        bypassImmune ||= row.bypassImmune;
+        bypassImmune ||= bypassImmuneOn(c, askFace);
         classifierEligible &&= row.classifierEligible;
         sandboxAdmission &&= row.sandboxAdmission;
         ruleMayClear &&= row.ruleMayClear;
@@ -39,8 +56,12 @@ export function foldModeArbitrationRow(classes) {
         return ORDINARY_ROW;
     return Object.freeze({ bypassImmune, classifierEligible, sandboxAdmission, ruleMayClear, hookAskFloor });
 }
-function laneBlocks(lane, row) {
-    return lane === 'mode_posture' ? row.bypassImmune : !row.ruleMayClear;
+function rowBlocks(lane, row) {
+    return lane === 'mode_posture' ? row.bypassImmune : lane === 'standing_rule' ? !row.ruleMayClear : row.hookAskFloor;
+}
+function classBlocks(lane, c, face) {
+    const row = TABLE[c];
+    return lane === 'mode_posture' ? bypassImmuneOn(c, face) : lane === 'standing_rule' ? !row.ruleMayClear : row.hookAskFloor;
 }
 function mustAsk(road, extra) {
     return Object.freeze({ kind: 'must_ask', road, ...(extra?.askClass !== undefined ? { askClass: extra.askClass } : {}), ...(extra?.origin !== undefined ? { origin: extra.origin } : {}) });
@@ -75,34 +96,33 @@ function readHostAskRuleMatched(facts) {
     }
 }
 export function automaticAnswerVerdict(card, lane, facts) {
-    if (lane !== 'mode_posture' && lane !== 'standing_rule')
+    if (lane !== 'mode_posture' && lane !== 'standing_rule' && lane !== 'permission_request_hook')
         return UNKNOWN.lane_not_recognised;
     try {
         if (typeof card !== 'object' || card === null)
             return UNKNOWN.card_unreadable;
+        const face = lane === 'mode_posture' ? askFaceOfCard(card) : undefined;
         const origin = readOwnNonEmptyString(evidenceView(card, 'origin'), 'origin');
         if (origin !== undefined && Object.hasOwn(ORIGIN_IMPLIES_CLASS, origin)) {
             const cls = ORIGIN_IMPLIES_CLASS[origin];
-            if (laneBlocks(lane, TABLE[cls]))
+            if (classBlocks(lane, cls, face))
                 return mustAsk('origin', { origin, askClass: cls });
         }
-        if (lane === 'standing_rule' && evidenceView(card, 'requiresRealApproval').requiresRealApproval === true)
+        if (lane !== 'mode_posture' && evidenceView(card, 'requiresRealApproval').requiresRealApproval === true)
             return mustAsk('requires_real_approval');
         if (evidenceView(card, 'governanceForced').governanceForced === true)
             return mustAsk('governance');
         if (lane === 'mode_posture') {
             const word = readApprovalMandate(evidenceView(card, 'mandate'));
-            if (word !== undefined && Object.hasOwn(MANDATE_WORD_IMPLIES_CLASS, word)) {
-                const cls = MANDATE_WORD_IMPLIES_CLASS[word];
-                if (laneBlocks(lane, TABLE[cls]))
-                    return mustAsk('mandate_word', { askClass: cls });
-            }
+            const cls = word !== undefined ? mandateWordClass(word) : undefined;
+            if (cls !== undefined && classBlocks(lane, cls, face))
+                return mustAsk('mandate_word', { askClass: cls });
         }
         else {
             const mandateView = evidenceView(card, 'mandated', 'ruleOffersAbsence', 'mandate');
             if (approvalIsMandated(mandateView))
                 return mustAsk('mandated');
-            if (approvalAllowRuleShadowed(card) || readOwnNonEmptyString(mandateView, 'ruleOffersAbsence') === 'shadowed')
+            if (lane === 'standing_rule' && (approvalAllowRuleShadowed(card) || readOwnNonEmptyString(mandateView, 'ruleOffersAbsence') === 'shadowed'))
                 return mustAsk('allow_rule_shadow');
         }
         const pair = readAskClassPairState(card);
@@ -110,7 +130,7 @@ export function automaticAnswerVerdict(card, lane, facts) {
             return UNKNOWN.classes_malformed;
         if (pair.state === 'absent')
             return UNKNOWN.classes_absent;
-        const folded = foldModeArbitrationRow(pair.classes);
+        const folded = foldModeArbitrationRow(pair.classes, face);
         let anyKnown = false;
         let firstBlocking;
         let anyUnknown = false;
@@ -120,14 +140,14 @@ export function automaticAnswerVerdict(card, lane, facts) {
                 continue;
             }
             anyKnown = true;
-            if (firstBlocking === undefined && laneBlocks(lane, TABLE[c]))
+            if (firstBlocking === undefined && classBlocks(lane, c, face))
                 firstBlocking = c;
         }
-        if (anyKnown && laneBlocks(lane, folded))
+        if (anyKnown && rowBlocks(lane, folded))
             return mustAsk('ask_class', firstBlocking !== undefined ? { askClass: firstBlocking } : undefined);
         if (anyUnknown)
             return UNKNOWN.class_not_in_table;
-        if (lane === 'standing_rule')
+        if (lane !== 'mode_posture')
             return MAY_ANSWER;
         const matched = readHostAskRuleMatched(facts);
         if (matched === true)
@@ -141,3 +161,31 @@ export function automaticAnswerVerdict(card, lane, facts) {
         return UNKNOWN.card_unreadable;
     }
 }
+export function mandatedApprovalDetailOf(card) {
+    try {
+        if (typeof card !== 'object' || card === null)
+            return mandatedApprovalDetail();
+        const pair = readAskClassPairState(card);
+        if (pair.state !== 'pair')
+            return mandatedApprovalDetail();
+        if (pair.classes.some((c) => !Object.hasOwn(TABLE, c)))
+            return mandatedApprovalDetail();
+        const row = foldModeArbitrationRow(pair.classes);
+        if (row.classifierEligible || row.sandboxAdmission)
+            return mandatedApprovalDetail();
+        return MANDATED_NO_AUTOMATIC_CHECK_DETAIL;
+    }
+    catch {
+        return mandatedApprovalDetail();
+    }
+}
+const MANDATED_NO_AUTOMATIC_CHECK_DETAIL = 'no saved allow rule and no remembered answer can retire this question, and no automatic check answers it; each call is settled on its own, by you here, and an answer covers only that call';
+export function permissionRequestHookScope(verdict) {
+    try {
+        const kind = typeof verdict === 'object' && verdict !== null ? verdict.kind : undefined;
+        return kind === 'may_answer' ? 'allow_or_deny' : kind === 'must_ask' ? 'skip' : 'deny_only';
+    }
+    catch {
+        return 'deny_only';
+    }
+}

package/dist/hitl/decisionRefusal.d.ts

@@ -0,0 +1,19 @@
+export type DecisionRefusalStanding = 'settled-elsewhere' | 'ambiguous' | 'refused-pending';
+export interface DecisionRefusalClassified {
+    readonly standing: DecisionRefusalStanding;
+    readonly status: number;
+    readonly errorCode?: string;
+    readonly transient?: true;
+}
+export declare function classifyDecisionRefusal(err: unknown): DecisionRefusalClassified | undefined;
+export type LiveAskPendingReading = 'pending' | 'not_pending' | 'unknown';
+export declare function liveAskPendingReading(envelope: unknown, approvalId: string): LiveAskPendingReading;
+export declare function decisionRefusalClosesOut(refusal: DecisionRefusalClassified | undefined, pending: LiveAskPendingReading): boolean;
+export type UndeliverableDecisionEnd = 'run-stopped' | 'run-unconfirmed' | 'turn-stopped';
+export interface UndeliverableDecisionFacts {
+    readonly status: number;
+    readonly errorCode?: string;
+    readonly end: UndeliverableDecisionEnd;
+    readonly runId?: string;
+}
+export declare function undeliverableDecisionContent(facts: UndeliverableDecisionFacts): string;