@sema-agent/core 5.23.0 → 5.25.0

package/dist/core/permission-rule-org.js

@@ -11,22 +11,29 @@ export const ORG_ADJUDICATION_TIMEOUT_MS = 15_000;
 export function settleOrgVerdictWithin(p, fallback, opts) {
     return new Promise((resolve) => {
         let settled = false;
-        const finish = (v) => {
+        const finish = (v, cause) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
             opts.signal?.removeEventListener("abort", onAbort);
+            if (cause !== undefined) {
+                try {
+                    opts.onFallback?.(cause);
+                }
+                catch {
+                }
+            }
             resolve(v);
         };
-        const onAbort = () => finish(fallback);
-        const timer = setTimeout(() => finish(fallback), opts.timeoutMs);
+        const onAbort = () => finish(fallback, "aborted");
+        const timer = setTimeout(() => finish(fallback, "timeout"), opts.timeoutMs);
         if (opts.signal?.aborted === true) {
-            finish(fallback);
+            finish(fallback, "aborted");
             return;
         }
         opts.signal?.addEventListener("abort", onAbort);
-        p.then(finish, () => finish(fallback));
+        p.then((v) => finish(v), () => finish(fallback));
     });
 }
 export const ORG_RULE_DECISION_REASON = "org_rule";

package/dist/core/permission-rule-store.d.ts

