@fungi.computer/truffle 0.2.2 → 0.3.1

package/dist/private-files-patch.js

@@ -1,24 +1,10 @@
 import { access, constants } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import { createRequire } from "node:module";
 import process from "node:process";
 import * as ChildProcess from "effect/process/ChildProcess";
 import { parsePatch } from "diff";
 import * as Stream from "effect/Stream";
 import { runPrivateInvocationProcess, } from "./private-invocation-computer.js";
-import { createNativePayloadStaging } from "./private-local-native-staging.js";
-function patchExecutable() {
-    if (process.env.FUNGI_BUNDLED_CLI) {
-        const name = `@fungi.computer/spore-native-${process.platform}-${process.arch}`;
-        try {
-            return createRequire(process.env.FUNGI_BUNDLED_CLI).resolve(`${name}/bin/fungi-apply-patch`);
-        }
-        catch (cause) {
-            throw new Error(`Missing ${name}; reinstall Fungi with npm optional dependencies enabled`, { cause });
-        }
-    }
-    return fileURLToPath(new URL("../native/bin/fungi-apply-patch", import.meta.url));
-}
+import { createNativePayloadStaging, packagedPatchPath, } from "./private-local-native-staging.js";
 const maximumPatchBytes = 128 * 1024;
 const mismatchExitCode = 23;
 const formatExitCode = 24;
