From a19725bc57f010e4ddd471da58950b764d8e5a39 Mon Sep 17 00:00:00 2001 From: michaelxer Date: Sun, 21 Jun 2026 04:06:38 +0700 Subject: [PATCH] docs: add note about ephemeral guard and per-call hooks contextvar MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document that SDK callers always go through run() → process_direct(ephemeral=False), so per_call hooks are intentionally excluded from ephemeral turns per chengyongru review feedback. --- nanobot/agent/loop.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/nanobot/agent/loop.py b/nanobot/agent/loop.py index 1f7906c1..43662489 100644 --- a/nanobot/agent/loop.py +++ b/nanobot/agent/loop.py @@ -729,6 +729,10 @@ class AgentLoop: hook: AgentHook = loop_hook per_call = _per_call_hooks.get() extra_hooks = None + # NOTE: SDK callers always go through run() → process_direct(ephemeral=False), + # so per_call hooks are intentionally excluded from ephemeral turns. If a future + # caller sets the contextvar and then calls process_direct(ephemeral=True), the + # hooks will correctly NOT fire (ephemeral guard takes precedence). if not ephemeral: extra_hooks = per_call if per_call is not None else self._extra_hooks if extra_hooks: