pum-agent 0.2.0-beta.4 → 0.2.2-beta.1

package/src/sandbox/types.ts

@@ -0,0 +1,62 @@
+import type { CheckPathAccessMode } from "../check-policy";
+
+export type SandboxMode = "auto" | "require" | "off";
+export type SandboxCapabilityState = "enforced" | "unavailable" | "error";
+export type SandboxBackendId = "bubblewrap" | "mxc";
+export type SandboxNetwork = "deny" | "host";
+
+export type SandboxCapability = {
+  state: SandboxCapabilityState;
+  backend: SandboxBackendId;
+  reason?: string;
+};
+
+export type SandboxPolicyAccess = {
+  resolvedPath: string;
+  mode: CheckPathAccessMode;
+  source: "operand" | "redirection" | "executable";
+  stage: number;
+  external: boolean;
+};
+
+/** Canonical policy derived from the approved command and authoritative PUM state. */
+export type SandboxPolicy = {
+  version: 1;
+  exactCommand: string;
+  cwd: string;
+  readOnlyPaths: string[];
+  readWritePaths: string[];
+  deniedPaths: string[];
+  privateTemp: string;
+  environment: Record<string, string>;
+  executable: string;
+  args: string[];
+  network: SandboxNetwork;
+  rationale: string;
+  accesses: SandboxPolicyAccess[];
+  networkCommands?: string[];
+};
+
+export type SandboxProcessExit = {
+  exitCode: number | null;
+  signal: string | null;
+};
+
+export type SandboxProcessOptions = {
+  onStdout(chunk: Uint8Array): void;
+  onStderr(chunk: Uint8Array): void;
+  signal?: AbortSignal;
+  timeoutSeconds?: number;
+  stdin?: Uint8Array;
+};
+
+export type SandboxProcessHandle = {
+  completed: Promise<SandboxProcessExit>;
+  kill(): void;
+};
+
+export interface SandboxBackend {
+  readonly id: SandboxBackendId;
+  probe(): Promise<SandboxCapability>;
+  spawn(policy: SandboxPolicy, options: SandboxProcessOptions): SandboxProcessHandle;
+}

package/src/sandbox/windows.ts

