@sema-agent/client-core 0.84.0 → 0.84.1

package/dist/hitl/parkResolver.js

@@ -1,6 +1,6 @@
 import { putOwnKey } from '../ownKey.js';
 import { DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, findPendingForTask, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
-import { RESUME_POLICY_FOLD_CODE } from '../engineErrorCodes.js';
+import { PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE } from '../engineErrorCodes.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
@@ -44,13 +44,16 @@ function isAlreadyResolvedFailure(outcome) {
     const code = 'code' in outcome && isGateFailureCode(outcome.code) ? outcome.code : undefined;
     if (code !== undefined)
         return code === 'no_pending';
-    if ('errorCode' in outcome && isGateStandingErrorCode(outcome.errorCode))
+    if ('errorCode' in outcome && isCodeClassifiedGateFailure(outcome.errorCode))
         return false;
     return isAlreadyResolvedGateReason(outcome.reason);
 }
 export function isGateStandingErrorCode(code) {
     return code === RESUME_POLICY_FOLD_CODE || code === 'corrupt';
 }
+export function isCodeClassifiedGateFailure(code) {
+    return isGateStandingErrorCode(code) || code === PARKED_RESUME_STARTUP_FAILED;
+}
 export function toAnsweredOutput(questions, answer) {
     const answers = {};
     const annotations = {};
@@ -122,10 +125,12 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
         return { kind: 'aborted', gatedCallId };
     }
     let declinedReceipt;
+    let attemptedDecision;
     try {
         const entries = answer.answers ?? [];
         const hasContent = entries.some(a => (a.selected?.length ?? 0) > 0 || (a.note?.length ?? 0) > 0);
         if (hasContent) {
+            attemptedDecision = 'approve';
             const raw = await bridge.answerQuestion(entries, gatedCallId, signal ? { signal } : undefined, pending);
             const receipt = readDecideReceipt(raw);
             return {
@@ -136,6 +141,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
             };
         }
         else {
+            attemptedDecision = 'deny';
             const raw = await bridge.decideTool({ decision: 'deny', reason: 'User declined to answer' }, gatedCallId, signal ? { signal } : undefined, pending);
             declinedReceipt = readDecideReceipt(raw);
         }
@@ -149,7 +155,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
             kind: 'failed',
             stage: 'decide',
             gatedCallId,
-            reason: `decide failed: ${String(e)}${decideFailureNote(e)}`,
+            reason: `decide failed: ${String(e)}${decideFailureNote(e, attemptedDecision)}`,
             ...(code !== undefined ? { code } : {}),
             ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
             ...(currentPending !== undefined ? { currentPending } : {}),

package/dist/hitl/planReviewWire.d.ts

@@ -1,5 +1,6 @@
 import { type QuestionAnswer } from '../liveQuestionStore.js';
 import { type PlanReviewModeAfter } from './hitlBridge.js';
+import type { AgentClient } from '@sema-agent/sdk';
 import type { ReopenCardVerdict } from '../adapter/activeRunSelfHeal.js';
 export declare const PLAN_REVIEW_APPROVE_LABEL = "Yes, approve and run the plan";
 export declare const PLAN_REVIEW_REJECT_LABEL = "No, reject it (keep planning)";
@@ -28,10 +29,13 @@ export declare function _resetArmedPlanReviewsForTest(): void;
 export type PlanReviewReopenTrigger = 'user' | 'automatic';
 export type PlanReviewGateInstanceReader = (taskId: string) => Promise<ReadonlySet<string> | null>;
 export declare function clearPlanReviewUserDismissals(sessionKey?: string): void;
-export declare function armPlanReviewApproval(result: unknown, sessionKey?: string, opts?: {
+export interface ArmPlanReviewOptions {
     submittedInPlanMode?: boolean;
     readGateInstanceKeys?: PlanReviewGateInstanceReader;
-}): boolean;
+    wire?: PlanReviewWire;
+    onOutcome?: PlanReviewDeliveryOptions['onOutcome'];
+}
+export declare function armPlanReviewApproval(result: unknown, sessionKey?: string, opts?: ArmPlanReviewOptions): boolean;
 export type PlanReviewDecisionEffect = 'took_effect' | 'advanced' | 'still_parked' | 'not_sent' | 'not_applied' | 'unconfirmed';
 export interface PlanReviewOutcomeMeta {
     taskId: string;
@@ -40,12 +44,35 @@ export interface PlanReviewOutcomeMeta {
     effect: PlanReviewDecisionEffect;
 }
 export declare function planReviewOutcomeTail(taskId: string, decision: 'approve' | 'reject', effect: PlanReviewDecisionEffect): string;
+export type PlanReviewWireClient = {
+    assistant: Pick<AgentClient['assistant'], 'planReview'>;
+    runs: Pick<AgentClient['runs'], 'get'>;
+};
+export interface PlanReviewWire {
+    client: PlanReviewWireClient;
+    capsBaseUrl?: string;
+}
+export interface PlanReviewDecisionOutcome extends PlanReviewOutcomeMeta {
+    detail: string;
+    tail: string;
+    prompt: string;
+    status?: string;
+}
+export interface PlanReviewDeliveryOptions {
+    wire?: PlanReviewWire;
+    onOutcome?: (outcome: PlanReviewDecisionOutcome) => void;
+}
+export interface DecidePlanReviewOptions extends PlanReviewDeliveryOptions {
+    reason?: string;
+}
 export declare function __resetPlanReviewDecisionLatchForTests(): void;
-export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject', permissionModeAfter?: string): Promise<void>;
+export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject', permissionModeAfter?: string, opts?: DecidePlanReviewOptions): Promise<void>;
 export interface ReopenPlanReviewOpts {
     mintFreshQuestionId?: boolean;
     deliverDecision?: (taskId: string, decision: 'approve' | 'reject') => void | Promise<void>;
     sessionKey?: string;
+    wire?: PlanReviewWire;
+    onOutcome?: PlanReviewDeliveryOptions['onOutcome'];
     presentationReceiptMs?: number;
     trigger?: PlanReviewReopenTrigger;
     readGateInstanceKeys?: PlanReviewGateInstanceReader;

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;