@sema-agent/core 7.17.7 → 7.19.0

package/dist/core/runner/tool-progress-lane.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The run's TOOL-PROGRESS lane — the single mint of the `tool_progress` frame: its clock, its cadence,
+ * and the heartbeat that keeps a silent long-running tool call visible.
+ *
+ * TWO PRODUCERS, ONE MINT. A tool that observes its own work ticks fast and carries what it produced: the
+ * shell's execute leg watches its command's output and calls `emit` about once a second. Every OTHER call is
+ * opaque here — the runner knows only that it started and has not ended — so this lane runs a slow beat for
+ * any in-flight call silent for {@link TOOL_HEARTBEAT_MS}.
+ *
+ * THE LANE OWNS TIME, the producer owns FACTS. A producer reports what it has seen (the tail, the totals),
+ * never how long it has run: `elapsedTimeSeconds` is computed HERE from one origin per call, because the two
+ * producers do not start their clocks together — the station registers a call when it ENTERS EXECUTION, a
+ * shell command's own clock could only start at its spawn. With two origins a 30 s beat could be followed
+ * moments later by a shell tick reporting 1 s, breaking the monotonicity the frame promises.
+ *
+ * THE CADENCE HAS ONE ENFORCEMENT POINT, same reason: a producer's timer is a SAMPLING clock, not the
+ * contract. `emit` drops a frame landing inside {@link TOOL_PROGRESS_MIN_INTERVAL_MS} of that call's last.
+ *
+ * ONE RULE FOR THE BEAT: a call is beaten when nothing has been emitted FOR IT for a whole interval,
+ * counting its own start as the first such event — covering both "it only just started" and "the tool
+ * already ticks faster than this". The interval is the RUN's, so a first beat lands anywhere in
+ * [TOOL_HEARTBEAT_MS, 2 × TOOL_HEARTBEAT_MS): the price of one timer per run, stated rather than hidden.
+ *
+ * THE CLOCK IS MONOTONIC: every predicate here is a DIFFERENCE of two readings (is this call due a beat, is
+ * this offer inside the floor, how long has it run), and off the wall clock a backward step — NTP, a
+ * container's clock settling after a resume — makes each difference negative and silences BOTH producers
+ * until it catches up: the exact failure this lane exists to prevent.
+ *
+ * LIVENESS ONLY — see the `tool_progress` member's contract in `task-event.ts`. The timer is `unref`'d and
+ * every emission is fault-contained. */
+import type { TaskEvent, TaskEventIdentity } from "../types.js";
+import type { ToolProgressLane } from "./contracts.js";
+/** How long a tool call may stay silent before this lane beats for it, in ms. ONE SOURCE, and CC
+ *  2.1.259's own per-tool heartbeat interval (`Cct`) — this engine keeps the cadence and folds the beat
+ *  into the one progress frame instead of minting a second shape (registered divergence). */
+export declare const TOOL_HEARTBEAT_MS = 30000;
+/** The floor between two frames of ONE call — the `tool_progress.cadence` contract, enforced here and
+ *  nowhere else so it holds across producers rather than inside each one. */
+export declare const TOOL_PROGRESS_MIN_INTERVAL_MS = 1000;
+/** Build the lane over the run's content pusher (`pushContent` — the ONE seat that puts a frame on this
+ *  run's queue and, for a sub-agent, forwards it to the parent's sink) and its identity mint. */
+export declare function createToolProgressLane(push: (e: TaskEvent) => void, ident: () => TaskEventIdentity): ToolProgressLane;

package/dist/core/runner/tool-progress-lane.js