@@ -0,0 +1,327 @@
+import type { ChildProcess } from "node:child_process";
+import { delimiter, join, win32 } from "node:path";
+import type {
+	ContainerConfig,
+	PlatformSupport,
+	SandboxPolicy as MxcPolicy,
+} from "@microsoft/mxc-sdk";
+import type {
+	SandboxBackend,
+	SandboxCapability,
+	SandboxPolicy,
+	SandboxProcessHandle,
+	SandboxProcessOptions,
+} from "./types.js";
+
+type MxcSdk = typeof import("@microsoft/mxc-sdk");
+type MxcSdkLoader = () => Promise<MxcSdk>;
+
+const REQUIRED_UI_CAPABILITIES = [
+	"canBlockClipboardRead",
+	"canBlockClipboardWrite",
+	"canBlockInputInjection",
+	"canBlockInputMethodChanges",
+	"canBlockExternalUiObjects",
+	"canBlockGlobalUiNamespace",
+	"canBlockDesktopSwitching",
+	"canBlockLogoffOrShutdown",
+	"canBlockSystemParameterChanges",
+	"canBlockDisplaySettingsChanges",
+] as const;
+
+const loadMxcSdk: MxcSdkLoader = async () => {
+	// MXC 0.7 resolves `whoami /user` through a shell during module import.
+	// Prefer the native Windows binary so a Git/MSYS PATH does not select GNU whoami.
+	const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+	const previous = process.env[pathKey];
+	const systemRoot = process.env.SystemRoot ?? process.env.WINDIR;
+	if (systemRoot) process.env[pathKey] = [join(systemRoot, "System32"), previous].filter(Boolean).join(delimiter);
+	try {
+		return await import("@microsoft/mxc-sdk");
+	} finally {
+		if (previous === undefined) delete process.env[pathKey];
+		else process.env[pathKey] = previous;
+	}
+};
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function unavailable(reason: string): SandboxCapability {
+	return { state: "unavailable", backend: "mxc", reason };
+}
+
+function failed(reason: string): SandboxCapability {
+	return { state: "error", backend: "mxc", reason };
+}
+
+function validateNativeSupport(support: PlatformSupport): SandboxCapability {
+	if (!support.isSupported || !support.availableMethods.includes("processcontainer")) {
+		return unavailable(support.reason || "MXC ProcessContainer is not available");
+	}
+	if (!support.isolationTier) {
+		return unavailable("The MXC native ProcessContainer probe did not return an isolation tier");
+	}
+	if (support.isolationTier !== "base-container") {
+		return unavailable(
+			`MXC BaseContainer/CreateProcessInSandbox is unavailable (reported tier: ${support.isolationTier}). ` +
+			"PUM does not use the AppContainer DACL fallback because it can change host ACLs.",
+		);
+	}
+	const ui = support.uiCapabilities;
+	if (!ui) {
+		return unavailable("The MXC native probe did not return UI restriction capabilities");
+	}
+	const missing = REQUIRED_UI_CAPABILITIES.filter((capability) => !ui[capability]);
+	if (missing.length > 0) {
+		return unavailable(`MXC cannot enforce required UI restrictions: ${missing.join(", ")}`);
+	}
+	return { state: "enforced", backend: "mxc" };
+}
+
+/**
+ * Quote one argv element for the Windows CreateProcess command-line grammar.
+ * This is the inverse convention used by CommandLineToArgvW and the Microsoft C runtime.
+ */
+export function quoteWindowsArgument(argument: string): string {
+	if (argument.length > 0 && !/[\s"]/u.test(argument)) return argument;
+
+	let quoted = '"';
+	let backslashes = 0;
+	for (const character of argument) {
+		if (character === "\\") {
+			backslashes += 1;
+			continue;
+		}
+		if (character === '"') {
+			quoted += "\\".repeat(backslashes * 2 + 1);
+			quoted += '"';
+			backslashes = 0;
+			continue;
+		}
+		quoted += "\\".repeat(backslashes);
+		quoted += character;
+		backslashes = 0;
+	}
+	quoted += "\\".repeat(backslashes * 2);
+	return `${quoted}"`;
+}
+
+/** MXC currently accepts only one command-line string, not executable and argv separately. */
+export function quoteWindowsCommandLine(executable: string, args: readonly string[]): string {
+	if (!executable) throw new Error("Sandbox executable is required");
+	return [quoteWindowsArgument(executable), ...args.map(quoteWindowsArgument)].join(" ");
+}
+
+function uniqueWindowsPaths(paths: readonly string[]): string[] {
+	const seen = new Set<string>();
+	const result: string[] = [];
+	for (const path of paths) {
+		const identity = path.replace(/[\\/]+$/u, "").toLowerCase();
+		if (seen.has(identity)) continue;
+		seen.add(identity);
+		result.push(path);
+	}
+	return result;
+}
+
+function windowsRuntimePaths(executable: string): string[] {
+	const executableDirectory = win32.dirname(executable);
+	return win32.basename(executableDirectory).toLowerCase() === "bin"
+		? [win32.dirname(executableDirectory)]
+		: [executableDirectory];
+}
+
+function sandboxEnvironment(policy: SandboxPolicy): string[] {
+	const entries = Object.entries(policy.environment).filter(
+		([name]) => name.toUpperCase() !== "TEMP" && name.toUpperCase() !== "TMP",
+	);
+	entries.push(["TEMP", policy.privateTemp], ["TMP", policy.privateTemp]);
+	return entries.map(([name, value]) => `${name}=${value}`);
+}
+
+/** Build the exact stable MXC 0.7 ProcessContainer configuration used for a run. */
+export function buildWindowsMxcConfig(
+	sdk: Pick<MxcSdk, "createConfigFromPolicy">,
+	policy: SandboxPolicy,
+	timeoutSeconds?: number,
+): ContainerConfig {
+	const timeoutMs = timeoutSeconds === undefined ? 0 : Math.ceil(timeoutSeconds * 1000);
+	if (timeoutSeconds !== undefined && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
+		throw new Error("Invalid timeout: must be a finite number of seconds");
+	}
+	if (timeoutMs > 2_147_483_647) {
+		throw new Error("Invalid timeout: maximum is 2147483.647 seconds");
+	}
+
+	const mxcPolicy: MxcPolicy = {
+		version: "0.7.0-alpha",
+		filesystem: {
+			readonlyPaths: uniqueWindowsPaths([...policy.readOnlyPaths, ...windowsRuntimePaths(policy.executable)]),
+			readwritePaths: uniqueWindowsPaths([...policy.readWritePaths, policy.privateTemp]),
+			deniedPaths: uniqueWindowsPaths(policy.deniedPaths),
+			clearPolicyOnExit: true,
+		},
+		network: {
+			allowOutbound: policy.network === "host",
+			allowLocalNetwork: policy.network === "host",
+		},
+		ui: {
+			allowWindows: false,
+			clipboard: "none",
+			allowInputInjection: false,
+		},
+		timeoutMs,
+	};
+
+	// SDK 0.7 declares concrete backends, but its implementation builds Windows
+	// ProcessContainer only through the abstract "process" intent.
+	const config = sdk.createConfigFromPolicy(mxcPolicy, "process");
+	config.process = {
+		commandLine: quoteWindowsCommandLine(policy.executable, policy.args),
+		cwd: policy.cwd,
+		env: sandboxEnvironment(policy),
+		timeout: timeoutMs,
+	};
+	config.lifecycle = { destroyOnExit: true, preservePolicy: false };
+	config.processContainer = {
+		...(config.processContainer ?? {}),
+		leastPrivilege: true,
+		capabilities:
+			policy.network === "host" ? ["internetClient", "privateNetworkClientServer"] : [],
+		ui: {
+			isolation: "container",
+			desktopSystemControl: false,
+			systemSettings: "none",
+			ime: false,
+		},
+	};
+	if (config.network) config.network.enforcementMode = "capabilities";
+	return config;
+}
+
+export async function probeWindowsSandbox(
+	loader: MxcSdkLoader = loadMxcSdk,
+	platform: NodeJS.Platform = process.platform,
+): Promise<SandboxCapability> {
+	if (platform !== "win32") return unavailable("MXC ProcessContainer requires Windows");
+	let sdk: MxcSdk;
+	try {
+		sdk = await loader();
+	} catch (error) {
+		return unavailable(`Optional dependency @microsoft/mxc-sdk is unavailable: ${errorMessage(error)}`);
+	}
+	try {
+		return validateNativeSupport(sdk.getPlatformSupport());
+	} catch (error) {
+		return failed(`MXC native availability probe failed: ${errorMessage(error)}`);
+	}
+}
+
+function startSandboxProcess(
+	sdk: MxcSdk,
+	policy: SandboxPolicy,
+	options: SandboxProcessOptions,
+	onChild: (child: ChildProcess) => void,
+): Promise<{ exitCode: number | null; signal: string | null }> {
+	return new Promise((resolve, reject) => {
+		let child: ChildProcess;
+		try {
+			const config = buildWindowsMxcConfig(sdk, policy, options.timeoutSeconds);
+			child = sdk.spawnSandboxFromConfig(config, { usePty: false }, policy.cwd) as ChildProcess;
+			onChild(child);
+		} catch (error) {
+			reject(error);
+			return;
+		}
+
+		let timedOut = false;
+		let stderrTail = "";
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+		const kill = () => child.kill();
+		const onAbort = () => kill();
+		if (options.timeoutSeconds !== undefined) {
+			timeout = setTimeout(() => {
+				timedOut = true;
+				kill();
+			// MXC enforces process.timeout inside the sandbox and tears down its
+			// Windows Job Object. This watchdog is only for a stuck executor.
+			}, options.timeoutSeconds * 1000 + 5_000);
+		}
+		if (options.signal) {
+			if (options.signal.aborted) onAbort();
+			else options.signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		child.stdout?.on("data", (chunk: Buffer) => options.onStdout(chunk));
+		child.stderr?.on("data", (chunk: Buffer) => {
+			options.onStderr(chunk);
+			stderrTail = `${stderrTail}${chunk.toString("utf8")}`.slice(-8_192);
+		});
+		child.once("error", reject);
+		child.once("close", (exitCode, signal) => {
+			if (timeout) clearTimeout(timeout);
+			options.signal?.removeEventListener("abort", onAbort);
+			if (options.signal?.aborted) {
+				reject(new Error("aborted"));
+				return;
+			}
+			if (
+				timedOut ||
+				(exitCode !== 0 && /(?:script|process|command) timed out after \d+ms/iu.test(stderrTail))
+			) {
+				reject(new Error(`timeout:${options.timeoutSeconds}`));
+				return;
+			}
+			resolve({ exitCode, signal });
+		});
+
+		child.stdin?.on("error", () => {});
+		child.stdin?.end(options.stdin ? Buffer.from(options.stdin) : undefined);
+	});
+}
+
+export class MxcSandboxBackend implements SandboxBackend {
+	readonly id = "mxc" as const;
+	readonly #loader: MxcSdkLoader;
+	readonly #platform: NodeJS.Platform;
+
+	constructor(options: { loader?: MxcSdkLoader; platform?: NodeJS.Platform } = {}) {
+		this.#loader = options.loader ?? loadMxcSdk;
+		this.#platform = options.platform ?? process.platform;
+	}
+
+	probe(): Promise<SandboxCapability> {
+		return probeWindowsSandbox(this.#loader, this.#platform);
+	}
+
+	spawn(policy: SandboxPolicy, options: SandboxProcessOptions): SandboxProcessHandle {
+		let child: ChildProcess | undefined;
+		let killRequested = false;
+		const completed = (async () => {
+			if (this.#platform !== "win32") throw new Error("MXC ProcessContainer requires Windows");
+			if (options.signal?.aborted) throw new Error("aborted");
+			const sdk = await this.#loader();
+			const capability = validateNativeSupport(sdk.getPlatformSupport());
+			if (capability.state !== "enforced") throw new Error(capability.reason);
+			return startSandboxProcess(sdk, policy, options, (spawned) => {
+				child = spawned;
+				if (killRequested) child.kill();
+			});
+		})();
+		return {
+			completed,
+			kill: () => {
+				killRequested = true;
+				child?.kill();
+			},
+		};
+	}
+}
+
+export function createWindowsSandboxBackend(
+	options: { loader?: MxcSdkLoader; platform?: NodeJS.Platform } = {},
+): SandboxBackend {
+	return new MxcSandboxBackend(options);
+}

package/src/sandbox-policy.ts

@@ -0,0 +1,204 @@
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { AGENT_DIR } from "./config";
+import type { CheckPolicyResult } from "./check-policy";
+import { isPathInsideOrSame, pathIdentity, type RuntimePlatform } from "./platform";
+import type {
+  SandboxCapability,
+  SandboxMode,
+  SandboxPolicy,
+  SandboxPolicyAccess,
+} from "./sandbox/types";
+
+export type BuildSandboxPolicyOptions = {
+  /** Exact command accepted by Check mode and any required user approval. */
+  command: string;
+  /** Authoritative configured prefix plus command actually passed to the shell. */
+  executionCommand?: string;
+  /** Authoritative project working directory. */
+  cwd: string;
+  /** Canonical Check mode roots for the launch project. */
+  additionalRoots?: readonly string[];
+  /** Deterministic Check mode result for the exact command. */
+  result: CheckPolicyResult;
+  /** Resolved shell executable. A backend must not select a shell. */
+  executable: string;
+  /** Complete shell arguments. For stdin-transport shells the command is supplied separately. */
+  args: readonly string[];
+  /** The resolved shell receives the exact command on stdin instead of argv. */
+  stdin?: boolean;
+  /** Private temporary directory prepared by the controller. */
+  privateTemp: string;
+  environment?: Readonly<Record<string, string | undefined>>;
+  pumConfigRoot?: string;
+  home?: string;
+  platform?: RuntimePlatform;
+};
+
+const SENSITIVE_ENVIRONMENT = /(?:^|_)(?:API_?KEY|AUTH|BEARER|COOKIE|CREDENTIALS?|PASS(?:WORD)?|PRIVATE_?KEY|SECRET|SESSION|TOKEN)(?:_|$)/i;
+const INJECTION_ENVIRONMENT = new Set([
+  "BASH_ENV", "BUN_OPTIONS", "ENV", "GIT_CONFIG_COUNT", "NODE_OPTIONS", "PERL5OPT",
+  "PROMPT_COMMAND", "PYTHONINSPECT", "PYTHONPATH", "RUBYOPT", "SHELLOPTS", "ZDOTDIR",
+]);
+
+export function isSandboxEnvironmentVariableDenied(name: string): boolean {
+  const upper = name.toUpperCase();
+  return SENSITIVE_ENVIRONMENT.test(upper)
+    || INJECTION_ENVIRONMENT.has(upper)
+    || upper.startsWith("AWS_")
+    || upper.startsWith("AZURE_")
+    || upper.startsWith("GOOGLE_")
+    || upper.startsWith("GITHUB_")
+    || upper.startsWith("NPM_")
+    || upper.startsWith("PUM_")
+    || upper.startsWith("PI_SESSION_");
+}
+
+/** Remove credentials, PUM/session metadata, and runtime injection variables. */
+export function sanitizeSandboxEnvironment(
+  environment: Readonly<Record<string, string | undefined>>,
+): Record<string, string> {
+  return Object.fromEntries(Object.entries(environment)
+    .filter(([name, value]) => value !== undefined
+      && !name.includes("\0")
+      && !isSandboxEnvironmentVariableDenied(name))
+    .map(([name, value]) => [name, value!] as const)
+    .sort(([first], [second]) => first.localeCompare(second)));
+}
+
+function pathApi(path: string, platform: RuntimePlatform): typeof posix {
+  return platform === "win32" || /^[A-Za-z]:[\\/]/.test(path) || path.startsWith("\\\\")
+    ? win32
+    : posix;
+}
+
+function canonicalPath(path: string, cwd: string, platform: RuntimePlatform): string {
+  const paths = pathApi(cwd, platform);
+  const absolute = paths.isAbsolute(path) ? path : paths.resolve(cwd, path);
+  return pathIdentity(absolute, platform);
+}
+
+function uniquePaths(paths: readonly string[], platform: RuntimePlatform): string[] {
+  return [...new Set(paths.map((path) => pathIdentity(path, platform)))]
+    .sort((first, second) => first.localeCompare(second));
+}
+
+/** Remove narrower paths when a root with the same permission already contains them. */
+function collapseSamePermissionRoots(paths: readonly string[], platform: RuntimePlatform): string[] {
+  const unique = uniquePaths(paths, platform);
+  return unique.filter((candidate) => !unique.some((parent) => (
+    parent !== candidate && isPathInsideOrSame(parent, candidate, platform)
+  )));
+}
+
+function deniedCredentialPaths(roots: readonly string[], home: string, platform: RuntimePlatform): string[] {
+  const directoryNames = [".ssh", ".gnupg", ".aws", ".azure", ".kube", ".docker"];
+  const fileNames = [
+    ".env", ".git-credentials", ".npmrc", ".pypirc", ".netrc", "auth.json", "credentials.json",
+  ];
+  const denied: string[] = [];
+  for (const root of [...roots, home]) {
+    const paths = pathApi(root, platform);
+    denied.push(...directoryNames.map((name) => paths.join(root, name)));
+    denied.push(...fileNames.map((name) => paths.join(root, name)));
+  }
+  if (platform !== "win32") {
+    denied.push("/root", "/etc/shadow", "/etc/gshadow", "/etc/sudoers", "/etc/sudoers.d", "/etc/ssh");
+  }
+  return uniquePaths(denied, platform);
+}
+
+function canonicalAccesses(
+  result: CheckPolicyResult,
+  cwd: string,
+  platform: RuntimePlatform,
+): SandboxPolicyAccess[] {
+  return result.accesses.map(({ resolvedPath, mode, source, stage, external }) => ({
+    resolvedPath: canonicalPath(resolvedPath, cwd, platform),
+    mode,
+    source,
+    stage,
+    external,
+  }));
+}
+
+/** Build a backend-neutral policy from authoritative inputs and deterministic Check mode output. */
+export function buildSandboxPolicy(options: BuildSandboxPolicyOptions): SandboxPolicy {
+  const platform = options.platform ?? process.platform;
+  if (!options.command || options.command.includes("\0")) throw new Error("Sandbox command is invalid");
+  const executionCommand = options.executionCommand ?? options.command;
+  if (options.result.exactCommand !== executionCommand) throw new Error("Sandbox command does not match the Check mode analysis");
+  if (!options.executable || options.executable.includes("\0")) throw new Error("Sandbox executable is invalid");
+  if (!pathApi(options.cwd, platform).isAbsolute(options.executable)) throw new Error("Sandbox executable must be resolved");
+  if (options.args.some((argument) => argument.includes("\0"))) throw new Error("Sandbox arguments are invalid");
+  if (!options.stdin && !options.args.includes(executionCommand)) {
+    throw new Error("Sandbox arguments must contain the exact command");
+  }
+  if (!options.result.analysis.complete || options.result.analysis.truncated || !options.result.analysis.syntaxBalanced) {
+    throw new Error("Sandbox policy requires complete Check mode analysis");
+  }
+  if (options.result.decision === "block") {
+    throw new Error(`Sandbox policy cannot grant a blocked command: ${options.result.reason}`);
+  }
+
+  const cwd = canonicalPath(options.cwd, options.cwd, platform);
+  const readWritePaths = collapseSamePermissionRoots([
+    cwd,
+    ...(options.additionalRoots ?? []).map((root) => canonicalPath(root, cwd, platform)),
+  ], platform);
+  const accesses = canonicalAccesses(options.result, cwd, platform);
+  const readOnlyPaths = collapseSamePermissionRoots(accesses
+    .filter((access) => access.external && access.mode === "read")
+    .map((access) => access.resolvedPath)
+    .filter((path) => !readWritePaths.some((root) => isPathInsideOrSame(root, path, platform))), platform);
+  const deniedPaths = uniquePaths([
+    canonicalPath(options.pumConfigRoot ?? AGENT_DIR, cwd, platform),
+    ...deniedCredentialPaths(readWritePaths, options.home ?? homedir(), platform),
+  ], platform);
+
+  const privateTemp = canonicalPath(options.privateTemp, cwd, platform);
+  const environment = sanitizeSandboxEnvironment(options.environment ?? process.env);
+  environment.TEMP = privateTemp;
+  environment.TMP = privateTemp;
+  if (platform !== "win32") environment.TMPDIR = privateTemp;
+
+  return {
+    version: 1,
+    exactCommand: options.command,
+    cwd,
+    readOnlyPaths,
+    readWritePaths,
+    deniedPaths,
+    privateTemp,
+    environment,
+    executable: canonicalPath(options.executable, cwd, platform),
+    args: [...options.args],
+    network: options.result.network.access === "host" ? "host" : "deny",
+    rationale: options.result.reason,
+    accesses,
+    networkCommands: [...options.result.network.commands],
+  };
+}
+
+export type SandboxModeDecision = {
+  action: "direct" | "sandbox" | "block";
+  warning?: string;
+  reason?: string;
+};
+
+/** Resolve one capability probe. The caller displays an automatic fallback warning once. */
+export function decideSandboxMode(
+  mode: SandboxMode,
+  capability: SandboxCapability,
+): SandboxModeDecision {
+  if (mode === "off") return { action: "direct" };
+  if (capability.state === "enforced") return { action: "sandbox" };
+  const reason = capability.reason ?? `sandbox backend ${capability.backend} is ${capability.state}`;
+  if (mode === "require") {
+    return { action: "block", reason: `Sandbox enforcement is required: ${reason}` };
+  }
+  return {
+    action: "direct",
+    warning: `Sandbox enforcement is unavailable. PUM will use deterministic Check mode only. ${reason}`,
+  };
+}

package/src/settings-popup.tsx

@@ -14,6 +14,7 @@ export type SettingRowId =
   | "writingStyle"
   | "explanationStrength"
   | "checkMode"
+  | "sandboxMode"
   | "checkModel"
   | "checkPaths"
   | "clearCheckApprovals"
@@ -44,6 +45,7 @@ export const SETTINGS_ROWS: readonly SettingRow[] = [
   { id: "explanationStrength", label: "Explanations", category: "Agent", keywords: "progress updates output none simple detailed rationale", description: "Choose how much regular output explains the agent plan, actions, decisions, and results." },
   { id: "webSearch", label: "Web search", category: "Agent", keywords: "internet hosted codex provider", description: "Allow hosted web search on supported Codex providers. Other providers are unchanged." },
   { id: "checkMode", label: "Check mode", category: "Safety", keywords: "profile strict balanced ask verify tools hard block approval bash edit patch", description: "Choose off, strict, balanced, or ask. Hard security rules apply to every active profile." },
+  { id: "sandboxMode", label: "Sandbox", category: "Safety", keywords: "os isolation auto require off enforcement fallback bash", description: "Choose automatic fallback, required OS enforcement, or no OS sandbox for Bash commands." },
   { id: "checkModel", label: "Check model", category: "Safety", keywords: "verifier tools safety structured verdict model", description: "Select the separate verifier model used for ambiguous Check mode calls." },
   { id: "checkPaths", label: "Allowed paths", category: "Safety", keywords: "additional directories roots boundary command", description: "Use /check-path to manage extra directory roots allowed by Check mode for this project." },
   { id: "clearCheckApprovals", label: "Clear approvals", category: "Safety", keywords: "remove reset exact project approvals ask", description: "Remove exact Check mode approvals stored for this project." },

package/src/settings.ts

@@ -8,11 +8,13 @@ import {
   isExplanationStrength,
   type ExplanationStrength,
 } from "./explanation-strength";
+import type { SandboxMode } from "./sandbox/types";
 
 export const WORKING_RULE_ANIMATION_MODES = ["off", "input-only", "coordinated"] as const;
 export type WorkingRuleAnimationMode = (typeof WORKING_RULE_ANIMATION_MODES)[number];
 export const CHECK_MODE_PROFILES = ["off", "strict", "balanced", "ask"] as const;
 export type CheckModeProfile = (typeof CHECK_MODE_PROFILES)[number];
+export const SANDBOX_MODES = ["auto", "require", "off"] as const;
 export const MIN_ACTIVE_SUBAGENTS = 1;
 export const MAX_ACTIVE_SUBAGENTS = 25;
 export const DEFAULT_MAX_ACTIVE_SUBAGENTS = 10;
@@ -63,6 +65,10 @@ export function isCheckModeProfile(value: unknown): value is CheckModeProfile {
   return CHECK_MODE_PROFILES.includes(value as CheckModeProfile);
 }
 
+export function isSandboxMode(value: unknown): value is SandboxMode {
+  return SANDBOX_MODES.includes(value as SandboxMode);
+}
+
 export function isWorkingRuleAnimationMode(value: unknown): value is WorkingRuleAnimationMode {
   return WORKING_RULE_ANIMATION_MODES.includes(value as WorkingRuleAnimationMode);
 }
@@ -83,6 +89,8 @@ export type PumSettings = {
   explanationStrength: ExplanationStrength;
   checkMode: CheckModeProfile;
   checkModel: string;
+  /** OS sandbox enforcement. Legacy settings omit this field and migrate to auto. */
+  sandboxMode?: SandboxMode;
   /** Additional canonical directory roots allowed by Check mode, keyed by launch project. */
   checkPaths?: CheckPathsByProject;
   maxActiveSubagents: number;
@@ -100,6 +108,7 @@ const DEFAULTS: PumSettings = {
   explanationStrength: "simple",
   checkMode: "off",
   checkModel: DEFAULT_CHECK_MODEL,
+  sandboxMode: "auto",
   checkPaths: {},
   maxActiveSubagents: DEFAULT_MAX_ACTIVE_SUBAGENTS,
 };
@@ -128,6 +137,7 @@ export function normalizeSettings(parsed: unknown): PumSettings {
       typeof merged.checkModel === "string" && merged.checkModel.includes("/")
         ? merged.checkModel
         : DEFAULTS.checkModel,
+    sandboxMode: isSandboxMode(merged.sandboxMode) ? merged.sandboxMode : DEFAULTS.sandboxMode,
     checkPaths: normalizeCheckPathsByProject(merged.checkPaths),
     maxActiveSubagents: normalizeMaxActiveSubagents(merged.maxActiveSubagents),
   };