zidane 6.4.3 → 6.5.0

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import { d as ClassifiedErrorKind, i as AgentContextExceededError, l as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, n as AgentAbortedError, o as AgentProviderError, p as matchesContextExceeded, r as AgentBudgetExceededError, s as AgentToolNotAllowedError, u as ClassifiedError } from "./timeout-DEaqslLO.js";
-import { $m as ToolDef, $p as DEFAULT_AGENT_CLOCK, As as SpawnToolOptions, Bm as ToolResultDocumentContent, C as SuccessfulMutationOutcome, Cm as RunHookMap, Dm as SessionMessage, Em as SessionHookContext, Gi as AgentHookMap, Gm as ToolResultTextContent, Hm as ToolResultImageContent, Hp as AgentClock, Im as ToolHookContext, Jm as TurnUsage, Jp as ChildRunStats, Kf as OpenAIParams, Ki as AgentHooks, Km as ToolResultVideoContent, Lm as ToolOutcome, Mh as RemoteStoreOptions, Mm as StreamHookContext, Om as SessionTurn, Pm as ThinkingLevel, Qm as ToolContext, Rm as ToolResultAudioContent, Rr as InteractionToolOptions, S as MutationValidationResult, Sf as OpenRouterParams, Sh as SessionStore, Sm as RetryConfig, Tm as SessionEndStatus, Ts as ChildAgent, Um as ToolResultImageRefContent, Up as AgentRunOptions, Vm as ToolResultDocumentRefContent, Vp as AgentBehavior, Wi as Agent, Wm as ToolResultMetadata, Wp as AgentStats, Xm as toolOutputByteLength, Ym as toolOutputBudgetByteLength, Zm as toolResultToText, _ as statsByModel, _m as PromptVideoPart, af as StreamCallbacks, am as McpToolHookContext, b as MutationValidationHooksOptions, bm as ResolveContentRef, cf as ToolCall, df as TurnResult, dg as McpConnection, dh as SkillConfig, dm as ProgressNudgeMessage, eh as ToolMap, fm as PromptAudioPart, gh as CreateSessionOptions, gm as PromptTextPart, h as flattenTurns, hh as SkillsConfig, hm as PromptPart, if as ProviderCapabilities, im as McpServerConfig, ip as CerebrasParams, js as SpawnToolState, km as SpawnHookContext, lf as ToolResult, lm as OAuthRefreshHookContext, mm as PromptImagePart, nh as ReadStateEntry, of as StreamOptions, p as ModelUsage, ph as SkillResource, pm as PromptDocumentPart, pp as AnthropicParams, qi as AgentOptions, qm as TurnFinishReason, rf as Provider, rh as ReadStateMap, t as Preset, uf as ToolSpec, um as ProgressNudgeKind, v as MutationValidationBatch, vh as Session, vm as RepeatGuardConfig, vr as ValidationResult, wm as SessionContentBlock, x as MutationValidationMutation, xh as SessionRun, xm as ResolveContentRefBlock, y as MutationValidationFailure, yh as SessionData, ym as RepeatGuardToolMatcher, zm as ToolResultContent } from "./index-W_8010Lt.js";
+import { $h as SkillsConfig, $m as SessionContentBlock, Bf as TurnResult, Bh as StagedToolState, Bm as ProgressNudgeMessage, C as SuccessfulMutationOutcome, Ch as TurnUsage, Cm as ChildRunStats, Dh as ToolContext, Eh as toolResultToText, Ff as StreamOptions, Gi as AgentHookMap, Gm as PromptTextPart, Hh as ToolStateOp, Hm as PromptDocumentPart, Hp as AnthropicParams, Jm as RepeatGuardToolMatcher, Ki as AgentHooks, Km as PromptVideoPart, Lf as ToolCall, Mf as Provider, Mh as ReadStateMap, Nf as ProviderCapabilities, Nm as McpServerConfig, Np as CerebrasParams, Ns as SpawnToolOptions, Oh as ToolDef, Om as DEFAULT_AGENT_CLOCK, Os as ChildAgent, Pf as StreamCallbacks, Pm as McpToolHookContext, Ps as SpawnToolState, Qm as RunHookMap, Rf as ToolResult, Rm as OAuthRefreshHookContext, Rr as InteractionToolOptions, S as MutationValidationResult, Sh as TurnFinishReason, Th as toolOutputByteLength, Uh as ToolStateStore, Um as PromptImagePart, Vh as ToolStateController, Vm as PromptAudioPart, Wh as ToolStateView, Wi as Agent, Wm as PromptPart, Xm as ResolveContentRefBlock, Yg as McpConnection, Yh as SkillConfig, Ym as ResolveContentRef, Zf as OpenRouterParams, Zh as SkillResource, Zm as RetryConfig, _ as statsByModel, _h as ToolResultImageContent, _m as AgentClock, ag as SessionRun, b as MutationValidationHooksOptions, bh as ToolResultTextContent, dh as ToolHookContext, eg as CreateSessionOptions, eh as SessionEndStatus, fh as ToolOutcome, gg as RemoteStoreOptions, gh as ToolResultDocumentRefContent, gm as AgentBehavior, h as flattenTurns, hh as ToolResultDocumentContent, ih as SpawnHookContext, jh as ReadStateEntry, kh as ToolMap, lh as ThinkingLevel, mh as ToolResultContent, ng as Session, nh as SessionMessage, og as SessionStore, p as ModelUsage, ph as ToolResultAudioContent, qi as AgentOptions, qm as RepeatGuardConfig, rg as SessionData, rh as SessionTurn, sh as StreamHookContext, t as Preset, th as SessionHookContext, v as MutationValidationBatch, vh as ToolResultImageRefContent, vm as AgentRunOptions, vr as ValidationResult, wh as toolOutputBudgetByteLength, x as MutationValidationMutation, xh as ToolResultVideoContent, xp as OpenAIParams, y as MutationValidationFailure, yh as ToolResultMetadata, ym as AgentStats, zf as ToolSpec, zm as ProgressNudgeKind } from "./index-CWBSrqI6.js";
 import { _ as TaskHandle, a as ContextType, c as ExecutionContext, g as TaskExitInfo, h as TaskEntry, l as ExecutionHandle, n as ContextCapabilities, o as DetachedTasksCapability, p as SpawnConfig, r as ContextHardening, s as ExecResult, t as BackgroundTaskStatus, v as TaskStallInfo } from "./types-M2DauK2D.js";
 import { t as SandboxProvider } from "./sandbox-DLY6uah7.js";
