@sema-agent/client-core 0.97.1 → 0.98.0

package/dist/generated/engineNoticeTables.js

@@ -8,6 +8,7 @@ export const CORE_ENGINE_NOTICE_CODES = Object.freeze([
     "config.read_face_deployment_clamped",
     "config.write_face_swapped",
     "config.write_face_deployment_clamped",
+    "config.read_deny_swapped",
     "config.tool_model_gate_removed",
     "config.tool_model_gate_unknown_class",
     "config.tool_model_gate_env_invalid",
@@ -85,10 +86,12 @@ export const CORE_ENGINE_NOTICE_CODES = Object.freeze([
     "skills.listing_truncated",
     "agents.listing_truncated",
     "tool_result.offload_put_failed",
+    "tool_result.media_refused",
     "instructions.source_changed",
     "session.records_skipped",
     "memory.layer_locked_legacy",
     "server.model_unreachable",
+    "permission.entry_mode_clamped",
 ]);
 export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "config.autocompact_window_clamped": "operator",
@@ -100,6 +103,7 @@ export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "config.read_face_deployment_clamped": "operator",
     "config.write_face_swapped": "operator",
     "config.write_face_deployment_clamped": "operator",
+    "config.read_deny_swapped": "operator",
     "config.tool_model_gate_removed": "operator",
     "config.tool_model_gate_unknown_class": "operator",
     "config.tool_model_gate_env_invalid": "operator",
@@ -177,10 +181,12 @@ export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "skills.listing_truncated": "operator",
     "agents.listing_truncated": "operator",
     "tool_result.offload_put_failed": "operator",
+    "tool_result.media_refused": "operator",
     "instructions.source_changed": "user",
     "session.records_skipped": "user",
     "memory.layer_locked_legacy": "operator",
     "server.model_unreachable": "user",
+    "permission.entry_mode_clamped": "user",
 });
 export const CORE_MCP_INJECTION_DROP_REASONS = Object.freeze([
     "malformed_entry",
@@ -198,6 +204,7 @@ export const CORE_NOTICE_MINTER = Object.freeze({
     "config.read_face_deployment_clamped": "engine",
     "config.write_face_swapped": "engine",
     "config.write_face_deployment_clamped": "engine",
+    "config.read_deny_swapped": "engine",
     "config.tool_model_gate_removed": "engine",
     "config.tool_model_gate_unknown_class": "engine",
     "config.tool_model_gate_env_invalid": "engine",
@@ -275,10 +282,12 @@ export const CORE_NOTICE_MINTER = Object.freeze({
     "skills.listing_truncated": "engine",
     "agents.listing_truncated": "engine",
     "tool_result.offload_put_failed": "engine",
+    "tool_result.media_refused": "engine",
     "instructions.source_changed": "server",
     "session.records_skipped": "server",
     "memory.layer_locked_legacy": "server",
     "server.model_unreachable": "server",
+    "permission.entry_mode_clamped": "server",
 });
 export const CORE_USER_INPUT_UNDRAINED_CAUSES = Object.freeze([
     "leg_end",

package/dist/generated/toolNameTables.d.ts

@@ -1,2 +1,3 @@
 export declare const CORE_PROTOCOL_PREFIXES: readonly ["mcp__", "a2a__"];
 export declare const CORE_SKILL_TOOL_NAME: "Skill";
+export declare const CORE_BOUND_GRANT_ABSENCES: readonly ["not_bindable", "unreadable"];

package/dist/generated/toolNameTables.js

@@ -1,2 +1,3 @@
 export const CORE_PROTOCOL_PREFIXES = ["mcp__", "a2a__"];
 export const CORE_SKILL_TOOL_NAME = "Skill";
+export const CORE_BOUND_GRANT_ABSENCES = ["not_bindable", "unreadable"];

package/dist/hitl/allowRuleShadow.d.ts

@@ -11,10 +11,15 @@ export interface AllowRuleShadowedWireMember {
     readonly omitted?: number;
 }
 export interface ApprovalAllowRuleShadow {
-    readonly source: 'allow_rule_shadowed' | 'legacy_shadowed_rule';
+    readonly source: 'allow_rule_shadowed';
     readonly members: readonly ApprovalAllowRuleShadowMember[];
     readonly unreadable?: true;
 }
+export declare const RETIRED_SHADOW_EVIDENCE_LABEL: Readonly<{
+    readonly frame: "persistedRuleShadowed";
+    readonly row: "riskDescriptor.shadowedRule";
+}>;
+export declare function retiredAllowRuleShadowKeyPresent(carrier: object | null | undefined, leg: 'frame' | 'row'): boolean;
 export declare function readAllowRuleShadowFromWire(carrier: object | null | undefined, leg: 'frame' | 'row'): ApprovalAllowRuleShadow | undefined;
 export declare function readApprovalAllowRuleShadow(card: object | null | undefined): ApprovalAllowRuleShadow | undefined;
 export declare function approvalAllowRuleShadowed(card: object | null | undefined): boolean;

package/dist/hitl/allowRuleShadow.js

@@ -76,20 +76,27 @@ function readNewKeyValue(raw) {
         return unreadable();
     return Object.freeze({ source: 'allow_rule_shadowed', members: Object.freeze(members) });
 }
-function readLegacyValue(raw) {
-    if (typeof raw !== 'string' || raw.trim() === '')
-        return undefined;
-    return Object.freeze({
-        source: 'legacy_shadowed_rule',
-        members: Object.freeze([freezeMember({ member: 'persisted', known: true, entries: Object.freeze([raw]) })]),
-    });
-}
 function ownValue(v, key) {
     return Object.hasOwn(v, key) ? v[key] : undefined;
 }
 function keyValue(v, key) {
     return v[key];
 }
+const RETIRED_SHADOW_KEY = Object.freeze({ frame: 'persistedRuleShadowed', row: 'shadowedRule' });
+export const RETIRED_SHADOW_EVIDENCE_LABEL = Object.freeze({ frame: 'persistedRuleShadowed', row: 'riskDescriptor.shadowedRule' });
+export function retiredAllowRuleShadowKeyPresent(carrier, leg) {
+    try {
+        if (typeof carrier !== 'object' || carrier === null)
+            return false;
+        const host = leg === 'row' ? keyValue(carrier, 'riskDescriptor') : carrier;
+        if (typeof host !== 'object' || host === null)
+            return false;
+        return RETIRED_SHADOW_KEY[leg] in host;
+    }
+    catch {
+        return true;
+    }
+}
 function readMemberAt(arr, i) {
     const d = Object.getOwnPropertyDescriptor(arr, i);
     return d !== undefined && 'value' in d ? readMemberRecord(d.value) : freezeMember({ known: false, malformed: true });
@@ -105,10 +112,7 @@ export function readAllowRuleShadowFromWire(carrier, leg) {
         }
         if (host === undefined)
             return undefined;
-        const fresh = readNewKeyValue(keyValue(host, 'allowRuleShadowed'));
-        if (fresh !== undefined)
-            return fresh;
-        return readLegacyValue(keyValue(host, leg === 'row' ? 'shadowedRule' : 'persistedRuleShadowed'));
+        return readNewKeyValue(keyValue(host, 'allowRuleShadowed'));
     }
     catch {
         return unreadable();
@@ -119,7 +123,7 @@ function readStampedValue(raw) {
         return unreadable();
     const source = ownValue(raw, 'source');
     const members = ownValue(raw, 'members');
-    if ((source !== 'allow_rule_shadowed' && source !== 'legacy_shadowed_rule') || !Array.isArray(members))
+    if (source !== 'allow_rule_shadowed' || !Array.isArray(members))
         return unreadable();
     const length = members.length;
     if (typeof length !== 'number' || !Number.isSafeInteger(length))
@@ -159,7 +163,7 @@ const ENTRY_MAX = 4096;
 const MEMBER_MAX = 64;
 const ENTRIES_SHOWN = 5;
 const UNREADABLE_LINE = 'An allow rule matched this call but cannot clear it; which rule could not be read, so this one is confirmed individually.';
-function legacySingleEntry(shadow) {
+function singlePersistedEntry(shadow) {
     if (shadow.unreadable === true || shadow.members.length !== 1)
         return undefined;
     const m = shadow.members[0];
@@ -196,9 +200,9 @@ export function allowRuleShadowSentence(card) {
     try {
         if (shadow.unreadable === true || shadow.members.length === 0)
             return UNREADABLE_LINE;
-        const legacy = legacySingleEntry(shadow);
-        if (legacy !== undefined) {
-            return `Your saved permission rule ${legacy} still exists — it just cannot clear this particular call, so this one is confirmed individually.`;
+        const single = singlePersistedEntry(shadow);
+        if (single !== undefined) {
+            return `Your saved permission rule ${single} still exists — it just cannot clear this particular call, so this one is confirmed individually.`;
         }
         return `Allow rules matched this call but cannot clear it, so this one is confirmed individually — ${shadow.members.map(memberPhrase).join(' · ')}.`;
     }

package/dist/hitl/approvalCardReading.d.ts

@@ -0,0 +1,15 @@
+import type { ApprovalCardRequest } from './toolApprovalWire.js';
+export declare function readRequiresRealApproval(carrier: object | null | undefined): boolean;
+export interface ApprovalWindowKeys {
+    readonly expiresInMs?: number;
+    readonly expiresAtMs?: number;
+    readonly serverNowMs?: number;
+    readonly receivedAtMs?: number;
+}
+export interface ApprovalWindowReadOpts {
+    readonly windowIsCurrent?: boolean;
+    readonly receivedAtMs?: number;
+    readonly unknownShape?: boolean;
+}
+export declare function approvalWindowKeysOf(carrier: object | null | undefined, opts?: ApprovalWindowReadOpts | null): Readonly<ApprovalWindowKeys>;
+export declare function probeCauseRowsOf(card: Pick<ApprovalCardRequest, 'probeCause'> | null | undefined): readonly string[] | undefined;

package/dist/hitl/approvalCardReading.js

@@ -0,0 +1,154 @@
+import { displayUntrusted } from '../displayUntrusted.js';
+import { guardedRead, readOwnDataValue } from '../ownKey.js';
+export function readRequiresRealApproval(carrier) {
+    if (typeof carrier !== 'object' || carrier === null)
+        return false;
+    let failed = false;
+    let failure;
+    try {
+        if (carrier.requiresRealApproval === true)
+            return true;
+    }
+    catch (e) {
+        failed = true;
+        failure = e;
+    }
+    try {
+        const risk = carrier.risk;
+        if (typeof risk === 'object' && risk !== null && risk.requiresRealApproval === true)
+            return true;
+    }
+    catch (e) {
+        if (!failed)
+            failure = e;
+        failed = true;
+    }
+    if (failed)
+        throw failure;
+    return false;
+}
+const EMPTY = Object.freeze({});
+const UNKNOWN_SHAPE_COHERENCE_TOLERANCE_MS = 1_000;
+function nonNegativeFinite(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined;
+}
+export function approvalWindowKeysOf(carrier, opts) {
+    if (typeof carrier !== 'object' || carrier === null)
+        return EMPTY;
+    if (typeof opts !== 'object' || opts === null)
+        return EMPTY;
+    let current;
+    let anchor;
+    let unknownShape;
+    try {
+        current = opts.windowIsCurrent;
+        anchor = opts.receivedAtMs;
+        unknownShape = opts.unknownShape;
+    }
+    catch {
+        return EMPTY;
+    }
+    if (current !== true)
+        return EMPTY;
+    const read = (key) => {
+        try {
+            return nonNegativeFinite(carrier[key]);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const inMs = read('expiresInMs');
+    const atMs = read('expiresAtMs');
+    const nowMs = read('serverNowMs');
+    if (unknownShape === true) {
+        if (inMs === undefined || atMs === undefined || nowMs === undefined)
+            return EMPTY;
+        if (atMs <= 0 || nowMs <= 0)
+            return EMPTY;
+        if (Math.abs(inMs - Math.max(0, atMs - nowMs)) > UNKNOWN_SHAPE_COHERENCE_TOLERANCE_MS)
+            return EMPTY;
+    }
+    const receivedAtMs = nonNegativeFinite(anchor);
+    const out = {};
+    if (inMs !== undefined)
+        out.expiresInMs = inMs;
+    if (atMs !== undefined)
+        out.expiresAtMs = atMs;
+    if (nowMs !== undefined)
+        out.serverNowMs = nowMs;
+    if ((inMs !== undefined || atMs !== undefined) && receivedAtMs !== undefined)
+        out.receivedAtMs = receivedAtMs;
+    return Object.freeze(out);
+}
+const PROBE_CAUSE_SHOWN_MAX = 8;
+const PROBE_CAUSE_ENTRY_MAX = 200;
+function own(v, key) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    return guardedRead(() => readOwnDataValue(v, key));
+}
+function readOperands(v) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    const shown = own(v, 'shown');
+    const isList = guardedRead(() => Array.isArray(shown));
+    if (isList !== true)
+        return undefined;
+    const length = own(shown, 'length');
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+        return undefined;
+    const items = [];
+    for (let i = 0; i < length; i++) {
+        const item = own(shown, String(i));
+        if (typeof item !== 'string')
+            return undefined;
+        items.push(item);
+    }
+    const total = own(v, 'total');
+    if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < 0 || total < items.length)
+        return undefined;
+    return { shown: items, total };
+}
+function operandsText(label, o) {
+    const shown = o.shown.slice(0, PROBE_CAUSE_SHOWN_MAX).map((p) => displayUntrusted(p, { max: PROBE_CAUSE_ENTRY_MAX }));
+    if (shown.length === 0)
+        return `${label}: ${String(o.total)} total`;
+    const more = o.total - shown.length;
+    return more > 0 ? `${label}: ${shown.join(', ')} (+${String(more)} more)` : `${label}: ${shown.join(', ')}`;
+}
+export function probeCauseRowsOf(card) {
+    try {
+        if (typeof card !== 'object' || card === null)
+            return undefined;
+        const cause = own(card, 'probeCause');
+        if (typeof cause !== 'object' || cause === null)
+            return undefined;
+        if (guardedRead(() => Array.isArray(cause)) !== false)
+            return undefined;
+        const code = own(cause, 'code');
+        if (typeof code !== 'string' || code === '')
+            return undefined;
+        const roots = readOperands(own(cause, 'roots'));
+        if (roots === undefined)
+            return undefined;
+        let fd;
+        try {
+            fd = Object.getOwnPropertyDescriptor(cause, 'further');
+        }
+        catch {
+            return undefined;
+        }
+        if (fd === undefined || (Object.hasOwn(fd, 'value') && fd.value === undefined))
+            return Object.freeze([operandsText('roots', roots)]);
+        if (!Object.hasOwn(fd, 'value'))
+            return undefined;
+        const further = readOperands(fd.value);
+        if (further === undefined)
+            return undefined;
+        return Object.freeze([operandsText('roots', roots), operandsText('further', further)]);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hitl/approvalCardReasons.d.ts

@@ -0,0 +1,13 @@
+import { type DenialLimitFallback } from './toolApprovalWire.js';
+export declare const APPROVAL_CARD_REASON_SOURCES: readonly ["payload_unreadable", "prior_cards", "message", "mandated", "mandate", "origin", "denial_limit", "probe", "allow_rule_shadow", "classifier_no_ruling", "bound_grants", "more"];
+export type ApprovalCardReasonSource = (typeof APPROVAL_CARD_REASON_SOURCES)[number];
+export interface ApprovalCardReasonLine {
+    readonly source: ApprovalCardReasonSource;
+    readonly text: string;
+}
+export interface ApprovalCardReasonsOptions {
+    readonly maxLines?: number;
+}
+export declare const APPROVAL_CARD_REASONS_DEFAULT_MAX_LINES = 4;
+export declare function denialLimitFallbackDetail(v: DenialLimitFallback | null | undefined): string | undefined;
+export declare function approvalCardReasons(card: object | null | undefined, opts?: ApprovalCardReasonsOptions | null): readonly ApprovalCardReasonLine[];

package/dist/hitl/approvalCardReasons.js

@@ -0,0 +1,120 @@
+import { displayUntrusted } from '../displayUntrusted.js';
+import { approvalMandateDetail, askOriginNoteOf } from '../gateVocabulary.js';
+import { readAskOrigin, readOwnDataValue, guardedRead } from '../ownKey.js';
+import { allowRuleShadowSentence } from './allowRuleShadow.js';
+import { mandatedApprovalDetailOf } from './automaticAnswerVerdict.js';
+import { approvalBoundGrantsDetail, approvalIsMandated, approvalPriorCardsDetail, askProbeReasonDetail, classifierNoRulingDetail, readApprovalBoundGrants, readApprovalClassifierNoRuling, readApprovalMandate, readDenialLimitFallback, } from './toolApprovalWire.js';
+export const APPROVAL_CARD_REASON_SOURCES = Object.freeze([
+    'payload_unreadable',
+    'prior_cards',
+    'message',
+    'mandated',
+    'mandate',
+    'origin',
+    'denial_limit',
+    'probe',
+    'allow_rule_shadow',
+    'classifier_no_ruling',
+    'bound_grants',
+    'more',
+]);
+export const APPROVAL_CARD_REASONS_DEFAULT_MAX_LINES = 4;
+const MESSAGE_DISPLAY_MAX = 300;
+const PAYLOAD_UNREADABLE_DETAIL = 'This client cannot read the format of this approval card, so only its basic facts are shown — decide from those, or deny it if you are not sure what it will do.';
+function moreDetail(n) {
+    return n === 1 ? '1 more reason for this card is not shown.' : `${String(n)} more reasons for this card are not shown.`;
+}
+export function denialLimitFallbackDetail(v) {
+    const d = readDenialLimitFallback(v);
+    if (d === undefined)
+        return undefined;
+    const parts = [
+        'auto-deny limit reached — auto mode denied enough calls on its own that the engine now wants a real human decision',
+        `${String(d.consecutive)} consecutive / ${String(d.total)} total automatic denials so far`,
+        `the limit that tripped: ${displayUntrusted(d.limit, { max: 24 })}`,
+    ];
+    if (d.autoDenyAfterMs > 0)
+        parts.push(`the engine auto-denies it in ${String(Math.round(d.autoDenyAfterMs / 1000))}s if nobody answers`);
+    return parts.join('; ');
+}
+function ownData(card, key) {
+    return guardedRead(() => readOwnDataValue(card, key));
+}
+function readMaxLines(opts) {
+    const raw = typeof opts === 'object' && opts !== null ? guardedRead(() => readOwnDataValue(opts, 'maxLines')) : undefined;
+    return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 1 ? raw : APPROVAL_CARD_REASONS_DEFAULT_MAX_LINES;
+}
+export function approvalCardReasons(card, opts) {
+    if (typeof card !== 'object' || card === null)
+        return Object.freeze([]);
+    const raw = [];
+    const add = (source, read) => {
+        let text;
+        try {
+            text = read();
+        }
+        catch {
+            text = undefined;
+        }
+        raw.push({ source, text });
+    };
+    let denialLimitReadable = false;
+    try {
+        denialLimitReadable = readDenialLimitFallback(ownData(card, 'denialLimitFallback')) !== undefined;
+    }
+    catch {
+        denialLimitReadable = false;
+    }
+    add('payload_unreadable', () => (ownData(card, 'cardPayloadUnreadable') === true ? PAYLOAD_UNREADABLE_DETAIL : undefined));
+    add('prior_cards', () => approvalPriorCardsDetail(card));
+    add('message', () => {
+        const msg = ownData(card, 'message');
+        if (typeof msg !== 'string' || msg.trim() === '')
+            return undefined;
+        const tool = ownData(card, 'toolName');
+        if (typeof tool === 'string' && msg.trim() === `approval required for "${tool}"`)
+            return undefined;
+        return displayUntrusted(msg, { max: MESSAGE_DISPLAY_MAX });
+    });
+    add('mandated', () => (approvalIsMandated(card) ? mandatedApprovalDetailOf(card) : undefined));
+    add('mandate', () => {
+        const word = readApprovalMandate(card);
+        return word !== undefined ? approvalMandateDetail(word) : undefined;
+    });
+    add('origin', () => {
+        const origin = readAskOrigin(card);
+        if (origin === undefined)
+            return undefined;
+        if (origin === 'denial_limit_fallback' && denialLimitReadable)
+            return undefined;
+        return askOriginNoteOf(origin);
+    });
+    add('denial_limit', () => denialLimitFallbackDetail(ownData(card, 'denialLimitFallback')));
+    add('probe', () => askProbeReasonDetail(card));
+    add('allow_rule_shadow', () => allowRuleShadowSentence(card));
+    add('classifier_no_ruling', () => {
+        const word = readApprovalClassifierNoRuling(card);
+        return word !== undefined ? classifierNoRulingDetail(word) : undefined;
+    });
+    add('bound_grants', () => {
+        const grants = readApprovalBoundGrants(card);
+        return grants !== undefined ? approvalBoundGrantsDetail(grants) : undefined;
+    });
+    const seen = new Set();
+    const lines = [];
+    for (const r of raw) {
+        if (r.text === undefined)
+            continue;
+        const text = displayUntrusted(r.text);
+        if (text === '' || seen.has(text))
+            continue;
+        seen.add(text);
+        lines.push(Object.freeze({ source: r.source, text }));
+    }
+    const max = readMaxLines(opts);
+    if (lines.length <= max)
+        return Object.freeze(lines);
+    const kept = lines.slice(0, max - 1);
+    kept.push(Object.freeze({ source: 'more', text: moreDetail(lines.length - kept.length) }));
+    return Object.freeze(kept);
+}

package/dist/hitl/approvalHolds.d.ts

@@ -1,15 +1,18 @@
-import type { ApprovalHolderIdentity, FsApprovalOutcome, ToolApprovalFrameOutcome } from './toolApprovalWire.js';
+import type { ApprovalHolderIdentity } from './toolApprovalWire.js';
+import type { ApprovalResolution, ApprovalResolutionLane } from './approvalResolution.js';
 export declare const APPROVAL_SETTLED_HOWS: readonly ["answered", "interrupted", "closed_by_engine"];
 export type ApprovalSettledHow = (typeof APPROVAL_SETTLED_HOWS)[number];
 export declare const SETTLED_APPROVALS_MAX_ENTRIES = 4096;
 export interface SettledApprovalEntry {
     readonly how: ApprovalSettledHow;
     readonly parked: boolean;
-    readonly outcome: ToolApprovalFrameOutcome;
+    readonly outcome: ApprovalResolution;
 }
 export interface DurableDecisionHold {
     readonly lane: 'durable';
-    readonly outcome: Promise<FsApprovalOutcome>;
+    readonly identity: HoldIdentity;
+    phase: 'card' | 'respond';
+    readonly outcome: Promise<ApprovalResolution>;
     presented: boolean;
     readonly interrupt: () => void;
     readonly cardSignal: AbortSignal;
@@ -18,7 +21,7 @@ export interface DurableDecisionHold {
 export interface LiveCardHold {
     readonly lane: 'live';
     readonly identity: LiveCardIdentity;
-    readonly outcome: Promise<ToolApprovalFrameOutcome>;
+    readonly outcome: Promise<ApprovalResolution>;
     phase: 'card' | 'respond';
     superseded?: {
         readonly parked: boolean;
@@ -27,17 +30,45 @@ export interface LiveCardHold {
     readonly interrupt: () => void;
     trailing?: Promise<boolean>;
 }
-export type ApprovalHold = DurableDecisionHold | LiveCardHold;
-export interface LiveCardIdentity {
+export interface HostCardHold {
+    readonly lane: 'host';
+    readonly identity: HoldIdentity;
+    phase: 'card' | 'respond';
+    readonly released: Promise<'answered' | 'interrupted' | undefined>;
+}
+export type ApprovalHold = DurableDecisionHold | LiveCardHold | HostCardHold;
+export interface LiveCardIdentity extends HoldIdentity {
     readonly approvalId: string;
-    readonly toolCallId?: string;
-    readonly taskId?: string;
-    readonly sessionId?: string;
 }
-export declare function liveCardHoldFor(who: ApprovalHolderIdentity): LiveCardHold | undefined;
+export interface HoldIdentity extends ApprovalHolderIdentity {
+    readonly askSig?: string;
+}
+export declare function approvalHoldFor(who: HoldIdentity, except?: (h: ApprovalHold) => boolean): ApprovalHold | undefined;
 export declare function settledForDurableLane(entry: SettledApprovalEntry | undefined): boolean;
-export declare function liveCardAnsweredHow(o: ToolApprovalFrameOutcome): 'answered' | 'interrupted' | undefined;
-export declare function awaitLiveCardHolder(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ToolApprovalFrameOutcome | undefined>;
+export declare function liveCardAnsweredHow(r: ApprovalResolution): 'answered' | 'interrupted' | undefined;
+export type ApprovalHolderWait = {
+    readonly kind: 'settled';
+    readonly how: 'answered' | 'interrupted';
+    readonly outcome: ApprovalResolution;
+} | {
+    readonly kind: 'free';
+} | {
+    readonly kind: 'left';
+};
+export declare function awaitApprovalHolder(hold: ApprovalHold, signal: AbortSignal | undefined, asker: ApprovalResolutionLane): Promise<ApprovalHolderWait>;
+export interface HostApprovalCardHold {
+    readonly identity: ApprovalHolderIdentity;
+    sending(): void;
+    release(settled?: 'answered' | 'interrupted'): void;
+}
+export type ApprovalCardClaim = {
+    readonly kind: 'held';
+    readonly hold: HostApprovalCardHold;
+} | {
+    readonly kind: 'joined';
+    readonly outcome: ApprovalResolution;
+};
+export declare function claimApprovalCardFor(who: HoldIdentity, signal: AbortSignal | undefined): Promise<ApprovalCardClaim>;
 export interface ApprovalDecisionHoldTable {
     readonly inFlight: Map<string, ApprovalHold>;
     readonly settled: Map<string, DurableSettledHold>;
@@ -54,8 +85,9 @@ export declare function settledApprovalOf(approvalId: string | undefined): Settl
 export declare function clearSettledApprovals(): void;
 export declare function anyApprovalSettled(): boolean;
 export declare function noteEngineClosedApproval(approvalId: string, parked: boolean): void;
-export declare function settledLiveCardOutcome(approvalId: string): ToolApprovalFrameOutcome | undefined;
+export declare function noteHolderSettledApproval(approvalId: string, how: 'answered' | 'interrupted', outcome: ApprovalResolution): void;
+export declare function settledLiveCardOutcome(approvalId: string): ApprovalResolution | undefined;
 export declare function liveCardHoldOf(key: string): LiveCardHold | undefined;
-export declare function holdLiveCard(identity: LiveCardIdentity, callerSignal: AbortSignal | undefined, present: (hold: LiveCardHold) => Promise<ToolApprovalFrameOutcome>): Promise<ToolApprovalFrameOutcome>;
-export declare function joinLiveCard(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ToolApprovalFrameOutcome>;
+export declare function holdLiveCard(identity: LiveCardIdentity, callerSignal: AbortSignal | undefined, present: (hold: LiveCardHold) => Promise<ApprovalResolution>): Promise<ApprovalResolution>;
+export declare function joinLiveCard(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ApprovalResolution>;
 export declare function supersedeLiveCard(key: string, parked: boolean): boolean;