@ai-hero/sandcastle 0.4.7 → 0.5.0

package/README.md

@@ -65,14 +65,16 @@ await run({
 
 ## Sandbox Providers
 
-Sandcastle uses a `SandboxProvider` to create isolated environments. The `sandbox` option on `run()` and `createSandbox()` accepts any provider. A no-sandbox option is also available for `interactive()` only. Built-in providers:
+Sandcastle uses a `SandboxProvider` to create isolated environments. The `sandbox` option on `run()` and `createSandbox()` accepts any provider. A no-sandbox option is also available for `interactive()` and `wt.interactive()`. Built-in providers:
 
-| Provider   | Import path                                | Type       | Accepted by                                 |
-| ---------- | ------------------------------------------ | ---------- | ------------------------------------------- |
-| Docker     | `@ai-hero/sandcastle/sandboxes/docker`     | Bind-mount | `run()`, `createSandbox()`, `interactive()` |
-| Podman     | `@ai-hero/sandcastle/sandboxes/podman`     | Bind-mount | `run()`, `createSandbox()`, `interactive()` |
-| Vercel     | `@ai-hero/sandcastle/sandboxes/vercel`     | Isolated   | `run()`, `createSandbox()`, `interactive()` |
-| No-sandbox | `@ai-hero/sandcastle/sandboxes/no-sandbox` | None       | `interactive()` only                        |
+| Provider   | Import path                                | Type       | Accepted by                                   |
+| ---------- | ------------------------------------------ | ---------- | --------------------------------------------- |
+| Docker     | `@ai-hero/sandcastle/sandboxes/docker`     | Bind-mount | `run()`, `createSandbox()`, `interactive()`   |
+| Podman     | `@ai-hero/sandcastle/sandboxes/podman`     | Bind-mount | `run()`, `createSandbox()`, `interactive()`   |
+| Vercel     | `@ai-hero/sandcastle/sandboxes/vercel`     | Isolated   | `run()`, `createSandbox()`, `interactive()`   |
+| No-sandbox | `@ai-hero/sandcastle/sandboxes/no-sandbox` | None       | `interactive()`, `wt.interactive()` (default) |
+
+Worktree methods (`wt.run()`, `wt.interactive()`, `wt.createSandbox()`) accept the same providers as their top-level counterparts. `wt.interactive()` defaults to `noSandbox()` when no sandbox is specified.
 
 ```typescript
 import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
@@ -91,7 +93,7 @@ await run({
 await interactive({
   agent: claudeCode("claude-opus-4-6"),
   sandbox: noSandbox(),
-  prompt: "...",
+  prompt: "...", // optional — omit to launch the TUI with no initial prompt
 });
 ```
 
@@ -111,7 +113,8 @@ const result = await run({
   promptFile: ".sandcastle/prompt.md",
 });
 
-console.log(result.iterationsRun); // number of iterations executed
+console.log(result.iterations.length); // number of iterations executed
+console.log(result.iterations); // per-iteration results with optional sessionId
 console.log(result.commits); // array of { sha } for commits created
 console.log(result.branch); // target branch name
 ```
@@ -132,11 +135,16 @@ const result = await run({
   sandbox: docker({
     imageName: "sandcastle:local",
     // Optional: mount host directories into the sandbox (e.g. package manager caches)
+    // hostPath supports absolute, tilde-expanded (~), and relative paths (resolved from cwd).
+    // sandboxPath supports absolute and relative paths (resolved from the sandbox repo directory).
     mounts: [
       { hostPath: "~/.npm", sandboxPath: "/home/agent/.npm", readonly: true },
+      { hostPath: "data", sandboxPath: "data" }, // mounts <cwd>/data → <sandbox-repo>/data
     ],
     // Optional: provider-level env vars merged at launch time
     env: { DOCKER_SPECIFIC: "value" },
+    // Optional: attach container to Docker network(s) — string or string[]
+    network: "my-network",
   }),
 
   // Branch strategy — controls how the agent's changes relate to branches.
@@ -158,15 +166,20 @@ const result = await run({
   // Display name for this run, shown as a prefix in log output.
   name: "fix-issue-42",
 
-  // Lifecycle hooks — arrays of shell commands run in parallel inside the sandbox.
+  // Lifecycle hooks grouped by where they run: host or sandbox.
   hooks: {
-    // Runs after the sandbox is ready.
-    onSandboxReady: [{ command: "npm install" }],
+    host: {
+      onWorktreeReady: [{ command: "cp .env.example .env" }],
+      onSandboxReady: [{ command: "echo setup done" }],
+    },
+    sandbox: {
+      onSandboxReady: [{ command: "npm install" }],
+    },
   },
 
   // Host-relative file paths to copy into the sandbox before the container starts.
   // Not supported with branchStrategy: { type: "head" }.
-  copyToWorkspace: [".env"],
+  copyToWorktree: [".env"],
 
   // How to record progress. Default: write to a file under .sandcastle/logs/
   logging: { type: "file", path: ".sandcastle/logs/my-run.log" },
@@ -180,7 +193,7 @@ const result = await run({
   idleTimeoutSeconds: 600,
 });
 
-console.log(result.iterationsRun); // number of iterations executed
+console.log(result.iterations.length); // number of iterations executed
 console.log(result.completionSignal); // matched signal string, or undefined if none fired
 console.log(result.commits); // array of { sha } for commits created
 console.log(result.branch); // target branch name
@@ -220,7 +233,7 @@ import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 await using sandbox = await createSandbox({
   branch: "agent/fix-42",
   sandbox: docker(),
-  hooks: { onSandboxReady: [{ command: "npm install" }] },
+  hooks: { sandbox: { onSandboxReady: [{ command: "npm install" }] } },
 });
 
 // Step 1: implement
@@ -263,8 +276,8 @@ if (closeResult.preservedWorktreePath) {
 | -------------------------- | --------------- | ------- | ------------------------------------------------------------------------ |
 | `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           |
-| `copyToWorkspace`          | string[]        | —       | Host-relative file paths to copy into the sandbox at creation time       |
+| `hooks`                    | SandboxHooks    | —       | Lifecycle hooks (`host.*`, `sandbox.*`) — run once at creation time      |
+| `copyToWorktree`           | 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`
@@ -293,13 +306,13 @@ if (closeResult.preservedWorktreePath) {
 
 #### `SandboxRunResult`
 
-| Field              | Type        | Description                                                        |
-| ------------------ | ----------- | ------------------------------------------------------------------ |
-| `iterationsRun`    | number      | Number of iterations executed                                      |
-| `completionSignal` | string?     | The matched completion signal string, or `undefined` if none fired |
-| `stdout`           | string      | Combined agent output from all iterations                          |
-| `commits`          | `{ sha }[]` | Commits created during the run                                     |
-| `logFilePath`      | string?     | Path to the log file (only when logging to a file)                 |
+| Field              | Type                | Description                                                        |
+| ------------------ | ------------------- | ------------------------------------------------------------------ |
+| `iterations`       | `IterationResult[]` | Per-iteration results (use `.length` for the count)                |
+| `completionSignal` | string?             | The matched completion signal string, or `undefined` if none fired |
+| `stdout`           | string              | Combined agent output from all iterations                          |
+| `commits`          | `{ sha }[]`         | Commits created during the run                                     |
+| `logFilePath`      | string?             | Path to the log file (only when logging to a file)                 |
 
 #### `CloseResult`
 
@@ -307,6 +320,124 @@ if (closeResult.preservedWorktreePath) {
 | ----------------------- | ------- | ------------------------------------------------------------------------ |
 | `preservedWorktreePath` | string? | Host path to the preserved worktree, set when it had uncommitted changes |
 
+### `createWorktree()` — independent worktree lifecycle
+
+Use `createWorktree()` when you need a worktree (git worktree) as an independent, first-class concept — separate from any sandbox. This is useful when you want to run an interactive session first and then hand the same worktree to a sandboxed AFK agent.
+
+Only `branch` and `merge-to-head` strategies are accepted; `head` is a compile-time type error since it means no worktree.
+
+```typescript
+import { createWorktree } from "@ai-hero/sandcastle";
+
+await using wt = await createWorktree({
+  branchStrategy: { type: "branch", branch: "agent/fix-42" },
+  copyToWorktree: ["node_modules"],
+});
+
+console.log(wt.worktreePath); // host path to the worktree
+console.log(wt.branch); // "agent/fix-42"
+
+// Run an interactive session in the worktree (defaults to noSandbox)
+await wt.interactive({
+  agent: claudeCode("claude-opus-4-6"),
+  prompt: "Explore the codebase and understand the bug.",
+});
+
+// Run an AFK agent in the worktree (sandbox is required)
+const result = await wt.run({
+  agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker({ imageName: "sandcastle:myrepo" }),
+  prompt: "Fix issue #42.",
+  maxIterations: 3,
+});
+console.log(result.commits); // commits made during the run
+
+// Create a long-lived sandbox from the worktree
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+
+await using sandbox = await wt.createSandbox({
+  sandbox: docker(),
+  hooks: { sandbox: { onSandboxReady: [{ command: "npm install" }] } },
+});
+
+// sandbox.close() tears down the container only — the worktree stays
+await sandbox.close();
+
+// wt.close() cleans up the worktree
+```
+
+`wt.close()` checks for uncommitted changes: if the worktree is dirty, it's preserved on disk; if clean, it's removed. `await using` calls `close()` automatically. The worktree persists after `run()`, `interactive()`, and `createSandbox()` complete, so you can hand it to another agent or inspect it.
+
+**Split ownership**: When a sandbox is created via `wt.createSandbox()`, `sandbox.close()` tears down the container only — the worktree remains. `wt.close()` is responsible for worktree cleanup. This differs from the top-level `createSandbox()`, where `sandbox.close()` owns both container and worktree.
+
+#### `CreateWorktreeOptions`
+
+| Option           | Type                   | Default | Description                                                               |
+| ---------------- | ---------------------- | ------- | ------------------------------------------------------------------------- |
+| `branchStrategy` | WorktreeBranchStrategy | —       | **Required.** `{ type: "branch", branch }` or `{ type: "merge-to-head" }` |
+| `copyToWorktree` | string[]               | —       | Host-relative file paths to copy into the worktree at creation time       |
+
+#### `Worktree`
+
+| Property / Method        | Type                                                                  | Description                                         |
+| ------------------------ | --------------------------------------------------------------------- | --------------------------------------------------- |
+| `branch`                 | string                                                                | The branch the worktree is on                       |
+| `worktreePath`           | string                                                                | Host path to the worktree                           |
+| `run(options)`           | `(options: WorktreeRunOptions) => Promise<WorktreeRunResult>`         | Run an AFK agent in the worktree (sandbox required) |
+| `interactive(options)`   | `(options: WorktreeInteractiveOptions) => Promise<InteractiveResult>` | Run an interactive agent session in the worktree    |
+| `createSandbox(options)` | `(options: WorktreeCreateSandboxOptions) => Promise<Sandbox>`         | Create a long-lived sandbox backed by this worktree |
+| `close()`                | `() => Promise<CloseResult>`                                          | Clean up the worktree (preserves if dirty)          |
+| `[Symbol.asyncDispose]`  | `() => Promise<void>`                                                 | Auto cleanup via `await using`                      |
+
+#### `WorktreeInteractiveOptions`
+
+| Option       | Type                   | Default       | Description                                          |
+| ------------ | ---------------------- | ------------- | ---------------------------------------------------- |
+| `agent`      | AgentProvider          | —             | **Required.** Agent provider                         |
+| `sandbox`    | AnySandboxProvider     | `noSandbox()` | Sandbox provider (defaults to no sandbox)            |
+| `prompt`     | string                 | —             | Inline prompt (mutually exclusive with `promptFile`) |
+| `promptFile` | string                 | —             | Path to prompt file                                  |
+| `name`       | string                 | —             | Optional session name                                |
+| `hooks`      | SandboxHooks           | —             | Lifecycle hooks (`host.*`, `sandbox.*`)              |
+| `promptArgs` | PromptArgs             | —             | Key-value map for `{{KEY}}` placeholder substitution |
+| `env`        | Record<string, string> | —             | Environment variables to inject into the sandbox     |
+
+#### `WorktreeRunOptions`
+
+| Option               | Type                   | Default | Description                                                   |
+| -------------------- | ---------------------- | ------- | ------------------------------------------------------------- |
+| `agent`              | AgentProvider          | —       | **Required.** Agent provider                                  |
+| `sandbox`            | SandboxProvider        | —       | **Required.** Sandbox provider (AFK agents must be sandboxed) |
+| `prompt`             | string                 | —       | Inline prompt (mutually exclusive with `promptFile`)          |
+| `promptFile`         | string                 | —       | Path to prompt file                                           |
+| `maxIterations`      | number                 | 1       | Maximum iterations to run                                     |
+| `completionSignal`   | string \| string[]     | —       | Substring(s) to stop the iteration loop early                 |
+| `idleTimeoutSeconds` | number                 | 600     | Idle timeout in seconds                                       |
+| `name`               | string                 | —       | Optional run name                                             |
+| `logging`            | LoggingOption          | file    | Logging mode                                                  |
+| `hooks`              | SandboxHooks           | —       | Lifecycle hooks (`host.*`, `sandbox.*`)                       |
+| `promptArgs`         | PromptArgs             | —       | Key-value map for `{{KEY}}` placeholder substitution          |
+| `env`                | Record<string, string> | —       | Environment variables to inject into the sandbox              |
+
+#### `WorktreeRunResult`
+
+| Property           | Type                | Description                                            |
+| ------------------ | ------------------- | ------------------------------------------------------ |
+| `iterations`       | `IterationResult[]` | Per-iteration results (use `.length` for the count)    |
+| `completionSignal` | string              | The matched completion signal, or undefined            |
+| `stdout`           | string              | Combined stdout output from all agent iterations       |
+| `commits`          | { sha: string }[]   | List of commits made by the agent during the run       |
+| `branch`           | string              | The branch name the agent worked on                    |
+| `logFilePath`      | string              | Path to the log file, if logging was drained to a file |
+
+#### `WorktreeCreateSandboxOptions`
+
+| Option           | Type            | Default | Description                                                         |
+| ---------------- | --------------- | ------- | ------------------------------------------------------------------- |
+| `sandbox`        | SandboxProvider | —       | **Required.** Sandbox provider (e.g. `docker()`)                    |
+| `hooks`          | SandboxHooks    | —       | Lifecycle hooks (`host.*`, `sandbox.*`)                             |
+| `copyToWorktree` | string[]        | —       | Host-relative file paths to copy into the worktree at creation time |
+
 ## How it works
 
 Sandcastle uses a **branch strategy** configured on the sandbox provider to control how the agent's changes relate to branches. There are three strategies:
@@ -338,7 +469,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. All expressions in a prompt run **in parallel** for faster expansion.
 
-Commands run **inside the sandbox** after `onSandboxReady` hooks complete, so they see the same repo state the agent sees (including installed dependencies).
+Commands run **inside the sandbox** after `sandbox.onSandboxReady` hooks complete, so they see the same repo state the agent sees (including installed dependencies).
 
 ```markdown
 # Open issues
@@ -501,26 +632,62 @@ Removes the Podman image.
 | `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`)                                                                                                                         |
+| `hooks`                    | SandboxHooks       | —                             | Lifecycle hooks (`host.*`, `sandbox.*`)                                                                                                                    |
 | `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: '…' }`                                                     |
-| `copyToWorkspace`          | string[]           | —                             | Host-relative file paths to copy into the sandbox before start (not supported with `branchStrategy: { type: 'head' }`)                                     |
+| `copyToWorktree`           | 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                                                             |
+| `resumeSession`            | string             | —                             | Resume a prior Claude Code session by ID. Incompatible with `maxIterations > 1`. Session file must exist on host.                                          |
 
 ### `RunResult`
 
-| Field              | Type        | Description                                                        |
-| ------------------ | ----------- | ------------------------------------------------------------------ |
-| `iterationsRun`    | number      | Number of iterations that were executed                            |
-| `completionSignal` | string?     | The matched completion signal string, or `undefined` if none fired |
-| `stdout`           | string      | Agent output                                                       |
-| `commits`          | `{ sha }[]` | Commits created during the run                                     |
-| `branch`           | string      | Target branch name                                                 |
-| `logFilePath`      | string?     | Path to the log file (only when logging to a file)                 |
+| Field              | Type                | Description                                                        |
+| ------------------ | ------------------- | ------------------------------------------------------------------ |
+| `iterations`       | `IterationResult[]` | Per-iteration results (use `.length` for the count)                |
+| `completionSignal` | string?             | The matched completion signal string, or `undefined` if none fired |
+| `stdout`           | string              | Agent output                                                       |
+| `commits`          | `{ sha }[]`         | Commits created during the run                                     |
+| `branch`           | string              | Target branch name                                                 |
+| `logFilePath`      | string?             | Path to the log file (only when logging to a file)                 |
+
+### `IterationResult`
+
+| Field             | Type    | Description                                                                          |
+| ----------------- | ------- | ------------------------------------------------------------------------------------ |
+| `sessionId`       | string? | Claude Code session ID from the init line, or `undefined` for non-Claude agents      |
+| `sessionFilePath` | string? | Absolute host path to the captured session JSONL, or `undefined` when capture is off |
+
+### Session capture
+
+After each Claude Code iteration, Sandcastle automatically captures the agent's session JSONL from the sandbox to the host at `~/.claude/projects/<encoded-path>/sessions/<session-id>.jsonl`. The `cwd` fields inside each JSONL entry are rewritten to match the host repo root, so `claude --resume` works natively.
+
+Session capture is enabled by default for `claudeCode()` and can be opted out via `captureSessions: false`. Non-Claude agent providers never attempt capture. Capture failure fails the run.
+
+### Session resume
+
+Pass `resumeSession` to `run()` to continue a prior Claude Code conversation inside a new sandbox:
+
+```typescript
+const result = await run({
+  agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
+  prompt: "Continue where you left off",
+  resumeSession: "abc-123-def",
+});
+```
+
+Before the sandbox starts, Sandcastle validates that the session file exists on the host and transfers it into the sandbox with `cwd` fields rewritten to match the sandbox-side path. The Claude Code agent receives `--resume <id>` on its print command for iteration 1.
+
+Constraints:
+
+- `resumeSession` is incompatible with `maxIterations > 1` (throws before sandbox creation).
+- The session file must exist at `~/.claude/projects/<encoded-path>/sessions/<id>.jsonl` (throws before sandbox creation).
+- Only iteration 1 receives the resume flag; subsequent iterations (if any) start fresh.
+- Non-Claude agent providers ignore `resumeSession`.
 
 ### `ClaudeCodeOptions`
 
@@ -530,10 +697,11 @@ The `claudeCode()` factory accepts an optional second argument for provider-spec
 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   |
+| 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     |
+| `captureSessions` | `boolean`                                    | `true`  | Capture agent session JSONL to host for `claude --resume` |
 
 ### `CodexOptions`
 
@@ -583,13 +751,14 @@ Sandcastle ships with built-in providers for Docker, Podman, and Vercel, but you
 
 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                            |
+| Method         | Required   | Description                                                                  |
+| -------------- | ---------- | ---------------------------------------------------------------------------- |
+| `exec`         | Both       | Run a command, optionally streaming stdout line-by-line via `options.onLine` |
+| `close`        | Both       | Tear down the sandbox                                                        |
+| `copyFileIn`   | Bind-mount | Copy a single file from the host into the sandbox                            |
+| `copyFileOut`  | Both       | Copy a single file from the sandbox to the host                              |
+| `copyIn`       | Isolated   | Copy a file or directory from the host into the sandbox                      |
+| `worktreePath` | Both       | Absolute path to the repo directory inside the sandbox                       |
 
 ### `ExecResult`
 
@@ -615,6 +784,8 @@ import {
   type ExecResult,
 } from "@ai-hero/sandcastle";
 import { execFile, spawn } from "node:child_process";
+import { copyFile as fsCopyFile, mkdir as fsMkdir } from "node:fs/promises";
+import { dirname } from "node:path";
 import { createInterface } from "node:readline";
 
 const localProcess = () =>
@@ -623,10 +794,10 @@ const localProcess = () =>
     create: async (
       options: BindMountCreateOptions,
     ): Promise<BindMountSandboxHandle> => {
-      const workspacePath = options.worktreePath;
+      const worktreePath = options.worktreePath;
 
       return {
-        workspacePath,
+        worktreePath,
 
         exec: (
           command: string,
@@ -636,7 +807,7 @@ const localProcess = () =>
             const onLine = opts.onLine;
             return new Promise((resolve, reject) => {
               const proc = spawn("sh", ["-c", command], {
-                cwd: opts?.cwd ?? workspacePath,
+                cwd: opts?.cwd ?? worktreePath,
                 stdio: ["ignore", "pipe", "pipe"],
               });
 
@@ -668,7 +839,7 @@ const localProcess = () =>
             execFile(
               "sh",
               ["-c", command],
-              { cwd: opts?.cwd ?? workspacePath, maxBuffer: 10 * 1024 * 1024 },
+              { cwd: opts?.cwd ?? worktreePath, maxBuffer: 10 * 1024 * 1024 },
               (error, stdout, stderr) => {
                 if (error && error.code === undefined) {
                   reject(new Error(`exec failed: ${error.message}`));
@@ -684,6 +855,16 @@ const localProcess = () =>
           });
         },
 
+        copyFileIn: async (hostPath: string, sandboxPath: string) => {
+          await fsMkdir(dirname(sandboxPath), { recursive: true });
+          await fsCopyFile(hostPath, sandboxPath);
+        },
+
+        copyFileOut: async (sandboxPath: string, hostPath: string) => {
+          await fsMkdir(dirname(hostPath), { recursive: true });
+          await fsCopyFile(sandboxPath, hostPath);
+        },
+
         close: async () => {
           // nothing to tear down for a local process
         },
@@ -713,11 +894,11 @@ const tempDir = () =>
     name: "temp-dir",
     create: async (): Promise<IsolatedSandboxHandle> => {
       const root = await mkdtemp(join(tmpdir(), "sandbox-"));
-      const workspacePath = join(root, "workspace");
-      await mkdir(workspacePath, { recursive: true });
+      const worktreePath = join(root, "workspace");
+      await mkdir(worktreePath, { recursive: true });
 
       return {
-        workspacePath,
+        worktreePath,
 
         exec: (
           command: string,
@@ -727,7 +908,7 @@ const tempDir = () =>
             const onLine = opts.onLine;
             return new Promise((resolve, reject) => {
               const proc = spawn("sh", ["-c", command], {
-                cwd: opts?.cwd ?? workspacePath,
+                cwd: opts?.cwd ?? worktreePath,
                 stdio: ["ignore", "pipe", "pipe"],
               });
 
@@ -759,7 +940,7 @@ const tempDir = () =>
             execFile(
               "sh",
               ["-c", command],
-              { cwd: opts?.cwd ?? workspacePath, maxBuffer: 10 * 1024 * 1024 },
+              { cwd: opts?.cwd ?? worktreePath, maxBuffer: 10 * 1024 * 1024 },
               (error, stdout, stderr) => {
                 if (error && error.code === undefined) {
                   reject(new Error(`exec failed: ${error.message}`));
@@ -891,28 +1072,36 @@ Add your project-specific dependencies (e.g., language runtimes, build tools) to
 
 ### Hooks
 
-Hooks are arrays of `{ command, sudo? }` objects executed **in parallel** inside the sandbox. All commands within a hook point run concurrently — if any command exits with a non-zero code, the operation fails after all commands settle. To enforce ordering between commands, combine them with `&&` in a single command string.
-
-| Hook             | When it runs               | Working directory      |
-| ---------------- | -------------------------- | ---------------------- |
-| `onSandboxReady` | After the sandbox is ready | Sandbox repo directory |
-
-**`onSandboxReady`** runs after the sandbox is ready. Use it for dependency installation or build steps (e.g., `npm install`).
-
-Set `sudo: true` to run a command with elevated privileges inside the sandbox:
+Hooks are grouped by **where** they run — `host` (on the developer's machine) or `sandbox` (inside the container):
 
 ```ts
-await run({
-  hooks: {
+hooks: {
+  host: {
+    onWorktreeReady: [{ command: "cp .env.example .env" }],
+    onSandboxReady:  [{ command: "echo sandbox is up" }],
+  },
+  sandbox: {
     onSandboxReady: [
-      { command: "apt-get install -y ffmpeg", sudo: true },
       { command: "npm install" },
+      { command: "apt-get install -y ffmpeg", sudo: true },
     ],
   },
-  // ...
-});
+}
 ```
 
+| Hook                     | Runs on | When                                         | Working directory                           |
+| ------------------------ | ------- | -------------------------------------------- | ------------------------------------------- |
+| `host.onWorktreeReady`   | Host    | After `copyToWorktree`, before sandbox start | Worktree path (host repo root under `head`) |
+| `host.onSandboxReady`    | Host    | After sandbox is up                          | Worktree path (host repo root under `head`) |
+| `sandbox.onSandboxReady` | Sandbox | After sandbox is up                          | Sandbox repo directory                      |
+
+**Ordering:** `copyToWorktree` -> `host.onWorktreeReady` (sequential) -> sandbox created -> `host.onSandboxReady` + `sandbox.onSandboxReady` (parallel).
+
+- **Host hooks** accept `{ command: string }` — no `sudo`, no `cwd`. Use `cd` or inline env in the command string.
+- **Sandbox hooks** accept `{ command: string; sudo?: boolean }` — set `sudo: true` for elevated privileges.
+- Within each hook point, sandbox hooks run in parallel; host hooks within `onSandboxReady` also run in parallel with sandbox hooks. `host.onWorktreeReady` hooks run sequentially in declared order.
+- If any hook exits non-zero, setup fails fast.
+
 ## Development
 
 ```bash

package/dist/AgentProvider.d.ts

@@ -8,16 +8,23 @@ export type ParsedStreamEvent = {
     type: "tool_call";
     name: string;
     args: string;
+} | {
+    type: "session_id";
+    sessionId: string;
 };
 /** Options passed to buildPrintCommand and buildInteractiveArgs. */
 export interface AgentCommandOptions {
     readonly prompt: string;
     readonly dangerouslySkipPermissions: boolean;
+    /** When set, the agent should resume the given session ID instead of starting fresh. */
+    readonly resumeSession?: string;
 }
 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>;
+    /** When true, session capture is enabled for this provider. Default: true for Claude Code, false for others. */
+    readonly captureSessions: boolean;
     buildPrintCommand(options: AgentCommandOptions): string;
     buildInteractiveArgs?(options: AgentCommandOptions): string[];
     parseStreamLine(line: string): ParsedStreamEvent[];
@@ -46,6 +53,8 @@ export interface ClaudeCodeOptions {
     readonly effort?: "low" | "medium" | "high" | "max";
     /** Environment variables injected by this agent provider. */
     readonly env?: Record<string, string>;
+    /** When false, session capture is disabled. Default: true. */
+    readonly captureSessions?: boolean;
 }
 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,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,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;CAC9C;AAED,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,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACxD,oBAAoB,CAAC,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAAC;IAC9D,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,mEAiBb,CAAC;AAwCH,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IACtD,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,eAAO,MAAM,KAAK,sEAuBhB,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,yEAoBnB,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,2EAiCrB,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,GACjD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAoE9C,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;IAC7C,wFAAwF;IACxF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,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,gHAAgH;IAChH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACxD,oBAAoB,CAAC,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAAC;IAC9D,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,mEAkBb,CAAC;AAwCH,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IACtD,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,eAAO,MAAM,KAAK,sEAwBhB,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,yEAqBnB,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;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,eAAO,MAAM,UAAU,2EAsCrB,CAAC"}

package/dist/AgentProvider.js

@@ -46,6 +46,11 @@ const parseStreamJsonLine = (line) => {
         if (obj.type === "result" && typeof obj.result === "string") {
             return [{ type: "result", result: obj.result }];
         }
+        if (obj.type === "system" &&
+            obj.subtype === "init" &&
+            typeof obj.session_id === "string") {
+            return [{ type: "session_id", sessionId: obj.session_id }];
+        }
     }
     catch {
         // Not valid JSON — skip
@@ -111,6 +116,7 @@ const parsePiStreamLine = (line) => {
 export const pi = (model, options) => ({
     name: "pi",
     env: options?.env ?? {},
+    captureSessions: false,
     buildPrintCommand({ prompt }) {
         return `pi -p --mode json --no-session --model ${shellEscape(model)} ${shellEscape(prompt)}`;
     },
@@ -158,6 +164,7 @@ const parseCodexStreamLine = (line) => {
 export const codex = (model, options) => ({
     name: "codex",
     env: options?.env ?? {},
+    captureSessions: false,
     buildPrintCommand({ prompt }) {
         const effortFlag = options?.effort
             ? ` -c ${shellEscape(`model_reasoning_effort="${options.effort}"`)}`
@@ -177,6 +184,7 @@ export const codex = (model, options) => ({
 export const opencode = (model, options) => ({
     name: "opencode",
     env: options?.env ?? {},
+    captureSessions: false,
     buildPrintCommand({ prompt }) {
         return `opencode run --model ${shellEscape(model)} ${shellEscape(prompt)}`;
     },
@@ -193,12 +201,16 @@ export const opencode = (model, options) => ({
 export const claudeCode = (model, options) => ({
     name: "claude-code",
     env: options?.env ?? {},
-    buildPrintCommand({ prompt, dangerouslySkipPermissions, }) {
+    captureSessions: options?.captureSessions ?? true,
+    buildPrintCommand({ prompt, dangerouslySkipPermissions, resumeSession, }) {
         const skipPerms = dangerouslySkipPermissions
             ? " --dangerously-skip-permissions"
             : "";
         const effortFlag = options?.effort ? ` --effort ${options.effort}` : "";
-        return `claude --print --verbose${skipPerms} --output-format stream-json --model ${shellEscape(model)}${effortFlag} -p ${shellEscape(prompt)}`;
+        const resumeFlag = resumeSession
+            ? ` --resume ${shellEscape(resumeSession)}`
+            : "";
+        return `claude --print --verbose${skipPerms} --output-format stream-json --model ${shellEscape(model)}${effortFlag}${resumeFlag} -p ${shellEscape(prompt)}`;
     },
     buildInteractiveArgs({ prompt, dangerouslySkipPermissions, }) {
         const args = ["claude"];