@sema-agent/core 7.7.0 → 7.8.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 7.8.0 — 2026-09-08
+
+One roster instead of 29 name tables. `ToolSpec` already described a tool completely; the engine, the server and the shells still re-asserted each tool's identity and axes by NAME in hand-kept tables (a retired name lived on as a key in five of them). This version mints ONE effect roster per prepared leg from the mounted instances, derives every remaining table from a static catalog, and closes the mount array behind a builder.
+
+### BREAKING
+- `HAND_TOOL_EFFECTS`, `DEFAULT_BUDGET_EXEMPT_TOOLS`, `COMPACTABLE_TOOLS` leave `src/index.ts` (B1). Replacement: `describeToolCatalog()` — the hand band is `.filter((e) => e.mountedBy.includes("hands"))` (or `handBandEffects()`), the two policy sets `budgetExemptToolNames()` / `compactableToolNames()`. A host deriving its hand band (server `HANDS_BAND_TOOL_NAMES`) derives it over `HANDS_BAND_TAGS`; the derived band equals today's server list plus `ListAgents` (the peer-lane definition the hand-kept list predates) — the server's list is the stale side.
+- `Prepared.tools` is `readonly AgentTool[]` (the builder's read face); a prepare phase that wrote the array takes `roster: RosterBuilder`.
+
+### Narrowings (each a two-arm pin)
+- **B6/B17** — the policy faces read the call's OBJECT face (`ToolCallRequest.face`, stamped at the gate entry off the live roster and carried through the fold's re-mint over the final args). The active-skill `allowPaths` face judges `pathTarget.skillScopeEligible` and confines the DECLARED target's value (`pathTargetValue`: the face's `param` + aliases — an in-fence `file_path` beside an out-of-fence declared param is a decoy, not the write; a declared param absent from the args is denied as unresolvable): a bare request (a policy invoked outside a Runner) or a caller tool that merely took a built-in's name (`Write`) is an unconfirmable write and is denied where it used to pass by name. The transcript-directory gate reads the face and falls back to the catalog's declaration for the name (never wider than 7.7.0).
+- **B15** — the permission-rule lint's diagnostic set is closed: `unsupported.param_unknown` (renamed from `unsupported.unknown_param`), `unsupported.param_non_scalar` (`Edit(edits:…)` and every carried object/array key), `unsupported.tool_unknown` (only under a leg-supplied `ruleFaces` resolver — `ruleFacesFromRoster(prepared.toolRoster)`; without one the catalog alone judges and an unknown tool stays permissive). `RuleFaceView` / `catalogRuleFaceView` / `PermissionRulePolicyOptions.ruleFaces` are the seats.
+- **B14** — the micro-compaction whitelist is derived from the catalog's `compactable` declarations: eight members, no `PowerShell` row (no sema definition ever carried the name).
+- **B20** — a caller tool name / alias over 128 characters, or a contract member over 64, is refused typed at prepare (`config.tool_name_too_long` / `config.tool_contract_too_long`); an MCP assembled name can never exceed the bound — the namespacing helper already budgets it (peer segment absorbs the clamp, digest-suffixed; provider bound 64), so the design's "drop that tool" arm is satisfied by construction and no drop arm exists (design/388 S49's "core has no bound on the synthetic name" premise is stale as of RB-83/RB-107).
+- The compaction file-op summary reads the live names' path access off the catalog and the three pre-rename names off the frozen `DURABLE_HISTORY_NAMES`; a persisted `MultiEdit` block contributes no file-op metadata any more (the retired name is a key nowhere — G3).
+- **Every write fence judges the call's DECLARED slot** — two named readers for the two kinds of fence, shared by all of them (`writeTargetPath(call, target)`): a DENY-LIST (sensitive paths, frozen paths, write protection, the transcript gate, edit tracking) reads `protectivePathTargetOf` — the object face's declaration first, the catalog's declaration for the NAME as the floor (a bare request, or a face that declares none): reading the catalog for an undeclared same-name tool can only tighten a deny-list (the pre-388 posture, never wider). A GRANT that admits a write BY its path (session `allowDirs`, the fs-write gate's accept/exempt dirs, the active-skill allowPaths eligibility) reads `declaredPathTargetOf` — the face's OWN declaration only: a same-name tool that declares no path target is an unconfirmable write and the fence fails closed (allowDirs denies "declares no path target to confine"; the fs-write gate asks; the catalog's slot never buys an admission); a bare request (no face at all — a policy invoked outside a Runner) reads the catalog for the name. `isProtectedWrite` / `isDeclaredWrite` are the two membership predicates. The sensitive-path guard's DEFAULT membership is the same predicate (a caller tool under any name whose face declares a write target is guarded); an explicit `tools` list stays a name list. A decoy `file_path` beside an out-of-fence declared param is not the target; a declared param absent from the args is "no resolvable path" (containment fences deny/ask as they always did for an unresolvable write; the additive deny-lists — sensitive paths, frozen paths — see no target and pass, as their unresolvable arm always did). The cross-slot fallback that once read `notebook_path` for a Write, or `file_path` for a NotebookEdit, is gone (the tool's own schema refuses such a call before any write).
+- **Merge-seam adversarial rounds (codex r1/r2 over the merged 388 × 393 S1/S2 × #602 tree)** — (H1) the durable resume-edit rechecks judge under the call's face: the park row carries `family` + `pathTarget` beside its B18 identity members (additive optional; `parkedToolFace` mints them at the same station, `parkedCallFaceOf` rebuilds the face — present iff face + all four identity members are on the row), the pre-CAS recheck judges the edited args under the ROW face and the two post-CAS rechecks under the live roster face; a decoy in-fence `file_path` beside an out-of-fence declared `destination` is refused `resume.constraint_rejected` pre-CAS (the checkpoint stays pending). **@server**: two additive optional keys on the checkpoint row (JSON rows: zero DDL); the store-contract kit gained a seven-member round-trip run your pg store must pass. (H2) MCP intake keys the overlay's results by tool NAME — a tool the overlay refused is not mounted at all (previously an index pairing mounted it bare and shifted later tools onto a neighbour's face). (F2) the `resume` identity arm is wired (see the disclosure below): a same-name tool whose contract / shape / revision differ from the parked row's is refused `resume.tool_contract_mismatch` through the non-executing reopen path (`tool_unavailable` family), never executed under the new face. (F3) the park-time projection re-adjudication (a JSON-fidelity store moving the args) carries the call face too. Two review proposals were REJECTED on the documented contract (#549 ①, HRD-PRM-1, #286, CLS-C-4): protective fences judge the tool's declared/catalog slot only — no "legacy spelling floor" when the slot is empty and no "judge every candidate" union; a caller whose implementation writes another slot declares its face.
+- **B20 (keys)** — a schema property name is a SEMANTIC key every fence reads by and is never truncated on a roster row: a caller declaration over `TOOL_KEY_MAX_CHARS` (256) or `TOOL_KEYS_MAX` (1024 keys) is refused typed at prepare (`config.tool_schema_bound`); a caller face that does not fit its schema (a `pathTarget.param` outside the top-level keys, a `ruleFace` param outside the derived vocabulary — scalar keys ∪ the declared path target's param + aliases —, an approval card whose required keys are missing, a declared key or display hint over its bound) is refused `config.tool_face_invalid`; no display hint is truncated on a row either — the same validator the MCP `toolFaces` overlay passes; an MCP tool whose schema breaks the key bound is dropped with a disclosed reason (its siblings mount). `writeProtectionCheck(toolName, args, face?)` gains the call's face (additive).
+- The sensitive-path guard / frozen-path deny / edited-file tracking / `allowDirs` all derive their covered set from the catalog's path targets: `MultiEdit` is no longer a member of any of them (it mounts nowhere).
+
+### Added
+- `ToolSpec.family` / `pathTarget` / `ruleFace` / `renderHints` / `compactable` / `budgetExempt` (additive; `defineTool` forwards them + `modelGate` onto the materialized face); `TaskSpec.excludeAllTools: true` (the whole face unmounts; `"*"` stays a legal caller name); `McpServerSpec.toolFaces` (a per-tool face overlay for MCP tools, validated against the materialized schema at every listing).
+- The tool FACE vocabulary (`TOOL_FAMILIES`, `TOOL_MOUNT_TAGS`, `TOOL_APPROVAL_CARDS`, `TOOL_PATH_ACCESSES`, the render-hint bounds, `TOOL_WIRE_NAME_MAX_CHARS` / `TOOL_CONTRACT_MAX_CHARS`, `ToolPathTarget` / `ToolRuleFace` / `ToolRenderHints` / `ToolFaceDeclaration` / `ToolCatalogEntry`), the static catalog (`describeToolCatalog`, `catalogEntriesNamed`, `catalogToolNames`, `catalogRuleFaceOf`, `pathTargetOf`, `pathTargetValue`, the derived predicates, `engineCardTypes`, `predictMountedToolNames`, `HANDS_BAND_TAGS` / `MOUNT_TAG_IN_HANDS_BAND`), the roster (`ToolRosterEntry` / `ToolRoster` / `ToolRosterDelta` / `ToolRosterRenderHints` as typebox schemas AND `Static` types, `ROSTER_SOURCES`, `mintCapabilityId`, `toolIdentityOf`, `diffToolRoster`, `judgeParkedToolIdentity`, `parkedToolIdentity`, `ruleFacesFromRoster`, `toolCallFaceOf`, `inputKeysOf`, `ruleFaceOfInstance`, `ToolRosterDeltaSeat`), `TOOL_CONFORMANCE_VECTORS` / `describeToolConformanceVectors`, `applyMcpToolFaces` / `toolFaceProblem` / `APPROVAL_CARD_REQUIRED_KEYS`, `createStructuredProjector`, `ASK_USER_QUESTION_TOOL_NAME` (B5), `DURABLE_HISTORY_NAMES`.
+- **Wire (@server @cli @client-core @web-admin @desktop)**: `WiringManifest.tools?: ToolRoster` on every effective manifest (OUTSIDE `configFingerprint`; `schemaVersion` unchanged); `TaskEvent` arm `tool_roster_delta { delta: ToolRosterDelta }` (a run-time roster change: the whole post-change roster + a summary usable when the consumer holds `fromDigest`; a mismatch means adopt the snapshot, never reject); `ToolCallRequest.face?: ToolCallFace`; `FsWriteGateWiring.isExempt(toolName, canonicalPath, identity?)` (B22 — the identity triple beside the name for a store keyed on `capabilityId`); `PendingAction{kind:"tool_approval"}` gains `capabilityId? / contractId? / shapeDigest? / implementationRevision? / rosterDigest?` (B18; additive, no checkpoint-version bump; a row without them follows the name-only path); three `engine_notice` codes (B2, audience operator): `config.tool_card_undeclared`, `config.tool_face_undeclared`, `config.tool_face_invalid`.
+- Gates (all in `gate:all`): `gate:tool-catalog` (every core-owned definition spreads its catalog face; a face under another name, a ghost id, a row without family, a card minted by a file that does not list it — red, named), `gate:tool-names` (L1: every retained tool-name table registered in `docs/TOOL-NAME-TABLES.json`, disjoint from the retired names, inside the catalog), `gate:tool-docs` (the `ToolSpec` field reference in docs/sdk/04 is generated from the declaration — `scripts/gen-tool-spec-fields.mjs --check`). `ToolMountTag` registered in `docs/CLOSED-SETS.md`.
+- The catalog is data: every row is deep-frozen at module init and `toolFace(id)` hands out a deep COPY — two factory products never share a `pathTarget`, and a host adapting one instance's face cannot move another run's fences (or the catalog).
+- An MCP `toolFaces` overlay that does not fit the tool's materialized schema (at intake or after a refresh) means the tool is NOT mounted on that leg — announced once (`config.tool_face_invalid`); it never mounts bare (a bare mount would silently drop the write protection the operator declared, and an MCP name has no catalog floor). The approval-edit re-check and the edit ask carry the stamped face (a decoy in an approved edit is confined by the declared slot).
+- A deferred tool's placeholder carries the real tool's `aliases` (dispatch by alias resolves to the same slot before and after activation, the roster's name→row resolution agrees with the dispatcher's — wire name first, then alias, in mount order — and a transcript call under an alias activates the canonical entry on replay). The MCP `toolFaces` overlay binds to the RAW accepted tool name (`Tool.mcpRemoteName`, a typed carry the materializer stamps): two raw spellings folding onto one minted name cannot make a face land on the other tool — the unaccepted spelling is announced undeclared. `TOOL_KEY_MAX_CHARS` / `TOOL_KEYS_MAX`; `ToolCallLike` / `callPathTargetOf` / `isPathConfinableWrite` / `fileOpAccessOf` (the compaction summary records file ops for the FILE families only — a search tool's `path` is a root, not a file read).
+- The roster carries every name the model can call: the ToolSearch instance the deferred lane appends to the harness list rides the roster's ENGINE LANE (`RosterBuilder.mountEngineLane`) as the trailing row, minted after the disclosure lane (which reads the mount array and never writes it) — the prompt manifest's tool rows are the mount array; the roster is that plus the engine lane. The effect map follows the instance the harness dispatches to (a later same-name mount's declared effect is the name's truth). `gate:tool-catalog` rule ②b: a resolvable `defineTool({ name })` with no catalog row is red (per-file `HOST_FACTORY_DEFINITIONS` exemption list, empty today).
+
+### Not wired in 7.8.0 — three runtask.ts seams deferred to design/393 S3 (the seats are minted; the driver does not yet consume them)
+- **Disclosure**: the three items below are the driver-side half of this slice. In 7.8.0 the roster, its delta seat and the structured projector all exist and are pinned at the seat/function level, but runtask.ts (design/393's domain, being decomposed in parallel) does not yet call them: no `tool_roster_delta` frame is pushed and `tool_end` still projects through the module-level card set. A consumer must not rely on `tool_roster_delta` frames until the version that lands 393 S3. (The `resume` identity arm — `judgeParkedToolIdentity` minting `resume.tool_contract_mismatch` — IS wired in 7.8.0: the merge-seam adversarial round showed a same-name replacement executing under a different face once the rechecks read faces, so it did not wait for S3.)
+- `tool_end`: the body projection reads `prepared.structuredProjector` (the per-leg card set + the once-per-leg announce) in place of the module-level `structuredFrom` (tool-end-body.ts:77 via runtask).
+- `wiring_manifest`: beside the manifest push (runtask.ts ≈:4149) subscribe `prepared.toolRosterDeltas.subscribe((delta) => queue.push({ type: "tool_roster_delta", delta, ...ident() }))`.
+
+### Pins
+- `test/tool-catalog.test.ts` (L5 snapshots + the gate's discriminance), `test/tool-roster.test.ts` (the builder, the row mint, the delta seat, G1 / G5 / G6 / G6c / G6e), `test/tool-conformance.test.ts` (L3 over four vectors on a real NodeExecutionEnv, L6 lockstep + every param matches, L4's once-per-leg announce, G6d), the retired-table tests re-pointed at the catalog.
+
 ## 7.7.0 — 2026-09-07
 
 One version for the first refactor wave and its bug fixes (the 7.6.2 patch folded in: main already carries the store-contract change, so the fix ships with it). #618 / B-040: The classifier request shape changes on the wire; the explicit "off" tier changes on both brain lanes.

package/dist/agents/agent-transcript-tool.js

@@ -6,14 +6,14 @@ import { inlineUntrusted } from "../core/untrusted-text.js";
 import { stepsFromMessages } from "./subagent-steps.js";
 import { REPORT_FIELD_MAX } from "./subagent.js";
 import { getSessionRetainLedger } from "./retain-ledger.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export const AGENT_TRANSCRIPT_TOOL_NAME = "AgentTranscript";
 const AGENT_TRANSCRIPT_DEFAULT_N = 20;
 const AGENT_TRANSCRIPT_MAX_N = 50;
 export function createAgentTranscriptTool(opts) {
     return defineTool({
         name: AGENT_TRANSCRIPT_TOOL_NAME,
-        contract: { contractId: "core.agent_transcript@1", implementationRevision: "1" },
-        effect: "read",
+        ...toolFace("agent-transcript"),
         description: `Read the recent tool steps of a background agent you launched (task_id 'a…' from the Agent tool with ` +
             `run_in_background), so you can see precisely where it got to — useful before SendMessage-ing a follow-up, ` +
             `or to inspect a stopped agent's tail. Returns the last N steps (tool, target, outcome); it does not re-run ` +

package/dist/agents/list-agents-tool.js

@@ -4,15 +4,14 @@ import { inlineUntrusted } from "../core/untrusted-text.js";
 import { formatPeerNameRef } from "./cross-session-ref.js";
 import { entryAccessible } from "./roster-store.js";
 import { mintPeerSessionCandidates, peerSessionBoxHandle } from "./peer-directory.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export const LIST_AGENTS_TOOL_NAME = "ListAgents";
 export const LIST_AGENTS_TOOL_ALIAS = "ListPeers";
 export const LIST_AGENTS_MAX_RESULT_CHARS = 10_000;
 export function createListAgentsTool(opts) {
     return defineTool({
         name: LIST_AGENTS_TOOL_NAME,
-        aliases: [LIST_AGENTS_TOOL_ALIAS],
-        contract: { contractId: "core.list_agents@1", implementationRevision: "1" },
-        effect: "read",
+        ...toolFace("list-agents"),
         isConcurrencySafe: () => true,
         description: `List the agents and peer sessions you can message with SendMessage. Peer sessions are other sessions of this ` +
             `engine running for the same user on this machine, shown as \`name [ref]\`; send to one with its name (or \`name [ref]\` ` +

package/dist/agents/observer.js

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { defineTool } from "../core/tools.js";
 import { createSafeNotifier } from "../core/safe-notify.js";
 import { escapeEnvelopeTag } from "../core/untrusted-text.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export const OBSERVER_EVENT_TAGS = ["tool-call", "user-message", "tool-result", "turn-ended"];
 const TAG_ESCAPE_RE = new RegExp(`<(?=/?(?:${OBSERVER_EVENT_TAGS.join("|")})(?:[>\\s/]|$))`, "gi");
 export function escapeObserverTags(text) {
@@ -377,9 +378,8 @@ export function frameObserverReport(observerAgentName, report) {
 export function createObserverReportToolSpec(opts) {
     return {
         name: OBSERVER_REPORT_TOOL_NAME,
-        contract: { contractId: "core.observer_report@1", implementationRevision: "1" },
+        ...toolFace("observer-report"),
         description: OBSERVER_REPORT_DESCRIPTION,
-        effect: "write",
         parameters: Type.Object({
             report: Type.String({
                 minLength: 1,

package/dist/agents/send-message-tool.js

@@ -14,6 +14,7 @@ import { neutralizePeerBody } from "./cross-session-envelope.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
 import { createSubagentResume } from "./subagent.js";
 import { appendHopToken, judgePeerAdmission, peerAxisToken, resolvePeerAdmissionConfig, PEER_MESSAGE_NOTICE, } from "./peer-admission.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export const SEND_MESSAGE_TOOL_NAME = "SendMessage";
 let uplinkSeqGlobal = Date.now();
 const UPLINK_RESULT_MAX = 8000;
@@ -134,7 +135,7 @@ export function createSendMessageTool(opts) {
     };
     return defineTool({
         name: SEND_MESSAGE_TOOL_NAME,
-        contract: { contractId: "core.send_message@1", implementationRevision: "1" },
+        ...toolFace("send-message"),
         executionMode: "parallel",
         description: `Send a follow-up message to a previously spawned background agent. ` +
             `Your plain text output is NOT visible to other agents — to communicate, you MUST call this tool. Messages addressed to you are delivered automatically; you don't check an inbox. ` +

package/dist/agents/subagent-steps.js

@@ -1,8 +1,9 @@
 import { redactSecrets } from "../core/untrusted-egress.js";
+import { isProtectedWrite } from "../core/tool-registry.js";
+import { writeTargetPath } from "../tools/fs/safety.js";
 export const STEP_CAP = 10;
 const FIELD_MAX = 80;
 const EDITED_FILES_CAP = 32;
-const EDITING_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
 function firstLine(s) {
     const nl = s.indexOf("\n");
     return nl === -1 ? s : s.slice(0, nl);
@@ -57,10 +58,10 @@ export function extractTarget(args) {
     }
 }
 function editTargetPath(toolName, args) {
-    if (!EDITING_TOOLS.has(toolName) || args === null || typeof args !== "object")
+    const call = { toolName, args };
+    if (!isProtectedWrite(call) || args === null || typeof args !== "object")
         return undefined;
-    const a = args;
-    const p = a.file_path ?? a.path ?? a.notebook_path;
+    const p = writeTargetPath(call);
     return typeof p === "string" && p.length > 0 ? p : undefined;
 }
 function outputFirstLine(output) {

package/dist/agents/subagent.js

@@ -60,6 +60,7 @@ import { recordRosterSpawn } from "./roster-store.js";
 import { LAUNCH_RECEIPT_OWN_WORDS_CLAUSE, launchReceiptNoQuoteClause } from "./launch-receipt-contract.js";
 import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, ObserverResumeStateError, ObserverStoppedByUserError, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
 import { SubagentStepRecorder } from "./subagent-steps.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 const BG_AGENT_RESULT_MAX = 4_000;
 const BG_AGENT_RESULT_FULL_MAX = 200_000;
 function resultSettleFields(result) {
@@ -243,7 +244,6 @@ function createToolStatsCounter(delegationToolName) {
                         t.bashCount++;
                         break;
                     case "Edit":
-                    case "MultiEdit":
                         t.editFileCount++;
                         recordEditLines(args);
                         break;
@@ -1392,13 +1392,12 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
         }));
     return {
         name: opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME,
+        ...toolFace("agent"),
         agentListing,
         agentToolFaces,
         ...(agentToolPool !== undefined ? { agentToolPool } : {}),
-        contentOrigin: "local",
         ...(rosterNames !== undefined ? { agentModels: rosterNames } : {}),
         executionMode: "parallel",
-        contract: { contractId: "core.agent@1", implementationRevision: "1" },
         description: `Launch a new agent to handle complex, multi-step tasks. Each agent type has specific capabilities and tools available to it.\n` +
             (opts.purpose ? `\nThis sub-agent is for: ${opts.purpose}.\n` : "") +
             (hasAgents ? `\nAvailable agent types are listed in <system-reminder> messages in the conversation.\n` : "") +

package/dist/core/ask-question.js

@@ -3,6 +3,7 @@ import { uuidv7 } from "../engine/session/uuid.js";
 import { boundInputHashOf } from "./canonical-json.js";
 import { defineTool, errorResult } from "./tools.js";
 import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";
+import { toolFace } from "./tool-catalog-entries.js";
 export const ASK_USER_QUESTION_TOOL_NAME = "AskUserQuestion";
 export function classifyQuestionOutcome(outcome) {
     let unavailable;
@@ -170,7 +171,7 @@ export function createAskUserQuestionTool(onQuestion, source, opts) {
     const continuationCard = askQuestionContinuationCard;
     return defineTool({
         name: ASK_USER_QUESTION_TOOL_NAME,
-        contract: { contractId: "core.ask_user_question@1", implementationRevision: "1" },
+        ...toolFace("ask-user-question"),
         description: "Ask the user a structured multiple-choice question when you are genuinely stuck or a decision is " +
             "the user's to make (which approach, which of these). Provide 1-4 questions, each with 2-4 options " +
             "(label + description). Use sparingly — not for anything you can determine yourself from the code or " +
@@ -226,7 +227,6 @@ export function createAskUserQuestionTool(onQuestion, source, opts) {
                 })),
             }), { minItems: 1, maxItems: 4, description: "Questions to ask the user (1-4 questions)" }),
         }),
-        effect: "read",
         executionMode: "sequential",
         execute: async (args, ctx) => {
             const { questions } = args;

package/dist/core/checkpoint-store.d.ts

@@ -822,6 +822,36 @@ export type PendingAction = {
      * pre-1a.2 checkpoint (deserialized without it), in which case the resume skips the hash check.
      */
     boundInputHash: string;
+    /**
+     * design/388 §2.5 boundary ② (B18; additive — no checkpoint-version bump, the `previewWithheld`
+     * precedent: an optional group an older reader ignores): the IDENTITY of the row the park minted
+     * this action against, read off the leg's tool roster at the suspend station — `capabilityId`
+     * (engine-minted over {source, peer, name, contractId}), `contractId`, `shapeDigest`,
+     * `implementationRevision` — plus the roster `digest` of the leg that parked. The resume finds the
+     * same-name row on ITS leg and compares the FOUR identity members (`judgeParkedToolIdentity`): any
+     * mismatch is a replacement wearing the name and the resume refuses it
+     * (`resume.tool_contract_mismatch`, the `tool_unavailable` reopen family). All four ABSENT ⇒ a row
+     * minted before the members existed ⇒ the name-only path, never widened by their absence.
+     */
+    capabilityId?: string;
+    contractId?: string;
+    shapeDigest?: string;
+    implementationRevision?: string;
+    rosterDigest?: string;
+    /**
+     * design/388 B6 × B18 (additive; the identity group's precedent): the FACE the parked call was judged under —
+     * display `family` + declared `pathTarget` — off the same roster row at the same mint. The pre-CAS resume-edit
+     * recheck has no roster yet; it rebuilds the call face from these (`parkedCallFaceOf`) and judges the edit as
+     * the live gate judged the original (merge-seam H1: without them a caller slot fell to the catalog's slot for
+     * the NAME). Any member absent ⇒ pre-388 row ⇒ the recheck falls to the catalog, never a widened grant.
+     */
+    family?: import("./tool-face.js").ToolFamily;
+    pathTarget?: {
+        param: string;
+        aliases: string[];
+        access: "read" | "create" | "edit";
+        skillScopeEligible: boolean;
+    };
     /**
      * #438 (additive; no checkpoint-version bump — the `reminderMark` precedent: an optional field an
      * older reader ignores. Unlike that precedent seat — which resume DOES read, through its
@@ -2119,11 +2149,13 @@ export declare class CheckpointError extends Error {
          *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
          *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
          *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
-         *     (retryable on an org-wired worker).
+         *     (retryable on an org-wired worker), `"origin_missing"` (a pending approval row minted
+         *     before the ask's origin was persisted on the park — terminal for the row's bytes; the host
+         *     decides the orphaned card itself, no worker version redeems it).
          *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
          *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
          *     current bytes — no worker version redeems a damaged row). */
-        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "origin_missing" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
     } | undefined;
     constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found"
     /** `runner.resume` was handed an {@link ResumeOutcome} whose `gate` arm does not match the
@@ -2305,11 +2337,13 @@ export declare class CheckpointError extends Error {
          *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
          *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
          *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
-         *     (retryable on an org-wired worker).
+         *     (retryable on an org-wired worker), `"origin_missing"` (a pending approval row minted
+         *     before the ask's origin was persisted on the park — terminal for the row's bytes; the host
+         *     decides the orphaned card itself, no worker version redeems it).
          *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
          *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
          *     current bytes — no worker version redeems a damaged row). */
-        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "origin_missing" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
     } | undefined);
 }
 /**

package/dist/core/context-edit.d.ts

@@ -130,28 +130,6 @@ export declare const MIN_CLEAR_SAVINGS_TOKENS = 20000;
 /** Minimum kept results — CC `EUs` :397710 `Math.max(1, keepRecent)`. See
  *  {@link ContextEditOptions.keepRecentToolResults} for why both degenerate ends are unusable. */
 export declare const MIN_KEEP_RECENT_TOOL_RESULTS = 1;
-/**
- * checklist #54 (CC microCompact.ts:41-50 `COMPACTABLE_TOOLS` parity): the INCLUSION whitelist of
- * tools whose results may be content-cleared by the stale-result pass. CC's set is exactly
- * { Read, Bash, PowerShell (SHELL_TOOL_NAMES), Grep, Glob, WebSearch, WebFetch, Edit, Write } —
- * cheap-to-regenerate I/O.
- *
- * RE-VERIFIED against the 2.1.250 corpus (design/374 slice 4, member-by-member — a set is exactly
- * the shape where "the count still matches" is not evidence): `eQt = new Set([wt, ...VD, Yo, Xo,
- * yO, Yr, tn, er])` at cli250.js:41714, whose aliases resolve to `wt`="Read", `VD`=[`Xe`="Bash",
- * `Nt`="PowerShell"], `Yo`="Grep", `Xo`="Glob", `yO`="WebSearch", `Yr`="WebFetch", `tn`="Edit",
- * `er`="Write" — nine members, byte-identical to the set below, zero drift from the 223 reading.
- * The exclusion side is the load-bearing half and is unchanged too: everything NOT here is
- * PRESERVED (Agent/Task/Skill/ToolSearch/TodoWrite/Monitor/SendMessage/NotebookEdit and ALL MCP
- * tools are never content-cleared by this pass, upstream or here).
- *
- * Everything else is PRESERVED: expensive/decision-bearing results
- * (Agent subagent reports, Task* registry state, TodoWrite acks, Monitor, MCP tools, custom
- * ToolSpecs) survive to the harder defenses (compaction summarizes them instead of blanking them).
- * PowerShell is kept for CC fidelity even though sema does not mount it. Overridable per call via
- * {@link ContextEditOptions.compactableTools} for custom-tool-heavy embedders.
- */
-export declare const COMPACTABLE_TOOLS: ReadonlySet<string>;
 export interface ContextEditOptions {
     /** Start clearing once estimated context tokens exceed this. */
     budgetTokens: number;

package/dist/core/context-edit.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
 import { isToolResult } from "./message-utils.js";
 import { PERSISTED_OUTPUT_PREFIX, offloadPagebackHint } from "./tool-result-store.js";
+import { compactableToolNames } from "./tool-registry.js";
 const CLEARED_MARKER = "[tool result cleared to save context]";
 const CC_CLEARED_MARKER = "[Old tool result content cleared]";
 const LEGACY_CLEARED_EXTENDED_PREFIX = "[tool result cleared to save context —";
@@ -46,17 +47,7 @@ function resolveKeepRecentToolResults(value, defaultValue) {
     }
     return Math.max(MIN_KEEP_RECENT_TOOL_RESULTS, value);
 }
-export const COMPACTABLE_TOOLS = new Set([
-    "Read",
-    "Bash",
-    "PowerShell",
-    "Grep",
-    "Glob",
-    "WebSearch",
-    "WebFetch",
-    "Edit",
-    "Write",
-]);
+const COMPACTABLE_TOOLS = compactableToolNames();
 function soleMarkerText(m) {
     const content = m.content;
     if (!Array.isArray(content) || content.length !== 1)

package/dist/core/engine-notice.d.ts

@@ -17,6 +17,12 @@ export interface EngineNotice {
      *    the value in force; `detail: { knob, raw, usedMs }`.
      *  - `"config.materialize_env_discarded"` — `SEMA_TOOL_MATERIALIZE_STRATEGY` held a value outside the
      *    closed set in a seat where it is not in force; `detail: { raw, specStrategy? }`.
+     *  - `"config.tool_card_undeclared"` (design/388 L4) — a tool minted a `details.type` card its definition
+     *    (or its caller declaration's `renderHints.resultCards`) never declared; the card was dropped from
+     *    `tool_end.structured`; once per leg per type; `detail: { type, sessionId, runId }`.
+     *  - `"config.tool_face_undeclared"` / `"config.tool_face_invalid"` (design/388 §2.7) — an MCP server's
+     *    `toolFaces` overlay names a tool the listing does not carry / does not fit the tool's materialized
+     *    schema (the tool mounts bare); once per leg per tool; `detail: { server, tool, problem?, sessionId, runId }`.
      *  - `"tool_result.offload_put_failed"` (#167) — a clear-with-offload persist's fire-and-forget put
      *    failed; THIS attempt stored nothing (the failure arm reports, it never re-inserts under the
      *    ref) — an earlier attempt of the same idempotent re-put may already have stored the row, so

package/dist/core/fs-write-gate-policy.d.ts

@@ -1,5 +1,11 @@
 import type { ExecutionEnv } from "../internal/harness-types.js";
 import type { ToolPolicy } from "./tool-policy.js";
+/** design/388 B22 — the identity triple the exemption probe hands the store beside the name. */
+export interface ToolCallIdentity {
+    capabilityId: string;
+    contractId: string;
+    shapeDigest: string;
+}
 /** Options for {@link createFsWriteGatePolicy}. */
 export interface FsWriteGatePolicyOptions {
     /** The task's real execution env (the one the hands run against) — canonicalization must see the
@@ -37,7 +43,7 @@ export interface FsWriteGatePolicyOptions {
      *    `combinePolicies` outranks this `allow` under the deny > ask > allow fold, and the two fail-closed
      *    asks for an UNRESOLVABLE target fire before any canonical key exists, so they are never exempted.
      */
-    isExempt?: (toolName: string, canonicalPath: string) => boolean | Promise<boolean>;
+    isExempt?: (toolName: string, canonicalPath: string, identity?: ToolCallIdentity) => boolean | Promise<boolean>;
     /**
      * design/380 O13 — the deployment HARD-CLOSE knob for guarded writes. Armed (`true`), a covered
      * write whose env does NOT provide `writeFileGuarded` is REFUSED (deny, typed message) — never the

package/dist/core/fs-write-gate-policy.js

@@ -1,9 +1,9 @@
 import { canonicalizeTarget, writeTargetPath } from "../tools/fs/safety.js";
-import { PATH_CONFINABLE_WRITE_TOOLS, isWithin } from "./runner/session-rule-policy.js";
+import { isWithin } from "./runner/session-rule-policy.js";
+import { declaredPathTargetOf, isProtectedWrite } from "./tool-registry.js";
 const ask = (message) => ({ action: "ask", message, decisionReason: "rule" });
 export function createFsWriteGatePolicy(opts) {
     const { env, rootPath, defaultWrite } = opts;
-    const gated = PATH_CONFINABLE_WRITE_TOOLS;
     const acceptDirs = opts.acceptDirs && opts.acceptDirs.length > 0 ? opts.acceptDirs : undefined;
     const exemptDirs = opts.exemptDirs && opts.exemptDirs.length > 0 ? opts.exemptDirs : undefined;
     const guardedCapable = env.writeFileGuarded !== undefined;
@@ -12,8 +12,7 @@ export function createFsWriteGatePolicy(opts) {
         : " (advisory adjudication: this environment provides no guarded write, so approval is judged before a separate, non-atomic write step)";
     return {
         async check(req, signal) {
-            const canonical = req.toolName;
-            if (!gated.has(canonical))
+            if (!isProtectedWrite(req))
                 return { action: "allow" };
             if (opts.requireGuardedWrite === true && !guardedCapable) {
                 return {
@@ -22,9 +21,10 @@ export function createFsWriteGatePolicy(opts) {
                     decisionReason: "rule",
                 };
             }
-            const path = writeTargetPath(canonical, req.args);
+            const declared = declaredPathTargetOf(req);
+            const path = declared === undefined ? undefined : writeTargetPath(req, declared);
             if (path === undefined) {
-                return ask(`write tool "${req.toolName}" requires approval: the call has no resolvable path target to confine${advisory}`);
+                return ask(`write tool "${req.toolName}" requires approval: the call has no resolvable path target to confine${declared === undefined ? " (the tool declares no path target)" : ""}${advisory}`);
             }
             const canon = await canonicalizeTarget(env, path, signal, req.cwd ?? rootPath);
             if (!canon.ok) {
@@ -42,7 +42,7 @@ export function createFsWriteGatePolicy(opts) {
             if (opts.isExempt) {
                 let exempt = false;
                 try {
-                    exempt = (await opts.isExempt(canonical, canon.key)) === true;
+                    exempt = (await opts.isExempt(req.toolName, canon.key, req.face !== undefined ? { capabilityId: req.face.capabilityId, contractId: req.face.contractId, shapeDigest: req.face.shapeDigest } : undefined)) === true;
                 }
                 catch {
                     exempt = false;

package/dist/core/gate-fold.js

@@ -30,7 +30,7 @@ function withProbeTimeout(p, ms, signal) {
 const DEFAULT_PROBE_TIMEOUT_MS = 30_000;
 export async function runGateFold(pass) {
     const { input, toolName, toolCallId, callSignal, ledger, notifier, adjudicate } = pass;
-    pass.req = { toolName, args: pass.currentInput, toolCallId };
+    pass.req = { toolName, args: pass.currentInput, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) };
     pass.decision = adjudicate ? await (callSignal !== undefined ? adjudicate(pass.req, callSignal) : adjudicate(pass.req)) : { action: "allow" };
     {
         const refusedBy = ledger.fromDecision(pass.decision);
@@ -144,7 +144,7 @@ export async function runGateFold(pass) {
         pass.tightenedBy = "safety";
     }
     if (pass.decision.action === "allow" && input.writeProtectionCheck !== undefined) {
-        const writeProtectedHit = input.writeProtectionCheck(toolName, pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput);
+        const writeProtectedHit = input.writeProtectionCheck(toolName, pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput, pass.req.face);
         if (writeProtectedHit !== null) {
             pass.decision = {
                 action: "ask",

package/dist/core/gate-lanes.js

@@ -548,7 +548,8 @@ export async function runGateLanes(pass) {
                     let recheck = { action: "allow" };
                     if (adjudicate) {
                         try {
-                            recheck = await (callSignal !== undefined ? adjudicate({ toolName, args: editArgs, toolCallId }, callSignal) : adjudicate({ toolName, args: editArgs, toolCallId }));
+                            const editReq = { toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) };
+                            recheck = await (callSignal !== undefined ? adjudicate(editReq, callSignal) : adjudicate(editReq));
                         }
                         catch (err) {
                             recheck = {
@@ -588,7 +589,7 @@ export async function runGateLanes(pass) {
                     }
                     const editAskSnapshot = { ...recheck, ruleEvidence: mintRuleEvidence({ dotsAbsent: "not_adjudicated" }) };
                     const editAskDecision = { ...editAskSnapshot, origin: askOriginOf(editAskSnapshot, askOriginFacts(editOrg.org)) };
-                    const editAskReq = { toolName, args: editArgs, toolCallId };
+                    const editAskReq = { toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) };
                     const rr = await (callSignal !== undefined ? resolveAsk(editAskDecision, editAskReq, callSignal) : resolveAsk(editAskDecision, editAskReq));
                     ledger.fromResolved(rr, editAskDecision, toolName);
                     if (rr.action !== "allow") {
@@ -606,7 +607,7 @@ export async function runGateLanes(pass) {
                     editRewrittenSinceHuman = false;
                 }
                 if (editDenied === undefined && editRewrittenSinceHuman && input.writeProtectionCheck !== undefined) {
-                    const editHit = input.writeProtectionCheck(toolName, editArgs);
+                    const editHit = input.writeProtectionCheck(toolName, editArgs, pass.req.face);
                     if (editHit !== null) {
                         editDenied = {
                             action: "deny",

package/dist/core/governance-codes.d.ts

@@ -103,7 +103,7 @@ export type NoticeAudience = "user" | "operator";
  * src/ for notice mint shapes and names any code that is minted but unregistered, or registered but
  * no longer minted.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "mcp.revocation_probe_failed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "route.fallback_to_primary", "route.base_url_changed_key_unchanged", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "tool_result.offload_put_failed"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "mcp.revocation_probe_failed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "route.fallback_to_primary", "route.base_url_changed_key_unchanged", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "tool_result.offload_put_failed"];
 /** A code this engine mints (see {@link ENGINE_NOTICE_CODES}). NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */

package/dist/core/governance-codes.js

@@ -101,6 +101,9 @@ export const ENGINE_NOTICE_CODES = [
     "config.tool_model_gate_removed",
     "config.tool_model_gate_unknown_class",
     "config.tool_model_gate_env_invalid",
+    "config.tool_card_undeclared",
+    "config.tool_face_undeclared",
+    "config.tool_face_invalid",
     "config.durable_gate_unavailable",
     "config.peer_admission_out_of_range",
     "config.peer_lane_unmounted",
@@ -164,6 +167,9 @@ const NOTICE_AUDIENCE_TABLE = {
     "config.tool_model_gate_removed": "operator",
     "config.tool_model_gate_unknown_class": "operator",
     "config.tool_model_gate_env_invalid": "operator",
+    "config.tool_card_undeclared": "operator",
+    "config.tool_face_undeclared": "operator",
+    "config.tool_face_invalid": "operator",
     "config.peer_lane_unmounted": "operator",
     "config.peer_admission_out_of_range": "operator",
     "peer.inbound_disposition": "user",

package/dist/core/hooks.d.ts

@@ -1,6 +1,6 @@
 import type { ActorAssertion, DocumentContent, ImageContent, TextContent } from "../internal/llm.js";
 import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../internal/harness-types.js";
-import type { DecisionReason, PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
+import type { DecisionReason, PermissionResult, ResolvedAsk, ToolCallFace, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
 import type { GateOutcome } from "./gate-outcome.js";
 export { normalizeOrgGateVerdict, normalizePersistedRuleHit, persistedRuleMandateOf } from "./gate-lanes.js";
 export { cloneObserverInput } from "./runner/gate-exit.js";
@@ -1115,6 +1115,12 @@ export interface ToolGateInput {
      *  builds ({@link HookEnvCapabilities}). Built ONCE per task by the runner (after the env is minted) and
      *  passed through unchanged; omitted when the deployment wired no execution environment. */
     hookEnv?: HookEnvCapabilities;
+    /**
+     * design/388 B6 — the leg's live roster lookup: the face of the mounted tool a call dispatches to, stamped
+     * on the {@link ToolCallRequest} every policy sees (read at the gate entry, so a run-time roster change is
+     * honoured on the next call). Absent ⇒ requests carry no face (a bare producer).
+     */
+    toolFaceOf?: (toolName: string) => ToolCallFace | undefined;
     /**
      * design/384 slice 1 — the PER-CALL abort signal, carried in from the `tool_call` hook event's
      * own `signal` seat (the loop's turn-scoped controller; the run abort is composed into it). The
@@ -1332,7 +1338,7 @@ export interface ToolGateInput {
      * (the write-protection tighten below). Absent ⇒ the deployment replaced the table with `[]` (or
      * the caller runs the gate without one) and the decision path is byte-identical.
      */
-    writeProtectionCheck?: (toolName: string, args: unknown) => import("./write-protect.js").WriteProtectedHit | null;
+    writeProtectionCheck?: (toolName: string, args: unknown, face?: import("./tool-registry.js").ToolCallLike["face"]) => import("./write-protect.js").WriteProtectedHit | null;
     /**
      * design/143 批2 (A, CC 2.1.207 auto mode): when present, a surviving `ask` is routed to the
      * small-model policy CLASSIFIER before any human/durable resolution:

package/dist/core/hooks.js

@@ -301,7 +301,7 @@ export async function runToolGate(input) {
         screening,
         afterFold: runGateLanes,
         currentInput: modelInput,
-        req: { toolName, args: modelInput, toolCallId },
+        req: { toolName, args: modelInput, toolCallId, ...(() => { const f = input.toolFaceOf?.(toolName); return f !== undefined ? { face: f } : {}; })() },
         preToolContext: [],
         hookAsk: undefined,
         parkFailed: undefined,

package/dist/core/lsp.js

@@ -2,6 +2,7 @@ import { uriToPath } from "./lsp-protocol.js";
 import { foldRedundantPathSegments, isAbsolutePathForm } from "../tools/fs/safety.js";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "./tools.js";
+import { toolFace } from "./tool-catalog-entries.js";
 export const LSP_OPERATIONS = [
     "goToDefinition", "findReferences", "hover", "documentSymbol", "workspaceSymbol",
     "goToImplementation", "prepareCallHierarchy", "incomingCalls", "outgoingCalls",
@@ -145,7 +146,7 @@ const POSITION_OPS = new Set([
 export function createLspTool(manager, opts = {}) {
     return defineTool({
         name: "LSP",
-        contract: { contractId: "core.lsp@1", implementationRevision: "1" },
+        ...toolFace("lsp"),
         description: "Interact with Language Server Protocol (LSP) servers to get code intelligence features.\n" +
             "\n" +
             "Supported operations:\n" +
@@ -172,7 +173,6 @@ export function createLspTool(manager, opts = {}) {
             character: Type.Optional(Type.Number({ description: "The character offset (1-based, as shown in editors)." })),
             query: Type.Optional(Type.String({ description: "Symbol query for workspaceSymbol (may be empty to browse broadly)." })),
         }),
-        effect: "read",
         execute: async (args, ctx) => {
             const { operation, filePath, line, character, query } = args;
             if (POSITION_OPS.has(operation) && (line === undefined || character === undefined)) {

package/dist/core/mcp-server-spec.d.ts

@@ -6,6 +6,7 @@
  * a longer name. Layer 0 vocabulary; `types.ts` re-exports every name below.
  */
 import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
+import type { ToolFamily, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
 /** Definition of an MCP server to connect to for the duration of one task, then discard. */
 export interface McpServerSpec {
     /** Stable name; tool names are namespaced as `<name>__<tool>` to avoid collisions. */
@@ -71,6 +72,22 @@ export interface McpServerSpec {
         egress?: boolean;
         irreversibility?: "always" | "never";
     }>;
+    /**
+     * design/388 §1.1 / §2.7 — the OPTIONAL per-tool FACE overlay for this server's tools (keyed by the server's
+     * RAW tool name, like {@link allowTools} / {@link toolAxes}): a deployment lets an MCP tool enter a specialised
+     * approval card, be confirmed by path, carry a display name / summary, or narrow its rule vocabulary. TRUSTED
+     * (the deployment writes it), but validated against the MATERIALIZED schema at every listing (first mount and
+     * every refresh): a `pathTarget.param` that is not a top-level property, an `approvalCard` whose keys the schema
+     * lacks, a `ruleFace` naming a non-scalar key ⇒ the tool mounts WITHOUT the overlay and the leg announces
+     * `config.tool_face_invalid` once; a key naming a tool the listing does not carry announces
+     * `config.tool_face_undeclared` once. Applied whole or not at all.
+     */
+    toolFaces?: Record<string, {
+        family?: ToolFamily;
+        pathTarget?: ToolPathTarget;
+        renderHints?: ToolRenderHints;
+        ruleFace?: ToolRuleFace;
+    }>;
     /**
      * design/378 — declare {@link ToolSpec.contentOrigin} on behalf of THIS SERVER'S ENTIRE TOOL SET
      * (tools a mid-task refresh adds included), with the same authority and the same responsibility a