toolroll 0.9.63 → 0.9.67

package/dist/invoke.js

@@ -18,6 +18,8 @@
  */
 import { adapterFor, auditOf, claudePluginEnv, isolationUnsupported, ALL_CREDENTIAL_ENV } from "./provider.js";
 import { readProviderKey, readAuthModeStrict, PROVIDER_KEY_ENV, OWN_KEY_ENV } from "./keys.js";
+import { ACP_AGENTS, isAcpProvider, isKeyedProvider } from "./acp-agents.js";
+import { launchFromJson, verifyLaunch } from "./acp-attest.js";
 import { classifyTerminal } from "./exhaustion.js";
 import { liftAuthPause } from "./provider-auth.js";
 import { attestProvider } from "./attest.js";
@@ -27,11 +29,14 @@ import { witnessedRunner } from "./process-custody.js";
 import { underStopWatch } from "./task-control.js";
 import { childDatabaseEnv, isolatedChildDatabase, removeChildDatabase as removeAgentDatabase } from "./child-database.js";
 import { RunSignInError, noToolsArgs, prepareRunTools } from "./project-tools.js";
-import { readFileSync, realpathSync } from "node:fs";
-import { homedir } from "node:os";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { poolRootOf } from "./worktree.js";
-import { agentFence, CheckoutBindingError, trustedWorktreeBinding, checkoutGitEnv, HARDENED_GIT_ARGS, codexFenceArgv, fenceGrants, fencedGitEnv, linuxFenceAvailable, linuxFenced, macosFenceAvailable, macosFenced, NO_GRANTS, runFolders, taskBoundary } from "./agent-fence.js";
+import { BRIDGE_DIR } from "./agent-fence.js";
+import { agentFence, buildCacheEnv, buildCacheFolder, grantFolder, writeAllowlist, WRITES_DEFAULT, CheckoutBindingError, trustedWorktreeBinding, checkoutGitEnv, HARDENED_GIT_ARGS, codexFenceArgv, fenceGrants, fencedGitEnv, linuxFenceAvailable, linuxFenced, macosFenceAvailable, macosFenced, NO_GRANTS, runFolders, taskBoundary } from "./agent-fence.js";
+import { proxyEnv, providerOnlyNetwork, startEgressProxy } from "./egress.js";
+import { bridgeFits, startEgressBridge } from "./egress-bridge.js";
 import { claudeConfigDir, claudeDefaults, codexDefaults, codexHomeDir, isolatedCodexHome } from "./provider-home.js";
 import { billingOf, claudeBillingFrom, seenBilling } from "./spend.js";
 /** The claude binary name — kept for the legacy quota rows and tests that
@@ -100,13 +105,6 @@ function transportSessionId(id) {
     const normalized = id.trim();
     return normalized === "" ? null : normalized;
 }
-/**
- * Spend money, on the record. Throws — never refuses quietly — when the run
- * is missing, already finished, or recorded against a different provider:
- * a caller that reaches for a harness without a matching open run is a
- * bug, not a case. Attestation and protocol refusals are VALUES (above),
- * not throws — those are cases, and they must dispose cleanly.
- */
 export async function invokeAgent(store, runId, spec, invocation, options) {
     const clock = options.clock ?? (() => new Date());
     if (options.accumulateUsage && (invocation.phase !== "review" || invocation.resumeSession === null)) {
@@ -175,7 +173,8 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // Tier-2 attestation (A2/B3): the authoritative check, immediately
     // before the spawn it authorizes. Tier-1 providers return null here and
     // keep their road byte-identical.
-    const attested = await attestProvider(spec.provider, adapter.binary, options.versionProbe);
+    // An ACP agent is admitted by its own record (acp-attest.ts), read below; the version ranges are for the others.
+    const attested = isAcpProvider(spec.provider) ? null : await attestProvider(spec.provider, adapter.binary, options.versionProbe);
     if (attested !== null && !attested.ok) {
         if (attested.version !== null)
             store.stampProviderVersion(runId, attested.version);
@@ -186,13 +185,61 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             diagnostic: attested.problem,
         };
     }
+    // AN ACP AGENT'S ADMISSION (docs/plans/acp-adapter.md § Admission): a passed conformance check of the exact binary
+    // on this runner, or nothing runs — absence is denial. It builds and repairs only, on a model it offered when it was
+    // checked, and no dollar cap rides it (it can't hold one; the scheduler refuses capped work first, this is the belt).
+    // An ACP spawn is admitted by its agent's attestation on this runner — or, for the conformance check alone, by the
+    // check request that will create it (acpCheck: set only by the check job). The two never stand in for each other.
+    const acpCheckAsk = options.acpCheck ?? null;
+    const acpAttestation = isAcpProvider(spec.provider) && acpCheckAsk === null ? store.acpAttestationFor(spec.provider, run.runner) : null;
+    const acpCheckRequest = isAcpProvider(spec.provider) && acpCheckAsk !== null ? store.acpCheckAdmitting(acpCheckAsk.requestId, acpCheckAsk.step, runId, clock()) : null;
+    const acpCheckLaunch = acpCheckRequest?.launchJson == null ? null : launchFromJson(acpCheckRequest.launchJson);
+    /** The plane's own isolation reading for a check's first step (below, before spawn); null when none was asked. */
+    let acpIsolation = null;
+    /** What starts the agent, and who the handshake must say it is (unknown, for a check: the check learns it). */
+    const acpLaunch = acpAttestation !== null ? acpAttestation.launch : acpCheckLaunch;
+    if (!isAcpProvider(spec.provider) && acpCheckAsk !== null)
+        throw new Error("only an ACP agent is checked");
+    if (isAcpProvider(spec.provider)) {
+        const name = ACP_AGENTS[spec.provider].name;
+        const refuse = (diagnostic) => ({ kind: "refused", reason: "provider-unattested", providerVersion: acpAttestation?.agent.version ?? null, diagnostic });
+        if (acpCheckAsk !== null) {
+            if (acpCheckRequest === null || acpCheckLaunch === null)
+                return refuse(`this check isn't running, has expired, lost its watch, or isn't this step's run`);
+            if (acpCheckRequest.provider !== spec.provider || acpCheckRequest.runner !== run.runner || acpCheckRequest.model !== spec.model || acpCheckRequest.taskRef !== run.taskRef) {
+                return refuse("this run isn't the check's: another agent, runner, model or task");
+            }
+            if (invocation.phase !== "build")
+                return refuse(`${name}'s check runs as a build`);
+        }
+        else {
+            if (acpAttestation === null)
+                return refuse(`${name} isn't checked on ${run.runner} — run \`toolroll agents check ${spec.provider}\` there`);
+            if (invocation.phase !== "build" && invocation.phase !== "repair")
+                return refuse(`${name} builds and repairs only`);
+            if (spec.model === null || !acpAttestation.models.includes(spec.model))
+                return refuse(`${name} didn't offer ${spec.model ?? "a model"} when it was checked — check it again, or choose one it offered`);
+        }
+        if (invocation.maxBudgetUsd !== undefined)
+            return refuse(`${name} can't hold a dollar cap, so it doesn't run capped work (budget-unenforceable)`);
+        // The billing the run was admitted under must be for the model about to be chosen.
+        const stamp = store.acpBillingOfRun(runId);
+        if (stamp !== null && stamp.model !== spec.model)
+            return refuse(`this run was admitted to bill ${stamp.model}, not ${spec.model}`);
+        // And the money moment holds it to the hard monthly budgets as stamped — immutable since admission, so a
+        // declaration changed between a gate and this spawn changes nothing: metered work a budget holds never starts.
+        const billed = stamp?.kind === "plan" ? "subscription" : "api-key";
+        const held = store.budgetGate(clock())({ ...store.budgetSubject(run.taskRef), agents: [{ provider: spec.provider, billing: billed }] });
+        if (held.over !== null)
+            return refuse(`a monthly budget holds metered work, and ${name} on ${spec.model ?? "this model"} is metered here (budget)`);
+    }
     // Auth mode decides how the credential reaches the process (the operator
     // keeps BOTH and prefers the subscription): in "api-key" mode the
     // managed file wins, the ambient env is a real fallback (explicit
     // re-supply survives resolveChildEnv's chat-key strip); in
     // "subscription" mode the key is STRIPPED from the child so the CLI's
     // own login is used — its key is retained, just not handed over.
-    const { runner, clock: _clock, versionProbe: _probe, keyHome, timeoutMs: _hardTimeout, idleTimeoutMs: _idleTimeout, stdin: _callerStdin, accumulateUsage: _accumulateUsage, liveInput: _liveInput, ...runOptions } = options;
+    const { runner, clock: _clock, versionProbe: _probe, keyHome, timeoutMs: _hardTimeout, idleTimeoutMs: _idleTimeout, stdin: _callerStdin, accumulateUsage: _accumulateUsage, liveInput: _liveInput, acpCheck: _acpCheck, network: launchNetwork, writes: launchWrites, ...runOptions } = options;
     // The live setting is read STRICTLY (atomic authority closure): a
     // present mode file that says neither word is a value-shaped refusal
     // before any stamp or process — never the subscription default a
@@ -213,9 +260,12 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         if (problem !== null)
             return { kind: "refused", reason: "auth-mode", providerVersion: attested?.version ?? null, diagnostic: problem };
     }
