@ai-hero/sandcastle 0.3.0 → 0.4.1

package/README.md

@@ -11,7 +11,7 @@
 A TypeScript library for orchestrating AI coding agents in isolated Docker containers:
 
 1. You invoke agents with a single `sandcastle.run()`.
-2. Sandcastle handles building worktrees and sandboxing the agent.
+2. Sandcastle handles sandboxing the agent with a configurable branch strategy.
 3. The commits made on the branches get merged back.
 
 Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents.
@@ -35,7 +35,7 @@ npm install @ai-hero/sandcastle
 npx sandcastle init
 ```
 
-3. Edit `.sandcastle/.env` and fill in your default values for `ANTHROPIC_API_KEY`
+3. Edit `.sandcastle/.env` and fill in your default values for `ANTHROPIC_API_KEY`. If you want to use your Claude subscription instead of an API key, see [#191](https://github.com/mattpocock/sandcastle/issues/191).
 
 ```bash
 cp .sandcastle/.env.example .sandcastle/.env
@@ -90,8 +90,20 @@ const result = await run({
   agent: claudeCode("claude-opus-4-6", { effort: "high" }),
 
   // Sandbox provider — required. Import from "@ai-hero/sandcastle/sandboxes/docker".
-  // Provider-specific config (like imageName) lives inside the provider factory call.
-  sandbox: docker({ imageName: "sandcastle:local" }),
+  // Provider-specific config (like imageName, mounts) lives inside the provider factory call.
+  sandbox: docker({
+    imageName: "sandcastle:local",
+    // Optional: mount host directories into the sandbox (e.g. package manager caches)
+    mounts: [
+      { hostPath: "~/.npm", sandboxPath: "/home/agent/.npm", readonly: true },
+    ],
+    // Optional: provider-level env vars merged at launch time
+    env: { DOCKER_SPECIFIC: "value" },
+  }),
+
+  // Branch strategy — controls how the agent's changes relate to branches.
+  // Defaults to { type: "head" } for bind-mount and { type: "merge-to-head" } for isolated providers.
+  branchStrategy: { type: "branch", branch: "agent/fix-42" },
 
   // Prompt source — provide one of these, not both:
   promptFile: ".sandcastle/prompt.md", // path to a prompt file
@@ -105,22 +117,17 @@ const result = await run({
   // Maximum number of agent iterations to run before stopping. Default: 1
   maxIterations: 5,
 
-  // Worktree mode for sandbox work. Defaults to { mode: 'temp-branch' }.
-  // { mode: 'none' } — bind-mount host working directory directly (no worktree).
-  // { mode: 'temp-branch' } — create a temp worktree, merge back.
-  // { mode: 'branch', branch } — create a worktree on an explicit branch.
-  worktree: { mode: "branch", branch: "agent/fix-42" },
-
   // Display name for this run, shown as a prefix in log output.
   name: "fix-issue-42",
 
   // Lifecycle hooks — arrays of shell commands run sequentially inside the sandbox.
   hooks: {
-    // Runs after the worktree is mounted into the sandbox.
+    // Runs after the sandbox is ready.
     onSandboxReady: [{ command: "npm install" }],
   },
 
-  // Host-relative file paths to copy into the worktree before the container starts.
+  // Host-relative file paths to copy into the sandbox before the container starts.
+  // Not supported with branchStrategy: { type: "head" }.
   copyToSandbox: [".env"],
 
   // How to record progress. Default: write to a file under .sandcastle/logs/
@@ -143,7 +150,7 @@ console.log(result.branch); // target branch name
 
 ### `createSandbox()` — reusable sandbox
 
-Use `createSandbox()` when you need to run multiple agents (or multiple rounds of the same agent) inside a single sandbox. It creates the worktree and container once, and you call `sandbox.run()` as many times as you need. This avoids repeated container startup costs and keeps all runs on the same branch.
+Use `createSandbox()` when you need to run multiple agents (or multiple rounds of the same agent) inside a single sandbox. It creates the sandbox once, and you call `sandbox.run()` as many times as you need. This avoids repeated container startup costs and keeps all runs on the same branch.
 
 Use `run()` instead when you only need a single one-shot invocation — it handles sandbox lifecycle automatically.
 
@@ -196,7 +203,7 @@ Commits from all `run()` calls accumulate on the same branch. The sandbox contai
 
 #### Automatic cleanup with `await using`
 
-`await using` calls `sandbox.close()` automatically when the block exits. If the worktree has uncommitted changes, it is preserved on disk; if clean, both container and worktree are removed.
+`await using` calls `sandbox.close()` automatically when the block exits. If the sandbox has uncommitted changes, the worktree is preserved on disk; if clean, both container and worktree are removed.
 
 #### Manual `close()` with `CloseResult`
 
@@ -214,21 +221,22 @@ if (closeResult.preservedWorktreePath) {
 
 #### `CreateSandboxOptions`
 
-| Option          | Type            | Default | Description                                                         |
-| --------------- | --------------- | ------- | ------------------------------------------------------------------- |
-| `branch`        | string          | —       | **Required.** Explicit branch for the worktree                      |
-| `sandbox`       | SandboxProvider | —       | **Required.** Sandbox provider (e.g. `docker()`)                    |
-| `hooks`         | object          | —       | Lifecycle hooks (`onSandboxReady`) — run once at creation time      |
-| `copyToSandbox` | string[]        | —       | Host-relative file paths to copy into the worktree at creation time |
+| Option                     | Type            | Default | Description                                                              |
+| -------------------------- | --------------- | ------- | ------------------------------------------------------------------------ |
+| `branch`                   | string          | —       | **Required.** Explicit branch for the sandbox                            |
+| `sandbox`                  | SandboxProvider | —       | **Required.** Sandbox provider (e.g. `docker()`, `podman()`)             |
+| `hooks`                    | object          | —       | Lifecycle hooks (`onSandboxReady`) — run once at creation time           |
+| `copyToSandbox`            | string[]        | —       | Host-relative file paths to copy into the sandbox at creation time       |
+| `throwOnDuplicateWorktree` | boolean         | `true`  | When `false`, reuse an existing worktree instead of failing on collision |
 
 #### `Sandbox`
 
 | Property / Method       | Type                                               | Description                                 |
 | ----------------------- | -------------------------------------------------- | ------------------------------------------- |
-| `branch`                | string                                             | The branch the worktree is on               |
+| `branch`                | string                                             | The branch the sandbox is on                |
 | `worktreePath`          | string                                             | Host path to the worktree                   |
 | `run(options)`          | `(SandboxRunOptions) => Promise<SandboxRunResult>` | Invoke an agent inside the existing sandbox |
-| `close()`               | `() => Promise<CloseResult>`                       | Tear down the container and worktree        |
+| `close()`               | `() => Promise<CloseResult>`                       | Tear down the container and sandbox         |
 | `[Symbol.asyncDispose]` | `() => Promise<void>`                              | Auto teardown via `await using`             |
 
 #### `SandboxRunOptions`
@@ -263,14 +271,15 @@ if (closeResult.preservedWorktreePath) {
 
 ## How it works
 
-Sandcastle uses a worktree-based architecture for agent execution:
+Sandcastle uses a **branch strategy** configured on the sandbox provider to control how the agent's changes relate to branches. There are three strategies:
+
+- **Head** (`{ type: "head" }`) — The agent writes directly to the host working directory. No worktree, no branch indirection. This is the default for bind-mount providers like `docker()`.
+- **Merge-to-head** (`{ type: "merge-to-head" }`) — Sandcastle creates a temporary branch in a git worktree. The agent works on the temp branch, and changes are merged back to HEAD when done. The temp branch is cleaned up after merge.
+- **Branch** (`{ type: "branch", branch: "foo" }`) — Commits land on an explicitly named branch in a git worktree.
 
-- **Worktree**: Sandcastle creates a git worktree on the host at `.sandcastle/worktrees/`. The worktree is a just a normal `git worktree`.
-- **Bind-mount**: The worktree directory is bind-mounted into the sandbox container as the agent's working directory. The agent writes directly to the host filesystem through the mount.
-- **No sync needed**: Because the agent writes directly to the host filesystem, there are no sync-in or sync-out operations. Commits made by the agent are immediately visible on the host.
-- **Merge back**: After the run completes, the temp worktree branch is fast-forward merged back to the target branch, and the worktree is cleaned up.
+For bind-mount providers (like Docker), the worktree directory is bind-mounted into the container — the agent writes directly to the host filesystem through the mount, so no sync is needed.
 
-From your point of view, you just run `sandcastle.run({ worktree: { mode: 'branch', branch: 'foo' } })`, and get a commit on branch `foo` once it's complete. All 100% local.
+From your point of view, you just configure `branchStrategy: { type: 'branch', branch: 'foo' }` on `run()`, and get a commit on branch `foo` once it's complete. All 100% local.
 
 ## Prompts
 
@@ -291,7 +300,7 @@ You must provide exactly one of:
 
 Use `` !`command` `` expressions in your prompt to pull in dynamic context. Each expression is replaced with the command's stdout before the prompt is sent to the agent.
 
-Commands run **inside the sandbox** after the worktree is mounted and `onSandboxReady` hooks complete, so they see the same repo state the agent sees (including installed dependencies).
+Commands run **inside the sandbox** after `onSandboxReady` hooks complete, so they see the same repo state the agent sees (including installed dependencies).
 
 ```markdown
 # Open issues
@@ -336,10 +345,10 @@ A `{{KEY}}` placeholder with no matching prompt argument is an error. Unused pro
 
 Sandcastle automatically injects two built-in prompt arguments into every prompt:
 
-| Placeholder         | Value                                                                |
-| ------------------- | -------------------------------------------------------------------- |
-| `{{SOURCE_BRANCH}}` | The branch the agent works on inside the worktree (temp or explicit) |
-| `{{TARGET_BRANCH}}` | The host's active branch at `run()` time                             |
+| Placeholder         | Value                                                             |
+| ------------------- | ----------------------------------------------------------------- |
+| `{{SOURCE_BRANCH}}` | The branch the agent works on (determined by the branch strategy) |
+| `{{TARGET_BRANCH}}` | The host's active branch at `run()` time                          |
 
 Use them in your prompt without passing them via `promptArgs`:
 
@@ -376,12 +385,13 @@ Tell the agent to output your chosen string(s) in the prompt, and the orchestrat
 
 `sandcastle init` prompts you to choose a template, which scaffolds a ready-to-use prompt and `main.mts` suited to a specific workflow. If your project's `package.json` has `"type": "module"`, the file will be named `main.ts` instead. Four templates are available:
 
-| Template              | Description                                                             |
-| --------------------- | ----------------------------------------------------------------------- |
-| `blank`               | Bare scaffold — write your own prompt and orchestration                 |
-| `simple-loop`         | Picks GitHub issues one by one and closes them                          |
-| `sequential-reviewer` | Implements issues one by one, with a code review step after each        |
-| `parallel-planner`    | Plans parallelizable issues, executes on separate branches, then merges |
+| Template                       | Description                                                               |
+| ------------------------------ | ------------------------------------------------------------------------- |
+| `blank`                        | Bare scaffold — write your own prompt and orchestration                   |
+| `simple-loop`                  | Picks GitHub issues one by one and closes them                            |
+| `sequential-reviewer`          | Implements issues one by one, with a code review step after each          |
+| `parallel-planner`             | Plans parallelizable issues, executes on separate branches, then merges   |
+| `parallel-planner-with-review` | Plans parallelizable issues, executes with per-branch review, then merges |
 
 Select a template during `sandcastle init` when prompted, or re-run init in a fresh repo to try a different one.
 
@@ -394,7 +404,7 @@ Scaffolds the `.sandcastle/` config directory and builds the Docker image. This
 | Option         | Required | Default                      | Description                                                          |
 | -------------- | -------- | ---------------------------- | -------------------------------------------------------------------- |
 | `--image-name` | No       | `sandcastle:<repo-dir-name>` | Docker image name                                                    |
-| `--agent`      | No       | Interactive prompt           | Agent to use (`claude-code`, `pi`, `codex`)                          |
+| `--agent`      | No       | Interactive prompt           | Agent to use (`claude-code`, `pi`, `codex`, `opencode`)              |
 | `--model`      | No       | Agent's default model        | Model to use (e.g. `claude-sonnet-4-6`). Defaults to agent's default |
 | `--template`   | No       | Interactive prompt           | Template to scaffold (e.g. `blank`, `simple-loop`)                   |
 
@@ -405,7 +415,7 @@ Creates the following files:
 ├── Dockerfile      # Sandbox environment (customize as needed)
 ├── prompt.md       # Agent instructions
 ├── .env.example    # Token placeholders
-└── .gitignore      # Ignores .env, logs/, worktrees/
+└── .gitignore      # Ignores .env, logs/
 ```
 
 Errors if `.sandcastle/` already exists to prevent overwriting customizations.
@@ -429,21 +439,22 @@ Removes the Docker image.
 
 ### `RunOptions`
 
-| Option               | Type               | Default                       | Description                                                                                                             |
-| -------------------- | ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `agent`              | AgentProvider      | —                             | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-6")`, `pi("claude-sonnet-4-6")`, `codex("gpt-5.4-mini")`) |
-| `sandbox`            | SandboxProvider    | —                             | **Required.** Sandbox provider (e.g. `docker()`, `docker({ imageName: "sandcastle:local" })`)                           |
-| `prompt`             | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                                                                    |
-| `promptFile`         | string             | —                             | Path to prompt file (mutually exclusive with `prompt`)                                                                  |
-| `maxIterations`      | number             | `1`                           | Maximum iterations to run                                                                                               |
-| `hooks`              | object             | —                             | Lifecycle hooks (`onSandboxReady`)                                                                                      |
-| `worktree`           | WorktreeMode       | `{ mode: 'temp-branch' }`     | Worktree mode: `{ mode: 'none' }`, `{ mode: 'temp-branch' }`, or `{ mode: 'branch', branch }`                           |
-| `name`               | string             | —                             | Display name for the run, shown as a prefix in log output                                                               |
-| `promptArgs`         | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                                                                    |
-| `copyToSandbox`      | string[]           | —                             | Host-relative file paths to copy into the worktree before start (not supported with `mode: 'none'`)                     |
-| `logging`            | object             | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`                                                                        |
-| `completionSignal`   | string \| string[] | `<promise>COMPLETE</promise>` | String or array of strings the agent emits to stop the iteration loop early                                             |
-| `idleTimeoutSeconds` | number             | `600`                         | Idle timeout in seconds — resets on each agent output event                                                             |
+| Option                     | Type               | Default                       | Description                                                                                                                                                |
+| -------------------------- | ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent`                    | AgentProvider      | —                             | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-6")`, `pi("claude-sonnet-4-6")`, `codex("gpt-5.4-mini")`, `opencode("opencode/big-pickle")`) |
+| `sandbox`                  | SandboxProvider    | —                             | **Required.** Sandbox provider (e.g. `docker()`, `podman()`, `docker({ imageName: "sandcastle:local" })`)                                                  |
+| `prompt`                   | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                                                                                                       |
+| `promptFile`               | string             | —                             | Path to prompt file (mutually exclusive with `prompt`)                                                                                                     |
+| `maxIterations`            | number             | `1`                           | Maximum iterations to run                                                                                                                                  |
+| `hooks`                    | object             | —                             | Lifecycle hooks (`onSandboxReady`)                                                                                                                         |
+| `name`                     | string             | —                             | Display name for the run, shown as a prefix in log output                                                                                                  |
+| `promptArgs`               | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                                                                                                       |
+| `branchStrategy`           | BranchStrategy     | per-provider default          | Branch strategy: `{ type: 'head' }`, `{ type: 'merge-to-head' }`, or `{ type: 'branch', branch: '…' }`                                                     |
+| `copyToSandbox`            | string[]           | —                             | Host-relative file paths to copy into the sandbox before start (not supported with `branchStrategy: { type: 'head' }`)                                     |
+| `logging`                  | object             | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`                                                                                                           |
+| `completionSignal`         | string \| string[] | `<promise>COMPLETE</promise>` | String or array of strings the agent emits to stop the iteration loop early                                                                                |
+| `idleTimeoutSeconds`       | number             | `600`                         | Idle timeout in seconds — resets on each agent output event                                                                                                |
+| `throwOnDuplicateWorktree` | boolean            | `true`                        | When `false`, reuse an existing worktree for the target branch instead of failing on collision                                                             |
 
 ### `RunResult`
 
@@ -467,8 +478,323 @@ agent: claudeCode("claude-opus-4-6", { effort: "high" });
 | Option   | Type                                         | Default | Description                                             |
 | -------- | -------------------------------------------- | ------- | ------------------------------------------------------- |
 | `effort` | `"low"` \| `"medium"` \| `"high"` \| `"max"` | —       | Claude Code reasoning effort level (`max` is Opus only) |
+| `env`    | `Record<string, string>`                     | `{}`    | Environment variables injected by this agent provider   |
+
+### Provider `env`
+
+Both **agent providers** and **sandbox providers** accept an optional `env: Record<string, string>` in their options. These environment variables are merged with the `.sandcastle/.env` resolver output at launch time:
+
+```typescript
+await run({
+  agent: claudeCode("claude-opus-4-6", {
+    env: { ANTHROPIC_API_KEY: "sk-ant-..." },
+  }),
+  sandbox: docker({
+    env: { DOCKER_SPECIFIC_VAR: "value" },
+  }),
+  prompt: "Fix issue #42",
+});
+```
+
+**Merge rules:**
+
+- Provider env (agent + sandbox) overrides `.sandcastle/.env` resolver output for shared keys
+- Agent provider env and sandbox provider env **must not overlap** — if they share any key, `run()` throws an error
+- When `env` is not provided, it defaults to `{}`
+
+Environment variables are also resolved automatically from `.sandcastle/.env` and `process.env` — no need to pass them to the API. The required variables depend on the **agent provider** (see `sandcastle init` output for details).
+
+## Custom Sandbox Providers
+
+Sandcastle ships with a Docker provider, but you can create your own. A sandbox provider tells Sandcastle how to execute commands in an isolated environment. There are two kinds:
+
+- **Bind-mount** — the sandbox can mount a host directory. Sandcastle creates a worktree on the host and the provider mounts it in. No file sync needed. Use this for Docker, Podman, or any local container runtime.
+- **Isolated** — the sandbox has its own filesystem (e.g. a cloud VM). The provider handles syncing code in and out via `copyIn` and `copyFileOut`. Use this when the sandbox cannot access the host filesystem.
+
+### The sandbox handle contract
+
+Both provider types return a **sandbox handle** from their `create()` function. The handle exposes:
+
+| Method          | Required | Description                                                                  |
+| --------------- | -------- | ---------------------------------------------------------------------------- |
+| `exec`          | Both     | Run a command, optionally streaming stdout line-by-line via `options.onLine` |
+| `close`         | Both     | Tear down the sandbox                                                        |
+| `copyIn`        | Isolated | Copy a file or directory from the host into the sandbox                      |
+| `copyOut`       | Isolated | Copy a file from the sandbox to the host                                     |
+| `workspacePath` | Both     | Absolute path to the workspace inside the sandbox                            |
+
+### `ExecResult`
+
+Every `exec` call returns an `ExecResult`:
+
+```typescript
+interface ExecResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+}
+```
+
+### Bind-mount provider example
+
+A minimal bind-mount provider that shells out to local processes (no container):
+
+```typescript
+import {
+  createBindMountSandboxProvider,
+  type BindMountCreateOptions,
+  type BindMountSandboxHandle,
+  type ExecResult,
+} from "@ai-hero/sandcastle";
+import { execFile, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+const localProcess = () =>
+  createBindMountSandboxProvider({
+    name: "local-process",
+    create: async (
+      options: BindMountCreateOptions,
+    ): Promise<BindMountSandboxHandle> => {
+      const workspacePath = options.worktreePath;
+
+      return {
+        workspacePath,
+
+        exec: (
+          command: string,
+          opts?: { onLine?: (line: string) => void; cwd?: string },
+        ): Promise<ExecResult> => {
+          if (opts?.onLine) {
+            const onLine = opts.onLine;
+            return new Promise((resolve, reject) => {
+              const proc = spawn("sh", ["-c", command], {
+                cwd: opts?.cwd ?? workspacePath,
+                stdio: ["ignore", "pipe", "pipe"],
+              });
+
+              const stdoutChunks: string[] = [];
+              const stderrChunks: string[] = [];
+
+              const rl = createInterface({ input: proc.stdout! });
+              rl.on("line", (line) => {
+                stdoutChunks.push(line);
+                onLine(line); // forward each line to Sandcastle
+              });
+
+              proc.stderr!.on("data", (chunk: Buffer) => {
+                stderrChunks.push(chunk.toString());
+              });
+
+              proc.on("error", (err) => reject(err));
+              proc.on("close", (code) => {
+                resolve({
+                  stdout: stdoutChunks.join("\n"),
+                  stderr: stderrChunks.join(""),
+                  exitCode: code ?? 0,
+                });
+              });
+            });
+          }
+
+          return new Promise((resolve, reject) => {
+            execFile(
+              "sh",
+              ["-c", command],
+              { cwd: opts?.cwd ?? workspacePath, maxBuffer: 10 * 1024 * 1024 },
+              (error, stdout, stderr) => {
+                if (error && error.code === undefined) {
+                  reject(new Error(`exec failed: ${error.message}`));
+                } else {
+                  resolve({
+                    stdout: stdout.toString(),
+                    stderr: stderr.toString(),
+                    exitCode: typeof error?.code === "number" ? error.code : 0,
+                  });
+                }
+              },
+            );
+          });
+        },
+
+        close: async () => {
+          // nothing to tear down for a local process
+        },
+      };
+    },
+  });
+```
+
+### Isolated provider example
+
+A minimal isolated provider using a temp directory:
+
+```typescript
+import {
+  createIsolatedSandboxProvider,
+  type IsolatedSandboxHandle,
+  type ExecResult,
+} from "@ai-hero/sandcastle";
+import { execFile, spawn } from "node:child_process";
+import { copyFile, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+
+const tempDir = () =>
+  createIsolatedSandboxProvider({
+    name: "temp-dir",
+    create: async (): Promise<IsolatedSandboxHandle> => {
+      const root = await mkdtemp(join(tmpdir(), "sandbox-"));
+      const workspacePath = join(root, "workspace");
+      await mkdir(workspacePath, { recursive: true });
+
+      return {
+        workspacePath,
+
+        exec: (
+          command: string,
+          opts?: { onLine?: (line: string) => void; cwd?: string },
+        ): Promise<ExecResult> => {
+          if (opts?.onLine) {
+            const onLine = opts.onLine;
+            return new Promise((resolve, reject) => {
+              const proc = spawn("sh", ["-c", command], {
+                cwd: opts?.cwd ?? workspacePath,
+                stdio: ["ignore", "pipe", "pipe"],
+              });
+
+              const stdoutChunks: string[] = [];
+              const stderrChunks: string[] = [];
+
+              const rl = createInterface({ input: proc.stdout! });
+              rl.on("line", (line) => {
+                stdoutChunks.push(line);
+                onLine(line);
+              });
+
+              proc.stderr!.on("data", (chunk: Buffer) => {
+                stderrChunks.push(chunk.toString());
+              });
+
+              proc.on("error", (err) => reject(err));
+              proc.on("close", (code) => {
+                resolve({
+                  stdout: stdoutChunks.join("\n"),
+                  stderr: stderrChunks.join(""),
+                  exitCode: code ?? 0,
+                });
+              });
+            });
+          }
+
+          return new Promise((resolve, reject) => {
+            execFile(
+              "sh",
+              ["-c", command],
+              { cwd: opts?.cwd ?? workspacePath, maxBuffer: 10 * 1024 * 1024 },
+              (error, stdout, stderr) => {
+                if (error && error.code === undefined) {
+                  reject(new Error(`exec failed: ${error.message}`));
+                } else {
+                  resolve({
+                    stdout: stdout.toString(),
+                    stderr: stderr.toString(),
+                    exitCode: typeof error?.code === "number" ? error.code : 0,
+                  });
+                }
+              },
+            );
+          });
+        },
+
+        copyIn: async (hostPath: string, sandboxPath: string) => {
+          const info = await stat(hostPath);
+          if (info.isDirectory()) {
+            await cp(hostPath, sandboxPath, { recursive: true });
+          } else {
+            await mkdir(dirname(sandboxPath), { recursive: true });
+            await copyFile(hostPath, sandboxPath);
+          }
+        },
+
+        copyFileOut: async (sandboxPath: string, hostPath: string) => {
+          await mkdir(dirname(hostPath), { recursive: true });
+          await copyFile(sandboxPath, hostPath);
+        },
+
+        close: async () => {
+          await rm(root, { recursive: true, force: true });
+        },
+      };
+    },
+  });
+```
+
+### Branch strategies
+
+A branch strategy controls where the agent's commits land. Configure it when constructing the provider:
+
+| Strategy        | Behavior                                                                 | Bind-mount | Isolated  |
+| --------------- | ------------------------------------------------------------------------ | ---------- | --------- |
+| `head`          | Agent writes directly to the host working directory. No worktree created | Default    | N/A       |
+| `merge-to-head` | Sandcastle creates a temp branch, merges back to HEAD when done          | Supported  | Default   |
+| `branch`        | Commits land on an explicit named branch you provide                     | Supported  | Supported |
+
+**When to use each:**
+
+- **`head`** — fast iteration during development. No branch indirection, no merge step. Only works with bind-mount providers since the agent needs direct host filesystem access.
+- **`merge-to-head`** — safe default for automation. The agent works on a throwaway branch; if something goes wrong, HEAD is untouched. Use this for CI or unattended runs.
+- **`branch`** — when you want commits on a specific branch (e.g. for a PR). Pass `{ type: "branch", branch: "agent/fix-42" }`.
+
+Branch strategy is now configured on `run()`, not on the provider:
+
+```typescript
+import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+
+// head — direct write, bind-mount only (default for bind-mount providers)
+await run({
+  agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
+  prompt: "…",
+});
+// merge-to-head — temp branch, merge back (default for isolated providers)
+await run({
+  agent: claudeCode("claude-opus-4-6"),
+  sandbox: tempDir(),
+  prompt: "…",
+});
+// branch — explicit named branch
+await run({
+  agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
+  branchStrategy: { type: "branch", branch: "agent/fix-42" },
+  prompt: "…",
+});
+```
+
+### Passing to `run()`
+
+Pass your custom provider via the `sandbox` option — it works the same as the built-in `docker()` provider:
+
+```typescript
+import { run, claudeCode } from "@ai-hero/sandcastle";
+
+const result = await run({
+  agent: claudeCode("claude-opus-4-6"),
+  sandbox: localProcess(), // your custom provider
+  prompt: "Fix issue #42 in this repo.",
+});
+```
+
+### Reference implementations
+
+For real-world examples, see:
 
-Environment variables are resolved automatically from `.sandcastle/.env` and `process.env` — no need to pass them to the API. The required variables depend on the **agent provider** (see `sandcastle init` output for details).
+- [`src/sandboxes/docker.ts`](src/sandboxes/docker.ts) — bind-mount provider using Docker containers
+- [`src/sandboxes/vercel.ts`](src/sandboxes/vercel.ts) — isolated provider using Vercel Firecracker microVMs via `@vercel/sandbox`
+- [`src/sandboxes/podman.ts`](src/sandboxes/podman.ts) — bind-mount provider using Podman containers (with SELinux label support)
+- [`src/sandboxes/test-isolated.ts`](src/sandboxes/test-isolated.ts) — isolated provider using temp directories (used in tests)
 
 ## Configuration
 
@@ -503,7 +829,7 @@ Hooks are arrays of `{ "command": "..." }` objects executed sequentially inside
 | ---------------- | -------------------------- | ---------------------- |
 | `onSandboxReady` | After the sandbox is ready | Sandbox repo directory |
 
-**`onSandboxReady`** runs after the worktree is mounted into the sandbox. Use it for dependency installation or build steps (e.g., `npm install`).
+**`onSandboxReady`** runs after the sandbox is ready. Use it for dependency installation or build steps (e.g., `npm install`).
 
 Pass hooks programmatically via `run()`:
 

package/dist/AgentProvider.d.ts

@@ -1,19 +1,9 @@
-export interface TokenUsage {
-    readonly input_tokens: number;
-    readonly output_tokens: number;
-    readonly cache_read_input_tokens: number;
-    readonly cache_creation_input_tokens: number;
-    readonly total_cost_usd: number;
-    readonly num_turns: number;
-    readonly duration_ms: number;
-}
 export type ParsedStreamEvent = {
     type: "text";
     text: string;
 } | {
     type: "result";
     result: string;
-    usage: TokenUsage | null;
 } | {
     type: "tool_call";
     name: string;
@@ -21,15 +11,35 @@ export type ParsedStreamEvent = {
 };
 export interface AgentProvider {
     readonly name: string;
+    /** Environment variables injected by this agent provider. Merged at launch time with env resolver and sandbox provider env. */
+    readonly env: Record<string, string>;
     buildPrintCommand(prompt: string): string;
     buildInteractiveArgs(prompt: string): string[];
     parseStreamLine(line: string): ParsedStreamEvent[];
 }
 export declare const DEFAULT_MODEL = "claude-opus-4-6";
-export declare const pi: (model: string) => AgentProvider;
-export declare const codex: (model: string) => AgentProvider;
+/** Options for the pi agent provider. */
+export interface PiOptions {
+    /** Environment variables injected by this agent provider. */
+    readonly env?: Record<string, string>;
+}
+export declare const pi: (model: string, options?: PiOptions | undefined) => AgentProvider;
+/** Options for the codex agent provider. */
+export interface CodexOptions {
+    /** Environment variables injected by this agent provider. */
+    readonly env?: Record<string, string>;
+}
+export declare const codex: (model: string, options?: CodexOptions | undefined) => AgentProvider;
+/** Options for the opencode agent provider. */
+export interface OpenCodeOptions {
+    /** Environment variables injected by this agent provider. */
+    readonly env?: Record<string, string>;
+}
+export declare const opencode: (model: string, options?: OpenCodeOptions | undefined) => AgentProvider;
 export interface ClaudeCodeOptions {
     readonly effort?: "low" | "medium" | "high" | "max";
+    /** Environment variables injected by this agent provider. */
+    readonly env?: Record<string, string>;
 }
 export declare const claudeCode: (model: string, options?: ClaudeCodeOptions | undefined) => AgentProvider;
 //# sourceMappingURL=AgentProvider.d.ts.map

package/dist/AgentProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentProvider.d.ts","sourceRoot":"","sources":["../src/AgentProvider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAwFtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1C,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/C,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAAC;CACpD;AAED,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAsD/C,eAAO,MAAM,EAAE,kCAcb,CAAC;AAwCH,eAAO,MAAM,KAAK,kCAchB,CAAC;AAMH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;CACrD;AAED,eAAO,MAAM,UAAU,2EAoBrB,CAAC"}
+{"version":3,"file":"AgentProvider.d.ts","sourceRoot":"","sources":["../src/AgentProvider.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AA6DtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+HAA+H;IAC/H,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1C,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/C,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAAC;CACpD;AAED,eAAO,MAAM,aAAa,oBAAoB,CAAC;AA2D/C,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,eAAO,MAAM,EAAE,mEAeb,CAAC;AAwCH,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,eAAO,MAAM,KAAK,sEAkBhB,CAAC;AAMH,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,eAAO,MAAM,QAAQ,yEAkBnB,CAAC;AAMH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IACpD,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,eAAO,MAAM,UAAU,2EAqBrB,CAAC"}