Agent Hooks

What’s New → Current release: 0.8.2. 0.7.0: Built on Spring AI 2.0.0, Spring Boot 4.0.7, and Claude Agent SDK 1.5.0. This release keeps the core-plus-adapters architecture and public dispatch API while correcting standalone dependency resolution, packaging, diagnostics, and Java compatibility claims. Every agent framework implements hooks differently. Claude Code has shell-based hooks. Strands has steering callbacks. Spring AI has advisors. Your safety policy, logging, and steering logic gets rewritten for each one. Agent Hooks is a portable Java API that lets you write hook logic once and run it on any runtime that has an adapter. The core module has no framework dependency — it defines the event model, decision types, and registry, with org.jspecify annotations as its only compile dependency. Adapters (Spring AI, Claude Agent SDK, and Gemini CLI) wire the core into their runtime’s tool-call lifecycle. Your hooks move with you when your agent infrastructure changes.

Why Hooks

LLMs are probabilistic — prompt-based instructions drift under token pressure. Agents skip steps, forget constraints, and ignore guardrails. Hooks solve this by moving critical logic out of the prompt and into deterministic code that intercepts every tool call, the same way servlet filters intercept HTTP requests:

Safety — Block dangerous operations before they execute. A Block decision short-circuits immediately and cannot be overridden by later hooks.
Observability — Log every tool call, capture timing data, and feed traces into Agent Journal for behavioral analysis.
Steering — Modify tool inputs in flight. Subsequent hooks see the modified input, so transformations chain cleanly.

How It Works

Hooks intercept at two points in the tool-call lifecycle:

BeforeToolCall ──► Tool Executes ──► AfterToolCall
     │                                    │
  Block?  ◄── short-circuit            Retry?
  Modify? ◄── chains                   Log / observe
  Proceed ◄── default                  Cleanup (reverse order)

// Block all shell commands
registry.onTool("shell.*", BeforeToolCall.class, event ->
    HookDecision.block("Shell access disabled in this environment"));

// Log every tool call
registry.on(AfterToolCall.class, event -> {
    log.info("{} completed in {}ms", event.toolName(), event.duration().toMillis());
    return HookDecision.proceed();
});

// Redirect file writes to a sandbox directory
registry.onTool("write.*", BeforeToolCall.class, event -> {
    String sandboxed = event.toolInput()
        .replace("/home/user", "/sandbox");
    return HookDecision.modify(sandboxed);
});

Decision Model

HookDecision is a sealed type with four variants:

Decision	When	Behavior
`Proceed`	Default	Tool executes normally
`Block`	Safety / policy	Short-circuits immediately — later hooks never run
`Modify`	Input transformation	Passes modified input to the next hook in the chain
`Retry`	AfterToolCall only	Advisory. Returned to the caller; no shipped adapter re-executes the tool

Multiple hooks execute in priority order (default: 100, lower = earlier). AfterToolCall hooks fire in reverse priority order for proper cleanup semantics. Two behaviors are worth knowing before you rely on them. Dispatch matches an event’s exact runtime class, so a hook registered against a supertype such as ToolEvent.class compiles but never fires — register against the concrete record. And a hook that throws is logged at WARNING and treated as Proceed: Block short-circuits, but a failing hook does not fail closed.

Modules

Module	What it does	Dependencies	Java
`agent-hooks-core`	Portable API — events, decisions, registry	No framework dependency; `org.jspecify` annotations only	17
`agent-hooks-spring`	Spring AI adapter — wraps `ToolCallback` with hook dispatch, auto-configures via Boot	Spring AI, Spring Boot	17
`agent-hooks-gemini`	Gemini CLI adapter — stateless stdin/stdout dispatcher for Gemini’s subprocess-per-event model	Jackson (compile)	17
`agent-hooks-claude`	Claude Agent SDK adapter — bridges hook providers to Claude CLI hooks via `AgentHookBridge`	Claude Agent SDK (provided)	21

agent-hooks-claude requires Java 21 because every published claude-code-sdk version is Java 21 bytecode. The other three modules are unaffected on Java 17.

Event Hierarchy

The event system is open (unsealed) — you can define custom events for your runtime:

