Merge remote-tracking branch 'origin/main' into jesse/non-clawhub-untrusted-installs

# Conflicts:
#	src/agents/tools/crestodian-tool.ts
#	src/cli/hooks-cli.test.ts
#	src/plugins/bundled-sources.ts

docs/plugins/building-plugins.md

@@ -25,7 +25,7 @@ Bare package specs still install from npm during the launch cutover. Use the
 
 ## Requirements
 
-- Node 22.19+, Node 23.11+, or Node 24+, and `npm` or `pnpm`.
+- Node 22.22.3+, Node 24.15+, or Node 25.9+, and `npm` or `pnpm`.
 - TypeScript ESM modules.
 - For in-repo bundled plugin work, clone the repository and run `pnpm install`.
   Source-checkout plugin development is pnpm-only because OpenClaw discovers

docs/plugins/cli-backend-plugins.md

@@ -210,7 +210,7 @@ only for behavior that really belongs to the backend.
 | ---------------------------------- | --------------------------------------------------------------------------- |
 | `normalizeConfig(config, context)` | Rewrite legacy user config after merge                                      |
 | `resolveExecutionArgs(ctx)`        | Add request-scoped flags such as thinking effort or side-question isolation |
-| `prepareExecution(ctx)`            | Create temporary auth or config bridges before launch                       |
+| `prepareExecution(ctx)`            | Create temporary auth, config, or environment bridges before launch         |
 | `transformSystemPrompt(ctx)`       | Apply a final CLI-specific system prompt transform                          |
 | `textTransforms`                   | Bidirectional prompt/output replacements                                    |
 | `defaultAuthProfileId`             | Prefer a specific OpenClaw auth profile                                     |
@@ -224,6 +224,10 @@ only for behavior that really belongs to the backend.
 Keep these hooks provider-owned. Do not add CLI-specific branches to core when
 a backend hook can express the behavior.
 
+`prepareExecution(ctx)` receives `ctx.contextTokenBudget`, the effective token
+limit selected for the run. Backends that own native compaction can map that
+budget into their CLI-specific launch contract.
+
 `runtimeArtifact` is plugin-owned and is not user-overridable. It is consulted
 only when a live inference turn mints or revalidates verified setup authority;
 normal CLI runs do not require it. A backend without this declaration cannot

docs/plugins/codex-harness-reference.md

@@ -130,7 +130,7 @@ flags, and plugin allow/deny references into this block. Explicit canonical
 ## App-server transport
 
 For ordinary harness turns, OpenClaw starts the managed Codex binary shipped
-with the official plugin (currently `@openai/codex` `0.144.1`):
+with the official plugin (currently `@openai/codex` `0.144.3`):
 
 ```bash
 codex app-server --listen stdio://
@@ -586,7 +586,7 @@ If discovery fails or times out, OpenClaw uses a bundled fallback catalog:
 | `gpt-5.4-mini` | GPT-5.4-Mini | low, medium, high, xhigh |
 
 <Note>
-The current bundled harness is `@openai/codex` `0.144.1`. A `model/list` probe
+The current bundled harness is `@openai/codex` `0.144.3`. A `model/list` probe
 against that bundled app-server returned these public picker rows:
 
 | Model id        | Input modalities | Reasoning efforts                    |

docs/plugins/codex-supervision.md

@@ -304,16 +304,19 @@ codex unarchive <thread-id>
 
 Paired nodes expose the versioned read-only
 `codex.appServer.threads.list.v1` and
-`codex.appServer.thread.turns.list.v1` commands. The Gateway receives normalized
+`codex.appServer.thread.turns.list.v1` commands. Native node hosts with the
+Codex CLI available also expose the allowlisted `codex.terminal.resume.v1`
+command. The Gateway receives normalized
 metadata and explicitly requested bounded transcript pages, never raw App Server
-endpoints. The current node invoke
-transport is request/response only, so it cannot carry the long-lived event,
-approval, and streaming lifecycle required by the Codex harness.
+endpoints. Opening a row in the operator terminal runs `codex resume <thread-id>`
+on the owning host and relays that command's PTY; it does not expose a general
+shell or gateway-supplied argv.
 
-For that reason, remote rows remain visible but do not offer **Continue** or
+The terminal relay does not provide the harness continuation or archive ownership
+contracts. Remote rows therefore remain visible but do not offer **Continue** or
 **Archive**, even when the remote thread is idle. Use Codex on that computer
-until a node-side streaming runner bridge exists for continuation and a safe
-runner-ownership boundary exists for archive.
+through **Open in terminal**, or use a future continuation flow with a safe
+runner-ownership boundary.
 
 ## Metadata and permissions
 

docs/plugins/google-meet.md

@@ -121,6 +121,15 @@ If the browser fallback hits a Google login or Meet permission blocker, the tool
 
 Set `"mode": "transcribe"` to skip the duplex realtime bridge (no BlackHole/SoX requirement, no talk-back). Transcribe-mode Chrome joins also skip OpenClaw's microphone/camera permission grant and the Meet **Use microphone** path; if Meet shows the audio-choice interstitial, automation tries **Continue without microphone** first. Managed Chrome transports in this mode install a best-effort Meet caption observer. `googlemeet status --json` and `googlemeet doctor` report `captioning`, `captionsEnabledAttempted`, `transcriptLines`, `lastCaptionAt`, `lastCaptionSpeaker`, `lastCaptionText`, and a `recentTranscript` tail.
 
+For the bounded session transcript, read the exact tracked Meet tab:
+
+```bash
+openclaw googlemeet transcript <session-id>
+openclaw googlemeet transcript <session-id> --since <next-index> --json
+```
+
+The observer keeps at most 2,000 completed caption lines in the Meet page. Visible progressive text stays in the status health tail until the caption row completes, so saving `nextIndex` cannot skip a later text expansion; leaving finalizes visible rows before the snapshot. `droppedLines` reports lines lost from the head when the cap is exceeded. The four most recently ended session transcripts remain readable until the gateway restarts. Older ended transcripts return `evicted: true`. This is intentionally runtime memory, not durable meeting-history storage: restarting the gateway, closing the tab before a snapshot, or exceeding the documented caps can lose captions.
+
 For a yes/no listen probe:
 
 ```bash
@@ -838,7 +847,8 @@ Agents use the `google_meet` tool:
 | `attendance`            | List participants and participant sessions                                                        |
 | `export`                | Write the artifacts/attendance/transcript/manifest bundle; set `"dryRun": true` for manifest-only |
 | `recover_current_tab`   | Focus/inspect an existing Meet tab without opening a new one                                      |
