@sema-agent/core 7.52.0 → 7.54.0

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

@@ -3,10 +3,12 @@
  * hanging / what brings it back), the three word types and the resume match DERIVED from it, and the
  * registry-bound `gate` × `pendingAction` pair with its checked constructor. A vocabulary module on the
  * floor: it types against `checkpoint-store.ts` (type-only, no runtime edge) and `checkpoint-store.ts`
- * reaches down for the pair type.
+ * reaches down for the pair type and the card reading; its one runtime edge is the card vocabulary
+ * (`tool-face.ts`, itself a leaf).
  */
 import type { AssertAllKeysHandled } from "./ask-origin.js";
 import type { Checkpoint, CheckpointGate, CheckpointRow, PendingAction, ResumeOutcome } from "./checkpoint-store.js";
+import { type ToolApprovalCard } from "./tool-face.js";
 /**
  * THE registry of pauses — one row per way a run can stop and wait, and the ONE place the three faces
  * of that pause are declared together: WHY it stopped (`CheckpointGate.kind`, the row key), WHAT it left
@@ -93,6 +95,38 @@ export declare function isQuestionGate(gate: {
     readonly kind: GateKind;
     readonly approvalCard?: unknown;
 }): boolean;
+/** What a parked row's gate says about its approval card — the four answers {@link parkedApprovalCardOf} gives. */
+export type ParkedApprovalCardReading = 
+/** An approval gate carrying a word of the closed card set (`TOOL_APPROVAL_CARDS`). */
+{
+    readonly kind: "card";
+    readonly card: ToolApprovalCard;
+}
+/** An approval gate carrying no card. */
+ | {
+    readonly kind: "no_card";
+}
+/** An approval gate carrying a value outside the closed set (a word a later engine minted, a hand-edited row,
+ *  a non-string). `word` is the value as read, unscreened: a caller that renders it bounds and redacts it. */
+ | {
+    readonly kind: "unknown_word";
+    readonly word: unknown;
+}
+/** Not an approval gate: a registered gate whose `pending` column is not `tool_approval`, or a gate kind the
+ *  registry does not hold. No card is read on it. */
+ | {
+    readonly kind: "not_approval";
+};
+/**
+ * The one reading of a parked row's approval card. A gate is an approval gate when its kind is a registry row whose
+ * `pending` column is `tool_approval`; only there is the card read, and only a member of the closed set is a card.
+ * Each member of `gate` is read once (the value screened is the value answered). Pure: the answer says nothing about
+ * how loud an `unknown_word` should be — that is the caller's to decide.
+ */
+export declare function parkedApprovalCardOf(gate: {
+    readonly kind: unknown;
+    readonly approvalCard?: unknown;
+}): ParkedApprovalCardReading;
 /** The one resume-match predicate: does this outcome gate word answer a checkpoint of this kind? `wake`
  *  answers any (it passed its own, stricter, non-gate validation upstream); every other word must be the
  *  row's `resume` column. Replaces a six-arm hand-written disjunction. */

package/dist/core/pause-registry.js

