@fungi.computer/truffle 0.2.2 → 0.3.0

package/dist/private-local-sandbox.d.ts

@@ -1,48 +1,53 @@
 import type { NativeSourceReader } from "./private-local-bwrap.js";
 import { z } from "zod";
+import { sandboxUnavailableReasonSchema, type SandboxUnavailableReason } from "./private-local-containment.js";
+import type { LocalPermissionMode } from "./private-local-permission-mode.js";
 import type { LocalSandboxWrites } from "./private-invocation-files.js";
-import { type NativeRunLivenessProbe } from "./private-local-sandbox-policy.js";
+import type { NativePayloadStaging } from "./private-local-native-staging.js";
 /** Availability is not a hostile-program security or an approval status. */
-export declare const sandboxStatusSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    state: z.ZodLiteral<"available">;
-    requireSandbox: z.ZodBoolean;
-}, z.core.$strict>, z.ZodObject<{
-    state: z.ZodLiteral<"unavailable">;
-    requireSandbox: z.ZodBoolean;
-    reason: z.ZodObject<{
+export declare const sandboxStatusSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        "read-only": "read-only";
+        workspace: "workspace";
+        "full-access": "full-access";
+    }>;
+    available: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodObject<{
         kind: z.ZodEnum<{
-            missing: "missing";
-            "missing-artifact": "missing-artifact";
-            "invalid-digest": "invalid-digest";
-            "digest-mismatch": "digest-mismatch";
-            unreadable: "unreadable";
-            "not-executable": "not-executable";
-            "staging-failed": "staging-failed";
-            "unsupported-platform": "unsupported-platform";
-            "invalid-folder": "invalid-folder";
-            "unsafe-native-payload": "unsafe-native-payload";
-            "unsafe-host-code": "unsafe-host-code";
+            install: "install";
+            unsupported: "unsupported";
+            folder: "folder";
             "startup-refused": "startup-refused";
-            "backend-refused": "backend-refused";
         }>;
         message: z.ZodString;
-    }, z.core.$strict>;
-}, z.core.$strict>], "state">;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export type LocalSandboxStatus = z.output<typeof sandboxStatusSchema>;
 export type LocalSandboxControls = LocalSandboxWrites & Readonly<{
     assertReady(): void;
+    assertModeReady(mode: LocalPermissionMode): void;
     status(): LocalSandboxStatus;
     close(): void;
 }>;
+/** Refusal before an Agent Files write can be staged or dispatched. */
+export declare class ProtectedLocalFilesPath extends Error {
+    readonly path: string;
+    readonly name = "ProtectedLocalFilesPath";
+    constructor(path: string);
+}
 /**
- * Native Local owns the live requirement; the adapter owns only preparation.
+ * Native Local owns the live mode; the adapter owns only preparation.
  * Every consumer calls this authority immediately before launching or writing.
  */
 export declare function createLocalSandboxControls(input: Readonly<{
     project: string;
     folder: string;
-    required(): boolean;
+    agentId?: string;
+    mode(): LocalPermissionMode;
+    defaultReason?: z.output<typeof sandboxUnavailableReasonSchema> | undefined;
     platform?: string;
     readNativePatchSource?: NativeSourceReader;
-    probeNativeRunLiveness?: NativeRunLivenessProbe;
+    native?: NativePayloadStaging | undefined;
 }>): LocalSandboxControls;
+/** Probe a fresh Agent before deciding its mode; never treat an unavailable backend as a sandboxed run. */
+export declare function probeLocalSandbox(project: string, folder: string, native?: NativePayloadStaging): SandboxUnavailableReason | undefined;

package/dist/private-local-sandbox.js

