claude: 🔒️ Pass isolated OAuth tokens through the child environment

[yasyf]

Summary

Isolated Claude runs now receive the OAuth access token through CLAUDE_CODE_OAUTH_TOKEN. They no longer seed a .credentials.json that can survive cleanup or become a persistent Keychain copy. A non-empty process token takes precedence over stored credentials, and Python resolves the token on every call so the next run can use renewed credentials.

Previously, claude_isolation_seed copied the full credential JSON into a 0600 file under $TMPDIR/spawnllm-claude-config-*. Python atexit, Go deferred cleanup, and Rust TempDir Drop cannot remove it when the parent is killed before cleanup, including at a Claude Code hook timeout. This machine had 77 leaked directories, including a token copy from September 14. PR #8 listed this as remaining work.

Verification also found a second leak: Claude Code migrated seeded credentials into Keychain items named Claude Code-credentials-<sha256(CLAUDE_CONFIG_DIR)[:8]>. The login Keychain held 345 such items; the earliest sampled item was created on September 9, 2026. Those copies outlived the temporary directories.

Fix

The core's claude_isolation_sources op takes claude_code_oauth_token_env. When it is set and non-empty, the op returns credentials_path: null and keychain_service: null. All three hosts accept the nullable path and skip both the credential file read and the security call. The seed carries no token, so the child inherits the process token. An unset or empty value still resolves stored credentials.

For stored credentials, the shared core parses claudeAiOauth.accessToken from credentials_json and returns it in an env map beside files. The only seeded file is the account pointer .claude.json, with mcpServers removed and mode 0644. Malformed credentials JSON returns an error; credentials without claudeAiOauth produce no token, as with a Keychain miss.

All three hosts apply the seed environment to the child. Python carries it in ClaudeIsolation(config_dir, env) and merges it in invocation() and env(). Go returns it from seedClaudeIsolation and merges it with maps.Copy. Rust carries it alongside TempDir in Isolation and applies it with cmd.envs. Each host already applied RunSpec.env last, so an explicit per-run override continues to win.

Python now caches only _isolated_config_dir. Source resolution, credential reads, and seed computation run on every call. The config directory stays the same, while a renewed Keychain token reaches the next run of the same backend.

The changelog records the security fix under Unreleased, including token precedence and per-run resolution. The already shipped 0.13.3 changes get their 2026-09-17 release heading, with the 0.13.2 and 0.13.3 compare links added.

Tests

• Regenerated 5 isolation seed vectors and replayed them through Python and Go against the rebuilt wasm blob. Added oauth-token-env-darwin and oauth-token-env-empty-darwin; 13 existing sources vectors gained the new null input field.
• Updated host isolation tests to assert that the child receives the access token in its environment and no .credentials.json is seeded. Fake Keychain credentials use the real JSON shape.
• Added inherited-token tests in Python, Go, and Rust with stored credentials containing not json and a Keychain lookup that must not run. These tests cover bypassing credential sources when the process supplies the token.
• Added test_env_resolves_the_token_on_every_call: the same Python backend sees credentials rewritten between two calls, returns the renewed token, and reuses the config directory.
• Isolation tests clear CLAUDE_CODE_OAUTH_TOKEN from the test environment, including through Go's clearHostEnv helper and Python's autouse fixture. The suites also pass with CLAUDE_CODE_OAUTH_TOKEN=review-sentinel exported.
• Added test_killed_run_leaves_no_token_on_disk: a child interpreter runs ClaudeCliBackend().execute with a sleeping fake CLI under a private TMPDIR. After SIGKILL, the config directory remains, but no file under TMPDIR contains the token. The marker is published with write-then-mv so readers cannot see a partial write, and the parent is killed in finally.
• cargo test --workspace passed, Clippy reported 0 warnings, and cargo fmt --check passed; go vet and go test ./... passed; uv run pytest passed with two environment skips. Ruff and ty were unchanged, with 21 pre-existing ty diagnostics.

With Claude Code 2.1.274, claude -p --model haiku authenticated using the Keychain access token in the environment and an empty config directory. It exited 0, wrote no .credentials.json or token bytes under the directory, and created no Keychain item for its hash. An invalid token exited 1 with Failed to authenticate. API Error: 401 OAuth access token is invalid.

Tradeoffs and remaining work

Claude Code does not refresh a user-supplied environment token on 401. An expired access token therefore fails explicitly; a running Claude Code session keeps the source Keychain token current. Previously, the isolated child received the refresh token and stored refreshed credentials under the temporary directory's hashed Keychain item.

With only a per-run RunSpec.env token override, malformed stored credentials JSON still raises an error before the override is applied. The error reports the corrupt stored credential.

There is no pre-spawn expiresAt check because the child's 401 already reports authentication failure. Directory cleanup still depends on normal exit, but isolation seeding no longer places a credential in that directory.

The 345 existing Keychain items and leaked directories require operator cleanup. This change prevents new copies; it does not remove existing ones.