refactor: per-plugin control-flow tool filtering

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

docs/docs/concepts/plugins.mdx

@@ -658,7 +658,7 @@ async def cap_tokens(payload, ctx):
 
 **Fires:** Before invoking a tool from LLM output.
 
-**Payload fields:** `model_tool_call` (contains `name`, `args`, `callable`)
+**Payload fields:** `model_tool_call` (contains `name`, `args`, `callable`), `is_control_flow`
 
 **Writable fields:** `model_tool_call`
 
@@ -675,14 +675,14 @@ async def enforce_tool_allowlist(payload, ctx):
 ```
 
 <Note>
-By default, `tool_pre_invoke` and `tool_post_invoke` hooks are **skipped for framework-internal tools** such as the ReAct loop's `final_answer` tool. This prevents allowlist plugins from accidentally blocking internal control flow. See [Internal tool exemption](#internal-tool-exemption) for details and how to opt out.
+The payload includes an `is_control_flow` field that is `True` for framework control-flow tools (e.g. the ReAct loop's `final_answer`). Allowlist plugins should check this field to avoid blocking internal tools. See [Control-flow tools](#control-flow-tools) for the recommended pattern.
 </Note>
 
 #### `tool_post_invoke`
 
 **Fires:** After tool execution completes.
 
-**Payload fields:** `model_tool_call`, `tool_output`, `tool_message`, `execution_time_ms`, `success`, `error`
+**Payload fields:** `model_tool_call`, `tool_output`, `tool_message`, `execution_time_ms`, `success`, `error`, `is_control_flow`
 
 **Writable fields:** `tool_output`
 
@@ -814,13 +814,15 @@ The `tool_pre_invoke` and `tool_post_invoke` hooks give you fine-grained control
 
 ### Tool allow-listing
 
-Block any tool not on an explicit approved list:
+Block any tool not on an explicit approved list. The `is_control_flow` guard ensures framework tools like `final_answer` are not blocked:
 
 ```python
 ALLOWED_TOOLS = frozenset({"get_weather", "calculator"})
 
 @hook(HookType.TOOL_PRE_INVOKE, mode=PluginMode.CONCURRENT, priority=5)
 async def enforce_tool_allowlist(payload, ctx):
+    if payload.is_control_flow:
+        return  # framework control-flow tools are exempt
     tool_name = payload.model_tool_call.name
     if tool_name not in ALLOWED_TOOLS:
         return block(f"Tool '{tool_name}' is not permitted", code="TOOL_NOT_ALLOWED")
