@sema-agent/client-core 0.94.0 → 0.96.0

package/dist/hitl/replayedApproval.js

@@ -1,29 +1,65 @@
-import { hasLedgerPositionKey } from './gateLedger.js';
+import { APPROVAL_SETTLED_HOWS, hasLedgerPositionKey } from './gateLedger.js';
 import { readLivePendingRows } from './livePendingAsk.js';
 import { projectCrashConverged } from './crashConverged.js';
+import { quoteUntrustedForSentence } from '../displayUntrusted.js';
+import { readOwnDataValue } from '../ownKey.js';
 const live = (basis) => Object.freeze({ kind: 'live', basis });
 const unknown = (why) => Object.freeze({ kind: 'unknown', why });
-const decided = (cause) => Object.freeze(cause !== undefined ? { kind: 'decided', cause } : { kind: 'decided' });
+const decided = (row) => Object.freeze(row === undefined
+    ? { kind: 'decided' }
+    : { kind: 'decided', cause: row.cause, ...(row.needsHumanReason !== undefined ? { needsHumanReason: row.needsHumanReason } : {}) });
+const decidedSettled = (how) => Object.freeze({ kind: 'decided', settled: how });
 function approvalIdOf(frame) {
     const v = frame.approvalId;
     return typeof v === 'string' && v !== '' ? v : undefined;
 }
