@sema-agent/client-core 0.94.0 → 0.96.0

package/dist/hitl/toolApprovalWire.js

@@ -1,24 +1,27 @@
-import { APPROVAL_CARD_PORT_KEY_MISMATCH_REASON, DEFAULT_DENY_REASON, DecideTransportRetryExhaustedError, HitlBridge, NO_APPROVAL_CARD_PORT_REASON, HitlSafetyError, denyReasonForWire, findPendingForTask, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
+import { APPROVAL_CARD_PORT_KEY_MISMATCH_REASON, DEFAULT_DENY_REASON, DecideTransportRetryExhaustedError, HitlBridge, NO_APPROVAL_CARD_PORT_REASON, denyReasonForWire, findPendingForTask, hitlSafetyCodeOf, readDecideCurrentPending, readWireCodes, readWireErrorCodeReading, } from './hitlBridge.js';
 import { askParkRowArm } from './askParkRowRouting.js';
 import { hostLog } from '../host.js';
-import { readOwnDataNonEmptyString, readOwnDataValue, readOwnNonEmptyString } from '../ownKey.js';
+import { readAskOrigin, readOwnDataNonEmptyString, readOwnDataValue, readOwnNonEmptyString } from '../ownKey.js';
 import { readAskClassPair } from './askClassPair.js';
-import { legacyShadowedRuleTextOf, readAllowRuleShadowFromWire } from './allowRuleShadow.js';
+import { readAllowRuleShadowFromWire } from './allowRuleShadow.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { readEngineActiveBgTasks } from '../fleet/fleetLedger.js';
+import { CORE_SKILL_TOOL_NAME } from '../generated/toolNameTables.js';
 import { INTERRUPT_DENY_REASON, observeCancelByDeny, surfaceApprovalParking, surfaceRememberNotApplied, surfaceEditNotForwarded, surfaceEditRefusedOnBlindAsk, surfaceRuleArmNotSent, surfaceRuleArmRejected } from './hitlHostSurface.js';
 import { approvalCallKey, liveFrameCallKey } from './gateIdentity.js';
 import { displayUntrusted } from '../displayUntrusted.js';
-import { approvalDecisionHolds, holdLiveCard, joinLiveCard, liveCardHoldOf } from './approvalHolds.js';
+import { approvalDecisionHolds, awaitLiveCardHolder, holdLiveCard, joinLiveCard, liveCardHoldFor, liveCardHoldOf } from './approvalHolds.js';
 import { approvalResolutionOf } from './approvalResolution.js';
 import { isApprovalMandateWord } from '../gateVocabulary.js';
 import { denyAttributionRefusalFromError } from '../wireRefusalCopy.js';
 import { approvalDecidedByAdmitted } from '../approvalDecidedByCapability.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { wireFailureTextsOf } from '../wireFailureShape.js';
-import { refusalSaysStillPending } from '../engineErrorCodes.js';
+import { readRefusalField, thrownIsInstanceOf, wireFailureTextsOf } from '../wireFailureShape.js';
+import { refusalCauseWordOf } from './approvalEndingCause.js';
+import { readDecisionRefusalAsk } from './decisionRefusal.js';
+import { DECIDE_WORKFLOW_REMEMBER_UNSUPPORTED, refusalSaysStillPending } 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, PERSISTED_RULE_MANDATES, } 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 isFsApprovalGate(gate) {
     if (!gate)
         return false;
@@ -61,7 +64,6 @@ export function structurallyEqual(a, b) {
 export { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS };
 export { RULE_OFFERS_ABSENCE_REASONS };
 export const ASK_ORIGIN_WORDS = ASK_ORIGINS;
-export const APPROVAL_MANDATE_WORDS = PERSISTED_RULE_MANDATES;
 export const APPROVAL_DENY_SETTLED_BY_WORDS = Object.freeze(['human', 'policy']);
 export function readApprovalDenySettledBy(decision) {
     if (decision === null || typeof decision !== 'object')
@@ -132,17 +134,26 @@ function cardPortMissReason() {
         return APPROVAL_CARD_PORT_KEY_MISMATCH_REASON;
     return NO_APPROVAL_CARD_PORT_REASON;
 }
-function rememberRefusedByServer(e) {
-    switch (readWireErrorCode(e)) {
-        case 'remember_not_in_proof':
-        case 'remember_requires_binding':
-        case 'capability.store_required':
-        case 'decide.workflow_remember_unsupported':
-        case 'decide.parked_remember_unsupported':
-            return true;
-        default:
-            return false;
-    }
+const REMEMBER_REFUSAL_CODES = Object.freeze([
+    'remember_not_in_proof',
+    'remember_requires_binding',
+    'capability.store_required',
+    DECIDE_WORKFLOW_REMEMBER_UNSUPPORTED,
+    'decide.parked_remember_unsupported',
+]);
+export function rememberRefusalOf(error) {
+    return rememberRefusalIn(readWireErrorCodeReading(error));
+}
+function rememberRefusalIn(reading) {
+    return reading.state === 'code' ? REMEMBER_REFUSAL_CODES.find((c) => c === reading.code) : undefined;
+}
+function rememberFallbackKind(e) {
+    const reading = readWireErrorCodeReading(e);
+    if (rememberRefusalIn(reading) !== undefined)
+        return 'refused';
+    if (reading.state !== 'absent')
+        return undefined;
+    return readToolApprovalRespondRefusal(e)?.status === 400 ? 'legacy' : undefined;
 }
 function logAfterDecided(msg) {
     try {
@@ -157,6 +168,14 @@ const ARGS_OMITTED_PATH_RECOVERED_NOTE = 'tool arguments exceeded the wire cap a
 const ARGS_OMITTED_NOTHING_RECOVERED_NOTE = 'tool arguments exceeded the wire cap and were omitted, and nothing could be recovered from the approval question — ' +
     'you are deciding without seeing what this call will do; deny it if you are not sure. ' +
     'Edits are not accepted on this card: there is no original input to edit';
+function argsFallbackOf(message, argsOmitted) {
+    const p = pathFromGateMessage(typeof message === 'string' ? message : undefined);
+    return {
+        args: p !== undefined ? { file_path: p } : {},
+        pathRecovered: p !== undefined,
+        ...(argsOmitted === true ? { omittedNote: p !== undefined ? ARGS_OMITTED_PATH_RECOVERED_NOTE : ARGS_OMITTED_NOTHING_RECOVERED_NOTE } : {}),
+    };
+}
 const PARK_ROW_ARGS_ABSENT_NOTE = "this request's tool arguments are not available on this surface — neither the event stream nor the pending approval record " +
     'carries them, 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';
@@ -281,6 +300,13 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         return { kind: 'failed', stage: 'fetch', reason: found.reason, ...(found.code !== undefined ? { code: found.code } : {}) };
     if (held !== undefined)
         return joinDurableDecision(held, deps, signal);
+    const liveHolder = liveCardHoldFor(parkRowHolderIdentity(found.pending, found.gatedCallId));
+    if (liveHolder !== undefined) {
+        const joined = await awaitLiveCardHolder(liveHolder, signal);
+        if (joined !== undefined)
+            return fsOutcomeOfJoinedLiveCard(joined, found.gatedCallId);
+        return surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signal, parkGatedCallId);
+    }
     const callKey = approvalCallKey(found.gatedCallId, taskId);
     const fetched = found;
     return holdDurableDecision(durableHoldKey(fetched.pending, callKey), signal, async (hold) => {
@@ -290,6 +316,33 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         return out;
     });
 }
+function parkRowHolderIdentity(row, gatedCallId) {
+    return {
+        ...(typeof row.taskId === 'string' && row.taskId !== '' ? { taskId: row.taskId } : {}),
+        ...(gatedCallId !== undefined && gatedCallId !== '' ? { toolCallId: gatedCallId } : {}),
+        ...(typeof row.sessionId === 'string' && row.sessionId !== '' ? { sessionId: row.sessionId } : {}),
+    };
+}
+function fsOutcomeOfJoinedLiveCard(o, gatedCallId) {
+    if (o.aborted === true)
+        return { kind: 'aborted', gatedCallId, joinedInFlight: true };
+    if (o.decision === 'unresolved')
+        return { kind: 'retracted', gatedCallId, joinedInFlight: true };
+    return {
+        kind: 'decided',
+        gatedCallId,
+        ...(o.decision === 'deny'
+            ? {
+                denied: true,
+                ...(o.denySettledBy !== undefined ? { denySettledBy: o.denySettledBy } : {}),
+                ...(o.denyReason !== undefined ? { denyReason: o.denyReason } : {}),
+            }
+            : {}),
+        ...(o.denyAttributionDropped === true ? { denyAttributionDropped: true } : {}),
+        ...(o.denyAttributionRenamed === true ? { denyAttributionRenamed: true } : {}),
+        joinedInFlight: true,
+    };
+}
 async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, found, decidedByReading, callKey, hold, ledgerSlot) {
     const { pending, gatedCallId } = found;
     const toolName = typeof pending.toolName === 'string' ? pending.toolName : '';
@@ -314,7 +367,7 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
     const durableRuleOffersAbsence = pending.ruleOffersAbsence;
     hold.presented = true;
     deps.onPresented?.();
-    const card = await surfaceCallTrackedCard(gatedCallId, undefined, ledgerSlot, {
+    const card = await surfaceCallTrackedCard(gatedCallId, undefined, ledgerSlot, withUnreadableEvidence(pending, 'row', {
         toolName,
         args,
         callKey,
@@ -329,23 +382,24 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
         ...(pending.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
         ...(hasOwnStrictTrue(pending, 'mandated') ? { mandated: true } : {}),
         ...((w) => (w !== undefined ? { mandate: w } : {}))(readApprovalMandate(pending)),
-        ...((o) => (o !== undefined ? { origin: o } : {}))(readOwnNonEmptyString(pending, 'origin')),
+        ...((o) => (o !== undefined ? { origin: o } : {}))(readAskOrigin(pending)),
         ...(readAskClassPair(pending) ?? {}),
         ...(pending.gateKind === 'irreversible_ask' ? { irreversibleParkGate: true } : {}),
         ...(pending.hasBidiControls === true ? { hasBidiControls: true } : {}),
         ...(ruleOffersReadOnly !== undefined ? { ruleOffersReadOnly } : {}),
         ...(isWireRecordCarrier(durableProbeCause) ? { probeCause: durableProbeCause } : {}),
         ...(durableProbeReason !== undefined ? { probeReason: durableProbeReason } : {}),
-        ...(readRememberRefused(pending) ? { rememberRefused: true } : {}),
+        ...(readApprovalRememberRefused(pending) ? { rememberRefused: true } : {}),
         ...(durableShadow !== undefined ? { allowRuleShadow: durableShadow } : {}),
-        ...((t) => (t !== undefined ? { persistedRuleShadowed: t } : {}))(legacyShadowedRuleTextOf(durableShadow)),
         ...(typeof durableRuleOffersAbsence === 'string' && durableRuleOffersAbsence !== ''
             ? { ruleOffersAbsence: durableRuleOffersAbsence }
             : {}),
         ...(typeof pending.toolCallId === 'string' && pending.toolCallId !== ''
             ? { toolCallId: pending.toolCallId }
             : {}),
-    });
+        allowSessionCarried: true,
+        grantBinding: readApprovalGrantBinding(pending),
+    }));
     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)`);
         surfaceEditRefusedOnBlindAsk();
@@ -379,12 +433,11 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
                             sessionDecided = true;
                         }
                         catch (e) {
-                            if (e instanceof HitlSafetyError || e instanceof DecideTransportRetryExhaustedError)
-                                throw e;
-                            if (readDecideCurrentPending(e) !== undefined)
+                            const fallbackKind = rememberFallbackKind(e);
+                            if (fallbackKind === undefined)
                                 throw e;
-                            rememberRefused = rememberRefusedByServer(e);
-                            logAfterDecided(`liveToolApprovalWire: decide(approve+remember) failed (${String(e)}) — falling back to plain approve`);
+                            rememberRefused = fallbackKind === 'refused';
+                            logAfterDecided(`liveToolApprovalWire: decide(approve+remember) refused the remember part (${String(e)}) — falling back to plain approve`);
                         }
                         if (sessionDecided) {
                             if (sessionReceipt?.rememberApplied === false)
@@ -400,9 +453,9 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
                 }
                 catch (e) {
                     const currentPending = readDecideCurrentPending(e);
-                    const wireCode = readWireErrorCode(e);
+                    const wireCodes = readWireCodes(e);
                     const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
-                    const safetyCode = e instanceof HitlSafetyError ? e.code : undefined;
+                    const safetyCode = hitlSafetyCodeOf(e);
                     const failureTexts = wireFailureTextsOf(e);
                     hostLog('debug', `liveToolApprovalWire: decide(approve) failed: ${failureTexts.log}`);
                     return {
@@ -410,9 +463,9 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
                         stage: 'decide',
                         gatedCallId,
                         reason: `decide(approve) failed: ${failureTexts.reason}${decideFailureNote(e, 'approve')}`,
-                        ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
+                        ...(thrownIsInstanceOf(e, DecideTransportRetryExhaustedError) ? { retryExhausted: true } : {}),
                         ...(currentPending !== undefined ? { currentPending } : {}),
-                        ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
+                        ...wireCodes,
                         ...(wireRetriable ? { retriable: true } : {}),
                         ...(safetyCode !== undefined ? { safetyCode } : {}),
                     };
@@ -486,9 +539,9 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
                 }
                 catch (e) {
                     const currentPending = readDecideCurrentPending(e);
-                    const wireCode = readWireErrorCode(e);
+                    const wireCodes = readWireCodes(e);
                     const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
-                    const safetyCode = e instanceof HitlSafetyError ? e.code : undefined;
+                    const safetyCode = hitlSafetyCodeOf(e);
                     const attributionRefusal = denyAttributionRefusalFromError(e, lastSendCarriedAttribution);
                     const failureTexts = wireFailureTextsOf(e);
                     hostLog('debug', `liveToolApprovalWire: decide(deny) failed: ${failureTexts.log}`);
@@ -497,9 +550,9 @@ async function presentFsApprovalAndDecide(deps, taskId, argsByCall, signal, foun
                         stage: 'decide',
                         gatedCallId,
                         reason: `decide(deny) failed: ${failureTexts.reason}${decideFailureNote(e, 'deny')}`,
-                        ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
+                        ...(thrownIsInstanceOf(e, DecideTransportRetryExhaustedError) ? { retryExhausted: true } : {}),
                         ...(currentPending !== undefined ? { currentPending } : {}),
-                        ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
+                        ...wireCodes,
                         ...(wireRetriable ? { retriable: true } : {}),
                         ...(safetyCode !== undefined ? { safetyCode } : {}),
                         ...(attributionRefusal !== null ? { denyAttributionRefusal: attributionRefusal } : {}),
@@ -562,6 +615,7 @@ export const TOOL_APPROVAL_FRAME_KEYS_MIRROR = [
     'serverNowMs',
     'delegation',
     'outcome',
+    'cause',
 ];
 const _mirrorPin = [true, true];
 void _mirrorPin;
@@ -588,7 +642,7 @@ export function toolPermissionRequestAskBits(card) {
         return {};
     const mandated = hasOwnStrictTrue(card, 'mandated');
     const mandate = readApprovalMandate(card);
-    const origin = readOwnNonEmptyString(card, 'origin');
+    const origin = readAskOrigin(card);
     const ruleOffersAbsence = readOwnNonEmptyString(card, 'ruleOffersAbsence');
     const askClassPair = readAskClassPair(card);
     return {
@@ -597,6 +651,7 @@ export function toolPermissionRequestAskBits(card) {
         ...(origin !== undefined ? { origin } : {}),
         ...(ruleOffersAbsence !== undefined ? { ruleOffersAbsence } : {}),
         ...(askClassPair ?? {}),
+        ...(readApprovalRememberRefused(card) ? { rememberRefused: true } : {}),
     };
 }
 function hasOwnStrictTrue(v, key) {
@@ -795,10 +850,20 @@ export function readToolApprovalRespondRefusal(err) {
     const message = refusalTextOf(err, pick('message'));
     if (status === undefined && errorCode === undefined && message === undefined)
         return undefined;
+    const machine = typeof err === 'object' && err !== null ? err : undefined;
+    const retriable = machine !== undefined && refusalSaysStillPending(machine);
+    const cause = machine !== undefined ? refusalCauseWordOf(machine) : undefined;
+    const field = machine !== undefined ? readRefusalField(machine) : undefined;
+    const unreadable = machine !== undefined && readDecisionRefusalAsk(machine).reading === 'unreadable';
     const rest = {
         ...(status !== undefined ? { status } : {}),
         ...(errorCode !== undefined ? { errorCode } : {}),
         ...(message !== undefined ? { message } : {}),
+        ...(retriable ? { retriable: true } : {}),
+        ...(cause !== undefined || field !== undefined
+            ? { extra: { ...(cause !== undefined ? { cause } : {}), ...(field !== undefined ? { field } : {}) } }
+            : {}),
+        ...(unreadable ? { unreadable: true } : {}),
     };
     if (status !== undefined)
         return { ...rest, status };
@@ -864,17 +929,28 @@ function usableProbeReason(raw) {
 }
 const PROBE_CAUSE_CODE_WORD = /^[a-z][a-z0-9_]{0,31}(?:\.[a-z][a-z0-9_]{0,31}){1,3}$/;
 export function askProbeReasonDetail(card) {
-    const reason = usableProbeReason(ownDataValue(card, 'probeReason'));
-    if (reason !== undefined)
-        return displayUntrusted(reason);
-    const cause = ownDataValue(card, 'probeCause');
-    if (!isWireRecordCarrier(cause))
+    const prose = usableProbeReason(ownDataValue(card, 'probeReason'));
+    const shown = prose === undefined ? '' : displayUntrusted(prose);
+    const sentence = probeCauseSentence(ownDataValue(card, 'probeCause'), shown !== '');
+    if (sentence === undefined)
+        return shown === '' ? undefined : shown;
+    return shown === '' ? sentence : `${sentence} ${shown}`;
+}
+function probeCauseSentence(cause, withProse) {
+    try {
+        if (!isWireRecordCarrier(cause))
+            return undefined;
+        const code = ownDataValue(cause, 'code');
+        const head = withProse
+            ? 'An automatic check could not clear this call, so it is asking you'
+            : 'An automatic check could not clear this call, so it is asking you; the engine did not say the specific reason';
+        return typeof code === 'string' && PROBE_CAUSE_CODE_WORD.test(code) ? `${head} (check code: ${code}).` : `${head}.`;
+    }
+    catch {
         return undefined;
-    const code = ownDataValue(cause, 'code');
-    const head = 'An automatic check could not clear this call, so it is asking you; the engine did not say the specific reason';
-    return typeof code === 'string' && PROBE_CAUSE_CODE_WORD.test(code) ? `${head} (check code: ${code}).` : `${head}.`;
+    }
 }
-function readRememberRefused(v) {
+export function readApprovalRememberRefused(v) {
     try {
         return typeof v === 'object' && v !== null && Object.hasOwn(v, 'rememberRefused') && v.rememberRefused === true;
     }
@@ -926,6 +1002,76 @@ export function readApprovalBoundGrants(v) {
         return undefined;
     return Object.freeze({ skill, allowedTools, disallowedTools });
 }
+function readApprovalGrantBinding(carrier) {
+    if (typeof carrier !== 'object' || carrier === null)
+        return 'unreadable';
+    try {
+        if (Object.hasOwn(carrier, 'boundGrantDigest')) {
+            const digest = ownDataValue(carrier, 'boundGrantDigest');
+            return typeof digest === 'string' && digest.length > 0 ? 'bound' : 'unreadable';
+        }
+        const tool = ownDataValue(carrier, 'toolName');
+        if (typeof tool !== 'string' || tool.length === 0)
+            return 'unreadable';
+        return tool === CORE_SKILL_TOOL_NAME ? 'unreadable' : 'none';
+    }
+    catch {
+        return 'unreadable';
+    }
+}
+const UNREADABLE_EVIDENCE_KEYS = Object.freeze({
+    frame: Object.freeze([
+        ['rememberRefused', 'rememberRefused'], ['governanceForced', 'governanceForced'], ['requiresRealApproval', 'requiresRealApproval'],
+        ['mandated', 'mandated'], ['mandate', 'mandate'], ['origin', 'origin'], ['ruleOffersAbsence', 'ruleOffersAbsence'], ['ruleOffers', 'ruleOffers'],
+        ['allowRuleShadowed', 'allowRuleShadow'], ['persistedRuleShadowed', 'allowRuleShadow'], ['askClass', 'askClass'], ['classes', 'classes'],
+    ]),
+    row: Object.freeze([
+        ['rememberRefused', 'rememberRefused'], ['governanceForced', 'governanceForced'], ['requiresRealApproval', 'requiresRealApproval'],
+        ['mandated', 'mandated'], ['mandate', 'mandate'], ['origin', 'origin'], ['ruleOffersAbsence', 'ruleOffersAbsence'], ['ruleOffers', 'ruleOffersReadOnly'],
+        ['askClass', 'askClass'], ['classes', 'classes'],
+    ]),
+    v1: Object.freeze([
+        ['rememberRefused', 'rememberRefused'], ['governanceForced', 'governanceForced'], ['ruleOffersAbsence', 'ruleOffersAbsence'], ['ruleOffers', 'ruleOffersReadOnly'],
+        ['allowRuleShadowed', 'allowRuleShadow'], ['persistedRuleShadowed', 'allowRuleShadow'], ['askClass', 'askClass'], ['classes', 'classes'],
+    ]),
+});
+function carrierHas(carrier, key) {
+    if (typeof carrier !== 'object' || carrier === null)
+        return false;
+    try {
+        return key in carrier;
+    }
+    catch {
+        return true;
+    }
+}
+function v1RiskUnreadable(card) {
+    if (!carrierHas(card, 'risk'))
+        return false;
+    try {
+        const risk = card.risk;
+        return typeof risk !== 'object' || risk === null || typeof risk.requiresRealApproval !== 'boolean';
+    }
+    catch {
+        return true;
+    }
+}
+function withUnreadableEvidence(carrier, leg, req) {
+    const keys = new Set();
+    for (const [from, to] of UNREADABLE_EVIDENCE_KEYS[leg]) {
+        if (carrierHas(carrier, from) && !Object.hasOwn(req, to))
+            keys.add(from);
+    }
+    if (leg === 'row') {
+        const rd = ownDataValue(carrier, 'riskDescriptor');
+        for (const k of ['allowRuleShadowed', 'shadowedRule'])
+            if (carrierHas(rd, k) && !Object.hasOwn(req, 'allowRuleShadow'))
+                keys.add(`riskDescriptor.${k}`);
+    }
+    if (leg === 'v1' && v1RiskUnreadable(carrier))
+        keys.add('risk');
+    return keys.size === 0 ? req : { ...req, unreadableEvidence: Object.freeze([...keys].sort()) };
+}
 const CAUSE_WORD = /^[a-z][a-z0-9_]{0,63}$/;
 export function readApprovalClassifierNoRuling(v) {
     const w = ownDataValue(v, 'classifierNoRuling');
@@ -1207,20 +1353,163 @@ function subagentBadgeFor(frame) {
         name = `${name.slice(0, 31)}…`;
     return { name, color: 'cyan' };
 }
+function v1Bit(stamp) {
+    try {
+        stamp();
+    }
+    catch {
+    }
+}
+export function approvalCardFactsOfV1(card) {
+    if (typeof card !== 'object' || card === null)
+        return undefined;
+    const c = card;
+    const asFrame = card;
+    const fromSubagent = (() => {
+        try {
+            return isFromSubagent(asFrame);
+        }
+        catch {
+            return false;
+        }
+    })();
+    const argsPart = (() => {
+        try {
+            const raw = c.args !== undefined && c.args !== null ? c.args : undefined;
+            if (typeof raw === 'object' && raw !== null)
+                return { args: raw };
+            const fallback = argsFallbackOf(c.message, c.argsOmitted);
+            return { args: fallback.args, argsUnavailable: true, ...(fallback.omittedNote !== undefined ? { wireNote: fallback.omittedNote } : {}) };
+        }
+        catch {
+            return { args: {}, argsUnavailable: true };
+        }
+    })();
+    const out = { toolName: '', ...argsPart };
+    v1Bit(() => {
+        if (typeof c.toolName === 'string')
+            out.toolName = c.toolName;
+    });
+    v1Bit(() => {
+        if (typeof c.toolCallId === 'string' && c.toolCallId !== '')
+            out.toolCallId = c.toolCallId;
+    });
+    v1Bit(() => {
+        if (fromSubagent)
+            out.workerBadge = subagentBadgeFor(asFrame);
+    });
+    v1Bit(() => {
+        if (c.governanceForced === true)
+            out.governanceForced = true;
+    });
+    v1Bit(() => {
+        const d = c.delegation;
+        if (fromSubagent && isToolApprovalDelegation(d))
+            out.delegation = d;
+    });
+    v1Bit(() => {
+        const offers = readRuleOffers(c.ruleOffers);
+        if (offers !== undefined)
+            out.ruleOffersReadOnly = offers;
+    });
+    v1Bit(() => {
+        const shadow = readAllowRuleShadowFromWire(card, 'frame');
+        if (shadow !== undefined)
+            out.allowRuleShadow = shadow;
+    });
+    v1Bit(() => {
+        const pc = c.probeCause;
+        if (isWireRecordCarrier(pc))
+            out.probeCause = pc;
+    });
+    v1Bit(() => {
+        if (readApprovalRememberRefused(card))
+            out.rememberRefused = true;
+    });
+    v1Bit(() => {
+        const re = c.ruleEvidence;
+        if (isWireRecordCarrier(re))
+            out.ruleEvidence = re;
+    });
+    v1Bit(() => {
+        const risk = c.risk;
+        if (typeof risk === 'object' && risk !== null && risk.requiresRealApproval === true)
+            out.requiresRealApproval = true;
+    });
+    v1Bit(() => {
+        if (c.inputHasBidi === true)
+            out.inputHasBidi = true;
+    });
+    v1Bit(() => {
+        const w = c.ruleOffersAbsence;
+        if (typeof w === 'string' && w !== '')
+            out.ruleOffersAbsence = w;
+    });
+    v1Bit(() => {
+        const dlf = readDenialLimitFallback(c.denialLimitFallback);
+        if (dlf !== undefined)
+            out.denialLimitFallback = dlf;
+    });
+    v1Bit(() => {
+        const pair = readAskClassPair(card);
+        if (pair !== undefined) {
+            out.askClass = pair.askClass;
+            out.classes = pair.classes;
+        }
+    });
+    out.grantBinding = readApprovalGrantBinding(card);
+    return Object.freeze(withUnreadableEvidence(card, 'v1', out));
+}
 const MAX_RESPOND_NOTE_CHARS = 2048;
-export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamArgs, signal, lane) {
+export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamArgs, signal, lane, run) {
     const approvalId = frame.approvalId;
-    const key = liveFrameCallKey(approvalId);
-    const held = liveCardHoldOf(key);
+    const held = liveCardHoldOf(liveFrameCallKey(approvalId));
     if (held !== undefined)
         return joinLiveCard(held, signal);
-    return holdLiveCard(key, signal, async (hold) => {
+    return holdLiveCard(liveCardIdentityOf(approvalId, frame, run), signal, async (hold) => {
         const slot = {};
         const out = await presentToolApprovalFrameAndRespond(frame, approvalId, respond, streamArgs, signal, lane, hold, slot);
         noteCallOutcome(slot, out);
         return out;
     });
 }
+function liveCardIdentityOf(approvalId, frame, run) {
+    const toolCallId = typeof frame.toolCallId === 'string' && frame.toolCallId !== '' ? frame.toolCallId : undefined;
+    const fromSubagent = isFromSubagent(frame);
+    const ownRun = fromSubagent ? frame.sourceTaskId : run?.taskId;
+    const taskId = typeof ownRun === 'string' && ownRun !== '' ? ownRun : undefined;
+    const sessionId = !fromSubagent && typeof run?.sessionId === 'string' && run.sessionId !== '' ? run.sessionId : undefined;
+    return {
+        approvalId,
+        ...(toolCallId !== undefined ? { toolCallId } : {}),
+        ...(taskId !== undefined ? { taskId } : {}),
+        ...(sessionId !== undefined ? { sessionId } : {}),
+    };
+}
+function readApprovalHolderIdentity(v) {
+    if (typeof v !== 'object' || v === null)
+        return {};
+    const out = {};
+    try {
+        for (const k of ['approvalId', 'taskId', 'toolCallId', 'sessionId']) {
+            const d = Object.getOwnPropertyDescriptor(v, k);
+            const x = d !== undefined && Object.hasOwn(d, 'value') ? d.value : undefined;
+            if (typeof x === 'string' && x !== '')
+                out[k] = x;
+        }
+    }
+    catch {
+        return {};
+    }
+    return out;
+}
+export async function joinApprovalHolder(identity, signal) {
+    const hold = liveCardHoldFor(readApprovalHolderIdentity(identity));
+    if (hold === undefined)
+        return { kind: 'free' };
+    const joined = await awaitLiveCardHolder(hold, signal);
+    return joined !== undefined ? { kind: 'joined', outcome: joined } : { kind: 'free' };
+}
 async function presentToolApprovalFrameAndRespond(frame, approvalId, respond, streamArgs, signal, lane, hold, ledgerSlot) {
     const frameToolCallId = typeof frame.toolCallId === 'string' && frame.toolCallId !== '' ? frame.toolCallId : undefined;
     const decidedByReading = decidedByReadingSnapshotOf(lane);
@@ -1234,11 +1523,11 @@ async function presentToolApprovalFrameAndRespond(frame, approvalId, respond, st
     let argsFallback = false;
     if (typeof args !== 'object' || args === null) {
         argsFallback = true;
-        const p = pathFromGateMessage(frame.message);
-        args = p !== undefined ? { file_path: p } : {};
-        if (frame.argsOmitted === true) {
-            wireNote = p !== undefined ? ARGS_OMITTED_PATH_RECOVERED_NOTE : ARGS_OMITTED_NOTHING_RECOVERED_NOTE;
-            hostLog('debug', `liveToolApprovalWire: frame ${approvalId} args omitted (>16KiB wire cap) — card falls back to ${p !== undefined ? 'the message-derived path' : 'an empty input (no path could be derived from the message)'}`);
+        const fallback = argsFallbackOf(frame.message, frame.argsOmitted);
+        args = fallback.args;
+        if (fallback.omittedNote !== undefined) {
+            wireNote = fallback.omittedNote;
+            hostLog('debug', `liveToolApprovalWire: frame ${approvalId} args omitted (>16KiB wire cap) — card falls back to ${fallback.pathRecovered ? 'the message-derived path' : 'an empty input (no path could be derived from the message)'}`);
         }
         if (lane?.argsUnavailable === true) {
             wireNote =
@@ -1251,7 +1540,7 @@ async function presentToolApprovalFrameAndRespond(frame, approvalId, respond, st
     const ruleOffers = readRuleOffers(frame.ruleOffers);
     const denialLimitFallback = readDenialLimitFallback(frame.denialLimitFallback);
     const frameShadow = readAllowRuleShadowFromWire(frame, 'frame');
-    const card = await surfaceCallTrackedCard(frameToolCallId, approvalId, ledgerSlot, {
+    const card = await surfaceCallTrackedCard(frameToolCallId, approvalId, ledgerSlot, withUnreadableEvidence(frame, 'frame', {
         toolName,
         args: args,
         callKey: liveFrameCallKey(approvalId),
@@ -1278,10 +1567,9 @@ async function presentToolApprovalFrameAndRespond(frame, approvalId, respond, st
             : {}),
         ...(ruleOffers !== undefined ? { ruleOffers } : {}),
         ...((sh) => (sh !== undefined ? { allowRuleShadow: sh } : {}))(frameShadow),
-        ...((t) => (t !== undefined ? { persistedRuleShadowed: t } : {}))(legacyShadowedRuleTextOf(frameShadow)),
         ...(isWireRecordCarrier(frame.probeCause) ? { probeCause: frame.probeCause } : {}),
         ...((r) => (r !== undefined ? { probeReason: r } : {}))(readProbeReason(frame)),
-        ...(readRememberRefused(frame) ? { rememberRefused: true } : {}),
+        ...(readApprovalRememberRefused(frame) ? { rememberRefused: true } : {}),
         ...(isWireRecordCarrier(frame.ruleEvidence) ? { ruleEvidence: frame.ruleEvidence } : {}),
         ...(frame.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
         ...(hasOwnStrictTrue(frame, 'mandated') ? { mandated: true } : {}),
@@ -1292,11 +1580,13 @@ async function presentToolApprovalFrameAndRespond(frame, approvalId, respond, st
             ? { ruleOffersAbsence: frame.ruleOffersAbsence }
             : {}),
         ...(denialLimitFallback !== undefined ? { denialLimitFallback } : {}),
-        ...((o) => (o !== undefined ? { origin: o } : {}))(readOwnNonEmptyString(frame, 'origin')),
+        ...((o) => (o !== undefined ? { origin: o } : {}))(readAskOrigin(frame)),
         ...(readAskClassPair(frame) ?? {}),
         ...((g) => (g !== undefined ? { boundGrants: g } : {}))(readApprovalBoundGrants(frame)),
         ...((w) => (w !== undefined ? { classifierNoRuling: w } : {}))(readApprovalClassifierNoRuling(frame)),
-    });
+        allowSessionCarried: true,
+        grantBinding: readApprovalGrantBinding(frame),
+    }));
     if (hold.superseded !== undefined) {
         hostLog('debug', `liveToolApprovalWire: ${approvalId} was settled by the engine while its card was up${hold.superseded.parked ? ' (parked)' : ''} — card withdrawn; ` +
             `the card came back ${card.kind}; nothing sent`);

package/dist/hookMatcherVerdict.d.ts

@@ -3,15 +3,7 @@ export type HookMatcherVerdict = {
     readonly kind: 'matchesAll';
 } | {
     readonly kind: 'accepted';
-    readonly reading: 'names';
-    readonly names: readonly string[];
-    readonly aliases: readonly {
-        readonly alias: string;
-        readonly canonical: string;
-    }[];
-} | {
-    readonly kind: 'accepted';
-    readonly reading: 'pattern';
+    readonly reading: 'names' | 'pattern';
     readonly aliases: readonly {
         readonly alias: string;
         readonly canonical: string;