docs: apply verbatim model experience guidance repo-wide

packages/subagent/subagent-acp/README.md

@@ -61,8 +61,8 @@ Keyless tests drive a scripted ACP subprocess over real stdio. The with-key e2e
 
 | Context surface | What the model sees | Token effect |
 |---|---|---|
-| Child-agent request | The remote child receives the standalone task through ACP plus its own process's configured system prompt, tools, and fresh session. It receives no parent conversation. This provider advertises no optional start-time capabilities, so the local service rejects requests for persona, tool filtering, depth enforcement, or structured output instead of silently omitting them. | The child pays for an independent full context and its own multi-step history. These tokens never enter the parent's context. |
-| Parent tool result, indirectly | Through `dsh-tool-subagent`, the parent receives only the child's final streamed assistant text or a stop-reason error, not intermediate messages or tool traffic. | Parent input grows only by the final result, which is data-dependent and retained until compaction. This provider adds no parent schema itself. |
+| Child-agent request | The remote child receives the standalone task content through ACP plus its own process's configured system prompt, tools, and fresh session. It receives no parent conversation. This provider advertises no optional start-time capabilities, so the local service rejects requests for persona, tool filtering, depth enforcement, or structured output instead of silently omitting them. | The child pays for an independent full context and its own multi-step history. These tokens never enter the parent's context. |
+| Parent tool result, indirectly | Through `dsh-tool-subagent`, the parent receives only the child's final streamed assistant text or that consumer's exact stop-reason error, not intermediate messages or tool traffic. A request already cancelled before publication becomes exactly `Error: subagent request was aborted before the ACP child started`; other start failures pass through as `Error: <message>`. | Parent input grows only by the final result or error, which is data-dependent and retained until compaction. This provider adds no parent schema itself. |
 
 ## Known Limitations and Deferred Work
 

packages/subagent/subagent-fork/README.md

@@ -27,7 +27,7 @@ See [`dsh-subagent-spawn`](../subagent-spawn/README.md) for the run lifecycle, m
 
 | Context surface | What the model sees | Token effect |
 |---|---|---|
-| Child-agent history and envelope | The child receives the parent's balanced completed-turn surface prefix, then the new task. A configured persona shadows prompt text in the child's fresh scope; a tool restriction filters its global wire schemas, executable lookup, and Code Mode SDK bindings but not standalone guidance. The parent's tool view and authority are not inherited. An optional structured-output request adds its child-only contract. The parent's current in-flight turn is excluded. | Forking duplicates retained completed history into separate child requests; the child then accumulates its own tokens independently. Persona changes repeated prompt cost, filtering changes schema or generated SDK cost, and a first-turn fork has no inherited history. |
+| Child-agent history and envelope | The child receives the parent's balanced completed-turn surface prefix, then the new task content verbatim. A configured persona shadows prompt text in the child's fresh scope; a tool restriction filters its global wire schemas, executable lookup, and Code Mode SDK bindings but not standalone guidance. The parent's tool view and authority are not inherited. An optional structured-output request adds its child-only contract. The parent's current in-flight turn is excluded. | Forking duplicates retained completed history into separate child requests; the child then accumulates its own tokens independently. Persona changes repeated prompt cost, filtering changes schema or generated SDK cost, and a first-turn fork has no inherited history. |
 | Parent tool result, indirectly | The parent receives only the child's own final output through `dsh-tool-subagent`, not the inherited prefix or intermediate work. | Parent input grows by one data-dependent final result retained until compaction. |
 
 ## Known Limitations and Deferred Work

packages/subagent/subagent-inprocess/README.md

@@ -44,9 +44,19 @@ A clean turn that never commits the required structured value reports `error`; t
 
 | Context surface | What the model sees | Token effect |
 |---|---|---|
