@sema-agent/core 5.25.0 → 5.27.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## 5.27.0 — 2026-08-11
+
+No API-BREAKING changes (exports grow only). Narrowings are tighten-direction and named below.
+
+### Narrowed (behavior, ruled)
+
+- **A declared-unavailable session reads the committed memory view.** Under
+  `memoryPersistenceCapable: false`, materialize/search/harvest serve the committed account
+  (ledger + shadow): disk divergence with no transaction backing is neither adopted nor served —
+  it stays on disk, is loudly reported (`restricted_divergence`, a new `HarvestRejectionCode`
+  member — consumers pinning that enum as a closed set must add the row), and a later unrestricted
+  session adopts it through the normal gates. Legitimate flows are untouched: user hand-edits and
+  git-pull drops keep working (deferred, not destroyed), a concurrent writable session's committed
+  changes pass as transaction-backed, and **a writeScope-null plane (org layers default read-only;
+  the dual-root non-write plane) keeps its ordinary adopt-on-read semantics** — the restriction is
+  the SESSION's declaration, never the plane's structure.
+- **Rule suggestions appear only where a persisted rule could actually work.** Mandated
+  (`shellGate:"always"` / tool marks / org / requiresRealApproval), shadowed, hook-originated,
+  inherited-unresolved, ancestor-resolved (a live parent approver), and anonymous-task (no
+  principal, no local-owner declaration) asks no longer carry `ruleSuggestions` — a card whose rule
+  could never silence it stops offering to mint one. Classifier-tier and ordinary policy asks keep
+  their suggestions.
+- **Known residual (registered)**: bytes refused by a restricted session remain on disk and are
+  adoptable by a later unrestricted session — the alternative (destroying bytes indistinguishable
+  from user edits) is ruled out; the boundary is "the restricted session is never polluted and
+  tampering is always visible", not "the bytes can never enter".
+
+### Added
+
+- **Prefix rule candidates**: the suggestion engine mints a reviewed PREFIX option beside the exact
+  one for lexicon-listed command bodies (`git push origin main` → optional `Bash(git push:*)`),
+  longest word-boundary hit, no fallback; candidate arrays grow from ≤1 to ≤2 with `exact` fixed at
+  index 0 (a documented contract across `AskRequest.ruleSuggestions`, checkpoint park rows, and the
+  approval card record). Consumers reading `[0]` unconditionally only miss the new option.
+- **CJK lexical retrieval**: `termSet` now mints CJK character bigrams and unigrams beside
+  alphanumeric runs — a pure-Chinese memory entry was previously INVISIBLE to the File backend's
+  lexical rung (empty term set); the class is written in explicit escapes (a literal compat
+  ideograph NFC-folds to its unified twin, silently widening the range).
+- **`toolResultContentSegment` exported** from the package root (the digest segment the engine's
+  own mints carry — consumers derive it instead of inventing a placeholder).
+- `MemoryEngine.materialize` accepts an optional `adoptionRestricted` verdict;
+  `MemorySessionHandle.adoptionRestricted` reports it (both additive).
+
+### Fixed
+
+- Three loaded-suite timing margins widened without losing discrimination; the defectscan
+  guardrail audit skips a concurrently-vanished temp dir instead of throwing; 24 stale doc/JSDoc
+  claims restated to actual behavior (bidirectional sweep + rescan trio).
+
+## 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

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/agent-transcript-tool.d.ts

