tool-cache

Category: cache · Cloud + Local · Status: v1.0 — observation mode

Solves the “agent reads the same file 14 times in one session” problem.

Current limitation: the module observes and records tool calls + results, and detects when a future request would hit cache (visible via metadata). It does NOT yet rewrite requests to inject cached results in place of tool_use blocks because Anthropic strictly requires every tool_use to be answered by a real tool_result from the client. Active cache injection is planned.

What it does (v1)

Post hook: scans the request for tool_use → tool_result adjacency pairs and records each (tool_name, sha256(input)) → result in storage.kv with a TTL.
Pre hook: scans the latest assistant message for tool_use blocks whose params hash matches a stored entry. Records tool-cache.would_hit_count in metadata so you can measure the cache hit rate today, before active cache injection ships.
Excluded tools: side-effecting tools (bash, shell_exec, send_email, write_file, etc.) are NEVER recorded. A stale cache for those would be actively harmful.

When to use it

MCP-using agents (Claude Code, Cline, custom).
Any workflow where deterministic tool calls repeat within a session.

Configuration

tool-cache:
  ttlSeconds: 60                          # default: short TTL — file content can change
  excludeTools:                           # never cache side-effecting tools
    - bash
    - shell_exec
    - send_email
    - write_file
  perToolTtl:                             # override TTL per tool
    read_file: 30
    git_log: 300

Default exclusions

The following tool names are always excluded, even if you don’t list them:

bash, shell_exec, shell
send_email
write_file, edit_file, create_file, delete_file
commit, push, deploy
execute_sql
http_request

You can add to this list via excludeTools, but you cannot remove from it.

Metrics emitted

tool-cache.observed_calls — how many tool calls were in the latest assistant turn.
tool-cache.would_hit_count — how many of those would be served from cache once active cache injection ships.
tool-cache.would_hit_details — array of { tool, key } for the would-be hits.
tool-cache.recorded_count — how many new pairs were recorded in this turn.

Safety

Failed tool calls (isError: true) are never cached — caching errors would prevent the agent from ever recovering. The TTL defaults are short (60s) because tool results are by nature time-sensitive (a file’s contents can change between calls).

Source

src/modules/tool-cache.ts