@sema-agent/client-core 0.82.7 → 0.83.1

package/dist/hooksWireCaps.js

@@ -1,10 +1,15 @@
-import { engineCapNestedTrue } from './engineCapsCache.js';
+import { engineCapNestedTrue, engineCapState } from './engineCapsCache.js';
+import { displayUntrusted } from './displayUntrusted.js';
 import { collapseLabel } from './fleetTaskDesc.js';
 import { hostLog, hostSettings } from './host.js';
+import { decidePluginHooks, filterSettingsHookGroups, occupancyOf, settingsHookDropText, } from './pluginHooksWire.js';
 import { MAX_HOOK_NOTICE_TEXT_CHARS } from './notifications.js';
 import { goalStopHookMatcher, __resetGoalStopHookForTests } from './goalStopHook.js';
 export { GOAL_STOP_HOOK_WIRE_ENV, CC_STOP_SEMANTICS_MIN_SERVER, ccStopSemanticsFromVersion, engineCcStopSemantics, isGoalStopHookWireArmed, setWireSessionStopHook, getWireSessionStopHook, getWireSessionStopHookCcSemantics, buildGoalStopHookPrompt, } from './goalStopHook.js';
 const EDITABLE_HOOK_SOURCES = ['userSettings', 'projectSettings', 'localSettings'];
