@sigitcodereview / sigit
Code Commits Issues Pulls Cloud Agent CI/CD
feature/hooks
claude/github-issue-40-0au5ua claude/linked-issue-acp-tui-u4vvpa claude/minor-release-cut-vkugow claude/sigit-acp-local-chat-cx6380 claude/sigit-cloud-agent-expansion-reox0a claude/tool-permission-system claude/zen-feynman-0u78dk development feature/acp-cancel-request feature/acp-session-list-cursor feature/acp-v1-conformance feature/agent-tools-multiedit-glob-todos-remember feature/cargo-workspace feature/hooks feature/load-local-model-explicitly feature/sigit-agent-profile feature/sigit-code-cloud feature/xcode-mcp-server fix/acp-replay-loaded-session-history fix/acp-replay-reasoning-and-attachments fix/dsml-doubled-bar-markers main release/v1.5.10 release/v1.5.6 release/v1.6.1
md 92 lines 3.22 KB
Rendered Raw
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 Every `{var}` value is quote-escaped for the platform shell before it's spliced
40 into the command line, so a directory name or an MCP-server-supplied tool name
41 that happens to contain shell metacharacters is always treated as literal text,
42 never executed. Windows `cmd.exe` quoting is best-effort (`cmd` has no fully
43 safe quoting story); the same values are also exported as environment
44 variables — `SIGIT_HOOK_CWD`, `SIGIT_HOOK_SESSION_ID`, `SIGIT_HOOK_TOOL_NAME`,
45 `SIGIT_HOOK_TOOL_ARGS_LEN`, `SIGIT_HOOK_TOOL_RESULT_LEN` — and reading those
46 in your script instead of `{var}` sidesteps quoting entirely on any platform.
47
48 ## Examples
49
50 ### Log all tool usage to a file
51
52 ```toml
53 [hooks]
54 pre_tool_use = ["echo '[{tool_name}]' >> /tmp/sigit-tools.log"]
55 post_tool_use = ["echo ' → {tool_result_len} bytes' >> /tmp/sigit-tools.log"]
56 ```
57
58 ### Send notifications
59
60 ```toml
61 [hooks]
62 session_start = ["notify-send 'siGit started in {cwd}'"]
63 ```
64
65 ### Build on session start
66
67 ```toml
68 [hooks]
69 session_start = ["cd {cwd} && cargo build"]
70 ```
71
72 ### Track metrics
73
74 ```toml
75 [hooks]
76 pre_tool_use = ["echo {tool_name} | tee -a ~/.sigit/tool_usage.txt"]
77 post_tool_use = ["wc -c <<< {tool_result_len} >> ~/.sigit/result_sizes.txt"]
78 ```
79
80 ## Notes
81
82 - Hooks are optional. When none are configured, each tool call still does one
83 lightweight settings-file read to check for that; there is no shell process
84 spawned and no other measurable overhead.
85 - Hook failures (non-zero exit codes) are logged as warnings but do not interrupt the session.
86 - Hooks are run synchronously, so slow hooks will impact agent responsiveness — this applies
87 in the interactive TUI too, not just ACP/headless mode.
88 - `PreToolUse` and `PostToolUse` hooks fire in every mode (TUI, ACP, headless) and for every
89 call to the shared tool-execution path — including tool calls made by a `task` subagent, not
90 just the top-level agent.
91 - `SessionStart` hooks currently only fire on ACP session lifecycle events (new/load/fork
92 session). The interactive TUI does not have an equivalent session-start hook point yet.