[President]

What changed

Adds adapters/openclaw/, an OpenClaw plugin that sends the agent's steps to an ACS Guardian and applies its decisions. It builds on #229; until #229 merges, this diff includes its commits.

Which issue does this implement

Closes #287

Base branch

• integration, because this touches the specification, schemas, a reference
  implementation, an adapter, tests, or CI

Type of change

• Reference implementation or adapter

I tested this

• I synced my branch with the base branch before opening this
• uv run pytest -v passes on my machine
• uv run mkdocs build --strict passes on my machine

Checklist

• Commits are signed off with git commit -s (required by the DCO)
• Prose follows STYLE.md
• No secrets, tokens, or internal URLs in the diff

Security

The adapter is a control point: it blocks what the Guardian denies. adapters/openclaw/mapping.md lists the paths OpenClaw gives no hook for.

[Lrd0036]

Tested at 76e8fd3 against OpenClaw 2026.10.9, at the hook level and on a live gateway. Each live finding reproduced in 3 of 3 runs. The line notes are inline.

The main risk: the adapter does not always run last, so the gateway can run a call the Guardian rewrote with the parameters the Guardian replaced. README.md:76 already tells operators not to run another plugin that returns params. Findings 1 and 2 are about the reason it gives and a case it doesn't name.

What holds up. At the hook level, a deny never sends a message, deny and cancel win in either load order, and a config reload fails closed. In OpenClaw's merge code for before_tool_call and message_sending, block and cancel are sticky and stop the handler chain, so this does not depend on load order.

Findings

1. The adapter does not always run last. README.md:76 says the plugin registers every hook "at the lowest priority", so OpenClaw keeps its params and reply text. Number.MIN_SAFE_INTEGER is not the lowest priority OpenClaw accepts. OpenClaw does not validate priority, and it breaks ties by load order. A test plugin at -Infinity replaced the params the Guardian approved in 3 of 3 live runs. At the hook level, it wins in either load order.

2. A second copy of this adapter undoes the first one's modify. OpenClaw gives each before_tool_call handler a copy of the original event, so each copy decides on the original call. The later copy's allow returns the original params, and OpenClaw keeps the last params returned. Load order decides which Guardian wins. In 3 of 3 live runs, the gateway ran the original command instead of Guardian A's rewrite. A deny still wins in either order.

OpenClaw loads one plugin per id and dropped an unmodified second copy. The live test used two copies of this plugin with only the id renamed (acs-org, acs-team), in openclaw.plugin.json, PLUGIN_ID and package.json. Both were listed in plugins.load.paths, each pointing at its own Guardian. An operator who runs two Guardians would do that, and would not read the README's "another plugin" rule as covering a second copy of this one. Unlike the two cases the README says a plugin cannot detect, this one can be detected, because both copies run in the gateway's process.

3. A Guardian that starts a run on this gateway sets off a chain of nested runs. In the test, the Guardian was a scripted fake built from tests/fake-guardian.ts. Before answering a userMessage, it sent an A2A message to the same gateway and waited for the reply, so the gateway's own agent acted as its judge. Each query opened a new session, and deadlineMs was 3000. With OpenClaw's A2A rate limit off (rateLimitPerMinute: 0), there were 47–49 nested runs in 40 s, and the count had not stopped rising. Every step failed closed, so nothing ran that the Guardian refused. The cost is the runaway runs. The default limit, 30 requests a minute per peer, stopped the chain at 30.

4. exec can read the HMAC secret in the demo setup. OpenClaw's host exec inherits the gateway's environment, minus a fixed list of known credential names such as AWS keys and GITHUB_TOKEN. ACS_HMAC_SECRET is not on that list. hmacSecretFile does not help on the host, because exec can read any file the gateway can. I verified the read, not a forged envelope. Signing one as the adapter takes only the secret and the key_id, and the demo config file holds the key_id.

5. A message the agent sends to its own gateway looks like another message from the same peer. It reached the Guardian with the same user_context as the original, and nothing linked it to the run that sent it, so policy cannot bound the depth. In the test, a script run through the agent's exec tool read A2A_DEMO_TOKEN from its environment and used it to message the gateway. The token reaches exec the same way as the secret in finding 4. The test supplied the script, because the stub model makes no choices, so this shows what the agent's tool can do, not what a model chose to do.

