Merge branch 'codex/simp-hide-concrete-agent-loop' into codex/simp-hide-subagent-internals

# Conflicts:
#	docs/rfc/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
#	packages/subagent/subagent-subprocess/src/index.ts
#	packages/subagent/tool-subagent/src/index.ts

packages/subagent/subagent-fork/src/index.ts

@@ -1,22 +1,9 @@
 /**
  * The in-process FORK subagent backend: registers a {@link SubagentProvider} on
- * `ctx.subagents` that runs each child as a child {@link Agent} SEEDED with a
- * prefix of the parent's session log — so the child inherits the parent's
- * conversation context instead of starting fresh. The run mechanics live in
- * `@deepseek-ai/dsh-subagent-inprocess` ({@link startInProcessRun}); this
- * backend just computes the seed. The spawn backend is an independent peer over
- * the same driver.
- *
- * The seed boundary is the crux: at the moment a subagent tool's `execute`
- * runs, the parent's CURRENT turn is open and unbalanced (it holds the
- * `assistant/message` with this spawn's tool-call, plus the dangling `tool/call`
- * with no `tool/result`). Seeding that raw prefix gives the child an open turn
- * the session constructor and the dev-mode invariants replay REJECT. So the
- * fork seeds only the **balanced completed-turn prefix**: the parent's log up
- * to and including its last `turn/end`, excluding the in-flight turn entirely.
- *
- * Plugin export shape: named `name`/`inject`/`Config`/`apply`, NO default.
- *
+ * `ctx.subagents` that runs each child as a child {@link Agent} SEEDED with a prefix of the
+ * parent's session log — so the child inherits the parent's conversation context instead of
+ * starting fresh. The seed ends at the last `turn/end`: the current tool-call turn is
+ * unbalanced and cannot be replayed as a valid child session.
  * @module @deepseek-ai/dsh-subagent-fork
  */
 
@@ -45,12 +32,10 @@ export const Config: z<Config> = z.object({
 })
 
 /**
- * The balanced completed-turn prefix of `parent`'s log: every event up to and
- * including the last `turn/end`. Empty if the parent has never completed a turn
- * (the in-flight turn is excluded, so a parent on its very first turn forks an
- * empty — i.e. fresh — child). The result is contiguous from seq 0 (the live
- * log keeps `seq === index`), so it is a valid session seed; the in-flight,
- * unbalanced turn is dropped so the invariants replay accepts it.
+ * The balanced completed-turn prefix of `parent`'s log: every event up to and including the
+ * last `turn/end`. The in-flight turn is excluded; before any completed turn the child starts
+ * fresh. Because live sequence numbers equal array indexes, the result remains a valid seed
+ * beginning at sequence zero.
  * @param parent - the agent whose session log to slice.
  * @returns the seed events, contiguous from seq 0; empty when no turn has completed.
  */

packages/subagent/subagent-fork/tests/subagent-fork.spec.ts

@@ -130,10 +130,9 @@ describe('dsh-subagent-fork', () => {
   })
 
   it('produces an invariant-CLEAN seed: forking mid-turn excludes the open turn', async () => {
-    // Drive the parent so it has ONE completed turn, then start a SECOND turn
-    // that is still open (a hanging model call), and fork while it's in flight.
-    // The fork must seed only the completed first turn — an unbalanced seed
-    // would make the invariants replay throw inside ctx.subagents.start.
+    // Drive the parent so it has one completed turn, then start a SECOND turn that is still
+    // open (a hanging model call), and fork while it's in flight. The seed must stop after the
+    // balanced first turn; including the open turn would fail invariant replay during start.
     const { ctx, parent } = await setup([textResponse('done'), 'hang', textResponse('child')])
     parent.send([{ type: 'text', text: 'q1' }])
     await parent.whenIdle()
@@ -178,12 +177,8 @@ describe('dsh-subagent-fork', () => {
   })
 
   it('does NOT return the seeded parent output when the child produces no message of its own', async () => {
-    // Regression: readResult must scope to the child's OWN events (after the
-    // seed). The parent completes a turn with a distinctive assistant message,
-    // then the fork child's own turn finishes with a bare `stop` and NO
-    // assistant/message. Scanning the whole (seeded) log would return the
-    // parent's "parent stale" message with stopReason 'completed'; scoped to the
-    // child's own events the output is empty.
+    // `readResult` must scan only child-owned events after the seed. The child emits no assistant
+    // message, so scanning the whole log would incorrectly return the parent's distinctive text.
     const { ctx, parent } = await setup([textResponse('parent stale'), emptyStop])
     parent.send([{ type: 'text', text: 'parent question' }])
     await parent.whenIdle()