@ai-hero/sandcastle 0.2.4 → 0.4.0

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
@@ -50,9 +50,11 @@ npx tsx .sandcastle/main.ts
 ```typescript
 // 3. Run the agent via the JS API
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 await run({
   agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
   promptFile: ".sandcastle/prompt.md",
 });
 ```
@@ -63,9 +65,11 @@ Sandcastle exports a programmatic `run()` function for use in scripts, CI pipeli
 
 ```typescript
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 const result = await run({
   agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
   promptFile: ".sandcastle/prompt.md",
 });
 
@@ -78,12 +82,20 @@ console.log(result.branch); // target branch name
 
 ```typescript
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 const result = await run({
   // Agent provider — required. Pass a model string to claudeCode().
   // Optional second arg for provider-specific options like effort level.
   agent: claudeCode("claude-opus-4-6", { effort: "high" }),
 
+  // Sandbox provider — required. Import from "@ai-hero/sandcastle/sandboxes/docker".
+  // Provider-specific config (like imageName and branchStrategy) lives inside the provider factory call.
+  sandbox: docker({
+    imageName: "sandcastle:local",
+    branchStrategy: { type: "branch", branch: "agent/fix-42" },
+  }),
+
   // Prompt source — provide one of these, not both:
   promptFile: ".sandcastle/prompt.md", // path to a prompt file
   // prompt: "Fix issue #42 in this repo", // OR an inline prompt string
@@ -96,25 +108,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" },
-
-  // Docker image used for the sandbox. Default: "sandcastle:<repo-dir-name>"
-  imageName: "sandcastle:local",
-
   // 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/
@@ -137,7 +141,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.
 
@@ -145,9 +149,11 @@ Use `run()` instead when you only need a single one-shot invocation — it handl
 
 ```typescript
 import { createSandbox, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 await using sandbox = await createSandbox({
   branch: "agent/fix-42",
+  sandbox: docker(),
 });
 
 const result = await sandbox.run({
@@ -162,9 +168,11 @@ console.log(result.commits); // [{ sha: "abc123" }]
 
 ```typescript
 import { createSandbox, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 await using sandbox = await createSandbox({
   branch: "agent/fix-42",
+  sandbox: docker(),
   hooks: { onSandboxReady: [{ command: "npm install" }] },
 });
 
@@ -186,12 +194,15 @@ 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`
 
 ```typescript
-const sandbox = await createSandbox({ branch: "agent/fix-42" });
+const sandbox = await createSandbox({
+  branch: "agent/fix-42",
+  sandbox: docker(),
+});
 // ... run agents ...
 const closeResult = await sandbox.close();
 if (closeResult.preservedWorktreePath) {
@@ -201,21 +212,21 @@ if (closeResult.preservedWorktreePath) {
 
 #### `CreateSandboxOptions`
 
-| Option          | Type     | Default                      | Description                                                         |
-| --------------- | -------- | ---------------------------- | ------------------------------------------------------------------- |
-| `branch`        | string   | —                            | **Required.** Explicit branch for the worktree                      |
-| `imageName`     | string   | `sandcastle:<repo-dir-name>` | Docker image name                                                   |
-| `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()`)                   |
+| `hooks`         | object          | —       | Lifecycle hooks (`onSandboxReady`) — run once at creation time     |
+| `copyToSandbox` | string[]        | —       | Host-relative file paths to copy into the sandbox at creation time |
 
 #### `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`
@@ -250,14 +261,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 `docker({ branchStrategy: { type: 'branch', branch: 'foo' } })`, and get a commit on branch `foo` once it's complete. All 100% local.
 
 ## Prompts
 
@@ -278,7 +290,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
@@ -323,10 +335,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`:
 
@@ -392,12 +404,12 @@ 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.
 
-### `sandcastle build-image`
+### `sandcastle docker build-image`
 
 Rebuilds the Docker image from an existing `.sandcastle/` directory. Use this after modifying the Dockerfile.
 
@@ -406,7 +418,7 @@ Rebuilds the Docker image from an existing `.sandcastle/` directory. Use this af
 | `--image-name` | No       | `sandcastle:<repo-dir-name>` | Docker image name                                                                 |
 | `--dockerfile` | No       | —                            | Path to a custom Dockerfile (build context will be the current working directory) |
 
-### `sandcastle remove-image`
+### `sandcastle docker remove-image`
 
 Removes the Docker image.
 
@@ -419,15 +431,14 @@ Removes the Docker image.
 | 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 }`                           |
-| `imageName`          | string             | `sandcastle:<repo-dir-name>`  | Docker image name for the sandbox                                                                                       |
 | `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'`)                     |
+| `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                                                             |
@@ -457,6 +468,275 @@ agent: claudeCode("claude-opus-4-6", { effort: "high" });
 
 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).
 
+## 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 `copyOut`. 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, return `ExecResult` when done      |
+| `execStreaming` | Both     | Run a command, call `onLine` for each stdout line |
+| `close`         | Both     | Tear down the sandbox                             |
+| `copyIn`        | Isolated | Copy a file 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` and `execStreaming` 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",
+    branchStrategy: { type: "merge-to-head" },
+    create: async (
+      options: BindMountCreateOptions,
+    ): Promise<BindMountSandboxHandle> => {
+      const workspacePath = options.worktreePath;
+
+      return {
+        workspacePath,
+
+        exec: (command: string, opts?: { cwd?: string }): Promise<ExecResult> =>
+          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,
+                  });
+                }
+              },
+            );
+          }),
+
+        execStreaming: (
+          command: string,
+          onLine: (line: string) => void,
+          opts?: { cwd?: string },
+        ): Promise<ExecResult> =>
+          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,
+              });
+            });
+          }),
+
+        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",
+    branchStrategy: { type: "merge-to-head" },
+    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?: { cwd?: string }): Promise<ExecResult> =>
+          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,
+                  });
+                }
+              },
+            );
+          }),
+
+        execStreaming: (
+          command: string,
+          onLine: (line: string) => void,
+          opts?: { cwd?: string },
+        ): Promise<ExecResult> =>
+          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,
+              });
+            });
+          }),
+
+        copyIn: async (hostPath: string, sandboxPath: string) => {
+          await mkdir(dirname(sandboxPath), { recursive: true });
+          await copyFile(hostPath, sandboxPath);
+        },
+
+        copyOut: 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" }`.
+
+```typescript
+// head — direct write, bind-mount only
+const provider = localProcess();
+// merge-to-head — temp branch, merge back (default for isolated)
+const provider = tempDir();
+// branch — explicit named branch
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+const provider = docker({
+  branchStrategy: { type: "branch", branch: "agent/fix-42" },
+});
+```
+
+### 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:
+
+- [`src/sandboxes/docker.ts`](src/sandboxes/docker.ts) — bind-mount provider using Docker containers
+- [`src/sandboxes/test-isolated.ts`](src/sandboxes/test-isolated.ts) — isolated provider using temp directories (used in tests)
+
 ## Configuration
 
 ### Config directory (`.sandcastle/`)
@@ -490,7 +770,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;

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,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,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"}