docs(subagents): define bounded role disclosure and schema stability

[627150795]

Problem

The subagent_spawn surface must describe role choice, lifecycle, tool restrictions, and provider-facing request shape without making the parent schema grow with every role detail or child instance. The boundary between role disclosure, execution enforcement, and prompt-cache evidence is not yet captured in one design document.

Value

This documents bounded role selection, stable capability loading, trust-gated Agent Types, model/effort precedence, schema evolution, cache invalidation limits, and the difference between observable receipts and inference.

Approach

Added a focused design contract and linked it from the design index. It preserves the current fail-closed child allowlist/denylist and Pi-native lifecycle, while recording Codex, Maka, Oh My Pi, and OpenPI comparison lessons. Runtime implementation remains with the existing implementation issue.

Validation

• git diff --cached --check
• bun run lint
• bun run typecheck

Impact

Documentation-only; no tool schema, prompt, capability, provider, cache, or runtime behavior changes.

Fixes #84

[tt-a1i]

Thank you for preserving this research. We are closing this PR as a source record for the Capability, authority, and resources consolidation tracked in #277. This is not a finding that the content is wrong. The current queue contains overlapping contracts from one stale base, so we will extract only settled boundaries into at most one successor record, citing this PR explicitly. Please do not spend time rebasing this branch.