@sema-agent/client-core 0.89.0 → 0.91.0

package/dist/index.d.ts

@@ -31,6 +31,8 @@ export * from './executionLaneCapability.js';
 export * from './approvalsStreamLiveCapability.js';
 export * from './peerLaneCapability.js';
 export * from './permissionRulesWriteCapability.js';
+export { __resetPermissionsAllowGrantReadingsForTests, forgetPermissionsAllowGrantReading, noteEngineCapsForPermissionsAllowGrant, observedPermissionsAllowGrant, permissionsAllowGrantAvailable, permissionsAllowGrantDoctorDetail, projectPermissionsAllowGrantCapability, } from './permissionsAllowGrantCapability.js';
+export type { PermissionsAllowGrantReading } from './permissionsAllowGrantCapability.js';
 export * from './sessionPolicyCapability.js';
 export * from './memoryComplianceCapability.js';
 export * from './memoryOriginCapability.js';
@@ -67,7 +69,7 @@ export type { DisplayUntrustedOptions, DisplayMark, DisplayMarkSpan, DisplayUntr
 export type * from './types/engineState.js';
 export * from './hostEnv.js';
 export * from './unrefTimer.js';
-export { ControlRouter, ControlSafetyError, errCodes, type ControlClientLike, type ControlRouterOptions, type ControlSafetyCode, type ErrCodes, type QueuedCommand, type QueuePriority, type RunsResourceLike, } from './controlRouter.js';
+export { ControlRouter, ControlSafetyError, errCodes, steerRefusalAdviceOf, steeringRefusedBeforeEngine, type ControlClientLike, type ControlRouterOptions, type ControlSafetyCode, type ErrCodes, type QueuedCommand, type QueuePriority, type RunsResourceLike, type SteerRefusalAdvice, type SteeringRefusedBeforeEngine, } from './controlRouter.js';
 export * from './sseIdleTriage.js';
 export * from './engineWireSdk.js';
 export * from './classifierVerdictWire.js';
@@ -90,6 +92,8 @@ export * from './oneShotWireCaps.js';
 export * from './rewindWireCaps.js';
 export * from './rewindArchiveCapability.js';
 export * from './fileHistoryCaptureCapability.js';
+export { FILE_HISTORY_LEG_VERDICTS, fileHistoryLegNoticeVerdict, fileHistoryLegNoticeSentence, fileHistoryDeclarationOfBody, createFileHistoryDeclarationLedger, } from './fileHistoryLegNotice.js';
+export type { FileHistoryDeclarationFact, FileHistoryLegNoticeVerdict, FileHistoryLegNoticeInput, FileHistoryDeclarationLedger } from './fileHistoryLegNotice.js';
 export * from './sealedKeyCapability.js';
 export * from './storePostureCapability.js';
 export * from './centerWiringCapability.js';
@@ -107,15 +111,18 @@ export * from './effortWire.js';
 export * from './adapter/types.js';
 export * from './adapter/downstream/turnUsageToModelUsage.js';
 export * from './adapter/downstream/eventToSdkMessage.js';
-export type { WiringManifestView, WiringManifestSections } from './adapter/downstream/wiringManifestView.js';
+export type { WiringManifestView, WiringManifestSections, WiringManifestFleetView } from './adapter/downstream/wiringManifestView.js';
 export * from './adapter/downstream/terminalToSdkResult.js';
 export * from './adapter/runStream.js';
 export * from './adapter/activeRunSelfHeal.js';
 export * from './request/taskRequest.js';
-export { disableSkillsDeclaration } from './disableSkillsWire.js';
+export { disableSkillsDeclaration, disableSkillsDeclarationSettled } from './disableSkillsWire.js';
 export type { DisableSkillsDeclaration } from './disableSkillsWire.js';
+export { PERMISSIONS_KEPT_REASONS, permissionsDeclaration, permissionsDeclarationReport } from './permissionsDeclaration.js';
+export type { PermissionsDeclaration, PermissionsDeclarationBuckets, PermissionsDeclarationInput, PermissionsDeclarationReport, PermissionsKeptReason, PermissionsKeptRule, PermissionsRewrittenRule, PermissionsUncheckedRule, WireRuleOrigin, WireRuleOrigins, } from './permissionsDeclaration.js';
 export * from './clientSlice.js';
 export * from './host.js';
+export { abortableSleep } from './abortableSleep.js';
 export { DEFAULT_SESSION_KEY } from './sessionSlot.js';
 export * from './scratchpadWireCaps.js';
 export * from './toolResult.js';
@@ -148,14 +155,24 @@ export * from './principalWire.js';
 export * from './wireErrorTriage.js';
 export * from './corruptSession.js';
 export * from './corruptSessionCopy.js';
-export { classifyToolHistoryMismatch, resolveToolHistoryRewindTarget } from './toolHistoryMismatch.js';
+export { classifyToolHistoryMismatch, readToolHistoryMismatchKey, resolveToolHistoryRewindTarget } from './toolHistoryMismatch.js';
+export type { ToolHistoryMismatchRowKey } from './toolHistoryMismatch.js';
+export { toolHistoryBadTurnSentence } from './toolHistoryBadTurn.js';
 export { classifyRegistryConflict, isScopeGoneError } from './registryConflict.js';
 export type { RegistryConflictClass } from './registryConflict.js';
 export { createPromptDeliveryLedger, promptKnownUndelivered, withoutUndeliveredPrompts } from './promptDelivery.js';
 export type { PromptDeliveryLedger, PromptDeliveryRecord } from './promptDelivery.js';
+export { mintUserAttachmentEnvelope } from './userAttachmentEnvelope.js';
+export type { UserAttachmentDescriptor, UserAttachmentNotebookCell } from './userAttachmentEnvelope.js';
+export { encodeHumanTurn, deliveredUuidsOf } from './humanTurn.js';
+export type { HumanTurnInput, HumanTurnItem, HumanTurnAttachment, HumanTurnRider, HumanTurnMissing, HumanTurnCaps, HumanTurnEncoding, HumanTurnShare, HumanTurnSharePart, HumanTurnDegraded, HumanTurnDelivered, } from './humanTurn.js';
+export { noteEngineCapsForAttachmentSeat, observedAttachmentSeat, forgetAttachmentSeatReading, __resetAttachmentSeatReadingsForTests, } from './attachmentSeatCapability.js';
+export type { AttachmentSeatReading } from './attachmentSeatCapability.js';
 export * from './resumeRefusalCopy.js';
 export * from './wireRefusalCopy.js';
 export * from './inheritEnvWire.js';
+export { SUPPORT_FLOOR, supportFloorOf, engineVersionTier } from './supportFloor.js';
+export type { SupportFloor, SupportFloorComponent, EngineVersionTier } from './supportFloor.js';
 export * from './decideReceipt.js';
 export * from './sessionMap.js';
 export * from './detachWire.js';
@@ -163,6 +180,12 @@ export * from './workflowMonitor.js';
 export * from './workflowClient.js';
 export * from './hooksWireCaps.js';
 export { ENGINE_FIRED_HOOK_EVENTS, PLUGIN_HOOK_DISPOSITIONS, PLUGIN_HOOK_REASONS, PLUGIN_HOOK_EXCLUSION_REASONS, SETTINGS_HOOK_DROP_REASONS, isEngineFiredHookEvent, pluginHookVerdictOf, pluginHookReasonText, settingsHookDropText, pluginHookExecutorLabel, hooksNotRunNotice, settingsHooksKeptLocally, type EngineFiredHookEvent, type PluginHookDisposition, type PluginHookReason, type PluginHookExclusionReason, type SettingsHookDropReason, type HookSettingsSource, type PluginHookKey, type PluginHookVerdict, type PluginHookExclusion, type SettingsHookDrop, type SettingsHookVerdict, type SettingsHookExclusion, type HooksWireEngineFacts, type PluginHookReaderState, type HooksWirePlan, type HooksWirePlanOptions, } from './pluginHooksWire.js';
+export { hookToolAliasesOf, canonicalHookToolName } from './hookToolAliases.js';
+export { hookMatcherVerdict } from './hookMatcherVerdict.js';
+export type { HookMatcherVerdict, HookMatcherUnjudgedReason } from './hookMatcherVerdict.js';
+export { ASK_EVIDENCE_ABSENCE_VALUES, SYSTEM_INJECTION_PRIORITIES } from './engineClosedSets.js';
+export { READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, parseReadDenyBuiltinTiers, type ReadDenyBuiltinTiersParse } from './readDenyTiers.js';
+export { MODE_ARBITRATION, askSurvivesStandingAnswer, type StandingAnswerVerdict } from './askSurvivesStandingAnswer.js';
 export * from './liveInitToolFace.js';
 export * from './printInitToolFace.js';
 export * from './model/providerPresets.js';
@@ -193,7 +216,9 @@ export * from './hitl/sessionPolicyDeliverable.js';
 export * from './hitl/approvalsFeed.js';
 export * from './hitl/livePendingAsk.js';
 export * from './hitl/askSurvivesPosture.js';
-export * from './hitl/crashConverged.js';
+export { projectCrashConverged } from './hitl/crashConverged.js';
+export type { ApprovalsListEnvelope, CrashConvergedOrphanState, CrashConvergedProjection, CrashConvergedRow } from './hitl/crashConverged.js';
+export * from './hitl/crashConvergedNotice.js';
 export * from './interactiveHalt.js';
 export * from './compensations.js';
 export * from './request/printNotification.js';

package/dist/index.js

@@ -26,6 +26,7 @@ export * from './executionLaneCapability.js';
 export * from './approvalsStreamLiveCapability.js';
 export * from './peerLaneCapability.js';
 export * from './permissionRulesWriteCapability.js';
+export { __resetPermissionsAllowGrantReadingsForTests, forgetPermissionsAllowGrantReading, noteEngineCapsForPermissionsAllowGrant, observedPermissionsAllowGrant, permissionsAllowGrantAvailable, permissionsAllowGrantDoctorDetail, projectPermissionsAllowGrantCapability, } from './permissionsAllowGrantCapability.js';
 export * from './sessionPolicyCapability.js';
 export * from './memoryComplianceCapability.js';
 export * from './memoryOriginCapability.js';
@@ -60,7 +61,7 @@ export * from './fleetTaskDesc.js';
 export { displayUntrusted, displayUntrustedMarks } from './displayUntrusted.js';
 export * from './hostEnv.js';
 export * from './unrefTimer.js';
-export { ControlRouter, ControlSafetyError, errCodes, } from './controlRouter.js';
+export { ControlRouter, ControlSafetyError, errCodes, steerRefusalAdviceOf, steeringRefusedBeforeEngine, } from './controlRouter.js';
 export * from './sseIdleTriage.js';
 export * from './engineWireSdk.js';
 export * from './classifierVerdictWire.js';
@@ -82,6 +83,7 @@ export * from './oneShotWireCaps.js';
 export * from './rewindWireCaps.js';
 export * from './rewindArchiveCapability.js';
 export * from './fileHistoryCaptureCapability.js';
+export { FILE_HISTORY_LEG_VERDICTS, fileHistoryLegNoticeVerdict, fileHistoryLegNoticeSentence, fileHistoryDeclarationOfBody, createFileHistoryDeclarationLedger, } from './fileHistoryLegNotice.js';
 export * from './sealedKeyCapability.js';
 export * from './storePostureCapability.js';
 export * from './centerWiringCapability.js';
@@ -103,9 +105,11 @@ export * from './adapter/downstream/terminalToSdkResult.js';
 export * from './adapter/runStream.js';
 export * from './adapter/activeRunSelfHeal.js';
 export * from './request/taskRequest.js';
-export { disableSkillsDeclaration } from './disableSkillsWire.js';
+export { disableSkillsDeclaration, disableSkillsDeclarationSettled } from './disableSkillsWire.js';
+export { PERMISSIONS_KEPT_REASONS, permissionsDeclaration, permissionsDeclarationReport } from './permissionsDeclaration.js';
 export * from './clientSlice.js';
 export * from './host.js';
+export { abortableSleep } from './abortableSleep.js';
 export { DEFAULT_SESSION_KEY } from './sessionSlot.js';
 export * from './scratchpadWireCaps.js';
 export * from './toolResult.js';
@@ -135,12 +139,17 @@ export * from './principalWire.js';
 export * from './wireErrorTriage.js';
 export * from './corruptSession.js';
 export * from './corruptSessionCopy.js';
-export { classifyToolHistoryMismatch, resolveToolHistoryRewindTarget } from './toolHistoryMismatch.js';
+export { classifyToolHistoryMismatch, readToolHistoryMismatchKey, resolveToolHistoryRewindTarget } from './toolHistoryMismatch.js';
+export { toolHistoryBadTurnSentence } from './toolHistoryBadTurn.js';
 export { classifyRegistryConflict, isScopeGoneError } from './registryConflict.js';
 export { createPromptDeliveryLedger, promptKnownUndelivered, withoutUndeliveredPrompts } from './promptDelivery.js';
+export { mintUserAttachmentEnvelope } from './userAttachmentEnvelope.js';
+export { encodeHumanTurn, deliveredUuidsOf } from './humanTurn.js';
+export { noteEngineCapsForAttachmentSeat, observedAttachmentSeat, forgetAttachmentSeatReading, __resetAttachmentSeatReadingsForTests, } from './attachmentSeatCapability.js';
 export * from './resumeRefusalCopy.js';
 export * from './wireRefusalCopy.js';
 export * from './inheritEnvWire.js';
+export { SUPPORT_FLOOR, supportFloorOf, engineVersionTier } from './supportFloor.js';
 export * from './decideReceipt.js';
 export * from './sessionMap.js';
 export * from './detachWire.js';
@@ -148,6 +157,11 @@ export * from './workflowMonitor.js';
 export * from './workflowClient.js';
 export * from './hooksWireCaps.js';
 export { ENGINE_FIRED_HOOK_EVENTS, PLUGIN_HOOK_DISPOSITIONS, PLUGIN_HOOK_REASONS, PLUGIN_HOOK_EXCLUSION_REASONS, SETTINGS_HOOK_DROP_REASONS, isEngineFiredHookEvent, pluginHookVerdictOf, pluginHookReasonText, settingsHookDropText, pluginHookExecutorLabel, hooksNotRunNotice, settingsHooksKeptLocally, } from './pluginHooksWire.js';
+export { hookToolAliasesOf, canonicalHookToolName } from './hookToolAliases.js';
+export { hookMatcherVerdict } from './hookMatcherVerdict.js';
+export { ASK_EVIDENCE_ABSENCE_VALUES, SYSTEM_INJECTION_PRIORITIES } from './engineClosedSets.js';
+export { READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, parseReadDenyBuiltinTiers } from './readDenyTiers.js';
+export { MODE_ARBITRATION, askSurvivesStandingAnswer } from './askSurvivesStandingAnswer.js';
 export * from './liveInitToolFace.js';
 export * from './printInitToolFace.js';
 export * from './model/providerPresets.js';
@@ -176,7 +190,8 @@ export * from './hitl/sessionPolicyDeliverable.js';
 export * from './hitl/approvalsFeed.js';
 export * from './hitl/livePendingAsk.js';
 export * from './hitl/askSurvivesPosture.js';
-export * from './hitl/crashConverged.js';
+export { projectCrashConverged } from './hitl/crashConverged.js';
+export * from './hitl/crashConvergedNotice.js';
 export * from './interactiveHalt.js';
 export * from './compensations.js';
 export * from './request/printNotification.js';

package/dist/inheritEnvWire.js

@@ -77,7 +77,7 @@ export function inheritEnvRefusalFromError(err, sentRequest) {
         return null;
     }
 }
