From 5b538d367fe0c911ff8c30695f16eb28afc1ca51 Mon Sep 17 00:00:00 2001
From: jesse-merhi <79823012+jesse-merhi@users.noreply.github.com>
Date: Wed, 6 May 2026 15:58:09 +1000
Subject: [PATCH] docs: clarify blocked hook metadata

---
 docs/plugins/hooks.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/plugins/hooks.md b/docs/plugins/hooks.md
index cd2d6c18ca8..c007c5eaf0e 100644
--- a/docs/plugins/hooks.md
+++ b/docs/plugins/hooks.md
@@ -242,9 +242,10 @@ to stop the run before the model can read the prompt. `reason` is internal;
 `pass` and `block`; unsupported decision shapes fail closed.
 
 When a run is blocked, OpenClaw stores only the replacement text in
-`message.content` plus non-sensitive block metadata such as the blocking plugin,
-reason, and timestamp. The original user text is not retained in transcript or
-history metadata.
+`message.content` plus non-sensitive block metadata such as the blocking plugin
+id and timestamp. The original user text is not retained in transcript or future
+context. The internal block reason remains logging/diagnostics-only and is not
+stored in transcript or history metadata.
 
 `before_agent_start` and `agent_end` include `event.runId` when OpenClaw can
 identify the active run. The same value is also available on `ctx.runId`.