@sema-agent/core 5.32.0 → 5.33.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 5.33.0 — 2026-08-14
+
+### BREAKING (operational)
+
+- memory-engine file backend: ledger schema v2 (design/186). Slug/scope rebinds and cross-scope
+  transfers are journaled transactions (`transfers.jsonl` + journaled rebind with a tri-state
+  projection probe); a v2 journal is REFUSED LOUDLY by pre-5.33 readers. Mixed-version deployments:
+  drain writers BEFORE downgrading (ship post carries the three-step rollback and the drain
+  precondition). Downgrade is fail-closed by design, not an oversight.
+
+### Behavior changes (named)
+
+- read-deny built-in table is deployment-configurable (#245, ruled): four tiers
+  (credentials 18 / shell-history 2 / browser 9 / wallet 6); the two shell-history rows
+  (`.bash_history` / `.zsh_history`) are OFF by default (ruled widening). Knobs:
+  `readDenyBuiltinTiers` (whole tiers) + `readDenyBuiltinExclude` (canonical pattern names),
+  deployment seats only (TaskSpec carries neither), every bad value refuses loudly. Persisted
+  checkpoint face rows freeze EXPLICIT additions only — built-in liveness stays a deployment
+  authority across suspend/resume (deploy-time exclude applies to resumed legs; explicit denies
+  survive verbatim).
+- verify/fix hands-less legs run the FULL read-face resolution (#242): one unified else-branch
+  (resolver + one deny compile over deps∪spec∪seed + carrier). Five narrowings enumerated in the
+  ship post; consumers keying on seat ABSENCE must re-key (absence now = "prepare never completed").
+- built-in deny config snapshot (#245 interference fix): prepare reads
+  `readDenyBuiltinTiers` / `readDenyBuiltinExclude` ONCE and every station eats the snapshot —
+  previously the toolkit mount re-read the caller-retained arrays past an await, so a hot-reload
+  mutation mid-prepare could give one task two different built-in deny sets.
+- internals activity sink containment (#248): a throwing `onActivity` no longer fails the leg it
+  fires on (previously: leg terminated `failed` misclassified as `provider.error`; inside a cascade
+  the false FAIL escalated and re-ran non-idempotent writes — measured). Contained via the RB-463
+  safe-notifier; first failure per site disclosed via `console.warn`, later ones counted.
+
+### Added
+
+- Structured reversibility-probe cause (#239): `ToolSpec.reversibilityProbe` may return a
+  `ReversibilityVerdict` (`{reversible, reason?, cause?}`); `AskRequest.probeCause` /
+  `RiskDescriptor.probeCause` carry `{code, roots: {shown, total}, further?}` with per-item caps,
+  percent-encoded separators and undercount coercion. The cause NEVER enters the ask `message`
+  (that text feeds the auto-mode classifier). #95 closed by the same structure.
+- TaskResult observation seats `effectiveReadFace` / `effectiveReadDenyPatterns` (#240, widened by
+  #242): present on every leg that completes prepare — including every hands-less leg — and ride
+  every terminal, not just `completed`. verifyCompleted folds them stricter-wins into the returned
+  result (`carryFrozenPosture`) so a chained gate cannot widen from a fix leg's own seats.
+- verify/cascade run-internals seat (#246): `runWithVerification` / `resumeWithVerification` /
+  `runCascade` / `verifyCompleted` / `runDeveloperTask` take a tail-optional `internals` —
+  forwarded WHOLE by identity to every leg; `isolation` is refused loudly
+  (`config.verify_internals_invalid`, distinct door / before-leg phases, re-checked before every
+  dispatch; the before-leg refusal is ordered AFTER the durable-pause hand-back). `RunInternals` +
+  `ResolvedWorkspace` are now package-root type exports.
+- prepare-task phase extraction (design/238 batches 1+2): prepare-config-doors / safety-scan /
+  acquire-reconcile / workspace-restore phase modules, verbatim slices behind Input/Result seams;
+  phase-API rules piece ratified (D-9). Internal restructuring — zero wire change; body span
+  ratchet banked 10138 → 9420. Both new modules joined the fail-open scan surface.
+- Retry-progress disclosure documented as built (#223): the per-attempt `status` TaskEvent family
+  (phase/attempt/maxRetries/retryInSec/errClass, 30s slice replay, exactly-one terminal frame) has
+  shipped since v5.22.0; the EngineNotice family table now records the negative space (no notice
+  family duplicates it).
+
+### Notes
+
+- #244 (scan-vs-mount TOCTOU): ruled — roster snapshot form, lands in a normal window (not this one).
+- Governed workflow key candidates (excludeTools/handsReadOnly/shellGate): ruled OBSERVED-NOT-ADDED.
+
 ## 5.32.0 — 2026-08-14
 
 No BREAKING changes. One additive disclosure surface; zero resolution-result changes (the read-face

package/dist/agents/cascade.d.ts

@@ -1,4 +1,5 @@
 import type { Runner } from "../core/runner/runtask.js";
+import type { RunInternals } from "../core/runner/prepare-task.js";
 import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
 /**
  * Quality-gate cascade (design/27). Run the SAME task across a ladder of models (cheapest → strongest);
@@ -153,4 +154,51 @@ export interface CascadeRunResult extends TaskResult {
  * (`effect: "write"`), those execute once PER rung — ensure idempotency, or gate before the side effect
  * (e.g. a structured-output gate). `TaskSpec` never guaranteed idempotency; cascade makes it explicit.
  */
-export declare function runCascade(runner: Runner, spec: TaskSpec, config: CascadeConfig): Promise<CascadeRunResult>;
+export declare function runCascade(runner: Runner, spec: TaskSpec, config: CascadeConfig, 
+/**
+ * The TRUSTED, run-scoped internals channel — the same object `Runner.runTask` takes as its second
+ * argument — forwarded UNCHANGED to EVERY rung.
+ *
+ * WHY THE SEAT EXISTS: `runCascade` returns a `TaskResult` and DRAINS each rung's event stream
+ * internally, so the host never holds a `TaskStream` for any rung. Without this parameter a
+ * deployment can observe nothing a rung did — tool beats, forwarded child progress, the resolved
+ * workspace — only the per-rung {@link CascadeAttempt} audit rows and the final result. Wiring an
+ * observation sink here (`onActivity`, `onForwardEvent`, `onWorkspaceResolved`) is the only way in.
+ *
+ * ATTRIBUTION: rungs run SEQUENTIALLY and each is dispatched with the SAME object, so one sink
+ * receives the rungs' beats CONCATENATED in ladder order. `ToolActivity` carries no rung identity of
+ * its own — the frames of two rungs running the same tool are indistinguishable in content, so the
+ * boundary a host keys on is {@link CascadeConfig.onRung}, which fires only after its own rung's
+ * beats have been delivered (the sole rung that ends without one is a durable pause, which returns
+ * immediately). Two honesty notes: SUBAGENT events forwarded through `onForwardEvent` do carry their
+ * own `sourceTaskId`, and a BACKGROUND child outlives the rung that spawned it — its frames can
+ * arrive after that rung's `onRung`, i.e. inside the next rung's segment.
+ *
+ * FAILURE-ISOLATED since #248, by the same primitive as {@link CascadeConfig.onRung}: engine-invoked
+ * through a run-scoped safe notifier — a throwing `onActivity` is contained (first failure per site
+ * disclosed via `console.warn`, later ones counted) and no longer faults the rung. Before #248 the
+ * fault AMPLIFIED: the faulted rung was rejected by the gate, the cascade escalated, and a
+ * non-idempotent tool the rung had ALREADY executed ran AGAIN on the next rung — the MEASURED
+ * HAZARD pin that recorded that now pins containment.
+ *
+ * FORWARDED WHOLE, NOT FILTERED: every field rides every rung, including the ref-valued ones
+ * (`peerSelfRef`, `ownOrgAdmissionRef`) whose own contract is one ref per RUN — wiring those here
+ * makes the ladder's rungs share one carrier. The seat is meant for observation sinks; anything else
+ * is a choice the caller is making explicitly, not a default this layer applies.
+ *
+ * `isolation: "worktree"` in particular rides through here, where the verification gate REFUSES it —
+ * an asymmetry with a reason. That field mints a NEW workspace per RUN. The gate's runs are one
+ * artifact judged and repaired by several legs, so separate workspaces would have the verifier
+ * grading files the implementation never wrote to; a ladder's rungs are INDEPENDENT COLD RE-RUNS of
+ * the same task (this function's own contract), so one workspace per rung is the coherent reading —
+ * each attempt gets its own tree. What a host must then know, stated without promises this function
+ * cannot keep: the returned result is ONE rung's, its work lives in THAT rung's workspace, and no
+ * field of the result names it — `onWorkspaceResolved` is the only place the path appears, once per
+ * rung in ladder order. Whether the path is still readable afterwards is the FACTORY's contract, not
+ * this function's: each rung's factory-minted env is torn down at the end of that rung's run, and
+ * what teardown does to the workspace is the factory's business.
+ *
+ * Absent ⇒ every rung is dispatched exactly as before (the call site passes `undefined`, which is
+ * what an omitted optional argument already was).
+ */
+internals?: RunInternals): Promise<CascadeRunResult>;

package/dist/agents/cascade.js

@@ -14,7 +14,7 @@ function createDefaultGate(spec) {
     const requiresStructured = spec.outputSchema != null;
     return (result) => result.status === "completed" && (!requiresStructured || result.structuredOutput !== undefined);
 }
-export async function runCascade(runner, spec, config) {
+export async function runCascade(runner, spec, config, internals) {
     const ladder = config.ladder;
     if (!ladder || ladder.length === 0) {
         throw new Error("runCascade: config.ladder must have at least one rung");
@@ -82,7 +82,7 @@ export async function runCascade(runner, spec, config) {
                 : rungAbort.signal;
         let result;
         try {
-            result = await runner.runTask({ ...specBase, model: rung.model, ...(rung.overrides ?? {}), ...(rungSignal ? { signal: rungSignal } : {}) });
+            result = await runner.runTask({ ...specBase, model: rung.model, ...(rung.overrides ?? {}), ...(rungSignal ? { signal: rungSignal } : {}) }, internals);
         }
         finally {
             if (deadlineTimer !== undefined)

package/dist/agents/verify.d.ts

@@ -1,5 +1,6 @@
 import { Type, type Static } from "typebox";
 import type { Runner, ResumeTaskConfig } from "../core/runner/runtask.js";
+import type { RunInternals } from "../core/runner/prepare-task.js";
 import type { CheckpointGate, CheckpointToken, ResumeOutcome } from "../core/checkpoint-store.js";
 import type { ModelRef, TaskResult, TaskSpec, ToolSpec } from "../core/types.js";
 /**
@@ -217,7 +218,54 @@ export interface VerificationResult extends TaskResult {
  * override is given, the verifier uses {@link STATIC_VERIFICATION_PROMPT} (read the diff/results; don't try
  * to execute — that was L2's job), avoiding the "PARTIAL on everything" failure in a read-only sandbox.
  */
-export declare function verifyCompleted(runner: Runner, result: TaskResult, specBase: ResumeTaskConfig, objective: string, config: VerifyConfig): Promise<VerificationResult>;
+export declare function verifyCompleted(runner: Runner, result: TaskResult, specBase: ResumeTaskConfig, objective: string, config: VerifyConfig, 
+/**
+ * The TRUSTED, run-scoped internals channel — the same object `Runner.runTask` takes as its second
+ * argument — forwarded UNCHANGED to EVERY leg this gate drives: the verifier run of each round and
+ * each fix continuation (and, from {@link runWithVerification} / {@link resumeWithVerification} /
+ * {@link runDeveloperTask}, the implementation leg as well). This doc is the contract for the whole
+ * family; the sibling entries carry the same parameter and point here.
+ *
+ * WHY THE SEAT EXISTS: these entries return a `TaskResult` and DRAIN each leg's event stream
+ * internally, so the host never holds a `TaskStream` for any of them. Without this parameter a
+ * deployment can observe nothing a leg did — tool beats, forwarded child progress, the resolved
+ * workspace — only the final result. Wiring an observation sink here (`onActivity`,
+ * `onForwardEvent`, `onWorkspaceResolved`) is the only way in.
+ *
+ * ATTRIBUTION — WEAK, and deliberately stated as such: the legs run SEQUENTIALLY (impl → verifier →
+ * fix → verifier → …) and each is dispatched with the SAME object, so a leg's own tool beats are all
+ * delivered before the next leg is dispatched. That ORDERING is the whole of it. `ToolActivity`
+ * carries no leg identity, so generic activity CANNOT be attributed to a leg from the frame alone:
+ * two adjacent legs calling the same tool are indistinguishable, and the structured-output tool is
+ * no verifier marker either (an impl spec carrying its own `outputSchema` mounts it too).
+ * {@link VerifyConfig.onRound} bounds a ROUND, not a leg — the segment before it holds the impl (or
+ * fix) leg's beats AND that round's verifier beats together. A host that needs true per-leg
+ * attribution must drive the legs itself (one `runner.runTask` per leg) rather than read it out of
+ * this stream. Two further honesty notes: SUBAGENT events forwarded through `onForwardEvent` do
+ * carry their own `sourceTaskId`, and a BACKGROUND child outlives the leg that spawned it — its
+ * frames can arrive after that leg returned, i.e. interleaved into a later leg's segment.
+ *
+ * FAILURE-ISOLATED since #248, by the same primitive as {@link VerifyConfig.onRound} /
+ * {@link VerifyConfig.onVerifierPause}: the fields on this object are invoked by the ENGINE on the
+ * run's own path, through a run-scoped safe notifier — a throwing `onActivity` is contained (first
+ * failure per site disclosed via `console.warn`, later ones counted) and never faults the leg it
+ * fires on. Before #248 a throw here failed the leg (misclassified `provider.error`) and an impl
+ * leg was reported incomplete — the MEASURED HAZARD pins that recorded that now pin containment.
+ *
+ * FORWARDED WHOLE, NOT FILTERED, with ONE refusal: every field rides every leg, including the
+ * ref-valued ones (`peerSelfRef`, `ownOrgAdmissionRef`) whose own contract is one ref per RUN —
+ * wiring those here makes the gate's legs share one carrier. The seat is meant for observation
+ * sinks; anything else is a choice the caller is making explicitly, not a default this layer
+ * applies. The single exception is `isolation`, which is REFUSED — at the entry door and again
+ * before each leg is dispatched, typed `config.verify_internals_invalid` — because it would mint a
+ * separate workspace per leg and break the one invariant the gate is for. The refusal's own doc
+ * (`refuseUnhonorableInternals`) carries the reasoning, the re-check rule, and what a mid-gate
+ * refusal does and does not undo.
+ *
+ * Absent ⇒ every leg is dispatched exactly as before (each call site passes `undefined`, which is
+ * what an omitted optional argument already was).
+ */
+internals?: RunInternals): Promise<VerificationResult>;
 /**
  * Run an implementation task, then gate it behind an independent falsification-style verifier, looping
  * fix→re-verify until PASS (or a round cap). Returns the implementation result plus the
@@ -226,7 +274,12 @@ export declare function verifyCompleted(runner: Runner, result: TaskResult, spec
  * failed-with-token (verdict `unverified`); the caller approves and calls {@link resumeWithVerification}
  * to resume AND verify (design/51 P1-b: the durable + HITL + verify integration).
  */
-export declare function runWithVerification(runner: Runner, implSpec: TaskSpec, config?: VerifyConfig): Promise<VerificationResult>;
+export declare function runWithVerification(runner: Runner, implSpec: TaskSpec, config?: VerifyConfig, 
+/** The trusted run-scoped internals channel, forwarded UNCHANGED to every leg this entry drives —
+ *  the implementation run, then (on completion) the verifier + fix legs of the gate. Full contract,
+ *  including the attribution and forwarded-whole rules, on {@link verifyCompleted}. Absent ⇒ every
+ *  leg is dispatched exactly as before. */
+internals?: RunInternals): Promise<VerificationResult>;
 /**
  * Resume a durable-suspended implementation task (design/45 F4) **and** verify it on completion — the
  * durable + HITL + verify integration (design/51 P1-b). The mirror of {@link runWithVerification} for the
@@ -242,7 +295,14 @@ export declare function runWithVerification(runner: Runner, implSpec: TaskSpec,
  * after approval, so a pre-suspend diff would grade stale code. The verifier already verifies the current working
  * tree (verifierObjective), so dropping the stale diff closes the timing window.
  */
-export declare function resumeWithVerification(runner: Runner, token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, objective: string, config?: VerifyConfig): Promise<VerificationResult>;
+export declare function resumeWithVerification(runner: Runner, token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, objective: string, config?: VerifyConfig, 
+/** The trusted run-scoped internals channel, forwarded UNCHANGED to every leg this entry drives —
+ *  `Runner.resume`'s own internals argument for the RESUMED implementation leg, then (on completion)
+ *  the verifier + fix legs of the gate. Note that this seat carries the resume-path duty of the same
+ *  channel as well: a checkpoint suspended under OPAQUE inherited parent constraints re-supplies them
+ *  through `internals.inheritedGate.parentConstraints`, which had no way in here before. Full
+ *  contract on {@link verifyCompleted}. Absent ⇒ every leg is dispatched exactly as before. */
+internals?: RunInternals): Promise<VerificationResult>;
 export interface DeveloperTaskConfig extends VerifyConfig {
     /** Run the verification gate. Default `true` (that's the point of developer mode). Set `false` for prompt-only. */
     verify?: boolean;
@@ -255,4 +315,10 @@ export interface DeveloperTaskConfig extends VerifyConfig {
  * Pair with a role map that gives a strong implementation model and cheaper helper/verifier models for
  * "auto model selection" (design/28 §3.2): `roles: { default: strong, subagent: cheap, verifier: strong }`.
  */
-export declare function runDeveloperTask(runner: Runner, spec: TaskSpec, config?: DeveloperTaskConfig): Promise<VerificationResult>;
+export declare function runDeveloperTask(runner: Runner, spec: TaskSpec, config?: DeveloperTaskConfig, 
+/** The trusted run-scoped internals channel, forwarded UNCHANGED to every leg this entry drives — in
+ *  BOTH arms: the lone implementation run when `verify: false`, and the whole gate otherwise. The two
+ *  arms differ in ONE respect: the gate's door refusal of `isolation` (see {@link verifyCompleted})
+ *  applies only to the gated arm, since `verify: false` is a single run that can honor it. Full
+ *  contract on {@link verifyCompleted}. Absent ⇒ every leg is dispatched exactly as before. */
+internals?: RunInternals): Promise<VerificationResult>;

package/dist/agents/verify.js

@@ -61,6 +61,24 @@ export const VerdictSchema = Type.Object({
 });
 const VERIFY_ON_ROUND_SITE = "verify.onRound";
 const VERIFY_ON_VERIFIER_PAUSE_SITE = "verify.onVerifierPause";
+const VERIFY_INTERNALS_ERROR_CODE = "config.verify_internals_invalid";
+function verifyInternalsError(message) {
+    const e = new Error(message);
+    e.code = VERIFY_INTERNALS_ERROR_CODE;
+    return e;
+}
+function refuseUnhonorableInternals(internals, phase) {
+    if (internals?.isolation !== undefined) {
+        throw verifyInternalsError(`the verification gate cannot honor internals.isolation ("${internals.isolation}"): it mints a new workspace per RUN, and this gate runs several of them ` +
+            `(implementation, verifier, and one per fix round), so the verifier would judge a checkout the implementation never wrote to. Isolate at the ` +
+            `execution-env factory instead, so every leg of the gate resolves the same root. ` +
+            (phase === "door"
+                ? `This call dispatched no leg before refusing.`
+                : `The object gained the field AFTER this call's entry check (it is forwarded by identity, so anything running between legs can set it): ` +
+                    `no FURTHER leg was dispatched. What already ran is not undone and is not returned — this throws instead of returning a result, so an ` +
+                    `implementation leg keeps whatever it did (a consumed checkpoint stays consumed, its session stays the caller's to reclaim).`));
+    }
+}
 function fixObjective(findings) {
     const list = findings.length
         ? findings.map((f) => `- ${sanitizeUntrustedText(f)}`).join("\n")
@@ -81,16 +99,37 @@ function verifierObjective(originalObjective, impl, evidence) {
     }
     return parts.join("\n\n");
 }
-export async function verifyCompleted(runner, result, specBase, objective, config) {
+export async function verifyCompleted(runner, result, specBase, objective, config, internals) {
+    refuseUnhonorableInternals(internals, "door");
     if (result.status !== "completed") {
         return { ...result, verification: { verdict: "unverified", unverifiedReason: "impl_incomplete", rounds: 0, findings: [] } };
     }
     const maxRounds = Number.isFinite(config.maxRounds) ? Math.max(1, Math.floor(config.maxRounds)) : 2;
     const notifier = createSafeNotifier(config.onNotifyError !== undefined ? { onError: config.onNotifyError } : undefined);
     const verifierTools = config.verifierTools ?? (specBase.tools ?? []).filter((t) => t.effect === "read");
+    const foldedRootsFace = specBase.readFace === "roots" || result.effectiveReadFace === "roots";
+    const foldedReadDeny = [...(specBase.readDenyPatterns ?? []), ...(result.effectiveReadDenyPatterns ?? [])];
+    const carryFrozenPosture = (r) => {
+        const face = result.effectiveReadFace === "roots" ? "roots" : r.effectiveReadFace;
+        const keyOf = (e) => `${e.caseSensitive ? "s" : "i"} ${e.pattern}`;
+        const seen = new Set((r.effectiveReadDenyPatterns ?? []).map(keyOf));
+        const merged = [...(r.effectiveReadDenyPatterns ?? [])];
+        for (const e of result.effectiveReadDenyPatterns ?? []) {
+            if (!seen.has(keyOf(e))) {
+                seen.add(keyOf(e));
+                merged.push({ ...e });
+            }
+        }
+        return {
+            ...r,
+            ...(face !== undefined ? { effectiveReadFace: face } : {}),
+            ...(merged.length > 0 ? { effectiveReadDenyPatterns: merged } : {}),
+        };
+    };
     const evidenceMode = config.evidence != null && config.evidence.trim() !== "";
     const verifierPrompt = config.verifierPrompt ?? (evidenceMode ? STATIC_VERIFICATION_PROMPT : VERIFICATION_PROMPT);
     const runVerifier = async (impl, round) => {
+        refuseUnhonorableInternals(internals, "before_leg");
         const roundEvidence = round === 1 ? config.evidence : undefined;
         const v = await runner.runTask({
             objective: verifierObjective(objective, impl, roundEvidence),
@@ -99,8 +138,8 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
             roles: specBase.roles,
             tools: verifierTools,
             handsReadOnly: config.verifierHandsReadOnly ?? true,
-            ...(specBase.readFace === "roots" ? { readFace: "roots" } : {}),
-            ...(specBase.readDenyPatterns !== undefined ? { readDenyPatterns: [...specBase.readDenyPatterns] } : {}),
+            ...(foldedRootsFace ? { readFace: "roots" } : {}),
+            ...(foldedReadDeny.length > 0 ? { readDenyPatterns: [...foldedReadDeny] } : {}),
             interactiveTools: false,
             outputSchema: VerdictSchema,
             enableBlockedReport: false,
@@ -113,7 +152,7 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
             ...(specBase.clientContext !== undefined ? { clientContext: { ...specBase.clientContext } } : {}),
             ...(specBase.promptProfile !== undefined ? { promptProfile: specBase.promptProfile } : {}),
             signal: specBase.signal,
-        });
+        }, internals);
         try {
             const cost = (v.stats.costMicroUsd ?? 0) + (v.stats.nested?.costMicroUsd ?? 0);
             return { verdict: v.structuredOutput, cost, ...(isDurablePause(v.status) ? { paused: v } : {}) };
@@ -183,39 +222,46 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
             break;
         if (config.costCeilingMicroUsd != null && spend >= config.costCeilingMicroUsd)
             break;
+        refuseUnhonorableInternals(internals, "before_leg");
         current = await runner.runTask({
             ...specBase,
             sessionId: current.sessionId,
             objective: fixObjective(outcome.findings),
-        });
+            ...(foldedRootsFace ? { readFace: "roots" } : {}),
+            ...(foldedReadDeny.length > 0 ? { readDenyPatterns: [...foldedReadDeny] } : {}),
+        }, internals);
         spend += (current.stats.costMicroUsd ?? 0) + (current.stats.nested?.costMicroUsd ?? 0);
         if (isDurablePause(current.status)) {
-            return { ...mapNestedSuspend(current), verification: outcome };
+            return { ...mapNestedSuspend(carryFrozenPosture(current)), verification: outcome };
         }
         if (current.status !== "completed")
             break;
     }
-    return { ...current, verification: outcome };
+    return { ...carryFrozenPosture(current), verification: outcome };
 }
-export async function runWithVerification(runner, implSpec, config = {}) {
-    const result = await runner.runTask(implSpec);
+export async function runWithVerification(runner, implSpec, config = {}, internals) {
+    refuseUnhonorableInternals(internals, "door");
+    const result = await runner.runTask(implSpec, internals);
     if (isDurablePause(result.status)) {
         return { ...mapNestedSuspend(result), verification: { verdict: "unverified", unverifiedReason: result.status === "needs_review" ? "needs_review" : "suspended", rounds: 0, findings: [] } };
     }
-    return verifyCompleted(runner, result, implSpec, implSpec.objective, config);
+    refuseUnhonorableInternals(internals, "before_leg");
+    return verifyCompleted(runner, result, implSpec, implSpec.objective, config, internals);
 }
-export async function resumeWithVerification(runner, token, outcome, taskConfig, objective, config = {}) {
-    const result = await runner.resume(token, outcome, taskConfig);
+export async function resumeWithVerification(runner, token, outcome, taskConfig, objective, config = {}, internals) {
+    refuseUnhonorableInternals(internals, "door");
+    const result = await runner.resume(token, outcome, taskConfig, internals);
     if (isDurablePause(result.status)) {
         return { ...mapNestedSuspend(result), verification: { verdict: "unverified", unverifiedReason: result.status === "needs_review" ? "needs_review" : "suspended", rounds: 0, findings: [] } };
     }
-    return verifyCompleted(runner, result, taskConfig, objective, config);
+    refuseUnhonorableInternals(internals, "before_leg");
+    return verifyCompleted(runner, result, taskConfig, objective, config, internals);
 }
-export async function runDeveloperTask(runner, spec, config = {}) {
+export async function runDeveloperTask(runner, spec, config = {}, internals) {
     const implSpec = { systemPrompt: CODE_AGENT_PROMPT, ...spec };
     if (config.verify === false) {
-        const result = await runner.runTask(implSpec);
+        const result = await runner.runTask(implSpec, internals);
         return { ...result, verification: { verdict: "unverified", unverifiedReason: "opted_out", rounds: 0, findings: [] } };
     }
-    return runWithVerification(runner, implSpec, config);
+    return runWithVerification(runner, implSpec, config, internals);
 }

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

@@ -140,7 +140,94 @@ export interface RiskDescriptor {
      *  carries the same disclosure the synchronous ask does. The inbox renders "their rule is alive,
      *  just outranked" instead of the person concluding their rule silently broke. */
     shadowedRule?: string;
+    /** backlog #239 (additive): WHY the reversibility probe did not clear this call, in the probe's own
+     *  words — the cause the tighten acted on, which until now existed only inside the probe and left the
+     *  card showing WHAT is gated with no account of WHY. Present only for a `"maybe"`-tier tighten whose
+     *  probe supplied a cause (an `"always"`-tier tighten runs no probe; a timeout/throw yields no verdict).
+     *  Neutralized + capped at {@link PROBE_REASON_MAX} — it is deployment-authored text on a human trust
+     *  boundary, so it is DISPLAY/TRIAGE metadata only, never adjudication input.
+     *
+     *  The UNSTRUCTURED face: a deployment's own probe writes prose here and this engine cannot say what it
+     *  means. An engine-minted cause uses {@link probeCause} instead — see that field for why. */
+    probeReason?: string;
+    /** backlog #239 (additive): the STRUCTURED cause, for a probe whose verdict this engine understands —
+     *  the built-in shell probe is the first. Carries a machine-readable {@link ProbeCause.code} and the
+     *  operand families as ARRAYS with honest totals, so a consumer renders its own sentence in its own
+     *  language instead of receiving one this engine had to write in advance.
+     *
+     *  The prose sibling above is what this replaces for engine-minted causes, and the reason is not
+     *  aesthetic: a sentence asserting what a command DOES is false for the demotion's documented
+     *  over-fire, a sentence asserting what its OPERANDS are is false when the check synthesizes one, and
+     *  serializing a variable-length multi-part disclosure into one length-capped string silently deletes
+     *  whichever part sorts last. A code cannot be false and an array cannot be truncated into a lie. */
+    probeCause?: ProbeCause;
+}
+/** backlog #239: one operand family inside a {@link ProbeCause} — the entries a card may NAME, plus how
+ *  many the family really has. `shown.length` ≤ {@link total}, and a consumer that renders only `shown`
+ *  is still obliged to tell the person when `total` exceeds it: the count is the part that cannot be
+ *  cut, and "there is a second unreviewed operand" is exactly what a reader cannot recover from the
+ *  command text. */
+export interface ProbeCauseOperands {
+    /** The named entries. Each `inlineUntrusted`-neutralized and capped at {@link PROBE_CAUSE_PATH_MAX}
+     *  INDIVIDUALLY, so one pathological entry costs only itself. Bounded in count by the minting probe. */
+    readonly shown: readonly string[];
+    /** How many entries the family has in total — `shown.length` when nothing was elided. A non-negative
+     *  integer; never a lie by omission. */
+    readonly total: number;
+}
+/**
+ * backlog #239: an ENGINE-MINTED, structured account of why a reversibility probe did not clear a call.
+ *
+ * DISPLAY/TRIAGE metadata, exactly like the rest of {@link RiskDescriptor} — nothing reads it to gate,
+ * budget or suppress anything, and it deliberately never reaches the ask's `message` (that string is
+ * handed to the auto-mode classifier, which may answer an ask with `allow`; a probe must not own an
+ * input to the decider that clears it).
+ *
+ * STRUCTURE IS THE CONTRACT. The entries are model-influenced text, so a consumer must render them as
+ * DATA — never re-derive structure by splitting or joining them. Structural characters are
+ * percent-encoded at the mint precisely so that a path cannot spell whatever grammar it is rendered
+ * into, but the array is the boundary that makes that guarantee cheap to keep.
+ */
+export interface ProbeCause {
+    /** Machine-readable cause id, `<domain>.<snake_case>` like this codebase's other notice codes. The
+     *  consumer maps it to its own prose. A code is the one part of a cause that cannot become false as
+     *  the check's edge cases are discovered. */
+    readonly code: string;
+    /** The paths the check TOOK as traversal roots — deduplicated and resolved, which is why they are
+     *  described by what the check did with them rather than by what the caller wrote: a lexical operand
+     *  walk has no option-value table (`du -d 2 sub` takes `2`), and it synthesizes the working directory
+     *  when no operand is written at all (`du --help`). */
+    readonly roots: ProbeCauseOperands;
+    /** Operands the SAME verdict left unreviewed for a different reason (an unexpanded glob). Present only
+     *  when non-empty. Named separately so a card can say what else this one approval clears — a partial
+     *  account of an approval's reach is worse than none. */
+    readonly further?: ProbeCauseOperands;
 }
+/** backlog #239: the bloat ceiling on {@link RiskDescriptor.probeReason} — one sentence of cause, sized
+ *  like its {@link RiskDescriptor.shadowedRule} sibling. The neutralizer is the injection ceiling; this
+ *  is only the length one. Exported (module-level, not part of the package's public surface) so the gate
+ *  that sanitizes at the entry boundary and the descriptor builder that re-sanitizes at the persist
+ *  boundary cannot cap the same value at two different lengths. */
+export declare const PROBE_REASON_MAX = 200;
+/** backlog #239: the per-ENTRY ceiling inside a {@link ProbeCause} operand family, sized like the
+ *  descriptor's own {@link RiskDescriptor.touchedPaths} entries (the same thing on the same card). Per
+ *  entry, not per cause: that is the whole point of the structured shape — one pathological path costs
+ *  only itself, where a single joined string let it consume every other entry's room. */
+export declare const PROBE_CAUSE_PATH_MAX = 200;
+/**
+ * backlog #239: the ONE validator for a {@link ProbeCause} arriving from a probe.
+ *
+ * The value crosses a trust boundary twice — once at the gate (where a deployment-supplied probe hands
+ * it over) and once at the persist boundary (where {@link buildRiskDescriptor} is an exported function a
+ * caller may reach directly) — so both call it rather than each writing its own idea of "valid". A
+ * malformed cause yields `undefined`: the ASK still stands (the verdict was never this member's to
+ * decide), the card simply carries no account. Fail-closed on the disclosure, never on the gate.
+ *
+ * Every field is re-derived rather than trusted: strings are neutralized and capped individually, the
+ * shown list is clamped, and `total` is coerced to a non-negative integer that cannot understate what is
+ * shown (a `total` below `shown.length` would turn an honest count into a false reassurance).
+ */
+export declare function normalizeProbeCause(value: unknown): ProbeCause | undefined;
 /**
  * design/80 §D-E: the DETERMINISTIC severity tier (1..5) for an escalation checkpoint, a PURE function of the
  * tripped {@link RiskDescriptor.axes} (NO LLM, NO clock/random) so the inbox's sort order is stable and
@@ -273,6 +360,14 @@ export declare function buildRiskDescriptor(input: {
     shellGateDoctrine?: "classify" | "always";
     /** #144: the matched-but-outranked persisted rule to persist (see {@link RiskDescriptor.shadowedRule}). */
     shadowedRule?: string;
+    /** backlog #239: the reversibility probe's cause for not clearing this call (see
+     *  {@link RiskDescriptor.probeReason}). Re-neutralized here like its shadowed-rule sibling: this
+     *  function is exported, so a caller reaching it directly must get the same redaction the gate applies. */
+    probeReason?: string;
+    /** backlog #239: the STRUCTURED cause (see {@link RiskDescriptor.probeCause}). Re-validated here for
+     *  the same reason the prose sibling is re-neutralized — this function is exported, so a caller
+     *  reaching it directly must not be able to persist a shape the gate would have rejected. */
+    probeCause?: unknown;
 }): RiskDescriptor;
 /**
  * #130/#131/#120 (2026-08-10) — the durable record of an ask's `requiresRealApproval` bit, which used

package/dist/core/checkpoint-store.js

@@ -5,6 +5,39 @@ import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 export function mintCheckpointToken() {
     return randomBytes(16).toString("hex");
 }
+export const PROBE_REASON_MAX = 200;
+export const PROBE_CAUSE_PATH_MAX = 200;
+const PROBE_CAUSE_MAX_SHOWN = 8;
+export function normalizeProbeCause(value) {
+    if (!isPlainRecord(value))
+        return undefined;
+    const code = safeDataValue(value, "code");
+    if (typeof code !== "string" || code.trim().length === 0)
+        return undefined;
+    const family = (raw) => {
+        if (!isPlainRecord(raw))
+            return undefined;
+        const shownRaw = safeDataValue(raw, "shown");
+        if (!Array.isArray(shownRaw))
+            return undefined;
+        const shown = shownRaw
+            .filter((p) => typeof p === "string")
+            .slice(0, PROBE_CAUSE_MAX_SHOWN)
+            .map((p) => inlineUntrusted(p, PROBE_CAUSE_PATH_MAX));
+        const totalRaw = safeDataValue(raw, "total");
+        const total = typeof totalRaw === "number" && Number.isFinite(totalRaw) ? Math.max(0, Math.floor(totalRaw)) : shown.length;
+        return { shown, total: Math.max(total, shown.length) };
+    };
+    const roots = family(safeDataValue(value, "roots"));
+    if (roots === undefined)
+        return undefined;
+    const further = family(safeDataValue(value, "further"));
+    return {
+        code: inlineUntrusted(code, PROBE_REASON_MAX),
+        roots,
+        ...(further !== undefined && further.total > 0 ? { further } : {}),
+    };
+}
 export function riskSeverity(axes) {
     const egress = axes.egress === true;
     const irreversible = axes.irreversible === true;
@@ -121,6 +154,13 @@ export function buildRiskDescriptor(input) {
             toolName,
             ...(input.shellGated && input.shellGateDoctrine !== undefined ? { shellGateDoctrine: input.shellGateDoctrine } : {}),
             ...(input.shadowedRule !== undefined ? { shadowedRule: inlineUntrusted(input.shadowedRule, 200) } : {}),
+            ...(input.probeReason !== undefined ? { probeReason: inlineUntrusted(input.probeReason, PROBE_REASON_MAX) } : {}),
+            ...(() => {
+                if (input.probeCause === undefined)
+                    return {};
+                const cause = normalizeProbeCause(input.probeCause);
+                return cause !== undefined ? { probeCause: cause } : {};
+            })(),
             ...(summary !== undefined ? { summary } : {}),
             ...(touchedPaths !== undefined ? { touchedPaths } : {}),
         };

package/dist/core/hooks.d.ts

@@ -645,7 +645,14 @@ export interface ToolGateInput {
      *  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>;
+    askDecisionReason?: DecisionReason, 
+    /** backlog #239: the reversibility probe's cause for the tighten (the surviving ask's `probeReason`)
+     *  — threaded so the park mint's risk descriptor carries on the durable route the same account of
+     *  WHY the call was gated that the synchronous card gets. Already neutralized + capped at the gate. */
+    probeReason?: string, 
+    /** backlog #239: the STRUCTURED cause (the surviving ask's `probeCause`) — same durable-route errand
+     *  as `probeReason`, already validated at the gate. */
+    probeCause?: import("./checkpoint-store.js").ProbeCause) => 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,
@@ -680,12 +687,13 @@ export interface ToolGateInput {
      * tool argument). Called ONLY when `irreversibility === "maybe"` && the surviving decision is `allow`,
      * time-bounded by {@link approvalTimeoutMs}. Fail-closed: anything other than `{ reversible: true }`
      * (including a timeout or a throw) tightens to `ask`. A probe is never trusted to AUTO-ALLOW past the gate.
+     *
+     * An optional `reason` on a TIGHTENING verdict names the cause. The gate neutralizes + caps it and
+     * carries it onto both approval routes (`AskRequest.probeReason`, `RiskDescriptor.probeReason`) — see
+     * `ToolSpec.reversibilityProbe`. Display/triage only: `reversible` alone decides the verdict, so a
+     * probe cannot widen anything through this member.
      */
-    reversibilityProbe?: (args: unknown) => {
-        reversible: boolean;
-    } | Promise<{
-        reversible: boolean;
-    }>;
+    reversibilityProbe?: (args: unknown) => import("./types.js").ReversibilityVerdict | Promise<import("./types.js").ReversibilityVerdict>;
     /** design/77 §4: deadline (ms) for {@link reversibilityProbe}; on timeout the gate fails closed to `ask`. */
     approvalTimeoutMs?: number;
     /** design/77 §4: the task abort signal — bounds {@link reversibilityProbe} by the task's real deadline