Suggested fixes

All untested.

• Detect a second copy at registration, for example with a marker on globalThis, and block every step when one is found (finding 2).
• Stop sending after repeated deadline expiries, so a Guardian whose decisions keep timing out ends its own chain (finding 3).
• Report A2A inbound as agentTrigger with trigger_type: "a2a_inbound" (finding 5).
• In the README, correct the priority claim, support one copy per gateway, and say how to keep the secret and the A2A token out of the agent's reach. OpenClaw appears to skip the host environment for sandboxed exec, which may be the answer.

api.registerTrustedToolPolicy does not fix finding 1. Trusted policies run before the before_tool_call hooks, and a later hook's params still win. OpenClaw locks the parameters only after a trusted policy has asked for approval and received it.

The spec does not say whether more than one adapter or Guardian may govern one host. That deserves its own issue rather than a fix here.

How this was tested

• Hook level: the plugin's own register(), loaded twice into OpenClaw's createHookRunner.
• Live: OpenClaw 2026.10.9 from npm in a node:24 container, with the demo config and stub model. The pinned ghcr.io image was not reachable from my environment.
• Guardians: tests/fake-guardian.ts. Its system/ping signature errors are a limit of the fake Guardian.

Repro: a second adapter undoes the first one's modify

Save as adapters/openclaw/tests/two-adapters.repro.test.ts and run bun test tests/two-adapters.repro.test.ts. It passes, which means the gateway runs the original command. With Guardian A's copy alone, or with the load order reversed, the rewrite runs. Both Guardians receive the original command.

// Two copies of this plugin on one gateway, run through OpenClaw 2026.10.9's own hook runner.
// Guardian A rewrites the command; Guardian B allows. OpenClaw runs B's (original) params.
import { expect, it } from "bun:test";
import plugin from "../acs-plugin.ts";
import { startFakeGuardian } from "./fake-guardian.ts";
// The hashed chunk name is specific to OpenClaw 2026.10.9.
import { t as createHookRunner } from "../node_modules/openclaw/dist/hooks-CgZHhfMh.mjs";

const KEY = { keyId: "k", secret: Buffer.from("0123456789abcdef0123456789abcdef") };
process.env.ACS_REPRO_SECRET = KEY.secret.toString("base64");
const METHODS = ["steps/userMessage", "steps/toolCallRequest", "steps/agentResponse"];
const allow = { decision: { decision: "allow" } };
const rewrite = { decision: { decision: "modify", reasoning: "mask", modifications: { parameter_overrides: { command: "ls /tmp/work" } } } };

function store() {
  const rows = new Map<string, unknown>();
  return {
    register: async (k: string, v: unknown) => void rows.set(k, v),
    registerIfAbsent: async (k: string, v: unknown) => (rows.has(k) ? false : (rows.set(k, v), true)),
    lookup: async (k: string) => rows.get(k),
    consume: async (k: string) => { const v = rows.get(k); rows.delete(k); return v; },
    delete: async (k: string) => void rows.delete(k),
    entries: async () => [...rows].map(([key, value]) => ({ key, value })),
    update: async (k: string, f: (c: unknown) => unknown) => { const v = f(rows.get(k)); if (v !== undefined) rows.set(k, v); },
  };
}

function load(registry: { typedHooks: unknown[] }, pluginId: string, guardianUrl: string) {
  const stores = new Map<string, ReturnType<typeof store>>();
  plugin.register({
    pluginConfig: { guardianUrl, hmacKeyId: KEY.keyId, hmacSecretEnv: "ACS_REPRO_SECRET" },
    runtime: { state: { openKeyedStore: ({ namespace }: { namespace: string }) => stores.get(namespace) ?? stores.set(namespace, store()).get(namespace)! } },
    logger: { error() {}, warn() {}, info() {} },
    on: (hookName: string, handler: unknown, opts?: { priority?: number }) => registry.typedHooks.push({ pluginId, hookName, handler, priority: opts?.priority }),
    registerAgentToolResultMiddleware() {},
  } as never);
}

