@agent-api/cli 0.1.2 → 0.2.1

package/dist/workbench/command-controller.js

@@ -99,6 +99,7 @@ export function createWorkbenchCommandController(options) {
                     contextEnabled: state.contextEnabled,
                     defaultPreset: state.defaultPreset,
                     renderMode: state.renderMode,
+                    shellIsolation: state.shellIsolation,
                 }),
             });
             return;
@@ -140,6 +141,53 @@ export function createWorkbenchCommandController(options) {
                 dispatch({ type: "activity.add", level: "error", text: "Default preset save failed" });
             }
         }
+        if (command.field === "isolation") {
+            if (!command.value) {
+                dispatch({
+                    type: "message.add",
+                    role: "system",
+                    text: options.settingsController.shellIsolationHelp(state.shellIsolation),
+                });
+                return;
+            }
+            try {
+                const settings = await options.settingsController.saveShellIsolationMode(command.value);
+                dispatch({ type: "settings.set", settings: { shellIsolation: settings.shellIsolation } });
+                dispatch({ type: "message.add", role: "system", text: settings.message });
+                dispatch({ type: "activity.add", level: "success", text: settings.activity });
+            }
+            catch (error) {
+                dispatch({ type: "message.add", role: "system", text: `Could not save shell isolation mode: ${userFacingError(error)}` });
+                dispatch({ type: "activity.add", level: "error", text: "Shell isolation save failed" });
+            }
+            return;
+        }
+        if (command.field === "isolator") {
+            if (!command.value) {
+                dispatch({
+                    type: "message.add",
+                    role: "system",
+                    text: options.settingsController.isolatorPathHelp(state.shellIsolation),
+                });
+                return;
+            }
+            try {
+                const [subcommand = "", ...rest] = command.value.split(/\s+/);
+                const value = rest.join(" ").trim();
+                const settings = subcommand === "source"
+                    ? await options.settingsController.saveIsolatorSource(value)
+                    : subcommand === "path"
+                        ? await options.settingsController.saveIsolatorPath(value)
+                        : await options.settingsController.saveIsolatorPath(command.value);
+                dispatch({ type: "settings.set", settings: { shellIsolation: settings.shellIsolation } });
+                dispatch({ type: "message.add", role: "system", text: settings.message });
+                dispatch({ type: "activity.add", level: "success", text: settings.activity });
+            }
+            catch (error) {
+                dispatch({ type: "message.add", role: "system", text: `Could not save isolator path: ${userFacingError(error)}` });
+                dispatch({ type: "activity.add", level: "error", text: "Isolator path save failed" });
+            }
+        }
     }
     async function runPresetCommand(value) {
         const state = options.engine.snapshot();

package/dist/workbench/isolator-installer.d.ts

@@ -0,0 +1,29 @@
+export interface IsolatorInstallConfig {
+    sourceURL?: string | null;
+    executablePath?: string | null;
+    sha256?: string | null;
+}
+export interface IsolatorInstallResult {
+    executablePath: string;
+    sourceURL: string;
+    bytes: number;
+    sha256: string;
+    replaced: boolean;
+}
+export interface IsolatorEnsureResult {
+    executablePath: string;
+    sourceURL: string;
+    sha256?: string | null;
+    repaired: boolean;
+}
+export interface IsolatorInstallOptions {
+    fetchImpl?: typeof fetch;
+    probeTimeoutMs?: number;
+}
+export declare function installConfiguredIsolator(config: IsolatorInstallConfig, options?: IsolatorInstallOptions): Promise<IsolatorInstallResult>;
+export declare function validateInstalledIsolator(executablePath: string, options?: Pick<IsolatorInstallOptions, "probeTimeoutMs">): Promise<string>;
+export declare function ensureConfiguredIsolator(config: IsolatorInstallConfig, options?: IsolatorInstallOptions): Promise<IsolatorEnsureResult>;
+export declare function relocateInstalledIsolator(fromPath: string, toPath: string, options?: Pick<IsolatorInstallOptions, "probeTimeoutMs">): Promise<string>;
+export declare function defaultIsolatorInstallPath(): string;
+export declare function normalizeSourceURL(value: string | null | undefined): string;
+export declare function normalizeInstallPath(value: string | null | undefined): string;

package/dist/workbench/isolator-installer.js

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { access, chmod, copyFile, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { runtime } from "../runtime/index.js";
+export async function installConfiguredIsolator(config, options = {}) {
+    const sourceURL = normalizeSourceURL(config.sourceURL);
+    const executablePath = normalizeInstallPath(config.executablePath);
+    const targetDir = path.dirname(executablePath);
+    const existing = await existingTargetState(executablePath);
+    await mkdir(targetDir, { recursive: true });
+    await ensureWritableDirectory(targetDir);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const response = await fetchImpl(sourceURL);
+    if (!response.ok) {
+        throw new Error(`isolator download failed: HTTP ${response.status}`);
+    }
+    const body = new Uint8Array(await response.arrayBuffer());
+    if (body.length === 0) {
+        throw new Error("isolator download failed: empty response body");
+    }
+    const actualSha256 = createHash("sha256").update(body).digest("hex");
+    const expectedSha256 = config.sha256?.trim().toLowerCase();
+    if (expectedSha256 && actualSha256 !== expectedSha256) {
+        throw new Error(`isolator checksum mismatch: expected ${expectedSha256}, got ${actualSha256}`);
+    }
+    const tempPath = path.join(targetDir, `.${path.basename(executablePath)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        await writeFile(tempPath, body, { mode: 0o700 });
+        if (process.platform !== "win32") {
+            await chmod(tempPath, 0o700);
+        }
+        await probeIsolator(tempPath, options.probeTimeoutMs ?? 10_000);
+        await rename(tempPath, executablePath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true });
+        throw error;
+    }
+    return {
+        executablePath,
+        sourceURL,
+        bytes: body.length,
+        sha256: actualSha256,
+        replaced: existing === "file",
+    };
+}
+export async function validateInstalledIsolator(executablePath, options = {}) {
+    const normalized = normalizeInstallPath(executablePath);
+    const state = await existingTargetState(normalized);
+    if (state !== "file") {
+        throw new Error(`isolator executable does not exist: ${normalized}`);
+    }
+    await probeIsolator(normalized, options.probeTimeoutMs ?? 10_000);
+    return normalized;
+}
+export async function ensureConfiguredIsolator(config, options = {}) {
+    const sourceURL = normalizeSourceURL(config.sourceURL);
+    const executablePath = normalizeInstallPath(config.executablePath);
+    try {
+        await validateInstalledIsolator(executablePath, options);
+        return {
+            executablePath,
+            sourceURL,
+            sha256: config.sha256,
+            repaired: false,
+        };
+    }
+    catch {
+        const result = await installConfiguredIsolator({ sourceURL, executablePath, sha256: config.sha256 }, options);
+        return {
+            executablePath: result.executablePath,
+            sourceURL: result.sourceURL,
+            sha256: result.sha256,
+            repaired: true,
+        };
+    }
+}
+export async function relocateInstalledIsolator(fromPath, toPath, options = {}) {
+    const source = await validateInstalledIsolator(fromPath, options);
+    const target = normalizeInstallPath(toPath);
+    if (source === target)
+        return target;
+    const targetDir = path.dirname(target);
+    await existingTargetState(target);
+    await mkdir(targetDir, { recursive: true });
+    await ensureWritableDirectory(targetDir);
+    const tempPath = path.join(targetDir, `.${path.basename(target)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        await copyFile(source, tempPath);
+        if (process.platform !== "win32") {
+            await chmod(tempPath, 0o700);
+        }
+        await probeIsolator(tempPath, options.probeTimeoutMs ?? 10_000);
+        await rename(tempPath, target);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true });
+        throw error;
+    }
+    return target;
+}
+export function defaultIsolatorInstallPath() {
+    return path.join(runtime.dirs.data, "bin", process.platform === "win32" ? "agent-isolator.exe" : "agent-isolator");
+}
+export function normalizeSourceURL(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        throw new Error("isolator sourceURL is required");
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new Error("isolator sourceURL must be a valid URL");
+    }
+    if (url.protocol !== "https:") {
+        throw new Error("isolator sourceURL must use https");
+    }
+    return url.toString();
+}
+export function normalizeInstallPath(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        throw new Error("isolator executablePath is required");
+    if (!path.isAbsolute(trimmed)) {
+        throw new Error("isolator executablePath must be absolute");
+    }
+    const normalized = path.normalize(trimmed);
+    const root = path.parse(normalized).root;
+    if (normalized === root) {
+        throw new Error("isolator executablePath cannot be a filesystem root");
+    }
+    if (path.basename(normalized).startsWith(".")) {
+        throw new Error("isolator executablePath must not be a hidden temp-style filename");
+    }
+    return normalized;
+}
+async function existingTargetState(file) {
+    try {
+        const info = await stat(file);
+        if (!info.isFile()) {
+            throw new Error(`isolator executablePath exists but is not a file: ${file}`);
+        }
+        return "file";
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return "missing";
+        throw error;
+    }
+}
+async function ensureWritableDirectory(dir) {
+    try {
+        await access(dir, fsConstants.W_OK);
+    }
+    catch {
+        throw new Error(`isolator target directory is not writable: ${dir}`);
+    }
+}
+async function probeIsolator(executablePath, timeoutMs) {
+    const request = JSON.stringify({ id: "status", method: "status", params: {} });
+    const child = spawn(executablePath, ["--once", "--driver=auto"], {
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    const chunks = [];
+    const errors = [];
+    child.stdout.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    child.stderr.on("data", (chunk) => errors.push(Buffer.from(chunk)));
+    child.stdin.end(`${request}\n`);
+    const code = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error("isolator probe timed out"));
+        }, timeoutMs);
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", (exitCode) => {
+            clearTimeout(timer);
+            resolve(exitCode);
+        });
+    });
+    const stdout = Buffer.concat(chunks).toString("utf8").trim();
+    const stderr = Buffer.concat(errors).toString("utf8").trim();
+    if (code !== 0) {
+        throw new Error(stderr || stdout || `isolator probe failed with exit code ${code}`);
+    }
+    const line = stdout.split(/\r?\n/).find(Boolean);
+    if (!line)
+        throw new Error("isolator probe returned no response");
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        throw new Error("isolator probe returned invalid JSON");
+    }
+    if (parsed?.error) {
+        throw new Error(parsed.error.message || parsed.error.code || "isolator probe failed");
+    }
+    if (!parsed?.result?.status?.driver) {
+        throw new Error("isolator probe response did not include shell isolation status");
+    }
+}

