adk-code-mode 0.3.0__tar.gz → 0.4.1__tar.gz

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

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

{adk_code_mode-0.3.0 → adk_code_mode-0.4.1}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.4.1](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.4.0...adk-code-mode-v0.4.1) (2026-07-10)
+
+
+### Documentation
+
+* note the sandbox writes to `/tools` in remote deployment guide ([96bb45e](https://github.com/a2anet/adk-code-mode/commit/96bb45e4e18d9d54709f4c10b6b09cf3567ee385))
+
+## [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)
 
 

{adk_code_mode-0.3.0 → adk_code_mode-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adk-code-mode
-Version: 0.3.0
+Version: 0.4.1
 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,6 +41,7 @@ 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 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).
@@ -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,16 +152,7 @@ print(send_message(channel="C123", text="hi"))
 
 ## 🌐 Remote Deployment
 
-**Every turn runs in its own container.** The container accepts exactly one WebSocket connection and holds it open for the whole turn, executing **one or more** code blocks with persistent globals + `/workspace`, then exits when the turn ends (`ShutdownFrame` or disconnect). The hosting platform destroys the container after each turn — no cross-turn or cross-tenant data leakage, no residual state. You **must** configure your platform for one container per turn (`--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 the tools tar **once**, then announces readiness
-4. Sanitizes the environment (strips all env vars except a safe allowlist)
-5. For each code block: receives that block's workspace tar, executes user code (tools proxied back to the host over the same WebSocket; globals + `/workspace` persist across blocks), then returns stdout/stderr and the updated workspace
-6. Exits when the turn ends (`ShutdownFrame` or disconnect)
+**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
 
@@ -183,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> \
@@ -197,10 +194,11 @@ gcloud run deploy adk-code-mode-sandbox \
     --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). Also add the `/health` startup probe below.
+> 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:
 
@@ -215,22 +213,20 @@ RemoteBackend(
 
 > **`--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.
 
-> **Configure an HTTP startup probe against `/health`.** Cloud Run's default TCP probe opens a raw socket that the `websockets` server rejects as a malformed HTTP request, which can race with real traffic during cold starts and surface to clients as `HTTP 503` on the WebSocket handshake. Add `--startup-probe="httpGet.path=/health,httpGet.port=8080,timeoutSeconds=3,periodSeconds=3,failureThreshold=80"` (or equivalent) so probes hit the `/health` endpoint the sandbox handles natively. Keep `periodSeconds` small (e.g. `3`): it sets how long Cloud Run waits before re-probing, so a short period lets a ready container start serving in ~3s instead of ~10s — raise `failureThreshold` to keep the same overall startup budget (`periodSeconds × failureThreshold`). Turn-scoping already gives demand-driven warmth (a container stays up for the whole turn), so `--min-instances=0` is fine; only set `--min-instances` if you want to eliminate cold starts at the cost of a paid warm pool.
-
 ### Deploy on other platforms
 
 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 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`.
+3. **Keep `/workspace` and `/tools` writable.** The sandbox stages input files into `/workspace` and materialises the `tools` package into `/tools` at connect time. If you set a read-only root filesystem (e.g., `readOnlyRootFilesystem: true` in Kubernetes), mount both as writable volumes (e.g., an `emptyDir`).
 4. **Authenticate connections.** Set `ADK_CODE_MODE_AUTH_TOKEN` and layer platform-level auth (IAM, NetworkPolicy, security groups) on top.
 
 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       |
@@ -252,8 +248,6 @@ RemoteBackend(
 )
 ```
 
-`connect_timeout` defaults to `10s` — fail a stalled connect fast and retry rather than block. `RemoteBackend` retries transient connect failures up to `start_attempts` times with linear backoff + jitter; raise `connect_timeout` (and/or `start_attempts`) for platforms with slow cold starts.
-
 ## 🗂️ Storage
 
 Code Mode exposes two file surfaces:
@@ -287,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:
@@ -300,17 +304,18 @@ The same image works for both `RemoteBackend` and `UnsafeLocalDockerBackend`. To
 
 ## ⚙️ Configuration
 
-### Catalog overflow
+All settings are `CodeModeCodeExecutor` constructor arguments:
 
-`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.
+| 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`. |
 
-```python
-CodeModeCodeExecutor(tools=..., backend=..., max_catalog_chars=20_000)
-```
-
-### Output truncation
-
-`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
@@ -318,53 +323,9 @@ spilled = load_artifact(filename="code_mode/stdout/<execution-id>.txt")
 print(spilled["data"][-2000:])
 ```
 
-### Code size limit
-
-`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,
-)
-```
-
-`timeout_seconds` / `per_tool_timeout_seconds` stay `None` by default; with turn-scoping the effective per-turn wall-clock ceiling is the platform request timeout (e.g. Cloud Run `--timeout`).
-
 ### Turn-scoped sessions
 
-A sandbox container is held open for the duration of a **turn** (one ADK invocation) and reused across that turn's code blocks, so cold start is paid at most once per turn instead of once per block. State — Python globals **and** `/workspace` — persists across a turn's blocks and resets between turns (use ADK Artifacts for cross-turn persistence).
-
-The container is released when the turn ends. Wire `code_executor.release_invocation(callback_context.invocation_id)` into your agent's `after_agent_callback` to free it the moment the turn finishes:
-
-```python
-def _release(callback_context):
-    code_executor.release_invocation(callback_context.invocation_id)
-
-agent = LlmAgent(..., after_agent_callback=[_release])
-```
-
-Two safety nets cover turns that never signal a clean end: an idle reaper closes sessions idle longer than `session_idle_timeout_seconds` (default `600`), and a mid-turn connection loss (or a `timeout_seconds` firing) drops the session — in-turn state (globals + `/workspace`) is lost and the next block reconnects on a fresh container.
-
-If the connection drops **while a block is running**, the executor re-runs the block only when the code provably never reached the sandbox, so a reconnect can't duplicate a tool call's side effects. What happens depends on how far the block got before the drop:
-
-- **Not run** — the `RunFrame` never left the host, so the code did not execute; the executor reconnects on a fresh container and retries the block once automatically.
-- **Ran (output lost)** — a `DoneFrame` came back before the drop, so the code executed but its stdout/stderr and output files couldn't be returned; the block is **not** re-run.
-- **Unknown** — the `RunFrame` was sent but no `DoneFrame` arrived, so whether the code executed is unknowable; the block is **not** re-run.
-
-For the `Ran` and `Unknown` cases the block returns a short message in its `stderr` telling the model what happened, so it can decide whether to re-run the code or check for its effects rather than the executor silently repeating it.
-
-```python
-CodeModeCodeExecutor(tools=..., backend=..., session_idle_timeout_seconds=600)
-```
-
-> Turn-scoping is wire-protocol **v2**. The host wheel and the sandbox image must be upgraded together — a version mismatch fails fast with `ProtocolVersionMismatchError` — so rebuild and push the sandbox image when you upgrade.
+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
 
@@ -383,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
-Within a turn the sandbox is stateful: variables you define and files you write under `/workspace` (the working directory) persist across the successive code blocks you run before replying to the user. They reset at the start of your next turn.
-To carry data across turns, use Artifacts: list them with the `list_artifacts` tool, save with `save_artifact`, and load with `load_artifact`.
+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>
 
@@ -435,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:
 

{adk_code_mode-0.3.0 → adk_code_mode-0.4.1}/README.md

@@ -14,6 +14,7 @@ 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 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).
@@ -51,11 +52,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)
 
@@ -77,6 +79,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",
@@ -89,6 +94,7 @@ root_agent = LlmAgent(
         ),
     ),
     before_model_callback=code_mode_before_model_callback(executor),
