zidane 6.4.4 → 6.5.1

package/docs/RESTATE.md

@@ -196,7 +196,9 @@ On platforms without bidirectional streaming (AWS Lambda, sandbox-reattach runne
 
 Pass `restateClock(ctx, { coalesce: true })` to collapse most of those round-trips: the clock journals a real anchor once, derives a monotonic logical sequence from it (`anchor`, `anchor+1`, …) without re-journaling, and re-anchors against the real clock only every `reanchorEvery` calls (default 8; tune via `{ coalesce: { reanchorEvery: n } }`). It stays fully replay-deterministic (anchors replay verbatim; the counter is a pure function of call order) and strictly monotonic.
 
-The **tradeoff**: timestamps within a re-anchor window are logical — ordered and stable, but clustered near the window's anchor rather than wall-clock-accurate. Run `elapsed` (`endedAt - startedAt`) and per-turn `createdAt` lose precision down to the window granularity; live-only measurements (TTFT, `maxWallMs` budget) are unaffected because the loop reads those from `Date.now()` directly. Lower `reanchorEvery` ⇒ more accurate timestamps + more suspensions; higher ⇒ fewer suspensions + more clustering. The default (coalescing off) journals every `now()` and keeps wall-accurate timestamps, so opt in per deployment. Provider/tool `ctx.run` calls remain irreducible suspension points — coalescing only addresses the clock.
+The **tradeoff**: timestamps within a re-anchor window are logical — ordered and stable, but clustered near the window's anchor rather than wall-clock-accurate. Run `elapsed` (`endedAt - startedAt`) and per-turn `createdAt` lose precision down to the window granularity; live-only measurements (TTFT, `maxWallMs` budget) are unaffected because the loop reads those from `Date.now()` directly.
+
+Two subagent-specific consequences, both from differencing two coalesced draws: the elapsed figure in the spawn result string the **model reads** (`[sub-agent child-1] Completed in 2 turns (3ms)`) becomes a count of intervening clock draws rather than milliseconds, so a child that ran 40 seconds can report single-digit ms; and `createSpawnTool({ timeoutMs })`'s turn-boundary deadline measures the same logical scale, so it effectively counts draws too and won't fire on wall-clock time. Leave coalescing off if the model needs true durations or the child budget must track real time — hosts can always read the real duration off `ChildRunStats.stats.elapsed` (`spawn:complete` / `AgentStats.children`), which stays live `Date.now()`. Lower `reanchorEvery` ⇒ more accurate timestamps + more suspensions; higher ⇒ fewer suspensions + more clustering. The default (coalescing off) journals every `now()` and keeps wall-accurate timestamps, so opt in per deployment. Provider/tool `ctx.run` calls remain irreducible suspension points — coalescing only addresses the clock.
 
 **Gotcha**: when you pair a `restateSessionStore` with a session, the store's own `generateTurnId` runs ahead of `clock.randomUUID()` (the loop short-circuits via `session?.generateTurnId() ?? clock.randomUUID()`). The store derives deterministic IDs from the persisted turn count (`turn_1`, `turn_2`, …) so turn IDs stay stable across replay and across later invocations on the same object key. If you wire a custom store, keep turn ID generation deterministic from persisted state or let the Restate-backed clock provide the fallback UUIDs.
 
@@ -347,6 +349,159 @@ createAgent({
 
 The scheduler starts concurrency-safe, Restate-wrapped tools in submission order, joins each chunk through `RestatePromise.all()`, and emits tool results back to the model in original call order. Unsafe tools remain barriers. If a safe tool is not wrapped with `restateTool()` / `wrapAgentTools()`, Restate mode runs that chunk sequentially instead of falling back to native promise parallelism. This mode is opt-in so the TUI/headless harness keeps its native sliding-window scheduler.
 
+## Subagents
+
+`spawn` works under Restate, with one rule: **the spawn tool is never journaled — its child's steps are.**
+
+```ts
+const spawnTool = createSpawnTool({
+  persist: true,     // child turns + runs land in the parent's session
+  shareHandle: true, // no unjournaled per-child sandbox mint
+  timeoutMs: 600_000,
+})
+
+createAgent({
+  provider: restateProvider(myProvider, ctx, { streamCallbacks: 'suppress' }),
+  // Pass `spawn` in like any other tool — `wrapAgentTools` leaves it unwrapped.
+  tools: wrapAgentTools({ ...tools, spawn: spawnTool }, ctx),
+  clock: restateClock(ctx),
+  session,
+  behavior: restateBehavior({ maxTurns: 8 }),
+})
+```
+
+### Why the spawn tool is excluded from wrapping
+
+A child agent drives the *same* journaled provider (`ctx.provider`) and the *same* wrapped tools (`ctx.tools`) as its parent. If the spawn tool itself were wrapped, the child's first provider call would open a `ctx.run` **inside** the spawn tool's own `ctx.run`. That fails on the retry with `RestateError (570) Found a mismatch between the code paths taken during the previous execution and the paths taken during this execution` — observed against a real server, which is why `test/fixtures/restate-docker` now carries a subagent scenario.
+
+`wrapAgentTools` therefore skips any tool declaring `ToolDef.runsNestedAgent` (the built-in `spawn` sets it; host orchestrator tools that call `agent.run` should too). The skip is keyed on that marker, not the tool name, so a host tool that merely happens to be called `spawn` still gets wrapped.
+
+What you get instead is better: the child's provider calls and tool calls are journal entries **of the parent's invocation**. A crash mid-subagent replays the child's completed steps from the journal without re-running their bodies; only the unfinished step re-executes. Suspensions inside a child behave the same way.
+
+**Escape hatch.** Wrapping a spawn tool explicitly (`restateTool(spawnTool, ctx, …)`) is legal *only* if that child is fully non-durable — a raw provider from a model catalog, unwrapped tools. Then the whole child collapses into ONE journal entry: cheap to replay, but a crash inside the child re-runs the entire child (re-billing every LLM call) and none of its side effects are individually journaled.
+
+### What the child inherits
+
+| Inherited | How |
+|---|---|
+| `AgentClock` | Automatic. The child stamps `SessionTurn.createdAt`, run start/end, and fallback turn ids from the parent's journaled clock, so a shared session gets byte-identical metadata across attempts. A child on the default clock mints fresh wall-clock values on every replay. |
+| `AgentBehavior` | Automatic, including `toolBatchExecutor` — a child's own concurrency-safe fleets join through `RestatePromise.all()` like the parent's. |
+| Wrapped tools + provider | Automatic (`ctx.tools` / `ctx.provider`) — this is what makes the child's steps journaled at all. |
+| Session | `persist: true`. Child turn ids then come from `restateSessionStore`'s deterministic `(object key, seq)` mint. |
+| Execution handle | `shareHandle: true`. Otherwise every child calls `execution.spawn()` — an unjournaled allocation, so a replayed attempt mints a fresh sandbox and orphans the first. |
+| Durable tool state | **Never.** A child's `ctx.state` is an isolated in-memory map — see the note under Durable tool state below. |
+
+### Per-child timeout
+
+`createSpawnTool({ timeoutMs })` normally races the child against a `setTimeout`. That is a wall-clock branch: the same child can time out live and not on the replay, and the abort can land mid-stream, tearing a provider call down from inside its own journal entry. When the clock reports `journaled` (as `restateClock` does), the spawn tool leaves the timer off and instead samples the journaled clock at the child's **turn boundaries** — one sample before the run, one per completed turn — aborting the child at a boundary where nothing is in flight. Both mechanisms report `status: 'timeout'`.
+
+Deliberately **not** implemented by borrowing `behavior.maxWallMs`, which looks like the natural fit: the loop derives the provider stream watchdogs from the wall budget (`providerWatchdogTimeouts` clamps start / total / idle by it), so a small `timeoutMs` would also shrink the child's TTFT ceiling and abort a live stream inside its `ctx.run`. Against a real server that fails the attempt with `awaitNext already pending` and then `RestateError 570` on the retry. The fixture's deadline scenario exists because that bug shipped for exactly one iteration.
+
+Two consequences of the turn-boundary check: a child stuck inside ONE long tool call is not interrupted (use the runtime's own invocation timeout for a hard cut), and the measured elapsed time **spans the crash-to-retry gap**, because the run-start timestamp replays from before the crash. Budget accordingly.
+
+### Limits
+
+- **Sequential spawns only** with `createSpawnTool` — for parallel children use `restateSpawnTool` (next section), which sidesteps both reasons below by giving each child its own journal. The weaker one: parallel children race on shared session state — the `child-N` label counter and the run-id re-sync both read `session.runs` at mint time — so label / run-id assignment can differ between attempts. The stronger one: children share the parent's *clock instance*, and `restateClock` carries mutable draw state (the `randomUUID` sequence counter, plus the anchor / call counter in `coalesce` mode). Concurrent children interleave those draws, so the same logical turn can draw a different id or timestamp ordinal on a replay — the `JournalMismatchError` class the clock module exists to prevent. `restateBehavior`'s default `maxConcurrentTools: 1` already gives you the safe posture; don't raise it for a turn that can spawn more than once.
+- **Anything that reaches the transcript must come from `ctx.clock`.** The spawn result string is persisted in the parent's turns, and a state write's payload IS compared across attempts — so the elapsed figure in `[sub-agent child-1] Completed in 2 turns (35ms)` is sampled from the clock, not from `stats.elapsed` (which stays live `Date.now()` by design, for measurement accuracy). Getting this wrong fails the invocation at `set state` with `RestateError 570`, and only on an attempt that fails AFTER a child completed — a crash mid-child never produces the string, so the failure hides until a retry happens later in the run. The fixture's retry scenario exists for exactly that reason. The same rule is why the child inherits the clock at all.
+- **The parent's spawn tool call is not itself journaled**, so it re-executes on replay: agent construction, MCP re-use, hook bubbling, and result-string formatting all run again. Keep host `onChildStart` / `spawn:*` handlers idempotent.
+- **Don't set `behavior.maxWallMs` on a Restate-backed agent** (parent or child) unless you mean it: the provider stream watchdogs are clamped by it, so a tight budget aborts an in-flight stream from inside its journal entry rather than stopping cleanly at a turn boundary. Reach for the runtime's own invocation timeout, or `createSpawnTool({ timeoutMs })` for a child.
+
+## Parallel subagents
+
+`createSpawnTool` runs children in the parent's journal, which is what makes them sequential. `restateSpawnTool` dispatches each child to **its own invocation**, so children fan out through the durable fleet — and a crash in one child retries only that child.
+
+```ts
+const spawn = restateSpawnTool({
+  // Return the runtime's promise UNTOUCHED — no await, no .then/.catch.
+  dispatch: req => ctx.serviceClient(childService).runChild(req),
+  // Stop in-flight children when the parent's own loop aborts.
+  onAbort: () => ctx.invocation(ctx.request().id).cancel(),
+})
+
+createAgent({
+  tools: { ...wrapAgentTools(tools, ctx), spawn },
+  clock: restateClock(ctx),
+  session,
+  behavior: restateBehavior({
+    maxConcurrentTools: 4, // defaults to 1 — without this there is no fan-out
+    toolBatchExecutor: restateToolBatchExecutor({ promises: RestatePromise }),
+  }),
+})
+```
+
+### Choosing between the two
+
+| | `createSpawnTool` | `restateSpawnTool` |
+|---|---|---|
+| Children per turn | one at a time | parallel (fleet-capped) |
+| Journal | shares the parent's | one per child |
+| Crash in a child | replays the parent frame, re-drives the child | retries only that child |
+| `child:*` events | live (in-process bubbling) | replayed onto the parent bus when the child merges |
+| Host code needed | none | a child handler |
+
+### Host obligations
+
+- **The child handler must be a `service`**, or an object on a *different* key. A virtual object serializes per key, so children sharing the parent's key queue behind the parent that still holds it — no parallelism, and a deadlock risk.
+- **Raise `maxConcurrentTools` and install the durable batch executor.** The fleet gate is all-or-nothing (`fleet.every(canExecuteDurably)`), so with the default cap of 1 the children serialize silently.
+- **The child runs sessionless** and returns a `ChildRunResult` (`status`, `text`, `turns`, `stats`). The parent stays the single writer: it merges each child's turns under a `SessionRun` labeled in submission order, so the persisted tree matches the in-process tool's.
+- **Enforce depth in the handler** (`req.depth`). The tool always dispatches, because short-circuiting would mean returning a non-durable promise and the fleet rejects those.
+
+### What you give up
+
+- **`child:*` events fire, but not live** — see the section below.
+- **`spawn:before` is fired without awaiting** — `durableExecute` must return the durable promise synchronously, so listeners on it must not perform journaled I/O.
+- **Merge ordering**: children are merged on `tool-results:after` (with `turn:after` as a backstop for turns that pack no results), so their turns land just *after* the parent's tool-result turn rather than just before it. `createdAt` still orders them correctly for consumers that sort chronologically. If the invocation is torn down before the turn ends at all — a cancellation, say — a child that already settled is never merged and its `spawn:complete` never fires; its work still happened, it just isn't recorded.
+- **The child should report its own `startedAt` / `endedAt`** (measured on its clock, e.g. `restateClock(ctx)`). Those land in the merged `SessionRun`, which is persisted through a journaled state write, so they have to be replay-stable — the parent never samples a clock for them. Omit them and it falls back to the child's first/last turn timestamps, then to the parent's run start.
+- **Per-child timeouts are the callee's job.** Racing the call promise is the forbidden native-combinator pattern; give the child handler its own budget, or use the runtime's `.orTimeout()`.
+- **Cancelling the parent INVOCATION stops the children** — Restate cancels the call tree, so each child halts at its next journal interaction, at any depth. Verified: with two children mid-fan-out, no further work steps started after a `PATCH /invocations/{id}/cancel`. A step already inside a `ctx.run` finishes, since run bodies are not interruptible.
+- **An in-agent `agent.abort()` needs `onAbort`.** On its own, `abort()` unwinds the parent's loop while its invocation keeps running, so nothing tells the children to stop. `onAbort` fires once with the in-flight set; cancel the parent's own invocation from it and the runtime cancels the tree. The cost is that the parent invocation ends too — an in-agent abort becomes "stop everything", so persist any summary BEFORE aborting.
+- **Cancelling individual children is not possible in this tool shape.** The `invocationId` on the runtime's call handle is itself a journal-backed promise, so reading it while the call is in flight registers a second consumer on the SDK's single-consumer progress channel: `awaitNext already pending`, a failed attempt, and a replay on *every* fan-out (measured — 13 spurious attempts across the fixture suite before this was reverted). Per-child cancellation needs a two-phase `send → id → attach` tool, where the id is consumed before the result promise exists.
+
+### Child events
+
+Hook bubbling can't cross an invocation boundary, so a parallel child's events can't reach the parent's bus *as they happen*. Instead, each child's transcript is **replayed onto the parent's bus when it merges** — so `src/output/terminal.ts`, the GUI engine, and any `child:tool:*` listener render parallel children with no changes. Turn it off with `emitChildEvents: false`.
+
+| Fires | From |
+|---|---|
+| `child:stream:text` | assistant text, one chunk per turn |
+| `child:tool:before` | each `tool_call` block, with a run-cumulative `runToolCounts` tally |
+| `child:tool:after` / `child:tool:error` | the matching `tool_result`, split on `isError` |
+| `child:turn:after` | each assistant turn, `usage` straight off the turn |
+| `child:stream:end` | end of each turn |
+
+Every event carries `childId` (the reserved label), `depth`, and — on the tool events, which extend `ToolHookContext` — `runId`, `parentRunId`, and `parentCallId` (the spawn call that owns the child). Per-child blocks stay contiguous and follow **submission** order, not settlement order.
+
+**Not synthesized**: `tool:gate`, `tool:transform`, `tool:dispatched`, `tool:cancelled`, `background:*`. Those describe decisions taken inside another process; inventing them would be fiction.
+
+**They re-fire on a parent replay**, exactly as the in-process tool's `child:tool:*` does — the drain runs live on every attempt. Dedupe by `callId` / `turnId`, or gate on `createReplayTracker`. The fixture pins this rather than asserting it in prose: a post-merge replay emits 24 events for 12 events' worth of work, measured through a file sink that outlives the attempt.
+
+#### Nested fan-out
+
+A child dispatched to a service runs **sessionless**, so it has nowhere to persist its own children. Left alone, a depth-2 fan-out loses everything below depth 1 — the parent sees the child's `spawn` tool calls and none of the work they did. Hand the subtree up instead:
+
+```ts
+const merged: MergedChild[] = []
+const spawn = restateSpawnTool({
+  onChildMerged: child => merged.push(child),
+  dispatch: req => ctx.serviceClient(childService).runChild(req),
+})
+// … and return it from the handler
+return { status: 'completed', text, turns: agent.turns, stats, children: merged }
+```
+
+The merging parent walks that subtree depth-first, **re-labeling** each descendant from its own session counter (every level mints `child-1` locally, so the arriving labels collide), and emits their `child:*` events at the right depth. Verified end to end: parent → one child → two grandchildren lands four runs at depths 0/1/2/2 with labels `child-1` / `child-2` / `child-3`, and the grandchildren's tool events arrive at `depth: 2`.
+
+#### If you need it live
+
+Publish from the child's own bus inside your handler; the child is an ordinary agent there and its hooks fire normally. `ChildRunRequest` carries `parentRunId`, `parentCallId` and `sessionId` so the child can tag what it publishes and your UI can group it with the parent's own events. Two caveats:
+
+- `restateProvider(..., { streamCallbacks: 'suppress' })` no-ops `onText`, so text deltas never fire even inside the child. Drop `suppress` and you get `maxRetryAttempts: 1` instead — otherwise an entry retry re-emits deltas and duplicates text.
+- A child's events re-fire on the *child's* own replay, so the sink must be idempotent.
+
+What's deliberately not offered is journaling each child event so the parent can consume it as a journal entry. That is the only live option that stays inside the determinism envelope, and it costs a journal entry per event plus a parent that must stay awake to read them — which defeats the suspension that makes long children cheap. Defensible at coarse milestones, not per token.
+
+Every property here is pinned by the fixture against a real server: two children overlapping by ~394ms of their 400ms of work; four children at a cap of two running as two clean waves (max concurrency exactly 2, wall time 1031ms versus 2090ms for the same fan-out at cap 1); a crash inside one child leaving its sibling with exactly one execution; and both children's transcripts arriving on the parent's bus as `child:*` events, in contiguous per-child blocks.
+
 ## Durable tool state
 
 The problem it solves: **a tool cannot keep state in a closure.** A journaled result skips the tool body on replay, so a `consumed = true` written inside `execute` never happens the second time around — while the closure itself was rebuilt from the original input. The tool then re-serves a payload it already delivered.
@@ -396,7 +551,7 @@ The invariant that makes it replay-safe: **a staged mutation is committed only i
 - **`set(key, undefined)` is a deletion.** It is what a read would report anyway, and an undefined value is not JSON-stable across the journal.
 - **Two-phase tools** (`durableStart`) journal their delta on the final entry (`wait.result` / `attach`). A write staged in `start` is lost if the process dies before the wait completes; write state in the final phase when it must be crash-durable.
 - **Keep values small and JSON-serializable.** They cross a journal and land in virtual-object state, which Restate size-caps: flags, ids, counters, cursors — not transcripts.
-- **Not inherited by subagents.** A child you construct yourself can take the same store; `createSpawnTool` has **no** `shareToolState` equivalent to `shareReadState`, so tools running inside a *spawned* subagent get an isolated in-memory map and their writes never reach the parent's store.
+- **Not inherited by subagents.** A child you construct yourself can take the same store; `createSpawnTool` has **no** `shareToolState` equivalent to `shareReadState`, so tools running inside a *spawned* subagent get an isolated in-memory map and their writes never reach the parent's store. This is the one thing a subagent does NOT get under Restate — everything else (journaled clock, wrapped tools/provider, session, handle) is covered in § Subagents. A child's one-shot delivery is therefore not crash-safe; keep such tools in the parent, or hand the child an explicitly constructed agent with the same `toolState` store.
 - **The store is bound to one invocation's `ctx`.** Build it inside the handler, like `restateSessionStore` and `restateProvider`. An agent constructed once at module scope and reused across invocations would commit through a dead context — and never re-hydrate. `toolState` reads like agent-lifetime configuration, which makes this easier to get wrong than the other ctx-bound wrappers.
 - **The stored map is a schema you own.** It is one JSON object under one state key, with no versioning or migration built in. Renaming a key or changing a value's shape has to tolerate the old value still being there from a previous deploy; `restateToolStateStore(ctx, { key })` gives you a clean namespace when a migration is easier than a tolerant read.
 
@@ -589,7 +744,17 @@ A runtime with a hard per-invocation CPU/wall cap (Cloudflare's ~5-minute limit)
 
 `test/tool-state.test.ts` covers the runtime-agnostic half — snapshot hydration, staging, commit-on-settle, the size guard, the commit-failure hook, the in-memory default, and the loop round-trip.
 
-`bun run restate:fixture:test` is the end-to-end suite against a **real** Restate server in Docker, and is deliberately **not** part of CI — run it locally when you touch the adapter. It boots the container, supervises the fixture service, and drives five scenarios through the real ingress: baseline agent run; crash → replay (the service process is killed mid-invocation and respawned, so the journal, not a mock, decides what re-runs); per-object-key state isolation; commit-after-soft-failure; and an awakeable suspend/resume. It fails if the crash never forced a respawn, so it cannot pass without actually exercising replay. This is the only coverage where replay, suspension, and virtual-object state semantics come from the SDK rather than from our reading of it.
+`bun run restate:fixture:test` is the end-to-end suite against a **real** Restate server in Docker, and is deliberately **not** part of CI — run it locally when you touch the adapter. It boots the container, supervises the fixture service, and drives nineteen scenarios through the real ingress.
+
+Five cover the adapter itself: baseline agent run; crash → replay (the service process is killed mid-invocation and respawned, so the journal, not a mock, decides what re-runs); per-object-key state isolation; commit-after-soft-failure; and an awakeable suspend/resume.
+
+Five cover **subagents**, each pinned on an on-disk ledger that has to outlive the process: a crash inside the child; an awakeable park inside the child (suspend → external resume, with the child's `register` phase required to fire exactly once, or the resumed awakeable id would be one nobody resolves); a depth-2 grandchild crash, two un-journaled spawn frames deep; a journaled-deadline trip; and an attempt that fails **without** a process death, so the journal replays against warm module state — that one asserts an unchanged boot count to prove it took the retry path and not the crash path.
+
+Eight cover **parallel** subagents (`restateSpawnTool`). Two children as separate invocations, asserted to have *overlapping* work intervals — counting executions can't tell parallel from sequential. A crash inside one of them, where the surviving sibling must show exactly one execution: proof that the children really are journal-isolated. Then the scheduling pair: four children in one turn against a fleet cap of two, where the interval ledger must show a maximum of exactly **two** open at once (3+ means the cap is ignored, 1 means the fleet silently fell back to sequential), and the same fan-out at cap 1 as a control, where nothing may overlap. Measured: 1031ms wall at cap 2 versus 2090ms at cap 1 for identical work.
+
+The remaining three cover the failure modes that decide whether this is production-safe. **A parent crash mid-fan-out**: the parent dies while both children are still working, and on replay must re-attach to the running invocations rather than dispatch new ones — exactly one execution per child, even though the parent frame ran twice. **Depth-2 fan-out**: a child that itself spawns two grandchildren, whose intervals must overlap, so parallelism survives nesting. **Cancellation**, twice: once from outside (the parent invocation is cancelled mid-flight and no child may start another work step) and once from inside (`agent.abort()` with `onAbort` wired, where children finish the step in flight and never begin the next). **A post-merge replay**: the fan-out completes and merges, then the handler fails once, so the parent replays *after* the merge — the only scenario that re-executes the merge path, and the one that caught wall-clock timestamps leaking into the merged run records.
+
+Both subagent bugs found in review — the `maxWallMs` watchdog clamp and the live `elapsed` inside a persisted string — were caught here and nowhere else. The suite fails if the crash never forced a respawn, so it cannot pass without actually exercising replay. This is the only coverage where replay, suspension, and virtual-object state semantics come from the SDK rather than from our reading of it.
 
 `test/start.test.ts` covers the local `bun start --restate` runner helpers: option parsing, deployment registration, ingress invocation timeout wiring, readiness/service probing, runtime-state cleanup, cached completion, changed-input rejection, and `status` / `history` handlers.
 

package/docs/SKILL.md

@@ -262,10 +262,22 @@ interface ToolDef {
   ) => Promise<string | ToolResultContent[]>
   /** Default `false`. See "Per-tool concurrency" below. */
   isConcurrencySafe?: boolean | ((input: Record<string, unknown>) => boolean)
+  /**
+   * Set it when `execute` runs a full nested agent loop (calls `agent.run`).
+   * The built-in `spawn` does. Inert outside durable execution; under a durable
+   * runtime it is load-bearing — `wrapAgentTools` keeps such tools out of its
+   * journaling wrapper, because the child's own journaled calls cannot nest
+   * inside the outer tool's journal entry. Miss it on a host orchestrator tool
+   * and the invocation fails on its first retry. See `docs/RESTATE.md`
+   * § Subagents.
+   */
+  runsNestedAgent?: boolean
 }
 ```
 
-`ToolContext` exposes `provider`, `signal`, `execution`, `handle`, `hooks`, `turnId`, `callId`, `runId?`, `parentRunId?`, `session?`, `readState?`, `depth?`, plus preset fields (`name`, `system`, `tools`, `toolAliases`, `mcpServers`, `skills`, `behavior`) so `spawn` can inherit.
+`ToolContext` exposes `provider`, `signal`, `execution`, `handle`, `hooks`, `turnId`, `callId`, `runId?`, `parentRunId?`, `parentCallId?`, `session?`, `readState?`, `clock?`, `depth?`, plus preset fields (`name`, `system`, `tools`, `toolAliases`, `mcpServers`, `skills`, `behavior`) so `spawn` can inherit.
+
+`clock` is the run's time / UUID source (`AgentClock`) — prefer it over `Date.now()` / `crypto.randomUUID()` for anything that gets persisted or shown to the model, because a durable host replaces it with a journaled one so those values replay byte-identically. If you write your own durable adapter, set `AgentClock.journaled: true` on the clock you install: consumers read it to avoid deciding on a wall-clock timer inside a journaled region (the `spawn` tool switches its per-child timeout to a turn-boundary check on that signal).
 
 Returns `string` (common) or `ToolResultContent[]` (images / mixed content). Routed natively via `tool_result.content` when supported, or via companion user message on plain Chat Completions. Flatten via `toolResultToText(result)`.
 
@@ -372,7 +384,7 @@ For post-edit validation, use `createMutationValidationHooks()` from `zidane`. I
 | `session:turns` | Turns persisted | — | `sessionId, turns, count` |
 | `session:save` | Session store write | — | `sessionId` |
 | `session:meta` | Session metadata write | — | `sessionId, key: string, value: unknown` |
-| `spawn:before`, `spawn:complete`, `spawn:error` | Sub-agent lifecycle | — | `id, task, stats?, error?` |
+| `spawn:before`, `spawn:complete`, `spawn:error` | Sub-agent lifecycle | — | `id, task, callId?, stats?, error?` (`callId` = the spawn call's own id, i.e. the child's `parentCallId`) |
 | `session:start`, `session:end` | Run boundaries (always fire) | — | `sessionId, runId` + (`prompt` \| `status, turnRange`) |
 | `agent:abort` | `agent.abort()` called | — | `{}` |
 | `agent:done` | Run finished (all exit paths) | — | `AgentStats` |
@@ -385,13 +397,14 @@ Mutable ctx fields: `tool:gate` (`block`, `reason`, `result`), `tool:transform`
 
 ### Identity fields on tool hook contexts
 
-Every `tool:*` and `mcp:tool:*` hook ctx additionally carries three optional identity fields (omitted from the per-row "key ctx fields" column above to keep the table readable):
+Every `tool:*` and `mcp:tool:*` hook ctx additionally carries four optional identity fields (omitted from the per-row "key ctx fields" column above to keep the table readable):
 
 - `runId?: string` — the `SessionRun.id` this call belongs to. Lets one listener disambiguate calls across parallel runs / subagent trees without subscribing to `child:tool:*`.
-- `parentRunId?: string` — set when the call's agent is a subagent (mirrors `SessionRun.parentRunId`); absent on top-level runs. Drives UI grouping for subagent-scoped state (todowrite batches, edit groups, etc.) without resolving the run row.
+- `parentRunId?: string` — set when the call's agent is a subagent (mirrors `SessionRun.parentRunId`); absent on top-level runs. Drives UI grouping for subagent-scoped state (todowrite batches, edit groups, etc.) without resolving the run row. Only wired when the spawn shares the parent's session (`persist`) — for grouping that must hold on every subagent, use `parentCallId`.
+- `parentCallId?: string` — the `callId` of the `spawn` call that created this run; absent on top-level runs. Set for every child the built-in `spawn` tool starts (it forwards its own call id; no session required), so hosts mirroring subagent work into a client protocol can use it as the "parent tool use" grouping key — absent at depth 0, a real tool-call id at depth ≥ 1. Two qualifications: it is not implied by `depth >= 1` (a host that spawns by calling `agent.run({ depth })` itself must also pass `AgentRunOptions.parentCallId`), and it resolves against the parent's own `tool:*` stream only at depth 1 — at depth ≥ 2 it names a call in the child's turn, which the top-level listener saw only as `child:tool:*`. Same ancestry semantics as `childId` / `depth` on `child:*` events. The spawn payloads (`spawn:before` / `:complete` / `:error`) carry the same id as `callId`, which is where a host learns the `childId` → call mapping for a child that never dispatches a tool.
 - `depth?: number` — subagent depth, 0 = top-level. Mirrors `ToolContext.depth`.
 
-Same three fields land on `ToolContext` (visible to the tool body via `ctx.runId` / `ctx.parentRunId` / `ctx.depth`). The loop centralizes their construction in `buildToolHookBase`, so a new tool-related hook event automatically inherits them.
+All four land on `ToolContext` as well (visible to the tool body via `ctx.runId` / `ctx.parentRunId` / `ctx.parentCallId` / `ctx.depth`). The loop centralizes their construction in `buildToolHookBase`, so a new tool-related hook event automatically inherits them.
 
 ### Child (sub-agent) bubble events
 
@@ -599,14 +612,17 @@ definePreset({
 })
 ```
 
-### Parent/child boundaries — `persist` and `shareReadState`
+### Parent/child boundaries — `persist`, `shareReadState`, `shareHandle`
 
-Two **independent** flags control what crosses the parent/child boundary:
+Three **independent** flags control what crosses the parent/child boundary:
 
 | Flag | Default | What it shares |
 |---|---|---|
 | `persist` | `false` | The parent's `Session`. Child turns get appended to the same `session.turns` stream with the child's `runId`; the child's `SessionRun` carries `parentRunId` so the tree is reconstructible. As a side-effect the read-state map (Session-keyed) is also shared. |
 | `shareReadState` | `false` | Only the read-state map. The child gets `AgentOptions.readState` populated with the parent's resolved map but **no session** — `read_file` populations land in the parent's tracking, but child turns stay in-memory. |
+| `shareHandle` | `false` | The parent's `ExecutionHandle`. The child skips its own `execution.spawn()` and never destroys the handle (host owns the lifecycle), so children see the parent's filesystem and background-task namespace instead of an isolated scratch space. Matters most for remote contexts (sandbox / container), where a per-child allocation is real — and under a durable runtime is an unjournaled side effect that orphans a sandbox on every replayed attempt. See `docs/RESTATE.md` § Subagents. |
+
+Always inherited (not flags): the parent's `AgentClock`, so a durable host's journaled time/UUID source stamps child metadata too, and `AgentBehavior`, which carries the durable tool-batch scheduler.
 
 Use `shareReadState: true` (without `persist`) when you want the parent's `requireReadBeforeEdit` gate to honor reads the child performed, without polluting the parent's session with child turns. The gate's error message now hints at this when the entry is missing — re-read in the calling context OR opt into one of the sharing flags.
 
@@ -918,7 +934,7 @@ createSandboxContext(myProvider)  // implement SandboxProvider (E2B, Rivet, …)
 | `RunHookMap` | `run({ hooks })` shape. |
 | `AgentBehavior.maxConcurrentTools` | Cap on in-flight tools per turn (default `10`, clamped at `1`). See "Per-tool concurrency" above. |
 | `ToolDef.isConcurrencySafe` | `boolean \| ((input) => boolean)`. Defaults to `false`. See "Per-tool concurrency" above. |
-| `ToolHookContext` / `McpToolHookContext` / `SessionHookContext` / `StreamHookContext` / `SpawnHookContext` | Hook ctx base types. `ToolHookContext` / `McpToolHookContext` carry `runId? / parentRunId? / depth?` identity fields on every `tool:*` / `mcp:tool:*` event — see Identity fields above. |
+| `ToolHookContext` / `McpToolHookContext` / `SessionHookContext` / `StreamHookContext` / `SpawnHookContext` | Hook ctx base types. `ToolHookContext` / `McpToolHookContext` carry `runId? / parentRunId? / parentCallId? / depth?` identity fields on every `tool:*` / `mcp:tool:*` event — see Identity fields above. |
 | `ReadStateMap` / `ReadStateEntry` | Per-file read-tracking map (`Map<canonicalAbsPath, { contentHash, offset, limit, maxBytes, lineNumbers?, mtimeMs }>`). Construct one manually for `AgentOptions.readState` to share across an agent tree; or get the session-bound one via `getReadState(session)` / the lookup-aware `resolveReadStateMap(ctx)`. Canonical keys come from `readStateKey(cwd, path)`. |
 | `ClassifiedError` | `{ kind, providerCode?, message? }` from `Provider.classifyError`. |
 | `AgentContextExceededError` / `AgentProviderError` / `AgentAbortedError` / `AgentToolNotAllowedError` / `AgentBudgetExceededError` | Typed errors. `toTypedError(err)` wraps native errors. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "6.4.4",
+  "version": "6.5.1",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,
@@ -171,6 +171,11 @@
       "import": "./dist/skills.js",
       "default": "./dist/skills.js"
     },
+    "./plugins": {
+      "types": "./dist/plugins.d.ts",
+      "import": "./dist/plugins.js",
+      "default": "./dist/plugins.js"
+    },
     "./extensions": {
       "types": "./dist/extensions.d.ts",
       "import": "./dist/extensions.js",