@mono-agent/agent-runtime 0.6.2 → 0.9.0

package/README.md

@@ -6,13 +6,15 @@ Category: `runtime`
 
 ## Responsibility
 
-Provides the multi-backend agent runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, Pi SDK) with provider session support. This is the runtime layer that `@mono-agent/runtime-adapter` wraps behind runtime contracts, and it enforces an optional sandbox policy for runtime-owned tools through an injectable `RuntimeSandbox` seam (a fail-closed passthrough by default; `@mono-agent/runtime-adapter` injects the real sandbox implementation for mono-agent hosts).
+Provides five runtime bridges (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 enforces optional mono-agent sandbox policy for runtime-owned tools 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.
 
 ## Public API
 
 - `createRuntime` — runtime factory dispatching to the backend bridges
 - `ai/runtime/model-refs.js` — `parseRuntimeModelReference`, `executionModeIncompatibilityReason`
 - `ai/runtime/registry.js` — `listRuntimeBridges`
+- `ai/providers/claude-sdk-discovery.js` — isolated Claude SDK model discovery without importing ambient auth/config
+- `createRouterRuntime({ chain, routeSafety, resolveAttempt })` — ordered fallback routing with exact route effort and bounded safety/failover telemetry
 - Provider bridges for `claude` (SDK + CLI), `codex` (app-server), `pi` (Pi SDK), and `opencode`
 - Provider session support: bridges accept `sessionId` in run options and report `provider_session_id`; the runtime exposes `disposeSession` / `disposeAllSessions`
 - Sandbox-aware built-in tools and stdio MCP startup through an injectable `RuntimeSandbox` seam (`agent/sandbox-seam.js`) — no direct dependency on `@mono-agent/runtime-adapter`
@@ -35,12 +37,13 @@ pnpm --filter @mono-agent/agent-runtime run test
 
 ## Overview
 
-Generic agent runtime that supports four backends out of the box:
+Generic agent runtime that supports five bridges out of the box:
 
-- **Claude SDK** (`@anthropic-ai/claude-agent-sdk`)
+- **Claude SDK** (`@anthropic-ai/claude-agent-sdk` 0.3.206)
 - **Claude Code CLI** (the `claude` binary)
 - **Pi SDK** (`@earendil-works/pi-agent-core`, used for OpenAI / Codex / Gemini / OpenRouter / Ollama / etc. via Pi providers)
 - **Codex CLI** (the `codex` app-server)
+- **OpenCode CLI** (an isolated `opencode` app-server driven through `@opencode-ai/sdk/v2`)
 
 Hosts wire in their own pricing, persistence, and credential callbacks (plus an `onCompactionRecorded` hook that fires on every automatic compaction — proactive or reactive — the pi bridge drives; see "Context compaction"). The runtime returns raw text + raw structured output; hosts that want a domain-specific contract parse it on their end.
 
@@ -57,10 +60,11 @@ npm install @mono-agent/agent-runtime
 
 Peer requirements:
 
-- Node.js ≥ 20
+- Node.js ≥ 22.19.0
 - `claude` CLI on PATH (only for `executionMode: "cli"` with `claude` SDK)
 - `codex` CLI on PATH (only for `executionMode: "cli"` with `codex` SDK; override via the `codexAppServerCommand` option)
-- `ripgrep` on PATH (or supplied via `ripgrepPath`) — required for the `Glob` and `Grep` built-in tools
+- stable `opencode` CLI >= 1.15.0 on PATH (only for direct `opencode:<provider>:<model>` refs)
+- `Glob` and `Grep` use the packaged `@vscode/ripgrep` binary on supported platforms. An explicit `ripgrepPath` is authoritative and PATH remains a fallback; provide one of those when optional dependencies are omitted or the platform is unsupported.
 
 ## Quick start
 
@@ -91,7 +95,7 @@ console.log(result.text);
 `@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 four backends and add transcript-resume across provider drops, a 22-kind failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Context/window handling stays with the provider — the runtime does not run its own in-loop summarization pass. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
+- **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 five bridges and add transcript-resume across provider drops, a 22-kind failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Context/window handling stays with the provider — the runtime does not run its own in-loop summarization pass. 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.
@@ -101,6 +105,7 @@ console.log(result.text);
 - 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.
 - 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:**
@@ -108,8 +113,8 @@ console.log(result.text);
 | Need | Use this | Use Vercel AI SDK | Use Claude Agent SDK |
 |---|---|---|---|
 | Streaming chat UI in React/Next | ✗ | ✓ | ✗ |
-| Multi-provider portability | ✓ (4 backends, 15+ providers) | partial | ✗ |
-| CLI providers (claude/codex binaries) | ✓ | ✗ | ✗ |
+| Multi-provider portability | ✓ (5 bridges, 15+ providers) | partial | ✗ |
+| CLI providers (claude/codex/opencode binaries) | ✓ | ✗ | ✗ |
 | Provider fallback on rate limit / overload | ✓ (`createRouterRuntime`) | ✗ | ✗ |
 | Context handling delegated to the provider (no host auto-summarization) | ✓ | ✓ | ✓ |
 | Transcript-tail resume after provider drops | ✓ | ✗ | ✗ |
@@ -131,6 +136,7 @@ The runtime picks a backend from `options.model` + `options.executionMode`:
 | `"claude"` | `"cli"` | `claude` CLI |
 | `"pi"` | any | Pi SDK |
 | `"codex"` | `"cli"` | Codex app-server CLI |
+| `"opencode"` | `"cli"` | Isolated OpenCode app-server CLI |
 
 A `model` reference can be the parsed shape `{ sdk, model, provider? }` or a string (`"pi:openai:gpt-5.5"`, `"claude:claude-sonnet-4-6"`, etc.) that you parse with the package's `parseRuntimeModelReference` helper.
 
@@ -151,7 +157,7 @@ createRuntime({
   // -- tool runtime context (process-level config for the tool kernel) --
   workspace,               // primary allowed root for path-based tools
   repoRoot,                // secondary allowed root
-  ripgrepPath,             // explicit path to `rg`; falls back to vendored binary, then PATH
+  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
                            // through the injectable RuntimeSandbox seam, not a bundled dep)
@@ -297,23 +303,23 @@ The package does **not** validate `structuredResult` against your schema — it
 
 ## Provider fallback router
 
-`createRouterRuntime({ host, chain })` wraps the standard runtime with an ordered chain of model references. On a retryable provider failure (rate limit, overload, network blip — classified via the same taxonomy as `retryableProviderFailureInfo`), it retries the same logical run against the next chain entry, replaying the transcript-tail snapshot of the previous attempt so the next provider continues rather than starts over.
+`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.
 
 ```js
 import { createRouterRuntime } from "@mono-agent/agent-runtime";
 
 const router = createRouterRuntime({
   host: { /* same shape as createRuntime */ },
+  routeSafety: "per-route-native",
   chain: [
-    { sdk: "claude", model: "claude-opus-4-7" },
-    { sdk: "claude", model: "claude-sonnet-4-6" },
-    { model: { sdk: "pi", provider: "openai", model: "gpt-5.5" }, requires: { structured_output: true } },
+    { model: { sdk: "claude", model: "claude-sonnet-5" }, effort: "high" },
+    { model: { sdk: "codex", model: "gpt-5.6-sol" }, effort: "xhigh" },
+    { model: { sdk: "pi", provider: "ollama", model: "gemma4:31b" }, effort: null },
   ],
 });
 
 const result = await router.run("...", { /* same shape as runtime.run */ });
-console.log(result.failoverHistory);
-// [{ model, failureKind, requestId, retryableSubkind }, ...]  one entry per attempt that didn't succeed.
+console.log(result.failoverHistory, result.routeSafetyHistory);
 ```
 
 Behaviour:
@@ -324,6 +330,18 @@ Behaviour:
 - 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.
+- 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.
+- 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.
 
 Chain entries can require backend capabilities via `requires: { structured_output: true, supports_mcp: true, ... }`; entries that don't satisfy the requirements are skipped (logged in `failoverHistory` as `failureKind: "skipped_capability_mismatch"`).
 
@@ -393,7 +411,9 @@ 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). Claude CLI and Codex CLI bridge into their backend's own approval models (`permissionMode` / `approvalPolicy`) — per-call runtime gates aren't available there.
+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`:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.6.2",
-  "description": "Agent runtime supporting Claude SDK, Claude CLI, Codex CLI, and PI SDK out of the box",
+  "version": "0.9.0",
+  "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, and Pi SDK bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",
   "keywords": [
@@ -70,6 +70,10 @@
       "types": "./types/ai/providers/claude-sdk.d.ts",
       "default": "./src/ai/providers/claude-sdk.js"
     },
+    "./ai/providers/claude-sdk-discovery.js": {
+      "types": "./types/ai/providers/claude-sdk-discovery.d.ts",
+      "default": "./src/ai/providers/claude-sdk-discovery.js"
+    },
     "./ai/providers/claude-cli.js": {
       "types": "./types/ai/providers/claude-cli.d.ts",
       "default": "./src/ai/providers/claude-cli.js"
@@ -123,14 +127,17 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.19.0"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
-    "@earendil-works/pi-agent-core": "^0.80.3",
-    "@earendil-works/pi-ai": "^0.80.3",
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.206",
+    "@anthropic-ai/sdk": "^0.110.0",
+    "@earendil-works/pi-agent-core": "^0.80.5",
+    "@earendil-works/pi-ai": "^0.80.5",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@opencode-ai/sdk": "^1.15.13",
+    "@vscode/ripgrep": "1.18.0",
+    "cross-spawn": "^7.0.6",
     "zod": "^4.3.6"
   },
   "scripts": {

package/src/agent/approval.js

@@ -30,7 +30,7 @@ export const RISK_TIERS = Object.freeze(["low", "medium", "high"]);
 const DEFAULT_TIMEOUT_MS = 60_000;
 
 /**
- * @param {{onToolApprovalRequest?: any, defaultRiskTier?: string, timeoutMs?: number, onEvent?: (event: any) => void, riskTiersByTool?: any, alwaysAllowTools?: any}} [options]
+ * @param {{onToolApprovalRequest?: any, defaultRiskTier?: string, timeoutMs?: number, onEvent?: (event: any) => void, riskTiersByTool?: any, alwaysAllowTools?: any, autoApproveLowRisk?: boolean}} [options]
  */
 export function createApprovalManager({
   onToolApprovalRequest = null,
@@ -39,6 +39,7 @@ export function createApprovalManager({
   onEvent = () => {},
   riskTiersByTool = {},
   alwaysAllowTools = [],
+  autoApproveLowRisk = true,
 } = {}) {
   const sessionAllowlist = new Set(normaliseList(alwaysAllowTools));
   const normalisedTiersByTool = Object.fromEntries(
@@ -63,24 +64,34 @@ export function createApprovalManager({
     const toolName = String(toolCall.toolName || toolCall.name || "");
     const toolUseId = toolCall.toolUseId || toolCall.id || null;
     const tier = riskTierFor(toolName);
+    const requestId = toolCall.requestId || randomUUID();
 
-    if (tier === "low") {
-      return { decision: "approve", reason: "low_risk", riskTier: tier };
+    if (tier === "low" && autoApproveLowRisk !== false) {
+      emitGrant({ requestId, toolName, toolUseId, tier, decision: "approve", reason: "low_risk" });
+      return { decision: "approve", reason: "low_risk", requestId, riskTier: tier };
     }
 
     if (sessionAllowlist.has(toolName)) {
-      return { decision: "approve", reason: "session_allowed", riskTier: tier };
+      emitGrant({ requestId, toolName, toolUseId, tier, decision: "approve", reason: "session_allowed" });
+      return { decision: "approve", reason: "session_allowed", requestId, riskTier: tier };
     }
 
     if (typeof onToolApprovalRequest !== "function") {
       if (tier === "high") {
-        emitDenial({ toolName, toolUseId, tier, reason: "no_host_callback_for_high_risk" });
-        return { decision: "deny", reason: "no_host_callback_for_high_risk", riskTier: tier };
+        emitDenial({ requestId, toolName, toolUseId, tier, reason: "no_host_callback_for_high_risk" });
+        return { decision: "deny", reason: "no_host_callback_for_high_risk", requestId, riskTier: tier };
       }
-      return { decision: "approve", reason: "no_host_callback_medium_auto_approve", riskTier: tier };
+      emitGrant({
+        requestId,
+        toolName,
+        toolUseId,
+        tier,
+        decision: "approve",
+        reason: "no_host_callback_medium_auto_approve",
+      });
+      return { decision: "approve", reason: "no_host_callback_medium_auto_approve", requestId, riskTier: tier };
     }
 
-    const requestId = toolCall.requestId || randomUUID();
     const argumentsSummary = redactSecrets(stringifyShort(toolCall.input || toolCall.arguments || {}));
     const payload = {
       requestId,
@@ -95,18 +106,26 @@ export function createApprovalManager({
 
     let response;
     let timedOut = false;
+    let timer;
     try {
       response = await Promise.race([
         Promise.resolve().then(() => onToolApprovalRequest(payload)),
-        new Promise((_, reject) => setTimeout(() => {
-          timedOut = true;
-          reject(new Error("approval_timeout"));
-        }, timeout).unref?.()),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => {
+            timedOut = true;
+            reject(new Error("approval_timeout"));
+          }, timeout);
+          timer.unref?.();
+        }),
       ]);
     } catch (err) {
-      const reason = timedOut || err?.message === "approval_timeout" ? "approval_timeout" : `host_error:${err?.message || err}`;
+      const reason = timedOut || err?.message === "approval_timeout"
+        ? "approval_timeout"
+        : `host_error:${redactSecrets(stringifyShort(err?.message || err))}`;
       emitDenial({ requestId, toolName, toolUseId, tier, reason });
       return { decision: "deny", reason, requestId, riskTier: tier };
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
     }
 
     const normalised = normaliseResponse(response, tier);
@@ -116,14 +135,13 @@ export function createApprovalManager({
     if (normalised.decision === "deny") {
       emitDenial({ requestId, toolName, toolUseId, tier, reason: normalised.reason });
     } else {
-      emit({
-        type: "tool_approval_granted",
+      emitGrant({
         requestId,
         toolName,
         toolUseId,
+        tier,
         decision: normalised.decision,
         reason: normalised.reason,
-        riskTier: tier,
       });
     }
     return { ...normalised, requestId, riskTier: tier };
@@ -141,6 +159,18 @@ export function createApprovalManager({
     });
   }
 
+  function emitGrant({ requestId, toolName, toolUseId = null, tier, decision, reason }) {
+    emit({
+      type: "tool_approval_granted",
+      requestId,
+      toolName,
+      toolUseId,
+      decision,
+      reason,
+      riskTier: tier,
+    });
+  }
+
   return {
     request,
     riskTierFor,
@@ -157,7 +187,12 @@ function normaliseResponse(response, tier) {
   const decision = APPROVAL_DECISIONS.includes(response.decision)
     ? response.decision
     : (tier === "high" ? "deny" : "approve");
-  return { decision, reason: typeof response.reason === "string" ? response.reason : null };
+  return {
+    decision,
+    reason: typeof response.reason === "string"
+      ? redactSecrets(response.reason).slice(0, 2000)
+      : null,
+  };
 }
 
 function normaliseList(value) {

package/src/agent/sandbox-seam.js

@@ -49,6 +49,7 @@
  * @property {ReadonlyArray<string>} [args]
  * @property {string} [cwd]
  * @property {Object<string, string|undefined>} [env]
+ * @property {boolean} [allowLocalBinding] Trusted per-command capability.
  */
 
 /**

package/src/agent/tools/pi-bridge.js

@@ -499,6 +499,7 @@ export function resolveMcpStdioCwd(cfg = {}, cwd = null) {
 export async function prepareMcpStdioCommand(cfg = {}, { cwd = null, sandboxPolicy = null, sandboxEngine = null, ctx = null } = {}) {
   const resolvedCtx = ctx ?? readToolRuntime();
   const sandbox = resolvedCtx.sandbox ?? passthroughSandbox;
+  const appOwnedLocalBinding = cfg[Symbol.for("@mono-agent/app-owned-local-binding")] === true;
   return sandbox.prepareCommand({
     policy: resolveSandboxPolicy(resolvedCtx, sandboxPolicy),
     engine: sandboxEngine ?? undefined,
@@ -507,6 +508,7 @@ export async function prepareMcpStdioCommand(cfg = {}, { cwd = null, sandboxPoli
       args: cfg.args || [],
       cwd: resolveMcpStdioCwd(cfg, cwd),
       ...(cfg.env && typeof cfg.env === "object" ? { env: cfg.env } : {}),
+      ...(appOwnedLocalBinding ? { allowLocalBinding: true } : {}),
     },
   });
 }
@@ -783,6 +785,11 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
             details: {
               server: serverName,
               tool: sourceTool.name,
+              // pi-agent-core treats a resolved execute() call as successful.
+              // Preserve the MCP protocol's explicit error bit in details so
+              // the harness after-tool hook can replace that default without
+              // throwing away the bounded content or structuredContent below.
+              ...(out?.isError === true ? { mcp_result_is_error: true } : {}),
               mcp_call_duration_ms: mcpCallDurationMs,
               result_truncated: mcpContentWasTruncated(out, { textLimit, imageInlineMaxBytes }),
               raw: compactRawMcpResult(out),

package/src/agent/tools/shared/ripgrep.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
-import { delimiter, dirname, join } from "node:path";
+import { delimiter, join } from "node:path";
 import {
   DEFAULT_EXCLUDED_DIRS,
   DEFAULT_EXCLUDED_FILES,
@@ -36,14 +36,18 @@ export function ripgrepMissingMessage(ctx) {
 // larger change with no real-world payoff today.
 export const cachedRgPath = { value: undefined };
 
-function vendoredRgPath() {
+function packagedRgPath() {
   try {
-    const sdkPkg = requireFromHere.resolve("@anthropic-ai/claude-agent-sdk/package.json");
-    const platform = process.platform === "win32" ? "win32" : process.platform;
-    const arch = process.arch === "x64" ? "x64" : process.arch === "arm64" ? "arm64" : null;
-    if (!arch) return null;
+    // Resolve the platform package relative to @vscode/ripgrep itself. pnpm's
+    // strict layout does not expose this optional transitive dependency from
+    // agent-runtime, and importing the wrapper eagerly would throw when a
+    // consumer intentionally installs with optional dependencies omitted.
+    const wrapperEntry = requireFromHere.resolve("@vscode/ripgrep");
+    const requireFromRipgrep = createRequire(wrapperEntry);
+    const arch = process.env.npm_config_arch || process.arch;
     const binaryName = process.platform === "win32" ? "rg.exe" : "rg";
-    const candidate = join(dirname(sdkPkg), "vendor", "ripgrep", `${arch}-${platform}`, binaryName);
+    const platformPackage = `@vscode/ripgrep-${process.platform}-${arch}`;
+    const candidate = requireFromRipgrep.resolve(`${platformPackage}/bin/${binaryName}`);
     return existsSync(candidate) ? candidate : null;
   } catch {
     return null;
@@ -73,7 +77,7 @@ export function resolveRgPath({ refresh = false, ctx } = {}) {
   if (ripgrepPath) {
     cachedRgPath.value = existsSync(ripgrepPath) ? ripgrepPath : null;
   } else {
-    cachedRgPath.value = vendoredRgPath() || rgFromPath() || null;
+    cachedRgPath.value = packagedRgPath() || rgFromPath() || null;
   }
   return cachedRgPath.value;
 }

package/src/ai/index.js

@@ -10,6 +10,14 @@ export {
 } from "./runtime/sessions.js";
 export { createMetricsObserver, createObserverHub } from "./observer.js";
 export { generatePiNativeResponse, piNativeRuntimeBridge } from "./providers/pi-native.js";
+export {
+  CLAUDE_SDK_CATALOG_VERSION,
+  createClaudeSdkDiscoveryIsolation,
+  curatedClaudeSdkModels,
+  discoverClaudeSdkModels,
+  normalizeClaudeSdkCatalog,
+  normalizeClaudeSdkModelId,
+} from "./providers/claude-sdk-discovery.js";
 export {
   buildCapabilitiesUsed,
   toolCompactionAppliedFromWarnings,

package/src/ai/providers/claude-cli.js

@@ -15,6 +15,62 @@ import {
   claudeNativeAgentDefinitions,
   resolveClaudeAllowedTools,
 } from "./claude-subagents.js";
+import {
+  claudeCapabilityMismatchResult,
+  claudeSandboxCapabilityMismatchResult,
+  claudeSandboxPolicyProblem,
+} from "./claude-sandbox.js";
+import { resolveSandboxPolicy } from "../../agent/tools/shared/tool-context.js";
+
+const CODEX_CLI_SANDBOX_POLICY_UNSUPPORTED =
+  "Direct Codex CLI cannot enforce mono-agent's native srt sandbox scopes. Remove the mono-agent sandbox policy or use a Pi runtime for exact readableRoots, writableRoots, denyWrite, and network rules.";
+const CLAUDE_CLI_EMPTY_TOOL_POLICY_UNSUPPORTED =
+  "Claude Code CLI cannot enforce an explicit empty allowedTools list: omitting --tools would restore Claude Code's default toolset. Use a specific non-empty allowlist, a denylist, or the Claude SDK for a no-tools run.";
+
+function codexCliToolPolicyProblem(options) {
+  const allowedTools = Array.isArray(options.allowedTools) ? options.allowedTools : null;
+  const disallowedTools = Array.isArray(options.disallowedTools) ? options.disallowedTools : [];
+  const exactAllowAll = allowedTools === null
+    || (allowedTools.length === 1 && allowedTools[0] === "*");
+  return exactAllowAll && disallowedTools.length === 0
+    ? null
+    : "Direct Codex CLI cannot enforce allowedTools/disallowedTools. Use exact allow-all ([\"*\"] with no disallowedTools) or another runtime.";
+}
+
+function codexCliCapabilityMismatchResult(options, error, codexErrorCode, start) {
+  const resolved = options.model;
+  const providerSessionId = (typeof options.sessionId === "string" && options.sessionId.trim())
+    || (typeof options.providerSessionId === "string" && options.providerSessionId.trim())
+    || null;
+  return {
+    text: null,
+    structuredResult: undefined,
+    structuredResultSource: null,
+    events: [],
+    usage: {},
+    durationMs: Date.now() - start,
+    numTurns: 0,
+    model: resolved?.reference || `codex:${resolved?.model || ""}`,
+    effort: options.effort || null,
+    sdk: "codex",
+    providerSessionId,
+    provider_session_id: providerSessionId,
+    cancelled: false,
+    error,
+    failureKind: "skipped_capability_mismatch",
+    diagnostics: { codex_error_code: codexErrorCode },
+    capabilitiesUsed: buildCapabilitiesUsed({
+      promptCacheActive: null,
+      thinkingEnabled: null,
+      structuredOutputEnforced: !!options.outputSchema,
+      subagentInvoked: null,
+      mcpServersUsed: [],
+      nativeSubagentsUsed: [],
+      toolCompactionApplied: false,
+      contextCompactionApplied: null,
+    }),
+  };
+}
 
 const DORMANT_CLI_CAPABILITIES = {
   streaming: true,
@@ -371,9 +427,8 @@ export function buildCliCommand({
   nativeSubagents,
   contextWindow,
 }) {
-  // Effort is expected to be pre-normalized by core/ai.js#generateResponse
-  // before reaching this provider. Direct callers of buildCliCommand must
-  // pass an already-normalized reasoning level (low/medium/high/xhigh/none).
+  // Effort arrives pre-normalized (low/medium/high/xhigh/max/none); per-CLI
+  // ceilings are clamped below rather than by callers.
   const normalizedEffort = typeof effort === "string" && effort.trim() ? effort : null;
   if (sdk === "claude-code") {
     const nativeAgents = claudeNativeAgentDefinitions(nativeSubagents);
@@ -435,8 +490,10 @@ export function buildCliCommand({
   if (permissionMode === "bypassPermissions") args.push("--dangerously-bypass-approvals-and-sandbox");
   else if (permissionMode === "acceptEdits" || permissionMode === "auto") args.push("--full-auto");
   else if (permissionMode === "plan") args.push("--sandbox", "read-only");
-  if (normalizedEffort) args.push("--config", `model_reasoning_effort=${normalizedEffort}`);
-  if (normalizedEffort !== "none") args.push("--config", `model_reasoning_summary=${tomlValue("auto")}`);
+  // codex has no "max" reasoning tier; clamp to its ceiling instead of crashing the CLI.
+  const codexEffort = normalizedEffort === "max" ? "xhigh" : normalizedEffort;
+  if (codexEffort) args.push("--config", `model_reasoning_effort=${codexEffort}`);
+  if (codexEffort !== "none") args.push("--config", `model_reasoning_summary=${tomlValue("auto")}`);
   if (hasEntries(mcpServers)) args.push(...codexMcpConfigArgs(mcpServers));
   args.push([systemPrompt, prompt].filter((part) => String(part || "").trim()).join("\n\n"));
   return { command: "codex", args, cwd };
@@ -445,6 +502,53 @@ export function buildCliCommand({
 export async function generateCliResponse(systemPrompt, options = {}) {
   const start = Date.now();
   const resolved = options.model;
+  if (resolved?.sdk === "claude-code" && claudeSandboxPolicyProblem(options)) {
+    const providerSessionId = (typeof options.sessionId === "string" && options.sessionId.trim())
+      || (typeof options.providerSessionId === "string" && options.providerSessionId.trim())
+      || null;
+    return claudeSandboxCapabilityMismatchResult({
+      model: resolved.reference || `claude:${resolved.model}`,
+      effort: options.effort,
+      sdk: "claude-code",
+      providerSessionId,
+      durationMs: Date.now() - start,
+      outputSchema: options.outputSchema,
+    });
+  }
+  if (resolved?.sdk === "claude-code" && Array.isArray(options.allowedTools) && options.allowedTools.length === 0) {
+    const providerSessionId = (typeof options.sessionId === "string" && options.sessionId.trim())
+      || (typeof options.providerSessionId === "string" && options.providerSessionId.trim())
+      || null;
+    return claudeCapabilityMismatchResult({
+      model: resolved.reference || `claude:${resolved.model}`,
+      effort: options.effort,
+      sdk: "claude-code",
+      providerSessionId,
+      durationMs: Date.now() - start,
+      outputSchema: options.outputSchema,
+      error: CLAUDE_CLI_EMPTY_TOOL_POLICY_UNSUPPORTED,
+      errorCode: "claude_cli_empty_tool_policy_unsupported",
+    });
+  }
+  if (resolved?.sdk !== "claude-code") {
+    if (resolveSandboxPolicy(options.toolContext, options.sandboxPolicy) !== undefined) {
+      return codexCliCapabilityMismatchResult(
+        options,
+        CODEX_CLI_SANDBOX_POLICY_UNSUPPORTED,
+        "codex_sandbox_policy_unsupported",
+        start,
+      );
+    }
+    const toolPolicyProblem = codexCliToolPolicyProblem(options);
+    if (toolPolicyProblem !== null) {
+      return codexCliCapabilityMismatchResult(
+        options,
+        toolPolicyProblem,
+        "codex_tool_policy_unsupported",
+        start,
+      );
+    }
+  }
   const prompt = promptFromMessages(options.messages);
   const dir = mkdtempSync(join(tmpdir(), (options.toolContext?.runtimeBrand ?? readRuntimeBrand()).tempdirPrefix));
   const schemaPath = options.outputSchema ? join(dir, "output-schema.json") : null;

package/src/ai/providers/claude-sandbox.js

@@ -0,0 +1,71 @@
+import { buildCapabilitiesUsed } from "../runtime/capabilities-used.js";
+import { resolveSandboxPolicy } from "../../agent/tools/shared/tool-context.js";
+
+export const CLAUDE_SANDBOX_POLICY_UNSUPPORTED =
+  "Claude SDK/CLI cannot enforce mono-agent's native srt sandbox scopes. Remove the mono-agent sandbox policy or use a Pi runtime for exact readableRoots, writableRoots, denyWrite, and network rules.";
+
+/**
+ * Claude owns its built-in tool subprocesses, so mono-agent's runtime tool
+ * context cannot wrap them with the configured srt engine. An explicit `off`
+ * policy is inert and remains valid; every enforcing mono-agent mode must fail
+ * before the provider starts instead of silently running outside that policy.
+ */
+export function claudeSandboxPolicyProblem(options) {
+  const effectivePolicy = resolveSandboxPolicy(
+    options?.toolContext,
+    options?.sandboxPolicy,
+  );
+  return effectivePolicy !== undefined
+    ? CLAUDE_SANDBOX_POLICY_UNSUPPORTED
+    : null;
+}
+
+/** Typed provider result used by Claude bridges for fail-closed capability paths. */
+export function claudeCapabilityMismatchResult({
+  model,
+  effort,
+  sdk,
+  providerSessionId = null,
+  durationMs = 0,
+  outputSchema,
+  error,
+  errorCode,
+}) {
+  return {
+    text: null,
+    structuredResult: undefined,
+    structuredResultSource: null,
+    events: [],
+    usage: {},
+    durationMs,
+    numTurns: 0,
+    model,
+    effort: effort || null,
+    sdk,
+    providerSessionId,
+    provider_session_id: providerSessionId,
+    cancelled: false,
+    error,
+    failureKind: "skipped_capability_mismatch",
+    diagnostics: { claude_error_code: errorCode },
+    capabilitiesUsed: buildCapabilitiesUsed({
+      promptCacheActive: null,
+      thinkingEnabled: null,
+      structuredOutputEnforced: !!outputSchema,
+      subagentInvoked: null,
+      mcpServersUsed: [],
+      nativeSubagentsUsed: [],
+      toolCompactionApplied: false,
+      contextCompactionApplied: null,
+    }),
+  };
+}
+
+/** Typed provider result used by both Claude bridges for the sandbox path. */
+export function claudeSandboxCapabilityMismatchResult(options) {
+  return claudeCapabilityMismatchResult({
+    ...options,
+    error: CLAUDE_SANDBOX_POLICY_UNSUPPORTED,
+    errorCode: "claude_sandbox_policy_unsupported",
+  });
+}