@sema-agent/core 7.17.7 → 7.18.0

package/dist/tools/fs/containment-face.d.ts

@@ -0,0 +1,89 @@
+/** A containment-face state. `"roots"` = the containment judgment runs. `"open"` = the containment
+ *  step is skipped (canonicalization, the deny/sensitive sets, the UNC out-of-set refusal and the
+ *  type gates all still run). One type for both seats: the two faces differ in WHICH band consults
+ *  them, never in what the word means. */
+export type ContainmentFace = "open" | "roots";
+/** Which band a face governs. Selects the seat spellings and the error codes below — never the
+ *  resolution ORDER, which is one body shared by both. */
+export type ContainmentFaceKind = "read" | "write";
+/** Which layer a seat belongs to. The SPELLING is derived from (kind, layer), never re-typed at a
+ *  call site: three doors screen the same two seats, and the value gate's message is the only place
+ *  a deployment reads the seat's name back. */
+export type ContainmentFaceLayer = "spec" | "deps";
+/** The seat spelling for a (kind, layer) pair — single-sourced from {@link FACE_DIALECT}. */
+export declare function containmentFaceSeatName(kind: ContainmentFaceKind, layer: ContainmentFaceLayer): string;
+/** Loud value gate: a containment-face seat carries exactly "open" | "roots" — anything else (case
+ *  variants, truthy garbage) refuses at wiring time, never folds to a default. Exported
+ *  module-internally (not on the package surface) so prepare's unconditional config-guard leg can
+ *  screen the seats on runs that never mount hands. The resolver itself also runs on every hands-less
+ *  leg; this screen still fires first, so a garbage value refuses before any leg-shape branching. */
+export declare function assertContainmentFaceValue(v: unknown, kind: ContainmentFaceKind, layer: ContainmentFaceLayer): ContainmentFace | undefined;
+/** Inputs to {@link resolveContainmentFace} — all structural/declaration facts, never permission modes
+ *  (a deliberate axis separation: this shape carries facts, not verdicts). */
+export interface ContainmentFaceInputs {
+    /** Which face is being resolved. Selects the seat spellings and the mint codes; the ORDER below is
+     *  one body, identical for both. */
+    kind: ContainmentFaceKind;
+    /** TaskSpec.readFace / TaskSpec.writeFace (raw — validated here). The TASK layer: may only tighten
+     *  under governance. */
+    specFace?: unknown;
+    /** RunnerDeps / HandsToolkitOptions seat of the same face (raw) — the DEPLOYMENT's own declaration. */
+    depsFace?: unknown;
+    /** The verifier read-only mount (`handsReadOnly` / toolkit `readOnly`): for the read face its
+     *  containment is a LOAD-BEARING wall (bash_readonly is genuinely confined by it); for the write
+     *  face it is the absence of the band entirely. Neither is openable. */
+    readOnlyMount: boolean;
+    /** Org governance declared (`RunnerDeps.permissionRuleStore.partitions.org === true`): default roots; the task layer
+     *  may not open (tighten-only under governance; the deps layer, being the deployment's own
+     *  declaration, still may). */
+    orgGoverned: boolean;
+    /** Is the FULL shell (`core.bash@1`) structurally reachable on this mount? Computed BEFORE
+     *  tool-band assembly from spec-time facts (env kind / handsReadOnly / Bash exclusion — every
+     *  exclusion source is spec-time-frozen, so this is always computable). When false, the roots fence
+     *  is the ONLY boundary this face has, so no IMPLICIT default may open it; an EXPLICIT "open" on
+     *  either seat still wins (row 4 of the order is a default, not a clamp). */
+    fullShellReachable: boolean;
+    /** Observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
+     *  (readOnly mount + deps "open" + NO task seat). Fired exactly when the deps declaration was the
+     *  deciding seat and the mount overrode it — not when a task-level "roots" pinned the same value
+     *  anyway (the mount changed nothing there, and announcing it would claim a false cause), and
+     *  never on the throw rows (those are already loud). The resolver stays the single owner of the
+     *  clamp predicate; stations own delivery/dedup ({@link deploymentFaceClampNotice}). */
+    onDeploymentClamp?: () => void;
+}
+/**
+ * The ONE resolution order, first hit wins — ONE body for BOTH faces. prepare-task AND
+ * createHandsToolkit both call it, once per face, so a library-direct mount gets identical validation
+ * and identical defaults on each seat.
+ *
+ *  1. read-only (verifier) mount → ROOTS; an explicit "open" on the TASK seat is a genuine
+ *     per-call CONTRADICTION and refuses loudly (never silently pick a side). An "open" on the
+ *     DEPLOYMENT seat alone is a deployment-wide default, not a per-task assertion — it silently
+ *     CLAMPS to roots (stricter-wins), the same seat distinction row 2 draws for org governance.
+ *  2. org-governed: the task seat's "open" refuses (task layer only tightens); deps "open" wins;
+ *     otherwise ROOTS.
+ *  3. explicit seat: spec ?? deps.
+ *  4. bash-less mount: ROOTS (the fence is the only boundary there — "the fence guards nothing bash
+ *     reaches anyway" does not hold, so no implicit default may open it).
+ *  5. default: ROOTS — the engine never opens implicitly.
+ *
+ * @contract fs.containment_face.seat_independence — the two containment seats never read each other:
+ * each band passes its OWN resolved value into the shared containment step, a seat nobody declared
+ * resolves to "roots" on its own, and no gate other than that step is touched by either word. A
+ * deployment that wants both bands open declares both.
+ */
+export declare function resolveContainmentFace(i: ContainmentFaceInputs): ContainmentFace;
+/**
+ * The ONE text of a face's deployment-clamp announcement (`config.<face>_face_deployment_clamped`).
+ * Both stations deliver THIS object through their own `deliverEngineNotice` call (prepare-task with
+ * the `RunnerDeps.onNotice` seat, once per notice sink — the sink, not the deps object, because the
+ * Runner rebuilds its deps; `createHandsToolkit` with its band-local `HandsToolkitOptions.onNotice`
+ * seat — toolkit creation is itself the one-per-mount boot moment, and an absent seat prints the
+ * same line via `console.warn`). Built here, import-free, so the message can never fork between
+ * the stations OR between the two faces.
+ */
+export declare function deploymentFaceClampNotice(kind: ContainmentFaceKind): {
+    code: string;
+    message: string;
+    detail: Record<string, unknown>;
+};