@@ -1,3 +1,4 @@
+import { isToolApprovalCard } from "./tool-face.js";
 export const PAUSE_REGISTRY = {
     human: { pending: "tool_approval", resume: "policy_ask", facet: "A", taskStatus: "suspended", terminal: false },
     irreversible_ask: { pending: "tool_approval", resume: "policy_ask", facet: "A", taskStatus: "suspended", terminal: false },
@@ -15,6 +16,15 @@ export function facetOf(gate) {
 export function isQuestionGate(gate) {
     return PAUSE_REGISTRY[gate.kind].pending === "tool_approval" && gate.approvalCard === "question";
 }
+export function parkedApprovalCardOf(gate) {
+    const kind = gate.kind;
+    if (!isGateKind(kind) || PAUSE_REGISTRY[kind].pending !== "tool_approval")
+        return { kind: "not_approval" };
+    const word = gate.approvalCard;
+    if (word === undefined)
+        return { kind: "no_card" };
+    return isToolApprovalCard(word) ? { kind: "card", card: word } : { kind: "unknown_word", word };
+}
 export function resumeGateMatches(gateKind, outcomeGate) {
     return outcomeGate === "wake" || PAUSE_REGISTRY[gateKind].resume === outcomeGate;
 }

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

@@ -38,8 +38,15 @@ export interface RuleCandidate {
     rule: string;
     scope: RuleScope;
 }
+/** The approval-record kinds, spelled once: {@link RuleApprovalKind} is derived from this tuple. */
+export declare const RULE_APPROVAL_KINDS: readonly ["card", "import", "starter"];
 /** What the approval record is for — it decides the provenance the minted adds carry. */
-export type RuleApprovalKind = "card" | "import" | "starter";
+export type RuleApprovalKind = (typeof RULE_APPROVAL_KINDS)[number];
+/** The approval-record states, spelled once: {@link RuleApprovalState} is derived from this tuple. */
+export declare const RULE_APPROVAL_STATES: readonly ["pending", "approved", "redeemed"];
+/** Where one approval record stands: `pending` as minted, `approved` once a person confirms, `redeemed` once a
+ *  redemption has recorded its dot (recorded before the rule is written, so a crash leaves a replayable intent). */
+export type RuleApprovalState = (typeof RULE_APPROVAL_STATES)[number];
 /**
  * design/375 §4.1 — one "don't ask again" OPTION as the record stores it: references into the
  * record's `candidates` by index, never rule text of its own. The display triple (rule, match,
@@ -78,6 +85,10 @@ export type RuleOffer2 = {
     readonly uncoveredSegments?: number;
     readonly uncoveredDetail?: readonly UncoveredSegmentDetail[];
 };
+/** The CURRENT record-form version stamp ({@link RuleApprovalRecord.schema}), spelled once: every mint writes it and
+ *  every readback compares against it by equality (an older or absent stamp is a stale row, never a floor). A
+ *  durable backend's stale gate reads this value rather than its own number. */
+export declare const RULE_APPROVAL_RECORD_SCHEMA = 4;
 /** A durable record of one pending/settled human decision about minting rules.
  *
  * Identity (design/182 §4.5, additive): a v1 record carries `principal` and nothing else — it stays
@@ -101,9 +112,9 @@ export interface RuleApprovalRecord {
      * bargain, unchanged). `4`: every candidate carries its `behavior` (the settings import now carries
      * the deny/ask lists too) — a `schema: 3` row is stale by the same equality gate.
      */
-    schema: 4;
+    schema: typeof RULE_APPROVAL_RECORD_SCHEMA;
     kind: RuleApprovalKind;
-    state: "pending" | "approved" | "redeemed";
+    state: RuleApprovalState;
     candidates: RuleCandidate[];
     /**
      * The card's OPTION structure over `candidates` (design/375 §4.1). The flat candidate list stays
@@ -504,8 +515,10 @@ export declare function redeemRuleTicket(opts: {
     owner?: RuleOwner;
     deps: RuleConsentDeps;
 }): Promise<RedeemResult>;
+/** The settings layer names, spelled once: {@link ImportedSettingsLayer} is derived from this tuple. */
+export declare const IMPORTED_SETTINGS_LAYERS: readonly ["userSettings", "projectSettings", "localSettings"];
 /** The three user-editable settings layers this version reads. */
-export type ImportedSettingsLayer = "userSettings" | "projectSettings" | "localSettings";
+export type ImportedSettingsLayer = (typeof IMPORTED_SETTINGS_LAYERS)[number];
 /** One layer to read. `root` is the canonical directory a project-layer rule is scoped to — taken from
  *  where the FILE actually lives, since the local layer is not always at a repository root. */
 export interface CcImportLayer {
@@ -528,7 +541,7 @@ export interface ImportPreview {
         reason: string;
     }>;
     /**
-     * ALWAYS EMPTY in this version — a compatibility seat, kept on the wire shape so an existing reader
+     * ALWAYS EMPTY in this version — a compatibility seat (RL-1336-import-translated), kept on the wire shape so an existing reader
      * keeps finding the key (removing a wire field would break readers for no gain).
      *
      * The seat once carried the entries whose MATCH FORM was rewritten on the way in (the space-star

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

@@ -1,14 +1,18 @@
 import { randomBytes } from "node:crypto";
-import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForName, suggestRulesForCommand, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
+import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForName, suggestRulesForCommand, EDITED_RULE_BREADTH_WARNING_CODES, UNCOVERED_SEGMENT_REASONS, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
 import { effectiveOrThrow } from "./permission-rule-provider.js";
 import { errText, isValidConsentScope, landRuleAdd, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
+const isUncoveredSegmentReason = (v) => UNCOVERED_SEGMENT_REASONS.some((word) => v === word);
+export const RULE_APPROVAL_KINDS = Object.freeze(["card", "import", "starter"]);
+export const RULE_APPROVAL_STATES = Object.freeze(["pending", "approved", "redeemed"]);
+export const RULE_APPROVAL_RECORD_SCHEMA = 4;
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
     async get(id) {
         const r = this.rows.get(id);
         if (r === undefined)
             return undefined;
-        if (r.schema !== 4) {
+        if (r.schema !== RULE_APPROVAL_RECORD_SCHEMA) {
             return {
                 staleSchema: true,
                 id: r.id,
@@ -156,7 +160,7 @@ function approvalRecordDamageOf(rec) {
                     if (typeof row !== "object" ||
                         row === null ||
                         typeof row.segment !== "string" ||
-                        (row.reason !== "redirection" && row.reason !== "no_rule_form" && row.reason !== "cap_overflow")) {
+                        !UNCOVERED_SEGMENT_REASONS.some((word) => row.reason === word)) {
                         return `card batch offer ${at} reason row ${ri} is not a segment/reason row from the closed reason set`;
                     }
                 }
@@ -195,7 +199,7 @@ function approvalRecordDamageOf(rec) {
             return "the edited seat is not an object";
         const w = rec.edited.warnings;
         if (w !== undefined) {
-            if (!Array.isArray(w) || w.length !== 1 || (w[0] !== "broad_prefix" && w[0] !== "compound_prefix")) {
+            if (!Array.isArray(w) || w.length !== 1 || !EDITED_RULE_BREADTH_WARNING_CODES.some((code) => w[0] === code)) {
                 return "the edited seat's warnings are not a single-code array from the closed breadth-code set";
             }
         }
@@ -238,7 +242,7 @@ export function ruleOffersOfRecord(rec) {
                     return true;
                 const segment = row.segment;
                 const reason = row.reason;
-                if (typeof segment !== "string" || (reason !== "redirection" && reason !== "no_rule_form" && reason !== "cap_overflow"))
+                if (typeof segment !== "string" || !isUncoveredSegmentReason(reason))
                     return true;
                 detail.push({ segment, reason });
             }
@@ -348,7 +352,7 @@ export async function prepareCardApproval(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 4,
+        schema: RULE_APPROVAL_RECORD_SCHEMA,
         kind: "card",
         state: "pending",
         rev: 0,
@@ -667,6 +671,7 @@ async function applyRedemption(args) {
 function originOfRecordKind(kind) {
     return kind === "import" ? "imported-cc" : kind === "starter" ? "starter" : "user";
 }
+export const IMPORTED_SETTINGS_LAYERS = Object.freeze(["userSettings", "projectSettings", "localSettings"]);
 const IMPORT_UNCOVERED_LAYERS = { flagSettings: "not-imported-v1", policySettings: "not-imported-v1" };
 export async function prepareCcImport(opts) {
     const owner = resolveCallerOwner(opts.principal, opts.owner, "prepareCcImport");
@@ -760,7 +765,7 @@ export async function prepareCcImport(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 4,
+        schema: RULE_APPROVAL_RECORD_SCHEMA,
         kind: "import",
         state: "pending",
         rev: 0,
@@ -794,7 +799,7 @@ export async function prepareStarterBatch(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 4,
+        schema: RULE_APPROVAL_RECORD_SCHEMA,
         kind: "starter",
         state: "pending",
         rev: 0,

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

@@ -15,7 +15,7 @@
  * The two DIRECTIONS read a command differently, on purpose: an allow must cover the WHOLE call
  * ({@link ruleAdmitsCommand} — one recorded yes clears exactly what it spells), while a deny/ask
  * speaks about any PROGRAM RUN the call may perform ({@link programRunReachOf} — whole command or
- * any segment of a chain, read with a real shell lexer, `shell-lexer.ts`, and answering `unreadable`
+ * any segment of a chain, read off the one shell lexer by `shell-run-candidates.ts`, and answering `unreadable`
  * for what it cannot read rather than silence). Precedence across behaviors is the upstream one,
  * deny > ask > allow ({@link RULE_BEHAVIOR_PRECEDENCE}, the one table every adjudication reads).
  *
@@ -161,15 +161,43 @@ export declare function callPathFaceOf(call: ToolCallLike): DenyFace | undefined
  *  it, whatever the call's tool is called (a caller's tool declaring a read path target is on the read face too)? */
 export declare function faceRowsSpeakFor(face: DenyFace | undefined): boolean;
 /**
- * The tools whose rule content NAMES THE VALUE of one parameter instead of a command or a path — the reference's `Skill(<name>)`
- * form, one row per tool: `param` is the argument the rule's content is read against, `params` every scalar argument the tool
- * carries (the parameter spelling `Tool(<param>:<pattern>)` those names used to reach is retired for such a tool, see
- * {@link parseNameRuleContent}). The tool's real schema keys are pinned equal to `params` (test/backlog1318).
+ * The tools whose rule content NAMES THE VALUE of one parameter instead of a command or a path — ONE grammar (the name grammar,
+ * match `name`), one row per tool, the row declaring the tool's SPELLING of it:
+ *  · BARE — the reference's `Skill(<name>)` / `Skill(<prefix>:*)`: `param` is the argument the rule's content is read against,
+ *    `params` every scalar argument the tool carries (the parameter spelling `Tool(<param>:<pattern>)` those names used to reach
+ *    is retired for such a tool, see {@link parseNameRuleContent}). The Skill tool's real schema keys are pinned equal to
+ *    `params` (test/backlog1318).
+ *  · KEYED — `words` present: the reference's `Artifact(action:<word>)`, the content carrying the argument's own key. `params`
+ *    is that one key; `words` is the closed set of values the tool itself declares for it (the row points at the tool's own
+ *    set, never a copy), and a rule names exactly one of them — no prefix form, no `*`.
+ * Whatever the spelling, a rule of this grammar says "the call's value of `param` is this value", read by the one subject
+ * reader ({@link nameRuleSubjectOf}), the one predicate ({@link nameRuleAdmits}), the one precedence walk
+ * ({@link adjudicatePersistedNameRules}) and the one offer ({@link suggestRuleForName}).
  */
 export declare const NAME_RULE_FACES: Readonly<Record<string, {
     readonly param: string;
     readonly params: readonly string[];
+    readonly words?: readonly string[];
 }>>;
+/**
+ * Why a call of a KEYED value tool that names no value for the key cannot be read against that key's deny / ask rules, or
+ * undefined (a bare-spelling tool, or no value tool). Every judge reads a call's arguments as the tool reads them
+ * (`argsAsTheToolReads`: its argument preparation, then the schema's coercions); a call that STILL names no value for the key
+ * runs a value no argument shows — a default filled in inside the tool's execution (a caller's tool mounted under the keyed
+ * name, or answering to it, with no argument preparation of its own). Whether a rule by the key reaches such a call is
+ * unknown, so every reader REFUSES it on the key's deny or ask rule — a refusal, never an ask a person could approve past a
+ * deny, and no allow by the key reaches it. A tool whose reading always names the key (the built-in `Artifact`: an absent
+ * action reads as `publish`) never meets this. A bare-spelling tool's call that names nothing is reached by nothing: no
+ * default stands behind it.
+ */
+export declare function keyedValueAbsentReason(tool: string): string | undefined;
+/**
+ * Does the name grammar read this content of this tool? Every content of a bare-spelling tool; on a keyed tool only content
+ * keyed by its own parameter (`action:…` on `Artifact`) — another key (`Artifact(url:…)`) is a rule on another argument,
+ * which the persisted grammar has no form for and the caller policy reads with its generic parameter lane. Undefined grammar
+ * ⇒ false.
+ */
+export declare function nameGrammarReads(tool: string, content: string): boolean;
 /**
  * The tools whose rule content names the HOST of the URL one parameter carries — the reference's `WebFetch(domain:<host>)`
  * form, one row per tool: `param` is the URL argument the host is read from ({@link domainRuleSubjectOf}). Read by
@@ -182,8 +210,9 @@ export declare const DOMAIN_RULE_FACES: Readonly<Record<string, {
  * Which tools a rule may name — the model's tool set is DERIVED, never a hand-kept list: the command rule word
  * ({@link COMMAND_RULE_TOOL}) takes the COMMAND grammar — the other shell-face tools take none of their own, their command is
  * judged by the `Bash(…)` rules ({@link laneToolNamesOf}); every tool the catalog declares a path target for (Read / Edit / Write /
- * Glob / NotebookEdit / …, `pathTargetOf`) takes the PATH grammar; the tools of {@link NAME_RULE_FACES} take the NAME grammar;
- * the tools of {@link DOMAIN_RULE_FACES} the DOMAIN grammar.
+ * Glob / NotebookEdit / …, `pathTargetOf`) takes the PATH grammar; the tools of {@link NAME_RULE_FACES} take the NAME grammar
+ * (each in its row's spelling: bare `Skill(<name>)`, keyed `Artifact(action:<word>)`); the tools of {@link DOMAIN_RULE_FACES} the
+ * DOMAIN grammar.
  * A rule on any other tool has no content this model can judge and is refused (`unsupported.tool`). The tool set therefore
  * moves with the catalog's declarations, exactly as the protective fences' covered set does.
  */
@@ -206,6 +235,10 @@ export declare function nameRuleSubjectOf(toolName: string, args: unknown): stri
  *  name, as a policy's rule does. Every lane that judges a call by a rule's word reads it here: the policy compiler, the
  *  person's stored rows, the org partition, the allow lists. Empty ⇒ no grammar speaks for the call. */
 export declare function laneToolNamesOf(req: Pick<import("./tool-policy.js").ToolCallRequest, "toolName" | "face">): readonly string[];
+/** The match words a persisted rule is stored with, spelled once: {@link PersistedRuleMatch} is derived from this
+ *  tuple (each form is documented there). A store backend that checks a stored row's `match` reads this value
+ *  rather than keeping its own list. */
+export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "subpath", "path", "name", "name_prefix", "host", "subdomain"];
 /**
  * Match forms, one family per grammar (`prefix` and `wildcard` are one predicate):
  *  · `exact` — admits the one string the rule spells.
@@ -232,7 +265,7 @@ export declare function laneToolNamesOf(req: Pick<import("./tool-policy.js").Too
  *  · `host` / `subdomain` — the DOMAIN grammar ({@link parseDomainRuleContent}): one exact host, or every
  *    host below one domain.
  */
-export type PersistedRuleMatch = "exact" | "prefix" | "wildcard" | "subpath" | "path" | "name" | "name_prefix" | "host" | "subdomain";
+export type PersistedRuleMatch = (typeof PERSISTED_RULE_MATCHES)[number];
 /**
  * Where a rule applies — design/382 §4.1, the THREE consent dimensions.
  *
@@ -277,9 +310,12 @@ export interface RuleDot {
     actor: string;
     counter: number;
 }
+/** The add provenance words, spelled once: {@link RuleAddOrigin} is derived from this tuple, and the sync wire's and
+ *  the session overlay's add checks read it. */
+export declare const RULE_ADD_ORIGINS: readonly ["user", "imported-cc", "starter"];
 /** Where one add came from. Stored PER ADD — never folded across dots (a folded provenance cannot
  *  follow a dot that is later deleted on its own). */
-export type RuleAddOrigin = "user" | "imported-cc" | "starter";
+export type RuleAddOrigin = (typeof RULE_ADD_ORIGINS)[number];
 /** One add of one logical rule, carrying its own dot and its own provenance. */
 export interface RuleAdd {
     dot: RuleDot;
@@ -355,6 +391,21 @@ export interface ParsedRule {
 /** Upper bound on a rule text. Rules are human-authored one-liners; anything longer is a mistake or an
  *  attempt to make the store unreadable. */
 export declare const MAX_RULE_TEXT_CHARS = 512;
+/**
+ * The most code points of a rule's ORIGINAL text a notice's machine-read slot carries: twice the grammar's own bound. A text past
+ * {@link MAX_RULE_TEXT_CHARS} reads as no rule whatever follows its first characters, so the slot keeps room to show it as far as a person
+ * needs to recognise it and no further; every text a rule can be is carried whole. Not exported from the package root: a consumer reads
+ * the slot and never judges its length (it is not a relay that must refuse what the engine did not mint).
+ */
+export declare const NOTICE_RULE_TEXT_MAX: number;
+/**
+ * A rule's (or allow-list entry's) text as a notice's machine-read slot carries it: the original string, untouched, when it is at most
+ * {@link NOTICE_RULE_TEXT_MAX} code points; a longer one is cut to that many and ends in the engine's one truncation mark
+ * ({@link INLINE_TRUNCATION_MARK}), so the longest slot is `NOTICE_RULE_TEXT_MAX + INLINE_TRUNCATION_MARK_CODEPOINTS` (1 025) code points.
+ * The ONE reading both `permission.allowed_tool_not_granted` (`detail.entries[].entry`) and `permission.rule_row_dropped`
+ * (`detail.rows[].rule`) hand their rule text over through — what spells it for a person is the sentence, never this slot.
+ */
+export declare function noticeRuleText(text: string): string;
 /**
  * Interpreter names whose PREFIX form is refused everywhere a rule can enter the store (minting,
  * import, file reload, every backend). `Bash(node:*)` reads as one narrow-looking rule and means "run
@@ -418,7 +469,7 @@ export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
  *
  * Refusing the keyword puts the whole command outside the ALLOW lane, which is the honest answer: no rule
  * can be minted for it and no allow matches it, so it asks. The DENY/ASK direction reads these shapes
- * with its own lexer (`shell-lexer.ts`: a prefixing keyword is stripped so `do curl evil.example` runs
+ * with its run-candidate view (`shell-run-candidates.ts`: a prefixing keyword is stripped so `do curl evil.example` runs
  * `curl`; a `for`/`case` header, whose commands need a syntax tree, is `unreadable` and asks).
  *
  * `!` is here for the same reason with a sharper edge: it is a keyword that PREFIXES a real command, so
@@ -736,11 +787,14 @@ export declare function programRunReachOf(rule: Pick<PersistedRule, "match" | "c
 /** The boolean face of {@link programRunReachOf}: `reached` only. The shadow view and the pins that
  *  assert a reach read this; a lane that must fail closed on `unreadable` reads the outcome. */
 export declare function ruleReachesProgramRun(rule: Pick<PersistedRule, "match" | "command">, command: string): boolean;
+/** The breadth-warning codes, spelled once: {@link EditedRuleBreadthWarning}'s `code` is derived from this tuple,
+ *  and a consent record's `edited.warnings` stores exactly these words (its readback refuses any other). */
+export declare const EDITED_RULE_BREADTH_WARNING_CODES: readonly ["broad_prefix", "compound_prefix"];
 /** design/382 §3.3-5 — one BREADTH note about a rule a person is about to persist: which wide shape
  *  it has, said in words a surface can show beside the input line. A warning is never a refusal —
  *  the closed refusal set is untouched — and never adjudication input. */
 export interface EditedRuleBreadthWarning {
-    readonly code: "broad_prefix" | "compound_prefix";
+    readonly code: (typeof EDITED_RULE_BREADTH_WARNING_CODES)[number];
     /** The baseline sentence (a surface may reword it, never invert it — the same contract as the
      *  §3.5 reason baselines). */
     readonly message: string;
@@ -956,7 +1010,9 @@ export declare function commandCoverageOf(rules: readonly PersistedRule[], call:
 };
 /** The answer of {@link adjudicatePersistedRules}: which behavior decided, and the rule(s) it stands
  *  on — a one-element set for a deny/ask (the first table-order rule of the deciding behavior that
- *  reaches the call) and the allow direction's coverage SET ({@link findAdmittingRule}). */
+ *  reaches the call; for a keyed tool's call naming no value for its key, a DENY standing on the first deny — else ask —
+ *  row of that key, which the call cannot be read against: {@link adjudicatePersistedNameRules}) and the allow
+ *  direction's coverage SET ({@link findAdmittingRule}). */
 export interface PersistedRuleVerdict {
     readonly behavior: RuleBehavior;
     readonly rules: readonly PersistedRule[];
@@ -1032,8 +1088,11 @@ export declare function adjudicatePersistedPathRules(rules: readonly PersistedRu
  * ({@link NAME_RULE_FACES}), judged on the one string the call names (`nameRuleSubjectOf`). A rule of the tool speaks for the call
  * when it is live, of this behavior, in scope ({@link eligiblePersisted}, the one predicate) and {@link nameRuleAdmits} the name; the
  * first behavior in {@link RULE_BEHAVIORS_BY_PRECEDENCE} whose rules speak decides, the first table-order rule of it is the answer.
- * Every behavior is judged with the one predicate — a name has no "program run" the tightening direction could read wider — and
- * there is nothing unreadable: a name is a string.
+ * Every behavior is judged with the one predicate — a name has no "program run" the tightening direction could read wider.
+ * A call that names nothing (read as the tool reads it): on a bare-spelling tool it is reached by no rule; on a KEYED tool it
+ * cannot be read against the key's rules ({@link keyedValueAbsentReason}) and is REFUSED — a deny verdict standing on the
+ * first eligible deny row of the key, else its first ask row (an ask a person could approve would let a deny be approved
+ * past) — and no allow row reaches it.
  */
 export declare function adjudicatePersistedNameRules(rules: readonly PersistedRule[], call: {
     tool: string;
@@ -1138,6 +1197,11 @@ export interface SegmentRuleSuggestion {
      *  show a reader something other than what they authorize. */
     readonly segment: string;
 }
+/** The batch member discriminants as a value: the `kind` words of {@link RuleOfferBatchMember}, both directions
+ *  fenced at compile time ({@link RuleOfferBatchMemberKindsCoverEveryArm} / {@link RuleOfferBatchMemberArmsCoverEveryKind}).
+ *  A consumer applying the degrade arm below (a member whose `kind` is outside this set drops the whole batch offer)
+ *  reads this value rather than keeping its own list. */
+export declare const RULE_OFFER_BATCH_MEMBER_KINDS: readonly ["command", "directoryRead"];
 /**
  * design/382 §2.3 (B3, BREAKING) — one member of a batch offer, a DISCRIMINATED union keyed by
  * `kind`:
@@ -1166,6 +1230,10 @@ export type RuleOfferBatchMember = (SegmentRuleSuggestion & {
     /** The (folded) cd segment this authorization came from — rendering context, never adjudication input. */
     readonly segment: string;
 };
+/** Compile fence: an arm whose `kind` is not in {@link RULE_OFFER_BATCH_MEMBER_KINDS} turns the argument into that word. */
+export type RuleOfferBatchMemberKindsCoverEveryArm = AssertAllKeysHandled<Exclude<RuleOfferBatchMember["kind"], (typeof RULE_OFFER_BATCH_MEMBER_KINDS)[number]>>;
+/** Compile fence, the other direction: a word in {@link RULE_OFFER_BATCH_MEMBER_KINDS} that no arm carries. */
+export type RuleOfferBatchMemberArmsCoverEveryKind = AssertAllKeysHandled<Exclude<(typeof RULE_OFFER_BATCH_MEMBER_KINDS)[number], RuleOfferBatchMember["kind"]>>;
 /**
  * design/375 §3.1 — ONE "don't ask again" option on an approval card. A CLOSED discriminated union
  * (`kind`); consumers parse it per element, and an element whose `kind` they do not know is dropped
@@ -1229,6 +1297,10 @@ export type RuleOffer = {
      */
     readonly uncoveredDetail?: readonly UncoveredSegmentDetail[];
 };
+/** The uncovered-segment reason words, spelled once: {@link UncoveredSegmentDetail}'s `reason` is derived from this
+ *  tuple, {@link UNCOVERED_SEGMENT_REASON_BASELINE} is keyed by it, and a consent record's reason rows are read
+ *  against it. */
+export declare const UNCOVERED_SEGMENT_REASONS: readonly ["redirection", "no_rule_form", "cap_overflow"];
 /** design/382 §3.5 — the closed reason set for one uncovered segment of a batch offer.
  *
  *  · `"redirection"` — the segment carries a shell redirection: refused by discipline (#490 修①,
@@ -1251,7 +1323,7 @@ export interface UncoveredSegmentDetail {
     /** The folded, trimmed segment text — raw post-rewrite command bytes, same contract as
      *  {@link SegmentRuleSuggestion.segment}. */
     readonly segment: string;
-    readonly reason: "redirection" | "no_rule_form" | "cap_overflow";
+    readonly reason: (typeof UNCOVERED_SEGMENT_REASONS)[number];
 }
 /**
  * design/382 §3.5-2 — the BASELINE "why + outlet" sentence per uncovered-segment reason: the

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

@@ -3,13 +3,15 @@ import { shellWordsOf } from "../shell/shell-words.js";
 import { parsePermissionRule } from "./permission-rule-syntax.js";
 import { compileReadDeny } from "../tools/fs/read-deny.js";
 import { carriesShellRedirection, parseLeadingCommandName, splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
-import { inlineUntrusted } from "./untrusted-text.js";
+import { INLINE_TRUNCATION_MARK, inlineUntrusted } from "./untrusted-text.js";
 import { isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
 import { heldValues } from "./tool-name-readings.js";
 import { carriesDotSegment, isAbsoluteForFamily, isIdentityDir, isPathIdentity, isShellRootedSpellingUnmapped, isUncIdentity, pathFamilyOf, pathIdentityOf } from "../tools/fs/safety.js";
 import { bindPathRules, judgeRuleRows, rowsWhereTheyLead } from "./path-rule-binding.js";
-import { readShellCommand } from "./shell-lexer.js";
+import { readShellCommand } from "./shell-run-candidates.js";
 import { lineDescriptorsOfText, readOnlyLineObjection, readOnlyShellVerdict } from "./read-only-shell.js";
+import { ARTIFACT_ACTIONS } from "./artifact-host.js";
+import { ARTIFACT_TOOL_NAME } from "./tool-catalog-entries.js";
 export const RULE_BEHAVIORS = Object.freeze(["deny", "ask", "allow"]);
 const RULE_BEHAVIOR_SET = new Set(RULE_BEHAVIORS);
 export function isRuleBehavior(v) {
@@ -43,7 +45,25 @@ export function faceRowsSpeakFor(face) {
 }
 export const NAME_RULE_FACES = Object.freeze({
     Skill: Object.freeze({ param: "skill", params: Object.freeze(["skill", "args"]) }),
+    [ARTIFACT_TOOL_NAME]: Object.freeze({ param: "action", params: Object.freeze(["action"]), words: ARTIFACT_ACTIONS }),
 });
+function keyedValueParamOf(tool) {
+    const face = Object.hasOwn(NAME_RULE_FACES, tool) ? NAME_RULE_FACES[tool] : undefined;
+    return face?.words !== undefined ? face.param : undefined;
+}
+export function keyedValueAbsentReason(tool) {
+    const key = keyedValueParamOf(tool);
+    return key === undefined ? undefined : `the ${tool} call names no ${key} as the tool reads it, so the ${key} it runs is not one its arguments show — a rule by ${key} cannot be read against it`;
+}
+export function nameGrammarReads(tool, content) {
+    if (ruleToolGrammarOf(tool) !== "name")
+        return false;
+    const key = keyedValueParamOf(tool);
+    if (key === undefined)
+        return true;
+    const colon = content.indexOf(":");
+    return colon > 0 && content.slice(0, colon).trim() === key;
+}
 export const DOMAIN_RULE_FACES = Object.freeze({
     WebFetch: Object.freeze({ param: "url" }),
 });
@@ -91,10 +111,26 @@ function ruleWordOf(name) {
         return COMMAND_RULE_TOOL;
     return ruleToolGrammarOf(name) !== undefined ? name : undefined;
 }
+export const PERSISTED_RULE_MATCHES = Object.freeze(["exact", "prefix", "wildcard", "subpath", "path", "name", "name_prefix", "host", "subdomain"]);
 function isCommandMatch(match) {
     return match === "exact" || match === "prefix" || match === "wildcard";
 }
+export const RULE_ADD_ORIGINS = Object.freeze(["user", "imported-cc", "starter"]);
 export const MAX_RULE_TEXT_CHARS = 512;
+export const NOTICE_RULE_TEXT_MAX = 2 * MAX_RULE_TEXT_CHARS;
+export function noticeRuleText(text) {
+    if (text.length <= NOTICE_RULE_TEXT_MAX)
+        return text;
+    let kept = 0;
+    let end = 0;
+    for (const ch of text) {
+        if (kept === NOTICE_RULE_TEXT_MAX)
+            return `${text.slice(0, end)}${INLINE_TRUNCATION_MARK}`;
+        end += ch.length;
+        kept += 1;
+    }
+    return text;
+}
 export const BARE_INTERPRETER_NAMES = new Set([
     "node", "deno", "bun", "python", "python2", "python3", "perl", "ruby", "php", "osascript",
     "java", "dotnet", "mono", "lua", "luajit", "julia", "Rscript", "tclsh", "groovy", "scala",
@@ -243,6 +279,13 @@ function ruleLaneShapeOf(command, reading) {
 }
 const CONTROL_CHARS_RE = /[\u0000-\u0008\u000A-\u001F\u007F-\u009F\p{Cf}\u2028\u2029]/u;
 const CONTROL_CHARS_GLOBAL_RE = new RegExp(CONTROL_CHARS_RE.source, "gu");
+const RULE_SPELLING_REJECT_BYTES = "<>";
+const RULE_SPELLING_REJECT_RE = new RegExp(`[${RULE_SPELLING_REJECT_BYTES}]`);
+function valueRuleFormsSentence() {
+    return Object.entries(NAME_RULE_FACES)
+        .map(([tool, face]) => (face.words !== undefined ? `${tool}(${face.param}:<${face.param}>) rules` : `${tool}(<${face.param}>) rules`))
+        .join(", ");
+}
 const DISCLOSED_RULE_TEXT_MAX_CHARS = 120;
 export function escapeForDisclosure(value) {
     let text;
@@ -293,13 +336,16 @@ export function parseRuleText(text, behavior) {
     }
     if (parsed.toolName !== COMMAND_RULE_TOOL) {
         const grammar = ruleToolGrammarOf(parsed.toolName);
+        if (grammar === undefined) {
+            return reject("unsupported.tool", `only Bash command rules, rules on path-targeting tools (Read, Edit, Write, …), ${valueRuleFormsSentence()} and WebFetch domain rules have a rule form in this version (got "${parsed.toolName}")`);
+        }
+        if (!tighten && RULE_SPELLING_REJECT_RE.test(parsed.ruleContent)) {
+            return reject("invalid.grammar", `"${text}" carries a shell redirection byte (${[...RULE_SPELLING_REJECT_BYTES].map((b) => `\`${b}\``).join(" or ")}) — no path, name or host allow spells one, and the grant would not read as what it looks like`);
+        }
         if (grammar === "name")
             return parseNameRuleContent(text, parsed.toolName, parsed.ruleContent, behavior);
         if (grammar === "domain")
             return parseDomainRuleContent(text, parsed.toolName, parsed.ruleContent, behavior);
-        if (grammar !== "path") {
-            return reject("unsupported.tool", `only Bash command rules, rules on path-targeting tools (Read, Edit, Write, …), Skill name rules and WebFetch domain rules have a rule form in this version (got "${parsed.toolName}")`);
-        }
         return parsePathRuleContent(text, parsed.toolName, parsed.ruleContent, behavior);
     }
     const content = parsed.ruleContent;
@@ -353,14 +399,18 @@ export function parseRuleText(text, behavior) {
 export function formatRuleText(command, match, tool) {
     if (match === "subpath")
         return `${tool}(//${command.startsWith("/") ? command.slice(1) : command}/**)`;
-    if (match === "path" || match === "name")
+    if (match === "path")
         return `${tool}(${command})`;
+    if (match === "name")
+        return `${tool}(${keyedValueParamOf(tool) !== undefined ? `${keyedValueParamOf(tool)}:` : ""}${command})`;
     if (match === "host" || match === "subdomain")
         return `${tool}(domain:${match === "subdomain" ? "*." : ""}${command})`;
     return `${tool}(${command}${match === "prefix" || match === "name_prefix" ? ":*" : match === "wildcard" ? " *" : ""})`;
 }
 function parseNameRuleContent(text, tool, content, behavior, verifyCanonical = true) {
     const face = NAME_RULE_FACES[tool];
+    if (face?.words !== undefined)
+        return parseKeyedValueRuleContent(text, tool, content, behavior, { param: face.param, words: face.words });
     const bare = content.startsWith("/") ? content.slice(1) : content;
     const colon = bare.indexOf(":");
     if (face !== undefined && colon > 0 && face.params.includes(bare.slice(0, colon).trim())) {
@@ -389,6 +439,24 @@ function parseNameRuleContent(text, tool, content, behavior, verifyCanonical = t
     }
     return { rule };
 }
+function parseKeyedValueRuleContent(text, tool, content, behavior, face) {
+    const vocabulary = face.words.join(", ");
+    const colon = content.indexOf(":");
+    if (colon <= 0 || content.slice(0, colon).trim() !== face.param) {
+        return reject("invalid.grammar", `${tool} rules name the ${face.param}: ${tool}(${face.param}:<${face.param}>) with one of ${vocabulary} ("${text}") — a bare value, or a rule on another argument, has no rule form here`);
+    }
+    const word = content.slice(colon + 1).trim();
+    if (word === "") {
+        return reject("invalid.grammar", `the ${face.param} in "${text}" is empty — ${tool} rules name the ${face.param} exactly as the call carries it`);
+    }
+    if (word.includes("*")) {
+        return reject("unsupported.wildcard", `a \`*\` in the ${face.param} of "${text}" has no rule form — ${tool} rules name one ${face.param} (${vocabulary}); the whole tool is the bare ${tool} entry`);
+    }
+    if (!face.words.includes(word)) {
+        return reject("invalid.grammar", `"${word}" is not one of the ${face.param} values ${tool} declares (${vocabulary}) — the rule would never reach a call`);
+    }
+    return { rule: { behavior, rule: formatRuleText(word, "name", tool), tool, match: "name", command: word } };
+}
 export function nameRuleAdmits(rule, name) {
     if (rule.match === "name")
         return name === rule.command;
@@ -745,6 +813,7 @@ function admitsUnder(rule, command, reading) {
         return false;
     return folded === rule.command || folded.startsWith(rule.command + " ");
 }
+export const EDITED_RULE_BREADTH_WARNING_CODES = Object.freeze(["broad_prefix", "compound_prefix"]);
 export function ruleBreadthWarningsOf(rule) {
     if (rule.match !== "prefix" && rule.match !== "wildcard")
         return [];
@@ -802,7 +871,7 @@ export function directoryIdentityOf(spelling, bases) {
     const r = pathIdentityOf(spelling, pathFamilyOf(bases), bases.root ?? bases.cwd);
     return r.ok ? r.identity : undefined;
 }
-const CD_TARGET_REJECT_CHARS = /[*?[\]{}$`\\'"<>\n\r]/;
+const CD_TARGET_REJECT_CHARS = new RegExp(String.raw `[*?[\]{}$` + "`" + String.raw `\\'"\n\r` + RULE_SPELLING_REJECT_BYTES + "]");
 function cdSegmentDirectoryOf(segment, opts) {
     if (/[^\S \t]/.test(segment))
         return undefined;
@@ -1033,8 +1102,16 @@ export function adjudicatePersistedPathRules(rules, call, views, anchorsOf, lead
     return undefined;
 }
 export function adjudicatePersistedNameRules(rules, call) {
-    if (call.name === undefined)
+    if (call.name === undefined) {
+        if (keyedValueAbsentReason(call.tool) === undefined)
+            return undefined;
+        for (const behavior of ["deny", "ask"]) {
+            const row = rules.find((rule) => rule.match === "name" && eligiblePersisted(rule, call, behavior));
+            if (row !== undefined)
+                return { behavior: "deny", rules: [row] };
+        }
         return undefined;
+    }
     for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
         for (const rule of rules) {
             if (eligiblePersisted(rule, call, behavior) && nameRuleAdmits(rule, call.name))
@@ -1085,6 +1162,8 @@ export function segmentCoverageOf(command, rules, call) {
         };
     });
 }
+export const RULE_OFFER_BATCH_MEMBER_KINDS = Object.freeze(["command", "directoryRead"]);
+export const UNCOVERED_SEGMENT_REASONS = Object.freeze(["redirection", "no_rule_form", "cap_overflow"]);
 export const UNCOVERED_SEGMENT_REASON_BASELINE = {
     redirection: "This part carries a redirection, so it is approved per use — no rule can cover this spelling. If you trust its redirection-free form, a rule can be written for that form (the card's edit row, or settings).",
     no_rule_form: "No rule form exists for this part; it can be approved per use.",