@@ -50,7 +36,7 @@ async function unifiedDiffContext(patch, read, context) {
 }
 /** Advertise only a packaged native engine; never install tools during a model call. */
 export async function createPrivateFilesPatch(root, read, sandbox) {
-    const executable = patchExecutable();
+    const executable = packagedPatchPath();
     try {
         // Advertise the installed helper if present; only the verified private
         // copy is executed, so its source does not need an execute bit.
@@ -78,7 +64,7 @@ export async function createPrivateFilesPatch(root, read, sandbox) {
             if (executableToRun === undefined)
                 throw new Error("Native Files helper was not staged");
             const env = { ...process.env, ...launch?.environment };
-            if (launch !== undefined && !("bareNative" in launch)) {
+            if (launch !== undefined) {
                 delete env.XDG_RUNTIME_DIR;
                 delete env.DBUS_SESSION_BUS_ADDRESS;
             }

package/dist/private-invocation-computer.d.ts

@@ -1,17 +1,72 @@
 import * as ChildProcess from "effect/process/ChildProcess";
 import type { KnapsackComputer } from "@fungi.computer/knapsack";
+import { type InvocationContext } from "@fungi.computer/mycelium";
 import { z } from "zod";
-import { type PrivateLocalProcessScope } from "./private-local-computer-processes.js";
+import { backgroundExecInput, backgroundExecOutput, type PrivateLocalProcessScope } from "./private-local-computer-processes.js";
 import type { SandboxCommand } from "./private-local-containment.js";
-/** A bare fallback for the native Files engine still names only staged bytes. */
-export type BareNativeCommand = SandboxCommand & Readonly<{
-    bareNative: true;
-}>;
-/** Only Files supplies a helper; generic exec can still fall back to its argv. */
-export type LocalSandboxLaunch = {
-    (cwd: string, argv: readonly [string, ...string[]]): SandboxCommand | undefined;
-    (cwd: string, argv: readonly [string, ...string[]], readOnlyHelperFile: string): SandboxCommand | BareNativeCommand;
-};
+import type { LocalPermissionMode } from "./private-local-permission-mode.js";
+import type { PendingApproval, ApprovalRefusal } from "@fungi.computer/approvals";
+/** A Full-access launch is bare; sandboxed launches always supply a command or refuse. */
+export type LocalSandboxLaunch = (cwd: string, argv: readonly [string, ...string[]], readOnlyHelperFile?: string) => SandboxCommand | undefined;
+/**
+ * `command` (shell) and `executable`/`args` (direct) are mutually exclusive:
+ * each branch is a strict object, so supplying both or neither fails every
+ * branch and the union is refused.
+ */
+declare const execInput: z.ZodUnion<readonly [z.ZodObject<{
+    command: z.ZodString;
+    stdin: z.ZodOptional<z.ZodString>;
+    operation: z.ZodDefault<z.ZodLiteral<"run">>;
+    escape: z.ZodOptional<z.ZodObject<{
+        justification: z.ZodString;
+    }, z.core.$strict>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    executable: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    stdin: z.ZodOptional<z.ZodString>;
+    operation: z.ZodDefault<z.ZodLiteral<"run">>;
+    escape: z.ZodOptional<z.ZodObject<{
+        justification: z.ZodString;
+    }, z.core.$strict>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>]>;
+declare const completedOutput: z.ZodObject<{
+    exitCode: z.ZodNumber;
+    stdout: z.ZodString;
+    stderr: z.ZodString;
+    truncated: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodObject<{
+        stream: z.ZodEnum<{
+            stdout: "stdout";
+            stderr: "stderr";
+        }>;
+        keptBytes: z.ZodNumber;
+        totalBytes: z.ZodNumber;
+    }, z.core.$strict>>]>;
+    status: z.ZodEnum<{
+        failed: "failed";
+        completed: "completed";
+    }>;
+}, z.core.$strict>;
+declare const deadlineOutput: z.ZodObject<{
+    exitCode: z.ZodNumber;
+    stdout: z.ZodString;
+    stderr: z.ZodString;
+    truncated: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodObject<{
+        stream: z.ZodEnum<{
+            stdout: "stdout";
+            stderr: "stderr";
+        }>;
+        keptBytes: z.ZodNumber;
+        totalBytes: z.ZodNumber;
+    }, z.core.$strict>>]>;
+    status: z.ZodLiteral<"deadline_exceeded">;
+    timeoutMs: z.ZodNumber;
+    elapsedMs: z.ZodNumber;
+    message: z.ZodString;
+}, z.core.$strict>;
 declare const execOutput: z.ZodDiscriminatedUnion<[z.ZodObject<{
     exitCode: z.ZodNumber;
     stdout: z.ZodString;
@@ -28,6 +83,15 @@ declare const execOutput: z.ZodDiscriminatedUnion<[z.ZodObject<{
         failed: "failed";
         completed: "completed";
     }>;
+    sandbox: z.ZodObject<{
+        mode: z.ZodEnum<{
+            "read-only": "read-only";
+            workspace: "workspace";
+            "full-access": "full-access";
+        }>;
+        likelyDenied: z.ZodBoolean;
+        ranOutsideSandbox: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     exitCode: z.ZodNumber;
     stdout: z.ZodString;
@@ -44,15 +108,161 @@ declare const execOutput: z.ZodDiscriminatedUnion<[z.ZodObject<{
     timeoutMs: z.ZodNumber;
     elapsedMs: z.ZodNumber;
     message: z.ZodString;
+    sandbox: z.ZodObject<{
+        mode: z.ZodEnum<{
+            "read-only": "read-only";
+            workspace: "workspace";
+            "full-access": "full-access";
+        }>;
+        likelyDenied: z.ZodBoolean;
+        ranOutsideSandbox: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
 }, z.core.$strict>], "status">;
+export declare const shellOutput: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    exitCode: z.ZodNumber;
+    stdout: z.ZodString;
+    stderr: z.ZodString;
+    truncated: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodObject<{
+        stream: z.ZodEnum<{
+            stdout: "stdout";
+            stderr: "stderr";
+        }>;
+        keptBytes: z.ZodNumber;
+        totalBytes: z.ZodNumber;
+    }, z.core.$strict>>]>;
+    status: z.ZodEnum<{
+        failed: "failed";
+        completed: "completed";
+    }>;
+    sandbox: z.ZodObject<{
+        mode: z.ZodEnum<{
+            "read-only": "read-only";
+            workspace: "workspace";
+            "full-access": "full-access";
+        }>;
+        likelyDenied: z.ZodBoolean;
+        ranOutsideSandbox: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    exitCode: z.ZodNumber;
+    stdout: z.ZodString;
+    stderr: z.ZodString;
+    truncated: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodObject<{
+        stream: z.ZodEnum<{
+            stdout: "stdout";
+            stderr: "stderr";
+        }>;
+        keptBytes: z.ZodNumber;
+        totalBytes: z.ZodNumber;
+    }, z.core.$strict>>]>;
+    status: z.ZodLiteral<"deadline_exceeded">;
+    timeoutMs: z.ZodNumber;
+    elapsedMs: z.ZodNumber;
+    message: z.ZodString;
+    sandbox: z.ZodObject<{
+        mode: z.ZodEnum<{
+            "read-only": "read-only";
+            workspace: "workspace";
+            "full-access": "full-access";
+        }>;
+        likelyDenied: z.ZodBoolean;
+        ranOutsideSandbox: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "status">, z.ZodUnion<readonly [z.ZodObject<{
+    process: z.ZodObject<{
+        id: z.ZodString & z.ZodType<import("@fungi.computer/cairn").CairnId<"local-computer-process", "process", 1>, string, z.core.$ZodTypeInternals<import("@fungi.computer/cairn").CairnId<"local-computer-process", "process", 1>, string>>;
+        command: z.ZodString;
+        cwd: z.ZodString;
+        state: z.ZodEnum<{
+            running: "running";
+            exited: "exited";
+        }>;
+        exitCode: z.ZodNullable<z.ZodNumber>;
+        signal: z.ZodNullable<z.ZodString>;
+        startedAt: z.ZodNumber;
+        endedAt: z.ZodNullable<z.ZodNumber>;
+        logPath: z.ZodString;
+        logBytes: z.ZodNumber;
+        logStartOffset: z.ZodNumber;
+        logTruncated: z.ZodBoolean;
+    }, z.core.$strict>;
+    offset: z.ZodNumber;
+    nextOffset: z.ZodNumber;
+    text: z.ZodString;
+    complete: z.ZodBoolean;
+    timedOut: z.ZodBoolean;
+    signalled: z.ZodOptional<z.ZodBoolean>;
+    sandbox: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            "read-only": "read-only";
+            workspace: "workspace";
+            "full-access": "full-access";
+        }>;
+        likelyDenied: z.ZodBoolean;
+        ranOutsideSandbox: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    processes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString & z.ZodType<import("@fungi.computer/cairn").CairnId<"local-computer-process", "process", 1>, string, z.core.$ZodTypeInternals<import("@fungi.computer/cairn").CairnId<"local-computer-process", "process", 1>, string>>;
+        command: z.ZodString;
+        cwd: z.ZodString;
+        state: z.ZodEnum<{
+            running: "running";
+            exited: "exited";
+        }>;
+        exitCode: z.ZodNullable<z.ZodNumber>;
+        signal: z.ZodNullable<z.ZodString>;
+        startedAt: z.ZodNumber;
+        endedAt: z.ZodNullable<z.ZodNumber>;
+        logPath: z.ZodString;
+        logBytes: z.ZodNumber;
+        logStartOffset: z.ZodNumber;
+        logTruncated: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>, z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"pending_approval">;
+    recordId: z.ZodString;
+    description: z.ZodObject<{
+        title: z.ZodString;
+        inputBytes: z.ZodNumber;
+        inputSha256: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"refused">;
+    reason: z.ZodString;
+}, z.core.$strict>]>]>;
+/** A host-attested stage door; the Computer cannot mint approval identity itself. */
+export type LocalExecEscapeStage = (input: Readonly<{
+    request: z.output<typeof execInput> | Extract<z.output<typeof backgroundExecInput>, {
+        operation: "start";
+    }>;
+    cwd: string;
+    mode: Exclude<LocalPermissionMode, "full-access">;
+    denialLine: string | null;
+    context: InvocationContext;
+    executionPath: string;
+}>) => Promise<PendingApproval | ApprovalRefusal>;
+/** Host-only prefix policy: the model has no rule-management door. */
+export type LocalExecPolicyRun = (input: Parameters<LocalExecEscapeStage>[0]) => Promise<z.output<typeof shellOutput> | undefined>;
+/** Run the recorded command through the normal bounded process door, without a sandbox.
+ * The host supplies the captured PATH and canonical cwd; the record supplies the
+ * exact original request. No model invocation can call this door directly. */
+export declare function dispatchApprovedLocalExec(input: unknown, cwd: string, executionPath: string, home: string, processes: PrivateLocalProcessScope, mode: LocalPermissionMode): Promise<ExecOutput | z.output<typeof backgroundExecOutput>>;
 export type ExecOutput = z.output<typeof execOutput>;
+export type ProcessOutput = z.output<typeof completedOutput> | z.output<typeof deadlineOutput>;
+/**
+ * A hint to the model, not evidence that an operation was refused. Only the
+ * sandboxed launch can carry this hint; common shell usage errors and missing
+ * commands are not sandbox denials, even if their stderr mentions permissions.
+ */
+export declare function likelySandboxDenied(mode: LocalPermissionMode, result: ProcessOutput): boolean;
 /** Shared bounded native process owner; callers supply argv/stdin, never shell interpolation. */
 export declare function runPrivateInvocationProcess(processCommand: ChildProcess.Command, signal: AbortSignal, timeoutMs: number | undefined, describe?: Readonly<{
     /** The timeout actually requested, before any clamp; defaults to `timeoutMs`. */
     requestedMs?: number;
     /** The real command text, for the timeout message; omitted when not meaningful (e.g. a native helper). */
     describeCommand?: () => string;
-}>): Promise<ExecOutput>;
+}>): Promise<ProcessOutput>;
 /**
  * Construct one private invocation-root Computer: bounded shell exec, plus the
  * background-process operations of `processes` when the host supplies a scope.
@@ -61,5 +271,7 @@ export declare function createPrivateInvocationComputer(invocationRoot: string,
 /** Selected host home; standalone callers capture it before any await. */
 home?: string, 
 /** Native Local always supplies its live per-Agent admission callback. */
-sandbox?: LocalSandboxLaunch): Promise<KnapsackComputer>;
+sandbox?: LocalSandboxLaunch, 
+/** The live Agent mode, captured once at the command boundary. */
+currentMode?: () => LocalPermissionMode, stageEscape?: LocalExecEscapeStage, runPolicy?: LocalExecPolicyRun): Promise<KnapsackComputer>;
 export {};

package/dist/private-invocation-computer.js

@@ -46,6 +46,9 @@ const capabilityNameSchema = z
     .regex(/^[A-Za-z][A-Za-z0-9_]*$/);
 const runCommonFields = {
     operation: z.literal("run").default("run"),
+    escape: z
+        .strictObject({ justification: z.string().min(1).max(2048) })
+        .optional(),
     cwd: launchCwdSchema.optional(),
     // Accepted up to the full invocation deadline and silently clamped to
     // maximumCommandTimeoutMs (see runCommandAtInvocationBoundary); rejecting
@@ -93,21 +96,68 @@ const commandOutputFields = {
     stderr: z.string(),
     truncated: z.union([z.literal(false), z.array(execTruncation).min(1)]),
 };
+const sandboxResult = z.strictObject({
+    mode: z.enum(["full-access", "workspace", "read-only"]),
+    likelyDenied: z.boolean(),
+    ranOutsideSandbox: z.boolean().default(false),
+});
+const completedOutput = z.strictObject({
+    status: z.enum(["completed", "failed"]),
+    ...commandOutputFields,
+});
+const deadlineOutput = z.strictObject({
+    status: z.literal("deadline_exceeded"),
+    timeoutMs: z.number().int().positive(),
+    elapsedMs: z.number().nonnegative(),
+    message: z.string(),
+    ...commandOutputFields,
+});
 const execOutput = z.discriminatedUnion("status", [
-    z.strictObject({
-        status: z.enum(["completed", "failed"]),
-        ...commandOutputFields,
-    }),
-    z.strictObject({
-        status: z.literal("deadline_exceeded"),
-        timeoutMs: z.number().int().positive(),
-        elapsedMs: z.number().nonnegative(),
-        message: z.string(),
-        ...commandOutputFields,
-    }),
+    completedOutput.extend({ sandbox: sandboxResult }),
+    deadlineOutput.extend({ sandbox: sandboxResult }),
 ]);
 const shellInput = z.union([execInput, backgroundExecInput]);
-const shellOutput = z.union([execOutput, backgroundExecOutput]);
+const pendingOutput = z.strictObject({
+    kind: z.literal("pending_approval"),
+    recordId: z.string(),
+    description: z.strictObject({
+        title: z.string(),
+        inputBytes: z.number(),
+        inputSha256: z.string(),
+    }),
+});
+const refusalOutput = z.strictObject({
+    kind: z.literal("refused"),
+    reason: z.string(),
+});
+const approvalOutput = z.union([pendingOutput, refusalOutput]);
+export const shellOutput = z.union([
+    execOutput,
+    backgroundExecOutput,
+    approvalOutput,
+]);
+/** Run the recorded command through the normal bounded process door, without a sandbox.
+ * The host supplies the captured PATH and canonical cwd; the record supplies the
+ * exact original request. No model invocation can call this door directly. */
+export async function dispatchApprovedLocalExec(input, cwd, executionPath, home, processes, mode) {
+    const request = shellInput.parse(input);
+    if (request.operation === "run") {
+        const result = await runCommandAtInvocationBoundary(request, cwd, executionPath, home, new AbortController().signal);
+        return execOutput.parse({
+            ...result,
+            sandbox: { mode, likelyDenied: false, ranOutsideSandbox: true },
+        });
+    }
+    if (request.operation !== "start")
+        throw new Error("Only recorded command launches may be dispatched");
+    const output = await callBackgroundExec(processes, request, () => Promise.resolve(cwd), executionPath, new AbortController().signal);
+    return "text" in output
+        ? {
+            ...output,
+            sandbox: { mode, likelyDenied: false, ranOutsideSandbox: true },
+        }
+        : output;
+}
 function computerCapabilities(root, processes) {
     return jsonValueSchema.parse([
         {
@@ -116,9 +166,11 @@ function computerCapabilities(root, processes) {
             kind: "runtime",
             // A filesystem path has no place in the bounded discovery summary.
             // Publish the exact root in the input schema, without truncating it.
-            description: `Shell, terminal, git, builds. cwd uses the root in the input schema. ~/$HOME use home. Or {executable,args}; stdin once, closed. exec kills its group at call end; nohup/& die. timeoutMs default ${String(defaultCommandTimeoutMs)}, max ${String(maximumCommandTimeoutMs)} ms; invocation ${String(invocationDeadlineMs)} ms; deadline returns partial output. Streams keep 64 KiB, then a [stdout|stderr truncated] line; redirect to a file or head/tail.${processes === undefined ? "" : ' Jobs: {operation:"start",command} or executable+args returns process.id; poll/wait: state, exitCode, tail. wait <=60000 ms; timedOut: wait expired. Cancelled wait keeps jobs. maxBytes <=64 KiB, offset/nextOffset; keeps last 8 MiB (logStartOffset). kill stops group; list: Session jobs. Delete/close stop jobs. Use wait, not sleep.'}`,
+            description: `Shell, terminal, git, builds. cwd uses the root in the input schema. ~/$HOME use home. Or {executable,args}; stdin once, closed. exec kills its group at call end; nohup/& die. timeoutMs default ${String(defaultCommandTimeoutMs)}, max ${String(maximumCommandTimeoutMs)} ms; invocation ${String(invocationDeadlineMs)} ms; deadline returns partial output. Streams keep 64 KiB, then a [stdout|stderr truncated] line; redirect to a file or head/tail. Only after a sandbox denial, retry with escape: {justification} to request human approval; no command runs until approval.${processes === undefined ? "" : ' Jobs: {operation:"start",command} or executable+args returns process.id; poll/wait: state, exitCode, tail. wait <=60000 ms; timedOut: wait expired. Cancelled wait keeps jobs. maxBytes <=64 KiB, offset/nextOffset; keeps last 8 MiB (logStartOffset). kill stops group; list: Session jobs. Delete/close stop jobs. Use wait, not sleep.'}`,
             parameters: structuredClone(z.toJSONSchema((processes === undefined ? execInput : shellInput).describe(`Computer root: ${root}. cwd must be absolute and remain inside this root; omission starts at the root.`), { io: "input" })),
-            output: structuredClone(z.toJSONSchema(processes === undefined ? execOutput : shellOutput)),
+            output: structuredClone(z.toJSONSchema(processes === undefined
+                ? z.union([execOutput, approvalOutput])
+                : shellOutput)),
         },
     ]);
 }
@@ -134,6 +186,24 @@ function commandTimeoutMessage(input) {
         : "";
     return `Command exceeded timeoutMs=${String(input.timeoutMs)} ms${clampNote}. Command: ${shortCommandLabel(input.command)}. Rerun with a larger timeoutMs, up to ${String(maximumCommandTimeoutMs)} ms; split longer work into separate tool calls.`;
 }
+/** Process stderr has no structured errno; classify only this display hint. */
+function classifySandboxDiagnostic(diagnostic) {
+    return /\b(?:EROFS|EPERM|EBUSY|read-only file system|operation not permitted|permission denied|device or resource busy|seccomp|sandbox|landlock)\b/iu.test(diagnostic)
+        ? "denial"
+        : "other";
+}
+/**
+ * A hint to the model, not evidence that an operation was refused. Only the
+ * sandboxed launch can carry this hint; common shell usage errors and missing
+ * commands are not sandbox denials, even if their stderr mentions permissions.
+ */
+export function likelySandboxDenied(mode, result) {
+    if (mode === "full-access" ||
+        result.exitCode === 0 ||
+        [2, 126, 127].includes(result.exitCode))
+        return false;
+    return classifySandboxDiagnostic(result.stderr) === "denial";
+}
 function isErrnoException(error) {
     return "code" in error;
 }
@@ -348,7 +418,7 @@ function buildRunCommand(request, cwd, executionPath, home, sandbox) {
         ? ["sh", "-c", request.command]
         : [request.executable, ...request.args];
     // Admission happens before spawn and is never retried after an executable
-    // may have run. Folder validity and requireSandbox belong to the host.
+    // may have run. Folder validity and mode belong to the host.
     const launch = sandbox?.(cwd, argv);
     if (launch !== undefined) {
         delete env.XDG_RUNTIME_DIR;
@@ -445,11 +515,19 @@ export function runPrivateInvocationProcess(processCommand, signal, timeoutMs, d
         };
     })).pipe(Effect.provide(NodeServices.layer)), { signal });
 }
-async function execute(root, executionPath, home, request, context, sandbox) {
+async function execute(root, executionPath, home, request, context, sandbox, mode = "full-access") {
     context.signal.throwIfAborted();
     const cwd = await resolveCwd(root, request.cwd);
     context.signal.throwIfAborted();
-    return runCommandAtInvocationBoundary(request, cwd, executionPath, home, context.signal, sandbox);
+    const result = await runCommandAtInvocationBoundary(request, cwd, executionPath, home, context.signal, sandbox);
+    return execOutput.parse({
+        ...result,
+        sandbox: {
+            mode,
+            likelyDenied: likelySandboxDenied(mode, result),
+            ranOutsideSandbox: sandbox === undefined,
+        },
+    });
 }
 /**
  * Construct one private invocation-root Computer: bounded shell exec, plus the
@@ -459,9 +537,12 @@ export async function createPrivateInvocationComputer(invocationRoot, executionP
 /** Selected host home; standalone callers capture it before any await. */
 home = capturePrivateLocalConfigRoot().home, 
 /** Native Local always supplies its live per-Agent admission callback. */
-sandbox) {
+sandbox, 
+/** The live Agent mode, captured once at the command boundary. */
+currentMode = () => "full-access", stageEscape, runPolicy) {
     const path = parsePrivateLocalExecPath(executionPath);
     const root = await realpath(resolve(invocationRoot));
+    let lastDenialLine = null;
     return Object.freeze({
         getCapabilities: () => Promise.resolve(computerCapabilities(root, processes)),
         call: async (capabilityId, input, context) => {
@@ -488,10 +569,69 @@ sandbox) {
                         message: "Computer exec command or argument contains a NUL byte. Remove it or double the backslash in JavaScript escapes (for example, \\\\x00); no process was started.",
                     },
                 });
-            if (request.operation === "run")
-                return execute(root, path, home, request, context, sandbox);
-            if (processes !== undefined)
-                return jsonValueSchema.parse(await callBackgroundExec(processes, request, (requested) => resolveCwd(root, requested), path, context.signal, sandbox));
+            const mode = currentMode();
+            if (mode !== "full-access" &&
+                (request.operation === "run" || request.operation === "start") &&
+                "executable" in request &&
+                runPolicy !== undefined) {
+                const cwd = await resolveCwd(root, request.cwd);
+                context.signal.throwIfAborted();
+                const allowed = await runPolicy({
+                    request,
+                    cwd,
+                    mode,
+                    denialLine: null,
+                    context,
+                    executionPath: path,
+                });
+                if (allowed !== undefined)
+                    return jsonValueSchema.parse(allowed);
+            }
+            if ((request.operation === "run" || request.operation === "start") &&
+                request.escape !== undefined &&
+                mode !== "full-access") {
+                if (stageEscape === undefined)
+                    throw new Error("Local escape approval owner is unavailable; command was not run");
+                const cwd = await resolveCwd(root, request.cwd);
+                context.signal.throwIfAborted();
+                return approvalOutput.parse(await stageEscape({
+                    request,
+                    cwd,
+                    mode,
+                    denialLine: lastDenialLine,
+                    context,
+                    executionPath: path,
+                }));
+            }
+            if (request.operation === "run") {
+                const result = await execute(root, path, home, request, context, sandbox, mode);
+                lastDenialLine = result.sandbox.likelyDenied
+                    ? (result.stderr
+                        .split("\n")
+                        .find((line) => classifySandboxDiagnostic(line) === "denial") ??
+                        null)
+                    : null;
+                return result;
+            }
+            if (processes !== undefined) {
+                const output = await callBackgroundExec(processes, request, (requested) => resolveCwd(root, requested), path, context.signal, sandbox);
+                return jsonValueSchema.parse("text" in output
+                    ? {
+                        ...output,
+                        sandbox: {
+                            mode,
+                            likelyDenied: likelySandboxDenied(mode, {
+                                status: "failed",
+                                exitCode: output.process.exitCode ?? 0,
+                                stderr: output.text,
+                                stdout: "",
+                                truncated: false,
+                            }),
+                            ranOutsideSandbox: sandbox === undefined,
+                        },
+                    }
+                    : output);
+            }
             throw new Error(`Computer capability is unavailable: ${selected}`);
         },
     });

