@sema-agent/core 5.24.0 → 5.26.0

package/CHANGELOG.md

@@ -1,5 +1,141 @@
 # Changelog
 
+## 5.26.0 — 2026-08-11
+
+No API-BREAKING changes (exports grow only; new members optional/additive). Several
+behavior-surface narrowings — every one tighten-direction — called out below.
+
+### Narrowed (behavior, ruled)
+
+- **A remote execution env no longer teaches the memory write path.** With `executionEnv` remote
+  and a memory store mounted, the `# Memory` write instruction is withheld (the sandboxed hands
+  cannot reach the host store; teaching the path walked the model into receipting saves that never
+  land). A deployment persisting through its own closure restores it by declaring
+  `TaskSpec.memoryPersistenceCapable: true`. **Consumer note**: probes pinning "remote run carries
+  the write instruction" go red; re-pin on the declaration.
+- **`memoryPersistenceCapable: false` is enforced, not just disclosed.** Over a writable scope the
+  session mounts the read-only notice AND the write gate refuses file-tool writes into the memory
+  root (`read_only_layering`, loud), and the terminal/checkpoint harvest admits nothing — through
+  the engine's zero-admission arm, so the report half still runs: materialize-time inbound findings
+  and quarantine escalations are drained into a real `HarvestReport` (with a warning naming the
+  declaration) instead of a fabricated empty one.
+- **The read-only notice retraction is DECLARED-only.** Only an explicit
+  `memoryPersistenceCapable: true` retracts the engine's writeScope-null notice; a write-capable
+  roster alone (inferred capability) no longer strips it — the gate refuses those very writes, so
+  inference proved nothing about the store.
+- **Dual-root overlap is a prepare-time configuration error.** Two memory planes whose data roots
+  or control dirs overlap (either direction, either tier) are refused loudly at prepare instead of
+  running two engines over shared physical state.
+- **A shell-doctrine mark is positive-only and monotonic.** A negative `irreversibility` tier is
+  not a provenance mark; `shellGate:"classify"` never downgrades an explicitly marked `"always"`.
+  Deployments with marked tools will see asks that classify used to swallow.
+- **Tool-result refs are injective and conflict-typed (#119).** The mint hashes an injective
+  representation (four `~`-separated segments incl. a content digest); writing a different payload
+  under an existing ref is a typed `ref_conflict` error, never a silent overwrite; a damaged owner
+  record refuses whole.
+
+### Added
+
+- **`TaskSpec.memoryPersistenceCapable`** (tri-state, additive): `true` = the deployment vouches
+  for a persistence channel the engine cannot see; `false` = mandatory floor (disclosure + write
+  gate + zero-admission harvest); absent = inferred from the final roster. Crosses the delegation
+  boundary tighten-only (a parent's `false` binds the subtree; a child definition cannot loosen
+  it). Non-boolean values are refused loudly at both doors (`config.memory_persistence_invalid` /
+  `config.agent.invalid`).
+- **`MEMORY_READONLY_NOTICE` / `NO_PERSISTENT_MEMORY_NOTICE` exported**, and
+  **`MemoryInjection.readOnlyNotice`** (additive member): a session with no write channel is told
+  so instead of silently receipting saves; the standalone notice serves rosters the engine never
+  sees.
+- **`MemoryEngine.harvest` accepts `admitNothing`** (additive option): a real harvest that commits
+  nothing while still draining and announcing inbound findings.
+
+### Fixed
+
+- Delegation seats forward the capability floor (subagent arbitration, retained-resume folding,
+  workflow agent-type folding fill absence only).
+- The offloaded-detail notice allowance derives from the ref-mint ceiling (a literal sized against
+  the retired two-segment shape under-bounded the four-segment notice).
+- Ten stale-or-loose doc/comment spots from the merged-code rescan (classify doctrine conditionals
+  stated in public docs; JSDoc reattachments; TiDB sizing note states the four-segment mint).
+
+### Known residual (registered, not a regression)
+
+- The zero-copy File backend's read-side inbound sync adopts disk divergence independent of session
+  intent: bytes a shell lands under the memory root during a read-only or declared-false session
+  can be adopted at a later materialize (checkpoint-resume included). Registered with three
+  candidate fixes pending a direction ruling; the disclosure, gate, and harvest boundaries above
+  all hold — this is the remaining channel, stated here so the boundary's edges are explicit.
+
+## 5.25.0 — 2026-08-10
+
+No API-BREAKING changes (exports grow only; every new member is optional/additive). One
+behavior-surface narrowing, called out below.
+
+### Narrowed (behavior, ruled)
+
+- **The persisted-rule lane gains its mandate boundary (#144, dual-source measured).** *Allow rules
+  silence the classifier's questions, never a mandated one.* A persisted allow rule used to
+  short-circuit every surviving non-governance ask — including an operator's `shellGate:"always"`
+  (per-call confirmation mandated by deployment config) and a tool's own egress/irreversibility
+  marks (the non-budgetable family). The boundary is a single-source provenance predicate: the
+  classify-doctrine bash ask (coarse tier `"maybe"`) stays the rule lane's home turf (the
+  don't-ask-again main case is deliberately preserved); doctrine-installed `"always"` and
+  tool-declared marks are not clearable by rule. When a rule MATCHES but cannot clear, the surviving
+  ask discloses it on both channels: a message note naming the rule and the mandate, and the new
+  additive `PermissionResult.ask.persistedRuleShadowed` member (the matched rule text) — a consumer
+  renders "your rule is alive, just outranked". **Consumer note**: deployments under
+  `shellGate:"always"` or with marked tools will see asks their users' rules used to clear.
+
+### Added
+
+- **`CheckpointError.detail.reason`** (closed set, additive; downstream-requested): discriminates
+  the pre-CAS refusal arms one code used to cover — `version_newer` / `env_factory_missing` /
+  `governed_unwired` on `unsupported_version` (each retryable on a differently-capable worker), and
+  `real_approval_damaged` / `real_approval_forged` / `constraint_chain_missing` on the
+  `invalid_outcome` row-integrity arms (terminal for the row's bytes). A deployment retry policy can
+  now tell "a capable worker can redeem this" from "no worker ever will".
+- **`REAL_APPROVAL_CHECKPOINT_VERSION` exported** from the package root (joins the other five ladder
+  constants).
+- **The I6 adoption boot gate reaches two more store faces** via an optional `dataRoot` anchor on
+  `FilePermissionRuleStoreProvider` and `createFileTaskListStore` (additive; the adoption arc's own
+  nested rule leg keeps its exemption, pinned). The freeze header states its real coverage — two
+  doors and the seams between them — instead of over-claiming.
+
+### Fixed
+
+- **The disclosure channel is real end-to-end (pre-release rescan on this very batch).**
+  `persistedRuleShadowed` was write-only as first landed: `AskRequest` gains the member (all four
+  mint sites thread it), and the durable park mint carries it as `RiskDescriptor.shadowedRule`
+  (`inlineUntrusted`-capped) — the mandated population's normal route now discloses like the
+  synchronous one. The mandate predicate judges egress FIRST (the tool's own declaration is not
+  shadowed by the coarse doctrine sharing the seat). The secret-scrub quarantine capture stops
+  treating a name collision as a receipt (family suffix form; the polluted-index warning claims a
+  capture only when its write landed). The last silent timeout discard (a legal cap below the
+  resolved default) is announced; an empty env string is a written silence exception (the unset
+  idiom). The materialize-strategy announcements gain a per-value process ledger and a reset seam.
+- **The loud-bad-value law lands on its two founding cases (#123, ruled).** `BASH_*_TIMEOUT_MS`
+  discards stop exempting the garbage/0/negative classes (every discarded value names the knob, what
+  arrived — env legs show the original string — and the value in force);
+  `SEMA_TOOL_MATERIALIZE_STRATEGY`'s refusal now matches the seat the bad value occupies: shadowed
+  by an explicit legal spec ⇒ loud discard (the documented "spec wins" precedence finally holds),
+  would-be-in-force ⇒ the closed-set refusal stands, dormant (no deferred tools) ⇒ announced once
+  per process instead of lying in wait.
+- **A v7+ checkpoint declaring parent constraints must carry both the frozen chain and its digest**
+  (they are one write with the version stamp) — a row carrying neither is refused pre-CAS as damaged
+  instead of silently falling back to the count-only contract. Rows v6 and below keep the historic
+  contract.
+- **The org resume belt's refusal carries the overlay's disclosure lines** (the resume path has no
+  `onUnavailable` seat) and tells a cancelled wait apart from unreadable governance. The verdict is
+  unchanged; the account is not.
+- The sandbox-admission registry/decision domain split is documented and pinned (the two
+  un-instrumented fold families are safe for structural reasons — a family that gains an ask arm
+  reds instead of arriving unrecorded); frozen projections' fold position is disclosed; the adoption
+  report declares the memory-engine tree `action:"none"` explicitly; two engine quarantine captures
+  go `wx`-exclusive (no symlink at the final name, no overwrite of earlier evidence under a coarse
+  clock); the abort-races-timeout test pin gets real load headroom; the v8 stamp note carries its
+  erratum (v8 rows appear on ANY durable deployment via the always-mounted integrity policies — what
+  stays true: rows without the bit keep their historic stamps).
+
 ## 5.24.0 — 2026-08-10
 
 No API-BREAKING changes (exports grow only; `suspendAsk` gains an optional fifth parameter;

package/dist/agents/agent-definition.js

@@ -4,5 +4,10 @@ export function defineAgent(def) {
         e.code = "config.agent.invalid";
         throw e;
     }
+    if (def.memoryPersistenceCapable !== undefined && typeof def.memoryPersistenceCapable !== "boolean") {
+        const e = new Error(`defineAgent("${def.name}"): memoryPersistenceCapable must be a boolean when present — got ${JSON.stringify(def.memoryPersistenceCapable)} (a string "false" would silently read as capable).`);
+        e.code = "config.agent.invalid";
+        throw e;
+    }
     return Object.freeze({ ...def });
 }

package/dist/agents/send-message-tool.js

@@ -682,6 +682,7 @@ export function createSendMessageTool(opts) {
                         ...(ctx.handsReadOnly === true ? { handsReadOnly: true } : {}),
                         ...(ctx.interactiveTools === false ? { interactiveTools: false } : {}),
                         ...(ctx.oneShot === true ? { oneShot: true } : {}),
+                        ...(ctx.memoryPersistenceCapable === false ? { memoryPersistenceCapable: false } : {}),
                     },
                     ...(ctx.autoModeReview !== undefined ? { currentAutoModeReview: ctx.autoModeReview } : {}),
                 });

package/dist/agents/subagent.d.ts

@@ -400,6 +400,7 @@ export declare function createSubagentResume(deps: {
         handsReadOnly?: true;
         interactiveTools?: false;
         oneShot?: true;
+        memoryPersistenceCapable?: false;
     };
     /** The RESUMING caller's own handback-review seat (its trusted `ToolExecuteContext.autoModeReview`),
      *  same turn-bound reasoning as `currentOnQuestion` above: a resumed cycle is a completion like any

package/dist/agents/subagent.js

@@ -522,6 +522,9 @@ export function createSubagentResume(deps) {
                 ...(entry.specSnapshot.handsReadOnly === true || deps.currentClamps?.handsReadOnly === true ? { handsReadOnly: true } : {}),
                 ...(entry.specSnapshot.interactiveTools === false || deps.currentClamps?.interactiveTools === false ? { interactiveTools: false } : {}),
                 ...(entry.specSnapshot.oneShot === true || deps.currentClamps?.oneShot === true ? { oneShot: true } : {}),
+                ...(entry.specSnapshot.memoryPersistenceCapable === false || deps.currentClamps?.memoryPersistenceCapable === false
+                    ? { memoryPersistenceCapable: false }
+                    : {}),
                 signal: abort.signal,
             };
             if (deps.registry !== undefined && deps.taskId !== undefined && deps.taskAccess !== undefined) {
@@ -1668,6 +1671,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             };
             const childThinking = def?.thinking ?? ctx.thinkingLevel;
             const provenanceAgentName = agentName ?? def?.name;
+            const childMemoryPersistenceCapable = ctx.memoryPersistenceCapable === false ? false : (def?.memoryPersistenceCapable ?? ctx.memoryPersistenceCapable);
             const childOnAsk = ctx.onAsk !== undefined
                 ? withDelegationProvenance(ctx.onAsk, {
                     parentToolCallId: ctx.toolCallId,
@@ -1689,6 +1693,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(ctx.onQuestion !== undefined ? { onQuestion: ctx.onQuestion } : {}),
                 ...(ctx.interactiveTools === false ? { interactiveTools: false } : {}),
                 ...(ctx.handsReadOnly === true ? { handsReadOnly: true } : {}),
+                ...(childMemoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: childMemoryPersistenceCapable } : {}),
                 ...(ctx.oneShot === true ? { oneShot: true } : {}),
                 ...(ctx.clientContext !== undefined ? { clientContext: ctx.clientContext } : {}),
                 ...(ctx.excludeTools !== undefined ? { excludeTools: [...ctx.excludeTools] } : {}),

package/dist/core/checkpoint-store.d.ts

@@ -135,6 +135,11 @@ export interface RiskDescriptor {
      *  attempted — over-reaching a shell parse risks a wrong/forgeable path). Each path `inlineUntrusted`-capped.
      *  Omitted when none derivable. */
     touchedPaths?: string[];
+    /** #144 (additive): a persisted allow rule MATCHED this call but could not clear the mandated ask —
+     *  the matched rule text (`inlineUntrusted`-capped), threaded to the mint so the durable-park route
+     *  carries the same disclosure the synchronous ask does. The inbox renders "their rule is alive,
+     *  just outranked" instead of the person concluding their rule silently broke. */
+    shadowedRule?: string;
 }
 /**
  * design/80 §D-E: the DETERMINISTIC severity tier (1..5) for an escalation checkpoint, a PURE function of the
@@ -266,6 +271,8 @@ export declare function buildRiskDescriptor(input: {
     shellGated?: boolean;
     /** The resolved doctrine to persist when `shellGated` (see {@link RiskDescriptor.shellGateDoctrine}). */
     shellGateDoctrine?: "classify" | "always";
+    /** #144: the matched-but-outranked persisted rule to persist (see {@link RiskDescriptor.shadowedRule}). */
+    shadowedRule?: string;
 }): RiskDescriptor;
 /**
  * #130/#131/#120 (2026-08-10) — the durable record of an ask's `requiresRealApproval` bit, which used
@@ -805,8 +812,11 @@ export interface CheckpointState {
          * (extra deny-narrowing layers + the pre-CAS edit re-adjudication) rather than trusting a
          * re-supplied policy's execution half for the frozen deny data — a re-supplied closure that
          * matches the digest but behaves differently cannot un-deny what the suspend froze. Present iff
-         * `requiresParentConstraint` on new mints; absent on older checkpoints (⇒ no frozen deny data —
-         * the count-only contract governs, and an EDIT resume is refused for want of a validatable chain). */
+         * `requiresParentConstraint` on new mints; absent on PRE-F-012 checkpoints (⇒ no frozen deny data —
+         * the count-only contract governs, and an EDIT resume is refused for want of a validatable chain).
+         * "Older" is version-decidable, not guessed: chain, digest and the {@link F012_CHECKPOINT_VERSION}
+         * stamp are one write, so on a v7+ row the pair is REQUIRED — its absence there is a damaged row and
+         * the resume ladder refuses it pre-CAS rather than falling back to the count-only contract. */
         constraintChain?: ReadonlyArray<import("./tool-policy.js").ConstraintChainEntry>;
         /**
          * F-012 L1 — the content digest over `constraintChain` ({@link import("./tool-policy.js").constraintChainDigest}):
@@ -814,7 +824,8 @@ export interface CheckpointState {
          * content. The resume pre-CAS ladder recomputes the digest over the RE-SUPPLIED chain's
          * projections and rejects a mismatch (`resume.parent_constraint_mismatch`) — replacing the
          * count-only shape check with a content contract (a same-length chain of different frozen deny
-         * data no longer passes). Present iff `constraintChain` is. */
+         * data no longer passes). Present iff `constraintChain` is — and on a v7+ row both are required
+         * (see {@link constraintChain}: the pair and the version stamp are minted together). */
         constraintDigest?: string;
     };
     /**
@@ -940,7 +951,11 @@ export declare const F012_CHECKPOINT_VERSION = 7;
  * either redeem a governed row with no org wiring at all (#120's exact hole, replayed through version
  * skew) or burn the approval on the unavailable belt the bit exists to soften. Stamping v8 forces it
  * to reject PRE-CAS (`unsupported_version`, stays `pending`, retried on an enforcing worker). A gate
- * with NO `realApproval` keeps the historic stamps — ungoverned deployments see zero version movement.
+ * with NO `realApproval` keeps the historic stamps. NOTE (erratum 2026-08-10, downstream-measured):
+ * "zero version movement for ungoverned deployments" is TOO WIDE — the two always-mounted integrity
+ * policies (transcript-integrity, unverifiable-delete) mint `requiresRealApproval` asks, so a park on
+ * one of THOSE stamps v8 with `origin:"policy"` on ANY durable deployment, org-governed or not. What
+ * stays true: rows whose gate carries no realApproval bit keep their historic stamps everywhere.
  */
 export declare const REAL_APPROVAL_CHECKPOINT_VERSION = 8;
 /** The highest {@link Checkpoint.version} `runner.resume` will act on; a higher one is rejected pre-CAS with
@@ -1463,8 +1478,8 @@ export declare class CheckpointError extends Error {
      *  computable from a self-reported closure, so the edited resume is refused typed pre-CAS (the
      *  checkpoint stays `pending`, still decidable); an UNEDITED approval is untouched. */
      | "resume.constraint_unprojectable";
