@sema-agent/core 7.54.1 → 7.55.0

package/dist/core/advisor-verdict.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The advisor seat's two answers, each minted here once and read by every reader: whether the advisor tool attaches for
+ * a (main model, advisor model) pair on a deployment ({@link advisorAttachVerdict} — the prepare mount, a host's advisor
+ * query and its echo all ask this one function), and whether a conversation has switched the advisor off
+ * ({@link advisorHoldOf} — read off the transcript, its only source of truth, at the mount, at every call and by a host).
+ * The closed sets the answers are spelled in live beside them.
+ */
+import type { SessionTreeEntry } from "../internal/harness-types.js";
+import { type BrainErrorCode } from "../brain/errors.js";
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { EngineNotice, Model, ModelRef, RunnerDeps } from "./types.js";
+/** The tool's wire name. */
+export declare const ADVISOR_TOOL_NAME = "advisor";
+/** What a fork is told when it inherits the advisor tool with its parent's prefix — the reference's sentence. */
+export declare const ADVISOR_FORK_SENTENCE = "Never consult the advisor tool.";
+/** Why the advisor tool is not attached on a leg whose spec names an advisor model. The first six are the static verdict's
+ *  answers; the last three are the mount's (the tool selector unmounted it, its route cannot pair, the transcript could
+ *  not be read). */
+export declare const ADVISOR_NOT_ATTACHED_REASONS: readonly ["disabled", "unknown_model", "advisor_unranked", "weakest_tier", "main_unranked", "pairing", "route_refused", "excluded", "hold_unknown"];
+export type AdvisorNotAttachedReason = (typeof ADVISOR_NOT_ATTACHED_REASONS)[number];
+/**
+ * Each reason's sentence to the person (`advisor.not_attached`, once per conversation per pair) — `null` for a reason that
+ * tells nobody: the deployment switched the advisor off (it is ignored), the deployment's tool selector unmounted it
+ * (`excluded`), or its route cannot pair with the deployment's credentials (`route_refused`, told to the operator by
+ * `route.seat_detached` — only an operator can fix it).
+ */
+declare const NOT_ATTACHED_SENTENCE: {
+    readonly disabled: null;
+    readonly unknown_model: (a: string) => string;
+    readonly advisor_unranked: (a: string) => string;
+    readonly weakest_tier: (a: string) => string;
+    readonly main_unranked: (_a: string, m: string) => string;
+    readonly pairing: (a: string, m: string) => string;
+    readonly route_refused: null;
+    readonly excluded: null;
+    readonly hold_unknown: () => string;
+};
+export type NotAttachedSentenceCoversEveryReason = AssertAllKeysHandled<Exclude<AdvisorNotAttachedReason, keyof typeof NOT_ATTACHED_SENTENCE>>;
+/** The shape door of `TaskSpec.advisorModel` (read only while the deployment switch is on): absent, a non-empty ref, or a
+ *  Model object; anything else refuses (`config.advisor_model_invalid`) — a model the engine cannot read names no advisor. */
+export declare function assertAdvisorModelShape(ref: unknown): void;
+/** The three faces of one advisor call: guidance came back, the advisor model refused, or no guidance could be had. */
+export declare const ADVISOR_OUTCOMES: readonly ["reviewed", "declined", "unavailable"];
+export type AdvisorOutcome = (typeof ADVISOR_OUTCOMES)[number];
+/** The static verdict: the advisor attaches on `model`, or does not and says why. */
+export type AdvisorAttachVerdict = {
+    readonly state: "on";
+    readonly model: Model;
+} | {
+    readonly state: "not_attached";
+    readonly reason: Exclude<AdvisorNotAttachedReason, "route_refused" | "excluded" | "hold_unknown">;
+};
+/**
+ * Whether the advisor tool attaches for `advisor` beside the run's `main` model, in command order: the deployment switch,
+ * then the advisor itself (a model the catalog cannot resolve, one on no declared tier, one on the weakest tier — `lite`,
+ * the tier the `haiku` alias names), then the main model (on no declared tier, or on a WEAKER tier than the advisor's:
+ * an advisor at least as capable as the main model attaches). Tiers are read by the classifier seat's own reading
+ * ({@link tierIndexOf}) over a catalog {@link normalizeSeatDeps} expanded, so a host holding raw deps gets the engine's
+ * answer. No tiers declared ⇒ no ranks ⇒ not attached.
+ */
+export declare function advisorAttachVerdict(args: {
+    deps: Pick<RunnerDeps, "models" | "tiers" | "advisorTool">;
+    main: Model;
+    advisor: ModelRef;
+}): AdvisorAttachVerdict;
+/**
+ * Which failure of an advisor request switches the advisor off for the conversation: the advisor model's credential refused
+ * (`auth`), or a provider 400 / 422 its minter ruled out as an over-window request (`invalid_request` with
+ * `inputTooLongRuledOut`) — deterministic client faults that repeat until the conversation is compacted. Every other code,
+ * an over-window refusal and an unclassified 400 pass (the next call may succeed). Total over the brain codes by its fence.
+ */
+export declare const ADVISOR_HOLD_CAUSES: Readonly<{
+    readonly auth: "hold";
+    readonly invalid_request: "hold_unless_window";
+    readonly rate_limit: "pass";
+    readonly server: "pass";
+    readonly network: "pass";
+    readonly http: "pass";
+    readonly stream_torn: "pass";
+    readonly refusal: "pass";
+    readonly length_empty: "pass";
+}>;
+/** What one failure's code does to the conversation's advisor ({@link ADVISOR_HOLD_CAUSES}). */
+export type AdvisorHoldDisposition = "hold" | "hold_unless_window" | "pass";
+export type HoldCausesCoverEveryBrainCode = AssertAllKeysHandled<Exclude<BrainErrorCode, keyof typeof ADVISOR_HOLD_CAUSES>>;
+/** What a failed advisor request said about itself — the fields the hold reads and the card carries. */
+export interface AdvisorFailure {
+    readonly code?: BrainErrorCode;
+    readonly errorKind?: "input_too_long" | "degenerate" | "length_empty";
+    readonly inputTooLongRuledOut?: true;
+}
+/** Whether this failure switches the advisor off for the conversation ({@link ADVISOR_HOLD_CAUSES}). */
+export declare function advisorFailureHolds(f: AdvisorFailure): boolean;
+/** The conversation's advisor switch-off, with the cause of the call that switched it. */
+export interface AdvisorHold {
+    readonly code?: BrainErrorCode;
+    readonly errorKind?: AdvisorFailure["errorKind"];
+}
+/**
+ * Whether the conversation on this branch has switched the advisor off, read off the transcript: an advisor tool result
+ * recorded after the latest compaction whose card says `hold: true` — the latest such card's cause. A compaction clears it
+ * (the card lands before it); a new conversation has none; a fork copies its parent's branch and with it the hold.
+ * `undefined` = not held. Members of a recorded card outside their closed sets are not carried.
+ */
+export declare function advisorHoldOf(entries: ReadonlyArray<SessionTreeEntry>): AdvisorHold | undefined;
+/** A not-attached reason the person is told about — its own fact or one they can act on — as a type. */
+export type AdvisorToldReason = {
+    [R in AdvisorNotAttachedReason]: (typeof NOT_ATTACHED_SENTENCE)[R] extends null ? never : R;
+}[AdvisorNotAttachedReason];
+/** Whether the person is told about this reason ({@link NOT_ATTACHED_SENTENCE}: the reasons with a sentence). */
+export declare function advisorReasonTold(reason: AdvisorNotAttachedReason): reason is AdvisorToldReason;
+/** The `advisor.not_attached` notice for a reason the person is told about. */
+export declare function advisorNotAttachedNotice(args: {
+    reason: AdvisorToldReason;
+    advisorModel: string;
+    mainModel: string;
+    sessionId: string;
+    runId?: string;
+}): EngineNotice;
+export {};

