@sema-agent/core 7.17.7 → 7.19.0

package/dist/core/runner/skill-base-dir.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A skill's BASE DIRECTORY: the placeholder grammar its material may use to name its own root, the bounded
+ * substitution that resolves it, and the delivered-length measure the load gate budgets on.
+ *
+ * Split out of the skill tool because it is a different concern: the tool decides what a skill INVOKE
+ * returns, this decides how the caller's material names files on the machine the tools run on.
+ */
+/** The typed refusal a `SkillSpec.baseDir` outside its domain raises — one code, one sentence. */
+export declare const SKILL_BASE_DIR_INVALID_CODE = "config.skill_base_dir_invalid";
+/**
+ * The ONE screen of `SkillSpec.baseDir`: absent ⇒ no directory (nothing is substituted and no opening line is
+ * added); a NON-EMPTY string ⇒ itself; anything else ⇒ a loud refusal carrying {@link SKILL_BASE_DIR_INVALID_CODE}.
+ *
+ * Both rejected shapes were SILENT before, and each was silent in its own direction. `""` is not "no directory":
+ * it substitutes to nothing, so a body's `${SKILL_ROOT}/ref.md` is delivered as the filesystem-root path
+ * `/ref.md` and the opening line names no directory at all — a wrong answer where absence would have given the
+ * visible unresolved placeholder the seat's contract promises. A non-string makes the delivered LENGTH `NaN`,
+ * and `NaN <= limit` is false, so the load gate dropped the skill and reported "content is NaN chars" —
+ * a configuration typo reading as an over-limit body. Core still neither resolves nor reads the directory
+ * (the brain-outside rule); this screens the VALUE, not the path.
+ *
+ * It runs at the load gate ({@link substitutedSkillLength}, which spec assembly calls for every skill), so the
+ * substitution faces below are reached only with a value that already passed it.
+ */
+export declare function skillBaseDirOf(value: unknown): string | undefined;
+/**
+ * Substitute a skill's base directory for the root placeholders in ITS OWN MATERIAL.
+ *
+ * @contract skill.base_dir — with `SkillSpec.baseDir` set, a `Skill` result opens with the line
+ * `Base directory for this skill: <baseDir>` and every `${SKILL_ROOT}` / `${CLAUDE_PLUGIN_ROOT}` in the
+ * body AND in every attachment's content is replaced by that value; `files[].path` is then read relative to
+ * it. The substitution covers the CALLER'S material only — never the model-supplied `args` section, which is
+ * live input and is delivered as written. Core neither resolves nor reads the directory (the brain-outside
+ * rule that keeps `SkillSpec.files` inline); with `baseDir` absent no line is added, nothing is substituted,
+ * and the result is byte-identical to a pre-baseDir invoke.
+ */
+export declare function substituteSkillRoot(text: string, baseDir: string): string;
+/**
+ * Substitute under a CEILING, and report the size the full substitution would have had.
+ *
+ * Substitution is the one step here that can make text grow without bound: a placeholder is 13 or 21 chars and a real directory can be any length, so an
+ * attachment that is nothing but placeholders expands by a factor of the path's length. Building that string in order to measure it against the attachments
+ * cap — or worse, to discover it does not FIT and drop it — spends exactly the memory the cap exists to bound before the cap is consulted, and a big enough
+ * one exceeds the runtime's own string limit. So the length is counted as the loop walks, nothing is materialized past `maxChars`, and the caller budgets on
+ * `totalChars` while rendering only what fits.
+ */
+/** The DELIVERED length of a body once its root placeholders resolve — counted, never materialized, so the load gate measures what the model will actually
+ *  receive rather than what the caller typed. Equal to `text.length` when no directory is stated, and the one place the seat's value is SCREENED
+ *  ({@link skillBaseDirOf}) — the gate that budgets on this number is the first reader of every skill on every leg. */
+export declare function substitutedSkillLength(text: string, baseDir: unknown): number;
+export declare function substituteSkillRootBounded(text: string, baseDir: string, maxChars: number): {
+    text: string;
+    totalChars: number;
+};

package/dist/core/runner/skill-base-dir.js

@@ -0,0 +1,42 @@
+const SKILL_ROOT_PLACEHOLDERS = /\$\{(?:SKILL_ROOT|CLAUDE_PLUGIN_ROOT)\}/g;
+export const SKILL_BASE_DIR_INVALID_CODE = "config.skill_base_dir_invalid";
+export function skillBaseDirOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "string" && value !== "")
+        return value;
+    const e = new Error(`SkillSpec.baseDir must be a non-empty string naming its own directory (got ${value === "" ? '""' : typeof value}) — ` +
+        `omit the key where no directory is stated; an empty one resolves the body's \${SKILL_ROOT} placeholders to nothing.`);
+    e.code = SKILL_BASE_DIR_INVALID_CODE;
+    throw e;
+}
+export function substituteSkillRoot(text, baseDir) {
+    return text.replace(SKILL_ROOT_PLACEHOLDERS, () => baseDir);
+}
+export function substitutedSkillLength(text, baseDir) {
+    const dir = skillBaseDirOf(baseDir);
+    if (dir === undefined)
+        return text.length;
+    return substituteSkillRootBounded(text, dir, 0).totalChars;
+}
+export function substituteSkillRootBounded(text, baseDir, maxChars) {
+    const parts = [];
+    let totalChars = 0;
+    let built = 0;
+    const push = (piece) => {
+        totalChars += piece.length;
+        if (built >= maxChars)
+            return;
+        const kept = piece.length > maxChars - built ? piece.slice(0, maxChars - built) : piece;
+        parts.push(kept);
+        built += kept.length;
+    };
+    let last = 0;
+    for (const m of text.matchAll(SKILL_ROOT_PLACEHOLDERS)) {
+        push(text.slice(last, m.index));
+        push(baseDir);
+        last = m.index + m[0].length;
+    }
+    push(text.slice(last));
+    return { text: parts.join(""), totalChars };
+}

