@sema-agent/core 7.6.3 → 7.8.0

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
@@ -211,6 +217,17 @@ export interface EngineNotice {
      *    (whoever answered the card is the one entitled to hear the answer ran nothing); a host may
      *    forward it on its own wire.
      *
+     *  - `"checkpoint.execution_outcome_unrecorded"` — the resumed leg's pending-call resolver disposed
+     *    the decided action (executed it, delivered the refusal, or vetoed the person's yes) and filed
+     *    the frame's record through `CheckpointStore.recordExecutionOutcome`, and the store answered
+     *    `not_resolved` or `absent` — the row was reopened, expired or removed under the leg by another
+     *    actor, so the row now reads `unknown` on its execution axis (`executionVerdict`). The
+     *    execution result is NOT changed by the answer (the record is an account of what ran, never a
+     *    gate on it); the notice is the loud half. Once per such resolution;
+     *    `detail: { sessionId, runId, scope, checkpointId?, word }` (`word` = the store's answer; the
+     *    secret token never rides a notice). A DIFFERENT record already on file is not this notice — it
+     *    is the `checkpoint.execution_outcome_conflict` throw (an engine defect, propagated).
+     *
      *  - `"classifier.denial_limit"` (#548, CC 2.1.250 `FO`/"too many classifier denials in headless
      *    mode") — the auto-mode classifier's DENIAL LIMIT was reached (3 consecutive blocks, or 20 in the
      *    run; `RunnerDeps.autoMode.denialLimit`) and the fallback ask it turns into had NO approver to go

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", "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",
@@ -108,6 +111,7 @@ export const ENGINE_NOTICE_CODES = [
     "peer.held_settled",
     "peer.idle_subscription",
     "classifier.denial_limit",
+    "checkpoint.execution_outcome_unrecorded",
     "delegation.transcript_integrity",
     "mcp.revocation_probe_failed",
     "workflow.governance_key_stripped",
@@ -163,12 +167,16 @@ 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",
     "peer.held_settled": "user",
     "peer.idle_subscription": "user",
     "delegation.transcript_integrity": "operator",
+    "checkpoint.execution_outcome_unrecorded": "operator",
     "mcp.revocation_probe_failed": "operator",
     "workflow.governance_key_stripped": "operator",
     "workflow.agent_option_ignored": "operator",

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

package/dist/core/mcp.js

@@ -18,6 +18,7 @@ import { discloseReminderShaped, observeReminderMarkEcho } from "./reminder-disc
 import { withContentOrigin } from "./memory-engine/content-origin.js";
 import { snapshotMcpEntries } from "./locked-config.js";
 import { validateJsonSchemaShape } from "./runner/strict-output-schema.js";
+import { schemaKeyBoundProblem } from "./tool-roster.js";
 export const MCP_PREFIX = MCP_NAMESPACE.prefix;
 const MCP_OUTPUT_TOKENS_DEFAULT = 25_000;
 const MCP_CHARS_PER_TOKEN = 4;
@@ -1513,7 +1514,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             effectiveInputSchema = normalized.schema;
             effectiveDescription = normalized.note + (effectiveDescription ? `\n\n${effectiveDescription}` : "");
         }
-        const schemaProblem = mcpToolSchemaProblem(effectiveInputSchema);
+        const schemaProblem = mcpToolSchemaProblem(effectiveInputSchema) ?? schemaKeyBoundProblem(effectiveInputSchema);
         if (schemaProblem !== undefined) {
             dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaProblem, 240) });
             continue;
@@ -1551,6 +1552,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             parameters: (effectiveInputSchema ?? { type: "object" }),
             ...(mcpMaxResultSizeChars !== undefined ? { mcpMaxResultSizeChars } : {}),
             ...(mcpAlwaysLoad ? { mcpAlwaysLoad: true } : {}),
