@sema-agent/client-core 0.83.6 → 0.84.1

package/dist/hitl/planReviewWire.js

@@ -1,12 +1,12 @@
 import { publishQuestionFrame, publishQuestionFrameFor, registerLocalQuestionResponder, unregisterLocalQuestionResponder, hasLocalQuestionResponder, hasQuestionOverlayFor, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
-import { abortableSleep } from '../abortableSleep.js';
+import { abortableSleep, settleWithinDeadline } from '../abortableSleep.js';
 import { makeEngineWireClient } from '../engineWireSdk.js';
 import { engineWireTarget } from '../engineWireTarget.js';
 import { enqueuePlanReviewOutcome } from '../notifications.js';
 import { corruptStoredRowContent, corruptStoredRowWhere } from '../wireErrorTriage.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { isPlanReviewModeAfter } from './hitlBridge.js';
+import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
 import { engineCapString } from '../engineCapsCache.js';
 import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
 import { notePlanReviewAnswered, notePlanReviewAnsweredFor, planReviewArmedKeyFor, registerArmedGateFor, waitForGateArmedFor, wasGateArmedFor, } from './armedGateRegistry.js';
@@ -225,8 +225,19 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
                 '此处拒绝而不是回落默认槽 —— 回落会把这条会话的决断带着别的槽的 baseUrl/token/principal 发出去。');
             return false;
         }
-        if (!engineWireTarget())
+        const wire = opts?.wire;
+        if (wire !== undefined) {
+            if (!usablePlanReviewWireClient(wire.client)) {
+                hostLog('error', 'planReviewWire: plan_review card NOT armed — the engine client supplied by the host is not usable (needs assistant.planReview and runs.get)');
+                return false;
+            }
+        }
+        else if (!engineWireTarget()) {
             return false;
+        }
+        const delivery = wire !== undefined || opts?.onOutcome !== undefined
+            ? { ...(wire !== undefined ? { wire } : {}), ...(opts?.onOutcome !== undefined ? { onOutcome: opts.onOutcome } : {}) }
+            : undefined;
         const { taskId } = result;
         retireActiveReopen(DEFAULT_SESSION_KEY, planReviewQuestionId(taskId));
         if (armedPlanReviewTaskIds.has(taskId)) {
@@ -240,8 +251,9 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
         }
         armedPlanReviewTaskIds.add(taskId);
         armedTaskId = taskId;
+        const capsBaseUrl = wire !== undefined ? wire.capsBaseUrl : engineWireTarget()?.baseUrl;
         const offerModeAfter = opts?.submittedInPlanMode === true &&
-            versionSupportsPlanReviewModeAfter(engineCapString(engineWireTarget()?.baseUrl, 'version')) === 'supported';
+            versionSupportsPlanReviewModeAfter(engineCapString(capsBaseUrl, 'version')) === 'supported';
         if (offerModeAfter)
             offerModeAfterByTask.set(taskId, true);
         else
@@ -262,7 +274,7 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
             offerModeAfterByTask.delete(taskId);
             notePlanReviewAnswered(questionId);
             hostLog('debug', `planReviewWire: arm responder delivering ${decided} for task ${taskId} (path=arm)`);
-            void decidePlanReview(taskId, decided, modeAfter);
+            void (delivery === undefined ? decidePlanReview(taskId, decided, modeAfter) : decidePlanReview(taskId, decided, modeAfter, delivery));
             return { ok: true };
         });
         publishPlanReviewCard(taskId);
@@ -296,12 +308,31 @@ export function planReviewOutcomeTail(taskId, decision, effect) {
             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 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'}).`);
+}
+function isRequestTimeout(e) {
+    try {
+        return typeof e === 'object' && e !== null && e.name === 'TimeoutError';
+    }
+    catch {
+        return false;
+    }
+}
+function usablePlanReviewWireClient(client) {
+    if (client === null || typeof client !== 'object')
+        return false;
+    const c = client;
+    return typeof c.assistant?.planReview === 'function' && typeof c.runs?.get === 'function';
+}
+const PLAN_REVIEW_INJECTED_REPULL_TIMEOUT_MS = 15_000;
 const decideInFlight = new Map();
 let decideDispatchSeq = 0;
 export function __resetPlanReviewDecisionLatchForTests() {
     decideInFlight.clear();
 }
