@sema-agent/core 7.54.1 → 7.56.0

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

@@ -1,17 +1,21 @@
 import { homedir } from "node:os";
 import { shellWordsOf } from "../shell/shell-words.js";
-import { parsePermissionRule } from "./permission-rule-syntax.js";
+import { lexShell } from "../shell/lex.js";
+import { readProgramPosition } from "../tools/fs/bash-program-position.js";
+import { parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.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 { isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
+import { catalogRuleFaceOf, hostTargetOf, isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
+import { HOST_UNREADABLE_SENTENCE, hostPatternAdmits, readHostPattern, spelledHostPattern } from "./host-target.js";
 import { 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";
 import { lineDescriptorsOfText, readOnlyLineObjection, readOnlyShellVerdict } from "./read-only-shell.js";
 import { ARTIFACT_ACTIONS } from "./artifact-host.js";
-import { ARTIFACT_TOOL_NAME } from "./tool-catalog-entries.js";
+import { ARTIFACT_TOOL_NAME, TOOL_CATALOG_ENTRIES } from "./tool-catalog-entries.js";
+import { paramRuleReaches } from "./param-rule-reach.js";
 export const RULE_BEHAVIORS = Object.freeze(["deny", "ask", "allow"]);
 const RULE_BEHAVIOR_SET = new Set(RULE_BEHAVIORS);
 export function isRuleBehavior(v) {
@@ -43,64 +47,121 @@ export function callPathFaceOf(call) {
 export function faceRowsSpeakFor(face) {
     return face !== undefined && Object.values(PATH_RULE_FACES).some((columns) => columns.deny?.includes(face) === true || columns.ask?.includes(face) === true);
 }
+function catalogVocabularyOf(tool) {
+    const params = catalogRuleFaceOf(tool)?.params;
+    if (params === undefined)
+        throw new Error(`permission rules: the catalog declares no rule vocabulary for ${JSON.stringify(tool)}`);
+    return params;
+}
+const DELEGATION_RULE_TOOL = (() => {
+    const row = TOOL_CATALOG_ENTRIES.find((e) => e.id === "agent");
+    if (row === undefined)
+        throw new Error("permission rules: the catalog carries no delegation tool row (`agent`)");
+    return row.name;
+})();
 export const NAME_RULE_FACES = Object.freeze({
-    Skill: Object.freeze({ param: "skill", params: Object.freeze(["skill", "args"]) }),
+    Skill: Object.freeze({ param: "skill", params: Object.freeze(catalogVocabularyOf("Skill")) }),
     [ARTIFACT_TOOL_NAME]: Object.freeze({ param: "action", params: Object.freeze(["action"]), words: ARTIFACT_ACTIONS }),
+    [DELEGATION_RULE_TOOL]: Object.freeze({ param: "subagent_type", params: Object.freeze(["subagent_type"]), values: "mounted" }),
 });
+function nameRuleFaceOf(tool) {
+    return Object.hasOwn(NAME_RULE_FACES, tool) ? NAME_RULE_FACES[tool] : undefined;
+}
 function keyedValueParamOf(tool) {
-    const face = Object.hasOwn(NAME_RULE_FACES, tool) ? NAME_RULE_FACES[tool] : undefined;
+    const face = nameRuleFaceOf(tool);
     return face?.words !== undefined ? face.param : undefined;
 }
-export function keyedValueAbsentReason(tool) {
-    const key = keyedValueParamOf(tool);
-    return key === undefined ? undefined : `the ${tool} call names no ${key} as the tool reads it, so the ${key} it runs is not one its arguments show — a rule by ${key} cannot be read against it`;
+export function normalizeSubagentType(value) {
+    return value.normalize("NFKC").toLowerCase().replace(/[\p{White_Space}\p{Pd}_]+/gu, "");
+}
+export function canonicalNameValue(value, values) {
+    if (values.includes(value))
+        return { kind: "entry", entry: value };
+    const key = normalizeSubagentType(value);
+    const hits = key === "" ? [] : [...new Set(values.filter((v) => normalizeSubagentType(v) === key))];
+    if (hits.length === 1)
+        return { kind: "entry", entry: hits[0] };
+    return hits.length > 1 ? { kind: "ambiguous", entries: hits } : { kind: "unknown" };
+}
+export function nameValueAbsentReason(tool) {
+    const face = nameRuleFaceOf(tool);
+    if (face === undefined || (face.words === undefined && face.values === undefined))
+        return undefined;
+    const key = face.param;
+    return `the ${tool} call names no ${key} as the tool reads it, so the ${key} it runs is not one its arguments show — a rule by ${key} cannot be read against it`;
 }
 export function nameGrammarReads(tool, content) {
     if (ruleToolGrammarOf(tool) !== "name")
         return false;
-    const key = keyedValueParamOf(tool);
-    if (key === undefined)
-        return true;
+    const face = nameRuleFaceOf(tool);
+    const key = contentKeyOf(content);
+    if (face.words !== undefined)
+        return key === face.param;
+    return key === undefined || face.params.includes(key) || !(catalogRuleFaceOf(tool)?.params ?? []).includes(key);
+}
+export function mountedValueArmOf(text, tool, behavior) {
+    if (behavior === "allow" || nameRuleFaceOf(tool)?.values !== "mounted")
+        return undefined;
+    const parsed = parseRuleText(text, behavior);
+    return "rule" in parsed && parsed.rule.match === "name" ? parsed.rule : undefined;
+}
+export function mountedOnlyArgumentOf(tool, content, mountedParams) {
+    if (nameRuleFaceOf(tool)?.values !== "mounted" || mountedParams === undefined)
+        return undefined;
+    const key = contentKeyOf(content);
+    return key !== undefined && mountedParams.includes(key) && !(catalogRuleFaceOf(tool)?.params ?? []).includes(key) ? key : undefined;
+}
+export function mountedArgumentArmOf(rule) {
+    const face = nameRuleFaceOf(rule.tool);
+    if (rule.behavior === "allow" || rule.match !== "name" || face?.values !== "mounted")
+        return undefined;
+    const key = contentKeyOf(rule.command);
+    if (key === undefined || face.params.includes(key) || !(catalogRuleFaceOf(rule.tool)?.params ?? []).includes(key))
+        return undefined;
+    const pattern = rule.command.slice(rule.command.indexOf(":") + 1).trim();
+    return pattern === "" ? undefined : { param: key, pattern };
+}
+function contentKeyOf(content) {
     const colon = content.indexOf(":");
-    return colon > 0 && content.slice(0, colon).trim() === key;
+    return colon > 0 ? content.slice(0, colon).trim() : undefined;
 }
-export const DOMAIN_RULE_FACES = Object.freeze({
-    WebFetch: Object.freeze({ param: "url" }),
-});
+export const DOMAIN_RULE_MARKER = "domain:";
 export function ruleToolGrammarOf(toolName) {
     if (toolName === COMMAND_RULE_TOOL)
         return "command";
     if (Object.hasOwn(NAME_RULE_FACES, toolName))
         return "name";
-    if (Object.hasOwn(DOMAIN_RULE_FACES, toolName))
+    if (hostTargetOf(toolName) !== undefined)
         return "domain";
     return pathTargetOf(toolName) !== undefined ? "path" : undefined;
 }
-export function domainRuleSubjectOf(toolName, args) {
-    const face = Object.hasOwn(DOMAIN_RULE_FACES, toolName) ? DOMAIN_RULE_FACES[toolName] : undefined;
-    if (face === undefined || typeof args !== "object" || args === null || Array.isArray(args) || !Object.hasOwn(args, face.param))
-        return undefined;
-    const value = args[face.param];
-    if (typeof value !== "string")
-        return undefined;
-    let url;
-    try {
-        url = new URL(value);
-    }
-    catch {
+export function shellRuleParamOf(tool, content) {
+    const colon = content.indexOf(":");
+    if (colon <= 0)
         return undefined;
+    const param = content.slice(0, colon).trim();
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(param) && (catalogRuleFaceOf(tool)?.params ?? []).includes(param) ? param : undefined;
+}
+export function ruleLaneOf(tool, content) {
+    if (isShellFaceToolName(tool))
+        return shellRuleParamOf(tool, content) !== undefined && !(tool === COMMAND_RULE_TOOL && content.endsWith(":*")) ? "param" : "command";
+    switch (ruleToolGrammarOf(tool)) {
+        case "name":
+            return nameGrammarReads(tool, content) ? "name" : "param";
+        case "path":
+            return content.indexOf(":") <= 0 ? "path" : "param";
+        case "domain":
+            return content.startsWith(DOMAIN_RULE_MARKER) ? "domain" : "param";
+        default:
+            return "param";
     }
-    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username !== "" || url.password !== "")
-        return undefined;
-    const host = url.hostname.replace(/\.+$/, "");
-    return host === "" ? undefined : host;
 }
 export function nameRuleSubjectOf(toolName, args) {
     const face = Object.hasOwn(NAME_RULE_FACES, toolName) ? NAME_RULE_FACES[toolName] : undefined;
     if (face === undefined || typeof args !== "object" || args === null || Array.isArray(args) || !Object.hasOwn(args, face.param))
         return undefined;
     const value = args[face.param];
-    return typeof value === "string" ? value : undefined;
+    return typeof value === "string" && value !== "" ? value : undefined;
 }
 export function laneToolNamesOf(req) {
     const words = heldValues("policy.persistedGrammar", { get: ruleWordOf }, req);
@@ -111,9 +172,9 @@ function ruleWordOf(name) {
         return COMMAND_RULE_TOOL;
     return ruleToolGrammarOf(name) !== undefined ? name : undefined;
 }
-export const PERSISTED_RULE_MATCHES = Object.freeze(["exact", "prefix", "wildcard", "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"]);
 function isCommandMatch(match) {
-    return match === "exact" || match === "prefix" || match === "wildcard";
+    return match === "exact" || match === "prefix" || match === "wildcard" || match === "pattern";
 }
 export const RULE_ADD_ORIGINS = Object.freeze(["user", "imported-cc", "starter"]);
 export const MAX_RULE_TEXT_CHARS = 512;
@@ -282,10 +343,32 @@ const CONTROL_CHARS_GLOBAL_RE = new RegExp(CONTROL_CHARS_RE.source, "gu");
 const RULE_SPELLING_REJECT_BYTES = "<>";
 const RULE_SPELLING_REJECT_RE = new RegExp(`[${RULE_SPELLING_REJECT_BYTES}]`);
 function valueRuleFormsSentence() {
-    return Object.entries(NAME_RULE_FACES)
-        .map(([tool, face]) => (face.words !== undefined ? `${tool}(${face.param}:<${face.param}>) rules` : `${tool}(<${face.param}>) rules`))
+    return Object.keys(NAME_RULE_FACES)
+        .map((tool) => `${nameRuleFormOf(tool)} rules`)
         .join(", ");
 }
+function nameRuleFormOf(tool) {
+    return formatRuleText(`<${nameRuleFaceOf(tool).param}>`, "name", tool);
+}
+export function ruleShapeOf(call, behavior) {
+    if (isShellFaceToolName(call.toolName))
+        return formatRuleText("<command>", "exact", COMMAND_RULE_TOOL);
+    switch (ruleToolGrammarOf(call.toolName)) {
+        case "name":
+            return nameRuleFormOf(call.toolName);
+        case "domain":
+            return formatRuleText("<host>", "host", call.toolName);
+        case "path": {
+            if (behavior !== "allow")
+                return formatRuleText("<path>", "path", call.toolName);
+            const face = callPathFaceOf(call) ?? (pathTargetOf(call.toolName)?.access === "read" ? "read" : "write");
+            const word = Object.keys(PATH_RULE_FACES).find((tool) => PATH_RULE_FACES[tool].allow?.includes(face) === true) ?? call.toolName;
+            return formatRuleText("<path>", "path", word);
+        }
+        default:
+            return undefined;
+    }
+}
 const DISCLOSED_RULE_TEXT_MAX_CHARS = 120;
 export function escapeForDisclosure(value) {
     let text;
@@ -319,6 +402,19 @@ export function renderUntrustedCommandText(text, maxLen = DISCLOSED_RULE_TEXT_MA
 export function hasUnrenderableCharacters(text) {
     return CONTROL_CHARS_RE.test(text);
 }
+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;
+}
 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("/")}`);
@@ -330,8 +426,19 @@ 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);
-    if (parsed.ruleContent === undefined) {
+    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 reject("invalid.grammar", `"${text}" is not a Tool(content) rule — a bare tool name claims the whole tool and is not a command rule`);
     }
     if (parsed.toolName !== COMMAND_RULE_TOOL) {
@@ -339,16 +446,16 @@ export function parseRuleText(text, behavior) {
         if (grammar === undefined) {
             return reject("unsupported.tool", `only Bash command rules, rules on path-targeting tools (Read, Edit, Write, …), ${valueRuleFormsSentence()} and WebFetch domain rules have a rule form in this version (got "${parsed.toolName}")`);
         }
-        if (!tighten && RULE_SPELLING_REJECT_RE.test(parsed.ruleContent)) {
+        if (!tighten && RULE_SPELLING_REJECT_RE.test(ruleContent)) {
             return reject("invalid.grammar", `"${text}" carries a shell redirection byte (${[...RULE_SPELLING_REJECT_BYTES].map((b) => `\`${b}\``).join(" or ")}) — no path, name or host allow spells one, and the grant would not read as what it looks like`);
         }
         if (grammar === "name")
-            return parseNameRuleContent(text, parsed.toolName, parsed.ruleContent, behavior);
+            return parseNameRuleContent(text, parsed.toolName, ruleContent, behavior);
         if (grammar === "domain")
-            return parseDomainRuleContent(text, parsed.toolName, parsed.ruleContent, behavior);
-        return parsePathRuleContent(text, parsed.toolName, parsed.ruleContent, behavior);
+            return parseDomainRuleContent(text, parsed.toolName, ruleContent, behavior);
+        return parsePathRuleContent(text, parsed.toolName, ruleContent, behavior);
     }
-    const content = parsed.ruleContent;
+    const content = foldSpacing(ruleContent) ?? ruleContent;
     const prefixBody = /^(.+):\*$/.exec(content)?.[1];
     let match;
     let body;
@@ -366,14 +473,18 @@ export function parseRuleText(text, behavior) {
             body = wildcardBody;
         }
         else if (hasUnescapedStar(content)) {
-            return reject("unsupported.wildcard", `a \`*\` before the end of the pattern matches anything at that position, which has no rule form in this version — only the trailing \`<command> *\` form does ("${text}")`);
+            match = "pattern";
+            body = content;
         }
         else {
             match = "exact";
             body = content;
         }
     }
-    const shape = ruleLaneShapeOf(body, MATCH_READING);
+    if (match === "pattern" && !tighten && hasUnescapedStar(body.trim().split(/[ \t]+/)[0] ?? "")) {
+        return reject("unsupported.wildcard", `a \`*\` in the first word of "${text}" leaves open which program runs — an allow names the program it grants (a deny or an ask may leave it open)`);
+    }
+    const shape = ruleLaneShapeOf(match === "pattern" ? globFloorText(body) : body, MATCH_READING);
     if ("reject" in shape) {
         if (body.trim() === "" || shape.reject === "empty command")
             return reject("invalid.empty_command", `rule "${text}" names no command`);
@@ -381,14 +492,16 @@ export function parseRuleText(text, behavior) {
             return reject("invalid.unbalanced_quotes", `rule "${text}" has unbalanced quoting, so the command it names is not determinable`);
         return reject("invalid.not_simple_command", `rule "${text}" is not a command this lane can name (${shape.reject})`);
     }
-    if (match === "wildcard" && shape.segments.length > 1) {
-        return reject("unsupported.wildcard", `a \`<chain> *\` pattern names more than one command, and the trailing-star form has no chain reading — the compound-prefix form spells one with the \`:*\` marker ("${text}")`);
+    if ((match === "wildcard" || match === "pattern") && shape.segments.length > 1) {
+        return reject("unsupported.wildcard", match === "pattern"
+            ? `a \`*\` pattern names one command, and "${text}" names more than one — a compound is covered segment by segment, and the compound-prefix form spells a chain with the \`:*\` marker`
+            : `a \`<chain> *\` pattern names more than one command, and the trailing-star form has no chain reading — the compound-prefix form spells one with the \`:*\` marker ("${text}")`);
     }
     const head = commandBasename(shape.names[shape.names.length - 1] ?? "");
-    if ((match === "prefix" || match === "wildcard") && BARE_INTERPRETER_NAMES.has(head) && !tighten) {
+    if (match !== "exact" && BARE_INTERPRETER_NAMES.has(head) && !tighten) {
         return reject("invalid.bare_interpreter_prefix", shape.segments.length > 1
             ? `prefix rule "${text}" leaves its final segment open-ended under the interpreter "${head}" — such a rule authorizes running arbitrary programs, which one approval click cannot be read as having granted (an exact rule naming the whole command line is accepted)`
-            : `prefix rule "${text}" is headed by the interpreter "${head}" — such a rule authorizes running arbitrary programs, which one approval click cannot be read as having granted (an exact rule naming the whole command line is accepted)`);
+            : `${match === "pattern" ? "pattern" : "prefix"} rule "${text}" is headed by the interpreter "${head}" — such a rule authorizes running arbitrary programs, which one approval click cannot be read as having granted (an exact rule naming the whole command line is accepted)`);
     }
     const command = foldSpacing(body);
     if (command === undefined) {
@@ -404,13 +517,15 @@ 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) {
     const face = NAME_RULE_FACES[tool];
     if (face?.words !== undefined)
         return parseKeyedValueRuleContent(text, tool, content, behavior, { param: face.param, words: face.words });
+    if (face?.values === "mounted")
+        return parseMountedValueRuleContent(text, tool, content, behavior, face);
     const bare = content.startsWith("/") ? content.slice(1) : content;
     const colon = bare.indexOf(":");
     if (face !== undefined && colon > 0 && face.params.includes(bare.slice(0, colon).trim())) {
@@ -457,6 +572,28 @@ function parseKeyedValueRuleContent(text, tool, content, behavior, face) {
     }
     return { rule: { behavior, rule: formatRuleText(word, "name", tool), tool, match: "name", command: word } };
 }
+function parseMountedValueRuleContent(text, tool, content, behavior, face) {
+    const form = nameRuleFormOf(tool);
+    const key = contentKeyOf(content);
+    if (key !== undefined && face.params.includes(key)) {
+        return reject("invalid.grammar", `"${text}" is the parameter spelling, which a ${tool} rule does not have — a ${tool} rule names the ${face.param} itself: ${form}`);
+    }
+    if (behavior === "allow" && key !== undefined && (catalogRuleFaceOf(tool)?.params ?? []).includes(key)) {
+        return reject("invalid.grammar", `"${text}" is a rule on the ${key} argument, which an allow entry has no form for — an allow reads one way, so it does not grant the ${face.param} "${content}" either; a ${tool} allow names the ${face.param}: ${form}`);
+    }
+    if (content === "" || content.trim() !== content) {
+        return reject("invalid.grammar", `the ${face.param} in "${text}" is empty or carries surrounding whitespace — a ${tool} rule names the ${face.param} exactly as it is spelled, so the spelling must be the one meant`);
+    }
+    if (content.includes("*")) {
+        return reject("unsupported.wildcard", `a \`*\` in the ${face.param} of "${text}" has no rule form — a ${tool} rule names one ${face.param} (${form}); the whole tool is the bare ${tool} entry`);
+    }
+    const canonical = formatRuleText(content, "name", tool);
+    const back = parsePermissionRule(canonical);
+    if (back.toolName !== tool || back.ruleContent !== content) {
+        return reject("invalid.grammar", `the ${face.param} in "${text}" has no spelling the rule syntax reads back (a backslash or an unbalanced parenthesis) — no ${tool} rule can name it`);
+    }
+    return { rule: { behavior, rule: canonical, tool, match: "name", command: content } };
+}
 export function nameRuleAdmits(rule, name) {
     if (rule.match === "name")
         return name === rule.command;
@@ -464,55 +601,50 @@ export function nameRuleAdmits(rule, name) {
         return name.startsWith(rule.command);
     return false;
 }
+export function nameRuleReach(rule, name, values) {
+    const face = nameRuleFaceOf(rule.tool);
+    if (face?.values !== "mounted")
+        return nameRuleAdmits(rule, name) ? "reached" : "not_reached";
+    if (rule.match !== "name")
+        return "not_reached";
+    if (values === undefined)
+        return "unread";
+    const operand = canonicalNameValue(rule.command, values);
+    const called = canonicalNameValue(name, values);
+    if (operand.kind === "ambiguous")
+        return rule.behavior !== "allow" && called.kind === "entry" && operand.entries.includes(called.entry) ? "reached" : "not_reached";
+    if (operand.kind === "entry" && called.kind === "entry")
+        return operand.entry === called.entry ? "reached" : "not_reached";
+    return name === rule.command ? "reached" : "not_reached";
+}
+export function nameValuesUnreadReason(tool) {
+    const face = nameRuleFaceOf(tool);
+    return `the ${tool} tool this call reaches declares no ${face?.param ?? "value"} values it offers, so which ${face?.param ?? "value"} the call runs cannot be read against a ${tool} rule`;
+}
 function parseDomainRuleContent(text, tool, content, behavior) {
-    if (behavior !== "allow") {
-        return reject("unsupported.tool", `a ${tool} rule by host has an allow form only in this version ("${text}") — a ${behavior} by host is not read; write the ${behavior} on the whole ${tool} tool`);
-    }
-    if (!content.startsWith("domain:")) {
+    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:".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 } };
 }
-function hostOfSpelling(spelled) {
-    if (spelled === "" || /[\s/\\@?#%]/.test(spelled) || (spelled.includes(":") && !/^\[[^\]]+\]$/.test(spelled)))
-        return undefined;
-    let url;
-    try {
-        url = new URL(`https://${spelled}/`);
-    }
-    catch {
-        return undefined;
-    }
-    if (url.port !== "" || url.username !== "" || url.password !== "" || url.pathname !== "/" || url.search !== "" || url.hash !== "")
-        return undefined;
-    const host = url.hostname.replace(/\.+$/, "");
-    return host === "" ? undefined : host;
-}
-function isAddressHost(host) {
-    return host.startsWith("[") || /^\d+\.\d+\.\d+\.\d+$/.test(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) {
@@ -712,6 +844,10 @@ const NOT_REACHED = { reach: "not_reached" };
 export function programRunReachOf(rule, command) {
     if (!isCommandMatch(rule.match))
         return NOT_REACHED;
+    if (rule.match === "pattern") {
+        const pattern = commandGlobOf(rule.command, "words");
+        return pattern === undefined ? NOT_REACHED : anySegmentReach(readCommandMemo(command), (argv) => globArgvReachOf(pattern, argv));
+    }
     const body = readRuleBody(rule.command);
     if (body === undefined)
         return NOT_REACHED;
@@ -727,7 +863,8 @@ export function programRunReachOf(rule, command) {
             return hidden === undefined ? NOT_REACHED : { reach: "unreadable", reason: hidden.peelUnreadable };
         let outcome = REACHED;
         for (let i = 0; i < body.segments.length; i++) {
-            const r = segmentReachOf(body.segments[i].argv, shape.segments[i], exact || i < body.segments.length - 1);
+            const bodyArgv = body.segments[i].argv;
+            const r = segmentReachOf(shape.segments[i], (argv) => argvReachOf(bodyArgv, argv, exact || i < body.segments.length - 1));
             if (r.reach === "not_reached")
                 return hidden === undefined ? NOT_REACHED : { reach: "unreadable", reason: hidden.peelUnreadable };
             if (r.reach === "unreadable")
@@ -736,9 +873,12 @@ export function programRunReachOf(rule, command) {
         return outcome;
     }
     const bodyArgv = body.segments[0].argv;
+    return anySegmentReach(shape, (argv) => argvReachOf(bodyArgv, argv, exact));
+}
+function anySegmentReach(shape, reachOf) {
     let unreadable;
     for (const segment of shape.segments) {
-        const r = segmentReachOf(bodyArgv, segment, exact);
+        const r = segmentReachOf(segment, reachOf);
         if (r.reach === "reached")
             return REACHED;
         if (r.reach === "unreadable")
@@ -749,12 +889,12 @@ export function programRunReachOf(rule, command) {
 export function ruleReachesProgramRun(rule, command) {
     return programRunReachOf(rule, command).reach === "reached";
 }
-function segmentReachOf(bodyArgv, segment, exact) {
+function segmentReachOf(segment, reachOf) {
     if (segment.unreadable !== undefined)
         return { reach: "unreadable", reason: segment.unreadable };
     let unreadable;
     for (const argv of [segment.argv, ...segment.peeled]) {
-        const r = argvReachOf(bodyArgv, argv, exact);
+        const r = reachOf(argv);
         if (r.reach === "reached")
             return REACHED;
         if (r.reach === "unreadable")
@@ -783,6 +923,148 @@ function argvReachOf(bodyArgv, argv, exact) {
     const loose = argv.slice(bodyArgv.length).find((w) => w.expands === "many");
     return loose === undefined ? NOT_REACHED : { reach: "unreadable", reason: `an unquoted expansion (${loose.raw}) may expand to nothing` };
 }
+const GLOB_STAR = -1;
+const GLOB_HOLE = -2;
+const GLOB_GROUP = -3;
+function globFloorText(body) {
+    let out = "";
+    for (let i = 0; i < body.length; i++) {
+        if (body[i] === "\\" && body[i + 1] === "*") {
+            out += "*";
+            i++;
+        }
+        else
+            out += body[i] === "*" ? "x" : body[i];
+    }
+    return out;
+}
+function commandGlobOf(body, reading) {
+    const shape = ruleLaneShapeOf(globFloorText(body), MATCH_READING);
+    return "reject" in shape || shape.segments.length !== 1 ? undefined : compileGlob(reading === "words" ? unquotedPattern(body) : body);
+}
+function unquotedPattern(body) {
+    let out = "";
+    let quote;
+    for (const ch of body) {
+        if (quote === undefined ? ch === "'" || ch === '"' : ch === quote)
+            quote = quote === undefined ? ch : undefined;
+        else
+            out += ch;
+    }
+    return out;
+}
+function compileGlob(pattern) {
+    const nodes = [];
+    const groupEnds = new Map();
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "\\" && pattern[i + 1] === "*") {
+            nodes.push(0x2a);
+            i++;
+            continue;
+        }
+        if (ch === "/" && pattern.startsWith("**/", i + 1)) {
+            let j = i + 1;
+            while (pattern.startsWith("**/", j))
+                j += 3;
+            nodes.push(0x2f, GLOB_GROUP, GLOB_STAR, 0x2f);
+            groupEnds.set(nodes.length - 3, nodes.length);
+            i = j - 1;
+            continue;
+        }
+        nodes.push(ch === "*" ? GLOB_STAR : ch.charCodeAt(0));
+    }
+    return { nodes, groupEnds };
+}
+function globMatches(glob, subject, holes) {
+    const { nodes, groupEnds } = glob;
+    const m = nodes.length;
+    let live = new Uint8Array(m + 1);
+    let next = new Uint8Array(m + 1);
+    const close = (set) => {
+        for (let p = 0; p < m; p++) {
+            if (set[p] !== 1)
+                continue;
+            if (nodes[p] === GLOB_STAR || nodes[p] === GLOB_GROUP)
+                set[p + 1] = 1;
+            if (nodes[p] === GLOB_GROUP)
+                set[groupEnds.get(p)] = 1;
+        }
+    };
+    live[0] = 1;
+    close(live);
+    for (const unit of subject) {
+        next.fill(0);
+        if (unit === GLOB_HOLE && holes === "any")
+            next.fill(1, live.indexOf(1));
+        else {
+            for (let p = 0; p < m; p++) {
+                if (live[p] !== 1)
+                    continue;
+                if (nodes[p] === GLOB_STAR)
+                    next[p] = 1;
+                else if (nodes[p] === unit)
+                    next[p + 1] = 1;
+            }
+            close(next);
+        }
+        if (next.indexOf(1) < 0)
+            return false;
+        [live, next] = [next, live];
+    }
+    return live[m] === 1;
+}
+function unitsOf(text) {
+    const out = [];
+    for (let i = 0; i < text.length; i++)
+        out.push(text.charCodeAt(i));
+    return out;
+}
+function globAdmitsSpelling(body, folded) {
+    const glob = commandGlobOf(body, "spelling");
+    return glob !== undefined && globMatches(glob, unitsOf(folded), "inside_star");
+}
+function globArgvReachOf(glob, argv) {
+    if (argv.length === 0)
+        return NOT_REACHED;
+    const subject = [];
+    let hole;
+    let anchored = false;
+    argv.forEach((w, k) => {
+        if (w.expands !== "many") {
+            if (anchored)
+                subject.push(0x20);
+            anchored = true;
+        }
+        if (w.expands === false)
+            subject.push(...unitsOf(w.text));
+        else {
+            subject.push(GLOB_HOLE);
+            hole ??= { at: k, raw: w.raw };
+        }
+    });
+    if (globMatches(glob, subject, "inside_star"))
+        return REACHED;
+    if (hole === undefined || !globMatches(glob, subject, "any"))
+        return NOT_REACHED;
+    return { reach: "unreadable", reason: hole.at === 0 ? "the program name is an expansion" : `an expansion (${hole.raw}) stands where the rule's pattern reads` };
+}
+export function commandPatternMayRun(body, programs) {
+    const lexed = lexShell(body);
+    const words = "parseFailure" in lexed ? undefined : lexed.segments[0]?.tokens.filter((t) => t.kind === "word");
+    if (words === undefined || words.length === 0)
+        return true;
+    const position = readProgramPosition(words);
+    const program = position.program;
+    if (program === undefined || position.refusal !== undefined || hasUnescapedStar(words[program.index]?.raw ?? "*"))
+        return true;
+    const rest = words.slice(program.index + 1).map((w) => ` ${w.raw}`).join("");
+    const glob = compileGlob(unquotedPattern(`${program.basename}${rest}`.toLowerCase()));
+    return programs.some((p) => {
+        const head = unitsOf(p.toLowerCase());
+        return globMatches(glob, head, "inside_star") || globMatches(glob, [...head, 0x20, GLOB_HOLE], "any");
+    });
+}
 function readRuleBody(body) {
     const shape = readShellCommand(body);
     if (shape.grouped || shape.segments.length === 0)
@@ -806,6 +1088,8 @@ function admitsUnder(rule, command, reading) {
         return false;
     if (rule.match === "exact")
         return folded === rule.command;
+    if (rule.match === "pattern")
+        return shape.segments.length === 1 && globAdmitsSpelling(rule.command, folded);
     const bodyShape = ruleLaneShapeOf(rule.command, reading);
     if ("reject" in bodyShape || foldSpacing(rule.command) === undefined)
         return false;
@@ -815,9 +1099,9 @@ function admitsUnder(rule, command, reading) {
 }
 export const EDITED_RULE_BREADTH_WARNING_CODES = Object.freeze(["broad_prefix", "compound_prefix"]);
 export function ruleBreadthWarningsOf(rule) {
-    if (rule.match !== "prefix" && rule.match !== "wildcard")
+    if (rule.match !== "prefix" && rule.match !== "wildcard" && rule.match !== "pattern")
         return [];
-    const bodyShape = ruleLaneShapeOf(rule.command, MATCH_READING);
+    const bodyShape = ruleLaneShapeOf(rule.match === "pattern" ? globFloorText(rule.command) : rule.command, MATCH_READING);
     if ("reject" in bodyShape)
         return [];
     if (bodyShape.segments.length > 1) {
@@ -1102,8 +1386,10 @@ export function adjudicatePersistedPathRules(rules, call, views, anchorsOf, lead
     return undefined;
 }
 export function adjudicatePersistedNameRules(rules, call) {
-    if (call.name === undefined) {
-        if (keyedValueAbsentReason(call.tool) === undefined)
+    const name = nameRuleSubjectOf(call.tool, call.request.args);
+    const values = call.request.face?.nameValues;
+    if (name === undefined) {
+        if (nameValueAbsentReason(call.tool) === undefined)
             return undefined;
         for (const behavior of ["deny", "ask"]) {
             const row = rules.find((rule) => rule.match === "name" && eligiblePersisted(rule, call, behavior));
@@ -1114,21 +1400,48 @@ export function adjudicatePersistedNameRules(rules, call) {
     }
     for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
         for (const rule of rules) {
-            if (eligiblePersisted(rule, call, behavior) && nameRuleAdmits(rule, call.name))
+            if (!eligiblePersisted(rule, call, behavior))
+                continue;
+            const arm = mountedArgumentArmOf(rule);
+            if (arm !== undefined && paramRuleReaches(call.request, arm.param, arm.pattern))
                 return { behavior, rules: [rule] };
+            const reach = nameRuleReach(rule, name, values);
+            if (reach === "reached")
+                return { behavior, rules: [rule] };
+            if (reach === "unread" && behavior !== "allow")
+                return behavior === "deny" ? { behavior, rules: [rule] } : { behavior, rules: [rule], unreadable: nameValuesUnreadReason(call.tool) };
         }
     }
     return undefined;
 }
 export function adjudicatePersistedDomainRules(rules, call) {
-    if (call.host === undefined)
-        return undefined;
-    for (const rule of rules) {
-        if (eligiblePersisted(rule, call, "allow") && domainRuleAdmits(rule, call.host))
-            return { behavior: "allow", rules: [rule] };
+    for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
+        const reading = behavior === "allow" ? call.hosts.grant : call.hosts.tighten;
+        if (reading === undefined)
+            continue;
+        const speaks = (rule) => (rule.match === "host" || rule.match === "subdomain") && eligiblePersisted(rule, call, behavior);
+        if ("unreadable" in reading) {
+            if (behavior === "allow")
+                continue;
+            const row = rules.find(speaks);
+            if (row === undefined)
+                continue;
+            return behavior === "deny" ? { behavior: "deny", rules: [row] } : { behavior: "ask", rules: [row], unreadable: `the host the call reaches cannot be read (${HOST_UNREADABLE_SENTENCE[reading.unreadable]})` };
+        }
+        const row = rules.find((rule) => speaks(rule) && domainRuleAdmits(rule, reading.host));
+        if (row !== undefined)
+            return { behavior, rules: [row] };
     }
     return undefined;
 }
+export function suggestRuleForHost(tool, host) {
+    if (ruleToolGrammarOf(tool) !== "domain")
+        return undefined;
+    const parsed = parseRuleText(formatRuleText(host, "host", tool), "allow");
+    if (!("rule" in parsed) || parsed.rule.match !== "host" || parsed.rule.command !== host)
+        return undefined;
+    return { kind: "single", rule: parsed.rule.rule, match: "host", command: host };
+}
 export function suggestRuleForName(tool, name) {
     if (ruleToolGrammarOf(tool) !== "name")
         return undefined;
@@ -1163,6 +1476,7 @@ export function segmentCoverageOf(command, rules, call) {
     });
 }
 export const RULE_OFFER_BATCH_MEMBER_KINDS = Object.freeze(["command", "directoryRead"]);
+export const RULE_OFFER_KINDS = Object.freeze(["single", "batch"]);
 export const UNCOVERED_SEGMENT_REASONS = Object.freeze(["redirection", "no_rule_form", "cap_overflow"]);
 export const UNCOVERED_SEGMENT_REASON_BASELINE = {
     redirection: "This part carries a redirection, so it is approved per use — no rule can cover this spelling. If you trust its redirection-free form, a rule can be written for that form (the card's edit row, or settings).",