package/dist/private-invocation-files.d.ts

@@ -1,8 +1,9 @@
 import { type FilesPort } from "@fungi.computer/knapsack";
+import type { LocalPermissionMode } from "./private-local-permission-mode.js";
 import type { LocalSandboxLaunch } from "./private-invocation-computer.js";
 /** Same live authority as exec; the policy module owns protected-path checks. */
 export type LocalSandboxWrites = Readonly<{
-    assertWrite(path: string): void;
+    assertWrite(paths: readonly string[]): void;
     launch: LocalSandboxLaunch;
 }>;
 /**
@@ -27,4 +28,4 @@ export declare class FilesPathError extends Error {
  * in-root symlinks. This is trusted same-user containment, not protection from
  * a same-user process racing pathname resolution.
  */
-export declare function createPrivateInvocationFilesPort(path: string, scanBounds?: ScanBounds, sandbox?: LocalSandboxWrites): Promise<FilesPort>;
+export declare function createPrivateInvocationFilesPort(path: string, scanBounds?: ScanBounds, sandbox?: LocalSandboxWrites, mode?: () => LocalPermissionMode): Promise<FilesPort>;

package/dist/private-invocation-files.js

@@ -7,6 +7,15 @@ import { RE2JS } from "re2js";
 import { createPrivateFilesPatch } from "./private-files-patch.js";
 import { fitLocalImage, maximumLocalImageInputBytes, } from "./local-image-fit.js";
 import writeFileAtomic from "write-file-atomic";
