@sema-agent/client-core 0.107.0 → 0.109.0

package/dist/hitl/persistedRulesWire.js

@@ -1,7 +1,7 @@
 import { displayUntrusted, quoteUntrustedForSentence } from '../displayUntrusted.js';
 import { engineCapTrue } from '../engineCapsCache.js';
 import { CORE_RULE_BEHAVIORS } from '../generated/engineFactTables.js';
-import { slotReadOf, wireFailureShapeOf } from '../wireFailureShape.js';
+import { inValueOf, slotReadOf, wireFailureShapeOf } from '../wireFailureShape.js';
 import { CAPABILITY_OPERATOR_PRINCIPALS_REQUIRED } from '../engineErrorCodes.js';
 import { hostLog } from '../host.js';
 import { msg, renderMessage } from '../i18n/translate.js';
@@ -43,17 +43,21 @@ function ownNonEmpty(o, key) {
     const r = slotReadOf(o, key);
     return r.presence === 'present' && typeof r.value === 'string' && r.value !== '' ? r.value : undefined;
 }
-function indeterminateRowOf(row) {
+function ruleKeyOfRow(row) {
     const k = slotReadOf(row, 'key');
     const keyObj = k.presence === 'present' && typeof k.value === 'object' && k.value !== null ? k.value : undefined;
     const behavior = keyObj === undefined ? undefined : ownNonEmpty(keyObj, 'behavior');
     const rule = keyObj === undefined ? undefined : ownNonEmpty(keyObj, 'rule');
     const scope = keyObj === undefined ? undefined : ownNonEmpty(keyObj, 'scope');
+    return behavior !== undefined && rule !== undefined && scope !== undefined ? Object.freeze({ behavior, rule, scope }) : undefined;
+}
+function unsettledRowOf(row) {
+    const key = ruleKeyOfRow(row);
     const reason = ownNonEmpty(row, 'reason');
     const d = slotReadOf(row, 'detail');
     const shown = d.presence === 'present' && typeof d.value === 'string' ? displayUntrusted(d.value, { max: INDETERMINATE_DETAIL_SHOWN_MAX }) : undefined;
     return Object.freeze({
-        ...(behavior !== undefined && rule !== undefined && scope !== undefined ? { key: Object.freeze({ behavior, rule, scope }) } : {}),
+        ...(key !== undefined ? { key } : {}),
         ...(reason !== undefined ? { reason } : {}),
         ...(shown !== undefined && shown.trim() !== '' ? { detail: shown } : {}),
     });
@@ -65,12 +69,15 @@ const RECEIPT_ROW_ARMS = {
     'no-op': (acc) => {
         acc.deduped += 1;
     },
+    refused: (acc, row) => {
+        appendOwnElement(acc.refused, unsettledRowOf(row));
+    },
     indeterminate: (acc, row) => {
-        appendOwnElement(acc.indeterminate, indeterminateRowOf(row));
+        appendOwnElement(acc.indeterminate, unsettledRowOf(row));
     },
 };
 function receiptCountsOf(rows) {
-    const acc = { persisted: 0, deduped: 0, indeterminate: [] };
+    const acc = { persisted: 0, deduped: 0, indeterminate: [], refused: [] };
     for (const row of rows) {
         if (typeof row !== 'object' || row === null)
             return null;
@@ -80,7 +87,12 @@ function receiptCountsOf(rows) {
             return null;
         RECEIPT_ROW_ARMS[word](acc, row);
     }
-    return { persisted: acc.persisted, deduped: acc.deduped, indeterminate: acc.indeterminate.length === 0 ? NO_INDETERMINATE : Object.freeze(acc.indeterminate) };
+    return {
+        persisted: acc.persisted,
+        deduped: acc.deduped,
+        indeterminate: acc.indeterminate.length === 0 ? NO_INDETERMINATE : Object.freeze(acc.indeterminate),
+        ...(acc.refused.length === 0 ? {} : { refused: Object.freeze(acc.refused) }),
+    };
 }
 function legacyEnvelopeCountsOf(result) {
     if (typeof result !== 'object' || result === null)
@@ -317,9 +329,14 @@ export function revokeTargetFromPersistedRule(rule, opts) {
     };
 }
 function readPrincipalOverride(carrier) {
-    if (carrier === null || typeof carrier !== 'object' || !('principal' in carrier))
+    if (carrier === null || typeof carrier !== 'object')
+        return { ok: true };
+    const slot = inValueOf(carrier, 'principal');
+    if (slot.state === 'absent')
         return { ok: true };
-    const raw = carrier.principal;
+    if (slot.state === 'unproven')
+        return { ok: false };
+    const raw = slot.value;
     if (typeof raw !== 'string' || raw.trim().length === 0)
         return { ok: false };
     return { ok: true, principal: raw };

package/dist/hitl/planReviewWire.js

@@ -1,5 +1,6 @@
 import { publishQuestionFrame, publishQuestionFrameFor, registerLocalQuestionResponder, unregisterLocalQuestionResponder, hasLocalQuestionResponder, hasQuestionOverlayFor, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
+import { invokeHostCallbackIsolated } from '../hostCallbackGuard.js';
 import { abortableSleep, settleWithinDeadline } from '../abortableSleep.js';
 import { clientHasVerbs, engineWireFor, noAnswerKindOf, sendOnce } from '../engineWireFor.js';
 import { engineWireTarget } from '../engineWireTarget.js';
@@ -1028,22 +1029,17 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
         hostLog('debug', `planReviewWire: outcome enqueue threw: ${String(e)}`);
     }
     if (onOutcome !== undefined) {
-        try {
-            onOutcome({
-                taskId,
-                dispatchNo,
-                decision: semanticDecision,
-                effect,
-                ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}),
-                detail: outcome,
-                tail,
-                prompt,
-                ...(statusSeen !== undefined ? { status: statusSeen } : {}),
-            });
-        }
-        catch (e) {
-            hostLog('debug', `planReviewWire: onOutcome callback threw for task ${taskId} (ignored): ${String(e)}`);
-        }
+        invokeHostCallbackIsolated(`planReviewWire: onOutcome callback (task ${taskId})`, () => onOutcome({
+            taskId,
+            dispatchNo,
+            decision: semanticDecision,
+            effect,
+            ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}),
+            detail: outcome,
+            tail,
+            prompt,
+            ...(statusSeen !== undefined ? { status: statusSeen } : {}),
+        }));
     }
 }
 function reopenIdSuffix() {

package/dist/hitl/policyDenyCause.d.ts

@@ -0,0 +1,3 @@
+export declare const POLICY_DENY_CAUSES: readonly ["no_approval_ui", "dont_ask", "deny_rule", "engine_floor"];
+export type PolicyDenyCause = (typeof POLICY_DENY_CAUSES)[number];
+export declare function readPolicyDenyCause(decision: object | null | undefined): PolicyDenyCause | undefined;

package/dist/hitl/policyDenyCause.js

@@ -0,0 +1,16 @@
+export const POLICY_DENY_CAUSES = Object.freeze(['no_approval_ui', 'dont_ask', 'deny_rule', 'engine_floor']);
+export function readPolicyDenyCause(decision) {
+    if (decision === null || typeof decision !== 'object')
+        return undefined;
+    let d;
+    try {
+        d = Object.getOwnPropertyDescriptor(decision, 'policyCause');
+    }
+    catch {
+        return undefined;
+    }
+    if (d === undefined || !Object.hasOwn(d, 'value'))
+        return undefined;
+    const v = d.value;
+    return typeof v === 'string' && POLICY_DENY_CAUSES.includes(v) ? v : undefined;
+}

package/dist/hitl/sessionAllowRoute.js

@@ -1,3 +1,4 @@
+import { inSlotReadOf } from '../wireFailureShape.js';
 export function sessionAllowCarried(leg, approvalId) {
     if (leg === 'frame')
         return true;
@@ -7,10 +8,10 @@ export function sessionAllowCarried(leg, approvalId) {
 }
 export function readCardUnreadableEvidence(card) {
     try {
-        if (!('unreadableEvidence' in card))
+        const slot = inSlotReadOf(card, 'unreadableEvidence');
+        if (slot.state === 'absent')
             return 'absent';
-        const d = Object.getOwnPropertyDescriptor(card, 'unreadableEvidence');
-        const list = d !== undefined && Object.hasOwn(d, 'value') ? d.value : undefined;
+        const list = slot.state === 'present' ? slot.value : undefined;
         return Array.isArray(list) && list.every((k) => typeof k === 'string') ? list : 'unreadable';
     }
     catch {
@@ -21,7 +22,7 @@ export function sessionAllowCardReadable(card) {
     if (typeof card !== 'object' || card === null)
         return 'card_unreadable';
     try {
-        if ('cardPayloadUnreadable' in card)
+        if (inSlotReadOf(card, 'cardPayloadUnreadable').state !== 'absent')
             return 'card_unreadable';
     }
     catch {

package/dist/hitl/sessionPolicyDeliverable.js

@@ -12,7 +12,7 @@ const WITHHELD_NOTICE = {
     qualified_deny: 'Not written to this session’s rule record: that record holds whole tool names and command names only, and this rule has a part in parentheses it cannot carry — recording just the name could block more than this rule does.',
     peer_wide: 'Not written to this session’s rule record: this rule names a server or agent peer without naming one of its tools, and an engine that matches that record by exact tool name would block none of that peer’s tools.',
     wildcard: 'Not written to this session’s rule record: this rule uses a wildcard (*), and an engine that matches that record by exact tool name would block none of the tools it covers.',
-    not_a_tool_name: 'Not written to this session’s rule record: this entry is not exactly one tool name — it is empty, not text, has spaces around the name, is not a single tool name in rule syntax (for example it contains a backslash or a parenthesis, or is longer than a rule can be), or spells its server or agent peer part in a way the engine never uses when naming tools (for example with a dot or a space), so no tool would ever match it.',
+    not_a_tool_name: 'Not written to this session’s rule record: this entry is not exactly one tool name — it is empty, not text, has spaces around the name, is not a single tool name in rule syntax (for example it contains a backslash or a parenthesis, or is longer than a rule can be), or spells its server or agent peer part in a form this record does not accept (for example with a dot or a space) · This record does not take entries of that form; record the exact name of a single tool instead.',
     legacy_tool_name: `Not written to this session’s rule record: unless a tool by exactly this name is available, the engine refuses it — it is a retired tool name, or it contains "__" but does not start with ${PREFIXES_IN_PROSE} — and with it in that record every later run of this session would fail at startup until that entry is removed from the record. ${REFUSED_NAME_FIX}`,
     not_in_roster: 'Not written to this session’s rule record: the tool roster supplied for this check has no tool this rule would block — no tool by exactly this name, as a name or an alias, with letter case counted, and, where the engine also reads the name as naming every tool of a server (a server whose own name contains "__"), no tool of that server either — it may be misspelled, or name a tool this deployment does not provide — so recorded as it is it would block nothing here.',
     namespace_covering_unconfirmed: msg('session.policy.withheld.namespaceCoveringUnconfirmed'),

package/dist/hitl/standingRows.d.ts

@@ -25,13 +25,9 @@ export interface RememberOfferable {
     readonly deploymentList: RememberOffer;
 }
 export declare function rememberOfferable(card: object | null | undefined, host?: StandingRowsHostFacts | null): RememberOfferable;
-export interface LocalAllowRuleHostFacts {
-    readonly hostLadderEnforces?: boolean;
-}
 export interface LocalAllowRuleEnforcement {
     readonly enforceable: boolean;
-    readonly by?: 'host_ladder' | 'engine_grant';
     readonly engine: 'sent' | 'kept' | 'unreadable';
     readonly keptReason?: PermissionsKeptReason;
 }
-export declare function localAllowRuleEnforceable(rule: string, caps: PermissionsAllowGrantReading, host?: LocalAllowRuleHostFacts | null): LocalAllowRuleEnforcement;
+export declare function localAllowRuleEnforceable(rule: string, caps: PermissionsAllowGrantReading): LocalAllowRuleEnforcement;

package/dist/hitl/standingRows.js

@@ -1,7 +1,8 @@
 import { DEPLOYMENT_LIST_ASK_CLASSES, readAskClassPairState } from './askClassPair.js';
-import { automaticAnswerVerdict } from './automaticAnswerVerdict.js';
+import { askLevelVerdict } from './automaticAnswerVerdict.js';
 import { readApprovalCardWord, readRuleOffers } from './toolApprovalWire.js';
 import { CORE_SKILL_TOOL_NAME } from '../generated/toolNameTables.js';
+import { inSlotReadOf, inValueOf } from '../wireFailureShape.js';
 import { toolPermissionRequestIdDomain } from '../seatContract.js';
 import { permissionsDeclarationReport } from '../permissionsDeclaration.js';
 import { readCardUnreadableEvidence, sessionAllowCardReadable, sessionAllowEligible } from './sessionAllowRoute.js';
@@ -15,9 +16,10 @@ function ownData(v, key) {
         return undefined;
     }
 }
-function hasKey(v, key) {
+function candidateSlot(v, key) {
     try {
-        return { inCard: key in v };
+        const s = inSlotReadOf(v, key);
+        return s.state === 'unproven' ? UNREADABLE : s;
     }
     catch {
         return UNREADABLE;
@@ -25,8 +27,10 @@ function hasKey(v, key) {
 }
 function present(v, key) {
     try {
-        const inCard = key in v;
-        return { inCard, value: inCard ? v[key] : undefined };
+        const s = inValueOf(v, key);
+        if (s.state === 'unproven')
+            return UNREADABLE;
+        return s.state === 'present' ? { inCard: true, value: s.value } : { inCard: false, value: undefined };
     }
     catch {
         return UNREADABLE;
@@ -42,12 +46,12 @@ function persistentRowOf(card, host, evidenceUnreadable) {
     if (evidenceUnreadable)
         return { row: 'none', why: 'evidence_unreadable' };
     for (const key of ['ruleOffers', 'ruleOffersReadOnly']) {
-        const p = hasKey(card, key);
+        const p = candidateSlot(card, key);
         if (p === UNREADABLE)
             return UNREADABLE;
-        if (!p.inCard)
+        if (p.state === 'absent')
             continue;
-        const offers = readRuleOffers(ownData(card, key));
+        const offers = readRuleOffers(p.state === 'present' ? p.value : undefined);
         if (offers === undefined || offers.length === 0)
             return { row: 'none', why: 'offers_unreadable' };
         return { row: 'engine_offer', why: 'given' };
@@ -69,7 +73,7 @@ function persistentRowOf(card, host, evidenceUnreadable) {
         return { row: 'none', why: 'tool_name_unreadable' };
     if (tool === CORE_SKILL_TOOL_NAME)
         return { row: 'none', why: 'grant_binding' };
-    if (automaticAnswerVerdict(card, 'standing_rule').kind !== 'may_answer')
+    if (askLevelVerdict(card, 'standing_rule').kind !== 'may_answer')
         return { row: 'none', why: 'rule_cannot_clear' };
     const face = readApprovalCardWord(card);
     if (face === undefined)
@@ -178,8 +182,7 @@ export function rememberOfferable(card, host) {
         deploymentList: SESSION_OFFER[rows.why.deploymentList],
     });
 }
-export function localAllowRuleEnforceable(rule, caps, host) {
-    const ladder = typeof host === 'object' && host !== null && ownData(host, 'hostLadderEnforces') === true;
+export function localAllowRuleEnforceable(rule, caps) {
     let engine = 'unreadable';
     let keptReason;
     if (typeof rule === 'string' && rule.trim() !== '') {
@@ -199,10 +202,8 @@ export function localAllowRuleEnforceable(rule, caps, host) {
             engine = 'unreadable';
         }
     }
-    const by = ladder ? 'host_ladder' : engine === 'sent' ? 'engine_grant' : undefined;
     return Object.freeze({
-        enforceable: by !== undefined,
-        ...(by !== undefined ? { by } : {}),
+        enforceable: engine === 'sent',
         engine,
         ...(keptReason !== undefined ? { keptReason } : {}),
     });

package/dist/hitl/toolApprovalWire.d.ts

@@ -1,4 +1,6 @@
 import { type HitlClientLike, type DecideOperationObserver } from './hitlBridge.js';
+import { type ApprovalAskReason } from './approvalAskers.js';
+export type { ApprovalAskReason, ApprovalAskReasonByHook, ApprovalAskReasonByPolicy } from './approvalAskers.js';
 import { readApprovalCardWord, type ApprovalCardWord } from './approvalCardReading.js';
 import { type ApprovalAllowRuleShadow } from './allowRuleShadow.js';
 import { CORE_PERSISTED_RULE_MATCHES } from '../generated/engineFactTables.js';
@@ -9,6 +11,8 @@ import { type ApprovalResolution } from './approvalResolution.js';
 import { type ApprovalMandateWord } from '../gateVocabulary.js';
 import type { ToolPermissionRequest } from '../seatContract.js';
 import { type ApprovalDecidedByReading } from '../approvalDecidedByCapability.js';
+import { type PolicyDenyCause } from './policyDenyCause.js';
+import { type ApprovalRequestFrameReading, type ApprovalRequestFrameUnreadableWhy } from './approvalRequestFrameReading.js';
 import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS } from '@sema-agent/sdk';
 import type { ApprovalDecidedBy, ApprovalCardDelegation, ToolApprovalDecision as SdkToolApprovalDecision, ToolApprovalRespondAck, ToolApprovalRespondReplayed, PersistedRuleAnchor, RuleOfferMatch, RuleOfferBatchMember, RuleOfferUncoveredDetail, RuleOfferUncoveredReason, AskOrigin, RuleOffersAbsence, DenialLimitKind, DenialLimitFallback, ToolApprovalFrame, ApprovalRequestFrame, RuleOffer as SdkRuleOffer } from '@sema-agent/sdk';
 export declare function toolNameIsFsWrite(name: string): boolean;
@@ -71,6 +75,7 @@ export interface ApprovalCardDenyDecision {
     kind: 'deny';
     reason?: string;
     settledBy?: ApprovalDenySettledBy;
+    policyCause?: PolicyDenyCause;
 }
 export declare const APPROVAL_DENY_SETTLED_BY_WORDS: readonly ["human", "policy"];
 export type ApprovalDenySettledBy = (typeof APPROVAL_DENY_SETTLED_BY_WORDS)[number];
@@ -125,6 +130,8 @@ export interface ApprovalCardRequest {
     approvalCard?: ApprovalCardWord;
     askClass?: string;
     classes?: readonly string[];
+    agentId?: string;
+    askReasons?: readonly ApprovalAskReason[];
     boundGrants?: BoundSkillGrantsWire;
     grantBinding?: ApprovalGrantBinding;
     unreadableEvidence?: readonly string[];
@@ -132,6 +139,7 @@ export interface ApprovalCardRequest {
     priorCardsForCall?: readonly ApprovalPriorCard[];
     message?: string;
     cardPayloadUnreadable?: true;
+    cardPayloadUnreadableWhy?: ApprovalRequestFrameUnreadableWhy;
     supersedes?: ApprovalCardSupersedes;
     parkRow?: ApprovalCardParkRow;
 }
@@ -163,7 +171,7 @@ export declare function approvalCardPortFor(sessionKey: string): ApprovalCardPor
 export declare function __resetSettledApprovalsForTests(): void;
 export declare function _resetApprovalCardPortForTest(): void;
 export declare function surfaceApprovalCard(req: ApprovalCardRequest): Promise<ApprovalCardDecision>;
-declare const REMEMBER_REFUSAL_CODES: readonly ["remember_not_in_proof", "capability.store_required", "decide.workflow_remember_unsupported", "decide.parked_remember_unsupported"];
+declare const REMEMBER_REFUSAL_CODES: readonly ["remember_not_in_proof", "capability.store_required", "decide.workflow_remember_unsupported", "decide.parked_remember_unsupported", "remember_requires_binding"];
 export type RememberRefusalCode = (typeof REMEMBER_REFUSAL_CODES)[number];
 export declare function rememberRefusalOf(error: unknown): RememberRefusalCode | undefined;
 export declare function surfaceFsApprovalAndDecide(deps: FsApprovalWireDeps, taskId: string, argsByCall: Map<string, unknown>, signal?: AbortSignal, parkGatedCallId?: string, parkToolName?: string): Promise<ApprovalResolution>;
@@ -276,8 +284,8 @@ export declare function approvalSupersedesDetail(card: Pick<ApprovalCardRequest,
 export declare function readDenialLimitFallback(v: unknown): DenialLimitFallback | undefined;
 export declare function readRuleOffers(v: unknown): RuleOfferReading[] | undefined;
 export declare function readRuleOfferSupply(offers: unknown): RuleOfferReading[] | undefined;
-export type ApprovalCardV1Facts = Pick<ApprovalCardRequest, 'toolName' | 'args'> & Pick<ApprovalCardRequest, 'toolCallId' | 'workerBadge' | 'wireNote' | 'argsUnavailable' | 'governanceForced' | 'delegation' | 'ruleOffersReadOnly' | 'inputHasBidi' | 'allowRuleShadow' | 'probeCause' | 'rememberRefused' | 'ruleEvidence' | 'requiresRealApproval' | 'ruleOffersAbsence' | 'denialLimitFallback' | 'askClass' | 'classes' | 'grantBinding' | 'unreadableEvidence' | 'message' | 'approvalCard'>;
-export type ApprovalCardFacts = ApprovalCardV1Facts & Pick<ApprovalCardRequest, 'argsRewritten' | 'ruleOffers' | 'probeReason' | 'mandated' | 'mandate' | 'readRootCandidate' | 'origin' | 'boundGrants' | 'classifierNoRuling' | 'allowSessionCarried' | 'cardPayloadUnreadable'>;
+export type ApprovalCardV1Facts = Pick<ApprovalCardRequest, 'toolName' | 'args'> & Pick<ApprovalCardRequest, 'toolCallId' | 'workerBadge' | 'wireNote' | 'argsUnavailable' | 'governanceForced' | 'delegation' | 'ruleOffersReadOnly' | 'inputHasBidi' | 'allowRuleShadow' | 'probeCause' | 'rememberRefused' | 'ruleEvidence' | 'requiresRealApproval' | 'ruleOffersAbsence' | 'denialLimitFallback' | 'askClass' | 'classes' | 'agentId' | 'askReasons' | 'grantBinding' | 'unreadableEvidence' | 'message' | 'approvalCard'>;
+export type ApprovalCardFacts = ApprovalCardV1Facts & Pick<ApprovalCardRequest, 'argsRewritten' | 'ruleOffers' | 'probeReason' | 'mandated' | 'mandate' | 'readRootCandidate' | 'origin' | 'boundGrants' | 'classifierNoRuling' | 'allowSessionCarried' | 'cardPayloadUnreadable' | 'cardPayloadUnreadableWhy'>;
 export interface ApprovalCardFrameFactsOptions {
     readonly streamArgs?: object;
     readonly argsUnavailable?: true;
@@ -285,7 +293,7 @@ export interface ApprovalCardFrameFactsOptions {
 export declare function approvalCardFactsOfV1(card: object | null | undefined): Readonly<ApprovalCardV1Facts> | undefined;
 export declare function approvalCardFactsOfV1Frame(frame: object | null | undefined): Readonly<ApprovalCardFacts> | undefined;
 export declare function approvalCardFactsOfFrame(frame: object | null | undefined, opts?: ApprovalCardFrameFactsOptions | null): Readonly<ApprovalCardFacts> | undefined;
-export declare function approvalCardFactsOfGeneric(card: object | null | undefined): Readonly<ApprovalCardFacts> | undefined;
+export declare function approvalCardFactsOfGeneric(card: object | null | undefined, reading?: ApprovalRequestFrameReading | null): Readonly<ApprovalCardFacts> | undefined;
 export interface ToolApprovalFrameLaneOpts {
     approvalDecisionNoteCapable?: boolean;
     respondFreeFormRulesCapable?: boolean;
@@ -298,6 +306,10 @@ export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFr
     readonly taskId?: string;
     readonly sessionId?: string;
 }): Promise<ApprovalResolution>;
+export declare function surfaceApprovalFrameWithId(frame: ToolApprovalFrame | ApprovalRequestFrame, approvalId: string, respond: RespondToolApprovalFn, streamArgs: Parameters<typeof surfaceToolApprovalFrameAndRespond>[2], signal: AbortSignal | undefined, lane: ToolApprovalFrameLaneOpts | undefined, run: {
+    readonly taskId?: string;
+    readonly sessionId?: string;
+} | undefined): Promise<ApprovalResolution>;
 export interface ApprovalHolderIdentity {
     readonly approvalId?: string;
     readonly taskId?: string;

package/dist/hitl/toolApprovalWire.js

@@ -7,6 +7,7 @@ import { trimEditedRuleText } from './editedRuleTextPrecheck.js';
 import { appendOwnElement, guardedRead, readAskOrigin, readOwnDataNonEmptyString, readOwnDataValue, readOwnNonEmptyString } from '../ownKey.js';
 import { ownReadingSlot } from '../engineWireFor.js';
 import { DEPLOYMENT_LIST_ASK_CLASSES, readAskClassPair } from './askClassPair.js';
+import { approvalAgentIdOf, approvalAskReasonsOf } from './approvalAskers.js';
 import { invokeHostCallbackIsolated } from '../hostCallbackGuard.js';
 import { approvalWindowKeysOf, readApprovalCardWord, readRequiresRealApproval } from './approvalCardReading.js';
 import { readAllowRuleShadowFromWire, retiredAllowRuleShadowKeyPresent, RETIRED_SHADOW_EVIDENCE_LABEL } from './allowRuleShadow.js';
@@ -28,13 +29,15 @@ import { parkRowDeadlineState } from './parkExpiryJudgements.js';
 import { isApprovalMandateWord } from '../gateVocabulary.js';
 import { approvalDecidedByAdmitted } from '../approvalDecidedByCapability.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { slotPresenceOf, wireFailureTextsOf } from '../wireFailureShape.js';
+import { readPolicyDenyCause } from './policyDenyCause.js';
+import { inValueOf, slotPresenceOf, wireFailureTextsOf } from '../wireFailureShape.js';
 import { APPROVAL_LIVE_FACE_KEYS, approvalLiveFaceOf, hasOwnStrictTrue } from './approvalLiveFace.js';
+import { approvalFrameUnreadableWhyOf, approvalRequestFrameReadingThrowing, } from './approvalRequestFrameReading.js';
 import { subagentSourceSessionOf } from './subagentSource.js';
 import { isPlainRecord } from '../jsonFaithful.js';
 import { DECIDE_WORKFLOW_REMEMBER_UNSUPPORTED } from '../engineErrorCodes.js';
 import { readDecideReceipt } from '../decideReceipt.js';
-import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS, ASK_ORIGINS, isApprovalRequestFrameV1, } from '@sema-agent/sdk';
+import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS, ASK_ORIGINS, } from '@sema-agent/sdk';
 export function toolNameIsFsWrite(name) {
     const n = name.replace(/[\s_-]+/g, '').toLowerCase();
     return (n === 'write' || n === 'filewrite' || n === 'edit' || n === 'fileedit' || n === 'multiedit' || n === 'notebookedit');
@@ -157,11 +160,13 @@ function cardPortMissReason() {
         return APPROVAL_CARD_PORT_KEY_MISMATCH_REASON;
     return NO_APPROVAL_CARD_PORT_REASON;
 }
+const LEGACY_REMEMBER_REFUSAL_CODE = 'remember_requires_binding';
 const REMEMBER_REFUSAL_CODES = Object.freeze([
     'remember_not_in_proof',
     'capability.store_required',
     DECIDE_WORKFLOW_REMEMBER_UNSUPPORTED,
     'decide.parked_remember_unsupported',
+    LEGACY_REMEMBER_REFUSAL_CODE,
 ]);
 export function rememberRefusalOf(error) {
     return rememberRefusalIn(readWireErrorCodeReading(error));
@@ -489,6 +494,7 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
     const rowArgsGap = reading.from !== 'none' ? undefined : reading.shape === 'absent' ? 'absent' : reading.shape === 'size_marker' ? 'truncated' : undefined;
     const args = reading.from !== 'none' ? reading.args : rowArgsGap !== undefined ? {} : reading.recorded;
     const argsRewritten = reading.from === 'recorded' && reading.rewritten;
+    const argsFromModelCall = reading.from === 'stream';
     if (typeof args !== 'object' || args === null) {
         return { kind: 'not_sent', ...at, cause: 'no_input', detail: 'gate has no tool input payload' };
     }
@@ -512,11 +518,13 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
             }
             : {}),
         ...(argsRewritten ? { argsRewritten: true, wireNote: ARGS_REWRITTEN_NOTE } : {}),
+        ...(argsFromModelCall ? { argsUnavailable: true, wireNote: renderMessage(msg('approval.park.argsFromModelCall')) } : {}),
         ...(pending.governanceForced === true ? { governanceForced: true } : {}),
         ...(readRequiresRealApproval(pending) ? { requiresRealApproval: true } : {}),
         ...approvalLiveFaceOf(pending).facts,
         ...((w) => (w !== undefined ? { approvalCard: w } : {}))(readApprovalCardWord(pending)),
         ...(readAskClassPair(pending) ?? {}),
+        ...((r) => (r !== undefined ? { askReasons: r } : {}))(approvalAskReasonsOf(pending)),
         ...(pending.gateKind === 'irreversible_ask' ? { irreversibleParkGate: true } : {}),
         ...(pending.hasBidiControls === true ? { hasBidiControls: true } : {}),
         ...(ruleOffersReadOnly !== undefined ? { ruleOffersReadOnly } : {}),
@@ -536,8 +544,8 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
     });
     const card = await surfaceCallTrackedCard(gatedCallId, undefined, ledgerSlot, cardRequest);
     hold.phase = 'respond';
-    if (rowArgsGap !== undefined && card.kind === 'allow' && card.updatedInput !== undefined) {
-        hostLog('error', `liveToolApprovalWire: approval card for ${gatedCallId ?? `task ${taskId}`} returned an edited approval, but the tool input is ${rowArgsGap === 'truncated' ? 'a size marker on the pending row' : 'missing from both the stream and the pending row'} — nothing sent (the park stays pending)`);
+    if ((rowArgsGap !== undefined || argsFromModelCall) && card.kind === 'allow' && card.updatedInput !== undefined) {
+        hostLog('error', `liveToolApprovalWire: approval card for ${gatedCallId ?? `task ${taskId}`} returned an edited approval, but the tool input is ${rowArgsGap === 'truncated' ? 'a size marker on the pending row' : rowArgsGap === 'absent' ? 'missing from both the stream and the pending row' : 'not recorded on the pending row'} — nothing sent (the park stays pending)`);
         surfaceEditRefusedOnBlindAsk();
         return { kind: 'not_sent', ...at, cause: 'edit_refused', detail: PARK_EDIT_REFUSED_REASON };
     }
@@ -609,6 +617,7 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
                 }
             case 'deny': {
                 const denySettledByForWire = readApprovalDenySettledBy(card);
+                const denyPolicyCauseForWire = readPolicyDenyCause(card);
                 const attributionKeys = decisionAttributionKeyOf(decidedByReading, denySettledByForWire);
                 const denyReasonSnapshot = ((r) => (typeof r === 'string' ? r : undefined))(card.reason);
                 let lastSendCarriedAttribution = false;
@@ -642,7 +651,7 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
                     const attributionDropped = ladder.dropped;
                     const attributionRenamed = ladder.renamed;
                     const receipt = readDecideReceipt(raw);
-                    const deny = denyFactsOf(denySettledByForWire, denyReasonSnapshot, attributionDropped, attributionRenamed);
+                    const deny = denyFactsOf(denySettledByForWire, denyReasonSnapshot, attributionDropped, attributionRenamed, denyPolicyCauseForWire);
                     return {
                         kind: 'decided',
                         ...at,
@@ -679,8 +688,11 @@ function readReadRootCandidate(v) {
     const o = v;
     if (typeof o.dir !== 'string' || o.dir.length === 0 || o.clearsThisAsk !== true)
         return undefined;
-    if ('covers' in o)
-        return o.covers === 'exact' ? { dir: o.dir, clearsThisAsk: true, covers: 'exact' } : undefined;
+    const covers = inValueOf(o, 'covers');
+    if (covers.state === 'unproven')
+        return undefined;
+    if (covers.state === 'present')
+        return covers.value === 'exact' ? { dir: o.dir, clearsThisAsk: true, covers: 'exact' } : undefined;
     return { dir: o.dir, clearsThisAsk: true };
 }
 export const TOOL_APPROVAL_FRAME_KEYS_MIRROR = [
@@ -1014,14 +1026,16 @@ function readDecidedByReadingOf(holder) {
 function decidedByReadingSnapshotOf(holder) {
     return approvalDecidedByAdmitted(readDecidedByReadingOf(holder)) ? Object.freeze({ kind: 'present', value: true }) : undefined;
 }
-function denyFactsOf(settledBy, reasonSnapshot, dropped, renamed) {
+function denyFactsOf(settledBy, reasonSnapshot, dropped, renamed, policyCauseSnapshot) {
     const reason = reasonSnapshot !== undefined && reasonSnapshot.trim() !== '' ? reasonSnapshot : undefined;
     const attributionKey = dropped ? 'dropped' : renamed ? 'renamed' : undefined;
+    const policyCause = settledBy === 'policy' ? policyCauseSnapshot : undefined;
     if (settledBy === undefined && reason === undefined && attributionKey === undefined)
         return undefined;
     return {
         ...(settledBy !== undefined ? { settledBy } : {}),
         ...(reason !== undefined ? { reason } : {}),
+        ...(policyCause !== undefined ? { policyCause } : {}),
         ...(attributionKey !== undefined ? { attributionKey } : {}),
     };
 }
@@ -1671,7 +1685,7 @@ function v1Bit(stamp) {
 const SUSPENDED_ASK_ARGS_NOTE = "this request's tool arguments are not available on this surface — it was raised while no client was connected, " +
     'so you are deciding without seeing them; deny it if you are not sure what it will do. ' +
     'Edits are not accepted on this card: there is no original input to edit';
-function cardFactsOf(carrier, leg, opts, liveFacts, approvalId) {
+function cardFactsOf(carrier, leg, opts, liveFacts, approvalId, payloadWhy) {
     const c = carrier;
     const full = leg !== 'generic';
     const live = leg === 'frame' ? carrier : leg === 'v1' ? liveFacts : undefined;
@@ -1822,6 +1836,16 @@ function cardFactsOf(carrier, leg, opts, liveFacts, approvalId) {
             if (w !== undefined)
                 out.approvalCard = w;
         });
+        v1Bit(() => {
+            const id = approvalAgentIdOf(carrier);
+            if (id !== undefined)
+                out.agentId = id;
+        });
+        v1Bit(() => {
+            const reasons = approvalAskReasonsOf(carrier);
+            if (reasons !== undefined)
+                out.askReasons = reasons;
+        });
     }
     v1Bit(() => {
         const pair = readAskClassPair(carrier);
@@ -1847,8 +1871,11 @@ function cardFactsOf(carrier, leg, opts, liveFacts, approvalId) {
         if (typeof msg === 'string' && msg.trim() !== '')
             out.message = msg;
     });
-    if (leg === 'generic')
+    if (leg === 'generic') {
         out.cardPayloadUnreadable = true;
+        if (payloadWhy !== undefined)
+            out.cardPayloadUnreadableWhy = payloadWhy;
+    }
     if (sessionAllowCarried(leg, approvalId))
         out.allowSessionCarried = true;
     out.grantBinding = readApprovalGrantBinding(carrier);
@@ -1880,15 +1907,26 @@ export function approvalCardFactsOfFrame(frame, opts) {
         return undefined;
     return Object.freeze(cardFactsOf(frame, 'frame', opts));
 }
-export function approvalCardFactsOfGeneric(card) {
+export function approvalCardFactsOfGeneric(card, reading) {
     if (typeof card !== 'object' || card === null)
         return undefined;
-    return Object.freeze(cardFactsOf(card, 'generic'));
+    return Object.freeze(cardFactsOf(card, 'generic', null, undefined, undefined, approvalFrameUnreadableWhyOf(reading)));
 }
 const MAX_RESPOND_NOTE_CHARS = 2048;
 export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamArgs, signal, lane, run) {
+    const approvalId = readOwnDataNonEmptyString(frame, 'approvalId');
+    if (approvalId === undefined)
+        return approvalIdUnreadableRefusal();
+    return surfaceApprovalFrameWithId(frame, approvalId, respond, streamArgs, signal, lane, run);
+}
+function approvalIdUnreadableRefusal() {
+    hostLog('debug', 'liveToolApprovalWire: refused (approvalId_unreadable)');
+    return { kind: 'not_sent', lane: 'respond', cause: 'card_unavailable' };
+}
+export async function surfaceApprovalFrameWithId(frame, approvalId, respond, streamArgs, signal, lane, run) {
     const receivedAtMs = Date.now();
-    const approvalId = frame.approvalId;
+    if (typeof approvalId !== 'string' || approvalId === '')
+        return approvalIdUnreadableRefusal();
     const carriers = openingFrameCarriersOf(frame);
     const entry = { frame, carriers, approvalId, identity: liveCardIdentityOf(approvalId, frame, carriers, run), respond, streamArgs, signal, lane, receivedAtMs };
     return enterLiveCard(entry);
@@ -1898,9 +1936,10 @@ function openingFrameCarriersOf(frame) {
         return { body: frame, live: frame, leg: 'frame' };
     const card = frame.card;
     const pinned = Object.create(frame, { card: { value: card, enumerable: true } });
-    if (isApprovalRequestFrameV1(pinned))
+    const reading = approvalRequestFrameReadingThrowing(pinned);
+    if (reading.v1)
         return { body: pinned.card, live: frame, leg: 'v1' };
-    return { body: typeof card === 'object' && card !== null ? card : {}, live: undefined, leg: 'generic' };
+    return { body: typeof card === 'object' && card !== null ? card : {}, live: undefined, leg: 'generic', why: reading.why };
 }
 function enterLiveCard(e) {
     const { approvalId, signal } = e;
@@ -1998,7 +2037,7 @@ async function presentToolApprovalFrameAndRespond(frame, carriers, approvalId, r
     const bodyToolCallId = carriers.body.toolCallId;
     const frameToolCallId = typeof bodyToolCallId === 'string' && bodyToolCallId !== '' ? bodyToolCallId : undefined;
     const decidedByReading = decidedByReadingSnapshotOf(lane);
-    const facts = cardFactsOf(carriers.body, carriers.leg, { streamArgs, ...(lane?.argsUnavailable === true ? { argsUnavailable: true } : {}) }, carriers.live, approvalId);
+    const facts = cardFactsOf(carriers.body, carriers.leg, { streamArgs, ...(lane?.argsUnavailable === true ? { argsUnavailable: true } : {}) }, carriers.live, approvalId, carriers.why);
     const argsNotRealInput = facts.argsUnavailable === true;
     const ruleOffers = facts.ruleOffers;
     if (argsNotRealInput && lane?.argsUnavailable !== true && facts.wireNote !== undefined) {
@@ -2059,6 +2098,7 @@ async function presentToolApprovalFrameAndRespond(frame, carriers, approvalId, r
         hostLog('debug', `liveToolApprovalWire: ${approvalId} card carried a note on Yes (len=${card.note.length}) — this engine has no field that brings it to the model, so it was not sent`);
     }
     const denySettledByForWire = card.kind === 'deny' ? readApprovalDenySettledBy(card) : undefined;
+    const denyPolicyCauseForWire = card.kind === 'deny' ? readPolicyDenyCause(card) : undefined;
     const attributionKeys = decision === 'deny' ? decisionAttributionKeyOf(decidedByReading, denySettledByForWire) : {};
     const sentAttributionKey = carriesAttributionKey(attributionKeys);
     let lastSendCarriedAttribution = sentAttributionKey;
@@ -2300,7 +2340,7 @@ async function presentToolApprovalFrameAndRespond(frame, carriers, approvalId, r
                 'this answer was not delivered, reporting the earlier decision');
             return { kind: 'decided', lane: 'respond', decision: replayed.decision, ack: replayed };
         }
-        const deny = decision === 'deny' ? denyFactsOf(denySettledByForWire, denyReasonSnapshot, attributionDropped, attributionRenamed) : undefined;
+        const deny = decision === 'deny' ? denyFactsOf(denySettledByForWire, denyReasonSnapshot, attributionDropped, attributionRenamed, denyPolicyCauseForWire) : undefined;
         return { kind: 'decided', lane: 'respond', decision, ...(ack !== undefined ? { ack } : {}), ...(deny !== undefined ? { deny } : {}) };
     }
     catch (e) {

package/dist/hooksReaderGenerations.d.ts

@@ -0,0 +1 @@
+export declare function hooksReaderNotReadKeys(serverVersion: string | undefined): readonly string[];

package/dist/hooksReaderGenerations.js

@@ -0,0 +1,12 @@
+import { engineVersionTier } from './supportFloor.js';
+const HOOKS_READER_GENERATIONS = Object.freeze([
+    Object.freeze({ from: '7.139.0', below: '7.147.0', notRead: Object.freeze(['onFailure']) }),
+]);
+const HOOKS_READER_FAIL_CLOSED = Object.freeze([...new Set(HOOKS_READER_GENERATIONS.flatMap((g) => g.notRead))]);
+export function hooksReaderNotReadKeys(serverVersion) {
+    for (const g of HOOKS_READER_GENERATIONS) {
+        if (engineVersionTier(serverVersion, g.from) === 'engine' && engineVersionTier(serverVersion, g.below) === 'legacy')
+            return g.notRead;
+    }
+    return HOOKS_READER_FAIL_CLOSED;
+}