@sema-agent/core 5.30.0 → 5.32.0

package/dist/orchestration/workflow-governance.js

@@ -1,5 +1,7 @@
+import { deliverEngineNotice } from "../core/types.js";
 import { tightenTaskSpec } from "../core/tighten-task-spec.js";
 import { sanitizeUntrustedText } from "../core/untrusted-text.js";
+import { compileReadDeny } from "../tools/fs/read-deny.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
 export class WorkflowModelNotAllowedError extends Error {
     modelName;
@@ -17,7 +19,43 @@ export const WHITELIST_KEYS = [
     "systemPrompt",
     "images",
     "limits",
+    "readFace",
+    "readDenyPatterns",
 ];
+const WHITELIST_KEY_SET = new Set(WHITELIST_KEYS);
+export const STRIPPED_KEYS_NOTICE_CODE = "workflow.governance_key_stripped";
+const MAX_STRIPPED_KEYS_ANNOUNCED = 20;
+const MAX_STRIPPED_KEY_CHARS = 64;
+const UNSAFE_KEY_CODE_POINT = /[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/u;
+function renderStrippedKey(key) {
+    let out = "";
+    let seen = 0;
+    for (const point of key) {
+        if (seen === MAX_STRIPPED_KEY_CHARS)
+            return `${out}…`;
+        out += UNSAFE_KEY_CODE_POINT.test(point) ? "?" : point;
+        seen++;
+    }
+    return out;
+}
+function emitStrippedKeysNotice(survey, onNotice) {
+    const shown = survey.sample.map((s) => ({ key: renderStrippedKey(s.key), reason: s.reason }));
+    const omitted = survey.total - shown.length;
+    const list = shown.map((s) => JSON.stringify(s.key)).join(", ") + (omitted > 0 ? `, +${omitted} more` : "");
+    const message = `workflow governance: ${survey.total} field(s) of an agent spec were NOT applied to the child (${list}). ` +
+        `A governed workflow script may set only: ${WHITELIST_KEYS.join(", ")} — and \`readFace\` only as "roots" ` +
+        `(the containment-tightening direction; "open" widens and is never taken from a script). Every other field ` +
+        `of the child comes from the deployment baseline.`;
+    try {
+        deliverEngineNotice(onNotice, {
+            code: STRIPPED_KEYS_NOTICE_CODE,
+            message,
+            detail: { total: survey.total, stripped: shown, ...(omitted > 0 ? { omitted } : {}) },
+        });
+    }
+    catch {
+    }
+}
 const VALID_THINKING = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 export function resolveModelName(name, allowlist, models) {
     if (!allowlist || allowlist.length === 0) {
@@ -49,49 +87,121 @@ function pickImageInput(el, i) {
     }
     const o = el;
     if ("url" in o) {
-        if (typeof o.url !== "string" || o.url.length === 0) {
+        const url = o.url;
+        if (typeof url !== "string" || url.length === 0) {
             throw new WorkflowScriptError(`${at}.url must be a non-empty string`);
         }
-        return { url: o.url };
+        return { url };
     }
-    if (typeof o.data !== "string") {
+    const data = o.data;
+    const mimeType = o.mimeType;
+    if (typeof data !== "string") {
         throw new WorkflowScriptError(`${at}.data must be a base64 string (or supply { url } instead)`);
     }
-    if (typeof o.mimeType !== "string" || o.mimeType.length === 0) {
+    if (typeof mimeType !== "string" || mimeType.length === 0) {
         throw new WorkflowScriptError(`${at}.mimeType must be a non-empty string, e.g. "image/png"`);
     }
-    return { data: o.data, mimeType: o.mimeType };
+    return { data, mimeType };
+}
+const MAX_SCRIPT_DENY_ENTRIES = 16;
+const MAX_SCRIPT_DENY_PATTERN_CHARS = 256;
+const MAX_SCRIPT_DENY_WILDCARDS_PER_SEGMENT = 1;
+const MAX_SCRIPT_IMAGES = 32;
+function assertScriptDenyPatternBounded(pattern, at) {
+    if (pattern.length > MAX_SCRIPT_DENY_PATTERN_CHARS) {
+        throw new WorkflowScriptError(`${at} is ${pattern.length} characters — a workflow script's deny pattern is limited to ${MAX_SCRIPT_DENY_PATTERN_CHARS} (the matcher runs on every read of the child's run).`);
+    }
+    for (const segment of pattern.split("/")) {
+        const wildcards = segment.split("*").length - 1;
+        if (wildcards > MAX_SCRIPT_DENY_WILDCARDS_PER_SEGMENT) {
+            throw new WorkflowScriptError(`${at} has a path segment with ${wildcards} \`*\` wildcards — a workflow script's deny pattern allows at most ` +
+                `${MAX_SCRIPT_DENY_WILDCARDS_PER_SEGMENT} per path segment (the same expressiveness the engine's built-in deny table ` +
+                `uses). Each \`*\` compiles to a greedy match, and more than one in a single segment makes the judgment cost grow ` +
+                `superlinearly with the path length, on every read the child performs. Write the intent as separate entries ` +
+                `(the set is a union, so more entries deny strictly more) or anchor it with literal segments.`);
+        }
+    }
+}
+function mapUntrustedArray(value, at, atMost, why, build) {
+    const declared = value.length;
+    if (typeof declared !== "number" || !Number.isSafeInteger(declared) || declared < 0) {
+        throw new WorkflowScriptError(`${at} does not report a valid array length.`);
+    }
+    if (declared > atMost) {
+        throw new WorkflowScriptError(`${at} carries ${declared} entries — a workflow script may set at most ${atMost}. ${why}`);
+    }
+    const out = [];
+    for (let i = 0; i < declared; i++)
+        out.push(build(value[i], i));
+    return out;
+}
+function pickReadDenyEntry(el, i) {
+    const at = `agent(spec): \`readDenyPatterns[${i}]\``;
+    if (typeof el === "string") {
+        if (el.length === 0)
+            throw new WorkflowScriptError(`${at} must be a non-empty pattern string`);
+        assertScriptDenyPatternBounded(el, at);
+        return el;
+    }
+    if (typeof el !== "object" || el === null || Array.isArray(el)) {
+        throw new WorkflowScriptError(`${at} must be a pattern string or an object { pattern, caseSensitive? }`);
+    }
+    const o = el;
+    const pattern = o.pattern;
+    const caseSensitive = o.caseSensitive;
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        throw new WorkflowScriptError(`${at}.pattern must be a non-empty string, e.g. ".ssh" or "secrets/*.json"`);
+    }
+    if (caseSensitive !== undefined && typeof caseSensitive !== "boolean") {
+        throw new WorkflowScriptError(`${at}.caseSensitive must be a boolean`);
+    }
+    assertScriptDenyPatternBounded(pattern, at);
+    return caseSensitive === undefined ? { pattern } : { pattern, caseSensitive };
 }
 function pickWhitelist(scriptSpec) {
     if (typeof scriptSpec !== "object" || scriptSpec === null || Array.isArray(scriptSpec)) {
         throw new WorkflowScriptError("agent(spec): spec must be an object with at least an `objective` string");
     }
     const s = scriptSpec;
-    if (typeof s.objective !== "string" || s.objective.length === 0) {
+    const stripped = { total: 0, sample: [] };
+    for (const k of Object.keys(s)) {
+        if (WHITELIST_KEY_SET.has(k))
+            continue;
+        stripped.total++;
+        if (stripped.sample.length < MAX_STRIPPED_KEYS_ANNOUNCED)
+            stripped.sample.push({ key: k, reason: "not_whitelisted" });
+    }
+    const objective = s.objective;
+    const thinking = s.thinking;
+    const systemPrompt = s.systemPrompt;
+    const modelNameRaw = s.modelName;
+    if (typeof objective !== "string" || objective.length === 0) {
         throw new WorkflowScriptError("agent(spec): `objective` is required and must be a non-empty string");
     }
-    const safe = { objective: s.objective };
-    if (s.thinking !== undefined) {
-        if (typeof s.thinking !== "string" || !VALID_THINKING.has(s.thinking)) {
+    const safe = { objective };
+    if (thinking !== undefined) {
+        if (typeof thinking !== "string" || !VALID_THINKING.has(thinking)) {
             throw new WorkflowScriptError(`agent(spec): invalid \`thinking\` (must be one of ${[...VALID_THINKING].join(", ")})`);
         }
-        safe.thinking = s.thinking;
+        safe.thinking = thinking;
     }
-    if (s.systemPrompt !== undefined) {
-        if (typeof s.systemPrompt !== "string")
+    if (systemPrompt !== undefined) {
+        if (typeof systemPrompt !== "string")
             throw new WorkflowScriptError("agent(spec): `systemPrompt` must be a string");
-        safe.systemPrompt = `[workflow-script-authored persona — task guidance, not engine authority]\n${sanitizeUntrustedText(s.systemPrompt)}`;
+        safe.systemPrompt = `[workflow-script-authored persona — task guidance, not engine authority]\n${sanitizeUntrustedText(systemPrompt)}`;
     }
-    if (s.images !== undefined) {
-        if (!Array.isArray(s.images))
+    const images = s.images;
+    if (images !== undefined) {
+        if (!Array.isArray(images))
             throw new WorkflowScriptError("agent(spec): `images` must be an array");
-        safe.images = s.images.map(pickImageInput);
+        safe.images = mapUntrustedArray(images, "agent(spec): `images`", MAX_SCRIPT_IMAGES, "Each one is decoded and shipped on every request of the child's turn.", pickImageInput);
     }
-    if (s.limits !== undefined) {
-        if (typeof s.limits !== "object" || s.limits === null || Array.isArray(s.limits)) {
+    const limitsRaw = s.limits;
+    if (limitsRaw !== undefined) {
+        if (typeof limitsRaw !== "object" || limitsRaw === null || Array.isArray(limitsRaw)) {
             throw new WorkflowScriptError("agent(spec): `limits` must be an object { maxTurns?, maxWalltimeMs?, maxTokens?, maxCostUsd? }");
         }
-        const l = s.limits;
+        const l = limitsRaw;
         const limits = {};
         const readAxis = (field, what) => {
             const raw = l[field];
@@ -109,13 +219,38 @@ function pickWhitelist(scriptSpec) {
         readAxis("maxCostUsd", "spend ceiling");
         safe.limits = limits;
     }
+    if (s.readFace !== undefined) {
+        if (s.readFace === "roots") {
+            safe.readFace = "roots";
+        }
+        else {
+            stripped.total++;
+            stripped.sample.unshift({ key: "readFace", reason: "not_a_tightening_value" });
+            if (stripped.sample.length > MAX_STRIPPED_KEYS_ANNOUNCED)
+                stripped.sample.pop();
+        }
+    }
+    const readDenyPatternsRaw = s.readDenyPatterns;
+    if (readDenyPatternsRaw !== undefined) {
+        if (!Array.isArray(readDenyPatternsRaw)) {
+            throw new WorkflowScriptError('agent(spec): `readDenyPatterns` must be an array of deny entries (a "/"-separated segment run such as ".ssh", or { pattern, caseSensitive? })');
+        }
+        const entries = mapUntrustedArray(readDenyPatternsRaw, "agent(spec): `readDenyPatterns`", MAX_SCRIPT_DENY_ENTRIES, "Every entry is judged against every path the child reads, for the child's whole run; the built-in and deployment entries are always in force on top of these.", pickReadDenyEntry);
+        try {
+            compileReadDeny(entries, "agent(spec).readDenyPatterns");
+        }
+        catch (err) {
+            throw new WorkflowScriptError(err instanceof Error ? err.message : String(err));
+        }
+        safe.readDenyPatterns = entries;
+    }
     let modelName;
-    if (s.modelName !== undefined) {
-        if (typeof s.modelName !== "string")
+    if (modelNameRaw !== undefined) {
+        if (typeof modelNameRaw !== "string")
             throw new WorkflowScriptError("agent(spec): `modelName` must be a string (a model NAME, never a Model object)");
-        modelName = s.modelName;
+        modelName = modelNameRaw;
     }
-    return { safe, modelName };
+    return { safe, modelName, stripped };
 }
 function clampResourceLimits(safe, base, caps) {
     const trustedCandidates = [
@@ -172,8 +307,10 @@ function clampResourceLimits(safe, base, caps) {
         safe.limits = rebuilt;
     return notes;
 }
-export function buildGovernedChildSpec(scriptSpec, baseline, models, caps, onResourceClamp) {
-    const { safe, modelName } = pickWhitelist(scriptSpec);
+export function buildGovernedChildSpec(scriptSpec, baseline, models, caps, onResourceClamp, onNotice) {
+    const { safe, modelName, stripped } = pickWhitelist(scriptSpec);
+    if (stripped.total > 0)
+        emitStrippedKeysNotice(stripped, onNotice);
     if (modelName !== undefined) {
         safe.model = resolveModelName(modelName, baseline.workflowModelAllowlist, models);
     }

package/dist/orchestration/workflow-primitives.d.ts

@@ -22,6 +22,11 @@ export interface WorkflowGovernance {
     baseline: WorkflowGovernanceBaseline;
     models?: Record<string, Model>;
     caps?: WorkflowChildCaps;
+    /** The deployment's structured notice sink (`RunnerDeps.onNotice`), threaded here because the governed
+     *  build is the only place that can report which spec fields did NOT reach the child (see
+     *  `buildGovernedChildSpec`'s `onNotice` param). Only meaningful in governed mode — the trusted-dev lane
+     *  strips nothing. Absent ⇒ the notice falls back to `console.warn`. */
+    onNotice?: (n: import("../core/types.js").EngineNotice) => void;
 }
 /**
  * Build the flat {@link WorkflowPrimitives} a {@link WorkflowScriptRunner} runs the script against. The

package/dist/orchestration/workflow-primitives.js

@@ -29,7 +29,7 @@ export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThi
         const agentOpts = safeAgentOptions(opts);
         const effectiveBaseline = (b) => agentOpts.isolation === "worktree" && b.worktreeBase !== undefined ? { ...b, base: { ...b.base, ...b.worktreeBase } } : b;
         const childSpec = governance
-            ? buildGovernedChildSpec(spec, effectiveBaseline(governance.baseline), governance.models, governance.caps, (notes) => ctx.log(formatResourceClampNote(notes)))
+            ? buildGovernedChildSpec(spec, effectiveBaseline(governance.baseline), governance.models, governance.caps, (notes) => ctx.log(formatResourceClampNote(notes)), governance.onNotice)
             : { ...spec };
         if (childSpec.thinking === undefined && parentThinking) {
             const inherited = parentThinking();

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

@@ -172,8 +172,32 @@ export interface CompoundReadonlyVerdict {
      *
      * `cd` is the one exception, and it fails closed: a glob there cannot be expanded into the single
      * directory the compound face must track as the new working directory, so it demotes (see {@link reason}).
+     *
+     * ALSO carries the {@link recursiveReadPaths} entries (a subset): both families are operands whose
+     * real read set is not in the command text, and the consumer contract above ("non-empty ⇒ ask, or
+     * resolve yourself") is stated over this one field so an auto-allow gate cannot honour one family
+     * and miss the other.
      */
     undecidedPaths?: readonly string[];
+    /**
+     * 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).
+     *
+     * 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.
+     */
+    recursiveReadPaths?: readonly string[];
 }
 /**
  * RB-412 — the single minting point for the out-of-root-read approval option text, so a gate rendering
@@ -224,10 +248,14 @@ export declare function classifyCompoundReadonlyDetailed(command: string, allow:
 export declare function classifySimpleCommandReadBoundary(command: string, boundary: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
 /**
  * design/154 — compound read-only classification, reason-only face. Returns the demotion reason, or
- * undefined when the command classifies read-only. RB-412 added the optional `boundary`: with it, an
- * allowlisted reader whose path arguments leave the allowed directories is demoted too (use
- * {@link classifyCompoundReadonlyDetailed} when the caller wants to know that WHY, e.g. to offer the
- * narrow "allow reading from <dir>" approval); without it the verdict is exactly what it always was.
+ * undefined when the command classifies read-only. ⚠️ `undefined` is NOT "safe to auto-execute":
+ * the detailed verdict may still carry `undecidedPaths` (operands whose unexpanded spelling — a
+ * glob — is what got checked), and this face discards that field. An auto-allow decision must read
+ * {@link classifyCompoundReadonlyDetailed} and treat a non-empty `undecidedPaths` as ask — the
+ * engine's own probe does exactly that (fs-bash.ts). RB-412 added the optional `boundary`: with it,
+ * an allowlisted reader whose path arguments leave the allowed directories is demoted too (use the
+ * detailed face when the caller wants to know WHY, e.g. to offer the narrow "allow reading from
+ * <dir>" approval); without it the verdict is exactly what it always was.
  */
 export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;
 /**

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

@@ -284,6 +284,90 @@ function takesSeparatedValue(name, tok) {
     }
     return false;
 }
+const RECURSIVE_READ_FORMS = {
+    grep: {
+        shortLetters: "rR",
+        valueOwners: "efmABCD",
+        longNames: ["recursive", "dereference-recursive"],
+        enumOptions: [{ shortLetter: "d", longName: "directories", recursiveValue: "recurse" }],
+        dashIsStdin: true,
+    },
+    ls: { shortLetters: "R", longNames: ["recursive"] },
+    du: { always: true },
+    find: { always: true },
+    rg: { always: true, dashIsStdin: true },
+    tree: { always: true },
+    ag: { always: true, dashIsStdin: true },
+    ack: { always: true, dashIsStdin: true },
+    tar: { shortLetters: "cru", valueOwners: "fCTXbg", longNames: ["create", "append", "update"], bundledModeLetters: "cru", dashIsStdin: true },
+    diff: { shortLetters: "r", valueOwners: "UCWISFXx", longNames: ["recursive"], dashIsStdin: true },
+};
+function segmentSelectsRecursiveRead(name, args) {
+    const model = RECURSIVE_READ_FORMS[name];
+    if (model === undefined)
+        return false;
+    if (model.always === true)
+        return true;
+    if (model.bundledModeLetters !== undefined) {
+        const first = args.find((t) => t.length > 0);
+        if (first !== undefined && !first.startsWith("-") && /^[A-Za-z]+$/.test(first) && [...first].some((ch) => model.bundledModeLetters.includes(ch))) {
+            return true;
+        }
+    }
+    let endOfOptions = false;
+    for (let k = 0; k < args.length; k++) {
+        const t = args[k];
+        if (endOfOptions)
+            continue;
+        if (t === "--") {
+            const prev = k > 0 ? args[k - 1] : undefined;
+            const prevMayOwnValue = prev !== undefined && prev.startsWith("--") && prev.length > 2 && !prev.includes("=");
+            if (!prevMayOwnValue)
+                endOfOptions = true;
+            continue;
+        }
+        if (t.startsWith("--")) {
+            const long = longOptionNameOf(t);
+            if (long === undefined)
+                continue;
+            if (model.longNames?.some((full) => isLongOptionAbbrevOf(long, full)) === true)
+                return true;
+            for (const en of model.enumOptions ?? []) {
+                if (en.longName === undefined || !isLongOptionAbbrevOf(long, en.longName))
+                    continue;
+                const eq = t.indexOf("=");
+                const v = eq >= 0 ? t.slice(eq + 1) : args[k + 1];
+                if (v !== undefined && v.length > 0 && en.recursiveValue.startsWith(v.toLowerCase()))
+                    return true;
+            }
+            continue;
+        }
+        if (!t.startsWith("-") || t === "-")
+            continue;
+        for (let i = 1; i < t.length; i++) {
+            const ch = t[i];
+            if (model.shortLetters?.includes(ch) === true)
+                return true;
+            const en = (model.enumOptions ?? []).find((e) => e.shortLetter === ch);
+            if (en !== undefined) {
+                const v = i === t.length - 1 ? args[k + 1] : t.slice(i + 1);
+                if (v !== undefined && v.length > 0 && en.recursiveValue.startsWith(v.toLowerCase()))
+                    return true;
+                if (i === t.length - 1)
+                    k++;
+                break;
+            }
+            if (model.valueOwners?.includes(ch) === true) {
+                if (i === t.length - 1)
+                    k++;
+                break;
+            }
+            if (!/[A-Za-z0-9]/.test(ch))
+                break;
+        }
+    }
+    return false;
+}
 function isGrepFileStdinLongOption(tok) {
     const eq = tok.indexOf("=");
     if (eq < 0 || tok.slice(eq + 1) !== "-")
@@ -327,6 +411,7 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
     const findings = [];
     const candidates = [];
     const bareWordOperands = [];
+    const positionalOperands = [];
     const argGlobs = (k) => {
         const raw = tokens.raw[k + 1];
         return raw !== undefined && hasUnquotedGlobMetachar(raw);
@@ -356,31 +441,47 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
         candidates.push({ text: target, globbed: false });
     }
     else {
-        const patternSuppliedByFlag = name === "grep" && args.some(isGrepPatternFlagToken);
+        const eoo = args.indexOf("--");
+        const patternSuppliedByFlag = name === "grep" && (eoo === -1 ? args : args.slice(0, eoo)).some(isGrepPatternFlagToken);
         let sawOperand = false;
+        let endOfOptions = false;
         for (let k = 0; k < args.length; k++) {
             const t = args[k];
-            if (name === "cut" && (t === "-d" || t === "--delimiter" || t === "--output-delimiter")) {
-                k++;
-                continue;
-            }
-            if (name === "cut" && (/^-d./.test(t) || isCutDelimiterPayloadLongOption(t)))
-                continue;
-            if (name === "grep" && (grepClusterValueOwner(t) === "e" || isGrepPatternPayloadLongOption(t)))
-                continue;
-            if (t.startsWith("-") && t !== "-") {
-                for (const payload of attachedOptionPayloads(t)) {
-                    if (isAbsolutePathForm(payload) || isPathShapedToken(payload))
-                        candidates.push({ text: payload, globbed: argGlobs(k) });
+            if (!endOfOptions) {
+                if (t === "--") {
+                    endOfOptions = true;
+                    continue;
+                }
+                if (name === "cut" && (t === "-d" || t === "--delimiter" || t === "--output-delimiter")) {
+                    k++;
+                    continue;
+                }
+                if (name === "cut" && (/^-d./.test(t) || isCutDelimiterPayloadLongOption(t)))
+                    continue;
+                if (name === "grep" && (grepClusterValueOwner(t) === "e" || isGrepPatternPayloadLongOption(t)))
+                    continue;
+                if (t.startsWith("-") && t !== "-") {
+                    for (const payload of attachedOptionPayloads(t)) {
+                        if (isAbsolutePathForm(payload) || isPathShapedToken(payload))
+                            candidates.push({ text: payload, globbed: argGlobs(k) });
+                    }
+                    continue;
                 }
-                continue;
             }
             const isGrepPatternSlot = name === "grep" && !patternSuppliedByFlag && !sawOperand;
             sawOperand = true;
-            if (t === "-")
+            if (t === "-") {
+                if (isGrepPatternSlot)
+                    continue;
+                const m = RECURSIVE_READ_FORMS[name];
+                if (m === undefined || m.dashIsStdin === true)
+                    continue;
+                positionalOperands.push(t);
                 continue;
+            }
             if (isGrepPatternSlot)
                 continue;
+            positionalOperands.push(t);
             if (isPathShapedToken(t))
                 candidates.push({ text: t, globbed: argGlobs(k) });
             else
@@ -416,6 +517,13 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
         if (!globbed && withinAnyRoot(boundary.roots, resolved))
             findings.push({ kind: "inside", path: resolved });
     }
+    if (boundary.denyMatch !== undefined && segmentSelectsRecursiveRead(name, args)) {
+        const roots = positionalOperands.length > 0 ? positionalOperands : ["."];
+        for (const operand of roots) {
+            const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], operand, boundary.homeDir);
+            findings.push({ kind: "recursive", path: resolved ?? operand });
+        }
+    }
     return findings;
 }
 export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
@@ -584,6 +692,7 @@ function evaluateReadBoundary(foldedSegments, boundary) {
     const outside = [];
     const inside = [];
     const undecided = [];
+    const recursive = [];
     for (const toks of foldedSegments) {
         for (const finding of collectSegmentBoundaryFindings(toks, boundary)) {
             if (finding.kind === "unresolvable")
@@ -604,6 +713,11 @@ function evaluateReadBoundary(foldedSegments, boundary) {
                     undecided.push(finding.path);
                 continue;
             }
+            if (finding.kind === "recursive") {
+                if (!recursive.includes(finding.path))
+                    recursive.push(finding.path);
+                continue;
+            }
             if (boundary.face === "open") {
                 if (!inside.includes(finding.path))
                     inside.push(finding.path);
@@ -613,7 +727,11 @@ function evaluateReadBoundary(foldedSegments, boundary) {
                 outside.push(finding);
         }
     }
-    const undecidedField = undecided.length > 0 ? { undecidedPaths: undecided } : {};
+    const undecidedAll = [...undecided, ...recursive.filter((p) => !undecided.includes(p))];
+    const undecidedField = {
+        ...(undecidedAll.length > 0 ? { undecidedPaths: undecidedAll } : {}),
+        ...(recursive.length > 0 ? { recursiveReadPaths: recursive } : {}),
+    };
     if (outside.length === 0)
         return inside.length > 0 ? { checkedPaths: inside, ...undecidedField } : { ...undecidedField };
     const paths = outside.map((o) => `"${o.path}"`).join(", ");
@@ -724,6 +842,9 @@ export function classifyBoundedReadonlyPollLoop(command, allow, boundary) {
     const verdict = classifyCompoundReadonlyDetailed(readSegments.join("; "), allow, boundary);
     if (verdict.reason !== undefined)
         return verdict.reason;
+    if (verdict.recursiveReadPaths !== undefined) {
+        return `the loop body reads recursively from ${verdict.recursiveReadPaths.join(", ")} — the traversal's reach is not covered by this lexical check, so it is not auto-allowed`;
+    }
     if (verdict.undecidedPaths !== undefined) {
         return `the loop body carries an unexpanded glob (${verdict.undecidedPaths.join(", ")}) — what a REPEATED read touches is decided at run time, so it is not auto-allowed`;
     }

package/dist/tools/fs/index.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import type { BeforeWriteHook } from "../../core/types.js";
+import { type BeforeWriteHook } from "../../core/types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type ReadFileState } from "./safety.js";
 import type { PdfModelCapabilities } from "./pdf.js";
@@ -130,8 +130,12 @@ export interface HandsToolkitOptions {
      *  {@link import("./read-face.js").resolveReadFace} order prepare-task uses). Absent ⇒ the
      *  resolution order's default = "roots" (D-1b: the engine never opens implicitly). "open" skips
      *  ONLY the roots containment judgment — the deny set, the UNC out-of-set refusal and the
-     *  special-file type gates run in both faces (§2.0). Refused loudly beside `readOnly: true`
-     *  (the verifier mount's containment is load-bearing). Never affects the write faces. */
+     *  special-file type gates run in both faces (§2.0). Beside `readOnly: true` the mount wins:
+     *  this seat is deps-shaped (a deployment default, not a per-call assertion), so its "open"
+     *  CLAMPS to "roots" and the clamp is ANNOUNCED (`config.read_face_deployment_clamped`, through
+     *  `onNotice` / `console.warn`) — the loud refusal belongs to the TASK seat (`TaskSpec.readFace`),
+     *  which is the one genuine per-call contradiction (#237; stale "refused loudly" wording here
+     *  predated the 96ef89d seat distinction). Never affects the write faces. */
     readFace?: "open" | "roots";
 }
 /**

package/dist/tools/fs/index.js

@@ -1,3 +1,4 @@
+import { deliverEngineNotice } from "../../core/types.js";
 import { createTaskOutputTool, createTaskStopTool } from "../../core/task-registry.js";
 import { hasBackgroundShell } from "../../core/background-shell.js";
 import {} from "./safety.js";
@@ -12,7 +13,7 @@ export * from "./fs-bash.js";
 export * from "./read-deny.js";
 import { BASH_READONLY_DEFAULT_ALLOW, } from "./bash-readonly-classifier.js";
 import { compileReadDeny } from "./read-deny.js";
-import { resolveReadFace } from "./read-face.js";
+import { deploymentReadFaceClampNotice, resolveReadFace } from "./read-face.js";
 export * from "./read-face.js";
 import {} from "./fs-shared.js";
 import { createReadFileTool } from "./fs-read.js";
@@ -39,6 +40,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
         readOnlyMount: readOnly,
         orgGoverned: false,
         fullShellReachable: includeShell && !readOnly,
+        onDeploymentClamp: () => deliverEngineNotice(opts.onNotice, deploymentReadFaceClampNotice()),
     });
     const tools = [
         createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace),

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

@@ -20,6 +20,11 @@ export interface NormalizedReadDenyEntry {
 /** A deny verdict: which entry's pattern matched. */
 export interface ReadDenyHit {
     pattern: string;
+    /** The view string the pattern actually matched (set by {@link CompiledReadDeny.matchTarget}: the
+     *  canonical key, or the lexical view when only the SPELLING matched). Disclosure must cite the
+     *  matched view — under a symlink/case alias the two strings differ, and naming the other one
+     *  sends the reader chasing a path the pattern does not match. */
+    matchedView?: string;
 }
 /** One compiled ripgrep glob flag for the traversal legs (`--iglob` = case-insensitive entry). */
 export interface ReadDenyRgGlob {

package/dist/tools/fs/read-deny.js

@@ -143,7 +143,15 @@ export function compileReadDeny(additions = [], layer = "additions") {
         entries: normalized,
         matchPath,
         matchTarget(canonicalKey, lexicalView) {
-            return matchPath(canonicalKey) ?? (lexicalView !== undefined ? matchPath(lexicalView) : null);
+            const canonical = matchPath(canonicalKey);
+            if (canonical !== null)
+                return { ...canonical, matchedView: canonicalKey };
+            if (lexicalView !== undefined) {
+                const lexical = matchPath(lexicalView);
+                if (lexical !== null)
+                    return { ...lexical, matchedView: lexicalView };
+            }
+            return null;
         },
         rgExclusionGlobs,
         rgProbeGlobs,