@sema-agent/core 5.26.0 → 5.28.0

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## 5.28.0 — 2026-08-12
+
+No API-BREAKING changes (exports grow only). Narrowings are tighten-direction and named below.
+
+### Narrowed (behavior, ruled)
+
+- **A hook-promoted ask's provenance is stamped, never read back.** Every consumption point keying
+  on `decisionReason === "hook"` now reads an engine-stamped value: the fold reconstructs the
+  promoted ask from an explicit member whitelist and stamps `"hook"` unconditionally, so a hook
+  self-declaring any other word (or extra members like `persistedRuleShadowed`) cannot change how
+  the persisted-rule lane, the rule-suggestion factory, or the inherited-frame reuse treat the ask.
+- **A `decisionReason` outside the closed set is refused at the consumption screen.** A
+  deployment-authored `ToolPolicy.check` returning an unrecognized word (or routing the field
+  through a getter/prototype) is denied fail-closed with the closed set named; plain decisions pass
+  by reference. The HOOK seam is exempt by design (the field is a documented non-input there — see
+  the stamp above).
+- **The served org snapshot meets the same validator as a fetched one.** A persisted last-known-good
+  snapshot carrying a rule the current validator refuses now fails closed during a provider outage
+  instead of serving partial policy.
+- **Legacy rule text the current validator refuses no longer stalls sync.** A shape-whole tombstone
+  whose TEXT is refused gets the new closed-set reason `invalid_rule_text` — disclosed, quarantined,
+  and no longer withholding the whole inbound-adds round (safe: tombstones match byte-identical
+  text only, and an add with that text is refused by the same predicate).
+- **Case-colliding scope directories are refused loudly on case-insensitive filesystems.** Two
+  scopes differing only by case no longer silently share one physical directory (macOS/Windows);
+  collision detection compares folded identity (dev:ino-keyed), with lazy real probing instead of
+  platform guessing.
+- **Spill provenance is session-only, and a failing spill degrades instead of poisoning.** The agent
+  spill write points stamp `{sessionId}` (matching the offload/budget/compaction form); a failed or
+  conflicting spill put defers to a sibling-proven ref or reports honestly — a legacy-shape row can
+  no longer make an agent result permanently unreadable (guarded put + generation guard + coherent
+  poll snapshot).
+
+### Added
+
+- `onNotice` structured notice seat (first two families: bash timeout, MATERIALIZE) — absent keeps
+  the `console.warn` text verbatim; a present non-function seat is announced once and falls back
+  loudly instead of silencing both channels.
+- `tool_end.errorCode` now reads both discriminator spellings — `details.code` first (string), then
+  `details.errorKind` — so loop-thrown error frames are classifiable; `code` wins when both exist.
+- `ToolResultStore.deleteBySession?` (optional member; File + in-memory implementations, not on the
+  scoped wrapper, not in the published contract kit) — returns `{ deleted, unattributable }`;
+  selection keys on recorded provenance, unowned rows are counted and never deleted. A put refused
+  over an orphan sidecar un-publishes its own content (pre-call state restored), and a damaged
+  re-published survivor is counted unattributable.
+- Adopt-on-read ledger writes are serialized behind the existing cross-process txn mutex (lock-free
+  probe fast path; divergence acquires the mutex, reloads the ledger from disk, and re-verifies
+  lock ownership at recovery, side-effect and commit points) — cross-process lost-update closed.
+- `runTaskStream` refuses an out-of-shape `resume` synchronously (a resume without `outcome` used to
+  hang `stream.result()` forever).
+- `docs/INTEGRATION-CORE.md` — the core→embedder contract document (event-frame per-key obligations,
+  code-vocabulary pointers, TaskResult matrix, resume/decide shapes, store optional-member table);
+  maintained per L3 release.
+- Rule-suggestion admission honesty (#174 adjacency): the suggestion factory keys on the stamped
+  provenance.
+
+### Fixed
+
+- Control-character gate: five bench probe arms now genuinely reach their claimed product paths;
+  the published B2 index-truncation curve was corrected to `[0, 0, 0.005, 0.602]` (the old counting
+  masked a real N200 loss).
+- `TaskResult.retryAfterMs` and `tool_end.errorCode` JSDoc corrected to match code (two accepted
+  codes; the errorKind fallback).
+
+## 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

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

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.
  */
@@ -410,6 +417,28 @@ export interface HookToolOutput {
 /**
  * A PreToolUse hook result: a {@link PermissionResult} (so a hook can `deny`/`ask`, or `allow` with an
  * `updatedInput` rewrite) plus optional `additionalContext` injected into the eventual tool result.
+ *
+ * **The provenance members are not hook-settable inputs** (#174). `decisionReason` is the ENGINE's account
+ * of which layer produced a verdict, and `persistedRuleShadowed` is the gate's own #144 disclosure that a
+ * stored rule matched without clearing the ask. The gate stamps both itself — a `decisionReason` on a hook
+ * result is DISCARDED (a hook ask always reads `"hook"` downstream), and a `persistedRuleShadowed` is
+ * dropped rather than rendered on an approval card as a rule no lane matched.
+ *
+ * Which of a hook's OTHER members reach the surviving decision depends on which fold arm ran, so read
+ * the arm, not a single list: an ask promoted from a policy `allow` is rebuilt from the hook's `message`,
+ * `requiresRealApproval` and `updatedInput`, while a hook ask folded BESIDE a policy ask contributes its
+ * message and its mandate to the policy's decision and leaves the policy's own rewrite in place (the
+ * hook's rewrite still reaches execution — through the gate's captured rewrite, not through the decision
+ * object). Both arms are at the `hookAsk` fold in {@link runToolGate}.
+ *
+ * `additionalContext` is on neither list and never was consumed as a decision member: it rides its own
+ * channel — collected into the gate's `preToolContext` as soon as the hook answers, whichever verdict it
+ * returned, and drained onto the tool result by the runner. DELIVERY is narrower than collection: the
+ * runner stashes the context only for a call that will EXECUTE, because a blocked or suspended call never
+ * reaches the result step that drains it and carries its own model-facing reason instead. The context
+ * formerly APPEARED on the promoted ask object as an undeclared property, because that fold spread the
+ * whole hook result; the concurrent arm never carried it, so the two arms disagreed on a member neither
+ * of them reads. Nothing in the engine reads it off a decision.
  */
 export type PreToolUseResult = PermissionResult & {
     additionalContext?: string;
@@ -611,7 +640,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 +905,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

@@ -98,7 +98,7 @@ function preToolUseCrashReason(subject, err) {
 function screenPreToolUseResult(r) {
     if (r === undefined)
         return undefined;
-    return refuseOutOfContractDecision(r);
+    return refuseOutOfContractDecision(r, { reasonIsNonInput: true });
 }
 export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash) {
     return brandPolicyAskClass({
@@ -125,6 +125,7 @@ export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash) {
                     action: "ask",
                     message: decisionText(r) ?? `approval required for "${req.toolName}" (inherited PreToolUse hook)`,
                     decisionReason: "hook",
+                    ...(r.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                     ...(r.updatedInput !== undefined ? { updatedInput: r.updatedInput } : {}),
                 };
             }
@@ -161,6 +162,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;
@@ -209,13 +221,31 @@ export async function runToolGate(input) {
     if ((decision.action === "allow" || decision.action === "ask") && decision.updatedInput !== undefined) {
         policyRewrite = decision.updatedInput;
     }
-    else if (hookAsk?.action === "ask" && hookAsk.updatedInput !== undefined) {
+    else if (hookAsk?.updatedInput !== undefined) {
         policyRewrite = hookAsk.updatedInput;
     }
     if (decision.action === "allow" && hookAsk) {
-        decision = { ...hookAsk, decisionReason: hookAsk.decisionReason ?? "hook" };
+        decision = {
+            action: "ask",
+            ...(hookAsk.message !== undefined ? { message: hookAsk.message } : {}),
+            decisionReason: "hook",
+            ...(hookAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+            ...(hookAsk.updatedInput !== undefined ? { updatedInput: hookAsk.updatedInput } : {}),
+        };
         denySource = "hook";
     }
+    else if (decision.action === "ask" && hookAsk) {
+        const hookMessage = hookAsk.message;
+        const foldedMessage = hookMessage !== undefined && hookMessage !== decision.message
+            ? `${decision.message !== undefined ? `${decision.message} ` : ""}(a PreToolUse hook also asks: ${hookMessage})`
+            : decision.message;
+        decision = {
+            ...decision,
+            decisionReason: "hook",
+            ...(foldedMessage !== undefined ? { message: foldedMessage } : {}),
+            ...(hookAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+        };
+    }
     if (input.egress && decision.action === "allow") {
         decision = {
             action: "ask",
@@ -315,15 +345,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" &&
@@ -408,7 +430,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;
@@ -427,7 +449,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;
@@ -455,7 +477,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/engine.d.ts

@@ -321,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;
@@ -365,10 +367,11 @@ export declare class MemoryEngine {
      * @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

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

@@ -323,9 +323,13 @@ export class MemoryEngine {
         catch {
         }
     }
-    async materialize(scopes, writeScope) {
+    async materialize(scopes, writeScope, opts) {
         ensureDirExists(this.memoryDir);
         ensureDirExists(this.controlDir);
+        const restricted = opts?.adoptionRestricted === true;
+        const readBackend = restricted
+            ? (this.backend.restrictedAdoptionView?.({ audit: true, writeScope }) ?? this.backend)
+            : this.backend;
         if (writeScope !== null)
             claimRootScope(this.controlDir, writeScope);
         const scopeDirs = new Map();
@@ -336,8 +340,8 @@ export class MemoryEngine {
         for (const [scope, dir] of scopeDirs)
             this.chmodScopeTree(dir, 0o755, 0o644, { excludeTopDirs: this.siblingScopeDirNames(dir, scope) });
         const allScopes = [...scopeDirs.keys()];
-        const headers = await this.backend.listHeaders(allScopes);
-        const entries = await this.backend.getByIds(headers.map((h) => h.id));
+        const headers = await readBackend.listHeaders(allScopes);
+        const entries = await readBackend.getByIds(headers.map((h) => h.id));
         const byScope = new Map();
         for (const e of entries) {
             const arr = byScope.get(e.scope) ?? [];
@@ -357,6 +361,7 @@ export class MemoryEngine {
             repoIndexTargets: new Map(),
             indexBaselineLines: 0,
             indexText: "",
+            ...(restricted ? { adoptionRestricted: true } : {}),
         };
         if (writeScope !== null)
             ensureDirExists(handle.writableRoot);
@@ -382,7 +387,8 @@ export class MemoryEngine {
                 const { deleted: _stubDrop, ...stubFm } = entry.frontmatter;
                 const text = stub ? serializeEntryFile({ id: entry.id, frontmatter: stubFm, body: STUB_ARCHIVED_LINE }) : fullText;
                 const target = join(dir, `${entry.slug}.md`);
-                this.writeIfChanged(target, text);
+                if (!(zeroCopy && restricted))
+                    this.writeIfChanged(target, text);
                 const onDiskRev = stub ? revOfText(text, entry.id) : entry.rev;
                 const path = canonicalize(target);
                 handle.materialized.push({
@@ -415,7 +421,7 @@ export class MemoryEngine {
                 this.discloseAnnounceFailure("index-gate enqueue", err);
             }
         }
-        const indexText = this.rebuildIndex(handle, headers, { write: writeScope !== null, ignoreOnDisk: indexGate !== undefined });
+        const indexText = this.rebuildIndex(handle, headers, { write: writeScope !== null && !restricted, ignoreOnDisk: indexGate !== undefined || restricted });
         handle.indexBaselineLines = countIndexLines(indexText);
         handle.indexText = indexText;
         for (const [scope, dir] of scopeDirs) {
@@ -433,7 +439,7 @@ export class MemoryEngine {
         const instruction = writeChannel ? buildMemoryInstruction(handle.writableRoot) : "";
         const readOnlyNotice = handle.writeScope === null ? MEMORY_READONLY_NOTICE : undefined;
         const indexPath = join(handle.writableRoot, MEMORY_INDEX_FILENAME);
-        const onDisk = handle.indexOnDiskUntrusted === true ? undefined : readSafe(indexPath);
+        const onDisk = handle.indexOnDiskUntrusted === true || handle.adoptionRestricted === true ? undefined : readSafe(indexPath);
         const indexText = onDisk !== undefined && onDisk.trim() !== "" ? onDisk : handle.indexText;
         const truncated = truncateIndex(indexText);
         const index = composeMemoryBlock(truncated, handle.writeScope ?? handle.scopes[0] ?? "memory");
@@ -529,6 +535,12 @@ export class MemoryEngine {
         };
         const writeScope = handle.writeScope;
         if (writeScope === null || opts?.admitNothing !== undefined) {
+            try {
+                this.backend.auditRestrictedDivergence?.([...new Set([...handle.scopes, ...(writeScope !== null ? [writeScope] : [])])], handle.adoptionRestricted === true && writeScope !== null ? { idlessWriteScope: writeScope } : undefined);
+            }
+            catch (err) {
+                report.warnings.push(`restricted-session divergence audit failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
             const roFindings = this.backend.drainInboundFindings?.();
             if (roFindings !== undefined && roFindings.length > 0)
                 report.inboundFindings = roFindings;