@sema-agent/client-core 0.87.0 → 0.89.0

package/dist/index.js

@@ -35,6 +35,7 @@ export * from './deviceExecutorManagementCapability.js';
 export * from './mcpReconnect.js';
 export * from './leaderConflict.js';
 export * from './runTerminal.js';
+export { providerRejectionResend } from './providerRejection.js';
 export * from './runCancelContext.js';
 export * from './argvFlagValue.js';
 export * from './readFacePosture.js';
@@ -59,7 +60,7 @@ export * from './fleetTaskDesc.js';
 export { displayUntrusted, displayUntrustedMarks } from './displayUntrusted.js';
 export * from './hostEnv.js';
 export * from './unrefTimer.js';
-export * from './controlRouter.js';
+export { ControlRouter, ControlSafetyError, errCodes, } from './controlRouter.js';
 export * from './sseIdleTriage.js';
 export * from './engineWireSdk.js';
 export * from './classifierVerdictWire.js';
@@ -102,6 +103,7 @@ 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 * from './clientSlice.js';
 export * from './host.js';
 export { DEFAULT_SESSION_KEY } from './sessionSlot.js';
@@ -134,6 +136,8 @@ export * from './wireErrorTriage.js';
 export * from './corruptSession.js';
 export * from './corruptSessionCopy.js';
 export { classifyToolHistoryMismatch, resolveToolHistoryRewindTarget } from './toolHistoryMismatch.js';
+export { classifyRegistryConflict, isScopeGoneError } from './registryConflict.js';
+export { createPromptDeliveryLedger, promptKnownUndelivered, withoutUndeliveredPrompts } from './promptDelivery.js';
 export * from './resumeRefusalCopy.js';
 export * from './wireRefusalCopy.js';
 export * from './inheritEnvWire.js';
@@ -143,7 +147,7 @@ export * from './detachWire.js';
 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, } from './pluginHooksWire.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 * from './liveInitToolFace.js';
 export * from './printInitToolFace.js';
 export * from './model/providerPresets.js';
@@ -179,9 +183,10 @@ export * from './request/printNotification.js';
 export * from './seatContract.js';
 export * from './agentSession/contract.js';
 export * from './agentSession/backgroundView.js';
-export { READ_CREDENTIAL_NOT_ACCEPTED_NOTICE } from './readCredentialRefusal.js';
+export { READ_CREDENTIAL_NOT_ACCEPTED_NOTICE, isReadCredentialRefusal } from './readCredentialRefusal.js';
 export { readEngineAgentRegistry, isEngineAgentRegistryListingSuperseded } from './agentSession/engineAgentRegistryRead.js';
 export { stopEngineSessionBackground, engineSessionBackgroundReceiptReadingOf, ENGINE_SESSION_BACKGROUND_RECEIPT_STATES, } from './agentSession/engineSessionBackgroundStop.js';
+export { eraseSessionMemory, sessionMemoryEraseOutcome, SESSION_MEMORY_ERASE_REFUSAL_REASONS, SESSION_MEMORY_ERASE_UNCONFIRMED_WHYS, SESSION_MEMORY_ERASE_RETRIES, } from './sessionMemoryErase.js';
 export * from './model/catalog.js';
 export * from './model/catalogLoader.js';
 export * from './model/providerAuth.js';

package/dist/pluginHooksWire.d.ts