package/dist/tools/fs/containment-face.js

@@ -0,0 +1,81 @@
+import { describeRejectedValue } from "../../core/tool-search-setting.js";
+const FACE_DIALECT = {
+    read: {
+        key: "readFace",
+        specSeat: "TaskSpec.readFace",
+        depsSeat: "readFace (deployment seat)",
+        depsOwnKey: "RunnerDeps.readFace",
+        noun: "open read face",
+        invalidCode: "config.read_face_invalid",
+        readOnlyConflictCode: "config.read_face_readonly_conflict",
+        orgEscalationCode: "config.read_face_org_task_escalation",
+        readOnlyWhy: `that mount's containment is load-bearing (its read-only shell face is confined by it) and is never openable.`,
+        clampWhy: `the mount's containment is load-bearing and never openable`,
+    },
+    write: {
+        key: "writeFace",
+        specSeat: "TaskSpec.writeFace",
+        depsSeat: "writeFace (deployment seat)",
+        depsOwnKey: "RunnerDeps.writeFace",
+        noun: "open write face",
+        invalidCode: "config.write_face_invalid",
+        readOnlyConflictCode: "config.write_face_readonly_conflict",
+        orgEscalationCode: "config.write_face_org_task_escalation",
+        readOnlyWhy: `that mount carries no write faces at all (the hand band's write half does not mount on it), so an open write face declares a posture for tools this call does not have.`,
+        clampWhy: `that mount carries no write faces for it to widen`,
+    },
+};
+export function containmentFaceSeatName(kind, layer) {
+    const d = FACE_DIALECT[kind];
+    return layer === "spec" ? d.specSeat : d.depsSeat;
+}
+export function assertContainmentFaceValue(v, kind, layer) {
+    if (v === undefined)
+        return undefined;
+    if (v === "open" || v === "roots")
+        return v;
+    const d = FACE_DIALECT[kind];
+    const e = new Error(`${containmentFaceSeatName(kind, layer)}: invalid ${d.key} value ${describeRejectedValue(v)} — expected "open" or "roots" (bad values refuse loudly; nothing falls back to a default).`);
+    e.code = d.invalidCode;
+    throw e;
+}
+export function resolveContainmentFace(i) {
+    const d = FACE_DIALECT[i.kind];
+    const spec = assertContainmentFaceValue(i.specFace, i.kind, "spec");
+    const deps = assertContainmentFaceValue(i.depsFace, i.kind, "deps");
+    if (i.readOnlyMount) {
+        if (spec === "open") {
+            const e = new Error(`${d.key}: "open" contradicts the read-only (verifier) mount — ${d.readOnlyWhy} Drop the ${d.key} declaration or the readOnly mount.`);
+            e.code = d.readOnlyConflictCode;
+            throw e;
+        }
+        if (deps === "open" && spec === undefined)
+            i.onDeploymentClamp?.();
+        return "roots";
+    }
+    if (i.orgGoverned) {
+        if (spec === "open") {
+            const e = new Error(`${d.specSeat}: "open" is refused under organization governance — the task layer may only tighten (set ${d.depsOwnKey}: "open" if the DEPLOYMENT declares the ${d.noun}).`);
+            e.code = d.orgEscalationCode;
+            throw e;
+        }
+        if (spec === "roots")
+            return "roots";
+        return deps ?? "roots";
+    }
+    if (spec !== undefined)
+        return spec;
+    if (deps !== undefined)
+        return deps;
+    if (!i.fullShellReachable)
+        return "roots";
+    return "roots";
+}
+export function deploymentFaceClampNotice(kind) {
+    const d = FACE_DIALECT[kind];
+    const message = `${d.depsSeat}: the deployment-wide "open" declaration is not in force on this read-only (verifier) mount — clamped to "roots" (stricter-wins: ${d.clampWhy}). Other mounts still honor "open".`;
+    const detail = { seat: d.depsSeat, declared: "open", inForce: "roots", cause: "read_only_mount" };
+    return kind === "read"
+        ? { code: "config.read_face_deployment_clamped", message, detail }
+        : { code: "config.write_face_deployment_clamped", message, detail };
+}

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

