@foldrun/core 2.14.3 → 4.0.0

package/dist/src/run-container.js

@@ -25,6 +25,7 @@ import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import { CAPTURE_CAP, isPlatformPath } from "./store.js";
 import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.js";
+import { refusedBack, refusedLine, keptLine } from "./copy-back.js";
 import { isFileValue, fileContent } from "./secrets.js";
 import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET } from "./runtime.js";
 import { egressCaSh } from "./network.js";
@@ -176,6 +177,46 @@ export function hashTree(dir) {
         walk(dir);
     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, runId, ref) {
+    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, runId, ref, hashes) {
+    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, runId, ref) {
+    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 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Forget it once the step's copy-out is done. */
+export function dropHandedIn(workspaceRoot, runId, ref) {
+    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
@@ -258,13 +299,17 @@ export function mergeAppends(was, host, next) {
     const joined = hostAdded && !hostAdded.endsWith("\n") ? hostAdded + "\n" : hostAdded;
     return Buffer.from(h.slice(0, end) + joined + stepAdded, "utf8");
 }
-export function applyContainerChanges(hostWs, containerWs, baseline, note, divert) {
+export function applyContainerChanges(hostWs, containerWs, baseline, note, divert, opts = {}) {
     const applied = [];
     // Files a sandbox: own job's reply copied into this sandbox mid-step
     // (delegate-tools.ts copyBackFiles), path → sha256 of what was written: for
     // 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 = {};
     try {
         // Read here, on the host: a link the step planted is never followed,
@@ -273,8 +318,16 @@ export function applyContainerChanges(hostWs, containerWs, baseline, note, diver
         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;
+            if (m && typeof m === "object" && !Array.isArray(m)) {
+                for (const [rel, h] of Object.entries(m)) {
+                    // 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 {
@@ -322,6 +375,18 @@ export function applyContainerChanges(hostWs, containerWs, baseline, note, diver
             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
@@ -646,6 +711,7 @@ try {
     agentDir,
     workspaceRoot: "/workspace",
     libraryRoot: "/library",
+    configWrites: input.configWrites === true,
     prompt: input.prompt,
     model: input.model,
     effort: input.effort ?? null,
@@ -1643,8 +1709,19 @@ export async function runStepInContainer(args) {
         fs.mkdirSync(wsOut);
         const back = spawnSync(cli(), ["cp", `${containerId}:/workspace/.`, wsOut], { encoding: "utf8" });
         let applied = [];
+        const refused = [];
+        const kept = [];
         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)}`);
@@ -1658,7 +1735,7 @@ export async function runStepInContainer(args) {
             phases,
         };
         args.emit("info", timingLine(timing));
-        return { ...outcome, timing, applied };
+        return { ...outcome, timing, applied, ...(refused.length ? { refused } : {}) };
     }
     finally {
         if (containerId)

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": "4.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/install-tool.ts

@@ -12,7 +12,13 @@
 // pip and npm need no root and run here, as the agent, into a per-step
 // directory already on PATH / PYTHONPATH / NODE_PATH (stepInstallEnv), so the
 // next command finds what this one installed. Inside a run container all of
-// it goes when the container does. Every install is logged with the line to
+// it goes when the container does.
+//
+// No package runs its own code on the way in (FOL-98, 28 Oct 2026): npm
+// installs with --ignore-scripts (no preinstall/postinstall), and pip takes
+// built wheels only (--only-binary :all:) — an sdist's setup.py is code. A
+// package that has no wheel says so, and `runtime: packages:` builds it
+// before the step instead, where the build is declared, cached and seen. Every install is logged with the line to
 // add to the agent's `runtime:` to have it before the step starts next time.
 
 import fs from "node:fs";
@@ -106,26 +112,29 @@ export function buildInstallTool(opts: {
         fs.mkdirSync(target, { recursive: true });
         const uv = findUv();
         const res = uv
-          ? spawnSync(uv, ["pip", "install", "-q", "--python", opts.python, "--target", target, ...names], {
+          ? spawnSync(uv, ["pip", "install", "-q", "--only-binary", ":all:", "--python", opts.python, "--target", target, ...names], {
               env: { ...opts.env, UV_CACHE_DIR: path.join(opts.cacheRoot, ".uv-cache"), UV_LINK_MODE: "copy", UV_NO_PROGRESS: "1" } as unknown as NodeJS.ProcessEnv,
               encoding: "utf8",
               timeout: 600_000,
             })
-          : spawnSync(opts.python, ["-m", "pip", "install", "-q", "--disable-pip-version-check", "--target", target, ...names], {
+          : spawnSync(opts.python, ["-m", "pip", "install", "-q", "--disable-pip-version-check", "--only-binary", ":all:", "--target", target, ...names], {
               env: opts.env as unknown as NodeJS.ProcessEnv,
               encoding: "utf8",
               timeout: 600_000,
             });
         if (res.status !== 0) {
-          const msg = summarizeInstallFailure(uv ? "uv pip install" : "pip install", `${res.stdout ?? ""}${res.stderr ?? ""}${res.error ? res.error.message : ""}`);
+          const raw = `${res.stdout ?? ""}${res.stderr ?? ""}${res.error ? res.error.message : ""}`;
+          const msg = summarizeInstallFailure(uv ? "uv pip install" : "pip install", raw);
           opts.emit("error", `install: pip ${names.join(" ")} — ${msg.split("\n")[0]}`);
-          return text(msg, true);
+          // Wheels only: one that exists only as source is not built here.
+          const noWheel = /no matching distribution|only-binary|no wheels? (?:with|for)|binary.*not available|doesn't have a wheel|has no wheel/i.test(raw);
+          return text(noWheel ? `${msg}\n\nOnly built wheels are installed mid-step — a source package's build runs its own code. Declare it in the agent's runtime: packages: [${names.join(", ")}] to have it built before the step.` : msg, true);
         }
         how = `pip, ${Math.round((Date.now() - t0) / 1000)}s`;
       } else {
         const prefix = path.join(opts.dir, "npm");
         fs.mkdirSync(prefix, { recursive: true });
-        const res = spawnSync("npm", ["install", "--no-fund", "--no-audit", "--no-progress", "--prefix", prefix, ...names], {
+        const res = spawnSync("npm", ["install", "--ignore-scripts", "--no-fund", "--no-audit", "--no-progress", "--prefix", prefix, ...names], {
           env: { ...opts.env, npm_config_cache: path.join(opts.cacheRoot, ".npm-cache") } as unknown as NodeJS.ProcessEnv,
           encoding: "utf8",
           timeout: 600_000,

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.