[FEATURE] Cacheable static prefix for Agent-tool prompts (cross-spawn cache hits for orchestrated sub-agent workflows)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

I'm building a multi-step orchestrator workflow on top of the Agent tool — Phase B of a structured /execute-tracks workflow that spawns one "implementer" sub-agent per step in a track (typically 5–7 sequential spawns per session, all within a ~30–60 minute window). Each spawn receives:

• ~4 KB stable prefix (role description, rulebook path, project paths) — byte-identical across every spawn in the session.
• ~200 B per-step variable tail (step index, description, risk tag, mode, mode-conditional inputs).

Today every spawn pays full cache-creation cost on the prefix even though it was identical to the previous spawn 2–10 minutes earlier. The mitmproxy capture in #44724 confirms why: subagent calls carry cache_control: ephemeral only on system blocks (Claude Code's identity + tool definitions), not on the user-message body that carries the orchestrator's prompt: argument. The Agent tool's prompt parameter is also just a string with no breakpoint surface — so even if the prefix is byte-identical, there's no way for the caller to mark it cacheable.

This is structurally distinct from the existing tickets:

• #44724 — Agent → SendMessage(same agent) resume cache miss (within one subagent's lifecycle).
• #46421 — parallel-dispatch cache_read multiplication.
• #54568 (closed) — independent TTL for subagent vs main session.

None of those address cross-Agent-spawn user-content cache reuse, which is the hot loop for any orchestrator pattern.

Proposed Solution

Two compatible options:

Option A — caller-supplied breakpoint. Accept a structured form in the prompt parameter, or add a prompt_prefix: string companion parameter that the harness automatically wraps with cache_control: ephemeral:

Agent({
  subagent_type: "general-purpose",
  prompt_prefix: STATIC_PREFIX,   // wrapped with cache_control by harness
  prompt: variableInputs,
  ...
})

Option B — auto-detect. When the same subagent_type is spawned multiple times in a session within the cache TTL, attach cache_control: ephemeral to the longest common prefix of the user-message content. Transparent to callers; saves tokens for any pattern that repeats content.

Option A is more precise (caller knows the boundary). Option B helps existing users with no code change. Not mutually exclusive.

Alternative Solutions

• Move static content into a sub-agent definition file — doesn't fit; the prefix is workflow/session-specific, not a stable sub-agent type.
• Direct Anthropic SDK outside the Agent tool — loses session integration, harness state, sub-agent ecosystem. Disproportionate change.
• cnighswonger/claude-code-cache-fix interceptor — fixes adjacent cache-busting bugs (e.g., the identity-string swap from #44724) but can't add cross-spawn user-content caching, since the underlying API call has no breakpoint there.

Priority

High - Significant impact on productivity

Feature Category

API and model interactions

Use Case Example

Phase B of a 5-step track:

1. Orchestrator spawns implementer-1 with 4 KB prefix + 200 B variable → cache_create=4200.
2. Step runs ~5–10 min. Orchestrator spawns implementer-2 with the same 4 KB prefix + different 200 B variable → today: cache_create=4200 again (prefix re-billed).
3. Repeat for steps 3–5.

Over the session: 5 × 4 KB ≈ 20 KB of redundant cache_creation, billed at the create rate (~10× the read rate). With this feature: spawn-1 creates, spawns 2–5 read — ~10× cheaper on the prefix portion across the session, no behavior change.

Additional Context

The workflow architecture this request comes out of lives at https://github.com/JetBrains/youtrackdb/tree/develop/.claude/workflow — step-implementation.md is the orchestrator entry point for Phase B (per-step implementation), workflow.md is the session-level driver. The orchestrator/implementer split that produces the static-prefix pattern described above is in development on a branch that isn't yet on develop; on the linked branch the static prefix is justified for predictability/transcript readability with an explicit "do not rely on caching as a load-bearing optimisation" caveat — that caveat is what this feature would let us drop.

If Agent-tool spawns ever participate in cross-spawn caching, this and similar workflows benefit automatically without code changes.