@sema-agent/core 7.24.4 → 7.25.0

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

@@ -2,163 +2,32 @@ import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type CwdRef } from "./fs-shared.js";
 import type { ReversibilityVerdict } from "../../core/types.js";
-import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
-import { type ShellScanDecline } from "./bash-program-position.js";
-import { type ReadDenyMatcher } from "./read-deny.js";
+import type { ShellReadAdmission } from "./shell-read-check.js";
 /**
- * A parsed-command classifier for the `bash` tool, exposed as a
- * `ToolSpec.reversibilityProbe`. A full shell is treated as egress+irreversible by DEFAULT; this probe is the
- * "real parsed classifier" that lets a deployment safely auto-allow the provably-benign subset (the
- * doctrine: shell⇒always-gate UNLESS a parsed classifier is wired). It is COMPOUND-aware
- * ({@link classifyCompoundReadonly}): a command is reversible ONLY if every `;`/`&&`/`||`/`|`
- * connected segment is a bare command (no redirects/substitution/subshells/escapes/`&` anywhere — those
- * whole-string reject, so it can't chain to `curl`/`git push`/`rm` or background past TaskStop) whose
- * `argv[0]` is in the reversible allowlist (default
- * {@link BASH_READONLY_DEFAULT_ALLOW} — `ls`/`cat`/`grep`/…, curated to commands with NO write/mutation mode
- * under ANY args; the final-council MAJOR removed `date`/`hostname`/`file`, which mutate with args). EVERYTHING
- * else (a write command, an egress command, an operator/pipe, a path-prefixed or env-assigned command, a
- * non-string arg) is NOT reversible → the gate tightens it to an `irreversible_ask` durable suspend. Fail-closed
- * by construction: the allowlist is the only path to `reversible: true`. It is an argv[0]-NAME filter, so the
- * remaining residual is the OTHER axis — a listed reader with crafted args can still READ a secret (a DATA side
- * channel, NOT irreversibility/egress); a deployment that widens `allow` owns that (and the mutation tradeoff).
- *
- * Wire it on the `bash` tool with `irreversibility: "maybe"` (or via `TaskSpec.shellGate: "classify"`); without
- * a classifier a deployment should mark `bash` `irreversibility: "always"` (`shellGate: "always"`) — fail-closed.
- *
- * The DATA-side residual named above is closed for the read direction: pass `boundary` and a listed
- * reader whose path arguments leave the allowed directories stops being reversible, so the gate asks
- * instead of auto-allowing. Pass it as a FUNCTION wherever the working directory is observable (an
- * in-task `cd` moves the base a relative operand resolves against, and the probe is called per command).
- * Omitted ⇒ name-only classification, exactly as before.
- *
- * The BOUNDED READ-ONLY POLL LOOP arm: a monitoring consumer's whole idiom is `for i in $(seq 1 8);
- * do tail -n 5 x.log; sleep 2; done`, which the compound face rejects as a class (`for` is not an
- * allowlisted name) — making the classify gate behave like `always` for exactly the tool that polls
- * the most. When the plain face rejects, the probe consults
- * {@link classifyBoundedReadonlyPollLoop} — a narrow exact grammar (literal bound, `;`-separated
- * allowlisted readers + literal `sleep`, the same read boundary, everything else banned; the full
- * safety argument lives on that function). Additive by construction: the plain verdict is tried
- * first and is never overridden.
- *
- * The RECURSIVE-READ demotion returns a STRUCTURED cause alongside the verdict. That
- * demotion is the one arm whose reason is genuinely unrecoverable downstream: a recursive read is
- * refused for what the traversal REACHES, and the reached set is by definition not in the command text
- * an approval card shows. The cause is minted from the SAME classification pass that produced the
- * verdict, so nothing re-parses the command to recover it.
- *
- * It is a `cause` (code + operand arrays), not a `reason` sentence, and that is a correction rather than
- * a preference: every sentence tried here was true of one call and false of another — "a recursive read
- * of X" is false for the zero-operand over-fire, "operand the check treated as a root" is false when the
- * check SYNTHESIZES the root, and any of them, flattened into one length-capped string, silently dropped
- * whichever family sorted last. The consumer now writes the sentence, from a code that cannot go stale
- * and arrays that cannot be truncated into a lie.
- *
- * The other non-reversible arms stay bare on purpose — their cause is legible in the command itself (a
- * write verb, a pipe, an unlisted name), and manufacturing an account for them would put text on a card
- * that adds nothing the reader cannot already see.
- *
- * What the boundary half of this probe is — and what it is not — is stated once on the seat that owns it
- * ({@link bashReadBoundaryProbe}, `@contract shell.read_boundary.friction_floor`); composing it with the
- * shape classifier here changes what happens to the residual shell risk, never that reading.
- */
-export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
-/**
- * ONE rule, TWO TABLES: which {@link ShellScanDecline} a SEAT reads as read evidence. A decline names no word,
- * so it is never the boundary DECLARING anything about a path.
- *
- * BOTH tables are ROW-PER-MEMBER objects behind a compile-time fence ({@link BOUNDARY_SEAT_READS_DECLINE} /
- * {@link CLASSIFY_SEAT_READS_DECLINE}); the sets below are DERIVED from those rows and the ARGUMENT for the
- * rows is this block. "Empty by the argument" is a row saying `false`, not a literal nobody can judge.
- *
- * The READ-BOUNDARY seat is what the default/off doctrine and a bypass mode mount ALONE: there "not mandated"
- * is VOUCHED, so a decline must count as evidence or a read nobody judged runs silently (`<out-of-root> |
- * xargs cat` at zero asks — a closed P0). It keeps both. The CLASSIFY seat composes the same boundary with the
- * SHAPE classifier, which refuses every one of these shapes: what survives is a CARD, and the only question
- * this table answers is who may retire it. It keeps NEITHER — an ANSWERER may (a person, the auto-mode
- * classifier, a person's stored allow rule) — empty by the argument, not by omission.
- *
- * WHAT AN EMPTY TABLE DOES NOT BUY, corrected where it was once claimed: "the shape classifier refuses these
- * shapes anyway, so the only question left is the stored answer" was true of the PROBE and false of the OUTCOME
- * — the allow layer's other members are not that classifier, and both cleared exactly these cards at ZERO asks. An
- * empty table says only "no MANDATE HERE"; that the boundary DECLINED is a separate fact, carried on every ask this
- * seat raises ({@link BoundaryAnswer}'s weaker rung), standing every ANSWERLESS arm down while every answerer's lane stays open.
- * THE COST, stated rather than mitigated: once that ask is retired BY AN ANSWERER, an out-of-root or deny-listed
- * read HIDDEN inside such a command is not asked again. A command's words are not the argv its programs receive (a
- * stream is re-split by its consumer, an unread option may move the working directory first, stdin text is a
- * command line nobody parsed), so a scan of them cannot be the guarantee it was claimed to be. "A read the boundary
- * objects to is never retired by a stored rule" does NOT hold on the classify seat for this class, and holds
- * unchanged elsewhere. One word-level check survives on both seats and is not part of the trade: a token the scan
- * DID read naming a path outside the roots still gates the call ({@link classifyOutOfRootReadGate}).
+ * The classify doctrine's SHAPE classifier for the `bash` tool, exposed as a `ToolSpec.reversibilityProbe`
+ * (the "maybe" tier's probe under `shellGate:"classify"`). A command is reversible ONLY if every connected
+ * segment is a bare command whose program is on the reversible allowlist (default
+ * {@link bashClassifyDefaultAllow} — curated to commands with NO write/mutation mode under ANY args) and whose
+ * SHAPE the compound classifier accepts (no redirects, substitutions, subshells, escapes or backgrounding; no
+ * blocking stdin read, follow mode or device read; a guarded verb form in its safe spelling) — or a bounded
+ * read-only poll loop of such commands ({@link classifyBoundedReadonlyPollLoop}). EVERYTHING else — a write
+ * command, an egress command, an operator, a path-prefixed or env-assigned command, a backgrounded call, a
+ * non-string arg — is NOT reversible → the gate tightens a surviving allow to an ordinary ask. Fail-closed by
+ * construction: the allowlist is the only path to `reversible: true`.
+ *
+ * WHERE a command reads is not this probe's question. The read boundary — deny rows, containment, symlinks,
+ * patterns, traversals, the working directory a `cd` moves — is the gate's shell READ STATION
+ * (`shell-read-check.ts`), judged on every shell call under every doctrine, ahead of this probe; a call the
+ * station refused never reaches it, and a call the station asks about is asked about whatever this probe
+ * says. `boundary` supplies only the environment's declared home, so the `$HOME`/`~` spellings fold here the
+ * way the station folds them; nothing else of it is read. A caller-supplied `allow` is honored verbatim, so a
+ * narrowed deployment is never widened by the default superset.
  */