@@ -1,11 +1,14 @@
 /**
- * design/179 §8 — the persisted allow-rule store seam, its core-private write face, and the removal entry.
+ * design/179 §8 — the persisted allow-rule store seam, its backend write face, and the removal entry.
  *
  * ## Two faces, deliberately unequal
  *
- * A deployment sees a READ face: `list()`, scoped to one verified principal by a factory. There is no
- * exported write API at all — the only way a rule enters the store through the engine is the core-private
- * redemption path (`permission-rule-consent.ts`), which requires an approved durable approval record.
+ * A deployment sees a READ face: `list()`, scoped to one verified principal by a factory. The write face
+ * is a BACKEND CONTRACT (ruled 2026-08-10: exported so an out-of-repo store twin builds against the same
+ * definitions instead of mirroring them), not a host write API — the only way a rule enters the store
+ * through the ENGINE is the redemption path (`permission-rule-consent.ts`), which requires an approved
+ * durable approval record; that invariant lives in the engine's wiring and is pinned by the
+ * writer-caller registry test, not in type visibility.
  * `expectedRev` is concurrency control, not authorization, so "hold a put API and skip the ticket" is not
  * a shape that exists here rather than a rule someone must remember.
  *
@@ -156,15 +159,19 @@ export interface RuleSyncJoinDelta {
  * What a write may say. Authorization discriminates on the DELTA SHAPE, not on a full snapshot: only the
  * add arm can introduce a dot, and the delete arm carries a tombstone and no adds. A backend additionally
  * REFUSES at runtime any delete that would introduce a new add dot — structure and runtime check together,
- * so "pick the delete arm and smuggle an add" is neither expressible nor accepted. The `sync-join` arm is
- * constructible only by core (the writer is never exported), and every inbound record inside it passes the
- * single validator again AT THE BACKEND — the fifth door of design/179 §4's validator list closes here,
- * not at the calling layer.
+ * so "pick the delete arm and smuggle an add" is neither expressible nor accepted. The `sync-join` arm's
+ * safety does not rest on hiding the type (ruled 2026-08-10: the backend contract IS exported for
+ * out-of-repo store twins) — it rests on every inbound record inside it passing the single validator
+ * again AT THE BACKEND: the fifth door of design/179 §4's validator list closes here, not at the
+ * calling layer, and closes identically for every caller.
  */
 export type RuleWriteDelta = RuleAddDelta | RuleDeleteDelta | RuleSyncJoinDelta;
 /**
- * The core-private write face. Deliberately absent from the package's public exports: a host cannot hold
- * one, so no API-level path to the store bypasses the consent protocol.
+ * The backend write face. Exported as part of the BACKEND CONTRACT (ruled 2026-08-10) so an
+ * out-of-repo store implementation hangs the same face the file backend does, instead of mirroring the
+ * types. The consent boundary is unchanged by the export: the ENGINE reaches a writer only through the
+ * consent protocol's redemption (and the sync client's join) — a property of the engine's wiring —
+ * and a deployment always owned its own storage bytes, so type visibility grants nothing new.
  */
 export interface PermissionRuleWriter {
     /** Mint the next dot for this replica. Counters need only be unique and monotonic, so a dot minted for
@@ -198,11 +205,11 @@ export interface RawRuleSyncState {
     quarantined?: QuarantinedRuleAdd[];
 }
 /**
- * The internal handle a writable backend hangs its write face on. Not exported from the package index —
- * that omission IS the boundary described in the module doc.
+ * The handle a writable backend hangs its write face on (exported with the backend contract, ruled 2026-08-10;
+ * the consent boundary lives in the engine's wiring, not in this key's visibility).
  */
 export declare const PERMISSION_RULE_WRITER = "__semaPermissionRuleWriter";
-/** A store that also carries the core-private write face. */
+/** A store that also carries the backend write face. */
 export interface WritablePermissionRuleStore extends PermissionRuleStore {
     readonly [PERMISSION_RULE_WRITER]: PermissionRuleWriter;
 }
@@ -419,7 +426,11 @@ export type RemoveResult =
 export declare function removePersistedRule(opts: {
     rule: string;
     scope: RuleScope;
-    principal: string;
+    /** Whose bucket. A bare string stays the principal shorthand (unchanged callers); the structural
+     *  {@link RuleOwner} form adds the local-owner bucket (downstream request, 2026-08-10 — design/182 §4.5's
+     *  `forLocalOwner()` face existed, but removal could not name it, so a local-owner rule was
+     *  unrevokable through this entry). Same observed-remove/add-wins/stillLive semantics either way. */
+    principal: string | RuleOwner;
     provider: PermissionRuleStoreProvider;
 }): Promise<RemoveResult>;
 export declare function errText(err: unknown): string;

package/dist/core/permission-rule-store.js

@@ -327,7 +327,11 @@ export async function ruleStoreChecksum(payload) {
 }
 const REMOVE_MAX_ATTEMPTS = 8;
 export async function removePersistedRule(opts) {
-    const store = opts.provider.forPrincipal(opts.principal);
+    const owner = typeof opts.principal === "string" ? { kind: "principal", principal: opts.principal } : opts.principal;
+    if (owner.kind === "local-owner" && opts.provider.forLocalOwner === undefined) {
+        return { status: "failed", error: "this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be removed through it" };
+    }
+    const store = owner.kind === "local-owner" ? opts.provider.forLocalOwner() : opts.provider.forPrincipal(owner.principal);
     const writer = writerOf(store);
     if (writer === undefined) {
         return { status: "failed", error: "the resolved permission-rule store has no write face — rules cannot be removed through it" };

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

@@ -28,6 +28,8 @@ import { type WiringManifest } from "../wiring-manifest.js";
 import type { ActiveWorktreeSession, AgentMessage, AgentTool, ExecutionEnv } from "../../internal/harness.js";
 import type { NestedUsageAccum, RunnerDeps, TaskEvent, TaskLimits, TaskResult, TaskSpec, ToolActivity, ToolEffect } from "../types.js";
 import type { RepairBundle } from "../../agents/repair-loop.js";
+/** Test seam (mirrors `__resetBashTimeoutAnnouncements`): never called by production code. */
+export declare function __resetMaterializeEnvAnnouncements(): void;
 /**
  * design/164 — validate `TaskSpec.limits` at the door and return it unchanged.
  *

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

@@ -85,10 +85,14 @@ import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-
 import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
 import { resolveKey } from "../../tools/fs/safety.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
-import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, remainingBudgetMicroUsd, resolveCheckpointStore, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
+import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, remainingBudgetMicroUsd, resolveCheckpointStore, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
 import { boundInputHashOf } from "../canonical-json.js";
 import { countElicitOptIns, deriveAskEffective, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam } from "../wiring-manifest.js";
 import { GLOBAL_USAGE_KEY, resolveUsageWindows, usageRetryAfterMs } from "../usage-window-store.js";
+const announcedMaterializeEnv = new Set();
+export function __resetMaterializeEnvAnnouncements() {
+    announcedMaterializeEnv.clear();
+}
 const RECONCILE_MAX_RETRIES = 3;
 const DEFAULT_MAX_SUSPENDS = 5;
 const TASK_LIMIT_KEY_DICT = {
@@ -2572,6 +2576,16 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             toolsDeltaRef = { pending: [], pendingRemoved: [], pendingReadded: [], pendingFailed: failedMcpServers };
         }
         const listingRideRef = {};
+        {
+            const raw = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
+            if (raw !== undefined && raw !== "swap" && raw !== "static" && deferred.size === 0) {
+                const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(raw)} is not "swap" or "static" — inert on this task (no deferred tools), but a deferring task WITHOUT an explicit spec strategy will refuse to prepare under it (an explicit legal spec outranks and discards it, loudly). Fix or unset the flag.`;
+                if (!announcedMaterializeEnv.has(line)) {
+                    announcedMaterializeEnv.add(line);
+                    console.warn(line);
+                }
+            }
+        }
         if (deferred.size > 0) {
             if (deferred.has(TOOL_SEARCH_NAME) || tools.some((t) => t.name === TOOL_SEARCH_NAME)) {
                 const e = new Error(`Tool name "${TOOL_SEARCH_NAME}" is reserved when deferred tools are present.`);
@@ -2579,12 +2593,21 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 throw e;
             }
             const registry = buildDeferredRegistry(deferred, tools);
-            const envStrategy = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
-            if (envStrategy !== undefined && envStrategy !== "swap" && envStrategy !== "static") {
-                const e = new Error(`SEMA_TOOL_MATERIALIZE_STRATEGY must be "swap" or "static" (got ${JSON.stringify(envStrategy)}).`);
+            const rawEnvStrategy = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
+            const envStrategyInvalid = rawEnvStrategy !== undefined && rawEnvStrategy !== "swap" && rawEnvStrategy !== "static";
+            if (envStrategyInvalid && spec.toolMaterializeStrategy === undefined) {
+                const e = new Error(`SEMA_TOOL_MATERIALIZE_STRATEGY must be "swap" or "static" (got ${JSON.stringify(rawEnvStrategy)}).`);
                 e.code = "config.tool_materialize_invalid";
                 throw e;
             }
+            if (envStrategyInvalid) {
+                const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(rawEnvStrategy)} was ignored — not "swap" or "static", and the task spec pins toolMaterializeStrategy=${JSON.stringify(spec.toolMaterializeStrategy)} which outranks it. Fix or unset the env flag.`;
+                if (!announcedMaterializeEnv.has(line)) {
+                    announcedMaterializeEnv.add(line);
+                    console.warn(line);
+                }
+            }
+            const envStrategy = envStrategyInvalid ? undefined : rawEnvStrategy;
             const requestedStrategy = spec.toolMaterializeStrategy ?? envStrategy ?? "swap";
             const laneDegrade = requestedStrategy === "static" && spec.deferSelfResolve === false;
             const materializeStatic = requestedStrategy === "static" && !laneDegrade;
@@ -3273,6 +3296,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...askSourceIdentity(),
                     ...riskAxesOf(creq.toolName),
                     ...(re.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+                    ...(re.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: re.persistedRuleShadowed } : {}),
                 }, onAskOf, csignal ?? abortController.signal);
                 if (rr.action !== "allow")
                     return rr;
@@ -3357,6 +3381,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
                             ...(first.action === "ask" && first.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+                            ...(first.action === "ask" && first.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: first.persistedRuleShadowed } : {}),
                         }, pc.onAsk, csignal ?? abortController.signal);
                         const askWaitMs = Math.max(0, now() - askT0);
                         if (resolved.action === "deny" && resolved.approverUnavailable === true) {
@@ -3443,6 +3468,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
                             ...(decision.action === "ask" && decision.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+                            ...(decision.action === "ask" && decision.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: decision.persistedRuleShadowed } : {}),
                         }, pc.onAsk, csignal ?? abortController.signal);
                         const askWaitMs = Math.max(0, now() - askT0);
                         if (resolved.action === "deny" && resolved.approverUnavailable === true) {
@@ -3755,6 +3781,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...askSourceIdentity(),
                     ...riskAxesOf(req.toolName),
                     ...(decision.action === "ask" && decision.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+                    ...(decision.action === "ask" && decision.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: decision.persistedRuleShadowed } : {}),
                 }, onAsk, abortController.signal);
                 const waitMs = Math.max(0, now() - t0);
                 if (resolved.approverUnavailable !== true) {
@@ -4236,7 +4263,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 }
             };
             const suspendAsk = parkLaneArmed && checkpointStore !== undefined
-                ? async (req, postHookArgs, safety, liveFaceUnavailable) => {
+                ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval, shadowedRule) => {
                     const syncFirstEligible = req.toolName === ASK_USER_QUESTION_TOOL_NAME ? contentAskRoutable(req.toolCallId) : isLiveApproverSeat(onAsk);
                     if (syncFirstEligible &&
                         runtimeCaps?.forceDurableGate !== true &&
@@ -4341,16 +4368,20 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             toolName: req.toolName,
                             args: parkedArgs,
                             safety,
+                            ...(shadowedRule !== undefined ? { shadowedRule } : {}),
                             shellGated: (req.toolName === "Bash" && shellGatedBash) || (req.toolName === "Monitor" && shellGatedMonitor),
                             ...(effectiveShellGate !== "off" ? { shellGateDoctrine: effectiveShellGate } : {}),
                         });
                         gate =
-                            safety !== undefined
+                            safety !== undefined || realApproval !== undefined
                                 ? {
                                     kind: "irreversible_ask",
-                                    reason: `human approval required before safety-tightened tool "${req.toolName}"`,
+                                    reason: safety !== undefined
+                                        ? `human approval required before safety-tightened tool "${req.toolName}"`
+                                        : `real human approval required for tool "${req.toolName}" (non-budgetable: ${realApproval.origin})`,
                                     toolName: req.toolName,
-                                    safetyAxis: safety,
+                                    ...(safety !== undefined ? { safetyAxis: safety } : {}),
+                                    ...(realApproval !== undefined ? { realApproval } : {}),
                                     riskDescriptor,
                                 }
                                 : durableApproval
@@ -4373,7 +4404,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const mintedAt = Date.now();
                         cp = {
                             token,
-                            version: f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : approvalLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
+                            version: realApproval !== undefined ? REAL_APPROVAL_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : approvalLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
                             scope,
                             sessionId,
                             leafId,

package/dist/core/runner/runtask.js

@@ -1,6 +1,6 @@
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
-import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, MAX_SUPPORTED_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
+import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
 import { engineVersion } from "../version.js";
 import { CONFIG_CATALOG_VERSION, declarationReasons, resolveEffectiveConfig } from "../../config/catalog.js";
 import { eventDefaultOn } from "../../prompt-assembly/event-registry.js";
@@ -71,6 +71,7 @@ const STOP_HOOK_BLOCK_CAP = 8;
 const COMPACTION_REGROWTH_FACTOR = 1.5;
 const COMPACTION_FREED_EPSILON = 256;
 const BATCH_RESPONSE_MAX_CHARS = 500;
+const ORG_DISCLOSURE_MAX_CHARS = 600;
 function batchResponseDigest(result) {
     const content = result !== null && typeof result === "object" ? result.content : result;
     if (content === undefined || content === null)
@@ -3702,7 +3703,22 @@ export class Runner {
             }
         }
         if (checkpointVersionOf(cp) > MAX_SUPPORTED_CHECKPOINT_VERSION) {
-            throw new CheckpointError("checkpoint.unsupported_version", `checkpoint version ${checkpointVersionOf(cp)} is newer than this worker supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION})`);
+            throw new CheckpointError("checkpoint.unsupported_version", `checkpoint version ${checkpointVersionOf(cp)} is newer than this worker supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION})`, { reason: "version_newer" });
+        }
+        const preCasGateBit = cp.gate.kind === "irreversible_ask" ? cp.gate.realApproval : undefined;
+        const preCasBitWellFormed = preCasGateBit !== undefined &&
+            typeof preCasGateBit === "object" &&
+            (preCasGateBit.origin === "org_rule" ||
+                preCasGateBit.origin === "org_unavailable" ||
+                preCasGateBit.origin === "policy");
+        if (checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION ? !preCasBitWellFormed : preCasGateBit !== undefined) {
+            throw new CheckpointError("checkpoint.invalid_outcome", checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION
+                ? `a v${checkpointVersionOf(cp)} checkpoint must carry a well-formed non-budgetable realApproval gate bit (origin org_rule/org_unavailable/policy) on an irreversible_ask gate — this row does not; refusing to resume a damaged real-approval row (corruption / downgrade guard), the checkpoint stays pending`
+                : `a v${checkpointVersionOf(cp)} checkpoint carries a realApproval gate bit no release of that version ever minted — refusing to honor a fabricated origin (corruption / forgery guard), the checkpoint stays pending`, { reason: checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION ? "real_approval_damaged" : "real_approval_forged" });
+        }
+        if ((preCasGateBit?.origin === "org_rule" || preCasGateBit?.origin === "org_unavailable") &&
+            this.deps.permissionRuleOrg === undefined) {
+            throw new CheckpointError("checkpoint.unsupported_version", `this checkpoint's approval was minted under organization governance (${preCasGateBit.origin}) and this worker has no org adjudication wiring (permissionRuleOrg) — a governed approval may only be redeemed where governance can be enforced; the checkpoint stays pending, resume it on an org-wired worker`, { reason: "governed_unwired" });
         }
         const retiredWalltimeTotal = cp.resourceLedger?.totalWalltimeSec;
         if (retiredWalltimeTotal !== undefined) {
@@ -3714,7 +3730,7 @@ export class Runner {
             throw new CheckpointError("checkpoint.resume_aborted", "the resume was handed an ALREADY-ABORTED signal — refusing to consume the approval on a leg that cannot run it (the checkpoint stays pending and is resumable with a live signal)");
         }
         if (cp.state.workspaceHandle !== undefined && this.deps.executionEnvFactory === undefined) {
-            throw new CheckpointError("checkpoint.unsupported_version", "checkpoint has a remote workspaceHandle but no RunnerDeps.executionEnvFactory is wired to rebuild the env");
+            throw new CheckpointError("checkpoint.unsupported_version", "checkpoint has a remote workspaceHandle but no RunnerDeps.executionEnvFactory is wired to rebuild the env", { reason: "env_factory_missing" });
         }
         if (cp.state.inheritedGate?.requiresParentConstraint === true) {
             const supplied = internals?.inheritedGate?.parentConstraints?.length ?? 0;
@@ -3730,6 +3746,10 @@ export class Runner {
                     "re-supply would run the resumed leg under a different ancestor chain than it suspended with; " +
                     "rejected pre-CAS (the checkpoint stays pending) — re-resume with the full original chain");
             }
+            if (checkpointVersionOf(cp) >= F012_CHECKPOINT_VERSION &&
+                (cp.state.inheritedGate.constraintChain === undefined || cp.state.inheritedGate.constraintDigest === undefined)) {
+                throw new CheckpointError("checkpoint.invalid_outcome", `a v${checkpointVersionOf(cp)} checkpoint that requires parent constraints must carry BOTH the frozen constraintChain and its constraintDigest (they are minted in one write with the version stamp) — this row carries neither or only one; refusing to fall back to the count-only contract on a damaged row (corruption / downgrade guard), the checkpoint stays pending`, { reason: "constraint_chain_missing" });
+            }
             const expectedDigest = cp.state.inheritedGate.constraintDigest;
             if (expectedDigest !== undefined) {
                 const persistedChain = cp.state.inheritedGate.constraintChain;
@@ -4009,18 +4029,41 @@ export class Runner {
                 return;
             }
         }
+        const gateRealApproval = resume.cp.gate.kind === "irreversible_ask" ? resume.cp.gate.realApproval : undefined;
+        const gateOrgGoverned = gateRealApproval?.origin === "org_rule" || gateRealApproval?.origin === "org_unavailable";
+        if (gateOrgGoverned && prepared.permissionRuleOrg === undefined) {
+            const unwiredDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" was not executed: its approval was minted under organization governance (${gateRealApproval.origin}), and this worker has no org adjudication wiring — a governed approval may only be redeemed where governance can be enforced. This approval is spent; re-issue the call on an org-wired worker.`);
+            emitEnd(true, { content: unwiredDenial });
+            const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, unwiredDenial, true));
+            emitCommitted(eid, "toolResult", pendingAction.toolCallId);
+            return;
+        }
         if (prepared.permissionRuleOrg !== undefined) {
             const orgVerdict = prepared.permissionRuleOrg
                 .adjudicate({ toolName: pendingAction.toolName, args: resolvedArgs, toolCallId: pendingAction.toolCallId })
                 .catch(() => ({ status: "unavailable", disclosures: ["the org adjudication face threw on resume"] }));
-            const org = await settleOrgVerdictWithin(orgVerdict, { status: "unavailable", disclosures: [`the org adjudication face did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms (or the task ended first)`] }, { signal: prepared.abortController.signal, timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
+            let orgWaitCancelled = false;
+            const org = await settleOrgVerdictWithin(orgVerdict, { status: "unavailable", disclosures: [`the org adjudication face did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms (or the task ended first)`] }, {
+                signal: prepared.abortController.signal,
+                timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS,
+                onFallback: (cause) => {
+                    orgWaitCancelled = cause === "aborted";
+                },
+            });
             const blocked = org.status === "unavailable"
-                ? "this deployment is org-governed and cannot currently adjudicate against an organization policy snapshot"
+                ? gateRealApproval?.origin === "org_unavailable"
+                    ? undefined
+                    : orgWaitCancelled
+                        ? "this deployment is org-governed and the task was cancelled before the organization policy snapshot could be adjudicated"
+                        : "this deployment is org-governed and cannot currently adjudicate against an organization policy snapshot"
                 : org.verdict?.behavior === "deny"
                     ? `an organization policy rule (${org.verdict.rule}) denies it`
                     : undefined;
             if (blocked !== undefined) {
-                const orgDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" was not executed: ${blocked}. This approval is spent — the call has to be re-issued and approved again once organization policy permits it.`);
+                const orgDisclosures = org.status === "unavailable" && org.disclosures.length > 0
+                    ? ` Governance disclosures: ${inlineUntrusted(org.disclosures.join("; "), ORG_DISCLOSURE_MAX_CHARS)}.`
+                    : "";
+                const orgDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" was not executed: ${blocked}.${orgDisclosures} This approval is spent — the call has to be re-issued and approved again once organization policy permits it.`);
                 emitEnd(true, { content: orgDenial });
                 const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, orgDenial, true));
                 emitCommitted(eid, "toolResult", pendingAction.toolCallId);

package/dist/core/runner/session-file-state-replay.js

@@ -1,4 +1,5 @@
 import { isAbsolutePathForm } from "../../tools/fs/safety.js";
+import { isOffloadedDetailReplacement } from "../tool-result-store.js";
 const READ_TOOL = "Read";
 const WRITE_TOOL = "Write";
 const RETRACTING_RESULTS = [
@@ -50,6 +51,8 @@ export function wholeFileRecordsFromTranscript(messages) {
         const content = isRead ? wholeFileFromReadCard(rest) : typeof rest.content === "string" ? rest.content : undefined;
         if (content === undefined)
             continue;
+        if (isOffloadedDetailReplacement(content))
+            continue;
         byPath.set(filePath, { path: filePath, content, at: m.timestamp });
     }
     return [...byPath.values()];

package/dist/core/tool-policy.d.ts

@@ -167,6 +167,13 @@ export type PermissionResult = {
     message?: string;
     decisionReason?: DecisionReason;
     requiresRealApproval?: boolean;
+    /** #144 disclosure (additive): a persisted allow rule MATCHED this call but could not clear the
+     *  ask, because the ask is MANDATED (operator shellGate:"always", or the tool's own
+     *  egress/irreversibility marks) rather than a classifier's hesitation — "allow rules silence
+     *  the classifier's questions, never a mandated one". Carries the matched rule text so a
+     *  consumer (approval card, wire frame) can tell the person their rule is alive, just outranked.
+     *  Absent ⇒ no rule matched, or the ask was cleared normally. */
+    persistedRuleShadowed?: string;
 } | {
     action: "deny";
     updatedInput?: unknown;
@@ -601,6 +608,10 @@ export interface AskDelegationProvenance {
 /** The structured context an `onAsk` approver receives for an `ask` decision (design/37). */
 export interface AskRequest {
     toolName: string;
+    /** #144: a persisted allow rule MATCHED this call but could not clear the ask (mandated — see
+     *  {@link PermissionResult}'s ask arm). The matched rule text, so the approval card renders "your
+     *  rule is alive, just outranked" instead of leaving the person to regex the message prose. */
+    persistedRuleShadowed?: string;
     toolCallId: string;
     /** The (post-rewrite) args the tool would run with. */
     args: unknown;

package/dist/core/tool-policy.js

@@ -122,12 +122,9 @@ export function createAllowDenyPolicy(opts) {
             if (entry.startsWith("mcp__")) {
                 const segments = entry.slice("mcp__".length).split("__");
                 if (segments.some((seg) => seg.length === 0)) {
-                    invalid.push({
-                        entry,
-                        list,
-                        message: `"${entry}" is a malformed MCP tool name (empty segment) — it can never match any mounted tool. ` +
-                            `Use \`mcp__<server>\` for every tool of a server, or \`mcp__<server>__<tool>\` for one tool.`,
-                    });
+                    const lesson = `a malformed MCP tool name (empty segment) — it can never match any mounted tool. ` +
+                        `Use \`mcp__<server>\` for every tool of a server, or \`mcp__<server>__<tool>\` for one tool.`;
+                    invalid.push({ entry, list, message: `"${entry}" is ${lesson}`, lesson });
                     continue;
                 }
             }
@@ -135,14 +132,11 @@ export function createAllowDenyPolicy(opts) {
                 kept.push(entry);
                 continue;
             }
-            invalid.push({
-                entry,
-                list,
-                message: `"${entry}" is a rule CONTENT form, not a tool name — a name set matches raw tool names, so this entry ` +
-                    `can never match any mounted tool (in an allow list it removes the tool entirely). Use the tool NAME here, ` +
-                    `and route the narrowing through the lane that speaks this grammar: parameter rules via ` +
-                    `createPermissionRulePolicy, Bash command prefixes via the persisted allow-rule lane.`,
-            });
+            const lesson = `a rule CONTENT form, not a tool name — a name set matches raw tool names, so this entry ` +
+                `can never match any mounted tool (in an allow list it removes the tool entirely). Use the tool NAME here, ` +
+                `and route the narrowing through the lane that speaks this grammar: parameter rules via ` +
+                `createPermissionRulePolicy, Bash command prefixes via the persisted allow-rule lane.`;
+            invalid.push({ entry, list, message: `"${entry}" is ${lesson}`, lesson });
         }
         return kept;
     };
@@ -150,8 +144,16 @@ export function createAllowDenyPolicy(opts) {
     const screenedDeny = screen(opts.deny, "deny");
     if (invalid.length > 0) {
         if ((opts.onInvalidName ?? "throw") === "throw") {
+            const byLesson = new Map();
+            for (const i of invalid) {
+                const group = byLesson.get(i.lesson) ?? [];
+                group.push({ entry: i.entry, list: i.list });
+                byLesson.set(i.lesson, group);
+            }
             const e = new Error(`createAllowDenyPolicy: ${invalid.length} entr${invalid.length === 1 ? "y is" : "ies are"} not tool name(s):\n` +
-                invalid.map((i) => `  [${i.list}] ${i.message}`).join("\n"));
+                [...byLesson.entries()]
+                    .map(([lesson, group]) => `  Each of the following is ${lesson}\n` + group.map((g) => `    [${g.list}] "${g.entry}"`).join("\n"))
+                    .join("\n"));
             e.code = "config.invalid_tool_name_set";
             e.issues = invalid;
             throw e;

package/dist/core/tool-result-store.d.ts

@@ -240,5 +240,13 @@ export declare function withToolResultOffload(tool: AgentTool, store: ToolResult
  *  ⇒ byte-identical historic preview. An accessor (not a snapshot) because the wrap happens at
  *  prepare time, before the deferred classification exists and before any activation can. */
 reachableTools?: () => ReadonlySet<string> | undefined): AgentTool;
+/** The machine-recognizable start of an offloaded-detail replacement notice. Exported for consumers
+ *  that treat a `details` string as SEMANTIC INPUT (not display) — e.g. the session-continuation
+ *  read-state replay — so they can tell "this member was offloaded, the bytes here are a preview"
+ *  and degrade honestly instead of consuming preview bytes as the real value. */
+export declare const OFFLOADED_DETAIL_NOTICE_PREFIX = "\u2026[offloaded \u2014 ";
+/** True when `s` carries an offloaded-detail replacement notice (the newline-anchored prefix form the
+ *  walk emits). A semantic consumer treats such a string as NOT the member's real bytes. */
+export declare function isOffloadedDetailReplacement(s: string): boolean;
 /** The injected `read_tool_result` tool: pages through an offloaded result. `effect:"read"` (verifier/reconcile-safe). */
 export declare function createReadToolResultTool(store: ToolResultStore): AgentTool;

package/dist/core/tool-result-store.js

@@ -121,6 +121,8 @@ export function firstPartyOffloadPolicy(toolName) {
     switch (toolName) {
         case "Read":
             return { offload: false };
+        case "Write":
+            return { offload: false };
         case "Bash":
             return { offloadThresholdChars: 30_000 };
         case "Grep":
@@ -164,21 +166,93 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId, re
         return tool;
     const wrappedExecute = async (toolCallId, params, signal, onUpdate) => {
         const res = await tool.execute(toolCallId, params, signal, onUpdate);
+        const offloadedDetails = res.details === undefined ? undefined : await offloadOversizedDetailStrings(res.details, store, thresholdChars, sessionId, toolCallId);
+        const withDetails = (r) => offloadedDetails === undefined || offloadedDetails.value === res.details ? r : { ...r, details: offloadedDetails.value };
         if (totalTextChars(res.content) <= thresholdChars)
-            return res;
+            return withDetails(res);
         const full = res.content
             .filter((b) => b.type === "text")
             .map((b) => b.text)
             .join("\n");
         if (full.length <= PREVIEW_HEAD_CHARS + PREVIEW_TAIL_CHARS)
-            return res;
+            return withDetails(res);
         const ref = buildToolResultRef(sessionId, toolCallId);
         await store.put(ref, full);
         const images = res.content.filter((b) => b.type !== "text");
-        return { ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] };
+        return withDetails({ ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] });
     };
     return { ...tool, execute: wrappedExecute };
 }
+const OFFLOADED_DETAIL_HEAD_CHARS = 2_000;
+const OFFLOADED_DETAIL_NOTICE_ALLOWANCE_CHARS = 400;
+export const OFFLOADED_DETAIL_NOTICE_PREFIX = "…[offloaded — ";
+export function isOffloadedDetailReplacement(s) {
+    return s.includes(`\n${OFFLOADED_DETAIL_NOTICE_PREFIX}`);
+}
+async function offloadOversizedDetailStrings(details, store, thresholdChars, sessionId, toolCallId) {
+    const puts = [];
+    const onStack = new Set();
+    const isPlainObject = (v) => {
+        if (typeof v !== "object" || v === null)
+            return false;
+        const p = Object.getPrototypeOf(v);
+        return p === Object.prototype || p === null;
+    };
+    const replace = (full, path) => {
+        const detailRef = buildToolResultRef(sessionId, toolCallId + " " + path);
+        puts.push(Promise.resolve(store.put(detailRef, full)));
+        return (`${full.slice(0, OFFLOADED_DETAIL_HEAD_CHARS)}\n` +
+            `${OFFLOADED_DETAIL_NOTICE_PREFIX}${full.length} chars total; ref "${detailRef}"; the remainder is retained in this run's tool-result store and reads back through the deployment's tool-results face]`);
+    };
+    const memo = new Map();
+    const walk = (v, segs) => {
+        if (typeof v === "string")
+            return v.length > thresholdChars && v.length > OFFLOADED_DETAIL_HEAD_CHARS + OFFLOADED_DETAIL_NOTICE_ALLOWANCE_CHARS ? replace(v, JSON.stringify(segs)) : v;
+        if (Array.isArray(v)) {
+            if (onStack.has(v))
+                return v;
+            const done = memo.get(v);
+            if (done !== undefined)
+                return done;
+            onStack.add(v);
+            let changed = false;
+            const next = v.map((item, i) => {
+                const w = walk(item, [...segs, i]);
+                if (w !== item)
+                    changed = true;
+                return w;
+            });
+            onStack.delete(v);
+            const result = changed ? next : v;
+            memo.set(v, result);
+            return result;
+        }
+        if (isPlainObject(v)) {
+            if (onStack.has(v))
+                return v;
+            const done = memo.get(v);
+            if (done !== undefined)
+                return done;
+            onStack.add(v);
+            let changed = false;
+            const next = {};
+            for (const [k, item] of Object.entries(v)) {
+                const w = walk(item, [...segs, k]);
+                if (w !== item)
+                    changed = true;
+                Object.defineProperty(next, k, { value: w, enumerable: true, writable: true, configurable: true });
+            }
+            onStack.delete(v);
+            const result = changed ? next : v;
+            memo.set(v, result);
+            return result;
+        }
+        return v;
+    };
+    const value = walk(details, []);
+    await Promise.all(puts);
+    return { value };
+}
 export function createReadToolResultTool(store) {
     return defineTool({
         name: OFFLOAD_TOOL_NAME,

package/dist/core/types.d.ts

@@ -4188,11 +4188,13 @@ export interface RunnerDeps {
      * they confirmed once is not asked about again.
      *
      * This is the one seam in this file that LOOSENS, and it is shaped so it can only do so within limits
-     * the engine holds. The provider hands out a READ face anchored to one verified principal; the write
-     * face is core-private, so a deployment has no API path to put a rule in — that goes through the
-     * approval-record protocol, which requires a confirmed human decision. Rules are consumed post-fold, in
-     * the gate's ask branch, and never resolve an ask carrying `requiresRealApproval` or one a PreToolUse
-     * hook raised.
+     * the engine holds. The provider hands out a READ face anchored to one verified principal. The write
+     * face is an exported BACKEND CONTRACT (ruled 2026-08-10: an out-of-repo store twin builds against the
+     * same definitions instead of mirroring them), but the ENGINE reaches it only on the consent lanes —
+     * redemption of a confirmed human decision, the tighten-delete, and the sync join — a wiring invariant
+     * pinned by a registered-caller scan (test/permission-rule-writer-callers); no exported convenience
+     * mints a rule around consent. Rules are consumed post-fold, in the gate's ask branch, and never
+     * resolve an ask carrying `requiresRealApproval` or one a PreToolUse hook raised.
      *
      * Omitted ⇒ the lane does not exist: no rules are read, no field is added to any ask, and the decision
      * path is byte-identical to a build without it. An unauthenticated task (no `principal`) resolves to