Merge pull request gi-dellav#178 from xavierforge/feat/hook-system

feat(hooks): external-command hooks at agent lifecycle points

Author: gi-dellav

Cargo.toml

@@ -30,6 +30,7 @@ multithread = ["tokio/rt-multi-thread"]
 multimodal = ["rig/image"]               
 pdf = ["multimodal", "rig/pdf"]   
 advisor = []
+hooks = []
 
 [dependencies]
 rig = { version = "0.39", features = ["rmcp"] }

docs/COMMANDS.md

@@ -67,6 +67,19 @@ the first line. When a prompt with `%%mode=last_user_mode` is activated,
 the mode reverts to whatever was last set explicitly by `/mode` or
 startup config. See Prompts & Themes below.
 
+## Hooks
+
+Requires the `hooks` feature (default-off; see [CONFIG.md](CONFIG.md#hooks)).
+
+| Command | Description |
+| ------- | ----------- |
+| `/hooks` | Show whether a hook dispatcher is installed and, if so, each configured event with its handler count. |
+
+Run `zerostack --hooks-test <tool> [--hooks-test-input <json>]` from the
+shell (not a slash command) to dry-run `PreToolUse` hooks for a tool without
+starting a session or making a model call. See
+[CONFIG.md](CONFIG.md#hooks) for the full hooks configuration reference.
+
 ## Prompts & Themes
 
 | Command | Description |

docs/CONFIG.md

@@ -189,6 +189,130 @@ Accepted top-level keys:
 | `acp_port`                | integer | TCP bind port for ACP server mode (equivalent to `--acp-port`, default: 7243).                                                                                               |
 | `colors`                  | object  | Background color overrides for the TUI. See the colors section below.                                                                                                       |
 
+## Hooks
+
+Requires the `hooks` Cargo feature, which is **default-off** — a prebuilt
+binary or package must have been compiled with `--features hooks` (or
+`--all-features`) for any of this to apply. When the feature isn't compiled
+in, none of the flags, files, or `/hooks`/`--hooks-test` commands below exist.
+
+Hooks let external commands observe or gate agent behavior at defined points
+(a tool call, a user prompt, the agent finishing a turn, a session
+starting/ending, a subagent starting/stopping), using the same
+`settings.json` shape, stdin envelope, and exit-code/stdout-JSON contract as
+Claude Code, so an existing CC hooks setup is largely compatible (see the
+`$CLAUDE_PROJECT_DIR` caveat below for the one script-level change some
+setups need).
+
+### Config file locations and precedence
+
+Hook config lives in a `settings.json` (JSON, not `config.toml`/`.yaml`) at up
+to three locations, loaded and merged in this order:
+
+| Location | Trust |
+| -------- | ----- |
+| `~/.config/zerostack/settings.json` (global; on macOS `~/Library/Application Support/zerostack/settings.json`; on Windows `%APPDATA%\zerostack\settings.json`, experimental) | Trusted by default |
+| `.zerostack/settings.json` (project, relative to CWD) | **Not** trusted by default — see Trust model below |
+| `/etc/zerostack/managed-settings.json` (Linux) / `/Library/Application Support/zerostack/managed-settings.json` (macOS) / `C:\ProgramData\zerostack\managed-settings.json` (Windows, experimental) — admin-controlled | Always trusted; unaffected by `disableAllHooks` |
+
+Each file may have a top-level `hooks` object (keyed by event name) and a
+top-level `disableAllHooks: true` boolean. `disableAllHooks` (from the global
+or project file) or the `--no-hooks` CLI flag suppresses every non-managed
+hook; managed hooks still run regardless. A missing or invalid file is not an
+error — it just contributes nothing.
+
+**Compatible with Claude Code's `.claude/settings.json`**: zerostack does not
+read that file directly, but its own `settings.json` uses the identical
+`hooks` schema, so copying or symlinking the `hooks` key from
+`.claude/settings.json` into `.zerostack/settings.json` works as-is. Scripts
+themselves may still need a change: zerostack sets `$ZEROSTACK_PROJECT_DIR`
+rather than `$CLAUDE_PROJECT_DIR`, so a script that reads the latter must be
+updated to read the former.
+
+### Handler schema
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write",
+        "hooks": [
+          { "type": "command", "command": "./guard.sh", "timeout": 30 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `type` | string | Only `"command"` is supported. |
+| `command` | string | Shell command, run via `sh -c` on Unix (`powershell -Command` on Windows, experimental). Receives the stdin envelope as JSON; `$ZEROSTACK_PROJECT_DIR` is set in its environment. |
+| `args` | array of strings | When present, bypasses the shell entirely: `command` is executed directly as the program with `args` as its argv (no shell metacharacter expansion). |
+| `timeout` | integer (seconds) | Per-hook timeout; the whole process group is killed on expiry. Default: 60. |
+| `async` | boolean | When `true`, the hook runs in the background and its decision is ignored. Default: `false`. |
+| `if` | string | A shell command evaluated (with the same stdin envelope) before the handler runs; the handler only runs if it exits `0`. Fails closed: a broken/unparseable/timed-out condition still runs the handler, with a warning. |
+| `once` | boolean | Runs the handler at most once per event per session; later matches are skipped. |
+
+`matcher` (on the handler group, not the handler) follows Claude Code
+semantics: omitted, `""`, or `"*"` matches every tool; a bare name or a
+`|`/`,`-separated list is an exact case-insensitive match after tool-name
+normalization (e.g. `Bash` ↔ `bash`, `Glob` ↔ `find_files`, `Edit|Write`
+matches zerostack's `write` tool); anything else is treated as a regex.
+Invalid regexes are reported at load time.
+
+### Events
+
+`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `UserPromptSubmit`,
+`Stop`, `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`.
+`PreCompact` and `Notification` are not currently implemented.
+
+Only `PreToolUse` is permission-blockable by default. A handler's stdout JSON
+may set `"permissionDecision"` to `"deny"`, `"ask"`, `"allow"`, or omit it
+(defer to the normal permission system). `deny` always blocks, holding even
+under `--yolo`. `ask` forces an interactive confirmation regardless of
+permission mode, and escalates to deny in non-interactive contexts (`-p`,
+`--loop`) where no confirmation is possible. `allow` suppresses the
+interactive prompt for that one call only — it can never override a deny
+from a rule, security mode, managed policy, or another hook. `PreToolUse` may
+also set `"updatedInput"` to rewrite the tool's arguments before it runs, and
+`PostToolUse` may set `"result"` to rewrite the model-visible output.
+
+`UserPromptSubmit` and `SubagentStart` can set `"additionalContext"` to
+prepend text to the prompt. `Stop` and `SubagentStop` can set
+`"decision": "block"` with a `"reason"` to force the agent (or subagent) to
+continue instead of finishing, using `reason` as the next instruction; `Stop`
+gives up after 8 consecutive blocks without progress.
+
+Any handler can also signal via **exit code** instead of JSON: exit `0` means
+no objection, exit `2` blocks (for blockable events) with stderr as the
+reason, and any other exit code is a non-blocking error. Exit `2` combined
+with stdout JSON is a mixed-channel warning — the JSON is ignored.
+
+### Trust model
+
+Project-level hook handlers (`.zerostack/settings.json` — global and managed
+hooks are trusted automatically) require interactive confirmation the first
+time they'd run, keyed by a hash of the handler's definition (event +
+matcher + command/args/timeout/etc.); changing the definition changes the
+hash and requires re-confirmation. Confirmations persist to
+`$XDG_DATA_HOME/zerostack/trusted-hooks.json` (a user-level file, so child
+processes/orchestrated subagents sharing it inherit trust automatically). In
+headless contexts (`-p`, `--loop`) an unconfirmed project hook is skipped
+with a warning rather than prompting.
+
+### Global switches
+
+| Flag | Effect |
+| ---- | ------ |
+| `--no-hooks` | Disables all non-managed hooks for this run. |
+| `disableAllHooks: true` (in global or project `settings.json`) | Same effect, via config. |
+| `--hooks-test <tool> [--hooks-test-input <json>]` | Dry-runs `PreToolUse` for `tool` against the loaded/trust-filtered dispatcher and prints the merged verdict/reason/`updatedInput`, then exits — no session, agent, or API key required. |
+
+See [COMMANDS.md](COMMANDS.md#hooks) for the `/hooks` slash command.
+
 ## Mid-turn compaction
 
 By default zerostack only compacts the conversation *between* turns, after a

src/agent/builder.rs

@@ -225,21 +225,29 @@ pub async fn build_agent_inner<M: CompletionModel + 'static>(
             )),
         ]);
 
-        let mut builder = builder.tools(base_tools.into_vec());
+        let mut all_tools: Vec<Box<dyn rig::tool::ToolDyn>> = base_tools.into_vec();
 
         #[cfg(feature = "subagents")]
         if cfg.task_enabled.unwrap_or(true) {
             use crate::extras::subagents::task_tool::TaskTool;
-            builder = builder.tool(TaskTool::new(permission.clone(), ask_tx.clone()));
+            all_tools.push(Box::new(TaskTool::new(permission.clone(), ask_tx.clone())));
         }
 
         #[cfg(feature = "memory")]
         {
             use crate::extras::memory::{MemoryRead, MemorySearch, MemoryWrite};
-            builder = builder
-                .tool(MemoryWrite::new(permission.clone(), ask_tx.clone()))
-                .tool(MemoryRead::new(permission.clone(), ask_tx.clone()))
-                .tool(MemorySearch::new(permission.clone(), ask_tx.clone()));
+            all_tools.push(Box::new(MemoryWrite::new(
+                permission.clone(),
+                ask_tx.clone(),
+            )));
+            all_tools.push(Box::new(MemoryRead::new(
+                permission.clone(),
+                ask_tx.clone(),
+            )));
+            all_tools.push(Box::new(MemorySearch::new(
+                permission.clone(),
+                ask_tx.clone(),
+            )));
         }
 
         #[cfg(feature = "mcp")]
@@ -253,22 +261,21 @@ pub async fn build_agent_inner<M: CompletionModel + 'static>(
             let mcp_tools = manager
                 .collect_tools(permission.clone(), ask_tx.clone())
                 .await;
-            if !mcp_tools.is_empty() {
-                let dyn_tools: Vec<Box<dyn rig::tool::ToolDyn>> = mcp_tools
-                    .into_iter()
-                    .map(|t| Box::new(t) as Box<dyn rig::tool::ToolDyn>)
-                    .collect();
-                builder = builder.tools(dyn_tools);
+            for t in mcp_tools {
+                all_tools.push(Box::new(t) as Box<dyn rig::tool::ToolDyn>);
             }
         }
 
         #[cfg(feature = "advisor")]
         if crate::extras::advisor::with_config(|c| c.enabled) {
             use crate::extras::advisor::AdvisorTool;
-            builder = builder.tool(AdvisorTool::new());
+            all_tools.push(Box::new(AdvisorTool::new()));
         }
 
-        builder.build()
+        #[cfg(feature = "hooks")]
+        let all_tools = crate::extras::hooks::wrap_from_global(all_tools, permission.clone());
+
+        builder.tools(all_tools).build()
     }
 }