package/dist/workbench/local-controller.d.ts

@@ -1,5 +1,6 @@
 import { openWorkdir } from "../workdir/index.js";
 import type { WorkbenchState, WorkbenchWorkdirStatus } from "../tui/workbench.js";
+import type { ShellIsolationPreferences } from "./shell-isolation.js";
 export interface WorkbenchLocalController {
     load(path?: string): Promise<WorkbenchWorkdirStatus>;
     isLoaded(): boolean;
@@ -13,6 +14,7 @@ export interface WorkbenchLocalController {
 }
 export interface WorkbenchLocalControllerOptions {
     openWorkdirImpl?: typeof openWorkdir;
+    getShellIsolation?: () => ShellIsolationPreferences | undefined;
 }
 type LocalApprovalLike = NonNullable<WorkbenchState["pendingLocalTool"]>;
 export declare function createWorkbenchLocalController(options?: WorkbenchLocalControllerOptions): WorkbenchLocalController;

package/dist/workbench/local-controller.js

@@ -1,5 +1,6 @@
 import { createLocalShellToolRegistry, createLocalWorkdirToolRegistry } from "@agent-api/sdk/local";
 import { openWorkdir } from "../workdir/index.js";
+import { localShellIsolationOptions } from "./shell-isolation.js";
 export function createWorkbenchLocalController(options = {}) {
     const openWorkdirImpl = options.openWorkdirImpl ?? openWorkdir;
     let workdir = null;
@@ -54,7 +55,11 @@ export function createWorkbenchLocalController(options = {}) {
         async applyApproval(approval) {
             const current = requireWorkdir();
             const workdirRegistry = createLocalWorkdirToolRegistry(current.workdir, { accessMode: "full" });
-            const shellRegistry = createLocalShellToolRegistry({ workdir: current.workdir, accessMode: "full" });
+            const shellRegistry = createLocalShellToolRegistry({
+                workdir: current.workdir,
+                accessMode: "full",
+                ...localShellIsolationOptions(options.getShellIsolation?.()),
+            });
             if (approval.name === workdirRegistry.toolName) {
                 return await workdirRegistry.execute(approval.name, approval.arguments);
             }

package/dist/workbench/session.js

@@ -14,7 +14,9 @@ export function createWorkbenchSession(options) {
         model: options.baseOptions.model,
         preset: options.baseOptions.preset,
     });
-    const local = createWorkbenchLocalController();
+    const local = createWorkbenchLocalController({
+        getShellIsolation: () => engine.snapshot().shellIsolation,
+    });
     const runtime = createWorkbenchRuntimeController({ dispatch: engine.dispatch });
     const turn = createWorkbenchTurnController({
         baseOptions: options.baseOptions,

package/dist/workbench/settings-controller.d.ts

@@ -1,9 +1,15 @@
 import { clearPresetToolCatalogCache, isAvailablePreset, listAvailablePresets, type AgentRunOptions } from "../agent.js";
 import { loadWorkbenchPreferences, updateWorkbenchPreferences, type WorkbenchPreferences } from "../config.js";
 import type { RenderMode } from "../tui/workbench.js";
+import type { ShellIsolationMode, ShellIsolationPreferences } from "./shell-isolation.js";
+import { type IsolatorInstallOptions } from "./isolator-installer.js";
 export interface WorkbenchSettingsSnapshot {
     defaultPreset?: string | null;
     runPreset?: string;
+    shellIsolation?: ShellIsolationPreferences;
+    activity?: string;
+    notice?: string;
+    warning?: string;
 }
 export interface WorkbenchSettingsController {
     loadInitial(options: Pick<AgentRunOptions, "modelExplicit" | "preset" | "presetExplicit">): Promise<WorkbenchSettingsSnapshot>;
@@ -15,6 +21,18 @@ export interface WorkbenchSettingsController {
         message: string;
         activity: string;
     }>;
+    saveShellIsolationMode(value: string): Promise<WorkbenchSettingsSnapshot & {
+        message: string;
+        activity: string;
+    }>;
+    saveIsolatorPath(value: string): Promise<WorkbenchSettingsSnapshot & {
+        message: string;
+        activity: string;
+    }>;
+    saveIsolatorSource(value: string): Promise<WorkbenchSettingsSnapshot & {
+        message: string;
+        activity: string;
+    }>;
     validatePreset(profileName: string | undefined, preset: string): Promise<boolean>;
     presetListText(input: {
         profileName?: string;
@@ -29,8 +47,11 @@ export interface WorkbenchSettingsController {
         runModel?: string;
         runPreset?: string;
         renderMode: RenderMode;
+        shellIsolation?: ShellIsolationPreferences;
     }): string;
     defaultPresetHelp(defaultPreset?: string | null): string;
+    shellIsolationHelp(shellIsolation?: ShellIsolationPreferences): string;
+    isolatorPathHelp(shellIsolation?: ShellIsolationPreferences): string;
     clearPresetToolCatalogCache(baseURL?: string): void;
 }
 export interface WorkbenchSettingsControllerOptions {
@@ -39,6 +60,7 @@ export interface WorkbenchSettingsControllerOptions {
     isAvailablePresetImpl?: typeof isAvailablePreset;
     listAvailablePresetsImpl?: typeof listAvailablePresets;
     clearPresetToolCatalogCacheImpl?: typeof clearPresetToolCatalogCache;
+    isolatorInstallOptions?: IsolatorInstallOptions;
     formatError?: (error: unknown) => string;
 }
 export declare function createWorkbenchSettingsController(options?: WorkbenchSettingsControllerOptions): WorkbenchSettingsController;
@@ -48,5 +70,11 @@ export declare class UnknownPresetError extends Error {
 }
 export declare function normalizeDefaultPreset(value: string): string | null | undefined;
 export declare function formatDefaultPreset(value: string | null | undefined): string;
+export declare function normalizeShellIsolationMode(value: string): ShellIsolationMode;
+export declare function normalizeIsolatorPath(value: string): string | null;
+export declare function normalizeIsolatorSource(value: string): string | null;
+export declare function formatShellIsolation(value: ShellIsolationPreferences | undefined): ShellIsolationMode;
+export declare function formatIsolatorPath(value: ShellIsolationPreferences | undefined): string;
+export declare function formatIsolatorSource(value: ShellIsolationPreferences | undefined): string;
 export declare function effectiveDefaultPreset(preferences: WorkbenchPreferences, builtInPreset?: string): string | undefined;
 export declare function formatPresetList(presets: Awaited<ReturnType<typeof listAvailablePresets>>, currentPreset?: string): string[];

package/dist/workbench/settings-controller.js

@@ -1,22 +1,107 @@
 import { clearPresetToolCatalogCache, isAvailablePreset, listAvailablePresets, } from "../agent.js";
 import { loadWorkbenchPreferences, updateWorkbenchPreferences, } from "../config.js";
+import { ensureConfiguredIsolator, installConfiguredIsolator, normalizeSourceURL, relocateInstalledIsolator, validateInstalledIsolator, } from "./isolator-installer.js";
 export function createWorkbenchSettingsController(options = {}) {
     const loadWorkbenchPreferencesImpl = options.loadWorkbenchPreferencesImpl ?? loadWorkbenchPreferences;
     const updateWorkbenchPreferencesImpl = options.updateWorkbenchPreferencesImpl ?? updateWorkbenchPreferences;
     const isAvailablePresetImpl = options.isAvailablePresetImpl ?? isAvailablePreset;
     const listAvailablePresetsImpl = options.listAvailablePresetsImpl ?? listAvailablePresets;
     const clearPresetToolCatalogCacheImpl = options.clearPresetToolCatalogCacheImpl ?? clearPresetToolCatalogCache;
+    const isolatorInstallOptions = options.isolatorInstallOptions ?? {};
     const formatError = options.formatError ?? userFacingError;
     return {
         async loadInitial(agentOptions) {
-            const preferences = await loadWorkbenchPreferencesImpl();
+            const loadedPreferences = await loadWorkbenchPreferencesImpl();
+            const { preferences, activity, warning } = await reconcileConfiguredIsolator(loadedPreferences, updateWorkbenchPreferencesImpl, isolatorInstallOptions, formatError);
             return {
                 defaultPreset: preferences.defaultPreset,
+                ...(preferences.isolation ? { shellIsolation: preferences.isolation } : {}),
+                ...(activity ? { activity } : {}),
+                ...(isolatorSetupNotice(preferences.isolation) ? { notice: isolatorSetupNotice(preferences.isolation) } : {}),
+                ...(warning ? { warning } : {}),
                 runPreset: shouldApplyDefaultPreset(agentOptions)
                     ? effectiveDefaultPreset(preferences, agentOptions.preset)
                     : undefined,
             };
         },
+        async saveShellIsolationMode(value) {
+            const mode = normalizeShellIsolationMode(value);
+            const preferences = await updateWorkbenchPreferencesImpl({
+                isolation: {
+                    mode,
+                    installSkipped: mode === "none" ? true : false,
+                },
+            });
+            return {
+                ...settingsSnapshot(preferences),
+                message: `Saved shell isolation mode: ${formatShellIsolation(preferences.isolation)}.`,
+                activity: `Shell isolation mode saved: ${preferences.isolation?.mode ?? "auto"}`,
+            };
+        },
+        async saveIsolatorPath(value) {
+            const executablePath = normalizeIsolatorPath(value);
+            if (!executablePath) {
+                const preferences = await updateWorkbenchPreferencesImpl({ isolation: { executablePath } });
+                return {
+                    ...settingsSnapshot(preferences),
+                    message: `Saved isolator path: ${formatIsolatorPath(preferences.isolation)}.`,
+                    activity: "Isolator path cleared",
+                };
+            }
+            const current = (await loadWorkbenchPreferencesImpl()).isolation;
+            if (current?.sourceURL) {
+                const result = await installConfiguredIsolator({
+                    sourceURL: current.sourceURL,
+                    executablePath,
+                    sha256: current.sha256,
+                }, isolatorInstallOptions);
+                const preferences = await updateWorkbenchPreferencesImpl({
+                    isolation: { executablePath: result.executablePath, sourceURL: result.sourceURL, sha256: result.sha256, installSkipped: false },
+                });
+                return {
+                    ...settingsSnapshot(preferences),
+                    message: `Installed isolator to ${result.executablePath}.`,
+                    activity: result.replaced ? "Isolator refreshed" : "Isolator installed",
+                };
+            }
+            const validatedPath = current?.executablePath
+                ? await relocateInstalledIsolator(current.executablePath, executablePath, isolatorInstallOptions)
+                : await validateInstalledIsolator(executablePath, isolatorInstallOptions);
+            const preferences = await updateWorkbenchPreferencesImpl({ isolation: { executablePath: validatedPath, installSkipped: false } });
+            return {
+                ...settingsSnapshot(preferences),
+                message: `Saved verified isolator path: ${formatIsolatorPath(preferences.isolation)}.`,
+                activity: "Isolator path verified",
+            };
+        },
+        async saveIsolatorSource(value) {
+            const sourceURL = normalizeIsolatorSource(value);
+            const current = (await loadWorkbenchPreferencesImpl()).isolation;
+            if (!sourceURL) {
+                const preferences = await updateWorkbenchPreferencesImpl({ isolation: { sourceURL, sha256: null } });
+                return {
+                    ...settingsSnapshot(preferences),
+                    message: "Cleared isolator source URL.",
+                    activity: "Isolator source cleared",
+                };
+            }
+            if (!current?.executablePath) {
+                throw new Error("Set a verified isolator path before saving a source URL.");
+            }
+            const result = await installConfiguredIsolator({
+                sourceURL,
+                executablePath: current.executablePath,
+                sha256: current.sha256,
+            }, isolatorInstallOptions);
+            const preferences = await updateWorkbenchPreferencesImpl({
+                isolation: { sourceURL: result.sourceURL, executablePath: result.executablePath, sha256: result.sha256, installSkipped: false },
+            });
+            return {
+                ...settingsSnapshot(preferences),
+                message: `Installed isolator from ${result.sourceURL}.`,
+                activity: result.replaced ? "Isolator refreshed from source" : "Isolator installed from source",
+            };
+        },
         async saveDefaultPreset(input) {
             const normalized = normalizeDefaultPreset(input.value);
             if (typeof normalized === "string" && !(await isAvailablePresetImpl(input.profileName, normalized))) {
@@ -25,6 +110,7 @@ export function createWorkbenchSettingsController(options = {}) {
             const preferences = await updateWorkbenchPreferencesImpl({ defaultPreset: normalized });
             return {
                 defaultPreset: preferences.defaultPreset,
+                ...(preferences.isolation ? { shellIsolation: preferences.isolation } : {}),
                 runPreset: shouldApplyDefaultPreset(input.options)
                     ? effectiveDefaultPreset(preferences, input.options.preset)
                     : undefined,
@@ -57,6 +143,16 @@ export function createWorkbenchSettingsController(options = {}) {
         defaultPresetHelp(defaultPreset) {
             return `Default preset: ${formatDefaultPreset(defaultPreset)}. Use /config preset <name>, /config preset none, or /config preset reset.`;
         },
+        shellIsolationHelp(shellIsolation) {
+            return `Shell isolation: ${formatShellIsolation(shellIsolation)}. Use /config isolation none, /config isolation auto, or /config isolation required.`;
+        },
+        isolatorPathHelp(shellIsolation) {
+            return [
+                `Isolator path: ${formatIsolatorPath(shellIsolation)}`,
+                `Isolator source: ${formatIsolatorSource(shellIsolation)}`,
+                "Use /config isolator path <absolute-path>, /config isolator source <https-url>, or /config isolator none to clear the path.",
+            ].join("\n");
+        },
         clearPresetToolCatalogCache(baseURL) {
             clearPresetToolCatalogCacheImpl(baseURL);
         },
@@ -84,6 +180,49 @@ export function formatDefaultPreset(value) {
         return "built-in (pro-search)";
     return value ?? "none";
 }
+function settingsSnapshot(preferences) {
+    return {
+        ...("defaultPreset" in preferences ? { defaultPreset: preferences.defaultPreset } : {}),
+        ...(preferences.isolation ? { shellIsolation: preferences.isolation } : {}),
+    };
+}
+export function normalizeShellIsolationMode(value) {
+    const lowered = value.trim().toLowerCase();
+    if (lowered === "none" || lowered === "off" || lowered === "disable" || lowered === "disabled")
+        return "none";
+    if (lowered === "auto" || lowered === "default")
+        return "auto";
+    if (lowered === "required" || lowered === "require" || lowered === "strict")
+        return "required";
+    throw new Error("Unknown shell isolation mode. Use none, auto, or required.");
+}
+export function normalizeIsolatorPath(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error("Usage: /config isolator <path>, or /config isolator none.");
+    const lowered = trimmed.toLowerCase();
+    if (["none", "off", "disable", "disabled", "clear", "reset"].includes(lowered))
+        return null;
+    return trimmed;
+}
+export function normalizeIsolatorSource(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error("Usage: /config isolator source <https-url>, or /config isolator source none.");
+    const lowered = trimmed.toLowerCase();
+    if (["none", "off", "disable", "disabled", "clear", "reset"].includes(lowered))
+        return null;
+    return normalizeSourceURL(trimmed);
+}
+export function formatShellIsolation(value) {
+    return value?.mode ?? "auto";
+}
+export function formatIsolatorPath(value) {
+    return value?.executablePath || process.env.AGENT_ISOLATOR_PATH || "not configured";
+}
+export function formatIsolatorSource(value) {
+    return value?.sourceURL || "not configured";
+}
 export function effectiveDefaultPreset(preferences, builtInPreset) {
     if ("defaultPreset" in preferences)
         return preferences.defaultPreset ?? undefined;
@@ -101,13 +240,16 @@ export function formatPresetList(presets, currentPreset) {
 function shouldApplyDefaultPreset(options) {
     return !options.presetExplicit && !options.modelExplicit;
 }
-function runConfigText({ accessMode, contextEnabled, defaultPreset, profileName, runModel, runPreset, renderMode, }) {
+function runConfigText({ accessMode, contextEnabled, defaultPreset, profileName, runModel, runPreset, renderMode, shellIsolation, }) {
     return [
         `Profile: ${profileName}`,
         `Preset: ${runPreset || "none"}`,
         `Default preset: ${formatDefaultPreset(defaultPreset)}`,
         `Model: ${runModel || "auto"}`,
         `Render mode: ${renderMode}`,
+        `Shell isolation: ${formatShellIsolation(shellIsolation)}`,
+        `Isolator path: ${formatIsolatorPath(shellIsolation)}`,
+        `Isolator source: ${formatIsolatorSource(shellIsolation)}`,
         `local_workdir tool: ${contextEnabled ? "on" : "off"}`,
         `local_shell tool: ${contextEnabled ? "on" : "off"}`,
         `Local access: ${accessMode}`,
@@ -118,3 +260,50 @@ function userFacingError(error) {
         return error.message;
     return String(error);
 }
+function isolatorSetupNotice(shellIsolation) {
+    if (process.env.AGENT_ISOLATOR_PATH)
+        return "";
+    if (shellIsolation?.installSkipped || shellIsolation?.mode === "none" || shellIsolation?.executablePath)
+        return "";
+    return [
+        "Local shell isolation is not configured yet.",
+        "",
+        "To enable it, set a verified target path and downloadable source URL:",
+        "/config isolator path <absolute-path>",
+        "/config isolator source <https-url>",
+        "",
+        "To skip this setup for future starts, use /config isolation none.",
+    ].join("\n");
+}
+async function reconcileConfiguredIsolator(preferences, updatePreferences, installOptions, formatError) {
+    const isolation = preferences.isolation;
+    if (!isolation?.sourceURL || !isolation.executablePath)
+        return { preferences };
+    try {
+        const result = await ensureConfiguredIsolator({
+            sourceURL: isolation.sourceURL,
+            executablePath: isolation.executablePath,
+            sha256: isolation.sha256,
+        }, installOptions);
+        if (!result.repaired)
+            return { preferences };
+        const updated = await updatePreferences({
+            isolation: {
+                sourceURL: result.sourceURL,
+                executablePath: result.executablePath,
+                sha256: result.sha256,
+                installSkipped: false,
+            },
+        });
+        return {
+            preferences: updated,
+            activity: `Reinstalled isolator: ${result.executablePath}`,
+        };
+    }
+    catch (error) {
+        return {
+            preferences,
+            warning: `Configured isolator is unavailable: ${formatError(error)}`,
+        };
+    }
+}