package/dist/core/runner/synthetic-tools.d.ts

@@ -1,6 +1,7 @@
 import { type TSchema } from "typebox";
 import type { AgentTool } from "../../internal/harness-types.js";
 import type { SkillManifest } from "../types.js";
+import { type ResolvedSkillListingBudget } from "../skill-listing-budget.js";
 import type { ActiveSkillScope } from "./active-skill-scope.js";
 /** Reserved name of the injected structured-output tool (CC 2.1.187 `StructuredOutput`; batch-A rename — old
  *  "submit_output" is canonicalized for pre-rename durable state). */
@@ -52,44 +53,34 @@ export interface ReportedFinding {
 export declare function createReportFindingsTool(): AgentTool;
 /** Reserved name of the injected skill-loading tool (present only when `spec.skills` is non-empty). */
 export declare const SKILL_TOOL_NAME = "Skill";
-/** Per-skill LOAD gate on `SkillSpec.content` (CC 2.1.207 parity: CC's only size door at invoke
- *  time is a 1MB file-load gate — an over-limit skill is REJECTED WHOLE, never truncated; the
- *  invoked body itself enters context untruncated). Sema skills are spec-supplied content, so the
- *  equivalent gate sits at spec assembly (prepare-task): an oversized skill is excluded from both
- *  the disclosure block and the tool, with an operator-visible config error. The compaction-time
- *  retention caps live in the engine's compaction module — a different door, deliberately. */
+/** Per-skill LOAD gate on `SkillSpec.content` (CC 2.1.207 parity: CC's only invoke-time size door is a 1MB file-load gate — an over-limit skill is REJECTED
+ *  WHOLE, never truncated, and the invoked body enters context untruncated). Sema skills are spec-supplied, so the equivalent gate sits at spec assembly:
+ *  an oversized skill is excluded from the disclosure block and the tool, with an operator-visible config error. The compaction-time retention caps are a
+ *  different door, deliberately. */
 export declare const SKILL_CONTENT_MAX_CHARS: number;
-/** Total listing-block cap in UTF-8 BYTES — [c209-C] R2 C4①: the old 8000-CHAR cap measured a
- *  different coordinate than the bundle's `ATTACHMENT_BYTE_CAP` (8192 UTF-8 bytes) and counted only
- *  the description lines (fence framing + name-only tail rode free), so a near-cap frame could
- *  exceed the bundle cap, get clip-mangled every boundary, never pass the intact-survival commit
- *  predicate, and REPLAY FOREVER. The cap is now enforced byte-exact over the WHOLE rendered block
- *  (fences, headers, markers, joiners included), so `buildSkillsBlock` output always fits the
- *  bundle cap solo and an intact commit is always reachable. MUST stay ≤ ATTACHMENT_BYTE_CAP
- *  (turn-attachments.ts; not imported here — that module imports this one — pinned by test instead). */
-export declare const SKILLS_BLOCK_MAX_BYTES = 8000;
-/** Total per-invoke cap for a skill's inlined attachments (`SkillSpec.files`) — an ATTACHMENT-face
- *  budget, distinct from the (gone) body truncation door: the body itself is delivered untruncated
- *  at invoke time (CC parity), while attachments are reference material riding along — bounded and
- *  truncation-disclosed. */
+/** The listing's budget vocabulary lives in `core/skill-listing-budget.ts` (the seat reader that lowers
+ *  the two `TaskSpec` knobs to these numbers); re-exported here because this module is where every
+ *  existing consumer of the cap imports it from, and the ceiling's structural reason is a property of
+ *  the delivery lane rather than of the renderer. */
+export { SKILLS_BLOCK_MAX_BYTES } from "../skill-listing-budget.js";
+/** Total per-invoke cap for a skill's inlined attachments (`SkillSpec.files`) — an ATTACHMENT-face budget, distinct from the (gone) body truncation door:
+ *  the body is delivered untruncated at invoke time (CC parity), while attachments ride along bounded and truncation-disclosed. */
 export declare const SKILL_ATTACHMENTS_MAX_CHARS = 50000;
-/** Per-attachment cap on the PATH rendered in its `###` header — a single pathological path must not
- *  eat the attachments budget on its own. Overflow is truncated with an ellipsis. */
+/** Per-attachment cap on the PATH rendered in its `###` header — one pathological path must not eat the budget. Overflow truncates with an ellipsis. */
 export declare const SKILL_ATTACHMENT_PATH_MAX_CHARS = 512;
 interface SkillLike {
     name: string;
     description: string;
     content: string;
-    /** Optional Gate-3 runtime capability manifest — carried through so a successful
-     *  `skill` load can push its scope frame. Skills without one stay unscoped (backward-compatible). */
+    /** Optional Gate-3 runtime capability manifest — carried through so a successful `skill` load can push its scope frame; skills without one stay unscoped. */
     manifest?: SkillManifest;
-    /** Optional attachments (SkillSpec.files): disclosed as paths in the block, delivered inline on
-     *  invoke under {@link SKILL_ATTACHMENTS_MAX_CHARS}. Same caller-trusted contract as `content`
-     *  (see the module note above) — core never writes them to disk (deployment's half). */
+    /** Optional attachments (SkillSpec.files): paths in the block, delivered inline on invoke under {@link SKILL_ATTACHMENTS_MAX_CHARS}. Same caller-trusted
+     *  contract as `content` — core never writes them to disk (deployment's half). */
     files?: Array<{
         path: string;
         content: string;
     }>;
+    /** Optional base directory (SkillSpec.baseDir) — see `@contract skill.base_dir`. Absent ⇒ byte-identical result. */ baseDir?: string;
 }
 /** [c209-C] The metadata slice of a skill the LISTING faces consume (disclosure block + the
  *  skills_listing turn attachment): name, description, attachment paths — never the body. The
@@ -116,8 +107,11 @@ export interface SkillListingEntry {
      *  keep their descriptions"). Absent ⇒ the entry's array index is used, i.e. the prior behavior. */
     declaredRank?: number;
 }