-export async function decidePlanReview(taskId, decision, permissionModeAfter) {
+export async function decidePlanReview(taskId, decision, permissionModeAfter, opts) {
     if (decideInFlight.has(taskId)) {
         hostLog('error', `planReviewWire: decidePlanReview(${decision}) for task ${taskId} REFUSED — a decision for this task is already in flight (duplicate delivery latched)`);
         return;
@@ -315,43 +346,84 @@ export async function decidePlanReview(taskId, decision, permissionModeAfter) {
     const dispatchNo = ++decideDispatchSeq;
     hostLog('debug', `planReviewWire: decidePlanReview dispatch #${dispatchNo} task=${taskId} decision=${decision} mode=${permissionModeAfter ?? '-'}`);
     try {
-        await decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch);
+        await decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, opts);
     }
     finally {
         releaseLatch();
     }
 }
-async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch) {
+function planReviewClientsFor(wire, cfg) {
+    if (wire !== undefined) {
+        let injected;
+        try {
+            injected = typeof wire === 'object' && wire !== null ? wire.client : undefined;
+        }
+        catch {
+            injected = undefined;
+        }
+        if (!usablePlanReviewWireClient(injected))
+            return null;
+        const client = injected;
+        return { decide: client, repull: () => client };
+    }
+    if (!cfg)
+        return null;
+    const decide = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+        timeoutMs: PLAN_REVIEW_RESUME_TIMEOUT_MS,
+    });
+    if (!decide)
+        return null;
+    return {
+        decide,
+        repull: () => makeEngineWireClient({
+            baseUrl: cfg.baseUrl,
+            ...(cfg.token ? { token: cfg.token } : {}),
+            principal: cfg.principal,
+            timeoutMs: 15_000,
+        }),
+    };
+}
+async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, opts) {
     let outcome;
     let effect = 'unconfirmed';
-    const cfg = engineWireTarget();
+    let statusSeen;
+    const wire = opts?.wire;
+    const cfg = wire === undefined ? engineWireTarget() : null;
     const badMode = permissionModeAfter !== undefined && (decision !== 'approve' || !isPlanReviewModeAfter(permissionModeAfter));
     if (badMode) {
         hostLog('error', `planReviewWire: ${decision} NOT sent — permissionModeAfter is only valid with approve and 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.`;
     }
-    else if (!cfg) {
+    else if (wire === undefined && !cfg) {
         hostLog('error', `planReviewWire: ${decision} NOT sent — engineWireTarget() unavailable`);
         effect = 'not_sent';
         outcome = `The plan_review ${decision} could NOT be sent: no engine connection is configured on this host. Tell the user plainly that the decision did not go through.`;
     }
     else {
-        const client = makeEngineWireClient({
-            baseUrl: cfg.baseUrl,
-            ...(cfg.token ? { token: cfg.token } : {}),
-            principal: cfg.principal,
-            timeoutMs: PLAN_REVIEW_RESUME_TIMEOUT_MS,
-        });
-        if (!client) {
-            hostLog('error', `planReviewWire: ${decision} NOT sent — makeEngineWireClient() returned null`);
+        const clients = planReviewClientsFor(wire, cfg);
+        if (!clients) {
+            if (wire !== undefined) {
+                hostLog('error', `planReviewWire: ${decision} NOT sent — the engine client supplied by the host is not usable (needs assistant.planReview and runs.get)`);
+                outcome = `The plan_review ${decision} could NOT be sent: the engine client supplied by the host cannot send it (it lacks the plan-review verb). Tell the user plainly that the decision did not go through.`;
+            }
+            else {
+                hostLog('error', `planReviewWire: ${decision} NOT sent — makeEngineWireClient() returned null`);
+                outcome = `The plan_review ${decision} could NOT be sent: the engine client could not be constructed. Tell the user plainly that the decision did not go through.`;
+            }
             effect = 'not_sent';
-            outcome = `The plan_review ${decision} could NOT be sent: the engine client could not be constructed. Tell the user plainly that the decision did not go through.`;
         }
         else {
+            const client = clients.decide;
             try {
                 const mode = isPlanReviewModeAfter(permissionModeAfter) ? permissionModeAfter : undefined;
+                const reason = denyReasonForWire(opts?.reason, `plan-review ${taskId}`);
                 const reqBody = { decision };
+                if (reason !== undefined)
+                    reqBody.reason = reason;
                 if (mode !== undefined)
                     reqBody.permissionModeAfter = mode;
                 let body;
@@ -362,7 +434,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     const conflict = e1;
                     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 client.assistant.planReview(taskId, { decision });
+                        body = await client.assistant.planReview(taskId, reason !== undefined ? { decision, reason } : { decision });
                     }
                     else {
                         throw e1;
@@ -374,19 +446,28 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 hostLog('debug', `planReviewWire: ${decision} → ok (dispatch #${dispatchNo}) ${JSON.stringify(body).slice(0, 200)}`);
                 let postStatus;
                 try {
-                    const probe = makeEngineWireClient({
-                        baseUrl: cfg.baseUrl,
-                        ...(cfg.token ? { token: cfg.token } : {}),
-                        principal: cfg.principal,
-                        timeoutMs: 15_000,
-                    });
-                    const post = probe ? (await probe.runs.get(taskId)) : null;
-                    postStatus = typeof post?.status === 'string' ? post.status : undefined;
+                    const probe = clients.repull();
+                    if (probe) {
+                        let post;
+                        if (wire !== undefined) {
+                            const got = await settleWithinDeadline(PLAN_REVIEW_INJECTED_REPULL_TIMEOUT_MS, (signal) => probe.runs.get(taskId, { signal }));
+                            if (got.kind === 'error')
+                                throw new Error(got.detail);
+                            if (got.kind === 'deadline')
+                                throw new Error(`post-decide status re-pull passed its ${PLAN_REVIEW_INJECTED_REPULL_TIMEOUT_MS} ms deadline`);
+                            post = got.value;
+                        }
+                        else {
+                            post = (await probe.runs.get(taskId));
+                        }
+                        postStatus = typeof post?.status === 'string' ? post.status : undefined;
+                    }
                 }
                 catch (e) {
                     hostLog('debug', `planReviewWire: post-decide status re-pull failed (fail-soft): ${String(e)}`);
                 }
                 const effective = postStatus ?? (typeof body?.status === 'string' ? body.status : undefined);
+                statusSeen = effective;
                 if (effective === 'needs_review') {
                     effect = 'still_parked';
                     outcome =
@@ -437,21 +518,41 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     effect = status >= 400 && status < 500 ? 'not_applied' : 'unconfirmed';
                     outcome = `${`The plan_review decision failed: HTTP ${status} ${msg}`.trim()}${decideFailureNote(e)}`;
                 }
+                else if (isRequestTimeout(e)) {
+                    hostLog('debug', `planReviewWire: ${decision} sent but no answer within the request time limit (task ${taskId})`);
+                    outcome = planReviewDecisionTimedOutOutcome(decision);
+                }
                 else {
                     outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
                 }
             }
         }
     }
+    const tail = planReviewOutcomeTail(taskId, decision, effect);
+    const prompt = `<plan-review-outcome>\n${outcome}\n${tail}\n</plan-review-outcome>`;
+    const onOutcome = opts?.onOutcome;
     try {
-        const delivered = enqueuePlanReviewOutcome(`<plan-review-outcome>\n${outcome}\n${planReviewOutcomeTail(taskId, decision, effect)}\n</plan-review-outcome>`, { taskId, dispatchNo, decision, effect });
+        const delivered = enqueuePlanReviewOutcome(prompt, { taskId, dispatchNo, decision, effect });
         if (!delivered) {
-            hostLog('error', `planReviewWire: outcome enqueue MISSED (queue port not installed or lacks enqueueMetaPrompt) for task ${taskId} — model will not learn the ${decision} result`);
+            if (onOutcome !== undefined) {
+                hostLog('debug', `planReviewWire: outcome queue port not installed for task ${taskId} — outcome handed to the host's onOutcome callback only`);
+            }
+            else {
+                hostLog('error', `planReviewWire: outcome enqueue MISSED (queue port not installed or lacks enqueueMetaPrompt) for task ${taskId} — model will not learn the ${decision} result`);
+            }
         }
     }
     catch (e) {
         hostLog('debug', `planReviewWire: outcome enqueue threw: ${String(e)}`);
     }
+    if (onOutcome !== undefined) {
+        try {
+            onOutcome({ taskId, dispatchNo, decision, effect, detail: outcome, tail, prompt, ...(statusSeen !== undefined ? { status: statusSeen } : {}) });
+        }
+        catch (e) {
+            hostLog('debug', `planReviewWire: onOutcome callback threw for task ${taskId} (ignored): ${String(e)}`);
+        }
+    }
 }
 function reopenIdSuffix() {
     return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
@@ -545,6 +646,9 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
         if (opts?.deliverDecision !== undefined) {
             hostLog('debug', `planReviewWire: reopen canonical-reuse branch for task ${taskId} ignores opts.deliverDecision (answers route through the existing arm responder — documented exception)`);
         }
+        if (opts?.wire !== undefined || opts?.onOutcome !== undefined) {
+            hostLog('debug', `planReviewWire: reopen canonical-reuse branch for task ${taskId} ignores opts.wire / opts.onOutcome (answers route through the existing arm responder and the wire it was armed with — documented exception)`);
+        }
         retireActiveReopen(sessionKey, canonicalId);
         if (receiptMs !== undefined) {
             const receipt = waitForGateArmedFor(sessionKey, [canonicalId], receiptMs);
@@ -571,10 +675,13 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
     publishQuestionFrameFor(sessionKey, { type: 'question_complete', questionId: canonicalId });
     const questionId = `${canonicalId}${REOPEN_ID_TAIL}${reopenIdSuffix()}`;
     hostLog('debug', `planReviewWire: reopen for task ${taskId} minting a fresh card ${questionId} (path=reopen-fresh)`);
+    const delivery = opts?.wire !== undefined || opts?.onOutcome !== undefined
+        ? { ...(opts.wire !== undefined ? { wire: opts.wire } : {}), ...(opts.onOutcome !== undefined ? { onOutcome: opts.onOutcome } : {}) }
+        : undefined;
     const deliver = opts?.deliverDecision ??
         ((tid, decision) => {
             hostLog('debug', `planReviewWire: reopen responder delivering ${decision} for task ${tid} (path=reopen-default)`);
-            void decidePlanReview(tid, decision);
+            void (delivery === undefined ? decidePlanReview(tid, decision) : decidePlanReview(tid, decision, undefined, delivery));
         });
     const activeKey = `${sessionKey}\u0000${canonicalId}`;
     const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
@@ -724,7 +831,7 @@ export function reopenPlanReviewCard(taskId, opts) {
         if (!hasQuestionOverlayFor(sessionKey)) {
             return receiptMs === undefined ? { reopened: false } : Promise.resolve({ reopened: false });
         }
-        if (sessionKey !== DEFAULT_SESSION_KEY && opts?.deliverDecision === undefined) {
+        if (sessionKey !== DEFAULT_SESSION_KEY && opts?.deliverDecision === undefined && opts?.wire === undefined) {
             hostLog('error', `planReviewWire: plan_review 卡未重开 —— sessionKey=${JSON.stringify(sessionKey)} 是非默认槽,` +
                 '而缺省决断投递口(decidePlanReview)今天固定打默认槽的 baseUrl/token/principal。' +
                 '整条链转 keyed 之前,非默认槽要重开请自带 deliverDecision(按本槽投递);' +

package/dist/hitl/sessionPolicyDeliverable.d.ts

@@ -11,5 +11,7 @@ export interface SessionPolicyDeliverability {
     readonly withheld: readonly SessionPolicyWithheldRule[];
     readonly unreadable?: true;
 }
+export declare function isEngineRefusedToolName(name: string): boolean;
 export declare function sessionPolicyDeliverable(behavior: 'deny' | 'ask', rules: readonly string[]): SessionPolicyDeliverability;
 export declare function sessionPolicyWithheldNotice(why: SessionPolicyWithheldWhy): string;
+export declare function legacyToolNameFailureNoteOf(code: string | undefined): string | undefined;

package/dist/hitl/sessionPolicyDeliverable.js

@@ -1,3 +1,4 @@
+import { CONFIG_LEGACY_TOOL_NAME } from '../engineErrorCodes.js';
 const COVERING_NAMESPACE_PREFIXES = ['mcp__', 'a2a__'];
 const ENGINE_RETIRED_TOOL_NAMES = new Map([
     ['read_file', 'Read'],
@@ -71,12 +72,17 @@ function withheldWhyOf(rule) {
     }
     if (rule.trim() !== rule)
         return 'not_a_tool_name';
-    if (ENGINE_RETIRED_TOOL_NAMES.has(rule))
-        return 'legacy_tool_name';
-    if (rule.includes('__') && !COVERING_NAMESPACE_PREFIXES.some((prefix) => rule.startsWith(prefix)))
+    if (isEngineRefusedToolName(rule))
         return 'legacy_tool_name';
     return undefined;
 }
+export function isEngineRefusedToolName(name) {
+    if (typeof name !== 'string')
+        return false;
+    if (ENGINE_RETIRED_TOOL_NAMES.has(name))
+        return true;
+    return name.includes('__') && !COVERING_NAMESPACE_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
 export function sessionPolicyDeliverable(behavior, rules) {
     const entries = [];
     try {
@@ -128,3 +134,8 @@ export function sessionPolicyWithheldNotice(why) {
         ? WITHHELD_NOTICE[why]
         : 'Not written to this session’s rule record.';
 }
+const LEGACY_TOOL_NAME_FAILURE_NOTE = `This run did not start: a tool rule applied to it names a tool the engine refuses — a retired tool name, or a name that contains "__" but does not start with ${PREFIXES_IN_PROSE} (the engine's own error text names the entry). ` +
+    'Every later run fails the same way until that entry is removed from wherever it is set: this session’s rule record, the settings sent with the run, a parent session’s rule record, or the deployment’s own tool rules.';
+export function legacyToolNameFailureNoteOf(code) {
+    return code === CONFIG_LEGACY_TOOL_NAME ? LEGACY_TOOL_NAME_FAILURE_NOTE : undefined;
+}

package/dist/hitl/sessionPolicyWire.d.ts

@@ -1,5 +1,6 @@
 import type { SessionPermissionRules, StoredSessionRules } from '@sema-agent/sdk';
 import type { SessionPolicyReading } from '../sessionPolicyCapability.js';
+import type { ToolRosterView } from '../toolRoster.js';
 export interface SessionPolicyFacade {
     getPolicy(sessionId: string, opts?: {
         signal?: AbortSignal;
@@ -93,3 +94,42 @@ export declare function tightenSessionPolicy(facade: SessionPolicyFacade, req: S
     signal?: AbortSignal;
 }): Promise<SessionPolicyTightenOutcome>;
 export declare function sessionPolicyTightenNotice(outcome: SessionPolicyTightenOutcome): string;
+export interface SessionPolicyRemovedEntry {
+    readonly field: 'toolDeny' | 'toolAllow';
+    readonly rule: string;
+}
+export type SessionPolicyRemovalOutcome = {
+    kind: 'roster_required';
+    why: SessionPolicyRosterRequiredWhy;
+} | {
+    kind: 'removed';
+    rev: number;
+    removed: readonly SessionPolicyRemovedEntry[];
+} | {
+    kind: 'nothing_to_remove';
+    rev: number;
+} | {
+    kind: 'loosen_forbidden';
+    message: string;
+    refused: readonly SessionPolicyRemovedEntry[];
+} | {
+    kind: 'conflict';
+    rev: number;
+} | {
+    kind: 'read_failed';
+    why: Extract<SessionPolicyTightenUnknownWhy, 'face_unavailable' | 'session_not_found' | 'session_ownerless' | 'unauthorized' | 'request_rejected' | 'store_corrupt' | 'read_unreadable' | 'read_failed'>;
+    message?: string;
+} | {
+    kind: 'write_refused';
+    why: Extract<SessionPolicyTightenUnknownWhy, 'face_unavailable' | 'session_not_found' | 'session_ownerless' | 'unauthorized' | 'request_rejected' | 'store_corrupt' | 'write_refused'>;
+    message?: string;
+} | {
+    kind: 'write_unconfirmed';
+    why: Extract<SessionPolicyTightenUnknownWhy, 'write_indeterminate' | 'write_receipt_unreadable' | 'write_receipt_mismatch'>;
+    message?: string;
+};
+export type SessionPolicyRosterRequiredWhy = 'absent' | 'unreadable';
+export declare function removeRefusedSessionRules(facade: SessionPolicyFacade, sessionId: string, roster: ToolRosterView | undefined, opts?: {
+    signal?: AbortSignal;
+}): Promise<SessionPolicyRemovalOutcome>;
+export declare function sessionPolicyRemovalNotice(outcome: SessionPolicyRemovalOutcome): string;

package/dist/hitl/sessionPolicyWire.js

@@ -1,5 +1,6 @@
 import { wireFailureShapeOf } from '../wireFailureShape.js';
 import { hostLog } from '../host.js';
+import { isEngineRefusedToolName } from './sessionPolicyDeliverable.js';
 const RULE_FIELD_PRESENCE = {
     toolAllow: true,
     toolDeny: true,
@@ -306,3 +307,212 @@ export function sessionPolicyTightenNotice(outcome) {
             }
     }
 }
+function rosterMountedNames(roster) {
+    if (roster === undefined || roster === null)
+        return 'absent';
+    try {
+        if (typeof roster !== 'object' || Array.isArray(roster))
+            return 'unreadable';
+        const entries = roster.entries;
+        if (!Array.isArray(entries))
+            return 'unreadable';
+        const names = new Set();
+        const n = entries.length;
+        for (let i = 0; i < n; i++) {
+            if (!Object.hasOwn(entries, i))
+                return 'unreadable';
+            const row = entries[i];
+            if (typeof row !== 'object' || row === null)
+                return 'unreadable';
+            const name = row.name;
+            if (typeof name !== 'string' || name.length === 0)
+                return 'unreadable';
+            names.add(name);
+            const aliases = row.aliases;
+            if (aliases === undefined)
+                continue;
+            if (!Array.isArray(aliases))
+                return 'unreadable';
+            for (const a of aliases) {
+                if (typeof a !== 'string')
+                    return 'unreadable';
+                names.add(a);
+            }
+        }
+        return names;
+    }
+    catch {
+        return 'unreadable';
+    }
+}
+function withoutRefusedEntries(prior, mounted) {
+    const REFUSABLE_NAME_FIELDS = ['toolDeny', 'toolAllow'];
+    const isRefusable = (f) => REFUSABLE_NAME_FIELDS.includes(f);
+    const next = {};
+    const removed = [];
+    for (const field of SESSION_POLICY_RULE_FIELDS) {
+        const list = Object.hasOwn(prior, field) ? prior[field] : undefined;
+        if (list === undefined)
+            continue;
+        if (!isRefusable(field)) {
+            next[field] = [...list];
+            continue;
+        }
+        const kept = [];
+        const seen = new Set();
+        for (const x of list) {
+            if (!isEngineRefusedToolName(x) || mounted.has(x)) {
+                kept.push(x);
+                continue;
+            }
+            if (seen.has(x))
+                continue;
+            seen.add(x);
+            removed.push({ field, rule: x });
+        }
+        next[field] = kept;
+    }
+    return { next, removed };
+}
+function removalFailed(failure, leg) {
+    const u = unknownFrom(failure, leg);
+    const message = u.message;
+    switch (u.why) {
+        case 'write_indeterminate':
+            return { kind: 'write_unconfirmed', why: 'write_indeterminate', ...(message !== undefined ? { message } : {}) };
+        case 'read_failed':
+        case 'read_unreadable':
+            return { kind: 'read_failed', why: u.why, ...(message !== undefined ? { message } : {}) };
+        case 'write_refused':
+            return { kind: 'write_refused', why: 'write_refused', ...(message !== undefined ? { message } : {}) };
+        case 'face_unavailable':
+        case 'session_not_found':
+        case 'session_ownerless':
+        case 'unauthorized':
+        case 'request_rejected':
+        case 'store_corrupt':
+            return leg === 'read'
+                ? { kind: 'read_failed', why: u.why, ...(message !== undefined ? { message } : {}) }
+                : { kind: 'write_refused', why: u.why, ...(message !== undefined ? { message } : {}) };
+        default:
+            return leg === 'read'
+                ? { kind: 'read_failed', why: 'read_failed', ...(message !== undefined ? { message } : {}) }
+                : { kind: 'write_unconfirmed', why: 'write_indeterminate', ...(message !== undefined ? { message } : {}) };
+    }
+}
+async function attemptRemoval(facade, sessionId, mounted, opts) {
+    const read = await readSessionPolicy(facade, sessionId, opts);
+    if (read.kind === 'failed')
+        return { done: removalFailed(read.failure, 'read') };
+    if (read.kind === 'malformed')
+        return { done: { kind: 'read_failed', why: 'read_unreadable', message: read.detail } };
+    const { next, removed } = withoutRefusedEntries(read.rules, mounted);
+    if (removed.length === 0)
+        return { done: { kind: 'nothing_to_remove', rev: read.rev } };
+    let receipt;
+    try {
+        receipt = await facade.putPolicy(sessionId, { rules: next, expectedRev: read.rev }, opts);
+    }
+    catch (e) {
+        const failure = classifySessionPolicyFailure(e);
+        if (failure.kind === 'loosen-forbidden')
+            return { done: { kind: 'loosen_forbidden', message: failure.message, refused: removed } };
+        if (failure.kind === 'cas-conflict')
+            return { retryAtRev: read.rev };
+        return { done: removalFailed(failure, 'write') };
+    }
+    let narrowed;
+    try {
+        narrowed = narrowStoredRecord(receipt);
+    }
+    catch {
+        narrowed = { ok: false, why: 'envelope', detail: 'policy write receipt could not be read' };
+    }
+    if (!narrowed.ok)
+        return { done: { kind: 'write_unconfirmed', why: 'write_receipt_unreadable', message: narrowed.detail } };
+    const mismatch = receiptMismatch(next, narrowed.rules, read.rev, narrowed.rev) ??
+        (removed.some((e) => {
+            const r = Object.hasOwn(narrowed.rules, e.field) ? narrowed.rules[e.field] : undefined;
+            return r !== undefined && r.includes(e.rule);
+        })
+            ? 'the write receipt still holds an entry that was sent for removal'
+            : null);
+    if (mismatch !== null)
+        return { done: { kind: 'write_unconfirmed', why: 'write_receipt_mismatch', message: mismatch } };
+    return { done: { kind: 'removed', rev: narrowed.rev, removed } };
+}
+export async function removeRefusedSessionRules(facade, sessionId, roster, opts) {
+    const mounted = rosterMountedNames(roster);
+    if (typeof mounted === 'string')
+        return { kind: 'roster_required', why: mounted };
+    const first = await attemptRemoval(facade, sessionId, mounted, opts);
+    if ('done' in first)
+        return first.done;
+    hostLog('debug', 'sessionPolicyWire: the session rule record moved between this read and this removal — re-reading once and judging the other writer’s record again');
+    const second = await attemptRemoval(facade, sessionId, mounted, opts);
+    if ('done' in second)
+        return second.done;
+    return { kind: 'conflict', rev: second.retryAtRev };
+}
+export function sessionPolicyRemovalNotice(outcome) {
+    const generic = 'The session’s rule record may not have changed — re-read it before doing anything else.';
+    if (outcome === null || typeof outcome !== 'object')
+        return generic;
+    switch (outcome.kind) {
+        case 'roster_required':
+            return outcome.why === 'unreadable'
+                ? 'The tool roster supplied for this removal could not be read, so nothing was changed: without it an entry that looks refused may name a tool this deployment mounts itself, and removing it would lift a restriction that is in effect. Supply the tool roster exactly as read from a run’s assembly manifest and try again.'
+                : 'No tool roster was supplied for this removal, so nothing was changed: without it an entry that looks refused may name a tool this deployment mounts itself, and removing it would lift a restriction that is in effect. Supply the tool roster from a run of this session on this deployment (a run that fails at startup reports none) and try again.';
+        case 'removed': {
+            const list = Array.isArray(outcome.removed) ? outcome.removed : [];
+            const n = list.length;
+            const what = n === 1 ? '1 entry' : `${n} entries`;
+            const fields = new Set(list.map((e) => (typeof e === 'object' && e !== null ? e.field : undefined)));
+            const deny = fields.has('toolDeny')
+                ? ' Removing names from the deny list lifts no block on any tool mounted for this session’s runs; to block such a tool under its current name, add a new deny rule with that name.'
+                : '';
+            const allow = fields.has('toolAllow')
+                ? ' Removing names from the allow list allows nothing new: the tools those names were meant to allow stay outside it, and an allow list left empty allows no tool at all; to allow such a tool under its current name, add its current name to the allow list.'
+                : '';
+            return `Removed ${what} from this session’s rule record (now at version ${outcome.rev}): ${n === 1 ? 'it names' : 'each names'} a tool the engine refuses, and no tool in the supplied roster answers to ${n === 1 ? 'it' : 'those names'}; this record no longer stops the session’s runs from starting.${deny}${allow}`;
+        }
+        case 'nothing_to_remove':
+            return 'This session’s rule record holds no entry naming a tool the engine refuses that the supplied roster does not mount, so nothing was changed. If runs still fail at startup over a refused tool name, that entry is set somewhere this record does not cover — the settings sent with the run, a parent session’s rule record, or the deployment’s own tool rules — or it is a name the engine refuses that this version does not yet recognise, or the failing run does not mount a tool the supplied roster has under that name.';
+        case 'loosen_forbidden':
+            return 'The engine refused to take these entries out of this session’s rule record: on this engine only an operator can remove entries from it, so the record is unchanged. Ask an operator to remove them, or continue in a new session.';
+        case 'conflict':
+            return 'This session’s rule record was changed by someone else while the refused entries were being removed, twice in a row — nothing was changed. Try again once the other change has finished.';
+        case 'read_failed':
+            switch (outcome.why) {
+                case 'face_unavailable':
+                    return 'This deployment does not keep per-session tool rules, so there is no session rule record to remove entries from — nothing was changed.';
+                case 'session_not_found':
+                    return 'This session is not readable from here — it may not exist, or it may belong to someone else; nothing was changed.';
+                case 'session_ownerless':
+                    return 'This session has no owner, so it has no session rule record to change; nothing was changed.';
+                case 'unauthorized':
+                    return 'This call could not present a verifiable identity, so nothing was changed.';
+                case 'store_corrupt':
+                    return 'The engine could not establish which version this session’s rules are at, so nothing was changed. This needs an operator to look at the rule store.';
+                case 'read_unreadable':
+                    return 'The session’s current rules could not be read, so nothing was changed — rewriting a record that cannot be read could replace real restrictions.';
+                default:
+                    return 'The session’s current rules could not be fetched, so nothing was changed.';
+            }
+        case 'write_refused':
+            switch (outcome.why) {
+                case 'store_corrupt':
+                    return 'The engine could not establish which version this session’s rules are at and refused to stamp a new one, so nothing was changed. This needs an operator to look at the rule store.';
+                case 'session_not_found':
+                    return 'This session is not writable from here — it may not exist, or it may belong to someone else; nothing was changed.';
+                case 'unauthorized':
+                    return 'This call could not present a verifiable identity, so nothing was changed.';
+                default:
+                    return 'The engine refused this change, so nothing was changed. Re-read the session’s rules before trying again.';
+            }
+        case 'write_unconfirmed':
+            return 'The removal was sent but no clear answer came back from the engine — it may already be in effect. Run the removal again: it re-reads the record, and reports nothing left to remove if it did take effect.';
+        default:
+            return generic;
+    }
+}

package/dist/hitl/toolApprovalWire.js

@@ -282,7 +282,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                         kind: 'failed',
                         stage: 'decide',
                         gatedCallId,
-                        reason: `decide(approve) failed: ${String(e)}${decideFailureNote(e)}`,
+                        reason: `decide(approve) failed: ${String(e)}${decideFailureNote(e, 'approve')}`,
                         ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
                         ...(currentPending !== undefined ? { currentPending } : {}),
                         ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
@@ -339,7 +339,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                         kind: 'failed',
                         stage: 'decide',
                         gatedCallId,
-                        reason: `decide(deny) failed: ${String(e)}${decideFailureNote(e)}`,
+                        reason: `decide(deny) failed: ${String(e)}${decideFailureNote(e, 'deny')}`,
                         ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
                         ...(currentPending !== undefined ? { currentPending } : {}),
                         ...(wireCode !== undefined ? { errorCode: wireCode } : {}),