toolroll 0.9.63 → 0.9.65

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 { mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { poolRootOf } from "./worktree.js";
+import { BRIDGE_DIR } from "./agent-fence.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 { 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, ...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 —
@@ -283,7 +333,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: [], problem: undefined } : runFence(store, runId, spec.provider, options.keyHome, codexHarness ? null : ownTools);
     if (fenceOf.problem !== undefined) {
         tools?.cleanup();
         codexHome?.cleanup();
@@ -291,11 +341,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 +372,69 @@ 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.
+        const serverGrants = () => { const { network: _agentOnly, ...rest } = grants; return rest; };
         if (macosFenceAvailable())
-            serverFence = (file, args) => macosFenced(file, args, fence, grants);
+            serverFence = (file, args) => macosFenced(file, args, fence, serverGrants());
         else if (linuxFenceAvailable())
-            serverFence = (file, args) => linuxFenced(file, args, fence, grants);
+            serverFence = (file, args) => linuxFenced(file, args, fence, serverGrants());
+    }
+    // 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 +451,12 @@ 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 }),
         // 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 +473,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 +504,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 +557,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 +631,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 +666,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 +697,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 +747,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 +776,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 +794,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 +808,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 +821,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 +841,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 +861,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,
@@ -735,6 +929,8 @@ function runFence(store, runId, provider, keyHome, ownTools) {
             // 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 }),
+            // 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")],
         };
     }
     catch (error) {

package/dist/keys.d.ts

@@ -14,13 +14,14 @@
  * being deliberate, wins).
  */
 import type { ProviderId } from "./provider.js";
+import { type KeyedProviderId } from "./acp-agents.js";
 /** The ONE env name each provider's own harness reads its key from —
  * where a managed key is INJECTED. */
-export declare const PROVIDER_KEY_ENV: Record<ProviderId, string>;
+export declare const PROVIDER_KEY_ENV: Record<KeyedProviderId, string>;
 /** EVERY env name a provider reads its OWN key from — what subscription
  * mode STRIPS so an ambient key cannot override the login. gemini reads
  * two; the rest read one. */
-export declare const OWN_KEY_ENV: Record<ProviderId, readonly string[]>;
+export declare const OWN_KEY_ENV: Record<KeyedProviderId, readonly string[]>;
 export declare function keysDir(home?: string): string;
 /**
  * How a provider authenticates (the operator's ruling 2026-08-29: keep
@@ -28,15 +29,18 @@ export declare function keysDir(home?: string): string;
  * — a Claude/ChatGPT plan, a Google cached login — and the API key is
  * kept but NOT handed to the process, so its own auth wins. "api-key"
  * hands the stored (or ambient) key to the process. openrouter has no
- * login and is always api-key.
+ * login and is always api-key. An ACP agent (acp-agents.ts) has neither:
+ * it signs in its own way and Toolroll never holds a key for it —
+ * "agent-login", which says nothing about how it is billed (that is the
+ * agent's billing declaration, per model).
  */
-export type AuthMode = "subscription" | "api-key";
+export type AuthMode = "subscription" | "api-key" | "agent-login";
 /** Providers that CAN authenticate without an API key (a subscription or
  * cached login). openrouter cannot — it is api-key only. */
-export declare const SUBSCRIPTION_CAPABLE: Record<ProviderId, boolean>;
+export declare const SUBSCRIPTION_CAPABLE: Record<KeyedProviderId, boolean>;
 /** The default when nothing is set: subscription where it exists (prefer
  * the plan the operator already pays for), api-key otherwise. */
-export declare const DEFAULT_AUTH_MODE: Record<ProviderId, AuthMode>;
+export declare const DEFAULT_AUTH_MODE: Record<KeyedProviderId, AuthMode>;
 export declare function readAuthMode(provider: ProviderId, home?: string): AuthMode;
 /**
  * The auth mode as an AUTHORITY reads it (raw authority repair): an absent
@@ -52,24 +56,24 @@ export declare function readAuthModeStrict(provider: ProviderId, home?: string):
     ok: false;
     problem: string;
 };
-export declare function setAuthMode(provider: ProviderId, mode: AuthMode, home?: string): {
+export declare function setAuthMode(provider: KeyedProviderId, mode: "subscription" | "api-key", home?: string): {
     ok: true;
 } | {
     ok: false;
     reason: "no-subscription";
 };
-export declare function keyFileFor(provider: ProviderId, home?: string): string;
+export declare function keyFileFor(provider: KeyedProviderId, home?: string): string;
 /** Shape check only — never a validity claim. A key is printable ASCII
  * without whitespace, bounded; anything else is a paste accident. */
 export declare function plausibleKey(value: string): boolean;