-    const ownKeyEnv = OWN_KEY_ENV[spec.provider];
-    const managedKey = authMode === "api-key"
-        ? readProviderKey(spec.provider, keyHome) ?? (process.env[PROVIDER_KEY_ENV[spec.provider]] || null)
+    // An ACP agent has no key Toolroll holds or injects: its own and everyone else's are shed (adapter.extraOmitEnv).
+    const keyed = isKeyedProvider(spec.provider) ? spec.provider : null;
+    const ownKeyEnv = keyed === null ? [] : OWN_KEY_ENV[keyed];
+    const keyEnvName = keyed === null ? null : PROVIDER_KEY_ENV[keyed];
+    const managedKey = authMode === "api-key" && keyed !== null && keyEnvName !== null
+        ? readProviderKey(keyed, keyHome) ?? (process.env[keyEnvName] || null)
         : null;
     // Resume XOR mint, enforced at the GATEWAY (Codex gemini verify round 2,
     // finding 3): a resume and a minted start id are mutually exclusive —
@@ -250,12 +300,21 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // The project's tools (v80): exactly its MCP servers, and none of the
     // operator's global or a repository's own, served by this launch's broker
     // (tool-broker.ts), which alone holds their secrets. A review keeps its isolation.
+    // Set once the fence is known: a fenced build's servers never start outside a fence.
+    let serverMustBeFenced = false;
+    // What the build writes (its checkout, its project's caches): a tool server never runs from there, nor reads it at all.
+    const serverUntrusted = workspace === null ? [] : toolUntrusted(store, workspace, keyHome);
     const launchTools = invocation.phase === "review" ? null : await runTools(store, runId, spec, options.keyHome, clock, invocation.readOnlyTools, invocation.researchWithheld, containment, {
         env: { ...process.env, ...(runOptions.env ?? {}) },
         omitEnv: [...(runOptions.omitEnv ?? []), ...ALL_CREDENTIAL_ENV],
         pass: childDatabaseEnv(isolatedDb.file),
-        ...(workspace === null ? {} : { cwd: workspace }),
+        // A tool server starts in a folder the build can't write, and never runs the build's own bytes (arc 2).
+        cwd: keyHome ?? homedir(),
+        untrusted: serverUntrusted,
         wrap: () => serverFence,
+        // A fenced build's tool servers start only in a fence too, unless an instance operator allowed unconfined agents.
+        unwrapped: () => serverMustBeFenced && !store.unfencedAgentsAllowed()
+            ? "This machine can't confine the tool's server (no macOS sandbox, no working bubblewrap), so it was not started." : null,
     });
     if (launchTools !== null && "refused" in launchTools) {
         removeAgentDatabase(isolatedDb.dir);
@@ -283,7 +342,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // tool servers outside its command sandbox, so its own launch folder is
     // fenced too; Claude reads its config from there, inside the sandbox.
     const ownTools = tools?.privateDir === undefined ? null : realpathSync(tools.privateDir);
-    const fenceOf = invocation.phase === "review" ? { fence: [], fileTools: [], grants: NO_GRANTS, problem: undefined } : runFence(store, runId, spec.provider, options.keyHome, codexHarness ? null : ownTools);
+    const fenceOf = invocation.phase === "review" ? { fence: [], fileTools: [], grants: NO_GRANTS, gitPaths: [], cache: undefined, problem: undefined } : runFence(store, runId, spec.provider, options.keyHome, codexHarness ? null : ownTools, launchWrites ?? WRITES_DEFAULT);
     if (fenceOf.problem !== undefined) {
         tools?.cleanup();
         codexHome?.cleanup();
@@ -291,11 +350,26 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         return { kind: "refused", reason: "containment", providerVersion: attested?.version ?? null, diagnostic: fenceOf.problem };
     }
     const fence = [...fenceOf.fence, ...(fenceOf.fence.length > 0 && codexHarness ? [ownTools, codexHome === null ? null : realpathSync(codexHome.dir)].filter((path) => path !== null) : [])];
-    const grants = fenceOf.grants;
+    const grants = { ...fenceOf.grants };
+    // The run's network (egress.ts): sealed by its approval, or the provider's hosts alone, or the caller's own proxy.
+    const network = launchNetwork ?? { policy: providerOnlyNetwork(spec.provider) };
+    // Codex's command sandbox has no proxy (its argv is fixed just below): its commands are online only for a sealed
+    // open network, and offline otherwise.
+    if (fence.length > 0 && codexHarness) {
+        grants.network = "policy" in network && network.policy.mode === "open" ? { mode: "open" }
+            : { mode: "allowlist", proxyPort: 0, brokerPorts: [], loopback: "proxy-only", socketRoots: [] };
+    }
     const inherited = spec.model === null && invocation.phase !== "review" ? inheritedDefaults(spec.provider, { ...process.env, ...(runOptions.env ?? {}) }, keyHome ?? homedir()) : undefined;
     const buildInvocation = { ...resolvedInvocation, ...(tools === null ? {} : { toolArgv: tools.argv, fence, fenceGrants: grants, fileToolFence: fenceOf.fileTools }), ...(workspace === null ? {} : { workspace }), ...(inherited === undefined ? {} : { inherited }) };
     const launchArgv = tools === null ? argv : adapter.argv(buildInvocation);
     const fenced = fenceLaunch(spec.provider, fence);
+    // An ACP agent runs only inside the OS fence: nothing else holds it (it may run commands without asking).
+    if (isAcpProvider(spec.provider) && fenced.method !== "macos-sandbox" && fenced.method !== "linux-bubblewrap") {
+        tools?.cleanup();
+        codexHome?.cleanup();
+        removeAgentDatabase(isolatedDb.dir);
+        return { kind: "refused", reason: "containment", providerVersion: acpAttestation?.agent.version ?? null, diagnostic: `${ACP_AGENTS[spec.provider].name} runs only inside the OS fence (the macOS sandbox or bubblewrap), and this launch has neither (fence-unavailable)` };
+    }
     // The tools were chosen for the fence decided above: a launch that got any other starts nothing.
     // Only a prepared project-tool broker depends on the earlier decision. Empty Claude configs also have a privateDir.
     if (tools?.serverPids !== undefined && fenced.method !== containment.fence) {
@@ -307,10 +381,73 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // A tool server the broker starts is fenced by what this platform supports, whatever the provider: Codex's own
     // profile fences only its agent's commands, and the broker starts servers outside it.
     if (fence.length > 0) {
+        // A tool server keeps its own reach (it holds its tool's secrets, not the agent's code): never the agent's network,
+        // nor its write allowlist (a server keeps its own state where it always has).
+        const serverGrants = () => { const { network: _agentOnly, writes: _agentWrites, ...rest } = grants; return rest; };
+        // Nor read what the build wrote: however its arguments are spelled, no byte of the checkout or caches can load.
+        const serverDenies = [...fence, ...serverUntrusted.filter(path => existsSync(path)).map(path => realpathSync(path))];
         if (macosFenceAvailable())
-            serverFence = (file, args) => macosFenced(file, args, fence, grants);
+            serverFence = (file, args) => macosFenced(file, args, serverDenies, serverGrants());
         else if (linuxFenceAvailable())
-            serverFence = (file, args) => linuxFenced(file, args, fence, grants);
+            serverFence = (file, args) => linuxFenced(file, args, serverDenies, serverGrants());
+        serverMustBeFenced = true;
+    }
+    // No silent fallback (arc 1): a build this machine can't confine at the OS — Claude reduced to its own file-tool
+    // rules, Gemini to nothing — doesn't start unless the instance operator allowed unconfined agents here. An injected
+    // runner (tests) starts no real agent.
+    const unconfined = fence.length > 0 && (fenced.method === "claude-rules" || fenced.method === "none");
+    if (unconfined && runner === undefined && !store.unfencedAgentsAllowed()) {
+        tools?.cleanup();
+        codexHome?.cleanup();
+        removeAgentDatabase(isolatedDb.dir);
+        return { kind: "refused", reason: "containment", providerVersion: attested?.version ?? null,
+            diagnostic: "This machine can't confine an agent (no macOS sandbox, no working bubblewrap), so nothing was started. Install bubblewrap, or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`." };
+    }
+    let egress = null;
+    let bridge = null;
+    let runTemp = null;
+    const confinedOs = fenced.method === "macos-sandbox" || fenced.method === "linux-bubblewrap";
+    if (fence.length > 0 && !codexHarness && confinedOs) {
+        const brokerPorts = tools?.brokerPort === undefined ? [] : [tools.brokerPort];
+        // Unix sockets only under this run's own folders: its checkout, and a temp folder of its own inside its private
+        // launch folder (the system temp folder holds other programs' sockets — editors, agents, password managers).
+        if (ownTools !== null) {
+            runTemp = join(ownTools, "tmp");
+            mkdirSync(runTemp, { recursive: true, mode: 0o700 });
+        }
+        const socketRoots = [...(runTemp === null ? [] : [runTemp]), ...(workspace === null ? [] : [realpathSync(workspace)])];
+        try {
+            if ("via" in network) {
+                const [proxyPort, ...more] = network.via;
+                grants.network = { mode: "allowlist", proxyPort: proxyPort ?? 0, brokerPorts: [...more, ...brokerPorts], loopback: "proxy-only", socketRoots };
+            }
+            else if (network.policy.mode === "open") {
+                grants.network = { mode: "open" };
+            }
+            else {
+                egress = await startEgressProxy({ hosts: network.policy.hosts });
+                grants.network = { mode: "allowlist", proxyPort: egress.port, brokerPorts, loopback: network.policy.loopback, socketRoots };
+            }
+            if (fenced.method === "linux-bubblewrap" && grants.network.mode === "allowlist") {
+                const database = store.databaseFile();
+                // The plane's own fenced folder, unless a socket there would be too long a path (a unix socket's path is capped
+                // near 100 bytes): then the system temp folder, which a confined Linux build doesn't see (its /tmp is its own).
+                const fenced = database === null || database === "" || database === ":memory:" ? undefined : join(dirname(realpathSync(database)), BRIDGE_DIR);
+                bridge = await startEgressBridge([grants.network.proxyPort, ...grants.network.brokerPorts], fenced !== undefined && bridgeFits(fenced) ? fenced : undefined);
+                grants.network.bridge = { folder: realpathSync(bridge.folder), forwarder: realpathSync(bridge.forwarder), node: process.execPath };
+                // Its private /tmp gives back only its own folders: its checkout and its launch folder (its temp is inside).
+                grants.network.keep = [...(workspace === null ? [] : [realpathSync(workspace)]), ...(ownTools === null ? [] : [ownTools]), ...(fenceOf.gitPaths ?? [])];
+            }
+        }
+        catch (error) {
+            await egress?.close();
+            await bridge?.close();
+            tools?.cleanup();
+            codexHome?.cleanup();
+            removeAgentDatabase(isolatedDb.dir);
+            return { kind: "refused", reason: "containment", providerVersion: attested?.version ?? null,
+                diagnostic: `The build's network could not be set up, so nothing was started: ${error instanceof Error ? error.message : String(error)}` };
+        }
     }
     if (invocation.phase !== "review")
         store.recordRunFence(runId, { method: fenced.method, paths: fence.length }, clock());
@@ -327,7 +464,16 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         // A fenced build's git never expires a reflog, so gc never rewrites another task's (agent-fence.ts).
         ...(fence.length > 0 ? fencedGitEnv({ ...process.env, ...(runOptions.env ?? {}) }) : {}),
         ...(codexHome === null ? {} : { CODEX_HOME: codexHome.dir }),
-        ...(managedKey === null ? {} : { [PROVIDER_KEY_ENV[spec.provider]]: managedKey }),
+        ...(managedKey === null || keyEnvName === null ? {} : { [keyEnvName]: managedKey }),
+        // The run's own proxy, in every spelling a program reads (egress.ts): after every other setting, so no caller's
+        // environment points the build around it. A program that ignores them is refused by the OS fence instead.
+        ...(egress === null || !("policy" in network) ? {} : proxyEnv(egress, network.policy.loopback)),
+        // Its own temp folder, where its tools' sockets may live (the only one its fence admits besides its checkout).
+        ...(runTemp === null ? {} : { TMPDIR: runTemp, TMP: runTemp, TEMP: runTemp }),
+        // Claude's own working folder goes there too (it is otherwise the shared /tmp/claude-<uid>).
+        ...(runTemp === null || spec.provider !== "claude" ? {} : { CLAUDE_CODE_TMPDIR: runTemp }),
+        // A workspace build's package managers keep their caches in its project's own folder (arc 2).
+        ...(fenceOf.cache === undefined || grants.writes === undefined ? {} : buildCacheEnv(fenceOf.cache)),
         // This key is deliberately last: no caller may point an agent back at
         // the live control database through a generic RunOptions override.
         ...childDatabaseEnv(isolatedDb.file),
@@ -344,7 +490,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         // must not override the ONE canonical key this mode injected.
         ...(authMode === "subscription"
             ? ownKeyEnv
-            : ownKeyEnv.filter(name => name !== PROVIDER_KEY_ENV[spec.provider])),
+            : ownKeyEnv.filter(name => name !== keyEnvName)),
     ];
     const launchOptions = {
         ...(fenced.wrap.length === 0 ? {} : { fence: fenced.wrap, fenceGrants: grants }),
@@ -375,6 +521,8 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         },
         ...(stdin === undefined ? {} : { stdin }),
         ...(liveInput === null ? {} : { liveInput }),
