feat: implement command hook system (#32) (#41)

* feat: implement command hook system (#32)

Add extensibility hook system matching Claude Code's design. Hooks let
users run shell commands at tool lifecycle points (PreToolUse, PostToolUse,
PostToolUseFailure) to enforce policies, audit actions, or modify inputs.

- 3 core abstractions: HookEvent (sealed), HookResult (sealed), HookExecutor
- HookConfig/HookMatcher/HookRegistry for config-driven hook resolution
- CommandHookExecutor: ProcessBuilder with JSON stdin/stdout, exit code
  semantics (0=proceed, 2=block, other=non-blocking error), timeout
- PreToolUse hooks run before permission check; can block or modify input
- PostToolUse/PostToolUseFailure hooks fire async on virtual threads
- Config loaded from ~/.aceclaw/config.json and project config (appending)
- 24 new tests across 3 test classes (unit + E2E integration)

* fix: read stdout/stderr concurrently to prevent pipe deadlock on Linux

Process pipe buffers are finite (~64KB on Linux). If the hook command
writes more than the buffer capacity before we start reading, it blocks
on write while we block on waitFor() — a classic deadlock. Fix by
draining stdout and stderr on virtual threads concurrently with waitFor.

* fix: start stdout/stderr readers before stdin write to prevent data loss

On fast CI runners, the hook process may exit before stdin write completes.
If the process doesn't read stdin, the write throws broken pipe IOException
which previously aborted the entire executeOne() method — stdout/stderr
reader threads were never started, so the hook's output was lost.

Fix: start reader threads FIRST, then write stdin with a separate
try-catch so broken pipe is non-fatal. This ensures we always capture
the process output regardless of stdin write success.

* refactor: address CodeRabbit review feedback on PR #41

- Convert HookMatcherFormat/HookConfigFormat from mutable classes to records
- Use session's projectPath for hook cwd instead of daemon's workingDir
- Replace Thread.sleep with bounded polling in HookIntegrationTest
- Add clarifying comment on exit-0 deny test contract

* fix: guard against null in hook merge and PostToolUseFailure

- AceClawConfig: skip null/empty hook lists during config merge to prevent NPE
- StreamingAgentHandler: ensure non-null error string for PostToolUseFailure
  so firePostHookAsync dispatches the correct event type

---------

Co-authored-by: Xinhua Gu <xinhua.gu@arz.at>

Author: xinhuagu

aceclaw-core/src/main/java/dev/aceclaw/core/agent/HookEvent.java

@@ -0,0 +1,65 @@
+package dev.aceclaw.core.agent;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+/**
+ * Events that trigger hook execution at different points in the tool lifecycle.
+ *
+ * <p>Three event types correspond to Claude Code's hook events:
+ * <ul>
+ *   <li>{@link PreToolUse} — fired before tool execution (blocking; can modify input or block)</li>
+ *   <li>{@link PostToolUse} — fired after successful tool execution (non-blocking)</li>
+ *   <li>{@link PostToolUseFailure} — fired after failed tool execution (non-blocking)</li>
+ * </ul>
+ */
+public sealed interface HookEvent {
+
+    /** The session ID of the current agent session. */
+    String sessionId();
+
+    /** The current working directory. */
+    String cwd();
+
+    /** The name of the tool being invoked. */
+    String toolName();
+
+    /** The tool input as a JSON object. */
+    JsonNode toolInput();
+
+    /**
+     * The event type name used in config matching and JSON serialization
+     * (e.g. "PreToolUse", "PostToolUse", "PostToolUseFailure").
+     */
+    String eventName();
+
+    /**
+     * Fired before a tool is executed. The hook can block execution or modify the input.
+     */
+    record PreToolUse(String sessionId, String cwd, String toolName, JsonNode toolInput)
+            implements HookEvent {
+        @Override
+        public String eventName() { return "PreToolUse"; }
+    }
+
+    /**
+     * Fired after a tool executes successfully. Non-blocking — hooks run but cannot alter the result.
+     *
+     * @param toolOutput the textual output of the tool execution
+     */
+    record PostToolUse(String sessionId, String cwd, String toolName, JsonNode toolInput,
+                       String toolOutput) implements HookEvent {
+        @Override
+        public String eventName() { return "PostToolUse"; }
+    }
+
+    /**
+     * Fired after a tool execution fails. Non-blocking — hooks run for auditing/logging.
+     *
+     * @param error the error message from the failed execution
+     */
+    record PostToolUseFailure(String sessionId, String cwd, String toolName, JsonNode toolInput,
+                              String error) implements HookEvent {
+        @Override
+        public String eventName() { return "PostToolUseFailure"; }
+    }
+}

aceclaw-core/src/main/java/dev/aceclaw/core/agent/HookExecutor.java

@@ -0,0 +1,21 @@
+package dev.aceclaw.core.agent;
+
+/**
+ * Executes hooks for a given hook event.
+ *
+ * <p>Implementations run one or more hook commands (shell scripts, binaries, etc.)
+ * and return the aggregate result. For {@link HookEvent.PreToolUse} events,
+ * the first {@link HookResult.Block} stops further hook execution.
+ * For post-execution events, all hooks always run.
+ */
+@FunctionalInterface
+public interface HookExecutor {
+
+    /**
+     * Executes all matching hooks for the given event.
+     *
+     * @param event the hook event describing the tool invocation context
+     * @return the result of hook execution
+     */
+    HookResult execute(HookEvent event);
+}

aceclaw-core/src/main/java/dev/aceclaw/core/agent/HookResult.java

@@ -0,0 +1,44 @@
+package dev.aceclaw.core.agent;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+/**
+ * Result of a hook execution, determining whether tool execution should proceed.
+ *
+ * <p>Exit code semantics (matching Claude Code):
+ * <ul>
+ *   <li>0 → {@link Proceed} — allow execution, optionally with modified input</li>
+ *   <li>2 → {@link Block} — block execution with a reason</li>
+ *   <li>other → {@link Error} — non-blocking error, log and continue</li>
+ * </ul>
+ */
+public sealed interface HookResult {
+
+    /**
+     * Hook permits execution to proceed.
+     *
+     * @param stdout       raw stdout from the hook process
+     * @param updatedInput optional modified tool input (null = no modification)
+     * @param additionalContext optional context string to append to tool description
+     */
+    record Proceed(String stdout, JsonNode updatedInput, String additionalContext) implements HookResult {
+        /** Convenience constructor for a simple proceed with no modifications. */
+        public Proceed() { this(null, null, null); }
+    }
+
+    /**
+     * Hook blocks execution.
+     *
+     * @param reason human-readable reason for blocking
+     */
+    record Block(String reason) implements HookResult {}
+
+    /**
+     * Hook encountered a non-blocking error (exit code != 0 and != 2).
+     * Execution should continue; the error is logged.
+     *
+     * @param exitCode the process exit code
+     * @param message  stderr or error description
+     */
+    record Error(int exitCode, String message) implements HookResult {}
+}

aceclaw-daemon/src/main/java/dev/aceclaw/daemon/AceClawConfig.java

@@ -8,6 +8,9 @@
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 
 /**
@@ -62,6 +65,7 @@ public final class AceClawConfig {
     private String defaultProfile;
     private Map<String, ConfigFileFormat> profiles;
     private Map<String, String> providerModels;
+    private Map<String, List<HookMatcherFormat>> hooks;
 
     private AceClawConfig() {
         this.provider = "anthropic";
@@ -260,6 +264,14 @@ public String permissionMode() {
         return permissionMode;
     }
 
+    /**
+     * Returns the hooks configuration map (event name to list of hook matchers).
+     * Returns null if no hooks are configured.
+     */
+    public Map<String, List<HookMatcherFormat>> hooks() {
+        return hooks;
+    }
+
     /**
      * Returns whether an API key is configured.
      */
@@ -364,6 +376,21 @@ private void mergeFromFile(Path configFile) {
                 this.providerModels.putAll(fileConfig.providerModels);
             }
 
+            // Hooks: project config appends to global config per event type
+            if (fileConfig.hooks != null && !fileConfig.hooks.isEmpty()) {
+                if (this.hooks == null) {
+                    this.hooks = new HashMap<>();
+                }
+                for (var hookEntry : fileConfig.hooks.entrySet()) {
+                    var hooksForEvent = hookEntry.getValue();
+                    if (hooksForEvent == null || hooksForEvent.isEmpty()) {
+                        continue;
+                    }
+                    this.hooks.computeIfAbsent(hookEntry.getKey(), _ -> new ArrayList<>())
+                            .addAll(hooksForEvent);
+                }
+            }
+
             log.debug("Loaded config from {}", configFile);
         } catch (IOException e) {
             log.warn("Failed to read config file {}: {}", configFile, e.getMessage());
@@ -425,5 +452,20 @@ static final class ConfigFileFormat {
         public String defaultProfile;
         public Map<String, ConfigFileFormat> profiles;
         public Map<String, String> providerModels;
+        public Map<String, List<HookMatcherFormat>> hooks;
     }
+
+    /**
+     * JSON structure for a hook matcher entry in config.
+     * <pre>{ "matcher": "bash", "hooks": [{ "type": "command", "command": "...", "timeout": 30 }] }</pre>
+     */
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public record HookMatcherFormat(String matcher, List<HookConfigFormat> hooks) {}
+
+    /**
+     * JSON structure for a single hook config entry.
+     * <pre>{ "type": "command", "command": "echo ok", "timeout": 60 }</pre>
+     */
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public record HookConfigFormat(String type, String command, int timeout) {}
 }

aceclaw-daemon/src/main/java/dev/aceclaw/daemon/AceClawDaemon.java

@@ -306,7 +306,19 @@ private void wireAgentHandler(Path workingDir) {
             agentHandler.setDailyJournal(journal);
         }
 
-        // 9. Self-improvement engine (post-turn learning analysis + strategy refinement)
+        // 9. Hook system (command hooks at tool lifecycle points)
+        var hookRegistry = HookRegistry.load(config.hooks());
+        if (!hookRegistry.isEmpty()) {
+            var hookExecutor = new CommandHookExecutor(hookRegistry, objectMapper, workingDir);
+            agentHandler.setHookExecutor(hookExecutor);
+            log.info("Hook system wired: {} matchers across {} event types",
+                    hookRegistry.size(),
+                    (hookRegistry.hasHooksFor("PreToolUse") ? 1 : 0) +
+                    (hookRegistry.hasHooksFor("PostToolUse") ? 1 : 0) +
+                    (hookRegistry.hasHooksFor("PostToolUseFailure") ? 1 : 0));
+        }
+
+        // 10. Self-improvement engine (post-turn learning analysis + strategy refinement)
         if (memoryStore != null) {
             var errorDetector = new ErrorDetector(memoryStore);
             var patternDetector = new PatternDetector(memoryStore);