AGENT SKILL

hook-profile-gating

Runtime gate hooks via OCTO_HOOK_PROFILE (minimal|standard|strict) and OCTO_DISABLED_HOOKS (comma-separated ids) — disable noisy hooks without editing hook files. Use when onboarding a new arm, debugging a runaway hook, or running a low-context session where the full hook stack is overhead. Always-on hooks (leak-guard, secret-scan, hooks-drift) cannot be disabled via env — that's by design. Pattern adopted from affaan-m/ECC.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 18
Forks
6

01 前言 Front Matter

name
hook-profile-gating
metadata
{ "type": "runtime-pattern", "origin": "repo-deep-learn — affaan-m/ECC scripts/lib/hook-flags.js (2026-05-28)" }
description
Runtime gate hooks via OCTO_HOOK_PROFILE (minimal|standard|strict) and OCTO_DISABLED_HOOKS (comma-separated ids) — disable noisy hooks without editing hook files. Use when onboarding a new arm, debugging a runaway hook, or running a low-context session where the full hook stack is overhead. Always-on hooks (leak-guard, secret-scan, hooks-drift) cannot be disabled via env — that's by design. Pattern adopted from affaan-m/ECC.

02 资源文件 1

03 SKILL.md 正文

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:

Var Values Default Effect
OCTO_HOOK_PROFILE minimal | standard | strict standard bulk gate by profile
OCTO_DISABLED_HOOKS id1,id2,... (comma-separated) empty per-hook off-switch

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:
    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)
    
  3. Decide if it's always_on or strict_only. Default (neither) = runs in standard+strict, skipped in minimal.
  4. 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

04 同仓库更多 Skills

CarlosCaPe
CarlosCaPe/octorato

yeet

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

★ 18
CarlosCaPe
CarlosCaPe/octorato

wrangler

Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

★ 18
CarlosCaPe
CarlosCaPe/octorato

workspace-skill-discovery

Discover and include ALL skills across the workspace — not just global ones. Use at the start of every session or when the user asks about available skills. Ensures project-level skills (under .claude/skills/ or skills/ in any repo) are never missed.

★ 18
CarlosCaPe
CarlosCaPe/octorato

workers-best-practices

Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

★ 18
CarlosCaPe
CarlosCaPe/octorato

winui-app

Create, build and design WinUI 3 desktop apps with C# and the Windows App SDK following Microsoft's official guidance and CommunityToolkit. Covers XAML, navigation, theming, accessibility and deployment.

★ 18
CarlosCaPe
CarlosCaPe/octorato

windows-brain-script-portability

Scripts in ~/.claude/scripts/ that run on a Windows brain: use the python3.cmd shim and not bare python3, and reconfigure stdout to UTF-8 if you print symbols. Use it when writing a brain script or triaging a Windows-only crash.

★ 18