Workflow Resume Cache Breaks Silently on Script Structure Changes

GitHub Issue: Workflow Resume Cache Breaks Silently on Script Structure Changes

Repository: anthropics/claude-code

---

Bug/Feature Request

Workflow caching for resumeFromRunId breaks silently when script structure changes, even when agent prompts are identical. There is no warning, validation, or documentation about what changes invalidate the cache.

---

Environment

• Claude Code version: Latest (2026-10-07)
• Model: claude-opus-4-5-20251101
• OS: Linux (Debian)

---

What Happened

1. Launched a large workflow (660 agents, 10 products)
2. Hit API rate limits mid-execution
3. 126 agents completed successfully, ~530 failed
4. Attempted to resume with resumeFromRunId after editing script to run sequentially
5. Changed control flow from pipeline(PRODUCTS, stage1, stage2, ...) to for (const product of PRODUCTS) { ... }
6. Agent prompts were character-for-character identical
7. Cache did not apply — all agents re-ran from scratch
8. Lost ~25-30M tokens

---

Expected Behavior

1. Cache should match on (prompt, opts) as documented, not on script structure
2. OR: Clear documentation that structural changes break cache
3. OR: Validation on resume that reports "X agents will replay from cache, Y will re-run"
4. OR: Warning when cache match rate is 0%

---

Actual Behavior

• Cache silently failed to match
• No warning or validation
• Tokens consumed with no indication that cache wasn't being used
• Claude (the assistant) was also unaware of this limitation and provided incorrect guidance

---

Reproduction Steps

// Original script - run this, let some agents complete, then stop
const results = await pipeline(
  ITEMS,
  async (item) => {
    return await agent(`Process ${item.name}`, { label: item.name, schema: SCHEMA })
  }
)

// Modified script - resume with same runId
// Prompts are IDENTICAL but structure changed
const results = []
for (const item of ITEMS) {
  const r = await agent(`Process ${item.name}`, { label: item.name, schema: SCHEMA })
  results.push(r)
}

Resume with resumeFromRunId pointing to original run. Observe that agents re-run instead of replaying from cache.

---

Suggested Fixes

1. Documentation (minimum)

Document clearly in the Workflow tool description:

• Exactly what determines cache key matching
• What changes will break cache (structural changes, reordering, etc.)
• Best practices for modifying scripts while preserving cache

2. Cache Validation (recommended)

On resumeFromRunId, before executing:

Resuming workflow wf_abc123
Cache status: 126/660 agents will replay from cache
WARNING: 534 agents have no cache match and will re-run
Proceed? [y/N]

3. Graceful TaskStop (recommended)

Add options to TaskStop:

• --finish-running: Let in-flight agents complete, don't start new ones
• --force: Current behavior (immediate kill)

4. Structural-Agnostic Cache (ideal)

Match cache purely on (prompt, opts) hash, independent of script structure. The script is just orchestration — if the agent call is identical, it should cache.

---

Impact

• Tokens lost: ~25-30M
• Time lost: ~4 hours of workflow execution + debugging
• User trust: Claude provided confident but incorrect guidance about caching

---

Related

• Support request submitted to support@anthropic.com for token credit
• Session ID: 2d714ec7-4a1a-4393-bd40-a7b60087dff7
• Run ID: wf_2b027677-569

---

Labels

bug, documentation, workflow, ux