feat: implement advanced lifecycle hooks

Key changes:
- New Hook Types: `sessionStart`, `sessionEnd`, `chatStart`, `chatEnd` for better lifecycle management.
- Enhanced `preRequest`: Supports prompt rewriting, context injection, and request blocking.
- Enhanced `preToolCall`: Allows argument modification, approval overrides (allow/ask/deny), and tool blocking via exit codes or JSON.
- New `postToolCall`: Provides access to tool responses and errors, allowing for post-execution context injection.
- JSON Protocol: Hooks now communicate via structured JSON on stdin/stdout for robust data exchange.
- Integration: Updates chat loop and tool state machine to respect hook decisions.

Author: zikajk

integration-test/entrypoint.clj

@@ -3,10 +3,12 @@
    [babashka.process :refer [shell]]
    [clojure.test :as t]
    [integration.eca :as eca]
+   [integration.chat.hooks-test]
    [llm-mock.server :as llm-mock.server]))
 
 (def namespaces
   '[integration.initialize-test
+    integration.chat.hooks-test
     integration.chat.openai-test
     integration.chat.anthropic-test
     integration.chat.github-copilot-test

integration-test/integration/chat/hooks_test.clj

@@ -1,76 +1,177 @@
 (ns eca.features.hooks
   (:require
+   [babashka.fs :as fs]
    [babashka.process :as p]
    [cheshire.core :as json]
    [eca.logger :as logger]
-   [eca.shared :as shared]))
+   [eca.shared :as shared]
+   [eca.features.tools.shell :as f.tools.shell]))
 
 (def ^:private logger-tag "[HOOK]")
 