-function crashConvergedCauseOf(body, approvalId) {
+function crashConvergedFactsOf(body, approvalId) {
     const projection = projectCrashConverged(body);
     if (projection === undefined)
         return undefined;
     for (const row of [...projection.resumeSafe, ...projection.needsHuman]) {
         if (row.approvalId === approvalId)
-            return row.cause;
+            return { cause: row.cause, ...(row.needsHumanReason !== undefined ? { needsHumanReason: row.needsHumanReason } : {}) };
     }
     return undefined;
 }
+export function settledApprovalDisposition(frame, settled) {
+    try {
+        if (typeof settled !== 'object' || settled === null || typeof settled.get !== 'function')
+            return undefined;
+        const id = approvalIdOf(frame);
+        if (id === undefined)
+            return undefined;
+        const how = settled.get(id);
+        return typeof how === 'string' && APPROVAL_SETTLED_HOWS.includes(how) ? decidedSettled(how) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function replayedApprovalDisposition(frame, basis) {
     let approvalId;
+    let positioned;
     try {
         if (typeof frame !== 'object' || frame === null)
             return unknown('unreadable_frame');
-        if (!hasLedgerPositionKey(frame))
+        positioned = hasLedgerPositionKey(frame);
+    }
+    catch {
+        return unknown('unreadable_frame');
+    }
+    let settledBasis;
+    try {
+        settledBasis = typeof basis === 'object' && basis !== null ? basis.settled : undefined;
+    }
+    catch {
+        settledBasis = undefined;
+    }
+    const early = settledApprovalDisposition(frame, settledBasis);
+    if (early !== undefined)
+        return early;
+    try {
+        if (!positioned)
             return live('live_leg');
         approvalId = approvalIdOf(frame);
     }
@@ -70,15 +106,15 @@ export function replayedApprovalDisposition(frame, basis) {
     }
     if (reading.kind === 'present' && reading.rows.some((r) => r.approvalId === approvalId))
         return live('pending_list');
-    let cause;
+    let facts;
     try {
-        cause = crashConvergedCauseOf(body, approvalId);
+        facts = crashConvergedFactsOf(body, approvalId);
     }
     catch {
-        cause = undefined;
+        facts = undefined;
     }
-    if (cause !== undefined)
-        return decided(cause);
+    if (facts !== undefined)
+        return decided(facts);
     if (reading.kind === 'not_reported')
         return unknown('list_not_reported');
     if (reading.kind === 'malformed')
@@ -87,3 +123,96 @@ export function replayedApprovalDisposition(frame, basis) {
         return unknown('list_incomplete');
     return decided();
 }
+const TOOL_NAME_MAX = 80;
+const THIS_REQUEST = 'this approval request';
+const sentenceInitial = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+const TOOL_STATE_NOT_SHOWN = 'Whether the tool had started is not shown here.';
+const STOPPED_BY_CAUSE = Object.freeze({
+    crashed_before_park: 'the engine stopped unexpectedly',
+    shutdown_before_park: 'the engine was shut down in an orderly way',
+});
+const STATE_BY_REASON = Object.freeze({
+    pending_unsafe: 'waiting',
+    approved_then_interrupted: 'approved',
+    contradictory: 'unclear',
+    unstable_row: 'unclear',
+});
+const CRASH_CONVERGED_SENTENCE = Object.freeze({
+    waiting: (what, stopped) => `${sentenceInitial(what)} was still waiting when ${stopped}, so the engine denied it automatically; no decision was sent for it from here. ${TOOL_STATE_NOT_SHOWN}`,
+    approved: (what, stopped) => `${sentenceInitial(what)} had already been approved and may have been running when ${stopped}, so a side effect may have partly landed; the engine then marked it denied, and no decision was sent for it from here.`,
+    unclear: (what, stopped) => `${sentenceInitial(what)} was denied automatically when ${stopped}, but its record does not show reliably whether it had been approved or whether the tool had started; no decision was sent for it from here.`,
+});
+function crashConvergedStateOf(disposition) {
+    let reason;
+    try {
+        if (typeof disposition !== 'object' || disposition === null || !('needsHumanReason' in disposition))
+            return 'waiting';
+        reason = disposition.needsHumanReason;
+    }
+    catch {
+        return 'unclear';
+    }
+    if (reason === undefined)
+        return 'waiting';
+    return typeof reason === 'string' && Object.hasOwn(STATE_BY_REASON, reason) ? STATE_BY_REASON[reason] : 'unclear';
+}
+const SETTLED_PHRASE = Object.freeze({
+    answered: 'answered',
+    interrupted: 'dismissed',
+    closed_by_engine: 'closed by the engine',
+});
+const settledRepeat = (what, how) => `${sentenceInitial(what)} was ${SETTLED_PHRASE[how]} earlier, so this repeated copy of it was not raised as a new question and no decision was sent for it.`;
+const decidedPlain = (what) => `${sentenceInitial(what)} is no longer listed by the engine as waiting for a decision, so no decision was sent for it.`;
+export function replayedApprovalClosesCardFrame(disposition) {
+    try {
+        if (typeof disposition !== 'object' || disposition === null)
+            return false;
+        if (readOwnDataValue(disposition, 'kind') !== 'decided')
+            return false;
+        const cause = readOwnDataValue(disposition, 'cause');
+        return typeof cause === 'string' && Object.hasOwn(STOPPED_BY_CAUSE, cause);
+    }
+    catch {
+        return false;
+    }
+}
+const unconfirmed = (what) => `Whether ${what} is still waiting for a decision could not be confirmed, so no decision was sent for it.`;
+function guardedGet(o, key) {
+    try {
+        if (typeof o !== 'object' || o === null)
+            return undefined;
+        return o[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+function subjectOf(opts) {
+    const raw = guardedGet(opts, 'toolName');
+    if (typeof raw !== 'string')
+        return THIS_REQUEST;
+    let quoted;
+    try {
+        quoted = quoteUntrustedForSentence(raw, TOOL_NAME_MAX);
+    }
+    catch {
+        return THIS_REQUEST;
+    }
+    return quoted === undefined ? THIS_REQUEST : `the approval request for ${quoted}`;
+}
+export function replayedApprovalSentence(disposition, opts) {
+    const kind = guardedGet(disposition, 'kind');
+    if (kind === 'unknown')
+        return unconfirmed(subjectOf(opts));
+    if (kind !== 'decided')
+        return undefined;
+    const what = subjectOf(opts);
+    const cause = guardedGet(disposition, 'cause');
+    if (typeof cause === 'string' && Object.hasOwn(STOPPED_BY_CAUSE, cause)) {
+        return CRASH_CONVERGED_SENTENCE[crashConvergedStateOf(disposition)](what, STOPPED_BY_CAUSE[cause]);
+    }
+    const settled = guardedGet(disposition, 'settled');
+    if (typeof settled === 'string' && Object.hasOwn(SETTLED_PHRASE, settled))
+        return settledRepeat(what, settled);
+    return decidedPlain(what);
+}

package/dist/hitl/resumeRunningCard.d.ts

@@ -17,6 +17,7 @@ export interface ResumeRunningCardOption {
 }
 export declare function resumeRunningLivenessRow(msSinceLastActivity: number | null | undefined): string | null;
 export declare function resumeRunningQuestionText(i: ResumeRunningCardInput): string;
+export declare function runningAttachOffered(canAttach: boolean | undefined): boolean;
 export declare function resumeRunningOptions(i: ResumeRunningCardInput): ResumeRunningCardOption[];
 export declare function resumeChoiceFromLabels(selected: readonly string[] | null | undefined): ResumeRunningChoice;
 export declare const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
@@ -26,4 +27,5 @@ export declare function resumeRunningNoUiGuidance(i: {
     sessionId?: string | null;
 }): string;
 export declare function resumeAttachReplayDisclosure(taskId: string): string;
+export declare function resumeRunningCancelConfirmedRow(taskId: string): string;
 export declare function resumeRunningCancelUnconfirmedRow(taskId: string): string;

package/dist/hitl/resumeRunningCard.js

@@ -14,6 +14,9 @@ export function resumeRunningQuestionText(i) {
     const liveness = resumeRunningLivenessRow(i.msSinceLastActivity);
     return liveness === null ? head : `${head}\n${liveness}`;
 }
+export function runningAttachOffered(canAttach) {
+    return canAttach === true;
+}
 export function resumeRunningOptions(i) {
     const options = [
         {
@@ -21,7 +24,7 @@ export function resumeRunningOptions(i) {
             description: 'Leaves the run alone. It keeps executing on the engine, but this screen will not show it and it will not be listed here — your next message runs into it again, and sema asks you then.',
         },
     ];
-    if (i.canAttach) {
+    if (runningAttachOffered(i.canAttach)) {
         options.push({
             label: RESUME_CHOICE_ATTACH_LABEL,
             description: 'Follows that run from here: sema replays it from the engine ledger and keeps streaming it into this conversation. ' +
@@ -65,8 +68,16 @@ export function resumeAttachReplayDisclosure(taskId) {
         `The replayed turns are not billed into this session's cost again either — the engine's own record ` +
         `(GET /v1/runs/${taskId}) is the authority on what that run really spent.`);
 }
+function cancelRow(taskId, confirmed) {
+    return confirmed
+        ? `The engine accepted the cancel for run ${taskId} on your request. A cancel finishes on the engine's side, so that run may need a moment to stop.`
+        : `sema: the cancel for run ${taskId} did not come back confirmed, so that run may still be executing. ` +
+            `This screen does not list it — read its real state on the engine (GET /v1/runs/${taskId}) before ` +
+            `assuming this session is free.`;
+}
+export function resumeRunningCancelConfirmedRow(taskId) {
+    return cancelRow(taskId, true);
+}
 export function resumeRunningCancelUnconfirmedRow(taskId) {
-    return (`sema: the cancel for run ${taskId} did not come back confirmed, so that run may still be executing. ` +
-        `This screen does not list it — read its real state on the engine (GET /v1/runs/${taskId}) before ` +
-        `assuming this session is free.`);
+    return cancelRow(taskId, false);
 }

package/dist/hitl/sessionPolicyDeliverable.js

@@ -1,7 +1,7 @@
 import { CONFIG_LEGACY_TOOL_NAME, RULES_LEGACY_TOOL_NAME } from '../engineErrorCodes.js';
 import { rosterMountedNames } from '../rosterMountedNames.js';
 import { ruleCompileVerdict } from '../ruleCompileVerdict.js';
-import { protocolSegmentOf } from '../protocolSegment.js';
+import { ruleToolNameVerdictOf } from '../protocolSegment.js';
 import { PREFIXES_IN_PROSE, REFUSED_NAME_CLASSES, REFUSED_NAME_FIX, RULES_LEGACY_TOOL_NAME_WRITE_NOTE } from './refusedToolNameProse.js';
 import { CORE_PROTOCOL_PREFIXES, CORE_RETIRED_TOOL_CURRENT_NAMES } from '../generated/toolNameTables.js';
 import { isEngineRefusedToolName } from '../engineRefusedToolName.js';
@@ -96,18 +96,20 @@ export function sessionPolicyDeliverable(behavior, rules, opts) {
         }
         let why = withheldWhyOf(r);
         if (why === undefined) {
-            const grammar = ruleCompileVerdict(r, 'deny');
+            const grammar = ruleCompileVerdict(r, 'deny').kind;
             if (grammar === 'unknown')
                 return unreadable();
             if (grammar === 'refused')
                 why = 'not_a_tool_name';
         }
         if (why === undefined && COVERING_NAMESPACE_PREFIXES.some((p) => r.startsWith(p))) {
-            const segment = protocolSegmentOf(r);
-            if (segment.kind === 'empty' || segment.kind === 'unminted')
-                why = 'not_a_tool_name';
-            else if (segment.kind === 'unknown')
+            const verdict = ruleToolNameVerdictOf(r);
+            if (verdict.kind === 'unknown')
                 return unreadable();
+            if (verdict.kind === 'unmintable_segment')
+                why = 'not_a_tool_name';
+            else if (verdict.kind === 'retired' || verdict.kind === 'unprefixed_namespace')
+                why = 'legacy_tool_name';
         }
         if (why === undefined && mounted !== undefined && !mounted.has(r))
             why = 'not_in_roster';

package/dist/hitl/standingRows.d.ts

@@ -0,0 +1,18 @@
+export type StandingRowWhy = 'given' | 'card_unreadable' | 'remember_refused' | 'remember_unreadable' | 'route_cannot_carry' | 'classes_unreadable' | 'not_deployment_list_question' | 'evidence_unreadable' | 'offers_unreadable' | 'engine_lane_closed' | 'args_unavailable' | 'grant_binding' | 'tool_name_unreadable' | 'rule_cannot_clear' | 'host_fact_missing' | 'face_not_generic' | 'rule_not_sent';
+export type StandingPersistentRow = 'engine_offer' | 'local_whole_tool' | 'none';
+export interface StandingRowsWhy {
+    readonly session: StandingRowWhy;
+    readonly persistent: StandingRowWhy;
+    readonly deploymentList: StandingRowWhy;
+}
+export interface StandingRows {
+    readonly sessionRow: boolean;
+    readonly persistentRow: StandingPersistentRow;
+    readonly deploymentListSessionRow: boolean;
+    readonly why: StandingRowsWhy;
+}
+export interface StandingRowsHostFacts {
+    readonly cardFace?: string;
+    readonly wholeToolRuleSent?: boolean;
+}
+export declare function standingRowsOf(card: object | null | undefined, host?: StandingRowsHostFacts | null): StandingRows;

package/dist/hitl/standingRows.js

@@ -0,0 +1,127 @@
+import { readAskClassPairState } from './askClassPair.js';
+import { automaticAnswerVerdict } from './automaticAnswerVerdict.js';
+import { readRuleOffers } from './toolApprovalWire.js';
+const DEPLOYMENT_LIST_ASK_CLASSES = Object.freeze(['ask_rule']);
+const UNREADABLE = Symbol('unreadable');
+function ownData(v, key) {
+    try {
+        const d = Object.getOwnPropertyDescriptor(v, key);
+        return d !== undefined && 'value' in d ? d.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasKey(v, key) {
+    try {
+        return { inCard: key in v };
+    }
+    catch {
+        return UNREADABLE;
+    }
+}
+function present(v, key) {
+    try {
+        const inCard = key in v;
+        return { inCard, value: inCard ? v[key] : undefined };
+    }
+    catch {
+        return UNREADABLE;
+    }
+}
+function freezeRows(sessionRow, persistentRow, deploymentListSessionRow, why) {
+    return Object.freeze({ sessionRow, persistentRow, deploymentListSessionRow, why: Object.freeze({ ...why }) });
+}
+function allClosed(why) {
+    return freezeRows(false, 'none', false, { session: why, persistent: why, deploymentList: why });
+}
+function persistentRowOf(card, host, evidenceUnreadable) {
+    if (evidenceUnreadable)
+        return { row: 'none', why: 'evidence_unreadable' };
+    for (const key of ['ruleOffers', 'ruleOffersReadOnly']) {
+        const p = hasKey(card, key);
+        if (p === UNREADABLE)
+            return UNREADABLE;
+        if (!p.inCard)
+            continue;
+        const offers = readRuleOffers(ownData(card, key));
+        if (offers === undefined || offers.length === 0)
+            return { row: 'none', why: 'offers_unreadable' };
+        return { row: 'engine_offer', why: 'given' };
+    }
+    const absence = present(card, 'ruleOffersAbsence');
+    if (absence === UNREADABLE)
+        return UNREADABLE;
+    if (absence.inCard)
+        return { row: 'none', why: 'engine_lane_closed' };
+    const blind = present(card, 'argsUnavailable');
+    if (blind === UNREADABLE)
+        return UNREADABLE;
+    if (blind.inCard)
+        return { row: 'none', why: 'args_unavailable' };
+    if (ownData(card, 'grantBinding') !== 'none')
+        return { row: 'none', why: 'grant_binding' };
+    const tool = ownData(card, 'toolName');
+    if (typeof tool !== 'string' || tool.length === 0)
+        return { row: 'none', why: 'tool_name_unreadable' };
+    if (automaticAnswerVerdict(card, 'standing_rule').kind !== 'may_answer')
+        return { row: 'none', why: 'rule_cannot_clear' };
+    if (typeof host !== 'object' || host === null)
+        return { row: 'none', why: 'host_fact_missing' };
+    const face = ownData(host, 'cardFace');
+    if (typeof face !== 'string')
+        return { row: 'none', why: 'host_fact_missing' };
+    if (face !== 'generic')
+        return { row: 'none', why: 'face_not_generic' };
+    const sent = ownData(host, 'wholeToolRuleSent');
+    if (typeof sent !== 'boolean')
+        return { row: 'none', why: 'host_fact_missing' };
+    if (!sent)
+        return { row: 'none', why: 'rule_not_sent' };
+    return { row: 'local_whole_tool', why: 'given' };
+}
+export function standingRowsOf(card, host) {
+    if (typeof card !== 'object' || card === null)
+        return allClosed('card_unreadable');
+    try {
+        const refused = present(card, 'rememberRefused');
+        if (refused === UNREADABLE)
+            return allClosed('card_unreadable');
+        if (refused.inCard)
+            return allClosed(refused.value === true ? 'remember_refused' : 'remember_unreadable');
+        const evidence = present(card, 'unreadableEvidence');
+        if (evidence === UNREADABLE)
+            return allClosed('card_unreadable');
+        let evidenceUnreadable = false;
+        if (evidence.inCard) {
+            const list = ownData(card, 'unreadableEvidence');
+            if (!Array.isArray(list) || !list.every((k) => typeof k === 'string'))
+                return allClosed('card_unreadable');
+            if (list.includes('rememberRefused'))
+                return allClosed('remember_unreadable');
+            evidenceUnreadable = list.length > 0;
+        }
+        const sessionRow = ownData(card, 'allowSessionCarried') === true;
+        const sessionWhy = sessionRow ? 'given' : 'route_cannot_carry';
+        let deploymentList;
+        if (!sessionRow) {
+            deploymentList = 'route_cannot_carry';
+        }
+        else {
+            const pair = readAskClassPairState(card);
+            deploymentList =
+                pair.state !== 'pair'
+                    ? 'classes_unreadable'
+                    : pair.classes.every((c) => DEPLOYMENT_LIST_ASK_CLASSES.includes(c))
+                        ? 'given'
+                        : 'not_deployment_list_question';
+        }
+        const persistent = persistentRowOf(card, host, evidenceUnreadable);
+        if (persistent === UNREADABLE)
+            return allClosed('card_unreadable');
+        return freezeRows(sessionRow, persistent.row, deploymentList === 'given', { session: sessionWhy, persistent: persistent.why, deploymentList });
+    }
+    catch {
+        return allClosed('card_unreadable');
+    }
+}

package/dist/hitl/toolApprovalWire.d.ts

@@ -6,7 +6,7 @@ import { type DenyAttributionRefusalDetail } from '../wireRefusalCopy.js';
 import { type ApprovalDecidedByReading } from '../approvalDecidedByCapability.js';
 import { type DecideReceiptView } from '../decideReceipt.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, ToolApprovalRespondAck, PersistedRuleAnchor as SdkPersistedRuleAnchor, RuleOfferMatch as SdkRuleOfferMatch, RuleOfferBatchMember as SdkRuleOfferBatchMember, RuleOfferUncoveredDetail as SdkRuleOfferUncoveredDetail, RuleOfferUncoveredReason as SdkRuleOfferUncoveredReason, AskOrigin as SdkAskOrigin, RuleOffersAbsence as SdkRuleOffersAbsence, DenialLimitKind as SdkDenialLimitKind, DenialLimitFallback as SdkDenialLimitFallback } from '@sema-agent/sdk';
+import type { ApprovalDecidedBy, ApprovalSettleCause, ToolApprovalRespondAck, PersistedRuleAnchor as SdkPersistedRuleAnchor, RuleOfferMatch as SdkRuleOfferMatch, RuleOfferBatchMember as SdkRuleOfferBatchMember, RuleOfferUncoveredDetail as SdkRuleOfferUncoveredDetail, RuleOfferUncoveredReason as SdkRuleOfferUncoveredReason, AskOrigin as SdkAskOrigin, RuleOffersAbsence as SdkRuleOffersAbsence, DenialLimitKind as SdkDenialLimitKind, DenialLimitFallback as SdkDenialLimitFallback } from '@sema-agent/sdk';
 export declare function isFsApprovalGate(gate: {
     kind?: unknown;
     toolName?: unknown;
@@ -40,8 +40,9 @@ export type FsApprovalOutcome = {
     stage: HitlFailureStage;
     gatedCallId?: string | undefined;
     reason: string;
-    code?: 'no_pending' | undefined;
+    code?: 'no_pending' | 'wrong_gate' | undefined;
     errorCode?: string | undefined;
+    blockedBy?: string | undefined;
     retriable?: true;
     safetyCode?: HitlSafetyCode | undefined;
     retryExhausted?: true;
@@ -68,7 +69,6 @@ export type DenialLimitKind = SdkDenialLimitKind;
 export type DenialLimitFallback = SdkDenialLimitFallback;
 export { RULE_OFFERS_ABSENCE_REASONS };
 export declare const ASK_ORIGIN_WORDS: readonly string[];
-export declare const APPROVAL_MANDATE_WORDS: readonly ["operator_always", "tool_marks", "probe_mandate", "probe_unanswered", "write_protection", "write_protection_unresolved"];
 export type WireRuleOffer = {
     kind: 'single';
     rule: string;
@@ -137,11 +137,11 @@ export interface ApprovalCardRequest {
     ruleOffersReadOnly?: RuleOffer[];
     inputHasBidi?: true;
     hasBidiControls?: true;
-    persistedRuleShadowed?: string;
     allowRuleShadow?: ApprovalAllowRuleShadow;
     probeCause?: unknown;
     probeReason?: string;
     rememberRefused?: true;
+    allowSessionCarried?: true;
     ruleEvidence?: unknown;
     requiresRealApproval?: true;
     irreversibleParkGate?: true;
@@ -158,6 +158,8 @@ export interface ApprovalCardRequest {
     askClass?: string;
     classes?: readonly string[];
     boundGrants?: BoundSkillGrantsWire;
+    grantBinding?: ApprovalGrantBinding;
+    unreadableEvidence?: readonly string[];
     classifierNoRuling?: string;
     priorCardsForCall?: readonly ApprovalPriorCard[];
 }
@@ -177,6 +179,9 @@ export declare function hasApprovalCardPortFor(sessionKey: string): boolean;
 export declare function approvalCardPortFor(sessionKey: string): ApprovalCardPort | null;
 export declare function _resetApprovalCardPortForTest(): void;
 export declare function surfaceApprovalCard(req: ApprovalCardRequest): Promise<ApprovalCardDecision>;
+declare const REMEMBER_REFUSAL_CODES: readonly ["remember_not_in_proof", "remember_requires_binding", "capability.store_required", "decide.workflow_remember_unsupported", "decide.parked_remember_unsupported"];
+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): Promise<FsApprovalOutcome>;
 export interface BoundSkillGrantsWire {
     readonly skill: string | null;
@@ -192,6 +197,7 @@ export interface ToolApprovalFrame {
     args?: unknown;
     argsOmitted?: boolean;
     outcome?: 'allowed' | 'denied' | 'expired';
+    cause?: ApprovalSettleCause;
     sourceTaskId?: string;
     fromSubagent?: true;
     sourceAgentName?: string;
@@ -232,7 +238,7 @@ export interface ToolApprovalDelegation {
     depth: number;
     agentName?: string;
 }
-export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "readRootCandidate", "mandated", "mandate", "origin", "askClass", "classes", "inputHasBidi", "parked", "persistedRuleShadowed", "allowRuleShadowed", "probeCause", "probeReason", "rememberRefused", "boundGrantDigest", "boundGrants", "classifierNoRuling", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome"];
+export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "readRootCandidate", "mandated", "mandate", "origin", "askClass", "classes", "inputHasBidi", "parked", "persistedRuleShadowed", "allowRuleShadowed", "probeCause", "probeReason", "rememberRefused", "boundGrantDigest", "boundGrants", "classifierNoRuling", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome", "cause"];
 export interface ApprovalMandatedFacts {
     readonly mandated?: true;
     readonly ruleOffersAbsence?: string;
@@ -242,7 +248,7 @@ export declare function approvalIsMandated(v: ApprovalMandatedFacts | undefined
 export declare function readApprovalMandate(v: {
     readonly mandate?: string;
 } | undefined | null): ApprovalMandateWord | undefined;
-export declare function toolPermissionRequestAskBits(card: object | null | undefined): Pick<ToolPermissionRequest, 'mandated' | 'mandate' | 'origin' | 'ruleOffersAbsence' | 'askClass' | 'classes'>;
+export declare function toolPermissionRequestAskBits(card: object | null | undefined): Pick<ToolPermissionRequest, 'mandated' | 'mandate' | 'origin' | 'ruleOffersAbsence' | 'askClass' | 'classes' | 'rememberRefused'>;
 export declare function isFromSubagent(frame: ToolApprovalFrame): boolean;
 export type ToolApprovalRespondDecision = 'allow' | 'allow_session' | 'deny';
 export interface RespondToolApprovalOpts {
@@ -296,6 +302,12 @@ interface ToolApprovalRespondRefusalFields {
     status?: number;
     errorCode?: string;
     message?: string;
+    retriable?: true;
+    extra?: {
+        readonly cause?: string;
+        readonly field?: string;
+    };
+    unreadable?: true;
 }
 export type ToolApprovalRespondRefusal = (ToolApprovalRespondRefusalFields & {
     status: number;
@@ -307,7 +319,9 @@ export type ToolApprovalRespondRefusal = (ToolApprovalRespondRefusalFields & {
 export declare function readToolApprovalRespondRefusal(err: unknown): ToolApprovalRespondRefusal | undefined;
 export declare function isToolApprovalFrame(ev: unknown): ev is ToolApprovalFrame;
 export declare function askProbeReasonDetail(card: Pick<ApprovalCardRequest, 'probeReason' | 'probeCause'> | null | undefined): string | undefined;
+export declare function readApprovalRememberRefused(v: unknown): boolean;
 export declare function readApprovalBoundGrants(v: unknown): BoundSkillGrantsWire | undefined;
+export type ApprovalGrantBinding = 'bound' | 'none' | 'unreadable';
 export declare function readApprovalClassifierNoRuling(v: unknown): string | undefined;
 export declare function classifierNoRulingDetail(word: string | undefined): string;
 export declare function approvalBoundGrantsDetail(grants: BoundSkillGrantsWire | null | undefined): string | undefined;
@@ -315,6 +329,8 @@ export declare function approvalPriorCardsDetail(card: Pick<ApprovalCardRequest,
 export declare function readDenialLimitFallback(v: unknown): DenialLimitFallback | undefined;
 export declare function readRuleOffers(v: unknown): RuleOffer[] | undefined;
 export declare function readRuleOfferSupply(offers: unknown): RuleOffer[] | 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'>;
+export declare function approvalCardFactsOfV1(card: object | null | undefined): Readonly<ApprovalCardV1Facts> | undefined;
 export interface ToolApprovalFrameLaneOpts {
     approvalDecisionNoteCapable?: boolean;
     respondFreeFormRulesCapable?: boolean;
@@ -323,4 +339,20 @@ export interface ToolApprovalFrameLaneOpts {
     windowIsCurrent?: boolean;
     argsUnavailable?: true;
 }
-export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts): Promise<ToolApprovalFrameOutcome>;
+export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts, run?: {
+    readonly taskId?: string;
+    readonly sessionId?: string;
+}): Promise<ToolApprovalFrameOutcome>;
+export interface ApprovalHolderIdentity {
+    readonly approvalId?: string;
+    readonly taskId?: string;
+    readonly toolCallId?: string;
+    readonly sessionId?: string;
+}
+export type ApprovalHolderJoin = {
+    readonly kind: 'joined';
+    readonly outcome: ToolApprovalFrameOutcome;
+} | {
+    readonly kind: 'free';
+};
+export declare function joinApprovalHolder(identity: ApprovalHolderIdentity, signal?: AbortSignal): Promise<ApprovalHolderJoin>;