@sema-agent/client-core 0.93.0 → 0.94.0

package/dist/hitl/decisionRefusal.js

@@ -0,0 +1,63 @@
+import { refusalSaysStillPending } from '../engineErrorCodes.js';
+import { readLivePendingRows } from './livePendingAsk.js';
+import { readToolApprovalRespondRefusal } from './toolApprovalWire.js';
+const ASK_DECIDED_CODE = 'conflict.ask_decided';
+const TRANSIENT_STATUSES = new Set([408, 425, 429, 502, 503, 504]);
+const DISPLAYABLE_CODE = /^[A-Za-z0-9._:-]{1,64}$/;
+export function classifyDecisionRefusal(err) {
+    const r = readToolApprovalRespondRefusal(err);
+    const status = r?.status;
+    if (status === undefined || !Number.isInteger(status) || status < 400 || status > 599)
+        return undefined;
+    const code = r?.errorCode;
+    const errorCode = code !== undefined && DISPLAYABLE_CODE.test(code) ? code : undefined;
+    const standing = status === 404 || status === 410 || (status === 409 && code === ASK_DECIDED_CODE)
+        ? 'settled-elsewhere'
+        : status >= 500 && status !== 501
+            ? 'ambiguous'
+            : 'refused-pending';
+    const transient = TRANSIENT_STATUSES.has(status) || (typeof err === 'object' && err !== null && refusalSaysStillPending(err));
+    return Object.freeze({ standing, status, ...(errorCode !== undefined ? { errorCode } : {}), ...(transient ? { transient: true } : {}) });
+}
+export function liveAskPendingReading(envelope, approvalId) {
+    if (typeof approvalId !== 'string' || approvalId === '')
+        return 'unknown';
+    try {
+        const reading = readLivePendingRows(envelope);
+        if (reading.kind !== 'present')
+            return 'unknown';
+        if (reading.rows.some((row) => row.approvalId === approvalId))
+            return 'pending';
+        return reading.dropped === 0 ? 'not_pending' : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export function decisionRefusalClosesOut(refusal, pending) {
+    if (pending !== 'pending' || typeof refusal !== 'object' || refusal === null)
+        return false;
+    try {
+        const standing = refusal.standing;
+        if (refusal.transient === true)
+            return false;
+        return standing === 'ambiguous' || standing === 'refused-pending';
+    }
+    catch {
+        return false;
+    }
+}
+export function undeliverableDecisionContent(facts) {
+    const code = typeof facts.errorCode === 'string' && DISPLAYABLE_CODE.test(facts.errorCode) ? ` ${facts.errorCode}` : '';
+    const head = `The engine refused the approval decision this client sent (HTTP ${String(facts.status)}${code}), so the call it asked about could not be answered from here and did not run`;
+    const runId = typeof facts.runId === 'string' && DISPLAYABLE_CODE.test(facts.runId) ? ` ${facts.runId}` : '';
+    switch (facts.end) {
+        case 'run-stopped':
+            return `${head}; the run was stopped instead of being left waiting for the approval window to close. Update the client, or run the task in an interactive session and answer the approval there.`;
+        case 'run-unconfirmed':
+            return `${head}; this client stopped waiting, but the engine did not confirm that it stopped the run${runId}, so that approval may stay open until its window closes. Update the client, or run the task in an interactive session and answer the approval there.`;
+        case 'turn-stopped':
+        default:
+            return `${head}; this turn was stopped instead of being left waiting. Update the client, or switch to a permission mode that shows you the approval and try again.`;
+    }
+}

package/dist/hitl/frameRouter.d.ts

@@ -2,9 +2,19 @@ import type { AgentEvent } from '@sema-agent/sdk';
 import type { DecideOperationObserver, HitlClientLike } from './hitlBridge.js';
 import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts, type ToolApprovalFrameOutcome } from './toolApprovalWire.js';
 import type { GateLedger } from './gateLedger.js';
+import type { NoAllowCause } from './noAllowCause.js';
 import { type ReplayedApprovalDisposition } from './replayedApproval.js';
 export declare const HITL_REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
 export declare const HITL_POLICY_DENY_MESSAGE: string;
+export type PolicyDenyLane = 'no_approval_ui' | 'dont_ask';
+export interface PolicyDenyReasonFacts {
+    readonly lane: PolicyDenyLane;
+    readonly toolName: string;
+    readonly cause?: NoAllowCause;
+    readonly allowRuleFlag?: string;
+    readonly budgetSetting?: string;
+}
+export declare function policyDenyReason(facts: PolicyDenyReasonFacts): string;
 export declare const HITL_INTERRUPT_MESSAGE_FOR_TOOL_USE = "[Request interrupted by user for tool use]";
 export declare const ENGINE_ABORT_TOOL_RESULT = "Operation aborted";
 export declare function toolEndOutputText(output: unknown): string | undefined;

package/dist/hitl/frameRouter.js

@@ -4,6 +4,8 @@ import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
 import { GATE_PARKED_ERROR_CODE } from '../engineErrorCodes.js';
 import { readRunTerminal, runTerminalCode, runTerminalGateKind, runTerminalGateToolName } from '../runTerminal.js';
 import { surfaceForCurrentSession, surfaceReplayedApprovalListUnreadable } from './hitlHostSurface.js';
+import { liveCardHoldOf, supersedeLiveCard } from './approvalHolds.js';
+import { liveFrameCallKey } from './gateIdentity.js';
 import { SEMA_DENIAL_KIND_KEY, hasLedgerPositionKey } from './gateLedger.js';
 import { replayedApprovalDisposition } from './replayedApproval.js';
 import { settleWithinDeadline } from '../abortableSleep.js';
@@ -14,6 +16,38 @@ export const HITL_REJECT_MESSAGE = REJECT_MESSAGE;
 export const HITL_POLICY_DENY_MESSAGE = 'Permission for this tool use was denied: it requires interactive approval, and permission prompts are ' +
     'not available in this session. The action was NOT performed. Do not claim it succeeded, and do not retry ' +
     'it in this session \u2014 report the limitation to the user, or suggest an alternative.';
+const SENTENCE_TOOL_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.:@-]{0,199}$/;
+export function policyDenyReason(facts) {
+    const one = typeof facts.toolName === 'string' && SENTENCE_TOOL_NAME.test(facts.toolName) ? `this one "${facts.toolName}" call` : 'this one call';
+    const flag = typeof facts.allowRuleFlag === 'string' && SENTENCE_TOOL_NAME.test(facts.allowRuleFlag.replace(/^--?/, '')) ? ` (or ${facts.allowRuleFlag})` : '';
+    const budgetKnob = typeof facts.budgetSetting === 'string' && SENTENCE_TOOL_NAME.test(facts.budgetSetting) ? facts.budgetSetting : undefined;
+    const cause = facts.cause === 'no_allow_rule' || facts.cause === 'ask_rule' || facts.cause === 'budget' ? facts.cause : 'other';
+    if (facts.lane === 'dont_ask') {
+        const mode = 'denied by the dontAsk permission mode';
+        switch (cause) {
+            case 'no_allow_rule':
+                return `${mode}: ${one} needed approval, no permission rule allowed it, and this mode refuses anything that would ask — calls that need no approval still run; an allow rule in settings${flag} can approve calls like this ahead of time`;
+            case 'ask_rule':
+                return `${mode}: an ask rule matched ${one}, and this mode refuses anything that would ask (an ask rule outranks allow rules) — narrow or remove that ask rule, or use another permission mode to answer it`;
+            case 'budget':
+                return `${mode}: ${one} needed approval, and this session's automatic-approval budget is used up, so saved rules no longer approve calls${budgetKnob !== undefined ? ` — raise ${budgetKnob} before launch to change the cap` : ''}`;
+            default:
+                return `${mode}: ${one} needed a person's approval that saved permission rules cannot approve here (the engine or your deployment requires a person for it, or it could not be checked against your rules), and this mode refuses anything that would ask — use another permission mode to answer it`;
+        }
+    }
+    const lane = 'no approval UI on this lane';
+    const tail = 'nobody can be asked here, so only this call was refused — calls that need no approval still run';
+    switch (cause) {
+        case 'no_allow_rule':
+            return `${lane}: ${one} needed a person's approval, no permission rule answered it, and ${tail}; a matching allow rule in settings${flag} can approve calls like this ahead of time`;
+        case 'ask_rule':
+            return `${lane}: an ask rule matched ${one}, so it needed a person's answer, and ${tail}; an ask rule outranks allow rules, so narrow or remove that ask rule, or run the task interactively to answer it`;
+        case 'budget':
+            return `${lane}: ${one} needed a person's approval, and this session's automatic-approval budget is used up, so saved rules no longer approve calls; ${tail}${budgetKnob !== undefined ? `; raise ${budgetKnob} before launch to change the cap` : ''}`;
+        default:
+            return `${lane}: ${one} needed a person's approval, and saved permission rules cannot approve it here (the engine or your deployment requires a person for it, or it could not be checked against your rules); ${tail}; run the task interactively to answer it`;
+    }
+}
 function denyOutputForRender(attribution) {
     if (attribution?.settledBy !== 'policy')
         return HITL_REJECT_MESSAGE;
@@ -232,10 +266,24 @@ const TOOL_END_ARMS = [
             '改顺序必须同批改 TOOL_END_ARM_ORDER 并说明为什么新顺序仍然对。');
     }
 }
