@sema-agent/core 7.50.2 → 7.51.1

package/dist/brain/anthropic.js

@@ -7,7 +7,7 @@ import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCal
 import { emitBrainTelemetry, reportReasoningWireFacts } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, takeHeaderCasefold } from "./request-params.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
@@ -226,7 +226,9 @@ function closeToolUseBlock(acc, responseIds, closed) {
     acc.closedTc = { type: "toolCall", id: engineId, ...(wireId !== engineId ? { wireId } : {}), name: acc.toolName, arguments: args };
     return acc.closedTc;
 }
-export function createAnthropicBrain(config = {}) {
+const ANTHROPIC_LANE_DEFAULT = "https://api.anthropic.com";
+export function createAnthropicBrain(given = {}) {
+    const config = brainConfigSnapshot(given, "createAnthropicBrain config");
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
     refuseRetiredTimeoutKnobs(config, "construction", "createAnthropicBrain config");
     const doFetch = resolveFetch(config);
@@ -244,7 +246,7 @@ export function createAnthropicBrain(config = {}) {
             maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const { root, origin: rootOrigin } = resolveRequestRootOf(model.baseUrl, config.baseUrl, "https://api.anthropic.com");
+                const { root, origin: rootOrigin } = resolveRequestRootOf(model.baseUrl, config.baseUrl, ANTHROPIC_LANE_DEFAULT);
                 const routeCredential = resolveRouteCredential({
                     optionsApiKey: options?.apiKey,
                     optionsHeaders: options?.headers,
@@ -252,7 +254,7 @@ export function createAnthropicBrain(config = {}) {
                     configApiKey: config.apiKey,
                     configHeaders: config.headers,
                 });
-                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
+                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl, laneDefault: ANTHROPIC_LANE_DEFAULT });
                 if (!routeVerdict.ok)
                     throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
                 const apiKey = routeCredential.apiKey;
@@ -766,5 +768,5 @@ export function createAnthropicBrain(config = {}) {
             },
         });
     };
-    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
+    return { stream, adjudicateRoute: createBrainRouteJudge({ ...config, laneDefault: ANTHROPIC_LANE_DEFAULT }) };
 }

package/dist/brain/open-responses.d.ts

