@sema-agent/client-core 0.112.1 → 0.113.0

package/dist/hitl/toolApprovalWire.d.ts

@@ -6,6 +6,8 @@ import { type ApprovalAllowRuleShadow } from './allowRuleShadow.js';
 import { CORE_PERSISTED_RULE_MATCHES } from '../generated/engineFactTables.js';
 import type { UiLanguage } from '../env/uiLanguage.js';
 import type { SessionRuleInertReason } from './sessionPolicyWire.js';
+import type { LegacyToolApprovalFrame, LegacyToolApprovalRespondAck, LegacyToolApprovalRespondApplied, LegacyToolApprovalRespondReplayed } from './legacyApprovalShapes.js';
+import { type ApprovalDecisionDoorReading, type AskDoorDecisionBody } from './approvalDecisionDoor.js';
 import { type ApprovalCardClaim } from './approvalHolds.js';
 import { type ApprovalResolution } from './approvalResolution.js';
 import { type HostWithdrawal } from './hostWithdrawal.js';
@@ -15,7 +17,7 @@ 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';
+import type { ApprovalDecidedBy, ApprovalCardDelegation, PersistedRuleAnchor, RuleOfferMatch, RuleOfferBatchMember, RuleOfferUncoveredDetail, RuleOfferUncoveredReason, AskOrigin, RuleOffersAbsence, DenialLimitKind, DenialLimitFallback, ApprovalRequestFrame, RuleOffer as SdkRuleOffer } from '@sema-agent/sdk';
 export declare function toolNameIsFsWrite(name: string): boolean;
 export declare function toolNameIsShellExec(name: string): boolean;
 export interface ToolApprovalGateLike {
@@ -183,13 +185,15 @@ export declare function surfaceApprovalCard(req: ApprovalCardRequest): Promise<A
 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 const FEEDBACK_REFUSAL_CODES: readonly ["feedback_not_in_proof"];
+export declare function feedbackRefusalOf(error: unknown): boolean;
 export declare function surfaceFsApprovalAndDecide(deps: FsApprovalWireDeps, taskId: string, argsByCall: Map<string, unknown>, signal?: AbortSignal, parkGatedCallId?: string, parkToolName?: string): Promise<ApprovalResolution>;
 export interface BoundSkillGrantsWire {
     readonly skill: string | null;
     readonly allowedTools: readonly string[];
     readonly disallowedTools: readonly string[];
 }
-export type { ToolApprovalFrame };
+export type { LegacyToolApprovalFrame, LegacyToolApprovalRespondAck };
 export interface ReadRootCandidateView {
     dir: string;
     clearsThisAsk: true;
@@ -208,8 +212,8 @@ export declare function readApprovalMandate(v: {
 } | undefined | null): ApprovalMandateWord | undefined;
 export { readApprovalCardWord };
 export declare function toolPermissionRequestAskBits(card: object | null | undefined, requestId?: string): Pick<ToolPermissionRequest, 'mandated' | 'mandate' | 'origin' | 'ruleOffersAbsence' | 'askClass' | 'classes' | 'sessionRow' | 'probeReason' | 'probeCause' | 'feedbackCapable' | 'requestedBy' | 'frameReading' | 'inputSource'>;
-export declare function isFromSubagent(frame: ToolApprovalFrame): boolean;
-export type ToolApprovalRespondDecision = SdkToolApprovalDecision;
+export declare function isFromSubagent(frame: LegacyToolApprovalFrame): boolean;
+export type ToolApprovalRespondDecision = (typeof RESPOND_DECISIONS)[number];
 export declare const RESPOND_DECISIONS: readonly ["allow", "allow_session", "deny"];
 export type AnswerPayloadLane = 'respond' | 'decide';
 export interface AnswerPayloadCaps {
@@ -259,8 +263,8 @@ export interface RespondToolApprovalOpts {
     settledBy?: 'policy';
     decidedBy?: Extract<ApprovalDecidedBy, 'policy'>;
 }
-export type RespondToolApprovalFn = (approvalId: string, decision: ToolApprovalRespondDecision, opts?: RespondToolApprovalOpts) => Promise<ToolApprovalRespondAck | void>;
-export type ToolApprovalRespondAckView = ToolApprovalRespondAck | ToolApprovalRespondRedeemedView;
+export type RespondToolApprovalFn = (approvalId: string, decision: ToolApprovalRespondDecision, opts?: RespondToolApprovalOpts) => Promise<LegacyToolApprovalRespondAck | void>;
+export type ToolApprovalRespondAckView = LegacyToolApprovalRespondAck | ToolApprovalRespondRedeemedView;
 export interface ToolApprovalRespondRedeemedView {
     readonly approvalId: string;
     readonly askId: string;
@@ -269,12 +273,24 @@ export interface ToolApprovalRespondRedeemedView {
     readonly decision?: string;
     readonly rememberApplied?: boolean;
 }
-export declare function isToolApprovalRespondReplayed(ack: ToolApprovalRespondAckView): ack is ToolApprovalRespondReplayed;
+export declare function isToolApprovalRespondReplayed(ack: ToolApprovalRespondAckView): ack is LegacyToolApprovalRespondReplayed;
 export declare function isToolApprovalRespondParkedRedeemed(ack: object): ack is ToolApprovalRespondRedeemedView;
 export declare function replayedFirstDecisionOf(ack: ToolApprovalRespondAckView | undefined): 'allow' | 'deny' | undefined;
 export declare function settlementAckOf(read: ToolApprovalRespondAckView | undefined): ToolApprovalRespondAckView | undefined;
 export type { PersistedRuleAnchor };
 export declare function readToolApprovalRespondAck(v: unknown): ToolApprovalRespondAckView | undefined;
+export type AskDoorDecisionBodyReading = {
+    readonly kind: 'receipt';
+    readonly ack: LegacyToolApprovalRespondApplied;
+} | {
+    readonly kind: 'earlier';
+    readonly firstDecision: 'allow' | 'deny';
+} | {
+    readonly kind: 'other_ask';
+} | {
+    readonly kind: 'none';
+};
+export declare function readAskDoorDecisionBody(v: {} | null | undefined, askId: string, sent: ToolApprovalRespondDecision): AskDoorDecisionBodyReading;
 export interface ToolApprovalRespondParkingView {
     readonly approvalId: string;
     readonly retryAfterMs?: number;
@@ -312,7 +328,7 @@ export declare function decisionAttributionKeyOf(reading: ApprovalDecidedByReadi
 } | {
     settledBy: 'policy';
 } | Record<never, never>;
-export declare function isToolApprovalFrame(ev: unknown): ev is ToolApprovalFrame;
+export declare function isToolApprovalFrame(ev: unknown): ev is LegacyToolApprovalFrame;
 export declare function askProbeReasonDetail(card: Pick<ApprovalCardRequest, 'probeReason' | 'probeCause'> | null | undefined, lang?: UiLanguage): string | undefined;
 export declare function readApprovalRememberRefused(v: unknown): boolean;
 export declare function readApprovalBoundGrants(v: unknown): BoundSkillGrantsWire | undefined;
@@ -332,6 +348,10 @@ 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 declare function subagentBadgeFor(carrier: object | null | undefined): {
+    name: string;
+    color: string;
+};
 export type ApprovalCardV1Facts = Pick<ApprovalCardRequest, 'toolName' | 'args'> & Pick<ApprovalCardRequest, 'toolCallId' | 'workerBadge' | 'wireNote' | 'argsUnavailable' | 'inputSource' | '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' | 'requestedBy'>;
 export interface ApprovalCardFrameFactsOptions {
@@ -349,6 +369,7 @@ export interface ToolApprovalFrameLaneOpts {
     respondFreeFormRulesCapable?: boolean;
     respondBatchRuleOffersCapable?: boolean;
     approvalDecidedBy?: ApprovalDecidedByReading | undefined;
+    approvalDecisionDoor?: ApprovalDecisionDoorReading | undefined;
     windowIsCurrent?: boolean;
     argsUnavailable?: true;
 }
@@ -357,8 +378,11 @@ export interface ToolApprovalFrameRunBits {
     readonly sessionId?: string;
     readonly sourceGeneration?: number;
 }
-export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame | ApprovalRequestFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts, run?: ToolApprovalFrameRunBits): 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: ToolApprovalFrameRunBits | undefined): Promise<ApprovalResolution>;
+export declare function surfaceToolApprovalFrameAndRespond(frame: LegacyToolApprovalFrame | ApprovalRequestFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts, run?: ToolApprovalFrameRunBits): Promise<ApprovalResolution>;
+export declare function surfaceApprovalFrameWithId(frame: LegacyToolApprovalFrame | ApprovalRequestFrame, approvalId: string, respond: RespondToolApprovalFn, streamArgs: Parameters<typeof surfaceToolApprovalFrameAndRespond>[2], signal: AbortSignal | undefined, lane: ToolApprovalFrameLaneOpts | undefined, run: ToolApprovalFrameRunBits | undefined): Promise<ApprovalResolution>;
+export declare function askDoorBodyOf(decision: ToolApprovalRespondDecision, o: RespondToolApprovalOpts, askId: string): AskDoorDecisionBody & {
+    readonly settledBy?: 'policy';
+};
 export interface ApprovalHolderIdentity {
     readonly approvalId?: string;
     readonly taskId?: string;

package/dist/hitl/toolApprovalWire.js

@@ -22,7 +22,8 @@ import { approvalCallKey, liveFrameCallKey } from './gateIdentity.js';
 import { displayUntrusted, quoteUntrustedForSentence } from '../displayUntrusted.js';
 import { frameBindingOf } from '../frameBinding.js';
 import { carriesAttributionKey, deliverWithAttributionLadder } from './attributionLadder.js';
-import { deliverApprovalDecision, newSendTally } from './approvalDelivery.js';
+import { askDoorParkingOfThrown, deliverApprovalDecision, isAborted, newSendTally, respondRouteGoneOf } from './approvalDelivery.js';
+import { approvalDecisionDoorOf, approvalDecisionVerbOf, hitlAskIdempotencyKey, noteRespondDoorSwitch, ROUTE_MISSING_WIRING_HINT } from './approvalDecisionDoor.js';
 import { approvalDecisionHolds, approvalHoldFor, awaitApprovalHolder, claimApprovalCardFor, enterLiveRespondPhase, holdLiveCard, joinLiveCard, liveCardHoldOf, clearSettledApprovals, noteHolderSettledApproval, settledApprovalOf, settledForDurableLane, settledLiveCardOutcome } from './approvalHolds.js';
 import { directFailureVerdictOf, directSafetyStopOf, joinedResolution, resolutionOfDecisionFailure, toolPermissionSettledElsewhereOf } from './approvalResolution.js';
 import { hostWithdrawalOf } from './hostWithdrawal.js';
@@ -186,8 +187,8 @@ export function rememberRefusalOf(error) {
 function rememberRefusalIn(reading) {
     return reading.state === 'code' ? REMEMBER_REFUSAL_CODES.find((c) => c === reading.code) : undefined;
 }
-const FEEDBACK_REFUSAL_CODES = Object.freeze(['feedback_not_in_proof']);
-function feedbackRefusalOf(error) {
+export const FEEDBACK_REFUSAL_CODES = Object.freeze(['feedback_not_in_proof']);
+export function feedbackRefusalOf(error) {
     const reading = readWireErrorCodeReading(error);
     return reading.state === 'code' && FEEDBACK_REFUSAL_CODES.some((c) => c === reading.code);
 }
@@ -863,8 +864,6 @@ export function isFromSubagent(frame) {
     return frame.fromSubagent === true;
 }
 export const RESPOND_DECISIONS = Object.freeze(['allow', 'allow_session', 'deny']);
-const _respondDecisionPins = [true, true];
-void _respondDecisionPins;
 function isRespondDecision(v) {
     return typeof v === 'string' && RESPOND_DECISIONS.includes(v);
 }
@@ -985,6 +984,9 @@ export function readToolApprovalRespondAck(v) {
         return undefined;
     if (!isRespondDecision(decision))
         return undefined;
+    return appliedReceiptOf(s, approvalId, decision);
+}
+function appliedReceiptOf(s, approvalId, decision) {
     const rememberApplied = slotValueOf(s.rememberApplied);
     const updatedInputForwarded = slotValueOf(s.updatedInputForwarded);
     const rulePersisted = slotValueOf(s.rulePersisted);
@@ -996,7 +998,7 @@ export function readToolApprovalRespondAck(v) {
     const out = {
         approvalId,
         delivery: 'applied',
-        decision: decision,
+        decision,
         ...(typeof rememberApplied === 'boolean' ? { rememberApplied } : {}),
         ...(typeof updatedInputForwarded === 'boolean' ? { updatedInputForwarded } : {}),
         ...(typeof rulePersisted === 'boolean' ? { rulePersisted } : {}),
@@ -1027,6 +1029,26 @@ export function readToolApprovalRespondAck(v) {
     }
     return out;
 }
+export function readAskDoorDecisionBody(v, askId, sent) {
+    if (v === null || typeof v !== 'object')
+        return Object.freeze({ kind: 'none' });
+    const s = respondAckSlotsOf(v);
+    const want = sent === 'deny' ? 'deny' : 'approve';
+    const idOk = typeof askId === 'string' && askId !== '' && slotValueOf(s.askId) === askId;
+    const dec = slotValueOf(s.decision);
+    if (s.askId.presence !== 'absent' && !idOk)
+        return Object.freeze({ kind: 'other_ask' });
+    if (s.decision.presence !== 'absent' && dec !== want) {
+        return idOk && (dec === 'approve' || dec === 'deny') ? Object.freeze({ kind: 'earlier', firstDecision: dec === 'approve' ? 'allow' : 'deny' }) : Object.freeze({ kind: 'other_ask' });
+    }
+    if (s.accepted.presence !== 'absent' || s.idempotent.presence !== 'absent' || s.delivery.presence !== 'absent')
+        return Object.freeze({ kind: 'none' });
+    if (idOk && dec === want) {
+        const ack = appliedReceiptOf(s, askId, sent);
+        return ack !== undefined ? Object.freeze({ kind: 'receipt', ack }) : Object.freeze({ kind: 'none' });
+    }
+    return Object.freeze({ kind: 'none' });
+}
 const RESPOND_ACK_SLOT_KEYS = [
     'accepted',
     'idempotent',
@@ -1120,6 +1142,7 @@ function ownIdempotentTrue(raw) {
         return false;
     }
 }
+const REPLAY_NONE = Object.freeze({ kind: 'none' });
 export function replayVerdictFrom(raw, parsed, approvalId) {
     if (parsed !== undefined && isToolApprovalRespondReplayed(parsed) && parsed.approvalId === approvalId)
         return { kind: 'replayed', firstDecision: parsed.decision, via: 'arm' };
@@ -1506,7 +1529,7 @@ const UNREADABLE_EVIDENCE_KEYS = Object.freeze({
     ]),
     v1: Object.freeze([
         ['rememberRefused', 'rememberRefused'], ['governanceForced', 'governanceForced'], ['requiresRealApproval', 'requiresRealApproval'],
-        ['ruleOffersAbsence', 'ruleOffersAbsence'], ['ruleOffers', 'ruleOffersReadOnly'],
+        ['ruleOffersAbsence', 'ruleOffersAbsence'], ['ruleOffers', ['ruleOffersReadOnly', 'ruleOffers']],
         ['allowRuleShadowed', 'allowRuleShadow'], ['askClass', 'askClass'], ['classes', 'classes'],
     ]),
     generic: Object.freeze([['ruleOffersAbsence', 'ruleOffersAbsence'], ['askClass', 'askClass'], ['classes', 'classes']]),
@@ -1525,7 +1548,8 @@ function riskSubtreeUnreadable(card) {
 function withUnreadableEvidence(carrier, leg, req, reported = [], live) {
     const keys = new Set(reported);
     for (const [from, to] of UNREADABLE_EVIDENCE_KEYS[leg]) {
-        if (slotPresenceOf(carrier, from) !== 'absent' && !Object.hasOwn(req, to))
+        const read = typeof to === 'string' ? Object.hasOwn(req, to) : to.some((t) => Object.hasOwn(req, t));
+        if (slotPresenceOf(carrier, from) !== 'absent' && !read)
             keys.add(from);
     }
     if (live !== undefined) {
@@ -1715,6 +1739,7 @@ function noteCallOutcome(slot, r) {
     const unsettledFate = {
         engine_refused: 'not_accepted',
         parking_in_progress: 'not_accepted',
+        route_missing: 'not_accepted',
         engine_error: 'unconfirmed',
         no_answer: 'unconfirmed',
         transport_exhausted: 'unconfirmed',
@@ -1921,17 +1946,18 @@ export function readRuleOffers(v) {
 export function readRuleOfferSupply(offers) {
     return readRuleOffers(offers);
 }
-function subagentBadgeFor(frame) {
-    let name = typeof frame.sourceAgentName === 'string' && frame.sourceAgentName.length > 0 ? frame.sourceAgentName : '';
-    const source = subagentSourceSessionOf(frame);
-    if (!name && source !== undefined) {
-        name = source;
-        try {
-            const row = readEngineActiveBgTasks().tasks.find(t => t.id === source);
-            if (typeof row?.name === 'string' && row.name.length > 0)
-                name = row.name;
-        }
-        catch {
+export function subagentBadgeFor(carrier) {
+    let name = guardedRead(() => readOwnDataNonEmptyString(carrier, 'sourceAgentName')) ?? '';
+    if (!name) {
+        const agentId = approvalAgentIdOf(carrier);
+        if (agentId !== undefined) {
+            try {
+                const row = readEngineActiveBgTasks().tasks.find(t => t.id === agentId);
+                if (typeof row?.name === 'string' && row.name.length > 0)
+                    name = row.name;
+            }
+            catch {
+            }
         }
     }
     if (!name)
@@ -2011,7 +2037,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, payloadWhy) {
+function cardFactsOf(carrier, leg, opts, liveFacts, approvalId, payloadWhy, rulesRedeemable) {
     const c = carrier;
     const full = leg !== 'generic';
     const live = leg === 'frame' ? carrier : leg === 'v1' ? liveFacts : undefined;
@@ -2093,7 +2119,7 @@ function cardFactsOf(carrier, leg, opts, liveFacts, approvalId, payloadWhy) {
             const offers = readRuleOffers(c.ruleOffers);
             if (offers === undefined)
                 return;
-            if (leg === 'frame')
+            if (leg === 'frame' || (leg === 'v1' && rulesRedeemable === true))
                 out.ruleOffers = offers;
             else
                 out.ruleOffersReadOnly = offers;
@@ -2263,12 +2289,95 @@ export async function surfaceApprovalFrameWithId(frame, approvalId, respond, str
     if (typeof approvalId !== 'string' || approvalId === '')
         return approvalIdUnreadableRefusal();
     const carriers = openingFrameCarriersOf(frame);
+    const route = askDoorRouteOf(lane, carriers, frame, approvalId, respond);
+    if (route.kind === 'refused')
+        return route.resolution;
     const liveRun = liveCardRunOf(frame, run);
     const sourceGenerationRaw = guardedRead(() => readOwnDataValue(run, 'sourceGeneration'));
     const sourceGeneration = typeof sourceGenerationRaw === 'number' && Number.isFinite(sourceGenerationRaw) ? sourceGenerationRaw : undefined;
-    const entry = { frame, carriers, approvalId, identity: liveCardIdentityOf(approvalId, carriers, liveRun), respond, streamArgs, signal, lane, receivedAtMs, sourceGeneration };
+    const askDoor = route.kind === 'target' ? route.target : undefined;
+    const respondSwitch = route.kind === 'respond' ? route.switchTo : undefined;
+    const entry = { frame, carriers, approvalId, identity: liveCardIdentityOf(approvalId, carriers, liveRun), respond, streamArgs, signal, lane, receivedAtMs, sourceGeneration, askDoor, respondSwitch };
     return enterLiveCard(entry);
 }
+const RESPOND_ROUTE = Object.freeze({ kind: 'respond' });
+function askDoorRouteOf(lane, carriers, frame, approvalId, respond) {
+    const reading = guardedRead(() => readOwnDataValue(lane, 'approvalDecisionDoor'));
+    const door = approvalDecisionDoorOf(reading);
+    const refused = (cause, missing) => {
+        const resolution = missing !== undefined ? { kind: 'not_sent', lane: 'respond', cause, door: missing } : { kind: 'not_sent', lane: 'respond', cause };
+        return Object.freeze({ kind: 'refused', resolution });
+    };
+    let target;
+    if (door === 'ask_decision') {
+        const blindRow = guardedRead(() => readOwnDataValue(lane, 'argsUnavailable')) === true;
+        const t = askDoorTargetOf(reading, carriers, frame, approvalId, blindRow);
+        if (t === 'card_unavailable' || t === 'card_unreadable')
+            return refused(t);
+        target = t;
+    }
+    if (door === 'ask_decision' ? target === undefined : typeof respond !== 'function') {
+        hostLog('error', door === 'ask_decision'
+            ? `liveToolApprovalWire: ${approvalId} must be answered on the ask decision door, but this host has not wired that door (approvalDecisionDoor.verbs.decideAsk) — not raised as a card, nothing sent; the request is still waiting on the engine`
+            : `liveToolApprovalWire: ${approvalId} must be answered on the respond door (the server is below the ask decision door version, or its version is unreadable), but the respond port this host passed is not a function — not raised as a card, nothing sent; the request is still waiting on the engine`);
+        return refused('no_verb', door);
+    }
+    if (target !== undefined)
+        return Object.freeze({ kind: 'target', target });
+    const addr = askDoorAddressOf(carriers, frame, approvalId);
+    const decide = 'missing' in addr ? undefined : approvalDecisionVerbOf(reading);
+    if ('missing' in addr || decide === undefined)
+        return RESPOND_ROUTE;
+    return Object.freeze({ kind: 'respond', switchTo: Object.freeze({ target: Object.freeze({ taskId: addr.taskId, askId: addr.askId, decide }), reading }) });
+}
+function askDoorAddressOf(carriers, frame, approvalId) {
+    if (carriers.leg === 'frame')
+        return { missing: 'old_family' };
+    const askId = guardedRead(() => readOwnDataNonEmptyString(frame, 'askId'));
+    const taskId = guardedRead(() => readOwnDataNonEmptyString(frame, 'taskId'));
+    if (askId === undefined)
+        return { missing: 'askId' };
+    if (taskId === undefined)
+        return { missing: 'taskId' };
+    if (askId !== approvalId)
+        return { missing: 'mismatch' };
+    return { taskId, askId };
+}
+function askDoorTargetOf(reading, carriers, frame, approvalId, blindRow) {
+    const addr = askDoorAddressOf(carriers, frame, approvalId);
+    if ('missing' in addr) {
+        if (addr.missing === 'old_family' && blindRow) {
+            hostLog('debug', `liveToolApprovalWire: ${approvalId} is a pending row whose card this host could not read, on a server that only takes the ask decision door — not raised as a card, nothing sent`);
+            return 'card_unreadable';
+        }
+        if (addr.missing === 'old_family') {
+            hostLog('debug', `liveToolApprovalWire: ${approvalId} is an old-family approval frame on a server that only takes the ask decision door — not raised as a card, nothing sent`);
+            return 'card_unavailable';
+        }
+        hostLog('debug', `liveToolApprovalWire: ${approvalId} has no usable ask identity on its frame (${addr.missing === 'mismatch' ? 'askId differs from the approval id' : addr.missing}) — the ask decision door cannot be addressed; not raised as a card, nothing sent`);
+        return 'card_unavailable';
+    }
+    const decide = approvalDecisionVerbOf(reading);
+    return decide === undefined ? undefined : Object.freeze({ taskId: addr.taskId, askId: addr.askId, decide });
+}
+export function askDoorBodyOf(decision, o, askId) {
+    const verdict = decision === 'deny' ? 'deny' : 'approve';
+    const persistRule = o.persistRuleBatchOfferIndex !== undefined
+        ? { batchOfferIndex: o.persistRuleBatchOfferIndex }
+        : o.persistRule !== undefined
+            ? { rule: o.persistRule, ...(o.persistRuleEdited === true ? { edited: true } : {}) }
+            : undefined;
+    return {
+        decision: verdict,
+        idempotencyKey: hitlAskIdempotencyKey(askId, verdict),
+        ...(decision === 'allow_session' ? { remember: 'session' } : {}),
+        ...(verdict === 'approve' && o.updatedInput !== undefined ? { updatedInput: o.updatedInput } : {}),
+        ...(o.note !== undefined ? { note: o.note } : {}),
+        ...(verdict === 'approve' && persistRule !== undefined ? { persistRule } : {}),
+        ...(o.decidedBy !== undefined ? { decidedBy: o.decidedBy } : {}),
+        ...(o.settledBy !== undefined ? { settledBy: o.settledBy } : {}),
+    };
+}
 function openingFrameCarriersOf(frame) {
     if (frame.type !== 'approval_request')
         return { body: frame, live: frame, leg: 'frame' };
@@ -2292,7 +2401,7 @@ function enterLiveCard(e) {
         return joinOtherLaneHolder(e, other);
     return holdLiveCard(e.identity, signal, async (hold) => {
         const slot = {};
-        const out = await presentToolApprovalFrameAndRespond(e.frame, e.carriers, approvalId, e.respond, e.streamArgs, signal, e.lane, hold, slot, e.receivedAtMs, e.identity.taskId, e.sourceGeneration);
+        const out = await presentToolApprovalFrameAndRespond(e.frame, e.carriers, approvalId, e.respond, e.streamArgs, signal, e.lane, hold, slot, e.receivedAtMs, e.identity.taskId, e.sourceGeneration, e.askDoor, e.respondSwitch);
         noteCallOutcome(slot, out);
         return out;
     });
@@ -2376,11 +2485,12 @@ function readApprovalCardClaimSignal(v) {
 export function claimApprovalCard(identity, options) {
     return claimApprovalCardFor(readApprovalHolderIdentity(identity), readApprovalCardClaimSignal(options));
 }
-async function presentToolApprovalFrameAndRespond(frame, carriers, approvalId, respond, streamArgs, signal, lane, hold, ledgerSlot, receivedAtMs, cardTaskId, sourceGeneration) {
+async function presentToolApprovalFrameAndRespond(frame, carriers, approvalId, respond, streamArgs, signal, lane, hold, ledgerSlot, receivedAtMs, cardTaskId, sourceGeneration, entryAskDoor, respondSwitch) {
+    let askDoor = entryAskDoor;
     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, carriers.why);
+    const facts = cardFactsOf(carriers.body, carriers.leg, { streamArgs, ...(lane?.argsUnavailable === true ? { argsUnavailable: true } : {}) }, carriers.live, approvalId, carriers.why, askDoor !== undefined);
     const argsNotRealInput = facts.argsUnavailable === true;
     const editAcceptance = editedApprovalAcceptanceOf(facts);
     const ruleOffers = facts.ruleOffers;
@@ -2416,16 +2526,36 @@ async function presentToolApprovalFrameAndRespond(frame, carriers, approvalId, r
         const p = readToolApprovalRespondParking(body);
         return p?.kind === 'parking' ? p.view : undefined;
     };
-    const deliverOnThisCard = (d, body, carrySignal, deliverySignal, ladder, onLadderStep) => deliverApprovalDecision({
+    const noParkingBody = () => undefined;
+    const parkingInProgress = (parking) => ({ kind: 'unsettled', lane: 'respond', cause: 'parking_in_progress', parking });
+    const deliverVia = (door, d, body, carrySignal, deliverySignal, ladder, onLadderStep) => deliverApprovalDecision({
         approvalId,
         body,
-        send: (o, sig) => respond(approvalId, d, carrySignal && sig !== undefined ? { ...o, signal: sig } : o),
+        send: (o, sig) => door !== undefined
+            ? door.decide(door.taskId, door.askId, askDoorBodyOf(d, o, door.askId), carrySignal && sig !== undefined ? { signal: sig } : undefined)
+            : respond(approvalId, d, carrySignal && sig !== undefined ? { ...o, signal: sig } : o),
         signal: deliverySignal,
         tally: newSendTally(),
         ladder,
         ...(onLadderStep !== undefined ? { onLadderStep } : {}),
-        parkingOf: respondParkingOf,
+        parkingOf: door !== undefined ? noParkingBody : respondParkingOf,
+        ...(door !== undefined ? { parkingOfThrown: (reading) => askDoorParkingOfThrown(reading, approvalId) } : {}),
     });
+    const deliverOnThisCard = (d, body, carrySignal, deliverySignal, ladder, onLadderStep) => {
+        const first = deliverVia(askDoor, d, body, carrySignal, deliverySignal, ladder, onLadderStep);
+        const sw = respondSwitch;
+        if (askDoor !== undefined || sw === undefined)
+            return first;
+        return first.then((delivery) => {
+            if (delivery.kind !== 'thrown' || !respondRouteGoneOf(delivery))
+                return delivery;
+            noteRespondDoorSwitch(sw.reading, 'liveToolApprovalWire', approvalId);
+            if (isAborted(deliverySignal))
+                return delivery;
+            askDoor = sw.target;
+            return deliverVia(sw.target, d, body, carrySignal, deliverySignal, ladder, onLadderStep);
+        });
+    };
     if (card.kind === 'aborted') {
         enterLiveRespondPhase(hold);
         const interruptOpts = lane?.approvalDecisionNoteCapable === true ? { note: INTERRUPT_DENY_REASON } : {};
@@ -2579,7 +2709,7 @@ async function presentToolApprovalFrameAndRespond(frame, carriers, approvalId, r
         }
         const attributionDropped = ladder.dropped;
         const attributionRenamed = ladder.renamed;
-        const parkingBody = readToolApprovalRespondParking(raw);
+        const parkingBody = askDoor === undefined ? readToolApprovalRespondParking(raw) : undefined;
         if (parkingBody !== undefined) {
             const parking = parkingBody.kind === 'parking' && parkingBody.view.approvalId === approvalId ? parkingBody.view : undefined;
             if (parking !== undefined) {
@@ -2588,14 +2718,23 @@ async function presentToolApprovalFrameAndRespond(frame, carriers, approvalId, r
                 hostLog('debug', `liveToolApprovalWire: respond(${decision}) for ${approvalId} answered 202 parking_in_progress${hint !== undefined ? ` (retryAfterMs=${hint})` : ''} — ` +
                     `the answer did NOT take effect${decidePath !== undefined ? ' (the engine pointed at a decide path for the parked card)' : ''}; not reported as decided (the one invited re-send, if any, has already been made); the user is told to answer again on the parked card`);
                 surfaceApprovalParking(hint);
-                return { kind: 'unsettled', lane: 'respond', cause: 'parking_in_progress', parking };
+                return parkingInProgress(parking);
             }
             hostLog('error', `liveToolApprovalWire: 202 parking body for ${approvalId} is ${parkingBody.kind === 'parking' ? `for another approval (${parkingBody.view.approvalId})` : 'unreadable (approvalId is not usable)'} — ` +
                 'reporting the answer as NOT settled (never as decided, never as parked); not re-sent');
             return { kind: 'unsettled', lane: 'respond', cause: 'unreadable' };
         }
-        const parsed = settlementAckOf(readToolApprovalRespondAck(raw));
-        const replayVerdict = replayVerdictFrom(raw, parsed, approvalId);
+        const askDoorBody = askDoor !== undefined ? readAskDoorDecisionBody(raw, askDoor.askId, decision) : undefined;
+        if (askDoorBody?.kind === 'earlier') {
+            hostLog('debug', `liveToolApprovalWire: decision(${decision}) for ${approvalId} answered with a body that names this ask but records the other decision (${askDoorBody.firstDecision}) — reporting the earlier decision, never the one this client sent`);
+            return replayedDecisionOf(askDoorBody.firstDecision, decision);
+        }
+        if (askDoorBody?.kind === 'other_ask') {
+            hostLog('error', `liveToolApprovalWire: decision(${decision}) for ${approvalId} answered with a body that names another ask or cannot be matched to this one — reporting the answer as NOT settled (never as the decision this client sent); not re-sent`);
+            return { kind: 'unsettled', lane: 'respond', cause: 'unreadable' };
+        }
+        const parsed = askDoor !== undefined ? (askDoorBody?.kind === 'receipt' ? askDoorBody.ack : undefined) : settlementAckOf(readToolApprovalRespondAck(raw));
+        const replayVerdict = askDoor === undefined ? replayVerdictFrom(raw, parsed, approvalId) : REPLAY_NONE;
         if (replayVerdict.kind === 'replayed' && replayVerdict.via === 'claim') {
             hostLog('debug', `liveToolApprovalWire: respond(${decision}) for ${approvalId} answered with a replay (body not in the full replay shape) — the approval was already decided ` +
                 `(${replayVerdict.firstDecision}); this answer was not delivered, reporting the earlier decision`);
@@ -2690,14 +2829,24 @@ async function presentToolApprovalFrameAndRespond(frame, carriers, approvalId, r
     }
     catch (e) {
         const fromDelivery = deliveryFailure !== undefined && deliveryFailure.error === e ? deliveryFailure : undefined;
+        const askDoorParking = askDoor !== undefined && fromDelivery !== undefined ? askDoorParkingOfThrown(fromDelivery.reading, approvalId) : undefined;
+        if (askDoorParking !== undefined) {
+            const hint = ownReadingSlot(askDoorParking, 'retryAfterMs');
+            hostLog('debug', `liveToolApprovalWire: decision(${decision}) for ${approvalId} answered 425 parking.ask_retry${hint !== undefined ? ` (retryAfterMs=${hint})` : ''} — the answer did NOT take effect; ` +
+                'not reported as decided (the one invited re-send, if any, has already been made)');
+            surfaceApprovalParking(hint);
+            return parkingInProgress(askDoorParking);
+        }
         const r = resolutionOfDecisionFailure(e, {
             lane: 'respond',
-            route: 'live_respond',
+            route: askDoor !== undefined ? 'ask_decide' : 'live_respond',
             attributionCarried: lastSendCarriedAttribution,
             ...(fromDelivery?.transportExhausted === true ? { transportExhausted: true } : {}),
             ...(fromDelivery?.afterRetry === true ? { afterRetry: true } : {}),
             ...(fromDelivery !== undefined ? { delivered: fromDelivery.reading } : {}),
         });
+        if (r.kind === 'unsettled' && r.cause === 'route_missing' && askDoor === undefined && respondSwitch === undefined)
+            hostLog('warn', ROUTE_MISSING_WIRING_HINT);
         const refusal = r.kind === 'unsettled' ? r.refusal : undefined;
         hostLog('debug', `liveToolApprovalWire: respond(${decision}) failed for ${approvalId} ` +
             `(status=${refusal?.status ?? 'none'} errorCode=${logSafeErrorCode(refusal?.errorCode)} ` +

package/dist/hookMatcherVerdict.d.ts

@@ -1,4 +1,5 @@
 import type { UiLanguage } from './env/uiLanguage.js';
+import { type HooksWireSettingsContract } from './pluginHooksWire.js';
 export type HookMatcherUnjudgedReason = 'event_out_of_scope' | 'not_a_string' | 'oversize' | 'pattern_unsupported' | 'over_budget';
 export type HookMatcherRefusedReason = 'alias_without_canonical' | 'invalid_regex';
 export type HookMatcherVerdict = {
@@ -24,5 +25,5 @@ export type HookMatcherVerdict = {
     readonly kind: 'unjudged';
     readonly reason: HookMatcherUnjudgedReason;
 };
-export declare function hookMatcherVerdict(event: string, matcher: unknown): HookMatcherVerdict;
+export declare function hookMatcherVerdict(event: string, matcher: unknown, contract: HooksWireSettingsContract): HookMatcherVerdict;
 export declare function hookMatcherUnjudgedWhy(reason: HookMatcherUnjudgedReason | string, lang?: UiLanguage): string;

package/dist/hookMatcherVerdict.js

@@ -1,6 +1,7 @@
 import { msg, renderMessage } from './i18n/translate.js';
 import { HOOK_TOOL_ALIASES } from './hookToolAliases.js';
 import { SETTINGS_TOOL_NAME_MATCHER_EVENTS } from './generated/settingsSchemaTables.js';
+import { isEngineFiredHookEvent } from './pluginHooksWire.js';
 import { SETTINGS_HOOK_MATCHER_FORM, SETTINGS_HOOK_MATCHER_SELECTS } from './generated/settingsSchemaFns.js';
 const TOOL_NAME_MATCHER_EVENTS = new Set(SETTINGS_TOOL_NAME_MATCHER_EVENTS);
 const MATCHER_MAX_CHARS = 8192;
@@ -180,8 +181,8 @@ function patternBound(src, n) {
         throw e;
     }
 }
-export function hookMatcherVerdict(event, matcher) {
-    if (typeof event !== 'string' || !TOOL_NAME_MATCHER_EVENTS.has(event))
+export function hookMatcherVerdict(event, matcher, contract) {
+    if (typeof event !== 'string' || !TOOL_NAME_MATCHER_EVENTS.has(event) || !isEngineFiredHookEvent(event, contract))
         return unjudged('event_out_of_scope');
     if (matcher !== undefined && typeof matcher !== 'string')
         return unjudged('not_a_string');

package/dist/hooksReaderGenerations.d.ts

@@ -1 +1,9 @@
+import type { EngineCapValueState } from './engineCapsCache.js';
+import { type HooksWireEngineFacts } from './pluginHooksWire.js';
 export declare function hooksReaderNotReadKeys(serverVersion: string | undefined): readonly string[];
+export type HookEntryFieldsReading = Exclude<HooksWireEngineFacts['hookEntryFields'], undefined>;
+export interface HooksEntryKeyReader {
+    readonly fields: HookEntryFieldsReading;
+    readonly reads: (entryType: string, key: string, carriedByCopy: boolean) => boolean;
+}
+export declare function hooksEntryKeyReaderOf(settingsContract: EngineCapValueState, serverVersion: string | undefined): HooksEntryKeyReader;

package/dist/hooksReaderGenerations.js

@@ -1,3 +1,5 @@
+import { ownDataField } from './ownKey.js';
+import { HOOK_ENTRY_TYPE_WORDS } from './pluginHooksWire.js';
 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', 'rewakeMessage', 'rewakeSummary', 'cloud', 'continueOnBlock']) }),
@@ -10,3 +12,50 @@ export function hooksReaderNotReadKeys(serverVersion) {
     }
     return HOOKS_READER_FAIL_CLOSED;
 }
+function isPlainRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function hookEntryFieldsOf(group) {
+    try {
+        if (!isPlainRecord(group))
+            return undefined;
+        const table = ownDataField(group, 'hookEntryFields');
+        if (!isPlainRecord(table))
+            return undefined;
+        const columns = Object.keys(table);
+        if (columns.length !== HOOK_ENTRY_TYPE_WORDS.length || !HOOK_ENTRY_TYPE_WORDS.every((t) => columns.includes(t)))
+            return undefined;
+        const out = new Map();
+        for (const type of HOOK_ENTRY_TYPE_WORDS) {
+            const column = ownDataField(table, type);
+            if (!Array.isArray(column))
+                return undefined;
+            const n = ownDataField(column, 'length');
+            if (typeof n !== 'number' || !Number.isInteger(n) || n < 0)
+                return undefined;
+            const keys = new Set();
+            for (let i = 0; i < n; i += 1) {
+                const key = ownDataField(column, String(i));
+                if (typeof key !== 'string')
+                    return undefined;
+                keys.add(key);
+            }
+            out.set(type, keys);
+        }
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function hooksEntryKeyReaderOf(settingsContract, serverVersion) {
+    if (settingsContract.kind === 'value') {
+        const fields = hookEntryFieldsOf(settingsContract.value);
+        if (fields !== undefined) {
+            return Object.freeze({ fields: 'reported', reads: (entryType, key) => key === 'type' || (fields.get(entryType)?.has(key) ?? false) });
+        }
+    }
+    const fields = settingsContract.kind === 'unobserved' ? null : settingsContract.kind === 'not_reported' ? 'not_reported' : 'unreadable';
+    const notRead = hooksReaderNotReadKeys(serverVersion);
+    return Object.freeze({ fields, reads: (_entryType, key, carriedByCopy) => carriedByCopy && !notRead.includes(key) });
+}