Cloud sessions should execute client-provided tools in the SDK process

[just-cameron]

Overlord (agent-c2adbf5c-8419-4211-8cd8-3740db164974)

Problem

CreateSessionOptions.tools represents tools whose callbacks execute in the Agent SDK client process.

That contract works through the local app-server path, but not for backend: "cloud" sessions using a managed sandbox. The tool definitions reach the sandbox and are advertised to the model, but invocation fails with:

External tool executor not set for tool: <name>

This prevents SDK consumers such as ACP editors from combining isolated sandbox execution with explicit client-side capabilities.

Expected contract

Tool ownership, rather than backend or authentication, determines execution location:

• Runtime-owned tools such as Bash, Read, and Write execute wherever the harness runs.
• Tools supplied through CreateSessionOptions.tools execute in the SDK client process for every backend.
• For managed Cloud sessions, the sandbox filesystem and client filesystem remain separate. Client tools provide explicit, capability-scoped access; the SDK does not mount the client filesystem or expose arbitrary local command execution.

For ACP, this allows built-in commands to run in the managed sandbox while tools such as read_editor_buffer and write_via_editor execute through the local editor.

Proven gaps

The existing bidirectional external-tool protocol is missing two downstream pieces:

1. Letta Code installs the external executor for local app-server attachments, but not every managed listener runtime that registers external tools.
2. Cloud does not currently relay external_tool_call_response from the SDK status connection back to the owning sandbox listener.

Related Cloud relay PR: https://github.com/letta-ai/letta-cloud/pull/13518

Public ACP reproduction: letta-ai/letta-acp#25

Original ACP backend discussion: letta-ai/letta-acp#46

Acceptance criteria

• A real backend: "cloud" session with an SDK-managed sandbox invokes a supplied JavaScript tool callback in the SDK client process.
• The callback result returns to the same sandbox run and settles the original model tool call.
• Concurrent sessions and tool calls remain scoped by connection, agent, conversation, and tool-call ID.
• Callback failure, rejection, timeout, cancellation, client disconnect, and sandbox reconnect settle without stranding the turn.
• A live integration test crosses the actual managed-sandbox/status-relay boundary; local-only fakes are insufficient.
• Documentation states clearly that cwd and built-in filesystem tools refer to the runtime environment, while client-provided tools execute at the caller.

Non-goals

• Mounting or automatically synchronizing the client repository into the sandbox.
• Giving a sandbox arbitrary access to local Bash.
• Collapsing the Cloud sandbox backend into the local app-server backend.
• Choosing authentication based on execution location.