@sema-agent/core 5.29.0 → 5.31.0

package/dist/orchestration/workflow-primitives.js

@@ -22,14 +22,14 @@ function formatResourceClampNote(notes) {
     const parts = notes.map((n) => `${n.field}: requested ${n.requested === undefined ? "unset" : n.requested} → applied ${n.applied}`);
     return `workflow governance tightened this agent's resource limits (${parts.join("; ")})`;
 }
-export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThinking, parentPrincipal, parentCheckpointStoreDisabled) {
+export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThinking, parentPrincipal, parentCheckpointStoreDisabled, parentReadFace, parentReadDenyPatterns) {
     const agent = (spec, opts) => {
         if (typeof spec === "string")
             spec = { objective: spec };
         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();
@@ -42,6 +42,17 @@ export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThi
         if (parentCheckpointStoreDisabled === true) {
             childSpec.checkpointStore = null;
         }
+        if (parentReadFace) {
+            const pf = parentReadFace();
+            if (pf === "roots" && childSpec.readFace !== "roots")
+                childSpec.readFace = "roots";
+        }
+        if (parentReadDenyPatterns) {
+            const pd = parentReadDenyPatterns();
+            if (pd !== undefined && pd.length > 0) {
+                childSpec.readDenyPatterns = childSpec.readDenyPatterns !== undefined ? [...childSpec.readDenyPatterns, ...pd] : [...pd];
+            }
+        }
         if (onAgentSpawn) {
             return ctx.agentStream(childSpec, agentOpts).then((handle) => {
                 onAgentSpawn(handle);

package/dist/prompt-assembly/epoch.js

@@ -22,6 +22,7 @@ const PROBE_FACTS_OFF = {
     isSubagent: false,
     promptProfile: "simple",
     fableMitigations: false,
+    readFaceOpen: false,
 };
 const PROBE_FACTS_ON = {
     policyEnabled: true,
@@ -38,6 +39,7 @@ const PROBE_FACTS_ON = {
     isSubagent: true,
     promptProfile: "classic",
     fableMitigations: true,
+    readFaceOpen: true,
 };
 const PROBE_VECTORS = [
     PROBE_FACTS_OFF,

package/dist/prompt-assembly/packs/sema-default.js

@@ -1,4 +1,4 @@
-import { CYBER_RISK, EXECUTION_ENVIRONMENT, URL_SAFETY, SUMMARIZE_TOOL_RESULTS, WORKTREE_NOTICE, SUBAGENT_CONSENT_NOTICE, SUBAGENT_DELIVERY_NOTES, harnessHeadLines, } from "../../prompts/default.js";
+import { CYBER_RISK, EXECUTION_ENVIRONMENT, EXECUTION_ENVIRONMENT_OPEN_READS, URL_SAFETY, SUMMARIZE_TOOL_RESULTS, WORKTREE_NOTICE, SUBAGENT_CONSENT_NOTICE, SUBAGENT_DELIVERY_NOTES, harnessHeadLines, } from "../../prompts/default.js";
 import { GOAL_COMPLETION_GUIDANCE, ORCHESTRATION_AWARENESS, ORCHESTRATION_GUIDANCE, ORCHESTRATION_GUIDANCE_DEFERRED, SUPERVISOR_PROMPT, } from "../../prompts/supervisor.js";
 import { TEAMMATE_COMMUNICATION_ADDENDUM } from "../../prompts/coordinator.js";
 import { SIMPLE_ACTION_CAUTION, SIMPLE_ACT_DONT_REDERIVE, SIMPLE_AUTONOMY_FABLE, SIMPLE_COMMUNICATING_FABLE, SIMPLE_CORRECTIONS_FABLE, SIMPLE_DELIVERING_WORK_FABLE, SIMPLE_COMMUNICATING_LEAN, SIMPLE_CONTEXT_MANAGEMENT, SIMPLE_PRONOUNS, SIMPLE_TOOL_PARAM_JSON, SEMA_VERIFY_FRESH, SEMA_EVIDENCE_AUDIT, } from "../../prompts/simple-sections.js";
@@ -41,7 +41,7 @@ export const SEMA_DEFAULT_PACK = {
             rank: 240,
             ...CORE,
             admit: (i) => i.facts.policyEnabled || i.facts.isolationEnabled,
-            content: () => EXECUTION_ENVIRONMENT,
+            content: (i) => (i.facts.readFaceOpen === true ? EXECUTION_ENVIRONMENT_OPEN_READS : EXECUTION_ENVIRONMENT),
             legacyBlockId: "harness.context",
         },
         { id: "core/simple.communicating", slot: "harness", rank: 250, ...CORE, admit: (i) => i.facts.promptProfile !== "classic", content: (i) => (i.facts.fableMitigations === true ? SIMPLE_COMMUNICATING_FABLE : SIMPLE_COMMUNICATING_LEAN), legacyBlockId: "harness.context" },

package/dist/prompt-assembly/types.d.ts

@@ -41,6 +41,10 @@ export interface PromptRuntimeFacts {
     policyEnabled: boolean;
     hooksEnabled: boolean;
     isolationEnabled: boolean;
+    /** design/199 F8① — the resolved read face is OPEN (renders the execution-environment block's
+     *  open-reads first bullet). OPTIONAL: absence reads as false (roots wording, byte-identical),
+     *  so existing fact constructors keep compiling. */
+    readFaceOpen?: boolean;
     withinTaskCompactionEnabled: boolean;
     supervisorEnabled: boolean;
     orchestrationEnabled: boolean;

package/dist/prompts/default.d.ts

@@ -161,15 +161,9 @@ export declare const URL_SAFETY = "IMPORTANT: You must NEVER generate or guess U
  * runs before EVERY request, which is a stronger reason to warn than CC's.
  */
 export declare const SUMMARIZE_TOOL_RESULTS = "When working with tool results, write down any important information you might need later in your own response, as the original tool result may be cleared or summarized from the context later.";
-/**
- * Execution-environment / isolation behavior contract (design/64 §16.2 — verbatim, copy-paste-ready). Our
- * adaptation of CC's sandbox prompt: CC's `SandboxManager` (Seatbelt / allowedHosts) is product-specific and
- * we don't run it; this gives the model-visible contract for OUR exec-env (managed container / remote host)
- * + the design/37 policy gate — how to read a restriction (permission/network/policy-deny) vs an ordinary
- * failure, and to not circumvent a genuine restriction. Injected only when isolation OR a policy gate is
- * active (§16.2) — never claim an isolated environment that isn't there.
- */
-export declare const EXECUTION_ENVIRONMENT = "# Execution environment\nCommands run inside an isolated execution environment (a managed container or remote host), not on the operator's machine. Within it:\n- You can read and write within the project working directory. Writes outside it, or to system paths, may be denied by the environment or the permission policy.\n- Network access may be restricted to an allowlist. A blocked request fails at the network layer \u2014 it does not silently succeed.\n- A permission policy may intercept individual tool calls and deny them. A denied call did not run; do not re-issue the identical call. Follow the denial message's own guidance: a policy denial is something to reason about and adjust to, while a rejection by the user means stop and follow their direction rather than working around it. If you cannot tell why a call was denied, ask the user (via the AskUserQuestion tool, if available) rather than guessing.\n\nWhen a command fails, identify the cause before retrying:\n- Evidence of an environment/permission restriction: \"Operation not permitted\", \"Permission denied\" on an unexpected path, a network timeout/refusal to a host, or an explicit policy-deny message.\n- Ordinary failures (missing file, wrong argument, a non-zero exit from the program itself) are unrelated to isolation \u2014 fix the command rather than treating it as a restriction.\n\nIf a restriction genuinely blocks a necessary action, do NOT attempt to circumvent it (no privilege escalation, no disabling of guards, no destructive workarounds). Adjust your approach, or surface the limitation to the user with the specific evidence you saw.";
+export declare const EXECUTION_ENVIRONMENT: string;
+/** design/199 F8① — the open-read-face variant (first bullet tells the truth about reads). */
+export declare const EXECUTION_ENVIRONMENT_OPEN_READS: string;
 /**
  * design/97 CORE-6 (P1b) — worktree-isolation NOTICE. Composed (via {@link StablePromptContext.worktreeIsolated})
  * only when the task runs in an isolated git worktree, so the model treats inherited paths correctly. Generic
@@ -291,6 +285,10 @@ export interface EnvironmentFacts {
     /** Ruled 2026-08-05 (read-boundary whitelist): extra directories the READ faces may access
      *  (canonical) — reads auto-classify inside them, writes are refused exactly as before. */
     additionalReadDirectories?: readonly string[];
+    /** design/199 件A — the RESOLVED read-face containment state ("open" | "roots"; additive
+     *  structured key). Rendered only when "open" (the roots posture is the historical default and
+     *  renders nothing new — byte-compat). */
+    readFace?: "open" | "roots";
     /** OS name (uname -s) — remote = the container's, not the host's. */
     platform?: string;
     /** OS version (uname -r). */
@@ -444,6 +442,13 @@ export interface StablePromptContext {
      * line in {@link harnessContext}. Don't claim a deny mechanism the task doesn't have (§6.3).
      */
     policyEnabled?: boolean;
+    /**
+     * design/199 F8① — the resolved read face is OPEN: the `# Execution environment` block's first
+     * bullet renders its open-reads variant ({@link EXECUTION_ENVIRONMENT_OPEN_READS}) so the prompt
+     * never claims a read fence that is not there. Absent/false ⇒ the historical (roots) wording,
+     * byte-identical.
+     */
+    readFaceOpen?: boolean;
     /**
      * Whether hooks are wired (design/37) — drives the "hook output is user feedback" line in
      * {@link harnessContext}. Omitted/false → that line is left out (§6.3).

package/dist/prompts/default.js

@@ -108,9 +108,13 @@ You have no persistent memory store: what is said in this conversation is not au
 export const CYBER_RISK = `IMPORTANT: Assist with authorized security testing, defensive security, CTF challenges, and educational contexts. Refuse requests for destructive techniques, DoS attacks, mass targeting, supply chain compromise, or detection evasion for malicious purposes. Dual-use security tools (C2 frameworks, credential testing, exploit development) require clear authorization context: pentesting engagements, CTF competitions, security research, or defensive use cases.`;
 export const URL_SAFETY = `IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.`;
 export const SUMMARIZE_TOOL_RESULTS = `When working with tool results, write down any important information you might need later in your own response, as the original tool result may be cleared or summarized from the context later.`;
-export const EXECUTION_ENVIRONMENT = `# Execution environment
+function executionEnvironmentBlock(openReads) {
+    const readWriteLine = openReads
+        ? "- You can read files anywhere this environment exposes (a small sensitive-path deny list applies), and write within the project working directory. Writes outside it, or to system paths, may be denied by the environment or the permission policy."
+        : "- You can read and write within the project working directory. Writes outside it, or to system paths, may be denied by the environment or the permission policy.";
+    return `# Execution environment
 Commands run inside an isolated execution environment (a managed container or remote host), not on the operator's machine. Within it:
-- You can read and write within the project working directory. Writes outside it, or to system paths, may be denied by the environment or the permission policy.
+${readWriteLine}
 - Network access may be restricted to an allowlist. A blocked request fails at the network layer — it does not silently succeed.
 - A permission policy may intercept individual tool calls and deny them. A denied call did not run; do not re-issue the identical call. Follow the denial message's own guidance: a policy denial is something to reason about and adjust to, while a rejection by the user means stop and follow their direction rather than working around it. If you cannot tell why a call was denied, ask the user (via the AskUserQuestion tool, if available) rather than guessing.
 
@@ -119,6 +123,9 @@ When a command fails, identify the cause before retrying:
 - Ordinary failures (missing file, wrong argument, a non-zero exit from the program itself) are unrelated to isolation — fix the command rather than treating it as a restriction.
 
 If a restriction genuinely blocks a necessary action, do NOT attempt to circumvent it (no privilege escalation, no disabling of guards, no destructive workarounds). Adjust your approach, or surface the limitation to the user with the specific evidence you saw.`;
+}
+export const EXECUTION_ENVIRONMENT = executionEnvironmentBlock(false);
+export const EXECUTION_ENVIRONMENT_OPEN_READS = executionEnvironmentBlock(true);
 export const WORKTREE_NOTICE = `# Isolated worktree
 This task runs in its own isolated git worktree — a separate working copy whose root is the working directory shown in # Environment, NOT the repository's main checkout. Any absolute path you were given that points at the main checkout (or another worktree) refers to a DIFFERENT copy; translate it to the same relative path under this worktree's root before reading or writing, and operate only within this worktree. A file's content here may differ from the main checkout, so re-read a file in this worktree before editing it rather than assuming an earlier or external view is current.`;
 export const WORKTREE_STASH_WARNING = "The git stash stack is shared with the main checkout and all other worktrees, and other agent sessions may push or pop it concurrently. " +
@@ -151,7 +158,7 @@ export function harnessHeadLines(ctx) {
 export function harnessContext(ctx) {
     const blocks = [harnessHeadLines(ctx), CYBER_RISK, URL_SAFETY, SUMMARIZE_TOOL_RESULTS];
     if (ctx.policyEnabled || ctx.isolationEnabled)
-        blocks.push(EXECUTION_ENVIRONMENT);
+        blocks.push(ctx.readFaceOpen === true ? EXECUTION_ENVIRONMENT_OPEN_READS : EXECUTION_ENVIRONMENT);
     if (ctx.promptProfile !== "classic") {
         blocks.push(ctx.fableMitigations === true ? SIMPLE_COMMUNICATING_FABLE : SIMPLE_COMMUNICATING_LEAN);
         blocks.push(SIMPLE_PRONOUNS);
@@ -243,6 +250,9 @@ export function buildEnvironmentContext(facts) {
     if (facts.additionalReadDirectories && facts.additionalReadDirectories.length > 0) {
         lines.push(`Additional read-only directories: ${facts.additionalReadDirectories.map((d) => inlineUntrusted(d)).join(", ")}`);
     }
+    if (facts.readFace === "open") {
+        lines.push("File reads are not confined to the workspace root. A small sensitive-path deny list applies (see refusals for the exact pattern).");
+    }
     if (facts.isGitRepo !== undefined)
         lines.push(`Is a git repository: ${facts.isGitRepo ? "yes" : "no"}`);
     if (facts.gitBranch)

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

@@ -91,6 +91,27 @@ export interface BashReadonlyRootBoundary {
      *  out-of-root signal — the classifier does not know where it points, which is a different verdict
      *  from knowing it points outside). */
     homeDir?: string;
+    /** design/199 件B — 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 — RB-448/RB-451 state the same scope for the
+     *  containment half): ① operand TARGET matching only — no ancestor intersection, so `grep -r x ~/`
+     *  whose operand is `~` itself does not demote here (§3.4; the recursive reach residual belongs to
+     *  the full-bash lane's honest scope note); ② LEXICAL only — an in-root symlink whose target is a
+     *  guarded path reads as its innocent spelling here, exactly as it does for the containment half
+     *  (the enforcing/canonicalizing recheck is the bash_readonly leg's job via checkedPaths; the
+     *  classify auto-allow lane has no I/O seat by contract). The structured read faces judge BOTH
+     *  views (canonical + lexical) — this seat is the shell lane's honest-friction floor, not its
+     *  security boundary (§3.0). 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). */
+    denyMatch?: (resolvedPath: string) => string | null;
+    /** design/199 件A — the resolved read-face containment state. Under "open" the CONTAINMENT half of
+     *  this boundary is structurally satisfied (an out-of-roots operand is not a demotion; it reports
+     *  as a checked candidate instead), while the deny half above keeps judging in both faces (§2.0).
+     *  Absent ⇒ "roots" (byte-compat). The `bash_readonly` face never passes this seat — its
+     *  containment is load-bearing and never opens. */
+    face?: "open" | "roots";
 }
 /**
  * RB-412 — the structured verdict of {@link classifyCompoundReadonlyDetailed}. `reason === undefined`
@@ -151,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
@@ -203,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,10 +692,17 @@ 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")
                 return { reason: finding.reason };
+            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}`,
+                };
+            }
             if (finding.kind === "inside") {
                 if (!inside.includes(finding.path))
                     inside.push(finding.path);
@@ -598,11 +713,25 @@ 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);
+                continue;
+            }
             if (!outside.some((o) => o.path === finding.path))
                 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(", ");
@@ -713,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/fs-bash.d.ts

@@ -40,6 +40,13 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
 export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => {
     reversible: boolean;
 };
+/**
+ * design/199 D-6 — 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
+ * the read-only allowlist face (`core.bash_readonly@1`). Consumed by prepare-task's
+ * fullShellReachable roster assertion (its first load-bearing consumer).
+ */
+export declare const FULL_SHELL_CONTRACT_ID = "core.bash@1";
 /** The CC-verbatim exit-1 interpretation for `command`, or undefined when exit 1 means a real error.
  *  Conservative parse: last `;`/`&&`/`||`/newline statement → last `|` pipeline segment → leading
  *  command name (env-assignments skipped, path prefix stripped); `git grep`/`git diff` special-cased

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

@@ -10,7 +10,7 @@ import { imageMagicMatches, withinAnyRoot } from "./safety.js";
 import { isRemoteExecutionEnv, hasDestroy, isIsolated } from "../../core/remote-env.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
-import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonly, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
+import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
     return (args) => {
@@ -21,11 +21,16 @@ export function bashReversibilityProbe(allow, boundary) {
         if (a?.run_in_background === true)
             return { reversible: false };
         const resolved = typeof boundary === "function" ? boundary() : boundary;
-        if (classifyCompoundReadonly(command, allowSet, resolved) === undefined)
+        const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
+        if (detailed.reason === undefined) {
+            if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0)
+                return { reversible: false };
             return { reversible: true };
+        }
         return { reversible: classifyBoundedReadonlyPollLoop(command, allowSet, resolved) === undefined };
     };
 }
+export const FULL_SHELL_CONTRACT_ID = "core.bash@1";
 const EXIT1_INTERPRETATION = {
     grep: "No matches found",
     rg: "No matches found",
@@ -497,7 +502,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
     const bgEnvIsolatedOwned = hasDestroy(env) && isIsolated(env);
     return defineTool({
         name: "Bash",
-        contract: { contractId: "core.bash@1", implementationRevision: "1" },
+        contract: { contractId: FULL_SHELL_CONTRACT_ID, implementationRevision: "1" },
         description: bashDescription(coAuthor, timeoutCaps, bgNotifies, bgRetained, bgSessionScoped, bgEnvIsolatedOwned),
         parameters: Type.Object({
             command: Type.String({ description: "The command to execute" }),

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

@@ -33,7 +33,7 @@ type ReadPdfReturn = string | {
  * Every degraded return carries `details.fallback = { level, reason }` (telemetry on the structured frame).
  * `caps` absent ⇒ fully capable (byte-compat: native document block; the brain placeholder still guards).
  */
-export declare function readPdfFile(env: ExecutionEnv, path: string, key: string, pages: string | undefined, signal: AbortSignal | undefined, downsamplerOpt: ReadImageDownsamplerOption, cwd: string, preRead?: Uint8Array, caps?: PdfModelCapabilities): Promise<ReadPdfReturn>;
+export declare function readPdfFile(env: ExecutionEnv, path: string, key: string, pages: string | undefined, signal: AbortSignal | undefined, downsamplerOpt: ReadImageDownsamplerOption, cwd: string, preRead?: Uint8Array, caps?: PdfModelCapabilities, readDeny?: import("./read-deny.js").ReadDenyMatcher): Promise<ReadPdfReturn>;
 /** E1: readPdfFile's own return type stays `ReadPdfReturn` (its INTERNAL string-means-error dispatch
  *  contract, shared with pdfPagesToImageBlocks) — the isError flag is applied once, here, at the tool's
  *  actual execute() boundary, not inside the helper. */

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

@@ -30,13 +30,13 @@ function boundPdfExtractedText(text) {
         return { body: text, truncated: false };
     return { body: text.slice(0, MAX_READ_BYTES), truncated: true };
 }
-export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, preRead, caps) {
+export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, preRead, caps, readDeny) {
     const cap = caps ?? { document: true, vision: true };
     const meta = await env.fileInfo(key, signal);
     if (!meta.ok) {
         const ex = await env.exists(key, signal);
         if (ex.ok && !ex.value)
-            return `Error (Read): ${await enoentMessage(env, key, cwd, signal)}`;
+            return `Error (Read): ${await enoentMessage(env, key, cwd, signal, readDeny)}`;
         return `Error (Read): cannot stat PDF "${path}" to verify its size before reading: ${meta.error.message}`;
     }
     if (meta.value.kind === "directory") {

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

@@ -5,4 +5,4 @@ import { type ReadImageDownsamplerOption, type CwdRef } from "./fs-shared.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): AgentTool;
+}) => boolean, readCyberReminder?: boolean, readDeny?: import("./read-deny.js").ReadDenyMatcher, readFace?: import("./read-face.js").ReadFace): AgentTool;