Skip to content
Flows
Library Paths Vault Generate Progress Run Demo Flow
Agent Architecture Advanced · 60-120 minutes

Make Parallel Sub-Agents Share the Prompt Cache

Byte-identical request prefixes are why forked workers cost a fraction of spawned ones - engineer your dispatch so every parallel child hits the same cache entry.

Start Route · 4 steps

The route

4 steps to Done

  1. 01

    Map what must be byte-identical

    The cache matches prefixes; know exactly what is in yours.

    Preview prompt + verify gate ▾

    Write out the full request structure your provider sees, in order: system prompt, tool definitions, conversation messages, and (last) the new content. Everything before the first differing byte is cacheable prefix - so the design goal is pushing all per-child variation to the very end. Inventory your current dispatch path for prefix pollution: timestamps or run ids in the system prompt, tool arrays rebuilt per child (set iteration order!), serialization that does not guarantee key order, permission-dependent tool filtering that differs per child, and configuration fields (thinking settings, verbosity) that default differently for children than the parent. Each finding is a work item for the next step. Also confirm your provider's cache granularity and minimum-prefix rules so you aim at real boundaries.

    • ✓ Request field order documented
    • ✓ All per-child variations found and listed
    • ✓ Provider cache rules confirmed
  2. 02

    Stabilize the shared prefix

    Reuse the parent's bytes; never regenerate what you can copy.

    Preview prompt + verify gate ▾

    Fix each pollution source. System prompt: pass the parent's already-rendered prompt bytes to children - do not re-render from templates (a template variable that resolves differently produces a different prefix). Tool definitions: pass the parent's exact tool array - skip per-child filtering entirely in fork mode (children inherit everything; enforcement happens at execution, not definition) and preserve order and serialization. Pending tool calls: when the parent's last assistant message has unresolved tool calls, insert placeholder results with one FIXED string shared by every fork ever dispatched - not per-child text, not indices, not timestamps. Configuration: inherit the parent's model settings (thinking config, session flags) rather than applying child defaults. The child's directive is appended strictly last.

    • ✓ System prompt bytes reused, not re-rendered
    • ✓ Tool array passed through untouched
    • ✓ One global placeholder string for all forks
  3. 03

    Measure cache performance

    Cache savings are a metric, not a vibe.

    Preview prompt + verify gate ▾

    Instrument dispatch with the provider's usage metrics: cached input tokens versus fresh input tokens per request. Run a controlled fan-out (one parent, four siblings, same moment) and check: sibling one may pay to warm the cache; siblings two through four should show the shared prefix as cached. Compute the batch's effective cost versus the no-cache baseline and log it per dispatch. Add a dashboard or log line per fan-out: sibling count, prefix tokens, cache-hit ratio, cost delta. If hits are low, return to the byte-diff from step 1 - the metrics tell you THAT you miss, the diff tells you WHERE. Also watch time-to-first-token: cache hits should visibly improve latency, a useful secondary signal when token metrics are murky.

    • ✓ Cached vs fresh tokens logged per request
    • ✓ Controlled fan-out shows siblings hitting cache
    • ✓ Cost delta vs baseline computed per batch
  4. 04

    Guard stability with regression tests

    One refactor away from silently paying full price forever.

    Preview prompt + verify gate ▾

    Encode prefix stability as tests. Unit level: dispatch two siblings from a fixture parent state and assert their serialized requests are identical up to the directive marker - run this in CI so any dispatch-path change that breaks byte identity fails the build. Property level: assert the placeholder constant is referenced from a single definition (no string duplication that can drift), tool arrays are passed by reference/untouched, and system prompts are copied not re-rendered. Operational level: alert when a fan-out's cache-hit ratio drops below a threshold - serialization library upgrades and provider API changes both break prefixes without any code change on your side. Document the invariant prominently in the dispatch module: all fork engineering serves byte-identical prefixes; do not 'improve' per-child content into the prefix.

    • ✓ Sibling byte-identity asserted in CI
    • ✓ Single-source placeholder constant enforced
    • ✓ Cache-ratio alert wired with a threshold

Research-backed

Sources behind this flow

Tier 1 · claude-code-internals

Deep Dive: Multi-Agent Dispatch - Spawn, Fork, Direct

Source-level analysis of the three ways Claude Code dispatches work: Spawn (a named sub-agent with a fresh context, its own tool pool, permission mode, and model), Fork (a synthetic agent that inherits the parent conversation byte-for-byte so parallel workers share the prompt cache), and Direct (the main agent just does the task itself). Covers sync-to-background promotion via a promise race, recursion guards on forking, git-worktree isolation, and a decision matrix for picking a strategy per task.