Merge remote-tracking branch 'origin/master' into worktree/provider-routed-llm-adapters

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/events.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/core.md
#	docs/event-producer-consumer.md
#	docs/persistence-catalog.md
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
#	examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
#	examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl
#	examples/acp-agent/tests/snapshots/skill-load/session.jsonl
#	examples/acp-agent/tests/snapshots/text-turn/session.jsonl
#	examples/sandbox-acp-agent/cordis.yml
#	examples/sandbox-acp-agent/tests/snapshots/escalation-approved/session.jsonl
#	examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/session.jsonl
#	examples/sandbox-acp-agent/tests/snapshots/mode-switching/session.jsonl
#	packages/compact/compact-basic/README.md
#	packages/compact/compact-basic/src/index.ts
#	packages/compact/compact-basic/tests/compact-basic.spec.ts
#	packages/core/agent-loop/README.md
#	packages/core/agent-loop/src/loop.ts
#	packages/core/agent-loop/tests/properties.spec.ts
#	packages/core/session/README.md
#	packages/core/session/src/types.ts
#	packages/core/session/tests/derived-cache.spec.ts
#	packages/llm/llm-deepseek/src/index.ts
#	packages/llm/llm-pi-ai/README.md
#	packages/llm/llm-pi-ai/src/adapter.ts
#	packages/llm/llm-pi-ai/src/convert.ts
#	packages/llm/llm-pi-ai/tests/adapter.spec.ts
#	packages/llm/llm/README.md
#	packages/llm/llm/src/call-config.ts
#	packages/llm/llm/src/index.ts
#	packages/ui/acp-agent/src/index.ts
#	packages/ui/acp/tests/harness.ts
#	packages/ui/jsonrpc/README.md
#	packages/ui/jsonrpc/src/server.ts
#	packages/ui/stdio-agent/README.md
#	packages/ui/stdio-agent/src/index.ts
#	python/sdk/README.i18n.yaml

packages/subagent/subagent-inprocess/README.md

@@ -39,3 +39,40 @@ After fulfillment, the caller owns the run. Provider-plugin unload does not revo
 - A monotonic tool guard blocks later calls after capture, and `agent/turn-stop` ends the turn after the structured result commits.
 
 A clean turn that never commits the required structured value reports `error`; the driver does not re-prompt. All registrations ride the child fiber and disappear with it.
