@sema-agent/core 7.54.1 → 7.55.0

package/dist/core/tool-policy.js

@@ -20,6 +20,8 @@ import { assertNoRetiredKeys, assertNoRetiredToolPolicyKeys, RETIRED_DECISION_ME
 import { DECISION_MEMBER_ARMS, isEngineRefusal, nestedRecordsOf, receiveContract, receiveNestedRecords, refusedOutOfContract, screenContractValues } from "./decision-receipt.js";
 export { isEngineRefusal } from "./decision-receipt.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "./permission-rules.js";
+import { ruleContentOf } from "./permission-rule-model.js";
+import { wildcardPeerRefusalOf } from "./tool-name-aliases.js";
 import { ruleSpellingOf } from "./permission-rule-syntax.js";
 import { protocolOf } from "./protocol-table.js";
 import { anchorSpelling, isAbsoluteForFamily, normalizeAbsPathLexically, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
@@ -194,8 +196,18 @@ export function toolPolicyWriteGuardRows(policies) {
         return undefined;
     return async (at) => (await Promise.all(sources.map((rowsOf) => rowsOf(at)))).flat();
 }
-export function namespacedCoveringEntries(entries) {
-    return (entries ?? []).filter(isNamespacedCoveringRuleName);
+export function namespacedCoveringEntries(entries, behavior) {
+    return (entries ?? []).filter((entry) => isNamespacedCoveringRuleName(entry, behavior));
+}
+function allowlistNameRefusal(who, entry, list) {
+    if (typeof entry !== "string")
+        return undefined;
+    const sentence = wildcardPeerRefusalOf(ruleSpellingOf(entry)?.toolName ?? entry, "allow");
+    if (sentence === undefined)
+        return undefined;
+    const e = new Error(`${who}: ${list} entry "${entry}" — ${sentence}`);
+    e.code = "config.invalid_tool_name_set";
+    return e;
 }
 export function namespacedCoveringHit(covering, call) {
     return covering.length > 0 && nameListHolds({ has: (name) => covering.some((e) => namespacedRuleNameCovers(e, name)) }, call);
@@ -207,13 +219,13 @@ export function checkToolPolicyProjection(projection, req) {
     const listed = (list) => heldBy("policy.projectionReplay", { has: (n) => list.includes(n) }, req);
     for (const c of projection.components) {
         if (c.kind === "tool_deny") {
-            if (listed(c.names) || namespacedCoveringHit(namespacedCoveringEntries(c.names), req)) {
+            if (listed(c.names) || namespacedCoveringHit(namespacedCoveringEntries(c.names, "deny"), req)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by a frozen inherited policy projection` };
             }
             continue;
         }
         if (c.kind === "tool_allowlist") {
-            if (!listed(c.names) && !namespacedCoveringHit(namespacedCoveringEntries(c.names), req)) {
+            if (!listed(c.names) && !namespacedCoveringHit(namespacedCoveringEntries(c.names, "allow"), req)) {
                 return { action: "deny", message: `tool "${req.toolName}" is not in a frozen inherited policy projection's allowlist` };
             }
             continue;
@@ -403,13 +415,18 @@ export function createAllowDenyPolicy(opts) {
                 invalid.push({ entry, list, message: `"${entry}" is ${lesson}`, lesson });
                 continue;
             }
-            if (spelled.ruleContent === undefined) {
+            if (ruleContentOf(spelled) === undefined) {
                 if (spelled.toolName === "*" && list === "deny") {
                     const lesson = `the wildcard — \`*\` names no tool, and a deny entry reaches the tool it names, so this one would be kept and never match ` +
                         `(a deny that reads protective and denies nothing). Name the tools to deny; to leave a run no tools, write an empty allow list.`;
                     invalid.push({ entry, list, message: `"${entry}" is ${lesson}`, lesson });
                     continue;
                 }
+                const wild = list === "allow" ? wildcardPeerRefusalOf(spelled.toolName, "allow") : undefined;
+                if (wild !== undefined) {
+                    invalid.push({ entry, list, message: `"${entry}": ${wild}`, lesson: wild });
+                    continue;
+                }
                 if (!seen.has(spelled.toolName)) {
                     seen.add(spelled.toolName);
                     kept.push(spelled.toolName);
@@ -448,8 +465,8 @@ export function createAllowDenyPolicy(opts) {
     opts = { ...opts, ...(screenedAllow ? { allow: screenedAllow } : {}), ...(screenedDeny ? { deny: screenedDeny } : {}) };
     const allow = opts.allow ? new Set(opts.allow) : undefined;
     const deny = new Set(opts.deny ?? []);
-    const denyCovering = namespacedCoveringEntries(opts.deny);
-    const allowCovering = namespacedCoveringEntries(opts.allow);
+    const denyCovering = namespacedCoveringEntries(opts.deny, "deny");
+    const allowCovering = namespacedCoveringEntries(opts.allow, "allow");
     return {
         projection: {
             components: [
@@ -480,12 +497,19 @@ export function createApprovalPolicy(opts) {
     if (opts.approvalTimeoutMs !== undefined && opts.approvalTimeoutMs > 2_147_483_647) {
         throw new Error(`createApprovalPolicy: approvalTimeoutMs must not exceed 2147483647ms (~24.8 days) (got ${opts.approvalTimeoutMs}) — a host timer truncates a larger delay and fires immediately, denying every request at once; omit it to wait indefinitely`);
     }
+    for (const [list, entries] of [["autoAllow", opts.autoAllow ?? []], ["requireApproval", opts.denyByDefault === true ? opts.requireApproval : []]]) {
+        for (const entry of entries) {
+            const refusal = allowlistNameRefusal("createApprovalPolicy", entry, list);
+            if (refusal !== undefined)
+                throw refusal;
+        }
+    }
     const need = new Set(opts.requireApproval);
     const deny = new Set(opts.deny ?? []);
     const auto = new Set(opts.autoAllow ?? []);
-    const needCovering = namespacedCoveringEntries(opts.requireApproval);
-    const denyCovering = namespacedCoveringEntries(opts.deny);
-    const autoCovering = namespacedCoveringEntries(opts.autoAllow);
+    const needCovering = namespacedCoveringEntries(opts.requireApproval, "ask");
+    const denyCovering = namespacedCoveringEntries(opts.deny, "deny");
+    const autoCovering = namespacedCoveringEntries(opts.autoAllow, "allow");
     return {
         projection: {
             components: [

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

@@ -10,7 +10,7 @@
  *
  * Layer-0 vocabulary: depends on the leaf catalog and the face vocabulary only.
  */
-import { type ToolCallPathTarget, type ToolCatalogEntry, type ToolFamily, type ToolMountTag, type ToolPathAccess } from "./tool-face.js";
+import { type ToolCallPathTarget, type ToolCatalogEntry, type ToolFamily, type ToolHostTarget, type ToolMountTag, type ToolPathAccess } from "./tool-face.js";
 /** The whole static catalog, one frozen row per definition (design/388 §2.1 `describeToolCatalog()`).
  *  Replaces the retired name-keyed exports `HAND_TOOL_EFFECTS` / `DEFAULT_BUDGET_EXEMPT_TOOLS` /
  *  `COMPACTABLE_TOOLS`: filter this instead (`e.mountedBy.includes("hands")`, `e.face.budgetExempt`,
@@ -68,6 +68,8 @@ export declare function rosterCanPersistMemory(tools: ReadonlyArray<PersistenceP
 export declare function persistenceCandidateToolNames(): 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>;
+/** Every definition that names a host target (the URL its call reaches): the names a host rule is written for. */
+export declare function hostTargetingToolNames(): 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
@@ -117,6 +119,7 @@ export interface ToolCallLike {
     args: unknown;
     face?: {
         pathTarget?: ToolCallPathTarget;
+        hostTarget?: ToolHostTarget;
         names?: readonly string[];
     } | undefined;
 }
@@ -165,13 +168,17 @@ export declare function isDeclaredWrite(call: ToolCallLike): boolean;
  *  records nothing (retired spellings in persisted transcripts read the frozen history table at the call site). */
 export declare function fileOpAccessOf(name: string): ToolPathAccess | undefined;
 export declare function pathTargetOf(name: string): ToolCatalogEntry["face"]["pathTarget"];
+/** The host target a wire name's catalog definition declares (the URL slot a host rule of that name is read on), the
+ *  {@link pathTargetOf} of the host face: the first definition under the name that declares one. */
+export declare function hostTargetOf(name: string): ToolCatalogEntry["face"]["hostTarget"];
 /**
- * The rule vocabulary of a wire name from the STATIC catalog: `primaryParams` = the declared primaries, else
- * the path target's `param` + aliases; `params` = the declared vocabulary, else the path target's names —
- * and UNDEFINED when the catalog cannot know the full vocabulary (a definition whose schema is built inside
- * its factory and declares no `ruleFace.params`): the static half never claims a vocabulary it has not
- * read, so the rule compiler judges only what it knows and the leg's roster (which reads the schema)
- * judges the rest. `undefined` as a whole for a name with nothing to say.
+ * The rule vocabulary of a wire name from the STATIC catalog, over every definition the name (or an alias) answers to:
+ * `primaryParams` = the first definition's declared primaries, else its path target's `param` + aliases; `params` = every
+ * definition's declared vocabulary, else its path target's names, primaries included — UNDEFINED when no definition
+ * under the name declares one (StructuredOutput: its schema is each task's), whose face then names no parameter at all.
+ * A definition whose schema is built inside its factory declares its FULLEST mount's vocabulary; a mounted instance's
+ * is the roster's, read off the schema it carries (`ruleFaceOfInstance`). `undefined` as a whole for a name the
+ * catalog does not carry.
  */
 export declare function catalogRuleFaceOf(name: string): {
     primaryParams: string[];

package/dist/core/tool-registry.js

@@ -55,6 +55,9 @@ export function persistenceCandidateToolNames() {
 export function pathTargetingToolNames() {
     return names((e) => e.face.pathTarget !== undefined);
 }
+export function hostTargetingToolNames() {
+    return names((e) => e.face.hostTarget !== undefined);
+}
 const onShellFace = (e) => e.face.ruleFace?.grammar === "command";
 export function shellFaceToolNames() {
     return names(onShellFace);
@@ -125,18 +128,25 @@ export function pathTargetOf(name) {
             return e.face.pathTarget;
     return undefined;
 }
+export function hostTargetOf(name) {
+    for (const e of TOOL_CATALOG_ENTRIES)
+        if (e.name === name && e.face.hostTarget !== undefined)
+            return e.face.hostTarget;
+    return undefined;
+}
 export function catalogRuleFaceOf(name) {
+    let face;
     for (const e of TOOL_CATALOG_ENTRIES) {
-        if (e.name !== name)
+        if (e.name !== name && !(e.face.aliases ?? []).includes(name))
             continue;
         const pt = e.face.pathTarget;
-        const primary = e.face.ruleFace?.primaryParams ?? (pt !== undefined ? [pt.param, ...(pt.aliases ?? [])] : []);
-        const params = e.face.ruleFace?.params ?? (pt !== undefined ? [pt.param, ...(pt.aliases ?? [])] : undefined);
-        if (params === undefined && primary.length === 0)
-            continue;
-        return { primaryParams: [...primary], ...(params !== undefined ? { params: [...new Set([...params, ...primary])] } : {}) };
+        const target = pt !== undefined ? [pt.param, ...(pt.aliases ?? [])] : undefined;
+        const primary = e.face.ruleFace?.primaryParams ?? target ?? [];
+        const declared = e.face.ruleFace?.params ?? target;
+        const params = declared === undefined ? face?.params : [...new Set([...(face?.params ?? []), ...declared, ...primary])];
+        face = { primaryParams: face?.primaryParams ?? [...primary], ...(params !== undefined ? { params } : {}) };
     }
-    return undefined;
+    return face;
 }
 export function handBandEffects() {
     const out = new Map();

package/dist/core/tool-result-store.js

@@ -4,7 +4,7 @@ import { uuidv7 } from "../engine/session/uuid.js";
 import { defineTool, errorResult } from "./tools.js";
 import { deliverEngineNotice } from "./types.js";
 import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
-import { toolFace } from "./tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
 import { thrownText } from "./thrown-value.js";
 export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
 export class ToolResultRefConflictError extends Error {
@@ -385,6 +385,7 @@ export function createReadToolResultTool(store) {
     return defineTool({
         name: OFFLOAD_TOOL_NAME,
         ...toolFace("read-tool-result"),
+        ruleFace: mountRuleFace("read-tool-result"),
         description: `Read the full content of a tool result that was too large and persisted (you saw it as ` +
             `<persisted-output ref="..."> with a preview). Pass the ref; use offset/limit to page through it.`,
         parameters: Type.Object({

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

@@ -1,6 +1,6 @@
 import { Type, type Static, type TSchema } from "typebox";
 import type { AgentTool } from "../internal/harness-types.js";
-import { type ReservedApprovalCard, type ToolApprovalCard, type ToolFamily, type ToolRosterPathTarget, type ToolMountTag, type ToolPathTarget, type ToolRenderHints, type ToolRuleFace } from "./tool-face.js";
+import { type ReservedApprovalCard, type ToolApprovalCard, type ToolFamily, type ToolHostTarget, type ToolRosterPathTarget, type ToolMountTag, type ToolPathTarget, type ToolRenderHints, type ToolRuleFace } from "./tool-face.js";
 import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
 import type { ToolMarkSource } from "./ask-origin.js";
 export declare const ROSTER_SOURCES: readonly ["builtin", "caller", "host", "mcp", "a2a", "external", "synthetic"];
@@ -10,7 +10,7 @@ export declare const ToolRosterRenderHints: Type.TObject<{
     activity: Type.TOptional<Type.TString>;
     summaryParams: Type.TOptional<Type.TArray<Type.TString>>;
     resultCards: Type.TOptional<Type.TArray<Type.TString>>;
-    approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
+    approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
 }>;
 export declare const ToolRosterEntry: Type.TObject<{
     name: Type.TString;
@@ -63,9 +63,17 @@ export declare const ToolRosterEntry: Type.TObject<{
         absent: Type.TOptional<Type.TUnion<[Type.TLiteral<"none">, Type.TLiteral<"base">]>>;
         patternParam: Type.TOptional<Type.TString>;
     }>>;
+    /** The URL slot a host rule of the row's name is read on, as the definition declared it ({@link ToolHostTarget}); absent when
+     *  it declares none. Exclusive with `pathTarget`. */
+    hostTarget: Type.TOptional<Type.TObject<{
+        param: Type.TString;
+    }>>;
+    /** `nameValues`: the values the mounted tool takes for the argument its name rules are read against (`ToolRuleFace.nameValues`,
+     *  the delegation tool's offered agent types) — present exactly when the definition declares them, copied as declared. */
     ruleFace: Type.TObject<{
         primaryParams: Type.TArray<Type.TString>;
         params: Type.TArray<Type.TString>;
+        nameValues: Type.TOptional<Type.TArray<Type.TString>>;
     }>;
     approvalPreview: Type.TBoolean;
     validateInput: Type.TBoolean;
@@ -78,7 +86,7 @@ export declare const ToolRosterEntry: Type.TObject<{
         activity: Type.TOptional<Type.TString>;
         summaryParams: Type.TOptional<Type.TArray<Type.TString>>;
         resultCards: Type.TOptional<Type.TArray<Type.TString>>;
-        approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
+        approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
     }>>;
     /** The ONE mount condition that fired for this instance. */
     mountedBy: Type.TUnion<[Type.TLiteral<"hands">, Type.TLiteral<"backgroundTasks">, Type.TLiteral<"workflow">, Type.TLiteral<"delegation">, Type.TLiteral<"hostInternals">, Type.TLiteral<"peerLane">, Type.TLiteral<"scheduler">, Type.TLiteral<"memory">, Type.TLiteral<"scenario">, Type.TLiteral<"always">, Type.TLiteral<"optional">]>;
@@ -140,9 +148,17 @@ export declare const ToolRoster: Type.TObject<{
             absent: Type.TOptional<Type.TUnion<[Type.TLiteral<"none">, Type.TLiteral<"base">]>>;
             patternParam: Type.TOptional<Type.TString>;
         }>>;
+        /** The URL slot a host rule of the row's name is read on, as the definition declared it ({@link ToolHostTarget}); absent when
+         *  it declares none. Exclusive with `pathTarget`. */
+        hostTarget: Type.TOptional<Type.TObject<{
+            param: Type.TString;
+        }>>;
+        /** `nameValues`: the values the mounted tool takes for the argument its name rules are read against (`ToolRuleFace.nameValues`,
+         *  the delegation tool's offered agent types) — present exactly when the definition declares them, copied as declared. */
         ruleFace: Type.TObject<{
             primaryParams: Type.TArray<Type.TString>;
             params: Type.TArray<Type.TString>;
+            nameValues: Type.TOptional<Type.TArray<Type.TString>>;
         }>;
         approvalPreview: Type.TBoolean;
         validateInput: Type.TBoolean;
@@ -155,7 +171,7 @@ export declare const ToolRoster: Type.TObject<{
             activity: Type.TOptional<Type.TString>;
             summaryParams: Type.TOptional<Type.TArray<Type.TString>>;
             resultCards: Type.TOptional<Type.TArray<Type.TString>>;
-            approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
+            approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
         }>>;
         /** The ONE mount condition that fired for this instance. */
         mountedBy: Type.TUnion<[Type.TLiteral<"hands">, Type.TLiteral<"backgroundTasks">, Type.TLiteral<"workflow">, Type.TLiteral<"delegation">, Type.TLiteral<"hostInternals">, Type.TLiteral<"peerLane">, Type.TLiteral<"scheduler">, Type.TLiteral<"memory">, Type.TLiteral<"scenario">, Type.TLiteral<"always">, Type.TLiteral<"optional">]>;
@@ -225,9 +241,17 @@ export declare const ToolRosterDelta: Type.TObject<{
                 absent: Type.TOptional<Type.TUnion<[Type.TLiteral<"none">, Type.TLiteral<"base">]>>;
                 patternParam: Type.TOptional<Type.TString>;
             }>>;
+            /** The URL slot a host rule of the row's name is read on, as the definition declared it ({@link ToolHostTarget}); absent when
+             *  it declares none. Exclusive with `pathTarget`. */
+            hostTarget: Type.TOptional<Type.TObject<{
+                param: Type.TString;
+            }>>;
+            /** `nameValues`: the values the mounted tool takes for the argument its name rules are read against (`ToolRuleFace.nameValues`,
+             *  the delegation tool's offered agent types) — present exactly when the definition declares them, copied as declared. */
             ruleFace: Type.TObject<{
                 primaryParams: Type.TArray<Type.TString>;
                 params: Type.TArray<Type.TString>;
+                nameValues: Type.TOptional<Type.TArray<Type.TString>>;
             }>;
             approvalPreview: Type.TBoolean;
             validateInput: Type.TBoolean;
@@ -240,7 +264,7 @@ export declare const ToolRosterDelta: Type.TObject<{
                 activity: Type.TOptional<Type.TString>;
                 summaryParams: Type.TOptional<Type.TArray<Type.TString>>;
                 resultCards: Type.TOptional<Type.TArray<Type.TString>>;
-                approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
+                approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
             }>>;
             /** The ONE mount condition that fired for this instance. */
             mountedBy: Type.TUnion<[Type.TLiteral<"hands">, Type.TLiteral<"backgroundTasks">, Type.TLiteral<"workflow">, Type.TLiteral<"delegation">, Type.TLiteral<"hostInternals">, Type.TLiteral<"peerLane">, Type.TLiteral<"scheduler">, Type.TLiteral<"memory">, Type.TLiteral<"scenario">, Type.TLiteral<"always">, Type.TLiteral<"optional">]>;
@@ -296,7 +320,7 @@ export declare function toolCallFaceOf(roster: ToolRoster | undefined, toolName:
  *  (the row then reads pre-identity and the resume binds the name alone). */
 export declare function parkedToolIdentity(roster: ToolRoster | undefined, toolName: string): Partial<ToolIdentity>;
 /** design/388 B6 × B18 — the FACE members a park row carries beside its identity: the display family, the declared
- *  path target and the names the parked call was judged under. `names` is copied from the face the gate stamped on the
+ *  path target or URL slot, and the names the parked call was judged under. `names` is copied from the face the gate stamped on the
  *  request (the model's spelling first — the row carries the judged fact, it is not re-derived); a request with no face
  *  takes the roster's names for its row. A recheck that runs before the leg's roster exists (the pre-CAS resume-edit
  *  re-adjudication) rebuilds the call face from the row through {@link parkedCallFaceOf}, so it judges the same object
@@ -310,6 +334,7 @@ export declare function parkedToolFace(roster: ToolRoster | undefined, req: {
 }): {
     family?: ToolFamily;
     pathTarget?: ToolRosterEntry["pathTarget"];
+    hostTarget?: ToolHostTarget;
     names?: readonly string[];
 };
 /** The live face a resumed park row is re-judged under: minted under the row's recorded spelling (`names[0]`) when that
@@ -325,6 +350,7 @@ export declare function parkedRowLiveFace(roster: ToolRoster | undefined, row: {
 export declare function parkedCallFaceOf(pending: {
     family?: ToolFamily;
     pathTarget?: ToolRosterPathTarget;
+    hostTarget?: ToolHostTarget;
     names?: readonly string[];
     capabilityId?: string;
     contractId?: string;
@@ -387,6 +413,10 @@ export declare function rosterMemberBoundProblem(m: RosterBoundMembers): {
     code: RosterBoundCode;
     message: string;
 } | undefined;
+/** Did one of the ENGINE's own mount sites mount this row — a built-in or synthetic tool the engine minted for the leg — rather than a
+ *  caller's `TaskSpec.tools` entry (`scenario`) or a protocol peer's tool? The one identity a caller cannot declare: a name, a contract
+ *  id and a source word all can be worn, the mount site cannot. Read onto the call's face ({@link toolCallFaceOf}, `engineMounted`). */
+export declare function engineMountedRow(e: Pick<ToolRosterEntry, "source" | "mountedBy">): boolean;
 /**
  * The rule vocabulary of ONE mounted instance (design/388 §2.2 ③ / D-3): DERIVED = the scalar top-level
  * keys ∪ the path target's `param` + aliases; a declared `params` list can only NARROW it (a declared
@@ -427,6 +457,7 @@ export interface MountedToolFace {
     mcpAlwaysLoad?: boolean;
     family?: ToolFamily;
     pathTarget?: ToolPathTarget;
+    hostTarget?: ToolHostTarget;
     ruleFace?: ToolRuleFace;
     renderHints?: ToolRenderHints;
     compactable?: true;
@@ -437,7 +468,7 @@ export interface MountedToolFace {
 export declare const faceOf: (t: AgentTool) => MountedToolFace;
 /** The leg facts the snapshot reads beside the instances — the safety scan's folds and the per-task knobs. */
 export interface RosterSnapshotFacts {
-    /** The leg's by-name effect map (the builder is its mount-time writer; the protocol folds also write it). */
+    /** The leg's by-name effect map (the builder writes it at every mount and unmount; the protocol folds write a protocol member's). */
     effects: ReadonlyMap<string, ToolEffect>;
     egress: ReadonlySet<string>;
     irreversibilityTier: ReadonlyMap<string, "never" | "maybe" | "always">;
@@ -464,15 +495,11 @@ export declare class RosterBuilder {
     get tools(): readonly AgentTool[];
     get length(): number;
     metaOf(tool: AgentTool): RosterMountMeta | undefined;
-    /** Mount one instance at the tail. An engine-lane instance that DECLARES an effect writes it into the leg's effect
-     *  map — the later mount under a name is the one the harness dispatches to (`snapshot`'s yield rule), so its
-     *  declaration is the map's truth for that name — an engine tool's effect reaches the map from its own declaration, here at its
-     *  mount (nothing writes it by name beforehand; a protocol axis fills a name no mounted instance declares, and the gate's
-     *  post-assembly sync a kept instance the map still lacks). The `scenario` lane never writes the map: its
-     *  declarations were latched by the safety scan BEFORE any mount (on the kept instance of each name, on the
-     *  synchronous doors+scan stretch — a microtask cannot flip them), so a scenario mount, kept or dropped, leaves
-     *  the map as the scan made it; an engine lane's mount under that name still displaces it, and the aliases the displaced
-     *  instance answered to move to the member they now resolve to (`#resettleAliases`). */
+    /** Mount one instance at the tail; the leg's effect map then follows the mounted set (`#settleEffects`). The later mount under
+     *  a name is the one the harness dispatches to (`snapshot`'s yield rule). A `scenario` mount (a caller's own `TaskSpec.tools`
+     *  entry, the driver's frozen face — the declaration the safety scan judged) leaves the three safety axes as the scan wrote them;
+     *  any other mount under a name displaces the instance there, and the axes of the aliases the displaced instance answered to
+     *  move to the member they now resolve to (`#resettleAliases`). */
     mount(tool: AgentTool, meta: RosterMountMeta): void;
     /** An ENGINE-INJECTED instance the harness list carries outside the mount array (the ToolSearch lane): a roster
      *  row — the model can call it — never a mount-array element (the disclosure lane owns that list and appends the
@@ -555,13 +582,15 @@ export declare class ToolRosterDeltaSeat {
 /**
  * design/388 B15 — the rule-face resolver a leg hands the rule compiler: every roster row answers with its
  * derived vocabulary, the carried-but-non-scalar keys (so `Edit(edits:x)` reads `param_non_scalar`, not
- * `param_unknown`) and whether it names a path target; a name off the roster answers undefined.
+ * `param_unknown`) and the values a name rule of it is resolved against when the definition declares them (`nameValues`);
+ * a name off the roster answers undefined. Which lane a rule takes is the rule name's grammar, not the row's: the resolver
+ * says which parameters the mounted tool carries and which name values it declares.
  */
 export declare function ruleFacesFromRoster(roster: ToolRoster): (toolName: string) => {
     primaryParams: readonly string[];
     params: readonly string[];
     nonScalar: readonly string[];
-    pathTargeting: boolean;
+    nameValues?: readonly string[];
 } | undefined;
 /** The delta between two snapshots (design/388 §2.5): the whole `next` roster plus the name summary. */
 export declare function diffToolRoster(prev: ToolRoster, next: ToolRoster): ToolRosterDelta;

package/dist/core/tool-roster.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { types } from "node:util";
 import { Type } from "typebox";
-import { findToolByName } from "../internal/llm.js";
+import { toolNameIndex } from "../internal/llm.js";
 import { getToolContract } from "../prompt-assembly/tool-catalog.js";
 import { protocolOf } from "./protocol-table.js";
 import { describeToolCatalog } from "./tool-registry.js";
@@ -60,7 +60,8 @@ export const ToolRosterEntry = Type.Object({
         absent: Type.Optional(lit(TOOL_PATH_ABSENCES)),
         patternParam: Type.Optional(Key),
     }, { additionalProperties: false })),
-    ruleFace: Type.Object({ primaryParams: Type.Array(Key), params: Type.Array(Key) }, { additionalProperties: false }),
+    hostTarget: Type.Optional(Type.Object({ param: Key }, { additionalProperties: false })),
+    ruleFace: Type.Object({ primaryParams: Type.Array(Key), params: Type.Array(Key), nameValues: Type.Optional(Type.Array(Type.String())) }, { additionalProperties: false }),
     approvalPreview: Type.Boolean(),
     validateInput: Type.Boolean(),
     deferred: Type.Boolean(),
@@ -116,11 +117,14 @@ export function toolCallFaceOf(roster, toolName) {
         names: resolving.includes(toolName) ? [toolName, ...resolving.filter((n) => n !== toolName)] : resolving,
         family: e.family,
         ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}),
+        ...(e.hostTarget !== undefined ? { hostTarget: e.hostTarget } : {}),
+        ...(e.ruleFace?.nameValues !== undefined ? { nameValues: Object.freeze([...e.ruleFace.nameValues]) } : {}),
         capabilityId: e.capabilityId,
         contractId: e.contract.contractId,
         shapeDigest: e.shapeDigest,
         implementationRevision: e.contract.implementationRevision,
         approvalCard: approvalCardOf({ toolName: e.name }, e.renderHints?.approvalCard),
+        ...(engineMountedRow(e) ? { engineMounted: true } : {}),
     };
 }
 export function parkedToolIdentity(roster, toolName) {
@@ -136,7 +140,7 @@ export function parkedToolFace(roster, req) {
     if (e === undefined)
         return {};
     const judged = req.face?.names;
-    return { family: e.family, ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}), names: judged !== undefined && judged.includes(req.toolName) ? [...judged] : namesResolvingTo(roster, e) };
+    return { family: e.family, ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}), ...(e.hostTarget !== undefined ? { hostTarget: e.hostTarget } : {}), names: judged !== undefined && judged.includes(req.toolName) ? [...judged] : namesResolvingTo(roster, e) };
 }
 export function parkedRowLiveFace(roster, row) {
     const spelled = row.names?.[0];
@@ -150,6 +154,7 @@ export function parkedCallFaceOf(pending) {
         ...(pending.names !== undefined ? { names: pending.names } : {}),
         family: pending.family,
         ...(pending.pathTarget !== undefined ? { pathTarget: pending.pathTarget } : {}),
+        ...(pending.hostTarget !== undefined ? { hostTarget: pending.hostTarget } : {}),
         capabilityId: pending.capabilityId,
         contractId: pending.contractId,
         shapeDigest: pending.shapeDigest,
@@ -268,6 +273,9 @@ export function rosterMemberBoundProblem(m) {
         return { code: "config.tool_roster_bound", message: of(over("cardId", m.cardId, TOOL_CARD_ID_MAX_CHARS)) };
     return undefined;
 }
+export function engineMountedRow(e) {
+    return e.mountedBy !== "scenario" && (e.source === "builtin" || e.source === "synthetic");
+}
 export function ruleFaceOfInstance(schema, declared, pathTarget) {
     const { scalar } = inputKeysOf(schema);
     const derived = new Set(scalar);
@@ -304,6 +312,7 @@ export function survivorsByName(mounted) {
     return winner;
 }
 export const faceOf = (t) => t;
+const protocolFolded = (source) => source === "mcp" || source === "a2a";
 const setOrClear = (m, key, value) => {
     if (value === undefined)
         m.delete(key);
@@ -341,18 +350,19 @@ export class RosterBuilder {
         return this.#meta.get(tool);
     }
     mount(tool, meta) {
+        this.#settleEffects(this.#mountOne(tool, meta, this.#tools));
+    }
+    #mountOne(tool, meta, lane) {
         const displaced = this.#survivorNamed(tool.name);
         this.#admit(tool, meta);
-        this.#tools.push(tool);
+        lane.push(tool);
+        const aliases = [...(displaced?.aliases ?? []), ...(tool.aliases ?? [])];
         if (meta.mountedBy !== "scenario")
-            this.#resettleAliases([...(displaced?.aliases ?? []), ...(tool.aliases ?? [])]);
+            this.#resettleAliases(aliases);
+        return [tool.name, ...aliases];
     }
     mountEngineLane(tool, meta) {
-        const displaced = this.#survivorNamed(tool.name);
-        this.#admit(tool, meta);
-        this.#engineLane.push(tool);
-        if (meta.mountedBy !== "scenario")
-            this.#resettleAliases([...(displaced?.aliases ?? []), ...(tool.aliases ?? [])]);
+        this.#settleEffects(this.#mountOne(tool, meta, this.#engineLane));
     }
     #admit(tool, meta) {
         if ((meta.source === "mcp" || meta.source === "a2a" || meta.source === "external") !== (meta.origin !== undefined)) {
@@ -361,9 +371,20 @@ export class RosterBuilder {
         if (!TOOL_MOUNT_TAGS.includes(meta.mountedBy))
             throw configError("config.tool_roster_mount_tag", `tool ${JSON.stringify(tool.name)}: mount tag ${JSON.stringify(meta.mountedBy)} is outside the closed set`);
         this.#meta.set(tool, meta);
-        const eff = faceOf(tool).effect;
-        if (eff !== undefined && meta.mountedBy !== "scenario")
-            this.#effects.set(tool.name, eff);
+    }
+    #settleEffects(names) {
+        const answering = toolNameIndex([...survivorsByName([...this.#tools, ...this.#engineLane]).values()]);
+        for (const name of new Set(names)) {
+            const owner = answering(name);
+            const declared = owner === undefined ? undefined : faceOf(owner).effect;
+            if (declared !== undefined)
+                this.#effects.set(name, declared);
+            else if (owner === undefined || !protocolFolded(this.#meta.get(owner)?.source))
+                this.#effects.delete(name);
+        }
+    }
+    #namesAfterRemoval(removed) {
+        return [...this.#tools, ...this.#engineLane, ...removed].flatMap((t) => [t.name, ...(t.aliases ?? [])]);
     }
     #survivorNamed(name) {
         return survivorsByName([...this.#tools, ...this.#engineLane]).get(name);
@@ -371,20 +392,19 @@ export class RosterBuilder {
     #resettleAliases(aliases) {
         if (aliases.length === 0)
             return;
-        const live = [...survivorsByName([...this.#tools, ...this.#engineLane]).values()];
+        const answering = toolNameIndex([...survivorsByName([...this.#tools, ...this.#engineLane]).values()]);
         for (const a of new Set(aliases)) {
-            const owner = findToolByName(live, a);
+            const owner = answering(a);
             if (owner?.name === a)
                 continue;
             this.#repoint(a, owner?.name);
         }
     }
     #repoint(key, from) {
-        const pick = (m) => (from === undefined ? undefined : m.get(from));
-        const marks = this.#axes === undefined ? undefined : pick(this.#axes.toolMarkSources);
-        setOrClear(this.#effects, key, pick(this.#effects));
         if (this.#axes === undefined)
             return;
+        const pick = (m) => (from === undefined ? undefined : m.get(from));
+        const marks = pick(this.#axes.toolMarkSources);
         setOrClear(this.#axes.irreversibilityTier, key, pick(this.#axes.irreversibilityTier));
         setOrClear(this.#axes.reversibilityProbes, key, pick(this.#axes.reversibilityProbes));
         setOrClear(this.#axes.toolMarkSources, key, marks === undefined ? undefined : new Set(marks));
@@ -392,8 +412,7 @@ export class RosterBuilder {
         memberIf(this.#axes.egressTools, key, from !== undefined && this.#axes.egressTools.has(from));
     }
     mountAll(tools, meta) {
-        for (const t of tools)
-            this.mount(t, meta);
+        this.#settleEffects(tools.flatMap((t) => this.#mountOne(t, meta, this.#tools)));
     }
     unmountWhere(pred) {
         const removed = [];
@@ -404,9 +423,7 @@ export class RosterBuilder {
                 removed.unshift(t);
             }
         }
-        for (const t of removed)
-            if (this.#survivorNamed(t.name) === undefined)
-                this.#effects.delete(t.name);
+        this.#settleEffects(this.#namesAfterRemoval(removed));
         this.#resettleAliases(removed.flatMap((t) => t.aliases ?? []));
         return removed;
     }
@@ -421,22 +438,20 @@ export class RosterBuilder {
     }
     replaceDomain(prefix, fresh, meta) {
         let anchor = -1;
+        const removed = [];
         for (let i = this.#tools.length - 1; i >= 0; i--) {
             if (this.#tools[i].name.startsWith(prefix)) {
                 anchor = i;
-                this.#tools.splice(i, 1);
+                removed.push(...this.#tools.splice(i, 1));
             }
         }
-        for (const t of fresh) {
+        for (const t of fresh)
             this.#meta.set(t, meta);
-            const eff = faceOf(t).effect;
-            if (eff !== undefined)
-                this.#effects.set(t.name, eff);
-        }
         if (anchor >= 0)
             this.#tools.splice(anchor, 0, ...fresh);
         else
             this.#tools.push(...fresh);
+        this.#settleEffects(this.#namesAfterRemoval(removed));
         return { anchor };
     }
     snapshot(facts) {
@@ -542,7 +557,7 @@ export function mintRosterEntry(tool, meta, facts) {
     const declaredEffect = face.effect;
     const foldedEffect = facts.effects.get(tool.name);
     const effect = declaredEffect ?? foldedEffect ?? "write";
-    const effectProvenance = declaredEffect !== undefined ? (meta.source === "synthetic" ? "synthetic" : "declared") : foldedEffect !== undefined && (meta.source === "mcp" || meta.source === "a2a") ? "caller" : "default";
+    const effectProvenance = declaredEffect !== undefined ? (meta.source === "synthetic" ? "synthetic" : "declared") : foldedEffect !== undefined && protocolFolded(meta.source) ? "caller" : "default";
     const boundaryLegs = rosterBoundaryLegs(meta.source, face.boundaryLegs, effect);
     if (boundaryLegs === undefined)
         throw boundaryLegsRefusal(tool.name);
@@ -554,6 +569,11 @@ export function mintRosterEntry(tool, meta, facts) {
     const contentOriginProvenance = face.contentOrigin !== undefined ? (meta.source === "mcp" || meta.source === "a2a" ? "server" : "declared") : facts.trustedTools.has(tool.name) ? "exempted" : "default";
     const pathTarget = face.pathTarget;
     const rf = ruleFaceOfInstance(tool.parameters, face.ruleFace, pathTarget);
+    const declaredValues = face.ruleFace?.nameValues;
+    const isStringList = (v) => Array.isArray(v) && Array.from(v).every((s) => typeof s === "string");
+    if (declaredValues !== undefined && !isStringList(declaredValues))
+        throw configError("config.tool_roster_bound", `tool ${JSON.stringify(tool.name)}: ruleFace.nameValues must be a list of strings`);
+    const nameValues = declaredValues;
     const hints = face.renderHints !== undefined ? capRenderHints(face.renderHints) : undefined;
     const bound = rosterMemberBoundProblem({
         name: tool.name,
@@ -604,7 +624,8 @@ export function mintRosterEntry(tool, meta, facts) {
                 },
             }
             : {}),
-        ruleFace: rf,
+        ...(face.hostTarget !== undefined ? { hostTarget: { param: face.hostTarget.param } } : {}),
+        ruleFace: { ...rf, ...(nameValues !== undefined ? { nameValues: [...nameValues] } : {}) },
         approvalPreview: typeof tool.approvalPreview === "function",
         validateInput: typeof tool.validateInput === "function",
         deferred: facts.deferred.has(tool.name),
@@ -672,7 +693,7 @@ export function ruleFacesFromRoster(roster) {
             primaryParams: e.ruleFace.primaryParams,
             params: e.ruleFace.params,
             nonScalar: e.inputKeys.filter((k) => !params.has(k.name) && (k.type === "object" || k.type === "array")).map((k) => k.name),
-            pathTargeting: e.pathTarget !== undefined,
+            ...(e.ruleFace.nameValues !== undefined ? { nameValues: Object.freeze([...e.ruleFace.nameValues]) } : {}),
         };
     };
 }