Hooks for programs
A hook is a command that Syntic Code runs when an event happens, for example just before a tool runs, or at session start. Hooks are configured in settings files; this page describes how a hook is run and what it can send back, which matters when your own program depends on the outcome.
For writing hooks and worked examples, see the hooks guide. For every event and field, see the hooks reference.
What a command hook receives
A command hook gets a JSON description of the event on standard input. It always carries the event name and the session id. Tool events add the tool’s name and input.
#!/bin/sh
file=$(jq -r '.tool_input.file_path // empty')
echo "edited: $file" >> ~/.syntic/edit-log.txtThe hook runs in bash by default. Set "shell": "powershell" on a hook to run it under PowerShell on Windows.
Timeouts
Each command hook has a time limit, 60 seconds by default. Set "timeout" on the hook to change it, in seconds. When the limit passes, the hook’s whole process group is stopped, so a hook that spawns children does not leave them running.
What a hook can send back
| Exit code | Effect |
|---|---|
0 | The hook passed. Standard output is read as an optional JSON answer. |
2 | The hook blocks the action. Its standard error is the reason, and the agent sees it. |
| Any other code | A non-blocking error. It is reported and the session continues. |
A hook that cannot start, times out, or prints an answer that cannot be read is skipped. It never blocks an action just by failing.
For finer control, a hook can print one JSON object, for example a permissionDecision on a PreToolUse event. The fields each event accepts are listed in the hooks reference.
Several hooks
Every hook whose matcher fits an event runs, in the order the settings list them. One hook failing does not stop the hooks after it, and a blocking exit from one hook does not stop the others from running.
Hooks and permissions
Hooks work inside the permission system:
- A deny rule always wins. A hook cannot allow what a rule denies.
- An ask rule always asks, even when a hook answers allow. In a non-interactive run, the ask is refused.
- Otherwise a hook’s
denyrefuses the call,askforces a question, andallowskips the question the mode would have asked.
Turning hooks off for a run
| Switch | Effect |
|---|---|
--bare | No hooks from settings files for this run. |
SYNTIC_DISABLE_HOOKS=1 | No hooks at all. |
Organization policy can also restrict hooks to managed ones only. See Managed settings.
Keep hook scripts short and deterministic. A hook runs on every matching event, so a slow hook slows every tool call it matches.