-(defn ^:private hook-matches? [type data hook]
+(def ^:const hook-rejection-exit-code 2)
+
+(def ^:const default-hook-timeout-ms 30000)
+
+(defn base-hook-data
+  "Returns common fields for ALL hooks (session and chat hooks).
+   These fields are present in every hook type."
+  [db]
+  {:workspaces (shared/get-workspaces db)
+   :db-cache-path (shared/db-cache-path db)})
+
+(defn chat-hook-data
+  "Returns common fields for CHAT-RELATED hooks.
+   Includes base fields plus chat-specific fields (chat-id, behavior).
+   Use this for: preRequest, postRequest, preToolCall, postToolCall, chatStart, chatEnd."
+  [db chat-id behavior]
+  (merge (base-hook-data db)
+         {:chat-id chat-id
+          :behavior behavior}))
+
+(defn ^:private parse-hook-json
+  "Attempts to parse hook output as JSON. Returns parsed map if successful, nil otherwise."
+  [output]
+  (when (and output (not-empty output))
+    (try
+      (let [parsed (json/parse-string output true)]
+        (if (map? parsed)
+          parsed
+          (logger/debug logger-tag "Hook JSON output must result in map")))
+      (catch Exception e
+        (logger/debug logger-tag "Hook output is not valid JSON, treating as plain text"
+                      {:output output :error (.getMessage e)})
+        nil))))
+
+(defn run-shell-cmd [opts]
+  (try
+    (let [timeout-ms (or (:timeout opts) default-hook-timeout-ms)
+          proc (f.tools.shell/start-shell-process! opts)
+          result (deref proc timeout-ms ::timeout)]
+      (if (= result ::timeout)
+        (do
+          (logger/warn logger-tag "Hook timed out" {:timeout-ms timeout-ms})
+          (p/destroy-tree proc)
+          {:exit 1 :out nil :err (format "Hook timed out after %d seconds" (/ timeout-ms 1000))})
+        {:exit (:exit result)
+         :out (:out result)
+         :err (:err result)}))
+    (catch Exception e
+      (let [msg (or (.getMessage e) "Caught an Exception during execution of hook")]
+        (logger/warn logger-tag "Got an Exception during execution" {:message msg})
+        {:exit 1 :err msg}))))
+
+(defn ^:private should-skip-on-error?
+  "Check if postToolCall hook should be skipped when tool errors.
+  By default, postToolCall hooks only run on success unless runOnError is true."
+  [type hook data]
+  (and (= type :postToolCall)
+       (not (get hook :runOnError false))
+       (:error data)))
+
+(defn ^:private hook-matches? [hook-type data hook]
   (let [hook-config-type (keyword (:type hook))
         hook-config-type (cond ;; legacy values
                            (= :prePrompt hook-config-type) :preRequest
                            (= :postPrompt hook-config-type) :postRequest
                            :else hook-config-type)]
     (cond
-      (not= type hook-config-type)
+      (not= hook-type hook-config-type)
       false
 
-      (contains? #{:preToolCall :postToolCall} type)
+      (should-skip-on-error? hook-type hook data)
+      false
+
+      (contains? #{:preToolCall :postToolCall} hook-type)
       (re-matches (re-pattern (or (:matcher hook) ".*"))
                   (str (:server data) "__" (:tool-name data)))
 
       :else
       true)))
 
-(defn ^:private run-hook-action! [action name data db]
+(defn ^:private run-and-parse-output!
+  "Run shell command and return parsed result map."
+  [opts]
+  (let [{:keys [exit out err]} (run-shell-cmd opts)
+        raw-output (not-empty out)
+        raw-error (not-empty err)]
+    {:exit exit
+     :raw-output raw-output
+     :raw-error raw-error
+     :parsed (parse-hook-json raw-output)}))
+
+(defn run-hook-action!
+  "Execute a single hook action. Supported hook types:
+   - :sessionStart, :sessionEnd (session lifecycle)
+   - :chatStart, :chatEnd (chat lifecycle)
+   - :preRequest, :postRequest (prompt lifecycle)
+   - :preToolCall, :postToolCall (tool lifecycle)
+
+   Returns map with :exit, :raw-output, :raw-error, :parsed"
+  [action name hook-type data db]
   (case (:type action)
     "shell" (let [cwd (some-> (:workspace-folders db)
                               first
                               :uri
                               shared/uri->filename)
                   shell (:shell action)
-                  input (json/generate-string (merge {:hook-name name} data))]
-              (logger/info logger-tag (format "Running hook '%s' shell '%s' with input '%s'" name shell input))
-              (let [{:keys [exit out err]} (p/sh {:dir cwd}
-                                                 "bash" "-c" shell "--" input)]
-                [exit (not-empty out) (not-empty err)]))
-    (logger/warn logger-tag (format "Unknown hook action %s for %s" (:type action) name))))
+                  file (:file action)
+                  ;; Convert to snake_case for bash/shell conventions
+                  ;; Nested keys (e.g. tool_input/tool_response): kebab-case (matches LLM format)
+                  input (json/generate-string (shared/map->snake-cased-map
+                                               (merge {:hook-name name :hook-type hook-type} data)))]
+              (cond
+                (and shell file)
+                (logger/error logger-tag (format "Hook '%s' has both 'shell' and 'file' - must have exactly one" name))
+
+                (and (not shell) (not file))
+                (logger/error logger-tag (format "Hook '%s' missing both 'shell' and 'file' - must have one" name))
+
+                (nil? cwd)
+                (logger/error logger-tag (format "Hook '%s' cannot run: no workspace folders configured" name))
+
+                shell
+                (do (logger/debug logger-tag (format "Running hook '%s' inline shell '%s' with input '%s'" name shell input))
+                    (run-and-parse-output! {:cwd cwd :input input :script shell :timeout (:timeout action)}))
+
+                file
+                (do (logger/debug logger-tag (format "Running hook '%s' file '%s' with input '%s'" name file input))
+                    (run-and-parse-output! {:cwd cwd :input input :file (str (fs/expand-home file)) :timeout (:timeout action)}))))
+
+    (logger/warn logger-tag (format "Unknown hook action type '%s' for %s" (:type action) name))))
 
 (defn trigger-if-matches!
   "Run hook of specified type if matches any config for that type"
-  [type
+  [hook-type
    data
    {:keys [on-before-action on-after-action]
     :or {on-before-action identity
          on-after-action identity}}
    db
    config]
-  (doseq [[name hook] (:hooks config)]
-    (when (hook-matches? type data hook)
+  ;; Sort hooks by name to ensure deterministic execution order.
+  (doseq [[name hook] (sort-by key (:hooks config))]
+    (when (hook-matches? hook-type data hook)
       (vec
        (map-indexed (fn [i action]
                       (let [id (str (random-uuid))
-                            type (:type action)
-                            name (if (> 1 (count (:actions hook)))
+                            action-type (:type action)
+                            name (if (> (count (:actions hook)) 1)
                                    (str name "-" (inc i))
                                    name)
                             visible? (get hook :visible true)]
                         (on-before-action {:id id
                                            :visible? visible?
                                            :name name})
-                        (if-let [[status output error] (run-hook-action! action name data db)]
-                          (on-after-action {:id id
-                                            :name name
-                                            :type type
-                                            :visible? visible?
-                                            :status status
-                                            :output output
-                                            :error error})
+                        (if-let [result (run-hook-action! action name hook-type data db)]
+                          (on-after-action (merge result
+                                                  {:id id
+                                                   :name name
+                                                   :type action-type
+                                                   :visible? visible?}))
                           (on-after-action {:id id
                                             :name name
                                             :visible? visible?
-                                            :type type
-                                            :status -1}))))
+                                            :type action-type
+                                            :exit 1}))))
                     (:actions hook))))))

