@sema-agent/core 7.54.1 → 7.55.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 { 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,28 @@ 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 { isNamespacedCoveringRuleName, namespacedRuleNameCovers, wildcardMatch } from "./namespaced-rule-name.js";
+import { wildcardPeerRefusalOf } from "./tool-name-aliases.js";
 export { isNamespacedCoveringRuleName, namespacedRuleNameCovers, 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";
+};
 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 +92,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);
@@ -111,23 +120,29 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
             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\``);
+            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", { name: "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)) {
+        const wildPeer = wildcardPeerRefusalOf(toolName, verb);
+        if (wildPeer !== undefined) {
+            bad(text, "invalid.tool_name", wildPeer);
+            continue;
+        }
+        if (parenthesised && isNamespacedCoveringRuleName(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 (isNamespacedCoveringRuleName(toolName, verb)) {
                 namespacedCovering[verb].push({ ruleName: toolName, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
                 continue;
             }
@@ -135,52 +150,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 +222,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 +232,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 +263,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 +288,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})` : ""}`;
@@ -386,11 +398,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 +441,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 });
         }
@@ -454,7 +488,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;
             }

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

@@ -61,8 +61,10 @@ 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.

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/protocol-naming.d.ts

@@ -1,13 +1,13 @@
 import type { ProtocolNamespace } from "./protocol-table.js";
 /** The provider's tool-name pattern is `^[a-zA-Z0-9_-]{1,64}$` — the limit applies to the ASSEMBLED name,
- *  not to its segments (design/116 W5-5, CC 2.1.187 parity `buildMcpToolName`). */
+ *  not to its segments (design/116 W5-5). */
 export declare const TOOL_NAME_MAX_CHARS = 64;
 /** Reserved for the tool segment when budgeting the peer segment: a peer kept at the full name budget
  *  overflows the assembled name on its own (prefix + 64 + separator = 71 > 64), which is how the tool
  *  segment used to be handed a NEGATIVE budget. A tool name shorter than this is not recognizable. */
 export declare const MINTED_TOOL_SEGMENT_MIN_CHARS = 16;
 /**
- * design/116 W5-5 (CC 2.1.187 parity) — normalize a peer/tool segment to the API tool-name charset by
+ * design/116 W5-5 — normalize a peer/tool segment to the API tool-name charset by
  * replacing every other character with `_`. CC does exactly this on BOTH segments when composing
  * `mcp__<server>__<tool>` (services/mcp/normalization.ts `normalizeNameForMCP` + mcpStringUtils.ts
  * `buildMcpToolName`), so a peer advertising a dotted/spaced/unicode name can't mint a name the provider

package/dist/core/read-only-shell-table.d.ts

@@ -1,6 +1,6 @@
 /**
  * The READ-ONLY shell tables — the closed data the read-only reader (`read-only-shell.ts`) judges a
- * command against, transcribed from upstream's own tables (CC 2.1.250) and kept as DATA so the parity
+ * command against, transcribed from upstream's own tables and kept as DATA so the parity
  * question is answered by diffing two tables, never by reading two programs:
  *  - {@link READ_ONLY_COMMAND_TABLE} — the flag-vetted commands: a command (one or more leading words,
  *    `git status`, `gh pr view`, `grep`) with the closed set of flags it may carry, each flag's value

package/dist/core/read-only-shell.d.ts

@@ -8,7 +8,7 @@ export type ReadOnlyShellVerdict = {
     readonly readOnly: false;
     readonly reason: string;
 };
-/** The reference implementation's question for a compound that changes directory and runs git (2.1.280, `cd-git-compound`). */
+/** The reference implementation's question for a compound that changes directory and runs git (`cd-git-compound`). */
 export declare const CD_GIT_COMPOUND_SENTENCE = "This command changes directory before running a version-control command, which can pick up untrusted hooks or repository configuration from the target directory. Approve only if you trust it.";
 /**
  * Does this line change directory and run git — a `cd` beside a `git` — other than by ONE plain `cd <path>` that lands

package/dist/core/roles.d.ts

@@ -3,8 +3,12 @@ import type { Model } from "../internal/llm.js";
 import { type ModelRef, type ModelRole, type ModelRoles, type RoleSpec } from "./types.js";
 export type { ModelRole, RoleSpec, ModelRoles } from "./types.js";
 export { MODEL_ROLES } from "./types.js";
-/** Resolve a string ModelRef against the catalog (a Model object passes through). */
-export declare function resolveModel(ref: ModelRef, models?: Record<string, Model>): Model;
+/**
+ * Resolve a ModelRef against the catalog (a Model object passes through). A word the catalog does not hold, and a value that is no model
+ * reference, are refused by `config.unknown_role` with `detail { field: seat, reason }` — `seat` names where the caller wrote the word
+ * (`"model"` when the caller names none).
+ */
+export declare function resolveModel(ref: ModelRef, models?: Record<string, Model>, seat?: string): Model;
 /** 档位降档链(强→弱)。解析某档无绑定时沿链向后找第一个有绑定的档(fail-open 可用性优先;绑定缺口
  *  在部署 catalog 审计面可见)。`ultra` 预留:排在 `max` 前,今天不绑,未来加档零码改。 */
 export declare const DEFAULT_TIER_ORDER: readonly string[];