@@ -0,0 +1,61 @@
+export const TOOL_HEARTBEAT_MS = 30_000;
+export const TOOL_PROGRESS_MIN_INTERVAL_MS = 1_000;
+const monotonicNow = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+export function createToolProgressLane(push, ident) {
+    const inFlight = new Map();
+    let timer;
+    const arm = () => {
+        if (timer !== undefined)
+            return;
+        timer = setInterval(beat, TOOL_HEARTBEAT_MS);
+        timer.unref?.();
+    };
+    const emit = (body) => {
+        const now = monotonicNow();
+        let live = inFlight.get(body.toolCallId);
+        if (live === undefined) {
+            live = { toolName: body.toolName, startedAt: now, lastAt: now - TOOL_PROGRESS_MIN_INTERVAL_MS };
+            inFlight.set(body.toolCallId, live);
+            arm();
+        }
+        if (now - live.lastAt < TOOL_PROGRESS_MIN_INTERVAL_MS)
+            return;
+        live.lastAt = now;
+        try {
+            push({ type: "tool_progress", ...body, elapsedTimeSeconds: Math.floor((now - live.startedAt) / 1000), ...ident() });
+        }
+        catch {
+        }
+    };
+    function beat() {
+        const now = monotonicNow();
+        for (const [toolCallId, live] of inFlight) {
+            if (now - live.lastAt < TOOL_HEARTBEAT_MS)
+                continue;
+            emit({ toolCallId, toolName: live.toolName });
+        }
+    }
+    const disarm = () => {
+        if (timer === undefined)
+            return;
+        clearInterval(timer);
+        timer = undefined;
+    };
+    return {
+        emit,
+        noteStart(toolCallId, toolName) {
+            const startedAt = monotonicNow();
+            inFlight.set(toolCallId, { toolName, startedAt, lastAt: startedAt });
+            arm();
+        },
+        noteEnd(toolCallId) {
+            inFlight.delete(toolCallId);
+            if (inFlight.size === 0)
+                disarm();
+        },
+        clear() {
+            inFlight.clear();
+            disarm();
+        },
+    };
+}

package/dist/core/runner/turn-attachments.d.ts

@@ -1,6 +1,7 @@
 import type { McpDroppedTool } from "../mcp.js";
 import type { TaskSpec } from "../types.js";
-import { type SkillListingEntry } from "./synthetic-tools.js";
+import { type SkillListingEntry, type SkillsBlockRender } from "./synthetic-tools.js";
+import { type ResolvedSkillListingBudget } from "../skill-listing-budget.js";
 /**
  * Turn-boundary attachment seam: the PURE producer layer (CC `getContextAttachments`
  * parity). This module is the single home of the CC-parity cadence judgment + reminder copy (提示词主权批:
@@ -545,6 +546,9 @@ export interface AttachmentInputs {
      *  the delta path serves dynamic-installation deployments and tests, same posture as
      *  `agentListing`). Only passed when `config.skillsListing` is on. */
     skillsListing?: ReadonlyArray<SkillListingEntry>;
