feat(agents)!: ship Claude Code in the wheel as the default agent

[earakely-scale]

Why

agent-env shipped no agent. A deploy_agent step or an agent judge that named no agent deployed a2a-default, which a fresh install doesn't have, and wrapping a harness was left to users.

What

The agents bundle, in the wheel beside hello and echo-mcp. Its one agent folder, agents/claude-code/, is @local/agentenv-framework/agents/claude-code, and its smoke task runs with agent-env run agents.

• The image.
  • python:3.11-slim at a pinned multi-arch digest, plus Anthropic's native Claude Code binary at a pinned CLAUDE_CODE_VERSION, checked against the release manifest's sha256.
  • It runs as a non-root user, or as root where the provider ignores USER (IS_SANDBOX). CLAUDE_CONFIG_DIR is fixed, so the CLI's state doesn't follow the uid. The auto-updater and nonessential traffic are off.
  • The model's scripts get node (copied from a pinned node:22-slim, without npm or npx) and Python with a pinned boto3 (model-requirements.txt).
  • 254 MB, built natively on x86 and arm64 in 33–38 s.
• The agent (a2a_server.py, claude_bridge.py, kit.py): an AgentEnvAgent running claude -p --output-format stream-json, ported from Scale's internal Claude Code wrapper.
  • It keeps:
    • the task env's MCP servers, through --mcp-config with the role header;
    • live and context trajectories;
    • skills, snapshots and triggers;
    • a resume after a transient API error, within the caller's budget;
    • cancellation that kills the CLI's whole process tree.
  • New: max_turns, max_thinking_tokens, and an error that explains a 404 from the endpoint.
• The model endpoint.
  • [model] reaches the CLI as ANTHROPIC_BASE_URL and a bearer ANTHROPIC_AUTH_TOKEN. The API key is blanked. LITELLM_API_KEY, LITELLM_BASE_URL and LITELLM_EXTRA_HEADERS stay in the CLI's environment, so a script the model runs can call the endpoint.
  • Claude Code's model aliases are pinned to the run's model on that endpoint.
  • [model.headers], and the run's project and task attribution, go on every call (ANTHROPIC_CUSTOM_HEADERS).
  • It needs an endpoint serving Anthropic's Messages API, such as a LiteLLM gateway.
• TLS checks stay on. The on-machine providers already give agent containers NODE_EXTRA_CA_CERTS.
• install/v1. install_agent installs the agent into a container a task already runs, or onto a vm sandbox's Linux host, with install.sh from its folder.
  • It brings Claude Code's native build for the target's CPU and libc, and uv, each checked against its published sha256. The agent's requirements go into a Python of uv's own, so the target's Python is never touched.
  • Claude Code runs its commands in bash or zsh, so a target with neither (Alpine, say) gets bash from its own package manager. A target with no package manager fails, saying so.
  • The model key, base URL and [model.headers] reach the agent through a 0600 env file, not its command line.
  • The install returns once the agent answers on its port. An agent that exits first fails it, with the end of its log.
  • Each container install lives under its port, so two agents can share a container.
  • The agent works in the container's working directory, or /app on a host. The CLI's transcripts follow that directory.
  • In core, install_agent gains a trust_env param: on a sandbox on this machine it puts the local transfer CA in the container, or beside the work dir on a host, and passes the variables that find it.
  • A host install on a local sandbox gets the local store's grants only when grant_advertise_host names an address the host reaches, such as the bridge address, since host.docker.internal resolves only in containers. AGENTS.md says so.
• A snapshot load keeps the live transcript of every other conversation the agent holds, even when the archive has an older copy of it.
• requirements.txt is the protocol alone, and a release pins it. publish-pypi.yml now rewrites every shipped example's requirements, not only echo-mcp's.

The default agent is now this one.

• _DEFAULT_A2A_AGENT_ID changes. A bundle run pulls the agent from the installed bundle for any agent field left unset. So a bare deploy_agent deploys Claude Code, and so does a rubrics_verifier that names no judge agent, since it's an agent judge by default.
• An explicit direct LLM judge (use_agent_judge: false) still pulls it, but nothing is built for it.
• The Explorer features the agent, and AGENTS.md and the example config say what the default is.

Breaking: a store agent named a2a-default is no longer the default. Set [agents] default_a2a_agent_id = "a2a-default" to keep it. A host that sets the default in its config is unaffected.

Not in this PR:

• Peer agents and the changelog come next. A file part naming a stored object needs nothing new: core already sends it as an https grant, and this PR adds the tests.
• The retired attribution-probe/v1 isn't served: nothing calls it, and attribution goes through agent-config's project_id.
• install_agent takes no env_ids, so an installed agent gets no env MCP tools; deploy_agent is the step for those.
• Caching VM-built images comes after that, so each new remote VM builds the image cold, in about 40 s on modal_vm.

Tests

• Unit: the agent's suite, 165 tests in tst/unit/examples/claude_code/, covers the card and its install commands, turns, retries and the failure messages, trajectories, snapshots, transfers, the CLI's environment and workspace, and the image contract. install_agent_test.py covers trust_env. Unit and protocol tiers: 8766 passed.

