windows-development-sandbox 1.0.5 → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh DiDuca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,8 +4,8 @@
 
 **A throwaway Windows machine for every project, with or without an AI agent.**
 
-[![Release](https://img.shields.io/github/v/release/JoshDiDuca/agent-sandbox?label=release)](https://github.com/JoshDiDuca/agent-sandbox/releases/latest)
-[![CI](https://github.com/JoshDiDuca/agent-sandbox/actions/workflows/ci.yml/badge.svg)](https://github.com/JoshDiDuca/agent-sandbox/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/JoshDiDuca/windows-development-sandbox?label=release)](https://github.com/JoshDiDuca/windows-development-sandbox/releases/latest)
+[![CI](https://github.com/JoshDiDuca/windows-development-sandbox/actions/workflows/ci.yml/badge.svg)](https://github.com/JoshDiDuca/windows-development-sandbox/actions/workflows/ci.yml)
 ![Windows 10/11 Pro, Enterprise, Education](https://img.shields.io/badge/Windows-10%20%7C%2011%20Pro-0078D4)
 ![MIT](https://img.shields.io/badge/license-MIT-green)
 
@@ -18,19 +18,20 @@ on your PC is reachable. Close it and it's gone. Your project, tools, databases
 ## Install
 
 ```powershell
-irm https://github.com/JoshDiDuca/agent-sandbox/releases/latest/download/install.ps1 | iex
+irm https://github.com/JoshDiDuca/windows-development-sandbox/releases/latest/download/install.ps1 | iex
 ```
 
 It checks your PC, offers to turn on Windows Sandbox, and installs everything. It uses your Node.js 20+ if you have it,
 otherwise a private copy just for this tool. Nothing is installed system-wide.
-Needs Windows 10/11 **Pro, Enterprise or Education**. [Other ways to install](docs/install.md)
+Needs Windows 10/11 **Pro, Enterprise or Education**. Already have Node.js 20+? `npm install -g windows-development-sandbox`
+works too. [Other ways to install](docs/install.md)
 
 ## Use
 
 ```powershell
 cd C:\code\my-app
 
-sandbox            # menu: start an agent, a plain sandbox, diagnostics, cleanup ...
+sandbox            # the menu: start agents, sessions, apps, every setting, diagnostics ...
 sandbox claude     # Claude Code in a sandbox for this folder (or: claude-sandbox)
 sandbox claude -t  # ... in this terminal (Ctrl+] detaches, the session keeps running)
 sandbox start      # just the sandbox, no agent
@@ -48,26 +49,42 @@ The first start downloads what the project needs (a few minutes, once). After th
 |---|---|
 | **Safe by default** | The agent sees only your project folder. Credentials are stripped before anything is copied in, your LAN is blocked, and nothing the sandbox writes can run on your PC. |
 | **Languages** | Node, Python, Rust, C/C++ (GCC or MSVC), .NET (incl. .NET Framework targeting), Go, Java, Ruby, PHP, Deno, Bun, PowerShell 7, with pnpm, yarn, Volta, uv, pyenv, Maven, Gradle, Composer, gh ... |
-| **Databases** | PostgreSQL, MySQL, MongoDB, Redis and DynamoDB Local with a web UI, started only when the project uses them |
+| **Apps and tools** | VS Code (set up for your languages, with their extensions) and Windows Terminal, plus 60 optional apps and tools by category: DBeaver, pgAdmin, Bruno, Godot, Blender, kubectl, jq, ripgrep ... and programs of your own |
+| **Databases** | PostgreSQL, MySQL, MongoDB, Redis and DynamoDB Local with a web UI, started when the project uses them, or any time with `--database` / `sandbox db` |
 | **Agents** | Claude Code, Codex, Gemini, opencode, Qwen, Crush, Copilot, Kilo, Amp, Cline, Continue, Kimi, Aider, DeepSeek agents |
 | **Smart** | Detects what the project needs from its files, respects version files, installs in parallel and reuses everything |
+| **Several projects** | `sandbox claude` from another project joins the running sandbox: its own folder, tools, versions, databases and environment, set up on demand. Start several agents at once (`--session claude@A --session codex@B`, or the menu) and attach to any of them from any terminal |
+| **Agent commands** (Beta) | `sandbox agent-commands on`: typing `claude`, `codex` ... in any folder starts it in a hidden sandbox and attaches your terminal |
 | **Feels like home** | Your desktop look, Claude settings, MCP servers and conversation history come along; history syncs back |
 
 ## Commands
 
 | Command | |
 |---|---|
-| `sandbox` | the interactive menu: repeat your last command, start agents, every option, and all settings |
+| `sandbox` | the menu, a full-screen app: start agents, attach to sessions, pick apps, edit every setting (yours and the project's), all commands, with search |
 | `sandbox <agent>`, `claude-sandbox` | start an agent; `-t` for this terminal, `--headless` for no window |
 | `sandbox start` | the sandbox without an agent |
-| `sandbox attach` / `sessions` / `status` | work with a running sandbox |
+| `sandbox attach` / `sessions` / `status` | work with a running sandbox (this folder's project first) |
+| `sandbox projects` | the projects a sandbox can open without a restart: roots, `all`, exclude |
+| `sandbox db [start\|stop <name>]` | list, start or stop databases (`sbx-db` inside) |
 | `sandbox exec -- <cmd>` | run a command inside |
+| `sandbox agent-commands on\|off` | (Beta) make the agents installed on this PC start in a sandbox |
+| `sandbox --version` | the installed version |
 | `sandbox stop` / `hide` / `show` | shut down, hide or show the window |
 | `sandbox data` / `data clean` | what's stored and how big, and freeing space |
 | `sandbox setup` / `doctor` / `repair` | check this PC, see what will be installed, fix common problems |
 
 All commands and options: [docs/commands.md](docs/commands.md)
 
+## Known gaps
+
+Adding a folder to a RUNNING sandbox needs Windows 11 24H2+ with the updated Windows Sandbox (`wsb share`, untested).
+On older Windows: folders inside a mapped project root (`sandbox projects roots add <folder>`) open instantly;
+anything else offers a restart (your files, tools, databases and logins are kept; the sessions can be reopened).
+
+To get `wsb`: Settings > Windows Update, turn on "Get the latest updates as soon as they're available" (or use the
+Windows 11 Installation Assistant), then update Windows Sandbox from the Microsoft Store. Check with `wsb --version`.
+
 ## Documentation
 
 - [Install](docs/install.md): requirements, other ways to install, upgrading

package/config.example.json

@@ -3,10 +3,25 @@
   "defaultHarness": "claude",
   "guestWorkspace": "auto",
   "readOnly": false,
+  "workspaceFilter": {
+    "enabled": false,
+    "exclude": [],
+    "include": []
+  },
+  "audit": {
+    "enabled": false,
+    "days": 14,
+    "maxMb": 100,
+    "processes": true,
+    "files": true
+  },
   "mappings": [],
   "sandbox": {
     "memoryMb": "auto",
     "maxMemoryMb": 32768,
+    "maxMemoryPercent": 80,
+    "cpuLimit": 80,
+    "pageFileMb": 16384,
     "reserveHostMb": 8192,
     "vGpu": false,
     "networking": true,
@@ -15,15 +30,23 @@
     "videoInput": false,
     "printerRedirection": false,
     "protectedClient": true,
-    "headless": false
+    "headless": false,
+    "keepAwake": true
   },
   "storage": {
     "root": "%LOCALAPPDATA%\\AgentSandbox",
     "persistAgentState": true,
-    "dataName": "default"
+    "dataName": "default",
+    "markSandboxFiles": true,
+    "warnDataGb": 50
   },
   "network": {
-    "blockPrivateRanges": true
+    "blockPrivateRanges": true,
+    "allowOnly": [],
+    "blockHosts": [],
+    "forwardPorts": [],
+    "dns": [],
+    "proxy": ""
   },
   "provisioning": {
     "copyFromHost": true,
@@ -35,8 +58,14 @@
     },
     "terminal": {
       "enabled": true
+    },
+    "conpty": {
+      "enabled": true
     }
   },
+  "downloads": {
+    "requireChecksum": false
+  },
   "toolchains": {
     "node": {
       "version": "host",
@@ -130,7 +159,10 @@
       "vulkan": false
     },
     "vscode": {
-      "enabled": true
+      "enabled": true,
+      "setup": true,
+      "recommended": true,
+      "extensions": []
     },
     "environment": {}
   },
@@ -170,6 +202,10 @@
     "auto": false,
     "autoHide": false
   },
+  "agentCommands": {
+    "enabled": false,
+    "agents": "auto"
+  },
   "secrets": {
     "strip": true,
     "allow": [],
@@ -179,6 +215,10 @@
   "personalization": {
     "enabled": true
   },
+  "apps": {
+    "install": [],
+    "custom": {}
+  },
   "claudeProfile": {
     "enabled": true,
     "hostDir": "auto",
@@ -194,7 +234,9 @@
     "copyCredentials": false,
     "overwrite": true,
     "syncHistory": true,
-    "syncClaudeMem": true
+    "historyScope": "project",
+    "syncClaudeMem": true,
+    "syncClaudeMemBack": false
   },
   "harnesses": {
     "claude": {
@@ -328,5 +370,13 @@
   },
   "hooks": {
     "failFast": false
+  },
+  "projects": {
+    "all": false,
+    "exclude": [],
+    "roots": [],
+    "askToAddRoot": true,
+    "declinedRoots": [],
+    "wsbShare": true
   }
 }

package/dist/api.js

@@ -1,7 +1,8 @@
 // Programmatic API: `import { sandbox } from 'windows-development-sandbox'`. Same safety model as the CLI: the host only sends the
 // request kinds the guest daemon accepts, and everything coming back is validated data.
 import path from 'node:path';
-import { attachTerminal, execInSandbox, pickSession, pingSandbox, requestSession, restartSessions, waitForReady, waitForSession } from './host/channel.js';
+import { attachTerminal } from './host/attach.js';
+import { execInSandbox, pickSession, pingSandbox, requestSession, restartSessions, waitForReady, waitForSession } from './host/channel.js';
 import { loadConfig } from './core/config.js';
 import { listSessions, readSandboxStatus } from './shared/rundir.js';
 import { isSandboxRunning } from './host/platform.js';

package/dist/cli/args.d.ts

@@ -25,7 +25,30 @@ export interface CliOptions {
     yes: boolean;
     timeout: number;
     days: number;
+    /** restart: every session, not only this folder's project's. */
+    all: boolean;
+    /** launch --session <agent>@<folder> (repeatable): several sessions at once, folders made absolute. */
+    sessions: SessionWant[];
+    /** audit: only events of this kind, and containing this text. */
+    kind?: string;
+    grep?: string;
 }
+/** One session to start: an agent in a folder, with arguments of its own (after the ones given after --). */
+export interface SessionWant {
+    harness: string;
+    folder: string;
+    args?: string[];
+}
+/** Splits a command line like a shell: "quoted words" and 'quoted words' stay together. */
+export declare const splitArgs: (text: string) => string[];
+/**
+ * `<agent>@<folder>` (the folder may contain '@': only the first one splits), `<agent>` alone = the current folder,
+ * and `|<arguments>` for that session's agent only ('|' cannot be in a Windows path). Folders become absolute against
+ * `cwd`. Pure; validate.ts checks that the agent and folder exist.
+ */
+export declare const parseSessionWant: (input: string, cwd?: string) => SessionWant;
+/** This package's version (this file is dist/cli/args.js, two folders below package.json). */
+export declare const packageVersion: () => string;
 /** Every command, its options and help text, from manifest.ts. Actions only record what was parsed. */
 export declare const buildProgram: (record: (name: string, cmd: Command) => void) => Command;
 /** Parses argv into the command name and options. Throws commander errors for unknown commands/options. */

package/dist/cli/args.js

@@ -1,8 +1,35 @@
 // Command-line parsing with commander. parseCli() only parses (no side effects), so it is easy to test; cli/index.ts
 // dispatches the result. sandbox claude & co parse as `launch`: every option launch does not own goes to the agent, in order.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Command, InvalidArgumentError, Option } from 'commander';
-import { fail } from '../core/util.js';
+import { z } from 'zod';
+import { fail, tryReadJson } from '../core/util.js';
+import { c } from './colors.js';
 import { COMMANDS } from './manifest.js';
+/** Splits a command line like a shell: "quoted words" and 'quoted words' stay together. */
+export const splitArgs = (text) => [...text.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3]);
+/**
+ * `<agent>@<folder>` (the folder may contain '@': only the first one splits), `<agent>` alone = the current folder,
+ * and `|<arguments>` for that session's agent only ('|' cannot be in a Windows path). Folders become absolute against
+ * `cwd`. Pure; validate.ts checks that the agent and folder exist.
+ */
+export const parseSessionWant = (input, cwd = process.cwd()) => {
+    const bar = input.indexOf('|');
+    const text = bar < 0 ? input : input.slice(0, bar);
+    const args = bar < 0 ? [] : splitArgs(input.slice(bar + 1));
+    const at = text.indexOf('@');
+    const harness = (at < 0 ? text : text.slice(0, at)).trim();
+    const folder = at < 0 ? '' : text.slice(at + 1).trim();
+    if (!harness)
+        fail('--session "' + text + '" names no agent.', 'Use --session <agent>@<folder>, e.g. --session claude@C:\\code\\api (the folder defaults to this one).');
+    return { harness, folder: path.resolve(cwd, folder || '.'), ...(args.length ? { args } : {}) };
+};
+/** This package's version (this file is dist/cli/args.js, two folders below package.json). */
+export const packageVersion = () => {
+    const file = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    return z.object({ version: z.string() }).safeParse(tryReadJson(file)).data?.version ?? 'unknown';
+};
 /** Reserved spelling for our launch options that can never clash with an agent's flags: --sbx-terminal, ... */
 const SBX_PREFIX = '--sbx-';
 const positiveNumber = (value) => {
@@ -28,8 +55,11 @@ const toOption = (o) => {
 export const buildProgram = (record) => {
     const program = new Command('sandbox')
         .description('A disposable Windows Sandbox for development, with or without an AI agent, for the folder you are in. Run it with no arguments for the menu.')
+        .version(packageVersion(), '-v, --version', 'show the version')
         .enablePositionalOptions()
-        .showHelpAfterError('(run with --help for usage)')
+        .showHelpAfterError('  Fix:  run the command with --help to see how to use it.')
+        .configureOutput({ outputError: (text, write) => write(c.red('Error: ') + text.replace(/^error: /, '').replace(/^./, (ch) => ch.toUpperCase())) })
+        .addHelpText('after', '\nPut --config <file> before or after the command to use another settings file.\nExamples:\n  sandbox                       the menu\n  sandbox claude -t             start Claude and attach this terminal\n  sandbox data clean logs       delete the saved logs\n  sandbox exec -- npm test      run a command in the running sandbox')
         .exitOverride();
     for (const spec of COMMANDS) {
         const cmd = program.command(spec.name, { hidden: spec.hidden }).description(spec.summary).option('--config <file>', 'config file (default: ~/.agent-sandbox/config.json)');
@@ -101,11 +131,15 @@ export const parseCli = (argv, wrapper = false) => {
         follow: Boolean(o.follow),
         json: Boolean(o.json),
         yes: Boolean(o.yes),
+        all: Boolean(o.all),
+        sessions: (o.session ?? []).map((s) => parseSessionWant(s)),
         timeout: o.timeout ?? 600,
-        days: o.days ?? 7,
+        days: o.days ?? (name === 'audit' ? 1 : 7),
+        kind: o.kind,
+        grep: o.grep,
     };
 };
 const defaults = () => ({
     command: '', positionals: [], passthrough: [], scripts: [], databases: [], terminal: false, newSession: false, noAgent: false, trustConfig: false, noLocalConfig: false,
-    personal: false, fromHost: false, noRestart: false, follow: false, json: false, yes: false, timeout: 600, days: 7,
+    personal: false, fromHost: false, noRestart: false, follow: false, json: false, yes: false, all: false, sessions: [], timeout: 600, days: 7,
 });

package/dist/cli/colors.d.ts

@@ -0,0 +1,24 @@
+/** The colour policy as a pure function (tested); `isTTY` is that of the stream being written to. */
+export declare const colorEnabled: (env: NodeJS.ProcessEnv, isTTY: boolean) => boolean;
+export declare const c: {
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    red: (text: string) => string;
+    green: (text: string) => string;
+    yellow: (text: string) => string;
+    cyan: (text: string) => string;
+};
+/** Removes colour codes (for measuring or comparing text). */
+export declare const stripAnsi: (text: string) => string;
+/** Cuts `text` to `max` visible characters, ending in an ellipsis (plain text only). */
+export declare const shorten: (text: string, max: number) => string;
+/** Cuts the middle out of a long path or id so both ends stay readable. */
+export declare const shortenMiddle: (text: string, max: number) => string;
+/** 1536 -> "1.5 KB" is in the data command; this is "3 min ago" for the tables. */
+export declare const ago: (then: number | string | Date, now?: number) => string;
+/** Width to lay text out in (terminal columns, 80 when unknown, never absurdly small). */
+export declare const termWidth: () => number;
+/** Each menu page starts on a clean screen (answered prompts would otherwise pile up above it). */
+export declare const clearScreen: () => void;
+/** Rows of a list that fit the terminal (leaving room for the prompt and the help line). */
+export declare const pageSizeFor: (wanted: number) => number;

package/dist/cli/colors.js

@@ -0,0 +1,42 @@
+// ANSI colours for terminal output (one place, so menus, errors and warnings agree).
+// Colour is on only for a terminal that wants it: not with NO_COLOR, TERM=dumb or piped output; FORCE_COLOR turns it on.
+/** The colour policy as a pure function (tested); `isTTY` is that of the stream being written to. */
+export const colorEnabled = (env, isTTY) => {
+    if (env.NO_COLOR)
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '')
+        return env.FORCE_COLOR !== '0' && env.FORCE_COLOR !== 'false';
+    return isTTY && env.TERM !== 'dumb';
+};
+const paint = (code) => (text) => (colorEnabled(process.env, Boolean(process.stdout.isTTY)) ? '\x1b[' + code + 'm' + text + '\x1b[0m' : text);
+export const c = { bold: paint(1), dim: paint(2), red: paint(31), green: paint(32), yellow: paint(33), cyan: paint(36) };
+/** Removes colour codes (for measuring or comparing text). */
+export const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+/** Cuts `text` to `max` visible characters, ending in an ellipsis (plain text only). */
+export const shorten = (text, max) => (max < 2 || text.length <= max ? text : text.slice(0, max - 1) + '…');
+/** Cuts the middle out of a long path or id so both ends stay readable. */
+export const shortenMiddle = (text, max) => {
+    if (max < 5 || text.length <= max)
+        return text;
+    const keep = max - 1;
+    const head = Math.ceil(keep / 2);
+    return text.slice(0, head) + '…' + text.slice(text.length - (keep - head));
+};
+/** 1536 -> "1.5 KB" is in the data command; this is "3 min ago" for the tables. */
+export const ago = (then, now = Date.now()) => {
+    const secs = Math.max(0, Math.round((now - new Date(then).getTime()) / 1000));
+    if (secs < 45)
+        return 'just now';
+    if (secs < 3600)
+        return Math.round(secs / 60) + ' min ago';
+    if (secs < 86400)
+        return Math.round(secs / 3600) + ' h ago';
+    return Math.round(secs / 86400) + ' d ago';
+};
+/** Width to lay text out in (terminal columns, 80 when unknown, never absurdly small). */
+export const termWidth = () => Math.max(40, process.stdout.columns ?? 80);
+/** Each menu page starts on a clean screen (answered prompts would otherwise pile up above it). */
+export const clearScreen = () => { if (process.stdout.isTTY)
+    process.stdout.write('\x1b[2J\x1b[3J\x1b[H'); };
+/** Rows of a list that fit the terminal (leaving room for the prompt and the help line). */
+export const pageSizeFor = (wanted) => Math.max(5, Math.min(wanted, (process.stdout.rows ?? 30) - 6));

package/dist/cli/commands/accounts.js

@@ -3,7 +3,7 @@ import { activateAccount, listAccounts, removeAccount, saveAccount, setDefaultAc
 import { restartSessions, runningSessions } from '../../host/channel.js';
 import { hostClaudeDir, hostGlobalStateFile } from '../../host/claude-profile.js';
 import { isSandboxRunning } from '../../host/platform.js';
-import { fail } from '../../core/util.js';
+import { fail, safeText } from '../../core/util.js';
 import { printJson, sandboxAlive, table } from './context.js';
 const label = (a) => '"' + a.name + '"' + (a.email ? ' (' + a.email + ')' : '');
 /** This PC's Claude login location (config folder + global state file). */
@@ -27,7 +27,7 @@ const use = async (ctx, name) => {
     console.log('Sandbox now uses ' + label(activateAccount(ctx.storageRoot, ctx.dataPath, name)) + '.');
     const claudeRunning = isSandboxRunning() && runningSessions(ctx.dataPath).some((s) => s.harness === 'claude');
     if (claudeRunning && !ctx.options.noRestart)
-        console.log((await restartSessions(ctx.dataPath, 'claude', sandboxAlive)).message + ' with --continue; the conversation carries on under the new account.');
+        console.log(safeText((await restartSessions(ctx.dataPath, 'claude', sandboxAlive)).message) + ' with --continue; the conversation carries on under the new account.');
     return 0;
 };
 export const account = async (ctx) => {

package/dist/cli/commands/agent-commands.d.ts

@@ -0,0 +1,6 @@
+import type { Config } from '../../core/types.js';
+import { type Reconciled } from '../../host/agent-commands.js';
+import { type Context } from './context.js';
+/** Brings this PC in line with agentCommands and says what changed (used after on/off, settings and launch). */
+export declare const syncAgentCommands: (ctx: Context, config: Config, quiet?: boolean) => Reconciled | null;
+export declare const agentCommandsCommand: (ctx: Context) => number;

package/dist/cli/commands/agent-commands.js

@@ -0,0 +1,61 @@
+// `sandbox agent-commands [status|on|off]` (Beta): typing claude, codex ... on this PC starts them in a hidden sandbox.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig, userConfigPath } from '../../core/config.js';
+import { fail } from '../../core/util.js';
+import { agentCommands, commandsDir, reconcileAgentCommands } from '../../host/agent-commands.js';
+import { insideSandbox } from '../../host/platform.js';
+import { writeFileAtomic } from '../../shared/rundir.js';
+import { c } from '../colors.js';
+import { editConfigText } from '../menu/settings/config-file.js';
+import { table } from './context.js';
+const entryOf = (ctx) => path.join(ctx.packageRoot, 'dist', 'bin', 'sandbox.js');
+/** Brings this PC in line with agentCommands and says what changed (used after on/off, settings and launch). */
+export const syncAgentCommands = (ctx, config, quiet = false) => {
+    if (insideSandbox())
+        return null;
+    const result = reconcileAgentCommands(config, ctx.storageRoot, process.execPath, entryOf(ctx));
+    if (!result.changed || quiet)
+        return result;
+    if (result.on) {
+        console.log('Agent commands (Beta) are on for: ' + (result.commands.map((a) => a.command).join(', ') || 'no installed agents found'));
+        console.log(c.dim('Open a new terminal, then type e.g. claude in any project folder. Run the real one: set SANDBOX_AGENT_DIRECT=1'));
+    }
+    else
+        console.log('Agent commands are off: claude, codex ... run on this PC again (open a new terminal).');
+    return result;
+};
+export const agentCommandsCommand = (ctx) => {
+    if (insideSandbox())
+        fail('Agent commands change your PC\'s PATH, so they are set up from your PC, not inside the sandbox.', 'Run sandbox agent-commands on in a terminal on your PC.');
+    const action = ctx.options.positionals[0] ?? 'status';
+    if (action === 'status') {
+        const config = ctx.loaded.config;
+        const found = agentCommands(config, ctx.storageRoot);
+        console.log('Agent commands (Beta): ' + (config.agentCommands.enabled ? c.green('on') : 'off') + c.dim('  (' + commandsDir(ctx.storageRoot) + ')'));
+        if (found.length)
+            table(found.map((a) => [a.command, 'sandboxed ' + a.harness + (config.agentCommands.enabled ? '' : ' when on'), c.dim('real: ' + a.real)]));
+        else
+            console.log(c.dim('No agents found on this PC (claude, codex, gemini ... on your PATH).'));
+        if (!config.agentCommands.enabled)
+            console.log(c.dim('Turn on with: sandbox agent-commands on'));
+        return 0;
+    }
+    if (action !== 'on' && action !== 'off')
+        fail('Unknown action "' + action + '".', 'Use: sandbox agent-commands [status|on|off]');
+    const file = ctx.loaded.configPath ?? userConfigPath();
+    const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const edited = editConfigText(text, ['agentCommands', 'enabled'], action === 'on' ? true : undefined);
+    if ('problems' in edited)
+        fail('Could not change ' + file + ': ' + edited.problems.join('; '), 'Fix the file with sandbox config check, then try again.');
+    writeFileAtomic(file, edited.text);
+    const result = syncAgentCommands(ctx, loadConfig(file).config, true);
+    if (result?.on) {
+        console.log('Agent commands (Beta) are on: ' + (result.commands.map((a) => a.command).join(', ') || 'no installed agents found yet'));
+        console.log(c.dim('Open a new terminal, then type e.g. claude in a project folder: it starts in a hidden sandbox and attaches.'));
+        console.log(c.dim('Run the real one on this PC: set SANDBOX_AGENT_DIRECT=1 (PowerShell: $env:SANDBOX_AGENT_DIRECT=1). Turn off: sandbox agent-commands off'));
+    }
+    else
+        console.log('Agent commands are off: claude, codex ... run on this PC again. Open a new terminal.');
+    return 0;
+};

package/dist/cli/commands/context.d.ts

@@ -14,6 +14,8 @@ export declare const table: (rows: string[][]) => void;
 /** Prints `value` as JSON when --json was given; returns whether it did. */
 export declare const printJson: (ctx: Context, value: unknown) => boolean;
 export declare const sandboxAlive: () => boolean;
+/** For commands that control the sandbox from your PC: inside the sandbox they make no sense. */
+export declare const requireOnPc: (what: string) => void;
 export declare const requireRunning: (hint?: string) => void;
 /** Maps a folder on this PC to its path inside the running sandbox (only folders inside the mapped workspace exist there). */
 export declare const guestPathFor: (hostDir: string, workspaceHost: string, guestWorkspace: string) => string;

package/dist/cli/commands/context.js

@@ -36,11 +36,15 @@ export const table = (rows) => {
 };
 /** Prints `value` as JSON when --json was given; returns whether it did. */
 export const printJson = (ctx, value) => {
+    // JSON.stringify leaves C1 controls (U+0080-U+009F) as they are; text from the sandbox must not reach a terminal raw.
     if (ctx.options.json)
-        console.log(JSON.stringify(value, null, 2));
+        console.log(JSON.stringify(value, null, 2).replace(/[\u0080-\u009f]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0')));
     return ctx.options.json;
 };
 export const sandboxAlive = () => isSandboxRunning();
+/** For commands that control the sandbox from your PC: inside the sandbox they make no sense. */
+export const requireOnPc = (what) => { if (insideSandbox())
+    fail('You are inside the sandbox already, so "sandbox ' + what + '" has nothing to control.', 'Run it from a terminal on your PC.'); };
 export const requireRunning = (hint = '') => { if (!isSandboxRunning())
     fail('No Windows Sandbox is running.', hint || 'Start one with sandbox claude.'); };
 /** Maps a folder on this PC to its path inside the running sandbox (only folders inside the mapped workspace exist there). */

package/dist/cli/commands/data/clean.d.ts

@@ -0,0 +1,15 @@
+import { type Context } from '../context.js';
+export interface CleanTarget {
+    /** The target as normalised (forward slashes), e.g. "tools/go". */
+    target: string;
+    path: string;
+    /** Folder the target must stay inside, with no links between the two. */
+    root: string;
+    warning?: string;
+}
+/**
+ * Turns `sandbox data clean` arguments into folders. Pure (no disk access); throws a UserError for anything that is
+ * not a plain relative target inside the data folder: absolute paths, drive letters, `..`, wildcards, unknown areas.
+ */
+export declare const resolveCleanTargets: (inputs: string[], dataPath: string, storageRoot: string) => CleanTarget[];
+export declare const dataClean: (ctx: Context) => Promise<number>;