+        // One ACP conversation: the brief, the sealed model, and who the check says the agent is.
+        ...(acpLaunch === null || spec.model === null ? {} : { acp: { prompt: buildInvocation.brief, model: spec.model, expect: acpAttestation?.agent ?? null, ...(runOptions.acp?.onControl === undefined ? {} : { onControl: runOptions.acp.onControl }), ...(runOptions.acp?.handshakeMs === undefined ? {} : { handshakeMs: runOptions.acp.handshakeMs }) } }),
         ...(hardTimeoutMs === undefined ? {} : { timeoutMs: hardTimeoutMs }),
         ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
         ...(defaultTimeoutMs === undefined ? {} : { timeoutMs: defaultTimeoutMs }),
@@ -426,6 +574,19 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 }
             }
         }
+        // THE CHECK'S ISOLATION, PROVEN BY THE PLANE (docs/plans/acp-adapter.md § Layer E): inside the exact fence and
+        // child environment the agent is about to get, a canary file in the fenced state must be unreadable and a canary
+        // key in the launching environment must be absent. No agent takes part, so no agent can fake it.
+        if (acpCheckAsk?.isolation !== undefined && launchOptions.fence !== undefined && workspace !== null) {
+            // processGroup: run() applies the fence only on the process-group road (a plain execFile carries none).
+            const probe = { cwd: workspace, env: childEnv, omitEnv: childOmitEnv, fence: launchOptions.fence, ...(launchOptions.fenceGrants === undefined ? {} : { fenceGrants: launchOptions.fenceGrants }), timeoutMs: 15_000, processGroup: true };
+            const read = await runCommand("/bin/cat", [acpCheckAsk.isolation.file], probe);
+            const env = await runCommand("/usr/bin/env", [], probe);
+            acpIsolation = {
+                fileDenied: read.code !== 0 && !read.stdout.includes(acpCheckAsk.isolation.fileCanary),
+                envClear: env.code === 0 && !env.stdout.includes(acpCheckAsk.isolation.envValue),
+            };
+        }
         // The stamp precedes the spawn, so a crash between the two leaves a run
         // that claims spend which never happened — the honest direction. A spawn
         // before the stamp would leave spend no record claims, which is the lie