+            mcpRemoteName: remoteName,
             execute: async (_toolCallId, params, signal) => {
                 const what = `The call to tool ${inlineUntrusted(remoteName)}`;
                 if (isServerRevoked?.(spec.name) === true) {

package/dist/core/memory-engine/tools.js

@@ -6,6 +6,7 @@ import { formatMemoryAge } from "../memory-recall.js";
 import { committedOriginOf } from "./frontmatter.js";
 import { MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, MEMORY_PROVENANCE_INDEX_SENTENCE, MEMORY_PROVENANCE_SEARCH_SENTENCE, MEMORY_SEARCH_BAND_ORDER_HEADER } from "./provenance-wording.js";
 import { deriveSupersededSet, memorySupersededNote, MEMORY_SEARCH_SUPERSEDED_TAG } from "./consolidation.js";
+import { toolFace } from "../tool-catalog-entries.js";
 export const MEMORY_SEARCH_TOOL_NAME = "memory_search";
 export const MEMORY_GET_TOOL_NAME = "memory_get";
 export const MEMORY_INDEX_TOOL_NAME = "memory_index";
@@ -175,11 +176,8 @@ export function createMemoryEngineTools(opts) {
     };
     const searchTool = {
         name: MEMORY_SEARCH_TOOL_NAME,
+        ...toolFace("memory-search"),
         description: carry ? `${SEARCH_DESCRIPTION}\n\n${MEMORY_PROVENANCE_SEARCH_SENTENCE}` : SEARCH_DESCRIPTION,
-        effect: "read",
-        offload: false,
-        contentOrigin: "local",
-        contract: { contractId: "core.memory_search@1", implementationRevision: "6" },
         parameters: Type.Object({
             query: Type.String({ description: "Keywords to look for (lexical match against entry names, descriptions and bodies)." }),
             limit: Type.Optional(Type.Number({ description: `Maximum hits to return (default ${MEMORY_SEARCH_DEFAULT_LIMIT}, max ${MEMORY_SEARCH_MAX_LIMIT}).` })),
@@ -319,11 +317,8 @@ export function createMemoryEngineTools(opts) {
     };
     const getTool = {
         name: MEMORY_GET_TOOL_NAME,
+        ...toolFace("memory-get"),
         description: GET_DESCRIPTION,
-        effect: "read",
-        offload: false,
-        contentOrigin: "local",
-        contract: { contractId: "core.memory_get@1", implementationRevision: "6" },
         parameters: Type.Object({
             id: Type.Optional(Type.String({ description: "Entry id (exact lookup). Pass either id or slug, not both." })),
             slug: Type.Optional(Type.String({ description: "Entry slug (its file path without .md). Ambiguous across scopes unless scope is also passed." })),
@@ -545,11 +540,8 @@ export function createMemoryEngineTools(opts) {
     };
     const indexTool = {
         name: MEMORY_INDEX_TOOL_NAME,
+        ...toolFace("memory-index"),
         description: carry ? `${INDEX_DESCRIPTION}\n\n${MEMORY_PROVENANCE_INDEX_SENTENCE}` : INDEX_DESCRIPTION,
-        effect: "read",
-        offload: false,
-        contentOrigin: "local",
-        contract: { contractId: "core.memory_index@1", implementationRevision: "1" },
         parameters: Type.Object({
             offset: Type.Optional(Type.Number({ description: "Zero-based row offset into the listing (default 0) — pass the previous page's footer value to continue." })),
             limit: Type.Optional(Type.Number({ description: `Maximum rows for this page (default ${MEMORY_INDEX_PAGE_ROWS}, max ${MEMORY_INDEX_MAX_PAGE_ROWS}).` })),

package/dist/core/permission-rules.d.ts

@@ -43,6 +43,11 @@ export interface PermissionRuleIssue {
     /** `invalid.*` = 语法/语义错;`unsupported.*` = CC 合法但 v1 不支持的 lane(独立
      *  分类,绝不静默 no-op —— `Bash(npm run:*)` 被当 generic 参数规则接受后永不匹配是最危险的失败形态)。 */
     code: "invalid.empty_tool" | "invalid.paren" | "invalid.param_split" | "invalid.allow_param_rule" | "invalid.primary_field" | "invalid.cap_exceeded" | "unsupported.bash_prefix"
+    /** design/388 B15 — the closed rule-lint set over a tool's RULE FACE (derived scalar vocabulary; a
+     *  declaration only narrows it): the named parameter is not one the tool carries; it is carried but
+     *  is an object/array (a rule on it can never match); the tool is unknown to the resolver a leg
+     *  supplied (absent resolver ⇒ the catalog alone judges and an unknown tool stays permissive). */
+     | "unsupported.param_unknown" | "unsupported.param_non_scalar" | "unsupported.tool_unknown"
     /** design/179 D7: a Bash prefix rule under `bashPrefixLane:"rules-store"` — reported so a migration
      *  report can tell "route this through the rule store" apart from "this is a mistake". */
      | "unsupported.bash_prefix_rules_store" | "unsupported.file_glob" | "unsupported.mcp_paren"
@@ -98,6 +103,13 @@ export interface PermissionRulePolicyOptions {
      */
     bashPrefixLane?: "reject" | "rules-store";
     caps?: Partial<PermissionRuleCaps>;
+    /**
+     * design/388 B15 — the leg's RULE-FACE resolver (typically `ruleFacesFromRoster(prepared.toolRoster)`): with it
+     * every tool on the leg is judged — MCP and caller tools included — and a rule naming a tool the leg does not
+     * mount is `unsupported.tool_unknown`. Without it the static catalog alone judges; a tool the catalog does not
+     * carry stays permissive (a rule for it compiles unjudged).
+     */
+    ruleFaces?: (toolName: string) => RuleFaceView | undefined;
 }
 /**
  * Parse one rule string — CC `Lh` :55214 parity, including its lenient downgrades (malformed parens /
@@ -134,11 +146,29 @@ export declare function namespacedRuleNameCovers(ruleName: string, toolName: str
  *  — i.e. the shapes {@link namespacedRuleNameCovers} answers and an exact name table cannot. Every
  *  lane that keys rules by exact tool name needs this to know which entries it must NOT key that way. */
 export declare function isNamespacedCoveringRuleName(name: string): boolean;
-/** Exported for the lockstep guard only (see {@link FILE_TOOL_PARAMS}) — not part of the rule DSL. */
+/**
+ * design/388 A-6/7/8/9 (D-3): the per-tool RULE FACE — the parameters a `Tool(param:pattern)` rule may name
+ * (`params`, the SCALAR top-level keys ∪ the path target's aliases), the ones the generic lexical matcher must
+ * not be pointed at (`primaryParams`), the carried-but-non-scalar keys a rule can never match (`nonScalar`), and
+ * whether the tool names a path target at all (the file-tool glob lane). Resolved through
+ * {@link PermissionRulePolicyOptions.ruleFaces} when a leg supplies its roster, else from the static catalog
+ * — the three hand-kept tables (`PRIMARY_FIELDS` / `FILE_TOOLS` / `FILE_TOOL_PARAMS`) this replaced are gone.
+ */
+export interface RuleFaceView {
+    primaryParams: readonly string[];
+    /** The full scalar vocabulary; ABSENT when the resolver does not know it (the static catalog for a
+     *  definition whose schema is factory-built) — then only the primary-field check applies. */
+    params?: readonly string[];
+    nonScalar?: readonly string[];
+    pathTargeting?: boolean;
+}
+/** The static catalog's answer for a wire name (undefined ⇒ the catalog does not carry it). */
+export declare function catalogRuleFaceView(toolName: string): RuleFaceView | undefined;
+/** Exported for the lockstep guard only (the scalar vocabulary of a catalog tool) — not part of the rule DSL. */
 export declare const fileToolParamVocabulary: (canonicalTool: string) => ReadonlySet<string> | undefined;
 /** Dry-run 校验/迁移报告:不 throw,返回全部 issues(含 `unsupported.*` 分类,
  *  供从 CC settings 迁移的部署逐条对照)。 */
-export declare function validatePermissionRules(rules: PermissionRule[], opts?: Pick<PermissionRulePolicyOptions, "primaryFieldGeneric" | "caps" | "bashPrefixLane">): PermissionRuleIssue[];
+export declare function validatePermissionRules(rules: PermissionRule[], opts?: Pick<PermissionRulePolicyOptions, "primaryFieldGeneric" | "caps" | "bashPrefixLane" | "ruleFaces">): PermissionRuleIssue[];
 /**
  * Compile declarative permission rules into ONE {@link ToolPolicy} (design/127). Evaluation order
  * inside the policy (CC `G1e` :595272 isomorph): bare deny → param deny → bare ask → param ask →

package/dist/core/permission-rules.js

@@ -1,5 +1,6 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
-export const BASH_GENERIC_PARAMS = new Set(["command", "timeout", "description", "run_in_background"]);
+import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
+export const BASH_GENERIC_PARAMS = new Set(catalogRuleFaceOf("Bash")?.params ?? []);
 const DEFAULT_CAPS = {
     maxRules: 256,
     maxRuleLength: 512,
@@ -107,31 +108,16 @@ export function isNamespacedCoveringRuleName(name) {
     const parsed = parseNamespacedRuleName(name);
     return parsed !== undefined && (parsed.tool === undefined || parsed.tool.includes("*"));
 }
-const PRIMARY_FIELDS = {
-    Bash: new Set(["command"]),
-    Read: new Set(["file_path", "path"]),
-    Edit: new Set(["file_path", "path"]),
-    Write: new Set(["file_path", "path"]),
-    MultiEdit: new Set(["file_path", "path"]),
-    NotebookEdit: new Set(["notebook_path", "path"]),
-    Grep: new Set(["path"]),
-    Glob: new Set(["path"]),
-    WebFetch: new Set(["url"]),
-    WebSearch: new Set(["query"]),
-};
-const FILE_TOOLS = new Set(["Read", "Edit", "Write", "MultiEdit", "NotebookEdit", "Grep", "Glob"]);
-const FILE_TOOL_PARAMS = {
-    Read: new Set(["file_path", "path", "offset", "limit", "pages"]),
-    Edit: new Set(["file_path", "path", "old_string", "new_string", "replace_all"]),
-    Write: new Set(["file_path", "path", "content"]),
-    NotebookEdit: new Set(["notebook_path", "path", "cell_id", "cell_type", "edit_mode", "new_source"]),
-    Grep: new Set([
-        "pattern", "path", "glob", "type", "output_mode", "head_limit", "offset",
-        "multiline", "context", "ignore_case", "-i", "-n", "-o", "-A", "-B", "-C",
-    ]),
-    Glob: new Set(["pattern", "path", "max_results"]),
+export function catalogRuleFaceView(toolName) {
+    const face = catalogRuleFaceOf(toolName);
+    if (face === undefined)
+        return undefined;
+    return { ...face, pathTargeting: pathTargetOf(toolName) !== undefined };
+}
+export const fileToolParamVocabulary = (canonicalTool) => {
+    const face = catalogRuleFaceOf(canonicalTool);
+    return face?.params === undefined || pathTargetOf(canonicalTool) === undefined ? undefined : new Set(face.params);
 };
-export const fileToolParamVocabulary = (canonicalTool) => FILE_TOOL_PARAMS[canonicalTool];
 function countStars(s) {
     let n = 0;
     for (const c of s)
@@ -139,7 +125,15 @@ function countStars(s) {
             n++;
     return n;
 }
-function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject") {
+function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject", ruleFaces) {
+    const faceOf = (toolName) => {
+        if (ruleFaces !== undefined) {
+            const face = ruleFaces(toolName);
+            return { face, judged: true };
+        }
+        const face = catalogRuleFaceView(toolName);
+        return { face, judged: face !== undefined };
+    };
     const byTool = new Map();
     const namespacedCovering = { deny: [], ask: [], allow: [] };
     const issues = [];
@@ -209,18 +203,30 @@ function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject") {
                 continue;
             }
         }
-        else if (FILE_TOOLS.has(toolName)) {
-            if (colon <= 0) {
-                bad(text, "unsupported.file_glob", "file-tool glob rules (`Edit(src/**)`) are the tool-specific lane — not supported by the generic param DSL");
+        else {
+            const resolved = faceOf(toolName);
+            if (resolved.judged && resolved.face === undefined) {
+                bad(text, "unsupported.tool_unknown", `"${toolName}" is not a tool on this leg's roster — the rule would compile and never match`);
                 continue;
             }
-            const paramPart = content.slice(0, colon).trim();
-            const vocabulary = FILE_TOOL_PARAMS[toolName];
-            if (vocabulary !== undefined && !vocabulary.has(paramPart)) {
-                bad(text, "unsupported.unknown_param", `"${paramPart}" is not a parameter of ${toolName} (it carries ${[...vocabulary].sort().join(", ")}) — the rule would compile and never match. ` +
-                    `For a path glob use the tool-specific lane (\`${toolName}(src/**)\` is not the generic param DSL); a Windows path such as \`${toolName}(C:/foo)\` parses as the param "C".`);
+            const face = resolved.face;
+            if (face !== undefined && face.pathTargeting === true && colon <= 0) {
+                bad(text, "unsupported.file_glob", "file-tool glob rules (`Edit(src/**)`) are the tool-specific lane — not supported by the generic param DSL");
                 continue;
             }
+            if (face?.params !== undefined && colon > 0) {
+                const paramPart = content.slice(0, colon).trim();
+                if (!face.params.includes(paramPart)) {
+                    if (face.nonScalar?.includes(paramPart)) {
+                        bad(text, "unsupported.param_non_scalar", `"${paramPart}" is a parameter of ${toolName} but its value is an object or an array — the generic matcher compares scalars only; the rule would compile and never match`);
+                    }
+                    else {
+                        bad(text, "unsupported.param_unknown", `"${paramPart}" is not a parameter of ${toolName} (it carries ${[...face.params].sort().join(", ")}) — the rule would compile and never match. ` +
+                            `For a path glob use the tool-specific lane (\`${toolName}(src/**)\` is not the generic param DSL); a Windows path such as \`${toolName}(C:/foo)\` parses as the param "C".`);
+                    }
+                    continue;
+                }
+            }
         }
         if (colon <= 0) {
             bad(text, "invalid.param_split", "param-level ruleContent must be `param:pattern`");
@@ -240,7 +246,7 @@ function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject") {
             bad(text, "invalid.cap_exceeded", `pattern exceeds maxPatternLength ${caps.maxPatternLength} or maxStars ${caps.maxStars}`);
             continue;
         }
-        if (PRIMARY_FIELDS[toolName]?.has(param) && primaryFieldGeneric === "reject") {
+        if (faceOf(toolName).face?.primaryParams.includes(param) === true && primaryFieldGeneric === "reject") {
             bad(text, "invalid.primary_field", `"${param}" is ${toolName}'s primary field — the generic matcher is a trim+FULL-STRING lexical match (no shell/path semantics); '${toolName}(${param}:git push*)' would NOT match 'cd /x && git push'. Opt in with primaryFieldGeneric:"allow-lexical" if you understand this.`);
             continue;
         }
@@ -251,7 +257,7 @@ function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject") {
 }
 export function validatePermissionRules(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
-    return compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject").issues;
+    return compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject", opts?.ruleFaces).issues;
 }
 function isPlainObjectArgs(args) {
     return typeof args === "object" && args !== null && !Array.isArray(args);
@@ -281,7 +287,7 @@ function ruleMessage(kind, ruleText, source) {
 }
 export function createPermissionRulePolicy(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
-    const { byTool, namespacedCovering, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject");
+    const { byTool, namespacedCovering, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject", opts?.ruleFaces);
     const setLevelCap = issues.some((i) => i.code === "invalid.cap_exceeded" && i.rule === "");
     if (issues.length > 0 && ((opts?.onInvalidRule ?? "throw") === "throw" || setLevelCap)) {
         const e = new Error(`createPermissionRulePolicy: ${issues.length} invalid/unsupported rule(s):\n` +

package/dist/core/present-plan-tool.js

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { delimitUntrusted } from "./untrusted-text.js";
+import { toolFace } from "./tool-catalog-entries.js";
 export const PRESENT_PLAN_TOOL_NAME = "ExitPlanMode";
 export const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
 const ENTER_PLAN_MODE_DESCRIPTION = `Enter PLAN MODE (read-only): stop making changes and switch to exploration/planning. For the rest of this run, write/edit/mutating tool calls are REJECTED while read-only tools (Read, Grep, Glob, etc.) still work. When your plan is ready, call ${PRESENT_PLAN_TOOL_NAME} with it — the run PAUSES for a human to approve it, then continues (read-only lifted) so you can execute.
@@ -31,10 +32,9 @@ BAD: "Fix the typo in the README" (trivial; nothing to align on). "Remove the le
 export function createEnterPlanModeTool(enterPlanMode) {
     return {
         name: ENTER_PLAN_MODE_TOOL_NAME,
-        contract: { contractId: "core.enter_plan_mode@1", implementationRevision: "1" },
+        ...toolFace("enter-plan-mode"),
         description: ENTER_PLAN_MODE_DESCRIPTION,
         parameters: Type.Object({}),
-        effect: "read",
         executionMode: "sequential",
         execute: async () => {
             enterPlanMode();
@@ -61,14 +61,13 @@ const PRESENT_PLAN_DESCRIPTION = [
 export function createPresentPlanTool(requestReview) {
     return {
         name: PRESENT_PLAN_TOOL_NAME,
-        contract: { contractId: "core.exit_plan_mode@1", implementationRevision: "1" },
+        ...toolFace("exit-plan-mode"),
         description: PRESENT_PLAN_DESCRIPTION,
         parameters: Type.Object({
             plan: Type.String({
                 description: "Your full proposed plan, in markdown. The human reviewer approves / edits / rejects it before you act.",
             }),
         }),
-        effect: "read",
         execute: async (args) => {
             const { plan } = args;
             requestReview({ reason: "ExitPlanMode" });