src/eca/features/chat.clj

@@ -59,7 +59,7 @@
       :else
       (load-builtin-prompt "agent_behavior.md"))))
 
-(defn contexts-str [refined-contexts repo-map*]
+(defn contexts-str [refined-contexts repo-map* startup-ctx]
   (multi-str
    "<contexts description=\"User-Provided. This content is current and accurate. Treat this as sufficient context for answering the query.\">"
    ""
@@ -86,9 +86,12 @@
                          "")))
     ""
     refined-contexts)
+   ;; TODO - should be refined contexts?
+   (when startup-ctx
+     (str "\n<additionalContext from=\"chatStart\">\n" startup-ctx "\n</additionalContext>\n\n"))
    "</contexts>"))
 
-(defn build-chat-instructions [refined-contexts rules repo-map* behavior config db]
+(defn build-chat-instructions [refined-contexts rules repo-map* behavior config chat-id db]
   (multi-str
    (eca-chat-prompt behavior config)
    (when (seq rules)
@@ -105,7 +108,7 @@
    (when (seq refined-contexts)
      ["## Contexts"
       ""
-      (contexts-str refined-contexts repo-map*)])
+      (contexts-str refined-contexts repo-map* (get-in db [:chats chat-id :startup-context]))])
    ""
    (replace-vars
     (load-builtin-prompt "additional_system_info.md")

src/eca/features/hooks.clj

@@ -15,6 +15,40 @@
 (def ^:private default-timeout 60000)
 (def ^:private max-timeout (* 60000 10))
 
+(defn start-shell-process!
+  "Start a shell process, returning the process object for deref/management.
+
+   Options:
+   - :cwd      Working directory (required)
+   - :script   Inline script string (mutually exclusive with :file)
+   - :file     Script file path (mutually exclusive with :script)
+   - :input    String to pass as stdin (optional)
+
+   Returns: babashka.process process object (deref-able)"
+  [{:keys [cwd script file input]}]
+  {:pre [(some? cwd)
+         (or (some? script) (some? file))
+         (not (and script file))]}
+  (let [win? (string/starts-with? (System/getProperty "os.name") "Windows")
+        cmd (cond
+              (and win? file)
+              ["powershell.exe" "-ExecutionPolicy" "Bypass" "-File" file]
+
+              (and win? script)
+              ["powershell.exe" "-NoProfile" "-Command" script]
+
+              file
+              ["bash" file]
+
+              :else
+              ["bash" "-c" script])]
+    (p/process (cond-> {:cmd cmd
+                        :dir cwd
+                        :out :string
+                        :err :string
+                        :continue true}
+                 input (assoc :in input)))))
+
 (defn ^:private shell-command [arguments {:keys [db tool-call-id call-state-fn state-transition-fn]}]
   (let [command-args (get arguments "command")
         user-work-dir (get arguments "working_directory")
@@ -30,11 +64,8 @@
               _ (logger/debug logger-tag "Running command:" command-args)
               result (try
                        (if-let [proc (when-not (= :stopping (:status (call-state-fn)))
-                                       (p/process {:dir work-dir
-                                                   :out :string
-                                                   :err :string
-                                                   :timeout timeout
-                                                   :continue true} "bash -c" command-args))]
+                                       (start-shell-process! {:cwd work-dir
+                                                              :script command-args}))]
                          (do
                            (state-transition-fn :resources-created {:resources {:process proc}})
                            (try (deref proc

src/eca/features/prompt.clj

@@ -4,6 +4,7 @@
    [eca.db :as db]
    [eca.features.chat :as f.chat]
    [eca.features.completion :as f.completion]
+   [eca.features.hooks :as f.hooks]
    [eca.features.login :as f.login]
    [eca.features.rewrite :as f.rewrite]
    [eca.features.tools :as f.tools]
@@ -73,10 +74,27 @@
                                 error)}}))
     (config/listen-for-changes! db*))
   (future
-    (f.tools/init-servers! db* messenger config metrics)))
-
-(defn shutdown [{:keys [db* metrics]}]
+    (f.tools/init-servers! db* messenger config metrics))
+  ;; Trigger sessionStart hook after initialization
+  (f.hooks/trigger-if-matches! :sessionStart
+                               (f.hooks/base-hook-data @db*)
+                               {}
+                               @db*
+                               config))
+
+(defn shutdown [{:keys [db* config metrics]}]
   (metrics/task metrics :eca/shutdown
+    ;; 1. Save cache BEFORE hook so db-cache-path contains current state
+    (db/update-workspaces-cache! @db* metrics)
+
+    ;; 2. Trigger sessionEnd hook
+    (f.hooks/trigger-if-matches! :sessionEnd
+                                 (f.hooks/base-hook-data @db*)
+                                 {}
+                                 @db*
+                                 config)
+
+    ;; 3. Then shutdown
     (f.mcp/shutdown! db*)
     (swap! db* assoc :stopping true)
     nil))
@@ -111,9 +129,9 @@
   (metrics/task metrics :eca/chat-prompt-stop
     (f.chat/prompt-stop params db* messenger metrics)))
 
