@f5-sales-demo/xcsh 19.98.9 → 19.99.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.98.9",
+	"version": "19.99.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -57,13 +57,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.98.9",
-		"@f5-sales-demo/pi-agent-core": "19.98.9",
-		"@f5-sales-demo/pi-ai": "19.98.9",
-		"@f5-sales-demo/pi-natives": "19.98.9",
-		"@f5-sales-demo/pi-resource-management": "19.98.9",
-		"@f5-sales-demo/pi-tui": "19.98.9",
-		"@f5-sales-demo/pi-utils": "19.98.9",
+		"@f5-sales-demo/xcsh-stats": "19.99.0",
+		"@f5-sales-demo/pi-agent-core": "19.99.0",
+		"@f5-sales-demo/pi-ai": "19.99.0",
+		"@f5-sales-demo/pi-natives": "19.99.0",
+		"@f5-sales-demo/pi-resource-management": "19.99.0",
+		"@f5-sales-demo/pi-tui": "19.99.0",
+		"@f5-sales-demo/pi-utils": "19.99.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/exec/bash-executor.ts

@@ -6,10 +6,27 @@
 import * as fs from "node:fs/promises";
 import { executeShell, Shell } from "@f5-sales-demo/pi-natives";
 import { Settings } from "../config/settings";
+import type { ContainmentFence } from "../sandbox/containment";
 import { OutputSink } from "../session/streaming-output";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
 import { NON_INTERACTIVE_ENV } from "./non-interactive-env";
 
