CONCEPT The code-execution tool is a real, server-side sandbox
Code execution is an Anthropic-hosted, server-side tool: you declare it in
tools (e.g. {"type": "code_execution_20260120", "name": "code_execution"}) and Claude
runs Python/bash in an isolated container on Anthropic's infrastructure — no client-side execution
loop. Results come back as content blocks in the same response (for bash, a
bash_code_execution_tool_result block with .content.stdout /
.stderr / .return_code). The container persists and can be reused across requests.
tool_result.CONCEPT Programmatic tool calling: Claude composes tool calls in a script
Normally each tool call is a round trip: Claude calls → the result lands in Claude's context → Claude reasons → calls again. Three sequential lookups = three round trips, and every intermediate result burns context tokens. Programmatic tool calling (PTC) lets Claude write a script that invokes your tools as functions inside the code-execution container:
- When the script calls a tool, the container pauses, the call is executed (client- or server-side), and the result returns to the running code — not to Claude's context.
- The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude.
- Token cost scales with the final output, not the intermediate results — the win for many sequential calls or large intermediate payloads you want filtered before they hit the window.
How to enable it (no beta header): add the code_execution_20260120 tool
and set "allowed_callers": ["code_execution_20260120"] on each custom tool the script may
call. Available on Opus 4.5+ / Sonnet 4.5+.
strict: true, disable_parallel_tool_use, a forced tool_choice, or MCP
tools. And when you respond to a pending programmatic call, the user message must contain only
tool_result blocks (no text).DIAGRAM Round trips vs. one script
all payloads in window"] end subgraph PTC["Programmatic tool calling"] B1["Claude writes ONE script"] --> B2["code_exec container runs it"] B2 --> B3["script calls tools as fns
(pause → run → resume)"] B3 --> B4["results stay in the CODE,
filtered by loops/branches"] B4 --> B5["🟢 only final output
returns to Claude"] end classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class B5 ok; class A7 bad;
CODE Enable code execution + a programmatically-callable tool
Declaring code_execution and marking lookup_orders with
allowed_callers lets Claude invoke it from inside a script, keeping the (potentially large) order
list out of its context.
resp = client.messages.create( model="claude-opus-4-8", max_tokens=16000, tools=[ {"type": "code_execution_20260120", "name": "code_execution"}, # server sandbox { "name": "lookup_orders", "description": "Return all orders for a customer id.", "allowed_callers": ["code_execution_20260120"], # callable from code "input_schema": {"type": "object", "properties": {"customer_id": {"type": "string"}}, "required": ["customer_id"]}, }, ], messages=[{"role": "user", "content": "Of my orders, how many shipped late? Just the count."}], ) # Claude writes code that calls lookup_orders(...), loops over the results # INSIDE the container, and returns only the count. Read stdout: for block in resp.content: if block.type == "bash_code_execution_tool_result": print(block.content.stdout) # e.g. "7" # NOTE: not compatible with strict / disable_parallel_tool_use / # forced tool_choice / MCP tools. Replies to pending PTC calls = # tool_result blocks ONLY (no text).
TRADE-OFFS When to hand orchestration to code
✅ Programmatic tool calling
- Many sequential/looping tool calls collapse into one turn
- Large intermediate results filtered before reaching context
- Token cost tracks the final output, not the raw payloads
⚠️ Constraints & cost
- No
strict, nodisable_parallel_tool_use, no forced tool, no MCP tools - Needs the code-execution sandbox (Opus 4.5+ / Sonnet 4.5+)
- Overkill for one or two calls Claude can just make directly
EXAM TRAPS
bash_code_execution_tool_result blocks. Nothing to run locally.tool_choice:{"type":"tool",…},
strict:true, disable_parallel_tool_use, or MCP tools. → All
incompatible with programmatic tool calling.tool_result blocks. And PTC needs no beta header — don't invent one.PRACTICE
Q1 · Where do intermediate tool results go under programmatic tool calling?
Into the running code in the code-execution container — not into Claude's context. The script processes them with normal control flow and returns only its final output to Claude, so token cost tracks that output, not the raw payloads.
Q2 · What two things must you configure to let Claude call your tool from a script?
Declare the code-execution tool (code_execution_20260120) and set
"allowed_callers": ["code_execution_20260120"] on the custom tool. No beta header is needed
(Opus 4.5+ / Sonnet 4.5+).
Q3 · Name two features PTC is incompatible with, and why it matters.
Any of: strict: true, disable_parallel_tool_use, forced
tool_choice, MCP tools. It matters because reaching for one of those alongside PTC will fail — you
can't, say, force a tool and have Claude orchestrate tools in code at once.