@mono-agent/agent-runtime 0.20.11 → 0.21.0

package/README.md

@@ -1,7 +1,7 @@
 # @mono-agent/agent-runtime
 
 Use this package when you need direct, capability-aware access to mono-agent's
-six built-in model runtime bridges, including product-neutral ACP v1 agents.
+Pi runtime and the ~39 providers it reaches.
 
 ## Category
 
@@ -10,13 +10,13 @@ six built-in model runtime bridges, including product-neutral ACP v1 agents.
 
 Category: `runtime`
 Tier: `core`
-Catalog responsibility: Provides six runtime bridges (ACP v1, Claude SDK, Claude Code CLI, Codex app-server, OpenCode app-server, Pi SDK); direct OpenCode requires stable CLI >=1.15.0 on PATH.
+Catalog responsibility: Provides the Pi SDK runtime bridge with native tools, MCP, sessions, compaction, and provider-catalog integration.
 
 <!-- package-metadata:end -->
 
 ## Responsibility
 
-Provides six runtime bridges (ACP v1, Claude SDK, Claude Code CLI, Codex app-server, OpenCode app-server, Pi SDK), with capabilities declared per bridge. This is the runtime layer that `@mono-agent/runtime-adapter` wraps behind runtime contracts. Pi and ACP-owned stdio children enforce optional mono-agent sandbox policy through an injectable `RuntimeSandbox` seam (a fail-closed passthrough by default; `@mono-agent/runtime-adapter` injects the real implementation). The router supports a compatibility-preserving uniform contract or explicit isolated per-route-native contracts; no provider route silently drops required capabilities.
+Implements the Pi runtime. This is the runtime layer that `@mono-agent/runtime-adapter` wraps behind runtime contracts. Pi-owned stdio children enforce optional mono-agent sandbox policy through an injectable `RuntimeSandbox` seam (a fail-closed passthrough by default; `@mono-agent/runtime-adapter` injects the real implementation). Every route in a fallback chain is Pi-native and shares one contract; no route silently drops required capabilities.
 
 ## Install / Usage
 