@@ -487,8 +648,32 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 diagnostic: containment.refusal,
             };
         }
+        // The ACP launch re-proved HERE, after every await: each bound file is still the one that passed its check.
+        if (acpCheckAsk !== null && acpCheckRequest !== null && acpCheckLaunch !== null) {
+            // The check request is read again here, after every await: still running, unexpired, owned, this step's run.
+            const still = store.acpCheckAdmitting(acpCheckAsk.requestId, acpCheckAsk.step, runId, clock());
+            if (still === null || still.launchJson !== acpCheckRequest.launchJson) {
+                return { kind: "refused", reason: "provider-unattested", providerVersion: null, diagnostic: "the check stopped admitting this run while it was being set up — nothing was started" };
+            }
+            const verified = verifyLaunch(acpCheckLaunch);
+            if (!verified.ok)
+                return { kind: "refused", reason: "provider-unattested", providerVersion: null, diagnostic: verified.problem };
+        }
+        if (acpAttestation !== null) {
+            // The record is read again here, after every await: a check revoked or replaced during setup starts nothing.
+            const live = store.acpAttestationFor(spec.provider, run.runner);
+            if (live === null || live.id !== acpAttestation.id) {
+                return { kind: "refused", reason: "provider-unattested", providerVersion: acpAttestation.agent.version, diagnostic: `${ACP_AGENTS[spec.provider].name}'s check was revoked or replaced while this run was being set up — nothing was started` };
+            }
+            const verified = verifyLaunch(live.launch);
+            if (!verified.ok) {
+                return { kind: "refused", reason: "provider-unattested", providerVersion: acpAttestation.agent.version, diagnostic: verified.problem };
+            }
+        }
         if (attested !== null)
             store.stampProviderStart(runId, clock(), attested.version);