-/** Dedupe by name (first occurrence wins) and sort by name — one deterministic list shared by the
- *  disclosure block and the tool, so what the prompt promises is exactly what the tool serves. */
+/** Dedupe by name (first occurrence wins) and sort by name — one deterministic list shared by the disclosure block
+ *  and the tool, so what the prompt promises is exactly what the tool serves. Each field is READ ONCE, BY NAME, and
+ *  both consumers see the copy: the gate screens this list while the invoke substitutes from it, so a `get baseDir()`
+ *  answering those two reads differently passed a screen that measured a value the model never received — and a rest
+ *  copy would silently drop an INHERITED or non-enumerable `manifest`, i.e. widen a skill's capability restriction. */
 export declare function normalizeSkills(skills: SkillLike[] | undefined): SkillLike[];
 /** [c209-C] The skills listing's lead line — single-sourced so the run loop's durable-resume
  *  transcript probe (MED-3② skills arm, runtask) matches EXACTLY what the initial frame carries
@@ -126,31 +120,73 @@ export declare const SKILLS_LISTING_PROBE_HEADER = "The following skills are ava
 /** [c209-C] One skill's disclosure line — `- name: description[(files 尾缀)]` with the per-skill
  *  description cap. Single-sourced so the skills_listing DELTA frame (turn-attachments) renders adds
  *  with byte-identical line shape to the initial `<skills>` block. */
