feat: add programmatic tool caller

[mkmeral]

Description

Adds programmatic_tool_caller tool that enables code-based tool invocation. Agents can write Python code that calls other tools as async functions, reducing API round-trips and enabling complex orchestration patterns like loops, parallel execution, and chaining.

Key Features

• Async-first design: Tools exposed as await tool_name(...) — code runs in async context automatically
• Only print() output returned: Tool results stay in code execution context, don't enter agent's context window unless explicitly printed
• User confirmation: Code preview shown before execution, with opt-out via BYPASS_TOOL_CONSENT=true
• Configurable allowed tools: Filter which tools are exposed via PROGRAMMATIC_TOOL_CALLER_ALLOWED_TOOLS
• Namespace clash detection: Raises ValueError if a tool name conflicts with reserved namespace entries (asyncio, __name__) or extra modules
• BaseException safety: SystemExit and KeyboardInterrupt in user code are caught and returned as error results (not propagated to host)

Example Usage

from strands import Agent
from strands_tools import programmatic_tool_caller, calculator

agent = Agent(tools=[programmatic_tool_caller, calculator])

result = agent.tool.programmatic_tool_caller(
    code="""
result = await calculator(expression="2 + 2")
print(f"Result: {result}")

# Parallel execution
results = await asyncio.gather(
    calculator(expression="10 * 1"),
    calculator(expression="10 * 2"),
)
print(f"Parallel results: {results}")
"""
)

Limitations

• Tools that use interrupts (human-in-the-loop) are not supported in this context
• exec() with user code — inherently requires trust in the code being executed
• No execution timeout — long-running code will block until completion
• asyncio.run() creates a new event loop — may conflict with environments that already have a running loop (e.g., Jupyter)

Environment Variables

Variable	Description
BYPASS_TOOL_CONSENT	Skip user confirmation if "true"
PROGRAMMATIC_TOOL_CALLER_ALLOWED_TOOLS	Comma-separated list of tools to expose (default: all except self)
PROGRAMMATIC_TOOL_CALLER_EXTRA_MODULES	Comma-separated list of extra Python modules to inject into namespace

Related Issues

• [FEATURE] Code-Based Tool Execution similar to smolagents sdk-python#1540
• [FEATURE] Support for Anthropic advanced tool use sdk-python#1349

Documentation PR

None yet — documentation PR needed before merge.

Type of Change

New feature

Testing

How have you tested the change?

• 31 unit tests covering executor, tool execution, validation, allowed tools filtering, BaseException handling, namespace clash detection

• 6 integration tests with real Agent and tools (async execution, loops, asyncio.gather, allowed tools)

• Tested on Linux, Windows, macOS × Python 3.10–3.13 (CI passing)

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[mkmeral]

Interrupt limitation with programmatic tool calls

Tools that use interrupts (human-in-the-loop) will raise a RuntimeError when invoked through the programmatic tool caller. The SDK's _ToolCaller has two guards:

• If an interrupt is already active when a direct tool call is made → RuntimeError("cannot directly call tool during interrupt")
• If a tool raises an interrupt during a direct call → RuntimeError("cannot raise interrupt in direct tool call")

This is a known SDK limitation — direct/programmatic tool calls have no mechanism to pause execution, collect human input, and resume. The error surfaces as a failed tool result back to the agent, so the agent can reason about it and try an alternative approach.

[agent-of-mkmeral]

🔴 Adversarial Testing Result: FAIL — 3 issues found

Scope: Full adversarial testing of programmatic_tool_caller — input boundaries, stdout/stderr restoration, async execution, namespace security, tool execution error paths, env var handling, contract verification, BaseException handling, indentation/wrapping, and concurrency.

Tests written: 47
Tests passing: 47 (all findings confirmed with reproducible artifacts)
Tests failing (findings): 3 bugs found and proven

Findings Summary

#	Category	Severity	Description
1	Bug	Critical	SystemExit and KeyboardInterrupt escape the tool — sys.exit() in user code kills the host process
2	Bug	Medium	Empty code and comment-only code cause SyntaxError due to async wrapping producing empty function body
3	Bug	Medium	Tool named asyncio shadows the required asyncio module in namespace, breaking all async functionality