-    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Today one
-     *  member: `field` names WHICH part of the decision payload was rejected on a
+    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Two
+     *  members. `field` names WHICH part of the decision payload was rejected on a
      *  `checkpoint.invalid_outcome` — `"boundCallId"` (the action you decided on has been replaced:
      *  re-fetch the pending list), `"boundInputHash"` (the input you reviewed has changed under the same
      *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
@@ -1476,6 +1491,18 @@ export declare class CheckpointError extends Error {
      *  discriminant. */
     readonly detail?: {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
+        /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
+         *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is
+         *  damaged/forged and no worker ever will" — blanket-retriable and gate-shape heuristics were
+         *  both refuted downstream, so the throw site carries the fact it always knew). Closed set;
+         *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
+         *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
+         *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
+         *     (retryable on an org-wired worker).
+         *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
+         *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
+         *     current bytes — no worker version redeems a damaged row). */
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "constraint_chain_missing";
     } | undefined;
     constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found"
     /** `runner.resume` was handed an {@link ResumeOutcome} whose `gate` arm does not match the
@@ -1572,8 +1599,8 @@ export declare class CheckpointError extends Error {
      *  computable from a self-reported closure, so the edited resume is refused typed pre-CAS (the
      *  checkpoint stays `pending`, still decidable); an UNEDITED approval is untouched. */
      | "resume.constraint_unprojectable", message: string, 