-| `leave`                 | End a session (hangs up the underlying Twilio call for delegated sessions)                        |
+| `transcript`            | Read the bounded caption transcript; `sinceIndex` resumes from the previous `nextIndex`           |
+| `leave`                 | End a session (Chrome clicks Leave; closes only tabs it opened; Twilio hangs up)                  |
 | `end_active_conference` | End the active Google Meet conference for an API-managed space                                    |
 | `speak`                 | Make the realtime agent speak immediately, given `sessionId` and `message`                        |
 | `test_speech`           | Create/reuse a session, trigger a known phrase, return Chrome health                              |
@@ -846,6 +856,8 @@ Agents use the `google_meet` tool:
 
 `test_speech` always forces `mode: "agent"` or `"bidi"` and fails if asked to run in `mode: "transcribe"`, because observe-only sessions cannot emit speech. Its `speechOutputVerified` result is based on realtime audio output bytes increasing during that call, so a reused session with older audio does not count as a fresh check.
 
+For Chrome transports, `leave` keeps a reused user-owned tab open after clicking Meet's Leave call button. Tabs opened by OpenClaw are closed after departure.
+
 Use `transport: "chrome"` when Chrome runs on the Gateway host, `transport: "chrome-node"` when it runs on a paired node. In both cases the model providers and `openclaw_agent_consult` run on the Gateway host, so model credentials stay there. Agent-mode logs include the resolved transcription provider/model at bridge startup and the TTS provider/model/voice/output format/sample rate after each synthesized reply. Raw `mode: "realtime"` is still accepted as a legacy compatibility alias for `mode: "agent"`, but it is no longer advertised in the tool's `mode` enum.
 
 `create` with an API-backed room and explicit access policy:

docs/plugins/hooks.md

@@ -40,7 +40,6 @@ export default definePluginEntry({
             description: `Allow search query: ${String(event.params.query ?? "")}`,
             severity: "info",
             timeoutMs: 60_000,
-            timeoutBehavior: "deny",
           },
         };
       },
