Merge branch 'hooks'

ericdallo · ericdallo · commit b6574a37cb0c · 2025-10-16T14:00:22.000-03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Add hooks support. #43
+
 ## 0.69.1
 
 - Fix regression on models with no extraPayload.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -352,6 +352,60 @@ ECA allows to totally customize the prompt sent to LLM via the `behavior` config
       }
     }
     ```
+    
+## Hooks
+
+Hooks are actions that can run before or after an specific event, useful to notify after prompt finished or to block a tool call doing some check in a script.
+
+Allowed hook types:
+
+- `prePrompt`: Run before prompt is sent to LLM, if a hook output is provided, append to user prompt.
+- `postPrompt`: Run after prompt is finished, when chat come back to idle state.
+- `preToolCall`: Run before a tool is called, if a hook exit with status `2`, reject the tool call.
+- `postToolCall`: Run after a tool was called.
+
+__Input__: Hooks will receive input as json with information from that event, like tool name, args or user prompt.
+__Output__: All hook actions allow printing output (stdout) and errors (stderr) which will be shown in chat.
+__Matcher__: Specify whether to apply this hook checking a regex applying to `mcp__tool-name`, applicable only for `*ToolCall` hooks.
+
+Examples:
+
+=== "Notify after prompt finish"
+
+    ```javascript
+    {
+      "hooks": {
+        "notify-me": {
+          "type": "postPrompt", 
+          "actions": [
+            {
+              "type": "shell",
+              "shell": "notify-send \"Hey, prompt finished!\""
+            }
+          ]
+        }
+      }
+    } 
+    ```
+    
+=== "Block specific tool call"
+
+    ```javascript
+    {
+      "hooks": {
+        "notify-me": {
+          "type": "preToolCall", 
+          "matcher": "my-mcp__some-tool",
+          "actions": [
+            {
+              "type": "shell",
+              "shell": "echo \"We should not run this tool bro!\" >&2 && exit 2"
+            }
+          ]
+        }
+      }
+    }
+    ```
 
 ## Opentelemetry integration
 
@@ -387,6 +441,15 @@ To configure, add your OTLP collector config via `:otlp` map following [otlp aut
             }};
         }};
         defaultModel?: string;
+        hooks?: {[key: string]: {
+                type: 'preToolCall' | 'postToolCall' | 'preToolCallApproval' | 'prePrompt' | 'postPrompt';
+                matcher: string;
+                actions: {
+                    type: 'shell';
+                    shell: string;
+                }[];
+            };
+        };
         rules?: [{path: string;}];
         commands?: [{path: string;}];
         behavior?: {[key: string]: {
@@ -464,6 +527,7 @@ To configure, add your OTLP collector config via `:otlp` map following [otlp aut
           "ollama": {"url": "http://localhost:11434"}
       },
       "defaultModel": null, // let ECA decides the default model.
+      "hooks": {},
       "rules" : [],
       "commands" : [],
       "disabledTools": [],
diff --git a/docs/features.md b/docs/features.md
@@ -111,7 +111,7 @@ The built-in commands are:
 
 It's possible to configure custom command prompts, for more details check [its configuration](./configuration.md#custom-command-prompts)
 
-### Login
+#### Login
 
 It's possible to login to some providers using `/login` command, ECA will ask and give instructions on how to authenticate in the chosen provider and save the login info globally in its cache `~/.cache/eca/db.transit.json`.
 
@@ -120,6 +120,14 @@ Current supported providers with login:
 - `anthropic`: with options to login to Claude Max/Pro or create API keys.
 - `github-copilot`: via Github oauth.
 
+### Hooks
+
+Hooks are actions that can run before or after an specific event, useful to notify after prompt finished or to block a tool call doing some check in a script.
+
+![](./images/features/hooks.png)
+
+For more details, check [hooks configuration](./configuration.md#hooks)
+
 ## OpenTelemetry integration
 
 ECA has support for [OpenTelemetry](https://opentelemetry.io/)(otlp), if configured, server tasks, tool calls, and more will be metrified via otlp API.
diff --git a/docs/protocol.md b/docs/protocol.md
@@ -515,6 +515,8 @@ type ChatContent =
     | ChatReasonStartedContent 
     | ChatReasonTextContent 
     | ChatReasonFinishedContent 
+    | ChatHookActionStartedContent 
+    | ChatHookActionFinishedContent 
     | ChatToolCallPrepareContent
     | ChatToolCallRunContent
     | ChatToolCallRunningContent
@@ -600,6 +602,67 @@ interface ChatReasonFinishedContent {
     totalTimeMs: number;
 }
 
+/**
+ * A hook action started to run
+ *
+ */
+interface ChatHookActionStartedContent {
+    type: 'hookActionStarted';
+    
+    /**
+     * The id of this hook
+     */
+    id: string; 
+    
+    /**
+     * The name of this hook
+     */
+    name: string;
+    
+    /**
+     * The type of this hook action
+     */
+    actionType: 'shell';
+}
+
+/**
+ * A hook action finished
+ *
+ */
+interface ChatHookActionFinishedContent {
+    type: 'hookActionFinished';
+    
+    /**
+     * The id of this hook
+     */
+    id: string; 
+    
+    /**
+     * The name of this hook
+     */
+    name: string;
+    
+    /**
+     * The type of this hook action
+     */
+    actionType: 'shell';
+    
+    /**
+     * The status code of this hook
+     */
+    status: number;
+    
+    /**
+     * The output of this hook if any
+     */
+    output?: string;
+    
+    /**
+     * The error of this hook if any
+     */
+    error?: string;
+}
+
 /**
  * URL content message from the LLM
  */
diff --git a/images/features/hooks.png b/images/features/hooks.png
diff --git a/src/eca/config.clj b/src/eca/config.clj
@@ -81,6 +81,7 @@
                                                                               ".*-c\\s+[\"'].*open.*[\"']w[\"'].*",
                                                                               ".*bash.*-c.*>.*"]}}}}}}}
    :defaultModel nil
+   :hooks {} 
    :rules []
    :commands []
    :disabledTools []
diff --git a/src/eca/features/chat.clj b/src/eca/features/chat.clj
@@ -7,6 +7,7 @@
    [eca.db :as db]
    [eca.features.commands :as f.commands]
    [eca.features.context :as f.context]
+   [eca.features.hooks :as f.hooks]
    [eca.features.index :as f.index]
    [eca.features.login :as f.login]
    [eca.features.prompt :as f.prompt]
@@ -33,8 +34,32 @@
     :role role
     :content content}))
 
-(defn finish-chat-prompt! [status {:keys [chat-id db* metrics on-finished-side-effect] :as chat-ctx}]
+(defn ^:private notify-before-hook-action! [chat-ctx {:keys [id name type]}]
+  (send-content! chat-ctx :system
+                 {:type :hookActionStarted
+                  :action-type type
+                  :name name
+                  :id id}))
+
+(defn ^:private notify-after-hook-action! [chat-ctx {:keys [id name output error status type]}]
+  (send-content! chat-ctx :system
+                 {:type :hookActionFinished
+                  :action-type type
+                  :id id
+                  :name name
+                  :status status
+                  :output output
+                  :error error}))
+
+(defn finish-chat-prompt! [status {:keys [message chat-id db* metrics config on-finished-side-effect] :as chat-ctx}]
   (swap! db* assoc-in [:chats chat-id :status] status)
+  (f.hooks/trigger-if-matches! :postPrompt
+                               {:chat-id chat-id
+                                :prompt message}
+                               {:on-before-action (partial notify-before-hook-action! chat-ctx)
+                                :on-after-action (partial notify-after-hook-action! chat-ctx)}
+                               @db*
+                               config)
   (send-content! chat-ctx :system
                  {:type :progress
                   :state :finished})
@@ -153,6 +178,10 @@
    {:status :rejected
     :actions [:send-toolCallRejected]}
 
+   [:execution-approved :hook-rejected]
+   {:status :rejected
+    :actions [:set-decision-reason]}
+
    [:execution-approved :execution-start]
    {:status :executing
     :actions [:set-start-time :add-future :send-toolCallRunning :send-progress]}
@@ -163,7 +192,7 @@
 
    [:cleanup :cleanup-finished]
    {:status :completed
-    :actions [:destroy-all-resources :remove-all-resources :remove-all-promises :remove-future]}
+    :actions [:destroy-all-resources :remove-all-resources :remove-all-promises :remove-future :trigger-post-tool-call-hook]}
 
    [:executing :resources-created]
    {:status :executing
@@ -304,6 +333,19 @@
                       :details (:details event-data)
                       :summary (:summary event-data))))
 
+    :trigger-post-tool-call-hook
+    (let [tool-call-state (get-tool-call-state @db* (:chat-id chat-ctx) tool-call-id)]
+      (f.hooks/trigger-if-matches!
+       :postToolCall
+       {:chat-id (:chat-id chat-ctx)
+        :tool-name (:name tool-call-state)
+        :server (:server tool-call-state)
+        :arguments (:arguments tool-call-state)}
+       {:on-before-action (partial notify-before-hook-action! chat-ctx)
+        :on-after-action (partial notify-after-hook-action! chat-ctx)}
+       @db*
+       (:config chat-ctx)))
+
     ;; Actions on parts of the state
     :deliver-approval-false
     (deliver (get-in @db* [:chats (:chat-id chat-ctx) :tool-calls tool-call-id :approved?*])
@@ -581,9 +623,10 @@
                          (when-not (string/blank? @received-msgs*)
                            (add-to-history! {:role "assistant" :content [{:type :text :text @received-msgs*}]})
                            (reset! received-msgs* ""))
-                         (let [any-rejected-tool-call?* (atom false)]
+                         (let [any-rejected-tool-call?* (atom nil)]
                            (run! (fn do-tool-call [{:keys [id name arguments] :as tool-call}]
                                    (let [approved?* (promise) ; created here, stored in the state.
+                                         hook-approved?* (atom true)
                                          details (f.tools/tool-call-details-before-invocation name arguments)
                                          summary (f.tools/tool-call-summary all-tools name arguments config)
                                          origin (tool-name->origin name all-tools)
@@ -616,8 +659,24 @@
                                                                                 :text "Tool call rejected by user config"}})
                                          (logger/warn logger-tag "Unknown value of approval in config"
                                                       {:approval approval :tool-call-id id})))
-                                     ;; Execute each tool call concurrently
-                                     (if @approved?* ;TODO: Should there be a timeout here?  If so, what would be the state transitions?
+                                     ;; TODO: Should there be a timeout here?  If so, what would be the state transitions?
+                                     @approved?* ;; wait for user respond before checking hook
+                                     (f.hooks/trigger-if-matches! :preToolCall
+                                                                  {:chat-id chat-id
+                                                                   :tool-name name
+                                                                   :server server
+                                                                   :arguments arguments}
+                                                                  {:on-before-action (partial notify-before-hook-action! chat-ctx)
+                                                                   :on-after-action (fn [result]
+                                                                                      (when (= 2 (:status result))
+                                                                                        (transition-tool-call! db* chat-ctx id :hook-rejected
+                                                                                                               {:reason {:code :hook-rejected
+                                                                                                                         :text (str "Tool call rejected by hook, output: " (:output result))}})
+                                                                                        (reset! hook-approved?* false))
+                                                                                      (notify-after-hook-action! chat-ctx result))}
+                                                                  db
+                                                                  config)
+                                     (if (and @approved?* @hook-approved?*)
                                        ;; assert: In :execution-approved or :stopping or :cleanup
                                        (when-not (#{:stopping :cleanup} (:status (get-tool-call-state @db* chat-id id)))
                                          (assert-chat-not-stopped! chat-ctx)
@@ -695,7 +754,7 @@
                                                            :content (assoc tool-call :output {:error true
                                                                                               :contents [{:text text
                                                                                                           :type :text}]})})
-                                         (reset! any-rejected-tool-call?* true)
+                                         (reset! any-rejected-tool-call?* code)
                                          (transition-tool-call! db* chat-ctx id :send-reject
                                                                 {:origin origin
                                                                  :name name
@@ -741,13 +800,21 @@
                                                              :ex-data (ex-data t)
                                                              :message (.getMessage t)
                                                              :cause (.getCause t)})))))))
-                           (if @any-rejected-tool-call?*
+                           (if-let [reason-code @any-rejected-tool-call?*]
                              (do
-                               (send-content! chat-ctx :system
-                                              {:type :text
-                                               :text "Tell ECA what to do differently for the rejected tool(s)"})
-                               (add-to-history! {:role "user" :content [{:type :text
-                                                                         :text "I rejected one or more tool calls with the following reason"}]})
+                               (if (= :hook-rejected reason-code)
+                                 (do
+                                   (send-content! chat-ctx :system
+                                                  {:type :text
+                                                   :text "Tool rejected by hook"})
+                                   (add-to-history! {:role "user" :content [{:type :text
+                                                                             :text "A user hook rejected one or more tool calls with the following reason"}]}))
+                                 (do
+                                   (send-content! chat-ctx :system
+                                                  {:type :text
+                                                   :text "Tell ECA what to do differently for the rejected tool(s)"})
+                                   (add-to-history! {:role "user" :content [{:type :text
+                                                                             :text "I rejected one or more tool calls with the following reason"}]})))
                                (finish-chat-prompt! :idle chat-ctx)
                                nil)
                              {:new-messages (get-in @db* [:chats chat-id :messages])})))
@@ -882,6 +949,7 @@
                                                       expanded-prompt-contexts
                                                       image-contents)}]
         chat-ctx {:chat-id chat-id
+                  :message message
                   :contexts contexts
                   :behavior selected-behavior
                   :behavior-config behavior-config
@@ -892,7 +960,21 @@
                   :metrics metrics
                   :config config
                   :messenger messenger}
-        decision (message->decision message)]
+        decision (message->decision message)
+        hook-outputs* (atom [])
+        _ (f.hooks/trigger-if-matches! :prePrompt
+                                       {:chat-id chat-id
+                                        :prompt message}
+                                       {:on-before-action (partial notify-before-hook-action! chat-ctx)
+                                        :on-after-action (fn [result]
+                                                           (when (= 0 (:status result))
+                                                             (reset! hook-outputs* (:outputs result)))
+                                                           (notify-after-hook-action! chat-ctx result))}
+                                       db
+                                       config)
+        user-messages (if (seq @hook-outputs*)
+                        (update-in user-messages [0 :content 0 :text] str " " (string/join "\n" @hook-outputs*))
+                        user-messages)]
     (swap! db* assoc-in [:chats chat-id :status] :running)
     (send-content! chat-ctx :user {:type :text
                                    :text (str message "\n")})
diff --git a/src/eca/features/hooks.clj b/src/eca/features/hooks.clj
diff --git a/test/eca/features/hooks_test.clj b/test/eca/features/hooks_test.clj
