@sema-agent/core 5.31.0 → 5.32.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 5.32.0 — 2026-08-14
+
+No BREAKING changes. One additive disclosure surface; zero resolution-result changes (the read-face
+clamp VERDICT is unchanged since 5.30.0 — only its occurrence is now announced).
+
+### Added
+
+- `config.read_face_deployment_clamped` EngineNotice family (#237): a deployment-wide
+  `readFace: "open"` beside a read-only (verifier) mount clamps to `"roots"` (stricter-wins);
+  the clamp's occurrence is now announced instead of silent. The trigger fires only when the
+  deployment seat was the deciding one — an explicit task-level `"roots"` reaches the same value
+  with or without the mount (no false-cause claim), and the task-seat `"open"` contradiction still
+  refuses loudly. Delivery: the prepare station announces once per `onNotice` SINK (the listener,
+  not the deps object — the Runner rebuilds its deps and `runTask` builds a Runner per call, so a
+  deps-keyed ledger would repeat per task; unwired console arm latches once per process); a
+  library-direct `createHandsToolkit({ readFace: "open", readOnly: true })` announces at toolkit
+  creation through its own `HandsToolkitOptions.onNotice` seat (absent ⇒ the same line via
+  `console.warn`). `detail: { seat, declared, inForce, cause }`. New export:
+  `deploymentReadFaceClampNotice` (the one shared notice builder).
+
+### Fixed
+
+- `HandsToolkitOptions.readFace` JSDoc (ships in the `.d.ts`) stopped promising a loud refusal
+  beside `readOnly: true` — stale since the 96ef89d seat distinction (5.30.0): the deps-shaped
+  seat clamps and announces; the loud refusal belongs to `TaskSpec.readFace`. Wording only, two
+  sites; the runtime behavior was already as now documented.
+
+### Docs
+
+- The recursive-verb table (`RECURSIVE_READ_FORMS`) declares its KNOWN OPEN SET with the standing
+  sweep obligation, and `StripSurvey` states consumer guidance for truncated samples (the two
+  5.31.0 review deductions; wording only).
+
 ## 5.31.0 — 2026-08-14
 
 No API-BREAKING changes. Behavior narrowings are all tighten-direction (auto-allow → ask, or

package/dist/core/runner/prepare-task.d.ts

@@ -30,6 +30,8 @@ import type { NestedUsageAccum, RunnerDeps, TaskEvent, TaskLimits, TaskResult, T
 import type { RepairBundle } from "../../agents/repair-loop.js";
 /** Test seam (mirrors `__resetBashTimeoutAnnouncements`): never called by production code. */
 export declare function __resetMaterializeEnvAnnouncements(): void;
+/** Test seam (mirrors `__resetMalformedNoticeSeatAnnouncement`): never called by production code. */
+export declare function __resetReadFaceClampAnnouncement(): void;
 /**
  * design/164 — validate `TaskSpec.limits` at the door and return it unchanged.
  *

package/dist/core/runner/prepare-task.js

@@ -74,7 +74,7 @@ import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.j
 import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../task-registry.js";
 import { createMonitorTool } from "../../tools/monitor.js";
 import { createWorktreeTools } from "../../tools/worktree.js";
-import { applyCompactionToReadFileState, assertReadFaceValue, bashReversibilityProbe, compileReadDeny, createHandsToolkit, isReadDedupStubResult, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, FULL_SHELL_CONTRACT_ID, HAND_TOOL_EFFECTS, pdfModelCapabilitiesOf } from "../../tools/fs/index.js";
+import { applyCompactionToReadFileState, assertReadFaceValue, bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, isReadDedupStubResult, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, FULL_SHELL_CONTRACT_ID, HAND_TOOL_EFFECTS, pdfModelCapabilitiesOf } from "../../tools/fs/index.js";
 import { decodeTextBytes } from "../../tools/fs/encoding.js";
 import { ASK_USER_QUESTION_TOOL_NAME, createAskUserQuestionTool, classifyQuestionOutcome, isLiveQuestionFace, validateAskQuestions, } from "../ask-question.js";
 import { createSchedulerTools } from "../../tools/scheduler-tools.js";
@@ -97,6 +97,11 @@ export function __resetMaterializeEnvAnnouncements() {
 function emitMaterializeEnvNotice(onNotice, message, detail) {
     deliverEngineNotice(onNotice, { code: "config.materialize_env_discarded", message, detail });
 }
+const readFaceClampAnnouncedSinks = new WeakSet();
+let readFaceClampConsoleAnnounced = false;
+export function __resetReadFaceClampAnnouncement() {
+    readFaceClampConsoleAnnounced = false;
+}
 const RECONCILE_MAX_RETRIES = 3;
 const DEFAULT_MAX_SUSPENDS = 5;
 const TASK_LIMIT_KEY_DICT = {
@@ -1692,6 +1697,20 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 readOnlyMount: handsReadOnly,
                 orgGoverned: deps.permissionRuleOrg !== undefined,
                 fullShellReachable,
+                onDeploymentClamp: () => {
+                    const sink = deps.onNotice;
+                    if (typeof sink === "function") {
+                        if (readFaceClampAnnouncedSinks.has(sink))
+                            return;
+                        readFaceClampAnnouncedSinks.add(sink);
+                    }
+                    else {
+                        if (readFaceClampConsoleAnnounced)
+                            return;
+                        readFaceClampConsoleAnnounced = true;
+                    }
+                    deliverEngineNotice(sink, deploymentReadFaceClampNotice());
+                },
             });
             if (resume !== undefined && (seedReadFaceSection === undefined || seedReadFaceSection.face === "roots"))
                 liveReadFace = "roots";

package/dist/core/types.d.ts

@@ -4230,7 +4230,16 @@ export interface EngineNotice {
      *    baseline (the strip is not a refusal in this window), which is why the drop is announced;
      *    `detail: { total, stripped: [{ key, reason }], omitted? }`, the rendered key list bounded in count
      *    and length because the names come from the untrusted script. One aggregated notice per governed
-     *    child build, not de-duplicated across builds: each spec is a distinct fact. */
+     *    child build, not de-duplicated across builds: each spec is a distinct fact.
+     *  - `"config.read_face_deployment_clamped"` (#237) — a deployment-wide `readFace: "open"` is not
+     *    in force beside a read-only (verifier) mount: it clamps to "roots" without throwing
+     *    (stricter-wins; the clamp verdict stands, only its occurrence was undisclosed). Announced
+     *    once per `onNotice` SINK at the prepare station (the verifier lane would otherwise repeat it
+     *    every spawn; the sink — not the deps object — is the unit because the Runner rebuilds its
+     *    deps and `runTask` builds a Runner per call), unwired console arm once per process;
+     *    a library-direct `createHandsToolkit` mount announces at toolkit creation (one per mount,
+     *    through the band-local `HandsToolkitOptions.onNotice` seat, absent ⇒ `console.warn`);
+     *    `detail: { seat, declared, inForce, cause }`. */
     code: string;
     /** The exact human-readable line the unwired build prints via `console.warn` — same words, one text. */
     message: string;

package/dist/index.d.ts

@@ -88,7 +88,7 @@ export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW,
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, } from "./tools/fs/index.js";
-export { resolveReadFace, type ReadFace, type ReadFaceInputs } from "./tools/fs/index.js";
+export { deploymentReadFaceClampNotice, resolveReadFace, type ReadFace, type ReadFaceInputs } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, type UsageWindow, type UsageWindowStore, type UsageWindowReading, type UsageWindowRecord, type UsageSlot, type UsageBucketRow, } from "./core/usage-window-store.js";

package/dist/index.js

@@ -69,7 +69,7 @@ export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW,
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, compileReadDeny, } from "./tools/fs/index.js";
-export { resolveReadFace } from "./tools/fs/index.js";
+export { deploymentReadFaceClampNotice, resolveReadFace } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, } from "./core/usage-window-store.js";

