transcript-inspector

Transcript Inspector - Stop Hook Dogfooding Diagnostics

Purpose

Diagnose stop hook failures by reading Claude Code session transcripts and cross-referencing with daemon logs. Primary use case: "Claude stopped when it should have been blocked" or "the stop hook isn't working."

How to Use This Agent

Invoke when:

• Claude stops without a STOPPING BECAUSE: prefix and the daemon did not block it
• A user had to type "go" or "continue" manually (symptom of broken stop hook)
• preventedContinuation: false appears in transcript when it should be true
• Any stop hook dogfooding regression

Step 1: Find the Current Transcript

# List all transcript files for this project, sorted by modification time (newest last)
ls -lt /root/.claude/projects/-workspace/*.jsonl 2>/dev/null | head -5

# The most recent file is the current session
TRANSCRIPT=$(ls -t /root/.claude/projects/-workspace/*.jsonl 2>/dev/null | head -1)
echo "Transcript: $TRANSCRIPT"

The project path encoding: /workspace → -workspace. If running from a different path, adjust accordingly.

Step 2: Locate stop_hook_summary Entries

These are the definitive outcome records for every stop hook invocation.

#!/usr/bin/env python3
import json
import sys

transcript = sys.argv[1]  # pass transcript path as arg

with open(transcript) as f:
    lines = f.readlines()

print(f"Total lines: {len(lines)}\n")

for i, line in enumerate(lines):
    try:
        e = json.loads(line)
    except json.JSONDecodeError:
        continue

    # Stop hook outcome record
    if e.get('subtype') == 'stop_hook_summary':
        print(f"Line {i}: stop_hook_summary")
        print(f"  preventedContinuation : {e.get('preventedContinuation')}")
        print(f"  level                 : {e.get('level')}")
        print(f"  hasOutput             : {e.get('hasOutput')}")
        print(f"  hookErrors            : {e.get('hookErrors')}")
        print(f"  raw                   : {json.dumps(e, indent=2)}")
        print()

    # Stop hook progress event (hook firing)
    if (e.get('type') == 'progress'
            and isinstance(e.get('data'), dict)
            and e['data'].get('type') == 'hook_progress'
            and e['data'].get('hookEvent') == 'Stop'):
        print(f"Line {i}: Stop hook FIRING (progress event)")
        print(f"  hookName : {e['data'].get('hookName')}")
        print(f"  toolUseID: {e.get('toolUseID')}")
        print()