Expose `exec()` on reusable `createSandbox()` handles

[nakleiderer]

Please expose a public exec() method on the Sandbox handle returned by createSandbox().

Today, sandbox provider handles expose exec(), and Sandcastle's internal sandbox service uses exec() for lifecycle hooks and prompt command expansion, but the reusable Sandbox returned by createSandbox() only exposes run(), interactive(), close(), and async dispose. That makes it hard for harness authors to run non-agent verification commands inside the same sandbox after an agent run.

Use case

I'm building a Sandcastle workflow where an implementer agent runs first, then the harness must run verification gates before allowing the implementer stage to finish. These commands need to run inside the same sandbox/container/worktree as the agent, not on the host.

Current workaround

The only way I've found is to wrap the sandbox provider, intercept the underlying provider handle returned by create(), and keep a reference to its exec() method. That works, but it feels like reaching around Sandcastle's public API.

Proposed API

await using sandbox = await createSandbox({
  branch: "agent/fix-42",
  sandbox: docker(),
});

await sandbox.run({
  agent: codex("gpt-5.5"),
  promptFile: ".sandcastle/prompts/implement.md",
});

const result = await sandbox.exec("bun run typecheck", {
  onLine: (line) => console.log(line),
});

if (result.exitCode !== 0) {
  throw new Error("Verification failed");
}

Suggested type:

interface Sandbox {
 // ... existing properties 

  exec(
    command: string,
    options?: {
      cwd?: string;
      onLine?: (line: string) => void;
      sudo?: boolean;
      stdin?: string;
    },
  ): Promise<ExecResult>;
}

Important behavior

cwd should default to the sandbox repo path, not the host worktree path.

For bind-mount providers those are related, but for Docker/Podman the command should run from the container-side repo path, e.g. /home/agent/workspace. For isolated providers, it should likewise run in the sandbox-side checkout.

[github-actions]

Triage — read-only first pass

TL;DR

Low-difficulty, well-scoped. The plumbing already exists inside buildSandboxHandle — providerHandle.exec and sandboxRepoDir are both in the handle's closure today. The change is essentially one method on the Sandbox interface, one implementation in buildSandboxHandle, doc + changeset, and tests.

Claims — all verified true

Claim	Evidence
Provider handles expose exec()	BindMountSandboxHandle.exec src/SandboxProvider.ts:39, IsolatedSandboxHandle.exec :116, NoSandboxHandle.exec :208 — required on all three handle types.
Sandcastle uses exec() internally for hooks + prompt expansion	SandboxLifecycle.ts:46-57 (execOk), :308-310 (sandbox onSandboxReady hooks); PromptPreprocessor.preprocessPrompt used in createSandbox.ts:451.
Public Sandbox exposes only run/interactive/close/asyncDispose	src/createSandbox.ts:168-183.
Wrapping the provider is the only workaround	providerHandle is private to the closure — no other escape hatch.
cwd should default to the sandbox repo path	interactive() already does this (createSandbox.ts:465). Docker provider has no default (docker.ts:262 only adds -w if user provides one), so without a Sandcastle-layer default, docker exec lands in the container's WORKDIR — a real footgun.

Relevant files

• src/createSandbox.ts:168-183 — Sandbox interface, the one type change.
• src/createSandbox.ts:207-521 — buildSandboxHandle; the new method goes alongside run and interactive. providerHandle and sandboxRepoDir are already in SandboxHandleContext (:186-199).
• src/index.ts:86 — ExecResult is already re-exported from SandboxProvider, so the new method can return it directly with no new exports.
• README.md:337-347 — Sandbox API table needs an exec() row; the "Multi-run implement-then-review" example (:280-306) is the obvious spot for a verification-gate snippet.
• src/createSandbox.test.ts — natural home for tests; uses _test.buildSandbox to inject a mock SandboxService (:20-29).
• .changeset/ — minor per CLAUDE.md (pre-1.0, new feature). Package @ai-hero/sandcastle.

Possible approach

Delegate to providerHandle.exec with cwd defaulting to sandboxRepoDir — mirroring how interactive() already delegates to providerHandle.interactiveExec:

exec: async (command, options) => {
  if (providerHandle) {
    return providerHandle.exec(command, { cwd: sandboxRepoDir, ...options });
  }
  // _test.buildSandbox path: no providerHandle, only the Effect SandboxService
  return Effect.runPromise(
    sandbox.exec(command, { cwd: sandboxRepoDir, ...options }),
  );
},

The { cwd: sandboxRepoDir, ...options } spread lets the caller override the default — same shape interactive uses (less explicitly).

Open questions for the implementer

1. Test-mode path. _test.buildSandbox (createSandbox.ts:84-86, used at :763-765) returns a SandboxService (Effect-based) with no providerHandle. Either fall back to Effect.runPromise(sandbox.exec(...)) (above) or restrict exec to non-test mode. Falling back is cleaner because every path constructs a SandboxService. Both surface the same ExecResult semantics — exitCode != 0 is not an error in either, matching the issue's example.

2. AbortSignal support. The proposed type omits signal. The provider exec contract doesn't take one either, and adding it would require plumbing through every provider. Reasonable to ship without it for v1.

3. Post-close() behavior. run() doesn't currently guard against being called after close — the torn-down provider surfaces a low-level error. Two options for exec(): match run() (do nothing; surface provider error) or guard with a clearer message. Worth a quick call but not blocking.

4. Throw vs return on non-zero exit. The issue's example checks exitCode explicitly, so the answer is "return, don't throw" — consistent with the existing public ExecResult contract. The throw-on-nonzero behavior in SandboxLifecycle.execOk is a private internal helper.

5. stdin size. BindMountSandboxHandle.exec doc notes the stdin path avoids the Linux 128 KB per-arg limit. That carries through naturally since we delegate — no special handling at the wrapper.

Bonus reason to land this at the Sandcastle layer

Defaulting cwd to sandboxRepoDir unifies behavior across providers. Today, calling providerHandle.exec("ls") lands in different places: container WORKDIR for Docker (often /), worktreePath for no-sandbox, VERCEL_REPO_PATH for Vercel. A wrapper at Sandbox.exec with a sensible default gives harness authors consistent behavior across every provider — a strong argument against telling users to keep reaching for the provider handle.