docs

Author: ericdallo

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
 

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.