@sema-agent/client-core 0.98.0 → 0.100.0

package/dist/permissionRuleIssue.js

@@ -1,7 +1,9 @@
 import { capForDisplay, escapeDisplayControlChars } from './fleetTaskDesc.js';
+import { msg, renderMessage } from './i18n/translate.js';
 export const PERMISSION_RULE_ISSUE_CODES = Object.freeze([
     'invalid.empty_tool',
     'invalid.paren',
+    'invalid.tool_name',
     'invalid.param_split',
     'invalid.primary_field',
     'invalid.cap_exceeded',
@@ -19,24 +21,25 @@ export const PERMISSION_RULE_ISSUE_CODES = Object.freeze([
 export const RETIRED_PERMISSION_RULE_ISSUE_CODES = Object.freeze(['unsupported.unknown_param']);
 const ISSUE_MESSAGE_MAX = 200;
 const ISSUE_SENTENCES = Object.freeze({
-    'invalid.empty_tool': 'this rule is invalid: it names no tool',
-    'invalid.paren': 'this rule is invalid: its parentheses do not parse (escape a literal one as \\( or \\))',
-    'invalid.param_split': 'this rule is invalid: its parentheses do not hold a parameter rule written name:pattern',
-    'invalid.primary_field': "this rule is invalid: it patterns the tool's primary field, which matches the whole trimmed string rather than a prefix",
-    'invalid.cap_exceeded': 'this rule set is invalid: it is over one of the deployment caps (rule count, rule length, pattern length, or star count); this client cannot tell which from the code alone',
-    'invalid.behavior': 'this rule is invalid: its behavior is neither deny nor ask, so it would never fire',
-    'invalid.command_rule': 'this rule is invalid: the command pattern was rejected by the command-rule validator',
-    'invalid.entry_type': 'this allow list is invalid: it must be a list of rule strings, and it or one of its entries is not a string',
-    'unsupported.allow': 'an allow rule is not supported in a rule set that only says deny or ask — a standing approval belongs on the allow list instead',
-    'unsupported.param_unknown': 'this parameter rule is not supported: the tool carries no such parameter, so it could never match',
-    'unsupported.param_non_scalar': 'this parameter rule is not supported: that parameter holds an object or an array, so it could never match',
-    'unsupported.tool_unknown': "this rule is not supported on this leg: the resolver it supplied does not know the tool, so the rule's face cannot be checked",
-    'unsupported.path_base': 'this path rule is not supported as spelled: the base it is relative to is missing or is not a usable absolute path, so it would reach nothing and is refused rather than compiled',
-    'unsupported.mcp_paren': 'a parenthesised parameter rule is not supported on an MCP tool name',
-    'unsupported.covering_paren': 'a parenthesised parameter rule is not supported on a covering protocol name — the parameter grammar is keyed by an exact tool name, so no mounted tool could ever bear it',
+    'invalid.empty_tool': 'rules.issue.emptyTool',
+    'invalid.paren': 'rules.issue.paren',
+    'invalid.tool_name': 'rules.issue.toolName',
+    'invalid.param_split': 'rules.issue.paramSplit',
+    'invalid.primary_field': 'rules.issue.primaryField',
+    'invalid.cap_exceeded': 'rules.issue.capExceeded',
+    'invalid.behavior': 'rules.issue.behavior',
+    'invalid.command_rule': 'rules.issue.commandRule',
+    'invalid.entry_type': 'rules.issue.entryType',
+    'unsupported.allow': 'rules.issue.allowRule',
+    'unsupported.param_unknown': 'rules.issue.paramUnknown',
+    'unsupported.param_non_scalar': 'rules.issue.paramNonScalar',
+    'unsupported.tool_unknown': 'rules.issue.toolUnknown',
+    'unsupported.path_base': 'rules.issue.pathBase',
+    'unsupported.mcp_paren': 'rules.issue.mcpParen',
+    'unsupported.covering_paren': 'rules.issue.coveringParen',
 });
-const PARAM_SPLIT_WITH_COLON = 'this rule is invalid: a parameter rule is written name:pattern, and the name before the colon or the pattern after it is empty';
-const PARAM_SPLIT_NO_COLON = 'this rule is invalid: there is no colon inside the parentheses, so this is not a parameter rule (a parameter rule is written name:pattern)';
+const PARAM_SPLIT_WITH_COLON = 'rules.issue.paramSplitWithColon';
+const PARAM_SPLIT_NO_COLON = 'rules.issue.paramSplitNoColon';
 function colonInsideParens(rule) {
     if (typeof rule !== 'string')
         return undefined;
@@ -51,7 +54,7 @@ function colonInsideParens(rule) {
     }
     return undefined;
 }
-export function permissionRuleIssueDetail(code, message, rule) {
+export function permissionRuleIssueDetail(code, message, rule, lang) {
     const colon = code === 'invalid.param_split' ? colonInsideParens(rule) : undefined;
     const known = colon !== undefined
         ? colon ? PARAM_SPLIT_WITH_COLON : PARAM_SPLIT_NO_COLON
@@ -61,7 +64,7 @@ export function permissionRuleIssueDetail(code, message, rule) {
         : '';
     const codeWord = typeof code === 'string' && code.length > 0 ? escapeDisplayControlChars(code) : '(no code)';
     const head = known !== undefined
-        ? known
-        : `this rule was refused with ${codeWord}, a code newer than this client`;
+        ? renderMessage(msg(known), lang)
+        : renderMessage(msg('rules.issue.newerCode', { code: codeWord }), lang);
     return text.length > 0 ? `${head} — ${text}` : head;
 }

package/dist/permissionRulesWriteCapability.d.ts

@@ -1,3 +1,4 @@
+import type { UiLanguage } from './env/uiLanguage.js';
 export type PermissionRulesWriteReading = {
     kind: 'unobserved';
 } | {
@@ -12,4 +13,4 @@ export type PermissionRulesWriteReading = {
 export declare function projectPermissionRulesWriteCapability(caps: unknown): PermissionRulesWriteReading | undefined;
 export declare function observedPermissionRulesWrite(baseUrl?: string | undefined): PermissionRulesWriteReading;
 export declare function permissionRulesWriteAvailable(reading: PermissionRulesWriteReading): boolean;
-export declare function permissionRulesWriteDoctorDetail(reading: PermissionRulesWriteReading): string;
+export declare function permissionRulesWriteDoctorDetail(reading: PermissionRulesWriteReading, lang?: UiLanguage): string;

package/dist/permissionRulesWriteCapability.js

@@ -1,5 +1,6 @@
 import { engineWireTarget } from './engineWireTarget.js';
 import { createEngineCapReader, unreadableReadingDetail } from './engineCapReader.js';
+import { msg, renderMessage } from './i18n/translate.js';
 import { ownDataField } from './ownKey.js';
 export function projectPermissionRulesWriteCapability(caps) {
     try {
@@ -28,17 +29,18 @@ export function observedPermissionRulesWrite(baseUrl = engineWireTarget()?.baseU
 export function permissionRulesWriteAvailable(reading) {
     return reading.kind === 'present';
 }
-export function permissionRulesWriteDoctorDetail(reading) {
+export function permissionRulesWriteDoctorDetail(reading, lang) {
+    const subject = msg('notice.capability.subject.permissionRulesWrite');
     switch (reading.kind) {
         case 'unreadable':
-            return unreadableReadingDetail('permission-rule write entry');
+            return unreadableReadingDetail(renderMessage(subject, lang), lang);
         case 'unobserved':
-            return 'permission-rule write entry not observed — the engine reports it on /v1/capabilities (permissionRulesWrite); this process has no usable capabilities reading cached for it (none received, the last one was unreadable, or the last one was discarded when the engine connection was reset; this process cannot tell which)';
+            return renderMessage(msg('notice.capability.unobserved', { subject, key: 'permissionRulesWrite' }), lang);
         case 'not_reported':
-            return 'permission-rule write entry not reported by this engine — this binary predates the entry itself; hide it rather than calling it';
+            return renderMessage(msg('notice.capability.permissionRulesWrite.notReported'), lang);
         case 'absent':
-            return 'permission-rule write entry unreachable for this call — either the rules lane is not open on this deployment, or this call cannot bring a verifiable identity; the engine reports one bit for both, so this client cannot tell which';
+            return renderMessage(msg('notice.capability.permissionRulesWrite.absent'), lang);
         case 'present':
-            return 'permission-rule write entry reachable for this call — a per-call attempt still answers for itself whether the direction, text, and scope are accepted';
+            return renderMessage(msg('notice.capability.permissionRulesWrite.present'), lang);
     }
 }

package/dist/pluginHooksWire.d.ts

@@ -1,10 +1,11 @@
 import type { WireHooksConfig } from './finalVerifyWire.js';
-import type { PluginHookSource } from './host.js';
+import type { PluginHookSource, SessionHookOrigin, SessionHookSource } from './host.js';
+import { type HooksSalvageDrop, type HooksSalvageMask, type HooksSalvageRejection } from './settingsHooksSalvage.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", "engine_hooks_off", "engine_hooks_unknown", "engine_type_skipped", "engine_llm_limit", "engine_unconfirmed", "engine_elsewhere"];
+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", "hooks_module", "scope_unsupported", "source_incomplete"];
 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", "prompt_not_user_authored"];
 export type PluginHookExclusionReason = (typeof PLUGIN_HOOK_EXCLUSION_REASONS)[number];
@@ -48,6 +49,28 @@ export interface SettingsHookExclusion {
     readonly hookIndex: number;
     readonly reason: PluginHookExclusionReason;
 }
+export interface SettingsHooksSalvageRow {
+    readonly source: HookSettingsSource;
+    readonly outcome: 'loaded-partial' | 'rejected';
+    readonly dropped: readonly HooksSalvageDrop[];
+    readonly rejections: readonly HooksSalvageRejection[];
+    readonly notice: string;
+}
+export interface PluginHookModuleVerdict {
+    readonly pluginId: string;
+    readonly pluginName: string;
+    readonly disposition: PluginHookDisposition;
+    readonly reason: PluginHookReason;
+}
+export interface SessionHookVerdict {
+    readonly origin: SessionHookOrigin;
+    readonly name: string;
+    readonly event: string;
+    readonly groupIndex: number;
+    readonly hookIndex: number;
+    readonly disposition: PluginHookDisposition;
+    readonly reason: PluginHookReason;
+}
 export interface HooksWireEngineFacts {
     readonly ownedByThisShell: boolean | null;
     readonly pluginHooksCapable: boolean | null;
@@ -62,6 +85,11 @@ export interface HooksWirePlan {
     readonly settingsDropped: readonly SettingsHookDrop[];
     readonly settingsVerdicts: readonly SettingsHookVerdict[];
     readonly settingsExcluded: readonly SettingsHookExclusion[];
+    readonly settingsSalvage: readonly SettingsHooksSalvageRow[];
+    readonly moduleVerdicts: readonly PluginHookModuleVerdict[];
+    readonly sessionVerdicts: readonly SessionHookVerdict[];
+    readonly sessionReader: PluginHookReaderState;
+    readonly closedBy: Extract<PluginHookExclusionReason, 'workspace_untrusted' | 'governance_unreadable' | 'policy_disable_all'> | null;
     readonly wire: WireHooksConfig | undefined;
 }
 export interface HooksWirePlanOptions {
@@ -70,7 +98,9 @@ export interface HooksWirePlanOptions {
     readonly shellHookEvents?: readonly string[];
     readonly shellHookTypesByEvent?: Readonly<Record<string, readonly string[]>>;
     readonly promptAuthoredByUser?: boolean;
+    readonly suppressedLocally?: readonly string[];
 }
+export declare function hooksWirePlanShapeOf(v: unknown): 'plan' | 'not' | 'threw';
 export declare const ENGINE_HOOK_LIMITS: {
     readonly maxGroupsPerEvent: 16;
     readonly maxEntriesPerEvent: 32;
@@ -102,15 +132,27 @@ export interface PluginHookDecisionInput {
     readonly shellRuns: ShellRunsHook;
     readonly promptAuthoredByUser: boolean;
     readonly occupied: ReadonlyMap<string, EventOccupancy>;
+    readonly suppressedLocally?: ReadonlySet<string>;
 }
 export interface PluginHookDecision {
     readonly verdicts: readonly PluginHookVerdict[];
+    readonly modules: readonly PluginHookModuleVerdict[];
     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, shellRunsType: (type: string | undefined) => boolean, judge: SettingsHookJudge): SettingsHookFilterResult;
+export interface SessionHookDecisionInput {
+    readonly sources: readonly SessionHookSource[];
+    readonly engine: HooksWireEngineFacts;
+    readonly shellRuns: ShellRunsHook;
+    readonly promptAuthoredByUser: boolean;
+}
+export declare function decideSessionHooks(input: SessionHookDecisionInput): {
+    readonly verdicts: readonly SessionHookVerdict[];
+    readonly unreadable: number;
+};
+export declare function filterSettingsHookGroups(source: HookSettingsSource, event: string, groups: readonly WireHookGroup[], execFormCapable: boolean, shellRunsType: (type: string | undefined) => boolean, judge: SettingsHookJudge, mask?: HooksSalvageMask): SettingsHookFilterResult;
 export interface SettingsHookFilterResult {
     readonly groups: WireHookGroup[];
     readonly drops: SettingsHookDrop[];
@@ -140,4 +182,5 @@ 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 declare function userPromptSubmitExecutorOf(plan: HooksWirePlan): 'shell' | 'engine' | 'unknown' | 'none';
 export {};

package/dist/pluginHooksWire.js

@@ -1,5 +1,6 @@
 import { displayUntrusted } from './displayUntrusted.js';
 import { SETTINGS_ENGINE_OWNED_HOOK_EVENTS } from './generated/settingsSchemaTables.js';
+import { HOOK_SETTINGS_SOURCE_TEXT, hooksSalvageMaskOf, salvageSettingsHooksEntries, } from './settingsHooksSalvage.js';
 export const ENGINE_FIRED_HOOK_EVENTS = SETTINGS_ENGINE_OWNED_HOOK_EVENTS;
 export const PLUGIN_HOOK_DISPOSITIONS = ['engine', 'shell', 'not_run'];
 export const PLUGIN_HOOK_REASONS = [
@@ -22,6 +23,9 @@ export const PLUGIN_HOOK_REASONS = [
     'engine_llm_limit',
     'engine_unconfirmed',
     'engine_elsewhere',
+    'hooks_module',
+    'scope_unsupported',
+    'source_incomplete',
 ];
 export const PLUGIN_HOOK_EXCLUSION_REASONS = [
     'workspace_untrusted',
@@ -32,6 +36,43 @@ export const PLUGIN_HOOK_EXCLUSION_REASONS = [
     'prompt_not_user_authored',
 ];
 export const SETTINGS_HOOK_DROP_REASONS = ['exec_form_unsupported', 'mcp_tool_unsupported'];
+export function hooksWirePlanShapeOf(v) {
+    try {
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            return 'not';
+        const o = v;
+        for (const k of PLAN_KEYS)
+            if (!Object.hasOwn(o, k) && !LATER_PLAN_KEYS.has(k))
+                return 'not';
+        const reader = o.pluginReader;
+        const engineFacts = o.engine;
+        const wire = o.wire;
+        const arrayOrAbsent = (k) => !Object.hasOwn(o, k) || Array.isArray(o[k]);
+        return Array.isArray(o.verdicts) &&
+            Array.isArray(o.excluded) &&
+            Array.isArray(o.settingsDropped) &&
+            Array.isArray(o.settingsVerdicts) &&
+            Array.isArray(o.settingsExcluded) &&
+            arrayOrAbsent('settingsSalvage') &&
+            arrayOrAbsent('moduleVerdicts') &&
+            arrayOrAbsent('sessionVerdicts') &&
+            (!Object.hasOwn(o, 'sessionReader') || o.sessionReader === 'present' || o.sessionReader === 'absent' || o.sessionReader === 'failed') &&
+            (!Object.hasOwn(o, 'closedBy') || o.closedBy === null || o.closedBy === 'workspace_untrusted' || o.closedBy === 'governance_unreadable' || o.closedBy === 'policy_disable_all') &&
+            (reader === 'present' || reader === 'absent' || reader === 'failed') &&
+            typeof engineFacts === 'object' &&
+            engineFacts !== null &&
+            (wire === undefined || (typeof wire === 'object' && wire !== null && !Array.isArray(wire)))
+            ? 'plan'
+            : 'not';
+    }
+    catch {
+        return 'threw';
+    }
+}
+const PLAN_KEYS = ['engine', 'pluginReader', 'verdicts', 'excluded', 'settingsDropped', 'settingsVerdicts', 'settingsExcluded', 'settingsSalvage', 'moduleVerdicts', 'sessionVerdicts', 'sessionReader', 'closedBy', 'wire'];
+const LATER_PLAN_KEYS = new Set(['settingsSalvage', 'moduleVerdicts', 'sessionVerdicts', 'sessionReader', 'closedBy']);
+const _planKeysPin = [true, true];
+void _planKeysPin;
 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']);
@@ -39,6 +80,8 @@ 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 === 'session')
+        return judged(x.shellRuns ? 'shell' : 'not_run', 'scope_unsupported');
     if (x.source === 'settings') {
         const why = x.powershell
             ? { reason: 'engine_type_skipped', certain: true }
@@ -172,15 +215,25 @@ export function occupancyOf(wire) {
 export function decidePluginHooks(input) {
     const verdicts = [];
     const excluded = [];
+    const modules = [];
     const candidates = new Map();
     let unreadable = 0;
     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)) {
+        if (!isRecord(p)) {
+            unreadable++;
+            return;
+        }
+        if (p.hooksModule === true && input.exclusion === undefined && !(input.managedOnly && p.managed !== true)) {
+            modules.push({ pluginId: typeof p.id === 'string' ? p.id : '', pluginName: typeof p.name === 'string' ? p.name : '', disposition: 'not_run', reason: 'hooks_module' });
+        }
+        if (!isRecord(p.hooks)) {
             unreadable++;
             return;
         }
         const src = p;
+        const sv = salvageSettingsHooksEntries({ hooks: p.hooks });
+        const pieceMask = hooksSalvageMaskOf(sv.outcome === 'loaded-partial' ? sv.dropped : []);
         const sourceOk = nonEmptyString(p.id) && nonEmptyString(p.name) && nonEmptyString(p.root) && nonEmptyString(p.dataDir);
         const pluginId = typeof p.id === 'string' ? p.id : '';
         const pluginName = typeof p.name === 'string' ? p.name : '';
@@ -207,7 +260,15 @@ export function decidePluginHooks(input) {
                         return;
                     }
                     const entryType = isRecord(entry) && typeof entry.type === 'string' ? entry.type : undefined;
-                    const shape = sourceOk ? classifyEntry(entry, src.options) : { kind: 'malformed' };
+                    if (!sourceOk) {
+                        verdicts.push({ ...key, disposition: 'not_run', reason: 'source_incomplete' });
+                        return;
+                    }
+                    if (!pieceMask.eventDropped(event) && pieceMask.entryDropped(event, groupIndex, hookIndex)) {
+                        verdicts.push({ ...key, disposition: 'not_run', reason: 'malformed_entry' });
+                        return;
+                    }
+                    const shape = classifyEntry(entry, src.options);
                     if (shape.kind === 'malformed') {
                         verdicts.push({ ...key, disposition: 'not_run', reason: 'malformed_entry' });
                         return;
@@ -299,7 +360,79 @@ export function decidePluginHooks(input) {
         }
         projected.set(event, groupsOut);
     }
-    return { verdicts, excluded, projected, unreadable };
+    const suppressed = input.suppressedLocally;
+    if (suppressed !== undefined && suppressed.size > 0) {
+        for (const v of verdicts) {
+            if (v.disposition !== 'shell' || !suppressed.has(v.pluginId))
+                continue;
+            v.disposition = 'not_run';
+            if (!ENGINE_EVENTS.has(v.event))
+                v.reason = 'no_executor';
+        }
+    }
+    return { verdicts, excluded, modules, projected, unreadable };
+}
+const SESSION_HOOK_ORIGINS = new Set(['skill', 'agent', 'sdk_host']);
+const LOCAL_REGISTRATION_TYPES = new Set(['callback', 'function']);
+const isLocalRegistration = (e) => isRecord(e) && typeof e.type === 'string' && LOCAL_REGISTRATION_TYPES.has(e.type);
+const JUDGE_STAND_IN = Object.freeze({ type: 'command', command: 'true' });
+function sessionHooksForJudge(hooks) {
+    const out = {};
+    for (const [event, groups] of Object.entries(hooks)) {
+        out[event] = Array.isArray(groups)
+            ? groups.map((g) => isRecord(g) && Array.isArray(g.hooks) && g.hooks.some(isLocalRegistration)
+                ? { ...g, hooks: g.hooks.map((e) => (isLocalRegistration(e) ? JUDGE_STAND_IN : e)) }
+                : g)
+            : groups;
+    }
+    return out;
+}
+export function decideSessionHooks(input) {
+    const out = [];
+    let unreadable = 0;
+    for (const src of input.sources) {
+        if (!isRecord(src) || typeof src.origin !== 'string' || !SESSION_HOOK_ORIGINS.has(src.origin) || !isRecord(src.hooks)) {
+            unreadable++;
+            continue;
+        }
+        const origin = src.origin;
+        const name = typeof src.name === 'string' ? src.name : '';
+        const sv = salvageSettingsHooksEntries({ hooks: sessionHooksForJudge(src.hooks) });
+        const rejectedWhole = sv.outcome === 'rejected';
+        const mask = hooksSalvageMaskOf(sv.outcome === 'loaded-partial' ? sv.dropped : []);
+        for (const [event, groups] of Object.entries(src.hooks)) {
+            if (!Array.isArray(groups)) {
+                unreadable++;
+                continue;
+            }
+            ;
+            groups.forEach((group, groupIndex) => {
+                if (!isRecord(group) || !Array.isArray(group.hooks)) {
+                    unreadable++;
+                    return;
+                }
+                ;
+                group.hooks.forEach((entry, hookIndex) => {
+                    const key = { origin, name, event, groupIndex, hookIndex };
+                    const type = isRecord(entry) && typeof entry.type === 'string' ? entry.type : undefined;
+                    if (rejectedWhole || (!mask.eventDropped(event) && mask.entryDropped(event, groupIndex, hookIndex)) || type === undefined) {
+                        out.push({ ...key, disposition: 'not_run', reason: 'malformed_entry' });
+                        return;
+                    }
+                    const shellRuns = input.shellRuns(event, type);
+                    if (!ENGINE_EVENTS.has(event)) {
+                        out.push({ ...key, ...(shellRuns ? { disposition: 'shell', reason: 'shell_event' } : { disposition: 'not_run', reason: 'no_executor' }) });
+                        return;
+                    }
+                    const ex = hookExecutorOf({ source: 'session', event, powershell: false, llmPosition: 0, engine: input.engine, shellRuns, promptAuthoredByUser: input.promptAuthoredByUser });
+                    if (ex.kind === 'excluded')
+                        return;
+                    out.push({ ...key, disposition: ex.disposition, reason: ex.reason });
+                });
+            });
+        }
+    }
+    return { verdicts: out, unreadable };
 }
 const SHELL_INERT_COMMAND = /^[A-Za-z0-9_./:+-]+$/;
 function carriesArgs(entry) {
@@ -312,7 +445,7 @@ function carriesArgs(entry) {
     }
     return true;
 }
-export function filterSettingsHookGroups(source, event, groups, execFormCapable, shellRunsType, judge) {
+export function filterSettingsHookGroups(source, event, groups, execFormCapable, shellRunsType, judge, mask) {
     const drops = [];
     const verdicts = [];
     const excluded = [];
@@ -320,6 +453,8 @@ export function filterSettingsHookGroups(source, event, groups, execFormCapable,
     let stripped = 0;
     const engineEvent = ENGINE_EVENTS.has(event);
     groups.forEach((group, groupIndex) => {
+        if (mask !== undefined && mask.groupDropped(event, groupIndex))
+            return;
         if (!isRecord(group) || !Array.isArray(group.hooks)) {
             out.push(group);
             return;
@@ -327,6 +462,10 @@ export function filterSettingsHookGroups(source, event, groups, execFormCapable,
         const kept = [];
         let changed = false;
         group.hooks.forEach((entry, hookIndex) => {
+            if (mask !== undefined && mask.entryDropped(event, groupIndex, hookIndex)) {
+                changed = true;
+                return;
+            }
             const reason = !isRecord(entry)
                 ? undefined
                 : entry.type === 'mcp_tool'
@@ -555,7 +694,7 @@ export function settingsHooksKeptLocally(plan, event, group, opts) {
         const planRec = plan;
         if (!isRecord(planRec))
             return hooks;
-        const excludedList = Object.hasOwn(planRec, 'settingsExcluded') ? planRec.settingsExcluded : [];
+        const excludedList = Object.hasOwn(planRec, 'settingsExcluded') ? planRec.settingsExcluded : undefined;
         const wire = ownField(planRec, 'wire');
         if (!Array.isArray(excludedList) || (wire !== undefined && !isRecord(wire)))
             return hooks;
@@ -665,18 +804,15 @@ const REASON_TEXT = {
     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',
+    hooks_module: 'hooks registered in code by a plugin module run neither in the engine nor in this client',
+    scope_unsupported: 'hooks registered for a skill, an agent or by the host application are not sent to the engine, and this client does not run this event',
+    source_incomplete: 'the plugin was reported without its id, name, root folder or data folder',
 };
 const DROP_TEXT = {
     exec_form_unsupported: 'exec-form hooks (with "args") are sent to the engine only once it reports support for them',
     mcp_tool_unsupported: 'MCP tool hooks are not supported by the engine',
 };
-const SOURCE_TEXT = {
-    policySettings: 'Managed settings',
-    userSettings: 'User settings',
-    projectSettings: 'Project settings',
-    localSettings: 'Local settings',
-    flagSettings: 'Flag settings',
-};
+const SOURCE_TEXT = HOOK_SETTINGS_SOURCE_TEXT;
 export function pluginHookReasonText(reason) {
     return REASON_TEXT[reason];
 }
@@ -786,5 +922,77 @@ 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 — ${pluginHookReasonText(row.reason)}.`);
     }
+    const moduleRows = plan.moduleVerdicts;
+    for (const raw of Array.isArray(moduleRows) ? moduleRows : []) {
+        if (!isRecord(raw) || ownField(raw, 'disposition') !== 'not_run')
+            continue;
+        const reason = ownField(raw, 'reason');
+        const name = ownField(raw, 'pluginName');
+        if (typeof reason !== 'string' || !REASON_SET.has(reason))
+            continue;
+        lines.push(`Plugin "${noticeLabel(typeof name === 'string' ? name : '') || '(unnamed)'}": hooks module will not run — ${pluginHookReasonText(reason)}.`);
+    }
+    const sessionRows = plan.sessionVerdicts;
+    const bySession = new Map();
+    for (const raw of Array.isArray(sessionRows) ? sessionRows : []) {
+        if (!isRecord(raw) || ownField(raw, 'disposition') !== 'not_run')
+            continue;
+        const origin = ownField(raw, 'origin');
+        const name = ownField(raw, 'name');
+        const reason = ownField(raw, 'reason');
+        const event = ownField(raw, 'event');
+        if (typeof origin !== 'string' || !SESSION_HOOK_ORIGINS.has(origin) || typeof reason !== 'string' || !REASON_SET.has(reason) || typeof event !== 'string')
+            continue;
+        const nm = typeof name === 'string' ? name : '';
+        const k = `${origin}\u0000${nm}\u0000${reason}`;
+        const row = bySession.get(k) ?? { origin: origin, name: nm, reason: reason, events: [], count: 0 };
+        if (!row.events.includes(event))
+            row.events.push(event);
+        row.count++;
+        bySession.set(k, row);
+    }
+    for (const row of bySession.values()) {
+        const events = row.events.map((e) => noticeLabel(e)).join(', ');
+        const who = row.origin === 'sdk_host' ? 'Host application hooks' : `${row.origin === 'skill' ? 'Skill' : 'Agent'} "${noticeLabel(row.name) || '(unnamed)'}"`;
+        lines.push(`${who}: ${events} ${row.count === 1 ? 'hook' : 'hooks'} will not run — ${pluginHookReasonText(row.reason)}.`);
+    }
+    const salvageRows = plan.settingsSalvage;
+    for (const row of Array.isArray(salvageRows) ? salvageRows : []) {
+        const notice = isRecord(row) ? ownField(row, 'notice') : undefined;
+        if (typeof notice === 'string' && notice.length > 0)
+            lines.push(notice);
+    }
     return lines;
 }
+export function userPromptSubmitExecutorOf(plan) {
+    try {
+        const p = plan;
+        if (!isRecord(p))
+            return 'unknown';
+        const verdicts = ownField(p, 'verdicts');
+        if (!Array.isArray(verdicts))
+            return 'unknown';
+        const rows = [...verdicts];
+        const settingsRows = ownField(p, 'settingsVerdicts');
+        if (!Array.isArray(settingsRows))
+            return 'unknown';
+        rows.push(...settingsRows);
+        const sessionRows = ownField(p, 'sessionVerdicts');
+        if (sessionRows !== undefined) {
+            if (!Array.isArray(sessionRows))
+                return 'unknown';
+            rows.push(...sessionRows);
+        }
+        const ups = rows.filter((r) => isRecord(r) && ownField(r, 'event') === 'UserPromptSubmit').map((r) => ownField(r, 'disposition'));
+        if (ups.length === 0)
+            return 'none';
+        if (ups.some((d) => d === 'engine'))
+            return 'engine';
+        if (ups.every((d) => d === 'shell'))
+            return 'shell';
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/prepareRefusal.d.ts

@@ -0,0 +1,8 @@
+import { CONFIG_AGENT_UNKNOWN_TOOL, CONFIG_IMAGE_INVALID, CONFIG_LEGACY_TOOL_NAME, CONFIG_TOOL_FACE_CONTROL, PROMPT_ASSEMBLED_ROLE_REFUSED, USER_ATTACHMENT_INVALID_ERROR_CODE, USER_INVOKED_SKILL_UNKNOWN_ERROR_CODE } from './engineErrorCodes.js';
+export type PrepareRefusalCode = typeof CONFIG_LEGACY_TOOL_NAME | typeof CONFIG_IMAGE_INVALID | typeof CONFIG_AGENT_UNKNOWN_TOOL | typeof PROMPT_ASSEMBLED_ROLE_REFUSED | typeof USER_ATTACHMENT_INVALID_ERROR_CODE | typeof USER_INVOKED_SKILL_UNKNOWN_ERROR_CODE | typeof CONFIG_TOOL_FACE_CONTROL;
+export interface PrepareRefusalNoteFacts {
+    readonly index?: number;
+}
+export declare function prepareRefusalNoteOf(code: string | undefined, facts?: PrepareRefusalNoteFacts): string | undefined;
+export declare function prepareRefusalCodeOf(failure: {} | null | undefined): PrepareRefusalCode | undefined;
+export declare function imageInvalidFailureNoteOf(code: string | undefined): string | undefined;

package/dist/prepareRefusal.js

@@ -0,0 +1,72 @@
+import { CONFIG_AGENT_UNKNOWN_TOOL, CONFIG_IMAGE_INVALID, CONFIG_LEGACY_TOOL_NAME, CONFIG_TOOL_FACE_CONTROL, PROMPT_ASSEMBLED_ROLE_REFUSED, USER_ATTACHMENT_INVALID_ERROR_CODE, USER_INVOKED_SKILL_UNKNOWN_ERROR_CODE, } from './engineErrorCodes.js';
+import { REFUSED_NAME_CLASSES } from './hitl/refusedToolNameProse.js';
+import { readOwnDataValue } from './ownKey.js';
+import { effectiveWireErrorCode } from './wireErrorTriage.js';
+const nonNegInt = (v) => (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : undefined);
+const PREPARE_REFUSAL_NOTES = Object.freeze({
+    [CONFIG_LEGACY_TOOL_NAME]: () => `The engine refused this run at setup: a tool rule applied to it names a tool the engine refuses — ${REFUSED_NAME_CLASSES} (the engine's own error text names the entry). ` +
+        'Every later run fails the same way until that entry is removed from wherever it is set: this session’s rule record, the settings sent with the run, a parent session’s rule record, or the deployment’s own tool rules.',
+    [CONFIG_IMAGE_INVALID]: () => 'The engine refused this run at setup: an image sent with the message was not accepted — the engine’s own error text says which image and what is wrong with it. ' +
+        'Remove or replace that image, then send the message again.',
+    [CONFIG_AGENT_UNKNOWN_TOOL]: () => 'The engine refused this run at setup: a subagent tool list (in a subagent definition sent with it, or on a delegation tool) is not a list of tool names, or has an entry that names no tool or uses a form that list does not accept — ' +
+        'the engine’s own error text says which list, and which entry when it is one entry · Sending the same request again is refused the same way; fix what it names, then send it',
+    [PROMPT_ASSEMBLED_ROLE_REFUSED]: () => 'The engine refused this run at setup: the role text sent with it contains the engine’s own prompt sections word for word — the engine’s own error text names the field · ' +
+        'Send only your own role text (the engine assembles the rest), then send it again',
+    [USER_ATTACHMENT_INVALID_ERROR_CODE]: (facts) => {
+        const index = nonNegInt(facts.index);
+        return index !== undefined
+            ? `The engine refused attachment ${index + 1} of this message: it is in a form the engine does not accept, or larger than it takes · Your draft is kept · Remove or replace that attachment, then send it again`
+            : 'The engine refused the files attached to this message: together with the message they are more than it can take in one request on this model, or one of them is in a form it does not accept · ' +
+                'Your draft is kept · Remove some attachments or attach smaller parts, then send it again';
+    },
+    [USER_INVOKED_SKILL_UNKNOWN_ERROR_CODE]: () => 'The engine refused this run at setup: a skill named for it is not one this run has loaded, or skills are turned off for this run · ' +
+        'Your draft is kept · Check the skill name, or load that skill, then send it again',
+    [CONFIG_TOOL_FACE_CONTROL]: () => 'The engine refused this run at setup: its tool set could not be put together as asked — usually a tool list on the request or one it inherits (allowed or excluded tools) names something no tool answers to, ' +
+        'uses a form those lists do not accept, or excludes a tool this run depends on; it can also be the deployment’s own tool mounts — the engine’s own error text says what it refused and where · ' +
+        'Sending the same request again is refused the same way; fix what it names (or ask whoever operates the engine, if it names the deployment’s tools), then send it',
+});
+function isPrepareRefusalCode(code) {
+    return typeof code === 'string' && Object.hasOwn(PREPARE_REFUSAL_NOTES, code);
+}
+export function prepareRefusalNoteOf(code, facts) {
+    try {
+        if (!isPrepareRefusalCode(code))
+            return undefined;
+        let index;
+        try {
+            index = facts === undefined || facts === null ? undefined : facts.index;
+        }
+        catch {
+            index = undefined;
+        }
+        const i = nonNegInt(index);
+        return PREPARE_REFUSAL_NOTES[code](i !== undefined ? { index: i } : {});
+    }
+    catch {
+        return undefined;
+    }
+}
+export function prepareRefusalCodeOf(failure) {
+    try {
+        if (typeof failure !== 'object' || failure === null)
+            return undefined;
+        const kind = readOwnDataValue(failure, 'kind');
+        const plane = readOwnDataValue(failure, 'plane');
+        if (kind === 'failed' && (plane === 'cause' || plane === 'flat')) {
+            const code = readOwnDataValue(failure, 'code');
+            return isPrepareRefusalCode(code) ? code : undefined;
+        }
+        if (readOwnDataValue(failure, 'type') === 'result') {
+            const code = readOwnDataValue(failure, '_sema_error_code');
+            return isPrepareRefusalCode(code) ? code : undefined;
+        }
+        const code = effectiveWireErrorCode(failure);
+        return isPrepareRefusalCode(code) ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function imageInvalidFailureNoteOf(code) {
+    return code === CONFIG_IMAGE_INVALID ? prepareRefusalNoteOf(code) : undefined;
+}