@sema-agent/core 7.54.1 → 7.56.0

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

@@ -4,8 +4,9 @@ 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";
+import { carryNotStartedReceipt } from "./delegation-not-started.js";
 export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
 export class ToolResultRefConflictError extends Error {
     ref;
@@ -239,6 +240,8 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId, re
     const wrappedExecute = async (toolCallId, params, signal, onUpdate) => {
         const res = await tool.execute(toolCallId, params, signal, onUpdate);
         const offloadedDetails = res.details === undefined ? undefined : await offloadOversizedDetailStrings(res.details, store, thresholdChars, sessionId, toolCallId, provenance);
+        if (offloadedDetails !== undefined)
+            carryNotStartedReceipt(res.details, offloadedDetails.value);
         const withDetails = (r) => offloadedDetails === undefined || offloadedDetails.value === res.details ? r : { ...r, details: offloadedDetails.value };
         if (totalTextChars(res.content) <= thresholdChars)
             return withDetails(res);
@@ -385,6 +388,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,8 +1,7 @@
 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"];
 export type RosterSource = (typeof ROSTER_SOURCES)[number];
 export declare const ToolRosterRenderHints: Type.TObject<{
@@ -10,7 +9,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 +62,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 +85,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 +147,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 +170,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 +240,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 +263,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,11 +319,13 @@ 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
- *  the live gate judged. An empty object when the name is not on the snapshot (the row then reads pre-face and the
+ *  takes the roster's names for its row. The mount site (`engineMounted`) is the roster entry's, as the identity and face members
+ *  beside it are: a fact of the tool, not of the call, and never read off the request's face, which the policy that judges the call
+ *  can write. 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 members the row
+ *  recorded (identity, family, targets, names, mount site) — not the live face's rule name values or approval card. An empty object when the name is not on the snapshot (the row then reads pre-face and the
  *  recheck falls to the catalog for the name). */
 export declare function parkedToolFace(roster: ToolRoster | undefined, req: {
     readonly toolName: string;
@@ -310,7 +335,9 @@ export declare function parkedToolFace(roster: ToolRoster | undefined, req: {
 }): {
     family?: ToolFamily;
     pathTarget?: ToolRosterEntry["pathTarget"];
+    hostTarget?: ToolHostTarget;
     names?: readonly string[];
+    engineMounted?: true;
 };
 /** The live face a resumed park row is re-judged under: minted under the row's recorded spelling (`names[0]`) when that
  *  spelling still resolves to the row's own tool on this roster, else under the row's wire name — a spelling that no
@@ -325,11 +352,13 @@ 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;
     shapeDigest?: string;
     implementationRevision?: string;
+    engineMounted?: true;
 }): import("./tool-policy.js").ToolCallFace | undefined;
 /** The optional `face` seat of a ToolCallRequest: present iff a face was read (a bare request carries no key). */
 export declare function callFaceSeat(face: import("./tool-policy.js").ToolCallFace | undefined): {
@@ -387,6 +416,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
@@ -397,6 +430,8 @@ export declare function ruleFaceOfInstance(schema: TSchema | undefined, declared
     primaryParams: string[];
     params: string[];
 };
+/** The instance `row` describes: what runs when a call is judged by that row. A row no snapshot minted has none. */
+export declare function rowMember(row: ToolRosterEntry): AgentTool | undefined;
 /** The instance each NAME dispatches to when several are mounted under it: the LATER mount (the harness keeps the
  *  later one). The one selection — the roster's snapshot and every table keyed by a caller tool's name read it here. */
 export declare function survivorsByName<T extends {
@@ -427,6 +462,7 @@ export interface MountedToolFace {
     mcpAlwaysLoad?: boolean;
     family?: ToolFamily;
     pathTarget?: ToolPathTarget;
+    hostTarget?: ToolHostTarget;
     ruleFace?: ToolRuleFace;
     renderHints?: ToolRenderHints;
     compactable?: true;
@@ -437,7 +473,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">;
@@ -447,32 +483,18 @@ export interface RosterSnapshotFacts {
     /** `TaskSpec.memory.trustedTools` — the exemption channel for an undeclared content class. */
     trustedTools: ReadonlySet<string>;
 }
-/** The leg's per-name safety-axis tables the builder keeps aligned with its mounts beside the effect map (the safety scan mints
- *  them; the protocol folds and the shell seat also write them). */
-export interface RosterAxisTables {
-    irreversibilityTier: Map<string, "never" | "maybe" | "always">;
-    irreversibleTools: Set<string>;
-    reversibilityProbes: Map<string, unknown>;
-    egressTools: Set<string>;
-    toolMarkSources: Map<string, Set<ToolMarkSource>>;
-}
 export declare class RosterBuilder {
     #private;
-    /** `axes` — the leg's safety-axis tables beside the effect map (a builder for a single probe tool may go without). */
-    constructor(effects: Map<string, ToolEffect>, axes?: RosterAxisTables);
+    /** `effects` — the leg's by-name effect map, which the builder keeps equal to the mounted set's answering members. The leg's
+     *  safety-axis tables are not the builder's: their marks live under the names they were laid on, and a call reads them under
+     *  the names it answers to. */
+    constructor(effects: Map<string, ToolEffect>);
     /** The mount array as a READ face. The order is the wire order. */
     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). */
     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 +577,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), ...(engineMountedRow(e) ? { engineMounted: true } : {}) };
 }
 export function parkedRowLiveFace(roster, row) {
     const spelled = row.names?.[0];
@@ -150,10 +154,12 @@ 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,
         implementationRevision: pending.implementationRevision,
+        ...(pending.engineMounted === true ? { engineMounted: true } : {}),
     };
 }
 export function callFaceSeat(face) {
@@ -268,6 +274,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);
@@ -297,6 +306,10 @@ function capRenderHints(h) {
         out.approvalCard = h.approvalCard;
     return Object.keys(out).length > 0 ? out : undefined;
 }
+const ROW_MEMBERS = new WeakMap();
+export function rowMember(row) {
+    return ROW_MEMBERS.get(row);
+}
 export function survivorsByName(mounted) {
     const winner = new Map();
     for (const t of mounted)
@@ -304,18 +317,7 @@ export function survivorsByName(mounted) {
     return winner;
 }
 export const faceOf = (t) => t;
-const setOrClear = (m, key, value) => {
-    if (value === undefined)
-        m.delete(key);
-    else
-        m.set(key, value);
-};
-const memberIf = (s, key, member) => {
-    if (member)
-        s.add(key);
-    else
-        s.delete(key);
-};
+const protocolFolded = (source) => source === "mcp" || source === "a2a";
 function configError(code, message) {
     const e = new Error(message);
     e.code = code;
@@ -326,10 +328,8 @@ export class RosterBuilder {
     #engineLane = [];
     #meta = new WeakMap();
     #effects;
-    #axes;
-    constructor(effects, axes) {
+    constructor(effects) {
         this.#effects = effects;
-        this.#axes = axes;
     }
     get tools() {
         return this.#tools;
@@ -341,18 +341,16 @@ 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);
-        if (meta.mountedBy !== "scenario")
-            this.#resettleAliases([...(displaced?.aliases ?? []), ...(tool.aliases ?? [])]);
+        lane.push(tool);
+        return [tool.name, ...(displaced?.aliases ?? []), ...(tool.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,39 +359,26 @@ 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);
-    }
-    #survivorNamed(name) {
-        return survivorsByName([...this.#tools, ...this.#engineLane]).get(name);
     }
-    #resettleAliases(aliases) {
-        if (aliases.length === 0)
-            return;
-        const live = [...survivorsByName([...this.#tools, ...this.#engineLane]).values()];
-        for (const a of new Set(aliases)) {
-            const owner = findToolByName(live, a);
-            if (owner?.name === a)
-                continue;
-            this.#repoint(a, owner?.name);
+    #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);
         }
     }
-    #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;
-        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));
-        memberIf(this.#axes.irreversibleTools, key, from !== undefined && this.#axes.irreversibleTools.has(from));
-        memberIf(this.#axes.egressTools, key, from !== undefined && this.#axes.egressTools.has(from));
+    #namesAfterRemoval(removed) {
+        return [...this.#tools, ...this.#engineLane, ...removed].flatMap((t) => [t.name, ...(t.aliases ?? [])]);
+    }
+    #survivorNamed(name) {
+        return survivorsByName([...this.#tools, ...this.#engineLane]).get(name);
     }
     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,10 +389,7 @@ export class RosterBuilder {
                 removed.unshift(t);
             }
         }
-        for (const t of removed)
-            if (this.#survivorNamed(t.name) === undefined)
-                this.#effects.delete(t.name);
-        this.#resettleAliases(removed.flatMap((t) => t.aliases ?? []));
+        this.#settleEffects(this.#namesAfterRemoval(removed));
         return removed;
     }
     replaceAt(index, tool) {
@@ -421,22 +403,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) {
@@ -450,7 +430,9 @@ export class RosterBuilder {
             emitted.add(t.name);
             const survivor = winner.get(t.name);
             const meta = this.#meta.get(survivor) ?? { source: "caller", mountedBy: "scenario" };
-            entries.push(mintRosterEntry(survivor, meta, facts));
+            const row = mintRosterEntry(survivor, meta, facts);
+            ROW_MEMBERS.set(row, survivor);
+            entries.push(row);
         }
         const roster = { schemaVersion: 1, count: entries.length, entries, digest: rosterDigestOf(entries) };
         const worn = rosterEngineNamesProblem(roster);
@@ -542,7 +524,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 +536,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 +591,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 +660,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]) } : {}),
         };
     };
 }

package/dist/core/tool-spec-members.js

@@ -1,9 +1,12 @@
+import { assertNoRetiredKeys, RETIRED_TOOL_SPEC_KEYS } from "./retired-keys.js";
 import { UNREADABLE_LIST, snapshotToolNameList } from "./tool-name-list.js";
+import { isCatalogContract } from "./tool-catalog-entries.js";
+import { isEngineDescriptor } from "../prompt-assembly/tool-catalog.js";
 export const TOOL_SPEC_MEMBERS = Object.keys({
-    name: true, aliases: true, description: true, descriptionClassic: true, label: true, parameters: true, execute: true, effect: true,
+    name: true, aliases: true, description: true, descriptionVariants: true, label: true, parameters: true, execute: true, effect: true,
     egress: true, irreversibility: true, reversibilityProbe: true, permissionSeat: true, isConcurrencySafe: true, executionMode: true,
     contentOrigin: true, offload: true, offloadThresholdChars: true, defer: true, alwaysLoad: true, prepareArguments: true,
-    validateInput: true, approvalPreview: true, family: true, pathTarget: true, ruleFace: true, renderHints: true, compactable: true,
+    validateInput: true, approvalPreview: true, family: true, pathTarget: true, hostTarget: true, ruleFace: true, renderHints: true, compactable: true,
     budgetExempt: true, modelGate: true, contract: true, agentListing: true, agentModels: true, agentToolFaces: true,
     agentToolLevelAllowTools: true, agentToolLevelDenyTools: true, agentToolPool: true, agentToolInheritsMcp: true, withAgents: true, boundaryLegs: true, boundaryLegsFor: true,
 });
@@ -14,6 +17,7 @@ const FACE_PLACES = { elementKeys: FACE_LIST_KEYS };
 const MAX_NODES = 20_000;
 const MAX_DEPTH = 64;
 const COPIED = new WeakSet();
+const isEngineMint = (value) => isCatalogContract(value) || isEngineDescriptor(value);
 class DeclarationRefused extends Error {
 }
 function refuse(path, why) {
@@ -46,7 +50,7 @@ function copyNode(value, path, depth, state, lenient, places) {
         return value;
     if (typeof value === "function")
         return lenient ? inertFunction() : refuse(path, "a function inside declaration data");
-    if (COPIED.has(value))
+    if (COPIED.has(value) || isEngineMint(value))
         return value;
     const seen = lenient ? state.seenLenient : state.seen;
     const shared = seen.get(value);
@@ -158,6 +162,7 @@ export function frozenExtra(key, value, state) {
     }
 }
 export function frozenToolSpec(spec) {
+    assertNoRetiredKeys(spec, RETIRED_TOOL_SPEC_KEYS, "ToolSpec");
     const copy = {};
     const state = newCopyState();
     for (const name of TOOL_SPEC_MEMBERS) {