claude-code adapter (pre-release / "coming soon"): in-VM Write/Bash/Skill/sub-agent tools stall ~120s — sidecar stays alive, agent ext-turn never completes

[idl3]

⚠️ CORRECTION (2026-06-27, see latest comment): A runtime frame-capture + RUST_LOG=debug sidecar-log trace contradicts the stale-response / read-loop-death root cause described below. The sidecar stays alive the whole hang (doing TLS to the LLM endpoint); the in-VM agent's ext turn simply never completes — the sidecar itself even warns "ext request still pending — possible stall before response frame". Treat the analysis below as a superseded hypothesis; the accurate symptom is in the latest comment.

---

claude agent: every tool routed through the ext extension runtime (Write / Bash / Skill / sub-agent) hangs with timed out waiting for sidecar protocol frame for ext

Summary

With a claude session, the agent boots, authenticates, and can use the Read tool and reply normally. But any tool that goes through the ext extension runtime — the Write tool, Bash tool, the Skill tool, or spawning a sub-agent (Task) — hangs ~120s and fails with:

timed out waiting for sidecar protocol frame for ext
stderr:
… level=info message="sidecar process started"
… level=info message="vm phase" phase=create_vm elapsed_ms=42
(no further frames; the ext request never returns an `ext_result`)

So a real coding-agent run can't complete (it can't write files, run shell commands, use skills, or fan out). Read-only / trivial sessions work fine, which is why this isn't obvious until the agent first reaches for a write/exec tool.

Confirmed NOT a usage error

• Reproduces with the canonical setup from examples/docs/agents/claude/: default HOME=/home/agentos, user agentos, createSession("claude", {cwd, env}), no overrides. (Initially suspected my HOME=/root override — ruled out; same failure with the documented home.)
• Read tool + trivial prompts succeed in the same session config, so auth, VM, and the SDK bridge are healthy. The failure is specific to the ext extension request path.

Reproduces on Node 22 and 25

Identical failure under fresh installs on Node v22.22.3 and v25.9.0 (macOS 15.7.4, arm64). Not a Node-version/ABI artifact.

Reproduction

npm i @rivet-dev/agentos-core @agentos-software/common @agentos-software/claude-code
export ANTHROPIC_API_KEY=sk-...
node repro.mjs

// repro.mjs
import { AgentOs } from "@rivet-dev/agentos-core";
import common from "@agentos-software/common";
import claude from "@agentos-software/claude-code";
const race = (p, ms) => Promise.race([p, new Promise((_, r) => setTimeout(() => r(new Error("TIMEOUT")), ms))]);

const vm = await AgentOs.create({ software: [common, claude] });
const { sessionId } = await vm.createSession("claude", {
  cwd: "/home/agentos",
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
});

// WORKS: Read-only / trivial → returns fine.
console.log(await vm.prompt(sessionId, "Reply with exactly: OK"));

// HANGS ~120s → `timed out waiting for sidecar protocol frame for ext`
try {
  console.log(await race(
    vm.prompt(sessionId, "Write HELLO to /home/agentos/out.txt with your file tool, then reply DONE."),
    150000));
} catch (e) { console.error("FAILED:", e.message); }
await vm.dispose();

What works vs fails

Works (in-process, no ext)	Fails — ext request times out (~120s)
AgentOs.create(), vm.exec() (direct)	agent Write tool
auth + trivial agent reply	agent Bash tool
agent Read tool	Skill tool (using a discovered skill)
	sub-agent (Task) spawn

Root cause (traced end-to-end)

