SDKHooks

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.txt

The 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 codeEffect
0The hook passed. Standard output is read as an optional JSON answer.
2The hook blocks the action. Its standard error is the reason, and the agent sees it.
Any other codeA 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 deny refuses the call, ask forces a question, and allow skips the question the mode would have asked.

See Permissions for programs.

Turning hooks off for a run

SwitchEffect
--bareNo hooks from settings files for this run.
SYNTIC_DISABLE_HOOKS=1No 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.