@sema-agent/core 7.17.6 → 7.18.0

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -5,22 +5,20 @@ import { CROSS_SESSION_CLASSIFIER_RULE } from "../../agents/cross-session-envelo
 import { createRunWorkflowTool } from "../../orchestration/run-workflow-tool.js";
 import { isSelfOrchestrationActive } from "../../orchestration/workflow-script-runner.js";
 import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
-import { thinkingOffExpressible } from "../../brain/reasoning.js";
 import { autoModeArmingRecipeOf } from "../auto-mode-arming.js";
-import { AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS, AUTO_MODE_CLASSIFIER_MAX_TOKENS } from "../auto-mode-defaults.js";
 import { buildAutoModePrompt, renderAutoModeAction, renderAutoModeWindow } from "../auto-mode-prompt.js";
-import { createAutoModeDecider, createAutoModeDenialTracker } from "../auto-mode.js";
+import { autoModeClassifierFallbackOf, autoModeRoundNotAsked, createAutoModeDecider, createAutoModeDenialTracker } from "../auto-mode.js";
 import { checkpointStoreOfSeat } from "../checkpoint-seat.js";
 import { COMPLIANCE_CAPABILITIES, WEB_FETCH_TOOL_NAME, resolveComplianceDenies } from "../compliance.js";
 import { createPresentPlanTool, createEnterPlanModeTool } from "../present-plan-tool.js";
 import { resolveTaskModel } from "../roles.js";
 import { brainToRuntime } from "../runtime.js";
 import { defaultTaskRegistry } from "../task-registry.js";
