orbitx 0.2.9 → 0.3.2

package/docs/api-reference.md

@@ -17,9 +17,14 @@ Flat index of every public export from `orbitx` (see `src/index.ts`), grouped by
 
 - `BaseAgent`
 - `SimpleAgent`
-- `WorkerAgent` *(experimental)*, type `WorkerAgentRating`
 - Types: `ExtractedSegment`, `ParsedToolCall`
 
+## Swarm — see [Swarm](./swarm.md)
+
+- `SwarmBase` — types `SwarmBaseProps`, `SwarmRunOptions`, `SwarmState`, `SwarmAgentState`, `SwarmStreamChunk`, `SwarmStreamCallback`, `SwarmAgentFailure`
+- `AgentDefinition`, `selectTools()`, `applyTextOverride()` — types `AgentDefinitionProps`, `AgentOverrides`, `AgentFactory`, `AgentFactoryOptions`, `TextOverride`
+- Ready-made definitions: `PlannerAgent`, `ReasonerAgent` (+ `REASONER_PANEL_MS`), `BackendAgent`, `FrontendAgent`, `TestAgent`, `ResearchAgent`, `DefaultAgents()`, and the shared instruction fragments `PLANNER_PROTOCOL` / `WORKER_PROTOCOL` / `TEAM_PROTOCOL` / `PRODUCTION_BAR`
+
 ## Tools — see [Tools](./tools.md)
 
 - `MCPTool`, `generateRefId()`, `normalizeToolOutput()`
