Hook-Intercept-Block Pattern

Pattern for implementing slash commands that execute entirely in the hook handler, bypassing the Claude API call entirely.

Why Use This Pattern

• No API cost: Commands execute in Go, no Claude API call
• Faster: Direct execution vs markdown parsing + API round trip
• Deterministic: No model variance - same input, same output

How It Works

User types: /bumper-reset
    ↓
UserPromptSubmit hook fires
    ↓
prompt_handler.go matches regex: ^/(?:claude-bumper-lanes:)?bumper-reset\s*$
    ↓
handleReset() executes Go logic
    ↓
Returns JSON to stdout: {"decision":"block","reason":"Baseline reset. Score: 0/400"}
    ↓
Claude Code shows "reason" to user, skips API call

The Confusing Naming

Claude Code's hook response API uses counterintuitive terminology:

decision: "block"

decision: "continue"

reason: "..."

Key insight:

block

Implementation Components

1. Hook config (

   hooks.json

   ): Routes UserPromptSubmit to handler binary
2. Handler (

   internal/hooks/prompt_handler.go

   ): Regex matching + dispatch
3. Command stubs (

   commands/*.md

   ): MUST exist for

   /help

   discovery (body ignored)

Adding a New Command

Step 1: Add Regex Pattern

In

prompt_handler.go

var newCmdPattern = regexp.MustCompile(`^/(?:claude-bumper-lanes:)?bumper-foo\s*(.*)$`)

The

(?:claude-bumper-lanes:)?

Step 2: Add Dispatch

In

HandlePrompt()

if m := newCmdPattern.FindStringSubmatch(prompt); m != nil {
    return handleFoo(sessionID, strings.TrimSpace(m[1]))
}

Step 3: Implement Handler

Use the helper functions for DRY session management:

func handleFoo(sessionID, args string) int {
    sess := loadSessionOrBlock(sessionID)
    if sess == nil {
        return 0
    }

    // ... your logic here ...

    if !saveOrBlock(sess) {
        return 0
    }

    blockPrompt("Success message")
    return 0
}

Step 4: Create Command Stub

Create

commands/bumper-foo.md

---
description: Does the foo thing
argument-hint: <optional-args>
---

This command is handled by the hook system.

The markdown body is ignored - the hook handles everything. The file MUST exist for the command to appear in

/help

Step 5: Rebuild

just build-bumper-lanes

Helper Functions

Two helpers reduce boilerplate:

loadSessionOrBlock

func loadSessionOrBlock(sessionID string) *state.SessionState

Returns session state or nil. If nil, error already shown to user via

blockPrompt()

saveOrBlock

func saveOrBlock(sess *state.SessionState) bool

Returns true on success. If false, error already shown to user via

blockPrompt()

JSON Response Format

The

UserPromptResponse

type UserPromptResponse struct {
    Decision string `json:"decision,omitempty"`
    Reason   string `json:"reason,omitempty"`
}

Output via

blockPrompt()

func blockPrompt(reason string) {
    resp := UserPromptResponse{
        Decision: "block",
        Reason:   reason,
    }
    out, _ := json.Marshal(resp)
    fmt.Println(string(out))
}

Existing Commands Using This Pattern

All bumper-lanes slash commands use hook-intercept-block:

/bumper-reset

handleReset()

/bumper-pause

handlePause()

/bumper-resume

handleResume()

/bumper-view

handleView()

/bumper-config

handleConfig()

Debugging Tips

1. Command not recognized: Check regex pattern matches user input exactly
2. No output shown: Ensure

   blockPrompt()

   is called and JSON printed to stdout
3. Command not in /help: Verify

   commands/*.md

   stub file exists
4. Binary not updated: Run

   just build-bumper-lanes

   after changes