@@ -24,10 +24,14 @@ Provides six runtime bridges (ACP v1, Claude SDK, Claude Code CLI, Codex app-ser
 pnpm add @mono-agent/agent-runtime
 ```
 
-Node.js 22.19 or newer is required. The Claude Code, Codex, and direct
-OpenCode bridges also require their matching CLI on `PATH`; direct OpenCode
-requires stable OpenCode 1.15.0 or newer. SDK-only Claude and Pi runs do not
-spawn those CLIs.
+Node.js 22.19 or newer is required. Pi is the only runtime, and it talks to
+providers over their SDKs, so no provider CLI has to be on `PATH`.
+
+When a host enables background Exec/Bash, `wake_on_completion` defaults to true;
+explicit false retains terminal lifecycle updates without a completion turn.
+Using that field without `background: true` is invalid. Host-provided
+`processJobsAvailability` exposes lineage and exhaustion diagnostics even
+when a request has no start controller.
 
 Create one runtime for a host, parse a model reference, and run a turn:
 
@@ -39,8 +43,7 @@ import {
 
 const runtime = createRuntime({ workspace: process.cwd() });
 const result = await runtime.run("You are a concise repository assistant.", {
-  model: parseRuntimeModelReference("claude:claude-sonnet-4-6"),
-  executionMode: "sdk",
+  model: parseRuntimeModelReference("anthropic:claude-sonnet-4-6"),
   messages: [{ role: "user", content: "Summarize README.md." }],
   cwd: process.cwd(),
   allowedTools: ["Read"],
@@ -50,6 +53,16 @@ if (result.error) throw new Error(result.error);
 console.log(result.text);
 ```
 
+Requests to Pi providers `opencode` and `opencode-go`, and to custom models whose
+exact URL hostname is `opencode.ai`, carry `x-opencode-client: mono-agent` and an
+`x-opencode-session` continuity value. The value is the raw internal provider
+session id, not a channel conversation id. It remains stable for a continuous
+conversation epoch, rotates on reset or invalidation, and is fresh per call when
+a direct caller supplies no session or attribution identity. Existing
+case-insensitive auth/model/request headers—including explicit `null`
+suppression—and caller header transforms take precedence. Other providers receive
+no `x-opencode-*` headers.
+
 `Glob` and `Grep` prefer the packaged `@vscode/ripgrep` binary on supported
 platforms. An explicit `ripgrepPath` wins, with `PATH` as the final fallback.
 
@@ -61,19 +74,24 @@ capability. The host then explicitly intersects the two reviewed protocol
 revisions, reads only the originating tool's declared `ui://` resource, and
 receives one exact connection capability. Successful registration retains that
 existing MCP client instead of creating a client per UI call; host LRU/idle
-eviction closes the client, transport, and sandbox cleanup. Other runtime
-backends do not advertise or receive this extension.
+eviction closes the client, transport, and sandbox cleanup.
 See [Reply files and MCP Apps](https://mono-agent-docs.vercel.app/tools/rich-replies/).
 
 ## Architecture
 
+The injected Pi-native `Monitor` tool supports `wake_on: "batch" | "exit"`,
+`dedupe: "none" | "batch"`, and `min_wake_interval_ms` (defaults batch/none/0).
+The start receipt reports the host's effective policy, including interval
+clamping. Terminal delivery bypasses batch suppression and timing. A cancelled
+watch is intentionally stopped and must not be automatically recreated.
+
 The package uses a fixed registry of bridge descriptors and loads provider code
 only after a run selects a matching model reference and execution mode:
 
 ### Data flow
 
 1. `createRuntime()` binds host callbacks and creates an isolated tool context.
-2. `resolveRuntimeBridge()` checks the six static bridge descriptors in order.
+2. `resolveRuntimeBridge()` resolves the single static bridge descriptor.
 3. The selected descriptor lazily imports its provider implementation.
 4. The bridge prepares the runtime inputs it supports, including managed or MCP
    tools only where that bridge can represent them, and streams normalized
@@ -91,7 +109,7 @@ only after a run selects a matching model reference and execution mode:
 | --- | --- |
 | `src/runtime.js` | Host binding, per-instance tool context, bridge dispatch, and observer flushing |
 | `src/ai/runtime/` | Model-reference parsing, the lazy bridge registry, capabilities, sessions, and fallback routing |
-| `src/ai/providers/` | ACP v1, Claude SDK/CLI, Codex app-server, OpenCode app-server, and Pi SDK integrations |
+| `src/ai/providers/` | Pi provider integrations |
 | `src/agent/tools/` | Managed tools, MCP adaptation, output limits, and the injectable sandbox seam |
 | `src/agent/` | Approvals, allowlists, transcript snapshots, and compaction policy helpers |
 
@@ -100,13 +118,23 @@ the [architecture guide](https://github.com/robertsreberski/mono-agent/blob/main
 
 ### Managed-tool lifecycle fidelity
 
+Native event admission precedes queued storage: observers receive `recordEvent`
+and optional `recordToolLifecycle` callbacks synchronously. The latter receives
+the normalized lifecycle event before persistence begins. This lets the harness
+retain work emitted before cancellation while its sidecar is busy. Persistence
+and client delivery remain serialized; later cancellation cannot reclassify an
+already admitted tool result.
+
 `RuntimeRunOptions.toolLifecycleSink` is an awaited host-owned boundary. The
 runtime sends redaction-eligible raw arguments/content plus stable provider call
 id and name; the host returns only record/sequence, persistence/truncation byte
 metadata, and opaque artifact references. That returned metadata is attached to
-the exact normalized `tool_use` / `tool_result` event rendered by clients. Sink
-failure is fail-soft and explicit (`persistence: "failed"` plus an error code),
-never fake success. A callback exception cannot duplicate a client event.
+the exact normalized `tool_use` / `tool_result` event rendered by clients.
+`persistence: "deferred"` preserves a host-accepted write whose foreground
+confirmation window elapsed; `failed` plus an error code is reserved for a
+definitive sink rejection. Both remain fail-soft for the provider outcome and
+neither is converted into fake success. A callback exception cannot duplicate a
+client event.
 
 Provider bridges only claim terminal distinctions their structured protocol
 actually supplies:
@@ -114,11 +142,6 @@ actually supplies:
 | Bridge | Genuine tool-result distinctions | Conservative fallback |
 | --- | --- | --- |
 | Pi native | `success`, `error`, numeric `exit_nonzero`, structured `timeout`, structured `signal`, and abort-backed `cancelled`; host approval denial/expiry adds `rejected`/`timeout` | Unknown failed outcome → `error` |
-| Codex app-server | `success`, `error`, and numeric command `exit_nonzero`; shared host abort rules still apply | Other failed item → `error`; no result before run end remains dangling for host closure/recovery |
-| Claude SDK | `success` / `error`; shared host approval events can add `rejected`/`timeout` and an aborted error result can add `cancelled` | Undistinguished failed result → `error` |
-| Claude Code CLI | `success` / `error`; a Codex-shaped command item with an explicit non-zero code is `exit_nonzero`; shared approval/abort rules still apply | Undistinguished failed result → `error` |
-| OpenCode app-server | `success` / `error`; shared approval/abort rules still apply | Undistinguished failed result → `error` |
-| ACP v1 | `completed` → `success`, `failed` → `error`; shared approval/abort rules still apply | ACP exposes no tool-level signal/exit/timeout distinction, so failed → `error` |
 
 The runtime never derives a state from result prose. Structured timeout, signal,
 non-zero exit, completed success, and a specific non-runtime, non-cancellation
@@ -157,13 +180,14 @@ provider-supplied known kind when available and otherwise `runtime_error`.
 | API | Use it for |
 | --- | --- |
 | `createRuntime()` | Run one model bridge with host-owned credentials, observers, tools, and lifecycle callbacks |
-| `probeAcpProfile()` / ACP management helpers | Probe, authenticate, log out, list sessions, validate opaque handles, or delete an ACP provider session |
 | `createRouterRuntime()` | Retry an ordered model chain while preserving explicit route-safety contracts |
-| `parseRuntimeModelReference()` | Convert a canonical `acp:`, `claude:`, `codex:`, `opencode:`, or `pi:` string into the object required by `run()` |
-| `listRuntimeBridges()` / `runtimeCapabilities()` | Inspect the six built-in bridge descriptors without loading provider implementations |
+| `parseRuntimeModelReference()` | Convert a canonical `<provider>:<model>` string into the object required by `run()` |
+| `listRuntimeBridges()` / `runtimeCapabilities()` | Inspect the built-in bridge descriptor without loading provider implementations |
 | `createPiOAuthApiKeyResolver()` | Bind a host-owned Pi auth file with refresh-safe writes |
 | `listPiBuiltinModels()` / `getPiBuiltinModel()` | Read cloned snapshots from the runtime-owned, exact-pinned Pi model catalog without importing Pi directly |
 | `resolvePiOAuthApiKey()` / `loginPiOAuth()` | Use the runtime-owned Pi OAuth implementation without importing Pi's mutable provider registry |
+| `describePiProviderAuth()` / `checkPiProviderAuth()` / `loginPiProviderAuth()` | Bridge Pi's provider-owned auth descriptions, detection, prompts, device events, and returned credential without exposing its mutable registry |
+| `runPiProviderCheck()` | Execute one isolated, bounded Pi request for an explicitly selected provider/model and return only a fixed sanitized outcome; only provider-construction options are admitted, never session/history/tool/hook state |
 | `createMetricsObserver()` | Aggregate normalized event, token, cache, cost, tool, error, turn, and approval metrics |
 
 Most hosts should use `@mono-agent/runtime-adapter` instead of importing deep
@@ -178,25 +202,26 @@ Every symbol exported by each public code entrypoint is listed below.
 **`@mono-agent/agent-runtime`**
 
 ```text
-ACP_PROTOCOL_VERSION
-ACTIVE_RUNTIME_KINDS
 ALLOWLIST_MODE_ALL
 ALLOWLIST_MODE_CUSTOM
 APPROVAL_DECISIONS
-AcpCallbackContext
-AcpClientError
-AcpClientHostOptions
-AcpInteractionRequest
-AcpListedSession
-AcpProfileDescriptor
-AcpSessionListResult
 BINARY_BLOAT_TOOLS
 BridgeSpec
-CLAUDE_SDK_CATALOG_VERSION
 DEFAULT_RUNTIME_BRAND
 DEFAULT_TOOL_BLOAT_CONFIG
 MAX_TOOL_RESULT_BYTES
-RESERVED_RUNTIME_KINDS
+PROVIDER_CHECK_PROMPT
+PiBuiltinModelSnapshot
+PiBuiltinProviderSnapshot
+PiOAuthCredentialsSnapshot
+PiOAuthLoginCallbacks
+PiProviderAuthCheck
+PiProviderAuthDescription
+PiProviderAuthInteraction
+PiProviderAuthPrompt
+PiReasoningLevel
+ProviderCheckCode
+ProviderCheckOutcome
 RISK_TIERS
 RUNTIME_CAPABILITIES
 RuntimeBridge
@@ -204,47 +229,38 @@ RuntimeBridgeDescriptor
 RuntimeBridgeId
 RuntimeModelRef
 UNKNOWN_CAPABILITY
-acpRuntimeBridge
-authenticateAcpProfile
 buildCapabilitiesUsed
 buildTranscriptTailSnapshot
-canonicalizeLegacyModelReference
+checkPiProviderAuth
+classifyProviderCheckFailure
 configureToolRuntime
 createApprovalManager
-createClaudeSdkDiscoveryIsolation
 createMetricsObserver
 createObserverHub
 createPiOAuthApiKeyResolver
 createRouterRuntime
 createRuntime
 createSessionRegistry
-curatedClaudeSdkModels
-deleteAcpSession
-discoverClaudeSdkModels
+describePiBuiltinProvider
+describePiProviderAuth
 disposeAllProviderSessions
 disposeProviderSession
-executionModeIncompatibilityReason
-generateAcpResponse
 generatePiNativeResponse
 getPiBuiltinModel
 inferAllowlistMode
 invalidateProviderSession
 isLikelyContextTermination
-isModelCompatibleWithExecutionMode
-listAcpSessions
 listPiBuiltinModels
+listPiBuiltinProviders
 listRuntimeBridges
 loginPiOAuth
-logoutAcpProfile
+loginPiProviderAuth
 normalizeAllowlistMode
-normalizeClaudeSdkCatalog
-normalizeClaudeSdkModelId
 normalizeList
 normalizeRuntimeModelReference
 parseRuntimeModelReference
 parseStoredAllowlist
 piNativeRuntimeBridge
-probeAcpProfile
 readRuntimeBrand
 readToolRuntime
 reasoningLevelsForPiModel
@@ -257,13 +273,11 @@ resolveAllowlistMap
 resolvePiOAuthApiKey
 resolveRuntimeBrand
 resolveRuntimeBridge
+runPiProviderCheck
 runtimeCapabilities
-sdkFromModelReference
 storedAllowlistMode
 syncProviderSession
 toolCompactionAppliedFromWarnings
-validateAcpProfileId
-validateAcpProviderSessionId
 wrapToolsWithApprovalGate
 ```
 
@@ -332,6 +346,8 @@ inferSkillsRoot
 
 ```text
 DEFAULT_CODEX_SEARCH_MODEL
+DEFAULT_MONITOR_TIMEOUT_MS
+MIN_MONITOR_TIMEOUT_MS
 bashToolImpl
 bashToolRun
 createWebToolController
@@ -343,9 +359,12 @@ grepToolImpl
 inspectCodexSubscriptionSearch
 isPathAllowed
 isWorkdirAllowed
+monitorStopToolRun
+monitorToolRun
 normalizeBackgroundBashTimeoutMs
 normalizeBackgroundTimeoutMs
 normalizeBashTimeoutMs
+normalizeMonitorTimeoutMs
 normalizeProcessTimeoutMs
 performWebFetch
 performWebSearch
@@ -393,64 +412,54 @@ renderResumeSnapshot
 **`@mono-agent/agent-runtime/ai`**
 
 ```text
-ACP_PROTOCOL_VERSION
-ACTIVE_RUNTIME_KINDS
-AcpCallbackContext
-AcpClientError
-AcpClientHostOptions
-AcpInteractionRequest
-AcpListedSession
-AcpProfileDescriptor
-AcpSessionListResult
 BridgeSpec
-CLAUDE_SDK_CATALOG_VERSION
-RESERVED_RUNTIME_KINDS
+PROVIDER_CHECK_PROMPT
+PiBuiltinModelSnapshot
+PiBuiltinProviderSnapshot
+PiOAuthCredentialsSnapshot
+PiOAuthLoginCallbacks
+PiProviderAuthCheck
+PiProviderAuthDescription
+PiProviderAuthInteraction
+PiProviderAuthPrompt
+PiReasoningLevel
+ProviderCheckCode
+ProviderCheckOutcome
 RUNTIME_CAPABILITIES
 RuntimeBridge
 RuntimeBridgeDescriptor
 RuntimeBridgeId
 RuntimeModelRef
 UNKNOWN_CAPABILITY
-acpRuntimeBridge
-authenticateAcpProfile
 buildCapabilitiesUsed
-canonicalizeLegacyModelReference
-createClaudeSdkDiscoveryIsolation
+checkPiProviderAuth
+classifyProviderCheckFailure
 createMetricsObserver
 createObserverHub
 createSessionRegistry
-curatedClaudeSdkModels
-deleteAcpSession
-discoverClaudeSdkModels
+describePiBuiltinProvider
+describePiProviderAuth
 disposeAllProviderSessions
 disposeProviderSession
-executionModeIncompatibilityReason
-generateAcpResponse
 generatePiNativeResponse
 getPiBuiltinModel
 invalidateProviderSession
-isModelCompatibleWithExecutionMode
-listAcpSessions
 listPiBuiltinModels
+listPiBuiltinProviders
 listRuntimeBridges
 loginPiOAuth
-logoutAcpProfile
-normalizeClaudeSdkCatalog
-normalizeClaudeSdkModelId
+loginPiProviderAuth
 normalizeRuntimeModelReference
 parseRuntimeModelReference
 piNativeRuntimeBridge
-probeAcpProfile
 reasoningLevelsForPiModel
 refreshProviderSession
 resolvePiOAuthApiKey
 resolveRuntimeBridge
+runPiProviderCheck
 runtimeCapabilities
-sdkFromModelReference
 syncProviderSession
 toolCompactionAppliedFromWarnings
-validateAcpProfileId
-validateAcpProviderSessionId
 ```
 
 **`@mono-agent/agent-runtime/ai/cost.js`**
@@ -498,93 +507,32 @@ statsForCompletedChange
 formatLiveInputGuidance
 ```
 
-**`@mono-agent/agent-runtime/ai/providers/acp.js`**
-
-```text
-acpRuntimeBridge
-generateAcpResponse
-```
-
-**`@mono-agent/agent-runtime/ai/providers/claude-cli.js`**
+**`@mono-agent/agent-runtime/ai/providers/codex/app-server-client.js`**
 
 ```text
-buildCliCommand
-claudeCodeRuntimeBridge
-createThinkingBuffer
-generateCliResponse
-normalizeCliEvent
-```
-
-**`@mono-agent/agent-runtime/ai/providers/claude-sdk-discovery.js`**
-
-```text
-CLAUDE_SDK_CATALOG_VERSION
-ClaudeSdkCatalogModel
-ClaudeSdkEffort
-createClaudeSdkDiscoveryIsolation
-curatedClaudeSdkModels
-discoverClaudeSdkModels
-normalizeClaudeSdkCatalog
-normalizeClaudeSdkModelId
-```
-
-**`@mono-agent/agent-runtime/ai/providers/claude-sdk.js`**
-
-```text
-claudeEffortOptions
-claudeRuntimeBridge
-claudeSdkModelForQuery
-generateClaudeResponse
-toolPayloadLimit
-```
-
-**`@mono-agent/agent-runtime/ai/providers/codex-app.js`**
-
-```text
-codexAppRuntimeBridge
+CODEX_APP_SERVER_ARGS
+CODEX_APP_SERVER_ISOLATED_ARGS
+addOpaqueSensitiveValue
+codexErrorMessage
 createCodexAppServerClient
-generateCodexAppResponse
-```
-
-**`@mono-agent/agent-runtime/ai/providers/opencode-discovery.js`**
-
-```text
-discoverOpencodeProviders
-```
-
-**`@mono-agent/agent-runtime/ai/runtime/context-windows.js`**
-
-```text
-CLAUDE_ONE_MILLION_CONTEXT_MODELS
-DEFAULT_CONTEXT_WINDOW
-ONE_MILLION_CONTEXT_WINDOW
-claudeModelSupportsContextWindow
-claudeModelSupportsOneMillionContext
-hasExplicitOneMillionContextWindow
-modelWithContextWindow
-normalizeContextWindow
-stripContextWindowSuffix
-```
-
-**`@mono-agent/agent-runtime/ai/runtime/fast-mode.js`**
-
-```text
-codexModelSupportsFastMode
-normalizeFastMode
+isCodexRequestTimeout
+isSensitivePayloadField
+normalizedSensitiveName
+redactCodexDiagnostic
+redactCodexPayload
+sanitizeCodexDiagnostic
+sanitizeCodexNotification
+sanitizeCodexResponseError
+sensitiveEnvironmentValues
+utf8Head
 ```
 
 **`@mono-agent/agent-runtime/ai/runtime/model-refs.js`**
 
 ```text
-ACTIVE_RUNTIME_KINDS
-RESERVED_RUNTIME_KINDS
 RuntimeModelRef
-canonicalizeLegacyModelReference
-executionModeIncompatibilityReason
-isModelCompatibleWithExecutionMode
 normalizeRuntimeModelReference
 parseRuntimeModelReference
-sdkFromModelReference
 ```
 
 **`@mono-agent/agent-runtime/ai/runtime/registry.js`**
@@ -600,33 +548,21 @@ resolveRuntimeBridge
 runtimeCapabilities
 ```
 
-**`@mono-agent/agent-runtime/ai/streaming/codex-events.js`**
-
-```text
-normalizeCodexItemEvent
-normalizeCodexItemType
-```
-
 <!-- public-api-inventory:end -->
 
 ### When to reach for this vs. other JS agent runtimes
 
 `@mono-agent/agent-runtime` is purpose-built for **autonomous, long-running agent work** with provider portability and operational resilience as first-class concerns. It is *not* a streaming-chat UI kit. Where each peer fits:
 
-- **Vercel AI SDK** — best when you're building a chat / generative-UI experience inside a React or Next.js app. `useChat`, `useCompletion`, streaming server components, and edge-runtime compatibility are their strengths. Their provider list is curated (Anthropic, OpenAI, Google, etc., via `@ai-sdk/*` packages); there's no Pi gateway, no Claude Code CLI, no Codex CLI app-server, and no per-call provider fallback. If you're rendering a streaming chat into a browser, use them. If you're orchestrating multi-turn autonomous work that must survive a rate-limited primary provider, use us.
-- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — first-party Anthropic SDK. Tight integration with Claude features (canUseTool, sub-agents, hooks, MCP). We *wrap* it as one of our six bridges and add transcript-resume across provider drops, a structured failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Context/window handling remains bridge-specific; the pi-native bridge drives its own compaction recovery. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
+- **Vercel AI SDK** — best when you're building a chat / generative-UI experience inside a React or Next.js app. `useChat`, `useCompletion`, streaming server components, and edge-runtime compatibility are their strengths. Their provider list is curated (Anthropic, OpenAI, Google, etc., via `@ai-sdk/*` packages); there's no Pi gateway and no per-call provider fallback. If you're rendering a streaming chat into a browser, use them. If you're orchestrating multi-turn autonomous work that must survive a rate-limited primary provider, use us.
+- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — first-party Anthropic SDK. Tight integration with Claude features (canUseTool, sub-agents, hooks, MCP). We reach Anthropic models through the Pi gateway instead, and add transcript-resume across provider drops, a structured failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
 - **Mastra** — a workflow engine + memory + RAG stack. Different category: it's the layer *above* a runtime. You can layer Mastra workflows on top of `@mono-agent/agent-runtime` if you want both.
 - **OpenAI Agents SDK** — first-party OpenAI SDK. Same trade-off as the Claude Agent SDK: tight integration with OpenAI, no other providers. Pi providers in our runtime cover OpenAI plus a dozen others through a single API.
 - **LangChain.js** — kitchen sink with deep abstraction stacks. We're deliberately lean; if you want chains, agents, vector stores, and parsers under one umbrella, LangChain is built for that. If you want a focused runtime kernel, use us.
 
 **What we natively bridge (no extra packages):**
 
-- Anthropic Claude via the Claude Agent SDK (`claude` SDK).
-- Anthropic Claude via the `claude` Code CLI binary.
-- OpenAI's Codex via the `codex` app-server CLI.
-- OpenCode providers via an isolated, password-authenticated `opencode` app-server.
-- Any ACP v1 stdio agent resolved by the host from an `acp:<profile-id>` reference.
-- OpenAI, Google Gemini, AWS Bedrock, OpenRouter, xAI, Groq, Mistral, Perplexity, DeepSeek, Ollama, LlamaCPP, GLM, Vercel AI Gateway, GitHub Copilot, Gemini CLI — all through the Pi (`@earendil-works/pi-ai`) provider gateway, which our SDK adapter speaks directly.
+- Anthropic, OpenAI-Codex, OpenAI, Google Gemini, AWS Bedrock, OpenRouter, xAI, Groq, Mistral, Perplexity, DeepSeek, Ollama, LlamaCPP, GLM, Vercel AI Gateway, GitHub Copilot, Gemini CLI — all through the Pi (`@earendil-works/pi-ai`) provider gateway, which our SDK adapter speaks directly.
 
 **At-a-glance:**
 
@@ -646,81 +582,28 @@ normalizeCodexItemType
 
 Honest summary: if the agent runs **without a human watching the screen** for minutes-to-hours and **must survive provider blips**, this is the right tool. If a human is watching a streaming chat, Vercel's SDK is the right tool. Both can coexist in the same app.
 
-### Picking a backend
+### Model references
 
-The runtime picks a backend from `options.model` + `options.executionMode`:
+There is one runtime. A `model` is a parsed
+`{ provider, model, reference }` object whose `reference` must be the canonical
+`<provider>:<model>` spelling; convert reference strings with
+`parseRuntimeModelReference()` before calling `run()` — `run()` does not parse
+strings.
 
-| `model.sdk` | `executionMode` | Backend |
-|---|---|---|
-| `"claude"` | `"sdk"` (or omitted) | Claude SDK |
-| `"claude"` | `"cli"` | `claude` CLI |
-| `"pi"` | `"sdk"` (or omitted) | Pi SDK |
-| `"codex"` | `"cli"` | Codex app-server CLI |
-| `"opencode"` | `"cli"` | Isolated OpenCode app-server CLI |
-| `"acp"` | `"acp"` | ACP v1 stdio client |
-
-A `model` is a parsed `{ sdk, model, provider? }` object. Convert canonical
-strings such as `"pi:openai:gpt-5.5"` with
-`parseRuntimeModelReference()` before calling `run()`.
-
-#### ACP v1 host contract
-
-ACP references are canonical `acp:<profile-id>` strings and always use the
-dedicated `executionMode: "acp"`. The host supplies
-`resolveAcpProfile(profileId, context)` either to `createRuntime()` or per run;
-per-run callbacks win. A profile contains an absolute executable command,
-literal arguments, an exact child environment, ownership declarations for
-configuration/workspace/MCP, explicit capability policy, and bounded process
-limits. The runtime never invokes a shell or inherits `process.env`.
-
-Client-owned filesystem, terminal, permission, and elicitation behavior must be
-provided as callbacks and is advertised only when enabled. The runtime-adapter
-facade injects mono-agent's real sandbox implementation; direct kernel callers
-must provide their own when policy requires it. Every owned stdio bridge is
-closed after the operation with stdin close, TERM, then bounded KILL escalation.
-Callback payloads retain their typed operation fields but omit raw protocol
-session ids, extension metadata, and copied raw-id strings. Session-scoped
-callbacks receive the corresponding opaque handle as
-`AcpCallbackContext.providerSessionId`; request ids are opaque host correlation
-tokens as well.
-Session-update dispatch reads only validated own protocol fields. If a valid
-transport frame is too structurally complex for the bounded host sanitizer,
-the turn fails explicitly as `provider_protocol` instead of emitting a partial
-tool, plan, or message event.
-
-ACP provider-session ids and list cursors are confidential, authenticated v2
-handles bound to their token kind and profile. The host must supply an exact
-32-byte binary `acpSessionTokenKey` for every task run, list, validation, and
-delete operation. Call
-`validateAcpProviderSessionId(handle, expectedProfileId, key)` at untrusted
-ingress. Keep the key stable and secret across host restarts; changing it
-invalidates every outstanding handle. Legacy `acp:v1:` and `acp-cursor:v1:`
-values are rejected.
-
-Preserve each returned handle byte-for-byte and pass it back only to the
-matching high-level resume, list, validation, or delete operation. Encryption
-uses a fresh nonce, so two handles for the same remote id are not equality
-keys. Raw protocol session ids, cursors, token keys, and transport connections
-remain private runtime state and are omitted from profile resolver context,
-callbacks, and diagnostics. Under the default `auto` recovery policy, the
-client prefers `session/resume`, then `session/load`, and finally a fresh
-session when neither capability is advertised. Explicit `resume` or `load`
-policies fail closed if missing. Stable usage comes from the latest typed
-`usage_update` notification; unstable `PromptResponse.usage` is ignored.
+#### ACP
+
+The ACP *client* runtime backend was removed in 0.21.0. `mono-agent bridge acp`
+— serving ACP to clients — is unaffected and lives in `@mono-agent/agent-app`.
 
 ### `createRuntime(host)`
 
-Pass host-level integration once at boot. Keys are optional unless the selected
-backend contract requires them.
+Pass host-level integration once at boot. Every key is optional.
 
 ```js
 createRuntime({
   // -- host callbacks --
   resolveCustomPricing,    // (parsed) => NormalizedPricing | null
   resolvePiApiKey,         // async (provider) => string | undefined
-  resolveAcpProfile,       // async (profileId, context) => AcpProfileDescriptor
-  onAcpInteractionRequest, // async permission/elicitation fallback callback
-  acpSessionTokenKey,      // Uint8Array(32), required for ACP task/session-handle operations
   persistArtifact,         // ({ filename, buffer, toolName, toolUseId }) => path | null
   onCompactionRecorded,    // (compactionRow) => void — fired when the pi bridge
                            // runs an automatic compaction (proactive or reactive
@@ -729,6 +612,8 @@ createRuntime({
   // -- tool runtime context (process-level config for the tool kernel) --
   workspace,               // primary allowed root for path-based tools
   repoRoot,                // secondary allowed root
+  additionalReadRoots,     // extra realpath-contained file-tool read roots
+  additionalWriteRoots,    // extra realpath-contained file-tool write roots
   ripgrepPath,             // explicit path to `rg`; falls back to packaged binary, then PATH
   qaOutputDir,             // fallback dir for Playwright MCP filename routing
   sandboxPolicy,           // optional SandboxPolicy for tools and stdio MCP (enforced
@@ -744,9 +629,10 @@ createRuntime({
   observers: [],
 
   // -- approval gates (HITL) --
-  // Optional. When set, the runtime asks the host before every tool call
-  // whose risk tier is "medium" or "high" (and not session-allowlisted).
-  // See the "Approval gates" section below for the request/response shape.
+  // Optional. When set, the runtime asks the host before every BUILT-IN tool
+  // call whose risk tier is "medium" or "high" (and not session-allowlisted).
+  // MCP-backed tools are not gated. See the "Approval gates" section below
+  // for the request/response shape.
   onToolApprovalRequest,           // async (req) => { decision, reason? }
   toolRiskTiers: { Bash: "high" }, // per-tool tier override (low|medium|high)
   approvalDefaultRiskTier: "medium",
@@ -761,9 +647,6 @@ createRuntime({
     tempdirPrefix: "agent-runtime-cli-", // mkdtemp prefix for CLI provider scratch dirs
     providerModelPrefix: "agent",  // id prefix for custom Pi providers
     doctorCommand: "agent-runtime doctor", // command suggested in tool error messages
-    serviceName: "agent-runtime",  // Codex app-server serviceName
-    clientInfoName: "agent-runtime", // Codex app-server clientInfo.name
-    clientInfoTitle: "Agent Runtime", // Codex app-server clientInfo.title
   },
 });
 ```
@@ -793,6 +676,10 @@ defensively cloned model snapshots; `getPiBuiltinModel(providerId, modelId)`
 returns one cloned snapshot or `undefined`; and
 `reasoningLevelsForPiModel(model)` translates a Pi model into mono-agent's
 reasoning vocabulary, including `none` rather than Pi's `off`.
+Pi 0.85.1 exposes GPT-6 Astra through these same catalog APIs as
+`openai:gpt-6-astra` for OpenAI API keys and
+`openai-codex:gpt-6-astra` for Codex subscriptions; no separate model allowlist
+is maintained by mono-agent.
 `resolvePiOAuthApiKey(providerId, credentials)` refreshes a caller-owned
 credential snapshot and returns `{ apiKey, newCredentials }` or `null`, while
 `loginPiOAuth(providerId, callbacks)` runs the selected supported login flow.
@@ -802,13 +689,25 @@ manual-code, and abort callbacks pass through unchanged.
 These functions deliberately do not expose Pi's mutable model collections or
 OAuth-provider registry.
 
+Headless hosts can instead use `describePiProviderAuth()` to enumerate a
+provider's OAuth/API-key methods, `checkPiProviderAuth()` to distinguish stored
+or ambient credential detection without refreshing or making a model request,
+and `loginPiProviderAuth()` to relay Pi's typed prompts and events. The last
+function returns a credential to its caller but does not persist it; the owning
+application must apply its own safe-store transaction and must never serialize
+prompt answers into an operator projection. Abort can close supported Pi flows
+and discard an uncooperative provider's late result, but it cannot undo a
+provider-side grant or a filesystem mutation that already began; the owning app
+must fence pre-mutation persistence and safely drain atomic promotion/cleanup.
+
 Returns:
 
 - `run(systemPrompt, options)` — async, runs one agent turn against the chosen backend.
 - `configureTools(next)` — update the tool runtime context after construction.
 - `syncSession(id)` — fsync provider-owned durable state before canonical history commits.
 - `refreshSession(id)` — guarantee the next resume cannot reuse process-local state; absence succeeds and cleanup uncertainty rejects.
-- `retireDurableSession(id, sessionsRoot)` — delete and verify every exact-id durable Pi transcript, including cold duplicates.
+- `recoverSession(receipt, { appliedInputIds })` — validate and fsync an opted-in, settled durable Pi tail without executing the provider or appending a message. A host-owned `sessionRecovery: { runId, revision }` run option enables receipts; retries/backups strip that option and every returned receipt. Pending recovery blocks native resume. Failed/aborted assistant messages stay on disk and are filtered by Pi; completed tool evidence retains its native bytes. False or uncertain recovery requires host retirement. See [session recovery](../../docs/runtime/sessions-concurrency.md).
+- `retireDurableSession(id, sessionsRoot)` — delete and verify every exact-id durable Pi transcript, including cold duplicates. If the matching live session is still unwinding after cancellation or failure, refresh it out of the registry and unlink and fsync its current JSONL; a post-runtime retry also removes any headerless exact-name file recreated by a late append. Uncoordinated calls retain the legacy rollback behavior; opted-in admitted durable calls can retain a provisional tail for host recovery.
 - `disposeSession(id)` / `invalidateSession(id)` / `disposeAllSessions()` — ordinary best-effort eviction, destructive live invalidation, and shutdown cleanup.
 
 #### `runtime.run(systemPrompt, options)`
@@ -818,163 +717,58 @@ Per-call options (a non-exhaustive selection):
 | Option | Type | Notes |
 |---|---|---|
 | `model` | `RuntimeModelRef` | **Required.** Pass the object returned by `parseRuntimeModelReference()`; `run()` does not parse strings. |
-| `executionMode` | `"sdk" \| "cli" \| "acp"` | Default `"sdk"`; ACP references require `"acp"`. |
 | `messages` | `Message[]` | Conversation history. |
 | `cwd` | `string` | Working directory for the agent's tools. |
 | `allowedTools` | `string[]` | Built-in tool allowlist. Default: all. |
 | `disallowedTools` | `string[]` | Block list. |
-| `nativeSubagents` | `object` | Caller-defined Claude native `Task` profiles. Direct Codex rejects configured teammate definitions because Codex owns its collaboration agents. |
-| `settingSources` | `("user" \| "project" \| "local")[]` | Claude Agent SDK filesystem settings opt-in. Omitted/empty disables those three sources; Anthropic managed settings still apply. |
-| `codexLoadProjectDocs` | `boolean` | Codex app-server repository-instruction opt-in. Omitted/false sets `project_doc_max_bytes=0`; true restores Codex defaults. Explicit `codexAppServerArgs` wins. |
-| `codexSandboxNetworkAccess` | `boolean` | Code-only Codex app-server per-turn network control. Only strict `true` enables it for plan/default/acceptEdits; omitted or any other value disables it. |
-| `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http); on direct Codex, each forwarded server authorizes its own tool calls. |
+| `subagents` | `RuntimeSubagentsOptions` | In-process `Agent` delegation: profiles, caps, and the nested-run callback. This replaced the withdrawn caller-defined native teammate profiles. |
+| `skills` / `skillsRoot` | `{name, description}[]` / `string` | Skills disclosed to the run and the directory holding `<name>/SKILL.md`. |
+| `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http). |
 | `sandboxPolicy` | `SandboxPolicy` | Optional fail-closed sandbox policy for built-in tools and stdio MCP process startup. |
-| `webSearchConfig` | `{ backend?, endpoint?, codex?: { model? } }` | Run-scoped local SearXNG, ChatGPT-subscription Codex, and keyless WebSearch backend selection. |
+| `webSearchConfig` | `{ backend?, maxRequestsPerRun?, searxng?: { endpoint? }, ollama?: { baseUrl?, apiKey?, apiKeyEnv?, trustPublicUrl? }, codex?: { model? } }` | Run-scoped ordered WebSearch selection and a 1–20 actual-provider-request budget (default 4). `auto` uses explicitly configured Ollama, configured SearXNG, Codex, then keyless; named modes are strict. The deprecated top-level `endpoint` remains a SearXNG compatibility alias. |
 | `webFetchConfig` | `{ render?, browserCommand? }` | Run-scoped static extraction and optional isolated browser-render policy. |
-| `piToolExecutionMode` | `"safe-parallel" \| "sequential"` | Pi built-in scheduling. Safe parallelism is the default; stateful/mutating and MCP tools stay sequential. |
+| `piToolExecutionMode` | `"safe-parallel" \| "sequential"` | Pi built-in scheduling. Safe parallelism is the default; read-only tools may overlap only when the offered tool set contains no stateful/mutating or MCP tool. Otherwise Pi 0.85 serializes the whole batch. |
 | `maxTurns` | `number` | Hard cap on agent turns. |
-| `outputSchema` | `JSONSchema` | Requests structured JSON on capable bridges; see “Structured output” below for bridge-specific return behavior. |
+| `outputSchema` | `JSONSchema` | Requests structured JSON; see “Structured output” below. |
 | `abortSignal` | `AbortSignal` | Cancel the run. |
-| `liveInput` | `AsyncIterable<{ body: string; id?: string; receivedAt?: string; acknowledge?: () => void; reject?: (error?: unknown) => void }>` | Stream of in-flight user messages for steering on capable bridges. A bridge acknowledges only after its native steering boundary accepts the message; per-attempt rejection permits router replay. Acknowledgement emits metadata-only `live_input_applied` telemetry. |
-| `claudeAgentQuery` | `typeof query` | Advanced programmatic/test seam for the Claude SDK bridge. When omitted, the bridge uses the runtime's pinned Claude Agent SDK. This is not a config field or telemetry value. |
+| `liveInput` | `AsyncIterable<RuntimeLiveInputMessage>` | Stream of in-flight user messages. `accepted` reports native queue acceptance; `acknowledge` reports exact owned-operation transcript consumption; `uncertain` fences ambiguous delivery; proved-safe `reject` permits identified router replay. Stable nonblank IDs are required for cross-attempt replay. |
 | `onEvent` | `(event) => void` | Fired for every runtime event (assistant text, tool calls/results, applied live input, runtime warnings, structured output). |
+| `persistArtifact` | `({ filename, buffer, toolName, toolUseId }) => path \| null` | Synchronous artifact sink for this run. A run value overrides the host default and route-attempt resolvers cannot replace it. |
 | `runId` | `string` | Tag this run for downstream callbacks (e.g. `onCompactionRecorded`). |
 | `providerSessionId` | `string` | Resume a prior provider session. |
-| `acpSessionTokenKey` | `Uint8Array(32)` | Required for ACP task runs when not bound at `createRuntime()`; keep it secret and stable across restarts. |
-| `runArtifactDir` | `string` | Used by some providers as the Playwright MCP filename target. |
-| `codexAppServerCommand` | `string` | Override the Codex CLI binary. |
-| `codexAppServerArgs` | `string[]` | Override the Codex CLI arguments. |
+| `runArtifactDir` | `string` | Used as the Playwright MCP filename target. |
 
 `runtimeCapabilities()` and each descriptor returned by
-`listRuntimeBridges()` expose `tool_policy`. `"projected"` means the bridge can
-project restrictive `allowedTools` / `disallowedTools`; `"allow_all_only"`
-means it accepts only an effective unrestricted policy—`allowedTools` omitted
-or containing `"*"`, with no denied tools. A wildcard dominates named entries,
-so `["*", "Read"]` is allow-all. Named-only lists, `[]`, and any denylist remain
-unsupported on the direct Codex and direct OpenCode bridges and fail before
-provider startup. Built-in bridges always report this field; omission by a
-custom structural bridge means the capability is unknown.
-
-Live input is native on the Claude SDK, Codex app-server, and Pi bridges. The
-one-shot Claude CLI and direct OpenCode bridges advertise it as unsupported so
-routers skip them when a direct runtime call requires steering.
-After a native bridge invokes `acknowledge()`, the runtime emits exactly one
-`{ type: "live_input_applied", inputId, receivedAt? }` event for that logical
-run. It deliberately omits the guidance body. A fallback router reuses the same
-instrumented input stream, so replay or duplicate acknowledgement cannot emit a
-second applied event. A throwing host `acknowledge` or `reject` callback cannot
-change the native steering outcome; the Codex bridge reports it as a bounded
-`live_input_callback_failed` runtime warning.
-
-### Provider-native subagents and project instructions
-
-Claude SDK runs are filesystem-isolated by default: mono-agent passes
-`settingSources: []`, which disables user, project, and local settings sources,
-including their `CLAUDE.md`, hooks, plugins, and `.claude/agents` profiles.
-Anthropic managed settings remain in force and may still configure hooks or
-plugins; `settingSources` is not a managed-policy bypass. Opt into only the
-needed sources, for example `settingSources: ["project"]`. User, project, and
-local settings may execute configured hooks and plugins, so enable only trusted
-settings and avoid opting in while running in an untrusted checkout. This
-option is SDK only. The Claude Code CLI performs its own settings discovery,
-and mono-agent does not pass it a `--setting-sources` value.
-
-Codex app-server owns its native collaboration agents and their profiles. The
-bridge observes and normalizes their lifecycle, but it does not synthesize a
-`collaborationMode` payload or inject caller-defined `nativeSubagents`
-teammates. A non-empty configured teammate list fails before app-server startup
-with `skipped_capability_mismatch`, allowing a fallback router to continue to a
-Claude route.
-
-Codex app-server runs disable automatic repository-instruction discovery by
-default with `project_doc_max_bytes=0`. Set `codexLoadProjectDocs: true` when
-Codex and its own collaboration agents should load repository instructions. If
-`codexAppServerArgs` is supplied, that explicit argument vector is authoritative
-and `codexLoadProjectDocs` does not alter it.
-
-`codexSandboxNetworkAccess` is a separate code-only, provider-native control.
-It is unrelated to `RuntimeRunOptions.sandboxPolicy`, which controls
-mono-agent's own sandbox and is not consumed by Codex's provider-owned tool
-loop. Only strict `true` enables network access for plan/read-only and
-default/acceptEdits/workspace-write turns; the no-tools probe remains offline
-and bypass remains danger-full-access. Combining workspace-write with network
-access grants repository read and network egress in the same turn. Prefer
-`permissionMode: "plan"` when only read-only browsing is needed.
-
-Provider-native and in-process delegation share `subagent_activity` telemetry.
-`subagent.id` is the canonical parent attachment key: the initiating parent
-tool-use id whenever the provider exposes it, or a stable synthetic key for an
-orphan lifecycle record. `nativeId` is an optional provider task/thread id for
-correlation only and never replaces that key.
-The normalized phases are `agent_started`, `started`, `completed`, `message`,
-and `agent_completed`. A `message` belongs to the child and must not be treated
-as parent answer text or as a completed tool call.
-
-Restrictive allowlists must still authorize the delegation surface. Include
-`Agent` for the in-process built-in. Claude-native teammate definitions add
-`Task` to an explicit allowed list automatically; filesystem profiles enabled
-only through `settingSources` require callers to include `Task` themselves.
-An explicit deny still wins. Direct Codex remains an allow-all-only bridge, so
-a named restrictive allowlist fails before provider startup rather than being
-silently widened.
-
-Returns:
-
-```ts
-{
-  text: string,                     // raw assistant text
-  structuredResult?: any,           // captured JSON on supported bridges
-  structuredResultSource?: string,  // where structuredResult came from
-  events: RuntimeEvent[],           // full event stream (for host-side parsing)
-  usage: {
-    input_tokens, output_tokens,
-    cache_read_tokens, cache_creation_tokens,
-    cost_usd,
-  },
-  durationMs: number,
-  numTurns: number,
-  model: string,
-  effort: string,
-  sdk: "claude" | "pi" | "codex" | "opencode",
-  cancelled: boolean,
-  error: string | null,
-  errorDetails: object | null,
-  failureKind: string | null,
-  providerSessionId: string | null,
-  runtimeWarnings: RuntimeWarning[],
-  diagnostics: object,
-  capabilitiesUsed: {                  // what the backend actually did this call
-    prompt_cache_active: true|false|null,
-    thinking_enabled: true|false|null,
-    structured_output_enforced: boolean,
-    subagent_invoked: true|false|null,
-    mcp_servers_used: string[],
-    native_subagents_used: string[],
-    tool_compaction_applied: boolean,
-    context_compaction_applied: true|false|null,
-  },
-}
-```
-
-`capabilitiesUsed` is the per-call complement to `runtimeCapabilities()`. Tristate fields use `null` to mean "this provider can't tell" — distinct from `false` ("definitely off"). It's also emitted as a `capabilities_resolved` event near the end of the run, so observers can capture it without inspecting the result object.
-
-Successful provider requests may also emit exact context telemetry through
-`onEvent` and `result.events`:
-
-- `context_usage` is one provider-counted request snapshot, never the run's
-  aggregate processed-token total. Pi emits it at each successful assistant
-  `message_end`; Codex uses `thread/tokenUsage/updated.tokenUsage.last`; direct
-  OpenCode requires a completed assistant message with native `tokens.total`;
-  ACP normalizes the agent's exact `usage_update` `used`/`size` pair.
-  Each event identifies the measured model and includes `contextWindow` only
-  when the provider's own model metadata supplied it. The Claude bridges do not
-  currently emit this event.
-- `context_compaction` is a lifecycle event with a stable `operationId`,
-  `status` (`running`, `succeeded`, `skipped`, or `failed`), `sdk`, `trigger`,
-  `timestamp`, and optional safe reason/model/count fields. Pi drives and emits
-  its own lifecycle; Codex and OpenCode normalize their native notifications and
-  suppress deprecated duplicate notifications. Pi's before/after counts are
-  estimates and explicitly set `tokenCountsExact: false`.
+`listRuntimeBridges()` expose `tool_policy`. The Pi bridge reports
+`"projected"`, meaning it projects restrictive `allowedTools` /
+`disallowedTools` as written, so named-only lists, `[]`, and denylists are all
+supported. A wildcard dominates named entries, so `["*", "Read"]` is allow-all.
+The `"allow_all_only"` value survives for custom structural bridges that accept
+only an effective unrestricted policy; omission by such a bridge means the
+capability is unknown.
+
+Live input is native on the Pi bridge. Native acceptance is not consumption.
+Consumption requires the exact Pi entry's user `message_end` in the one
+main-lane prompt operation owned by the Mono run, plus the prompt result's
+matching operation ID. This proves transcript incorporation only—not provider
+receipt, answer use, or adherence. `live_input_consumed` records native
+evidence; legacy `live_input_applied` follows only when host acknowledgement
+returns exactly `recorded`. Void, `ignored`, throwing, or thenable callbacks
+produce settlement-unconfirmed diagnostics instead of false success.
+
+The logical-run fence keys stable IDs across retry and failover. The first
+occurrence owns its body and callbacks; later same-ID occurrences are suppressed
+as invalid duplicates. A proved pre-acceptance rejection or native queue removal
+can replay the original owner. Accepted, consumed, and uncertain IDs never
+replay. Missing IDs remain compatible but are exposed only in the first iterator
+generation. Diagnostics contain metadata only, never guidance bodies.
+
+### Project instructions
+
+The Pi runtime does not read another tool's filesystem settings, hooks, plugins,
+or project documents. Subagents are the kernel's own in-process delegation
+surface (the `Agent` tool), configured by the host rather than discovered from a
+provider's on-disk profiles.
 
 ### Built-in tools
 
@@ -988,12 +782,13 @@ by one lazily started Node.js REPL child per run. You select them via
 `allowedTools`. Tool implementations honor:
 
 - `cwd` (required for path-based tools)
-- The runtime context's `workspace` / `repoRoot` allow-list (paths outside both, plus `/tmp` and `process.cwd()`, are rejected)
-- Output truncation with optional artifact persistence (`{toolArtifactDir}/tool-output/{runId}/...` when `toolArtifactDir` is configured)
+- The runtime context's `workspace` / `repoRoot` allow-list (paths outside both, plus `/tmp` and `process.cwd()`, are rejected), with optional `additionalReadRoots` / `additionalWriteRoots` for narrowly scoped managed file-tool access. Additional roots require both the requested path and its realpath to stay inside the configured roots, so a symlink cannot escape them.
+- Output truncation with optional host-provided artifact persistence. The configured app binds this per run under `artifacts.dir/tool-output/<runId>/`.
 
 The Pi-native tool context may structurally receive a host process-job
-controller. Only then do Exec and Bash add optional `background`; with no
-controller their schemas and foreground path are unchanged. A background call
+controller. Only then do Exec and Bash add optional `background` and
+`wake_on_completion`. A host can disclose lineage diagnostics independently
+of that controller; a background request without one is rejected. A background call
 hands the exact prepared command to the controller and stops awaiting it. The
 kernel first creates a command-agnostic detached POSIX group leader; only after
 the host durably records its PID, equal PGID, and process incarnation does the
@@ -1004,14 +799,34 @@ contract package for this boundary.
 
 `NodeRepl` uses Node's default `node:repl` evaluator, so variables, `_`, `_error`, and loaded modules persist across calls in the same run. It supports multiline input and top-level `await`, resolves workspace-installed packages, and is closed with the run. Its child is prepared through the same sandbox seam as `Exec`/`Bash` and communicates through token-authenticated, length-prefixed JSON frames on ordinary stdin/stdout; abort, the fixed 120-second timeout, child exit, or hard output overflow resets the session. It deliberately has no session ids, persistent history, terminal commands, or package-install surface.
 
-`WebSearch` uses a configured loopback SearXNG endpoint and/or deterministic
-public fallbacks that require no credentials. It canonicalizes and deduplicates
-results, then fuses multiple query rankings. `WebFetch` extracts HTML, JSON,
-feeds, PDFs, and text locally with
-bounded redirects, bodies, headers, and retries. Config can opt into isolated
-`agent-browser` rendering for sparse client-rendered HTML. One ephemeral
-controller per run deduplicates identical calls and closes every browser
-namespace at run end.
+`WebSearch` uses explicit Ollama Web Search, a configured loopback SearXNG
+endpoint, and deterministic public fallbacks. Strict backends do not fall
+through, and `auto` tries explicitly configured Ollama → configured SearXNG →
+Codex → keyless. Hosted Ollama bearer credentials are accepted only for the
+exact official origin. Search canonicalizes and deduplicates results, trying
+supplied alternate queries only if the primary has no relevant results. Codex
+subscription search preserves a 10% allowance reserve. An optional host-injected
+coordinator shares admission and cooldowns across processes. `WebFetch`
+deterministically decodes and extracts HTML, JSON, feeds, PDFs, and text locally
+with bounded redirects, bodies, headers, retries, and structured parser
+failures. Config can opt into isolated `agent-browser` rendering for sparse
+client-rendered HTML; an explicit `render: "always"` call is browser-first.
+One ephemeral controller per run deduplicates identical calls and closes every
+browser namespace at run end. WebFetch `start_line` and `max_lines` reuse a
+bounded run-scoped document cache. Search and fetch use total deadlines of 60
+and 45 seconds respectively, with bounded transport cleanup after cancellation.
+WebSearch also shares a default hard budget of four actual provider requests
+across route retries in one logical run. Cache hits, in-flight followers,
+cooldown skips, and quota skips do not spend it. Rate-limited providers are
+deferred for that run, with retry timing and an explicit next action returned
+to the model; children and later runs receive fresh budgets.
+
+Each normalized WebSearch result caps its title at 500 characters and its
+snippet at 4,000 characters, including a visible truncation marker directing
+the model to `WebFetch`. The ranked result body is capped at 64 KiB UTF-8;
+lower-ranked snippets shrink before whole results are omitted, while the
+control, metadata, filter, and balanced untrusted-result framing always remain.
+Ollama receives the caller's effective 1–10 result limit as `max_results`.
 
 Pi runs with selected skills also expose `ReadSkill`. It returns the complete
 skill instructions by default, including content beyond the former
@@ -1021,51 +836,59 @@ truncation is explicitly desired; omitting it is not a separate hidden limit.
 The standard 256 KiB tool-payload guard still applies to oversized tool results.
 
 Override or extend the tool surface by passing `mcpServers` for MCP-backed tools.
-On direct Codex normal runs, each valid server that survives translation into
-the app-server config is the authorization boundary for the tools it exposes.
-The bridge accepts Codex's synthesized `mcp_tool_call` elicitation for that exact
-server without persisting an approval. Inherited or otherwise unconfigured
-server names, genuine downstream MCP elicitations, and other app-server requests
-remain fail-closed.
-
-This also applies under direct Codex `permissionMode: "plan"`: the read-only
-sandbox constrains Codex-owned filesystem and command execution, but a declared
-MCP tool can still change state managed by its server. Do not declare a server
-whose complete tool surface is not authorized for the run.
+Declaring a server is the authorization boundary: it exposes that server's whole
+tool surface to the run, and `sandboxPolicy` does not reach state the server
+owns on the other side of the connection. Do not declare a server whose complete
+tool surface is not authorized for the run: there is no per-call gate behind it.
+`onToolApprovalRequest` wraps the built-in tool set only (`getPiBuiltinTools`);
+`initPiMcpTools` is initialized without an approval manager, so an MCP call runs
+without asking the host, whatever risk tier is configured.
 
 ### Structured output
 
-Pass `options.outputSchema` (a JSON Schema). Claude SDK, Claude CLI, and Pi SDK
-surface captured JSON as `result.structuredResult`. Codex app-server receives
-the schema and reports that structured output was enforced, but its bridge
-returns provider text rather than parsing `structuredResult`; hosts must parse
-and validate `result.text`. Direct OpenCode rejects `outputSchema` with a typed
-capability mismatch.
-
-The package does **not** validate captured output against your schema. Hosts run
-their own validation (Zod, AJV, and similar) before applying domain effects.
+Pass `options.outputSchema` (a JSON Schema). The Pi runtime surfaces captured
+JSON as `result.structuredResult`.
 
 ### Provider fallback router
 
-`createRouterRuntime({ host, chain, routeSafety, resolveAttempt })` wraps the standard runtime with an ordered chain of model references. On a retryable provider/auth failure it retries the logical run against the next entry with one bounded transcript-tail snapshot. A chain is stateless across provider sessions. Entry `effort` is tri-state: a string fixes that route, `null` asks for provider default, and omission inherits the legacy per-run effort.
+`createRouterRuntime({ host, chain, resolveAttempt })` wraps the standard runtime with an ordered chain of model references. On a retryable provider/auth failure it retries the logical run against the next entry with one bounded transcript-tail snapshot. Only the primary's first attempt can keep a provider session; retries and backups are stateless and their successful results withhold `providerSessionId`. Entry `effort` is tri-state: a string fixes that route, `null` asks for provider default, and omission inherits the legacy per-run effort.
+
+The primary's first attempt owns the provider session. Retries and failovers run
+stateless with bounded transcript-tail replay. With coordinated durable Pi history,
+any answer from a retry or backup retires the primary epoch. The next turn
+cold-reseeds from canonical history; after a primary first-attempt success,
+subsequent turns resume the new session and are eligible for provider caching.
+
+On a warm turn whose primary attempt fails, the retry or backup attempt runs
+stateless with the current message and a bounded snapshot of the failed attempt,
+without the earlier conversation; the next turn reseeds from canonical history.
+
+Provider attribution remains stable across attempts even when the router withholds
+the resumable result id. Fresh stateless Pi calls use a private in-memory repository
+to avoid colliding with, or deleting, a primary transcript sharing that attribution.
+Lifecycle methods forward to the router's original inner runtime; a custom
+`resolveAttempt().runtime` must not assume those methods target its own independent
+session store.
 
 ```js
-import { createRouterRuntime } from "@mono-agent/agent-runtime";
+import { createRouterRuntime, parseRuntimeModelReference } from "@mono-agent/agent-runtime";
 
+// A RuntimeModelRef is { provider, model, reference }; `reference` is required
+// and must be the canonical `<provider>:<model>` spelling, so build refs with
+// parseRuntimeModelReference rather than writing the object literal by hand.
 const router = createRouterRuntime({
   host: { /* same shape as createRuntime */ },
-  routeSafety: "per-route-native",
   // Backoff shape for same-model retries; per-route counts live on `attempts`.
   retry: { backoffMs: 1000, maxBackoffMs: 15000 },
   chain: [
-    { model: { sdk: "claude", model: "claude-sonnet-5" }, effort: "high", attempts: 2 },
-    { model: { sdk: "codex", model: "gpt-5.6-sol" }, effort: "xhigh" },
-    { model: { sdk: "pi", provider: "ollama", model: "gemma4:31b" }, effort: null },
+    { model: parseRuntimeModelReference("anthropic:claude-sonnet-5"), effort: "high", attempts: 2 },
+    { model: parseRuntimeModelReference("openai-codex:gpt-5.6-sol"), effort: "xhigh" },
+    { model: parseRuntimeModelReference("ollama:gemma4:31b"), effort: null },
   ],
 });
 
 const result = await router.run("...", { /* same shape as runtime.run */ });