@@ -36,18 +41,18 @@ Built-in tool factories, grouped by domain (each domain also exports a `*Tools()
 | Present | `PresentAddTool`, `PresentClearTool`, `PresentGetListTool`, `PresentTools`, `getPresentFolder()` |
 | Question/Answer | `QuestionAnswerTool`, `QuestionAnswerTools` |
 | Utility | `GetCurrentTimeTool`, `DelayTool`, `ReadImageTool`, `UtilTools` |
-| Multi-agent *(experimental)* | `AgentTools(availableAgents, options?)`, `AgentListTool`, `AgentHireTool`, `AgentPromptTool`, `AgentReportTool`, `AgentRegistry`, type `AgentInfo`, type `AgentToolsOptions` — see [Agents](./agents.md#multi-agent-workeragent-experimental) |
+| Swarm | `getAgentTools(options?)`, `AgentTypesTool`, `AgentHireTool`, `AgentFireTool`, `AgentActiveTool`, `AgentPromptTool`, `AgentReportParentTool`, `AgentReportGroupTool`, `AgentToolsRegistry`, types `AgentToolsOptions`, `AgentToolsHandle`, `SwarmController`, `SwarmAgentTypeInfo`, `SwarmAgentInfo`, `AgentToolsEvent`, `AgentToolsAck`, `AgentToolsListener` — see [Swarm](./swarm.md#getagenttoolsoptions) |
 
 ## Skills — see [Skills](./skills.md)
 
 - `Skill`
-- `BackendSecuritySkill`, `BigTaskSkill`, `CodeVerificationSkill`, `LongTaskEfficiencySkill`, `NodeBackendSkill`, `PlannerSkill`, `PresentSkill`, `QuestionAnswerSkill`, `ReactFrontendSkill`, `ResearchSkill`, `ShoppingSkill`, `UiUxDesignSkill`, `WebEndToEndTestSkill`
+- `BackendSecuritySkill`, `BigTaskSkill`, `CodeVerificationSkill`, `LongTaskEfficiencySkill`, `NodeBackendSkill`, `PlannerSkill`, `PresentSkill`, `QuestionAnswerSkill`, `ReactFrontendSkill`, `ResearchSkill`, `UiUxDesignSkill`, `WebEndToEndTestSkill`
 
 ## MCP transport — see [MCP Architecture](./mcp-architecture.md)
 
 - `MCPServer`, `MCPClient`
 - `MCPConnection`, `MCPIPCConnection`, `MCPWSConnection`
-- `MCPComputer` *(experimental)*
+- `MCPComputer`, type `MCPComputerOptions` *(experimental)*
 - `MCPStorage`, `MCPFSStorage`
 - `MCPRNG`
 - `MCPOutputFilter` (`MCPFilter` is a deprecated alias, removed in `1.0.0`)

package/docs/getting-started.md

@@ -1,78 +1,78 @@
-# Getting Started
-
-## Install
-
-```bash
-npm install orbitx
-```
-
-## Your first agent
-
-The fastest path is `SimpleAgent`: give it a provider, an instruction, and a list of tools/skills. It wires up an in-process MCP server/client for you automatically.
-
-```ts
-import { OllamaProvider, SimpleAgent, GetCurrentTimeTool } from "orbitx";
-
-const provider = new OllamaProvider("gemma4:e4b");
-
-const agent = new SimpleAgent({
-  aiProvider: provider,
-  instruction: "You are a helpful assistant.",
-  tools: [GetCurrentTimeTool()],
-});
-
-await agent.run("what is current time?", (chunk) => {
-  process.stdout.write(chunk.content);
-});
-```
-
-`agent.run(prompt, streamCallback)` resolves once the model has stopped calling tools and produced a final answer. The `streamCallback` is optional — omit it if you only care about the eventual message history via `getCurrentAgentStates()`.
-
-See [Streaming](./streaming.md) for the full chunk shape (roles, tool call/result chunks, `done` flag).
-
-## Choosing a provider
-
-```ts
-import { OllamaProvider, DeepSeekProvider, AnthropicProvider, OpenAIProvider } from "orbitx";
-
-new OllamaProvider("gemma4:e4b");                        // local, via Ollama
-new DeepSeekProvider("api-key", "deepseek-v4-flash");     // hosted
-new AnthropicProvider("api-key", "claude-sonnet-5");      // hosted
-new OpenAIProvider("api-key", "gpt-5");                   // hosted
-```
-
-Every provider implements the same `AIProvider` interface, so switching models is a one-line change to your agent's `aiProvider`. Details, capability flags, and the main/image role split are in [Providers](./providers.md).
-
-## Tools and skills up front
-
-`SimpleAgent`'s `tools` and `skills` lists are baked into the system prompt once, at construction time — there's no per-turn tool selection/routing step deciding what the model is allowed to see. If you want the model to be able to call something, put it in `tools` (or bundle it inside a `Skill`). See [Tools](./tools.md) and [Skills](./skills.md).
-
-## Recovering an agent's state
-
-`getCurrentAgentStates()` returns a plain JSON-serializable snapshot: message history (each message carrying its own token usage) and running memory summary. Persist it anywhere; pass it back in as `initData` to resume the exact same agent later (after a process restart, in a new request handler, etc.):
-
-```ts
-import { writeFileSync, existsSync, readFileSync } from "fs";
-
-const initData = existsSync("./state.json")
-  ? JSON.parse(readFileSync("./state.json", "utf-8"))
-  : undefined;
-
-const agent = new SimpleAgent({
-  aiProvider: provider,
-  instruction: "You are a helpful assistant.",
-  tools: [GetCurrentTimeTool()],
-  ...(initData ? { initData } : {}),
-});
-
-// after any run() call:
-writeFileSync("./state.json", JSON.stringify(agent.getCurrentAgentStates()));
-```
-
-Messages are only ever appended, never rewritten. When the conversation grows past the memory threshold, OrbitX retires the working context into `retiredMessages` and resets the model's *active* context (`messagesCompact`) from a running summary (`compactMemory`), so an agent can keep going indefinitely without losing the ability to act on what happened earlier — nothing on disk is ever deleted, it just moves from one array to the other. Mechanics are covered in [Agents](./agents.md#memory-compaction).
-
-## Next steps
-
-- Full control over the MCP transport (custom server/client, IPC, WebSocket, sandboxed Docker execution): [MCP Architecture](./mcp-architecture.md).
-- Writing your own tool or skill: [Tools](./tools.md#writing-a-custom-tool), [Skills](./skills.md#writing-a-custom-skill).
-- Every public export: [API Reference](./api-reference.md).
+# Getting Started
+
+## Install
+
+```bash
+npm install orbitx
+```
+
+## Your first agent
+
+The fastest path is `SimpleAgent`: give it a provider, an instruction, and a list of tools/skills. It wires up an in-process MCP server/client for you automatically.
+
+```ts
+import { OllamaProvider, SimpleAgent, GetCurrentTimeTool } from "orbitx";
+
+const provider = new OllamaProvider("gemma4:e4b");
+
+const agent = new SimpleAgent({
+  aiProvider: provider,
+  instruction: "You are a helpful assistant.",
+  tools: [GetCurrentTimeTool()],
+});
+
+await agent.run("what is current time?", (chunk) => {
+  process.stdout.write(chunk.content);
+});
+```
+
+`agent.run(prompt, streamCallback)` resolves once the model has stopped calling tools and produced a final answer. The `streamCallback` is optional — omit it if you only care about the eventual message history via `getCurrentAgentStates()`.
+
+See [Streaming](./streaming.md) for the full chunk shape (roles, tool call/result chunks, `done` flag).
+
+## Choosing a provider
+
+```ts
+import { OllamaProvider, DeepSeekProvider, AnthropicProvider, OpenAIProvider } from "orbitx";
+
+new OllamaProvider("gemma4:e4b");                        // local, via Ollama
+new DeepSeekProvider("api-key", "deepseek-v4-flash");     // hosted
+new AnthropicProvider("api-key", "claude-sonnet-5");      // hosted
+new OpenAIProvider("api-key", "gpt-5");                   // hosted
+```
+
+Every provider implements the same `AIProvider` interface, so switching models is a one-line change to your agent's `aiProvider`. Details, capability flags, and the main/image role split are in [Providers](./providers.md).
+
+## Tools and skills up front
+
+`SimpleAgent`'s `tools` and `skills` lists are baked into the system prompt once, at construction time — there's no per-turn tool selection/routing step deciding what the model is allowed to see. If you want the model to be able to call something, put it in `tools` (or bundle it inside a `Skill`). See [Tools](./tools.md) and [Skills](./skills.md).
+
+## Recovering an agent's state
+
+`getCurrentAgentStates()` returns a plain JSON-serializable snapshot: message history (each message carrying its own token usage) and running memory summary. Persist it anywhere; pass it back in as `initData` to resume the exact same agent later (after a process restart, in a new request handler, etc.):
+
+```ts
+import { writeFileSync, existsSync, readFileSync } from "fs";
+
+const initData = existsSync("./state.json")
+  ? JSON.parse(readFileSync("./state.json", "utf-8"))
+  : undefined;
+
+const agent = new SimpleAgent({
+  aiProvider: provider,
+  instruction: "You are a helpful assistant.",
+  tools: [GetCurrentTimeTool()],
+  ...(initData ? { initData } : {}),
+});
+
+// after any run() call:
+writeFileSync("./state.json", JSON.stringify(agent.getCurrentAgentStates()));
+```
+
+Messages are only ever appended, never rewritten. When the conversation grows past the memory threshold, OrbitX retires the working context into `retiredMessages` and resets the model's *active* context (`messagesCompact`) from a running summary (`compactMemory`), so an agent can keep going indefinitely without losing the ability to act on what happened earlier — nothing on disk is ever deleted, it just moves from one array to the other. Mechanics are covered in [Agents](./agents.md#memory-compaction).
+
+## Next steps
+
+- Full control over the MCP transport (custom server/client, IPC, WebSocket, sandboxed Docker execution): [MCP Architecture](./mcp-architecture.md).
+- Writing your own tool or skill: [Tools](./tools.md#writing-a-custom-tool), [Skills](./skills.md#writing-a-custom-skill).
+- Every public export: [API Reference](./api-reference.md).

package/docs/index.md

@@ -1,23 +1,24 @@
-# OrbitX Docs
-
-OrbitX is a TypeScript SDK for building AI agents: pluggable model providers, a tool/skill system, an MCP-based execution layer (in-process, IPC, or WebSocket), and a resumable agent loop with automatic memory compaction.
-
-This directory is written for two audiences at once:
-
-- **Humans** learning the library for the first time — read top to bottom.
-- **AI coding agents** working inside a project that depends on `orbitx` — each page is self-contained enough to be read on its own when you only need one topic (e.g. "how do I define a tool").
-
-## Pages
-
-1. [Getting Started](./getting-started.md) — install, first agent, streaming output, resuming state.
-2. [Providers](./providers.md) — `AIProvider`, the four built-in providers, capabilities, main/image roles.
-3. [Agents](./agents.md) — `BaseAgent` vs `SimpleAgent`, the run loop, memory compaction, tokens, and multi-agent (`WorkerAgent`/`AgentTools`).
-4. [Tools](./tools.md) — the `MCPTool` shape, built-in tool catalog, writing your own tools.
-5. [Skills](./skills.md) — bundling instructions + tools, built-in skill catalog, writing your own.
-6. [MCP Architecture](./mcp-architecture.md) — `MCPServer`/`MCPClient`/connections, in-process vs IPC vs WS, `MCPComputer` sandbox.
-7. [Streaming](./streaming.md) — the `StreamCallback` chunk shape and how to consume it.
-8. [API Reference](./api-reference.md) — flat index of every public export from `orbitx`.
-
-## The shape of the library, in one paragraph
-
-You construct one or more `AIProvider` instances (OpenAI, Anthropic, DeepSeek, or Ollama), a list of `MCPTool`s and/or `Skill`s (a skill is just instructions + tools bundled together), and hand them to `SimpleAgent` (or `BaseAgent` for full control over the underlying MCP transport). Calling `agent.run(prompt, streamCallback)` drives a loop: send the conversation + tool schemas to the provider, dispatch any tool calls the model requests, feed results back, repeat until the model stops calling tools. Everything the model can see (tools, skills, instructions) is decided once, up front — there's no dynamic tool routing/selection step. Long conversations are handled by summarizing into a running `memory` string instead of ever deleting messages; the full history is preserved in `getCurrentAgentStates()` for persistence/resume.
+# OrbitX Docs
+
+OrbitX is a TypeScript SDK for building AI agents: pluggable model providers, a tool/skill system, an MCP-based execution layer (in-process, IPC, or WebSocket), and a resumable agent loop with automatic memory compaction.
+
+This directory is written for two audiences at once:
+
+- **Humans** learning the library for the first time — read top to bottom.
+- **AI coding agents** working inside a project that depends on `orbitx` — each page is self-contained enough to be read on its own when you only need one topic (e.g. "how do I define a tool").
+
+## Pages
+
+1. [Getting Started](./getting-started.md) — install, first agent, streaming output, resuming state.
+2. [Providers](./providers.md) — `AIProvider`, the four built-in providers, capabilities, main/image roles.
+3. [Agents](./agents.md) — `BaseAgent` vs `SimpleAgent`, the run loop, memory compaction, tokens.
+4. [Swarm](./swarm.md) — many agents that hire, task, and report to each other: `SwarmBase`, `AgentDefinition`, `getAgentTools()`.
+5. [Tools](./tools.md) — the `MCPTool` shape, built-in tool catalog, writing your own tools.
+6. [Skills](./skills.md) — bundling instructions + tools, built-in skill catalog, writing your own.
+7. [MCP Architecture](./mcp-architecture.md) — `MCPServer`/`MCPClient`/connections, in-process vs IPC vs WS, `MCPComputer` sandbox.
+8. [Streaming](./streaming.md) — the `StreamCallback` chunk shape and how to consume it.
+9. [API Reference](./api-reference.md) — flat index of every public export from `orbitx`.
+
+## The shape of the library, in one paragraph
+
+You construct one or more `AIProvider` instances (OpenAI, Anthropic, DeepSeek, or Ollama), a list of `MCPTool`s and/or `Skill`s (a skill is just instructions + tools bundled together), and hand them to `SimpleAgent` (or `BaseAgent` for full control over the underlying MCP transport). Calling `agent.run(prompt, streamCallback)` drives a loop: send the conversation + tool schemas to the provider, dispatch any tool calls the model requests, feed results back, repeat until the model stops calling tools. Everything the model can see (tools, skills, instructions) is decided once, up front — there's no dynamic tool routing/selection step. Long conversations are handled by summarizing into a running `memory` string instead of ever deleting messages; the full history is preserved in `getCurrentAgentStates()` for persistence/resume.

package/docs/mcp-architecture.md

@@ -30,7 +30,7 @@ mcpClient.callTool(name: string, inputs: Record<string, any>, toolCallId?: strin
 mcpClient.setExecuteProviderHandler(handler: (toolCallId: string, type: ProviderType, input: Record<string, any>) => Promise<{ output: Record<string, any> }>): void;
 ```
 
-`toolCallId` on `callTool()` and the handler installed via `setExecuteProviderHandler()` are what `BaseAgent` wires up automatically so `mcp.executeProvider(...)` works inside a tool's `execute()` — see [Custom `MCP` subclasses](#custom-mcp-subclasses) below. You don't need to call either yourself unless you're driving `MCPClient` outside of `BaseAgent`.
+`toolCallId` on `callTool()` and the handler installed via `setExecuteProviderHandler()` are what `BaseAgent` wires up automatically so `mcp.executeProvider(...)` works inside a tool's `execute()` — see [Custom `MCP` subclasses](#custom-mcp-subclasses) below. You don't need to call either yourself unless you're driving `MCPClient` outside of `BaseAgent`. A `SwarmBase` takes that handler back after building each agent, so in a swarm the provider call is answered by the swarm — see [Swarm](./swarm.md#providers-a-tool-reaches-for).
 
 This is what you pass into `BaseAgent({ mcpClient, ... })`. `envID` scopes storage/RNG state per logical environment/session — pass a stable id (e.g. a user or conversation id) if you want isolated tool state per agent instance sharing a server. Accepting an array of connections lets one client fan out across multiple servers.
 
@@ -82,12 +82,35 @@ const connection = computer.getConnection();
 await computer.stop();
 ```
 
-- `mountPath` — host directory mounted into the container (this is what filesystem tools inside the sandbox actually touch).
-- `ports` — ports to expose from the container, or `"*"` for host network mode (Linux only, or Windows via WSL2).
-- `getConnection()` — returns a ready `MCPConnection`: IPC on Linux/macOS, WebSocket on Windows (auth token generated automatically).
-- `stop()` — kills the container.
+```ts
+new MCPComputer(mountPath: string, ports: number[] | "*", image?: string, options?: MCPComputerOptions);
+```
+
+- `mountPath` — host directory mounted into the container (this is what filesystem tools inside the sandbox actually touch). Four subdirectories are created under it and mounted: `workspace`, `mcp-server-storage`, `presents`, `user-inputs`.
+- `ports` — ports to publish from the container, or `"*"` for host network mode. **`"*"` is Linux-only**: on Windows and macOS the container joins a VM's network namespace, so nothing it binds is reachable from your machine and published ports are ignored — the constructor throws rather than letting that surface later as a connection timeout.
+- `image` — defaults to `aliafsordeh/orbitx-sandbox:0.2`.
+- `start()` — verifies the Docker daemon is reachable, prepares the mount, launches the container, waits for its ready log, and then waits for the connection endpoint to actually accept traffic. It resolves only when the sandbox is genuinely reachable, and rejects with the container's own output when it is not.
+- `getConnection(wsHost?)` — returns a ready `MCPConnection`, cached (repeated calls hand back the same object). In `"ws"` mode it must be called after `start()`, since the port is only chosen there.
+- `waitUntilConnected(timeoutMs?)` — optional; resolves once the transport is carrying traffic, if you want the MCP handshake up before the first tool call.
+- `getPresentsHostPath()`, `getConnectionPort()`, `getContainerName()`, `isRunning()` — host-side accessors.
+- `stop()` — removes the container, closes the connection, and cleans up the socket directory. Idempotent.
+
+`MCPComputerOptions`:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `connectionMode` | `"ipc"` on Linux, `"ws"` elsewhere | Transport between your process and the sandbox. |
+| `readyTimeoutMs` | `60_000` | Wait for the sandbox's ready log once the container is running. |
+| `pullTimeoutMs` | `300_000` | Inactivity budget while docker pulls the image, so a first run isn't killed mid-download. |
+| `handshakeTimeoutMs` | `20_000` | Wait for the endpoint to accept traffic after the ready log. |
+| `onLog` | — | `(line, "stdout" \| "stderr") => void`; receives everything the container writes. |
+| `dockerBin` | `"docker"` | Override the executable (e.g. `"podman"`, or an absolute path). |
+
+The transport default is not a style choice: Docker Desktop on Windows and macOS runs the daemon inside a VM and shares the mount over a network filesystem, which cannot carry a unix-domain socket. IPC therefore only works when the daemon and your process share a kernel, and WebSocket (loopback-published, with an auto-generated auth token) is used everywhere else.
 
-Requires the `aliafsordeh/orbitx-sandbox:0.1` image (pull it, or build it yourself from the `Dockerfile.sandbox` at the repo root).
+Requires the `aliafsordeh/orbitx-sandbox:0.2` image (pull it, or build it yourself from the `Dockerfile.sandbox` at the repo root). Note that the sandbox's own stdout/stderr are drained continuously for the life of the container — a piped-but-unread stream fills its OS buffer after ~64KB and blocks the sandbox process on its next write, which surfaces much later as tool calls that never return.
+
+Servers started *inside* the sandbox must bind `0.0.0.0`, not `localhost`, to be reachable through a published port; `getInstructions()` tells agents this.
 
 ## Storage and RNG
 
@@ -135,6 +158,48 @@ class AllowlistPolicy extends MCPExecutionPolicy {
 const mcpClient = new MCPClient(envID, connection, storage, rng, undefined, new AllowlistPolicy(["get_current_time"]));
 ```
 
+### `MCPAutoExecutionPolicy` — an AI-judged policy
+
+`MCPAutoExecutionPolicy` (`src/core/mcp-auto-execution-policy.ts`) is a built-in `MCPExecutionPolicy` that asks a model, via [`AIASK`](./agents.md#aiask), whether each call is safe — an alternative to a hand-written allowlist/denylist for cases where "safe" isn't a fixed rule. It's built to keep the expensive part (an actual model call) as rare as possible rather than reviewing every single tool call:
+
+```ts
+new MCPAutoExecutionPolicy({
+  aiModel: AIProvider | AgentProviderEntry[];
+  instruction?: string;   // extra context appended after the built-in default instruction — e.g. what the user actually asked the agent to do
+  onVerdict?: (request: MCPToolCallRequest, verdict: { harmful: boolean; reason: string }) => void;
+  watchedTools?: string[];   // default: ["bash-run", "fs-write-file", "fs-edit-file", "fs-delete", "fs-move"]
+  scopeDir?: string;         // default: process.cwd() at construction time
+});
+```
+
+Three cost-cutting layers, checked in order inside `authorize(request)`:
+
+1. **Not in `watchedTools`?** Authorized immediately — no model call, no verdict recorded at all. Most tools (`get-current-time`, `todo-*`, `fs-read-file`, ...) have nothing dangerous to weigh, so the default watch list is only the destructive/execution tools: `bash-run` and the fs tools that write, edit, delete, or move something. Pass your own `watchedTools` to widen or narrow that set.
+2. **A watched *fs* call whose path(s) all resolve inside `scopeDir`?** Also authorized immediately, no model call — a write/edit/delete confined to the expected working directory doesn't need judgment. Paths are resolved the same way the fs tools themselves resolve them (relative to `process.cwd()`); `fs-move` needs *both* `from` and `to` inside scope to skip the model — one path escaping scope is enough to escalate. `bash-run` has no path field to check here, so it always falls through to the model.
+3. **Otherwise, ask the model** — via `AIASK`, on `{ toolName, inputs }`. `authorize()` denies whenever the verdict comes back `harmful: true`, or whenever `AIASK` itself couldn't reach a valid verdict after its own retries (fails closed, not open).
+
+Whenever a call *does* reach the model, file content is stripped out first — `fs-write-file`/`fs-edit-file`'s `content` field is replaced with `<omitted, N bytes>` before it's ever sent, since the file's contents aren't relevant to judging whether the *call* is safe, and including it would make every write/edit review needlessly expensive. The model judges those calls by path and other inputs alone.
+
+`authorize()`'s boolean return only tells `MCPClient` whether to proceed — it doesn't surface *why* a call was judged (or skipped as) harmful/safe, which callers usually want (to log it, or show the user what got blocked). Three ways to get that — all populated for both a model-reviewed call and one that was authorized locally via the path-scope check, but never for a call outside `watchedTools`, which is never reviewed at all:
+
+- `policy.getVerdict(toolCallId)` — the verdict recorded for one specific call, if it carried a `toolCallId`.
+- `policy.getLastVerdict()` — the most recent verdict of any reviewed call, useful when only one policy instance is ever in flight at a time.
+- `onVerdict` — called synchronously right after every reviewed `authorize()` decision, with both the request and the verdict.
+
+```ts
+const policy = new MCPAutoExecutionPolicy({
+  aiModel,
+  scopeDir: "/home/me/project",   // writes/edits/deletes/moves confined here skip the model entirely
+  onVerdict: (request, verdict) => {
+    if (verdict.harmful) console.warn(`blocked ${request.toolName}: ${verdict.reason}`);
+  },
+});
+
+const mcpClient = new MCPClient(envID, connection, storage, rng, undefined, policy);
+```
+
+Even with those shortcuts, a call that does reach the model costs at least one real call (more if `AIASK`'s own retry loop kicks in — see [`AIASK`](./agents.md#aiask)) — this still trades latency/cost for judgment a fixed rule can't express, just as rarely as the watch list and scope check allow. Reach for a plain `MCPExecutionPolicy` subclass first when a simple allowlist/denylist actually covers the case.
+
 ## Custom `MCP` subclasses
 
 Both `MCPServer` and `MCPClient` extend the abstract `MCP` class — `getStorage()`, `getRNG()`, and `executeProvider(toolCallId, type, input)`. Tool `execute` functions receive the calling `MCP` instance directly, as their 4th argument (after a `toolCallId` — see [Tools](./tools.md#the-mcptool-shape)), so a tool can reach storage/RNG scoped to whichever client dispatched the call.