feat(hooks): add Deny.abort to support hard-abort of agent loop

Guards can now return Deny(reason, abort=True) to immediately terminate
the agent loop instead of just injecting a soft-denial tool result.
BeforeIteration also gains guard support for early iteration blocking.

Author: root

docs/hook-plugin-guide.md

@@ -62,6 +62,24 @@ class RateLimitHandler:
 
         self._counts[session_id] = count + len(event.tool_calls)
         return None
+
+
+class BlocklistHandler:
+    """Abort the agent loop if a blocked tool is called."""
+
+    hook_events = [(BeforeExecuteTools, "guard")]
+
+    def __init__(self, blocked_tools: list[str] | None = None) -> None:
+        self._blocked = set(blocked_tools or [])
+
+    async def __call__(self, event: BeforeExecuteTools):
+        for tc in event.tool_calls:
+            if tc.name in self._blocked:
+                return Deny(
+                    f"Blocked tool '{tc.name}' — agent loop aborted",
+                    abort=True,
+                )
+        return None
 ```
 
 ### 2. Register the Entry Point
@@ -127,7 +145,8 @@ async def handler(event: EventType) -> HookResult | Modified | Deny | None: ...
 |-------------|----------|--------|
 | `None` | Observe | No action needed; handler ran as a side-effect |
 | `Modified(data)` | Transform | Apply the returned data to the event (dict keys mapped to event fields) |
-| `Deny(reason)` | Guard | Block the operation — runner injects the reason as a tool result |
+| `Deny(reason)` | Guard (soft) | Block the operation — runner injects the reason as a tool result and continues the loop |
+| `Deny(reason, abort=True)` | Guard (hard) | Block the operation — runner terminates the agent loop immediately, `reason` becomes the final content |
 
 ### Declaring subscriptions
 
@@ -149,7 +168,7 @@ v1 exposes six event types covering the agent iteration lifecycle:
 
 | Event | Fields | Mode |
 |-------|--------|------|
-| `BeforeIteration` | `iteration`, `messages` | observe |
+| `BeforeIteration` | `iteration`, `messages` | guard, observe |
 | `OnStream` | `delta`, `iteration` | observe |
 | `OnStreamEnd` | `resuming`, `iteration` | observe |
 | `BeforeExecuteTools` | `iteration`, `tool_calls`, `response` | guard, observe |

nanobot/agent/runner.py

@@ -295,7 +295,14 @@ async def run(self, spec: AgentRunSpec) -> AgentRunResult:
                     messages_for_model = messages
             context = AgentHookContext(iteration=iteration, messages=messages)
             session.context = context
-            await center.emit(BeforeIteration(iteration=iteration, messages=messages), session)
+            bi_result = await center.emit(BeforeIteration(iteration=iteration, messages=messages), session)
+            if isinstance(bi_result, Deny) and bi_result.abort:
+                final_content = bi_result.reason
+                stop_reason = "aborted"
+                context.final_content = final_content
+                context.stop_reason = stop_reason
+                await center.emit(_make_after_iteration(context, iteration), session)
+                break
             response = await self._request_model(spec, messages_for_model, center, session, context)
             raw_usage = self._usage_dict(response.usage)
             context.response = response
@@ -334,6 +341,13 @@ async def run(self, spec: AgentRunSpec) -> AgentRunResult:
 
                 result = await center.emit(BeforeExecuteTools(iteration=iteration, tool_calls=context.tool_calls, response=context.response), session)
                 if isinstance(result, Deny):
+                    if result.abort:
+                        final_content = result.reason
+                        stop_reason = "aborted"
+                        context.final_content = final_content
+                        context.stop_reason = stop_reason
+                        await center.emit(_make_after_iteration(context, iteration), session)
+                        break
                     for tc in tool_calls:
                         messages.append({
                             "role": "tool",
@@ -347,16 +361,7 @@ async def run(self, spec: AgentRunSpec) -> AgentRunResult:
                     )
                     empty_content_retries = 0
                     length_recovery_count = 0
-                    await center.emit(AfterIteration(
-                        iteration=iteration,
-                        final_content=context.final_content,
-                        stop_reason=context.stop_reason,
-                        usage=dict(context.usage),
-                        tool_calls=list(context.tool_calls),
-                        tool_events=list(context.tool_events),
-                        tool_results=list(context.tool_results),
-                        error=context.error,
-                    ), session)
+                    await center.emit(_make_after_iteration(context, iteration), session)
                     continue
 
                 results, new_events, fatal_error = await self._execute_tools(

nanobot/hooks/protocols.py

@@ -24,10 +24,17 @@ class Deny:
     ``reason`` is a human-readable string explaining the denial.
     The caller (emit site) decides how to act on it — soft-deny
     (inject reason into the conversation) or hard-deny (abort the
-    operation).
+    agent loop entirely).
+
+    When ``abort`` is ``False`` (default), the operation is denied
+    but the agent loop continues — the reason is injected as a tool
+    result so the LLM can adapt.  When ``abort`` is ``True``, the
+    agent loop terminates immediately and ``reason`` becomes the
+    final content returned to the caller.
     """
 
     reason: str
+    abort: bool = False
 
 
 HookResult = Modified | Deny | None