ac-teams 0.0.6 → 0.0.7

package/README.md

@@ -4,7 +4,7 @@ Persistent agent teams for [Pi](https://github.com/earendil-works/pi): shared ta
 
 ## Install
 
-Requires Linux, Node 22.19 or newer, and an authenticated `pi` executable on `PATH`. Interactive teams also require `tmux` on `PATH`. Tested with Pi 1.4.0.
+Requires Linux, Node 22.19 or newer, and an authenticated `pi` executable on `PATH`. Interactive teams also require `tmux` on `PATH`. Tested with Pi 1.4.0 and 1.5.0.
 
 ```sh
 pi install npm:ac-teams@0.0.4
@@ -34,7 +34,7 @@ Defaults allow up to **10 live members** and **two levels of delegation**. Use t
 
 ## Know the boundaries
 
-- Members share your filesystem access. All members can read all team messages, including direct messages.
+- Members share your filesystem access unless launched with [enforced access](docs/access.md), an opt-in Docker sandbox that needs Docker and a locally built member image. All members can read all team messages, including direct messages.
 - Limits cover only `team_agent`, not other delegation tools. Use separate worktrees for concurrent writers.
 - Stop retains tasks, sessions, and worktrees. Worktree deletion is explicit and requires clean, integrated work.
 - Exit confirmation needs Pi's `session_before_exit` hook, which installed Pi 1.4.0 lacks. Without it, shutdown cleans up but cannot ask first. Signals always bypass confirmation.
@@ -45,6 +45,7 @@ See the [operations guide](docs/operations.md) for recovery guarantees, storage,
 
 - [Usage](docs/usage.md): tool actions, task rules, messages, and companion tools
 - [Operations](docs/operations.md): limits, stop/resume, worktrees, and security
+- [Enforced access](docs/access.md): Docker-enforced read/write grants, outbound proxy and destination policy, and setup
 - [Development](docs/development.md): source setup, verification, and publishing
 - [Implementation history](docs/implementation-plan.md): design decisions and prior art
 

package/docs/access.md

@@ -0,0 +1,99 @@
+# Enforce member access
+
+By default, members are ordinary unsandboxed Pi processes with your full user permissions. Enforced access is opt-in: ac-teams runs the member's whole Pi process, including its shell, extensions, and subprocesses, in a Docker container that sees only the directories you grant. If enforcement is unavailable, the launch fails; ac-teams never falls back to an unsandboxed member.
+
+## Request access
+
+`team_agent` launch accepts `access`:
+
+```json
+{ "action": "launch", "name": "reviewer", "brief": "...", "access": { "read": ["."] } }
+{ "action": "launch", "name": "parser", "brief": "...", "cwd": "/repo/parser", "access": { "read": ["/repo/docs", "/repo/lib"], "write": ["."] } }
+```
+
+- Paths are directories, absolute or relative to the member's `cwd`. Write implies read. The `cwd` must be inside a grant.
+- `network.allow` limits outbound destinations: `host`, or `*.host` for its subdomains, each optionally `:port`; without a port, an entry allows ports 80 and 443. `[]` allows only the model provider. Omit `allow` for any public destination. Omitting `network` keeps the requester's network access; from an unsandboxed requester that is any public destination.
+- Omitting `access` inherits the requesting member's access. From an unsandboxed requester, it launches an unsandboxed member, as before.
+- Members can only narrow access: a sandboxed member cannot grant a path outside its own access, give write where it has read, allow a destination its own allowlist does not, or launch or resume an unsandboxed member. Access is fixed at launch; resume keeps it.
+- Refused grants: `/`, your home directory or its parents, `/tmp`, `/run`, anything under `/proc`, `/dev`, or `/sys`, and anything containing or inside `~/.pi/agent` or `~/.pi/ac-teams`. They would expose host service sockets, credentials, transcripts, or coordinator state.
+- Grants must be canonical paths with no symlinks, and cannot contain commas, which Docker's mount syntax cannot escape.
+- Docker resolves mount paths when a container starts, so a sandboxed writer could swap a granted path for a symlink just before another member starts. ac-teams holds each grant open from before the container is created, and after the container starts, before any member code runs, compares every mounted grant with the directory it holds; any difference removes the container. A writer of `/repo` and a reader of `/repo/src` can therefore run together. Runtime, transcript, and socket mounts are not compared this way, so none may sit strictly inside another live member's writable grant, across all teams. This protects against sandboxed members only; your own processes, Main, and unsandboxed members can change any path and are trusted.
+- Sandboxed members cannot create or clean up worktrees, send user team actions (`/teams` feedback, task requests, resume), or open other members' terminals; use Main.
+
+Before launching, check `sandbox` in `team_agent` `list` or `limits`: `{ "available": true, "backend": "docker" }`, or `available: false` with a `reason`. Every member receives `AC_TEAMS_ACCESS`: `{"enforced":true,"read":[...],"write":[...],"network":{"allow":[...]}}` (no `allow` means any public destination), or `{"enforced":false}`. `team_agent status` reports the coordinator's authoritative `access`.
+
+## Write grants and untrusted output
+
+A write grant lets the member change those live files, including Git metadata such as hooks and config, Pi project resources, and build scripts. Treat the result like any untrusted contribution: review changes before you run them, commit them, or start Git or Pi in those directories. Running changed code later outside the sandbox is your choice, not a sandbox escape.
+
+## What an enforced member can reach
+
+| Resource | Enforced member |
+| --- | --- |
+| Granted directories | Mounted at the same paths, read-only or read-write |
+| Rest of the host filesystem | Not mounted. The container's system files come from the member image |
+| Pi runtime | Read-only: the ac-teams package and these entries from your Pi agent directory: `npm`, `extensions`, `themes`, `skills`, `prompts`, `AGENTS.md`, `keybindings.json`, `acstack.json`, `models-store.json`. They run as trusted code inside the container and are not secret-free by design: the member can read your installed package code and lockfile, custom extension source, and global instructions. Keep secrets out of them. Your real `auth.json`, sessions, and caches are not mounted |
+| Web search settings | A copy of your `web-search.json` (including any search API keys) with the proxy set |
+| Trust decisions | A filtered `trust.json` with only the entries for the member's `cwd` and its parents |
+| Settings | A copy of your Pi `settings.json`, including its package list and device ID, so do not store secrets there |
+| Scratch | Private `/tmp` (512 MiB), home (256 MiB), and Pi agent directory (64 MiB), discarded at exit |
+| Network | Outbound HTTP and HTTPS through the parent's proxy only (below); no direct network |
+| Processes | Private process namespace; host processes are invisible |
+| Team | The coordinator socket for team tools, and the member's own transcript directory |
+| Environment | A fixed minimal set; host variables, including credentials, are not inherited |
+
+Any Unix socket inside a granted directory remains reachable, so grant narrow directories.
+
+Containers run as your user with all capabilities dropped, `no-new-privileges`, a read-only root filesystem, `--network none`, no published ports, no restart policy, no Docker socket, and logging disabled. Before starting a container, ac-teams inspects its effective configuration and refuses to start it on any difference in network, ports, privileges, capabilities, security options, namespaces, devices, mounts, image volumes, user, limits, or restart policy. Docker reports bind sources unresolved, so symlink swaps are caught by re-resolving sources instead. It checks network and ports again after start.
+
+## Outbound access goes through the parent's proxy
+
+Containers have no network interface except loopback. A bridge inside the container exposes a proxy owned by the root Pi process on `127.0.0.1:3128`, and members get `HTTP_PROXY`, `HTTPS_PROXY`, their lowercase forms, `NO_PROXY` for loopback, and `NODE_USE_ENV_PROXY=1`. Pi, Node, curl, and other clients that honour these variables reach the web; ac-teams also points pi-web-access and billion-context at the proxy through their own settings. Clients that ignore proxy settings have no network at all; there is no transparent capture of other protocols.
+
+The proxy:
+
+- Handles HTTPS through `CONNECT` and plain HTTP requests, without following redirects; each new request is checked again
+- Resolves names itself and refuses a destination if any resolved address is not global unicast: loopback, private, CGNAT (including Tailscale), link-local and cloud metadata, documentation, multicast, IPv4-mapped and translated forms, and every address of this host, even public ones. It connects to the address it checked, so DNS cannot change in between
+- Applies the member's `network.allow` list, if any, but always allows the selected model provider's endpoint so Pi can run
+- Is reachable only from that member's container, through its own socket
+- Accepts at most 256 open connections per member, so one member cannot exhaust Main's file descriptors
+
+A destination allowlist does not keep data private: an allowed host, including the model provider, receives whatever the member sends it.
+
+## Model credentials
+
+The member gets an `auth.json` with only its selected provider's current OAuth access token and expiry: no refresh token and no other providers. Main's Pi refreshes the token and rewrites the member's copy when it changes. The member can use, or leak, that token until it expires, and spend your quota with it; it cannot mint new tokens. Switching to another provider inside the member fails, because no other credential is present. A member with a `network.allow` list keeps its provider: its children and its resumes must use the same provider, so the always-allowed provider endpoint cannot widen its network access. The file is removed when the member exits; if Main's Pi is killed, it stays until that team is opened again and its orphans are cleaned up.
+
+Supported: OAuth `anthropic` and `openai` models at their default endpoints, tested with Pi 1.4.0 and 1.5.0. Other providers, API-key credentials, or a changed credential shape fail the launch.
+
+## Resource limits
+
+Each member container is capped at 2 GiB of memory (no swap) and 1024 processes. ac-teams allows at most as many enforced members at once, across all teams on the host, as fit in 75% of host memory at that cap (5 on a 15 GiB host). It counts created and running member containers after creating a new one, so concurrent launches cannot both pass. This bounds the sum of container caps; it does not limit Main, unsandboxed members, or other host processes. CPU is not capped.
+
+A new enforced member takes about 20 seconds to start, because Pi compiles TypeScript extensions into an empty cache.
+
+## Set up Docker
+
+Enforced access needs a running Docker daemon your user can use, and the member image for your Pi version. Using Docker means trusting the Docker daemon, which runs as root; membership in the `docker` group is equivalent to root access on the host.
+
+When the image is missing, `team_agent list` reports the exact build command, for example:
+
+```sh
+docker build -t ac-teams-member:1.5.0-<hash> --build-arg PI_VERSION=1.5.0 -f <ac-teams>/src/sandbox.Dockerfile <ac-teams>/src
+```
+
+The image is `node:22-bookworm-slim`, pinned by digest, with bash, curl, Git, ripgrep, CA certificates, and the same Pi version as Main. Rebuild after upgrading Pi.
+
+## Storage
+
+- Coordinator state and settings: `~/.pi/ac-teams/teams/<team>/`, `~/.pi/ac-teams/config.json`, and `~/.pi/ac-teams/display.json`
+- Generated member configuration (settings copy, provider access token, trust and web search copies, launch file): `~/.pi/ac-teams/agents/<member>/`, removed when the member exits
+- Member transcripts: `<Main's session directory>/ac-teams/<team>/<member>/`, normally under `~/.pi/agent/sessions/<project>/`. Pi's `/resume` lists only top-level sessions, so member transcripts appear in `/teams`, not `/resume`
+
+## Known limits
+
+- Tools outside the mounted runtime, such as the ACStack CLI at `~/.claude/acstack/bin/acstack`, need explicit read grants for their directory and any symlink target. Grant those narrow directories, never `~/.claude`, which holds credentials.
+- Interactive members run in the team's tmux pane through `docker start --attach`, on the container's own terminal.
+- Linux only. [Development](development.md#enforced-access-verification) records what has been verified.
+
+[Back to README](../README.md)

package/docs/development.md

@@ -48,6 +48,24 @@ Terminal UI checks used real native Pi processes in an isolated full-size Herdr
 - Task summary above the input, agent selector below status, native subcommand/name autocomplete, and same-PID/session opening by name or ID
 - Pi-reported model display names and changing context estimates in the live selector
 
+### Enforced access verification
+
+Checks on 2026-11-02, Ubuntu 24.04, kernel 6.8, Docker 29.9.2 (rootful, default AppArmor and seccomp), Pi 1.4.0, member image `ac-teams-member:1.4.0-<hash>`:
+
+- `test/sandbox.test.ts` with real containers for RPC and native (tmux) members: grants enforced read-only and read-write; host files, other transcripts, team state, the real `auth.json`, the Docker socket, and the tmux socket unreachable; only the selected provider's access token is present, without a refresh token, and a token change reaches the container in place; public HTTP and HTTPS work through the proxy with curl and Node; this host's addresses (including its public IP and Tailscale address), the Docker bridge, and cloud metadata are refused; no direct network, UDP, or host Unix socket; the start gate cannot be replayed; no capabilities, `NoNewPrivs`, private PIDs, read-only root, written files owned by the user; nested narrower launch works and escalation is refused; the native member's terminal is the container's own pty, and TIOCSTI did not inject; containers and member credentials are removed on close
+- A grant swapped for a symlink between the checks and start is caught before any member code runs, and the container is removed; a writer of a repo and a reader of its subdirectory run together; resume gets a new gated container
+- A refused second owner leaves live containers alone; after the coordinator is killed, the next owner removes the orphaned container; the enforced-member cap counts other teams' containers
+- A real OpenAI OAuth member with the full installed extension set (billion-context active, ACStack, pi-web-access) answered through the proxy, ran curl (200), `web_search`, and `fetch_content` on a public documentation page; a member with `network.allow: []` still reached the model while curl to a public site failed; no refresh token or other provider in the container; network `none`, no ports, and no host listener changes
+
+Anthropic, later on 2026-11-02 (Pi 1.4.0 for the first two checks; Pi 1.5.0 with member image `ac-teams-member:1.5.0-<hash>` for the third and for a full `npm test` rerun, 118 pass):
+
+- A `claude-haiku-4-5` member with the full installed extension set ran curl (200), `web_search`, and `fetch_content`; with `network.allow: []` it still reached the model while curl failed; no refresh token or other provider in the container; network `none`, no ports
+- A real Pi Main loading this branch from an isolated agent directory (access tokens only, no refresh tokens) launched an enforced Anthropic member with `network.allow: []` through Main's own credential code: the sandbox was available, the launch succeeded, and the member answered `curl=000`; no host listener changes and no leftover containers or member files
+
+On the final tree with Pi 1.5.0, the OpenAI full-extension and `network.allow: []` runs passed again: curl 200, `web_search` and `fetch_content` ok, then curl `000` with the model still reachable. `npm test` passed 119 tests, and the Docker suite passed 10.
+
+Not verified: an Anthropic Main session, because Main's own Anthropic request was refused as out of extra usage while the member's Haiku requests succeeded.
+
 Not verified on macOS, Windows, or network filesystems. The package is Linux-only because safe process identity uses `/proc`. No web dashboard, workflow DSL, daemon, or automatic merging is included.
 
 ## Stage releases for npm approval

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operate ac-teams
 
-ac-teams runs on Linux with Node 22.19 or newer and an authenticated `pi` executable on `PATH`. Interactive roots also require `tmux`: each team owns a private server and native member terminals. Headless roots retain RPC members. Both share your OS user's access, not a sandbox.
+ac-teams runs on Linux with Node 22.19 or newer and an authenticated `pi` executable on `PATH`. Interactive roots also require `tmux`: each team owns a private server and native member terminals. Headless roots retain RPC members. Both share your OS user's access unless a member is launched with [enforced access](access.md).
 
 ## Save project trust before launching
 
@@ -15,7 +15,7 @@ Default: at most **10 live descendants**, counting starting, busy, idle, and sto
 Root policy precedence, from lowest to highest:
 
 1. Built-in defaults
-2. `~/.acstack/ac-teams/config.json`
+2. `~/.pi/ac-teams/config.json`
 3. `.pi/ac-teams.json`, only with `--teams-project-config`
 4. Explicit `--teams-limit` and `--teams-depth` flags
 
@@ -33,7 +33,7 @@ Other delegation tools remain outside these limits. See [companion tools](usage.
 
 ## Display preferences are global
 
-`/teams config` saves task-summary and agent-selector visibility to `~/.acstack/ac-teams/display.json`:
+`/teams config` saves task-summary and agent-selector visibility to `~/.pi/ac-teams/display.json`:
 
 ```json
 {"tasks":true,"agents":true}
@@ -75,10 +75,10 @@ Missing targets, dirty work, and uncertain/squashed integration retain the tree.
 
 ## Local records contain sensitive project data
 
-Each root session uses `~/.acstack/ac-teams/teams/<session-id>/`:
+Each root session uses `~/.pi/ac-teams/teams/<session-id>/`:
 
 - `state.json` contains membership, policy, tasks, messages, claims, and notification cursors
-- `sessions/` contains native Pi-managed member transcripts
+- Member transcripts live under Main's session directory in `ac-teams/<team>/<member>/`, normally `~/.pi/agent/sessions/<project>/ac-teams/...`; Pi's `/resume` lists only top-level sessions, so use `/teams` to find them
 - `owner.lock` and `coordinator.sock` coordinate the running root
 - Interactive teams also own `t.sock`, the private tmux socket, and per-member terminal environment files; shutdown removes those files
 

package/docs/usage.md

@@ -133,6 +133,6 @@ Messages survive crashes; exactly-once delivery or model execution does not. Avo
 
 ac-teams works alone. ACStack adds planning, review, and shipping skills; Herdr adds terminal tabs, panes, and visible root sessions. These are companion capabilities, not automatic integrations. ac-teams does not open a Herdr pane for each member. Interactive members use a team-private tmux server and open in the current terminal when selected; headless roots use RPC members.
 
-Other delegation tools can coexist. ac-teams warns when `Agent`, `SubagentWorkflow`, or `subagent` is active, but does not disable them. Its limits cover only members launched through `team_agent`. Use Pi's resource settings to disable other launchers if you want one team authority. Shell access and same-user extensions are not sandboxed.
+Other delegation tools can coexist. ac-teams warns when `Agent`, `SubagentWorkflow`, or `subagent` is active, but does not disable them. Its limits cover only members launched through `team_agent`. Use Pi's resource settings to disable other launchers if you want one team authority. Shell access and same-user extensions are not sandboxed unless a member is launched with [enforced access](access.md).
 
 [Back to README](../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-teams",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Small, persistent teams for Pi",
   "type": "module",
   "license": "MIT",

package/src/access.ts

@@ -0,0 +1,175 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir, totalmem } from "node:os";
+import { stateRoot } from "./config.ts";
+import { assertNetworkNarrower, validatePolicy, type NetworkPolicy } from "./egress.ts";
+import { dirname, join, resolve } from "node:path";
+
+/** Canonical directory grants; write implies read. Undefined access means an unsandboxed member. */
+export interface Access { read: string[]; write: string[]; network: NetworkPolicy }
+export interface AccessRequest { read?: string[]; write?: string[]; network?: NetworkPolicy }
+export interface SandboxStatus { available: boolean; backend: "docker"; reason?: string }
+
+export const within = (path: string, root: string) => path === root || path.startsWith(root === "/" ? "/" : root + "/");
+const inside = (path: string, roots: string[]) => roots.some(root => within(path, root));
+export const readable = (access: Access, path: string) => inside(path, [...access.read, ...access.write]);
+export const writable = (access: Access, path: string) => inside(path, access.write);
+
+/** Pi's agent directory and ac-teams state hold credentials, transcripts, and coordinator tokens. */
+export const privateRoots = () => [resolve(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent")), stateRoot()];
+
+export function resolveAccess(request: AccessRequest, base: string): Access {
+  const canonical = (paths: string[] = []) => [...new Set(paths.map(path => {
+    let real: string;
+    try { real = realpathSync(resolve(base, path)); } catch { throw new Error(`Access path does not exist: ${path}`); }
+    if (!statSync(real).isDirectory()) throw new Error(`Access path must be a directory: ${path}`);
+    // A symlink in the path would be re-resolved by Docker at start; a sandboxed writer could have planted or could swap it.
+    if (real !== resolve(base, path)) throw new Error(`Access paths must be canonical, without symlinks: ${path} resolves to ${real}`);
+    // Docker's --mount syntax has no escaping, so a comma would inject mount options.
+    if (/[,\n]/.test(real)) throw new Error(`Access paths cannot contain commas or newlines: ${real}`);
+    // These would replace the sandbox's private /proc, /dev, /tmp, or home, or expose host sockets and credentials.
+    for (const unsafe of ["/proc", "/dev", "/sys", "/run"]) if (within(real, unsafe)) throw new Error(`Access to ${real} is not allowed`);
+    for (const covered of ["/tmp", "/run", "/var/run", homedir()]) if (within(covered, real)) throw new Error(`Access to ${real} would expose ${covered}; grant a narrower directory`);
+    for (const root of privateRoots()) if (within(real, root) || within(root, real)) throw new Error(`Access to ${real} would expose private Pi or ac-teams state in ${root}`);
+    return real;
+  }))].sort();
+  const write = canonical(request.write);
+  return { read: canonical(request.read).filter(path => !inside(path, write)), write, network: validatePolicy(request.network ?? {}) };
+}
+
+/** Throws unless child grants are the same as or narrower than the actor's; an unsandboxed actor may grant anything. */
+export function assertNarrower(actor: Access | undefined, child: Access | undefined): void {
+  if (!actor) return;
+  if (!child) throw new Error("A sandboxed member cannot launch or resume an unsandboxed member");
+  for (const path of child.write) if (!writable(actor, path)) throw new Error(`Write access to ${path} exceeds the requesting member's access`);
+  for (const path of child.read) if (!readable(actor, path)) throw new Error(`Read access to ${path} exceeds the requesting member's access`);
+  assertNetworkNarrower(actor.network, child.network);
+}
+
+/** Host paths a member mounts, and the subset it can write. */
+export interface MountSet { sources: string[]; writes: string[] }
+/** Grants are identity-checked at start, so only a member's other mounts count as sources; its writable grants are its writes. */
+export const mountSet = (mounts: { source: string; rw: boolean }[], grants: string[]): MountSet => ({
+  sources: mounts.filter(mount => !grants.includes(mount.source)).map(mount => mount.source),
+  writes: mounts.filter(mount => mount.rw && grants.includes(mount.source)).map(mount => mount.source) });
+/**
+ * Docker resolves bind sources when a container starts. A sandboxed writer can replace any entry strictly below its
+ * writable directory, so no member may mount a path strictly inside another live member's writable directory, in either
+ * direction. Equal paths are safe: a writer cannot replace its own mount point. A member's own non-grant mounts (runtime,
+ * bridge) must not sit inside its own writable directory either, or it could swap them before its next start.
+ */
+export function assertStableGrants(mine: MountSet, others: MountSet[]): void {
+  const below = (set: MountSet, writer: MountSet) => set.sources.find(path => writer.writes.some(root => path !== root && within(path, root)));
+  for (const other of [...others, mine]) {
+    const path = below(mine, other) ?? below(other, mine);
+    if (path) throw new Error(`Mount ${path} lies strictly inside a sandboxed member's writable directory; grant that directory or a path outside it`);
+  }
+}
+
+/** Pi agent-directory entries members need: installed packages, extensions, themes, skills, prompts, and settings Pi reads at startup. */
+export const agentRuntime = ["npm", "extensions", "themes", "skills", "prompts", "AGENTS.md", "keybindings.json", "acstack.json", "models-store.json"];
+export const generatedAgentFiles = ["settings.json", "auth.json", "trust.json", "web-search.json"];
+
+export function packageRoot(file: string): string {
+  for (let dir = dirname(realpathSync(file)); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    if (dir === dirname(dir)) throw new Error(`No package root for ${file}`);
+  }
+}
+
+// Container memory caps; the aggregate guard keeps the sum of caps within 75% of host RAM.
+// shortcut: fixed per-member cap, add a setting if real workloads need more.
+export const memberMemory = 2 * 1024 ** 3;
+export const memberPids = 1024;
+export const maxSandboxed = () => Math.max(1, Math.floor(totalmem() * 0.75 / memberMemory));
+
+const dockerfile = new URL("./sandbox.Dockerfile", import.meta.url);
+/** Image tag tied to the host Pi version and this Dockerfile, so members run the same Pi as Main. */
+export function memberImage(piVersion: string): { tag: string; build: string } {
+  const hash = createHash("sha256").update(readFileSync(dockerfile)).digest("hex").slice(0, 12);
+  const tag = `ac-teams-member:${piVersion}-${hash}`, file = dockerfile.pathname;
+  return { tag, build: `docker build -t ${tag} --build-arg PI_VERSION=${piVersion} -f ${file} ${dirname(file)}` };
+}
+
+export function sandboxStatus(image: { tag: string; build: string }, docker = "docker"): SandboxStatus {
+  const status = (reason?: string): SandboxStatus => ({ available: !reason, backend: "docker", ...(reason ? { reason } : {}) });
+  if (process.platform !== "linux") return status("Enforced access requires Linux");
+  const probe = spawnSync(docker, ["image", "inspect", "--format", "{{json .Config.Volumes}}", image.tag], { encoding: "utf8", timeout: 10000 });
+  if (probe.error) return status(`Docker is unavailable: ${probe.error.message}`);
+  if (probe.status !== 0) return status(/No such image/i.test(probe.stderr) ? `Member image ${image.tag} is missing; build it with: ${image.build}` : `Docker cannot be used: ${probe.stderr.trim().slice(0, 300)}`);
+  if (!["null", "{}"].includes(probe.stdout.trim())) return status(`Member image ${image.tag} declares volumes; rebuild it from the shipped Dockerfile`);
+  return status();
+}
+
+export interface SandboxPlan {
+  name: string; labels: Record<string, string>; image: string; access: Access; cwd: string; home: string; terminal: boolean;
+  agentDir: string; configDir: string; sessionDir: string; coordinatorSocket: string; egressSocket: string;
+  runtime: string[]; launch: string; bridge: string;
+}
+export interface Mount { source: string; target: string; readonly: boolean }
+/** Every host path a member container sees. Nothing else on the host is mounted. */
+export function sandboxMounts(plan: SandboxPlan): Mount[] {
+  const mounts: Mount[] = [
+    ...plan.access.read.map(path => ({ source: path, target: path, readonly: true })),
+    ...plan.access.write.map(path => ({ source: path, target: path, readonly: false })),
+    // Runtime code stays read-only even inside a writable grant, because unsandboxed processes load it too.
+    ...plan.runtime.map(path => ({ source: path, target: path, readonly: true })),
+    ...agentRuntime.map(name => join(plan.agentDir, name)).filter(path => existsSync(path)).map(path => ({ source: path, target: path, readonly: true })),
+    ...generatedAgentFiles.map(name => ({ source: join(plan.configDir, name), target: join(plan.agentDir, name), readonly: true })),
+    { source: plan.launch, target: plan.launch, readonly: true },
+    { source: plan.sessionDir, target: plan.sessionDir, readonly: false },
+    { source: plan.coordinatorSocket, target: plan.coordinatorSocket, readonly: false },
+    { source: plan.egressSocket, target: plan.egressSocket, readonly: false },
+  ];
+  return mounts;
+}
+
+export function dockerCreateArgs(plan: SandboxPlan): string[] {
+  const uid = process.getuid!(), gid = process.getgid!();
+  const args = ["create", "--name", plan.name, "--interactive", ...(plan.terminal ? ["--tty"] : []), "--init",
+    "--network", "none", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--read-only", "--restart", "no",
+    "--user", `${uid}:${gid}`, "--memory", String(memberMemory), "--memory-swap", String(memberMemory), "--pids-limit", String(memberPids),
+    "--log-driver", "none", "--hostname", "ac-teams",
+    "--tmpfs", "/tmp:rw,nosuid,nodev,size=512m", "--tmpfs", `${plan.home}:rw,nosuid,nodev,size=256m,uid=${uid},gid=${gid},mode=0700`,
+    // Pi writes lock files and caches in its agent directory; this private scratch copy hides the real one.
+    "--tmpfs", `${plan.agentDir}:rw,nosuid,nodev,size=64m,uid=${uid},gid=${gid},mode=0700`];
+  for (const [key, value] of Object.entries(plan.labels)) args.push("--label", `${key}=${value}`);
+  // Other coordinators use this to tell grants (identity-checked at start) from runtime mounts.
+  args.push("--label", `ac-teams.grants=${JSON.stringify([...plan.access.read, ...plan.access.write])}`);
+  for (const mount of sandboxMounts(plan)) args.push("--mount", `type=bind,source=${mount.source},target=${mount.target}${mount.readonly ? ",readonly" : ""}`);
+  args.push("--env", "PATH=/usr/local/bin:/usr/bin:/bin", "--env", `HOME=${plan.home}`, "--env", "TMPDIR=/tmp",
+    "--workdir", plan.cwd, plan.image, "node", plan.bridge, plan.launch);
+  return args;
+}
+
+/** Checks docker inspect output against the policy; any problem means the container must not start. */
+export function containerProblems(inspect: any, plan: SandboxPlan, started = false): string[] {
+  const problems: string[] = [], host = inspect?.HostConfig ?? {}, config = inspect?.Config ?? {};
+  const expect = (ok: boolean, problem: string) => { if (!ok) problems.push(problem); };
+  expect(host.NetworkMode === "none", `network mode ${host.NetworkMode}`);
+  expect(!Object.keys(host.PortBindings ?? {}).length && !host.PublishAllPorts && !Object.keys(config.ExposedPorts ?? {}).length, "ports are published or exposed");
+  expect(host.Privileged === false, "privileged");
+  expect(JSON.stringify(host.CapDrop) === '["ALL"]' && !(host.CapAdd ?? []).length, "capabilities are not all dropped");
+  const security: string[] = host.SecurityOpt ?? [];
+  expect(security.length > 0 && security.every(option => /^no-new-privileges(:true)?$/.test(option)), "security options differ from no-new-privileges");
+  expect(host.ReadonlyRootfs === true, "root filesystem is writable");
+  expect(["no", ""].includes(host.RestartPolicy?.Name ?? ""), "restart policy is set");
+  expect(host.LogConfig?.Type === "none", "container logging is enabled");
+  expect(!host.PidMode && ["", "private"].includes(host.IpcMode ?? "") && !host.UTSMode && !host.UsernsMode && !host.CgroupnsMode?.startsWith?.("host"), "host namespaces are shared");
+  expect(!(host.Devices ?? []).length && !(host.DeviceRequests ?? []).length && !(host.GroupAdd ?? []).length && !(host.VolumesFrom ?? []).length, "devices, groups, or volumes-from are added");
+  expect(host.Memory === memberMemory && host.PidsLimit === memberPids, "resource limits are missing");
+  expect(config.User === `${process.getuid!()}:${process.getgid!()}`, `user ${config.User}`);
+  expect(!Object.keys(config.Volumes ?? {}).length, "the image declares volumes");
+  const allowed = new Map(sandboxMounts(plan).map(mount => [mount.target, mount]));
+  const mounts: any[] = inspect?.Mounts ?? [];
+  expect(mounts.length === allowed.size, `expected ${allowed.size} mounts, found ${mounts.length}`);
+  for (const mount of mounts) {
+    const wanted = allowed.get(mount.Destination);
+    expect(mount.Type === "bind" && !!wanted && mount.Source === wanted.source && mount.RW === !wanted.readonly, `unexpected mount ${mount.Type} ${mount.Source} -> ${mount.Destination}`);
+    expect(!/docker\.sock$/.test(mount.Source ?? ""), "the Docker socket is mounted");
+  }
+  expect(JSON.stringify(Object.keys(host.Tmpfs ?? {}).sort()) === JSON.stringify(["/tmp", plan.home, plan.agentDir].sort()), "unexpected tmpfs mounts");
+  if (started) expect(inspect?.NetworkSettings && !Object.keys(inspect.NetworkSettings.Ports ?? {}).length, "ports are bound after start");
+  return problems;
+}

package/src/config.ts

@@ -6,7 +6,9 @@ import { isRecord } from "./connection.ts";
 
 export interface DisplaySettings { tasks: boolean; agents: boolean }
 export const defaultDisplaySettings: DisplaySettings = { tasks: true, agents: true };
-const displayPath = () => join(homedir(), ".acstack", "ac-teams", "display.json");
+/** ac-teams state outside Pi's agent directory: settings, team stores, and generated member configuration. */
+export const stateRoot = () => join(homedir(), ".pi", "ac-teams");
+const displayPath = () => join(stateRoot(), "display.json");
 
 export function readDisplaySettings(): DisplaySettings {
   let value: unknown;
@@ -32,7 +34,7 @@ export function saveDisplaySettings(value: DisplaySettings): void {
 
 export function policy(cwd: string, trusted: boolean, flags: { limit?: string; depth?: string }) {
   let config: Record<string, unknown> = { limit: 10, depth: 2 };
-  const files = [join(homedir(), ".acstack", "ac-teams", "config.json")];
+  const files = [join(stateRoot(), "config.json")];
   if (trusted) files.push(join(cwd, ".pi", "ac-teams.json"));
   for (const file of files) {
     let value: unknown;

package/src/coordinator.ts

@@ -1,8 +1,15 @@
 import { createServer, type Server, type Socket } from "node:net";
-import { chmodSync, mkdirSync, realpathSync, statSync, unlinkSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { chmodSync, closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, lstatSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertNarrower, assertStableGrants, mountSet, within, containerProblems, dockerCreateArgs, sandboxMounts, maxSandboxed, memberImage, packageRoot, readable, resolveAccess, sandboxStatus, type Access, type SandboxPlan, type SandboxStatus } from "./access.ts";
+import { Egress, egressPort, providerRoutes, type Credentials } from "./egress.ts";
 import { Store, processAlive, processIdentity } from "./store.ts";
+import { stateRoot } from "./config.ts";
 import { RpcAgent } from "./rpc-agent.ts";
 import { TerminalAgent, tmux } from "./terminal-agent.ts";
 import { authentic, isRecord, readLines, send } from "./connection.ts";
@@ -30,6 +37,16 @@ export interface CoordinatorOptions {
   id: string; cwd: string; sessionFile?: string; limit: number; depth: number;
   extension: string; home?: string; command?: string;
   interactive?: boolean; model?: string; thinking?: string;
+  /** Version of the running Pi; members use the image built for it. Defaults to the `pi` on PATH. */
+  piVersion?: string;
+  /** Test hook: provider token refresh interval (default one minute). */
+  refreshMs?: number;
+  /** Test hook: runs after a member container passes all checks and before it starts. */
+  beforeStart?: (member: string) => Promise<void>;
+  /** Main's session directory; member transcripts live under <it>/ac-teams/<team>/<member>. */
+  sessionDir?: string;
+  /** Parent-side provider credentials for sandboxed members; without it enforced access is unavailable. */
+  credentials?: Credentials;
   notice: (through: number, messages: Message[]) => void;
   warning: (message: string) => void;
   status?: (kind: "busy" | "blocked", active: boolean) => void;
@@ -49,6 +66,11 @@ export class Coordinator {
   private closed = false;
   private status = { busy: false, blocked: false };
   private closePromise?: Promise<void>;
+  private sandboxes = new Map<string, { egress: Egress; grants: { path: string; fd: number; dev: number; ino: number }[]; release: (go: boolean) => void; refresh: NodeJS.Timeout; token: string }>();
+  private plans = new Map<string, SandboxPlan>();
+  private releasing = new Map<string, Promise<void>>();
+  private sessionDirs = new Map<string, string>();
+  private sandbox?: { status: SandboxStatus; at: number };
 
   private options: CoordinatorOptions;
   private constructor(options: CoordinatorOptions) {
@@ -83,6 +105,13 @@ export class Coordinator {
           if (member.id !== "root" && isLive(member)) member.status = "interrupted";
         }
       });
+      // Owner lock held and no member process alive: containers left by a killed coordinator are orphans of this store.
+      for (const member of Object.values(coordinator.store.state.members)) if (member.access) {
+        const name = coordinator.containerName(member.id);
+        const owner = await docker(["inspect", "--format", '{{index .Config.Labels "ac-teams.store"}}', name]).catch(() => "");
+        if (owner.trim() === coordinator.store.dir) await docker(["rm", "-f", name]).catch(error => options.warning(`Cannot remove orphaned member container ${name}: ${String(error)}`));
+        rmSync(memberConfigDir(member.id), { recursive: true, force: true });
+      }
       try { unlinkSync(coordinator.socketPath); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
       coordinator.server = createServer(socket => coordinator.accept(socket));
       await new Promise<void>((done, fail) => {
@@ -124,6 +153,9 @@ export class Coordinator {
           if (previous && previous !== socket && !previous.destroyed) throw new Error("Member already connected");
           const args = value.args;
           if (!isRecord(args) || typeof args.sessionId !== "string" || typeof args.sessionFile !== "string" || !Array.isArray(args.tools) || !["team_agent", "team_task", "team_message"].every(name => Array.isArray(args.tools) && args.tools.includes(name))) throw new Error("Incomplete ac-teams readiness handshake");
+          // The session file chooses a host mount on resume, so it must stay in the directory ac-teams assigned.
+          const assigned = this.sessionDirs.get(member.id) ?? this.memberSessionDir(member.id);
+          if (!assigned || !within(resolve(args.sessionFile as string), assigned)) throw new Error("Member session file is outside its assigned directory");
           if (args.trusted !== true) throw new Error("Pi skipped protected project resources. Approve the member cwd with Pi's /trust command before retrying; ac-teams never auto-approves a project.");
           this.store.update(state => {
             state.members[member.id].sessionId = args.sessionId as string;
@@ -240,6 +272,16 @@ export class Coordinator {
     const { token: _token, identity: _identity, ...view } = member;
     return view;
   }
+  sandboxStatus(): SandboxStatus {
+    if (!this.options.credentials) return { available: false, backend: "docker", reason: "This Pi root cannot broker provider credentials" };
+    // Cache success; recheck failures so a fixed host is noticed without restarting.
+    if (!this.sandbox || (!this.sandbox.status.available && Date.now() - this.sandbox.at > 30000)) {
+      let status: SandboxStatus;
+      try { status = sandboxStatus(this.image()); } catch (error) { status = { available: false, backend: "docker", reason: String(error) }; }
+      this.sandbox = { status, at: Date.now() };
+    }
+    return this.sandbox.status;
+  }
   live(): Member[] { return Object.values(this.store.state.members).filter(member => member.id !== "root" && isLive(member)); }
   ack(id: string, through: number): void {
     const last = this.store.state.messages.at(-1)?.seq ?? 0;
@@ -267,7 +309,11 @@ export class Coordinator {
     if (!member || !isLive(member)) throw new Error("Member is not active");
     validate(operation, args);
     if (operation === "event") return this.recordEvent(actor, args);
-    if (operation === "ui") return this.userAction(actor, args as UserAction);
+    if (operation === "ui") {
+      // User actions can resume any member as Main, so sandboxed members cannot send them.
+      if (member.access) throw new Error("Sandboxed members cannot send user team actions; use Main");
+      return this.userAction(actor, args as UserAction);
+    }
     if (operation === "task") return this.store.task(actor, args as TaskArgs);
     if (operation === "message") {
       const result = this.store.message(actor, args as MessageArgs);
@@ -278,12 +324,12 @@ export class Coordinator {
   }
   private async agent(actor: string, args: AgentArgs, authorizedLimit: boolean): Promise<unknown> {
     const state = this.store.state;
-    if (args.action === "list") return { team: state.id, limit: state.limit, depth: state.depth, lastMessage: state.messages.at(-1)?.seq ?? 0, members: Object.values(state.members).map(member => this.publicMember(member)) };
+    if (args.action === "list") return { team: state.id, limit: state.limit, depth: state.depth, sandbox: this.sandboxStatus(), lastMessage: state.messages.at(-1)?.seq ?? 0, members: Object.values(state.members).map(member => this.publicMember(member)) };
     if (args.action === "limits") {
       if (actor !== "root") throw new Error("Only the root can change team limits");
       if ((args.limit ?? state.limit) > 10 && !authorizedLimit) throw new Error("A ceiling above 10 requires explicit user confirmation or --teams-limit");
       this.store.update(next => { next.limit = args.limit ?? next.limit; next.depth = args.depth ?? next.depth; });
-      return { limit: this.store.state.limit, depth: this.store.state.depth };
+      return { limit: this.store.state.limit, depth: this.store.state.depth, sandbox: this.sandboxStatus() };
     }
     if (args.action === "launch" || args.action === "resume") {
       const launch = this.launch(actor, args);
@@ -295,6 +341,7 @@ export class Coordinator {
     if (args.action === "status") return this.publicMember(member);
     if (member.id === "root" || !isDescendant(state, member.id, actor)) throw new Error("Only a member's ancestor can stop or clean it up");
     if (args.action === "cleanup") {
+      if (state.members[actor].access) throw new Error("Sandboxed members cannot remove worktrees");
       if (isLive(member)) throw new Error("Stop the member before worktree cleanup");
       if (!member.worktree) throw new Error("Member has no worktree");
       if (this.cleaning.has(member.id)) throw new Error("Member cleanup is already running");
@@ -326,7 +373,22 @@ export class Coordinator {
     const id = resumed?.id ?? randomUUID().slice(0, 16);
     const cwd = realpathSync(resolve(args.cwd ?? resumed?.cwd ?? parent.cwd));
     if (!statSync(cwd).isDirectory()) throw new Error("Agent cwd must be a directory");
-    const member: Member = resumed ? { ...resumed, token: randomUUID(), status: "starting", error: undefined, contextUsage: undefined, modelName: undefined } : { id, name: args.name, parent: actor, depth, token: randomUUID(), cwd, status: "starting", notified: 0 };
+    // An access request without a network policy keeps the requester's; only an unsandboxed requester's default is public.
+    const access = resumed ? resumed.access : args.access ? resolveAccess({ ...args.access, network: args.access.network ?? parent.access?.network }, cwd) : parent.access;
+    assertNarrower(parent.access, access);
+    if (access) {
+      if (!readable(access, cwd)) throw new Error("The member cwd must be inside its granted directories");
+      if (args.worktree) throw new Error("Worktrees cannot be combined with enforced access");
+      // Container memory caps must stay within host RAM in total; unsandboxed members are not limited.
+      if (this.live().filter(other => other.access && other.id !== resumed?.id).length >= maxSandboxed()) throw new Error(`At most ${maxSandboxed()} enforced members can run at once on this host`);
+      const status = this.sandboxStatus();
+      if (!status.available) throw new Error(`Enforced access is unavailable: ${status.reason}`);
+    }
+    // The provider endpoint bypasses the allowlist, so a restricted member keeps its provider and its children inherit it.
+    const provider = args.model.slice(0, args.model.indexOf("/"));
+    const locked = resumed ? resumed.provider : parent.access?.network.allow ? parent.provider : undefined;
+    if (access?.network.allow && locked && provider !== locked) throw new Error(`A member with restricted network access can only use ${locked} models`);
+    const member: Member = resumed ? { ...resumed, token: randomUUID(), status: "starting", error: undefined, contextUsage: undefined, modelName: undefined } : { id, name: args.name, parent: actor, depth, token: randomUUID(), cwd, status: "starting", notified: 0, access, provider: access ? provider : undefined };
     // Reserve synchronously before the first await so concurrent launches cannot oversubscribe.
     this.store.update(next => { next.members[id] = member; });
     this.publishStatus();
@@ -344,16 +406,23 @@ export class Coordinator {
       if (this.closed || this.store.state.members[id].status !== "starting") throw new Error("Launch was stopped before startup");
       const readiness = new Promise<void>((done, fail) => {
         this.ready.set(id, { resolve: done, reject: fail });
-        timer = setTimeout(() => fail(new Error("ac-teams child readiness timed out")), 20000);
+        // Enforced members start with an empty compile cache, so Pi recompiles TypeScript extensions (about 20 s here).
+        timer = setTimeout(() => fail(new Error("ac-teams child readiness timed out")), access ? 90000 : 20000);
       });
       // Attach immediately: a spawn error must not leave a rejected readiness promise unobserved.
       void readiness.catch(() => {});
       const slash = args.model.indexOf("/");
-      mkdirSync(join(this.store.dir, "sessions"), { recursive: true, mode: 0o700 });
-      chmodSync(join(this.store.dir, "sessions"), 0o700);
-      const rpcArgs = [...(this.options.interactive ? [] : ["--mode", "rpc"]), "--session-dir", join(this.store.dir, "sessions"), "-e", this.options.extension, "--provider", args.model.slice(0, slash), "--model", args.model.slice(slash + 1), "--thinking", args.thinking ?? "off"];
+      const modelId = args.model.slice(slash + 1);
+      // Each member gets its own transcript directory, so a sandboxed member cannot read or alter others.
+      const sessions = resumed?.sessionFile ? dirname(resumed.sessionFile) : this.memberSessionDir(id);
+      mkdirSync(sessions, { recursive: true, mode: 0o700 });
+      this.sessionDirs.set(id, sessions);
+      const rpcArgs = [...(this.options.interactive ? [] : ["--mode", "rpc"]), "--session-dir", sessions, "-e", this.options.extension, "--provider", provider, "--model", modelId, "--thinking", args.thinking ?? "off"];
       if (resumed?.sessionFile) rpcArgs.push("--session", resumed.sessionFile);
-      const spawnOptions = { cwd: member.cwd, args: rpcArgs, command: this.options.command, env: { ...process.env, HERDR_ENV: "0", AC_TEAMS_SOCKET: this.socketPath, AC_TEAMS_MEMBER: id, AC_TEAMS_TOKEN: member.token, AC_TEAMS_TERMINAL_SOCKET: join(this.store.dir, "t.sock") } };
+      const identity = { HERDR_ENV: "0", AC_TEAMS_SOCKET: this.socketPath, AC_TEAMS_MEMBER: id, AC_TEAMS_TOKEN: member.token, AC_TEAMS_ACCESS: JSON.stringify(access ? { enforced: true, ...access } : { enforced: false }) };
+      const spawnOptions = access
+        ? await this.sandboxed(id, access, member.cwd, provider, modelId, rpcArgs, identity, sessions)
+        : { cwd: member.cwd, args: rpcArgs, command: this.options.command, env: { ...process.env, ...identity, AC_TEAMS_TERMINAL_SOCKET: join(this.store.dir, "t.sock") } };
       agent = this.options.interactive
         ? new TerminalAgent({ ...spawnOptions, id, dir: this.store.dir, request: (type, fields, timeout) => this.control(id, type, fields, timeout) })
         : new RpcAgent(spawnOptions);
@@ -371,6 +440,10 @@ export class Coordinator {
       });
       agent.once("exit", () => {
         this.agents.delete(id);
+        // Tracked so close() waits for container removal.
+        const release = this.releaseSandbox(id).catch(error => this.options.warning(String(error)));
+        this.operations.add(release); this.releasing.set(id, release);
+        void release.finally(() => { this.operations.delete(release); if (this.releasing.get(id) === release) this.releasing.delete(id); });
         if (this.closed) return;
         this.store.update(next => { next.members[id].status = next.members[id].status === "stopping" ? "stopped" : "interrupted"; delete next.members[id].needsInput; });
         this.publishStatus();
@@ -380,6 +453,7 @@ export class Coordinator {
       member.pid = agent.process.pid;
       member.identity = member.pid ? processIdentity(member.pid) : undefined;
       this.store.update(next => { next.members[id].pid = member.pid; next.members[id].identity = member.identity; });
+      if (access) await this.releaseMember(id);
       try {
         await Promise.race([readiness, agent.exited.then(() => { throw new Error("Child exited before readiness"); })]);
       } finally { if (timer) clearTimeout(timer); this.ready.delete(id); }
@@ -393,11 +467,143 @@ export class Coordinator {
     } catch (error) {
       clearTimeout(timer); this.ready.delete(id);
       if (agent) await agent.stop();
+      // The exit handler may already own the container removal; wait for it so a failed launch leaves nothing running.
+      await this.releaseSandbox(id); await this.releasing.get(id);
       this.store.update(next => { next.members[id].status = "interrupted"; delete next.members[id].needsInput; next.members[id].error = error instanceof Error ? error.message : "Startup failed"; });
       this.publishStatus();
       throw error;
     }
   }
+  private image() {
+    return memberImage(this.options.piVersion ?? JSON.parse(readFileSync(join(packageRoot(command("pi")), "package.json"), "utf8")).version);
+  }
+  /** Transcript root: Main's session directory, without any ac-teams nesting if Main itself resumed a member transcript. */
+  private memberSessionDir(id: string): string {
+    const root = resolve(this.options.sessionDir ?? join(this.store.dir, "sessions")).replace(/\/ac-teams\/[^/]+\/[^/]+$/, "");
+    return join(root, "ac-teams", this.store.state.id, id);
+  }
+  private containerName(id: string): string { return `ac-teams-${this.store.state.id}-${id}`; }
+  /** Prepares a member container whose only outside channels are the coordinator socket and this member's egress proxy. */
+  private async sandboxed(id: string, access: Access, cwd: string, provider: string, model: string, args: string[], identity: Record<string, string>, sessionDir: string) {
+    const credentials = this.options.credentials, route = providerRoutes[provider];
+    if (!credentials || !route) throw new Error(`Enforced access supports only ${Object.keys(providerRoutes).join("/")} models with Main's Pi login`);
+    const first = await credentials(provider, model); // Fails closed for unsupported providers before anything starts.
+    // A resume reuses the member ID, so the previous run's cleanup must finish before its files are recreated.
+    await this.releasing.get(id);
+    const home = homedir(), agentDir = resolve(process.env.PI_CODING_AGENT_DIR ?? join(home, ".pi", "agent"));
+    const dir = memberConfigDir(id);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const read = (name: string) => { try { return JSON.parse(readFileSync(join(agentDir, name), "utf8")) as Record<string, unknown>; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return {}; throw error; } };
+    const write = (name: string, value: unknown) => writeFileSync(join(dir, name), JSON.stringify(value, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+    // WebSocket clients may ignore proxy settings, so pin the SSE transport.
+    write("settings.json", { ...read("settings.json"), transport: "sse" });
+    // Only the selected provider's current access token: no refresh token and no other providers. The parent refreshes it.
+    const auth = (credential: { token: string; expires: number }) => ({ [provider]: { type: "oauth", access: credential.token, refresh: "", expires: credential.expires } });
+    write("auth.json", auth(first));
+    // Only trust decisions for the member's cwd and its ancestors; the full file lists every trusted project.
+    write("trust.json", Object.fromEntries(Object.entries(read("trust.json")).filter(([path]) => cwd === path || cwd.startsWith(path.endsWith("/") ? path : path + "/"))));
+    // pi-web-access ignores proxy environment variables but honours its own proxy setting. The container has no DNS,
+    // so it must leave address checks to the proxy, which refuses private and host addresses itself.
+    const proxy = `http://127.0.0.1:${egressPort}`, search = read("web-search.json");
+    write("web-search.json", { ...search, proxy, ssrf: { ...(search.ssrf as object | undefined), trustEnvProxy: true } });
+    // The image's Pi runs members; a test command is mounted from its own package instead.
+    const custom = this.options.command ?? process.env.AC_TEAMS_PI;
+    const pi = custom ? command(custom) : "pi";
+    const env: Record<string, string> = { PATH: "/usr/local/bin:/usr/bin:/bin", HOME: home, TMPDIR: "/tmp", PI_CODING_AGENT_DIR: agentDir, PI_SKIP_VERSION_CHECK: "1", PI_TELEMETRY: "0", ...identity,
+      HTTP_PROXY: proxy, HTTPS_PROXY: proxy, http_proxy: proxy, https_proxy: proxy, NO_PROXY: "localhost,127.0.0.1,::1", no_proxy: "localhost,127.0.0.1,::1", NODE_USE_ENV_PROXY: "1",
+      // billion-context's spawned proxy reads its own upstream setting rather than the inherited environment.
+      BILI_UPSTREAM_PROXY: proxy };
+    for (const key of ["USER", "LANG", "LC_ALL", "TERM", "COLORTERM"]) if (process.env[key]) env[key] = process.env[key]!;
+    const launch = join(dir, "launch.json");
+    // The bridge waits on this before running any member code; it opens only after the mounts are verified.
+    let release!: (go: boolean) => void;
+    const gate = new Promise<boolean>(resolve => { release = resolve; });
+    const egress = await Egress.open(join(this.store.dir, `e-${id}.sock`), access.network, { host: new URL(route.baseUrl).hostname, port: 443 }, gate);
+    // Rewrites in place (same inode), because the file is bind-mounted; the member never sees the refresh token.
+    const refresh = setInterval(() => void credentials(provider, model).then(next => {
+      const current = this.sandboxes.get(id);
+      if (current && next.token !== current.token) { writeFileSync(join(dir, "auth.json"), JSON.stringify(auth(next), null, 2) + "\n"); current.token = next.token; }
+    }, () => this.options.warning(`Member ${id}: provider credential refresh failed`)), this.options.refreshMs ?? 60000);
+    refresh.unref();
+    const entry = { egress, grants: [] as { path: string; fd: number; dev: number; ino: number }[], release, refresh, token: first.token };
+    this.sandboxes.set(id, entry);
+    // Registered first so releaseSandbox closes the proxy if this fails. The coordinator token travels in this private file, never in container configuration that docker inspect shows.
+    write("launch.json", { socket: egress.socket, port: egressPort, command: pi, args, env });
+    // Hold each grant open so the started container's mounts can be compared with exactly these directories.
+    for (const path of [...access.read, ...access.write]) {
+      const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+      entry.grants.push({ path, fd, ...(({ dev, ino }) => ({ dev, ino }))(fstatSync(fd)) });
+      if (readlinkSync(`/proc/self/fd/${fd}`) !== path) throw new Error(`Grant ${path} changed while opening`);
+    }
+    const plan: SandboxPlan = {
+      name: this.containerName(id), labels: { "ac-teams.team": this.store.state.id, "ac-teams.member": id, "ac-teams.store": this.store.dir },
+      image: this.image().tag, access, cwd, home, terminal: this.options.interactive === true, agentDir, configDir: dir, sessionDir,
+      coordinatorSocket: this.socketPath, egressSocket: egress.socket, launch,
+      runtime: [...new Set([packageRoot(this.options.extension), packageRoot(fileURLToPath(import.meta.url)), ...(custom ? [packageRoot(pi)] : [])])],
+      bridge: fileURLToPath(new URL("./sandbox-bridge.mjs", import.meta.url)),
+    };
+    this.plans.set(id, plan);
+    await docker(["rm", "-f", plan.name]).catch(() => {});
+    const created = (await docker(dockerCreateArgs(plan))).trim();
+    // Register first, then check. Grants are identity-checked at start, but runtime, transcript, and socket mounts are
+    // not, so none may sit strictly inside another live member's writable grant, and no writable grant may strictly
+    // contain another member's such mounts, across all teams.
+    const others = (await docker(["ps", "-aq", "--no-trunc", "--filter", "label=ac-teams.member", ...["created", "running", "paused", "restarting"].flatMap(state => ["--filter", `status=${state}`])])).trim().split("\n").filter(other => other && other !== created);
+    const sets = others.length ? (JSON.parse(await docker(["inspect", ...others])) as { Mounts?: { Type: string; Source: string; RW: boolean }[]; Config: { Labels?: Record<string, string> } }[])
+      .map(container => mountSet((container.Mounts ?? []).filter(mount => mount.Type === "bind").map(mount => ({ source: mount.Source, rw: mount.RW })), JSON.parse(container.Config.Labels?.["ac-teams.grants"] ?? "[]"))) : [];
+    assertStableGrants(mountSet(sandboxMounts(plan).map(mount => ({ source: mount.source, rw: !mount.readonly })), [...access.read, ...access.write]), sets);
+    // Admission across every coordinator on this host: count after creating, so concurrent launches cannot both slip under the cap.
+    const admitted = (await docker(["ps", "-aq", "--filter", "label=ac-teams.member", "--filter", "status=created", "--filter", "status=running"])).trim().split("\n").filter(Boolean).length;
+    if (admitted > maxSandboxed()) throw new Error(`At most ${maxSandboxed()} enforced members can run at once on this host`);
+    await this.verifyContainer(id, false);
+    await this.options.beforeStart?.(id);
+    return { cwd, command: "docker", args: ["start", "--attach", "--interactive", plan.name], env: { ...process.env } };
+  }
+  /** Refuses to run a container whose effective configuration differs from the policy. */
+  private async verifyContainer(id: string, started: boolean): Promise<void> {
+    const plan = this.plans.get(id)!;
+    const [inspect] = JSON.parse(await docker(["inspect", plan.name]));
+    const problems = containerProblems(inspect, plan, started);
+    if (problems.length) throw new Error(`Member container failed policy checks: ${problems.join("; ")}`);
+  }
+  /**
+   * After start, before any member code runs: each grant mounted in the container must be the directory held open
+   * before creation. Docker resolves bind sources at start, so this is what pins grants against symlink swaps.
+   */
+  private async releaseMember(id: string): Promise<void> {
+    const sandbox = this.sandboxes.get(id)!, plan = this.plans.get(id)!;
+    try {
+      let pid = 0;
+      for (const end = Date.now() + 30000; !pid; await new Promise(done => setTimeout(done, 100))) {
+        if (Date.now() > end) throw new Error("Member container did not start");
+        const [inspect] = JSON.parse(await docker(["inspect", plan.name]));
+        if (inspect?.State?.Running) pid = inspect.State.Pid;
+        else if (inspect?.State?.Status === "exited") throw new Error("Member container exited before release");
+      }
+      await this.verifyContainer(id, true);
+      for (const grant of sandbox.grants) {
+        const mounted = lstatSync(`/proc/${pid}/root${grant.path}`);
+        if (mounted.dev !== grant.dev || mounted.ino !== grant.ino) throw new Error(`Grant ${grant.path} is not the directory that was checked`);
+      }
+      sandbox.release(true);
+    } catch (error) { sandbox.release(false); throw error; }
+    finally { for (const grant of sandbox.grants) closeSync(grant.fd); sandbox.grants = []; }
+  }
+  private async releaseSandbox(id: string): Promise<void> {
+    const sandbox = this.sandboxes.get(id), plan = this.plans.get(id);
+    this.sandboxes.delete(id); this.plans.delete(id);
+    if (sandbox) {
+      sandbox.release(false); clearInterval(sandbox.refresh);
+      // releaseMember may still hold this entry; emptying the list keeps it from closing reused descriptors.
+      for (const grant of sandbox.grants) closeSync(grant.fd);
+      sandbox.grants = [];
+    }
+    if (plan) await docker(["rm", "-f", plan.name]).catch(error => this.options.warning(`Cannot remove member container ${plan.name}: ${String(error)}`));
+    await sandbox?.egress.close();
+    // The member's files hold its coordinator token and provider access token.
+    rmSync(memberConfigDir(id), { recursive: true, force: true });
+  }
   private async stopDescendants(id: string): Promise<void> {
     const descendants = this.live().filter(member => isDescendant(this.store.state, member.id, id)).sort((a, b) => b.depth - a.depth);
     for (const member of descendants) await this.stopOne(member.id);
@@ -408,7 +614,8 @@ export class Coordinator {
     this.store.update(next => { next.members[id].status = "stopping"; delete next.members[id].needsInput; });
     this.publishStatus();
     const agent = this.agents.get(id);
-    if (agent) await agent.stop();
+    // A stopped member's container and credential files are gone before stop returns.
+    if (agent) { await agent.stop(); await this.releasing.get(id); }
     else if (member.pid && processAlive(member.pid, member.identity)) throw new Error("No owned transport for live process; refusing to kill by PID");
     this.store.update(next => { next.members[id].status = "stopped"; });
   }
@@ -423,6 +630,7 @@ export class Coordinator {
     for (const socket of this.connections) socket.destroy();
     if (this.server) await new Promise<void>(done => this.server!.close(() => done()));
     try { unlinkSync(this.socketPath); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    for (const id of [...this.sandboxes.keys()]) await this.releaseSandbox(id);
     for (const pending of this.controls.values()) { clearTimeout(pending.timer); pending.reject(new Error("Team stopped")); }
     this.controls.clear();
     if (this.options.interactive) {
@@ -433,3 +641,18 @@ export class Coordinator {
     this.store.close();
   }
 }
+
+const memberConfigDir = (id: string) => join(stateRoot(), "agents", id);
+
+function command(name: string): string {
+  if (name.includes("/")) return realpathSync(name);
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (dir && existsSync(join(dir, name))) return realpathSync(join(dir, name));
+  }
+  throw new Error(`Cannot find ${name} on PATH`);
+}
+
+const execFileAsync = promisify(execFile);
+async function docker(args: string[]): Promise<string> {
+  return (await execFileAsync("docker", args, { timeout: 30000, maxBuffer: 4 * 1024 * 1024 })).stdout;
+}

package/src/egress.ts

@@ -0,0 +1,187 @@
+import { createServer, request as httpRequest, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { BlockList, connect, isIP, type Socket } from "node:net";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { chmodSync, unlinkSync } from "node:fs";
+import { networkInterfaces } from "node:os";
+
+/**
+ * Outbound policy for a sandboxed member. `allow` undefined means any public destination; otherwise only matching
+ * destinations. The member's model provider is always reachable so Pi can run; that endpoint still receives whatever
+ * the member sends it.
+ */
+export interface NetworkPolicy { allow?: string[] }
+export const egressPort = 3128;
+// Each tunnel holds two descriptors in the parent (Main's Pi), so one member cannot exhaust them.
+export const maxEgressConnections = 256;
+
+// Entries: "host", "*.host" (subdomains only), each optionally ":port". Without a port, an entry allows 80 and 443.
+const entryPattern = /^(\*\.)?([a-z0-9-]+(?:\.[a-z0-9-]+)+)(?::(\d{1,5}))?$/;
+function parseEntry(entry: string) {
+  const match = entryPattern.exec(entry.toLowerCase());
+  const port = match?.[3] === undefined ? undefined : Number(match[3]);
+  if (!match || (port !== undefined && (port < 1 || port > 65535))) throw new Error(`Invalid network allow entry: ${entry}`);
+  return { wildcard: !!match[1], host: match[2], ports: port === undefined ? [80, 443] : [port] };
+}
+export function validatePolicy(policy: NetworkPolicy): NetworkPolicy {
+  if (policy.allow === undefined) return {};
+  return { allow: [...new Set(policy.allow.map(entry => { parseEntry(entry); return entry.toLowerCase(); }))].sort() };
+}
+const covers = (entry: ReturnType<typeof parseEntry>, host: string, port: number) =>
+  entry.ports.includes(port) && (entry.wildcard ? host.endsWith("." + entry.host) : host === entry.host);
+export function allowed(policy: NetworkPolicy, host: string, port: number): boolean {
+  return policy.allow === undefined || policy.allow.some(entry => covers(parseEntry(entry), host.toLowerCase(), port));
+}
+/** Throws unless the child's policy allows nothing the parent's does not. */
+export function assertNetworkNarrower(parent: NetworkPolicy, child: NetworkPolicy): void {
+  if (parent.allow === undefined) return;
+  if (child.allow === undefined) throw new Error("A member with restricted network access cannot launch one with public access");
+  for (const text of child.allow) {
+    const entry = parseEntry(text);
+    const ok = parent.allow.some(parentText => {
+      const outer = parseEntry(parentText);
+      if (!entry.ports.every(port => outer.ports.includes(port))) return false;
+      if (outer.wildcard) return entry.host.endsWith("." + outer.host);
+      return !entry.wildcard && entry.host === outer.host;
+    });
+    if (!ok) throw new Error(`Network access to ${text} exceeds the requesting member's access`);
+  }
+}
+
+// Only global unicast is public. Everything else (host loopback, LAN, Docker bridges, tailscale CGNAT, link-local,
+// documentation, multicast, translation prefixes) stays unreachable.
+const blocked = new BlockList();
+for (const [address, prefix] of [["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24],
+  ["192.0.2.0", 24], ["192.88.99.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15], ["198.51.100.0", 24], ["203.0.113.0", 24], ["224.0.0.0", 3]] as const) blocked.addSubnet(address, prefix, "ipv4");
+for (const [address, prefix] of [["64:ff9b::", 96], ["64:ff9b:1::", 48], ["100::", 64], ["2001::", 23], ["2001:db8::", 32], ["2002::", 16], ["3fff::", 20]] as const) blocked.addSubnet(address, prefix, "ipv6");
+export function isPublicAddress(address: string): boolean {
+  const family = isIP(address);
+  if (family === 4) return !blocked.check(address, "ipv4");
+  if (family !== 6) return false;
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+  if (mapped) return isPublicAddress(mapped[1]);
+  // Global unicast is 2000::/3; this also excludes ::, ::1, IPv4-compatible, ULA fc00::/7, link-local, and multicast.
+  const first = parseInt(address.startsWith("::") ? "0" : address.split(":")[0] || "0", 16);
+  return first >= 0x2000 && first <= 0x3fff && !blocked.check(address, "ipv6");
+}
+
+/** The host's own addresses are refused even when public, so services listening on all interfaces stay unreachable. */
+export function isHostAddress(address: string): boolean {
+  const normal = (value: string) => value.toLowerCase().replace(/^::ffff:(?=\d)/, "").replace(/%.*$/, "");
+  return Object.values(networkInterfaces()).flat().some(entry => entry && normal(entry.address) === normal(address));
+}
+const reachable = (address: string) => isPublicAddress(address) && !isHostAddress(address);
+
+type Lookup = (host: string) => Promise<string[]>;
+const systemLookup: Lookup = async host => (await dnsLookup(host, { all: true, verbatim: true })).map(entry => entry.address);
+
+/** Splits an authority (host:port, [v6]:port) strictly; returns undefined for anything else. */
+export function parseAuthority(authority: string, defaultPort?: number): { host: string; port: number } | undefined {
+  const match = /^(?:\[([0-9a-f:.]+)\]|([a-z0-9.-]+))(?::(\d{1,5}))?$/i.exec(authority);
+  if (!match) return;
+  const host = (match[1] ?? match[2]).toLowerCase(), port = match[3] === undefined ? defaultPort : Number(match[3]);
+  if (port === undefined || port < 1 || port > 65535 || (match[1] && isIP(match[1]) !== 6) || (!match[1] && isIP(host) === 6)) return;
+  return { host, port };
+}
+
+/** One member's outbound proxy on a private Unix socket: HTTP CONNECT and plain HTTP forwarding to public addresses only. */
+export class Egress {
+  readonly socket: string;
+  private server: Server;
+  private sockets = new Set<Socket>();
+  private policy: NetworkPolicy;
+  private model: { host: string; port: number };
+  private lookup: Lookup;
+  private isPublic: (address: string) => boolean;
+  private start: Promise<boolean>;
+  private started = false;
+  private constructor(socket: string, policy: NetworkPolicy, model: { host: string; port: number }, start: Promise<boolean>, lookup: Lookup, isPublic: (address: string) => boolean) {
+    this.socket = socket; this.policy = policy; this.model = model; this.start = start; this.lookup = lookup; this.isPublic = isPublic;
+    this.server = createServer({ requestTimeout: 0, headersTimeout: 30000 }, (req, res) => void this.forward(req, res).catch(() => res.destroy()));
+    this.server.on("connect", (req, client: Socket, head: Buffer) => void this.tunnel(req, client, head).catch(() => client.destroy()));
+    this.server.on("connection", socket => { if (this.sockets.size >= maxEgressConnections) return socket.destroy(); this.sockets.add(socket); socket.once("close", () => this.sockets.delete(socket)); });
+  }
+  /** `start` resolves true once the member's mounts are verified; the bridge waits on it before running any member code. */
+  static async open(socket: string, policy: NetworkPolicy, model: { host: string; port: number }, start: Promise<boolean>, lookup = systemLookup, isPublic = reachable): Promise<Egress> {
+    if (Buffer.byteLength(socket) > 107) throw new Error(`Egress socket path is too long: ${socket}`);
+    const egress = new Egress(socket, policy, model, start, lookup, isPublic);
+    try { unlinkSync(socket); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    await new Promise<void>((done, fail) => {
+      egress.server.once("error", fail);
+      egress.server.listen(socket, () => { try { chmodSync(socket, 0o600); done(); } catch (error) { egress.server.close(); fail(error); } });
+    });
+    return egress;
+  }
+  close(): Promise<void> {
+    return new Promise(done => {
+      for (const socket of this.sockets) socket.destroy();
+      this.server.close(() => { try { unlinkSync(this.socket); } catch { /* Already removed. */ } done(); });
+    });
+  }
+  private permitted(host: string, port: number): boolean {
+    return (host === this.model.host && port === this.model.port) || allowed(this.policy, host, port);
+  }
+  /** Resolves and validates every address, then returns one to connect to, so DNS cannot change between check and connect. */
+  private async resolve(host: string): Promise<string> {
+    const addresses = isIP(host) ? [host] : await this.lookup(host);
+    if (!addresses.length || !addresses.every(address => this.isPublic(address))) throw new Error("Destination is not a public address");
+    return addresses[0];
+  }
+  private async tunnel(req: IncomingMessage, client: Socket, head: Buffer): Promise<void> {
+    const target = parseAuthority(req.url ?? "");
+    const refuse = (status: string) => { client.end(`HTTP/1.1 ${status}\r\nConnection: close\r\n\r\n`); };
+    if (!target) return refuse("400 Bad Request");
+    if (!this.permitted(target.host, target.port)) return refuse("403 Forbidden");
+    let address: string;
+    try { address = await this.resolve(target.host); } catch { return refuse("403 Forbidden"); }
+    const upstream = connect({ host: address, port: target.port, timeout: 10000 });
+    let established = false;
+    upstream.once("timeout", () => upstream.destroy());
+    upstream.once("connect", () => {
+      established = true;
+      upstream.setTimeout(300000);
+      client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      // Bytes the client sent right after CONNECT (e.g. a TLS ClientHello) arrive in `head`.
+      if (head.length) upstream.write(head);
+      upstream.pipe(client).pipe(upstream);
+    });
+    // Once tunnelled, the stream belongs to the client's protocol; an HTTP error response would corrupt it.
+    upstream.on("error", () => { if (established) client.destroy(); else if (!client.destroyed) refuse("502 Bad Gateway"); });
+    client.on("error", () => upstream.destroy());
+    client.once("close", () => upstream.destroy());
+  }
+  private async forward(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const fail = (status: number) => { if (!res.headersSent) { res.writeHead(status, { "content-type": "text/plain", connection: "close" }); res.end(); } else res.destroy(); };
+    // Start gate for the in-container bridge: answered once, after mount verification.
+    if (req.url === "http://ac-teams.invalid/start") {
+      if (this.started) return fail(409);
+      this.started = true;
+      return (await this.start.catch(() => false)) ? (res.writeHead(200), void res.end("go")) : fail(403);
+    }
+    let url: URL;
+    try { url = new URL(req.url ?? ""); } catch { return fail(400); }
+    const target = url.protocol === "http:" && !url.username && !url.password ? parseAuthority(url.host, 80) : undefined;
+    if (!target) return fail(400);
+    if (!this.permitted(target.host, target.port)) return fail(403);
+    let address: string;
+    try { address = await this.resolve(target.host); } catch { return fail(403); }
+    const headers: Record<string, string | string[]> = {};
+    for (const [name, value] of Object.entries(req.headers)) if (value !== undefined && !/^(proxy-|connection$|keep-alive$|te$|trailer$|upgrade$|host$)/i.test(name)) headers[name] = value;
+    headers.host = url.host;
+    const upstream = httpRequest({ host: address, port: target.port, method: req.method, path: url.pathname + url.search, headers, timeout: 300000 }, response => {
+      res.writeHead(response.statusCode ?? 502, response.headers);
+      response.pipe(res);
+    });
+    upstream.on("timeout", () => upstream.destroy());
+    upstream.on("error", () => fail(502));
+    res.once("close", () => { if (!res.writableFinished) upstream.destroy(); });
+    req.pipe(upstream);
+  }
+}
+
+/** Providers whose current-token auth ac-teams can hand to a member; the endpoint stays reachable under any policy. */
+export const providerRoutes: Record<string, { api: string; baseUrl: string }> = {
+  anthropic: { api: "anthropic-messages", baseUrl: "https://api.anthropic.com" },
+  openai: { api: "openai-responses", baseUrl: "https://api.openai.com/v1" },
+};
+/** Resolves the provider's current access token in the trusted parent, which owns OAuth refresh. */
+export type Credentials = (provider: string, model: string) => Promise<{ token: string; expires: number }>;

package/src/index.ts

@@ -12,6 +12,8 @@ import { join } from "node:path";
 import { Coordinator, assistantEvent, taskRequestGuidance } from "./coordinator.ts";
 import { Connection, isRecord } from "./connection.ts";
 import { policy, readDisplaySettings, defaultDisplaySettings } from "./config.ts";
+import { providerRoutes } from "./egress.ts";
+import { VERSION, readStoredCredential } from "@earendil-works/pi-coding-agent";
 
 export default function teams(pi: ExtensionAPI) {
   pi.registerFlag("teams-limit", { description: "Explicit maximum live ac-teams members (default 10, idle members count)", type: "string" });
@@ -42,10 +44,22 @@ export default function teams(pi: ExtensionAPI) {
     if (exiting) throw new Error("Team is stopping");
     context = ctx;
     opening ??= Coordinator.open({
-      id: ctx.sessionManager.getSessionId(), cwd: ctx.cwd, sessionFile: ctx.sessionManager.getSessionFile(),
+      id: ctx.sessionManager.getSessionId(), cwd: ctx.cwd, sessionFile: ctx.sessionManager.getSessionFile(), sessionDir: ctx.sessionManager.getSessionDir(),
       ...policy(ctx.cwd, pi.getFlag("teams-project-config") === true, { limit: pi.getFlag("teams-limit") as string | undefined, depth: pi.getFlag("teams-depth") as string | undefined }),
-      extension: fileURLToPath(import.meta.url), notice: notify, warning: warn,
+      extension: fileURLToPath(import.meta.url), notice: notify, warning: warn, piVersion: VERSION,
       status: (kind, active) => pi.events.emit(`herdr:${kind}`, { active, source: "ac-teams" }),
+      credentials: async (provider, modelId) => {
+        // Only providers whose request shape was verified are brokered; anything else fails closed.
+        const registry = (context ?? ctx).modelRegistry, model = registry.find(provider, modelId), route = providerRoutes[provider];
+        if (!model || !route || model.api !== route.api || model.baseUrl !== route.baseUrl || !registry.isUsingOAuth(model)) throw new Error(`Enforced access supports only OAuth ${Object.keys(providerRoutes).join("/")} models at their default endpoints, not ${provider}/${modelId}`);
+        const auth = await registry.getApiKeyAndHeaders(model);
+        if (!auth.ok) throw new Error(auth.error);
+        if (!auth.apiKey || auth.baseUrl || Object.keys(auth.headers ?? {}).length || Object.keys(auth.env ?? {}).length) throw new Error(`Unsupported credential shape for ${provider}`);
+        // The member gets the token's real expiry; an unknown expiry is kept short so the parent's rewrite stays ahead of it.
+        const stored = readStoredCredential(provider) as { type?: string; access?: string; expires?: number } | undefined;
+        const expires = stored?.type === "oauth" && stored.access === auth.apiKey && typeof stored.expires === "number" ? stored.expires : Date.now() + 10 * 60000;
+        return { token: auth.apiKey, expires };
+      },
       interactive: ctx.mode === "tui", model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined, thinking: pi.getThinkingLevel(),
     }).then(value => {
       coordinator = value;

package/src/sandbox-bridge.mjs

@@ -0,0 +1,33 @@
+// Trusted bootstrap inside a member container. It exposes the parent's egress proxy on loopback, then waits for the
+// parent to verify the container's mounts before running any member code (Pi, extensions, project files).
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { request } from "node:http";
+import { connect, createServer } from "node:net";
+import { constants } from "node:os";
+
+const launch = JSON.parse(readFileSync(process.argv[2], "utf8"));
+const fail = message => { console.error(`ac-teams sandbox bridge: ${message}`); process.exit(1); };
+const server = createServer(client => {
+  const upstream = connect(launch.socket);
+  client.pipe(upstream).pipe(client);
+  client.on("error", () => upstream.destroy());
+  upstream.on("error", () => client.destroy());
+});
+server.on("error", error => fail(error.message));
+server.listen(launch.port, "127.0.0.1", () => {
+  const gate = request({ socketPath: launch.socket, path: "http://ac-teams.invalid/start", method: "GET" }, response => {
+    let body = "";
+    response.on("data", chunk => { body += chunk; });
+    response.on("end", () => {
+      if (response.statusCode !== 200 || body !== "go") fail("the parent did not release this member");
+      const child = spawn(launch.command, launch.args, { env: launch.env, stdio: "inherit" });
+      for (const signal of ["SIGTERM", "SIGHUP"]) process.on(signal, () => child.kill(signal));
+      process.on("SIGINT", () => {}); // The terminal already delivers Ctrl+C to Pi's process group.
+      child.on("error", error => fail(error.message));
+      child.on("exit", (code, signal) => process.exit(code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 1)));
+    });
+  });
+  gate.on("error", error => fail(error.message));
+  gate.end();
+});

package/src/sandbox.Dockerfile

@@ -0,0 +1,8 @@
+# Image for enforced ac-teams members. Host code, grants, and Pi packages are mounted at run time.
+FROM node:22-bookworm-slim@sha256:4b150b48b4116e2a22f2c39cc27025fbf4f153e2078fd3b14d159fdb5c7279da
+ARG PI_VERSION
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends bash ca-certificates curl git ripgrep \
+  && rm -rf /var/lib/apt/lists/* \
+  && npm install -g --ignore-scripts "@earendil-works/pi-coding-agent@${PI_VERSION}" \
+  && npm cache clean --force

package/src/schemas.ts

@@ -13,6 +13,13 @@ export const AgentSchema = Type.Object({
   worktree: Type.Optional(Type.Boolean()), base: Type.Optional(id), target: Type.Optional(id),
   limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
   depth: Type.Optional(Type.Integer({ minimum: 0, maximum: 10 })),
+  access: Type.Optional(Type.Object({
+    read: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 4096 }), { maxItems: 32 })),
+    write: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 4096 }), { maxItems: 32 })),
+    network: Type.Optional(Type.Object({
+      allow: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 260 }), { maxItems: 64, description: "Hosts the member may reach through its proxy: host or *.host (subdomains), optionally :port; without a port, 80 and 443. [] allows only the model provider. Omit allow for any public destination." })),
+    }, { additionalProperties: false, description: "Omit to keep the requester's network access. Children can only narrow it. The model provider stays reachable." })),
+  }, { additionalProperties: false, description: "Launch only: OS-enforced directory access (Docker container). Paths are absolute or cwd-relative directories; write implies read and permits changing those live files; everything else on the host is hidden, and outbound access goes through a proxy that reaches only public addresses. Omit to inherit the requesting member's access; an unsandboxed requester then launches an unsandboxed member. Children can only narrow access. Launch fails if enforcement is unavailable; check team_agent list/limits sandbox first." })),
 }, { additionalProperties: false });
 export const TaskSchema = Type.Object({
   revision: Type.Optional(Type.Integer({ minimum: 1 })), acceptance: Type.Optional(Type.Boolean()),
@@ -56,5 +63,6 @@ export function validate(operation: string, value: unknown): void {
     const args = value as { action: string; name?: string };
     if (args.action === "launch" && !args.name) throw new Error("A descriptive teammate name is required on launch");
     if (args.action !== "launch" && args.name !== undefined) throw new Error("A teammate name can only be set on launch");
+    if (args.action !== "launch" && (value as { access?: unknown }).access !== undefined) throw new Error("Access can only be set on launch; resume keeps the member's access");
   }
 }

package/src/store.ts

@@ -1,7 +1,8 @@
 import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
+import { stateRoot } from "./config.ts";
+import { validatePolicy } from "./egress.ts";
 import { stripVTControlCharacters } from "node:util";
 import { isDescendant, isLive, memberNamePattern, memberNameMaxLength, taskLabelMaxLength, taskLabelPattern } from "./types.ts";
 import type { TeamState, TaskArgs, MessageArgs, Task, TaskView, Message, Worktree } from "./types.ts";
@@ -85,7 +86,7 @@ function validate(state: unknown): asserts state is TeamState {
       names.add(member.name);
     }
     requireValue(member.parent === undefined || (text(member.parent) && Object.hasOwn(members, member.parent)), "Invalid member parent");
-    for (const field of ["identity", "sessionId", "sessionFile", "error", "model", "modelName", "thinking", "activity", "summary"]) requireValue(member[field] === undefined || typeof member[field] === "string", "Invalid member field");
+    for (const field of ["identity", "sessionId", "sessionFile", "error", "model", "modelName", "thinking", "activity", "summary", "provider"]) requireValue(member[field] === undefined || typeof member[field] === "string", "Invalid member field");
     if (member.contextUsage !== undefined) {
       const usage = member.contextUsage;
       requireValue(object(usage) && integer(usage.contextWindow, 1) && (usage.tokens === null || integer(usage.tokens)) && (usage.percent === null || typeof usage.percent === "number" && Number.isFinite(usage.percent) && usage.percent >= 0), "Invalid member context usage");
@@ -94,6 +95,9 @@ function validate(state: unknown): asserts state is TeamState {
     requireValue(member.needsInput === undefined || typeof member.needsInput === "boolean", "Invalid member input flag");
     requireValue(member.pid === undefined || integer(member.pid, 1), "Invalid member PID");
     requireValue(member.worktree === undefined || validateWorktree(member.worktree), "Invalid member worktree");
+    const paths = (value: unknown) => Array.isArray(value) && value.every(path => typeof path === "string" && path.startsWith("/"));
+    const network = (value: unknown) => { try { return object(value) && (value.allow === undefined || (Array.isArray(value.allow) && value.allow.every(entry => typeof entry === "string"))) && (validatePolicy(value), true); } catch { return false; } };
+    requireValue(member.access === undefined || (object(member.access) && paths(member.access.read) && paths(member.access.write) && network(member.access.network)), "Invalid member access");
     const seen = new Set<string>([key]);
     for (let parent: unknown = member.parent; parent !== undefined;) {
       requireValue(typeof parent === "string" && !seen.has(parent), "Cyclic member ancestry");
@@ -158,7 +162,7 @@ export class Store {
   private lock?: number;
   private closed = false;
 
-  constructor(initial: TeamState, home = join(homedir(), ".acstack", "ac-teams", "teams")) {
+  constructor(initial: TeamState, home = join(stateRoot(), "teams")) {
     validate(initial);
     this.dir = join(resolve(home), initial.id);
     this.state = structuredClone(initial);

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { Access, AccessRequest } from "./access.ts";
 export interface Worktree {
   repo: string;
   path: string;
@@ -39,6 +40,9 @@ export interface Member {
   summary?: string;
   terminal?: boolean;
   needsInput?: boolean;
+  access?: Access;
+  /** Provider fixed at an enforced member's first launch; member telemetry cannot change it. */
+  provider?: string;
 }
 export const memberNameMaxLength = 40;
 export const memberNamePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)?(?![\s\S])/;
@@ -113,6 +117,7 @@ export interface AgentArgs {
   target?: string;
   limit?: number;
   depth?: number;
+  access?: AccessRequest;
 }
 export interface UserAction {
   action: "task_request" | "feedback" | "resume";