@sema-agent/core 7.23.3 → 7.23.5

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

@@ -159,6 +159,17 @@ export function argvReentryUnjudged(pos, acceptedTargets) {
     return runs === undefined || !acceptedTargets.has(runs);
 }
 export const SHELL_SCAN_DECLINES = ["unreadable_program_position", "stream_fed_operands"];
+export const BOUNDARY_SEAT_READS_DECLINE = {
+    unreadable_program_position: true,
+    stream_fed_operands: true,
+};
+export const CLASSIFY_SEAT_READS_DECLINE = {
+    unreadable_program_position: false,
+    stream_fed_operands: false,
+};
+export function seatDeclineEvidence(table) {
+    return new Set(SHELL_SCAN_DECLINES.filter((decline) => table[decline] === true));
+}
 export function programPositionRunsShell(pos, shellProgram) {
     if (pos.refusal !== undefined)
         return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell === true;

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

@@ -76,11 +76,13 @@ export interface LeadingCommandNameOptions {
      * Read a shell operator that sits inside a QUOTED region as ordinary argument TEXT rather than as an
      * operator, so `grep -E "a|b" f.log` parses as the single simple command it is.
      *
-     * OPT-IN, and used by ONE caller: the compound classify face ({@link classifyCompoundReadonlyDetailed}),
-     * which has already rejected the whole command for backslashes / `$` / backticks / subshells / line
-     * breaks and so is inside {@link quoteMask}'s exactness envelope. The declaration and rule faces do
-     * NOT set it — their contract is "a single simple command with no operator characters at all", which
-     * is a spelling rule about what a person can read at a glance, not a claim about bash's grammar.
+     * OPT-IN, and the two callers that set it share one premise: the whole command has ALREADY been refused
+     * for backslashes / an expanding `$` / backticks / subshells / line breaks, so they are inside
+     * {@link quoteMask}'s exactness envelope — the compound classify face
+     * ({@link classifyCompoundReadonlyDetailed}) and the persisted permission-RULE lane (`RULE_LANE_FLOOR`),
+     * whose segments come out of that same gate ({@link splitShellCompoundSegments}). The `bash_readonly`
+     * DECLARATION face does NOT set it: its contract is "a single simple command with no operator characters
+     * at all", and it runs on raw tool input with no whole-string gate in front of it.
      *
      * Fail-closed on unbalanced quoting: with a region left open, the mask is not trusted and every
      * operator character counts, exactly as without this option.
@@ -272,28 +274,24 @@ export interface BashReadonlyRootBoundary {
      *  and demotes (with no out-of-root signal — the classifier does not know where it points, which is a
      *  different verdict from knowing it points outside). */
     homeDir?: string;
-    /** The sensitive-path read deny judge over LEXICALLY RESOLVED operands: a hit
-     *  demotes the command (ask, never auto-allow), independently of the roots — in-root operands are
-     *  judged too. Returns the matched pattern, or null. TWO named residuals, both inherited from this
-     *  classifier's declared purity (synchronous, zero I/O — the same scope stated for the
-     *  containment half): ① operand TARGET matching only — no ancestor intersection: the judge sees
-     *  the operand's own resolved spelling, never its subtree. The RECURSIVE-reach half of that
-     *  residual has since been narrowed: a listed recursive/expanding verb's path
-     *  operand under this wired seat rides {@link CompoundReadonlyVerdict.recursiveReadPaths}
-     *  (⊂ undecidedPaths), so `grep -r x ~/` no longer auto-allows — it demotes to ask through the
-     *  undecided contract. What REMAINS of ① is the form table's stated open set (see the KNOWN OPEN
-     *  SET note at {@link RECURSIVE_READ_FORMS}: a traversal verb absent there that a deployment
-     *  allowlists classifies by its ordinary form and can auto-run a traversal unjudged);
-     *  ② LEXICAL only HERE — an in-root symlink whose target is a
-     *  guarded path reads as its innocent spelling at this seat, exactly as it does for the containment half,
-     *  because the classify auto-allow lane has no I/O seat by contract. The CANONICAL view is judged by the
-     *  full shell's execute-time recheck, which asks THIS judge (the same function object, forwarded) where
-     *  each candidate really lands — a `checkedPaths` literal and a `undecidedPaths` pattern's expansions
-     *  alike. The `bash_readonly` face wires no deny seat at all, so its own recheck carries nothing. The structured read faces judge BOTH
-     *  views (canonical + lexical); what this seat is and is not is stated once, at
-     *  `shell.read_boundary.friction_floor`. The `bash_readonly` face deliberately does NOT wire this seat (its
-     *  roots containment + command allowlist double gate is the deployment's own read-safety
-     *  declaration — v1 ruling). */
+    /** The sensitive-path read deny judge over LEXICALLY RESOLVED operands: a hit demotes the command (ask,
+     *  never auto-allow), independently of the roots — in-root operands are judged too. Returns the matched
+     *  pattern, or null. TWO named residuals, both inherited from this classifier's declared purity
+     *  (synchronous, zero I/O — the same scope stated for the containment half): ① operand TARGET matching
+     *  only, no ancestor intersection: the judge sees the operand's own resolved spelling, never its subtree.
+     *  The RECURSIVE-reach half of ① is narrowed — a listed recursive verb's path operand under this wired
+     *  seat rides {@link CompoundReadonlyVerdict.recursiveReadPaths} (⊂ undecidedPaths), so `grep -r x ~/` no
+     *  longer auto-allows; what REMAINS is the form table's stated open set (the KNOWN OPEN SET note at
+     *  {@link RECURSIVE_READ_FORMS}: a traversal verb absent there that a deployment allowlists classifies by
+     *  its ordinary form and can auto-run a traversal unjudged). ② LEXICAL only HERE — an in-root symlink
+     *  whose target is guarded reads as its innocent spelling at this seat, as it does for the containment
+     *  half, because the classify auto-allow lane has no I/O seat by contract; the CANONICAL view is judged by
+     *  an execute-time recheck that asks THIS judge (the same function object, forwarded) where each candidate
+     *  really lands, on a `checkedPaths` literal and a pattern's expansions alike.
+     *  EVERY read face wires this one seat, the `bash_readonly` shell included, at BOTH of its judging
+     *  moments — roots answer WHERE a command may read and the allowlist WHICH verb runs, neither answers
+     *  WHICH FILES are off the table. What this seat is and is not is stated once, at
+     *  `shell.read_boundary.friction_floor`. */
     denyMatch?: (resolvedPath: string) => string | null;
     /** What the wired {@link denyMatch} judge would apply — the ACTIVE deny patterns. Read for ONE question:
      *  is there anything for a traversal to defeat? EMPTY ⇒ the judge refuses nothing, so a walk under it
@@ -333,6 +331,10 @@ export interface CompoundReadonlyVerdict {
      *  reads it to mint `mandated` — a stored allow rule or the read-only shell arm may retire a classify-
      *  tier question, never one the read face itself asked. Structural sibling of `outOfRootRead`. */
     readDenied?: true;
+    /** The matched operand (resolved spelling) and the pattern — present iff {@link readDenied} (the
+     *  `outOfRootRead`/`outOfRootPaths` idiom), so a refusal CARD names the target without parsing prose. */
+    readDeniedPath?: string;
+    readDeniedPattern?: string;
     /**
      * The paths this scan resolved INSIDE the roots (de-duplicated, first-seen order), i.e. the
      * candidates a caller holding a filesystem should re-check with symlinks resolved. Absent when there
@@ -419,20 +421,19 @@ export interface CompoundReadonlyVerdict {
     /**
      * Operands of a RECURSIVE/EXPANDING read form (`grep -r`, `ls -R`, `du`, … — see
      * {@link RECURSIVE_READ_FORMS}) judged with a {@link BashReadonlyRootBoundary.denyMatch} seat wired.
-     * The deny judge sees only the operand's own resolved spelling, but a recursive verb reads the
-     * operand's whole SUBTREE — `grep -r x /home/user` touches `/home/user/.ssh/*` while the judged
-     * spelling `/home/user` matches no deny pattern. The traversal's reach set is therefore not covered
-     * by the lexical check at all, and with zero I/O "provably not a directory" does not exist — so
-     * every such operand is UNDECIDED (no directory guessing, no bounded pre-check: both would be a
-     * false "resolved, inside" of exactly the kind {@link undecidedPaths} exists to prevent).
+     * The judge sees only the operand's own resolved spelling, but a recursive verb reads the operand's whole
+     * SUBTREE — `grep -r x /home/user` touches `/home/user/.ssh/*` while the judged spelling matches nothing.
+     * The traversal's reach set is therefore not covered by the lexical check at all, and with zero I/O
+     * "provably not a directory" does not exist — so every such operand is UNDECIDED (no directory guessing,
+     * no bounded pre-check: both would be a false "resolved, inside" of exactly the kind
+     * {@link undecidedPaths} exists to prevent).
      *
-     * Subset of {@link undecidedPaths} (same consumer contract: ask, never auto-allow); carried
-     * separately so a consumer minting prose can name the recursive-reach cause rather than the glob
-     * one. Minted ONLY when `denyMatch` is wired: without a deny judge there is nothing the traversal
-     * bypasses — the containment half already judges the operand itself, and its lexical residuals are
-     * recorded on {@link checkedPaths}. The `bash_readonly` face never wires `denyMatch` (v1 ruling,
-     * see that seat's note), so this field never appears there and its expand-and-verify execution
-     * path is unchanged.
+     * Subset of {@link undecidedPaths} (same consumer contract: ask, never auto-allow); carried separately so
+     * a consumer minting prose can name the recursive-reach cause rather than the glob one. Minted ONLY when
+     * `denyMatch` is wired: without a judge there is nothing the traversal bypasses. EVERY face wiring the
+     * seat sees this field, the `bash_readonly` shell included, and answers it by its OWN rule for a demotion
+     * — that face has no approval channel, so what it cannot establish it REFUSES (an unbounded traversal is
+     * the same "the read set is not in the text" finding as a pattern the expander cannot enumerate).
      */
     recursiveReadPaths?: readonly string[];
     /**
@@ -618,8 +619,29 @@ export interface OutOfRootReadGateVerdict {
     readonly paths: readonly string[];
     /** Did the deployment's DENY judge speak about an operand this command names? The other half of the same
      *  question, over the very same readers, in a second pass WITH the deny judge — which is what lets the
-     *  containment answer above stay deny-free and keep its `paths` contract. Absent ⇔ it said nothing. */
-    readonly denied?: true;
+     *  containment answer above stay deny-free and keep its `paths` contract. Absent ⇔ it said nothing.
+     *
+     *  It carries the FINDING, not a boolean: this is the arm a command the grammar gate refused WHOLE
+     *  (`cat .env > out.txt`, a subshell, a substitution) reaches, and there the compound verdict carries no
+     *  deny fields at all — so a caller disclosing the hit has nowhere else to read the path and the pattern
+     *  from, and said nothing. The second pass already computed both; throwing them away was the whole bug. */
+    readonly denied?: {
+        readonly path: string;
+        readonly pattern: string;
+    };
+    /** The reader operands this pass RESOLVED and placed inside the roots, plus the expansions it parsed but
+     *  cannot enumerate — the candidates an execute-time recheck must canonicalize.
+     *
+     *  Published because this pass reads SHAPES the compound walk hands nothing out for: a launcher whose
+     *  program it cannot name (`env -- cat f`, `sudo -u root cat f`), a stream-fed one (`… | xargs cat f`).
+     *  There the compound verdict carries no candidates at all, so the recheck had nothing to resolve and an
+     *  in-root symlink to a deny-listed target RAN after an approval — while the same read spelled without
+     *  the launcher was refused. Same operands, same judge, one more pass allowed to hand them over.
+     *
+     *  NOT the out-of-root ones: those ride {@link paths}, they are what the boundary RAISED, and a leg that
+     *  re-refused them would be a second adjudicator of a decision already made. */
+    readonly checked: readonly string[];
+    readonly undecided: readonly string[];
 }
 /** Test seam for the lockstep pin that the launcher table (the ONE launcher truth, in the program-position
  *  reader's module) stays a SUBSET of the rule lane's curated `BARE_INTERPRETER_NAMES`. Exported for that one

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

@@ -1,3 +1,4 @@
+import { sensitivePathDenyList } from "./read-deny.js";
 import { hasWin32AliasedComponent, isAbsoluteForFamily, isAbsolutePathForm, isBlockedDevicePath, isShellRootedSpellingUnmapped, joinForFamily, nativeUncSpellingOf, normalizeAbsPathLexically, win32NamespaceScreen, pathFamilyOf, withinAnyRoot } from "./safety.js";
 import { lexShellText, literalTildeSpelling, quoteMask, substitutionsInHeredocBody, SUBSTITUTION_PLACEHOLDER, wordsOf, } from "./bash-lexer.js";
 import { ASSIGNMENT_WORD, COMMAND_LAUNCHERS, NOT_AUTO_ALLOWED, SHELL_BLOCK_WORDS, argvReentryUnjudged, isBareControlWord, programPositionRunsShell, shellScanDeclineOf, programBasename, programPositionRefusalSentence, readProgramPosition, } from "./bash-program-position.js";
@@ -19,11 +20,16 @@ function hasBareShellOperator(s, quotedOperatorsAreText) {
     if (!mask.balanced)
         return SHELL_OPERATORS.test(s);
     for (let i = 0; i < s.length; i++) {
-        if (!mask.quoted[i] && SHELL_OPERATORS.test(s[i]))
+        const ch = s[i];
+        if (!SHELL_OPERATORS.test(ch))
+            continue;
+        const literal = SHELL_EXPANDS_IN_DOUBLE_QUOTES.test(ch) ? mask.openedBy[i] === "'" : mask.quoted[i];
+        if (!literal)
             return true;
     }
     return false;
 }
+const SHELL_EXPANDS_IN_DOUBLE_QUOTES = /[$`]/;
 export function parseLeadingCommandName(command, options) {
     const trimmed = command.trim();
     if (!trimmed)
@@ -2169,8 +2175,10 @@ function evaluateReadBoundary(foldedSegments, boundary, mintGrantCandidate, reac
                 const denied = boundary.denyMatch?.(finding.path);
                 if (denied != null) {
                     return {
-                        reason: `a command operand resolves to "${finding.path}", which matches the sensitive-path read deny list (pattern "${denied}") ${NOT_AUTO_ALLOWED}`,
+                        reason: `a command operand resolves to "${finding.path}", which matches ${sensitivePathDenyList(denied)} ${NOT_AUTO_ALLOWED}`,
                         readDenied: true,
+                        readDeniedPath: finding.path,
+                        readDeniedPattern: denied,
                     };
                 }
                 if (finding.kind === "inside") {
@@ -2299,7 +2307,7 @@ export function classifySimpleCommandReadBoundary(command, boundary) {
     }
     return evaluateReadBoundary([toks], boundary, true);
 }
-const NOT_GATED = { gated: false, paths: [] };
+const NOT_GATED = { gated: false, paths: [], checked: [], undecided: [] };
 const UNREADABLE_WHITELIST_WORD = /[$`()*?[\]{}]/;
 const UNMODELLED_BASE_MOVERS = new Set(["pushd", "popd"]);
 export const COMMAND_LAUNCHERS_FOR_TEST = COMMAND_LAUNCHERS;
@@ -2357,18 +2365,33 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
         if (readers.length === 0)
             return NOT_GATED;
         if (baseMoved)
-            return { gated: true, paths: [] };
+            return { gated: true, paths: [], checked: [], undecided: [] };
         const verdict = evaluateReadBoundary(readers, containmentOnly, false, readerReach);
-        const denied = boundary.denyMatch === undefined ? false : evaluateReadBoundary(readers, boundary, false, readerReach).readDenied === true;
-        if (verdict.outOfRootRead === true)
-            return { gated: true, paths: verdict.outOfRootPaths ?? [], ...(denied ? { denied: true } : {}) };
-        return denied ? { gated: false, paths: [], denied: true } : NOT_GATED;
+        const denyPass = boundary.denyMatch === undefined ? undefined : evaluateReadBoundary(readers, boundary, false, readerReach);
+        const denied = denyPass?.readDenied === true && denyPass.readDeniedPath !== undefined && denyPass.readDeniedPattern !== undefined
+            ? { path: denyPass.readDeniedPath, pattern: denyPass.readDeniedPattern }
+            : undefined;
+        const resolvedOperands = {
+            checked: [...(verdict.checkedPaths ?? []), ...(verdict.checkedSpellings ?? [])],
+            undecided: [...(verdict.undecidedPaths ?? []), ...(verdict.undecidedSpellings ?? [])],
+        };
+        if (verdict.outOfRootRead === true) {
+            return { gated: true, paths: verdict.outOfRootPaths ?? [], ...resolvedOperands, ...(denied !== undefined ? { denied } : {}) };
+        }
+        if (denied !== undefined)
+            return { gated: false, paths: [], ...resolvedOperands, denied };
+        return resolvedOperands.checked.length === 0 && resolvedOperands.undecided.length === 0 ? NOT_GATED : { gated: false, paths: [], ...resolvedOperands };
     };
     const direct = judge(command);
-    if (direct.gated || direct.denied === true)
+    if (direct.gated || direct.denied !== undefined)
         return direct;
     const shape = POLL_LOOP_SHAPE.exec(command.trim());
-    return shape !== null ? judge(shape[3]) : NOT_GATED;
+    if (shape === null)
+        return direct;
+    const loop = judge(shape[3]);
+    return loop.gated || loop.denied !== undefined
+        ? loop
+        : { ...loop, checked: [...direct.checked, ...loop.checked], undecided: [...direct.undecided, ...loop.undecided] };
 }
 export function classifyCompoundReadonly(command, allow, boundary) {
     return classifyCompoundReadonlyDetailed(command, allow, boundary).reason;

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

@@ -4,6 +4,7 @@ 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";
 /**
  * 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
@@ -65,6 +66,10 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  * 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
@@ -86,8 +91,13 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  * DID read naming a path outside the roots still gates the call ({@link classifyOutOfRootReadGate}).
  */
 export declare const BOUNDARY_SEAT_DECLINE_EVIDENCE: ReadonlySet<ShellScanDecline>;
-/** The classify doctrine's table — see above; empty by the argument. */
+/** 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
@@ -291,6 +301,26 @@ 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
@@ -306,12 +336,17 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
  * 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.
  */
 export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, opts?: {
     /** Same timeout-cap overrides the full `bash` leg takes — see
      *  {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} /
-     *  {@link import("./index.js").HandsToolkitOptions.bashMaxTimeoutMs} (类修完整域: both foreground
-     *  legs share runShell's clamp, so both must share the configurable resolution). */
+     *  {@link import("./index.js").HandsToolkitOptions.bashMaxTimeoutMs} — both foreground legs share
+     *  runShell's clamp, so both must share the configurable resolution. */
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
     /** Structured sink for the timeout-cap discard announcements — same seat the full `bash` leg
@@ -321,6 +356,9 @@ 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 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 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