@sema-agent/core 7.50.2 → 7.51.0

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 {};

package/dist/core/allow-entry.js

@@ -3,7 +3,7 @@ import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermission
 import { judgeRuleToolName, splitNamespacedName } from "./tool-name-aliases.js";
 import { catalogToolNames, isShellFaceToolName } from "./tool-registry.js";
 import { ALLOW_RULE_MEMBERS } from "./allow-rule-shadow.js";
-import { COMMAND_RULE_TOOL, adjudicatePersistedDomainRules, adjudicatePersistedNameRules, domainRuleSubjectOf, findAdmittingRule, laneToolNamesOf, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleToolGrammarOf } from "./permission-rule-model.js";
+import { COMMAND_RULE_TOOL, adjudicatePersistedDomainRules, adjudicatePersistedNameRules, commandCoverageOf, domainRuleSubjectOf, laneToolNamesOf, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleToolGrammarOf } from "./permission-rule-model.js";
 import { pathRuleLaneAnswer } from "./runner/permission-rule-lanes.js";
 import { callTargetReadingOf } from "./effective-path-target.js";
 import { splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
@@ -31,20 +31,21 @@ function mountedSpellingOf(name, roster) {
 }
 function toolNameReading(name, roster) {
     const verdict = judgeRuleToolName(name, roster);
+    if (verdict.kind === "unprefixed_namespace")
+        return { kind: "inert", reason: "tool_name", verdict: verdict.kind };
     if (verdict.kind !== "current") {
-        const currentName = verdict.kind === "unprefixed_namespace" ? undefined : verdict.currentName;
-        return { inert: "tool_name", detail: { verdict: verdict.kind, ...(currentName !== undefined ? { currentName } : {}) } };
+        return { kind: "inert", reason: "tool_name", verdict: verdict.kind, guidance: verdict.guidance, ...(verdict.currentName !== undefined ? { currentName: verdict.currentName } : {}) };
     }
     if (roster.has(name) || catalogToolNames().has(name) || splitNamespacedName(name) !== undefined)
         return undefined;
     const mounted = mountedSpellingOf(name, roster);
-    return mounted === undefined ? undefined : { inert: "near_miss", detail: { currentName: mounted } };
+    return mounted === undefined ? undefined : { kind: "inert", reason: "near_miss", currentName: mounted };
 }
-function readAllowEntry(raw, behavior, roster) {
-    const inert = (reason) => ({ inert: reason });
-    const row = (compiled) => ({ compiled });
+export function readRuleEntry(raw, behavior, roster) {
+    const inert = (reason) => ({ kind: "inert", reason });
+    const row = (compiled) => ({ kind: "row", compiled });
     if (typeof raw !== "string")
-        return { inert: "grammar", detail: { valueType: valueTypeLabel(raw) } };
+        return { kind: "inert", reason: "grammar", valueType: valueTypeLabel(raw) };
     if (raw !== raw.trim())
         return inert("grammar");
     const parsed = parsePermissionRule(raw);
@@ -82,26 +83,39 @@ function readAllowEntry(raw, behavior, roster) {
     }
     return inert(inertReasonOf(read.reject.code));
 }
+export function compiledEntryName(compiled) {
+    switch (compiled.kind) {
+        case "tool":
+        case "shell":
+            return compiled.name;
+        case "namespace":
+            return compiled.pattern;
+        default:
+            return compiled.rule.tool;
+    }
+}
 function inertReasonOf(code) {
     return code === "unsupported.tool" ? "content_unsupported" : "grammar";
 }
-export function compileAllowEntry(raw, behavior, roster) {
-    const read = readAllowEntry(raw, behavior, roster);
-    return "compiled" in read ? read.compiled : read.inert;
-}
 export function compileAllowList(entries, behavior, roster) {
-    const voided = behavior === "allow" && entries.some((e) => compileAllowEntry(e, behavior) === "wildcard_all");
+    const voided = behavior === "allow" && entries.some((e) => isWildcardAll(readRuleEntry(e, behavior)));
     const rows = [];
     const inert = [];
     for (const entry of entries) {
-        const read = typeof entry !== "string" || !voided ? readAllowEntry(entry, behavior, roster) : { inert: "wildcard_all" };
-        if ("compiled" in read)
+        const read = typeof entry !== "string" || !voided ? readRuleEntry(entry, behavior, roster) : { kind: "inert", reason: "wildcard_all" };
+        if (read.kind === "row")
             rows.push({ entry, compiled: read.compiled });
-        else
-            inert.push({ entry: typeof entry === "string" ? entry : nonStringMemberLabel(entry), reason: read.inert, ...read.detail });
+        else {
+            const { kind: _kind, ...why } = read;
+            void _kind;
+            inert.push({ entry: typeof entry === "string" ? entry : nonStringMemberLabel(entry), ...why });
+        }
     }
     return { rows, inert };
 }
+function isWildcardAll(read) {
+    return read.kind === "inert" && read.reason === "wildcard_all";
+}
 function answersTo(req, has) {
     return heldBy("allowEntry.names", { has }, req);
 }
@@ -164,7 +178,18 @@ function commandOf(req) {
     const command = req.args?.command;
     return tool !== undefined && typeof command === "string" ? { tool, command } : undefined;
 }
-export function judgeAllowEntries(rows, req, behavior, ctx) {
+function admissionCallOf(call, ctx, liveCwd, posture) {
+    return { tool: call.tool, command: call.command, cwd: ctx.root, ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}), ...(liveCwd !== undefined ? { execCwd: liveCwd } : {}), posture };
+}
+export function uncoveredCommandSegment(rows, req, ctx, posture) {
+    const call = commandOf(req);
+    if (call === undefined)
+        return undefined;
+    const rules = rows.flatMap((r) => (r.behavior === "allow" && r.compiled.kind === "command" ? [r.compiled.rule] : []));
+    const coverage = commandCoverageOf(rules, admissionCallOf(call, ctx, ctx.liveCwd(), posture));
+    return "uncovered" in coverage ? coverage.uncovered : undefined;
+}
+export function judgeAllowEntries(rows, req, behavior, ctx, posture = "grant") {
     const live = rows.filter((r) => r.behavior === behavior);
     if (live.length === 0)
         return undefined;
@@ -179,8 +204,8 @@ export function judgeAllowEntries(rows, req, behavior, ctx) {
             if (r.compiled.kind === "command")
                 byRule.set(r.compiled.rule, r);
         if (behavior === "allow") {
-            const covering = findAdmittingRule([...byRule.keys()], { tool: call.tool, command: call.command, cwd: ctx.root, ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}), ...(liveCwd !== undefined ? { execCwd: liveCwd } : {}) });
-            const hits = (covering ?? []).flatMap((rule) => byRule.get(rule) ?? []);
+            const coverage = commandCoverageOf([...byRule.keys()], admissionCallOf(call, ctx, liveCwd, posture));
+            const hits = ("covering" in coverage ? coverage.covering : []).flatMap((rule) => byRule.get(rule) ?? []);
             if (hits.length > 0)
                 return hits;
         }
@@ -319,7 +344,7 @@ export function readAllowRuleShadows(value) {
         return undefined;
     }
 }
-const SHADOW_REASON = {
+export const SHADOW_REASON = Object.freeze({
     content_question: "the call is the engine's own question to a person",
     hook: "a PreToolUse hook asks about this call — the deployment's own screening is answered by a person",
     ancestor: "the task that delegated this one owns this question",
@@ -328,8 +353,7 @@ const SHADOW_REASON = {
     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",
     transcript_write: "this write targets the session transcript — it is cleared by confirming this call, never by an allow rule",
     org_rule: "an organization policy rule requires approval for this call",
-    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",
-    rule_unreadable: "this call could not be read against a deny or ask rule, so whether one forbids it is unknown",
+    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",
     ask_rule: mandateDisclosureOf(undefined),
     denial_limit_fallback: "the auto-mode classifier refused too many calls in a row, so a person decides",
     classifier_no_ruling: "the auto-mode classifier could not judge this call, so a person decides",
@@ -346,7 +370,7 @@ const SHADOW_REASON = {
     mode: "the permission mode puts this question to a person",
     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",
     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",
-};
+});
 function memberPhrase(s) {
     const listed = `${s.entries.join(", ")}${s.omitted !== undefined ? ` and ${s.omitted} more` : ""}`;
     switch (s.member) {