@sema-agent/client-core 0.83.0 → 0.83.2

package/dist/engineAgentAbsence.d.ts

@@ -0,0 +1,52 @@
+import { type EngineAgentPanelAbsence, type EngineAgentPanelCycleIdentity, type EngineAgentPanelEvent } from './engineAgentPanelStore.js';
+import type { RunTerminalStatus } from './runTerminal.js';
+export declare const ENGINE_AGENT_ABSENT_ROW_TEXT = "engine no longer reports this agent \u00B7 it may still be running";
+export declare const ENGINE_AGENT_ABSENCE_TTL_MS: number;
+export type EngineAgentAbsenceMark = Readonly<Pick<EngineAgentPanelAbsence, 'lastSeenAtMs' | 'absentForMs'>>;
+export interface EngineAgentAbsenceRowFacts {
+    readonly status: string;
+    readonly absence?: EngineAgentAbsenceMark;
+    readonly viewing?: boolean;
+}
+type AbsenceOnly = Pick<EngineAgentAbsenceRowFacts, 'absence'> | null | undefined;
+type StatusAndAbsence = Pick<EngineAgentAbsenceRowFacts, 'status' | 'absence'>;
+export declare function isEngineAgentAbsentRow(row: AbsenceOnly): boolean;
+export declare function engineAgentAbsenceMarkOf(row: StatusAndAbsence, ev: Pick<EngineAgentPanelAbsence, 'lastSeenAtMs' | 'absentForMs'>): EngineAgentAbsenceMark | null;
+export declare function engineAgentPanelEventClearsAbsence(ev: EngineAgentPanelEvent, current?: EngineAgentPanelCycleIdentity | null): boolean;
+export declare function engineAgentAbsenceClockStopMs(row: AbsenceOnly): number | undefined;
+export declare function engineAgentRowCountsAsRunning(row: StatusAndAbsence): boolean;
+export interface EngineAgentRowTally {
+    readonly running: number;
+    readonly absent: number;
+    readonly byStatus: Readonly<Record<string, number>>;
+}
+export declare function tallyEngineAgentRows(rows: readonly StatusAndAbsence[] | Readonly<Record<string, StatusAndAbsence>>): EngineAgentRowTally;
+export declare function engineAgentTurnSweepSettles(taskId: string, row: StatusAndAbsence): boolean;
+export declare function engineAgentAbsenceTtlDueAtMs(row: AbsenceOnly, ttlMs?: number): number | undefined;
+export declare const ENGINE_AGENT_REGISTRY_READINGS: readonly ["running", "ended", "not_listed", "unknown"];
+export type EngineAgentRegistryReading = (typeof ENGINE_AGENT_REGISTRY_READINGS)[number];
+export interface EngineAgentAbsenceReapRow {
+    readonly absence?: EngineAgentAbsenceMark;
+    readonly viewing?: boolean;
+    readonly registry?: EngineAgentRegistryReading;
+}
+export interface EngineAgentAbsenceReclaim {
+    readonly taskId: string;
+    readonly lastSeenAtMs: number;
+    readonly absentForMs: number;
+    readonly dueAtMs: number;
+    readonly registry: 'ended' | 'not_listed';
+}
+export interface EngineAgentAbsenceReap {
+    readonly reclaim: readonly EngineAgentAbsenceReclaim[];
+    readonly heldByViewer: readonly string[];
+}
+export interface EngineAgentAbsenceReapOptions {
+    readonly nowMs: number;
+    readonly ttlMs?: number;
+    readonly owned?: ReadonlySet<string>;
+}
+export declare function reapEngineAgentAbsentRows(rows: Readonly<Record<string, EngineAgentAbsenceReapRow | null | undefined>>, opts: EngineAgentAbsenceReapOptions): EngineAgentAbsenceReap;
+export declare function engineAgentAbsenceDroppedLine(label: string, ttlMs?: number, removeReason?: string | null): string;
+export declare function engineAgentTerminalAfterDropLine(label: string, status: RunTerminalStatus, hasReport: boolean): string;
+export {};

package/dist/engineAgentAbsence.js

