Agent Hooks

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);
});

<!-- Core API (zero dependencies) -->
<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>agent-hooks-core</artifactId>
    <version>0.6.2</version>
</dependency>

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

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

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

// 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"));
    }
}

@Component
public class MySecurityHooks extends SecurityHooks {}

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

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

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