@sema-agent/client-core 0.90.0 → 0.91.0

package/dist/hitl/crashConverged.js

@@ -127,3 +127,60 @@ export function projectCrashConverged(env) {
     }
     return { total: resumeSafe.length + needsHuman.length, resumeSafe, needsHuman, dropped };
 }
+const isCount = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+function bucketRowsOf(bucket) {
+    if (!Array.isArray(bucket))
+        return undefined;
+    const len = ownDataValue(bucket, 'length');
+    if (!isCount(len) || len > MAX_CRASH_CONVERGED_ROWS)
+        return undefined;
+    const rows = [];
+    for (let i = 0; i < len; i++)
+        rows.push(ownDataValue(bucket, String(i)));
+    return rows;
+}
+function reasonTextOf(row) {
+    try {
+        if (typeof row !== 'object' || row === null)
+            return undefined;
+        const v = ownDataValue(row, 'needsHumanReason');
+        return typeof v === 'string' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function causeWordsOf(rows) {
+    const seen = [];
+    try {
+        for (const row of rows) {
+            if (typeof row !== 'object' || row === null)
+                return undefined;
+            const c = ownDataValue(row, 'cause');
+            if (isCrashConvergedCause(c) && !seen.includes(c))
+                seen.push(c);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return seen;
+}
+export function readCrashConvergedNoticeFacts(projection) {
+    try {
+        if (typeof projection !== 'object' || projection === null)
+            return undefined;
+        const total = ownDataValue(projection, 'total');
+        const dropped = ownDataValue(projection, 'dropped');
+        if (!isCount(total) || !isCount(dropped) || total > MAX_CRASH_CONVERGED_ROWS)
+            return undefined;
+        const safe = bucketRowsOf(ownDataValue(projection, 'resumeSafe'));
+        const human = bucketRowsOf(ownDataValue(projection, 'needsHuman'));
+        if (safe === undefined || human === undefined || safe.length + human.length !== total)
+            return undefined;
+        return { total, dropped, needsHumanReasons: human.map(reasonTextOf), causes: causeWordsOf([...safe, ...human]) };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hitl/crashConvergedNotice.d.ts

@@ -0,0 +1,4 @@
+import type { CrashConvergedProjection } from './crashConverged.js';
+export declare const NEEDS_HUMAN_REASON_ORDER: readonly ["approved_then_interrupted", "pending_unsafe", "contradictory", "unstable_row"];
+export declare function crashConvergedNeedsHumanSentence(reason: string | undefined, n: number, total: number): string | undefined;
+export declare function crashConvergedNotice(projection: CrashConvergedProjection | undefined): string | undefined;

package/dist/hitl/crashConvergedNotice.js

@@ -0,0 +1,57 @@
+import { readCrashConvergedNoticeFacts } from './crashConverged.js';
+export const NEEDS_HUMAN_REASON_ORDER = Object.freeze(['approved_then_interrupted', 'pending_unsafe', 'contradictory', 'unstable_row']);
+const _orderCoversReasons = true;
+const _orderInsideReasons = true;
+const _orderHasNoDuplicate = true;
+void _orderCoversReasons;
+void _orderInsideReasons;
+void _orderHasNoDuplicate;
+const RECORDED = 'based on what was recorded';
+const NO_AUTO_RERUN = 'sema has not re-run anything';
+const plural = (n, one, many) => (n === 1 ? one : many);
+const SENTENCE = Object.freeze({
+    approved_then_interrupted: (n, total) => `${n} of ${total} had already been approved and may have been running when the previous engine run ended, so a side effect may have partly landed`,
+    pending_unsafe: (n, total) => `${n} of ${total} had not started, ${RECORDED}, but the engine did not mark ${plural(n, 'it', 'them')} as safe to re-run`,
+    contradictory: (n, total) => `${n} of ${total} ${plural(n, 'has a contradictory record', 'have contradictory records')}`,
+    unstable_row: (n, total) => `${n} of ${total} ${plural(n, 'has a record that read differently each time it was read', 'have records that read differently each time they were read')}`,
+});
+const fallbackSentence = (n, total) => `${n} of ${total} had already been approved, or cannot be accounted for, so a side effect may have partly landed`;
+const isNeedsHumanReason = (v) => typeof v === 'string' && Object.hasOwn(SENTENCE, v);
+export function crashConvergedNeedsHumanSentence(reason, n, total) {
+    if (!isNeedsHumanReason(reason))
+        return undefined;
+    if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 1)
+        return undefined;
+    if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < n)
+        return undefined;
+    return SENTENCE[reason](n, total);
+}
+function needsHumanClauses(reasons, total) {
+    const clauses = [];
+    for (const reason of NEEDS_HUMAN_REASON_ORDER) {
+        const n = reasons.filter((r) => r === reason).length;
+        if (n > 0)
+            clauses.push(SENTENCE[reason](n, total));
+    }
+    const fallback = reasons.filter((r) => !isNeedsHumanReason(r)).length;
+    if (fallback > 0)
+        clauses.push(fallbackSentence(fallback, total));
+    return `${clauses.join('; ')} — check ${plural(reasons.length, 'it', 'them')} by hand before re-running`;
+}
+export function crashConvergedNotice(projection) {
+    const facts = readCrashConvergedNoticeFacts(projection);
+    if (facts === undefined)
+        return undefined;
+    const { total, dropped, needsHumanReasons, causes } = facts;
+    if (total === 0 && dropped === 0)
+        return undefined;
+    if (total === 0) {
+        return `the previous session left ${dropped} crash-converged approval ${plural(dropped, 'record', 'records')} that this version could not read. ${NO_AUTO_RERUN}.`;
+    }
+    const recordedAs = causes !== undefined && causes.length > 0 ? ` (recorded as ${causes.join(', ')})` : '';
+    const head = `the previous engine run ended with ${total} ${plural(total, 'approval', 'approvals')} still waiting${recordedAs}, ` +
+        `and the engine converged ${plural(total, 'it', 'them')} to denied`;
+    const body = needsHumanReasons.length > 0 ? needsHumanClauses(needsHumanReasons, total) : `${RECORDED}, ${plural(total, 'it', 'they')} can be re-run`;
+    const droppedClause = dropped > 0 ? ` (${dropped} further ${plural(dropped, 'record', 'records')} could not be read.)` : '';
+    return `${head}; ${body}. ${NO_AUTO_RERUN}.${droppedClause}`;
+}

package/dist/hitl/hitlBridge.d.ts

@@ -1,4 +1,5 @@
 import type { AgentEvent, 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';
 export declare const DEFAULT_DENY_REASON = "The user rejected this tool use";
@@ -8,9 +9,9 @@ export interface HitlPermissionDecisionLike {
     message?: string;
     updatedInput?: unknown;
 }
-export type HitlCanUseToolFn<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike> = (tool: {
+export type HitlCanUseToolFn<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike, Ctx = never, Msg = never> = (tool: {
     name: string;
-}, input: Record<string, unknown>, toolUseContext: never, assistantMessage: never, toolUseID: string, forceDecision?: D) => Promise<D>;
+}, input: Record<string, unknown>, toolUseContext: Ctx, assistantMessage: Msg, toolUseID: string, forceDecision?: D) => Promise<D>;
 export interface ApprovalsResourceLike {
     list(opts?: {
         signal?: AbortSignal;
@@ -147,8 +148,10 @@ export type GatePrompt<D extends HitlPermissionDecisionLike = HitlPermissionDeci
     toolUseID: string;
     gate: CheckpointGate | null;
 }) => Promise<D>;
-export declare function makeHitlCanUseTool<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike>(bridge: HitlBridge, prompt: GatePrompt<D>): HitlCanUseToolFn<D>;
-export interface HitlBackendDenyDecision {
+export declare function makeHitlCanUseTool<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike, Ctx = unknown, Msg = unknown>(bridge: HitlBridge, prompt: GatePrompt<D>): HitlCanUseToolFn<D, Ctx, Msg>;
+export interface HitlBackendDenyDecision extends Extract<PermissionResult, {
+    behavior: 'deny';
+}> {
     behavior: 'deny';
     message: string;
     decisionReason: {

package/dist/hitl/parkResolver.d.ts

@@ -1,6 +1,7 @@
 import type { AgentEvent } from '@sema-agent/sdk';
 import { type GateCurrentPending, type HitlFailureStage } from './hitlBridge.js';
 import { type QuestionAnswer } from '../liveQuestionStore.js';
+import { type FsApprovalOutcome } from './toolApprovalWire.js';
 import type { AskAnsweredOutput, GateLedger } from './gateLedger.js';
 import { type AskGateWireDeps, type GatePark } from './frameRouter.js';
 import { type DecideReceiptView } from '../decideReceipt.js';
@@ -29,12 +30,16 @@ export type GateOutcome = {
     reason: string;
     code?: GateFailureCode | undefined;
     errorCode?: string | undefined;
+    retriable?: true;
     retryExhausted?: true;
     currentPending?: GateCurrentPending | undefined;
 };
 export declare function isAlreadyResolvedGateReason(reason: unknown): boolean;
-export declare function isGateStandingErrorCode(code: string | null | undefined): boolean;
-export declare function isCodeClassifiedGateFailure(code: string | null | undefined): boolean;
+export declare function isAlreadyResolvedFailure(outcome: Extract<GateOutcome | FsApprovalOutcome, {
+    kind: 'failed';
+}>): boolean;
+export declare function isGateStandingErrorCode(code: string | null | undefined, retriable?: boolean): boolean;
+export declare function isCodeClassifiedGateFailure(code: string | null | undefined, retriable?: boolean): boolean;
 export declare function toAnsweredOutput(questions: unknown[], answer: QuestionAnswer): AskAnsweredOutput;
 export type ParkResolution = {
     kind: 'reattach';

package/dist/hitl/parkResolver.js

@@ -1,6 +1,6 @@
 import { putOwnKey } from '../ownKey.js';
 import { DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, NO_QUESTION_OVERLAY_REASON, findPendingForTask, isNoDecisionSurfaceReason, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
-import { PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE, isDecideParkMovedCode } from '../engineErrorCodes.js';
+import { CHECKPOINT_UNSUPPORTED_VERSION, PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE, isDecideParkMovedCode, refusalSaysStillPending } from '../engineErrorCodes.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
@@ -40,21 +40,31 @@ function alreadyResolvedReasonToken(reason) {
     const r = reason.toLowerCase();
     return ALREADY_RESOLVED_REASON_TOKENS.find((t) => r.includes(t));
 }
-function isAlreadyResolvedFailure(outcome) {
+export function isAlreadyResolvedFailure(outcome) {
+    try {
+        return alreadyResolvedFailureVerdict(outcome);
+    }
+    catch {
+        return false;
+    }
+}
+function alreadyResolvedFailureVerdict(outcome) {
+    if (typeof outcome !== 'object' || outcome === null)
+        return false;
     const code = 'code' in outcome && isGateFailureCode(outcome.code) ? outcome.code : undefined;
     if (code !== undefined)
         return code === 'no_pending';
-    if ('errorCode' in outcome && isCodeClassifiedGateFailure(outcome.errorCode))
+    if ('errorCode' in outcome && isCodeClassifiedGateFailure(outcome.errorCode, Object.hasOwn(outcome, 'retriable') && outcome.retriable === true))
         return false;
     if ('errorCode' in outcome && isDecideParkMovedCode(outcome.errorCode))
         return true;
     return isAlreadyResolvedGateReason(outcome.reason);
 }
-export function isGateStandingErrorCode(code) {
-    return code === RESUME_POLICY_FOLD_CODE || code === 'corrupt';
+export function isGateStandingErrorCode(code, retriable) {
+    return code === RESUME_POLICY_FOLD_CODE || code === 'corrupt' || (code === CHECKPOINT_UNSUPPORTED_VERSION && retriable === true);
 }
-export function isCodeClassifiedGateFailure(code) {
-    return isGateStandingErrorCode(code) || code === PARKED_RESUME_STARTUP_FAILED;
+export function isCodeClassifiedGateFailure(code, retriable) {
+    return isGateStandingErrorCode(code, retriable) || code === PARKED_RESUME_STARTUP_FAILED;
 }
 export function toAnsweredOutput(questions, answer) {
     const answers = {};
@@ -153,6 +163,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
         const code = e instanceof HitlSafetyError && isGateFailureCode(e.code) ? e.code : undefined;
         const currentPending = readDecideCurrentPending(e);
         const wireCode = readWireErrorCode(e);
+        const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
         return {
             kind: 'failed',
             stage: 'decide',
@@ -162,6 +173,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
             ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
             ...(currentPending !== undefined ? { currentPending } : {}),
             ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
+            ...(wireRetriable ? { retriable: true } : {}),
         };
     }
 }

package/dist/hitl/planReviewWire.d.ts

@@ -43,7 +43,7 @@ export interface PlanReviewOutcomeMeta {
     decision: 'approve' | 'reject';
     effect: PlanReviewDecisionEffect;
 }
-export declare function planReviewOutcomeTail(taskId: string, decision: 'approve' | 'reject', effect: PlanReviewDecisionEffect): string;
+export declare function planReviewOutcomeTail(taskId: string, decision: 'approve' | 'reject', effect: PlanReviewDecisionEffect, cause?: 'stored_form_unsupported'): string;
 export type PlanReviewWireClient = {
     assistant: Pick<AgentClient['assistant'], 'planReview'>;
     runs: Pick<AgentClient['runs'], 'get'>;

package/dist/hitl/planReviewWire.js

@@ -6,6 +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 { REQUEST_FIELD_CONFLICT } from '../engineErrorCodes.js';
 import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
 import { engineCapString } from '../engineCapsCache.js';
 import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
@@ -303,7 +305,10 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
         return false;
     }
 }
-export function planReviewOutcomeTail(taskId, decision, effect) {
+export function planReviewOutcomeTail(taskId, decision, effect, cause) {
+    if (effect === 'still_parked' && cause === 'stored_form_unsupported') {
+        return `Do not tell the user the plan was ${decision === 'approve' ? 'approved' : 'rejected'}, and do not ${decision} it again: deciding again will not take effect while it is stored in this form. Tell the user the way forward this outcome gives — cancel this task's run, then submit the work again as a new task.`;
+    }
     switch (effect) {
         case 'took_effect':
             return decision === 'approve'
@@ -500,6 +505,7 @@ function planReviewClientsFor(resolved) {
 async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, gateBefore) {
     let outcome;
     let effect = 'unconfirmed';
+    let stillParkedCause;
     let stillParkedProven = false;
     let statusSeen;
     const wire = opts?.wire;
@@ -543,7 +549,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 }
                 catch (e1) {
                     const conflict = e1;
-                    if (mode === 'default' && conflict?.status === 400 && conflict?.errorCode === 'request.field_conflict') {
+                    if (mode === 'default' && conflict?.status === 400 && conflict?.errorCode === REQUEST_FIELD_CONFLICT) {
                         hostLog('debug', 'planReviewWire: permissionModeAfter "default" refused as not applicable — re-sending the approval without the key (same meaning)');
                         body = await sendOnce(undefined, () => client.assistant.planReview(taskId, reason !== undefined ? { decision, reason } : { decision }));
                     }
@@ -610,7 +616,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 const status = e?.status;
                 const refusedCode = e?.errorCode;
                 const noAnswer = typeof status === 'number' || typeof e !== 'object' ? null : noAnswerKindOf(e);
-                if (status === 400 && refusedCode === 'request.field_conflict' && permissionModeAfter === 'acceptEdits') {
+                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');
                     effect = 'still_parked';
                     stillParkedProven = true;
@@ -625,6 +631,14 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                         `This ${decision} was not applied: the engine no longer has a pending plan review for this task — an earlier decision most likely already went through (or the review expired). ` +
                             'This is NOT a rejection of the plan and NOT a failure of the task; the answer just given simply had nothing left to act on.';
                 }
+                else if (checkpointUnsupportedVersionFromError(e) !== null) {
+                    const cu = checkpointUnsupportedVersionFromError(e);
+                    hostLog('debug', `planReviewWire: ${decision} → 409 checkpoint.unsupported_version (the server cannot continue this parked review in its stored form; still pending)`);
+                    effect = 'still_parked';
+                    stillParkedProven = true;
+                    stillParkedCause = 'stored_form_unsupported';
+                    outcome = `This ${decision} was not applied. ${checkpointUnsupportedVersionContent(cu, { parkKind: 'plan_review', runId: taskId })}`;
+                }
                 else if (typeof status === 'number' && corruptStoredRowWhere(e) !== undefined) {
                     const where = corruptStoredRowWhere(e);
                     hostLog('debug', `planReviewWire: ${decision} → ${String(status)} corrupt (stored resume context unreadable)`);
@@ -651,7 +665,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
             }
         }
     }
-    const tail = planReviewOutcomeTail(taskId, decision, effect);
+    const tail = planReviewOutcomeTail(taskId, decision, effect, stillParkedCause);
     const prompt = `<plan-review-outcome>\n${outcome}\n${tail}\n</plan-review-outcome>`;
     const onOutcome = opts?.onOutcome;
     settle(effect === 'not_sent' || (effect === 'still_parked' && stillParkedProven));

package/dist/hitl/sessionPolicyWire.d.ts

@@ -105,6 +105,11 @@ export declare function tightenSessionPolicy(facade: SessionPolicyFacade, req: S
     signal?: AbortSignal;
 }): Promise<SessionPolicyTightenOutcome>;
 export declare function sessionPolicyTightenNotice(outcome: SessionPolicyTightenOutcome): string;
+export declare function sessionPolicyReadNotice(outcome: Exclude<SessionPolicyReadOutcome, {
+    kind: 'present';
+}> | {
+    kind: 'no_target';
+}): string;
 export interface SessionPolicyRemovedEntry {
     readonly field: 'toolDeny' | 'toolAllow';
     readonly rule: string;

package/dist/hitl/sessionPolicyWire.js

@@ -344,6 +344,69 @@ export function sessionPolicyTightenNotice(outcome) {
             }
     }
 }
+const READ_NOTICE_GENERIC = 'This session’s rule record could not be shown, so what it holds is not known. Try reading it again.';
+const READ_NOTICE_NO_TARGET = 'There is no engine connection for this session, so its rule record cannot be read and what it holds is not known. Look again once it is connected.';
+function readFailureSentence(kind) {
+    switch (kind) {
+        case 'face-unavailable':
+            return 'This deployment does not keep per-session tool rules, so there is no session rule record to read.';
+        case 'loosen-forbidden':
+            return 'The engine answered this read with a refusal that only applies to relaxing rules, so this session’s rule record could not be read. Try again; if it keeps happening, whoever runs the engine needs to look at it.';
+        case 'store-corrupt':
+            return 'The engine could not establish which version this session’s rules are at, so it would not hand the record over. This needs an operator to look at the rule store.';
+        case 'cas-conflict':
+            return 'The engine reported a version clash on this session’s rule record, so it could not be read this time. Try again.';
+        case 'session-ownerless':
+            return 'This session has no owner, so it has no rule record to read.';
+        case 'session-not-found':
+            return 'This session is not readable from here — it may not exist, or it may belong to someone else — so its rule record cannot be shown. Check that you are connected to the engine and the session you meant, or continue in a new session.';
+        case 'request-rejected':
+            return 'The engine rejected the request to read this session’s rule record as malformed, so it could not be read. Sending the same request again will not change that; check which session was asked for.';
+        case 'legacy-tool-name':
+            return 'The engine answered this read with a refusal about a tool name it no longer accepts, so this session’s rule record could not be read. Try again; if it keeps happening, whoever runs the engine needs to look at it.';
+        case 'unauthorized':
+            return 'This call could not present a verifiable identity, so this session’s rule record could not be read.';
+        case 'error':
+            return 'The engine refused to hand over this session’s rule record for a reason this version has no wording for, so it could not be read. Try again; if it keeps happening, whoever runs the engine needs to look at it.';
+        case 'no-verdict':
+            return 'No clear answer came back from the engine when this session’s rule record was read, so what it holds is not known — that is not the same as holding nothing. Try again.';
+    }
+}
+function readMalformedSentence(why) {
+    switch (why) {
+        case 'envelope':
+            return 'The engine answered, but not in a form this version can read as a session rule record, so what the record holds is not known. Try again; if it keeps happening, this version and the engine may be out of step.';
+        case 'rev':
+            return 'The engine’s answer for this session’s rule record carried no usable version, so this version will not show it — a record it cannot place may still hold restrictions that are in effect. Try again.';
+        case 'rule_field':
+            return 'One of the lists in this session’s rule record came back in a form this version cannot read, so none of the record is shown rather than part of it — a partly shown record could leave out restrictions that are in effect.';
+    }
+}
+function ownRead(o, key) {
+    const d = Object.getOwnPropertyDescriptor(o, key);
+    return d !== undefined && Object.hasOwn(d, 'value') ? d.value : undefined;
+}
+export function sessionPolicyReadNotice(outcome) {
+    try {
+        if (outcome === null || typeof outcome !== 'object')
+            return READ_NOTICE_GENERIC;
+        const arm = ownRead(outcome, 'kind');
+        if (arm === 'failed') {
+            const failure = ownRead(outcome, 'failure');
+            if (failure === null || typeof failure !== 'object')
+                return READ_NOTICE_GENERIC;
+            return readFailureSentence(ownRead(failure, 'kind')) ?? READ_NOTICE_GENERIC;
+        }
+        if (arm === 'malformed')
+            return readMalformedSentence(ownRead(outcome, 'why')) ?? READ_NOTICE_GENERIC;
+        if (arm === 'no_target')
+            return READ_NOTICE_NO_TARGET;
+        return READ_NOTICE_GENERIC;
+    }
+    catch {
+        return READ_NOTICE_GENERIC;
+    }
+}
 function withoutRefusedEntries(prior, mounted) {
     const REFUSABLE_NAME_FIELDS = ['toolDeny', 'toolAllow'];
     const isRefusable = (f) => REFUSABLE_NAME_FIELDS.includes(f);

package/dist/hitl/suspendedReopen.js

@@ -1,4 +1,4 @@
-import { RESUME_REOPEN_CODES, RESUME_ENV_FAILED, RESUME_TOOL_UNAVAILABLE } from '../engineErrorCodes.js';
+import { RESUME_REOPEN_CODES, RESUME_ENV_FAILED, RESUME_TOOL_UNAVAILABLE, refusalSaysStillPending } from '../engineErrorCodes.js';
 const UNSTATED = Object.freeze({ kind: 'unstated' });
 const NOT_REOPENED = Object.freeze({ kind: 'not_reopened' });
 export function suspendedReopenOf(ev) {
@@ -25,7 +25,7 @@ export function resumeReopenFromError(err) {
     const code = err.errorCode;
     if (typeof code !== 'string' || !RESUME_REOPEN_CODES.includes(code))
         return null;
-    if (err.retriable !== true)
+    if (!refusalSaysStillPending(err))
         return null;
     const reason = code.slice('resume.'.length);
     return { code, reason, retriable: true };

package/dist/hitl/toolApprovalWire.d.ts

@@ -37,6 +37,7 @@ export type FsApprovalOutcome = {
     reason: string;
     code?: 'no_pending' | undefined;
     errorCode?: string | undefined;
+    retriable?: true;
     safetyCode?: HitlSafetyCode | undefined;
     retryExhausted?: true;
     currentPending?: GateCurrentPending | undefined;
@@ -131,6 +132,7 @@ export interface ApprovalCardRequest {
     hasBidiControls?: true;
     persistedRuleShadowed?: string;
     probeCause?: unknown;
+    probeReason?: string;
     ruleEvidence?: unknown;
     requiresRealApproval?: true;
     irreversibleParkGate?: true;
@@ -180,6 +182,7 @@ export interface ToolApprovalFrame {
     ruleStoreUnreadable?: string;
     persistedRuleShadowed?: string;
     probeCause?: unknown;
+    probeReason?: string;
     ruleEvidence?: unknown;
     requiresRealApproval?: true;
     mandated?: true;
@@ -204,7 +207,7 @@ export interface ToolApprovalDelegation {
     depth: number;
     agentName?: string;
 }
-export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "ruleStoreUnreadable", "readRootCandidate", "mandated", "mandate", "origin", "askClass", "classes", "inputHasBidi", "parked", "persistedRuleShadowed", "probeCause", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome"];
+export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "ruleStoreUnreadable", "readRootCandidate", "mandated", "mandate", "origin", "askClass", "classes", "inputHasBidi", "parked", "persistedRuleShadowed", "probeCause", "probeReason", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome"];
 export interface ApprovalMandatedFacts {
     readonly mandated?: true;
     readonly ruleOffersAbsence?: string;

package/dist/hitl/toolApprovalWire.js

@@ -10,6 +10,7 @@ import { isRuleStoreUnreadableKind } from '../gateVocabulary.js';
 import { isApprovalMandateWord } from '../gateVocabulary.js';
 import { denyAttributionRefusalFromError } from '../wireRefusalCopy.js';
 import { decideFailureNote } from '../decideFailureNote.js';
+import { 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';
 export function isFsApprovalGate(gate) {
@@ -190,6 +191,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
     const callKey = approvalCallKey(gatedCallId, taskId);
     const ruleOffersReadOnly = readRuleOfferSupply(pending.ruleOffers, pending.ruleSuggestions);
     const durableProbeCause = pending.riskDescriptor?.probeCause;
+    const durableProbeReason = readProbeReason(pending.riskDescriptor);
     const durableShadowedRule = pending.riskDescriptor?.shadowedRule;
     const durableRuleOffersAbsence = pending.ruleOffersAbsence;
     const durableRuleStoreUnreadable = readRuleStoreUnreadable(pending.ruleStoreUnreadable);
@@ -215,6 +217,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         ...(pending.hasBidiControls === true ? { hasBidiControls: true } : {}),
         ...(ruleOffersReadOnly !== undefined ? { ruleOffersReadOnly } : {}),
         ...(isWireRecordCarrier(durableProbeCause) ? { probeCause: durableProbeCause } : {}),
+        ...(durableProbeReason !== undefined ? { probeReason: durableProbeReason } : {}),
         ...(durableRuleStoreUnreadable !== undefined
             ? { ruleStoreUnreadable: durableRuleStoreUnreadable }
             : {}),
@@ -279,6 +282,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                 catch (e) {
                     const currentPending = readDecideCurrentPending(e);
                     const wireCode = readWireErrorCode(e);
+                    const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
                     const safetyCode = e instanceof HitlSafetyError ? e.code : undefined;
                     return {
                         kind: 'failed',
@@ -288,6 +292,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                         ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
                         ...(currentPending !== undefined ? { currentPending } : {}),
                         ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
+                        ...(wireRetriable ? { retriable: true } : {}),
                         ...(safetyCode !== undefined ? { safetyCode } : {}),
                     };
                 }
@@ -335,6 +340,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                 catch (e) {
                     const currentPending = readDecideCurrentPending(e);
                     const wireCode = readWireErrorCode(e);
+                    const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
                     const safetyCode = e instanceof HitlSafetyError ? e.code : undefined;
                     const attributionRefusal = denyAttributionRefusalFromError(e, lastSendCarriedAttribution);
                     return {
@@ -345,6 +351,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                         ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
                         ...(currentPending !== undefined ? { currentPending } : {}),
                         ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
+                        ...(wireRetriable ? { retriable: true } : {}),
                         ...(safetyCode !== undefined ? { safetyCode } : {}),
                         ...(attributionRefusal !== null ? { denyAttributionRefusal: attributionRefusal } : {}),
                     };
@@ -393,6 +400,7 @@ export const TOOL_APPROVAL_FRAME_KEYS_MIRROR = [
     'parked',
     'persistedRuleShadowed',
     'probeCause',
+    'probeReason',
     'ruleEvidence',
     'requiresRealApproval',
     'expiresInMs',
@@ -644,6 +652,17 @@ function pathFromGateMessage(message) {
         return undefined;
     return body.slice(0, close);
 }
+function readProbeReason(v) {
+    try {
+        if (typeof v !== 'object' || v === null || !Object.hasOwn(v, 'probeReason'))
+            return undefined;
+        const raw = v.probeReason;
+        return typeof raw === 'string' && raw.trim() !== '' ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function isNonNegativeFinite(v) {
     return typeof v === 'number' && Number.isFinite(v) && v >= 0;
 }
@@ -887,6 +906,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
             ? { persistedRuleShadowed: frame.persistedRuleShadowed }
             : {}),
         ...(isWireRecordCarrier(frame.probeCause) ? { probeCause: frame.probeCause } : {}),
+        ...((r) => (r !== undefined ? { probeReason: r } : {}))(readProbeReason(frame)),
         ...(isWireRecordCarrier(frame.ruleEvidence) ? { ruleEvidence: frame.ruleEvidence } : {}),
         ...(frame.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
         ...(hasOwnStrictTrue(frame, 'mandated') ? { mandated: true } : {}),

package/dist/hookMatcherVerdict.d.ts

@@ -0,0 +1,29 @@
+export type HookMatcherUnjudgedReason = 'event_out_of_scope' | 'not_a_string' | 'oversize' | 'invalid_pattern' | 'pattern_unsupported' | 'over_budget';
+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 aliases: readonly {
+        readonly alias: string;
+        readonly canonical: string;
+    }[];
+} | {
+    readonly kind: 'refused';
+    readonly reason: 'alias_without_canonical';
+    readonly reading: 'names' | 'pattern';
+    readonly alias: string;
+    readonly canonical: string;
+} | {
+    readonly kind: 'unjudged';
+    readonly reason: HookMatcherUnjudgedReason;
+};
+export declare function hookMatcherVerdict(event: string, matcher: unknown): HookMatcherVerdict;