@sema-agent/client-core 0.89.0 → 0.90.0

package/dist/adapter/runStream.js

@@ -140,11 +140,6 @@ function engineSessionIdOf(result) {
     const v = result?.sessionId;
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
-function providerFailureStatusOf(result) {
-    const af = result?.apiFailure;
-    const status = typeof af === 'object' && af !== null ? af.status : undefined;
-    return typeof status === 'number' && Number.isFinite(status) ? status : undefined;
-}
 export function isOutcomeUnknownRowText(text) {
     return text.trimStart().startsWith(`${OUTCOME_UNKNOWN_ROW_PREFIX}:`);
 }
@@ -155,6 +150,157 @@ export function isGovernanceTerminal(input) {
         return true;
     return input.errorCode === OUTPUT_INVALID;
 }
+function terminalRowFacts(ev) {
+    const doneTerminal = ev.type === 'done' ? readRunTerminal(ev.result) : null;
+    const errTextRaw = ev.type === 'failed'
+        ? (ev.errorMessage ?? ev.errorCode ?? 'run failed')
+        : doneTerminal?.kind === 'failed'
+            ? (doneTerminal.message ?? doneTerminal.code ?? 'run failed')
+            : doneTerminal?.kind === 'blocked'
+                ? (doneTerminal.reason
+                    ? `Run blocked: ${doneTerminal.reason}`
+                    : 'Run blocked (the agent reported it cannot proceed)')
+                : null;
+    const errText = errTextRaw === '' ? null : errTextRaw;
+    if (errText === null)
+        return { doneTerminal, errText, activeTaskId: undefined, busy: { busy: false, handle: null }, governance: false };
+    const activeTaskId = (ev.type === 'done' ? ev.result?.activeTaskId : undefined) ??
+        (ev.type === 'failed' ? ev.activeTaskId : undefined);
+    const busy = classifyActiveRunBusy({
+        errorCode: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
+        activeTaskId,
+    });
+    const governance = isGovernanceTerminal({
+        status: ev.type === 'failed' ? undefined : doneTerminal?.kind === 'blocked' ? 'blocked' : undefined,
+        errorCode: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
+    });
+    return { doneTerminal, errText, activeTaskId, busy, governance };
+}
+const PROVIDER_REJECTED_DETAIL = 'provider_rejected';
+function ownDataBit(o, k) {
+    try {
+        const d = Object.getOwnPropertyDescriptor(o, k);
+        return d !== undefined && Object.prototype.hasOwnProperty.call(d, 'value') ? d.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function plainObjectOf(v) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    try {
+        return Array.isArray(v) ? undefined : v;
+    }
+    catch {
+        return undefined;
+    }
+}
+function ownDataCopy(o, keys) {
+    const out = Object.create(null);
+    for (const k of keys) {
+        const v = ownDataBit(o, k);
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+function ownTerminalSnapshot(result) {
+    let causePlane;
+    try {
+        causePlane = 'terminal' in result;
+    }
+    catch {
+        return undefined;
+    }
+    const snap = ownDataCopy(result, ['status', 'errorCode', 'errorMessage']);
+    if (!causePlane)
+        return snap;
+    let d;
+    try {
+        d = Object.getOwnPropertyDescriptor(result, 'terminal');
+    }
+    catch {
+        return undefined;
+    }
+    if (d === undefined || !Object.prototype.hasOwnProperty.call(d, 'value'))
+        return undefined;
+    const t = plainObjectOf(d.value);
+    if (t === undefined) {
+        snap.terminal = null;
+        return snap;
+    }
+    const ts = ownDataCopy(t, ['kind', 'code', 'message']);
+    const detail = plainObjectOf(ownDataBit(t, 'detail'));
+    if (detail !== undefined)
+        ts.detail = ownDataCopy(detail, ['kind', 'status', 'code']);
+    snap.terminal = ts;
+    return snap;
+}
+function nonEmptyStr(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function mintToolHistoryCarrier(code, status, message) {
+    const out = Object.create(null);
+    if (code !== undefined)
+        out.code = code;
+    if (status !== undefined)
+        out.status = status;
+    if (message !== undefined)
+        out.message = message;
+    return Object.freeze(out);
+}
+export function toolHistoryErrorCarrierOf(terminalOrResult) {
+    const empty = () => mintToolHistoryCarrier(undefined, undefined, undefined);
+    try {
+        const x = plainObjectOf(terminalOrResult);
+        if (x === undefined)
+            return empty();
+        const type = ownDataBit(x, 'type');
+        const frame = (type === 'done' || type === 'failed' ? x : { type: 'done', result: x });
+        return toolHistoryCarrierFromFacts(x, terminalRowFacts(frame));
+    }
+    catch {
+        return empty();
+    }
+}
+function toolHistoryCarrierFromFacts(x, facts) {
+    const empty = () => mintToolHistoryCarrier(undefined, undefined, undefined);
+    try {
+        const type = ownDataBit(x, 'type');
+        if (facts.errText === null || facts.busy.busy || facts.governance || isModelOutputErrorText(facts.errText))
+            return empty();
+        if (type === 'failed')
+            return mintToolHistoryCarrier(nonEmptyStr(ownDataBit(x, 'errorCode')), undefined, nonEmptyStr(ownDataBit(x, 'errorMessage')));
+        const result = type === 'done' ? plainObjectOf(ownDataBit(x, 'result')) : x;
+        if (result === undefined)
+            return empty();
+        const snap = ownTerminalSnapshot(result);
+        if (snap === undefined)
+            return empty();
+        const read = readRunTerminal(snap);
+        if (read === null || read.kind !== 'failed')
+            return empty();
+        const detail = plainObjectOf(ownDataBit(read, 'detail'));
+        const detailStatus = detail !== undefined && ownDataBit(detail, 'kind') === PROVIDER_REJECTED_DETAIL ? ownDataBit(detail, 'status') : undefined;
+        const apiFailure = plainObjectOf(ownDataBit(result, 'apiFailure'));
+        const apiStatus = apiFailure === undefined ? undefined : ownDataBit(apiFailure, 'status');
+        const status = typeof apiStatus === 'number' && Number.isFinite(apiStatus) ? apiStatus : typeof detailStatus === 'number' ? detailStatus : undefined;
+        return mintToolHistoryCarrier(nonEmptyStr(ownDataBit(read, 'code')), status, nonEmptyStr(ownDataBit(read, 'message')));
+    }
+    catch {
+        return empty();
+    }
+}
+function toolHistoryCarrierOfRowFrame(ev, facts) {
+    try {
+        const x = plainObjectOf(ev);
+        return x === undefined ? mintToolHistoryCarrier(undefined, undefined, undefined) : toolHistoryCarrierFromFacts(x, facts);
+    }
+    catch {
+        return mintToolHistoryCarrier(undefined, undefined, undefined);
+    }
+}
 const reportedDroppedTypes = new Set();
 const DROPPED_TYPE_MEMO_CAP = 64;
 const DROPPED_TYPE_DISPLAY_CAP = 60;
@@ -477,30 +623,15 @@ async function* runStreamInner(events, ctx, handle = {}) {
             continue;
         }
         if (ev.type === 'done' || ev.type === 'failed') {
-            const doneTerminal = ev.type === 'done' ? readRunTerminal(ev.result) : null;
-            const errText = ev.type === 'failed'
-                ? (ev.errorMessage ?? ev.errorCode ?? 'run failed')
-                : doneTerminal?.kind === 'failed'
-                    ? (doneTerminal.message ?? doneTerminal.code ?? 'run failed')
-                    : doneTerminal?.kind === 'blocked'
-                        ? (doneTerminal.reason
-                            ? `Run blocked: ${doneTerminal.reason}`
-                            : 'Run blocked (the agent reported it cannot proceed)')
-                        : null;
+            const rowFacts = terminalRowFacts(ev);
+            const doneTerminal = rowFacts.doneTerminal;
+            const errText = rowFacts.errText;
             if (errText) {
-                const activeTaskId = (ev.type === 'done' ? ev.result?.activeTaskId : undefined) ??
-                    (ev.type === 'failed' ? ev.activeTaskId : undefined);
-                const busy = classifyActiveRunBusy({
-                    errorCode: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
-                    activeTaskId,
-                });
+                const busy = rowFacts.busy;
                 const maxTokHint = /max_tokens/i.test(errText)
                     ? '\nyour provider caps max_tokens lower — lower it in /model (press m, or M to type a value)'
                     : '';
-                const governance = isGovernanceTerminal({
-                    status: ev.type === 'failed' ? undefined : doneTerminal?.kind === 'blocked' ? 'blocked' : undefined,
-                    errorCode: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
-                });
+                const governance = rowFacts.governance;
                 const busyHandle = busy.handle;
                 const rowText = busy.busy
                     ? `This session is locked by an earlier run${busyHandle ? ` (run ${busyHandle})` : ''} that ` +
@@ -516,13 +647,7 @@ async function* runStreamInner(events, ctx, handle = {}) {
                 const sessionUnreadable = ev.type === 'failed'
                     ? isCorruptSessionCode(ev.errorCode)
                     : doneTerminal?.kind === 'failed' && isCorruptSessionCode(doneTerminal.code);
-                const historyMismatch = !busy.busy && !governance && !isModelOutputErrorText(errText)
-                    ? classifyToolHistoryMismatch({
-                        code: ev.type === 'failed' ? ev.errorCode : runTerminalCode(doneTerminal),
-                        status: ev.type === 'done' ? providerFailureStatusOf(ev.result) : undefined,
-                        message: errText,
-                    })
-                    : null;
+                const historyMismatch = classifyToolHistoryMismatch(toolHistoryCarrierOfRowFrame(ev, rowFacts));
                 const historyEchoedSid = ev.type === 'done' ? engineSessionIdOf(ev.result) : undefined;
                 const historyRepeat = noteToolHistoryTerminal({
                     sessionId: historyEchoedSid ?? ctx.sessionId,

package/dist/attachmentsWireCaps.d.ts

@@ -6,7 +6,6 @@ export interface AttachmentsSpec {
     changedFiles?: true | {
         maxFiles?: number;
     };
-    planModeReminder?: true;
     budgetUsd?: true;
     backgroundTasks?: boolean;
     toolsDelta?: true;
@@ -14,6 +13,18 @@ export interface AttachmentsSpec {
     agentListing?: boolean;
     skillsListing?: boolean;
 }
-export declare const ATTACHMENTS_SPEC_KEYS: readonly ["todoReminder", "todoReminderMode", "changedFiles", "planModeReminder", "budgetUsd", "backgroundTasks", "toolsDelta", "mcpInstructions", "agentListing", "skillsListing"];
+export declare const ATTACHMENTS_SPEC_KEYS: readonly ["todoReminder", "todoReminderMode", "changedFiles", "budgetUsd", "backgroundTasks", "toolsDelta", "mcpInstructions", "agentListing", "skillsListing"];
 export declare const ATTACHMENTS_DEFAULT_ON_KEYS: readonly ["agentListing", "skillsListing", "backgroundTasks"];
+export declare class AttachmentsSpecRefused extends TypeError {
+    readonly token: string;
+    readonly why: string;
+    readonly allowed: readonly string[];
+    readonly key?: string;
+    constructor(message: string, init: {
+        readonly token: string;
+        readonly why: string;
+        readonly allowed: readonly string[];
+        readonly key?: string;
+    });
+}
 export declare function attachmentsForRequest(env?: EnvLike): AttachmentsSpec | undefined;

package/dist/attachmentsWireCaps.js

@@ -1,11 +1,11 @@
 import { hostEnv } from './hostEnv.js';
 import { envFlagOff } from './envFlag.js';
+import { retiredAttachmentsKeyWhy } from './taskRequestWords.js';
 export const ATTACHMENTS_ENV = 'SEMA_ATTACHMENTS';
 export const ATTACHMENTS_SPEC_KEYS = Object.freeze([
     'todoReminder',
     'todoReminderMode',
     'changedFiles',
-    'planModeReminder',
     'budgetUsd',
     'backgroundTasks',
     'toolsDelta',
@@ -17,7 +17,6 @@ export const ATTACHMENTS_DEFAULT_ON_KEYS = ['agentListing', 'skillsListing', 'ba
 const OPT_IN_KEYS = [
     'todoReminder',
     'changedFiles',
-    'planModeReminder',
     'budgetUsd',
     'backgroundTasks',
     'toolsDelta',
@@ -28,16 +27,37 @@ const DEFAULT_PAIR = ['backgroundTasks', 'toolsDelta'];
 const _attachmentsKeyPins = [true, true, true, true, true, true];
 void _attachmentsKeyPins;
 const TODO_REMINDER_MODES = ['baseline', 'off'];
+export class AttachmentsSpecRefused extends TypeError {
+    token;
+    why;
+    allowed;
+    constructor(message, init) {
+        super(message);
+        this.name = 'AttachmentsSpecRefused';
+        this.token = init.token;
+        this.why = init.why;
+        this.allowed = Object.freeze([...init.allowed]);
+        if (init.key !== undefined)
+            this.key = init.key;
+    }
+}
+function legalAttachmentsTokens() {
+    return ['off', 'full', 'all', 'default', '<literalTrueKey>', '+<literalTrueKey>', ...DEFAULT_ON_ONLY_KEYS.map(k => `-${k}`), `todoReminderMode=${TODO_REMINDER_MODES.join('|')}`];
+}
 function refuse(token, why) {
-    throw new Error(`${ATTACHMENTS_ENV}: refusing token "${token}" — ${why}. ` +
-        `Legal tokens: off | full | all | default | <literalTrueKey> | +<literalTrueKey> | ` +
-        `-agentListing | -skillsListing | todoReminderMode=baseline|off`);
+    const allowed = legalAttachmentsTokens();
+    throw new AttachmentsSpecRefused(`${ATTACHMENTS_ENV}: refusing token "${token}" — ${why}. Legal tokens: ${allowed.join(' | ')}`, { token, why, allowed });
 }
 export function attachmentsForRequest(env = hostEnv()) {
     const raw = (env[ATTACHMENTS_ENV] ?? '').trim().toLowerCase();
     if (envFlagOff(raw))
         return allDefaultOnOff();
     const tokens = raw.split(',').map(t => t.trim()).filter(t => t.length > 0);
+    for (const token of tokens) {
+        const named = retiredAttachmentsKeyWhy(token);
+        if (named !== undefined)
+            refuse(token, named);
+    }
     if (tokens.length === 0)
         return { backgroundTasks: true, toolsDelta: true };
     if (tokens.length === 1 && (tokens[0] === 'full' || tokens[0] === 'all'))

package/dist/coreValuePorts.d.ts

@@ -16,6 +16,7 @@ export interface AllowDenyPolicyOptionsView {
     deny?: string[];
     onInvalidName?: 'throw' | 'skip';
     onInvalidNameIssue?: (issue: AllowDenyInvalidNameIssueView) => void;
+    scope?: 'grant' | 'narrowing';
 }
 export interface AllowDenyInvalidNameIssueView {
     entry: string;

package/dist/engineCapReader.js

@@ -1,4 +1,15 @@
 import { snapshotCapsGeneration, capsGenerationStillCurrent } from './engineCapsGenerationGuard.js';
+function freezeReading(reading, seen = new Set()) {
+    if (reading === null || typeof reading !== 'object' || seen.has(reading))
+        return reading;
+    seen.add(reading);
+    Object.freeze(reading);
+    for (const d of Object.values(Object.getOwnPropertyDescriptors(reading))) {
+        if ('value' in d)
+            freezeReading(d.value, seen);
+    }
+    return reading;
+}
 export function createEngineCapReader(spec) {
     const readingByBase = new Map();
     return {
@@ -23,7 +34,7 @@ export function createEngineCapReader(spec) {
                 readingByBase.delete(baseUrl);
                 return;
             }
-            readingByBase.set(baseUrl, reading);
+            readingByBase.set(baseUrl, freezeReading(reading));
         },
         observed(baseUrl) {
             if (typeof baseUrl !== 'string' || baseUrl === '')

package/dist/engineNoticeCodes.d.ts

@@ -130,13 +130,6 @@ export interface ReadDenyUnappliedFactsView {
     runId: string;
 }
 export declare function readReadDenyUnapplied(notice: unknown): ReadDenyUnappliedFactsView | undefined;
-export interface LegacyModeSeedMigratedFactsView {
-    permissionMode?: string;
-    droppedKeys: readonly string[];
-    sessionId: string;
-    runId: string;
-}
-export declare function readLegacyModeSeedMigrated(notice: unknown): LegacyModeSeedMigratedFactsView | undefined;
 export interface ToolTurnRepairView {
     form: string;
     toolCallIds: readonly string[];
@@ -172,9 +165,10 @@ export interface UserInputUndrainedFactsView {
     taskId?: string;
     sessionId?: string;
     runId?: string;
+    childSessionId?: string;
 }
 export declare function readUserInputUndrained(notice: unknown): UserInputUndrainedFactsView | undefined;
-export declare function userInputUndrainedNotice(facts: Pick<UserInputUndrainedFactsView, 'kind' | 'count' | 'cause'>): string | undefined;
+export declare function userInputUndrainedNotice(facts: Pick<UserInputUndrainedFactsView, 'kind' | 'count' | 'cause' | 'childSessionId'>): string | undefined;
 export declare const ENGINE_NOTICE_FACT_READERS: Readonly<{
     readonly 'mcp.injection_dropped': typeof readMcpInjectionDrop;
     readonly 'delegation.ask_unresolvable': typeof readAskUnresolvable;
@@ -190,7 +184,6 @@ export declare const ENGINE_NOTICE_FACT_READERS: Readonly<{
     readonly 'config.permission_mode_unavailable': typeof readPermissionModeUnavailable;
     readonly 'permission.ask_released_by_mode': typeof readAskReleasedByMode;
     readonly 'permission.read_deny_unapplied': typeof readReadDenyUnapplied;
-    readonly 'resume.legacy_mode_seed_migrated': typeof readLegacyModeSeedMigrated;
     readonly 'context.tool_turn_repaired': typeof readToolTurnRepaired;
     readonly 'server.model_unreachable': typeof readModelUnreachable;
     readonly 'task.tool_turn_incomplete': typeof readToolTurnIncomplete;

package/dist/engineNoticeCodes.js

@@ -454,31 +454,6 @@ function readReadDenyUnappliedOf(notice) {
     }
     return { mode, toolCallId, tiers, rows, rowCount, sessionId, runId };
 }
-export function readLegacyModeSeedMigrated(notice) {
-    return guardedRead(notice, readLegacyModeSeedMigratedOf);
-}
-function readLegacyModeSeedMigratedOf(notice) {
-    if (typeof notice !== 'object' || notice === null || Array.isArray(notice))
-        return undefined;
-    const n = notice;
-    if (ownSeat(n, 'code') !== 'resume.legacy_mode_seed_migrated')
-        return undefined;
-    const d = ownSeat(n, 'detail');
-    if (typeof d !== 'object' || d === null || Array.isArray(d))
-        return undefined;
-    const o = d;
-    const m = o.migrated;
-    if (typeof m !== 'object' || m === null || Array.isArray(m))
-        return undefined;
-    const mo = m;
-    const droppedKeys = nameList(mo.droppedKeys);
-    const sessionId = nonEmpty(o.sessionId);
-    const runId = nonEmpty(o.runId);
-    if (droppedKeys === undefined || sessionId === undefined || runId === undefined)
-        return undefined;
-    const permissionMode = nonEmpty(optionalSeat(mo, 'permissionMode'));
-    return { ...(permissionMode !== undefined ? { permissionMode } : {}), droppedKeys, sessionId, runId };
-}
 export function readToolTurnRepaired(notice) {
     return guardedRead(notice, readToolTurnRepairedOf);
 }
@@ -601,6 +576,7 @@ function readUserInputUndrainedOf(notice) {
     const taskId = nonEmpty(optionalOwnSeat(o, 'taskId'));
     const sessionId = nonEmpty(optionalOwnSeat(o, 'sessionId'));
     const runId = nonEmpty(optionalOwnSeat(o, 'runId'));
+    const childSessionId = nonEmpty(optionalOwnSeat(o, 'childSessionId'));
     return {
         kind,
         count,
@@ -608,6 +584,7 @@ function readUserInputUndrainedOf(notice) {
         ...(taskId !== undefined ? { taskId } : {}),
         ...(sessionId !== undefined ? { sessionId } : {}),
         ...(runId !== undefined ? { runId } : {}),
+        ...(childSessionId !== undefined ? { childSessionId } : {}),
     };
 }
 const messagesPhrase = (n, noun) => `${n} ${noun}${n === 1 ? '' : 's'}`;
@@ -623,12 +600,17 @@ const _steerSentencePin = true;
 void _steerSentencePin;
 const followUpUndrainedSentence = (n) => `${messagesPhrase(n, 'follow-up message')} you queued ${verbBe(n)} not used before the run ended and will not be delivered. ` +
     `Send ${itThem(n)} again if you still need ${itThem(n)}.`;
+const subagentSteerUndrainedSentence = (n) => `${messagesPhrase(n, 'message')} you sent while the run was in progress ${verbBe(n)} not used before a sub-agent's run ended and will not be delivered. ` +
+    `Send ${itThem(n)} again if you still need ${itThem(n)}.`;
+const subagentFollowUpUndrainedSentence = (n) => `${messagesPhrase(n, 'follow-up message')} you queued ${verbBe(n)} not used before a sub-agent's run ended and will not be delivered. ` +
+    `Send ${itThem(n)} again if you still need ${itThem(n)}.`;
 const unrecognizedUndrainedSentence = (n, kind) => `${kind === 'followUp' ? `${messagesPhrase(n, 'follow-up message')} you queued` : `${messagesPhrase(n, 'message')} you sent during a run`} may not have been used, ` +
     `and the reason was not reported in a form this version recognizes. Check the run's transcript before sending ${itThem(n)} again.`;
 export function userInputUndrainedNotice(facts) {
     let kind;
     let count;
     let cause;
+    let child;
     try {
         if (facts === null || typeof facts !== 'object' || Array.isArray(facts))
             return undefined;
@@ -639,12 +621,23 @@ export function userInputUndrainedNotice(facts) {
     catch {
         return undefined;
     }
+    try {
+        child = Object.hasOwn(facts, 'childSessionId') ? facts.childSessionId : undefined;
+    }
+    catch {
+        child = undefined;
+    }
+    const fromSubagent = typeof child === 'string' && child.length > 0;
     const n = positiveInt(count);
     if (n === undefined || (kind !== 'steer' && kind !== 'followUp'))
         return undefined;
     if (kind === 'followUp') {
-        return cause === undefined || cause === 'leg_end' ? followUpUndrainedSentence(n) : unrecognizedUndrainedSentence(n, kind);
+        if (cause === undefined || cause === 'leg_end')
+            return fromSubagent ? subagentFollowUpUndrainedSentence(n) : followUpUndrainedSentence(n);
+        return unrecognizedUndrainedSentence(n, kind);
     }
+    if (cause === 'leg_end' && fromSubagent)
+        return subagentSteerUndrainedSentence(n);
     if (typeof cause === 'string' && Object.hasOwn(STEER_UNDRAINED_SENTENCE, cause)) {
         return STEER_UNDRAINED_SENTENCE[cause](n);
     }
@@ -665,7 +658,6 @@ export const ENGINE_NOTICE_FACT_READERS = Object.freeze({
     'config.permission_mode_unavailable': readPermissionModeUnavailable,
     'permission.ask_released_by_mode': readAskReleasedByMode,
     'permission.read_deny_unapplied': readReadDenyUnapplied,
-    'resume.legacy_mode_seed_migrated': readLegacyModeSeedMigrated,
     'context.tool_turn_repaired': readToolTurnRepaired,
     'server.model_unreachable': readModelUnreachable,
     'task.tool_turn_incomplete': readToolTurnIncomplete,

package/dist/fileHistoryLegNotice.d.ts

@@ -0,0 +1,20 @@
+import type { AgentEvent } from '@sema-agent/sdk';
+import { type FileHistoryCaptureReading } from './fileHistoryCaptureCapability.js';
+export type FileHistoryDeclarationFact = 'sent' | 'not_sent' | 'unknown';
+export declare const FILE_HISTORY_LEG_VERDICTS: readonly ["not_honored", "not_offered", "honored", "not_declared", "unknown"];
+export type FileHistoryLegNoticeVerdict = (typeof FILE_HISTORY_LEG_VERDICTS)[number];
+export interface FileHistoryLegNoticeInput {
+    readonly capability: FileHistoryCaptureReading;
+    readonly declaration: FileHistoryDeclarationFact;
+    readonly captureOffByUser: boolean;
+    readonly legWord: string | undefined;
+}
+export declare function fileHistoryLegNoticeVerdict(input: FileHistoryLegNoticeInput): FileHistoryLegNoticeVerdict;
+export declare function fileHistoryLegNoticeSentence(verdict: FileHistoryLegNoticeVerdict): string | null;
+export declare function fileHistoryDeclarationOfBody(body: object | null | undefined): FileHistoryDeclarationFact;
+export interface FileHistoryDeclarationLedger {
+    declared(requestKey: string, fact: FileHistoryDeclarationFact): boolean;
+    boundToRun(requestKey: string, runId: string, event: AgentEvent): boolean;
+    declarationOf(runId: string): FileHistoryDeclarationFact;
+}
+export declare function createFileHistoryDeclarationLedger(): FileHistoryDeclarationLedger;

package/dist/fileHistoryLegNotice.js

@@ -0,0 +1,122 @@
+import { fileHistoryCaptureMode } from './fileHistoryCaptureCapability.js';
+import { frameProvesDelivery } from './promptDelivery.js';
+import { FILE_HISTORY_DISABLED } from './request/taskRequest.js';
+export const FILE_HISTORY_LEG_VERDICTS = Object.freeze(['not_honored', 'not_offered', 'honored', 'not_declared', 'unknown']);
+function ownRead(o, key) {
+    return Object.hasOwn(o, key) ? o[key] : undefined;
+}
+function declarationOfInput(v) {
+    return v === 'sent' || v === 'not_sent' ? v : 'unknown';
+}
+export function fileHistoryLegNoticeVerdict(input) {
+    if (typeof input !== 'object' || input === null)
+        return 'unknown';
+    let capability;
+    let declaration;
+    let offByUser;
+    let legWord;
+    try {
+        capability = ownRead(input, 'capability');
+        declaration = declarationOfInput(ownRead(input, 'declaration'));
+        offByUser = ownRead(input, 'captureOffByUser') === true;
+        legWord = ownRead(input, 'legWord');
+    }
+    catch {
+        return 'unknown';
+    }
+    if (legWord !== 'on' && legWord !== FILE_HISTORY_DISABLED)
+        return 'unknown';
+    if (declaration === 'sent')
+        return legWord === 'on' ? 'not_honored' : 'honored';
+    if (!offByUser)
+        return 'not_declared';
+    const mode = fileHistoryCaptureMode(capability);
+    if (legWord === 'on' && mode === 'on-always')
+        return 'not_offered';
+    if (declaration === 'not_sent' && (legWord === FILE_HISTORY_DISABLED || mode === 'on-optional'))
+        return 'not_declared';
+    return 'unknown';
+}
+const NOT_HONORED_SENTENCE = 'The engine is still capturing file history for this session, though your settings asked it not to.';
+const NOT_OFFERED_SENTENCE = 'This engine always captures file history and cannot turn it off per session, even though file checkpoints are off in your settings.';
+export function fileHistoryLegNoticeSentence(verdict) {
+    if (verdict === 'not_honored')
+        return NOT_HONORED_SENTENCE;
+    if (verdict === 'not_offered')
+        return NOT_OFFERED_SENTENCE;
+    return null;
+}
+export function fileHistoryDeclarationOfBody(body) {
+    if (typeof body !== 'object' || body === null)
+        return 'unknown';
+    try {
+        if (Array.isArray(body))
+            return 'unknown';
+        if (typeof body.toJSON === 'function')
+            return 'unknown';
+        const d = Object.getOwnPropertyDescriptor(body, 'fileHistory');
+        const all = Object.getOwnPropertyDescriptors(body);
+        for (const k of Reflect.ownKeys(all)) {
+            const x = all[k];
+            if (x !== undefined && x.enumerable === true && !Object.hasOwn(x, 'value'))
+                return 'unknown';
+        }
+        const listed = Object.hasOwn(all, 'fileHistory') ? all.fileHistory : undefined;
+        const listedOn = listed !== undefined && listed.enumerable === true;
+        if (d === undefined || d.enumerable !== true)
+            return listedOn ? 'unknown' : 'not_sent';
+        if (!Object.hasOwn(d, 'value') || !listedOn || !Object.hasOwn(listed, 'value') || !Object.is(listed.value, d.value))
+            return 'unknown';
+        if (!Object.is(body.fileHistory, d.value))
+            return 'unknown';
+        if (typeof d.value === 'object' && d.value !== null)
+            return 'unknown';
+        return d.value === FILE_HISTORY_DISABLED ? 'sent' : 'not_sent';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+const idOk = (v) => typeof v === 'string' && v.length > 0;
+export function createFileHistoryDeclarationLedger() {
+    const factsByKey = new Map();
+    const keysByRun = new Map();
+    return Object.freeze({
+        declared(requestKey, fact) {
+            if (!idOk(requestKey) || (fact !== 'sent' && fact !== 'not_sent'))
+                return false;
+            let set = factsByKey.get(requestKey);
+            if (set === undefined)
+                factsByKey.set(requestKey, (set = new Set()));
+            set.add(fact);
+            return true;
+        },
+        boundToRun(requestKey, runId, event) {
+            if (!idOk(requestKey) || !idOk(runId) || !frameProvesDelivery(event))
+                return false;
+            let set = keysByRun.get(runId);
+            if (set === undefined)
+                keysByRun.set(runId, (set = new Set()));
+            set.add(requestKey);
+            return true;
+        },
+        declarationOf(runId) {
+            if (!idOk(runId))
+                return 'unknown';
+            const keys = keysByRun.get(runId);
+            if (keys === undefined)
+                return 'unknown';
+            let agreed;
+            for (const k of keys) {
+                const facts = factsByKey.get(k);
+                if (facts === undefined || facts.size !== 1)
+                    return 'unknown';
+                const [only] = facts;
+                if (only === undefined || (agreed !== undefined && agreed !== only))
+                    return 'unknown';
+                agreed = only;
+            }
+            return agreed ?? 'unknown';
+        },
+    });
+}

package/dist/gateOutcome.d.ts

@@ -40,7 +40,7 @@ export interface SettlementWhoView {
     approver?: string;
     window?: string;
 }
-export declare const SETTLEMENT_KIND_WORDS: readonly ["human_allowed", "human_refused", "approval_window_expired", "denial_limit_window_expired", "park_sla_expired", "no_approver", "approver_unavailable", "approver_error", "approver_contract", "presentation_failed", "blanket_allow_refused", "policy_refused", "task_aborted"];
+export declare const SETTLEMENT_KIND_WORDS: readonly ["human_allowed", "human_refused", "approval_window_expired", "denial_limit_window_expired", "park_sla_expired", "no_approver", "approver_unavailable", "approver_error", "approver_contract", "presentation_failed", "blanket_allow_refused", "policy_allowed", "policy_refused", "task_aborted"];
 export interface SettlementView {
     kind: Settlement['kind'] | (string & {});
     who: SettlementWhoView;

package/dist/gateOutcome.js

@@ -20,6 +20,7 @@ export const SETTLEMENT_KIND_WORDS = Object.freeze([
     'approver_contract',
     'presentation_failed',
     'blanket_allow_refused',
+    'policy_allowed',
     'policy_refused',
     'task_aborted',
 ]);

package/dist/generated/engineFactTables.d.ts

@@ -9,3 +9,4 @@ export declare const CORE_PERMISSION_MODE_FOLD_REASONS: readonly string[];
 export declare const CORE_ENGINE_CARD_TYPES: readonly string[];
 export declare const CORE_TOOL_DECLARATION_CODES: readonly string[];
 export declare const CORE_MODE_RELEASE_REASONS: readonly ["rule_unreadable"];
+export declare const CORE_HOOK_TOOL_ALIASES: Readonly<Record<string, string>>;

package/dist/generated/engineFactTables.js

@@ -114,3 +114,6 @@ export const CORE_TOOL_DECLARATION_CODES = Object.freeze([
 export const CORE_MODE_RELEASE_REASONS = Object.freeze([
     "rule_unreadable",
 ]);
+export const CORE_HOOK_TOOL_ALIASES = Object.freeze(Object.assign(Object.create(null), Object.fromEntries([
+    ["ListPeers", "ListAgents"],
+])));