+/**
+ * The fence as the napi boundary wants it: plain mutable arrays, or absent for unrestricted.
+ *
+ * Shared with the PTY path, which needs the identical conversion. One converter, so the two
+ * execution paths cannot end up disagreeing about what they hand the native layer.
+ */
+export function fenceForNative(fence: ContainmentFence | undefined) {
+	if (!fence) return undefined;
+	return {
+		allow: [...fence.allow],
+		allowReadOnly: [...fence.allowReadOnly],
+		allowWriteOnly: [...fence.allowWriteOnly],
+		deny: [...fence.deny],
+	};
+}
+
 export interface BashExecutorOptions {
 	cwd?: string;
 	timeout?: number;
@@ -24,6 +41,16 @@ export interface BashExecutorOptions {
 	artifactId?: string;
 	/** Mask sensitive values (e.g. env var secrets) in output. */
 	maskSecrets?: (text: string) => string;
+	/**
+	 * Which paths this command may reach, enforced inside the shell rather than guessed from the
+	 * command text (#2554).
+	 *
+	 * Absent means unrestricted, and absent is the default on purpose. Only the model's `bash` tool
+	 * supplies one — `executeBash` is also reached by user-typed `!cmd`, by RPC `bash`, and the same
+	 * brush-core runs credential helpers and the interactive `xcsh shell`. Fencing those would break
+	 * API-key resolution and confine the operator at their own prompt.
+	 */
+	fence?: ContainmentFence;
 }
 
 export interface BashResult {
@@ -186,6 +213,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 						env: commandEnv,
 						timeoutMs: options?.timeout,
 						signal: runAbortController.signal,
+						fence: fenceForNative(options?.fence),
 					},
 					(err, chunk) => {
 						if (!err) {
@@ -202,6 +230,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 						snapshotPath: snapshotPath ?? undefined,
 						timeoutMs: options?.timeout,
 						signal: runAbortController.signal,
+						fence: fenceForNative(options?.fence),
 					},
 					(err, chunk) => {
 						if (!err) {

package/src/internal-urls/build-info-runtime.ts

@@ -3,6 +3,8 @@ import * as path from "node:path";
 import { prompt } from "@f5-sales-demo/pi-utils";
 import { $ } from "bun";
 import activeModelTemplate from "../prompts/internal-urls/active-model.md" with { type: "text" };
+import containmentTemplate from "../prompts/internal-urls/containment.md" with { type: "text" };
+import type { ContainmentStatus } from "../sandbox/containment";
 import type { ContextStatus } from "../services/xcsh-context";
 import type { ActiveModelSnapshot } from "../session/active-model";
 import { BUILD_INFO, type BuildInfo } from "./build-info.generated";
@@ -157,10 +159,23 @@ function renderActiveModel(model: ActiveModelSnapshot | null): string {
 	return prompt.render(activeModelTemplate, { model });
 }
 
+/**
+ * What is enforcing the filesystem boundary, and what that does and does not guarantee.
+ *
+ * Stated here because two sessions can look identical and offer very different guarantees: with an OS
+ * backend a path is checked where it is opened and the spelling cannot matter, while without one the
+ * only check reads the command text. An operator has no other way to tell which they have.
+ */
+function renderContainment(containment: ContainmentStatus | null): string {
+	if (!containment) return "";
+	return prompt.render(containmentTemplate, { containment });
+}
+
 export function renderAboutDoc(
 	info: RuntimeBuildInfo,
 	context: ContextStatus | null,
 	model: ActiveModelSnapshot | null,
+	containment: ContainmentStatus | null,
 ): string {
 	return [
 		"# xcsh — identity and build fingerprint",
@@ -183,6 +198,7 @@ export function renderAboutDoc(
 		"",
 		renderPlatformContext(context, Date.now()),
 		renderActiveModel(model),
+		renderContainment(containment),
 		"## Source of truth",
 		"",
 		`- Repository: ${info.repoUrl}`,

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.98.9",
-	"commit": "f920b739147c8af141a54972d353e0522a276fcc",
-	"shortCommit": "f920b73",
+	"version": "19.99.0",
+	"commit": "8020e6b8aa7ae0c4fd4ac6da9ee9fa81b77182f0",
+	"shortCommit": "8020e6b",
 	"branch": "main",
-	"tag": "v19.98.9",
-	"commitDate": "2026-07-28T14:28:13Z",
-	"buildDate": "2026-07-28T15:05:19.433Z",
+	"tag": "v19.99.0",
+	"commitDate": "2026-07-28T17:45:44Z",
+	"buildDate": "2026-07-28T18:11:25.457Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/f920b739147c8af141a54972d353e0522a276fcc",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.98.9"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/8020e6b8aa7ae0c4fd4ac6da9ee9fa81b77182f0",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.99.0"
 };

package/src/internal-urls/plugin-resolve.ts

@@ -55,12 +55,12 @@ function contentTypeFor(filePath: string): InternalResource["contentType"] {
 /**
  * Extensions a plugin may legitimately declare that are NOT text.
  *
- * Reading one as UTF-8 corrupts it, and nobody wants 91 KB of mangled bytes in a prompt
- * either — the MEDDPICC plugin's `meddpicc-template.xlsx` is exactly that size. What a
- * caller needs is where the file is, so it can be copied, opened, or handed to a tool
- * that understands the format; so a binary resource resolves to its location, not its
- * contents. Deliberately a small allow-list of formats plugins actually ship rather than
- * content sniffing, so the decision is inspectable.
+ * Reading one as UTF-8 corrupts it, and nobody wants tens of kilobytes of mangled bytes in a
+ * prompt either — a spreadsheet or a slide deck runs to that easily. What a caller needs is
+ * where the file is, so it can be copied, opened, or handed to a tool that understands the
+ * format; so a binary resource resolves to its location, not its contents. Deliberately a
+ * small allow-list of formats plugins actually ship rather than content sniffing, so the
+ * decision is inspectable.
  */
 const BINARY_EXTENSIONS = new Set([
 	".xlsx",

package/src/internal-urls/xcsh-protocol.ts

@@ -27,6 +27,7 @@
  */
 import * as path from "node:path";
 import { logger } from "@f5-sales-demo/pi-utils";
+import type { ContainmentStatus } from "../sandbox/containment";
 import type { ContextStatus } from "../services/xcsh-context";
 import type { ActiveModelSnapshot } from "../session/active-model";
 import { type ApiCatalogResolver, createApiCatalogResolver } from "./api-catalog-resolve";
@@ -311,6 +312,12 @@ export interface InternalDocsProtocolOptions {
 	 * reflects a mid-session switch instead of the model the session launched with (#2459).
 	 */
 	readonly getActiveModel?: () => ActiveModelSnapshot | null;
+	/**
+	 * What is enforcing the filesystem boundary. A live getter, like `getActiveModel`, because
+	 * `--no-sandbox` and `sandbox.enabled` can differ per session and the answer must not be captured
+	 * at construction.
+	 */
+	readonly getContainment?: () => ContainmentStatus | null;
 	readonly apiSpecResolver?: ApiSpecResolver;
 	readonly apiCatalogResolver?: ApiCatalogResolver;
 	readonly getPluginRoots?: GetPluginRoots;
@@ -323,6 +330,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	readonly #resolveBuildInfo: () => Promise<RuntimeBuildInfo>;
 	readonly #getContextStatus: (() => ContextStatus | null) | undefined;
 	readonly #getActiveModel: (() => ActiveModelSnapshot | null) | undefined;
+	readonly #getContainment: (() => ContainmentStatus | null) | undefined;
 	#apiSpecResolver: ApiSpecResolver | null;
 	#apiCatalogResolver: ApiCatalogResolver | null;
 	#terraformResolver: TerraformResolver | null;
@@ -338,6 +346,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		this.#resolveBuildInfo = options.resolveBuildInfo ?? getRuntimeBuildInfo;
 		this.#getContextStatus = options.getContextStatus;
 		this.#getActiveModel = options.getActiveModel;
+		this.#getContainment = options.getContainment;
 		this.#apiSpecResolver = options.apiSpecResolver ?? null;
 		this.#apiCatalogResolver = options.apiCatalogResolver ?? null;
 		this.#terraformResolver = null;
@@ -814,7 +823,8 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			const info = await this.#resolveBuildInfo();
 			const context = this.#getContextStatus?.() ?? null;
 			const activeModel = this.#getActiveModel?.() ?? null;
-			const content = renderAboutDoc(info, context, activeModel);
+			const containment = this.#getContainment?.() ?? null;
+			const content = renderAboutDoc(info, context, activeModel, containment);
 			return {
 				url: url.href,
 				content,

package/src/prompts/internal-urls/containment.md

@@ -0,0 +1,35 @@
+## Sandbox containment
+
+{{#if containment.enabled}}
+Filesystem isolation is **on**. Enforcement for the `bash` tool: **{{containment.backend}}**.
+
+{{#if containment.osEnforced}}
+Your shell is confined by the operating system, not by inspecting the command you wrote. A path is
+checked where it is actually opened, after the shell has expanded variables, resolved aliases and
+followed symlinks — so how a path is spelled does not change what is reachable.
+- Ordinary work is unrestricted: system paths, `/tmp`, package caches (`~/.bun`, `~/.cargo`, …), the
+  network, and running programs are all untouched.
+- What is refused: reading or writing outside the session directory — another checkout, `~/.ssh`,
+  `~/.aws`, `~/Documents`, and other sessions' transcripts. `~/.gitconfig` is readable, not writable.
+- `cd` out of the session tree is refused, because every later relative path would resolve there.
+
+If a command is refused, do not try to reach the same path a different way: the boundary is enforced
+below the command text, so no rewriting will succeed. Say what you needed and why. The operator can
+widen it with `--allow-path <dir>`, which grants read and write.
+{{else}}
+On this platform there is **no OS-level backend**, so the boundary is enforced only by scanning the
+command text before it runs. That check is best-effort by construction: it reads what you wrote
+rather than what the shell will do, so a path assembled at runtime or reached through an unusual
+spelling may not be caught.
+
+Treat the boundary as a statement of intent rather than a guarantee here, and do not go looking for
+paths outside the session directory on the assumption that something would stop you.
+{{/if}}
+{{else}}
+Filesystem isolation is **off** for this session — started with `--no-sandbox`, or
+`sandbox.enabled` is false. Every path on this machine is reachable.
+
+Nothing is confining you, so the judgement is yours: stay within the directory the operator is
+working in unless they asked for something else, and do not read private files elsewhere on the
+machine because you happen to be able to.
+{{/if}}

package/src/sandbox/containment.ts

@@ -0,0 +1,269 @@
+/**
+ * The containment fence: what the shell may reach, enforced below the command text.
+ *
+ * This is deliberately NOT `SandboxPolicy`. That object is deny-by-default — "a path matched by no
+ * rule is denied" — which is the right posture for the structured file tools and the wrong one here.
+ * Confining a shell that way refuses ordinary work: measured on macOS 26.3, a deny-default seatbelt
+ * profile could not even `execvp /bin/cat`.
+ *
+ * So the fence is gentle. It restricts no operation — `/usr`, `/tmp`, package caches, the network and
+ * process execution are never mentioned, and nothing that works today stops working. The single thing
+ * it prevents is the assistant wandering the filesystem: reading or writing another customer's
+ * checkout, `~/.ssh`, `~/Documents`. That is where the cross-customer risk actually lives (#2554).
+ *
+ * Produced declaratively rather than as an ordered rule list, because the two backends disagree about
+ * order: seatbelt evaluates rules in sequence with the last match winning, while Landlock only grants
+ * and cannot deny a subpath of something granted. Both can compile `{allow, allowReadOnly, deny}` with
+ * deny-wins, so neither has to reason about ordering.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getMemoriesDir, getSessionsDir, getXCSHContextsDir, pathIsWithin } from "@f5-sales-demo/pi-utils";
+
+export type FenceAccess = "read" | "write";
+export type FenceVerdict = "allow" | "deny";
+
+export interface ContainmentFence {
+	/** Canonical roots the shell may read and write. */
+	readonly allow: readonly string[];
+	/** Canonical roots the shell may read but not write. */
+	readonly allowReadOnly: readonly string[];
+	/** Canonical roots the shell may write but not read. */
+	readonly allowWriteOnly: readonly string[];
+	/** Canonical roots denied in both directions, winning over any allow they sit inside. */
+	readonly deny: readonly string[];
+}
+
+export interface ContainmentOptions {
+	/** The session's working directory. Must exist — it is the one root that cannot be dropped. */
+	workspace: string;
+	/** Overridable for tests; defaults to the real home directory. */
+	home?: string;
+	/** A session-specific temp dir, if the session has one. */
+	sessionTmp?: string;
+	/** Roots granted read+write, as `--allow-path` does. */
+	extraRoots?: readonly string[];
+	/** Roots granted read only — `sandbox.allowRead`. Must NOT become writable. */
+	readOnlyRoots?: readonly string[];
+	/** Roots granted write only — `sandbox.allowWrite`. */
+	writeOnlyRoots?: readonly string[];
+	/** Cross-session leak roots to deny. Defaults to the real memories/sessions/contexts dirs. */
+	leakRoots?: readonly string[];
+}
+
+/**
+ * Directories inside home that hold tool state rather than the operator's data. Denying home without
+ * carving these back out is what would break `bun install`, `cargo build` and `npm ci` — the exact
+ * class of breakage this fence must not cause.
+ *
+ * `~/Library/Caches` is macOS-wide tool cache; it is not customer data and several toolchains use it.
+ */
+const CACHE_DIRS = [
+	// Artifact subdirectories only. Granting the parents put credentials inside the fence —
+	// `.cargo/credentials.toml`, `.m2/settings.xml`, `.npm/_authToken` — and `.cargo/config.toml`
+	// and `.gradle/init.gradle` are worse than credentials: both can redirect a later build, so a
+	// write there is persistence rather than theft. Found by adversarial review, verified writable.
+	path.join(".bun", "install", "cache"),
+	path.join(".cargo", "registry"),
+	path.join(".cargo", "git"),
+	path.join(".npm", "_cacache"),
+	path.join(".m2", "repository"),
+	path.join(".gradle", "caches"),
+	path.join(".gradle", "wrapper"),
+	path.join(".yarn", "berry", "cache"),
+	path.join(".rustup", "toolchains"),
+	path.join(".rustup", "downloads"),
+	// No credential convention of their own, so granted whole.
+	".pnpm-store",
+	".deno",
+	path.join("Library", "Caches"),
+	path.join("Library", "pnpm"),
+];
+
+/** Read-only inside home: configuration a tool needs to behave correctly, but must not rewrite. */
+const READ_ONLY_HOME = [".gitconfig", path.join(".config", "git")];
+
+/**
+ * Canonicalise a root, or return undefined when it is absent.
+ *
+ * Canonicalisation is load-bearing rather than tidiness: a seatbelt `(subpath "/tmp/x")` rule grants
+ * nothing, because the real path is `/private/tmp/x`. A rule that appears to enforce and does not is
+ * the worst outcome available, so a root that cannot be resolved is dropped rather than emitted.
+ */
+function canonical(root: string): string | undefined {
+	try {
+		return fs.realpathSync(root);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Parents that must never be denied, however the workspace is placed.
+ *
+ * Denying the workspace's parent closes sibling access, but the parent is not always a sibling
+ * container. A workspace directly under `/`, under a system directory, or under the OS temp dir would
+ * otherwise deny `/`, `/usr` or `/tmp` — refusing exactly the work this fence is supposed to leave
+ * alone. The home tree is excluded too because the home deny already covers it, at the right depth.
+ */
+function tooBroadToDeny(candidate: string): boolean {
+	if (candidate === path.parse(candidate).root) return true;
+	const never = [
+		safeReal(os.tmpdir()),
+		"/usr",
+		"/bin",
+		"/sbin",
+		"/lib",
+		"/opt",
+		"/etc",
+		"/dev",
+		"/proc",
+		"/sys",
+		"/var",
+		"/private",
+		"/System",
+		"/Library",
+		"/Users",
+		"/home",
+	];
+	return never.includes(candidate);
+}
+
+/** realpath without throwing, for building the never-deny list. */
+function safeReal(input: string): string {
+	try {
+		return fs.realpathSync(input);
+	} catch {
+		return input;
+	}
+}
+
+/** The deepest root containing `candidate`, so a nested rule beats the broader one it sits inside. */
+function deepestMatch(roots: readonly string[], candidate: string): string | undefined {
+	let best: string | undefined;
+	for (const root of roots) {
+		if (!pathIsWithin(root, candidate)) continue;
+		if (best === undefined || root.length > best.length) best = root;
+	}
+	return best;
+}
+
+/** Build the fence for a session. Throws only when the workspace itself cannot be resolved. */
+export function buildContainmentFence(options: ContainmentOptions): ContainmentFence {
+	const workspace = canonical(options.workspace);
+	if (workspace === undefined) {
+		throw new Error(
+			`sandbox containment: cannot canonicalise the session workspace ${options.workspace}. ` +
+				"A fence built on an unresolved path would silently grant nothing, so refusing to build one.",
+		);
+	}
+
+	const home = canonical(options.home ?? os.homedir());
+	const allow = new Set<string>([workspace]);
+	const allowReadOnly = new Set<string>();
+	const allowWriteOnly = new Set<string>();
+	const deny = new Set<string>();
+
+	// Home is one fence. The workspace's own parent is the other, and it is the one that matters when
+	// checkouts live outside home: with /work/customer-a as the workspace, /work/customer-b matched no
+	// rule at all and was readable and writable. Denying the parent closes sibling access wherever the
+	// checkouts sit, which is the threat this exists for.
+	if (home !== undefined && home !== workspace) deny.add(home);
+	const parent = path.dirname(workspace);
+	if (parent !== workspace && !tooBroadToDeny(parent)) deny.add(parent);
+
+	for (const root of [options.sessionTmp, ...(options.extraRoots ?? [])]) {
+		if (root === undefined) continue;
+		const resolved = canonical(root);
+		if (resolved !== undefined) allow.add(resolved);
+	}
+	// Kept distinct. Merging them into one read+write list made a folder shared for reading writable,
+	// undoing the read/write split built for #2516 — found by adversarial review.
+	for (const root of options.readOnlyRoots ?? []) {
+		const resolved = canonical(root);
+		if (resolved !== undefined) allowReadOnly.add(resolved);
+	}
+	for (const root of options.writeOnlyRoots ?? []) {
+		const resolved = canonical(root);
+		if (resolved !== undefined) allowWriteOnly.add(resolved);
+	}
+
+	if (home !== undefined) {
+		// Granted whether or not they exist yet. `~/.bun` has to be writable *before* the first
+		// `bun install` creates it, so dropping absent caches would break exactly the first run.
+		// Canonicalised when present, so a symlinked cache resolves to its real location.
+		for (const cache of CACHE_DIRS) allow.add(canonical(path.join(home, cache)) ?? path.join(home, cache));
+		for (const config of READ_ONLY_HOME) {
+			allowReadOnly.add(canonical(path.join(home, config)) ?? path.join(home, config));
+		}
+	}
+
+	// Cross-session leak roots. These may sit *under* an allowed root — the agent dir is inside home,
+	// and a session whose workspace is the agent dir would otherwise re-expose every other session's
+	// transcript. `fenceVerdict` resolves that by depth, so nesting is safe rather than accidental.
+	const leaks = options.leakRoots ?? [getMemoriesDir(), getSessionsDir(), getXCSHContextsDir()];
+	for (const leak of leaks) {
+		const resolved = canonical(leak);
+		if (resolved !== undefined) deny.add(resolved);
+	}
+
+	return {
+		allow: [...allow],
+		allowReadOnly: [...allowReadOnly],
+		allowWriteOnly: [...allowWriteOnly],
+		deny: [...deny],
+	};
+}
+
+/**
+ * Whether the fence permits `access` on `candidate`.
+ *
+ * Deepest match wins, and a deny beats an allow at equal depth — the same precedence `SandboxPolicy`
+ * uses, so the two layers cannot disagree about a path they both see. Unlike that policy, the default
+ * here is **allow**: a path matched by no rule is outside the fence and none of its business.
+ */
+export function fenceVerdict(fence: ContainmentFence, candidate: string, access: FenceAccess): FenceVerdict {
+	const denied = deepestMatch(fence.deny, candidate);
+	const readOnly = deepestMatch(fence.allowReadOnly, candidate);
+	const writeOnly = deepestMatch(fence.allowWriteOnly, candidate);
+	const allowed = deepestMatch(fence.allow, candidate);
+
+	const depth = (root: string | undefined): number => (root === undefined ? -1 : root.length);
+	const deepest = Math.max(depth(denied), depth(readOnly), depth(writeOnly), depth(allowed));
+
+	// Deny first at equal depth: the leak roots depend on it.
+	if (denied !== undefined && depth(denied) === deepest) return "deny";
+	if (readOnly !== undefined && depth(readOnly) === deepest) return access === "read" ? "allow" : "deny";
+	if (writeOnly !== undefined && depth(writeOnly) === deepest) return access === "write" ? "allow" : "deny";
+	if (allowed !== undefined && depth(allowed) === deepest) return "allow";
+	return "allow";
+}
+
+/** Which mechanism is actually enforcing the boundary for the `bash` tool. */
+export type ContainmentBackend = "seatbelt" | "landlock" | "scanner-only" | "disabled";
+
+export interface ContainmentStatus {
+	readonly enabled: boolean;
+	readonly backend: ContainmentBackend;
+	/** True when the kernel enforces it, false when only the command-text scan does. */
+	readonly osEnforced: boolean;
+}
+
+/**
+ * What is actually enforcing the boundary right now.
+ *
+ * Reported so an operator can tell a confined session from an unconfined one. The distinction is not
+ * cosmetic: with a backend, a path is checked where it is opened and the spelling cannot matter;
+ * without one, the only check reads the command text and is best-effort by construction. Two sessions
+ * that look identical can offer very different guarantees, and `xcsh://about` is where that is stated.
+ *
+ * Deliberately not surfaced at startup or anywhere in the TUI — the operator asked for no UI change.
+ */
+export function containmentStatus(enabled: boolean, platform: string = process.platform): ContainmentStatus {
+	if (!enabled) return { enabled: false, backend: "disabled", osEnforced: false };
+	// Only the macOS seatbelt backend exists today. Linux Landlock is a follow-up; until it lands,
+	// Linux and Windows fall back to the scanner and say so rather than implying enforcement.
+	if (platform === "darwin") return { enabled: true, backend: "seatbelt", osEnforced: true };
+	return { enabled: true, backend: "scanner-only", osEnforced: false };
+}

package/src/sandbox/enforce.ts

@@ -14,8 +14,22 @@
  * Arbitrary-code tools (`bash`, `python`) cannot be fully contained in-process: this
  * checks the `cwd` argument precisely and scans the command/code for path tokens
  * (bare, quoted, `~`, `..`, absolute) that escape the tree. OS system paths are exempt.
- * This is best-effort; the opt-in OS-level sandbox (Phase 2) is the airtight enforcement
- * for both bash and python.
+ *
+ * **This scan is no longer the boundary for `bash` on macOS.** Containment now runs below the command
+ * text (`sandbox/containment.ts`, #2554): the shell's own `cd` and redirections are checked where they
+ * act, and spawned children are confined by a seatbelt profile. A path is therefore decided after
+ * expansion, alias resolution and symlink following, which is what closed the escapes this scan kept
+ * leaking — #2470, #2516, #2520, #2524, #2540, #2542, #2553, and GHSA-q4hg.
+ *
+ * What remains this file's job:
+ *  - every structured file tool (`read`/`write`/`edit`/`grep`/…), which has no subprocess to confine
+ *  - `python`, which is not covered by the shell fence at all
+ *  - `bash` on platforms with no backend — Linux Landlock is a follow-up, Windows has no equivalent —
+ *    where this is again the only layer, and `xcsh://about` says so
+ *  - a fast pre-check that produces a readable refusal before a command runs
+ *
+ * So: keep it, and do not extend it. Another spelling caught here buys little now, and the pattern of
+ * adding one has a poor record — two adversarial rounds on the #2542 fix alone produced six bypasses.
  */
 import * as path from "node:path";
 import { expandPath, parseFindPattern, parseSearchPath, resolveToCwd, splitTopLevel } from "../tools/path-utils";

package/src/sdk.ts

@@ -96,6 +96,8 @@ import {
 } from "./mcp/discoverable-tool-metadata";
 import { buildMemoryToolDeveloperInstructions, getMemoryRoot, startMemoryStartupTask } from "./memories";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
+import { containmentStatus } from "./sandbox/containment";
+import { resolveSessionPolicy } from "./sandbox/session-policy";
 import {
 	collectEnvSecrets,
 	deobfuscateSessionContext,
@@ -1154,6 +1156,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						return null;
 					}
 				},
+				// Read live rather than captured, for the same reason as the model: `--no-sandbox` and
+				// `sandbox.enabled` are per-session, so the answer must reflect this session (#2554).
+				getContainment: () => containmentStatus(resolveSessionPolicy(process.cwd(), settings) !== undefined),
 				// Read live rather than captured: `session.model` is a read-through to agent state, so a
 				// mid-session Ctrl+P switch shows up on the next xcsh://about read (#2459).
 				getActiveModel: () =>

package/src/tools/bash-interactive.ts

@@ -12,8 +12,10 @@ import {
 } from "@f5-sales-demo/pi-tui";
 import type { Terminal as XtermTerminalType } from "@xterm/headless";
 import xterm from "@xterm/headless";
+import { fenceForNative } from "../exec/bash-executor";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
 import type { Theme } from "../modes/theme/theme";
+import type { ContainmentFence } from "../sandbox/containment";
 import { OutputSink, type OutputSummary } from "../session/streaming-output";
 import { sanitizeWithImagePassthrough } from "../utils/image-passthrough";
 import { formatStatusIcon, replaceTabs } from "./render-utils";
@@ -293,6 +295,17 @@ export async function runInteractiveBashPty(
 		artifactPath?: string;
 		artifactId?: string;
 		maskSecrets?: (text: string) => string;
+		/**
+		 * Filesystem boundary for this command. `undefined` means unrestricted, and must be said
+		 * rather than omitted.
+		 *
+		 * Deliberately a required key with an optional value. This path is reached only from the
+		 * model's `bash` tool, and it was unfenced precisely because the field was easy to leave out
+		 * of one of two call sites — the boundary ended up opt-out via a parameter the model itself
+		 * supplies. Requiring the key makes that omission a type error instead of a silent hole; a
+		 * future caller that genuinely wants no fence has to write `fence: undefined` and mean it.
+		 */
+		fence: ContainmentFence | undefined;
 	},
 ): Promise<BashInteractiveResult> {
 	const sink = new OutputSink({
@@ -360,6 +373,7 @@ export async function runInteractiveBashPty(
 						signal: options.signal,
 						cols,
 						rows,
+						fence: fenceForNative(options.fence),
 					},
 					(err, chunk) => {
 						if (finished || err || !chunk) return;

package/src/tools/bash.ts

@@ -16,6 +16,7 @@ import { resolveLocalRoot } from "../internal-urls/local-protocol";
 import { truncateToVisualLines } from "../modes/components/visual-truncate";
 import type { Theme } from "../modes/theme/theme";
 import bashDescription from "../prompts/tools/bash.md" with { type: "text" };
+import { buildContainmentFence } from "../sandbox/containment";
 import { resolveSessionPolicy } from "../sandbox/session-policy";
 import { SECRET_ENV_PATTERNS, type SecretObfuscator } from "../secrets";
 import { DEFAULT_MAX_BYTES, TailBuffer } from "../session/streaming-output";
@@ -392,6 +393,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 						artifactPath,
 						artifactId,
 						maskSecrets: options.maskSecrets,
+						fence: this.#containmentFence(),
 						onChunk: chunk => {
 							tailBuffer.append(chunk);
 							const preview = options.maskSecrets ? options.maskSecrets(tailBuffer.text()) : tailBuffer.text();
@@ -475,6 +477,31 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		return Math.max(0, Math.min(this.#autoBackgroundThresholdMs, timeoutMs - timeoutBufferMs));
 	}
 
+	/**
+	 * The fence for this invocation, or undefined when isolation is off.
+	 *
+	 * Built here rather than in the executor because `executeBash` is shared: user-typed `!cmd` and
+	 * RPC `bash` reach it too, and the same brush-core runs credential helpers and the interactive
+	 * `xcsh shell`. Only the model's tool call is fenced (#2554).
+	 *
+	 * Uses the session's *live* cwd so an in-tree `cd` keeps working, while the fence's own roots
+	 * decide what is reachable — which is what stops a `cd` out of the tree from taking the boundary
+	 * with it, without the text layer having to recognise every spelling of `cd`.
+	 */
+	#containmentFence() {
+		const policy = resolveSessionPolicy(this.session.cwd, this.session.settings);
+		if (!policy) return undefined; // --no-sandbox / sandbox.enabled = false
+		const artifactsDir = this.session.getArtifactsDir?.();
+		// The three grants stay distinct. Merging allowRead and allowWrite into one read+write list
+		// made a folder shared for reading writable, undoing the split built for #2516.
+		return buildContainmentFence({
+			workspace: this.session.cwd,
+			extraRoots: artifactsDir ? [artifactsDir] : [],
+			readOnlyRoots: (this.session.settings.get("sandbox.allowRead") as string[] | undefined) ?? [],
+			writeOnlyRoots: (this.session.settings.get("sandbox.allowWrite") as string[] | undefined) ?? [],
+		});
+	}
+
 	async execute(
 		_toolCallId: string,
 		{
@@ -644,6 +671,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					artifactPath,
 					artifactId,
 					maskSecrets,
+					fence: this.#containmentFence(),
 				})
 			: await executeBash(command, {
 					cwd: commandCwd,
@@ -654,6 +682,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					artifactPath,
 					artifactId,
 					maskSecrets,
+					fence: this.#containmentFence(),
 					onChunk: chunk => {
 						tailBuffer.append(chunk);
 						if (onUpdate) {