From e7d800f053048bd5a4c86e0092e90a1ad5f84c47 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 26 Oct 2026 17:44:17 +0100 Subject: [PATCH] feat(hooks): InstructionsLoaded logger, the proof channel for path rules --- hooks/instructions-loaded.sh | 19 +++++++++++++++++++ lib/tests/project-rules.test.sh | 24 ++++++++++++++++++++++++ settings.json | 11 +++++++++++ 3 files changed, 54 insertions(+) create mode 100755 hooks/instructions-loaded.sh diff --git a/hooks/instructions-loaded.sh b/hooks/instructions-loaded.sh new file mode 100755 index 0000000..30dd8d8 --- /dev/null +++ b/hooks/instructions-loaded.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# hooks/instructions-loaded.sh — InstructionsLoaded hook: one JSON line per +# instruction file the engine loads, into +# ~/.claude/logs/instructions-loaded.jsonl. The proof channel for +# path-scoped rules (BDR-125 phase 0): a rule that loaded shows +# `load_reason: path_glob_match`, the file that triggered it, and the +# session or sub-agent that loaded it. Never blocks, never prints to +# stdout (stdout reaches the model), exits 0 whatever happens. Rotates to +# .1 above 5 MB. CLAUDE_INSTRUCTIONS_LOG overrides the path (tests). +log="${CLAUDE_INSTRUCTIONS_LOG:-$HOME/.claude/logs/instructions-loaded.jsonl}" +command -v jq >/dev/null 2>&1 || exit 0 +mkdir -p "$(dirname "$log")" 2>/dev/null || exit 0 +if [ -f "$log" ] && [ "$(wc -c < "$log")" -gt 5242880 ]; then + mv -f "$log" "$log.1" 2>/dev/null +fi +jq -c --arg ts "$(date -u +%FT%TZ)" '{ts: $ts, session_id, agent_id, + agent_type, cwd, file_path, memory_type, load_reason, globs, + trigger_file_path}' >> "$log" 2>/dev/null +exit 0 diff --git a/lib/tests/project-rules.test.sh b/lib/tests/project-rules.test.sh index a94d5dd..2b636b9 100644 --- a/lib/tests/project-rules.test.sh +++ b/lib/tests/project-rules.test.sh @@ -150,5 +150,29 @@ check T9b-unmatched-glob-rc "$?" 2 check T9c-nothing-written "$([ -e .claude/rules/beta.md ] && echo yes || echo no)" no check T9d-beta-still-there "$(grep -c '^## Beta' CLAUDE.md)" 1 +# T10 the hook appends one jq line, prints nothing, never fails +HOOK="$ROOT/hooks/instructions-loaded.sh" +LOG="$FIX/il.jsonl" +IN='{"hook_event_name":"InstructionsLoaded","session_id":"s1","agent_id":"a1","agent_type":"general-purpose","cwd":"/p","file_path":"/p/.claude/rules/x.md","memory_type":"Project","load_reason":"path_glob_match","globs":["src/**"],"trigger_file_path":"/p/src/a.ts"}' +out=$(printf '%s' "$IN" | CLAUDE_INSTRUCTIONS_LOG="$LOG" bash "$HOOK"); rc=$? +check T10-hook-rc "$rc" 0 +check T10b-stdout-empty "$out" "" +check T10c-one-line "$(wc -l < "$LOG" | tr -d ' ')" 1 +check T10d-reason-kept "$(jq -r '.load_reason' "$LOG")" path_glob_match +check T10e-ids-kept "$(jq -r '[.session_id, .agent_id, .globs[0]] | join(",")' "$LOG")" 's1,a1,src/**' +out=$(printf '%s' "$IN" | CLAUDE_INSTRUCTIONS_LOG=/proc/nowhere/il.jsonl bash "$HOOK"); rc=$? +check T10f-unwritable-log-rc0 "$rc" 0 +check T10g-unwritable-log-stdout-empty "$out" "" +# "$BASH", not bash: the blank PATH applies to the command lookup too (rc 127) +out=$(printf '%s' "$IN" \ + | CLAUDE_INSTRUCTIONS_LOG="$LOG" PATH=/nonexistent "$BASH" "$HOOK"); rc=$? +check T10h-no-jq-rc0 "$rc" 0 +check T10i-no-jq-stdout-empty "$out" "" +check T10j-no-jq-nothing-appended "$(wc -l < "$LOG" | tr -d ' ')" 1 +head -c 5300000 /dev/zero | tr '\0' 'x' > "$LOG" +printf '%s' "$IN" | CLAUDE_INSTRUCTIONS_LOG="$LOG" bash "$HOOK" +check T10k-rotated "$([ -e "$LOG.1" ] && echo yes || echo no)" yes +check T10l-fresh-log-one-line "$(wc -l < "$LOG" | tr -d ' ')" 1 + echo "PASS=$pass FAIL=$fail" [ "$fail" -eq 0 ] diff --git a/settings.json b/settings.json index f619f5e..523e214 100644 --- a/settings.json +++ b/settings.json @@ -374,6 +374,17 @@ ] } ], + "InstructionsLoaded": [ + { + "hooks": [ + { + "type": "command", + "command": "bash ~/.claude/hooks/instructions-loaded.sh", + "timeout": 5 + } + ] + } + ], "PreToolUse": [ { "matcher": "Bash",