-console.log(result.failoverHistory, result.routeSafetyHistory);
+console.log(result.failoverHistory);
 ```
 
 Behaviour:
@@ -1073,32 +896,30 @@ Behaviour:
 - Successful run on entry N → returns the result with `failoverHistory` set to attempts 0..N-1.
 - Retryable provider failure → retries the SAME entry while it has `attempts` left (emitting `provider_retry_started` after a doubling backoff), then emits `provider_failover_started`, builds a transcript snapshot, and advances to the next entry. `attempts` defaults to `1` per entry, so the kernel is single-shot unless a host opts in — `@mono-agent/config` supplies the product default of 2 on the primary.
 - Same-model retries fire only for transient subkinds (`overloaded`, `rate_limited`, `timeout`, `network`, `server_error`, `retryable_request`, terminated streams). A retry drops the route's provider session, since the failed attempt already appended to it, and appends its own `failoverHistory` entry carrying `retryIndex`.
-- A retry is *not* a failover: `provider_route_safety` and `provider_failover_started` are emitted once per entry, and `provider_failover_completed` only fires when a genuinely different model answered.
+- A retry is *not* a failover: `provider_failover_started` is emitted once per entry, and `provider_failover_completed` only fires when a genuinely different model answered.
 - This is a whole-logical-turn retry sitting strictly outside the provider bridges' own transport retries. On a `pi` route, `attempts: 2` combined with pi's default `maxRetries: 2` means up to six provider stream starts.
 - Context-window failure after bridge compaction recovery → never retries the same entry (a second identical request against the same window is a guaranteed second failure); preserves `failureKind: "context_limit"` in `failoverHistory` and tries the next entry; quota/output/max-turn `usage_limit` remains terminal.
 - Provider auth failure → retries the next chain entry and preserves `failureKind: "provider_auth"` in `failoverHistory` for the failed attempt.
 - Malformed request/config/billing-type non-retryable failure → returns immediately with `failoverHistory` containing the one attempt.
 - Cancellation → returns immediately.
 - Chain exhausted → `failureKind: "provider_unavailable_exhausted"`, `failoverHistory` lists every attempt.
-- `uniform` safety keeps the shared monotonic runtime; `per-route-native` isolates
-  route runtimes and records each bounded safety contract/status.
-- A `per-route-native` non-Pi route cannot project non-empty internal
-  `sandboxPolicy.protectedRoots`; the router records `safety_unavailable` and
-  advances before route resolution or provider invocation. Empty protected-root
-  sets preserve ordinary provider-native behavior, while Pi routes retain the
-  policy. The same invariant covers model routes reached through `Agent`
-  children.
-- Pi route telemetry distinguishes `disabled`, fail-closed `mono-agent-srt`,
-  and `mono-agent-srt-unsafe-host-fallback`; the last describes a configured
-  policy that prefers SRT but permits host execution, not which branch ran.
+- Every route is Pi-native, so the whole chain shares one monotonic runtime
+  contract. There is no per-route safety negotiation and no
+  `provider_route_safety` event: with a single contract there is nothing to
+  reconcile between routes. Pi routes retain the sandbox policy, including
+  routes reached through `Agent` children.
 - A resolver-supplied Pi runtime may own provider credentials and lifecycle,
   but must expose `configureTools()`: before every attempt the router replaces
   its mutable tool context with the router's effective host/configured safety
   inputs, while request-scoped overrides remain on that exact run. A runtime
-  that cannot accept this projection fails closed as `safety_unavailable`.
-- Attempt-resolver failures are sanitized to `safety_unavailable`; resolver
-  credentials/options never enter result telemetry, and they advance to the next
-  entry rather than consuming the route's remaining `attempts`.
+  that cannot accept this projection fails the attempt before it runs.
+- Attempt-resolver failures — that missing `configureTools()` included — surface
+  as `failureKind: "provider_unavailable"`, with the error text fixed to
+  `The route attempt could not be resolved before execution.` (only a
+  `ResolverProtectedOptionError`, built from a repository-owned allowlist key,
+  reports its own message). Resolver credentials/options never enter result
+  telemetry, and such a failure advances to the next entry rather than consuming
+  the route's remaining `attempts`.
 - `resolveAttempt` runs once per attempt — including every same-model retry — and
   receives `{ attemptIndex, retryIndex }`, where `attemptIndex` stays the chain
   index. Its `cleanup` runs after each attempt.
@@ -1116,12 +937,16 @@ The runtime emits structured events for everything that happens during a run —
 A built-in aggregator covers the common metrics:
 
 ```js
