# Hook Failure Audit

Audit hook delivery health from Agent Monitor data, balance PreToolUse vs PostToolUse...

- Repository: https://github.com/hoangsonww/Claude-Code-Agent-Monitor (1136 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill hook-failure-audit -g -a claude-code -y`
Codex: `npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill hook-failure-audit -g -a codex -y`
Cursor: `npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill hook-failure-audit -g -a cursor -y`
Gemini CLI: `npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill hook-failure-audit -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor`

## Description

Audit hook delivery health from Agent Monitor data, balance PreToolUse vs PostToolUse (a gap means tools that started but never reported back), detect missing Stop/SubagentStop terminators (sessions/subagents that never closed), and check for stale ingestion (no recent events). Use when hooks look unreliable or events seem to be dropping.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Hook Failure Audit

Assess whether the hook pipeline is delivering events reliably, using the event
counts and stream the dashboard already has. This is about *delivery* health
(missing/dropped events), not about why a model errored.

## Input

The user provides: **$ARGUMENTS**

This may be:
- empty or "all", run every check (default)
- "balance", PreToolUse/PostToolUse balance only
- "terminators", missing Stop/SubagentStop only
- "freshness", stale-ingestion check only

## Data Sources

| Endpoint | Returns |
|----------|---------|
| `GET /api/analytics` | `event_types` (counts per type: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd), `daily_events` (365d), `total_subagents`, `sessions_by_status`, fleet-wide delivery balance |
| `GET /api/stats` | `total_sessions`, `total_agents`, `total_events`, `events_today`, expected terminator counts and recency |
| `GET /api/events?session_id=X` | Per-session stream, confirm which sessions are missing a `PostToolUse`, `Stop`, or `SubagentStop` |

## Report Sections

### 1. PreToolUse / PostToolUse Balance
From `GET /api/analytics` `event_types`: `gap = PreToolUse − PostToolUse`. A positive gap means tools whose completion hook never arrived. Report the gap as a count and as a percentage of `PreToolUse`. A healthy pipeline keeps this near 0%.

### 2. Missing Terminators
Compare `Stop` count against completed sessions (`sessions_by_status`) and `SubagentStop` against `total_subagents`/`total_agents` (from `/api/stats`). A shortfall means sessions or subagents that ran but never emitted a closing hook, likely dropped delivery or a crashed handler. Report expected vs observed for each.

### 3. Stale Ingestion
Check `events_today` from `/api/stats` and the tail of `daily_events` from analytics. If recent days are empty while sessions exist, ingestion has stalled. Report the most recent day with events and how long ago that was.

The rest: https://github.com/hoangsonww/Claude-Code-Agent-Monitor/blob/HEAD/plugins/ccam-quality/skills/hook-failure-audit/SKILL.md