@@ -115,7 +115,10 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  * on the filesystem, and a target that leaves the roots only after a symlink is followed is REFUSED —
  * refused rather than asked, because by then the approval step is behind the call (see `createBashTool`'s
  * `readBoundary` option). The leg runs where an environment can resolve a link locally; a remote adapter
- * keeps the textual answer alone.
+ * keeps the textual answer alone. A program FILE named in the slot of a verb this floor has no row for
+ * (`awk -f prog.awk`, `jq -f filter.jq`, `python3 script.py`) is judged as the in-root operand it is, and the
+ * program inside it is text nobody here parsed — vouched as any in-root operand is, which is the floor's
+ * stated reach, not a hole in the sandbox.
  */
 export declare function bashReadBoundaryProbe(boundary: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
@@ -131,6 +134,16 @@ export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
  *  (CC `cLp`). Exported for its unit tests. */
 export declare function bashExitOneInterpretation(command: string): string | undefined;
 export declare function canAutoBackground(command: string, depth?: number): boolean;
+/** One observation of a running command, handed to {@link runShell}'s caller once per
+ *  {@link TOOL_PROGRESS_BOUND}.intervalMs. NO clock: how long the call has been running is the RUN's fact,
+ *  not this leg's — the two producers of a progress frame do not start their clocks at the same instant, so
+ *  the lane that mints the frame owns the origin. The output trio rides or stays away TOGETHER, and only
+ *  when the environment has actually streamed something — see the frame's own absence law. */
+export interface RunningShellTick {
+    output?: string;
+    totalLines?: number;
+    totalBytes?: number;
+}
 /**
  * `bash` (effect:write) — a full shell. ⚠️ It runs with `rootCanonical` as the initial cwd but is NOT
  * sandboxed: a command can `cd` out, read/write/delete any path the process can reach, and use the
@@ -169,8 +182,35 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      * `canAutoBackground`-eligible command it never expected to survive its timeout started surviving
      * it). A deployment that wants the CC-parity behavior sets this explicitly; sema's own default
      * Runner wiring currently does NOT set it, so this feature ships INERT until a caller opts in.
+     *
+     * IT ARMS TWO TRIGGERS, not one — the name is older than the second. Both are the engine deciding
+     * to adopt a running command instead of ending it, both take the same adoption chain, and both are
+     * gated on the same eligibility read of this command's text (`canAutoBackground`): (1) the command's
+     * OWN timeout fires, and (2) a person's input is waiting for the turn boundary while this command
+     * still runs (see {@link queuedHumanInput}). A deployment that opted in for one has opted in for
+     * both; there is deliberately no second knob, because "may this command be moved to the background
+     * by the engine" is one question and answering it twice is how the two triggers would drift apart.
      */
     autoBackgroundOnTimeout?: boolean;
+    /**
+     * The run's tool-progress sink: one call per liveness tick of a running foreground command (about
+     * once a second), minted into a `tool_progress` frame by whoever wired this. Runner-wired; a
+     * standalone toolkit build leaves it absent, and the execute leg then opens no streaming callbacks
+     * at all — its `env.exec` options are byte-identical to what they were before this seat existed.
+     */
+    onToolProgress?: (body: import("../../core/runner/contracts.js").ToolProgressBody) => void;
+    /**
+     * Is a PERSON's input waiting for this run's next turn boundary? Read on each liveness tick of a
+     * running foreground command: `true` on an {@link autoBackgroundOnTimeout}-armed command moves that
+     * command into the background (through the SAME detach verb ctrl+b fires) so the message is
+     * delivered this turn instead of after the command. CC 2.1.259 `backgroundedToDeliverMessage`.
+     *
+     * The predicate is the HARNESS's own accepted-but-unserved account and deliberately counts only what
+     * a PERSON sent: an engine-authored reminder is not somebody waiting, and stepping a build aside for
+     * one would fire on nearly every long command. Absent ⇒ nothing is ever auto-backgrounded for a
+     * message (the pre-seat behavior), which is also what a standalone toolkit build gets.
+     */
+    queuedHumanInput?: () => boolean;
     /**
      * Mirrors {@link import("../../core/types.js").TaskSpec.oneShot}: this run has no later
      * turn for an async background notification to land in (a headless `-p` process exits once the
@@ -253,6 +293,11 @@ export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical:
      *  canonical). A read this deployment already sanctions for Read/Grep/Glob is equally sanctioned
      *  here — the two faces must not disagree about which directories exist for this session. */
     additionalRoots?: readonly string[];
+    /** The run's tool-progress sink — the SAME seat the full shell leg takes, for the same reason its
+     *  two neighbours above are shared: both foreground legs run through `runShell`, so a long command
+     *  must breathe on both or a person watching one of them is told nothing. This face has no detach
+     *  chain, so it ticks and never auto-backgrounds. Absent ⇒ no streaming callbacks, byte-unchanged. */
+    onToolProgress?: (body: import("../../core/runner/contracts.js").ToolProgressBody) => void;
 }): AgentTool;
 /**
  * `TaskOutput` — read a background shell's NEW output

package/dist/tools/fs/fs-bash.js

@@ -1,7 +1,9 @@
+import { randomBytes } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { defaultTaskRegistry } from "../../core/task-registry.js";
 import { accountDroppedBytes, spoolDropNote } from "../../core/task-registry-shared.js";
+import { RollingTailBuffer } from "../../core/exec-output-tail.js";
 import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, ENV_DIRECT_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "../../core/task-tool-shape.js";
 import { hasBackgroundShell } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
@@ -349,27 +351,142 @@ function msTimeoutToRequestedSec(timeoutMs) {
         return undefined;
     return Math.max(1, Math.round(timeoutMs / 1000));
 }
-async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, cwdRef, detach, readOnly, containmentRoots) {
+const TOOL_PROGRESS_BOUND = Object.freeze({ intervalMs: 1_000, tailLines: 20, tailMaxBytes: 16 * 1024 });
+function lastLines(text, n) {
+    const body = text.endsWith("\n") ? text.slice(0, -1) : text;
+    const lines = body.split("\n");
+    return lines.length <= n ? body : lines.slice(-n).join("\n");
+}
+const EPILOGUE_HOLD_MAX_CHARS = 4096;
+function createEpilogueFilter(marker) {
+    let held = "";
+    let inside = false;
+    return (chunk) => {
+        let buf = held + chunk;
+        held = "";
+        let out = "";
+        for (;;) {
+            if (inside) {
+                const close = buf.indexOf(marker);
+                if (close === -1)
+                    break;
+                buf = buf.slice(close + marker.length);
+                inside = false;
+                continue;
+            }
+            const open = buf.indexOf(marker);
+            if (open === -1)
+                break;
+            out += buf.slice(0, open);
+            buf = buf.slice(open + marker.length);
+            inside = true;
+        }
+        if (inside) {
+            if (buf.length > EPILOGUE_HOLD_MAX_CHARS) {
+                inside = false;
+                return out + marker + buf;
+            }
+            held = buf;
+            return out;
+        }
+        for (let n = Math.min(marker.length - 1, buf.length); n > 0; n--) {
+            if (buf.endsWith(marker.slice(0, n))) {
+                held = buf.slice(buf.length - n);
+                return out + buf.slice(0, buf.length - n);
+            }
+        }
+        return out + buf;
+    };
+}
+function readCwdEpilogue(stderr, marker) {
+    let out = "";
+    let rest = stderr;
+    let cwd;
+    for (;;) {
+        const open = rest.indexOf(marker);
+        if (open === -1)
+            break;
+        const close = rest.indexOf(marker, open + marker.length);
+        if (close === -1)
+            break;
+        out += rest.slice(0, open);
+        cwd = rest.slice(open + marker.length, close);
+        rest = rest.slice(close + marker.length);
+    }
+    return { stderr: out + rest, cwd };
+}
+function describeSafely(sink, body) {
+    if (sink === undefined)
+        return;
+    try {
+        const returned = sink(body);
+        if (typeof returned?.then === "function")
+            void returned.then(undefined, () => { });
+    }
+    catch {
+    }
+}
+function startLivenessTicks(onTick, filterStderr) {
+    const tail = new RollingTailBuffer(TOOL_PROGRESS_BOUND.tailMaxBytes);
+    let totalBytes = 0;
+    let totalLines = 0;
+    let cached;
+    const feed = (chunk) => {
+        if (chunk === "")
+            return;
+        const bytes = Buffer.from(chunk, "utf8");
+        totalBytes += bytes.length;
+        totalLines += chunk.split("\n").length - 1;
+        tail.push(bytes);
+    };
+    const describeTo = (t) => describeSafely(onTick, t);
+    const tick = () => {
+        if (totalBytes === 0) {
+            describeTo({});
+            return;
+        }
+        if (cached?.atBytes !== totalBytes)
+            cached = { atBytes: totalBytes, text: lastLines(tail.result().text, TOOL_PROGRESS_BOUND.tailLines) };
+        describeTo({ output: cached.text, totalLines, totalBytes });
+    };
+    const timer = setInterval(tick, TOOL_PROGRESS_BOUND.intervalMs);
+    timer.unref?.();
+    return {
+        onStdout: feed,
+        onStderr: filterStderr === undefined ? feed : (chunk) => feed(filterStderr(chunk)),
+        stop: () => clearInterval(timer),
+    };
+}
+async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, cwdRef, detach, readOnly, containmentRoots, onTick) {
     const requestedSec = Math.max(1, Math.floor(timeoutSec ?? caps.defaultSec));
     let timeout = Math.min(caps.maxSec, requestedSec);
     const cappedByMaxTimeout = requestedSec > caps.maxSec;
     const effectiveCwd = cwdRef ? cwdRef.current : cwd;
+    const cwdMarker = cwdRef ? `${CWD_SENTINEL}${randomBytes(8).toString("hex")}` : CWD_SENTINEL;
     const toRun = cwdRef
-        ? `${command}\n__cc_rc=$?; printf '%s%s%s' '${CWD_SENTINEL}' "$(pwd)" '${CWD_SENTINEL}' 1>&2; exit $__cc_rc`
+        ? `${command}\n__cc_rc=$?\n{ set +vx; } 2>/dev/null\nprintf '%s%s%s' '${cwdMarker}' "$(pwd)" '${cwdMarker}' 1>&2\nexit $__cc_rc`
         : command;
     const execEnv = cwdRef ? { env: { PWD: effectiveCwd } } : undefined;
-    const res = await env.exec(toRun, {
-        cwd: effectiveCwd,
-        timeout,
-        abortSignal: signal,
-        ...execEnv,
-        ...(detach
-            ? {
-                detachSignal: detach.signal,
-                autoBackgroundOnTimeout: detach.autoBackgroundEligible === true,
-            }
-            : {}),
-    });
+    const live = onTick === undefined ? undefined : startLivenessTicks(onTick, cwdRef ? createEpilogueFilter(cwdMarker) : undefined);
+    let res;
+    try {
+        res = await env.exec(toRun, {
+            cwd: effectiveCwd,
+            timeout,
+            abortSignal: signal,
+            ...execEnv,
+            ...(live !== undefined ? { onStdout: live.onStdout, onStderr: live.onStderr } : {}),
+            ...(detach
+                ? {
+                    detachSignal: detach.signal,
+                    autoBackgroundOnTimeout: detach.autoBackgroundEligible === true,
+                }
+                : {}),
+        });
+    }
+    finally {
+        live?.stop();
+    }
     if (!res.ok) {
         if (res.error.code === "spawn_error" || res.error.code === "shell_unavailable") {
             const diagnosis = await diagnoseDeadCwd(env, toolName, effectiveCwd, cwd, cwdRef);
@@ -461,10 +578,10 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
     let { stderr } = res.value;
     const { stdout, exitCode } = res.value;
     if (cwdRef) {
-        const m = stderr.match(new RegExp(`${CWD_SENTINEL}([\\s\\S]*?)${CWD_SENTINEL}`));
-        if (m) {
-            stderr = stderr.replace(m[0], "");
-            const captured = m[1].trim();
+        const epilogue = readCwdEpilogue(stderr, cwdMarker);
+        stderr = epilogue.stderr;
+        if (epilogue.cwd !== undefined) {
+            const captured = epilogue.cwd.trim();
             const windowsWorld = /^[A-Za-z]:[\\/]/.test(cwdRef.current);
             const msys = /^\/([A-Za-z])(\/.*)?$/.exec(captured);
             if (/^[A-Za-z]:[\\/]/.test(captured))
@@ -756,6 +873,22 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
             }
             const detachHub = taskOpts.detachHub;
             const detachRegistry = taskOpts.taskRegistry;
+            const autoBackgroundArmed = taskOpts.autoBackgroundOnTimeout === true && canAutoBackground(command);
+            let backgroundedForQueuedMessage = false;
+            const wantsTicks = taskOpts.onToolProgress !== undefined || (autoBackgroundArmed && detachHub !== undefined && taskOpts.queuedHumanInput !== undefined);
+            const onTick = !wantsTicks
+                ? undefined
+                : (t) => {
+                    describeSafely(taskOpts.onToolProgress, { toolCallId: ctx.toolCallId, toolName: "Bash", ...t });
+                    if (!autoBackgroundArmed || backgroundedForQueuedMessage || detachHub === undefined)
+                        return;
+                    if (ctx.signal?.aborted === true)
+                        return;
+                    if (taskOpts.queuedHumanInput?.() !== true)
+                        return;
+                    backgroundedForQueuedMessage = true;
+                    detachHub.request(ctx.toolCallId);
+                };
             const detachEnv = hasBackgroundShell(env) ? env : undefined;
             const detachChain = detachHub !== undefined && detachRegistry !== undefined && detachEnv !== undefined && detachEnv.backgroundCapabilities.supportsDetach === true
                 ? {
@@ -804,7 +937,9 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                         return {
                             content: (cause === "timeout"
                                 ? `Command exceeded its timeout but is still running — moved to background instead of being killed (task_id=${taskId}). `
-                                : `Command moved to background; task_id=${taskId}. `) +
+                                : backgroundedForQueuedMessage
+                                    ? `Command is still running and was moved to the background so a queued message could be delivered without waiting for it (task_id=${taskId}). It was NOT stopped and nothing about it failed. `
+                                    : `Command moved to background; task_id=${taskId}. `) +
                                 (outputFile !== undefined
                                     ? `Output file: ${outputFile} (full output is appended there — Read it any time). `
                                     : `Use TaskOutput("${taskId}") to read its output. `) +
@@ -818,7 +953,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                                 adoptBudgetNote +
                                 backgroundLifetimeNote(adoptCaps, bgSessionScoped, bgEnvIsolatedOwned) +
                                 (tail ? `\n--- output so far (tail) ---\n${tail}` : ""),
-                            details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}), ...(outputFile !== undefined ? { output_file: outputFile } : {}), ...(cause === "timeout" ? { autoBackgrounded: true } : {}) },
+                            details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}), ...(outputFile !== undefined ? { output_file: outputFile } : {}), ...(cause === "timeout" || backgroundedForQueuedMessage ? { autoBackgrounded: true } : {}) },
                         };
                     },
                     autoBackgroundEligible: taskOpts.autoBackgroundOnTimeout === true && canAutoBackground(command),
@@ -826,7 +961,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                 : undefined;
             let res;
             try {
-                res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, cwdRef, detachChain, false, [rootCanonical, ...(taskOpts.additionalRoots ?? [])]);
+                res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, cwdRef, detachChain, false, [rootCanonical, ...(taskOpts.additionalRoots ?? [])], onTick);
             }
             finally {
                 taskOpts.detachHub?.gc(ctx.toolCallId);
@@ -1210,7 +1345,8 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
             const escape = await canonicalEscapeRefusal(canonicalBoundary, { literal: [...(boundary.checkedPaths ?? []), ...(boundary.checkedSpellings ?? [])], patterns: [...(boundary.undecidedPaths ?? []), ...(boundary.undecidedSpellings ?? [])] }, readRoots, READONLY_FACE_ESCAPE_PROSE, ctx.signal);
             if (escape !== undefined)
                 return escape;
-            return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true);
+            const readOnlyTick = opts?.onToolProgress === undefined ? undefined : (t) => describeSafely(opts.onToolProgress, { toolCallId: ctx.toolCallId, toolName: "Bash", ...t });
+            return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true, undefined, readOnlyTick);
         },
     });
 }

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

@@ -6,4 +6,4 @@ import { type ReminderDisclosureCounts } from "../../core/reminder-disclosure.js
 export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
     taskId?: string;
     principal?: string;
-}) => boolean, readCyberReminder?: boolean, readDeny?: import("./read-deny.js").ReadDenyMatcher, readFace?: import("./read-face.js").ReadFace, reminderMark?: string, reminderDisclosureCounts?: ReminderDisclosureCounts): AgentTool;
+}) => boolean, readCyberReminder?: boolean, readDeny?: import("./read-deny.js").ReadDenyMatcher, readFace?: import("./containment-face.js").ContainmentFace, reminderMark?: string, reminderDisclosureCounts?: ReminderDisclosureCounts): AgentTool;

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

@@ -1,6 +1,6 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import type { ReadDenyMatcher } from "./read-deny.js";
-import type { ReadFace } from "./read-face.js";
+import type { ContainmentFace } from "./containment-face.js";
 import type { CwdRef } from "./fs-shared.js";
 /**
  * The Grep card's details assembly, PURE over the engine text ({mode, offset} from the request) —
@@ -11,5 +11,5 @@ import type { CwdRef } from "./fs-shared.js";
  * honesty boundary.
  */
 export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number, structuredRows?: readonly import("./search.js").GrepRow[]): Record<string, unknown>;