This is a shared-sidecar lifecycle bug in secure-exec-sidecar 0.3.1 that was already fixed in 0.3.2 (secure-exec PR #133 / tag v0.3.2, commit d8a4435) — but 0.3.1 is what @agentos-software/claude-code@0.2.0 drags onto the tool path via its exact pin on @rivet-dev/agentos-core@0.2.0.

Mechanism:

1. Write/Bash/Skill/Task each provision a VM on the shared secure-exec sidecar and dispose it (phase=create_vm). The ext extension that backs them is dev.rivet.agent-os.acp (agentos crates/agentos-protocol/src/lib.rs:7, AcpExtension in crates/agentos-sidecar/src/acp_extension.rs), baked into the sidecar binary. (An unregistered namespace would reject fast — service.rs:1483-1492 — so this is not a missing-registration / protocol-version issue; those fail immediately, not after 120s.)
2. When a per-VM sidecar_response arrives after that VM was torn down, SidecarResponseTracker::accept_response returns UnmatchedResponse/DuplicateResponse (secure-exec crates/sidecar/src/protocol.rs:1899-1913).
3. Pre-0.3.2, that error propagates: accept_wire_sidecar_response → stdio.rs:364 …? → the main read loop's handle_protocol_frame(...).await? (stdio.rs:232,252) exits the read loop. The sidecar stops servicing all frames.
4. The host's in-flight ext request never gets ext_result and times out after DEFAULT_SIDECAR_FRAME_TIMEOUT_MS = 120_000 (secure-exec packages/core/src/native-client.ts:17) → the exact error in protocol-client.ts:122-124. Matches the 120s + the started → create_vm → silence signature precisely.
5. 0.3.2 fixes it by tolerating stale responses (drop + warn instead of dying): secure-exec crates/sidecar/src/service.rs:2720-2742 ("a per-VM sidecar_request can be answered by the host after that VM has been torn down (multiple VMs share one sidecar process)").

This is a same-version-lockstep break

Per AGENTS.md: "The protocol has no backwards compatibility. Clients and the sidecar ship in same-version lockstep... the single same-version wire handshake is the only version check." And the package tracks: "agent-os product/API (@rivet-dev/agentos*)... pins compatible secure-exec and registry package versions", while "@agentos-software/* registry packages... [are] versioned independently."

The @agentos-software/claude-code ACP adapter therefore must run in lockstep with the agentos-core/sidecar it talks to. But @agentos-software/claude-code@0.2.0 exact-pins @rivet-dev/agentos-core@0.2.0, so the README install npm i @rivet-dev/agentos-core @agentos-software/claude-code resolves core 0.2.2 (latest, with the fixed secure-exec-sidecar 0.3.2) for the host alongside the adapter's pinned core 0.2.0 (unfixed 0.3.1) — a lockstep break that routes tool execution through the unfixed sidecar.

The fix (maintainer-side)

Publish a @agentos-software/claude-code that depends on the same @rivet-dev/agentos-core version agent-os ships (0.2.2), so the adapter and sidecar are in lockstep on the fixed secure-exec-sidecar 0.3.2. (That package has no public repo, so this is maintainer action; per AGENTS.md the registry packages are version-managed via just agentos-pkgs-set-version.)

An npm overrides workaround is NOT valid here and is not recommended: forcing agentos-core@0.2.2 under a claude-code@0.2.0 build removes the 120s hang (confirming the root cause — the Write prompt returns end_turn instead of timing out) but leaves a 0.2.0-built adapter running against a 0.2.2 protocol, i.e. exactly the lockstep break AGENTS.md forbids — and in testing tool calls did not cleanly persist in that mixed state. Only a lockstep-rebuilt adapter fixes it.

Secondary: the silent 120s hang is an observability gap (per AGENTS.md)

Independent of the version fix: AGENTS.md → Limits, Bounds & Observability states "The default 120s ACP method timeout is the adapter-stall failure mode — make it observable, not a silent 120s hang," and that ACP timeouts carry data.kind === "acp_timeout" while "the native-sidecar frame timeout... [should] emit a structured near-threshold signal (default ≥80%) and fail with a typed error that names the limit and how to raise it."

This bug is precisely that failure mode: the native-sidecar ext frame timeout (secure-exec packages/core/src/protocol-client.ts:122-124, DEFAULT_SIDECAR_FRAME_TIMEOUT_MS = 120_000) surfaces as a bare 120s silent hang with no near-threshold warning and no typed error/kind. Even after the lockstep fix, giving the native-sidecar frame timeout the same typed-error + warn-on-approach treatment as acp_timeout would have turned this from a 120s silent hang into an immediately actionable error.

Notes

• Reproduces on Node 22 and 25 → not a Node/ABI artifact. macOS arm64.
• The slash-skill Unknown skill behaviour (a /100x:... or personal ~/.claude/skills skill not resolving) is a separate matter from this hang and is not covered here.

Environment

OS	macOS 15.7.4, arm64
Node	v25.9.0 and v22.22.3 (same result)
@rivet-dev/agentos-core	0.2.2 (README install) — also tried 0.2.0
@agentos-software/claude-code	0.2.0 (pins agentos-core 0.2.0)
@secure-exec/core	0.3.2 (top) + 0.3.1 (nested under claude-code)
@rivet-dev/agentos-sidecar	0.2.2
@anthropic-ai/claude-agent-sdk	0.2.141

[idl3]

Opened #1543 with a docs caution + overrides workaround as a stopgap. The proper fix remains maintainer-side: bump @agentos-software/claude-code's @rivet-dev/agentos-core dependency from the exact 0.2.0 to 0.2.2 (or ^0.2.2) so tool execution routes through the fixed secure-exec-sidecar 0.3.2.

Note: forcing core 0.2.2 via overrides removes the 120s hang, but in that mixed state (core 0.2.2 under a claude-code adapter built for 0.2.0) tool calls did not cleanly persist in testing — so a claude-code rebuilt against 0.2.2 is the real fix, worth verifying end-to-end once published.

[idl3]

Correction after more testing — no published build works on macOS arm64

I tried to confirm the fix and could not find any published release or preview where tool execution completes on macOS 15.7 (arm64):

• Tested the newest lockstep preview set — @rivet-dev/agentos-core, @agentos-software/claude-code, and @rivet-dev/agentos-sidecar all at 0.0.0-feat-on-limit-warning.62a2bc2 (single @secure-exec/core@0.0.0-fix-queue-backpressure-and-tracker.f7cc68e). A Write-tool prompt still wedges: it hangs, and afterwards the sidecar is dead — a follow-up vm.exec times out (~120s) and even a fresh createSession then times out. That matches the "read loop exits → the whole sidecar stops servicing every frame" mechanism above.

So, correcting my earlier framing:

• The mechanism (a stale/UnmatchedResponse after a tool-op VM teardown wedging the sidecar read loop) is well-traced and is exactly what feat: run only local tests unless explicitly specifying remote module #133 / v0.3.2 tolerates — that part stands.
• But I cannot confirm that any shipped agentos-core/sidecar build actually resolves it on this platform: the wedge reproduces on the latest lockstep preview too, and the 0.2.2-override case was inconsistent (a race, fittingly). The version-skew/lockstep point is a real packaging issue but is not confirmed to be the sole cause.

Ask: could a maintainer repro a single Write/Bash tool turn (e.g. the repro above) on macOS arm64? If it works on Linux x86 but hangs on arm64, this points at the arm64 prebuilt sidecar; if it hangs everywhere, the #133 stale-response tolerance may be incomplete (a residual unmatched path) rather than a pure version issue. Happy to run any diagnostic build.

[idl3]

Correction: runtime capture contradicts the stale-response / read-loop theory

I instrumented the wire (logged every frame in/out of @secure-exec/core's StdioFrameTransport) and captured the Rust sidecar's RUST_LOG=debug output through a full ~120s Write-tool hang (macOS 15, arm64). The evidence contradicts my earlier hypothesis that a stale UnmatchedResponse kills the sidecar read loop:

• The sidecar stays alive the entire time — its debug log shows it actively doing DNS + TLS to the agent's LLM endpoint (the configured ANTHROPIC_BASE_URL) well into the hang.
• ext events keep streaming from the in-VM agent throughout (frame_type=event payload=ext) — the agent is active, not frozen (it looks like it may be retrying).
• The sidecar emits its own warning near the end: level=warn message="ext request still pending — possible stall before response frame" kind=session_request elapsed_ms=118381.
• The host's ext request never receives an ext_result, so after DEFAULT_SIDECAR_FRAME_TIMEOUT_MS=120000 the client throws timed out waiting for sidecar protocol frame for ext.

So the actual symptom is: the in-VM (patched) claude agent's ext turn never completes — the sidecar is healthy and waiting on it — rather than the sidecar's read loop dying. The version-skew/lockstep angle in the body was a source-reading hypothesis the runtime evidence doesn't support.

Still holds: Read-only / trivial turns complete; Write / Bash / Skill / sub-agent turns stall to the 120s timeout. Reproduces across published versions incl. the latest lockstep preview, on macOS arm64.

I don't have the confirmed root cause — handing over the accurate symptom + your own "ext request still pending" warning. Plausible areas a maintainer could pin faster: the agent's LLM-streaming path through the VM's emulated network stack, or the fs/write_text_file tool-result round-trip not propagating back (the agent appears to retry — many ext events, no completion). Happy to run any diagnostic build. Apologies for the earlier mis-diagnosis.

[idl3]

Closing — succinct learnings

After fuller investigation I don't think this is an actionable report in its current form, so I'm closing it to keep your tracker clean. Honest summary:

1. This is the @agentos-software/claude-code adapter, which your docs mark "coming soon." The stall (in-VM Write/Bash/Skill/sub-agent tools never completing) reproduces on that pre-release adapter; Pi works fine. So it's most likely a known not-ready-yet gap rather than a regression worth tracking now.

2. My earlier root-cause analyses in this thread were wrong — apologies for the noise. The "version-skew → unfixed secure-exec-sidecar 0.3.1 / stale-response read-loop death" theory (from reading source) did not hold up. A runtime frame+log capture showed the sidecar stays alive (doing TLS to the LLM endpoint), ext events keep streaming, and the sidecar emits its own "ext request still pending — possible stall before response frame" (~118s) before the host's 120s frame timeout. So the symptom is "the in-VM agent's ext turn never completes," not a protocol death — and I did not confirm the actual cause.

3. Minimal repro (for when the adapter graduates): AgentOs.create({software:[common, claude]}) → createSession("claude", {env:{ANTHROPIC_API_KEY}}) → a trivial "reply OK" returns, but "use the Write tool to create a file" hangs ~120s. macOS arm64, Node 22 + 25.

Happy to reopen with a cleaner standalone repro if a reproducible in-VM-tool stall on the claude-code adapter is useful to you pre-release. And thanks — the limitations + agents docs cleared up exactly what I'd misunderstood about the runtime.

[NathanFlurry]

Partial fix in #1552: wires the agent permission flow through the RivetKit actor (permissionRequest event + respondPermission action) and adds a host-visible, once-per-session warning when a tool-permission request arrives with no handler registered.

Investigating this report, the in-VM "stall" reproduced as the permission flow — with no approval wired, tool requests were silently denied and the agent looped. The remaining piece for the full 120s-stall behavior is removing the claude adapter's 2s auto-resolve fallback (published in @agentos-software/claude-code@0.2.1); agent-os isn't re-pinned to it yet.