@sema-agent/core 7.7.0 → 7.9.0

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

@@ -0,0 +1,171 @@
+/**
+ * The tool FACE vocabulary (design/388 §2.1–§2.2): the closed word sets and the small declaration
+ * shapes that describe a tool WITHOUT executing it — its display family, the parameter that names its
+ * path target, the parameter vocabulary a permission rule may speak about it, the render hints a shell
+ * may read, and the mount-condition tags the static catalog lists it under.
+ *
+ * Layer-0 vocabulary: nothing here reads an env, a deps object, or a tool instance. `ToolSpec`
+ * (tool-spec.ts) carries the declaration half of these shapes as optional fields; the static catalog
+ * (tool-catalog-entries.ts) lists every built-in's face; the effect roster (tool-roster.ts) reads the
+ * same shapes off the MOUNTED instance. One vocabulary, three readers, no second table.
+ */
+/** The display / dispatch family of a tool. INPUT to grouping and card pre-selection only — never an
+ *  authorization source (a `"file-write"` family grants nothing; the path-confinable predicate reads
+ *  {@link ToolPathTarget}, and the approval card is chosen by {@link ToolRenderHints.approvalCard}). */
+export declare const TOOL_FAMILIES: readonly ["shell", "file-read", "file-write", "search", "web", "delegate", "plan", "scaffold", "memory", "protocol", "other"];
+export type ToolFamily = (typeof TOOL_FAMILIES)[number];
+/**
+ * The closed set of MOUNT-CONDITION tags a static catalog entry is listed under. The static half of the
+ * catalog carries an ARRAY (a tool can be mounted by more than one condition — TaskOutput rides both the
+ * hand band and the delegation surface); the effect roster records the ONE tag that actually fired.
+ *
+ *  - `hands` — the hand band (an execution env is wired: `deps.executionEnv` / `executionEnvFactory`);
+ *  - `backgroundTasks` — the background-task surface (`Monitor`);
+ *  - `workflow` — the workflow tool surface (`Workflow`);
+ *  - `delegation` — the union of the background-task and workflow surfaces (TaskOutput/TaskStop/
+ *    AgentTranscript, SendMessage's first condition);
+ *  - `hostInternals` — a host-internal seat is present (`RunInternals.parentNotify`);
+ *  - `peerLane` — the peer-session lane is mounted;
+ *  - `scheduler` — the env carries a scheduler daemon (the Cron family + ScheduleWakeup);
+ *  - `memory` — an engine-memory / shared-memory session is wired;
+ *  - `scenario` — mounted by a HOST scenario factory through `TaskSpec.tools` (core defines the tool,
+ *    the host decides to mount it);
+ *  - `always` — mounted on every task unless excluded (ReportBlocked/ReportFindings);
+ *  - `optional` — mounted by a per-task opt-in or a wired seat (plan mode, an output schema, an
+ *    offload store, a question face, a skills listing, an MCP configuration).
+ */
+export declare const TOOL_MOUNT_TAGS: readonly ["hands", "backgroundTasks", "workflow", "delegation", "hostInternals", "peerLane", "scheduler", "memory", "scenario", "always", "optional"];
+export type ToolMountTag = (typeof TOOL_MOUNT_TAGS)[number];
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+/** The closed set of specialised approval cards a shell may pre-select from a render hint. The hint is a
+ *  PRE-FILTER: the shell owns each card's input schema and validates the call's full args before
+ *  mounting the card (design/388 §2.5 boundary ①). */
+export declare const TOOL_APPROVAL_CARDS: readonly ["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"];
+export type ToolApprovalCard = (typeof TOOL_APPROVAL_CARDS)[number];
+/** How a path-targeting tool touches its target. `read` never enters a write-confinement face. */
+export declare const TOOL_PATH_ACCESSES: readonly ["read", "create", "edit"];
+export type ToolPathAccess = (typeof TOOL_PATH_ACCESSES)[number];
+/**
+ * The parameter that names this tool's filesystem target, and how the target is touched. Present ⇔ the
+ * tool can be confirmed BY PATH (write confinement, sensitive-path guards, edited-file tracking, the
+ * transcript-directory gate). `param` outranks every alias (NotebookEdit's `notebook_path` beats a decoy
+ * `file_path`). `skillScopeEligible` (default false) is the SEPARATE authorization domain of the
+ * active-skill `allowPaths` face — a confinable write tool is not automatically eligible there.
+ */
+export interface ToolPathTarget {
+    param: string;
+    aliases?: readonly string[];
+    access: ToolPathAccess;
+    skillScopeEligible?: true;
+}
+/**
+ * The parameter vocabulary a permission rule (`Tool(param:pattern)`) may name. DERIVED by default from
+ * the tool's schema: the SCALAR top-level parameters (string/number/integer/boolean and their enum/const/
+ * union forms) plus {@link ToolPathTarget.aliases}; object/array parameters never enter (a rule on them
+ * can never match — `matchParamRules` skips non-scalar values). A declaration can only NARROW the derived
+ * set; `primaryParams` defaults to the path target's `param` + aliases.
+ */
+export interface ToolRuleFace {
+    primaryParams?: readonly string[];
+    params?: readonly string[];
+}
+/** The roster's WIRE bounds on a tool name and a contract member (design/388 §2.5 / B20). Distinct from
+ *  protocol-naming's `TOOL_NAME_MAX_CHARS` (64), the provider-facing bound the MCP/A2A namespacing helper
+ *  budgets a MINTED name to — a minted name is always inside this wire bound by construction; a CALLER
+ *  declaration is judged against it at prepare. */
+export declare const TOOL_WIRE_NAME_MAX_CHARS = 128;
+export declare const TOOL_CONTRACT_MAX_CHARS = 64;
+/** The roster's wire bound on a KEY — a schema property name, a path-target `param`/alias, a rule-face param. A key is a
+ *  SEMANTIC name every fence reads an argument by, so it is never truncated: a declaration over the bound is refused at
+ *  the door (caller) or dropped with a disclosed reason (MCP intake), and a row carries every key exactly. */
+export declare const TOOL_KEY_MAX_CHARS = 256;
+/** The roster's bound on how many top-level keys one row carries (the same refuse/drop treatment). */
+export declare const TOOL_KEYS_MAX = 1024;
+/** Bounds every render-hint string is held to on the roster (design/388 §2.2 ④). */
+export declare const RENDER_HINT_MAX_CHARS = 64;
+export declare const RENDER_HINT_ACTIVITY_MAX_CHARS = 32;
+export declare const RENDER_HINT_MAX_LIST = 16;
+/**
+ * Declarative, template-free display hints (design/388 §2.2 ④, D-4). UNTRUSTED display input on the
+ * wire: the engine length-caps them at the roster mint; the shell strips control / newline / bidi
+ * characters before rendering. `resultCards` may only name cards in the tool's OWN namespace
+ * (`caller:<contractId>/<type>`) — engine cards (`builtin:*`, `mcp`, the refusal cards) are minted by
+ * the engine alone and a declaration naming one is refused at prepare.
+ */
+export interface ToolRenderHints {
+    userFacingName?: string;
+    activity?: string;
+    summaryParams?: readonly string[];
+    resultCards?: readonly string[];
+    approvalCard?: ToolApprovalCard;
+}
+/**
+ * The static FACE of a tool — the subset of `ToolSpec` a catalog entry declares and a definition module
+ * spreads into its spec. Everything here is readable without an env or a deps object; the effect roster
+ * reads the same members off the mounted instance.
+ */
+export interface ToolFaceDeclaration {
+    family: ToolFamily;
+    effect?: import("./tool-spec.js").ToolEffect;
+    egress?: true;
+    irreversibility?: "never" | "maybe" | "always";
+    contentOrigin?: import("./tool-spec.js").ToolContentOrigin;
+    contract?: {
+        contractId: string;
+        implementationRevision: string;
+    };
+    aliases?: string[];
+    pathTarget?: ToolPathTarget;
+    ruleFace?: ToolRuleFace;
+    renderHints?: ToolRenderHints;
+    offload?: boolean;
+    offloadThresholdChars?: number;
+    compactable?: true;
+    budgetExempt?: true;
+}
+/**
+ * One row of the static tool catalog (design/388 §2.1 "静态目录"). Keyed by DEFINITION identity, not by
+ * name: two definitions may share a wire name (the full and the read-only shell both answer to `Bash`),
+ * and every catalog predicate counts a name as a member when ANY entry under it matches.
+ */
+export interface ToolCatalogEntry {
+    /** Definition identity — unique across the catalog (`bash`, `bash-readonly`). */
+    id: string;
+    /** Wire name; may repeat across entries. */
+    name: string;
+    /** `builtin` = a core definition mounted by core or by a host factory; `synthetic` = core mints it
+     *  per task with a per-task shape (the structured-output tool). */
+    source: "builtin" | "synthetic";
+    /** Where the definition lives (repo-relative), so a catalog gate can name the file. */
+    definedIn: string;
+    /** The conditions under which core (or a host scenario) mounts this definition. */
+    mountedBy: readonly ToolMountTag[];
+    /** The `details.type` cards this definition mints on `tool_end.structured`. */
+    cards: readonly string[];
+    /** The declared face — spread into the definition's `ToolSpec` by the module that owns it. */
+    face: ToolFaceDeclaration;
+    /** A `modelGate` class the default-bundle assembler stamps on this definition's default arm. */
+    modelGate?: string;
+}
+/**
+ * The band-membership table over the mount tags: a host derives its hand band as the definitions listed under a
+ * TRUE row (server B-1). Every tag has a row — the fence reds `tsc` when a tag is added without one. The
+ * background-task surface is hands-derived (`backgroundTaskToolsActive` requires the shell), so a definition
+ * mounted by it alone is a band member that is NOT dual-use.
+ */
+export declare const MOUNT_TAG_IN_HANDS_BAND: {
+    readonly hands: true;
+    readonly backgroundTasks: true;
+    readonly workflow: false;
+    readonly delegation: true;
+    readonly hostInternals: true;
+    readonly peerLane: true;
+    readonly scheduler: false;
+    readonly memory: false;
+    readonly scenario: false;
+    readonly always: false;
+    readonly optional: false;
+};
+export type HandsBandTableCoversEveryMountTag = AssertAllKeysHandled<Exclude<ToolMountTag, keyof typeof MOUNT_TAG_IN_HANDS_BAND>>;
+/** The tags whose definitions form the hand band a host derives (server B-1 `HANDS_BAND_TAGS`). */
+export declare const HANDS_BAND_TAGS: ReadonlySet<ToolMountTag>;

