just-bash-mcp 2.8.0 → 2.9.1

package/README.md

@@ -7,15 +7,20 @@ An MCP (Model Context Protocol) server that provides a sandboxed bash environmen
 
 Execute bash commands in a secure, isolated environment with an in-memory virtual filesystem.
 
-Built on top of [`just-bash`](https://github.com/vercel-labs/just-bash) v2.5.2.
+Built on top of [`just-bash`](https://github.com/vercel-labs/just-bash) v2.10.2.
 
-## What's New in v2.1.0
+## What's New in v2.9.0
 
+- **Synced with upstream `just-bash` v2.10.2** - Latest upstream commands, APIs, and type exports
+- **Defense-in-depth mode** - Opt-in monkey-patching of dangerous JS globals (`JUST_BASH_DEFENSE_IN_DEPTH=true`)
+- **Python support** - Python3 via Pyodide (`JUST_BASH_ENABLE_PYTHON=true`)
+- **Vercel Sandbox API** - Compatible `bash_sandbox_*` tools for isolated execution
+- **oxlint/oxfmt toolchain** - Replaced tsc/biome with faster oxlint and oxfmt
+- **Configurable limits** - Fine-grained control over glob ops, string length, array size, heredoc size, and more
 - **`rg` (ripgrep)** - Fast regex search with `--files`, `-d`, `--stats`, `-t markdown`
 - **`tar`** - Archive support with compression
 - **MountableFS** - Mount multiple filesystems at different paths
 - **ReadWriteFS** - Direct read-write access to real directories
-- **Multi-level glob patterns** - Improved `**/*.ts` style matching
 
 ## Features
 
@@ -120,6 +125,16 @@ Add to your MCP settings:
 | `JUST_BASH_MAX_CALL_DEPTH` | Maximum function recursion depth | `100` |
 | `JUST_BASH_MAX_COMMAND_COUNT` | Maximum total commands per execution | `10000` |
 | `JUST_BASH_MAX_LOOP_ITERATIONS` | Maximum iterations per loop | `10000` |
+| `JUST_BASH_ENABLE_PYTHON` | Enable Python3 via Pyodide (`true`/`false`) | `false` |
+| `JUST_BASH_DEFENSE_IN_DEPTH` | Enable defense-in-depth mode (`true`/`false`) | `false` |
+| `JUST_BASH_DEFENSE_IN_DEPTH_AUDIT` | Audit mode: log violations but don't block | `false` |
+| `JUST_BASH_DEFENSE_IN_DEPTH_LOG` | Log violations to console | `false` |
+| `JUST_BASH_OVERLAY_READ_ONLY` | OverlayFS read-only mode | `false` |
+| `JUST_BASH_MAX_RESPONSE_SIZE` | Max network response body size (bytes) | `10485760` |
+| `JUST_BASH_MAX_FILE_READ_SIZE` | Max file read size for OverlayFs/ReadWriteFs | `10485760` |
+| `JUST_BASH_ALLOWED_COMMANDS` | Comma-separated command allow-list | all |
+| `JUST_BASH_ENABLE_LOGGING` | Enable execution logging | `false` |
+| `JUST_BASH_ENABLE_TRACING` | Enable performance tracing | `false` |
 
 ## Tools
 
@@ -149,9 +164,28 @@ Reset the persistent bash environment, clearing all files and state.
 
 File operations in the persistent environment.
 
+### `bash_direct_read` / `bash_direct_write`
+
+Direct filesystem read/write operations (bypass shell execution).
+
 ### `bash_info`
 
-Get information about the bash environment configuration.
+Get information about the bash environment configuration, including defense-in-depth violation stats.
+
+### `bash_get_cwd` / `bash_get_env`
+
+Get current working directory or environment variables.
+
+### Vercel Sandbox API
+
+Compatible with the Vercel Sandbox API:
+
+- `bash_sandbox_run` - Run a command in the sandbox
+- `bash_sandbox_write_files` - Write multiple files at once
+- `bash_sandbox_read_file` - Read a file (supports base64 encoding)
+- `bash_sandbox_mkdir` - Create a directory
+- `bash_sandbox_stop` - Stop and clean up the sandbox
+- `bash_sandbox_reset` - Reset the sandbox state
 
 ## Supported Commands
 
@@ -235,6 +269,26 @@ Get information about the bash environment configuration.
 - Execution limits protect against infinite loops and recursion
 - No binary/WASM execution
 - Network disabled by default; when enabled, URL and method allow-lists enforced
+- **Defense-in-depth mode** (opt-in): Monkey-patches dangerous JS globals (`Function`, `eval`, `setTimeout`, `process`, etc.) during script execution to block escape vectors
+- **SecurityViolationLogger**: Tracks all defense-in-depth violations with full stats accessible via `bash_info`
+- **Rich network error classification**: `NetworkAccessDeniedError`, `TooManyRedirectsError`, `RedirectNotAllowedError` for precise error messages
+
+## Upstream API Coverage
+
+This wrapper integrates the full public API surface of `just-bash` v2.10.2:
+
+| Category | Exports Used |
+|----------|-------------|
+| Core | `Bash`, `BashOptions`, `ExecOptions`, `BashExecResult` |
+| Commands | `CommandName`, `AllCommandName`, `getCommandNames`, `getNetworkCommandNames`, `getPythonCommandNames` |
+| Custom Commands | `defineCommand`, `CustomCommand`, `LazyCommand` |
+| Filesystem | `InMemoryFs`, `OverlayFs`, `ReadWriteFs`, `MountableFs`, `IFileSystem` |
+| Network | `NetworkConfig`, `NetworkAccessDeniedError`, `TooManyRedirectsError`, `RedirectNotAllowedError` |
+| Sandbox | `Sandbox`, `SandboxCommand`, `SandboxOptions`, `OutputMessage` |
+| Security | `DefenseInDepthBox`, `SecurityViolationLogger`, `SecurityViolationError`, `createConsoleViolationCallback` |
+| Trace | `TraceCallback`, `TraceEvent` |
+
+All types are re-exported from `src/types.ts` for downstream consumers.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "just-bash-mcp",
-	"version": "2.8.0",
+	"version": "2.9.1",
 	"description": "MCP server providing a sandboxed bash environment using just-bash",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -61,13 +61,13 @@
 	"packageManager": "bun@1.3.8",
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.26.0",
-		"just-bash": "^2.9.6",
+		"just-bash": "^2.10.2",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@types/node": "^25.2.1",
+		"@types/node": "^25.2.3",
 		"oxfmt": "^0.28.0",
-		"oxlint": "^1.43.0",
-		"oxlint-tsgolint": "^0.11.4"
+		"oxlint": "^1.48.0",
+		"oxlint-tsgolint": "^0.11.5"
 	}
 }