-export { type Agent, AgentAbortedError, type AgentBehavior, AgentBudgetExceededError, type AgentClock, AgentContextExceededError, type AgentHookMap, type AgentHooks, type AgentOptions, AgentProviderError, type AgentRunOptions, type AgentStats, AgentToolNotAllowedError, type AnthropicParams, type BackgroundTaskStatus, CONTEXT_EXCEEDED_MESSAGE_PATTERNS, type CerebrasParams, type ChildAgent, type ChildRunStats, type ClassifiedError, type ClassifiedErrorKind, type ContextCapabilities, type ContextHardening, type ContextType, type CreateSessionOptions, DEFAULT_AGENT_CLOCK, type DetachedTasksCapability, type ExecResult, type ExecutionContext, type ExecutionHandle, type InteractionToolOptions, type McpConnection, type McpServerConfig, type McpToolHookContext, type ModelUsage, type MutationValidationBatch, type MutationValidationFailure, type MutationValidationHooksOptions, type MutationValidationMutation, type MutationValidationResult, type OAuthRefreshHookContext, type OpenAIParams, type OpenRouterParams, type Preset, type ProgressNudgeKind, type ProgressNudgeMessage, type PromptAudioPart, type PromptDocumentPart, type PromptImagePart, type PromptPart, type PromptTextPart, type PromptVideoPart, type Provider, type ProviderCapabilities, type ReadStateEntry, type ReadStateMap, type RemoteStoreOptions, type RepeatGuardConfig, type RepeatGuardToolMatcher, type ResolveContentRef, type ResolveContentRefBlock, type RetryConfig, type RunHookMap, type SandboxProvider, type Session, type SessionContentBlock, type SessionData, type SessionEndStatus, type SessionHookContext, type SessionMessage, type SessionRun, type SessionStore, type SessionTurn, type SkillConfig, type SkillResource, type SkillsConfig, type SpawnConfig, type SpawnHookContext, type SpawnToolOptions, type SpawnToolState, type StreamCallbacks, type StreamHookContext, type StreamOptions, type SuccessfulMutationOutcome, type TaskEntry, type TaskExitInfo, type TaskHandle, type TaskStallInfo, type ThinkingLevel, type ToolCall, type ToolContext, type ToolDef, type ToolHookContext, type ToolMap, type ToolOutcome, type ToolResult, type ToolResultAudioContent, type ToolResultContent, type ToolResultDocumentContent, type ToolResultDocumentRefContent, type ToolResultImageContent, type ToolResultImageRefContent, type ToolResultMetadata, type ToolResultTextContent, type ToolResultVideoContent, type ToolSpec, type TurnFinishReason, type TurnResult, type TurnUsage, type ValidationResult, flattenTurns, matchesContextExceeded, statsByModel, toolOutputBudgetByteLength, toolOutputByteLength, toolResultToText };
+export { type Agent, AgentAbortedError, type AgentBehavior, AgentBudgetExceededError, type AgentClock, AgentContextExceededError, type AgentHookMap, type AgentHooks, type AgentOptions, AgentProviderError, type AgentRunOptions, type AgentStats, AgentToolNotAllowedError, type AnthropicParams, type BackgroundTaskStatus, CONTEXT_EXCEEDED_MESSAGE_PATTERNS, type CerebrasParams, type ChildAgent, type ChildRunStats, type ClassifiedError, type ClassifiedErrorKind, type ContextCapabilities, type ContextHardening, type ContextType, type CreateSessionOptions, DEFAULT_AGENT_CLOCK, type DetachedTasksCapability, type ExecResult, type ExecutionContext, type ExecutionHandle, type InteractionToolOptions, type McpConnection, type McpServerConfig, type McpToolHookContext, type ModelUsage, type MutationValidationBatch, type MutationValidationFailure, type MutationValidationHooksOptions, type MutationValidationMutation, type MutationValidationResult, type OAuthRefreshHookContext, type OpenAIParams, type OpenRouterParams, type Preset, type ProgressNudgeKind, type ProgressNudgeMessage, type PromptAudioPart, type PromptDocumentPart, type PromptImagePart, type PromptPart, type PromptTextPart, type PromptVideoPart, type Provider, type ProviderCapabilities, type ReadStateEntry, type ReadStateMap, type RemoteStoreOptions, type RepeatGuardConfig, type RepeatGuardToolMatcher, type ResolveContentRef, type ResolveContentRefBlock, type RetryConfig, type RunHookMap, type SandboxProvider, type Session, type SessionContentBlock, type SessionData, type SessionEndStatus, type SessionHookContext, type SessionMessage, type SessionRun, type SessionStore, type SessionTurn, type SkillConfig, type SkillResource, type SkillsConfig, type SpawnConfig, type SpawnHookContext, type SpawnToolOptions, type SpawnToolState, type StagedToolState, type StreamCallbacks, type StreamHookContext, type StreamOptions, type SuccessfulMutationOutcome, type TaskEntry, type TaskExitInfo, type TaskHandle, type TaskStallInfo, type ThinkingLevel, type ToolCall, type ToolContext, type ToolDef, type ToolHookContext, type ToolMap, type ToolOutcome, type ToolResult, type ToolResultAudioContent, type ToolResultContent, type ToolResultDocumentContent, type ToolResultDocumentRefContent, type ToolResultImageContent, type ToolResultImageRefContent, type ToolResultMetadata, type ToolResultTextContent, type ToolResultVideoContent, type ToolSpec, type ToolStateController, type ToolStateOp, type ToolStateStore, type ToolStateView, type TurnFinishReason, type TurnResult, type TurnUsage, type ValidationResult, flattenTurns, matchesContextExceeded, statsByModel, toolOutputBudgetByteLength, toolOutputByteLength, toolResultToText };