@@ -251,6 +250,7 @@ type BeforeToolCallResult = {
     description: string;
     severity?: "info" | "warning" | "critical";
     timeoutMs?: number;
+    /** @deprecated Unresolved approvals always deny. */
     timeoutBehavior?: "allow" | "deny";
     allowedDecisions?: Array<"allow-once" | "allow-always" | "deny">;
     pluginId?: string;

docs/plugins/manage-plugins.md

@@ -46,7 +46,10 @@ removed, only disabled.
 Catalog and search access require `operator.read`. Install, enable, disable,
 remove, and MCP server changes require `operator.admin`. A ClawHub install is
 performed by the Gateway and preserves its trust, integrity, and plugin-install
-policy checks.
+policy checks. Enabling an installed plugin as an administrator also records
+that explicit trust by adding the selected plugin to an existing restrictive
+`plugins.allow` list. An explicit `plugins.deny` entry remains authoritative and
+must be removed before enabling the plugin.
 
 Installing or removing plugin code requires a Gateway restart. Enablement
 changes can be applied without a restart when the installed plugin and current

docs/plugins/onepassword.md

@@ -0,0 +1,197 @@
+---
+summary: "Use the optional 1Password plugin as an audited agent secrets broker"
+read_when:
+  - You want agents to request curated 1Password secrets
+  - You need per-secret approval policy and audit history
+  - You are configuring a 1Password service account for OpenClaw
+title: "1Password secrets broker"
+---
+
+# 1Password secrets broker
+
+The bundled `onepassword` plugin gives agents one policy-controlled tool for
+reading a curated set of 1Password fields. It is disabled by default and does
+nothing until `plugins.entries.onepassword.config` is present.
+
+This is an agent tool, not a SecretRef provider. It does not inject environment
+variables or resolve OpenClaw config secrets.
+
+## Security model
+
+- Service-account authentication only. The token stays in a local credentials
+  file and is never accepted in `openclaw.json`.
+- Curated registry only. Agents can list configured slugs, but the plugin never
+  enumerates a 1Password vault.
+- Per-slug `auto`, `approve`, or `deny` policy.
+- Approval grants expire. A cached value never bypasses current policy.
+- Every access attempt is recorded in OpenClaw's shared SQLite state. Audit
+  rows include the supplied reason; keep reasons non-sensitive. The broker
+  never copies a fetched value or the service token into an audit row.
+- After the current tool execution, OpenClaw-owned transcript persistence
+  replaces a successful `get` value with redacted metadata.
+- The value is model-visible for that execution. If the model copies it into a
+  later tool call or reply, that separate record is outside this plugin's
+  persistence hook. Keep policies narrow and do not ask the model to echo a
+  value.
+- The plugin invokes `op` once per cache miss. It does not retry rate limits or
+  other failures.
+
+Give the service account read access only to the vaults and items registered in
+the plugin config.
+
+## Before you begin
+
+You need:
+
+- the 1Password CLI (`op`) installed on the Gateway host
+- a 1Password service account with access to the selected items
+- a dedicated service-account token file
+
+Enable the bundled plugin:
+
+```bash
+openclaw plugins enable onepassword
+```
+
+Create the token directory and file under the OpenClaw state directory:
+
+```bash
+mkdir -p ~/.openclaw/credentials/onepassword
+chmod 700 ~/.openclaw/credentials/onepassword
+printf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \
+  ~/.openclaw/credentials/onepassword/service-account-token
+chmod 600 ~/.openclaw/credentials/onepassword/service-account-token
+unset OP_SERVICE_ACCOUNT_TOKEN
+```
+
+When `OPENCLAW_STATE_DIR` is set, replace `~/.openclaw` with that directory.
+The plugin warns once when the token file is readable or writable by group or
+other users.
+
+## Configure registered secrets
+
+Add plugin config to `openclaw.json`:
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "onepassword": {
+        "enabled": true,
+        "config": {
+          "vault": "Automation",
+          "defaultPolicy": "approve",
+          "cacheTtlSeconds": 300,
+          "grantTtlHours": 720,
+          "opTimeoutMs": 15000,
+          "items": {
+            "repository-token": {
+              "item": "Repository automation token",
+              "field": "credential",
+              "policy": "approve",
+              "description": "Token for repository automation",
+            },
+            "model-key": {
+              "item": "Model provider key",
+              "vault": "Agent credentials",
+              "policy": "auto",
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Slugs use lowercase letters, numbers, and hyphens, start with a letter or
+number, and contain at most 64 characters. A registry can contain up to 32
+slugs; descriptions can contain up to 200 characters. `field` accepts one field
+label or ID, must not contain a comma, and defaults to `credential`.
+An item-level `vault` overrides the default vault. `opBin` can set an absolute
+path to the `op` executable; otherwise the plugin resolves `op` from `PATH`.
+Item titles must not start with a hyphen.
+
+## Use the agent tool
+
+The tool name is `onepassword`.
+
+List registered slugs:
+
+```json
+{ "action": "list" }
+```
+
+The result contains only the slug, description, policy, and whether a standing
+grant is active. It never contains a secret value and does not query 1Password.
+
+Request one secret:
+
+```json
+{
+  "action": "get",
+  "slug": "repository-token",
+  "reason": "Authenticate the requested repository operation"
+}
+```
+
+`reason` is required, must be non-empty, and is limited to 300 characters. A
+successful `get` returns the value plus the configured slug, item title, and
+field label.
+
+## Policy tiers and approvals
+
+- `auto`: fetch immediately and audit the request.
+- `deny`: block and audit the request.
+- `approve`: use an unexpired standing grant, or ask a human to allow once,
+  always, or deny.
+
+Allow once authorizes only the current tool call. Allow always writes a standing
+grant for that agent and slug to SQLite; other agents must receive their own
+approval. OpenClaw offers allow always only when the caller has a concrete agent
+identity. The grant expires after `grantTtlHours`, which defaults to 720 hours.
+An unresolved or timed-out approval denies the request; the maximum approval
+wait is 600 seconds. The plugin retains up to 1,024 standing grants; at that
+bound, the oldest grant is evicted and its agent must approve the next access.
+
+The in-memory cache defaults to 300 seconds and is bounded by the configured
+slug registry. Set `cacheTtlSeconds` to `0` to disable it. Policy is evaluated
+before every cache lookup, and cache hits are audited. Runtime config reloads
+take effect at each policy and execution boundary; disabling the plugin or
+removing, denying, or retargeting a slug invalidates pending authorization and
+cached values.
+
+## Inspect status and audit history
+
+Show readiness and registry counts:
+
+```bash
+openclaw onepassword status
+```
+
+This reports whether the token file exists, whether `op` resolved and its path,
+the registered item count, and per-policy counts. It never reads or prints the
+token or secret values.
+
+Show the 50 most recent audit rows:
+
+```bash
+openclaw onepassword audit
+openclaw onepassword audit --limit 100
+```
+
+Rows are newest first and show timestamp, agent, slug, outcome, and a truncated
+reason. The reason is stored as supplied; the broker never adds the fetched
+value to the audit log.
+
+## 1Password CLI behavior
+
+Each cache miss runs `op item get` with the configured item, vault, and exact
+field selector, JSON output, a bounded timeout, and `--cache=false`. The child
+receives only that field rather than the full item. Only
+`OP_SERVICE_ACCOUNT_TOKEN` and `HOME` are present in the child environment.
+
+The plugin makes one attempt. `RATE_LIMITED` errors should be handled by waiting
+before a later agent request; the plugin does not create an automatic retry
+loop. Other stable error codes distinguish missing tokens or binaries, missing
+items or fields, authentication failures, timeouts, and other `op` failures.

docs/plugins/plugin-inventory.md

@@ -51,7 +51,7 @@ Each entry lists the package, distribution route, and description.
 
 ## Core npm package
 
-64 plugins
+66 plugins
 
 - **[admin-http-rpc](/plugins/reference/admin-http-rpc)** (`@openclaw/admin-http-rpc`) - included in OpenClaw. OpenClaw admin HTTP RPC endpoint.
 
@@ -133,6 +133,8 @@ Each entry lists the package, distribution route, and description.
 
 - **[ollama](/plugins/reference/ollama)** (`@openclaw/ollama-provider`) - included in OpenClaw. Adds Ollama, Ollama Cloud model provider support to OpenClaw.
 
+- **[onepassword](/plugins/reference/onepassword)** (`@openclaw/onepassword`) - included in OpenClaw. Curated 1Password secrets broker with approval policy and SQLite audit history.
+
 - **[open-prose](/plugins/reference/open-prose)** (`@openclaw/open-prose`) - included in OpenClaw. OpenProse VM skill pack with a /prose slash command.
 
 - **[openai](/plugins/reference/openai)** (`@openclaw/openai-provider`) - included in OpenClaw. Adds OpenAI model provider support to OpenClaw.
@@ -145,6 +147,8 @@ Each entry lists the package, distribution route, and description.
 
 - **[policy](/plugins/reference/policy)** (`@openclaw/policy`) - included in OpenClaw. Adds policy-backed doctor checks for workspace conformance.
 
+- **[reef](/plugins/reference/reef)** (`@openclaw/reef`) - included in OpenClaw. Guarded end-to-end encrypted claw channel.
+
 - **[runway](/plugins/reference/runway)** (`@openclaw/runway-provider`) - included in OpenClaw. Adds video generation provider support.
 
 - **[senseaudio](/plugins/reference/senseaudio)** (`@openclaw/senseaudio-provider`) - included in OpenClaw. Adds media understanding provider support.
@@ -183,7 +187,7 @@ Each entry lists the package, distribution route, and description.
 
 ## Official external packages
 
-70 plugins
+71 plugins
 
 - **[acpx](/plugins/reference/acpx)** (`@openclaw/acpx`) - npm; ClawHub. OpenClaw ACP runtime backend with plugin-owned session and transport management.
 
@@ -269,6 +273,8 @@ Each entry lists the package, distribution route, and description.
 
 - **[msteams](/plugins/reference/msteams)** (`@openclaw/msteams`) - npm; ClawHub. OpenClaw Microsoft Teams channel plugin for bot conversations.
 
+- **[mxc](/plugins/reference/mxc)** (`@openclaw/mxc-sandbox`) - npm; ClawHub. OS-level sandboxed tool execution via MXC for MXC-capable Windows hosts: runs commands in ProcessContainer (Windows) with configured MXC policy files.
+
 - **[nextcloud-talk](/plugins/reference/nextcloud-talk)** (`@openclaw/nextcloud-talk`) - npm; ClawHub. OpenClaw Nextcloud Talk channel plugin for conversations.
 
 - **[nostr](/plugins/reference/nostr)** (`@openclaw/nostr`) - npm; ClawHub. OpenClaw Nostr channel plugin for NIP-04 encrypted direct messages.

docs/plugins/plugin-permission-requests.md

@@ -63,7 +63,6 @@ export default definePluginEntry({
               ? ["allow-once", "deny"]
               : ["allow-once", "allow-always", "deny"],
           timeoutMs: 120_000,
-          timeoutBehavior: "deny",
           onResolution(decision) {
             console.log(`deploy approval resolved: ${decision}`);
           },
@@ -99,10 +98,15 @@ available approval surfaces, and waits for a decision.
 | `allow-once`      | The current call continues.                                               |
 | `allow-always`    | The current call continues and the decision is passed to the plugin.      |
 | `deny`            | The call is blocked with a denied tool result.                            |
-| Timeout           | The call is blocked unless `timeoutBehavior` is `"allow"`.                |
+| Timeout           | The call is blocked.                                                      |
 | Cancellation      | The call is blocked when the run is aborted.                              |
 | No approval route | The call is blocked because no connected approval surface can resolve it. |
 
+Only the exact `allow-once` and `allow-always` decisions permitted by the
+request allow execution. Unknown, malformed, mismatched, missing, and timed-out
+decisions fail closed. The legacy `timeoutBehavior` field remains accepted for
+plugin compatibility but is deprecated and ignored; do not set it in new hooks.
+
 `allow-always` is only durable when the requesting plugin or runtime implements
 that persistence. For ordinary `before_tool_call.requireApproval` hooks,
 OpenClaw treats `allow-once` and `allow-always` as approval decisions for the

docs/plugins/reference.md

@@ -15,5 +15,5 @@ This page is generated from `extensions/*/package.json` and
 pnpm plugins:inventory:gen
 ```
 
-Use [Plugin inventory](/plugins/plugin-inventory) to browse all 136
+Use [Plugin inventory](/plugins/plugin-inventory) to browse all 139
 generated plugin reference pages by distribution, package, and description.

docs/plugins/reference/acpx.md

@@ -16,7 +16,19 @@ OpenClaw ACP runtime backend with plugin-owned session and transport management.
 
 ## Surface
 
-skills
+skills; session catalog: pi
+
+## Pi native sessions
+
+The bundled runtime auto-detects Pi's session store on the Gateway and paired
+nodes. Stored sessions appear in the **Pi** sessions-sidebar group, with
+read-only transcript browsing from Pi's documented JSONL session format. The
+catalog honors project and global `settings.json` session directories plus
+`PI_CODING_AGENT_DIR` and `PI_CODING_AGENT_SESSION_DIR`. Relative paths resolve
+from the directory containing their `settings.json` file.
+
+Turn **Pi Session Catalog** off under **Config > Plugins > ACPX Runtime** to
+disable discovery. It is enabled by default.
 
 ## Related docs
 

docs/plugins/reference/mxc.md

@@ -0,0 +1,19 @@
+---
+summary: "OS-level sandboxed tool execution via MXC for MXC-capable Windows hosts: runs commands in ProcessContainer (Windows) with configured MXC policy files."
+read_when:
+  - You are installing, configuring, or auditing the mxc plugin
+title: "Mxc plugin"
+---
+
+# Mxc plugin
+
+OS-level sandboxed tool execution via MXC for MXC-capable Windows hosts: runs commands in ProcessContainer (Windows) with configured MXC policy files.
+
+## Distribution
+
+- Package: `@openclaw/mxc-sandbox`
+- Install route: npm; ClawHub
+
+## Surface
+
+plugin

docs/plugins/reference/onepassword.md

@@ -0,0 +1,23 @@
+---
+summary: "Curated 1Password secrets broker with approval policy and SQLite audit history."
+read_when:
+  - You are installing, configuring, or auditing the onepassword plugin
+title: "Onepassword plugin"
+---
+
+# Onepassword plugin
+
+Curated 1Password secrets broker with approval policy and SQLite audit history.
+
+## Distribution
+
+- Package: `@openclaw/onepassword`
+- Install route: included in OpenClaw
+
+## Surface
+
+contracts: tools
+
+## Related docs
+
+- [onepassword](/plugins/onepassword)

docs/plugins/reference/opencode.md

@@ -1,5 +1,5 @@
 ---
-summary: "Adds OpenCode model provider support to OpenClaw."
+summary: "Adds OpenCode model provider and native session catalog support to OpenClaw."
 read_when:
   - You are installing, configuring, or auditing the opencode plugin
 title: "OpenCode plugin"
@@ -7,7 +7,7 @@ title: "OpenCode plugin"
 
 # OpenCode plugin
 
-Adds OpenCode model provider support to OpenClaw.
+Adds OpenCode model provider and native session catalog support to OpenClaw.
 
 ## Distribution
 
@@ -16,7 +16,19 @@ Adds OpenCode model provider support to OpenClaw.
 
 ## Surface
 
-providers: opencode; contracts: mediaUnderstandingProviders
+providers: opencode; contracts: mediaUnderstandingProviders; session catalog: opencode
+
+## Native sessions
+
+OpenClaw auto-detects the `opencode` CLI on the Gateway and paired nodes. Stored
+sessions then appear in the **OpenCode** sessions-sidebar group, with read-only
+transcript browsing through the official `opencode --pure db ... --format json`
+and `opencode --pure export` commands. The restricted environment and `--pure`
+mode prevent catalog browsing from loading project plugins or inheriting unrelated
+Gateway credentials.
+
+Turn **OpenCode Session Catalog** off under **Config > Plugins > OpenCode** to
+disable discovery. It is enabled by default.
 
 ## Related docs
 

docs/plugins/reference/qa-lab.md

@@ -16,4 +16,4 @@ OpenClaw QA lab plugin with private debugger UI and scenario runner.
 
 ## Surface
 
-contracts: webSearchProviders, workerProviders
+contracts: tools, webSearchProviders, workerProviders

docs/plugins/reference/reef.md

@@ -0,0 +1,23 @@
+---
+summary: "Guarded end-to-end encrypted claw channel."
+read_when:
+  - You are installing, configuring, or auditing the reef plugin
+title: "Reef plugin"
+---
+
+# Reef plugin
+
+Guarded end-to-end encrypted claw channel.
+
+## Distribution
+
+- Package: `@openclaw/reef`
+- Install route: included in OpenClaw
+
+## Surface
+
+channels: reef
+
+## Related docs
+
+- [reef](/channels/reef)

docs/plugins/reference/xai.md

@@ -16,7 +16,7 @@ Adds xAI model provider support to OpenClaw.
 
 ## Surface
 
-providers: xai; contracts: imageGenerationProviders, mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders, tools, videoGenerationProviders, webSearchProviders
+providers: xai; contracts: imageGenerationProviders, mediaUnderstandingProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, speechProviders, tools, videoGenerationProviders, webSearchProviders
 
 ## Related docs
 

docs/plugins/sdk-migration.md

@@ -153,7 +153,7 @@ SDK.
     | Need | Import |
     | --- | --- |
     | Config types such as `OpenClawConfig` | `openclaw/plugin-sdk/config-contracts` |
-    | Already-loaded config assertions and plugin-entry config lookup | `openclaw/plugin-sdk/plugin-config-runtime` |
+    | Already-loaded config assertions, plugin-entry config lookup, and config merging | `openclaw/plugin-sdk/plugin-config-runtime` |
     | Current runtime snapshot reads | `openclaw/plugin-sdk/runtime-config-snapshot` |
     | Config writes | `openclaw/plugin-sdk/config-mutation` |
     | Session store helpers | `openclaw/plugin-sdk/session-store-runtime` |
@@ -324,6 +324,7 @@ SDK.
     | Transport readiness waits | `openclaw/plugin-sdk/transport-ready-runtime` |
     | Secure token helpers | `openclaw/plugin-sdk/secure-random-runtime` |
     | Bounded async task concurrency | `openclaw/plugin-sdk/concurrency-runtime` |
+    | Required-value assertions for provable invariants | `openclaw/plugin-sdk/expect-runtime` |
     | Numeric coercion | `openclaw/plugin-sdk/number-runtime` |
     | Process-local async lock | `openclaw/plugin-sdk/async-lock-runtime` |
     | File locks | `openclaw/plugin-sdk/file-lock` |
@@ -379,7 +380,7 @@ SDK.
   | `plugin-sdk/core` | Legacy umbrella re-export for channel entry definitions/builders | `defineChannelPluginEntry`, `createChatChannelPlugin` |
   | `plugin-sdk/config-schema` | Root config schema export | `OpenClawSchema` |
   | `plugin-sdk/provider-entry` | Single-provider entry helper | `defineSingleProviderPluginEntry` |
-  | `plugin-sdk/channel-core` | Focused channel entry definitions and builders | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
+  | `plugin-sdk/channel-core` | Focused channel entry definitions and builders | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `createChannelConfigUiHints` |
   | `plugin-sdk/setup` | Shared setup wizard helpers | Setup translator, allowlist prompts, setup status builders |
   | `plugin-sdk/setup-runtime` | Setup-time runtime helpers | `createSetupTranslator`, import-safe setup patch adapters, lookup-note helpers, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies |
   | `plugin-sdk/setup-adapter-runtime` | Deprecated setup adapter alias | Use `plugin-sdk/setup-runtime` |
@@ -435,7 +436,7 @@ SDK.
   | `plugin-sdk/security-runtime` | Security helpers | Shared trust, DM gating, root-bounded file/path helpers, external-content, and secret-collection helpers |
   | `plugin-sdk/ssrf-policy` | SSRF policy helpers | Host allowlist and private-network policy helpers |
   | `plugin-sdk/ssrf-runtime` | SSRF runtime helpers | Pinned-dispatcher, guarded fetch, SSRF policy helpers |
-  | `plugin-sdk/system-event-runtime` | System event helpers | `enqueueSystemEvent`, `peekSystemEventEntries` |
+  | `plugin-sdk/system-event-runtime` | System event helpers | `enqueueSystemEvent` (including keyed replacement), `peekSystemEventEntries` |
   | `plugin-sdk/heartbeat-runtime` | Heartbeat helpers | Heartbeat wake, event, and visibility helpers |
   | `plugin-sdk/delivery-queue-runtime` | Delivery queue helpers | `drainPendingDeliveries` |
   | `plugin-sdk/channel-activity-runtime` | Channel activity helpers | `recordChannelActivity` |
@@ -499,7 +500,7 @@ SDK.
   | `plugin-sdk/media-generation-runtime` | Shared media-generation helpers | Shared failover helpers, candidate selection, and missing-model messaging for image/video/music generation |
   | `plugin-sdk/media-understanding` | Media-understanding helpers | Media understanding provider types plus provider-facing image/audio helper exports |
   | `plugin-sdk/text-runtime` | Deprecated broad text compatibility export | Use `string-coerce-runtime`, `text-chunking`, `text-utility-runtime`, and `logging-core` |
-  | `plugin-sdk/text-chunking` | Text chunking helpers | Outbound text chunking helper |
+  | `plugin-sdk/text-chunking` | Text chunking helpers | Outbound text and offset-preserving range chunking helpers |
   | `plugin-sdk/speech` | Speech helpers | Speech provider types plus provider-facing directive, registry, validation helpers, and OpenAI-compatible TTS builder |
   | `plugin-sdk/speech-core` | Shared speech core | Speech provider types, registry, directives, normalization |
   | `plugin-sdk/realtime-transcription` | Realtime transcription helpers | Provider types, registry helpers, and shared WebSocket session helper |
@@ -790,6 +791,18 @@ major release. Every entry maps the old API to its canonical replacement.
 
   </Accordion>
 
+  <Accordion title="Raw channel send results -> OutboundDeliveryResult">
+    **Old**: return `{ ok, messageId, error }` through
+    `ChannelSendRawResult` and normalize it with
+    `createRawChannelSendResultAdapter(...)`.
+
+    **New**: return `OutboundDeliveryResult` fields and attach the channel with
+    `createAttachedChannelResultAdapter(...)`. Failed sends should throw instead
+    of returning an error string. The raw result type remains available until
+    the next plugin-SDK major release.
+
+  </Accordion>
+
   <Accordion title="Subagent session messages types renamed">
     Two legacy type aliases still exported from `src/plugins/runtime/types.ts`:
 
@@ -805,15 +818,17 @@ major release. Every entry maps the old API to its canonical replacement.
   </Accordion>
 
   <Accordion title="Removed session and transcript file APIs">
-    The SQLite session/transcript flip removes plugin-facing APIs that exposed
-    active `sessions.json` stores, JSONL transcript paths, or lists of session
-    files. Runtime plugins should use session identity and SDK runtime helpers
-    instead of resolving or mutating active files.
+    The SQLite session/transcript flip removes or deprecates plugin-facing APIs
+    that exposed active `sessions.json` stores, JSONL transcript paths, or lists
+    of session files. Runtime plugins should use session identity and SDK runtime
+    helpers instead of resolving or mutating active files.
 
-    | Removed surface | Replacement |
-    | ---------------- | ----------- |
-    | `loadSessionStore(...)`, `saveSessionStore(...)`, `updateSessionStore(...)` | Gateway-owned session runtime APIs; plugin code should request session state through documented runtime/context helpers instead of reading the active store file. |
-    | `resolveSessionFilePath(...)`, `resolveSessionTranscriptPathInDir(...)`, `resolveAndPersistSessionFile(...)` | Session identity (`sessionKey`, `sessionId`, and SDK runtime target helpers) plus Gateway methods that operate on the current session. |
+    | Migrating surface | Replacement |
+    | ----------------- | ----------- |
+    | Deprecated `loadSessionStore(...)`, `updateSessionStore(...)`, and `resolveSessionStoreEntry(...)` | `getSessionEntry(...)`, `listSessionEntries(...)`, and row-level session mutations. |
+    | Deprecated `resolveSessionFilePath(...)` | Session identity (`sessionKey`, `sessionId`, and SDK runtime target helpers) plus Gateway methods that operate on the current session. |
+    | Removed `saveSessionStore(...)` | Gateway-owned session runtime APIs; plugin code should request or mutate session state through documented runtime/context helpers instead of writing the active store file. |
+    | Removed `resolveSessionTranscriptPathInDir(...)` and `resolveAndPersistSessionFile(...)` | Session identity and Gateway methods that operate on the current session. |
     | `readLatestAssistantTextFromSessionTranscript(...)` | Identity-backed transcript readers exposed by the current runtime context, or Gateway history/session methods when the plugin is outside the transcript owner path. |
     | `SessionTranscriptUpdate.sessionFile` | `SessionTranscriptUpdate.target` with `agentId`, `sessionKey`, and `sessionId`. |
     | Memory sync inputs such as `sessionFiles` | Identity-backed transcript/session sources provided by the host; do not crawl active JSONL files for live sessions. |
@@ -823,6 +838,12 @@ major release. Every entry maps the old API to its canonical replacement.
     support artifacts. They are no longer the steady-state runtime contract for
     active sessions.
 
+    Official plugins released with `v2026.7.1-beta.5` imported the four
+    deprecated helpers above. `openclaw/plugin-sdk/session-store-runtime` keeps
+    that exact bridge through 2026-10-12; new plugins must use the replacements.
+    `resolveStorePath(...)` remains a supported SDK helper and is not part of
+    this deprecation.
+
     `openclaw plugins inspect --all --runtime` reports non-bundled plugins whose
     load errors or diagnostics still reference these removed file APIs. The
     `@openclaw/plugin-inspector` advisory sweep must use version `0.3.17` or

docs/plugins/sdk-overview.md

@@ -451,6 +451,10 @@ AI CLI backend such as `claude-cli` or `my-cli`.
   backend-native isolation flags for ephemeral `/btw` calls. If those flags
   reliably disable native tools for an otherwise always-on CLI, declare
   `sideQuestionToolMode: "disabled"` too.
+- Use `prepareExecution` for backend-owned launch environment or temporary
+  auth/config bridges. Its `ctx.contextTokenBudget` is the effective token
+  limit selected for the run, so native-compaction backends can align their
+  own threshold without provider-specific core branches.
 - Backends that can disable all native tools for a specific run may declare
   `nativeToolMode: "selectable"`. Restricted calls pass an empty
   `ctx.toolAvailability.native` tuple plus an exact host-isolated MCP allowlist;

docs/plugins/sdk-runtime.md

@@ -47,7 +47,7 @@ The mutation helpers return `afterWrite` plus a typed `followUp` summary so call
 `api.runtime.config.loadConfig()` and `api.runtime.config.writeConfigFile(...)` are deprecated. They warn once per plugin at runtime and remain available only for old external plugins during the migration window. Bundled plugins must not use them: an internal config boundary guard fails the build if plugin code calls them or imports those helpers from plugin SDK subpaths. Use `current()`, a passed-in `cfg`, `mutateConfigFile(...)`, or `replaceConfigFile(...)` instead.
 </Warning>
 
-For direct SDK imports, prefer the focused config subpaths over the broad `openclaw/plugin-sdk/config-runtime` compatibility barrel: `config-contracts` for types, `plugin-config-runtime` for already-loaded config assertions and plugin entry lookup, `runtime-config-snapshot` for current process snapshots, and `config-mutation` for writes. Bundled plugin tests should mock these focused subpaths directly instead of mocking the broad compatibility barrel.
+For direct SDK imports, prefer the focused config subpaths over the broad `openclaw/plugin-sdk/config-runtime` compatibility barrel: `config-contracts` for types, `plugin-config-runtime` for already-loaded config assertions, plugin entry lookup, and canonical config merging, `runtime-config-snapshot` for current process snapshots, and `config-mutation` for writes. Bundled plugin tests should mock these focused subpaths directly instead of mocking the broad compatibility barrel.
 
 Internal OpenClaw runtime code follows the same direction: load config once at the CLI, gateway, or process boundary, then pass that value through. Successful mutation writes refresh the process runtime snapshot and advance its internal revision; long-lived caches should key off the runtime-owned cache key instead of serializing config locally. Long-lived runtime modules have a zero-tolerance scanner for ambient `loadConfig()` calls; use a passed `cfg`, a request `context.getRuntimeConfig()`, or `getRuntimeConfig()` at an explicit process boundary.
 
@@ -325,6 +325,39 @@ two-party event loops that do not go through the shared inbound reply runner.
 
     `deleteSession(...)` can delete sessions created by the same plugin through `api.runtime.subagent.run(...)`. Deleting arbitrary user or operator sessions still requires an admin-scoped Gateway request.
 
+  </Accordion>
+  <Accordion title="api.runtime.sandbox">
+    Inspect the effective sandbox workspace authority for an agent session.
+
+    ```typescript
+    const authority = api.runtime.sandbox.resolveWorkspaceAuthority({
+      config: cfg,
+      agentId,
+      sessionKey,
+    });
+
+    const liveAuthority = await api.runtime.sandbox.prepareWorkspaceAuthority({
+      config: cfg,
+      agentId,
+      sessionKey,
+      workspaceDir,
+      confinedToolNames: ["my_plugin_safe_tool"],
+    });
+    ```
+
+    The result reports whether this session is sandboxed, whether its workspace
+    is unavailable, read-only, or writable, and an optional `confinementError`
+    when the effective Docker, tool, session, browser, or elevated policy can
+    escape that workspace. Use this for host-owned delegation decisions that
+    must not grant a worker more authority than its caller. It is an attestation
+    helper, not a replacement for checking the caller's own authorization.
+
+    `prepareWorkspaceAuthority(...)` performs the same policy check and also
+    prepares the Docker sandbox for `workspaceDir`. It rejects a hot container
+    whose live config hash does not match the requested mounts or policy. Pass
+    only exact tool names whose registered implementations the calling plugin
+    confines; wildcard prefixes do not prove tool ownership.
+
   </Accordion>
   <Accordion title="api.runtime.nodes">
     List connected nodes and invoke a node-host command from Gateway-loaded plugin code or from plugin CLI commands. Use this when a plugin owns local work on a paired device, for example a browser or audio bridge on another Mac.
@@ -675,7 +708,7 @@ two-party event loops that do not go through the shared inbound reply runner.
 
     `openSyncKeyedStore<T>(...)` returns the same store shape with synchronous methods (`register`, `registerIfAbsent`, `lookup`, `consume`, `clear` all return values directly instead of promises) for callers that cannot await.
 
-    `openChannelIngressQueue<TPayload>(...)` opens a persisted ingress queue scoped to the calling plugin, for buffering inbound events that need at-least-once processing across restarts.
+    `openChannelIngressQueue<TPayload>(...)` opens a persisted ingress queue scoped to the calling plugin, for buffering inbound events that need at-least-once processing across restarts. When stale-claim recovery uses `shouldRecover`, also provide `shouldRecoverCorrupt` if corrupt claimed payloads should be quarantined: its payload-independent claim identity lets the plugin preserve live owner and lane policy before the queue tombstones the row.
 
     <Warning>
     `openKeyedStore`, `openSyncKeyedStore`, and `openChannelIngressQueue` are available only to bundled plugins and trusted official plugin installations in this release.

docs/plugins/sdk-subpaths.md

@@ -85,7 +85,7 @@ deprecated for new code; see the per-row notes below.
   <Accordion title="Channel subpaths">
     | Subpath | Key exports |
     | --- | --- |
-    | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
+    | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `createChannelConfigUiHints` |
     | `plugin-sdk/json-schema-runtime` | Cached JSON Schema validation helper for plugin-owned schemas |
     | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
     | `plugin-sdk/setup` | Shared setup wizard helpers, setup translator, allowlist prompts, setup status builders |
@@ -226,7 +226,7 @@ usage endpoint failed or returned no usable usage data.
     | `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
     | `plugin-sdk/provider-auth-login-flow-runtime` | Lazy provider auth login flow helpers for private channel and Web UI device-code pairing |
     | `plugin-sdk/channel-secret-runtime` | Deprecated broad secret-contract surface (`collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, secret target types); prefer the focused subpaths below |
-    | `plugin-sdk/channel-secret-basic-runtime` | Narrow secret-contract exports for non-TTS channel/plugin secret surfaces |
+    | `plugin-sdk/channel-secret-basic-runtime` | Narrow secret-contract exports and target-registry builders for non-TTS channel/plugin secret surfaces |
     | `plugin-sdk/channel-secret-tts-runtime` | Narrow nested channel TTS secret assignment helpers |
     | `plugin-sdk/secret-ref-runtime` | Narrow SecretRef typing, resolution, and plan-target path lookup for secret-contract/config parsing |
     | `plugin-sdk/secret-provider-integration` | Type-only SecretRef provider integration manifest and preset contracts for plugins that publish external secret provider presets |
@@ -263,7 +263,7 @@ usage endpoint failed or returned no usable usage data.
     | `plugin-sdk/gateway-method-runtime` | Reserved Gateway method dispatch helper for plugin HTTP routes that declare `contracts.gatewayMethodDispatch: ["authenticated-request"]` |
     | `plugin-sdk/gateway-runtime` | Gateway client, event-loop-ready client start helper, gateway CLI RPC, gateway protocol errors, advertised LAN host resolution, and channel-status patch helpers |
     | `plugin-sdk/config-contracts` | Focused type-only config surface for plugin config shapes such as `OpenClawConfig` and channel/provider config types |
-    | `plugin-sdk/plugin-config-runtime` | Runtime plugin-config lookup helpers such as `requireRuntimeConfig`, `resolvePluginConfigObject`, and `resolveLivePluginConfigObject` |
+    | `plugin-sdk/plugin-config-runtime` | Runtime plugin-config helpers such as `mergeDeep`, `requireRuntimeConfig`, `resolvePluginConfigObject`, and `resolveLivePluginConfigObject` |
     | `plugin-sdk/config-mutation` | Transactional config mutation helpers such as `mutateConfigFile`, `replaceConfigFile`, and `logConfigUpdated` |
     | `plugin-sdk/message-tool-delivery-hints` | Shared message-tool delivery metadata hint strings |
     | `plugin-sdk/runtime-config-snapshot` | Current process config snapshot helpers such as `getRuntimeConfig`, `getRuntimeConfigSnapshot`, and test snapshot setters |
@@ -319,6 +319,7 @@ usage endpoint failed or returned no usable usage data.
     | `plugin-sdk/delivery-queue-runtime` | Outbound pending-delivery drain helper |
     | `plugin-sdk/file-access-runtime` | Safe local-file and media-source path helpers |
     | `plugin-sdk/heartbeat-runtime` | Heartbeat wake, event, and visibility helpers |
+    | `plugin-sdk/expect-runtime` | Required-value assertion helper for provable runtime invariants |
     | `plugin-sdk/number-runtime` | Numeric coercion helper |
     | `plugin-sdk/secure-random-runtime` | Secure token/UUID helpers |
     | `plugin-sdk/system-event-runtime` | System event queue helpers |
@@ -335,6 +336,7 @@ usage endpoint failed or returned no usable usage data.
     | `plugin-sdk/session-binding-runtime` | Current conversation binding state without configured binding routing or pairing stores |
     | `plugin-sdk/context-visibility-runtime` | Context visibility resolution and supplemental context filtering without broad config/security imports |
     | `plugin-sdk/string-coerce-runtime` | Narrow primitive record/string coercion and normalization helpers without markdown/logging imports |
+    | `plugin-sdk/text-utility-runtime` | Low-level text and path helpers, including five-entity HTML escaping |
     | `plugin-sdk/host-runtime` | Hostname and SCP host normalization helpers |
     | `plugin-sdk/retry-runtime` | Retry config and retry runner helpers |
     | `plugin-sdk/agent-runtime` | Deprecated broad barrel for agent dir/identity/workspace helpers, including `resolveAgentDir`, `resolveDefaultAgentDir`, and the deprecated `resolveOpenClawAgentDir` compatibility export; prefer focused agent/runtime subpaths |
@@ -350,7 +352,7 @@ usage endpoint failed or returned no usable usage data.
     | `plugin-sdk/media-store` | Narrow media store helpers such as `saveMediaBuffer` and `saveMediaStream` |
     | `plugin-sdk/media-generation-runtime` | Shared media-generation failover helpers, candidate selection, and missing-model messaging |
     | `plugin-sdk/media-understanding` | Media understanding provider types plus provider-facing image/audio/structured-extraction helper exports |
-    | `plugin-sdk/text-chunking` | Outbound text and markdown chunking/render helpers, markdown table conversion, directive-tag stripping, and safe-text utilities |
+    | `plugin-sdk/text-chunking` | Outbound text and offset-preserving range chunking, markdown chunking/render helpers, markdown table conversion, directive-tag stripping, and safe-text utilities |
     | `plugin-sdk/speech` | Speech provider types plus provider-facing directive, registry, validation, OpenAI-compatible TTS builder, and speech helper exports |
     | `plugin-sdk/speech-core` | Shared speech provider types, registry, directive, normalization, and speech helper exports |
     | `plugin-sdk/realtime-transcription` | Realtime transcription provider types, registry helpers, and shared WebSocket session helper |

docs/plugins/tool-plugins.md

@@ -19,7 +19,7 @@ or [Provider Plugins](/plugins/sdk-provider-plugins) instead.
 
 ## Requirements
 
-- Node 22.19+, Node 23.11+, or Node 24+.
+- Node 22.22.3+, Node 24.15+, or Node 25.9+.
 - TypeScript ESM package output.
 - `typebox` in `dependencies` (not just `devDependencies` - the generated
   plugin imports it at runtime).

docs/plugins/voice-call.md

@@ -156,7 +156,7 @@ Voice-call credentials accept SecretRefs. `plugins.entries.voice-call.config.twi
             defaultMode: "notify", // notify | conversation
           },
 
-          streaming: { enabled: true /* see Streaming transcription */ },
+          streaming: { enabled: true /* Twilio only; see Streaming transcription */ },
           realtime: { enabled: false /* see Realtime voice conversations */ },
         },
       },
@@ -399,7 +399,10 @@ options.
 
 ## Streaming transcription
 
-`streaming` selects a realtime transcription provider for live call audio.
+`streaming` connects Twilio Media Streams to a realtime transcription provider.
+The classic streaming path requires `provider: "twilio"`; configuration with
+Telnyx, Plivo, or mock is rejected. Telnyx live audio uses the separately
+authenticated `realtime.enabled` path instead.
 
 Current runtime behavior:
 

docs/plugins/workboard.md

@@ -136,7 +136,7 @@ rule as linked sessions (see [Session lifecycle sync](#session-lifecycle-sync)).
 | `workboard_promote` / `workboard_reassign` / `workboard_reclaim`                                                                                 | Recover or hand off stuck work.                                                                                                                                                           |
 | `workboard_comment` / `workboard_proof`                                                                                                          | Add handoff notes or attach proof/artifact references.                                                                                                                                    |
 | `workboard_unblock`                                                                                                                              | Move blocked work back to `todo`.                                                                                                                                                         |
-| `workboard_dispatch`                                                                                                                             | Nudge dependency promotion or stale-claim cleanup.                                                                                                                                        |
+| `workboard_dispatch`                                                                                                                             | Nudge dependency promotion or stale-claim cleanup without launching workers; worker launch uses Gateway or slash-command dispatch.                                                        |
 
 Claimed cards reject agent-tool mutations from other agents unless the caller
 holds the claim token returned by `workboard_claim`. Every card returned by an
@@ -162,6 +162,35 @@ OpenClaw subagent sessions still own execution. One dispatch pass:
 Workers get bounded card context plus the claim token needed to heartbeat,
 complete, or block the card through the Workboard tools.
 
+Workspace paths follow the caller's existing filesystem authority. Gateway
+clients with `operator.write` can use configured agent workspaces;
+`operator.admin` clients can use other host checkouts. Sandboxed agent tools use
+their sandbox workspace access, while unsandboxed workspace-only tools use their
+configured workspace root. Workboard records that authority when a workspace is
+assigned and intersects it with the current caller's authority again at dispatch,
+so a persisted card cannot widen a later caller's access. Older cards with an
+explicit host workspace but no recorded authority must have that workspace
+re-saved before a full-host dispatch; cards without a host path adopt the
+current caller's authority when first dispatched.
+
+Workspace-bound dispatch accepts a directory or Git checkout only when its
+repository root exactly matches the target agent workspace. A worktree request
+is narrowed to that directory and persisted as a directory workspace, so the
+host does not materialize the checkout or execute repository setup code. The
+target worker must use a writable, non-shared Docker sandbox for that exact
+workspace, without elevated execution, persisted host/node exec overrides, or
+unclassified plugin and MCP tools. Workboard enumerates its registered tools
+instead of trusting a `workboard_*` prefix, and dispatch refuses a hot Docker
+container whose live mount/config hash is stale. Dispatch reports the
+incompatible target policy instead of starting a less-confined worker.
+Full-host dispatch may target other local checkouts and keeps normal managed-
+worktree setup.
+
+Workspace authority does not create a second card-lifecycle permission model.
+Callers that may mutate Workboard cards can manually move them through the same
+statuses on every surface; read-only workspace access only prevents worker
+dispatch that needs writes.
+
 ### Worker selection
 
 Each pass starts **at most 3 workers by default**. Ready cards are ordered by
@@ -229,6 +258,8 @@ troubleshooting.
 and `/workboard dispatch` mirror the CLI. List and show are read operations
 for any authorized command sender. Create and dispatch require owner status on
 chat surfaces, or a Gateway client with `operator.write`/`operator.admin`.
+Their worktree access still follows the same workspace boundary described
+above.
 
 ## Session lifecycle sync
 
@@ -302,7 +333,8 @@ Gateway RPC methods live under `workboard.*`:
 | `operator.write` | `cards.diagnostics.refresh`, create/update/move/delete/comment/link/linkDependency/proof/artifact, attachment add/delete, worker log, protocol violation, claim/heartbeat/release/promote/reassign/reclaim/complete/block/unblock, `cards.dispatch`, `cards.bulk`, archive, `boards.upsert`/`archive`/`delete`, `cards.specify`/`decompose`, notification subscribe/delete/advance |
 
 No RPC method requires `operator.admin`. Browsers connected with read-only
-operator access can inspect the board but cannot mutate cards.
+operator access can inspect the board but cannot mutate cards. An admin scope
+widens accepted Workboard host paths; it does not change the methods available.
 
 ## Storage