@@ -0,0 +1,131 @@
+import { displayUntrusted } from './displayUntrusted.js';
+import { isEnginePanelTaskResident, isStaleEngineAgentPanelEnd, } from './engineAgentPanelStore.js';
+export const ENGINE_AGENT_ABSENT_ROW_TEXT = 'engine no longer reports this agent · it may still be running';
+export const ENGINE_AGENT_ABSENCE_TTL_MS = 30 * 60_000;
+function effectiveTtl(ttlMs) {
+    return typeof ttlMs === 'number' && Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : ENGINE_AGENT_ABSENCE_TTL_MS;
+}
+function markOf(row) {
+    if (typeof row !== 'object' || row === null)
+        return undefined;
+    const a = row.absence;
+    return typeof a === 'object' && a !== null ? a : undefined;
+}
+export function isEngineAgentAbsentRow(row) {
+    return markOf(row) !== undefined;
+}
+export function engineAgentAbsenceMarkOf(row, ev) {
+    if (row?.status !== 'running')
+        return null;
+    if (isEngineAgentAbsentRow(row))
+        return null;
+    if (typeof ev?.lastSeenAtMs !== 'number' || !Number.isFinite(ev.lastSeenAtMs))
+        return null;
+    return { lastSeenAtMs: ev.lastSeenAtMs, absentForMs: ev.absentForMs };
+}
+export function engineAgentPanelEventClearsAbsence(ev, current) {
+    if (typeof ev !== 'object' || ev === null)
+        return false;
+    switch (ev.kind) {
+        case 'tick':
+        case 'fleet-row':
+            return true;
+        case 'end':
+            return !isStaleEngineAgentPanelEnd(ev, current);
+        default:
+            return false;
+    }
+}
+export function engineAgentAbsenceClockStopMs(row) {
+    return markOf(row)?.lastSeenAtMs;
+}
+export function engineAgentRowCountsAsRunning(row) {
+    if (typeof row !== 'object' || row === null)
+        return false;
+    if (isEngineAgentAbsentRow(row))
+        return false;
+    return row.status === 'running' || row.status === 'pending';
+}
+export function tallyEngineAgentRows(rows) {
+    const list = Array.isArray(rows) ? rows : Object.values(rows ?? {});
+    let running = 0;
+    let absent = 0;
+    const byStatus = Object.create(null);
+    for (const row of list) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const r = row;
+        if (isEngineAgentAbsentRow(r)) {
+            absent++;
+            continue;
+        }
+        if (engineAgentRowCountsAsRunning(r)) {
+            running++;
+            continue;
+        }
+        const word = String(r.status);
+        byStatus[word] = (byStatus[word] ?? 0) + 1;
+    }
+    return { running, absent, byStatus };
+}
+export function engineAgentTurnSweepSettles(taskId, row) {
+    if (typeof row !== 'object' || row === null)
+        return false;
+    if (isEnginePanelTaskResident(taskId))
+        return false;
+    if (row.status !== 'running')
+        return false;
+    return !isEngineAgentAbsentRow(row);
+}
+export function engineAgentAbsenceTtlDueAtMs(row, ttlMs) {
+    const a = markOf(row);
+    if (a === undefined || typeof a.lastSeenAtMs !== 'number' || !Number.isFinite(a.lastSeenAtMs))
+        return undefined;
+    return a.lastSeenAtMs + effectiveTtl(ttlMs);
+}
+export const ENGINE_AGENT_REGISTRY_READINGS = Object.freeze(['running', 'ended', 'not_listed', 'unknown']);
+function registryConfirmsGone(reading) {
+    return reading === 'ended' || reading === 'not_listed';
+}
+export function reapEngineAgentAbsentRows(rows, opts) {
+    const reclaim = [];
+    const heldByViewer = [];
+    const now = opts?.nowMs;
+    if (typeof now !== 'number' || !Number.isFinite(now))
+        return { reclaim, heldByViewer };
+    const ttl = effectiveTtl(opts.ttlMs);
+    for (const [taskId, row] of Object.entries(rows ?? {})) {
+        if (opts.owned !== undefined && !opts.owned.has(taskId))
+            continue;
+        const a = markOf(row);
+        if (a === undefined || typeof a.lastSeenAtMs !== 'number' || !Number.isFinite(a.lastSeenAtMs))
+            continue;
+        const dueAtMs = a.lastSeenAtMs + ttl;
+        if (now < dueAtMs)
+            continue;
+        const registry = row?.registry;
+        if (!registryConfirmsGone(registry))
+            continue;
+        if (row?.viewing === true) {
+            heldByViewer.push(taskId);
+            continue;
+        }
+        reclaim.push({ taskId, lastSeenAtMs: a.lastSeenAtMs, absentForMs: a.absentForMs, dueAtMs, registry });
+    }
+    return { reclaim, heldByViewer };
+}
+const REMOVE_REASON_DISPLAY_MAX = 64;
+export function engineAgentAbsenceDroppedLine(label, ttlMs, removeReason) {
+    const minutes = Math.round(effectiveTtl(ttlMs) / 60_000);
+    const reason = typeof removeReason === 'string' && removeReason !== ''
+        ? displayUntrusted(removeReason, { max: REMOVE_REASON_DISPLAY_MAX })
+        : '';
+    const why = reason !== ''
+        ? ` · the engine removed it from the fleet list (${reason}); that is not an outcome — read the run to settle it`
+        : ' · outcome unknown';
+    return `${displayUntrusted(label)} was dropped from the task panel after ${minutes} min without an engine report${why}`;
+}
+export function engineAgentTerminalAfterDropLine(label, status, hasReport) {
+    const tail = hasReport ? ' · its final report arrived too late to keep in the panel' : '';
+    return `${displayUntrusted(label)} reported ${displayUntrusted(status)} after it was dropped from the task panel${tail}`;
+}

