Shared-Memory Tool-Call Cache

Background

Parallel agents running in lock-step often hit the same tool with the same args. Without coordination they both pay the latency and cost. A shared in-memory cache keyed by (tool_name, args) deduplicates the calls cleanly — a single underlying tool invocation, two agents satisfied. This is the canonical observation from the "parallel executors" lesson.

Problem statement

Implement SharedToolCache as a class:

• __init__() — creates an empty cache and calls_saved = 0.
• call(tool_name, args, tool_fn) — if (tool_name, args) was called before, return the cached result and increment calls_saved. Otherwise call tool_fn(**args), cache the result, and return it.

Input

• tool_name — str, the tool identifier.
• args — dict of keyword args passed to tool_fn.
• tool_fn — a callable accepting **args.

Output

• call(...) returns whatever tool_fn(**args) returns (or the cached prior result).
• calls_saved attribute exposes the count of cache hits.

Examples

Example 1 — cache hit dedupes the second call

n_calls = [0]
def tool(x): n_calls[0] += 1; return x * 2

c = SharedToolCache()
c.call("double", {"x": 3}, tool)   # -> 6, tool fired
c.call("double", {"x": 3}, tool)   # -> 6, cached
# n_calls[0] == 1; c.calls_saved == 1

Example 2 — different args -> no dedup

c = SharedToolCache()
c.call("inc", {"x": 1}, lambda x: x+1)
c.call("inc", {"x": 2}, lambda x: x+1)
# c.calls_saved == 0

Constraints

• Cache key must be (tool_name, frozenset(args.items())) so dict-ordering doesn't cause false misses.
• tool_fn is invoked with **args (keyword expansion).
• calls_saved starts at 0 and only increments on cache hits.

Notes

• Why frozenset. A regular dict isn't hashable. frozenset(args.items()) is order-independent and hashable as long as the values are hashable.
• Production caveats. A real shared cache adds TTL, size bounds, and per-tool override (e.g. don't cache now()).