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.

Cusp'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 Cusp.

ConfigurationCopy Anchor Link

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|MultiEdit|Write|ApplyPatch",
        "hooks": [
          { "type": "command", "command": "bunx biome format --write \"$CUSP_PROJECT_DIR\"", "timeout": 30 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.cusp/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.

MatchersCopy Anchor Link

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 ifCopy Anchor Link

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.

Handler typesCopy Anchor Link

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

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

InputCopy Anchor Link

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:

OutputCopy Anchor Link

Exit codesCopy Anchor Link

JSON outputCopy Anchor Link

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 defer, which beats ask, which beats allow. A hook's deny holds in every permission mode, including bypass. Context from multiple hooks is combined in configuration order. Each text field is capped at 10,000 characters.

EventsCopy Anchor Link

ExamplesCopy Anchor Link

Block edits to generated filesCopy Anchor Link

#!/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|MultiEdit|Write|ApplyPatch|EditLines",
        "hooks": [{ "type": "command", "command": "${CUSP_PROJECT_DIR}/.cusp/hooks/no-generated.sh" }]
      }
    ]
  }
}

Keep going until tests passCopy Anchor Link

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 startCopy Anchor Link

{
  "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 workCopy Anchor Link

{
  "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"
          }
        ]
      }
    ]
  }
}

SafetyCopy Anchor Link

• Hooks run with your user's permissions, outside the 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 turns hooks off.