@sema-agent/client-core 0.85.2 → 0.87.0

package/dist/gateOutcome.js

@@ -50,6 +50,39 @@ function readSettlement(v) {
         ...(note !== undefined ? { note } : {}),
     };
 }
+function nonEmptyStringList(v) {
+    if (!Array.isArray(v) || v.length === 0)
+        return undefined;
+    const out = [];
+    for (const x of v) {
+        const t = str(x);
+        if (t === undefined)
+            return undefined;
+        out.push(t);
+    }
+    return Object.freeze(out);
+}
+function readModeRelease(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const r = raw;
+    const mode = str(r.mode);
+    const askClass = str(r.askClass);
+    const classes = nonEmptyStringList(r.classes);
+    if (mode === undefined || askClass === undefined || classes === undefined)
+        return undefined;
+    const origin = str(r.origin);
+    const mandate = str(r.mandate);
+    const reason = str(r.reason);
+    return {
+        mode,
+        askClass,
+        classes,
+        ...(origin !== undefined ? { origin } : {}),
+        ...(mandate !== undefined ? { mandate } : {}),
+        ...(reason !== undefined ? { reason } : {}),
+    };
+}
 function readClassifierRound(raw) {
     if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
         return undefined;
@@ -85,18 +118,29 @@ export function gateOutcomeOf(frame) {
     let disposition;
     const classifier = readClassifierRound(dr.classifier);
     if (dk === 'allowed') {
-        disposition = { kind: 'allowed', ...(classifier !== undefined ? { classifier } : {}) };
+        const released = readModeRelease(dr.released);
+        disposition = {
+            kind: 'allowed',
+            ...(classifier !== undefined ? { classifier } : {}),
+            ...(released !== undefined ? { released } : {}),
+        };
     }
     else if (dk === 'denied') {
         const deniedBy = str(dr.deniedBy);
         if (deniedBy === undefined)
             return undefined;
         const cause = str(dr.cause);
+        const mode = str(dr.mode);
+        const askClass = str(dr.askClass);
+        const classes = nonEmptyStringList(dr.classes);
         disposition = {
             kind: 'denied',
             deniedBy,
             ...(cause !== undefined ? { cause } : {}),
             ...(classifier !== undefined ? { classifier } : {}),
+            ...(mode !== undefined ? { mode } : {}),
+            ...(askClass !== undefined ? { askClass } : {}),
+            ...(classes !== undefined ? { classes } : {}),
         };
     }
     else {
@@ -115,6 +159,9 @@ export function isGateParkedToolEnd(frame) {
         return false;
     return frame.errorCode === GATE_PARKED_ERROR_CODE;
 }
+export function gateModeRelease(g) {
+    return g?.disposition.kind === 'allowed' ? g.disposition.released : undefined;
+}
 export function isDeniedGate(g) {
     return g?.disposition.kind === 'denied';
 }

package/dist/gateVocabulary.d.ts

@@ -1,12 +1,14 @@
-import type { DeniedBy } from '@sema-agent/sdk';
+import { CORE_DENIED_BY_VALUES } from './generated/engineFactTables.js';
 import type { APPROVAL_MANDATE_WORDS } from './hitl/toolApprovalWire.js';
 export declare const CC_TOOL_DENIAL_KINDS: readonly ["user-rejected", "permission-rule", "automode-blocked", "automode-unavailable", "automode-parsing-error", "interrupted", "cancelled"];
 export type CcToolDenialKind = (typeof CC_TOOL_DENIAL_KINDS)[number];
 export declare function isCcToolDenialKind(v: unknown): v is CcToolDenialKind;
 export declare function isCcToolDenialKindADenial(v: unknown): boolean;
 export declare function ccToolDenialKindForSettledBy(settledBy: unknown): CcToolDenialKind | undefined;
-export declare const GATE_DENIED_BY_WORDS: readonly DeniedBy[];
-export declare function isGateDeniedByWord(v: unknown): v is DeniedBy;
+declare const RETIRED_DENIED_BY_WORDS: readonly ["plan_mode"];
+export type GateDeniedByWord = (typeof CORE_DENIED_BY_VALUES)[number] | (typeof RETIRED_DENIED_BY_WORDS)[number];
+export declare const GATE_DENIED_BY_WORDS: readonly GateDeniedByWord[];
+export declare function isGateDeniedByWord(v: unknown): v is GateDeniedByWord;
 export declare function gateDeniedByDetail(deniedBy: unknown): string;
 export declare function askOriginDetail(origin: unknown, message?: unknown): string;
 export declare const RULE_STORE_UNREADABLE_KINDS: readonly ["store", "call"];
@@ -17,3 +19,4 @@ export declare function mandatedApprovalDetail(): string;
 export type ApprovalMandateWord = (typeof APPROVAL_MANDATE_WORDS)[number];
 export declare function isApprovalMandateWord(v: unknown): v is ApprovalMandateWord;
 export declare function approvalMandateDetail(word: ApprovalMandateWord): string;
+export {};

package/dist/gateVocabulary.js

@@ -1,3 +1,4 @@
+import { CORE_DENIED_BY_VALUES } from './generated/engineFactTables.js';
 export const CC_TOOL_DENIAL_KINDS = Object.freeze([
     'user-rejected',
     'permission-rule',
@@ -20,18 +21,10 @@ export function ccToolDenialKindForSettledBy(settledBy) {
         return 'permission-rule';
     return undefined;
 }
-export const GATE_DENIED_BY_WORDS = Object.freeze([
-    'policy',
-    'hook',
-    'org',
-    'persisted_rule',
-    'classifier',
-    'plan_mode',
-    'compliance',
-    'write_protection',
-    'ask_resolution',
-    'read_boundary',
-]);
+const RETIRED_DENIED_BY_WORDS = Object.freeze(['plan_mode']);
+export const GATE_DENIED_BY_WORDS = Object.freeze([...CORE_DENIED_BY_VALUES, ...RETIRED_DENIED_BY_WORDS]);
+const _deniedByWordsPin = true;
+void _deniedByWordsPin;
 const DENIED_BY_SENTENCES = Object.freeze({
     policy: "denied by this deployment's permission policy",
     hook: 'denied by a PreToolUse hook',
@@ -43,6 +36,7 @@ const DENIED_BY_SENTENCES = Object.freeze({
     write_protection: 'denied because the write landed on a write-protected path',
     ask_resolution: 'denied when the approval was resolved',
     read_boundary: 'denied by the read boundary',
+    mode: "denied by this session's permission mode",
 });
 export function isGateDeniedByWord(v) {
     return typeof v === 'string' && GATE_DENIED_BY_WORDS.includes(v);
@@ -63,7 +57,7 @@ const ASK_ORIGIN_SENTENCES = Object.freeze({
     hook: 'a PreToolUse hook asked about this call',
     ask_rule: 'a persisted ask rule matches this call',
     denial_limit_fallback: 'the auto-mode classifier hit its denial limit and handed this call back to you',
-    shell_gate_tighten: 'this deployment asks about shell commands the coarse shell gate rates above this tier',
+    shell_gate_tighten: 'the coarse shell check rates this command above the tier it lets through, so it asks',
     safety_tighten: 'the gate tightened on this call’s own facts (network egress, irreversibility, or a protected write)',
     policy: 'this deployment’s permission policy asks about this call',
 });
@@ -82,8 +76,6 @@ export function askOriginDetail(origin, message) {
     const word = typeof origin === 'string' && origin.length > 0 ? origin : '(none)';
     return `this call asks; its origin ${word} is a word newer than this client, so answer it as usual`;
 }
-const _deniedByWordsPin = GATE_DENIED_BY_WORDS;
-void _deniedByWordsPin;
 export const RULE_STORE_UNREADABLE_KINDS = Object.freeze(['store', 'call']);
 const RULE_STORE_UNREADABLE_SET = new Set(RULE_STORE_UNREADABLE_KINDS);
 export function isRuleStoreUnreadableKind(v) {

package/dist/generated/engineFactTables.d.ts

@@ -0,0 +1,10 @@
+export declare const CORE_ASK_UNRESOLVABLE_CAUSES: readonly string[];
+export declare const CORE_DURABLE_MANDATE_SOURCES: readonly string[];
+export declare const CORE_TERMINAL_CAUSE_KINDS: readonly ["completed", "failed", "blocked", "paused"];
+export declare const CORE_RESERVED_AGENT_NAMES: readonly string[];
+export declare const CORE_WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS: Readonly<Record<"small" | "medium" | "large", number>>;
+export declare const CORE_ENGINE_AUTHORITY_ENVELOPE_TAGS: readonly string[];
+export declare const CORE_DENIED_BY_VALUES: readonly ["policy", "hook", "org", "persisted_rule", "classifier", "compliance", "write_protection", "ask_resolution", "read_boundary", "mode"];
+export declare const CORE_PERMISSION_MODE_FOLD_REASONS: readonly string[];
+export declare const CORE_ENGINE_CARD_TYPES: readonly string[];
+export declare const CORE_TOOL_DECLARATION_CODES: readonly string[];

package/dist/generated/engineFactTables.js

@@ -0,0 +1,113 @@
+export const CORE_ASK_UNRESOLVABLE_CAUSES = Object.freeze([
+    "approver_unavailable",
+    "no_approver_wired",
+    "mandate_unreconstructible",
+]);
+export const CORE_DURABLE_MANDATE_SOURCES = Object.freeze([
+    "force_durable_gate",
+    "durable_approval",
+]);
+export const CORE_TERMINAL_CAUSE_KINDS = Object.freeze([
+    "completed",
+    "failed",
+    "blocked",
+    "paused",
+]);
+export const CORE_RESERVED_AGENT_NAMES = Object.freeze([
+    "StructuredOutput",
+    "ToolSearch",
+    "ReadToolResult",
+    "ReportBlocked",
+    "Agent",
+]);
+export const CORE_WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS = Object.freeze({
+    "small": 5,
+    "medium": 15,
+    "large": 50,
+});
+export const CORE_ENGINE_AUTHORITY_ENVELOPE_TAGS = Object.freeze([
+    "system-reminder",
+    "task-notification",
+    "new-diagnostics",
+    "user_memory",
+    "scope",
+    "skills",
+    "total_tokens",
+    "instruction-files",
+]);
+export const CORE_DENIED_BY_VALUES = Object.freeze([
+    "policy",
+    "hook",
+    "org",
+    "persisted_rule",
+    "classifier",
+    "compliance",
+    "write_protection",
+    "ask_resolution",
+    "read_boundary",
+    "mode",
+]);
+export const CORE_PERMISSION_MODE_FOLD_REASONS = Object.freeze([
+    "operator_deny",
+    "face_absent",
+    "inherited_ceiling",
+]);
+export const CORE_ENGINE_CARD_TYPES = Object.freeze([
+    "mcp",
+    "a2a",
+    "path_not_in_root",
+    "read_path_denied",
+    "readonly_out_of_root",
+    "read_unestablished",
+    "text",
+    "notebook",
+    "file_unchanged",
+    "image",
+    "document",
+    "edit",
+    "create",
+    "update",
+    "notebook-edit",
+    "bash",
+    "bash_invalid_timeout",
+    "grep",
+    "glob",
+    "repo-map",
+    "artifact",
+    "worktree",
+    "task-output",
+    "task-stop",
+    "monitor-start",
+    "send-message",
+    "agent-transcript",
+    "list-agents",
+    "read-inbox",
+    "workflow-run",
+    "report-findings",
+    "tool-search",
+    "ask-question",
+    "exit-plan-mode",
+    "enter-plan-mode",
+    "cron-create",
+    "cron-delete",
+    "cron-list",
+    "schedule-wakeup",
+    "web-fetch",
+    "web-search",
+    "todo",
+    "task",
+    "task-list",
+    "agent",
+    "fork",
+]);
+export const CORE_TOOL_DECLARATION_CODES = Object.freeze([
+    "config.tool_mount_denied",
+    "config.tool_roster_bound",
+    "config.tool_name_too_long",
+    "config.tool_contract_too_long",
+    "config.tool_schema_bound",
+    "config.tool_face_invalid",
+    "config.tool_name_invalid",
+    "config.egress_requires_write_effect",
+    "config.reserved_tool_name",
+]);

package/dist/generated/engineNoticeTables.js

@@ -24,6 +24,11 @@ export const CORE_ENGINE_NOTICE_CODES = Object.freeze([
     "config.peer_admission_out_of_range",
     "config.peer_lane_unmounted",
     "config.secret_env_scrubbed",
+    "config.permission_mode_unavailable",
+    "permission.ask_released_by_mode",
+    "permission.read_deny_unapplied",
+    "permission.rule_store_unavailable",
+    "resume.legacy_mode_seed_migrated",
     "peer.inbound_disposition",
     "peer.held_settled",
     "peer.idle_subscription",
@@ -31,6 +36,7 @@ export const CORE_ENGINE_NOTICE_CODES = Object.freeze([
     "classifier.fallback",
     "classifier.role_defaulted",
     "classifier.contract_broken",
+    "classifier.unavailable",
     "checkpoint.execution_outcome_unrecorded",
     "delegation.transcript_integrity",
     "delegation.ask_unresolvable",
@@ -58,6 +64,7 @@ export const CORE_ENGINE_NOTICE_CODES = Object.freeze([
     "route.classifier_unroutable",
     "route.base_url_changed_key_unchanged",
     "route.response_model_mismatch",
+    "route.tool_call_id_folded",
     "task.user_steer_undrained",
     "task.user_followup_undrained",
     "steering.parked_input_blocked",
@@ -99,6 +106,11 @@ export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "config.peer_admission_out_of_range": "operator",
     "config.peer_lane_unmounted": "operator",
     "config.secret_env_scrubbed": "operator",
+    "config.permission_mode_unavailable": "user",
+    "permission.ask_released_by_mode": "user",
+    "permission.read_deny_unapplied": "user",
+    "permission.rule_store_unavailable": "user",
+    "resume.legacy_mode_seed_migrated": "operator",
     "peer.inbound_disposition": "user",
     "peer.held_settled": "user",
     "peer.idle_subscription": "user",
@@ -106,6 +118,7 @@ export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "classifier.fallback": "operator",
     "classifier.role_defaulted": "operator",
     "classifier.contract_broken": "operator",
+    "classifier.unavailable": "user",
     "checkpoint.execution_outcome_unrecorded": "operator",
     "delegation.transcript_integrity": "operator",
     "delegation.ask_unresolvable": "user",
@@ -133,6 +146,7 @@ export const CORE_NOTICE_AUDIENCE = Object.freeze({
     "route.classifier_unroutable": "operator",
     "route.base_url_changed_key_unchanged": "operator",
     "route.response_model_mismatch": "operator",
+    "route.tool_call_id_folded": "operator",
     "task.user_steer_undrained": "user",
     "task.user_followup_undrained": "user",
     "steering.parked_input_blocked": "user",

package/dist/hitl/crashConverged.d.ts

@@ -14,6 +14,7 @@ export interface CrashConvergedRow {
     readonly decidedAtMs?: number;
     readonly convergedAtMs: number;
     readonly resumeSafe: boolean;
+    readonly needsHumanReason?: 'approved_then_interrupted' | 'pending_unsafe' | 'unstable_row' | 'contradictory';
 }
 export interface ApprovalsListEnvelope {
     pending: PendingCheckpoint[];

package/dist/hitl/crashConverged.js

@@ -71,6 +71,15 @@ function readCrashConvergedRow(v) {
         return null;
     }
 }
+function needsHumanReasonOf(reading) {
+    if (reading.unstable)
+        return 'unstable_row';
+    if (reading.orphanState === 'pending' ? reading.hasApprovalEvidence : reading.resumeSafe === true)
+        return 'contradictory';
+    if (reading.orphanState === 'decided')
+        return 'approved_then_interrupted';
+    return 'pending_unsafe';
+}
 export function projectCrashConverged(env) {
     const resumeSafe = [];
     const needsHuman = [];
@@ -96,10 +105,16 @@ export function projectCrashConverged(env) {
             }
             const row = reading.row;
             const consistentlyUnexecuted = reading.orphanState === 'pending' && !reading.hasApprovalEvidence;
-            if (!reading.unstable && consistentlyUnexecuted && reading.resumeSafe === true)
+            if (!reading.unstable && consistentlyUnexecuted && reading.resumeSafe === true) {
+                Reflect.deleteProperty(row, 'needsHumanReason');
                 resumeSafe.push(row);
-            else
+            }
+            else {
+                Object.defineProperty(row, 'needsHumanReason', {
+                    value: needsHumanReasonOf(reading), enumerable: true, writable: true, configurable: true,
+                });
                 needsHuman.push(row);
+            }
         }
     }
     catch {

package/dist/hitl/hitlBridge.d.ts

@@ -47,6 +47,10 @@ export type PlanReviewModeAfter = (typeof PLAN_REVIEW_MODE_AFTER_WORDS)[number];
 export declare function isPlanReviewModeAfter(v: string | undefined): v is PlanReviewModeAfter;
 export type HitlSafetyCode = 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit' | 'bad_plan_mode' | 'empty_answer';
 export type HitlFailureStage = 'fetch' | 'input' | 'card' | 'decide' | 'orchestration';
+export declare const NO_APPROVAL_CARD_PORT_REASON = "no approval card port installed (print/non-REPL mode, or host forgot installApprovalCardPort)";
+export declare const APPROVAL_CARD_PORT_KEY_MISMATCH_REASON = "no approval card port installed for the default session key, but a non-default sessionKey has one \u2014 likely a keyed-install/default-read mismatch (installApprovalCardPortFor vs the zero-arg default-key read), not a missing install";
+export declare const NO_QUESTION_OVERLAY_REASON = "no question overlay mounted (print/non-REPL mode)";
+export declare function isNoDecisionSurfaceReason(reason: string): boolean;
 export interface HitlDecideDenyOutcome {
     decision: 'deny';
     reason?: string | undefined;

package/dist/hitl/hitlBridge.js

@@ -25,6 +25,12 @@ export const PLAN_REVIEW_MODE_AFTER_WORDS = Object.freeze(['default', 'acceptEdi
 export function isPlanReviewModeAfter(v) {
     return v !== undefined && PLAN_REVIEW_MODE_AFTER_WORDS.includes(v);
 }
+export const NO_APPROVAL_CARD_PORT_REASON = 'no approval card port installed (print/non-REPL mode, or host forgot installApprovalCardPort)';
+export const APPROVAL_CARD_PORT_KEY_MISMATCH_REASON = 'no approval card port installed for the default session key, but a non-default sessionKey has one — likely a keyed-install/default-read mismatch (installApprovalCardPortFor vs the zero-arg default-key read), not a missing install';
+export const NO_QUESTION_OVERLAY_REASON = 'no question overlay mounted (print/non-REPL mode)';
+export function isNoDecisionSurfaceReason(reason) {
+    return reason === NO_APPROVAL_CARD_PORT_REASON || reason === APPROVAL_CARD_PORT_KEY_MISMATCH_REASON || reason === NO_QUESTION_OVERLAY_REASON;
+}
 export class HitlSafetyError extends Error {
     code;
     constructor(message, code) {

package/dist/hitl/parkResolver.js

@@ -1,5 +1,5 @@
 import { putOwnKey } from '../ownKey.js';
-import { DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, findPendingForTask, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.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 { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
@@ -75,7 +75,7 @@ export function toAnsweredOutput(questions, answer) {
 }
 async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGatedCallId, onPresented) {
     if (!hasQuestionOverlay()) {
-        return { kind: 'failed', stage: 'card', reason: 'no question overlay mounted (print/non-REPL mode)' };
+        return { kind: 'failed', stage: 'card', reason: NO_QUESTION_OVERLAY_REASON };
     }
     const found = await findPendingForTask(deps.client, taskId, isAskTool, signal ? { signal } : undefined, parkGatedCallId, (row) => isAskTool(typeof row.toolName === 'string' ? row.toolName : undefined));
     if (!found.ok)
@@ -301,7 +301,8 @@ export async function resolvePark(park, ctx) {
             : outcome.kind === 'retracted'
                 ? 'the approval card was retracted by the host without a decision (nothing was sent; the run stays parked and remains decidable elsewhere)'
                 : undefined;
-        return { kind: 'failsoft', events: failsoftEvents(park, ctx, outcome.kind === 'aborted', failedReason) };
+        const noDecisionSurface = outcome.kind === 'failed' && outcome.stage === 'card' && isNoDecisionSurfaceReason(outcome.reason);
+        return { kind: 'failsoft', events: failsoftEvents(park, ctx, outcome.kind === 'aborted', failedReason, undefined, noDecisionSurface) };
     }
     led.dropHeldForDecidedPark(outcome.gatedCallId, park.gatedCallId);
     if (outcome.gatedCallId) {
@@ -324,7 +325,15 @@ export async function resolvePark(park, ctx) {
         ...(handoffTaskId !== undefined ? { handoffTaskId } : {}),
     };
 }
-function failsoftEvents(park, ctx, gateAbortedByUser, failedReason, terminal) {
+function failsoftReasonSentence(park, failedReason, terminal) {
+    if (terminal !== undefined)
+        return terminal.errorMessage;
+    if (failedReason === undefined)
+        return undefined;
+    return (`${park.gate === 'fs' ? 'Tool approval' : 'AskUserQuestion'} gate could not be answered: ${failedReason}` +
+        ' — the run is still parked on this approval: decide it on the card when it is shown again, or cancel the run.');
+}
+function failsoftEvents(park, ctx, gateAbortedByUser, failedReason, terminal, noDecisionSurface = false) {
     const events = [
         ...flushHeldWithInterruptRewrite(ctx.led, {
             terminal: park.pendingDone,
@@ -332,19 +341,15 @@ function failsoftEvents(park, ctx, gateAbortedByUser, failedReason, terminal) {
             gateAbortedByUser,
         }),
     ];
+    const reason = failsoftReasonSentence(park, failedReason, terminal);
     if (park.pendingDone) {
-        events.push(park.pendingDone);
+        events.push(reason === undefined || noDecisionSurface ? park.pendingDone : { ...park.pendingDone, _sema_park_failed_reason: reason });
     }
     else if (terminal !== undefined) {
         events.push({ type: 'failed', ...terminal });
     }
-    else if (failedReason !== undefined) {
-        events.push({
-            type: 'failed',
-            errorCode: 'hitl_unanswered',
-            errorMessage: `${park.gate === 'fs' ? 'Tool approval' : 'AskUserQuestion'} gate could not be answered: ${failedReason}` +
-                ' — the run is still parked on this approval: decide it on the card when it is shown again, or cancel the run.',
-        });
+    else if (reason !== undefined) {
+        events.push({ type: 'failed', errorCode: 'hitl_unanswered', errorMessage: reason });
     }
     return events;
 }

package/dist/hitl/refusedToolNameProse.d.ts

@@ -0,0 +1,4 @@
+export declare const PREFIXES_IN_PROSE: string;
+export declare const REFUSED_NAME_CLASSES: string;
+export declare const REFUSED_NAME_FIX: string;
+export declare const RULES_LEGACY_TOOL_NAME_WRITE_NOTE: string;

package/dist/hitl/refusedToolNameProse.js

@@ -0,0 +1,7 @@
+import { CORE_PROTOCOL_PREFIXES } from '../generated/toolNameTables.js';
+export const PREFIXES_IN_PROSE = CORE_PROTOCOL_PREFIXES.map((prefix) => `"${prefix}"`).join(' or ');
+export const REFUSED_NAME_CLASSES = `a retired tool name, or a name that contains "__" but does not start with ${PREFIXES_IN_PROSE}`;
+export const REFUSED_NAME_FIX = `If the tool still exists, use its current name; a server or agent-peer tool name starts with ${PREFIXES_IN_PROSE}.`;
+export const RULES_LEGACY_TOOL_NAME_WRITE_NOTE = `The engine refused to write these session rules, and the stored record was not changed at all: they name a tool the engine refuses — ${REFUSED_NAME_CLASSES} (the engine's own error text names the entry). ` +
+    `${REFUSED_NAME_FIX} Then write the rules again. ` +
+    'If that entry was already in this session’s rule record, it has to be removed from the record before the record can be written again.';

package/dist/hitl/sessionPolicyDeliverable.js

@@ -1,16 +1,16 @@
-import { CONFIG_LEGACY_TOOL_NAME } from '../engineErrorCodes.js';
+import { CONFIG_LEGACY_TOOL_NAME, RULES_LEGACY_TOOL_NAME } from '../engineErrorCodes.js';
 import { rosterMountedNames } from './rosterMountedNames.js';
+import { PREFIXES_IN_PROSE, REFUSED_NAME_CLASSES, REFUSED_NAME_FIX, RULES_LEGACY_TOOL_NAME_WRITE_NOTE } from './refusedToolNameProse.js';
 import { CORE_PROTOCOL_PREFIXES, CORE_RETIRED_TOOL_CURRENT_NAMES } from '../generated/toolNameTables.js';
 const COVERING_NAMESPACE_PREFIXES = CORE_PROTOCOL_PREFIXES;
 const ENGINE_RETIRED_TOOL_NAMES = CORE_RETIRED_TOOL_CURRENT_NAMES;
-const PREFIXES_IN_PROSE = COVERING_NAMESPACE_PREFIXES.map((prefix) => `"${prefix}"`).join(' or ');
 const WITHHELD_NOTICE = {
     ask_no_bucket: 'Not written to this session’s rule record: that record only holds rules that block outright, and this rule asks before running instead — recording it as a block would change what it means.',
     qualified_deny: 'Not written to this session’s rule record: that record holds whole tool names and command names only, and this rule has a part in parentheses it cannot carry — recording just the name could block more than this rule does.',
     peer_wide: 'Not written to this session’s rule record: this rule names a server or agent peer without naming one of its tools, and an engine that matches that record by exact tool name would block none of that peer’s tools.',
     wildcard: 'Not written to this session’s rule record: this rule uses a wildcard (*), and an engine that matches that record by exact tool name would block none of the tools it covers.',
     not_a_tool_name: 'Not written to this session’s rule record: this entry is not exactly one tool name — it is empty, not text, or has spaces around the name.',
-    legacy_tool_name: `Not written to this session’s rule record: unless a tool by exactly this name is available, the engine refuses it — it is a retired tool name, or it contains "__" but does not start with ${PREFIXES_IN_PROSE} — and with it in that record every later run of this session would fail at startup until that entry is removed from the record. If the tool still exists, use its current name; a server or agent-peer tool name starts with ${PREFIXES_IN_PROSE}.`,
+    legacy_tool_name: `Not written to this session’s rule record: unless a tool by exactly this name is available, the engine refuses it — it is a retired tool name, or it contains "__" but does not start with ${PREFIXES_IN_PROSE} — and with it in that record every later run of this session would fail at startup until that entry is removed from the record. ${REFUSED_NAME_FIX}`,
     not_in_roster: 'Not written to this session’s rule record: the tool roster supplied for this check has no tool by exactly this name, as a name or an alias, with letter case counted — it may be misspelled, or name a tool this deployment does not provide — so recorded as it is it would block nothing here.',
 };
 export const SESSION_POLICY_WITHHELD_WHY = Object.freeze(Object.keys(WITHHELD_NOTICE));
@@ -114,8 +114,12 @@ 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). ` +
+const LEGACY_TOOL_NAME_FAILURE_NOTE = `This run did not start: a tool rule applied to it names a tool the engine refuses — ${REFUSED_NAME_CLASSES} (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;
+    if (code === CONFIG_LEGACY_TOOL_NAME)
+        return LEGACY_TOOL_NAME_FAILURE_NOTE;
+    if (code === RULES_LEGACY_TOOL_NAME)
+        return RULES_LEGACY_TOOL_NAME_WRITE_NOTE;
+    return undefined;
 }

package/dist/hitl/sessionPolicyWire.d.ts

@@ -38,6 +38,11 @@ export type SessionPolicyFailure = {
 } | {
     kind: 'request-rejected';
     message: string;
+} | {
+    kind: 'legacy-tool-name';
+    message: string;
+    field?: SessionPolicyRemovedEntry['field'];
+    name?: string;
 } | {
     kind: 'unauthorized';
     message: string;
@@ -85,6 +90,12 @@ export type SessionPolicyTightenOutcome = {
 } | {
     kind: 'capability_absent';
     why: 'not_reported' | 'absent';
+} | {
+    kind: 'legacy_tool_name';
+    message: string;
+    field?: SessionPolicyRemovedEntry['field'];
+    name?: string;
+    alreadyInRecord?: boolean;
 } | {
     kind: 'unknown';
     why: SessionPolicyTightenUnknownWhy;
@@ -127,6 +138,11 @@ export type SessionPolicyRemovalOutcome = {
     kind: 'write_unconfirmed';
     why: Extract<SessionPolicyTightenUnknownWhy, 'write_indeterminate' | 'write_receipt_unreadable' | 'write_receipt_mismatch'>;
     message?: string;
+} | {
+    kind: 'legacy_tool_name';
+    message: string;
+    field?: SessionPolicyRemovedEntry['field'];
+    name?: string;
 };
 export type SessionPolicyRosterRequiredWhy = 'absent' | 'unreadable';
 export declare function removeRefusedSessionRules(facade: SessionPolicyFacade, sessionId: string, roster: ToolRosterView | undefined, opts?: {