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:

Key insight: block = "handled and done", not "rejected". The command succeeded.

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:)? makes the plugin namespace optional.

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 struct:

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:

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