@@ -4,9 +4,9 @@ export declare const ENGINE_FIRED_HOOK_EVENTS: readonly ["PreToolUse", "PostTool
 export type EngineFiredHookEvent = (typeof ENGINE_FIRED_HOOK_EVENTS)[number];
 export declare const PLUGIN_HOOK_DISPOSITIONS: readonly ["engine", "shell", "not_run"];
 export type PluginHookDisposition = (typeof PLUGIN_HOOK_DISPOSITIONS)[number];
-export declare const PLUGIN_HOOK_REASONS: readonly ["projected", "shell_event", "no_executor", "engine_not_local", "engine_locality_unknown", "engine_capability_absent", "engine_capability_unknown", "not_command", "sensitive_options", "engine_limit", "shell_form_user_config", "user_config_unset", "malformed_entry"];
+export declare const PLUGIN_HOOK_REASONS: readonly ["projected", "shell_event", "no_executor", "engine_not_local", "engine_locality_unknown", "engine_capability_absent", "engine_capability_unknown", "not_command", "sensitive_options", "engine_limit", "shell_form_user_config", "user_config_unset", "malformed_entry", "engine_hooks_off", "engine_hooks_unknown", "engine_type_skipped", "engine_llm_limit", "engine_unconfirmed", "engine_elsewhere"];
 export type PluginHookReason = (typeof PLUGIN_HOOK_REASONS)[number];
-export declare const PLUGIN_HOOK_EXCLUSION_REASONS: readonly ["workspace_untrusted", "governance_unreadable", "policy_disable_all", "startup_mode", "managed_plugins_only"];
+export declare const PLUGIN_HOOK_EXCLUSION_REASONS: readonly ["workspace_untrusted", "governance_unreadable", "policy_disable_all", "startup_mode", "managed_plugins_only", "prompt_not_user_authored"];
 export type PluginHookExclusionReason = (typeof PLUGIN_HOOK_EXCLUSION_REASONS)[number];
 export declare const SETTINGS_HOOK_DROP_REASONS: readonly ["exec_form_unsupported", "mcp_tool_unsupported"];
 export type SettingsHookDropReason = (typeof SETTINGS_HOOK_DROP_REASONS)[number];
@@ -33,9 +33,25 @@ export interface SettingsHookDrop {
     readonly reason: SettingsHookDropReason;
     readonly notRun: boolean;
 }
+export interface SettingsHookVerdict {
+    readonly source: HookSettingsSource;
+    readonly event: string;
+    readonly groupIndex: number;
+    readonly hookIndex: number;
+    readonly disposition: PluginHookDisposition;
+    readonly reason: PluginHookReason;
+}
+export interface SettingsHookExclusion {
+    readonly source: HookSettingsSource;
+    readonly event: string;
+    readonly groupIndex: number;
+    readonly hookIndex: number;
+    readonly reason: PluginHookExclusionReason;
+}
 export interface HooksWireEngineFacts {
     readonly ownedByThisShell: boolean | null;
     readonly pluginHooksCapable: boolean | null;
+    readonly hooksCapable: boolean | null;
 }
 export type PluginHookReaderState = 'present' | 'absent' | 'failed';
 export interface HooksWirePlan {
@@ -44,19 +60,34 @@ export interface HooksWirePlan {
     readonly verdicts: readonly PluginHookVerdict[];
     readonly excluded: readonly PluginHookExclusion[];
     readonly settingsDropped: readonly SettingsHookDrop[];
+    readonly settingsVerdicts: readonly SettingsHookVerdict[];
+    readonly settingsExcluded: readonly SettingsHookExclusion[];
     readonly wire: WireHooksConfig | undefined;
 }
 export interface HooksWirePlanOptions {
     readonly baseUrl?: string;
     readonly engineOwnedByThisShell?: boolean;
     readonly shellHookEvents?: readonly string[];
+    readonly shellHookTypesByEvent?: Readonly<Record<string, readonly string[]>>;
+    readonly promptAuthoredByUser?: boolean;
 }
 export declare const ENGINE_HOOK_LIMITS: {
     readonly maxGroupsPerEvent: 16;
     readonly maxEntriesPerEvent: 32;
     readonly maxCommandChars: 8192;
+    readonly maxLlmEntriesPerEvent: 4;
+};
+export type ShellRunsHook = (event: string, type: string | undefined) => boolean;
+type HookExecutor = {
+    readonly kind: 'excluded';
+    readonly reason: 'prompt_not_user_authored';
+} | {
+    readonly kind: 'judged';
+    readonly disposition: PluginHookDisposition;
+    readonly reason: PluginHookReason;
 };
 type WireHookGroup = NonNullable<WireHooksConfig[string]>[number];
+type WireHookEntry = WireHookGroup['hooks'][number];
 export declare function isEngineFiredHookEvent(event: string): boolean;
 export interface EventOccupancy {
     readonly groups: number;
@@ -68,7 +99,8 @@ export interface PluginHookDecisionInput {
     readonly exclusion: PluginHookExclusionReason | undefined;
     readonly managedOnly: boolean;
     readonly engine: HooksWireEngineFacts;
-    readonly shellHookEvents: ReadonlySet<string>;
+    readonly shellRuns: ShellRunsHook;
+    readonly promptAuthoredByUser: boolean;
     readonly occupied: ReadonlyMap<string, EventOccupancy>;
 }
 export interface PluginHookDecision {
@@ -78,12 +110,16 @@ export interface PluginHookDecision {
     readonly unreadable: number;
 }
 export declare function decidePluginHooks(input: PluginHookDecisionInput): PluginHookDecision;
-export declare function filterSettingsHookGroups(source: HookSettingsSource, event: string, groups: readonly WireHookGroup[], execFormCapable: boolean, hostFires: boolean, failLoudMcpTool: boolean): SettingsHookFilterResult;
+export declare function filterSettingsHookGroups(source: HookSettingsSource, event: string, groups: readonly WireHookGroup[], execFormCapable: boolean, shellRunsType: (type: string | undefined) => boolean, failLoudMcpTool: boolean, judge?: SettingsHookJudge): SettingsHookFilterResult;
 export interface SettingsHookFilterResult {
     readonly groups: WireHookGroup[];
     readonly drops: SettingsHookDrop[];
     readonly stripped: number;
+    readonly verdicts: SettingsHookVerdict[];
+    readonly excluded: SettingsHookExclusion[];
 }
+export type SettingsHookJudge = (event: string, group: WireHookGroup, entry: WireHookEntry) => HookExecutor;
+export declare function createSettingsHookJudge(engine: HooksWireEngineFacts, shellRuns: ShellRunsHook, promptAuthoredByUser: boolean): SettingsHookJudge;
 export interface SourcedSettingsHookGroup {
     readonly source: HookSettingsSource;
     readonly group: WireHookGroup;
@@ -94,6 +130,12 @@ export interface SettingsHookDedupResult {
     readonly removed: number;
 }
 export declare function pluginHookVerdictOf(plan: HooksWirePlan, pluginId: string, event: string, groupIndex: number, hookIndex: number): PluginHookVerdict | undefined;
+export declare function settingsHooksKeptLocally<T>(plan: HooksWirePlan, event: string, group: {
+    readonly matcher?: string;
+    readonly hooks: readonly T[];
+}, opts?: {
+    readonly engineCompaction?: 'performed' | 'not_performed';
+}): readonly T[];
 export declare function pluginHookReasonText(reason: PluginHookReason): string;
 export declare function settingsHookDropText(reason: SettingsHookDropReason): string;
 export declare function pluginHookExecutorLabel(v: PluginHookVerdict): string;

package/dist/pluginHooksWire.js

@@ -25,6 +25,12 @@ export const PLUGIN_HOOK_REASONS = [
     'shell_form_user_config',
     'user_config_unset',
     'malformed_entry',
+    'engine_hooks_off',
+    'engine_hooks_unknown',
+    'engine_type_skipped',
+    'engine_llm_limit',
+    'engine_unconfirmed',
+    'engine_elsewhere',
 ];
 export const PLUGIN_HOOK_EXCLUSION_REASONS = [
     'workspace_untrusted',
@@ -32,15 +38,69 @@ export const PLUGIN_HOOK_EXCLUSION_REASONS = [
     'policy_disable_all',
     'startup_mode',
     'managed_plugins_only',
+    'prompt_not_user_authored',
 ];
 export const SETTINGS_HOOK_DROP_REASONS = ['exec_form_unsupported', 'mcp_tool_unsupported'];
-export const ENGINE_HOOK_LIMITS = { maxGroupsPerEvent: 16, maxEntriesPerEvent: 32, maxCommandChars: 8192 };
+export const ENGINE_HOOK_LIMITS = { maxGroupsPerEvent: 16, maxEntriesPerEvent: 32, maxCommandChars: 8192, maxLlmEntriesPerEvent: 4 };
+const ENGINE_HOOK_TYPE_RUNS = new Set(['command', 'http', 'prompt', 'agent']);
+const COMPACTION_EVENTS = new Set(['PreCompact', 'PostCompact']);
+const judged = (disposition, reason) => ({ kind: 'judged', disposition, reason });
+function hookExecutorOf(x) {
+    if (x.event === 'UserPromptSubmit' && !x.promptAuthoredByUser)
+        return { kind: 'excluded', reason: 'prompt_not_user_authored' };
+    if (x.source === 'settings') {
+        const why = x.powershell
+            ? { reason: 'engine_type_skipped', certain: true }
+            : x.engine.hooksCapable === false
+                ? { reason: 'engine_hooks_off', certain: true }
+                : x.engine.hooksCapable === null
+                    ? { reason: 'engine_hooks_unknown', certain: false }
+                    : x.llmPosition > ENGINE_HOOK_LIMITS.maxLlmEntriesPerEvent
+                        ? { reason: 'engine_llm_limit', certain: false }
+                        : undefined;
+        const compaction = COMPACTION_EVENTS.has(x.event);
+        if (why === undefined) {
+            if (!x.shellRuns || x.engine.ownedByThisShell === true)
+                return judged('engine', 'projected');
+            return compaction ? judged('engine', 'engine_unconfirmed') : judged('shell', 'engine_elsewhere');
+        }
+        if (x.shellRuns && (why.certain || !compaction || why.reason === 'engine_llm_limit'))
+            return judged('shell', why.reason);
+        return why.certain ? judged('not_run', why.reason) : judged('engine', 'engine_unconfirmed');
+    }
+    const why = x.engine.ownedByThisShell === null
+        ? 'engine_locality_unknown'
+        : !x.engine.ownedByThisShell
+            ? 'engine_not_local'
+            : x.engine.pluginHooksCapable === null
+                ? 'engine_capability_unknown'
+                : !x.engine.pluginHooksCapable
+                    ? 'engine_capability_absent'
+                    : x.engine.hooksCapable === false
+                        ? 'engine_hooks_off'
+                        : x.engine.hooksCapable === null
+                            ? 'engine_hooks_unknown'
+                            : x.pluginBlock === 'not_command'
+                                ? 'not_command'
+                                : x.powershell
+                                    ? 'engine_type_skipped'
+                                    : x.pluginBlock;
+    if (why === undefined)
+        return judged('engine', 'projected');
+    return judged(x.shellRuns ? 'shell' : 'not_run', why);
+}
 const ENGINE_EVENTS = new Set(ENGINE_FIRED_HOOK_EVENTS);
 const USER_CONFIG_REF_ONE = /\$\{user_config\.[^}]+\}/;
 const USER_CONFIG_REF_ALL = /\$\{user_config\.([^}]+)\}/g;
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
+function ownField(o, key) {
+    return Object.hasOwn(o, key) ? o[key] : undefined;
+}
+function ownView(v) {
+    return isRecord(v) ? Object.assign(Object.create(null), Object.fromEntries(Object.entries(v))) : v;
+}
 function nonEmptyString(v) {
     return typeof v === 'string' && v.length > 0;
 }
@@ -123,7 +183,7 @@ export function decidePluginHooks(input) {
     const excluded = [];
     const candidates = new Map();
     let unreadable = 0;
-    const fallback = (event, reason) => input.shellHookEvents.has(event) ? { disposition: 'shell', reason } : { disposition: 'not_run', reason };
+    const fallback = (event, type, reason) => input.shellRuns(event, typeof type === 'string' ? type : undefined) ? { disposition: 'shell', reason } : { disposition: 'not_run', reason };
     input.plugins.forEach((p, pluginIndex) => {
         if (!isRecord(p) || !isRecord(p.hooks)) {
             unreadable++;
@@ -155,6 +215,7 @@ export function decidePluginHooks(input) {
                         excluded.push({ ...key, reason: 'managed_plugins_only' });
                         return;
                     }
+                    const entryType = isRecord(entry) && typeof entry.type === 'string' ? entry.type : undefined;
                     const shape = sourceOk ? classifyEntry(entry, src.options) : { kind: 'malformed' };
                     if (shape.kind === 'malformed') {
                         verdicts.push({ ...key, disposition: 'not_run', reason: 'malformed_entry' });
@@ -171,27 +232,28 @@ export function decidePluginHooks(input) {
                     if (!ENGINE_EVENTS.has(event)) {
                         verdicts.push({
                             ...key,
-                            ...(input.shellHookEvents.has(event)
+                            ...(input.shellRuns(event, entryType)
                                 ? { disposition: 'shell', reason: 'shell_event' }
                                 : { disposition: 'not_run', reason: 'no_executor' }),
                         });
                         return;
                     }
-                    const blocked = input.engine.ownedByThisShell === null
-                        ? 'engine_locality_unknown'
-                        : !input.engine.ownedByThisShell
-                            ? 'engine_not_local'
-                            : input.engine.pluginHooksCapable === null
-                                ? 'engine_capability_unknown'
-                                : !input.engine.pluginHooksCapable
-                                    ? 'engine_capability_absent'
-                                    : shape.kind === 'other'
-                                        ? 'not_command'
-                                        : declaresSensitive(src.options)
-                                            ? 'sensitive_options'
-                                            : undefined;
-                    if (blocked !== undefined) {
-                        verdicts.push({ ...key, ...fallback(event, blocked) });
+                    const ex = hookExecutorOf({
+                        source: 'plugin',
+                        event,
+                        powershell: shape.kind !== 'other' && isRecord(entry) && entry.shell === 'powershell',
+                        llmPosition: 0,
+                        engine: input.engine,
+                        shellRuns: input.shellRuns(event, entryType),
+                        promptAuthoredByUser: input.promptAuthoredByUser,
+                        ...(shape.kind === 'other' ? { pluginBlock: 'not_command' } : declaresSensitive(src.options) ? { pluginBlock: 'sensitive_options' } : {}),
+                    });
+                    if (ex.kind === 'excluded') {
+                        excluded.push({ ...key, reason: ex.reason });
+                        return;
+                    }
+                    if (ex.disposition !== 'engine') {
+                        verdicts.push({ ...key, disposition: ex.disposition, reason: ex.reason });
                         return;
                     }
                     const plugin = { name: src.name, root: src.root, dataDir: src.dataDir };
@@ -218,7 +280,7 @@ export function decidePluginHooks(input) {
             const cmd = c.wireEntry.command;
             if (typeof cmd === 'string' && cmd.length <= ENGINE_HOOK_LIMITS.maxCommandChars)
                 return true;
-            Object.assign(c.verdict, fallback(event, 'engine_limit'));
+            Object.assign(c.verdict, fallback(event, c.wireEntry.type, 'engine_limit'));
             return false;
         });
         if (fits.length === 0)
@@ -233,7 +295,7 @@ export function decidePluginHooks(input) {
         if (occ.groups + groupKeys.length > ENGINE_HOOK_LIMITS.maxGroupsPerEvent ||
             occ.entries + fits.length > ENGINE_HOOK_LIMITS.maxEntriesPerEvent) {
             for (const c of fits)
-                Object.assign(c.verdict, fallback(event, 'engine_limit'));
+                Object.assign(c.verdict, fallback(event, c.wireEntry.type, 'engine_limit'));
             continue;
         }
         const groupsOut = [];
@@ -259,12 +321,13 @@ function carriesArgs(entry) {
     }
     return true;
 }
-export function filterSettingsHookGroups(source, event, groups, execFormCapable, hostFires, failLoudMcpTool) {
+export function filterSettingsHookGroups(source, event, groups, execFormCapable, shellRunsType, failLoudMcpTool, judge) {
     const drops = [];
+    const verdicts = [];
+    const excluded = [];
     const out = [];
     let stripped = 0;
     const engineEvent = ENGINE_EVENTS.has(event);
-    const notRun = engineEvent && !hostFires;
     const keepMcpTool = failLoudMcpTool && engineEvent;
     groups.forEach((group, groupIndex) => {
         if (!isRecord(group) || !Array.isArray(group.hooks)) {
@@ -284,10 +347,23 @@ export function filterSettingsHookGroups(source, event, groups, execFormCapable,
                         ? 'exec_form_unsupported'
                         : undefined;
             if (reason !== undefined) {
-                drops.push({ source, event, groupIndex, hookIndex, reason, notRun });
+                drops.push({ source, event, groupIndex, hookIndex, reason, notRun: engineEvent && !shellRunsType(isRecord(entry) && typeof entry.type === 'string' ? entry.type : undefined) });
                 changed = true;
                 return;
             }
+            if (judge !== undefined && engineEvent && isRecord(entry) && judgeableSettingsEntry(entry)) {
+                const ex = judge(event, group, entry);
+                if (ex.kind === 'excluded') {
+                    excluded.push({ source, event, groupIndex, hookIndex, reason: ex.reason });
+                    changed = true;
+                    return;
+                }
+                verdicts.push({ source, event, groupIndex, hookIndex, disposition: ex.disposition, reason: ex.reason });
+                if (ex.disposition === 'shell') {
+                    changed = true;
+                    return;
+                }
+            }
             if (isRecord(entry) && Object.hasOwn(entry, 'plugin')) {
                 const copy = { ...entry };
                 delete copy.plugin;
@@ -303,7 +379,51 @@ export function filterSettingsHookGroups(source, event, groups, execFormCapable,
         else if (kept.length > 0)
             out.push({ ...group, hooks: kept });
     });
-    return { groups: out, drops, stripped };
+    return { groups: out, drops, stripped, verdicts, excluded };
+}
+function judgeableSettingsEntry(entry) {
+    const type = entry.type;
+    if (typeof type !== 'string' || !ENGINE_HOOK_TYPE_RUNS.has(type))
+        return false;
+    const field = type === 'command' ? entry.command : type === 'http' ? entry.url : entry.prompt;
+    return nonEmptyString(field) && !field.includes('\u0000');
+}
+export function createSettingsHookJudge(engine, shellRuns, promptAuthoredByUser) {
+    const llm = new Map();
+    const seen = new Map();
+    return (event, group, entry) => {
+        let dk;
+        const entryKey = settingsHookEntryKey(entry);
+        if (entryKey !== undefined && isRecord(group)) {
+            try {
+                const { hooks: _hooks, ...rest } = group;
+                void _hooks;
+                dk = `${event}\u0000${JSON.stringify(rest)}\u0000${entryKey}`;
+            }
+            catch {
+                dk = undefined;
+            }
+        }
+        const prior = dk === undefined ? undefined : seen.get(dk);
+        if (prior !== undefined)
+            return prior;
+        const type = entry.type;
+        const isLlm = type === 'prompt' || type === 'agent';
+        const ex = hookExecutorOf({
+            source: 'settings',
+            event,
+            powershell: type === 'command' && entry.shell === 'powershell',
+            llmPosition: isLlm ? (llm.get(event) ?? 0) + 1 : 0,
+            engine,
+            shellRuns: shellRuns(event, typeof type === 'string' ? type : undefined),
+            promptAuthoredByUser,
+        });
+        if (isLlm && ex.kind === 'judged' && ex.disposition !== 'shell')
+            llm.set(event, (llm.get(event) ?? 0) + 1);
+        if (dk !== undefined)
+            seen.set(dk, ex);
+        return ex;
+    };
 }
 function settingsHookEntryKey(entry) {
     if (!isRecord(entry) || typeof entry.type !== 'string')
@@ -427,6 +547,116 @@ export function dedupeSettingsHookGroups(groups) {
 export function pluginHookVerdictOf(plan, pluginId, event, groupIndex, hookIndex) {
     return plan.verdicts.find((v) => v.pluginId === pluginId && v.event === event && v.groupIndex === groupIndex && v.hookIndex === hookIndex);
 }
+function skipMatcherKey(matcher) {
+    return matcher === undefined || matcher === null || matcher === '' || matcher === '*' ? 'null' : JSON.stringify(matcher);
+}
+export function settingsHooksKeptLocally(plan, event, group, opts) {
+    let raw;
+    try {
+        raw = group?.hooks;
+    }
+    catch {
+        raw = undefined;
+    }
+    const hooks = raw;
+    if (!Array.isArray(hooks) || hooks.length === 0 || !ENGINE_EVENTS.has(event))
+        return hooks;
+    try {
+        if (COMPACTION_EVENTS.has(event) && opts?.engineCompaction === 'not_performed')
+            return hooks;
+        const planRec = plan;
+        if (!isRecord(planRec))
+            return hooks;
+        const excludedList = Object.hasOwn(planRec, 'settingsExcluded') ? planRec.settingsExcluded : [];
+        const wire = ownField(planRec, 'wire');
+        if (!Array.isArray(excludedList) || (wire !== undefined && !isRecord(wire)))
+            return hooks;
+        if (excludedList.some((e) => settingsExclusionRowOf(e)?.event === event))
+            return [];
+        const sent = new Set();
+        const groups = isRecord(wire) ? ownField(wire, event) : undefined;
+        if (Array.isArray(groups)) {
+            for (const g of groups) {
+                if (!isRecord(g))
+                    continue;
+                const gh = ownField(g, 'hooks');
+                if (!Array.isArray(gh))
+                    continue;
+                const mk = skipMatcherKey(ownField(g, 'matcher'));
+                for (const h of gh) {
+                    if (isRecord(h) && Object.hasOwn(h, 'plugin'))
+                        continue;
+                    const k = settingsHookEntryKey(ownView(h));
+                    if (k !== undefined)
+                        sent.add(`${mk}\u0000${k}`);
+                }
+            }
+        }
+        if (sent.size === 0)
+            return hooks;
+        const mk = skipMatcherKey(isRecord(group) ? group.matcher : undefined);
+        let kept = null;
+        hooks.forEach((h, i) => {
+            const k = settingsHookEntryKey(h);
+            const skip = k !== undefined && sent.has(`${mk}\u0000${k}`);
+            if (skip)
+                kept ??= hooks.slice(0, i);
+            else if (kept !== null)
+                kept.push(h);
+        });
+        return kept ?? hooks;
+    }
+    catch {
+        return hooks;
+    }
+}
+function settingsRowBaseOf(v) {
+    if (!isRecord(v))
+        return undefined;
+    const source = ownField(v, 'source');
+    const event = ownField(v, 'event');
+    const groupIndex = ownField(v, 'groupIndex');
+    const hookIndex = ownField(v, 'hookIndex');
+    if (typeof source !== 'string' || !Object.hasOwn(SOURCE_TEXT, source))
+        return undefined;
+    if (typeof event !== 'string' || !ENGINE_EVENTS.has(event))
+        return undefined;
+    if (!Number.isInteger(groupIndex) || groupIndex < 0 || !Number.isInteger(hookIndex) || hookIndex < 0)
+        return undefined;
+    return { source: source, event, groupIndex: groupIndex, hookIndex: hookIndex, o: v };
+}
+const DISPOSITION_SET = new Set(PLUGIN_HOOK_DISPOSITIONS);
+const REASON_SET = new Set(PLUGIN_HOOK_REASONS);
+const EXCLUSION_REASON_SET = new Set(PLUGIN_HOOK_EXCLUSION_REASONS);
+function settingsVerdictRowOf(v) {
+    try {
+        const b = settingsRowBaseOf(v);
+        if (b === undefined)
+            return undefined;
+        const disposition = ownField(b.o, 'disposition');
+        const reason = ownField(b.o, 'reason');
+        if (typeof disposition !== 'string' || !DISPOSITION_SET.has(disposition) || typeof reason !== 'string' || !REASON_SET.has(reason))
+            return undefined;
+        return { source: b.source, event: b.event, groupIndex: b.groupIndex, hookIndex: b.hookIndex, disposition: disposition, reason: reason };
+    }
+    catch {
+        return undefined;
+    }
+}
+function settingsExclusionRowOf(v) {
+    try {
+        const b = settingsRowBaseOf(v);
+        if (b === undefined)
+            return undefined;
+        const reason = ownField(b.o, 'reason');
+        if (typeof reason !== 'string' || !EXCLUSION_REASON_SET.has(reason))
+            return undefined;
+        return { source: b.source, event: b.event, groupIndex: b.groupIndex, hookIndex: b.hookIndex, reason: reason };
+    }
+    catch {
+        return undefined;
+    }
+}
 const REASON_TEXT = {
     projected: 'it is sent to the engine',
     shell_event: 'this client runs this event itself',
@@ -441,6 +671,12 @@ const REASON_TEXT = {
     shell_form_user_config: 'its command uses ${user_config.…} in shell form, which is refused (use exec form with "args", or read $CLAUDE_PLUGIN_OPTION_<KEY>)',
     user_config_unset: 'its command uses a plugin option that has not been set',
     malformed_entry: 'the hook entry is malformed',
+    engine_hooks_off: 'the connected engine ignores hooks sent with requests',
+    engine_hooks_unknown: 'it is not known whether the connected engine runs hooks sent with requests',
+    engine_type_skipped: 'the engine does not run PowerShell command hooks',
+    engine_llm_limit: 'the engine may skip prompt or agent hooks after the first four on one event',
+    engine_unconfirmed: 'it is sent to the engine, which is expected to run it, but this client cannot confirm that',
+    engine_elsewhere: 'it is not confirmed that the engine was started by this client on this machine, so this client runs it itself',
 };
 const DROP_TEXT = {
     exec_form_unsupported: 'exec-form hooks (with "args") are sent to the engine only once it reports support for them',
@@ -545,5 +781,22 @@ export function hooksNotRunNotice(plan) {
         const events = row.events.map((e) => noticeLabel(e)).join(', ');
         lines.push(`${SOURCE_TEXT[row.source]}: ${events} ${row.count === 1 ? 'hook' : 'hooks'} will not run — ${settingsHookDropText(row.reason)}.`);
     }
+    const settingsVerdicts = plan.settingsVerdicts;
+    const byVerdict = new Map();
+    for (const raw of Array.isArray(settingsVerdicts) ? settingsVerdicts : []) {
+        const v = settingsVerdictRowOf(raw);
+        if (v === undefined || v.disposition !== 'not_run')
+            continue;
+        const k = `${v.source}\u0000${v.reason}`;
+        const row = byVerdict.get(k) ?? { source: v.source, reason: v.reason, events: [], count: 0 };
+        if (!row.events.includes(v.event))
+            row.events.push(v.event);
+        row.count++;
+        byVerdict.set(k, row);
+    }
+    for (const row of byVerdict.values()) {
+        const events = row.events.map((e) => noticeLabel(e)).join(', ');
+        lines.push(`${SOURCE_TEXT[row.source]}: ${events} ${row.count === 1 ? 'hook' : 'hooks'} will not run — ${pluginHookReasonText(row.reason)}.`);
+    }
     return lines;
 }

package/dist/promptDelivery.d.ts

@@ -0,0 +1,20 @@
+import type { AgentEvent } from '@sema-agent/sdk';
+import { type SelfHealOutcome } from './adapter/activeRunSelfHeal.js';
+export interface PromptDeliveryRecord {
+    readonly u: string;
+    readonly s: 'a' | 'd';
+}
+export interface PromptDeliveryLedger {
+    attempted(batchUuids: readonly string[]): readonly PromptDeliveryRecord[];
+    deliveredByFrame(batchUuids: readonly string[], event: AgentEvent): readonly PromptDeliveryRecord[];
+    deliveredBySteerReceipt(batchUuids: readonly string[], outcome: SelfHealOutcome): readonly PromptDeliveryRecord[];
+    isAttempted(uuid: string): boolean;
+    isDelivered(uuid: string): boolean;
+    knownUndelivered(uuid: string): boolean;
+    batchOf(uuid: string): readonly string[] | undefined;
+    toRecords(): readonly PromptDeliveryRecord[];
+    fromRecords(records: readonly PromptDeliveryRecord[]): readonly PromptDeliveryRecord[];
+}
+export declare function createPromptDeliveryLedger(): PromptDeliveryLedger;
+export declare function promptKnownUndelivered(ledger: PromptDeliveryLedger, message: object | null | undefined): boolean;
+export declare function withoutUndeliveredPrompts<T>(ledger: PromptDeliveryLedger, messages: readonly T[]): T[];