+function completeFrameParked(ev) {
+    try {
+        const d = Object.getOwnPropertyDescriptor(ev, 'parked');
+        return d !== undefined && 'value' in d && d.value === true;
+    }
+    catch {
+        return false;
+    }
+}
 async function routeToolApprovalFrame(ev, ctx) {
     const { led, deps } = ctx;
-    if (ev.type === 'tool_approval_complete')
+    if (ev.type === 'tool_approval_complete') {
+        const id = ev.approvalId;
+        if (typeof id === 'string' && id !== '' && supersedeLiveCard(liveFrameCallKey(id), completeFrameParked(ev))) {
+            hostLog('debug', `liveHitlAskWire: tool_approval_complete for ${id} arrived while its card was waiting — card withdrawn (nothing will be sent from it)`);
+        }
         return { kind: 'skip' };
+    }
     if (!deps.respondToolApproval) {
         hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} but no respond wire — engine self-settles (TTL deny)`);
         return { kind: 'skip' };
@@ -269,7 +317,16 @@ async function routeToolApprovalFrame(ev, ctx) {
     const frameCallId = !fromSubagent && typeof ev.toolCallId === 'string' && ev.toolCallId !== '' ? ev.toolCallId : undefined;
     const gatedCallId = fromSubagent ? undefined : frameCallId ?? led.lastPendingFsCall();
     const argsCallId = frameCallId === undefined ? gatedCallId : typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName) ? frameCallId : undefined;
-    const outcome = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, argsCallId), ctx.signal, deps.approvalLane);
+    const launched = surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, argsCallId), ctx.signal, deps.approvalLane);
+    const hold = liveCardHoldOf(liveFrameCallKey(ev.approvalId));
+    const handled = launched.then((outcome) => settleLiveCardOutcome(ev, outcome, ctx, fromSubagent, gatedCallId), (e) => {
+        hostLog('debug', `liveHitlAskWire: tool_approval card for ${ev.approvalId} failed: ${String(e).slice(0, 160)}`);
+    });
+    led.trackLiveCard(() => hold?.phase ?? 'card', handled);
+    return { kind: 'skip' };
+}
+function settleLiveCardOutcome(ev, outcome, ctx, fromSubagent, gatedCallId) {
+    const { led, deps } = ctx;
     const { decision } = outcome;
     if (deps.onToolApprovalOutcome !== undefined) {
         try {
@@ -294,7 +351,6 @@ async function routeToolApprovalFrame(ev, ctx) {
         else
             led.armDenyStamp(attribution);
     }
-    return { kind: 'skip' };
 }
 const REPLAYED_APPROVAL_LIST_DEADLINE_MS = 3000;
 async function judgeLedgerApprovalFrame(ev, ctx) {

package/dist/hitl/gateLedger.d.ts

@@ -23,6 +23,9 @@ export interface GateLedger {
     notePreambleApproval(approvalId: string): void;
     preambleApprovals(): ReadonlySet<string>;
     beginStreamSegment(): void;
+    trackLiveCard(phaseOf: () => 'card' | 'respond', handled: Promise<void>): void;
+    answeringLiveCards(): Promise<void>[];
+    liveCardsSettled(): Promise<void>;
     markStarted(callId: string): boolean;
     noteGatedStart(callId: string, ev: AgentEvent): void;
     gatedStartArgs(): ReadonlyMap<string, unknown>;

package/dist/hitl/gateLedger.js

@@ -88,6 +88,7 @@ export function createGateLedger() {
     let denyStampAttribution;
     let seq;
     const preambleApprovalIds = new Set();
+    const liveCards = new Set();
     return {
         noteSeq(ev) {
             const s = durableSeqOf(ev);
@@ -120,6 +121,22 @@ export function createGateLedger() {
         beginStreamSegment() {
             preambleApprovalIds.clear();
         },
+        trackLiveCard(phaseOf, handled) {
+            const entry = { phaseOf, handled };
+            liveCards.add(entry);
+            void handled.then(() => { liveCards.delete(entry); }, () => { liveCards.delete(entry); });
+        },
+        answeringLiveCards() {
+            const out = [];
+            for (const e of liveCards)
+                if (e.phaseOf() === 'respond')
+                    out.push(e.handled);
+            return out;
+        },
+        async liveCardsSettled() {
+            while (liveCards.size > 0)
+                await Promise.allSettled([...liveCards].map((e) => e.handled));
+        },
         markStarted(callId) {
             if (startedCalls.has(callId))
                 return false;

package/dist/hitl/hitlBridge.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
+import type { AgentEvent, ApprovalDecidedBy, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
 import type { PermissionResult } from '@sema-agent/agent-types';
 import type { ApprovalsListEnvelope } from './crashConverged.js';
 import { type SuspendedReopenReading } from './suspendedReopen.js';
@@ -56,7 +56,7 @@ export interface HitlDecideDenyOutcome {
     decision: 'deny';
     reason?: string | undefined;
     settledBy?: 'policy' | undefined;
-    decidedBy?: 'policy' | undefined;
+    decidedBy?: Extract<ApprovalDecidedBy, 'policy'> | undefined;
 }
 export declare class HitlSafetyError extends Error {
     readonly code: HitlSafetyCode;

package/dist/hitl/hitlBridge.js

@@ -3,6 +3,7 @@ import { eventSeq } from '../adapter/types.js';
 import { hostLog } from '../host.js';
 import { abortableSleep } from '../abortableSleep.js';
 import { readOwnDataValue } from '../ownKey.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
 import { suspendedReopenOf } from './suspendedReopen.js';
 export const DEFAULT_DENY_REASON = 'The user rejected this tool use';
 const MAX_DENY_REASON_CHARS = 4096;
@@ -208,7 +209,9 @@ export async function findPendingForTask(client, taskId, matches, opts, callId,
         rows = (await client.approvals.list(opts)).pending;
     }
     catch (e) {
-        return { ok: false, reason: `approvals.list failed: ${String(e)}` };
+        const t = wireFailureTextsOf(e);
+        hostLog('debug', `hitlBridge: approvals.list failed: ${t.log}`);
+        return { ok: false, reason: `approvals.list failed: ${t.reason}` };
     }
     const decidable = rows.filter((r) => askParkForeignGateKind(r) === null);
     const identityRow = callId !== undefined
@@ -327,13 +330,8 @@ export class HitlBridge {
             throw new HitlSafetyError(`plan-review "${outcome.decision}" must NOT carry editedPlan`, 'bad_plan_edit');
         }
         const modeAfter = outcome.permissionModeAfter;
-        if (modeAfter !== undefined) {
-            if (outcome.decision !== 'approve') {
-                throw new HitlSafetyError(`plan-review "${outcome.decision}" must NOT carry permissionModeAfter (it only applies to an approval)`, 'bad_plan_mode');
-            }
-            if (!isPlanReviewModeAfter(modeAfter)) {
-                throw new HitlSafetyError('plan-review permissionModeAfter must be "default" or "acceptEdits"', 'bad_plan_mode');
-            }
+        if (modeAfter !== undefined && !isPlanReviewModeAfter(modeAfter)) {
+            throw new HitlSafetyError('plan-review permissionModeAfter must be "default" or "acceptEdits"', 'bad_plan_mode');
         }
         const req = { decision: outcome.decision };
         if (modeAfter !== undefined && isPlanReviewModeAfter(modeAfter))
@@ -416,11 +414,11 @@ export class HitlBridge {
                     throw e;
                 if (isDecideAttemptTimeout(e)) {
                     if (attempts >= DECIDE_TIMEOUT_MIN_ATTEMPTS && Date.now() - startedAt >= decideTimeoutRetryBudgetMs()) {
-                        throw new DecideTransportRetryExhaustedError(attempts, String(e));
+                        throw new DecideTransportRetryExhaustedError(attempts, wireFailureTextsOf(e).reason);
                     }
                 }
                 else if (netRetriesUsed >= 1) {
-                    throw new DecideTransportRetryExhaustedError(attempts, String(e));
+                    throw new DecideTransportRetryExhaustedError(attempts, wireFailureTextsOf(e).reason);
                 }
                 else {
                     netRetriesUsed++;

package/dist/hitl/hitlHostSurface.d.ts

@@ -23,11 +23,17 @@ export declare function hitlHostSurfaceFor(sessionKey: string): HitlHostSurface
 export declare function _resetHitlHostSurfaceForTest(): void;
 export declare function surfaceForCurrentSession(): HitlHostSurface | null;
 export declare const CANCEL_DENY_BUDGET_MS = 2000;
+export declare const INTERRUPT_DENY_REASON = "Interrupted by user";
 export declare const CANCEL_DENY_WARN_TEXT = "could not cancel the pending question \u2014 the session may stay locked; the run may need engine-side recovery";
 export declare const REMEMBER_NOT_APPLIED_WARN_TEXT = "this session-wide allow was not remembered by the worker \u2014 you will be asked again for this tool";
 export declare const EDIT_NOT_FORWARDED_WARN_TEXT = "your edited tool input was NOT forwarded \u2014 the tool is running with the ORIGINAL input you saw before editing";
 export declare function surfaceRememberNotApplied(): void;
 export declare function surfaceEditNotForwarded(): void;
+export declare const APPROVAL_PARKING_WARN_TEXT = "This approval is being parked; answer it again on the parked card when it appears.";
+export declare function approvalParkingNoticeText(retryAfterMs?: number): string;
+export declare function surfaceApprovalParking(retryAfterMs?: number): void;
+export declare const COMPACT_NOT_RUNNING_WARN_TEXT = "engine run finished before compaction was applied; nothing was compacted";
+export declare function surfaceCompactNotRunning(sessionKey?: string): void;
 export declare const REPLAYED_APPROVAL_LIST_UNREADABLE_WARN_TEXT: string;
 export declare function surfaceReplayedApprovalListUnreadable(): void;
 export declare const EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT: string;

package/dist/hitl/hitlHostSurface.js

@@ -29,22 +29,26 @@ export function _resetHitlHostSurfaceForTest() {
     hostSurfaceMissesByKey.clear();
 }
 export function surfaceForCurrentSession() {
-    const hostSurface = hitlHostSurfaceFor(DEFAULT_SESSION_KEY);
+    return surfaceForSession(DEFAULT_SESSION_KEY);
+}
+function surfaceForSession(sessionKey) {
+    const hostSurface = hitlHostSurfaceFor(sessionKey);
     if (hostSurface === null) {
-        hostSurfaceMissesByKey.set(DEFAULT_SESSION_KEY, (hostSurfaceMissesByKey.get(DEFAULT_SESSION_KEY) ?? 0) + 1);
+        hostSurfaceMissesByKey.set(sessionKey, (hostSurfaceMissesByKey.get(sessionKey) ?? 0) + 1);
     }
     return hostSurface;
 }
 export const CANCEL_DENY_BUDGET_MS = 2000;
+export const INTERRUPT_DENY_REASON = 'Interrupted by user';
 export const CANCEL_DENY_WARN_TEXT = 'could not cancel the pending question — the session may stay locked; the run may need engine-side recovery';
 const CANCEL_DENY_WARN_KEY = 'hitl-cancel-deny-warn';
 const CANCEL_DENY_WARN_TIMEOUT_MS = 10_000;
 function surfaceCancelDenyWarn(text = CANCEL_DENY_WARN_TEXT) {
     surfaceSelfClearingWarn(CANCEL_DENY_WARN_KEY, text, CANCEL_DENY_WARN_TIMEOUT_MS);
 }
-function surfaceSelfClearingWarn(key, text, timeoutMs) {
+function surfaceSelfClearingWarn(key, text, timeoutMs, sessionKey = DEFAULT_SESSION_KEY) {
     try {
-        const s = surfaceForCurrentSession();
+        const s = surfaceForSession(sessionKey);
         if (!s)
             return;
         s.showNotice({ key, text, color: 'warning', priority: 'immediate', timeoutMs });
@@ -72,6 +76,23 @@ export function surfaceRememberNotApplied() {
 export function surfaceEditNotForwarded() {
     surfaceSelfClearingWarn(EDIT_NOT_FORWARDED_KEY, EDIT_NOT_FORWARDED_WARN_TEXT, EDIT_NOT_FORWARDED_TIMEOUT_MS);
 }
+export const APPROVAL_PARKING_WARN_TEXT = 'This approval is being parked; answer it again on the parked card when it appears.';
+const APPROVAL_PARKING_KEY = 'hitl-approval-parking';
+const APPROVAL_PARKING_TIMEOUT_MS = 15_000;
+export function approvalParkingNoticeText(retryAfterMs) {
+    if (retryAfterMs === undefined)
+        return APPROVAL_PARKING_WARN_TEXT;
+    return `${APPROVAL_PARKING_WARN_TEXT} (the engine suggested waiting about ${Math.ceil(retryAfterMs / 100) / 10} s)`;
+}
+export function surfaceApprovalParking(retryAfterMs) {
+    surfaceSelfClearingWarn(APPROVAL_PARKING_KEY, approvalParkingNoticeText(retryAfterMs), APPROVAL_PARKING_TIMEOUT_MS);
+}
+export const COMPACT_NOT_RUNNING_WARN_TEXT = 'engine run finished before compaction was applied; nothing was compacted';
+const COMPACT_NOT_RUNNING_KEY = 'engine-compact-not-running';
+const COMPACT_NOT_RUNNING_TIMEOUT_MS = 10_000;
+export function surfaceCompactNotRunning(sessionKey = DEFAULT_SESSION_KEY) {
+    surfaceSelfClearingWarn(COMPACT_NOT_RUNNING_KEY, COMPACT_NOT_RUNNING_WARN_TEXT, COMPACT_NOT_RUNNING_TIMEOUT_MS, sessionKey);
+}
 export const REPLAYED_APPROVAL_LIST_UNREADABLE_WARN_TEXT = "Could not read the pending-approval list, so an approval request read back from this run's event log was not raised as a question, " +
     'and no decision was sent for it.';
 const REPLAYED_APPROVAL_LIST_UNREADABLE_KEY = 'hitl-replayed-approval-list-unreadable';

package/dist/hitl/localAllowRule.js

@@ -1,3 +1,4 @@
+import { wireFailureTextsOf } from '../wireFailureShape.js';
 const BASH_TOOL_NAME_FOR_RULES = 'Bash';
 export function parseLocalAllowRule(rule, expectedToolName, deps) {
     if (typeof rule !== 'string' || rule === '') {
@@ -8,7 +9,7 @@ export function parseLocalAllowRule(rule, expectedToolName, deps) {
         value = deps.parseRule(rule);
     }
     catch (e) {
-        return { ok: false, error: `rule text did not parse (${String(e)})` };
+        return { ok: false, error: `rule text did not parse (${wireFailureTextsOf(e).reason})` };
     }
     if (typeof value.toolName !== 'string' || value.toolName === '') {
         return { ok: false, error: 'rule text carries no tool name' };

package/dist/hitl/noAllowCause.d.ts

@@ -0,0 +1,9 @@
+export type NoAllowCause = 'no_allow_rule' | 'ask_rule' | 'budget' | 'other';
+export interface RuleLadderNoAllowFacts {
+    readonly allowed?: boolean;
+    readonly denied?: boolean;
+    readonly askRuleMatched?: boolean;
+    readonly budgetExhausted?: boolean;
+    readonly noRuleMatched?: boolean;
+}
+export declare function noAllowCauseOf(card: object | null | undefined, ladder: RuleLadderNoAllowFacts | null | undefined): NoAllowCause | undefined;

package/dist/hitl/noAllowCause.js

@@ -0,0 +1,26 @@
+import { automaticAnswerVerdict } from './automaticAnswerVerdict.js';
+function ladderSays(ladder, key) {
+    if (typeof ladder !== 'object' || ladder === null)
+        return false;
+    try {
+        const d = Object.getOwnPropertyDescriptor(ladder, key);
+        return d !== undefined && 'value' in d && d.value === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function noAllowCauseOf(card, ladder) {
+    if (ladderSays(ladder, 'allowed') || ladderSays(ladder, 'denied'))
+        return undefined;
+    if (ladderSays(ladder, 'askRuleMatched'))
+        return 'ask_rule';
+    if (ladderSays(ladder, 'budgetExhausted'))
+        return 'budget';
+    const standing = automaticAnswerVerdict(card, 'standing_rule');
+    if (standing.kind === 'must_ask' && (standing.askClass === 'ask_rule' || standing.origin === 'ask_rule'))
+        return 'ask_rule';
+    if (ladderSays(ladder, 'noRuleMatched') && standing.kind === 'may_answer')
+        return 'no_allow_rule';
+    return 'other';
+}

package/dist/hitl/parkResolver.js

@@ -4,11 +4,12 @@ import { ASK_GONE, CHECKPOINT_UNSUPPORTED_VERSION, DECIDE_WORKFLOW_PARK_FORKED,
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
-import { observeCancelByDeny } from './hitlHostSurface.js';
+import { INTERRUPT_DENY_REASON, observeCancelByDeny } from './hitlHostSurface.js';
 import { flushHeldWithInterruptRewrite, isAskTool } from './frameRouter.js';
 import { approvalCallKey, askGateQuestionId } from './gateIdentity.js';
 import { readDecideReceipt } from '../decideReceipt.js';
 import { decideFailureNote } from '../decideFailureNote.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
 export const MAX_GATE_HOPS = 2;
 export function nextHopBudget(prev, round) {
     const total = (prev?.total ?? 0) + 1;
@@ -139,7 +140,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
     });
     const bridge = new HitlBridge(deps.client, taskId, deps.onDecideOperation ? { onDecideOperation: deps.onDecideOperation } : undefined);
     if (answer === null) {
-        observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: 'Interrupted by user' }, gatedCallId, undefined, pending), taskId);
+        observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: INTERRUPT_DENY_REASON }, gatedCallId, undefined, pending), taskId);
         return { kind: 'aborted', gatedCallId };
     }
     let declinedReceipt;
@@ -170,11 +171,13 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
         const currentPending = readDecideCurrentPending(e);
         const wireCode = readWireErrorCode(e);
         const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
+        const failureTexts = wireFailureTextsOf(e);
+        hostLog('debug', `liveHitlAskWire: decide failed: ${failureTexts.log}`);
         return {
             kind: 'failed',
             stage: 'decide',
             gatedCallId,
-            reason: `decide failed: ${String(e)}${decideFailureNote(e, attemptedDecision)}`,
+            reason: `decide failed: ${failureTexts.reason}${decideFailureNote(e, attemptedDecision)}`,
             ...(code !== undefined ? { code } : {}),
             ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
             ...(currentPending !== undefined ? { currentPending } : {}),

package/dist/hitl/parkRowBirthWait.js

@@ -1,4 +1,5 @@
 import { abortableSleep } from '../abortableSleep.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
 function parkRowPollDelay(ms, signal) {
     return abortableSleep(ms, signal ?? new AbortController().signal);
 }
@@ -16,7 +17,7 @@ export async function waitForParkRowBirth(deps) {
             return await deps.probe(attempt, signal);
         }
         catch (e) {
-            return { kind: 'unborn', reason: `probe threw: ${String(e)}` };
+            return { kind: 'unborn', reason: `probe threw: ${wireFailureTextsOf(e).reason}` };
         }
     };
     const probeWithinRemaining = async (attempt, remainingMs) => {

package/dist/hitl/persistedRulesWire.d.ts

@@ -44,6 +44,9 @@ export type RulesFailure = {
 } | {
     kind: 'cursor-stale';
     message: string;
+} | {
+    kind: 'query-refused';
+    message: string;
 } | {
     kind: 'too-many-candidates';
     message: string;
@@ -78,7 +81,9 @@ export type RulesFailure = {
     kind: 'error';
     message: string;
 };
-export declare function classifyRulesFailure(e: unknown): RulesFailure;
+export declare function classifyRulesFailure(e: unknown, context?: {
+    readonly cursorSent?: boolean;
+}): RulesFailure;
 export declare const PERSISTED_RULE_BEHAVIORS: readonly RuleBehavior[];
 export declare function persistedRuleBehaviorOf(rule: unknown): RuleBehavior | undefined;
 export declare const PERSISTED_RULE_BEHAVIOR_UNKNOWN = "(unknown)";

package/dist/hitl/persistedRulesWire.js

@@ -36,7 +36,7 @@ export function readCcImportRedeemCounts(result) {
     }
     return null;
 }
-export function classifyRulesFailure(e) {
+export function classifyRulesFailure(e, context) {
     const { status, errorCode, message, retryAfterSec, committed } = wireFailureShapeOf(e);
     if (errorCode === 'capability.rule_store_required') {
         return { kind: 'lane-unavailable', message };
@@ -58,8 +58,16 @@ export function classifyRulesFailure(e) {
     if (errorCode === 'state.rule_write_failed') {
         return committed === 'no' ? { kind: 'write-not-committed', message } : { kind: 'write-indeterminate', message };
     }
-    if (status === 400 && errorCode === 'request.query_invalid')
-        return { kind: 'cursor-stale', message };
+    if (status === 400 && errorCode === 'request.query_invalid') {
+        let cursorSent;
+        try {
+            cursorSent = context?.cursorSent;
+        }
+        catch {
+            cursorSent = undefined;
+        }
+        return cursorSent === false ? { kind: 'query-refused', message } : { kind: 'cursor-stale', message };
+    }
     if (status === 400 && errorCode === 'request.field_invalid')
         return { kind: 'field-refused', message };
     if (status === 400 && errorCode === 'request.body_shape')
@@ -144,7 +152,7 @@ export async function listAllPersistedRules(facade, params = {}, opts) {
                 res = await facade.list({ limit: PAGE_LIMIT, ...cleanParams, ...(cursor !== undefined ? { cursor } : {}) }, opts);
             }
             catch (e) {
-                const failure = classifyRulesFailure(e);
+                const failure = classifyRulesFailure(e, { cursorSent: cursor !== undefined });
                 if (failure.kind === 'cursor-stale' && cursor !== undefined && attempt === 0) {
                     hostLog('debug', 'persistedRulesWire: rule list cursor was minted on another rev/principal/scope — dropping it and re-listing from the top (never resuming a stale keyset)');
                     restart = true;

package/dist/hitl/planReviewWire.d.ts

@@ -48,7 +48,6 @@ export type PlanReviewWireClient = {
 };
 export interface PlanReviewWire {
     client: PlanReviewWireClient;
-    capsBaseUrl?: string;
 }
 export interface PlanReviewDecisionOutcome extends PlanReviewOutcomeMeta {
     detail: string;

package/dist/hitl/planReviewWire.js

@@ -6,7 +6,8 @@ import { engineWireTarget } from '../engineWireTarget.js';
 import { enqueuePlanReviewOutcome } from '../notifications.js';
 import { corruptStoredRowContent, corruptStoredRowWhere } from '../wireErrorTriage.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError } from '../resumeRefusalCopy.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
+import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError, resumeContextUnavailableContent, resumeContextUnavailableFromError } from '../resumeRefusalCopy.js';
 import { REQUEST_FIELD_CONFLICT, isUnavailableFaceCode } from '../engineErrorCodes.js';
 import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
 import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
@@ -309,6 +310,15 @@ export function planReviewOutcomeTail(taskId, decision, effect, cause) {
             return `Do not state the result as fact: tell the user the ${decision} was submitted but its effect could not be confirmed; TaskOutput("${taskId}") shows where the task stands.`;
     }
 }
+function clientOnlyView(wire) {
+    if (wire === undefined || wire === null || typeof wire !== 'object')
+        return wire;
+    return {
+        get client() {
+            return wire.client;
+        },
+    };
+}
 function planReviewDecisionTimedOutOutcome(decision) {
     return (`The plan_review ${decision} was sent, but no answer came back from the engine within the time limit this host allows for it — ` +
         `it may have taken effect (${decision === 'approve' ? 'an approval keeps the engine busy until the resumed work finishes' : 'the engine may still be applying it'}).`);
@@ -492,12 +502,12 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
     let stillParkedProven = false;
     let statusSeen;
     const wire = opts?.wire;
-    const resolved = engineWireFor(wire, DEFAULT_SESSION_KEY, usablePlanReviewWireClient);
-    const badMode = permissionModeAfter !== undefined && (decision !== 'approve' || !isPlanReviewModeAfter(permissionModeAfter));
+    const resolved = engineWireFor(clientOnlyView(wire), DEFAULT_SESSION_KEY, usablePlanReviewWireClient);
+    const badMode = permissionModeAfter !== undefined && !isPlanReviewModeAfter(permissionModeAfter);
     if (badMode) {
-        hostLog('error', `planReviewWire: ${decision} NOT sent — permissionModeAfter is only valid with approve and must be "default" or "acceptEdits"`);
+        hostLog('error', `planReviewWire: ${decision} NOT sent — permissionModeAfter must be "default" or "acceptEdits"`);
         effect = 'not_sent';
-        outcome = `The plan_review ${decision} could NOT be sent: the post-approval permission mode given with it is not valid for this decision (it only applies to an approval, and must be "default" or "acceptEdits"). Tell the user plainly that the decision did not go through; the plan is still waiting.`;
+        outcome = `The plan_review ${decision} could NOT be sent: the post-approval permission mode given with it is not valid (it must be "default" or "acceptEdits"). Tell the user plainly that the decision did not go through; the plan is still waiting.`;
     }
     else if (resolved.kind === 'no-target') {
         hostLog('error', `planReviewWire: ${decision} NOT sent — engineWireTarget() unavailable`);
@@ -600,12 +610,15 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 const refusedCode = e?.errorCode;
                 const noAnswer = typeof status === 'number' || typeof e !== 'object' ? null : noAnswerKindOf(e);
                 if (status === 400 && refusedCode === REQUEST_FIELD_CONFLICT && permissionModeAfter === 'acceptEdits') {
-                    hostLog('debug', 'planReviewWire: approve + acceptEdits refused (request.field_conflict) — NOT re-sent with a different mode');
+                    hostLog('debug', `planReviewWire: ${decision} + acceptEdits refused (request.field_conflict) — NOT re-sent with a different mode`);
                     effect = 'still_parked';
                     stillParkedProven = true;
                     outcome =
-                        'The plan approval was NOT applied: the engine refused "auto-accept edits" for this task (it was not started read-only in plan mode, so that option does not apply). ' +
-                            'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly, and that approving with "manually approve edits" will go through.';
+                        decision === 'approve'
+                            ? 'The plan approval was NOT applied: the engine refused "auto-accept edits" for this task (it was not started read-only in plan mode, so that option does not apply). ' +
+                                'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly, and that approving with "manually approve edits" will go through.'
+                            : `The plan ${decision} was NOT applied: the engine refused the post-approval permission mode that was sent with it (request.field_conflict). ` +
+                                'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly that the decision did not go through.';
                 }
                 else if (status === 404 && refusedCode === 'not_found.plan_review') {
                     hostLog('debug', `planReviewWire: ${decision} → 404 not_found.plan_review (no pending plan review any more — an earlier decision likely settled it)`);
@@ -622,6 +635,12 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     stillParkedCause = 'stored_form_unsupported';
                     outcome = `This ${decision} was not applied. ${checkpointUnsupportedVersionContent(cu, { parkKind: 'plan_review', runId: taskId })}`;
                 }
+                else if (resumeContextUnavailableFromError(e) !== null) {
+                    const ru = resumeContextUnavailableFromError(e);
+                    hostLog('debug', `planReviewWire: ${decision} → 409 conflict.resume_context_unavailable (the session context needed to continue this run is not available)`);
+                    effect = 'not_applied';
+                    outcome = `This ${decision} was not applied. ${resumeContextUnavailableContent(ru)}`;
+                }
                 else if (typeof status === 'number' && corruptStoredRowWhere(e) !== undefined) {
                     const where = corruptStoredRowWhere(e);
                     hostLog('debug', `planReviewWire: ${decision} → ${String(status)} corrupt (stored resume context unreadable)`);
@@ -643,7 +662,9 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     outcome = planReviewDecisionConnectionLostOutcome(decision);
                 }
                 else {
-                    outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
+                    const failureTexts = wireFailureTextsOf(e);
+                    hostLog('debug', `planReviewWire: ${decision} could not reach the engine: ${failureTexts.log}`);
+                    outcome = `The plan_review decision could not reach the engine: ${failureTexts.reason}`;
                 }
             }
         }