@axonflow/openclaw 1.3.1 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [2.0.0] - 2026-04-29 — Production, quality, and security hardening — upgrade encouraged
+
+**Upgrade strongly recommended.** Over the past month we've shipped substantial production, quality, and security hardening across the AxonFlow plugin and platform — upgrade to the latest version for a more secure, reliable, and bug-free experience.
+
+**Security highlights from this release cycle:**
+- **Plugin cache and credential-file permission hardening** (this release). Cache and config directories are tightened to mode `0700` on every invocation; `try-registration.json` is written with mode `0600`. Pre-existing world-readable credential files are detected and refused on first load. Documented in [`GHSA-cqmh-pcgr-q42f`](https://github.com/getaxonflow/axonflow-openclaw-plugin/security/advisories/GHSA-cqmh-pcgr-q42f).
+- **Hook-closure dead-code fix** (this release). Hooks registered against the AxonFlow client previously captured the pre-bootstrap client by value, so the post-bootstrap re-construction was invisible to every registered hook. Refactored to a `ClientRef` holder so all 5 factory paths see the live client. Closes a P0 governance bypass on the hook-driven enforcement path.
+- **Telemetry opt-out reliability** (this release). `DO_NOT_TRACK` was unreliable because host CLIs commonly inject `DO_NOT_TRACK=1` regardless of user intent; the canonical opt-out is now `AXONFLOW_TELEMETRY=off`, an AxonFlow-scoped signal hosts can't unilaterally set.
+
+The full set of platform-side security fixes shipped alongside this release — including multi-tenant isolation in MAP execution, cross-tenant audit-log isolation, and SQLi enforcement on the Community SaaS endpoint — is documented in the consolidated platform advisory [`GHSA-9h64-2846-7x7f`](https://github.com/getaxonflow/axonflow/security/advisories/GHSA-9h64-2846-7x7f). Bundled OpenClaw upstream advisories closed by the dependency bump in this release are tracked in this repo's Dependabot alerts.
+
+**Reliability and bug-fix highlights:**
+- **7-day delivered-heartbeat with stamp-on-success** (this release). Telemetry stamp advances only after the POST returns 2xx, so a transient network failure no longer silences telemetry until the next 7-day window. Concurrent invocations are de-duplicated by an in-flight gate.
+- **Mode-clarity canary log line** on every plugin init (this release). Logs `[AxonFlow] Connected to AxonFlow at <URL> (mode=...)` and a PR-blocking CI gate asserts the canary matches the actual outbound destination, guarding against silent endpoint drift.
+- **PR-blocking install-to-use smoke against the live community stack** (this release). Catches plugin-side regressions against `try.getaxonflow.com` before they reach a user's host process.
+
+### BREAKING
+
+- **`DO_NOT_TRACK` is no longer honored as an AxonFlow telemetry opt-out.** Use `AXONFLOW_TELEMETRY=off` instead. Host tools and CLIs commonly inject `DO_NOT_TRACK=1` regardless of user intent, which makes it unreliable as a signal.
+- **`default` values for `endpoint` / `clientId` / `clientSecret` removed from `openclaw.plugin.json`.** The plugin loader now sees `pluginConfig.endpoint` as `undefined` when the user hasn't configured it — required by the Community-SaaS-default resolver to distinguish "no choice" from "explicit localhost".
+
+### Added
+
+- **First-run Community-SaaS bootstrap** — plugin connects to AxonFlow Community SaaS at `https://try.getaxonflow.com` when no `endpoint` / `clientId` / `clientSecret` is supplied in `pluginConfig`. Registers via `/api/v1/register` on first run and persists the credential to `~/.config/axonflow/try-registration.json` (mode 0600). Set any of those keys to opt into self-hosted.
+- **Mode-clarity canary** on every plugin init: `[AxonFlow] Connected to AxonFlow at <url> (mode=community-saas|self-hosted)`.
+- **One-time setup disclosure** on first Community-SaaS connection. Stamped at `<cache-dir>/openclaw-plugin-disclosure-shown` so it fires exactly once per install.
+- **Plugin/platform version compatibility check** on startup. Reads `plugin_compatibility.min_plugin_version["openclaw"]` from the agent's `/health` endpoint and `console.warn`s if the runtime version is below the floor.
+- **`deployment_mode=community-saas`** telemetry value, distinguishing first-class Community-SaaS users from self-hosted production / development (previously bucketed inside `production`).
+- **`AXONFLOW_CACHE_DIR` / `AXONFLOW_CONFIG_DIR`** environment overrides for the cache/config directory resolver. Useful for sandboxed containers and any deployment that needs to redirect AxonFlow state.
+
+### Changed
+
+- **Telemetry switched to a 7-day delivered-heartbeat.** At most one anonymous ping per environment every 7 days, with the stamp advanced only after the POST returns 2xx — a transient network failure doesn't silence telemetry until the next window. Concurrent invocations are de-duplicated by an in-flight gate.
+- `pluginConfig` is now optional (was required). `registerAxonFlowGovernance` with no `pluginConfig`, `undefined`, or `{}` resolves to Community SaaS mode rather than throwing `requires configuration`.
+
+### Fixed
+
+- The `DO_NOT_TRACK=1 is deprecated...` `console.warn` is no longer emitted on every plugin init when `DO_NOT_TRACK=1` is set.
+- Hooks now correctly see Community-SaaS credentials produced by the asynchronous bootstrap. Previously the hook handlers captured the AxonFlowClient by value at registration time, so the post-bootstrap reassignment was invisible — every governed tool call kept shipping `Authorization: Basic :` against try.getaxonflow.com. Hooks now read through a mutable client holder.
+
+### Security
+
+- Cache and config directories tightened to `0700` on every plugin init (was: only set on directory creation via `mkdirSync({ mode: 0o700 })`, which left existing 0755 dirs unchanged).
+
+
+## [1.3.2] - 2026-04-22
+
+### Deprecated
+
+- `DO_NOT_TRACK=1` as an AxonFlow telemetry opt-out — scheduled for removal after 2026-05-05 in the next major release. Use `AXONFLOW_TELEMETRY=off` instead. The plugin emits a one-time `console.warn` when `DO_NOT_TRACK=1` is the active control and `AXONFLOW_TELEMETRY=off` is not also set.
+
 ## [1.3.1] - 2026-04-19
 
 Patch release. Fixes a v1.3.0 gap surfaced by install-and-use E2E

package/README.md

@@ -1,81 +1,159 @@
 # @axonflow/openclaw
 
-**Policy enforcement, approval gates, and audit trails for [OpenClaw](https://github.com/openclaw/openclaw).**
+**Governance for OpenClaw agents: block dangerous tool calls, require human approval on high-risk actions, redact PII from outbound messages, and keep a compliance-grade audit trail — without changing a single line of your agent code.**
 
-## Why
+[![npm](https://img.shields.io/npm/v/%40axonflow%2Fopenclaw?color=%2300A36C)](https://www.npmjs.com/package/@axonflow/openclaw)
+[![ClawHub](https://img.shields.io/badge/ClawHub-listed-00A36C)](https://clawhub.ai/plugins/%40axonflow%2Fopenclaw)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
 
-OpenClaw is widely deployed with [13+ CVEs disclosed in 2026](https://github.com/jgamblin/OpenClawCVEs/) (multiple CVSS 9.8+), [135,000+ publicly exposed instances](https://www.bitsight.com/blog/openclaw-ai-security-risks-exposed-instances), and [1,184 malicious skills](https://cyberpress.org/clawhavoc-poisons-openclaws-clawhub-with-1184-malicious-skills/) poisoned in ClawHub via the ClawHavoc supply chain attack. OpenClaw provides agent runtime and tool execution but no centralized policy enforcement, no PII scanning, and no compliance-grade audit trails.
+> **→ Full integration walkthrough:** **[docs.getaxonflow.com/docs/integration/openclaw](https://docs.getaxonflow.com/docs/integration/openclaw/)** — architecture, hook coverage, policy examples, and troubleshooting.
 
-This plugin adds the governance layer. AxonFlow governs, OpenClaw orchestrates. No LLM provider keys needed — OpenClaw handles all LLM calls, AxonFlow only enforces policies and records audit trails. Your data stays on your infrastructure.
+> **Upgrade strongly recommended.** AxonFlow ships substantial monthly security and quality hardening; staying on the latest major is the security-supported release line. [Latest release](https://github.com/getaxonflow/axonflow-openclaw-plugin/releases/latest) · [Security advisories](https://github.com/getaxonflow/axonflow-openclaw-plugin/security/advisories)
 
-This plugin is useful when you want to:
-- block dangerous tool calls (reverse shells, SSRF, destructive commands) before they run
-- detect and redact PII and secrets in outbound messages before delivery
-- require human approval for high-risk tools (exec, web_fetch, message)
-- keep a compliance-grade audit trail of every tool call and LLM interaction
-- gain visibility into token usage and LLM activity across agents via audit trails
+---
 
-## What It Does
+## Why this plugin exists
 
-| Hook | Purpose |
-|------|---------|
-| `before_tool_call` | Evaluate tool inputs against AxonFlow policies before execution |
-| `after_tool_call` | Record tool execution in AxonFlow audit trail |
-| `message_sending` | Scan outbound messages for PII/secrets before delivery |
-| `llm_input` | Record prompt, model, and provider for audit |
-| `llm_output` | Record response summary, token usage, and latency for audit |
+OpenClaw is a strong agent runtime. It is also a serious production security problem the moment you take it past a prototype:
 
-The plugin also:
-- **Verifies AxonFlow connectivity** on startup and logs a warning if unreachable
-- **Tracks governance metrics** in-process (tool calls blocked/allowed, messages redacted, etc.) accessible via `getMetrics()`
+- **[135,000+ publicly exposed instances](https://www.bitsight.com/blog/openclaw-ai-security-risks-exposed-instances)** deployed without central policy enforcement
+- **[13+ CVEs disclosed in 2026](https://github.com/jgamblin/OpenClawCVEs/)**, several at CVSS 9.8+
+- **[1,184 malicious skills](https://cyberpress.org/clawhavoc-poisons-openclaws-clawhub-with-1184-malicious-skills/)** poisoned in ClawHub via the ClawHavoc supply-chain attack
+- **No native PII/secrets scanning**, no SQL-injection defense, no compliance-grade audit trail, no org-wide tool policy, no approval workflow
 
-## Current Limitation
+OpenClaw handles agent runtime, MCP connectivity, channels, and tool execution. It was never intended to be the place you enforce governance. This plugin adds the governance layer on top, so OpenClaw keeps doing what it does well and AxonFlow takes over the "is this allowed, should this redact, who approved, where is the audit record" questions.
 
-Tool results written into the OpenClaw session transcript are not yet scanned by this plugin. OpenClaw's `tool_result_persist` hook is synchronous today, so it cannot call AxonFlow's HTTP policy APIs.
+**AxonFlow governs. OpenClaw orchestrates. Your data stays on your infrastructure.** No LLM provider keys leave your machine — OpenClaw still makes every LLM call; AxonFlow only evaluates policies and records audit trails.
 
-What is protected today:
-- tool inputs before execution
-- outbound messages before delivery
-- tool and LLM audit trails
+---
 
-What is not protected yet:
-- tool results entering the LLM context through the session transcript
+## What you get
 
-If OpenClaw adds async support for `tool_result_persist`, AxonFlow can add transcript/result scanning immediately. Upstream issue: [openclaw/openclaw#58558](https://github.com/openclaw/openclaw/issues/58558).
+| Capability | What it means in practice |
+|---|---|
+| **Pre-execution policy check** | Every tool call is scored against 80+ built-in policies (reverse shells, SSRF, credential access, SQLi, prompt injection, path traversal, PII in arguments) before it runs |
+| **Approval gates** | Any tool in `highRiskTools` pauses execution and posts a native OpenClaw approval request with policy severity surfaced as approval priority |
+| **Outbound message scanning** | Every message to Telegram/Discord/Slack/webhook is scanned for PII and secrets before delivery — redacted, blocked, or passed through per policy |
+| **Compliance-grade audit trail** | Every tool call and LLM interaction records the input, output summary, matched policies, decision, and duration |
+| **Decision explainability** | Blocked calls return a `decision_id` the agent can pass to `explainDecision()` to see exactly which policy family triggered and why |
+| **Session overrides** | Operators can request a time-bounded, audit-logged exception when policy allows it — without leaving the agent |
+| **Per-user identity** | `config.userEmail` threads the actual human operator through to every explain/override call, so shared chat agents still produce attributable audits |
 
-## Prerequisites
+---
 
-This plugin connects to [AxonFlow](https://github.com/getaxonflow/axonflow), a self-hosted governance platform, for policy evaluation and audit logging. AxonFlow must be running before you use the plugin. Your data stays on your infrastructure.
+## How it plugs in
 
-```bash
-# Start AxonFlow (Docker — runs entirely on your machine)
-git clone https://github.com/getaxonflow/axonflow.git
-cd axonflow
-docker compose up -d
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        OpenClaw Agent                        │
+│                                                              │
+│  User Message → LLM Call → Tool Execution → Response → User  │
+│        │           │             │                       │   │
+│        ▼           ▼             ▼                       ▼   │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │            @axonflow/openclaw                          │  │
+│  │                                                        │  │
+│  │  GOVERNANCE (can block / modify):                      │  │
+│  │  before_tool_call   (priority 10) → check_input        │  │
+│  │  message_sending    (priority 10) → check_output       │  │
+│  │                                                        │  │
+│  │  AUDIT (observe-only, non-blocking):                   │  │
+│  │  after_tool_call    (priority 90) → audit_tool_call    │  │
+│  │  llm_input          (priority 90) → record prompt      │  │
+│  │  llm_output         (priority 90) → record response    │  │
+│  └────────────────────────┬───────────────────────────────┘  │
+└───────────────────────────┼──────────────────────────────────┘
+                            │
+                            ▼
+                    ┌───────────────────┐
+                    │     AxonFlow      │
+                    │  ┌─────┐ ┌─────┐  │
+                    │  │Policy│ │Audit│  │
+                    │  │Engine│ │Trail│  │
+                    │  └─────┘ └─────┘  │
+                    │  ┌─────┐          │
+                    │  │ PII │          │
+                    │  │Scan │          │
+                    │  └─────┘          │
+                    └───────────────────┘
 ```
 
-See [Getting Started](https://docs.getaxonflow.com/docs/getting-started/) for full setup options.
+**What stays the same:** your OpenClaw agent config, ClawHub skills, MCP connectors, and channel integrations are unchanged. The plugin only adds lifecycle hooks.
 
-## Install
+---
 
-Available on [ClawHub](https://clawhub.ai/plugins/%40axonflow%2Fopenclaw) and [npm](https://www.npmjs.com/package/@axonflow/openclaw).
+## The production problems this solves
 
-**Recommended:**
+These are the three questions that reliably surface the moment an OpenClaw agent hits real users or regulators.
 
-```bash
-openclaw plugins install @axonflow/openclaw
-```
+### 1. "The tool that phones home"
+
+A `web_fetch` skill is installed from ClawHub. An agent uses it to look up product docs. Then a user asks, *"Summarize my customer list"* — the agent calls `web_fetch` with customer emails in the URL. The data leaves your infrastructure. OpenClaw executed the tool correctly; nobody checked what it was sending.
+
+**What the plugin does:** `check_input` fires before `web_fetch` runs, scans the URL arguments against PII and exfiltration policies, and blocks the call with a decision ID.
+
+### 2. "The MCP response full of PII"
+
+An MCP connector queries your CRM for "recent support tickets." The MCP server returns 50 rows with names, emails, phone numbers. All of it flows into the LLM context. OpenClaw managed the connection; SecretRef protected the credentials; the *data itself* was never inspected.
+
+**What the plugin does:** `check_output` fires on `message_sending` before anything reaches the user channel, and scans every outbound message for SSN, credit card, API key, and other 80+ policy matches — redacting or blocking per policy.
+
+### 3. "The compliance question nobody can answer"
+
+Six months later, a regulator asks: *"For this interaction on March 14, which tools were called, what data did they access, which policies were in effect, and why was the response allowed?"* OpenClaw's execution logs show a tool was called and succeeded. The *decision context* does not exist.
+
+**What the plugin does:** every governed call emits a structured audit record with tool, input, output summary, matched policies, decision, and duration. Search via `searchAuditEvents()` or the Customer Portal.
+
+---
+
+## Try AxonFlow on a real plugin rollout
+
+We're opening limited **Plugin Design Partner** slots.
+
+30-minute hook lifecycle review, policy pack scoping, override workflow design, and IDE/CLI rollout pattern walkthrough — for solo developers and small teams putting governance on OpenClaw.
+
+[Apply here](https://getaxonflow.com/plugins/design-partner?utm_source=readme_plugin_openclaw) or email [design-partners@getaxonflow.com](mailto:design-partners@getaxonflow.com). Personal email is fine — solo developers welcome.
+
+### See AxonFlow in Action
+
+Three short videos covering different angles of the platform:
+
+- **[Community Quickstart Demo (Code + Terminal, 2.5 min)](https://youtu.be/BSqU1z0xxCo)** — governed calls, PII block, Gateway Mode with LangChain/CrewAI, and MAP from YAML
+- **[Runtime Control Demo (Portal + Workflow, 3 min)](https://youtu.be/6UatGpn7KwE)** — approvals, retry safety, execution state, and the audit viewer
+- **[Architecture Deep Dive (12 min)](https://youtu.be/Q2CZ1qnquhg)** — how the control plane works, policy enforcement flow, and multi-agent planning
 
-The `clawhub:@axonflow/openclaw` form also works if you prefer to be explicit about the source:
+### Plugin Evaluation Tier (Free 90-day License)
+
+Outgrown Community on a real plugin install? Evaluation unlocks the capacity and features that matter for plugin users — without moving to Enterprise yet:
+
+| Capability | Community | Evaluation (Free) | Enterprise |
+|---|---|---|---|
+| Tenant policies | 20 | 50 | Unlimited |
+| Org-wide policies | 0 | 5 | Unlimited |
+| Audit retention | 3 days | 14 days | Up to 10 years |
+| HITL approval gates | — | 25 pending, 24h expiry | Unlimited, 24h |
+| Evidence export (CSV/JSON) | — | 5,000 records · 14d window · 3/day | Unlimited |
+| Policy simulation | — | 300/day | Unlimited |
+| Session overrides (self-service unblock) | — | — | Enterprise-only |
+
+Org-wide policies and session overrides are **Enterprise-only** — those are the actual upgrade triggers for plugin users.
+
+[Get a free Plugin Evaluation license](https://getaxonflow.com/plugins/evaluation-license?utm_source=readme_plugin_openclaw_eval)
+
+---
+
+## Install
+
+Requires OpenClaw **2026.4.14 or later**. Upgrade with `npm install -g openclaw@latest` if needed.
 
 ```bash
-openclaw plugins install clawhub:@axonflow/openclaw
+openclaw plugins install @axonflow/openclaw
 ```
 
-Requires OpenClaw **2026.4.14 or later**. If you are not on the latest, upgrade with `npm install -g openclaw@latest`.
+Available on [ClawHub](https://clawhub.ai/plugins/%40axonflow%2Fopenclaw) and [npm](https://www.npmjs.com/package/@axonflow/openclaw). The `clawhub:@axonflow/openclaw` form works if you prefer to be explicit about the source.
 
 <details>
-<summary>On an older OpenClaw CLI? The old workaround is still needed.</summary>
+<summary>On an older OpenClaw CLI? The ENOENT workaround still applies.</summary>
 
 OpenClaw versions before 2026.4.14 had a bug ([openclaw/openclaw#66618](https://github.com/openclaw/openclaw/issues/66618)) that made scoped packages fail with `ENOENT .../openclaw-clawhub-package-XXXXXX/@axonflow/openclaw.zip` — both forms of the install command hit it. The fix shipped in 2026.4.14. If you cannot upgrade, install from npm directly:
 
@@ -86,111 +164,169 @@ openclaw plugins install "./$TGZ"
 ```
 </details>
 
-For the full integration walkthrough (architecture, hook coverage, policy examples, troubleshooting), see the [OpenClaw Integration Guide](https://docs.getaxonflow.com/docs/integration/openclaw/).
+### Start AxonFlow
+
+The plugin connects to AxonFlow, a self-hosted governance platform. AxonFlow must be running before the plugin loads. Everything stays on your infrastructure.
+
+```bash
+git clone https://github.com/getaxonflow/axonflow.git
+cd axonflow && docker compose up -d
+```
+
+See [Getting Started](https://docs.getaxonflow.com/docs/getting-started/) for production deployment options.
+
+---
 
 ## Configure
 
-In your OpenClaw config:
+The plugin works without any configuration. Install it and run a tool — on first run it registers against AxonFlow Community SaaS at `https://try.getaxonflow.com` and persists the resulting credentials to `~/.config/axonflow/try-registration.json` (mode 0600). Every plugin init logs:
+
+```
+[AxonFlow] Connected to AxonFlow at https://try.getaxonflow.com (mode=community-saas)
+```
+
+Community SaaS is intended for basic testing and evaluation. For real workflows, real systems, or sensitive data, point the plugin at a self-hosted AxonFlow:
 
 ```yaml
+# openclaw.config.yaml
 plugins:
   @axonflow/openclaw:
     endpoint: http://localhost:8080
-    # In community mode, clientId defaults to "community"
-    # and clientSecret can be left unset.
-    # Set both only for evaluation/enterprise credentials.
-    # clientId: your-client-id
-    # clientSecret: your-client-secret
-    # requestTimeoutMs: 8000
     highRiskTools:
       - web_fetch
       - message
 ```
 
-### Configuration Options
+Setting any of `endpoint` / `clientId` / `clientSecret` opts you into self-hosted mode. The Community-SaaS bootstrap is skipped, and the plugin uses your values verbatim. The same canary log line confirms the destination on every init:
+
+```
+[AxonFlow] Connected to AxonFlow at http://localhost:8080 (mode=self-hosted)
+```
+
+### Full configuration reference
 
 | Option | Required | Default | Description |
 |--------|----------|---------|-------------|
-| `endpoint` | Yes | — | AxonFlow agent gateway URL |
-| `clientId` | No | `"community"` | Tenant identity for data isolation. Override for evaluation/enterprise. |
-| `clientSecret` | No | `""` | License key for evaluation/enterprise features. Requires `clientId` to be set. |
+| `endpoint` | No | `https://try.getaxonflow.com` (Community SaaS) when unset; `http://localhost:8080` when self-hosted with no endpoint specified | AxonFlow agent gateway URL |
+| `clientId` | No | `"community"` (self-hosted) or auto-bootstrapped `cs_<uuid>` (Community SaaS) | Tenant identity for data isolation. Override for evaluation/enterprise. |
+| `clientSecret` | No | `""` (self-hosted) or auto-bootstrapped (Community SaaS) | Basic-auth secret paired with `clientId`. Required for evaluation/enterprise tenants; leave unset in community mode. |
+| `userEmail` | No | — | Per-user identity forwarded on explain/override calls. Shared agents should set this from session context. |
 | `highRiskTools` | No | `[]` | Tools that require human approval even when policy allows |
 | `governedTools` | No | `[]` (all) | Tools to govern. Empty = all tools. |
-| `excludedTools` | No | `[]` | Tools to exclude from governance |
-| `defaultOperation` | No | `"execute"` | Operation type for mcp_check_input (`"execute"` or `"query"`) |
-| `onError` | No | `"block"` | Behavior when AxonFlow is unreachable: `"block"` (fail-closed) or `"allow"` (fail-open) |
-| `requestTimeoutMs` | No | `8000` | Timeout for policy checks, output scans, audit writes, and health checks. Increase for remote AxonFlow deployments. |
+| `excludedTools` | No | `[]` | Tools to exclude from governance. Takes precedence over `governedTools`. |
+| `defaultOperation` | No | `"execute"` | Operation type for `check_input` (`"execute"` or `"query"`) |
+| `onError` | No | `"block"` | Governs behavior on **auth/config errors only** (401/403). `"block"` denies the tool call with a message telling the operator to fix configuration; `"allow"` lets the call through ungoverned. Does not apply to network/transient errors — see Fail behavior below. |
+| `requestTimeoutMs` | No | `8000` | Timeout for policy checks, output scans, audit writes, and health checks |
+
+### Fail behavior
+
+The plugin classifies errors from the AxonFlow client into two buckets and applies different rules per hook.
+
+| Hook | Transient network error (timeout, DNS, connection refused, 5xx) | Auth/config error (401 / 403) |
+|---|---|---|
+| `before_tool_call` | **Always fail-open** — tool call proceeds regardless of `onError`. Transient infrastructure issues should not block legitimate dev workflows. |  Respects `onError`. With the default `"block"`, the tool call is denied with a message pointing at the misconfiguration. With `"allow"`, the call proceeds ungoverned. |
+| `message_sending` | Respects `onError`. With `"block"` (default), the outbound message is cancelled. With `"allow"`, it is delivered ungoverned. | Same as network error — respects `onError`. |
+| `after_tool_call`, `llm_input`, `llm_output` (audit) | Always silently caught. Governance was already enforced on the pre-execution hook. | Always silently caught. |
+
+If you need tool-execution itself to fail-closed during an AxonFlow outage (for example on a production infrastructure agent), pair the plugin with an OpenClaw-side health check or a front-door liveness gate — the plugin alone will not achieve that for `before_tool_call`.
+
+---
 
-**Valid configurations:**
-- Both omitted → community mode (`clientId` defaults to `"community"`)
-- `clientId` only → community mode with custom tenant identity
-- Both set → licensed mode (evaluation/enterprise)
-- `clientSecret` only → **error** (licensed mode requires explicit tenant identity to prevent data going to the wrong tenant)
+## Use-case recipes
 
-## How It Works
+### DevOps / coding agent — heavy exec usage
 
+```yaml
+plugins:
+  @axonflow/openclaw:
+    endpoint: http://localhost:8080
+    highRiskTools: [exec, process]
+    excludedTools: [get_current_time, list_models]
+    onError: block
 ```
-User sends message → OpenClaw receives
-    │
-    ▼
-┌─────────────────────────────────────────────┐
-│ llm_input (audit)                           │
-│ → Record prompt, model, provider            │
-└─────────────────────────────────────────────┘
-    │
-    ▼
-LLM generates response (may include tool calls)
-    │
-    ▼
-┌─────────────────────────────────────────────┐
-│ llm_output (audit)                          │
-│ → Record response, tokens, latency          │
-└─────────────────────────────────────────────┘
-    │
-    ▼  (if tool calls in response)
-┌─────────────────────────────────────────────┐
-│ before_tool_call (governance)               │
-│ → mcp_check_input(openclaw.{tool}, args)    │
-│ → BLOCK / REQUIRE APPROVAL / ALLOW          │
-└─────────────────────────────────────────────┘
-    │
-    ▼
-Tool executes (web_fetch, message, MCP, etc.)
-    │
-    ▼
-Tool result persisted to session transcript
-(not scanned — pending async hook support)
-    │
-    ▼
-┌─────────────────────────────────────────────┐
-│ after_tool_call (audit)                     │
-│ → audit_tool_call(tool, params, result)     │
-└─────────────────────────────────────────────┘
-    │
-    ▼
-┌─────────────────────────────────────────────┐
-│ message_sending (governance)                │
-│ → mcp_check_output(openclaw.message_sending) │
-│ → CANCEL / REDACT / ALLOW                   │
-└─────────────────────────────────────────────┘
-    │
-    ▼
-Message delivered to user channel
+
+### Customer support agent — Slack/Discord/Telegram
+
+```yaml
+plugins:
+  @axonflow/openclaw:
+    endpoint: http://localhost:8080
+    highRiskTools: [message, execute_sql, send_email]
+    onError: block
 ```
 
-## Telemetry
+### Self-healing infrastructure agent — highest risk
+
+```yaml
+plugins:
+  @axonflow/openclaw:
+    endpoint: http://localhost:8080
+    highRiskTools: [exec, process, web_fetch]
+    onError: block  # auth-error path and message_sending fail-closed; see Fail behavior above
+```
 
-This plugin sends an anonymous telemetry ping on initialization to help us understand usage patterns, including local and self-hosted evaluations. The ping includes: plugin version, platform info (OS, architecture, Node.js version), AxonFlow platform version, and hook configuration (count, onError mode). No PII, no tool arguments, no policy data.
+More examples — content/social agents, data analysts, RAG pipelines — in the [integration guide](https://docs.getaxonflow.com/docs/integration/openclaw/#use-case-configuration-examples).
 
-Opt out:
-- `DO_NOT_TRACK=1` (standard)
-- `AXONFLOW_TELEMETRY=off`
+---
 
-The startup ping is enabled by default for local, self-hosted, and remote deployments. Opt-out controls always win.
+## MCP tools available to your agent
 
-## Starter Policies
+Beyond the lifecycle hooks, OpenClaw agents can call **10 MCP tools** via the agent's MCP server at `/api/v1/mcp-server`. These are served by the platform (not the plugin), so new tools become available to every plugin without a code change.
 
-See [policies/README.md](./policies/README.md) for recommended policy setup for OpenClaw deployments, including protections against reverse shells, credential exfiltration, SSRF, path traversal, and agent config file poisoning.
+**Governance (6):** `check_policy`, `check_output`, `audit_tool_call`, `list_policies`, `get_policy_stats`, `search_audit_events`
+
+**Explainability & overrides (4):** `explain_decision`, `create_override`, `delete_override`, `list_overrides`
+
+When a tool call is blocked, the agent can surface the `decision_id` to the operator, call `explain_decision` to reveal the triggering policy family, and — if the decision is overridable — call `create_override` with mandatory justification for a short-lived, audit-logged exception. Operators never leave the OpenClaw session.
+
+See [Decision Explainability](https://docs.getaxonflow.com/docs/governance/explainability/) and [Session Overrides](https://docs.getaxonflow.com/docs/governance/overrides/).
+
+---
+
+## What's covered today, and what's not
+
+**Protected today:**
+- Tool inputs before execution
+- Outbound messages before delivery
+- Tool and LLM audit trails (including search & explainability)
+- Decision-level overrides with per-user attribution
+
+**Not protected yet:**
+- Tool results written into the session transcript (OpenClaw's `tool_result_persist` hook is synchronous and cannot call AxonFlow's HTTP APIs)
+
+PII in tool results is still caught by `message_sending` before it reaches the end user, but it is visible to the LLM. When OpenClaw adds async support for `tool_result_persist`, this plugin will add transcript scanning immediately. Upstream issue: [openclaw/openclaw#58558](https://github.com/openclaw/openclaw/issues/58558).
+
+---
+
+## Latency
+
+| Operation | Typical overhead |
+|-----------|-----------------|
+| Policy pre-check | 2–5 ms |
+| PII / secrets detection | 1–3 ms |
+| SQL-injection scan | 1–2 ms |
+| Audit write (async) | 0 ms (non-blocking) |
+| **Total per-tool overhead** | **3–10 ms** |
+
+Imperceptible for interactive agents.
+
+---
+
+## Starter policies
+
+The [policies directory](./policies) ships research-backed starter policies addressing the top 10 OpenClaw security risks — reverse shells, SSRF, credential exfiltration, path traversal, agent config poisoning, prompt injection, and more. Ready-to-use SQL INSERT statements and setup instructions included.
+
+---
+
+## Telemetry
+
+The plugin sends a one-time anonymous ping on initialization so AxonFlow can understand adoption and environment shape. Includes plugin version, OS/arch, Node.js version, AxonFlow platform version, hook configuration summary. **Never** includes message contents, tool arguments, or policy data.
+
+Opt out: set `AXONFLOW_TELEMETRY=off` in the environment OpenClaw runs in.
+
+`DO_NOT_TRACK` is **not** honored as an opt-out for AxonFlow telemetry. It is commonly inherited from host tools and developer environments, which makes it an unreliable expression of user intent.
+
+---
 
 ## Testing
 
@@ -204,25 +340,27 @@ Smoke E2E (requires a live AxonFlow stack at `localhost:8080`):
 
 ```bash
 npm ci && npm run build
-# Start a stack via axonflow-enterprise (see its setup-e2e-testing.sh)
+# Start a local AxonFlow stack first — `docker compose up -d` in
+# the axonflow repo, or point AXONFLOW_ENDPOINT at an existing one.
 node tests/e2e/smoke-block-context.mjs
 ```
 
-The smoke scenario uses `AxonFlowClient.mcpCheckInput` to fire a
-SQLi-bearing statement against a running platform and asserts the
-response carries Plugin Batch 1 richer-context fields (`decision_id`,
-`risk_level`, `policy_matches`). Exits 0 with a `SKIP:` message if no
-stack is reachable. In CI, run manually via `workflow_dispatch` with a
-reachable endpoint (GitHub-hosted runners have no local stack).
+The smoke scenario uses `AxonFlowClient.mcpCheckInput` to fire a SQLi-bearing statement against a running platform and asserts the response carries richer-context fields (`decision_id`, `risk_level`, `policy_matches`). Exits 0 with a `SKIP:` message if no stack is reachable.
+
+For the broader validation story — explain-decision, override lifecycle, audit-filter parity, cache invalidation — see the [OpenClaw integration guide](https://docs.getaxonflow.com/docs/integration/openclaw/).
 
-Full install-and-use matrix (explain, override lifecycle, audit filter
-parity, cache invalidation) lives in `axonflow-enterprise/tests/e2e/plugin-batch-1/openclaw-install/`.
+---
 
 ## Links
 
+- **[OpenClaw Integration Guide](https://docs.getaxonflow.com/docs/integration/openclaw/)** — the full walkthrough (recommended starting point)
 - [AxonFlow Documentation](https://docs.getaxonflow.com)
-- [OpenClaw Integration Guide](https://docs.getaxonflow.com/docs/integration/openclaw/)
 - [Policy Enforcement](https://docs.getaxonflow.com/docs/mcp/policy-enforcement/)
+- [Decision Explainability](https://docs.getaxonflow.com/docs/governance/explainability/)
+- [Session Overrides](https://docs.getaxonflow.com/docs/governance/overrides/)
+- [PII Detection](https://docs.getaxonflow.com/docs/security/pii-detection/)
+- [Audit Logging](https://docs.getaxonflow.com/docs/governance/audit-logging/)
+- Sister plugins: [Claude Code](https://github.com/getaxonflow/axonflow-claude-plugin) · [Cursor](https://github.com/getaxonflow/axonflow-cursor-plugin) · [Codex](https://github.com/getaxonflow/axonflow-codex-plugin)
 
 ## License
 

package/dist/audit.d.ts

@@ -4,14 +4,14 @@
  * Records every tool execution to AxonFlow's audit trail.
  * Fire-and-forget: audit failures do not block tool execution.
  */
-import type { AxonFlowClient } from "./axonflow-client.js";
+import type { ClientRef } from "./client-ref.js";
 import type { AxonFlowPluginConfig } from "./config.js";
 /**
  * Create the after_tool_call hook handler.
  *
  * Logs tool execution details to AxonFlow for compliance audit.
  */
-export declare function createAfterToolCallHandler(client: AxonFlowClient, config: AxonFlowPluginConfig): (event: {
+export declare function createAfterToolCallHandler(clientRef: ClientRef, config: AxonFlowPluginConfig): (event: {
     toolName: string;
     params: Record<string, unknown>;
     runId?: string;

package/dist/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAIxD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,oBAAoB,IAEd,OAAO;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,KAAG,OAAO,CAAC,IAAI,CAAC,CAkBlB"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAIxD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,oBAAoB,IAEd,OAAO;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,KAAG,OAAO,CAAC,IAAI,CAAC,CAkBlB"}

package/dist/audit.js

@@ -11,13 +11,13 @@ import { recordAuditEventSent } from "./metrics.js";
  *
  * Logs tool execution details to AxonFlow for compliance audit.
  */
-export function createAfterToolCallHandler(client, config) {
+export function createAfterToolCallHandler(clientRef, config) {
     return async (event) => {
         if (!shouldGovernTool(event.toolName, config)) {
             return;
         }
         try {
-            await client.auditToolCall(event.toolName, event.params, event.result, event.error, event.durationMs);
+            await clientRef.current.auditToolCall(event.toolName, event.params, event.result, event.error, event.durationMs);
             recordAuditEventSent();
         }
         catch {

package/dist/audit.js.map

@@ -1 +1 @@
-{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAsB,EACtB,MAA4B;IAE5B,OAAO,KAAK,EAAE,KAQb,EAAiB,EAAE;QAClB,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;YAC9C,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,aAAa,CACxB,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,UAAU,CACjB,CAAC;YACF,oBAAoB,EAAE,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,SAAoB,EACpB,MAA4B;IAE5B,OAAO,KAAK,EAAE,KAQb,EAAiB,EAAE;QAClB,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;YAC9C,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,OAAO,CAAC,aAAa,CACnC,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,UAAU,CACjB,CAAC;YACF,oBAAoB,EAAE,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}