-import { createRuntime, createMetricsObserver } from "@mono-agent/agent-runtime";
+import {
+  createMetricsObserver,
+  createRuntime,
+  parseRuntimeModelReference,
+} from "@mono-agent/agent-runtime";
 
 const metrics = createMetricsObserver();
 const runtime = createRuntime({ observers: [metrics] });
 
-await runtime.run("...", { model: { sdk: "claude", model: "claude-sonnet-4-6" } });
+await runtime.run("...", { model: parseRuntimeModelReference("anthropic:claude-sonnet-4-6") });
 
 console.log(metrics.snapshot());
 // {
@@ -1146,7 +971,7 @@ Notable new events emitted by the bridges:
 
 ### Approval gates (human-in-the-loop)
 
-Pass `onToolApprovalRequest` to gate tool calls behind a runtime approval. The runtime calls your callback once per tool invocation whose risk tier requires it, and pauses the agent until you respond.
+Pass `onToolApprovalRequest` to gate built-in tool calls behind a runtime approval. The runtime calls your callback once per built-in tool invocation whose risk tier requires it, and pauses the agent until you respond.
 
 ```js
 const runtime = createRuntime({
@@ -1175,32 +1000,86 @@ Responses:
 - `{ decision: "deny", reason? }` — block; the agent receives a tool error.
 - `{ decision: "always" }` — allow + session-allowlist for the run.
 
-Backend coverage: Claude SDK (via `canUseTool`) and Pi SDK (via tool dispatch wrapping). Direct OpenCode projects `permissionMode` into its SDK rules and forwards native permission events through the callback; `default`/`acceptEdits` ask for reads, dynamic/custom permission names require explicit host approval in attended modes, and unsupported live-question/subagent permissions are always denied. OpenCode `plan` is read-only but not a secret boundary because path rules follow symlinks; use Pi plus native `srt` for filesystem confinement. Claude CLI and Codex app-server use their backend-native `permissionMode` / `approvalPolicy` instead of the per-call gate.
-
-Direct OpenCode uses a password-authenticated ephemeral loopback server and a unique private database for every run; that database is deleted after the server closes, so user sessions and saved approvals are never imported. Session resume and MCP injection are intentionally unsupported. Repo/global config and external plugins/skills are disabled, and the provider shell inherits only a narrow non-secret environment; built-in providers use the normal OpenCode auth store so token rotation persists. `OPENCODE_AUTH_CONTENT` is rejected, stable OpenCode CLI >=1.15.0 is required, and the user's native DB migration marker must pre-exist. Provider replies are always one-shot—even a host `always` decision stays only in the current mono-agent run. Positive `maxTurns`, explicit effort, structured output, live input, fast mode, native subagents, and runtime skill metadata fail with typed capability mismatches before startup rather than being silently ignored.
-
-Approval lifecycle is observable via `onEvent`:
-
-- `tool_approval_pending` — emitted before calling the host.
-- `tool_approval_granted` — host approved.
-- `tool_approval_denied` — host denied, timed out, threw, or no callback for a high-risk tool.
+Coverage is the Pi runtime's built-in tool set, via tool dispatch wrapping.
+MCP-backed tools are outside the gate — the MCP bridge is built without an
+approval manager — so for those, declaring the server is the authorization
+boundary, not approving the call.
 
 ### Tool-result bloat handling
 
 The kernel's tool-bloat guard (`agent/tool-bloat.js`, internal) enforces a 256 KB default cap per `tool_result`. When a payload exceeds the cap, the kernel:
 
 1. Calls your `persistArtifact({ filename, buffer, toolName, toolUseId })` callback (if you supplied one).
-2. Substitutes a compact text reference in the agent's transcript.
+2. For text-only overflow, substitutes a compact summary plus a UTF-8-safe
+   60/40 head/tail sample inside a new balanced untrusted frame. The explicit
+   notice says the omitted middle may contain content and the retained tail is
+   not the source ending. Image, binary, and mixed payloads stay summary-only.
 3. Emits a `runtime_warning` with `warning_kind: "tool_payload_truncated"` and the saved-paths array.
 
-Hosts that don't supply `persistArtifact` get the truncation summary but no on-disk capture.
+Hosts that don't supply `persistArtifact`, or whose sink fails, get honest
+`persistence unavailable` text and no on-disk capture; the tool call still
+completes. The configured app writes owner-private raw, untrusted files under
+`artifacts.dir/tool-output/<runId>/`. Neither run-artifact retention nor
+tool-history retention cleans them up automatically.
 
 Before that byte cap runs, the builtin `Read` tool normalizes raster images with an edge longer than 8,000 px to fit within an 8,000 × 8,000 px box. Resizing preserves aspect ratio and the source format (resized BMP input becomes PNG), retains GIF/WebP animation, and never modifies the source file. Images already within the limit are embedded byte-for-byte unchanged.
 
+### System instructions and transcript assembly
+
+The host supplies stable system instructions separately from ordered messages.
+`@mono-agent/agent-harness` projects core/SOUL, identity and skill instructions
+by typed section ids; its full inspection prompt is not dispatched as system
+text. The runtime still appends its structured-output instruction here.
+The current user message starts with the host's latest Session/warm-skill
+envelope, followed by user/attachment text and recall. Tool authorization and
+delivery routing remain host-enforced.
+
+On every cold/stateless/retry path, canonical historical text precedes the cold
+untrusted tool-history projection and current turn. Canonical replay preserves
+speaker and stored timestamp labels, but cannot reconstruct native reasoning
+signatures or tool calls. A true Pi resume skips all supplied prior messages and
+keeps its native transcript; a missing durable JSONL seeds prior messages once.
+History retention remains last-64 for the configured host. Compaction can replace
+an older native prefix and remove previously loaded skill bodies, so warm-skill
+guidance only says complete instructions may remain visible.
+
 ### Context compaction
 
-The sole pi bridge runs on pi-agent-core's native `AgentHarness`. pi performs **no**
-automatic in-loop compaction, so the bridge drives it: before each turn it estimates the
+Summary preparation preserves labelled heads and tails of text tool results within
+Pi's 2,000-character serializer allowance. Copies retain tool identities and
+arguments; live results remain unchanged. Confirmed `Read`/`Write`/`Edit` results
+augment file metadata using `file_path`; failed or unmatched writes remain
+unresolved evidence. File metadata and supplemental file-operation evidence each
+have a 4 KiB bound, with omission counts. Record references remain unavailable
+without a proven host resolver.
+
+A versioned focus supplements both Pi summary requests, including split turns:
+intent, approval constraints, open work, decisions, exact symbols, errors, and next
+action, distinguishing current instructions from superseded ones. Pi's prompts,
+cut rules, recent tail and output budgets remain unchanged. Empty, malformed,
+aborted and output-truncated summaries are rejected before persistence.
+
+Each `context_compaction` event includes metadata-only `accounting` (version 1).
+Terminal events retain separately identified summary requests and their status,
+duration, provider tokens and cost, including rejected requests. Missing usage or
+cost stays `null`. Transcript and full-request before/after estimates are comparable
+and explicitly inexact; `afterSource` distinguishes a candidate preview from the
+persisted context. Summary text estimates, appended metadata bytes, tail
+estimate, policy and preparation omission counts are separate. Summary content,
+paths, tool arguments and raw cache keys are excluded from accounting.
+
+With prompt-cache diagnostics enabled, assistant payload diagnostics and usage
+share a request ID and phase. `context_usage.providerCostUsd` preserves unknown
+provider cost as `null` alongside the existing compatibility cost field. Summary requests use operation-scoped IDs in
+compaction accounting; their usage never flows into assistant request totals.
+`scripts/summarize-prompt-cache.mjs` reports boundaries, separate assistant/summary
+cost, and first differing observed message fingerprints for full inputs. Differences
+are evidence of payload changes, not proof of cache misses; delta/unsupported
+prefix comparisons remain unknown. Pi summary requests retain their existing
+`cacheRetention: "none"` behavior.
+
+The sole pi bridge runs on pi-agent-core's native `AgentHarness`. Pi supports native checkpoint and overflow compaction; mono-agent disables that path
+and drives guarded compaction itself: before each turn it estimates the
 running model's context usage and calls `AgentHarness.compact()` when near the window
 (proactive), and if a turn still overflows it compacts once and re-prompts exactly once
 only after a rebuilt-context preview proves positive reduction (reactive recovery).
@@ -1256,23 +1135,18 @@ These are stable but treated as advanced API. Most consumers should reach for `c
 
 ## Dependency Boundary
 
-This package has zero `@mono-agent/*` workspace dependencies. Its runtime
-dependencies are `@agentclientprotocol/sdk`, `@anthropic-ai/claude-agent-sdk`, `@anthropic-ai/sdk`,
-`@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`,
-`@modelcontextprotocol/sdk`, `@opencode-ai/sdk`, `@vscode/ripgrep`,
-`cross-spawn`, and `zod`.
-
-The runtime owns and exact-pins the compatible Pi pair at `0.80.6`; consumers
-use the runtime's Pi façade rather than coordinating a second direct
-`@earendil-works/pi-ai` dependency. Do not attempt to flatten the resulting
-Anthropic dependency tree: Pi AI pins `@anthropic-ai/sdk@0.91.1`, while the
-Claude Agent SDK requires `@anthropic-ai/sdk>=0.93.0` and the runtime supplies
-its compatible newer SDK. Two isolated Anthropic SDK versions are therefore
-expected. `RuntimeRunOptions.claudeAgentQuery` provides deterministic Claude
-tests without mocking package resolution or sending real SDK traffic.
-If a downstream test suite still needs Pi's faux-provider helpers, isolate that
-fixture or keep its development-only Pi dependency on the runtime's exact
-`0.80.6` version until the fixture is removed; a broad host range can otherwise
+This package has zero `@mono-agent/*` workspace dependencies. Its runtime core
+uses `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`,
+`@modelcontextprotocol/sdk`, `@vscode/ripgrep`, `cross-spawn`, and `zod`.
+Managed web extraction owns its direct parser dependencies: Defuddle,
+Readability, linkedom, Turndown, fast-xml-parser, and unpdf. Image inspection
+uses bmp-ts and sharp.
+
+The runtime owns and exact-pins its Pi dependencies; consumers use the runtime's
+Pi façade rather than coordinating a second direct `@earendil-works/pi-ai`
+dependency. If a downstream test suite still needs Pi's faux-provider helpers,
+isolate that fixture or keep its development-only Pi dependency on the runtime's
+exact version until the fixture is removed; a broad host range can otherwise
 float Pi Agent Core's own upstream dependency independently of this façade.
 
 Sandbox enforcement is an injectable `RuntimeSandbox` seam.
@@ -1298,7 +1172,8 @@ runtime fails closed.
 - [Programmatic approvals and structured output](https://mono-agent-docs.vercel.app/programmatic/approval-and-structured-output/)
   shows the code-only host hooks.
 - [Local-first web research](https://mono-agent-docs.vercel.app/tools/web-research/)
-  documents SearXNG, extraction, retry, browser isolation, and sandbox policy.
+  documents Ollama/SearXNG selection, extraction, retry, browser isolation, and
+  sandbox policy.
 - [Reply files and MCP Apps](https://mono-agent-docs.vercel.app/tools/rich-replies/)
   documents the host bridge, browser sandbox, and lifecycle limits.
 - [Architecture](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/ARCHITECTURE.md)