-    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Today one
-     *  member: `field` names WHICH part of the decision payload was rejected on a
+    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Two
+     *  members. `field` names WHICH part of the decision payload was rejected on a
      *  `checkpoint.invalid_outcome` — `"boundCallId"` (the action you decided on has been replaced:
      *  re-fetch the pending list), `"boundInputHash"` (the input you reviewed has changed under the same
      *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
@@ -1585,6 +1612,18 @@ export declare class CheckpointError extends Error {
      *  discriminant. */
     detail?: {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
+        /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
+         *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is
+         *  damaged/forged and no worker ever will" — blanket-retriable and gate-shape heuristics were
+         *  both refuted downstream, so the throw site carries the fact it always knew). Closed set;
+         *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
+         *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
+         *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
+         *     (retryable on an org-wired worker).
+         *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
+         *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
+         *     current bytes — no worker version redeems a damaged row). */
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "constraint_chain_missing";
     } | undefined);
 }
 /**

package/dist/core/checkpoint-store.js

@@ -120,6 +120,7 @@ export function buildRiskDescriptor(input) {
             axes,
             toolName,
             ...(input.shellGated && input.shellGateDoctrine !== undefined ? { shellGateDoctrine: input.shellGateDoctrine } : {}),
+            ...(input.shadowedRule !== undefined ? { shadowedRule: inlineUntrusted(input.shadowedRule, 200) } : {}),
             ...(summary !== undefined ? { summary } : {}),
             ...(touchedPaths !== undefined ? { touchedPaths } : {}),
         };

package/dist/core/hooks.d.ts

@@ -608,7 +608,10 @@ export interface ToolGateInput {
      *  auto-approve what only judgment may clear). `origin` records whether the bit came from an org
      *  ASK rule, from the org-unavailable tighten (whose resume semantics differ — see
      *  {@link import("./checkpoint-store.js").RealApprovalGateBit}), or from a policy/hook. */
