@sema-agent/core 7.46.0 → 7.47.0

package/dist/core/permission-rules.js

@@ -1,15 +1,14 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { splitNamespacedName } from "./tool-name-aliases.js";
-import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
+import { catalogRuleFaceOf, isShellFaceToolName, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
-import { NAME_RULE_FACES, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, nameRuleAdmits, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleBasesNeeded, ruleToolGrammarOf } from "./permission-rule-model.js";
+import { COMMAND_RULE_TOOL, NAME_RULE_FACES, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, laneToolNamesOf, nameRuleAdmits, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleBasesNeeded, ruleToolGrammarOf } from "./permission-rule-model.js";
 import { pathFamilyOf } from "../tools/fs/safety.js";
 import { callTargetReadingOf, callTargetViewsOf } from "./effective-path-target.js";
 import { bindPathRules, pathRowsReach, policyAnchors, rowsWhereTheyLead } from "./path-rule-binding.js";
 import { ruleDenialSentence } from "./rule-denial-sentence.js";
 import { heldValues } from "./tool-name-readings.js";
 export { parsePermissionRule };
-export const BASH_GENERIC_PARAMS = new Set(catalogRuleFaceOf("Bash")?.params ?? []);
 function describeBehavior(v) {
     switch (typeof v) {
         case "undefined": return "undefined";
@@ -110,13 +109,14 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
         return { face, judged: face !== undefined };
     };
     const byTool = new Map();
+    const command = { deny: [], ask: [] };
     const namespacedCovering = { deny: [], ask: [] };
     const issues = [];
     const bad = (rule, code, message) => {
         issues.push({ rule, code, message });
     };
     if (rules.length > caps.maxRules) {
-        return { byTool, namespacedCovering, issues: [{ rule: "", code: "invalid.cap_exceeded", message: `${rules.length} rules > maxRules ${caps.maxRules}` }] };
+        return { byTool, command, namespacedCovering, issues: [{ rule: "", code: "invalid.cap_exceeded", message: `${rules.length} rules > maxRules ${caps.maxRules}` }] };
     }
     for (const r of rules) {
         const text = r.rule;
@@ -174,17 +174,24 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
         }
         const content = parsed.ruleContent;
         const colon = content.indexOf(":");
-        if (toolName === "Bash") {
+        if (isShellFaceToolName(toolName)) {
             const paramPart = colon > 0 ? content.slice(0, colon).trim() : "";
-            const looksLikeParamRule = colon > 0 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(paramPart) && BASH_GENERIC_PARAMS.has(paramPart);
-            if (!looksLikeParamRule || content.endsWith(":*")) {
+            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.`
+                    : `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;
                 }
-                entry.content[verb].push({ parsed: parsedCommand.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
-                byTool.set(toolName, entry);
+                command[verb].push({ parsed: parsedCommand.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
                 continue;
             }
         }
@@ -264,7 +271,7 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
         entry.param[verb].push({ param, pattern, behavior: verb, ruleText: text, source: r.source });
         byTool.set(toolName, entry);
     }
-    return { byTool, namespacedCovering, issues };
+    return { byTool, command, namespacedCovering, issues };
 }
 export function validatePermissionRules(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
@@ -303,7 +310,7 @@ const NO_LEADS = new Map();
 export function createPermissionRulePolicy(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
     const pathBases = opts?.pathBases ?? {};
-    const { byTool, namespacedCovering, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.ruleFaces, pathBases);
+    const { byTool, command, namespacedCovering, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.ruleFaces, pathBases);
     const setLevelCap = issues.some((i) => i.code === "invalid.cap_exceeded" && i.rule === "");
     if (issues.length > 0 && ((opts?.onInvalidRule ?? "throw") === "throw" || setLevelCap)) {
         const e = new Error(`createPermissionRulePolicy: ${issues.length} invalid/unsupported rule(s):\n` +
@@ -335,6 +342,9 @@ export function createPermissionRulePolicy(rules, opts) {
         if (entry.bare.ask !== undefined || entry.param.ask.length > 0 || entry.content.ask.length > 0)
             nameSets.ask.push(toolName);
     }
+    for (const behavior of ["deny", "ask"])
+        if (command[behavior].length > 0 && !nameSets[behavior].includes(COMMAND_RULE_TOOL))
+            nameSets[behavior].push(COMMAND_RULE_TOOL);
     for (const behavior of ["deny", "ask"]) {
         for (const r of namespacedCovering[behavior])
             nameSets[behavior].push(r.ruleName);
@@ -345,11 +355,13 @@ export function createPermissionRulePolicy(rules, opts) {
         deny: [...byTool.values()].flatMap((e) => e.content.deny.filter((r) => r.faces !== undefined)),
         ask: [...byTool.values()].flatMap((e) => e.content.ask.filter((r) => r.faces !== undefined)),
     };
-    const contentLaneOf = (behavior, entry, callFace) => [
+    const contentLaneOf = (behavior, entry, shellCall, callFace) => [
         ...(entry?.content[behavior].filter((r) => r.faces === undefined) ?? []),
+        ...(shellCall ? command[behavior] : []),
         ...(callFace !== undefined ? faceRules[behavior].filter((r) => r.faces.includes(callFace)) : []),
     ];
-    const commandParam = catalogRuleFaceOf("Bash")?.primaryParams[0] ?? "command";
+    const hasCommandRules = command.deny.length > 0 || command.ask.length > 0;
+    const commandParam = catalogRuleFaceOf(COMMAND_RULE_TOOL)?.primaryParams[0] ?? "command";
     const pathRuleOf = new Map();
     for (const e of byTool.values()) {
         for (const behavior of ["deny", "ask"]) {
@@ -450,7 +462,8 @@ export function createPermissionRulePolicy(rules, opts) {
                     return { action: "deny", message: ruleDenial(req, coveringDeny.ruleText, coveringDeny.source) };
             }
             const callFace = faceRules.deny.length > 0 || faceRules.ask.length > 0 ? callPathFaceOf(req) : undefined;
-            const denyLane = contentLaneOf("deny", entry, callFace);
+            const shellCall = hasCommandRules && laneToolNamesOf(req).includes(COMMAND_RULE_TOOL);
+            const denyLane = contentLaneOf("deny", entry, shellCall, callFace);
             const contentDeny = denyLane.length > 0 ? contentHit(denyLane, req) : undefined;
             if (contentDeny !== undefined && contentDeny.unreadable === undefined) {
                 return { action: "deny", message: ruleDenial(req, contentDeny.rule.ruleText, contentDeny.rule.source) };
@@ -473,7 +486,7 @@ export function createPermissionRulePolicy(rules, opts) {
                 if (coveringAsk)
                     return { action: "ask", message: ruleAskMessage(coveringAsk.ruleText, coveringAsk.source), matchedAskRule: coveringAsk.ruleText };
             }
-            const askLane = contentLaneOf("ask", entry, callFace);
+            const askLane = contentLaneOf("ask", entry, shellCall, callFace);
             const contentAsk = askLane.length > 0 ? contentHit(askLane, req) : undefined;
             if (contentAsk !== undefined) {
                 if (contentAsk.unreadable !== undefined)

package/dist/core/runner/gate-exit.d.ts

@@ -23,7 +23,7 @@
  */
 import { type ClassifierDenyCause, type DeniedBy, type GateOutcome, type ModeRefusal, type ModeRelease, type Settlement } from "../gate-outcome.js";
 import type { AutoModeClassifierRound } from "../auto-mode.js";
-import { type Arbitration, type AskClassification, type AskOrigin, type AskOriginFacts } from "../ask-origin.js";
+import { type Arbitration, type AskClassification, type AskFace, type AskOrigin, type AskOriginFacts } from "../ask-origin.js";
 import { type PermissionResult, type ResolvedAsk, type ToolCallRequest } from "../tool-policy.js";
 import type { SafeNotifier } from "../safe-notify.js";
 import type { HookSeatOutcome, PermissionDeniedPayload, PreToolUseResult, ToolGateInput, ToolGateResult } from "../hooks.js";
@@ -143,6 +143,9 @@ export interface PreToolUseScreening {
     /** The model-facing text for an answer the decision receipt refused (an ENGINE fail-closed, not the face's deny). */
     refusedReason(answer: PreToolUseResult): string;
 }
+/** The FACE a pass's questions are put on ({@link askFaceOf} of the call's wire name) — the one reading of it the
+ *  write-protection tighten (the fold) and every class derivation (the lanes) make. */
+export declare function passAskFace(pass: Pick<GatePass, "req">): AskFace;
 /**
  * ONE gate pass — the record the station groups (`runGateFold`, `runGateLanes`) and the exits read and write,
  * built once per call by `runToolGate` before the screening pass. What used to be the closure-captured `let`

package/dist/core/runner/gate-exit.js

@@ -1,5 +1,6 @@
 import { screenGateOutcome, SETTLEMENT_IS_REFUSAL } from "../gate-outcome.js";
-import { classifyAsk, headlessApprovalRemedy } from "../ask-origin.js";
+import { askFaceOf, classifyAsk, headlessApprovalRemedy } from "../ask-origin.js";
+import { wireOf } from "../tool-name-readings.js";
 import { isProtectedWrite } from "../tool-registry.js";
 import { askUnresolvableCauseOf, classifierDenyCauseOf, classifierRoundOf, decisionText, engineSettlementOf } from "../tool-policy.js";
 import { askUnresolvableRemedySeat } from "../ask-unresolvable-notice.js";
@@ -97,6 +98,9 @@ function withParkFailureCause(reason, parkFailed) {
         `(${inlineUntrusted(parkFailed, PARK_FAILURE_CAUSE_MAX)}), so the refusal above is what the fallback had ` +
         `left to say, not the reason the call stopped.`);
 }
+export function passAskFace(pass) {
+    return askFaceOf(wireOf("gate.askFace", pass.req));
+}
 export async function engineFailClosedExit(pass, reason) {
     const { input, toolName, toolCallId, notifyPermissionDenied } = pass;
     const gate = directDeny("hook");

package/dist/core/runner/prepare-hands-readface.js

@@ -8,7 +8,7 @@ import { placeReadDenyAtHome } from "../../tools/fs/read-deny-home.js";
 import { createShellOverflowSpoolFence } from "../../tools/fs/fs-shared.js";
 import { createShellReadStation } from "../../tools/fs/shell-read-check.js";
 import { composeReadChecks, createFileReadStation } from "../../tools/fs/file-read-check.js";
-import { readTargetToolNames } from "../tool-registry.js";
+import { isShellFaceToolName, predictMountedToolNames, readTargetToolNames } from "../tool-registry.js";
 import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
 import { deliverEngineNotice } from "../types.js";
@@ -203,6 +203,7 @@ export async function prepareHandsMount(input) {
         const handsIncludeShell = !(executionEnv instanceof StubExecutionEnv);
         const handsReadOnly = spec.handsReadOnly === true;
         backgroundTaskToolsActive = handsIncludeShell && !handsReadOnly && hasBackgroundShell(executionEnv);
+        const shellFaceHere = [...predictMountedToolNames(new Set(backgroundTaskToolsActive ? ["hands", "backgroundTasks"] : ["hands"]))].filter(isShellFaceToolName);
         wsSnapshot = resume !== undefined || !(handsIncludeShell && !handsReadOnly) ? undefined : await session.getWorkspaceState().catch(() => undefined);
         rebaseWsPath = (p) => (wsSnapshot === undefined || wsSnapshot.taskRoot === rootCanonical ? p : rebaseWorkspacePath(p, wsSnapshot.taskRoot, rootCanonical));
         if (handsIncludeShell && !handsReadOnly) {
@@ -307,7 +308,7 @@ export async function prepareHandsMount(input) {
         if (handsIncludeShell) {
             const spoolFence = handsReadOnly ? createShellOverflowSpoolFence(executionEnv) : undefined;
             const readonlyBoundary = () => spoolFence !== undefined ? { roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical], cwd: rootCanonical, ...denySeat, ...writeDenySeat, alsoInside: spoolFence } : undefined;
-            shellReadTools = new Set(handsReadOnly ? ["Bash"] : backgroundTaskToolsActive ? ["Bash", "Monitor"] : ["Bash"]);
+            shellReadTools = new Set(shellFaceHere);
             shellReadStation = createShellReadStation({
                 env: executionEnv,
                 tools: shellReadTools,
@@ -400,9 +401,8 @@ export async function prepareHandsMount(input) {
                 if (seatOwned)
                     shellGatedTools.add(name);
             };
-            installShellSeat("Bash");
-            if (backgroundTaskToolsActive)
-                installShellSeat("Monitor");
+            for (const name of shellFaceHere)
+                installShellSeat(name);
         }
     }
     return {

package/dist/core/runner/prepare-policy-chain.js

@@ -14,7 +14,7 @@ import { emitTrace } from "../trace.js";
 import { skillGrantBindingMembers } from "../skill-grant.js";
 import { SKILL_TOOL_NAME } from "./synthetic-tools.js";
 import { autoStrippedRule, cardDisclosureOf } from "../allow-entry.js";
-import { arbitrateByMode, askClassMembersOf, askMandateMember } from "../ask-origin.js";
+import { arbitrateByMode, askClassMembersOf, askFaceOf, askMandateMember } from "../ask-origin.js";
 import { createModeGatePolicy, mountedToolDeclaresReadOnly } from "../mode-policy.js";
 const ancestorFacts = (ask) => ({ ...(ask ?? {}), ancestorResolved: true });
 import { headlessDenyAtFold, headlessDenyAtRecheck, INHERITED_STATION_FACTS, inheritedAskCarry, inheritedAskFallbackMessage, judgeInheritedClassifier, lateAskSettlementObserver, resolveInheritedAsk, settleDenialLimitFallback } from "./denial-limit-arms.js";
@@ -313,6 +313,7 @@ export async function preparePolicyChain(input) {
             ...(seat.sources.size > 0 ? { toolMarkSources: seat.sources } : {}),
             ...(deps.a2a?.isolatePeers === true ? { a2aIsolatePeers: true } : {}),
             ...(face !== undefined ? { readFace: face } : {}),
+            askFace: askFaceOf(wireOf("inherited.askFace", call)),
         };
     };
     const inheritedAskEvidence = inheritedAskRuleEvidence(deps.permissionRuleStore);

package/dist/core/shell-wrapper-projection.js

@@ -30,7 +30,7 @@ const runsCommand = (spec) => spec.effect === "executes" || spec.value?.kind ===
 function projectRow(row) {
     const sorted = (xs) => [...new Set(xs)].sort();
     const all = spellings(row);
-    const viaShell = row.reentry?.kind === "shell" || row.launcher?.shellText === true || row.body === "first-operand" || row.body === "assignment-values" || (row.operands?.rest?.kind === "program-text" && row.operands.rest.language === "arithmetic");
+    const viaShell = row.reentry?.kind === "shell" || row.launcher?.shellText !== undefined || row.body === "first-operand" || row.body === "assignment-values" || (row.operands?.rest?.kind === "program-text" && row.operands.rest.language === "arithmetic");
     if (row.launcher === undefined) {
         if (viaShell)
             return { valueFlags: [], flags: [], commandString: [], viaShell: true };

package/dist/core/shell-wrapper-table.d.ts

@@ -276,15 +276,15 @@ export declare const SHELL_WRAPPER_TABLE: {
         readonly commandString: readonly [];
     };
     readonly su: {
-        readonly valueFlags: readonly [];
-        readonly flags: readonly [];
-        readonly commandString: readonly [];
+        readonly valueFlags: readonly ["--group", "--shell", "--supp-group", "--whitelist-environment", "-G", "-g", "-s", "-w"];
+        readonly flags: readonly ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"];
+        readonly commandString: readonly ["--command", "--session-command", "-c"];
         readonly viaShell: true;
     };
     readonly runuser: {
-        readonly valueFlags: readonly [];
-        readonly flags: readonly [];
-        readonly commandString: readonly [];
+        readonly valueFlags: readonly ["--group", "--shell", "--supp-group", "--user", "--whitelist-environment", "-G", "-g", "-s", "-u", "-w"];
+        readonly flags: readonly ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"];
+        readonly commandString: readonly ["--command", "--session-command", "-c"];
         readonly viaShell: true;
     };
     readonly chroot: {

package/dist/core/shell-wrapper-table.js

@@ -43,8 +43,8 @@ export const SHELL_WRAPPER_TABLE = {
     compgen: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
     complete: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
     busybox: { valueFlags: [], flags: [], commandString: [] },
-    su: { valueFlags: [], flags: [], commandString: [], viaShell: true },
-    runuser: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    su: { valueFlags: ["--group", "--shell", "--supp-group", "--whitelist-environment", "-G", "-g", "-s", "-w"], flags: ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"], commandString: ["--command", "--session-command", "-c"], viaShell: true },
+    runuser: { valueFlags: ["--group", "--shell", "--supp-group", "--user", "--whitelist-environment", "-G", "-g", "-s", "-u", "-w"], flags: ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"], commandString: ["--command", "--session-command", "-c"], viaShell: true },
     chroot: { valueFlags: [], flags: [], commandString: [], positional: /^/ },
     setpriv: { valueFlags: [], flags: [], commandString: [] },
     numactl: { valueFlags: [], flags: [], commandString: [] },

package/dist/core/tool-catalog-entries.js

@@ -8,7 +8,8 @@ export const TASK_LIST_TOOL_NAME = "TaskList";
 export const TODO_WRITE_TOOL_NAME = "TodoWrite";
 export const REFRESH_MCP_TOOLS_TOOL_NAME = "RefreshMcpTools";
 export const ARTIFACT_TOOL_NAME = "Artifact";
-const SHELL_RULE_FACE = { primaryParams: ["command"], params: ["command", "timeout", "description", "run_in_background"] };
+const shellRuleFace = (params) => ({ grammar: "command", primaryParams: ["command"], params });
+const SHELL_RULE_FACE = shellRuleFace(["command", "timeout", "description", "run_in_background"]);
 const c = (contractId, implementationRevision = "1") => ({ contractId, implementationRevision });
 export const TOOL_CATALOG_ENTRIES = [
     {
@@ -108,7 +109,7 @@ export const TOOL_CATALOG_ENTRIES = [
     { id: "task-stop-hands", name: "TaskStop", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"], cards: [], face: { family: "delegate", effect: "write", contract: TASK_STOP_CONTRACT } },
     { id: "task-output", name: "TaskOutput", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-output"], face: { family: "delegate", effect: "read", contract: TASK_OUTPUT_CONTRACT } },
     { id: "task-stop", name: "TaskStop", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-stop"], face: { family: "delegate", effect: "write", contract: TASK_STOP_CONTRACT } },
-    { id: "monitor", name: "Monitor", source: "builtin", definedIn: "src/tools/monitor.ts", mountedBy: ["backgroundTasks"], cards: ["monitor-start", "readonly_out_of_root", "read_unestablished"], face: { family: "other", effect: "write", contract: c("core.monitor@1"), offloadThresholdChars: 10_000 } },
+    { id: "monitor", name: "Monitor", source: "builtin", definedIn: "src/tools/monitor.ts", mountedBy: ["backgroundTasks"], cards: ["monitor-start", "readonly_out_of_root", "read_unestablished"], face: { family: "other", effect: "write", contract: c("core.monitor@1"), ruleFace: shellRuleFace(["command", "description", "timeout_ms", "persistent"]), offloadThresholdChars: 10_000 } },
     { id: "send-message", name: "SendMessage", source: "builtin", definedIn: "src/agents/send-message-tool.ts", mountedBy: ["delegation", "hostInternals", "peerLane"], cards: ["send-message"], face: { family: "protocol", effect: "write", contract: c("core.send_message@1") } },
     { id: "agent-transcript", name: "AgentTranscript", source: "builtin", definedIn: "src/agents/agent-transcript-tool.ts", mountedBy: ["delegation"], cards: ["agent-transcript"], face: { family: "delegate", effect: "read", contract: c("core.agent_transcript@1") } },
     { id: "list-agents", name: "ListAgents", source: "builtin", definedIn: "src/agents/list-agents-tool.ts", mountedBy: ["delegation", "peerLane"], cards: ["list-agents"], face: { family: "protocol", effect: "read", aliases: ["ListPeers"], contract: c("core.list_agents@1") } },

package/dist/core/tool-face.d.ts

@@ -201,7 +201,16 @@ export interface ToolFaceDeclaration {
     };
     aliases?: string[];
     pathTarget?: ToolPathTarget;
-    ruleFace?: ToolRuleFace;
+    /**
+     * The rule face ({@link ToolRuleFace}) and, for a definition whose primary parameter is a shell command line, the grammar
+     * that judges it — `grammar: "command"`, the SHELL FACE. Every `Bash(<command>)` rule (the command grammar's one spelling,
+     * deny / ask / allow, from every source) is judged on a call that answers to the name of such a definition, against that
+     * parameter; a bare `Bash` rule stays a rule on the tool of that name. Only a catalog row declares it (a caller's
+     * `ToolSpec.ruleFace` is a {@link ToolRuleFace}): the static catalog is the one place the shell face is read from.
+     */
+    ruleFace?: ToolRuleFace & {
+        readonly grammar?: "command";
+    };
     renderHints?: ToolRenderHints;
     offload?: boolean;
     offloadThresholdChars?: number;

package/dist/core/tool-name-readings.d.ts

@@ -69,6 +69,10 @@ export declare const NAME_READINGS: {
         readonly kind: "wire";
         readonly file: string;
     };
+    readonly "gate.askFace": {
+        readonly kind: "wire";
+        readonly file: string;
+    };
     readonly "fold.readStation": {
         readonly kind: "seat";
         readonly rank: "member";
@@ -251,6 +255,10 @@ export declare const NAME_READINGS: {
         readonly kind: "wire";
         readonly file: string;
     };
+    readonly "inherited.askFace": {
+        readonly kind: "wire";
+        readonly file: string;
+    };
     readonly "park.contentKindProjection": {
         readonly kind: "wire";
         readonly file: string;

package/dist/core/tool-name-readings.js

@@ -19,6 +19,7 @@ export const NAME_READINGS = {
     "gate.sandboxBoundary.egress": any(CHAIN),
     "gate.sandboxBoundary.hand": wire(CHAIN),
     "gate.preToolUse": wire("src/core/hooks.ts"),
+    "gate.askFace": wire("src/core/runner/gate-exit.ts"),
     "fold.readStation": seat("member", "src/tools/fs/shell-read-check.ts"),
     "lanes.contentQuestionClass": any(LANES),
     "lanes.readOnlyShellAllow": wire(LANES),
@@ -63,6 +64,7 @@ export const NAME_READINGS = {
     "activity.sink": spelling(HANDLERS),
     "reconcile.orphanEffect": spelling("src/core/session-reconcile.ts"),
     "inherited.questionFloat": wire(CHAIN),
+    "inherited.askFace": wire(CHAIN),
     "park.contentKindProjection": wire("src/core/checkpoint-store.ts"),
     "resume.contentAskRow": wire("src/core/runner/decide-continuation.ts"),
     "resume.editRecheckQuestionSkip": wire("src/core/runner/resume-apply.ts"),

package/dist/core/tool-policy.d.ts

@@ -977,13 +977,14 @@ export declare function createApprovalPolicy(opts: {
  */
 export declare function combinePolicies(...policies: ToolPolicy[]): ToolPolicy;
 /**
- * The shell tools whose `{ command }` arg a coarse command-name policy parses; other tools are out of scope. `Monitor`
- * belongs here: it runs an arbitrary shell `command` through the same env seam as Bash, so the always-on parity gates
- * keyed on this list reach it too (a list of `Bash` alone let the identical command run ungated as `Monitor`). EXPORTED:
- * a downstream governance layer keeps its own copy of this list so its per-command ask-list gates the same tools core
- * does — the list itself is the fact, and publishing it removes the guess.
+ * The shell tools whose `{ command }` arg a coarse command-name policy parses; other tools are out of scope. It is the
+ * catalog's shell face ({@link shellFaceToolNames} — every definition whose `command` the command grammar judges, `Monitor`
+ * among them: it runs an arbitrary shell `command` through the same env seam as Bash), spelled out for the wire; the
+ * catalog's shell face is the truth, and a lockstep pin keeps the two one (a catalog row added or dropped turns it red):
+ * the always-on parity gates keyed on it, the `Bash(...)` rules and the shell seat reach the same tools. EXPORTED: a
+ * downstream governance layer reads it so its per-command ask-list gates the same tools core does.
  */
-export declare const COARSE_SHELL_TOOLS: string[];
+export declare const COARSE_SHELL_TOOLS: readonly ["Bash", "Monitor"];
 /**
  * design/center §10 — a COARSE allow/deny gate keyed on the LEADING command NAME (`argv[0]`) of a single
  * simple shell command. It reuses the ONE shared simple-command parser
@@ -1033,7 +1034,7 @@ export declare function createCoarseCommandNamePolicy(opts: {
     deny?: string[];
     /** What to do for a command not matched by `allow` (or un-parseable): `"ask"` (default) or `"deny"`. */
     defaultAction?: "ask" | "deny";
-    /** Override the shell tool names this gate parses (default `Bash` — bash + bash_readonly share the CC name). */
+    /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
     tools?: string[];
 }): ToolPolicy;
 export declare function findUnverifiableRecursiveDelete(command: string, safeVars?: ReadonlySet<string>): string | undefined;
@@ -1112,7 +1113,7 @@ export declare function createUnverifiableDeletePolicy(opts?: {
      *  the default was `TMPDIR` alone, reading STRICTER than the gate really is; `HOME`/`PWD` are a
      *  registered sema divergence from CC's temp-only carve-out, see the RB-340 note there). */
     safeVars?: readonly string[];
-    /** Override the shell tool names this gate parses (default `Bash`). */
+    /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
     tools?: string[];
     removalSeat?: RemovalGuardSeat;
 }): ToolPolicy;
@@ -1121,7 +1122,7 @@ export declare function createTranscriptIntegrityPolicy(opts?: {
     sessionsDirs?: readonly string[];
     /** argv[0] allowlist for read-only access to the transcript dir (default {@link BASH_READONLY_DEFAULT_ALLOW}). */
     readAllow?: readonly string[];
-    /** Override the shell tool names this gate parses (default `Bash`). */
+    /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
     tools?: string[];
 }): ToolPolicy;
 /**

package/dist/core/tool-policy.js

@@ -10,7 +10,7 @@ export { policyCannotAnswer, rowDemandsAPerson } from "./real-approval.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
-import { protectivePathTargetOf } from "./tool-registry.js";
+import { protectivePathTargetOf, shellFaceToolNames } from "./tool-registry.js";
 import { heldBy } from "./tool-name-readings.js";
 import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
@@ -642,7 +642,7 @@ export function combinePolicies(...policies) {
         },
     };
 }
-export const COARSE_SHELL_TOOLS = ["Bash", "Monitor"];
+export const COARSE_SHELL_TOOLS = Object.freeze(["Bash", "Monitor"]);
 function canonicalToolNameSet(tools) {
     return new Set(tools ?? COARSE_SHELL_TOOLS);
 }

package/dist/core/tool-registry.d.ts

@@ -25,6 +25,15 @@ export declare function catalogToolNames(): ReadonlySet<string>;
 export declare function pathConfinableWriteToolNames(): ReadonlySet<string>;
 /** A-8 — every definition that names a path target at all (read or write): the file-tool glob lane. */
 export declare function pathTargetingToolNames(): ReadonlySet<string>;
+/**
+ * The SHELL FACE: every definition whose `command` argument is a shell command line the command grammar judges (today the two
+ * `Bash` definitions and `Monitor`). A `Bash(<command>)` rule reaches a call that answers to any of these names; the coarse
+ * command-name gate's default list, the shell read station and the shell seat are this set. Derived from the rows' rule faces,
+ * never a list of its own.
+ */
+export declare function shellFaceToolNames(): ReadonlySet<string>;
+/** {@link shellFaceToolNames}' membership for one name — any definition under the name on the shell face. */
+export declare function isShellFaceToolName(name: string): boolean;
 /** The tools whose declared path target is a READ (a file read, a search root): the file read station's membership. */
 export declare function readTargetToolNames(): ReadonlySet<string>;
 /** A-10 — the micro-compaction whitelist (`compactable: true`). */

package/dist/core/tool-registry.js

@@ -29,6 +29,16 @@ export function pathConfinableWriteToolNames() {
 export function pathTargetingToolNames() {
     return names((e) => e.face.pathTarget !== undefined);
 }
+const onShellFace = (e) => e.face.ruleFace?.grammar === "command";
+export function shellFaceToolNames() {
+    return names(onShellFace);
+}
+export function isShellFaceToolName(name) {
+    for (const e of TOOL_CATALOG_ENTRIES)
+        if (e.name === name && onShellFace(e))
+            return true;
+    return false;
+}
 export function readTargetToolNames() {
     return names((e) => e.face.pathTarget?.access === "read");
 }

package/dist/core/write-protect.d.ts

@@ -1,5 +1,6 @@
 import type { ExecutionEnv } from "../internal/harness-types.js";
 import type { PermissionResult } from "./tool-policy.js";
+import { type AskFace } from "./ask-origin.js";
 import { type ToolCallLike } from "./tool-registry.js";
 /**
  * How one table row matches the judged path:
@@ -209,11 +210,17 @@ export declare function compileWriteProtection(entries?: readonly WriteProtected
  *    message (table names are deployment-validated vocabulary); the model-authored target path deliberately
  *    does not — `message` is the classifier's `askMessage`, and the approval card already shows the args. The
  *    spelling form's sentence is the historical one byte for byte; the target form says the target RESOLVED.
- *  · `unresolvable` ⇒ `deny` naming the cause: an unjudged target is never vouched, and an ask would be a
- *    question about a file nobody can name — the rule the canonicalizing deny set follows for the same reason.
+ *  · `unresolvable` ⇒ read by the call's FACE (`face`, {@link releasableAskClassesFor}): where no permission mode releases
+ *    `write_protection_unresolved` (the file face) — `deny` naming the cause: an unjudged target is never vouched (the rule
+ *    the canonicalizing deny set follows for the same reason), so there a standing allow is refused while a standing ask
+ *    carrying the record stays a person's question in the modes that ask (dontAsk and bypassPermissions refuse it); where
+ *    a mode may release the class (the shell face) — `ask` (`safety`)
+ *    naming the cause, which the mode arbitration answers exactly as it answers that record over a standing ask
+ *    (bypassPermissions releases it, default puts it to a person, dontAsk refuses): on that face alone a standing allow
+ *    reads as a standing ask.
  *  · `clear` ⇒ `undefined`: the surviving decision stands.
  */
-export declare function writeProtectionTightenDecision(toolName: string, verdict: WriteProtectionVerdict): PermissionResult | undefined;
+export declare function writeProtectionTightenDecision(toolName: string, verdict: WriteProtectionVerdict, face: AskFace): PermissionResult | undefined;
 /**
  * @contract write_protection.verdict_is_the_mandate — the judge's two non-clear verdicts are the two facts
  * a standing allow rule may not retire, and `clear` is neither: a MATCHED row is the mandate a live decider

package/dist/core/write-protect.js

@@ -1,3 +1,4 @@
+import { releasableAskClassesFor } from "./ask-origin.js";
 import { canonicalizeTarget, isWinFormPath, writeTargetPath, isUncPath, isAbsoluteForFamily, joinForFamily, pathFamilyOf } from "../tools/fs/safety.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
@@ -346,7 +347,7 @@ export function compileWriteProtection(entries, opts) {
         },
     };
 }
-export function writeProtectionTightenDecision(toolName, verdict) {
+export function writeProtectionTightenDecision(toolName, verdict, face) {
     if (verdict.kind === "hit") {
         return {
             action: "ask",
@@ -359,6 +360,15 @@ export function writeProtectionTightenDecision(toolName, verdict) {
         };
     }
     if (verdict.kind === "unresolvable") {
+        if (releasableAskClassesFor(face).includes("write_protection_unresolved")) {
+            return {
+                action: "ask",
+                message: verdict.unresolvedSymlink
+                    ? `tool "${toolName}" writes to a symlink whose real target could not be resolved, so the write-protection judge cannot tell whether it lands on a protected path (${verdict.cause}) — explicit approval required`
+                    : `tool "${toolName}" writes to a target that could not be resolved on this tree, so the write-protection judge cannot tell whether it lands on a protected path (${verdict.cause}) — explicit approval required`,
+                decisionReason: "safety",
+            };
+        }
         return {
             action: "deny",
             message: verdict.unresolvedSymlink

package/dist/index.d.ts

@@ -197,7 +197,7 @@ export { createAllowDenyPolicy, createApprovalPolicy,
 type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, abortedSeatDeny, receiveHookResult, isEngineRefusal, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathRules, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export { type ReadRootGrantScreen } from "./core/read-root-grant-screen.js";
 export { type AskOrigin, ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate, screenAskClassMembers } from "./core/ask-origin.js";
-export { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, RELEASABLE_ASK_CLASSES, MODE_RELEASE_REASONS, type ModeReleaseReason, isModeReleaseReason, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, type AskClassification, type AskClassFacts, type ToolMarkSource, arbitrateByMode, type Arbitration, fileCommandOptionsSentence } from "./core/ask-origin.js";
+export { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, ASK_FACES, type AskFace, askFaceOf, releasableAskClassesFor, MODE_RELEASE_REASONS, type ModeReleaseReason, isModeReleaseReason, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, type AskClassification, type AskClassFacts, type ToolMarkSource, arbitrateByMode, type Arbitration, fileCommandOptionsSentence } from "./core/ask-origin.js";
 export { modePolicyOf, type ModePolicy, PERMISSION_MODE_FOLD_REASONS, type PermissionModeFoldReason, type PermissionModeReceipt, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
 export type { PermissionSeatInputs, PermissionSeatReading } from "./core/mode-policy.js";
 export type { SkillGateSeats, SkillGrantHit, SkillGrantLane, SkillGrantOrigin, SkillGrantRecord } from "./core/skill-grant.js";

package/dist/index.js

@@ -162,7 +162,7 @@ export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.
 export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, abortedSeatDeny, receiveHookResult, isEngineRefusal, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathRules, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export {} from "./core/read-root-grant-screen.js";
 export { ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, isPersistedRuleMandate, screenAskClassMembers } from "./core/ask-origin.js";
-export { PERMISSION_MODES, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, isAskClass, MODE_ARBITRATION, RELEASABLE_ASK_CLASSES, MODE_RELEASE_REASONS, isModeReleaseReason, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, arbitrateByMode, fileCommandOptionsSentence } from "./core/ask-origin.js";
+export { PERMISSION_MODES, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, isAskClass, MODE_ARBITRATION, ASK_FACES, askFaceOf, releasableAskClassesFor, MODE_RELEASE_REASONS, isModeReleaseReason, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, arbitrateByMode, fileCommandOptionsSentence } from "./core/ask-origin.js";
 export { modePolicyOf, PERMISSION_MODE_FOLD_REASONS, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
 export { SKILL_GRANT_ORIGINS } from "./core/skill-grant.js";
 export { ALLOW_ENTRY_INERT_REASONS, compileAllowEntry, compileAllowList, renderListEntry } from "./core/allow-entry.js";

package/dist/shell/lex.d.ts

@@ -103,6 +103,17 @@ export interface WordExpansion {
     readonly body?: string;
     /** The parameter name, where the expansion names one. */
     readonly name?: string;
+    /** A glob's pattern — absent where an expansion stands inside it (its text is not the pattern): `folded`, what the
+     *  program receives where it matches nothing — quotes removed, the spelling {@link LexedWord.folded} carries at its place
+     *  (`[^.]`); `written`, as written, quoting kept (`[^\.]`, `["!"a]`) — the text a shell re-reading it matches by;
+     *  `judged`, the spelling a reader judges the names it matches by — `folded`, save a class the judge reads as any one
+     *  character: one holding a quoted or escaped character (its quote-removed text reads another class: `["!"a]` is not
+     *  the negation `[!a]`) or a `[:…:]` / `[=…=]` / `[.….]` unit — spelled `?`, a superset of its members. */
+    readonly pattern?: {
+        readonly folded: string;
+        readonly written: string;
+        readonly judged: string;
+    };
 }
 export interface QuotedSpan {
     /** Offsets into {@link LexedWord.raw}, `[start, end)`; the quote characters belong to their span. */
@@ -143,6 +154,10 @@ export interface LexedWord {
     readonly kind: "word";
     readonly raw: string;
     readonly folded: string;
+    /** The spelling a reader judges the word's names by, where it is not `folded`: each bracket class holding a quoted or
+     *  escaped character or a `[:…:]` / `[=…=]` / `[.….]` unit spelled `?` (`["!"a]*`, `[[:alpha:]]*` ⇒ `?*`,
+     *  {@link WordExpansion.pattern}). */
+    readonly judged?: string;
     readonly pieces: readonly WordPiece[];
     readonly quotedSpans: readonly QuotedSpan[];
     /** The pieces that carry an expansion, in order. */