package/src/config/index.ts

@@ -3,23 +3,24 @@
  * Handles environment variable parsing and configuration building
  */
 
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
 	type BashLogger,
 	type BashOptions,
 	type CommandName,
-	InMemoryFs,
-	MountableFs,
+	type DefenseInDepthConfig,
 	type MountConfig,
 	type NetworkConfig,
 	OverlayFs,
 	ReadWriteFs,
+	SecurityViolationLogger,
+	createConsoleViolationCallback,
 } from "just-bash";
 
-// ============================================================================
-// Types
-// ============================================================================
-
-export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+// Re-export upstream types used by other modules
+export type { DefenseInDepthConfig };
 
 export interface TraceEvent {
 	category: string;
@@ -30,6 +31,12 @@ export interface TraceEvent {
 
 export type TraceCallback = (event: TraceEvent) => void;
 
+// ============================================================================
+// Types
+// ============================================================================
+
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+
 // ============================================================================
 // Environment Variable Parsing
 // ============================================================================
@@ -89,10 +96,28 @@ export interface Config {
 	readonly ENABLE_TRACING: boolean;
 	readonly ENABLE_PYTHON: boolean;
 	readonly ENABLE_DEFENSE_IN_DEPTH: boolean;
+	readonly DEFENSE_IN_DEPTH_AUDIT: boolean;
+	readonly DEFENSE_IN_DEPTH_LOG: boolean;
 	readonly OVERLAY_READ_ONLY: boolean;
 	readonly ALLOWED_COMMANDS: CommandName[] | undefined;
 }
 
+function readPackageVersion(relativePath: string): string {
+	try {
+		const __dirname = dirname(fileURLToPath(import.meta.url));
+		const packagePath = join(__dirname, relativePath);
+		const packageJson = JSON.parse(readFileSync(packagePath, "utf-8")) as { version?: string };
+		return packageJson.version || "unknown";
+	} catch {
+		return "unknown";
+	}
+}
+
+export const WRAPPER_VERSION = readPackageVersion("../../package.json");
+export const UPSTREAM_JUST_BASH_VERSION = readPackageVersion(
+	"../../node_modules/just-bash/package.json",
+);
+
 function getAllowedMethods(): HttpMethod[] {
 	const methods = parseEnvStringArray("JUST_BASH_ALLOWED_METHODS");
 	return methods.length > 0 ? (methods as HttpMethod[]) : ["GET", "HEAD"];
@@ -112,7 +137,7 @@ function parseEnvOptionalInt(key: string): number | undefined {
 
 export const config: Config = {
 	// Server info
-	VERSION: "2.8.0",
+	VERSION: WRAPPER_VERSION,
 	SERVER_NAME: "just-bash-mcp",
 
 	// Filesystem configuration
@@ -157,6 +182,8 @@ export const config: Config = {
 	// Feature flags
 	ENABLE_PYTHON: parseEnvBoolean("JUST_BASH_ENABLE_PYTHON", false),
 	ENABLE_DEFENSE_IN_DEPTH: parseEnvBoolean("JUST_BASH_DEFENSE_IN_DEPTH", false),
+	DEFENSE_IN_DEPTH_AUDIT: parseEnvBoolean("JUST_BASH_DEFENSE_IN_DEPTH_AUDIT", false),
+	DEFENSE_IN_DEPTH_LOG: parseEnvBoolean("JUST_BASH_DEFENSE_IN_DEPTH_LOG", false),
 	OVERLAY_READ_ONLY: parseEnvBoolean("JUST_BASH_OVERLAY_READ_ONLY", false),
 
 	// Command filtering
@@ -186,7 +213,7 @@ export const bashLogger: BashLogger | undefined = config.ENABLE_LOGGING
 		}
 	: undefined;
 
-export const traceCallback: TraceCallback | undefined = config.ENABLE_TRACING
+export const traceCallback: BashOptions["trace"] = config.ENABLE_TRACING
 	? (event: TraceEvent) => {
 			if (event.details) {
 				console.error(
@@ -199,6 +226,39 @@ export const traceCallback: TraceCallback | undefined = config.ENABLE_TRACING
 		}
 	: undefined;
 
+// ============================================================================
+// Defense-in-Depth Configuration
+// ============================================================================
+
+/**
+ * Shared SecurityViolationLogger instance for tracking violations across
+ * all Bash instances. Exposed so info-tools can report violation stats.
+ */
+export const violationLogger = new SecurityViolationLogger();
+
+/**
+ * Build the defense-in-depth configuration from environment variables.
+ * Returns `false` when disabled, or a full DefenseInDepthConfig object.
+ */
+export function buildDefenseInDepthConfig(): DefenseInDepthConfig | false {
+	if (!config.ENABLE_DEFENSE_IN_DEPTH) {
+		return false;
+	}
+
+	const consoleCallback = config.DEFENSE_IN_DEPTH_LOG
+		? createConsoleViolationCallback()
+		: undefined;
+
+	return {
+		enabled: true,
+		auditMode: config.DEFENSE_IN_DEPTH_AUDIT,
+		onViolation: (violation: { type: string; target: string; details: string }) => {
+			violationLogger.record(violation);
+			consoleCallback?.(violation);
+		},
+	};
+}
+
 // ============================================================================
 // Configuration Builders
 // ============================================================================
@@ -315,6 +375,10 @@ export const ENVIRONMENT_VARIABLES = {
 	JUST_BASH_ENABLE_PYTHON: "Enable python3/python commands via Pyodide (default: false)",
 	JUST_BASH_DEFENSE_IN_DEPTH:
 		"Enable defense-in-depth mode that patches dangerous JS globals (default: false)",
+	JUST_BASH_DEFENSE_IN_DEPTH_AUDIT:
+		"Audit mode: log violations but don't block them (default: false, requires DEFENSE_IN_DEPTH=true)",
+	JUST_BASH_DEFENSE_IN_DEPTH_LOG:
+		"Log violations to console via createConsoleViolationCallback (default: false)",
 } as const;
 
 // ============================================================================
@@ -340,19 +404,25 @@ export const COMMAND_CATEGORIES = {
 // ============================================================================
 
 export const FEATURES = {
-	customCommands: "Define custom TypeScript commands using defineCommand()",
+	customCommands:
+		"Define custom TypeScript commands using defineCommand() from just-bash, supports lazy-loading via LazyCommand",
 	rawScript: "Preserve leading whitespace in scripts (useful for here-docs)",
 	logger: "Optional execution logging via BashLogger interface",
-	trace: "Performance profiling via TraceCallback",
+	trace: "Performance profiling via TraceCallback (upstream type)",
 	commandFilter: "Restrict available commands via JUST_BASH_ALLOWED_COMMANDS env var",
-	sandboxApi: "Vercel Sandbox compatible API via bash_sandbox_* tools",
+	sandboxApi:
+		"Vercel Sandbox compatible API via bash_sandbox_* tools (run, write, read, mkdir, stop, reset)",
 	python: "Python support via Pyodide (opt-in via JUST_BASH_ENABLE_PYTHON=true)",
 	defenseInDepth:
-		"Defense-in-depth mode that monkey-patches dangerous JS globals during execution (opt-in via JUST_BASH_DEFENSE_IN_DEPTH=true)",
+		"Defense-in-depth with SecurityViolationLogger, audit mode, and console logging (opt-in via JUST_BASH_DEFENSE_IN_DEPTH=true)",
 	overlayReadOnly:
 		"Read-only overlay filesystem mode (opt-in via JUST_BASH_OVERLAY_READ_ONLY=true)",
 	networkResponseSize:
 		"Configurable max network response body size via JUST_BASH_MAX_RESPONSE_SIZE",
 	fileReadSizeLimit:
 		"Configurable max file read size for OverlayFs/ReadWriteFs via JUST_BASH_MAX_FILE_READ_SIZE",
+	networkErrorHandling:
+		"Rich network error classification: NetworkAccessDeniedError, TooManyRedirectsError, RedirectNotAllowedError",
+	securityViolationTracking:
+		"SecurityViolationLogger tracks all defense-in-depth violations with stats via bash_info",
 } as const;

package/src/tools/bash-instance.ts

@@ -1,33 +1,79 @@
 /**
  * Bash instance management
  * Handles creation and lifecycle of Bash instances
+ *
+ * Uses all upstream just-bash APIs:
+ * - Bash, Sandbox, SandboxCommand for execution
+ * - DefenseInDepthBox with SecurityViolationLogger for security monitoring
+ * - defineCommand for custom command registration
+ * - All filesystem variants (InMemoryFs, MountableFs, OverlayFs, ReadWriteFs)
+ * - Network error classes for rich error reporting (handled in exec-tools/sandbox-tools)
  */
 
 import {
 	Bash,
 	type BashOptions,
 	type CustomCommand,
+	DefenseInDepthBox,
 	InMemoryFs,
 	MountableFs,
 	OverlayFs,
 	ReadWriteFs,
 	Sandbox,
 	type SandboxOptions,
+	defineCommand,
 } from "just-bash";
 
 import {
 	bashLogger,
+	buildDefenseInDepthConfig,
 	buildExecutionLimits,
 	buildNetworkConfig,
 	config,
 	parseMountsConfig,
 	traceCallback,
+	violationLogger,
 } from "../config/index.ts";
 
 // ============================================================================
 // Bash Instance Factory
 // ============================================================================
 
+// ============================================================================
+// Defense-in-Depth Box (singleton)
+// ============================================================================
+
+let defenseInDepthBox: DefenseInDepthBox | null = null;
+
+/**
+ * Get or create the shared DefenseInDepthBox instance.
+ * Returns null if defense-in-depth is disabled.
+ */
+export function getDefenseInDepthBox(): DefenseInDepthBox | null {
+	const didConfig = buildDefenseInDepthConfig();
+	if (!didConfig) return null;
+
+	if (!defenseInDepthBox) {
+		defenseInDepthBox = new DefenseInDepthBox(didConfig);
+	}
+	return defenseInDepthBox;
+}
+
+/**
+ * Get the shared SecurityViolationLogger for querying violation stats.
+ */
+export { violationLogger } from "../config/index.ts";
+
+/**
+ * Re-export defineCommand so downstream consumers can create custom commands
+ * using the upstream API without importing just-bash directly.
+ */
+export { defineCommand };
+
+// ============================================================================
+// Bash Instance Factory
+// ============================================================================
+
 /**
  * Create a new Bash instance with the given configuration
  */
@@ -38,6 +84,7 @@ export function createBashInstance(
 ): Bash {
 	const networkConfig = buildNetworkConfig();
 	const executionLimits = buildExecutionLimits();
+	const defenseInDepthConfig = buildDefenseInDepthConfig();
 
 	const baseOptions: BashOptions = {
 		network: networkConfig,
@@ -49,7 +96,7 @@ export function createBashInstance(
 		customCommands,
 		commands: config.ALLOWED_COMMANDS,
 		python: config.ENABLE_PYTHON,
-		defenseInDepth: config.ENABLE_DEFENSE_IN_DEPTH,
+		defenseInDepth: defenseInDepthConfig,
 	};
 
 	// Check for mountable filesystem configuration
@@ -134,7 +181,8 @@ export function resetPersistentBash(): void {
 let persistentSandbox: Sandbox | null = null;
 
 /**
- * Get or create the persistent Sandbox instance
+ * Get or create the persistent Sandbox instance.
+ * Passes all available configuration including network and filesystem options.
  */
 export async function getPersistentSandbox(): Promise<Sandbox> {
 	if (!persistentSandbox) {
@@ -153,8 +201,12 @@ export async function getPersistentSandbox(): Promise<Sandbox> {
 }
 
 /**
- * Reset the persistent Sandbox instance
+ * Reset the persistent Sandbox instance.
+ * Calls Sandbox.stop() to clean up resources before releasing.
  */
-export function resetPersistentSandbox(): void {
+export async function resetPersistentSandbox(): Promise<void> {
+	if (persistentSandbox) {
+		await persistentSandbox.stop();
+	}
 	persistentSandbox = null;
 }

package/src/tools/exec-tools.ts

@@ -1,13 +1,45 @@
 /**
  * Bash execution tools
  * Core tools for executing bash commands
+ *
+ * Uses upstream network error classes for rich error classification:
+ * - NetworkAccessDeniedError: URL not in allowlist
+ * - TooManyRedirectsError: Redirect limit exceeded
+ * - RedirectNotAllowedError: Redirect target not in allowlist
+ * - SecurityViolationError: Defense-in-depth violation detected
  */
 
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+	NetworkAccessDeniedError,
+	RedirectNotAllowedError,
+	SecurityViolationError,
+	TooManyRedirectsError,
+} from "just-bash";
 import { z } from "zod/v4";
 import { createErrorResponse, formatExecResult } from "../utils/index.ts";
 import { createBashInstance, getPersistentBash, resetPersistentBash } from "./bash-instance.ts";
 
+/**
+ * Classify errors from just-bash into user-friendly messages.
+ * Uses upstream error classes for precise classification.
+ */
+function classifyError(error: unknown, prefix: string) {
+	if (error instanceof NetworkAccessDeniedError) {
+		return createErrorResponse(error, `${prefix} [Network Access Denied]`);
+	}
+	if (error instanceof TooManyRedirectsError) {
+		return createErrorResponse(error, `${prefix} [Too Many Redirects]`);
+	}
+	if (error instanceof RedirectNotAllowedError) {
+		return createErrorResponse(error, `${prefix} [Redirect Not Allowed]`);
+	}
+	if (error instanceof SecurityViolationError) {
+		return createErrorResponse(error, `${prefix} [Security Violation]`);
+	}
+	return createErrorResponse(error, prefix);
+}
+
 /**
  * Register bash execution tools with the MCP server
  */
@@ -63,7 +95,7 @@ export function registerExecTools(server: McpServer): void {
 				const result = await bash.exec(command, { cwd, env, rawScript });
 				return formatExecResult(result);
 			} catch (error) {
-				return createErrorResponse(error, "Execution error");
+				return classifyError(error, "Execution error");
 			}
 		},
 	);
@@ -104,7 +136,7 @@ export function registerExecTools(server: McpServer): void {
 				const result = await bash.exec(command, { cwd, env, rawScript });
 				return formatExecResult(result);
 			} catch (error) {
-				return createErrorResponse(error, "Execution error");
+				return classifyError(error, "Execution error");
 			}
 		},
 	);

package/src/tools/index.ts

@@ -13,10 +13,13 @@ import { registerSandboxTools } from "./sandbox-tools.ts";
 // Re-export bash instance utilities
 export {
 	createBashInstance,
+	defineCommand,
+	getDefenseInDepthBox,
 	getPersistentBash,
 	getPersistentSandbox,
 	resetPersistentBash,
 	resetPersistentSandbox,
+	violationLogger,
 } from "./bash-instance.ts";
 // Re-export individual registrations for fine-grained control
 export { registerExecTools } from "./exec-tools.ts";

package/src/tools/info-tools.ts

@@ -1,13 +1,14 @@
 /**
  * Information and state tools
  * Tools for getting information about the bash environment
+ *
+ * Uses upstream command registry types (AllCommandName, CommandName) and
+ * SecurityViolationLogger for defense-in-depth violation reporting.
  */
 
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
+	type AllCommandName,
 	type CommandName,
 	getCommandNames,
 	getNetworkCommandNames,
@@ -20,25 +21,11 @@ import {
 	ENVIRONMENT_VARIABLES,
 	FEATURES,
 	parseMountsConfig,
+	UPSTREAM_JUST_BASH_VERSION,
+	violationLogger,
 } from "../config/index.ts";
 import { createErrorResponse, createJsonResponse } from "../utils/index.ts";
-import { getPersistentBash } from "./bash-instance.ts";
-
-function getUpstreamVersion(): string {
-	try {
-		// Resolve the just-bash package directory relative to this module
-		const __dirname = dirname(fileURLToPath(import.meta.url));
-		const pkgPath = join(__dirname, "..", "..", "node_modules", "just-bash", "package.json");
-		const pkg: { version: string } = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
-			version: string;
-		};
-		return pkg.version;
-	} catch {
-		return "unknown";
-	}
-}
-
-const UPSTREAM_VERSION = getUpstreamVersion();
+import { getDefenseInDepthBox, getPersistentBash } from "./bash-instance.ts";
 
 /**
  * Register information tools with the MCP server
@@ -67,12 +54,33 @@ export function registerInfoTools(server: McpServer): void {
 			// Get actual available commands (respects ALLOWED_COMMANDS filter)
 			const allBuiltinCommands = getCommandNames();
 			const availableCommands = config.ALLOWED_COMMANDS
-				? allBuiltinCommands.filter((cmd) => config.ALLOWED_COMMANDS?.includes(cmd as CommandName))
+				? allBuiltinCommands.filter((cmd) =>
+						config.ALLOWED_COMMANDS?.includes(cmd as AllCommandName as CommandName),
+					)
 				: allBuiltinCommands;
 
+			// Build defense-in-depth status with violation stats
+			const didBox = getDefenseInDepthBox();
+			const defenseInDepthStatus = config.ENABLE_DEFENSE_IN_DEPTH
+				? {
+						enabled: true,
+						auditMode: config.DEFENSE_IN_DEPTH_AUDIT,
+						consoleLogging: config.DEFENSE_IN_DEPTH_LOG,
+						boxActive: didBox?.isActive() ?? false,
+						...(didBox && {
+							stats: didBox.getStats(),
+						}),
+						violations: {
+							total: violationLogger.getTotalCount(),
+							hasViolations: violationLogger.hasViolations(),
+							summary: violationLogger.getSummary(),
+						},
+					}
+				: { enabled: false };
+
 			const info = {
 				version: config.VERSION,
-				upstreamVersion: UPSTREAM_VERSION,
+				upstreamVersion: UPSTREAM_JUST_BASH_VERSION,
 				fsMode,
 				fsRoot: config.READ_WRITE_ROOT || config.OVERLAY_ROOT || null,
 				overlayReadOnly: config.OVERLAY_ROOT ? config.OVERLAY_READ_ONLY : null,
@@ -88,7 +96,7 @@ export function registerInfoTools(server: McpServer): void {
 				loggingEnabled: config.ENABLE_LOGGING,
 				tracingEnabled: config.ENABLE_TRACING,
 				pythonEnabled: config.ENABLE_PYTHON,
-				defenseInDepthEnabled: config.ENABLE_DEFENSE_IN_DEPTH,
+				defenseInDepth: defenseInDepthStatus,
 				commandFilter: config.ALLOWED_COMMANDS || null,
 				executionLimits: buildExecutionLimits(),
 				availableCommands,

package/src/tools/sandbox-tools.ts

@@ -1,9 +1,21 @@
 /**
  * Sandbox API tools
  * Vercel Sandbox compatible tools for execution in an isolated environment
+ *
+ * Uses upstream Sandbox/SandboxCommand APIs:
+ * - Sandbox.create(), runCommand(), writeFiles(), readFile(), mkDir(), stop()
+ * - SandboxCommand: wait(), stdout(), stderr(), output(), logs(), kill()
+ * - Sandbox.domain getter for domain info
+ * - OutputMessage type for streaming output
  */
 
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+	NetworkAccessDeniedError,
+	RedirectNotAllowedError,
+	SecurityViolationError,
+	TooManyRedirectsError,
+} from "just-bash";
 import { z } from "zod/v4";
 import { config } from "../config/index.ts";
 import {
@@ -14,6 +26,25 @@ import {
 } from "../utils/index.ts";
 import { getPersistentSandbox, resetPersistentSandbox } from "./bash-instance.ts";
 
+/**
+ * Classify errors from just-bash into user-friendly messages.
+ */
+function classifyError(error: unknown, prefix: string) {
+	if (error instanceof NetworkAccessDeniedError) {
+		return createErrorResponse(error, `${prefix} [Network Access Denied]`);
+	}
+	if (error instanceof TooManyRedirectsError) {
+		return createErrorResponse(error, `${prefix} [Too Many Redirects]`);
+	}
+	if (error instanceof RedirectNotAllowedError) {
+		return createErrorResponse(error, `${prefix} [Redirect Not Allowed]`);
+	}
+	if (error instanceof SecurityViolationError) {
+		return createErrorResponse(error, `${prefix} [Security Violation]`);
+	}
+	return createErrorResponse(error, prefix);
+}
+
 /**
  * Register Vercel Sandbox compatible tools with the MCP server
  */
@@ -57,7 +88,7 @@ export function registerSandboxTools(server: McpServer): void {
 					result.exitCode !== 0,
 				);
 			} catch (error) {
-				return createErrorResponse(error, "Sandbox error");
+				return classifyError(error, "Sandbox error");
 			}
 		},
 	);
@@ -82,7 +113,7 @@ export function registerSandboxTools(server: McpServer): void {
 					`Successfully wrote ${Object.keys(files).length} file(s): ${Object.keys(files).join(", ")}`,
 				);
 			} catch (error) {
-				return createErrorResponse(error, "Write error");
+				return classifyError(error, "Write error");
 			}
 		},
 	);
@@ -96,12 +127,13 @@ export function registerSandboxTools(server: McpServer): void {
 			description: "Read a file from the sandbox environment.",
 			inputSchema: {
 				path: z.string().describe("The file path to read"),
+				encoding: z.enum(["utf-8", "base64"]).optional().describe("File encoding (default: utf-8)"),
 			},
 		},
-		async ({ path }: { path: string }) => {
+		async ({ path, encoding = "utf-8" }: { path: string; encoding?: "utf-8" | "base64" }) => {
 			try {
 				const sandbox = await getPersistentSandbox();
-				const content = await sandbox.readFile(path);
+				const content = await sandbox.readFile(path, encoding);
 
 				return {
 					content: [
@@ -112,7 +144,7 @@ export function registerSandboxTools(server: McpServer): void {
 					],
 				};
 			} catch (error) {
-				return createErrorResponse(error, "Read error");
+				return classifyError(error, "Read error");
 			}
 		},
 	);
@@ -139,7 +171,27 @@ export function registerSandboxTools(server: McpServer): void {
 
 				return createSuccessResponse(`Successfully created directory: ${path}`);
 			} catch (error) {
-				return createErrorResponse(error, "Mkdir error");
+				return classifyError(error, "Mkdir error");
+			}
+		},
+	);
+
+	// ========================================================================
+	// bash_sandbox_stop - Stop and clean up sandbox
+	// ========================================================================
+	server.registerTool(
+		"bash_sandbox_stop",
+		{
+			description:
+				"Stop and clean up the sandbox environment, releasing all resources. Use bash_sandbox_reset to just clear state.",
+			inputSchema: {},
+		},
+		async () => {
+			try {
+				await resetPersistentSandbox();
+				return createSuccessResponse("Sandbox environment has been stopped and cleaned up.");
+			} catch (error) {
+				return classifyError(error, "Stop error");
 			}
 		},
 	);
@@ -154,8 +206,12 @@ export function registerSandboxTools(server: McpServer): void {
 			inputSchema: {},
 		},
 		async () => {
-			resetPersistentSandbox();
-			return createSuccessResponse("Sandbox environment has been reset.");
+			try {
+				await resetPersistentSandbox();
+				return createSuccessResponse("Sandbox environment has been reset.");
+			} catch (error) {
+				return classifyError(error, "Reset error");
+			}
 		},
 	);
 }

package/src/types.ts

@@ -0,0 +1,7 @@
+/**
+ * Exact passthrough of the upstream just-bash public API.
+ *
+ * Keeping this as a wildcard export guarantees this wrapper stays 1:1 with
+ * whatever the installed just-bash version exposes.
+ */
+export * from "just-bash";