@@ -28,4 +28,4 @@ export interface OpenResponsesBrainConfig extends StreamEngineConfig {
  * Create a Brain that talks to an Open Responses endpoint. See the file header for the stateless
  * invariant, the capability-audit posture, and the reasoning-replay rule.
  */
-export declare function createOpenResponsesBrain(config?: OpenResponsesBrainConfig): Brain;
+export declare function createOpenResponsesBrain(given?: OpenResponsesBrainConfig): Brain;

package/dist/brain/open-responses.js

@@ -6,7 +6,7 @@ import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCal
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
@@ -219,7 +219,8 @@ function mapTerminalStopReason(incompleteReason, hadToolCalls) {
         return "length";
     return "stop";
 }
-export function createOpenResponsesBrain(config = {}) {
+export function createOpenResponsesBrain(given = {}) {
+    const config = brainConfigSnapshot(given, "createOpenResponsesBrain config");
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
     refuseRetiredTimeoutKnobs(config, "construction", "createOpenResponsesBrain config");
     const doFetch = resolveFetch(config);

package/dist/brain/openai.d.ts

@@ -57,4 +57,4 @@ export declare function inferMaxTokensField(modelId: string): "max_completion_to
  * machinery lives in the shared {@link runStreamingBrain} engine (design/32); this adapter owns the
  * OpenAI request shaping + chat-completions SSE parsing + finalization.
  */
-export declare function createOpenAIBrain(config?: OpenAIBrainConfig): Brain;
+export declare function createOpenAIBrain(given?: OpenAIBrainConfig): Brain;

package/dist/brain/openai.js

@@ -8,7 +8,7 @@ import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNot
 import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
 import { BrainError, providerErrorWord } from "./errors.js";
 import { inBandProviderError } from "./provider-dialect.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
@@ -323,7 +323,8 @@ export function inferMaxTokensField(modelId) {
         return "max_completion_tokens";
     return "max_tokens";
 }
-export function createOpenAIBrain(config = {}) {
+export function createOpenAIBrain(given = {}) {
+    const config = brainConfigSnapshot(given, "createOpenAIBrain config");
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
     refuseRetiredTimeoutKnobs(config, "construction", "createOpenAIBrain config");
     const doFetch = resolveFetch(config);

package/dist/brain/request-route.d.ts

@@ -16,7 +16,7 @@ import type { RouteCredential } from "../internal/llm.js";
  *    (`getApiKeyAndHeaders`), or an auth-bearing header declared on `Model.headers`. Paired by
  *    construction (the resolver was asked about THIS entry), so the adjudicator never refuses it.
  *  - `"deployment-config"` — the brain construction-time fallback (`config.apiKey` / an auth header
- *    in `config.headers`). Paired only with the deployment's own declared root (`config.baseUrl`).
+ *    in `config.headers`). Paired only with the deployment's own root (`config.baseUrl`, else the lane's default).
  *  - `"absent"` — no credential anywhere. Legal for keyless gateways; refused only where an entry
  *    declares its OWN URL away from a declared deployment root (a distinct endpoint with no
  *    credential route is a configuration hole, not a keyless deployment). */
@@ -64,7 +64,7 @@ export interface RouteCredentialPairingRow {
     readonly credentialKnobs: readonly string[];
     /** The root knob the credential is paired with: `"Model.baseUrl"` for a per-model credential (paired by
      *  construction — it was resolved for this entry), `"config.baseUrl"` for the deployment credential (paired only
-     *  when that root is declared and the request targets it; undeclared = the unpinned posture). Absent for
+     *  when the request targets that root — or, undeclared, the lane's own default endpoint). Absent for
      *  `"absent"`. */
     readonly pairsWith?: "Model.baseUrl" | "config.baseUrl";
 }

package/dist/brain/route-adjudicator.d.ts

@@ -15,13 +15,12 @@
  *  - `per-model` → OK always. A per-model credential was resolved FOR this entry (auth hook or an
  *    auth header on `Model.headers`); it is paired by construction, so the per-model lane pays no
  *    new cost.
- *  - `deployment-config` → OK only where the pairing is verifiable-and-true: the deployment DECLARED
- *    its credential's URL half (`config.baseUrl`) and the request targets exactly that root.
- *    A declared root with a diverging entry URL is the torn pair this module exists to stop
- *    (`route.credential_mismatch`). An UNDECLARED root (`config.apiKey` with no `config.baseUrl`)
- *    stays allowed as the `"unpinned"` posture — that is the documented single-endpoint quick-start
- *    shape (key on config, URL on the model) and refusing it would break every deployment built from
- *    it; the posture is surfaced so read faces can annotate the unverifiable pairing instead.
+ *  - `deployment-config` → a deployment credential has exactly ONE root: the one its brain sends to when
+ *    an entry names none — `config.baseUrl`, else the lane's own default endpoint
+ *    (`RoutePairingConfig.laneDefault`). A request to that root is `"paired"`; a request to any other
+ *    root — an entry carrying its own `baseUrl` — is the torn pair this module exists to stop
+ *    (`route.credential_mismatch`), whether or not the deployment wrote its root down. A key on the
+ *    config with the URL only on the model is that torn pair: nothing says the key belongs there.
  *  - `absent` → OK for keyless deployments (nothing to protect); refused as
  *    `route.credential_missing` only where an entry declares its OWN URL away from a DECLARED
  *    deployment root — a distinct endpoint with no credential route is a configuration hole, and a
@@ -180,10 +179,20 @@ export declare function applyRouteCredentialHeaders(merged: Record<string, strin
  * EXACTLY the resolution + judgment the brain's own request build runs (single source, two call
  * sites), so a pre-flight verdict and the request-time verdict can never disagree.
  */
+/** A brain's construction config, received ONCE by the engine's receipt law for caller objects
+ *  ({@link receiveOwnProperties}: a plain object, every own member read once): the request gate and the pre-flight
+ *  judge both read this frozen copy, so a config object mutated after construction moves neither and the two cannot
+ *  disagree about the root a credential is paired with. The header bag is a caller object too: it is received by the
+ *  same law from that one reading into a frozen bag of the copy's own. */
+export declare function brainConfigSnapshot<T extends {
+    headers?: Record<string, string>;
+}>(given: T, subject: string): Readonly<T>;
 export declare function createBrainRouteJudge(config: {
     apiKey?: string;
     baseUrl?: string;
     headers?: Record<string, string>;
+    /** The lane's own default endpoint (the brain's constant), when it has one. */
+    laneDefault?: string;
 }): (model: Model, perModelAuth?: {
     apiKey?: string;
     headers?: Record<string, string>;

package/dist/brain/route-adjudicator.js

@@ -1,5 +1,6 @@
 import { AUTH_CARRIER_NAMES } from "./request-params.js";
 import { BrainError } from "./errors.js";
+import { receiptRefusal, receiveOwnProperties } from "../core/own-property-receipt.js";
 const REDACTED_VALUE = "«redacted»";
 const REDACTED_CREDENTIALS = "[redacted-credentials]";
 function servableParse(raw) {
@@ -223,17 +224,21 @@ export function resolveRouteCredential(input) {
 export function adjudicateModelRoute(model, credential, config) {
     const entry = routeKeyOf(model.baseUrl);
     const declared = routeKeyOf(config.baseUrl);
-    const request = entry || declared;
+    const deploymentRoot = declared || routeKeyOf(config.laneDefault);
+    const request = entry || deploymentRoot;
     const entryShown = displayUrlOf(entry);
     const declaredShown = displayUrlOf(declared);
     const requestShown = displayUrlOf(request);
     if (credential.source === "per-model")
         return { ok: true, posture: "per-model" };
     if (credential.source === "deployment-config") {
-        if (declared === "")
-            return { ok: true, posture: "unpinned" };
-        if (request === declared)
+        if (request !== "" && request === deploymentRoot)
             return { ok: true, posture: "paired" };
+        const pairedWith = declared !== ""
+            ? `is paired with ${declaredShown}`
+            : deploymentRoot !== ""
+                ? `is paired with this brain's default endpoint ${displayUrlOf(deploymentRoot)} (config.baseUrl is unset)`
+                : `names no root of its own (config.baseUrl is unset)`;
         return {
             ok: false,
             code: "route.credential_mismatch",
@@ -242,8 +247,8 @@ export function adjudicateModelRoute(model, credential, config) {
                 entryBaseUrl: entryShown,
                 requestBaseUrl: requestShown,
                 configBaseUrl: declaredShown,
-                fixHint: `model "${model.id}" targets ${requestShown} but the deployment credential is paired with ${declaredShown}` +
-                    `${queryDifferenceNote(request, declared)}: ` +
+                fixHint: `model "${model.id}" targets ${requestShown || "no root"} but the deployment credential ${pairedWith}` +
+                    `${queryDifferenceNote(request, deploymentRoot)}: ` +
                     `give the model its own credential (a per-model key via getApiKeyAndHeaders, or an auth header on Model.headers), ` +
                     `or serve it through a brain whose config.baseUrl is the model's own root`,
             },
@@ -285,6 +290,17 @@ export function applyRouteCredentialHeaders(merged, credential, bags) {
             merged[k] = v;
     }
 }
+export function brainConfigSnapshot(given, subject) {
+    const words = { subject, unit: "member", moment: "at construction" };
+    const received = receiveOwnProperties(given, words);
+    const headers = received.headers;
+    if (headers !== undefined) {
+        if (headers === null || typeof headers !== "object")
+            throw receiptRefusal(`${subject}.headers must be an object of header names to values`);
+        Object.defineProperty(received, "headers", { value: Object.freeze(receiveOwnProperties(headers, { ...words, subject: `${subject}.headers`, unit: "header" })), enumerable: true });
+    }
+    return Object.freeze(received);
+}
 export function createBrainRouteJudge(config) {
     return (model, perModelAuth) => {
         const credential = resolveRouteCredential({
@@ -294,7 +310,7 @@ export function createBrainRouteJudge(config) {
             configApiKey: config.apiKey,
             configHeaders: config.headers,
         });
-        return adjudicateModelRoute(model, credential, { baseUrl: config.baseUrl });
+        return adjudicateModelRoute(model, credential, { baseUrl: config.baseUrl, laneDefault: config.laneDefault });
     };
 }
 export function routePairingStatus(brain, model, perModelAuth) {

package/dist/brain/route-conformance.js

@@ -101,12 +101,30 @@ export const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS = [
         leg: "named",
     },
     {
-        name: "deployment-unpinned",
-        intent: "the quick-start posture: config key with NO declared config root stays allowed (single-endpoint form: key on config, URL on the model) — surfaced as unpinned, not refused",
-        model: { id: "m-quickstart", baseUrl: "https://api.example.com/v1" },
-        credential: { source: "deployment-config", apiKey: "k-quickstart" },
+        name: "deployment-undeclared-entry-root",
+        intent: "a config key with NO declared root and an entry carrying its own root: nothing says the key belongs there — refused, never sent (declare config.baseUrl, or give the entry its own credential)",
+        model: { id: "m-catalogue", baseUrl: "https://api.example.com/v1" },
+        credential: { source: "deployment-config", apiKey: "k-deployment" },
         config: {},
-        expect: { ok: true, posture: "unpinned" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "named",
+    },
+    {
+        name: "deployment-lane-default",
+        intent: "a config key with no declared root is paired with the lane's own default endpoint — a request there is paired",
+        model: { id: "m-vendor", baseUrl: "https://api.vendor.example" },
+        credential: { source: "deployment-config", apiKey: "k-vendor" },
+        config: { laneDefault: "https://api.vendor.example" },
+        expect: { ok: true, posture: "paired" },
+    },
+    {
+        name: "deployment-lane-default-entry-elsewhere",
+        intent: "the same key with an entry rooted away from the lane default is refused, exactly like a declared root",
+        model: { id: "m-catalogue", baseUrl: "https://third-party.example.net/v1" },
+        credential: { source: "deployment-config", apiKey: "k-vendor" },
+        config: { laneDefault: "https://api.vendor.example" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "named",
     },
     {
         name: "absent-keyless-on-root",

package/dist/brain/stream-engine.js

@@ -9,7 +9,7 @@ import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.j
 import { bindBrainStatusEmitter, emitBrainStatus, emitBrainTelemetry, reportExtraBodyDropped } from "./status-sink.js";
 import { createAttemptController, firstByteWindow, refuseRetiredTimeoutKnobs, resolveFirstByteRetries, resolveWatchdogMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, } from "./timeout.js";
 import { readMember, thrownText } from "../core/thrown-value.js";
-import { redactSecrets } from "../core/untrusted-egress.js";
+import { egressText } from "../core/untrusted-egress.js";
 const DEFAULT_MAX_RETRIES = 10;
 const MAX_RETRIES_ENV_CEILING = 15;
 const MAX_RETRIES_ENV = "SEMA_MAX_RETRIES";
@@ -455,7 +455,7 @@ export function runStreamingBrain(args) {
                     };
                 };
                 try {
-                    r = await doFetch(req.url, { method: "POST", headers: req.headers, body: req.body, signal: cc.signal });
+                    r = await doFetch(req.url, { method: "POST", headers: req.headers, body: req.body, signal: cc.signal, redirect: "manual" });
                     requestIdSeen = readProviderRequestId(r);
                     if (cc.timedOut()) {
                         discardResponseBody(r);
@@ -474,7 +474,7 @@ export function runStreamingBrain(args) {
                     }
                     else if (classifyFetchThrow(e) === "request_unbuildable") {
                         cc.dispose();
-                        throw new BrainError("invalid_request", `${httpLabel} request could not be built: ${redactSecrets(stripUrlCredentials(thrownText(e)))}`);
+                        throw new BrainError("invalid_request", `${httpLabel} request could not be built: ${egressText("same-principal", stripUrlCredentials(thrownText(e)))}`);
                     }
                     else {
                         netErr = e;
@@ -486,6 +486,12 @@ export function runStreamingBrain(args) {
                     else
                         headerWait.stop();
                 }
+                if (r !== undefined && (r.type === "opaqueredirect" || (r.status >= 300 && r.status < 400))) {
+                    const status = r.status;
+                    discardResponseBody(r);
+                    cc.dispose();
+                    throw new BrainError("network", `${httpLabel} endpoint answered with a redirect${status > 0 ? ` (HTTP ${status})` : ""}; it was not followed and no credential was sent anywhere else — declare the final endpoint as the brain's baseUrl`);
+                }
                 if (r && r.ok && r.body) {
                     cc.clearTimer();
                     connect = cc;

package/dist/core/a2a.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { A2A_TASK_STATES } from "./a2a-task-state.js";
-import { resolveProtocolHttpHeaders } from "./mcp.js";
+import { assertEndpointBound, redirectPolicy, resolveProtocolHttpHeaders, underDeclaredHeaders } from "./protocol-http-auth.js";
 import { describeHttpTransportFailure } from "./mcp-failure.js";
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
 import { A2A_NAMESPACE } from "./protocol-table.js";
@@ -146,12 +146,8 @@ async function requestJson(t, what, init) {
         const res = await doFetch(init.url, {
             method: init.method,
             signal: deadline.signal,
-            headers: {
-                accept: "application/json",
-                "a2a-version": A2A_PROTOCOL_VERSION,
-                ...(init.body !== undefined ? { "content-type": "application/json" } : {}),
-                ...t.headers,
-            },
+            redirect: redirectPolicy(t.headers),
+            headers: underDeclaredHeaders({ accept: "application/json", "a2a-version": A2A_PROTOCOL_VERSION, ...(init.body !== undefined ? { "content-type": "application/json" } : {}) }, t.headers),
             ...(init.body !== undefined ? { body: init.body } : {}),
         });
         const text = await readBoundedText(res, `${what} from A2A peer "${inlineUntrusted(t.peer, A2A_ID_MAX_CHARS)}"`);
@@ -544,10 +540,12 @@ function buildSkillTool(spec, t, skill, lifecycle) {
         },
     };
 }
-async function materializePeer(spec, principal, lifecycle, signal) {
+async function materializePeer(declaredSpec, principal, lifecycle, signal) {
+    const spec = Object.freeze({ ...declaredSpec });
     const headers = resolveProtocolHttpHeaders(A2A_NAMESPACE.id, spec, principal);
     const discovery = { peer: spec.name, endpoint: spec.url, headers };
     const card = readCard(spec.name, await discoverCardBody(spec, discovery, signal), spec.url);
+    assertEndpointBound(A2A_NAMESPACE.id, spec.name, card.endpoint, spec.cardUrl === undefined ? [spec.url] : [spec.url, spec.cardUrl], headers);
     const transport = { peer: spec.name, endpoint: card.endpoint, headers };
     const tools = [];
     const axes = [];

package/dist/core/allow-entry.d.ts

@@ -1,7 +1,7 @@
 import { type RuleToolNameVerdict } from "./tool-name-aliases.js";
 import type { ToolCallRequest } from "./tool-policy.js";
 import { type AllowRuleMember, type AllowRuleShadow } from "./allow-rule-shadow.js";
-import { type PathRuleBases, type PersistedRule } from "./permission-rule-model.js";
+import { type AdmissionPosture, type PathRuleBases, type PersistedRule } from "./permission-rule-model.js";
 import { type AskClass, type AssertAllKeysHandled, type PermissionMode, type PersistedRuleMandate } from "./ask-origin.js";
 import { type ToolNameListReading } from "./tool-name-list.js";
 import { type EngineNotice } from "./engine-notice.js";
@@ -10,11 +10,13 @@ import { type EngineNotice } from "./engine-notice.js";
  *  run mounts no tool of that exact name but mounts one that differs only by case (`currentName` is its spelling). */
 export declare const ALLOW_ENTRY_INERT_REASONS: readonly ["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss"];
 export type AllowEntryInertReason = (typeof ALLOW_ENTRY_INERT_REASONS)[number];
-/** The facts beside a reason: for `tool_name` / `near_miss` the judgment's word and the spelling to write instead when there is
- *  one; for a list member that is not a string (`grammar`) the TYPE of the value (`a number`, `null`, `an object`…) — `entry` then
- *  holds {@link nonStringMemberLabel}, never the value. */
+/** The facts beside a reason: for `tool_name` / `near_miss` the judgment's word, the judgment's own one-line sentence when it has
+ *  one (`guidance`, byte for byte — `retired` and `unmintable_segment` carry one, `unprefixed_namespace` none) and the spelling to
+ *  write instead when there is one; for a list member that is not a string (`grammar`) the TYPE of the value (`a number`, `null`,
+ *  `an object`…) — `entry` then holds {@link nonStringMemberLabel}, never the value. */
 export interface AllowEntryInertDetail {
     readonly verdict?: Exclude<RuleToolNameVerdict["kind"], "current">;
+    readonly guidance?: string;
     readonly currentName?: string;
     readonly valueType?: string;
 }
@@ -60,18 +62,32 @@ export type CompiledAllowEntry = {
     readonly kind: "domain";
     readonly rule: PersistedRule;
 };
+/** What one rule entry means under one direction ({@link readRuleEntry}): the row the grammar compiles it to, or the reason it
+ *  reads as nothing with the facts a sentence about it names. */
+export type RuleEntryReading = {
+    readonly kind: "row";
+    readonly compiled: CompiledAllowEntry;
+} | ({
+    readonly kind: "inert";
+    readonly reason: AllowEntryInertReason;
+} & AllowEntryInertDetail);
 /**
- * Read one entry under one direction. `roster` = the tool names the run mounts (aliases included): given, the entry's tool name
- * is also read against it (a stale name, or one that differs from a mounted tool's only by case, reads as `tool_name` /
- * `near_miss`); absent, the grammar alone is read — what a resume's pre-claim screen can read before the leg has a roster.
+ * THE ONE READER of a rule entry — a member of an entry list in either direction: a skill's `allowed-tools` /
+ * `disallowed-tools`, a sub-agent's deny list, the request's and the deployment's `allowedTools`, a session's `toolDeny` /
+ * `toolAllow`. Every station that compiles, validates, compares or names such an entry reads this answer and no other.
+ * `roster` = the tool names the reader knows are mounted (aliases included): given, the entry's tool name is also read against
+ * it (a stale name, or one that differs from a mounted tool's only by case, reads as `tool_name` / `near_miss`); absent, the
+ * grammar alone is read — what a resume's pre-claim screen can read before the leg has a roster.
  */
-export declare function compileAllowEntry(raw: string, behavior: "allow" | "deny", roster?: ReadonlySet<string>): CompiledAllowEntry | AllowEntryInertReason;
+export declare function readRuleEntry(raw: unknown, behavior: "allow" | "deny", roster?: ReadonlySet<string>): RuleEntryReading;
+/** The tool name a compiled entry speaks for — its tool, its namespace spelling, or its rule's tool (what a name audit reads). */
+export declare function compiledEntryName(compiled: CompiledAllowEntry): string;
 /**
- * Compile one list WHOLE: the entries it reads and the ones it reads as nothing (each with its reason and, for a name the
- * roster refuses, the judgment's word and the spelling to write). An allow list holding `*` voids the list (every other entry
- * on it reads as nothing too: the list grants nothing — the safe direction). A `*` on a deny list reads as nothing by itself
- * and the rest of that list still refuses: a deny list never loses an entry to a wildcard beside it. `roster` as in
- * {@link compileAllowEntry}.
+ * Compile one list WHOLE through {@link readRuleEntry}: the entries it reads and the ones it reads as nothing (each with its
+ * reason and, for a name the roster refuses, the judgment's word and the spelling to write). An allow list holding `*` voids
+ * the list (every other entry on it reads as nothing too: the list grants nothing — the safe direction). A `*` on a deny list
+ * reads as nothing by itself and the rest of that list still refuses: a deny list never loses an entry to a wildcard beside
+ * it. `roster` as in {@link readRuleEntry}.
  */
 export declare function compileAllowList(entries: readonly string[], behavior: "allow" | "deny", roster?: ReadonlySet<string>): {
     rows: Array<{
@@ -107,16 +123,20 @@ export interface AllowEntryJudgeContext {
     readonly liveCwd: () => string | undefined;
     readonly anchors: PathRuleBases;
 }
+/** For a list whose allow rows admitted no call ({@link judgeAllowEntries}): the first segment of the call's command no command
+ *  row covers under `posture` — the word a refusal names; `undefined` when the call carries no command or no single segment is
+ *  to blame (a line the matcher cannot read at all). The same walk the matcher took. */
+export declare function uncoveredCommandSegment(rows: readonly AllowEntryRow[], req: ToolCallRequest, ctx: AllowEntryJudgeContext, posture: AdmissionPosture): string | undefined;
 /**
  * The ONE list matcher, both directions — the rows that speak for the call, or undefined. A tool-name row first (the first
  * that reaches the call); then the content rows, each family by the predicate the stored rows of that grammar meet:
- * COMMAND — allow: the persisted allow matcher's coverage (the whole command, or each segment covered by a row or read-only
- * by itself); deny: a row whose program run the call performs (the wide tightening reading; a call that cannot be read
- * against the row is refused too). PATH — the persisted path adjudication (allow: the narrow reading, every view of the
- * target inside what the row names; deny: any view reaching it). NAME / DOMAIN — the one predicate of each (the name the
- * call names, the host it fetches).
+ * COMMAND — allow: the persisted allow matcher's coverage under the list's {@link AdmissionPosture} (the whole command, or each
+ * segment covered by a row — or, for a `grant` list, read-only by itself); deny: a row whose program run the call performs (the
+ * wide tightening reading; a call that cannot be read against the row is refused too). PATH — the persisted path adjudication
+ * (allow: the narrow reading, every view of the target inside what the row names; deny: any view reaching it). NAME / DOMAIN —
+ * the one predicate of each (the name the call names, the host it fetches).
  */
-export declare function judgeAllowEntries<R extends AllowEntryRow>(rows: readonly R[], req: ToolCallRequest, behavior: "allow" | "deny", ctx: AllowEntryJudgeContext): readonly R[] | undefined;
+export declare function judgeAllowEntries<R extends AllowEntryRow>(rows: readonly R[], req: ToolCallRequest, behavior: "allow" | "deny", ctx: AllowEntryJudgeContext, posture?: AdmissionPosture): readonly R[] | undefined;
 /** The allow rows of a list, as the allow layer reads them in `mode`: the strip applied BEFORE the match (in `auto`). */
 export declare function allowingRows<R extends AllowEntryRow>(rows: readonly R[], req: ToolCallRequest, mode: PermissionMode | undefined): readonly R[];
 /** The two sources {@link AllowEntryTable} holds (a skill's list is the skill table's). */
@@ -159,7 +179,7 @@ export declare class AllowEntryTable {
     private held;
     private readonly heldEntries;
     /** Write a list's rows (a row already held is not held twice). Returns the entries that read as nothing. `roster` as in
-     *  {@link compileAllowEntry}: a list the leg itself wrote is read against it, a carried one (a delegating parent's capture) is not. */
+     *  {@link readRuleEntry}: a list the leg itself wrote is read against it, a carried one (a delegating parent's capture) is not. */
     seed(entries: readonly string[], roster?: ReadonlySet<string>): readonly AllowEntryInert[];
     /** The entries held, as written (a copy) — what a delegated child is handed. */
     entries(): readonly string[];
@@ -210,8 +230,9 @@ export declare function readAllowRuleShadows(value: unknown): readonly AllowRule
 /** Why a matched entry did not clear the ask, by the ask's class — one row per class, so a class added later is a
  *  compile error here rather than somebody else's reason on the card. Two facts the ask carries are read first, because
  *  they name the reason more exactly than a class shared by several: a table word (`mandate` — the exact mark) and the
- *  deployment's own authorship (`authoredBy`). */
-declare const SHADOW_REASON: {
+ *  deployment's own authorship (`authoredBy`) — {@link allowRuleShadowSentence} is the reader that applies that order.
+ *  Exported (frozen) so a host that renders the card's "why it cannot be cleared" half reads the engine's row, never a copy. */
+export declare const SHADOW_REASON: Readonly<{
     readonly content_question: "the call is the engine's own question to a person";
     readonly hook: "a PreToolUse hook asks about this call — the deployment's own screening is answered by a person";
     readonly ancestor: "the task that delegated this one owns this question";
@@ -220,8 +241,7 @@ declare const SHADOW_REASON: {
     readonly unverifiable_shell_text: "the text this shell will run cannot be read by the engine — it is cleared by confirming this call, never by an allow rule";
     readonly transcript_write: "this write targets the session transcript — it is cleared by confirming this call, never by an allow rule";
     readonly org_rule: "an organization policy rule requires approval for this call";
-    readonly governance_unavailable: "a source of governance for this call cannot currently be read (this deployment's organization policy, or a partition of the person's standing rules), so whether it forbids the call is unknown";
-    readonly rule_unreadable: "this call could not be read against a deny or ask rule, so whether one forbids it is unknown";
+    readonly rule_unreadable: "a rule that may govern this call cannot currently be read (this deployment's organization policy, a partition of the person's standing rules, or this call against a deny or ask rule), so whether one forbids it is unknown";
     readonly ask_rule: string;
     readonly denial_limit_fallback: "the auto-mode classifier refused too many calls in a row, so a person decides";
     readonly classifier_no_ruling: "the auto-mode classifier could not judge this call, so a person decides";
@@ -238,7 +258,7 @@ declare const SHADOW_REASON: {
     readonly mode: "the permission mode puts this question to a person";
     readonly unstated: "this call arrived already marked as requiring confirmation (an earlier layer of this run, or the task that delegated it, judged it so) — it is cleared by confirming this call, never by a standing allow rule";
     readonly ordinary: "this call arrived already marked as requiring confirmation (an earlier layer of this run, or the task that delegated it, judged it so) — it is cleared by confirming this call, never by a standing allow rule";
-};
+}>;
 /** The fence over the reason table: `never` while every class has a row. */
 export type ShadowReasonTableCoversEveryClass = AssertAllKeysHandled<Exclude<AskClass, keyof typeof SHADOW_REASON>>;
 /**
@@ -292,4 +312,3 @@ export declare function inertEntryPhrase(e: AllowEntryInert): string;
  * `disallowed-tools` holds such an entry is named as one that does not activate.
  */
 export declare function allowedToolsNotGrantedNotice(inert: readonly AllowEntryInertNote[], sessionId: string | undefined): EngineNotice;
-export {};