@f5-sales-demo/xcsh 19.76.0 → 19.77.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.76.0",
+	"version": "19.77.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",
@@ -56,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.76.0",
-		"@f5-sales-demo/pi-agent-core": "19.76.0",
-		"@f5-sales-demo/pi-ai": "19.76.0",
-		"@f5-sales-demo/pi-natives": "19.76.0",
-		"@f5-sales-demo/pi-resource-management": "19.76.0",
-		"@f5-sales-demo/pi-tui": "19.76.0",
-		"@f5-sales-demo/pi-utils": "19.76.0",
+		"@f5-sales-demo/xcsh-stats": "19.77.0",
+		"@f5-sales-demo/pi-agent-core": "19.77.0",
+		"@f5-sales-demo/pi-ai": "19.77.0",
+		"@f5-sales-demo/pi-natives": "19.77.0",
+		"@f5-sales-demo/pi-resource-management": "19.77.0",
+		"@f5-sales-demo/pi-tui": "19.77.0",
+		"@f5-sales-demo/pi-utils": "19.77.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/cli/args.ts

@@ -12,6 +12,10 @@ export type Mode = "text" | "json" | "rpc" | "acp";
 export interface Args {
 	cwd?: string;
 	allowHome?: boolean;
+	/** Disable the session filesystem sandbox (widen to unrestricted access). */
+	noSandbox?: boolean;
+	/** Extra directories the session may read AND write, beyond its CWD subtree (repeatable). */
+	allowPath?: string[];
 	provider?: string;
 	model?: string;
 	smol?: string;
@@ -69,6 +73,11 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 			result.version = true;
 		} else if (arg === "--allow-home") {
 			result.allowHome = true;
+		} else if (arg === "--no-sandbox") {
+			result.noSandbox = true;
+		} else if (arg === "--allow-path" && i + 1 < args.length) {
+			result.allowPath = result.allowPath ?? [];
+			result.allowPath.push(args[++i]);
 		} else if (arg === "--mode" && i + 1 < args.length) {
 			const mode = args[++i];
 			if (mode === "text" || mode === "json" || mode === "rpc" || mode === "acp") {
@@ -268,6 +277,10 @@ ${chalk.bold("Available Tools (default-enabled unless noted):")}
   web_search    - Search the web
   ask           - Ask user questions (interactive mode only)
 
+${chalk.bold("Sandbox Options:")}
+  --no-sandbox               Disable session filesystem isolation (allow access outside the CWD)
+  --allow-path <path>        Grant read+write access to an extra directory (repeatable)
+
 ${chalk.bold("Plugin Options:")}
   --plugin-dir <path>        Load plugin from directory (repeatable)
 

package/src/config/settings-schema.ts

@@ -24,7 +24,8 @@ export type SettingTab =
 	| "editing"
 	| "tools"
 	| "tasks"
-	| "providers";
+	| "providers"
+	| "sandbox";
 
 /** Tab display metadata - icon is resolved via theme.symbol() */
 export type TabMetadata = { label: string; icon: `tab.${string}` };
@@ -39,6 +40,7 @@ export const SETTING_TABS: SettingTab[] = [
 	"tools",
 	"tasks",
 	"providers",
+	"sandbox",
 ];
 
 /** Tab display metadata - icon is a symbol key from theme.ts (tab.*) */
@@ -51,6 +53,7 @@ export const TAB_METADATA: Record<SettingTab, { label: string; icon: `tab.${stri
 	tools: { label: "Tools", icon: "tab.tools" },
 	tasks: { label: "Tasks", icon: "tab.tasks" },
 	providers: { label: "Providers", icon: "tab.providers" },
+	sandbox: { label: "Sandbox", icon: "tab.sandbox" },
 };
 
 /** Status line segment identifiers */
@@ -147,10 +150,9 @@ export interface ModelTagsSettings {
 	[key: string]: ModelTagDef;
 }
 
-// Typed defaults for array/record settings — named constants avoid `as` casts
-// under `as const` while still letting SettingValue infer the correct element type.
+// Typed defaults for array settings — named constants avoid `as` casts under
+// `as const` while still letting SettingValue infer the correct element type.
 const EMPTY_STRING_ARRAY: string[] = [];
-const EMPTY_STRING_RECORD: Record<string, string> = {};
 const DEFAULT_CYCLE_ORDER: string[] = ["smol", "default", "slow"];
 /**
  * Binary-baked default model role. Ships in the binary so a fresh install needs
@@ -1790,6 +1792,25 @@ export const SETTINGS_SCHEMA = {
 		ui: { tab: "providers", label: "Hide Secrets", description: "Obfuscate secrets before sending to AI providers" },
 	},
 
+	// Session filesystem isolation. Confines the file tools (read/write/edit/find/grep)
+	// and the Bash working directory to the session's CWD subtree plus a curated global
+	// allowlist, so concurrent sessions in different customer folders cannot read or
+	// write each other's files, secrets, or memory. See src/sandbox/.
+	"sandbox.enabled": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "sandbox",
+			label: "Filesystem isolation",
+			description: "Confine file tools to the working directory subtree (blocks cross-session access)",
+		},
+	},
+	// Extra roots (beyond the CWD subtree) the session may read/write. Config/CLI only —
+	// e.g. `--allow-path <dir>` maps into both. The hardcoded cross-session leak-denies
+	// (other sessions' memories/sessions and the shared tenant contexts) always win.
+	"sandbox.allowRead": { type: "array", default: [] as string[] },
+	"sandbox.allowWrite": { type: "array", default: [] as string[] },
+
 	// Provider selection
 	"providers.webSearch": {
 		type: "enum",

package/src/extensibility/extensions/bundled/sandbox-guard.ts

@@ -0,0 +1,61 @@
+import type { ExtensionAPI } from "@f5-sales-demo/xcsh";
+import { settings } from "../../../config/settings";
+import { evaluateToolCall } from "../../../sandbox/enforce";
+import { buildDefaultSandboxPolicy, type SandboxPolicy } from "../../../sandbox/policy";
+
+/**
+ * Session filesystem sandbox (bundled, default-on).
+ *
+ * Confines the model-invoked file tools (read/write/edit/find/grep) and the Bash
+ * working directory to the session's CWD subtree plus a curated global allowlist, so
+ * concurrent sessions in different customer folders cannot read or write each other's
+ * files, secrets, or memory. Enforcement is a `tool_call` gate: the extension wrapper
+ * blocks the tool when this returns `{ block: true }`, and fails safe (a thrown handler
+ * also blocks).
+ *
+ * The boundary is derived from `ctx.cwd` (always the live session's directory) plus the
+ * `sandbox.*` settings. Controlled by `sandbox.enabled` (default true); widened per run
+ * with `--allow-path` / `--no-sandbox` or the `sandbox.allow*` settings.
+ */
+export default function sandboxGuard(pi: ExtensionAPI): void {
+	// One policy per cwd — rebuilt only when the working directory changes.
+	let cache: { cwd: string; policy: SandboxPolicy } | undefined;
+
+	// The global settings proxy throws before Settings.init() (e.g. some SDK/test
+	// contexts). Fall back to the given default there so the guard never hard-fails.
+	function readSetting<T>(key: string, fallback: T): T {
+		try {
+			const value = (settings as unknown as { get(k: string): unknown }).get(key);
+			return value === undefined ? fallback : (value as T);
+		} catch {
+			return fallback;
+		}
+	}
+
+	function policyFor(cwd: string): SandboxPolicy | undefined {
+		// Fail closed: if `sandbox.enabled` can't be read, keep isolation on rather than
+		// silently disabling it. In a normal session settings resolves the true default.
+		if (!readSetting<boolean>("sandbox.enabled", true)) return undefined;
+		if (cache?.cwd === cwd) return cache.policy;
+		const policy = buildDefaultSandboxPolicy({
+			cwd,
+			enabled: true,
+			allowRead: readSetting<string[]>("sandbox.allowRead", []),
+			allowWrite: readSetting<string[]>("sandbox.allowWrite", []),
+		});
+		cache = { cwd, policy };
+		return policy;
+	}
+
+	pi.on("tool_call", (event, ctx) => {
+		const policy = policyFor(ctx.cwd);
+		if (!policy) return undefined;
+		const decision = evaluateToolCall({
+			toolName: event.toolName,
+			input: event.input as Record<string, unknown>,
+			cwd: ctx.cwd,
+			policy,
+		});
+		return decision.block ? { block: true, reason: decision.reason } : undefined;
+	});
+}

package/src/extensibility/extensions/loader.ts

@@ -21,6 +21,7 @@ import { EventBus } from "../../utils/event-bus";
 import { getAllPluginExtensionPaths } from "../plugins/loader";
 import { resolvePath } from "../utils";
 import herdrReporter from "./bundled/herdr-reporter";
+import sandboxGuard from "./bundled/sandbox-guard";
 import type {
 	Extension,
 	ExtensionAPI,
@@ -496,6 +497,7 @@ async function discoverExtensionsInDir(dir: string): Promise<string[]> {
 /** Extensions bundled with xcsh and loaded by default (before user extensions). */
 const BUNDLED_EXTENSIONS: ReadonlyArray<{ name: string; factory: ExtensionFactory }> = [
 	{ name: "herdr-reporter", factory: herdrReporter },
+	{ name: "sandbox-guard", factory: sandboxGuard },
 ];
 
 /**

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.76.0",
-	"commit": "2e4e3b0d461f6dc353419167c54b0da3c7310765",
-	"shortCommit": "2e4e3b0",
+	"version": "19.77.0",
+	"commit": "bdabc05ed9f27370b8cb0f794923cf981d71cc82",
+	"shortCommit": "bdabc05",
 	"branch": "main",
-	"tag": "v19.76.0",
-	"commitDate": "2026-07-22T16:43:35Z",
-	"buildDate": "2026-07-22T17:06:30.694Z",
+	"tag": "v19.77.0",
+	"commitDate": "2026-07-23T01:40:52Z",
+	"buildDate": "2026-07-23T02:01:44.889Z",
 	"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/2e4e3b0d461f6dc353419167c54b0da3c7310765",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.76.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/bdabc05ed9f27370b8cb0f794923cf981d71cc82",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.77.0"
 };

package/src/main.ts

@@ -604,7 +604,16 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 	}
 
 	const cwd = getProjectDir();
-	await logger.time("settings:init", Settings.init, { cwd });
+	const sandboxOverrides: Partial<Record<SettingPath, unknown>> = {};
+	if (parsedArgs.noSandbox) sandboxOverrides["sandbox.enabled"] = false;
+	if (parsedArgs.allowPath?.length) {
+		sandboxOverrides["sandbox.allowRead"] = parsedArgs.allowPath;
+		sandboxOverrides["sandbox.allowWrite"] = parsedArgs.allowPath;
+	}
+	await logger.time("settings:init", Settings.init, {
+		cwd,
+		overrides: Object.keys(sandboxOverrides).length > 0 ? sandboxOverrides : undefined,
+	});
 
 	// F5 XC context is session-scoped: nothing loads at startup. We still init the
 	// ContextService singleton so /context commands and the session bootstrap work.

package/src/modes/theme/theme.ts

@@ -191,7 +191,8 @@ export type SymbolKey =
 	| "tab.editing"
 	| "tab.tools"
 	| "tab.tasks"
-	| "tab.providers";
+	| "tab.providers"
+	| "tab.sandbox";
 
 type SymbolMap = Record<SymbolKey, string>;
 
@@ -356,6 +357,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"tab.tools": "🔧",
 	"tab.tasks": "📦",
 	"tab.providers": "🌐",
+	"tab.sandbox": "🔒",
 };
 
 const NERD_SYMBOLS: SymbolMap = {
@@ -616,6 +618,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"tab.tools": "󰠭",
 	"tab.tasks": "󰐱",
 	"tab.providers": "󰖟",
+	"tab.sandbox": "󰌾",
 };
 
 const ASCII_SYMBOLS: SymbolMap = {
@@ -778,6 +781,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"tab.tools": "[T]",
 	"tab.tasks": "[K]",
 	"tab.providers": "[P]",
+	"tab.sandbox": "[S]",
 };
 
 const SYMBOL_PRESETS: Record<SymbolPreset, SymbolMap> = {

package/src/sandbox/enforce.ts

@@ -0,0 +1,319 @@
+/**
+ * Pure evaluation of a tool call against a SandboxPolicy.
+ *
+ * Maps each path-taking tool to its path argument(s) and access mode, resolves the
+ * path relative to the session cwd, and asks the policy whether it is allowed. Kept
+ * free of settings/runtime so it is fully unit-testable; the bundled `sandbox-guard`
+ * extension is a thin wrapper that supplies cwd, settings, and the policy.
+ *
+ * Search tools (`find`/`grep`/`ast_grep`/`ast_edit`) accept comma-/whitespace-delimited
+ * multi-path inputs that the tools split (via `splitTopLevel`) and search from a common
+ * base directory. We split the same way and policy-check EVERY token's base, so a
+ * multi-path input cannot smuggle a sibling directory past the gate.
+ *
+ * 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.
+ */
+import * as path from "node:path";
+import { parseFindPattern, parseSearchPath, resolveToCwd, splitTopLevel } from "../tools/path-utils";
+import type { SandboxAccess, SandboxPolicy } from "./policy";
+
+export interface ToolCallCheck {
+	toolName: string;
+	input: Record<string, unknown>;
+	cwd: string;
+	policy: SandboxPolicy;
+}
+
+export interface ToolCallDecision {
+	block: boolean;
+	reason?: string;
+}
+
+const ALLOW: ToolCallDecision = { block: false };
+
+interface PathArgSpec {
+	/** Candidate input keys, tried in order; first non-empty string wins. */
+	keys: string[];
+	access: SandboxAccess;
+	/** Exempt OS system paths (for tools that legitimately execute system binaries). */
+	systemExempt?: boolean;
+}
+
+/**
+ * Tools that touch explicit path argument(s). Each tool lists one or more specs; every
+ * present path is checked. Remote/in-memory path-looking args (xcsh_api HTTP paths,
+ * ssh remote cwd) are intentionally absent.
+ */
+const TOOL_PATHS: Record<string, PathArgSpec[]> = {
+	read: [{ keys: ["file_path", "path"], access: "read" }],
+	write: [{ keys: ["file_path", "path"], access: "write" }],
+	notebook: [{ keys: ["notebook_path"], access: "write" }],
+	inspect_image: [{ keys: ["path"], access: "read" }],
+	display_image: [{ keys: ["path"], access: "read" }],
+	lsp: [{ keys: ["file"], access: "read" }], // read for most actions; rename-apply writes
+	catalog_workflow_runner: [
+		{ keys: ["catalog_path"], access: "read" },
+		{ keys: ["screenshot_dir"], access: "write" },
+	],
+	// debug executes an arbitrary program and reads source files; system binaries are ok.
+	debug: [
+		{ keys: ["program"], access: "read", systemExempt: true },
+		{ keys: ["file"], access: "read", systemExempt: true },
+		{ keys: ["cwd"], access: "read", systemExempt: true },
+	],
+};
+
+interface SearchSpec {
+	/** Input key holding the (possibly multi-) path or glob list. */
+	key: string;
+	/** Extract the base directory of one token (matches the tool's own resolver). */
+	base: (token: string) => string;
+	access: SandboxAccess;
+}
+
+/** Tools that accept multi-path search inputs split from a common base directory. */
+const SEARCH_TOOLS: Record<string, SearchSpec> = {
+	find: { key: "pattern", base: token => parseFindPattern(token).basePath, access: "read" },
+	grep: { key: "path", base: token => parseSearchPath(token).basePath, access: "read" },
+	ast_grep: { key: "path", base: token => parseSearchPath(token).basePath, access: "read" },
+	ast_edit: { key: "path", base: token => parseSearchPath(token).basePath, access: "write" },
+};
+
+/** Arbitrary-code tools whose command/code strings are scanned best-effort. */
+const CODE_FIELDS: Record<string, string[]> = {
+	bash: ["command"],
+	python: ["code"],
+};
+
+/**
+ * Standard OS directories a subprocess may legitimately read or traverse (interpreters,
+ * libraries, device files) and which hold no customer data. Only the code-tool scan
+ * treats these as benign; the file tools stay strictly confined to the policy. Notably
+ * excludes /tmp, /var, /private, and home — those can hold per-session or per-user data.
+ */
+const SYSTEM_READ_ROOTS = [
+	"/usr",
+	"/bin",
+	"/sbin",
+	"/lib",
+	"/lib64",
+	"/opt",
+	"/etc",
+	"/dev",
+	"/proc",
+	"/sys",
+	"/System",
+	"/Library",
+];
+
+function isSystemPath(resolved: string): boolean {
+	return SYSTEM_READ_ROOTS.some(root => resolved === root || resolved.startsWith(`${root}${path.sep}`));
+}
+
+function firstString(input: Record<string, unknown>, keys: string[]): string | undefined {
+	for (const key of keys) {
+		const value = input[key];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return undefined;
+}
+
+function deny(policy: SandboxPolicy, resolved: string, access: SandboxAccess): ToolCallDecision {
+	return { block: true, reason: policy.describe(resolved, access) };
+}
+
+function looksLikePath(token: string): boolean {
+	return path.isAbsolute(token) || token.startsWith("~") || /(^|[/\\])\.\.([/\\]|$)/.test(token);
+}
+
+/** Path-like tokens in a command/code string: bare (whitespace-split) and quoted. */
+function codePathTokens(command: string): string[] {
+	const tokens = new Set<string>();
+	for (const raw of command.split(/\s+/)) tokens.add(raw.replace(/^["']|["']$/g, ""));
+	for (const match of command.matchAll(/["']([^"']+)["']/g)) tokens.add(match[1]);
+	return [...tokens].filter(token => token.length > 0 && looksLikePath(token));
+}
+
+/** Base directories a search input would actually search, split like the tools do. */
+function searchBases(raw: string, base: (token: string) => string): string[] {
+	const trimmed = raw.trim();
+	if (!trimmed) return [];
+	const tokens = new Set<string>();
+	// Union of comma and whitespace splits — over-splitting only adds harmless in-tree
+	// checks; it can never hide an out-of-tree token from the gate.
+	for (const separator of ["comma", "whitespace"] as const) {
+		for (const token of splitTopLevel(trimmed, separator)) {
+			const cleaned = token.trim();
+			if (cleaned) tokens.add(base(cleaned));
+		}
+	}
+	return [...tokens];
+}
+
+function evaluateCodeTool(check: ToolCallCheck, fields: string[]): ToolCallDecision {
+	const { input, cwd, policy } = check;
+
+	const rawCwd = typeof input.cwd === "string" ? input.cwd : undefined;
+	const base = rawCwd ? resolveToCwd(rawCwd, cwd) : cwd;
+	if (rawCwd && !policy.isAllowed(base, "read")) return deny(policy, base, "read");
+
+	const commands: string[] = [];
+	for (const field of fields) {
+		if (typeof input[field] === "string") commands.push(input[field] as string);
+	}
+	// python also accepts a `cells` array of { code }.
+	if (Array.isArray(input.cells)) {
+		for (const cell of input.cells) {
+			const code = (cell as { code?: unknown })?.code;
+			if (typeof code === "string") commands.push(code);
+		}
+	}
+
+	for (const command of commands) {
+		for (const token of codePathTokens(command)) {
+			const resolved = resolveToCwd(token, base);
+			if (!policy.isAllowed(resolved, "read") && !isSystemPath(resolved)) {
+				return deny(policy, resolved, "read");
+			}
+		}
+	}
+
+	return ALLOW;
+}
+
+/**
+ * The `edit` tool is mode-dependent; every mode writes. Targets, across modes:
+ *  - vim mode: top-level `file`
+ *  - replace/patch/hashline/chunk: each `edits[]` entry's `path`
+ *  - hashline rename: `edits[].move`; patch rename: `edits[].rename`
+ * (Chunk paths embed a `:selector#hash~` suffix, but a `..`/absolute escape still resolves
+ * out of tree via the leading segments, so no stripping is needed for the boundary check.)
+ */
+function evaluateEdit(check: ToolCallCheck): ToolCallDecision {
+	const { input, cwd, policy } = check;
+	const targets: string[] = [];
+	const add = (value: unknown): void => {
+		if (typeof value === "string" && value.length > 0) targets.push(value);
+	};
+	add(input.file); // vim mode
+	add(input.file_path);
+	add(input.path);
+	if (Array.isArray(input.edits)) {
+		for (const entry of input.edits) {
+			if (entry && typeof entry === "object") {
+				const e = entry as Record<string, unknown>;
+				add(e.path);
+				add(e.move); // hashline rename
+				add(e.rename); // patch rename
+			}
+		}
+	}
+	for (const target of targets) {
+		const resolved = resolveToCwd(target, cwd);
+		if (!policy.isAllowed(resolved, "write")) return deny(policy, resolved, "write");
+	}
+	return ALLOW;
+}
+
+/**
+ * `generate_image` reads local files named in its `input[]` array (each `{ path?, data? }`)
+ * and sends the bytes to an external API — so an out-of-tree path is both a read escape
+ * and an exfiltration. Registered dynamically (not in BUILTIN_TOOLS).
+ */
+function evaluateGenerateImage(check: ToolCallCheck): ToolCallDecision {
+	const { input, cwd, policy } = check;
+	if (Array.isArray(input.input)) {
+		for (const entry of input.input) {
+			const value = entry && typeof entry === "object" ? (entry as Record<string, unknown>).path : undefined;
+			if (typeof value === "string" && value.length > 0) {
+				const resolved = resolveToCwd(value, cwd);
+				if (!policy.isAllowed(resolved, "read")) return deny(policy, resolved, "read");
+			}
+		}
+	}
+	return ALLOW;
+}
+
+const REMOTE_URL_SCHEME = /^(https?|about|data|chrome|chrome-extension|blob|ws|wss):/i;
+
+/**
+ * If a browser navigation target refers to the LOCAL filesystem, return the path to
+ * check; otherwise undefined (remote/benign scheme). Covers file: URLs, the filesystem:
+ * wrapper, and bare/relative/absolute paths that `goto` would resolve against disk.
+ */
+function navLocalPath(raw: string): string | undefined {
+	const url = raw.trim();
+	if (!url || REMOTE_URL_SCHEME.test(url)) return undefined;
+	if (url.toLowerCase().startsWith("file:")) return url; // resolveToCwd → stripFileUrl
+	if (url.toLowerCase().startsWith("filesystem:")) return url.slice("filesystem:".length);
+	if (path.isAbsolute(url) || url.startsWith("~") || url.startsWith(".")) return url;
+	return undefined; // domain-like host or unknown scheme → not local disk
+}
+
+/**
+ * `puppeteer` (the browser tool) writes screenshots to `path` and navigates to `url`.
+ * A file:// / local navigation target followed by get_text/evaluate/screenshot returns
+ * another session's file contents to the model, so local navigation is a read escape.
+ */
+function evaluatePuppeteer(check: ToolCallCheck): ToolCallDecision {
+	const { input, cwd, policy } = check;
+	const screenshot = firstString(input, ["path"]);
+	if (screenshot) {
+		const resolved = resolveToCwd(screenshot, cwd);
+		if (!policy.isAllowed(resolved, "write")) return deny(policy, resolved, "write");
+	}
+	if (typeof input.url === "string") {
+		const local = navLocalPath(input.url);
+		if (local) {
+			const resolved = resolveToCwd(local, cwd);
+			if (!policy.isAllowed(resolved, "read")) return deny(policy, resolved, "read");
+		}
+	}
+	return ALLOW;
+}
+
+function evaluateSearchTool(check: ToolCallCheck, spec: SearchSpec): ToolCallDecision {
+	const { input, cwd, policy } = check;
+	const raw = typeof input[spec.key] === "string" ? (input[spec.key] as string) : "";
+	for (const basePath of searchBases(raw, spec.base)) {
+		const resolved = resolveToCwd(basePath, cwd);
+		if (!policy.isAllowed(resolved, spec.access)) return deny(policy, resolved, spec.access);
+	}
+	return ALLOW;
+}
+
+/**
+ * Decide whether a tool call is allowed under the policy. Tools with no recognized
+ * path argument are always allowed.
+ */
+export function evaluateToolCall(check: ToolCallCheck): ToolCallDecision {
+	const { toolName, input, cwd, policy } = check;
+	if (!policy.enabled) return ALLOW;
+
+	const codeFields = CODE_FIELDS[toolName];
+	if (codeFields) return evaluateCodeTool(check, codeFields);
+
+	if (toolName === "edit") return evaluateEdit(check);
+	if (toolName === "generate_image") return evaluateGenerateImage(check);
+	if (toolName === "puppeteer") return evaluatePuppeteer(check);
+
+	const searchSpec = SEARCH_TOOLS[toolName];
+	if (searchSpec) return evaluateSearchTool(check, searchSpec);
+
+	const specs = TOOL_PATHS[toolName];
+	if (!specs) return ALLOW;
+
+	for (const spec of specs) {
+		const raw = firstString(input, spec.keys);
+		if (!raw) continue; // optional path → defaults to cwd, which is allowed
+		const resolved = resolveToCwd(raw, cwd);
+		if (policy.isAllowed(resolved, spec.access)) continue;
+		if (spec.systemExempt && isSystemPath(resolved)) continue;
+		return deny(policy, resolved, spec.access);
+	}
+	return ALLOW;
+}

package/src/sandbox/policy.ts

@@ -0,0 +1,161 @@
+/**
+ * SandboxPolicy — resolves whether a file path is inside the current session's
+ * read/write boundary.
+ *
+ * The model is longest-prefix-wins over an ordered set of allow/deny rules, with
+ * deny beating allow on an exact-depth tie (fail-safe). A path matched by no rule
+ * is denied (default-deny outside the working tree). This mirrors the deny-then-allow
+ * precedence used by Anthropic's sandbox-runtime, but is enforced in-process for the
+ * structured file tools (read/write/edit/find/grep) and the Bash `cwd`, rather than at
+ * the OS level.
+ *
+ * The boundary only gates model-invoked tools. Internal subsystems (memory pipeline,
+ * session manager, settings) do not go through the file tools, so they are unaffected.
+ */
+import * as path from "node:path";
+import {
+	getAgentDir,
+	getConfigRootDir,
+	getMemoriesDir,
+	getPluginsDir,
+	getSessionsDir,
+	getXCSHContextsDir,
+	normalizePathForComparison,
+	pathIsWithin,
+} from "@f5-sales-demo/pi-utils";
+import { expandPath } from "../tools/path-utils";
+
+export type SandboxAccess = "read" | "write";
+
+export interface SandboxRule {
+	/** Absolute directory or file this rule governs. */
+	root: string;
+	/** true = allow, false = deny. */
+	allow: boolean;
+}
+
+export interface SandboxPolicyConfig {
+	enabled: boolean;
+	/** Session working directory, used for messaging and as the primary allowed root. */
+	cwd: string;
+	read: SandboxRule[];
+	write: SandboxRule[];
+}
+
+interface NormalizedRule {
+	root: string;
+	depth: number;
+	allow: boolean;
+}
+
+function normalizeRule(rule: SandboxRule): NormalizedRule {
+	const normalized = normalizePathForComparison(rule.root);
+	return {
+		root: rule.root,
+		depth: normalized.split(path.sep).filter(Boolean).length,
+		allow: rule.allow,
+	};
+}
+
+export class SandboxPolicy {
+	readonly enabled: boolean;
+	readonly cwd: string;
+	readonly #read: NormalizedRule[];
+	readonly #write: NormalizedRule[];
+
+	constructor(config: SandboxPolicyConfig) {
+		this.enabled = config.enabled;
+		this.cwd = config.cwd;
+		this.#read = config.read.map(normalizeRule);
+		this.#write = config.write.map(normalizeRule);
+	}
+
+	/**
+	 * Whether `candidate` (an absolute, already-resolved path) may be accessed for
+	 * the given mode. Callers must resolve `~`/relative/`..` first (see resolveToCwd).
+	 */
+	isAllowed(candidate: string, access: SandboxAccess): boolean {
+		if (!this.enabled) return true;
+		const rules = access === "write" ? this.#write : this.#read;
+		let best: NormalizedRule | undefined;
+		for (const rule of rules) {
+			if (!pathIsWithin(rule.root, candidate)) continue;
+			const deeper = !best || rule.depth > best.depth;
+			const denyTie = best !== undefined && rule.depth === best.depth && best.allow && !rule.allow;
+			if (deeper || denyTie) best = rule;
+		}
+		return best?.allow ?? false;
+	}
+
+	/** Human-readable reason surfaced to the model when a path is blocked. */
+	describe(candidate: string, access: SandboxAccess): string {
+		return `Path is outside this session's ${access} boundary (working directory: ${this.cwd}): ${candidate}. Use --allow-path or the sandbox.allow* settings to widen it, or --no-sandbox to disable isolation.`;
+	}
+}
+
+export interface DefaultSandboxOptions {
+	/** Session working directory. */
+	cwd: string;
+	/** Defaults to true — isolation is enforced by default. */
+	enabled?: boolean;
+	/** A session-specific temp dir to allow (read+write). NOT the shared OS temp dir. */
+	tmpDir?: string;
+	/** Extra roots (read+write) — e.g. from `--allow-path`. */
+	extraAllowRoots?: string[];
+	allowRead?: string[];
+	allowWrite?: string[];
+}
+
+/**
+ * Build the default session policy: confine reads/writes to the CWD subtree, plus a
+ * curated global allowlist (plugin cache, user-level skills, operator profile/settings)
+ * for reads. Cross-session leak surfaces under `~/.xcsh` and the shared global tenant
+ * contexts are explicitly denied, so even a broad user-configured allow cannot re-expose
+ * another customer's memory, session, or credentials.
+ *
+ * Note: the OS temp dir is deliberately NOT allowlisted. It is shared across all
+ * sessions, so allowing it would let one customer's session read another's scratch
+ * files. The agent should work in temp directories under its CWD; internal tool temp
+ * usage bypasses this boundary (it is not a model-invoked path). A specific session
+ * temp dir can still be granted via `tmpDir`.
+ */
+export function buildDefaultSandboxPolicy(opts: DefaultSandboxOptions): SandboxPolicy {
+	const cwd = path.resolve(opts.cwd);
+	const configRoot = getConfigRootDir();
+	const skillsDir = path.join(getAgentDir(), "skills");
+
+	const allow = (root: string): SandboxRule => ({ root, allow: true });
+	const deny = (root: string): SandboxRule => ({ root, allow: false });
+	const expand = (roots: string[] | undefined, allowed: boolean): SandboxRule[] =>
+		(roots ?? []).map(r => ({ root: expandPath(r), allow: allowed }));
+
+	// Denied even though some sit under otherwise-allowlisted roots. Longest-prefix
+	// precedence makes these win over any broader allow.
+	const leakDenies = [deny(getMemoriesDir()), deny(getSessionsDir()), deny(getXCSHContextsDir())];
+	const extraAllow = expand(opts.extraAllowRoots, true);
+	// Only allowed if a specific (non-shared) session temp dir is passed in.
+	const sessionTmp = opts.tmpDir ? [allow(opts.tmpDir)] : [];
+
+	const read: SandboxRule[] = [
+		allow(cwd),
+		...sessionTmp,
+		allow(getPluginsDir()), // plugin engines/schemas (e.g. meddpicc)
+		allow(skillsDir), // user-level skills
+		allow(path.join(configRoot, "user-profile.json")),
+		allow(path.join(configRoot, "computer-profile.json")),
+		allow(path.join(configRoot, "settings.json")),
+		...leakDenies,
+		...extraAllow,
+		...expand(opts.allowRead, true),
+	];
+
+	const write: SandboxRule[] = [
+		allow(cwd),
+		...sessionTmp,
+		...leakDenies,
+		...extraAllow,
+		...expand(opts.allowWrite, true),
+	];
+
+	return new SandboxPolicy({ enabled: opts.enabled ?? true, cwd, read, write });
+}

package/src/tools/path-utils.ts

@@ -244,9 +244,9 @@ export function combineSearchGlobs(prefixGlob?: string, suffixGlob?: string): st
 	return `${normalizedPrefix}/${normalizedSuffix}`;
 }
 
-type TopLevelSeparator = "comma" | "whitespace";
+export type TopLevelSeparator = "comma" | "whitespace";
 
-function splitTopLevel(value: string, separator: TopLevelSeparator): string[] {
+export function splitTopLevel(value: string, separator: TopLevelSeparator): string[] {
 	const parts: string[] = [];
 	let current = "";
 	let braceDepth = 0;