-export declare const BOUNDARY_SEAT_DECLINE_EVIDENCE: ReadonlySet<ShellScanDecline>;
-/** The classify doctrine's table in the shape its readers take — see above; empty because every row says `false`. */
-export declare const CLASSIFY_SEAT_DECLINE_EVIDENCE: ReadonlySet<ShellScanDecline>;
-export declare function fitMiddle(s: string, budget: number): string;
-/** `s` shortened to `budget` by removing its MIDDLE, marked — cut through the repo's surrogate-safe
- *  primitive, never a raw `slice` (a raw cut leaves half an astral code point on a card and in a durable
- *  row). Under a dozen characters the HEAD is taken. */
-export declare function elideMiddle(s: string, budget: number): string;
-/**
- * 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 under an adapter that declares no home, 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). The engine wires the environment's
- *    declared home, so `~/x`, `$HOME/x` and `${HOME}/x` RESOLVE and are judged like the absolute spelling;
- *  · 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. A listed reader refused for a PER-SEGMENT shape (follow mode, a device,
- *    a blocking stdin read) is different: the compound face still walks its operands and carries the boundary's
- *    structural findings beside the sentence, so `tail -f <denied>` is the declared ask `cat <denied>` is.
- *    `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 variable other
- * than the home's own deterministic spellings — 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's structured verdict
- * ({@link classifyBoundedReadonlyPollLoopDetailed}) is read the same three ways as the compound face's.
- *
- * The reader set is the engine's classify set ({@link bashClassifyDefaultAllow}) — 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.
- *
- * @contract shell.read_boundary.friction_floor — what this seat answers is a question about TEXT: which
- * files the words of a command may name, resolved against the declared roots, the declared home and the
- * observed working directory. It is not a question about what the process will open, and no amount of
- * parsing makes it one. A deployment's containment for what a shell may reach is the `ExecutionEnv` the
- * command runs in (a sandbox, a container, a remote adapter); everything here is the friction floor under
- * that containment — it raises the cost of an accidental or careless read, and it is not a defence against
- * a command written to defeat it. The floor's last cell belongs to the full shell's own execute leg: once
- * the gate has allowed a call and before anything spawns, the candidates this seat accepted are resolved
- * 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. 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;
+export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: {
+    readonly homeDir?: string;
+} | (() => {
+    readonly homeDir?: string;
+} | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
  * 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
@@ -267,16 +136,14 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      */
     additionalRoots?: readonly string[];
     /**
-     * The deployment's shell READ BOUNDARY — the same seat the gate's shell probes read
-     * ({@link bashReadBoundaryProbe}), handed to the tool so its execute leg can close the one gap a
-     * synchronous seat structurally cannot: the seat judges the WRITTEN spelling, the kernel opens the
-     * symlink-resolved target. Passed as a FUNCTION wherever the working directory is observable (an
-     * in-task `cd` moves the base a relative operand resolves against); evaluated per call.
-     *
-     * Absent ⇒ no recheck and no I/O: a deployment with no read boundary declared has no roots for a
-     * read to be outside of, exactly as the seat itself reads an absent boundary.
+     * The gate's shell read station's pre-spawn ADMISSION (`ShellReadAdmission`, shell-read-check.ts): what
+     * this leg runs is what the station judged before approval, and the admission re-establishes the SAME
+     * candidates right before the spawn — a symlink re-pointed or a pattern re-matched while the approver
+     * was thinking refuses the call instead of running it. It parses nothing and judges no word the
+     * station did not. Absent ⇒ no station judged this mount (a library-direct toolkit with no gate):
+     * nothing is re-established, and the full shell runs unconfined as it always did.
      */
