diff --git a/gateway/hooks.py b/gateway/hooks.py
index 5ab45119202..1ea7faa32a1 100644
--- a/gateway/hooks.py
+++ b/gateway/hooks.py
@@ -17,6 +17,23 @@ Events:
   - command:*           -- Any slash command executed (wildcard match)
 
 Errors in hooks are caught and logged but never block the main pipeline.
+
+Context dict passed to ``agent:start`` / ``agent:end`` handlers:
+  platform     -- source platform name (e.g. "telegram", "matrix", "slack")
+  user_id      -- platform user id of the sender
+  chat_id      -- platform chat id (group/DM identifier)
+  thread_id    -- Telegram forum-topic id / thread root id (string; empty
+                  when not in a thread / topic)
+  chat_type    -- "dm" | "group" | "forum" (empty if unknown)
+  session_id   -- Hermes session id
+  message      -- inbound message text (truncated to 500 chars)
+
+``agent:end`` adds:
+  response     -- agent response text (truncated to 500 chars)
+
+Handlers posting a follow-up into the same Telegram forum-topic should
+include ``message_thread_id=int(thread_id)`` when ``chat_type == "forum"``
+and ``thread_id`` is non-empty.
 """
 
 import asyncio
diff --git a/gateway/run.py b/gateway/run.py
index f643eadf4a7..3d0eb848d61 100644
--- a/gateway/run.py
+++ b/gateway/run.py
@@ -9552,6 +9552,8 @@ class GatewayRunner:
                 "platform": source.platform.value if source.platform else "",
                 "user_id": source.user_id,
                 "chat_id": source.chat_id or "",
+                "thread_id": str(getattr(source, "thread_id", None)) if getattr(source, "thread_id", None) else "",
+                "chat_type": getattr(source, "chat_type", "") or "",
                 "session_id": session_entry.session_id,
                 "message": message_text[:500],
             }