-import { emitTrace } from "../trace.js";
 import { defineTool, isDefineToolProduct, rebindDefineToolCtx } from "../tools.js";
 const MOUNT_REMEDY = "author it as a plain-object ToolSpec (own `name` and `execute`), hand the defineTool product itself, or wrap a product through the supported wrapper form (a fresh object re-stamped with `stampDefineToolBrand` whose rebind re-wraps the rebound product)";
 import { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "../runtime-caps.js";
 import { derivedRouteFallsBack } from "./derived-route-fallback.js";
+import { CLASSIFIER_LOW_SEAT, CLASSIFIER_OFF_SEAT, classifierLadderRungs, classifierRoundObserver, classifierRungSeat } from "./classifier-ladder.js";
 import { REPORT_FINDINGS_TOOL_NAME, createReportBlockedTool, createReportFindingsTool } from "./synthetic-tools.js";
 function classifierReplyText(reply) {
     return reply.content
@@ -112,7 +110,7 @@ function autoModeArmReasonOf(intent, facePresent, caps, capsFaulted) {
     return { armed: true, reason: "armed" };
 }
 export async function prepareCapsAndWorkflow(input) {
-    const { spec, deps, parentSpecSeat, checkpointSeat, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf } = input;
+    const { spec, deps, parentSpecSeat, checkpointSeat, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, carrierWriteFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf } = input;
     const roster = new RosterBuilder(toolEffects);
     for (const t of spec.tools ?? []) {
         const mounted = mountCallerTool(t);
@@ -218,45 +216,45 @@ export async function prepareCapsAndWorkflow(input) {
         catch {
             classifierModel = model;
         }
-        if (await derivedRouteFallsBack({ seat: "auto-mode-classifier", derived: classifierModel, primary: model, brain: deps.brain, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, onNotice: deps.onNotice, sessionId, runId })) {
+        if (await derivedRouteFallsBack({ seat: "auto-mode-classifier", derived: classifierModel, primary: model, brain: deps.brain, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, onNotice: deps.onNotice, sessionId, runId, onBrokenPairing: autoModeClassifierFallbackOf(am.classifierFallback) === "none" ? "refuse" : "fall_back" })) {
             classifierModel = model;
         }
         const classifierLaneRule = peerLaneActive && peerSendMessageBuiltIn;
         const classifierSystemPrompt = buildAutoModePrompt(classifierLaneRule ? { ...am, crossSessionMessagesRule: CROSS_SESSION_CLASSIFIER_RULE } : am);
         const classifierRuntime = brainToRuntime(deps.brain);
-        const classifierOffSeat = { reasoning: "off", maxTokens: AUTO_MODE_CLASSIFIER_MAX_TOKENS };
-        const classifierLowSeat = { reasoning: "low", maxTokens: AUTO_MODE_CLASSIFIER_MAX_TOKENS + AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS };
-        const classifierSeat = thinkingOffExpressible(classifierModel) ? classifierOffSeat : classifierLowSeat;
+        const classifierRungs = classifierLadderRungs(am.classifierFallback, classifierModel, model);
+        const roundPrompt = new WeakMap();
         autoModeDenialTracking = createAutoModeDenialTracker(am.denialLimit);
         autoModeDecider = createAutoModeDecider({
             ...(am.timeoutMs !== undefined ? { timeoutMs: am.timeoutMs } : {}),
-            onClassified: (info) => emitTrace(deps.tracer, () => ({
-                kind: "auto_mode.classified",
-                version: 1,
-                taskId: hostTaskId,
-                toolCallId: info.toolCallId,
-                model: classifierModel.id,
-                ms: info.ms,
-                verdict: info.verdict,
-                ...(info.cause !== undefined ? { cause: info.cause } : {}),
-                ts: Date.now(),
-            })),
-            classify: async (input, signal) => {
-                const ctx = await session.buildContext();
-                const known = ctx.messages.filter((m) => !isSyntheticApiErrorMessage(m) &&
-                    (m.role === "user" || m.role === "assistant" || m.role === "toolResult"));
-                const userPrompt = renderAutoModeWindow(known, am.window) + renderAutoModeAction(input);
-                const classifierAuth = await spec.getApiKeyAndHeaders?.(classifierModel);
-                const request = (seat) => classifierRuntime.completeSimple(classifierModel, { systemPrompt: classifierSystemPrompt, messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] }, {
+            candidates: classifierRungs.map((m) => m.id),
+            onClassified: classifierRoundObserver({ tracer: deps.tracer, onNotice: deps.onNotice, taskId: hostTaskId, seatModelId: classifierModel.id, ...(sessionId !== undefined ? { sessionId } : {}), ...(runId !== undefined ? { runId } : {}) }),
+            classify: async (input, signal, rung) => {
+                const rungModel = rung !== undefined ? classifierRungs[rung.index] : undefined;
+                if (rung === undefined || rungModel === undefined) {
+                    throw new Error(`the auto-mode classifier was asked at ladder position ${JSON.stringify(rung?.index)}, which this arming did not build`);
+                }
+                let build = rung.index > 0 ? roundPrompt.get(input) : undefined;
+                if (build === undefined) {
+                    build = (async () => {
+                        const ctx = await session.buildContext();
+                        const known = ctx.messages.filter((m) => !isSyntheticApiErrorMessage(m) && (m.role === "user" || m.role === "assistant" || m.role === "toolResult"));
+                        return renderAutoModeWindow(known, am.window) + renderAutoModeAction(input);
+                    })();
+                    roundPrompt.set(input, build);
+                }
+                const userPrompt = await build.catch((e) => { throw autoModeRoundNotAsked(e); });
+                const classifierAuth = await spec.getApiKeyAndHeaders?.(rungModel);
+                const request = (seat) => classifierRuntime.completeSimple(rungModel, { systemPrompt: classifierSystemPrompt, messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] }, {
                     signal,
                     ...seat,
                     ...(classifierAuth?.apiKey !== undefined ? { apiKey: classifierAuth.apiKey } : {}),
                     ...(classifierAuth?.headers !== undefined ? { headers: classifierAuth.headers } : {}),
                 });
-                let response = await request(classifierSeat);
-                if (classifierSeat === classifierOffSeat && classifierReplyEmptyAtCap(response)) {
-                    response = await request(classifierLowSeat);
-                }
+                const rungSeat = classifierRungSeat(rungModel);
+                let response = await request(rungSeat);
+                if (rungSeat === CLASSIFIER_OFF_SEAT && classifierReplyEmptyAtCap(response))
+                    response = await request(CLASSIFIER_LOW_SEAT);
                 return classifierReplyText(response);
             },
         });
@@ -325,6 +323,7 @@ export async function prepareCapsAndWorkflow(input) {
             parentCwd: taskRootFinal,
             parentThinking: () => childThinkingSeat(undefined, deploymentSubagentThinking(runnerSelf.agentCatalog?.roles), harnessRef.current?.getThinkingLevel() ?? thinking).thinking,
             parentReadFace: () => carrierReadFace(),
+            parentWriteFace: () => carrierWriteFace(),
             parentReadDenyPatterns: () => {
                 const readDenyAdditionsNormalized = input.readDenyAdditionsNormalized();
                 return readDenyAdditionsNormalized.length > 0 ? readDenyAdditionsNormalized : undefined;

package/dist/core/runner/prepare-config-doors.d.ts

@@ -115,7 +115,7 @@ export interface PrepareConfigDoorsInput {
     /** borrowed-readonly — the caller's spec. NEVER mutated here: the per-task agents rebind returns a
      *  SHALLOW COPY on {@link PrepareConfigDoorsResult.spec} (only `tools` replaced). */
     spec: TaskSpec;
-    /** borrowed-readonly — deployment seats. Read for: readFace value screen, locked-config preflight,
+    /** borrowed-readonly — deployment seats. Read for: the two containment-face value screens, locked-config preflight,
      *  retention door, interaction-posture door (incl. `deps.onError` disclosure), usage windows,
      *  brain-call guardrail default, model/role maps. */
     deps: RunnerDeps;

package/dist/core/runner/prepare-config-doors.js

@@ -1,5 +1,5 @@
 import { resolveBrainCallGuardrailMs } from "../../brain/timeout.js";
-import { assertReadFaceValue } from "../../tools/fs/index.js";
+import { assertContainmentFaceValue } from "../../tools/fs/index.js";
 import { MICRO_COMPACT_MACHINES } from "../context-edit.js";
 import { assertNoRetiredRunnerDeps } from "./retired-runner-deps.js";
 import { resolveCheckpointStore } from "../checkpoint-store.js";
@@ -196,8 +196,10 @@ export function prepareConfigDoors(input) {
             throw e;
         }
     }
-    assertReadFaceValue(spec.readFace, "TaskSpec.readFace");
-    assertReadFaceValue(deps.readFace, "readFace (deployment seat)");
+    assertContainmentFaceValue(spec.readFace, "read", "spec");
+    assertContainmentFaceValue(deps.readFace, "read", "deps");
+    assertContainmentFaceValue(spec.writeFace, "write", "spec");
+    assertContainmentFaceValue(deps.writeFace, "write", "deps");
     const memoryDelegationEvidenceRaw = deps.memoryDelegationEvidence;
     if (memoryDelegationEvidenceRaw !== undefined && memoryDelegationEvidenceRaw !== "static-face" && memoryDelegationEvidenceRaw !== "attested-only") {
         const evidence = memoryDelegationEvidenceRaw;

package/dist/core/runner/prepare-defer-classify.d.ts

@@ -5,11 +5,10 @@ import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { AnnounceOnceSink, ToolFaceSnapshot } from "./contracts.js";
 import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareDeferClassifyInput {
-    /** borrowed-readonly — the REBOUND spec (`spec′`); only `tools` is read (the caller roster the
-     *  classifier judges: names for the full-schema filter, specs for the `defer` declarations). */
+    /** borrowed-readonly — the REBOUND spec (`spec′`); only `tools` is read (names for the full-schema filter, specs for the `defer` declarations). */
     spec: Pick<TaskSpec, "tools" | "excludeAllTools">;
-    /** borrowed-readonly — deployment deps; only `deferMode` is read (the classifier's mode knob). */
-    deps: Pick<RunnerDeps, "deferMode">;
+    /** borrowed-readonly — deps; `deferMode` (candidate widening) and `toolSearch` (rule ②'s gate) are the only seats read. */
+    deps: Pick<RunnerDeps, "deferMode" | "toolSearch">;
     /** borrowed-mutable — the shared mount array (later refs alias it; in-place contract, never
      *  re-created). Mutated here, in order: `splice` of every excluded name; element REPLACEMENT with a
      *  shallow copy for the classic-profile description swap (the caller's ToolSpec object is never
@@ -17,21 +16,17 @@ export interface PrepareDeferClassifyInput {
      *  (element replacement with the wrapped object), the disclosure mount, the MCP refresh re-splice. Since
      *  Every one of those writes is a builder verb (`unmountWhere` / `replaceAt`). */
     roster: RosterBuilder;
-    /** borrowed-readonly — the frozen task-start tool face: `exclude` (the valve), `defer` (operator
-     *  defers, exact wire names), `alwaysLoad` (the inline pins). */
+    /** borrowed-readonly — the frozen task-start tool face: `exclude` (the valve), `defer` (operator defers, exact wire names), `alwaysLoad` (the pins). */
     toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude" | "defer" | "alwaysLoad">;
-    /** borrowed-readonly — whether a real execution env is mounted (the full-shell invariant runs only
-     *  where a shell could be on the roster). */
+    /** borrowed-readonly — whether a real execution env is mounted (the full-shell invariant runs only where a shell could be on the roster). */
     handsEnabled: boolean;
-    /** borrowed-readonly — the spec-time precomputation the invariant checks the post-exclusion roster
-     *  against: a mismatch is an engine bug, thrown. */
+    /** borrowed-readonly — the spec-time precomputation the invariant checks the post-exclusion roster against: a mismatch is an engine bug, thrown. */
     fullShellReachable: boolean;
     /** borrowed-readonly — the resolved prompt profile (`classic` swaps in `descriptionClassic`). */
     promptProfile: "simple" | "classic";
     /** borrowed-readonly — the resolved model (the deferral gate's threshold reads its context window). */
     model: Model;
-    /** borrowed-readonly — the materialized MCP roster; only `tools` is read (protocol names for the
-     *  remote-roster arm; `mcpAlwaysLoad` self-declarations, losing to an explicit operator defer). */
+    /** borrowed-readonly — the materialized MCP roster; only `tools` is read (protocol names; `mcpAlwaysLoad` self-declarations lose to an operator defer). */
     mcp: Pick<MaterializedMcp, "tools">;
     /** borrowed-readonly — the materialized A2A roster; only `tools` is read (protocol names). */
     a2a: Pick<MaterializedA2a, "tools">;
@@ -39,15 +34,12 @@ export interface PrepareDeferClassifyInput {
     sharedMemoryPairMounted: boolean;
     /** borrowed-readonly — whether the engine-memory pair mounted (project-context phase). */
     memoryEnginePairMounted: boolean;
-    /** borrowed-readonly — the memory block as the project-context phase left it. The engine pair's
-     *  retraction strips the recall paragraph from it and the stripped value returns as
-     *  {@link PrepareDeferClassifyResult.memoryBlock}; the input value itself is never mutated. */
+    /** borrowed-readonly — the memory block as the project-context phase left it; the engine pair's retraction strips the recall paragraph and returns the
+     *  stripped value as {@link PrepareDeferClassifyResult.memoryBlock}. The input is never mutated. */
     memoryBlock: string | undefined;
-    /** borrowed-readonly — the exact recall-discipline segment the memory phase composed (the strip
-     *  removes THIS string, never a re-composition). */
+    /** borrowed-readonly — the exact recall-discipline segment the memory phase composed (the strip removes THIS string, never a re-composition). */
     memoryRecallSegment: string | undefined;
-    /** borrowed-readonly — the once-per-session ledger's deduplicated operator sink (a retraction is a
-     *  session-level fact, announced once). */
+    /** borrowed-readonly — the once-per-session ledger's deduplicated operator sink (a retraction is announced once per session). */
     onceLedger: AnnounceOnceSink;
     /** borrowed-readonly — the acquired session's id (operator-line context). */
     sessionId: string;
@@ -60,6 +52,8 @@ export interface PrepareDeferClassifyResult {
     /** owned — the memory block after the engine pair's retraction strip (unchanged when no retraction
      *  ran). The driver binds it under the name the prompt assembly reads. */
     memoryBlock: string | undefined;
+    /** owned — the gate policy this classification was MEASURED under; the census reports it from here, never a second reading of the seat. */
+    toolSearch: import("../tool-search-setting.js").ResolvedToolSearch;
 }
 /** The M11 phase body — prepareTask's tool-face fold + deferred classification, verbatim (module header). */
 export declare function prepareDeferClassify(input: PrepareDeferClassifyInput): PrepareDeferClassifyResult;

package/dist/core/runner/prepare-defer-classify.js

@@ -4,8 +4,9 @@ import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
 import { MEMORY_ENGINE_TOOL_NAMES } from "../memory-engine/tools.js";
 import { SHARED_MEMORY_TOOL_NAMES } from "../shared-memory/types.js";
 import { protocolOf } from "../protocol-table.js";
-import { classifyDeferred } from "./tool-defer-gate.js";
+import { classifyDeferredWithGate } from "./tool-defer-gate.js";
 import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
+import { resolveToolSearch, toolSearchSettingOf } from "../tool-search-setting.js";
 import { RosterBuilder } from "../tool-roster.js";
 function explicitlyDeferredMemoryTrio(mounted, roster, callerDeferNames) {
     return mounted ? MEMORY_ENGINE_TOOL_NAMES.filter((n) => roster.some((t) => t.name === n) && (callerDeferNames ?? []).includes(n)) : [];
@@ -45,13 +46,16 @@ export function prepareDeferClassify(input) {
     const mcpAlwaysLoadNames = mcp.tools
         .filter((t) => t.mcpAlwaysLoad === true && !(toolFaceSnapshot.defer ?? []).includes(t.name))
         .map((t) => t.name);
+    const resolvedToolSearch = resolveToolSearch(deps.toolSearch);
+    const toolSearchSeat = toolSearchSettingOf(resolvedToolSearch);
     const classifyDeferredOverFace = (face, builtinDeferNames) => {
         const mounted = new Set(face.map((t) => t.name));
-        const deferredSet = classifyDeferred({
+        const classified = classifyDeferredWithGate({
             specs: spec.tools ?? [],
             protocolToolNames,
             fullTools: face,
             deferMode: deps.deferMode,
+            toolSearch: toolSearchSeat,
             model,
             callerDeferNames: (toolFaceSnapshot.defer ?? []).filter((n) => mounted.has(n)),
             builtinDeferNames: builtinDeferNames.filter((n) => mounted.has(n)),
@@ -61,6 +65,7 @@ export function prepareDeferClassify(input) {
                 ...mcpAlwaysLoadNames,
             ],
         });
+        const deferredSet = classified.deferred;
         for (const n of [...deferredSet])
             if (!mounted.has(n))
                 deferredSet.delete(n);
@@ -105,5 +110,5 @@ export function prepareDeferClassify(input) {
     else {
         deferred = classifyDeferredOverFace(tools, []);
     }
-    return { deferred, memoryBlock };
+    return { deferred, memoryBlock, toolSearch: resolvedToolSearch };
 }

package/dist/core/runner/prepare-gate-stations.d.ts

@@ -28,12 +28,38 @@ import type { AutoModeDecider, AutoModeDenialTracker } from "../auto-mode.js";
 import { type ComplianceCapability } from "../compliance.js";
 import { type HookEnvCapabilities, type HookInvocationIdentity, type Hooks } from "../hooks.js";
 import type { ToolPolicy } from "../tool-policy.js";
+import { type GateOutcome } from "../gate-outcome.js";
 import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
 import type { CwdRef } from "../../tools/fs/fs-shared.js";
 import type { AskLane, IrreversibilityTier, ParkAsk, Prepared, ReversibilityProbes } from "./contracts.js";
 import type { StopForDenialLimit } from "./denial-limit-arms.js";
 import type { PermissionRuleLanes } from "./permission-rule-lanes.js";
 import { type ToolRosterDeltaSeat } from "../tool-roster.js";
+/**
+ * The parent-thread human-rejection boundary — judged ONCE here, from the pass's own record (CC parity:
+ * the reference CLI's reject path aborts exactly when there is no feedback and the run is not a
+ * subagent; a rejection WITH the decider's note, and every delegated child — forks included — keep the
+ * continue / adapt-or-report posture): the final block IS a person's refusal (`deniedBy: ask_resolution`
+ * and a `human_refused` settlement — not a later fold layer's deny that merely followed a human
+ * interaction), the refusal carried NO note (`settlement.note` absent — a fact composed at the refusal,
+ * never re-derived from message text), and the run is not a delegated child (the raw trusted delegation
+ * facet — the same fact that selects the refusal text's posture, so the boundary and the words the model
+ * was told always agree). Policy/hook/classifier denies and window/abort settlements never satisfy it.
+ *
+ * Returns the loop directive that settles every never-started same-batch sibling: honest
+ * known-not-executed wording plus the machine mark (`error`/`code` twin — the wire errorCode lift
+ * reads `details.code`; `details.error` is the in-band mark result consumers grep) naming the
+ * rejected call. `undefined` = no boundary (the block stands alone, current behavior).
+ */
+export declare function maybeHumanRejectionHalt(input: {
+    gate: GateOutcome | undefined;
+    isDelegatedChild: boolean;
+    toolName: string;
+    toolCallId: string;
+}): {
+    reason: string;
+    details: Record<string, unknown>;
+} | undefined;
 export interface PrepareGateStationsInput {
     /** borrowed-readonly — the in-stream ask lane, or undefined when the gate machinery is inactive (then no `tool_call`
      *  station is built). Read: `adjudicate`, `resolveAskBound`, `notifyPermissionDenied`, `notifyHookError`. */

package/dist/core/runner/prepare-gate-stations.js

@@ -23,7 +23,7 @@ function screenGateResult(result) {
     }
     return defects.length > 0 ? { defects } : { gate, defects };
 }
-function maybeHumanRejectionHalt(input) {
+export function maybeHumanRejectionHalt(input) {
     const d = input.gate?.disposition;
     const s = input.gate?.settlement;
     const bare = d?.kind === "denied" && d.deniedBy === "ask_resolution" && s?.kind === "human_refused" && s.note === undefined;

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -1,11 +1,11 @@
-import { type BeforeWriteHook, type CwdRef, type ReadDenyMatcher, type ReadFace } from "../../tools/fs/index.js";
+import { type BeforeWriteHook, type CwdRef, type ReadDenyMatcher, type ContainmentFace } from "../../tools/fs/index.js";
 import { type ReadFileState } from "../../tools/fs/safety.js";
 import type { RunnerDeps, ShellGateDoctrine, TaskSpec } from "../types.js";
 import type { Model } from "../../internal/llm.js";
-import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
+import type { AgentHarness, AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
 import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
 import type { StoredSession } from "../session.js";
-import type { IrreversibilityTier, PrepareResume, ReversibilityProbes, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+import type { IrreversibilityTier, PrepareResume, ReversibilityProbes, RunInternals, ToolFaceSnapshot, ToolProgressLane } from "./contracts.js";
 import { RosterBuilder } from "../tool-roster.js";
 /** Test seam (mirrors `__resetMalformedNoticeSeatAnnouncement`): never called by production code.
  *  Deliberately asymmetric — it resets only the console latch: the WeakSet arm needs no seam
@@ -145,16 +145,26 @@ export interface PrepareHandsReadFaceInput {
     model: Model;
     /** borrowed-readonly — the task-spec seats this phase reads, as a Pick over the SAME spec object
      *  (R-4). `tools` feeds only the band shadow check; `envFacts` only the advertised scratchpad. */
-    spec: Pick<TaskSpec, "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "handsReadOnly" | "readDenyPatterns" | "readFace" | "oneShot" | "resumeAt" | "sessionId" | "tools">;
+    spec: Pick<TaskSpec, "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "handsReadOnly" | "readDenyPatterns" | "readFace" | "writeFace" | "oneShot" | "resumeAt" | "sessionId" | "tools">;
     /** borrowed-readonly — the deployment seats this phase reads, as a Pick over the SAME deps
      *  object (R-4: `deps.onError?.()` keeps its receiver; a new deps read must widen this Pick).
      *  `readDenyBuiltinTiers`/`readDenyBuiltinExclude` are SNAPSHOTTED before the first await that
      *  precedes the toolkit compile (the caller retains these arrays by reference). */
-    deps: Pick<RunnerDeps, "onError" | "onNotice" | "tracer" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "readFace" | "permissionRuleStore" | "hands">;
+    deps: Pick<RunnerDeps, "onError" | "onNotice" | "tracer" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "readFace" | "writeFace" | "permissionRuleStore" | "hands">;
     /** borrowed-readonly — the trusted spawn-side seats the band forwards: the finished-command
      *  notification lane, the mid-flight detach hub, and the Runner's per-session
      *  read-state seats (absent on a standalone prepare ⇒ the transcript-replay rung covers alone). */
     internals: Pick<RunInternals, "onTaskNotification" | "detachHub" | "sessionReadStates"> | undefined;
+    /** borrowed-mutable — the harness seat, read LIVE by the band's queued-human-input predicate (the shell's
+     *  auto-backgrounding leg asks it mid-command). Late-bound: the band is built here, the harness later. */
+    harnessRef: {
+        current?: AgentHarness;
+    };
+    /** borrowed-mutable — the tool-progress lane's cell, read LIVE by the band's progress seat; same
+     *  late-binding contract as {@link harnessRef}. Unbound ⇒ every tick through it is a silent no-op. */
+    toolProgressRef: {
+        current?: ToolProgressLane;
+    };
     /** borrowed-readonly — ABSOLUTE paths this prepare's restore wrote, deleted,
      *  or failed to write. Every read-state seed above describes the PRE-restore tree, so these keys are
      *  dropped from the map: the engine replaced those bytes itself, and a surviving entry makes the
@@ -255,7 +265,14 @@ export interface PrepareHandsReadFaceResult {
     /** write-back (D-3 hold) — the run's RESOLVED read face where hands mount; undefined ⇔ no hands
      *  (the hands-less value lives in `handsLessResolvedFace`). The driver assigns this onto its
      *  outer `let` for the call-time closures (ctx enrichment / checkpoint mint / envFacts). */
-    resolvedReadFace: ReadFace | undefined;
+    resolvedReadFace: ContainmentFace | undefined;
+    /** write-back — the run's RESOLVED WRITE face where hands mount; undefined ⇔ no hands (the
+     *  hands-less value lives in `handsLessResolvedWriteFace`). The read seat's twin, resolved by the
+     *  SAME order on its OWN seats — the two never read each other. */
+    resolvedWriteFace: ContainmentFace | undefined;
+    /** write-back — the hands-LESS legs' resolved WRITE face (the posture is a property of the RUN,
+     *  not the mount): the delegation carriers and the checkpoint mint need it on every leg. */
+    handsLessResolvedWriteFace: ContainmentFace | undefined;
     /** write-back (D-3 hold) — the NORMALIZED deny-set additions in force (deployment ∪ task ∪
      *  resume-seed; zero-builtin compile — the persisted/carrier form, never the judged union's
      *  post-dedup remainder). Driver assigns onto its outer `let`. */
@@ -265,7 +282,7 @@ export interface PrepareHandsReadFaceResult {
     }>;
     /** write-back (D-3 hold) — the hands-LESS legs' resolved face (the read posture is a
      *  property of the RUN, not the mount). Driver assigns onto its outer `let`. */
-    handsLessResolvedFace: ReadFace | undefined;
+    handsLessResolvedFace: ContainmentFace | undefined;
     /** owned — the canonicalized write-capable extra roots (additionalDirectories + the advertised
      *  scratchpad), deduped; the driver's envFacts advertisement and attachment readers share the
      *  ARRAY identity. Settled here (no mutation after return). */

package/dist/core/runner/prepare-hands-readface.js

@@ -3,17 +3,31 @@ import { StubExecutionEnv } from "../stub-env.js";
 import { hasBackgroundShell } from "../background-shell.js";
 import { boundaryIsTheSandbox } from "../remote-env.js";
 import { defaultTaskRegistry } from "../task-registry.js";
-import { bashReadBoundaryProbe, bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, inheritSessionReadFileState, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
+import { bashReadBoundaryProbe, bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, inheritSessionReadFileState, resolveContainmentFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
 import { resolveKey, sha256 } from "../../tools/fs/safety.js";
 import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
 import { deliverEngineNotice } from "../types.js";
 import { rebaseWorkspacePath } from "./workspace-path.js";
 import { RosterBuilder } from "../tool-roster.js";
-const readFaceClampAnnouncedSinks = new WeakSet();
-let readFaceClampConsoleAnnounced = false;
+const faceClampAnnouncedSinks = { read: new WeakSet(), write: new WeakSet() };
+const faceClampConsoleAnnounced = { read: false, write: false };
+function announceDeploymentFaceClamp(kind, sink) {
+    if (typeof sink === "function") {
+        if (faceClampAnnouncedSinks[kind].has(sink))
+            return;
+        faceClampAnnouncedSinks[kind].add(sink);
+    }
+    else {
+        if (faceClampConsoleAnnounced[kind])
+            return;
+        faceClampConsoleAnnounced[kind] = true;
+    }
+    deliverEngineNotice(sink, deploymentFaceClampNotice(kind));
+}
 export function __resetReadFaceClampAnnouncement() {
-    readFaceClampConsoleAnnounced = false;
+    faceClampConsoleAnnounced.read = false;
+    faceClampConsoleAnnounced.write = false;
 }
 export class SessionReadFileStates {
     seats = new Map();
@@ -82,17 +96,29 @@ export function resolveHandsLessReadFace(input) {
     assertStringArraySeat(deps.readDenyPatterns, "RunnerDeps.readDenyPatterns", "compiler-owned");
     assertStringArraySeat(spec.readDenyPatterns, "TaskSpec.readDenyPatterns", "compiler-owned");
     let handsLessResolvedFace;
+    let handsLessResolvedWriteFace;
     let readDenyAdditionsNormalized = [];
     {
-        const liveFace = resolveReadFace({
-            specReadFace: spec.readFace,
-            depsReadFace: deps.readFace,
+        const liveFace = resolveContainmentFace({
+            kind: "read",
+            specFace: spec.readFace,
+            depsFace: deps.readFace,
             readOnlyMount: spec.handsReadOnly === true,
             orgGoverned: deps.permissionRuleStore?.partitions.org === true,
             fullShellReachable,
         });
         const seed = resume?.seed.readFace;
         handsLessResolvedFace = resume !== undefined && (seed === undefined || seed.face === "roots") ? "roots" : liveFace;
+        const liveWriteFace = resolveContainmentFace({
+            kind: "write",
+            specFace: spec.writeFace,
+            depsFace: deps.writeFace,
+            readOnlyMount: spec.handsReadOnly === true,
+            orgGoverned: deps.permissionRuleStore?.partitions.org === true,
+            fullShellReachable,
+        });
+        const seedWrite = resume?.seed.writeFace;
+        handsLessResolvedWriteFace = resume !== undefined && (seedWrite === undefined || seedWrite.face === "roots") ? "roots" : liveWriteFace;
         const denyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seed?.denyEntries ?? [])];
         resolveReadDenyBuiltins({
             ...(deps.readDenyBuiltinTiers !== undefined ? { tiers: deps.readDenyBuiltinTiers } : {}),
@@ -111,8 +137,10 @@ export function resolveHandsLessReadFace(input) {
         rebaseWsPath: (p) => p,
         backgroundTaskToolsActive: false,
         resolvedReadFace: undefined,
+        resolvedWriteFace: undefined,
         readDenyAdditionsNormalized,
         handsLessResolvedFace,
+        handsLessResolvedWriteFace,
         additionalRootsCanonical: [],
         additionalReadRootsCanonical: [],
         attachmentRootCanonical: undefined,
@@ -138,8 +166,10 @@ export async function prepareHandsMount(input) {
     let rebaseWsPath = (p) => p;
     let backgroundTaskToolsActive = false;
     let resolvedReadFace;
+    let resolvedWriteFace;
     let readDenyAdditionsNormalized = [];
     let handsLessResolvedFace;
+    const handsLessResolvedWriteFace = undefined;
     const shellGatedTools = new Set();
     const additionalRootsCanonical = [];
     const additionalReadRootsCanonical = [];
@@ -218,30 +248,31 @@ export async function prepareHandsMount(input) {
         };
         readDenyMatcher = compileReadDeny(readDenyAdditions, "readDenyPatterns", readDenyBuiltinCfg);
         readDenyAdditionsNormalized = compileReadDeny(readDenyAdditions, "readDenyPatterns", { tiers: [] }).entries;
-        let liveReadFace = resolveReadFace({
-            specReadFace: spec.readFace,
-            depsReadFace: deps.readFace,
+        let liveReadFace = resolveContainmentFace({
+            kind: "read",
+            specFace: spec.readFace,
+            depsFace: deps.readFace,
             readOnlyMount: handsReadOnly,
             orgGoverned: deps.permissionRuleStore?.partitions.org === true,
             fullShellReachable,
-            onDeploymentClamp: () => {
-                const sink = deps.onNotice;
-                if (typeof sink === "function") {
-                    if (readFaceClampAnnouncedSinks.has(sink))
-                        return;
-                    readFaceClampAnnouncedSinks.add(sink);
-                }
-                else {
-                    if (readFaceClampConsoleAnnounced)
-                        return;
-                    readFaceClampConsoleAnnounced = true;
-                }
-                deliverEngineNotice(sink, deploymentReadFaceClampNotice());
-            },
+            onDeploymentClamp: () => announceDeploymentFaceClamp("read", deps.onNotice),
         });
         if (resume !== undefined && (seedReadFaceSection === undefined || seedReadFaceSection.face === "roots"))
             liveReadFace = "roots";
         resolvedReadFace = liveReadFace;
+        let liveWriteFace = resolveContainmentFace({
+            kind: "write",
+            specFace: spec.writeFace,
+            depsFace: deps.writeFace,
+            readOnlyMount: handsReadOnly,
+            orgGoverned: deps.permissionRuleStore?.partitions.org === true,
+            fullShellReachable,
+            onDeploymentClamp: () => announceDeploymentFaceClamp("write", deps.onNotice),
+        });
+        const seedWriteFaceSection = resume?.seed.writeFace;
+        if (resume !== undefined && (seedWriteFaceSection === undefined || seedWriteFaceSection.face === "roots"))
+            liveWriteFace = "roots";
+        resolvedWriteFace = liveWriteFace;
         const sessionSeats = input.internals?.sessionReadStates;
         let seatLeafId;
         try {
@@ -308,6 +339,7 @@ export async function prepareHandsMount(input) {
             ...(readDenyBuiltinCfg.tiers !== undefined ? { readDenyBuiltinTiers: readDenyBuiltinCfg.tiers } : {}),
             ...(readDenyBuiltinCfg.exclude !== undefined ? { readDenyBuiltinExclude: readDenyBuiltinCfg.exclude } : {}),
             readFace: liveReadFace,
+            writeFace: liveWriteFace,
             reminderMark: input.reminderMark,
             reminderDisclosureCounts: input.reminderDisclosureCounts,
             ...(input.trackFileEdit !== undefined ? { trackFileEdit: input.trackFileEdit } : {}),
@@ -323,6 +355,8 @@ export async function prepareHandsMount(input) {
             ...(sessionId !== undefined ? { sessionId } : {}),
             ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
             ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
+            onToolProgress: (body) => input.toolProgressRef.current?.emit(body),
+            queuedHumanInput: () => input.harnessRef.current?.hasPendingUserInput() === true,
             ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
             pdfModelCapabilities: pdfModelCapabilitiesOf(model),
             ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
@@ -386,6 +420,8 @@ export async function prepareHandsMount(input) {
         rebaseWsPath,
         backgroundTaskToolsActive,
         resolvedReadFace,
+        resolvedWriteFace,
+        handsLessResolvedWriteFace,
         readDenyAdditionsNormalized,
         handsLessResolvedFace,
         additionalRootsCanonical,

package/dist/core/runner/prepare-inherited-gate.d.ts

@@ -32,7 +32,7 @@ import type { SubagentWorktreeIsolation } from "../../agents/subagent.js";
 import { forkGovernanceDenial } from "../../agents/subagent.js";
 import type { SubagentRetainLedger } from "../../agents/retain-ledger.js";
 import type { PromptEpochArtifact } from "../../prompt-assembly/artifact.js";
-import type { ReadFace } from "../../tools/fs/index.js";
+import type { ContainmentFace } from "../../tools/fs/index.js";
 import type { AutoModeArmingRecipe } from "../auto-mode-arming.js";
 import type { AutoModeDecider, AutoModeDenialTracker } from "../auto-mode.js";
 import { type OnQuestion } from "../ask-question.js";
@@ -159,14 +159,18 @@ export interface PrepareInheritedGateInput {
     /** borrowed-readonly — LATE-BOUND: the observers grant (ctx `observersAllowed`, present only when explicitly granted). */
     observersActive: () => boolean;
     /** borrowed-readonly — LATE-BOUND: the hands mount's resolved read face (undefined until/unless hands mount). */
-    resolvedReadFace: () => ReadFace | undefined;
+    resolvedReadFace: () => ContainmentFace | undefined;
+    /** borrowed-readonly — LATE-BOUND: the hands mount's resolved WRITE face (the read seat's twin). */
+    resolvedWriteFace: () => ContainmentFace | undefined;
     /** borrowed-readonly — LATE-BOUND: the normalized deny additions in force (empty until the hands mount resolves them). */
     readDenyAdditionsNormalized: () => ReadonlyArray<{
         pattern: string;
         caseSensitive: boolean;
     }>;
     /** borrowed-readonly — LATE-BOUND: the hands-less legs' resolved face (the carrier's second source). */
-    handsLessResolvedFace: () => ReadFace | undefined;
+    handsLessResolvedFace: () => ContainmentFace | undefined;
+    /** borrowed-readonly — LATE-BOUND: the hands-less legs' resolved WRITE face (same second source, write seat). */
+    handsLessResolvedWriteFace: () => ContainmentFace | undefined;
     /** borrowed-readonly — LATE-BOUND: the adopted center artifact (ctx `centerArtifactDigest` / `centerSourceRevision`). */
     centerAdoption: () => {
         artifact: PromptEpochArtifact;
@@ -230,6 +234,13 @@ export interface PrepareInheritedGateResult {
     } | undefined;
     /** owned — the face stamp predicate (`faceCheckpointSection() !== undefined`). */
     faceCheckpointState: () => boolean;
+    /** owned — the WRITE-face checkpoint section builder: written ONLY for a non-default (open) write
+     *  posture, so an absent section IS "roots" on every reader, including an engine that predates the
+     *  seat. No version stamp rides it — dropping the section can only ever make a resume STRICTER
+     *  (the opposite direction from the read section, whose deny additions a blind reader would lose). */
+    writeFaceCheckpointSection: () => {
+        face: "open" | "roots";
+    } | undefined;
     /** owned — the F-012 stamp predicate (opaque constraints present ∨ seed frozen chain ∨ provenance-armed). */
     f012CheckpointState: () => boolean;
     /** owned — the FROZEN approver seat (spec over deps) every station of this leg and its children's chain resolve at. */
@@ -259,7 +270,9 @@ export interface PrepareInheritedGateResult {
     /** owned — chain assembly SINGLE SITE: upstream chain + this task's own contribution, called by delegation tools at spawn. */
     inheritedGateForChildren: () => InheritedGate;
     /** owned — the ONE carrier expression both delegation mounts consume (resolved face ?? hands-less face). */
-    carrierReadFace: () => ReadFace | undefined;
+    carrierReadFace: () => ContainmentFace | undefined;
+    /** owned — the same expression on the WRITE seat. */
+    carrierWriteFace: () => ContainmentFace | undefined;
     /** owned — the full shell's structural reachability from spec-time facts. */
     fullShellReachable: boolean;
     /** borrowed-mutable — the gate's typed stop seat (`Prepared.gateStopRef`). Writers: `stopForDenialLimit` only. */