Event	Interface	Decisions
`BeforeToolCall`	`ToolEvent`	Proceed, Block, Modify
`AfterToolCall`	`ToolEvent`	Proceed, Retry
`SessionStart`	`HookEvent`	Observation only
`SessionEnd`	`HookEvent`	Observation only
`UserPromptSubmit`	`HookEvent`	Observation only (Claude adapter)
`AgentStop`	`HookEvent`	Observation only (Claude adapter)
`SubagentStop`	`HookEvent`	Observation only (Claude adapter)
`PreCompact`	`HookEvent`	Observation only (Claude adapter)
`GeminiBeforeAgent`	`HookEvent`	Observation only (Gemini adapter)
`GeminiAfterAgent`	`HookEvent`	Observation only (Gemini adapter)
`GeminiBeforeModel`	`HookEvent`	Observation only (Gemini adapter)
`GeminiAfterModel`	`HookEvent`	Observation only (Gemini adapter)
`GeminiBeforeToolSelection`	`HookEvent`	Observation only (Gemini adapter)
`GeminiNotification`	`HookEvent`	Observation only (Gemini adapter)
`GeminiPreCompress`	`HookEvent`	Observation only (Gemini adapter)

Quick Start

<!-- Core API (no framework dependency) -->
<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>agent-hooks-core</artifactId>
    <version>0.8.2</version>
</dependency>

<!-- Spring AI adapter (auto-configured) -->
<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>agent-hooks-spring</artifactId>
    <version>0.8.2</version>
</dependency>

<!-- Claude Agent SDK adapter -->
<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>agent-hooks-claude</artifactId>
    <version>0.8.2</version>
</dependency>

<!-- Gemini CLI adapter (stateless subprocess) -->
<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>agent-hooks-gemini</artifactId>
    <version>0.8.2</version>
</dependency>

Write Once, Run Anywhere

The same AgentHookProvider works on all three runtimes — this is the core value proposition.

// This provider works on Spring AI, Claude CLI, and Gemini CLI
public class SecurityHooks implements AgentHookProvider {
    @Override
    public void registerHooks(AgentHookRegistry registry) {
        registry.onTool("Bash", BeforeToolCall.class, event ->
            HookDecision.block("Shell access not permitted"));
    }
}

Spring AI — register as a @Component bean, auto-configuration handles the rest:

@Component
public class MySecurityHooks extends SecurityHooks {}

The auto-configured HookContext is an application-wide singleton: every hooked tool call in the application shares one state map and one tool-call history. That suits a single-user CLI or desktop app. A multi-user server should define its own request- or session-scoped HookContext bean, or build one per conversation and call HookedTools.wrap at that point. Claude Agent SDK — bridge into the Claude HookRegistry:

AgentHookRegistry registry = new AgentHookRegistry();
registry.register(new SecurityHooks());

AgentHookBridge bridge = new AgentHookBridge(registry);
bridge.registerInto(claudeHookRegistry);

The bridge registers callbacks for all six Claude hook events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, PreCompact). It converts Claude SDK types to core events, dispatches through your hooks, and maps decisions back to Claude’s HookOutput. Tool call duration is tracked via wall-clock timing across the pre/post hook boundary. Each Claude session gets its own HookContext for isolated state and history. The bridge retains those contexts for its own lifetime — fine for one bridge per CLI process; a long-lived bridge shared across sessions should call evictSession(sessionId) when a session finishes. Gemini CLI — stateless subprocess dispatcher reads JSON from stdin:

public class MyGeminiHooks {
    public static void main(String[] args) throws Exception {
        GeminiHookDispatcher.create(new SecurityHooks())
            .run();  // reads stdin, dispatches, writes stdout, exits
    }
}

Gemini CLI spawns the hook process per event. The dispatcher maps all 11 Gemini events to core and Gemini-specific HookEvent records. HookContext is fresh per invocation — stateless hooks (security gates, audit logging) work out of the box. Note: Gemini BeforeTool can only allow or block — Modify is downgraded to allow with a warning.

Documentation

Source Code

Core API, Spring AI adapter, Claude adapter, and Gemini adapter

Design Notes

Architecture decisions, event hierarchy, dispatch semantics

Suite integration

Agent Hooks is managed by the AgentWorks BOM, but it is standalone today: no other published AgentWorks module depends on it. Bridges to Agent Journal (a hook provider that logs tool-call events to a journal Run) and to workflow steps are intended directions, not shipped code.

Projects

AgentWorks

Supporting Projects

Migration

Why Hooks

How It Works

Decision Model

Modules

Event Hierarchy

Quick Start

Write Once, Run Anywhere

Documentation

Source Code

Design Notes

Suite integration

​Why Hooks

​How It Works

​Decision Model

​Modules

​Event Hierarchy

​Quick Start

​Write Once, Run Anywhere

​Documentation

Source Code

Design Notes

​Suite integration

Why Hooks

How It Works

Decision Model

Modules

Event Hierarchy

Quick Start

Write Once, Run Anywhere

Documentation

Suite integration