@sema-agent/core 7.54.0 → 7.55.0

package/dist/core/permission-rule-consent.js

@@ -1,7 +1,8 @@
 import { randomBytes } from "node:crypto";
-import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForName, suggestRulesForCommand, EDITED_RULE_BREADTH_WARNING_CODES, UNCOVERED_SEGMENT_REASONS, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
+import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForHost, suggestRuleForName, suggestRulesForCommand, EDITED_RULE_BREADTH_WARNING_CODES, RULE_OFFER_KINDS, UNCOVERED_SEGMENT_REASONS, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
+import { readRuleOwner, sameRuleOwner } from "./rule-owner.js";
 import { effectiveOrThrow } from "./permission-rule-provider.js";
-import { errText, isValidConsentScope, landRuleAdd, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
+import { errText, isValidConsentScope, landRuleAdd, sameScope, writerOf } from "./permission-rule-store.js";
 const isUncoveredSegmentReason = (v) => UNCOVERED_SEGMENT_REASONS.some((word) => v === word);
 export const RULE_APPROVAL_KINDS = Object.freeze(["card", "import", "starter"]);
 export const RULE_APPROVAL_STATES = Object.freeze(["pending", "approved", "redeemed"]);
@@ -47,41 +48,46 @@ function mintId(deps, prefix) {
     return `${prefix}_${Date.now().toString(36)}_${randomBytes(9).toString("base64url")}`;
 }
 function requirePrincipal(principal, entry) {
-    if (typeof principal !== "string" || principal === "") {
+    const owner = readRuleOwner({ kind: "principal", principal });
+    if (owner?.kind !== "principal") {
         throw new Error(`${entry} requires a verified principal — refusing to create an approval record without one`);
     }
-    return principal;
+    return owner.principal;
 }
 function resolveCallerOwner(principal, owner, entry) {
     if (owner !== undefined) {
-        if (owner.kind === "principal") {
-            const p = requirePrincipal(owner.principal, entry);
-            if (typeof principal === "string" && principal !== "" && principal !== p) {
-                throw new Error(`${entry}: contradictory identity — principal "${principal}" and owner principal "${p}" disagree`);
+        const given = readRuleOwner(owner);
+        if (given === undefined) {
+            throw new Error(`${entry} requires a verified principal or the local owner — the owner given is neither (a principal owner names a non-blank principal)`);
+        }
+        if (given.kind === "principal") {
+            if (typeof principal === "string" && principal !== "" && principal !== given.principal) {
+                throw new Error(`${entry}: contradictory identity — principal "${principal}" and owner principal "${given.principal}" disagree`);
             }
-            return { kind: "principal", principal: p };
+            return given;
         }
         if (typeof principal === "string" && principal !== "") {
             throw new Error(`${entry}: contradictory identity — a principal and a local-owner were both given; a bucket has one owner`);
         }
-        return { kind: "local-owner" };
+        return given;
     }
     return { kind: "principal", principal: requirePrincipal(principal, entry) };
 }
 function ownerOfRecord(rec) {
-    if (rec.owner !== undefined) {
-        if (rec.owner.kind === "principal") {
-            if (typeof rec.owner.principal !== "string" || rec.owner.principal === "")
-                return undefined;
-            if (typeof rec.principal === "string" && rec.principal !== "" && rec.principal !== rec.owner.principal)
-                return undefined;
-            return rec.owner;
-        }
-        if (typeof rec.principal === "string" && rec.principal !== "")
-            return undefined;
-        return { kind: "local-owner" };
-    }
-    return typeof rec.principal === "string" && rec.principal !== "" ? { kind: "principal", principal: rec.principal } : undefined;
+    const stated = rec.owner;
+    const owner = stated === undefined ? undefined : readRuleOwner(stated);
+    if (stated !== undefined && owner === undefined)
+        return undefined;
+    const principal = rec.principal;
+    const given = typeof principal === "string" && principal !== "";
+    const named = given ? readRuleOwner({ kind: "principal", principal }) : undefined;
+    if (given && named === undefined)
+        return undefined;
+    if (owner === undefined)
+        return named;
+    if (named !== undefined && !sameRuleOwner(owner, named))
+        return undefined;
+    return owner;
 }
 function recordIdentityOf(owner) {
     return owner.kind === "principal" ? { principal: owner.principal } : { owner: { kind: "local-owner" } };
@@ -111,7 +117,7 @@ function approvalRecordDamageOf(rec) {
     for (const [at, offer] of rec.offers.entries()) {
         if (typeof offer !== "object" || offer === null)
             return `offer ${at} is not an offer object`;
-        if (offer.kind !== "single" && offer.kind !== "batch")
+        if (!RULE_OFFER_KINDS.some((word) => offer.kind === word))
             return `offer ${at} has an unknown kind`;
         if (offer.kind === "batch" && (!Array.isArray(offer.candidates) || offer.candidates.length === 0)) {
             return `batch offer ${at} has no members`;
@@ -283,8 +289,9 @@ export async function prepareCardApproval(opts) {
         e.code = "config.invalid_argument";
         throw e;
     }
-    const nameCard = ruleToolGrammarOf(opts.toolName) === "name";
-    if (opts.toolName !== CARD_RULE_TOOL && !nameCard)
+    const grammar = ruleToolGrammarOf(opts.toolName);
+    const oneRuleCard = grammar === "name" || grammar === "domain" ? grammar : undefined;
+    if (opts.toolName !== CARD_RULE_TOOL && oneRuleCard === undefined)
         return undefined;
     const scope = (() => {
         if (opts.scope !== undefined) {
@@ -308,7 +315,7 @@ export async function prepareCardApproval(opts) {
         throw e;
     })();
     let coverage;
-    if (!nameCard) {
+    if (oneRuleCard === undefined) {
         try {
             const view = await effectiveOrThrow(storeForOwner(opts.deps.provider, owner), opts.sessionId !== undefined ? { sessionId: opts.sessionId } : undefined);
             const table = view.rules;
@@ -318,8 +325,8 @@ export async function prepareCardApproval(opts) {
             coverage = undefined;
         }
     }
-    const suggested = nameCard
-        ? [suggestRuleForName(opts.toolName, opts.command)].filter((o) => o !== undefined)
+    const suggested = oneRuleCard !== undefined
+        ? [oneRuleCard === "name" ? suggestRuleForName(opts.toolName, opts.command) : suggestRuleForHost(opts.toolName, opts.command)].filter((o) => o !== undefined)
         : suggestRulesForCommand(opts.command, {
             ...(coverage !== undefined ? { coverage } : {}),
             scope,
@@ -358,7 +365,7 @@ export async function prepareCardApproval(opts) {
         rev: 0,
         candidates,
         offers,
-        ...(nameCard ? {} : { command: opts.command }),
+        ...(oneRuleCard !== undefined ? {} : { command: opts.command }),
         createdAt: nowIso(opts.deps),
         ...(opts.toolCallId !== undefined ? { toolCallId: opts.toolCallId } : {}),
         ...(opts.boundInputHash !== undefined ? { boundInputHash: opts.boundInputHash } : {}),

package/dist/core/permission-rule-model.d.ts

@@ -72,9 +72,11 @@
  * here) and no leading-env-assignment stripping (`FOO=1 git status` simply does not match
  * `Bash(git status:*)`) — the last two are strict-side divergences from upstream, registered as such.
  */
+import { type ParsedPermissionRule } from "./permission-rule-syntax.js";
 import { type DenyFace } from "../tools/fs/read-deny.js";
 import type { AssertAllKeysHandled, RuleOffersAbsence } from "./ask-origin.js";
 import { type ToolCallLike } from "./tool-registry.js";
+import { type HostReading } from "./host-target.js";
 import { type PathDenialEvidence, type PathFamily, type PathIdentity } from "../tools/fs/safety.js";
 import { type TargetViews } from "./path-rule-binding.js";
 /**
@@ -160,73 +162,148 @@ export declare function callPathFaceOf(call: ToolCallLike): DenyFace | undefined
 /** Does some {@link PATH_RULE_FACES} tightening column (deny or ask) hold `face` — may a face-keyed row speak for a call on
  *  it, whatever the call's tool is called (a caller's tool declaring a read path target is on the read face too)? */
 export declare function faceRowsSpeakFor(face: DenyFace | undefined): boolean;
+/** One row of {@link NAME_RULE_FACES}. */
+export interface NameRuleFace {
+    /** The argument a rule's content is read against. */
+    readonly param: string;
+    /** The arguments whose `<param>:` spelling the row CLAIMS: on a bare row that spelling is refused (the bare one is the rule's),
+     *  on a keyed row it is the rule. An argument the tool carries that the row does not claim keeps the generic parameter lane. */
+    readonly params: readonly string[];
+    /** KEYED: the closed set of values the tool itself declares for `param` (the tool's own set, never a copy). */
+    readonly words?: readonly string[];
+    /** `mounted`: the values a rule names are the MOUNTED tool's own — its `ToolRuleFace.nameValues`, riding the call's face — and a
+     *  rule's value and the call's are each resolved to one of them by the one resolver ({@link canonicalNameValue}). */
+    readonly values?: "mounted";
+}
 /**
  * The tools whose rule content NAMES THE VALUE of one parameter instead of a command or a path — ONE grammar (the name grammar,
  * match `name`), one row per tool, the row declaring the tool's SPELLING of it:
- *  · BARE — the reference's `Skill(<name>)` / `Skill(<prefix>:*)`: `param` is the argument the rule's content is read against,
- *    `params` every scalar argument the tool carries (the parameter spelling `Tool(<param>:<pattern>)` those names used to reach
- *    is retired for such a tool, see {@link parseNameRuleContent}). The Skill tool's real schema keys are pinned equal to
- *    `params` (test/backlog1318).
+ *  · BARE — the reference's `Skill(<name>)` / `Skill(<prefix>:*)`: `params` is every scalar argument the tool carries, read off
+ *    its catalog row (the parameter spelling `Tool(<param>:<pattern>)` those names used to reach is retired for such a tool,
+ *    see {@link parseNameRuleContent}). The Skill tool's real schema keys are pinned equal to `params` (test/backlog1318).
  *  · KEYED — `words` present: the reference's `Artifact(action:<word>)`, the content carrying the argument's own key. `params`
- *    is that one key; `words` is the closed set of values the tool itself declares for it (the row points at the tool's own
- *    set, never a copy), and a rule names exactly one of them — no prefix form, no `*`.
+ *    is that one key, and a rule names exactly one of the words — no prefix form, no `*`.
+ *  · MOUNTED — `values: "mounted"`: the reference's `Agent(<subagent_type>)`, bare, naming one value of the set the mounted tool
+ *    declares (which agent types this leg offers) — no prefix form, no `*`, no leading-slash reading. `params` is the one
+ *    argument it claims; the tool's other arguments keep the generic parameter lane (`Agent(model:…)`).
  * Whatever the spelling, a rule of this grammar says "the call's value of `param` is this value", read by the one subject
- * reader ({@link nameRuleSubjectOf}), the one predicate ({@link nameRuleAdmits}), the one precedence walk
+ * reader ({@link nameRuleSubjectOf}), the one predicate ({@link nameRuleReach}), the one precedence walk
  * ({@link adjudicatePersistedNameRules}) and the one offer ({@link suggestRuleForName}).
  */
-export declare const NAME_RULE_FACES: Readonly<Record<string, {
-    readonly param: string;
-    readonly params: readonly string[];
-    readonly words?: readonly string[];
-}>>;
+export declare const NAME_RULE_FACES: Readonly<Record<string, NameRuleFace>>;
 /**
- * Why a call of a KEYED value tool that names no value for the key cannot be read against that key's deny / ask rules, or
- * undefined (a bare-spelling tool, or no value tool). Every judge reads a call's arguments as the tool reads them
- * (`argsAsTheToolReads`: its argument preparation, then the schema's coercions); a call that STILL names no value for the key
- * runs a value no argument shows — a default filled in inside the tool's execution (a caller's tool mounted under the keyed
- * name, or answering to it, with no argument preparation of its own). Whether a rule by the key reaches such a call is
- * unknown, so every reader REFUSES it on the key's deny or ask rule — a refusal, never an ask a person could approve past a
- * deny, and no allow by the key reaches it. A tool whose reading always names the key (the built-in `Artifact`: an absent
- * action reads as `publish`) never meets this. A bare-spelling tool's call that names nothing is reached by nothing: no
- * default stands behind it.
+ * The reference's fold of a delegated agent type (`lhe`, cli296.js:246723):
+ * `e.normalize("NFKC").toLowerCase().replace(/[\p{White_Space}\p{Pd}_]+/gu, "")`.
+ *
+ * Deliberately lossy and deliberately NOT a resolver: it decides whether two spellings denote the same entry of a value set AFTER
+ * an exact match has already failed ({@link canonicalNameValue} is the resolver). `\p{Pd}` is the dash punctuation class (an
+ * en-dash paste folds like a hyphen), `\p{White_Space}` covers NBSP and friends, and NFKC folds fullwidth/compatibility forms —
+ * the three ways a name gets mangled between a listing line and a tool call. It can map DISTINCT entries onto one key
+ * ("code-review" / "code_review"), which is why a fold that lands on several is ambiguous, never a pick.
  */
-export declare function keyedValueAbsentReason(tool: string): string | undefined;
+export declare function normalizeSubagentType(value: string): string;
+/** What a spelling names in a value set ({@link canonicalNameValue}): one entry, several (the fold lands on each), or none. */
+export type NameValueResolution = {
+    readonly kind: "entry";
+    readonly entry: string;
+} | {
+    readonly kind: "ambiguous";
+    readonly entries: readonly string[];
+} | {
+    readonly kind: "unknown";
+};
+/**
+ * THE resolver of a spelling against a value set — the one identity a delegated agent type has, read alike by the tool that runs
+ * the call and by every rule judged on it: an EXACT member first (a correct spelling never moves); else the members the
+ * reference's fold ({@link normalizeSubagentType}) maps onto the same key — exactly one ⇒ that member, several ⇒ `ambiguous`
+ * (listed, never one picked), none (or a spelling that folds to nothing) ⇒ `unknown`.
+ */
+export declare function canonicalNameValue(value: string, values: readonly string[]): NameValueResolution;
+/**
+ * Why a call of a name tool whose rules name one value of a CLOSED set (a keyed tool's `words`, a mounted tool's values) cannot
+ * be read against the tool's deny / ask rules when it names no value, or undefined (an open-set tool, or no value tool). Every
+ * judge reads a call's arguments as the tool reads them (`argsAsTheToolReads`: its argument preparation, then the schema's
+ * coercions); a call that STILL names no value runs one no argument shows — a default filled in inside the tool's execution (a
+ * caller's tool mounted under the name with no argument preparation of its own; the delegation tool's plain lane while a
+ * definition shadows its default type's name). Whether a rule by the value reaches such a call is unknown, so every reader
+ * REFUSES it on the tool's deny or ask rule — a refusal, never an ask a person could approve past a deny, and no allow by the
+ * value reaches it. A tool whose reading always names its value (the built-in `Artifact`: an absent action reads as
+ * `publish`) never meets this. An open-set tool's call that names nothing is reached by nothing: no default stands behind it.
+ */
+export declare function nameValueAbsentReason(tool: string): string | undefined;
 /**
- * Does the name grammar read this content of this tool? Every content of a bare-spelling tool; on a keyed tool only content
- * keyed by its own parameter (`action:…` on `Artifact`) — another key (`Artifact(url:…)`) is a rule on another argument,
- * which the persisted grammar has no form for and the caller policy reads with its generic parameter lane. Undefined grammar
- * ⇒ false.
+ * Does the name grammar read this content of this tool ALONE? On a keyed tool only content keyed by its own parameter
+ * (`action:…` on `Artifact`); on a bare tool every content but one keyed by an argument the catalog's tool carries and the row
+ * does not claim ({@link NameRuleFace.params}) — that is a rule on that argument (`Agent(model:…)`, `Artifact(url:…)`), which the
+ * caller policy reads with its generic parameter lane; a MOUNTED row's such content is read as its value too where it tightens
+ * ({@link mountedValueArmOf}). The arguments are the catalog's, whatever face a leg mounts the tool with: one text reads one way
+ * on every compile. Undefined grammar ⇒ false.
  */
 export declare function nameGrammarReads(tool: string, content: string): boolean;
 /**
- * The tools whose rule content names the HOST of the URL one parameter carries — the reference's `WebFetch(domain:<host>)`
- * form, one row per tool: `param` is the URL argument the host is read from ({@link domainRuleSubjectOf}). Read by
- * {@link parseDomainRuleContent}; an allow only (see there).
+ * The VALUE arm of a mounted row's (`Agent`) `<key>:<rest>` deny / ask that the parameter lane reads as a rule on the argument
+ * `key` — or undefined (any other tool, or an allow). One rule for every reader of such a content: a TIGHTENING reaches the call
+ * under every reading of its text — the rule on the argument, and the whole text as one of the tool's values (an agent type may
+ * carry a colon), either reaching ⇒ it applies (the reference reads the content as an agent type for its deny filter and as a
+ * `key:value` for its generic parameter check alike); a GRANT reads exactly one way — the argument rule where `key` is an
+ * argument the tool carries — so an allow never widens through a second reading. The value arm is the name grammar's own rule
+ * over the whole content, judged like every value rule ({@link nameRuleReach}).
+ */
+export declare function mountedValueArmOf(text: string, tool: string, behavior: RuleBehavior): ParsedRule | undefined;
+/**
+ * The argument a mounted row's (`Agent`) `<key>:<rest>` content is keyed by when the leg's own tool declares it (`mountedParams`,
+ * the leg's face) and the catalog's does not — or undefined. A rule's grammar reads the catalog's arguments only, so such a
+ * content would read as one of the tool's values and never reach a call setting that argument: a compile that holds the leg's
+ * face knows this and refuses it; one without the face cannot tell, and reads the value.
+ */
+export declare function mountedOnlyArgumentOf(tool: string, content: string, mountedParams: readonly string[] | undefined): string | undefined;
+/**
+ * The ARGUMENT arm of a mounted row's value rule — the other half of {@link mountedValueArmOf}'s law, read where the rule is a
+ * stored row (a list entry, a session bucket's entry, the person's persisted row): a deny or an ask whose value is
+ * `<argument>:<pattern>`, `argument` one the catalog's tool carries and the row does not claim, is ALSO the rule on that
+ * argument, judged by the one argument predicate (`paramRuleReaches`) — so a stored `Agent(model:opus)` deny refuses a call
+ * running `model: opus` as the rule policy does. Undefined for an allow (a grant reads one way), another tool, or another value.
  */
-export declare const DOMAIN_RULE_FACES: Readonly<Record<string, {
+export declare function mountedArgumentArmOf(rule: Pick<PersistedRule, "tool" | "behavior" | "match" | "command">): {
     readonly param: string;
-}>>;
+    readonly pattern: string;
+} | undefined;
+/** The marker a DOMAIN-grammar rule's content starts with: `<Tool>(domain:<host>)` (the reference's spelling). */
+export declare const DOMAIN_RULE_MARKER = "domain:";
 /**
- * Which tools a rule may name — the model's tool set is DERIVED, never a hand-kept list: the command rule word
- * ({@link COMMAND_RULE_TOOL}) takes the COMMAND grammar — the other shell-face tools take none of their own, their command is
- * judged by the `Bash(…)` rules ({@link laneToolNamesOf}); every tool the catalog declares a path target for (Read / Edit / Write /
- * Glob / NotebookEdit / …, `pathTargetOf`) takes the PATH grammar; the tools of {@link NAME_RULE_FACES} take the NAME grammar
- * (each in its row's spelling: bare `Skill(<name>)`, keyed `Artifact(action:<word>)`); the tools of {@link DOMAIN_RULE_FACES} the
- * DOMAIN grammar.
- * A rule on any other tool has no content this model can judge and is refused (`unsupported.tool`). The tool set therefore
- * moves with the catalog's declarations, exactly as the protective fences' covered set does.
+ * THE grammar a rule on a tool takes — the one reading every rule reader shares (the persisted model's {@link parseRuleText}, the
+ * rule policy's compiler through {@link ruleLaneOf}, the entry lists, the approval card), and a property of the rule's tool NAME
+ * as the catalog declares it, never of the tool a leg mounts under that name. The model's tool set is DERIVED, never a hand-kept
+ * list: the command rule word ({@link COMMAND_RULE_TOOL}) takes the COMMAND grammar — the other shell-face tools take none of
+ * their own, their command is judged by the `Bash(…)` rules ({@link laneToolNamesOf}); the tools of {@link NAME_RULE_FACES} the
+ * NAME grammar (each in its row's spelling: bare `Skill(<name>)`, keyed `Artifact(action:<word>)`); every name the catalog
+ * declares a host target for (`hostTargetOf`: WebFetch) the DOMAIN grammar; every name it declares a path target for
+ * (`pathTargetOf`: Read / Edit / Write / Glob / NotebookEdit / …) the PATH grammar. A rule on any other tool has no content
+ * this model can judge and is refused (`unsupported.tool`). The tool set therefore moves with the catalog's declarations,
+ * exactly as the protective fences' covered set does.
  */
 export type RuleGrammar = "command" | "path" | "name" | "domain";
 export declare function ruleToolGrammarOf(toolName: string): RuleGrammar | undefined;
+/** The parameter a shell-face tool's rule content names as one of the tool's own scalar arguments (`Monitor(description:*)`,
+ *  `Bash(timeout:5)`), or undefined — the content is then a command spelling. */
+export declare function shellRuleParamOf(tool: string, content: string): string | undefined;
+/** A lane of the rule policy's compiler: one of the content grammars, or the generic `param:pattern` lane. */
+export type RuleLane = RuleGrammar | "param";
 /**
- * The HOST a domain-grammar tool's call fetches — the string every DOMAIN rule is read against — or undefined: not a domain
- * tool; no URL argument, or one that is not a string; a URL that does not parse, is not http(s), or carries credentials (the
- * fetch tool refuses those itself). The host is the URL parser's (lower case, IDN in its ASCII form, an IPv4 shorthand
- * expanded — the host the fetch connects to), its trailing dots read off.
+ * THE dispatch of a `<tool>(<content>)` rule in the rule policy's compiler — which lane reads it. A shell-face tool's content
+ * is a COMMAND spelling unless it names one of that tool's own scalar arguments (the command word's `<param>:*` keeps the
+ * command-prefix reading); otherwise the tool's grammar ({@link ruleToolGrammarOf}, the rule model's own reading) reads the
+ * content it claims — a name tool every content (a keyed one only content keyed by its own parameter, {@link nameGrammarReads}),
+ * a path tool a content with no `:` past its first character, a host tool a content that starts with {@link DOMAIN_RULE_MARKER}
+ * — and every other content is a rule on a parameter. The lane is a function of the rule's name and content alone: it is decided
+ * before any lane's own check runs, a content a grammar claims is never judged as a parameter rule, and the same rule text takes
+ * the same lane whether the policy is compiled with no leg resolver or with a leg's roster (whose faces say only which
+ * parameters a tool carries).
  */
-export declare function domainRuleSubjectOf(toolName: string, args: unknown): string | undefined;
+export declare function ruleLaneOf(tool: string, content: string): RuleLane;
 /** The value a name-grammar tool's call carries in its name argument — the string every NAME rule is read against, the one a
- *  `Skill` call is resolved by — or undefined (not a name-grammar tool; no such argument; not a string). */
+ *  `Skill` call is resolved by — or undefined (not a name-grammar tool; no such argument; not a string; the empty string, which
+ *  names no value: an empty and an omitted argument are one call to every reader, as they are to the tool that runs it). */
 export declare function nameRuleSubjectOf(toolName: string, args: unknown): string | undefined;
 /** The rule WORDS a call is judged under, once each: for every name the call answers to (the model's spelling, the wire
  *  name, the other aliases that resolve to it), the word its rules are written in — a shell-face name's is the command
@@ -238,7 +315,7 @@ export declare function laneToolNamesOf(req: Pick<import("./tool-policy.js").Too
 /** The match words a persisted rule is stored with, spelled once: {@link PersistedRuleMatch} is derived from this
  *  tuple (each form is documented there). A store backend that checks a stored row's `match` reads this value
  *  rather than keeping its own list. */
-export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "subpath", "path", "name", "name_prefix", "host", "subdomain"];
+export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain"];
 /**
  * Match forms, one family per grammar (`prefix` and `wildcard` are one predicate):
  *  · `exact` — admits the one string the rule spells.
@@ -252,6 +329,12 @@ export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildc
  *    (`Bash(cd /tmp && adb pull:*)`): the trailing-star form deliberately has no compound reading
  *    (see {@link parseRuleText}), because upstream's own trailing-star pattern is inert on a
  *    compound and importing/minting one as a chain licence would grant what nobody approved.
+ *  · `pattern` — the PATTERN spelling (`Bash(git * main)`): any other unescaped `*` in the content, the reference's
+ *    wildcard. `command` is the folded pattern as written (stars and `\*` escapes kept); `*` is any text, newlines
+ *    included, `\*` a literal star, a `/` then `**` then `/` also matches one `/`. It reaches ONE simple command, matched whole:
+ *    an allow against the command's spelling, a deny / ask against each program run's words
+ *    ({@link programRunReachOf}); never a chain — its body is one command, and a compound is covered segment
+ *    by segment. No allow leaves the program open (a `*` in the first word) or opens an interpreter's arguments.
  *  · `subpath` — the directory form (design/382 §2.2): `Tool(//abs-dir/**)`, reaching every path under
  *    one absolute directory. Never admits any command; its one predicate is {@link directoryRuleAdmits}.
  *    As an ALLOW it exists on the two face tools ({@link PATH_RULE_FACES}); as a deny/ask on every
@@ -270,7 +353,7 @@ export type PersistedRuleMatch = (typeof PERSISTED_RULE_MATCHES)[number];
  * Where a rule applies — design/382 §4.1, the THREE consent dimensions.
  *
  *  · `global` — the personal-global dimension: this OWNER's rules, everywhere (the bucket is already
- *    per-owner, {@link import("./permission-rule-store.js").RuleOwner}). The member keeps its historical
+ *    per-owner, {@link import("./rule-owner.js").RuleOwner}). The member keeps its historical
  *    spelling on purpose: renaming it `personal-global` would be a no-benefit migration of every stored
  *    row; the "personal" half lives in documentation and card wording, not in the wire byte.
  *  · `project` — applies ONLY inside `root`. `root` is expected to be already canonicalized (realpath)
@@ -527,6 +610,19 @@ export declare const SHELL_RESERVED_WORDS: ReadonlySet<string>;
  * misled.
  */
 export declare const SUGGESTION_LEXICON: readonly string[];
+/**
+ * THE spelling of a content rule on a call's tool under one behavior — its rule word and grammar with a placeholder for the
+ * content, never a rule minted for the call — or undefined: the tool takes no content rule (the catalog gives it no grammar,
+ * whatever face a leg mounts it with), and the whole-tool entry is the only rule it has. The command grammar's `Bash(<command>)`
+ * for a tool on the shell face (`Monitor` too: a command rule is written on the command word); a name tool's own spelling
+ * ({@link nameRuleFormOf}); a host tool's `<Tool>(domain:<host>)`; a path tool's — a TIGHTENING on the tool's own word
+ * (`Write(<path>)` reaches the tool it is written on), a GRANT on the face tool whose allow column holds the call's face
+ * (`Read(<path>)` for a read, `Edit(<path>)` for a write: a path allow exists on the two face tools of {@link PATH_RULE_FACES}
+ * only). Read off the dispatch every reader shares ({@link ruleToolGrammarOf}, {@link callPathFaceOf}) and spelled by
+ * {@link formatRuleText}; every sentence that offers a rule's shape (a compile refusal's way out, the dontAsk refusal's remedy)
+ * reads it.
+ */
+export declare function ruleShapeOf(call: ToolCallLike, behavior: RuleBehavior): string | undefined;
 /**
  * Render a peer- or file-controlled value for a DISCLOSURE line (a warning, a refusal message, an
  * operator log). Takes `unknown` on purpose: most of these values are typed but arrive off a wire or a
@@ -600,6 +696,13 @@ export declare function renderUntrustedCommandText(text: unknown, maxLen?: numbe
  * Not part of the package's public surface — an internal screen for lane entry points.
  */
 export declare function hasUnrenderableCharacters(text: string): boolean;
+/**
+ * A rule spelling's content as a content rule, or undefined when the spelling names its WHOLE tool: no content (`Bash`,
+ * `Bash()`, `Bash(*)` — the syntax's reading), or a command content that folds to the lone `*` (`Bash( * )`): the command
+ * grammar folds its spacing, so that spelling is `Bash(*)` and never a pattern. The one reading every lane asks — the
+ * store, the entry lists, the rule policy — so a spelling of the whole tool is answered as the whole tool wherever it is written.
+ */
+export declare function ruleContentOf(parsed: ParsedPermissionRule): string | undefined;
 /**
  * Parse one rule text into its canonical shape, or refuse it with a reason.
  *
@@ -624,10 +727,25 @@ export declare function parseRuleText(text: string, behavior: RuleBehavior): {
  *  `subpath` the command is the lexical-normal absolute directory (one leading slash), re-spelled in the
  *  double-slash directory form; for `path` it is the pattern as spelled. */
 export declare function formatRuleText(command: string, match: PersistedRuleMatch, tool: PersistedRuleTool): string;
-/** Does a name rule reach this name? `name`: equal; `name_prefix`: begins with it (no boundary — the reference's `startsWith`).
- *  A rule of any other family reaches no name. */
+/** Does a name rule reach this name, spelling against spelling? `name`: equal; `name_prefix`: begins with it (no boundary — the
+ *  reference's `startsWith`). A rule of any other family reaches no name. The comparison {@link nameRuleReach} makes for a row
+ *  whose values are not resolved against a set. */
 export declare function nameRuleAdmits(rule: Pick<PersistedRule, "match" | "command">, name: string): boolean;
-/** Does a domain rule reach this host (as {@link domainRuleSubjectOf} reads it)? `host`: equal; `subdomain`: a name ending in
+/** How a name rule meets a call ({@link nameRuleReach}). `unread`: the call's face carries no value set for a row that needs one. */
+export type NameRuleReach = "reached" | "not_reached" | "unread";
+/**
+ * THE predicate of a name rule over one call's value — every reader of a name rule (the rule policy, the lists, the person's
+ * stored rows) asks it. An open or keyed row compares spellings ({@link nameRuleAdmits}). A MOUNTED row (`Agent`) resolves the
+ * rule's value and the call's through the one resolver ({@link canonicalNameValue}) against the set the call's face carries
+ * (`values`, the mounted tool's `nameValues`): both one entry ⇒ reached iff the same one; a rule value the fold lands on several
+ * entries with ⇒ a deny or an ask reaches every one of them and an allow none (an operand is never resolved to one of several);
+ * a side that resolves to none ⇒ the two spellings compared exactly (an unknown rule value never reaches a resolved call); no
+ * set ⇒ `unread` — which type the call runs cannot be read, so a deny refuses, an ask asks a person, and an allow grants nothing.
+ */
+export declare function nameRuleReach(rule: Pick<PersistedRule, "tool" | "behavior" | "match" | "command">, name: string, values: readonly string[] | undefined): NameRuleReach;
+/** Why a call is unread against a mounted row's rule ({@link nameRuleReach} `unread`) — the sentence every reader carries. */
+export declare function nameValuesUnreadReason(tool: string): string;
+/** Does a domain rule reach this host (as `hostOfUrl` reads it)? `host`: equal; `subdomain`: a name ending in
  *  `.<domain>` with at least one label before it and no empty label. A rule of any other family reaches no host. */
 export declare function domainRuleAdmits(rule: Pick<PersistedRule, "match" | "command">, host: string): boolean;
 /**
@@ -696,7 +814,7 @@ export declare function pathRuleReachOf(rule: Pick<PersistedRule, "match" | "com
  * reaches lies at or below the head, so a spelling of the head that the environment resolves elsewhere (a link, a
  * firmlink, `/var` → `/private/var`) is a second spelling of everything the rule reaches — the deny tables judge the
  * rule at both ({@link import("../tools/fs/read-deny.js").withRuleRowsWhereTheyLead}; the reference's "physical twin"
- * of a rule prefix, cli280.js 9766583). The head may be the bare anchor (`/`, a drive or share root — `Read(/**)` at a
+ * of a rule prefix). The head may be the bare anchor (`/`, a drive or share root — `Read(/**)` at a
  * drive root): an environment can resolve a drive or share root elsewhere. `undefined`: the pattern needs a base the
  * call does not supply (the rule then reads `unreadable`, a reach, everywhere), or a directory rule names the bare
  * anchor (it admits nothing).
@@ -787,6 +905,15 @@ export declare function programRunReachOf(rule: Pick<PersistedRule, "match" | "c
 /** The boolean face of {@link programRunReachOf}: `reached` only. The shadow view and the pins that
  *  assert a reach read this; a lane that must fail closed on `unreadable` reads the outcome. */
 export declare function ruleReachesProgramRun(rule: Pick<PersistedRule, "match" | "command">, command: string): boolean;
+/**
+ * Could the run this pattern names be one of `programs` (each its word or words, then anything)? The program is read as the
+ * read station reads it — past the launchers and wrappers in front of it (`nice`, `timeout 5`, `command`, `doas`, `env`,
+ * …: {@link readProgramPosition}) and by basename (`/usr/bin/python` runs `python`) — and the words from it on are read as
+ * the run receives them (quotes off), in lower case as the auto-mode strip reads every rule
+ * ({@link import("./allow-entry.js").autoStripped}). A program word the pattern leaves open (a star in it), or a run whose
+ * program cannot be read, could be any of them.
+ */
+export declare function commandPatternMayRun(body: string, programs: readonly string[]): boolean;
 /** The breadth-warning codes, spelled once: {@link EditedRuleBreadthWarning}'s `code` is derived from this tuple,
  *  and a consent record's `edited.warnings` stores exactly these words (its readback refuses any other). */
 export declare const EDITED_RULE_BREADTH_WARNING_CODES: readonly ["broad_prefix", "compound_prefix"];
@@ -820,7 +947,8 @@ export interface EditedRuleBreadthWarning {
  * and a SUBPATH rule is not this classifier's subject (no command reach at all). The two
  * reach-bearing forms take the same two questions: `prefix` (colon-star) and `wildcard`
  * (trailing space-star, #510 — match-equivalent reach on a single-command body; its grammar has no
- * chain reading, so only the single-token question can fire for it).
+ * chain reading, so only the single-token question can fire for it), and `pattern` (the pattern form: one command, its
+ * first word star-free in an allow, so neither question fires for an allow pattern today).
  * MAINTENANCE DUTY, stated where it binds: every match form with PREFIX REACH belongs here — a
  * new reach-bearing member added to {@link PersistedRuleMatch} owes this classifier its arm, judged
  * by the same "single token / chain body" questions (an exact-only form never warns).
@@ -1083,36 +1211,68 @@ export declare function adjudicatePersistedPathRules(rules: readonly PersistedRu
     readonly tighten?: TargetViews;
     readonly allow?: TargetViews;
 }, anchorsOf: (rule: PersistedRule) => PathRuleBases, leads: ReadonlyMap<string, string | undefined>): PersistedRuleVerdict | undefined;
+/** The call a persisted name rule is judged on — the request itself: its arguments (the one string it names is read off them,
+ *  `nameRuleSubjectOf`; a mounted row's argument arm reads them too) and its face (a mounted tool's values, the tool's reading). */
+export interface PersistedNameCall {
+    readonly args: unknown;
+    readonly face?: {
+        readonly nameValues?: readonly string[];
+    } | undefined;
+}
 /**
  * The name-family sibling of {@link adjudicatePersistedRules}: the same precedence walk over the rules of one name tool
- * ({@link NAME_RULE_FACES}), judged on the one string the call names (`nameRuleSubjectOf`). A rule of the tool speaks for the call
- * when it is live, of this behavior, in scope ({@link eligiblePersisted}, the one predicate) and {@link nameRuleAdmits} the name; the
- * first behavior in {@link RULE_BEHAVIORS_BY_PRECEDENCE} whose rules speak decides, the first table-order rule of it is the answer.
- * Every behavior is judged with the one predicate — a name has no "program run" the tightening direction could read wider.
- * A call that names nothing (read as the tool reads it): on a bare-spelling tool it is reached by no rule; on a KEYED tool it
- * cannot be read against the key's rules ({@link keyedValueAbsentReason}) and is REFUSED — a deny verdict standing on the
- * first eligible deny row of the key, else its first ask row (an ask a person could approve would let a deny be approved
+ * ({@link NAME_RULE_FACES}), judged on the call itself (`request`): the one string it names (`nameRuleSubjectOf`) and, for a
+ * mounted row, the value set its face carries. A rule of the tool speaks for the call when it is live, of this behavior, in scope
+ * ({@link eligiblePersisted}, the one predicate) and reaches the call — a tightening of a mounted row by its argument arm
+ * ({@link mountedArgumentArmOf}, judged by `paramRuleReaches`) or by its value ({@link nameRuleReach}); the first behavior in
+ * {@link RULE_BEHAVIORS_BY_PRECEDENCE} whose rules speak decides, the first table-order rule of it is the answer. A call a
+ * mounted row cannot be read against (`unread`: no value set on the face) is REFUSED by the first such deny row and asked in the
+ * fail-closed form (`unreadable`) by the first such ask row; no allow row reaches it.
+ * A call that names nothing (read as the tool reads it): on an open-set tool it is reached by no rule; on a closed-set tool it
+ * cannot be read against the tool's rules ({@link nameValueAbsentReason}) and is REFUSED — a deny verdict standing on the
+ * first eligible deny row of the tool, else its first ask row (an ask a person could approve would let a deny be approved
  * past) — and no allow row reaches it.
  */
 export declare function adjudicatePersistedNameRules(rules: readonly PersistedRule[], call: {
     tool: string;
-    name: string | undefined;
+    request: PersistedNameCall;
     cwd: string | undefined;
     sessionId?: string;
     scopeIdentity?: ScopeRootIdentity;
 }): PersistedRuleVerdict | undefined;
 /**
- * The domain-family sibling of {@link adjudicatePersistedNameRules}: the rules of one domain tool ({@link DOMAIN_RULE_FACES})
- * judged on the host the call fetches ({@link domainRuleSubjectOf}) by {@link domainRuleAdmits}; the first table-order rule
- * that is eligible and admits the host is the answer. The grammar has an allow form only, so only an allow can speak.
+ * The host the domain rules of one call are judged on, per direction (`callHostTargetOf`): `tighten` for a deny and an ask
+ * (the protective reading), `grant` for an allow (the declared reading). Absent ⇒ the call has no URL slot in that direction.
+ */
+export interface CallHosts {
+    readonly tighten: HostReading | undefined;
+    readonly grant: HostReading | undefined;
+}
+/**
+ * The domain-family sibling of {@link adjudicatePersistedNameRules}: the same precedence walk (deny > ask > allow) over the rules of
+ * one host tool, each behavior judged on its direction's host ({@link CallHosts}) by {@link domainRuleAdmits}; the first behavior
+ * whose eligible rules speak decides, the first table-order rule of it is the answer. A call whose host cannot be read (a URL
+ * that does not parse, is not http(s), carries credentials, or names a host that does not read back as itself) is REFUSED by the
+ * tool's first eligible deny row, whatever host that row names, and otherwise ASKED by its first eligible ask row in the
+ * fail-closed form (`unreadable`, never a matched ask); no allow row reaches it, and with no deny or ask row it is reached by
+ * nothing.
  */
 export declare function adjudicatePersistedDomainRules(rules: readonly PersistedRule[], call: {
     tool: string;
-    host: string | undefined;
+    hosts: CallHosts;
     cwd: string | undefined;
     sessionId?: string;
     scopeIdentity?: ScopeRootIdentity;
 }): PersistedRuleVerdict | undefined;
+/**
+ * The ONE offer a host tool's approval card carries: the exact rule for the host the call reaches (`WebFetch(domain:<host>)`, the
+ * reference's "don't ask again for <host>" row), or undefined when no rule spells exactly that host (the round-trip law: the
+ * canonical text, parsed back as an allow, must be the exact host rule over the very host). Never a `*.` rule: it would widen past
+ * the host shown.
+ */
+export declare function suggestRuleForHost(tool: string, host: string): Extract<RuleOffer, {
+    kind: "single";
+}> | undefined;
 /**
  * The ONE offer a name tool's approval card carries: the exact rule for the name the call carries (`Skill(<name>)`, the reference's
  * "don't ask again for <skill>" row), or undefined when no rule spells exactly that name (the round-trip law: the canonical text,
@@ -1297,6 +1457,15 @@ export type RuleOffer = {
      */
     readonly uncoveredDetail?: readonly UncoveredSegmentDetail[];
 };
+/** The offer discriminants as a value: the `kind` words of {@link RuleOffer} and of the consent record's own option form
+ *  (`RuleOffer2`, which stores the same choice by candidate index), each union fenced to the tuple in both directions
+ *  ({@link RuleOfferKindsCoverEveryArm} / {@link RuleOfferArmsCoverEveryKind} here, their twins beside `RuleOffer2`).
+ *  The engine's offer reader and record check read it; a backend's offer or record shape reads it too. */
+export declare const RULE_OFFER_KINDS: readonly ["single", "batch"];
+/** Compile fence: an arm whose `kind` is not in {@link RULE_OFFER_KINDS} turns the argument into that word. */
+export type RuleOfferKindsCoverEveryArm = AssertAllKeysHandled<Exclude<RuleOffer["kind"], (typeof RULE_OFFER_KINDS)[number]>>;
+/** Compile fence, the other direction: a word in {@link RULE_OFFER_KINDS} that no arm carries. */
+export type RuleOfferArmsCoverEveryKind = AssertAllKeysHandled<Exclude<(typeof RULE_OFFER_KINDS)[number], RuleOffer["kind"]>>;
 /** The uncovered-segment reason words, spelled once: {@link UncoveredSegmentDetail}'s `reason` is derived from this
  *  tuple, {@link UNCOVERED_SEGMENT_REASON_BASELINE} is keyed by it, and a consent record's reason rows are read
  *  against it. */