@sema-agent/core 7.55.0 → 7.57.0

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

@@ -1,11 +1,111 @@
 import { randomBytes } from "node:crypto";
-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 { COMMAND_RULE_TOOL, cardRuleFormOf, escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, segmentCoverageOf, suggestRuleForHost, suggestRuleForName, suggestRuleForTool, 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 { principalNameOf, readPrincipal } from "./principal-name.js";
+import { isPlainRecord } from "./mods/kernel/receive.js";
 import { effectiveOrThrow } from "./permission-rule-provider.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"]);
+const RECORD_OPTION_MEMBERS = { single: ["kind", "candidate"], batch: ["kind", "candidates", "segments", "uncoveredSegments", "uncoveredDetail"] };
+export function readRuleOffer2(raw) {
+    if (!isPlainRecord(raw))
+        return { problem: "malformed" };
+    const kind = raw.kind;
+    if (typeof kind !== "string")
+        return { problem: "malformed" };
+    const word = RULE_OFFER_KINDS.find((k) => k === kind);
+    if (word === undefined)
+        return { problem: "unknown_word" };
+    const declared = RECORD_OPTION_MEMBERS[word];
+    if (Object.keys(raw).some((name) => !declared.includes(name)))
+        return { problem: "malformed" };
+    switch (word) {
+        case "single": {
+            const candidate = raw.candidate;
+            return isCandidateIndex(candidate) ? { offer: { kind: "single", candidate } } : { problem: "malformed" };
+        }
+        case "batch": {
+            const candidates = indexListOf(raw.candidates);
+            if (candidates === undefined || candidates.length === 0)
+                return { problem: "malformed" };
+            const segments = raw.segments;
+            const uncoveredSegments = raw.uncoveredSegments;
+            const detail = raw.uncoveredDetail;
+            const segmentList = segments === undefined ? undefined : stringListOf(segments);
+            if (segments !== undefined && segmentList === undefined)
+                return { problem: "malformed" };
+            if (uncoveredSegments !== undefined && !isCandidateIndex(uncoveredSegments))
+                return { problem: "malformed" };
+            const rows = detail === undefined ? undefined : reasonRowsOf(detail);
+            if (rows !== undefined && "problem" in rows)
+                return rows;
+            return {
+                offer: {
+                    kind: "batch",
+                    candidates,
+                    ...(segmentList !== undefined ? { segments: segmentList } : {}),
+                    ...(uncoveredSegments !== undefined ? { uncoveredSegments } : {}),
+                    ...(rows !== undefined ? { uncoveredDetail: rows.rows } : {}),
+                },
+            };
+        }
+        default: {
+            const unhandled = word;
+            return unhandled;
+        }
+    }
+}
+function isCandidateIndex(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function indexListOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const length = value.length;
+    const out = [];
+    for (let i = 0; i < length; i++) {
+        const item = value[i];
+        if (!isCandidateIndex(item))
+            return undefined;
+        out.push(item);
+    }
+    return out;
+}
+function stringListOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const length = value.length;
+    const out = [];
+    for (let i = 0; i < length; i++) {
+        const item = value[i];
+        if (typeof item !== "string")
+            return undefined;
+        out.push(item);
+    }
+    return out;
+}
+function reasonRowsOf(value) {
+    if (!Array.isArray(value))
+        return { problem: "malformed" };
+    const length = value.length;
+    const rows = [];
+    for (let i = 0; i < length; i++) {
+        const row = value[i];
+        if (!isPlainRecord(row) || Object.keys(row).some((name) => name !== "segment" && name !== "reason"))
+            return { problem: "malformed" };
+        const segment = row.segment;
+        const reason = row.reason;
+        if (typeof segment !== "string" || typeof reason !== "string")
+            return { problem: "malformed" };
+        const word = UNCOVERED_SEGMENT_REASONS.find((r) => r === reason);
+        if (word === undefined)
+            return { problem: "unknown_word" };
+        rows.push({ segment, reason: word });
+    }
+    return { rows };
+}
 export const RULE_APPROVAL_RECORD_SCHEMA = 4;
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
@@ -48,25 +148,25 @@ function mintId(deps, prefix) {
     return `${prefix}_${Date.now().toString(36)}_${randomBytes(9).toString("base64url")}`;
 }
 function requirePrincipal(principal, entry) {
-    const owner = readRuleOwner({ kind: "principal", principal });
-    if (owner?.kind !== "principal") {
+    const name = principalNameOf(principal);
+    if (name === undefined) {
         throw new Error(`${entry} requires a verified principal — refusing to create an approval record without one`);
     }
-    return owner.principal;
+    return name;
 }
 function resolveCallerOwner(principal, owner, entry) {
     if (owner !== undefined) {
         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)`);
+            throw new Error(`${entry} requires a verified principal or the local owner — the owner given is neither (a principal owner names a principal name)`);
         }
         if (given.kind === "principal") {
-            if (typeof principal === "string" && principal !== "" && principal !== given.principal) {
+            if (readPrincipal(principal).kind !== "absent" && principal !== given.principal) {
                 throw new Error(`${entry}: contradictory identity — principal "${principal}" and owner principal "${given.principal}" disagree`);
             }
             return given;
         }
-        if (typeof principal === "string" && principal !== "") {
+        if (readPrincipal(principal).kind !== "absent") {
             throw new Error(`${entry}: contradictory identity — a principal and a local-owner were both given; a bucket has one owner`);
         }
         return given;
@@ -114,19 +214,17 @@ function approvalRecordDamageOf(rec) {
     if (!Array.isArray(rec.offers) || rec.offers.length === 0)
         return "the record carries no offers";
     const claimed = new Set();
-    for (const [at, offer] of rec.offers.entries()) {
-        if (typeof offer !== "object" || offer === null)
-            return `offer ${at} is not an offer object`;
-        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`;
+    for (const [at, stored] of rec.offers.entries()) {
+        const read = readRuleOffer2(stored);
+        if ("problem" in read) {
+            return `offer ${at} is not a record option this engine reads (${read.problem}): an option is an object whose kind is ${RULE_OFFER_KINDS.join(" or ")}, whose candidate indices are non-negative integers (a batch with no members is not one), whose reason rows are segment/reason rows from the closed reason set, and which carries no other member`;
         }
+        const offer = read.offer;
         const members = offerMembersOf(offer);
         const seen = new Set();
         for (const member of members) {
-            if (!Number.isInteger(member) || member < 0 || rec.candidates[member] === undefined) {
-                return `offer ${at} references candidate ${escapeForDisclosure(member)}, which the record does not carry`;
+            if (rec.candidates[member] === undefined) {
+                return `offer ${at} references candidate ${member}, which the record does not carry`;
             }
             const cand = rec.candidates[member];
             if (typeof cand !== "object" || cand === null || typeof cand.rule !== "string") {
@@ -138,6 +236,12 @@ function approvalRecordDamageOf(rec) {
             if (rec.kind === "card" && cand.behavior !== "allow") {
                 return `card offer ${at} references candidate ${member}, a ${cand.behavior} rule — a card mints allow candidates only`;
             }
+            if (rec.kind === "card") {
+                const read = parseRuleText(cand.rule, cand.behavior);
+                if ("rule" in read && read.rule.match === "tool" && (typeof rec.command === "string" || cardRuleFormOf(read.rule.tool) !== "tool")) {
+                    return `card offer ${at} references candidate ${member}, the whole-tool rule "${escapeForDisclosure(read.rule.rule)}" — the engine mints one only on the whole-tool card of a tool with no rule grammar`;
+                }
+            }
             if (!isValidConsentScope(cand.scope)) {
                 return `offer ${at} references candidate ${member}, whose scope is not a consent-face scope (global, project, or session)`;
             }
@@ -150,29 +254,21 @@ function approvalRecordDamageOf(rec) {
         }
         if (offer.kind === "batch") {
             if (rec.kind === "card") {
-                if (!Array.isArray(offer.segments) || offer.segments.length !== offer.candidates.length || !offer.segments.every((s) => typeof s === "string")) {
+                if (offer.segments === undefined || offer.segments.length !== offer.candidates.length) {
                     return `card batch offer ${at} must carry exactly one source segment per member`;
                 }
-                if (!Number.isInteger(offer.uncoveredSegments) || offer.uncoveredSegments < 0) {
+                if (offer.uncoveredSegments === undefined) {
                     return `card batch offer ${at} must carry a non-negative uncovered-segment count`;
                 }
                 const detail = offer.uncoveredDetail;
-                if (!Array.isArray(detail))
+                if (detail === undefined)
                     return `card batch offer ${at} must carry its uncovered-segment reason rows`;
                 if (detail.length !== offer.uncoveredSegments) {
                     return `card batch offer ${at} carries ${detail.length} reason rows for an uncovered-segment count of ${offer.uncoveredSegments} — one fact, two seats, and they must agree`;
                 }
-                for (const [ri, row] of detail.entries()) {
-                    if (typeof row !== "object" ||
-                        row === null ||
-                        typeof row.segment !== "string" ||
-                        !UNCOVERED_SEGMENT_REASONS.some((word) => row.reason === word)) {
-                        return `card batch offer ${at} reason row ${ri} is not a segment/reason row from the closed reason set`;
-                    }
-                }
                 if (detail.length > 0) {
                     const rows = detail;
-                    const table = typeof rec.command === "string" ? segmentCoverageOf(rec.command, { persisted: [] }, { tool: CARD_RULE_TOOL, cwd: undefined }) : undefined;
+                    const table = typeof rec.command === "string" ? segmentCoverageOf(rec.command, { persisted: [] }, { tool: COMMAND_RULE_TOOL, cwd: undefined }) : undefined;
                     if (table === undefined) {
                         return `card batch offer ${at} carries reason rows but the record's command cannot back them — a row without a readable source command is a row nobody can audit`;
                     }
@@ -289,10 +385,10 @@ export async function prepareCardApproval(opts) {
         e.code = "config.invalid_argument";
         throw e;
     }
-    const grammar = ruleToolGrammarOf(opts.toolName);
-    const oneRuleCard = grammar === "name" || grammar === "domain" ? grammar : undefined;
-    if (opts.toolName !== CARD_RULE_TOOL && oneRuleCard === undefined)
+    const form = cardRuleFormOf(opts.toolName);
+    if (form === undefined)
         return undefined;
+    const oneRuleCard = form === "command" ? undefined : form;
     const scope = (() => {
         if (opts.scope !== undefined) {
             if (!isValidConsentScope(opts.scope)) {
@@ -319,14 +415,14 @@ export async function prepareCardApproval(opts) {
         try {
             const view = await effectiveOrThrow(storeForOwner(opts.deps.provider, owner), opts.sessionId !== undefined ? { sessionId: opts.sessionId } : undefined);
             const table = view.rules;
-            coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: CARD_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId, ...(opts.execCwd !== undefined ? { execCwd: opts.execCwd } : {}) });
+            coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: COMMAND_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId, ...(opts.execCwd !== undefined ? { execCwd: opts.execCwd } : {}) });
         }
         catch {
             coverage = undefined;
         }
     }
     const suggested = oneRuleCard !== undefined
-        ? [oneRuleCard === "name" ? suggestRuleForName(opts.toolName, opts.command) : suggestRuleForHost(opts.toolName, opts.command)].filter((o) => o !== undefined)
+        ? [oneRuleCard === "name" ? suggestRuleForName(opts.toolName, opts.command) : oneRuleCard === "domain" ? suggestRuleForHost(opts.toolName, opts.command) : opts.command === "" ? suggestRuleForTool(opts.toolName) : undefined].filter((o) => o !== undefined)
         : suggestRulesForCommand(opts.command, {
             ...(coverage !== undefined ? { coverage } : {}),
             scope,
@@ -378,7 +474,6 @@ export async function prepareCardApproval(opts) {
         candidates,
     };
 }
-const CARD_RULE_TOOL = "Bash";
 export async function confirmRuleApproval(opts) {
     const caller = resolveCallerOwner(opts.principal, opts.owner, "confirmRuleApproval");
     const no = (reason, detail) => ({
@@ -456,6 +551,9 @@ function checkEditedRuleText(text, command) {
     const parsed = parseSubmittedSpelling(text);
     if ("reject" in parsed)
         return { ok: false, code: parsed.reject.code, message: parsed.reject.message };
+    if (parsed.rule.match === "tool") {
+        return { ok: false, message: `the edited rule "${parsed.rule.rule}" names the whole tool — a card's edit names a command rule, and a standing yes to every command is not one a card mints` };
+    }
     if (!ruleAdmitsCommand(parsed.rule, command)) {
         return {
             ok: false,
@@ -748,18 +846,15 @@ export async function prepareCcImport(opts) {
                     skipped.push({ rule: String(entry), reason: `settings ${behavior} entry is not a string` });
                     continue;
                 }
-                if (!/^[A-Za-z][A-Za-z0-9_]*\(.*\)$/.test(entry)) {
-                    const reason = /^[A-Za-z][A-Za-z0-9_-]*$/.test(entry)
-                        ? "unsupported.form: a bare tool-name entry is a name-set item, not a command rule — it stays in the settings file, unimported"
-                        : "unsupported.form: not a command rule spelling this version imports — it stays in the settings file, unimported";
-                    skipped.push({ rule: entry, reason });
-                    continue;
-                }
                 const parsed = parseRuleText(entry, behavior);
                 if ("reject" in parsed) {
                     skipped.push({ rule: entry, reason: `${parsed.reject.code}: ${parsed.reject.message}` });
                     continue;
                 }
+                if (parsed.rule.match === "tool") {
+                    skipped.push({ rule: entry, reason: "unsupported.form: a bare tool-name entry is a name-set item the host carries from the settings layer's own lists — it stays in the settings file, unimported" });
+                    continue;
+                }
                 if (candidates.some((c) => c.behavior === behavior && c.rule === parsed.rule.rule && sameScope(c.scope, scope)))
                     continue;
                 candidates.push({ behavior, rule: parsed.rule.rule, scope });

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

@@ -77,6 +77,7 @@ 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 NamedCall } from "./tool-name-readings.js";
 import { type PathDenialEvidence, type PathFamily, type PathIdentity } from "../tools/fs/safety.js";
 import { type TargetViews } from "./path-rule-binding.js";
 /**
@@ -284,6 +285,18 @@ export declare const DOMAIN_RULE_MARKER = "domain:";
  */
 export type RuleGrammar = "command" | "path" | "name" | "domain";
 export declare function ruleToolGrammarOf(toolName: string): RuleGrammar | undefined;
+/**
+ * THE rule a tool's approval card mints a "don't ask again" option in — one answer, read by the offer factory and the consent door
+ * alike: `command` for the command rule word (the shell card's command rules), `name` / `domain` for a tool of those grammars (the one
+ * exact value rule), `tool` for a call no rule word speaks for under any name it answers to ({@link laneToolNamesOf} empty: the
+ * whole-tool rule, the reference's fallback card), and `undefined` for the rest — a path tool (no path offer is minted), a shell-face
+ * sibling of the command word (its commands are `Bash(…)` rules), and a tool that answers to one of those under an alias it declares
+ * (a caller's shell wearing `Bash`: a one-click whole-tool yes on it would be a licence for every program): its card names that it has
+ * no rule to offer. `toolName` is the wire name the card mints on; `call` the call's names (absent: the wire name alone — the
+ * consent door, which holds no face).
+ */
+export type CardRuleForm = "command" | "name" | "domain" | "tool";
+export declare function cardRuleFormOf(toolName: string, call?: NamedCall): CardRuleForm | 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;
@@ -311,11 +324,11 @@ export declare function nameRuleSubjectOf(toolName: string, args: unknown): stri
  *  domain tool's its own name — so a stored `Bash(…)` or `Edit(…)` row reaches a tool that answers to that name under another wire
  *  name, as a policy's rule does. Every lane that judges a call by a rule's word reads it here: the policy compiler, the
  *  person's stored rows, the org partition, the allow lists. Empty ⇒ no grammar speaks for the call. */
-export declare function laneToolNamesOf(req: Pick<import("./tool-policy.js").ToolCallRequest, "toolName" | "face">): readonly string[];
+export declare function laneToolNamesOf(req: NamedCall): readonly string[];
 /** 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", "pattern", "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", "tool"];
 /**
  * Match forms, one family per grammar (`prefix` and `wildcard` are one predicate):
  *  · `exact` — admits the one string the rule spells.
@@ -347,6 +360,8 @@ export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildc
  *  · `name` / `name_prefix` — the NAME grammar ({@link parseNameRuleContent}).
  *  · `host` / `subdomain` — the DOMAIN grammar ({@link parseDomainRuleContent}): one exact host, or every
  *    host below one domain.
+ *  · `tool` — the WHOLE-TOOL form, a rule with no content (`SendUserFile`, `Bash`, `mcp__srv__get_issue`), on any tool:
+ *    `command` is empty and the rule reaches every call that answers to the name it spells ({@link wholeToolRuleReaches}).
  */
 export type PersistedRuleMatch = (typeof PERSISTED_RULE_MATCHES)[number];
 /**
@@ -460,6 +475,9 @@ export type RuleRejectCode = "invalid.grammar" | "invalid.empty_command" | "inva
 export interface RuleReject {
     code: RuleRejectCode;
     message: string;
+    /** For a text that is no rule spelling only because of white space (a tab, a no-break space included) around it or before its `(`:
+     *  the rule spelling it is a blank away from ({@link respelledRuleTextOf}) — named in `message`, never read in its place. */
+    respelling?: string;
 }
 /** The parsed, canonical shape of one rule text under one behavior — everything but the scope and the
  *  provenance. The behavior is the parser's INPUT (it decides which validator floor applies), carried
@@ -718,6 +736,13 @@ export declare function ruleContentOf(parsed: ParsedPermissionRule): string | un
  * most wants. The tightening behaviors therefore admit the interpreter-headed prefix form and change
  * nothing else; the allow floor is unchanged.
  */
+/**
+ * The rule spelling a text the rule syntax cannot read is a blank away from: the text with the white space (tabs included) around
+ * it and before its first `(` taken off, when that reads as a rule under `behavior` — its canonical text — else `undefined`. A text
+ * holding an invisible format character never gets here (its one caller refuses it first: `invalid.control_chars`, or `invalid.too_long`). Only what a refusal SAYS: a rule text is read as written ({@link parseRuleText}), so the way out is named, never
+ * taken (a door that reads the respelled text would be a second reading of the same text).
+ */
+export declare function respelledRuleTextOf(text: string, behavior: RuleBehavior): string | undefined;
 export declare function parseRuleText(text: string, behavior: RuleBehavior): {
     rule: ParsedRule;
 } | {
@@ -745,8 +770,8 @@ export type NameRuleReach = "reached" | "not_reached" | "unread";
 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. */
+/** Does a domain rule reach this host (as `hostOfUrl` reads it)? The pattern's own reach ({@link hostPatternAdmits}); a rule of
+ *  any other family reaches no host. */
 export declare function domainRuleAdmits(rule: Pick<PersistedRule, "match" | "command">, host: string): boolean;
 /**
  * The closed set of BASES a path-form pattern resolves against — facts of the CALL (its execution
@@ -1255,7 +1280,8 @@ export interface CallHosts {
  * 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.
+ * nothing. A stored row whose text the rule reader reads as no rule reaches this walk from the person's rule lane only as a deny
+ * or an ask (its fields still tighten); the lane answers a call none of the rows refuses as one it cannot judge.
  */
 export declare function adjudicatePersistedDomainRules(rules: readonly PersistedRule[], call: {
     tool: string;
@@ -1264,6 +1290,32 @@ export declare function adjudicatePersistedDomainRules(rules: readonly Persisted
     sessionId?: string;
     scopeIdentity?: ScopeRootIdentity;
 }): PersistedRuleVerdict | undefined;
+/**
+ * THE predicate of a whole-tool rule (`match: "tool"`) over one call: the rule reaches the call iff the call answers to the name it
+ * spells, under every name the call answers to (the model's spelling, the wire name, the aliases that resolve to it) — the
+ * reference's tool-wide matcher. Every reader of a rule with no content asks it: an entry list's whole-tool row and a person's stored
+ * whole-tool row alike.
+ */
+export declare function wholeToolRuleReaches(tool: string, call: NamedCall): boolean;
+/**
+ * The whole-tool sibling of {@link adjudicatePersistedRules}: the same precedence walk (deny > ask > allow) over the whole-tool rows
+ * (`match: "tool"`) that reach the call ({@link wholeToolRuleReaches}) and are eligible under their own tool ({@link eligiblePersisted},
+ * the one predicate); the first behavior with such a row decides, the first table-order row of it is the answer.
+ */
+export declare function adjudicatePersistedToolRules(rules: readonly PersistedRule[], call: {
+    request: NamedCall;
+    cwd: string | undefined;
+    sessionId?: string;
+    scopeIdentity?: ScopeRootIdentity;
+}): PersistedRuleVerdict | undefined;
+/**
+ * The ONE offer the card of a tool with no rule grammar carries ({@link cardRuleFormOf} `tool`): the whole-tool rule on its name (the
+ * reference's fallback card, "don't ask again for <tool>"), or undefined when the name has no such rule (the round-trip law: the bare
+ * name, parsed back as an allow, must be the whole-tool rule on that very name).
+ */
+export declare function suggestRuleForTool(tool: string): Extract<RuleOffer, {
+    kind: "single";
+}> | 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

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

@@ -2,13 +2,15 @@ import { homedir } from "node:os";
 import { shellWordsOf } from "../shell/shell-words.js";
 import { lexShell } from "../shell/lex.js";
 import { readProgramPosition } from "../tools/fs/bash-program-position.js";
-import { parsePermissionRule } from "./permission-rule-syntax.js";
+import { isNameableToolName, parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
+import { isCoveringRuleName } from "./namespaced-rule-name.js";
+import { toolNameFaultOf } from "./tool-name-aliases.js";
 import { compileReadDeny } from "../tools/fs/read-deny.js";
 import { carriesShellRedirection, parseLeadingCommandName, splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
 import { INLINE_TRUNCATION_MARK, inlineUntrusted } from "./untrusted-text.js";
-import { catalogRuleFaceOf, hostTargetOf, isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
-import { HOST_UNREADABLE_SENTENCE, hostOfSpelling, isAddressHost } from "./host-target.js";
-import { heldValues } from "./tool-name-readings.js";
+import { catalogRuleFaceOf, catalogToolNames, hostTargetOf, isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
+import { HOST_UNREADABLE_SENTENCE, hostPatternAdmits, readHostPattern, spelledHostPattern } from "./host-target.js";
+import { heldBy, heldValues } from "./tool-name-readings.js";
 import { carriesDotSegment, isAbsoluteForFamily, isIdentityDir, isPathIdentity, isShellRootedSpellingUnmapped, isUncIdentity, pathFamilyOf, pathIdentityOf } from "../tools/fs/safety.js";
 import { bindPathRules, judgeRuleRows, rowsWhereTheyLead } from "./path-rule-binding.js";
 import { readShellCommand } from "./shell-run-candidates.js";
@@ -135,6 +137,14 @@ export function ruleToolGrammarOf(toolName) {
         return "domain";
     return pathTargetOf(toolName) !== undefined ? "path" : undefined;
 }
+export function cardRuleFormOf(toolName, call = { toolName }) {
+    if (toolName === COMMAND_RULE_TOOL)
+        return "command";
+    const grammar = ruleToolGrammarOf(toolName);
+    if (grammar === "name" || grammar === "domain")
+        return grammar;
+    return grammar === undefined && laneToolNamesOf(call).length === 0 && laneToolNamesOf({ toolName }).length === 0 ? "tool" : undefined;
+}
 export function shellRuleParamOf(tool, content) {
     const colon = content.indexOf(":");
     if (colon <= 0)
@@ -172,7 +182,7 @@ function ruleWordOf(name) {
         return COMMAND_RULE_TOOL;
     return ruleToolGrammarOf(name) !== undefined ? name : undefined;
 }
-export const PERSISTED_RULE_MATCHES = Object.freeze(["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain"]);
+export const PERSISTED_RULE_MATCHES = Object.freeze(["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain", "tool"]);
 function isCommandMatch(match) {
     return match === "exact" || match === "prefix" || match === "wildcard" || match === "pattern";
 }
@@ -406,6 +416,28 @@ export function ruleContentOf(parsed) {
     const content = parsed.ruleContent;
     return content === undefined || (parsed.toolName === COMMAND_RULE_TOOL && foldSpacing(content) === "*") ? undefined : content;
 }
+export function respelledRuleTextOf(text, behavior) {
+    const outer = text.trim();
+    const open = outer.indexOf("(");
+    const candidate = open < 0 ? outer : outer.slice(0, open).replace(/\s+$/u, "") + outer.slice(open);
+    if (candidate === text || ruleSpellingOf(candidate) === undefined)
+        return undefined;
+    const read = parseRuleText(candidate, behavior);
+    return "rule" in read ? read.rule.rule : undefined;
+}
+function parseWholeToolRule(text, tool, behavior) {
+    if (!isNameableToolName(tool) || isCoveringRuleName(tool, behavior)) {
+        return reject("invalid.grammar", `"${text}" names a set of tools — a stored rule names one tool, or one tool's content; a set of tools is a list entry's form`);
+    }
+    const fault = toolNameFaultOf(tool, catalogToolNames(), behavior);
+    if (fault === undefined)
+        return { rule: { behavior, rule: tool, tool, match: "tool", command: "" } };
+    const why = fault.reason === "near_miss"
+        ? `is another spelling of "${fault.currentName}", which the engine's tool catalog names — a rule names its tool exactly as spelled, so this one would reach no tool`
+        : `names no tool under that name${fault.guidance !== undefined ? ` — ${fault.guidance}` : ""}`;
+    const write = fault.currentName !== undefined && !why.includes(`"${fault.currentName}"`) ? `; write "${fault.currentName}"` : "";
+    return reject("unsupported.tool", `"${text}" ${why}${write}`);
+}
 export function parseRuleText(text, behavior) {
     if (!isRuleBehavior(behavior)) {
         return reject("invalid.grammar", `rule "${text}" was parsed under behavior ${escapeForDisclosure(behavior)}, which is not one of ${RULE_BEHAVIORS.join("/")}`);
@@ -417,11 +449,20 @@ export function parseRuleText(text, behavior) {
     if (CONTROL_CHARS_RE.test(text)) {
         return reject("invalid.control_chars", "rule text contains control characters (C0/C1, tab excepted), which cannot be part of a readable command");
     }
-    const parsed = parsePermissionRule(text);
-    const ruleContent = ruleContentOf(parsed);
-    if (ruleContent === undefined) {
-        return reject("invalid.grammar", `"${text}" is not a Tool(content) rule — a bare tool name claims the whole tool and is not a command rule`);
+    const parsed = ruleSpellingOf(text);
+    if (parsed === undefined) {
+        const respelling = respelledRuleTextOf(text, behavior);
+        return {
+            reject: {
+                code: "invalid.grammar",
+                message: `"${text}" is not a rule spelling — a rule is the tool's name exactly as spelled, then its content in parentheses (no blank, tab or invisible character around the rule or before the "("), and the ")" ends it${respelling !== undefined ? `; spelled as a rule it is "${respelling}"` : ""}`,
+                ...(respelling !== undefined ? { respelling } : {}),
+            },
+        };
     }
+    const ruleContent = ruleContentOf(parsed);
+    if (ruleContent === undefined)
+        return parseWholeToolRule(text, parsed.toolName, behavior);
     if (parsed.toolName !== COMMAND_RULE_TOOL) {
         const grammar = ruleToolGrammarOf(parsed.toolName);
         if (grammar === undefined) {
@@ -491,6 +532,8 @@ export function parseRuleText(text, behavior) {
     return { rule: { behavior, rule: formatRuleText(command, match, COMMAND_RULE_TOOL), tool: COMMAND_RULE_TOOL, match, command } };
 }
 export function formatRuleText(command, match, tool) {
+    if (match === "tool")
+        return tool;
     if (match === "subpath")
         return `${tool}(//${command.startsWith("/") ? command.slice(1) : command}/**)`;
     if (match === "path")
@@ -498,7 +541,7 @@ export function formatRuleText(command, match, tool) {
     if (match === "name")
         return `${tool}(${keyedValueParamOf(tool) !== undefined ? `${keyedValueParamOf(tool)}:` : ""}${command})`;
     if (match === "host" || match === "subdomain")
-        return `${tool}(domain:${match === "subdomain" ? "*." : ""}${command})`;
+        return `${tool}(domain:${spelledHostPattern({ match, host: command })})`;
     return `${tool}(${command}${match === "prefix" || match === "name_prefix" ? ":*" : match === "wildcard" ? " *" : ""})`;
 }
 function parseNameRuleContent(text, tool, content, behavior, verifyCanonical = true) {
@@ -606,30 +649,26 @@ function parseDomainRuleContent(text, tool, content, behavior) {
     if (!content.startsWith(DOMAIN_RULE_MARKER)) {
         return reject("invalid.grammar", `a ${tool} rule names a host: ${tool}(domain:<host>) for one, ${tool}(domain:*.<domain>) for every host below a domain ("${text}")`);
     }
-    const spelled = content.slice(DOMAIN_RULE_MARKER.length);
-    if (spelled === "*")
-        return reject("unsupported.wildcard", `"${text}" names every host — the whole tool is the bare ${tool} entry`);
-    const below = spelled.startsWith("*.");
-    const body = below ? spelled.slice(2) : spelled;
-    if (body.includes("*")) {
-        return reject("unsupported.wildcard", `a \`*\` in "${text}" other than a leading \`*.\` has no rule form — a ${tool} rule names one host, or every host below one domain with \`*.<domain>\``);
-    }
-    const host = hostOfSpelling(body);
-    if (host === undefined || hostOfSpelling(host) !== host) {
-        return reject("invalid.grammar", `"${text}" does not name a host alone — write the host as a URL carries it, with no scheme, path, port or credentials`);
+    const read = readHostPattern(content.slice(DOMAIN_RULE_MARKER.length));
+    if ("problem" in read) {
+        switch (read.problem) {
+            case "every_host":
+                return reject("unsupported.wildcard", `"${text}" names every host — the whole tool is the bare ${tool} entry`);
+            case "inner_wildcard":
+                return reject("unsupported.wildcard", `a \`*\` in "${text}" other than a leading \`*.\` has no rule form — a ${tool} rule names one host, or every host below one domain with \`*.<domain>\``);
+            case "empty_label":
+                return reject("invalid.grammar", `"${text}" names a host with an empty label (a leading or doubled dot) — write the host itself, and every host below a domain as \`*.<domain>\``);
+            case "not_a_host":
+                return reject("invalid.grammar", `"${text}" does not name a host alone — write the host as a URL carries it, with no scheme, path, port or credentials`);
+            case "below_address":
+                return reject("invalid.grammar", `"${text}" names hosts below an address, which has none — write the address itself`);
+        }
     }
-    if (below && isAddressHost(host))
-        return reject("invalid.grammar", `"${text}" names hosts below an address, which has none — write the address itself`);
-    const match = below ? "subdomain" : "host";
+    const { match, host } = read.pattern;
     return { rule: { behavior, rule: formatRuleText(host, match, tool), tool, match, command: host } };
 }
 export function domainRuleAdmits(rule, host) {
-    if (rule.match === "host")
-        return host === rule.command;
-    if (rule.match !== "subdomain" || isAddressHost(host) || !host.endsWith(`.${rule.command}`))
-        return false;
-    const labels = host.slice(0, -(rule.command.length + 1));
-    return labels !== "" && !labels.split(".").includes("");
+    return (rule.match === "host" || rule.match === "subdomain") && hostPatternAdmits({ match: rule.match, host: rule.command }, host);
 }
 function parsePathRuleContent(text, tool, content, behavior) {
     if (behavior === "allow" && PATH_RULE_FACES[tool]?.allow === undefined) {
@@ -1303,7 +1342,7 @@ export function commandCoverageOf(rules, call) {
     return covering.length > 0 ? { covering } : { uncovered: undefined };
 }
 function readsOnlyAsSegment(segment, lineObjection, whole) {
-    return lineObjection === undefined && !movesShellCursor(segment) && readOnlyShellVerdict(segment, undefined, undefined, () => lineDescriptorsOfText(whole)).readOnly;
+    return lineObjection === undefined && !movesShellCursor(segment) && readOnlyShellVerdict(segment, { bound: () => lineDescriptorsOfText(whole) }).readOnly;
 }
 function firstEligibleDirectoryRule(rules, directory, call) {
     for (const rule of rules) {
@@ -1419,6 +1458,26 @@ export function adjudicatePersistedDomainRules(rules, call) {
     }
     return undefined;
 }
+export function wholeToolRuleReaches(tool, call) {
+    return heldBy("policy.persistedToolRule", { has: (name) => name === tool }, call);
+}
+export function adjudicatePersistedToolRules(rules, call) {
+    const at = { cwd: call.cwd, ...(call.sessionId !== undefined ? { sessionId: call.sessionId } : {}), ...(call.scopeIdentity !== undefined ? { scopeIdentity: call.scopeIdentity } : {}) };
+    for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
+        const row = rules.find((rule) => rule.match === "tool" && wholeToolRuleReaches(rule.tool, call.request) && eligiblePersisted(rule, { ...at, tool: rule.tool }, behavior));
+        if (row !== undefined)
+            return { behavior, rules: [row] };
+    }
+    return undefined;
+}
+export function suggestRuleForTool(tool) {
+    if (cardRuleFormOf(tool) !== "tool")
+        return undefined;
+    const parsed = parseRuleText(formatRuleText("", "tool", tool), "allow");
+    if (!("rule" in parsed) || parsed.rule.match !== "tool" || parsed.rule.tool !== tool)
+        return undefined;
+    return { kind: "single", rule: parsed.rule.rule, match: "tool", command: "" };
+}
 export function suggestRuleForHost(tool, host) {
     if (ruleToolGrammarOf(tool) !== "domain")
         return undefined;

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

@@ -224,6 +224,9 @@ export interface UnreadableOrgRow {
     readonly rule: string;
     readonly code: RuleRejectCode;
     readonly detail?: string;
+    /** The rule spelling a row that is no rule spelling only because of white space (a tab, a no-break space) is a blank away from — the
+     *  text to republish it as; the row itself is still read as unreadable (one spelling reader, fail-closed). */
+    readonly respelling?: string;
     readonly behavior: "deny" | "ask";
     readonly reach: OrgRowReach;
 }
@@ -327,8 +330,9 @@ export declare function unenforceableOrgRules(rules: readonly OrgPermissionRule[
     rule: string;
     code: RuleRejectCode;
 }>;
-/** The reason an unreadable row's verdict carries — its place in the snapshot, its code, and the repair. */
-export declare function unreadableOrgRowReason(row: Pick<UnreadableOrgRow, "index" | "code" | "detail">): string;
+/** The reason an unreadable row's verdict carries — its place in the snapshot, its code, and the repair: for a row that is no rule
+ *  spelling only because of white space (a tab, a no-break space), its text and the spelling to republish it as. */
+export declare function unreadableOrgRowReason(row: Pick<UnreadableOrgRow, "index" | "code" | "detail" | "rule" | "respelling">): string;
 /** The ONE clause for an org verdict that carries an `unreadable` reason — a rule the call could not be read against, or
  *  a row this layer cannot read — on a refusal and on a question alike. */
 export declare function orgUnreadableClause(reason: string): string;