-export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace, cwdRef?: CwdRef): AgentTool;
-export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace, cwdRef?: CwdRef): AgentTool;
+export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;
+export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;

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

@@ -1,6 +1,7 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import type { BeforeWriteHook, FileEditedHook, TrackFileEditHook } from "../../core/types.js";
 import { type ReadFileState } from "./safety.js";
+import type { ContainmentFace } from "./containment-face.js";
 import { type CwdRef } from "./fs-shared.js";
 /**
  * The `beforeWrite` CONTENT hook, mounted here rather than in ToolPolicy because only this band sees
@@ -12,8 +13,8 @@ import { type CwdRef } from "./fs-shared.js";
  * Absent hook ⇒ byte-identical behavior.
  */
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook } from "../../core/types.js";
-export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook): AgentTool;
-export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook): AgentTool;
+export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: ContainmentFace): AgentTool;
+export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: ContainmentFace): AgentTool;
 /**
  * design v1.163 — NotebookEdit: replace/insert/delete a single cell in a .ipynb. CC-parity tool over the SAME hand-band
  * safety skeleton as Edit/Write (resolveKey containment → requireRead read-before-edit → checkStale content-hash
@@ -21,4 +22,4 @@ export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileSt
  * .ipynb as the cell projection but records read state (hash/totalLines) in the RAW notebook-text
  * coordinate — that raw-coordinate read record is what this tool's freshness check depends on.
  */
