@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/runner/tool-end-body.d.ts

@@ -17,7 +17,7 @@ import type { GateOutcome } from "../gate-outcome.js";
 import type { TaskEvent, TaskEventIdentity } from "../types.js";
 import type { OccurrenceStart, ToolOccurrenceTable } from "./tool-occurrence.js";
 import { type McpDelivered } from "../mcp-failure.js";
-import type { RecoveredOrphan } from "../session-reconcile.js";
+import { type RecoveredOrphan } from "../session-reconcile.js";
 import { type StructuredProjector } from "./tool-output-projection.js";
 import type { WriteFamily } from "./turn-attachments.js";
 /** Derive the thin `response` digest from a harness tool result: model-facing text
@@ -77,16 +77,15 @@ export interface OccurrenceEnd {
     /** The harness result (or the exact text the closing station records). */
     result: unknown;
     isError: boolean;
-    /** POSITIVE evidence the call never executed — the loop's own mark on a call it closed without running it, or the
-     *  reconcile's never-started class. Absent = no such evidence, never "it ran" (see `tool_end.notExecuted`). */
+    /** The CLOSING STATION's own POSITIVE evidence the call never executed — the loop's mark (a halted sibling may well have been let go by the gate) or the reconcile's never-started class; the engine's refusal is read off the occurrence. Absent = no such evidence, never "it ran". */
     notExecuted?: true;
     /** The call is closed by an interruption rather than a result of its own. */
     interrupted?: true;
     /** See {@link toolEndBodyFrom}'s parameter of the same name. */
     gatedCallIdOfRun?: string;
 }