package/dist/tools/fs/index.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import type { BeforeWriteHook } from "../../core/types.js";
+import { type BeforeWriteHook } from "../../core/types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type ReadFileState } from "./safety.js";
 import type { PdfModelCapabilities } from "./pdf.js";
@@ -130,8 +130,12 @@ export interface HandsToolkitOptions {
      *  {@link import("./read-face.js").resolveReadFace} order prepare-task uses). Absent ⇒ the
      *  resolution order's default = "roots" (D-1b: the engine never opens implicitly). "open" skips
      *  ONLY the roots containment judgment — the deny set, the UNC out-of-set refusal and the
-     *  special-file type gates run in both faces (§2.0). Refused loudly beside `readOnly: true`
-     *  (the verifier mount's containment is load-bearing). Never affects the write faces. */
+     *  special-file type gates run in both faces (§2.0). Beside `readOnly: true` the mount wins:
+     *  this seat is deps-shaped (a deployment default, not a per-call assertion), so its "open"
+     *  CLAMPS to "roots" and the clamp is ANNOUNCED (`config.read_face_deployment_clamped`, through
+     *  `onNotice` / `console.warn`) — the loud refusal belongs to the TASK seat (`TaskSpec.readFace`),
+     *  which is the one genuine per-call contradiction (#237; stale "refused loudly" wording here
+     *  predated the 96ef89d seat distinction). Never affects the write faces. */
     readFace?: "open" | "roots";
 }
 /**

package/dist/tools/fs/index.js

@@ -1,3 +1,4 @@
+import { deliverEngineNotice } from "../../core/types.js";
 import { createTaskOutputTool, createTaskStopTool } from "../../core/task-registry.js";
 import { hasBackgroundShell } from "../../core/background-shell.js";
 import {} from "./safety.js";
@@ -12,7 +13,7 @@ export * from "./fs-bash.js";
 export * from "./read-deny.js";
 import { BASH_READONLY_DEFAULT_ALLOW, } from "./bash-readonly-classifier.js";
 import { compileReadDeny } from "./read-deny.js";
-import { resolveReadFace } from "./read-face.js";
+import { deploymentReadFaceClampNotice, resolveReadFace } from "./read-face.js";
 export * from "./read-face.js";
 import {} from "./fs-shared.js";
 import { createReadFileTool } from "./fs-read.js";
@@ -39,6 +40,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
         readOnlyMount: readOnly,
         orgGoverned: false,
         fullShellReachable: includeShell && !readOnly,
+        onDeploymentClamp: () => deliverEngineNotice(opts.onNotice, deploymentReadFaceClampNotice()),
     });
     const tools = [
         createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace),

package/dist/tools/fs/read-face.d.ts

@@ -29,6 +29,13 @@ export interface ReadFaceInputs {
      *  "open"… no — see the resolution order: an EXPLICIT open still wins (row 4 is a default, not a
      *  clamp); what it changes is that NOTHING implicit opens a bash-less mount. */
     fullShellReachable: boolean;
