@sema-agent/core 7.17.7 → 7.19.0

package/dist/core/task-notification.js

@@ -115,8 +115,74 @@ export function isDelegatedAgentTerminal(n) {
 export function isTerminalTaskNotification(n) {
     return TERMINAL_STATUSES.has(n.status);
 }
+export function createLiveNotificationLane(seat) {
+    const handedOff = new Set();
+    const enter = (admits) => (payload, priority, onDisposition) => {
+        const dedupKey = taskNotificationDedupKey(payload);
+        if (seat.alreadyDelivered(dedupKey))
+            return "duplicate";
+        if (!admits(dedupKey))
+            return "unavailable";
+        const accepted = seat.queue.enqueue({ kind: "task_notification", priority, dedupKey, payload, ...(onDisposition !== undefined ? { onDisposition } : {}) });
+        if (!accepted)
+            return "pending";
+        return "taken";
+    };
+    return {
+        take: enter(() => seat.isLive()),
+        takeAsDestination: enter((dedupKey) => seat.isLive() && seat.canTakeNow() && !handedOff.has(dedupKey)),
+        handOff: (payload) => {
+            if (!seat.isLive())
+                return;
+            handedOff.add(taskNotificationDedupKey(payload));
+            if (handedOff.size > MAX_DEDUP_KEYS) {
+                for (const k of handedOff) {
+                    handedOff.delete(k);
+                    if (handedOff.size <= MAX_DEDUP_KEYS)
+                        break;
+                }
+            }
+        },
+        release: () => handedOff.clear(),
+    };
+}
+export class SessionLiveNotificationLanes {
+    lanes = new Map();
+    register(sessionId, lane) {
+        const existing = this.lanes.get(sessionId);
+        if (existing === undefined)
+            this.lanes.set(sessionId, [lane]);
+        else if (!existing.includes(lane))
+            existing.push(lane);
+    }
+    unregister(sessionId, lane) {
+        const existing = this.lanes.get(sessionId);
+        if (existing === undefined)
+            return;
+        const at = existing.indexOf(lane);
+        if (at !== -1)
+            existing.splice(at, 1);
+        if (existing.length === 0)
+            this.lanes.delete(sessionId);
+    }
+    deliver(sessionId, payload, priority, opts) {
+        const existing = this.lanes.get(sessionId);
+        if (existing === undefined)
+            return "unavailable";
+        for (let i = existing.length - 1; i >= 0; i -= 1) {
+            const outcome = existing[i](payload, priority, opts?.onDisposition);
+            if (outcome !== "unavailable")
+                return outcome;
+        }
+        return "unavailable";
+    }
+    get size() {
+        return this.lanes.size;
+    }
+}
 export class PendingSessionNotifications {
     sessions = new Map();
+    liveLanes = new SessionLiveNotificationLanes();
     droppedSessions = 0;
     evictedSessions = new Map();
     unattributedDrops = 0;
@@ -163,6 +229,7 @@ export class PendingSessionNotifications {
             evictOldest(s, () => true);
     }
     drain(sessionId) {
+        this.routed.delete(sessionId);
         const s = this.sessions.get(sessionId);
         if (s !== undefined) {
             this.sessions.delete(sessionId);
@@ -182,10 +249,49 @@ export class PendingSessionNotifications {
         out.droppedWholeSession = (out.droppedWholeSession ?? 0) + (tomb ?? 0) + carried;
         return out;
     }
+    routed = new Map();
+    holdsKey(sessionId, dedupKey) {
+        return this.sessions.get(sessionId)?.keys.has(dedupKey) === true || this.routed.get(sessionId)?.has(dedupKey) === true;
+    }
+    markDelivered(sessionId, dedupKey) {
+        let mine = this.routed.get(sessionId);
+        if (mine === undefined) {
+            if (this.routed.size >= MAX_PENDING_SESSIONS) {
+                const oldest = this.routed.keys().next().value;
+                if (oldest !== undefined)
+                    this.routed.delete(oldest);
+            }
+            mine = new Set();
+            this.routed.set(sessionId, mine);
+        }
+        mine.add(dedupKey);
+        if (mine.size > MAX_PENDING_EVENTS_PER_SESSION) {
+            for (const k of mine) {
+                mine.delete(k);
+                if (mine.size <= MAX_PENDING_EVENTS_PER_SESSION)
+                    break;
+            }
+        }
+    }
     get size() {
         return this.sessions.size;
     }
 }
+export function routeOrParkNotification(store, sessionId, payload, priority, onDisposition) {
+    const dedupKey = taskNotificationDedupKey(payload);
+    if (store.holdsKey(sessionId, dedupKey)) {
+        onDisposition?.("parked");
+        return;
+    }
+    const routed = store.liveLanes.deliver(sessionId, payload, priority, { ...(onDisposition !== undefined ? { onDisposition } : {}) });
+    if (routed === "unavailable") {
+        store.pend(sessionId, payload, priority);
+        onDisposition?.("parked");
+    }
+    else if (routed !== "taken") {
+        onDisposition?.("queued");
+    }
+}
 function evictOldest(s, match) {
     let idx = s.items.findIndex((i) => match(i) && !TERMINAL_STATUSES.has(i.status));
     if (idx === -1)

package/dist/core/task-result.d.ts

@@ -541,7 +541,15 @@ export interface TaskResult {
      * `"open"` observation is never forwarded) closes that escape for ANY follow-on, not just the
      * verifier. See {@link effectiveReadDenyPatterns} for the deny-set half.
      */
-    effectiveReadFace?: import("../tools/fs/read-face.js").ReadFace;
+    effectiveReadFace?: import("../tools/fs/containment-face.js").ContainmentFace;
+    /**
+     * The WRITE-face containment state in force on this leg, the read seat's twin as an engine-filled
+     * OBSERVATION. Same in-presence condition as {@link effectiveReadFace} (every leg that completes
+     * prepare; absent only on prepare-failure terminals) and the same purpose: a POST-COMPLETION follow-on
+     * leg folds it stricter-wins into its own spec. Only `"roots"` is ever worth forwarding; an `"open"`
+     * observation never widens anything by itself.
+     */
+    effectiveWriteFace?: import("../tools/fs/containment-face.js").ContainmentFace;
     /**
      * The sensitive-path deny ADDITIONS in force on this leg beyond the
      * built-in table, normalized (deployment ∪ task ∪ checkpoint-frozen seed), as an engine-filled

package/dist/core/task-spec.d.ts

@@ -795,15 +795,32 @@ export interface TaskSpec {
     readDenyPatterns?: readonly import("../tools/fs/read-deny.js").ReadDenyEntry[];
     /**
      * design/199 件A — the TASK layer's read-face containment declaration
-     * ({@link import("../tools/fs/read-face.js").ReadFace}). "roots" pins this task (and, via the
+     * ({@link import("../tools/fs/containment-face.js").ContainmentFace}). "roots" pins this task (and, via the
      * tighten-only clamp, its whole delegation subtree) to the historical containment; "open" lifts
      * the roots judgment for the structured read faces — refused loudly under org governance (the
      * task layer only tightens there; the deployment opens via {@link RunnerDeps.readFace}) and
      * beside `handsReadOnly: true` (the verifier containment is load-bearing). Absent ⇒ the
      * deployment seat, then the engine default ("roots" — D-1b: an upgrade never opens implicitly).
-     * Bad values refuse loudly (#123). Never affects the write faces.
+     * Bad values refuse loudly (#123). Never affects the write faces — that is {@link writeFace}, a
+     * separate seat with its own default.
      */
-    readFace?: import("../tools/fs/read-face.js").ReadFace;
+    readFace?: import("../tools/fs/containment-face.js").ContainmentFace;
+    /**
+     * The TASK layer's WRITE-face containment declaration
+     * ({@link import("../tools/fs/containment-face.js").ContainmentFace}) — the read seat's twin,
+     * resolved through the SAME order (`resolveContainmentFace`, one body, one set of rows). "roots"
+     * pins this task (and, via the tighten-only clamp, its whole delegation subtree) to the historical
+     * write fence; "open" lifts the roots judgment for the structured WRITE faces (`edit_file` /
+     * `write_file` / `notebook_edit`) — refused loudly under org governance (the task layer only
+     * tightens there; the deployment opens via {@link RunnerDeps.writeFace}) and beside
+     * `handsReadOnly: true` (that mount carries no write faces at all). Absent ⇒ the deployment seat,
+     * then the engine default ("roots" — an upgrade never opens implicitly). Bad values refuse loudly.
+     *
+     * What "open" does NOT change: the write-side sensitive-path policy, the blocked-device gate, the
+     * UNC out-of-set refusal, the read-before-edit requirement and the deployment's approval policy. Seat
+     * independence is owned by `fs.containment_face.seat_independence` ({@link import("../tools/fs/containment-face.js").resolveContainmentFace}).
+     */
+    writeFace?: import("../tools/fs/containment-face.js").ContainmentFace;
     /**
      * design/80 D-B — opt in to PLAN MODE: mount the first-party `present_plan` tool (CC `ExitPlanMode` parity).
      * The model calls it to present a plan; the engine then pauses with a durable `plan_review` checkpoint
@@ -918,6 +935,32 @@ export interface TaskSpec {
      * end-user-authored skills are responsible for vetting them: a skill IS instructions by design.
      */
     skills?: SkillSpec[];
+    /**
+     * Fraction of the model's context window the `<skills>` listing may spend. Absent ⇒ `0.01` (1%).
+     * Domain `(0, 1]`; anything else — including `0`, a string, `NaN` — REFUSES at the door with
+     * `config.skill_listing_budget_invalid` rather than folding back to the default.
+     *
+     * The budget is `(contextTokens ?? contextWindow ?? 200 000) × 4 × fraction`, in UTF-8 bytes, and the
+     * listing degrades inside it: every skill stays listed, the lower-priority ones (declaration order)
+     * lose their descriptions first. Raising this is opting in to a higher per-turn context cost.
+     *
+     * ⚠️ ONE-WAY IN PRACTICE (`@contract skills.listing_budget_ceiling`): the listing rides the turn-
+     * attachment lane, whose bundle cap is a hard structural limit, so the resolved budget is clamped to
+     * 8 000 bytes. A fraction that asks for MORE lowers nothing and raises nothing; a fraction that asks
+     * for less takes effect exactly. When the clamp costs a skill its description, both numbers ride the
+     * `skills.listing_truncated` notice.
+     *
+     * ⚠️ A model declaring a window SMALLER than 200 000 tokens now gets a proportionally smaller listing
+     * budget than the flat 8 000 bytes that preceded this seat.
+     */
+    skillListingBudgetFraction?: number;
+    /**
+     * Per-skill description cap inside the `<skills>` listing, in code units, ellipsis included. Absent ⇒
+     * `1536`. Must be a positive integer; anything else REFUSES with
+     * `config.skill_listing_budget_invalid`. A description longer than the cap is truncated to exactly
+     * this many units; lowering it is how a deployment fits more skills' descriptions inside one budget.
+     */
+    skillListingMaxDescChars?: number;
     /**
      * design/129 — lifetime scope for BACKGROUND children (Agent/Fork `run_in_background`). Default `"task"`:
      * the parent runTask's terminal reaps them (design/115 — no orphans burning tokens; turn-end killed

package/dist/core/tighten-task-spec.js

@@ -25,11 +25,13 @@ export function tightenTaskSpec(base, overrides) {
             merged[field] = [...new Set([...(b ?? []), ...(o ?? [])])];
         }
     }
-    if (base.readFace === "roots" && overrides.readFace === "open") {
-        throw new TaskSpecTightenError('tightenTaskSpec: cannot loosen readFace from "roots" to "open" (override may only tighten)');
-    }
-    if (base.readFace !== undefined || overrides.readFace !== undefined) {
-        merged.readFace = base.readFace === "roots" || overrides.readFace === "roots" ? "roots" : (overrides.readFace ?? base.readFace);
+    for (const faceKey of ["readFace", "writeFace"]) {
+        if (base[faceKey] === "roots" && overrides[faceKey] === "open") {
+            throw new TaskSpecTightenError(`tightenTaskSpec: cannot loosen ${faceKey} from "roots" to "open" (override may only tighten)`);
+        }
+        if (base[faceKey] !== undefined || overrides[faceKey] !== undefined) {
+            merged[faceKey] = base[faceKey] === "roots" || overrides[faceKey] === "roots" ? "roots" : (overrides[faceKey] ?? base[faceKey]);
+        }
     }
     if (base.readDenyPatterns !== undefined || overrides.readDenyPatterns !== undefined) {
         const seen = new Set();

package/dist/core/tool-model-gate.d.ts

@@ -67,7 +67,7 @@ export declare const TOOL_MODEL_GATE_CLASSES: Readonly<Record<string, ToolModelG
  */
 export declare function isModelGatedForClass(modelId: string, rule: ToolModelGateRule): boolean;
 /**
- * #123 value screen for `TaskSpec.restoreGatedTools` (same posture as `assertReadFaceValue`: the
+ * #123 value screen for `TaskSpec.restoreGatedTools` (same posture as `assertContainmentFaceValue`: the
  * VALUE is screened at the door, unconditionally — a garbage restore list must refuse loudly on
  * every leg, never be silently read as "no restore" in the narrowing direction). Legal: absent,
  * literal `true` (restore every class), or an array of strings (wire names; unknown names are

package/dist/core/tool-policy.d.ts

@@ -1,5 +1,5 @@
 import type { AskOrigin } from "./ask-origin.js";
-import type { Settlement } from "./gate-outcome.js";
+import { type Settlement } from "./gate-outcome.js";
 /** A tool call presented to a policy before it executes. */
 /** design/388 B6 — the per-call face (see {@link ToolCallRequest.face}). */
 export interface ToolCallFace {
@@ -310,6 +310,11 @@ export type PermissionResult = {
      *  in the one direction the stamp cannot reach (a caller composing its own ask) the claim is
      *  tightening-only: it can make an ask outlive a rule, never turn one into an allow. */
     probeMandated?: true;
+    /** The probe named a directory that would clear this ask
+     *  ({@link import("./types.js").ReversibilityVerdict.readRootCandidate}). Display metadata like the two
+     *  `probe*` above; ENGINE-STAMPED and VALIDATED at the tighten, and deliberately NOT merged onto an ask
+     *  another layer raised, which a grant leaves standing. */
+    probeReadRootCandidate?: import("./types.js").ReadRootGrantCandidate;
     /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules`
      *  shape); carries the matched rule's text. Present ⇔ a rule someone WROTE says "ask about this",
      *  never for a `defaultAction:"ask"` fallback (an unmatched call is default-closed posture, not a
@@ -1013,6 +1018,15 @@ export interface AskRequest {
      *  structure: render the entries as data, never re-derive structure by splitting or joining them.
      *  The durable park route carries the same value as `RiskDescriptor.probeCause`. */
     readonly probeCause?: import("./checkpoint-store.js").ProbeCause;
+    /**
+     * The ask-facing face of {@link import("./types.js").ReversibilityVerdict.readRootCandidate}, which owns
+     * the meaning, the absence reading and the spelling contract: PRESENT ⇒ declaring this one directory
+     * clears THIS ask, so a card can offer "add it and stop being asked" beside "yes, this once". Filled at
+     * the synchronous MINT station by the tighten that ran the probe — the three INHERITED-lane sites present
+     * an ancestor's decision from upstream of it and carry none, and the durable park row has NO twin: a
+     * parked out-of-root ask renders the confirmation alone.
+     */
+    readonly readRootCandidate?: import("./types.js").ReadRootGrantCandidate;
     /** design/252 G-2: the RULE-PROVENANCE evidence behind this ask — the org snapshot revision and the
      *  matched rules' own identity keys, each present as a value or as a named absence (see
      *  {@link AskRuleEvidence}). Present on EVERY ask the engine mints, so a consumer never has to tell a
@@ -1121,9 +1135,10 @@ export interface AskRequest {
      *    probe declared structural — for the built-in shell probe, a read outside the directories this
      *    session declared. A surface must NOT point at rule-writing here — "allow rules silence the
      *    classifier's questions, never a mandated one", so a rule minted in answer to this line would
-     *    never take effect where it was minted. It must not point at a directory GRANT either: the
-     *    out-of-root arm has no clearing configuration in this version, and confirming the call is the
-     *    whole of what a person can do about it;
+     *    never take effect where it was minted. Whether a DIRECTORY grant is worth pointing at is not this
+     *    seat's to say: it is answered per ask by {@link readRootCandidate}, which is present exactly when
+     *    widening the session's read directories would clear this one and absent for every other member of
+     *    the family — so a surface reads that seat and never infers an answer from this word;
      *  · `"shadowed"` — a rule the person already wrote is speaking and does not clear this ask (a
      *    matching allow rule that the lane refuses to honor here, or their own explicit `ask` rule);
      *  · `"lane_cannot_speak"` — the lane is armed and this ask IS clearable, but the offer lane

package/dist/core/tool-policy.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { brandPolicyAskClass } from "./ask-class.js";
+import { decidersNote, settledByPerson } from "./gate-outcome.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
@@ -18,9 +19,6 @@ const DECISION_REASON_SET = new Set(DECISION_REASONS);
 function settledByNobody(kind) {
     return { kind, who: { party: "none" }, when: Date.now() };
 }
-function settledByPerson(kind, approver, note) {
-    return { kind, who: { party: "person", ...(approver !== undefined ? { approver } : {}) }, when: Date.now(), ...(note !== undefined ? { note } : {}) };
-}
 const ENGINE_SETTLEMENTS = new WeakMap();
 function attestEngineSettlement(d, record, call) {
     const s = record.settlement;
@@ -1273,7 +1271,7 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
                         settlement: settledByNobody("approver_contract"),
                     };
                 }
-                reasonText = typeof suppliedReason === "string" && suppliedReason !== "" ? suppliedReason : undefined;
+                reasonText = typeof suppliedReason === "string" ? suppliedReason : undefined;
             }
             catch (err) {
                 return {
@@ -1283,15 +1281,16 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
                     settlement: settledByNobody("approver_contract"),
                 };
             }
+            const note = decidersNote(reasonText);
             return {
                 action: "deny",
                 message: supplied === "timeout"
-                    ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${reasonText !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reasonText, REVIEWER_NOTE_MAX_BODY)}` : ""}`
-                    : humanRefusalMessage(req, reasonText),
+                    ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", note, REVIEWER_NOTE_MAX_BODY)}` : ""}`
+                    : humanRefusalMessage(req, note),
                 decisionReason: "mode",
                 settlement: supplied === "timeout"
                     ? { kind: "approval_window_expired", who: { party: "host" }, when: Date.now() }
-                    : settledByPerson("human_refused", attribution.approver, reasonText),
+                    : settledByPerson("human_refused", attribution.approver, note),
             };
         }
         if (suppliedEdit === undefined)

package/dist/core/tool-search-setting.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The deferral gate's POLICY SEAT as vocabulary: the three states a deployment may declare
+ * (`RunnerDeps.toolSearch`), the word a disclosure reports, and the ONE reader that lowers the seat to the
+ * single number the gate compares against. Pure — no harness, no roster, no I/O. `runner/tool-defer-gate.ts`
+ * owns the gate that consumes the number.
+ */
+/** The default threshold percent: with no seat, the candidate set defers when its inlined size reaches this
+ *  percent of the model's context window. `DEFER_THRESHOLD_FRACTION` is derived from it. */
+export declare const TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT = 10;
+/** The typed refusal a `toolSearch` seat outside its domain raises: a bad value never selects an arm
+ *  silently and never folds back to the default gate. */
+export declare const TOOL_SEARCH_INVALID_CODE = "config.tool_search_invalid";
+/**
+ * The deployment's deferral-gate SETTING: `true` = the candidate set defers on every request, `false` = it never defers (and with no caller list no
+ * ToolSearch mounts), `{mode:"auto", thresholdPercent}` = the threshold gate at that percent of the context window (omitted ⇒
+ * {@link TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT}). Absent ⇒ that default — the pre-seat behavior.
+ *
+ * @contract defer_gate.one_threshold — the three states are THREE VALUES OF ONE NUMBER, never three code paths: {@link resolveToolSearch} lowers the seat to
+ * one threshold fraction (`true` ⇒ `0`, so every candidate byte is over budget; `false` ⇒ `Infinity`, so no candidate set reaches it; `auto:N` ⇒ `N/100`) and
+ * `deferralGate` keeps its ONE comparison `gatedChars ≥ thresholdChars`; a second arm for a new state breaks this contract rather than extending it. It
+ * governs rule ② ONLY — `TaskSpec.deferTools` still defers under every state, `alwaysLoadTools` still pins first, and `RunnerDeps.deferMode` remains the
+ * orthogonal knob that WIDENS rule ②'s candidate set.
+ */
+export type ToolSearchSetting = boolean | {
+    mode: "auto";
+    thresholdPercent?: number;
+};
+/** The three arms of {@link ToolSearchSetting} as one word — the disclosure face's vocabulary. */
+export declare const TOOL_SEARCH_POLICIES: readonly ["always", "never", "auto"];
+export type ToolSearchPolicy = (typeof TOOL_SEARCH_POLICIES)[number];
+/** The lowered seat: the word a disclosure reports, and the ONE number the gate compares against. */
+export interface ResolvedToolSearch {
+    policy: ToolSearchPolicy;
+    /** Present iff `policy === "auto"` — the percent the deployment asked for (or the default). */
+    thresholdPercent?: number;
+    /** The fraction of the context window the candidate set must reach: `0` (always) / `Infinity` (never) /
+     *  `thresholdPercent / 100`. This is the gate's only input from the seat. */
+    fraction: number;
+}
+/**
+ * The ONE reader of {@link ToolSearchSetting} (`@contract defer_gate.one_threshold`). A value outside the domain refuses loudly with
+ * {@link TOOL_SEARCH_INVALID_CODE} — an unparseable knob must not fall back to the default gate while the deployment believes its declaration took effect.
+ * The object form's MEMBER SET is part of that domain (`mode` + `thresholdPercent`, nothing else): an unknown key is the same silent fold one level down,
+ * since a misspelled percent lowers to the default while the declaration looks like it took effect.
+ * `thresholdPercent` must be a finite number in `[0, 100]`, and the two ends are NOT symmetric: `auto:0` is
+ * an exact alias for `true` (threshold 0), while `auto:100` is the FULL-WINDOW threshold, not `false`. Only
+ * `false` never defers.
+ */
+export declare function resolveToolSearch(setting: ToolSearchSetting | undefined): ResolvedToolSearch;
+/**
+ * Describe a REJECTED value for a refusal message — the ONE describer the config seats share — without ever
+ * throwing, and without letting the rejected value NARRATE ITSELF.
+ *
+ * Two failures, one root. `JSON.stringify` is not total (a BigInt and a circular object make it throw, and a
+ * formatter that throws inside a refusal replaces the coded refusal with an uncoded `TypeError`) — and where
+ * it does not throw it calls the VALUE'S OWN `toJSON`, i.e. it asks the thing being rejected to say what it
+ * is. Measured: `{ toJSON: () => "open" }` described itself as `"open"`, so a refusal of an illegal object
+ * read as a refusal of a legal word; `{ toJSON: () => undefined }` fell through to `String(value)` and read
+ * `[object Object]`; a function printed its whole source (unbounded, and equally forgeable through
+ * `toString`); and `NaN` / `Infinity` — the two numbers these seats reject most — both came out as `null`,
+ * the spelling of a value the caller never wrote.
+ *
+ * So: PRIMITIVES are spelled exactly (a number through `String`, which is total and keeps `NaN`, `Infinity`
+ * and the `-0` a caller can only have written deliberately); anything else is DESCRIBED structurally — its
+ * shape, its constructor's name and its own top-level keys, bounded. Reading those may still hit a proxy's
+ * traps (every read is guarded), but NOTHING a read hands back is turned into text unless it is already a
+ * primitive of the expected domain — a formatting hook of the value is never what writes this sentence. A description is worth less to a reader than the value would be; a WRONG value is worth less than
+ * nothing, because it sends them to fix something they did not write.
+ */
+export declare function describeRejectedValue(value: unknown): string;
+/**
+ * The INERT spelling of a lowered policy — the exact seat value that lowers back to it, with no accessor,
+ * proxy or prototype left on the path. A nested accessor (`get thresholdPercent()`) answers every later read
+ * differently, so a phase that runs several passes over one cached object still measures several different
+ * numbers. Round-trip: `resolveToolSearch(toolSearchSettingOf(r))` deep-equals `r` for every `r` this module
+ * mints.
+ */
+export declare function toolSearchSettingOf(resolved: ResolvedToolSearch): ToolSearchSetting;

package/dist/core/tool-search-setting.js

@@ -0,0 +1,90 @@
+export const TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT = 10;
+export const TOOL_SEARCH_INVALID_CODE = "config.tool_search_invalid";
+export const TOOL_SEARCH_POLICIES = ["always", "never", "auto"];
+export function resolveToolSearch(setting) {
+    if (setting === undefined)
+        return { policy: "auto", thresholdPercent: TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT, fraction: TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT / 100 };
+    if (setting === true)
+        return { policy: "always", fraction: 0 };
+    if (setting === false)
+        return { policy: "never", fraction: Number.POSITIVE_INFINITY };
+    if (typeof setting !== "object" || setting === null) {
+        throw toolSearchRefusal(`invalid value ${describeRejectedValue(setting)} — expected true, false, {mode:"auto"} or {mode:"auto", thresholdPercent:N}`);
+    }
+    let mode;
+    let percent;
+    let keys = [];
+    try {
+        keys = Object.keys(setting);
+        mode = setting.mode;
+        percent = setting.thresholdPercent;
+    }
+    catch {
+        throw toolSearchRefusal(`its members could not be read (a throwing accessor, or a revoked proxy) — expected true, false, {mode:"auto"} or {mode:"auto", thresholdPercent:N}`);
+    }
+    if (mode !== "auto") {
+        throw toolSearchRefusal(`invalid value ${describeRejectedValue(setting)} — expected true, false, {mode:"auto"} or {mode:"auto", thresholdPercent:N}`);
+    }
+    const stray = keys.find((k) => k !== "mode" && k !== "thresholdPercent");
+    if (stray !== undefined) {
+        throw toolSearchRefusal(`unknown member ${JSON.stringify(stray)} — the object form carries mode and thresholdPercent only`);
+    }
+    if (percent === undefined)
+        return { policy: "auto", thresholdPercent: TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT, fraction: TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT / 100 };
+    if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0 || percent > 100) {
+        throw toolSearchRefusal(`thresholdPercent ${describeRejectedValue(percent)} is not a finite percent in [0, 100]`);
+    }
+    return { policy: "auto", thresholdPercent: percent, fraction: percent / 100 };
+}
+export function describeRejectedValue(value) {
+    try {
+        switch (typeof value) {
+            case "bigint":
+                return `${value}n`;
+            case "symbol":
+                return String(value);
+            case "string":
+                return JSON.stringify(value);
+            case "number":
+                return Object.is(value, -0) ? "-0" : String(value);
+            case "boolean":
+            case "undefined":
+                return String(value);
+            case "function":
+                return "a function";
+        }
+        if (value === null || value === undefined)
+            return String(value);
+        let ctor = "";
+        try {
+            const name = value.constructor?.name;
+            if (typeof name === "string" && name !== "" && name !== "Object" && name !== "Array")
+                ctor = ` (${name.slice(0, 40)})`;
+        }
+        catch {
+        }
+        if (Array.isArray(value)) {
+            const n = value.length;
+            return `an array${ctor}${typeof n === "number" && Number.isSafeInteger(n) && n >= 0 ? ` of ${n} member(s)` : ""}`;
+        }
+        const keys = Object.keys(value);
+        if (keys.length === 0)
+            return `an object${ctor} with no keys`;
+        return `an object${ctor} with keys [${keys.slice(0, 5).map((k) => k.slice(0, 40)).join(", ")}${keys.length > 5 ? ", …" : ""}]`;
+    }
+    catch {
+        return `a value of type ${value === null ? "null" : typeof value} that cannot be described`;
+    }
+}
+export function toolSearchSettingOf(resolved) {
+    if (resolved.policy === "always")
+        return true;
+    if (resolved.policy === "never")
+        return false;
+    return { mode: "auto", thresholdPercent: resolved.thresholdPercent ?? TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT };
+}
+function toolSearchRefusal(problem) {
+    const e = new Error(`RunnerDeps.toolSearch: ${problem}; a bad value refuses loudly, nothing falls back to the default gate.`);
+    e.code = TOOL_SEARCH_INVALID_CODE;
+    return e;
+}

package/dist/core/tool-spec.d.ts

@@ -62,12 +62,45 @@ export interface ReversibilityVerdict {
      * its own deployment a re-confirmation and can never turn an ask into an allow.
      *
      * The built-in shell probe sets it for exactly one family: a listed reader naming a path outside the
-     * session's allowed directories. The engine's own out-of-root demotion has no clearing channel in
-     * this version other than confirming the call each time — a directory-scoped grant that WOULD clear
-     * it is a separate, later mechanism, and until it exists a surface must not word the refusal as
-     * though one already answers it.
+     * session's allowed directories. That demotion HAS a clearing channel — widening the declared read
+     * directories retires it — and where the probe can name the directory, {@link readRootCandidate} carries
+     * it. A mandated ask WITHOUT that member has no configuration behind it: the rest of the family (an
+     * operator `shellGate:"always"`, the tool's egress/irreversibility marks, an org demand, an out-of-root
+     * arm with no named directory) is confirm-or-refuse, and must not be worded as though a grant answers it.
      */
     mandated?: boolean;
+    /**
+     * The directory-scoped GRANT that would clear THIS ask, when the probe can name one: PRESENT ⇒ the only
+     * thing between this call and a plain `reversible: true` verdict is the session's declared read
+     * containment, and adding {@link ReadRootGrantCandidate.dir} to it makes the same call run with no card.
+     *
+     * ABSENT is the ordinary world and no claim that nothing would clear the ask — it covers every demotion
+     * with no directory answer (a deny row, a read the walk could not read, an unenumerable expansion, a
+     * shape refused whatever the roots say) and every probe silent on this member. Read presence, never
+     * absence. ADVISORY display metadata, never adjudication input.
+     */
+    readRootCandidate?: ReadRootGrantCandidate;
+}
+/**
+ * A directory-scoped grant a surface can offer on an approval card — see
+ * {@link ReversibilityVerdict.readRootCandidate} and `AskRequest.readRootCandidate`.
+ *
+ * @contract shell.read_boundary.grant_candidate_is_the_grant — {@link dir} is the string to ADD, not a
+ * string to show: a consumer that renders a shortened or home-relative form must send this exact spelling
+ * back when the person accepts. Core mints one spelling for both errands, and the promise is over THAT
+ * spelling reaching the directories the boundary compares against: a deployment that REWRITES a declared
+ * directory — canonicalizing a symlinked one included — must rewrite the command's spelling the same way,
+ * or it will compare a rewritten root against an unrewritten operand and ask again. Where the two differ
+ * the ask was unclearable before this seat existed and still is; the offer names the directory the command
+ * spelled, which is the only one derivable from the text.
+ */
+export interface ReadRootGrantCandidate {
+    /** An absolute, lexically folded directory in the boundary's own spelling; never a file or a pattern. */
+    readonly dir: string;
+    /** Always the literal `true` — a shape, not a value, so the seat cannot be widened into a "maybe this
+     *  helps" hint without a visible type change. It claims THIS ask: not the deny layer (judged by pattern
+     *  rather than by root, and unmoved by any grant), and not another ask the same call may raise. */
+    readonly clearsThisAsk: true;
 }
 export interface ToolSpec<TParams extends TSchema = TSchema> {
     /**
@@ -852,6 +885,14 @@ export interface ToolExecuteContext {
      * ONLY as the delegation carrier — no tool adapts its model-facing behavior on it.
      */
     readFace?: "roots";
+    /**
+     * The WRITE-face clamp carrier ({@link TaskSpec.writeFace}), the read carrier's twin: present (as
+     * "roots") ONLY when this run RESOLVED to the roots write face, so a delegation tool pins every
+     * child spec to roots — without it a roots-narrowed parent's children would resolve the shared
+     * deployment seat (possibly "open") and write wider than the parent could. Strictly a tightening
+     * carrier, and independent of {@link readFace}.
+     */
+    writeFace?: "roots";
     /**
      * design/199 件B — the parent task's OWN deny-set additions ({@link TaskSpec.readDenyPatterns}),
      * traveling the delegation tree add-only (a child judges at least every entry its parent judged).

package/dist/core/types.d.ts

@@ -13,7 +13,7 @@ import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVer
 import type { Model, StreamFn } from "../internal/llm.js";
 export type { ModelRef, ModelRole, RoleSpec, ModelRoles, Brain } from "./model-seat.js";
 export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine } from "./task-spec.js";
-export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
+export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrantCandidate, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
 export type { AgentDefinition, SkillManifest, SkillSpec } from "./agent-definition.js";
 export type { McpServerSpec, A2aServerSpec, McpElicitRequest, McpElicitResponse, OnElicit } from "./mcp-server-spec.js";
@@ -28,5 +28,5 @@ export type { BackgroundChildEvent, DelegationLifecycleEvent } from "./delegatio
 export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
 export type { ProjectMemoryLoad, ResumePreflightInfo, ResumePreflightVerdict, RunnerDeps } from "./runner-deps.js";
 export type { EngineNotice } from "./engine-notice.js";
-export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, undrainedUserInputNotices } from "./engine-notice.js";
+export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, undrainedUserInputNotices } from "./engine-notice.js";
 export type { AgentTool, Model, StreamFn, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict };

package/dist/core/types.js

@@ -1,3 +1,3 @@
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
 export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
-export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, undrainedUserInputNotices } from "./engine-notice.js";
+export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, undrainedUserInputNotices } from "./engine-notice.js";