docs(security): clarify policy reevaluation outcomes

docs/gateway/protocol.md

@@ -551,7 +551,7 @@ methods. Treat this as feature discovery, not a full enumeration of
   <Accordion title="Plugin management">
     - `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.
 

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.

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