Hooks

Hooks let you attach your own logic to the agent loop: format a file after every edit, block a command your team never wants run, add context when a session starts, or keep the agent working until the tests pass. Unlike instructions, hooks always run. They don't depend on the model remembering to do something.

Nib's hooks use the widely used hook format: the same events, configuration, exit codes and JSON output. Hooks you already have in .claude/settings.json work in Nib, except for two events that never fire (see Events).

ConfigurationСкопировать ссылку на раздел

Hooks live under hooks in any settings file. Each event maps to a list of matcher groups, and each group lists handlers.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|ApplyPatch",
        "hooks": [
          { "type": "command", "command": "bunx biome format --write \"$NIB_PROJECT_DIR\"", "timeout": 30 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.nib/hooks/check-bash.sh" }
        ]
      }
    ]
  }
}

Hooks from every settings level are combined: managed, local, project and user, plus hooks declared by skills and subagents while they're active.

MatchersСкопировать ссылку на раздел

matcher selects which tool calls (or which event subtypes) the group applies to.

• A bare name matches exactly: Bash.
• A list separated by | matches any of them: Edit|Write.
• Anything with regex characters is treated as a regular expression: mcp__github__.*.
• An empty or missing matcher matches everything.

Matchers see canonical tool names. A GPT model's apply_patch call arrives as ApplyPatch, so include it when you match edits.

Narrowing with ifСкопировать ссылку на раздел

A handler can carry an if condition written as a single permission rule. It only runs when the call matches:

{ "type": "command", "command": "./scripts/guard-push.sh", "if": "Bash(git push *)" }

if is evaluated only on tool events: a handler with if on any other event never runs. It matches the way a permission rule does: Bash(rm *) also catches sudo rm … and bash -c 'rm …', Edit(*.ts) also catches Write and a shell redirect into a .ts file, and WebFetch(domain:github.com) matches that host only (write WebFetch(domain:*.github.com) for its subdomains). A rule that doesn't parse doesn't narrow: the hook runs.

One exception: when a tool can't say what a call touched after the call has run, PostToolUse handlers run without checking their if, so such a hook may fire on a call its if would have excluded.

Handler typesСкопировать ссылку на раздел

Common fields on every handler: timeout (seconds), statusMessage (shown while it runs), if, and once (run once, then remove; honored for skill hooks).

Not every type runs on every event. prompt and agent handlers run on the tool events, the prompt events, Stop, SubagentStop, PermissionDenied and the task events; PermissionRequest takes every type but agent; SessionStart and Setup take only command and mcp_tool; the other events take command, http and mcp_tool.

A command hook's line runs in bash (/bin/sh where bash isn't installed) on macOS and Linux, and in Git Bash on Windows, or in PowerShell there when Git Bash isn't installed. shell: "powershell" runs it in PowerShell (pwsh, else Windows PowerShell), and shell: "bash" only in a POSIX shell. With args, command itself runs, with no shell.

async runs a command in the background. With asyncRewake, a background command that exits with code 2 wakes the agent with its output. continueOnBlock makes a prompt hook that blocks return its reason to the agent, which carries on, instead of ending the turn; agent hooks always do.

onFailure: "block" makes a timeout or crash count as a block. By default a failing hook doesn't stop the agent.

InputСкопировать ссылку на раздел

Every hook receives a JSON object. Common fields:

Tool events add tool_name, tool_input and tool_use_id. PostToolUse adds tool_response.

Environment variables for command hooks:

OutputСкопировать ссылку на раздел

Exit codesСкопировать ссылку на раздел

JSON outputСкопировать ссылку на раздел

Print a JSON object on stdout with exit code 0 for finer control:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use the deploy skill instead of calling kubectl directly."
  }
}

When several hooks answer the same event, the strictest wins: for PreToolUse, deny beats ask, which beats allow, and defer means no opinion: it counts only when every hook defers, so one hook's defer never cancels another's ask. A hook's deny holds in every permission mode, including bypass. So does an ask, except that bypass honours it only from your own hooks and your organization's (your user settings, managed settings, the command line, or the program embedding Nib), not from a repository's (its project or local settings), a plugin's, a skill's or an agent's. Context from multiple hooks is combined in configuration order. A text field over 10,000 characters is cut to its first 2,000, with a note saying so.

hookSpecificOutput.sessionTitle, initialUserMessage and reloadSkills (SessionStart, and sessionTitle on UserPromptSubmit too) and the top-level terminalSequence are accepted so existing hooks keep working, but not applied yet. suppressOutput is accepted and has no effect. suppressOriginalPrompt changes nothing: a blocked prompt's notice never repeats the prompt.

EventsСкопировать ссылку на раздел

MessageDisplay and TeammateIdle are accepted in a hooks file so that existing configurations load, but they never fire. If your settings have a hook for either, Nib shows a warning naming it when the session starts.

ExamplesСкопировать ссылку на раздел

Block edits to generated filesСкопировать ссылку на раздел

#!/usr/bin/env bash
path=$(jq -r '.tool_input.file_path // empty')
if [[ "$path" == *"/generated/"* ]]; then
  echo "Files under generated/ are produced by 'bun run codegen'. Edit the schema instead." >&2
  exit 2
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|ApplyPatch|EditLines",
        "hooks": [{ "type": "command", "command": "${NIB_PROJECT_DIR}/.nib/hooks/no-generated.sh" }]
      }
    ]
  }
}

Keep going until tests passСкопировать ссылку на раздел

A Stop hook that blocks with the test output sends the agent back to work:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "out=$(bun test 2>&1) || { echo \"$out\" | tail -40 >&2; exit 2; }", "timeout": 300 }
        ]
      }
    ]
  }
}

The hook exits 0 when the tests pass, so the turn ends normally. If a failure is outside the agent's control, it will keep trying until you interrupt it; combine this with --max-turns in headless runs.

Add context at session startСкопировать ссылку на раздел

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{ "type": "command", "command": "echo \"Open issues assigned to me:\"; gh issue list --assignee @me --limit 5" }]
      }
    ]
  }
}

Ask a model to check the workСкопировать ссылку на раздел

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "The user asked for a change and the agent says it is done. Based on this transcript excerpt, did the agent run the tests and do they pass? $ARGUMENTS"
          }
        ]
      }
    ]
  }
}

SafetyСкопировать ссылку на раздел

• Your hooks run with your user's permissions, outside the sandbox; a Hub extension's hooks run in the extension's sandbox. Review hook scripts in a repository before trusting it.
• In an untrusted workspace, project and local settings can't add hooks.
• Administrators can restrict hooks to managed settings with allowManagedHooksOnly, and restrict HTTP hooks to approved URLs with allowedHttpHookUrls.
• disableAllHooks: true in managed settings turns every hook off. Set anywhere else, it leaves only managed hooks running.