+        else if (acpAttestation !== null)
+            store.stampProviderStart(runId, clock(), acpAttestation.agent.version);
         else
             store.stampProviderStart(runId, clock());
         // The brief is queued only once the checkout has passed the fence check.
@@ -498,12 +683,26 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         // provider runs, and a stop kills THIS run's process group through the
         // handle registered under its owner tag — the exact-attempt road,
         // never the global sweep. Settlement then reads the same row.
-        result = await underStopWatch(store, runId, () => spawn(attested !== null ? attested.executable : adapter.binary, launchArgv, launchOptions));
+        // An ACP agent starts through its attested launch (the pinned interpreter for a script), never a PATH lookup.
+        result = await underStopWatch(store, runId, () => acpLaunch !== null
+            ? spawn(acpLaunch.file, [...acpLaunch.prefix, ...launchArgv], launchOptions)
+            : spawn(attested !== null ? attested.executable : adapter.binary, launchArgv, launchOptions));
     }
     finally {
         removeAgentDatabase(isolatedDb.dir);
         tools?.cleanup();
         codexHome?.cleanup();
+        // What the run's proxy saw (shown on its result): connections it made and refused. A connection the OS refused
+        // outright never reached it, and isn't counted.
+        if (invocation.phase !== "review" && grants.network !== undefined) {
+            store.recordRunNetwork(runId, {
+                mode: grants.network.mode, phase: "agent",
+                ...("via" in network ? { via: true } : { hosts: network.policy.hosts.length, loopback: network.policy.loopback }),
+                ...(egress === null ? {} : { counts: egress.counts() }),
+            }, clock());
+        }
+        await egress?.close();
+        await bridge?.close();
     }
     // v105: the run's billing, fixed from evidence before its usage is priced: a key it was given is a key; otherwise
     // what the CLI said (Claude's stream) or was last seen doing (Codex's account), and the setting only when neither.