-| Child-agent request | The shared driver sends the task as the child's user message and, when requested, shadows the persona and restricts global tool schemas, lookup, execution, and Code Mode SDK bindings in the unpublished child's fresh scope; parent restrictions are not inherited, and standalone tool-guidance sections remain. Structured runs add a scoped instruction plus `structured_output` in the visible schema or Code Mode SDK, then stop after a committed capture. Spawn supplies no history; fork supplies its balanced seed. | Child input is isolated from the parent and grows through the child's own steps. A persona changes repeated prompt text; filtering changes schema or generated SDK cost but not independently registered guidance. Structured output adds fixed instruction and capability tokens for that child. |
+| Child-agent request | The shared driver sends the task verbatim as the child's user message and, when requested, shadows the persona and restricts global tool schemas, lookup, execution, and Code Mode SDK bindings in the unpublished child's fresh scope; parent restrictions are not inherited, and standalone tool-guidance sections remain. Spawn supplies no history; fork supplies its balanced seed. | Child input is isolated from the parent and grows through the child's own steps. A persona changes repeated prompt text; filtering changes schema or generated SDK cost but not independently registered guidance. |
+| Structured child request and results | A structured run adds the exact [structured-output instruction](#structured-output-instruction). The tool description is exactly `Report your final structured result. Call this exactly once, when your answer is complete; the arguments must match this tool's parameter schema exactly.` with the requested schema. Success returns `Structured output recorded.`; a later call becomes ``Error: structured output already recorded: the run is complete, so `<tool>` is not executed``. | Fixed instruction and capability tokens are paid only by that child. Result text enters the child history, while the captured value alone becomes the parent result. |
+| Parent start error, indirectly | Through `dsh-tool-subagent`, invalid depth state becomes exactly `Error: agent subagentDepth must be a non-negative safe integer`, `Error: subagent child depth exceeds the safe-integer range`, or `Error: subagent depth <attempted> exceeds maxDepth <max>`. A pre-publication cancellation passes its abort reason through the registry's `Error: <message>` wrapper. | Zero tokens on a successful start; only the failed parent tool call retains this text. |
 | Parent result, indirectly | The driver extracts only the child's own last assistant output or captured structured value; seeded parent messages and intermediate child work do not become the result. | The parent receives one data-dependent result through the consumer; all other child tokens stay in the child session. |
 
+### Verbatim model-visible text
+
+#### Structured-output instruction
+
+```text
+When you have your final answer, you MUST report it by calling the `structured_output` tool with arguments matching its parameter schema exactly. Do not finish with a plain text answer: only the tool call counts as your result.
+```
+
 ## Known Limitations and Deferred Work
 
 - **Runs expose no `sendMessage`/`resume`** — the optional runtime capabilities are absent on in-process runs.

packages/subagent/subagent-spawn/README.md

@@ -22,7 +22,7 @@ Spawn advertises `{ outputSchema: true, depthLimit: true, toolFilter: true, pers
 
 | Context surface | What the model sees | Token effect |
 |---|---|---|
-| Child-agent request | The fresh child receives the standalone task, inherits the parent model and workspace by default, and sees the global prompt with any configured child-scoped persona shadow. A tool filter removes global wire schemas, executable lookup, and Code Mode SDK bindings for that child but leaves independently registered guidance. It receives zero parent conversation messages; the filter is visibility/composition, not an authority grant inherited from the parent. | The child pays for a new independent context and history; no parent-history tokens are duplicated. Persona changes this child's repeated prompt cost, while filtering changes its schema or generated SDK cost. |
+| Child-agent request | The fresh child receives the standalone task content verbatim, inherits the parent model and workspace by default, and sees the global prompt with any configured child-scoped persona shadow. A tool filter removes global wire schemas, executable lookup, and Code Mode SDK bindings for that child but leaves independently registered guidance. It receives zero parent conversation messages; the filter is visibility/composition, not an authority grant inherited from the parent. | The child pays for a new independent context and history; no parent-history tokens are duplicated. Persona changes this child's repeated prompt cost, while filtering changes its schema or generated SDK cost. |
 | Parent tool result, indirectly | Through `dsh-tool-subagent`, the parent receives only the child's final output or stop-reason error. | Parent input grows by one data-dependent result retained until compaction. |
 
 ## Known Limitations and Deferred Work

packages/subagent/subagent/README.md

@@ -62,7 +62,9 @@ The current model-facing tool collects synchronously: it awaits the child result
 
 ## Model Experience
 
-Indirectly, through `dsh-tool-subagent` and registered providers, which expose delegation schemas, child contexts, and retained parent results.
+| Context surface | What the model sees | Token effect |
+|---|---|---|
+| Delegation result, indirectly | Through `dsh-tool-subagent`, registered providers create child contexts and return data-dependent final output. A missing provider or unsupported requested capability becomes exactly `Error: no subagent provider registered for "<name>"` or `Error: subagent provider "<name>" does not support the "<capability>" capability`. Provider-specific start errors receive the same `Error: <message>` wrapper. | This seam adds no parent schema itself. The parent retains only the final output or start error; child working tokens remain in the child. |
 
 ## Known Limitations and Deferred Work
 

packages/subagent/tool-subagent/README.md

@@ -31,8 +31,35 @@ A non-`completed` stop reason becomes an `isError` tool result; partial child ou
 
 | Context surface | What the model sees | Token effect |
 |---|---|---|
-| Tool schema | While the configured provider exists, the parent model sees one `{ description, prompt }` tool under `toolName`. Its description explicitly says whether the child inherits completed turns or needs a standalone prompt; persona, model, filter, depth, and provider choice remain deployment config. For a capable in-process provider, the filter changes the child's global wire schemas, lookup, execution, and Code Mode SDK bindings, not standalone guidance or an inherited authority ceiling. | Fixed schema cost per parent request while mounted. Removing the provider removes the whole schema; exposing multiple providers adds one independently named schema per load. |
-| Tool-call history and result | The task description and full prompt remain in the parent assistant tool call. The result contains only the child's final text or a stop-reason error, never intermediate child steps. | Prompt and final output are data-dependent retained tokens. All child working context is paid in the child and omitted from the parent. |
+| Standalone-provider schema | While a fresh-context provider exists, the configured tool uses the exact [standalone tool](#standalone-provider-tool-description) and [`prompt` parameter](#standalone-provider-prompt-description) descriptions. | Fixed schema cost per parent request while mounted. Removing the provider removes the whole schema. |
+| Inherited-context-provider schema | A provider that seeds completed turns uses the exact [inherited-context tool](#inherited-context-provider-tool-description) and [`prompt` parameter](#inherited-context-provider-prompt-description) descriptions. Both variants describe `description` exactly as `A short (3-5 word) description of the delegated task, for display.` | Fixed schema cost per parent request while mounted. Exposing multiple providers adds one independently named schema per load. |
+| Tool-call history and result | The task description and full prompt remain in the parent assistant tool call. Success contains only the child's data-dependent final text. Other stop reasons become exactly `Error: subagent run was cancelled`, `Error: subagent run failed`, `Error: subagent run hit its token limit before finishing`, `Error: subagent declined the task`, or `Error: subagent run ended abnormally (<reason>)`; a call without an owning agent becomes `Error: subagent tool requires a calling agent (exec.agent was undefined)`. Intermediate child steps never enter the parent. | Prompt and final output are data-dependent retained tokens. All child working context is paid in the child and omitted from the parent. |
+
+### Verbatim model-visible text
+
+#### Standalone-provider tool description
+
+```text
+Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.
+```
+
+#### Standalone-provider prompt description
+
+```text
+The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs.
+```
+
+#### Inherited-context-provider tool description
+
+```text
+Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.
+```
+
+#### Inherited-context-provider prompt description
+
+```text
+The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new.
+```
 
 ## Known Limitations and Deferred Work