@sigitcodereview / sigit / commits / 730381a

feat: add extensibility hooks for agent lifecycle and tool execution

Implement SessionStart, PreToolUse, and PostToolUse hooks that allow users to run custom shell commands at key moments in the agent lifecycle. Hooks support variable substitution for context information and run in the session working directory. Configuration example in ~/.config/sigit/settings.toml: [hooks] session_start = ["echo 'Starting in {cwd}'"] pre_tool_use = ["echo 'Running {tool_name}'"] post_tool_use = ["echo 'Result: {tool_result_len} bytes'"] Hook execution is synchronous and failures are logged but don't interrupt the session. No performance overhead when hooks are not configured. Changes: - New src/hooks.rs module with hook definitions, configuration, and execution - Updated src/settings.rs to load hooks from [hooks] section in settings.toml - Integrated SessionStart hooks into handle_new_session, handle_load_session, and handle_fork_session in src/main.rs - Integrated PreToolUse and PostToolUse hooks around tool execution in src/tools.rs - Added documentation and example configuration files All existing tests pass (178 unit tests + 5 integration tests). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

paydii committed Jul 10, 2026 at 18:56 UTC 730381aada62dd7cb7a43b903e666e204cded4c6
5 files changed +373 -2
docs/hooks.md new
+76
@@ -0,0 +1,76 @@
1 +# siGit Code Hooks
2 +
3 +Hooks allow you to run custom scripts at key moments in the agent lifecycle:
4 +- **SessionStart**: When a session begins (new/load/fork)
5 +- **PreToolUse**: Before a tool is executed
6 +- **PostToolUse**: After a tool is executed
7 +
8 +## Configuration
9 +
10 +Hooks are configured in `~/.config/sigit/settings.toml` under the `[hooks]` section:
11 +
12 +```toml
13 +[hooks]
14 +session_start = ["echo 'Starting siGit in {cwd}'"]
15 +pre_tool_use = ["echo 'About to run {tool_name} with {tool_args_len} bytes of args'"]
16 +post_tool_use = ["echo 'Finished {tool_name}, result was {tool_result_len} bytes'"]
17 +```
18 +
19 +Each hook is a list of shell commands. Commands run in the session working directory and inherit the environment.
20 +
21 +## Variable Substitution
22 +
23 +Hooks support substitution for context variables:
24 +
25 +### SessionStart
26 +- `{cwd}` - The session working directory
27 +- `{session_id}` - The unique session identifier
28 +
29 +### PreToolUse
30 +- `{tool_name}` - The name of the tool being called
31 +- `{tool_args_len}` - Length of the tool arguments in bytes
32 +- `{cwd}` - The session working directory
33 +
34 +### PostToolUse
35 +- `{tool_name}` - The name of the tool that ran
36 +- `{tool_result_len}` - Length of the tool result in bytes
37 +- `{cwd}` - The session working directory
38 +
39 +## Examples
40 +
41 +### Log all tool usage to a file
42 +
43 +```toml
44 +[hooks]
45 +pre_tool_use = ["echo '[{tool_name}]' >> /tmp/sigit-tools.log"]
46 +post_tool_use = ["echo ' → {tool_result_len} bytes' >> /tmp/sigit-tools.log"]
47 +```
48 +
49 +### Send notifications
50 +
51 +```toml
52 +[hooks]
53 +session_start = ["notify-send 'siGit started in {cwd}'"]
54 +```
55 +
56 +### Build on session start
57 +
58 +```toml
59 +[hooks]
60 +session_start = ["cd {cwd} && cargo build"]
61 +```
62 +
63 +### Track metrics
64 +
65 +```toml
66 +[hooks]
67 +pre_tool_use = ["echo {tool_name} | tee -a ~/.sigit/tool_usage.txt"]
68 +post_tool_use = ["wc -c <<< {tool_result_len} >> ~/.sigit/result_sizes.txt"]
69 +```
70 +
71 +## Notes
72 +
73 +- Hooks are optional. If no hooks are configured, there is no performance overhead.
74 +- Hook failures (non-zero exit codes) are logged as warnings but do not interrupt the session.
75 +- Hooks are run synchronously, so slow hooks will impact agent responsiveness.
76 +- Hooks are not available in the interactive TUI yet—only in ACP mode and headless mode.
examples/settings-with-hooks.toml new
+49
@@ -0,0 +1,49 @@
1 +# Example siGit Code settings with hooks configured
2 +# Place this at ~/.config/sigit/settings.toml
3 +
4 +# Whether to use on-device inference (true) or cloud (false)
5 +local_inference = true
6 +
7 +# Tool permission policy
8 +[permissions]
9 +# Default permission mode: allow, ask, or deny
10 +default = "ask"
11 +
12 +# Per-tool overrides
13 +[permissions.tools]
14 +edit_file = "ask"
15 +run_command = "ask"
16 +
17 +# Argument-level allow/deny rules
18 +[permissions.rules]
19 +allow = ["run_command(cargo *)"]
20 +deny = ["run_command(rm -rf *)"]
21 +
22 +# Extensibility hooks for session and tool lifecycle
23 +[hooks]
24 +
25 +# SessionStart hooks run when a session begins (new/load/fork)
26 +# Available variables: {cwd}, {session_id}
27 +session_start = [
28 + "echo 'Starting siGit session in {cwd}'",
29 + # Uncomment to build on session start:
30 + # "cd {cwd} && cargo build",
31 +]
32 +
33 +# PreToolUse hooks run before a tool is executed
34 +# Available variables: {tool_name}, {tool_args_len}, {cwd}
35 +pre_tool_use = [
36 + # Log tool usage
37 + "echo '[TOOL] {tool_name}' >> /tmp/sigit-tool-log.txt",
38 + # Uncomment to show which tools run:
39 + # "echo 'About to run: {tool_name} ({tool_args_len} bytes of args)'",
40 +]
41 +
42 +# PostToolUse hooks run after a tool is executed
43 +# Available variables: {tool_name}, {tool_result_len}, {cwd}
44 +post_tool_use = [
45 + # Log result size
46 + "echo '[RESULT] {tool_name}: {tool_result_len} bytes' >> /tmp/sigit-tool-log.txt",
47 + # Uncomment to track metrics:
48 + # "echo {tool_result_len} >> /tmp/sigit-result-sizes.log",
49 +]
src/hooks.rs new
+220
@@ -0,0 +1,220 @@
1 +//! Extensibility hooks for agent lifecycle and tool execution.
2 +//!
3 +//! Hooks allow users to run custom logic at key moments:
4 +//! - `SessionStart`: when a session begins (new/load/fork)
5 +//! - `PreToolUse`: before a tool is executed
6 +//! - `PostToolUse`: after a tool is executed
7 +//!
8 +//! Hooks are configured in `settings.toml` under `[hooks]`:
9 +//! ```toml
10 +//! [hooks]
11 +//! session_start = ["echo 'Starting siGit session'"]
12 +//! pre_tool_use = ["echo 'About to run {tool_name}'"]
13 +//! post_tool_use = ["echo 'Finished {tool_name}: {tool_result_len} chars'"]
14 +//! ```
15 +//!
16 +//! Hooks support substitution for context variables:
17 +//! - SessionStart: `{cwd}`, `{session_id}`
18 +//! - PreToolUse: `{tool_name}`, `{tool_args_len}`
19 +//! - PostToolUse: `{tool_name}`, `{tool_result_len}`
20 +//!
21 +//! Hooks run in the session cwd and inherit the environment. Shell hook failures
22 +//! are logged but do not interrupt the session.
23 +
24 +use serde::{Deserialize, Serialize};
25 +use std::path::Path;
26 +use std::process::Command;
27 +
28 +/// Hook configuration: lists of shell commands to run at key moments.
29 +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
30 +pub struct HookSettings {
31 + /// Commands to run when a session starts (new/load/fork).
32 + #[serde(default)]
33 + pub session_start: Vec<String>,
34 + /// Commands to run before a tool is executed.
35 + #[serde(default)]
36 + pub pre_tool_use: Vec<String>,
37 + /// Commands to run after a tool is executed.
38 + #[serde(default)]
39 + pub post_tool_use: Vec<String>,
40 +}
41 +
42 +impl HookSettings {
43 + /// Whether any hooks are configured.
44 + pub fn has_hooks(&self) -> bool {
45 + !self.session_start.is_empty()
46 + || !self.pre_tool_use.is_empty()
47 + || !self.post_tool_use.is_empty()
48 + }
49 +}
50 +
51 +/// Context passed to hook substitution.
52 +pub struct HookContext {
53 + pub cwd: Option<String>,
54 + pub session_id: Option<String>,
55 + pub tool_name: Option<String>,
56 + pub tool_args_len: Option<usize>,
57 + pub tool_result_len: Option<usize>,
58 +}
59 +
60 +impl HookContext {
61 + /// Create a new empty context.
62 + pub fn new() -> Self {
63 + Self {
64 + cwd: None,
65 + session_id: None,
66 + tool_name: None,
67 + tool_args_len: None,
68 + tool_result_len: None,
69 + }
70 + }
71 +
72 + /// Substitute variables in the command string.
73 + fn substitute(&self, cmd: &str) -> String {
74 + let mut result = cmd.to_string();
75 + if let Some(cwd) = &self.cwd {
76 + result = result.replace("{cwd}", cwd);
77 + }
78 + if let Some(session_id) = &self.session_id {
79 + result = result.replace("{session_id}", session_id);
80 + }
81 + if let Some(tool_name) = &self.tool_name {
82 + result = result.replace("{tool_name}", tool_name);
83 + }
84 + if let Some(tool_args_len) = self.tool_args_len {
85 + result = result.replace("{tool_args_len}", &tool_args_len.to_string());
86 + }
87 + if let Some(tool_result_len) = self.tool_result_len {
88 + result = result.replace("{tool_result_len}", &tool_result_len.to_string());
89 + }
90 + result
91 + }
92 +}
93 +
94 +impl Default for HookContext {
95 + fn default() -> Self {
96 + Self::new()
97 + }
98 +}
99 +
100 +/// Run a single hook command in the given context.
101 +fn run_hook(cmd: &str, context: &HookContext, cwd: &Path) {
102 + let substituted = context.substitute(cmd);
103 + log::debug!("Running hook: {substituted}");
104 + match Command::new("sh")
105 + .arg("-c")
106 + .arg(&substituted)
107 + .current_dir(cwd)
108 + .output()
109 + {
110 + Ok(output) => {
111 + if !output.status.success() {
112 + let stderr = String::from_utf8_lossy(&output.stderr);
113 + log::warn!(
114 + "Hook failed with status {:?}: {}",
115 + output.status.code(),
116 + stderr.trim()
117 + );
118 + } else {
119 + let stdout = String::from_utf8_lossy(&output.stdout);
120 + if !stdout.is_empty() {
121 + log::debug!("Hook output: {}", stdout.trim());
122 + }
123 + }
124 + }
125 + Err(err) => {
126 + log::warn!("Failed to run hook: {err}");
127 + }
128 + }
129 +}
130 +
131 +/// Run all session start hooks.
132 +pub fn run_session_start_hooks(hooks: &HookSettings, cwd: &Path, session_id: &str) {
133 + if hooks.session_start.is_empty() {
134 + return;
135 + }
136 + log::info!("Running {} session_start hooks", hooks.session_start.len());
137 + let context = HookContext {
138 + cwd: Some(cwd.display().to_string()),
139 + session_id: Some(session_id.to_string()),
140 + ..HookContext::new()
141 + };
142 + for cmd in &hooks.session_start {
143 + run_hook(cmd, &context, cwd);
144 + }
145 +}
146 +
147 +/// Run all pre-tool-use hooks.
148 +pub fn run_pre_tool_use_hooks(hooks: &HookSettings, tool_name: &str, tool_args: &str, cwd: &Path) {
149 + if hooks.pre_tool_use.is_empty() {
150 + return;
151 + }
152 + log::debug!("Running {} pre_tool_use hooks", hooks.pre_tool_use.len());
153 + let context = HookContext {
154 + cwd: Some(cwd.display().to_string()),
155 + tool_name: Some(tool_name.to_string()),
156 + tool_args_len: Some(tool_args.len()),
157 + ..HookContext::new()
158 + };
159 + for cmd in &hooks.pre_tool_use {
160 + run_hook(cmd, &context, cwd);
161 + }
162 +}
163 +
164 +/// Run all post-tool-use hooks.
165 +pub fn run_post_tool_use_hooks(
166 + hooks: &HookSettings,
167 + tool_name: &str,
168 + tool_result: &str,
169 + cwd: &Path,
170 +) {
171 + if hooks.post_tool_use.is_empty() {
172 + return;
173 + }
174 + log::debug!("Running {} post_tool_use hooks", hooks.post_tool_use.len());
175 + let context = HookContext {
176 + cwd: Some(cwd.display().to_string()),
177 + tool_name: Some(tool_name.to_string()),
178 + tool_result_len: Some(tool_result.len()),
179 + ..HookContext::new()
180 + };
181 + for cmd in &hooks.post_tool_use {
182 + run_hook(cmd, &context, cwd);
183 + }
184 +}
185 +
186 +#[cfg(test)]
187 +mod tests {
188 + use super::*;
189 +
190 + #[test]
191 + fn test_hook_context_substitution() {
192 + let context = HookContext {
193 + cwd: Some("/home/user/project".to_string()),
194 + session_id: Some("session-123".to_string()),
195 + tool_name: Some("read_file".to_string()),
196 + tool_args_len: Some(42),
197 + tool_result_len: Some(1000),
198 + };
199 + assert_eq!(
200 + context.substitute("cd {cwd} && echo {session_id}"),
201 + "cd /home/user/project && echo session-123"
202 + );
203 + assert_eq!(
204 + context.substitute("Tool: {tool_name}, args={tool_args_len}, result={tool_result_len}"),
205 + "Tool: read_file, args=42, result=1000"
206 + );
207 + }
208 +
209 + #[test]
210 + fn test_hook_settings_has_hooks() {
211 + let empty = HookSettings::default();
212 + assert!(!empty.has_hooks());
213 +
214 + let with_hooks = HookSettings {
215 + session_start: vec!["echo start".to_string()],
216 + ..HookSettings::default()
217 + };
218 + assert!(with_hooks.has_hooks());
219 + }
220 +}
src/main.rs
+19
@@ -33,6 +33,7 @@ mod backend;
33 mod chat;
34 mod credentials;
35 mod headless;
36 +mod hooks;
37 mod instructions;
38 mod mcp;
39 mod models;
@@ -1024,6 +1025,12 @@ impl SiGitAgent {
1025
1026 self.advertise_commands(cx, args.session_id.clone());
1027
1028 + // Run SessionStart hooks
1029 + let hook_settings = settings::load().hooks;
1030 + if hook_settings.has_hooks() {
1031 + hooks::run_session_start_hooks(&hook_settings, &args.cwd, &args.session_id.to_string());
1032 + }
1033 +
1034 Ok(LoadSessionResponse::new().config_options(config_options))
1035 }
1036
@@ -1074,6 +1081,12 @@ impl SiGitAgent {
1081
1082 self.advertise_commands(cx, new_id.clone());
1083
1084 + // Run SessionStart hooks
1085 + let hook_settings = settings::load().hooks;
1086 + if hook_settings.has_hooks() {
1087 + hooks::run_session_start_hooks(&hook_settings, &args.cwd, &new_id.to_string());
1088 + }
1089 +
1090 Ok(ForkSessionResponse::new(new_id).config_options(config_options))
1091 }
1092
@@ -1122,6 +1135,12 @@ impl SiGitAgent {
1135
1136 self.advertise_commands(cx, session_id.clone());
1137
1138 + // Run SessionStart hooks
1139 + let hook_settings = settings::load().hooks;
1140 + if hook_settings.has_hooks() {
1141 + hooks::run_session_start_hooks(&hook_settings, &args.cwd, &session_id.to_string());
1142 + }
1143 +
1144 Ok(NewSessionResponse::new(session_id).config_options(config_options))
1145 }
1146
src/settings.rs
+9 -2
@@ -8,15 +8,18 @@
8 //! Settings today: `local_inference` (whether on-device inference is the
9 //! active mode — the source of truth for the local/cloud toggle, also surfaced
10 //! as a session config option for ACP clients without slash commands, e.g.
11 -//! Xcode) and `[permissions]` (the tool permission policy consumed by
11 +//! Xcode), `[permissions]` (the tool permission policy consumed by
12 //! `crate::permissions`: a default mode for mutating tools plus per-tool
13 -//! overrides).
13 +//! overrides), and `[hooks]` (extensibility hooks for session and tool
14 +//! lifecycle events).
15
16 use std::collections::BTreeMap;
17 use std::path::PathBuf;
18
19 use serde::{Deserialize, Serialize};
20
21 +use crate::hooks;
22 +
23 /// Env override for `local_inference`. When set to a truthy/falsy value it wins
24 /// over the stored file for reads (matching the existing `SIGIT_*` override
25 /// style); it never writes the file.
@@ -129,6 +132,9 @@ pub struct Settings {
132 /// Permission policy for mutating agent tools.
133 #[serde(default)]
134 pub permissions: PermissionSettings,
135 + /// Extensibility hooks for session and tool lifecycle events.
136 + #[serde(default)]
137 + pub hooks: hooks::HookSettings,
138 }
139
140 impl Default for Settings {
@@ -136,6 +142,7 @@ impl Default for Settings {
142 Self {
143 local_inference: default_local_inference(),
144 permissions: PermissionSettings::default(),
145 + hooks: hooks::HookSettings::default(),
146 }
147 }
148 }