package/dist/core/advisor-verdict.js

@@ -0,0 +1,92 @@
+import { ALL_BRAIN_ERROR_CODES } from "../brain/errors.js";
+import { DEFAULT_TIER_ORDER, resolveModel } from "./roles.js";
+import { normalizeSeatDeps, tierIndexOf } from "./runner/classifier-ladder.js";
+export const ADVISOR_TOOL_NAME = "advisor";
+export const ADVISOR_FORK_SENTENCE = "Never consult the advisor tool.";
+export const ADVISOR_NOT_ATTACHED_REASONS = Object.freeze(["disabled", "unknown_model", "advisor_unranked", "weakest_tier", "main_unranked", "pairing", "route_refused", "excluded", "hold_unknown"]);
+const NOT_ATTACHED_SENTENCE = {
+    disabled: null,
+    unknown_model: (a) => `The advisor model "${a}" is not in this deployment's model catalog, so the advisor is off.`,
+    advisor_unranked: (a) => `"${a}" cannot be used as an advisor: the deployment declares no tier for it (declare RunnerDeps.tiers so the engine knows which model is stronger).`,
+    weakest_tier: (a) => `"${a}" cannot be used as an advisor: it is on the weakest tier.`,
+    main_unranked: (_a, m) => `The advisor will not activate on the main model (${m}): the deployment declares no tier for it (declare RunnerDeps.tiers). Subagents may still use it.`,
+    pairing: (a, m) => `${a} is less capable than the current main model (${m}), so the advisor will not activate. Choose a more capable advisor, or switch to a smaller main model.`,
+    route_refused: null,
+    excluded: null,
+    hold_unknown: () => `The advisor is off for this run: whether this conversation had switched it off could not be read.`,
+};
+export function assertAdvisorModelShape(ref) {
+    if (ref === undefined || (typeof ref === "string" ? ref !== "" : typeof ref === "object" && ref !== null && typeof ref.id === "string"))
+        return;
+    const shown = typeof ref === "string" ? "an empty string" : ref === null ? "null" : Array.isArray(ref) ? "an array" : typeof ref;
+    throw Object.assign(new Error(`TaskSpec.advisorModel must be a non-empty model ref or a Model (got ${shown}) — a model the engine cannot read names no advisor.`), { code: "config.advisor_model_invalid" });
+}
+export const ADVISOR_OUTCOMES = Object.freeze(["reviewed", "declined", "unavailable"]);
+export function advisorAttachVerdict(args) {
+    if (args.deps.advisorTool === "disabled")
+        return { state: "not_attached", reason: "disabled" };
+    const deps = normalizeSeatDeps(args.deps);
+    let advisor;
+    try {
+        advisor = resolveModel(args.advisor, deps.models);
+    }
+    catch {
+        return { state: "not_attached", reason: "unknown_model" };
+    }
+    const advisorTier = tierIndexOf(deps, advisor);
+    if (advisorTier === undefined)
+        return { state: "not_attached", reason: "advisor_unranked" };
+    if (advisorTier === DEFAULT_TIER_ORDER.indexOf("lite"))
+        return { state: "not_attached", reason: "weakest_tier" };
+    const mainTier = tierIndexOf(deps, args.main);
+    if (mainTier === undefined)
+        return { state: "not_attached", reason: "main_unranked" };
+    if (advisorTier > mainTier)
+        return { state: "not_attached", reason: "pairing" };
+    return { state: "on", model: advisor };
+}
+export const ADVISOR_HOLD_CAUSES = Object.freeze({
+    auth: "hold",
+    invalid_request: "hold_unless_window",
+    rate_limit: "pass",
+    server: "pass",
+    network: "pass",
+    http: "pass",
+    stream_torn: "pass",
+    refusal: "pass",
+    length_empty: "pass",
+});
+export function advisorFailureHolds(f) {
+    if (f.code === undefined)
+        return false;
+    const row = ADVISOR_HOLD_CAUSES[f.code];
+    return row === "hold" || (row === "hold_unless_window" && f.errorKind !== "input_too_long" && f.inputTooLongRuledOut === true);
+}
+const ERROR_KINDS = new Set(["input_too_long", "degenerate", "length_empty"]);
+export function advisorHoldOf(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (e.type === "compaction")
+            return undefined;
+        if (e.type !== "message" || e.message.role !== "toolResult" || e.message.toolName !== ADVISOR_TOOL_NAME)
+            continue;
+        const d = e.message.details;
+        if (d === null || typeof d !== "object" || d.type !== "advisor" || d.hold !== true)
+            continue;
+        const code = ALL_BRAIN_ERROR_CODES.find((c) => c === d.code);
+        const errorKind = typeof d.errorKind === "string" && ERROR_KINDS.has(d.errorKind) ? d.errorKind : undefined;
+        return { ...(code !== undefined ? { code } : {}), ...(errorKind !== undefined ? { errorKind } : {}) };
+    }
+    return undefined;
+}
+export function advisorReasonTold(reason) {
+    return NOT_ATTACHED_SENTENCE[reason] !== null;
+}
+export function advisorNotAttachedNotice(args) {
+    const sentence = NOT_ATTACHED_SENTENCE[args.reason];
+    return {
+        code: "advisor.not_attached",
+        message: sentence(args.advisorModel, args.mainModel),
+        detail: { advisorModel: args.advisorModel, mainModel: args.mainModel, reason: args.reason, sessionId: args.sessionId, ...(args.runId !== undefined ? { runId: args.runId } : {}) },
+    };
+}

