@sema-agent/client-core 0.83.0 → 0.83.1

package/dist/fleetTaskDesc.js

@@ -1,6 +1,6 @@
-const DISPLAY_UNSAFE = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]|[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g;
+import { applyDisplayFace, LEGACY_ESCAPE_FACE, LEGACY_LABEL_FACE } from './displayUntrusted.js';
 export function escapeDisplayControlChars(s) {
-    return s.replace(DISPLAY_UNSAFE, ch => `\\u${(ch.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(4, '0')}`);
+    return applyDisplayFace(s, LEGACY_ESCAPE_FACE);
 }
 export function capForDisplay(raw, max) {
     const escaped = escapeDisplayControlChars(raw);
@@ -19,7 +19,7 @@ export function capForDisplay(raw, max) {
     return cut > 0 ? escaped.slice(0, cut) : '';
 }
 export function collapseLabel(s) {
-    return escapeDisplayControlChars(s.replace(/\s+/g, ' ').trim());
+    return applyDisplayFace(s, LEGACY_LABEL_FACE);
 }
 export function taskDescFromName(name, agentType, agentName) {
     if (!name || !agentType)

package/dist/gateVocabulary.js

@@ -116,5 +116,5 @@ export function ruleStoreUnreadableDetail(kind) {
     return `your standing deny/ask rules could not be applied to this call; the reported reason ${word} is not one of the mechanisms this client's closed set knows, so answer this ask as usual`;
 }
 export function mandatedApprovalDetail() {
-    return 'no saved allow rule and no standing posture can retire this question, so it is asked every time — answering it here settles this one call';
+    return 'no saved allow rule and no remembered answer can retire this question; each call is settled on its own — by you here, by a hook, or by an automatic check the deployment runs — and an answer covers only that call';
 }

package/dist/hitl/approvalDecisionNoteAudit.js

@@ -1,10 +1,12 @@
+import { displayUntrusted } from '../displayUntrusted.js';
 const NOTE_DISPLAY_MAX = 200;
 export const DECISION_NOTE_NOTICE_KEY = 'approval-decision-note';
 function cleanNote(raw) {
-    const flat = raw
-        .replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ')
+    const flat = displayUntrusted(raw, { credentialUrls: false, credentialWords: false, foldLines: false, mark: 'space' })
         .replace(/ {2,}/g, ' ')
         .trim();
+    if (flat === '')
+        return undefined;
     return flat.length <= NOTE_DISPLAY_MAX ? flat : `${flat.slice(0, NOTE_DISPLAY_MAX - 1)}…`;
 }
 export function readDecisionNoteAudit(ack) {

package/dist/hitl/sessionPolicyDeliverable.d.ts

@@ -0,0 +1,14 @@
+import type { SessionPermissionRules } from '@sema-agent/sdk';
+export type SessionPolicyWithheldWhy = 'ask_no_bucket' | 'qualified_deny' | 'peer_wide' | 'wildcard' | 'not_a_tool_name';
+export declare const SESSION_POLICY_WITHHELD_WHY: readonly SessionPolicyWithheldWhy[];
+export interface SessionPolicyWithheldRule {
+    readonly rule: string;
+    readonly why: SessionPolicyWithheldWhy;
+}
+export interface SessionPolicyDeliverability {
+    readonly deliverable: SessionPermissionRules;
+    readonly withheld: readonly SessionPolicyWithheldRule[];
+    readonly unreadable?: true;
+}
+export declare function sessionPolicyDeliverable(behavior: 'deny' | 'ask', rules: readonly string[]): SessionPolicyDeliverability;
+export declare function sessionPolicyWithheldNotice(why: SessionPolicyWithheldWhy): string;

package/dist/hitl/sessionPolicyDeliverable.js

@@ -0,0 +1,80 @@
+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 covers every tool of one server or agent peer, and an engine that matches that record by exact tool name would block none of them.',
+    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.',
+};
+export const SESSION_POLICY_WITHHELD_WHY = Object.freeze(Object.keys(WITHHELD_NOTICE));
+const MAX_RULES = 10_000;
+function unreadable() {
+    return { deliverable: {}, withheld: [], unreadable: true };
+}
+const COVERING_NAMESPACE_PREFIXES = ['mcp__', 'a2a__'];
+function withheldWhyOf(rule) {
+    if (rule.length === 0)
+        return 'not_a_tool_name';
+    if (/(?:^|[^\\])\(/.test(rule))
+        return 'qualified_deny';
+    if (rule.includes('*'))
+        return 'wildcard';
+    for (const prefix of COVERING_NAMESPACE_PREFIXES) {
+        if (!rule.startsWith(prefix))
+            continue;
+        const segments = rule.slice(prefix.length).split('__');
+        if (segments[0] !== '' && segments.slice(1).join('__') === '')
+            return 'peer_wide';
+    }
+    if (rule.trim() !== rule)
+        return 'not_a_tool_name';
+    return undefined;
+}
+export function sessionPolicyDeliverable(behavior, rules) {
+    const entries = [];
+    try {
+        if (behavior !== 'deny' && behavior !== 'ask')
+            return unreadable();
+        if (!Array.isArray(rules))
+            return unreadable();
+        const n = rules.length;
+        if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 0 || n > MAX_RULES)
+            return unreadable();
+        for (let i = 0; i < n; i++) {
+            if (!Object.hasOwn(rules, i)) {
+                entries.push(undefined);
+                continue;
+            }
+            const x = rules[i];
+            entries.push(typeof x === 'string' ? x : undefined);
+        }
+    }
+    catch {
+        return unreadable();
+    }
+    const withheld = [];
+    if (behavior === 'ask') {
+        for (const r of entries)
+            withheld.push({ rule: r ?? '', why: 'ask_no_bucket' });
+        return { deliverable: {}, withheld };
+    }
+    const exact = [];
+    for (const r of entries) {
+        if (r === undefined) {
+            withheld.push({ rule: '', why: 'not_a_tool_name' });
+            continue;
+        }
+        const why = withheldWhyOf(r);
+        if (why === undefined)
+            exact.push(r);
+        else
+            withheld.push({ rule: r, why });
+    }
+    if (withheld.length > 0 || exact.length === 0)
+        return { deliverable: {}, withheld };
+    return { deliverable: { toolDeny: exact }, withheld };
+}
+export function sessionPolicyWithheldNotice(why) {
+    return typeof why === 'string' && Object.hasOwn(WITHHELD_NOTICE, why)
+        ? WITHHELD_NOTICE[why]
+        : 'Not written to this session’s rule record.';
+}

package/dist/hooksWireCaps.d.ts

@@ -1,8 +1,13 @@
+import { type HooksWirePlan, type HooksWirePlanOptions } from './pluginHooksWire.js';
 import { type HookFailureNotice } from './notifications.js';
 import type { WireHooksConfig } from './finalVerifyWire.js';
 export { GOAL_STOP_HOOK_WIRE_ENV, CC_STOP_SEMANTICS_MIN_SERVER, ccStopSemanticsFromVersion, engineCcStopSemantics, isGoalStopHookWireArmed, setWireSessionStopHook, getWireSessionStopHook, getWireSessionStopHookCcSemantics, buildGoalStopHookPrompt, } from './goalStopHook.js';
 export type { WireHooksConfig };
-export declare function hooksForWire(): WireHooksConfig | undefined;
+export interface HooksForWireOptions {
+    readonly plan?: HooksWirePlan;
+}
+export declare function hooksForWire(opts?: HooksForWireOptions): WireHooksConfig | undefined;
+export declare function hooksWirePlan(opts?: HooksWirePlanOptions): HooksWirePlan;
 export declare function __resetHooksWireCapsForTests(): void;
 export declare function fleetHookFailureNoticeCapable(baseUrl: string | undefined): boolean;
 export declare const HOOK_FAILURE_WARN_PREFIX = "Hook error";

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;
@@ -42,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 {
@@ -62,25 +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 managedByPolicy = policy?.allowManagedHooksOnly === true || pluginOnlyHooks;
-    const disabledByNonManaged = !managedByPolicy && nonManagedDisableAllHooks(settings);
+    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']
-        : ['policySettings', ...EDITABLE_HOOK_SOURCES];
+    const sources = managedOnly ? ['policySettings'] : ALL_HOOK_SOURCES;
     const merged = {};
     for (const source of sources) {
         const hooks = hooksOfSource(source);
@@ -89,18 +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,10 +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/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 {};