carloscape/octorato/hook-profile-gating

Hook Profile Gating

Why

Hook stack grows over time. Some hooks are non-negotiable (secret-scan, leak-guard); some are nice-to-have (typecheck, tmux-reminder); some get noisy in specific contexts (onboarding a new arm, debugging the brain itself). Editing settings.json to disable one is heavy. Env-vars give per-session gating.

How

Three env vars + one Python helper:

Profiles:

• minimal — only always_on=True hooks run (leak-guard, secret-scan, hooks-drift). Fastest. Use when sanity-checking a brain change without firing the world.
• standard — default. Everything except strict_only=True hooks.
• strict — everything, including strict_only (slow type-checks, extended security scans).

OCTO_DISABLED_HOOKS overrides everything except always_on=True. You cannot disable the leak-guard via env, ever.

Helper API

scripts/lib/hook_flags.py:

from lib.hook_flags import should_run, profile, is_disabled
# Most common pattern at the top of any hook script:
if not should_run("pre:bash:tmux-reminder"):
    sys.exit(0)
# Always-on:
if not should_run("pre:push:secret-scan", always_on=True):
    sys.exit(0)  # never fires; always returns True
# Strict-only:
if not should_run("post:edit:slow-typecheck", strict_only=True):
    sys.exit(0)
# Read profile directly:
prof = profile()  # 'minimal' | 'standard' | 'strict'

How to port an existing hook

1. Pick a hook id following <phase>:<event>:<short-name> (e.g. pre:bash:tmux-reminder).
2. Add at the very top of the hook script:

``python import sys, pathlib sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "scripts" / "lib")) from hook_flags import should_run if not should_run("<your-id>"): sys.exit(0) ``

1. Decide if it's always_on or strict_only. Default (neither) = runs in standard+strict, skipped in minimal.
2. Document the id in the hook's docstring + a row in ~/.claude/hooks/README.md.

Hooks that don't opt in are always active — porting is incremental, no flag-day required.

Examples

# Onboarding a new arm; minimize noise
export OCTO_HOOK_PROFILE=minimal
ai-pull
 
# Debugging a specific noisy hook
export OCTO_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
ai-push "..."
 
# Pre-merge strict gate (catches everything before going live)
export OCTO_HOOK_PROFILE=strict
node tests/run-all.js

What NOT to do

• Don't make leak-guard env-overridable. It's always_on=True for a reason — public brain.
• Don't gate behavior outside hooks via these env vars. They're hook-runtime only; for runtime behavior in skills/scripts, use the operator-recall pattern (load_config() from a YAML).
• Don't ship a hook without an id. Untrackable disabling = bad ops story.

See also

• [[do-not-ask-to-pause]] — hooks should never prompt the operator; if they need a decision, they're not hooks
• [[dry-run-gate-pattern]] — sibling concept: opt-in for destructive ops, opt-out for hooks via env