package/dist/core/agent-definition.d.ts

@@ -19,8 +19,7 @@ export interface AgentDefinition {
     /** Guidance shown to the model for WHEN to pick this agent (listed in the delegation tool's description). */
     whenToUse?: string;
     /**
-     * F4 (CC 2.1.198 parity, `whenToUseLean` — 锚 pretty.js:409174 `rbm` + selection `tIl` :453029
-     * `(lean && e.whenToUseLean) || e.whenToUse`): a SHORT variant of {@link whenToUse} preferred on
+     * F4 (`whenToUseLean`): a SHORT variant of {@link whenToUse} preferred on
      * lean-prompt surfaces. sema posture: the engine runs the CC lean-prompt arm wholesale (web.ts
      * lean-card precedent), so roster listings/descriptions prefer this text whenever present;
      * {@link whenToUse} remains the fallback. Optional — a single-text agent behaves exactly as before.
@@ -36,7 +35,7 @@ export interface AgentDefinition {
     /** Tool denylist (a deny always wins), tool NAMES: `Tool(content)` hides the whole `Tool`. See {@link allowTools} for the per-agent delegation-tool note. */
     denyTools?: string[];
     /**
-     * F7 (CC 2.1.198 parity, per-agent `skills` — 锚 pretty.js:422126 `e.skills ?? []`, GA/ungated in 198:
+     * F7 (per-agent `skills`:
      * CC preloads each named skill's prompt content into the child's opening messages, warning on misses).
      * sema shape: full {@link SkillSpec} objects (sema has no ambient skill registry to resolve bare names
      * against) threaded into the chosen child's `TaskSpec.skills` — disclosed in its `<skills>` block +
@@ -44,7 +43,7 @@ export interface AgentDefinition {
      */
     skills?: SkillSpec[];
     /**
-     * F7 (CC 2.1.198 parity, per-agent `background` — 锚 pretty.js:453611 `H.background===!0` OR-ed into
+     * F7 (per-agent `background`, OR-ed into
      * the background predicate, GA/ungated): `true` = this agent ALWAYS launches on the background lane
      * (an omitted `run_in_background` no longer means sync, and the per-call parameter cannot force sync —
      * CC-same OR semantics). Requires the delegation tool's `background` surface; without one the child
@@ -52,7 +51,7 @@ export interface AgentDefinition {
      */
     background?: boolean;
     /**
-     * F7 (CC 2.1.198 parity, per-agent `isolation` — 锚 pretty.js:453599 `z = a ?? H.isolation`, GA):
+     * F7 (per-agent `isolation`):
      * default isolation for this agent; an explicit per-call `isolation` argument wins. sema supports
      * `"worktree"` (CC's `"remote"` arm is a claude.ai-session concern, not ported).
      */
@@ -86,8 +85,8 @@ export interface AgentDefinition {
      */
     memoryPersistenceCapable?: boolean;
     /**
-     * Observer agents (CC 2.1.206 parity — 逐字锚 docs/CC206-OBSERVER-ANCHORS-2026-07-11.md, schema
-     * 面 C @28385708): "Agent type auto-spawned as a background observer whenever this agent runs.
+     * Observer agents (schema
+     * 面 C): "Agent type auto-spawned as a background observer whenever this agent runs.
      * The observer receives read-only activity digests and reports via the ObserverReport tool; it
      * never participates in the task." Resolution is warn-and-unobserved on an unknown type and
      * refuses chaining (an observer's own `observer` declaration is ignored). Gated by
@@ -116,7 +115,7 @@ export interface SkillSpec {
      * either list asks once (`Execute skill: <name>`, the card listing what it releases); a skill the person invoked by
      * name ({@link import("./task-spec.js").TaskSpec.userInvokedSkills}) grants without asking. The grant holds for that
      * run (a steer it takes in does not end it) and the next runTask starts without it. An entry this grammar reads as nothing — `*` (it voids an allow list; on a deny list it is inert and the rest of the
-     * list still refuses), `mcp__*`, a write path, a domain — grants nothing and is announced at the start of the run (`permission.allowed_tool_not_granted`). A table whose value is not a list (a string, an object…) reads as one such entry; `null` is no table.
+     * list still refuses), `mcp__*` / `mcp__*__*` (an allow entry names a peer), a write path, a domain — grants nothing and is announced at the start of the run (`permission.allowed_tool_not_granted`). A table whose value is not a list (a string, an object…) reads as one such entry; `null` is no table.
      */
     allowedTools?: string[];
     /** The tools refused for the rest of the run this skill is activated in — the frontmatter `disallowed-tools` list,

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

@@ -126,7 +126,7 @@ export declare function compileAllowList(entries: readonly string[], behavior: "
     inert: AllowEntryInert[];
 };
 /** The programs whose open allow rule the reference implementation drops in auto mode — its interpreter / launcher table
- *  plus the shells and the run-anything builtins (2.1.280). A program that only reaches the network is not here. */
+ *  plus the shells and the run-anything builtins. A program that only reaches the network is not here. */
 export declare const AUTO_STRIPPED_PROGRAMS: readonly ["python", "python3", "python2", "node", "deno", "tsx", "ruby", "perl", "php", "lua", "npx", "bunx", "npm run", "yarn run", "pnpm run", "bun run", "bash", "sh", "ssh", "zsh", "fish", "eval", "exec", "env", "xargs", "sudo"];
 /**
  * Does auto mode strip this allow entry for this call (see the module doc)? Read for every rule-shaped member — a list
@@ -163,17 +163,23 @@ export declare function uncoveredCommandSegment(rows: readonly AllowEntryRow[],
  * 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); a keyed tool's call naming no value for its key is
- * refused by a deny list's row of the key and granted by no allow row (the persisted walk's reading, `keyedValueAbsentReason`).
+ * the one predicate of each (the name the call names, the host it reaches — a deny row read on the protective reading, an allow
+ * row on the tool's own declared slot, `callHostTargetOf`; a mounted name tool's value resolved against the agent types the call's
+ * face carries, `nameRuleReach`); a closed-set tool's call naming no value is refused by a deny list's row of the tool and granted
+ * by no allow row (the persisted walk's reading, `nameValueAbsentReason`), a mounted tool's call whose face carries no values is
+ * refused by a deny list's row of the tool and granted by no allow row, and a call whose host cannot be read is refused by a deny
+ * list's host row and granted by no allow row (`adjudicatePersistedDomainRules`).
  */
 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). */
 export type AllowEntrySource = "request" | "deployment";
-/** What spoke for a call: the entries it stands on, as the list spells them. */
+/** What spoke for a call: the entries it stands on, as the list spells them, and — for entries of the list the run received —
+ *  the index of every element of that list that is one of them (a string listed twice has both). */
 export interface AllowEntryHit {
     readonly entries: readonly string[];
+    readonly positions?: readonly number[];
 }
 /** The face the gate reads one entry list through. */
 export interface AllowEntryLane {
@@ -208,9 +214,16 @@ export interface AllowEntryGateSeats {
 export declare class AllowEntryTable {
     private held;
     private readonly heldEntries;
+    /** Each entry of the list the run RECEIVED for this source, with its indices in that list — what a hit's `positions` read. */
+    private receivedAt;
     /** Write a list's rows (a row already held is not held twice). Returns the entries that read as nothing. `roster` as in
-     *  {@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[];
+     *  {@link readRuleEntry}: a list the leg itself wrote is read against it, a carried one (a delegating parent's capture) is not.
+     *  `received`: this list is the one the run received for the source (the request's `TaskSpec.allowedTools`, the deployment's
+     *  `RunnerDeps.allowedTools`), the list a hit's positions are read in; a carried capture is not. */
+    seed(entries: readonly string[], reading?: {
+        readonly roster?: ReadonlySet<string>;
+        readonly received?: true;
+    }): readonly AllowEntryInert[];
     /** The entries held, as written (a copy) — what a delegated child is handed. */
     entries(): readonly string[];
     /** Does the table hold a path row — must the leg read each call's target views for it? */
@@ -245,21 +258,32 @@ export declare function withDeploymentAllowedTools<D extends {
 }>(deps: D): D;
 /** The code a list value that is not a list of strings refuses with — the policy compiler's family, with its issues. */
 export declare const INVALID_PERMISSION_RULES_CODE = "config.invalid_permission_rules";
+/** The two seats an allow list is handed over at — the library coordinates the refusal carries as `libraryOption`, each with the
+ *  words the sentence says instead. */
+declare const ALLOW_LIST_SEATS: {
+    readonly "TaskSpec.allowedTools": "the request's allow list";
+    readonly "RunnerDeps.allowedTools": "the deployment's allow list";
+};
+type AllowedToolsSeat = keyof typeof ALLOW_LIST_SEATS;
 /**
- * Screen and snapshot one `allowedTools` value (`seat` names the key in the refusal): absent ⇒ undefined; a list of strings
- * ⇒ a frozen copy (the one read every later reader takes); anything else refuses loudly with
- * {@link INVALID_PERMISSION_RULES_CODE} and an issue per defect — never dropped, never read as "no entries".
+ * Screen and snapshot one `allowedTools` value (`seat` is the seat it was handed at; the sentence says it in words, the issues'
+ * `libraryOption` names it): absent ⇒ undefined; a list of strings ⇒ a frozen copy (the one read every later reader takes);
+ * anything else refuses loudly with {@link INVALID_PERMISSION_RULES_CODE} and an issue per defect — never dropped, never read
+ * as "no entries".
  */
-export declare function screenAllowedToolsValue(value: unknown, seat: string): readonly string[] | undefined;
+export declare function screenAllowedToolsValue(value: unknown, seat: AllowedToolsSeat): readonly string[] | undefined;
 /** The disclosure record for one member, minted from the entries it matched: each sanitized (deployment or model-authored
  *  text on a human trust boundary) and capped, the rest counted. */
 export declare function allowRuleShadowOf(member: AllowRuleMember, entries: readonly string[]): AllowRuleShadow;
 /** Read a disclosure value off a decision WITHOUT trusting it (a policy's own value, an ancestor's): every record a known
  *  member with a list of strings, or nothing — a display member must never throw where a card is minted. */
 export declare function readAllowRuleShadows(value: unknown): readonly AllowRuleShadow[] | undefined;
-/** 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
+/** The ask class whose reason is not a row: `probe` is the class of a FINDING about this very call (the read station's, or a
+ *  probe's), and only the ask's own account of it — its `probeReason` — can say which ({@link allowRuleShadowSentence}). */
+export type AccountedClass = "probe";
+/** Why a matched entry did not clear the ask, by the ask's class — one row per class that has a reason of its own, 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`) — {@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<{
@@ -272,26 +296,25 @@ export declare const SHADOW_REASON: Readonly<{
     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 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 ask_rule: "an explicit ask rule matched this call (a person's or the deployment's ask-me-each-time outranks a standing allow rule)";
     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";
     readonly requires_user_interaction: "this tool's server declares that a call must be put to a person";
-    readonly cross_boundary: string;
+    readonly cross_boundary: "this run executes on a device outside the deployment's trust boundary and the deployment is multi-tenant, so an org-side write — or, after an off-target read, a call bound for the device — is confirmed by the deployment's approver for this call: no standing allow rule and no automatic lane answers for it, and an allow the configuration gives (a blanket seat or a policy's answer) is refused";
     readonly operator_forced: "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 shell_floor: string;
-    readonly target_unresolved: string;
-    readonly probe: string;
-    readonly write_protection: string;
-    readonly tool_marks_mcp: string;
-    readonly tool_marks_a2a: string;
+    readonly shell_floor: "this deployment mandates per-call confirmation for shell commands (shellGate: always)";
+    readonly target_unresolved: "where this write leads on disk could not be determined (a link on the way could not be examined, or the environment could not resolve the target), so whether it lands on a guarded path is unknown — it is cleared by confirming this call: no standing rule and no automatic decider answers for it, though a wired approver seat can";
+    readonly write_protection: "this write's target is on the deployment's write-protection table (the agent's own configuration is guarded one look per write) — it is cleared by confirming this call, never by a standing allow rule";
+    readonly tool_marks_mcp: "this tool carries egress/irreversibility/interaction marks (a mandated confirmation a rule cannot clear)";
+    readonly tool_marks_a2a: "this tool carries egress/irreversibility/interaction marks (a mandated confirmation a rule cannot clear)";
     readonly policy_rra: "the deployment's policy requires a real approval for this call";
     readonly artifact_shared_read: "this read targets another task's shared artifact — it is cleared by confirming this call";
     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>>;
+/** The fence over the reason table: `never` while every class that has a reason of its own has a row. */
+export type ShadowReasonTableCoversEveryClass = AssertAllKeysHandled<Exclude<AskClass, keyof typeof SHADOW_REASON | AccountedClass>>;
 /**
  * The disclosure in the sentence a PERSON reads — rendered where a card or a park row is minted, never onto the decision
  * the classifier reads: "<members> match(es) this call but do(es) not clear the ask — <why>".
@@ -300,6 +323,7 @@ export declare function allowRuleShadowSentence(shadows: readonly AllowRuleShado
     askClass?: AskClass;
     mandate?: PersistedRuleMandate;
     authoredBy?: "deployment";
+    probeReason?: string;
 }): string;
 /** The card's two disclosure members off a surviving ask, minted at every station that builds an approval request: the
  *  sanitized records, and the message with the sentence rendered onto it. */
@@ -309,6 +333,7 @@ export declare function cardDisclosureOf(decision: {
     askClass?: AskClass;
     mandate?: PersistedRuleMandate;
     authoredBy?: "deployment";
+    probeReason?: string;
 }, fallbackMessage: string): {
     message: string;
     allowRuleShadowed?: readonly AllowRuleShadow[];
@@ -348,3 +373,4 @@ 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

@@ -1,15 +1,16 @@
 import { heldBy } from "./tool-name-readings.js";
-import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "./permission-rules.js";
+import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, ruleIssue } from "./permission-rules.js";
 import { parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
 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, commandCoverageOf, domainRuleSubjectOf, laneToolNamesOf, nameRuleSubjectOf, noticeRuleText, parseRuleText, programRunReachOf, ruleToolGrammarOf } from "./permission-rule-model.js";
+import { callHostTargetOf } from "./host-target.js";
+import { COMMAND_RULE_TOOL, adjudicatePersistedDomainRules, adjudicatePersistedNameRules, commandCoverageOf, laneToolNamesOf, ruleContentOf, noticeRuleText, parseRuleText, programRunReachOf, ruleToolGrammarOf, commandPatternMayRun } 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";
-import { mandateDisclosureOf } from "./ask-origin.js";
-import { inlineUntrusted } from "./untrusted-text.js";
+import { ASK_RULE_DISCLOSURE, MANDATE_DISCLOSURE, mandateDisclosureOf } from "./ask-origin.js";
+import { inlineUntrusted, isMintableProbeReason } from "./untrusted-text.js";
 import { valueTypeLabel } from "./tool-name-list.js";
 import { deliverEngineNotice } from "./engine-notice.js";
 export const ALLOW_ENTRY_INERT_REASONS = Object.freeze(["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss", "earlier_grammar"]);
@@ -38,8 +39,8 @@ export function nearMissSpellingOf(name, roster) {
 export function rootFacingToolNames(carried) {
     return new Set([...catalogToolNames(), ...carried]);
 }
-function toolNameReading(name, roster) {
-    const verdict = judgeRuleToolName(name, roster);
+function toolNameReading(name, roster, behavior) {
+    const verdict = judgeRuleToolName(name, roster, behavior);
     if (verdict.kind === "unprefixed_namespace")
         return { kind: "inert", reason: "tool_name", verdict: verdict.kind };
     if (verdict.kind !== "current") {
@@ -60,15 +61,15 @@ export function readRuleEntry(raw, behavior, roster) {
     if (name === "*")
         return inert("wildcard_all");
     if (roster !== undefined) {
-        const stale = toolNameReading(name, roster);
+        const stale = toolNameReading(name, roster, behavior);
         if (stale !== undefined)
             return stale;
     }
-    if (parsed.ruleContent === undefined) {
+    if (ruleContentOf(parsed) === undefined) {
         const split = splitNamespacedName(name);
         if (split !== undefined) {
             if (split.peer.includes("*"))
-                return inert("namespace_wildcard");
+                return isNamespacedCoveringRuleName(name, behavior) ? row({ kind: "namespace", pattern: name }) : inert("namespace_wildcard");
             if (isNamespacedCoveringRuleName(name))
                 return row({ kind: "namespace", pattern: name });
             return row({ kind: "tool", name });
@@ -158,7 +159,7 @@ export function autoStripped(compiled, call) {
         case "tool":
             return call !== undefined && answersTo(call, isShellFaceToolName);
         case "command":
-            return shellContentStripped(shellRuleContent(compiled.rule));
+            return compiled.rule.match === "pattern" ? commandPatternMayRun(compiled.rule.command, AUTO_STRIPPED_PROGRAMS) : shellContentStripped(shellRuleContent(compiled.rule));
         case "namespace":
         case "path":
         case "name":
@@ -240,7 +241,8 @@ export function judgeAllowEntries(rows, req, behavior, ctx, posture = "grant") {
         const table = familyRows.map((r) => r.compiled.rule);
         for (const name of laneToolNamesOf(req).filter((n) => ruleToolGrammarOf(n) === grammar)) {
             const at = { tool: name, cwd: ctx.root, ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}) };
-            const verdict = grammar === "name" ? adjudicatePersistedNameRules(table, { ...at, name: nameRuleSubjectOf(name, req.args) }) : adjudicatePersistedDomainRules(table, { ...at, host: domainRuleSubjectOf(name, req.args) });
+            const named = { ...req, toolName: name };
+            const verdict = grammar === "name" ? adjudicatePersistedNameRules(table, { ...at, request: req }) : adjudicatePersistedDomainRules(table, { ...at, hosts: { tighten: callHostTargetOf(named, "tighten"), grant: callHostTargetOf(named, "grant") } });
             if (verdict !== undefined && verdict.behavior === behavior)
                 return [familyRows.find((r) => r.compiled.rule === verdict.rules[0]) ?? familyRows[0]];
         }
@@ -253,8 +255,19 @@ export function allowingRows(rows, req, mode) {
 export class AllowEntryTable {
     held = [];
     heldEntries = new Set();
-    seed(entries, roster) {
-        const { rows, inert } = compileAllowList(entries, "allow", roster);
+    receivedAt = new Map();
+    seed(entries, reading = {}) {
+        const { rows, inert } = compileAllowList(entries, "allow", reading.roster);
+        if (reading.received === true) {
+            this.receivedAt = new Map();
+            entries.forEach((e, i) => {
+                const at = this.receivedAt.get(e);
+                if (at === undefined)
+                    this.receivedAt.set(e, [i]);
+                else
+                    at.push(i);
+            });
+        }
         for (const r of rows) {
             if (this.heldEntries.has(r.entry))
                 continue;
@@ -273,15 +286,19 @@ export class AllowEntryTable {
         return {
             allowing: (req, mode) => {
                 const hit = judgeAllowEntries(allowingRows(this.held, req, mode), req, "allow", ctx);
-                return hit === undefined ? undefined : { entries: hit.map((r) => r.entry) };
+                if (hit === undefined)
+                    return undefined;
+                const entries = hit.map((r) => r.entry);
+                const positions = entries.flatMap((e) => this.receivedAt.get(e) ?? []).sort((a, b) => a - b);
+                return { entries, ...(positions.length > 0 ? { positions } : {}) };
             },
         };
     }
 }
 export function seedAllowEntryTables(tables, lists, roster) {
     tables.request.seed(lists.inherited ?? []);
-    const requestInert = tables.request.seed(lists.request ?? [], roster);
-    const deploymentInert = tables.deployment.seed(lists.deployment ?? [], roster).filter((e) => e.reason === "tool_name" || e.reason === "near_miss");
+    const requestInert = tables.request.seed(lists.request ?? [], { roster, received: true });
+    const deploymentInert = tables.deployment.seed(lists.deployment ?? [], { roster, received: true }).filter((e) => e.reason === "tool_name" || e.reason === "near_miss");
     return [
         ...lists.skillInert.map((e) => ({ source: "skill", ...e })),
         ...requestInert.map((e) => ({ source: "request", ...e })),
@@ -298,22 +315,27 @@ export function withDeploymentAllowedTools(deps) {
     return { ...deps, allowedTools };
 }
 export const INVALID_PERMISSION_RULES_CODE = "config.invalid_permission_rules";
+const ALLOW_LIST_SEATS = {
+    "TaskSpec.allowedTools": "the request's allow list",
+    "RunnerDeps.allowedTools": "the deployment's allow list",
+};
 export function screenAllowedToolsValue(value, seat) {
     if (value === undefined)
         return undefined;
+    const label = ALLOW_LIST_SEATS[seat];
     const issues = [];
     if (!Array.isArray(value)) {
-        issues.push({ rule: "", code: "invalid.entry_type", message: `${seat} must be a list of permission-rule strings (got ${value === null ? "null" : typeof value})` });
+        issues.push(ruleIssue("", "invalid.entry_type", `${label} must be a list of permission-rule strings (got ${value === null ? "null" : typeof value})`, { name: seat }));
     }
     else {
         const list = value;
         list.forEach((entry, i) => {
             if (typeof entry !== "string")
-                issues.push({ rule: "", code: "invalid.entry_type", message: `${seat}[${i}] must be a permission-rule string (got ${entry === null ? "null" : typeof entry})` });
+                issues.push(ruleIssue("", "invalid.entry_type", `entry ${i} of ${label} must be a permission-rule string (got ${entry === null ? "null" : typeof entry})`, { name: seat }));
         });
     }
     if (issues.length > 0) {
-        const e = new Error(`${seat}: ${issues.length} invalid entr${issues.length === 1 ? "y" : "ies"} — refusing rather than running without them:\n${issues.map((i) => `  [${i.code}] ${i.message}`).join("\n")}`);
+        const e = new Error(`${label}: ${issues.length} invalid entr${issues.length === 1 ? "y" : "ies"} — refusing rather than running without them:\n${issues.map((i) => `  [${i.code}] ${i.message}`).join("\n")}`);
         e.code = INVALID_PERMISSION_RULES_CODE;
         e.issues = issues;
         throw e;
@@ -359,18 +381,17 @@ export const SHADOW_REASON = Object.freeze({
     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",
     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),
+    ask_rule: ASK_RULE_DISCLOSURE,
     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",
     requires_user_interaction: "this tool's server declares that a call must be put to a person",
-    cross_boundary: mandateDisclosureOf("cross_boundary_taint"),
+    cross_boundary: MANDATE_DISCLOSURE.cross_boundary_taint,
     operator_forced: "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",
-    shell_floor: mandateDisclosureOf("operator_always"),
-    target_unresolved: mandateDisclosureOf("target_unresolved"),
-    probe: mandateDisclosureOf("probe_mandate"),
-    write_protection: mandateDisclosureOf("write_protection"),
-    tool_marks_mcp: mandateDisclosureOf("tool_marks"),
-    tool_marks_a2a: mandateDisclosureOf("tool_marks"),
+    shell_floor: MANDATE_DISCLOSURE.operator_always,
+    target_unresolved: MANDATE_DISCLOSURE.target_unresolved,
+    write_protection: MANDATE_DISCLOSURE.write_protection,
+    tool_marks_mcp: MANDATE_DISCLOSURE.tool_marks,
+    tool_marks_a2a: MANDATE_DISCLOSURE.tool_marks,
     policy_rra: "the deployment's policy requires a real approval for this call",
     artifact_shared_read: "this read targets another task's shared artifact — it is cleared by confirming this call",
     mode: "the permission mode puts this question to a person",
@@ -398,12 +419,16 @@ function memberPhrase(s) {
 }
 export function allowRuleShadowSentence(shadows, ask) {
     const one = shadows.length === 1 && (shadows[0].member === "hook" || shadows[0].entries.length + (shadows[0].omitted ?? 0) === 1);
-    const why = ask.mandate !== undefined
-        ? mandateDisclosureOf(ask.mandate)
-        : ask.authoredBy === "deployment"
+    const { askClass, mandate, authoredBy, probeReason } = ask;
+    const account = typeof probeReason === "string" && probeReason.trim().length > 0 && isMintableProbeReason(probeReason) ? probeReason : undefined;
+    const why = mandate !== undefined
+        ? mandateDisclosureOf(mandate, account)
+        : authoredBy === "deployment"
             ? "this deployment requires a person's confirmation for this call"
-            : SHADOW_REASON[ask.askClass ?? "ordinary"];
-    return `${shadows.map(memberPhrase).join("; ")} ${one ? "matches this call but does not clear the ask" : "match this call but do not clear the ask"} — ${why}`;
+            : askClass === "probe"
+                ? account
+                : SHADOW_REASON[askClass ?? "ordinary"];
+    return `${shadows.map(memberPhrase).join("; ")} ${one ? "matches this call but does not clear the ask" : "match this call but do not clear the ask"}${why !== undefined ? ` — ${why}` : ""}`;
 }
 export function cardDisclosureOf(decision, fallbackMessage) {
     const base = decision.message ?? fallbackMessage;