-    realApproval?: import("./checkpoint-store.js").RealApprovalGateBit) => Promise<ToolGateResult["suspend"] | ParkAttemptFailed | undefined>;
+    realApproval?: import("./checkpoint-store.js").RealApprovalGateBit, 
+    /** #144: the matched-but-outranked persisted rule (the surviving ask's `persistedRuleShadowed`)
+     *  — threaded so the park mint's risk descriptor carries the disclosure on the durable route. */
+    shadowedRule?: string) => Promise<ToolGateResult["suspend"] | ParkAttemptFailed | undefined>;
     /**
      * design/174 — route a policy `ask` on the reserved question tool to this run's CONTENT-ask channel
      * before it can become a park or a refusal. Called in the `ask` branch with the FINAL post-hook,
@@ -728,10 +731,14 @@ export interface ToolGateInput {
      *  · the reserved question tool and a call MARKED unresolvable are excluded for the same reason the
      *    classifier excludes them: both contracts require that no synchronous decision-maker stands between
      *    the ask and the park / content route, and this lane is one.
-     * What it DOES consume is the egress and irreversibility/shellGate tightens and unmarked bare asks —
-     * deliberately, because a deployment forcing shell classification is exactly where the feature is for.
-     * Consuming such an ask also skips the park it would have minted; that IS what a standing approval
-     * means, and the first bullet is what keeps an integrity ask out of that set.
+     *  · #144 (ruled): a MANDATED ask is never consumed — an operator's shellGate:"always" tier and a
+     *    tool's own egress/irreversibility marks are structural requirements, not classifier hesitation
+     *    ("allow rules silence the classifier's questions, never a mandated one"). When a rule matches
+     *    but cannot clear, the surviving ask discloses it (message + `persistedRuleShadowed`).
+     * What it DOES consume is the classify-DOCTRINE shell ask (the coarse tier "maybe" — the
+     * don't-ask-again main case this feature exists for) and unmarked bare asks. Consuming such an ask
+     * also skips the park it would have minted; that IS what a standing approval means, and the
+     * bullets above are what keep integrity/hook/mandated asks out of that set.
      */
     persistedRules?: {
         /** The canonical text of the rule that admits this call, or `undefined`. Must not throw: a store that

package/dist/core/hooks.js

@@ -315,6 +315,15 @@ export async function runToolGate(input) {
             currentInput = policyRewrite;
             req.args = policyRewrite;
         }
+        const persistedRuleMandate = input.egress === true
+            ? "tool_marks"
+            : input.shellGated === true
+                ? input.irreversibility === "always"
+                    ? "operator_always"
+                    : undefined
+                : input.irreversibility === "always" || input.irreversibility === "maybe"
+                    ? "tool_marks"
+                    : undefined;
         if (input.persistedRules &&
             !orgRealApprovalRequired &&
             decision.action === "ask" &&
@@ -323,7 +332,7 @@ export async function runToolGate(input) {
             req.toolName !== ASK_USER_QUESTION_TOOL_NAME &&
             input.isMarkedUnresolvable?.(input.event.toolCallId) !== true) {
             const hit = await input.persistedRules.admits(req).catch(() => undefined);
-            if (hit !== undefined) {
+            if (hit !== undefined && persistedRuleMandate === undefined) {
                 decision = {
                     action: "allow",
                     message: `a persisted allow rule (${hit}) covers this call`,
@@ -332,6 +341,15 @@ export async function runToolGate(input) {
                 };
                 await notifier.notifyAsync(() => input.persistedRules?.onResolved?.({ toolName: req.toolName, toolCallId, rule: hit }), "toolGate.persistedRuleResolved");
             }
+            else if (hit !== undefined) {
+                const shownRule = inlineUntrusted(hit, 200);
+                const mandateNoun = persistedRuleMandate === "operator_always" ? "this deployment mandates per-call confirmation for shell commands (shellGate: always)" : "this tool carries egress/irreversibility marks (a mandated confirmation a rule cannot clear)";
+                decision = {
+                    ...decision,
+                    persistedRuleShadowed: shownRule,
+                    message: `${decision.message !== undefined ? `${decision.message} ` : ""}(a persisted allow rule (${shownRule}) matches this call but does not clear the ask — ${mandateNoun})`,
+                };
+            }
         }
         if (input.autoMode &&
             !orgRealApprovalRequired &&
@@ -390,7 +408,7 @@ export async function runToolGate(input) {
             ? { origin: orgAskOrigin !== undefined ? `org_${orgAskOrigin}` : "policy" }
             : undefined;
         if (suspendAsk && decision.action === "ask") {
-            const suspended = await suspendAsk(req, currentInput, safety, undefined, realApprovalOf(decision));
+            const suspended = await suspendAsk(req, currentInput, safety, undefined, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined);
             if (suspended) {
                 if ("parkFailed" in suspended)
                     parkFailed = suspended.parkFailed;
@@ -409,7 +427,7 @@ export async function runToolGate(input) {
                     req.args = outcome.presentedInput;
                 }
                 if (suspendAsk && outcome.parkDeclined && parkFailed === undefined) {
-                    const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(decision));
+                    const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined);
                     if (suspended) {
                         if ("parkFailed" in suspended)
                             parkFailed = suspended.parkFailed;
@@ -437,7 +455,7 @@ export async function runToolGate(input) {
             const resolved = await resolveAsk(decision, req);
             decision = resolved;
             if (resolved.action === "deny" && resolved.approverUnavailable === true && suspendAsk && parkFailed === undefined) {
-                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve));
+                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined);
                 if (suspended) {
                     if ("parkFailed" in suspended)
                         parkFailed = suspended.parkFailed;

package/dist/core/memory-engine/dual-root.js

@@ -31,13 +31,15 @@ export function mergeInjections(project, personal) {
     if (!personal)
         return project;
     const instruction = project.instruction || personal.instruction;
+    const readOnlyNotice = instruction === "" && project.readOnlyNotice !== undefined && personal.readOnlyNotice !== undefined ? project.readOnlyNotice : undefined;
     const indexParts = [project.index, personal.index].filter((s) => Boolean(s && s.trim()));
     const announcements = [...(project.announcements ?? []), ...(personal.announcements ?? [])];
     const announceParts = [project.announceBlock, personal.announceBlock].filter((s) => Boolean(s && s.trim()));
-    const blockParts = [instruction, ...indexParts, ...announceParts];
+    const blockParts = [instruction || readOnlyNotice, ...indexParts, ...announceParts];
     const indexSeed = project.indexSeed ?? personal.indexSeed;
     return {
         instruction,
+        ...(readOnlyNotice !== undefined ? { readOnlyNotice } : {}),
         ...(indexParts.length > 0 ? { index: indexParts.join("\n\n") } : {}),
         ...(announcements.length > 0 ? { announcements } : {}),
         ...(announceParts.length > 0 ? { announceBlock: announceParts.join("\n\n") } : {}),

package/dist/core/memory-engine/engine.d.ts

@@ -40,6 +40,37 @@ export declare const MEMORY_RECALL_DISCIPLINE = "Before answering questions abou
  * would forge the very account the three-tier discipline forbids forging).
  */
 export declare const MEMORY_PREFERENCE_DISCIPLINE = "When the user confirms a stored preference or fact still holds, refresh that entry's `last-confirmed: <YYYY-MM-DD>` frontmatter line (add it when absent). When you save a preference, add an `applies-when: <context>` frontmatter line naming when it applies. Both are plain frontmatter lines \u2014 write them yourself; nothing fills them in for you.";
+/**
+ * Corrections for announcement segments that carry store-mutation guidance ("record a fresh entry …
+ * tombstone the old one", minted in an earlier writable session) a session cannot act on. The queue
+ * items are opaque strings (rewriting them would be text surgery over minted-at-enqueue wording),
+ * so the correction is a trailing coda, not a rewrite — in two scopes, because the two mounting
+ * seats speak about different things (an unqualified "the memory store is not writable" beside
+ * another, WRITABLE plane's instruction would negate that plane's guidance):
+ * - PLANE scope, attached by `inject()` right after a read-only layering's own announcement block:
+ *   explicitly local to the immediately preceding notices, so a mixed dual-root merge keeps the
+ *   writable plane's instruction and announcements fully actionable.
+ * - SESSION scope, attached by the runner at the block tail when the whole session cannot persist:
+ *   there is no writable instruction left standing there (it is replaced or absent), so the global
+ *   wording is accurate. Name-free by construction (#181 class).
+ */
+export declare const MEMORY_ANNOUNCEMENT_READONLY_PLANE_CODA = "The notices immediately above concern a READ-ONLY memory store: any guidance in them to record, update, or tombstone an entry cannot be applied to that store this session \u2014 surface it to the user instead of claiming it done.";
+export declare const MEMORY_ANNOUNCEMENT_READONLY_CODA = "The memory store itself is not writable this session, so any guidance above to record, update, or tombstone a memory entry cannot be applied here \u2014 surface it to the user instead of claiming it done.";
+/**
+ * The read-only counterpart of the `# Memory` write instruction. A run with memory mounted but no
+ * way to write it used to get an EMPTY instruction — correct in what it doesn't teach, but silent
+ * about the state itself, and a model asked "remember X" under that silence answers with a success
+ * receipt for a save that never happens (the confabulated-receipt shape). This section states the
+ * state instead. Mounted only where "you cannot save" is provably TRUE: by `inject()` for a
+ * read-only layering (writeScope null ⇒ chmod'd tree), and by the runner for handsReadOnly (the
+ * shell rides the read-only band), for a declared-unavailable session (`memoryPersistenceCapable:
+ * false` — where the runner's write gate also refuses the file channel, keeping the engine-refusal
+ * sentence true), and for a write-less roster the persistence inference cannot vouch for. A merely
+ * Write-less roster does NOT qualify — other tools can still write the root. Name-free by
+ * construction (#181 class — it names no tool), and NOT part of the CC-verbatim capture: CC has no
+ * read-only memory layering, so there is nothing to capture; the section is sema-authored.
+ */
+export declare const MEMORY_READONLY_NOTICE = "# Memory\n\nYou have READ-ONLY access to persistent memory in this session: stored notes are available below, but this session has no memory write channel \u2014 the engine will not accept writes into the memory store. If the user asks you to remember something for later, say plainly that you cannot save it in this session \u2014 never claim to have noted or remembered it.";
 /** CC index-injection parameters: MEMORY.md's first 200 lines / 25KB enter the prompt. */
 export declare const MEMORY_INDEX_MAX_LINES = 200;
 export declare const MEMORY_INDEX_MAX_BYTES: number;
@@ -105,6 +136,16 @@ export interface MemoryInjection {
     /** CC `# Memory` section (system-authority instruction — §0.3 逐字 surface). Empty for a read-only
      *  layering (no write channel to instruct). */
     instruction: string;
+    /** Present exactly when this is a read-only LAYERING (writeScope null — the tree is chmod'd
+     *  read-only, so no tool writes into it whatever the roster): the {@link MEMORY_READONLY_NOTICE}
+     *  section stating that memory cannot be saved to, so the model declines "remember X" instead of
+     *  issuing a confabulated success receipt. NOT set for `writeToolMounted:false` over a writable
+     *  scope — there only the instruction-named tool is absent, other roster tools can still write the
+     *  root, and the claim would be false (the runner mounts the notice for its own provably
+     *  write-less shape, handsReadOnly). Kept as its OWN member (not folded into `instruction`) so the
+     *  dual-root merge's "the write plane's instruction wins" falsy-OR keeps working: a read-only
+     *  plane must never outrank a write plane's instruction. */
+    readOnlyNotice?: string;
     /** The derived MEMORY.md index, truncated (200 lines / 25KB) and FENCED untrusted. Undefined when empty. */
     index?: string;
     /** design/138 S2-B (时机①) — the announcements DRAINED by this inject (queued by the previous
@@ -301,7 +342,7 @@ export declare class MemoryEngine {
         ok: true;
     } | {
         ok: false;
-        code: ScanFinding["code"];
+        code: ScanFinding["code"] | "read_only_layering";
         reason: string;
         muted: boolean;
     };
@@ -315,6 +356,9 @@ export declare class MemoryEngine {
             reason: string;
         };
         sessionId?: string;
+        admitNothing?: {
+            reason: string;
+        };
     }): Promise<HarvestReport>;
     private harvestCore;
     /**