Skip to content

feat: return full tool results and parsed load_artifact content (re-applies #27) - #34

Merged
benclarkeio merged 2 commits into
mainfrom
feat/full-tool-results-default
Nov 16, 2026
Merged

benclarkeio merged 2 commits into
mainfrom
feat/full-tool-results-default

Conversation

@benclarkeio

@benclarkeio benclarkeio commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR makes #27's behaviour the default again, for release as 2.2.0. #27 gave the code full tool results and parsed artifact content. #29 held it back on purpose for 2.1.0: its last commit, "fix: preserve Code Mode 2.x result contracts", put the 2.x formats back so 2.1.0 could ship as a minor release. So 2.1.0 and main still swap any tool result over 50 KB for a pointer, and load_artifact still returns raw JSON text that the model then parses by hand.

The changes only affect what the agent's code sees. The agent's tools are loaded on every call, so no existing code relies on the old formats.

This replaces #32 and #33.

What changes

  • Tool results: the code always gets the real result. Results are still saved as artifacts so later turns can reload them. The 50,000-byte threshold and its {"tool_result_artifact", "note"} pointer are gone, and so are the | ToolResultArtifact stub return type and the pointer sentence in the tool description.

    • Saved results use the same JSON-safe conversion as the reply to the code (_json.json_safe), so a dataclass or Pydantic result reloads as the value the code received.
  • load_artifact returns the content itself:

    • JSON (application/json, *+json): the parsed value
    • other text: a str
    • binary: {"mime_type": str, "bytes": <base64 str>}

    Text is encoded and decoded with the mime type's charset, with UTF-8 as the default. JSON that fails to parse comes back as a str.

  • MCP failures: only an McpTool result with isError: true raises ToolError, the same way only a RestApiTool result can raise HTTPStatusError. Other tools that return that shape, such as load_artifact reading a saved failed MCP result, return it as data.

  • Remote sandbox: RemoteBackend refuses a frame over max_message_size before sending it. An oversized tool reply reaches the code as an error, and the sandbox stays connected. An oversized code block fails the call, and the next block gets a fresh sandbox.

  • API: DEFAULT_LARGE_RESULT_THRESHOLD is removed, along with the large_result_threshold parameter of ToolResultArtifactTool and wrap_tool_result_as_artifact. agent-run uses none of these.

  • The README, docstrings and tests now describe the new behaviour.

What's kept from #28 and #29

  • Typed stub return values, TypedDict return types in the catalog, escaped docstrings, the names-tier hint to read a function's stub, and the tool description's sentence on what is saved and how to load it.
  • MCP tools still return ADK's full result, with structuredContent typed from the tool's outputSchema.

How #27 was re-applied

I applied git diff dcb15ab ed4626d to main with a 3-way merge and resolved the rest by hand.

Sandbox, release and agent-run

  • The sandbox needs no changes. ToolResultFrame and PROTOCOL_VERSION are unchanged, and nothing under sandbox-wheel/ changes.
  • release-please bumps both __about__.py files together. On release, release-please.yml publishes both adk-code-mode and adk-code-mode-sandbox, then the base image. Merging this PR only opens the 2.2.0 release PR; merging that release PR publishes to PyPI.
  • agent-run: pin adk-code-mode==2.2.0 in pyproject.toml, in both dependencies and the dev group's adk-code-mode[docker], then run uv lock. No code changes are needed. The sandbox image picks up adk-code-mode-sandbox==2.2.0 from uv.lock.

Tests

  • feat!: return full tool results and artifact content to the code #27's tests are restored. They cover:
    • large results returned in full and saved
    • saved results reloading as the original value, including a dataclass result
    • load_artifact for each mime type and charset, and save_artifact → load_artifact round-trips
    • the remote session refusing a frame over max_message_size without sending it
  • feat: show return types in the catalog and point the names tier at stubs #29's pointer stub test now checks that a wrapped tool keeps its return type, and the description test checks that the pointer sentence is gone.
  • The MCP failure tests use an McpTool, and a non-MCP tool returning an isError: true result is checked to come back unchanged.
  • make ci passes locally: ruff, mypy and pytest (257 passed). The 3 Docker-marked tests didn't run because no Docker daemon was available.

Generated by Claude Code

…pplies #27)

#29's squash put the 2.x result formats back before 2.1.0, so #27 never
shipped. Re-apply #27's diff on top of main, keeping the typed stubs,
catalog return types and MCP result envelope from #28/#29.

- Drop the 50,000-byte large-result threshold and its
  `{"tool_result_artifact", "note"}` substitute: the code always gets the
  real tool result, which is still saved as an artifact
- Save tool results with the same JSON-safe conversion as the RPC reply
  (`_json.json_safe`), so a saved result reloads as the value the code got
- `load_artifact` returns parsed JSON, a `str` for other text, or
  `{"mime_type", "bytes"}` for binary, instead of `{"kind", "data",
  "mime_type"}`; text is encoded and decoded with the mime type's charset,
  defaulting to UTF-8
- `RemoteBackend` refuses a frame over `max_message_size` before sending
  it, so an oversized tool reply reaches the code as an error instead of
  closing the sandbox connection
- Remove `DEFAULT_LARGE_RESULT_THRESHOLD` and the `large_result_threshold`
  parameter of `ToolResultArtifactTool` and `wrap_tool_result_as_artifact`
- Drop the `ToolResultArtifact` pointer #29 added to wrapped tools' stub
  and catalog return types, and the description's large-result sentence
- Restore #27's tests and update the README and docstrings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7F1kLDzPsAwBRC5KV1

@benclarkeio benclarkeio left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Found two P2 regressions that should be addressed before merging:

  1. Parsed artifact JSON containing isError: true is treated as a failed MCP call, preventing the code from reading valid artifact contents.
  2. Rejecting an oversized RunFrame after staging the workspace leaves the remote protocol out of sync and loses the turn on the next block.

Both reproductions pass on base commit c97dca8517e262756cd6c6f35e1f43031c8430e2 and fail on PR commit 7cd5c128790719b1c72f21991e0b9ca3bdc83a91.

Validation: lint, formatting, and type checks pass. The existing non-Docker suite reports 253 passed and three timeout-test failures; all three failures also reproduce on the base commit. The three Docker-marked tests were excluded.

Comment thread src/adk_code_mode/_artifact_tools.py Resolved
Comment thread src/adk_code_mode/runtime/remote.py Resolved
- Run the MCP failure check only for `McpTool`, as the REST check already
  does for `RestApiTool`; `load_artifact` now returns parsed JSON, so a
  saved failed MCP result (or any JSON with `isError: true`) raised
  `McpToolError` when reloaded
- Raise `RuntimeError` for a frame over `max_message_size`, so a block
  whose `RunFrame` is refused discards its turn instead of leaving the
  sandbox waiting for it after the workspace archive was sent
- Use an `McpTool` in the MCP failure tests and check that other tools
  returning the same shape are left alone

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CXLVCru82aWPycMKN
@benclarkeio
benclarkeio merged commit f39088e into main Nov 16, 2026
6 checks passed
@benclarkeio
benclarkeio deleted the feat/full-tool-results-default branch November 16, 2026 17:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants