@arnilo/prism 0.3.2 → 0.5.0

package/docs/migrate-to-0.5.md

@@ -0,0 +1,122 @@
+# Migrate Prism 0.4 to 0.5
+
+> **Status: released 2026-09-06** (`v0.5.0` tag). Covers every host-visible change from plan 055 onward: new provider adapters (055), security hardening (056), the dead-export cut (058), dependency majors (062), the MCP 2026-07-28 adoption (063), the CLI real-provider contract (064), and model-aware thinking effort (065).
+
+## What changes
+
+Prism 0.5 is a **lockstep cut**: all 10 publishable manifests move `0.4.x` → `0.5.0` and internal first-party ranges move `^0.4.0` → `^0.5.0`. Package names and import subpaths from 0.4 stay valid; the breaking surface is (1) 27 removed unused exports, (2) the MCP SDK module move, (3) two thinking-effort wire moves, and (4) two hardening behavior changes. Everything else is additive.
+
+## 1. New provider adapters — additive (plan 055, shipped as 0.4.1)
+
+`@arnilo/prism-providers/hyper` and `@arnilo/prism-providers/commandcode` join the first-party catalog (Hyper with chat + `/v1/responses` passthrough + intelligent-routing metadata; Command Code with dual-route chat/Anthropic-Messages and GPT-5.6 explicit caching). No action needed for existing hosts; both adapters follow the standard provider factory contract (`factory({ apiKey })`).
+
+## 2. Security hardening — behavior changes (plan 056)
+
+- **Tenant-aware store factories:** session/memory/enterprise store factory signatures now require an explicit tenant scope — constructing a durable store without a tenant fails closed. Pass the tenant in the factory options (see the store pages under `docs/`).
+- **Child process env allow-list:** spawned processes (shell default, LSP client, process sessions, computer-use-linux MCP transport) no longer inherit the ambient `process.env`. A deterministic allow-list (`buildChildEnv` / `DEFAULT_CHILD_ENV_INHERIT`, `src/agent/env.ts`) governs inheritance. If you relied on custom env vars reaching child tools, pass them explicitly through the session/spawn options.
+
+## 3. Dead-export removal — 27 symbols (plan 058, breaking)
+
+Every removed symbol was verified unused (zero in-repo references, no third-party import evidence) and carried `@deprecated` "no replacement" earlier in the same cycle. If your code compiled against 0.4 without importing any symbol below, this section does not affect you.
+
+| package | removed export | kind |
+|---|---|---|
+| `@arnilo/prism` | `statusFromState` | function |
+| `@arnilo/prism` | `isInitProvider` | type-guard function |
+| `@arnilo/prism` | `isInitTemplate` | function |
+| `@arnilo/prism` | `parseContextFile` | function |
+| `@arnilo/prism` | `parseToolFile` | function |
+| `@arnilo/prism` | `defaultUserSettingsPath` | function |
+| `@arnilo/prism` | `resolveProviderMediaBlock` | async function |
+| `@arnilo/prism` | `ProviderSecretLeakConformanceOptions` | interface |
+| `@arnilo/prism` | `runToolEffectStoreConformance` | async function |
+| `@arnilo/prism-core` | `OidcIdentityVerifierResult` | type alias |
+| `@arnilo/prism-core` | `assertDiffLines` | function |
+| `@arnilo/prism-core` | `ResolvedPromptLimits` | type alias |
+| `@arnilo/prism-core` | `encodeMetadata` | function |
+| `@arnilo/prism-core` | `parseListOffsetCursor` | function |
+| `@arnilo/prism-core` | `nodeKindOf` | function |
+| `@arnilo/prism-memory` | `DEFAULT_MAX_PROMPT_CHARS` | const |
+| `@arnilo/prism-memory` | `GRAFT_RESOLVE_ERROR_CODE` | const |
+| `@arnilo/prism-memory` | `LinterOptions` | interface |
+| `@arnilo/prism-memory` | `ResolvedGraftExtension` | interface |
+| `@arnilo/prism-memory` | `WikiCategory` | type alias |
+| `@arnilo/prism-coding-tools` | `codingSha256Hex` | function |
+| `@arnilo/prism-coding-tools` | `DEFAULT_MAX_REVIEW_DELTA_ENTRIES` | const |
+| `@arnilo/prism-coding-tools` | `HARD_MAX_REVIEW_DELTA_ENTRIES` | const |
+| `@arnilo/prism-coding-tools` | `indexErrorCode` | function |
+| `@arnilo/prism-coding-tools` | `PONYTAIL_PEER_RANGE` | const |
+| `@arnilo/prism-coding-tools` | `CavemanSkillName` | type alias |
+| `@arnilo/prism-providers` | `withOpenRouterCacheMarker` | function |
+
+Per-symbol local replacements for the two cases where 0.4 docs showed a usage pattern:
+
+- `defaultUserSettingsPath(appName)` → build the path with stdlib:
+  `join(homedir(), ".config", appName, "settings.json")` (see
+  [`docs/settings-auth-trust-security.md`](settings-auth-trust-security.md)).
+- `parseContextFile` / `parseToolFile` → colocated `CONTEXT.md` / tool-descriptor parsing is
+  host-owned; parse frontmatter with `parseAgentFile` (kept) plus your own file reading
+  (see [`docs/agent-definitions.md`](agent-definitions.md)).
+
+## 4. Dependency majors (plan 062)
+
+- **`pdf-parse` 1.1 → 2.4** (`@arnilo/prism-coding-tools` optional peer): v2 parses in a worker thread and transfers the `data` TypedArray — do not reuse the buffer after `extract`; requires Node ≥ 20.16 (repo engines already `>=20`). Embedded-script execution is hard-disabled (`isEvalSupported: false`). Extracted text is byte-identical to v1 modulo trailing newline.
+- **`better-sqlite3` 12 → 13** (`@arnilo/prism-core` optional peer): N-API rewrite with bundled prebuilt binaries (no per-Node rebuild); unsupported platforms compile from source during install. No API removals.
+- **`@napi-rs/keyring` 1.x → 2.0** (`@arnilo/prism-core`): locked/inaccessible keychain reads and deletes now **reject** with typed errors (`CredentialStoreLockedError`, `CredentialStoreUnavailableError`) instead of silently resolving `undefined`/`false`. A missing credential still resolves `undefined`. If you treated a locked keychain as an empty vault, handle the typed errors.
+
+## 5. MCP: TypeScript SDK v2 modular adoption (plan 063, breaking for MCP hosts)
+
+`@arnilo/prism-mcp` replaces the monolithic `@modelcontextprotocol/sdk` 1.30.0 with the modular v2 packages (`@modelcontextprotocol/client` + `@modelcontextprotocol/server` 2.0.0 exact pins). Prism's public surface (`createPrismMcpServer`, `createPrismMcpWebHandler`) keeps its shape; hosts that imported SDK types directly must move to the v2 module imports. Highlights: modern client negotiation, SDK-managed routing headers (SEP-2243), MRTR-compatible elicitation, dual-era HTTP/stdio serving, 2026-07-28-conformant OAuth (issuer-keyed storage, RFC 9207 `iss` validation). Draft-era task vocabulary fails closed. Full migration table + legacy-session timeline: [`docs/migration.md`](migration.md), canonical API in [`docs/mcp-tools.md`](mcp-tools.md).
+
+## 6. CLI real-provider contract (plan 064)
+
+`prism --provider <id>` runs real providers: ids resolve through the init provider catalog (`templates/init/providers.json`), the factory is imported from the installed `@arnilo/prism-providers/*` package, and the credential comes from the catalog's env var. `--mode print|json|rpc` all honor it. **Contract change:** omitting `--provider` fails with a usage error (exit 2) — the mock provider runs only on explicit `--provider mock`. The RPC session factory is async-capable (`AgentSession | Promise<AgentSession>`).
+
+## 7. Model-aware thinking effort (plan 065, two wire moves)
+
+Thinking/reasoning effort is now model-aware, declared, and snapped: every reasoning-capable model in a first-party catalog declares `capabilities.thinkingLevels` and a `compat.thinkingFamily` stamp, and one adapter resolves, snaps, and merges the level.
+
+Breaking / behavior changes:
+
+1. **Anthropic Messages: `effort` → `output_config.effort`.** Prism emits `output_config: { effort }` (the `output_config_effort` family). Hosts hand-building `compat.effort` / `compat.reasoning_effort` keep working (resolver reads the aliases); hosts *reading* emitted bodies must look at `output_config.effort`. Thinking is generation-aware: 4.6+ models map bare `enabled` to `adaptive`; legacy 4.5 models get `enabled` + `budget_tokens` default 10000 (bare `enabled` without a budget is rejected upstream).
+2. **xAI now sends `reasoning_effort`** (previously dropped): grok-4.6 `low/medium/high/xhigh`, grok-4.5 `low/medium/high`, grok-4.3 `none/low/medium/high`; out-of-set values snap. `grok-build` and unknown models pass through verbatim. `reasoning_content` replay is unchanged.
+3. **Snapping replaces silent drop** on declared models: out-of-set portable levels snap to the nearest declared level (ladder distance, ties up; below-minimum snaps up). Provider-documented tables (DeepSeek, Z.AI GLM-5.2/5.3, Kimi K3, ClinePass slot maps) remain wire authority. Opaque strings on reasoning-capable models still pass through.
+4. **Azure / Vertex / Bedrock forward thinking compat** through a sanitized forwarder (`reasoning_effort` + aliases, or `reasoning` object with `summary` preserved). Unrecognized compat keys are dropped, not leaked. Hand-built `options.extra` workarounds can become `compat`.
+
+New surface on `@arnilo/prism`:
+
+| Export | Purpose |
+|---|---|
+| `applyThinkingLevelForModel(base, level, model)` | One-call adapter: family resolution + snap + merge — prefer over `applyThinkingLevel` |
+| `parseThinkingLevel(value)` | Known level → canonical; other string → opaque passthrough; empty/non-string → `undefined` (fail closed) |
+| `isSupportedThinkingLevel(model, level)` | Is the level in the model's declared set |
+| `thinkingLevelsForModel(model)` | Declared set or `undefined` |
+| `snapThinkingLevel(model, level)` | Snap to the declared set (nearest, ties up) |
+
+New compat families: `google` (`{ thinkingLevel }`) and `output_config_effort` (`{ output_config: { effort } }`). Family inference is stamp-first via `compat.thinkingFamily`.
+
+What to do:
+
+1. Replace `applyThinkingLevel(base, level, family)` call sites with `applyThinkingLevelForModel(base, level, model)`.
+2. Gate level pickers on `model.capabilities?.thinkingLevels` when present.
+3. Update any body assertion reading Anthropic top-level `effort` to `output_config.effort`.
+4. Remove xAI "never send reasoning_effort" workarounds.
+5. Nothing else: `mergeProviderRequestOptions`, `RunOptions`, and persisted shapes are unchanged.
+
+Contract reference: [`docs/thinking-and-reasoning.md`](thinking-and-reasoning.md); per-provider declared levels + wire fields on each `docs/providers/*.md` page.
+
+## Upgrade steps
+
+1. Bump every `@arnilo/*` dependency/peer to `^0.5.0`.
+2. Build; if the compiler flags a removed symbol above, apply the replacement from the table.
+3. If you host MCP: move SDK imports to the v2 modular packages (section 5).
+4. If you spawn child processes with ambient env: pass env explicitly (section 2).
+5. If you construct durable stores: pass the tenant scope (section 2).
+6. If you set thinking levels: move to `applyThinkingLevelForModel` (section 7).
+7. Run your suite. No persisted-data migration exists or is needed.
+
+## Rollback
+
+Pin the previous version: `@arnilo/prism@0.4.x` (exact pins per package). Nothing persisted
+changes under 0.5, so a pin rollback is safe. The MCP module move (section 5) is the only
+migration that touches host import code — keep a 0.4 pin if you need the monolithic SDK.

package/docs/migration.md

@@ -1,5 +1,31 @@
 # Migration guide
 
+## 0.4.x → 0.5.0 lockstep cut (breaking)
+
+Prism 0.5 (plans 055–065) ships four breaking surfaces: the 27 removed unused exports from the plan 058 sweep (symbol-surface only), the MCP TypeScript SDK v2 module move (plan 063 — hosts importing `@modelcontextprotocol/sdk` directly must move to the modular `client`/`server` 2.0.0 packages), the thinking-effort wire moves (plan 065 — Anthropic `effort` → `output_config.effort`, xAI `reasoning_effort` now sent, snap-on-declared semantics), and the plan 056 hardening behavior changes (tenant-scoped store factories, child env allow-list). Dependency majors (plan 062: pdf-parse 2.4 with Node ≥ 20.16, better-sqlite3 13, keyring 2 with typed locked-store errors) and the CLI real-provider contract (plan 064: explicit `--provider` required, exit 2 when omitted) are behavior changes without import impact. See the complete guide with per-symbol replacements and upgrade steps in [migrate-to-0.5.md](migrate-to-0.5.md). All 10 publishable manifests bump to `0.5.0` lockstep; internal first-party ranges move `^0.4.0` → `^0.5.0`. Security keeper surface (ownership/checkpoint guards, `secureCompare`, `zeroBuffer`, sandbox path-escape guard, RAG scope guard, MCP content-bounds guard, secret-leak conformance assert) is unchanged.
+
+## 0.3.3 → 0.4.0 package reorganization (breaking)
+
+Prism 0.4 consolidates package names into explicit family subpaths. It is a dependency and import-specifier migration, not a persisted-data migration. See the complete [legacy 0.3 → 0.4 guide](migrate-to-0.4.md) for all 54 retired package mappings, profile replacements, optional peers/host binaries, security checks, rollback, and npm legacy-warning behavior.
+
+## 0.3.1 → 0.3.2: bounded workflow loop durability (additive, no migration)
+
+`@arnilo/prism-workflows@0.3.2` adds the bounded `loopNode` durable extension. It adds optional `WorkflowNodeCheckpoint.iterations` records, each carrying `schemaVersion: 1`, a zero-based `iteration`, stable `iterationId`, and bounded/redacted output. Existing `WorkflowCheckpointValue.schemaVersion` remains `1`; older checkpoints without `iterations` remain readable through the legacy `iteration`/`lastOutput` cursor, and older hosts ignore the additive field. No SQL or generic checkpoint-store migration is required. Replay creates a new run and never mutates source iteration evidence. Hosts using saga compensation keep one saga step/aggregate and register per-iteration compensation by `iterationId` in reverse order.
+
+This independent package patch freezes budget accounting: `maxNodes` counts declared DAG nodes once, while loop body executions consume only the required hard-capped `maxIterations` budget. Rollback is package-version rollback; no persisted migration is needed.
+
+## 0.3.2 → 0.3.3: run-ledger prompt provenance (additive, schema version 9)
+
+Plan 042 adds an optional typed `promptVersion` ref (`{ name, version, hash }`) to `RunOptions` and `RunRecord`. Hosts resolve a prompt from `@arnilo/prism-prompts` and stamp the run: the ref is copied onto the start/finish ledger records and persisted by the first-party SQLite/PostgreSQL stores as a nullable `prompt_version` JSON column (shared schema migration `009_run_prompt_version`, schema version 8 → 9, forward-only and applied automatically by the adapters' checksummed `prism_migrations`). Strictly additive: unset `promptVersion` produces byte-identical rows and records, legacy rows read back without the field, and no exported declaration was removed. The ref carries identity only (`sha256:` body hash) — prompt bodies stay in the separate `@arnilo/prism-prompts` tables and out of run rows, metadata, and telemetry.
+
+## 0.3.2 → 0.3.3: tool progressive disclosure (additive, no migration)
+
+Plan 041 adds opt-in progressive tool loading to `@arnilo/prism`: `toolsDisclosure` (default `"all"`, byte-identical to previous releases) and `toolsSearch.topK` on `AgentConfig` / `RunOptions`, plus the generated `search_tools` tool in search mode. Strictly additive — no exported declaration removed, no persisted shape repurposed. Durable run state gains an optional `sessionState.activatedToolNames` (names only, capped at 128); stores that ignore it resume exactly as before. Set nothing and behavior is unchanged; see [Tools](tools.md#tool-disclosure-progressive-tool-loading).
+
+## 0.3.1 → 0.3.2 memory package: composite recall scoring (additive, no migration)
+
+`@arnilo/prism-memory@0.3.2` adds opt-in `RecallOptions.scoring`: sum-normalized similarity/recency/importance blending, with a positive `halfLifeMs` required only when `recencyWeight > 0`. Default recall (no `scoring`) keeps its existing ordering and query count. `MemoryVectorRecord.importance?` persists through an additive nullable `importance REAL` column (`ADD COLUMN IF NOT EXISTS`); legacy NULL rows score neutral `1.0`, so no re-index or data migration is required. At write, hosts may pass a clamped `[0,1]` `entry.importance` or an `importanceFrom` hook over a redacted reflection; it runs once at write, never at recall. Rollback is package-version rollback only: old readers ignore the nullable column, and new readers treat absent values neutrally.
+
 ## 0.3.0 → 0.3.1 production RAG engine (independent patch)
 
 Only `@arnilo/prism-rag`, `@arnilo/prism-memory`, and `@arnilo/prism-observability-opentelemetry` move to `0.3.1`. Keep every other first-party package on `^0.3.0` — those ranges already satisfy `0.3.1`.
@@ -796,7 +822,31 @@ Existing text `createA2AHandler({ exposure })`, `client.send()`, and `client.str
 
 ## 0.0.7 → 0.0.8 MCP capabilities and sessions
 
-`@arnilo/prism-mcp` now pins official SDK 1.29.0. Existing `connectMcpTools()` and stateless web handlers remain compatible. Use `connectMcpCapabilities()` for bounded resources/prompts and explicit roots/sampling/elicitation callbacks. Server resources/prompts must be selected explicitly and authorize every operation. Stateful Streamable HTTP additionally requires `sessionIdGenerator`, exact `allowedOrigins`, and host `resolveIdentity`; omission preserves stateless mode. `Last-Event-ID` replay is not enabled. Missing capability calls fail with `ERR_PRISM_MCP_UNSUPPORTED_CAPABILITY`.
+`@arnilo/prism-mcp` now pins the modular TypeScript SDK v2 packages (`@modelcontextprotocol/client` + `@modelcontextprotocol/server` 2.0.0). Existing `connectMcpTools()` and stateless web handlers remain compatible. Use `connectMcpCapabilities()` for bounded resources/prompts and explicit callbacks. **Roots (`roots`) and sampling (`sampling`) callbacks are deprecated with protocol revision 2026-07-28 (SEP-2577)** and kept for existing legacy callers only — migrate server-hosted state to explicit tool arguments and host-side model calls; elicitation is the active capability and works across eras (legacy direct `elicitation/create` dispatch, or SDK MRTR `input_required` auto-fulfilment on the modern era, capped by `maxMrtrRounds` with the call timeout as the outer ceiling). Server resources/prompts must be selected explicitly and authorize every operation.
+
+HTTP/stdio serving is dual-era: `createPrismMcpWebHandler(factory)` now serves modern 2026-07-28 traffic through SDK `createMcpHandler` (one fresh `McpServer` per request, no `Mcp-Session-Id`, no sticky routing) with the SDK stateless fallback for 2025 traffic, and stays callable while gaining `fetch`/`close`/`notify`/`bus`. Host/origin allowlists are enforced by Prism before body parsing and auth (the SDK entry provides no validation); `maxRequestBytes`, response bounding, concurrency, and request timeouts are unchanged. Configuring `sessionIdGenerator` keeps legacy sessionful serving (identity-bound POST/GET/DELETE/SSE) beside a strict modern handler; a bare `McpServer` instance with sessions is legacy-only — pass a factory for dual-era serving. `servePrismMcpStdio(factory, options)` replaces hand-wired stdio serving with SDK dual-era `serveStdio` (era pinned by the opening exchange, stdout protocol-only). Stateful Streamable HTTP still requires `sessionIdGenerator`, exact `allowedOrigins`, and host `resolveIdentity`. `Last-Event-ID` replay is not enabled. Missing capability calls fail with `ERR_PRISM_MCP_UNSUPPORTED_CAPABILITY`.
+
+OAuth client behavior is 2026-07-28 conformant: `finishAuth` now takes the full callback `URLSearchParams` (persisted `state` validated fail-closed, RFC 9207 `iss` checked before the code is redeemed; the bare-code string form remains as the unvalidated legacy path — switch to the params form). Persisted token/client records are SDK issuer-stamped; `McpClientAuthState` credential methods take the validated `issuer` (existing implementations ignoring the parameter keep working for single-server hosts, but **un-stamped pre-upgrade records are refused on issuer-keyed reads** rather than guessed — hosts see one interactive re-authorization, after which every record is stamped). CIMD (SEP-991) is the preferred registration strategy, `dcr` is `@deprecated` with `application_type` defaulting to `"native"`, and `onInsufficientScope: "reauthorize" | "throw"` makes the 403 step-up policy explicit. Server 401 challenges now include the configured `scope`; host token verifiers must validate the token audience.
+
+### Monolithic SDK 1.x → modular SDK v2 migration table
+
+| v1 (`@modelcontextprotocol/sdk` 1.30.0) | v2 / current Synapta API | Notes |
+| --- | --- | --- |
+| `new Client(...)` from `sdk/client/index.js` | same name from `@modelcontextprotocol/client` | `ClientOptions` gains `versionNegotiation`, `listChanged`, `inputRequired`, `cachePartition`, `listMaxPages` |
+| `InMemoryTransport` / `StdioClientTransport` / `StreamableHTTPClientTransport` | `InMemoryTransport`/`StreamableHTTPClientTransport` from `@modelcontextprotocol/client`; `StdioClientTransport` from `@modelcontextprotocol/client/stdio` | subpath moves only |
+| `McpServer`, `WebStandardStreamableHTTPServerTransport` from `sdk/server/*` | `@modelcontextprotocol/server` root | `createMcpHandler` (dual-era HTTP) + `serveStdio` (dual-era stdio) replace hand-wired serving |
+| `client.request({method}, Schema, options)` | method-keyed `client.request(...)` or high-level `listTools`/`listResources`/`readResource`/`callTool` | per-page list walks must send an explicit cursor (`{cursor: ""}` on page 0) — the no-cursor form is the SDK's uncapped aggregate |
+| `CompatibilityCallToolResultSchema` (`toolResult` member) | gone from the client codec; `callTool` decodes `CallToolResult` only | draft-era `task` members fail closed at the bridge |
+| `server.setRequestHandler(Schema, handler)` | `setRequestHandler("method/string", handler)` with `ctx.mcpReq.{id,signal}` | `ctx.authInfo` moved to `ctx.http?.authInfo`; unknown tools now error (`-32602`) instead of `isError` results |
+| `sdk/server/auth/types.js` `AuthInfo` | `AuthInfo` from `@modelcontextprotocol/server` | type-only move |
+| `OAuthClientProvider` (string-keyed persistence) | issuer-keyed `StoredOAuthTokens`/`StoredOAuthClientInformation` + optional `ctx: {issuer}` params, `clientMetadataUrl` (CIMD) | see the OAuth paragraph above |
+| `LATEST_PROTOCOL_VERSION` mock fixtures (initialize results) | legacy-era negotiation unchanged; modern (2026-07-28) results need top-level `resultType: "complete"`, `ttlMs`, `cacheScope` | raw mock fixtures only |
+
+### Legacy-session timeline
+
+- **Now (default):** `createPrismMcpWebHandler(factory)` without `sessionIdGenerator` is stateless dual-era — modern 2026-07-28 serving plus the SDK stateless fallback for 2025 clients. No `Mcp-Session-Id`, no sticky routing, `Last-Event-ID` replay not enabled.
+- **Now (opt-in):** configuring `sessionIdGenerator` keeps identity-bound legacy sessions (POST/GET/DELETE/SSE beside the strict modern handler) for hosts that still need them; the pairing requires exact `allowedOrigins` and host `resolveIdentity`.
+- **Planned removal:** the legacy session leg is deprecated once Synapta's clients and documented hosts are modern-era; removal lands as a breaking 0.x cut with a migration note here (the `sessionIdGenerator` option disappears and legacy traffic gets the SDK stateless fallback, which 2025 clients already work against). No date is committed in this release.
 
 ## 0.0.7 → 0.0.8 OpenTelemetry adapter
 

package/docs/model-registry.md

@@ -107,14 +107,51 @@ Provider packages register models through `ProviderPackageAPI.registerModel(mode
 
 `ModelConfig.compat` remains for provider-owned inert JSON. Prefer typed fields (`capabilities`, `limits`, `cost`, `cache`) for generic behavior shared across providers.
 
+### Model-list/capability discovery with provenance
+
+`ModelDiscovery` (plan 062) is the normalized `listModels()` seam: it returns the existing `ModelConfig` contract verbatim (id = `model`, context window = `limits`, pricing hint = `cost`) plus `provenance` (`provider`, `fetchedAt` ISO timestamp, `source: "api" | "catalog"`, and `ttlMs` cache guidance). Discovery execution stays provider/host code — Prism core ships only the result types; adapters live in `@arnilo/prism-providers/model-discovery`:
+
+```ts
+import { createOpenAiCompatibleModelDiscovery, createGoogleModelDiscovery, createFakeModelDiscovery, runModelDiscoveryConformance } from "@arnilo/prism-providers/model-discovery";
+
+const discovery = createOpenAiCompatibleModelDiscovery({
+  baseUrl: "https://gw.internal/v1", // GET <baseUrl>/models
+  apiKey, // CredentialValueSource — sent as Bearer, resolved via the existing credential seam
+  catalog: registry.list(), // host overrides merged by model id; catalog fields win
+});
+const { models, provenance } = await discovery.listModels({ ttlMs: 3_600_000 });
+
+// Independent provider: Google Gemini `GET <baseUrl>/v1beta/models` (x-goog-api-key), paginated:
+const google = createGoogleModelDiscovery({ apiKey: gcpKey });
+
+// Network-free fake + conformance for any ModelDiscovery implementation:
+await runModelDiscoveryConformance(() => createFakeModelDiscovery());
+```
+
+- Passthrough normalization: entries the provider does not describe stay bare (`{provider, model}`); there is no hard-coded catalog in core or adapters. Hosts merge catalog overrides (`capabilities`/`limits`/`cost`/`displayName`) over normalized entries by model id via the `catalog` option.
+- Results cache per discovery instance within the configured TTL (default 3,600,000 ms). `listModels()` in loops performs no network until the TTL expires; `ttlMs: 0` forces a refresh. The provenance `fetchedAt`/`ttlMs` fields let hosts layer their own caching on top.
+- `ModelDiscoveryError` is the typed failure (provider label + HTTP status); credentials are resolved through the existing `CredentialValueSource` seam, redacted from every error message, and responses are byte-bounded through the shared provider transport.
+
 ## Security and performance notes
 
 - Model metadata must not contain credentials or secrets.
 - Declare truthful `capabilities.input` tags. Prism core rejects undeclared modalities in `assembleProviderInput()` when the list is present.
 - Registration is in-memory and O(1) by provider/model key.
 - `ModelConfig.cache` is declarative capability info only; it does not grant permissions, select tools, or bypass auth.
+- Model-discovery listings are untrusted metadata: normalized entries carry no tool authority, cached results stay per discovery instance (no cross-provider cache bleed), and discovery requests reuse the bounded transport with credential redaction. Catalog overrides come from host-owned registries only — provider responses never write into the host's `ModelRegistry` without host code in between.
 - Provider-specific behavior belongs in provider packages, not Prism core.
 
+## Live probe (discovery adapters)
+
+The `@arnilo/prism-providers/model-discovery` adapters have an opt-in live leg that runs `runModelDiscoveryConformance` against a real listing endpoint:
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 OPENAI_API_KEY=...   # or GEMINI_API_KEY for the Google route
+node --test packages/prism-providers/dist/model-discovery/__tests__/live.test.js
+```
+
+Chooses the OpenAI-compatible or Google route based on which key is present; neither → skip.
+
 ## Related APIs
 
 - [Multimodal content](multimodal-content.md): `audio`/`file`/`document` blocks and `MODEL_INPUT_CAPABILITIES`.
@@ -122,3 +159,4 @@ Provider packages register models through `ProviderPackageAPI.registerModel(mode
 - [Provider caching](provider-caching.md): `ModelCacheCapabilities` and cache helpers.
 - [Provider packages](provider-packages.md): package registration of model metadata.
 - [Public contracts](public-contracts.md): `ModelConfig`, `ModelCost`, and cache type contracts.
+- [Provider layer](provider-layer.md): `ModelDiscovery` adapters, provenance, and TTL semantics.

package/docs/model-routing.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-model-router` is an optional governance facade over an existing `ProviderResolver`. It enforces allow-lists, residency, token/cost budgets, rate limits, circuit breaking, and bounded fallbacks before provider selection, and emits redacted selection diagnostics. It does not implement a second provider runtime.
+`@arnilo/prism-core/governance/model-router` is an optional governance facade over an existing `ProviderResolver`. It enforces allow-lists, residency, token/cost budgets, rate limits, circuit breaking, and bounded fallbacks before provider selection, and emits redacted selection diagnostics. It does not implement a second provider runtime.
 
 ## When to use it
 
@@ -57,8 +57,8 @@ Frozen caps (default / hard): attempts `3 / 8`, circuit keys `1,024 / 16,384`, d
 
 ```ts
 import { createAgent, createProviderResolver } from "@arnilo/prism";
-import { createModelRouter } from "@arnilo/prism-model-router";
-import { createPostgresEnterpriseState } from "@arnilo/prism-enterprise-postgres";
+import { createModelRouter } from "@arnilo/prism-core/governance/model-router";
+import { createPostgresEnterpriseState } from "@arnilo/prism-core/enterprise/postgres";
 
 const enterprise = await createPostgresEnterpriseState({ pool, schema: "prism" });
 const router = createModelRouter({
@@ -91,7 +91,7 @@ await enterprise.close();
 
 ## Extension and configuration notes
 
-Router is optional. Chain returned `providerRequestPolicy` with other `ProviderRequestPolicy` values. Wire `onDiagnostics` to `@arnilo/prism-policy` when audit export is required. OpenRouter package behavior is unchanged; routing metadata participates only when this gate allows it.
+Router is optional. Chain returned `providerRequestPolicy` with other `ProviderRequestPolicy` values. Wire `onDiagnostics` to `@arnilo/prism-core/governance/policy` when audit export is required. OpenRouter package behavior is unchanged; routing metadata participates only when this gate allows it.
 
 ### Selection policies (0.1.7)
 
@@ -100,7 +100,7 @@ By default the router tries candidates in input order: the primary model, then
 `createModelRouter` to rank the candidates before the governance checks run:
 
 ```ts
-import { createCostLatencySelection, createModelRouter } from "@arnilo/prism-model-router";
+import { createCostLatencySelection, createModelRouter } from "@arnilo/prism-core/governance/model-router";
 
 const router = createModelRouter({
   resolver,
@@ -156,4 +156,4 @@ await router.recordOutcome({ identity, provider, model, success: true, latencyMs
 - [Policy and audit](policy-and-audit.md)
 - [Agent identity](agent-identity.md)
 - [Enterprise PostgreSQL state](enterprise-postgres-state.md): durable router state, migration, cleanup, and ownership requirements.
-- Package README: [`@arnilo/prism-model-router`](../packages/model-router/README.md)
+- Package README: [`@arnilo/prism-core`](../packages/prism-core/README.md)

package/docs/moderation.md

@@ -0,0 +1,117 @@
+# Moderation
+
+## What it does
+
+`ModerationProvider` is the provider-neutral content-classification contract:
+`moderate({ input })` sends text to a provider classifier and returns per-category
+`{ score, flagged }` verdicts keyed by a provider-neutral vocabulary (plan 061
+Task 6). Raw provider category/score fields ride along unmodified as `raw` for
+host-side audits. Scores and flagged booleans are **provider output** — core
+bakes in no policy: thresholds, blocking, and routing stay host-owned
+([host security](host-security.md)). The first-party adapter is
+[`createOpenAIModerationProvider`](providers/openai.md) (`POST /v1/moderations`,
+`omni-moderation-latest`); offline conformance runs via
+`runModerationConformance` from `@arnilo/prism/testing/provider-conformance`.
+
+## When to use it
+
+Use it when a host or guardrail seam wants pre-flight or post-hoc text
+classification from a vendor classifier with portable category names. Do not use
+it for local policy enforcement — Prism core never decides what is blocked;
+hosts read `flagged`/`score` and apply their own thresholds.
+
+## Inputs / request
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `input` | `string \| readonly string[]` | One input per call, or a batch (results match input arity and order). |
+| `model` | `string?` | Classification model; adapter default `omni-moderation-latest`. |
+| `signal` | `AbortSignal?` | Cancellation. |
+
+Adapter options: `apiKey` (`CredentialValueSource` — resolved per call, redacted
+from errors), `baseUrl`, `fetch` (fake transport for offline tests), `headers`,
+`model`. Input caps reject typed before network I/O
+(`OPENAI_MODERATION_INPUT_MAX_CHARS`, 100,000 chars — no provider-documented limit,
+conservative ceiling).
+
+## Outputs / response / events
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `flagged` | `boolean` | Provider's own top-level decision, verbatim. |
+| `categories` | `Record<string, { score, flagged }>` | Verdicts keyed by the neutral vocabulary (see below); unknown raw categories pass through untouched. |
+| `categories[k].score` | `number` | Provider-reported score in [0,1] — never locally recomputed. |
+| `raw` | `JsonObject?` | Provider-native response fields for audits. |
+
+Neutral category vocabulary (`MODERATION_CATEGORIES`): `harassment`,
+`harassment/threatening`, `hate`, `hate/threatening`, `illicit`,
+`illicit/violent`, `self-harm`, `self-harm/instructions`, `self-harm/intent`,
+`sexual`, `sexual/minors`, `violence`, `violence/graphic`. The OpenAI adapter
+maps via a data-driven table; vendor categories missing from the table surface
+under their raw names so no provider signal is dropped.
+
+Failures throw `ModerationError` with a stable `code`: `empty_input`,
+`input_too_large`, `unsupported_model` (via `assertModerationSupported` when the
+host checks `ModelCapabilities.moderation`), `request_failed` (non-2xx,
+secret-redacted), `response_malformed` (missing `results`, non-numeric scores
+downstream).
+
+## Request/response example
+
+```json
+{ "model": "omni-moderation-latest", "input": "text to classify" }
+```
+
+## Implementation example
+
+```ts
+import { createOpenAIModerationProvider } from "@arnilo/prism-providers/openai";
+import { runModerationConformance } from "@arnilo/prism/testing/provider-conformance";
+
+const moderation = createOpenAIModerationProvider({ apiKey: process.env.OPENAI_API_KEY });
+const result = await moderation.moderate({ input: text });
+// Host-owned policy — Prism applies no thresholds:
+if (result.categories.violence?.score ?? 0 > myPolicy.violenceCutoff) { ... }
+
+// Batch where the provider allows it (arity- and order-preserving):
+const batch = await moderation.moderate({ input: ["first", "second"] });
+
+// Offline conformance (fake transport, no network):
+await runModerationConformance({
+  provider: createOpenAIModerationProvider({ apiKey: "sk-test", fetch: fakeFetch }),
+  model: "omni-moderation-latest",
+  maxInputChars: 100_000,
+  sample: { input: "conformance probe" },
+});
+```
+
+## Extension and configuration notes
+
+- Implement `ModerationProvider` for other vendors; the contract is structural —
+  no base class, no registry. Keep the data-driven category table per provider;
+  never hard-code category logic in call paths.
+- Models declare support with `capabilities.moderation`; hosts gate with
+  `modelSupportsModeration` / `assertModerationSupported`, mirroring the
+  embeddings/speech/image/video guard pattern.
+- Guardrail seams consume the contract at the host layer: wire `moderate()`
+  into request/output inspection stages; core stays policy-free by design.
+
+## Security and performance notes
+
+- API keys resolve through the existing `CredentialValueSource` seam and are
+  redacted from every thrown error; no new secret paths.
+- Classification responses are read through the bounded JSON reader
+  (`OPENAI_MODERATION_MAX_RESPONSE_BYTES`, 8 MiB) — oversized payloads reject
+  instead of buffering.
+- One provider request per input; batch inputs loop the same bounded path.
+- Inputs, verdicts, and raw payloads are never logged by core; error messages
+  carry status and a redacted body only.
+
+## Related APIs
+
+- [Host security](host-security.md): policy ownership — thresholds and blocking
+  stay host-side.
+- [Provider conformance](provider-conformance.md): `runModerationConformance`
+  and the offline conformance matrix.
+- [Provider packages](provider-packages.md): subpath import rules for
+  `@arnilo/prism-providers/openai`.

package/docs/multi-agent-patterns.md

@@ -0,0 +1,177 @@
+# Multi-agent patterns: handoff, hierarchical crew, supervisor delegation, A2A
+
+## What it does
+
+Maps the four Prism answers for "more than one agent" onto one decision table. All four compose existing seams — none introduces a new runtime:
+
+- **In-session handoff (swarm)** — agent A transfers control of the ongoing conversation to agent B by calling a host-built `handoff` tool; the host resolves the target `AgentDefinition` with `resolveAgentDefinition` and opens the specialist against the same session (same store + session id, previous run's `leafId`). One transcript, no new session. No helper primitive ships; the tool factory lives in [`examples/handoff-swarm.ts`](../examples/handoff-swarm.ts).
+- **Hierarchical crew** — a manager agent decomposes a goal into typed tasks (`{ tasks: [{ role, instruction }] }`) via structured output ([`Artifact*`](structured-output.md)), fans out to parallel role specialists with bounded `maxFanOut` ([`fanOutNode`](workflows.md)), aggregates deliverables with host reduce ([`joinNode`](workflows.md)), and validates outputs with conditional routing to completion or revision ([`conditionalNode`](workflows.md)). The entire process is a deterministic DAG workflow with zero new runtime primitives. Live demo in [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts).
+- **Supervisor delegation** — `@arnilo/prism-core/runtime/supervisor` `delegate()` invokes allow-listed child agents as bounded runs and returns their result to the parent. Separate child transcripts, hooks, budgets, narrowing.
+- **A2A 1.0** — cross-service interop over the JSON-RPC/HTTPS binding; the remote peer's lifecycle is host-owned behind `A2ATaskLifecycle`.
+
+## When to use it
+
+| Pattern | Use when | Conversation boundary | Ownership / identity | Telemetry |
+| --- | --- | --- | --- | --- |
+| In-session handoff | One host, one ongoing conversation; the model decides **when** to transfer; specialists are alternate definitions of the same app | One continuous transcript chain (same store, session id, `leafId`) | Same session scope; give the specialist its own identity via its definition (`AgentConfig.identity` / `RunOptions.identity`) | Attribution is per-run: each `session.run()`'s events/result belong to the active definition — record the swap in host bookkeeping; no `delegated_agent_step` event exists for in-process swaps |
+| Hierarchical crew | A goal requires dynamic decomposition by a manager LLM, parallel execution by role specialists, host aggregation, and conditional validation/revision loop | Workflow DAG execution — each specialist executes a bounded child task session; final deliverable returns to host | Workflow tenant/ownership scopes propagate; specialists activate only their own narrowed `tools` | Workflow node events (`node_started`/`node_finished`/`agent_event`); task attribution per role in the aggregated deliverable |
+| Supervisor delegation | Parent agent needs a child as a *tool call*: bounded budget, hooks that redact/narrow, nested delegation, durable child approvals | Separate runs; child result returns to the parent transcript | Parent identity/effectStore propagate; child factories receive derived resource/thread ids and AND-composed permission | Dedicated `delegation_started/finished/rejected/error` events, projectable through observability `handleDelegation()`; opt-in `delegation_child_event` passthrough |
+| A2A 1.0 | The other agent is owned by a **different service/deployment**; cross-org or cross-cluster; needs durable task lifecycle, push configs, streaming | Protocol boundary (JSON-RPC/HTTPS agent card); replay/reconnect via host-owned task adapter | Exact-origin verified client, `A2AAuthorization` per operation, principal-scoped push configs | Host-owned task adapter records the remote lifecycle; Prism creates no worker/store |
+
+Rule of thumb: same conversation → handoff; dynamic task decomposition + parallel execution → hierarchical crew; same process but a subtask → supervisor delegation; different deployment/trust boundary → A2A.
+
+## How in-session handoff works
+
+The pattern is a definition swap over existing seams — triage keeps calling `handoff(target)`; the host authorizes, swaps, and continues the same session:
+
+```ts
+// Host-built allow-list tool; untrusted target -> fail-closed tool error result.
+const handoffTool: ToolDefinition = {
+  name: "handoff",
+  description: "Transfer this conversation to a named specialist agent.",
+  parameters: { type: "object", required: ["target"], properties: { target: { type: "string" } } },
+  execute(args, ctx): ToolResult {
+    const target = String((args as { target: string }).target);
+    if (!(target in handoffTargets)) {
+      return { toolCallId: ctx.toolCallId, name: "handoff", error: { message: `Unknown handoff target: ${target}` } };
+    }
+    return { toolCallId: ctx.toolCallId, name: "handoff", value: { transferredTo: target } };
+  },
+};
+
+// Host authorizes the transfer mid-run: resolve the target definition and
+// continue the SAME session (same store + sessionId). The previous run's
+// leafId carries the transcript pointer; without it the next append forks
+// a sibling branch and the specialist loses the carried context.
+const specialist = await resolveAgentDefinition(handoffTargets[target], {
+  tools: [refundTool],              // narrowed: no handoff tool unless the host allows it
+  overrides: { provider: specialistProvider },
+});
+const specialistSession = createAgentSession({ agent: specialist, store, id: "handoff-demo", leafId: triageRun.leafId });
+```
+
+Live demo: [`examples/handoff-swarm.ts`](../examples/handoff-swarm.ts) — triage → billing transfer with fail-closed unknown target, a specialist whose re-handoff attempt is blocked (`unknown_tool`), and zero provider calls for the swap (it is a registry-level operation).
+
+Two non-obvious details the example encodes:
+
+1. **`leafId` carries the transcript pointer.** The specialist session must pass the triage run's `leafId`; creating the session without it appends to a sibling branch and the specialist loses the carried context.
+2. **Carried context is the transcript chain itself.** Handoff is not delegation: there is no input-payload boundary to sanitize; whatever was said to triage is what the specialist reads.
+
+## How hierarchical crew orchestration works
+
+Hierarchical multi-agent orchestration (the CrewAI "Hierarchical Process" pattern) decomposes a high-level goal into structured tasks, assigns each task to a role specialist agent in parallel, aggregates deliverables, and validates the outcome in a deterministic workflow:
+
+```ts
+// 1. Manager produces a typed task plan via structured output.
+//    Untrusted model output is validated against the schema before updating state.
+const manager = agentNode({
+  agent: "manager",
+  input: (ctx) => ({ goal: ctx.workflowInput }),
+  output: async (ctx) => {
+    const plan = parseTaskPlan(await getSessionOutput(ctx.session));
+    if (!plan.ok) throw new Error(`Invalid task plan: ${plan.error}`);
+    await ctx.updateState({ plan: plan.value });
+    return plan.value;
+  },
+});
+
+// 2. fan_out maps each task item to its corresponding role specialist.
+const fan = fanOutNode({
+  items: (ctx) => (ctx.state.plan as TaskPlan).tasks,
+  map: async (task, _index, _ctx) => {
+    const agent = await resolveAgentDefinition(definitions[task.role], { tools });
+    const session = createAgentSession({ agent });
+    const result = await session.run(task.instruction);
+    return { role: task.role, result: result.text, attribution: { agent: task.role } };
+  },
+  maxFanOut: 8,
+});
+
+// 3. join aggregates all specialist deliverables and computes per-role attribution.
+const aggregate = joinNode({
+  from: "fan",
+  reduce: async (items, ctx) => ({
+    deliverables: items,
+    summary: items.map((d) => `[${d.role}]: ${d.result}`).join("\n"),
+    validationPassed: evaluateQuality(items),
+  }),
+});
+
+// 4. conditional validation routes to completion or revision.
+const validate = conditionalNode({
+  when: async (ctx) => Boolean((ctx.upstream.aggregate as AggregatedDeliverable).validationPassed),
+  then: ["complete"],
+  else: ["revise"],
+});
+
+const complete = functionNode({ execute: async (ctx) => formatDeliverable(ctx.upstream.aggregate) });
+const revise = functionNode({ execute: async (ctx) => formatRevision(ctx.upstream.aggregate) });
+
+// 5. Entire flow is a single defineWorkflow DAG with fixed revision ID.
+const crewWorkflow = defineWorkflow({
+  revision: "crew-demo-1",
+  id: "hierarchical-crew",
+  nodes: { manager, fan, aggregate, validate, complete, revise },
+  edges: [
+    ["manager", "fan"],
+    ["fan", "aggregate"],
+    ["aggregate", "validate"],
+    ["validate", "complete"],
+    ["validate", "revise"],
+  ],
+  limits: { maxFanOut: 8, maxConcurrency: 4, maxNodes: 32 },
+});
+```
+
+Live demo: [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts) — manager structured task decomposition, parallel role specialists (`researcher`, `writer`), host reduce aggregation with per-role attribution, and conditional validation/revision routing.
+
+## CrewAI to Prism mapping table
+
+| CrewAI Concept | Prism Primitive | Notes & Documentation |
+| --- | --- | --- |
+| **Crew** | Workflow ([`defineWorkflow`](workflows.md)) | A deterministic DAG with explicit revision id, node concurrency, and checkpoint persistence. |
+| **Manager Agent** | Agent Node ([`agentNode`](workflows.md)) + Structured Output ([`generateValidateReviseLoop`](structured-output.md)) | Manager emits a typed `{ tasks: [{ role, instruction }] }` schema via `ArtifactValidator`/`ArtifactParser`. |
+| **Task** | Fan-out item ([`fanOutNode`](workflows.md)) | Bounded dynamic fan-out (`maxFanOut`), mapping each decomposed task to a role specialist session. |
+| **Role Agent (Specialist)** | Agent Definition ([`resolveAgentDefinition`](agent-definitions.md)) | Declarative agent with fail-closed tool narrowing; activated per role during `fan_out.map`. |
+| **Process (Sequential / Hierarchical)** | Workflow DAG ([`defineWorkflow`](workflows.md) / Edges) | Edges define data and execution dependencies; no unconstrained agent-to-agent loops. |
+| **Task Output Aggregation** | Join Node ([`joinNode`](workflows.md) + `reduce`) | Host-controlled reduction aggregating specialist outputs and computing per-role attribution. |
+| **Validation & Quality Review** | Conditional Node ([`conditionalNode`](workflows.md)) | Deterministic branch routing to `complete` or `revise` based on validation criteria. |
+| **Process Revision Loop** | Node Retries / DAG Branching / Loop Node ([`loopNode`](workflows.md)) | Bounded retry/revision path or bounded in-graph loop iteration. |
+
+## Where Prism is stronger
+
+- **Durable Human-in-the-Loop (HITL)**: Prism workflows support durable pause and resume via [`suspend()`](workflows.md#durable-suspension-and-resumption) and [`resumeWorkflow()`](workflows.md) across worker restarts or approval gates ([Agent durable approval](agent-session-runtime.md)).
+- **Strict Budget & Concurrency Caps**: Workflows enforce hard limits on `maxNodes`, `maxFanOut`, `maxConcurrency`, and timeout bounds ([Workflow limits](workflows.md)).
+- **Fail-Closed Capability Narrowing**: Specialists receive only their explicitly authorized `tools` via [`resolveAgentDefinition`](agent-definitions.md); managers cannot invoke specialist tools directly, preventing accidental tool leakage.
+- **Untrusted Model Output Validation**: Manager task plans are treated as untrusted LLM output and validated against a typed schema before triggering fan-out ([Structured output](structured-output.md)).
+- **Durable Audit & Telemetry**: Every node start/finish and agent event is emitted with deterministic sequence numbers and can be persisted to signed audit ledgers ([Policy and audit](policy-and-audit.md), [Observability](observability.md)).
+
+## Security and performance notes
+
+- **Transfers are explicit model-initiated, host-authorized.** The `handoff` tool exists on the triage agent's allow-list only; the target name is validated against the host-authored targets map before any definition resolves. Unknown names fail closed as a standard tool error (`Unknown handoff target: <name>`).
+- **No permission escalation through handoff or delegation.** The specialist's capabilities come solely from its own `AgentDefinition` as resolved by `resolveAgentDefinition` (fail-closed for omitted capabilities). Handoff or fan-out grants nothing: tools/identity are what the host put on that definition. The specialist cannot invoke manager tools unless its definition explicitly includes them — the standard `unknown_tool` block applies otherwise.
+- **Narrowing on transfer, never widening.** If the specialist needs the caller's verified identity, project it through `narrowIdentity` / `assertIdentityPropagation` ([Agent identity](agent-identity.md)) so scopes and tenant cannot widen across the swap. For delegation the same discipline is built in (`narrowIdentity`, AND-composed policies); for A2A the exact-origin client plus per-operation authorization is the boundary.
+- **Manager-generated task plans are untrusted model output.** Manager plan outputs are validated against the typed schema via `ArtifactValidator` before being persisted to workflow state or dispatched to `fan_out`. Malformed or invalid plans trigger the artifact repair loop or fail closed before any specialist is invoked.
+- **Redaction of carried context.** Handoff carries the raw transcript by design — same rows a human replay would read. Apply the session egress seams on the way out: `redactSessionEntry` / `redactMessage` with a host field policy (see [Data classification](data-classification.md)) and `AgentConfig.redactor`; for durable replay across tenants reuse the redacted transcript seam discipline used by ACP `sessions.transcript` ([ACP interop](acp.md)).
+- **Telemetry attribution.** Which agent produced which turn is not stored on message entries; the host knows (it performed the swap or aggregated fan-out results) and should pin it per run via `RunOptions.identity` (principal kind `agent`) so `identityTelemetryAttributes` (`prism.identity.*`) carries redacted attribution on telemetry, or via observability metadata. Supervisor runs emit dedicated `delegation_*` events; an in-process definition swap has no session seam to emit one, so the host records attribution.
+- **Performance.** The swap performs zero provider calls; it costs one registry resolution plus one session open (~sub-millisecond in the example fixture). The transferred turn costs what any tool round costs.
+
+## Extension and configuration notes
+
+- Handoff targets may be code-defined `AgentDefinition` objects or `<configRoot>/agents/<name>/AGENT.md` bundles resolved via `resolveAgentBundle` — the allow-list maps names to either.
+- Hosts wanting the pattern behind a UI timeline can emit their own step events from the swap.
+- A reusable in-session handoff helper was evaluated and **not** shipped in 0.3.x: the unavoidable boilerplate is a ~20-line allow-list tool plus one `createAgentSession` call. Revisit only if multiple hosts show materially different swap semantics.
+- Hierarchical crew patterns compose entirely on existing `@arnilo/prism-core/runtime/workflows` and `@arnilo/prism` primitives (`agentNode`, `fanOutNode`, `joinNode`, `conditionalNode`, `ArtifactValidator`, `resolveAgentDefinition`); no separate helper package is needed.
+
+## Related APIs
+
+- [Workflows](workflows.md): `defineWorkflow`, `fanOutNode`, `joinNode`, `conditionalNode`, `runWorkflow`.
+- [Structured output](structured-output.md): `ArtifactParser`, `ArtifactValidator`, `generateValidateReviseLoop`.
+- [Agent definitions](agent-definitions.md): `resolveAgentDefinition` and fail-closed capability activation — the swap seam itself.
+- [Supervisor delegation](supervisors.md): same-process subtasks with budgets, hooks, and durable nested approvals.
+- [A2A interoperability](a2a.md): the cross-service protocol boundary.
+- [Agent identity](agent-identity.md): verified identity propagation and narrowing (`narrowIdentity`, `assertIdentityPropagation`).
+- [Agent events](agent-events.md): `delegated_agent_step` and delegation event surfaces for timelines.
+- [Policy and audit](policy-and-audit.md): decision ledger, approval gates, and signed audit export.
+- [Observability](observability.md): OpenTelemetry agent/provider/tool hierarchy and metrics.
+- [Middleware hooks](middleware-hooks.md): context bridging and redaction without permission grants.