-export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook): AgentTool;
+export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook, writeFace?: ContainmentFace): AgentTool;

package/dist/tools/fs/fs-write.js

@@ -86,7 +86,7 @@ async function gateToolWrite(hook, tool, path, key, content) {
         return `Error (${tool}): write rejected by the write gate (${res.code}): ${clipHookText(res.reason)}`;
     return undefined;
 }
-export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
+export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace) {
     return defineTool({
         name: "Edit",
         ...toolFace("edit"),
@@ -111,7 +111,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             const path = fileArgPath(args);
             if (path === undefined)
                 return { ok: true };
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
             if (!r.ok)
                 return { ok: true };
             if (a.old_string === a.new_string)
@@ -149,7 +149,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             const path = fileArgPath(args);
             if (path === undefined)
                 return errorResult(`Error (Edit): file_path is required.`);
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
             if (!r.ok)
                 return errorResult(violationText("Edit", r.violation), violationDetails(r.violation));
             if (!batch && a.old_string === a.new_string) {
@@ -324,7 +324,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
         },
     });
 }
-export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
+export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace) {
     return defineTool({
         name: "Write",
         ...toolFace("write"),
@@ -343,7 +343,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                 return { ok: true };
             if (ipynbRedirect("Write", path))
                 return { ok: true };
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
             if (!r.ok)
                 return { ok: true };
             const exists = await env.exists(r.key, ctx.signal);
@@ -362,7 +362,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             const ipynb = ipynbRedirect("Write", path);
             if (ipynb)
                 return errorResult(ipynb);
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
             if (!r.ok)
                 return errorResult(violationText("Write", r.violation), violationDetails(r.violation));
             const exists = await env.exists(r.key, ctx.signal);
@@ -423,7 +423,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
 const notebookNotIpynbMessage = (notebookPath) => `Error (NotebookEdit): "${notebookPath}" is not a .ipynb file; use Edit for other file types.`;
 const NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE = `Error (NotebookEdit): Cell type is required when using edit_mode=insert.`;
 const NOTEBOOK_CELL_ID_REQUIRED_MESSAGE = `Error (NotebookEdit): cell_id is required for replace/delete.`;
-export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
+export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited, writeFace) {
     return defineTool({
         name: "NotebookEdit",
         ...toolFace("notebook-edit"),
@@ -457,7 +457,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 return { ok: false, code: "invalid", message: NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE };
             if (mode !== "insert" && !a.cell_id)
                 return { ok: false, code: "invalid", message: NOTEBOOK_CELL_ID_REQUIRED_MESSAGE };
-            const r = await resolveKey(env, rootCanonical, a.notebook_path, ctx.signal, cwdRef?.current, additionalRoots);
+            const r = await resolveKey(env, rootCanonical, a.notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
             if (!r.ok)
                 return { ok: true };
             const notRead = requireRead(state, r.key);
@@ -477,7 +477,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 return errorResult(NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE);
             if (mode !== "insert" && !cell_id)
                 return errorResult(NOTEBOOK_CELL_ID_REQUIRED_MESSAGE);
-            const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots);
+            const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots, undefined, undefined, writeFace);
             if (!r.ok)
                 return errorResult(violationText("NotebookEdit", r.violation), violationDetails(r.violation));
             const notRead = requireRead(state, r.key);