Hooks

Hooks let you run a script at specific points in the agent loop — for example, auto-formatting after every file edit, or running a linter before a commit. A hook is a command the platform executes, with the current phase and tool info passed in as environment variables.

Hook phases

Nexrall Code fires hooks at two points:

Phase	When it runs
PreToolUse	Before a tool is executed — can inspect (or veto) the call.
PostToolUse	After a tool completes — can react to the result (format, lint, notify).

Configuring hooks

Hooks are configured in settings.json under a hooks key, keyed by phase:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write", "command": "./.nexrall/hooks/lint-before-write.sh" }
    ],
    "PostToolUse": [
      { "matcher": "*", "command": "npx prettier --write ." }
    ]
  }
}

Each entry names a matcher (which tools it applies to) and a command (the script to run). Plugins can also ship hooks via a hooks.json (or hooks/hooks.json), and hook arrays are concatenated across enabled plugins — see Plugins.

Environment available to the hook

When a hook command runs, the platform sets these variables so the script knows what triggered it:

Variable	Value
NEXRALL_HOOK_PHASE	PreToolUse or PostToolUse
NEXRALL_TOOL_NAME	The tool being invoked
NEXRALL_TOOL_INPUT	The tool's input, JSON-encoded

These are the "Injected into hooks" variables described in Environment variables.

Security

Hooks run arbitrary commands as part of your agent sessions, so they're a trust boundary:

• Plugins that define hooks require explicit confirmation before install — this can't be bypassed with --yes (see Plugins).
• A hook you write yourself should be treated like any other script in your repo — it runs with your user's privileges.

Next steps

• Environment variables — the injected NEXRALL_HOOK_PHASE / NEXRALL_TOOL_* variables.
• Plugins — how plugins bundle and merge hooks.
• Agent SDK — pluginHooks in the npm package.