HookEvent

Base class for all hook events.

This is a sealed class - only the predefined event types are permitted. This enables exhaustive pattern matching in switch expressions.

All events provide access to common context:

• #getAgent() - The agent instance

• #getMemory() - Convenient access to agent's memory (may be null)

• #getType() - The event type

• #getTimestamp() - When the event occurred

System message lifecycle: Every event carries a unified systemMsg field that holds the single MsgRole#SYSTEM message visible to the LLM. ReActAgent manages this field across the event lifecycle as follows:

• Seeded from sysPrompt at the start of each call() before PreCallEvent hooks run.

• After PreCallEvent hooks complete, the resulting system message is frozen as the base for the entire call.

• Before each PreReasoningEvent (and PreSummaryEvent), the frozen base is injected fresh into the event — hooks that run on these events always start from the same clean baseline and may append per-iteration content.

• Before model.stream(...) is called: the event's final system message is prepended to PreReasoningEvent#getInputMessages() as the first element.

Because each PreReasoningEvent starts from a fresh copy of the frozen base, hooks that fire per-iteration (e.g. subagent guidance) can safely use #appendSystemContent(String) — content is added to that iteration's copy and never accumulates across iterations.

Hooks should modify the system message exclusively via #setSystemMessage(Msg), #appendSystemContent(String), or #appendSystemContent(ContentBlock). Injecting MsgRole#SYSTEM messages into inputMessages directly is forbidden and results in an IllegalStateException at runtime.

Modifiability: Whether an event allows modification is determined by the presence of setter methods in the concrete event class.