+const ALL_HOOK_SOURCES = ['policySettings', ...EDITABLE_HOOK_SOURCES];
+const _hookSourceListsPin = [true, true];
+void _hookSourceListsPin;
 function hooksLockedToPluginOnly(policyValue) {
     if (policyValue === true)
         return true;
@@ -12,6 +17,26 @@ function hooksLockedToPluginOnly(policyValue) {
         return policyValue.includes('hooks');
     return false;
 }
+let warnedNoMergedReader = new WeakSet();
+const NO_MERGED_READER_WARNING = 'client-core: the installed settings port does not implement mergedDisableAllHooks() — ' +
+    'a disableAllHooks set in user, project, local or flag settings is not applied to hooks sent to the engine ' +
+    '(only a managed-settings disableAllHooks is). Implement SettingsPort.mergedDisableAllHooks() to return ' +
+    'the effective merged value.';
+function nonManagedDisableAllHooks(settings) {
+    try {
+        if (typeof settings.mergedDisableAllHooks === 'function')
+            return settings.mergedDisableAllHooks() === true;
+    }
+    catch (err) {
+        hostLog('debug', `hooksWireCaps: merged disableAllHooks read threw — fail-closed (only policySettings hooks projected to the engine): ${String(err)}`);
+        return true;
+    }
+    if (!warnedNoMergedReader.has(settings)) {
+        warnedNoMergedReader.add(settings);
+        hostLog('warn', NO_MERGED_READER_WARNING);
+    }
+    return false;
+}
 function hooksOfSource(source) {
     try {
         const s = hostSettings()?.getSettingsForSource(source);
@@ -22,19 +47,137 @@ function hooksOfSource(source) {
         return null;
     }
 }
-export function hooksForWire() {
+let warnedNoPluginReader = new WeakSet();
+const NO_PLUGIN_READER_WARNING = 'client-core: the installed settings port does not implement enabledPluginHooks() — ' +
+    'plugin hooks are not sent to the engine and are not reported as not running. ' +
+    'Implement SettingsPort.enabledPluginHooks() to list the enabled plugins and their hooks.';
+let warnedNoPlanDrops = new WeakMap();
+function noPlanDropWarning(event, reason) {
+    return (`client-core: ${displayUntrusted(event, { credentialUrls: false, credentialWords: false })} hooks from settings are not sent to the engine (${reason}), so they do not run there — ` +
+        `${settingsHookDropText(reason)}. Build the request with hooksForWire({ plan }) from hooksWirePlan() and show ` +
+        'hooksNotRunNotice(plan) to tell the user which hooks will not run.');
+}
+function guardPluginTraversal(run) {
+    try {
+        return run();
+    }
+    catch (err) {
+        hostLog('debug', `hooksWireCaps: plugin hook data threw while being read — no plugin hooks projected this turn: ${String(err)}`);
+        return undefined;
+    }
+}
+function readPluginHooks(settings, warnIfAbsent) {
+    try {
+        if (typeof settings.enabledPluginHooks === 'function') {
+            const r = settings.enabledPluginHooks();
+            if (typeof r === 'object' && r !== null && Array.isArray(r.plugins)) {
+                return { state: 'present', reading: r };
+            }
+            hostLog('debug', 'hooksWireCaps: enabledPluginHooks() returned a malformed reading — no plugin hooks projected this turn');
+            return { state: 'failed' };
+        }
+    }
+    catch (err) {
+        hostLog('debug', `hooksWireCaps: enabledPluginHooks() threw — no plugin hooks projected this turn: ${String(err)}`);
+        return { state: 'failed' };
+    }
+    if (warnIfAbsent && !warnedNoPluginReader.has(settings)) {
+        warnedNoPluginReader.add(settings);
+        hostLog('warn', NO_PLUGIN_READER_WARNING);
+    }
+    return { state: 'absent' };
+}
+const NO_PLAN_ENGINE = { ownedByThisShell: null, pluginHooksCapable: null };
+export function hooksForWire(opts = {}) {
+    const given = opts?.plan;
+    if (isHooksWirePlan(given))
+        return given.wire;
+    if (given !== undefined && given !== null) {
+        hostLog('debug', 'hooksForWire: opts.plan is not a plan from hooksWirePlan() — treated as absent (settings hooks only)');
+    }
+    if (isHooksWirePlan(opts))
+        return opts.wire;
+    return buildHooksWirePlan(NO_PLAN_ENGINE, new Set(), false).wire;
+}
+function isHooksWirePlan(v) {
+    try {
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            return false;
+        const o = v;
+        for (const k of PLAN_KEYS)
+            if (!Object.hasOwn(o, k))
+                return false;
+        const reader = o.pluginReader;
+        const engineFacts = o.engine;
+        const wire = o.wire;
+        return (Array.isArray(o.verdicts) &&
+            Array.isArray(o.excluded) &&
+            Array.isArray(o.settingsDropped) &&
+            (reader === 'present' || reader === 'absent' || reader === 'failed') &&
+            typeof engineFacts === 'object' &&
+            engineFacts !== null &&
+            (wire === undefined || (typeof wire === 'object' && wire !== null && !Array.isArray(wire))));
+    }
+    catch (err) {
+        hostLog('debug', `hooksForWire: a value offered as a plan threw while being read — treated as not a plan: ${String(err)}`);
+        return false;
+    }
+}
+const PLAN_KEYS = ['engine', 'pluginReader', 'verdicts', 'excluded', 'settingsDropped', 'wire'];
+const _planKeysPin = [true, true];
+void _planKeysPin;
+export function hooksWirePlan(opts = {}) {
+    const o = opts ?? {};
+    const owned = o.engineOwnedByThisShell;
+    const engine = {
+        ownedByThisShell: owned === true ? true : owned === false ? false : null,
+        pluginHooksCapable: engineCapState(o.baseUrl, 'taskSettings') === 'unprobed'
+            ? null
+            : engineCapNestedTrue(o.baseUrl, 'taskSettings', 'pluginHooks'),
+    };
+    const shellEvents = new Set();
+    if (Array.isArray(o.shellHookEvents)) {
+        for (const e of o.shellHookEvents)
+            if (typeof e === 'string')
+                shellEvents.add(e);
+    }
+    return buildHooksWirePlan(engine, shellEvents, true);
+}
+function buildHooksWirePlan(engine, shellEvents, withPlugins) {
+    const settingsDropped = [];
+    let settingsStripped = 0;
+    const planOf = (pluginReader, wire, verdicts = [], excluded = []) => ({ engine, pluginReader, verdicts, excluded, settingsDropped, wire });
+    const closedPlan = (settings, reason) => {
+        if (!withPlugins)
+            return planOf('absent', undefined);
+        const read = readPluginHooks(settings, false);
+        if (read.reading === undefined)
+            return planOf(read.state, undefined);
+        const reading = read.reading;
+        const d = guardPluginTraversal(() => decidePluginHooks({
+            plugins: reading.plugins,
+            exclusion: reason,
+            managedOnly: false,
+            engine,
+            shellHookEvents: shellEvents,
+            occupied: new Map(),
+        }));
+        if (d === undefined)
+            return planOf('failed', undefined);
+        return planOf(read.state, undefined, d.verdicts, d.excluded);
+    };
     const settings = hostSettings();
     if (settings === undefined)
-        return undefined;
+        return planOf('absent', undefined);
     try {
         if (settings.shouldSkipHookDueToTrust()) {
             hostLog('debug', 'hooksWireCaps: workspace not trusted — no hooks projected to the engine');
-            return undefined;
+            return closedPlan(settings, 'workspace_untrusted');
         }
     }
     catch (err) {
         hostLog('debug', `hooksWireCaps: workspace trust check threw — fail-closed (no hooks projected to the engine): ${String(err)}`);
-        return undefined;
+        return closedPlan(settings, 'governance_unreadable');
     }
     let policy = null;
     try {
@@ -42,20 +185,25 @@ export function hooksForWire() {
     }
     catch (err) {
         hostLog('debug', `hooksWireCaps: policySettings read threw — fail-closed (no hooks projected to the engine): ${String(err)}`);
-        return undefined;
+        return closedPlan(settings, 'governance_unreadable');
     }
     if (policy?.disableAllHooks === true) {
         hostLog('debug', 'hooksWireCaps: disableAllHooks (managed) — no hooks projected to the engine');
-        return undefined;
+        return closedPlan(settings, 'policy_disable_all');
     }
     const pluginOnlyHooks = hooksLockedToPluginOnly(policy?.strictPluginOnlyCustomization);
     if (pluginOnlyHooks) {
         hostLog('debug', 'hooksWireCaps: strictPluginOnlyCustomization locks the hooks surface (managed) — only policySettings hooks projected to the engine');
     }
-    const managedOnly = policy?.allowManagedHooksOnly === true || pluginOnlyHooks;
-    const sources = managedOnly
-        ? ['policySettings']
-        : ['policySettings', ...EDITABLE_HOOK_SOURCES];
+    const managedByPolicy = policy?.allowManagedHooksOnly === true || pluginOnlyHooks;
+    let mergedMemo;
+    const mergedDisable = () => (mergedMemo ??= nonManagedDisableAllHooks(settings));
+    const disabledByNonManaged = !managedByPolicy && mergedDisable();
+    if (disabledByNonManaged) {
+        hostLog('debug', 'hooksWireCaps: disableAllHooks (merged, non-managed) — only policySettings hooks projected to the engine');
+    }
+    const managedOnly = managedByPolicy || disabledByNonManaged;
+    const sources = managedOnly ? ['policySettings'] : ALL_HOOK_SOURCES;
     const merged = {};
     for (const source of sources) {
         const hooks = hooksOfSource(source);
@@ -64,17 +212,76 @@ export function hooksForWire() {
         for (const [event, groups] of Object.entries(hooks)) {
             if (!Array.isArray(groups) || groups.length === 0)
                 continue;
-            merged[event] = [...(merged[event] ?? []), ...groups];
+            const kept = filterSettingsHookGroups(source, event, groups, engine.pluginHooksCapable === true, shellEvents.has(event), !withPlugins);
+            settingsDropped.push(...kept.drops);
+            settingsStripped += kept.stripped;
+            if (kept.groups.length === 0)
+                continue;
+            merged[event] = [...(merged[event] ?? []), ...kept.groups];
         }
     }
     const goalMatcher = goalStopHookMatcher(managedOnly);
     if (goalMatcher !== null) {
         merged['Stop'] = [...(merged['Stop'] ?? []), goalMatcher];
     }
-    return Object.keys(merged).length > 0 ? merged : undefined;
+    if (settingsDropped.length > 0) {
+        hostLog('debug', `hooksWireCaps: ${settingsDropped.length} settings hook entr${settingsDropped.length === 1 ? 'y' : 'ies'} not sent to the engine ` +
+            `(${[...new Set(settingsDropped.map((d) => d.reason))].join(', ')}) — see hooksWirePlan().settingsDropped`);
+    }
+    if (settingsStripped > 0) {
+        hostLog('debug', `hooksWireCaps: ${settingsStripped} settings hook entr${settingsStripped === 1 ? 'y' : 'ies'} carried a plugin key — ` +
+            'stripped before sending (plugin context is only minted for entries from the plugin reader)');
+    }
+    const wireOf = () => (Object.keys(merged).length > 0 ? merged : undefined);
+    if (!withPlugins) {
+        let seen = warnedNoPlanDrops.get(settings);
+        for (const d of settingsDropped) {
+            if (!d.notRun)
+                continue;
+            const key = `${d.event}\u0000${d.reason}`;
+            if (seen?.has(key) === true)
+                continue;
+            if (seen === undefined) {
+                seen = new Set();
+                warnedNoPlanDrops.set(settings, seen);
+            }
+            seen.add(key);
+            hostLog('warn', noPlanDropWarning(d.event, d.reason));
+        }
+        return planOf('absent', wireOf());
+    }
+    const read = readPluginHooks(settings, true);
+    if (read.reading === undefined)
+        return planOf(read.state, wireOf());
+    const reading = read.reading;
+    const occupied = occupancyOf(merged);
+    const d = guardPluginTraversal(() => {
+        const plugins = reading.plugins;
+        const startupMode = reading.suppressedByStartupMode === true;
+        const managedOnlyPlugins = !startupMode && plugins.length > 0 && (policy?.allowManagedHooksOnly === true || mergedDisable());
+        return decidePluginHooks({
+            plugins,
+            exclusion: startupMode ? 'startup_mode' : undefined,
+            managedOnly: managedOnlyPlugins,
+            engine,
+            shellHookEvents: shellEvents,
+            occupied,
+        });
+    });
+    if (d === undefined)
+        return planOf('failed', wireOf());
+    if (d.unreadable > 0) {
+        hostLog('debug', `hooksWireCaps: ${d.unreadable} plugin hook source(s) or group(s) unreadable — skipped`);
+    }
+    for (const [event, groups] of d.projected)
+        merged[event] = [...(merged[event] ?? []), ...groups];
+    return planOf('present', wireOf(), d.verdicts, d.excluded);
 }
 export function __resetHooksWireCapsForTests() {
     __resetGoalStopHookForTests();
+    warnedNoMergedReader = new WeakSet();
+    warnedNoPluginReader = new WeakSet();
+    warnedNoPlanDrops = new WeakMap();
 }
 export function fleetHookFailureNoticeCapable(baseUrl) {
     return engineCapNestedTrue(baseUrl, 'fleet', 'hookFailureNotice');

package/dist/host.d.ts

@@ -1,9 +1,34 @@
 import type { AdapterLogLevel, TimerHandle } from './seam.js';
+import type { WireHooksConfig } from './finalVerifyWire.js';
 import { type NotificationQueuePort } from './notifications.js';
 export type SettingsDocument = Record<string, unknown>;
 export interface SettingsPort {
     getSettingsForSource(source: string): SettingsDocument | null;
     shouldSkipHookDueToTrust(hook?: unknown): boolean;
+    mergedDisableAllHooks?(): boolean | undefined;
+    enabledPluginHooks?(): PluginHooksReading;
+}
+export type PluginHookOptionValue = string | number | boolean;
+export interface PluginHookSensitiveOption {
+    readonly sensitive: true;
+}
+export interface PluginHookPlainOption {
+    readonly sensitive: false;
+    readonly value?: PluginHookOptionValue;
+}
+export type PluginHookOption = PluginHookSensitiveOption | PluginHookPlainOption;
+export interface PluginHookSource {
+    readonly id: string;
+    readonly name: string;
+    readonly root: string;
+    readonly dataDir: string;
+    readonly managed: boolean;
+    readonly options?: Readonly<Record<string, PluginHookOption>>;
+    readonly hooks: WireHooksConfig;
+}
+export interface PluginHooksReading {
+    readonly plugins: readonly PluginHookSource[];
+    readonly suppressedByStartupMode?: boolean;
 }
 export interface FsPort {
     getScratchpadDir(): string | undefined;

package/dist/index.d.ts

@@ -56,6 +56,8 @@ export * from './modelCapabilityProbe.js';
 export * from './classifierStatus.js';
 export * from './engineToolLabelStore.js';
 export * from './fleetTaskDesc.js';
+export { displayUntrusted } from './displayUntrusted.js';
+export type { DisplayUntrustedOptions, DisplayMark } from './displayUntrusted.js';
 export type * from './types/engineState.js';
 export * from './hostEnv.js';
 export * from './unrefTimer.js';
@@ -135,6 +137,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, type EngineFiredHookEvent, type PluginHookDisposition, type PluginHookReason, type PluginHookExclusionReason, type SettingsHookDropReason, type HookSettingsSource, type PluginHookKey, type PluginHookVerdict, type PluginHookExclusion, type SettingsHookDrop, type HooksWireEngineFacts, type PluginHookReaderState, type HooksWirePlan, type HooksWirePlanOptions, } from './pluginHooksWire.js';
 export * from './liveInitToolFace.js';
 export * from './printInitToolFace.js';
 export * from './model/providerPresets.js';
@@ -160,6 +163,7 @@ export * from './hitl/resumeRunningCard.js';
 export * from './hitl/persistedRulesWire.js';
 export * from './hitl/localAllowRule.js';
 export * from './hitl/sessionPolicyWire.js';
+export * from './hitl/sessionPolicyDeliverable.js';
 export * from './hitl/approvalsFeed.js';
 export * from './hitl/livePendingAsk.js';
 export * from './hitl/crashConverged.js';

package/dist/index.js

@@ -56,6 +56,7 @@ export * from './modelCapabilityProbe.js';
 export * from './classifierStatus.js';
 export * from './engineToolLabelStore.js';
 export * from './fleetTaskDesc.js';
+export { displayUntrusted } from './displayUntrusted.js';
 export * from './hostEnv.js';
 export * from './unrefTimer.js';
 export * from './controlRouter.js';
@@ -133,6 +134,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 * from './liveInitToolFace.js';
 export * from './printInitToolFace.js';
 export * from './model/providerPresets.js';
@@ -158,6 +160,7 @@ export * from './hitl/resumeRunningCard.js';
 export * from './hitl/persistedRulesWire.js';
 export * from './hitl/localAllowRule.js';
 export * from './hitl/sessionPolicyWire.js';
+export * from './hitl/sessionPolicyDeliverable.js';
 export * from './hitl/approvalsFeed.js';
 export * from './hitl/livePendingAsk.js';
 export * from './hitl/crashConverged.js';

package/dist/liveInitToolFace.d.ts

@@ -15,7 +15,9 @@ export declare function probeScenarioTools(baseUrl: string, scenario: string, op
     tools: string[];
     toolset?: string;
 } | null>;
-export declare function resolveLiveInitToolFace(argv: readonly string[], env: EnvLike, opts?: {
+export interface LiveInitToolFaceOptions {
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
-}): Promise<LiveInitToolFace | null>;
+    webSearchStamped?: boolean;
+}
+export declare function resolveLiveInitToolFace(argv: readonly string[], env: EnvLike, opts?: LiveInitToolFaceOptions): Promise<LiveInitToolFace | null>;

package/dist/liveInitToolFace.js

@@ -2,7 +2,7 @@ import { makeEngineWireClient, resolveWireAuth } from './engineWireSdk.js';
 import { hostLog } from './host.js';
 import { scenarioForPrint } from './scenarioWire.js';
 import { resolveHeadlessInteractiveTools } from './interactiveToolsWire.js';
-import { webSearchFromEnv } from './webSearchWireCaps.js';
+import { webSearchVerdictFromEnv } from './webSearchWireCaps.js';
 export const ENGINE_HANDS_BAND = [
     'Bash',
     'Read',
@@ -105,7 +105,7 @@ export async function resolveLiveInitToolFace(argv, env, opts) {
         }
         let webSearch = false;
         try {
-            webSearch = webSearchFromEnv(env) !== undefined;
+            webSearch = typeof opts?.webSearchStamped === 'boolean' ? opts.webSearchStamped : webSearchVerdictFromEnv(env).kind === 'honored';
         }
         catch {
         }

package/dist/model/catalogLoader.d.ts

@@ -1,5 +1,5 @@
 import { type EnvLike } from '../hostEnv.js';
-import { type ModelCatalogResult, type OnlineCatalogDoc } from './catalog.js';
+import { type ModelCatalogResult } from './catalog.js';
 import type { ProviderPreset } from './providerPresets.js';
 export declare const DEFAULT_CATALOG_SOURCES: readonly string[];
 export declare const CATALOG_DEFAULT_HOSTS: readonly string[];
@@ -12,11 +12,6 @@ export interface CatalogSourceAttempt {
     shaChecked?: boolean;
     detail?: string;
 }
-export interface CatalogCacheEnvelope {
-    fetchedAt?: number;
-    sourceUrl: string;
-    catalog: OnlineCatalogDoc;
-}
 export interface CatalogCachePort {
     read(path: string): string | null | Promise<string | null>;
     writeAtomic(path: string, text: string): void | Promise<void>;

package/dist/panelRunningHistory.d.ts

@@ -1,6 +1,6 @@
 export declare function notePanelRowRunning(taskId: string): void;
 export declare function retirePanelRowRunning(taskId: string): void;
-export interface PanelRowEndedIdentity {
+interface PanelRowEndedIdentity {
     cycleSeq?: number;
     startedAt?: number;
 }
@@ -11,7 +11,7 @@ export declare function holdNewbornTerminalRow(taskId: string, ev: object): void
 export declare function peekHeldNewbornTerminalRow<T extends object>(taskId: string): T | undefined;
 export declare function takeHeldNewbornTerminalRow<T extends object>(taskId: string): T | undefined;
 export declare function dropHeldNewbornTerminalRow(taskId: string): void;
-export interface HeldNewbornTerminalRef {
+interface HeldNewbornTerminalRef {
     readonly taskId: string;
     readonly transcriptId?: string;
     readonly parentToolCallId?: string;
@@ -19,3 +19,4 @@ export interface HeldNewbornTerminalRef {
 export declare function heldNewbornTerminalRefs(): HeldNewbornTerminalRef[];
 export declare function __resetPanelRunningHistoryForTests(): void;
 export declare function __panelRunningHistorySize(): number;
+export {};

package/dist/peerFrames.d.ts

@@ -1,7 +1,6 @@
 export declare const AGENT_MESSAGE_TAG = "agent-message";
 export declare const CROSS_SESSION_MESSAGE_TAG = "cross-session-message";
 export declare const PEER_FRAME_LANES: readonly ["agent_message", "cross_session_message", "cross_session_notice"];
-export type PeerFrameLane = (typeof PEER_FRAME_LANES)[number];
 export declare const CROSS_SESSION_NOTICE_KINDS: readonly ["delivery_notice", "idle_notice"];
 export type CrossSessionNoticeKind = (typeof CROSS_SESSION_NOTICE_KINDS)[number];
 export declare const PEER_MODE_CLASSES: readonly ["bypass", "prompting"];

package/dist/peerFrames.js

@@ -1,3 +1,4 @@
+import { applyDisplayFace, LEGACY_NAME_FACE } from './displayUntrusted.js';
 const WIRE_KEY_FROM = 'from';
 const WIRE_KEY_BODY = 'body';
 const WIRE_KEY_KIND = 'kind';
@@ -124,7 +125,7 @@ function neutralizeAuthorityTags(text) {
 function cleanName(v) {
     if (typeof v !== 'string')
         return undefined;
-    const t = v.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, ' ').replace(/\s+/g, ' ').trim();
+    const t = applyDisplayFace(v, LEGACY_NAME_FACE);
     return t.length > 0 ? t : undefined;
 }
 function escapeEnvelopeTag(tag, text) {

package/dist/pluginHooksWire.d.ts

@@ -0,0 +1,92 @@
+import type { WireHooksConfig } from './finalVerifyWire.js';
+import type { PluginHookSource } from './host.js';
+export declare const ENGINE_FIRED_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreCompact", "PostCompact", "Stop", "StopFailure", "UserPromptSubmit"];
+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 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 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];
+export type HookSettingsSource = 'policySettings' | 'userSettings' | 'projectSettings' | 'localSettings';
+export interface PluginHookKey {
+    readonly pluginId: string;
+    readonly pluginName: string;
+    readonly event: string;
+    readonly groupIndex: number;
+    readonly hookIndex: number;
+}
+export interface PluginHookVerdict extends PluginHookKey {
+    readonly disposition: PluginHookDisposition;
+    readonly reason: PluginHookReason;
+}
+export interface PluginHookExclusion extends PluginHookKey {
+    readonly reason: PluginHookExclusionReason;
+}
+export interface SettingsHookDrop {
+    readonly source: HookSettingsSource;
+    readonly event: string;
+    readonly groupIndex: number;
+    readonly hookIndex: number;
+    readonly reason: SettingsHookDropReason;
+    readonly notRun: boolean;
+}
+export interface HooksWireEngineFacts {
+    readonly ownedByThisShell: boolean | null;
+    readonly pluginHooksCapable: boolean | null;
+}
+export type PluginHookReaderState = 'present' | 'absent' | 'failed';
+export interface HooksWirePlan {
+    readonly engine: HooksWireEngineFacts;
+    readonly pluginReader: PluginHookReaderState;
+    readonly verdicts: readonly PluginHookVerdict[];
+    readonly excluded: readonly PluginHookExclusion[];
+    readonly settingsDropped: readonly SettingsHookDrop[];
+    readonly wire: WireHooksConfig | undefined;
+}
+export interface HooksWirePlanOptions {
+    readonly baseUrl?: string;
+    readonly engineOwnedByThisShell?: boolean;
+    readonly shellHookEvents?: readonly string[];
+}
+export declare const ENGINE_HOOK_LIMITS: {
+    readonly maxGroupsPerEvent: 16;
+    readonly maxEntriesPerEvent: 32;
+    readonly maxCommandChars: 8192;
+};
+type WireHookGroup = NonNullable<WireHooksConfig[string]>[number];
+export declare function isEngineFiredHookEvent(event: string): boolean;
+export interface EventOccupancy {
+    readonly groups: number;
+    readonly entries: number;
+}
+export declare function occupancyOf(wire: WireHooksConfig): Map<string, EventOccupancy>;
+export interface PluginHookDecisionInput {
+    readonly plugins: readonly PluginHookSource[];
+    readonly exclusion: PluginHookExclusionReason | undefined;
+    readonly managedOnly: boolean;
+    readonly engine: HooksWireEngineFacts;
+    readonly shellHookEvents: ReadonlySet<string>;
+    readonly occupied: ReadonlyMap<string, EventOccupancy>;
+}
+export interface PluginHookDecision {
+    readonly verdicts: readonly PluginHookVerdict[];
+    readonly excluded: readonly PluginHookExclusion[];
+    readonly projected: ReadonlyMap<string, readonly WireHookGroup[]>;
+    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 interface SettingsHookFilterResult {
+    readonly groups: WireHookGroup[];
+    readonly drops: SettingsHookDrop[];
+    readonly stripped: number;
+}
+export declare function pluginHookVerdictOf(plan: HooksWirePlan, pluginId: string, event: string, groupIndex: number, hookIndex: number): PluginHookVerdict | undefined;
+export declare function pluginHookReasonText(reason: PluginHookReason): string;
+export declare function settingsHookDropText(reason: SettingsHookDropReason): string;
+export declare function pluginHookExecutorLabel(v: PluginHookVerdict): string;
+export declare function hooksNotRunNotice(plan: HooksWirePlan): readonly string[];
+export {};