@sema-agent/core 7.14.0 → 7.15.0

package/dist/core/runner/prepare-task.js

@@ -265,8 +265,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     announceToolModelGate(deps.onNotice, model.id, doors.modelGate);
     const modelGateManifest = toolModelGateManifest(doors.modelGate);
     const { toolEffects, egressTools, irreversibleTools, irreversibilityTier, axisExplicitNegatives, reversibilityProbes, ownToolNames } = prepareSafetyScan({ spec, deps });
-    let shellGatedBash = false;
-    let shellGatedMonitor = false;
+    let shellGatedTools = new Set();
     refuseRequireExistingWithoutSession(spec);
     const { acquired, session, conflictRef, wakeRecovered, resumeAtBeforeParentId } = await prepareAcquireReconcile({ sessions, spec, resume, toolEffects, ...(internals?.sessionPlacement !== undefined ? { placement: internals.sessionPlacement } : {}), ...(() => { const g = durableParkGapFor(deps, spec); return g !== undefined ? { durableParkGap: g } : {}; })() });
     const sessionId = acquired.sessionId;
@@ -512,8 +511,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         resolvedReadFace = handsReadFace.resolvedReadFace;
         readDenyAdditionsNormalized = handsReadFace.readDenyAdditionsNormalized;
         handsLessResolvedFace = handsReadFace.handsLessResolvedFace;
-        shellGatedBash = handsReadFace.shellGatedBash;
-        shellGatedMonitor = handsReadFace.shellGatedMonitor;
+        shellGatedTools = handsReadFace.shellGatedTools;
         const { worktreeSessionRef } = prepareDelegationSurface({ spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, roster, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle });
         const { liveQuestionFace, contentAskBindings, contentAskRoutable, lateStrandedAnswers, discloseStrandedAnswers, settleContentAskBindings, durableQuestionFace, questionToolMounted, mountedQuestionTool } = prepareQuestionFace({ frozenOnQuestion, spec, deps, checkpointStore, runtimeCaps, resolvedInteractionPosture, resume, sessionId, roster, inheritedUnavailableAsks: () => inheritedUnavailableAsks });
         if (spec.handsReadOnly !== true) {
@@ -683,7 +681,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 releaseSignal = () => sig.removeEventListener("abort", onExternalAbort);
             }
         }
