@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/permission-rules.js

@@ -1,11 +1,12 @@
 import { attest } from "./tool-policy.js";
-import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
+import { MCP_NAMESPACE } from "./protocol-table.js";
 import { catalogRuleFaceOf, isShellFaceToolName, pathTargetOf } from "./tool-registry.js";
+import { HOST_UNREADABLE_SENTENCE, callHostTargetOf } from "./host-target.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
-import { COMMAND_RULE_TOOL, NAME_RULE_FACES, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, keyedValueAbsentReason, laneToolNamesOf, nameGrammarReads, nameRuleAdmits, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleBasesNeeded } from "./permission-rule-model.js";
+import { callPathFaceOf, canonicalNameValue, COMMAND_RULE_TOOL, domainRuleAdmits, isUsablePathBase, laneToolNamesOf, mountedOnlyArgumentOf, mountedValueArmOf, NAME_RULE_FACES, nameRuleReach, nameRuleSubjectOf, nameValueAbsentReason, nameValuesUnreadReason, parseRuleText, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, programRunReachOf, ruleBasesNeeded, ruleLaneOf, ruleShapeOf, shellRuleParamOf, ruleContentOf } from "./permission-rule-model.js";
 import { pathFamilyOf } from "../tools/fs/safety.js";
-import { argsAsTheToolReads, callTargetReadingOf, callTargetViewsOf } from "./effective-path-target.js";
-import { canonicalize, UNCANONICALIZABLE } from "./canonical-json.js";
+import { callTargetReadingOf, callTargetViewsOf } from "./effective-path-target.js";
+import { DEFAULT_MAX_SCALAR_VALUE_CHARS, paramRuleReaches } from "./param-rule-reach.js";
 import { bindPathRules, judgeRuleRows, policyAnchors, rowsWhereTheyLead } from "./path-rule-binding.js";
 import { ruleDenialSentence } from "./rule-denial-sentence.js";
 import { heldValues } from "./tool-name-readings.js";
@@ -25,20 +26,27 @@ function describeBehavior(v) {
         default: return v === null ? "null" : "an object";
     }
 }
+export function ruleIssue(rule, code, message, libraryOption) {
+    return { rule, code, message, ...(libraryOption !== undefined ? { libraryOption } : {}) };
+}
 export const DEFAULT_CAPS = {
     maxRules: 256,
     maxRuleLength: 512,
     maxPatternLength: 256,
     maxStars: 16,
-    maxScalarValueChars: 16_384,
+    maxScalarValueChars: DEFAULT_MAX_SCALAR_VALUE_CHARS,
+};
+import { isCoveringRuleName, ruleNameCovers, wildcardMatch } from "./namespaced-rule-name.js";
+export { isCoveringRuleName, ruleNameCovers, wildcardMatch };
+const vocabularyOf = (face) => face.params ?? face.primaryParams;
+const carriedPhrase = (face) => {
+    const vocabulary = vocabularyOf(face);
+    if (vocabulary.length > 0)
+        return `it carries ${[...vocabulary].sort().join(", ")}`;
+    return face.params !== undefined ? "it declares no rule-readable parameters" : "its parameters are not declared statically: each mount's schema is its own";
 };
