feat: add claudeCodeVertex agent provider for Google Vertex AI

[mikkelhartung]

Summary

• Adds a new claudeCodeVertex() agent provider that routes Claude Code through Google Vertex AI, enabling AFK / unattended runs against models hosted in a customer's GCP project.
• Uses the same claude CLI binary as claudeCode() and produces an identical session format — session capture, --resume, and effort work the same way.
• The factory injects only non-secret routing config (CLAUDE_CODE_USE_VERTEX=1, CLOUD_ML_REGION, ANTHROPIC_VERTEX_PROJECT_ID). Google credentials are always supplied via the sandbox environment (GOOGLE_APPLICATION_CREDENTIALS or Application Default Credentials), matching the pattern claudeCode() uses for ANTHROPIC_API_KEY.
• sandcastle init offers a "Claude Code (Vertex AI)" template choice with a matching Dockerfile.

API

import { claudeCodeVertex, run } from "@ai-hero/sandcastle";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";

await run({
  agent: claudeCodeVertex("claude-opus-4-7", {
    region: "global",
    projectId: "my-gcp-project",
    // Optional — Claude Code verifies a small/fast model at startup too:
    env: { ANTHROPIC_DEFAULT_HAIKU_MODEL: "claude-haiku-4-5@20251001" },
  }),
  sandbox: docker(),
  prompt: "…",
});

Vertex-specific gotchas (documented in the README)

These aren't obvious from the Anthropic Vertex docs and tripped me up during smoke testing — surfaced as explicit callouts in the new ClaudeCodeVertexOptions README section:

1. Model IDs must match Model Garden entries. Vertex commonly requires a dated suffix (e.g. claude-opus-4-1@20250805). For AFK runs, pin a dated version.
2. Region must match where the model is actually served. A model enabled in Model Garden isn't automatically on every endpoint — many newer models are only on region: "global". Wrong region surfaces as "model is not available on your vertex deployment".
3. Claude Code verifies both a primary and a small/fast (haiku) model at startup. If the default haiku ID isn't enabled in your project, startup fails with "may not exist or you may not have access to it" — even when the primary model is fine. Workaround: set ANTHROPIC_DEFAULT_HAIKU_MODEL via env.

Test plan

• npx vitest run src/AgentProvider.test.ts — 133 tests pass (23 new tests for claudeCodeVertex covering name, env vars with/without projectId, env merging, buildPrintCommand flags, parseStreamLine, parseSessionUsage, captureSessions default/override, buildInteractiveArgs, model independence).
• npm run typecheck — only pre-existing @daytona/sdk errors remain (unrelated to this change).
• End-to-end smoke test against a real GCP project — confirmed Claude Code routes successfully through Vertex AI with the documented config (region: "global", ANTHROPIC_DEFAULT_HAIKU_MODEL override). Exit code 0, Claude responded.
• Changeset added (@ai-hero/sandcastle patch).

🤖 Generated with Claude Code

[vercel]

@mikkelhartung is attempting to deploy a commit to the Matt Pocock's projects Team on Vercel.

A member of the Team first needs to authorize it.