-export declare function skillListingLine(s: SkillListingEntry): string;
+export declare function skillListingLine(s: SkillListingEntry, descMaxChars?: number): string;
+/** What one {@link renderSkillsBlock} call produced: the block, and which skills the budget degraded. */
+export interface SkillsBlockRender {
+    /** The rendered block — what {@link buildSkillsBlock} returns. */
+    text: string;
+    /** Skills listed WITHOUT their description (tier B's unspent candidates, or every listed name under
+     *  tier C), in display order. Raw names: this is host-facing structured data, not prompt text. */
+    nameOnly: readonly string[];
+    /** Skills the block could not list at all (tier C's overflow tail). The `Skill` tool still serves them. */
+    dropped: readonly string[];
+}
+/** The text-only face of {@link renderSkillsBlock} — the `<skills>` BLOCK's face, not the listing
+ *  family's: the drift frame renders its own arms through the shared tier engine
+ *  ({@link renderSkillLinesWithin}), which is where "one ruler for every frame" lives. */
+export declare function buildSkillsBlock(skills: ReadonlyArray<SkillListingEntry>, budget?: ResolvedSkillListingBudget): string | undefined;
 /** Render the `<skills>` disclosure block (metadata only — bodies stay behind the tool).
  *  [c209-C] REVERSAL: no longer composed into the stable system prompt — this is now the RENDERER for
  *  the `skills_listing` initial frame (first-user-turn reminder / boundary re-announce), so the
  *  cached prefix carries zero skill bytes (design/C §2.3; CC 209 classic ships the same listing as a
  *  first-turn reminder; Q6: 8KB cap ≈ CC's observed 5.9KB listing).
  *
- *  [c209-C] R2 C4① — the cap is BYTE-EXACT over the whole rendered block (see
- *  {@link SKILLS_BLOCK_MAX_BYTES}): three honesty tiers, each chosen with the LATER tiers' fixed
- *  overhead (cap marker / name-only tail / overflow count line) already reserved so the final
- *  render can never blow the budget it was sized against —
- *    A. everything fits → every skill gets its full `- name: description` line (byte-identical to
- *       the pre-C4 render for every block that was legal under the old cap);
- *    B. (CC 220 `sbs` @317547-317586) — reserve the cap marker + EVERY skill's name-only line
- *       first, then spend the remaining slack on descriptions in PRIORITY order
- *       ({@link SkillListingEntry.declaredRank}), admitting each description whose incremental cost
- *       still fits and skipping (not stopping at) the ones that do not. Every skill stays listed;
- *       the ones that lose their description are the low-priority ones, not the alphabetically late
- *       ones. This replaces the prior "longest full-line PREFIX" cut, which had two defects the
- *       anchor does not: the surviving set was decided by name sort order (a skill named `zip-deploy`
- *       lost its description to `aardvark-lint` for no reason connected to either skill), and one
- *       oversized description truncated the block at itself instead of being skipped over;
- *    C. even all-name-only overflows (pathological name census) → list what fits and close with an
- *       honest `(… +N more skills …)` count line — the tool still serves all of them. */
-export declare function buildSkillsBlock(skills: ReadonlyArray<SkillListingEntry>): string | undefined;
+ *  The fence and its four header lines are this lane's frame; the budget arithmetic and the three
+ *  degradation tiers belong to {@link renderSkillLinesWithin}, which the drift frame renders through
+ *  as well. {@link buildSkillsBlock} is the text-only face; this one additionally reports what the
+ *  budget cost, for the disclosure lane. */
+export declare function renderSkillsBlock(skills: ReadonlyArray<SkillListingEntry>, budget?: ResolvedSkillListingBudget): SkillsBlockRender | undefined;
+/**
+ * The three honesty tiers over ONE set of skills, measured byte-exact inside a caller-supplied FRAME —
+ * the engine both {@link renderSkillsBlock} and the drift frame's ADD arm render through, so the
+ * initial `<skills>` block and a later "new skills are now available" announcement degrade by the same
+ * rules against the same number. A lane that folded by its own rules (or by none) renders a body the
+ * bundle cap CLIPS, and a clipped body can never equal the intact-survival re-render, so the
+ * announcement replays at every boundary for the life of the task — the failure
+ * `@contract skills.listing_budget_ceiling` names, on whichever lane skipped the measurement.
+ *
+ * `frame` renders the body lines into the shape its lane carries; its fixed cost is priced once, by
+ * rendering it empty, so the tiers below decide against the bytes that actually ship.
+ *
+ * [c209-C] R2 C4① — the cap is BYTE-EXACT over the whole rendered frame (see
+ * {@link SKILLS_BLOCK_MAX_BYTES}): three honesty tiers, each chosen with the LATER tiers' fixed
+ * overhead (cap marker / name-only tail / overflow count line) already reserved so the final
+ * render can never blow the budget it was sized against —
+ *   A. everything fits → every skill gets its full `- name: description` line (byte-identical to
+ *      the pre-C4 render for every block that was legal under the old cap);
+ *   B. (CC 220 `sbs` @317547-317586) — reserve the cap marker + EVERY skill's name-only line
+ *      first, then spend the remaining slack on descriptions in PRIORITY order
+ *      ({@link SkillListingEntry.declaredRank}), admitting each description whose incremental cost
+ *      still fits and skipping (not stopping at) the ones that do not. Every skill stays listed;
+ *      the ones that lose their description are the low-priority ones, not the alphabetically late
+ *      ones. This replaces the prior "longest full-line PREFIX" cut, which had two defects the
+ *      anchor does not: the surviving set was decided by name sort order (a skill named `zip-deploy`
+ *      lost its description to `aardvark-lint` for no reason connected to either skill), and one
+ *      oversized description truncated the block at itself instead of being skipped over;
+ *   C. even all-name-only overflows (pathological name census) → list what fits and close with an
+ *      honest `(… +N more skills …)` count line — the tool still serves all of them.
+ *
+ * Pure: the same entries, budget and frame always render the same bytes, which is what the
+ * prompt-prefix stability contract requires of the listing frames.
+ */
+export declare function renderSkillLinesWithin(skills: ReadonlyArray<SkillListingEntry>, opts: {
+    /** The whole frame's byte budget. Re-clamped to {@link SKILLS_BLOCK_MAX_BYTES} here, not only in
+     *  the seat reader: this renderer is reachable from every listing lane, and the ceiling invariant
+     *  has to hold for a caller that computed its own number. */
+    blockMaxBytes: number;
+    descMaxChars: number;
+    frame: (lines: readonly string[]) => string;
+}): SkillsBlockRender | undefined;
 /**
  * The injected `skill` tool: returns a skill's full body as a tool result.
  *
@@ -167,4 +203,3 @@ export declare function buildSkillsBlock(skills: ReadonlyArray<SkillListingEntry
  * widening, so it stays safe-by-construction.
  */
 export declare function createSkillTool(skills: SkillLike[], scope?: ActiveSkillScope): AgentTool;
-export {};

package/dist/core/runner/synthetic-tools.js

