zidane 6.4.3 → 6.5.0

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.3",
+  "version": "6.5.0",
   "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",