-/** What the end projection decided, for the readers that ride beside the frame (the trace row, the row's record). */
-export interface SettledOccurrence {
+/** What the end projection decided, for the readers that ride beside the frame (the trace row, the row's record, the rows' `notExecuted`). */
+export interface SettledOccurrence extends Pick<OccurrenceEnd, "notExecuted"> {
     /** The latest gate record — the call's disposition (absent when no gate exit saw it). */
     gate?: GateOutcome;
     /** The tool's own error bit, or a refusal recorded after the gate: the engine's record wins over the tool's word. */
@@ -96,7 +95,7 @@ export interface SettledOccurrence {
  * The END projection — the ONE mint of `tool_end`, for every station that closes a call: the live loop's
  * `tool_execution_end`, the resumed leg's resolution, an interrupted run's reconcile and the reconcile replayed at
  * the next process start. It reads the occurrence and nothing else: `gate` is its latest gate record, `isError` is
- * the tool's bit or the refusal that record names, and `notExecuted` rides only on the station's positive evidence.
+ * the tool's bit or the refusal that record names, and `notExecuted` rides on positive evidence only: the station's own or `refusedBeforeRelease` (returned for the rows).
  *
  * A call whose start never went out on this stream (a call the loop never reached, a call announced by a dead
  * process) gets its start minted here first, marked `recovered` and carrying the input the closing station holds —

package/dist/core/runner/tool-end-body.js

@@ -1,6 +1,8 @@
 import {} from "../../internal/harness.js";
 import { readMember } from "../thrown-value.js";
+import { refusedBeforeRelease } from "./tool-not-executed.js";
 import { MCP_DELIVERY_VERDICTS } from "../mcp-failure.js";
+import { closeNeverExecuted } from "../session-reconcile.js";
 import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
 import { toolOutputFrom } from "./tool-output-projection.js";
 import { TASK_CREATE_TOOL_NAME, TASK_UPDATE_TOOL_NAME, TODO_WRITE_TOOL_NAME } from "../tool-catalog-entries.js";
@@ -63,7 +65,7 @@ export function emitSettled(table, start, end, frames) {
     if (!occ.startEmitted)
         frames.push(startFrameOf(occ, true));
     const gate = occ.gateRounds.at(-1);
-    const isError = end.isError || gate?.disposition.kind === "denied";
+    const isError = end.isError || gate?.disposition.kind === "denied", notExecuted = end.notExecuted === true || refusedBeforeRelease(occ);
     table.close(occ.toolCallId, end.interrupted === true ? "interrupted" : "settled");
     frames.push({
         type: "tool_end",
@@ -73,12 +75,12 @@ export function emitSettled(table, start, end, frames) {
         isError,
         ...toolEndBodyFrom(end.result, isError, frames, gate, end.gatedCallIdOfRun),
         ...(gate?.disposition.kind === "denied" && occ.wireName !== undefined ? { wireName: occ.wireName } : {}),
-        ...(end.notExecuted === true ? { notExecuted: true } : {}),
+        ...(notExecuted ? { notExecuted: true } : {}),
     });
-    return { ...(gate !== undefined ? { gate } : {}), isError };
+    return { ...(gate !== undefined ? { gate } : {}), isError, ...(notExecuted ? { notExecuted: true } : {}) };
 }
 export function reconciledEnd(orphan) {
-    return { result: { content: orphan.text, details: { code: orphan.errorKind } }, isError: true, interrupted: true, ...(orphan.errorKind === "interrupted_never_started" ? { notExecuted: true } : {}) };
+    return { result: { content: orphan.text, details: { code: orphan.errorKind } }, isError: true, interrupted: true, ...(closeNeverExecuted(orphan.errorKind) ? { notExecuted: true } : {}) };
 }
 export function writeFamilyOfCanonical(name) {
     if (name === TASK_CREATE_TOOL_NAME || name === TASK_UPDATE_TOOL_NAME)

package/dist/core/runner/tool-not-executed.d.ts

@@ -0,0 +1,15 @@
+import type { ToolOccurrence } from "./tool-occurrence.js";
+/** The engine's own judgment refused this call and it was never let go to an executor: the latest gate record is a
+ *  refusal and the life never left `announced` — positive evidence the call did not run (a refusal recorded AFTER the
+ *  release, by a station inside the execution, is not). A call whose start this stream never carried (a recovered
+ *  one, closed by a station that knows only its own class) is not read here. */
+export declare function refusedBeforeRelease(occ: Pick<ToolOccurrence, "life" | "gateRounds" | "startEmitted">): boolean;
+/** `details` as a persisted `toolResult` row carries it: `notExecuted` is the ENGINE's key — the settlement's fact when it holds,
+ *  absent otherwise, whatever a tool wrote under that name. Returns `details` itself unless the key has to move; never mutates it. */
+export declare function rowDetailsOf(details: unknown, notExecuted: boolean): unknown;
+/** A row the resumed leg mints (`toolResultMsg`) with the settlement's fact on it. */
+export declare function withRowNotExecuted<T extends object>(row: T, notExecuted: boolean): T;
+/** Write the end projection's one `notExecuted` onto the result the live loop persists as the call's row: the loop builds that message
+ *  from this very result right after the end event. The frame's card was projected from the previous `details` first and keeps its
+ *  members (a row mark is never part of a card). `Reflect.set`: a result that refuses the write keeps its row as it was. */
+export declare function stampRowNotExecuted(result: unknown, notExecuted: boolean): void;

package/dist/core/runner/tool-not-executed.js

@@ -0,0 +1,30 @@
+import { readOwnMembers } from "../thrown-value.js";
+export function refusedBeforeRelease(occ) {
+    return occ.life === "announced" && occ.startEmitted && occ.gateRounds.at(-1)?.disposition.kind === "denied";
+}
+export function rowDetailsOf(details, notExecuted) {
+    const carries = (() => { try {
+        return details !== null && typeof details === "object" && !Array.isArray(details) && Object.keys(details).includes("notExecuted");
+    }
+    catch {
+        return false;
+    } })();
+    if (!notExecuted && !carries)
+        return details;
+    const bag = { ...readOwnMembers(details) };
+    if (notExecuted)
+        bag["notExecuted"] = true;
+    else
+        delete bag["notExecuted"];
+    return bag;
+}
+export function withRowNotExecuted(row, notExecuted) {
+    return notExecuted ? { ...row, details: rowDetailsOf(undefined, true) } : row;
+}
+export function stampRowNotExecuted(result, notExecuted) {
+    if (result === null || typeof result !== "object")
+        return;
+    const next = rowDetailsOf(result.details, notExecuted);
+    if (next !== result.details)
+        Reflect.set(result, "details", next);
+}

package/dist/core/runner/tool-occurrence.d.ts

@@ -6,10 +6,11 @@
  * `tool_progress` heartbeat (`tool-progress-lane.ts`), the trace row's `ok`, and the resumed leg's
  * `executionOutcome` filing. The record has three parts:
  *
- *  - the EXECUTION LIFE, monotonic: `announced` (the start frame is out) → `executing` (the engine started the
- *    tool body itself — the resumed leg; on a live leg the loop starts the body and the runner does not observe
- *    that moment, so a live call stays `announced`) → `settled` or `interrupted`. Leaving a terminal state is an
- *    engine defect and throws;
+ *  - the EXECUTION LIFE, monotonic: `announced` (the start frame is out) → `released` (the engine let the call go
+ *    to its executor: the resumed leg right before it runs the tool body itself, a live leg at the gate's allow
+ *    exit — the loop starts the body after it and the runner does not observe that moment) → `settled` or
+ *    `interrupted`. A call that closes still `announced` was never let go: whatever the tool's body did, this call
+ *    did not do it (`refusedBeforeRelease`, `tool-not-executed.ts`). Leaving a terminal state is an engine defect and throws;
  *  - the WAIT ON A PERSON, re-entrant: every ask put to the person's seat for this call counts one entry and one
  *    exit (several rounds of one gate pass, a confirmation asked during the execution) — a count, never a bit,
  *    because the waits nest and overlap;
@@ -28,7 +29,7 @@ import type { DeniedBy, GateOutcome } from "../gate-outcome.js";
  *  host without `performance` falls back to the wall clock and inherits its rollback behaviour. */
 export declare const occurrenceClock: () => number;
 /** Where a call's execution life stands — see the module header for the order. */
-export type OccurrenceLife = "announced" | "executing" | "settled" | "interrupted";
+export type OccurrenceLife = "announced" | "released" | "settled" | "interrupted";
 /** What opens an occurrence: the facts its start frame carries. */
 export interface OccurrenceStart {
     readonly toolCallId: string;
@@ -78,8 +79,8 @@ export interface ToolOccurrenceTable {
     ensure(start: OccurrenceStart): ToolOccurrence;
     /** The call's start frame is out. */
     noteStartEmitted(toolCallId: string): void;
-    /** The engine starts the tool body. */
-    execute(toolCallId: string): void;
+    /** The engine lets the call go to its executor — the one transition into `released`, whichever leg makes it. */
+    release(toolCallId: string): void;
     /** A gate exit for this call: its record and the input it decided on (frozen by the gate's exit). */
     gateRound(toolCallId: string, outcome: GateOutcome, finalInput?: unknown): void;
     /** A station after the gate refused the call: one more gate record, minted as a veto of whatever the latest one

package/dist/core/runner/tool-occurrence.js

@@ -1,6 +1,6 @@
 import { mintGateOutcome } from "./gate-exit.js";
 export const occurrenceClock = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
-const TERMINAL = { announced: false, executing: false, settled: true, interrupted: true };
+const TERMINAL = { announced: false, released: false, settled: true, interrupted: true };
 export function createToolOccurrenceTable() {
     const byId = new Map();
     const attempts = new Map();
@@ -77,11 +77,11 @@ export function createToolOccurrenceTable() {
         noteStartEmitted(toolCallId) {
             held(toolCallId, "a start frame").startEmitted = true;
         },
-        execute(toolCallId) {
-            const occ = held(toolCallId, "execute");
+        release(toolCallId) {
+            const occ = held(toolCallId, "release");
             if (occ.life !== "announced")
-                throw new Error(`tool occurrence: call "${toolCallId}" (attempt ${occ.attempt}) cannot start executing from "${occ.life}"`);
-            occ.life = "executing";
+                throw new Error(`tool occurrence: call "${toolCallId}" (attempt ${occ.attempt}) cannot be released from "${occ.life}"`);
+            occ.life = "released";
         },
         gateRound(toolCallId, outcome, finalInput) {
             const occ = held(toolCallId, "a gate round");

package/dist/core/runner/tool-result-media-seat.d.ts

@@ -6,7 +6,7 @@
  * closed-set words, counts, the call's identity and a media type only when it can be one — never the bytes.
  */
 import { type EngineNotice } from "../engine-notice.js";
-import type { ToolResultMediaRefusal } from "../../tools/fs/image-admission.js";
+import type { ToolResultMediaRefusal } from "../image-admission.js";
 /** The run's attribution pair, as every per-run notice carries it. */
 export interface ToolResultMediaSeatIds {
     sessionId: string;

package/dist/core/runner-deps.d.ts

@@ -159,12 +159,14 @@ export interface RunnerDeps {
      */
     rosterStore?: import("../agents/roster-store.js").RosterStore;
     /**
-     * design/148 S1 — the center prompt-artifact source (protocol §9.2). `current()` supplies the
-     * validated candidate NEW sessions adopt at session_start; `get(digest)` resolves a PINNED
-     * center artifact on resume (a miss is fail-loud `prompt.snapshot_unavailable` — core never
-     * recomposes a hybrid from same-named newer content). Core bundles `CenterPromptSource`
-     * (+ memory/file artifact & source-state stores); a server deployment feeds it verified
-     * effective-snapshot envelopes via `applySnapshot`. Omitted = bundled-only (today's shape).
+     * The center prompt-artifact source (artifact v3 only — a v2 body is refused `schema`, INTEGRATION-CORE §12.11).
+     * `current()` supplies the verified
+     * candidate a top-level session adopts at session start and at a compaction; `get(digest)` resolves a PINNED center
+     * layer on resume (a miss is fail-loud `prompt.snapshot_unavailable` — core never recomposes a hybrid from newer
+     * content; a copy the engine refuses is told apart from a missing one, in the failure's sentence and on `onError`);
+     * `sourceState()` is the tri-state every adoption decision keys on. What a source hands a run is re-checked
+     * before it is adopted. Core bundles `CenterPromptSource` (+ memory/file artifact & source-state stores); a server
+     * feeds it published artifacts via `applySnapshot`. Omitted = no center layer.
      */
     promptSource?: import("../prompt-assembly/artifact-store.js").PromptArtifactSource;
     /**
@@ -518,7 +520,7 @@ export interface RunnerDeps {
     resumePreflight?: (info: ResumePreflightInfo, signal: AbortSignal) => Promise<ResumePreflightVerdict>;
     /**
      * design/380 O2 — the {@link resumePreflight} deadline in ms. Default 10s (its own bound,
-     * deliberately NOT the hooks-record default: a resume preflight sits on every redeem attempt of a
+     * deliberately its own: a resume preflight sits on every redeem attempt of a
      * parked row and must answer promptly or get out of the way). Bad values (non-finite, ≤ 0,
      * non-number) are DISCLOSED loudly through `onError` and fall back to the default (the bad-value
      * loudness default: announce, never silently absorb).
@@ -961,6 +963,19 @@ export interface RunnerDeps {
      * everywhere (mode parity, the CC default). Inert without {@link peerDirectory}.
      */
     crossSessionInbound?: import("../agents/cross-session-judge.js").CrossSessionInboundSettingLayers | (() => import("../agents/cross-session-judge.js").CrossSessionInboundSettingLayers);
+    /**
+     * WHO consumes this deployment's principal inbox (`principal.inbox`, where the
+     * organization's delivery gate appends cross-principal letters; the mailbox contract's fourth chain).
+     * Absent = no consumer, no lane (byte for byte as before); a deployment that mounts a gate DECLARES
+     * `{ assistant: "<agent handle>" }` (the scope's assistant is the only consumer; no terminal leg touches the
+     * box). `"terminals"` (each terminal drains the box as a second lane) is refused until held decisions are
+     * shared across terminals (`detail.reason: "terminals_unsupported"`). Letters are judged on the principal's
+     * `crossSessionInbound` layers (managed, user), held when unset. ANY other value fails the prepare of a leg
+     * that drains a session box with `config.principal_inbox_consumer_invalid` (`detail.reason: "malformed"`).
+     */
+    principalInboxConsumer?: "terminals" | {
+        assistant: string;
+    };
     /**
      * design/385 §4.4 (slice 4) — this deployment's `dialogExpiry` (CC settings key, verbatim vocabulary
      * `"60s" | "5m" | "10m" | "never"`, default `"5m"`): how long a HELD cross-session message whose cause
@@ -1117,7 +1132,7 @@ export interface RunnerDeps {
      * CLAUDE.md/git injection — the cure for "say hi → only greets"). The deployment/profile owns the CONTENT
      * (read CLAUDE.md / `.claude/` + fold in `git log -5`/status + a byte budget); core owns the seam + fence +
      * cache placement and NEVER hardcodes a filename (same trust posture as {@link executionEnvFactory}/
-     * {@link promptProvider}/{@link modelKnowledgeCutoffs}). A RunnerDeps FUNCTION, not a `TaskSpec` field: it is
+     * {@link mods}/{@link modelKnowledgeCutoffs}). A RunnerDeps FUNCTION, not a `TaskSpec` field: it is
      * unserializable (durable resume) and reading files for an UNTRUSTED caller would be a confused-deputy hole
      * (design/44 §7 Q4). DECOUPLED from `memoryStore` — injects even with NO long-term memory configured (H5).
      *
@@ -1189,8 +1204,6 @@ export interface RunnerDeps {
         path: string;
         contentHash: string | null;
     }> | null>;
-    /** Override system-prompt assembly. Defaults to `defaultPromptProvider`. */
-    promptProvider?: import("../prompts/default.js").PromptProvider;
     /**
      * design/99 §E23 — the LIVE-ONLY inbound-elicitation seam (an MCP server asking the END USER for input
      * mid-tool-call). Wired ONLY for servers that opted in via {@link McpServerSpec.elicitation}; absent ⇒ core
@@ -1269,20 +1282,13 @@ export interface RunnerDeps {
      */
     artifactHost?: import("./artifact-host.js").ArtifactHost;
     /**
-     * Default in-process hooks for all tasks (design/37) — the FULL lifecycle seam of the `Hooks`
-     * interface, not just the tool-call trio: `preToolUse` (rewrite/restrict args + inject context),
-     * `postToolUse` (rewrite output + inject context), `userPromptSubmit` (design/373 §4.3: screens
-     * EVERY user-lane entrance — the objective, a live `TaskStream.steer`, a wake resume's message,
-     * and a parked steer's redelivery, discriminated by `ctx.source`; a hook that blocks
-     * unconditionally refuses steers/wakes too — see the ⚠️ WIDENED INVOCATION SET banner on
-     * {@link import("./hooks.js").Hooks.userPromptSubmit}), plus `stop` (push back when the run would otherwise end and continue
-     * it), `postToolUseFailure` / `postToolBatch` / `permissionDenied` (failure, batch-boundary and
-     * deny observers), `preCompact` / `postCompact` (compaction gate + observer), `stopFailure`
-     * (API-error terminal observer) and the `preToolUseObservational` declaration flag — each member's
-     * contract is documented on the `Hooks` interface itself. A task's own `hooks` overrides this. A
-     * PreToolUse hook's `allow` never bypasses `toolPolicy` — the policy is always the final say.
-     */
-    hooks?: import("./hooks.js").Hooks;
+     * The deployment seat of the mods bus: extension registrations every task of this Runner carries (every leg — root,
+     * delegated child, resume — admits them at its own prepare). Each declares its tier (`prepend`, `user` or `append`;
+     * absent or another word refuses the prepare, `config.mods_invalid`). A task's own `TaskSpec.mods` run beside these,
+     * never instead of them. A `classic.PreToolUse` handler's `allow` never bypasses `toolPolicy` — the policy is always
+     * the final say.
+     */
+    mods?: readonly import("./mods/kernel/index.js").ModRegistration<import("./mods/dollar.js").EngineDollar>[];
     /**
      * Policy for remote image URLs (`TaskSpec.images[].url`). Return false to reject. When set it
      * **replaces** the built-in SSRF guard (https-only + private/reserved-host block) — e.g. supply a
@@ -1295,17 +1301,18 @@ export interface RunnerDeps {
      *   summaries) is invisible without this and lets a session grow until it tops the window.
      * - `"prompt-cache"` — a prefix-cache hazard on the wire: a detected cache break (design/31), or a
      *   mis-declared/mismatched `promptCacheFamily`. The prefix cache will miss. Log/alert on both.
-     * - `"prompt-constitution"` — a `stableSystem` provider returned an ALREADY-assembled prompt
-     *   (constitution anchor found); core passed it through un-doubled. Upgrade the provider to return
-     *   only the role base (or set `replaceAll: true` to own the whole base).
-     * - `"degraded"` — the task kept running with a capability quietly reduced: a question auto-answered
-     *   with no human present, a skipped env git snapshot, a lost checkpoint-put confirmation, an
-     *   unroutable descendant notification, and similar best-effort arms. The run proceeds; the reduced
-     *   arm is what is being disclosed (`classification` names it).
-     * - `"config"` — a deployment-wiring problem detected while preparing or tearing down a task: tool
-     *   mount conflicts, refused/ignored knob values, gate-off notices, store/env teardown legs. The
-     *   broadest class by call-site count — most misconfigurations announce here rather than failing
-     *   the task.
+     * - `"prompt-constitution"` — a prompt overlay did not take effect as written: a later source (or a later declaration in the same source) superseded
+     *   it on the same target, its target was not in this run's prompt, or a mods handler's `prompt.compose` answer was skipped (it rewrote another's
+     *   overlay, or wrote what the band table does not grant its seat); each overlay is named once per run. The center prompt too: a pinned session's
+     *   stored artifact refused or unreadable (it fails `prompt.snapshot_unavailable`), a fresh session's candidate that does not verify, and a
+     *   `CenterPromptSource` boot restore with no usable copy (`sessionId: ""`, `classification: "center-source-restore"`) — that last line only when the
+     *   host passes this same sink to `CenterPromptSource` as its own `onError` (the source restores at boot, apart from any Runner; given none, it is silent).
+     * - `"degraded"` — the task kept running with a capability quietly reduced: a question auto-answered with no human
+     *   present, a skipped env git snapshot, a lost checkpoint-put confirmation, an unroutable descendant notification, and
+     *   similar best-effort arms. The run proceeds; the reduced arm is what is being disclosed (`classification` names it).
+     * - `"config"` — a deployment-wiring problem detected while preparing or tearing down a task: tool mount conflicts,
+     *   refused/ignored knob values, gate-off notices, store/env teardown legs. The broadest class by call-site count — most
+     *   misconfigurations announce here rather than failing the task.
      * - `"memory"` — a post-task memory-consolidation pass failed or skipped a malformed reconcile
      *   decision (design/41). Best-effort: the notes the model saved are kept; the task still succeeds.
      * - `"mcp"` — an MCP server failed to connect / list its tools and was skipped (fail-open, design/29);
@@ -1496,7 +1503,7 @@ export interface RunnerDeps {
      * trusted control-plane injection), so it lives on `RunnerDeps` — NOT `TaskSpec`: `TaskSpec` is the
      * serializable, untrusted-caller, durable-resume-round-trippable per-task config (a function can be
      * neither serialized nor durably checkpointed, and the sandbox/env-class injections deliberately sit on
-     * `RunnerDeps` for the same trust reason). Same placement as `promptProvider` / `executionEnvFactory`.
+     * `RunnerDeps` for the same trust reason). Same placement as `mods` / `executionEnvFactory`.
      *
      * When `summaryProvider` is set, BOTH compaction call sites (the within-task turn boundary AND `finish()`
      * at task end) consult it: a NON-EMPTY string is reused verbatim (the real `generateSummary` LLM call is

package/dist/core/safety-merge-corpus.js

@@ -177,12 +177,28 @@ export const SAFETY_MERGE_CONFORMANCE_CORPUS = [
     },
     {
         name: "inert-deny-entry-removed-safe",
-        intent: "removing a deny entry that reads as nothing (an empty entry, a wildcard peer, a `__` name with no protocol prefix) relaxes nothing — the comparison reads the EFFECTIVE entries on both sides",
-        prior: { toolDeny: ["Bash", "", "mcp__*", "github__x"] },
+        intent: "removing a deny entry the grammar reads that names nothing (a wildcard peer, a `__` name with no protocol prefix) relaxes nothing — the comparison reads the EFFECTIVE entries on both sides",
+        prior: { toolDeny: ["Bash", "mcp__*", "github__x"] },
         next: { toolDeny: ["Bash"] },
         loosens: false,
         reasons: [],
     },
+    {
+        name: "unreadable-deny-prior-loosened",
+        intent: "rules whose toolDeny holds an entry no rule grammar reads (an empty entry) cannot be read and refuse every call — an override that can be read loosens them",
+        prior: { toolDeny: ["Bash", ""] },
+        next: { toolDeny: ["Bash"] },
+        loosens: true,
+        reasons: ['the prior rules refuse every call — their toolDeny holds "" (grammar), which no grammar reads'],
+    },
+    {
+        name: "unreadable-deny-next-safe",
+        intent: "an override whose toolDeny holds an entry no rule grammar reads refuses every call — it loosens nothing, whatever else it drops",
+        prior: { toolDeny: ["Bash"], allowDirs: ["/repo"] },
+        next: { toolDeny: [""] },
+        loosens: false,
+        reasons: [],
+    },
     {
         name: "inert-allow-entry-added-safe",
         intent: "adding an allowlist entry that reads as nothing admits nothing, so it widens nothing",

package/dist/core/secret-env.d.ts

@@ -4,8 +4,9 @@
  * A child the engine spawns may run what the MODEL chose (a tool shell, a gate over model-written code, a language
  * server). Under the `"scrub"` policy (the default) it inherits every variable but those the judgment below names —
  * deleted whole, never rewritten; `"all"` and a `string[]` allow list are the caller's explicit alternatives
- * ({@link inheritedHostEnv}). Whatever the policy, a name the deployment declares as its own credential
- * ({@link declareWithheldEnv}) is never inherited. One judgment per variable ({@link classifySecretEnvEntry}), the first rule that answers:
+ * ({@link inheritedHostEnv}). Whatever the policy, an entry that is this deployment's own credential is never inherited:
+ * its name is one the deployment declared, or its value equals a credential value the deployment declared or the
+ * engine holds ({@link declareWithheldEnv}, {@link holdOwnCredentialValues}). One judgment per variable ({@link classifySecretEnvEntry}), the first rule that answers:
  *   1. exempt — git's environment config and the proxy variables, handed on as written ({@link isExemptEnvName});
  *   2. `exact-name` — a known credential name (the vocabulary's exact env names);
  *   3. `prefix-rule` — the OpenTelemetry settings ({@link OTEL_ENV_RE});
@@ -26,8 +27,9 @@ import { type EngineNotice } from "./engine-notice.js";
  *  Reads the first {@link VALUE_SCAN_LIMIT} code units. The value half of the judgment, exported apart from the env
  *  entry's exemptions ({@link isExemptEnvName}): a caller holding a value that is no environment variable asks this. */
 export declare function looksLikeCredentialValue(value: string): boolean;
-/** Which rule withheld an entry: one of the scrub's rules, or `own-credential` — the deployment declared the name as its
- *  own credential ({@link declareWithheldEnv}), which every policy withholds. */
+/** Which rule withheld an entry: one of the scrub's rules, or `own-credential` — the entry is this deployment's own
+ *  credential (its name is declared, or its value equals a declared or engine-held credential value:
+ *  {@link declareWithheldEnv}), which every policy withholds. */
 export type SecretEnvFindingKind = "exact-name" | "name-rule" | "namespace-rule" | "prefix-rule" | "value-rule" | "own-credential";
 /** One env entry withheld (deleted) from a child's environment: its name — never its value, so the record is
  *  loggable —, the rule that withheld it, how strong that claim is, and the minting module. */
@@ -50,34 +52,100 @@ export declare function isSecretEnvKey(key: string, value?: string): boolean;
 export declare function scrubSecretEnv(env: NodeJS.ProcessEnv, findings?: SecretEnvFinding[]): NodeJS.ProcessEnv;
 /** How much of this process's environment a child spawned on this host inherits — the `inheritEnv` value. */
 export type InheritEnvPolicy = "all" | "scrub" | string[];
+/** What {@link declareWithheldEnv} takes: this deployment's own credentials in this process's environment. */
+export interface WithheldEnvDeclaration {
+    /** Names of variables that are this deployment's own credentials: never inherited, and an allow list naming one is refused. */
+    readonly names: readonly string[];
+    /** Credential values this deployment holds: an inherited entry whose value equals one — the same string, compared
+     *  whole, never as a part — is never inherited, whatever its name. A value must be a credential: not white space only,
+     *  a flag or placeholder word, one character repeated, or fewer than eight characters. */
+    readonly values: readonly string[];
+}
 /**
- * Declare the names of this deployment's OWN credentials in this process's environment — the engine's or its host's:
- * an approval bearer, a service token. From then on no child spawned on this host inherits one, whatever the policy:
- * every spawn site reads its environment through {@link inheritedHostEnv}, which subtracts them from `"all"` and from
- * the scrub's result (each one present is a finding of kind `own-credential`), and {@link inheritEnvPolicyProblem}
- * refuses an allow list naming one. Compared as the platform compares variable names: exactly, but case-blind on
- * Windows. A variable a host hands a child itself (a shell's `shellEnv`, a per-exec `env`, a language server's `env`, an MCP server entry's `env`)
- * is its explicit grant and is not read against the list.
+ * Declare this deployment's OWN credentials in this process's environment — the engine's or its host's: an approval
+ * bearer, a service token — by name and by value. From then on no child spawned on this host inherits one, whatever the
+ * policy: every spawn site reads its environment through {@link inheritedHostEnv}, which subtracts from `"all"`, from the
+ * scrub's result and from an allow list's every entry that is this deployment's own credential (each one present is a
+ * finding of kind `own-credential`), and {@link inheritEnvPolicyProblem} refuses an allow list naming a declared name.
+ * A NAME is compared as the platform compares variable names: exactly, but case-blind on Windows. A VALUE is compared
+ * whole, as the same string: an entry holding it as a part (`Bearer <value>`, a URL, an encoding of it) is not its value.
+ * Besides the declared values, every value the engine took in itself ({@link holdOwnCredentialValues}) is withheld the
+ * same way. A variable a host hands a child itself (a shell's `shellEnv`, a per-exec `env`, a language server's `env`,
+ * an MCP server entry's `env`) is its explicit grant and is not read against the table.
  *
- * Declared once, at start-up, before anything spawns; a later call REPLACES the list (a configuration reload), read
- * from the next spawn on — a spawn whose environment is already read (one announcing its findings) keeps it. The
- * list is copied. A malformed list — not an array, an entry that is no variable name, or a name the host hands every
- * child anyway ({@link runtimeSuppliedEnv}) — throws and leaves the declaration as it was.
+ * Declared once, at start-up, before anything spawns; a later call REPLACES the declaration whole (a configuration
+ * reload), read from the next spawn on — a spawn whose environment is already read (one announcing its findings) keeps
+ * it; the values the engine took in stay. The lists are copied, and a value is kept only as a digest (no credential is
+ * held by the table). A malformed table — not a plain object `{ names, values }` (the names-only list of earlier releases
+ * included), a member besides those two, a list that is a Proxy or whose element throws while it is read, a name that
+ * is no variable name or that the host hands every child anyway ({@link runtimeSuppliedEnv}), a value that is not a
+ * string a variable can hold or is no credential ({@link notACredentialReason}: white space only, a flag or placeholder
+ * word, one character repeated, fewer than {@link CREDENTIAL_MIN_CHARS} characters — withholding it would take a setting
+ * such as `CI=true` from every child) or that is, in this process's environment now, the value of such a variable —
+ * throws and leaves the declaration as it was. A value listed twice is the one value (the declaration is a set). No
+ * refusal sentence repeats a value.
  *
  * Two Windows readings, measured on a real machine: a withheld name that the child's own shell or runtime re-creates
  * with a DEFAULT of its own (`ComSpec`, `PATHEXT`, `HOME`, `CommonProgramFiles`, …) shows up in the child's table with
  * that default, never with this process's value — withheld, not leaked; and the disclosure (`detail.ownCredentials`)
  * spells each withheld name as this process's environment spells it, not as the declaration spelled it.
  */
-export declare function declareWithheldEnv(names: readonly string[]): void;
-/** Test seam: never called by production code (a host re-declares `[]`). */
+export declare function declareWithheldEnv(table: WithheldEnvDeclaration): void;
+/**
+ * The engine takes credential values in — each where the engine receives it: a first-party brain's construction
+ * credential (`brainConfigSnapshot`), a model entry's own credential headers (`resolveRouteCredential`), a protocol
+ * peer's credential headers (`resolveProtocolHttpHeaders`), the memory distiller's chat seat key (`openAiCompatChatSeat`,
+ * and `RunnerDeps.memoryConsolidationDriver.chat` at `new Runner`, before that seat is built). From then on, for the
+ * life of the process, no child spawned on this host inherits an entry whose value equals one: the same table, the same
+ * subtraction, finding and disclosure as a declared value ({@link declareWithheldEnv}). A credential the engine is handed
+ * per request (a per-model auth hook's answer) is not taken in: the host that resolves it owns it and declares it.
+ * An absent or empty value adds nothing. A value that is no credential ({@link notACredentialReason}: white space, a
+ * flag or placeholder word, one character repeated, fewer than {@link CREDENTIAL_MIN_CHARS} characters — the key a local
+ * gateway is told to be handed) is not taken in: its holder uses it as given (it is no bad value), and the variables
+ * that hold the same string stay with every child. Said once per process per value, never the value, as the notice
+ * `config.credential_not_withheld` through the engine's one notice throat ({@link deliverEngineNotice}): to `onNotice`
+ * when the intake has the structured seat in hand (the `RunnerDeps` receipt at `new Runner`), else as that notice's
+ * line on `console.warn` (the throat's own arm for an absent seat — a brain's construction, a request's route reading,
+ * a peer's dial, a directly built distiller seat). A value that is, in this process's
+ * environment now, the value of a variable every child is handed whatever the spawn passes cannot be withheld: the intake
+ * throws (`config.invalid_argument`, the variable named, never the value) and takes nothing in — the brain is not built,
+ * the peer is not dialed.
+ */
+export declare function holdOwnCredentialValues(values: Iterable<string | undefined>, onNotice?: (notice: EngineNotice) => void): void;
+/** THE one reading of which HTTP header carries a credential by its NAME — the credential vocabulary's header-name
+ *  reading ({@link isSensitiveHeaderName}: `Authorization`, `Proxy-Authorization`, `X-Api-Key`, Azure's `api-key`,
+ *  `x-goog-api-key`, `Cookie`, any name holding a credential word; not a gateway's own spelling of a name the
+ *  vocabulary declares non-secret, `cf-aig-cache-key` / `X-Idempotency-Key`). The reading of a record MEMBER's name
+ *  (`isSensitiveRecordKey`), which decides what a record shows, takes those declared names whole only. Every face that
+ *  asks "which header is a credential, by its name" reads this one: the withheld-value intake below
+ *  ({@link credentialHeaderValues}) and the route law — which bag carries a credential, which header values a per-model
+ *  credential's identity is read from, which headers the per-model winner strips, which the user-header merge leaves to
+ *  that strip, which the run-static stream options refuse. The NAME is the shared half: the intake adds a half of its
+ *  own, a value that looks like a credential under any name ({@link looksLikeCredentialValue}) — a guess it may make,
+ *  because withholding a value from a child costs little; the route law does not, because a header it reads as a
+ *  credential replaces the deployment's key and is bound to an origin, and a guess that is wrong drops a key that should
+ *  have gone out. */
+export declare function isCredentialHeaderName(name: string): boolean;
+/** Whether a credential header's value is `<auth-scheme> <credentials>` by definition (RFC 9110 §11.6.2 / §11.7.2:
+ *  `Authorization`, `Proxy-Authorization`) — the scheme word is public and the credentials part is the secret. Any other
+ *  credential header's value is opaque, read whole. */
+export declare function isSchemedCredentialHeader(name: string): boolean;
+/** The credential values a header bag carries: each header whose name is a credential header ({@link isCredentialHeaderName})
+ *  or whose value carries one ({@link looksLikeCredentialValue}), as written and, when it reads `<scheme> <credentials>`,
+ *  its credentials part too — the spelling a variable copied from it would carry. A schemed header's
+ *  ({@link isSchemedCredentialHeader}) value over a credentials part that is no credential (`Bearer 1`) gives that part
+ *  alone — the engine's intake then does not take it in — and not the whole value, which carries nothing else. Any other
+ *  header (`User-Agent`, `Accept`, a region) is no credential. */
+export declare function credentialHeaderValues(headers: Readonly<Record<string, string>> | undefined): string[];
+/** Test seam: never called by production code (a host re-declares `{ names: [], values: [] }`; what the engine took in stays). */
 export declare function __resetWithheldEnv(): void;
 /**
- * THE environment a child spawned ON THIS HOST inherits: the policy's arm, less the declared own credentials
- * ({@link declareWithheldEnv}). The arms: `"scrub"` (and absent) is this process's environment through
+ * THE environment a child spawned ON THIS HOST inherits: the policy's arm, less this deployment's own credentials — a
+ * declared name, or a value equal to a declared or engine-held credential value ({@link declareWithheldEnv},
+ * {@link holdOwnCredentialValues}). The arms: `"scrub"` (and absent) is this process's environment through
  * {@link scrubSecretEnv}; `"all"` is this process's environment as written; a `string[]` is exactly the named
  * variables that are set, as written — a strict allow list, so a name it leaves out (`PATH` included) is not
- * inherited. `findings` collects every entry withheld: the scrub's, and each declared own credential the arm held.
+ * inherited. `findings` collects every entry withheld: the scrub's, and each own credential the arm held.
  *
  * A policy {@link inheritEnvPolicyProblem} refuses throws that reason HERE, at every spawn, read against the
  * declaration as it stands: a value that is no policy at all (never read as the scrub), and an allow list naming a