@sema-agent/core 7.7.0 → 7.9.0

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

@@ -2,7 +2,9 @@ import { decisionText, describeThrown } from "./tool-policy.js";
 import { askOriginOf, classifierMayAnswer } from "./ask-origin.js";
 import { denialLimitFallbackMessage, unarmedWindow } from "./auto-mode.js";
 import { inlineUntrusted } from "./untrusted-text.js";
+import { isRuleBehavior } from "./permission-rule-model.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
+import { applyPersistedTightening, disclosedRuleSet } from "./persisted-rule-arms.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
 import { exitGate, traceHookCrash } from "./runner/gate-exit.js";
 function isPlainOwnRecord(x) {
@@ -89,8 +91,6 @@ function copiedUsableDots(dots) {
     return usable ? { dots: copied } : {};
 }
 export function normalizePersistedRuleHit(hit) {
-    if (typeof hit === "string")
-        return { hit: { rules: [{ rule: hit }] } };
     if (!isPlainOwnRecord(hit))
         return {};
     if (ownDataValue(hit, "unreadable") === true)
@@ -132,7 +132,10 @@ export function normalizePersistedRuleHit(hit) {
         return {};
     if (!members.every((m) => typeof m.rule === "string"))
         return {};
-    return { hit: { rules: members.map((m) => ({ rule: m.rule, ...copiedUsableDots(m.dots) })) } };
+    const behavior = ownDataValue(hit, "behavior");
+    if (!isRuleBehavior(behavior))
+        return {};
+    return { hit: { behavior, rules: members.map((m) => ({ rule: m.rule, ...copiedUsableDots(m.dots) })) } };
 }
 export function persistedRuleMandateOf(marks) {
     return marks.probeMandated === true
@@ -153,10 +156,11 @@ function parkWith(suspendAsk, parkArgs, carry) {
 export async function runGateLanes(pass) {
     const { input, toolName, toolCallId, callSignal, ledger, notifier, screening, adjudicate, resolveAsk, suspendAsk } = pass;
     let orgRealApprovalRequired = false;
-    const askOriginFacts = (org) => ({
+    const askOriginFacts = (org, ruleStore) => ({
         contentQuestion: toolName === ASK_USER_QUESTION_TOOL_NAME,
         markedUnresolvable: input.isMarkedUnresolvable?.(input.event.toolCallId) === true,
         org,
+        ...(ruleStore !== undefined ? { ruleStore } : {}),
         tightened: pass.tightenedBy,
     });
     let orgTightenCount = 0;
@@ -240,6 +244,24 @@ export async function runGateLanes(pass) {
     };
     const orgAnswer = await applyOrgLayer(pass.decision, pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput);
     pass.decision = orgAnswer.decision;
+    const readPersistedRules = async (req) => {
+        let pendingHit;
+        try {
+            pendingHit = Promise.resolve(input.persistedRules?.adjudicate(req));
+        }
+        catch {
+            return { unreadable: true };
+        }
+        return await settleOrgVerdictWithin(pendingHit.then(normalizePersistedRuleHit).catch(() => ({ unreadable: true })), { unreadable: true }, { ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
+    };
+    const laneReq = { ...pass.req, ...(pass.policyRewrite !== undefined ? { args: pass.policyRewrite } : {}) };
+    const laneAnswer = input.persistedRules !== undefined && pass.req.toolName !== ASK_USER_QUESTION_TOOL_NAME ? await readPersistedRules(laneReq) : undefined;
+    {
+        const tightened = applyPersistedTightening(pass.decision, laneAnswer);
+        pass.decision = tightened.decision;
+        if (tightened.tightened === "deny")
+            pass.deniedBy = "persisted_rule";
+    }
     if (pass.decision.action === "ask") {
         if (pass.policyRewrite !== undefined) {
             pass.currentInput = pass.policyRewrite;
@@ -252,6 +274,8 @@ export async function runGateLanes(pass) {
             probeMandated: pass.decision.action === "ask" && pass.decision.probeMandated === true,
         });
         let personalEvidence = { dotsAbsent: input.persistedRules === undefined ? "not_wired" : "not_adjudicated" };
+        if (laneAnswer?.unreadable === true)
+            personalEvidence = { dotsAbsent: "unavailable" };
         let laneCoverage;
         if (input.persistedRules &&
             !orgRealApprovalRequired &&
@@ -260,24 +284,10 @@ export async function runGateLanes(pass) {
             pass.decision.decisionReason !== "hook" &&
             pass.req.toolName !== ASK_USER_QUESTION_TOOL_NAME &&
             input.isMarkedUnresolvable?.(input.event.toolCallId) !== true) {
-            const answer = await (async () => {
-                let pendingHit;
-                try {
-                    pendingHit = Promise.resolve(input.persistedRules?.admits(pass.req));
-                }
-                catch {
-                    return { unreadable: true };
-                }
-                return await settleOrgVerdictWithin(pendingHit.then(normalizePersistedRuleHit).catch(() => ({ unreadable: true })), { unreadable: true }, { ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
-            })();
-            const hitRules = answer.hit?.rules;
+            const answer = laneAnswer ?? {};
+            const hitRules = answer.hit?.behavior === "allow" ? answer.hit.rules : undefined;
             laneCoverage = answer.coverage;
             personalEvidence = { dotsAbsent: answer.unreadable === true ? "unavailable" : "no_match" };
-            const disclosedRuleSet = (rules) => {
-                const shown = rules.slice(0, 5).map((r) => inlineUntrusted(r.rule, 200));
-                const rest = rules.length - shown.length;
-                return rest > 0 ? `${shown.join(", ")} and ${rest} more` : shown.join(", ");
-            };
             const unionDotsOf = (rules) => {
                 const seen = new Set();
                 const union = [];
@@ -294,6 +304,8 @@ export async function runGateLanes(pass) {
                 }
                 return { dots: union };
             };
+            if (answer.hit?.behavior === "ask")
+                personalEvidence = unionDotsOf(answer.hit.rules);
             if (hitRules !== undefined && persistedRuleMandate === undefined && pass.decision.matchedAskRule === undefined) {
                 pass.decision = {
                     action: "allow",
@@ -324,7 +336,7 @@ export async function runGateLanes(pass) {
                 };
             }
         }
-        const originFacts = askOriginFacts(orgAnswer.org);
+        const originFacts = askOriginFacts(orgAnswer.org, laneAnswer?.unreadable === true ? "unavailable" : undefined);
         if (pass.decision.action === "ask") {
             const stamped = { ...pass.decision, ruleEvidence: mintRuleEvidence(personalEvidence), ...(laneCoverage !== undefined ? { segmentCoverage: laneCoverage } : {}) };
             pass.decision = { ...stamped, origin: askOriginOf(stamped, originFacts) };
@@ -374,6 +386,7 @@ export async function runGateLanes(pass) {
             input.isMarkedUnresolvable?.(input.event.toolCallId) !== true &&
             pass.decision.requiresRealApproval !== true &&
             pass.decision.decisionReason !== "hook" &&
+            pass.decision.origin !== "ask_rule" &&
             pass.hookAsk === undefined &&
             input.egress !== true &&
             input.peerMessage !== true &&
@@ -543,12 +556,13 @@ export async function runGateLanes(pass) {
                             }
                         }
                     }
-                    if (!adjudicate && input.orgRules === undefined)
+                    if (!adjudicate && input.orgRules === undefined && input.persistedRules === undefined)
                         break;
                     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 = {
@@ -575,6 +589,19 @@ export async function runGateLanes(pass) {
                         editDenied = recheck;
                         break;
                     }
+                    let editRuleStore;
+                    if (input.persistedRules !== undefined && toolName !== ASK_USER_QUESTION_TOOL_NAME) {
+                        const editLane = await readPersistedRules({ toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) });
+                        editRuleStore = editLane.unreadable === true ? "unavailable" : undefined;
+                        const editTightened = applyPersistedTightening(recheck, editLane);
+                        recheck = editTightened.decision;
+                        if (editTightened.tightened === "deny")
+                            pass.deniedBy = "persisted_rule";
+                        if (recheck.action === "deny") {
+                            editDenied = recheck;
+                            break;
+                        }
+                    }
                     if (recheck.action === "allow") {
                         if (recheck.updatedInput !== undefined) {
                             editArgs = recheck.updatedInput;
@@ -587,8 +614,8 @@ export async function runGateLanes(pass) {
                         editRewrittenSinceHuman = true;
                     }
                     const editAskSnapshot = { ...recheck, ruleEvidence: mintRuleEvidence({ dotsAbsent: "not_adjudicated" }) };
-                    const editAskDecision = { ...editAskSnapshot, origin: askOriginOf(editAskSnapshot, askOriginFacts(editOrg.org)) };
-                    const editAskReq = { toolName, args: editArgs, toolCallId };
+                    const editAskDecision = { ...editAskSnapshot, origin: askOriginOf(editAskSnapshot, askOriginFacts(editOrg.org, editRuleStore)) };
+                    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 +633,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/gate-outcome.d.ts

@@ -129,18 +129,22 @@ export type SettlementRefusalTableCoversEveryKind = AssertAllKeysHandled<Exclude
  *  - `ask_resolution` — the ask's own settlement is the refusal (a person said no, a window elapsed,
  *    nobody could be asked…); the detail is on {@link GateOutcome.settlement}.
  */
-export declare const DENIED_BY_VALUES: readonly ["policy", "hook", "org", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
+export declare const DENIED_BY_VALUES: readonly ["policy", "hook", "org", "persisted_rule", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
 export type DeniedBy = (typeof DENIED_BY_VALUES)[number];
 /** Membership test for {@link DeniedBy}. */
 export declare function isDeniedBy(v: unknown): v is DeniedBy;
 /** Which layers may VETO an approval a person already gave (invariant I3: a `human_allowed` settlement
- *  beside a `denied` disposition names one of these). The approval-edit re-screen (hook), the policy and
- *  org re-checks, and the write-protection re-judge run AFTER the person's yes; the classifier, plan mode
- *  and compliance run before any ask exists, and `ask_resolution` IS the settlement, not a veto of it. */
+ *  beside a `denied` disposition names one of these). The approval-edit re-screen (hook), the policy, org
+ *  and persisted-rule re-checks, and the write-protection re-judge run AFTER the person's yes; the
+ *  classifier, plan mode and compliance run before any ask exists, and `ask_resolution` IS the
+ *  settlement, not a veto of it. `persisted_rule` = a person's own standing DENY row (their settings'
+ *  deny list, imported) — the personal-store sibling of `org`, and like it re-judged on an edited
+ *  command. */
 export declare const DENIED_BY_MAY_VETO: {
     readonly policy: true;
     readonly hook: true;
     readonly org: true;
+    readonly persisted_rule: true;
     readonly classifier: false;
     readonly plan_mode: false;
     readonly compliance: false;

package/dist/core/gate-outcome.js

@@ -31,7 +31,7 @@ export const SETTLEMENT_IS_REFUSAL = {
     blanket_allow_refused: true,
     task_aborted: true,
 };
-export const DENIED_BY_VALUES = ["policy", "hook", "org", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
+export const DENIED_BY_VALUES = ["policy", "hook", "org", "persisted_rule", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
 const DENIED_BY_SET = new Set(DENIED_BY_VALUES);
 export function isDeniedBy(v) {
     return DENIED_BY_SET.has(v);
@@ -40,6 +40,7 @@ export const DENIED_BY_MAY_VETO = {
     policy: true,
     hook: true,
     org: true,
+    persisted_rule: true,
     classifier: false,
     plan_mode: false,
     compliance: false,

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";
@@ -1022,22 +1022,27 @@ export interface PersistedRuleHitRule {
     readonly dots?: readonly import("./permission-rule-model.js").RuleDot[];
 }
 /**
- * design/252 G-2, re-formed by design/375 (BREAKING) — the structured answer a persisted-rule lane
- * gives: the COVERAGE SET that admits the call. A single rule admitting the whole command is a
- * one-element set (the historical case); a compound admitted by the conjunction of per-segment rules
- * (design/375 §5.1) is the set of those rules, in segment order. `rules` is non-empty by contract —
- * an empty set covers nothing and is not a hit (the normalizer reads it as a clean negative).
+ * design/252 G-2, re-formed by design/375 and again by the three-behavior model (BREAKING) — the
+ * structured answer a persisted-rule lane gives: WHICH behavior spoke for the call, and the rule set it
+ * stands on. For an `allow` the set is the COVERAGE SET that admits the call — a single rule admitting
+ * the whole command is a one-element set (the historical case); a compound admitted by the conjunction
+ * of per-segment rules (design/375 §5.1) is the set of those rules, in segment order. For a `deny` or an
+ * `ask` the set is the one rule of that behavior that reaches the call (the lane's precedence walk —
+ * deny > ask > allow — already chose it). `rules` is non-empty by contract — an empty set covers nothing
+ * and is not a hit (the normalizer reads it as a clean negative).
  *
- * Why dots and not an id: a persisted allow rule HAS no scalar id — it is a (text, scope) group whose
+ * Why dots and not an id: a persisted rule HAS no scalar id — it is a (behavior, text, scope) group whose
  * identity is the set of add dots that redeemed it, and two concurrently approved records for one text
  * each carry their own. The set is the identity; a joined string would not be one.
  *
- * The pre-375 single-rule object shape (`{ rule, dots? }`) is NOT accepted: on this loosening seam an
- * unrecognized answer degrades to a clean negative (more asks), never to a match — the safe failure
- * shape for a lane that missed the same-window upgrade.
+ * The pre-375 single-rule object shape (`{ rule, dots? }`) and the pre-behavior `{ rules }` shape are
+ * NOT accepted: on this loosening seam an unrecognized answer degrades to a clean negative (more asks),
+ * never to a match — the safe failure shape for a lane that missed the same-window upgrade.
  */
 export interface PersistedRuleHit {
-    /** The coverage set — every rule the decision stands on. Non-empty. */
+    /** What the deciding rule(s) say about the call — the closed set's word. */
+    readonly behavior: import("./permission-rule-model.js").RuleBehavior;
+    /** The rule set the verdict stands on. Non-empty. */
     readonly rules: readonly PersistedRuleHitRule[];
 }
 /**
@@ -1065,8 +1070,9 @@ export interface PersistedRuleUnreadable {
 export interface PersistedRuleCoverage {
     readonly segmentCoverage: readonly import("./permission-rule-model.js").SegmentCoverage[];
 }
-/** Every shape a lane may answer with. A bare string stays valid and unchanged. */
-export type PersistedRuleAnswer = string | PersistedRuleHit | PersistedRuleCoverage | PersistedRuleUnreadable | undefined;
+/** Every shape a lane may answer with. The retired bare-string form (a single allow rule's text) is read
+ *  by the normalizer as a clean negative, like every other unrecognized shape. */
+export type PersistedRuleAnswer = PersistedRuleHit | PersistedRuleCoverage | PersistedRuleUnreadable | undefined;
 /** Inputs to the two-phase tool gate. `adjudicate`/`resolveAsk` are pre-bound to the task abort
  *  signal; when the caller also supplies {@link ToolGateInput.callSignal}, the Runner's closures
  *  additionally bind their waits to that per-call signal (`AbortSignal.any` of the two), so a turn
@@ -1115,6 +1121,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 +1344,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:
@@ -1398,15 +1410,27 @@ export interface ToolGateInput {
      */
     isMarkedUnresolvable?: (toolCallId: string) => boolean;
     /**
-     * design/179 — the persisted allow-rule lane. Present only when a deployment wired a rule store; absent
-     * it, this whole step does not exist and the gate's decision path is byte-identical to what it was.
+     * design/179 — the persisted-rule lane. Present only when a deployment wired a rule store; absent it,
+     * this whole step does not exist and the gate's decision path is byte-identical to what it was.
      *
-     * A persisted rule is the standing form of ONE recorded human approval, so it resolves the asks a real
-     * person saying "allow" would have resolved — and nothing else. It sits post-fold, at the entry of the
-     * `ask` branch, BEFORE the classifier and AFTER every tighten: earlier and a tighten would simply put
-     * the ask back; later and the classifier would already have spoken.
+     * The lane answers with the BEHAVIOR that spoke ({@link PersistedRuleHit}), and the gate consumes the
+     * three behaviors at two different places — the upstream arbiter's order, deny > ask > allow, across
+     * the person's own standing rules:
+     *  · a DENY row refuses the call outright, on EVERY decision (an allow from the policy fold included):
+     *    it is the person's own "never run this" (their settings' deny list, imported), the personal-store
+     *    sibling of an org deny, and it runs right after the org layer — nothing downstream re-opens it;
+     *  · an ASK row is the person's standing "ask me each time": it turns a surviving allow into an ask
+     *    and stamps `matchedAskRule` on it (the same marker an explicit `ask` permission rule stamps), so
+     *    the ask's origin is `ask_rule` — the auto-mode classifier never answers it and a persisted ALLOW
+     *    never clears it; on a call that is already an ask it stamps the marker and leaves the rest;
+     *  · an ALLOW row is the standing form of ONE recorded human approval, so it resolves the asks a real
+     *    person saying "allow" would have resolved — and nothing else. It sits post-fold, at the entry of
+     *    the `ask` branch, BEFORE the classifier and AFTER every tighten: earlier and a tighten would
+     *    simply put the ask back; later and the classifier would already have spoken.
      *
-     * Its consumption predicate is its own, not the classifier's blanket flip:
+     * The deny/ask arms tighten and take no conjunct but the two structural ones every lane shares (the
+     * engine's own content-ask tool is exempt; the lane must be wired). The ALLOW arm's consumption
+     * predicate is its own, not the classifier's blanket flip:
      *  · `requiresRealApproval` asks are never consumed — the two integrity gates are the floor, and the
      *    same flag is what a v2 organization-level ask will carry;
      *  · a PreToolUse hook's ask is never consumed — that is the deployment's own adjudication, and a rule
@@ -1435,19 +1459,26 @@ export interface ToolGateInput {
      * bullets above are what keep integrity/hook/mandated asks out of that set.
      */
     persistedRules?: {
-        /** The rule COVERAGE that admits this call, or `undefined`. Must not throw: a store that cannot
-         *  be read answers "no rule" and discloses on its own channel (fail-closed = more asks).
+        /** The lane's verdict for this call — a {@link PersistedRuleHit} naming the behavior that spoke and
+         *  the rule set it stands on, a coverage-carrying clean negative, an unreadable-store report, or
+         *  `undefined` (the store was READ and no rule speaks). Must not throw — and a store that cannot be
+         *  read answers `{ unreadable: true }`, NEVER `undefined`: the gate reads the unreadable report as
+         *  fail-closed (an allow tightens to a real-approval ask of origin `rule_store_unavailable`), while
+         *  `undefined` is a successful no-match that leaves an allow standing. An adapter that answers
+         *  `undefined` on a read failure silently disarms every deny/ask row it holds.
          *
-         *  TWO ACCEPTED SHAPES (design/252 G-2 / design/375 BREAKING): the canonical rule TEXT (a
-         *  single-rule hit with no identity), or a {@link PersistedRuleHit} carrying the coverage SET —
-         *  each member's canonical text plus its add DOTS. A single rule admitting the whole command is a
-         *  one-element set; a compound admitted by the per-segment conjunction (design/375 §5.1) is the
-         *  set of the covering rules. The dots are a rule's durable identity, and the text is not one (it
-         *  reaches a card sanitized and capped); a lane that can name them lets the shadowed-ask evidence
-         *  say WHICH stored rules matched rather than merely what they looked like. The retired pre-375
-         *  single-rule object shape (`{ rule, dots? }`) is read as a clean negative by the normalizer —
-         *  a stale lane degrades toward asking, never toward an allow. */
-        admits: (req: ToolCallRequest) => Promise<PersistedRuleAnswer>;
+         *  For an ALLOW the set is the COVERAGE SET — each member's canonical text plus its add DOTS. A
+         *  single rule admitting the whole command is a one-element set; a compound admitted by the
+         *  per-segment conjunction (design/375 §5.1) is the set of the covering rules. The dots are a rule's
+         *  durable identity, and the text is not one (it reaches a card sanitized and capped); a lane that
+         *  can name them lets the shadowed-ask evidence say WHICH stored rules matched rather than merely
+         *  what they looked like. The retired shapes — a bare rule TEXT, the pre-375 `{ rule, dots? }` object,
+         *  a `{ rules }` hit without its behavior — are read as a clean negative by the normalizer: a stale
+         *  lane degrades toward asking, never toward an allow. Consulted on EVERY decision (a deny/ask row
+         *  must be able to tighten an allow), so the lane pays one store read per call on the tools it
+         *  speaks for; the runner's lane hands the org layer's read to it, so a governed deployment still
+         *  pays one. */
+        adjudicate: (req: ToolCallRequest) => Promise<PersistedRuleAnswer>;
         /** Observation sink for an ask a rule coverage resolved — the allow-side disclosure. `rules` is
          *  the coverage set's canonical texts in reporting order (design/375: a conjunction names every
          *  rule the decision stands on). Never affects the outcome. */

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) {