+    /** #237 — observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
+     *  (readOnly mount + deps "open" + NO task seat). Fired exactly when the deps declaration was the
+     *  deciding seat and the mount overrode it — not when a task-level "roots" pinned the same value
+     *  anyway (the mount changed nothing there, and announcing it would claim a false cause), and
+     *  never on the throw rows (those are already loud). The resolver stays the single owner of the
+     *  clamp predicate; stations own delivery/dedup ({@link deploymentReadFaceClampNotice}). */
+    onDeploymentClamp?: () => void;
 }
 /**
  * The ONE resolution order (§2.2), first hit wins. prepare-task AND createHandsToolkit both call
@@ -47,3 +54,17 @@ export interface ReadFaceInputs {
  *  5. default: ROOTS (D-1b — the engine never opens implicitly).
  */
 export declare function resolveReadFace(i: ReadFaceInputs): ReadFace;
+/**
+ * #237 — the ONE text of the deployment-clamp announcement (`config.read_face_deployment_clamped`).
+ * Both stations deliver THIS object through their own `deliverEngineNotice` call (prepare-task with
+ * the `RunnerDeps.onNotice` seat, once per notice sink — the sink, not the deps object, because the
+ * Runner rebuilds its deps; `createHandsToolkit` with its band-local `HandsToolkitOptions.onNotice`
+ * seat — toolkit creation is itself the one-per-mount boot moment, and an absent seat prints the
+ * same line via `console.warn`). Built here, import-free, so the message can never fork between
+ * the stations.
+ */
+export declare function deploymentReadFaceClampNotice(): {
+    code: string;
+    message: string;
+    detail: Record<string, unknown>;
+};

package/dist/tools/fs/read-face.js

@@ -16,6 +16,8 @@ export function resolveReadFace(i) {
             e.code = "config.read_face_readonly_conflict";
             throw e;
         }
+        if (deps === "open" && spec === undefined)
+            i.onDeploymentClamp?.();
         return "roots";
     }
     if (i.orgGoverned) {
@@ -36,3 +38,10 @@ export function resolveReadFace(i) {
         return "roots";
     return "roots";
 }
+export function deploymentReadFaceClampNotice() {
+    return {
+        code: "config.read_face_deployment_clamped",
+        message: `readFace (deployment seat): the deployment-wide "open" declaration is not in force on this read-only (verifier) mount — clamped to "roots" (stricter-wins: the mount's containment is load-bearing and never openable). Other mounts still honor "open".`,
+        detail: { seat: "readFace (deployment seat)", declared: "open", inForce: "roots", cause: "read_only_mount" },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.31.0",
+  "version": "5.32.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",