Hooks

The hook system lets you run shell commands at specific points in the engine’s execution lifecycle. Every hook invocation is logged to the hook_invocations table with full input, output, and timing.

How Hooks Work

Hooks are defined as an array in your settings (.ona/settings.json, .claude/settings.local.json, or via /config). When an event fires, the engine:

1. Filters hooks by hook_event_name
2. Deduplicates adjacent identical hooks
3. For each matching hook, checks the matcher against event-specific fields
4. Spawns the hook command as a child process
5. Passes event context as JSON on stdin
6. Captures stdout (up to 4 MB), stderr, and exit code
7. Persists everything to hook_invocations
8. Processes the result based on the event type

Hook Config Schema

{
  "hooks": [
    {
      "hook_event_name": "PreToolUse",
      "matcher": "Bash",
      "command": "echo $HOOK_INPUT | jq .tool_input.command",
      "shell": "bash",
      "if_condition": ""
    }
  ]
}

Matcher Behavior

The matcher is compared against an event-specific field:

Matcher formats:

• * or empty — matches everything
• Bash — exact match
• Bash|Edit|Write — pipe-delimited list (matches any)
• ^Bash$ — regex

Event Reference

Tool Lifecycle

PreToolUse: Controlling Execution

A PreToolUse hook can influence the tool execution in two ways:

Block the tool — Exit with code 2. The tool call is rejected and the model receives an error:

#!/bin/bash
# Block rm -rf commands
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo "Destructive command blocked by policy" >&2
  exit 2
fi

Influence permission decision — Return JSON on stdout with a permissionDecision:

#!/bin/bash
echo '{"hookSpecificOutput":{"permissionDecision":"deny"}}'

When multiple PreToolUse hooks fire, their permission decisions are merged with a priority ranking: deny > ask > allow > unset. The highest-ranking decision wins. If any hook blocks (exit code 2), remaining hooks are skipped.

Conversation Lifecycle

File & Directory

Worktree

Agent & Task

Stdin Input

Every hook receives a JSON object on stdin with these base fields:

{
  "hook_event_name": "PreToolUse",
  "session_id": "uuid",
  "conversation_id": "uuid",
  "runtime_db_path": "/path/to/db",
  "cwd": "/working/directory"
}

Plus event-specific fields (e.g. tool_name, tool_input, file_path). You can read this with jq or any JSON parser.

Environment Variables

Hook processes inherit the parent environment plus:

Disabling Hooks

Set SDLC_DISABLE_ALL_HOOKS=1 to skip all hooks:

SDLC_DISABLE_ALL_HOOKS=1 node bin/agent.mjs

Timeouts

Example: Block Destructive Commands

{
  "hooks": [
    {
      "hook_event_name": "PreToolUse",
      "matcher": "Bash",
      "command": ".ona/hooks/block-destructive.sh"
    }
  ]
}

.ona/hooks/block-destructive.sh:

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -qE '(rm -rf|drop table|DROP DATABASE)'; then
  echo "Blocked destructive command: $COMMAND" >&2
  exit 2
fi

Example: Notify on File Changes

{
  "hooks": [
    {
      "hook_event_name": "FileChanged",
      "matcher": "*",
      "command": "echo \"$(date): $CLAUDE_PROJECT_DIR\" >> ~/.nehanda-changes.log"
    }
  ]
}