@sema-agent/core 7.55.0 → 7.57.0

package/dist/core/mods/tool-call.js

@@ -0,0 +1,152 @@
+import { formatHookFeedback } from "../reminder-mint.js";
+import { toolFace } from "../tool-catalog-entries.js";
+import { declaredDelegationNameOf } from "../delegation-name.js";
+import { describeThrown } from "../tool-policy.js";
+import { extensionWords } from "../untrusted-egress.js";
+import { ENGINE_ORIGIN } from "./kernel/index.js";
+import { isPlainRecord } from "./kernel/receive.js";
+import { NEXT_IN_FLIGHT } from "./kernel/site-rules.js";
+import { classicEventBase, failedHandlerClause, judgedInputOf } from "./stations.js";
+import { runExtensionCall } from "./extension-call.js";
+import { randomUUID } from "node:crypto";
+const FORM = "tool.call takes next(e), { deny: <reason> } or { result } (a string, or a list of text blocks)";
+const denyOf = (a) => isPlainRecord(a) && Object.keys(a).length === 1 && typeof a["deny"] === "string" && a["deny"] !== "" ? a["deny"] : undefined;
+function substituteOf(a) {
+    if (!isPlainRecord(a) || Object.keys(a).length !== 1 || !Object.hasOwn(a, "result"))
+        return undefined;
+    const r = a["result"];
+    if (typeof r === "string")
+        return [{ type: "text", text: r }];
+    if (!Array.isArray(r) || r.length === 0)
+        return undefined;
+    const out = [];
+    for (const b of r) {
+        if (!isPlainRecord(b) || b["type"] !== "text" || typeof b["text"] !== "string" || Object.keys(b).some((k) => k !== "type" && k !== "text"))
+            return undefined;
+        out.push({ type: "text", text: b["text"] });
+    }
+    return out;
+}
+function viewOf(result) {
+    let blocks = [];
+    try {
+        const content = result.content;
+        blocks = (Array.isArray(content) ? content : []).map((b) => Object.freeze(Object.fromEntries(Object.entries(typeof b === "object" && b !== null ? b : {}).filter(([, v]) => v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean"))));
+    }
+    catch {
+        blocks = [];
+    }
+    return Object.freeze({ result: Object.freeze({ content: Object.freeze([...blocks]), isError: result.isError === true }) });
+}
+function letGoUnasked(occurrences, toolCallId) {
+    const latest = occurrences.get(toolCallId)?.gateRounds.at(-1);
+    if (latest === undefined || latest.disposition.kind !== "allowed" || latest.settlement !== undefined)
+        return false;
+    return latest.disposition.released === undefined && latest.disposition.clearedBy === undefined;
+}
+const RANKS = Object.freeze({ of: (a) => (denyOf(a) !== undefined ? 1 : 0), top: 1 });
+export function createToolCallStation(input) {
+    if (!input.bus.hasHandlers("tool.call"))
+        return undefined;
+    const refusal = (call, by, text) => {
+        if (input.occurrences.get(call.toolCallId) !== undefined) {
+            input.occurrences.refuse(call.toolCallId, "hook");
+            input.occurrences.answeredInPlace(call.toolCallId, by);
+        }
+        input.blockedToolCalls.add(call.toolCallId);
+        return { content: [{ type: "text", text: formatHookFeedback(text, input.reminderMark) }], details: {}, isError: true };
+    };
+    return async (call, run, signal) => {
+        const e = { ...classicEventBase(input.identity), tool: call.toolName, tool_use_id: call.toolCallId, input: judgedInputOf(call.args) };
+        const bodies = new Map();
+        let body;
+        const bottom = async () => {
+            body = run();
+            const result = await body;
+            const view = viewOf(result);
+            bodies.set(view, result);
+            return view;
+        };
+        const checkAnswer = (a, _e, _by, below, ran) => {
+            if (typeof a === "object" && a !== null && bodies.has(a))
+                return undefined;
+            const denied = denyOf(a) !== undefined;
+            if (!denied && substituteOf(a) === undefined)
+                return FORM;
+            if (ran.bottomStarted)
+                return `a ${denied ? "deny" : "result"} after the tool started (once the tool runs, only its own outcome stands)`;
+            if (denied)
+                return below.some((b) => denyOf(b) === undefined) ? "a deny while its next(e) still runs or after it was answered (deny in place of next)" : undefined;
+            if (below.includes(NEXT_IN_FLIGHT))
+                return "a result while its next(e) still runs (result in place of next)";
+            return letGoUnasked(input.occurrences, call.toolCallId) ? undefined : "a result in place of a call someone was asked about (a person's or a rule's yes is a yes to running the tool, so only the tool answers it)";
+        };
+        let outcome;
+        try {
+            outcome = await input.bus.dispatch("tool.call", e, { bottom, checkAnswer, ranks: RANKS, ...(signal !== undefined ? { signal } : {}) });
+        }
+        catch (err) {
+            if (body !== undefined)
+                return body;
+            return refusal(call, ENGINE_ORIGIN.plugin, `the tool.call station could not be raised (${describeThrown(err)}); this call to "${extensionWords(call.toolName, 80)}" was NOT executed (fail-closed)`);
+        }
+        if (outcome.kind === "aborted") {
+            if (body !== undefined)
+                return body;
+            return { content: [{ type: "text", text: "Operation aborted" }], details: {}, isError: true };
+        }
+        if (outcome.kind === "failed") {
+            return refusal(call, outcome.registration, `a tool.call extension ${failedHandlerClause(outcome)} before this call to "${extensionWords(call.toolName, 80)}" ran; the call was NOT executed (fail-closed)`);
+        }
+        const answer = outcome.answer;
+        const ran = typeof answer === "object" && answer !== null ? bodies.get(answer) : undefined;
+        if (ran !== undefined)
+            return ran;
+        const by = outcome.answeredBy ?? ENGINE_ORIGIN.plugin;
+        const reason = denyOf(answer);
+        if (reason !== undefined)
+            return refusal(call, by, `extension "${extensionWords(by, 80)}" refused this call to "${extensionWords(call.toolName, 80)}" before it ran: ${extensionWords(reason, 300)}`);
+        const content = substituteOf(answer);
+        if (content === undefined)
+            return refusal(call, by, `extension "${extensionWords(by, 80)}" answered this call in a form tool.call does not take; the call was NOT executed (fail-closed)`);
+        if (input.occurrences.get(call.toolCallId) !== undefined)
+            input.occurrences.answeredInPlace(call.toolCallId, by);
+        input.blockedToolCalls.add(call.toolCallId);
+        return { content, details: {} };
+    };
+}
+const AGENT_DOOR = "runs the Agent tool: that is $.agent.spawn";
+const OTHER_DOOR = new Map([
+    [toolFace("ask-user-question").contract.contractId, "runs the AskUserQuestion tool, which puts a question to the person: an extension's call does not ask the person"],
+    [toolFace("workflow").contract.contractId, "runs the Workflow tool, whose agents run outside the at-once bound on spawns: $.agent.spawn is the door"],
+]);
+export function createToolCallEntry(input) {
+    return async (args, ctx) => {
+        const by = ctx.origin.plugin;
+        const { tool, ...callInput } = args;
+        if (typeof tool !== "string" || tool === "")
+            throw new TypeError(`${by}: $.tool.call takes the event's input: { tool, ...args }`);
+        const toolCallId = `ext-${randomUUID()}`;
+        return runExtensionCall(input.bus, toolCallId, ctx, async (call) => {
+            const finalized = await input.harness.callTool({ type: "toolCall", id: toolCallId, name: tool, arguments: { ...callInput } }, ctx.signal, (t) => {
+                const contractId = input.faceOf(t.name)?.contractId;
+                const door = declaredDelegationNameOf(input.specOf(t.name)) !== undefined ? AGENT_DOOR : contractId !== undefined ? OTHER_DOOR.get(contractId) : undefined;
+                if (door !== undefined)
+                    throw new TypeError(`${by}: $.tool.call(${extensionWords(t.name, 80)}) ${door}`);
+            });
+            if (call.denied)
+                return Object.freeze({ deny: textOf(finalized.result.content) });
+            return viewOf({ ...finalized.result, isError: finalized.isError });
+        });
+    };
+}
+export function extensionCallOverlap(input) {
+    const others = input.occurrences.live().filter((o) => o.toolCallId !== input.toolCallId);
+    const name = extensionWords(input.toolName, 80);
+    if (!input.batchSafe(input.toolName, input.args)) {
+        return others.length === 0 ? undefined : `${name}: an extension's call of a tool that has the run to itself cannot run while another call is in flight`;
+    }
+    const exclusive = others.find((o) => o.life === "released" && !input.batchSafe(o.wireName ?? o.spelledName, o.finalInput ?? o.args));
+    return exclusive === undefined ? undefined : `${name}: an extension's call cannot run beside "${extensionWords(exclusive.wireName ?? exclusive.spelledName, 80)}", which has the run to itself`;
+}
+const textOf = (content) => (Array.isArray(content) ? content.map((b) => (isPlainRecord(b) && b["type"] === "text" && typeof b["text"] === "string" ? b["text"] : "")).join("") : "");

package/dist/core/namespaced-rule-name.d.ts

@@ -1,9 +1,10 @@
 /**
- * The name matchers of the rule grammar and of a sub-agent's tool-name lists: the linear `*` glob and the protocol-namespace covering forms
- * (`<ns>__<peer>`, `<ns>__<peer>__*`, `<ns>__<peer>__get_*`). A leaf module — the allow layer's rule model and the sub-agent list reader both import it,
- * so neither needs the other's dependency tree.
+ * The name matchers of the rule grammar and of a run's tool-name lists: the linear `*` glob and the covering forms of a tool name —
+ * a glob over the whole name (`Re*d`, `mcp__*`, the lone `*`; read by a list that restricts) and the protocol-namespace peer
+ * (`<ns>__<peer>`). A leaf module — the allow layer's rule model and the run's list reader both import it, so neither needs the
+ * other's dependency tree.
  */
-import type { ProtocolId } from "./protocol-table.js";
+import type { ProtocolNamespace } from "./protocol-table.js";
 import type { RuleBehavior } from "./permission-rule-model.js";
 /**
  * `*` glob match (design/127 M6: NOT a RegExp — patterns may come from tenant-supplied Settings layers; the same semantics as
@@ -18,38 +19,31 @@ import type { RuleBehavior } from "./permission-rule-model.js";
  */
 export declare function wildcardMatch(pattern: string, value: string): boolean;
 /**
- * Does a namespaced RULE name cover `toolName`? — the tail branch of CC's rule matcher `VRp`
- * (:595780), which is UNCONDITIONAL there (its `globMatching` option gates only the whole-name glob
- * branch, so CC's allow lane — `mVo` :595803, which passes no options — matches MCP segments too).
- * Three covering forms, matching CC's three disjuncts (`<ns>` = any protocol-table prefix):
- *   · `<ns>__<peer>`           — every tool of that peer (rule tool segment absent);
- *   · `<ns>__<peer>__*`        — the same set, spelled with the star CC's own settings validator
- *                                recommends (`"MCP rules do not support patterns in parentheses …
- *                                use mcp__srv__*"`);
- *   · `<ns>__<peer>__get_*`    — a glob over the tool segment;
- *   · `<ns>__*` / `<ns>__*__*` — every tool of the namespace, in the lists that restrict only: CC's deny and ask rules
- *                                reach it through the whole-name glob (`globMatching`), and its agent denied-tools set
- *                                reads both spellings as every server.
- * A LITERAL tool segment is deliberately NOT covered here: it is an exact tool name, and the exact
- * table already answers it — the same split CC makes with its leading `ruleName === toolName`.
- *
- * Rule and target must be in the SAME namespace, and peer segments compare EXACTLY (CC
- * `s.serverName === a.serverName`). A rule must therefore spell the peer the way the mint does; that
- * is the same string an operator reads off any mounted tool name, and inventing a fuzzier comparison
- * here would let one rule reach a peer — or a protocol — it does not name. The one peer spelling that
- * is not a peer is the wildcard of the whole-protocol name (`<ns>__*`, `<ns>__*__*`, {@link wholeProtocolOf}):
- * every tool of the namespace. This matcher does not know whose list a name was written in — a caller
- * asks {@link isNamespacedCoveringRuleName} with the list's behavior first and matches only what it admits.
+ * True ⇔ this rule name reaches a SET of tool names rather than one exact name — the shapes {@link ruleNameCovers} answers and an
+ * exact-name table cannot hold — on a list of `behavior`. Every lane that keys entries by exact tool name asks it to know which
+ * entries it must NOT key that way. Two shapes:
+ *   · a `*` in the name — on a list that RESTRICTS (`deny`, `ask`; {@link readsNameGlob}) anywhere in it (`Re*d`, `mcp__*`, `*`);
+ *     on a list that GRANTS only in the tool segment after a literal `<ns>__<peer>__` (`mcp__srv__*`, `mcp__srv__get_*`): any other
+ *     `*` names no scope an allow widens ({@link grantWildcardRefusalOf}), so it is no covering name there — the readers refuse it;
+ *   · a protocol peer with no tool segment (`<ns>__<peer>`): every tool of that peer, in every list.
+ * `behavior` = the behavior of the list the name is written in — required: a list's `*` has no reading without it, so a value
+ * that is no behavior word (an array index handed by `filter`, say) is refused loudly, never read as either list.
  */
-export declare function namespacedRuleNameCovers(ruleName: string, toolName: string): boolean;
-/** How far a rule name reaches into the peer `peer` of protocol `ns`: `"all"` — every tool of it (`<ns>__<peer>`,
- *  `<ns>__<peer>__*`, or the whole-protocol name); `"some"` — it names tools of that peer (an exact name, a glob over the tool
- *  segment); `"none"` — it names no tool of it. The one reading of a name against a peer that the tool-name lists take. */
-export declare function namespacedRuleReachInto(ruleName: string, ns: ProtocolId, peer: string): "all" | "some" | "none";
-/** True ⇔ this rule name is a namespaced name whose reach is a SET of tools rather than one exact tool
- *  — i.e. the shapes {@link namespacedRuleNameCovers} answers and an exact name table cannot. Every
- *  lane that keys rules by exact tool name needs this to know which entries it must NOT key that way.
- *  `behavior` = the behavior of the list the name is written in: the whole-protocol name is a covering name for a
- *  restricting list (`deny`, `ask`) only — given `allow`, or no behavior, it is not one (it names no peer). A wildcard in
- *  any other peer segment is a covering name in no list. */
-export declare function isNamespacedCoveringRuleName(name: string, behavior?: RuleBehavior): boolean;
+export declare function isCoveringRuleName(name: string, behavior: RuleBehavior): boolean;
+/**
+ * Does a covering rule name ({@link isCoveringRuleName}) cover `toolName`? A name with a `*` is a glob over the WHOLE name
+ * ({@link wildcardMatch} — the reference's `p` matcher): `mcp__srv__get_*` reaches `mcp__srv__get_issue`, `mcp__*` every MCP tool,
+ * `*` every tool. A protocol peer (`<ns>__<peer>`) reaches every tool minted under that peer, in the SAME namespace, the peer
+ * compared EXACTLY (CC `s.serverName === a.serverName`): a rule spells the peer the way the mint does. A literal name is an exact
+ * tool name, not a covering one — the exact tables answer it. This matcher does not know whose list a name was written in: a caller
+ * asks {@link isCoveringRuleName} with the list's behavior first and matches only what it admits.
+ */
+export declare function ruleNameCovers(ruleName: string, toolName: string): boolean;
+/**
+ * How far a covering rule name reaches into the peer `peer` of namespace `ns`: `"all"` — every tool of it; `"some"` — some tools of
+ * it (a glob over that peer's tool segment); `"none"` — none of it, as far as a list that dials peers needs to know. A glob reaches
+ * EVERY tool of the peer exactly when it ends in `*` and matches the peer's own prefix (`<ns>__<peer>__`): a prefix of every name
+ * minted under the peer is then matched by the glob up to its last `*`, which takes the rest; a glob that does not end in `*` leaves
+ * a tool name it does not match. The one reading of a name against a peer that the tool-name lists take.
+ */
+export declare function ruleNameReachIntoPeer(ruleName: string, ns: ProtocolNamespace, peer: string): "all" | "some" | "none";

package/dist/core/namespaced-rule-name.js

@@ -1,4 +1,4 @@
-import { readsWholeProtocol, splitNamespacedName, wholeProtocolOf } from "./tool-name-aliases.js";
+import { grantWildcardRefusalOf, readsNameGlob, splitNamespacedName } from "./tool-name-aliases.js";
 export function wildcardMatch(pattern, value) {
     const first = pattern.indexOf("*");
     if (first < 0)
@@ -23,44 +23,37 @@ export function wildcardMatch(pattern, value) {
     }
     return true;
 }
-function parseNamespacedRuleName(name) {
+function namespacedPeerOf(name) {
     const split = splitNamespacedName(name);
-    if (split === undefined || split.peer === "")
-        return undefined;
-    return split.tool !== undefined ? { protocol: split.ns.id, peer: split.peer, tool: split.tool } : { protocol: split.ns.id, peer: split.peer };
+    return split === undefined || split.peer === "" ? undefined : split;
 }
-export function namespacedRuleNameCovers(ruleName, toolName) {
-    const rule = parseNamespacedRuleName(ruleName);
-    if (rule === undefined)
-        return false;
-    const target = parseNamespacedRuleName(toolName);
-    if (target === undefined)
-        return false;
-    if (rule.protocol !== target.protocol)
-        return false;
-    if (wholeProtocolOf(ruleName) !== undefined)
-        return true;
-    if (rule.peer !== target.peer)
+export function isCoveringRuleName(name, behavior) {
+    if (behavior !== "deny" && behavior !== "ask" && behavior !== "allow") {
+        throw new TypeError(`isCoveringRuleName: the list's behavior must be "deny", "ask" or "allow" (got ${typeof behavior === "string" ? JSON.stringify(behavior) : typeof behavior}) — a "*" in a name reads one way on a list that restricts and another on one that grants`);
+    }
+    if (name.includes("*"))
+        return readsNameGlob(behavior) || grantWildcardRefusalOf(name) === undefined;
+    const peer = namespacedPeerOf(name);
+    return peer !== undefined && peer.tool === undefined;
+}
+export function ruleNameCovers(ruleName, toolName) {
+    if (ruleName.includes("*"))
+        return wildcardMatch(ruleName, toolName);
+    const rule = namespacedPeerOf(ruleName);
+    if (rule === undefined || rule.tool !== undefined)
         return false;
-    if (rule.tool === undefined || rule.tool === "*")
-        return true;
-    return target.tool !== undefined && rule.tool.includes("*") && wildcardMatch(rule.tool, target.tool);
+    const target = namespacedPeerOf(toolName);
+    return target !== undefined && target.ns.id === rule.ns.id && target.peer === rule.peer;
 }
-export function namespacedRuleReachInto(ruleName, ns, peer) {
-    const rule = parseNamespacedRuleName(ruleName);
-    if (rule === undefined || rule.protocol !== ns)
-        return "none";
-    if (wholeProtocolOf(ruleName) !== undefined)
-        return "all";
-    if (rule.peer !== peer)
+export function ruleNameReachIntoPeer(ruleName, ns, peer) {
+    if (ruleName.includes("*")) {
+        if (ruleName.endsWith("*") && wildcardMatch(ruleName, `${ns.prefix}${peer}__`))
+            return "all";
+        const rule = namespacedPeerOf(ruleName);
+        return rule !== undefined && rule.ns.id === ns.id && rule.peer === peer ? "some" : "none";
+    }
+    const rule = namespacedPeerOf(ruleName);
+    if (rule === undefined || rule.ns.id !== ns.id || rule.peer !== peer)
         return "none";
-    return rule.tool === undefined || rule.tool === "*" ? "all" : "some";
-}
-export function isNamespacedCoveringRuleName(name, behavior) {
-    const parsed = parseNamespacedRuleName(name);
-    if (parsed === undefined)
-        return false;
-    if (parsed.peer.includes("*"))
-        return wholeProtocolOf(name) !== undefined && readsWholeProtocol(behavior);
-    return parsed.tool === undefined || parsed.tool.includes("*");
+    return rule.tool === undefined ? "all" : "some";
 }

package/dist/core/parent-spec-seat.d.ts

@@ -14,7 +14,7 @@ import type { EngineDollar } from "./mods/dollar.js";
 import type { ToolExecuteContext } from "./tool-spec.js";
 import type { TaskSpec } from "./types.js";
 /** The fields of a spec the seat carries — one `Pick`, shared by the mint's input and the apply's target. */
-export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "mods" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "memory" | "compaction" | "skillListingBudgetFraction" | "skillListingMaxDescChars" | "fileHistory" | "projectMemory" | "promptForm" | "promptBinding" | "advisorModel">;
+export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "mods" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "memory" | "compaction" | "skillListingBudgetFraction" | "skillListingMaxDescChars" | "fileHistory" | "projectMemory" | "promptForm" | "promptBinding" | "advisorModel" | "attachments">;
 /**
  * The seat a run hands its children. Every member is the parent's own value, frozen at mint (arrays copied and
  * frozen; the facts object copied). Members present iff the parent carries them — an absent member is "nothing to
@@ -60,6 +60,10 @@ export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "cli
  *  · `advisorModel` — the person's advisor setting: every engine-built child judges it against its OWN model (an advisor
  *    weaker than the child's model does not attach there). An ORDINARY member (fill law); the observer sidecar takes it and
  *    excludes the tool by name.
+ *  · `attachments` — the request's attachment-lane declaration, WHOLE (which frames ride the legs' requests and which are
+ *    switched off): one declaration for the delegation tree, so a lane the parent turned on or off is on or off for the
+ *    delegates that work for it. An ORDINARY member (fill law): a child that authors `attachments` at all keeps exactly what it
+ *    authored, never half to the parent.
  */
 export interface ParentSpecSeat {
     readonly principal?: string;
@@ -82,6 +86,7 @@ export interface ParentSpecSeat {
     readonly promptForm?: "minimal";
     readonly promptBinding?: string;
     readonly advisorModel?: TaskSpec["advisorModel"];
+    readonly attachments?: TaskSpec["attachments"];
 }
 /** Refuse (by name, `config.deps_retired_key`) a seat that still carries a retired member. Read at every door a seat enters
  *  by hand: the ctx reader, the apply, and the send lane's waker clamps. */

package/dist/core/parent-spec-seat.js

@@ -26,6 +26,7 @@ export function parentSpecSeatOf(spec, frozenOnQuestion) {
         ...(spec.promptForm !== undefined ? { promptForm: spec.promptForm } : {}),
         ...(spec.promptBinding !== undefined ? { promptBinding: spec.promptBinding } : {}),
         ...(spec.advisorModel !== undefined ? { advisorModel: spec.advisorModel } : {}),
+        ...(spec.attachments !== undefined ? { attachments: Object.freeze({ ...spec.attachments }) } : {}),
         ...clampFieldSeatsOf(spec),
     });
 }
@@ -51,6 +52,7 @@ export function applyParentSpecSeat(child, seat) {
         ...fill("promptForm", seat.promptForm),
         ...fill("promptBinding", seat.promptBinding),
         ...fill("advisorModel", seat.advisorModel),
+        ...fill("attachments", (seat.attachments !== undefined ? { ...seat.attachments } : undefined)),
         ...(seat.oneShot === true ? { oneShot: true } : {}),
         ...(seat.memoryPersistenceCapable === false ? { memoryPersistenceCapable: false } : fill("memoryPersistenceCapable", seat.memoryPersistenceCapable)),
     };

package/dist/core/park-selfcheck.js

@@ -80,6 +80,9 @@ function syntheticCheckpoint(scope, fidelity) {
             origin: "denial_limit_fallback",
             askClass: "denial_limit_fallback",
             classes: ["denial_limit_fallback"],
+            engineMounted: true,
+            targets: { protective: "/park-selfcheck/target", declared: null },
+            targetReads: { ["0".repeat(64)]: "f".repeat(64) },
             batchToolCallIds: [`${scope}:call`],
             completedCallIds: [],
         },

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

@@ -29,6 +29,7 @@
  */
 import { RULE_OFFER_KINDS, type EditedRuleBreadthWarning, type UncoveredSegmentDetail, type RuleBehavior, type RuleOffer, type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
 import { type RuleOwner } from "./rule-owner.js";
+import type { RuleOfferShapeProblem } from "./rule-offer-read.js";
 import type { AssertAllKeysHandled } from "./ask-origin.js";
 import { type PermissionRuleStoreProvider } from "./permission-rule-provider.js";
 /** One candidate rule inside an approval record: what it says (`behavior`), the exact text and where it
@@ -90,6 +91,24 @@ export type RuleOffer2 = {
 export type RuleOffer2KindsCoverEveryArm = AssertAllKeysHandled<Exclude<RuleOffer2["kind"], (typeof RULE_OFFER_KINDS)[number]>>;
 /** {@link import("./permission-rule-model.js").RuleOfferArmsCoverEveryKind}'s twin over the record's option form. */
 export type RuleOffer2ArmsCoverEveryKind = AssertAllKeysHandled<Exclude<(typeof RULE_OFFER_KINDS)[number], RuleOffer2["kind"]>>;
+/** {@link readRuleOffer2}'s answer: the option as read, or why it is not one (the offer read-back judge's two element words). */
+export type RuleOffer2Reading = {
+    readonly offer: RuleOffer2;
+} | {
+    readonly problem: Exclude<RuleOfferShapeProblem, "not_an_array">;
+};
+/**
+ * The one SHAPE reading of a stored record option ({@link RuleOffer2}), for every reader of an approval record the engine did not
+ * just build — the consent entries' record check, and a durable backend reading its rows back. Not a plain record, a member the form
+ * does not declare, a candidate index that is not a non-negative safe integer, a batch with no members, a `segments` that is not a
+ * list of strings, an uncovered count that is not a non-negative safe integer, a reason row that is not exactly a segment and a reason
+ * ⇒ `malformed`; a `kind` or a reason that is a string outside its closed set ⇒ `unknown_word`. A member the form does not declare is
+ * refused, not dropped: the record's `schema` stamp is the version gate, so a same-stamp row carrying one was written by another writer.
+ * Which batch seats a record of which kind must carry, and whether the indices name its candidates, are the record's own facts —
+ * judged by the record check, not here. The answer is a fresh object holding the members it judged; each member is read once, a list
+ * by position with its length read once.
+ */
+export declare function readRuleOffer2(raw: unknown): RuleOffer2Reading;
 /** 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. */
@@ -298,11 +317,13 @@ export declare function prepareCardApproval(opts: {
     principal?: string;
     /** design/182 §4.5 (additive): the structural owner — only the local-owner path needs it. */
     owner?: RuleOwner;
-    /** The tool whose ask this card belongs to. Only the shell tool the rule lane speaks for, the name tools (the skill-activation
-     *  card) and the host tools (the fetch card) are accepted. */
+    /** The tool whose ask this card belongs to: a tool whose card the offer factory mints a rule on (`cardRuleFormOf`) — the shell
+     *  tool, a name tool (the skill-activation card), a host tool (the fetch card), a tool with no rule grammar (the whole-tool card).
+     *  Any other tool (a path tool, a shell-face sibling) draws no card. */
     toolName: string;
     /** The command as adjudicated — the same bytes the ask carried; for a name tool (`Skill`), the name its call carried (`args.skill`);
-     *  for a host tool (`WebFetch`), the host its call reaches (the offer's `command`). */
+     *  for a host tool (`WebFetch`), the host its call reaches (the offer's `command`); for a tool with no rule grammar, `""` (the
+     *  offer's `command`: the whole tool binds no value). */
     command: string;
     /** The ask's call id and argument digest, recorded for reconciliation. */
     toolCallId?: string;