@@ -37,8 +37,11 @@ export interface AgentTranscriptToolOptions {
  * into a child's tail when the residual isn't enough.
  *
  * Safety: reads are bounded to the parent's OWN lineage — the same non-leaking registry access scope as
- * SendMessage/TaskOutput (an unknown or out-of-scope id reads identically to "not found"). Only a
- * RETAINED child's session survives to be read; a throwaway child returns an honest "not retained".
+ * SendMessage/TaskOutput (an unknown or out-of-scope id reads identically to "not found"). Two read
+ * paths keep a child's session reachable: the retain ledger (a RETAINED child), and the durable
+ * agent-store fallback (`agentStore` wired + accessible row + preserved `sessionId` — readable even
+ * with retain off/expired/evicted). Only when BOTH miss does the call return the honest
+ * "not retained" / "not found".
  */
 export declare function createAgentTranscriptTool(opts: AgentTranscriptToolOptions): import("../internal/harness-types.js").AgentTool<Type.TObject<{
     id: Type.TString;

package/dist/agents/agent-transcript-tool.js

@@ -16,7 +16,8 @@ export function createAgentTranscriptTool(opts) {
         description: `Read the recent tool steps of a background agent you launched (task_id 'a…' from the Agent tool with ` +
             `run_in_background), so you can see precisely where it got to — useful before SendMessage-ing a follow-up, ` +
             `or to inspect a stopped agent's tail. Returns the last N steps (tool, target, outcome); it does not re-run ` +
-            `the agent. Only works for agents this run retained (retainSubagentSessions); otherwise you get an honest error.`,
+            `the agent. Works for agents this run retained (retainSubagentSessions) and for agents whose durable ` +
+            `record preserved their transcript session; when neither holds you get an honest error.`,
         parameters: Type.Object({
             id: Type.String({ description: "The background agent's task_id (a…) returned by the Agent tool." }),
             lastN: Type.Optional(Type.Integer({ minimum: 1, maximum: AGENT_TRANSCRIPT_MAX_N, description: `How many recent steps to return (default ${AGENT_TRANSCRIPT_DEFAULT_N}).` })),

package/dist/agents/send-message-tool.d.ts

@@ -19,7 +19,10 @@ export interface SendMessageToolOptions {
     owner?: string;
     scope?: string;
     sessionId?: string;
-    /** Deployment-level background-notify sink — the resumed run's completion rides the existing chain. */
+    /** Completion-notify sink for the resumed run. The Runner mount wires the SENDING run's own
+     *  notification injector here (its runtask-wrapped `injectTaskNotification`), so the completion
+     *  notice lands in the sender's live injection queue at a turn boundary; a direct mount may wire a
+     *  deployment-level background-notify sink instead. Absent ⇒ completion is silent. */
     notify?: (n: TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;

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

@@ -361,8 +361,11 @@ export interface SubagentSteerHandle {
  * before any await; rolled back on pre-launch failure) → session exists AND non-empty (r1-m1).
  * Then: fenced revive prompt (unpredictable marker) →
  * `runTaskStream` on the FROZEN spawn snapshot + `requireExistingSession` (spec is tighten-only: the caller
- * contributes ONLY `content`) → ledger `activeRun` bookkeeping → completion via the deployment-level
- * background-notify sink ONLY (no sink ⇒ silent; NEVER the parent-model notification lane — r1-M5).
+ * contributes ONLY `content`) → ledger `activeRun` bookkeeping → completion announced through
+ * `deps.notify` (no sink ⇒ silent). Which lane
+ * that is depends on the mount: the background Agent lane wires the deployment-level background-notify
+ * sink, while the SendMessage mount wires the SENDING run's own notification injector — there the
+ * completion notice lands in the sender's live injection queue at its next turn boundary.
  */
 export declare function createSubagentResume(deps: {
     ledger: SubagentRetainLedger | undefined;
@@ -400,6 +403,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

@@ -574,8 +574,13 @@ export type PendingAction = {
     /** design/179 §4 (additive) — the persistable allow-rule forms this parked call could be covered by,
      *  minted from the SAME post-hook args the row executes. Advisory display metadata for the approval
      *  inbox's "stop asking me this" option; never read by the resume path, and never a rule by itself
-     *  (minting one goes through the approval-record protocol). Absent when no rule lane is armed or the
-     *  command is one the lane cannot speak for. */
+     *  (minting one goes through the approval-record protocol). Absent when no rule lane is armed, the
+     *  command is one the lane cannot speak for, or the parked ask is one a persisted rule could not
+     *  clear (mandated marks / a real-approval demand / a shadowed matching rule).
+     *  CONTRACT (same as the synchronous `AskRequest.ruleSuggestions`) — array order is display order,
+     *  narrowest first: the EXACT form is always index 0, a broader reviewed PREFIX form (at most one)
+     *  follows; basis ≤ 2, and selection/ticket indices are keyed against this order. A row persisted
+     *  before the prefix arm existed carries ≤ 1 entry and stays valid under the same reading. */
     ruleSuggestions?: readonly import("./permission-rule-model.js").RuleSuggestion[];
     /**
      * design/80 D-1 §2 (slice 1a.2): the server-minted **opaque** boundInputHash of {@link args} — a

package/dist/core/hooks.d.ts

@@ -1,10 +1,10 @@
 import type { DocumentContent, ImageContent, TextContent } from "../internal/llm.js";
 import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../internal/harness-types.js";
-import type { PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
+import type { DecisionReason, PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
 import { type AskClass } from "./ask-class.js";
 /**
- * In-process hook seam (design/37) — a small, provider-agnostic interception layer modeled on CC's
- * hooks but reduced to three process-internal callbacks (no shell/HTTP executors, no settings files):
+ * In-process hook seam (design/37) — a provider-agnostic interception layer modeled on CC's hooks,
+ * kept process-internal (no shell/HTTP executors, no settings files). The original tool-call trio:
  *
  *  - {@link Hooks.preToolUse} runs before a tool executes. It may **rewrite** the args (an `allow` with
  *    `updatedInput`), **restrict** the call (`deny`/`ask`), and/or inject `additionalContext`. It is a
@@ -15,6 +15,13 @@ import { type AskClass } from "./ask-class.js";
  *  - {@link Hooks.userPromptSubmit} runs before the objective becomes a user message. It may `block`
  *    submission (the task fails with a model-readable reason) or inject `additionalContext` ahead of it.
  *
+ * The seam has since grown well past the trio — each later member carries its own contract below:
+ * {@link Hooks.stop} / {@link Hooks.stopFailure} (run-end pushback / API-error terminal observer),
+ * {@link Hooks.postToolUseFailure} and {@link Hooks.postToolBatch} (failure + batch-boundary taps),
+ * {@link Hooks.preCompact} / {@link Hooks.postCompact} (compaction gate + observer),
+ * {@link Hooks.permissionDenied} (deny observer), and the {@link Hooks.preToolUseObservational}
+ * declaration flag.
+ *
  * All feedback the model should see (a block reason, injected context) is wrapped as a
  * `<system-reminder>` via {@link formatHookFeedback} so the model can read and self-correct.
  */
@@ -611,7 +618,12 @@ export interface ToolGateInput {
     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>;
+    shadowedRule?: string, 
+    /** The surviving ask's `decisionReason` — threaded so the park mint's rule-suggestion door can
+     *  read the ask's origin on the durable route exactly as the synchronous mints read it off the
+     *  decision (a hook-raised ask is one no persisted rule may clear, so its parked card must not
+     *  offer to mint one). */
+    askDecisionReason?: DecisionReason) => 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,
@@ -871,6 +883,29 @@ export interface ToolGateInput {
  * reach the same lane from inside a descendant's fold.
  */
 export declare function createPreToolUseConstraintPolicy(preToolUse: NonNullable<Hooks["preToolUse"]>, env?: HookEnvCapabilities, onCrash?: (err: unknown) => void): ToolPolicy;
+/**
+ * The mandate provenance of one call, judged from the SAME mark inputs the gate is driven with —
+ * the single source for "could a persisted allow rule clear this ask?". Allow rules silence the
+ * classifier's questions, never a mandated one, and this predicate is the mandated-family half of
+ * that boundary (the real-approval/governance half rides the decision's own `requiresRealApproval`
+ * bit, which the org layer stamps):
+ *  · `egress` — the tool's own external-write mark, judged FIRST: it is the tool's declaration even
+ *    when the coarse doctrine also installed a shell tier on the same seat;
+ *  · `shellGated` + tier `"always"` — the operator's per-call confirmation doctrine
+ *    (`"operator_always"`); the classify doctrine installs `"maybe"`, and THOSE asks stay the rule
+ *    lane's home turf (`undefined`);
+ *  · a tool's OWN `"always"`/`"maybe"` irreversibility tier without the doctrine (`"tool_marks"`).
+ *
+ * Two consumers, one derivation: the gate's silencing arm (a matching rule is disclosed as shadowed
+ * instead of clearing the ask) and the runner's suggestion factory (a mandated ask offers no
+ * "stop asking me this" option — a rule minted from it would never clear it). A drift between the
+ * two would let a card offer a rule the lane then refuses to honor.
+ */
+export declare function persistedRuleMandateOf(marks: {
+    egress?: boolean;
+    shellGated?: boolean;
+    irreversibility?: "never" | "maybe" | "always";
+}): "operator_always" | "tool_marks" | undefined;
 /**
  * The design/37 **two-phase tool gate** — the single chokepoint that makes the load-bearing invariant
  * structural ("a hook's `allow` cannot bypass the policy's `deny`/`ask`"):

package/dist/core/hooks.js

@@ -161,6 +161,17 @@ function withProbeTimeout(p, ms, signal) {
         p.then((v) => done(resolve, v), (err) => done(reject, err));
     });
 }
+export function persistedRuleMandateOf(marks) {
+    return marks.egress === true
+        ? "tool_marks"
+        : marks.shellGated === true
+            ? marks.irreversibility === "always"
+                ? "operator_always"
+                : undefined
+            : marks.irreversibility === "always" || marks.irreversibility === "maybe"
+                ? "tool_marks"
+                : undefined;
+}
 export async function runToolGate(input) {
     const { event, preToolUse, adjudicate, resolveAsk, suspendAsk } = input;
     const { toolCallId, toolName } = event;
@@ -315,15 +326,7 @@ 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;
+        const persistedRuleMandate = persistedRuleMandateOf(input);
         if (input.persistedRules &&
             !orgRealApprovalRequired &&
             decision.action === "ask" &&
@@ -342,11 +345,12 @@ 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: hit,
-                    message: `${decision.message !== undefined ? `${decision.message} ` : ""}(a persisted allow rule (${hit}) matches this call but does not clear the ask — ${mandateNoun})`,
+                    persistedRuleShadowed: shownRule,
+                    message: `${decision.message !== undefined ? `${decision.message} ` : ""}(a persisted allow rule (${shownRule}) matches this call but does not clear the ask — ${mandateNoun})`,
                 };
             }
         }
@@ -407,7 +411,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), decision.action === "ask" ? decision.persistedRuleShadowed : undefined);
+            const suspended = await suspendAsk(req, currentInput, safety, undefined, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined);
             if (suspended) {
                 if ("parkFailed" in suspended)
                     parkFailed = suspended.parkFailed;
@@ -426,7 +430,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), decision.action === "ask" ? decision.persistedRuleShadowed : undefined);
+                    const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined);
                     if (suspended) {
                         if ("parkFailed" in suspended)
                             parkFailed = suspended.parkFailed;
@@ -454,7 +458,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), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined);
+                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.decisionReason : 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
@@ -280,7 +321,9 @@ export declare class MemoryEngine {
      *  eventId anchors on the pollution record (sessionId + marked-at), so however many times this
      *  settlement replays the same pollution event, the generation is allocated once. */
     private settlePromotions;
-    materialize(scopes: readonly string[], writeScope: string | null): Promise<MemorySessionHandle>;
+    materialize(scopes: readonly string[], writeScope: string | null, opts?: {
+        adoptionRestricted?: boolean;
+    }): Promise<MemorySessionHandle>;
     inject(handle: MemorySessionHandle, opts?: {
         writeToolMounted?: boolean;
     }): MemoryInjection;
@@ -301,7 +344,7 @@ export declare class MemoryEngine {
         ok: true;
     } | {
         ok: false;
-        code: ScanFinding["code"];
+        code: ScanFinding["code"] | "read_only_layering";
         reason: string;
         muted: boolean;
     };
@@ -315,16 +358,20 @@ export declare class MemoryEngine {
             reason: string;
         };
         sessionId?: string;
+        admitNothing?: {
+            reason: string;
+        };
     }): Promise<HarvestReport>;
     private harvestCore;
     /**
      * @param keepBaseline RB-440 (2026-07-31, hardening probe P3) — relative paths whose baseline must NOT
      * advance: the files a DEGRADED harvest deferred (`report.degraded.pending`).
      *
-     * The deferral contract at :659-665 promises "the REST is deferred to the next harvest (still on disk),
-     * never dropped", but execution then continued into this scan, which re-baselined EVERY file carrying an
-     * id — the pending ones included — writing the CURRENT disk rev into `handle.baseRevs`. The next harvest
-     * hit the unchanged-baseline fast path at :679 and skipped the file FOREVER: the deferred edit never
+     * The deferral contract in the harvest scan (the budget/deadline arm — see `harvestDeadlineMs`)
+     * promises "the REST is deferred to the next harvest (still on disk), never dropped", but execution
+     * then continued into this scan, which re-baselined EVERY file carrying an id — the pending ones
+     * included — writing the CURRENT disk rev into `handle.baseRevs`. The next harvest hit the harvest
+     * scan's unchanged-baseline fast path and skipped the file FOREVER: the deferred edit never
      * became a patch. Session-NEW files escaped it (no id ⇒ `continue` below), which is exactly why the
      * existing budget test passed. Measured with a copy-out backend: harvest#1 {update:1} + pending ["b.md"],
      * harvest#2 {update:0}, and the backend still held v1 — so the next `materialize` wrote the stale text