jeevesagent.security.hooks
==========================

.. py:module:: jeevesagent.security.hooks

.. autoapi-nested-parse::

   User-registered lifecycle callbacks.

   Hooks run in a timeout-shielded scope so a buggy callback can't hang
   the loop. Pre-tool hooks can deny a call (first deny wins); post-tool
   hooks are best-effort and can never affect the result.



Attributes
----------

.. autoapisummary::

   jeevesagent.security.hooks.EventHook
   jeevesagent.security.hooks.PostToolHook
   jeevesagent.security.hooks.PreToolHook


Classes
-------

.. autoapisummary::

   jeevesagent.security.hooks.HookRegistry


Module Contents
---------------

.. py:class:: HookRegistry

   Implements :class:`~jeevesagent.core.protocols.HookHost`.


   .. py:method:: on_event(event: jeevesagent.core.types.Event) -> None
      :async:



   .. py:method:: post_tool(call: jeevesagent.core.types.ToolCall, result: jeevesagent.core.types.ToolResult, *, user_id: str | None = None) -> None
      :async:


      Best-effort post-tool callbacks. Failures and timeouts are
      absorbed so they cannot affect the result the loop returns.
      ``user_id`` follows the same forwarded-but-not-required
      pattern as :meth:`pre_tool`.



   .. py:method:: pre_tool(call: jeevesagent.core.types.ToolCall, *, user_id: str | None = None) -> jeevesagent.core.types.PermissionDecision
      :async:


      Run all pre-tool hooks. First deny wins; otherwise allow.

      The ``user_id`` kwarg is forwarded for protocol parity (M9);
      the bundled :class:`HookRegistry` doesn't itself dispatch
      per-user, but custom :class:`HookHost` implementations can
      route on it. Individual hook callables continue to receive
      only ``(call,)`` to keep the existing decorator API stable;
      hooks that need the user_id can call
      :func:`get_run_context` themselves.



   .. py:method:: register_event(hook: EventHook) -> EventHook


   .. py:method:: register_post_tool(hook: PostToolHook) -> PostToolHook


   .. py:method:: register_pre_tool(hook: PreToolHook) -> PreToolHook


   .. py:attribute:: event_hooks
      :type:  list[EventHook]
      :value: []



   .. py:attribute:: hook_timeout_s
      :type:  float
      :value: 5.0



   .. py:attribute:: post_tool_hooks
      :type:  list[PostToolHook]
      :value: []



   .. py:attribute:: pre_tool_hooks
      :type:  list[PreToolHook]
      :value: []



.. py:data:: EventHook

.. py:data:: PostToolHook

.. py:data:: PreToolHook

