@randuhmm/openclaw-agent-acl 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Install clawhub CLI
+        run: npm install -g clawhub
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Build plugin
+        run: npm run plugin:build
+
+      - name: Validate manifest
+        run: npm run plugin:validate

package/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write  # required for ClawHub OIDC trusted publishing
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - name: Install clawhub CLI
+        run: npm install -g clawhub
+
+      - name: Build plugin
+        run: npm run build
+
+      - name: Validate plugin package
+        run: clawhub package validate .
+
+      - name: Authenticate clawhub
+        run: clawhub login --token "$CLAWHUB_TOKEN"
+        env:
+          CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
+
+      - name: Publish to ClawHub
+        run: clawhub package publish randuhmm/openclaw-agent-acl
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/ARCHITECTURE.md

@@ -0,0 +1,155 @@
+# Architecture: openclaw-agent-acl
+
+This document describes the internal design of the plugin, its data flow, current limitations, and the planned roadmap for future versions. Intended audience: contributors and anyone building on top of this plugin.
+
+## Design overview
+
+```
+User prompt
+    │
+    ▼
+OpenClaw gateway
+    │  dispatches tool call
+    ▼
+before_tool_call event
+    │
+    ▼
+agent-acl plugin
+    │
+    ├─ extract server name from tool name  ("calendar-mcp__list_events" → "calendar-mcp")
+    │
+    ├─ look up acl.servers["calendar-mcp"]
+    │      ├─ no rule → pass (unrestricted)
+    │      └─ rule found → check allowAgents.includes(ctx.agentId)
+    │              ├─ yes → pass
+    │              └─ no  → block + log
+    │
+    ▼
+Tool executes (or is blocked with reason returned to agent)
+```
+
+## Key implementation details
+
+### Hook: `before_tool_call`
+
+The plugin registers a single async handler on OpenClaw's `before_tool_call` event. This event fires synchronously in the tool dispatch path before any MCP call is made. The handler returns `{ block: false }` to allow or `{ block: true, blockReason: string }` to deny.
+
+### Tool name parsing
+
+OpenClaw namespaces MCP tools as `<server>__<tool>`. The plugin splits on the first `__` to extract the server name:
+
+```typescript
+const serverName = event.toolName.split('__')[0];
+```
+
+This is safe as long as server names do not themselves contain `__`, which is consistent with OpenClaw's naming conventions.
+
+### ACL config loading
+
+`acl.json` is read once during `register()` via `readFileSync`. The file is parsed and validated at startup — missing file, invalid JSON, or wrong structure all throw with a descriptive error message that surfaces in gateway logs. The parsed config is held in memory for the lifetime of the gateway process.
+
+### Default-open policy
+
+Any MCP server not listed in `acl.json` is fully unrestricted. This is an intentional "lock what you need" design: adding the plugin doesn't break anything by default, and you opt specific servers into the allowlist incrementally.
+
+### Agent ID resolution
+
+The agent ID is taken from `ctx.agentId`, falling back to `"main"` if absent. Agent IDs in `allowAgents` must match exactly (case-sensitive).
+
+### Plugin manifest: `trustedToolPolicies`
+
+The `openclaw.plugin.json` declares `contracts.trustedToolPolicies: ["agent-acl"]`. This contract grants the plugin permission to intercept `before_tool_call` events and return block decisions. Without it, the gateway would not dispatch the hook to this plugin.
+
+---
+
+## Known limitations
+
+These are intentional constraints for v1.0, not bugs. Each is tracked as a future enhancement.
+
+| # | Limitation | Impact |
+|---|---|---|
+| 1 | **No hot-reload** | Rule changes require gateway restart (`openclaw gateway restart`) |
+| 2 | **Server-level granularity only** | Can't allow `mealie__search` but block `mealie__delete` for the same agent |
+| 3 | **Allowlist only** | No denylist mode — can't say "all agents except X" |
+| 4 | **No wildcard agent IDs** | Can't match `jonny-*` to cover all per-user agent instances |
+| 5 | **No runtime inspection** | No API to query the loaded ACL without reading the file directly |
+| 6 | **Single config file** | All rules live in one `acl.json`; no include/merge of multiple rule files |
+
+---
+
+## Roadmap
+
+### v1.1 — Hot-reload
+
+Watch `aclPath` with `fs.watch` and atomically swap the in-memory ACL on change. No gateway restart needed to update rules. Implementation sketch:
+
+```typescript
+import { watch } from 'node:fs';
+
+watch(aclPath, () => {
+  try {
+    acl = loadAcl(aclPath);
+    api.logger.info(`agent-acl: reloaded ${Object.keys(acl.servers).length} rule(s)`);
+  } catch (e) {
+    api.logger.error(`agent-acl: reload failed — keeping previous rules. ${e}`);
+  }
+});
+```
+
+### v1.2 — Per-tool granularity
+
+Extend the schema to allow tool-level overrides within a server:
+
+```json
+{
+  "servers": {
+    "mealie": {
+      "allowAgents": ["family-chef"],
+      "tools": {
+        "delete_recipe": { "allowAgents": [] }
+      }
+    }
+  }
+}
+```
+
+Tool-level rules take precedence over server-level rules.
+
+### v1.3 — Denylist mode
+
+Add `denyAgents` as an alternative to `allowAgents`. Semantics: if `denyAgents` is present, all agents are allowed *except* those listed.
+
+```json
+{
+  "servers": {
+    "web-search": {
+      "denyAgents": ["child-agent"]
+    }
+  }
+}
+```
+
+### v1.4 — Wildcard agent IDs
+
+Support glob-style patterns in `allowAgents`/`denyAgents`:
+
+```json
+{ "allowAgents": ["jonny-*", "main"] }
+```
+
+Matches any agent ID starting with `jonny-`, which covers per-user instances like `jonny-assistant`, `jonny-chef`, etc.
+
+---
+
+## Contributing
+
+The plugin is a single TypeScript file (`index.ts`) compiled with `tsup` to `dist/index.js`. The `dist/` output is committed to the repo so that `git:`-based installs work without a build step.
+
+```bash
+npm install          # install dev deps
+npm run typecheck    # type-check without building
+npm run build        # compile index.ts → dist/index.js
+npm run plugin:build # build + validate plugin entry point
+```
+
+All PRs should pass `npm run plugin:build` and `npm run plugin:validate` before merge. The CI workflow (`.github/workflows/ci.yml`) enforces this on every push.

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [1.0.0] — 2026-06-27
+
+### Added
+- Initial release: per-agent MCP server allowlist via `before_tool_call` hook
+- JSON config (`acl.json`) with server-level rules — servers not listed are unrestricted
+- `aclPath` plugin config option for placing `acl.json` outside the plugin directory
+- Validated error messages for missing, unreadable, or malformed `acl.json`
+- `contracts.trustedToolPolicies` manifest declaration for gateway integration

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# openclaw-agent-acl
+
+An [OpenClaw](https://openclaw.ai) plugin that restricts MCP server tool access on a per-agent basis using a simple JSON allowlist.
+
+## Why
+
+By default, every agent in OpenClaw can call tools from every connected MCP server. That's fine for a single-agent setup, but breaks down when you run multiple agents with different roles or trust levels — a family cooking assistant shouldn't be able to read your email, a child's agent shouldn't have access to your calendar or smart-home controls, and a work agent probably shouldn't touch personal data.
+
+This plugin lets you lock down specific MCP servers to designated agents without touching OpenClaw's core configuration. You define the rules once in a JSON file; everything else stays open by default.
+
+## How it works
+
+OpenClaw namespaces all MCP tools as `<server>__<tool>` (e.g. `calendar-mcp__list_events`). This plugin intercepts every `before_tool_call` event, extracts the server name from the tool name, and checks whether the calling agent is in that server's allowlist. If not, the call is blocked with a clear reason returned to the agent and logged.
+
+Servers with no rule in `acl.json` are unrestricted — you only list the servers you want to lock down.
+
+## Installation
+
+```bash
+openclaw plugins install clawhub:randuhmm/openclaw-agent-acl
+```
+
+Or directly from git (for pre-release versions or self-hosted installs):
+
+```bash
+openclaw plugins install git:github.com/randuhmm/openclaw-agent-acl
+```
+
+## Configuration
+
+### 1. Create `acl.json`
+
+Copy the example and edit it for your setup:
+
+```bash
+cp acl.json.example ~/.openclaw/acl.json
+```
+
+```json
+{
+  "servers": {
+    "calendar-mcp": {
+      "allowAgents": ["my-assistant"]
+    },
+    "smart-home": {
+      "allowAgents": ["main", "my-assistant"]
+    },
+    "recipes": {
+      "allowAgents": ["family-chef"]
+    }
+  }
+}
+```
+
+- `servers` — keys are MCP server names exactly as configured in OpenClaw
+- `allowAgents` — agent IDs allowed to call tools from that server
+- Servers **not listed** are unrestricted — all agents pass through
+
+### 2. Point the plugin at your `acl.json`
+
+In your `openclaw.json`, configure the `aclPath`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "agent-acl": {
+        "enabled": true,
+        "config": {
+          "aclPath": "/home/user/.openclaw/acl.json"
+        }
+      }
+    }
+  }
+}
+```
+
+If `aclPath` is omitted, the plugin looks for `acl.json` in its own installed directory.
+
+### 3. Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+## Verification
+
+Confirm the plugin is active:
+
+```bash
+openclaw plugins inspect agent-acl --runtime
+```
+
+Test it: ask a restricted agent to use a blocked tool — it will receive a refusal, and you'll see a log line like:
+
+```
+agent-acl: blocked agent="family-chef" from tool="calendar-mcp__list_events"
+```
+
+## Finding your agent IDs
+
+Agent IDs are the identifiers used when creating agents with `openclaw agents create`. List them:
+
+```bash
+openclaw agents list
+```
+
+The default agent ID is `"main"`.
+
+## Updating rules
+
+Edit `acl.json` and restart the gateway to apply changes. No plugin reinstall needed.
+
+## Troubleshooting
+
+**Plugin is loaded but nothing is being blocked**
+Check that the server name in `acl.json` exactly matches the server name as configured in OpenClaw (case-sensitive). The key must equal what appears before `__` in a tool name — e.g. if the tool is `Calendar__list_events`, the server key is `Calendar`, not `calendar-mcp`.
+
+**Gateway fails to start after installing the plugin**
+The plugin now gives a clear error message if `acl.json` is missing or malformed. Check the gateway logs — the message will include the exact path it tried to read and what went wrong.
+
+**An agent is being blocked unexpectedly**
+Run `openclaw agents list` to confirm the exact agent ID. Agent IDs are case-sensitive and must match the string in `allowAgents` exactly.
+
+## Plugin manifest: `trustedToolPolicies`
+
+The `openclaw.plugin.json` manifest declares `contracts.trustedToolPolicies: ["agent-acl"]`. This tells OpenClaw's gateway that this plugin provides a trusted tool policy and should be loaded before tool calls are dispatched — it's what grants the plugin permission to intercept `before_tool_call` events.
+
+## Requirements
+
+- OpenClaw `>=2026.6.8`
+- Node.js `>=22.19`
+
+## License
+
+MIT

package/acl.json.example

@@ -0,0 +1,13 @@
+{
+  "servers": {
+    "calendar-mcp": {
+      "allowAgents": ["my-assistant"]
+    },
+    "smart-home": {
+      "allowAgents": ["main", "my-assistant"]
+    },
+    "recipes": {
+      "allowAgents": ["family-chef"]
+    }
+  }
+}

package/dist/index.js

@@ -0,0 +1,49 @@
+// index.ts
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { readFileSync } from "fs";
+import { join } from "path";
+function loadAcl(aclPath) {
+  let raw;
+  try {
+    raw = readFileSync(aclPath, "utf8");
+  } catch {
+    throw new Error(
+      `agent-acl: cannot read acl.json at "${aclPath}". Create the file or set aclPath in plugin config.`
+    );
+  }
+  let acl;
+  try {
+    acl = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`agent-acl: acl.json at "${aclPath}" is not valid JSON: ${e}`);
+  }
+  if (!acl || typeof acl.servers !== "object" || Array.isArray(acl.servers)) {
+    throw new Error(`agent-acl: acl.json must have a top-level "servers" object`);
+  }
+  return acl;
+}
+var index_default = definePluginEntry({
+  id: "agent-acl",
+  name: "Agent Tool ACL",
+  description: "Restricts MCP server tool access per agent via acl.json",
+  register(api) {
+    const aclPath = api.pluginConfig?.["aclPath"] ?? join(api.rootDir, "acl.json");
+    const acl = loadAcl(aclPath);
+    api.logger.info(`agent-acl: loaded ${Object.keys(acl.servers).length} server rule(s) from ${aclPath}`);
+    api.on("before_tool_call", async (event, ctx) => {
+      const serverName = event.toolName.split("__")[0];
+      const rule = acl.servers[serverName];
+      if (!rule) return { block: false };
+      const agentId = ctx.agentId ?? "main";
+      if (rule.allowAgents.includes(agentId)) return { block: false };
+      api.logger.info(`agent-acl: blocked agent="${agentId}" from tool="${event.toolName}"`);
+      return {
+        block: true,
+        blockReason: `Agent "${agentId}" does not have access to "${serverName}" tools`
+      };
+    });
+  }
+});
+export {
+  index_default as default
+};

package/index.ts

@@ -0,0 +1,58 @@
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+interface AclConfig {
+  servers: Record<string, { allowAgents: string[] }>;
+}
+
+function loadAcl(aclPath: string): AclConfig {
+  let raw: string;
+  try {
+    raw = readFileSync(aclPath, 'utf8');
+  } catch {
+    throw new Error(
+      `agent-acl: cannot read acl.json at "${aclPath}". ` +
+      `Create the file or set aclPath in plugin config.`,
+    );
+  }
+  let acl: AclConfig;
+  try {
+    acl = JSON.parse(raw) as AclConfig;
+  } catch (e) {
+    throw new Error(`agent-acl: acl.json at "${aclPath}" is not valid JSON: ${e}`);
+  }
+  if (!acl || typeof acl.servers !== 'object' || Array.isArray(acl.servers)) {
+    throw new Error(`agent-acl: acl.json must have a top-level "servers" object`);
+  }
+  return acl;
+}
+
+export default definePluginEntry({
+  id: 'agent-acl',
+  name: 'Agent Tool ACL',
+  description: 'Restricts MCP server tool access per agent via acl.json',
+  register(api) {
+    const aclPath: string =
+      (api.pluginConfig?.['aclPath'] as string | undefined) ??
+      join(api.rootDir!, 'acl.json');
+
+    const acl = loadAcl(aclPath);
+    api.logger.info(`agent-acl: loaded ${Object.keys(acl.servers).length} server rule(s) from ${aclPath}`);
+
+    api.on('before_tool_call', async (event, ctx) => {
+      const serverName = event.toolName.split('__')[0];
+      const rule = acl.servers[serverName];
+      if (!rule) return { block: false };
+
+      const agentId = ctx.agentId ?? 'main';
+      if (rule.allowAgents.includes(agentId)) return { block: false };
+
+      api.logger.info(`agent-acl: blocked agent="${agentId}" from tool="${event.toolName}"`);
+      return {
+        block: true,
+        blockReason: `Agent "${agentId}" does not have access to "${serverName}" tools`,
+      };
+    });
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "agent-acl",
+  "name": "Agent Tool ACL",
+  "description": "Restricts MCP server tool access per agent via a JSON allowlist.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "aclPath": {
+        "type": "string",
+        "description": "Absolute path to acl.json. Defaults to acl.json in the installed plugin root."
+      }
+    },
+    "additionalProperties": false
+  },
+  "contracts": {
+    "trustedToolPolicies": ["agent-acl"]
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@randuhmm/openclaw-agent-acl",
+  "version": "1.0.0",
+  "description": "Per-agent MCP tool access control for OpenClaw",
+  "type": "module",
+  "scripts": {
+    "build": "tsup index.ts --format esm --outDir dist --external openclaw --external node:fs --external node:path",
+    "plugin:build": "npm run build",
+    "plugin:validate": "clawhub package validate .",
+    "typecheck": "tsc --noEmit"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.6.10"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=22.19"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/randuhmm/openclaw-agent-acl"
+  },
+  "license": "MIT",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "mcp",
+    "acl",
+    "agent",
+    "tool-policy"
+  ],
+  "peerDependencies": {
+    "openclaw": "^2026.6.8"
+  }
+}

package/reports/plugin-inspector-issues.md

@@ -0,0 +1,73 @@
+# OpenClaw Plugin Issue Findings
+
+Generated: deterministic
+Status: PASS
+
+## Triage Summary
+
+| Metric                     | Value |
+| -------------------------- | ----- |
+| Issue findings             | 0     |
+| Open issue findings        | 0     |
+| Runtime-covered findings   | 0     |
+| Runtime-partial findings   | 0     |
+| P0                         | 0     |
+| P1                         | 0     |
+| Open P0                    | 0     |
+| Open P1                    | 0     |
+| Live issues                | 0     |
+| Live P0 issues             | 0     |
+| Compat gaps                | 0     |
+| Deprecation warnings       | 0     |
+| Inspector gaps             | 0     |
+| Open inspector gaps        | 0     |
+| Runtime coverage artifacts | 0     |
+| Upstream metadata          | 0     |
+| Contract probes            | 0     |
+
+## Triage Overview
+
+| Class               | Count | P0 | Meaning                                                                                                                                                  |
+| ------------------- | ----- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| live-issue          | 0     | 0  | Potential runtime breakage in the target OpenClaw/plugin pair. P0 only when it is not a deprecated compat seam.                                          |
+| compat-gap          | 0     | -  | Compatibility behavior is needed but missing from the target OpenClaw compat registry.                                                                   |
+| deprecation-warning | 0     | -  | Plugin uses a supported but deprecated compatibility seam; keep it wired while migration exists.                                                         |
+| inspector-gap       | 0     | -  | Plugin Inspector needs stronger capture/probe evidence before making contract judgments. Runtime-covered rows are proof-backed and not open report work. |
+| upstream-metadata   | 0     | -  | Plugin package or manifest metadata should improve upstream; not a target OpenClaw live break by itself.                                                 |
+| fixture-regression  | 0     | -  | Fixture no longer exposes an expected seam; investigate fixture pin or scanner drift.                                                                    |
+
+## P0 Live Issues
+
+_none_
+
+## Other Live Issues
+
+_none_
+
+## Compat Gaps
+
+_none_
+
+## Deprecation Warnings
+
+_none_
+
+## Inspector Proof Gaps
+
+_none_
+
+## Runtime-Covered Inspector Gaps
+
+_none_
+
+## Upstream Metadata Issues
+
+_none_
+
+## Issues
+
+_none_
+
+## Contract Probe Backlog
+
+_none_

package/reports/plugin-inspector-report.json

@@ -0,0 +1,231 @@
+{
+  "generatedAt": "deterministic",
+  "targetOpenClaw": {
+    "configuredPath": null,
+    "status": "disabled",
+    "compatRecords": [],
+    "compatRecordStatuses": {},
+    "hookNames": [],
+    "apiRegistrars": [],
+    "capturedRegistrars": [],
+    "sdkExports": [],
+    "reservedSdkExports": [],
+    "supportedFacadeSdkExports": [],
+    "publicPluginOwnedSdkExports": [],
+    "manifestFields": [],
+    "manifestContractFields": []
+  },
+  "status": "pass",
+  "summary": {
+    "breakageCount": 0,
+    "warningCount": 0,
+    "deprecationWarningCount": 0,
+    "issueCount": 0
+  },
+  "fixtures": [
+    {
+      "id": "openclaw-agent-acl",
+      "name": "Agent Tool ACL",
+      "priority": "high",
+      "seams": [
+        "plugin-runtime"
+      ],
+      "why": "local OpenClaw plugin root",
+      "status": "ok",
+      "hooks": [
+        "before_tool_call"
+      ],
+      "hookDetails": [
+        {
+          "name": "before_tool_call",
+          "file": "index.ts",
+          "line": 43,
+          "ref": "index.ts:43"
+        }
+      ],
+      "registrations": [
+        "definePluginEntry"
+      ],
+      "registrationDetails": [
+        {
+          "name": "definePluginEntry",
+          "file": "index.ts",
+          "line": 31,
+          "ref": "index.ts:31"
+        }
+      ],
+      "manifestContracts": [
+        "trustedToolPolicies"
+      ],
+      "manifestFiles": [
+        "openclaw.plugin.json"
+      ],
+      "sourceFiles": [
+        "index.ts"
+      ],
+      "pluginManifests": [
+        {
+          "path": "openclaw.plugin.json",
+          "id": "agent-acl",
+          "name": "Agent Tool ACL",
+          "version": null,
+          "keys": [
+            "configSchema",
+            "contracts",
+            "description",
+            "id",
+            "name"
+          ],
+          "contracts": [
+            "trustedToolPolicies"
+          ],
+          "providerAuthEnvVars": {},
+          "channelEnvVars": {},
+          "activation": null
+        }
+      ],
+      "securityManifests": [],
+      "package": {
+        "path": "package.json",
+        "name": "@randuhmm/openclaw-agent-acl",
+        "version": "1.0.0",
+        "type": "module",
+        "main": null,
+        "npmPack": {
+          "advertised": false,
+          "private": false,
+          "filesMode": "implicit",
+          "files": [],
+          "invalidFileSpecs": []
+        },
+        "dependencies": [],
+        "peerDependencies": [
+          "openclaw"
+        ],
+        "optionalDependencies": [],
+        "openclaw": {
+          "extensions": [
+            "./dist/index.js"
+          ],
+          "runtimeExtensions": [],
+          "setupEntry": null,
+          "compatPluginApi": ">=2026.3.24-beta.2",
+          "buildOpenClawVersion": "2026.6.10",
+          "buildPluginSdkVersion": null,
+          "install": null,
+          "release": null,
+          "unsupportedMetadata": [],
+          "entrypoints": [
+            {
+              "kind": "extension",
+              "specifier": "./dist/index.js",
+              "relativePath": "dist/index.js",
+              "exists": true,
+              "requiresBuild": true
+            }
+          ]
+        }
+      },
+      "packages": [
+        {
+          "path": "package.json",
+          "name": "@randuhmm/openclaw-agent-acl",
+          "version": "1.0.0",
+          "type": "module",
+          "main": null,
+          "npmPack": {
+            "advertised": false,
+            "private": false,
+            "filesMode": "implicit",
+            "files": [],
+            "invalidFileSpecs": []
+          },
+          "dependencies": [],
+          "peerDependencies": [
+            "openclaw"
+          ],
+          "optionalDependencies": [],
+          "openclaw": {
+            "extensions": [
+              "./dist/index.js"
+            ],
+            "runtimeExtensions": [],
+            "setupEntry": null,
+            "compatPluginApi": ">=2026.3.24-beta.2",
+            "buildOpenClawVersion": "2026.6.10",
+            "buildPluginSdkVersion": null,
+            "install": null,
+            "release": null,
+            "unsupportedMetadata": [],
+            "entrypoints": [
+              {
+                "kind": "extension",
+                "specifier": "./dist/index.js",
+                "relativePath": "dist/index.js",
+                "exists": true,
+                "requiresBuild": true
+              }
+            ]
+          }
+        }
+      ],
+      "sdkImports": [
+        "openclaw/plugin-sdk/plugin-entry"
+      ],
+      "sdkImportDetails": [
+        {
+          "specifier": "openclaw/plugin-sdk/plugin-entry",
+          "file": "index.ts",
+          "line": 1,
+          "ref": "index.ts:1"
+        }
+      ],
+      "sdkDeprecations": []
+    }
+  ],
+  "issues": [],
+  "contractProbes": [],
+  "logs": [
+    {
+      "fixture": "openclaw-agent-acl",
+      "code": "seam-inventory",
+      "level": "log",
+      "message": "observed 1 hooks, 1 registrations, and 1 manifest contracts",
+      "evidence": [
+        "hook:before_tool_call",
+        "registration:definePluginEntry",
+        "manifestContract:trustedToolPolicies"
+      ]
+    },
+    {
+      "fixture": "openclaw-agent-acl",
+      "code": "package-metadata",
+      "level": "log",
+      "message": "selected package metadata for plugin contract checks",
+      "evidence": [
+        "package.json",
+        "@randuhmm/openclaw-agent-acl",
+        "version:1.0.0"
+      ]
+    },
+    {
+      "fixture": "openclaw-agent-acl",
+      "code": "declarative-contracts",
+      "level": "log",
+      "message": "fixture declares manifest contracts that can be checked without executing plugin code",
+      "evidence": [
+        "trustedToolPolicies"
+      ]
+    },
+    {
+      "fixture": "openclaw",
+      "code": "target-openclaw-unavailable",
+      "level": "log",
+      "message": "target OpenClaw checkout was not available, so compat record coverage was not checked",
+      "evidence": [
+        "not configured"
+      ]
+    }
+  ],
+  "decisions": []
+}

package/reports/plugin-inspector-report.md

@@ -0,0 +1,132 @@
+# OpenClaw Plugin Compatibility Report
+
+Generated: deterministic
+Status: PASS
+
+## Summary
+
+| Metric                     | Value |
+| -------------------------- | ----- |
+| Fixtures                   | 1     |
+| High-priority fixtures     | 1     |
+| Hard breakages             | 0     |
+| Warnings                   | 0     |
+| Compatibility suggestions  | 0     |
+| Issue findings             | 0     |
+| Open issue findings        | 0     |
+| Runtime-covered findings   | 0     |
+| Runtime-partial findings   | 0     |
+| P0 issues                  | 0     |
+| P1 issues                  | 0     |
+| Open P0 issues             | 0     |
+| Open P1 issues             | 0     |
+| Live issues                | 0     |
+| Live P0 issues             | 0     |
+| Compat gaps                | 0     |
+| Deprecation warnings       | 0     |
+| Inspector gaps             | 0     |
+| Open inspector gaps        | 0     |
+| Runtime coverage artifacts | 0     |
+| Upstream metadata          | 0     |
+| Contract probes            | 0     |
+| Decision rows              | 0     |
+
+## Triage Overview
+
+| Class               | Count | P0 | Meaning                                                                                                                                                  |
+| ------------------- | ----- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| live-issue          | 0     | 0  | Potential runtime breakage in the target OpenClaw/plugin pair. P0 only when it is not a deprecated compat seam.                                          |
+| compat-gap          | 0     | -  | Compatibility behavior is needed but missing from the target OpenClaw compat registry.                                                                   |
+| deprecation-warning | 0     | -  | Plugin uses a supported but deprecated compatibility seam; keep it wired while migration exists.                                                         |
+| inspector-gap       | 0     | -  | Plugin Inspector needs stronger capture/probe evidence before making contract judgments. Runtime-covered rows are proof-backed and not open report work. |
+| upstream-metadata   | 0     | -  | Plugin package or manifest metadata should improve upstream; not a target OpenClaw live break by itself.                                                 |
+| fixture-regression  | 0     | -  | Fixture no longer exposes an expected seam; investigate fixture pin or scanner drift.                                                                    |
+
+## P0 Live Issues
+
+_none_
+
+## Other Live Issues
+
+_none_
+
+## Compat Gaps
+
+_none_
+
+## Deprecation Warnings
+
+_none_
+
+## Inspector Proof Gaps
+
+_none_
+
+## Runtime-Covered Inspector Gaps
+
+_none_
+
+## Upstream Metadata Issues
+
+_none_
+
+## Hard Breakages
+
+_none_
+
+## Target OpenClaw Compat Records
+
+| Metric                   | Value    |
+| ------------------------ | -------- |
+| Configured path          | -        |
+| Status                   | disabled |
+| Compat registry          | -        |
+| Compat records           | 0        |
+| Compat status counts     | -        |
+| Record ids               | -        |
+| Hook registry            | -        |
+| Hook names               | 0        |
+| API builder              | -        |
+| API registrars           | 0        |
+| Captured registration    | -        |
+| Captured registrars      | 0        |
+| Package metadata         | -        |
+| Plugin SDK exports       | 0        |
+| Manifest types           | -        |
+| Manifest fields          | 0        |
+| Manifest contract fields | 0        |
+
+## Warnings
+
+_none_
+
+## Suggestions To OpenClaw Compat Layer
+
+_none_
+
+## Issue Findings
+
+_none_
+
+## Contract Probe Backlog
+
+_none_
+
+## Fixture Seam Inventory
+
+| Fixture            | Priority | Seams          | Hooks            | Registrations     | Manifest contracts  |
+| ------------------ | -------- | -------------- | ---------------- | ----------------- | ------------------- |
+| openclaw-agent-acl | high     | plugin-runtime | before_tool_call | definePluginEntry | trustedToolPolicies |
+
+## Decision Matrix
+
+_none_
+
+## Raw Logs
+
+| Fixture            | Code                        | Level | Message                                                                               | Evidence                                                                                    | Compat record |
+| ------------------ | --------------------------- | ----- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------- |
+| openclaw-agent-acl | seam-inventory              | log   | observed 1 hooks, 1 registrations, and 1 manifest contracts                           | hook:before_tool_call, registration:definePluginEntry, manifestContract:trustedToolPolicies | -             |
+| openclaw-agent-acl | package-metadata            | log   | selected package metadata for plugin contract checks                                  | package.json, @randuhmm/openclaw-agent-acl, version:1.0.0                                   | -             |
+| openclaw-agent-acl | declarative-contracts       | log   | fixture declares manifest contracts that can be checked without executing plugin code | trustedToolPolicies                                                                         | -             |
+| openclaw           | target-openclaw-unavailable | log   | target OpenClaw checkout was not available, so compat record coverage was not checked | not configured                                                                              | -             |

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["index.ts"]
+}