package/dist/engineNoticeCodes.js

@@ -65,6 +65,8 @@ export const ENGINE_NOTICE_CODES = Object.freeze([
     'task.halt_unconsumed',
     'task.late_approval',
     'task.interrupt_unconsumed',
+    'approval.read_root_granted',
+    'approval.read_root_grant_rejected',
     'memory.capture_opted_out',
     'memory.capture_optout_unpersisted',
     'skills.listing_truncated',
@@ -142,6 +144,8 @@ export const ENGINE_NOTICE_AUDIENCE = Object.freeze({
     'task.halt_unconsumed': 'user',
     'task.late_approval': 'user',
     'task.interrupt_unconsumed': 'user',
+    'approval.read_root_granted': 'user',
+    'approval.read_root_grant_rejected': 'user',
     'memory.capture_opted_out': 'user',
     'memory.capture_optout_unpersisted': 'user',
     'skills.listing_truncated': 'operator',

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.d.ts

@@ -14,3 +14,7 @@ export type RuleStoreUnreadableKind = (typeof RULE_STORE_UNREADABLE_KINDS)[numbe
 export declare function isRuleStoreUnreadableKind(v: unknown): v is RuleStoreUnreadableKind;
 export declare function ruleStoreUnreadableDetail(kind: RuleStoreUnreadableKind): string;
 export declare function mandatedApprovalDetail(): string;
+export declare const APPROVAL_MANDATE_WORDS: readonly ["operator_always", "tool_marks", "probe_mandate", "probe_unanswered", "write_protection", "write_protection_unresolved"];
+export type ApprovalMandateWord = (typeof APPROVAL_MANDATE_WORDS)[number];
+export declare function isApprovalMandateWord(v: unknown): v is ApprovalMandateWord;
+export declare function approvalMandateDetail(word: ApprovalMandateWord): string;

package/dist/gateVocabulary.js

@@ -116,5 +116,33 @@ 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';
+}
+export const APPROVAL_MANDATE_WORDS = Object.freeze([
+    'operator_always',
+    'tool_marks',
+    'probe_mandate',
+    'probe_unanswered',
+    'write_protection',
+    'write_protection_unresolved',
+]);
+const _mandateWordsPin = true;
+void _mandateWordsPin;
+const APPROVAL_MANDATE_SET = new Set(APPROVAL_MANDATE_WORDS);
+export function isApprovalMandateWord(v) {
+    return APPROVAL_MANDATE_SET.has(v);
+}
+const APPROVAL_MANDATE_SENTENCES = Object.freeze({
+    operator_always: 'this deployment requires a separate confirmation for each shell command, and this call is one of them',
+    tool_marks: 'this tool declares that it reaches outside this machine or makes changes that cannot be undone',
+    probe_mandate: 'the check run on this call marked it as needing its own confirmation (the built-in shell check does so for a read outside the directories allowed for this session)',
+    probe_unanswered: 'the check run on this call did not answer (it timed out or failed), so whether the call stays inside the directories allowed for this session is unknown',
+    write_protection: "this change lands on a protected location (the agent's own configuration), which is confirmed one change at a time",
+    write_protection_unresolved: 'the protected-location check could not tell where this change lands, so whether it touches a protected location is unknown',
+});
+export function approvalMandateDetail(word) {
+    if (typeof word === 'string' && Object.hasOwn(APPROVAL_MANDATE_SENTENCES, word)) {
+        return APPROVAL_MANDATE_SENTENCES[word];
+    }
+    return 'the reason reported for this confirmation is not one this client recognises, so it shows no reason';
 }

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/askSurvivesPosture.d.ts

@@ -0,0 +1,15 @@
+export interface AskPostureFacts {
+    readonly settingsAskRuleMatched?: boolean;
+}
+export type AskPostureSurvivalRoad = 'origin' | 'settings_ask_rule';
+export type AskPostureVerdict = {
+    readonly kind: 'must_ask';
+    readonly by: AskPostureSurvivalRoad;
+} | {
+    readonly kind: 'posture_may_answer';
+} | {
+    readonly kind: 'unknown';
+};
+export declare function askSurvivesPosture(req: {
+    readonly origin?: string;
+} | null | undefined, facts?: AskPostureFacts | null): AskPostureVerdict;

package/dist/hitl/askSurvivesPosture.js

@@ -0,0 +1,31 @@
+import { readOwnNonEmptyString } from '../ownKey.js';
+const ORIGIN_SURVIVES_POSTURE = Object.freeze({
+    content_question: true,
+    ancestor_marked: false,
+    org_unavailable: true,
+    org_rule: true,
+    rule_store_unavailable: true,
+    hook: true,
+    ask_rule: true,
+    denial_limit_fallback: true,
+    shell_gate_tighten: false,
+    safety_tighten: false,
+    policy: false,
+});
+const MUST_ASK_BY_ORIGIN = Object.freeze({ kind: 'must_ask', by: 'origin' });
+const MUST_ASK_BY_SETTINGS = Object.freeze({ kind: 'must_ask', by: 'settings_ask_rule' });
+const POSTURE_MAY_ANSWER = Object.freeze({ kind: 'posture_may_answer' });
+const UNKNOWN = Object.freeze({ kind: 'unknown' });
+export function askSurvivesPosture(req, facts) {
+    const origin = readOwnNonEmptyString(req, 'origin');
+    const rawMatched = typeof facts === 'object' && facts !== null ? facts.settingsAskRuleMatched : undefined;
+    const matched = typeof rawMatched === 'boolean' ? rawMatched : undefined;
+    const known = origin !== undefined && Object.hasOwn(ORIGIN_SURVIVES_POSTURE, origin);
+    if (known && ORIGIN_SURVIVES_POSTURE[origin] === true)
+        return MUST_ASK_BY_ORIGIN;
+    if (matched === true)
+        return MUST_ASK_BY_SETTINGS;
+    if (matched === false && (origin === undefined || known))
+        return POSTURE_MAY_ANSWER;
+    return UNKNOWN;
+}

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/hitl/toolApprovalWire.d.ts

@@ -1,5 +1,6 @@
 import { type GateCurrentPending, type HitlFailureStage, type HitlSafetyCode, type HitlClientLike, type DecideOperationObserver } from './hitlBridge.js';
 import { type RuleStoreUnreadableKind } from '../gateVocabulary.js';
+import { type ApprovalMandateWord } from '../gateVocabulary.js';
 import { type DenyAttributionRefusalDetail } from '../wireRefusalCopy.js';
 import { type DecideReceiptView } from '../decideReceipt.js';
 import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS, DENIAL_LIMIT_KINDS } from '@sema-agent/sdk';
@@ -137,6 +138,7 @@ export interface ApprovalCardRequest {
     receivedAtMs?: number;
     ruleOffersAbsence?: string;
     mandated?: true;
+    mandate?: ApprovalMandateWord;
     denialLimitFallback?: DenialLimitFallback;
     origin?: string;
     ruleStoreUnreadable?: RuleStoreUnreadableKind;
@@ -176,6 +178,7 @@ export interface ToolApprovalFrame {
     ruleEvidence?: unknown;
     requiresRealApproval?: true;
     mandated?: true;
+    mandate?: string;
     origin?: string;
     inputHasBidi?: true;
     parked?: true;
@@ -194,11 +197,16 @@ export interface ToolApprovalDelegation {
     depth: number;
     agentName?: string;
 }
-export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "ruleStoreUnreadable", "readRootCandidate", "mandated", "origin", "inputHasBidi", "parked", "persistedRuleShadowed", "probeCause", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome"];
-export declare function approvalIsMandated(v: {
-    mandated?: true;
-    ruleOffersAbsence?: string;
-} | undefined | null): boolean;
+export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "ruleStoreUnreadable", "readRootCandidate", "mandated", "mandate", "origin", "inputHasBidi", "parked", "persistedRuleShadowed", "probeCause", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome"];
+export interface ApprovalMandatedFacts {
+    readonly mandated?: true;
+    readonly ruleOffersAbsence?: string;
+    readonly mandate?: string;
+}
+export declare function approvalIsMandated(v: ApprovalMandatedFacts | undefined | null): boolean;
+export declare function readApprovalMandate(v: {
+    readonly mandate?: string;
+} | undefined | null): ApprovalMandateWord | undefined;
 export declare function isFromSubagent(frame: ToolApprovalFrame): boolean;
 export type ToolApprovalRespondDecision = 'allow' | 'allow_session' | 'deny';
 export interface RespondToolApprovalOpts {

package/dist/hitl/toolApprovalWire.js

@@ -1,11 +1,13 @@
 import { DEFAULT_DENY_REASON, DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, denyReasonForWire, findPendingForTask, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
 import { askParkRowArm } from './askParkRowRouting.js';
 import { hostLog } from '../host.js';
+import { readOwnNonEmptyString } from '../ownKey.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { readEngineActiveBgTasks } from '../fleet/fleetLedger.js';
 import { observeCancelByDeny, surfaceRememberNotApplied, surfaceEditNotForwarded, surfaceEditRefusedOnBlindAsk, surfaceRuleArmNotSent, surfaceRuleArmRejected } from './hitlHostSurface.js';
 import { approvalCallKey, liveFrameCallKey } from './gateIdentity.js';
 import { isRuleStoreUnreadableKind } from '../gateVocabulary.js';
+import { isApprovalMandateWord } from '../gateVocabulary.js';
 import { denyAttributionRefusalFromError } from '../wireRefusalCopy.js';
 import { decideFailureNote } from '../decideFailureNote.js';
 import { readDecideReceipt } from '../decideReceipt.js';
@@ -205,6 +207,8 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         ...(pending.governanceForced === true ? { governanceForced: true } : {}),
         ...(pending.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
         ...(pending.mandated === true ? { mandated: true } : {}),
+        ...((w) => (w !== undefined ? { mandate: w } : {}))(readApprovalMandate(pending)),
+        ...((o) => (o !== undefined ? { origin: o } : {}))(readOwnNonEmptyString(pending, 'origin')),
         ...(pending.gateKind === 'irreversible_ask' ? { irreversibleParkGate: true } : {}),
         ...(pending.hasBidiControls === true ? { hasBidiControls: true } : {}),
         ...(ruleOffersReadOnly !== undefined ? { ruleOffersReadOnly } : {}),
@@ -379,6 +383,7 @@ export const TOOL_APPROVAL_FRAME_KEYS_MIRROR = [
     'ruleStoreUnreadable',
     'readRootCandidate',
     'mandated',
+    'mandate',
     'origin',
     'inputHasBidi',
     'parked',
@@ -400,7 +405,15 @@ export function approvalIsMandated(v) {
         return false;
     if (v.mandated === true)
         return true;
-    return v.ruleOffersAbsence === MANDATED_ABSENCE_WORD;
+    if (v.ruleOffersAbsence === MANDATED_ABSENCE_WORD)
+        return true;
+    return readApprovalMandate(v) !== undefined;
+}
+export function readApprovalMandate(v) {
+    if (typeof v !== 'object' || v === null || !Object.hasOwn(v, 'mandate'))
+        return undefined;
+    const raw = v.mandate;
+    return isApprovalMandateWord(raw) ? raw : undefined;
 }
 function isToolApprovalDelegation(v) {
     if (v === null || typeof v !== 'object')
@@ -828,6 +841,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         ...(isWireRecordCarrier(frame.ruleEvidence) ? { ruleEvidence: frame.ruleEvidence } : {}),
         ...(frame.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
         ...(frame.mandated === true ? { mandated: true } : {}),
+        ...((w) => (w !== undefined ? { mandate: w } : {}))(readApprovalMandate(frame)),
         ...(() => { const rc = readReadRootCandidate(frame.readRootCandidate); return rc !== undefined ? { readRootCandidate: rc } : {}; })(),
         ...(frame.inputHasBidi === true ? { inputHasBidi: true } : {}),
         ...(typeof frame.ruleOffersAbsence === 'string' && frame.ruleOffersAbsence !== ''
@@ -835,7 +849,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
             : {}),
         ...(denialLimitFallback !== undefined ? { denialLimitFallback } : {}),
         ...((k) => (k !== undefined ? { ruleStoreUnreadable: k } : {}))(readRuleStoreUnreadable(frame.ruleStoreUnreadable)),
-        ...(typeof frame.origin === 'string' && frame.origin !== '' ? { origin: frame.origin } : {}),
+        ...((o) => (o !== undefined ? { origin: o } : {}))(readOwnNonEmptyString(frame, 'origin')),
     });
     if (argsNotRealInput && card.kind === 'allow' && card.updatedInput !== undefined) {
         hostLog('error', `liveToolApprovalWire: ${approvalId} card returned an edited approval on a card whose arguments are not the tool's real input (${lane?.argsUnavailable === true ? 'args-unavailable ask' : 'arguments omitted or absent on the frame'}) — nothing sent (the ask stays pending)`);

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";