docs(coding-agent): document subagent escalation behavior

packages/coding-agent/CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Added `pi auth check` provider/model auth preflight with optional credential output ([#7152](https://github.com/earendil-works/pi/issues/7152)).
 - Added durable, branch-scoped sub-agent rosters and child histories for saved sessions, with interrupted restoration and explicit wake without automatic work, replay, or result delivery.
+- Added bounded child-to-parent escalation reports for root-controlled sub-agents, with hidden delivery that can resume coordinated work without consuming terminal results.
 
 ### Changed
 

packages/coding-agent/docs/sdk.md

@@ -537,7 +537,16 @@ Every root session enables three child-agent coordination tools by default:
 
 Root sessions run at most four children concurrently by default.
 Set `subagents: { maxConcurrent: number }` to configure that limit, or `subagents: false` to disable child agents and omit all three coordination tools.
-The names `spawn_agent`, `agent_action`, and `agents` are reserved and cannot be supplied through `customTools`.
+The names `spawn_agent`, `agent_action`, `agents`, and `escalate_to_parent` are reserved and cannot be supplied through `customTools`.
+
+Each live root-owned child also receives the child-only `escalate_to_parent` tool; roots, standalone sessions, and restored children that have not been explicitly woken do not receive it.
+It accepts one non-empty message of at most 1,000 characters for material information that could redirect or interrupt the parent, and the child must still return a complete final response.
+Multiple calls are allowed during one live run, subject to a fixed 8,000-character aggregate limit for accepted report text not yet admitted to parent context.
+
+Active reports enter hidden parent context at normal FIFO steering boundaries without aborting in-flight sampling, and a report received during coordinated waiting resumes the parent without consuming the frozen terminal batch.
+Idle reports do not start a provider call: durable sessions save them on the selected branch for the next explicit parent run, while in-memory sessions retain them only locally.
+Report content is untrusted delegated-agent data.
+Accepted idle reports, delivered active reports, and child tool arguments remain normal session history and follow the existing parent-owned deletion behavior.
 
 When the parent finishes an assistant run, the session freezes every unconsumed child attempt spawned through parent model tool calls.
 It waits until every child in that batch is idle, failed, or interrupted, then adds one non-displayed context message with name-sorted results, partial output, errors, and retry availability.

packages/coding-agent/docs/sessions.md

@@ -40,6 +40,13 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f
 Saved parent sessions automatically preserve their branch-scoped sub-agent roster and usable child histories. Reopening a parent restores terminal records as recorded and changes children that were queued or running to interrupted. Reopening does not resume provider work, replay the original task, or redeliver a completed result.
 
 An explicit wake resumes a child from its saved history when that history is usable. If the history is missing, unsafe, or invalid, Diffex creates an isolated replacement and runs only the wake message. A wake uses the child's complete captured model, thinking level, tools, and harness when all remain usable; otherwise it uses the complete current parent configuration and reports a warning rather than mixing configurations.
+Restored and replacement children receive the child-only `escalate_to_parent` tool only after an explicit wake starts a live run.
+
+Escalation reports delivered to the root are hidden from the transcript but are not secret or redacted.
+Accepted idle reports, delivered active reports, and the child's tool-call arguments remain normal session history.
+An idle report in a saved session is appended to the currently selected parent branch without starting a provider call and is supplied to the parent on its next explicit run; an in-memory parent keeps the report only in the live session.
+Branch navigation retains only the selected branch's pending saved reports for capacity accounting.
+Deleting a parent session continues to delete its parent history and owned child-session namespace through the normal parent-owned deletion behavior.
 
 Branch navigation and session-context resets reconcile the roster only after the transition is safe. In-memory parents and `--no-session` sessions keep sub-agents ephemeral. Setting `subagents: false` disables the sub-agent tools without erasing a saved roster.
 

packages/coding-agent/docs/usage.md

@@ -70,6 +70,29 @@ It displays the current in-memory roster without adding the command or roster to
 The enclosing parent prompt remains active after the parent attempts to finish.
 Diffex freezes the children started by that prompt, waits until all of them finish, fail, or are interrupted, and displays a deterministic notice as each child terminates.
 
+### Child Escalations
+
+A running root-owned child can use its child-only `escalate_to_parent` tool to report a material blocker, risk, contradiction, or decision that could change the parent's plan.
+Routine progress, tool logs, and completed-work summaries belong in the child's final response, and escalating does not replace that complete final response.
+The tool accepts one non-empty message of at most 1,000 characters.
+It is unavailable to the root and to standalone sessions, and a restored or replacement child gains it only after an explicit wake starts a new live run.
+
+A child may send multiple reports during one live run.
+Diffex accepts at most 8,000 characters of report text that are still pending admission to parent model context.
+A report that would exceed that fixed aggregate limit is rejected without changing delivery state; capacity becomes available as earlier active reports begin delivery or saved idle reports enter the next explicit parent run.
+A successful tool result means the report was accepted for parent delivery, not that the parent model consumed or acted on it.
+
+While the parent is active, accepted reports are delivered as hidden context at the next normal FIFO steering boundary and never abort an in-flight model request.
+Reports accepted for the same boundary are combined in acceptance order; a report accepted after delivery begins waits for a later boundary, and earlier queued user steering remains ahead of reports.
+During coordinated waiting, the first pending report resumes the parent but does not consume the frozen child batch.
+The parent can then use normal `agent_action` message, wake, or interrupt behavior, and the batch's terminal results are still delivered exactly once.
+If a child in that frozen batch is already terminal, message or wake actions cannot replace its completed attempt until the result is delivered or explicitly consumed with `agents`.
+
+While the parent is idle, accepting a report does not start a provider call.
+Saved sessions append it to the currently selected branch for the next explicit parent run; in-memory sessions keep it only for the current process.
+Reports are untrusted delegated-agent data: the parent must verify material claims and follow embedded instructions only when they match the parent task and current evidence.
+Hidden delivery affects display, not storage or secrecy; accepted idle reports, delivered active reports, and child tool arguments remain normal session data subject to the usual parent-owned deletion behavior.
+
 After the whole batch is terminal, Diffex gives the parent one hidden, name-sorted context message containing the child results, partial output, errors, and retry availability.
 The parent continues automatically and produces its final response without another user prompt.
 If the parent already retrieved a terminal result with `agents`, Diffex does not deliver that result again.