Hooks - BRICKS

Hooks let you run shell commands automatically when specific agent events occur — for example, enforcing coding standards before a tool writes a file, or logging every completed turn. The system follows the same conventions as Claude Code hooks.

Configuration

Hooks are configured in JSON files at two levels:

Scope	File	Managed via
Global	`~/.bricks-project-desktop/hooks.json`	Settings > Agent > Hooks settings > Open
Project	`<project>/.bricks/hooks.json`	Edit directly

Both files are merged additively. Identical handlers (same event, matcher, and command) are deduplicated.

Config format

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash|write_file",
        "hooks": [
          {
            "type": "command",
            "command": "node check.js",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

The top-level hooks wrapper is optional — you can place event keys at the root. Each event key maps to an array of rule objects. A rule has:

matcher — which tool or trigger to match (see Matchers)
hooks — an array of handler objects, each with:
- type — always "command"
- command — the shell command to run
- timeout — per-handler timeout in seconds (default 60)

Matchers

Matchers follow Claude Code semantics:

Pattern	Behavior
Empty or `*`	Matches everything
Word characters and `\|` only	Exact pipe-separated list (e.g. `bash\|write_file`)
Anything else	Treated as a regular expression

Events

Event	Matcher value	Can block	Description
`SessionStart`	`startup` \| `resume`	No	Fires when a session starts or resumes
`UserPromptSubmit`	—	Yes	Runs before a user prompt is sent; can reject it
`PreToolUse`	tool name	Yes	Runs before a tool call; can deny it
`PostToolUse`	tool name	No	Runs after a tool call; can append feedback
`Stop`	—	No	Fires when the agent finishes a turn
`SubagentStart`	agent name	No	Fires when a sub-agent spawns
`SubagentStop`	agent name	No	Fires when a sub-agent finishes
`PreCompact`	`manual` \| `auto`	No	Fires before context compaction
`PostCompact`	`manual` \| `auto`	No	Fires after context compaction
`GoalUpdate`	`set` \| `evaluated` \| `complete` \| `cancel`	No	Fires on goal lifecycle changes

Execution protocol

Each matching handler runs through the shell with cwd set to the project path. A JSON payload is passed on stdin containing:

session_id — the current session ID
cwd — the project path
hook_event_name — the event name

Plus per-event fields such as tool_name, tool_input, tool_response, prompt, trigger, agent_type, and goal. The following environment variables are set:

Variable	Value
`BRICKS_PROJECT_DIR`	Project path
`BRICKS_SESSION_ID`	Current session ID
`BRICKS_HOOK_EVENT`	Event name

Exit codes

Exit code	Behavior
`0`	Success — stdout may carry a JSON decision (see below)
`2`	Block — stderr is used as the block reason
Any other	Non-blocking failure — logged and ignored

Timeouts are also treated as non-blocking failures.

Decision output

On exit code 0, stdout may contain a JSON object:

Block a tool call (PreToolUse): {"decision": "block", "reason": "..."}
Deny with reason (PreToolUse): {"hookSpecificOutput": {"permissionDecision": "deny", "permissionDecisionReason": "..."}}
Append feedback (PostToolUse): {"additionalContext": "..."}

All matching handlers run in parallel. If any handler blocks, the tool call or prompt is denied and all block reasons are joined.

Scope

Hooks apply across all agent contexts:

Main agent tool calls
Sub-agent tool calls (with agent_type in the payload)
GUI tool calls
ACP tool calls

UserPromptSubmit only gates user-typed prompts — goal continuations and internal session messages are not intercepted. Hook engine failures never propagate into the agent loop.

Examples

Require a linter check before file writes

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/lint-check.js"
          }
        ]
      }
    ]
  }
}

Log every completed turn

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Turn completed\" >> /tmp/ctor-events.log"
          }
        ]
      }
    ]
  }
}

Data storage

Data	Location
Global hooks config	`~/.bricks-project-desktop/hooks.json`
Project hooks config	`<project>/.bricks/hooks.json`

​Configuration

​Config format

​Matchers

​Events

​Execution protocol

​Exit codes

​Decision output

​Scope

​Examples

​Require a linter check before file writes

​Log every completed turn

​Data storage