@@ -882,49 +884,43 @@ with start_session(plugins=[tool_security]) as m:
 
 See the [full tool hooks example](https://github.com/generative-computing/mellea/blob/main/docs/examples/plugins/tool_hooks.py).
 
-### Internal tool exemption
+### Control-flow tools
 
-Mellea's frameworks use internal tools that are invisible to application developers. For example, the [ReAct loop](../reference/glossary#react) uses a `final_answer` tool to signal that the agent has finished reasoning. These tools flow through the same invocation path as user-defined tools, which means a `tool_pre_invoke` allowlist plugin would block them — breaking the framework.
+Mellea's frameworks use internal tools for control flow. For example, the [ReAct loop](../reference/glossary#react) uses a `final_answer` tool to signal that the agent has finished reasoning. These tools flow through the same invocation path as user-defined tools — hooks always fire for them — but the payload carries an `is_control_flow` flag so each plugin can decide its own policy.
 
-To prevent this, **tool hooks are skipped for framework-internal tools by default**. Both `tool_pre_invoke` and `tool_post_invoke` are bypassed; the tool itself still executes normally.
-
-This means you can write a tool allowlist plugin that lists only your own tools, without worrying about framework internals:
+The recommended pattern for allowlist plugins is to skip control-flow tools explicitly:
 
 ```python
 ALLOWED_TOOLS = frozenset({"get_weather", "calculator"})
 
 @hook(HookType.TOOL_PRE_INVOKE, mode=PluginMode.CONCURRENT, priority=5)
 async def enforce_tool_allowlist(payload, ctx):
+    if payload.is_control_flow:
+        return  # framework control-flow tools are exempt
     if payload.model_tool_call.name not in ALLOWED_TOOLS:
         return block(f"Tool '{payload.model_tool_call.name}' not permitted")
-    # final_answer will never reach this hook — it is automatically exempted
 ```
 
-#### Checking whether a tool is internal
-
-Use `is_internal_tool()` to query the internal tools registry:
+Logging and telemetry plugins typically do **not** check this flag — they observe all tool calls including control-flow tools:
 
 ```python
-from mellea.plugins import is_internal_tool
-
-is_internal_tool("final_answer")  # True
-is_internal_tool("get_weather")   # False
+@hook(HookType.TOOL_POST_INVOKE, mode=PluginMode.FIRE_AND_FORGET)
+async def log_all_tools(payload, ctx):
+    logger.info("tool=%s control_flow=%s ms=%d", payload.model_tool_call.name,
+                payload.is_control_flow, payload.execution_time_ms)
 ```
 
-#### Opting out
+#### Querying the registry
 
-If your plugin genuinely needs to intercept internal tools (e.g., for deep audit logging of every tool invocation including framework tools), disable the exemption:
+Use `is_internal_tool()` to check whether a tool name is a known control-flow tool:
 
 ```python
-from mellea.plugins import set_skip_hooks_for_internal_tools
+from mellea.plugins import is_internal_tool
 
-set_skip_hooks_for_internal_tools(False)  # all tools now fire hooks
+is_internal_tool("final_answer")  # True
+is_internal_tool("get_weather")   # False
 ```
 
-<Warning>
-Disabling the exemption means your allowlist plugin must explicitly permit internal tools like `final_answer`, or the ReAct loop will fail with a `PluginViolationError`.
-</Warning>
-
 ---
 
 ## Patterns and best practices
@@ -1026,12 +1022,10 @@ from mellea.plugins import (
     PluginViolationError,            # Exception raised when a hook blocks execution
     block,                           # Helper to create a blocking PluginResult
     hook,                            # Decorator to register an async function as a hook handler
-    is_internal_tool,                # Check if a tool name is framework-internal
+    is_internal_tool,                # Check if a tool is a framework control-flow tool
     modify,                          # Helper to create a modifying PluginResult
     plugin_scope,                    # Context manager for with-block scoped activation
     register,                        # Register hooks/plugins globally or per-session
-    set_skip_hooks_for_internal_tools, # Enable/disable tool hook exemption for internal tools
-    skip_hooks_for_internal_tools,   # Query current exemption state
     unregister,                      # Remove globally-registered hooks/plugins
 )
 ```
@@ -1046,9 +1040,7 @@ from mellea.plugins import (
 | `plugin_scope(*items)` | Context manager that registers on enter, deregisters on exit |
 | `block(reason, *, code, details)` | Create a blocking `PluginResult` |
 | `modify(payload, **field_updates)` | Create a modifying `PluginResult` via `model_copy` |
-| `is_internal_tool(tool_name)` | Returns `True` if the tool is framework-internal (e.g. `final_answer`) |
-| `skip_hooks_for_internal_tools()` | Returns `True` if tool hooks are currently skipped for internal tools |
-| `set_skip_hooks_for_internal_tools(enabled)` | Enable or disable tool hook exemption for internal tools |
+| `is_internal_tool(tool_name)` | Returns `True` if the tool is a framework control-flow tool (e.g. `final_answer`) |
 | `HookType` | Enum with all 18 hook types |
 | `PluginMode` | Enum: `SEQUENTIAL`, `TRANSFORM`, `AUDIT`, `CONCURRENT`, `FIRE_AND_FORGET` |
 | `PluginResult` | Typed result with `continue_processing`, `modified_payload`, and `violation` |

docs/examples/plugins/tool_hooks.py

@@ -150,6 +150,8 @@ def parse_factor():
 @hook(HookType.TOOL_PRE_INVOKE, mode=PluginMode.CONCURRENT, priority=5)
 async def enforce_tool_allowlist(payload, _):
     """Block any tool not on the explicit allow list."""
+    if payload.is_control_flow:
+        return  # framework control-flow tools (e.g. final_answer) are exempt
     tool_name = payload.model_tool_call.name
     if tool_name not in ALLOWED_TOOLS:
         log.warning(

mellea/plugins/__init__.py

@@ -9,11 +9,7 @@
 
 from .base import Plugin, PluginResult, PluginViolationError
 from .decorators import hook
-from .manager import (
-    is_internal_tool,
-    set_skip_hooks_for_internal_tools,
-    skip_hooks_for_internal_tools,
-)
+from .manager import is_internal_tool
 from .pluginset import PluginSet
 from .registry import block, modify, plugin_scope, register, unregister
 from .types import HookType, PluginMode
@@ -31,7 +27,5 @@
     "modify",
     "plugin_scope",
     "register",
-    "set_skip_hooks_for_internal_tools",
-    "skip_hooks_for_internal_tools",
     "unregister",
 ]

mellea/plugins/hooks/tool.py

@@ -13,9 +13,13 @@ class ToolPreInvokePayload(MelleaBasePayload):
     Attributes:
         model_tool_call: The ``ModelToolCall`` about to be executed (writable —
             plugins may modify arguments or swap the tool entirely).
+        is_control_flow: ``True`` when this tool is used for framework control
+            flow (e.g. ``final_answer`` in ReAct) rather than data processing.
+            Plugins should check this field to decide whether to act.
     """
 
     model_tool_call: Any = None
+    is_control_flow: bool = False
 
 
 class ToolPostInvokePayload(MelleaBasePayload):
@@ -29,6 +33,9 @@ class ToolPostInvokePayload(MelleaBasePayload):
         execution_time_ms: Wall-clock time of the tool execution in milliseconds.
         success: ``True`` if the tool executed without raising an exception.
         error: The ``Exception`` raised during execution, or ``None`` on success.
+        is_control_flow: ``True`` when this tool is used for framework control
+            flow (e.g. ``final_answer`` in ReAct) rather than data processing.
+            Plugins should check this field to decide whether to act.
     """
 
     model_tool_call: Any = None
@@ -37,3 +44,4 @@ class ToolPostInvokePayload(MelleaBasePayload):
     execution_time_ms: int = 0
     success: bool = True
     error: Any = None
+    is_control_flow: bool = False

mellea/plugins/manager.py

@@ -29,10 +29,9 @@
 _pending_background_results: list[Any] = []
 _collect_background_results: bool = False  # opt-in; only tests enable this
 
-# Framework-internal tool names that bypass plugin hooks by default.
-# See mellea.stdlib.components.react.MELLEA_FINALIZER_TOOL
+# Framework control-flow tool names (e.g. loop terminators).
+# These are flagged on the payload so plugins can decide per-tool policy.
 _INTERNAL_TOOL_NAMES: frozenset[str] = frozenset({"final_answer"})
-_skip_hooks_for_internal_tools: bool = True
 
 DEFAULT_PLUGIN_TIMEOUT: int = 5  # seconds
 DEFAULT_HOOK_POLICY: Literal["allow"] | Literal["deny"] = "deny"
@@ -93,29 +92,6 @@ def has_plugins(hook_type: HookType | None = None) -> bool:
     return True
 
 
-def skip_hooks_for_internal_tools() -> bool:
-    """Return whether tool hooks are skipped for framework-internal tools.
-
-    Returns:
-        ``True`` if hooks are bypassed for internal tools like ``final_answer``.
-    """
-    return _skip_hooks_for_internal_tools
-
-
-def set_skip_hooks_for_internal_tools(enabled: bool) -> None:
-    """Control whether tool hooks are skipped for framework-internal tools.
-
-    When *enabled* (the default), ``tool_pre_invoke`` and ``tool_post_invoke``
-    hooks will not fire for tools in the internal registry (e.g. ``final_answer``).
-    Set to ``False`` if your plugin intentionally needs to intercept internal tools.
-
-    Args:
-        enabled: ``True`` to skip hooks for internal tools, ``False`` to invoke them.
-    """
-    global _skip_hooks_for_internal_tools
-    _skip_hooks_for_internal_tools = enabled
-
-
 def is_internal_tool(tool_name: str) -> bool:
     """Return whether the given tool name is a framework-internal tool.
 
@@ -212,11 +188,7 @@ async def initialize_plugins(
 
 async def shutdown_plugins() -> None:
     """Shut down the PluginManager and reset all state."""
-    global \
-        _plugin_manager, \
-        _plugins_enabled, \
-        _session_tags, \
-        _skip_hooks_for_internal_tools
+    global _plugin_manager, _plugins_enabled, _session_tags
 
     if _plugin_manager is not None:
         await _plugin_manager.shutdown()

mellea/stdlib/functional.py

@@ -30,12 +30,7 @@
 )
 from ..helpers import _run_async_in_thread
 from ..plugins.hooks.tool import ToolPostInvokePayload, ToolPreInvokePayload
-from ..plugins.manager import (
-    has_plugins,
-    invoke_hook,
-    is_internal_tool,
-    skip_hooks_for_internal_tools,
-)
+from ..plugins.manager import has_plugins, invoke_hook, is_internal_tool
 from ..plugins.types import HookType
 from ..telemetry import set_span_attribute, trace_application
 from .components import (
@@ -1292,11 +1287,13 @@ async def _acall_tools(result: ModelOutputThunk, backend: Backend) -> list[ToolM
         return outputs
 
     for name, tool in tool_calls.items():
-        run_hooks = not (skip_hooks_for_internal_tools() and is_internal_tool(name))
+        control_flow = is_internal_tool(name)
 
         # --- tool_pre_invoke ---
-        if run_hooks and has_plugins(HookType.TOOL_PRE_INVOKE):
-            pre_payload = ToolPreInvokePayload(model_tool_call=tool)
+        if has_plugins(HookType.TOOL_PRE_INVOKE):
+            pre_payload = ToolPreInvokePayload(
+                model_tool_call=tool, is_control_flow=control_flow
+            )
             _, pre_payload = await invoke_hook(
                 HookType.TOOL_PRE_INVOKE, pre_payload, backend=backend
             )
@@ -1334,14 +1331,15 @@ async def _acall_tools(result: ModelOutputThunk, backend: Backend) -> list[ToolM
         )
 
         # --- tool_post_invoke ---
-        if run_hooks and has_plugins(HookType.TOOL_POST_INVOKE):
+        if has_plugins(HookType.TOOL_POST_INVOKE):
             post_payload = ToolPostInvokePayload(
                 model_tool_call=tool,
                 tool_output=output,
                 tool_message=tool_msg,
                 execution_time_ms=latency_ms,
                 success=success,
                 error=error,
+                is_control_flow=control_flow,
             )
             _, post_payload = await invoke_hook(
                 HookType.TOOL_POST_INVOKE, post_payload, backend=backend