--- phase: 20.4-implement-all-retro-agent-failure-patterns-mitigations-m-1-t plan: 02 subsystem: infra tags: [claude-code-hooks, shell, git, process-hardening] # Dependency graph requires: - phase: 20.4-01 provides: M-1 parallel-sites checklist template and planner/plan-checker wiring provides: - M-2 PreToolUse soft-warning hook (sibling-search-warn.sh) registered in .claude/settings.json - M-6 PreToolUse soft-warning hook (commit-size-warn.sh) registered in .claude/settings.json - CLAUDE.md Pre-fix sibling search rule pointing to M-2 hook affects: - all future execution phases (hooks fire on every Edit/Write/.rs/.slint and git commit) - 20.4-03 onwards (further mitigations in same phase) # Tech tracking tech-stack: added: [] patterns: - "Claude Code PreToolUse hook with permissionDecision:allow for soft (non-blocking) agent reminders" - "Python -c JSON parsing in bash hooks (no jq, Windows Git-Bash compatible)" - ".claude/settings.json project-level hook registration (shareable with contributors)" - ".gitignore negation pattern to expose .claude/hooks/** and .claude/settings.json while keeping .claude/worktrees/ ignored" key-files: created: - .claude/hooks/sibling-search-warn.sh - .claude/hooks/commit-size-warn.sh - .claude/settings.json modified: - CLAUDE.md - .gitignore key-decisions: - "M-2 and M-6 hooks use permissionDecision:allow — soft reminders only, never blocking agent progress" - ".gitignore updated from '.claude/' blanket ignore to '.claude/*' + negations for hooks/** and settings.json so shareable config is tracked in git" - "Both hooks parse JSON via 'python -c' (not jq) to comply with CLAUDE.md Windows constraint" - "sibling-search-warn.sh reads transcript_path from stdin JSON (not env var) — aligned with hooks reference §Common Input Fields" patterns-established: - "Soft-warning hook pattern: read stdin JSON via python -c, pattern-match only, emit permissionDecision:allow with additionalContext, exit 0" - "Hook security: never eval tool_input content; use grep -oE for pattern extraction only (T-20.4-01 mitigated)" requirements-completed: - M-2 - M-6 # Metrics duration: 7min completed: 2026-04-16 --- # Phase 20.4 Plan 02: M-2 and M-6 Hook Scripts Summary **Two PreToolUse soft-warning hooks — sibling-search-warn.sh (M-2) and commit-size-warn.sh (M-6) — registered in .claude/settings.json, with CLAUDE.md Pre-fix sibling search rule added** ## Performance - **Duration:** 7 min - **Started:** 2026-04-16T09:22:19Z - **Completed:** 2026-04-16T09:29:47Z - **Tasks:** 2 - **Files modified:** 4 ## Accomplishments - Created M-2 hook: fires on Edit/Write of .rs/.slint files containing `fn` definitions, checks transcript for prior grep, emits soft reminder if missing - Created M-6 hook: fires on `git commit` Bash calls, checks `git diff --cached --shortstat` insertions, warns if >200 lines - Registered both hooks in .claude/settings.json with timeout:10 and permissionDecision:allow - Added Pre-fix sibling search section to CLAUDE.md between Data Architecture and Owl messaging - Updated .gitignore to track .claude/hooks/** and .claude/settings.json while keeping .claude/worktrees/ ignored ## Task Commits Each task was committed atomically: 1. **Task 1: Create hook scripts and settings.json** - `c9bdb13` (feat) 2. **Task 2: Add Pre-fix sibling search rule to CLAUDE.md** - `b3c3bde` (feat) **Plan metadata:** (docs commit below) ## Files Created/Modified - `.claude/hooks/sibling-search-warn.sh` - M-2 PreToolUse hook: warns when editing .rs/.slint function without prior grep - `.claude/hooks/commit-size-warn.sh` - M-6 PreToolUse hook: warns on git commit with >200 insertions - `.claude/settings.json` - Hook registration: PreToolUse[Edit|Write -> sibling-search, Bash -> commit-size] - `CLAUDE.md` - New "## Pre-fix sibling search" section with 3-step rule and hook/retro references - `.gitignore` - Changed `.claude/` blanket ignore to `.claude/*` + negations for hooks/ and settings.json ## Decisions Made - **.gitignore negation approach:** The original `.claude/` blanket ignore blocked all hook files. Changed to `.claude/*` with explicit negation patterns (`!.claude/hooks/`, `!.claude/hooks/**`, `!.claude/settings.json`) so shareable project-level config is version-controlled. - **transcript_path from stdin:** The M-2 hook reads `transcript_path` from the stdin JSON field (not from a `$CLAUDE_TRANSCRIPT_PATH` env var) — matching the hooks reference which lists it in §Common Input Fields as a stdin property. - **Shell: bash prefix in command:** Hook commands use `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/..."` pattern (matching research Pitfall 2 guidance for Windows Git-Bash compatibility). ## Deviations from Plan ### Auto-fixed Issues **1. [Rule 3 - Blocking] Updated .gitignore to allow .claude/hooks/ and settings.json to be tracked** - **Found during:** Task 1 (hook scripts and settings.json creation) - **Issue:** `.gitignore` had `.claude/` blanket ignore — `git add` rejected all files under `.claude/` - **Fix:** Changed `.claude/` to `.claude/*` and added three negation lines to expose hooks/ and settings.json while keeping worktrees/ hidden - **Files modified:** `.gitignore` - **Verification:** `git add .claude/hooks/sibling-search-warn.sh .claude/hooks/commit-size-warn.sh .claude/settings.json` succeeded with no errors - **Committed in:** `c9bdb13` (Task 1 commit) --- **Total deviations:** 1 auto-fixed (Rule 3 - blocking) **Impact on plan:** Necessary for plan goal — files would not be committed without this fix. No scope creep. ## Issues Encountered None beyond the .gitignore blocking issue (handled as deviation above). ## User Setup Required None — hooks activate automatically when Claude Code reads .claude/settings.json at session start. No manual configuration needed. ## Next Phase Readiness - M-2 and M-6 are active in this project session going forward - Ready for 20.4-03 (next mitigation in the phase) - Both hooks verified via dry-run: M-2 fires correctly on synthetic Edit payload with function definition --- *Phase: 20.4-implement-all-retro-agent-failure-patterns-mitigations-m-1-t* *Completed: 2026-04-16*