`--add-dir` causes Claude sub-agent dispatch to fail: 400 "A maximum of 4 blocks with cache_control ... Found 5"

[spqian]

Bug: --add-dir causes Claude subagent dispatch to fail with 400 A maximum of 4 blocks with cache_control ... Found 5

Summary

When Copilot CLI is launched with one or more --add-dir <directory> flags, every sub-agent
dispatch that runs on an Anthropic (Claude) model fails instantly with:

CAPIError: 400 A maximum of 4 blocks with cache_control may be provided. Found 5.

The sub-agent returns an empty response ("Agent completed but produced no response"), so the
parent silently loses the sub-agent's work. Removing --add-dir fixes it. GPT sub-agents are
unaffected (OpenAI requests carry no cache_control). Root/top-level Claude requests are also
unaffected even with --add-dir — the defect is specific to the sub-agent request-builder path.

Environment

• GitHub Copilot CLI: 1.0.72-1
• OS: Windows 11 (10.0.26200)
• Failing model path: any Anthropic model as a sub-agent (claude-sonnet-5, claude-opus-4.8,
  claude-sonnet-4.6, etc.), via the task tool, any agent_type.
• Trigger flag: --add-dir <dir> (one is enough).
• Example failing Request IDs: AF1E:308403:2FF3CC5:3C2DA35:6A5D4183,
  8280:355A15:2F0158E:393D205:6A5D0AA8.

Impact

• Severity: High for any workflow that (a) launches the CLI with --add-dir and (b) dispatches
  Claude sub-agents. This includes bootstrappers/wrappers that add the repo root as an
  allowed directory when the launch cwd is a nested subfolder, and any orchestration that fans out
  work to Claude sub-agents.
• Failure is silent to the model: the sub-agent produces no output and the parent proceeds as if
  it got an empty result, corrupting multi-agent pipelines.

Minimal, deterministic repro (no wrapper, no special repo)

# FAILS — 400 A maximum of 4 blocks with cache_control ... Found 5
copilot -p "Use the task tool exactly once to run a general-purpose sub-agent on model claude-sonnet-5 whose entire prompt is: reply with exactly PROBE-OK. Then print the sub-agent's response, or SUBAGENT-EMPTY if it returned nothing." \
  --add-dir <any-directory-other-than-cwd> --allow-all-tools -s

# PASSES — identical, but no --add-dir
copilot -p "<same prompt>" --allow-all-tools -s

Controlled results (only --add-dir and root-vs-subagent varied)

Run	Condition	cache_control blocks	Result
A	Claude sub-agent, no --add-dir	4	PASS PROBE-OK
B	Claude sub-agent, with --add-dir	5	FAIL Found 5
C	Claude root (no sub-agent), --add-dir	4	PASS ROOT-OK

--add-dir is the only difference between A (pass) and B (fail).

Actual vs. expected

• Actual: --add-dir causes the sub-agent request to carry 5 cache_control breakpoints;
  Anthropic hard-caps at 4, so the request is rejected 400 and the sub-agent yields nothing.
• Expected: the request builder should never emit more than 4 cache_control breakpoints for
  Anthropic, regardless of --add-dir. --add-dir should not add a cache breakpoint.

Root-cause analysis

A Fiddler capture of the failing sub-agent request shows exactly 5 cache_control: {type: ephemeral} markers:

#	Section	Block	Origin
1	system	Base CLI system prompt (ends </environment_limitations>)	base
2	system	Main <environment_context> + instructions + /tmp security rule	base
3	system	2nd <environment_context>: "Additional directories available for file access: <dir>"	--add-dir
4	messages	Last user message	base (subagent)
5	tools	End of tools array	base

Anthropic counts cache_control breakpoints across system + messages + tools toward the max of 4.

• The base sub-agent request already uses 4 (Create ownership.yaml #1, Update ownership.yaml #2, Updating exec sponsor per request from the TPM org #4, #5).
• --add-dir emits the additional-directory context as a separate, separately-cached system
  text block (ownership.yaml: Surface inactive data for replacement #3) — the whole request is now serving two <environment_context> blocks, the second
  existing only to list the extra allowed directory. That pushes the total to 5 → 400.
• Root Claude requests carry one fewer breakpoint than the sub-agent path (the sub-agent path
  caches the trailing user turn, Updating exec sponsor per request from the TPM org #4). So root stays at 4 even with --add-dir (Run C passes), while
  the sub-agent path tips to 5 (Run B fails). This is why the failure is sub-agent-specific.

Key confirming facts:

• The request contains two <environment_context> blocks; "Additional directories available for
  file access" appears only in block ownership.yaml: Surface inactive data for replacement #3, and only when --add-dir is passed.
• A CLI session launched without --add-dir has a single <environment_context> (cwd + git
  root, no "Additional directories") and stays at 4 breakpoints → sub-agents pass.

Suggested fix

On the Anthropic sub-agent request-building path, guarantee ≤4 cache_control breakpoints. Any of:

1. Fold the additional-directory info into the main <environment_context> block (Update ownership.yaml #2) instead of
   emitting a second, separately-cached block — the natural fix, since --add-dir is just more
   environment context.
2. Do not attach cache_control to the additional-directory block (leave it uncached).
3. Generally: cap/coalesce cache_control markers at 4 for Anthropic before send (e.g. drop the
   ephemeral marker on the smallest/least-valuable block — the tiny trailing user message or the
   add-dir block — when the count would exceed 4).

Option 1 or a general cap (option 3) is preferable so future additions (more --add-dir entries,
extra system blocks) can't regress past 4.

Workarounds (until fixed)

1. Launch from a directory that already covers everything you need, so no --add-dir is required
   (e.g. launch at the repo root instead of a nested subfolder).
2. Route sub-agents to GPT models (no cache_control, immune).
3. Drop --add-dir and rely on cwd + explicit path approvals.