+    after_agent_callback=[_release_sandbox],
 )
 ```
 
@@ -119,16 +125,7 @@ print(send_message(channel="C123", text="hi"))
 
 ## 🌐 Remote Deployment
 
-**Every turn runs in its own container.** The container accepts exactly one WebSocket connection and holds it open for the whole turn, executing **one or more** code blocks with persistent globals + `/workspace`, then exits when the turn ends (`ShutdownFrame` or disconnect). The hosting platform destroys the container after each turn — no cross-turn or cross-tenant data leakage, no residual state. You **must** configure your platform for one container per turn (`--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 the tools tar **once**, then announces readiness
-4. Sanitizes the environment (strips all env vars except a safe allowlist)
-5. For each code block: receives that block's workspace tar, executes user code (tools proxied back to the host over the same WebSocket; globals + `/workspace` persist across blocks), then returns stdout/stderr and the updated workspace
-6. Exits when the turn ends (`ShutdownFrame` or disconnect)
+**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
 
@@ -156,7 +153,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> \
@@ -170,10 +167,11 @@ gcloud run deploy adk-code-mode-sandbox \
     --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). Also add the `/health` startup probe below.
+> 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:
 
@@ -188,22 +186,20 @@ RemoteBackend(
 
 > **`--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.
 
-> **Configure an HTTP startup probe against `/health`.** Cloud Run's default TCP probe opens a raw socket that the `websockets` server rejects as a malformed HTTP request, which can race with real traffic during cold starts and surface to clients as `HTTP 503` on the WebSocket handshake. Add `--startup-probe="httpGet.path=/health,httpGet.port=8080,timeoutSeconds=3,periodSeconds=3,failureThreshold=80"` (or equivalent) so probes hit the `/health` endpoint the sandbox handles natively. Keep `periodSeconds` small (e.g. `3`): it sets how long Cloud Run waits before re-probing, so a short period lets a ready container start serving in ~3s instead of ~10s — raise `failureThreshold` to keep the same overall startup budget (`periodSeconds × failureThreshold`). Turn-scoping already gives demand-driven warmth (a container stays up for the whole turn), so `--min-instances=0` is fine; only set `--min-instances` if you want to eliminate cold starts at the cost of a paid warm pool.
-
 ### Deploy on other platforms
 
 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 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`.
+3. **Keep `/workspace` and `/tools` writable.** The sandbox stages input files into `/workspace` and materialises the `tools` package into `/tools` at connect time. If you set a read-only root filesystem (e.g., `readOnlyRootFilesystem: true` in Kubernetes), mount both as writable volumes (e.g., an `emptyDir`).
 4. **Authenticate connections.** Set `ADK_CODE_MODE_AUTH_TOKEN` and layer platform-level auth (IAM, NetworkPolicy, security groups) on top.
 
 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       |
@@ -225,8 +221,6 @@ RemoteBackend(
 )
 ```
 
-`connect_timeout` defaults to `10s` — fail a stalled connect fast and retry rather than block. `RemoteBackend` retries transient connect failures up to `start_attempts` times with linear backoff + jitter; raise `connect_timeout` (and/or `start_attempts`) for platforms with slow cold starts.
-
 ## 🗂️ Storage
 
 Code Mode exposes two file surfaces:
@@ -260,6 +254,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:
@@ -273,17 +277,18 @@ The same image works for both `RemoteBackend` and `UnsafeLocalDockerBackend`. To
 
 ## ⚙️ Configuration
 
-### Catalog overflow
+All settings are `CodeModeCodeExecutor` constructor arguments:
 
-`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.
+| 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`. |
 
-```python
-CodeModeCodeExecutor(tools=..., backend=..., max_catalog_chars=20_000)
-```
-
-### Output truncation
-
-`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
@@ -291,53 +296,9 @@ spilled = load_artifact(filename="code_mode/stdout/<execution-id>.txt")
 print(spilled["data"][-2000:])
 ```
 
-### Code size limit
-
-`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,
-)
-```
-
-`timeout_seconds` / `per_tool_timeout_seconds` stay `None` by default; with turn-scoping the effective per-turn wall-clock ceiling is the platform request timeout (e.g. Cloud Run `--timeout`).
-
 ### Turn-scoped sessions
 
-A sandbox container is held open for the duration of a **turn** (one ADK invocation) and reused across that turn's code blocks, so cold start is paid at most once per turn instead of once per block. State — Python globals **and** `/workspace` — persists across a turn's blocks and resets between turns (use ADK Artifacts for cross-turn persistence).
-
-The container is released when the turn ends. Wire `code_executor.release_invocation(callback_context.invocation_id)` into your agent's `after_agent_callback` to free it the moment the turn finishes:
-
-```python
-def _release(callback_context):
-    code_executor.release_invocation(callback_context.invocation_id)
-
-agent = LlmAgent(..., after_agent_callback=[_release])
-```
-
-Two safety nets cover turns that never signal a clean end: an idle reaper closes sessions idle longer than `session_idle_timeout_seconds` (default `600`), and a mid-turn connection loss (or a `timeout_seconds` firing) drops the session — in-turn state (globals + `/workspace`) is lost and the next block reconnects on a fresh container.
-
-If the connection drops **while a block is running**, the executor re-runs the block only when the code provably never reached the sandbox, so a reconnect can't duplicate a tool call's side effects. What happens depends on how far the block got before the drop:
-
-- **Not run** — the `RunFrame` never left the host, so the code did not execute; the executor reconnects on a fresh container and retries the block once automatically.
-- **Ran (output lost)** — a `DoneFrame` came back before the drop, so the code executed but its stdout/stderr and output files couldn't be returned; the block is **not** re-run.
-- **Unknown** — the `RunFrame` was sent but no `DoneFrame` arrived, so whether the code executed is unknowable; the block is **not** re-run.
-
-For the `Ran` and `Unknown` cases the block returns a short message in its `stderr` telling the model what happened, so it can decide whether to re-run the code or check for its effects rather than the executor silently repeating it.
-
-```python
-CodeModeCodeExecutor(tools=..., backend=..., session_idle_timeout_seconds=600)
-```
-
-> Turn-scoping is wire-protocol **v2**. The host wheel and the sandbox image must be upgraded together — a version mismatch fails fast with `ProtocolVersionMismatchError` — so rebuild and push the sandbox image when you upgrade.
+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
 
@@ -356,37 +317,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
-Within a turn the sandbox is stateful: variables you define and files you write under `/workspace` (the working directory) persist across the successive code blocks you run before replying to the user. They reset at the start of your next turn.
-To carry data across turns, use Artifacts: list them with the `list_artifacts` tool, save with `save_artifact`, and load with `load_artifact`.
+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>
 
@@ -408,7 +372,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:
 

{adk_code_mode-0.3.0 → adk_code_mode-0.4.1}/docker/Dockerfile

@@ -9,8 +9,8 @@ RUN pip install --no-cache-dir /tmp/adk_code_mode_sandbox-*.whl \
     && rm /tmp/adk_code_mode_sandbox-*.whl
 
 RUN useradd -m -d /home/sandbox sandbox \
-    && mkdir -p /workspace \
-    && chown sandbox:sandbox /workspace
+    && mkdir -p /workspace /tools \
+    && chown sandbox:sandbox /workspace /tools
 USER sandbox
 
 EXPOSE 8080

{adk_code_mode-0.3.0 → adk_code_mode-0.4.1}/sandbox-wheel/src/adk_code_mode_sandbox/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
 #
 # SPDX-License-Identifier: Apache-2.0
-__version__ = "0.3.0"  # x-release-please-version
+__version__ = "0.4.1"  # x-release-please-version