---

Finding 1 — BaseException Escape (Critical)

Category: Bug
Severity: Critical

Reproduction:

# This kills the host process:
result = programmatic_tool_caller(code="import sys; sys.exit(42)", tool_context=ctx)
# ^^^ SystemExit propagates past except Exception — host dies

# This also escapes:
result = programmatic_tool_caller(code="raise KeyboardInterrupt()", tool_context=ctx)
# ^^^ KeyboardInterrupt propagates to caller

Root cause: The exception handlers are:

except SyntaxError:
    ...
except Exception:
    ...

SystemExit and KeyboardInterrupt inherit from BaseException, NOT Exception. They bypass both catch blocks.

Observed behavior: SystemExit propagates up the call stack, killing the host process. KeyboardInterrupt similarly escapes.

Expected behavior: User code should never be able to kill the host. The tool should catch these and return an error dict.

Fix:

except SyntaxError:
    ...
except (SystemExit, KeyboardInterrupt) as e:
    error_msg = f"Execution error: {type(e).__name__}: {e}"
    console.print(Panel(error_msg, title="[bold red]Error[/]", border_style="red"))
    return {"status": "error", "content": [{"text": error_msg}]}
except Exception:
    ...

Artifact: TestFinding2_BaseExceptionEscape::test_system_exit_escapes_tool, test_keyboard_interrupt_escapes_tool

---

Finding 2 — Empty/Comment-Only Code SyntaxError (Medium)

Category: Unhandled Edge Case
Severity: Medium

Reproduction:

# Empty code → SyntaxError
result = programmatic_tool_caller(code="", tool_context=ctx)
# Returns: {"status": "error", "content": [{"text": "Syntax error: expected an indented block..."}]}

# Comment-only code → SyntaxError  
result = programmatic_tool_caller(code="# just a comment", tool_context=ctx)
# Same SyntaxError

Root cause: The async wrapping does:

indented_code = textwrap.indent(code, "    ")
wrapped_code = f"async def __user_code__():\n{indented_code}\n"

Empty code → async def __user_code__():\n\n → empty function body = SyntaxError.
Comment-only → async def __user_code__():\n # comment\n → comments aren't statements = SyntaxError.

Expected behavior: Empty/comment-only code should succeed with (no output), same as passing x = 42.

Fix: Add pass if code strip is empty or comments-only:

if not code.strip() or all(line.strip().startswith('#') for line in code.strip().splitlines()):
    indented_code = "    pass"
else:
    indented_code = textwrap.indent(code, "    ")

Artifact: TestFinding1_EmptyCodeWrapping::test_empty_code_string_fails, test_comment_only_code_fails

---

Finding 3 — asyncio Module Shadowing (Medium)

Category: Bug
Severity: Medium

Reproduction:

# If a tool named 'asyncio' exists in the registry:
ns = _build_namespace({"asyncio"}, agent)
assert ns["asyncio"] is not asyncio_module  # True! It's now a tool wrapper
# asyncio.gather(), asyncio.sleep() etc. are now broken

Root cause: In _build_namespace(), asyncio module is injected first, then tools overwrite by name:

namespace["asyncio"] = asyncio  # ← injected
for tool_name in available_tools:
    namespace[tool_name] = _create_async_tool_function(...)  # ← overwrites 'asyncio'

Expected behavior: Reserved names (asyncio, __name__, extra modules) should not be overwritable by tool names.

Fix: Either exclude reserved names from tool injection, or inject tools first and modules after:

# Option A: Exclude reserved names
RESERVED = {"asyncio", "__name__"}
for tool_name in available_tools - RESERVED:
    namespace[tool_name] = ...

# Option B: Inject tools first, then required modules (modules win)
for tool_name in available_tools:
    namespace[tool_name] = ...
namespace["asyncio"] = asyncio  # Overwrite any tool shadowing

Artifact: TestFinding3_AsyncioShadowing::test_asyncio_tool_overwrites_module

---

What Survived

41 adversarial tests passed without finding issues:

