Hooks

What are hooks?

Hooks are shell commands that run at specific points in SANDCODE’s lifecycle. They let you automate tasks like running tests after edits, formatting code on save, or validating changes before they’re applied.

Hook types

Hook	When it fires
preToolUse	Before a tool is executed
postToolUse	After a tool finishes
notification	When a notification is sent
stop	When the conversation ends

Configuration

Add hooks in your project’s .sandcode/settings.json:

{
  "hooks": {
    "postToolUse": "npm test",
    "preToolUse": "npm run lint"
  }
}

Hook environment

Hooks receive context via environment variables:

• TOOL_NAME — the tool being used (e.g., “Edit”, “Bash”)
• TOOL_INPUT — JSON string of the tool’s input
• TOOL_OUTPUT — JSON string of the tool’s output (post hooks only)

Exit codes

• Exit 0 — continue normally
• Exit 2 — block the tool execution (pre hooks only)
• Any other code — warning logged, execution continues

Plugin hooks

Plugins can define their own hooks in the plugin manifest. These use ${SANDCODE_PLUGIN_ROOT} to reference the plugin directory:

{
  "hooks": {
    "postToolUse": "${SANDCODE_PLUGIN_ROOT}/hooks/format.sh"
  }
}