@fungi.computer/truffle 0.2.1 → 0.3.0

package/dist/private-local-runtime-host.js

@@ -1,18 +1,22 @@
 import { createAssistantMessageEventStream } from "@earendil-works/pi-ai/utils/event-stream";
-import { observeProviderStatus } from "@fungi.computer/mule";
+import { observeProviderStatus, normalizeModel, decodeProviderData, } from "@fungi.computer/mule";
+import { normalizeContext } from "@earendil-works/pi-ai/utils/transcript";
 import { modelFailureMessage, modelFailureRetryable, } from "./private-provider-rejection.js";
 import { logEvent } from "./log-event.js";
 import { localArchiveHandoff } from "./local-archive-handoff.js";
 import { createMcpFormSession } from "./private-mcp-form-session.js";
+import { localExecEscapeReview } from "./private-local-exec-review.js";
+import { ApprovalLedger, } from "@fungi.computer/approvals";
 import { localExtensions, } from "./local-extensions.js";
 import { lstat, mkdir, realpath, stat } from "node:fs/promises";
 import { lstatSync, mkdirSync, realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
 import { createHash } from "node:crypto";
 import { z } from "zod";
+import { defaultLocalPermissionMode, localPermissionModeSchema, modeWithinCeiling, } from "./private-local-permission-mode.js";
 import { cleanupSessionResources, } from "@earendil-works/pi-ai";
 import { parseModelPreference, } from "@fungi.computer/shiitake/model-preference";
-import { createAgentControlSource, } from "@fungi.computer/shiitake/agent-control";
+import { AgentCreateRefused, createAgentControlSource, } from "@fungi.computer/shiitake/agent-control";
 import { defineIdFamily } from "@fungi.computer/cairn";
 import { words } from "@fungi.computer/cairn/words";
 import { botanicalExtensionsWithSkills } from "@fungi.computer/shiitake-extensions/roster";
@@ -27,12 +31,14 @@ import { ensureAgentDefaultModelTable, readAgentDefaultModel, seedAgentDefaultMo
 import { defaultLocalReasoning, resolveKnownLocalStartupChoice, resolveLocalStartupChoice, startupReasoning, validateLocalReasoning, } from "./private-local-startup-model.js";
 import { assertFungiModelsEnabled } from "./private-fungi-model-api.js";
 import { privateLocalEffectiveModelSchema, } from "./private-local-effective-model.js";
-import { createPrivateInvocationComputer, } from "./private-invocation-computer.js";
+import { createPrivateInvocationComputer, dispatchApprovedLocalExec, shellOutput, } from "./private-invocation-computer.js";
+import { localExecRules } from "./private-local-exec-rules.js";
 import { createPrivateLocalComputerProcesses, } from "./private-local-computer-processes.js";
 import { capturePrivateLocalExecPath, parsePrivateLocalExecPath, } from "./private-local-exec-path.js";
 import { ensurePrivateLocalGitExclude } from "./private-local-git-exclude.js";
-import { createLocalSandboxControls, } from "./private-local-sandbox.js";
-import { localAgentFolderSchema, resolveAgentFolder, } from "./private-local-sandbox-policy.js";
+import { createLocalSandboxControls, probeLocalSandbox, } from "./private-local-sandbox.js";
+import { LocalSandboxUnavailable } from "./private-local-containment.js";
+import { gitDirectories, protectedGitRemoteNames, localAgentFolderSchema, resolveAgentFolder, } from "./private-local-sandbox-policy.js";
 import { LocalStoreSchemaError } from "./private-local-session-discovery.js";
 import { acquireNodeStoreLease, nodeRuntimeHost, } from "@fungi.computer/shiitake/node";
 import { createPrivateInvocationFilesPort, } from "./private-invocation-files.js";
@@ -64,7 +70,8 @@ function isErrnoException(error) {
 function sidecarPathFor(databasePath) {
     return `${databasePath}.owner.sqlite`;
 }
-function ensureLocalAgentId(database, databasePath, pathAgentId, name, createdBy, folder, requireSandbox) {
+function ensureLocalAgentId(options) {
+    const { database, databasePath, project, pathAgentId, name, createdBy, folder, mode, native, } = options;
     database.exec("BEGIN IMMEDIATE");
     try {
         database.exec(`
@@ -75,16 +82,24 @@ function ensureLocalAgentId(database, databasePath, pathAgentId, name, createdBy
         created_by TEXT,
         archived INTEGER NOT NULL DEFAULT 0 CHECK (archived IN (0, 1)),
         folder TEXT NOT NULL DEFAULT '.',
-        require_sandbox INTEGER NOT NULL DEFAULT 0 CHECK (require_sandbox IN (0, 1))
+        mode TEXT NOT NULL CHECK (mode IN ('full-access', 'workspace', 'read-only')),
+        writable_folders TEXT NOT NULL DEFAULT '[]'
       )
     `);
         const columns = database
             .prepare("PRAGMA table_info(private_local_identity)")
             .all();
-        if (!["name", "created_by", "archived", "folder", "require_sandbox"].every((required) => columns.some((column) => column.name === required)))
+        if (![
+            "name",
+            "created_by",
+            "archived",
+            "folder",
+            "mode",
+            "writable_folders",
+        ].every((required) => columns.some((column) => column.name === required)))
             throw new LocalStoreSchemaError(databasePath);
         const row = database
-            .prepare("SELECT agent_id, created_by, folder FROM private_local_identity WHERE singleton = 1")
+            .prepare("SELECT agent_id, created_by, folder, mode FROM private_local_identity WHERE singleton = 1")
             .get();
         if (row !== undefined) {
             const parsed = localHostIds.store.schema.safeParse(row.agent_id);
@@ -97,18 +112,37 @@ function ensureLocalAgentId(database, databasePath, pathAgentId, name, createdBy
             if (folder !== undefined &&
                 localAgentFolderSchema.parse(folder) !== storedFolder)
                 throw new Error("Local Agent folder conflicts with its store");
-            if (requireSandbox !== undefined)
+            if (mode !== undefined) {
+                if (createdBy !== undefined) {
+                    if (!modeWithinCeiling(localPermissionModeSchema.parse(row.mode), mode))
+                        throw new AgentCreateRefused("exceeds_creator", "Child Agent mode exceeds its creator's mode");
+                    database.exec("COMMIT");
+                    return parsed.data;
+                }
+                if (mode !== "full-access") {
+                    const reason = probeLocalSandbox(project, storedFolder, native);
+                    if (reason !== undefined)
+                        throw new LocalSandboxUnavailable(reason);
+                }
                 database
-                    .prepare("UPDATE private_local_identity SET require_sandbox = ? WHERE singleton = 1")
-                    .run(requireSandbox ? 1 : 0);
+                    .prepare("UPDATE private_local_identity SET mode = ? WHERE singleton = 1")
+                    .run(mode);
+            }
             database.exec("COMMIT");
             return parsed.data;
         }
         const agentId = pathAgentId ?? localHostIds.store.generate();
+        const selectedFolder = localAgentFolderSchema.parse(folder ?? ".");
+        const unavailable = mode === "full-access"
+            ? undefined
+            : probeLocalSandbox(project, selectedFolder, native);
+        if (mode !== undefined && unavailable !== undefined)
+            throw new LocalSandboxUnavailable(unavailable);
+        const selectedMode = mode ?? defaultLocalPermissionMode(unavailable === undefined);
         database
-            .prepare("INSERT INTO private_local_identity (singleton, agent_id, name, created_by, folder, require_sandbox) VALUES (1, ?, ?, ?, ?, ?)")
+            .prepare("INSERT INTO private_local_identity (singleton, agent_id, name, created_by, folder, mode, writable_folders) VALUES (1, ?, ?, ?, ?, ?, '[]')")
             // An unnamed Agent gets a Cairn candidate word name so it never shows its id.
-            .run(agentId, name ?? words(), createdBy ?? null, localAgentFolderSchema.parse(folder ?? "."), requireSandbox === true ? 1 : 0);
+            .run(agentId, name ?? words(), createdBy ?? null, selectedFolder, selectedMode);
         database.exec("COMMIT");
         return agentId;
     }
@@ -556,82 +590,122 @@ export function createPrivateLocalModelSource(models, providerId, modelId, provi
             // prose that any SDK can supply.
             let modelFailure;
             return Promise.resolve(Object.freeze({
-                model: selected,
+                model: normalizeModel(selected),
                 retryable: (message) => !signal.aborted &&
                     message.stopReason === "error" &&
                     modelFailure?.message === message &&
                     modelFailure.retryable,
                 failureReason: (message) => modelFailure?.message === message ? modelFailure.reason : undefined,
+                providerError: (message) => modelFailure?.message === message
+                    ? modelFailure.providerError
+                    : undefined,
                 stream: (selected, context, options) => {
+                    const startedAt = Date.now();
                     modelFailure = undefined;
+                    let lastPartial;
                     const streamOptions = { ...options };
                     const reasoning = options?.reasoning ?? selectedReasoning;
                     if (reasoning !== undefined)
                         streamOptions.reasoning = reasoning;
                     const provider = observeProviderStatus(streamOptions);
                     const events = createAssistantMessageEventStream();
-                    const failure = (usage, aborted, upstream) => {
+                    const failure = (aborted, upstream, cause) => {
+                        const partial = upstream?.content.some((part) => part.type !== "text" || part.text.length > 0)
+                            ? upstream
+                            : (lastPartial ?? upstream);
                         const evidence = {
                             refusal: turn.refusal(),
-                            upstream,
+                            upstream: upstream ?? partial,
                             rejection: provider.rejection(),
                         };
-                        const message = modelFailureMessage(selected.provider, evidence);
+                        const message = cause === undefined
+                            ? modelFailureMessage(selected.provider, evidence)
+                            : `${selected.provider} ${cause instanceof Error && cause.name === "TimeoutError" ? "request timed out" : cause instanceof Error && cause.name === "AbortError" ? "request was aborted" : "connection failed"} after ${String(Date.now() - startedAt)} ms. Retry the request.`;
                         const result = {
                             role: "assistant",
-                            content: [],
+                            content: partial?.content ?? [],
                             api: selected.api,
                             provider: selected.provider,
                             model: selected.id,
-                            usage,
+                            usage: partial?.usage ?? {
+                                input: 0,
+                                output: 0,
+                                cacheRead: 0,
+                                cacheWrite: 0,
+                                totalTokens: 0,
+                                cost: {
+                                    input: 0,
+                                    output: 0,
+                                    cacheRead: 0,
+                                    cacheWrite: 0,
+                                    total: 0,
+                                },
+                            },
                             stopReason: aborted ? "aborted" : "error",
                             timestamp: Date.now(),
-                            errorMessage: aborted ? "Run cancelled" : message,
                         };
-                        if (!aborted)
+                        // The summary caller and retries receive only the safe reason.
+                        // The turn recorder obtains provider prose by exact message identity.
+                        result.errorMessage = aborted ? "Run cancelled" : message;
+                        if (!aborted) {
                             modelFailure = {
                                 message: result,
                                 reason: message,
                                 retryable: modelFailureRetryable(evidence),
                             };
+                            if (upstream?.errorMessage !== undefined)
+                                modelFailure.providerError = upstream.errorMessage;
+                        }
                         return result;
                     };
                     void (async () => {
                         try {
-                            const upstream = turn.models.streamSimple(selected, context, {
-                                ...streamOptions,
+                            const { onPayload, onResponse, ...rest } = streamOptions;
+                            const requestOptions = {
+                                ...rest,
                                 fetch: provider.fetch,
-                                onProviderStreamEvent: provider.onProviderStreamEvent,
+                                onProviderStreamEvent: (data, model) => provider.onProviderStreamEvent(decodeProviderData(data), normalizeModel(model)),
                                 sessionId: providerCacheKey,
                                 transport: options?.transport ?? "auto",
-                            });
+                            };
+                            if (onPayload !== undefined)
+                                requestOptions.onPayload = (data, model) => onPayload(decodeProviderData(data), normalizeModel(model));
+                            if (onResponse !== undefined)
+                                requestOptions.onResponse = (response, model) => onResponse(response, normalizeModel(model));
+                            const upstream = turn.models.streamSimple(selected, normalizeContext(context), requestOptions);
                             for await (const event of upstream) {
+                                if ("partial" in event)
+                                    lastPartial = event.partial;
                                 if (event.type === "error") {
-                                    const error = failure(event.error.usage, event.reason === "aborted", event.error);
+                                    const error = failure(event.reason === "aborted", event.error);
                                     events.push({ ...event, error });
                                     events.end(error);
                                     return;
                                 }
+                                if (event.type === "done" &&
+                                    (event.message.stopReason === "error" ||
+                                        event.message.stopReason === "aborted")) {
+                                    const aborted = event.message.stopReason === "aborted";
+                                    const error = failure(aborted, event.message);
+                                    events.push({
+                                        type: "error",
+                                        reason: aborted ? "aborted" : "error",
+                                        error,
+                                    });
+                                    events.end(error);
+                                    return;
+                                }
                                 events.push(event);
                             }
-                            events.end(await upstream.result());
+                            const result = await upstream.result();
+                            events.end(result.stopReason === "error" ||
+                                result.stopReason === "aborted"
+                                ? failure(result.stopReason === "aborted", result)
+                                : result);
                         }
-                        catch {
+                        catch (cause) {
                             const aborted = (options?.signal ?? signal).aborted;
-                            const error = failure({
-                                input: 0,
-                                output: 0,
-                                cacheRead: 0,
-                                cacheWrite: 0,
-                                totalTokens: 0,
-                                cost: {
-                                    input: 0,
-                                    output: 0,
-                                    cacheRead: 0,
-                                    cacheWrite: 0,
-                                    total: 0,
-                                },
-                            }, aborted);
+                            const error = failure(aborted, undefined, cause);
                             events.push({
                                 type: "error",
                                 reason: aborted ? "aborted" : "error",
@@ -648,7 +722,7 @@ export function createPrivateLocalModelSource(models, providerId, modelId, provi
     });
 }
 /** One local Computer source, resolving its PATH and process scope per Session. */
-function createPrivateLocalComputerSource(root, port, sessionPath, processes, home, sandbox) {
+function createPrivateLocalComputerSource(root, port, sessionPath, processes, home, sandbox, mode = () => "full-access", escapeForSession, policyForSession) {
     const id = "local-computer";
     return {
         id,
@@ -658,7 +732,7 @@ function createPrivateLocalComputerSource(root, port, sessionPath, processes, ho
                 throw new Error("Local Computer requires a Session");
             const path = sessionPath(sessionId) ??
                 capturePrivateLocalExecPath(process.env.PATH ?? "/usr/bin:/bin", process.cwd());
-            const selected = await createPrivateInvocationComputer(root, path, processes.scope(sessionId), home, sandbox);
+            const selected = await createPrivateInvocationComputer(root, path, processes.scope(sessionId), home, sandbox, mode, escapeForSession?.(sessionId), policyForSession?.(sessionId));
             return Knapsack.computer({
                 id,
                 name: "local",
@@ -683,10 +757,10 @@ storeDirectory,
  * This Agent's sub-agent record: its Session-bound Agent-control tools and
  * the view's facts. Present when it can direct other Agents.
  */
-subagents, configuration, configRoot = capturePrivateLocalConfigRoot(), sandbox) {
+subagents, configuration, configRoot = capturePrivateLocalConfigRoot(), sandbox, currentMode = () => "full-access", escapeForSession, policyForSession) {
     const forms = createMcpFormSession();
     const root = await realpath(resolve(invocationRoot));
-    const port = await createPrivateInvocationFilesPort(root, undefined, sandbox);
+    const port = await createPrivateInvocationFilesPort(root, undefined, sandbox, currentMode);
     const processes = createPrivateLocalComputerProcesses(root, configRoot.home);
     const computerSources = sessionPath === undefined
         ? [
@@ -698,11 +772,11 @@ subagents, configuration, configRoot = capturePrivateLocalConfigRoot(), sandbox)
                     port,
                     pathInstructions: localPathInstructions(root),
                 },
-                computer: await createPrivateInvocationComputer(root, undefined, processes.scope("invocation"), configRoot.home, sandbox?.launch),
+                computer: await createPrivateInvocationComputer(root, undefined, processes.scope("invocation"), configRoot.home, sandbox?.launch, currentMode, escapeForSession?.("invocation"), policyForSession?.("invocation")),
             }),
         ]
         : [
-            createPrivateLocalComputerSource(root, port, sessionPath, processes, configRoot.home, sandbox?.launch),
+            createPrivateLocalComputerSource(root, port, sessionPath, processes, configRoot.home, sandbox?.launch, currentMode, escapeForSession, policyForSession),
         ];
     const installed = configuration?.installed ??
         (storeDirectory === undefined
@@ -726,7 +800,11 @@ subagents, configuration, configRoot = capturePrivateLocalConfigRoot(), sandbox)
                 homeExtension({
                     computers: {
                         read: () => [
-                            { name: "local", attachmentId: "local-computer", port },
+                            {
+                                name: "local",
+                                attachmentId: "local-computer",
+                                port,
+                            },
                         ],
                     },
                 }),
@@ -759,7 +837,7 @@ subagents, configuration, configRoot = capturePrivateLocalConfigRoot(), sandbox)
                     ...(clientPath === undefined
                         ? computerSources
                         : [
-                            createPrivateLocalComputerSource(root, port, () => clientPath, processes, configRoot.home, sandbox?.launch),
+                            createPrivateLocalComputerSource(root, port, () => clientPath, processes, configRoot.home, sandbox?.launch, currentMode, escapeForSession, policyForSession),
                         ]),
                     ...(connection === undefined
                         ? []
@@ -797,9 +875,13 @@ function localRuntimeOwner() {
         }),
         settled: async () => {
             if (pendingWork === undefined)
-                return false;
+                return { idle: false, wakeAt: null };
             const work = await pendingWork();
-            return !work.pending && work.nextWakeAt === null;
+            return {
+                idle: !work.pending &&
+                    (work.nextWakeAt === null || work.nextWakeAt > Date.now()),
+                wakeAt: work.nextWakeAt,
+            };
         },
     });
 }
@@ -910,6 +992,16 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
             throw new ShiitakeError("model", "rejected", `Local model is not registered: ${selectedProviderId}/${selectedModelId ?? "select with --model"}`);
         validateLocalReasoning(model, input.reasoning);
     }
+    // A new explicit sandboxed Agent must be admissible before resolving its
+    // create receipt, directory, sidecar or SQLite file. Keep the check inside
+    // ensureLocalAgentId too: policy may change between this probe and commit.
+    if (input.databasePath === undefined &&
+        input.mode !== undefined &&
+        input.mode !== "full-access") {
+        const reason = probeLocalSandbox(root, localAgentFolderSchema.parse(input.folder ?? "."), input.native);
+        if (reason !== undefined)
+            throw new LocalSandboxUnavailable(reason);
+    }
     const paths = await localDatabasePaths(root, input.databasePath, input.createRequestId);
     const runtime = localRuntimeOwner();
     let lease;
@@ -928,20 +1020,34 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
             .digest("hex");
         database = openPrivateWritableSqliteDatabase(paths.databasePath, 0);
         database.exec("PRAGMA foreign_keys = ON");
-        const agentId = ensureLocalAgentId(database, paths.databasePath, paths.agentId, input.name, input.createdBy, input.folder, input.requireSandbox);
+        const agentId = ensureLocalAgentId({
+            database,
+            databasePath: paths.databasePath,
+            project: root,
+            pathAgentId: paths.agentId,
+            name: input.name,
+            createdBy: input.createdBy,
+            folder: input.folder,
+            mode: input.mode,
+            native: input.native,
+        });
         const sandboxDatabase = database;
-        const readSandboxRequirement = () => z
-            .union([z.literal(0), z.literal(1)])
-            .parse(sandboxDatabase
-            .prepare("SELECT require_sandbox FROM private_local_identity WHERE singleton = 1")
-            .get()?.require_sandbox) === 1;
+        const readMode = () => localPermissionModeSchema.parse(sandboxDatabase
+            .prepare("SELECT mode FROM private_local_identity WHERE singleton = 1")
+            .get()?.mode);
         const selectedFolder = resolveAgentFolder(root, localAgentFolderSchema.parse(database
             .prepare("SELECT folder FROM private_local_identity WHERE singleton = 1")
             .get()?.folder));
+        const defaultReason = readMode() === "full-access" && input.mode === undefined
+            ? probeLocalSandbox(root, selectedFolder.folder, input.native)
+            : undefined;
         const sandboxOwner = createLocalSandboxControls({
             project: root,
             folder: selectedFolder.folder,
-            required: readSandboxRequirement,
+            agentId,
+            mode: readMode,
+            defaultReason,
+            native: input.native,
         });
         sandbox = sandboxOwner;
         // Both constructors below can resume stored commands before returning.
@@ -1008,7 +1114,178 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
                 directory: projectDirectory,
                 storage: store,
             });
-        const localTools = await createPrivateLocalTools(selectedFolder.absolute, input.fungiMcp, subagents?.directory, (sessionId) => sessionPaths.get(sessionId), dirname(paths.databasePath), subagents, await input.configuration?.(dirname(paths.databasePath)), configRoot, sandboxOwner);
+        const escapeLedger = new ApprovalLedger({
+            owner: createPrivateSqliteOwner(database),
+            home: { kind: "local", id: agentId },
+            now: Date.now,
+        });
+        const execRules = localExecRules(root);
+        // An Agent can create .git after opening the Session. That does not make
+        // its newly authored config/hooks a protected repository for a grant.
+        const grantRepository = lstatSync(join(root, ".git"), { throwIfNoEntry: false }) === undefined
+            ? undefined
+            : gitDirectories(root, root);
+        // The attached human's answer, never form JSON or the model, selects
+        // this short-lived intent. Commit the rule before dispatching the command.
+        const ruleIntents = new Map();
+        const selectRule = (recordId, prefix) => (selected) => {
+            if (selected === "prefix")
+                ruleIntents.set(recordId, () => {
+                    execRules.add(prefix);
+                });
+            else
+                ruleIntents.delete(recordId);
+        };
+        const escapeFence = () => JSON.stringify([
+            readMode(),
+            resolveAgentFolder(root, localAgentFolderSchema.parse(sandboxDatabase
+                .prepare("SELECT folder FROM private_local_identity WHERE singleton = 1")
+                .get()?.folder)).absolute,
+        ]);
+        const escapeApply = {
+            recheck: () => Promise.resolve({
+                kind: "authorized",
+                authorityFence: escapeFence(),
+            }),
+            dispatch: async ({ record, input: payload }) => {
+                if (record.module !== "computer" || record.operation !== "exec")
+                    return { kind: "refused", reason: "not-granted" };
+                const evidence = z
+                    .object({
+                    request: z.unknown(),
+                    cwd: z.string(),
+                    executionPath: z.string(),
+                })
+                    .parse(payload);
+                // Refuse a replaced or re-pointed working directory: the card showed
+                // the canonical path selected at staging, not a later symlink target.
+                if ((await realpath(evidence.cwd)) !== evidence.cwd)
+                    return { kind: "refused", reason: "not-granted" };
+                const sessionId = record.requester.sessionId;
+                if (sessionId === null)
+                    return { kind: "refused", reason: "not-granted" };
+                const output = await dispatchApprovedLocalExec(evidence.request, evidence.cwd, evidence.executionPath, configRoot.home, localTools.processes.scope(sessionId), readMode());
+                return { kind: "completed", output: z.json().parse(output) };
+            },
+        };
+        const deliverEscapeResult = async (recordId) => {
+            await escapeLedger.handoff(recordId, async (notice) => {
+                const sessionId = notice.record.requester.sessionId;
+                if (sessionId === null)
+                    throw new Error("Approval has no recipient Session");
+                const accepted = await sessionOwner
+                    .session(sessionId)
+                    .send(`Approval ${notice.record.module}.${notice.record.operation}: ${JSON.stringify(notice.result)}`, { requestId: notice.deliveryId, delivery: "followUp" });
+                return { commandId: accepted.commandId };
+            });
+        };
+        const escapeApprovals = escapeLedger.capability({
+            // Only the attached Local UI reaches the form's answer command. The
+            // model has no member-bound approval capability.
+            actor: () => Promise.resolve({
+                kind: "human",
+                memberId: agentId,
+                role: "owner",
+                actingForAgent: false,
+                mayUseOperation: true,
+            }),
+            decision: async (recordId) => {
+                const answered = escapeLedger.get(recordId);
+                if (answered?.state === "approved") {
+                    if (answered.module === "computer" &&
+                        answered.operation === "exec" &&
+                        answered.authorityFence === escapeFence())
+                        ruleIntents.get(recordId)?.();
+                    await escapeLedger.apply(recordId, escapeApply);
+                }
+                for (const pending of escapeLedger.pendingHandoffs())
+                    await deliverEscapeResult(pending);
+            },
+        });
+        const escapeForSession = (sessionId) => async ({ request, cwd, mode, denialLine, context, executionPath }) => {
+            if (request.escape === undefined)
+                throw new Error("An escape requires a justification");
+            // The identity, current mode and root are host facts, not model input.
+            const staged = await escapeLedger.request({
+                requester: {
+                    principalId: agentId,
+                    agentId,
+                    sessionId,
+                    displayName: name,
+                },
+                module: "computer",
+                operation: "exec",
+                access: "external",
+                reversibility: "irreversible-external",
+                authorityFence: JSON.stringify([mode, selectedFolder.absolute]),
+                idempotencyKey: JSON.stringify([
+                    context.executionId,
+                    context.toolCallId ?? null,
+                    context.operationOrdinal ?? null,
+                ]),
+                inputJson: JSON.stringify({
+                    request,
+                    cwd,
+                    mode,
+                    denialLine,
+                    executionPath,
+                }),
+                requireHumanApproval: true,
+            });
+            if (staged.kind === "refused")
+                return staged;
+            if (staged.record.state !== "pending")
+                return {
+                    kind: "refused",
+                    reason: staged.record.state === "expired"
+                        ? "expired"
+                        : "already-answered",
+                };
+            const pending = {
+                kind: "pending_approval",
+                recordId: staged.record.recordId,
+                description: staged.record.description,
+            };
+            const review = localExecEscapeReview(request, cwd);
+            const presented = await localTools.presentApproval(sessionId, pending, escapeApprovals, review, review.prefix === undefined
+                ? undefined
+                : selectRule(pending.recordId, review.prefix));
+            if (presented.kind !== "presented")
+                throw new Error("Local escape approval could not be presented");
+            return pending;
+        };
+        const policyForSession = (sessionId) => async ({ request, cwd, mode, executionPath }) => {
+            if (mode !== "workspace" || !("executable" in request))
+                return undefined;
+            let configuredRemotes;
+            if (request.executable === "git") {
+                // Only the project's own protected common Git directory may use a
+                // Git grant. A nested/Agent-created repository has writable config.
+                const protectedGit = grantRepository === undefined
+                    ? undefined
+                    : gitDirectories(root, root, executionPath);
+                const selectedGit = gitDirectories(root, cwd, executionPath);
+                if (protectedGit?.common === undefined ||
+                    protectedGit.common !== grantRepository?.common ||
+                    protectedGit.worktree !== grantRepository.worktree ||
+                    selectedGit?.common !== protectedGit.common ||
+                    selectedGit.worktree !== protectedGit.worktree)
+                    return undefined;
+                configuredRemotes = protectedGitRemoteNames(root, protectedGit.common, executionPath);
+                if (configuredRemotes === undefined)
+                    return undefined;
+            }
+            const matched = execRules.match([request.executable, ...request.args], configuredRemotes);
+            if (matched === undefined)
+                return undefined;
+            input.onExecRuleMatch?.({
+                agentId,
+                executable: request.executable,
+                ruleId: matched.ruleId,
+            });
+            return shellOutput.parse(await dispatchApprovedLocalExec(request, cwd, executionPath, configRoot.home, localTools.processes.scope(sessionId), mode));
+        };
+        const localTools = await createPrivateLocalTools(selectedFolder.absolute, input.fungiMcp, subagents?.directory, (sessionId) => sessionPaths.get(sessionId), dirname(paths.databasePath), subagents, await input.configuration?.(dirname(paths.databasePath)), configRoot, sandboxOwner, () => sandboxOwner.status().mode, escapeForSession, policyForSession);
         processes = localTools.processes;
         const sessionProcesses = processes;
         const modelSource = createPrivateLocalModelSource(models, selectedProviderId, selectedModelId, providerCacheKey, input.reasoning, { agent: readAgentModel });
@@ -1034,6 +1311,40 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
             readSettlement = host.readSettlement;
         }
         const sessionOwner = agent;
+        async function recoverEscapes(sessionId) {
+            for (const recordId of escapeLedger.pendingApplications())
+                await escapeLedger.apply(recordId, escapeApply);
+            for (const recordId of escapeLedger.pendingHandoffs())
+                await deliverEscapeResult(recordId);
+            const page = await escapeApprovals.list({ state: "pending", limit: 100 });
+            for (const view of page.items) {
+                if (view.record.requester.sessionId !== sessionId)
+                    continue;
+                if (view.record.module !== "computer" ||
+                    view.record.operation !== "exec")
+                    continue;
+                const input = escapeLedger.readInput(view.record.recordId);
+                const evidence = z
+                    .object({
+                    request: z.object({
+                        command: z.string().optional(),
+                        executable: z.string().optional(),
+                        args: z.array(z.string()).optional(),
+                        escape: z.object({ justification: z.string() }),
+                    }),
+                    cwd: z.string(),
+                })
+                    .parse(input);
+                const review = localExecEscapeReview(evidence.request, evidence.cwd);
+                await localTools.presentApproval(sessionId, {
+                    kind: "pending_approval",
+                    recordId: view.record.recordId,
+                    description: view.record.description,
+                }, escapeApprovals, review, review.prefix === undefined
+                    ? undefined
+                    : selectRule(view.record.recordId, review.prefix));
+            }
+        }
         const setAgentModel = async (input, signal) => {
             const preference = parseModelPreference(input);
             if (preference === null)
@@ -1046,6 +1357,10 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
         // Session override is cleared so the running Session follows the default.
         const getSession = (sessionId, attachment) => {
             const session = localTools.bindSession(sessionId, sessionOwner.session(sessionId), attachment);
+            if (attachment !== undefined)
+                void recoverEscapes(sessionId).catch((cause) => {
+                    logEvent("local-approval-recovery-failed", cause);
+                });
             return {
                 ...session,
                 modelPreference: {
@@ -1069,11 +1384,11 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
             getSession,
             presentApproval: localTools.presentApproval,
             setModel: setAgentModel,
-            setRequireSandbox: (required) => {
+            setMode: (mode) => {
+                sandboxOwner.assertModeReady(mode);
                 sandboxDatabase
-                    .prepare("UPDATE private_local_identity SET require_sandbox = ? WHERE singleton = 1")
-                    .run(required ? 1 : 0);
-                sandboxOwner.assertReady();
+                    .prepare("UPDATE private_local_identity SET mode = ? WHERE singleton = 1")
+                    .run(mode);
             },
             sandboxStatus: sandboxOwner.status,
             setArchived: (archived) => {
@@ -1133,10 +1448,12 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
                 ? Promise.reject(new Error("Local settlement reads are unavailable"))
                 : readSettlement(sessionId, commandId),
             idle: async () => {
+                const busy = { idle: false, wakeAt: null };
                 if (sessionProcesses.running())
-                    return false;
-                if (!(await runtime.settled()))
-                    return false;
+                    return busy;
+                const settlement = await runtime.settled();
+                if (!settlement.idle)
+                    return busy;
                 // Delegated work still owed to this Agent is not read here: that read
                 // reopens each child, and the child's reply mail reopens this Agent.
                 let after;
@@ -1144,7 +1461,7 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
                     const page = await sessionOwner.listSessions(after);
                     for (const row of page.sessions)
                         if (row.state === "running" || row.state === "needs_you")
-                            return false;
+                            return busy;
                     after = page.next;
                 } while (after !== undefined);
                 // Reconciliation enqueues replies before advancing its settled cursor.
@@ -1152,8 +1469,11 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
                 // while we await settlement or Session reads, especially during stop
                 // when delivery cannot reopen a parent. The owner rechecks admissions
                 // and uses after this observation before forgetting the Agent.
-                return (input.mail === undefined ||
-                    !(await hasPrivateLocalPendingMail(modelDatabase)));
+                return {
+                    idle: input.mail === undefined ||
+                        !(await hasPrivateLocalPendingMail(modelDatabase)),
+                    wakeAt: settlement.wakeAt,
+                };
             },
             close: () => {
                 closing ??= closePrivateLocalResources({