package/docs/ARCHITECTURE.md

@@ -839,6 +839,8 @@ Defaults: unlimited turns (set `maxTurns` as a safety net), model-driven output
 
 Tools with side effects or non-deterministic outputs MUST NOT be listed (no safety net beyond the consumer hasher).
 
+**`ToolContext.state`** (`src/tool-state.ts`) is durable key/value state for tools — the supported way to keep a one-shot marker, a cursor, or a dedup flag that must outlive the process. It exists because a closure variable can't: under a durable runtime a journaled tool result skips the body on replay, so a mutation made inside `execute` silently doesn't happen the second time. Reads are synchronous against a snapshot the agent hydrates once per agent instance (before the first dispatch, memoized on the controller); writes are staged as ops and committed by the dispatch path when the call settles — in call-index order, never completion order, and a rejecting store commit drops the write rather than failing the call. `AgentOptions.toolState` supplies the durable backing (`ToolStateStore` = `load` + `commit`, runtime-agnostic; `zidane/restate` ships `restateToolStateStore`); with none configured the map is in-memory and agent-scoped, so tools behave identically locally minus durability. The three-phase split is what lets a durable adapter journal the staged delta *as data* alongside the tool result and re-issue the identical write on replay — see [Durable tool state](./RESTATE.md#durable-tool-state). A rejecting store never fails the call (the body already ran): it fires `tool-state:commit-failed` with the lost ops and otherwise logs. Values are size-checked at `set()` time against `ToolStateStore.maxValueBytes` (default 64 KiB of JSON) so an oversized write throws in the tool that caused it rather than at commit — under Restate that difference is a failed-and-retried invocation versus a clean error.
+
 **`toolBudgets`** caps per-tool calls per run. When `runToolCounts[name] >= max`, fires `onExceed`: `'block'` refuses with `Blocked: <message>`, `'steer'` enqueues a synthetic user message (one per tool per run, deduped). Function form returns `{ mode, message }` dynamically. Fires `tool-budget:exceeded` (distinct from byte-level `budget:exceeded`). Counts include dedup substitutes by design.
 
 **`thinkingDecay`** tapers `thinkingBudget` per run-relative turn (1-indexed). `applyThinkingDecay(base, decay, turn)` runs at `runTurn` start. Struct form `{ afterTurn, factor, floor }` does geometric decay; function form `(turn, base) => number` accepts arbitrary curves. Result clamped to `[0, base]` so buggy curves can't exceed the caller's opt-in. Skipped for `thinking: 'adaptive'` only on providers with `adaptiveBudgetIsEnvelope` (Anthropic), where `thinkingBudget` caps the whole response envelope (`max_tokens`) and decaying it would strangle text/tool output; providers where adaptive `thinkingBudget` is a genuine per-turn thinking budget (openai-compat `reasoning.max_tokens`) still decay. `taskBudget` (Anthropic adaptive-only whole-task cap, emitted as `output_config.task_budget`) never decays.

package/docs/PLUGINS.md

@@ -0,0 +1,340 @@
+# Agent Plugins
+
+Support for [Agent Plugins](https://agent-plugins.org) 1.0.0 — an open, vendor-neutral package format for reusable agent components. A plugin is a directory with a manifest and its components at fixed locations; any conformant client can load it.
+
+```
+my-plugin/
+├── plugin.json      manifest (required)
+├── skills/          one directory per Agent Skill
+│   └── deploy/
+│       └── SKILL.md
+└── mcp.json         MCP server configuration
+```
+
+```ts
+import { loadAgentPlugin } from 'zidane/plugins'
+
+const plugin = await loadAgentPlugin('./my-plugin')
+if (plugin.ok) {
+  console.log(plugin.manifest.name, plugin.skills.length, plugin.mcpServers.length)
+}
+```
+
+Agent Plugins deliberately does **not** redefine either component format — skills are Agent Skills, MCP config is MCP config. So `zidane/plugins` owns only the packaging contract and hands back plain `SkillConfig[]` / `McpServerConfig[]` that every other zidane surface already consumes.
+
+## Why a separate loader
+
+zidane already reads both component types, but both existing readers are deliberately *lenient*: `discoverSkills` recurses into nested category directories, and `normalizeMcpServers` infers a transport from the presence of `command` / `url` and accepts `httpUrl` / `sseUrl` / `type: "http"` aliases. That leniency is correct for a file the user wrote, and wrong for a third-party package — guessing on behalf of a stranger's `mcp.json` is how you spawn a command the author never wrote.
+
+`zidane/plugins` is the strict layer: closed schemas, immediate-children-only discovery, and a filesystem boundary. It never loosens the existing readers; it wraps them.
+
+## Discovery
+
+Plugins are found in four locations, in precedence order — the same project/user pair every other zidane discovery surface uses:
+
+1. `{project}/.agents/plugins/`
+2. `{project}/.zidane/plugins/`
+3. `~/.agents/plugins/`
+4. `~/.zidane/plugins/`
+
+Each **immediate child directory** is one plugin. Nothing is searched below that, and a child with no `plugin.json` is silently ignored — dropping a README next to your plugins is not an error.
+
+`.agents/plugins/` is the portable location: Agent Plugins is vendor-neutral, so there is no foreign-agent or Ruler import variant the way there is for skills and MCP servers.
+
+Identity is the **manifest** name, not the directory name. Two directories called `tools/` shipping different plugins are two plugins; the same plugin vendored at two scopes is one, and the project copy wins.
+
+Discovered plugins are enabled by default and gated by `enabledPlugins` in settings. A plugin that fails to load still appears — as a read-only row explaining why — rather than vanishing.
+
+### Extra roots for development
+
+`ZIDANE_PLUGIN_DIRS` adds scan roots, mirroring `ZIDANE_EXTENSION_DIRS`:
+
+```sh
+ZIDANE_PLUGIN_DIRS=/repo/plugins zidane
+```
+
+Each entry is a **root** whose immediate children are plugins (`<root>/<name>/plugin.json`), not a single plugin directory. Multiple roots use the platform path delimiter.
+
+This exists because all four default roots are dot-directories and `.zidane/` is gitignored — so a repo has nowhere *tracked* to keep example or first-party plugins. Extra roots are appended **after** the four defaults and scoped `project`, so a real project or user plugin always wins a name collision against a dev root.
+
+This repo uses it to dogfood both load paths in `npm run tui`:
+
+| Plugin | Route | Origin shown |
+| --- | --- | --- |
+| `plugins/hello-plugin` | disk, via `ZIDANE_PLUGIN_DIRS=../plugins` | `[project: plugins/hello-plugin]` |
+| `extensions/plugin-host/vendor/vendored-plugin` | `ctx.loadAgentPlugin` | `[via extension: plugin-host]` |
+
+Their skills (`plugin-smoke-test`, `vendored-smoke-test`) double as the manual verification scripts for plugin loading.
+
+### Project-scope trust
+
+A project plugin's stdio MCP servers run, the same as those in a project `.zidane/mcps.json` beside them. There is no extra gate, deliberately: holding plugins to a stricter rule than the MCP config sitting next to them would be inconsistent rather than safer, since both are things you or your repo placed on purpose.
+
+Stated plainly, the exposure that comes with that: a cloned repo carrying `.agents/plugins/evil/mcp.json` gets its stdio command spawned on the first agent bootstrap. That is today's behavior for project `mcps.json` too. If you don't want it, disable the plugin in settings, or set `enabledPlugins` to an allowlist that omits it.
+
+(The `dropStdio` carve-out in `chat/mcps-discovery.ts` is narrower than it looks — it applies to **Ruler** files specifically, because `importRulerConfigs` defaults on and would otherwise execute a repo-committed foreign config unprompted.)
+
+## Loading a plugin
+
+### From an extension
+
+The primary entry point. One call registers everything the plugin ships:
+
+```ts
+import { defineExtension } from 'zidane'
+
+export default defineExtension({
+  name: 'my-toolkit',
+  capabilities: ['plugins'],
+  async setup(ctx) {
+    const plugin = await ctx.loadAgentPlugin('./vendor/deploy-tools')
+    if (!plugin.ok)
+      ctx.logger.warn('deploy-tools failed to load')
+  },
+})
+```
+
+`dir` may be absolute or relative to the extension's own directory, so an extension can vendor plugins inside itself. Inline extensions (no directory) resolve against `ctx.paths.cwd`.
+
+Options, when you need them:
+
+```ts
+await ctx.loadAgentPlugin({
+  dir: './vendor/deploy-tools',
+  skills: true,        // register skills/          (default true)
+  mcp: true,           // register mcp.json servers (default true)
+  namePrefix: 'acme',  // rename to `acme-<name>`   (default none)
+})
+```
+
+Three things worth knowing:
+
+- **It never throws for plugin-level problems.** A malformed manifest, an escaping symlink or an invalid skill comes back as `ok: false` / diagnostics and is logged to the extension's logger. One bad package cannot fail your `setup()`.
+- **Await it inside `setup()`.** Registration closes when `setup()` resolves. A load still in flight at that point is dropped with a warning rather than mutating an already-published registry.
+- **Components inherit the extension's scope.** A project-scoped extension's plugin is project-scoped, exactly as `ctx.registerSkill` behaves.
+
+### From the SDK
+
+```ts
+import { loadAgentPlugin } from 'zidane/plugins'
+
+const plugin = await loadAgentPlugin(dir, {
+  source: 'user',      // scope stamped on discovered skills (default 'project')
+  skills: true,        // discover skills/          (default true)
+  mcp: true,           // discover mcp.json         (default true)
+  namePrefix: 'acme',  // rename to `acme-<name>`   (default none)
+  dataRoot: '/custom/parent',   // ${PLUGIN_DATA} parent; name is appended
+  dataDir: '/exact/dir',        // or pin one plugin's directory outright
+})
+```
+
+## `plugin.json`
+
+The manifest is a **closed** schema, validated locally — the spec forbids retrieving a schema while loading. `$schema` and `name` are required; everything else is optional metadata.
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "deploy-tools",
+  "version": "1.2.0",
+  "description": "Deployment skills and a release MCP server",
+  "author": { "name": "Acme", "email": "dev@acme.example" },
+  "homepage": "https://acme.example",
+  "repository": "https://github.com/acme/deploy-tools",
+  "license": "MIT",
+  "keywords": ["deploy", "release"],
+  "extensions": { "dev.example": { "anything": true } }
+}
+```
+
+`name` is 1–64 characters: lowercase letters, digits, `-` and `.`, alphanumeric at both ends, no `--` or `..`.
+
+Metadata strings are type-checked only. A `license` that isn't valid SPDX, or a `homepage` that isn't a valid URL, does **not** reject the plugin — the spec keeps identity portable and leaves semantic policing to registries.
+
+Exactly two violations are non-fatal, per spec:
+
+| Violation | Behavior |
+|---|---|
+| Unknown top-level field | Reported, ignored, loading continues |
+| `extensions` is not an object | Reported, ignored, loading continues |
+
+Every other schema violation **rejects the whole plugin**, and rejection happens *before* component discovery — a plugin with a broken manifest never has its skills read or its servers spawned.
+
+`extensions` member *values* are never validated. The spec says to ignore namespaces the client does not implement without inspecting them, so a client validates only its own namespace at the point of use.
+
+## `skills/`
+
+Each immediate child directory containing a `SKILL.md` that resolves to a regular file is one skill. The format is plain [Agent Skills](./SKILL.md) — same parser as `~/.agents/skills`.
+
+Nested descendants are **not** searched. `skills/category/nested/SKILL.md` is invisible, even though zidane's own skill discovery would find it. Bundling a non-skill directory under `skills/` is legal and silently ignored.
+
+Every discovered skill is stamped with `metadata['zidane.plugin']` naming the plugin that shipped it.
+
+## `mcp.json`
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "release": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["release-mcp", "--root", "${PLUGIN_ROOT}"],
+      "env": { "CACHE_DIR": "${PLUGIN_DATA}/cache" },
+      "cwd": "${PLUGIN_ROOT}"
+    },
+    "registry": {
+      "type": "streamable-http",
+      "url": "https://mcp.acme.example/v1",
+      "headers": { "X-Client": "zidane" }
+    }
+  }
+}
+```
+
+`$schema` must declare the **same** Agent Plugins version as `plugin.json`.
+
+`type` is required and never inferred. Each transport has a closed key set:
+
+| `type` | Permitted keys |
+|---|---|
+| `stdio` | `type`, `command`, `args`, `env`, `cwd` |
+| `streamable-http` | `type`, `url`, `headers` |
+| `sse` | `type`, `url`, `headers` |
+
+An unknown field, an unknown transport, or a missing required field invalidates **that one entry**; its siblings still load. A malformed document, a version mismatch, or an unknown top-level field disables the MCP component for that plugin only — its skills are unaffected.
+
+### Plugin variables
+
+Two placeholders, and only two:
+
+| Variable | Value |
+|---|---|
+| `${PLUGIN_ROOT}` | Symlink-resolved plugin root |
+| `${PLUGIN_DATA}` | Dedicated writable directory, persistent across plugin updates |
+
+They expand in `args`, `env` values and `cwd` — **nowhere else**. In `command`, `url` and `headers` the text stays literal, so a `${PLUGIN_ROOT}` in `command` is rejected rather than handed to the OS verbatim.
+
+Expansion is single-pass and non-recursive: an expanded value containing `${PLUGIN_DATA}` does not expand again. Unknown `${...}` text is left alone — zidane's wider `${VAR}` / `${VAR:-default}` / `${env:VAR}` handling does **not** apply to plugin configs (they carry `preExpanded`, which suppresses it). That is deliberate: it keeps an ambient `PLUGIN_ROOT` environment variable from reaching fields the spec says must stay literal.
+
+Both variables are always present in a stdio server's `env`, written last, and a plugin that tries to set either itself has that entry rejected.
+
+`${PLUGIN_DATA}` defaults to `<dataDir>/plugin-data/<plugin-name>/` from `resolveStorageDirs` (honouring `ZIDANE_STORAGE_DIR` and XDG). It sits **outside** the plugin root so a plugin update — which replaces the package tree — cannot wipe it. Extension-loaded plugins get it inside the loading extension's storage root instead, so two extensions loading the same plugin don't share state.
+
+The directory is created at **spawn** time, not load time. Loading is not consent: a host has to load every plugin it finds just to learn its name (identity lives in the manifest, so it can't filter first), and `enabledPlugins` only applies afterwards — creating on load left a directory behind for every plugin the user had switched off, on every discovery pass. A `cwd` inside `${PLUGIN_DATA}` is created along with it, since spawning into a non-existent directory fails with a bare `ENOENT`; a `cwd` under `${PLUGIN_ROOT}` is not, because that path is package content the author was supposed to ship.
+
+Note the honest consequence: `ZIDANE_PREFIX` is *not* read by `resolveStorageDirs` — callers thread `prefix` explicitly, which disk discovery does.
+
+### stdio commands
+
+`command` is exactly one executable token — no shell, no argv splitting:
+
+- **Bare name** (`uvx`, `node`) → PATH lookup by the OS.
+- **`./`-relative** → resolved inside the plugin root, and it must exist.
+- **Absolute** → rejected. It is neither a PATH lookup nor a package file.
+
+`cwd` defaults to the plugin root and must stay inside the root or the data directory, checked both lexically and after symlink resolution.
+
+### Remote servers
+
+- HTTPS required unless the host is loopback.
+- No userinfo credentials, no fragment.
+- Configured headers are pinned to the URL's origin: redirects are followed manually and credentials are dropped the moment a hop leaves that origin. `authorization` is always protected, including the header the SDK's OAuth provider injects rather than reading from config.
+- A redirect to non-loopback cleartext is refused outright, not merely stripped.
+
+## The package boundary
+
+Every package file must stay inside the symlink-resolved plugin root. Lexical checks are not enough — a `skills` symlink pointing at `~/.ssh` passes every one of them — so each path is resolved through `realpath` and re-tested, and required filesystem kinds are asserted.
+
+Failures are isolated at the narrowest level that still holds:
+
+| Problem | Consequence |
+|---|---|
+| Invalid manifest, or manifest outside the root | Whole plugin rejected, no components discovered |
+| `skills/` or `mcp.json` invalid, wrong kind, or outside the root | That component type disabled; the other still loads |
+| One skill invalid, unreadable, or outside the root | That skill skipped; siblings load |
+| One `mcp.json` entry invalid | That server skipped; siblings load |
+| Any other escaping path | Access denied for that path |
+
+A **missing** fixed location is not an error. `components.skills === 'absent'` means the plugin ships no skills; `'invalid'` means they were rejected.
+
+## Results and diagnostics
+
+```ts
+interface LoadedPlugin {
+  ok: boolean                    // false ⇒ plugin rejected, components never discovered
+  dir: string                    // root as requested, made absolute
+  root: string                   // symlink-resolved root — the boundary
+  manifest?: PluginManifest      // absent iff !ok
+  skills: SkillConfig[]
+  mcpServers: McpServerConfig[]
+  components: {
+    skills: 'absent' | 'loaded' | 'invalid' | 'unsupported'
+    mcp: 'absent' | 'loaded' | 'invalid' | 'unsupported'
+  }
+  diagnostics: PluginDiagnostic[]
+}
+```
+
+Each diagnostic carries a `severity`, a stable machine-readable `code` (`manifest-unknown-field`, `skill-escapes-root`, `mcp-entry-transport-invalid`, …), a message, and optionally the `field` or `path` involved. `severity: 'error'` on a plugin that still returned `ok: true` means a narrow boundary fired, not that the plugin failed.
+
+## Naming and collisions
+
+zidane's skill catalog and MCP server names are single flat namespaces, so two plugins each shipping a `deploy` skill or a `github` server would collide. The spec leaves the policy to the client; zidane's default is first-found-wins with a collision diagnostic, plus opt-in `namePrefix` for the cases where you know you're loading several.
+
+Server names are validated in the form they actually take in the tool catalog — `mcp_<server>_<tool>` — which means *after* `namePrefix` is applied, since a bad prefix can invalidate a name the plugin got right.
+
+Collisions are resolved at the merge, not at load, so a plugin's settings row counts what the **package ships** rather than what ended up live. A plugin server whose name matches one in `mcps.json` is dropped (first-wins, `mcps.json` first), and a plugin skill whose name matches an extension's is shadowed. The MCPs and Skills tabs are the authority on what actually loaded; skill collisions emit `name-collision-shadowed`, server collisions are logged under `ZIDANE_DEBUG`. Pass `namePrefix` when loading plugins that might collide.
+
+### The same plugin from both routes
+
+A plugin present *both* on disk and vendored inside an extension is **one** plugin: the disk copy wins, and the extension's copy contributes nothing. One settings row, one checkbox, one set of skills and servers.
+
+This has to hold on the contribution side, not just the display side. If both copies stayed live, that single checkbox would govern two of them, and the skills are the sharp end: both sets reach the catalog, where one shadows the other and earns a `name-collision-shadowed` warning about a collision the user never created.
+
+The MCP half is the same shape but milder — both configs reach the merge, where a first-wins dedupe by name collapses them, so nothing is spawned twice. What's wrong there is that one checkbox nominally governs two records, and which copy survives is decided by merge order rather than by anything the user chose.
+
+Disk wins even when the disk copy is *rejected*, so a broken installed copy doesn't quietly fall back to a vendored one while the row reads `rejected`.
+
+## Settings
+
+Plugins live in the **Extensions & Plugins** tab, interleaved alphabetically with extensions rather than in a separate section. They aren't parallel categories — a plugin can be loaded *by* an extension — so each row carries a kind badge and an origin instead:
+
+```
+[✓] git-flow v2.1.0  ext
+    Git helpers · [project: .zidane/extensions/git-flow]
+[✓] deploy-tools v1.2.0  plugin
+    Deploy skills · [project: .agents/plugins/deploy-tools] · 3 skills, 1 server
+[✓] registry-mcp v0.4.0  plugin
+    Registry access · [via extension: my-toolkit] · 1 server
+✗   broken-thing  plugin
+    rejected: manifest-name-invalid · [user: ~/.agents/plugins/broken-thing]
+```
+
+The kind badge is a filled pill trailing the title line, so names stay left-aligned instead of being pushed right by a fixed-width column. Extensions get the neutral `border` tier because they're the majority — a saturated pill on nearly every row is noise — and plugins get the `model` accent so they stand out of that field.
+
+Both colors derive from `ThemeColors` / `ThemeSurfaces` members every theme must define, rather than from `surfaces.chips` entries: that map is keyed by completion-provider id, and a third-party theme that never opted in would fall back to `chips.default` for both kinds, collapsing the very distinction the badge exists to draw.
+
+Errored extensions and rejected plugins lead the list. A rejected plugin has no checkbox — there is nothing to enable — matching how an errored extension renders.
+
+Searching matches a plugin's name, description and origin, plus the literal word `plugin`: type `plugin` to narrow to plugins, or an extension's name to find the plugins it loaded.
+
+`ctrl+r` on this tab re-scans the plugin directories, so a package you just dropped into `.agents/plugins/` appears without a restart. It refreshes **plugins only** — an extension's `setup()` runs once per process, so extensions genuinely cannot be re-scanned in place, and calling it a generic refresh would over-promise. Extension-loaded plugins likewise only reload with their extension.
+
+Toggling writes `enabledPlugins`, which gates the plugin's skills **and** its MCP servers together — for disk plugins and for extension-loaded ones alike. Extension-loaded plugins need a second filter pass to achieve that (`filterRegistryPlugins`), because their contributions are fanned into the loading extension's own sinks and `enabledExtensions` can only express whole-extension on/off.
+
+Skills from an *enabled* plugin are force-included into `enabledSkills` when you have an allowlist there — enabling the plugin is the consent, and `enabledPlugins` is where you withhold it.
+
+The gate is plugin-level only. A plugin's skills **are** listed in the Skills tab, badged `plugin:<name>`, but they carry no checkbox: the agent build force-includes every enabled plugin's skills, so a per-skill "off" would be persisted, flip the box, and then be overridden on the next build. Rather than ship a control whose off state doesn't hold, the row is read-only and the badge points at the plugin row that owns the switch. Turning off one skill of a plugin means disabling the plugin.
+
+Extension-registered skills work the same way, badged `ext:<name>` and gated by `enabledExtensions`.
+
+Real per-skill control would mean dropping that force-include and seeding contributed skill names into `enabledSkills` at enable time — a persistence change, not a rendering one.
+
+## Conformance
+
+zidane implements Agent Plugins 1.0.0: manifest validation, both component types, both required MCP transports plus legacy HTTP+SSE, plugin variables, and the failure-isolation ladder. Supported versions are listed in `SUPPORTED_AGENT_PLUGINS_VERSIONS`; a plugin targeting anything else is rejected with a diagnostic rather than loaded on a guess.
+
+`test/plugins/conformance.test.ts` maps 1:1 to the [published checklist](https://agent-plugins.org/client-implementers/conformance) — one test per line, same order, same headings. Behavioral depth lives in the sibling suites; that file exists so conformance can be verified item by item instead of inferred from three test files. A checklist line with no test there is a claim nobody checked.
+
+Not yet implemented: installing a plugin from a git/npm spec (`/plugin install`). Drop a package into one of the discovery directories, load it from an extension, or call `loadAgentPlugin` directly.

package/docs/RESTATE.md

@@ -35,6 +35,7 @@ Adapter helpers — pick the ones you need. Pass-through for everything else (`P
 | `restateMcpToolWrap(ctx)` | `mcpToolWrap` hook (DISCOVERED MCP tools) | The MCP analogue of `wrapAgentTools`: journals every discovered MCP tool's result (soft-error-preserving). MCP tools are connected internally, past the public tool-wrapping seam, so the agent applies this on your behalf |
 | `restateToolBatchExecutor({ promises })` | Tool scheduler | Opt-in Restate-native parallel join for concurrency-safe tool fleets |
 | `restateSessionStore(ctx)` | `SessionStore` | Session header + turns + runs as virtual-object K/V state, header timestamps journal-sourced |
+| `restateToolStateStore(ctx)` | `AgentOptions.toolState` | Backs `ToolContext.state` — durable key/value state tools keep across resumes and invocations (see [Durable tool state](#durable-tool-state)) |
 | `restateAwakeableTool(options)` | `ToolDef` | Tool that parks on a Restate awakeable until an external resumer resolves it (human-in-the-loop waits) |
 | `restateWaitBackground(options)` | `ExecutionContext.waitBackground` | Packages the race-safe durable wait for a background task's exit (mint → register-before-probe → already-exited fast-path → park → settle); the host supplies only persistence callbacks |
 | `awakeableWithTimeout(ctx, opts)` | awakeable + `ctx.sleep` | Awakeable raced against a durable timer — resolves the resumer payload, or `null` on deadline. The low-level building block `restateWaitBackground` is built on |
@@ -45,7 +46,7 @@ Adapter helpers — pick the ones you need. Pass-through for everything else (`P
 import * as restate from '@restatedev/restate-sdk'
 import { createAgent } from 'zidane'
 import { anthropic } from 'zidane/providers'
-import { restateBehavior, restateClock, restateProvider, restateSessionStore, wrapAgentTools } from 'zidane/restate'
+import { restateBehavior, restateClock, restateProvider, restateSessionStore, restateToolStateStore, wrapAgentTools } from 'zidane/restate'
 import { createSession } from 'zidane/session'
 import { shell } from 'zidane/tools'
 
@@ -63,6 +64,8 @@ const zidaneAgent = restate.object({
         tools: wrapAgentTools({ shell }, ctx),
         clock: restateClock(ctx),
         session,
+        // Optional — only if your tools use `ctx.state`.
+        toolState: restateToolStateStore(ctx),
         behavior: restateBehavior(),
       })
 
@@ -193,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.
 
@@ -344,6 +349,121 @@ 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**, for two reasons. 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.
+- **A child as its own Restate invocation is not supported.** That's the idiomatic answer for long or genuinely parallel children (own journal, own suspension budget), but it needs a transport for `child:*` hook bubbling and stat rollup across the invocation boundary.
+
+## 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.
+
+`ToolContext.state` is a key/value map that survives replays, suspensions, and whole invocations:
+
+```ts
+const readErrors: ToolDef = {
+  spec: { name: 'read_errors', description: 'Report build errors once', inputSchema },
+  async execute(_input, ctx) {
+    if (ctx.state?.get<boolean>('delivered'))
+      return 'already delivered'
+    ctx.state?.set('delivered', true)
+    return problems
+  },
+}
+
+createAgent({
+  tools: wrapAgentTools({ read_errors: readErrors }, ctx),
+  toolState: restateToolStateStore(ctx),
+})
+```
+
+### The three phases
+
+Reads are synchronous by design. A wrapped tool body runs inside `ctx.run`, and Restate forbids context use in there (no `ctx.get`, no `ctx.sleep`, no nested `ctx.run`) — so the durable I/O happens on either side of the body instead:
+
+| Phase | When | Where |
+|---|---|---|
+| **hydrate** | Once per **agent instance**, before the first tool dispatch | Agent, outside every journaled action — one `ctx.get` |
+| **stage** | Inside the tool body | In memory; `set` / `delete` record ops, they are not written through |
+| **commit** | When the call settles | Loop, outside the journaled action — one `ctx.set` |
+
+The load is memoized on the controller, and the controller is built once in `createAgent` — so a long-lived agent doing many runs loads exactly once. Under Restate that's one agent per invocation and the distinction doesn't bite, but elsewhere it means a resident agent never picks up state another process wrote to the same store out of band. Build a fresh agent (or a fresh controller) per unit of work if you need that.
+
+The invariant that makes it replay-safe: **a staged mutation is committed only if it came back out of a journal entry.** `restateTool` reads the staged ops inside its journaled closure and ships them out as part of the journaled value (`{ __zidaneToolState: 1, ops, output }`), then re-seeds them outside it. On replay the body never runs, the ops come from the journal, and the commit re-issues an identical `ctx.set`. Attempts that produced no journal entry (control error, abort, dead process) have their staged ops dropped — the replay re-runs the body and stages them again.
+
+### Semantics
+
+- **Envelope is conditional.** A call that writes no state journals exactly what it journaled before this feature existed, so in-flight invocations replay unchanged across the deploy. What *does* change the journal shape is configuring `toolState` at all (it adds the run-start `ctx.get`) — drain in-flight invocations before rolling it out.
+- **Commit order is call-index order**, never completion order — including durable fleets joined through `RestatePromise.all()`. Two parallel tools writing the same key would otherwise produce a nondeterministic write sequence.
+- **A write becomes visible when its call commits**, not when it is staged. Views read through to the live snapshot, so a call that runs *after* a sibling committed does see that write (the sequential path `restateBehavior` defaults to reads back the previous call's write). A durable fleet commits only once the whole batch has settled, so calls racing inside one batch never see each other.
+- **Errors still commit.** A soft tool failure journals its sentinel and its delta in the same entry, so the write is honored — live and replay agree.
+- **A store failure drops the write, it doesn't fail the call.** The tool body already ran, so failing the run over a bookkeeping write would be worse than losing it — but losing it silently is worse still, since a dropped one-shot flag re-arms the exact bug this state prevents. A rejecting `commit` fires the `tool-state:commit-failed` hook with the ops that did NOT land (replaying them by hand is a legitimate recovery), and falls back to an unconditional stderr line when nothing is listening; set `handled = true` in your handler to own the reporting. A throwing handler can't take the dispatch path down with it. Make `commit` idempotent and retry inside it if the write matters more than latency.
+- **Oversized values are rejected where they're written.** `ToolStateView.set` enforces a per-value budget (`DEFAULT_MAX_VALUE_BYTES`, 64 KiB of JSON; override with `restateToolStateStore(ctx, { maxValueBytes })`) and throws inside the tool body rather than letting the write fail at commit time. That matters more under Restate than elsewhere: an oversized state value doesn't fail politely, it fails the invocation with `RT0003` (MessageSizeLimit) and retries it under the configured policy — a fat write is a poison pill, not a dropped write. Non-serializable values (cycles, functions) are rejected the same way.
+- **A failing `load` fails the run**, deliberately asymmetric with `commit`: running on an empty snapshot would re-arm the one-shot bugs this state exists to prevent. It throws from `agent.run()` on the normal error path (`errorRun` + `agent:done` still fire), and the memo is cleared so the next run retries.
+- **`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. 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.
+
+### Without Restate
+
+`ToolStateStore` is two methods (`load`, `commit`) and nothing in it is Restate-specific — implement it against Redis, Postgres, or a file for other hosts. With no store configured `ctx.state` is still present and functional, backed by an in-memory map scoped to the agent instance, so a tool written against it behaves identically on the local CLI path and only loses durability.
+
 ## Recommended `AgentBehavior` for Restate deployments
 
 ```ts
@@ -525,7 +645,17 @@ A runtime with a hard per-invocation CPU/wall cap (Cloudflare's ~5-minute limit)
 
 ## Tests
 
-`test/restate.test.ts` covers each wrapper individually + end-to-end agent.run() with the clock + provider in place. A fake `RestateContextLike` records `ctx.run` calls and can be pre-seeded with a journal to verify replay semantics (inner fn not invoked, cached value returned verbatim).
+`test/restate.test.ts` covers each wrapper individually + end-to-end agent.run() with the clock + provider in place. A fake `RestateContextLike` records `ctx.run` calls and can be pre-seeded with a journal to verify replay semantics (inner fn not invoked, cached value returned verbatim). Its `durable tool state` block pairs a recording ctx with a replaying one to assert the live→replay contract end to end: the delta is journaled with the output, replay restores it without entering the body, and the commit is identical.
+
+`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 ten 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.
+
+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.