package/dist/core/tool-face.js

@@ -0,0 +1,25 @@
+export const TOOL_FAMILIES = ["shell", "file-read", "file-write", "search", "web", "delegate", "plan", "scaffold", "memory", "protocol", "other"];
+export const TOOL_MOUNT_TAGS = ["hands", "backgroundTasks", "workflow", "delegation", "hostInternals", "peerLane", "scheduler", "memory", "scenario", "always", "optional"];
+export const TOOL_APPROVAL_CARDS = ["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"];
+export const TOOL_PATH_ACCESSES = ["read", "create", "edit"];
+export const TOOL_WIRE_NAME_MAX_CHARS = 128;
+export const TOOL_CONTRACT_MAX_CHARS = 64;
+export const TOOL_KEY_MAX_CHARS = 256;
+export const TOOL_KEYS_MAX = 1024;
+export const RENDER_HINT_MAX_CHARS = 64;
+export const RENDER_HINT_ACTIVITY_MAX_CHARS = 32;
+export const RENDER_HINT_MAX_LIST = 16;
+export const MOUNT_TAG_IN_HANDS_BAND = {
+    hands: true,
+    backgroundTasks: true,
+    workflow: false,
+    delegation: true,
+    hostInternals: true,
+    peerLane: true,
+    scheduler: false,
+    memory: false,
+    scenario: false,
+    always: false,
+    optional: false,
+};
+export const HANDS_BAND_TAGS = new Set(Object.keys(MOUNT_TAG_IN_HANDS_BAND).filter((t) => MOUNT_TAG_IN_HANDS_BAND[t]));

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

