adk-code-mode 0.2.2__tar.gz → 0.4.0__tar.gz

adk_code_mode-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+    ".": "0.4.0"
+}

adk_code_mode-0.4.0/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## [0.4.0](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.3.0...adk-code-mode-v0.4.0) (2026-07-09)
+
+
+### Features
+
+* save tool results as artifacts with optional model-supplied naming ([76a3671](https://github.com/a2anet/adk-code-mode/commit/76a36713b2c52bd5b8dc51d3669226a47e7108e5))
+
+
+### Bug Fixes
+
+* align code-mode example with the `<code-mode>` catalog and fix fences ([4a0cc6d](https://github.com/a2anet/adk-code-mode/commit/4a0cc6d0fc99d5425f6682cc489e76c9ddef7d46))
+* clarify code-mode tools are a Python library, not function tools ([48d1018](https://github.com/a2anet/adk-code-mode/commit/48d1018152a2ed2a8e7361de6ce0f43b31b429ce))
+* nudge the model to call tools via Python in the code-mode block ([141baf3](https://github.com/a2anet/adk-code-mode/commit/141baf3a44976e82cf437b2064666be893d6d409))
+* update `CODE_MODE_SYSTEM_INSTRUCTION` and `README.md` ([933d42c](https://github.com/a2anet/adk-code-mode/commit/933d42cb237b9d6deeb6611511cba28a0d5e9261))
+
+
+### Documentation
+
+* streamline `README.md` and fix broken code fences ([c237514](https://github.com/a2anet/adk-code-mode/commit/c2375149df48e21318967090b6c85d0b1f411ea2))
+
+## [0.3.0](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.2.2...adk-code-mode-v0.3.0) (2026-07-06)
+
+
+### Features
+
+* hold one sandbox container open per turn (protocol v2) ([#6](https://github.com/a2anet/adk-code-mode/issues/6)) ([aebe17d](https://github.com/a2anet/adk-code-mode/commit/aebe17d2bbbf21cc0f05852efaf910ff6adc3154))
+
+
+### Documentation
+
+* lower startup probe period in `README.md` for faster cold starts ([e251af2](https://github.com/a2anet/adk-code-mode/commit/e251af2cf7307c9944361e1a0e37c7191822a9e1))
+* note HTTP `/health` startup probe in `README.md` Cloud Run section ([d58fb10](https://github.com/a2anet/adk-code-mode/commit/d58fb10f7aeda95e5c8cf29263a13e1333f661dd))
+
+## [0.2.2](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.2.1...adk-code-mode-v0.2.2) (2026-05-08)
+
+
+### Bug Fixes
+
+* use `python` fences instead of `tool_code` in `CodeModeCodeExecutor` ([efcc11e](https://github.com/a2anet/adk-code-mode/commit/efcc11e1020c7544223074e00a8649f9c85d4ad6))
+
+## [0.2.1](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.2.0...adk-code-mode-v0.2.1) (2026-05-05)
+
+
+### Bug Fixes
+
+* rename `<tools>` tag to `<code-mode>` and update `CODE_MODE_SYSTEM_INSTRUCTION` ([0a06bfb](https://github.com/a2anet/adk-code-mode/commit/0a06bfbdf22db6e0226e477d0ed074a6cc4d1515))
+
+
+### Documentation
+
+* update `README.md` with deployment instructions ([1dd7a95](https://github.com/a2anet/adk-code-mode/commit/1dd7a95197fd56231ba97182526a825baf18508a))
+
+## [0.2.0](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.1.0...adk-code-mode-v0.2.0) (2026-05-03)
+
+
+### Features
+
+* add `RemoteBackend`, sandbox hardening, and make `README.md` more concise ([a1a70ee](https://github.com/a2anet/adk-code-mode/commit/a1a70eec0686f164ce3796ba1d82bb82b7fbda59))
+
+
+### Bug Fixes
+
+* improve `CODE_MODE_SYSTEM_INSTRUCTION` ([0d00863](https://github.com/a2anet/adk-code-mode/commit/0d008636e2e273b438192f737e20e207c165a610))
+
+## 0.1.0 (2026-04-29)
+
+
+### Features
+
+* ADK Code Mode: `CodeModeExecutor`, `DockerRuntime`, and more ([6ab1ac2](https://github.com/a2anet/adk-code-mode/commit/6ab1ac28236d21ecb740d8e920e08e4d9bd969c5))
+
+
+### Documentation
+
+* shorten ADK code executor comparison table headers ([28116cf](https://github.com/a2anet/adk-code-mode/commit/28116cf9f40b3623c31782a55885fa5c4f8c6bbf))

{adk_code_mode-0.2.2 → adk_code_mode-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adk-code-mode
-Version: 0.2.2
+Version: 0.4.0
 Summary: A "Code Mode" Code Executor for ADK for agents to interact with tools, files, and custom packages with Python
 Project-URL: Documentation, https://github.com/A2ANet/adk-code-mode#readme
 Project-URL: Issues, https://github.com/A2ANet/adk-code-mode/issues
@@ -41,15 +41,16 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and
 - **Call ADK tools from sandbox code** — imports against the `tools` package proxy back to the host and run through ADK's `before_tool` / `after_tool` / `on_error` callbacks and the plugin manager exactly as direct tool calls would.
 - **Bake any Python package into the image** — extend the published base image with anything the model's code needs to `import`, no runtime `pip install` required.
 - **Cross-turn persistence via ADK Artifacts** — `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`.
+- **Tool results saved as artifacts** — on by default; every tool's result is persisted as a `code_mode.tool_result` artifact (with optional model-supplied name/description) so hosts can forward outputs and large results stay out of the prompt. Opt out with `save_tool_results_as_artifacts=False`.
 - **Bounded stdout/stderr** — overflow lands in a session artifact instead of poisoning the prompt.
-- **Production-ready remote sandbox** — `RemoteBackend` connects to an isolated, single-use container over WebSocket. Deploy on any cloud platform (Cloud Run, Fargate, ACI, Kubernetes, Fly.io, etc.).
+- **Production-ready remote sandbox** — `RemoteBackend` connects to an isolated per-turn container over WebSocket, reused across the turn's code blocks. Deploy on any cloud platform (Cloud Run, Fargate, ACI, Kubernetes, Fly.io, etc.).
 - **Local development** — `UnsafeLocalDockerBackend` runs the sandbox against your local Docker daemon for fast iteration. **Not for production** — see [Safety](#-safety).
 
 |                                     | BuiltIn | AgentEngineSandbox              | VertexAi                        | Container | Gke | CodeMode                 |
 | ----------------------------------- | ------- | ------------------------------- | ------------------------------- | --------- | --- | ------------------------ |
 | Call ADK tools from code            | no      | no                              | no                              | no        | no  | yes (with limitations)   |
 | Extra Python packages               | no      | no (more than stdlib but fixed) | no (more than stdlib but fixed) | yes       | yes | yes                      |
-| Variables are stateful              | no      | yes                             | yes                             | no        | no  | no                       |
+| Variables are stateful              | no      | yes                             | yes                             | no        | no  | yes (within a turn)      |
 | Input files                         | no      | yes                             | yes                             | no        | no  | yes                      |
 | Output files                        | no      | yes                             | yes                             | no        | no  | yes                      |
 | Storage                             | no      | yes (via variables)             | yes (via variables)             | no        | no  | yes (via ADK Artifacts)  |
@@ -78,11 +79,12 @@ Requires Python 3.10+. Local development requires [Docker](https://docs.docker.c
 
 ## 🚀 Usage
 
-Build a `CodeModeCodeExecutor`, then wire three things into the agent:
+Build a `CodeModeCodeExecutor`, then wire four things into the agent:
 
 - **`CODE_MODE_SYSTEM_INSTRUCTION`** — append to the agent's `instruction`. Teaches the model how to write code blocks and use artifacts.
 - **`code_mode_before_model_callback`** — set as `before_model_callback`. Injects the tool catalog (`<code-mode>` block) into the system prompt on every model turn.
 - **`generate_content_config`** with `function_calling_config.mode="NONE"` — disables native function calling so the model writes Python instead of attempting tool calls that fail with `MALFORMED_FUNCTION_CALL` (since `tools=[]`).
+- **`release_invocation`** — call it from the agent's `after_agent_callback` to release the turn's sandbox container as soon as the turn ends. An idle reaper (`session_idle_timeout_seconds`, default `600`) is a backstop, so containers are still reclaimed without it — just later.
 
 ### Production (remote sandbox)
 
@@ -104,6 +106,9 @@ executor = CodeModeCodeExecutor(
     ),
 )
 
+def _release_sandbox(callback_context):
+    executor.release_invocation(callback_context.invocation_id)
+
 root_agent = LlmAgent(
     name="assistant",
     model="gemini-2.5-pro",
@@ -116,6 +121,7 @@ root_agent = LlmAgent(
         ),
     ),
     before_model_callback=code_mode_before_model_callback(executor),
+    after_agent_callback=[_release_sandbox],
 )
 ```
 
@@ -146,17 +152,7 @@ print(send_message(channel="C123", text="hi"))
 
 ## 🌐 Remote Deployment
 
-**Every execution runs in its own container.** The container accepts exactly one WebSocket connection, executes the user's code, returns results, and exits. The hosting platform destroys the container after each request — no cross-tenant data leakage, no residual state. You **must** configure your platform for one container per request (`--concurrency 1` on Cloud Run, or equivalent).
-
-Setting `ADK_CODE_MODE_CONTROL_HTTP=1` activates HTTP mode. The container:
-
-1. Starts a WebSocket server on port 8080 (configurable via `PORT`)
-2. Accepts exactly one connection (rejects further connections with 503)
-3. Receives tools and workspace as tar archives over binary WebSocket frames
-4. Sanitizes the environment (strips all env vars except a safe allowlist)
-5. Executes user code with tools proxied back to the host over the same WebSocket
-6. Returns stdout/stderr and updated workspace files
-7. Exits
+**Every turn runs in its own container**, which the platform destroys when the turn ends — no cross-turn or cross-tenant state. The sandbox runs as a WebSocket server (set `ADK_CODE_MODE_CONTROL_HTTP=1`) and accepts exactly one connection, so you **must** configure your platform for one container per turn (`--concurrency 1` on Cloud Run, or equivalent).
 
 ### Deploy to Cloud Run
 
@@ -184,7 +180,7 @@ gcloud compute networks vpc-access connectors create adk-sandbox-connector \
     --region=<region> \
     --subnet=adk-sandbox-subnet
 
-# Deploy — note --concurrency 1 and --vpc-egress=all-traffic
+# Deploy — note --concurrency 1, --vpc-egress=all-traffic, and the /health startup probe
 gcloud run deploy adk-code-mode-sandbox \
     --image <region>-docker.pkg.dev/<project>/<repository>/adk-code-mode-sandbox:latest \
     --region <region> \
@@ -192,13 +188,18 @@ gcloud run deploy adk-code-mode-sandbox \
     --cpu 1 \
     --memory 1Gi \
     --concurrency 1 \
+    --timeout 3600 \
+    --max-instances 120 \
     --allow-unauthenticated \
     --vpc-connector=adk-sandbox-connector \
     --vpc-egress=all-traffic \
     --set-env-vars "ADK_CODE_MODE_CONTROL_HTTP=1" \
-    --set-secrets "ADK_CODE_MODE_AUTH_TOKEN=<your-secret-name>:latest"
+    --set-secrets "ADK_CODE_MODE_AUTH_TOKEN=<your-secret-name>:latest" \
+    --startup-probe "httpGet.path=/health,httpGet.port=8080,timeoutSeconds=3,periodSeconds=3,failureThreshold=80"
 ```
 
+> These flags are **recommendations to tune per deployment**, not hard requirements. `--timeout 3600` (Cloud Run's max) is the per-turn ceiling since the container holds the WebSocket for the whole turn; `--max-instances` should cover your peak concurrent *turns* (`120` covers a 10–100 target — verify your region's Cloud Run vCPU quota). The `/health` startup probe avoids cold-start `HTTP 503`s — Cloud Run's default TCP probe opens a raw socket the WebSocket server rejects.
+
 Then in your agent:
 
 ```python
@@ -208,7 +209,7 @@ RemoteBackend(
 )
 ```
 
-> **`--concurrency 1` is critical for security.** Without this flag, Cloud Run may route multiple requests to the same container. The sandbox rejects the second connection, but the misconfiguration itself is a risk.
+> **`--concurrency 1` is critical for security.** It pins one turn to one container. Without this flag, Cloud Run may route multiple turns to the same container. The sandbox rejects the second connection, but the misconfiguration itself is a risk.
 
 > **`--vpc-egress=all-traffic` with a deny-all VPC is critical for security.** Without it, user code can make arbitrary outbound requests — including hitting the GCP metadata endpoint (`169.254.169.254`) to steal the service account token, exfiltrating data, or scanning your VPC. The sandbox only needs to _accept_ inbound connections; it never needs outbound access.
 
@@ -216,7 +217,7 @@ RemoteBackend(
 
 The same pattern works on any platform that runs Docker containers as HTTP services (AWS Fargate/ECS, Azure Container Instances, Kubernetes, Fly.io, etc.):
 
-1. **One container per request.** Each container handles exactly one execution and exits.
+1. **One container per turn.** Each container handles exactly one turn (one or more code blocks) and exits.
 2. **Block all outbound network access.** Without egress restrictions, user code can exfiltrate data, access cloud metadata endpoints, or scan internal networks.
 3. **Set a read-only root filesystem** where the platform supports it (e.g., `readOnlyRootFilesystem: true` in Kubernetes). The sandbox only writes to `/workspace`.
 4. **Authenticate connections.** Set `ADK_CODE_MODE_AUTH_TOKEN` and layer platform-level auth (IAM, NetworkPolicy, security groups) on top.
@@ -225,18 +226,22 @@ Required env vars:
 
 | Env var                              | Required | Default | Purpose                          |
 | ------------------------------------ | -------- | ------- | -------------------------------- |
-| `ADK_CODE_MODE_CONTROL_HTTP`         | yes      | —       | Set to `1` to activate HTTP mode |
+| `ADK_CODE_MODE_CONTROL_HTTP`         | yes      | —       | Set to `1` to run the sandbox as a WebSocket server (required for remote) |
 | `ADK_CODE_MODE_AUTH_TOKEN`           | yes      | —       | Bearer token for WebSocket auth  |
 | `PORT`                               | no       | `8080`  | Listen port                      |
 | `ADK_CODE_MODE_MAX_UPLOAD_TOOLS`     | no       | 100 MiB | Max tools tar archive size       |
 | `ADK_CODE_MODE_MAX_UPLOAD_WORKSPACE` | no       | 100 MiB | Max workspace tar archive size   |
 
-The same upload limits (plus a download limit) are configurable on `RemoteBackend`:
+Connection tuning, retry, and the same upload limits (plus a download limit) are configurable on `RemoteBackend`:
 
 ```python
 RemoteBackend(
     url="...",
     token="...",
+    connect_timeout=10.0,             # seconds to wait for the WS handshake (default)
+    start_attempts=3,                 # connect attempts before giving up (default)
+    start_retry_delay_seconds=1.0,    # linear backoff base: delay * attempt (default)
+    start_retry_jitter_seconds=0.25,  # uniform jitter added per retry (default)
     max_upload_tools_bytes=100 * 1024 * 1024,       # 100 MiB (default)
     max_upload_workspace_bytes=100 * 1024 * 1024,    # 100 MiB (default)
     max_download_workspace_bytes=100 * 1024 * 1024,  # 100 MiB (default)
@@ -247,7 +252,7 @@ RemoteBackend(
 
 Code Mode exposes two file surfaces:
 
-- **`/workspace`** — per-run working directory. ADK `input_files` are staged here before code runs (`open("input.csv")` works). Files created or modified under `/workspace` are returned as `CodeExecutionResult.output_files` but are not re-hydrated next turn unless persisted via `save_artifact`.
+- **`/workspace`** — the turn's working directory. It persists across the turn's code blocks and resets between turns. ADK `input_files` for a block are staged here before that block runs (`open("input.csv")` works). Files whose content changed in a block are returned as that block's `CodeExecutionResult.output_files`; nothing under `/workspace` is re-hydrated on the next turn unless persisted via `save_artifact`.
 
 - **ADK Artifacts** — persistent cross-turn storage. `CodeModeCodeExecutor` injects three tools into the catalog:
 
@@ -276,6 +281,16 @@ async def on_saved(invocation_context, delta):
 CodeModeCodeExecutor(tools=..., backend=..., on_artifacts_saved=on_saved)
 ```
 
+### Tool results as artifacts
+
+By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and keeps large results out of the model's context — a result whose serialised form exceeds the threshold is replaced in the reply with a short note pointing at the artifact, which the model reloads with `load_artifact`.
+
+Naming is transparent: the filename is derived from the tool name and call id. Each wrapped tool also gains two **optional** parameters — `artifact_name` and `artifact_description` — that the model may pass to name/describe the saved artifact; both land in the artifact's `custom_metadata` (`code_mode.artifact_name` / `code_mode.artifact_description`) alongside the marker. Set `save_tool_results_as_artifacts=False` to return tool results inline without persisting them.
+
+```python
+CodeModeCodeExecutor(tools=..., backend=..., save_tool_results_as_artifacts=True)
+```
+
 ## 🐳 Sandbox Image
 
 The published base image (`ghcr.io/a2anet/adk-code-mode`) works as-is for tools whose execution is fully host-side. To bake in extra Python packages:
@@ -289,17 +304,18 @@ The same image works for both `RemoteBackend` and `UnsafeLocalDockerBackend`. To
 
 ## ⚙️ Configuration
 
-### Catalog overflow
-
-`max_catalog_chars` (default `50_000`) is a soft cap on the rendered tool catalog in the system prompt. When exceeded, the per-tool sections are replaced with a short note telling the model how to navigate `/tools/` from Python.
-
-```python
-CodeModeCodeExecutor(tools=..., backend=..., max_catalog_chars=20_000)
-```
+All settings are `CodeModeCodeExecutor` constructor arguments:
 
-### Output truncation
+| Argument | Default | Purpose |
+| --- | --- | --- |
+| `max_catalog_chars` | `50_000` | Soft cap on the rendered tool catalog in the system prompt. When exceeded, the per-tool sections are replaced with a short note telling the model how to navigate `/tools/` from Python. |
+| `max_output_chars` | `50_000` | Caps stdout/stderr handed back to the model. Overflow is saved as a session artifact at `code_mode/stdout/<execution-id>.txt` and the model sees a head-and-tail view pointing to it. |
+| `max_code_chars` | `1_000_000` | Rejects oversized code payloads before starting a container. |
+| `timeout_seconds` | `None` | Caps overall execution time. Defaults to the platform request timeout (e.g. Cloud Run `--timeout`); set explicitly for defense in depth. |
+| `per_tool_timeout_seconds` | `None` | Caps each individual tool call. |
+| `session_idle_timeout_seconds` | `600` | Idle reaper: closes a turn's container once it goes untouched this long. Backstop for turns that never call `release_invocation`. |
 
-`max_output_chars` (default `50_000`) caps stdout and stderr handed back to the model. Overflow is saved as a session artifact at `code_mode/stdout/<execution-id>.txt`, and the model sees a head-and-tail view with a marker pointing to it.
+The model can read spilled stdout back from the overflow artifact:
 
 ```python
 from tools import load_artifact
@@ -307,26 +323,13 @@ spilled = load_artifact(filename="code_mode/stdout/<execution-id>.txt")
 print(spilled["data"][-2000:])
 ```
 
-### Code size limit
+### Turn-scoped sessions
 
-`max_code_chars` (default `1_000_000`) rejects oversized code payloads before starting a container.
-
-### Timeouts
-
-`timeout_seconds` caps overall execution time; `per_tool_timeout_seconds` caps each individual tool call. Both default to `None` (relying on platform timeouts). Set them explicitly for defense in depth:
-
-```python
-CodeModeCodeExecutor(
-    tools=...,
-    backend=...,
-    timeout_seconds=30,
-    per_tool_timeout_seconds=10,
-)
-```
+A sandbox container is held open for one **turn** (one ADK invocation) and reused across that turn's code blocks, so cold start is paid at most once per turn. Python globals **and** `/workspace` persist across a turn's blocks and reset between turns — use ADK Artifacts for cross-turn persistence. The container is released when the turn ends (via `release_invocation`, wired in [Usage](#-usage)) and destroyed by the platform, so no state survives into another turn or tenant.
 
 ## 🏗️ Architecture
 
-**Host wheel (`adk-code-mode`).** Lives in the same process as your `LlmAgent`. The `before_model_callback` resolves tools, renders the catalog, and appends it to the system prompt. At execution time, it generates a `tools/` Python package of thin stubs, stages `input_files` into `/workspace`, and launches the sandbox.
+**Host wheel (`adk-code-mode`).** Lives in the same process as your `LlmAgent`. The `before_model_callback` resolves tools, renders the catalog, and appends it to the system prompt. At execution time, it generates a `tools/` Python package of thin stubs, stages the block's `input_files` into `/workspace`, and opens (or reuses) the turn's sandbox connection — the container spans the whole turn.
 
 **Sandbox wheel (`adk-code-mode-sandbox`).** Pre-installed in the container image. When model code calls a stub, it sends a JSON-Lines frame over the control connection; the host runs the real tool (with callbacks and plugins) and sends the result back.
 
@@ -341,37 +344,40 @@ The only things crossing the boundary are: code, tool call arguments, tool retur
 
 Your `instruction` (containing `CODE_MODE_SYSTEM_INSTRUCTION`) followed by a `<code-mode>` block appended by the callback:
 
-```
+~~~
 …your instruction…
 
 # How to execute code and use tools
-Code you write in a fenced Python block (i.e. ```python) will be executed in a sandbox.
-The Python Standard Library and a custom set of tools are available to you.
-To see the result of your code, you need to print it.
-
-For example, if you had the following tool:
+You have no callable function tools. To use a tool you must write Python code in a fenced Python block (i.e. ```python\n...\n```). Do not emit a function or tool call.
+The Python Standard Library and a set of custom tools are available to you as an importable library, listed in the `<code-mode>` section below.
+To see the result of your code, you need to print it. For example, if you had the following tool:
 
 ```
+<code-mode>
+
 from tools.slack import send_message
 
 def send_message(*, channel: str, text: str, thread_ts: str | None = ...) -> Any:
     """Send a message to a Slack channel."""
     ...
+
+</code-mode>
 ```
 
 To call the tool, you should write:
 
-"""
+````
 ```python
 from tools.slack import send_message
 
 print(send_message(channel="C123", text="hi"))
 ```
-"""
+````
 
 # How to use files and variables in between executions
-Code is executed in a new environment each time.
-To list available Artifacts, use the `list_artifacts` tool. To save an Artifact, use the `save_artifact` tool, and to load an Artifact, use the `load_artifact` tool.
+You can reuse variables and files within a turn. Between turns, to reuse variables and files you must save and load Artifacts.
+To list available Artifacts, use the `list_artifacts` tool, to save an Artifact, use the `save_artifact` tool, and to load an Artifact, use the `load_artifact` tool.
+Tool results are automatically saved as Artifacts.
 
 <code-mode>
 
@@ -393,7 +399,9 @@ from tools import save_artifact, load_artifact, list_artifacts
 …
 
 </code-mode>
-```
+~~~
+
+With `save_tool_results_as_artifacts` enabled (the default), each non-artifact tool above — e.g. `list_channels` and `send_message` — also carries two optional `artifact_name: str | None = ...` / `artifact_description: str | None = ...` parameters for naming its saved result.
 
 When the rendered catalog exceeds `max_catalog_chars`, the per-tool sections are replaced with:
 
@@ -416,7 +424,7 @@ Text and JSON-like MIME types travel as plain strings in artifact tools; binary
 
 `RemoteBackend` is designed for multi-tenant production use where untrusted users submit arbitrary Python code:
 
-- **One container per execution.** Fresh container per request — no shared filesystem, memory, or processes.
+- **One container per turn (one tenant, one invocation).** Within a turn the process/filesystem are reused across that turn's code blocks; the container is destroyed at turn end, with **no cross-turn or cross-tenant sharing**.
 - **Environment sanitization.** All env vars are stripped except a safe allowlist (`PATH`, `HOME`, `USER`, locale vars, Python config) before user code runs.
 - **Credentials never enter the sandbox.** API keys, OAuth tokens, and connection strings stay in the host process. The container only receives tool results.
 - **Bearer token authentication.** WebSocket connections without a valid token are rejected. Always set `ADK_CODE_MODE_AUTH_TOKEN` and layer platform-level auth on top.
@@ -441,7 +449,7 @@ Named "Unsafe" intentionally: it binds a TCP listener on `0.0.0.0`, communicates
 ## ⚠️ Limitations
 
 - **No credential-requesting tools.** Tools that need ADK to request credentials, confirmations, UI widgets, agent transfer, escalation, or that yield without an immediate response are rejected with a structured error.
-- **No state across executions.** Variables don't survive between turns. Use `save_artifact` / `load_artifact` to persist, or `/workspace` within a single run.
+- **State is turn-scoped.** Variables and `/workspace` files persist across code blocks **within** a turn, but reset between turns. Use `save_artifact` / `load_artifact` to persist across turns.
 - **No runtime package installation.** The sandbox ships with the Python Standard Library and the runtime's own dependencies only. Extra packages must be baked into the image at build time.
 
 ## 🛠️ Development