feat: Claude code execution tool and programmatic tool calling

[klin333]

Summary

This PR adds support for Anthropic's server-side code execution tool and programmatic tool calling (PTC) to ellmer.

• claude_tool_code_execution(): a built-in tool definition that enables Claude's server-side code execution sandbox, including downloading/handling of output files, container reuse across conversation turns, and expired-container recovery.
• tool(allowed_callers = ...): lets a client-defined tool be invoked programmatically from inside Claude's code execution environment, not just by the model directly. Tool results are serialized back into the sandbox.

The headline capability is the combination of the two: with programmatic tool calling, data returned by client tools (e.g. a SQL query tool) flows directly into the code execution sandbox without passing through the model's context. Without PTC, the model has to regurgitate tool output token-by-token before any code can use it — prohibitively token-inefficient for things like large SQL result sets. With PTC, Claude writes code that calls the tool, receives the result inside the sandbox, and only the final computed answer needs to surface to the model.

Supporting work included here:

• Streaming support for programmatic tool calls, including paused/resumed tool-call turns.
• Prompt-caching breakpoints that remain valid when a conversation ends in a programmatic tool result.
• Conversation state rollback when chat()/stream() fails mid-tool-loop, so a failed request doesn't corrupt the turn history.
• Replay of server-side tool content on providers that don't support it (OpenAI-compatible, DeepSeek), so a conversation started on Claude can be continued elsewhere without crashing.
• Foundation fix (983f025): extra_args$tools is now appended rather than merged with utils::modifyList(), which silently dropped unnamed list entries.

Minimal example

A local R tool returns an employee's expense rows as JSON. Opting it in via allowed_callers lets Claude's code call it from inside the sandbox:

library(ellmer)

get_expenses <- function(employee) {
  expenses <- data.frame(
    employee = c("Emma", "Emma", "Victor", "Tara", "Kai", "Kai"),
    amount = c(2500, 2700, 4100, 1200, 1500, 900),
    category = c("travel", "lodging", "equipment", "software", "software", "office")
  )
  jsonlite::toJSON(
    expenses[expenses$employee == employee, ],
    dataframe = "rows",
    auto_unbox = TRUE
  )
}

expense_tool <- tool(
  get_expenses,
  description = paste(
    "Look up an employee's expense line items.",
    "Returns a JSON array of objects with fields:",
    "employee (string), amount (number), category (string)."
  ),
  arguments = list(employee = type_string()),
  # Opt in to programmatic tool calling: Claude's *code* may call this tool
  # from inside the code-execution sandbox, not just the model directly.
  allowed_callers = "code_execution_20250825"
)

chat <- chat_anthropic(model = "claude-sonnet-4-6", echo = "all")
chat$register_tool(claude_tool_code_execution())
chat$register_tool(expense_tool)

chat$chat("Which of Emma, Victor, Tara, Kai exceeded their $5000 total expense budget?")

Live transcript (echo output, abridged)

Claude writes Python that calls the R tool four times in parallel inside the sandbox; ellmer executes get_expenses() locally for each call and returns the rows to the sandbox, not to the model's context.