-    readBoundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined);
+    shellReadAdmission?: ShellReadAdmission;
     /** Override of the `timeout` parameter's DEFAULT budget, in ms — see
      *  {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} for the resolution
      *  contract (options over env over constant; invalid values discarded). */
@@ -301,46 +168,16 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      *  Absent ⇒ historic bare tag. */
     reminderMark?: string;
 }): AgentTool;
-type ShellCanonicalRefusal = {
-    content: string;
-    isError: true;
-    details?: unknown;
-};
-/** What a face contributes to the shared refusal cards: the TOOL refusing, and the three prose slots. */
-export interface ShellFaceProse {
-    readonly tool: string;
-    readonly subject: string;
-    readonly verdictPhrase: string;
-    readonly note: string;
-}
-export type ShellCanonicalRecheck = (command: string, signal?: AbortSignal) => Promise<ShellCanonicalRefusal | undefined>;
-/**
- * THE execute-time canonical recheck, mounted by every face that spawns a shell command — the full `Bash`
- * tool and `Monitor`, whose approval-time seats judge the WRITTEN spelling while this re-judges where the
- * kernel takes those words. The SAME leg, not a second one; the contract below is the leg's own. */
-export declare function createShellCanonicalRecheck(env: ExecutionEnv, readBoundary: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined) | undefined, face?: ShellFaceProse): ShellCanonicalRecheck;
-/** The `Monitor` face's prose — the full shell's with its own tool name: one leg, one finding, two tools. */
-export declare const MONITOR_ESCAPE_PROSE: ShellFaceProse;
 /**
  * `bash_readonly` (effect:read) — a restricted shell for the verifier read-only boundary: a single
  * allowlisted, bare command with no shell operators. effect:read lets it survive the verifier's
  * read-only filter, but it is NOT a policy circumvention — it still goes through the tool-policy gate,
- * because a read can still be a side channel (dumping a secret file). The allowlist is a coarse pre-filter;
- * the policy gate is the authoritative control.
- *
- * Hard refusal, not a demotion: the allowlist vets argv[0] and nothing else, so without a path
- * boundary an allowlisted reader could name ANY file on the host and get it (`cat /etc/passwd` would go
- * straight through). The full `bash` leg carries the same boundary as a DEMOTION — that leg's verdict
- * feeds an approval gate, so "outside the roots" can become a prompt. This face has no
- * such channel: `effect:"read"` is precisely what lets it run where the write shell may not (the verifier's
- * read-only band), so an out-of-root read here is not something to escalate, it is outside what the tool
- * is. It is refused, fail-closed, before anything executes — including the conservative direction, where
- * the operand cannot be resolved statically (there is nothing to degrade to).
- *
- * The boundary has TWO halves and this face wires both: roots answer WHERE a command may read and the
- * allowlist WHICH verb runs, neither answers WHICH FILES are off the table (a deny row holds INSIDE the
- * roots). The judge is the structured read faces' own, asked at both judging moments; every finding lands
- * on the standing rule above — a demotion here is a refusal.
+ * because a read can still be a side channel (dumping a secret file). The allowlist is a coarse pre-filter
+ * over the command's SHAPE; WHERE it reads is the gate's shell read station's judgment (`shell-read-check.ts`,
+ * the `readonly` seat), which REFUSES a deny-listed read, an out-of-root read and a read it cannot establish
+ * — this face has no approval channel to degrade to, so every finding is a refusal, before anything runs.
+ * The execute leg judges nothing: it admits what the station established (`shellReadAdmission` re-establishes
+ * the same candidates right before the spawn) and runs the command.
  */
 export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, opts?: {
     /** Same timeout-cap overrides the full `bash` leg takes — see
@@ -352,13 +189,12 @@ export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical:
     /** Structured sink for the timeout-cap discard announcements — same seat the full `bash` leg
      *  takes (both foreground legs share the resolver, so both must share the sink). */
     onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
-    /** The extra containment roots the structured file tools got (the CC `--add-dir` family,
-     *  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 deployment's compiled read deny set — the SAME matcher object the structured read faces of this
-     *  mount hold (one compile, one table). Absent ⇒ no deny judge, and both judging moments are unchanged. */
-    readDeny?: ReadDenyMatcher;
+    /** The gate's shell read station's pre-spawn ADMISSION (`ShellReadAdmission`, shell-read-check.ts): what
+     *  this leg runs is what the station judged, re-established right before the spawn. Absent ⇒ no station
+     *  judged this mount (a library-direct toolkit with no gate): this face then confines NOTHING — its
+     *  containment IS the station, and a consumer mounting it without one must run `runToolGate` with the
+     *  station's `shellReadCheck` (the Runner does). */
+    shellReadAdmission?: ShellReadAdmission;
     /** 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