-const REFUSAL_NOT_ACCEPTED = 'The engine refused this request as invalid without naming the field · ' +
+const REFUSAL_NOT_ACCEPTED = 'The engine refused this request as invalid, under a refusal code that many different request fields share · ' +
     "This request asked for the shell to inherit this machine's whole environment, which the engine accepts only when tools run directly on its own machine and the request belongs to a session; if that is what it refused, send it again without that setting (or with the default)";
 export function inheritEnvRefusalContent(_detail) {
     return REFUSAL_NOT_ACCEPTED;

package/dist/liveModelCatalog.d.ts

@@ -16,6 +16,8 @@ export declare function setLiveModelCatalogRefresher(fn: (() => Promise<LiveMode
 export declare function refreshLiveModelCatalog(): Promise<boolean>;
 export declare function getLiveModelCatalog(): LiveModelCatalog | null;
 export declare function normalizeLiveModelRef(ref: string): string;
+export type ImageVision = 'yes' | 'no' | 'unknown';
+export declare function imageVisionOf(model: string | undefined, catalog?: LiveModelCatalog | null): ImageVision;
 export declare function liveDefaultModelName(): string | null;
 export interface RoutePairingVerdict {
     verdict: 'ok' | 'broken' | 'unknown';

package/dist/liveModelCatalog.js

@@ -26,10 +26,58 @@ export function getLiveModelCatalog() {
 export function normalizeLiveModelRef(ref) {
     if (!catalog || !ref)
         return ref;
-    if (catalog.models.some(m => m.name === ref))
+    const row = liveModelRowOf(catalog, ref);
+    if (row === undefined)
         return ref;
-    const row = catalog.models.find(m => typeof m.id === 'string' && m.id === ref);
-    return row?.name || ref;
+    const name = ownDataOf(row, 'name');
+    return typeof name === 'string' && name ? name : ref;
+}
+function ownDataOf(o, key) {
+    try {
+        const d = Object.getOwnPropertyDescriptor(o, key);
+        return d !== undefined && 'value' in d ? d.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function liveModelRowOf(cat, ref) {
+    const models = ownDataOf(cat, 'models');
+    if (!Array.isArray(models))
+        return undefined;
+    const n = ownDataOf(models, 'length');
+    if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 0)
+        return undefined;
+    const rows = [];
+    for (let i = 0; i < n; i += 1) {
+        const row = ownDataOf(models, String(i));
+        if (row !== null && typeof row === 'object')
+            rows.push(row);
+    }
+    return rows.find((row) => ownDataOf(row, 'name') === ref) ?? rows.find((row) => ownDataOf(row, 'id') === ref);
+}
+export function imageVisionOf(model, catalog = getLiveModelCatalog()) {
+    try {
+        if (model !== undefined && typeof model !== 'string')
+            return 'unknown';
+        if (catalog === null || typeof catalog !== 'object' || Array.isArray(catalog))
+            return 'unknown';
+        let target = model !== undefined && model.length > 0 ? model : undefined;
+        if (target === undefined) {
+            const def = ownDataOf(catalog, 'default');
+            target = typeof def === 'string' && def.length > 0 ? def : undefined;
+        }
+        if (target === undefined)
+            return 'unknown';
+        const row = liveModelRowOf(catalog, target);
+        if (row === undefined)
+            return 'unknown';
+        const vision = ownDataOf(row, 'vision');
+        return vision === true ? 'yes' : vision === false ? 'no' : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
 }
 export function liveDefaultModelName() {
     if (!catalog?.default)

package/dist/permissionRuleIssue.d.ts

@@ -1,3 +1,3 @@
 export declare const PERMISSION_RULE_ISSUE_CODES: readonly string[];
 export declare const RETIRED_PERMISSION_RULE_ISSUE_CODES: readonly string[];
-export declare function permissionRuleIssueDetail(code: unknown, message: unknown): string;
+export declare function permissionRuleIssueDetail(code: unknown, message: unknown, rule?: string): string;

package/dist/permissionRuleIssue.js

@@ -21,7 +21,7 @@ const ISSUE_MESSAGE_MAX = 200;
 const ISSUE_SENTENCES = Object.freeze({
     'invalid.empty_tool': 'this rule is invalid: it names no tool',
     'invalid.paren': 'this rule is invalid: its parentheses do not parse (escape a literal one as \\( or \\))',
-    'invalid.param_split': 'this rule is invalid: the part before the colon is not a parameter name',
+    'invalid.param_split': 'this rule is invalid: its parentheses do not hold a parameter rule written name:pattern',
     'invalid.allow_param_rule': 'this rule is invalid: an allow rule cannot carry a parameter pattern — only bare tool rules auto-allow',
     'invalid.primary_field': "this rule is invalid: it patterns the tool's primary field, which matches the whole trimmed string rather than a prefix",
     'invalid.cap_exceeded': 'this rule set is invalid: it is over one of the deployment caps (rule count, rule length, pattern length, or star count)',
@@ -35,8 +35,27 @@ const ISSUE_SENTENCES = Object.freeze({
     'unsupported.mcp_paren': 'a parenthesised parameter rule is not supported on an MCP tool name',
     'unsupported.covering_paren': 'a parenthesised parameter rule is not supported on a covering protocol name — the parameter grammar is keyed by an exact tool name, so no mounted tool could ever bear it',
 });
-export function permissionRuleIssueDetail(code, message) {
-    const known = typeof code === 'string' && Object.hasOwn(ISSUE_SENTENCES, code) ? ISSUE_SENTENCES[code] : undefined;
+const PARAM_SPLIT_WITH_COLON = 'this rule is invalid: a parameter rule is written name:pattern, and the name before the colon or the pattern after it is empty';
+const PARAM_SPLIT_NO_COLON = 'this rule is invalid: there is no colon inside the parentheses, so this is not a parameter rule (a parameter rule is written name:pattern)';
+function colonInsideParens(rule) {
+    if (typeof rule !== 'string')
+        return undefined;
+    for (let i = 0; i < rule.length; i += 1) {
+        const ch = rule[i];
+        if (ch === '\\') {
+            i += 1;
+            continue;
+        }
+        if (ch === '(')
+            return rule.indexOf(':', i + 1) !== -1;
+    }
+    return undefined;
+}
+export function permissionRuleIssueDetail(code, message, rule) {
+    const colon = code === 'invalid.param_split' ? colonInsideParens(rule) : undefined;
+    const known = colon !== undefined
+        ? colon ? PARAM_SPLIT_WITH_COLON : PARAM_SPLIT_NO_COLON
+        : typeof code === 'string' && Object.hasOwn(ISSUE_SENTENCES, code) ? ISSUE_SENTENCES[code] : undefined;
     const text = typeof message === 'string' && message.length > 0
         ? capForDisplay(message, ISSUE_MESSAGE_MAX)
         : '';

package/dist/permissionsAllowGrantCapability.d.ts

@@ -0,0 +1,18 @@
+export type PermissionsAllowGrantReading = {
+    kind: 'unobserved';
+} | {
+    kind: 'not_reported';
+} | {
+    kind: 'present';
+    grants: boolean;
+};
+export declare function projectPermissionsAllowGrantCapability(caps: unknown): PermissionsAllowGrantReading | undefined;
+export declare function noteEngineCapsForPermissionsAllowGrant(baseUrl: string, caps: unknown, opts?: {
+    generation?: number;
+}): void;
+export declare function observedPermissionsAllowGrant(baseUrl?: string | undefined): PermissionsAllowGrantReading;
+export declare function permissionsAllowGrantAvailable(reading: PermissionsAllowGrantReading): boolean;
+export declare function allowRulesGate(reading: PermissionsAllowGrantReading, settingsRead: 'clean' | 'partial' | 'unreadable' | undefined): 'open' | 'capability_off' | 'settings_read_not_clean';
+export declare function permissionsAllowGrantDoctorDetail(reading: PermissionsAllowGrantReading, settingsRead?: 'clean' | 'partial' | 'unreadable'): string;
+export declare function forgetPermissionsAllowGrantReading(baseUrl: string | undefined): void;
+export declare function __resetPermissionsAllowGrantReadingsForTests(): void;

package/dist/permissionsAllowGrantCapability.js

@@ -0,0 +1,84 @@
+import { engineWireTarget } from './engineWireTarget.js';
+import { createEngineCapReader } from './engineCapReader.js';
+const ALLOW_GRANT_CAP_PATH = ['settings', 'permissions', 'allowGrant'];
+export function projectPermissionsAllowGrantCapability(caps) {
+    if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
+        return undefined;
+    let node = caps;
+    for (let i = 0; i < ALLOW_GRANT_CAP_PATH.length; i++) {
+        const seg = ALLOW_GRANT_CAP_PATH[i];
+        if (!Object.hasOwn(node, seg))
+            return { kind: 'not_reported' };
+        const v = node[seg];
+        if (v === undefined)
+            return { kind: 'not_reported' };
+        if (i === ALLOW_GRANT_CAP_PATH.length - 1) {
+            return typeof v === 'boolean' ? { kind: 'present', grants: v } : undefined;
+        }
+        if (v === null || typeof v !== 'object' || Array.isArray(v))
+            return undefined;
+        node = v;
+    }
+    return undefined;
+}
+const reader = createEngineCapReader({
+    name: ALLOW_GRANT_CAP_PATH.join('.'),
+    project: projectPermissionsAllowGrantCapability,
+    makeUnobserved: () => ({ kind: 'unobserved' }),
+});
+export function noteEngineCapsForPermissionsAllowGrant(baseUrl, caps, opts) {
+    reader.note(baseUrl, caps, opts);
+}
+export function observedPermissionsAllowGrant(baseUrl = engineWireTarget()?.baseUrl) {
+    return reader.observed(baseUrl);
+}
+export function permissionsAllowGrantAvailable(reading) {
+    try {
+        if (reading === null || typeof reading !== 'object' || Array.isArray(reading))
+            return false;
+        if (!Object.hasOwn(reading, 'kind') || !Object.hasOwn(reading, 'grants'))
+            return false;
+        return reading.kind === 'present' && reading.grants === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function allowRulesGate(reading, settingsRead) {
+    if (!permissionsAllowGrantAvailable(reading))
+        return 'capability_off';
+    return settingsRead === 'clean' ? 'open' : 'settings_read_not_clean';
+}
+function ownReadingField(reading, key) {
+    try {
+        if (reading === null || typeof reading !== 'object' || Array.isArray(reading))
+            return undefined;
+        return Object.hasOwn(reading, key) ? reading[key] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function permissionsAllowGrantDoctorDetail(reading, settingsRead) {
+    const gate = allowRulesGate(reading, settingsRead);
+    if (gate === 'open') {
+        return 'allow rules sent to the engine — it reads them as rules, not as an exclusive list: a matching call counts as answered for, and the engine still raises its own prompts where it requires them';
+    }
+    if (gate === 'settings_read_not_clean') {
+        return 'allow rules from settings files kept on this side — this engine reads allow rules as rules, but the settings read that produced them was not reported clean (a settings file was unreadable or had a problem, or no read health was given), so they are not sent; command-line and session allow rules are still sent, and matching approvals are still answered here';
+    }
+    const kind = ownReadingField(reading, 'kind');
+    if (kind === 'present' && ownReadingField(reading, 'grants') === false) {
+        return 'allow rules kept on this side — this engine says it does not read allow rules as rules of that kind, so they are not sent and matching approvals are still answered here';
+    }
+    if (kind === 'not_reported') {
+        return 'allow rules kept on this side — this engine does not say how it reads allow rules; sending them to an engine that reads them as an exclusive list would block every tool not on it, so they are not sent and matching approvals are still answered here';
+    }
+    return 'allow rules kept on this side — no usable capabilities reading is cached for this engine (none received, or the last one was unreadable), so allow rules are not sent and matching approvals are still answered here';
+}
+export function forgetPermissionsAllowGrantReading(baseUrl) {
+    reader.forget(baseUrl);
+}
+export function __resetPermissionsAllowGrantReadingsForTests() {
+    reader.__resetForTests();
+}

package/dist/permissionsDeclaration.d.ts

@@ -0,0 +1,48 @@
+import { type PermissionsAllowGrantReading } from './permissionsAllowGrantCapability.js';
+declare const RULE_TRUST_ORDER: readonly ["policySettings", "cliArg", "flagSettings", "session", "userSettings", "localSettings", "projectSettings"];
+export type WireRuleOrigin = (typeof RULE_TRUST_ORDER)[number];
+export interface WireRuleOrigins {
+    readonly deny?: ReadonlyMap<string, WireRuleOrigin>;
+    readonly ask?: ReadonlyMap<string, WireRuleOrigin>;
+    readonly allow?: ReadonlyMap<string, WireRuleOrigin>;
+}
+export interface PermissionsDeclarationInput {
+    readonly deny: readonly string[];
+    readonly ask: readonly string[];
+    readonly allow: readonly string[];
+    readonly origins?: WireRuleOrigins;
+    readonly cliDeny?: readonly string[];
+    readonly settingsRead: 'clean' | 'partial' | 'unreadable';
+}
+export interface PermissionsDeclarationBuckets {
+    deny?: string[];
+    ask?: string[];
+    allow?: string[];
+}
+export interface PermissionsDeclaration {
+    permissions?: PermissionsDeclarationBuckets;
+}
+export declare const PERMISSIONS_KEPT_REASONS: readonly ["allow_capability_off", "settings_read_not_clean", "empty_rule", "paren_in_tool_name", "retired_tool_name", "unprefixed_namespaced_name", "incomplete_protocol_name", "home_relative_path", "compile_refused", "content_form_not_grantable", "judge_failed", "duplicate"];
+export type PermissionsKeptReason = (typeof PERMISSIONS_KEPT_REASONS)[number];
+export interface PermissionsKeptRule {
+    rule: string;
+    bucket: 'deny' | 'ask' | 'allow';
+    reason: PermissionsKeptReason;
+}
+export interface PermissionsRewrittenRule {
+    from: string;
+    to: string;
+    bucket: 'deny' | 'ask' | 'allow';
+}
+export interface PermissionsUncheckedRule {
+    rule: string;
+    bucket: 'deny' | 'ask';
+}
+export interface PermissionsDeclarationReport extends PermissionsDeclaration {
+    kept: PermissionsKeptRule[];
+    rewritten: PermissionsRewrittenRule[];
+    unchecked: PermissionsUncheckedRule[];
+}
+export declare function permissionsDeclaration(input: PermissionsDeclarationInput, caps: PermissionsAllowGrantReading): PermissionsDeclaration;
+export declare function permissionsDeclarationReport(input: PermissionsDeclarationInput, caps: PermissionsAllowGrantReading): PermissionsDeclarationReport;
+export {};