From ef263aea43cf99b5df1b6853f9df84c3e8dde4d2 Mon Sep 17 00:00:00 2001 From: jesse-merhi <79823012+jesse-merhi@users.noreply.github.com> Date: Tue, 11 Aug 2026 03:49:20 +1000 Subject: [PATCH] docs(security): clarify policy reevaluation outcomes --- docs/gateway/protocol.md | 2 +- docs/tools/plugin.md | 3 ++- docs/tools/skills-config.md | 3 ++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 9438075f32bf..0ed572684e57 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -551,7 +551,7 @@ methods. Treat this as feature discovery, not a full enumeration of - `plugins.list` (`operator.read`) returns the installed plugin inventory plus locally curated official picks, diagnostics, and whether the current install mode allows mutations. - `plugins.search` (`operator.read`) searches installable ClawHub code-plugin and bundle-plugin families. Pass non-empty `query` and optional `limit` from 1 to 100. - - `plugins.install` (`operator.admin`) installs either an official catalog entry with `{ source: "official", pluginId, installPolicyWarningAcknowledgement? }` or a ClawHub package with `{ source: "clawhub", packageName, version?, acknowledgeClawHubRisk?, installPolicyWarningAcknowledgement? }`. ClawHub installs preserve Gateway trust, integrity, and install-policy checks. When install policy warns and the Gateway can bind the request to an immutable resolved artifact, the request fails before commit with structured `error.details` containing `installPolicyCode: "install_policy_warning_acknowledgement_required"`, target metadata, `reason`, optional `findings`, and a server-issued `acknowledgementToken`. After showing those details, a client may retry with that token as `installPolicyWarningAcknowledgement`. The Gateway consumes the token once and only for the same install request and resolved artifact; policy then re-evaluates the staged source and continues only when the warning is unchanged. Tokens expire after five minutes and are invalidated by a Gateway restart; after either event, retry without the token to receive the current warning and a fresh token. A changed or later warning fails that request with its own structured details and, when the artifact remains immutably resolved, a fresh token for another reviewed retry. A block or a warning without immutable resolution metadata is terminal and does not include an acknowledgement token. Successful installs require a Gateway restart. + - `plugins.install` (`operator.admin`) installs either an official catalog entry with `{ source: "official", pluginId, installPolicyWarningAcknowledgement? }` or a ClawHub package with `{ source: "clawhub", packageName, version?, acknowledgeClawHubRisk?, installPolicyWarningAcknowledgement? }`. ClawHub installs preserve Gateway trust, integrity, and install-policy checks. When install policy warns and the Gateway can bind the request to an immutable resolved artifact, the request fails before commit with structured `error.details` containing `installPolicyCode: "install_policy_warning_acknowledgement_required"`, target metadata, `reason`, optional `findings`, and a server-issued `acknowledgementToken`. After showing those details, a client may retry with that token as `installPolicyWarningAcknowledgement`. The Gateway consumes the token once and only for the same install request and resolved artifact; policy then re-evaluates the staged source and continues when that fresh evaluation allows the install or repeats the unchanged warning the operator approved. Tokens expire after five minutes and are invalidated by a Gateway restart; after either event, retry without the token to receive the current warning and a fresh token. A changed or later warning fails that request with its own structured details and, when the artifact remains immutably resolved, a fresh token for another reviewed retry. A block or a warning without immutable resolution metadata is terminal and does not include an acknowledgement token. Successful installs require a Gateway restart. - `plugins.setEnabled` (`operator.admin`) changes one installed plugin's enabled policy with `{ pluginId, enabled }`. The response includes the updated catalog entry, restart metadata, and any slot-selection warnings. - `plugins.uninstall` (`operator.admin`) removes one externally installed plugin with `{ pluginId }`: config references, the install record, and managed files. Bundled plugins cannot be uninstalled, only disabled. The response lists the removal actions and always requires a Gateway restart. diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 990a475614a1..65cfd5531cdc 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -158,7 +158,8 @@ Gateway can bind the request to an immutable resolved artifact, and may make one explicit retry with the returned `acknowledgementToken` as `installPolicyWarningAcknowledgement`. The Gateway consumes that server-issued token once and only for the same install request and resolved artifact. OpenClaw -re-evaluates the staged source and continues only when the warning is unchanged. +re-evaluates the staged source and continues when that fresh evaluation allows +the install or repeats the unchanged warning the operator approved. A changed or later warning stops the request before commit and receives a fresh token when the artifact remains immutably resolved. A block or a warning without immutable resolution metadata is terminal and has no acknowledgement token. diff --git a/docs/tools/skills-config.md b/docs/tools/skills-config.md index 2cdfe918111c..866f90d2dac1 100644 --- a/docs/tools/skills-config.md +++ b/docs/tools/skills-config.md @@ -206,7 +206,8 @@ Gateway can bind the request to an immutable resolved artifact, and may make one explicit retry with the returned `acknowledgementToken` as `installPolicyWarningAcknowledgement`. The Gateway consumes that server-issued token once and only for the same install request and resolved artifact. OpenClaw -re-evaluates the staged source and continues only when the warning is unchanged. +re-evaluates the staged source and continues when that fresh evaluation allows +the install or repeats the unchanged warning the operator approved. A changed or later warning stops the request before commit and receives a fresh token when the artifact remains immutably resolved. A block or a warning without immutable resolution metadata is terminal and has no acknowledgement token. Other