@foldrun/core 2.14.3 → 3.0.0

package/dist/src/runner.js

@@ -2824,6 +2824,8 @@ mayDefer) {
                 tenant,
                 input: {
                     agentRel: path.relative(workspaceRoot, agentDir).replaceAll("\\", "/"),
+                    // Its file tools inside the sandbox get the same allowance (FOL-96).
+                    configWrites: step.approve === true && Boolean(step.approvedAt),
                     prompt,
                     model,
                     effort,
@@ -2913,6 +2915,11 @@ mayDefer) {
                 network: { level: network.level, enforced: forward?.enforce === true },
                 // A test run's state/ and storage/ changes come out under the run.
                 divert: testRun && runId ? divertFor(runId) : undefined,
+                // Read at copy-out: what the host handed back into the sandbox.
+                handedBack: () => step.handedBack,
+                // A person approved this step before it ran: configuration and code
+                // it changes are kept, listed on the trail (FOL-96).
+                configWrites: step.approve === true && Boolean(step.approvedAt),
                 test: testRun,
                 // Resume: a sandbox a previous driver left running, recorded on the
                 // step. Consumed once — a fresh attempt after this one (a retry, a
@@ -3120,6 +3127,12 @@ mayDefer) {
             step.browserPod = outcome.browserPod ? { ...outcome.browserPod } : null;
             if (step.subagentOf && outcome.applied?.length)
                 step.wrote = [...new Set([...(step.wrote ?? []), ...outcome.applied])];
+            if (outcome.refused?.length) {
+                const seen = new Map((step.refused ?? []).map((r) => [r.path, r]));
+                for (const r of outcome.refused)
+                    seen.set(r.path, r);
+                step.refused = [...seen.values()];
+            }
             if (outcome.status === "failed" && outcome.browserPod?.lost) {
                 const decision = podLossDecision(outcome.browserPod);
                 if (decision.rerun) {
@@ -3291,6 +3304,9 @@ mayDefer) {
             const attemptInProcess = (modelEnv) => executeStep({
                 agentDir,
                 workspaceRoot,
+                // A person approved this step (its gate) before it ran: it may change
+                // configuration and code (FOL-96) — the desks' retro applies fixes so.
+                configWrites: step.approve === true && Boolean(step.approvedAt),
                 libraryRoot: libraryDir(tenant),
                 ...(subagents.length ? { subagents } : {}),
                 // The colleagues' inbox, read after every tool call — the same hook
@@ -4991,6 +5007,22 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     // Its files go back with the reply, so the delegating step's
                     // sandbox has them too (delegate-tools.ts copyBackFiles).
                     const back = readCopyBack(pDir, child.wrote ?? []);
+                    // What goes back into the parent's sandbox, as the host sends it:
+                    // its copy-out reads this, not the sandbox's own note (FOL-96).
+                    if (back.files.length) {
+                        parent.handedBack = { ...(parent.handedBack ?? {}) };
+                        for (const f of back.files) {
+                            const h = crypto.createHash("sha256").update(Buffer.from(f.base64, "base64")).digest("hex");
+                            // Kept beside any earlier job's for the same path, never over
+                            // it: either may be what the sandbox ends up holding.
+                            const prev = parent.handedBack[f.path];
+                            const all = prev === undefined ? [] : Array.isArray(prev) ? prev : [prev];
+                            if (!all.includes(h))
+                                all.push(h);
+                            parent.handedBack[f.path] = all.length === 1 ? all[0] : all;
+                        }
+                        save();
+                    }
                     return {
                         status,
                         result: child.result ?? (errors || "(no reply)"),

package/dist/src/step-exec.d.ts

@@ -57,6 +57,9 @@ export interface ExecOutcome {
     browserPod?: BrowserPodOutcome;
 }
 export interface ExecOptions {
+    /** A person approved this step before it ran: its file tools may write
+     *  the workspace's configuration and code (confine.ts, FOL-96). */
+    configWrites?: boolean;
     /** What the step reports beyond its events (FOL-54 step 4): `metadata`
      *  sends each model call (`turn`); `full` also sends each tool call's input
      *  and output (`io`). Unset sends neither — the consult, the probe and any

package/dist/src/step-exec.js

@@ -315,7 +315,7 @@ async function executeStepInner(opts, runQuery) {
                                     }
                                 }
                                 const verdict = isFilesystemTool(hookInput.tool_name)
-                                    ? checkPaths(hookInput.tool_name, hookInput.tool_input, { agentDir, workspaceRoot, libraryRoot })
+                                    ? checkPaths(hookInput.tool_name, hookInput.tool_input, { agentDir, workspaceRoot, libraryRoot, configWrites: opts.configWrites })
                                     : null;
                                 if (verdict && !verdict.ok) {
                                     emit("error", verdict.reason, via ? { subagent: via } : undefined);
@@ -357,7 +357,7 @@ async function executeStepInner(opts, runQuery) {
                                         const again = hookInput.tool_name === "Bash"
                                             ? checkBash(String(v.input.command ?? ""))
                                             : isFilesystemTool(hookInput.tool_name)
-                                                ? checkPaths(hookInput.tool_name, v.input, { agentDir, workspaceRoot, libraryRoot })
+                                                ? checkPaths(hookInput.tool_name, v.input, { agentDir, workspaceRoot, libraryRoot, configWrites: opts.configWrites })
                                                 : { ok: true };
                                         const granted = opts.allowed.includes(hookInput.tool_name) || opts.mcpNames.some((n) => hookInput.tool_name.startsWith(`mcp__${n}__`));
                                         // The sub-agent guard read the ORIGINAL input: a rewrite of a
@@ -432,7 +432,7 @@ async function executeStepInner(opts, runQuery) {
                 const verdict = toolName === "Bash"
                     ? checkBash(String(input.command ?? ""))
                     : isFilesystemTool(toolName)
-                        ? checkPaths(toolName, input, { agentDir, workspaceRoot, libraryRoot })
+                        ? checkPaths(toolName, input, { agentDir, workspaceRoot, libraryRoot, configWrites: opts.configWrites })
                         : { ok: true };
                 if (!verdict.ok) {
                     refund();

package/dist/src/store.d.ts

@@ -1294,6 +1294,17 @@ export interface StepRecord {
     /** On an isolated sub-agent's run: the workspace paths its sandbox's
      *  changes were applied to — what its delegating step is told it wrote. */
     wrote?: string[];
+    /** What this step's sandbox changed that was not taken back to the
+     *  workspace: configuration and code, which a step proposes and a person
+     *  applies (copy-back.ts, FOL-96). */
+    refused?: {
+        path: string;
+        kind: "config" | "code";
+    }[];
+    /** What the host handed back into this step's sandbox mid-step — its
+     *  `sandbox: own` jobs' files, path → sha256 — recorded HERE, on the host,
+     *  so the copy-out never has to take the sandbox's word for it (FOL-96). */
+    handedBack?: Record<string, string | string[]>;
     /**
      * Sandbox seconds this step rented, and how many of them were cold start.
      * Set only on the isolated path — an in-process step rents nothing, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "2.14.3",
+  "version": "3.0.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "FSL-1.1-ALv2",
   "type": "module",

package/src/confine.ts

@@ -30,6 +30,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { refusedBack } from "./copy-back.ts";
 
 /**
  * A path with its symlinks resolved, as far as it exists.
@@ -97,6 +98,9 @@ export interface Roots {
   workspaceRoot: string;
   /** The account library: readable, never writable. */
   libraryRoot: string;
+  /** A person approved this step before it ran (an approval gate): its
+   *  writes to the workspace's configuration and code are allowed. */
+  configWrites?: boolean;
 }
 
 // Skills are announced to the agent with virtual prefixes — `workspace/skills/…`
@@ -322,6 +326,21 @@ export function checkPaths(
       };
     }
 
+    // Configuration and code are a person's: the same list a sandbox's
+    // copy-back refuses (copy-back.ts, FOL-96), so a step that runs on this
+    // host, with no sandbox between it and the files, is held to the same
+    // rule by its file tools. Its shell is not confined here — isolation is.
+    const asConfig = isWrite && !inLibrary && !roots.configWrites ? refusedBack(within) : null;
+    if (asConfig) {
+      return {
+        ok: false,
+        reason:
+          `${toolName} was denied: "${raw}" is this workspace's ${asConfig === "config" ? "configuration" : "code"}, ` +
+          `which a run does not change. Say what should change and why in your answer — a person ` +
+          `applies it (or it becomes a Proposed fix). Your own notes go to outputs/ or workspace/memory/.`,
+      };
+    }
+
     // Hand the real path back to the tool, so the virtual prefix the prompt
     // advertises is one the agent can actually open — unless the step's
     // `workspace` link already opens it. Then the path is left as written,

package/src/copy-back.ts

@@ -0,0 +1,87 @@
+// What a run's sandbox may hand back to the workspace (FOL-96, 27 Oct 2026).
+//
+// A step's file changes come back from its sandbox (run-container.ts
+// applyContainerChanges — the docker and the k8s runner both), and until now
+// everything came back that was not platform-owned, knowledge or hooks. So a
+// step steered by a page it read could rewrite AGENTS.md, an agent.md or a
+// flow — its own tools:, network:, a provider: block, a new scheduled flow —
+// and every later run, the next step of the same run included, ran on it.
+//
+// Configuration and code are a person's to change. A step that wants a
+// change proposes it (Proposed fixes, the assistant), and a person applies
+// it; a step that writes one anyway has the write refused, and the run's
+// trail names it. What steps legitimately write — state/, memory/, storage/,
+// an agent's own outputs — comes back as before.
+//
+// The list is not written here. It is read off the kinds (kinds.ts), whose
+// every row must say what its files are, so a kind added later is classified
+// the moment it exists — tsc refuses a row without `copyBack`.
+
+import { KINDS, ALL_KINDS, SUBAGENT_IMPORT_DIRS, WORKSPACE_CONFIG_FILES, type CopyBackClass, type Kind } from "./kinds.ts";
+
+/** A path a step changed that was not taken back, and why. */
+export interface RefusedPath {
+  path: string;
+  kind: "config" | "code";
+}
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const NAME = "\u0000";
+
+/** Where an agent's own folder is — the scope agent-level kinds live under. */
+const AGENT_SCOPE = KINDS.agents.file(NAME).split(NAME)[0]; // "agents/"
+
+/** The path shapes one kind's files take, inside a workspace. */
+export function kindPatterns(kind: Kind): RegExp[] {
+  const meta = KINDS[kind];
+  const file = meta.file(NAME);
+  // An agent's folder is a scope as well as a document: everything else in
+  // it is the agent's working directory. Its document is the one file.
+  if (kind === "agents") {
+    const [head, tail] = file.split(NAME);
+    return [new RegExp(`^${escape(head)}[^/]+${escape(tail)}$`)];
+  }
+  // Every other kind owns its top-level folder — a file document's siblings
+  // (a tool's script beside its .md) and a folder document's contents alike.
+  const root = file.split("/")[0];
+  const out = [new RegExp(`^${escape(root)}/`)];
+  if (meta.scopes.includes("agent")) out.push(new RegExp(`^${escape(AGENT_SCOPE)}[^/]+/${escape(root)}/`));
+  return out;
+}
+
+const RULES: { re: RegExp; kind: "config" | "code" }[] = [
+  ...WORKSPACE_CONFIG_FILES.map((f) => ({ re: new RegExp(`^${escape(f)}$`), kind: "config" as const })),
+  // Single-file subagents another tool wrote: a deploy imports them as agents.
+  ...[...new Set(SUBAGENT_IMPORT_DIRS.map((d) => d.split("/")[0]))].map((d) => ({ re: new RegExp(`^${escape(d)}/`), kind: "config" as const })),
+  ...ALL_KINDS.flatMap((k) => {
+    const cls: CopyBackClass = KINDS[k].copyBack;
+    return cls === "data" ? [] : kindPatterns(k).map((re) => ({ re, kind: cls }));
+  }),
+];
+
+/** Whether a step's write to `rel` (workspace-relative) is refused on the way
+ *  back, and as what; null when it is data and may come back. */
+export function refusedBack(rel: string): "config" | "code" | null {
+  const norm = rel.replaceAll("\\", "/").replace(/^\.\//, "");
+  for (const r of RULES) if (r.re.test(norm)) return r.kind;
+  return null;
+}
+
+/** The trail's line for a step's refused writes. */
+/** The trail's line for config and code a person-approved step changed and
+ *  that were kept (an approval gate before the step: the person read what
+ *  it would do — the desks' retro applies approved fixes this way). */
+export function keptLine(kept: readonly RefusedPath[]): string {
+  const shown = kept.slice(0, 20).map((r) => `${r.path} (${r.kind})`).join(", ");
+  const more = kept.length > 20 ? ` and ${kept.length - 20} more` : "";
+  return `kept with approval: ${shown}${more} — configuration or code this step changed, kept because a person approved the step before it ran`;
+}
+
+export function refusedLine(refused: readonly RefusedPath[]): string {
+  const shown = refused.slice(0, 20).map((r) => `${r.path} (${r.kind})`).join(", ");
+  const more = refused.length > 20 ? ` and ${refused.length - 20} more` : "";
+  return (
+    `refused path: ${shown}${more} — a step cannot change the workspace's configuration or code; ` +
+    `the workspace keeps its own copy. Propose the change instead (Proposed fixes), and a person applies it.`
+  );
+}

package/src/deploy.ts

@@ -41,6 +41,7 @@ import { libraryTools } from "./library.ts";
 import { lintFlow, regexProblem } from "./flow-lint.ts";
 import { parseEval } from "./evals.ts";
 import { refNames } from "./refs.ts";
+import { SUBAGENT_IMPORT_DIRS } from "./kinds.ts";
 import matter, { configMatter } from "./matter.ts";
 import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.ts";
 import { conformanceIssues } from "./okf.ts";
@@ -123,12 +124,9 @@ export interface DeployResult extends DeployPlan {
  * skipped rather than rejected, because a workspace living in a repo alongside
  * other things is the normal case, not an error.
  */
-// Where single-file subagents authored by other tools are found, in
-// precedence order: the vendor-neutral cross-client location first, then any
-// tool-specific one for pragmatic compatibility. Extend the tail, never the
-// head. Shared by the deploy import (readTree) and the CLI checker so the two
-// agree on what counts as an agent.
-export const SUBAGENT_IMPORT_DIRS = [".agents/agents", ".claude/agents"] as const;
+// Where single-file subagents authored by other tools are found — declared
+// with the kinds (kinds.ts), which the copy-back rule reads too.
+export { SUBAGENT_IMPORT_DIRS };
 
 /** What agents write as they run, not what anyone authored: state/ and
  *  memory/, the workspace's or one agent's. */

package/src/kinds.ts

@@ -55,6 +55,20 @@ export type Kind =
 // question each answers rather than the alphabet, and a consistency test
 // holds the sidebar and the asset pages to it.
 
+/** How a run's write to a kind's files is treated on the way back. */
+export type CopyBackClass = "config" | "code" | "data";
+
+/** Workspace files that are configuration without being a kind: the shared
+ *  context and its pre-rename name. */
+export const WORKSPACE_CONFIG_FILES = ["AGENTS.md", "project.md"] as const;
+
+// Where single-file subagents authored by other tools are found, in
+// precedence order: the vendor-neutral cross-client location first, then any
+// tool-specific one for pragmatic compatibility. Extend the tail, never the
+// head. Shared by the deploy import (deploy.ts readTree), the CLI checker
+// and the copy-back rule, so all three agree on what counts as an agent.
+export const SUBAGENT_IMPORT_DIRS = [".agents/agents", ".claude/agents"] as const;
+
 export interface KindMeta {
   kind: Kind;
   /** Singular noun, for buttons and prose. */
@@ -77,6 +91,14 @@ export interface KindMeta {
   hint: string;
   /** Path relative to the scope root. */
   file: (name: string) => string;
+  /**
+   * What a run's sandbox writing one of these means (copy-back.ts):
+   * `config` grants or changes what runs and how, `code` is something a
+   * later step executes — neither is ever taken back from a step, which
+   * proposes the change instead — and `data` is what steps legitimately
+   * write. Required, so a new kind cannot become copy-back-able unnoticed.
+   */
+  copyBack: CopyBackClass;
   /** Starting content. */
   template: (name: string, ctx?: TemplateContext) => string;
 }
@@ -105,6 +127,7 @@ const titleCase = (slug: string) => {
 export const KINDS: Record<Kind, KindMeta> = {
   agents: {
     kind: "agents",
+    copyBack: "config",
     one: "agent",
     docType: null,
     docKey: null,
@@ -129,6 +152,7 @@ this text is the whole of the agent's instructions.
 
   evals: {
     kind: "evals",
+    copyBack: "config",
     one: "eval",
     docType: null,
     docKey: null,
@@ -152,6 +176,7 @@ expect:
 
   flows: {
     kind: "flows",
+    copyBack: "config",
     one: "flow",
     docType: null,
     docKey: null,
@@ -171,6 +196,7 @@ trigger: manual
 
   tools: {
     kind: "tools",
+    copyBack: "config",
     one: "tool",
     docType: null,
     docKey: null,
@@ -198,6 +224,7 @@ tools: [${name}]
 
   hooks: {
     kind: "hooks",
+    copyBack: "code",
     one: "hook",
     docType: null,
     docKey: null,
@@ -228,6 +255,7 @@ it reads the event as JSON on stdin and prints one JSON answer —
   // a decision, so the sidebar has no door for it.
   knowledge: {
     kind: "knowledge",
+    copyBack: "data",
     one: "knowledge doc",
     docType: "Reference",
     // OKF's field and OKF's vocabulary — `Reference` is only the starting point.
@@ -250,6 +278,7 @@ The reference content. Agents read this and never rewrite it.
 
   memory: {
     kind: "memory",
+    copyBack: "data",
     one: "memory",
     docType: "Fact",
     // OKF's field and OKF's vocabulary — `Fact` is only the starting point.
@@ -277,6 +306,7 @@ The fact.
 
   skills: {
     kind: "skills",
+    copyBack: "config",
     one: "skill",
     docType: null,
     docKey: null,
@@ -297,6 +327,7 @@ Step-by-step instructions. Bundle code in this folder's scripts/ if it needs any
 
   scripts: {
     kind: "scripts",
+    copyBack: "code",
     one: "script",
     // Code, not a document — no frontmatter to carry either field. A tool
     // file points at it.

package/src/run-container.ts

@@ -29,6 +29,7 @@ import { spawn, spawnSync } from "node:child_process";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { CAPTURE_CAP, isPlatformPath, type ApiSpec, type Effort, type ModelCall } from "./store.ts";
 import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.ts";
+import { refusedBack, refusedLine, keptLine, type RefusedPath } from "./copy-back.ts";
 import type { CallIo, EventExtra, ExecUsage } from "./step-exec.ts";
 import type { TokenPrice } from "./catalog.ts";
 import { isFileValue, fileContent } from "./secrets.ts";
@@ -47,6 +48,9 @@ import { parseBrowserPod, type BrowserPodOutcome } from "./browser-pod.ts";
  *  secrets in headers, assembled prompt, serializable MCP configs. */
 export interface ContainerStepInput {
   agentRel: string; // "agents/<name>" inside the workspace
+  /** A person approved this step before it ran: its file tools may write
+   *  configuration and code inside the sandbox too (FOL-96). */
+  configWrites?: boolean;
   prompt: string;
   model: string;
   effort?: Effort | null;
@@ -229,6 +233,9 @@ export interface ContainerStepOutcome {
    *  applyContainerChanges returned. An isolated sub-agent's reply names
    *  them to the step that delegated (delegate-tools.ts). */
   applied?: string[];
+  /** What the step changed that was not taken back: configuration and code
+   *  (copy-back.ts). On the step record and in the trail. */
+  refused?: RefusedPath[];
 }
 
 /**
@@ -333,6 +340,45 @@ export function hashTree(dir: string): Record<string, string> {
   return out;
 }
 
+/**
+ * Where the host keeps what a sandbox was handed (hashTree), for a driver
+ * that inherits the step: under the run's own folder, which is platform-
+ * owned — never staged into a sandbox, never copied back, erased with the
+ * run (deleteRun). It used to ride into the pod beside the input and be
+ * read back from there, where the step could rewrite it (FOL-96).
+ */
+export function handedInPath(workspaceRoot: string, runId: string, ref: string): string | null {
+  const safe = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/;
+  if (!safe.test(runId) || !safe.test(ref)) return null;
+  return path.join(workspaceRoot, "runs", runId, "sandbox", `${ref}.json`);
+}
+
+/** Note what a sandbox was handed, on the host. */
+export function writeHandedIn(workspaceRoot: string, runId: string, ref: string, hashes: Record<string, string>): void {
+  const file = handedInPath(workspaceRoot, runId, ref);
+  if (!file) return;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(hashes));
+}
+
+/** What the host noted a sandbox was handed, or undefined. */
+export function readHandedIn(workspaceRoot: string, runId: string, ref: string): Record<string, string> | undefined {
+  const file = handedInPath(workspaceRoot, runId, ref);
+  if (!file) return undefined;
+  try {
+    const m = JSON.parse(fs.readFileSync(file, "utf8"));
+    return m && typeof m === "object" && !Array.isArray(m) ? (m as Record<string, string>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Forget it once the step's copy-out is done. */
+export function dropHandedIn(workspaceRoot: string, runId: string, ref: string): void {
+  const file = handedInPath(workspaceRoot, runId, ref);
+  if (file) fs.rmSync(file, { force: true });
+}
+
 /**
  * Every file's mtime under `dir`, relative path to milliseconds — so a copy
  * that cannot carry times can have them put back. `kubectl cp` unpacks with
@@ -412,12 +458,28 @@ export function mergeAppends(was: Buffer | string | null, host: Buffer, next: Bu
   return Buffer.from(h.slice(0, end) + joined + stepAdded, "utf8");
 }
 
+export interface ApplyOptions {
+  /** What the host handed back into this sandbox mid-step — a `sandbox: own`
+   *  job's files (delegate-tools.ts), path → sha256 — as the HOST recorded
+   *  it (StepRecord.handedBack). The sandbox's own note of the same is only
+   *  believed where it agrees with this: a step can write that note. */
+  handedBack?: Record<string, string | string[]>;
+  /** Told of every path the step changed that was not taken back because it
+   *  is configuration or code (copy-back.ts). */
+  onRefused?: (refused: RefusedPath) => void;
+  /** A person approved the step before it ran: configuration and code it
+   *  changed come back, each told to onKept instead of refused. */
+  allowConfig?: boolean;
+  onKept?: (kept: RefusedPath) => void;
+}
+
 export function applyContainerChanges(
   hostWs: string,
   containerWs: string,
   baseline?: string | Record<string, string>,
   note?: (message: string) => void,
   divert?: WriteDivert,
+  opts: ApplyOptions = {},
 ): string[] {
   const applied: string[] = [];
   // Files a sandbox: own job's reply copied into this sandbox mid-step
@@ -425,6 +487,10 @@ export function applyContainerChanges(
   // those, that is what the step started from. The job's change is already on
   // the workspace; read against the older baseline it came back as the
   // step's own and was merged in a second time (Codex review, 23 Oct 2026).
+  // The sandbox notes which it actually wrote (a conflict goes beside the
+  // file instead), but the step can write that note too, so an entry counts
+  // only where the host handed exactly those bytes back (FOL-96).
+  const handedBack = opts.handedBack ?? {};
   let imported: Record<string, string> = {};
   try {
     // Read here, on the host: a link the step planted is never followed,
@@ -433,7 +499,15 @@ export function applyContainerChanges(
     const file = path.join(dir, "copied-back.json");
     if (fs.lstatSync(dir).isDirectory() && fs.lstatSync(file).isFile()) {
       const m = JSON.parse(fs.readFileSync(file, "utf8"));
-      if (m && typeof m === "object" && !Array.isArray(m)) imported = m as Record<string, string>;
+      if (m && typeof m === "object" && !Array.isArray(m)) {
+        for (const [rel, h] of Object.entries(m as Record<string, unknown>)) {
+          // Every version the host handed back for the path counts: two jobs
+          // can return the same file, and the sandbox may hold the first
+          // (the second went beside a parent edit as a conflict copy).
+          const ok = handedBack[rel];
+          if (typeof h === "string" && (Array.isArray(ok) ? ok.includes(h) : ok === h)) imported[rel] = h;
+        }
+      }
     }
   } catch {
     /* none copied back */
@@ -474,6 +548,17 @@ export function applyContainerChanges(
       const target = path.join(hostWs, rel);
       const hostNow = fs.existsSync(target) ? fs.readFileSync(target) : null;
       if (hostNow && hostNow.equals(next)) continue;
+      // Configuration and code are a person's (copy-back.ts): refused here,
+      // after "did the step change it" and before any merge, conflict copy
+      // or test divert — so none of those can carry it to the workspace,
+      // and the next step is staged from the workspace's own copy.
+      const refused = refusedBack(rel);
+      if (refused && opts.allowConfig) {
+        opts.onKept?.({ path: rel.replaceAll("\\", "/"), kind: refused });
+      } else if (refused) {
+        opts.onRefused?.({ path: rel.replaceAll("\\", "/"), kind: refused });
+        continue;
+      }
       // The host moved too since the step was handed its copy — another run
       // or a person wrote it. Writing the step's copy over it erased the
       // other run's ledger rows on 2026-09-14. Merge appends; keep both
@@ -806,6 +891,7 @@ try {
     agentDir,
     workspaceRoot: "/workspace",
     libraryRoot: "/library",
+    configWrites: input.configWrites === true,
     prompt: input.prompt,
     model: input.model,
     effort: input.effort ?? null,
@@ -1491,6 +1577,9 @@ export function heldCores(cpus: string, isolation: string | undefined, available
 
 export interface RunInContainerArgs {
   workspaceRoot: string;
+  /** A person approved this step before it ran: configuration and code it
+   *  changed are kept, not refused (copy-back.ts, FOL-96). */
+  configWrites?: boolean;
   libraryRoot: string;
   /** The platform's gallery, staged under /library BEFORE the account library so the account's copies win. */
   galleryRoot?: string;
@@ -1543,6 +1632,10 @@ export interface RunInContainerArgs {
   /** A test run: where state/ and storage/ changes go instead of the
    *  workspace, and who to tell about each. See test-mode.ts. */
   divert?: WriteDivert;
+  /** What the host handed back into this sandbox mid-step (StepRecord.
+   *  handedBack), read at copy-out — kept on the host, never read back from
+   *  the sandbox alone (FOL-96). */
+  handedBack?: () => Record<string, string | string[]> | undefined;
   /** The run is a test run. An isolated executor labels the sandbox so the
    *  cluster can cut its network down to the egress proxy: a script tool
    *  calls the network directly, not through the proxy where the test-mode
@@ -1912,8 +2005,17 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
     fs.mkdirSync(wsOut);
     const back = spawnSync(cli(), ["cp", `${containerId}:/workspace/.`, wsOut], { encoding: "utf8" });
     let applied: string[] = [];
+    const refused: RefusedPath[] = [];
+    const kept: RefusedPath[] = [];
     if (back.status === 0) {
-      applied = applyContainerChanges(args.workspaceRoot, wsOut, wsIn, (m) => args.emit("error", m), args.divert);
+      applied = applyContainerChanges(args.workspaceRoot, wsOut, wsIn, (m) => args.emit("error", m), args.divert, {
+        handedBack: args.handedBack?.(),
+        onRefused: (r) => refused.push(r),
+        allowConfig: args.configWrites === true,
+        onKept: (r) => kept.push(r),
+      });
+      if (refused.length) args.emit("info", refusedLine(refused));
+      if (kept.length) args.emit("info", keptLine(kept));
     } else {
       args.emit("error", `copy-out failed — the step's file changes were lost:\n${back.stderr.slice(0, 500)}`);
     }
@@ -1927,7 +2029,7 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
       phases,
     };
     args.emit("info", timingLine(timing));
-    return { ...outcome, timing, applied };
+    return { ...outcome, timing, applied, ...(refused.length ? { refused } : {}) };
   } finally {
     if (containerId) spawnSync(cli(), ["rm", "-f", containerId], { stdio: "ignore" });
     fs.rmSync(staging, { recursive: true, force: true });

package/src/runner.ts

@@ -3036,6 +3036,8 @@ async function runStep(
         tenant,
         input: {
           agentRel: path.relative(workspaceRoot, agentDir).replaceAll("\\", "/"),
+          // Its file tools inside the sandbox get the same allowance (FOL-96).
+          configWrites: step.approve === true && Boolean(step.approvedAt),
           prompt,
           model,
           effort,
@@ -3127,6 +3129,11 @@ async function runStep(
         network: { level: network.level, enforced: forward?.enforce === true },
         // A test run's state/ and storage/ changes come out under the run.
         divert: testRun && runId ? divertFor(runId) : undefined,
+        // Read at copy-out: what the host handed back into the sandbox.
+        handedBack: () => step.handedBack,
+        // A person approved this step before it ran: configuration and code
+        // it changes are kept, listed on the trail (FOL-96).
+        configWrites: step.approve === true && Boolean(step.approvedAt),
         test: testRun,
         // Resume: a sandbox a previous driver left running, recorded on the
         // step. Consumed once — a fresh attempt after this one (a retry, a
@@ -3332,6 +3339,11 @@ async function runStep(
       step.image = outcome.image ?? null;
       step.browserPod = outcome.browserPod ? { ...outcome.browserPod } : null;
       if (step.subagentOf && outcome.applied?.length) step.wrote = [...new Set([...(step.wrote ?? []), ...outcome.applied])];
+      if (outcome.refused?.length) {
+        const seen = new Map((step.refused ?? []).map((r) => [r.path, r]));
+        for (const r of outcome.refused) seen.set(r.path, r);
+        step.refused = [...seen.values()];
+      }
       if (outcome.status === "failed" && outcome.browserPod?.lost) {
         const decision = podLossDecision(outcome.browserPod);
         if (decision.rerun) {
@@ -3503,6 +3515,9 @@ async function runStep(
       const attemptInProcess = (modelEnv: Record<string, string | undefined>) => executeStep({
         agentDir,
         workspaceRoot,
+        // A person approved this step (its gate) before it ran: it may change
+        // configuration and code (FOL-96) — the desks' retro applies fixes so.
+        configWrites: step.approve === true && Boolean(step.approvedAt),
         libraryRoot: libraryDir(tenant),
         ...(subagents.length ? { subagents } : {}),
         // The colleagues' inbox, read after every tool call — the same hook
@@ -5241,6 +5256,21 @@ function driveRunInner(
           // Its files go back with the reply, so the delegating step's
           // sandbox has them too (delegate-tools.ts copyBackFiles).
           const back = readCopyBack(pDir, child.wrote ?? []);
+          // What goes back into the parent's sandbox, as the host sends it:
+          // its copy-out reads this, not the sandbox's own note (FOL-96).
+          if (back.files.length) {
+            parent.handedBack = { ...(parent.handedBack ?? {}) };
+            for (const f of back.files) {
+              const h = crypto.createHash("sha256").update(Buffer.from(f.base64, "base64")).digest("hex");
+              // Kept beside any earlier job's for the same path, never over
+              // it: either may be what the sandbox ends up holding.
+              const prev = parent.handedBack[f.path];
+              const all = prev === undefined ? [] : Array.isArray(prev) ? prev : [prev];
+              if (!all.includes(h)) all.push(h);
+              parent.handedBack[f.path] = all.length === 1 ? all[0] : all;
+            }
+            save();
+          }
           return {
             status,
             result: child.result ?? (errors || "(no reply)"),