[Issacboy123]

Summary

This PR explains how child-to-parent escalation reports work and when children should use them. It covers report limits, delivery while the parent is active or idle, behavior while the parent waits for children, and availability after a saved child is woken. It also clarifies that reports are hidden but still untrusted session data and records the feature in the coding-agent changelog.

This PR is stacked on fix/complete-subagent-coordination, which completes escalation-aware coordinated waiting.

Reasoning

The usage guide is the natural home for operational behavior, while the sessions and SDK guides clarify persistence and construction boundaries where users already encounter subagents. Describing acknowledgement, hidden delivery, and storage separately avoids implying model consumption, crash durability, secrecy, or redaction beyond the implemented guarantees.

Changes

• Documented the child-only tool, material-report guidance, 1,000-character per-message limit, multiple-report support, and 8,000-character pending aggregate limit.
• Documented FIFO active delivery, coalescing boundaries, non-interruption of sampling, and coordinated-wait resumption with exactly-once terminal results.
• Documented non-triggering idle behavior for saved and in-memory sessions and restored or replacement availability after explicit wake.
• Clarified that reports are untrusted, successful acknowledgement is not consumption, and hidden root messages and child tool arguments remain normal session data.
• Reserved escalate_to_parent in the SDK documentation and added an Unreleased coding-agent changelog entry.

Testing

• node ../../node_modules/vitest/dist/cli.js --run test/suite/subagent-parent-messaging.test.ts test/suite/subagent-services.test.ts test/suite/subagent-registration.test.ts test/suite/subagent-actions.test.ts test/suite/subagent-coordination.test.ts test/suite/subagent-persistence.test.ts test/suite/agent-session-queue.test.ts test/subagent-controller.test.ts
• npm.cmd run check
• git diff --check