@@ -1,7 +1,9 @@
 import { Type } from "typebox";
 import { defineTool } from "../tools.js";
 import { sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
+import { SKILLS_BLOCK_MAX_BYTES as SKILL_LISTING_CEILING_BYTES, SKILL_LISTING_DESC_MAX_CHARS_DEFAULT, } from "../skill-listing-budget.js";
 import { toolFace } from "../tool-catalog-entries.js";
+import { substituteSkillRoot, substituteSkillRootBounded } from "./skill-base-dir.js";
 export const OUTPUT_TOOL_NAME = "StructuredOutput";
 export const REPORT_BLOCKED_TOOL_NAME = "ReportBlocked";
 export const REPORT_FINDINGS_TOOL_NAME = "ReportFindings";
@@ -84,8 +86,7 @@ export function createReportFindingsTool() {
 }
 export const SKILL_TOOL_NAME = "Skill";
 export const SKILL_CONTENT_MAX_CHARS = 1024 * 1024;
-const SKILL_DESC_MAX_CHARS = 1_536;
-export const SKILLS_BLOCK_MAX_BYTES = 8_000;
+export { SKILLS_BLOCK_MAX_BYTES } from "../skill-listing-budget.js";
 export const SKILL_ATTACHMENTS_MAX_CHARS = 50_000;
 export const SKILL_ATTACHMENT_PATH_MAX_CHARS = 512;
 const SKILL_FILES_LIST_MAX_CHARS = 200;
@@ -112,24 +113,26 @@ export function normalizeSkills(skills) {
     for (const s of skills ?? []) {
         if (!seen.has(s.name)) {
             seen.add(s.name);
-            out.push(s);
+            const { name, description, content, manifest, files, baseDir, ...rest } = s;
+            void rest;
+            out.push({ name, description, content, ...(manifest !== undefined ? { manifest } : {}), ...(files !== undefined ? { files } : {}), ...(baseDir !== undefined ? { baseDir } : {}) });
         }
     }
     return out.toSorted((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 export const SKILLS_LISTING_PROBE_HEADER = "The following skills are available for this task.";
-export function skillListingLine(s) {
-    const desc = s.description.length > SKILL_DESC_MAX_CHARS
-        ? `${s.description.slice(0, SKILL_DESC_MAX_CHARS - 1)}…`
-        : s.description;
+export function skillListingLine(s, descMaxChars = SKILL_LISTING_DESC_MAX_CHARS_DEFAULT) {
+    const desc = s.description.length > descMaxChars ? `${s.description.slice(0, descMaxChars - 1)}…` : s.description;
     const safe = (t) => sanitizeUntrustedText(t, SHELLED_BODY_ENVELOPE_TAGS);
     return `- ${safe(s.name)}: ${safe(desc)}${safe(skillFilesSuffix(s.files))}`;
 }
 const SKILLS_BLOCK_CAP_MARKER = "(block size cap reached — lower-priority skills are listed name-only; descriptions via the tool)";
-export function buildSkillsBlock(skills) {
+export function buildSkillsBlock(skills, budget) {
+    return renderSkillsBlock(skills, budget)?.text;
+}
+export function renderSkillsBlock(skills, budget) {
     if (skills.length === 0)
         return undefined;
-    const bytes = (s) => Buffer.byteLength(s, "utf8");
     const headerLines = [
         "<skills>",
         `${SKILLS_LISTING_PROBE_HEADER} A skill is a named package of instructions;`,
@@ -137,18 +140,34 @@ export function buildSkillsBlock(skills) {
         `instructions by calling the \`${SKILL_TOOL_NAME}\` tool with \`skill: "<name>"\` (plus optional \`args\`).`,
         "",
     ];
-    const render = (lines) => [...headerLines, ...lines, "</skills>"].join("\n");
+    return renderSkillLinesWithin(skills, {
+        blockMaxBytes: budget?.blockMaxBytes ?? SKILL_LISTING_CEILING_BYTES,
+        descMaxChars: budget?.descMaxChars ?? SKILL_LISTING_DESC_MAX_CHARS_DEFAULT,
+        frame: (lines) => [...headerLines, ...lines, "</skills>"].join("\n"),
+    });
+}
+export function renderSkillLinesWithin(skills, opts) {
+    if (skills.length === 0)
+        return undefined;
+    const blockMaxBytes = Math.min(opts.blockMaxBytes, SKILL_LISTING_CEILING_BYTES);
+    const descMaxChars = opts.descMaxChars;
+    const bytes = (s) => Buffer.byteLength(s, "utf8");
+    const render = opts.frame;
     const lineCost = (l) => bytes(l) + 1;
-    const budget = SKILLS_BLOCK_MAX_BYTES - bytes(render([]));
-    const fullLines = skills.map((s) => skillListingLine(s));
-    const nameLines = skills.map((s) => `- ${sanitizeUntrustedText(s.name, SHELLED_BODY_ENVELOPE_TAGS)}`);
+    const bodyBudget = blockMaxBytes - bytes(render([]));
+    const fullLines = skills.map((s) => skillListingLine(s, descMaxChars));
     const fullTotal = fullLines.reduce((acc, l) => acc + lineCost(l), 0);
-    if (fullTotal <= budget)
-        return render(fullLines);
+    if (fullTotal <= bodyBudget)
+        return { text: render(fullLines), nameOnly: [], dropped: [] };
+    const nameLines = skills.map((s) => `- ${sanitizeUntrustedText(s.name, SHELLED_BODY_ENVELOPE_TAGS)}`);
+    const namePrefix = new Array(nameLines.length + 1);
+    namePrefix[0] = 0;
+    for (let i = 0; i < nameLines.length; i++)
+        namePrefix[i + 1] = namePrefix[i] + lineCost(nameLines[i]);
     const markerCost = lineCost(SKILLS_BLOCK_CAP_MARKER);
-    const floorCost = markerCost + nameLines.reduce((acc, l) => acc + lineCost(l), 0);
-    if (floorCost <= budget) {
-        let slack = budget - floorCost;
+    const floorCost = markerCost + namePrefix[nameLines.length];
+    if (floorCost <= bodyBudget) {
+        let slack = bodyBudget - floorCost;
         const byPriority = skills
             .map((s, i) => ({ i, rank: s.declaredRank ?? i }))
             .toSorted((a, b) => a.rank - b.rank || a.i - b.i);
@@ -160,15 +179,28 @@ export function buildSkillsBlock(skills) {
                 slack -= delta;
             }
         }
-        return render([SKILLS_BLOCK_CAP_MARKER, ...skills.map((_s, i) => (withDescription.has(i) ? fullLines[i] : nameLines[i]))]);
+        return {
+            text: render([SKILLS_BLOCK_CAP_MARKER, ...skills.map((_s, i) => (withDescription.has(i) ? fullLines[i] : nameLines[i]))]),
+            nameOnly: skills.filter((_s, i) => !withDescription.has(i)).map((s) => s.name),
+            dropped: [],
+        };
     }
     for (let m = skills.length - 1; m >= 0; m--) {
         const overflowLine = `(… +${skills.length - m} more skills not listed — the ${SKILL_TOOL_NAME} tool serves them all)`;
-        const cost = markerCost + nameLines.slice(0, m).reduce((acc, l) => acc + lineCost(l), 0) + lineCost(overflowLine);
-        if (cost <= budget)
-            return render([SKILLS_BLOCK_CAP_MARKER, ...nameLines.slice(0, m), overflowLine]);
+        const cost = markerCost + namePrefix[m] + lineCost(overflowLine);
+        if (cost <= bodyBudget) {
+            return {
+                text: render([SKILLS_BLOCK_CAP_MARKER, ...nameLines.slice(0, m), overflowLine]),
+                nameOnly: skills.slice(0, m).map((s) => s.name),
+                dropped: skills.slice(m).map((s) => s.name),
+            };
+        }
     }
-    return render([SKILLS_BLOCK_CAP_MARKER, `(… +${skills.length} more skills not listed — the ${SKILL_TOOL_NAME} tool serves them all)`]);
+    return {
+        text: render([SKILLS_BLOCK_CAP_MARKER, `(… +${skills.length} more skills not listed — the ${SKILL_TOOL_NAME} tool serves them all)`]),
+        nameOnly: [],
+        dropped: skills.map((s) => s.name),
+    };
 }
 export function createSkillTool(skills, scope) {
     const byName = new Map(skills.map((s) => [s.name, s]));
@@ -202,7 +234,8 @@ export function createSkillTool(skills, scope) {
             if (scope && skill.manifest) {
                 scope.push({ kind: "manifest", manifest: skill.manifest });
             }
-            let body = skill.content;
+            const baseDir = skill.baseDir;
+            let body = baseDir !== undefined ? substituteSkillRoot(skill.content, baseDir) : skill.content;
             if (skill.files !== undefined && skill.files.length > 0) {
                 const SEPARATOR_CHARS = 2;
                 const SECTION_HEADER = "## Attachments";
@@ -217,27 +250,30 @@ export function createSkillTool(skills, scope) {
                         : f.path;
                     const header = `### ${path}\n`;
                     const renderedOverhead = header.length + SEPARATOR_CHARS;
+                    const expanded = baseDir !== undefined ? substituteSkillRootBounded(f.content, baseDir, Math.max(0, budget)) : { text: f.content, totalChars: f.content.length };
+                    const content = expanded.text;
+                    const contentChars = expanded.totalChars;
                     if (budget <= renderedOverhead) {
                         omittedCount += 1;
-                        omittedChars += header.length + f.content.length;
+                        omittedChars += header.length + contentChars;
                         continue;
                     }
                     const contentBudget = budget - renderedOverhead;
-                    if (f.content.length > contentBudget) {
-                        const markerFor = (shown) => `\n[attachment truncated: showing the first ${shown} of ${f.content.length} chars — attachments cap reached]`;
+                    if (contentChars > contentBudget) {
+                        const markerFor = (shown) => `\n[attachment truncated: showing the first ${shown} of ${contentChars} chars — attachments cap reached]`;
                         const shown = contentBudget - markerFor(contentBudget).length;
                         if (shown <= 0) {
                             omittedCount += 1;
-                            omittedChars += header.length + f.content.length;
+                            omittedChars += header.length + contentChars;
                             budget = 0;
                             continue;
                         }
-                        sections.push(`${header}${f.content.slice(0, shown)}${markerFor(shown)}`);
+                        sections.push(`${header}${content.slice(0, shown)}${markerFor(shown)}`);
                         budget = 0;
                         continue;
                     }
-                    sections.push(`${header}${f.content}`);
-                    budget -= renderedOverhead + f.content.length;
+                    sections.push(`${header}${content}`);
+                    budget -= renderedOverhead + contentChars;
                 }
                 if (omittedCount > 0) {
                     sections.push(`[+${omittedCount} more attachment(s) omitted (${omittedChars} chars) — the ${SKILL_ATTACHMENTS_MAX_CHARS}-char attachments cap is exhausted]`);
@@ -245,7 +281,8 @@ export function createSkillTool(skills, scope) {
                 body = `${body}\n\n${sections.join("\n\n")}`;
             }
             const skillArgs = typeof a.args === "string" && a.args.length > 0 ? a.args.slice(0, 10_000) : undefined;
-            return skillArgs ? `${body}\n\n## Input\n${skillArgs}` : body;
+            const delivered = skillArgs ? `${body}\n\n## Input\n${skillArgs}` : body;
+            return baseDir !== undefined ? `Base directory for this skill: ${baseDir}\n\n${delivered}` : delivered;
         },
     });
 }

package/dist/core/runner/tool-defer-gate.d.ts

@@ -1,15 +1,16 @@
 import type { Model } from "../../internal/llm.js";
 import type { ToolSpec } from "../types.js";
 import type { ToolFingerprintInput } from "../cache-break-detector.js";
+import { type ResolvedToolSearch, type ToolSearchSetting } from "../tool-search-setting.js";
 /**
  * The deferral GATE: which mounted tool names ship as placeholders on a request. Pure
  * registry logic over names and sizes — no harness, no I/O. `tool-disclosure.ts` owns the placeholder
  * and ToolSearch mechanics that act on the set this module decides; `prepare-defer-classify.ts` is the
  * phase that assembles the inputs from the mounted face.
  */
-/** The deferral gate's threshold: the engine's candidate set is deferred when its inlined size reaches
- *  this fraction of the model's context window (that set measured, never the rest of the face). */
-export declare const DEFER_THRESHOLD_FRACTION = 0.1;
+/** The deferral gate's DEFAULT threshold: with no `toolSearch` seat, the candidate set defers when its inlined size reaches this fraction of the model's
+ *  context window (that set measured, never the rest of the face). Derived from the seat's own default percent — one default, two units. */
+export declare const DEFER_THRESHOLD_FRACTION: number;
 /** The typed refusal a `deferMode` outside its declared domain (`"auto"` or absent) raises at the classifier —
  *  a bad value never selects an arm silently. */
 export declare const DEFER_MODE_INVALID_CODE = "config.defer_mode_invalid";
@@ -24,10 +25,13 @@ export interface DeferralGate {
     gated: Set<string>;
     /** Σ inlined chars (name + description + serialized schema) over `gated` — the bytes the gate could reclaim. */
     gatedChars: number;
-    /** `floor(contextTokens × fraction) × CHARS_PER_TOKEN`; the char reading of the token threshold. */
+    /** `floor(contextTokens × fraction) × CHARS_PER_TOKEN`; the char reading of the token threshold. `0` under `toolSearch: true` and `Infinity` under
+     *  `false` — the two boolean arms ARE this number. */
     thresholdChars: number;
     /** Whether `gated` is deferred on this request: `gatedChars ≥ thresholdChars`. */
     open: boolean;
+    /** The lowered seat this verdict was measured under ({@link ToolSearchSetting}); always present, since an absent seat resolves to the default `auto`. */
+    toolSearch: ResolvedToolSearch;
 }
 /**
  * Deferral has TWO rules, and only two.
@@ -44,11 +48,12 @@ export interface DeferralGate {
  *    "auto"` WIDENS the candidate set to every caller spec — undeclared caller tools included — and nothing
  *    else: it is not a second gate, and engine built-ins the deployment did not name are candidates under no
  *    setting. The gate decides the set all or nothing: deferred iff `gatedChars ≥ thresholdChars`, where the
- *    threshold is {@link DEFER_THRESHOLD_FRACTION} of the model's context window (`contextTokens ??
- *    contextWindow`, in chars at {@link CHARS_PER_TOKEN}). The measure is the candidate set ONLY — the bytes
- *    the gate could reclaim — never the caller's list, the pins, or non-candidates: a request whose weight
- *    sits elsewhere gains nothing from a ToolSearch round-trip, so nothing about it argues for one. A window
- *    of zero reads as a zero threshold (every candidate byte is over budget), so the candidates defer.
+ *    threshold is the DEPLOYMENT'S FRACTION of the model's context window (`contextTokens ?? contextWindow`,
+ *    in chars at {@link CHARS_PER_TOKEN}) — {@link ToolSearchSetting} lowered by {@link resolveToolSearch},
+ *    which is {@link DEFER_THRESHOLD_FRACTION} when no seat is wired. The measure is the candidate set ONLY —
+ *    the bytes the gate could reclaim — never the caller's list, the pins, or non-candidates: a request whose
+ *    weight sits elsewhere gains nothing from a ToolSearch round-trip, so nothing about it argues for one. A
+ *    window of zero reads as a zero threshold (every candidate byte is over budget), so the candidates defer.
  *
  * Invariants: `explicit ∩ gated = ∅`; `deferred = explicit ∪ (open ? gated : ∅)`; a pinned name is in no
  * list; the same inputs always yield the same verdict (a pure function of the request).
@@ -65,6 +70,9 @@ export declare function deferralGate(opts: {
     fullTools: ReadonlyArray<ToolFingerprintInput>;
     /** `"auto"` widens the candidate set to every caller spec (see above). Any other value refuses. */
     deferMode?: "auto";
+    /** The deployment's gate policy for rule ② ({@link ToolSearchSetting}); absent ⇒ the default `auto` at
+     *  {@link TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT}, byte-for-byte the prior behavior. */
+    toolSearch?: ToolSearchSetting;
     model: Model;
     /** Rule ① — `TaskSpec.deferTools`: ALREADY-MOUNTED wire names (built-ins included; `ToolSpec.defer`
      *  only reaches caller specs) the caller defers on every request. Caller pre-filters to mounted names. */
@@ -84,3 +92,8 @@ export declare function deferralGate(opts: {
  * gate; the `TaskSpec` / `RunnerDeps` JSDoc points here.
  */
 export declare function classifyDeferred(opts: Parameters<typeof deferralGate>[0]): Set<string>;
+/** The SAME fold, with the verdict it folded — a disclosure that reports the policy must read the one the gate measured under, never a later re-resolution. */
+export declare function classifyDeferredWithGate(opts: Parameters<typeof deferralGate>[0]): {
+    deferred: Set<string>;
+    gate: DeferralGate;
+};

package/dist/core/runner/tool-defer-gate.js

@@ -1,5 +1,6 @@
 import { DEFAULT_CHARS_PER_TOKEN } from "../../internal/harness.js";
-export const DEFER_THRESHOLD_FRACTION = 0.1;
+import { TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT, describeRejectedValue, resolveToolSearch } from "../tool-search-setting.js";
+export const DEFER_THRESHOLD_FRACTION = TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT / 100;
 const CHARS_PER_TOKEN = DEFAULT_CHARS_PER_TOKEN;
 function inlinedChars(t) {
     let schema = "";
@@ -14,10 +15,11 @@ function inlinedChars(t) {
 export const DEFER_MODE_INVALID_CODE = "config.defer_mode_invalid";
 export function deferralGate(opts) {
     if (opts.deferMode !== undefined && opts.deferMode !== "auto") {
-        const e = new Error(`RunnerDeps.deferMode: invalid value ${JSON.stringify(opts.deferMode)} — expected "auto" or omitted; a bad value refuses loudly, nothing falls back to a default.`);
+        const e = new Error(`RunnerDeps.deferMode: invalid value ${describeRejectedValue(opts.deferMode)} — expected "auto" or omitted; a bad value refuses loudly, nothing falls back to a default.`);
         e.code = DEFER_MODE_INVALID_CODE;
         throw e;
     }
+    const toolSearch = resolveToolSearch(opts.toolSearch);
     const pinned = new Set(opts.alwaysLoadNames ?? []);
     for (const s of opts.specs) {
         if (s.alwaysLoad === true)
@@ -44,14 +46,22 @@ export function deferralGate(opts) {
         if (gated.has(t.name))
             gatedChars += inlinedChars(t);
     const windowTokens = Math.max(0, opts.model.contextTokens ?? opts.model.contextWindow ?? 0);
-    const thresholdChars = Math.floor(windowTokens * DEFER_THRESHOLD_FRACTION) * CHARS_PER_TOKEN;
-    return { explicit, gated, gatedChars, thresholdChars, open: gatedChars >= thresholdChars };
+    const thresholdTokens = windowTokens * toolSearch.fraction;
+    const thresholdChars = Number.isFinite(thresholdTokens)
+        ? Math.floor(thresholdTokens) * CHARS_PER_TOKEN
+        : toolSearch.fraction === 0
+            ? 0
+            : Number.POSITIVE_INFINITY;
+    return { explicit, gated, gatedChars, thresholdChars, open: gatedChars >= thresholdChars, toolSearch };
 }
 export function classifyDeferred(opts) {
+    return classifyDeferredWithGate(opts).deferred;
+}
+export function classifyDeferredWithGate(opts) {
     const gate = deferralGate(opts);
     const deferred = new Set(gate.explicit);
     if (gate.open)
         for (const n of gate.gated)
             deferred.add(n);
-    return deferred;
+    return { deferred, gate };
 }

package/dist/core/runner/tool-disclosure.d.ts

@@ -247,6 +247,11 @@ export declare function createToolSearchTool(opts: {
      */
     isMounted?: (name: string) => boolean;
     serializeActivation?: <T>(section: () => Promise<T>) => Promise<T>;
+    /** Called at the TAIL of this lane's activation section, after the rollback window has closed — the one point at which the shared active set is committed
+     *  for this call. The disclosure census rides it, because a publisher reading that set from OUTSIDE the section (an MCP refresh's rematerialize, which runs
+     *  unserialized and after an await) can observe a name a racing activation staged and then rolled back, and announce an activation that never happened.
+     *  Absent ⇒ nothing is published. */
+    onActivationCommitted?: () => void;
     /** Resolve a deferred name's REAL declared
      *  parameter schema, read from the live roster at call time. Presence switches this face to the
      *  static posture: activation never swaps the placeholder in the tools block, so the result text

package/dist/core/runner/tool-disclosure.js

@@ -336,6 +336,8 @@ export function createToolSearchTool(opts) {
                         throw e;
                     }
                 }
+                if (newly.length > 0)
+                    opts.onActivationCommitted?.();
                 return { newly, ride: newly.length > 0 ? listingRide?.(newly) : undefined };
             });
             const { newly, ride } = await section;