Hook

Hook interface for monitoring and intercepting agent execution.

All agent execution events are delivered through a single #onEvent(HookEvent) method. This unified event model provides a clean, type-safe way to intercept and modify agent behavior.

Hook Priority: Hooks are executed in priority order (lower value = higher priority). Default priority is 100. Hooks with the same priority execute in registration order.

Event Modifiability: Whether an event is modifiable is indicated by the presence of setter methods:

• Events with setters (e.g., PreReasoningEvent#setInputMessages) allow modification

• Events without setters are notification-only

Example Usage:

`// Basic hook with default priority
Hook loggingHook = new Hook() {
@Override
public <T extends HookEvent> Mono<T> onEvent(T event) {
return switch (event) {
case PreReasoningEvent e -> {
System.out.println("Reasoning with model: " + e.getModelName());
yield Mono.just(e);
}
case ReasoningChunkEvent e -> {
// Display streaming output
System.out.print(extractText(e.getIncrementalChunk()));
yield Mono.just(e);
}
default -> Mono.just(event);
};
}
};

// High priority hook (executes first)
Hook authHook = new Hook() {
@Override
public int priority() {
return 10; // High priority
}

@Override
public <T extends HookEvent> Mono<T> onEvent(T event) {
return switch (event) {
case PreActingEvent e -> {
// Inject auth token before any other hook
ToolUseBlock toolUse = e.getToolUse();
// ... add auth
e.setToolUse(toolUse);
yield Mono.just(e);
}
default -> Mono.just(event);
};
}
};

// Modifying events
Hook hintInjector = new Hook() {
@Override
public <T extends HookEvent> Mono<T> onEvent(T event) {
return switch (event) {
case PreReasoningEvent e -> {
// Modify messages before LLM reasoning
List<Msg> msgs = new ArrayList<>(e.getInputMessages());
msgs.add(0, Msg.builder()
.role(MsgRole.SYSTEM)
.content(new TextBlock("Think step by step"))
.build());
e.setInputMessages(msgs);
yield Mono.just(e);
}
case PostActingEvent e -> {
// Modify tool result
ToolResultBlock result = e.getToolResult();
// ... process result
e.setToolResult(result);
yield Mono.just(e);
}
default -> Mono.just(event);
};
}
};
`