@@ -515,8 +714,11 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     if (spec.provider === "claude" && managedKey === null && authMode === "subscription" && billingSeen.answered && evidence !== null) {
         store.recordProviderBilling("claude", evidence, new Date());
     }
-    store.fixRunBilling(runId, authMode === "api-key" ? "api-key" : evidence ?? billingOf(spec.provider, store.handle), new Date());
+    // An ACP run bills as its admission stamp says (store.acpBillingOfRun): its agent's own plan, or metered.
+    const acpBilling = isAcpProvider(spec.provider) ? (store.acpBillingOfRun(runId)?.kind === "plan" ? "subscription" : "api-key") : null;
+    store.fixRunBilling(runId, acpBilling ?? (authMode === "api-key" ? "api-key" : evidence ?? billingOf(spec.provider, store.handle)), new Date());
     const envelope = adapter.parse(result.stdout);
+    store.stampAgentReportedUsage(runId, envelope.agentReportedUsage ?? null);
     // An installed CLI too old for a build's own setup refuses its flags
     // before it starts: nothing ran, and the run says what to update.
     const unsupported = result.code !== 0 && envelope.initObserved !== true && invocation.phase !== "review" ? isolationUnsupported(spec.provider, result.stderr) : null;
@@ -562,6 +764,8 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         ...(envelope.tokensOut === null ? {} : { tokensOut: envelope.tokensOut + (options.accumulateUsage ? run.tokensOut ?? 0 : 0) }),
         ...(costUsd === null ? {} : { costUsd: costUsd + (options.accumulateUsage ? run.costUsd ?? 0 : 0) }),
         ...(usageJson === null ? {} : { usageJson }),
+        // How many agent turns it took, where the provider reports it (docs/plans/run-efficiency.md); unknown stays NULL.
+        ...(envelope.ending?.turns == null ? {} : { agentTurns: envelope.ending.turns + (options.accumulateUsage ? run.agentTurns ?? 0 : 0) }),
     });
     // How the attempt ended, classified HERE where the structural terminal
     // still exists; a sign-in that no longer works pauses its provider.
@@ -589,6 +793,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             providerVersion: attested === null ? null : attested.version,
             diagnostic: envelope.protocolError,
             finalMessage: envelope.finalMessage,
+            ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
     // The minted-identity proof (A5): once the harness initialized, the id
@@ -606,6 +811,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                 ? "the harness initialized without announcing its session id"
                 : "the harness announced a session id different from the one it was started under",
             finalMessage: envelope.finalMessage,
+            ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
     // An early transport announcement, a pre-existing resume identity, and
