cache-friendly sub-agent prompt construction for prompt-cache reuse

[yai-dev]

Summary

Make sub-agent prompt construction cache-friendly so repeated orchestration turns get better prompt-cache reuse.

Current State

The current repo no longer matches the older package layout that originally framed this issue. The problem still exists conceptually, but implementation should target the current @agentrail/core, @agentrail/app, and @agentrail/capabilities architecture.

Problem

Sub-agents often share the same system prompt shape and tool inventory as the parent agent, but small differences in prompt assembly or tool serialization can break provider prompt-cache reuse.

Proposed Direction

1. Define what parts of the current agent-construction path must stay byte-stable for cache reuse
2. Reuse stable tool serialization when the effective toolset is unchanged
3. Preserve stable system prompt bytes when spawning related sub-agents in the same session
4. Document the cache-sensitive fields explicitly

Affected Areas

• packages/capabilities/src/orchestration/
• prompt / agent construction in packages/core and packages/app
• provider-specific cache-control handling in packages/core/src/llm/providers/

Acceptance Criteria

• Cache-sensitive prompt/tool prefix inputs are explicitly defined
• Equivalent parent/sub-agent toolsets can reuse stable serialization
• Equivalent prompt text is preserved byte-for-byte where intended
• Documentation explains what breaks cache reuse