> Which of Emma, Victor, Tara, Kai exceeded their $5000 total expense budget?
< I'll look up the expenses for all four employees at the same time!
< [code execution]:
<
< import asyncio
<
< async def main():
<     results = await asyncio.gather(
<         get_expenses({"employee": "Emma"}),
<         get_expenses({"employee": "Victor"}),
<         get_expenses({"employee": "Tara"}),
<         get_expenses({"employee": "Kai"})
<     )
<     for name, result in zip(["Emma", "Victor", "Tara", "Kai"], results):
<         print(f"{name}: {result}")
<
< asyncio.run(main())
<
< [tool request (toolu_01…vnet)]: get_expenses(employee = "Emma")
< [tool request (toolu_01…8zh8)]: get_expenses(employee = "Victor")
< [tool request (toolu_01…kAGp)]: get_expenses(employee = "Tara")
< [tool request (toolu_01…segH)]: get_expenses(employee = "Kai")
[tool result  (toolu_01…vnet)]: [{"employee":"Emma","amount":2500,"category":"travel"},{"employee":"Emma","amount":2700,"category":"lodging"}]
[tool result  (toolu_01…8zh8)]: [{"employee":"Victor","amount":4100,"category":"equipment"}]
[tool result  (toolu_01…kAGp)]: [{"employee":"Tara","amount":1200,"category":"software"}]
[tool result  (toolu_01…segH)]: [{"employee":"Kai","amount":1500,"category":"software"},{"employee":"Kai","amount":900,"category":"office"}]
< [code execution result] (exit 0)
< Emma: [{"employee":"Emma","amount":2500,...},{"employee":"Emma","amount":2700,...}]
< Victor: [{"employee":"Victor","amount":4100,...}]
< Tara: [{"employee":"Tara","amount":1200,...}]
< Kai: [{"employee":"Kai","amount":1500,...},{"employee":"Kai","amount":900,...}]
<
< | Employee | Total Expenses | Over Budget? |
< |----------|---------------|--------------|
< | Emma | $2,500 + $2,700 = **$5,200** | ✅ Yes |
< | Victor | **$4,100** | ❌ No |
< | Tara | **$1,200** | ❌ No |
< | Kai | $1,500 + $900 = **$2,400** | ❌ No |
<
< Only **Emma** exceeded the $5,000 budget, with a total of **$5,200** (over by
< $200) across travel and lodging expenses.

Review scope

This branch builds on the MCP connector work (everything before 983f025, related to #985). For review, focus on changes from 983f025 onward — that is where the code execution / programmatic tool calling work starts.

Test plan

• testthat suites for provider-claude, tools-built-in, tools-def, chat, chat-tools, provider-deepseek, provider-openai-compatible: 680 passed, 0 failed (29 skipped pending live API keys)
• Live end-to-end run of the minimal example above against the Anthropic API (parallel programmatic tool calls, streaming)
• Live end-to-end testing via a Shiny app driving SQL-over-MCP results into code execution

🤖 Generated with Claude Code

[github-actions]

[air] _{reported by reviewdog 🐶}

Suggested change

	switch(class(content)[1],
	switch(
	class(content)[1],

[github-actions]

[air] _{reported by reviewdog 🐶}

Suggested change

	request = ContentToolRequest(id = "srvtoolu_1", name = "", arguments = list()),
	request = ContentToolRequest(
	id = "srvtoolu_1",
	name = "",
	arguments = list()
	),

[github-actions]

[air] _{reported by reviewdog 🐶}

Suggested change

	request = ContentToolRequest(id = "srvtoolu_1", name = "", arguments = list()),
	request = ContentToolRequest(
	id = "srvtoolu_1",
	name = "",
	arguments = list()
	),

[github-actions]

[air] _{reported by reviewdog 🐶}

Suggested change

	request = ContentToolRequest(id = "mcptoolu_1", name = "", arguments = list()),
	request = ContentToolRequest(
	id = "mcptoolu_1",
	name = "",
	arguments = list()
	),

[thisisnic]

Thanks for the PR @klin333.

I'm going to close it for now, as it's not reviewable in its current state being based off multiple unmerged PRs.

Please could you wait for the other PRs to merge before submitting a new one? At this point, it's unclear what changes will be needed to the other PRs, and so you might need to totally rewrite your code here if they change drastically or don't get merged in the end.

Once they've merged, then you can rebase off the main branch and submit a new PR.

When you do submit a new PR, would you mind writing the PR description yourself? Claude generates a lot of content, and it'd be more useful to hear your own summary about what you've implemented and the design decisions you've made as you interacted with Claude.

[klin333]

No problem. Was going to wait but then Hadley posted about giving LLM a custom calculator tool, and thought to make this PR public so people know it’s not far from writing custom calculate tools to having full server side python execution.