@sema-agent/core 7.18.0 → 7.20.0

package/dist/core/runner/turn-attachments.js

@@ -1,7 +1,9 @@
 import { PRESENT_PLAN_TOOL_NAME } from "../present-plan-tool.js";
 import { delimitUntrustedWithClip, sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
 import { protocolOf } from "../protocol-table.js";
-import { buildSkillsBlock, skillListingLine } from "./synthetic-tools.js";
+import { renderSkillLinesWithin, renderSkillsBlock } from "./synthetic-tools.js";
+import { SKILL_LISTING_DEFAULT_BUDGET } from "../skill-listing-budget.js";
+import { foldListingWithin, foldRemovalArmWithin, removalArmFloor } from "./listing-fold.js";
 import { TOOL_SEARCH_NAME as TOOL_SEARCH_TOOL_NAME } from "./tool-disclosure.js";
 export const TODO_REMINDER_CONFIG = {
     TURNS_SINCE_WRITE: 10,
@@ -23,6 +25,33 @@ export const CHANGED_FILES_MTIME_EPS_MS = 2000;
 export const ATTACHMENT_BYTE_CAP = 8 * 1024;
 const PROJECTION_ITEMS_MAX = 50;
 const PROJECTION_CONTENT_MAX = 80;
+const LISTING_FRAME_FLOOR_BYTES = 768;
+const DATE_CHANGE_MAX_BYTES = 160;
+const WORKFLOW_SIZE_GUIDELINE_CHANGE_MAX_BYTES = 256;
+export const ATTACHMENT_DELIVERY_CLASS = {
+    todo_reminder: { class: "clippable" },
+    task_reminder: { class: "clippable" },
+    tool_search_usage_reminder: { class: "clippable" },
+    changed_files: { class: "clippable" },
+    plan_mode: { class: "clippable" },
+    budget_usd: { class: "clippable" },
+    total_tokens_reminder: { class: "clippable" },
+    background_tasks: { class: "clippable" },
+    tools_delta: { class: "intact", bound: (inp) => toolsDeltaBound(inp) },
+    agent_listing: { class: "intact", bound: (inp) => listingFrameBound(inp.listingBudget) + (inp.agentModels !== undefined ? Buffer.byteLength(modelsAvailableLine(inp.agentModels), "utf8") : 0) },
+    skills_listing: { class: "intact", bound: (inp) => listingFrameBound(inp.listingBudget) },
+    mcp_instructions: { class: "intact", bound: (inp) => mcpInstructionsBound(inp) },
+    mcp_dropped_tools: { class: "intact", bound: (inp) => mcpDroppedToolsBound(inp) },
+    date_change: { class: "intact", bound: () => DATE_CHANGE_MAX_BYTES },
+    instructions_change: { class: "intact", bound: () => INSTRUCTIONS_CHANGE_BYTE_CAP },
+    workflow_size_guideline_change: { class: "intact", bound: () => WORKFLOW_SIZE_GUIDELINE_CHANGE_MAX_BYTES },
+};
+export function isIntactSource(source) {
+    return ATTACHMENT_DELIVERY_CLASS[source].class === "intact";
+}
+function listingFrameBound(budget) {
+    return Math.max((budget ?? SKILL_LISTING_DEFAULT_BUDGET).blockMaxBytes, LISTING_FRAME_FLOOR_BYTES);
+}
 const ATTACHMENT_TAGS_DEFAULT = [...SHELLED_BODY_ENVELOPE_TAGS];
 const ATTACHMENT_TAGS_OWNED = {
     skills_listing: SHELLED_BODY_ENVELOPE_TAGS.filter((t) => t !== "skills"),
@@ -207,21 +236,15 @@ export function collectDueAttachments(state, inp) {
             (out ??= []).push({ source: "tools_delta", body });
     }
     const agentListingBody = inp.config.agentListing && inp.agentListing !== undefined
-        ? renderAgentListingDelta(state, inp.agentListing, inp.agentToolName ?? "Agent", inp.agentModels)
+        ? renderAgentListingDelta(state, inp.agentListing, inp.agentToolName ?? "Agent", inp.agentModels, inp.listingBudget)
         : undefined;
-    const skillsListingBody = inp.config.skillsListing && inp.skillsListing !== undefined ? renderSkillsListingDelta(state, inp.skillsListing) : undefined;
-    const listingPair = [];
     if (agentListingBody !== undefined)
-        listingPair.push({ source: "agent_listing", body: agentListingBody });
-    if (skillsListingBody !== undefined) {
-        const att = { source: "skills_listing", body: skillsListingBody };
-        if (state.skillsListingStarved === true)
-            listingPair.unshift(att);
-        else
-            listingPair.push(att);
-    }
-    for (const att of listingPair)
-        (out ??= []).push(att);
+        (out ??= []).push({ source: "agent_listing", body: agentListingBody });
+    const skillsListingBody = inp.config.skillsListing && inp.skillsListing !== undefined
+        ? renderSkillsListingDelta(state, inp.skillsListing, inp.listingBudget)
+        : undefined;
+    if (skillsListingBody !== undefined)
+        (out ??= []).push({ source: "skills_listing", body: skillsListingBody });
     if (inp.config.mcpInstructions && inp.mcpInstructions !== undefined) {
         const body = renderMcpInstructionsDelta(inp.mcpInstructions.added, inp.mcpInstructions.removed);
         if (body !== undefined)
@@ -241,9 +264,6 @@ export function collectDueAttachments(state, inp) {
     if (out === undefined)
         return EMPTY;
     const capped = capAttachments(out);
-    if (skillsListingBody !== undefined) {
-        state.skillsListingStarved = !capped.some((a) => a.source === "skills_listing" && a.body === skillsListingBody);
-    }
     if (pendingSurfaced !== undefined && capped.some((a) => a.source === "changed_files")) {
         for (const c of pendingSurfaced)
             state.surfacedMtime.set(c.path, c.mtimeMs);
@@ -431,15 +451,19 @@ export function renderToolsDelta(input) {
     const added = input.added ?? [];
     if (added.length > 0) {
         const swapped = input.staticFace === true ? (input.swappedUnderStatic ?? []).filter((n) => added.includes(n)) : [];
-        blocks.push((input.staticFace === true
-            ? "The following deferred tools are now active — call them directly. The tools list keeps compact " +
-                'placeholder entries, so re-run ToolSearch ("select:<name>") if you need a parameter schema:\n'
-            : "The following deferred tools are now available. Their full schemas are loaded — call them " +
-                "directly like any other tool:\n") +
-            added.map((n) => `- ${n}`).join("\n") +
-            (swapped.length > 0
-                ? `\nException: ${swapped.join(", ")} — too large to inline, so the full declaration is in the tools list instead.`
-                : ""));
+        const grouped = added.length > TOOLS_DELTA_LIST_MAX;
+        const exception = swapped.length > 0
+            ? grouped
+                ? `\nException: ${swapped.length} of them were too large to inline, so their full declarations are in the tools list instead.`
+                : `\nException: ${swapped.join(", ")} — too large to inline, so the full declaration is in the tools list instead.`
+            : "";
+        blocks.push((grouped ? `${added.length} deferred tools are now ${input.staticFace === true ? "active" : "available"}: ${groupByMcpServer(added)}. ` : "") +
+            (input.staticFace === true
+                ? (grouped ? "Call them directly. " : "The following deferred tools are now active — call them directly. ") +
+                    `The tools list keeps compact placeholder entries, so re-run ToolSearch ("select:<name>") if you need a parameter schema${grouped ? "." : ":\n"}`
+                : (grouped ? "" : "The following deferred tools are now available. ") + `Their full schemas are loaded — call them directly like any other tool${grouped ? "." : ":\n"}`) +
+            (grouped ? "" : added.map((n) => `- ${n}`).join("\n")) +
+            exception);
     }
     const readded = input.readded ?? [];
     if (readded.length > 0) {
@@ -527,45 +551,66 @@ function listingIdentity(name) {
 export function agentListingDeltaHeader(toolName) {
     return `New agent types are now available for the ${sanitizeUntrustedText(toolName, SHELLED_BODY_ENVELOPE_TAGS)} tool:`;
 }
-export function renderAgentListingDelta(state, entries, toolName, models) {
+export function renderAgentListingFrame(state, entries, toolName, models, budget = SKILL_LISTING_DEFAULT_BUDGET) {
     const safe = (t) => sanitizeUntrustedText(t, SHELLED_BODY_ENVELOPE_TAGS);
     const line = (e) => {
         const base = e.description ? `- ${safe(e.name)}: ${safe(e.description)}` : `- ${safe(e.name)}`;
         return `${base} (Tools: ${safe(e.tools ?? AGENT_TOOLS_NOTE_DEFAULT)})`;
     };
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const joiner = bytes(AGENT_DELTA_BLOCK_JOINER);
+    const fold = (items, header, maxBytes) => foldListingWithin(items, {
+        blockMaxBytes: maxBytes,
+        full: line,
+        nameOnly: (e) => `- ${safe(e.name)}`,
+        nameOf: (e) => e.name,
+        capMarker: AGENT_LISTING_CAP_MARKER,
+        overflowLine: (n) => `(… +${n} more agent types not listed)`,
+        frame: (lines) => [header, ...lines].join("\n"),
+    });
     const announced = state.announcedAgentTypes;
     if (announced === undefined) {
         if (entries.length === 0)
             return undefined;
-        const blocks = [`${agentListingInitialHeader(toolName)}\n${entries.map(line).join("\n")}`];
+        const tail = [];
         if (entries.length > 1)
-            blocks.push(AGENT_CONCURRENCY_NOTE);
+            tail.push(AGENT_CONCURRENCY_NOTE);
         if (models !== undefined && models.length > 0)
-            blocks.push(modelsAvailableLine(models));
-        return blocks.join("\n\n");
+            tail.push(modelsAvailableLine(models));
+        const tailCost = tail.reduce((acc, t) => acc + joiner + bytes(t), 0);
+        const roster = fold(entries, agentListingInitialHeader(toolName), budget.blockMaxBytes - tailCost);
+        return { text: [roster.text, ...tail].join(AGENT_DELTA_BLOCK_JOINER), nameOnly: roster.nameOnly, dropped: roster.dropped, listed: entries.length };
     }
     const announcedIds = new Set([...announced.keys()].map(listingIdentity));
+    const entryIds = new Set(entries.map((e) => listingIdentity(e.name)));
     const added = entries.filter((e) => !announcedIds.has(listingIdentity(e.name))).toSorted((a, b) => a.name.localeCompare(b.name));
-    const removed = [...announced.keys()]
-        .filter((n) => !entries.some((e) => listingIdentity(e.name) === listingIdentity(n)))
-        .sort();
+    const removed = [...announced.keys()].filter((n) => !entryIds.has(listingIdentity(n))).sort();
     const modelsDrifted = state.announcedModels !== undefined &&
         models !== undefined &&
         (state.announcedModels.length !== models.length ||
             state.announcedModels.some((m, i) => listingIdentity(m) !== listingIdentity(models[i])));
     if (added.length === 0 && removed.length === 0 && !modelsDrifted)
         return undefined;
-    const blocks = [];
-    if (added.length > 0)
-        blocks.push(`${agentListingDeltaHeader(toolName)}\n${added.map(line).join("\n")}`);
+    const modelsLine = modelsDrifted ? modelsAvailableLine(models) : undefined;
+    const modelsCost = modelsLine !== undefined ? joiner + bytes(modelsLine) : 0;
+    const ambientCost = removed.length > 0 ? joiner + bytes(AMBIENT_CONTEXT_NOTE) : 0;
+    const removalReserve = removed.length > 0 ? joiner + bytes(removalArmFloor(AGENT_LISTING_REMOVED_HEADER, removed.length)) : 0;
+    const addArm = added.length > 0 ? fold(added, agentListingDeltaHeader(toolName), budget.blockMaxBytes - modelsCost - ambientCost - removalReserve) : undefined;
+    const addCost = addArm === undefined ? 0 : bytes(addArm.text) + joiner;
+    const blocks = addArm === undefined ? [] : [addArm.text];
     if (removed.length > 0) {
-        blocks.push(`${AGENT_LISTING_REMOVED_HEADER}\n${removed.map((n) => `- ${safe(n)}`).join("\n")}`);
+        blocks.push(foldRemovalArmWithin(removed, AGENT_LISTING_REMOVED_HEADER, budget.blockMaxBytes - modelsCost - ambientCost - addCost));
         blocks.push(AMBIENT_CONTEXT_NOTE);
     }
-    if (modelsDrifted)
-        blocks.push(modelsAvailableLine(models));
-    return blocks.join("\n\n");
+    if (modelsLine !== undefined)
+        blocks.push(modelsLine);
+    return { text: blocks.join(AGENT_DELTA_BLOCK_JOINER), nameOnly: addArm?.nameOnly ?? [], dropped: addArm?.dropped ?? [], listed: added.length };
+}
+export function renderAgentListingDelta(state, entries, toolName, models, budget) {
+    return renderAgentListingFrame(state, entries, toolName, models, budget)?.text;
 }
+const AGENT_LISTING_CAP_MARKER = "(listing budget reached — lower-priority agent types are listed name-only)";
+const AGENT_DELTA_BLOCK_JOINER = "\n\n";
 export const MODELS_AVAILABLE_PREFIX = "Models available for the 'model' parameter: ";
 function modelsAvailableLine(models) {
     const named = models.map((m) => sanitizeUntrustedText(m, SHELLED_BODY_ENVELOPE_TAGS));
@@ -594,26 +639,47 @@ export function commitAgentListing(state, entries, models) {
 }
 export const SKILLS_LISTING_DELTA_HEADER = "New skills are now available:";
 export const SKILLS_LISTING_REMOVED_HEADER = "The following skills are no longer available:";
-export function renderSkillsListingDelta(state, entries) {
+const SKILLS_DELTA_BLOCK_JOINER = "\n\n";
+export function renderSkillsListingFrame(state, entries, budget = SKILL_LISTING_DEFAULT_BUDGET) {
     const announced = state.announcedSkills;
     if (announced === undefined) {
         if (entries.length === 0)
             return undefined;
-        return buildSkillsBlock(entries);
+        const block = renderSkillsBlock(entries, budget);
+        return block === undefined ? undefined : { ...block, listed: entries.length };
     }
     const announcedIds = new Set([...announced.keys()].map(listingIdentity));
+    const entryIds = new Set(entries.map((e) => listingIdentity(e.name)));
     const added = entries.filter((e) => !announcedIds.has(listingIdentity(e.name)));
-    const removed = [...announced.keys()].filter((n) => !entries.some((e) => listingIdentity(e.name) === listingIdentity(n)));
+    const removed = [...announced.keys()].filter((n) => !entryIds.has(listingIdentity(n)));
     if (added.length === 0 && removed.length === 0)
         return undefined;
-    const blocks = [];
-    if (added.length > 0)
-        blocks.push(`${SKILLS_LISTING_DELTA_HEADER}\n${added.map((e) => skillListingLine(e)).join("\n")}`);
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const joiner = bytes(SKILLS_DELTA_BLOCK_JOINER);
+    const frameMaxBytes = budget.blockMaxBytes;
+    const ambientCost = removed.length > 0 ? joiner + bytes(AMBIENT_CONTEXT_NOTE) : 0;
+    const removalReserve = removed.length > 0 ? joiner + bytes(removalArmFloor(SKILLS_LISTING_REMOVED_HEADER, removed.length)) : 0;
+    const addArm = added.length > 0
+        ? renderSkillLinesWithin(added, {
+            blockMaxBytes: frameMaxBytes - ambientCost - removalReserve,
+            descMaxChars: budget.descMaxChars,
+            frame: (lines) => [SKILLS_LISTING_DELTA_HEADER, ...lines].join("\n"),
+        })
+        : undefined;
+    const addCost = addArm === undefined ? 0 : bytes(addArm.text) + (removed.length > 0 ? joiner : 0);
+    const blocks = addArm === undefined ? [] : [addArm.text];
     if (removed.length > 0) {
-        blocks.push(`${SKILLS_LISTING_REMOVED_HEADER}\n${removed.map((n) => `- ${sanitizeUntrustedText(n, SHELLED_BODY_ENVELOPE_TAGS)}`).join("\n")}`);
-        blocks.push(AMBIENT_CONTEXT_NOTE);
+        blocks.push(foldRemovalArmWithin(removed, SKILLS_LISTING_REMOVED_HEADER, frameMaxBytes - ambientCost - addCost), AMBIENT_CONTEXT_NOTE);
     }
-    return blocks.join("\n\n");
+    return {
+        text: blocks.join(SKILLS_DELTA_BLOCK_JOINER),
+        nameOnly: addArm?.nameOnly ?? [],
+        dropped: addArm?.dropped ?? [],
+        listed: added.length,
+    };
+}
+export function renderSkillsListingDelta(state, entries, budget) {
+    return renderSkillsListingFrame(state, entries, budget)?.text;
 }
 export function commitSkillsListing(state, entries) {
     state.announcedSkills = new Map(entries.map((e) => [e.name, e.description]));
@@ -659,6 +725,37 @@ export function selectMcpDroppedBatch(entries) {
     }
     return out;
 }
+const TOOLS_DELTA_FIXED_MAX_BYTES = 2048;
+function toolsDeltaBound(inp) {
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const list = (names) => (names.length > TOOLS_DELTA_LIST_MAX ? bytes(groupByMcpServer(names)) : names.reduce((acc, n) => acc + bytes(n) + 3, 0));
+    const swapped = (names) => names.reduce((acc, n) => acc + bytes(n) + 2, 0);
+    const mcp = inp.mcpToolsDelta;
+    return (TOOLS_DELTA_FIXED_MAX_BYTES +
+        list(inp.newTools ?? []) +
+        swapped(inp.newToolsSwappedUnderStatic ?? []) +
+        bytes(groupByMcpServer(mcp?.readded ?? [])) +
+        swapped(inp.readdedToolsSwappedUnderStatic ?? []) +
+        list(mcp?.removed ?? []) +
+        (mcp?.failedServers ?? []).slice(0, TOOLS_DELTA_LIST_MAX).reduce((acc, f) => acc + bytes(f.name) + bytes(f.error ?? "") + 8, 0));
+}
+const MCP_INSTRUCTIONS_FENCE_MAX_BYTES = 512;
+function mcpInstructionsBound(inp) {
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const m = inp.mcpInstructions;
+    if (m === undefined)
+        return 0;
+    return (512 +
+        m.added.reduce((acc, a) => acc + MCP_INSTRUCTIONS_MAX_CHARS * 4 + bytes(a.server) + MCP_INSTRUCTIONS_FENCE_MAX_BYTES, 0) +
+        m.removed.reduce((acc, n) => acc + bytes(n) + 1, 0));
+}
+const MCP_DROPPED_FIXED_MAX_BYTES = 1024;
+function mcpDroppedToolsBound(inp) {
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const first = inp.mcpDroppedTools?.[0];
+    const single = first === undefined ? 0 : MCP_DROPPED_FIXED_MAX_BYTES + bytes(first.tool) + bytes(first.server) + bytes(first.reason) + 32;
+    return Math.max(MCP_DROPPED_BATCH_MAX_BYTES, single);
+}
 const PLAN_MODE_FULL_BODY = `Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits, run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received. Instead, you should: research and analyze with read-only tools, and when you have formed a concrete plan, present it with the ${PRESENT_PLAN_TOOL_NAME} tool for approval. That tool inherently requests plan approval — never ask for approval via plain text.`;
 const PLAN_MODE_SPARSE_BODY = `Plan mode still active (see full instructions earlier in conversation). Read-only: no edits, commits, or config changes. When your plan is ready, present it with the ${PRESENT_PLAN_TOOL_NAME} tool for approval. Never ask about plan approval via plain text.`;
 const TRUNCATION_MARKER = "\n…[truncated]";
@@ -666,12 +763,17 @@ const MIN_KEEP_BYTES = 160;
 function capAttachments(atts) {
     let total = 0;
     for (const a of atts)
-        total += Buffer.byteLength(a.body, "utf8");
+        if (!isIntactSource(a.source))
+            total += Buffer.byteLength(a.body, "utf8");
     if (total <= ATTACHMENT_BYTE_CAP)
         return atts;
     let budget = ATTACHMENT_BYTE_CAP;
     const out = [];
     for (const a of atts) {
+        if (isIntactSource(a.source)) {
+            out.push(a);
+            continue;
+        }
         const len = Buffer.byteLength(a.body, "utf8");
         if (len <= budget) {
             out.push(a);

package/dist/core/safe-notify.d.ts

@@ -56,6 +56,11 @@ export interface SafeNotifierOptions {
      */
     readonly onError?: (failure: SafeNotifyFailure) => void;
 }
+/** The sentence of a contained failure, for a consumer that puts it in front of a person. Total by the
+ *  same rule as {@link containedError}: an error object handed in from elsewhere (a `lastErrorAt`
+ *  reading, a rejection an adapter wrapped) may still carry a hostile `message`, and the disclosure a
+ *  site composes from it must not be the thing that faults. */
+export declare function safeErrorMessage(error: unknown): string;
 export interface SafeNotifier {
     /**
      * Run one host-callback invocation, containing any throw. Returns `true` when it completed, `false` when it

package/dist/core/safe-notify.js

@@ -1,9 +1,30 @@
+function containedError(thrown) {
+    try {
+        if (thrown instanceof Error && typeof thrown.message === "string")
+            return thrown;
+        return new Error(String(thrown));
+    }
+    catch {
+        return new Error(`a thrown value of type ${typeof thrown} that cannot be inspected or converted to text`);
+    }
+}
+export function safeErrorMessage(error) {
+    try {
+        const m = error?.message;
+        if (typeof m === "string")
+            return m;
+        return String(error);
+    }
+    catch {
+        return "a failure whose message could not be read";
+    }
+}
 export function createSafeNotifier(opts) {
     const onError = opts?.onError;
     let sites;
     let total = 0;
     const record = (site, thrown) => {
-        const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+        const error = containedError(thrown);
         total += 1;
         if (sites === undefined)
             sites = new Map();
@@ -60,8 +81,9 @@ export function createSafeNotifier(opts) {
 export function observeThenableRejection(r, notifier, site) {
     if (typeof r?.then === "function") {
         r.then(undefined, (err) => {
+            const error = containedError(err);
             notifier.notify(() => {
-                throw err instanceof Error ? err : new Error(String(err));
+                throw error;
             }, site);
         });
     }

package/dist/core/sensitive-path-policy.d.ts

@@ -3,6 +3,22 @@ import type { ToolPolicy } from "./tool-policy.js";
 /** fs hand tools that take a `path` and write — the reliably-guardable surface. NotebookEdit joined
  *  in [886]①a (mirror of the fs-write-gate's covered set): its target is `notebook_path`, and a
  *  guard that ignored notebook writes to the same paths by default was the same hole one tool away. */
+/**
+ * The agent-configuration block of {@link RECOMMENDED_SENSITIVE_PATTERNS} MIRRORS the read tier (spelled as
+ * literals so the closed set stays statically readable; a set-equality pin keeps the mirror exact): the read tier's rows already encode this severity's predicate ("an agent's own config
+ * FILE, whose `env`/`mcpServers` block is a credential or a command line the host launches") and argue
+ * each one. Shared is the VOCABULARY, not the judgment.
+ *
+ * @contract sensitive_paths.agent_config_tier_is_shared — the write deny set's agent-configuration
+ * block IS the read face's `agent-config` tier, row for row: one table, two judges, and the two faces
+ * cannot drift into disagreeing about which files are an agent's own configuration. The CONFIGURATION
+ * DIRECTORIES (`.claude`, `.sema`) are on neither face's deny side — their write guard is ASK
+ * severity, where an approver or a persisted allow rule can clear it. Their `hooks/` and `agents/`
+ * sub-directories are the two exceptions and they are NOT part of this mirror: a hook script is an executable
+ * body and an agent definition re-authorizes the agent on load, both guarded on the write face only, by
+ * hand-kept rows of the list below.
+ */
+export declare function agentConfigDenyPatterns(): readonly string[];
 /**
  * RECOMMENDED default pattern set for {@link createSensitivePathPolicy} (additive export).
  * NO upstream verbatim anchor exists (cc-anchors/2.1.209 carries no sensitive/dangerous file-pattern
@@ -20,13 +36,15 @@ import type { ToolPolicy } from "./tool-policy.js";
  *
  * HRD-PRM-10 — sema's own data root (`$AGENT_DATA_DIR ?? ~/.ai-agent`) is excluded BY CONSTRUCTION,
  * not by the absence of an entry. The exclusion used to be "just don't add a pattern that names it",
- * which held only as long as no entry happened to match one of its ANCESTOR segments. That assumption
- * died the moment the shell's own config root joined the list: the shell sets
+ * which held only as long as no entry happened to match one of its ANCESTOR segments — and that
+ * assumption died the first time a directory-wide config-root entry was on this list: the shell sets
  * `AGENT_DATA_DIR = <configRoot>/engine-data` with a configRoot of `~/.sema`, so every path under the
- * data root carries a `.sema` segment, and a pattern guarding the config root swallowed the whole data
- * root with it — including the memory library the model is INSTRUCTED to write with the Write tool
+ * data root carries a `.sema` segment, and the entry swallowed the whole data root with it —
+ * including the memory library the model is INSTRUCTED to write with the Write tool
  * (`MEMORY_INSTRUCTION_TEMPLATE`), i.e. every memory write refused, on a default server wiring.
- * So the exclusion is now mechanical: a target INSIDE the data root is matched on its path RELATIVE to
+ * That entry is gone (see the severity layering below), but the exclusion stays mechanical — a
+ * deployment may site its data root beneath ANY guarded directory, and both tiers honour it. A
+ * target INSIDE the data root is matched on its path RELATIVE to
  * that root (see {@link createSensitivePathPolicy}'s `dataRoot`), so the root's own ancestry is not the
  * target's business, while a genuinely sensitive path INSIDE it (`<dataRoot>/x/.ssh/id_rsa`) still
  * matches. The `sessions/` subtree keeps its own owner: `createTranscriptIntegrityPolicy` is wired
@@ -34,6 +52,13 @@ import type { ToolPolicy } from "./tool-policy.js";
  * transcripts is routine» and a legitimate operator write must remain clearable by judgment — and a
  * deny here would outrank that ask under the deny > ask > allow fold and silently convert it into a
  * hard refusal for every deployment that wires this list.
+ *
+ * SEVERITY LAYERING for the agent-configuration class: the law is {@link agentConfigDenyPatterns} —
+ * configuration FILES here, the DIRECTORY one step down on the always-on write-protection table
+ * (`WRITE_PROTECTED_DEFAULT_TABLE`'s `.claude` / `.sema` rows — the same reach, since that judge sees the
+ * real target too, {@link import("./write-protect.js").WriteProtectionMatcher.judge}); a directory also
+ * holds the person's own material, and a directory-wide DENY entry turned an explicit instruction to edit
+ * `.claude/projects/…` into a refusal nobody could lift (a deny outranks an ask under the fold).
  */
 export declare const RECOMMENDED_SENSITIVE_PATTERNS: readonly string[];
 /**
@@ -53,22 +78,64 @@ export declare const RECOMMENDED_SENSITIVE_PATTERNS: readonly string[];
  */
 export declare function dataRootSpellings(explicit: string | undefined): string[];
 /**
- * Build a composable policy that DENIES writes (via the guarded fs tools) whose canonical target
- * lands on a sensitive path. `patterns` are deployment-supplied (no default list is shipped — the
- * set of escalation-vector paths is deployment-specific); an empty list is a no-op allow.
+ * The data root's identity in the SAME namespace a judged key lives in: every declared spelling
+ * ({@link dataRootSpellings}) run through the SAME `canonicalizeTarget` that mints the target key. Not a
+ * second canonicalization — the same one, on the other operand, which is what lets
+ * {@link relativeUnderRoot}'s comparison be exact.
+ *
+ * Resolved PER CALL, deliberately not cached. A cached canonical root is a snapshot of the symlink
+ * topology at first use: with a data root reached through a symlink, retargeting it left the policy
+ * still exempting the OLD target for the life of the run. The module header already accepts paying
+ * `canonicalizeTarget` twice for a guarded write as the price of a decoupled gate; this is the same
+ * bargain on the other operand, and a request-scoped cache is the same note's answer if profiling
+ * ever asks for one. A spelling that cannot be resolved contributes NO exemption (the guard's side wins).
+ *
+ * ONE resolver for both write judges (the deny set here, the always-on table's target view) — an
+ * engine-internal seam, like the two neighbours above.
+ */
+export declare function canonicalDataRootKeys(env: ExecutionEnv, spellings: readonly string[], signal?: AbortSignal): Promise<string[]>;
+/**
+ * Is `targetKey` inside the data root `rootKey`, and if so what is its path relative to it? Returns
+ * the relative sub-path (`""` when the target IS the root), or `null` for everything else.
+ *
+ * 🔴 EXACT, and deliberately nothing else. Both operands are minted by the SAME canonicalizer, so
+ * every transformation this comparison could apply — a case fold, an NFC pass, splitting a foreign
+ * separator family, unioning several readings of the root — can only ADD matches. On the DENY side of
+ * this file that is the safe direction and several of those transforms are applied on purpose (a
+ * spelling filter is not a path filter). Here the direction inverts: this test grants an EXEMPTION, so
+ * an added match is not a wider guard, it is a bypass of one — each of case folding, an NFC pass and a
+ * foreign-family read was measured leaking an unrelated sibling into the exemption (their pins name the
+ * shapes). The rule: compare what the canonicalizer produced, byte for byte, every uncertainty falling
+ * to the deny side.
+ *
+ * The separator family comes from the ROOT key (a backslash is an ordinary filename character on
+ * POSIX, so a root `/x/.sema/data` must not swallow the sibling FILE `/x/.sema/data\evil`), and a root
+ * that reduces to nothing exempts nothing rather than exempting the filesystem.
+ *
+ * Exported as an ENGINE-INTERNAL seam (not re-exported from `src/index.ts`), like {@link dataRootSpellings}:
+ * the always-on write-protection judge applies the same exemption on its target view, and a second
+ * containment test would be a second place for the two judges to disagree about what "inside" means.
+ */
+export declare function relativeUnderRoot(targetKey: string, rootKey: string): string | null;
+/**
+ * Build a composable policy that DENIES writes (via the guarded fs tools) whose CANONICAL target lands on
+ * a guarded pattern. `patterns` is deployment-supplied — no default list is shipped; empty = a no-op allow.
+ * A deny is a refusal no approver and no persisted allow rule can lift. The ASK severity of the same class
+ * (the agent-configuration DIRECTORIES) is not a tier here: it is the always-on write-protection table's,
+ * which judges the same real target ({@link import("./write-protect.js").WriteProtectionMatcher.judge} —
+ * its contract sentence `write_protection.judges_the_real_target` says the two differ in vocabulary and
+ * severity, never in reach).
  *
  * `env` is the same ExecutionEnv the hands run against (inject the one you pass to the Runner), so
  * canonicalization sees the task's real filesystem (a remote/E2B task resolves in its container).
- * `rootPath` is the FALLBACK base a relative path resolves against (omit = paths resolve as given).
- * When the engine stamps a live cwd onto the request (`ToolCallRequest.cwd` — the tracked
- * directory the shell's `cd` moves and the fs tools resolve with), THAT wins for the call's target, so
- * the guard judges the file the tool will actually write. `rootPath` still serves every deployment that
- * calls this policy outside a Runner.
+ * `rootPath` plays the same fallback-base role it plays on the sibling write gate (see
+ * {@link import("./fs-write-gate-policy.js").FsWriteGatePolicyOptions.rootPath}); the call's live
+ * `ToolCallRequest.cwd` outranks it for the target.
  *
- * Fail-open by design: a tool with no string `path`, or a path that cannot be canonicalized, returns
- * `allow` here — this guard adds a denial on top of the other gates, it is not the only line of
- * defense, and it must not turn an unrelated tool call into a spurious deny. The verdict it owns is
- * narrow and certain: "the real target IS a guarded path → deny".
+ * Fail-open by design: a tool with no string `path` returns `allow` here — this guard adds friction on
+ * top of the other gates, it is not the only line of defense, and it must not turn an unrelated tool
+ * call into a spurious verdict. The verdict it owns is narrow and certain: "the real target IS a
+ * guarded path → deny". (A target it could not RESOLVE is the one fail-CLOSED arm, below.)
  */
 export declare function createSensitivePathPolicy(opts: {
     env: ExecutionEnv;

package/dist/core/sensitive-path-policy.js

@@ -1,9 +1,12 @@
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { canonicalizeTarget, expandHomeTilde, isAbsoluteForFamily, isWinFormPath, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
-import { compileSegmentPattern, matchSegmentPatterns } from "../tools/fs/read-deny.js";
+import { compileSegmentPattern, matchSegmentPatterns, READ_FACE_BUILTIN_DENY_TABLE } from "../tools/fs/read-deny.js";
 import { isProtectedWrite, protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
+export function agentConfigDenyPatterns() {
+    return READ_FACE_BUILTIN_DENY_TABLE.filter((row) => row.tier === "agent-config").map((row) => row.pattern);
+}
 export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".env",
     ".env.*",
@@ -18,10 +21,25 @@ export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".git/hooks",
     ".git/config",
     ".git/modules",
-    ".mcp.json",
-    ".claude*",
-    ".sema",
+    ".sema/settings.json",
+    ".sema/settings.local.json",
     ".sema.*",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".claude.*",
+    ".mcp.json",
+    ".ai-agent/.env",
+    ".sema/engine-data/.env",
+    ".codex/config.toml",
+    ".cursor/mcp.json",
+    ".continue/config.json",
+    ".continue/config.yaml",
+    ".aider.conf.yml",
+    ".gemini/settings.json",
+    ".claude/hooks",
+    ".sema/hooks",
+    ".claude/agents",
+    ".sema/agents",
     ".sema-notifier-build",
     ".aws",
     ".config/gcloud",
@@ -46,7 +64,20 @@ export function dataRootSpellings(explicit) {
     }
     return out;
 }
-function relativeUnderRoot(targetKey, rootKey) {
+export async function canonicalDataRootKeys(env, spellings, signal) {
+    const keys = [];
+    for (const spelling of spellings) {
+        try {
+            const r = await canonicalizeTarget(env, spelling, signal, pathFamilyOf({ root: spelling }));
+            if (r.ok && !keys.includes(r.key))
+                keys.push(r.key);
+        }
+        catch {
+        }
+    }
+    return keys;
+}
+export function relativeUnderRoot(targetKey, rootKey) {
     const seps = isWinFormPath(rootKey) ? ["\\", "/"] : ["/"];
     let root = rootKey;
     while (root.length > 0 && seps.includes(root[root.length - 1]))
@@ -78,19 +109,6 @@ function matchSensitive(canonicalKey, compiled, aliasResolved) {
 export function createSensitivePathPolicy(opts) {
     const compiled = compilePatterns(opts.patterns);
     const dataRootPaths = dataRootSpellings(opts.dataRoot);
-    const dataRootKeys = async (signal) => {
-        const keys = [];
-        for (const spelling of dataRootPaths) {
-            try {
-                const r = await canonicalizeTarget(opts.env, spelling, signal, pathFamilyOf({ root: spelling }));
-                if (r.ok && !keys.includes(r.key))
-                    keys.push(r.key);
-            }
-            catch {
-            }
-        }
-        return keys;
-    };
     const guardedByName = opts.tools !== undefined ? new Set(opts.tools) : undefined;
     return {
         async check(req, signal) {
@@ -113,7 +131,7 @@ export function createSensitivePathPolicy(opts) {
                 };
             }
             let relative = null;
-            for (const rootKey of await dataRootKeys(signal)) {
+            for (const rootKey of await canonicalDataRootKeys(opts.env, dataRootPaths, signal)) {
                 relative = relativeUnderRoot(canon.key, rootKey);
                 if (relative !== null)
                     break;