-import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, wildcardMatch } from "./namespaced-rule-name.js";
-export { isNamespacedCoveringRuleName, namespacedRuleNameCovers, wildcardMatch };
 export function catalogRuleFaceView(toolName) {
-    const face = catalogRuleFaceOf(toolName);
-    if (face === undefined)
-        return undefined;
-    return { ...face, pathTargeting: pathTargetOf(toolName) !== undefined };
+    return catalogRuleFaceOf(toolName);
 }
 export const fileToolParamVocabulary = (canonicalTool) => {
     const face = catalogRuleFaceOf(canonicalTool);
@@ -83,25 +91,25 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
     const command = { deny: [], ask: [] };
     const namespacedCovering = { deny: [], ask: [] };
     const issues = [];
-    const bad = (rule, code, message) => {
-        issues.push({ rule, code, message });
+    const bad = (rule, code, message, libraryOption) => {
+        issues.push(ruleIssue(rule, code, message, libraryOption));
     };
     if (rules.length > caps.maxRules) {
-        return { byTool, command, namespacedCovering, issues: [{ rule: "", code: "invalid.cap_exceeded", message: `${rules.length} rules > maxRules ${caps.maxRules}` }] };
+        return { byTool, command, namespacedCovering, issues: [ruleIssue("", "invalid.cap_exceeded", `${rules.length} rules — a rule set holds at most ${caps.maxRules}`, { name: "caps.maxRules" })] };
     }
     for (const r of rules) {
         const text = r.rule;
         const behavior = r.behavior;
         if (behavior !== "deny" && behavior !== "ask") {
             if (behavior === "allow")
-                bad(text, "unsupported.allow", "an allow rule does not belong to a policy — allow entries live on the allow layer: put the entry in `TaskSpec.allowedTools` (a request's) or `RunnerDeps.allowedTools` (the deployment's); deny / ask rules stay here");
+                bad(text, "unsupported.allow", "an allow rule does not belong to a policy — allow entries live on the allow layer (the request's allow list, or the deployment's); deny / ask rules stay here", { name: "TaskSpec.allowedTools" });
             else
                 bad(text, "invalid.behavior", `a rule's behavior is one of "deny" | "ask" — got ${describeBehavior(behavior)}; a misspelled verb would compile to a rule that silently never fires`);
             continue;
         }
         const verb = behavior;
         if (text.length > caps.maxRuleLength) {
-            bad(text, "invalid.cap_exceeded", `rule longer than ${caps.maxRuleLength} chars`);
+            bad(text, "invalid.cap_exceeded", `rule longer than ${caps.maxRuleLength} chars`, { name: "caps.maxRuleLength" });
             continue;
         }
         const parsed = ruleSpellingOf(text);
@@ -110,24 +118,21 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
             bad(text, why.code, why.message);
             continue;
         }
-        if (parsed.toolName === "*") {
-            bad(text, "invalid.tool_name", `\`*\` names no tool — a rule reaches the tool it names, so this one would compile and never match; name the tool, or state the answer for every call no rule reaches with \`defaultAction\``);
-            continue;
-        }
         const toolName = parsed.toolName;
         const parenthesised = parsed.ruleContent !== undefined || indexOfUnescaped(text, "(") !== -1;
         if (toolName.startsWith(MCP_NAMESPACE.prefix) && parenthesised) {
-            bad(text, "unsupported.mcp_paren", "MCP rules do not support patterns in parentheses (CC parity); use the toolAxes system");
+            bad(text, "unsupported.mcp_paren", "MCP rules do not support patterns in parentheses (CC parity); a rule names a whole tool (`mcp__<server>__<tool>`) or a whole server (`mcp__<server>`), and what a tool does is declared per tool in the MCP server's spec", { name: "toolAxes" });
             continue;
         }
-        if (parenthesised && isNamespacedCoveringRuleName(toolName)) {
+        if (ruleContentOf(parsed) !== undefined && isCoveringRuleName(toolName, verb)) {
             bad(text, "unsupported.covering_paren", `"${toolName}" reaches a SET of tools, and the generic param DSL is keyed by exact tool name — a parenthesised rule on it can never match. ` +
                 `Write the parenthesised rule against one exact tool name, or drop the parentheses to keep the covering rule.`);
             continue;
         }
         const entry = byTool.get(toolName) ?? { bare: {}, param: { deny: [], ask: [] }, content: { deny: [], ask: [] } };
-        if (parsed.ruleContent === undefined) {
-            if (isNamespacedCoveringRuleName(toolName)) {
+        const content = ruleContentOf(parsed);
+        if (content === undefined) {
+            if (isCoveringRuleName(toolName, verb)) {
                 namespacedCovering[verb].push({ ruleName: toolName, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
                 continue;
             }
@@ -135,52 +140,70 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
             byTool.set(toolName, entry);
             continue;
         }
-        const content = parsed.ruleContent;
         const colon = content.indexOf(":");
-        if (isShellFaceToolName(toolName)) {
-            const paramPart = colon > 0 ? content.slice(0, colon).trim() : "";
-            const declaresParam = (tool) => colon > 0 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(paramPart) && (catalogRuleFaceOf(tool)?.params ?? []).includes(paramPart);
-            const looksLikeParamRule = declaresParam(toolName);
-            if (toolName !== COMMAND_RULE_TOOL && !looksLikeParamRule) {
-                const commandWordParam = declaresParam(COMMAND_RULE_TOOL) && !content.endsWith(":*");
-                bad(text, "invalid.command_rule", commandWordParam
-                    ? `"${text}" is a parameter rule on "${paramPart}", which ${toolName} does not declare (its rule parameters: ${(catalogRuleFaceOf(toolName)?.params ?? []).join(", ")}); a parameter rule reaches only the tool that declares the parameter, so ${COMMAND_RULE_TOOL}(${content}) is a rule on ${COMMAND_RULE_TOOL}'s own argument and does not reach ${toolName}. A shell command rule is written ${COMMAND_RULE_TOOL}(<command>) — it reaches ${toolName} and every other tool that runs a shell command by the command it runs.`
+        let face;
+        if (!isShellFaceToolName(toolName)) {
+            const resolved = faceOf(toolName);
+            if (resolved.judged && resolved.face === undefined) {
+                bad(text, "unsupported.tool_unknown", `"${toolName}" is not a tool on this leg's roster — the rule would compile and never match`);
+                continue;
+            }
+            face = resolved.face;
+        }
+        const lane = ruleLaneOf(toolName, content);
+        if (lane === "command") {
+            if (toolName !== COMMAND_RULE_TOOL) {
+                const commandWordParam = shellRuleParamOf(COMMAND_RULE_TOOL, content);
+                bad(text, "invalid.command_rule", commandWordParam !== undefined && !content.endsWith(":*")
+                    ? `"${text}" is a parameter rule on "${commandWordParam}", which ${toolName} does not declare (its rule parameters: ${(catalogRuleFaceOf(toolName)?.params ?? []).join(", ")}); a parameter rule reaches only the tool that declares the parameter, so ${COMMAND_RULE_TOOL}(${content}) is a rule on ${COMMAND_RULE_TOOL}'s own argument and does not reach ${toolName}. A shell command rule is written ${COMMAND_RULE_TOOL}(<command>) — it reaches ${toolName} and every other tool that runs a shell command by the command it runs.`
                     : `a shell command rule is written ${COMMAND_RULE_TOOL}(…) — it reaches ${toolName} and every other tool that runs a shell command by the command it runs; "${text}" names no rule upstream reads. Write ${COMMAND_RULE_TOOL}(${content}).`);
                 continue;
             }
-            if (toolName === COMMAND_RULE_TOOL && (!looksLikeParamRule || content.endsWith(":*"))) {
-                const parsedCommand = parseRuleText(text, verb);
-                if ("reject" in parsedCommand) {
-                    bad(text, "invalid.command_rule", `${parsedCommand.reject.code}: ${parsedCommand.reject.message}`);
-                    continue;
-                }
-                command[verb].push({ parsed: parsedCommand.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
+            const parsedCommand = parseRuleText(text, verb);
+            if ("reject" in parsedCommand) {
+                bad(text, "invalid.command_rule", `${parsedCommand.reject.code}: ${parsedCommand.reject.message}`);
                 continue;
             }
+            command[verb].push({ parsed: parsedCommand.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
+            continue;
         }
         else {
-            const resolved = faceOf(toolName);
-            if (resolved.judged && resolved.face === undefined) {
-                bad(text, "unsupported.tool_unknown", `"${toolName}" is not a tool on this leg's roster — the rule would compile and never match`);
-                continue;
-            }
-            const face = resolved.face;
-            if (nameGrammarReads(toolName, content)) {
+            if (lane === "name") {
                 const parsedName = parseRuleText(text, verb);
                 if ("reject" in parsedName) {
                     bad(text, "invalid.command_rule", `${parsedName.reject.code}: ${parsedName.reject.message}`);
                     continue;
                 }
                 const param = NAME_RULE_FACES[toolName].param;
-                if (face?.params !== undefined && !face.params.includes(param)) {
-                    bad(text, "unsupported.param_unknown", `"${param}" is not a parameter of ${toolName} on this leg (it carries ${[...face.params].sort().join(", ")}) — a ${toolName} rule is read against it, so the rule would compile and never match`);
+                if (face !== undefined && !vocabularyOf(face).includes(param)) {
+                    bad(text, "unsupported.param_unknown", `"${param}" is not a parameter of ${toolName} on this leg (${carriedPhrase(face)}) — a ${toolName} rule is read against it, so the rule would compile and never match`);
+                    continue;
+                }
+                const mountedOnly = mountedOnlyArgumentOf(toolName, content, face?.params);
+                if (mountedOnly !== undefined) {
+                    bad(text, "unsupported.param_unknown", `"${mountedOnly}" is an argument declared only by the ${toolName} tool this leg mounts, which is not rule-readable (#2248) — "${text}" would read as the ${param} "${content}" and never reach a call setting ${mountedOnly}; write the rule on the whole tool (\`${toolName}\`), or on the ${param} it means`);
+                    continue;
+                }
+                const resolved = face?.nameValues !== undefined ? canonicalNameValue(parsedName.rule.command, face.nameValues) : undefined;
+                if (resolved?.kind === "ambiguous") {
+                    bad(text, "invalid.name_ambiguous", `"${parsedName.rule.command}" names ${resolved.entries.length} of the ${param} values this leg's ${toolName} offers (${resolved.entries.join(", ")}) — they differ only by case, spacing or punctuation, so which one the rule means is not determinable; write the exact one`);
                     continue;
                 }
                 entry.content[verb].push({ parsed: parsedName.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
                 byTool.set(toolName, entry);
                 continue;
             }
-            if (face !== undefined && face.pathTargeting === true && colon <= 0) {
+            if (lane === "domain") {
+                const parsedHost = parseRuleText(text, verb);
+                if ("reject" in parsedHost) {
+                    bad(text, "invalid.command_rule", `${parsedHost.reject.code}: ${parsedHost.reject.message}`);
+                    continue;
+                }
+                entry.content[verb].push({ parsed: parsedHost.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
+                byTool.set(toolName, entry);
+                continue;
+            }
+            if (lane === "path") {
                 const parsedPath = parseRuleText(text, verb);
                 if ("reject" in parsedPath) {
                     bad(text, "invalid.command_rule", `${parsedPath.reject.code}: ${parsedPath.reject.message}`);
@@ -189,7 +212,7 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
                 for (const base of ruleBasesNeeded(parsedPath.rule)) {
                     const declared = base === "cwd" ? (pathBases.cwd ?? pathBases.root) : pathBases[base];
                     if (declared !== undefined && !isUsablePathBase(declared, pathFamilyOf(pathBases))) {
-                        bad(text, "unsupported.path_base", `"${text}" is relative to ${PATH_RULE_BASE_LABEL[base]}, and the \`pathBases.${base === "cwd" && pathBases.cwd === undefined ? "root" : base}\` this policy declares is not an absolute path of its tree's family — the rule could not be judged on any call`);
+                        bad(text, "unsupported.path_base", `"${text}" is relative to ${PATH_RULE_BASE_LABEL[base]}, and the one this policy declares for it is not an absolute path of its tree's family — the rule could not be judged on any call`, { name: `pathBases.${base === "cwd" && pathBases.cwd === undefined ? "root" : base}` });
                     }
                 }
                 if (issues.length > 0 && issues[issues.length - 1].rule === text && issues[issues.length - 1].code === "unsupported.path_base")
@@ -199,15 +222,21 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
                 byTool.set(toolName, entry);
                 continue;
             }
-            if (face?.params !== undefined && colon > 0) {
+            if (face !== undefined && colon > 0) {
                 const paramPart = content.slice(0, colon).trim();
-                if (!face.params.includes(paramPart)) {
+                const vocabulary = vocabularyOf(face);
+                if (!vocabulary.includes(paramPart)) {
                     if (face.nonScalar?.includes(paramPart)) {
                         bad(text, "unsupported.param_non_scalar", `"${paramPart}" is a parameter of ${toolName} but its value is an object or an array — the generic matcher compares scalars only; the rule would compile and never match`);
                     }
                     else {
-                        bad(text, "unsupported.param_unknown", `"${paramPart}" is not a parameter of ${toolName} (it carries ${[...face.params].sort().join(", ")}) — the rule would compile and never match. ` +
-                            `For a path glob use the tool-specific lane (\`${toolName}(src/**)\` is not the generic param DSL); a Windows path such as \`${toolName}(C:/foo)\` parses as the param "C".`);
+                        const statesNothing = face.params === undefined && vocabulary.length === 0;
+                        bad(text, "unsupported.param_unknown", statesNothing
+                            ? `"${paramPart}" cannot be judged on ${toolName} here (${carriedPhrase(face)}) — write the rule on the whole tool (\`${toolName}\`).`
+                            : `"${paramPart}" is not a scalar parameter of ${toolName} (${carriedPhrase(face)}${vocabulary.length > 0 ? "; arrays and objects are not rule-readable" : ""}) — the rule would compile and never match. ` +
+                                (pathTargetOf(toolName) !== undefined
+                                    ? `For a path glob use the tool-specific lane (\`${toolName}(src/**)\` is not the generic param DSL); a Windows path such as \`${toolName}(C:/foo)\` parses as the param "C".`
+                                    : `${vocabulary.length > 0 ? "Name one of its parameters, or write" : "Write"} the rule on the whole tool (\`${toolName}\`).`), statesNothing ? { name: "ruleFaces" } : undefined);
                     }
                     continue;
                 }
@@ -224,14 +253,19 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
             continue;
         }
         if (pattern.length > caps.maxPatternLength || countStars(pattern) > caps.maxStars) {
-            bad(text, "invalid.cap_exceeded", `pattern exceeds maxPatternLength ${caps.maxPatternLength} or maxStars ${caps.maxStars}`);
+            bad(text, "invalid.cap_exceeded", `a pattern holds at most ${caps.maxPatternLength} characters and ${caps.maxStars} stars`, { name: pattern.length > caps.maxPatternLength ? "caps.maxPatternLength" : "caps.maxStars" });
             continue;
         }
         if (faceOf(toolName).face?.primaryParams.includes(param) === true && primaryFieldGeneric === "reject") {
-            bad(text, "invalid.primary_field", `"${param}" is ${toolName}'s primary field — the generic matcher is a trim+FULL-STRING lexical match (no shell/path semantics); '${toolName}(${param}:git push*)' would NOT match 'cd /x && git push'. Opt in with primaryFieldGeneric:"allow-lexical" if you understand this.`);
+            const form = ruleShapeOf({ toolName, args: {} }, verb);
+            bad(text, "invalid.primary_field", `"${param}" is ${toolName}'s primary field, and a rule on it matches the WHOLE value lexically — no shell or path semantics — so \`${toolName}(${param}:git push*)\` would NOT match \`cd /x && git push\`. ` +
+                `Write the rule ${form === undefined ? "" : `as \`${form}\`, or `}on the whole tool (\`${toolName}\`).`, { name: "primaryFieldGeneric", value: "allow-lexical" });
             continue;
         }
         entry.param[verb].push({ param, pattern, behavior: verb, ruleText: text, source: r.source });
+        const valueArm = mountedValueArmOf(text, toolName, verb);
+        if (valueArm !== undefined)
+            entry.content[verb].push({ parsed: valueArm, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
         byTool.set(toolName, entry);
     }
     return { byTool, command, namespacedCovering, issues };
@@ -244,42 +278,10 @@ function isPlainObjectArgs(args) {
     return typeof args === "object" && args !== null && !Array.isArray(args);
 }
 function matchParamRules(rules, req, maxScalarValueChars) {
-    const args = req.args;
-    if (!isPlainObjectArgs(args))
-        return undefined;
-    for (const r of rules) {
-        if (!Object.hasOwn(args, r.param)) {
-            if (readingAbsorbs(req, r.param, r.pattern))
-                return r;
-            continue;
-        }
-        const raw = args[r.param];
-        if (raw === undefined || raw === null)
-            continue;
-        const t = typeof raw;
-        if (t === "object" || t === "function" || t === "symbol")
-            continue;
-        const value = String(raw).trim();
-        if (value.length > maxScalarValueChars)
-            return r;
-        if (wildcardMatch(r.pattern, value))
-            return r;
-    }
-    return undefined;
-}
-function readingAbsorbs(req, param, pattern) {
-    if (pattern.includes("*"))
-        return false;
-    try {
-        const read = canonicalize(argsAsTheToolReads(req, { ...req.args, [param]: pattern }));
-        return read !== UNCANONICALIZABLE && read === canonicalize(req.args);
-    }
-    catch {
-        return false;
-    }
+    return rules.find((r) => paramRuleReaches(req, r.param, r.pattern, maxScalarValueChars));
 }
-function ruleDenial(req, ruleText, source) {
-    return ruleDenialSentence({ source: "permission", tool: req.toolName, rule: ruleText, ...(source ? { origin: source } : {}) });
+function ruleDenial(req, ruleText, source, detail) {
+    return ruleDenialSentence({ source: "permission", tool: req.toolName, rule: ruleText, ...(source ? { origin: source } : {}), ...(detail !== undefined ? { detail } : {}) });
 }
 function ruleAskMessage(ruleText, source) {
     return `flagged by permission rule "${ruleText}"${source ? ` (${source})` : ""}`;
@@ -327,7 +329,8 @@ export function createPermissionRulePolicy(rules, opts) {
         for (const r of namespacedCovering[behavior])
             nameSets[behavior].push(r.ruleName);
     }
-    const coveringHit = (lane, toolName) => lane.length === 0 ? undefined : lane.find((r) => namespacedRuleNameCovers(r.ruleName, toolName));
+    const heldFor = (table, req) => heldValues("policy.permissionRules", table, req);
+    const coveringHit = (lane, req) => lane.length === 0 ? undefined : heldFor({ get: (name) => lane.find((r) => ruleNameCovers(r.ruleName, name)) }, req)[0];
     const hasCovering = namespacedCovering.deny.length > 0 || namespacedCovering.ask.length > 0;
     const faceRules = {
         deny: [...byTool.values()].flatMap((e) => e.content.deny.filter((r) => r.faces !== undefined)),
@@ -386,11 +389,33 @@ export function createPermissionRulePolicy(rules, opts) {
     const judgeOthers = (lane, req) => {
         const command = isPlainObjectArgs(req.args) ? req.args[commandParam] : undefined;
         let unreadable;
+        let host = null;
         for (const r of lane) {
             if (r.parsed.match === "name" || r.parsed.match === "name_prefix") {
                 const named = nameRuleSubjectOf(r.parsed.tool, req.args);
-                if (named !== undefined && nameRuleAdmits(r.parsed, named))
+                if (named === undefined)
+                    continue;
+                const reach = nameRuleReach(r.parsed, named, req.face?.nameValues);
+                if (reach === "reached")
                     return { rule: r };
+                if (reach === "unread")
+                    unreadable ??= { rule: r, unreadable: nameValuesUnreadReason(r.parsed.tool) };
+                continue;
+            }
+            if (r.parsed.match === "host" || r.parsed.match === "subdomain") {
+                if (host === null)
+                    host = callHostTargetOf(req, "tighten");
+                if (host === undefined)
+                    continue;
+                if ("host" in host) {
+                    if (domainRuleAdmits(r.parsed, host.host))
+                        return { rule: r };
+                    continue;
+                }
+                const why = `the host the call reaches cannot be read (${HOST_UNREADABLE_SENTENCE[host.unreadable]})`;
+                if (r.parsed.behavior === "deny")
+                    return { rule: r, detail: why };
+                unreadable ??= { rule: r, unreadable: why };
                 continue;
             }
             if (typeof command !== "string")
@@ -407,7 +432,7 @@ export function createPermissionRulePolicy(rules, opts) {
         for (const r of [...entry.content.deny, ...entry.content.ask]) {
             if (r.parsed.match !== "name" || nameRuleSubjectOf(r.parsed.tool, req.args) !== undefined)
                 continue;
-            const absent = keyedValueAbsentReason(r.parsed.tool);
+            const absent = nameValueAbsentReason(r.parsed.tool);
             if (absent !== undefined)
                 return ruleDenialSentence({ source: "permission", tool: req.toolName, rule: r.ruleText, ...(r.source ? { origin: r.source } : {}), detail: absent });
         }
@@ -420,7 +445,7 @@ export function createPermissionRulePolicy(rules, opts) {
         requiresRealApproval: true,
     });
     const entryFor = (req) => {
-        const entries = heldValues("policy.permissionRules", byTool, req);
+        const entries = heldFor(byTool, req);
         if (entries.length <= 1)
             return entries[0];
         const bare = {};
@@ -440,12 +465,12 @@ export function createPermissionRulePolicy(rules, opts) {
         ...(pathSpecs.length > 0 ? { pathRules: (anchors) => boundAt(policyAnchors(pathBases, anchors)).rows } : {}),
         check(req) {
             const entry = entryFor(req);
-            const covering = hasCovering && protocolOf(req.toolName) !== undefined;
+            const covering = hasCovering;
             if (entry?.bare.deny) {
                 return { action: "deny", message: ruleDenial(req, entry.bare.deny.ruleText, entry.bare.deny.source) };
             }
             if (covering) {
-                const coveringDeny = coveringHit(namespacedCovering.deny, req.toolName);
+                const coveringDeny = coveringHit(namespacedCovering.deny, req);
                 if (coveringDeny)
                     return { action: "deny", message: ruleDenial(req, coveringDeny.ruleText, coveringDeny.source) };
             }
@@ -454,7 +479,7 @@ export function createPermissionRulePolicy(rules, opts) {
             const denyLane = contentLaneOf("deny", entry, shellCall, callFace);
             const contentDeny = denyLane.length > 0 ? contentHit(denyLane, req) : undefined;
             if (contentDeny !== undefined && contentDeny.unreadable === undefined) {
-                const denied = { action: "deny", message: ruleDenial(req, contentDeny.rule.ruleText, contentDeny.rule.source) };
+                const denied = { action: "deny", message: ruleDenial(req, contentDeny.rule.ruleText, contentDeny.rule.source, contentDeny.detail) };
                 const face = contentDeny.view !== undefined ? callPathFaceOf(req) : undefined;
                 return face !== undefined ? attest(denied, req, { pathDenial: { rule: contentDeny.rule.ruleText, view: contentDeny.view, face } }) : denied;
             }
@@ -475,7 +500,7 @@ export function createPermissionRulePolicy(rules, opts) {
                 }
             }
             if (covering) {
-                const coveringAsk = coveringHit(namespacedCovering.ask, req.toolName);
+                const coveringAsk = coveringHit(namespacedCovering.ask, req);
                 if (coveringAsk)
                     return { action: "ask", message: ruleAskMessage(coveringAsk.ruleText, coveringAsk.source), matchedAskRule: coveringAsk.ruleText };
             }

package/dist/core/persisted-rule-arms.d.ts

@@ -44,7 +44,7 @@ export declare function disclosedRuleSet(rules: readonly PersistedRuleHitRule[])
  *    lane's allow carries: one authority, one word) and the rule text disclosed through the display
  *    transform; the STATION attributes the refusal (`tightened: "deny"` ⇒ it writes the pass's refusing
  *    layer — the attribution is a station's word and lives in the station file). A path row's hit reports where
- *    it met the call; with `call` given and the face the call's own, the deny carries that as its attested `pathDenial`, so every exit that
+ *    it met the call; with the face the call's own (`call`, the request the lane read), the deny carries that as its attested `pathDenial`, so every exit that
  *    reads the deny (the gate's exit, the approved-edit re-check, a resumed leg's belt) mints the same card from the same fact.
  *  · ASK — on an allow, a fresh ask is minted carrying `matchedAskRule` (the marker an explicit `ask`
  *    permission rule stamps, so the ask's origin derives as `ask_rule`: the classifier never answers
@@ -61,13 +61,15 @@ export declare function disclosedRuleSet(rules: readonly PersistedRuleHitRule[])
  *  · UNREADABLE STORE — a partition of the store (or all of it) could not be READ (`unreadable` without a `reason`): a deny
  *    or ask row inside it may forbid this call and nobody can tell, so it fails CLOSED the same way, to the question
  *    only a person answers — an allow becomes an ask carrying `requiresRealApproval`, an ask acquires the bit, a deny stays
- *    a deny. Every call the lane judges is in this state until a read succeeds again (the lane announces the skipped store,
- *    once per run, and reads again on the next call). The two forms differ in WHICH fact the gate records (one class for
+ *    a deny. Every call is in this state until a read succeeds again, whatever its tool — rules nobody could read are rules
+ *    whose tools nobody knows (a newer engine's grammar names rules for tools this one names none for), so the lane hands
+ *    this form for a call no rule grammar here speaks for too; it announces the skipped store once per run and reads again
+ *    on the next call. The two forms differ in WHICH fact the gate records (one class for
  *    both, `rule_unreadable`, bypass-immune) and in the
  *    resumed-call belt, which vetoes only the call form: a person already answered that call's question.
  * An allow hit (or no hit) returns the decision untouched: the allow arm is the station's.
  */
-export declare function applyPersistedTightening(decision: PermissionResult, read: PersistedRuleRead | undefined, call?: ToolCallRequest): {
+export declare function applyPersistedTightening(decision: PermissionResult, read: PersistedRuleRead | undefined, call: ToolCallRequest): {
     decision: PermissionResult;
     tightened?: "deny" | "ask" | "unreadable" | "store_unreadable";
 };

package/dist/core/persisted-rule-arms.js

@@ -1,6 +1,6 @@
-import { attest } from "./tool-policy.js";
+import { attest, attestationOf } from "./tool-policy.js";
 import { callPathFaceOf } from "./permission-rule-model.js";
-import { decisionAskClassesOf } from "./ask-origin.js";
+import { ownAskClassesOf } from "./ask-origin.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 export function strongestAnswer(answers) {
     const rank = (a) => (a === undefined ? 0 : "unreadable" in a ? 4 : "behavior" in a ? { deny: 5, ask: 3, allow: 2 }[a.behavior] : 1);
@@ -20,15 +20,13 @@ export function applyPersistedTightening(decision, read, call) {
             ? `this call could not be read against the person's standing deny/ask rules (${read.reason}) — whether one of them forbids it is unknown, so it needs a real approval`
             : "the person's standing permission rules could not be read — whether one of them forbids this call is unknown, so it needs a real approval";
         const unreadableCall = callForm ? { ruleUnreadable: "persisted_call" } : {};
-        const standingFence = decision.action === "ask" && decisionAskClassesOf({ ...decision, foldedAskClasses: undefined }).has("policy_rra")
-            ? { foldedAskClasses: [...(decision.foldedAskClasses ?? []), "policy_rra"] }
-            : {};
-        return {
-            decision: decision.action === "allow"
-                ? { action: "ask", message, decisionReason: "persisted_rule", requiresRealApproval: true, ...unreadableCall, ...(decision.updatedInput !== undefined ? { updatedInput: decision.updatedInput } : {}) }
-                : { ...decision, requiresRealApproval: true, ...unreadableCall, ...standingFence, message: `${decision.message !== undefined ? `${decision.message} ` : ""}(${message})` },
-            tightened: callForm ? "unreadable" : "store_unreadable",
-        };
+        const tightened = callForm ? "unreadable" : "store_unreadable";
+        if (decision.action === "allow") {
+            return { decision: { action: "ask", message, decisionReason: "persisted_rule", requiresRealApproval: true, ...unreadableCall, ...(decision.updatedInput !== undefined ? { updatedInput: decision.updatedInput } : {}) }, tightened };
+        }
+        const record = attestationOf(decision, call);
+        const asked = { ...decision, requiresRealApproval: true, ...unreadableCall, message: `${decision.message !== undefined ? `${decision.message} ` : ""}(${message})` };
+        return { decision: ownAskClassesOf(decision, record).has("policy_rra") ? attest(asked, call, { foldedClasses: [...new Set([...(record?.foldedClasses ?? []), "policy_rra"])] }) : asked, tightened };
     }
     const hit = read?.hit;
     if (hit === undefined || hit.behavior === "allow")
@@ -36,7 +34,7 @@ export function applyPersistedTightening(decision, read, call) {
     const shown = disclosedRuleSet(hit.rules);
     if (hit.behavior === "deny") {
         const denied = { action: "deny", message: `a persisted deny rule (${shown}) refuses this call`, decisionReason: "persisted_rule" };
-        const attested = hit.denial !== undefined && call !== undefined && hit.denial.face === callPathFaceOf(call);
+        const attested = hit.denial !== undefined && hit.denial.face === callPathFaceOf(call);
         return { decision: attested ? attest(denied, call, { pathDenial: hit.denial }) : denied, tightened: "deny" };
     }
     if (decision.action === "deny")

package/dist/core/present-plan-tool.js

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { delimitUntrusted } from "./untrusted-text.js";
-import { toolFace } from "./tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
 export const PRESENT_PLAN_TOOL_NAME = "ExitPlanMode";
 export const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
 const ENTER_PLAN_MODE_DESCRIPTION = `Enter PLAN MODE (read-only): stop making changes and switch to exploration/planning. For the rest of this run, every write/edit/mutating tool call ASKS the user first ("Cannot write to <path> while in plan mode."; where nobody can answer, it is refused) while read-only tools (Read, Grep, Glob, etc.) still work. When your plan is ready, call ${PRESENT_PLAN_TOOL_NAME} with it — the run PAUSES for a human to approve it, then continues (read-only lifted) so you can execute.
@@ -33,6 +33,7 @@ export function createEnterPlanModeTool(enterPlanMode) {
     return {
         name: ENTER_PLAN_MODE_TOOL_NAME,
         ...toolFace("enter-plan-mode"),
+        ruleFace: mountRuleFace("enter-plan-mode"),
         description: ENTER_PLAN_MODE_DESCRIPTION,
         parameters: Type.Object({}),
         executionMode: "sequential",
@@ -62,6 +63,7 @@ export function createPresentPlanTool(requestReview) {
     return {
         name: PRESENT_PLAN_TOOL_NAME,
         ...toolFace("exit-plan-mode"),
+        ruleFace: mountRuleFace("exit-plan-mode"),
         description: PRESENT_PLAN_DESCRIPTION,
         parameters: Type.Object({
             plan: Type.String({

package/dist/core/principal-name.d.ts

@@ -0,0 +1,20 @@
+export declare function principalNameOf(raw: unknown): string | undefined;
+/** What a value offered as THE principal of a task or of a lookup is — read once, here, so no face decides it on its own. */
+export type PrincipalReading = {
+    readonly kind: "name";
+    readonly name: string;
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "invalid";
+    readonly fault: string;
+};
+/**
+ * A principal offered to a face that tolerates having none: `name` (a principal name), `absent` (no principal — `undefined`, and the
+ * empty string, which the task door and the bucket resolvers have always spelled the same), or `invalid` (it was PROVIDED and is not a name). Only absence reaches
+ * the unauthenticated floor, or the declared local owner's bucket; an invalid value is a bad value, refused where a principal is taken
+ * (never read as absence — a caller who appends one invisible character to a principal must not become the machine owner).
+ */
+export declare function readPrincipal(raw: unknown): PrincipalReading;
+/** Why a value is not a principal name, as a clause for a refusal sentence: the kind of string it is, or the type of the value. */
+export declare function principalNameFault(raw: unknown): string;

package/dist/core/principal-name.js

@@ -0,0 +1,22 @@
+const NOT_IN_A_NAME = /[\p{Cc}\p{Zl}\p{Zp}]|(?![\u200c\u200d])\p{Cf}/u;
+const NOT_VISIBLE = /[\s\p{Cf}]+/gu;
+export function principalNameOf(raw) {
+    return typeof raw === "string" && raw.replace(NOT_VISIBLE, "") !== "" && !NOT_IN_A_NAME.test(raw) ? raw : undefined;
+}
+export function readPrincipal(raw) {
+    if (raw === undefined || raw === "")
+        return { kind: "absent" };
+    const name = principalNameOf(raw);
+    return name !== undefined ? { kind: "name", name } : { kind: "invalid", fault: principalNameFault(raw) };
+}
+export function principalNameFault(raw) {
+    if (typeof raw !== "string")
+        return raw === null ? "null" : typeof raw;
+    if (raw === "")
+        return "an empty string";
+    if (raw.trim() === "")
+        return "a blank string";
+    if (raw.replace(NOT_VISIBLE, "") === "")
+        return "a string with no visible character";
+    return "a string holding a control, separator or format character";
+}

package/dist/core/prompt-section-seat.js

@@ -1,16 +1,14 @@
 import { bandOf } from "../prompt-assembly/bands.js";
-import { lockedTextIn, receivePromptData } from "../prompt-assembly/overlay.js";
+import { lockedTextIn } from "../prompt-assembly/overlay.js";
+import { isPlainRecord } from "./mods/kernel/receive.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { egressThrownText, extensionWords } from "./untrusted-egress.js";
 export const DISPOSABLE_PROMPT_SECTIONS = Object.freeze(["core/discovery.mcp-instructions"]);
 const DEFECT_MAX = 600;
 function readAnswer(answer, seat) {
-    if (typeof answer !== "object" || answer === null || Array.isArray(answer))
+    if (!isPlainRecord(answer))
         return `answered ${answer === null ? "null" : Array.isArray(answer) ? "an array" : typeof answer}; prompt.section takes { text: string | null }`;
-    const received = receivePromptData(answer);
-    if ("notData" in received)
-        return `a prompt.section answer is data (plain objects, arrays, strings, booleans); it holds ${received.notData}`;
-    const data = received.value;
+    const data = answer;
     const keys = Object.keys(data);
     const stray = keys.filter((k) => k !== "text");
     if (stray.length > 0)

package/dist/core/protocol-http-auth.d.ts

@@ -10,8 +10,8 @@
  * A declaration that breaks the rule is that peer's defect: the resolver throws inside the peer's own dial,
  * so the peer is skipped with a coded warning and its siblings still mount. The MCP transport binds its
  * endpoint by dialing only the declared URL with redirects not followed (`declaredEndpointFetch`); the A2A
- * peer, whose card may name another endpoint, is bound by {@link assertEndpointBound} and by
- * {@link redirectPolicy}.
+ * peer, whose card may name another endpoint, is bound by {@link assertEndpointBound} and by its follow law (a request carrying
+ * declared headers follows no redirect, {@link carriesDeclaredHeaders}).
  */
 import type { ProtocolId } from "./protocol-table.js";
 /** The per-peer HTTP auth declaration every protocol spec carries in the same two fields. */
@@ -35,10 +35,31 @@ export declare function resolveProtocolHttpHeaders(protocol: ProtocolId, t: Prot
 /** The engine's default request headers under the declared ones: a declared name, in any case, owns that header
  *  (the default of the same name is not sent beside it). */
 export declare function underDeclaredHeaders(defaults: Readonly<Record<string, string>>, declared: Record<string, string> | undefined): Record<string, string>;
-/** Whether a resolved header set carries anything the declaration bound to its endpoints. */
+/**
+ * Every header VALUE one HTTP peer's requests carry, whatever the header's NAME: each string value of the declaration's static
+ * `headers` and the principal the engine sends under `principalHeader`, as declared. The transport knows these; the credential vocabulary
+ * can only guess by name. How an endpoint can print one back — edges dropped, its credentials part, percent-encoded — is derived from
+ * each value by {@link requestEchoSpellings}, once, and nowhere else.
+ * Total: a declaration whose members cannot be read yields what could be read, because it is called on a failure path.
+ */
+export declare function declaredHeaderValues(transport: unknown, principal?: string): readonly string[];
+/**
+ * A peer's error text with what the peer was SENT taken out of it. Both kinds of removal are found on the ORIGINAL text (so no marker is
+ * rescanned and no replacement can disturb what another one reads) and the ranges they take are merged, one marker per merged range: every
+ * occurrence of a declared value in any spelling {@link requestEchoSpellings} derives from it (as declared and as sent, its credentials
+ * part, JSON-escaped with or without `\/`, percent-encoded, form-urlencoded, `+` for a space), in any letter case, longest first, and every `Cookie` / `Set-Cookie` member
+ * whole — a header line to its end, a record member's string, array or object to its close. The two never disarm each other: a declared
+ * value that lies wholly inside a Cookie member's NAME leaves the name (and the member's value is still taken); one that overlaps the name
+ * from outside takes its own range and the member's value goes with it. A declared value that is also an ordinary word or number (`en`, `1`,
+ * `application/json`) goes wherever it occurs in the remote's words, in any case — a legibility cost, never a leak; the failure's closed
+ * fields (code, status, delivery) are not text. A declaration too large for one matcher (tens of thousands of characters, which no header
+ * carries) makes the whole text the marker: the pass never throws and never shows what it could not match. Run BEFORE the credential
+ * vocabulary: that pass rewrites parts of a value, after which the value no longer matches whole.
+ */
+export declare function scrubRequestEcho(text: string, declared: readonly string[]): string;
+/** Whether a resolved header set carries anything the declaration bound to its endpoints — a request that does follows no redirect (the
+ *  next hop is not a declared endpoint; A2A's follow law reads this). */
 export declare function carriesDeclaredHeaders(headers: Record<string, string> | undefined): boolean;
-/** A request carrying declared headers does not follow a redirect (the next hop is not a declared endpoint). */
-export declare function redirectPolicy(headers: Record<string, string> | undefined): "manual" | "follow";
 /**
  * Refuse an endpoint a peer advertised (an A2A card's interface URL) when it lies outside every origin the
  * declaration names and the peer's requests carry declared headers: `config.protocol_endpoint_unbound`.