-        const { hooks, hookTimeoutMs, preToolUseObservational, ownGatePreToolUse, basePolicyForResumeEdit, denyNarrowingPolicy, policyLayers, effectivePolicy, inheritedUnavailableAsks, inheritedAskGrants, askSourceIdentity, riskAxesOf, ruleOffersOf, permissionRuleLane, permissionRuleOrgLane, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, foldAskClasses, ancestorSandboxAdmissions } = await preparePolicyChain({ spec, deps, internals, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, lockedPreflight, tools, harnessTools, toolEffects, egressTools, irreversibilityTier, axisExplicitNegatives, ownToolNames, shellGatedBash, handsCwdRef, readDenyMatcher, questionToolMounted, runtimeCaps, inheritedAncestorRules, inheritedParentConstraints, seedInheritedGate, hasSkillManifest, skillScope, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, autoModeDecider, stopForDenialLimit, delegation, abortController, now, ownSessionRulesRef });
+        const { hooks, hookTimeoutMs, preToolUseObservational, ownGatePreToolUse, basePolicyForResumeEdit, denyNarrowingPolicy, policyLayers, effectivePolicy, inheritedUnavailableAsks, inheritedAskGrants, askSourceIdentity, riskAxesOf, ruleOffersOf, permissionRuleLane, permissionRuleOrgLane, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, foldAskClasses, ancestorSandboxAdmissions } = await preparePolicyChain({ spec, deps, internals, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, lockedPreflight, tools, harnessTools, toolEffects, egressTools, irreversibilityTier, axisExplicitNegatives, ownToolNames, shellGatedTools, handsCwdRef, readDenyMatcher, questionToolMounted, runtimeCaps, inheritedAncestorRules, inheritedParentConstraints, seedInheritedGate, hasSkillManifest, skillScope, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, autoModeDecider, stopForDenialLimit, delegation, abortController, now, ownSessionRulesRef });
         const { onAsk, preToolContexts, blockedToolCalls, gateOutcomes, batchHaltRef, blockedTracked, incompleteSuspendAdapter, durableSuspendInfraReady, resourceSuspendEligible, usageGovernance, durableApproval, wiringManifest, parkLaneArmed, gateMachineryActive, hookIdentity, hookEnvFace } = prepareWiringManifest({ spec, deps, internals, resume, sessionId, runId, hostTaskId, taskScope, hooks, preToolUseObservational, policyLayers, effectivePolicy, handsEnabled, mcp, irreversibleTools, egressTools, toolEffects, ownedEnv, executionEnv, offloadStore, onceLedger, usageWindows, envLifetimeSuspendAt, runtimeCaps, resolvedInteractionPosture, durableQuestionFace, liveQuestionFace, checkpointStore, sessions, modelGateManifest, autoModeArmReason, lockedPreflight, peerLaneRefs, peerLaneActive, harness, pausedRef, frozenOnAsk, liveInheritedGate, delegation, toolRoster });
         if (fileHistoryBoundary !== undefined) {
             harness.on("tool_call", async () => {
@@ -694,8 +692,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const { askLane } = prepareAskLane({ gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash });
         const { saga } = prepareSuspendSaga({ gateMachineryActive, abortController, harness, checkpointStore, deps, sessionId, hostTaskId, taskScope, liveSpendRef, resume, nestedStats, internals, activeTools, outputRef, readFileStateForCheckpoint, faceCheckpointSection, reminderMark, handsCwdRef, worktreeSessionRef, inheritedParentConstraints, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, autoModeIntent, inheritedAdmittedOrgScopes, ownOrgVerdictRef, orgGovernedProvenance, announcedListingsRef, gitStatusRef, hookIdentity, placementRootResolved, externalContentTargetActive, remoteEnvFailures, memoryEngineSession, suspendLoopRef, ownedEnv, incompleteSuspendAdapter });
         const { suspendForResource, suspendForPlatformLimit, suspendForReview } = prepareBoundaryParks({ saga, spec, checkpointStore, abortController, harness, session, sessions, sessionId, deps, priorLedger, maxSlices, maxSuspends, resourceTotal, priorSuspendCount, suspendChainBase, humanReviewRef, liveSpendRef, now, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, pausedRef, remoteEnvFailures, resourceSuspendEligible, durableSuspendInfraReady, incompleteSuspendAdapter });
-        const { parkAsk } = prepareParkAsk({ askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas: rosterSeat, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedBash, shellGatedMonitor, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef });
-        prepareGateStations({ askLane, parkAsk, tools, toolRosterDeltas: rosterSeat, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedBash, shellGatedMonitor, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash });
+        const { parkAsk } = prepareParkAsk({ askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas: rosterSeat, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedTools, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef });
+        prepareGateStations({ askLane, parkAsk, tools, toolRosterDeltas: rosterSeat, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedTools, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash });
         const { microCompact, charsPerToken } = prepareContextLane({ model, deps, sessionId, runId, hostTaskId, offloadStore, microCompactKnob, harness, batchHaltRef, gitStatusRef, requestLossyRef, trimPressureRef });
         const preparedHolder = {};
         const { cacheBreakDetector, cacheFingerprint, promptOverheadTokens, readTaskFile, normalizeAttachmentPath, isDedupStubResult, recentlyReadFiles, onCompactionApplied, detectExternalChanges, listBackgroundTasks, centerCompactionCandidate, effectiveReadFaceObserved, effectiveReadDenyObserved } = prepareTurnWiring({ deps, systemPromptSeat, harnessTools, fpRef, model, epochArtifactDigestForSnapshot, promptProfile, fableMitigations, systemBlocks, thinking, spec, sessionId, turnSnapshotRef, promptManifest, charsPerToken, handsEnabled, executionEnv, attachmentRootCanonical, additionalRootsCanonical, additionalReadRootsCanonical, readDenyMatcher, resolvedReadFace, handsCwdRef, readFileStateForCheckpoint, denyNarrowingPolicy, abortController, hostTaskId, taskScope, buildAssembleInputs, centerAdoptionRef, harnessRef, epochDeclaredSections, carrierReadFace, readDenyAdditionsNormalized, preparedHolder });

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

@@ -0,0 +1,86 @@
+import type { Model } from "../../internal/llm.js";
+import type { ToolSpec } from "../types.js";
+import type { ToolFingerprintInput } from "../cache-break-detector.js";
+/**
+ * The deferral GATE (design/36): 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 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";
+/** The deferral gate's verdict — the two deferral lists, what the gate measured, and whether it opened. */
+export interface DeferralGate {
+    /** The caller's LITERAL list: `TaskSpec.deferTools` names mounted on this face, minus the inline pins.
+     *  Deferred on every request, whatever the gate says — an intentional deferral is not a size question. */
+    explicit: Set<string>;
+    /** The engine's SELF-SELECTED candidates: `ToolSpec.defer === true`, every remote-protocol name, built-ins
+     *  that declare their own `defer`, and — under `deferMode: "auto"` — every caller spec; minus the inline
+     *  pins and minus `explicit`. Deferred iff the gate opens. */
+    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. */
+    thresholdChars: number;
+    /** Whether `gated` is deferred on this request: `gatedChars ≥ thresholdChars`. */
+    open: boolean;
+}
+/**
+ * Deferral has TWO rules, and only two.
+ *
+ * ① THE CALLER'S LIST IS LITERAL. `TaskSpec.deferTools` (arriving as `callerDeferNames`, pre-filtered to
+ *    mounted wire names, built-ins included) is deferred on every request; `alwaysLoad` (`ToolSpec.alwaysLoad`,
+ *    `alwaysLoadNames`) is inlined on every request and is judged FIRST — a pinned name is in neither list
+ *    and is never measured. Neither depends on the gate: they are the deployment's stated intent.
+ *
+ * ② THE ENGINE'S OWN CANDIDATES SIT BEHIND ONE THRESHOLD GATE. The candidates are declared: explicit
+ *    `ToolSpec.defer === true` on a caller spec, every REMOTE-PROTOCOL tool name (MCP servers AND A2A peers —
+ *    the caller unions them), and `builtinDeferNames` (mounted BUILT-INS that declare their own `defer`; a
+ *    built-in ToolSpec never reaches `specs`, so its declaration arrives as a mounted name). `deferMode:
+ *    "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.
+ *
+ * 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).
+ */
+export declare function deferralGate(opts: {
+    specs: ReadonlyArray<ToolSpec>;
+    /** Every namespaced tool a remote protocol materialized for this task (MCP servers AND A2A peers —
+     *  the caller unions them). The remote-roster shape (many tools, schemas the deployment does not
+     *  control, drift between tasks) is the same for every protocol, so every protocol's names are
+     *  candidates by being remote. Only an inline pin (or the caller's own list) takes a name out. */
+    protocolToolNames: ReadonlyArray<string>;
+    /** The MOUNTED face — the tools whose full definitions the request would carry. The measure reads
+     *  each candidate's inlined size from here; a candidate absent from it weighs nothing. */
+    fullTools: ReadonlyArray<ToolFingerprintInput>;
+    /** `"auto"` widens the candidate set to every caller spec (see above). Any other value refuses. */
+    deferMode?: "auto";
+    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. */
+    callerDeferNames?: ReadonlyArray<string>;
+    /** Rule ② — mounted BUILT-INS that declare their own `defer` (the engine's declaration, not the
+     *  caller's), so they are candidates. Caller pre-filters to mounted names. */
+    builtinDeferNames?: ReadonlyArray<string>;
+    /** Rule ① — inline-pin names (`TaskSpec.alwaysLoadTools` + the MCP tools whose server declared
+     *  `_meta["anthropic/alwaysLoad"]`, caller-collected; A2A has no such per-skill declaration, so the
+     *  task-level list is a peer's only inline-keep channel): exempt from BOTH lists.
+     *  `ToolSpec.alwaysLoad` rides the specs directly and needs no entry here. */
+    alwaysLoadNames?: ReadonlyArray<string>;
+}): DeferralGate;
+/**
+ * Decide which tool names are deferred: the caller's literal list, plus the gated candidates when the gate
+ * opens. THIS CONTRACT (with {@link deferralGate}) IS THE SINGLE AUTHORITY on the deferral sources and the
+ * gate; the `TaskSpec` / `RunnerDeps` JSDoc points here.
+ */
+export declare function classifyDeferred(opts: Parameters<typeof deferralGate>[0]): Set<string>;

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

@@ -0,0 +1,57 @@
+import { DEFAULT_CHARS_PER_TOKEN } from "../../internal/harness.js";
+export const DEFER_THRESHOLD_FRACTION = 0.1;
+const CHARS_PER_TOKEN = DEFAULT_CHARS_PER_TOKEN;
+function inlinedChars(t) {
+    let schema = "";
+    try {
+        schema = JSON.stringify(t.parameters) ?? "";
+    }
+    catch {
+        schema = "";
+    }
+    return t.name.length + t.description.length + schema.length;
+}
+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.`);
+        e.code = DEFER_MODE_INVALID_CODE;
+        throw e;
+    }
+    const pinned = new Set(opts.alwaysLoadNames ?? []);
+    for (const s of opts.specs) {
+        if (s.alwaysLoad === true)
+            pinned.add(s.name);
+    }
+    const explicit = new Set();
+    for (const name of opts.callerDeferNames ?? [])
+        if (!pinned.has(name))
+            explicit.add(name);
+    const gated = new Set();
+    const select = (name) => {
+        if (!pinned.has(name) && !explicit.has(name))
+            gated.add(name);
+    };
+    for (const s of opts.specs)
+        if (s.defer === true || opts.deferMode === "auto")
+            select(s.name);
+    for (const name of opts.protocolToolNames)
+        select(name);
+    for (const name of opts.builtinDeferNames ?? [])
+        select(name);
+    let gatedChars = 0;
+    for (const t of opts.fullTools)
+        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 };
+}
+export function classifyDeferred(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;
+}

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

@@ -1,8 +1,5 @@
 import { type TSchema } from "typebox";
 import type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode } from "../../internal/harness-types.js";
-import type { Model } from "../../internal/llm.js";
-import type { ToolSpec } from "../types.js";
-import type { ToolFingerprintInput } from "../cache-break-detector.js";
 /**
  * Deferred-tool dynamic disclosure (design/36). A deployment with hundreds of tools / several MCP
  * servers can't inline every full JSON Schema into every request — turn-1 cache-creation tokens
@@ -56,39 +53,6 @@ export declare function deferHint(description: string, max?: number): string;
  * announcement, anywhere. A bare interpolation is a prompt-injection hole (council BUG, design/36).
  */
 export declare function safeName(name: string): string;
-/**
- * Decide which tool names are deferred. THIS CONTRACT IS THE SINGLE AUTHORITY on the default-mode
- * source list (TaskSpec/RunnerDeps JSDoc points here), so every arm the body implements is named:
- * deterministic by default = explicit `ToolSpec.defer === true`, plus every REMOTE-PROTOCOL tool name
- * (MCP servers AND A2A peers — most numerous / most drift-prone), plus `deferNames`, i.e. the
- * already-mounted wire names from `TaskSpec.deferTools` and from BUILT-INS that declare their own
- * `defer` (a built-in ToolSpec never reaches `specs`, so its declared deferral has to arrive here as a
- * mounted name — this is why the shared-memory pair defaults to deferred). With `deferMode: "auto"`, ADDITIONALLY
- * defer the remaining user tools when their combined inlined schema would exceed ~10% of the model's
- * context window — an explicit opt-in (council minor #6), because an implicit threshold makes the same
- * TaskSpec yield different tools[] across models/contexts. Explicit `defer` always wins — except
- * against an alwaysLoad pin (RB-400-a), which exempts a name from every deferral source.
- */
-export declare function classifyDeferred(opts: {
-    specs: ReadonlyArray<ToolSpec>;
-    /** Every namespaced tool a remote protocol materialized for this task (MCP servers AND A2A peers —
-     *  the caller unions them). The constant-defer arm is about the SHAPE of a remote roster (many tools,
-     *  schemas the deployment does not control, drift between tasks), which is the same for every protocol
-     *  in the table: naming one protocol here left the next one inlined by omission, with nobody deciding
-     *  that. Only an alwaysLoad pin exempts a name. */
-    protocolToolNames: ReadonlyArray<string>;
-    fullTools: ReadonlyArray<ToolFingerprintInput>;
-    deferMode?: "auto";
-    model: Model;
-    /** TaskSpec.deferTools — defer ALREADY-MOUNTED tools by wire name (built-ins included;
-     *  `ToolSpec.defer` only reaches caller specs). Caller pre-filters to mounted names. */
-    deferNames?: ReadonlyArray<string>;
-    /** RB-400-a — inline-pin names (`TaskSpec.alwaysLoadTools` + the MCP tools whose server declared
-     *  `_meta["anthropic/alwaysLoad"]`, caller-collected; A2A has no such per-skill declaration, so the
-     *  task-level list is a peer's only inline-keep channel): exempt from EVERY deferral source below.
-     *  `ToolSpec.alwaysLoad` rides the specs directly and needs no entry here. */
-    alwaysLoadNames?: ReadonlyArray<string>;
-}): Set<string>;
 /** Build the registry the search ranks over (deferred tools only — non-deferred are already visible). */
 export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, tools: ReadonlyArray<{
     name: string;

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

@@ -2,11 +2,8 @@ import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { defineTool, errorResult } from "../tools.js";
 import { formatZodValidationError, truncateError } from "../tool-errors.js";
-import { DEFAULT_CHARS_PER_TOKEN } from "../../internal/harness.js";
 import { toolFace } from "../tool-catalog-entries.js";
 export const TOOL_SEARCH_NAME = "ToolSearch";
-const DEFER_AUTO_FRACTION = 0.1;
-const CHARS_PER_TOKEN = DEFAULT_CHARS_PER_TOKEN;
 export const TOOL_SEARCH_DEFAULT_MAX_RESULTS = 5;
 const MAX_QUERY_RESULTS = 25;
 export const DEFERRED_NO_PROGRESS_LIMIT = 3;
@@ -19,46 +16,6 @@ export function deferHint(description, max = 120) {
 export function safeName(name) {
     return name.replace(/[\x00-\x1f<>"`]/g, "");
 }