+    /** The lowered skills-listing budget seats, resolved once at the config door. Absent ⇒ the module
+     *  defaults, i.e. byte-identical to the pre-seat render. */
+    skillsListingBudget?: ResolvedSkillListingBudget;
     /** G1 续批 mcp_instructions: pending deltas snapshotted from `MaterializedMcp.instructionsDelta`.
      *  CALLER-owned consumption on intact cap survival (same `newTools` discipline). */
     mcpInstructions?: {
@@ -849,21 +853,48 @@ export declare function commitAgentListing(state: AttachmentState, entries: Read
 export declare const SKILLS_LISTING_DELTA_HEADER = "New skills are now available:";
 /** [c209-C] skills removal-arm header — mirrors the agent-listing removal arm's phrasing. */
 export declare const SKILLS_LISTING_REMOVED_HEADER = "The following skills are no longer available:";
+/** What one {@link renderSkillsListingFrame} call produced: the render's own report, plus the
+ *  denominator it is against. */
+export interface SkillsListingFrameRender extends SkillsBlockRender {
+    /** How many skills this frame set out to list — the whole roster on an initial frame, the ADDED set
+     *  on a drift frame. The disclosure's denominator, read off the frame that was actually delivered
+     *  rather than re-derived from the roster. */
+    readonly listed: number;
+}
 /**
- * [c209-C] skills_listing producer — the skills counterpart of {@link renderAgentListingDelta}.
- * First call (no announced map) = the full `<skills>` disclosure block VERBATIM (buildSkillsBlock —
- * the exact bytes that used to sit in the stable system prompt now ride the reminder lane; CC 209
- * classic ships its skills listing the same way, as a first-user-turn reminder ~5.9KB, report §5.1).
- * Later calls announce only drift, name-keyed like the agent arm: adds under
- * {@link SKILLS_LISTING_DELTA_HEADER} with the SAME `- name: description` line shape the block uses,
- * removals under {@link SKILLS_LISTING_REMOVED_HEADER} + `- <name>` lines, followed by the
- * CC-verbatim {@link AMBIENT_CONTEXT_NOTE} (agent-removal-arm parity). A description change on an
- * existing name is not re-announced (name-keyed, agent-arm parity).
+ * [c209-C] skills_listing producer — the skills counterpart of {@link renderAgentListingDelta}, with
+ * the degradation report the disclosure lane announces. First call (no announced map) = the full
+ * `<skills>` disclosure block VERBATIM (the exact bytes that used to sit in the stable system prompt
+ * now ride the reminder lane; CC 209 classic ships its skills listing the same way, as a
+ * first-user-turn reminder ~5.9KB, report §5.1). Later calls announce only drift, name-keyed like the
+ * agent arm: adds under {@link SKILLS_LISTING_DELTA_HEADER} with the SAME `- name: description` line
+ * shape the block uses, removals under {@link SKILLS_LISTING_REMOVED_HEADER} + `- <name>` lines,
+ * followed by the CC-verbatim {@link AMBIENT_CONTEXT_NOTE} (agent-removal-arm parity). A description
+ * change on an existing name is not re-announced (name-keyed, agent-arm parity).
+ *
+ * ONE RULER FOR EVERY FRAME: the drift frame is measured against the SAME resolved budget as the
+ * initial block, arms and joiners included, and its ADD arm degrades through the same three tiers
+ * ({@link renderSkillLinesWithin}). An unmeasured drift frame is the block's own failure mode one lane
+ * over: a roster's worth of new skills renders past `ATTACHMENT_BYTE_CAP`, `capAttachments` clips the
+ * body, a clipped body never equals the intact-survival re-render, and the frame is re-rendered and
+ * re-clipped at every boundary for the life of the task. The split: the ambient tail and the removal
+ * arm's one-line floor are reserved first (both constants), the ADD arm degrades into what is left,
+ * and the removal arm spends whatever the add arm did not — so the frame's size is the resolved budget
+ * or, when even the two floors do not fit it, a small constant, never a function of the roster.
+ *
+ * The report covers the ADD arm only: `nameOnly` / `dropped` name skills this frame listed without a
+ * description or could not list at all. A departed name that did not fit is not a listed skill.
  *
  * MED-3① discipline: PURE — the announced-set advance is CALLER-owned via {@link commitSkillsListing},
- * committed only on first-frame delivery or intact cap survival at a boundary.
+ * committed only on first-frame delivery or intact cap survival at a boundary. The commit records
+ * EVERY entry, including one this frame dropped: the alternative is a frame re-rendering the same
+ * un-listable tail at every boundary, which is the replay this budget exists to end. The `Skill` tool
+ * serves a dropped skill, and `skills.listing_truncated` tells the deployment it happened.
  */
-export declare function renderSkillsListingDelta(state: AttachmentState, entries: ReadonlyArray<SkillListingEntry>): string | undefined;
+export declare function renderSkillsListingFrame(state: AttachmentState, entries: ReadonlyArray<SkillListingEntry>, budget?: ResolvedSkillListingBudget): SkillsListingFrameRender | undefined;
+/** The text-only face of {@link renderSkillsListingFrame} — what the delivery lanes render, and what
+ *  the intact-survival predicate re-renders to compare. */
+export declare function renderSkillsListingDelta(state: AttachmentState, entries: ReadonlyArray<SkillListingEntry>, budget?: ResolvedSkillListingBudget): string | undefined;
 /** [c209-C] commit half of {@link renderSkillsListingDelta} — same MED-3① contract as
  *  {@link commitAgentListing}: called by the run loop only on first-frame delivery or when the
  *  `skills_listing` block survived the capped bundle INTACT; a clipped/dropped block leaves the

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

@@ -1,7 +1,8 @@
 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_DESC_MAX_CHARS_DEFAULT, SKILLS_BLOCK_MAX_BYTES } from "../skill-listing-budget.js";
 import { TOOL_SEARCH_NAME as TOOL_SEARCH_TOOL_NAME } from "./tool-disclosure.js";
 export const TODO_REMINDER_CONFIG = {
     TURNS_SINCE_WRITE: 10,
@@ -209,7 +210,9 @@ export function collectDueAttachments(state, inp) {
     const agentListingBody = inp.config.agentListing && inp.agentListing !== undefined
         ? renderAgentListingDelta(state, inp.agentListing, inp.agentToolName ?? "Agent", inp.agentModels)
         : undefined;
-    const skillsListingBody = inp.config.skillsListing && inp.skillsListing !== undefined ? renderSkillsListingDelta(state, inp.skillsListing) : undefined;
+    const skillsListingBody = inp.config.skillsListing && inp.skillsListing !== undefined
+        ? renderSkillsListingDelta(state, inp.skillsListing, inp.skillsListingBudget)
+        : undefined;
     const listingPair = [];
     if (agentListingBody !== undefined)
         listingPair.push({ source: "agent_listing", body: agentListingBody });
@@ -545,10 +548,9 @@ export function renderAgentListingDelta(state, entries, toolName, models) {
         return blocks.join("\n\n");
     }
     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 ||
@@ -594,26 +596,68 @@ 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";
+function skillsRemovalArmFloor(count) {
+    return [SKILLS_LISTING_REMOVED_HEADER, `(… +${count} more are no longer available)`].join("\n");
+}
+function renderSkillsRemovalArm(removed, maxBytes) {
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const lines = removed.map((n) => `- ${sanitizeUntrustedText(n, SHELLED_BODY_ENVELOPE_TAGS)}`);
+    const head = bytes(SKILLS_LISTING_REMOVED_HEADER);
+    const lineCost = (l) => bytes(l) + 1;
+    const prefix = new Array(lines.length + 1);
+    prefix[0] = 0;
+    for (let i = 0; i < lines.length; i++)
+        prefix[i + 1] = prefix[i] + lineCost(lines[i]);
+    if (head + prefix[lines.length] <= maxBytes)
+        return [SKILLS_LISTING_REMOVED_HEADER, ...lines].join("\n");
+    for (let m = lines.length - 1; m >= 0; m--) {
+        const tail = `(… +${lines.length - m} more are no longer available)`;
+        if (head + prefix[m] + lineCost(tail) <= maxBytes)
+            return [SKILLS_LISTING_REMOVED_HEADER, ...lines.slice(0, m), tail].join("\n");
+    }
+    return skillsRemovalArmFloor(lines.length);
+}
+export function renderSkillsListingFrame(state, entries, 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 = Math.min(budget?.blockMaxBytes ?? SKILLS_BLOCK_MAX_BYTES, SKILLS_BLOCK_MAX_BYTES);
+    const ambientCost = removed.length > 0 ? joiner + bytes(AMBIENT_CONTEXT_NOTE) : 0;
+    const removalReserve = removed.length > 0 ? joiner + bytes(skillsRemovalArmFloor(removed.length)) : 0;
+    const addArm = added.length > 0
+        ? renderSkillLinesWithin(added, {
+            blockMaxBytes: frameMaxBytes - ambientCost - removalReserve,
+            descMaxChars: budget?.descMaxChars ?? SKILL_LISTING_DESC_MAX_CHARS_DEFAULT,
+            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(renderSkillsRemovalArm(removed, 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]));

package/dist/core/runner-deps.d.ts

@@ -393,7 +393,7 @@ export interface RunnerDeps {
     };
     /**
      * design/199 件A — the DEPLOYMENT's read-face declaration
-     * ({@link import("../tools/fs/read-face.js").ReadFace}; see {@link TaskSpec.readFace} for the
+     * ({@link import("../tools/fs/containment-face.js").ContainmentFace}; see {@link TaskSpec.readFace} for the
      * task layer and the resolution order). An interactive single-user product declares
      * `readFace: "open"` here in one line; the engine default stays "roots" (D-1b). Under org
      * governance this seat may still open (it is the deployment's own declaration); the task layer
@@ -406,7 +406,19 @@ export interface RunnerDeps {
      * later prepare reads the new declaration; announced as `config.read_face_swapped`). A host whose
      * declaration arrives late (a governance source read after boot) swaps it in rather than restarting.
      */
-    readFace?: import("../tools/fs/read-face.js").ReadFace;
+    readFace?: import("../tools/fs/containment-face.js").ContainmentFace;
+    /**
+     * The DEPLOYMENT's WRITE-face declaration
+     * ({@link import("../tools/fs/containment-face.js").ContainmentFace}; see {@link TaskSpec.writeFace}
+     * for the task layer and the resolution order — the SAME order the read seat runs, one body). The
+     * engine default stays "roots". Under org governance this seat may still open (it is the deployment's
+     * own declaration); the task layer may not. Beside a read-only (verifier) mount this seat's "open"
+     * silently CLAMPS to roots and is ANNOUNCED (`config.write_face_deployment_clamped`); TaskSpec.writeFace's
+     * own "open" there refuses loudly. INDEPENDENT of {@link readFace}: neither seat reads the other. A LIVE
+     * seat — `Runner.swapDeps({ writeFace })` replaces it without a restart (announced as
+     * `config.write_face_swapped`).
+     */
+    writeFace?: import("../tools/fs/containment-face.js").ContainmentFace;
     /**
      * design/96 §20 (P1a) — DEPLOYMENT-DECLARED training knowledge cutoff per model id (e.g.
      * `{ "qwen-3.5-35b": "2025-01", "deepseek-pro": "2024-07" }`). When the resolved model id is present, the
@@ -663,10 +675,28 @@ export interface RunnerDeps {
         sessionContext?: readonly string[];
         /** Transcript-window bounds for the classify prompt (defaults: 40 entries / 2000 chars each). */
         window?: import("./auto-mode-prompt.js").AutoModeWindowOptions;
-        /** Classify round-trip cap, ms (default 15_000). A round past the cap is `unavailable(timeout)`: the call is
-         *  DENIED with a sentence that says so (CC 2.1.250 form), and the next call is classified afresh — there is no
-         *  failure count and no session latch. */
+        /** Classify round-trip cap, ms (default 15_000) — ONE ladder rung (see `classifierFallback`), not the
+         *  whole classification. A rung past the cap did not rule: the walk moves to the next candidate, and with
+         *  none left the call is DENIED with a sentence that says so. The next call is classified afresh. */
         timeoutMs?: number;
+        /**
+         * What a classification does when the classifier SEAT does not rule (the leg threw / rejected, the cap
+         * elapsed, or the reply carried no verdict):
+         *  - `"main"` (DEFAULT) — re-ask the SAME prompt on this run's own main model, once, and act on what it
+         *    says; only if that rung does not rule either does the call reach the fail-closed deny. The record
+         *    says which model answered (`GateDisposition.classifier`) and the first move per (rung, cause)
+         *    announces `classifier.fallback` to the operator.
+         *  - `"none"` — one rung: a classifier that does not rule denies the call exactly as it did before this
+         *    knob existed, at exactly one model call.
+         *
+         * COST of the default, stated: while the seat is broken every gated call pays a second round-trip
+         * (worst case two `timeoutMs` caps); `"none"` buys that back for the deny.
+         *
+         * A value outside the closed set ({@link import("./auto-mode.js").AUTO_MODE_CLASSIFIER_FALLBACKS}) is
+         * REFUSED loudly at prepare (`config.auto_mode_classifier_fallback_invalid`) — never clamped, never read
+         * as the default.
+         */
+        classifierFallback?: import("./auto-mode.js").AutoModeClassifierFallback;
         /**
          * The classifier DENIAL LIMIT (CC 2.1.250 `FO`/`AKe`): a run whose classifier keeps blocking falls
          * back to a PERSON instead of being denied without end. Per run: a `block` first increments the
@@ -1357,8 +1387,9 @@ export interface RunnerDeps {
      * knob. ② The engine's own candidates — `ToolSpec.defer === true`, every REMOTE-PROTOCOL tool name
      * (MCP **and** A2A peer tools), and built-in tools that declare their own `defer` — sit behind ONE
      * threshold gate, all or nothing: deferred iff their inlined size (name + description + schema; the
-     * candidate set only — the caller's list, pins and non-candidates are not measured) reaches 10% of the
-     * model's context window; below that they ship inline in full and no ToolSearch is mounted.
+     * candidate set only — the caller's list, pins and non-candidates are not measured) reaches the
+     * {@link toolSearch} threshold (10% of the model's context window when that seat is absent); below that
+     * they ship inline in full and no ToolSearch is mounted.
      *
      * `"auto"` is a CANDIDATE-WIDENING knob, not a second gate: it adds every caller spec — undeclared
      * caller tools included — to the candidate set, measured and decided by the same threshold. Engine
@@ -1369,6 +1400,16 @@ export interface RunnerDeps {
      * if this text drifts.
      */
     deferMode?: "auto";
+    /**
+       * Rule ②'s GATE POLICY — when the engine's candidate set ships as placeholders — in three states:
+       * `true` (always), `false` (never; with no caller list no ToolSearch mounts at all), `{mode:"auto",
+       * thresholdPercent}` (the threshold gate at that percent of the model's context window). Absent ⇒
+       * `{mode:"auto", thresholdPercent:10}`. ORTHOGONAL to {@link deferMode}, which decides WHICH tools are
+       * candidates; neither touches rule ① ({@link TaskSpec.deferTools} still defers,
+       * {@link TaskSpec.alwaysLoadTools} still pins first). A value outside the domain refuses at prepare
+       * (`config.tool_search_invalid`), a `thresholdPercent` outside a finite `[0, 100]` included.
+     */
+    toolSearch?: import("./tool-search-setting.js").ToolSearchSetting;
     /**
      * design/84 Seam C — compact-boundary COST optimization (data-gated, default OFF). A FUNCTION seam (a
      * trusted control-plane injection), so it lives on `RunnerDeps` — NOT `TaskSpec`: `TaskSpec` is the

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,8 +52,22 @@ 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 {@link RECOMMENDED_SENSITIVE_ASK_PATTERNS}
+ * (same judge, so the severity drops and the reach does not); a directory also holds the person's own
+ * material, and the directory-wide 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[];
+/**
+ * The ASK-severity half of the same guard: the agent-configuration DIRECTORIES, on the SAME judge
+ * ({@link createSensitivePathPolicy}'s `askPatterns` seat, whose ABSENCE reads as this list) — only the
+ * directories, since the configuration FILES inside them are deny material above. It lives HERE and not
+ * only on `WRITE_PROTECTED_DEFAULT_TABLE`, which names the same segments but judges LEXICALLY: a
+ * symlink with an innocent name walks past that one, so demoting to it alone trades severity for REACH.
+ */
+export declare const RECOMMENDED_SENSITIVE_ASK_PATTERNS: readonly string[];
 /**
  * HRD-PRM-10 — the engine data root, read from the same knob its two consumers read
  * (`$AGENT_DATA_DIR ?? ~/.ai-agent`, off the HOST at wiring time, NFC-normalized) and returned in
@@ -53,27 +85,36 @@ 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.
+ * Build a composable policy that judges writes (via the guarded fs tools) by their CANONICAL target,
+ * at TWO severities from ONE judge. `patterns` is the DENY set — deployment-supplied, no default list
+ * is shipped; `askPatterns` is the ASK set, judged the same way and consulted only where the deny set
+ * misses, so a path on both denies. Both empty = a no-op allow.
+ *
+ * @contract sensitive_paths.two_severities_one_judge — ONE canonicalizing judge answers both
+ * severities: a deny is a refusal no approver and no persisted allow rule can lift, an ask is one
+ * explicit look that either of them may clear. Lowering a path's severity here never lowers its REACH
+ * — both tiers see the real target (symlinks resolved, relative spellings resolved against the call's
+ * live cwd), which the synchronous write-protection TABLE deliberately does not.
  *
  * `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 verdicts it owns are narrow and certain: "the real target IS a
+ * guarded path → deny / ask". (A target it could not RESOLVE is the one fail-CLOSED arm, below.)
  */
 export declare function createSensitivePathPolicy(opts: {
     env: ExecutionEnv;
     /** `readonly` accepted so {@link RECOMMENDED_SENSITIVE_PATTERNS} can be passed as-is (widening, non-breaking). */
     patterns: readonly string[];
+    /** The ASK-severity set, same syntax and same judge as `patterns`, consulted only where the deny set
+     *  misses. ABSENT ⇒ {@link RECOMMENDED_SENSITIVE_ASK_PATTERNS}, so a deployment already wiring this
+     *  guard keeps its reach over those directories without a code change; `[]` = no ask tier. */
+    askPatterns?: readonly string[];
     rootPath?: string;
     /**
      * HRD-PRM-10 — the engine data root this deployment runs on. Default

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",
@@ -32,6 +50,7 @@ export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".bash_history",
     ".zsh_history",
 ];
+export const RECOMMENDED_SENSITIVE_ASK_PATTERNS = [".claude", ".sema"];
 const CASE_INSENSITIVE_FS = process.platform === "darwin" || process.platform === "win32";
 export function dataRootSpellings(explicit) {
     const raw = explicit ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent");
@@ -77,6 +96,7 @@ function matchSensitive(canonicalKey, compiled, aliasResolved) {
 }
 export function createSensitivePathPolicy(opts) {
     const compiled = compilePatterns(opts.patterns);
+    const compiledAsk = compilePatterns(opts.askPatterns ?? RECOMMENDED_SENSITIVE_ASK_PATTERNS);
     const dataRootPaths = dataRootSpellings(opts.dataRoot);
     const dataRootKeys = async (signal) => {
         const keys = [];
@@ -94,7 +114,7 @@ export function createSensitivePathPolicy(opts) {
     const guardedByName = opts.tools !== undefined ? new Set(opts.tools) : undefined;
     return {
         async check(req, signal) {
-            if (compiled.length === 0)
+            if (compiled.length === 0 && compiledAsk.length === 0)
                 return { action: "allow" };
             if (guardedByName !== undefined ? !guardedByName.has(req.toolName) : !isProtectedWrite(req))
                 return { action: "allow" };
@@ -129,6 +149,14 @@ export function createSensitivePathPolicy(opts) {
                     decisionReason: "safety",
                 };
             }
+            const askHit = matchSensitive(judged, compiledAsk, canon.aliasResolved === true);
+            if (askHit) {
+                return {
+                    action: "ask",
+                    message: `this write's real target resolves inside the guarded directory "${askHit}" — explicit approval required`,
+                    decisionReason: "safety",
+                };
+            }
             return { action: "allow" };
         },
     };