-export declare function saveProviderKey(provider: ProviderId, value: string, home?: string): {
+export declare function saveProviderKey(provider: KeyedProviderId, value: string, home?: string): {
     ok: true;
 } | {
     ok: false;
     reason: "implausible";
 };
-export declare function readProviderKey(provider: ProviderId, home?: string): string | null;
-export declare function clearProviderKey(provider: ProviderId, home?: string): boolean;
+export declare function readProviderKey(provider: KeyedProviderId, home?: string): string | null;
+export declare function clearProviderKey(provider: KeyedProviderId, home?: string): boolean;
 /**
  * A live credential check that spends NO tokens: each provider exposes a
  * cheap authenticated GET (its model list, or a key-info route) whose only
@@ -93,12 +97,12 @@ export type KeyVerdict = {
     reason: "unexpected";
     status: number;
 };
-export declare function verifyProviderKey(provider: ProviderId, value: string, fetcher?: typeof fetch, timeoutMs?: number): Promise<KeyVerdict>;
+export declare function verifyProviderKey(provider: KeyedProviderId, value: string, fetcher?: typeof fetch, timeoutMs?: number): Promise<KeyVerdict>;
 /** Words for a verdict, safe to render on any surface (never the key). */
-export declare function verdictWords(provider: ProviderId, verdict: KeyVerdict): string;
+export declare function verdictWords(provider: KeyedProviderId, verdict: KeyVerdict): string;
 /** What a surface may say about a key: that it exists and when it last
  * changed — NEVER the value, never a prefix, never a length. */
-export declare function keyStatus(provider: ProviderId, home?: string): {
+export declare function keyStatus(provider: KeyedProviderId, home?: string): {
     set: boolean;
     updatedAt: string | null;
 };

package/dist/keys.js

@@ -16,6 +16,7 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { isAcpProvider } from "./acp-agents.js";
 import { namedPath } from "./names.js";
 /** The ONE env name each provider's own harness reads its key from —
  * where a managed key is INJECTED. */
@@ -62,6 +63,8 @@ function authModeFileFor(provider, home) {
     return join(keysDir(home), `${provider}.auth`);
 }
 export function readAuthMode(provider, home = homedir()) {
+    if (isAcpProvider(provider))
+        return "agent-login";
     if (!SUBSCRIPTION_CAPABLE[provider])
         return "api-key";
     try {
@@ -80,6 +83,8 @@ export function readAuthMode(provider, home = homedir()) {
  * no subscription login is the key, whatever the file says.
  */
 export function readAuthModeStrict(provider, home = homedir()) {
+    if (isAcpProvider(provider))
+        return { ok: true, mode: "agent-login" };
     if (!SUBSCRIPTION_CAPABLE[provider])
         return { ok: true, mode: "api-key" };
     let raw;

package/dist/lead-capabilities.js

@@ -5,6 +5,7 @@
  * takes the owner there. Everything here reads what is already recorded — runner readiness reports, sign-in pauses,
  * plan-limit readings, tool tests, skill tests, integration checks — and never probes anything that spends.
  */
+import { isAcpProvider } from "./acp-agents.js";
 import { projectBatchChecks } from "./batch-policy.js";
 import { resolveRouteCandidates } from "./agentconfig.js";
 import { authPauseOf, messageCommand, providerName } from "./provider-auth.js";
@@ -60,7 +61,7 @@ function agentsOf(store, repo, now, authMode) {
         // Signed out only on a real sign-in failure: a sign-in pause from a run, the worker's login check saying not logged
         // in, or the key a key-only provider needs missing. A provider on an API key gets the key step, never the sign-in.
         const pause = authPauseOf(store, pair.provider);
-        const mode = pause?.authMode ?? (SUBSCRIPTION_CAPABLE[pair.provider] ? authMode(pair.provider) : "api-key");
+        const mode = pause?.authMode ?? (isAcpProvider(pair.provider) ? "agent-login" : SUBSCRIPTION_CAPABLE[pair.provider] ? authMode(pair.provider) : "api-key");
         const key = mode === "api-key";
         const outWords = key ? "Needs a working API key" : "Signed out";
         const outNext = (detail) => key ? `Save a working API key: run \`${messageCommand({ provider: pair.provider, authMode: "api-key" })}\` on this computer${detail}.` : `Sign in: run \`${messageCommand({ provider: pair.provider, authMode: "subscription" })}\` on this computer${detail}.`;
@@ -198,7 +199,7 @@ export function capabilitiesOf(store, input) {
  * report on a task, attempt or check does (crew work must run), and a timed one does when it is reported on a chat app. */
 const FLOW_WORK = new Set(["create", "edit", "kit", "starter", "add_trigger", "resume_trigger", "add_card"]);
 export function needsCapabilities(name, args, channel) {
-    if (name === "propose_task")
+    if (name === "propose_task" || name === "propose_sweep")
         return true;
     if (name === "propose_flow")
         return FLOW_WORK.has(String(args["operation"]));

package/dist/lead-contract.js

@@ -14,6 +14,7 @@ export const LEAD_CONTRACT = [
     "Before a recommendation or any propose_* on a project with recorded decisions, call search_project_memory for it this turn, in an earlier step than the proposal (the plane refuses the proposal otherwise), and cite the decision ids you rely on.",
     "Before promising work that depends on an agent, a worker, a tool, a skill or an integration, call get_capabilities this turn, in an earlier step than the promise (the plane refuses propose_task, a propose_flow that sets up or starts work, and commit_to otherwise). If what it needs can't work, say so plainly with its next step and open its link with show_control; never promise what it cannot do yet, and never pretend it works. Drafting a flow or confirmation the operator asked for is not a promise (see Flows).",
     "Investigate before reporting a limitation: when a tool refuses or something looks unsupported, read get_capabilities and the relevant skill (get_skills, then that skill's instructions) before telling the owner it can't be done. Then say what you checked, what is missing, and the one next step.",
+    "You start each reply with the everyday tools. Flows, subagents, sweeps, agents and models, project tools and integrations, settings pages, holds and the queue, task actions (retry, stop, merge), images and evidence are found with find_tools: search by what you want to do before saying something can't be done, then call what it finds from your next step.",
     "Ask rarely: only when the answer changes the work and you cannot settle it from tools or project memory. Then use ask_owner: one question, 2-4 short options (Something else is added), shown as buttons after your reply; the tapped option comes back as the owner's next message. Keep your reply to one short line leading into it, and do not repeat the options in your text.",
     "propose_* drafts, never completes. Confirmation and execution approvals still apply. Never request credentials in chat. Read get_task currentExecution before acting; revisions retain task identity and old cards retain exact targets.",
     "The operator talks plainly and names work by what it is about ('the login page', 'that payout fix'), rarely by id. Use the current task when there is one; otherwise find it with list_tasks search, and if several fit, ask which by title. When they want work moved forward, read get_task and draft its next step: changes to a result still waiting on them → propose_review revise; guidance for work in progress → propose_steer; stopped → resume and failed → retry with propose_task_action; waiting for approval, or 'approve X' → offer_approval for exactly that plan or flow card, which sends its own Approve buttons to the owner's chat (their tap approves it; you never do), and only when it says why not, say that in one line and show_control approval; new work, or more on something already completed → propose_task in the same project, naming the earlier task in its goal.",
@@ -24,6 +25,7 @@ export const LEAD_CONTRACT = [
     "For a task's models/risk, read get_agents and answer in its words; for defaults, CLI versions and new models, read get_models; never an agent that is not listed. Changes require renewed approval. Before propose_answer read get_decision in an earlier step, including every option and consequence. Irreversible answers require explicit confirmation; cards retain consequences and recommendations.",
     "For intake, a plain-language outcome is enough to draft a task. Infer title, narrow goal, safe non-goals and testable criteria; leave touches empty for discovery. Do not ask the operator for a title, paths, implementation details, acceptance wording, model, budget or safely inferable fields. Ask at most three questions with defaults (one at a time with ask_owner) for material ambiguity, conflicting goals or unresolved irreversible/public/security/data-loss/migration choices. With 'use your judgment', use reversible defaults; real blockers may still arise.",
     "Set propose_task planning to 'required' for broad, risky or plan-first work, 'skip' for explicitly small direct builds, otherwise 'auto'. report:true investigates without a branch; follow-ups require confirmed proposals.",
+    "Several independent items under one rule set (a bug sweep, a batch of small fixes) are one propose_sweep: the shared rules go in brief, each item is only its own report, one approval starts them all and its table collects their verdicts. Not for a single task, and not for steps that depend on each other.",
     "Tools are MCP servers a project's builds get, and builds get nothing else: read get_project_tools. A service in connectBySigningIn (Stripe, Notion, Linear, Sentry, Jira, Intercom, Attio and more) connects in one click: give the operator its connect link, where they sign in on the service's own page; never tool_add it and never ask for its key. To add another, prefer its commonTools entry (propose_action tool_add with catalog); otherwise use exactly the command or address the operator gives, never a package you are unsure exists. A tool reaches work approved after it was added. Never ask for, accept or repeat a secret's value: name it and open the Tools page with show_control tools.",
     "Your subagents (get_subagents) are named helpers in a project, each with its own personality, instructions and rules (do on its own, ask first, never). When the operator says 'ask Rosa to …' or writes to one by name ('@rosa, …'), delegate with propose_subagent ask in their words; never do its work yourself or speak for it. A flow step can call one by name too.",
     "Flows are a project's process: zones that cards move through, started by triggers and worked by people and your subagents. Read get_flows before answering about them and draft changes with propose_flow (subagents: get_subagents, propose_subagent). Those tools' descriptions say how flows, steps, triggers, cards, subagents, starter flows and kits work. When asked for a flow or a confirmation step, call propose_flow and draft it even if an integration it uses (a chat app, email) isn't set up yet; then say in one line what's missing for it to run and the next step. Say a draft or any tool call failed only when a tool result this turn said so, quoting its words.",

package/dist/lead-doors.d.ts

@@ -9,6 +9,8 @@ export type DoorOutcome = {
     said: string;
     taskId: string | null;
     href?: string;
+    awaiting?: true;
+    already?: true;
 } | {
     ok: false;
     kind: ProposalKind | null;

package/dist/lead-doors.js

@@ -169,6 +169,13 @@ export function confirmLeadProposal(store, who, proposalId, now, options) {
             store.casLeadProposal(proposalId, "confirming", "pending", null, null, now);
             return outcome;
         }
+        // A first yes on protected work is kept, and the card stays pending for the second approver.
+        if (outcome.ok && outcome.awaiting === true) {
+            store.casLeadProposal(proposalId, "confirming", "pending", null, null, now);
+            if (shared)
+                store.handle.prepare('INSERT INTO team_event(lead,conversation,kind,actor,created_at) VALUES(?,?,?,?,?)').run(shared['lead'], shared['id'], 'proposal-changed', who.name, now.toISOString());
+            return outcome;
+        }
         // The recorded outcome names the surface that confirmed — the audit a
         // card shows on every other surface afterwards.
         store.casLeadProposal(proposalId, "confirming", outcome.ok ? "confirmed" : "refused", who.name, { ...outcome, via: options.via }, now);

package/dist/lead-follow.d.ts

@@ -22,3 +22,5 @@ export type LeadFollowInput = {
     fetcher?: typeof fetch;
 };
 export declare function runLeadFollowPass(input: LeadFollowInput): Promise<void>;
+/** How long a burst of one sweep's updates is held so it lands on one page (docs/plans/lead-fan-out.md). */
+export declare const SWEEP_SETTLE_MS: number;