@sema-agent/client-core 0.82.7 → 0.83.1

package/dist/engineNoticeCodes.js

@@ -3,6 +3,7 @@ export const ENGINE_NOTICE_CODES = Object.freeze([
     'config.env_timeout_discarded',
     'config.materialize_env_discarded',
     'config.models_swapped',
+    'config.context_settings_swapped',
     'config.read_face_swapped',
     'config.read_face_deployment_clamped',
     'config.write_face_swapped',
@@ -22,6 +23,7 @@ export const ENGINE_NOTICE_CODES = Object.freeze([
     'config.durable_gate_unavailable',
     'config.peer_admission_out_of_range',
     'config.peer_lane_unmounted',
+    'config.secret_env_scrubbed',
     'peer.inbound_disposition',
     'peer.held_settled',
     'peer.idle_subscription',
@@ -78,6 +80,7 @@ export const ENGINE_NOTICE_AUDIENCE = Object.freeze({
     'config.env_timeout_discarded': 'operator',
     'config.materialize_env_discarded': 'operator',
     'config.models_swapped': 'operator',
+    'config.context_settings_swapped': 'operator',
     'config.read_face_swapped': 'operator',
     'config.read_face_deployment_clamped': 'operator',
     'config.write_face_swapped': 'operator',
@@ -97,6 +100,7 @@ export const ENGINE_NOTICE_AUDIENCE = Object.freeze({
     'config.durable_gate_unavailable': 'user',
     'config.peer_admission_out_of_range': 'operator',
     'config.peer_lane_unmounted': 'operator',
+    'config.secret_env_scrubbed': 'operator',
     'peer.inbound_disposition': 'user',
     'peer.held_settled': 'user',
     'peer.idle_subscription': 'user',

package/dist/fleet/fleetRowAgentType.d.ts

@@ -1,3 +1,2 @@
 export declare function recordFleetRowAgentType(taskIdTail: string, agentType: string | undefined): void;
 export declare function fleetRowAgentType(taskIdTail: string | undefined): string | undefined;
-export declare function __resetFleetRowAgentTypeForTests(): void;

package/dist/fleet/fleetRowAgentType.js

@@ -23,6 +23,3 @@ export function fleetRowAgentType(taskIdTail) {
     agentTypeByTail.set(taskIdTail, v);
     return v;
 }
-export function __resetFleetRowAgentTypeForTests() {
-    agentTypeByTail.clear();
-}

package/dist/fleetTaskDesc.js

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

package/dist/gateVocabulary.js

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

package/dist/hitl/approvalDecisionNoteAudit.js

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

package/dist/hitl/approvalResolution.js

@@ -70,6 +70,8 @@ function fsLegResolution(outcome, kind) {
     }
     if (stage === 'input')
         return { kind: 'not_sent', cause: 'no_input', ...call, ...detail };
+    if (stage === 'card' && pick(outcome, 'editRefused') === true)
+        return { kind: 'not_sent', cause: 'edit_refused', ...call, ...detail };
     if (stage === 'card')
         return { kind: 'not_sent', cause: 'card_unavailable', ...call, ...detail };
     if (stage === 'decide') {

package/dist/hitl/frameRouter.d.ts

@@ -24,7 +24,7 @@ export interface AskGateWireDeps {
     onToolApprovalOutcome?: (frame: ToolApprovalFrame, outcome: ToolApprovalFrameOutcome) => void | Promise<void>;
     onDecideOperation?: DecideOperationObserver;
 }
-export type GateKind = 'ask' | 'fs';
+type GateKind = 'ask' | 'fs';
 export interface GatePark {
     gate: GateKind;
     pendingDone?: AgentEvent | undefined;
@@ -55,10 +55,11 @@ export interface FrameRouterCtx {
 }
 export declare function isAskTool(toolName: string | undefined): boolean;
 export declare function isHostProgressFrame(ev: AgentEvent): boolean;
-export interface HeldFlushInterruptEvidence {
+interface HeldFlushInterruptEvidence {
     terminal?: AgentEvent | undefined;
     signal?: AbortSignal | undefined;
     gateAbortedByUser?: boolean | undefined;
 }
 export declare function flushHeldWithInterruptRewrite(led: GateLedger, evidence: HeldFlushInterruptEvidence): Generator<AgentEvent>;
 export declare function routeFrame(ev: AgentEvent, ctx: FrameRouterCtx): Promise<FrameAction>;
+export {};

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

@@ -39,6 +39,7 @@ export type FsApprovalOutcome = {
     retryExhausted?: true;
     currentPending?: GateCurrentPending | undefined;
     denyAttributionRefusal?: DenyAttributionRefusalDetail | undefined;
+    editRefused?: true;
 };
 export interface FsApprovalWireDeps {
     client: HitlClientLike;

package/dist/hitl/toolApprovalWire.js

@@ -140,15 +140,46 @@ function logAfterDecided(msg) {
     catch {
     }
 }
+const ARGS_OMITTED_PATH_RECOVERED_NOTE = 'tool arguments exceeded the wire cap and were omitted — only the target path was recovered (from the approval question); ' +
+    'the rest of the arguments, such as the content to write, is not shown, so you are deciding without seeing it. ' +
+    'Edits are not accepted on this card: there is no original input to edit';
+const ARGS_OMITTED_NOTHING_RECOVERED_NOTE = 'tool arguments exceeded the wire cap and were omitted, and nothing could be recovered from the approval question — ' +
+    'you are deciding without seeing what this call will do; deny it if you are not sure. ' +
+    'Edits are not accepted on this card: there is no original input to edit';
+const PARK_ROW_ARGS_ABSENT_NOTE = "this request's tool arguments are not available on this surface — neither the event stream nor the pending approval record " +
+    'carries them, so you are deciding without seeing them; deny it if you are not sure what it will do. ' +
+    'Edits are not accepted on this card: there is no original input to edit';
+const PARK_ROW_ARGS_TRUNCATED_NOTE = "this request's tool arguments were too large to keep on the pending approval record and were replaced by a size marker, " +
+    'so you are deciding without seeing them; deny it if you are not sure what it will do. ' +
+    'Edits are not accepted on this card: there is no original input to edit';
+const PARK_EDIT_REFUSED_REASON = "the card returned an edited approval, but this request's tool arguments are not available on this surface " +
+    '(missing, or replaced by a size marker on the pending approval record), so the edit cannot be applied — nothing was sent; ' +
+    'approve or deny it as it is';
+function isParkRowInputSizeMarker(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return false;
+    const keys = Object.keys(v);
+    if (keys.length !== 2 || !keys.includes('truncated') || !keys.includes('bytes'))
+        return false;
+    const o = v;
+    return o.truncated === true && typeof o.bytes === 'number' && Number.isFinite(o.bytes) && o.bytes >= 0;
+}
 export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signal, parkGatedCallId) {
     const found = await findPendingForTask(deps.client, taskId, (toolName) => toolName !== undefined && (toolNameIsFsWrite(toolName) || toolNameIsShellExec(toolName)), signal ? { signal } : undefined, parkGatedCallId, (row) => askParkRowArm(row) === 'tool-gate');
     if (!found.ok)
         return { kind: 'failed', stage: 'fetch', reason: found.reason, ...(found.code !== undefined ? { code: found.code } : {}) };
     const { pending, gatedCallId } = found;
     const toolName = typeof pending.toolName === 'string' ? pending.toolName : '';
-    const args = (gatedCallId !== undefined ? argsByCall.get(gatedCallId) : undefined) ??
-        pending.input ??
-        {};
+    const streamArgs = gatedCallId !== undefined ? argsByCall.get(gatedCallId) : undefined;
+    const rowInput = pending.input;
+    const rowArgsGap = streamArgs !== undefined && streamArgs !== null
+        ? undefined
+        : rowInput === undefined || rowInput === null
+            ? 'absent'
+            : isParkRowInputSizeMarker(rowInput)
+                ? 'truncated'
+                : undefined;
+    const args = streamArgs !== undefined && streamArgs !== null ? streamArgs : rowArgsGap !== undefined ? {} : rowInput;
     if (typeof args !== 'object' || args === null) {
         return { kind: 'failed', stage: 'input', gatedCallId, reason: 'gate has no tool input payload' };
     }
@@ -165,8 +196,15 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         args,
         callKey,
         ...(signal ? { signal } : {}),
+        ...(rowArgsGap !== undefined
+            ? {
+                argsUnavailable: true,
+                wireNote: rowArgsGap === 'truncated' ? PARK_ROW_ARGS_TRUNCATED_NOTE : PARK_ROW_ARGS_ABSENT_NOTE,
+            }
+            : {}),
         ...(pending.governanceForced === true ? { governanceForced: true } : {}),
         ...(pending.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+        ...(pending.mandated === true ? { mandated: true } : {}),
         ...(pending.gateKind === 'irreversible_ask' ? { irreversibleParkGate: true } : {}),
         ...(pending.hasBidiControls === true ? { hasBidiControls: true } : {}),
         ...(ruleOffersReadOnly !== undefined ? { ruleOffersReadOnly } : {}),
@@ -184,6 +222,11 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
             ? { toolCallId: pending.toolCallId }
             : {}),
     });
+    if (rowArgsGap !== undefined && card.kind === 'allow' && card.updatedInput !== undefined) {
+        hostLog('error', `liveToolApprovalWire: approval card for ${gatedCallId ?? `task ${taskId}`} returned an edited approval, but the tool input is ${rowArgsGap === 'truncated' ? 'a size marker on the pending row' : 'missing from both the stream and the pending row'} — nothing sent (the park stays pending)`);
+        surfaceEditRefusedOnBlindAsk();
+        return { kind: 'failed', stage: 'card', gatedCallId, reason: PARK_EDIT_REFUSED_REASON, editRefused: true };
+    }
     const decideSpan = bridge.openDecideOperation();
     const decideOpts = { ...(signal ? { signal } : {}), operation: decideSpan };
     try {
@@ -733,10 +776,14 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
             ? frame.args
             : undefined;
     let wireNote;
+    let argsFallback = false;
     if (typeof args !== 'object' || args === null) {
+        argsFallback = true;
+        const p = pathFromGateMessage(frame.message);
+        args = p !== undefined ? { file_path: p } : {};
         if (frame.argsOmitted === true) {
-            wireNote = 'tool arguments exceeded the wire cap and were omitted — the diff below is reconstructed from the gate message, not the full payload';
-            hostLog('debug', `liveToolApprovalWire: frame ${approvalId} args omitted (>16KiB wire cap) — card falls back to message-derived path`);
+            wireNote = p !== undefined ? ARGS_OMITTED_PATH_RECOVERED_NOTE : ARGS_OMITTED_NOTHING_RECOVERED_NOTE;
+            hostLog('debug', `liveToolApprovalWire: frame ${approvalId} args omitted (>16KiB wire cap) — card falls back to ${p !== undefined ? 'the message-derived path' : 'an empty input (no path could be derived from the message)'}`);
         }
         if (lane?.argsUnavailable === true) {
             wireNote =
@@ -744,9 +791,8 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
                     'so you are deciding without seeing them; deny it if you are not sure what it will do. ' +
                     'Edits are not accepted on this card: there is no original input to edit';
         }
-        const p = pathFromGateMessage(frame.message);
-        args = p !== undefined ? { file_path: p } : {};
     }
+    const argsNotRealInput = argsFallback || lane?.argsUnavailable === true;
     const ruleOffers = readRuleOfferSupply(frame.ruleOffers, frame.ruleSuggestions);
     const denialLimitFallback = readDenialLimitFallback(frame.denialLimitFallback);
     const card = await surfaceApprovalCard({
@@ -759,7 +805,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         ...(signal ? { signal } : {}),
         ...(isFromSubagent(frame) ? { workerBadge: subagentBadgeFor(frame) } : {}),
         ...(wireNote !== undefined ? { wireNote } : {}),
-        ...(lane?.argsUnavailable === true ? { argsUnavailable: true } : {}),
+        ...(argsNotRealInput ? { argsUnavailable: true } : {}),
         ...(frame.governanceForced === true ? { governanceForced: true } : {}),
         ...(lane?.windowIsCurrent === true
             ? {
@@ -791,8 +837,8 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         ...((k) => (k !== undefined ? { ruleStoreUnreadable: k } : {}))(readRuleStoreUnreadable(frame.ruleStoreUnreadable)),
         ...(typeof frame.origin === 'string' && frame.origin !== '' ? { origin: frame.origin } : {}),
     });
-    if (lane?.argsUnavailable === true && card.kind === 'allow' && card.updatedInput !== undefined) {
-        hostLog('error', `liveToolApprovalWire: ${approvalId} card returned an edited approval on an args-unavailable ask — nothing sent (the ask stays pending)`);
+    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)`);
         surfaceEditRefusedOnBlindAsk();
         return { decision: 'unresolved', editRefused: true };
     }

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