@sema-agent/core 7.17.6 → 7.18.0

package/dist/core/runner/runtask.js

@@ -49,6 +49,7 @@ import { runAttachmentSeats } from "./run-attachment-seats.js";
 import { runToolMountFacts } from "./run-tool-mount-facts.js";
 import { runReasoningSeat } from "./run-reasoning-seat.js";
 import { runClockAndContent } from "./run-clock-and-content.js";
+import { createToolProgressLane } from "./tool-progress-lane.js";
 import { runBrainSinks } from "./run-brain-sinks.js";
 import { runCompactionMachinery } from "./run-compaction-machinery.js";
 import { runStopAndFinalVerify } from "./run-stop-and-final-verify.js";
@@ -212,18 +213,25 @@ export class Runner {
                 }
             }
         }
-        const faceSwap = seats.includes("readFace");
-        const priorFace = this.deps.readFace;
+        const faceSeats = ["readFace", "writeFace"].filter((seat) => seats.includes(seat));
+        const priorFaces = {
+            readFace: this.deps.readFace,
+            writeFace: this.deps.writeFace,
+        };
         const written = {
             ...this.deps,
             ...(expanded !== undefined ? { models: expanded } : {}),
             ...(catalogSwap && tiers !== undefined ? { tiers } : {}),
-            ...(faceSwap && candidate.readFace !== undefined ? { readFace: candidate.readFace } : {}),
         };
         if (catalogSwap && tiers === undefined)
             delete written.tiers;
-        if (faceSwap && candidate.readFace === undefined)
-            delete written.readFace;
+        const writtenFaceSeats = written;
+        for (const seat of faceSeats) {
+            if (candidate[seat] !== undefined)
+                writtenFaceSeats[seat] = candidate[seat];
+            else
+                delete writtenFaceSeats[seat];
+        }
         this.deps = written;
         if (catalogSwap) {
             const modelCount = Object.keys(candidate.models).length;
@@ -245,13 +253,15 @@ export class Runner {
                 });
             }
         }
-        if (faceSwap) {
-            const to = candidate.readFace ?? null;
-            deliverEngineNotice(this.deps.onNotice, {
-                code: "config.read_face_swapped",
-                message: `deployment read face swapped: ${priorFace ?? "(no declaration)"} → ${to ?? "(no declaration)"}; in-flight legs keep the face they prepared under, new legs resolve against the new declaration`,
-                detail: { from: priorFace ?? null, to, occurrenceId: uuidv7() },
-            });
+        for (const seat of faceSeats) {
+            const to = candidate[seat] ?? null;
+            const from = priorFaces[seat] ?? null;
+            const message = `deployment ${seat === "readFace" ? "read" : "write"} face swapped: ${from ?? "(no declaration)"} → ${to ?? "(no declaration)"}; in-flight legs keep the face they prepared under, new legs resolve against the new declaration`;
+            const detail = { from, to, occurrenceId: uuidv7() };
+            if (seat === "readFace")
+                deliverEngineNotice(this.deps.onNotice, { code: "config.read_face_swapped", message, detail });
+            else
+                deliverEngineNotice(this.deps.onNotice, { code: "config.write_face_swapped", message, detail });
         }
     }
     sideQuery(spec) {
@@ -413,6 +423,8 @@ export class Runner {
                         const { todoToolMounted, taskToolsMounted, writeFamilyOf, toolStartAt, startedToolCallIds } = runToolMountFacts({ spec, prepared, rs });
                         const { observeReasoningWireFacts, reasoningResolution } = runReasoningSeat({ prepared, rs, taskIdRef });
                         const { effectiveTimeoutMs, walltimeMonotonicDeadline, timeout, pushContent, ownCommittedTailRef, emitCommitted } = runClockAndContent({ spec, prepared, queue, internals, rs, ident, parentToolCallId, startedToolCallIds });
+                        const toolProgress = createToolProgressLane(pushContent, ident);
+                        prepared.toolProgressRef.current = toolProgress;
                         const { subagentName, withBrainSinks } = runBrainSinks({ queue, internals, rs, ident, parentToolCallId, observeReasoningWireFacts });
                         const toolLabels = new Map(prepared.tools.flatMap((t) => (t.label !== undefined && t.label !== t.name ? [[t.name, t.label]] : [])));
                         for (const orphan of prepared.wakeRecovered) {
@@ -426,7 +438,7 @@ export class Runner {
                             prepared, stats, rs,
                             deps: {
                                 spec, queue, internals, ident, parentToolCallId, subagentName,
-                                pushContent, emitCommitted, startedToolCallIds, toolStartAt, writeFamilyOf,
+                                pushContent, emitCommitted, startedToolCallIds, toolStartAt, toolProgress, writeFamilyOf,
                                 toolLabels, postToolBatchHook, batchArgs,
                                 runnerHooks: { onError: (e, info) => this.deps.onError?.(e, info) },
                             },
@@ -453,7 +465,7 @@ export class Runner {
                         });
                         const { flushGitMirror, unsubGitRetry, unsubBoundary, unsub } = runGitLane({ prepared, queue, rs, ident, onMessageUpdate, onMessageEnd, onToolStart, onToolEnd, onTurnEnd, onTurnBoundary, runner: this.depsSeat });
                         return runLeg({
-                            spec, queue, prepared, resume, rs, entryActor, effectiveTimeoutMs, timeout, pushContent, ident, emitCommitted, writeFamilyOf, startedToolCallIds,
+                            spec, queue, prepared, resume, rs, isDelegatedChild: internals?.isDelegatedChild === true, entryActor, effectiveTimeoutMs, timeout, pushContent, ident, emitCommitted, writeFamilyOf, startedToolCallIds,
                             announceWorkspaceMove, withBrainSinks, flushGitMirror, loopLatch, notificationLane, unsubscribeTaskNotifications, unsubGitRetry, unsubBoundary, unsub,
                             runner: this.depsSeat,
                             next: ({ final, threw, abortedLive, userInterruptedLive, strandedHumanAnswers }) => runTerminalAdoption({

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

@@ -52,12 +52,10 @@ 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
@@ -68,28 +66,24 @@ export declare const SKILL_CONTENT_MAX_CHARS: number;
  *  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. */
+/** 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 +110,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

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

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { defineTool } from "../tools.js";
 import { sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.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";
@@ -112,7 +113,9 @@ 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));
@@ -202,7 +205,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 +221,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 +252,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;

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();
+        },
+    };
+}