Hooks reference

This page lists every hook event Syntic Code fires, what each one sends to your hook, and what your hook can send back. For a gentler introduction with worked examples, start with the hooks guide.

Configuration format

Hooks live under a hooks key in any settings file, grouped by event name. Each event holds a list of matcher groups; each group holds a list of hooks.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./scripts/guard-shell.sh", "timeout": 15 }
        ]
      }
    ]
  }
}

Hooks are read from ~/.syntic/settings.json, ~/.syntic/hooks.json, the project’s .syntic/settings.json, .syntic/hooks.json and .syntic/settings.local.json, your organization’s managed policy, and every enabled plugin’s hooks/hooks.json. All of them are combined. Project files only count once you trust the folder. An entry Syntic Code cannot parse is skipped; the rest still load.

Hook fields

Matchers

The matcher on a group is tested against one field of the event (listed per event below).

• Missing, empty or * matches everything.
• Letters, digits, _ and | only: an exact match against one of the |-separated names, for example Edit|Write.
• Anything else is treated as a regular expression that must match the whole value, for example mcp__github__.*. An invalid expression matches nothing.
• Events without a matcher field run every group, whatever its matcher says.

Common input fields

Each hook gets one JSON object. Command hooks read it on standard input, http hooks receive it as the request body, and prompt/agent hooks see it in place of $ARGUMENTS.

Events

Tool events

Tool names are the ones on the Tools page; MCP tools are named mcp__<server>__<tool>.

Prompt and turn events

stop_hook_active is true when a Stop hook already sent the agent back this turn. Use it to avoid sending it back forever. background_tasks lists running background commands and agents; session_crons lists this project’s scheduled prompts.

Session events

A FileChanged group’s matcher also tells Syntic Code which file names to watch, for example "matcher": ".envrc|.env". Hooks can add more files with watchPaths.

Compaction events

Subagent, task and team events

MCP events

Environment variables

Command hooks inherit your environment, minus Syntic Code’s own sign-in credentials, plus:

Output

Exit codes (command hooks)

A hook that cannot start, runs past its timeout, or (for http) cannot be reached contributes nothing and never blocks. When a hook times out, its whole process group is stopped.

An http hook’s answer is the response body, in the same JSON shape a command prints. A non-2xx status is reported as a non-blocking error. A prompt or agent hook answers {"ok": true} or {"ok": false, "reason": "…"}; false blocks.

JSON fields

Print one JSON object on standard output for finer control.

hookSpecificOutput fields

What a block does

StopFailure, SessionEnd, PreCompact, PostCompact, InstructionsLoaded, PermissionDenied and Notification only observe; their answers change nothing.

Hooks and permission rules

From strongest to weakest:

1. A deny rule in settings always refuses the call.
2. An ask rule always shows the dialog, even when a hook says allow.
3. A PreToolUse hook’s deny refuses the call.
4. A PreToolUse hook’s ask forces the dialog.
5. A PreToolUse hook’s allow skips the dialog the mode would have shown.
6. Otherwise the normal flow decides. Before a dialog appears, PermissionRequest hooks may answer it.

Limits

Turning hooks off

Debugging

• /hooks lists every configured hook with its number and source file.
• syntic --debug hooks logs each hook run and its output.
• In -p runs, --output-format stream-json --verbose --include-hook-events reports each hook as it starts and finishes.
• Test a script by hand: echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh; echo $?.