• ✅ stdout/stderr properly restored after RuntimeError, SyntaxError, and user-replaced stdout
• ✅ Unicode, null bytes, large output all handled correctly
• ✅ Async code with user-defined coroutines, asyncio.sleep, asyncio.gather all work
• ✅ Tool errors properly propagate to user code via try/except
• ✅ asyncio.gather with 20 concurrent calls completes correctly
• ✅ Sequential tool calls in loops work correctly
• ✅ Namespace isolation: agent object not leaked, __name__ properly set
• ✅ Self-exclusion: programmatic_tool_caller never available in namespace
• ✅ Return format consistent (always {"status": ..., "content": [{"text": ...}]})
• ✅ Env var edge cases (extra commas, whitespace, empty strings) handled correctly
• ✅ Complex code structures (decorators, classes, nested indentation) work through async wrapping

---

🤖 AI agent response. Strands Agents. Feedback welcome!

[agent-of-mkmeral]

CI Fix: Merge from main

Root Cause & Fix

All 3 CI failures (Lint, Unit Tests, check-access-and-checkout) had the same root cause: the branch's pyproject.toml was outdated and diverged from main.

Specific issues:

1. Hatch version: Branch had hatch>=1.0.0,<1.16.0, but main updated to hatch>=1.16.5 — the old version caused module 'virtualenv.discovery.builtin' has no attribute 'propose_interpreters' (Lint failure) and No compatible environments found (Test/checkout failures)
2. Optional-dependencies normalization: Branch had underscored feature names (mem0_memory, a2a_client) while main fixed them to hyphens (mem0-memory, a2a-client) in PR fix: hatch virtual env fix with optional-dependencies normalization #409
3. pillow version: Branch had >=11.2.1,<12.0.0 while main bumped to >=12.1.1,<13.0.0 for CVE fix (fix(deps): support pillow 12.x to resolve CVE-2026-25990 #399)
4. pytest version: Branch had <9.0.0 while main updated to <10.0.0

Fix: Merged origin/main into the branch + fixed a ruff formatting artifact in tests/test_http_request.py.

Verification

• ✅ ruff format --check — all 143 files pass
• ✅ ruff check — all checks pass
• ✅ hatch run test-lint — passes
• ✅ pytest tests/test_programmatic_tool_caller.py — all 23 tests pass

⚠️ CI workflow needs maintainer approval to run (standard fork PR security policy).

🤖 AI agent response. Strands Agents. Feedback welcome!

[mkmeral]

/strands review

[agent-of-mkmeral]

⚠️ PR Description Update Needed

@mkmeral — I pushed the code fixes (commit 9ceaf89), but I don't have write access to update the PR description on strands-agents/tools. Please replace the PR description with the updated version below.

The old description claimed features that don't exist (Executor class, security controls, Windows limitation). The new description accurately reflects the implementation.

📋 Updated PR description (click to expand, then copy)

## Description

Adds `programmatic_tool_caller` tool that enables code-based tool invocation. Agents can write Python code that calls other tools as async functions, reducing API round-trips and enabling complex orchestration patterns like loops, parallel execution, and chaining.

### Key Features

- **Async-first design**: Tools exposed as `await tool_name(...)` — code runs in async context automatically
- **Only `print()` output returned**: Tool results stay in code execution context, don't enter agent's context window unless explicitly printed
- **User confirmation**: Code preview shown before execution, with opt-out via `BYPASS_TOOL_CONSENT=true`
- **Configurable allowed tools**: Filter which tools are exposed via `PROGRAMMATIC_TOOL_CALLER_ALLOWED_TOOLS`
- **Namespace clash detection**: Raises `ValueError` if a tool name conflicts with reserved namespace entries (`asyncio`, `__name__`) or extra modules
- **BaseException safety**: `SystemExit` and `KeyboardInterrupt` in user code are caught and returned as error results (not propagated to host)

### Limitations

- Tools that use interrupts (human-in-the-loop) are not supported in this context
- `exec()` with user code — inherently requires trust in the code being executed
- No execution timeout — long-running code will block until completion
- `asyncio.run()` creates a new event loop — may conflict with environments that already have a running loop (e.g., Jupyter)

### Testing

- 31 unit tests (up from 23)
- 6 integration tests