calute.extensions.hooks

calute.extensions.hooks#

Hook system for Calute lifecycle events.

Hooks allow external code to observe and mutate agent execution at well-defined points. Each hook point has documented semantics:

Hook Points:
  • before_tool_call(tool_name, arguments, agent_id) -> arguments

    Called before a tool is executed. Can modify arguments. Return modified arguments dict or None to keep original.

  • after_tool_call(tool_name, arguments, result, agent_id) -> result

    Called after a tool executes. Can transform the result. Return modified result or None to keep original.

  • tool_result_persist(tool_name, result, agent_id) -> result

    Called before tool result is stored in conversation history. Allows sanitizing/transforming results for persistence.

  • bootstrap_files(agent_id) -> list[str]

    Called during prompt assembly. Returns extra content strings to inject into the system prompt.

  • on_turn_start(agent_id, messages)

    Called when a new agent turn begins.

  • on_turn_end(agent_id, response)

    Called when an agent turn completes.

  • on_error(agent_id, error)

    Called when an error occurs during execution.

Execution semantics:

  • Hooks run in registration order.

  • A hook that raises is logged and skipped (does not break the chain).

  • Mutation hooks (before_tool_call, after_tool_call, tool_result_persist) pass their return value to the next hook in the chain.

class calute.extensions.hooks.HookRunner[source]#

Bases: object

Manages registration and execution of lifecycle hooks.

HookRunner maintains an ordered list of callback functions for each defined hook point. Hooks are divided into two categories:

  • Mutation hooks (before_tool_call, after_tool_call, tool_result_persist) – callbacks are chained so each can modify a value that is passed to the next callback.

  • Observation hooks (bootstrap_files, on_turn_start, on_turn_end, on_error) – all callbacks are invoked and their non-None return values are collected into a list.

Callbacks that raise exceptions are logged and skipped without breaking the hook chain.

_hooks#

Internal mapping from hook point names to ordered lists of registered callbacks.

Example

>>> runner = HookRunner()
>>> runner.register("before_tool_call", my_hook_fn)
>>> modified_args = runner.run("before_tool_call",
...     tool_name="search", arguments={"q": "hello"}, agent_id="a1")
clear(hook_point: str | None = None) → None[source]#

Clear all registered callbacks for one or all hook points.

Parameters

hook_point – If provided, only callbacks for this specific hook point are removed. If None (the default), callbacks for every hook point are removed.

has_hooks(hook_point: str) → bool[source]#

Check whether any callbacks are registered for a hook point.

Parameters

hook_point – The hook point name to query.

Returns

True if at least one callback is registered, False otherwise (including when hook_point is not a recognized name).

register(hook_point: str, callback: Callable[[...], Any]) → None[source]#

Register a hook callback for a specific hook point.

Parameters

  • hook_point – One of the defined HOOK_POINTS.

  • callback – The callable to invoke at this hook point.

Raises

ValueError – If hook_point is not recognized.

run(hook_point: str, **kwargs) → Any[source]#

Execute all hooks registered for a hook point.

Dispatches to _run_mutation() or _run_observation() depending on the hook category.

For mutation hooks (before_tool_call, after_tool_call, tool_result_persist):

  • The return value from each hook is passed as updated kwargs to the next hook in the chain.

  • For before_tool_call: the return value replaces 'arguments'.

  • For after_tool_call / tool_result_persist: the return value replaces 'result'.

  • Returns the final mutated value.

For observation hooks (bootstrap_files, on_turn_start, etc.):

  • All callbacks are invoked; return values are collected.

  • Returns a list of non-None return values.

If no callbacks are registered the method returns the relevant default value (arguments or result from kwargs).

Parameters

  • hook_point – The hook point name to execute.

  • **kwargs – Keyword arguments forwarded to every callback. The exact keys depend on the hook point (see module docstring).

Returns

The final mutated value for mutation hooks, or a list of collected results for observation hooks.

unregister(hook_point: str, callback: Callable[[...], Any]) → bool[source]#

Remove a previously registered callback from a hook point.

Parameters

  • hook_point – The hook point name to search in.

  • callback – The exact callable instance to remove (identity match).

Returns

True if the callback was found and removed, False if the hook point does not exist or the callback was not registered.

Contents