Hook point enum and callback types for engine lifecycle hooks. More...
#include <stddef.h>
Go to the source code of this file.
Typedefs | |
| typedef int(* | entropic_hook_callback_t) (entropic_hook_point_t hook_point, const char *context_json, char **modified_json, void *user_data) |
| Hook callback function type. | |
Detailed Description
Hook point enum and callback types for engine lifecycle hooks.
Consumers register callbacks at hook points to intercept, modify, inspect, and transform engine behavior without forking. Pre-hooks can modify context or cancel operations. Post-hooks can transform results. Failing hooks are logged and skipped — never crash the engine.
- Version
- 2.0.6-rc16
Definition in file hooks.h.
Typedef Documentation
◆ entropic_hook_callback_t
| typedef int(* entropic_hook_callback_t) (entropic_hook_point_t hook_point, const char *context_json, char **modified_json, void *user_data) |
Hook callback function type.
Pre-hook semantics:
- Return 0 + *modified_json == NULL: proceed unchanged
- Return 0 + *modified_json != NULL: proceed with modified context
- Return non-zero: cancel the operation
Post-hook semantics:
- Return value ignored (post-hooks cannot cancel)
- *modified_json != NULL: transform the result
- *modified_json == NULL: no transformation
For POST_TOOL_CALL specifically (since v2.1.1, issue #2): the engine treats *modified_json as the replacement string for the tool result's Message::content — NOT as a JSON context object to be deconstructed. Mirrors POST_GENERATE's "raw text in / raw text out" semantic. Hook authors wanting to inspect the structured pre-hook context (tool_name, args, raw result, directives, result_kind) read those from the input context_json; the output is just the replacement content. When multiple POST_TOOL_CALL hooks are registered, last-write-wins per registry semantics — each hook receives the same context_json; the final *modified_json (whichever hook wrote it last) is what the engine applies. Pre-2.1.1 the engine called free() on *modified_json without applying the transform — silently breaking redaction/enrichment/normalization hooks.
For PRE_TOOL_CALL specifically (since v2.13.0, gh#168): a proceed (return 0) that writes *modified_json rewrites the ARGUMENTS of the call about to be dispatched. The payload is an OBJECT of the same shape the hook received, and only args is read:
args REPLACES the call's arguments wholesale — a hook that means to add one field echoes back the others it read from context_json. The engine refuses, loudly and in full, any payload that is not valid JSON, is not an object, carries no args object, or names a different tool: a hook may enrich a call, never re-route it past per-tier allowed_tools. A refusal logs at ERROR with the reason and the verbatim payload and dispatches the call with the model's own arguments; it does NOT cancel, because cancellation has exactly one channel (a non-zero return). Bytes crossing in are sanitized to valid UTF-8 before parsing. Pre-2.13.0 the engine called free() on *modified_json without applying it, so no PRE_TOOL_CALL hook could ever change a call — the defect that closed gh#168.
The engine frees *modified_json after consuming it. The callback MUST allocate it with entropic_alloc() (not malloc, not new, not stack).
- Parameters
-
hook_point Which hook point fired. context_json JSON string with hook-specific context data. Owned by the engine, valid only for this call. modified_json Output: replacement JSON, or NULL for no change. Allocated by callback with entropic_alloc(), freed by engine. user_data Opaque pointer from registration.
- Returns
- 0 to continue, non-zero to cancel (pre-hooks only).
@callback
- Version
- 2.1.1
Enumeration Type Documentation
◆ entropic_hook_point_t
Hook points in the engine lifecycle.
Each value identifies a stage where registered callbacks are invoked. Pre-hooks can cancel the operation by returning non-zero. Post-hooks can transform results via the modified_json out-param. Informational hooks fire for observation only.
New values are appended only — no renumbering (ABI stable).
The trailing ENTROPIC_HOOK_COUNT_ sentinel is NOT a valid hook point: it bounds registry validation and pins the declared cardinality.
@req REQ-TYPE-002 @req REQ-TYPE-004
- Version
- 2.0.6-rc16
