calibrate-hooks

calibrate-hooks — per-feature bundle

You audit and tune hook configurations and hook scripts. Two entry points:

• Direct invocation (/claude-calibration:calibrate-hooks) — audit everything, report findings, propose fixes inline.
• Dispatch from the calibrator — one approved plan row at a time, applied surgically.

The workflow is the same; only the framing differs.

1. Enumerate

bash <BUNDLE>/scripts/enumerate.sh "$PROJECT_DIR"

Yields TSV scope\tpath. Scope is settings (a settings.json with a hooks block — user or project), script (a project-local hook script under .claude/hooks/), script-user (user hook script under ~/.claude/hooks/), or plugin-self (when the project is itself a plugin and ships hooks at <plugin-root>/hooks/).

2. Lint

bash <BUNDLE>/scripts/lint.sh <path …>

Yields TSV path\tsignature\tseverity\tdetail. The signatures this bundle owns (see reference.md):

• hook:matcher-bare-star (MEDIUM)
• hook:exit-1-non-blocking (HIGH)
• hook:remote-untrusted (HIGH)
• hook:duplicate-across-layers (LOW) — only fires when multiple settings files are passed
• hook:not-locally-sourced (LOW)
• hook:heavy-on-pretooluse-heuristic (MEDIUM)
• hook:invalid-json (HIGH)

3. Fix — kind: edit rows

For each finding, the remediation pattern lives in examples/<case>/:

• hook:matcher-bare-star → examples/matcher-bare-star/{before,after}.md. Narrow the matcher to the specific tool(s) (Edit|Write|MultiEdit) plus a path pattern. Bare * on a hot event fires on every tool call.
• hook:exit-1-non-blocking → examples/exit-1-non-blocking/{before,after}.md. Replace exit 1 with exit 2 when the intent is to block; keep exit 1 only for non-blocking warnings. The semantics: exit 0 = pass, exit 1 = non-blocking warning surfaced to the user, exit 2 = block the tool call and surface stderr to Claude.
• hook:remote-untrusted → vendor the script locally under ${CLAUDE_PROJECT_DIR}/.claude/hooks/ or ${CLAUDE_PLUGIN_ROOT}/hooks/. Hooks that curl | sh re-fetch on every fire and are a supply-chain risk.
• hook:heavy-on-pretooluse-heuristic → move the heavy work to a Stop hook (runs at session end) or a manual command. PreToolUse/PostToolUse must stay sub-second.
• hook:not-locally-sourced → point the command at ${CLAUDE_PROJECT_DIR}/... or ${CLAUDE_PLUGIN_ROOT}/... rather than relying on system PATH.
• hook:duplicate-across-layers → delete the duplicate from one layer (usually the user layer defers to project, or vice versa — keep the one closer to the change).
• hook:invalid-json → fix the JSON. Run python3 -m json.tool <settings.json> to find the parse error.