it("lets the second adapter's allow undo the first adapter's modify", async () => {
  const a = startFakeGuardian({ key: KEY, methodsEvaluated: METHODS, reply: (s) => (s.method === "steps/toolCallRequest" ? rewrite : allow) });
  const b = startFakeGuardian({ key: KEY, methodsEvaluated: METHODS, reply: () => allow });
  const registry = { typedHooks: [] as unknown[] };
  load(registry, "acs-a", a.url);
  load(registry, "acs-b", b.url);
  const runner = createHookRunner(registry as never, {});
  const ctx = { runId: "run-1", sessionKey: "agent:main:signal:direct:+15550100", sessionId: "session-1", senderId: "+15550100", channel: "signal" };
  await runner.runBeforeAgentRun({ prompt: "clean up", senderId: "+15550100" }, ctx);
  const result = await runner.runBeforeToolCall({ toolName: "exec", params: { command: "rm -rf /tmp/work" } }, ctx);
  a.stop();
  b.stop();
  expect(result?.params).toEqual({ command: "rm -rf /tmp/work" }); // Guardian A asked for "ls /tmp/work"
});

[Lrd0036]

This keeps the plugin last only while nothing else registers below it, or at the same priority and later. OpenClaw sorts hooks by priority without validating the number, and it breaks ties by load order. A test plugin at -Infinity ran after this one, and its params won in 3 of 3 live runs. The comment on line 187 says this plugin runs last.

[Lrd0036]

With two copies of this plugin, each one sees the original params, because OpenClaw clones the event for each before_tool_call handler. This allow returns those params, and OpenClaw keeps the last params returned, so a later copy's allow drops an earlier copy's modify. The original command ran in 3 of 3 live runs.

Returning params here also keeps a higher-priority plugin's change from running unseen by the Guardian. Returning nothing on allow would trade one problem for the other, so detecting a second copy at registration may be the cleaner fix.

[Lrd0036]

This is the same pattern on message_sending. Every handler gets the original event, and OpenClaw keeps the last content, so this allow drops an earlier copy's rewrite. I reproduced this at the hook level only. A reply that passes reply_payload_sending first keeps the earlier copy's redaction, because that hook returns nothing on allow (line 216). A delivery that reaches only message_sending loses it.

[Lrd0036]

Each admission gets a fresh deadline, and OpenClaw's hook timeout races the handler without cancelling it. A Guardian whose decision starts a run on this gateway produced 47–49 nested runs in 40 s live, with the A2A rate limit off. At most 6 were open at once, so a concurrency cap would not trip. A breaker after repeated deadline expiries would, though I have not tested it.

[Lrd0036]

A message from an A2A peer becomes user_message. A message sent from the agent's exec tool to its own gateway reached the Guardian with the same user_context as the original, and nothing linked the two. The agentTrigger section of the Hooks page says A2A delegation uses trigger_type: "a2a_inbound" to carry the peer's identity. This PR's README also sends agentTrigger for runs that do not start with a person's message.

[Lrd0036]

Number.MIN_SAFE_INTEGER is not the lowest priority OpenClaw accepts (see acs-plugin.ts:188). This rule also needs to name a second copy of this adapter. An operator who runs two Guardians will not read "another plugin" as covering it.

[Lrd0036]

Sorry for bombarding you with the comments. I was more just curious about this one because we're not black-boxed on the actual codebase for... what this adapter feeds into. I kept these as comments instead of requested changes just because they're optional, but could theoretically drive improvements with the 'black box' adapters.

I don't know what else to call them besides 'black box'–all I mean by that is Openclaw is OSS. Codex is not. We can hope that Claude, Cursor, and Codex have accurate documentation. lol.

but! I did test this thorougly and it might be over-engineering to actually implement these fixes. so. it's optional.

Thanks

[President]

@Lrd0036 huge thanks for the review! All five are addressed in 28844e9:

1 and 2. Another plugin, or a second copy of this one, can run after the adapter. We can't prevent that, so the README now warns about it. Whoever installs plugins is responsible. I didn't add a check for a second copy: it's a rare case, and IMHO it's not worth the extra code.

3. IMHO it isn't an adapter problem - it's a Guardian's. The README says this setup isn't supported, and I opened #514 to discuss it for the spec.

4. Any agent with exec can read secrets. The README now says to deny exec or run it in a sandbox, which drops the gateway's env vars.

5. The README also says to keep channel tokens away from the agent. a2a_inbound wouldn't tell us which run sent the message, so agentTrigger wouldn't help, and I kept userMessage. It stays listed under "Not met".