Hooks Reference

This page specifies the exact JSON contract for Syntic Code hooks. For the concepts and use cases, see the hooks guide; here we document the events, the payload passed to your command on stdin, and how Syntic Code interprets your command’s response. Hooks are configured under the hooks key of .syntic/settings.json.

Configuration schema

Each event maps to a list of matchers, each pairing a matcher pattern against tool names with one or more command strings to run:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash|write",
        "command": "./scripts/policy-check.sh",
        "timeout": 5000
      }
    ]
  }
}

The matcher is a regular expression tested against the tool name (omit it or use "*" to match all). timeout is optional milliseconds after which the hook is killed and treated as a failure.

Stdin payload

Syntic Code invokes your command and writes a JSON object to its stdin describing the event:

Field	Type	Description
`event`	string	The lifecycle event, e.g. `PreToolUse`.
`session_id`	string	Identifier of the current session.
`tool_name`	string	Name of the tool involved (tool events only).
`tool_input`	object	Arguments passed to the tool.
`tool_result`	object	Result of the tool (PostToolUse only).
`cwd`	string	The session working directory.

Response contract

Your command signals its decision through its exit code and output. Exit 0 allows the action; on PreToolUse and Stop, a non-zero exit blocks it. Anything written to stderr is returned to Amara as feedback, so a blocking hook should explain why it blocked. For richer control, a hook may print a JSON object to stdout with a decision field (allow, deny, or ask) and an optional message, which overrides the exit-code behavior. Events fire for SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, and SessionEnd.

Checkpointing Plugins Reference