+
+## Model Experience
+
+### Child-agent request
+
+**What the model sees**: 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.
+
+**Token effect**: 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 system prompt, schema, and results
+
+**What the model sees**: A structured run adds the structured-output instruction below. It also adds a child-scoped `structured_output` definition with exact description `Report your final structured result. Call this exactly once, when your answer is complete; the arguments must match this tool's parameter schema exactly.` and the requested schema. This runtime-only definition is outside the generated shipped [tool package map](../../../docs/tool-catalog.md#tool-package-map). Success returns `Structured output recorded.`; a later call becomes ``Error: structured output already recorded: the run is complete, so `<tool>` is not executed``.
+
+**Token effect**: 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.
+
+#### Structured-output instruction
+
+```markdown
+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.
+```
+
+### Parent start error, indirectly
+
+**What the model sees**: 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.
+
+**Token effect**: Zero tokens on a successful start; only the failed parent tool call retains this text.
+
+### Parent result, indirectly
+
+**What the model sees**: 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.
+
+**Token effect**: The parent receives one data-dependent result through the consumer; all other child tokens stay in the child session.
+
+## Known Limitations and Deferred Work
+
+- **Runs expose no `sendMessage`/`resume`** — the optional runtime capabilities are absent on in-process runs.
+- **Structured capture accepts the `defineTool` schema subset only** — unsupported JSON Schema constructs fail before the child is created; a provider needing a broader schema vocabulary requires a different runtime.

packages/subagent/subagent-inprocess/src/structured.ts

@@ -1,42 +1,12 @@
 /**
- * Structured-output support for the in-process subagent backends: the
- * mechanism behind `SubagentStartRequest.outputSchema` for children that run
- * as agents on the same context.
- *
- * Everything is a SCOPED registration on the child agent's context
- * (`child.ctx`, the dsh-scope seam): the `structured_output` capture tool
- * carries the run's REAL schema as its registered parameters (each child sees
- * exactly its own schema — two concurrent structured runs never interact), the
- * demand instruction is an ordinary order-190 scoped section, and the
- * enforcement listeners fire only for this child (scope-filtered dispatch).
- * Registration lifetime rides the child's fiber, so a backend hot-reload
- * mid-run cannot unregister the capture tool out from under a live child, and
- * a disposed child leaves no residue — no placeholder schema,
- * strip-for-everyone-else pass, or refcounted global runtime.
- *
- * The child scope's registrations enforce the contract:
- *
- * - The scoped capture tool and instruction are ordinary assembly inputs. The
- *   loop logs the assembled request header, so the demand is reconstructable
- *   log state rather than a wire-only mutation. As with every other assembly
- *   contribution, an expert `system-prompt/assemble` listener that deliberately
- *   removes or replaces either input owns the resulting composition.
- * - `agent/turn-stop` (serial, scoped): stop the child's turn once its output
- *   is captured. This terminal checkpoint runs after the ordinary continuation
- *   waterfall and steering folding, so listener order cannot resurrect a
- *   completed structured run or carry terminal steering into another turn.
- * - `tools.guard()` is the monotonic terminal gate after the extensible
- *   pre-execute waterfall: once capture commits, no later listener can turn
- *   the denial back into a dispatched side effect.
- * - `tools/result` is the capture COMMIT point. The tool body only STAGES the
- *   validated value in a WeakMap keyed by the execution object; the awaited,
- *   non-transforming notification promotes it only when the authoritative
- *   result after the whole pre/execute/post pipeline succeeds. For a Code Mode
- *   sub-dispatch, promotion waits again for the enclosing `run_code` result, so
- *   a runtime failure or outer post-policy block cannot report structured
- *   success. Execution identity makes call-id reuse and orphaned stages
- *   irrelevant.
+ * Child-scoped structured-output tool, prompt instruction, terminal guard, and authoritative
+ * result capture for in-process subagents. Each child registers its real schema on its own
+ * scope, so concurrent runs do not interact and disposal leaves no global residue. The prompt
+ * contribution is ordinary reconstructed request state.
  *
+ * Capture commits only after the authoritative `tools/result` succeeds; Code Mode capture also
+ * waits for the enclosing `run_code` result. The terminal turn-stop and monotonic tool guard
+ * then prevent later listeners or calls from reopening a completed structured run.
  * @module @deepseek-ai/dsh-subagent-inprocess/structured
  */
 
@@ -70,11 +40,8 @@ export interface StructuredAttachment {
 }
 
 /**
- * Attach the structured-output runtime to a child for `schema`: register the
- * scoped capture tool (real schema), the scoped instruction section, and the
- * scoped enforcement registrations (see the module doc). Call from the
- * agent-creation `setup` window with the child's scope context — every
- * registration rides the child's fiber and unwinds with the child.
+ * Attach the scoped capture tool, instruction, and enforcement to a child during
+ * its creation window. Child disposal removes every registration.
  * @param childCtx - the child agent's scope context (`setup`'s argument).
  * @param schema - the trusted, already-asserted schema subset to enforce (see
  *   `assertSupportedOutputSchema` in dsh-tools).

packages/subagent/subagent-inprocess/tests/structured.spec.ts

@@ -36,12 +36,9 @@ const SCHEMA: StructuredOutputSchema = {
 }
 
 /**
- * Real loop + scripted mock model + an INLINE fresh-conversation provider over the
- * shared driver. The concrete backend plugins are deliberately NOT loaded —
- * they would devDep-cycle this package (spawn/fork already depend on the
- * driver), and the runtime under test is the driver's; plugin-level structured
- * coverage lives in the spawn/fork specs. The mock model script drives the
- * child's structured_output calls.
+ * Real loop, scripted model, and inline fresh-conversation provider over the shared driver. Loading
+ * spawn/fork here would create a dev-dependency cycle; their specs cover plugin integration while
+ * this fixture isolates driver behavior and scripts the child's `structured_output` calls.
  */
 async function setup(script: Script, options: SetupOptions = {}) {
   const ctx = new Context()
@@ -216,11 +213,9 @@ describe('in-process structured output', () => {
     ])
     ctx.on('agent/turn-continuation', () => Promise.resolve<ContinuationDecision>({ action: 'stop' }))
     let wrapperInstalled = false
-    // Register before the ready-only start. The child session-start boundary is
-    // after unpublished setup attached structured output but before the loop
-    // can run. The wrapper awaits the
-    // explicit downstream stop above, then overwrites that result with continue.
-    // The later terminal checkpoint still wins.
+    // Register before ready-only start: structured output is attached before session-start and the
+    // loop. The wrapper waits for a downstream stop, rewrites it to continue, and must still lose
+    // to the later terminal checkpoint.
     ctx.on('agent/session-start', (child) => {
       if (child === parent) return
       wrapperInstalled = true
@@ -244,10 +239,8 @@ describe('in-process structured output', () => {
       toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 9 }),
       textResponse('MUST NOT BE CONSUMED'),
     ])
-    // The downstream ordinary policy says stop. A wrapper registered after
-    // start() delegates to that stop, then queues steering; ordinary folding
-    // would turn the stop back into continue. The terminal checkpoint runs
-    // afterwards and discards that steering.
+    // A downstream policy stops, then a later wrapper delegates and queues steering that ordinary
+    // folding would turn into continue. The terminal checkpoint must discard that steering.
     ctx.on('agent/turn-continuation', () => Promise.resolve<ContinuationDecision>({ action: 'stop' }))
     const run = await ctx.subagents.start('spawn', structuredRequest(parent))
     ctx.on('agent/session-start', (child) => {