Hooks

Hooks let you run commands or inject prompts automatically when specific events happen during a Nyzhi session. Use them to auto-format files after edits, run tests after each turn, or enforce policies before tool execution.

Quick Example

Auto-format Rust files after every edit:

[[agent.hooks]]
event = "after_edit"
command = "cargo fmt --all"
pattern = "*.rs"
timeout = 60

Hook Configuration

Hooks are defined as TOML array entries under [[agent.hooks]]:

[[agent.hooks]]
event = "after_turn"        # when to trigger (required)
hook_type = "command"        # "command" | "prompt" | "agent" (default: "command")
command = "npm test"         # shell command to run
pattern = ""                 # file pattern filter (for edit events)
tool_name = ""               # tool name filter (comma-separated)
block = false                # block execution on non-zero exit?
timeout = 30                 # seconds before timeout
prompt = ""                  # text to inject (for prompt/agent types)
instructions = ""            # alternative to prompt
tools = []                   # tools available to agent hooks
model = ""                   # model override for agent hooks

Events

Every hook needs an event — the moment it fires:

Hook Types

Command Hooks

Run a shell command. The most common type:

[[agent.hooks]]
event = "after_edit"
hook_type = "command"
command = "prettier --write {file}"
pattern = "*.ts"

The command receives JSON context on stdin for event-driven hooks. Returns stdout, stderr, and exit code.

Prompt Hooks

Inject text into the conversation after an event:

[[agent.hooks]]
event = "after_turn"
hook_type = "prompt"
prompt = "Before finalizing, confirm tests and lint were run."

If a command is also set, its output is appended as context.

Agent Hooks

Emit structured instructions for the agent:

[[agent.hooks]]
event = "post_tool_use"
hook_type = "agent"
tool_name = "git_commit"
instructions = "After committing, check that CI would pass by running the test suite."

Filtering

File Pattern Filter

Only trigger for matching files:

[[agent.hooks]]
event = "after_edit"
command = "cargo fmt --all"
pattern = "*.rs"

Supports *.ext suffix matching and substring matching.

Tool Name Filter

Only trigger for specific tools:

[[agent.hooks]]
event = "pre_tool_use"
tool_name = "git_commit,git_checkout"
command = "scripts/policy-check.sh"
block = true

Comma-separated list of tool names.

Blocking Hooks

When block = true on a pre_tool_use hook, a non-zero exit code blocks the tool from executing:

[[agent.hooks]]
event = "pre_tool_use"
tool_name = "bash"
command = "scripts/check-safe-command.sh"
block = true
timeout = 10

This is powerful for enforcing security policies or preventing dangerous operations.

Team Feedback Hooks

For teammate_idle and task_completed events, exit code 2 has special meaning:

• teammate_idle — exit code 2 means “keep working” with stderr as the follow-up instruction
• task_completed — exit code 2 means “reject completion” with stderr as feedback

[[agent.hooks]]
event = "task_completed"
command = "scripts/verify-task.sh"

Practical Examples

Run Tests After Every Turn

[[agent.hooks]]
event = "after_turn"
command = "npm test -- --bail"
timeout = 120

Format on Save

[[agent.hooks]]
event = "after_edit"
command = "prettier --write {file}"
pattern = "*.{ts,tsx,js,jsx}"

[[agent.hooks]]
event = "after_edit"
command = "cargo fmt --all"
pattern = "*.rs"

Block Dangerous Git Operations

[[agent.hooks]]
event = "pre_tool_use"
tool_name = "git_commit"
command = "scripts/pre-commit-check.sh"
block = true
timeout = 30

Quality Reminder After Turn

[[agent.hooks]]
event = "after_turn"
hook_type = "prompt"
prompt = "Check: did you run tests? Did you check for type errors? Did you update docs?"

Best Practices

• Keep hooks fast and deterministic — slow hooks degrade the interactive experience
• Set explicit timeout values for anything that touches the network
• Use block sparingly — only for hard policy gates
• Filter by tool_name or pattern to avoid noisy global hooks
• Global hooks run before project hooks (they’re concatenated)

Next Steps

• Configuration — hook config reference
• Verification — automated check system
• Commands — custom slash commands