-function inlinedChars(t) {
-    let schema = "";
-    try {
-        schema = JSON.stringify(t.parameters) ?? "";
-    }
-    catch {
-        schema = "";
-    }
-    return t.description.length + schema.length;
-}
-export function classifyDeferred(opts) {
-    const pinned = new Set(opts.alwaysLoadNames ?? []);
-    for (const s of opts.specs) {
-        if (s.alwaysLoad === true)
-            pinned.add(s.name);
-    }
-    const deferred = new Set();
-    for (const s of opts.specs) {
-        if (s.defer === true && !pinned.has(s.name))
-            deferred.add(s.name);
-    }
-    for (const name of opts.protocolToolNames)
-        if (!pinned.has(name))
-            deferred.add(name);
-    for (const name of opts.deferNames ?? [])
-        if (!pinned.has(name))
-            deferred.add(name);
-    if (opts.deferMode === "auto") {
-        const callerNames = new Set(opts.specs.map((s) => s.name));
-        const candidates = opts.fullTools.filter((t) => !deferred.has(t.name) && !pinned.has(t.name) && callerNames.has(t.name));
-        const inlineFace = opts.fullTools.filter((t) => !deferred.has(t.name));
-        const total = inlineFace.reduce((n, t) => n + inlinedChars(t), 0);
-        const window = (opts.model.contextTokens ?? opts.model.contextWindow ?? 0) * CHARS_PER_TOKEN;
-        if (window > 0 && total > DEFER_AUTO_FRACTION * window) {
-            for (const t of candidates)
-                deferred.add(t.name);
-        }
-    }
-    return deferred;
-}
 export function buildDeferredRegistry(deferred, tools) {
     const reg = new Map();
     for (const t of tools) {

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

@@ -1370,15 +1370,22 @@ export interface RunnerDeps {
         removedBytes: number;
     }) => void;
     /**
-     * Deferred-tool disclosure policy (design/36). Default (omitted): deterministic per-tool, so the same
-     * `TaskSpec` always yields the same `tools[]`. The default deferral sources are `ToolSpec.defer === true`,
-     * every REMOTE-PROTOCOL tool name (MCP **and** A2A peer tools), {@link TaskSpec.deferTools}, and built-in
-     * tools that declare their own `defer` (today the shared-memory pair) — minus anything pinned inline by
-     * `ToolSpec.alwaysLoad` / {@link TaskSpec.alwaysLoadTools}. `classifyDeferred`'s own contract is the
-     * single authority if this list ever drifts again. `"auto"`: additionally auto-defer tools when the total
-     * inlined schema size would exceed a fraction of the model's context window. Auto is an explicit opt-in
-     * (council minor #6) because an implicit threshold makes `tools[]` depend on the model/context, which
-     * callers find hard to predict; explicit `defer` flags always win regardless of this setting.
+     * Deferred-tool disclosure policy (design/36). Two rules govern deferral. ① The caller's list is
+     * literal: {@link TaskSpec.deferTools} names defer on every request, `ToolSpec.alwaysLoad` /
+     * {@link TaskSpec.alwaysLoadTools} pins inline on every request (judged first) — neither reads this
+     * knob. ② The engine's own candidates — `ToolSpec.defer === true`, every REMOTE-PROTOCOL tool name
+     * (MCP **and** A2A peer tools), and built-in tools that declare their own `defer` — sit behind ONE
+     * threshold gate, all or nothing: deferred iff their inlined size (name + description + schema; the
+     * candidate set only — the caller's list, pins and non-candidates are not measured) reaches 10% of the
+     * model's context window; below that they ship inline in full and no ToolSearch is mounted.
+     *
+     * `"auto"` is a CANDIDATE-WIDENING knob, not a second gate: it adds every caller spec — undeclared
+     * caller tools included — to the candidate set, measured and decided by the same threshold. Engine
+     * built-ins the deployment did not name are candidates under no setting. An explicit opt-in (council
+     * minor #6) because it makes `tools[]` depend on the caller roster's total weight, which a deployment
+     * with many thin tools may not want. Any other value refuses at prepare (`config.defer_mode_invalid`).
+     * `classifyDeferred` / `deferralGate` in `src/core/runner/tool-disclosure.ts` are the single authority
+     * if this text drifts.
      */
     deferMode?: "auto";
     /**

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

@@ -31,6 +31,10 @@ export type ImageInput = {
     url: string;
 };
 /** A single self-contained task with its full configuration. */
+/** The shell-gate doctrine vocabulary — {@link TaskSpec.shellGate}'s value set, and the word the engine persists on a
+ *  shell-gated ask (`RiskDescriptor.shellGateDoctrine`) and folds across a delegation chain (max-rank: `off` <
+ *  `classify` < `always`). One closed set; every seat that names a doctrine spells it through this alias. */
+export type ShellGateDoctrine = "off" | "classify" | "always";
 export interface TaskSpec {
     taskId?: string;
     /** The instruction / latest user message for this turn. */
@@ -400,6 +404,8 @@ export interface TaskSpec {
      * included — `ToolSpec.defer` only covers caller specs): wire names listed here ship as
      * lightweight placeholders (name + one-line hint, schema bytes OFF the cache prefix) and are
      * activated on demand via the injected ToolSearch (design/36 materialization — prefix untouched).
+     * This list is LITERAL — an intentional deferral, deferred on every request regardless of the
+     * deferral gate ({@link RunnerDeps.deferMode}) and not counted toward its threshold.
      * "Default-on but not exposed" = the deployment lists the tool here on requests where no
      * activation source fired (e.g. Workflow unless the user said "workflow"/"ultracode"); omitting
      * the name on a later request mounts it fully (activation = not deferring). Unknown names are
@@ -445,7 +451,7 @@ export interface TaskSpec {
      * direction; CC 220 `alwaysLoad` 对位): names listed here are NEVER deferred — not by
      * `ToolSpec.defer`, not by the MCP constant-defer arm (besides the server's own
      * `_meta["anthropic/alwaysLoad"]` declaration this list is the only channel that keeps a chosen
-     * MCP tool's full schema inlined), not by `deferTools`, not by `deferMode:"auto"`. Unknown names
+     * MCP tool's full schema inlined), not by `deferTools`, not by the deferral gate under any `deferMode`. Unknown names
      * are ignored (the valve only subtracts). Names also in `excludeTools` stay excluded (exclusion
      * wins — an unmounted tool has no schema to keep inline).
      */
@@ -862,7 +868,7 @@ export interface TaskSpec {
      * task config — a resume that omits it leaves the resumed run's SUBSEQUENT `bash` calls ungated (the approved
      * pending call itself runs once, having been adjudicated). Re-pass the same value the original task used.
      */
-    shellGate?: "off" | "always" | "classify";
+    shellGate?: ShellGateDoctrine;
     /**
      * The caller's AUTO-MODE INTENT for this task — the "user turned auto on" half of the classifier
      * arming (CC 2.1.250 polarity: auto mode is something the USER enables at the permission-mode

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

@@ -363,9 +363,12 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      *  for this tool — it is not a "threshold so low that everything offloads". */
     offloadThresholdChars?: number;
     /**
-     * Deferred disclosure (design/36): when `true`, this tool is NOT inlined with its full JSON Schema in
-     * every request. It appears as a lightweight placeholder (`{name, one-line hint, empty params}`) so
-     * the model knows it exists. Activation is a DISCLOSURE fact (has the model seen the schema?), not an
+     * Deferred disclosure (design/36): when `true`, this tool is a CANDIDATE of the engine's deferral gate.
+     * When the gate opens (the candidate set's inlined size reaching 10% of the model's context window; see
+     * {@link RunnerDeps.deferMode}) it is NOT inlined with its full JSON Schema: it appears as a lightweight
+     * placeholder (`{name, one-line hint, empty params}`) so the model knows it exists; when the gate stays
+     * shut it ships inline in full. (A caller that wants a tool deferred on every request names it in
+     * {@link TaskSpec.deferTools} — that list is literal.) Activation is a DISCLOSURE fact (has the model seen the schema?), not an
      * execution precondition: the model activates the tool via the injected ToolSearch, or by making a call
      * whose arguments already match the real parameters (see {@link TaskSpec.deferSelfResolve}, on by
      * default). Where the schema then lands depends on {@link TaskSpec.toolMaterializeStrategy} — the next
@@ -386,7 +389,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * `alwaysLoad`, declared per MCP tool via `_meta["anthropic/alwaysLoad"]`, whose `isDeferredTool`
      * checks it before every deferral arm): `true` pins this tool's full schema inline in every
      * request — it is never deferred, regardless of its own {@link defer}, {@link TaskSpec.deferTools},
-     * or `deferMode:"auto"`. The deferral sources only ever ADD; this is the explicit subtract valve.
+     * or the deferral gate. The deferral sources only ever ADD; this is the explicit subtract valve.
      * Exclusion still wins ({@link TaskSpec.excludeTools} unmounts — nothing left to keep inline).
      */
     alwaysLoad?: boolean;

package/dist/core/types.d.ts

@@ -12,7 +12,7 @@
 import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict } from "../internal/harness.js";
 import type { Model, StreamFn } from "../internal/llm.js";
 export type { ModelRef, ModelRole, RoleSpec, ModelRoles, Brain } from "./model-seat.js";
-export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec } from "./task-spec.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 { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
 export type { AgentDefinition, SkillManifest, SkillSpec } from "./agent-definition.js";

package/dist/index.d.ts

@@ -93,7 +93,7 @@ export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core
 export { mintReminderMark, isValidReminderMark, openSystemReminder, mintSystemReminder, reminderMarkDeclaration } from "./core/reminder-mint.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, CheckResult, } from "./core/property-harness.js";
-export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { bashReversibilityProbe, bashReadBoundaryProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } from "./tools/fs/index.js";
@@ -318,7 +318,7 @@ export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } f
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, ShellGateDoctrine, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";