• Integration: run_bundle_claude_code_test.py runs the real image and the real CLI against a fake Anthropic Messages endpoint (tst/util/fake_anthropic.py) on local docker, so no model key is needed. It covers:

  • a task naming no agent;
  • the bearer key, [model.headers] and the model reaching the endpoint;
  • a second bundle reusing the image;
  • a call to the tool of echo-mcp's env, through the gateway;
  • a run's project_id posted over agent-config, as a host's runner does, reaching every model call as x-litellm-customer-id and x-litellm-tags;
  • a file part naming a stored object, which core sends as an https grant, downloaded into the task's inputs and read by the CLI.

  It passes on fresh x86 and arm64 Linux VMs.

• Install integration: run_bundle_claude_code_install_test.py installs the default agent, from a step naming none, into a Debian and an Alpine task container with no Python of their own (Alpine has no bash either), as two agents into one container, again into the same container by a retried step, and onto the sandbox's host under a name with a space. A skill then reaches it through a read grant over the local CA's TLS. Each time, the CLI runs a command where the task's files are, against the fake endpoint, and reads the skill back. It passes on x86 and arm64 Linux VMs.

• Live, with a real model through a LiteLLM gateway, on fresh Linux VMs: the results are in the verification comment.

• Chaos: the results are in the verification comment.

🤖 Generated with Claude Code

[earakely-scale]

Verification

All on fresh x86 and arm64 Linux VMs, with a real model through a LiteLLM gateway unless noted. No run printed the model key, and nothing was left behind: no containers, agent processes, work dirs or Modal sandboxes.

Deploying the agent (deploy_agent, judges)

Provider	smoke	named agent	env MCP tool	agent judge
local, x86 and arm64	7–9 s	pass	45–48 s	pass
smol, x86	52 s (33 s warm)	35 s	106 s	70 s
modal	41 s cold, 10 s warm
modal_vm	41–49 s	pass	192 s	109 s

Eight repeat runs passed.

Installing it (install_agent, def7431 and f025888)

Provider	Debian container	Alpine container	host
local, x86	20 s	18 s	14 s
local, arm64	23 s	20 s	18 s
modal_vm	64–67 s	62–73 s	60–65 s

• The agent used both Bash and Grep in the Alpine container, where it is musl and bash came from apk.
• verify_a2a_install reports supported (rubric 1.0) on x86 and arm64. It was run as the validator's install sub-chain: the full a2a-agent validate needs a fixture env a local store doesn't hold.
• CI's integration-local-slow ran all six Claude Code tests. Four are install tests: Debian, Alpine, two agents in one container, and the host under a name with a space. Each installs a skill through a TLS grant.

beta_scale (Scale's sandbox platform)

Smoke	Agent judge	Install, Debian container	Install, host
110 s	226 s	132 s	121 s

• An env's MCP tools don't reach the agent there. Inside the cluster, the env's MCP URL is served with a self-signed certificate that doesn't name its host, and the agent keeps TLS verification on.
• The old wrapper switched verification off. Its beta_scale-only equivalent goes into the Scale provider when the hub moves onto this agent, so nothing changes in this PR.
• Every other provider made real MCP tool calls.

Snapshot round trip (the hub's next-turn resume)

How the hub resumes a run: snapshot_agent_state after turn 1, then a fresh agent loads the snapshot under a target context, and turn 2 continues it.

• Turn 2 recalled a codeword only the restored conversation held.
• Its cat printed random bytes only the restored workspace held, matched against the snapshot's own workspace archive.

beta_scale, S3	modal_vm, S3
pass, 231 s	pass, 150 s

A stored image as a file part

A PNG in the store (s3://) is named in a prompt. Core sends it as an https grant, and the agent downloads it for the CLI. The model then reported which colour was on which side.

beta_scale	modal_vm
pass, 110 s	pass, 69 s

Chaos

The trials fault the run, then check it ends as allowed, leaves nothing behind and leaks no key. A failed trial is rerun, and the rerun must pass.

• Deploy path, 179 trials. Faults: killing the CLI or the container mid-turn, a Docker restart, a cancel, an env's MCP server stopped mid-call, Anthropic API faults (fake and through a proxy), a killed image build, blocked binary downloads, and four concurrent cold builds.
  • The only flagged trials were one pass's blocked-download trials: the build cache meant the download never ran, so the harness's expectation was wrong.
  • With the cache pruned, the cold-build passes ran clean: 61 trials, 0 violations.
• Install path, 246 trials over five passes. Faults: install.sh killed mid-run (Debian, Alpine, host), the task container killed mid-install, Claude Code's download blocked, and Debian, Alpine and host installs at once.
  • 1 flagged trial was the harness's: the container was killed after the agent had answered, so the run rightly passed.
  • Every rerun passed.
  • A container killed mid-turn fails in about 60 s, from prompt_agent's liveness check.
  • Before the install waited for the agent's /health, a container killed just after the install took 300 s to fail, install_agent's card wait. Since then, the slowest is 71 s.
  • It recurred once in about 40 later kill-container trials, and not in 14 targeted ones on f025888.

🤖 Generated with Claude Code