Don't let your verification script's full output flow back through a hook

Decide the output budget before you write the body

In practice, the reliable move was to fix a byte budget per hook up front. I first tried to manage this by feel and it did not hold, so it became a number.

Rough values I use now:

The one rule that matters is that higher-frequency hooks get tighter success budgets. Adjust the specific numbers to your workflow. If something that runs on every edit returns 100 bytes, a hundred edits cost you ten thousand bytes — small enough that you will never be surprised by it.

Put a wrapper in front that enforces the budget

Deciding on a policy is not enough, because check scripts drift toward being chatty. Swap a tool, or watch --verbose quietly become the default, and your assumption breaks without a word. So the budget is enforced by a wrapper, not by the good intentions of the script.

This is the shape I use, rewritten to be generic. Call any check through it and the returned volume stays inside the budget.

#!/usr/bin/env bash
# hook-guard.sh — keep a check command's output inside a byte budget
# usage: hook-guard.sh <budget_bytes> <evidence_dir> -- <check command...>
set -uo pipefail
 
BUDGET="$1"; shift
EVIDENCE_DIR="$1"; shift
[ "${1:-}" = "--" ] && shift
 
mkdir -p "$EVIDENCE_DIR"
STAMP="$(date +%Y%m%d-%H%M%S)-$$"
EVIDENCE="${EVIDENCE_DIR}/${STAMP}.log"
 
# Send stdout and stderr to the evidence file; nothing reaches the conversation yet
"$@" > "$EVIDENCE" 2>&1
STATUS=$?
 
TOTAL_BYTES=$(wc -c < "$EVIDENCE" | tr -d ' ')
TOTAL_LINES=$(wc -l < "$EVIDENCE" | tr -d ' ')
 
if [ "$STATUS" -eq 0 ]; then
  # On success, state the fact and nothing more — not even the evidence path
  echo "check ok (${TOTAL_LINES} lines suppressed)"
  exit 0
fi
 
# Only on failure do we spend the budget on actual content
head -c "$BUDGET" "$EVIDENCE"
if [ "$TOTAL_BYTES" -gt "$BUDGET" ]; then
  printf '\n--- truncated: %s of %s bytes shown, %s lines total ---\n' \
    "$BUDGET" "$TOTAL_BYTES" "$TOTAL_LINES"
  printf 'full log: %s\n' "$EVIDENCE"
fi
exit "$STATUS"

The call site looks like this:

# command invoked from a hook entry in settings.json
~/bin/hook-guard.sh 1500 ~/.cache/hook-evidence -- \
  python3 tools/frontmatter_check.py "$CLAUDE_FILE_PATH"

Why it is written this way

Three details, each one learned the hard way.

Output goes to a file before any decision is made. Truncating through a pipe kills the writing process with SIGPIPE, and the exit status stops matching reality — a passing check reported as failed, or the reverse. That confusion cost me real time, so the wrapper takes the plain route and writes to disk once.

On success, the evidence path is not printed. It used to be. It felt helpful. But on a high-frequency hook, that one line of path accumulates on every single run, and since the check passed, nobody ever opens the file. Returning something you know will never be read is just a subscription to debt.

When output is truncated, the totals always come along. A bare head -c leaves the reader unable to tell whether they are looking at everything or at a fragment — and a fragment mistaken for the whole leads somewhere wrong. "1,500 of 42,280 bytes shown, 398 lines total" removes the ambiguity entirely. Truncating is fine. Truncating silently is not.

What to keep and what to drop, in order

When the budget is exceeded, what goes first? Deciding this in advance keeps the implementation from wandering. My order:

1. Total violation count — one versus two hundred changes the entire response
2. The first three to five representative violations — enough to see the shape of the fix
3. Breakdown by violation type — distinguishes "one cause, 200 times" from "200 different problems"
4. Path to the evidence file — the door back to the full listing
5. Everything else — not returned

Items 1 and 2 usually settle the next move on their own. Item 3 earns its place when the count is high and you want a single sweeping fix.

Put the other way around: a hook that returns item 5 is almost certainly wasting its budget. If 200 violations share one cause, 199 of them say nothing the first one did not already say.

Exit codes and output volume are separate design axes

One more distinction worth making explicit. Exit status and output size are independent, and all four combinations have legitimate uses.

The quadrant people miss is the top right: passing, and long. Nothing failed, so nobody investigates. No error appears anywhere. And it removes a slice of the context window on every run, reliably. When things get slow, the hook to suspect first is not the one that failed — it is the one that has been quietly succeeding.

I lost real time reading failure logs for exactly this reason. The culprit had never failed once.

Measure your own hooks for one week

Before changing any design, it helps enormously to turn the present state into numbers. Here is the smallest instrument that does it.

#!/usr/bin/env bash
# hook-meter.sh — wrap an existing hook and record only its output volume
# usage: hook-meter.sh <hook_name> -- <original command...>
set -uo pipefail
 
NAME="$1"; shift
[ "${1:-}" = "--" ] && shift
 
LEDGER="$HOME/.cache/hook-meter.tsv"
mkdir -p "$(dirname "$LEDGER")"
 
OUT="$("$@" 2>&1)"
STATUS=$?
 
printf '%s\t%s\t%s\t%s\t%s\n' \
  "$(date +%Y-%m-%dT%H:%M:%S)" \
  "$NAME" \
  "$STATUS" \
  "$(printf '%s' "$OUT" | wc -c | tr -d ' ')" \
  "$(printf '%s' "$OUT" | wc -l | tr -d ' ')" \
  >> "$LEDGER"
 
printf '%s' "$OUT"
exit "$STATUS"

After a week, total it up per hook.

awk -F'\t' '
  { bytes[$2] += $4; runs[$2] += 1; if ($3 != 0) fails[$2] += 1 }
  END {
    printf "%-28s %8s %10s %10s %8s\n", "hook", "runs", "total_B", "avg_B", "fails"
    for (h in bytes)
      printf "%-28s %8d %10d %10.1f %8d\n", h, runs[h], bytes[h], bytes[h]/runs[h], fails[h]+0
  }
' ~/.cache/hook-meter.tsv | sort -k3 -nr

Read the total column, not the average. Two hundred bytes per run becomes sixty thousand if it fires three hundred times a day. Two thousand bytes once per session is not worth a thought. Frequency multiplied by volume is what your conversation is actually paying.

In my case the top of that list was the check I had been calling "the light one." I had been looking only at the per-run number and feeling reassured by it.

One next step

Just one thing is enough. Take the hook that fires most often, and cut its success output down to a single line.

The question that decides what can go: does this line change the next action anyone takes? If it does not, it does not belong in the conversation.

I have spent a lot of time making the net finer. But a fine net attached to a verbose report ends up slowing the very judgment it was meant to sharpen. The checks I trust most now are the ones that pass in silence.

Thank you for reading. If you measure your hooks and the ranking surprises you, that surprise is where to start.