package/dist/index.js

@@ -72,7 +72,7 @@ export { runExecGate } from "./core/exec-gate.js";
 export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core/untrusted-text.js";
 export { mintReminderMark, isValidReminderMark, openSystemReminder, mintSystemReminder, reminderMarkDeclaration } from "./core/reminder-mint.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
-export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { bashReversibilityProbe, bashReadBoundaryProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, } from "./tools/fs/index.js";

package/dist/tools/fs/fs-bash.d.ts

@@ -56,6 +56,47 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * that adds nothing the reader cannot already see.
  */
 export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
+/**
+ * The READ-BOUNDARY seat of the full shell: a `ToolSpec.reversibilityProbe` that answers exactly ONE
+ * question — does the deployment's read boundary object to where this command reads? — and nothing about
+ * the command's shape. It is the shell face of the rule every read face obeys: the structured readers
+ * (Read/Grep/Glob) refuse a deny-listed or out-of-root target; the shell reader gets a MANDATED ask for the
+ * same target. The engine installs it on Bash and Monitor whenever a real writable shell is mounted and the
+ * shellGate doctrine adds no residual-risk classifier of its own (`shellGate:"off"`, the default); under
+ * `"classify"` the doctrine installs {@link bashReversibilityProbe} instead, which composes THIS judgment
+ * with the read-only shape classifier, and under `"always"` the tier itself is the mandate and no probe runs.
+ * The boundary is therefore judged under every doctrine; the doctrine decides only what happens to the
+ * residual shell risk.
+ *
+ * The verdict, in the probe vocabulary the gate reads (`reversible` here means "the boundary raised no
+ * question — the seat vouches the call may run"):
+ *  · the boundary DECLARED an objection — a deny-listed operand, a recursive walk under the deny judge, an
+ *    operand outside the roots — ⇒ `{ reversible: false, mandated: true }` (+ the recursive-reach `cause`);
+ *  · the boundary could NOT READ where the command reads — an unexpanded glob operand (the compound face
+ *    reports it as undecided), a `~`-rooted operand with no home declared, a working-directory move the walk
+ *    cannot model — ⇒ `{ reversible: false }` (fail-closed; a plain ask, which a stored allow rule may retire —
+ *    the seat did not declare anything, it declined to guess);
+ *  · otherwise ⇒ `{ reversible: true }`. This includes every command whose SHAPE the read faces refuse whole
+ *    (an unlisted program, a redirection, a substitution, a segment that is not a reader): those shapes carry
+ *    no read-face verdict, so this seat has no question to ask — the residual is the doctrine's, and under
+ *    `"off"` the doctrine asks nothing. `run_in_background` is likewise not this seat's question (it changes
+ *    WHEN the command runs, never WHERE it reads).
+ *
+ * Reach = the read faces' reach, and nothing wider: the compound face walks the operands of a command whose
+ * every segment is a listed reader, and the bounded poll-loop face walks a loop body of listed readers. A
+ * read hidden in a shape the faces refuse whole (`cat x | <unlisted>`, `$(cat x)`, `cat $DIR/x`, a launcher
+ * `env cat x`, a path-prefixed `/bin/cat x`) is not seen here — deny-listed or out-of-root alike — exactly
+ * the shapes the `"classify"` doctrine exists to ask about. The text-level containment gate the classify
+ * seat consults on its demotion arms is deliberately not consulted here ({@link boundaryDeclared}: it may
+ * add a mandate to an ask, never originate one). The poll-loop face reports its refusal as one sentence,
+ * so the boundary's share of it is read by removing the boundary's judging seats
+ * ({@link pollLoopBoundaryVerdict}).
+ *
+ * The reader set is the engine's classify set ({@link BASH_CLASSIFY_DEFAULT_ALLOW}) — here it is NOT an
+ * auto-allow list but the set of programs whose operands the faces read; a wider set means more reads are
+ * judged, never that more runs are vouched.
+ */
+export declare function bashReadBoundaryProbe(boundary: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
  * design/199 D-6 — the FULL shell's contract id, single-sourced: both shell faces share the wire
  * name "Bash", so this id is the ONE structural discriminator between the write-capable shell and