-(defn chat-delete [{:keys [db* metrics]} params]
+(defn chat-delete [{:keys [db* config metrics]} params]
   (metrics/task metrics :eca/chat-delete
-    (f.chat/delete-chat params db* metrics)
+    (f.chat/delete-chat params db* config metrics)
     {}))
 
 (defn chat-rollback [{:keys [db* metrics messenger]} params]

src/eca/features/tools/shell.clj

@@ -4,7 +4,8 @@
    [clojure.core.memoize :as memoize]
    [clojure.java.io :as io]
    [clojure.string :as string]
-   [clojure.walk :as walk])
+   [clojure.walk :as walk]
+   [eca.cache :as cache])
   (:import
    [java.net URI]
    [java.nio.file Paths]
@@ -143,6 +144,12 @@
                        x))
                    m)))
 
+(defn map->snake-cased-map
+  "Converts top-level keyword keys to snake_case strings.
+ Used for hook script inputs to follow shell/bash conventions."
+  [m]
+  (update-keys m #(if (keyword %) (csk/->snake_case %) %)))
+
 (defn obfuscate
   "Obfuscate all but first `preserve-num` and last `preserve-num` characters of a string.
    If the string is 4 characters or less, obfuscate all characters.
@@ -214,3 +221,16 @@
                              (deliver p# e#)))))]
        (.start t#)
        p#)))
+
+(defn get-workspaces
+  "Returns a vector of all workspace folder paths.
+   Returns nil if no workspace folders are configured."
+  [db]
+  (when-let [folders (seq (:workspace-folders db))]
+    (mapv (comp uri->filename :uri) folders)))
+
+(defn db-cache-path
+  "Returns the absolute path to the workspace-specific DB cache file as a string.
+   Used by hooks to access the cached database."
+  [db]
+  (str (cache/workspace-cache-file (:workspace-folders db) "db.transit.json" uri->filename)))