@@ -1,70 +1,130 @@
-import { isAbsolute, relative, resolve, sep } from "node:path";
-import { tmpdir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { rmSync } from "node:fs";
 import { createNativePayloadStaging } from "./private-local-native-staging.js";
 import { z } from "zod";
 import { establishLocalSandbox, LocalSandboxUnavailable, sandboxUnavailableReason, sandboxUnavailableReasonSchema, } from "./private-local-containment.js";
-import { protectedSandboxPaths, assertHostCodeOutsideAgent, UnsafeHostCode, resolveAgentFolder, sandboxPolicy, } from "./private-local-sandbox-policy.js";
+import { protectedSandboxPaths, assertHostCodeOutsideAgent, UnsafeHostCode, resolveAgentFolder, sandboxPolicy, agentSandboxTemporaryDirectory, } from "./private-local-sandbox-policy.js";
 /** Availability is not a hostile-program security or an approval status. */
-export const sandboxStatusSchema = z.discriminatedUnion("state", [
-    z.strictObject({
-        state: z.literal("available"),
-        requireSandbox: z.boolean(),
-    }),
-    z.strictObject({
-        state: z.literal("unavailable"),
-        requireSandbox: z.boolean(),
-        reason: sandboxUnavailableReasonSchema,
-    }),
-]);
+export const sandboxStatusSchema = z.strictObject({
+    mode: z.enum(["full-access", "workspace", "read-only"]),
+    available: z.boolean(),
+    reason: sandboxUnavailableReasonSchema.optional(),
+});
+/** Refusal before an Agent Files write can be staged or dispatched. */
+export class ProtectedLocalFilesPath extends Error {
+    path;
+    name = "ProtectedLocalFilesPath";
+    constructor(path) {
+        super(`Files write targets a protected Local path: ${path}`);
+        this.path = path;
+    }
+}
 function contains(root, path) {
     const within = relative(root, path);
     return (!isAbsolute(within) && within !== ".." && !within.startsWith(`..${sep}`));
 }
 /**
- * Native Local owns the live requirement; the adapter owns only preparation.
+ * Native Local owns the live mode; the adapter owns only preparation.
  * Every consumer calls this authority immediately before launching or writing.
  */
 export function createLocalSandboxControls(input) {
-    const required = input.required();
+    const mode = input.mode();
     const folder = resolveAgentFolder(input.project, input.folder);
+    // Before an Agent store exists, a probe has a disposable temporary owner,
+    // not a fabricated Local store identity.
+    const temporaryOwner = input.agentId ??
+        `probe-${String(process.pid)}-${process.hrtime.bigint().toString(36)}`;
     // The packed Node wrapper passes the paths it actually loaded. In source
     // runs this module is the executing host authority instead. Check before
-    // staging or probing, independent of the optional/required setting.
+    // staging or probing. Full access never calls this admission.
+    const assertHostCode = () => {
+        try {
+            const launcher = process.env.FUNGI_LAUNCHER;
+            const cli = launcher === undefined
+                ? fileURLToPath(import.meta.url)
+                : process.env.FUNGI_BUNDLED_CLI;
+            if (cli === undefined)
+                throw new UnsafeHostCode("Packed CLI entry was not provided by the launcher; reinstall Fungi outside the project.");
+            assertHostCodeOutsideAgent(input.project, cli, launcher ?? cli);
+        }
+        catch (cause) {
+            throw new LocalSandboxUnavailable(cause instanceof UnsafeHostCode
+                ? sandboxUnavailableReason(cause)
+                : {
+                    kind: "install",
+                    message: `Fungi host JavaScript identity cannot be verified (${cause instanceof Error ? cause.message : String(cause)}); reinstall Fungi using a copying install outside the project.`,
+                });
+        }
+    };
+    if (mode !== "full-access")
+        assertHostCode();
+    let hostCodeAdmitted = mode !== "full-access";
+    let temporaryDirectory = mode === "full-access"
+        ? undefined
+        : agentSandboxTemporaryDirectory(temporaryOwner, input.project);
+    const platform = input.platform === undefined ? {} : { platform: input.platform };
+    const supportedPlatform = (input.platform ?? process.platform) === "linux" ||
+        (input.platform ?? process.platform) === "darwin";
+    const ownNative = () => {
+        try {
+            return createNativePayloadStaging(input.project, input.readNativePatchSource);
+        }
+        catch (cause) {
+            throw new LocalSandboxUnavailable(sandboxUnavailableReason(cause));
+        }
+    };
+    const admitNative = (staging) => {
+        try {
+            staging?.admitProject(input.project);
+        }
+        catch (cause) {
+            throw new LocalSandboxUnavailable(sandboxUnavailableReason(cause));
+        }
+    };
+    let native;
+    let nativeAdmitted = false;
+    let initial;
     try {
-        const launcher = process.env.FUNGI_LAUNCHER;
-        const cli = launcher === undefined
-            ? fileURLToPath(import.meta.url)
-            : process.env.FUNGI_BUNDLED_CLI;
-        if (cli === undefined)
-            throw new UnsafeHostCode("Packed CLI entry was not provided by the launcher; reinstall Fungi outside the project.");
-        assertHostCodeOutsideAgent(input.project, cli, launcher ?? cli);
+        if (mode !== "full-access") {
+            native = supportedPlatform ? (input.native ?? ownNative()) : undefined;
+            admitNative(native);
+            nativeAdmitted = native !== undefined;
+            initial = establishLocalSandbox({
+                project: input.project,
+                folder: folder.absolute,
+                mode,
+                temporaryDirectory: temporaryDirectory ??
+                    agentSandboxTemporaryDirectory(temporaryOwner, input.project),
+                ...platform,
+            }, native);
+        }
     }
     catch (cause) {
-        throw new LocalSandboxUnavailable(cause instanceof UnsafeHostCode
-            ? sandboxUnavailableReason(cause)
-            : {
-                kind: "unsafe-host-code",
-                message: `Fungi host JavaScript identity cannot be verified (${cause instanceof Error ? cause.message : String(cause)}); reinstall Fungi using a copying install outside the project.`,
-            });
+        try {
+            if (input.native === undefined)
+                native?.close();
+        }
+        finally {
+            if (temporaryDirectory !== undefined)
+                rmSync(temporaryDirectory, { recursive: true, force: true });
+        }
+        throw cause;
     }
-    const platform = input.platform === undefined ? {} : { platform: input.platform };
-    const native = createNativePayloadStaging(input.project, input.readNativePatchSource, input.probeNativeRunLiveness);
-    const initial = establishLocalSandbox({
-        project: input.project,
-        folder: folder.absolute,
-        ...platform,
-    }, native);
-    let sandbox = initial.state === "ready" ? initial.sandbox : undefined;
-    let everReady = initial.state === "ready";
-    let unavailable = initial.state === "unavailable" ? initial.reason : undefined;
+    let sandbox = initial?.state === "ready" ? initial.sandbox : undefined;
+    let preparedMode = sandbox === undefined ? undefined : mode;
+    let unavailable = initial?.state === "unavailable" ? initial.reason : input.defaultReason;
     if (unavailable !== undefined) {
-        if (unavailable.kind === "invalid-folder") {
-            native.close();
+        if (temporaryDirectory !== undefined)
+            rmSync(temporaryDirectory, { recursive: true, force: true });
+        if (unavailable.kind === "folder") {
+            if (input.native === undefined)
+                native?.close();
             throw new Error(unavailable.message);
         }
-        if (required) {
-            native.close();
+        if (mode !== "full-access") {
+            if (input.native === undefined)
+                native?.close();
             throw new LocalSandboxUnavailable(unavailable);
         }
     }
@@ -79,30 +139,50 @@ export function createLocalSandboxControls(input) {
             throw new Error("Local Agent folder authority changed while open");
         }
         catch (cause) {
-            if (!everReady)
-                throw cause;
             unavailable = {
-                kind: "invalid-folder",
+                kind: "folder",
                 message: cause instanceof Error ? cause.message : String(cause),
             };
             throw new LocalSandboxUnavailable(unavailable);
         }
     };
+    function prepareSandbox(nextMode) {
+        if (sandbox !== undefined && preparedMode === nextMode)
+            return;
+        sandbox?.close();
+        sandbox = undefined;
+        if (!hostCodeAdmitted) {
+            assertHostCode();
+            hostCodeAdmitted = true;
+        }
+        native ??= input.native ?? ownNative();
+        if (!nativeAdmitted) {
+            admitNative(native);
+            nativeAdmitted = true;
+        }
+        temporaryDirectory ??= agentSandboxTemporaryDirectory(temporaryOwner, input.project);
+        const admission = establishLocalSandbox({
+            project: input.project,
+            folder: folder.absolute,
+            mode: nextMode,
+            temporaryDirectory,
+            ...platform,
+        }, native);
+        if (admission.state === "ready") {
+            sandbox = admission.sandbox;
+            preparedMode = nextMode;
+            unavailable = undefined;
+        }
+        else {
+            unavailable = admission.reason;
+            throw new LocalSandboxUnavailable(unavailable);
+        }
+    }
     function launch(cwd, argv, readOnlyHelperFile) {
         assertFolder();
-        if (sandbox === undefined) {
-            const admission = establishLocalSandbox({
-                project: input.project,
-                folder: folder.absolute,
-                ...platform,
-            }, native);
-            if (admission.state === "ready") {
-                sandbox = admission.sandbox;
-                everReady = true;
-            }
-            else
-                unavailable = admission.reason;
-        }
+        if (input.mode() === "full-access")
+            return undefined;
+        prepareSandbox(input.mode() === "read-only" ? "read-only" : "workspace");
         if (sandbox !== undefined) {
             try {
                 const command = sandbox.command(cwd, argv, readOnlyHelperFile);
@@ -119,60 +199,49 @@ export function createLocalSandboxControls(input) {
         }
         if (unavailable === undefined)
             throw new Error("Local sandbox preparation produced no result");
-        if (unavailable.kind === "invalid-folder" && !everReady)
+        if (unavailable.kind === "folder")
             throw new Error(unavailable.message);
-        // A formerly ready sandbox never becomes optional bare execution.
-        // Before readiness, only availability failures permit fallback.
-        if (everReady ||
-            (unavailable.kind !== "missing" &&
-                unavailable.kind !== "unsupported-platform" &&
-                unavailable.kind !== "startup-refused"))
-            throw new LocalSandboxUnavailable(unavailable);
-        if (input.required())
-            throw new LocalSandboxUnavailable(unavailable);
-        // Files is never handed back its installed executable for a bare retry.
-        if (readOnlyHelperFile !== undefined) {
-            try {
-                return {
-                    bareNative: true,
-                    executable: native.patch(readOnlyHelperFile),
-                    args: [],
-                    environment: { TMPDIR: process.env.TMPDIR ?? tmpdir() },
-                };
-            }
-            catch (cause) {
-                unavailable = sandboxUnavailableReason(cause);
-                throw new LocalSandboxUnavailable(unavailable);
-            }
-        }
-        // No executable has started. Generic exec retains its ordinary fallback.
-        return undefined;
+        throw new LocalSandboxUnavailable(unavailable);
     }
     const assertReady = () => {
+        if (input.mode() === "full-access")
+            return;
         launch(folder.absolute, ["/usr/bin/true"]);
     };
     return {
         launch,
         assertReady,
-        assertWrite: (path) => {
+        assertModeReady: (nextMode) => {
+            if (nextMode === "full-access")
+                return;
+            assertFolder();
+            prepareSandbox(nextMode);
+            if (sandbox === undefined)
+                throw new Error("Local sandbox preparation produced no result");
+            sandbox.command(folder.absolute, ["/usr/bin/true"]);
+        },
+        assertWrite: (paths) => {
+            if (input.mode() === "full-access")
+                return;
             assertReady();
-            const target = resolve(path);
             const policy = sandboxPolicy(input.project, folder.absolute);
-            if (!contains(policy.writableRoot, target) ||
-                protectedSandboxPaths(policy.readOnly).some((protectedPath) => contains(protectedPath, target)) ||
-                protectedSandboxPaths(policy.immovable).includes(target))
-                throw new Error("Files write targets a protected Local path");
+            const protectedPaths = protectedSandboxPaths([
+                ...policy.readOnly,
+                join(policy.writableRoot, ".git"),
+            ]);
+            for (const path of paths) {
+                const target = resolve(path);
+                if (!contains(policy.writableRoot, target) ||
+                    protectedPaths.some((protectedPath) => contains(protectedPath, target)))
+                    throw new ProtectedLocalFilesPath(target);
+            }
         },
         status: () => {
             if (closed)
                 throw new Error("Local sandbox owner is closed");
             return unavailable === undefined
-                ? { state: "available", requireSandbox: input.required() }
-                : {
-                    state: "unavailable",
-                    requireSandbox: input.required(),
-                    reason: unavailable,
-                };
+                ? { mode: input.mode(), available: true }
+                : { mode: input.mode(), available: false, reason: unavailable };
         },
         close: () => {
             if (closed)
@@ -182,8 +251,29 @@ export function createLocalSandboxControls(input) {
                 sandbox?.close();
             }
             finally {
-                native.close();
+                if (input.native === undefined)
+                    native?.close();
+                if (temporaryDirectory !== undefined)
+                    rmSync(temporaryDirectory, { recursive: true });
             }
         },
     };
 }
+/** Probe a fresh Agent before deciding its mode; never treat an unavailable backend as a sandboxed run. */
+export function probeLocalSandbox(project, folder, native) {
+    try {
+        const controls = createLocalSandboxControls({
+            project,
+            folder,
+            mode: () => "workspace",
+            native,
+        });
+        controls.close();
+        return undefined;
+    }
+    catch (cause) {
+        if (cause instanceof LocalSandboxUnavailable)
+            return cause.reason;
+        throw cause;
+    }
+}

package/dist/private-local-seatbelt.d.ts

@@ -1,11 +1,12 @@
-import { type LocalSandboxPolicy } from "./private-local-sandbox-policy.js";
+import { type LinuxSandboxProfile } from "./private-local-sandbox-policy.js";
+export declare class UnsafeSeatbeltFolder extends Error {
+    readonly name = "UnsafeSeatbeltFolder";
+}
 /**
- * The containment owner supplies temporary-directory lifetime and command-time
- * protected paths; this adapter owns only the maintained Seatbelt translation.
+ * Containment supplies the single command-time profile (including HOME-based
+ * hidden paths). macOS intentionally grants neither Linux caches nor ssh-agent.
  */
-export type SeatbeltPolicy = LocalSandboxPolicy & Readonly<{
-    temporaryDirectory: string;
-}>;
+export type SeatbeltPolicy = Pick<LinuxSandboxProfile, "mode" | "writableRoot" | "readOnly" | "hidden" | "temporaryDirectory" | "fungiCache">;
 /**
  * Paths are argv definitions, never SBPL source. Both the logical name and its
  * resolved target are protected, including when a protected entry is a symlink.
@@ -15,10 +16,3 @@ export declare function seatbeltCommand(policy: SeatbeltPolicy, argv: readonly [
     args: string[];
     temporaryDirectory: string;
 };
-/** A real startup probe; failure is data, never permission to execute bare. */
-export declare function seatbeltReadiness(policy: SeatbeltPolicy): Readonly<{
-    ready: true;
-}> | Readonly<{
-    ready: false;
-    reason: string;
-}>;

package/dist/private-local-seatbelt.js

@@ -1,36 +1,75 @@
-import { spawnSync } from "node:child_process";
 import { readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, sep } from "node:path";
 import { protectedSandboxPaths, } from "./private-local-sandbox-policy.js";
 const sandboxExecutable = "/usr/bin/sandbox-exec";
+export class UnsafeSeatbeltFolder extends Error {
+    name = "UnsafeSeatbeltFolder";
+}
+function covers(root, path) {
+    const remainder = relative(root, path);
+    return (!isAbsolute(remainder) &&
+        remainder !== ".." &&
+        !remainder.startsWith(`..${sep}`));
+}
 /**
  * Paths are argv definitions, never SBPL source. Both the logical name and its
  * resolved target are protected, including when a protected entry is a symlink.
  */
 export function seatbeltCommand(policy, argv) {
+    const hidden = protectedSandboxPaths(policy.hidden);
+    const roots = policy.mode === "workspace"
+        ? [policy.writableRoot, policy.temporaryDirectory]
+        : [policy.temporaryDirectory];
+    // Denying writes on the hidden directory alone cannot prevent renaming its
+    // parent into a writable root, then reading its credentials at the new path.
+    if (roots.some((root) => hidden.some((path) => covers(root, dirname(path)) || covers(path, root))))
+        throw new UnsafeSeatbeltFolder("Seatbelt writable folder or temp contains a Fungi hidden record or its parent.");
     const definitions = [];
     const parameter = (name, path) => {
         definitions.push("-D", `${name}=${path}`);
         return `(param "${name}")`;
     };
-    const excluded = protectedSandboxPaths(policy.readOnly);
-    const carveouts = excluded.flatMap((path, index) => {
-        const value = parameter(`PROTECTED_${String(index)}`, path);
+    const hiddenRules = hidden.flatMap((path, index) => {
+        const value = parameter(`HIDDEN_${String(index)}`, path);
+        return [
+            `(deny file-read* (literal ${value}))`,
+            `(deny file-read* (subpath ${value}))`,
+        ];
+    });
+    const hiddenWriteRules = hidden.flatMap((_, index) => {
+        const value = `(param "HIDDEN_${String(index)}")`;
         return [
-            `(require-not (literal ${value}))`,
-            `(require-not (subpath ${value}))`,
+            `(deny file-write* (literal ${value}))`,
+            `(deny file-write* (subpath ${value}))`,
         ];
     });
-    const roots = [policy.writableRoot, policy.temporaryDirectory];
+    const excluded = protectedSandboxPaths(policy.readOnly);
+    const carveouts = excluded.map((path, index) => {
+        const value = parameter(`PROTECTED_${String(index)}`, path);
+        return {
+            path,
+            rules: [
+                `(require-not (literal ${value}))`,
+                `(require-not (subpath ${value}))`,
+            ],
+        };
+    });
+    const ownTemp = realpathSync(policy.temporaryDirectory);
+    // Workspace's cache carve-out protects native receipts under a writable
+    // cache parent. It must not cancel the narrower grant for our own temp.
+    const cachePaths = policy.fungiCache !== undefined && covers(policy.fungiCache, ownTemp)
+        ? new Set(protectedSandboxPaths([policy.fungiCache]))
+        : undefined;
     const grants = roots.map((path, index) => {
         const value = parameter(`WRITABLE_ROOT_${String(index)}`, realpathSync(path));
-        return `(require-all (subpath ${value}) ${carveouts.join(" ")})`;
+        const protectedRules = carveouts
+            .filter(({ path }) => !(policy.mode === "workspace" &&
+            index === 1 &&
+            cachePaths?.has(path)))
+            .flatMap(({ rules }) => rules);
+        return `(require-all (subpath ${value}) ${protectedRules.join(" ")})`;
     });
-    const anchors = [
-        ...new Set([
-            ...roots.map((path) => realpathSync(path)),
-            ...protectedSandboxPaths(policy.immovable),
-        ]),
-    ].map((path, index) => {
+    const anchors = [...new Set(roots.map((path) => realpathSync(path)))].map((path, index) => {
         const value = parameter(`ANCHOR_${String(index)}`, path);
         return `(deny file-write-unlink (require-all (vnode-type DIRECTORY) (literal ${value})))`;
     });
@@ -38,7 +77,9 @@ export function seatbeltCommand(policy, argv) {
     const profile = [
         base,
         "(allow file-read*)",
+        ...hiddenRules,
         `(allow file-write* ${grants.join(" ")})`,
+        ...hiddenWriteRules,
         ...anchors,
         "(deny system-fcntl (fcntl-command 80 110))",
     ].join("\n");
@@ -48,21 +89,3 @@ export function seatbeltCommand(policy, argv) {
         temporaryDirectory: realpathSync(policy.temporaryDirectory),
     };
 }
-/** A real startup probe; failure is data, never permission to execute bare. */
-export function seatbeltReadiness(policy) {
-    const command = seatbeltCommand(policy, ["/usr/bin/true"]);
-    const result = spawnSync(command.executable, command.args, {
-        env: { TMPDIR: command.temporaryDirectory },
-        encoding: "utf8",
-        timeout: 5_000,
-    });
-    const diagnostic = result.error?.message ?? result.stderr.trim();
-    return result.status === 0
-        ? { ready: true }
-        : {
-            ready: false,
-            reason: diagnostic.length > 0
-                ? diagnostic
-                : `sandbox-exec exited ${String(result.status)} (${String(result.signal)})`,
-        };
-}

package/dist/private-local-service-contract.d.ts

@@ -8,6 +8,7 @@ import type { PrivateLocalEffectiveModel } from "./private-local-effective-model
 import type { StopAllResult } from "./private-local-stop-all.js";
 import type { ServiceDiagnosticsStatus } from "./private-local-service-log.js";
 import type { LocalSandboxStatus } from "./private-local-sandbox.js";
+import type { LocalPermissionMode } from "./private-local-permission-mode.js";
 import type { LocalUiAttachmentLifetime } from "./private-local-ui-attachment.js";
 /** Live health, not the on-disk identity record or a cached connection snapshot. */
 export type PrivateLocalServiceStatus = Readonly<{
@@ -36,8 +37,8 @@ export type PrivateLocalServiceSelection = Readonly<{
     /** TUI/form watches own their attachment; ACP retains it until connection close. */
     uiAttachmentLifetime?: LocalUiAttachmentLifetime | undefined;
     clientPath?: string | undefined;
-    /** Person-selected sandbox requirement, not an approval setting. */
-    requireSandbox?: boolean | undefined;
+    /** Person-selected Agent mode, not an approval setting. */
+    mode?: LocalPermissionMode | undefined;
     databasePath?: string | undefined;
     sessionId?: string | undefined;
     fungiMcp?: PrivateFungiMcpSelection | undefined;
@@ -46,7 +47,7 @@ export type PrivateLocalSessionCreation = Readonly<{
     invocationRoot: string;
     uiAttachmentLifetime?: LocalUiAttachmentLifetime | undefined;
     clientPath?: string | undefined;
-    requireSandbox?: boolean | undefined;
+    mode?: LocalPermissionMode | undefined;
     databasePath: string;
     requestId: string;
     fungiMcp?: PrivateFungiMcpSelection | undefined;
@@ -111,7 +112,7 @@ export type PrivateLocalSessionChoice = Readonly<{
     /** Reopen this saved store through the persistent service connection. */
     resume: (options?: PrivateLocalServiceRequestOptions & {
         fungiMcp?: PrivateFungiMcpSelection | undefined;
-        requireSandbox?: boolean | undefined;
+        mode?: LocalPermissionMode | undefined;
     }) => Promise<PrivateLocalServiceConnection>;
 }>;
 export type PrivateLocalSessionProblem = Readonly<{