@@ -1,10 +1,34 @@
 import type { AskOrigin } from "./ask-origin.js";
 import type { Settlement } from "./gate-outcome.js";
 /** A tool call presented to a policy before it executes. */
+/** design/388 B6 — the per-call face (see {@link ToolCallRequest.face}). */
+export interface ToolCallFace {
+    family: import("./tool-face.js").ToolFamily;
+    pathTarget?: {
+        param: string;
+        aliases: readonly string[];
+        access: "read" | "create" | "edit";
+        skillScopeEligible: boolean;
+    };
+    capabilityId: string;
+    contractId: string;
+    shapeDigest: string;
+    implementationRevision: string;
+}
 export interface ToolCallRequest {
     toolName: string;
     args: unknown;
     toolCallId: string;
+    /**
+     * design/388 B6 (additive) — the mounted tool's FACE as the leg's roster minted it: the declared path target
+     * (how the target may be confirmed by path), the display family, and the engine-minted identity
+     * (`capabilityId` / `contractId` / `shapeDigest`) an exemption store keys on. Stamped at the gate entry
+     * from the live roster, so identity follows the OBJECT the call dispatches to — a caller tool that merely
+     * took a built-in's name carries its own face, never the built-in's. ABSENT when a policy is invoked
+     * outside a Runner (a bare producer): a path-confining face then reads the catalog's declaration for the
+     * NAME (the pre-388 posture, never wider), and a skill-scope face treats the write as unconfirmable.
+     */
+    face?: ToolCallFace;
     /**
      * RB-108 — the LIVE working directory this call's RELATIVE path arguments will actually resolve
      * against, read at adjudication time from the same tracked `cwdRef` the fs hand tools resolve with

package/dist/core/tool-policy.js

@@ -4,6 +4,7 @@ import { brandPolicyAskClass } from "./ask-class.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, posix as posixPath, sep, win32 as winPath } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
+import { protectivePathTargetOf } from "./tool-registry.js";
 import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
@@ -847,8 +848,9 @@ export function createTranscriptIntegrityPolicy(opts) {
                         ? "the shell's working directory is inside the transcript directory and this is not a single read-only command (fail-closed)"
                         : "the command references the transcript directory and is not a single read-only command (fail-closed)");
             }
-            if (toolName === "Write" || toolName === "Edit" || toolName === "NotebookEdit") {
-                const p = writeTargetPath(toolName, req.args);
+            const writeTarget = protectivePathTargetOf(req);
+            if (writeTarget !== undefined && writeTarget.access !== "read") {
+                const p = writeTargetPath(req);
                 if (typeof p === "string" && inProtectedDir(p, req.cwd)) {
                     return askReason(`"${p}" is inside the session-transcript directory`);
                 }

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

@@ -0,0 +1,114 @@
+/**
+ * The static tool catalog's READ FACE (design/388 §2.1): `describeToolCatalog()` and the predicates
+ * every former name table is now DERIVED from. Readable without an env, a deps object or a tool
+ * instance — a host predicts a leg's roster from it (`predictMountedToolNames`), a policy module
+ * derives its covered set from it, a shell renders it.
+ *
+ * Every predicate here answers over DEFINITIONS and folds to names with "any definition under this
+ * name matches" — the rule that pins the two fail-open shapes a per-name table had (one name, two
+ * definitions; the table could only hold one).
+ *
+ * Layer-0 vocabulary: depends on the leaf catalog and the face vocabulary only.
+ */
+import { type ToolCatalogEntry, 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`,
+ *  `e.face.compactable`). */
+export declare function describeToolCatalog(): readonly ToolCatalogEntry[];
+/** Every definition under a wire name (a name may carry more than one — the two shells). */
+export declare function catalogEntriesNamed(name: string): readonly ToolCatalogEntry[];
+/** Every wire name the catalog knows, aliases included (a set — the two shells fold to one name). */
+export declare function catalogToolNames(): ReadonlySet<string>;
+/** A-11/12/13/14 — tools this engine can CONFINE BY PATH on a write: `pathTarget.access ≠ read`.
+ *  Today {Write, Edit, NotebookEdit}. */
+export declare function pathConfinableWriteToolNames(): ReadonlySet<string>;
+/** A-11 (the SECOND authorization domain) — the active-skill `allowPaths` face: confinable AND the
+ *  definition opted into skill scoping. Today {Write, Edit} — NotebookEdit is deliberately outside. */
+export declare function skillScopeWriteToolNames(): ReadonlySet<string>;
+/** A-8 — every definition that names a path target at all (read or write): the file-tool glob lane. */
+export declare function pathTargetingToolNames(): ReadonlySet<string>;
+/** A-10 — the micro-compaction whitelist (`compactable: true`). */
+export declare function compactableToolNames(): ReadonlySet<string>;
+/** A-5 — the aggregate-budget exemptions (`budgetExempt: true`). */
+export declare function budgetExemptToolNames(): ReadonlySet<string>;
+/** The value a call's args carry under a path target: `param` first, then each alias, first non-empty string wins. */
+export declare function pathTargetValue(args: unknown, pt: {
+    param: string;
+    aliases?: readonly string[];
+}): string | undefined;
+/** The path target of a wire name — the FIRST definition's (every definition under one name declares
+ *  the same target; the conformance test pins that). */
+/** A gated call as every fence sees it: the wire name, the args, and the OBJECT face a prepared leg stamped on the
+ *  request (absent on a BARE request — a policy invoked outside a Runner). */
+export interface ToolCallLike {
+    toolName: string;
+    args: unknown;
+    face?: {
+        pathTarget?: {
+            param: string;
+            aliases?: readonly string[];
+            access: ToolPathAccess;
+        };
+    } | undefined;
+}
+type CallPathTarget = {
+    param: string;
+    aliases?: readonly string[];
+    access: ToolPathAccess;
+};
+/**
+ * design/388 B6/B17 — the path target a PROTECTIVE fence reads (a deny-list judging a write's target: sensitive paths,
+ * frozen paths, write protection, the transcript gate; edit tracking): the object face's own declaration first, the
+ * catalog's declaration for the NAME as the FLOOR — for a bare request (a policy invoked outside a Runner) and for a
+ * face that declares none. Reading the catalog for an undeclared same-name tool can only TIGHTEN a deny-list (it adds
+ * a slot to judge — the pre-388 posture, never wider), which is exactly why this floor is wrong for a grant.
+ */
+export declare function protectivePathTargetOf(call: ToolCallLike): CallPathTarget | undefined;
+/**
+ * The path target a CONTAINMENT fence reads (a grant admitting a write BY its path: session `allowDirs`, the fs-write
+ * gate's accept/exempt dirs; the active-skill allowPaths face reads its own eligibility bit the same way): the object
+ * face's OWN declaration only — a same-name tool that declares no path target is an UNCONFIRMABLE write (the catalog's
+ * slot may not be the one it writes; a decoy in that slot would buy an admission), so the fence fails closed. A BARE
+ * request (no face at all — a policy invoked outside a Runner) reads the catalog for the name: the pre-388 reading, the
+ * documented migration seam for bare producers.
+ */
+export declare function declaredPathTargetOf(call: ToolCallLike): CallPathTarget | undefined;
+/** Is this call a write a PROTECTIVE fence judges (a protected target whose access ≠ read)? The name sets are its static view. */
+export declare function isProtectedWrite(call: ToolCallLike): boolean;
+/** Is this call a write a CONTAINMENT fence may ADMIT by its path (a declared target whose access ≠ read)? */
+export declare function isDeclaredWrite(call: ToolCallLike): boolean;
+/** design/388 A-18 — the file-op access a compaction summary records for a LIVE tool name: only the FILE families'
+ *  path targets name a file (a search tool's `path` is a search ROOT, not a file the model read); every other name
+ *  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 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.
+ */
+export declare function catalogRuleFaceOf(name: string): {
+    primaryParams: string[];
+    params?: string[];
+} | undefined;
+/** A-1 / server B-1 — the hand band's declared effects by name (any `hands` definition; the WRITE shell
+ *  wins the name when both are listed, matching the by-name table this replaces — the read-only shell's
+ *  own instance carries `effect: "read"` and the effect roster reports THAT). */
+export declare function handBandEffects(): ReadonlyMap<string, NonNullable<ToolCatalogEntry["face"]["effect"]>>;
+/** A-3 / L4 — every `details.type` card the engine owns: the catalog's per-definition cards plus the
+ *  engine-minted ones (protocol channels, fs refusals). */
+export declare function engineCardTypes(): ReadonlySet<string>;
+/**
+ * L3 — the STATIC PREDICTION of a leg's core-mounted names for a set of active mount conditions:
+ * every definition listed under at least one active tag. `scenario` and `optional` definitions mount
+ * only when the vector names their tag (a host factory / a per-task opt-in decides them). Names are
+ * folded (the two shells predict one `Bash`).
+ */
+export declare function predictMountedToolNames(active: ReadonlySet<ToolMountTag>): ReadonlySet<string>;
+/** The closed set as a Set, for callers that validate a tag read off the wire. */
+export declare const TOOL_MOUNT_TAG_SET: ReadonlySet<string>;
+export { HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND } from "./tool-face.js";

package/dist/core/tool-registry.js

@@ -0,0 +1,114 @@
+import { TOOL_MOUNT_TAGS } from "./tool-face.js";
+import { ENGINE_CARDS, TOOL_CATALOG_ENTRIES } from "./tool-catalog-entries.js";
+export function describeToolCatalog() {
+    return TOOL_CATALOG_ENTRIES;
+}
+export function catalogEntriesNamed(name) {
+    return TOOL_CATALOG_ENTRIES.filter((e) => e.name === name);
+}
+export function catalogToolNames() {
+    const out = new Set();
+    for (const e of TOOL_CATALOG_ENTRIES) {
+        out.add(e.name);
+        for (const a of e.face.aliases ?? [])
+            out.add(a);
+    }
+    return out;
+}
+const names = (pred) => {
+    const out = new Set();
+    for (const e of TOOL_CATALOG_ENTRIES)
+        if (pred(e))
+            out.add(e.name);
+    return out;
+};
+export function pathConfinableWriteToolNames() {
+    return names((e) => e.face.pathTarget !== undefined && e.face.pathTarget.access !== "read");
+}
+export function skillScopeWriteToolNames() {
+    return names((e) => e.face.pathTarget !== undefined && e.face.pathTarget.access !== "read" && e.face.pathTarget.skillScopeEligible === true);
+}
+export function pathTargetingToolNames() {
+    return names((e) => e.face.pathTarget !== undefined);
+}
+export function compactableToolNames() {
+    return names((e) => e.face.compactable === true);
+}
+export function budgetExemptToolNames() {
+    return names((e) => e.face.budgetExempt === true);
+}
+export function pathTargetValue(args, pt) {
+    if (args === null || typeof args !== "object")
+        return undefined;
+    const a = args;
+    for (const k of [pt.param, ...(pt.aliases ?? [])]) {
+        const v = a[k];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    return undefined;
+}
+export function protectivePathTargetOf(call) {
+    return call.face?.pathTarget ?? pathTargetOf(call.toolName);
+}
+export function declaredPathTargetOf(call) {
+    return call.face !== undefined ? call.face.pathTarget : pathTargetOf(call.toolName);
+}
+export function isProtectedWrite(call) {
+    const pt = protectivePathTargetOf(call);
+    return pt !== undefined && pt.access !== "read";
+}
+export function isDeclaredWrite(call) {
+    const pt = declaredPathTargetOf(call);
+    return pt !== undefined && pt.access !== "read";
+}
+export function fileOpAccessOf(name) {
+    for (const e of TOOL_CATALOG_ENTRIES) {
+        if (e.name === name && (e.face.family === "file-read" || e.face.family === "file-write") && e.face.pathTarget !== undefined)
+            return e.face.pathTarget.access;
+    }
+    return undefined;
+}
+export function pathTargetOf(name) {
+    for (const e of TOOL_CATALOG_ENTRIES)
+        if (e.name === name && e.face.pathTarget !== undefined)
+            return e.face.pathTarget;
+    return undefined;
+}
+export function catalogRuleFaceOf(name) {
+    for (const e of TOOL_CATALOG_ENTRIES) {
+        if (e.name !== 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])] } : {}) };
+    }
+    return undefined;
+}
+export function handBandEffects() {
+    const out = new Map();
+    for (const e of TOOL_CATALOG_ENTRIES) {
+        if (!e.mountedBy.includes("hands"))
+            continue;
+        const eff = e.face.effect ?? "write";
+        const prior = out.get(e.name);
+        if (prior === undefined || prior === "read")
+            out.set(e.name, eff);
+    }
+    return out;
+}
+export function engineCardTypes() {
+    const out = new Set(Object.keys(ENGINE_CARDS));
+    for (const e of TOOL_CATALOG_ENTRIES)
+        for (const card of e.cards)
+            out.add(card);
+    return out;
+}
+export function predictMountedToolNames(active) {
+    return names((e) => e.mountedBy.some((t) => active.has(t)));
+}
+export const TOOL_MOUNT_TAG_SET = new Set(TOOL_MOUNT_TAGS);
+export { HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND } from "./tool-face.js";

package/dist/core/tool-result-budget.d.ts

@@ -46,8 +46,5 @@ export interface AggregateBudgetOptions {
         results: number;
     }) => void;
 }
-/** Default exemptions: tools whose result is self-bounded (read_file errors at its own token cap; the
- *  offload reader pages small slices). grep/bash/glob/web_fetch/MCP are the risk sources, NOT exempt. */
-export declare const DEFAULT_BUDGET_EXEMPT_TOOLS: ReadonlySet<string>;
 /** Cap each over-budget turn-batch (run of consecutive tool_result messages). Request-only; see file docs. */
 export declare function capAggregateToolResults(messages: AgentMessage[], opts: AggregateBudgetOptions): Promise<AgentMessage[]>;

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

@@ -1,5 +1,6 @@
 import { isToolResult } from "./message-utils.js";
-import { buildPreview, buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX, toolResultContentSegment, toolResultProvenanceOf, } from "./tool-result-store.js";
+import { buildPreview, buildToolResultRef, PERSISTED_OUTPUT_PREFIX, toolResultContentSegment, toolResultProvenanceOf, } from "./tool-result-store.js";
+import { budgetExemptToolNames } from "./tool-registry.js";
 export const AGGREGATE_TOOL_RESULT_BUDGET_CHARS = 200_000;
 const HEAD = 1_000;
 const TAIL = 1_000;
@@ -33,10 +34,10 @@ function truncationPreview(full, head = HEAD, tail = TAIL) {
         `…[${total} chars total; ${tailStart - head} omitted to fit the per-turn result budget — re-run with a narrower query to see the rest.]\n` +
         `${full.slice(tailStart)}`);
 }
-export const DEFAULT_BUDGET_EXEMPT_TOOLS = new Set(["Read", OFFLOAD_TOOL_NAME]);
+const CATALOG_BUDGET_EXEMPT_TOOLS = budgetExemptToolNames();
 export async function capAggregateToolResults(messages, opts) {
     const budget = opts.budgetChars ?? AGGREGATE_TOOL_RESULT_BUDGET_CHARS;
-    const exempt = opts.exemptTools ?? DEFAULT_BUDGET_EXEMPT_TOOLS;
+    const exempt = opts.exemptTools ?? CATALOG_BUDGET_EXEMPT_TOOLS;
     let out;
     let i = 0;
     while (i < messages.length) {

package/dist/core/tool-result-store.d.ts

@@ -446,24 +446,6 @@ export declare function offloadPagebackHint(ref: string, form: "preview" | "clea
 export declare const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 /** Default per-result offload threshold (chars). ~5K tokens; configurable globally or per tool. */
 export declare const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20000;
-/**
- * CC 198 per-tool persistence thresholds, mirrored for the first-party mounts (PARITY-SPOT-USAGE-CONSTANTS
- * 2026-07-10 F1/F2). CC's GIa framework (pretty.js:286716-286721) resolves each tool's persist threshold as
- * `min(maxResultSizeChars, w6t=50000)`:
- *   - Read declares `maxResultSizeChars: 1/0` (:478260) → **never persisted**. Read already owns its bound
- *     (25K-token first-page auto-pagination) and the aggregate budget exempts it — wrapping it in offload
- *     re-truncated a page the tool had already sized (the F1 two-layer inconsistency). Structural exemption:
- *     applies even when a deployment sets an explicit global threshold.
- *   - Bash 30000 (:335231) / Grep 20000 (:333220) / Monitor 1e4 (:450030); everything else first-party
- *     declares 1e5 (Agent :453402, Glob :333570, TaskOutput :458260, …) → min(1e5, 50000) = 50000.
- * Unknown tools keep the deployment default ({@link DEFAULT_TOOL_RESULT_THRESHOLD_CHARS}) — we deliberately
- * do NOT mirror KIa's bare `$xa=400000` undeclared-tool fallback: our aggregate budget is 200K chars, so a
- * 400K inline result is unrepresentable anyway.
- */
-export declare function firstPartyOffloadPolicy(toolName: string): {
-    offload?: boolean;
-    offloadThresholdChars?: number;
-};
 /** Head+tail preview of an offloaded result, pointing at {@link OFFLOAD_TOOL_NAME} via `ref`. Exported so
  *  the per-message aggregate budget (design/64 §17.2) produces the SAME preview format (deterministic →
  *  byte-identical across queries → prompt-cache safe).

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

@@ -4,6 +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";
 export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
 export class ToolResultRefConflictError extends Error {
     ref;
@@ -202,22 +203,6 @@ export function offloadPagebackHint(ref, form, reachableTools) {
 }
 export const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 export const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20_000;
-export function firstPartyOffloadPolicy(toolName) {
-    switch (toolName) {
-        case "Read":
-            return { offload: false };
-        case "Write":
-            return { offload: false };
-        case "Bash":
-            return { offloadThresholdChars: 30_000 };
-        case "Grep":
-            return { offloadThresholdChars: 20_000 };
-        case "Monitor":
-            return { offloadThresholdChars: 10_000 };
-        default:
-            return { offloadThresholdChars: 50_000 };
-    }
-}
 const PREVIEW_HEAD_CHARS = 1_000;
 const PREVIEW_TAIL_CHARS = 1_000;
 const READ_DEFAULT_LIMIT = 4_000;
@@ -398,7 +383,7 @@ async function offloadOversizedDetailStrings(details, store, thresholdChars, ses
 export function createReadToolResultTool(store) {
     return defineTool({
         name: OFFLOAD_TOOL_NAME,
-        contract: { contractId: "core.read_tool_result@1", implementationRevision: "1" },
+        ...toolFace("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({
@@ -406,7 +391,6 @@ export function createReadToolResultTool(store) {
             offset: Type.Optional(Type.Number({ description: "Char offset to start at (default 0)." })),
             limit: Type.Optional(Type.Number({ description: `Max chars to return (default ${READ_DEFAULT_LIMIT}, capped ${READ_MAX_LIMIT}).` })),
         }),
-        effect: "read",
         execute: async (args) => {
             const { ref, offset, limit } = args;
             const off = Math.max(0, intOr(offset, 0));