diff --git a/.github/workflows/agent-runtime-images.yml b/.github/workflows/agent-runtime-images.yml
new file mode 100644
index 00000000..0c775d67
--- /dev/null
+++ b/.github/workflows/agent-runtime-images.yml
@@ -0,0 +1,98 @@
+name: Agent runtime images
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docker/agent-runtime/**"
+      - "tools/agent-shim/**"
+      - ".github/workflows/agent-runtime-images.yml"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Image version tag (e.g., v1.0.0 or dev-test)"
+        required: true
+        default: "dev"
+
+permissions:
+  contents: read
+  packages: write
+  id-token: write   # cosign keyless OIDC
+
+env:
+  REGISTRY: ghcr.io/paperclipai
+  VERSION: ${{ github.event.inputs.version || format('git-{0}', github.sha) }}
+
+jobs:
+  build-and-sign:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log into GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@v3
+
+      - name: Build + push all deployed harness images (linux/amd64)
+        id: bake
+        run: |
+          # Scope: the five harnesses the kubernetes sandbox provider supports
+          # out of the box (opencode, pi, codex, gemini, claude). acpx/hermes
+          # have Dockerfiles in the bake group but are not published by default.
+          # Platforms come from the bake HCL (linux/amd64).
+          # Use --push rather than a "*.push" --set so the wildcard does not hit
+          # the bake group (which has no such key -> "unknown key" error).
+          docker buildx bake \
+            -f docker/agent-runtime/buildx-bake.hcl \
+            base opencode pi codex gemini claude \
+            --push \
+            --metadata-file=bake-metadata.json
+          # Extract digests for cosign signing
+          BASE_DIGEST=$(jq -r '."base"."containerimage.digest"' bake-metadata.json)
+          OPENCODE_DIGEST=$(jq -r '."opencode"."containerimage.digest"' bake-metadata.json)
+          PI_DIGEST=$(jq -r '."pi"."containerimage.digest"' bake-metadata.json)
+          CODEX_DIGEST=$(jq -r '."codex"."containerimage.digest"' bake-metadata.json)
+          GEMINI_DIGEST=$(jq -r '."gemini"."containerimage.digest"' bake-metadata.json)
+          CLAUDE_DIGEST=$(jq -r '."claude"."containerimage.digest"' bake-metadata.json)
+          echo "base_digest=$BASE_DIGEST" >> "$GITHUB_OUTPUT"
+          echo "opencode_digest=$OPENCODE_DIGEST" >> "$GITHUB_OUTPUT"
+          echo "pi_digest=$PI_DIGEST" >> "$GITHUB_OUTPUT"
+          echo "codex_digest=$CODEX_DIGEST" >> "$GITHUB_OUTPUT"
+          echo "gemini_digest=$GEMINI_DIGEST" >> "$GITHUB_OUTPUT"
+          echo "claude_digest=$CLAUDE_DIGEST" >> "$GITHUB_OUTPUT"
+        env:
+          VERSION: ${{ env.VERSION }}
+          REGISTRY: ${{ env.REGISTRY }}
+
+      - name: Cosign sign base
+        run: |
+          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-base@${{ steps.bake.outputs.base_digest }}"
+
+      - name: Cosign sign opencode
+        run: |
+          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-opencode@${{ steps.bake.outputs.opencode_digest }}"
+
+      - name: Cosign sign pi
+        run: |
+          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-pi@${{ steps.bake.outputs.pi_digest }}"
+
+      - name: Cosign sign codex
+        run: |
+          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-codex@${{ steps.bake.outputs.codex_digest }}"
+
+      - name: Cosign sign gemini
+        run: |
+          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-gemini@${{ steps.bake.outputs.gemini_digest }}"
+
+      - name: Cosign sign claude
+        run: |
+          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-claude@${{ steps.bake.outputs.claude_digest }}"
diff --git a/docker/agent-runtime/Dockerfile.acpx b/docker/agent-runtime/Dockerfile.acpx
new file mode 100644
index 00000000..965be1f0
--- /dev/null
+++ b/docker/agent-runtime/Dockerfile.acpx
@@ -0,0 +1,14 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipai/agent-runtime-base:${BASE_TAG}
+
+USER root
+# acpx is the ACPX wrapper that bridges to claude / codex backends.
+# Verified npm package name: "acpx" (bin 'acpx' → dist/cli.js).
+RUN npm install -g acpx@latest \
+    && { chown -R 1000:1000 /usr/lib/node_modules || true; }
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v acpx >/dev/null 2>&1 || (echo "acpx not on PATH"; exit 1)
diff --git a/docker/agent-runtime/Dockerfile.base b/docker/agent-runtime/Dockerfile.base
new file mode 100644
index 00000000..31c41a53
--- /dev/null
+++ b/docker/agent-runtime/Dockerfile.base
@@ -0,0 +1,37 @@
+# syntax=docker/dockerfile:1.6
+ARG NODE_VERSION=22
+ARG TARGETARCH
+
+# ---------- Stage 1: build agent-shim ----------
+FROM golang:1.25-bookworm AS shim-build
+ARG TARGETARCH
+WORKDIR /src
+COPY tools/agent-shim/ ./
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=${TARGETARCH:-amd64} \
+    go build -ldflags='-s -w' -o /out/paperclip-agent-shim .
+
+# ---------- Stage 2: runtime base image ----------
+# Ubuntu + Node + git + tini + non-root paperclip user + the agent-shim. This is
+# everything the sandbox exec-in model needs: the pod idles and paperclip-server
+# execs the harness CLI in, so the harness images only add their CLI on top of
+# this. Git workspace population (an init-container workspace bootstrap) is
+# intentionally NOT built here yet: the current scope is a blank workspace.
+# Add it when git workspace population lands.
+FROM ubuntu:22.04 AS base
+ARG NODE_VERSION
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      ca-certificates curl git tini gnupg \
+    && rm -rf /var/lib/apt/lists/* \
+    && curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd -g 1000 paperclip \
+    && useradd -u 1000 -g 1000 -d /home/paperclip -m -s /bin/bash paperclip
+
+COPY --from=shim-build   /out/paperclip-agent-shim                          /usr/local/bin/paperclip-agent-shim
+
+USER 1000:1000
+WORKDIR /workspace
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["/usr/local/bin/paperclip-agent-shim"]
diff --git a/docker/agent-runtime/Dockerfile.claude b/docker/agent-runtime/Dockerfile.claude
new file mode 100644
index 00000000..1511ba62
--- /dev/null
+++ b/docker/agent-runtime/Dockerfile.claude
@@ -0,0 +1,17 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipai/agent-runtime-base:${BASE_TAG}
+
+USER root
+RUN npm install -g @anthropic-ai/claude-code@latest \
+    && { chown -R 1000:1000 /usr/lib/node_modules || true; }
+
+# @anthropic-ai/claude-code installs as 'claude', but the shim expects 'claude-code'.
+# Resolve the real install path and fail the build if claude is missing.
+RUN CLAUDE_BIN="$(command -v claude)" \
+    && ln -s "$CLAUDE_BIN" /usr/bin/claude-code
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v claude-code >/dev/null 2>&1 || (echo "claude-code not on PATH"; exit 1)
diff --git a/docker/agent-runtime/Dockerfile.codex b/docker/agent-runtime/Dockerfile.codex
new file mode 100644
index 00000000..f44487e2
--- /dev/null
+++ b/docker/agent-runtime/Dockerfile.codex
@@ -0,0 +1,12 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipai/agent-runtime-base:${BASE_TAG}
+
+USER root
+RUN npm install -g @openai/codex@latest \
+    && { chown -R 1000:1000 /usr/lib/node_modules || true; }
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v codex >/dev/null 2>&1 || (echo "codex not on PATH"; exit 1)
diff --git a/docker/agent-runtime/Dockerfile.gemini b/docker/agent-runtime/Dockerfile.gemini
new file mode 100644
index 00000000..cec7c283
--- /dev/null
+++ b/docker/agent-runtime/Dockerfile.gemini
@@ -0,0 +1,21 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipai/agent-runtime-base:${BASE_TAG}
+
+USER root
+RUN npm install -g @google/gemini-cli@latest \
+    && { chown -R 1000:1000 /usr/lib/node_modules || true; }
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v gemini >/dev/null 2>&1 || (echo "gemini not on PATH"; exit 1)
+
+# Pre-select the gemini-api-key auth mode: gemini-cli refuses headless runs with
+# "Invalid auth method selected." unless settings.json picks an auth type (the
+# GEMINI_DEFAULT_AUTH_TYPE env alone does NOT work, proven empirically). Both
+# schema generations are written (selectedAuthType = legacy, security.auth
+# .selectedType = current). Correct for managed-gateway AND BYOK api-key modes;
+# OAuth flows are interactive and out of scope for sandbox pods.
+RUN mkdir -p /home/paperclip/.gemini \
+    && printf '%s\n' '{"selectedAuthType":"gemini-api-key","security":{"auth":{"selectedType":"gemini-api-key"}}}' > /home/paperclip/.gemini/settings.json
diff --git a/docker/agent-runtime/Dockerfile.hermes b/docker/agent-runtime/Dockerfile.hermes
new file mode 100644
index 00000000..a5ace8da
--- /dev/null
+++ b/docker/agent-runtime/Dockerfile.hermes
@@ -0,0 +1,17 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipai/agent-runtime-base:${BASE_TAG}
+
+# hermes_local is in the legacy sessioned-adapter set but has no upstream
+# npm package wired into Paperclip locally yet (see
+# packages/adapter-utils/src/session-compaction.ts vs the absent
+# packages/adapters/hermes-local/). This stub image preserves a cloud
+# runtime slot for hermes_local; whoever ports the hermes binary to
+# Paperclip locally adds the `npm install -g <pkg>` and the PATH check
+# to this Dockerfile.
+#
+# Until then, runs targeting hermes_local on the cloud adapter will boot
+# the container but `agent-shim` will fail with "hermes not on PATH" when
+# it tries to invoke the CLI.
+
+USER 1000:1000
diff --git a/docker/agent-runtime/Dockerfile.opencode b/docker/agent-runtime/Dockerfile.opencode
new file mode 100644
index 00000000..f024f0c0
--- /dev/null
+++ b/docker/agent-runtime/Dockerfile.opencode
@@ -0,0 +1,13 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipai/agent-runtime-base:${BASE_TAG}
+
+USER root
+# opencode-ai npm package; binary on PATH is `opencode`.
+RUN npm install -g opencode-ai@latest \
+    && { chown -R 1000:1000 /usr/lib/node_modules || true; }
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v opencode >/dev/null 2>&1 || (echo "opencode not on PATH"; exit 1)
diff --git a/docker/agent-runtime/Dockerfile.pi b/docker/agent-runtime/Dockerfile.pi
new file mode 100644
index 00000000..9788d475
--- /dev/null
+++ b/docker/agent-runtime/Dockerfile.pi
@@ -0,0 +1,15 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipai/agent-runtime-base:${BASE_TAG}
+
+USER root
+# pi is the multi-provider Pi coding-agent router. Verified npm package:
+# @mariozechner/pi-coding-agent (binary 'pi' → dist/cli.js). Same package
+# is used by SANDBOX_INSTALL_COMMAND in pi-local/src/index.ts.
+RUN npm install -g @mariozechner/pi-coding-agent@latest \
+    && { chown -R 1000:1000 /usr/lib/node_modules || true; }
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v pi >/dev/null 2>&1 || (echo "pi not on PATH"; exit 1)
diff --git a/docker/agent-runtime/README.md b/docker/agent-runtime/README.md
new file mode 100644
index 00000000..5b5ce28a
--- /dev/null
+++ b/docker/agent-runtime/README.md
@@ -0,0 +1,85 @@
+# Agent Runtime Image Family
+
+Container images for running coding-agent harnesses in sandboxed environments (for example the kubernetes sandbox provider, stage 1 of the k8s contribution). Images are named `agent-runtime-{harness}:{version}` and published to `ghcr.io/paperclipai/` by the `agent-runtime-images` workflow. The registry is overridable: every reference flows through the `REGISTRY` bake variable.
+
+## Image Lineup
+
+- **`agent-runtime-base`**: Foundation. Ubuntu 22.04 + Node 22 + git + tini + non-root user (uid 1000) + the agent shim.
+- **`agent-runtime-opencode`**: Extends base with `opencode-ai` globally installed.
+- **`agent-runtime-pi`**: Extends base with `@mariozechner/pi-coding-agent`.
+- **`agent-runtime-codex`**: Extends base with `@openai/codex`.
+- **`agent-runtime-gemini`**: Extends base with `@google/gemini-cli` plus headless auth-mode settings.
+- **`agent-runtime-claude`**: Extends base with `@anthropic-ai/claude-code` (symlinked as `claude-code`).
+- **`agent-runtime-acpx`** / **`agent-runtime-hermes`**: Dockerfiles included in the bake group, not in the default publish scope (hermes is a stub until a CLI package exists).
+
+## Base Image Contents
+
+**OS & Runtime:**
+- Ubuntu 22.04
+- Node.js 22 (via NodeSource APT repo)
+- git
+- tini (PID-1 init, ensures signal propagation)
+- Non-root user `paperclip` (uid/gid 1000)
+
+**Paperclip Binaries:**
+- `/usr/local/bin/paperclip-agent-shim`: Go binary compiled from `tools/agent-shim/`. Reads `/run/paperclip/runtime-command.json` and `syscall.Exec`s the harness CLI.
+
+**Defaults:**
+- `USER`: 1000:1000 (paperclip, non-root)
+- `WORKDIR`: `/workspace` (mount workspace volumes here)
+- `ENTRYPOINT`: `/usr/bin/tini --` (PID-1 reaper, forwards signals)
+- `CMD`: `/usr/local/bin/paperclip-agent-shim`
+
+## Building Locally
+
+All targets build `linux/amd64` by default (see `buildx-bake.hcl`). Derived images chain off the `base` target through bake `contexts`, so the literal registry in each `FROM` line is overridden at build time and the whole family builds in one pass without pushing intermediates.
+
+```bash
+docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --load
+```
+
+### Custom tag or registry
+
+```bash
+REGISTRY=myregistry VERSION=mytag \
+  docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --load
+```
+
+## Quickstart Smoke Test
+
+Build and verify the `agent-runtime-claude` image runs locally:
+
+```bash
+docker buildx bake -f docker/agent-runtime/buildx-bake.hcl base claude --load
+docker run --rm ghcr.io/paperclipai/agent-runtime-claude:dev claude-code --version
+```
+
+## Agent Container (paperclip-agent-shim)
+
+The main agent process runs as the shim (PID 1 under tini). The shim:
+
+1. Reads `/run/paperclip/runtime-command.json` (path overridable via `-spec`), a JSON file mounted by whatever schedules the run
+2. Parses `{ "command", "args" }`: the harness CLI and arguments
+3. Resolves the command on PATH and `syscall.Exec`s it, replacing itself
+4. SIGTERM from the kubelet propagates directly to the harness (no zombie processes)
+
+**runtime-command.json Contract:**
+```json
+{
+  "command": "claude-code",
+  "args": ["--token", "xyz", "--workspace", "/workspace"]
+}
+```
+
+The shim makes no assumptions about command structure; it is harness-agnostic. New harnesses swap the command/args; the base image stays the same.
+
+## Security Model
+
+- **Non-root execution**: user 1000:1000, no capability grants
+- **PSS Restricted compatible**: no privileged containers, no host mounts; works with a read-only root filesystem (writable `/workspace` + `/tmp` mounts)
+- **No secrets baked in**: API tokens and credentials come from per-run ephemeral Secrets mounted as env vars or files
+- **Image signing**: cosign keyless OIDC in the publish workflow
+
+## Publishing
+
+`.github/workflows/agent-runtime-images.yml` builds and pushes the default scope (base, opencode, pi, codex, gemini, claude) on `workflow_dispatch` (with an explicit version tag) or on pushes to `master` touching these paths, then signs each digest with cosign keyless OIDC.
diff --git a/docker/agent-runtime/buildx-bake.hcl b/docker/agent-runtime/buildx-bake.hcl
new file mode 100644
index 00000000..e7d9f67e
--- /dev/null
+++ b/docker/agent-runtime/buildx-bake.hcl
@@ -0,0 +1,104 @@
+group "default" {
+  targets = ["base", "claude", "codex", "gemini", "acpx", "opencode", "pi", "hermes"]
+}
+
+variable "VERSION" { default = "dev" }
+variable "REGISTRY" { default = "ghcr.io/paperclipai" }
+
+target "base" {
+  context = "."
+  dockerfile = "docker/agent-runtime/Dockerfile.base"
+  platforms = ["linux/amd64"]
+  tags = ["${REGISTRY}/agent-runtime-base:${VERSION}"]
+}
+
+target "claude" {
+  context = "."
+  dockerfile = "docker/agent-runtime/Dockerfile.claude"
+  platforms = ["linux/amd64"]
+  tags = ["${REGISTRY}/agent-runtime-claude:${VERSION}"]
+  args = {
+    BASE_TAG = "${VERSION}"
+  }
+  contexts = {
+    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
+  }
+}
+
+target "codex" {
+  context = "."
+  dockerfile = "docker/agent-runtime/Dockerfile.codex"
+  platforms = ["linux/amd64"]
+  tags = ["${REGISTRY}/agent-runtime-codex:${VERSION}"]
+  args = {
+    BASE_TAG = "${VERSION}"
+  }
+  contexts = {
+    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
+  }
+}
+
+target "gemini" {
+  context = "."
+  dockerfile = "docker/agent-runtime/Dockerfile.gemini"
+  platforms = ["linux/amd64"]
+  tags = ["${REGISTRY}/agent-runtime-gemini:${VERSION}"]
+  args = {
+    BASE_TAG = "${VERSION}"
+  }
+  contexts = {
+    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
+  }
+}
+
+target "acpx" {
+  context = "."
+  dockerfile = "docker/agent-runtime/Dockerfile.acpx"
+  platforms = ["linux/amd64"]
+  tags = ["${REGISTRY}/agent-runtime-acpx:${VERSION}"]
+  args = {
+    BASE_TAG = "${VERSION}"
+  }
+  contexts = {
+    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
+  }
+}
+
+target "opencode" {
+  context = "."
+  dockerfile = "docker/agent-runtime/Dockerfile.opencode"
+  platforms = ["linux/amd64"]
+  tags = ["${REGISTRY}/agent-runtime-opencode:${VERSION}"]
+  args = {
+    BASE_TAG = "${VERSION}"
+  }
+  contexts = {
+    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
+  }
+}
+
+target "pi" {
+  context = "."
+  dockerfile = "docker/agent-runtime/Dockerfile.pi"
+  platforms = ["linux/amd64"]
+  tags = ["${REGISTRY}/agent-runtime-pi:${VERSION}"]
+  args = {
+    BASE_TAG = "${VERSION}"
+  }
+  contexts = {
+    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
+  }
+}
+
+target "hermes" {
+  context = "."
+  dockerfile = "docker/agent-runtime/Dockerfile.hermes"
+  platforms = ["linux/amd64"]
+  tags = ["${REGISTRY}/agent-runtime-hermes:${VERSION}"]
+  args = {
+    BASE_TAG = "${VERSION}"
+  }
+  contexts = {
+    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
+  }
+}
diff --git a/tools/agent-shim/.gitignore b/tools/agent-shim/.gitignore
new file mode 100644
index 00000000..f61750a1
--- /dev/null
+++ b/tools/agent-shim/.gitignore
@@ -0,0 +1,2 @@
+/bin/
+/agent-shim
diff --git a/tools/agent-shim/go.mod b/tools/agent-shim/go.mod
new file mode 100644
index 00000000..363a57f5
--- /dev/null
+++ b/tools/agent-shim/go.mod
@@ -0,0 +1,3 @@
+module github.com/paperclipai/paperclip/tools/agent-shim
+
+go 1.22
diff --git a/tools/agent-shim/main.go b/tools/agent-shim/main.go
new file mode 100644
index 00000000..3cc3b8c9
--- /dev/null
+++ b/tools/agent-shim/main.go
@@ -0,0 +1,40 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"os/exec"
+	"syscall"
+)
+
+const (
+	defaultRuntimeCommandPath = "/run/paperclip/runtime-command.json"
+)
+
+func main() {
+	specPath := flag.String("spec", defaultRuntimeCommandPath, "path to AdapterRuntimeCommandSpec JSON")
+	adapterType := flag.String("adapter", "", "adapter type (informational; e.g. claude_local)")
+	flag.Parse()
+
+	spec, err := loadRuntimeCommandSpec(*specPath)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "[shim] cannot read runtime command spec: %v\n", err)
+		os.Exit(2)
+	}
+
+	resolved, err := exec.LookPath(spec.Command)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "[shim] adapter command %q not found in PATH (adapter=%s)\n", spec.Command, *adapterType)
+		os.Exit(127)
+	}
+
+	// Build argv (resolved binary as argv[0])
+	argv := append([]string{resolved}, spec.Args...)
+
+	// syscall.Exec replaces this process; SIGTERM from k8s reaches the adapter directly.
+	if err := syscall.Exec(resolved, argv, os.Environ()); err != nil {
+		fmt.Fprintf(os.Stderr, "[shim] exec %q failed: %v\n", resolved, err)
+		os.Exit(126)
+	}
+}
diff --git a/tools/agent-shim/main_test.go b/tools/agent-shim/main_test.go
new file mode 100644
index 00000000..57c01be0
--- /dev/null
+++ b/tools/agent-shim/main_test.go
@@ -0,0 +1,29 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLoadRuntimeCommandSpec_OK(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "spec.json")
+	_ = os.WriteFile(p, []byte(`{"command":"claude-code","args":["--print"]}`), 0o600)
+	spec, err := loadRuntimeCommandSpec(p)
+	if err != nil {
+		t.Fatalf("expected ok, got %v", err)
+	}
+	if spec.Command != "claude-code" || len(spec.Args) != 1 {
+		t.Fatalf("unexpected spec: %+v", spec)
+	}
+}
+
+func TestLoadRuntimeCommandSpec_MissingCommand(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "spec.json")
+	_ = os.WriteFile(p, []byte(`{"command":""}`), 0o600)
+	if _, err := loadRuntimeCommandSpec(p); err == nil {
+		t.Fatal("expected error for empty command")
+	}
+}
diff --git a/tools/agent-shim/runtime_command.go b/tools/agent-shim/runtime_command.go
new file mode 100644
index 00000000..d6ad3007
--- /dev/null
+++ b/tools/agent-shim/runtime_command.go
@@ -0,0 +1,29 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+)
+
+type RuntimeCommandSpec struct {
+	Command        string   `json:"command"`
+	Args           []string `json:"args"`
+	DetectCommand  string   `json:"detectCommand,omitempty"`
+	InstallCommand string   `json:"installCommand,omitempty"`
+}
+
+func loadRuntimeCommandSpec(path string) (*RuntimeCommandSpec, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var spec RuntimeCommandSpec
+	if err := json.Unmarshal(b, &spec); err != nil {
+		return nil, err
+	}
+	if spec.Command == "" {
+		return nil, errors.New("runtime-command.json has empty 'command'")
+	}
+	return &spec, nil
+}