@@ -619,6 +825,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             providerVersion: attested === null ? null : attested.version,
             diagnostic: sessionIdentityProblem,
             finalMessage: envelope.finalMessage,
+            ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
     // A provider's explicit failure terminal always wins over its process exit
@@ -631,6 +838,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             providerVersion: attested === null ? null : attested.version,
             diagnostic: "the provider reported a failed terminal despite exiting with code 0",
             finalMessage: envelope.finalMessage,
+            ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
     // The terminal contract (A4): when the audit requires it, a zero exit is
@@ -650,6 +858,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
                     ? "the harness exited 0 without its success terminal — the stream ended mid-protocol"
                     : "the harness exited 0 without ever initializing"),
             finalMessage: envelope.finalMessage,
+            ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
         };
     }
     // A run that worked proves its provider's sign-in works: a sign-in pause
@@ -669,7 +878,9 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             notFound: result.notFound,
             sessionId: envelope.sessionId,
             finalMessage: envelope.finalMessage,
+            ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
             structuredOutput: envelope.structuredOutput ?? null,
+            ...(envelope.acp === undefined ? {} : { acp: { ...envelope.acp, ...(acpIsolation === null ? {} : { isolation: acpIsolation }) } }),
             ending: envelope.ending ?? null,
             usage: {
                 tokensIn: envelope.tokensIn,
@@ -712,7 +923,7 @@ function linkedFor(store, worktree) {
 /** The paths this run's agent may not reach: the state folder around the live database (but not its own worktree),
  * ~/.toolroll (or its older name), its task boundary and other launches' private folders; what the fence gives back
  * (FenceGrants); and what only Claude's file tools refuse. */
-function runFence(store, runId, provider, keyHome, ownTools) {
+function runFence(store, runId, provider, keyHome, ownTools, writes = WRITES_DEFAULT) {
     try {
         // A plane always has a database file; an in-memory store (a test) has nothing to fence.
         const databaseFile = store.databaseFile();
@@ -727,20 +938,128 @@ function runFence(store, runId, provider, keyHome, ownTools) {
         const binding = worktree === null || row === null ? null : trustedWorktreeBinding(row.repo, worktree, poolRoots);
         const boundary = worktree === null ? null : taskBoundary({ worktree, provider, ...home, binding });
         const folders = runFolders(ownTools);
+        // A build with a checkout writes only its workspace unless its approval said anywhere (arc 2): its checkout and
+        // Git data, its launch folder, its project's caches and the provider state its CLI must write.
+        const allowed = worktree === null || row === null || writes !== "workspace" ? null
+            : writeAllowlist({ provider, home: keyHome ?? homedir(), worktree, binding, launchFolder: ownTools, cache: buildCacheFolder(row.repo, keyHome ?? homedir()) });
+        const fence = agentFence({ databaseFile, worktree, ...home, boundary, binding, runFolders: folders, extra: allowed?.deny ?? [] });
+        const grants = fenceGrants({ databaseFile, worktree, boundary, runFolders: folders, linked: linkedFor(store, worktree), binding, ...home, poolRoots });
         return {
-            fence: agentFence({ databaseFile, worktree, ...home, boundary, binding, runFolders: folders }),
+            fence,
             fileTools: boundary?.fileTools ?? [],
             // The shared install is granted only as the plane linked it: this checkout's project and stamped setup.
             // Every plane checkout pool is denied around this one: the plane's own beside the database, and the one this
             // checkout was recorded in (a --pool elsewhere), so another project's worktree, present at launch, is out of reach. Native wrappers also cover later creations.
-            grants: fenceGrants({ databaseFile, worktree, boundary, runFolders: folders, linked: linkedFor(store, worktree), binding, ...home,
-                poolRoots }),
+            grants: allowed === null ? grants : { ...grants, writes: allowed.writes, readOnly: [...new Set([...grants.readOnly, ...allowed.readOnly])].sort() },
+            // The checkout's own Git data, which a private /tmp gives back beside the checkout (agent-fence.ts linuxFenced).
+            gitPaths: binding === null ? [] : [binding.gitdir, join(binding.main, ".git")],
+            ...(allowed === null || row === null ? {} : { cache: buildCacheFolder(row.repo, keyHome ?? homedir()) }),
         };
     }
     catch (error) {
         return { fence: [], fileTools: [], grants: NO_GRANTS, problem: error instanceof CheckoutBindingError ? error.message : "The build fence could not be prepared." };
     }
 }
+/**
+ * A build's setup and check commands, run in its fence (arc 2): the same denies as its agent's (Toolroll's state,
+ * credentials, other projects and runs), its write allowlist when its approval sealed one (its checkout and Git data,
+ * its project's caches, and a temp folder of the command's own), and its package managers pointed at those caches.
+ * Their network stays as it was. A machine without an OS fence runs them as before; a fence that can't be prepared
+ * (a checkout whose binding no longer proves) runs nothing.
+ */
+export function fencedCommands(store, runId, writes, inner, available = () => macosFenceAvailable() || linuxFenceAvailable()) {
+    // An injected runner (tests) starts no real command, as an injected agent starts no real agent (invokeAgent).
+    if (inner !== runCommand)
+        return inner;
+    return async (file, args, options) => {
+        // As a build itself: where nothing can confine them, they run only when an instance operator allowed unconfined agents.
+        if (!available()) {
+            if (store.unfencedAgentsAllowed())
+                return inner(file, args, options);
+            return { code: 1, stdout: "", stderr: "This machine can't confine the build's commands (no macOS sandbox, no working bubblewrap), so they didn't run. Install bubblewrap, or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`.\n", timedOut: false, notFound: false };
+        }
+        const own = realpathSync(mkdtempSync(join(tmpdir(), "so-cmd-")));
+        try {
+            const temp = join(own, "tmp");
+            mkdirSync(temp, { mode: 0o700 });
+            const fenced = runFence(store, runId, "command", undefined, own, writes);
+            if (fenced.problem !== undefined)
+                return { code: 1, stdout: "", stderr: `${fenced.problem}\n`, timedOut: false, notFound: false };
+            if (fenced.fence.length === 0)
+                return inner(file, args, options);
+            // A self-hosted check's own database (child-database.ts) is the command's to write too.
+            const database = options?.env?.["TOOLROLL_DB"];
+            const checkData = database === undefined || fenced.grants.writes === undefined ? null : grantFolder(dirname(database), false);
+            const grants = checkData === null ? fenced.grants : { ...fenced.grants, writes: { ...fenced.grants.writes, subpaths: [...fenced.grants.writes.subpaths, checkData] } };
+            return await inner(file, args, {
+                ...options,
+                fence: fenced.fence,
+                fenceGrants: grants,
+                env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp, ...(fenced.cache === undefined || fenced.grants.writes === undefined ? {} : buildCacheEnv(fenced.cache)) },
+            });
+        }
+        finally {
+            rmSync(own, { recursive: true, force: true });
+        }
+    };
+}
+/**
+ * A project's checks run in a checkout of a result's commit made for them (result-follow-ups.ts, batch-checks.ts), in
+ * the same fence as a build's commands: Toolroll's state, credentials, other projects and runs denied; under the
+ * project's writes setting, only that checkout, its Git data, its own temp folder, the project's caches and its check
+ * database writable. Where nothing can confine them, they run only when an instance operator allowed unconfined agents.
+ */
+export function fencedCheckoutCommands(store, repo, checkout, inner, available = () => macosFenceAvailable() || linuxFenceAvailable()) {
+    if (inner !== runCommand)
+        return inner;
+    return async (file, args, options) => {
+        if (!available()) {
+            if (store.unfencedAgentsAllowed())
+                return inner(file, args, options);
+            return { code: 1, stdout: "", stderr: "This machine can't confine the project's checks (no macOS sandbox, no working bubblewrap), so they didn't run. Install bubblewrap, or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`.\n", timedOut: false, notFound: false };
+        }
+        const databaseFile = store.databaseFile();
+        if (databaseFile === null)
+            return inner(file, args, options);
+        const own = realpathSync(mkdtempSync(join(tmpdir(), "so-cmd-")));
+        try {
+            const temp = join(own, "tmp");
+            mkdirSync(temp, { mode: 0o700 });
+            let binding;
+            try {
+                binding = trustedWorktreeBinding(repo, checkout);
+            }
+            catch {
+                return { code: 1, stdout: "", stderr: "The check's checkout couldn't be bound to its project, so nothing ran.\n", timedOut: false, notFound: false };
+            }
+            const poolRoots = [join(dirname(databaseFile), "worktrees"), ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
+            const boundary = taskBoundary({ worktree: checkout, provider: "command", binding });
+            const folders = runFolders(own);
+            const cache = buildCacheFolder(repo);
+            const allowed = store.projectWrites(repo) !== "workspace" ? null : writeAllowlist({ provider: "command", home: homedir(), worktree: checkout, binding, launchFolder: own, cache });
+            const database = options?.env?.["TOOLROLL_DB"];
+            const checkData = allowed === null || database === undefined ? null : grantFolder(dirname(database), false);
+            const base = fenceGrants({ databaseFile, worktree: checkout, boundary, runFolders: folders, linked: linkedFor(store, checkout), binding, poolRoots });
+            const grants = allowed === null ? base
+                : { ...base, readOnly: [...new Set([...base.readOnly, ...allowed.readOnly])].sort(), writes: { ...allowed.writes, subpaths: [...allowed.writes.subpaths, ...(checkData === null ? [] : [checkData])] } };
+            return await inner(file, args, {
+                ...options,
+                fence: agentFence({ databaseFile, worktree: checkout, boundary, binding, runFolders: folders, extra: allowed?.deny ?? [] }),
+                fenceGrants: grants,
+                env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp, ...(allowed === null ? {} : buildCacheEnv(cache)) },
+            });
+        }
+        finally {
+            rmSync(own, { recursive: true, force: true });
+        }
+    };
+}
+/** What a build writes that a tool server must never run from: its checkout and its project's caches. A checkout with
+ * no record never gets this far: its fence refuses the launch (runFence) before any tool server can start. */
+function toolUntrusted(store, workspace, keyHome) {
+    const row = store.getWorktree(workspace);
+    return [workspace, ...(row === null ? [] : [buildCacheFolder(row.repo, keyHome ?? homedir())])];
+}
 /** The operator's own model choices a build routed with no model keeps (provider-home.ts). */
 function inheritedDefaults(provider, env, home) {
     if (provider === "claude")