+const readOnlyFilesMessage = "Read-only mode: switch to Workspace to edit";
+/** An expected Files refusal, not a proposal for an approval. */
+class ReadOnlyFilesRefusal extends FilesEditError {
+    constructor(path) {
+        super("read-only", path, readOnlyFilesMessage);
+        this.name = "ReadOnlyFilesRefusal";
+        this.message = readOnlyFilesMessage;
+    }
+}
 const maximumFileBytes = 128 * 1_024;
 const defaultScanBounds = {
     candidates: 50_000,
@@ -472,10 +481,14 @@ function createWriteQueue() {
  * in-root symlinks. This is trusted same-user containment, not protection from
  * a same-user process racing pathname resolution.
  */
-export async function createPrivateInvocationFilesPort(path, scanBounds = defaultScanBounds, sandbox) {
+export async function createPrivateInvocationFilesPort(path, scanBounds = defaultScanBounds, sandbox, mode = () => "full-access") {
     const root = await InvocationRoot.capture(path);
     const write = createWriteQueue();
     const port = {
+        assertEditable(requested) {
+            if (mode() === "read-only")
+                throw new ReadOnlyFilesRefusal(requested);
+        },
         async read(input, context) {
             return await readPage(await root.existing(input.path, context), input.offset, input.limit, context);
         },
@@ -491,6 +504,7 @@ export async function createPrivateInvocationFilesPort(path, scanBounds = defaul
         async replace(input, context) {
             return await write(async () => {
                 checkCancellation(context);
+                port.assertEditable?.(input.path);
                 const path = await root.existing(input.path, context);
                 const current = await readBoundedText(path, context);
                 if (current !== input.expectedContent)
@@ -500,7 +514,7 @@ export async function createPrivateInvocationFilesPort(path, scanBounds = defaul
                     throw new FilesEditError("file-too-large", input.path, `Result exceeds ${String(maximumFileBytes)} bytes; use files.patch for a small change`);
                 }
                 checkCancellation(context);
-                sandbox?.assertWrite(path.resolved);
+                sandbox?.assertWrite([path.resolved]);
                 await writeFileAtomic(path.resolved, input.content, {
                     encoding: "utf8",
                 });
@@ -515,6 +529,11 @@ export async function createPrivateInvocationFilesPort(path, scanBounds = defaul
         return Object.freeze(port);
     return Object.freeze({
         ...port,
-        patch: (input, context) => write(() => patch(input, context)),
+        patch: (input, context) => write(async () => {
+            checkCancellation(context);
+            if (mode() === "read-only")
+                throw new ReadOnlyFilesRefusal(root.canonicalPath);
+            return patch(input, context);
+        }),
     });
 }

package/dist/private-local-agent-control.d.ts

@@ -70,7 +70,7 @@ export declare function createPrivateLocalAgentControl(input: Readonly<{
         list: (signal: AbortSignal, options?: Readonly<{
             archived?: boolean;
         }>) => Promise<readonly AgentControlAgent[]>;
-        send?: (input: import("@fungi.computer/shiitake/agent-control").AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: import("@fungi.computer/shiitake/agent-control").AgentDelegationInvocation) => Promise<import("@fungi.computer/shiitake").Accepted>;
+        send?: (input: import("@fungi.computer/shiitake/agent-control").AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: import("@fungi.computer/shiitake/agent-control").AgentDelegationInvocation) => Promise<import("@fungi.computer/shiitake").Accepted | import("@fungi.computer/shiitake").Held>;
         recall?: (input: import("@fungi.computer/shiitake/agent-control").AgentRecallInput, sourceSessionId: string, signal: AbortSignal) => Promise<import("@fungi.computer/shiitake").CancelResult>;
         create?: (input: Readonly<{
             requestId: string;
@@ -91,7 +91,7 @@ export declare function createPrivateLocalAgentControl(input: Readonly<{
         models?: (signal: AbortSignal) => Promise<readonly import("@fungi.computer/shiitake/agent-control").AgentControlModel[]>;
         checkModel?: (input: Readonly<{
             agentId: string;
-            sessionId: string;
+            sessionId?: string;
         }>, signal: AbortSignal) => Promise<void>;
         open: (agentId: string, signal: AbortSignal) => Promise<Readonly<{
             agent: import("@fungi.computer/shiitake").ShiitakeAgent;